@agentskit/harness 0.1.0

package/docs/ADR-0001-extensible-kernel.md

@@ -0,0 +1,41 @@
+# ADR-0001: Extensible kernel with append-only run events
+
+- Status: accepted
+- Date: 2026-08-29
+
+## Context
+
+The harness must work with different coding agents, repositories, browsers,
+databases, documentation systems, and tracking providers without moving its
+completion guarantees into optional integrations. A mutable summary alone is
+also insufficient for diagnosing retries and stale evidence.
+
+## Decision
+
+Keep the contract, lifecycle transitions, evidence validation, source binding,
+staleness rules, approval boundaries, and security checks in the kernel. Expose
+an in-process, typed plugin registry for optional capabilities. Plugins declare
+their API version and dependencies, contribute through named typed slots, and
+are cleaned up deterministically.
+
+Persist lifecycle facts as append-only NDJSON under each run. `run.json` remains
+the compatible projection used by the current CLI; event records carry the run
+ID, source revision, and contract hash so projections and diagnostics can be
+checked against the same execution.
+
+## Constraints
+
+- No remote plugin installation, hot reload, marketplace, or distributed event
+  store is part of this decision.
+- A plugin cannot approve a run or bypass kernel evidence validation.
+- Event records are appended by the harness and rejected when malformed or out
+  of order.
+- Doc Bridge, Playbook profiles, browser adapters, and SCM integrations are
+  consumers of this seam, not kernel dependencies.
+
+## Consequences
+
+The public API can grow by adding typed slots and event payloads while the
+existing CLI and JSON projection remain stable. The current event log records
+run creation and state transitions; check-level event types and remote stores
+can be added when a measured diagnostic need justifies them.

package/docs/ADR-0002-profiles-and-context.md

@@ -0,0 +1,22 @@
+# ADR-0002: Profiles and optional context providers
+
+- Status: accepted
+- Date: 2026-08-29
+
+## Decision
+
+Verification contracts may define named profiles. A selected profile resolves
+its parent chain deterministically, then overlays budgets, cleanup roots, and
+existing checks by ID before validation and contract hashing. Missing profiles,
+cycles, and unknown check IDs fail closed.
+
+Context retrieval is an optional typed plugin slot. A provider returns a query,
+references, content provenance, and a snapshot hash. Doc Bridge and Playbook
+adapters can use the seam without becoming kernel dependencies.
+
+## Boundaries
+
+Profiles cannot bypass required checks or human approval. Providers cannot
+approve runs, alter evidence validation, or silently replace the frozen
+contract. Remote provider discovery, credential management, and context cache
+policy remain integration concerns.

package/docs/ADR-0003-doc-bridge-context-binding.md

@@ -0,0 +1,36 @@
+# ADR-0003: Bind optional Doc Bridge context to a run
+
+- Status: accepted
+- Date: 2026-08-29
+
+## Decision
+
+The harness provides a dependency-free `createDocBridgeContextProvider` adapter
+that reads the local `.doc-bridge/index.json` contract. It returns at most
+eight deterministic references, carries the index `contentHash` as source
+provenance, and computes a stable snapshot hash.
+
+`planRun` accepts resolved context snapshots and freezes them into `run.json`
+with a `contextHash`. The lifecycle log records one `context.attached` event per
+snapshot. Resolution timestamps remain audit metadata and are excluded from the
+reproducibility hash.
+
+Shell-based agents use the same wire boundary with `context resolve` and
+`plan --context-file`. A context file contains one snapshot or an array of
+snapshots, allowing another provider to participate without a dynamic runtime
+loader.
+
+The file loader verifies the snapshot hash before planning. This makes the
+portable handoff tamper-evident while leaving provider-specific source
+provenance and authorization at the provider boundary.
+
+The kernel applies the same verification to snapshots supplied directly to
+`planRun`, so typed callers cannot bypass the integrity boundary.
+
+## Boundaries
+
+The adapter does not install or import Doc Bridge, access remote services, or
+refresh context after planning. A caller owns query selection and must resolve
+context before the contract is verified. Index schema validation and richer
+semantic search remain responsibilities of Doc Bridge; malformed or missing
+indexes fail the adapter closed.

package/docs/ADR-0004-run-metrics.md

