Add a domain-neutral control debugger

[bigboateng]

Why

Boatstack could return a decision, but an operator could not inspect why a transition was selected, blocked, shadowed, or rejected without reconstructing the controller logic outside the runtime.

This adds Boatstack's first domain-neutral control debugger. It keeps one authoritative selector and projects an optional trace from the same evaluation that produces the decision.

What changed by layer

1. Generic kernel

• Add the versioned DecisionTrace and CandidateTrace schemas.
• Record state, program, objective, request, authority, recovery, and candidate evaluations.
• Preserve domain-provided rejection reasons instead of replacing them with generic text.
• Make Relate and RelateWithTrace use one internal relation implementation. There is no second selector or debug-only policy path.
• Cover the generic behavior with a non-software integer domain.

The control path is now:

state + program + objective + authority
                    |
                    v
              kernel.Relate
                    |
          decision + optional trace

2. Software-delivery adapter

• Project source, objective, recovery, policy, ranking, and authority evaluations into the generic trace.
• Preserve any-of and all-of authority semantics. For example, autonomy may satisfy a human-or-autonomy gate while external-provider authority remains independently required.
• Explain stale verification, source mismatch, objective mismatch, recovery incompatibility, ambiguity, frontier membership, and shadowing.
• Redact namespaced and composite facet values so explanations do not expose private plant data.

3. Read-only protocol and CLI

• Add the explain operation to the protocol and SDK.
• Add concise text output and stable JSON output:

boatstack explain --repo . --flow product-delivery --entry run
boatstack explain --repo . --flow product-delivery --entry run \
  --run-id <id> --format json

• Reuse the normal resolver and side-effect-free preflight, then stop before effect execution.
• Do not emit a prescription, admission, receipt, or idempotency artifact.
• Do not create or settle delegation state. An existing valid delegation may be read and projected only.

4. Flow authoring and Control Program IR

• Add the opt-in entry diagnostic:

diagnostics: { explain_on_suspend: true }

• Bump the Control Program schema to revision 2. This is an intentional breaking change; no revision-1 compatibility path is retained.
• Bind diagnostics into source, artifact, and generated-skill hashes while keeping the executable control-law fingerprint unchanged.

5. Generated agent UX

• Teach generated Codex and Claude entry skills to call boatstack explain with the exact flow, run, entry, and target when an opted-in entry suspends.
• State that an explanation is evidence, not authority.
• Prevent generated instructions from inventing a run, reconstructing the graph, or applying a rejected action.

6. Safety, tests, and documentation

• Add byte-for-byte repository and delegation non-interference tests.
• Add deterministic ordering, decision parity, privacy, authority, stale-program, recovery, ambiguity, and generated-skill tests.
• Document the difference between flow check, next/flow run, and explain.
• Add a release-note fragment for the new debugger.

Boundaries

• Explanations contain only facts exposed by the active domain.
• This is not whole-Flow static analysis or policy advice.
• Opaque composite values remain redacted.
• Observation may read fresh external state, but explanation cannot install a mutation manifest or execute an effect.

Verification

The unified local verification completed successfully on 2026-08-14 at 10:13:47 UTC after both automated-review passes were addressed.

• Pushed head: 7cbde2a74493cd1b23c153ae70a32c547150ea27
• Tree fingerprint: fd541e1da0a4841edddd17e3ca1d39130f8773bf

The passing matrix covers:

• Go race tests, vet, build, and all 362 isolated sharded tests
• Flow SDK TypeScript build
• 39 repository contract tests, including one expected failure
• Release-note validation
• git diff --check

The repaired capture helper drains stdout concurrently and includes a 1 MiB regression so platform pipe capacity cannot deadlock the explain test.

Automated review pass 1 found that a caller-supplied delegation receipt could survive the missing-record explain branch. The repaired trust boundary now strips all delegation-derived receipts before any lifecycle branch and re-materializes them only from a current active durable record. Its regression proves that replaying a saved receipt after deleting the record leaves explain at an authority frontier and creates no state.

Automated review pass 2 found two trace-fidelity gaps. The engine now preserves the caller-requested objective independently from the effective durable binding, including absent and ignored optional-preserve requests. Candidate text now follows the authoritative disposition and final decision, so ambiguity and deterministic preflight refusal cannot be mislabeled as preference. Focused regressions cover both paths.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[github-actions]

Codex automated review

Verdict: patch is incorrect
Confidence: 0.94

The read-only debugger can reuse stale delegation authority when the durable record is missing, producing a false control decision. A targeted regression test is sufficient; model-level verification is not recommended before merge.

Findings without inline diff anchors

[P2] Clear replayed delegation receipts when the record is missing

Invariant: delegation-derived authority must exist only while its matching durable delegation record authorizes the run. An active resolve exposes its generated delegation-* receipt in the admission; if that receipt is saved, the delegation record is then removed, and explain is invoked with the saved receipt, this branch returns before the filtering at lines 88–94. The unexpired receipt therefore reaches resolution and can make an autonomy-gated transition appear prescribed even though normal resolve/apply requires a delegation record. This is introduced by the new explain-specific early return and makes the debugger report authority that no longer exists. A regression test should issue a delegation receipt, remove the record, pass that receipt to an explain request, and assert autonomy is absent and the decision remains an authority frontier.

Confidence: 0.96

Location: boatstack/cmd/boatstack-helper/delegation_runtime.go:59-62 (RIGHT)

[bigboateng]

Addressed the first automated-review finding in 8698dd7. Delegation-derived receipts are now removed before every durable-record lifecycle branch and re-materialized only from an active matching record. The new regression saves a genuine delegation receipt, deletes the record, replays it through explain, and verifies that autonomy is absent, the decision remains an authority frontier, and no record is recreated. The full local verification matrix passed on the repaired source.

[github-actions]

Codex automated review

Verdict: patch is incorrect
Confidence: 0.98

The control decision remains enforced, but the newly added debugger emits incorrect objective and candidate-selection facts on reachable production paths. These trace-fidelity defects should be fixed before merge. Model-level verification is not recommended; focused trace and rendering regressions are sufficient.