hecks 1.4.0 → 1.5.0

data/lib/hecks/storehouse.rb

@@ -19,9 +19,11 @@ module Hecks
   # stdio — not the whole thing; a plain CLI door, an HTTP door, a second
   # transport of any shape, would sit beside it on the exact same bus,
   # sharing the same audit log and caller-identity handling, without
-  # ever needing to speak MCP. (This module used to be named `McpDoor`
-  # and live under `Facade` — that conflated the bus with its one built
-  # transport; this file is the rename, not a rewrite.)
+  # ever needing to speak MCP. (This bus is deliberately not
+  # `Facade::McpDoor` — folding it into `Facade` under that name would
+  # conflate the bus with its one built transport.)
+  #
+  # ## The surface
   #
   #   catalog  — what aggregates a domain declares, and what each can do
   #   describe — one aggregate's full command/query/refusal contract
@@ -37,6 +39,8 @@ module Hecks
   #   behaviors — run a domain's hand-curated `.behaviors` examples
   #   follow   — tail this bus's own dispatch/query/state audit log
   #
+  # ## Auditing and caller identity
+  #
   # `dispatch`/`query`/`state` each take a `summary` — the survey's "every
   # audit row carries human intent for free" — and `dispatch`/`query`
   # additionally take an optional `source:` (`SOURCE_TAGS`, the survey's
@@ -58,6 +62,8 @@ module Hecks
   # `describe`/`validate`/`domains`/`history`/`behaviors`/`events` need
   # neither — they change nothing and commit nothing to any log.
   #
+  # ## Booting is the caller's job
+  #
   # A caller hands in an already-booted `runtime`, the same division of
   # labor `Facade::CliRunner` already keeps against `bin/run`: booting a
   # domain from a path is IO the calling `bin/` script owns, this stays a
@@ -68,6 +74,8 @@ module Hecks
   # takes the domain path instead and boots it; `domains` has no
   # domain to be handed one of yet, that's what it's answering.
   #
+  # ## Built from existing doors
+  #
   # No new vocabulary otherwise. Every method here composes doors that
   # already exist — `Projector.call(:cli, ...)` for verb/question alias
   # resolution (the identical table `CliRunner` itself resolves against),
@@ -108,11 +116,19 @@ module Hecks
     # project tree.
     BOOT_ROOT = File.expand_path(ENV["HECKS_STOREHOUSE_ROOT"] || File.expand_path("../..", __dir__))
 
+    # Resolves `path` against `BOOT_ROOT` and refuses one that escapes it.
+    #
     # **Refused, not silently clamped** — a path outside `BOOT_ROOT` is either
     # an honest mistake (a relative path typed against the wrong cwd) or
     # the exact thing this check exists to catch, and both deserve the
     # same clear refusal rather than a silent rewrite to something the
     # caller didn't ask for.
+    #
+    # @param path [String, #to_s] the caller-supplied path to confine
+    # @param label [String] the argument's own name, for the refusal message
+    #   (e.g. `"domain"`, `"under"`)
+    # @return [String] `path` resolved to an absolute path under `BOOT_ROOT`
+    # @raise [Runtime::TypeMismatch] if the resolved path is outside `BOOT_ROOT`
     def confine!(path, label)
       resolved = File.expand_path(path.to_s, BOOT_ROOT)
       return resolved if resolved == BOOT_ROOT || resolved.start_with?("#{BOOT_ROOT}#{File::SEPARATOR}")
@@ -128,11 +144,22 @@ module Hecks
     # projects a whole-domain CLI or doc set makes this same assumption
     # (`Facade::CliRunner#call`'s own `bluebook = runtime.registry.
     # bluebooks.values.first`) — one `.hecksagon` names one chapter.
+    # The one bluebook this runtime booted.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @return [Bluebook::Chapter] the runtime's one loaded bluebook
+    # @raise [Runtime::NotFound] if the runtime's boot loaded no bluebook
     def bluebook_for(runtime)
       runtime.registry.bluebooks.values.first or
         raise Runtime::NotFound, "this boot loaded no bluebook"
     end
 