@@ -0,0 +1,29 @@
+# ADR-0004: Derive benchmark metrics from immutable run projections
+
+## Status
+
+Accepted
+
+## Context
+
+The harness needs to measure improvement across repeated development runs without
+introducing a database or a remote telemetry service. Each run already stores its
+source, contract, checks, evidence, lifecycle state, approval, retry lineage,
+and duration.
+
+## Decision
+
+Expose `benchmarkRuns(stateDir)` and the `ak-harness benchmark` command. They
+read the historical `run.json` projections, sort by run ID, and emit a versioned
+JSON report with per-run facts and aggregate rates for checks, outcomes, evidence,
+approvals, retries, stale runs, and duration.
+
+## Consequences
+
+- Metrics are local, reproducible, portable, and usable without a service.
+- Historical reports can be committed or exported by CI when the project wants a
+  trend record.
+- The report measures harness execution and review friction; it does not claim
+  developer productivity or causality without a controlled task benchmark.
+- A future remote metrics store can consume this versioned report without changing
+  the verification kernel.

package/docs/ADR-0005-benchmark-manifest.md

@@ -0,0 +1,27 @@
+# ADR-0005: Use explicit benchmark manifests and task bindings
+
+## Status
+
+Accepted
+
+## Context
+
+Run IDs identify executions, not the task being measured. Comparing harness
+performance requires a stable task corpus and an honest baseline. A missing
+baseline must not be silently inferred from harness history.
+
+## Decision
+
+Add a versioned benchmark manifest containing task IDs, titles, acceptance
+criteria, and optional baseline observations. Verification contracts may bind a
+run to a suite and task ID. The benchmark report compares only bound harness runs
+with explicit, non-`not-run` baseline observations and reports the rest as
+non-comparable.
+
+## Consequences
+
+- Multiple runs can be grouped as attempts of one task.
+- Baseline provenance is visible and reviewable.
+- The first corpus can be committed without fabricating baseline data.
+- Controlled task execution and baseline collection remain a later phase; this
+  schema provides the stable seam now.

package/docs/ADR-0006-agent-session-protocol.md

@@ -0,0 +1,36 @@
+# ADR-0006: Record agent sessions through a protocol-first seam
+
+## Status
+
+Accepted
+
+## Context
+
+The harness must make agent work observable without coupling the kernel to a
+specific model, runtime, tool host, or provider. It also must not turn prompts,
+tool arguments, results, or chain-of-thought into persisted application data.
+
+## Decision
+
+Expose a small `AgentAdapter` descriptor and `createSessionRecorder` API. The
+recorder accepts hashes and metadata, writes correlated session, turn, and tool
+events to the existing append-only run log, and rejects invalid local ordering.
+It can start only from `IMPLEMENTING`; with `resume: true`, it reconstructs
+unfinished actions from the event log and emits a `session.resumed` event. A
+persisted `tool.execution.started` event marks an unfinished action as
+ambiguous; resumption requires an explicit human `retry` or `abandon` decision
+through `recoverTool` before the runtime can be entered again. It does not
+execute tools or make policy decisions.
+
+## Consequences
+
+- Any coding agent can implement the descriptor without importing an agent SDK.
+- Session evidence is reproducible and correlated by run, session, turn, and
+  action IDs.
+- Raw content stays outside the harness event log.
+- An interrupted process can resume pending approvals and actions without
+  replaying completed tools or bypassing the policy gate.
+- An interrupted action that may have reached an external runtime is fail-closed
+  until a human explicitly chooses retry or abandonment.
+- A later policy gate or runtime adapter can consume this protocol without
+  changing the verification kernel.

package/docs/ADR-0007-policy-gate.md

@@ -0,0 +1,33 @@
+# ADR-0007: Gate tool actions with ordered deny-by-default policy
+
+## Status
+
+Accepted
+
+## Context
+
+The session protocol observes tool calls, but observation alone cannot prevent
+an unsafe or out-of-scope action from reaching a runtime. The kernel needs a
+portable control point that works before provider-specific tool execution.
+
+## Decision
+
+Require every `SessionRecorder` to receive a typed `PolicyGate`. The built-in
+`createPolicyGate` evaluates ordered exact-tool rules, uses the first match,
+and blocks by default when no rule allows the tool. Rules may allow, block, or
+require human approval. Each decision is recorded; approval-required attempts
+cannot enter the pending execution lifecycle until a human approves them.
+
+The gate receives hashes and identifiers only. It does not execute tools,
+inspect raw arguments, or approve the overall task.
+
+## Consequences
+
+- A tool cannot be requested through the public session API without a policy
+  decision.
+- Sensitive tools can pause for an explicit human decision before execution.
+- Policy behavior is deterministic, inspectable, and provider-independent.
+- Rejected or unresolved approvals remain fail-closed and generate an audit
+  trail without storing raw prompts, arguments, or results.
+- Existing integrations must provide an explicit allowlist or their tools are
+  blocked by default.

