On this page ↓

Reality map

Implementation status and evidence ledger

A source-audited maturity ledger for every Shoal subsystem, host surface, security boundary, platform promise, and historical design claim.

Status
Reconciled against the hardened branch: 2026-07-17
For
Maintainers, reviewers, and release owners
On this page
  1. Status vocabulary
  2. Evidence hierarchy
  3. Executive dashboard
  4. Host-surface parity
  5. Crate-by-crate maturity ledger
  6. Language implementation matrix
    1. Syntax and dispatch
    2. Values and methods
    3. Namespaces and commands
  7. Execution and concurrency matrix
  8. Security and authority status
    1. Authentication and session identity
    2. Effects, policy, and enforcement
  9. Protocol and agent surface status
    1. Kernel router
    2. MCP facade
    3. Refs and elision
  10. Configuration status
  11. Prompt, editor, and LSP status
  12. Reef and adapter status
    1. Reef
    2. Adapters
  13. Persistence status
  14. Platform matrix
  15. Quality and test evidence
    1. Current evidence
    2. Known quality gaps
  16. Historical-document reconciliation
    1. Historical wave disposition
  17. Release claim checklist
  18. Highest-impact open findings
  19. Audit maintenance protocol

This page answers one deliberately narrow question: what is real in the current tree, through which host, and with what evidence? It is not a release announcement and it is not a substitute for executable tests. It reconciles historical design documents with the source so that an old “done” label cannot quietly become an architecture guarantee.

Read the system map first for ownership, the change map before editing a boundary, and the roadmap for ordered future work. The status vocabulary below is the same vocabulary future audits should use.

Status vocabulary🔗

LabelMeaningRequired evidence
ImplementedThe behavior is reachable through at least one real composition root.Runtime source plus a focused or integration test.
Implemented, host-limitedThe behavior works, but not through every surface implied by broad product prose.Host matrix names the supported and missing routes.
PartialA useful path exists, but an important semantic, authority, lifecycle, or portability requirement is absent.The missing requirement is stated explicitly.
ScaffoldedTypes, config, protocol, or a leaf implementation exist without an end-to-end caller.The last real caller and missing edge are named.
AspirationalThe idea exists only in design prose or an intentionally deferred contract.No current user-facing claim is made.
DriftedTwo executable or serialized descriptions disagree.Both sides and the intended authority are named.

“Implemented” never means “finished forever.” It means the audited claim is reachable and tested at the stated scope. A unit-tested leaf with no host caller remains scaffolded. A UI that returns an honest unavailable error is a correctly implemented error boundary around an incomplete feature.

Evidence hierarchy🔗

The audit uses this order when sources disagree:

  1. public types and reachable runtime branches;
  2. integration tests and the normative language corpus;
  3. focused unit tests;
  4. generated schemas and protocol fixtures;
  5. current internal documentation;
  6. historical root documents, comments, wiki prose, and remembered demonstrations.

The reconciliation inspected the workspace manifests, all composition roots, the 78 conformance suites, the kernel router and handlers, MCP mappings, configuration consumers, Reef resolution, prompt producers, journal schema, and CI definitions. It does not certify every OS backend on every kernel version, every third-party adapter executable, or performance targets on release hardware.

Executive dashboard🔗

