tracegrove 0.0.0-stage → 0.3.0

package/docs/examples/portable-environments/alongside_runner.json

@@ -0,0 +1,199 @@
+{
+  "schemaVersion": "workflow.portable-environment-profile/v1",
+  "ref": {
+    "id": "example.profile.alongside_runner",
+    "revision": "1",
+    "digest": {
+      "algorithm": "sha256",
+      "hex": "e4996a6cd34d28fdecc35d1b6fbef4b7e38301c7133137a43d833d1833e53e56"
+    }
+  },
+  "scope": {
+    "ownerId": "example.owner",
+    "tenantId": null,
+    "visibility": "owner_private"
+  },
+  "sourceSelectionRef": {
+    "id": "example.source-selection",
+    "revision": "1",
+    "digest": {
+      "algorithm": "sha256",
+      "hex": "ab392664423be621da6bb048313f6531356bd96333edb3938dce0b97cad0f277"
+    }
+  },
+  "buildRef": {
+    "id": "example.build",
+    "revision": "1",
+    "digest": {
+      "algorithm": "sha256",
+      "hex": "7e261d3ba9878d05db4c5c6baa3e4a2db1a584c3d2f5f0628b4a1c78f43f5e42"
+    }
+  },
+  "configurationRef": {
+    "id": "example.non-secret-config",
+    "revision": "1",
+    "digest": {
+      "algorithm": "sha256",
+      "hex": "74afc8ef6b145b02ec9bb478dfdefdadb225fc6f7c6a729760b525ca83476e55"
+    }
+  },
+  "target": {
+    "mode": "alongside_runner",
+    "workspaceRef": {
+      "id": "example.workspace",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "8e1f432465350d78268d8b77cee90f0715de9e46a650df4235f2a74894fa52b1"
+      }
+    },
+    "hostPlanRef": {
+      "id": "example.host-plan",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "bc6a1e45f33b36d86dbce570145d739f81e757d620e6a973f641905ad11aff21"
+      }
+    },
+    "launchRecipeRef": {
+      "id": "example.launch-recipe",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "ea08051425f1b814abb6bc69d036429beb70df5b2a142f94bd1dcfe3df7cabd4"
+      }
+    }
+  },
+  "endpoints": [
+    {
+      "id": "app",
+      "resolverRef": {
+        "id": "example.app-endpoint",
+        "revision": "1",
+        "digest": {
+          "algorithm": "sha256",
+          "hex": "a6b3d24ad9a0af002a55a8ac10805e763bedd7b3e5fc0a714a3d59fecc129b81"
+        }
+      },
+      "source": "launch_reported"
+    }
+  ],
+  "readiness": {
+    "endpointId": "app",
+    "path": "/health",
+    "method": "GET",
+    "expectedStatus": 200,
+    "timeoutMs": 20000
+  },
+  "capabilities": [
+    {
+      "id": "surface.http",
+      "version": 1,
+      "required": true
+    }
+  ],
+  "dependencyPlanRefs": [],
+  "personaCredentials": [
+    {
+      "personaRef": {
+        "id": "example.persona.owner",
+        "revision": "1",
+        "digest": {
+          "algorithm": "sha256",
+          "hex": "6e993a3445b5165be1d544736fadaa7d46d65c63d07ed71b1552bb51a5bd0813"
+        }
+      },
+      "secretRef": {
+        "id": "example.app-persona-credential",
+        "revision": "1",
+        "digest": {
+          "algorithm": "sha256",
+          "hex": "e90cf65d59c84838c7dd77bec933794873024e2c93cf8252a4079e494a04c4f8"
+        }
+      }
+    }
+  ],
+  "executionPolicyRef": {
+    "id": "example.execution-policy",
+    "revision": "1",
+    "digest": {
+      "algorithm": "sha256",
+      "hex": "f5150e48ea518c445afe198f0c7d643b4645faaeb4fe3d6d007d79209dc4de59"
+    }
+  },
+  "executionSecretRefs": [],
+  "network": {
+    "policyRef": {
+      "id": "example.network-policy",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "858db25db4c84793dd49f8bce7d12c9900326669c502880e1f5267895119efd2"
+      }
+    },
+    "enforcement": "host",
+    "inbound": "loopback_only",
+    "egress": "explicit_allowlist",
+    "allowedEndpointIds": [
+      "app"
+    ]
+  },
+  "data": {
+    "mode": "none"
+  },
+  "ownership": {
+    "leasePolicyRef": {
+      "id": "example.lease-policy",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "0cc0aa82f73b5bf800d872d90a515772246e60a1f26c0b827c823a1256afb26d"
+      }
+    },
+    "cleanupPlanRef": {
+      "id": "example.cleanup-plan",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "af70f7ee71e47a2ba88e31da4d90bcf0cd8a991cb24b937245704f17d5f6b1db"
+      }
+    },
+    "cleanupReserveMs": 10000
+  },
+  "artifacts": {
+    "destinationRef": {
+      "id": "example.artifact-destination",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "86b317ba249de72c702be4390a57b7bcd090aa5fdb086fe16e64479efa4f9fca"
+      }
+    },
+    "durability": "export_required",
+    "redactionPolicyRef": {
+      "id": "example.redaction-policy",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "ebe43b36aeba3427ee4be196757f1cc3d4acb47c34f02928f40ed0cf008d0a8c"
+      }
+    },
+    "retentionMs": 86400000,
+    "maxBytes": 16777216
+  },
+  "limits": {
+    "wallMs": 120000,
+    "cpu": 1,
+    "memoryMb": 1024,
+    "diskMb": 256,
+    "maxRequests": 100,
+    "maxBrowserActions": 0,
+    "maxProviderCalls": 0,
+    "maxAgentCalls": 0,
+    "maxSpendCents": 0
+  },
+  "allowedReplayModes": [
+    "fresh_execution",
+    "evidence_playback"
+  ]
+}

