textus 0.55.1 → 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#as(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.as(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.as(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,138 +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
-    notebook/     # 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)`.
-- **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/action/` with `def initialize(...)` (args from contract) and a `#call(container:, call:)` method; verbs are looked up in the static `Textus::Action::VERBS` table. `Container` is a `Dry::Struct` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `workflows`, `gate`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). All dispatch routes through `Gate#dispatch(spec:, inputs:, role:, correlation_id:, session:)` — the single seam that binds inputs via `Gate::Binder`, checks auth, and invokes the action. `store.as(role)` returns a `RoleScope` that forwards verbs to `Gate::dispatch`.
-- **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/action/accept.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Accept < Base
-      verb :accept
-      summary "apply a queued proposal to its target zone; requires the author capability"
-      surfaces :cli, :mcp
-      cli "accept"
-      arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
-
-      def self.call(container:, call:, pending_key:)
-        env = container.compositor.read(pending_key)
-        parsed = proposal_from(env, key: pending_key)
-        return parsed if parsed.is_a?(Dry::Monads::Result::Failure)
-
-        target = parsed[:target_key]
-        action = parsed[:proposal]["action"] || "put"
-
-        case action
-        when "put"
-          mentry = container.manifest.resolver.resolve(target).entry
-          container.compositor.write(
-            target,
-            mentry: mentry,
-            payload: Textus::Store::Envelope::Writer::Payload.new(
-              meta: env.meta["_meta"] || {},
-              body: env.body,
-              content: nil,
-            ),
-            call: call,
-          )
-        when "delete"
-          container.compositor.delete(target, call: call)
-        else
-          return Failure(code: :proposal_error, message: "unknown action: #{action}")
-        end
-
-        container.compositor.delete(pending_key, call: call)
-
-        Success("protocol" => Textus::PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action,
-                "cascade_key" => target)
-      end
-    end
-  end
-end

data/lib/textus/action/audit.rb

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "time"
-
-module Textus
-  module Action
-    class Audit < Base
-      verb :audit
-      summary "Query the audit log with optional filters."
-      surfaces :cli
-      cli "audit"
-      arg :key, String, required: false, description: "filter to rows for this key"
-      arg :lane, String, required: false, description: "filter to keys in this lane"
-      arg :role, String, required: false, description: "filter to rows written under this role"
-      arg :verb, String, required: false, description: "filter to rows for this verb"
-      arg :since, String, required: false,
-                          coerce: ->(s) { Textus::Action::Audit.parse_since(s, now: Time.now) },
-                          description: "ISO-8601 timestamp or relative offset (e.g. 1h, 30m)"
-      arg :seq_since, Integer, required: false, description: "return rows with seq > this cursor value"
-      arg :correlation_id, String, required: false, description: "filter to rows with this correlation_id"
-      arg :limit, Integer, required: false, description: "maximum number of rows to return"
-      view(:cli) { |rows, _i| { "verb" => "audit", "rows" => rows } }
-
-      def self.call(container:, key: nil, lane: nil, role: nil, verb: nil, since: nil, seq_since: nil, correlation_id: nil, limit: nil, **) # rubocop:disable Metrics/ParameterLists
-        audit_log = container.audit_log
-        manifest = container.manifest
-
-        cursor_check = check_cursor_expiry(seq_since, audit_log)
-        return cursor_check if cursor_check.is_a?(Dry::Monads::Result::Failure)
-
-        Success(audit_log.scan(
-          seq_since: seq_since,
-          key: key,
-          role: role,
-          verb: verb,
-          correlation_id: correlation_id,
-          limit: limit,
-        ).select do |row|
-          next false if lane && !key_in_lane?(row["key"], lane, manifest)
-          next false if since && (row["ts"].nil? || Time.parse(row["ts"]) < since)
-
-          true
-        end)
-      end
-
-      def self.parse_since(str, now: Time.now.utc)
-        return nil if str.nil? || str.empty?
-        return Time.parse(str) if str =~ /\A\d{4}-\d{2}-\d{2}/
-
-        match = str.match(/\A(\d+)([smhd])\z/) or return nil
-        mult = { "s" => 1, "m" => 60, "h" => 3600, "d" => 86_400 }[match[2]]
-        now - (match[1].to_i * mult)
-      end
-
-      Query = Data.define(:key, :lane, :role, :verb, :since, :seq_since, :correlation_id, :limit) do
-        # rubocop:disable Metrics/ParameterLists
-        def self.build(key: nil, lane: nil, role: nil, verb: nil,
-                       since: nil, seq_since: nil, correlation_id: nil, limit: nil)
-          new(key:, lane:, role:, verb:, since:, seq_since:, correlation_id:, limit:)
-        end
-        # rubocop:enable Metrics/ParameterLists
-
-        def matches?(row)
-          return false if key && row["key"] != key
-          return false if role && row["role"] != role
-          return false if verb && row["verb"] != verb
-          return false if since && (row["ts"].nil? || Time.parse(row["ts"]) < since)
-          return false if seq_since && (row["seq"].nil? || row["seq"] <= seq_since)
-          return false if correlation_id && row.dig("extras", "correlation_id") != correlation_id
-
-          true
-        end
-      end
-
-      def self.check_cursor_expiry(seq_since, audit_log)
-        return unless seq_since
-
-        min = audit_log.min_available_seq
-        return unless min && seq_since < min - 1
-
-        Failure(code: :cursor_expired, message: "requested seq #{seq_since} is below minimum available #{min}",
-                details: { requested: seq_since, min_available: min })
-      end
-
-      def self.key_in_lane?(key, lane, manifest)
-        mentry = manifest.resolver.resolve(key).entry
-        mentry && mentry.lane == lane
-      rescue Textus::Error
-        false
-      end
-    end
-  end
-end