AreaStatusStrongest current evidenceMaterial qualification
lexical grammar and parserImplementedparser tests, format round trips, conformance corpushost parse context differs for some statement heads
AST and source spansImplementedtyped AST, parser fixtures, wire span testsoptional outcome spans survive normal and elided wire paths; producers may honestly omit them
evaluator and structured valuesImplementedevaluator tests and 1,374 corpus casesdynamic/opaque values retain tag-level rather than static element schemas
builtins and namespacesImplementedcanonical command precedence plus corpusnamespaces are not first-class callable values
process captureImplementedreal process-group and dual-pipe testshash preflight has an exec-time TOCTOU window
interactive PTY executionImplemented, host-limitedUnix PTY integration and REPL testsWindows/ConPTY is deferred; kernel PTYs are poll-based
streams and channelsImplemented, host-limitedevaluator stream/feed tests and live kernel bridgelocal process stdin and bounded wire cursor pulls are available; reconnect replay remains client-driven
effects and plansImplemented with enforcement limitsstatic derivation, policy tests, plan/apply handlersplanning cannot describe every native-program effect; network allowlists are semantic-only
Leash OS sandboxImplemented, host-limitedLinux/macOS backend tests, live TCP-denial test, and enforcement reportingcoarse network denial requires Landlock ABI 4+ or Seatbelt; hostname/port allowlists are unavailable
task lifecycleImplemented, execution-form limitedevaluator jobs and kernel process-control testspure evaluator tasks have no independently suspendable OS owner
modules and script runnersImplemented, host-limitedmodule/corpus tests and .shl executionnon-.shl bare path heads require explicit run
Reef environmentsImplementedresolver/provider/lock/view tests, strict discovery tests, bounded provider runners, and live sandbox integrationmetadata-to-open/hash-to-exec races and platform portability remain
adaptersImplementedschema fixtures, bundled catalog, evaluator bindingsexternal tools and output dialects remain inherently environment-dependent
configurationImplemented, host-limitedtyped loader tests and shared host-bootstrap integrationhost-specific editor/history/prompt consumers remain intentionally local
promptImplemented, host-limitedpure renderer snapshots and authenticated host producersoptional battery/custom segments depend on host capability and configuration
journal and CASImplementedSQLite/CAS/undo/GC/lease testslive spill ownership is automatic; migrated parent links and archival remain limited
kernel JSON-RPCImplemented with boundedness limitsrouter/handler tests and daemon testsraw/blob pages are bounded; most live objects are restart-ephemeral
MCP facadeImplementedlive-kernel multiplexing and lifecycle integrationone connection/worker per facade; reconnect cursor replay remains client-driven
LSPPartialprotocol tests and shared builtin namesdeclarations/completion remain mostly lexical, not evaluator-semantic
secretsImplemented, host-limitedsecret value redaction and port testsstorage backend and host coverage are narrow by design
WASMImplemented, preview ABIevaluator invocation and Wasmtime limit/deadline/admission testscompilation is byte-bounded and limited to two process-wide jobs with bounded admission wait, but an admitted compile is not interruptible; ABI surface is intentionally narrow
WindowsAspirationalexplicit deferred branchesUnix sockets, job control, PTY, sandbox, and path rules need a separate port

Host-surface parity🔗

The same syntax crate does not imply the same runtime environment. “Local” below means the interactive shoal REPL or shoal -c; “kernel” means direct newline-delimited JSON-RPC; “MCP” means the stdio facade; “LSP” is editor analysis only.

CapabilityLocal shell.shl / -cKernelMCPLSP
parse full languageyesyesyesvia toolyes
binding-aware statement-head parseyesevaluator-dependentyesinherits kernel execno
evaluate structured valuesyesyesyesshoal_execno
persistent evaluator variablesREPL lifetimeprocess lifetimenamed-session lifetimenamed-session lifetimeno
layered core configyesyesyesinherits kernelno
init scriptsyesnotrusted private-human REPL onlynono
rich promptyesn/anonono
bundled/configured adaptersyesyesyesinherits kernelnames only
user/project Reefyesyesyesinherits kernelno
journal per statementyesyesyesinherits kernelno
coarse exec journal rownonoyesinherits kernelno
effect planningyesyesyestool/resourceno
approval workflowlocal policy pathlocal policy pathstored plan + applytoolsno
long-lived PTY refforeground job modellimitedyesresource/tool surfaceno
live event subscriptionlanguage channellanguage channelyesyesno
completionReedlinen/acontext-free endpointtool routeprotocol completion
diagnostics with spansterminalterminalstructured RPCstructured tool errordiagnostics

The former composition gap is closed by shoal-host::SessionBootstrap: local and kernel evaluators share config snapshots, aliases/environment, adapters, plugins, and Reef inputs. Surface-owned behavior remains deliberately different: only an interactive profile runs init; the CLI owns the prompt/editor/history UI, while the durable kernel owns authenticated attachments, refs, PTYs, and its coarse execution journal.

flowchart TB
accTitle: Host-surface parity
accDescr: Shows the components and relationships described in Host-surface parity.
  Core["AST + syntax + evaluator"] --> Shared["SessionBootstrap"]
  Shared --> Local["local evaluator"]
  Shared --> Kernel["principal-private kernel Session"]
  Local --> LC["prompt + editor + line history"]
  Kernel --> KC["attachments + refs + PTYs + wire events"]
  MCP["MCP"] --> Kernel
  Local --> Common["config + init + adapters + plugins + Reef"]
  Kernel --> Common

Crate-by-crate maturity ledger🔗

The “proof surface” column names the kind of executable evidence, not an immutable test count. Test counts should be generated by CI rather than copied into prose.