package/docs/examples/portable-environments/external_staging.json

@@ -0,0 +1,183 @@
+{
+  "schemaVersion": "workflow.portable-environment-profile/v1",
+  "ref": {
+    "id": "example.profile.external_staging",
+    "revision": "1",
+    "digest": {
+      "algorithm": "sha256",
+      "hex": "ce613297287d6c80046cf21ea9439ec5cecbd01db2facba9cdd0721e89af5045"
+    }
+  },
+  "scope": {
+    "ownerId": "example.owner",
+    "tenantId": null,
+    "visibility": "owner_private"
+  },
+  "sourceSelectionRef": {
+    "id": "example.source-selection",
+    "revision": "1",
+    "digest": {
+      "algorithm": "sha256",
+      "hex": "ab392664423be621da6bb048313f6531356bd96333edb3938dce0b97cad0f277"
+    }
+  },
+  "buildRef": {
+    "id": "example.build",
+    "revision": "1",
+    "digest": {
+      "algorithm": "sha256",
+      "hex": "7e261d3ba9878d05db4c5c6baa3e4a2db1a584c3d2f5f0628b4a1c78f43f5e42"
+    }
+  },
+  "configurationRef": {
+    "id": "example.non-secret-config",
+    "revision": "1",
+    "digest": {
+      "algorithm": "sha256",
+      "hex": "74afc8ef6b145b02ec9bb478dfdefdadb225fc6f7c6a729760b525ca83476e55"
+    }
+  },
+  "target": {
+    "mode": "external_staging",
+    "deploymentRef": {
+      "id": "example.deployment",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "8076c13e2f647e540083550833a8160c5e089fb199c9453ab5aecd598c9228fb"
+      }
+    }
+  },
+  "endpoints": [
+    {
+      "id": "app",
+      "resolverRef": {
+        "id": "example.app-endpoint",
+        "revision": "1",
+        "digest": {
+          "algorithm": "sha256",
+          "hex": "a6b3d24ad9a0af002a55a8ac10805e763bedd7b3e5fc0a714a3d59fecc129b81"
+        }
+      },
+      "source": "external_deployment"
+    }
+  ],
+  "readiness": {
+    "endpointId": "app",
+    "path": "/health",
+    "method": "GET",
+    "expectedStatus": 200,
+    "timeoutMs": 20000
+  },
+  "capabilities": [
+    {
+      "id": "surface.http",
+      "version": 1,
+      "required": true
+    }
+  ],
+  "dependencyPlanRefs": [],
+  "personaCredentials": [
+    {
+      "personaRef": {
+        "id": "example.persona.owner",
+        "revision": "1",
+        "digest": {
+          "algorithm": "sha256",
+          "hex": "6e993a3445b5165be1d544736fadaa7d46d65c63d07ed71b1552bb51a5bd0813"
+        }
+      },
+      "secretRef": {
+        "id": "example.app-persona-credential",
+        "revision": "1",
+        "digest": {
+          "algorithm": "sha256",
+          "hex": "e90cf65d59c84838c7dd77bec933794873024e2c93cf8252a4079e494a04c4f8"
+        }
+      }
+    }
+  ],
+  "executionPolicyRef": {
+    "id": "example.execution-policy",
+    "revision": "1",
+    "digest": {
+      "algorithm": "sha256",
+      "hex": "f5150e48ea518c445afe198f0c7d643b4645faaeb4fe3d6d007d79209dc4de59"
+    }
+  },
+  "executionSecretRefs": [],
+  "network": {
+    "policyRef": {
+      "id": "example.network-policy",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "858db25db4c84793dd49f8bce7d12c9900326669c502880e1f5267895119efd2"
+      }
+    },
+    "enforcement": "host",
+    "inbound": "none",
+    "egress": "explicit_allowlist",
+    "allowedEndpointIds": [
+      "app"
+    ]
+  },
+  "data": {
+    "mode": "none"
+  },
+  "ownership": {
+    "leasePolicyRef": {
+      "id": "example.lease-policy",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "0cc0aa82f73b5bf800d872d90a515772246e60a1f26c0b827c823a1256afb26d"
+      }
+    },
+    "cleanupPlanRef": {
+      "id": "example.cleanup-plan",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "af70f7ee71e47a2ba88e31da4d90bcf0cd8a991cb24b937245704f17d5f6b1db"
+      }
+    },
+    "cleanupReserveMs": 10000
+  },
+  "artifacts": {
+    "destinationRef": {
+      "id": "example.artifact-destination",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "86b317ba249de72c702be4390a57b7bcd090aa5fdb086fe16e64479efa4f9fca"
+      }
+    },
+    "durability": "export_required",
+    "redactionPolicyRef": {
+      "id": "example.redaction-policy",
+      "revision": "1",
+      "digest": {
+        "algorithm": "sha256",
+        "hex": "ebe43b36aeba3427ee4be196757f1cc3d4acb47c34f02928f40ed0cf008d0a8c"
+      }
+    },
+    "retentionMs": 86400000,
+    "maxBytes": 16777216
+  },
+  "limits": {
+    "wallMs": 120000,
+    "cpu": 1,
+    "memoryMb": 1024,
+    "diskMb": 256,
+    "maxRequests": 100,
+    "maxBrowserActions": 0,
+    "maxProviderCalls": 0,
+    "maxAgentCalls": 0,
+    "maxSpendCents": 0
+  },
+  "allowedReplayModes": [
+    "fresh_execution",
+    "evidence_playback"
+  ]
+}

