tracegrove 0.3.0 → 0.3.1

package/docs/portable-environments.md

@@ -1,155 +0,0 @@
-# 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

@@ -1,58 +0,0 @@
-# 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

@@ -1,59 +0,0 @@
-# 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.

package/docs/replay-assessment.md

@@ -1,17 +0,0 @@
-# Replay assessment
-
-`assessScenarioReplay(ports, token)` derives read-only readiness from the complete registered scenario history and authenticated raw bundle snapshots. It never accepts caller-provided passing assessments and never activates coverage. A host must still perform explicit authenticated activation with an atomic comparison against the returned scenario revision token, chosen rounds and exact definition bindings.
-
-The immutable, scoped `workflow.qualification-policy/v1` selects environment or revision proof and requires between two and twenty independent rounds. Two is the minimum; there is no mock-only or single-run activation policy. Source-derived scenarios additionally require revision proof even when the policy requests environment proof.
-
-Every current-epoch round retains its exact scenario/replay/policy/matrix/target-profile/strata bindings. Registration history is complete, monotonic and checked before any results are filtered. Reused campaign, execution, attempt or leased-state identities are refused. An incomplete history or unknown issuer is an error, never an empty passing report. Old epochs remain in the host's history but cannot count toward current qualification.
-
-Each terminal round is re-derived through the same authenticated snapshot reader used by `reduceQualificationRound`; the trusted result index must match that derived round reference. Required cell coverage, assertions, capture, observed identity and cleanup guards therefore run again. Mock, replayed, intercepted, fault-injected or stubbed claimed boundaries cannot count as live proof. Required target identities must be nonempty and observed; the full observed tuple must match the expected tuple. A failed, cancelled, blocked or inconclusive campaign cannot qualify even when some cells passed.
-
-Revision proof additionally binds every resolved repository role, URL, commit, origin, object reference and lockfile digest to the observed target and requires a registered resolver reference. Generic environment proof cannot satisfy a revision-specific policy or waive missing/mismatched source identity when source bindings or expected repository identities exist. Source-bound requests must retain the scenario's reviewed source plan. These comparisons do not authenticate observations by themselves: `authenticateEvidence` must establish issuer authority, real state leases, the reviewed source/replay/policy/matrix/target closure, required capture and independently observed target fields against the captured manifest digest. Copying requested identities into an observation is insufficient. The prototype does not install that host adapter or a source resolver.
-
-The latest admitted current-epoch round must be terminal and qualify. Two older passes do not hide a newer pending or nonqualifying campaign. All current-epoch rounds, including nonqualifying ones, appear in the report. Version, definition, epoch and latest sequence are rechecked after reading evidence; a concurrent registration or semantic edit makes the report stale. A subsequent activation must repeat its atomic comparison because an edit can still arrive after this read-only report returns.
-
-Reports contain sealed `workflow.replay-assessment/v1` documents and their resolvable `workflow.replay-finding/v1` reason documents. Proof levels are structural, mock, environment or revision. These are observations, not permissions. The report contains its exact revision token and qualifying round refs for a future activation owner; the schema's `qualifies` boolean alone grants no authority.
-
-Tests run real local native application observations and genuine mock observations with explicitly simulated catalog registration and issuer ports. They prove consumer reduction and race handling. Synthetic resolved-source fixtures exercise classifier guards only. The [local result index](qualification-results.md#durable-local-terminal-results) supplies retained terminal evidence, and [explicit activation](scenario-activation.md#local-atomic-storage) has a durable journal adapter. [Structural validation](scenario-structure.md) shares the executor preflight and supports proposed/degraded transitions. [Source-plan promotion](source-promotion.md) binds current approved storage to proposed scenarios. Additional integration tests use actual registration and native execution with simulated external authority. Hosted registration/issuer authority, live staging qualification and activated regression execution remain open.

package/docs/scenario-activation.md

@@ -1,54 +0,0 @@
-# Explicit scenario activation
-
-`activateScenario(ports, intent)` consumes an exact scenario revision token, replay/policy/matrix/target references, an explicit selection of terminal round references and a scoped idempotency key. It returns a sealed `workflow.scenario-activation/v1` receipt. Actor identity and the authorization policy come from the authenticated host's `authorizeActivation(scope, intentDigest)`; callers cannot submit an actor, approval flag or readiness result.
-
-The operation requires a validating scenario, checks all expected definition bindings and re-derives replay qualification from authenticated complete evidence. The selected set must satisfy the policy's independent-round minimum and include the latest admitted qualifying round. Duplicate or foreign rounds, mock-only proof, a newer pending round and stale scope/version/epoch are refused. Existing matrix, history, issuer and bundle guards are shared with replay assessment.
-
-`compareAndSwapActivation` is an atomic authority boundary. In one transaction, the host must compare validating state, aggregate version, definition and replay/policy/matrix/target digests, epoch, latest admitted sequence, exact immutable selected result refs and current activation authorization. It must enforce the scoped idempotency key and publish the assessment/finding records, activation receipt and active projection together, or publish none. The selected-result check still matters when a result index changes without advancing the scenario version. A registered newer round or semantic invalidation must conflict with an older activation attempt. The local adapter below uses the existing journal; hosted transaction storage remains a separate host integration.
-
-Repeated round order is normalized. An already committed identical intent returns its original receipt without another write, including after a lost commit acknowledgement or concurrent identical delivery. Reusing the key for a different intent conflicts. Authorization runs before historical receipt lookup too. Returning an earlier activation receipt does not assert that coverage remains active now: a later semantic invalidation or retirement remains in effect, and retries cannot resurrect it. Read the current projection to establish current state.
-
-This API cannot activate proposed, degraded, active or retired projections through a fresh intent. Promotion and successful structural validation must first establish validating state through their own authority. Product regressions remain visible through qualification/release evidence; they do not implicitly call semantic invalidation or remove the detecting case.
-
-## Local atomic storage
-
-`LocalScenarioStore.activationPorts(results, authority)` connects explicit activation
-to the scenario registry and `LocalQualificationResults` on the same `LocalLedger`.
-It reuses the public decision validator and independently rederives replay assessment
-inside the commit boundary. Submitted readiness flags, actors, reports and projections
-are compared with freshly derived values; they cannot grant authority.
-
-```ts
-const ports = store.activationPorts(results, {
-  resolvePolicy,
-  authorizeActivation, // Current authenticated owner and policy for this exact intent digest.
-});
-const activation = await activateScenario(ports, intent);
-```
-
-The adapter checks the scenario registry version, complete result-index version and
-captured archive manifest digests after its final activation authorization await.
-There is no await between those checks and the single synced append containing the
-active projection, receipt and full assessment/finding records. An unrelated change
-to the scope's registry or result index can conflict conservatively; retry from a
-fresh snapshot. Revocation and physical/provider fencing outside this local writer
-still require the host to synchronize its authority checks with its controller.
-
-Idempotency keys are unique across scenarios in the scope. Reopen reads the complete
-activation and projection from the same journal entry. A write failure publishes
-neither; a committed entry with a lost acknowledgement returns its original receipt
-on retry. Historical retrieval requires current activation authorization and never
-reverses a later invalidation. Existing registration-only journals read with empty
-activation history; an active projection without its persisted receipt is refused.
-The scope permits 500 retained activations before explicit archival indexing is needed.
-
-Tests use actual registered native/mock execution, the immutable result sink and
-durable scenario journal, alongside the earlier in-memory consumer tests. They cover
-concurrency, lost acknowledgement with reopen, pre-write failure, forged submissions,
-registration/invalidation/revocation/archive/index races and corrupt persisted reports.
-Host, reviewed-source, physical-lease and issuer authority are explicitly simulated.
-These proofs do not establish hosted activation, deployed staging qualification or
-live regression admission. [Structural transitions](scenario-structure.md) have a local
-adapter. [Source-plan promotion](source-promotion.md) has a local approved-review bridge.
-Hosted persistence and
-activated regression execution remain open.

package/docs/scenario-structure.md

@@ -1,58 +0,0 @@
-# Structural validation before qualification
-
-`LocalScenarioStore.propose(definition, selections)` stores an authorized immutable
-scenario in `proposed` state. Qualification registration refuses that state.
-`validateScenarioStructure(ports, token, frozenPlan)` performs static checks and
-records the transition to `validating`. It can also revalidate a `degraded` revision
-after semantic invalidation. It does not run the candidate or claim functional PASS.
-
-```ts
-await store.propose(definition, [qualificationMatrix, selectedRound]);
-const validation = await validateScenarioStructure(
-  store.structuralPorts({ authorizeValidation }),
-  exactScenarioRevisionToken,
-  frozenTrialPlan,
-);
-```
-
-The plan must be a sealed trial/work-proof request without lifecycle refs or plan
-blockers. Its cases, personas, target cells and exclusions must exactly match the
-scenario matrix. The implementation shares the executor's actual document resolution,
-capability reproduction, fixture/fidelity checks and case compiler. Missing fixture
-plans, changed fidelity, unsupported capabilities and unresolved/modified documents
-fail before a host, fixture operation or provider starts. Matrix policy is taken from
-the scenario's reviewed definition; this operation cannot change that matrix.
-
-The authenticated host supplies `authorizeValidation(scope, intentDigest)`, returning
-the current actor and authorization policy for the exact token, frozen request and
-executable-closure digest. Source/review/definition checking remains the store's
-required `validateDefinition` responsibility. No permission or independent source
-validation is inferred from a caller's success flag. Proposed storage is not itself
-the source-plan promotion manifest; [source promotion](source-promotion.md) supplies
-that separate approved-review operation.
-
-The local adapter recompiles the supplied closure and rechecks definition and actor
-authority before publishing the sealed `workflow.scenario-structure/v1` receipt and
-validating projection in one synced registry entry. A competing edit, invalidation or
-authorization change publishes no validation. The receipt records the exact scenario
-token, request, qualification matrix, executable closure, actor, policy and timestamp.
-It clears current qualification/activation refs without deleting historical evidence.
-
-Repeated identical deliveries recover one receipt, including after lost acknowledgement
-or journal reopen. Historical receipt retrieval requires current validation permission;
-it does not reverse later invalidation or prove that coverage remains validating now.
-Revalidation of a replacement definition uses a new token and preserves its advanced
-invalidation epoch. Keep the original frozen plan alongside the receipt: the digest
-binds that plan but does not make the receipt an executable bundle.
-
-The index is bounded to 500 structural records per scope and refuses exhaustion rather
-than dropping history. Existing journals read with empty structural history. The earlier
-`initialize` API remains a trusted-host import of an already structurally validated
-scenario; it does not produce this receipt and requires the host to establish both
-promotion and validation authority before calling it.
-
-This is protected local single-writer storage. It does not install hosted IAM, physical
-state leases, hosted source promotion, CLI lifecycle commands, live qualification or
-activation. Tests use real journal bytes and static compilation; one positive test then
-executes two newly admitted native cells. Host/source/review/effect authority is explicitly
-simulated, and structural success alone is never reported as application success.

package/docs/source-promotion.md

@@ -1,104 +0,0 @@
-# Promoting an approved source plan
-
-`promoteScenario(ports, intent, definition, selections)` registers an approved source
-scenario as `proposed`. It returns a sealed `workflow.scenario-promotion/v1` manifest.
-It creates no plan approval, structural validation, runtime PASS or active coverage.
-
-The intent names the scenario, immutable definition and selection refs, exact editable
-plan revision token, and scoped idempotency key. The definition binds the source plan
-and current review. Promotion requires the stored review to be approved for that exact
-plan/edit revision and to retain its atomically stored source validation. Each promoted
-case must belong to approved runnable candidates whose source elements were independently
-validated. Blocked/excluded candidates and non-scenario plan dispositions cannot become
-promoted cases. The matrix and every supplied selection retain the exact case/persona/
-target strata and policy.
-
-```ts
-const ports = scenarios.promotionPorts(reviews, { authorizePromotion });
-const manifest = await promoteScenario(ports, {
-  scenarioId,
-  definitionRef: definition.ref,
-  reviewToken,
-  selectionManifestRefs: selections.map(selection => selection.ref),
-  idempotencyKey,
-}, definition, selections);
-```
-
-`LocalReviewStore.approvedSnapshot(ledger, token, reviewRef)` resolves actual approved
-storage on the same writer. It requires current review authority without writing a
-review or approving anything. Its documents are copies; its runtime `assertCurrent`
-checks the review aggregate version. The local promotion adapter resolves that snapshot
-again inside its commit, compares the submitted context, rechecks creation/promotion
-authority and verifies both review and scenario versions after the final await.
-One synced scenario-registry entry contains the proposed definition, selections,
-manifest, full reviewed plan, review and source-validation snapshot. Gaps, withheld
-flows, excluded candidates and diagnostics remain in that immutable snapshot.
-
-The manifest binds the review/source-validation refs and storage version as well as
-the authenticated promoter and policy. Selection order is normalized. Repeated or
-concurrent identical intent returns one manifest; a changed scoped key binding or an
-attempt to overwrite an existing scenario conflicts. A pre-write failure publishes
-nothing; a lost acknowledgement recovers the committed manifest after reopen. The
-registry's existing 100-scenario bound applies. Older journals have no promotion record.
-
-## Current review checks after promotion
-
-Bind the current review owner once when constructing a source-backed local scenario store:
-
-```ts
-const scenarios = new LocalScenarioStore(ledger, scenarioId, scope, {
-  reviewStore: reviews,
-  authorize,
-  validateDefinition: validateReplayPolicyAndTarget,
-  validateStateLeases,
-});
-```
-
-`reviewStore` is required when a definition names a source plan. It must own the same
-ledger. The store checks its exact current approved review and independently validated
-runnable cases in addition to the host's replay/target/policy checks. Initialize,
-structural validation, round registration and activation hold its synchronous version
-fence through their last awaited authorization and assert it immediately before the
-registry write. An edit during that await publishes no transition.
-
-An edit clears the current plan review. These guards then refuse later structural,
-qualification and activation admission against the old review. Use `invalidateScenario`
-with a replacement definition to advance its epoch and clear activation. Historical
-promotion retries return the original receipt without renewing approval or altering
-the scenario. Promotion registers new entries; replacing an existing scenario remains
-an explicit semantic edit and review flow.
-
-All ports belong to the trusted host. A saved source plan or producer-supplied approval
-object cannot supply them. Protect the state directory and synchronize external IAM,
-revocation and provider fencing with the controller. Local hashes and receipts do not
-establish a hosted issuer or deployed revision. Source-bound activation still requires
-independent runtime revision proof; source inspection alone cannot grant it.
-
-## Execute the reviewed revision
-
-Use the compiler's `--source-snapshot` and `--source-repository-role` options to bind
-the complete resolver-head snapshot before selecting, reviewing and promoting cases.
-The approved source plan must name that exact resolver matrix. A different matrix
-ref is rejected even when its commits happen to match. Component-only source runs
-can still execute, but cannot establish revision qualification.
-
-`prepareQualificationExecution` reads current source review evidence through the
-scenario owner and carries copies of the sealed plan, approved review and source
-validation into the frozen execution documents. It leaves the original trial plan
-unchanged. Each effect authorization resolves current owner state again, including
-after awaited effect permission. The controller never obtains approval from the
-copied documents.
-
-Preflight and saved-bundle checks use `validateReviewedSourceDocuments` to check seals,
-scope, plan/review/validation links and the selected matrix. The same pure schema is
-shared with promotion. Saved evidence proves the recorded relationships; the owning
-review store determines current approval. Historical bundles remain readable after
-an edit, while new execution and activation require current authority.
-
-Tests compose immutable Git reads, an actual bounded TypeScript AST predicate, source
-validation, durable review, promotion, structural validation, two independently admitted
-native revision rounds and atomic activation, including reopen recovery and source-edit
-races at the final structural, registration and activation boundaries.
-Authentication, coverage policy, physical leases and issuer authority are explicitly
-simulated. The AST oracle proves a declared POST branch only. These proofs do not
-establish full semantic coverage, a deployed source tuple or hosted qualification.

package/docs/source-review.md

@@ -1,21 +0,0 @@
-# Source-backed plan review
-
-`validatePlanSources` checks a sealed source plan against its exact change model and revision matrix. It authorizes each repository, hashes the fetched full diff, resolves citations only at selected immutable commits, and reuses `verifySourceCitation` for file/excerpt checks. A modified working checkout cannot substitute for unavailable selected source.
-
-Runnable derivations need confirmed metadata, citations, and nonempty evidence from a registered independent AST/schema/route oracle. Confidence and a proposed `confirmed` label do not establish that evidence. Failed/partial/unsupported extraction retains diagnostic refs as plan gaps. The trusted coverage policy checks frozen requirements, unresolved questions, excluded material and no-E2E reasoning. Source checks never produce runtime PASS, qualification or activation.
-
-Trusted host integration:
-
-```ts
-const reviewPorts: PlanReviewPorts = {
-  ...authenticatedReviewAndStorage,
-  validateSources: (plan, policyRef) => validatePlanSources(sourcePorts, plan, policyRef),
-};
-const reviewed = await reviewPlan(reviewPorts, revisionToken, 'approved', reasonRefs);
-```
-
-All ports belong to the authenticated host. A candidate, plugin or authoring model cannot supply its own source checker, oracle or coverage policy. Revision policy must explicitly admit a missing merge base and its alternative diff method. A full diff over 4 MiB, over 500 distinct runnable citations, unavailable objects, mismatched refs or denied authority block validation rather than truncate source.
-
-Approval requires a sealed `workflow.source-validation/v1` result binding the same plan, change model, matrix, scope and admitted review policy. Its ref is included in the immutable review's reason refs. The host's `compareAndSwap` must publish that validation record, review and projection in one atomic write. A losing write publishes none of them. Rejection requires no fabricated successful source check. An edit still clears the current review; historical validation records remain evidence of their original source digests.
-
-This changes the experimental `PlanReviewPorts` contract: approved reviews require `validateSources`, and `compareAndSwap` receives a fourth validation argument. Persist it atomically; ignoring it is not a conforming host. [Local review storage](local-review-store.md) persists its records and [source promotion](source-promotion.md) binds current approved storage to a proposed scenario. This review API installs no hosted source registry or production oracle. Qualification execution requires a separately registered runtime owner; activated regression execution remains blocked.