CrateResponsibilityStatusProof surfaceKnown boundary
shoal-astsource spans and syntax-independent ASTImplementedsyntax and formatter tests consume itserialized AST changes require wire version review
shoal-syntaxlexing, two-mode parsing, formatting, builtin identityImplementedunit/integration tests and corpus parsingsession exec is binding-aware; public parse/LSP remain context-free
shoal-valuevalues, rendering, methods, streams, capability portsImplementedmethod/value/stream tests and corpusshared task/stream/env state has explicit poison containment; host resources remain process-local
shoal-evalscopes, calls, commands, builtins, effects, modules, ReefImplementedlargest corpus and integration surfacechild creation, command-source precedence, and function annotation enforcement are unified
shoal-execcapture, process groups, cancellation, PTY, sandbox launchImplemented on Unixreal subprocess and PTY testsConPTY/Windows absent; pin check remains pre-exec
shoal-leasheffects, plans, policy, enforcement reporting/backendsImplemented, platform-limitedpolicy unit tests, backend integration, and live TCP denialcoarse denial needs Landlock ABI 4+ or Seatbelt; destination allowlists unavailable
shoal-journalentry lifecycle, CAS, undo, pins, GC, transcript payloadsImplementedschema migration, kind/parent, CAS, undo, GC testsstatement ordinal and archival/export remain absent
shoal-reefmanifests, constraints, providers, locks, views, runnersImplementedprovider/resolver/temp-tree and strict discovery testsinteractive discovery is deliberately best-effort; strict execution refuses retained warnings
shoal-adaptersdeclarative command schemas and structured parsersImplementedfixture and bundled-spec loading testscorrectness depends on third-party output versions
shoal-configtyped config discovery, merge, env overrides, validationImplementedloader/validation testsrich prompt and Reef retain subsystem-owned schemas
shoal-promptpure prompt model, style, module renderingImplementedsnapshots and renderer benchmarkoptional producer data is host-owned and cached outside rendering
shoal-secretredacted secret value and storage abstractionImplemented, narrowfocused value/store testsnot every execution path is capability-injected
shoal-pickerstructured interactive selectionImplemented locallyevaluator/terminal teststerminal-only and not an agent protocol
shoal-protoJSON-RPC shapes, refs, wire values, numeric errorsImplementedserialization testscompatibility is preview-only and unversioned beyond AST/security fields
shoal-authtoken persistence and validationImplemented, host-limitedmultiprocess store tests, live admin RPC tests, and per-request revalidationmost cap labels are descriptive; exact plan.approve and token.admin checks are handler authority
shoal-kernelsessions, RPC, refs, plans, tasks, PTYs, eventsImplemented with hardening debtunit, daemon, restart, and live MCP testsmemory-only live state, coarse/fine rows, compressed-range CPU cost
shoal-mcpMCP tools/resources over kernel socketImplementedunit and live-kernel multiplex/lifecycle testsdisconnected subscription hubs require client resubscribe/reconciliation
shoal-lspeditor diagnostics, completion, symbolsPartialprotocol/unit testslexical index cannot model evaluator/module scope fully
shoal-historyjournal inspection CLIImplementedtargeted lookup/config-root tests through journal APIexplicit durable-kernel roots still require --state-dir
shoal-doctorinstallation and environment diagnosticsImplemented, platform-limitedfocused checksUnix socket check is explicitly unsupported elsewhere
shoallocal CLI, REPL, prompt producer, composition rootImplementedCLI/config/interactive testsinteractive UI remains host-owned; default REPL uses a private kernel
shoal-wasmWasmtime component runtime and ABI v1Implemented, narrowruntime/evaluator integration and adversarial limit testshost ABI exposes only declared time/read capabilities and command invocation

Language implementation matrix🔗

Syntax and dispatch🔗

ContractStatusEvidenceQualification
CMD/EXPR two-mode grammarImplementedparser plus corpuscontextual bindings matter at statement head
byte spansImplementedtokens, AST, errorsexternal protocols may convert to UTF-16 or drop them
comments, strings, interpolationImplementedparser/formatter/corpusformatter is the canonical re-emission path
pipelines and redirectionImplementedAST/evaluator/corpusvalues stay structured only on Shoal-aware edges
match and patternsImplementedevaluator/corpuspattern expansion belongs to eval, not parser
functions and closuresImplementedcall tests plus function-type conformance matrixannotations are runtime-checked, not statically inferred
modules and exportsImplementedmodule integration testsmodule cache is evaluator-local and has no hot invalidation
interpreter blocksImplementeddynamic parser-context and real adapter-lowering testsshipped default names have generated parity; custom names require the host parse context
formatter round tripImplementedsyntax testssemantic comments/trivia behavior remains part of the contract