+    # Finds one aggregate by name on a bluebook, or refuses.
+    #
+    # @param bluebook [Bluebook::Chapter] the chapter to search
+    # @param name [String, Symbol, #to_s] the aggregate's declared name
+    # @return [Bluebook::Aggregate] the matching aggregate
+    # @raise [Runtime::NotFound] if `bluebook` declares no aggregate named `name`
     def aggregate_ir!(bluebook, name)
       bluebook.aggregate(name) or
         raise Runtime::NotFound, "#{bluebook.name} declares no aggregate named #{name.inspect} — " \
@@ -143,6 +170,13 @@ module Hecks
     # short name when it's unambiguous, the qualified `Aggregate.Verb`
     # form always. Shared here so `dispatch` and `query` (and their error
     # messages) never drift from what a human typing `bin/run` sees.
+    #
+    # @param cli [Hash{Symbol => Object}] a `Projector.call(:cli, ...)` result
+    # @param name [String, Symbol, #to_s] the command or query name, as given by the caller
+    # @param asking [Boolean] true to resolve a query (against `cli[:questions]`),
+    #   false to resolve a command (against `cli[:verbs]`)
+    # @return [Hash{Symbol => Object}] the resolved verb/question spec
+    # @raise [Runtime::NotFound] if `name` matches no known command or query
     def resolve!(cli, name, asking:)
       pool = asking ? cli[:questions] : cli[:verbs]
       key  = cli[:names][asking ? :question : :command][name]
@@ -153,6 +187,11 @@ module Hecks
       raise Runtime::NotFound, "no such #{asking ? 'query' : 'command'}: #{name.inspect} — known: #{known}"
     end
 
+    # Refuses a call with no summary.
+    #
+    # @param summary [String, nil] the caller-supplied one-line summary
+    # @return [void]
+    # @raise [Runtime::TypeMismatch] if `summary` is nil or blank
     def require_summary!(summary)
       return unless summary.nil? || summary.to_s.strip.empty?
 
@@ -160,6 +199,11 @@ module Hecks
             "a one-line summary: is required on dispatch/query/state — it is what makes an audit row legible later"
     end
 
+    # Refuses a `source:` that is not one of `SOURCE_TAGS`.
+    #
+    # @param source [String, Symbol, nil] the caller-supplied source tag
+    # @return [void]
+    # @raise [Runtime::TypeMismatch] if `source` is present and not in `SOURCE_TAGS`
     def valid_source!(source)
       return if source.nil? || SOURCE_TAGS.include?(source.to_s)
 
@@ -172,6 +216,11 @@ module Hecks
     # `role` would silently do nothing rather than bind a real caller,
     # which is worse than refusing: a caller who thinks they've
     # identified themselves and haven't deserves to be told.
+    #
+    # @param role [String, Symbol, nil] the caller's self-asserted role
+    # @param actor_id [String, nil] the caller's self-asserted identity
+    # @return [void]
+    # @raise [Runtime::TypeMismatch] if `actor_id` is given without `role`
     def valid_caller!(role, actor_id)
       return unless actor_id && role.nil?
 
@@ -193,6 +242,12 @@ module Hecks
     # is ever reached when the command declares a role and no caller is
     # bound — so an unbound `dispatch` here means either the command
     # declares no role at all, or a caller-side check let it through.
+    #
+    # @param role [String, Symbol, nil] the caller's self-asserted role; nil runs
+    #   `block` unbound
+    # @param actor_id [String, nil] the caller's self-asserted identity
+    # @yield the dispatch/query to run, bound to the caller for its duration
+    # @return [Object] the block's own return value
     def with_caller(role, actor_id, &block)
       return block.call if role.nil?
 
@@ -212,6 +267,12 @@ module Hecks
     # upstream of it. Refusing here, before `with_caller`/`dispatch` are
     # ever reached, makes the bus keep the same promise: a command whose
     # bluebook declares a role is not run through this bus without one.
+    #
+    # @param spec [Hash{Symbol => Object}] a resolved command spec (from `resolve!`),
+    #   read for `:role_gated`, `:role` and `:verb`
+    # @param role [String, Symbol, nil] the caller's self-asserted role
+    # @return [void]
+    # @raise [Runtime::Unauthorized] if `spec` is role-gated and `role` is nil
     def require_caller_for_role_gated!(spec, role)
       return unless spec[:role_gated] && role.nil?
 