package/docs/ADR-0008-runtime-executor.md

@@ -0,0 +1,33 @@
+# ADR-0008: Execute allowed actions through a bounded runtime seam
+
+## Status
+
+Accepted
+
+## Context
+
+The policy gate can decide whether a tool action is allowed, but the session
+protocol still needs a portable way to execute that action and close it with
+reproducible evidence. Tool providers differ widely, so the kernel must not
+depend on a shell, MCP host, model SDK, or container runtime.
+
+## Decision
+
+Require every `SessionRecorder` to receive a `ToolRuntime`. The built-in
+runtime dispatches to explicitly registered handlers, propagates an
+`AbortSignal`, applies a timeout, hashes successful results, and returns
+structured failures for missing tools, exceptions, and timeouts. The recorder
+invokes it only after a policy allow decision and converts the result into the
+existing `tool.completed` or `tool.failed` event.
+
+The built-in runtime is in-process. It is an execution boundary, not a hard
+security sandbox; isolated process or container runtimes remain provider
+adapters for a later phase.
+
+## Consequences
+
+- Runtime handlers are portable and independently replaceable.
+- Blocked actions cannot reach a handler through the public session API.
+- Raw arguments and results remain in memory only; the event log stores hashes.
+- Timeouts bound the recorder's wait, but a handler that ignores abort cannot be
+  force-killed by an in-process runtime.

package/docs/ADR-0009-process-runtime-boundary.md

@@ -0,0 +1,34 @@
+# ADR-0009: Add a bounded shell-free process runtime
+
+## Status
+
+Accepted
+
+## Context
+
+An in-process handler is useful for adapters, but it cannot be killed if it
+ignores abort and is not an isolation boundary for untrusted code. The harness
+needs a portable process seam for commands that require stronger lifecycle
+control without pretending that every host has a container runtime.
+
+## Decision
+
+Expose `createProcessToolRuntime`. Each tool has a fixed executable, argument
+list, optional working directory, and explicit environment. The runtime uses
+`spawn` with `shell: false`, sends one JSON request over stdin, kills timed-out
+or oversized children, and returns only hashed stdout or structured failure
+metadata.
+
+Recovery closes the failed action and requires a fresh policy-approved action;
+the harness does not automatically replay potentially side-effecting tools.
+
+This is a bounded child-process boundary, not a complete security sandbox.
+Container, OS policy, filesystem, network, and credential isolation remain
+provider-specific responsibilities.
+
+## Consequences
+
+- Shell interpolation is removed from the portable process path.
+- Timeouts and output limits prevent common runaway-process failures.
+- Explicit environments reduce accidental secret inheritance.
+- Hard isolation and resource quotas require a later sandbox provider.

package/docs/ADR-0010-docker-sandbox-runtime.md

@@ -0,0 +1,32 @@
+# ADR-0010: Optional Docker sandbox runtime
+
+## Status
+
+Accepted
+
+## Context
+
+The process runtime bounds execution but does not isolate an agent tool from
+the host. Coding tasks sometimes need a stronger boundary while the harness
+must remain portable and must not require Docker for its core API.
+
+## Decision
+
+Expose `createDockerToolRuntime` as an optional provider built on the existing
+process runtime. Each tool declares a fixed image and argv; the provider never
+constructs or invokes a shell. By default it uses a cached image only, disables
+container networking, makes the root filesystem read-only, drops Linux
+capabilities, enables `no-new-privileges`, runs as an unprivileged UID, and
+applies PIDs, memory, CPU, timeout, and output limits. Host mounts are absent
+unless explicitly declared and default to read-only.
+
+## Consequences
+
+- Consumers without Docker can keep using the portable process or in-process
+  providers; Docker failures are structured runtime failures.
+- A Docker image is a trust boundary input and should be pinned by consumers
+  when reproducibility matters. `pull: 'never'` prevents an implicit network
+  fetch by default.
+- The provider is not a VM or a guarantee against a compromised Docker daemon.
+  Stronger VM, rootless, Windows, and remote sandbox providers can implement
+  the same `ToolRuntime` seam later without changing the kernel.

