tracegrove 0.0.0-stage → 0.3.0

package/dist/source/gitObjectProof.js

@@ -0,0 +1,115 @@
+import { createHash } from 'node:crypto';
+import { GitSourceSnapshot, GIT_COMMIT_PROOF_LIMITS, GIT_SNAPSHOT_LIMITS, digestOfBytes, digestOfValue, sameDigest, verifySelfDigest } from "../protocol/index.js";
+import { Conflict } from "../core/errors.js";
+import { assertSnapshotPaths } from "./snapshotPaths.js";
+export function gitObjectId(type, bytes, algorithm) {
+    return createHash(algorithm).update(`${type} ${bytes.byteLength}\0`).update(bytes).digest('hex');
+}
+function decode(value, bound) {
+    const bytes = Buffer.from(value, 'base64');
+    if (bytes.length > bound || bytes.toString('base64') !== value)
+        throw new Conflict('Git object proof has noncanonical or oversized bytes');
+    return bytes;
+}
+function verify(input, actual) {
+    const snapshot = GitSourceSnapshot.parse(input);
+    if (!verifySelfDigest(snapshot) || !snapshot.commitProof)
+        throw new Conflict('Git commit proof is missing or its snapshot seal changed');
+    if (snapshot.files.reduce((sum, file) => sum + file.bytes, 0) > GIT_SNAPSHOT_LIMITS.totalBytes)
+        throw new Conflict('Git proof snapshot exceeds the total file byte bound');
+    const proof = snapshot.commitProof;
+    const algorithm = snapshot.commit.length === 40 ? 'sha1' : 'sha256';
+    const oidBytes = algorithm === 'sha1' ? 20 : 32;
+    const commit = decode(proof.commitBase64, GIT_COMMIT_PROOF_LIMITS.commitBytes);
+    const observedCommit = gitObjectId('commit', commit, algorithm);
+    if (observedCommit !== snapshot.commit)
+        throw new Conflict('Git commit object disagrees with selected snapshot commit');
+    const root = /^tree ([a-f0-9]{40}|[a-f0-9]{64})\n/.exec(commit.toString('utf8'))?.[1];
+    if (!root || root.length !== snapshot.commit.length)
+        throw new Conflict('Git commit proof has no valid root tree');
+    const trees = new Map();
+    let total = 0;
+    for (const entry of proof.trees) {
+        const bytes = decode(entry.base64, GIT_COMMIT_PROOF_LIMITS.treeBytes);
+        total += bytes.length;
+        if (total > GIT_COMMIT_PROOF_LIMITS.totalTreeBytes || trees.has(entry.objectId) ||
+            gitObjectId('tree', bytes, algorithm) !== entry.objectId)
+            throw new Conflict('Git tree object proof is duplicated, oversized or changed');
+        trees.set(entry.objectId, bytes);
+    }
+    assertSnapshotPaths(snapshot.files.map(file => file.path));
+    const declared = new Map(snapshot.files.map(file => [file.path, file]));
+    if (actual && actual.length !== declared.size)
+        throw new Conflict('Git proof needs the complete actual snapshot file closure');
+    const files = actual ? new Map(actual.map(file => {
+        const path = file.path;
+        const mode = file.mode;
+        const source = file.bytes;
+        const expected = declared.get(path);
+        if (!expected || mode !== expected.mode || !(source instanceof Uint8Array) || source.byteLength !== expected.bytes)
+            throw new Conflict('Actual snapshot bytes disagree with the declared file closure');
+        return [path, { path, mode, bytes: Buffer.from(source) }];
+    })) : null;
+    if (files && (files.size !== actual.length || files.size !== declared.size))
+        throw new Conflict('Git proof needs the complete actual snapshot file closure');
+    const visited = new Set();
+    const paths = new Set();
+    const pending = [{ id: root, prefix: '' }];
+    let nodes = 0;
+    while (pending.length) {
+        const selected = pending.pop();
+        const bytes = trees.get(selected.id);
+        if (!bytes)
+            throw new Conflict('Git tree object closure is incomplete');
+        if (!bytes.length)
+            throw new Conflict('Git snapshot cannot materialize empty Git directories');
+        visited.add(selected.id);
+        let offset = 0;
+        const names = new Set();
+        while (offset < bytes.length) {
+            if (++nodes > GIT_COMMIT_PROOF_LIMITS.nodes)
+                throw new Conflict('Git object proof exceeds the complete traversal bound');
+            const space = bytes.indexOf(32, offset);
+            const nul = bytes.indexOf(0, space + 1);
+            if (space < offset || nul <= space + 1 || nul + 1 + oidBytes > bytes.length)
+                throw new Conflict('Git tree object record is truncated');
+            const mode = bytes.subarray(offset, space).toString('ascii');
+            const name = new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(space + 1, nul));
+            if (names.has(name) || name.includes('/') || name === '.' || name === '..' || !name)
+                throw new Conflict('Git tree object has an ambiguous path');
+            names.add(name);
+            const path = selected.prefix ? `${selected.prefix}/${name}` : name;
+            assertSnapshotPaths([path]);
+            const id = bytes.subarray(nul + 1, nul + 1 + oidBytes).toString('hex');
+            offset = nul + 1 + oidBytes;
+            if (mode === '40000') {
+                pending.push({ id, prefix: path });
+                continue;
+            }
+            const entry = declared.get(path);
+            if (!['100644', '100755'].includes(mode) || !entry || entry.mode !== mode || entry.objectId !== id || paths.has(path))
+                throw new Conflict('Git object tree differs from the declared snapshot files');
+            paths.add(path);
+            if (files) {
+                const file = files.get(path);
+                if (!file || file.mode !== entry.mode || file.bytes.length !== entry.bytes || !sameDigest(digestOfBytes(file.bytes), entry.digest) ||
+                    gitObjectId('blob', file.bytes, algorithm) !== id)
+                    throw new Conflict('Actual snapshot bytes disagree with the Git commit tree');
+            }
+        }
+    }
+    if (paths.size !== declared.size || visited.size !== trees.size)
+        throw new Conflict('Git object proof has omitted files or unrelated trees');
+    return { algorithm, commit: observedCommit, tree: root, proofDigest: digestOfValue(proof) };
+}
+/** Structural object/manifest links only: cannot certify SHA-256 file bytes without reading them. */
+export function verifyGitSnapshotProofMetadata(snapshot) {
+    return { verification: 'object_links_only', binding: verify(snapshot) };
+}
+/** Hashes every actual file through its Git blob identity and the full tree/commit object closure. */
+export function verifyGitSnapshotCommit(snapshot, files) {
+    if (!Array.isArray(files))
+        throw new Conflict('actual Git source files are required');
+    return { ...verify(snapshot, files), verification: 'actual_file_bytes' };
+}
+//# sourceMappingURL=gitObjectProof.js.map