@@ -231,6 +292,15 @@ module Hecks
     # kind (a bare id under one string key for :aggregate, a
     # {aggregate:, entity:} pair of keys for :entity) — this is the one
     # door back into it.
+    #
+    # @param envelope [Hash{Symbol => Object}] a normalized command request, with an
+    #   optional `:to` route and `:with` facts
+    # @param receiver [Symbol, nil] `:aggregate`, `:entity`, or nil for anything else
+    # @param legacy_receiver [Symbol, String, Hash{Symbol => Symbol, String}, nil] where
+    #   the route belongs in the flat shape: a single key for `:aggregate`, an
+    #   `{aggregate:, entity:}` pair of keys for `:entity`
+    # @return [Hash{Symbol => Object}] the facts, with the route merged in under its
+    #   legacy key(s) when `envelope` carries one
     def flatten_legacy(envelope, receiver, legacy_receiver)
       facts = envelope[:with] || {}
       return facts unless envelope.key?(:to)
@@ -247,14 +317,34 @@ module Hecks
 
     # ── the audit log `follow` reads back ───────────────────────────────
 
+    # The audit log file one domain's calls are appended to.
+    #
+    # @param domain_name [String, Symbol, #to_s] the domain name
+    # @return [String] the absolute path to that domain's JSONL log file, under
+    #   `LOG_ROOT`
     def log_path(domain_name)
       File.join(LOG_ROOT, "#{domain_name.to_s.gsub(/[^A-Za-z0-9_-]/, '_')}.jsonl")
     end
 
+    # Appends one call's outcome to its domain's audit log.
+    #
     # Never fails a real call because its own audit log couldn't be
     # written — a full disk or a permissions problem is a `follow`
     # feature going dark, not a reason to refuse the dispatch/query/
     # state call that was actually asked for.
+    #
+    # @param domain_name [String, Symbol, nil] the domain to log against; nil skips
+    #   logging entirely (a call that never resolved a bluebook)
+    # @param tool [String] which tool logged this: `"dispatch"`, `"dry_run"`,
+    #   `"query"`, or `"state"`
+    # @param summary [String, nil] the caller's one-line summary
+    # @param source [String, Symbol, nil] the caller's source tag
+    # @param outcome [Hash{Symbol => Object}] the call's own result, read for `:ok`,
+    #   `:id`, `:error` and `:events`
+    # @param verb [String, nil] the resolved verb dispatched or queried, when known
+    # @param role [String, Symbol, nil] the caller's self-asserted role
+    # @param actor_id [String, nil] the caller's self-asserted identity
+    # @return [void]
     def record!(domain_name, tool:, summary:, source:, outcome:, verb: nil, role: nil, actor_id: nil)
       return unless domain_name
 
@@ -275,6 +365,19 @@ module Hecks
     # would_succeed: false`), not a failed call. A malformed request
     # (unknown command, a bad args shape) is still a failed call
     # (`ok: false`) either way — it never reached the domain to be asked.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param command [String, Symbol] the command name, bare or qualified
+    # @param summary [String] a one-line human summary of the call, for the audit log
+    # @param args [Hash] the command's arguments
+    # @param source [String, Symbol, nil] a `SOURCE_TAGS` tag naming who is calling
+    # @param dry_run [Boolean] true to check whether the command would succeed,
+    #   without actually dispatching it
+    # @param role [String, Symbol, nil] the caller's self-asserted role
+    # @param actor_id [String, nil] the caller's self-asserted identity
+    # @return [Hash{Symbol => Object}] `:ok` plus, on success, `:id`/`:state`/`:events`
+    #   (a real dispatch) or `:would_succeed`/`:error` (a dry run); on refusal, the
+    #   shape `refused` returns
     def dispatch(runtime:, command:, summary:, args: {}, source: nil, dry_run: false, role: nil, actor_id: nil)
       bluebook = bluebook_for(runtime)
       tool     = dry_run ? "dry_run" : "dispatch"