package/docs/ADR-0011-runtime-attestation.md

@@ -0,0 +1,30 @@
+# ADR-0011: Runtime attestation in tool evidence
+
+## Status
+
+Accepted
+
+## Context
+
+A sandbox result hash proves what the tool returned, but not which image or
+limits produced it. Enterprise review needs to correlate terminal tool events
+with the exact runtime profile used for that action.
+
+## Decision
+
+Runtime providers may attach typed runtime evidence to completed or failed tool
+results. The Docker provider resolves the local image ID before execution,
+hashes the effective profile plus that ID, and carries the attestation into the
+terminal event. Missing images or an unavailable daemon fail before execution.
+
+The evidence is descriptive and bound to the harness event's run, source
+revision, and configuration hash; it is not a claim that the Docker daemon or
+host kernel is trustworthy.
+
+## Consequences
+
+- Reviewers can identify the provider, image digest, security profile, and
+  resource limits for each action without storing raw command output.
+- Custom runtimes remain compatible because runtime evidence is optional.
+- Future VM or remote providers can publish their own typed evidence without
+  changing the session protocol.

package/docs/ADR-0012-controlled-baseline-observations.md

@@ -0,0 +1,27 @@
+# ADR-0012: Record controlled baseline observations through the public interface
+
+## Context
+
+The harness already aggregates run history, but a benchmark comparison is only
+meaningful when the baseline is real, attributable, and tied to the same task
+identity. Manual JSON editing is easy to get wrong and makes the measurement
+process hard to reproduce.
+
+## Decision
+
+Expose `recordBenchmarkObservation` and `ak-harness benchmark baseline` as the
+single supported write path for one baseline observation per task. The API
+validates the manifest and observation, rejects unknown tasks and duplicates,
+and writes through a temporary file followed by an atomic rename. It also
+checks that the source manifest did not change during the operation.
+
+`not-run` remains an explicit non-comparable status. The benchmark report must
+not infer a baseline from harness history or report improvement without both a
+valid baseline and a bound harness run.
+
+## Consequences
+
+- Baselines have a reproducible CLI/API entry point and visible provenance.
+- Concurrent or stale writes fail instead of silently overwriting newer data.
+- A controlled task run is still required; this API records evidence but does
+  not manufacture experimental results.

package/docs/ADR-0013-honest-benchmark-comparability.md

@@ -0,0 +1,27 @@
+# ADR-0013: Require completed evidence for benchmark comparability
+
+## Context
+
+An explicit baseline is necessary but not sufficient for a meaningful
+comparison. A blocked or still-running harness attempt must not be presented as
+an achieved result, and aggregate pass rates alone do not explain why a task is
+or is not comparable.
+
+## Decision
+
+`benchmarkRuns` reports a task as comparable only when it has a baseline whose
+status is not `not-run` and the latest bound harness run is `COMPLETE`. Every
+other case has a typed reason: missing baseline, not-run baseline, harness not
+run, or harness not complete.
+
+The comparison also exposes the latest harness check, outcome, evidence,
+duration, attempt, and human-review metrics. Human-review duration is derived
+only when approval is recorded. The report remains descriptive; it does not
+claim causality or productivity improvement.
+
+## Consequences
+
+- A blocked or partial attempt cannot inflate the comparison dataset.
+- Reviewers can distinguish missing evidence from failed execution.
+- Future statistical analysis has stable inputs without changing the run
+  protocol.

package/docs/ADR-0014-criterion-level-benchmark-evidence.md

@@ -0,0 +1,24 @@
+# ADR-0014: Criterion-level benchmark evidence
+
+## Context
+
+Scalar baseline numbers do not prove that a benchmark task exercised its
+acceptance criteria. Treating those numbers as comparable can make an
+incomplete delivery look like an improvement.
+
+## Decision
+
+Baseline observations may include an `evidence` array. Each entry names one
+acceptance criterion exactly, records its status, and points to a source. The
+manifest validator rejects unknown or duplicate criteria and invalid evidence
+metadata. A comparison is `comparable` only when every criterion is covered,
+the baseline is not `not-run`, and the latest bound harness run is `COMPLETE`.
+The report exposes `baselineEvidenceCoverageRate` and returns
+`baseline-evidence-missing` when coverage is incomplete.
+
+## Consequences
+
+Baseline collection has a small additional input requirement, but benchmark
+reports can distinguish missing proof from a real completed comparison. The
+evidence source remains a reference; this phase does not claim causality or
+replace criterion-level harness evidence for the current run.

