algal.organism.v1

The organism manifest contract. A manifest is data: it can be checked, canonicalized, hashed, and embedded. It never carries host code — the only programs it may carry are bounded, contract-owned ones (algal.expr.v1), interpreted under fuel by the contract's evaluator rather than the host language.

Manifest

{
  "contract": "algal.organism.v1",
  "key": "organism:triage",
  "name": "Ticket triage",
  "note": "optional bounded text",
  "budgets": { "maxSteps": 64, "maxAgentCalls": 4, "maxWork": 100000 },
  "interface": {
    "inputs": { "ticket": { "cell": "ticket", "port": "text" } },
    "outputs": { "summary": { "cell": "result", "port": "value" } }
  },
  "cells": [ ... ],
  "edges": [ ... ]
}

JSON manifest files and canonical SDK manifest inputs are each bounded to 1,048,576 bytes in both runtimes, including the normalized manifest with defaults. Bun counts SDK JSON bytes before allocating a canonical copy; cell and edge counts are checked before parsing their entries. CLI JSON manifests and other bounded-input paths must resolve to regular files. A symlink to a regular input is supported; a FIFO, device, or directory is rejected before read.

Cells

organism, repeat, and each cells may declare via: a transport name (a safe id) the host maps to a bundle source — a directory of <hex>.bundle.json files or an HTTP(S) base URL serving the same. When the referenced manifest is absent from the local store, the transport supplies a algal.bundle.v1 closure; unpack installs it with every claimed digest rehashed, then resolution retries locally. The cell's receipt record carries via — the transport name that served the closure. Local hits never consult transports, so via is a fallback, not a preference; a missing transport or missing bundle fails closed (STORE_MISS), and a wrong-rooted or tampered bundle fails DIGEST_MISMATCH. Trust is the digest itself: a transport can only deliver content the manifest already named — execution stays local, metered, and receipted either way.

Bundle transports admit at most 67,108,864 received bytes before parsing. File transports validate the opened descriptor as a regular file and use nonblocking admission on Unix; explicitly configured regular-file symlinks remain supported. HTTP transport is a Bun host feature: it bounds streamed decoded-body bytes even without Content-Length, cancels rejected bodies, and bounds the entire request/body lifetime (default 15 seconds, configured integer range 1–600,000 milliseconds). Native transports currently accept file directories. Both reject invalid UTF-8 and a leading BOM. These limits bound ingestion; the bundle's digest checks still establish its identity.

Port types

Every port declares one of:

A ref is a pointer, not a value: the payload never rides the edge, so it never enters receipts, agent contexts, or request digests — only the token does. recall, store, load, slot, and spawn cells are the cells whose ports are fixed by the contract. A ref token admitted through input args or a const port must already resolve in the store — the caller mints tokens by writing the payload first; no cell can invent a dangling pointer.

A cap is authority, not payload. It feeds only a cap port declaring the same class — never json, even though handles serialize as strings. const cells cannot produce capabilities; roots receive them through host-supplied input args, trusted host functions/tools may return them, and organism interfaces may delegate them without widening their class. The handle is an opaque local identifier, not a provider credential: the host must still hold an active admission record and may revoke it independently.

JSON-shaped dynamic composition cannot introduce a capability-typed edge: spawn rejects capability ports on its child interface, and each.over cannot name a capability input. Use typed organism delegation, or a typed pass-through input on each. Capability and ref lists cannot feed scalar ports.

agent / classifier / gate fields

{
  "id": "route",
  "kind": "classifier",
  "inputs": { "ticket": "text" },
  "prompt": "Classify the ticket.",
  "view": { "inputs": "*", "note": "optional", "cells": ["prep"] },
  "output": { "kind": "choice", "labels": ["bug", "feature"], "onMiss": "bug" },
  "route": { "provider": "…", "model": "…", "preset": "…" },
  "tools": ["pick.v1"],
  "shadow": { "take": "bug" },
  "retry": { "attempts": 3 },
  "budget": {
    "maxContextBytes": 65536,
    "maxOutputBytes": 4096,
    "maxTurns": 8,
    "maxEffectMs": 30000
  }
}

decide cells

{
  "id": "probe",
  "kind": "decide",
  "inputs": { "proposal": "json" },
  "prompt": "optional framing for the provider",
  "questions": {
    "keep": { "type": "noul", "instructions": "Is this proposal still relevant?" },
    "lane": {
      "type": "choice",
      "instructions": "Pick the closest lane.",
      "criteria": { "bug": null, "feature": null, "chore": null }
    },
    "risk": { "type": "score", "instructions": "Rate breakage risk." }
  },
  "view": { "inputs": "*" },
  "route": { "provider": "jev" },
  "budget": { "maxContextBytes": 65536 },
  "retry": { "attempts": 2 }
}