package/dist/source/gitObjectProof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitObjectProof.js","sourceRoot":"","sources":["../../src/source/gitObjectProof.ts"],"names":[],"mappings":"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"}

package/dist/source/snapshotPaths.d.ts

@@ -0,0 +1,2 @@
+/** Shared Git/transport path rules; prevent aliases before any filesystem write. */
+export declare function assertSnapshotPaths(paths: string[]): void;

package/dist/source/snapshotPaths.js

@@ -0,0 +1,24 @@
+import { RepositoryPath } from "../protocol/primitives.js";
+import { Conflict } from "../core/errors.js";
+/** Shared Git/transport path rules; prevent aliases before any filesystem write. */
+export function assertSnapshotPaths(paths) {
+    const seen = new Set();
+    const spellings = new Map();
+    for (const raw of paths) {
+        const path = RepositoryPath.parse(raw);
+        const canonical = path.normalize('NFC').toLowerCase();
+        const parts = path.split('/');
+        if (seen.has(canonical) || parts.some(part => /^(?:\.git|con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part) || /[. ]$/.test(part) || /[<>"|?*]/.test(part))) {
+            throw new Conflict('Git snapshot path is not portable or is duplicated');
+        }
+        seen.add(canonical);
+        for (let length = 1; length <= parts.length; length++) {
+            const prefix = parts.slice(0, length).join('/');
+            const key = prefix.normalize('NFC').toLowerCase();
+            if (spellings.has(key) && spellings.get(key) !== prefix)
+                throw new Conflict('Git snapshot contains aliased directory names');
+            spellings.set(key, prefix);
+        }
+    }
+}
+//# sourceMappingURL=snapshotPaths.js.map

package/dist/source/snapshotPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotPaths.js","sourceRoot":"","sources":["../../src/source/snapshotPaths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,oFAAoF;AACpF,MAAM,UAAU,mBAAmB,CAAC,KAAe;IACjD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAAC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5E,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAAC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QAC9F,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,uDAAuD,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACjK,MAAM,IAAI,QAAQ,CAAC,oDAAoD,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACpB,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,IAAI,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;YACtD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAAC,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACnG,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,MAAM;gBAAE,MAAM,IAAI,QAAQ,CAAC,+CAA+C,CAAC,CAAC;YAC7H,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/source/snapshotTree.d.ts

@@ -0,0 +1,15 @@
+import { GitSourceSnapshot, type GitCommitObservation } from '../protocol/schemas/gitSources.ts';
+export type SnapshotFile = {
+    path: string;
+    mode: '100644' | '100755';
+    bytes: Buffer;
+};
+export declare function readGitSnapshotManifest(path: string): GitSourceSnapshot;
+/** Read every pinned regular file, ignoring untracked inputs that will never enter the launch copy. */
+export declare function readGitSnapshotTree(input: unknown, sourceRoot: string): SnapshotFile[];
+export declare function readGitSnapshotSource(input: unknown, sourceRoot: string): {
+    files: SnapshotFile[];
+    gitSource: GitCommitObservation | null;
+};
+/** Exclusively create a private tree; a failed write removes only this owned directory. */
+export declare function writeGitSnapshotTree(files: SnapshotFile[], destination: string): void;

package/dist/source/snapshotTree.js

@@ -0,0 +1,79 @@
+import { lstatSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { GitSourceSnapshot, GIT_SNAPSHOT_LIMITS } from "../protocol/schemas/gitSources.js";
+import { digestOfBytes, sameDigest, verifySelfDigest } from "../protocol/canonical.js";
+import { Conflict } from "../core/errors.js";
+import { readBoundedFile } from "../core/boundedFile.js";
+import { assertSnapshotPaths } from "./snapshotPaths.js";
+import { verifyGitSnapshotCommit, verifyGitSnapshotProofMetadata } from "./gitObjectProof.js";
+export function readGitSnapshotManifest(path) {
+    let snapshot;
+    try {
+        snapshot = GitSourceSnapshot.parse(JSON.parse(readBoundedFile(path, 32 * 1024 * 1024).toString('utf8')));
+    }
+    catch {
+        throw new Conflict('Choose a bounded, regular source snapshot manifest with valid metadata');
+    }
+    if (!verifySelfDigest(snapshot))
+        throw new Conflict('Git snapshot manifest digest mismatch');
+    if (snapshot.commitProof)
+        verifyGitSnapshotProofMetadata(snapshot);
+    return snapshot;
+}
+/** Read every pinned regular file, ignoring untracked inputs that will never enter the launch copy. */
+export function readGitSnapshotTree(input, sourceRoot) {
+    return readGitSnapshotSource(input, sourceRoot).files;
+}
+export function readGitSnapshotSource(input, sourceRoot) {
+    const snapshot = GitSourceSnapshot.parse(input);
+    if (!verifySelfDigest(snapshot))
+        throw new Conflict('Git snapshot manifest digest mismatch');
+    assertSnapshotPaths(snapshot.files.map(file => file.path));
+    if (snapshot.files.reduce((sum, file) => sum + file.bytes, 0) > GIT_SNAPSHOT_LIMITS.totalBytes)
+        throw new Conflict('Git snapshot exceeds the total byte bound');
+    const root = resolve(sourceRoot);
+    const checked = new Set();
+    const directory = (path) => {
+        if (checked.has(path))
+            return;
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new Conflict('Git snapshot refuses linked or non-directory parents');
+        checked.add(path);
+    };
+    directory(root);
+    const files = snapshot.files.map(file => {
+        let parent = root;
+        for (const segment of file.path.split('/').slice(0, -1)) {
+            parent = join(parent, segment);
+            directory(parent);
+        }
+        const bytes = readBoundedFile(join(root, file.path), file.bytes, file.bytes);
+        if (!sameDigest(digestOfBytes(bytes), file.digest))
+            throw new Conflict('Git snapshot file digest mismatch');
+        return { path: file.path, mode: file.mode, bytes };
+    });
+    return { files, gitSource: snapshot.commitProof ? verifyGitSnapshotCommit(snapshot, files) : null };
+}
+/** Exclusively create a private tree; a failed write removes only this owned directory. */
+export function writeGitSnapshotTree(files, destination) {
+    if (!files.length || files.length > GIT_SNAPSHOT_LIMITS.files || files.some(file => file.bytes.length > GIT_SNAPSHOT_LIMITS.fileBytes) ||
+        files.reduce((sum, file) => sum + file.bytes.length, 0) > GIT_SNAPSHOT_LIMITS.totalBytes)
+        throw new Conflict('Git snapshot tree exceeds complete-coverage bounds');
+    assertSnapshotPaths(files.map(file => file.path));
+    mkdirSync(destination, { mode: 0o700 });
+    try {
+        for (const file of files) {
+            const path = join(destination, file.path);
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            writeFileSync(path, file.bytes, { flag: 'wx', mode: file.mode === '100755' ? 0o700 : 0o600 });
+            if (!readBoundedFile(path, file.bytes.length, file.bytes.length).equals(file.bytes))
+                throw new Conflict('snapshot bytes changed while writing');
+        }
+    }
+    catch (error) {
+        rmSync(destination, { recursive: true, force: true });
+        throw error;
+    }
+}
+//# sourceMappingURL=snapshotTree.js.map

package/dist/source/snapshotTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotTree.js","sourceRoot":"","sources":["../../src/source/snapshotTree.ts"],"names":[],"mappings":"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"}

package/docs/architecture.md

@@ -0,0 +1,126 @@
+# Tracegrove: architecture, current UX flow, and adapter gaps
+
+Status as of 2026-10-16, for this repository. "Intended" means what the protocol schemas already declare (enums for surfaces, lanes, boundaries, hosts) and what the README lists as not implemented yet.
+
+## 1. High-level architecture
+
+```text
+ you write                     compiled (derived)              kernel (unchanged)                 evidence
+ ─────────                     ──────────────────              ──────────────────                 ────────
+ tracegrove.config.yaml ─┐
+ tracegrove/**/*.flow.yaml ├─► authoring compiler ─► .tracegrove/compiled/   ─► corpus loader (freeze + sha256 refs)
+ tracegrove/fixtures/*.yaml┘    (src/authoring)        workflow.yaml, cases,     ─► planner  (side-effect free, blockers w/ owner+action)
+                                                       host, persona, recipe…    ─► admission + local ledger (single writer, idempotent)
+                                                                                 ─► executor
+                                                                                      host adapter:  local_process │ mock_loopback
+                                                                                      fixtures:      registered API actions, readback, cleanup
+                                                                                      surface driver: http │ Chromium browser
+                                                                                 ─► trusted reducer (outcome from observations)
+                                                                                 ─► bundle writer ─► verify-bundle ───────► .tracegrove/runs/<run>/
+                                                                                                                              summary.md/json, junit.xml,
+                                                                                                                              request.json, bundle/
+ tracegrove ui ─► reads config, flows, runs, git; runs `test`; scans routes for discovery
+```
+
+The [Chromium browser runner](browser-driver.md) supports short flows and the low-level corpus, with typed UI steps, DOM assertions, authenticated local personas, and sealed recordings in Grove. Supporting modules that exist but aren't wired into the everyday flow yet include shared coordination, signed cleanup follow-ups, source citations, and the plan review API.
+
+## 2. The current UX flow, end to end
+
+| Step | Today (this branch) | Intended |
+| --- | --- | --- |
+| Install | Private package; install a packed archive | `npm i -D tracegrove`, `pipx`/`uvx` shim for Python repos |
+| Set up | `tracegrove init` detects FastAPI, Django or Node and writes config + example flow | Same, plus discovery proposes the first flows |
+| Discover what to test | `tracegrove ui` scans routes (FastAPI, Django, Express/Fastify/Hono) and shows which have no flow, at a folder or a git branch | Source-selection resolver: diff-aware selection, coverage policy, AI-drafted flows reviewed through the plan review API |
+| Write tests | YAML/TypeScript flows with HTTP, browser, native job and local MCP steps, personas, saved values, fixtures | Hosted integration steps and widget-host qualification |
+| Run | `tracegrove test` (local process host, real lane) | Lanes: mock contract, recorded replay, hybrid, full live sandbox, canary; hosts: container, CI, cloud sandbox |
+| Read results | Terminal table, run folder, JUnit, `tracegrove show`, UI run history | Trace/video media, flaky-history, PR comments |
+| Prove it | `verify-bundle` re-derives the verdict from sealed evidence | Importer with issuer trust; hosted qualification lifecycle |
+
+## 3. Gaps versus intended, by layer
+
+| Layer | Supported now | Declared but not implemented |
+| --- | --- | --- |
+| Surfaces (step kinds) | HTTP, Chromium UI, local `mcp.call` through the optional SDK, and `job.submit`/`job.observe`/`job.cancel` through an opted-in local Node IPC bridge | Hosted MCP/job providers, `integration.action`, `widget.action`, native desktop and computer-use |
+| Hosts | `local_process` (POSIX), `mock_loopback` | container, managed sandbox, cloud VM, customer CI, device service; Windows process trees |
+| Fidelity lanes | `full_live_sandbox`, `mock_contract` | `recorded_replay`, `hybrid_live_product`, `full_live_canary` |
+| Boundaries | `application`, `storage` observed as real/stubbed | per-provider boundaries with interceptors and readback oracles |
+| Auth | host-issued bearer tokens per persona | `env_credential` recipes, login flows (form/cookie/OAuth), account bindings and persona leases in use |
+| Fixtures/seeding | API-created entities with readback and confirmed 404/410 cleanup; deterministic generators | DB-level seeding, snapshots/restore, factories, datasets, relation bindings in use, `update` lifecycle |
+| Oracles | HTTP status/JSON path, native job observations with real worker/store sample, browser DOM, step result | Generic DB readback, hosted queue/job state, email/webhook capture, visual baseline, LLM judge (policy exists, all stages disabled) |
+| Environments | `isolated_candidate` | deployed preview, canary, production observation |
+| Discovery | Route scan in `tracegrove ui` (heuristic) | source selection resolver, intelligence-policy-gated drafting |
+| Media | step events, network metadata | trace and video capture (`required` currently unsatisfiable) |
+
+### Integration with the verified core
+
+The integration branch also includes the immutable Git pair resolver, source citation
+validation, durable local plan review, qualification reduction and activation contracts.
+Those APIs do not make heuristic route discovery independent source confirmation or
+hosted qualification. The workbench remains a local authoring and replay interface.
+
+Node and Python presets use the same bounded interpreter observation during compilation
+and launch. Django runs migrations and starts its server through that Python executable.
+Generic shell wrappers remain blocked until a qualified host can observe their actual
+application runtime. A corrupt exported evidence bundle marks the overall run inconclusive,
+uses an inconclusive run directory and adds an evidence-integrity JUnit error, even when
+individual HTTP checks passed.
+
+## 4. Adapter gap analysis for full-stack and data-engineering work
+
+"Adapter" here means anything tracegrove needs to start, seed, fake, observe or clean up. Priority is what blocks the most real repos first.
+
+### Seeding
+
+| Need | Now | Gap and proposed adapter | Priority |
+| --- | --- | --- | --- |
+| Create records through the app's API | Yes (fixtures) | — | — |
+| Seed straight into the database (fast, bypasses API) | No | `seed.sql` adapter: run SQL/fixtures against a per-run DB, readback by SELECT, cleanup by transaction rollback or DB drop | P0 |
+| Framework factories (factory_boy, Django fixtures, Prisma seed) | No | `seed.command` adapter: run a repo command with `{dataDir}`/`DATABASE_URL`, capture emitted ids as JSON | P0 |
+| Snapshot and restore a known state | No | `seed.snapshot`: SQLite file copy / `pg_dump` template DB / `CREATE DATABASE … TEMPLATE` | P1 |
+| Large synthetic datasets for data pipelines | Generators only (words, slug, uuid, int) | dataset recipes: CSV/Parquet generators with seeds, row counts, schemas; `datasetRef` is already in the case schema | P1 |
+
+### Databases
+
+| Need | Now | Gap and proposed adapter | Priority |
+| --- | --- | --- | --- |
+| SQLite per run | Works if the app reads `TRACEGROVE_DATA_DIR` (Django/FastAPI samples) | Built-in `db: sqlite` that sets `DATABASE_URL` | P0 |
+| Postgres/MySQL per run | No | `db: postgres` service adapter: start a container or use a local server, create a throwaway database per run, inject `DATABASE_URL`, drop it on cleanup, record server version in identity | P0 |
+| Migrations | Django preset runs `migrate` | `app.setup:` commands (alembic upgrade, prisma migrate, knex) run before readiness | P0 |
+| Assert on DB state | No | `observe: { sql: "select … ", expect: … }` read-only oracle with a separate read-only connection | P1 |
+| Redis, Mongo, Elasticsearch | No | generic `services:` block with per-service health + isolation recipe | P1 |
+
+### Asynchronous jobs
+
+| Need | Now | Gap and proposed adapter | Priority |
+| --- | --- | --- | --- |
+| Start workers next to the app | `report-jobs` app starts a separate local worker; aggregate source identity includes its code | `components:` list in config: app + `celery worker`, RQ, Sidekiq, BullMQ, Dramatiq, Temporal worker; each its own supervised process, attested identity, health check | P0 |
+| Broker | No | `services: redis/rabbitmq` with per-run vhost/db index | P0 |
+| Wait for a job to finish | HTTP polling qualified against a persisted queue and separate worker; independent report readback catches false success, with cancellation, idempotency and failure controls | `job.submit` + `observe: { job: id, state: SUCCESS }` via Celery result backend / Flower API, BullMQ queue API; eager mode is explicitly not a real boundary | P1 |
+| Scheduled jobs (beat, cron) | No | logical clock control (`clockProfileRef` exists in the schema) plus a "tick" step | P2 |
+
+### Third-party services and mocks
+
+| Need | Now | Gap and proposed adapter | Priority |
+| --- | --- | --- | --- |
+| Whole-app mock (contract lane) | `mock_loopback` host with declared routes, not in the authoring layer yet | `lanes: { mock: { from: recordings/ } }` in config | P1 |
+| Fake one dependency while the app is real (Stripe, SendGrid, S3, OpenAI) | No | outbound interceptor proxy: app gets `HTTPS_PROXY`/base URL env; routes are stubbed, recorded or passed through per boundary; observations sealed as boundary evidence (`interceptorRef` exists) | P0 |
+| Record once, replay in CI | No | `recorded_replay` lane: record real calls in a sandbox account, redact, replay deterministically | P1 |
+| Provider sandboxes (Stripe test mode, etc.) | No | `env_credential` auth + `test_sandbox` account class + provider cleanup actions with signed follow-ups (verifier exists) | P2 |
+| Email/webhook capture | No | built-in inbox (SMTP sink) and webhook catcher with assertions | P1 |
+| Object storage | No | MinIO/localstack service adapter | P2 |
+
+### Data engineering
+
+| Need | Now | Gap and proposed adapter | Priority |
+| --- | --- | --- | --- |
+| Run a pipeline (Airflow DAG, Dagster job, dbt run, Spark job) | No | `job` surface with a `runner: command` that runs the pipeline against seeded inputs and records exit state and logs | P1 |
+| Assert on outputs | No | table oracles: row counts, schema, uniqueness, not-null, freshness, golden-file diff on CSV/Parquet | P1 |
+| Warehouses (BigQuery, Snowflake, DuckDB) | No | DuckDB local first; warehouse adapters with per-run schema/dataset and cleanup | P2 |
+
+## 5. Suggested order
+
+1. **P0 for full-stack repos:** `app.setup` commands, `services:` (Postgres, Redis), `components:` (workers), `db: sqlite|postgres` that injects `DATABASE_URL`, SQL and command seeding, and the outbound interceptor for third parties.
+2. **P1 for coverage:** job observe, DB-state oracle, mock lane in the authoring layer, record/replay, email/webhook capture, data-pipeline job surface with table oracles.
+3. **Qualify browser execution beyond local runs**, including staging personas, controller-death cleanup, trace/redaction collectors, and host network confinement.
+
+Each adapter keeps the kernel's rules: launched or reserved per run, identity attested, effects inside the declared envelope, cleanup confirmed by an independent read, and evidence sealed in the bundle.

package/docs/awr-delivery.md

@@ -0,0 +1,102 @@
+# Retained evidence to Agent Work Receipt
+
+This optional adapter exports a retained result as redacted AWR v0.2 and saves
+an immutable delivery intent in the existing local ledger. Delivery uses OrgX's
+existing workspace-scoped AWR importer. Import does not execute a campaign,
+complete work, qualify scenarios, or observe native outcomes. The separate
+[work-report attachment stage](work-report-attachment.md) links the imported
+report to its original work target and preserves its own retry state.
+
+Install the optional peer only when using this integration:
+
+```sh
+npm install --save-exact @useorgx/agent-work-receipt@0.3.0
+```
+
+Core SDK and ordinary CLI startup do not import that package. The optional adapter
+uses its canonical validator and content-hash helpers, without copying AWR schemas
+or implementing a competing canonicalizer.
+
+After `result-ingest`, create a protected operator-owned destination file:
+
+```json
+{"origin":"https://useorgx.com","workspaceId":"00000000-0000-4000-8000-000000000001"}
+```
+
+Replace the example UUID with your authorized workspace. The HTTPS origin must
+have no path, query, fragment, credentials, or trailing slash. The bundle cannot
+choose its destination.
+
+```sh
+tracegrove awr-prepare --sink ./retained-results --id <result-id> --destination ./destination.json --json
+tracegrove awr-inspect --sink ./retained-results --id <result-id> --json
+tracegrove awr-deliver --sink ./retained-results --id <result-id> --json
+```
+
+Preparation and inspection make no network requests. Supply the credential through
+a protected `TRACEGROVE_ORGX_TOKEN` environment variable. `--credential-env` selects
+a different variable name; never pass a credential as an argument. Tokens are not
+included in prepared records, journal entries, or transport diagnostics. Redirects
+are refused. Responses have a 32 KiB bound and 15-second deadline.
+
+The local operator controls configuration. The authenticated importer independently
+checks workspace access and admission. SDK hosts must implement
+`AwrDeliveryAuthority` against actual consumer-to-workspace policy. Local owner
+labels and no-op callbacks do not authenticate a remote tenant or grant approval.
+
+## Evidence and acceptance
+
+The receipt describes export effort. A successful export of a failing campaign is
+successful export work; the original product verdict remains visible in its summary
+and `extensions["org.tracegrove.workflow"]`. A target regression is not assigned to
+the evidence exporter as an operational failure.
+
+The shared `workflow.evidence-projection/v1` schema preserves exact request,
+selection, campaign and attempt refs, separate expected/observed target digests,
+actual recorded provenance, planned lanes, and the frozen work binding. An unbound
+run stays unbound. Raw observations, excerpts, local paths, media locations and
+credentials are withheld. Refs/digests remain potentially sensitive metadata; use
+authorized destinations. Full evidence stays in the private result archive.
+Oversize exports fail rather than silently omitting attempts.
+
+Verification remains `unverified`; acceptance remains `pending`; qualification is
+not evaluated; native outcomes are not observed. The runtime is `tracegrove`, never
+the reserved `orgx-verify`. The adapter cannot manufacture native proof, a second
+verifier lens, task acceptance, or outcome attribution.
+
+Per-attempt estimates, reconciled costs and unknown-charge counts remain in the
+projection. AWR v0.2 requires a numeric total even when unknown. The export uses
+zero with `estimated: true` and explicit `status: unknown` /
+`zero_is_schema_placeholder: true` metadata. It is not a measured zero, campaign
+total, invoice cap, or authoritative economic observation.
+
+## Recovery
+
+One retained result has one immutable destination and receipt. Preparing again
+returns the same envelope. Changing workspace or origin conflicts; editing the
+configuration cannot redirect a saved delivery. A new effort requires a new result.
+
+Before network I/O, the outbox syncs an attempt record. Missing or invalid responses
+leave `acknowledgement_unknown`. Retry with the same result ID: it reuses the exact
+receipt, destination, and digest-bound key. Receiver admission followed by connection
+loss reconciles one import. The same recovery covers a successful response followed
+by failed local acknowledgement publication. No retry path calls a runner, seeds
+data, or reruns product actions. Corrupt retained evidence blocks fresh delivery.
+
+A validated response records `imported_unverified`. Repeating delivery returns the
+saved acknowledgement without another network call; it does not renew archive
+integrity or permission. Use `results --id` for a fresh archive check. The prototype
+blocks at 1,000 attempts without evicting history. It inherits protected filesystem
+and single-writer requirements, not distributed fencing.
+
+The SDK subpath `workflow-verify/integrations/awr` exports `LocalAwrOutbox`, typed
+destination/envelope/acknowledgement contracts, `AwrDeliveryAuthority`,
+`AwrTransport`, and `OrgxAwrHttpTransport`. Supply the sink's same fenced ledger and
+scope. Credentials are retrieved only for network delivery. Trusted hosts may
+inject a transport; producers cannot select one through evidence.
+
+Conformance uses real loopback HTTP with simulated authority and admission. The
+receiver destroys the first connection after admission; reopen/retry must retain
+one receiver record, identical request bytes, and no credentials in the journal.
+This does not establish live OrgX import or native-work attachment; those require
+their own authenticated provider receipts.