package/docs/ADR-0015-directional-benchmark-outcomes.md

@@ -0,0 +1,23 @@
+# ADR-0015: Directional benchmark outcomes
+
+## Context
+
+The harness already reports raw deltas, but a negative duration delta is easy
+to misread and non-comparable tasks can be mistaken for missing data. Operators
+need a small, explicit interpretation layer for the measured resources.
+
+## Decision
+
+For comparable tasks, report a rate for duration, attempts, and human review:
+`(baseline - harness) / baseline`. Positive means the harness used less of the
+resource and is labelled `improved`; negative is `regressed`; zero is
+`unchanged`. A missing value, zero baseline, or non-comparable task is labelled
+`unavailable`. These are per-resource signals, not a composite productivity
+score or a causal claim.
+
+## Consequences
+
+Benchmark consumers can read the direction without reimplementing arithmetic,
+while trade-offs remain visible instead of being hidden in one score. A real
+baseline with complete criterion evidence is still required before any outcome
+is reported as comparable.

package/docs/ADR-0016-baseline-evidence-digests.md

@@ -0,0 +1,21 @@
+# ADR-0016: Baseline evidence digests
+
+## Context
+
+Criterion coverage and directional metrics can still be detached from the
+exact JSON input used during baseline collection. Without a digest, a later
+review cannot distinguish the recorded evidence file from a changed copy.
+
+## Decision
+
+When `ak-harness benchmark baseline` reads `--evidence-file`, it computes and
+stores the file's lowercase SHA-256 digest in `evidenceDigest`. Manifest
+validation accepts only a 64-character lowercase SHA-256 value. The digest is
+of the evidence file content, not of the external artifact named by each
+criterion source.
+
+## Consequences
+
+The baseline record is tamper-evident with respect to its input file and can be
+replayed from the same bytes. External systems remain an explicit integration
+boundary; their content verification is not claimed by the local harness.

package/docs/ADR-0017-event-log-integrity.md

@@ -0,0 +1,25 @@
+# ADR-0017: Hash chained lifecycle event logs
+
+## Context
+
+The lifecycle log already preserves order and binds events to a run revision
+and contract hash, but a later edit to an existing record would not be
+detected. Enterprise review needs a deterministic integrity signal without
+persisting prompts, tool arguments, or adding a remote service.
+
+## Decision
+
+New events include `previousHash` and `eventHash`. The hash covers the exact
+serialized event body, including the preceding hash, so changing or reordering
+records makes the chain invalid. `FileEventStore.read` validates the chain and
+`FileEventStore.verify` exposes a typed `verified` or `legacy` result. Existing
+logs without integrity fields remain readable and are never reported as
+verified; appending to them preserves their legacy status.
+
+## Consequences
+
+The log is tamper-evident for new records and can be checked locally or through
+`ak-harness events verify`. This is not a signature or external notarization:
+an attacker able to rewrite both the log and its consumer can recompute the
+chain. A future signed export can add that trust boundary without changing the
+event lifecycle API.

package/docs/ADR-0018-verification-projection-attestation.md

@@ -0,0 +1,23 @@
+# ADR-0018: Attest verification projections before approval
+
+## Context
+
+`run.json` is a convenient projection of checks and outcomes, but it is not
+itself an immutable store. Approval must not trust a projection that was
+changed after verification while the source and contract remain unchanged.
+
+## Decision
+
+After every verification pass, the harness hashes the checks, outcomes, and
+metrics projection, persists that `verificationDigest` in `run.json`, and
+appends a `verification.completed` event carrying the same digest. Human
+approval recomputes the digest, verifies the audit log, and requires the latest
+completion event to match it.
+
+## Consequences
+
+Manual edits to the verification projection are rejected before approval while
+the existing source and contract freshness checks remain in force. The digest
+protects the local projection through the audit log; it is not a digital
+signature or external notarization. Dogfood uses the public API, and prior
+Docker sandbox evidence remains covered by the earlier runtime phase.

package/docs/ADR-0019-human-decision-attestation.md

