New to Hara · 8 min
Evaluate the first form
Open an isolated browser session and inspect the result and capability boundary.
Open path →Guides · Reference · Examples
Hara documentation is organised by the kind of answer required.
A guide explains a task in sequence. A reference page defines a language form, namespace, symbol, or interface. An executable example adds a named runtime session to otherwise static source and explanation.
- Guide contract
- 2.1.0
- Version range
- >=1.8 <2.0
- Exact revision
sha256:72a194a3- Runtime example
- runtime-example:docs-work-01
01 · Task index
Start with the task or question you need to resolve.
Each path names its expected reading time, assumed background, version range, and likely runtime. The language and API hierarchy remains available in the reference.
Application · 20 min
Create a portable project
Add namespaces, dependencies, tests, and an explicit target runtime.
Open path →Systems · 30 min
Build a durable work pipeline
Separate replayable work from checkpointed effects and record receipts.
Open path →Interop · 25 min
Call a native interface
Resolve host values, lifecycle, errors, and ownership through a narrow ABI.
Open path →Distribution · 18 min
Publish a package
Register namespace ownership, compatibility, artifact digest, and release notes.
Open path →Tooling · 12 min
Inspect compiler and lint facts
Move from source form to generated output without losing source locations.
Open path →02 · Guide document
Navigation records location; prose explains the task.
The document uses a quiet guide rail, stable outline, version and runtime selectors, and one optional executable example. The article remains readable without the runtime.
Guide · docs.guide
Build a durable work pipeline
Keep deterministic orchestration separate from checkpointed effects while the runtime records exact boundaries.
- Applies to
- >=1.8 <2.0
- Reading time
- 18 minutes
- Published revision
sha256:72a194a3
Work describes what should happen. The executor chooses how it runs. The store remembers completed boundaries. This separation keeps orchestration replayable without pretending that network, database, clock, or filesystem effects can be repeated invisibly.
Model the work
Start with a small algebra. Pure nodes may replay; step nodes checkpoint external observations; chain and branch nodes only compose work.
Static exampleCopyable without runtime
{:op :chain
:id :document/import
:work [{:op :pure :id :resolve-input}
{:op :step :id :fetch-source :capabilities [:network]}
{:op :step :id :store-original :capabilities [:database]}]}Checkpoint effects
A step boundary records input identity, fenced generation, output digest, declared capabilities, and a durable receipt. A replay reads the recorded output rather than quietly reissuing the effect.
Executable example · optional runtime surface
durable-import.hal
- Runtime
- Wasm · work.ephemeral
- Session
- docs-work-01
- Generation
- 4
- Revision
hara@9b6c10e + example@72a194a3
purenetworkdatabaseclock:nonefilesystem:none
;; orchestration is replayable
(def durable-import
(work/chain
(work/pure :resolve-input resolve-input)
(work/step :fetch-source fetch-source [:network])
(work/step :store-original store-original [:database])
(work/pure :index-document index-document)))
(work/submit executor store durable-import)The runtime is attached. Running creates a new fenced execution receipt.
Result
{:work/id :durable-import
:status :complete
:steps 2
:receipts ["fetch-source:g4" "store-original:g4"]} Ready to run.
Attach a runtime
The guide selector changes explanatory compatibility context. It does not mutate the source revision. An executable surface must explicitly attach a compatible provider before Run becomes available.
Inspect the receipt
Completion evidence links work identity, source revision, executor, store, capability declaration, step outputs, and the final accepted result. The receipt belongs to the runtime registry, not editable front matter.
03 · API and namespace reference
Each symbol record names its namespace, signature, version, and definition.
Reference rows are canonical records rather than headings copied into prose. A production implementation resolves them from the symbol registry.
Namespace
std.work
Algebra, submission, checkpoint boundaries, stores, and executors.
SymbolSignatureSinceDefinition
std.work/work-specprotocol method (work-spec [work]) 1.8.0 Return the canonical algebraic representation of a work value.
std.work/submitfunction (submit executor store work) 1.8.0 Submit work through explicit executor and store interfaces.
std.work/stepconstructor (step id f & capabilities) 1.8.0 Declare a checkpointed effect boundary with named capabilities.
std.work/chainconstructor (chain & work) 1.8.0 Compose work without forcing an execution strategy.
04 · Search results and filters
Search distinguishes guides, reference, version notes, and executable examples.
Type, category, version, and runtime are visible filters. A result does not imply that a static guide is executable or that a live example applies to every runtime.
GuideSystems
Build a durable work pipeline
Replayable work, checkpointed steps, stores, executors, and receipts.
ReferenceAPI
std.work/work-spec
Canonical algebraic representation for work values.
Version noteMigration
Migrating work.* to the narrow executor/store ABI
Runtime maps become host configuration rather than a public protocol.
Live exampleTutorial
Checkpoint an HTTP effect
Fence network access and replay from the recorded result.
05 · Runtime, compile, and version states
An unavailable executable example does not erase its documentation.
Each state names what remains readable, which action is disabled, and which immutable source and runtime context can still be inspected.
Unavailable runtime
Wasm backend could not attach
The article remains readable. Running is disabled and the exact source stays copyable.
- Backend: wasm-core
- Fallback: static source
- Retry preserves revision
Compile error
Capability declaration is missing
The error names the source range and required capability instead of replacing the article with an editor.
- work.hal:8:13
- Required: :network
- Session generation: 4
Stale version
Example targets Hara 1.8; selector is on 1.9-next
Readers can pin the documented version, inspect the migration note, or open the exact revision.
- Documented: 1.8.0
- Selected: 1.9-next
- Revision remains immutable
Compile error specimen
missing-capability.hal
- Runtime
- Wasm · isolated
- Session
- docs-01
- Generation
- 4
- Revision
example@72a194a3
pureclock:nonenetwork:nonefilesystem:none
;; orchestration is replayable
(def durable-import
(work/chain
(work/pure :resolve-input resolve-input)
(work/step :fetch-source fetch-source [:network])
(work/step :store-original store-original [:database])
(work/pure :index-document index-document)))
(work/submit executor store durable-import)Capability :network is required at work.hal:8:13. Source and revision remain inspectable.
Result
3 Capability :network is required at work.hal:8:13. Source and revision remain inspectable.
Stale version specimen
migration-needed.hal
- Runtime
- Wasm · isolated
- Session
- docs-01
- Generation
- 4
- Revision
example@72a194a3
pureclock:nonenetwork:nonefilesystem:none
;; orchestration is replayable
(def durable-import
(work/chain
(work/pure :resolve-input resolve-input)
(work/step :fetch-source fetch-source [:network])
(work/step :store-original store-original [:database])
(work/pure :index-document index-document)))
(work/submit executor store durable-import)This example targets Hara 1.8. Pin the documented runtime or inspect the migration note.
Result
3 This example targets Hara 1.8. Pin the documented runtime or inspect the migration note.
06 · Narrow and mobile reading behaviour
The article remains a document at every viewport.
The outline folds first, the guide rail becomes a labelled drawer, selectors remain available, and the optional control pane moves below source rather than squeezing prose.
07 · Shared content contract
Docs consumes hara.docs; it does not define a local front-matter dialect.
Guides, references, versions, and executable examples with runtime-aware evidence.
docs.guide@2.1.0Task-oriented path with audience, versions, and optional runnable examples.
docs.reference@2.1.0Canonical API or language reference driven by registered symbols.
docs.version@2.1.0Version-scoped behaviour and migration guidance.
docs.live-example@2.1.0Runnable documentation with fenced runtime expectations.