Crate and module ledger

The workspace contains 22 crates. The table below is a routing contract: start a change in the crate that owns the invariant, then let hosts adapt to it. Do not begin in a composition root merely because that is where a symptom appears.

Workspace ledger🔗

Module atlas🔗

Syntax and representation🔗

flowchart LR
accTitle: Syntax and representation
accDescr: Shows the components and relationships described in Syntax and representation.
  Span["shoal-ast/span.rs\nbyte-offset spans"] --> AST["shoal-ast/ast.rs\nProgram, Stmt, Expr, Pattern"]
  Lexer["shoal-syntax/lexer.rs\nEXPR and CMD modes"] --> Parser["parser.rs + stmt/expr/command/pattern"]
  Parser --> AST
  AST --> Formatter["shoal-syntax/format.rs\ncanonical source"]
  Registry["shoal-syntax/commands.rs\ncanonical builtin names"] --> Parser

shoal-syntax is divided by grammar concern: lexer, parser, stmt, expr, command, pattern, block, string, and number. format walks the resulting AST. commands is the shared builtin-name registry used by evaluator and editor-facing classification.

Values and generic operations🔗

flowchart TB
accTitle: Values and generic operations
accDescr: Shows the components and relationships described in Values and generic operations.
  Value["lib.rs\nValue algebra + feed_bytes"]
  Env["env.rs\nlexical bindings"]
  Methods["methods/*\ntype-directed methods"]
  Stream["stream/*\npull protocol + lazy operators"]
  Task["task.rs\ncompletion and control hooks"]
  Render["render.rs\nhuman rendering"]
  JSON["json.rs\nstructured conversion"]
  Ports["ports.rs\nvalue-side IO traits"]
  Outcome["outcome.rs\nprocess/builtin result"]

  Value --> Env
  Value --> Methods
  Value --> Stream
  Value --> Task
  Value --> Render
  Value --> JSON
  Value --> Outcome
  Methods --> Ports

The methods directory separates list, record, string, numeric, path, outcome, task, and stream families. Stream operators live under stream/ because they own pull state, timeout propagation, single-consumption, and tee buffering rather than only method name dispatch.

Evaluation🔗

flowchart TB
accTitle: Evaluation
accDescr: Shows the components and relationships described in Evaluation.
  Entry["lib.rs\nEvaluator state + program loop"]
  Stmt["stmt.rs"] --> Expr["expr.rs / expr_access / expr_binop"]
  Expr --> Call["call.rs"]
  Expr --> Command["command.rs\ncommand dispatch"]
  Command --> Args["args.rs / coerce.rs"]
  Command --> Builtins["builtins.rs"]
  Command --> Host["host.rs\noutcome wrapping"]
  Command --> Script["script.rs"]
  Command --> Reef["reef*.rs"]
  Command --> Ports["ports.rs\nFs, Exec, Clock, Opener…"]
  Entry --> Modules["modules.rs / namespaces.rs"]
  Entry --> Journal["journal.rs"]
  Entry --> Plans["plan.rs / plan_derive.rs / plan_effects.rs"]
  Entry --> Streams["streams.rs / channels.rs"]

This is a tree-walk evaluator. lib.rs holds session state and the top-level evaluation loop; semantic cases are split by AST kind. command.rs is intentionally a high-fan-out dispatch point, so additions there deserve parity tests across callable, builtin, adapter, script, Reef, and external-command cases.

Execution and policy🔗

shoal-exec separates capture from pty and pty_session; cancel, watcher, and status normalize lifecycle behavior; which locates executables; sandbox selects the OS implementation. OS-specific enforcement is in Leash’s enforce and seatbelt modules. This is where the workspace’s unsafe and Unix-specific code should remain concentrated and reviewable.

flowchart LR
accTitle: Execution and policy
accDescr: Shows the components and relationships described in Execution and policy.
  Effects["leash/effects.rs"] --> Policy["leash/policy.rs"]
  Policy --> Lower["leash/enforce.rs"]
  Lower --> Request["exec/lib.rs\nExecSpec"]
  Request --> Capture["capture.rs"]
  Request --> Pty["pty.rs / pty_session.rs"]
  Capture --> Status["status.rs"]
  Pty --> Status
  Cancel["cancel.rs"] --> Capture
  Cancel --> Pty

Kernel and agent bridge🔗

The kernel’s dispatch.rs is a thin method router. Handler modules own session, execution/plan, value/event, task, and PTY families. session.rs owns shared evaluator/transcript state; wire.rs does bounded Value conversion; eventbus.rs owns rings, durable replay integration, and subscriber queues. lib.rs owns connection lifecycle and shared maps.

shoal-mcp is divided into a socket client, MCP tools, URI-backed resources, and the stdio server in lib. It deliberately consumes the public kernel contract rather than reaching into kernel memory.

Reef, adapters, and configuration🔗

flowchart TB
accTitle: Reef, adapters, and configuration
accDescr: Shows the components and relationships described in Reef, adapters, and configuration.
  Scope["reef/scope.rs\nnearest-first discovery"] --> Manifest["manifest.rs"]
  Manifest --> Resolve["resolve.rs"]
  Resolve --> Providers["npm / venv / mise / cargo / system"]
  Resolve --> Lock["lock.rs"]
  Lock --> Hash["hashcache.rs"]
  Resolve --> View["view.rs\ncontent-addressed PATH view"]
  Runner["runner.rs\nextension + shebang"] --> Resolve

  ConfigLoad["config/load.rs"] --> ConfigSchema["config/schema.rs"]
  AdapterLoad["adapters/lib.rs\nTOML specs"] --> Bind["typed argv binding"]
  Bind --> Parse["JSON / lines / CSV / records…"]

Core config and prompt config are separate systems. shoal-config loads the shell’s core schema; shoal-prompt has its own config and formatting modules. Reef manifests are also parsed through their own discovery path. Treating all three as one configuration object will miss real behavior.

Complete source-module routing index🔗

This index names every current Rust source module, including binary entrypoints and nested modules. It is intentionally mechanical: a newly added module should appear here in the same change so future maintainers can tell whether the architecture gained a boundary or only an implementation split.

Entrypoints are adapters🔗

Every main.rs should remain thin: parse process arguments/environment, construct the owning library, choose exit behavior, and report errors. Business rules placed only in a binary cannot be reused by the shoal companion launcher or exercised through library integration tests.

Public boundaries versus implementation modules🔗

Changing a private module is not automatically a local change. These cross-crate concepts are the effective public architecture:

Workspace-level maintenance signals🔗

The root Cargo.toml declares a workspace lint policy, but member manifests do not currently opt in with [lints] workspace = true. CI still runs Clippy with warnings denied, so today the executable quality gate is the CI command rather than inherited manifest metadata. If lint inheritance is enabled, do it across the workspace and expect latent warnings rather than assuming the table is already active.

Workspace package metadata now uses the same alliecatowo/shoal repository as the checked-out remote and documentation links. Keep this as one workspace-level value rather than overriding it in individual crates.