@@ -290,6 +393,24 @@ module Hecks
       outcome
     end
 
+    # Validates and dispatches one command, real or dry-run.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param bluebook [Bluebook::Chapter] the domain's one loaded chapter
+    # @param command [String, Symbol] the command name, bare or qualified
+    # @param summary [String, nil] a one-line human summary of the call
+    # @param args [Hash] the command's arguments, JSON-shaped
+    # @param source [String, Symbol, nil] a `SOURCE_TAGS` tag naming who is calling
+    # @param dry_run [Boolean] true to check whether the command would succeed,
+    #   without actually dispatching it
+    # @param role [String, Symbol, nil] the caller's self-asserted role
+    # @param actor_id [String, nil] the caller's self-asserted identity
+    # @return [Hash{Symbol => Object}] the outcome from `real_dispatch`/`dry_run_outcome`,
+    #   merged with `:verb`
+    # @raise [Runtime::TypeMismatch] if `summary`, `source`, or `actor_id` without
+    #   `role` is invalid
+    # @raise [Runtime::NotFound] if `command` names no known command
+    # @raise [Runtime::Unauthorized] if `command` is role-gated and `role` is nil
     def perform_dispatch(runtime, bluebook, command, summary, args, source, dry_run, role, actor_id)
       require_summary!(summary)
       valid_source!(source)
@@ -307,6 +428,14 @@ module Hecks
       result.merge(verb: spec[:verb])
     end
 
+    # Dispatches one command for real and shapes its result for the bus.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param spec [Hash{Symbol => Object}] the resolved command spec (from `resolve!`)
+    # @param envelope [Hash{Symbol => Object}] the normalized `to:`/`with:` request
+    # @param summary [String, nil] a one-line human summary of the call
+    # @return [Hash{Symbol => Object}] `:ok`, `:summary`, `:id`, `:state` (JSON-safe,
+    #   nil for a port operation) and `:events` (name/payload pairs)
     def real_dispatch(runtime, spec, envelope, summary)
       result = runtime.dispatch_flat(spec[:verb], envelope)
       ok(summary: summary,
@@ -315,6 +444,14 @@ module Hecks
          events:  result.events.map { |event| { name: event.name, payload: Facade::JsonDoor.materialize(event.payload) } })
     end
 
+    # Checks whether one command would succeed, without dispatching it for real.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param spec [Hash{Symbol => Object}] the resolved command spec (from `resolve!`)
+    # @param envelope [Hash{Symbol => Object}] the normalized `to:`/`with:` request
+    # @param summary [String, nil] a one-line human summary of the call
+    # @return [Hash{Symbol => Object}] `:ok`, `:summary`, `:would_succeed`, and
+    #   `:error` (the refusal message) when it would not succeed
     def dry_run_outcome(runtime, spec, envelope, summary:)
       flat = flatten_legacy(envelope, spec[:receiver], spec[:legacy_receiver])
       runtime.dry_run?(spec[:verb], **flat)
@@ -323,6 +460,8 @@ module Hecks
       ok(summary: summary, would_succeed: false, error: e.message)
     end
 
+    # Dispatches a whole sequence of commands as one call.
+    #
     # **One call, many steps** — the survey's own `bin/run <domain> script`
     # shape, so an agent issuing a known sequence of commands (open an
     # account, then fund it) pays one round trip instead of N. Every step
@@ -333,6 +472,16 @@ module Hecks
     # refusing — a later step naming a record an earlier step never
     # created will refuse honestly on its own account, which is more
     # informative than silently dropping the rest of the batch.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param steps [Array<Hash>] each step's `command`/`args`, JSON-shaped
+    # @param summary [String] a one-line human summary of the whole batch
+    # @param source [String, Symbol, nil] a `SOURCE_TAGS` tag naming who is calling
+    # @param role [String, Symbol, nil] the caller's self-asserted role
+    # @param actor_id [String, nil] the caller's self-asserted identity
+    # @return [Hash{Symbol => Object}] `:ok` (true only if every step's own `:ok` was
+    #   true), `:summary` and `:results` (each step's own `dispatch` outcome); on a
+    #   refusal outside any one step, the shape `refused` returns
     def dispatch_batch(runtime:, steps:, summary:, source: nil, role: nil, actor_id: nil)
       require_summary!(summary)
       results = Array(steps).map do |raw|
