textus 0.55.2 → 0.56.0

data/docs/architecture/README.md

@@ -1,273 +0,0 @@
-# Textus architecture
-
-> **Explanation** · for contributors · **read this first** for orientation before SPEC
-> **SSoT for** the Ruby implementation layout (layers, container, ports, dispatch paths) · **reviewed** 2026-06 (v0.54)
-
-```mermaid
-flowchart TD
-    surfaces["Surfaces — CLI · MCP · RoleScope"]
-    contract["Contract — per-verb DSL (Arg, Spec, DSL)"]
-    dispatch["Dispatch — Binder · Around · CommandBuilder · Dispatcher"]
-    gate["Gate — routing (VERB_COMMAND) · Auth"]
-    action["Actions — per-verb use cases (action/)"]
-    jobs["Jobs — Worker · Planner · Materialize · Retention · Sweep"]
-    produce["Produce — Engine · Render"]
-    workflow["Workflow — Runner · Registry · Loader · DSL"]
-    manifest["Manifest — declarative config, no IO (policy/, schema/, entry/)"]
-    core["Core — pure value types (Freshness, Retention, Duration, Sentinel)"]
-    ports["Ports — IO adapters (FileStore, AuditLog, JobStore, Publisher…)"]
-    surfaces --> dispatch
-    surfaces -.->|declare| contract
-    contract --> dispatch
-    dispatch --> gate
-    gate --> action
-    action --> jobs
-    action --> produce
-    produce --> workflow
-    action --> manifest
-    action --> core
-    action --> ports
-    jobs --> produce
-```
-
-*Dependency rule: inward only.* Surfaces → Dispatch → Gate → Actions → inner layers. Actions never reference surfaces.
-
-### What lives in each layer
-
-**Surfaces**
-
-```
-surfaces/cli/     CLI command generation from contracts
-  sources.rb      CLI-only input acquisition (stdin parsing, file sourcing, coercion)
-surfaces/mcp/     MCP server — stdio JSON-RPC 2.0, tools derived from contracts
-surfaces/role_scope.rb
-                  (Store#with_role(role)) — holds (container, role, dry_run, correlation_id);
-                  all verb methods injected via define_method in textus.rb
-```
-
-**Contract + Dispatch**
-
-```
-contract/         Per-verb DSL — verb, summary, surfaces, arg, view, around.
-                  Pure declaration: Spec and DSL only.
-
-dispatch/         Runtime machinery consumed by every surface.
-  binder.rb       Binder — validates required args, resolves session/literal defaults.
-  around.rb       Around — registry of stateful wrappers (cursor, build_lock).
-  view.rb         View.render(spec, surface, result, inputs) — output shaping.
-  command_builder.rb
-                  CommandBuilder — command construction + role injection.
-  dispatcher.rb   Dispatcher — unified pipeline: Around → Binder → Command → Gate.
-  resources/      Around resource implementations (Cursor, BuildLock).
-```
-
-**Gate + Auth**
-
-```
-gate.rb           VERB_COMMAND  (verb symbol → Command class)
-                  Gate#dispatch(cmd) — Auth → action call
-gate/auth.rb      Authorization engine — FLOOR predicates + rule guards
-```
-
-**Actions**
-
-```
-action/{get,list,put,key_delete,key_mv,accept,reject,propose,
-        drain,enqueue,audit,blame,deps,rdeps,published,boot,doctor,
-        rule_explain,rule_list,rule_lint,pulse,
-        data_mv,key_mv_prefix,key_delete_prefix,
-        schema_envelope,where,uid,jobs}.rb
-```
-
-**Jobs**
-
-```
-jobs/planner.rb   Rules-driven job planning — seeds materialize/refresh/sweep jobs
-jobs/worker.rb    Queue drain — leases and runs jobs from JobStore
-jobs/materialize.rb  Per-key produce job → Produce::Engine.converge
-jobs/refresh.rb   Per-key refresh job (retention-rule-triggered)
-jobs/retention.rb Retention policy check
-jobs/sweep.rb     Lane sweep job
-```
-
-**Produce**
-
-```
-produce/engine.rb         Engine.converge(container:, call:, keys:)
-                          For each key: looks up a registered workflow and runs it,
-                          or publishes existing bytes for entries with publish targets.
-produce/render.rb         Mustache template expansion for publish targets
-```
-
-**Workflow**
-
-```
-workflow/runner.rb    Runs a Definition: build_context → execute_steps → publish
-workflow/registry.rb  In-memory list of registered Definitions; Registry#for(key)
-workflow/loader.rb    Loads .textus/workflows/*.rb files via Collector DSL
-workflow/dsl.rb       Textus.workflow "name" { match "...", step :fetch { ... }, publish }
-workflow/context.rb   Context passed to each step (key, entry, config, container, call)
-workflow/pattern.rb   Key-matching pattern (glob via File.fnmatch?)
-workflow/errors.rb    NotFound, StepFailed
-```
-
-**Core (pure value types)**
-
-```
-Freshness::{Verdict,Evaluator}
-Core::Duration  Core::Sentinel
-```
-
-**Infrastructure**
-
-```
-Store              (composition root — wires ports, vends Container)
-Storage::FileStore (bytes-only port: read/write/delete/exists?/etag)
-Manifest           (Data, Resolver, Policy, Rules)
-Schemas            (eager-load cache)
-Ports::{AuditLog,JobStore,Publisher,Clock,
-        BuildLock,SentinelStore}
-Entry::{Markdown,Json,Yaml,Text}  (format strategies)
-```
-
-## How a verb becomes a method
-
-All actions live under `lib/textus/action/`. The shape is uniform:
-
-```ruby
-module Textus
-  module Action
-    class Get < Base
-      extend Textus::Contract::DSL
-
-      verb :get
-      summary "Read an entry by key."
-      surfaces :cli, :mcp
-      arg :key, String, required: true, positional: true
-
-      BURN = :sync
-
-      def initialize(key:)
-        super()
-        @key = key
-      end
-
-      def call(container:, call:)
-        ...
-      end
-    end
-  end
-end
-```
-
-Verbs are looked up in a static frozen table (`Textus::Action::VERBS`) that maps `:get → Action::Get`, `:put → Action::Put`, etc. Adding a new verb is one entry in `VERBS` plus the class — no metaprogramming.
-
-## Container
-
-Use cases never see the raw `Store`. `Textus::Container` is a single record holding the wired collaborators:
-
-```ruby
-Container = Data.define(
-  :manifest, :file_store, :schemas, :root,
-  :audit_log, :workflows, :gate
-)
-```
-
-The `Store` builds one `Container` at boot; every action receives it via `(container:, call:)`. Workflow steps receive a `Workflow::Context` (key, entry, config, container, call).
-
-## Ports
-
-| Class | Role |
-|---|---|
-| `Ports::Storage::FileStore` | Bytes-only FS I/O — `read`, `write`, `delete`, `exists?`, `etag`. |
-| `Ports::AuditLog` | Append-only structured log (`audit.log`). Owns seq numbering, file-locking, rotation. |
-| `Ports::Clock` | Supplies `Time.now` — module-function so tests can swap without DI boilerplate. |
-| `Ports::Publisher` | Copies a built artifact to a repo-relative consumer path and writes a sentinel. |
-| `Ports::BuildLock` | Process-exclusive `flock` guard over the produce pipeline. |
-| `Ports::JobStore` | Persistent job queue used by `drain` workers; tracks ready/leased/done/failed jobs. |
-| `Ports::SentinelStore` | Reads and writes per-target sentinel files for managed-file detection. |
-
-Application use cases access ports only through `Container` fields — never through the raw `Store`.
-
-### Envelope
-
-`Envelope::Reader` and `Envelope::Writer` split the envelope pipeline into read-only parse and write-with-audit halves.
-
-**Reader** (`lib/textus/envelope/reader.rb`) — resolves a key through `manifest.resolver`, reads bytes via `FileStore`, parses via the format strategy, returns an `Envelope`. No audit, no permissions.
-
-**Writer** (`lib/textus/envelope/writer.rb`) — owns the full write pipeline: serialize → schema-validate → etag-check → `FileStore#write` → `AuditLog#append`. The audit append is the commit step.
-
-Both are built from a `Container` via named constructors — `Writer.from(container:, call:)` and `Reader.from(container:)`.
-
-## Manifest carving
-
-`Manifest` is a `Data.define` struct with four named members:
-
-| Member | Class | Responsibility |
-|---|---|---|
-| `data` | `Manifest::Data` | Frozen value: raw, root, lanes, entries, audit_config, role_caps. |
-| `resolver` | `Manifest::Resolver` | Key → `Resolution(entry, path, remaining)`. Nested entry enumeration and fuzzy-match suggestions. |
-| `policy` | `Manifest::Policy` | Zone/capability authority — `verb_for_lane`, `roles_with_capability`, `propose_lane_for(role)`. |
-| `rules` | `Manifest::Rules` | Pattern-matched rule engine. `rules.for(key)` → `RuleSet(guard, retention, react)`. |
-
-## Read path (`store.get(key)`)
-
-`Action::Get` is a **pure read** — it resolves the path, reads bytes, parses the envelope, and annotates a freshness verdict. It never ingests and never mutates.
-
-1. CLI/MCP surface calls `store.with_role(role).get(key)`.
-2. `Gate#dispatch` runs Auth → `Action::Get#call`.
-3. `Get` resolves path via `manifest.resolver`, reads bytes via `file_store`, parses the envelope, annotates `freshness` based on retention-rule TTL (if any).
-
-Staleness is age-based (retention-rule TTL vs file mtime). A stale entry is returned stale — the read does not refresh it; `drain` does.
-
-## Write path (`store.put(key, ...)`)
-
-1. CLI/MCP surface calls `store.with_role(role).put(key, meta:, body:)`.
-2. `Gate#dispatch` runs Auth → `Action::Put#call`.
-3. `Put` validates, resolves manifest entry, delegates to `Envelope::Writer#put` (serialize → schema-validate → etag-check → FileStore#write → AuditLog#append).
-4. `WriteVerb#cascade_to_rdeps` enqueues `materialize` jobs for any entries with publish_tree that depend on the written key.
-
-`Action::{KeyDelete,KeyMv,Accept,Reject,Propose}` follow the same shape.
-
-## Workflow path (`drain` + materialize jobs)
-
-The workflow system owns the produce pipeline. `Produce::Engine.converge(container:, call:, keys:)` is the entry point that `Jobs::Materialize` calls.
-
-For each key, `Engine#produce_one`:
-
-1. Looks up a registered workflow via `container.workflows.for(key)` (Pattern matching against the key).
-2. If a workflow matches: `Workflow::Runner.new(definition, container:, call:).run(key)`.
-   - `Runner` builds a `Workflow::Context`, executes each step in sequence, then publishes.
-   - **Built-in publish**: writes the step output to the entry via `Envelope::Writer`, then calls `entry.publish_via(pctx)` for any `publish_to` or `publish_tree` targets.
-3. If no workflow matches but the entry has publish targets: runs `publish_only` — publishes existing store bytes via `entry.publish_via` without re-fetching.
-
-**Workflow files** live in `.textus/workflows/*.rb`. The DSL:
-
-```ruby
-Textus.workflow "my-producer" do
-  match "artifacts.derived.*"
-  step :fetch do |data, ctx|
-    { content: { "key" => ctx.key } }
-  end
-  publish  # uses built-in publish (writes to entry, then to publish targets)
-end
-```
-
-## Agent surface (boot + pulse + MCP)
-
-```
-agent/plugin  ──▶  gate (CLI | MCP)  ──▶  Store  ──▶  memory (.textus/)
-```
-
-Two transports, one façade:
-
-- **CLI** — human/script surface. `textus boot`, `textus pulse --since=N`, `textus get/put/...`.
-- **MCP** — agent surface. `textus mcp serve` runs a stdio JSON-RPC 2.0 server. Tools are auto-derived from contracts. Session state (cursor, role, contract_etag) is server-side.
-
-The agent loop:
-
-1. **Session start:** `boot()` → contract envelope (lanes, entries, workflows, write_flows, agent_quickstart).
-2. **Per turn:** `pulse(since=cursor)` → `{cursor, changed, stale, pending_review, doctor, next_due_at}`.
-3. **On demand:** `get`, `put`, `propose`, `schema_show`, `rule_explain`, `drain`.
-
-Contract drift surfaces as `ContractDrift` (contract_etag mismatch — a change to manifest/schemas); audit cursor expiry as `CursorExpired`. Both signal "call `boot` again."

data/docs/reference/conventions.md

@@ -1,141 +0,0 @@
-# Conventions
-
-> **Reference** · for integrators · **read when** you're shaping a `.textus/` tree and want the idiomatic choices
-> **SSoT for** idiomatic key naming, schema design, and automation integration · **reviewed** 2026-06 (v0.43)
-
-Guidelines for shaping a `.textus/` tree, naming keys, organising schemas, and integrating with build automation. The spec ([`../../SPEC.md`](../../SPEC.md)) defines what's enforceable; this document captures what's *idiomatic*.
-
-## Key naming
-
-- **Segments are lowercase, kebab- or snake-case.** The grammar `^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$` is the hard limit. Prefer `acme-dashboard` over `acmedashboard` when there's a natural word break.
-- **Lead with the lane in the key path.** `working.projects.acme.dashboard`, not `projects.acme.dashboard`. The lane prefix makes it obvious from the key alone whether a write will be accepted.
-- **Mirror the directory structure.** If `working.projects.acme.dashboard` resolves to `working/projects/acme/dashboard.md`, do not invent shortcuts that diverge.
-- **Don't pluralise the leaf.** `working.network.org.jane`, not `working.network.org.janes`. Pluralise the container, not the entry.
-
-## Lane layout
-
-Recommended top-level layout — the spec allows alternatives, but this is what tooling will default to:
-
-```
-.textus/
-  manifest.yaml
-  schemas/        # YAML schema definitions
-  workflows/      # Textus.workflow DSL files for produced entry acquisition
-  templates/      # ERB templates for publish rendering
-  data/
-    knowledge/    # authored truth: identity, voice, decisions — author-holders write
-    scratchpad/     # agent's own durable lane (workspace) — keep-holders write
-    proposals/    # AI proposals awaiting accept (propose)
-    artifacts/    # computed outputs produced by drain — never edit by hand
-    raw/          # write-once external source material (ingest)
-```
-
-Inside `knowledge/`, group by **domain** (identity, people, projects, decisions, runbooks), not by file type or date. `knowledge.identity.*` is the convention for slow-changing identity facts. Inside `artifacts/`, group by **producer** (`artifacts/catalogs/`, `artifacts/indexes/`) so it's clear which build job owns what.
-
-## Schema design
-
-- **One schema per entry type, not per directory.** `person.yaml`, `project.yaml`, `decision.yaml` — applied across multiple subtrees if the shape matches.
-- **Required = "this entry is meaningless without it."** Everything else is `optional`. Resist the urge to mark organisational metadata (like `tags`) required.
-- **Prefer `enum` over free-text** for low-cardinality fields (relationship type, status, severity). Agents are far better at picking from a list than at producing exact strings.
-- **Cap string lengths** with `max:` where the field has a natural bound (names, summaries). Skip for prose body — bodies are not schema-validated, only frontmatter is.
-
-## Owner strings
-
-The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it to label *who's expected to write here*. The form is `<archetype>` or `<archetype>:<subject>`; the archetype must be one of `human`, `agent`, `automation` (validated at load — ADR 0045), and the subject is free-form:
-
-- `human:network` — humans curate
-- `agent:planner` — a specific named agent
-- `automation:catalog-skills` — a specific build job
-
-Tooling around `git blame` or audit logs may filter on owner; the gem itself only echoes it back in envelopes.
-
-## Produced entries
-
-A produced entry declares `source: { from: external, command: "true", sources: [] }` and a matching `Textus.workflow` block in `.textus/workflows/**/*.rb`. The `source:` acquires **data** — it never renders; rendering is a publish concern (below).
-
-```yaml
-- key: artifacts.feeds.skills
-  lane: artifacts
-  kind: produced
-  format: json
-  source: { from: external, command: "true", sources: [] }
-  publish:
-    - { to: docs/reference/skills.md, template: feeds/skills.erb }
-```
-
-The matching workflow block:
-
-```ruby
-# .textus/workflows/feeds/agentskills.rb
-Textus.workflow "agentskills" do
-  match "artifacts.feeds.skills"
-
-  step :fetch do |_, _ctx|
-    { "content" => { "skills" => [...], "count" => 1 } }
-  end
-
-  publish
-end
-```
-
-`drain` discovers workflows, matches entries, runs the steps, and writes the result back to the entry's data path. Publishing then copies or renders each `publish:` target.
-
-Age-based GC uses a `retention:` rule in the top-level `rules:` block:
-
-```yaml
-rules:
-  - match: artifacts.feeds.**
-    retention: { ttl: 90d, action: archive }
-```
-
-Full contract in [`../../SPEC.md` §5.2](../../SPEC.md).
-
-## Freshness
-
-A `get` is always a pure read (ADR 0089) — it never triggers a re-produce:
-
-```sh
-textus pulse --output=json       # `stale` lists entries past their ttl
-textus drain --as=automation     # re-produces stale entries
-```
-
-See [`./lanes.md`](lanes.md) for lane semantics and [`../how-to/configuring-lanes.md`](../how-to/configuring-lanes.md) for setting up produced entries and workflows.
-
-### Read vs. refresh
-
-There is one public read operation, and it is pure (ADR 0089):
-
-| Operation | Behaviour | Use for |
-|-----------|-----------|---------|
-| `ops.get` | A pure on-disk read annotated with a freshness verdict — it NEVER ingests, regardless of the entry's `action`. A stale `refresh` entry reads back stale until the next `drain`. | every caller — interactive reads, dashboards, scripts, and internal pipelines (materializer, projection, schema tooling, accept/reject/publish, uid, validator) |
-
-Refreshing a stale entry is `drain`'s job (or a `hook run` event), never a read's — so no caller can accidentally trigger network I/O by reading.
-
-## Body content
-
-- **Bodies are Markdown.** Headings, lists, code fences — whatever a human or agent finds useful.
-- **The schema does not validate the body.** If a field belongs in structured data, put it in frontmatter, not the body.
-- **Keep entries short.** If a project entry hits 500 lines, it probably wants to be split into sub-entries (e.g. `working.projects.acme.dashboard` + `working.projects.acme.api`) rather than one mega-document.
-
-## Concurrency
-
-For multi-writer environments, **always pass `if_etag`** on `put`. The gem treats etag-less writes as last-writer-wins on purpose (single-writer scripts, fresh-file creation), but anything resembling a daemon or a long-running agent should round-trip the etag.
-
-## Application layering
-
-The application layer is organised around three shapes — `Manifest` as a composition record, a single `Container` capability record handed to every use case, and a split envelope reader/writer. See [ADR 0018](../architecture/decisions/0018-manifest-carving.md), [ADR 0017](../architecture/decisions/0017-envelope-io-split.md), [ADR 0022](../architecture/decisions/0022-container-call-dispatcher.md), and [ADR 0023](../architecture/decisions/0023-uniform-use-case-shape.md).
-
-- **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(lane)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`.
-- **`Store` is the single dispatch module.** `Store` holds the `Container`, the active role, session state (cursor, propose_lane, contract_etag), and dispatches verbs through `method_missing`. Each verb call (`store.get(key: ...)`, `store.put(key:, meta:, body:)`) goes through `VerbRegistry`, binds inputs via `Dispatch::Binder`, routes through `Dispatch::Pipeline` (middleware chain: auth, cascade, audit), and reaches the handler. `Store#with_role(role)` returns a new `Store` bound to that role.
-- **`Container` is a `Data.define` composition** of `Infrastructure` (`file_store`, `schemas`, `audit_log`, `job_store`, `geometry`) and `Coordination` (`manifest`, `workflows`, `pipeline`). Built in a single pass — no circular dependencies or lazy proxies.
-- **Dispatch lives in `lib/textus/dispatch/`**: `Dispatch.dispatch` orchestrates verb dispatch, `Dispatch::Pipeline` runs middleware then invokes the handler, `Dispatch::Binder` handles input binding (wire format, CLI flags, session defaults). Auth predicates moved to `Manifest::Policy::Predicates`.
-- **Handlers receive `container:`** and access I/O via `@container.pipeline.read/write/delete/move` and manifest config via `@container.manifest`.
-- **Write path is split**: `Envelope::IO::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Envelope::IO::Writer` owns put/delete/move + the audit-append invariant (every public method's final action is `@audit_log.append(...)`).
-
-The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/4`) are unchanged.
-
-## Pairing with other tools
-
-- **MCP servers**: a thin server that exposes `textus get` and `textus put` as tools is the recommended way to give Claude/agents access. Don't bake MCP into this gem.
-- **Vector stores**: index `body` content into a vector store if you want fuzzy retrieval. `frontmatter` stays in textus as the source of truth for deterministic facts.
-- **CI**: run `textus doctor` (the `generator_drift` check) or `textus pulse` (the `stale` list) in CI to catch drift between derived entries and their sources.

data/lib/textus/boot.rb

@@ -1,181 +0,0 @@
-module Textus
-  # Read-only "what's in this store and how do I use it" envelope.
-  # Boot is side-effect-free. Reads from pre-computed artifacts and
-  # the store catalog rather than computing inline.
-  module Boot
-    PROTOCOL_ID = PROTOCOL
-
-    # Human-readable name(s) for the live lane(s) of a given kind, or `fallback`
-    # when the manifest declares none. Lets write-flow guidance name the live
-    # lane by kind instead of a hardcoded instance name (ADR 0034).
-    def self.lane_label(manifest, kind, fallback)
-      lanes = manifest.policy.lanes_of_kind(kind)
-      lanes.empty? ? fallback : lanes.join(", ")
-    end
-
-    # Static, store-independent parts of the agent-facing protocol. The
-    # `recipes` and `role_resolution` blocks are derived per-manifest in
-    # agent_protocol(...) because lane and role names are user-configurable.
-    AGENT_PROTOCOL_TEMPLATE = {
-      "envelope_shape" => {
-        "summary" => "every read/write payload is a JSON envelope with _meta, body, uid, and etag",
-        "fields" => {
-          "_meta" => "hash of structured frontmatter; schema-validated per entry family",
-          "body" => "string payload (markdown/text) or nil for json/yaml formats where body lives in _meta",
-          "uid" => "stable 16-char hex identifier; preserved across writes and key renames",
-          "etag" => "content hash; pass back on writes to detect concurrent edits",
-        },
-        "ref" => "SPEC.md §8",
-      },
-    }.freeze
-
-    # Curated agent-facing verb catalog. This declares which verbs the operator
-    # CLI surfaces and in what order — the editorial presentation. The summary of
-    # each verb is a fact, not presentation: it is derived from `contract.summary`
-    # at load time (ADR 0039). A literal "summary" survives here only for grouped
-    # CLI tokens (schema/key/rule/hook) that aggregate several sub-contracts and so
-    # have no single contract to derive from. CLI_VERBS itself is assigned in
-    # textus.rb after Zeitwerk eager_load so all contract files are present.
-    CURATED_CLI_VERBS = [
-      { "name" => "boot" },
-      { "name" => "list" },
-      { "name" => "get" },
-      { "name" => "ingest" },
-      { "name" => "where" },
-      { "name" => "schema", "summary" => "schema operations: 'schema show KEY', 'schema diff', 'schema init', 'schema migrate'" },
-      { "name" => "put" },
-      { "name" => "propose" },
-      { "name" => "accept" },
-      { "name" => "enqueue" },
-      { "name" => "key", "summary" => "key operations: 'key delete', 'key mv', 'key uid'" },
-      { "name" => "drain" },
-      { "name" => "audit" },
-      { "name" => "blame" },
-      { "name" => "rule", "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },
-      { "name" => "doctor" },
-      { "name" => "jobs" },
-      { "name" => "pulse" },
-    ].freeze
-
-    def self.contract_summaries
-      Textus::VerbRegistry.registered.to_h { |s| [s.verb.to_s, s.summary] }
-    end
-
-    # Build the CLI verb catalog: each summary is derived from its contract when
-    # one exists, falling back to the curated editorial string for grouped tokens
-    # (schema/key/rule/hook). Called once from textus.rb after eager_load.
-    def self.build_cli_verbs
-      summaries = contract_summaries
-      CURATED_CLI_VERBS.map do |entry|
-        derived = summaries[entry["name"]]
-        derived ? entry.merge("summary" => derived) : entry
-      end
-    end
-
-    def self.build(container:)
-      etag       = Textus::Value::Etag.for_contract(container.root)
-      latest_seq = container.audit_log.latest_seq
-      artifact   = read_artifact_content(container, "artifacts.boot")
-      context    = read_boot_context(container)
-
-      # Prefer pre-computed artifact (drain computes, boot reads).
-      # Fall back to inline manifest projection for stores that have not yet
-      # run drain (test fixtures, fresh inits).
-      stable = artifact || inline_boot_content(container.manifest, latest_seq)
-
-      if stable["agent_quickstart"]
-        stable = stable.merge(
-          "agent_quickstart" => stable["agent_quickstart"].merge("latest_seq" => latest_seq),
-        )
-      end
-
-      payload = {
-        "protocol" => PROTOCOL_ID,
-        "store_root" => container.root,
-        "contract_etag" => etag,
-      }.merge(stable)
-      payload["context"] = context if context
-      payload
-    end
-
-    def self.inline_boot_content(manifest, _latest_seq)
-      agent_role     = manifest.policy.proposer_role
-      writable_lanes = manifest.data.declared_lane_kinds.keys.each_with_object([]) do |ln, acc|
-        next unless agent_role
-
-        verb    = manifest.policy.verb_for_lane(ln)
-        writers = manifest.policy.roles_with_capability(verb)
-        acc << ln if writers.include?(agent_role)
-      end
-
-      {
-        "lanes" => lanes_for(manifest),
-        "agent_quickstart" => {
-          "read_verbs" => Textus::Surface::MCP::Catalog.read_verbs,
-          "write_verbs" => agent_role ? Textus::Surface::MCP::Catalog.write_verbs : [],
-          "writable_lanes" => writable_lanes,
-          "propose_lane" => manifest.policy.propose_lane_for(agent_role),
-        },
-        "agent_protocol" => agent_protocol(manifest),
-      }
-    end
-
-    def self.agent_protocol(manifest)
-      queue = manifest.policy.queue_lane
-      feeds = lane_label(manifest, :machine, "the machine lane")
-      AGENT_PROTOCOL_TEMPLATE.merge(
-        "recipes" => {
-          "read" => { "purpose" => "find and read an entry",
-                      "steps" => ["list (lane:, prefix:) — discover keys", "get KEY — returns the entry envelope"] },
-          "write" => { "purpose" => "create or update an entry",
-                       "steps" => ["schema KEY — learn field shape", "put KEY — persist it (role-gated)"] },
-          "propose" => { "purpose" => "agent suggests a change for human review",
-                         "agent_steps" => ["propose KEY — writes to #{queue} lane"],
-                         "human_steps" => ["accept #{queue}.KEY — promotes to target lane"] },
-          "drain" => { "purpose" => "keep machine lanes fresh",
-                       "steps" => ["pulse — stale list names overdue entries",
-                                   "drain (lane: #{feeds}) — re-pull stale entries"] },
-        },
-        "role_resolution" => {
-          "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, " \
-                       "then a transport default ('human' for CLI, 'agent' for MCP)",
-          "roles" => manifest.data.role_caps.keys,
-          "ref" => "SPEC.md §5",
-        },
-      )
-    end
-
-    def self.lanes_for(manifest)
-      manifest.data.declared_lane_kinds.keys.map do |name|
-        verb = manifest.policy.verb_for_lane(name)
-        row  = { "name" => name, "writers" => manifest.policy.roles_with_capability(verb) }
-        kind = manifest.policy.declared_kind(name)
-        row["kind"] = kind.to_s if kind
-        purpose = manifest.data.lane_descs[name]
-        row["purpose"] = purpose if purpose && !purpose.empty?
-        row
-      end
-    end
-
-    def self.read_artifact_content(container, key)
-      res = container.manifest.resolver.resolve(key)
-      return nil unless res.path && File.exist?(res.path)
-
-      env = Textus::Store::Entry::Reader.from(container: container).read(key)
-      env&.content
-    rescue Textus::Error
-      nil
-    end
-
-    def self.read_boot_context(container)
-      res = container.manifest.resolver.resolve("knowledge.boot")
-      return nil unless res.path && File.exist?(res.path)
-
-      env = Textus::Store::Entry::Reader.from(container: container).read("knowledge.boot")
-      body = env&.body&.strip
-      body.nil? || body.empty? ? nil : body
-    rescue Textus::Error
-      nil
-    end
-  end
-end

data/lib/textus/dispatch/contracts.rb

@@ -1,63 +0,0 @@
-module Textus
-  module Dispatch
-    module Contracts
-      GetEntry = Data.define(:key)
-
-      PutEntry = Data.define(:key, :meta, :body, :content, :if_etag)
-
-      ListKeys = Data.define(:prefix, :lane, :q, :schema)
-
-      DeleteKey = Data.define(:key, :if_etag)
-
-      MoveKey = Data.define(:old_key, :new_key, :if_etag, :dry_run)
-
-      ProposeEntry = Data.define(:key, :meta, :body, :content)
-
-      AcceptProposal = Data.define(:pending_key)
-
-      RejectProposal = Data.define(:pending_key)
-
-      EnqueueJob = Data.define(:type, :args)
-
-      AuditEntries = Data.define(:key, :lane, :role, :verb, :since, :seq_since, :correlation_id, :limit)
-
-      PulseEntries = Data.define(:since)
-
-      BlameEntry = Data.define(:key, :limit)
-
-      WhereEntry = Data.define(:key)
-
-      UidEntry = Data.define(:key)
-
-      DepsEntry = Data.define(:key)
-
-      RdepsEntry = Data.define(:key)
-
-      BootStore = Data.define
-
-      DoctorStore = Data.define(:checks)
-
-      PublishedEntries = Data.define
-
-      RuleExplain = Data.define(:key, :detail)
-
-      RuleList = Data.define
-
-      SchemaEnvelope = Data.define(:key)
-
-      DrainStore = Data.define(:prefix, :lane)
-
-      IngestEntry = Data.define(:kind, :slug, :url, :path, :lane, :label)
-
-      JobsAction = Data.define(:state, :action, :job_id)
-
-      RuleLint = Data.define(:candidate_yaml)
-
-      DataMv = Data.define(:from, :to, :dry_run)
-
-      KeyMvPrefix = Data.define(:from_prefix, :to_prefix, :dry_run)
-
-      KeyDeletePrefix = Data.define(:prefix, :dry_run)
-    end
-  end
-end

data/lib/textus/dispatch/handler_registry.rb

@@ -1,21 +0,0 @@
-module Textus
-  module Dispatch
-    class HandlerRegistry
-      def initialize
-        @handlers = {}
-      end
-
-      def register(command_class, handler)
-        @handlers[command_class] = handler
-      end
-
-      def for(command_class)
-        @handlers[command_class] || raise("no handler registered for #{command_class}")
-      end
-
-      def registered?(command_class)
-        @handlers.key?(command_class)
-      end
-    end
-  end
-end