package/docs/git-object-proof.md

@@ -0,0 +1,100 @@
+# Git object checks for pinned snapshots
+
+New `materializeGitSnapshot` outputs include the raw commit/tree object proof and each
+file's Git blob identity. The resolver reads immutable Git objects with its existing
+restricted environment; materialization verifies the complete proof before creating
+an output directory. No fetch, checkout, helper, signature verification or application
+execution is added.
+
+`verifyGitSnapshotCommit(snapshot, files)` independently hashes every actual file as a
+Git blob, checks paths and modes against the complete raw tree closure, and hashes that
+tree/commit chain against the selected commit. Both SHA-1 and SHA-256 object formats
+are supported. Its observation has `verification: actual_file_bytes` and binds the
+computed commit, root tree, object algorithm and proof digest. It needs captured bytes
+and proof objects and captures each supplied file buffer once before both hash checks,
+so it continues to work after the Git store and source directory
+are unavailable.
+
+```ts
+const files = readGitSnapshotTree(snapshot, sourceRoot);
+const observed = verifyGitSnapshotCommit(snapshot, files);
+```
+
+`verifyGitSnapshotProofMetadata(snapshot)` checks object/manifest links without reading
+source files. Its distinct `verification: object_links_only` result is not a runtime
+observation. A resealed manifest could pair a new SHA-256 file checksum with an old Git
+blob ID; metadata alone cannot prove that association. Actual-file verification rejects
+it even when the new checksums and manifest seal agree.
+
+## Launch and saved evidence
+
+Snapshot reads now verify object proofs when present. The trusted supervisor copies the
+pinned files into its owned tree and verifies the private copy again before launching
+the application. It sends the computed Git observation over its existing IPC channel.
+The parent refuses missing/mismatched observations for proof-bearing snapshots, and
+the sealed identity attestation records the observed fields. The application cannot
+establish this observation through its health response.
+
+Saved-bundle verification checks the proof's metadata, snapshot ref, component file
+closure and recorded Git observation after the private launch directory is removed.
+It does not regain the full source bytes from that observation. Authenticating the host
+and its runtime file measurements remains the issuer's job. Existing proof-less snapshots
+remain component-only and receive no Git observation. Repository binding is a separate,
+explicit option described below; remote ownership and dependency-install provenance are
+not inferred from Git object hashes.
+
+## Bind a repository role
+
+Materialization also saves a sealed `resolution.json` next to `snapshot.json`. To connect
+the selected resolver head to a repository role:
+
+```sh
+tracegrove test --config ./head/source/tracegrove.config.yaml \
+  --source-snapshot ./head/snapshot.json --source-repository-role application
+```
+
+The same flags work with `compile`. Compilation verifies the complete source tree,
+checks the sealed resolution sidecar against the snapshot, and emits `SourceSelection`,
+the original `RevisionMatrix`, and snapshot documents in the normal frozen corpus. The
+planner binds that selection to the request and every cell. Existing component-only
+snapshot runs do not change unless a repository role is provided. Old snapshots can
+be rematerialized to obtain a sidecar; no network access is required.
+
+The descriptor uses `urn:tracegrove:git-object:<algorithm>:<commit>` and origin
+`snapshot_bundle`. It identifies the actual Git object, not ownership of a GitHub URL.
+`requestedRef` in the target is the immutable commit; `requestedExpression` in source
+selection retains the resolver's original expression. Both Git SHA-1 and SHA-256 work.
+`dirty: false` describes the supervisor's complete private pinned copy, not the checkout.
+
+Lockfile identity v1 hashes a sorted manifest of complete pinned path, mode and SHA-256
+digest for `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`,
+`bun.lock`, `bun.lockb`, `uv.lock`, `poetry.lock`, `Pipfile.lock`, `Cargo.lock`, `Gemfile.lock`,
+`composer.lock` and `go.sum` at any depth. No recognized lockfile produces an explicit
+empty-manifest digest. This identifies pinned lockfiles; it does not establish which
+dependencies were installed.
+
+Repository observation is derived only after the supervisor's `actual_file_bytes`
+observation matches the proof. Planning, execution preflight, saved-bundle checks and
+revision assessment share the frozen source-closure checks. They reject different
+roles, remote URLs, lockfile identities, missing closure documents and source plans
+whose reviewed matrix differs. Base snapshots and multi-repository resolution sidecars
+cannot use this single-head binding; companion repositories are never silently dropped.
+They remain available for component-only runs until a complete multi-host binding exists.
+
+Two independent native campaigns can now meet a revision-level local qualification
+policy and activate through the durable scenario store. The tests simulate issuer and
+physical-lease authority explicitly. This does not establish hosted issuer trust, live
+staging coverage, remote repository ownership, or a reviewed-source promotion by itself.
+
+Proofs fail on missing or duplicate trees, unrelated objects, malformed/canonicalization
+errors, changed file/object/mode bindings, incomplete actual file coverage and unsupported
+tree entries. Symlinks, submodules, empty Git directories and nonportable paths cannot
+be silently omitted. Prototype bounds are 1 MiB per commit, 4 MiB per tree, 8 MiB total
+tree bytes, 8,192 distinct trees and 20,000 traversal entries, in addition to the existing
+10,000-file/32 MiB snapshot bound. Unsupported coverage blocks instead of truncating it.
+
+Tests use real SHA-1/SHA-256 repositories, binary files and reused subtrees; remove the
+Git/source paths before pure verification; and exercise resealed forged commits, trees,
+files and runtime attestations. Native pinned launches and independent bundle reads
+verify the observation path. These are local integrity/runtime facts, not hosted issuer
+authentication, author identity, a signed release or remote repository ownership.