The canonical behavioral inventory is the language conformance contract. The reconciled tree contains 1,364 cases across 79 suites. An exact-toolchain run on 2026-07-18 observed 1,360 passed, 0 failed, 4 skipped. Skips are host-dependent and are not proof of the skipped behavior. The prior 2026-07-16 snapshot remains preserved in explicitly dated audit/reference pages.

Values and methods🔗

Value familyConstruction/evaluationmethods/renderwireImportant caveat
null/bool/int/floatyesyesinlinebool .str/.display are executable and receiver-advertised
string/bytesyesyesbounded/elidedtext and bytes must not be conflated at OS boundaries
pathyesyeslossless path formnon-UTF-8 preservation must survive every new conversion
list/record/table/rangeyesyesrecursive with budgetlist/table/range integer .get and record string .get are executable and advertised
duration/datetime/sizeyesyestyped variantsDateTime wire strings are RFC 3339 via jiff::Timestamp display
outcome/erroryesyesrefs/elisionoptional outcome spans are preserved; reconstructed/builtin values can have no anchor
stream/channelyesyeslabel/ref onlyno wire pull protocol for stream items
task/plan/secretyesyesscoped refs/redactionrestart cannot reconstruct live identity-bearing values

The previously documented receiver drift is closed: table/range .get dispatch and boolean .str/.display metadata agree with runtime behavior and have owning behavioral fixtures. The registry supplies completion and did-you-mean candidates; dispatch remains authoritative for exact arity and argument-value validation. See value method dispatch.

Namespaces and commands🔗

The builtin identity registry is centralized in the syntax crate and consumed by evaluation, completion, highlighting, and LSP. That portion of the old R4 roadmap is implemented. The actual resolution sequence for functions, aliases, adapters, Reef tools, interpreter runners, and ambient PATH remains distributed across evaluator modules. It is working behavior, but its precedence is harder to audit and easier to diverge than one typed resolver result.

Structured namespaces for JSON, YAML, TOML, CSV, math, HTTP, OS, and config are reachable. External HTTP effects are represented, but Leash has no OS network-enforcement backend; an effect can be planned/denied without a claim that allowed traffic is network-confined.

Execution and concurrency matrix🔗

PathStatusCancellationBackpressure/boundsAuthority notes
captured external commandImplementedprocess-group escalationstdout/stderr drained concurrently; capture limits applyspawn gate and sandbox path are reachable
interactive foreground PTYImplemented on Unixprocess group / terminal controlterminal streaming, host-ownedlocal shell path differs from captured execution
kernel long-lived PTYImplementedclose/drop terminatesread is polling over vt100 screenscoped to session ID; no change subscription
evaluator background taskImplementedtoken and job controloutput representation is bounded by normal capturesuspend/resume available for owned process
kernel async taskImplemented, execution-form limitedcancellation plus process-group suspend/resumeresult stored behind ref; task records advertise current controlsevaluator-only work has no independently stoppable OS owner
list/table stream sourceImplementedconsumer lifecyclefinitesingle-consumption semantics
watch/tail/everyImplementedsink-to-source propagationbounded/coalescing source queuesfilesystem watch still touches host APIs directly
language channelImplementedstream consumer lifecyclereplay/live modeluser.* bridge prevents spoofing kernel channels
kernel EventBusImplemented with scale limitsunsubscribe/disconnect closes queue1,024-event/2 MiB replay ring; 256-event/512 KiB subscriber queues with coalesced count+byte gap summariesone dedicated writer thread per connection; user identity/payload admission
language EventBusImplemented with scale limitsstream drop closes/prunes its queue1,024-event/256 KiB replay ring; 256-event/256 KiB subscriber queues with explicit gap records64 channel identities and 64 live subscribers per evaluator; publish fan-out still holds the channel-map mutex
stream to command stdinImplemented for capture modecommand/caller cancellation stops the pump16 queued chunks, each at most 64 KiBPTY mode rejects stream stdin; no wire stream-pull protocol
stream over wireScaffolded labelno pull cancellationno cursor/item budgetWireValue::Stream is descriptive only
WASM invocationImplemented preview ABIfuel, epoch deadline, and session cancellationmemory/table/instance/argument/value/hostcall limits plus a two-slot process-wide compiler semaphorean admitted synchronous component compile is not wall-interruptible

