tracegrove 0.0.0-stage → 0.3.0

package/docs/local-execution-recovery.md

@@ -0,0 +1,55 @@
+# Local acquisition recovery gate
+
+The executable local path records ownership in the existing fsynced, single-writer ProjectionLedger. Each new execution initializes `ownership:<executionId>` with its scope, immutable request digest, campaign, attempt and generation. Host and fixture reservations precede workspace acquisition/host startup or application-API create. Observed physical IDs are acknowledged before readback/steps, and cleanup moves through pending to removed only after the existing trusted host stop or registered deletion plus absence readback confirms it. Internal typed host and fixture acknowledgements remain separate: a fixture named `host.process` or `host.workspace` cannot borrow a successful host acknowledgement from the legacy public display-key arrays.
+
+No credentials or fixture request/cleanup arguments are added to this inventory. Physical resource IDs and native workspace/process identities remain private operational metadata in the existing private ledger. The owner must protect that directory.
+
+After controller interruption, redelivery of the same frozen idempotency key checks the prior inventory before admitting a new attempt. Reserved, observed or cleanup-pending entries block with `ownership_reconciliation_required`. Legacy interrupted attempts without inventory block with `ownership_inventory_missing`. Wrong request/scope/attempt/generation cannot discharge the inventory. Cleanly recorded removed inventory permits a fresh attempt through the existing admission path; an empty initialized inventory means no acquisition was reserved. Existing finalized redelivery returns its existing result without replaying effects.
+
+This is deliberately a recovery gate, not an automatic janitor. A controller crash after a real acquisition but before its acknowledgement leaves a durable reservation even if the native supervisor subsequently cleans up. No cleanup acknowledgement is invented from supervisor exit, workspace disappearance, an old PID or elapsed lease time. There is no automatic cross-process takeover/deletion or credential reconstruction, and no operator command to discharge unresolved inventory in this slice. Such cases remain blocked pending a separately reviewed reconciliation path with independent ownership and cleanup evidence. Do not edit ledger records to bypass the gate.
+
+The actual local supervisor still handles ordinary controller disconnect and cleanup. A persistence failure must not prevent best-effort cleanup of resources already known in memory; it does prevent a successful durable completion acknowledgement. A process/power loss during the ledger write inherits the ledger's existing uncertain-write and corrupt-tail behavior.
+
+Tests exercise real native acquisition and application-API fixture create in subprocesses, kill the controller before the executor receives their acknowledgements, reopen the actual persisted ledger, and prove redelivery performs no second acquisition. Other tests exercise native/sample cleanup, reservation/acknowledgement ordering, invalid cleanup transitions and foreign binding rejection. They do not qualify a remote provider, shared-resource fencing, distributed leases, machine power-loss recovery, or a durable supervisor-to-controller cleanup journal. Atomic artifact publication is a separate milestone.
+
+## Read-only recovery inspection
+
+```sh
+tracegrove recovery-status --state-dir <owned-state> --execution <execution-id> --json
+```
+
+This command reads an existing checkpoint without opening `LocalLedger` for writing. It creates
+no directories, locks or credentials, does not contact a controller, and never probes or kills a
+PID. It does not append interrupted/finalized transitions, delete resources, discharge ownership,
+sync a commit, resume a run or admit an acquisition. The existing execution path remains the
+authority for all recovery and admission decisions.
+
+The strict `tracegrove.recovery-status/v1` report includes a journal sequence/content digest,
+lock presence (not process liveness), recorded phase, counts by resource kind/state, bounded
+evidence status, static recovery guidance and an optional verified **historical** outcome.
+It omits raw journal records, resource keys, physical IDs, PIDs, paths, controller tokens,
+cleanup arguments and candidate diagnostics. The checkpoint digest identifies selected local
+bytes; it is not a signature or an admission token. The local process scope and filesystem owner
+must already be authorized to inspect the private state directory.
+
+The journal uses the same schema/sequence/version parser as the existing writer. Inspection is
+bounded to 16 MiB and 100,000 records; oversized, nonregular, linked, malformed or partial inputs
+fail closed. The directory identity, journal bytes and lock fingerprint are checked before and
+after capture and again after evidence inspection. Concurrent changes return an explicit changed
+checkpoint rather than a ready result. This is a checkpoint observation, not a promise that a
+live writer cannot change state after the command returns or confinement against hostile parent
+replacement during filesystem operations.
+
+Ownership counts describe the journal's recorded states, not newly observed absence. The
+committed-bundle path reuses the executor's exact ledger/request/selection/scope/attempt/generation/
+receipt binding checks and full bounded bundle reduction. Exit 0 means either matching finalized
+historical evidence or a recorded interrupted commit available for normal readback; exit 2 means
+another state or unavailable/invalid evidence. Every report says `actionAuthority: none`,
+`execution: not_started_by_inspection` and `verificationVerdict: not_evaluated`. Unknown cleanup
+remains unresolved even when a workspace disappeared or a controller exited. A stale lock does
+not itself record interruption; only normal trusted writer reconciliation can do that.
+
+Automatic janitor/discharge, durable supervisor acknowledgements and provider recovery remain
+separate gates. The supervisor's current `host.cleaned` message is ephemeral IPC. Adding cleanup
+authority requires bound ownership/cleanup evidence admitted by the existing exclusive ledger
+writer; this status command provides neither that evidence nor a new journal.

package/docs/local-review-store.md