package/docs/git-source-resolution.md

@@ -0,0 +1,133 @@
+# Immutable Git source resolution
+
+`workflow-verify source-resolve --input repositories.json --output source.json --json` freezes explicit local base/head selections across repositories. It exports a sealed owner-private source-resolution document containing the `RevisionMatrix`, full binary-capable diffs, changed paths and before/after blob bytes. Exit zero means source resolution succeeded; it is not a case review, execution verdict or deployment proof.
+
+Create a local request using the public typed SDK (the repository reference below is a local label, not a registered remote identity):
+
+```js
+import { writeFileSync } from 'node:fs';
+import { localScope, digestOfValue } from 'workflow-verify';
+
+writeFileSync('repositories.json', JSON.stringify({
+  scope: localScope(),
+  repositories: [{
+    repositoryRef: { id: 'application', revision: '1',
+      digest: digestOfValue({ kind: 'local-git-binding', name: 'application' }) },
+    root: '.', base: 'HEAD~1', head: 'HEAD',
+  }],
+}, null, 2), { flag: 'wx', mode: 0o600 });
+```
+
+Roots in CLI requests resolve relative to the request file. Library callers supply their own trusted local mappings. Both worktrees and bare repositories are supported; selecting a nested directory cannot silently bind its parent repository. The CLI accepts only the process's `localScope()` and writes new output files privately without overwriting existing evidence. Public JSON schemas include the Git request and resolution contracts.
+
+`resolveGitSources(request, authorize)` requires a trusted host authorization callback before reading each repository. `GitSourceReader(matrix, bindings, authorize)` implements citation object reads and full-diff reads after restart. Bindings contain only `repositoryRef` and `root`; they do not re-resolve branch expressions. A reader refuses another scope/repository, substituted matrix rows, unavailable objects and changed full-diff bytes. Citation validation still checks exact file/excerpt digests. A later dirty checkout or moved branch does not change the selected immutable commit identities.
+
+Git invocation uses argument arrays and [documented end-of-options handling](https://git-scm.com/docs/git-rev-parse), reads commit objects rather than worktree files, and disables replacement objects, inherited Git routing variables, external diff/text-conversion helpers, terminal prompts and lazy fetching. [Git's diff options](https://git-scm.com/docs/git-diff) define the helper exclusions. Selected commits and their tree closure are checked against Git object hashes; captured/read blobs are rehashed independently too. SHA-1 and SHA-256 Git object IDs are preserved in full. This does not create an authenticated issuer or attest a remote repository or deployed target; the host owns the Git executable, source mappings, protected object storage and admission policy.
+
+No fetch, checkout, model call or review approval occurs. Missing or multiple merge bases block until a registered alternative revision policy exists; an empty base is never invented. Renames are represented as deletion/addition with detection disabled. Changed symlinks, submodules, unsupported paths/modes, oversized blobs and incomplete output block instead of dropping coverage.
+
+Bounds: 32 repositories, 500 changed paths, 1 MiB per captured/cited blob, 4 MiB per full diff/tree listing/tree object, 8,192 trees per selected commit, 32 MiB of captured payload bytes and ten seconds per Git command. CLI input is at most 256 KiB. The artifact includes changed blobs and full diffs, not every source object: later citation reads require the selected objects in an authorized Git store. Full source-object transport remains separate work.
+
+The output is a `RevisionMatrix`, not a complete runtime `SourceSelection` or qualified source-to-target proof. Independent element/coverage checking, reviewed source admission, hosted lifecycle storage and execution wiring remain separate gates. Tests use real temporary repositories, including dirty/moved checkouts, bare and SHA-256 repositories, corrupt objects, denied/revoked scope, missing objects, oversized blobs, configured helpers and the actual source/built CLI.
+
+## Run selected revisions independently
+
+Materialize complete regular-file trees from the frozen resolution using an explicit
+authorized local repository mapping. Relative `--root` paths resolve beside the
+input JSON. Output directories must not exist, and their parent must already exist.
+
+```sh
+tracegrove source-materialize --input source.json --repository application --root . --side base --output ./base-snapshot
+tracegrove source-materialize --input source.json --repository application --root . --side head --output ./head-snapshot
+tracegrove test --config ./base-snapshot/source/tracegrove.config.yaml --source-snapshot ./base-snapshot/snapshot.json
+tracegrove test --config ./head-snapshot/source/tracegrove.config.yaml --source-snapshot ./head-snapshot/snapshot.json
+```
+
+Each output contains `source/` and a sealed `snapshot.json` with the resolution and
+repository references, exact commit, side, and every file's original Git mode,
+byte count and SHA-256 digest. `materializeGitSnapshot(input, authorize)` exposes
+the same operation through the SDK. Authorization runs before object reads and
+again before output allocation. No fetch, checkout, dependency installation, app
+execution, Git filters or hooks occur during materialization. Later `test` runs
+execute trusted project code and use the ordinary compiler and app identity checks.
+
+The reader validates the commit/tree closure and independently rehashes every blob,
+including unchanged files. It refuses an empty tree, symlinks, submodules, unsupported
+modes, nonportable names, case/Unicode aliases, more than 10,000 files, blobs over
+1 MiB, or more than 32 MiB of file bytes. These are complete-coverage limits: it
+never silently excludes a file to make a snapshot pass. A private output is created
+only after all object reads succeed; the manifest is written last, and write failure
+removes only the directory this operation exclusively created. Existing output is
+preserved. The host filesystem and Git executable remain trusted.
+
+The CLI regression test creates a real authorization bug and its fix in separate
+commits, freezes them, dirties the checkout and moves its branch. Separate CLI
+processes run the identical saved flow against both materialized revisions: the
+base fails the ownership assertion and the head passes. Both bundles are re-read
+and re-reduced, app digests match the snapshot's source bytes, and cleanup is
+confirmed. CI repeats this through the built distribution and retains both sealed
+bundles, source trees, snapshot manifests and resolution in `source-regression-proof`.
+Another process can verify those bundles or rerun either snapshot without discovery;
+the artifact README gives the exact commands. Locally, set
+`TRACEGROVE_SOURCE_PROOF_DIR` to a new directory when running
+`tests/cliGitSnapshot.test.ts` to retain the same proof.
+
+A snapshot is mutable after publication; its manifest describes the captured
+bytes. `test` and `compile` accept `--source-snapshot` for an explicit per-command
+binding. Compilation checks the manifest, local owner scope and every pinned file.
+The frozen launch plan includes that binding; the trusted supervisor checks the
+files again, copies only pinned inputs into its private owned workspace, and
+starts the app there. Untracked files cannot enter the launch copy. Post-plan drift
+in any pinned file, including files outside the entrypoint's source glob, blocks
+startup. The supervisor owns and removes the private copy after stop, startup
+failure or controlling-client disconnect.
+
+Pinned launches support the Node file, FastAPI module and canonical Django launch
+templates. Opaque eval/shell wrappers and entrypoints outside the snapshot are
+refused. The attestation binds the supervisor-computed source digest and snapshot
+reference; saved-bundle verification rechecks the exact file closure and manifest
+digests. Dependency installations, interpreter binaries and application environment
+remain separately supplied inputs; this is not a process sandbox or a complete
+dependency attestation. The CLI refuses snapshots from another local scope.
+
+New snapshots carry [Git object proofs](git-object-proof.md). The supervisor checks the
+actual private tree against blob/tree/commit object identities and records that fact.
+Metadata-only checks remain distinct from actual-file verification. A self-sealed
+manifest does not prove who resolved its commit, remote repository ownership or deployed
+identity. This is not a runtime `SourceSelection`. The host does not yet populate repository observations
+or promote qualification from this manifest. Authenticated resolver/admission
+policy, reviewed lifecycle execution and hosted activation remain separate work.
+
+## Keep scenarios in one workbench
+
+Application input can be selected independently of the config and saved flows.
+`app.root` is resolved inside the selected snapshot; flows, personas and config
+continue to come from the workbench. No team config rewrite is needed.
+
+```sh
+tracegrove settings --dir ./workbench --source-snapshot ./snapshots/head/snapshot.json
+tracegrove test --config ./workbench/tracegrove.config.yaml
+tracegrove settings --dir ./workbench --working-tree
+```
+
+The CLI snapshot path is relative to the calling directory, as with the existing
+one-run `test --source-snapshot` override. The saved path is relative to the
+workbench. An explicit one-run override takes precedence over the saved choice.
+Settings preserves the agent/model/budget preferences and rejects conflicting
+input switches before writing any preference.
+
+Grove's **Settings → Verification input** offers **Check snapshot** before
+**Use this snapshot**. Checking reads and validates bytes and the launch template;
+it launches no application and writes no compile output. Saving records the
+manifest's exact reference. Replacing the manifest or changing a pinned file
+blocks runs until reviewed again; there is no automatic fallback to working tree.
+**Use working tree** clears the local selection without deleting a snapshot.
+
+The Run page separates **Next run input** from **Recorded run request**. The latter
+is reconstructed from the frozen host plans in re-verified saved evidence, even
+after a preference change. Unreadable or inconsistent evidence shows unavailable,
+never the current default. A recorded request describes local inputs; it does
+not establish that an application successfully launched or grant hosted qualification.
+Discovery's branch selector only scans routes and does not change run input.
+Python dependencies may be supplied by the workbench's `.venv` or explicit
+`app.python`; neither dependencies nor environment are sealed by the source pin.