@@ -0,0 +1,27 @@
+# ADR-0019: Record human decisions as attested lifecycle events
+
+## Context
+
+The verification result is now attested before approval, but the approval and
+tracking authorization themselves only existed in the mutable `run.json`
+projection. An audit consumer could see that a run reached `COMPLETE` without
+an immutable record of which human decision accepted the exact evidence.
+
+## Decision
+
+Record `approval.recorded` and `authorization.recorded` events in the existing
+hash-chained lifecycle log. Each event contains the decision, resulting state,
+verification digest, source revision, contract hash, and human actor; tracking
+authorization also contains its declared target. Rejections are recorded too,
+so every human terminal decision is auditable.
+
+The existing freshness and verification-attestation checks run before either
+decision is accepted. The `run.json` fields remain a convenient projection,
+but the event is the audit record.
+
+## Consequences
+
+Consumers can independently prove which verified result was approved and which
+external tracking target was authorized. Legacy logs remain readable and are
+reported as legacy until they contain the new hashed event protocol. This is an
+audit attestation, not a digital signature or external notarization.

package/docs/ADR-0020-terminal-reconciliation.md

@@ -0,0 +1,26 @@
+# ADR-0020: Reconcile terminal projections before reporting completion
+
+## Context
+
+The event log and human decision attestations protect the audit trail, but
+`run.json` is still a mutable projection. Reading it directly after approval
+could report `COMPLETE` even if its digest, decision projection, or decision
+event had been removed or changed.
+
+## Decision
+
+Expose `reconcileRun` in the public API and `ak-harness audit` in the CLI. The
+reconciliation verifies the event hash chain, event-to-run binding, current
+verification digest, and the required approval/authorization event and
+projection for terminal states. `ak-harness status` uses this same gate.
+
+Event appends use an atomic per-run lock and fail closed when another writer is
+active, preventing concurrent lifecycle operations from duplicating a sequence
+number or corrupting the append-only log.
+
+## Consequences
+
+Post-approval projection tampering and removal of a decision event fail closed
+with a harness error. Historical non-terminal projections remain inspectable;
+terminal runs from before the attestation protocol must be reverified rather
+than being treated as enterprise-grade evidence.

package/docs/ADR-0021-event-lock-recovery.md

@@ -0,0 +1,25 @@
+# ADR-0021: Explicit recovery for orphaned event-log locks
+
+## Context
+
+The per-run event-log lock prevents concurrent append and read operations from
+duplicating sequence numbers or observing a partial write. A process can still
+terminate after acquiring the lock, leaving a file that must not be removed
+automatically because another writer may still own it.
+
+## Decision
+
+Write the owning process ID and creation timestamp into every lock. Expose lock
+inspection and an explicit `human`-authorized recovery operation. Recovery is
+allowed only when the lock is older than the requested threshold and its owner
+process is no longer alive. Malformed, young, or live locks remain fail-closed.
+
+The CLI exposes this maintenance operation as `events unlock`; it never runs as
+part of normal status, verification, or append flows.
+
+## Consequences
+
+An interrupted local run can be recovered without manually deleting an audit
+artifact, while active or ambiguous locks cannot be silently bypassed. A lock
+owner PID is local-process evidence; distributed writers still require a shared
+coordination primitive outside this file store.

package/docs/ADR-0022-signed-evidence-bundle.md

@@ -0,0 +1,27 @@
+# ADR-0022: Signed portable evidence bundles
+
+## Context
+
+Hash chaining protects the local event log from accidental or casual edits,
+but a reviewer or CI system needs a portable artifact whose contents and
+provenance can be checked outside the originating workspace.
+
+## Decision
+
+`exportEvidenceBundle` packages a reconciled `COMPLETE` run, its projection,
+event log, and referenced check outputs. Each file is hashed with SHA-256 and
+the canonical bundle payload is signed with an Ed25519 private key. The key ID
+and signature travel with the bundle; `verifyEvidenceBundle` independently
+validates every file hash, the payload hash, and the signature. Callers can
+additionally provide an explicit trust store to require an active key with the
+expected identity instead of trusting the embedded public key.
+
+The bundle contains check outputs as captured, so operators must treat it as a
+potentially sensitive artifact and apply their existing retention controls.
+
+## Consequences
+
+Evidence can cross machine and CI boundaries without adding a remote service.
+Key custody remains an operator responsibility; this is a signed artifact, not
+a replacement for an enterprise KMS, certificate authority, or notarization
+service. Trust-store entries support explicit rotation and revocation.