@@ -0,0 +1,13 @@
+# Durable local plan review
+
+`LocalReviewStore` connects `editPlan` and `reviewPlan` to the existing `LocalLedger`. Construct it with an already opened ledger, editable-plan identity, exact scope and trusted host implementations of `authorize` and `validateSources`. Its `ports()` implements `PlanReviewPorts`; no permissive authority or source-check fallback is installed.
+
+`initialize(plan)` stores an unreviewed immutable draft at edit revision one. `stage(plan)` adds another immutable revision without changing the editable revision or current review. The staged draft gains neither approval nor execution authority. `editPlan(store.ports(), token, stagedRef)` then atomically advances editable revision and clears approval. Re-staging identical bytes is a no-op; changing bytes under the same document identity/revision is refused.
+
+Review commits recheck the current actor and policy after source checking, compare the storage version, and append the projection, review and source-validation records in one journal entry. Authorization revocation, substituted scope, missing independent validation, immutable-reference collisions and competing writers publish no losing review. Source validation is persisted with its exact plan/change-model/revision-matrix/policy bindings. Reopening the ledger recovers the review and those records together. Local collections are bounded to 500 plans, reviews and validations; exhaustion fails rather than discarding history.
+
+The journal stores private local state behind the single-writer controller lock. Writes check ownership, serialize and validate before consuming a sequence, synchronize the journal and its directory, and cache only the serialized bytes. Reads and append results are copies. An uncertain write stops both reads and writes through that handle; close it and reconcile the persisted journal before continuing. Closed handles and replaced writer ownership also refuse current-state reads. A truncated or unterminated record is retained and refuses reopening; this change never trims or repairs evidence automatically. Recovery acquires the new writer identity before recording interrupted work.
+
+This is a protected local-host adapter, not distributed fencing, a tenant ACL, a signed external issuer or a replacement for the shared OrgX authority decision. The host must protect the state directory from candidate processes and supply authenticated admission and the registered independent source checker. Do not accept local approval records as hosted authority merely because their hashes verify. No new database table, paid call, deployment or live database change is required by this adapter.
+
+Tests cover actual journal bytes, reopen recovery, concurrent review arbitration, staged edits, authorization revocation, forged actor/policy fields, missing validation, caller mutation, serialization failure, failed synchronization, replaced writer ownership and unterminated records. Source authorization/checking in the persistence tests is explicitly simulated. [Source promotion](source-promotion.md) reuses its actual approved snapshot and current-review guard. [Local scenario storage](local-scenario-store.md) supports structural transitions, registered qualification execution, result retention and explicit atomic activation. Hosted coordination acceptance, CLI lifecycle commands and activated regression execution remain open.

package/docs/local-scenario-store.md