The former child-context escalation defect is closed: production child evaluators for spawn, parallel, channels, scripts, and streams build through one audited constructor carrying Leash, principal, Reef, config/ports, and cancellation state. A source-inventory regression test prevents new direct child construction. Future child factories must extend that explicit boundary.

Security and authority status🔗

Authentication and session identity🔗

ControlStatusReality
kernel socket transport admissionImplemented, opt-in hardeningsocket 0600; optional mandatory bearer and same-effective-UID peer credential gate
RPC attachment admissionImplemented centralized classificationevery routed stateful method rejects before parameter decode; only attach/parse/complete are pre-attachment surfaces
persisted bearer tokensImplemented live lifecyclefd-locked fresh validation; attached requests revalidate and fail closed on revoke/expiry/store error
token profile/cap stringsInformationalreturned in attach metadata; no Leash/handler authorization consumes them
named-session ownershipImplemented principal-private identityregistry keys are (principal, visible Session name); equal visible names do not share evaluators or quotas
task/PTY ref scopingImplemented exact-owner modelhandlers and registries use the same principal+Session owner key
task await worker boundImplementeddefault 30s, hard 60s ceiling, zero nonblocking; timeout never cancels task
task execution deadlineImplemented through owned task cancellationoptional deadline_ms, hard 24h ceiling, completion-aware watchdog, observable expiry
live state after restartintentionally absentsessions, plans, approvals, tasks, PTYs, refs, and subscriptions are memory-only

Principal-private keys close the former cross-principal aliasing defect, but they do not turn one process into a hard hostile-tenant boundary. Principals still share process memory budgets, global kernel resources, and persisted state roots; mutually hostile tenants need separate OS users, processes, and state directories.

Token administration has a live serving-state contract. shoal-token create/revoke takes an exclusive fd lock, reloads fresh disk state, and atomically replaces it; validation takes a shared lock and reads fresh state. The kernel revalidates a bearer before every attached request, clears the attachment on failure, and therefore observes creation, revocation, expiry, corruption, and I/O failure without restart. profile/--cap values are echoed metadata, not enforced grants.

Effects, policy, and enforcement🔗

LayerStatusHonest interpretation
effect derivationImplemented for modeled operationsopaque/raw paths remain explicitly opaque
plan hashing/storageImplemented bounded object identityfull source/AST/effects/Session/principal digest plus unique object suffix; ephemeral across restart
capability approval callerImplemented one-shot boundaryattached authorized approver, default separation of duties, durable immutable grant audit
journal query/blob/event callersImplemented policy + exact-owner boundaryattachment and JournalRead before row/blob/cursor decode; principal+Session rows/hashes/events only; server-capped pages
allow/ask/deny policyImplementedverdict is not itself OS containment
filesystem sandboxImplemented on supported Linux/macOS pathsenforcement tier reports actual backend result
process hash gateImplemented preflightcontent is checked before exec; TOCTOU remains
coarse network denialImplemented, platform-limitedLandlock ABI 4+ TCP bind/connect denial; Seatbelt deny-default
inherited process ceilingsImplemented, non-aggregatepolicy-driven RLIMIT_CPU/RLIMIT_AS applied by the child launcher across capture/provider/PTY spawns; each descendant inherits its own per-process ceiling
hostname/port network allowlistNot implementedgrants remain planning/policy only; hermetic opaque spawn refuses
malformed local policy handlingImplemented fail closedonly a genuinely missing convenience file selects the permissive default; present invalid authority quarantines to deny-all
child authority inheritanceImplemented unified constructorproduction sites carry principal/policy/Reef/fs/cancellation; future sites are inventory-guarded
secret renderingImplementedgeneric render is redacted; review every new serialization/stdin path
cap-request honestyImplementedresponse uses the same enforcement truth as attach
enforcement previewImplementedattach and plan share typed filesystem/network/spawn/process-limit/hermetic dimensions; activation remains child-local

No documentation should collapse these layers into the sentence “Leash sandboxes commands.” State the effect coverage, policy verdict, backend dimensions, and unsupported dimensions separately.

Protocol and agent surface status🔗

Kernel router🔗