A decide cell declares a bounded question map (≤ 64 names, each noul/choice/score with instructions ≤ 4096 bytes and optional criteria). It declares no output contract — the contract is derived from the question map, an {"answers": {<name>: <answer-by-type>}} record:

The cell activates like an agent with one turn and no tools: the effect request carries questions alongside context, and a decision provider answers them — typed decisions, never generated text. The provider must return exactly the declared answers: a missing, extra, or malformed answer fails the output contract like any other violation. A decide request routes to decision executors (route.provider/preset); a model executor that only generates text must reject it, and a decision executor must reject agent and gate requests — approval stays human/policy-routed. classifier cells are the model-served single-choice equivalent: a decision provider serves them by synthesizing one choice question from the declared labels.

budget.maxTurns is fixed at 1 for decide; other budget fields, view, route, and retry behave as on agent cells.

recall cells

{
  "id": "memory",
  "kind": "recall",
  "inputs": { "topic": "text" },
  "query": {
    "contract": "algal.expr.v1",
    "program": ["sconcat", ["get", "topic"], " failure recovery"]
  },
  "k": 8,
  "embedder": "local",
  "route": { "provider": "recall" },
  "rerank": { "route": { "provider": "jev" }, "take": 4 },
  "budget": { "maxContextBytes": 65536, "maxOutputBytes": 65536 },
  "retry": { "attempts": 2 }
}

A recall cell evaluates query.program against its delivered inputs under ordinary expression fuel. Static checking admits only declared input names. The result must be non-empty text of at most 4096 UTF-8 bytes. k defaults to 8 and is bounded to 1–32. embedder defaults to local and may be local, gateway, or gateway:<model>; it names the vector space the host recall executor must query. route, retry, maxContextBytes, maxOutputBytes, and maxEffectMs have their ordinary effect meanings; maxTurns is not accepted.

rerank is optional and must declare an independent route containing provider or preset; this keeps semantic-index access and model decisions under separate host authority. take optionally truncates the reranked result to 1–k hits and otherwise all hits remain. When the index returns at least two hits, the runtime issues a second, ordinary kind:"decide" effect with one noul relevance question per hit over context:{query,hits}. Hits sort by answer descending with original rank as the deterministic tie-break. The runtime never rewrites a hit: retained records are byte-for-byte source values, only reordered and optionally truncated. Zero- and one-hit results need no rerank effect.

The resulting kind:"recall" request carries recall:{query,k,embedder}. A provider returns exactly one hits list with at most k records in ranked order. Each record is {id,source,seq,score,text,ref?}: id is the chunk digest, score is finite, text is capped at 2048 UTF-8 bytes, and ref—when present—must be the exact sha256: token named by its value: source. Unknown fields and malformed records fail EFFECT_UNPARSEABLE.

The full {hits:[…]} record commits on out. If the first ranked hit has a ref, the same token also commits on ref; otherwise that port is absent and its downstream edge dies. Thus recall.ref → load.ref resolves full CAS payloads. With rerank, out and ref reflect the decision-ranked result; without it, they reflect index order. An empty hit list is a successful result whose ref consumers skip. A rerank call counts independently against maxAgentCalls and work, uses the cell's retry/effect bounds, and records every relevance score in the effect receipt so replay reconstructs the same order.

The semantic index is host-owned, derived, and mutable—not manifest or receipt data. A live run records the returned hits as an ordinary effect, and replay serves that exact response without reopening the index. Index-backed recall executors are not cross-run memoized: an identical query may legitimately see a newer derived index. The receipt proves which request received which hits; it does not attest the index's current contents.

expr cells

{
  "id": "rate",
  "kind": "expr",
  "inputs": { "ticket": "json", "base": "json" },
  "expr": {
    "contract": "algal.expr.v1",
    "program": [
      "let", "amt", ["get", "ticket", "amount"],
      ["if", ["gt", ["mul", ["get", "amt"], ["get", "base"]], 1000],
        "high", "std"]
    ]
  },
  "output": { "kind": "choice", "labels": ["high", "std"] }
}

Where fn cells compose functions the host registry owns, expr cells carry the program itself — a bounded pure algal.expr.v1 program (spec/v1/expr.md) evaluated against the delivered inputs. The result commits to the single port out under the output contract (same shape as agent output; onMiss is rejected — a program returns exact values). Static checking at parse covers op names, arity, bounds, and literal get names against the declared input ports. Activation burns 100 + fuel work units (budgets-bounded; the per-activation fuel ceiling is BOUNDS.maxExprFuel) and produces an ordinary cell commit — no effect request, no executor — so verification replays the program by re-evaluation.

repeat cells

{
  "id": "loop",
  "kind": "repeat",
  "manifest": "sha256:…",
  "maxRounds": 4,
  "carry": { "draft": "draft" },
  "until": { "output": "verdict", "equals": "ship" }
}