@@ -0,0 +1,91 @@
+# Durable local scenario registration
+
+`LocalScenarioStore` implements `ScenarioPorts` on the existing `LocalLedger`.
+It persists definitions, selections, pending qualification admissions and semantic
+invalidation together. It supplies `resolveAdmission(ref, scope)` for reading an
+actual registered record, rather than accepting a producer document as registration.
+
+```ts
+const store = new LocalScenarioStore(ledger, scenarioId, scope, authority);
+await store.initialize(definition, [qualificationMatrix, selectedRound]);
+const admission = await registerQualificationRound(store.ports(), token, {
+  selectionManifestRef: selectedRound.ref,
+  stateLeaseRefs: provisionedStateLeaseRefs,
+});
+```
+
+The authenticated host must provide all three authority methods. There is no
+permissive default:
+
+- `authorize(scope, action)` checks the current owner and policy. Reads are
+  authorized too; registration/invalidation recheck authorization before publication.
+- `validateDefinition(definition)` checks the complete reviewed source, replay,
+  policy, target and matrix closure. Initialization requires the host to have
+  already authorized promotion and structural validation. It does not create an
+  approval or turn a draft into an accepted native plan.
+- `validateStateLeases(admission)` is a read-only check that the host actually
+  provisioned fresh state and can reserve the supplied leases for this admission.
+  The store does not provision resources, establish an issuer or infer freshness
+  from a caller-generated UUID. The host remains responsible for synchronizing its
+  external authority and physical lease checks with its controller.
+
+Source-derived definitions additionally require `reviewStore: reviews`, the
+`LocalReviewStore` that owns the same ledger. Its current approved source snapshot
+and synchronous fence are composed with the three host methods. Do not substitute a
+serialized approval object or a callback that only checks the review before an await.
+The fence is checked again immediately before registry writes. Qualification context
+also carries its sealed plan, review and validation into the execution bundle.
+
+Repeated identical input documents are stored once, including when the selected
+round is the qualification matrix itself. Different bytes under the same immutable
+document identity are refused.
+
+One bounded registry per scope makes lease claims atomic across scenarios sharing
+that registry. A commit checks the scenario version, exact allowed projection
+transition, complete selection/allocation, epoch and immutable definition bindings.
+It then rechecks authorization and the registry version and appends the projection
+and admission in one synced record. Competing writers publish one winner. A lease
+identity cannot be reused by changing its revision/digest or by selecting another
+scenario in the same scope. Other scopes and distributed resource pools need their
+own trusted coordination owner; this is not a tenant isolation boundary.
+
+`stage(definition, selections)` stores an immutable replacement without changing
+the current definition, epoch, approval or coverage. Re-staging identical bytes
+is a no-op. `invalidateScenario` must name a new revision of the same definition;
+it retains history, advances the epoch, clears activation authority and degrades
+the projection. Invalidation that commits while registration checks state makes
+the older registration lose its CAS. Direct port calls cannot manufacture an
+active projection or skip the epoch/version rules.
+
+Reopening the ledger recovers admission and projection together. If a commit's
+acknowledgement is lost, inspect the registered history and resolve its immutable
+admission reference. An old token conflicts; it does not register another attempt.
+Historical reads do not establish current execution or activation authority.
+Caller mutations cannot rewrite returned or stored records. Closed, ownership-lost
+or uncertain ledger handles retain the underlying ledger's refusal behavior.
+
+The prototype permits 100 scenarios, 500 total admissions and 2,000 definition/
+selection records in one registry. Exhaustion requires archival indexing; history
+is never silently dropped. The state directory must stay private to the trusted
+controller and inaccessible to candidate processes. Local hashes and projection
+states are not signatures or hosted approval receipts.
+
+The [terminal result index](qualification-results.md#durable-local-terminal-results)
+retains complete rounds through the existing result sink. The
+[activation adapter](scenario-activation.md#local-atomic-storage) publishes the active
+projection, receipt and assessment records in one scenario-registry append.
+`propose` and the [structural validation adapter](scenario-structure.md) separate
+staging a proposal from compiling its frozen execution closure and entering validating
+state. The same operation can revalidate a semantically edited, degraded definition.
+This adapter does not install physical lease provisioning, hosted source/issuer
+authorization or CLI lifecycle commands. [Source-plan promotion](source-promotion.md)
+uses actual current approved review storage to register proposed scenarios.
+[Registered qualification execution](qualification-registration.md#executing-a-registered-round)
+requires a separate authenticated runtime owner and uses the admission's allocated
+cell identities. Requests without that owner and all activated regression requests
+remain refused. A registration record cannot relabel trial evidence as qualification.
+
+Tests use real journal bytes, reopen recovery and competing operations. Host
+authentication, structural promotion and physical lease checks are explicitly
+simulated in those storage tests. No live database, paid model or OrgX decision is
+created or approved by this adapter.

package/docs/mcp-driver.md

@@ -0,0 +1,87 @@
+# Test a local MCP tool through the existing verification path
+
+Install the optional protocol adapter dependency when using MCP flows:
+
+```sh
+npm install --save-dev --save-exact @modelcontextprotocol/sdk@1.32.1
+tracegrove sample-config --sample notes-mcp --output ./mcp-notes
+tracegrove test --config ./mcp-notes/tracegrove.config.yaml
+```
+
+The core, HTTP, browser and native job startup paths do not load this peer. Planning
+an MCP flow without it reports `mcp_sdk_missing` with the installation command.
+The package pins the SDK version and lockfile integrity. This driver uses the
+[official v1 client](https://ts.sdk.modelcontextprotocol.io/client) and its
+Streamable HTTP transport. Conformance exercises the negotiated `2025-11-25`
+protocol with JSON and SSE responses. Other protocol revisions, legacy HTTP+SSE
+fallback, stdio servers, OAuth discovery and hosted targets are not qualified here.
+
+## Author a flow
+
+```yaml
+title: A created note is independently readable
+effects:
+  maxMcpCalls: 1
+  allowedMcpTools: [notes.create]
+steps:
+  - name: create
+    mcp:
+      endpoint: /mcp
+      tool: notes.create
+      arguments: {title: Protocol proof, body: Native persistence}
+    save: {noteId: structuredContent.note.id}
+    expect:
+      json: {structuredContent.note.title: Protocol proof}
+  - GET: /notes/{noteId}
+    expect:
+      status: 200
+      json: {note.title: Protocol proof}
+```
+
+MCP steps use the ordinary persona selector, saved-value bindings, deadlines and
+JSON captures. The endpoint stays on the launched application's admitted origin.
+Tool and endpoint names are frozen; only arguments can contain saved values.
+The compiler requires the tool allowlist, call ceiling, designated-write mode,
+POST permission and endpoint prefix before any host starts. A tool's
+`readOnlyHint` or other server-supplied annotation cannot grant authority.
+The ceiling bounds calls, not the number or financial cost of downstream effects.
+Use an isolated application with run-owned data and known tool effects. Hosted,
+paid, messaging and external-provider tool qualifications remain separate gates.
+MCP and HTTP can share a flow; browser/native-job combinations remain blocked
+until jointly qualified.
+
+## Results and recovery
+
+The existing planner, executor, bundle writer and independent reducer handle the
+flow. Each observation includes the tool, endpoint, negotiated protocol version,
+observed server name/version, content, structured content, `isError`, duration and
+attempt count. Server identity is self-reported protocol metadata; target source
+and runtime identity still come from the local host's attestation.
+
+The default required assertion checks `isError: false` in addition to configured
+facts. A tool error is retained as a failed step, skips dependent effects, and
+keeps potentially partial mutations unknown. An independently readable record is
+stronger evidence than the tool saying it saved one: the sample's controlled
+success-without-persistence defect fails on HTTP readback. Independent bundle
+verification uses the frozen MCP runner and typed oracle; substituting an HTTP
+runner or oracle is rejected.
+
+Each call establishes a protocol connection with the same step deadline. There is
+one tool attempt and no automatic tool replay or transport fallback. Throttling,
+connection loss, cancellation or expiry does not prove that remote work stopped.
+Potential effects remain unknown in cleanup accounting after an ambiguous call.
+Local process/workspace cleanup is confirmed separately. Inspect the native
+application before requesting another run; MCP has no generic idempotency-key or
+rollback guarantee. SDK transport reconnection is disabled.
+
+Requests and each response stream are bounded to 64 KiB. Credentials stay in
+memory, are sent only to the admitted endpoint, and cannot be expanded into tool
+arguments. Redirects are refused. Results echoing an issued bearer are withheld;
+raw protocol/provider error messages are not saved. Resource links are inert
+evidence: the driver does not fetch them, render embedded UI or call other tools.
+
+The native `notes-mcp` sample uses file-backed notes and a JSON-response subset of
+the `2025-11-25` transport. Separate tests interoperate with the official SDK server
+using JSON and SSE. These are local protocol proofs, not an actual ChatGPT/Claude
+widget-host, mobile, production authorization or complete MCP-server conformance
+claim. No inference model or external account is used in these tests.

package/docs/native-jobs.md

@@ -0,0 +1,96 @@
+# Native job bridge
+
+The `native_job` runner uses Node IPC for job submission, independent readback,
+and cancellation. HTTP remains available for fixtures and application readiness;
+an HTTP response cannot satisfy a `job.observation/1` assertion. The core,
+planner, reducer, evidence bundle, CLI, and Grove use the same frozen contracts.
+
+```sh
+tracegrove sample-config --sample report-native --output ./native-example
+tracegrove test --config ./native-example/tracegrove.config.yaml
+tracegrove ui --dir ./native-example
+```
+
+The example reuses the report-jobs application's real SQLite store and separate
+worker. It exercises duplicate delivery, a conflicting idempotency key, another
+persona's denied read, persisted output, worker-confirmed cancellation, and a
+failed job. The application and worker are stopped and their attempt-owned data
+directory removed. The native sample uses no HTTP job endpoint.
+
+## Authoring
+
+Set `app.nativeJobs: node_ipc/v1` on a Node preset. The application must implement
+the explicit handshake below; setting the option alone cannot establish a native
+capability. Declare `effects.maxJobs`; every submit invocation, including a
+duplicate or conflicting invocation, consumes one position in that ceiling.
+The compiler derives the allowed queues from the flow. Low-level corpus authors
+must supply `effects.allowedJobQueues` explicitly. Read-only envelopes refuse
+submission and cancellation. Job steps require one attempt; there is no implicit
+submission retry.
+
+```yaml
+effects: { maxJobs: 1 }
+steps:
+  - job:
+      action: submit
+      queue: reports
+      requestKey: one-report
+      payload: { title: Example, mode: succeed }
+    save: { jobId: jobId }
+    expect: { present: [jobId] }
+  - job: { action: read, queue: reports, jobId: '{jobId}' }
+    expect:
+      json: { status: succeeded, output.report.content: 'Report: Example' }
+      present: [workerId]
+```
+
+These compile to `job.submit`, `job.observe`, and `job.cancel`. Expectations
+refer to the typed job observation, using `expect.json`, `present`, `absent`, or
+`count`. HTTP status expectations are rejected. `as` uses the same attempt-issued
+persona credentials as HTTP. Credentials cross the private IPC channel and are
+excluded from protocol results and recorded observations. Provider output still
+needs the application's ordinary data-redaction policy.
+An output that echoes the issued credential is withheld with a typed adapter
+failure; the credential is not sealed into observations.
+
+The read operation polls to its step deadline. A completed readback survives a
+later timeout, so `succeeded` without the required report is an assertion failure
+with retained evidence. Cancellation or a transport failure remains a failure of
+the attempt. Request and response IDs are correlated, read/cancel results must
+name the requested job, and submitted results must retain the requested key.
+
+## Application protocol
+
+Schemas are exported through `workflow-verify/protocol` and JSON Schema:
+`workflow.native-job-{action,request,response,ready,observation}/v1`.
+The supervisor opens IPC only for an opted-in Node application and sets
+`TRACEGROVE_NATIVE_JOBS=node_ipc/v1`. After its worker/provider is ready, the
+application sends:
+
+```json
+{"kind":"tracegrove.job.ready","version":1,"queues":["reports"]}
+```
+
+It receives `tracegrove.job.request` messages with a UUID `id`, nullable
+`credential`, and a typed `command`. Commands are `submit` (queue, requestKey,
+payload), `read` (queue, jobId), or `cancel` (queue, jobId). The application owns
+credential validation, tenant isolation, idempotency, actual submission, readback,
+and cancellation semantics. It replies with the same UUID:
+
+```json
+{"kind":"tracegrove.job.response","id":"00000000-0000-4000-8000-000000000001","result":{"jobId":"example","status":"queued","requestKey":"one-report","output":null,"workerId":null}}
+```
+
+Messages are bounded to 32 KiB. Malformed, missing, oversized, mismatched, or
+late responses cannot become successful observations. Only job-namespace
+messages are forwarded from the application; application output cannot impersonate
+the supervisor's source or cleanup observations. The same supervisor owns the
+application process group, including workers, and removes its workspace when the
+controller disconnects. Snapshot-pinned launches use the same bridge from the
+private pinned source copy.
+
+This is a local Node provider seam. It does not qualify a hosted queue, a remote
+provider account, production cancellation, or distributed crash recovery. The
+handshake declares supported queues; it does not independently certify the
+provider's implementation. Python bridges and mixed browser/native-job packs
+require separate conformance work and currently block rather than downgrade.

package/docs/portable-environments.md

@@ -0,0 +1,155 @@
+# Portable environment setup — experimental foundation
+
+Use the README's single first-run quickstart before adapting your app. This document defines a
+profile/admission boundary; it does not install another runner. The executable scenario remains
+the existing case/flow with its assertions, fixtures and personas. A separate execution profile
+selects where and under what authority that same scenario runs. A host brand or a placement enum
+is not a supported capability.
+
+## Current versus needed configuration
+
+| Concern | Current executable CLI | New reusable contract / remaining integration |
+| --- | --- | --- |
+| Scenario versus placement | Short authoring config combines app setup and personas; low-level corpus separates cases, profiles, EnvironmentPlan and HostPlan | Reference-only PortableEnvironmentProfile plus per-attempt intent; profile never embeds scenario steps. Selection/compiler/CLI integration remains gated. |
+| Workspace / source / build | Native launch hashes selected source files and observes the interpreter; Git resolver freezes exact base/head | Host-resolved workspace, immutable source-selection/build/config refs. Verify actual installed dependency/build closure; a launch-file hash is not a complete installed closure. |
+| Start app alongside runner | Node, FastAPI and Django native process hosts, fresh directory/port, GET readiness; command wrapper blocked | Reuse frozen host/launch/dependency plan refs. Discover process/runtime/loopback/filesystem capabilities. No arbitrary shell execution DSL. |
+| Existing hosted staging | Declared origins and environment classes exist; general authenticated external-host execution is not wired | Resolve exact deployment and endpoint, confirm authorized access and identity, then read readiness. Never restart or tear down a borrowed deployment. Not qualified here. |
+| Endpoints | Native host reports/reserves loopback port; browser and HTTP use that observed origin | Host endpoint resolver refs distinguish owned launch, service discovery and external deployment. No embedded credential-bearing URLs, tunnels or assumed inbound access. |
+| Browser / dependencies | Chromium driver; explicit Playwright binary/system libraries. Python environments separate. Docker sample harness exists | Required versioned capabilities and pinned dependency plans; unsupported/missing features block. No automatic Docker, services, root, persistent-volume or browser-library assumption. |
+| Network | Browser/API effect envelopes constrain adapter actions; arbitrary launched app egress is not proven confined | Host-enforced policy ref, explicit allowed endpoints, inbound none/loopback. Current native host cannot attest full network containment; a strict profile must remain blocked there. No policy changes or gateway bypass. |
+| Application persona | Sample host issues attempt-local synthetic bearer tokens; adapters consume in-memory credentials | personaRef + secretRef, resolved by that environment's authorized broker. No values in scenarios/profiles/artifacts. Declaring the ref grants no access. |
+| Execution authority | Current local process runs with the environment's existing OS/sandbox permissions | Independent execution actor, policy ref and optional execution secret refs. App personas cannot grant workspace/service/admin authority. Host must validate scope/lease/operation permission. |
+| Synthetic data / reset | API fixture create/readback/reverse cleanup; isolated sample data dirs | Versioned seed/generator/namespace/reset/resource policy refs. Reset only host-resolved owned isolated resources; no production reset, global prune or database integrity replay. General DB/service provisioning is not installed. |
+| Artifacts / redaction | Local verified bundles, JSON/Markdown/JUnit, WebM and media integrity. Raw bodies/video can be private | Destination/durability/retention/redaction policy/size bound. Ephemeral hosts must prove authorized export before completion; executable redaction and general destination adapters remain unfinished. |
+| Resource/time/spend | Existing request/action deadlines and budgets; native/Docker enforcement differs; draft provider caps differ | Explicit wall/cleanup reserve, CPU/memory/disk/request/browser/provider/agent/spend limits. Host must prove enforceability, including zero calls/spend. A number in YAML is not enforced accounting. |
+| Ownership / cleanup | Scoped process/data/fixture inventory, acknowledged stop, unresolved cleanup retained | Lease/cleanup policy refs and per-attempt bindings; acquired resources only. Durable acquisition CAS/fencing, atomic artifacts, expired-lease recovery and real-provider crash/interleaving remain integration gates. |
+| Replay | Verify/play existing evidence; `test` creates fresh actions; low-level rerun preserves lineage | Explicit fresh execution, evidence playback, fresh-fixture, recorded-I/O or history mode; host-supported replay plan required. Source fixture reuse is rejected by the existing lifecycle validator. No replay engine installed. |
+| Agent output / onboarding | check/doctor/test JSON and exit codes; doctor discovers authoring projects and reports native compiled-plan provenance, dependencies and structured errors. Other top-level errors sometimes prose | SDK preflight returns typed checks, omissions, stable errors and recovery; ready is execution not started and verification not evaluated. It is not an admission token. Portable profile dispatch remains gated. |
+
+## Reference-only profiles
+
+Generated, schema-validated examples:
+
+- [App alongside runner](examples/portable-environments/alongside_runner.json)
+- [Existing staging](examples/portable-environments/external_staging.json)
+
+Every `example.*` ref is an unresolved placeholder, including its illustrative digest. Neither
+file registers a host, authorizes a target or can be passed to the current CLI config loader.
+The source is `src/authoring/environmentTemplates.ts`; `node --import tsx
+scripts/export-environment-examples.ts` regenerates them. Tests compare generated bytes/records
+and parse them through the same Zod schemas exported to JSON Schema. Do not maintain another
+handwritten environment DSL or copy credentials into these files.
+
+Recommended setup is one shared scenario tree plus one small profile selection per environment:
+`mac-local`, `coding-cloud-local`, `workflow-cloud`, and separately `authorized-staging`. Each
+selection resolves the same logical source/build/configuration refs to that host's workspace and
+resolves credential refs in that host. These names are recommendations, not installed adapters.
+Start with the native no-service API sample, then Chromium, then OrgX with its isolated dependency
+and fixture prerequisites; qualify each stage before enabling it in onboarding.
+
+For application credentials, have the environment's existing broker bind a logical secret ref
+to the intended test persona under an attempt-scoped lease. For execution permissions, separately
+bind the execution actor to an existing policy and any required execution credential refs. The
+preflight interface checks access metadata without fetching or returning secret values. Actual
+dispatch must obtain an in-memory handle from that broker and erase/revoke it at teardown. No
+universal environment-variable/token export, copied browser session, persistent credential setup
+or transfer between Mac/Codex/Claude/OrgX environments is implemented or authorized.
+
+The optional non-secret configuration ref is also host-resolved: its resolver must reject secret
+values and must not evaluate arbitrary project code during preflight. Existing `app.env` is
+serialized into frozen inputs; use it only for non-secret test configuration. Hashes/ref names are
+not an automatic secret detector or evidence-content redactor.
+
+## Read-only SDK preflight
+
+`preflightPortableEnvironment(intent, ports, {signal, timeoutMs})` resolves a self-digested frozen
+profile, validates scope and requested replay mode, and invokes bounded trusted read-only probes.
+Each observation binds the exact profile, execution/attempt/generation, actor and request digest,
+has an observed/expiry time and references host evidence. Unknown/stale/unsupported required
+capabilities block. Optional omissions remain visible. Authorization is checked before target or
+secret metadata. Errors returned by a port are never serialized into the report.
+
+The host probes inspect launch/readiness capability and existing target metadata. Preflight never
+starts a server, changes permissions, installs dependencies, issues credentials, creates fixtures,
+resets data, creates tunnels or performs cleanup. Actual post-launch readiness, identity, actions,
+artifact byte verification and cleanup need their own execution receipts. Ready preflight reports
+must be re-admitted under a live lease before effects; they are not reusable permission tokens.
+
+Examples of actionable machine output:
+
+| Code | Meaning / recovery |
+| --- | --- |
+| `capability_missing` | Install through an already authorized dependency path or choose a provisioned host; do not assume Docker/root. |
+| `persona_credential_missing` | Bind the existing logical secret reference in this host's broker. Never paste the value into a scenario. |
+| `authorization_denied` | Stop before target/secret probing; obtain owner review or select an already authorized target. Do not change permissions automatically. |
+| `network_unknown` | No observed enforcement for this policy; select a host/policy with proof, preserving current restrictions. |
+| `artifacts_missing` | Select an authorized exportable destination before an ephemeral host run. |
+| `probe_binding_mismatch` | Reject stale/cross-run, wrong actor or wrong request evidence; collect a fresh scoped observation. |
+| `preflight_deadline` / `preflight_cancelled` | Stop bounded probes; preserve the blocked report. No execution started. |
+
+The report uses `status: ready|blocked`, `exitCode: 0|2`, `checks[]` with request/state/required/
+evidenceRefs/code/recovery, `errors[]`, `execution: not_started` and
+`verificationVerdict: not_evaluated`. CLI `doctor --dir <project> --json` discovers an authoring
+config and reuses the existing compiler and planner; low-level `--config`/`--profile` remain
+supported. Its separate `tracegrove.doctor/v1` report includes selected host/corpus refs,
+source/runtime digests, dependency checks and recovery actions. Compilation writes derived
+files and interpreter version probes may run; the app never starts. Required Chromium executable
+presence is installation metadata, not a tested engine or environment qualification. No portable
+profile execution flag is advertised.
+
+## Environment acceptance and rollout
+
+1. **This slice:** frozen reference-only schemas/templates, bounded SDK probes, negative
+   conformance and README first-use checks. Synthetic probe tests establish contract behavior,
+   not host support. Independent review must challenge secret/actor separation, stale observations,
+   ignored cancellation, scope, startup-versus-staging and security/spend enforcement claims.
+2. **Native selection/onboarding:** doctor now resolves the existing native authoring/HostPlan
+   selection and reports source/runtime/dependency inspection. General portable profile dispatch
+   and host-specific missing-ref recovery remain gated; no silent policy downgrade. Repeat the clean API/browser
+   first run independently on each actual machine. Mac remains unqualified while offline.
+3. **External staging:** install a reviewed read-only external-host adapter and existing secret
+   broker integration. Prove deployment/endpoint identity and authorized test-persona access;
+   fixtures require separately scoped owned synthetic-resource authority. No denied staging retry
+   is part of this work. Do not infer support from local notes or Inspector/mock tests.
+4. **OrgX-triggered/workflow cloud:** bind an actual authorized runner/workspace/lease, discover
+   capabilities and enforce budgets/export/cleanup. Reuse existing dispatch ownership; a task
+   record is not a running verifier. Add real interruption/interleaving recovery before broader
+   resource/provider integration; keep journals/atomic-publication gates open until tested.
+
+For every claimed environment retain: clean dependency/runtime install, exact tool/source/build
+and profile pins; setup elapsed time and manual steps (including failures); fresh capability and
+authorization observations; the actual API/browser/client journey with positive/negative
+assertions; verified artifacts exported before ephemeral storage expires; owned-resource cleanup
+readback; and measured cost or explicitly unmeasured infrastructure cost. Preserve failed attempts
+and distinguish preflight, execution, verification and business acceptance. No environment becomes
+supported from templates, schemas, host brand, CI color or prose alone.
+
+Current evidence is limited to this Codex Linux cloud's isolated native/API/browser fixtures and
+the hosted Linux sample CI lanes already linked in the release audit. Actual OrgX #3620 proved a
+settings heading, #3614 a method boundary, and #3645 failed receipt lookup with unavailable offline
+workspace/store. None proves full OrgX workflow/client acceptance. Local Docker registry HTTPS
+was refused; hosted CI's Docker success is separate evidence. Claude coding cloud, Hope's Mac,
+OrgX-triggered runtime and authenticated external staging remain unqualified.
+
+## Recorded clean-room onboarding
+
+An independent AI reviewer followed only the README at source
+`3894ed6e43b32c0177be03397e22df757405ed6c` in a fresh Linux x86_64 checkout, with a new toolchain,
+dependency tree, cache and sample. Default Node 24.19.0/npm 11.9.0 required the documented optional
+bootstrap to Node 22.23.3/npm 10.9.9. The reviewer preserved PATH/cache across stateless shell
+calls; the README now explicitly recommends one shell session. No source/flow repair or
+undocumented install was needed. Observed setup through bundle verification took 39 seconds,
+including README inspection and orchestration; it is not a benchmark or measured infrastructure cost.
+
+Doctor/check, both real notes scenarios, independent API readbacks, stranger 403/empty-list,
+anonymous 401 and deletion 404 assertions passed. Original and copied evidence bundles verified
+with two receipts and no problems. Fixture/process/workspace cleanup was confirmed, with independent
+readback finding both owned process entries and workspaces absent. The private receipt and run are
+retained privately in the saved cloud environment; they are not shipped in npm. One stale “any command” table claim was corrected after review.
+The canonical executed quickstart is unchanged by that documentation correction.
+
+The automated README journey separately passed using the existing build/dependencies. Its first
+harness run misread the receipt's `critical` IDs as errors; the corrected harness requires all
+attempted and critical IDs to be confirmed. That initial harness failure receipt is preserved.
+Neither run exercises portable-profile dispatch, a browser, another cloud, Mac, authenticated
+staging or an npm registry installation. Those environment acceptance gates remain open.

package/docs/qualification-registration.md

@@ -0,0 +1,58 @@
+# Qualification registration and invalidation
+
+`registerQualificationRound` creates a sealed pending admission before execution. It requires an exact scenario revision token, a structurally validated definition, its complete frozen selection matrix and fresh leased-state refs. A new campaign and per-cell execution/attempt identities are allocated together with the next monotonic round sequence.
+
+The prototype uses `SelectionManifest` as the qualification matrix. Its policy, required case/persona/target strata and exclusions are frozen; the round selection must match them exactly. Every scenario case must retain a required matrix cell. Changed personas/targets, empty or duplicated cells, unexplained exclusions and dropped required cases are refused. The exported `qualificationStrataDigest` uses stable code-unit ordering across hosts.
+
+`ScenarioPorts` are trusted host ports, never candidate/plugin inputs. `validateDefinition` must resolve and validate the exact review, replay-contract, matrix, policy and target-profile closure. `compareAndSwap` must atomically verify/reserve the submitted state leases, enforce ownership/fencing/freshness, append the admission and update the projection, or publish none of them. This API does not provision physical state or grant per-cell effects. It does not install that storage adapter.
+
+Snapshots include all registered admissions, including rounds still pending or later failed; the admission itself carries no outcome claim. The projection's latest sequence must match complete, scoped, sealed history. Reused campaign/execution/attempt/lease identities and incomplete histories are conflicts. A lease cannot become fresh by changing its revision or digest. An exhausted 500-round prototype history blocks until an authoritative archival index is supplied; it never silently drops earlier registrations.
+
+Registration increments aggregate version and latest-round sequence without activating coverage. Any older activation snapshot must therefore conflict even before the newest round completes. Concurrent registration/invalidation uses the same aggregate-version CAS. Losing writers publish no admission and do not advance the epoch.
+
+`invalidateScenario` requires a new immutable definition revision of the same scenario, advances the invalidation epoch, clears activation authority and moves coverage to `degraded`. It retains historical round records. Retired coverage cannot be resurrected through this operation. An observed product regression does not itself call semantic invalidation or remove its detecting case.
+
+Terminal campaign binding is available through [qualification result reduction](qualification-results.md), followed by [read-only replay assessment](replay-assessment.md) and [explicit activation](scenario-activation.md). [LocalScenarioStore](local-scenario-store.md) supplies durable local registration/invalidation and scoped lease-identity claims on the existing ledger, with required host authority callbacks. Promotion, structural-validation transitions and hosted persistence remain open. A registration record is neither a passing round nor release coverage.
+
+## Executing a registered round
+
+The SDK can prepare a new qualification request from an unchanged frozen trial or
+work-proof plan. This creates new sealed request, fidelity and fixture documents;
+it does not read, rewrite or promote trial receipts.
+
+```ts
+const owner = localQualificationExecutionOwner(store, authorizeEffects);
+const qualified = await prepareQualificationExecution(
+  frozenPlan, admission.ref, scope, ledger, owner,
+);
+const run = await executeBundle({
+  bundle: qualified, scope, ledger, stateDir, qualification: owner,
+});
+```
+
+The store must use this exact ledger and state directory. `authorizeEffects` is a
+trusted host capability checked before host start, fixture creation and each
+forward step. It must establish actual permission to affect the selected target;
+read and registration permission alone do not suffice. The store rechecks current
+definition, invalidation epoch, reviewed closure and physical leases around each
+authorization await. Cleanup remains available after forward permission is revoked.
+External authority synchronization and provider fencing remain host responsibilities.
+
+Every cell uses its registered execution and attempt IDs. A single durable claim
+binds the admission to the complete frozen request, independently of caller retry
+keys. Terminal redelivery returns the recorded summary without repeating effects.
+An incomplete claim, including a lost publication acknowledgement, requires
+reconciliation; it never automatically replays preallocated effects. Execution
+directories cannot overwrite existing evidence. The trusted controller must keep
+its ledger and evidence directory inaccessible to candidate processes.
+
+Pass resulting bundles to `reduceQualificationRound` with the persisted admission
+resolver and independent issuer authentication. Structural bundle verification
+alone does not establish an authentic qualification result. Local tests use real
+native HTTP effects and durable registration, with explicitly simulated host
+authorization, reviewed-source and physical-lease callbacks.
+
+There is no automatic CLI qualification owner. Qualification without an explicit
+runtime owner, a trial disguised with lifecycle refs, and activated regression
+requests remain refused. This SDK path does not activate coverage or prove hosted
+source, issuer, lease provisioning or release authority.

package/docs/qualification-results.md

@@ -0,0 +1,59 @@
+# Complete terminal qualification rounds
+
+`reduceQualificationRound(ports, { admissionRef, scope, bundleDir })` reads a single verified bundle snapshot and binds its entire campaign to an authentic previously registered admission. It returns a sealed `workflow.qualification-round/v1` document containing the exact admission, campaign and terminal receipt references. Redelivery of identical evidence produces the same result reference and digest.
+
+Every selected cell needs exactly one terminal receipt with its preallocated execution and attempt identity. Missing cells, duplicate allocations, substituted scope/campaign/selection/policy/strata, mismatched scenario references and invalid raw evidence are rejected. The bundle reader reapplies the full saved cell and campaign guards, including assertions, identity observations, capture, cleanup and receipt bindings. No caller-supplied success count replaces those checks.
+
+The host owns `authorize`, `resolveAdmission` and `authenticateEvidence`. The admission resolver must read authentic persisted registration and reserved state, not accept an imported producer document as registration. Evidence authentication must validate the exact definition/replay/policy/matrix/target closure and issuer/effect authority against the captured bundle manifest digest. A host without those implementations must refuse the operation. Callbacks receive separate copies so mutation cannot rewrite the result being sealed. The reducer publishes no persistence write; a host must store the result with its immutable admission binding and enforce idempotency/conflict handling.
+
+Complete failed, blocked, cancelled, inconclusive and mock campaigns remain terminal evidence. A result has neither `qualifies` nor a live proof level. It does not activate coverage. [Replay assessment](replay-assessment.md) derives independent-round readiness, latest-round and epoch checks and policy-specific revision proof. [Explicit activation](scenario-activation.md) supplies an atomic host contract and local journal adapter. A historical terminal result can be retained after invalidation without becoming eligible for current activation.
+
+[Registered SDK execution](qualification-registration.md#executing-a-registered-round)
+uses actual persisted admissions and allocated cell identities with an explicit runtime
+owner. Qualification without that owner and activated regression execution remain blocked.
+Older consumer fixtures simulate registration around real observations; they do not prove
+authentic hosted qualification.
+
+## Durable local terminal results
+
+`LocalQualificationResults` connects this reducer to the existing `LocalResultSink` and
+`LocalLedger`. It retains a complete immutable bundle before atomically publishing the
+admission-to-round index. It does not create a second archive, database or readiness flag.
+
+```ts
+const results = new LocalQualificationResults(ledger, scope, {
+  authorize: authorizeResultRead,
+  authorizeRetention: authorizeResultRetention,
+  resolveAdmission: (ref, scope) => store.resolveAdmission(ref, scope),
+  authenticateEvidence,
+});
+const saved = await results.retain({ admissionRef: admission.ref, scope, bundleDir });
+// Supply this resolver to ReplayAssessmentPorts:
+const resolveRound = (admission) => results.resolveRound(admission);
+```
+
+All authority callbacks are required. Read permission, retention permission and issuer
+authentication are distinct. Registration must come from an authoritative owner; the
+result sink's integrity check does not authenticate a producer. Every historical lookup
+rechecks permission, persisted admission, raw bundle integrity, issuer authentication,
+manifest digest and exact terminal round bindings. Pending work returns null only after
+checking authentic registration. Broken or inaccessible retained evidence raises an error.
+
+Both outcomes and raw bytes remain available after the producer's directory is deleted.
+Duplicate and concurrent retention of the same admission/manifest converge on one index
+record. Different bytes under an existing round conflict. The sink accepts an expected
+manifest digest, so bytes changed after issuer authentication cannot claim the campaign
+in the generic index. A crash before index publication
+can leave an integrity-checked generic result, which stays pending as a qualification round;
+retry reconciles it. A lost acknowledgement after publication recovers the original round
+after reopening the ledger. Neither recovery path executes the candidate again.
+
+The bounded index permits 500 rounds per scope and requires archival indexing at capacity;
+it never drops failures or pending admissions to make coverage pass. The controller must
+protect the state directory from candidate writes. This is local single-writer storage,
+not distributed fencing, hosted IAM, physical lease provisioning or atomic activation.
+Tests include real registration and native HTTP effects, producer deletion, journal reopen,
+lost publication acknowledgements, concurrent retention, permission/issuer revocation and
+byte replacement across authorization awaits. Two independent real registered campaigns
+feed replay assessment through this index. Host, source, physical-lease and issuer authority
+are explicitly simulated; hosted qualification and release coverage remain unproven.