The router exposes session, parse/complete, exec, value, task, PTY, plan, capability, journal, event, blob, and explain method families. Attachment and parameter requirements are documented in the kernel protocol. Attachment-scoped journal reads, authenticated one-shot approval, full non-overwriting owner/content-bound plan identities, and bounded-during-read frame ingestion and bounded raw/blob paging close the original authority/allocation defects. The following contract limitations remain:

  • raw/blob retrieval is capped at 8 KiB of decoded content per response and requires continuation;
  • compressed CAS range reads use bounded memory but verify/decompress sequentially, so distant or repeated pages trade memory safety for extra I/O and CPU;
  • outcome spans now travel when OutcomeVal carries one, including through elision, and are omitted honestly when the producer has no source anchor;
  • task records advertise race-honest cancel/suspend/resume availability; process-backed control may still return TASK_CONTROL_UNAVAILABLE after a child exits, and evaluator-only work is never advertised as suspendable;
  • kernel and in-language events both use count- and byte-bounded subscriber queues with explicit/coalesced gap summaries;
  • journal and transcript cursors survive restart through durable indexes, while most other state does not.

Raw fetch is an explicit pageable contract: value.get uses the existing slice units, blob.get uses byte offset/length, and both expose enough metadata to retrieve the complete authorized value.

MCP facade🔗

Tools and resources map to real kernel methods and have live-kernel integration coverage. MCP does not embed the evaluator, which keeps one source of runtime truth. One facade-owned subscription hub multiplexes at most 64 URI routes over one dedicated socket/thread; exact unsubscribe removes routing state and the final kernel channel membership, while facade drop shuts down and joins the hub.

Refs and elision🔗

Inline value encoding, recursive budgets, CAS blobs, and scoped dynamic refs are implemented. The wire must preserve these distinctions:

flowchart TB
accTitle: Refs and elision
accDescr: Shows the components and relationships described in Refs and elision.
  Value --> Small{"within recursive budget?"}
  Small -->|yes| Inline["typed inline WireValue"]
  Small -->|no| Ref["summary + scoped ref"]
  Bytes --> Blob["CAS blob + shoal://blob URI"]
  Dynamic["task / PTY / stream / plan"] --> Live["session-owned live ref"]
  Restart -. "invalidates" .-> Live
  Restart -. "does not invalidate" .-> Blob

Configuration status🔗

The typed loader, precedence rules, environment overrides, validation, aliases, environment, init, adapter paths, completion settings, history fields, prompt basics, and Reef user scope are real. The exact schema and consumers live in the configuration reference.

Consumer scope remains host-specific and must be documented explicitly:

Field familyParsed/validatedHost consumerStatus
prompt.* basic fieldsyespartialrich prompt separately rereads legacy/template inputs
history.*yeslocal hostimplemented
editor.*yesReedline hostimplemented
completion.*yeslocal hostimplemented
aliases, env, inityesshared bootstrap; init is profile-enforced interactive-onlyimplemented with surface-specific init
adapters.*, plugins.*yesshared host bootstrapimplemented
reef.*yesshared host bootstrap/resolverimplemented
render.widthyesCLI/REPL rendering and pagingimplemented locally
kernel.enabled/sessionyesinteractive REPL compositionimplemented
journal.enabled/state_diryesREPL/private kernel, doctor, history; durable kernel uses its CLI state rootimplemented, host-specific
leash.policyyesshared host bootstrap/private kernelimplemented; authenticated durable kernel policy remains authoritative

Core config and rich prompt loading share one nearest-ancestor project-file discovery rule. Rich prompt details remain subsystem-owned so core validation treats [prompt] as an opaque table while the bounded prompt parser validates its exact schema and migrates legacy prompt.template.

Prompt, editor, and LSP status🔗

The prompt crate is correctly pure: a PromptContext snapshot plus a scalar live edit-mode overlay enter and rendered lines/styles leave. This is a strong boundary. Remaining model gaps are narrow:

  • Git counts, including stash count, come from one bounded status probe;
  • battery and trusted custom module data are gathered outside the render path when configured;
  • git status is gathered synchronously rather than from a deferred/event-driven cache.

The kernel session snapshot carries authenticated human/agent identity and actual Leash tier/enforcement forecast; standalone mode is explicitly local-human. Reedline’s selected editor mode is tracked live across Emacs and Vi insert/normal/visual paints without I/O.

Reedline completion, highlighting, history, menu/picker, and keybinding paths are implemented. They share builtin names but duplicate context heuristics. LSP diagnostics and completion work, while declaration/reference understanding is based on token-level indexing rather than the evaluator’s module, export, closure, and dynamic command-resolution semantics. The full audit is in prompt, editor, and LSP.

Reef and adapter status🔗

Reef🔗