@@ -345,6 +494,17 @@ module Hecks
       refused(e, summary: summary)
     end
 
+    # Answers one declared query.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param question [String, Symbol] the query name, bare or qualified
+    # @param summary [String] a one-line human summary of the call, for the audit log
+    # @param args [Hash] the query's arguments
+    # @param source [String, Symbol, nil] a `SOURCE_TAGS` tag naming who is calling
+    # @param role [String, Symbol, nil] the caller's self-asserted role
+    # @param actor_id [String, nil] the caller's self-asserted identity
+    # @return [Hash{Symbol => Object}] `:ok` and `:rows` (each JSON-safe) on success,
+    #   or the shape `refused` returns
     def query(runtime:, question:, summary:, args: {}, source: nil, role: nil, actor_id: nil)
       bluebook = bluebook_for(runtime)
       outcome  = perform_query(bluebook, runtime, question, summary, args, source, role, actor_id)
@@ -359,6 +519,20 @@ module Hecks
       outcome
     end
 
+    # Validates and answers one query.
+    #
+    # @param bluebook [Bluebook::Chapter] the domain's one loaded chapter
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param question [String, Symbol] the query name, bare or qualified
+    # @param summary [String, nil] a one-line human summary of the call
+    # @param args [Hash] the query's arguments, JSON-shaped
+    # @param source [String, Symbol, nil] a `SOURCE_TAGS` tag naming who is calling
+    # @param role [String, Symbol, nil] the caller's self-asserted role
+    # @param actor_id [String, nil] the caller's self-asserted identity
+    # @return [Hash{Symbol => Object}] `:ok`, `:rows` (each JSON-safe) and `:verb`
+    # @raise [Runtime::TypeMismatch] if `summary`, `source`, or `actor_id` without
+    #   `role` is invalid
+    # @raise [Runtime::NotFound] if `question` names no known query
     def perform_query(bluebook, runtime, question, summary, args, source, role, actor_id)
       require_summary!(summary)
       valid_source!(source)
@@ -370,12 +544,22 @@ module Hecks
       ok(summary: summary, rows: rows.map { |row| Facade::JsonDoor.materialize(row) }).merge(verb: spec[:verb])
     end
 
+    # Reads one aggregate's stored records directly, bypassing any declared query.
+    #
     # **What is actually stored** — no verb, no interpretation, the repository
     # itself. `id:` given answers one record (`NotFound` when it names
     # nothing); omitted answers every record the aggregate currently
     # holds. This is the difference `query` can't cover: a query answers a
     # declared question, and an aggregate that never declared "list
     # everything" has no query this could reuse.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param aggregate [String, Symbol] the aggregate's declared name
+    # @param summary [String] a one-line human summary of the call, for the audit log
+    # @param id [String, Object, nil] one record's identity, or nil for every record
+    # @param source [String, Symbol, nil] a `SOURCE_TAGS` tag naming who is calling
+    # @return [Hash{Symbol => Object}] `:ok` and, with `id:`, `:record`; without it,
+    #   `:count` and `:records` (each JSON-safe); or the shape `refused` returns
     def state(runtime:, aggregate:, summary:, id: nil, source: nil)
       bluebook = bluebook_for(runtime)
       outcome  = perform_state(runtime, bluebook, aggregate, summary, id)
@@ -388,6 +572,18 @@ module Hecks
       outcome
     end
 
+    # Validates and reads one aggregate's stored record(s).
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param bluebook [Bluebook::Chapter] the domain's one loaded chapter
+    # @param aggregate [String, Symbol] the aggregate's declared name
+    # @param summary [String, nil] a one-line human summary of the call
+    # @param id [String, Object, nil] one record's identity, or nil for every record
+    # @return [Hash{Symbol => Object}] `:ok` and, with `id`, `:record`; without it,
+    #   `:count` and `:records` (each JSON-safe)
+    # @raise [Runtime::TypeMismatch] if `summary` is invalid
+    # @raise [Runtime::NotFound] if `aggregate` names no known aggregate, or `id`
+    #   names no record of it
     def perform_state(runtime, bluebook, aggregate, summary, id)
       require_summary!(summary)
       ir         = aggregate_ir!(bluebook, aggregate)