store / load cells

{ "id": "pin", "kind": "store" }
{ "id": "get", "kind": "load" }

slot cells

{ "id": "mem", "kind": "slot", "name": "count", "mode": "read", "default": 0 }
{ "id": "sink", "kind": "slot", "name": "count", "mode": "write" }

Capability mailboxes and wakeups

Mailboxes are host standard-library tools over the generic tool cell — not a new cell kind:

{ "id":"in", "kind":"input",
  "outputs":{"inbox":{"type":"cap","capability":"mailbox-receive"}} }
{ "id":"wait", "kind":"tool", "tool":"mailbox.receive.v1" }

The host admits two typed drivers:

algal mailbox create <name> admits a mailbox and prints independent send and receive handles plus its bounds. Pending count is 1–1024 (default 64); canonical message bytes are 1–250,000 (default 65,536). mailbox revoke disables one handle without changing the other. Capability records, immutable message claims, and pending/consumed delivery markers live under the host's --dir; bundles and manifests never contain those admissions.

An empty receive throws EFFECT_SUSPENDED. The tool attempt records retryable:false, the cell/run suspend normally, and the algal mailbox send command supplies an external wakeup from a send cap and JSON value. A caller may pass --idempotency-key sha256:… to make retries the same delivery; without it each invocation mints a fresh delivery key. The algal resume command filters the suspended dequeue attempt, replays any completed prefix tool effects, and reissues that exact receive request live. Its successful effect receipt records the delivered message id and value. verify serves that receipt and never opens or consumes the live mailbox. Immutable message claims and consumed markers are retained as host recovery evidence; mailbox storage accounting and garbage collection remain host lifecycle responsibilities.

spawn cells

{ "id": "run", "kind": "spawn" }

each cells

{
  "id": "map",
  "kind": "each",
  "manifest": "sha256:…",
  "over": "q",
  "maxItems": 8
}

Edges

{ "from": { "cell": "route", "port": "out" },
  "to": { "cell": "as-bug", "port": "tag" },
  "guard": { "equals": "bug" } }

Compilation admission bounds

Before execution, both runtimes bound the complete expanded static compilation: 1,024 manifest instances, 4,096 cells, 16,384 edges, and 67,108,864 cumulative canonical UTF-8 manifest bytes. The root and every organism, repeat, or each child occurrence count, including repeated references to the same digest. The maximum static embedding depth remains 64 (root depth zero).

One compilation shares these counters across its entire recursive traversal. Admission fails with BUDGET_EXHAUSTED before allocating the next compiled instance's maps or resolving its children; excessive depth is DEPTH_EXCEEDED. The byte budget counts normalized manifest JSON, including defaults. These host admission ceilings prevent compact shared DAGs from causing unbounded expansion before runtime budgets take effect. They add no manifest or receipt fields and do not change execution or receipts for programs within the ceilings. Dynamic compilations start a fresh admission budget and still consume their run's normal step, depth and work limits.

Run semantics

Work ledger

Expression guards run once in manifest edge order after every incoming producer has resolved. A guard error ends the run with GUARD_INVALID, preserves the committed prefix, and names the receiving cell in the run failure; that cell has not activated. Guard fuel counts toward maxWork even when the edge is false, and exhaustion is checked before another guard or activation executes.

Modeled units, not wall time: 100 per activation, plus the fn signature's cost, plus 500 + context bytes + output bytes per effect. Bounded by budgets.maxWork; maxSteps bounds activations, maxAgentCalls bounds effects, maxContextBytes/maxOutputBytes bound each effect's I/O. Each cell record carries the work attributed to it — for organism, repeat, and each cells that is the whole subtree's units, while inner cells keep their own records.

A cell that fails still spends work. A declared on:"fail" edge handles its failure but does not replenish maxWork; exhaustion is checked before another recovery cell can activate. The failed activation and its charged units remain in the receipt in both runtimes.

Effects

An agent/classifier/gate/decide/recall activation produces an effect request:

{ "contract": "algal.effect.v1", "cellId": "route", "kind": "classifier",
  "prompt": "…", "context": {"inputs": {…}}, "output": {…},
  "budget": {…}, "route": {…}, "questions": {…}, "recall": {…} }

A host tool call uses algal.tool-effect.v1 instead: {contract,path,tool,effect,inputs}. Its canonical digest is the idempotency key passed to the driver, and its output/error is stored in the same ordered run effects list under executor:"tool:<name>". Strict verification serves that record; resume may replay a completed tool prefix and route only a missing or suspended tool request live.

questions is present on decide requests only — the declared question map the provider must answer. Internal compaction and recall-rerank requests carry it too; kind stays decide while cellId names the owning agent or recall cell. recall is present on kind:"recall" requests only and binds the evaluated query, hit cap, and embedder spec.