Manifest parsing, ancestor discovery, semver constraints, provider queries, lock records, content hashing, view construction, runner selection, evaluator resolution, and which reporting are real. Important qualifications:

  • interactive discovery warns once and skips malformed/unreadable scopes so diagnosis remains possible; noninteractive external execution fails closed while any such warning is retained;
  • metadata cache identities include device/inode/mtime/ctime/length, but cannot close the metadata-to-open or hash-to-exec race against a hostile concurrent writer;
  • an unknown tool constrained to latest does not imply exhaustive remote probing;
  • provider acquisition can have external partial effects even though lock publication is atomic;
  • filesystem sandbox enforcement is platform-dependent; coarse network denial requires Landlock ABI 4+ or Seatbelt, while hostname/port allowlists remain unavailable.

See the Reef resolution reference for the exact pipeline.

Adapters🔗

Adapters are data-driven command descriptions and output parsers, not magic wrappers around all versions of a tool. The current tree contains substantially more definitions and command tables than the older “42 adapters” roadmap count. Catalog size is best generated during the site build or release process; prose should describe coverage classes and validation rather than freeze a number.

Interpreter-class adapters feed an explicit parser-context set and own raw-block argv/payload/output lowering. A generated bundled-pack parity test prevents shipped interpreter declarations from drifting outside the standalone parser’s default registry.

Persistence status🔗

SQLite WAL, version stamping, unfinished rows, zstd-compressed blake3 CAS, output metadata, typed undo inverses, pins, garbage collection, query filters, and durable transcript payloads are implemented. The journal storage reference records the schema and lifecycle.

Two current limitations deserve release-note visibility:

  1. schema v2 distinguishes coarse exec, fine statement, and approval rows and links new kernel statements to their parent exec, but migrated v1 rows cannot recover historical parent links;
  2. the language evaluator now rejects an installed-journal begin failure before effects and reports post-effect persistence failure as indeterminate, but direct journal embedders still define their own degraded-health policy.

Evaluator spill adoption now uses counted owner leases. Lazy value drop releases them, independent owners cannot release one another, and applied GC detects crash-stale owner lockfiles before selecting blobs. Permanent history pins remain explicitly manual.

Crash persistence is intentionally asymmetric: an appended row with NULL completion columns survives; live task/PTY/ref/session objects do not.

Platform matrix🔗

ConcernLinuxmacOSWindowsPortability note
parser/evaluator/value semanticsprimarysupportedlargely portable leaf codeOS/path/process tests still required
captured subprocessesyesyesno supported contractprocess groups/signals are Unix-shaped
interactive PTYyesyesdeferredConPTY needs a distinct backend
Unix kernel socketyesyesunsupportednamed pipe or TCP/auth design required
filesystem sandboxLandlock/seccomp pathSeatbelt pathabsentenforcement dimensions differ
network sandboxabsentabsentabsentpolicy-only everywhere
symlink-safe undosupported pathcwd-under-symlink edge openunreviewedpath identity rules differ
filesystem watchsupported backendsupported backenduncommittedcancellation and overflow need platform tests
non-UTF-8 path contractUnix raw bytesUnix raw bytesdifferent wide-string modelcannot blindly copy Unix encoding
CIUbuntumacOSnoneWindows remains an explicit project, not a checkbox

“Runs on Rust” is not evidence for Windows support. The kernel transport, PTY, job control, signals, sandbox, executable resolution, path encoding, and undo safety rules all require coherent Windows design and integration tests.

Quality and test evidence🔗

Current evidence🔗

  • the conformance corpus is the normative language behavior suite;
  • crate unit tests cover leaf invariants and many error paths;
  • integration tests exercise interactive CLI, config wiring, process/PTY behavior, daemon restart, and a live MCP-to-kernel route;
  • CI runs formatting, Clippy, tests, and release builds on Ubuntu and macOS;
  • fuzz-target compilation is a blocking PR check; bounded runtime fuzzing runs nightly, and coverage remains intentionally smoke-level;
  • Criterion commands exist for parser, evaluator, prompt, and wire benchmarks.

The benchmark thresholds in historical BENCHMARKS.md are review budgets, not evidence that the current commit meets them on a standardized machine. The site’s tooling and quality page preserves exact commands and separates measured results from desired ceilings.

Known quality gaps🔗

  • every workspace member inherits the workspace lint table; stronger deferred lints still have live violations and are tracked rather than enabled decoratively;
  • two corpus harnesses duplicate fixture/schema behavior;
  • highlighter tests isolate and restore NO_COLOR, so ambient color policy no longer changes them;
  • test presence is uneven across crates, with significant inline unit coverage that directory counts do not reveal;
  • protocol framing, slow-consumer gap accounting, principal isolation, child-capability inheritance, poison quarantine, plugin deadlines, and bounded raw/blob paging have dedicated adversarial tests; broader OS/platform matrices remain coverage and design gaps.