@@ -405,6 +601,8 @@ module Hecks
 
     # ── the four zoom levels ─────────────────────────────────────────
 
+    # Lists every domain directory under a root.
+    #
     # **Zoom level zero** — every domain directory a root actually holds,
     # discovered rather than typed from memory. Every other tool takes
     # `domain:` as a directory it assumes the caller already knows; this
@@ -412,6 +610,12 @@ module Hecks
     # is the same predicate `domain_root`/`nearest_domain` already walk
     # up directories checking — a bare `.hecksagon` or one under
     # `bluebook/`, the two real shapes this corpus uses.
+    #
+    # @param under [String] the directory to search, relative to `BOOT_ROOT`
+    # @return [Hash{Symbol => Object}] `:ok`, `:under`, and `:domains` (each found
+    #   domain's path, relative to `BOOT_ROOT`, sorted); `:domains` is `[]` when
+    #   `under` does not exist
+    # @raise [Runtime::TypeMismatch] if `under` resolves outside `BOOT_ROOT`
     def domains(under: "examples")
       root = confine!(under, "under")
       return ok(under: under, domains: []) unless Dir.exist?(root)
@@ -422,10 +626,17 @@ module Hecks
       ok(under: under, domains: found.map { |name| File.join(under, name) })
     end
 
+    # Lists a domain's aggregates and their command/query names.
+    #
     # **Zoom level one** — every aggregate this domain declares, and every
     # command/query name each answers to, snake_cased exactly as
     # `dispatch`/`query` want it. Enough to pick a target; `describe` is
     # the next level down for what one of them actually takes.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @return [Hash{Symbol => Object}] `:ok`, `:domain`, and `:aggregates` — an Array
+    #   of `{name:, commands:, queries:}` Hashes, commands and queries sorted,
+    #   command names suffixed `!`; or the shape `refused` returns
     def catalog(runtime:)
       bluebook = bluebook_for(runtime)
 
@@ -439,12 +650,21 @@ module Hecks
       refused(e)
     end
 
+    # Answers one aggregate's (or the whole chapter's) full usage documentation.
+    #
     # **Zoom level two** — the exact same usage document a human gets from
     # `bin/docs <domain> [aggregate]` (`Projector::DocsProjector`, the
     # identical projection `Surface::AggregateDoor#docs` calls one door
     # over): every command's arguments, the states it may be issued
     # from, and every way it can refuse. `aggregate:` omitted answers the
     # whole chapter.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param aggregate [String, Symbol, nil] one aggregate's name, or nil for the
+    #   whole chapter
+    # @return [Hash{Symbol => Object}] `:ok`, `:domain` and `:docs` (the rendered
+    #   documentation); or the shape `refused` returns
+    # @raise [Runtime::NotFound] if `aggregate` names no known aggregate
     def describe(runtime:, aggregate: nil)
       bluebook = bluebook_for(runtime)
       options  = aggregate ? { aggregate: aggregate_ir!(bluebook, aggregate).hecks_name } : {}
@@ -454,6 +674,8 @@ module Hecks
       refused(e)
     end
 
+    # Boots a domain and reports whether its wiring (and, optionally, its logic) is sound.
+    #
     # **Zoom level three** — is the wiring sound at all: every bind names a
     # declared aggregate, every adapter satisfies the port it claims, the
     # default adapter is usable. `Registry#verify!` (`runtime/registry/
@@ -479,6 +701,12 @@ module Hecks
     # much "not valid" as a real wiring mismatch, and this tool exists
     # precisely so none of those ever cross a projection of this bus as
     # a crash.
+    #
+    # @param domain [String] the domain's directory path, relative to `BOOT_ROOT`
+    # @param deep [Boolean] also run `Bluebook::ModelCheck` past wiring, into logic
+    # @return [Hash{Symbol => Object}] `{ok: true, domain:, valid: true}`, plus
+    #   `:findings` (each `{kind:, severity:, subject:, message:}`) when `deep`; or
+    #   `{ok: false, domain:, valid: false, error:}` if the boot itself failed
     def validate(domain:, deep: false)
       runtime = Hecks.boot(confine!(domain, "domain"), install_facade: false)
       result  = { ok: true, domain: domain, valid: true }