sha256 over the canonical request is the binding between request and receipt. The executor sees exactly these bytes; nothing else crosses the boundary. Executor output is bound to the declared output contract before it can feed edges. A miss on a choice output resolves to onMiss or fails the run.

Executors

Executors are host-supplied; the manifest is data and cannot name host code. Every executor declares capabilities.effects — the effect kinds it is admitted to serve. Undeclared executors default to agent/classifier only: a legacy adapter never silently gains approval, decision, or index authority.

Selection is capability-aware in both directions:

The built-in matrix: model executors serve agent/classifier; decision executors serve classifier/decide; index executors serve recall; gate approval requires an executor the host explicitly admitted for gate; command executors are host-written adapters admitted for every kind; scripted fixtures serve every kind and wildcard routes.

A replay executor is not a route: verification resolves recorded effects by request digest before capability selection, so offline replay never depends on which executors the host currently admits. An executor may also declare serves(request) — a request-aware admission checked before capability routing. The replay executor uses it to serve exactly the request digests its receipt list holds; on a miss the request falls through to ordinary live routing, which is what makes resume able to replay a recorded prefix and execute the tail live in one pass.

Receipts — algal.run.v1

A receipt records manifestDigest, args, outcome, per-cell records (committed | skipped | failed | suspended, outputs, failure detail, effectDigest, toolCalls, shadowOut, rounds, items, per-cell work), the effects list (requestDigest, then output or error — a failed effect records {code, message} so replay reproduces it — executor id, optional usage, cached when the response was served from a prior run's record rather than executed, retryable:false when re-issue is forbidden, and configurationDigest for the admitted backend configuration), the bounded events log, the work ledger, and run-level failure detail. digest is over the canonical receipt minus itself.

Verification

verify(receipt, manifest) replays the run with a replay executor that serves recorded effect outputs by request digest — in record order when a digest repeats under retry — then compares cells, effects, work, and outcome. Any divergence is reported by name. The check is offline and deterministic: receipts fix what the world returned.

Suspension and resume

An executor or host tool may decline a request with EFFECT_SUSPENDED — the answer is not ready (a gate awaiting a decision, a delegated task still pending, or an empty mailbox). Suspension is not failure and not an answer:

The bounded named supervisor, dispatch intents, mailbox wake scheduling, and cross-runtime filesystem ABI are specified in algal.process.v1. A recorded suspension is resumable; an interrupted dispatch with uncertain external completion must be reconciled before any retry.

Effect memoization

The store keeps an effect index keyed by request digest — a memo table, not CAS: the first recorded successful receipt wins and cannot be overwritten. An executor wrapped in cachedExecutor(inner, store) consults the index before calling inner; a hit returns the recorded output and the new run's receipt records it with cached: true, so "this response came from a prior run" stays a fact of the record. Errors are never memoized — a recorded failure may be transient and must not determinize into permanence. A memoized effect still occupies its budgeted slot (agent calls, context and output bytes), still binds to the declared output contract, and still replays bit-for-bit: replay reproduces the cached flag from the record. Derived-index recall executors opt out of this memo table because the same query may observe newly indexed sources; their per-run effect receipt remains replayable.

Bundles — algal.bundle.v1

A bundle is a portable closure: {"contract","root","manifests","values"}. pack walks the root manifest's embedding graph (organism/repeat/each cells) and every payload named by a const ref port, collecting each into a digest-keyed map. unpack installs the closure into a store — every entry re-hashes against its claimed key (DIGEST_MISMATCH on tamper) and the root must be among the manifests. A bundle is data with no host code: the unpacked organism runs exactly as if its modules had been loaded individually.

Reserved, not implemented

Schema-validation compatibility

Bun now enforces the same recursive type, required, and properties subset as the native runtime. Previously, Bun accepted some outputs with a wrong root type or missing/incorrect nested fields. It also rejected valid primitive or integer JSON outputs that native accepted. The correction does not turn unsupported provider hints into runtime constraints.

This changes replay for receipts affected by those bugs: an invalid output formerly accepted may now fail verification, and a formerly rejected valid output may replay as success. Preserve the original receipt and its matching runtime when analyzing historical execution; do not rewrite retained evidence to make it pass. Schema failure messages and property-validation order now match native too, so newly created successful and failed receipts can replay across both runtimes. Older Bun schema-failure receipts may therefore require the original runtime even when their rejection was valid. Native failures with multiple invalid properties may also need their original runtime and source key order; native now checks properties in a deterministic order. This correction does not relax exact replay or ignore diagnostic differences.

Strict schema admission also corrects malformed declarations that older versions silently ignored or interpreted as default object schemas. Existing valid schemas retain their data and execution semantics; unsupported keywords remain hints. Preserve VM.7 or the original matching runtime alongside historical receipts containing malformed declarations. The current parser intentionally rejects those manifests rather than spending an effect or weakening replay.