data/lib/textus/action/base.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    @registry = {}
-
-    def self.registry = @registry
-
-    def self.register(klass)
-      @registry[klass.name.gsub("::", "/").downcase] = klass
-    end
-
-    def self.fetch(type)
-      return @registry[type] if @registry[type]
-
-      match = @registry.values.find { |k| k.const_defined?(:TYPE, false) && type == k::TYPE }
-      raise Textus::UsageError.new("unknown action type: #{type}") unless match
-
-      @registry[type] = match
-    end
-
-    class Base
-      extend Contract::DSL
-      extend Dry::Monads[:result]
-
-      def self.inherited(subclass)
-        super
-        Textus::Action.register(subclass) if subclass.name
-      end
-
-      def self.call(**)
-        raise NotImplementedError.new("#{name}.call")
-      end
-
-      def self.proposal_from(env, key:)
-        proposal = env.meta&.dig("proposal") or return Failure(code: :proposal_error, message: "entry has no proposal block: #{key}")
-        target = proposal["target_key"] or return Failure(code: :proposal_error, message: "proposal missing target_key")
-        { proposal:, target_key: target }
-      end
-    end
-  end
-end

data/lib/textus/action/blame.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-require "open3"
-
-module Textus
-  module Action
-    class Blame < Base
-      verb :blame
-      summary "Annotate audit rows for a key with the git commit that introduced each file state."
-      surfaces :cli
-      cli "blame"
-      arg :key, String, required: true, positional: true, description: "entry key to blame"
-      arg :limit, Integer, required: false, description: "maximum number of audit rows to return"
-      view(:cli) { |rows, inputs| { "verb" => "blame", "key" => inputs[:key], "rows" => rows } }
-
-      def self.call(container:, key:, limit: nil, **)
-        manifest = container.manifest
-        root = container.root
-
-        audit_result = Textus::Action::Audit.call(container: container, key: key, limit: limit)
-        audit_rows = Value::Result.unwrap(audit_result)
-        path = resolve_path(key, manifest: manifest)
-        return Success(audit_rows.map { |row| row.merge("git" => nil) }) unless git_tracked?(path, root: root)
-
-        Success(audit_rows.map { |row| row.merge("git" => git_commit_at(path, timestamp: row["ts"], root: root)) })
-      end
-
-      def self.resolve_path(key, manifest:)
-        res = manifest.resolver.resolve(key)
-        mentry = res.entry
-        path = res.path
-        path || Textus::Key::Path.resolve(manifest.data, mentry)
-      rescue Textus::Error
-        nil
-      end
-
-      def self.git_tracked?(path, root:)
-        return false if path.nil?
-        return false unless File.exist?(path)
-        return false unless git_repo?(root)
-
-        _out, _err, status = Open3.capture3(
-          "git", "ls-files", "--error-unmatch", path,
-          chdir: root
-        )
-        status.success?
-      rescue Errno::ENOENT
-        false
-      end
-
-      def self.git_repo?(root)
-        dir = root
-        loop do
-          return true if File.directory?(File.join(dir, ".git"))
-
-          parent = File.dirname(dir)
-          return false if parent == dir
-
-          dir = parent
-        end
-      end
-
-      def self.git_commit_at(path, timestamp:, root:)
-        args = ["git", "log", "-1"]
-        args << "--before=#{timestamp}" if timestamp
-        args += ["--format=%H%x09%an%x09%aI%x09%s", "--", path]
-        out, _err, status = Open3.capture3(*args, chdir: root)
-        return nil unless status.success?
-
-        sha, author, date, subject = out.strip.split("\t", 4)
-        return nil if sha.nil? || sha.empty?
-
-        { "sha" => sha, "author" => author, "date" => date, "subject" => subject }
-      rescue Errno::ENOENT
-        nil
-      end
-    end
-  end
-end