@@ -497,10 +725,19 @@ module Hecks
     # ── beyond the zoom levels ──────────────────────────────────────────
 
     # The full write history, not just the current head — `bin/history`'s
-    # own logic, unchanged: an append-only-backed aggregate's `entries`,
-    # every operation that ever touched it. An aggregate bound to a
-    # non-append-only adapter (Memory, Postgres proper) answers an empty
-    # list honestly rather than pretending to a history it never kept.
+    # own logic, unchanged: every operation that ever touched the
+    # aggregate, read off its repository's own `entries`. `Registry#repository`
+    # always hands back a `Ports::Persistence::AppendOnly`-wrapped adapter,
+    # never the bare adapter, so this never needs to guard against one —
+    # what varies by adapter is only how much the wrapped `entries` itself
+    # actually holds: a fresh Memory boot honestly has none yet, and a
+    # durable adapter (Heki, Postgres, SQLite, D1) has whatever it
+    # journaled.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @return [Hash{Symbol => Object}] `:ok`, `:domain` and `:history` (each
+    #   aggregate's storage name mapped to its `journal_entries`); or the shape
+    #   `refused` returns
     def history(runtime:)
       bluebook = bluebook_for(runtime)
       entries  = bluebook.aggregates.each_with_object({}) do |aggregate, all|
@@ -513,9 +750,13 @@ module Hecks
       refused(e)
     end
 
+    # One aggregate's full append-only write history, JSON-safe.
+    #
+    # @param repository [Ports::Persistence::AppendOnly] the aggregate's repository, as
+    #   `Registry#repository` always returns it
+    # @return [Array<Hash>] each journal entry's `:operation`, `:id` and `:state`
+    #   (materialized); `[]` when the adapter has journaled nothing yet
     def journal_entries(repository)
-      return [] unless repository.is_a?(Ports::Persistence::AppendOnly)
-
       repository.entries.map { |entry| { operation: entry.operation, id: entry.id, state: Facade::JsonDoor.materialize(entry.state) } }
     end
 
@@ -526,6 +767,13 @@ module Hecks
     # itself — `target:` names a `.behaviors` file or a directory to
     # sweep, never a `runtime:`, the one other method here besides
     # `validate` that takes a path instead.
+    #
+    # @param target [String] a `.behaviors` file's path, or a directory to sweep
+    #   for every `.behaviors` file under it
+    # @return [Hash{Symbol => Object}] `:ok`, `:target`, `:files` (each file's own
+    #   `behaviors_file` shape) and `:counts` (`Behaviors.summarize`'s tally); or
+    #   the shape `refused` returns
+    # @raise [Runtime::NotFound] if `target` is nil or names no real file or directory
     def behaviors(target:)
       require_relative "behaviors"
       raise Runtime::NotFound, "no such file or directory: #{target.inspect}" unless target && File.exist?(target)
@@ -541,6 +789,11 @@ module Hecks
       refused(e)
     end
 