Historical-document reconciliation🔗

These root documents were valuable design inputs. Their durable material has been absorbed into the internal atlas; their counts and status language are not current authority.

Historical documentDurable intentCurrent canonical homeClaim that needed correction
docs/VISION.mdtyped values, explicit effects, shared agent/human semanticssystem map, value/effect pagesthe default REPL now executes through an isolated private kernel, while durable machine kernels remain a separate trust/state domain
docs/ROADMAP.mdwave rationale and original acceptance criteriathis page and roadmap“done” waves concealed host/security/lifecycle qualifications; counts were stale
docs/TDD.mdgrammar, semantics, errors, edge rulingslanguage conformance contractold corpus count and some later feature statuses drifted
docs/STREAMS.mdone stream model, explicit consumption/backpressurestreams and channelsbounded stream-to-stdin is implemented; wire pulling remains absent
docs/IO.mdtyped stdin, interpreter blocks, runner UXprocess execution, calls/modules, Reefbare path auto-run remains .shl-only
docs/REEF.mdreproducible scope/lock/provider/view modelReef resolutionhistorical design remains less precise than the canonical reference
docs/CONFIG.mdtyped layered configurationconfiguration referenceseveral documented keys parse but do nothing
docs/AGENT-SURFACE.mdrefs, elision, events, tools, PTYskernel protocol and agent/MCPraw fetch bounds, subscription cost, and restart limits needed qualification
docs/CONTRACTS.mdpublic APIs and dependency directionintercrate protocol contractssome pinned prose lagged current types and wire behavior
docs/BENCHMARKS.mdperformance budgets and commandstooling and qualitytargets were not continuously measured assertions

Historical wave disposition🔗

Old waveHonest current disposition
R0 interactive ergonomicsImplemented on the local shell; host-specific exit/render behavior remains deliberately owned there.
R1 streams/channelsCore language path and bounded stream stdin are implemented; wire pulling and cross-surface scaling remain open.
R2 namespaces/builtinsImplemented; security meaning of network effects remains policy-only.
R3 modules/tasks/plan/undoMostly implemented; child authority inheritance and process-backed kernel task control are complete, while task identity models remain split.
R4 ports/modularizationStructural split, effect ports, canonical command-source precedence, and method metadata parity are implemented; some direct host calls remain.
R5 corpus/docs/polishCorpus target exceeded; this Zola atlas replaces duplicated wiki/root status prose; polish is continuous.

Release claim checklist🔗

Before calling a subsystem “done,” answer all of these with links to executable evidence:

  1. Which composition roots can reach it?
  2. Which configuration or capability state reaches those roots?
  3. Which values, errors, and spans survive local, kernel, and MCP boundaries?
  4. Which queues, frames, collections, and outputs have hard bounds?
  5. What happens on cancellation, disconnect, crash, and restart?
  6. Which principal owns each session, ref, plan, blob, task, and PTY?
  7. Which effect is derived and which OS backend enforces it?
  8. What is advisory, unavailable, or platform-specific?
  9. Which focused invariant test and which live-boundary test prove it?
  10. Which diagrams, public docs, protocol fixtures, and migration notes changed?

Highest-impact open findings🔗

This is a status list, not the work order; ordering and exit criteria live in the roadmap.

  1. Reef metadata-to-open/hash-to-exec atomicity and cross-platform containment remain incomplete;
  2. filesystem/network sandbox coverage is platform- and effect-limited;
  3. plugin ABI v1 is deliberately narrow, and admitted synchronous component compilation cannot be preempted even though input bytes, concurrent jobs, and admission wait are bounded;
  4. kernel quotas and separate evaluator budgets bound retained sessions, 64 native workers per session (512 process-wide), 256 executable plans, and 1,024 memoized modules; these remain independent admission systems rather than one universal executor;
  5. Windows remains a separate architecture project.

Audit maintenance protocol🔗

Update this ledger in the same change that changes reachability or removes a qualification. Do not replace an explicit caveat with “fixed” unless the new proof includes the lowest invariant and the real composition boundary. If a feature becomes intentionally unsupported, documenting and testing the error is better than preserving an unreachable status claim.

Type to search every guide↑↓ navigate ↵ open esc close
Diagram