+    # Shapes one `.behaviors` file's own result for the bus.
+    #
+    # @param result [Behaviors::FileResult] one file's run result
+    # @return [Hash{Symbol => Object}] `:path`, `:parse_error`, and `:runs` (each
+    #   test's `description`/`status`/`message`)
     def behaviors_file(result)
       { path:        result.path,
         parse_error: result.parse_error,
@@ -555,6 +808,12 @@ module Hecks
     # dry-run call appends to (`record!`), tailed back here. Still real,
     # still cross-process — the log outlives any one door's own process —
     # just pull instead of push.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param limit [Integer, #to_i] how many of the most recent log entries to return;
+    #   clamped to at least 1
+    # @return [Hash{Symbol => Object}] `:ok`, `:domain` and `:entries` (each logged
+    #   call's own JSON entry); or the shape `refused` returns
     def follow(runtime:, limit: 20)
       bluebook = bluebook_for(runtime)
       entries  = log_lines(bluebook.name).last([limit.to_i, 1].max)
@@ -564,6 +823,11 @@ module Hecks
       refused(e)
     end
 
+    # Reads back one domain's whole audit log.
+    #
+    # @param domain_name [String, Symbol, #to_s] the domain name
+    # @return [Array<Hash>] every logged entry, parsed with Symbol keys, in log
+    #   order; `[]` if the domain has no log file yet
     def log_lines(domain_name)
       path = log_path(domain_name)
       return [] unless File.exist?(path)
@@ -586,6 +850,17 @@ module Hecks
     # `aggregate:` narrows to one aggregate; `id:` (requires
     # `aggregate:` — an id alone is not unique across aggregates)
     # narrows to one record's own events.
+    #
+    # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+    # @param aggregate [String, Symbol, nil] narrows to one aggregate's own events
+    # @param id [String, Object, nil] narrows to one record's own events; requires
+    #   `aggregate`
+    # @param limit [Integer, #to_i, nil] how many of the most recent matching events
+    #   to return; nil returns every one found
+    # @return [Hash{Symbol => Object}] `:ok`, `:domain` and `:events` (each with
+    #   `:name`, `:payload`, `:time`, `:verb` and `:id`); or the shape `refused` returns
+    # @raise [Runtime::TypeMismatch] if `id` is given without `aggregate`
+    # @raise [Runtime::NotFound] if `aggregate` names no known aggregate
     def events(runtime:, aggregate: nil, id: nil, limit: nil)
       raise Runtime::TypeMismatch, "id: requires aggregate: too — an id alone is not unique across aggregates" if id && !aggregate
 
@@ -606,6 +881,14 @@ module Hecks
     # self-contained per-entry check with nothing to share with its
     # neighbors, extracted only to keep `events` itself to the query's
     # own shape: build the filter, apply the limit, wrap the result.
+    #
+    # @param entry [Hash{Symbol => Object}] one logged audit entry
+    # @param fqn [String, nil] narrows to a dispatch whose verb starts with this
+    #   aggregate FQN; nil matches any aggregate
+    # @param id [String, Object, nil] narrows to a dispatch whose settled record has
+    #   this id; nil matches any record
+    # @return [Array<Hash>, nil] `entry`'s own events (each with `:time`, `:verb` and
+    #   `:id` merged in), or nil if `entry` isn't a matching successful dispatch
     def entry_events(entry, fqn, id)
       return unless entry[:tool] == "dispatch" && entry[:ok] && entry[:events]
       return if fqn && !entry[:verb].to_s.start_with?("#{fqn}.")
@@ -624,16 +907,29 @@ module Hecks
     # port verb) is exactly the shape this bus promises never crashes
     # through it. `dry_run_outcome` already treats it this way locally;
     # this makes every other caller of `refusal_classes` do the same.
+    #
+    # @return [Array<Class>] every exception class this bus catches and reshapes
+    #   into an honest refusal rather than letting crash through
     def refusal_classes = [Runtime::NotFound, Runtime::TypeMismatch, Runtime::WiringError, *Runtime::DOMAIN_REFUSALS]
 
+    # Builds a successful outcome Hash.
+    #
+    # @param fields [Hash{Symbol => Object}] fields to merge in alongside `ok: true`
+    # @return [Hash{Symbol => Object}] `{ok: true}` merged with `fields`
     def ok(**fields) = { ok: true }.merge(fields)
 
+    # Builds a refused outcome Hash from a caught exception.
+    #
     # **An honest refusal, not a crash** — the survey's own item #9: "an
     # explicit, structured refusal a caller can act on" rather than a
     # stack trace an agent has to parse to find the one line that
     # mattered. The domain's own refusal text travels verbatim
     # (`RefusalWording` already renders every one of these to be read),
     # this only wraps it consistently.
+    #
+    # @param error [StandardError] the caught exception, a member of `refusal_classes`
+    # @param summary [String, nil] the caller's one-line summary
+    # @return [Hash{Symbol => Object}] `{ok: false, summary:, error:}`
     def refused(error, summary: nil) = { ok: false, summary: summary, error: error.message }
   end
 end