tracegrove 0.0.0-stage → 0.3.1

package/docs/mcp-driver.md

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

package/docs/native-jobs.md

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

package/docs/result-sink.md

@@ -0,0 +1,87 @@
+# Independent local result retention
+
+The result sink retains complete verified bundles independently of the producer's
+run directory. It reuses the existing fenced `LocalLedger` for its index; there is
+no second database, mutable status file, or hosted service in this implementation.
+
+```sh
+tracegrove result-ingest --bundle ./run/bundle --sink ./retained-results --json
+tracegrove results --sink ./retained-results --limit 20 --json
+tracegrove results --sink ./retained-results --id <result-id> --json
+```
+
+`result-ingest` captures a bounded verified snapshot, checks the selected consumer
+scope, copies only sealed files, reads the completed archive back, and publishes
+an immutable `workflow.result-ingest/v1` receipt. Manifest and payload bytes come
+from the same snapshot that passed complete evidence reduction; the source is
+not reopened during copy. Binary artifacts retain their exact bytes. Unsealed
+files, including accidental scratch files, are not imported.
+
+SDK consumers that authenticated an earlier snapshot can pass
+`sink.ingest(bundleDir, { expectedManifestDigest })`. A mismatch is refused before
+archiving or publishing a campaign receipt. This binds retention to the authenticated
+bytes without treating the digest itself as issuer authentication.
+
+The receipt records the actual retained outcome, exact campaign/request/selection
+and fidelity-plan refs, planned fidelity lanes, manifest digest, receipt count,
+and acceptance time. A failed, cancelled, blocked, or mocked result never becomes
+a passing live result through storage. Every receipt explicitly says:
+
+```json
+{"evidenceClass":"integrity_checked_local_bundle","issuerStatus":"unverified","qualificationStatus":"not_evaluated"}
+```
+
+Exit 0 from ingestion means durable retention succeeded, including retention of
+an honestly failed attempt. Check `receipt.retainedOutcome` for the result's
+verdict. The ordinary CLI error convention remains stderr plus a nonzero exit;
+invalid or inconsistent evidence is a conflict (exit 2).
+
+## Reading and replaying deliveries
+
+Listing returns stored receipt metadata with `archiveStatus: not_checked`. It
+does not renew an earlier integrity check. Inspecting a result by ID captures and
+re-verifies the retained archive against its exact indexed manifest and refs.
+Missing or corrupted archives fail rather than echoing the recorded verdict as a
+fresh verification. Inspection keeps working when the original run is removed.
+
+Delivering the identical campaign and manifest again returns the original receipt
+with `replayed: true`; it does not append another result. Reusing that scoped
+`campaignId` with different evidence is a conflict, including renaming its result
+document reference. Even a differently serialized
+manifest is different evidence. Preserve the original manifest bytes for retries.
+
+List pages are bounded to 100 records. An opaque cursor binds the selected scope,
+index version, and offset; later deliveries do not change that page sequence.
+Cursors are pagination positions, not access grants. An exhausted 10,000-record
+prototype index blocks new admissions until an authoritative archival index is
+provided. Entries are never silently evicted.
+
+## Durability and scope
+
+Archive files and directories are synced before their immutable content-addressed
+directory is published. The archive namespace is synced before the ledger receipt
+is appended and synced. A crash between those operations can leave an unindexed
+complete object, but cannot publish an accepted receipt for an incomplete copy.
+A retry verifies that object and syncs its namespace again before publishing one receipt. Partial
+staging directories are not indexed; only a staging directory created by the
+current operation is removed on an ordinary write failure. Existing content is
+not replaced or silently repaired. The test suite includes an actual SIGKILL at
+the archive/index boundary, reopen/retry, and injected sync failure.
+
+The SDK exports `ResultSink`, `ResultSinkAuthority`, `LocalResultSink`, and
+`VerifiedBundleSnapshot`. A host supplies consumer authorization; ingestion
+rechecks it after capture and commits without an asynchronous gap. The CLI uses
+the same local operator scope as ordinary runs, with no producer-supplied scope
+override. The journal and objects are namespaced by that complete scope.
+
+The operator must provide protected, quiescent source and storage directories
+and authorize the source location before calling the SDK. The existing local
+ledger supplies one writer and stale-process recovery; this is not distributed
+fencing or a filesystem ACL against a hostile same-user process. Local owner
+labels, including `WORKFLOW_VERIFY_OWNER`, do not authenticate a remote tenant.
+
+This sink verifies integrity and record consistency. It does not authenticate an
+issuer, approve a source plan, provision qualification leases, activate coverage,
+or publish a third-party work receipt. Hosted receiver authentication, tenant delivery,
+and scoped downstream projections require their own trusted adapters. A storage receipt
+cannot stand in for those acceptance gates.

package/docs/verified-bundles.md

@@ -0,0 +1,175 @@
+# Verified bundle snapshots
+
+`verifyBundle(directory)` retains its summary response shape; invalid bundles report a null outcome instead of echoing a producer's PASS label. `readVerifiedBundle(directory)` returns the checked request, selection, campaign, per-cell receipts, frozen document map and manifest byte digest; it throws instead of returning records for an invalid bundle. These records prepare whole-round qualification evaluation but do not themselves qualify or activate a scenario.
+
+Both paths use one `BundleSnapshot`. Each listed payload is read once, checked against its sealed byte count/hash and retained privately. JSON decoding, assertion checks and campaign reduction consume those captured bytes. Mutating the directory after capture does not change that snapshot. Buffers returned by the snapshot are copies. A later verification call takes a fresh snapshot rather than caching a former success.
+
+`VerifiedBundleSnapshot.open(directory)` exposes the exact verified manifest and
+payload bytes as defensive copies for storage adapters. Its records and manifest
+digest are copies too. The [local result sink](result-sink.md) writes those
+captured bytes, verifies the completed archive, and publishes a scoped receipt
+through the existing ledger. It does not re-open producer files during copying
+or promote a storage receipt into qualification authority.
+
+The reader refuses traversal, duplicate paths, symlinks and nonregular files. Reads are bounded to the expected size plus one byte so growth is detected without loading an arbitrarily larger file. Current prototype bounds are 1 MiB for the manifest, 16 MiB per file, 64 MiB of payload and 10,000 files. Oversize bundles fail verification; files are never truncated or silently omitted. Larger media packs need an explicitly supported bounded reader.
+
+Campaign verification rechecks complete receipt bindings, missing cells, coverage and proof eligibility, as well as full request/selection/campaign scope and reference identity. Per-cell checks bind exact case/persona/surface/variant and qualification-admission refs. The outcome label alone cannot cover inconsistent campaign metadata.
+
+Target comparison checks every target metadata field and each required component's
+kind and identity. Current hosts supply component attestations and, when explicitly
+bound, verified pinned Git-object repository observations. Remote ownership,
+release, schema, flag, browser, container and model metadata remain unobserved.
+Requesting those fields cannot fill their observations; a required mismatch blocks
+the run before fixtures or steps. The saved-bundle reader reconstructs the observed
+tuple from the captured host attestations too, so inventing matching expected and
+observed metadata and recomputing all file/document hashes cannot create passing
+source or deployment evidence. Unsupported target observations need a real host
+contract before they can qualify. Honest blocked attempts retain their evidence.
+
+An optional source-snapshot binding covers local launch content. Its frozen
+manifest must match the admitted scope and supervisor observation; every attested
+identity file must belong to that manifest with the same bytes. The reader also
+recomputes the source digest from those file observations. This binds captured
+local content. The [Git proof guide](git-object-proof.md) describes the separate
+actual-file object check and opt-in repository role. Neither establishes remote
+ownership, deployment identity or hosted issuer trust.
+
+This is integrity and record-consistency verification. A passing mocked bundle retains its mocked proof boundary. It is not live qualification, trusted issuer identity, tenant authorization or production acceptance. The host must authorize a quiescent artifact directory and apply its own issuer/admission policy. The snapshot API is not a remote filesystem ACL or a defense against a hostile process replacing parent directories during capture.
+
+## Atomic local export
+
+`exportVerifiedBundle(source, output)` captures and reduces one bounded snapshot, writes only its sealed bytes into a private sibling staging directory, verifies the staged copy, and renames it into a fresh output directory. The manifest comes from that same snapshot; unlisted host/private files are excluded. The CLI `export` and authoring `test` use this path. CLI JSON includes `published`; invalid source evidence publishes no output. Existing outputs are never merged or overwritten, including an empty directory.
+
+Files and directory entries are synced before acknowledgement, including newly created ancestor entries. Content-addressed object publication uses an exclusive hard link, unique temporary storage, bounded no-follow readback and a single digest-checked read. A preexisting corrupt object is retained and reported, never silently replaced. Preexisting symlink ancestors are rejected before directory creation. These operations require a supported owned local filesystem with directory fsync and hard links; unsupported filesystem behavior fails rather than claiming durability.
+
+Cooperating exporters share an exclusive sibling publication lock. A writer crash can leave its private staging directory and lock; the destination is absent or contains the complete verified bundle. Locks are never automatically broken. The operator must establish that the writer is gone and inspect the owned staging/output state before a separately authorized cleanup/retry; do not blindly remove a lock belonging to another writer. If final parent sync fails after rename, the command reports that publication durability is unconfirmed: the complete output may exist, so verify it before retrying and do not overwrite it.
+
+Tests include concurrent independent publishers, actual writer SIGKILL during a payload write, source mutation after snapshot capture, corrupt objects, symlink/no-effect refusal and injected write/sync failures. This establishes local process-crash behavior and fsync ordering, not physical power-loss qualification, arbitrary hostile-parent confinement, distributed fencing, automatic recovery or provider attestation.
+
+## Durable original execution seal
+
+`writeExecutionBundle` now persists the original execution records before acknowledging the
+source seal, rather than relying on a later exported copy. Cell and final payload files are created
+exclusively and fsynced. Existing cell payloads are re-read through the bounded no-follow reader,
+synced as regular files, and their directories are synced before final publication. Existing
+payloads or manifests are never overwritten, including corrupt bytes left by an interrupted write.
+
+The writer builds the existing v1 manifest in a unique private `.bundle-pending-*` directory.
+An internal candidate snapshot checks its bounded payload hashes and performs the same complete
+frozen-record, assertion and campaign reduction as the public verifier. The verified receipt set
+must also match the final records supplied by the executor. Only then does an exclusive hard link
+publish `manifest.json`, followed by directory fsync. The executor's ledger finalization follows
+the returned source seal. The bundle format and public reader contract are unchanged: a candidate
+without a published manifest is never a valid public bundle.
+
+The caller must own a quiescent local execution tree and retain its existing ledger writer.
+An exclusive `.bundle-write.lock` serializes cooperating source writers. A write/sync/candidate
+failure or process death retains its incomplete records, lock and any manifest staging for explicit
+reconciliation; no stale lock is automatically removed and no assertion is retried. A manifest
+that became visible before a later directory sync failure is reported as published with durability
+unconfirmed, rather than removed or overwritten. Verify that existing bundle before any retry.
+
+Tests cover actual SIGKILL before the manifest link and after its first directory fsync, injected
+payload write/fsync failures, corruption during manifest staging, a hash-consistent candidate
+whose campaign disagrees with reduction, existing corrupt payload preservation, linked-parent
+refusal and post-publication sync uncertainty. A process crash can leave an invalid incomplete
+source or a complete verifiable source with reconciliation remnants. These bounded local tests
+do not simulate physical power loss, establish hostile-writer confinement, distributed fencing,
+provider/host qualification, or transactional recovery across the separate ledger and bundle seal.
+
+## Local commit-window readback
+
+If a controller dies after the original manifest commits but before ledger finalization, local
+redelivery first requires the existing durable ownership inventory to show acknowledged removal
+of every resource. It then verifies and reduces the entire committed bundle and binds its exact
+request/selection, scope, execution/attempt/generation, attempt number, idempotency key and
+per-cell receipt references to the trusted ledger. Only a matching commit can reconstruct the
+original summary, sync the manifest's directory and append the missing `finalized` transition.
+A failed recovery directory sync leaves finalization blocked with durability unconfirmed.
+It returns checked receipts and
+starts no second host or fixture. A manifest's mere presence or a producer PASS label is insufficient.
+
+Finalized redelivery also reads this bound committed evidence instead of trusting the cached
+summary containing an empty receipt list. Missing, corrupt or foreign finalized evidence fails
+closed without acquisition. Interrupted attempts without a committed manifest retain the existing
+retry policy and ownership gate; this readback does not repair incomplete files or invent cleanup.
+Actual controller SIGKILL immediately before the ledger finalization write, zero-launch readback,
+unknown ownership, corrupt/foreign/missing evidence and false cached summary are regression-tested.
+This is local reconciliation under one ledger writer, not a distributed transaction or a claim that
+physical power loss was simulated.
+
+## Inspect and hand off a frozen run
+
+```sh
+tracegrove inspect --request ./frozen.json --json
+tracegrove rerun --request ./frozen.json --output ./next-attempt.json
+tracegrove run --request ./next-attempt.json --state-dir ./state
+tracegrove inspect --execution <id> --state-dir ./state --json
+tracegrove inspect --bundle ./exported-evidence --failed-step --json
+tracegrove export --execution <id> --state-dir ./state --output ./new-export
+```
+
+`inspect --request` uses the typed frozen transport envelope and static executable
+closure checks. It reports requested refs, selected cells, a closure digest, blockers
+and whether a qualification owner is required. `executionAuthority: not_checked`
+means exactly that: inspection does not query an approval owner, probe a runtime,
+start an application, provision state or grant effects. It needs no mutable project
+YAML. A blocked structure exits 2; a valid structure exits 0.
+
+The CLI reads frozen envelopes from bounded regular files (96 MiB maximum), rejects
+unknown envelope fields and checks document keys and seals before rerun. A trial or
+work-proof rerun retains the exact frozen case/persona/target selection, assigns fresh
+campaign/request identities and records `replayOf`. Its documents are independent
+copies of the original. Qualification/lifecycle requests cannot use `rerun` to erase
+registration; use the current owning registry to admit a new independent round and
+`prepareQualificationExecution` to bind it.
+
+Execution inspection first captures and independently verifies the complete evidence
+bundle. It never reports an unverified producer PASS. `--bundle` supports evidence
+outside the original state directory; `--execution` requires one safe path segment
+and a state directory. `--failed-step` is the explicit path for failed observation
+payloads. Ordinary summaries retain compact step/assertion labels. Successful
+inspection exits 0 even when the verified product outcome is a failure; read `outcome`.
+Invalid evidence exits 2 and reports no success summary.
+
+The CLI `export` uses the atomic local export described above. The library also exports
+`exportCapturedBundle(snapshot, output)`, which writes a `VerifiedBundleSnapshot`'s captured
+sealed bytes through the same file writer as the result archive. It never rereads the producer directory or copies
+unlisted scratch files or workspaces. The output must be a new directory. Files are
+exclusive, the manifest is written last, and completed output is reverified. Failed
+writes remove only the newly allocated output; existing destinations and links are
+left intact. Capturing before the producer disappears still permits export afterward.
+
+The library exports the `FrozenBundle`, `FrozenPlanInspection`, `ExecutionInspection`
+and `FailedStepInspection` Zod schemas with the corresponding reader/inspection
+functions. These local projections are not new execution authority or outcome records.
+
+
+## Runner compatibility
+
+A frozen runner profile is evidence of the selected configuration, not permission to
+substitute the verifier's current runner identity. `verify-bundle --json` and failed verified
+exports may include `diagnostics` with schema `tracegrove.runner-compatibility/v1`:
+
+- `runner_profile_missing`: no valid, self-digest-checked profile reproduces the requested runner kind.
+- `runner_capability_revision_unsupported`: a valid matching profile is present, but this verifier
+  cannot reproduce the requested capability revision.
+- `runner_capability_digest_mismatch`: the kind and revision are supported, but the exact capability
+  digest cannot be reproduced from the frozen profiles. Investigate the producer/profile mismatch.
+
+The diagnostic includes the exact `requestedRunner` ref and up to 32 matching valid profiles with
+`reproducedRunner` refs. It always says `verification: "not_completed"`; it never grants a historical
+outcome. Unsupported evidence still returns `ok: false`, `outcome: null`, and CLI exit 2. Other
+integrity failures retain their own errors and need not produce a compatibility diagnostic.
+
+Preserve the original bytes and manifest. Do not edit or reseal references, choose a runner by
+step names, or replace a requested revision merely because the case uses a subset of its operations.
+For historical inspection, use the producer's recorded compatible verifier and pinned dependency
+closure. An npm version alone may be insufficient for an unpublished build; retain its source commit
+and package integrity too. To qualify a current runtime, perform a new authorized execution, preserving
+both attempts and their distinct identities. This is a new qualification, not a migration of old proof.
+
+For example, a valid browser profile captured by an unreleased verifier with capability revision
+`0.3.0` cannot be reproduced by a verifier that implements only `0.1.0`. That is an unsupported reader
+boundary, not proof that the profile is absent or that either workflow passed now. These diagnostics
+do not add historical runner implementations, alter accepted evidence, or grant replay authority.

package/package.json

@@ -1,6 +1,100 @@
 {
   "name": "tracegrove",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "private": false,
+  "description": "Verify app behavior with real requests, independent readback and inspectable evidence.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.0 <23"
+  },
+  "bin": {
+    "tracegrove": "./dist/cli/main.js",
+    "workflow-verify": "./dist/cli/main.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./integrations/awr": {
+      "types": "./dist/integrations/awr/index.d.ts",
+      "default": "./dist/integrations/awr/index.js"
+    },
+    "./authoring": {
+      "types": "./dist/authoring/index.d.ts",
+      "default": "./dist/authoring/index.js"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol/index.d.ts",
+      "default": "./dist/protocol/index.js"
+    },
+    "./coordination": {
+      "types": "./dist/core/coordination.d.ts",
+      "default": "./dist/core/coordination.js"
+    }
+  },
+  "files": [
+    "dist",
+    "schema",
+    "samples",
+    "docs/getting-started.md",
+    "docs/agent-guide.md",
+    "docs/local-execution-recovery.md",
+    "docs/verified-bundles.md",
+    "docs/browser-driver.md",
+    "docs/native-jobs.md",
+    "docs/mcp-driver.md",
+    "LICENSE",
+    "README.md",
+    "docs/result-sink.md",
+    "docs/git-object-proof.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json && node scripts/copy-samples.mjs",
+    "typecheck": "tsc --project tsconfig.json --noEmit && tsc --project tsconfig.container.json --noEmit",
+    "test": "vitest run",
+    "test:conformance": "vitest run conformance/",
+    "test:django": "vitest run --config vitest.django.config.ts",
+    "test:container": "node scripts/container-conformance.mjs",
+    "schema:export": "node --import tsx scripts/export-schemas.ts",
+    "schema:check": "node --import tsx scripts/export-schemas.ts --check && node --import tsx scripts/export-environment-examples.ts --check",
+    "test:onboarding": "node scripts/readme-onboarding.mjs && node scripts/readme-onboarding-negative.mjs",
+    "verify": "npm run typecheck && npm run schema:check && npm run test"
+  },
+  "dependencies": {
+    "playwright": "1.64.1",
+    "yaml": "2.9.1",
+    "zod": "4.6.5"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@useorgx/agent-work-receipt": "0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "@useorgx/agent-work-receipt": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@useorgx/agent-work-receipt": "0.3.0",
+    "@types/node": "22.19.1",
+    "tsx": "4.23.15",
+    "typescript": "5.9.3",
+    "vitest": "5.0.3"
+  },
+  "keywords": [
+    "testing",
+    "workflow",
+    "verification",
+    "cli",
+    "evidence"
+  ],
+  "homepage": "https://www.npmjs.com/package/tracegrove"
+}

package/samples/django-notes/manage.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python
+import os
+import sys
+
+if __name__ == "__main__":
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "notesite.settings")
+    from django.core.management import execute_from_command_line
+    execute_from_command_line(sys.argv)

package/samples/django-notes/notes/auth.py

@@ -0,0 +1,14 @@
+"""Test-mode auth: tracegrove issues one random bearer token per persona per run."""
+import json
+import os
+
+TOKENS = json.loads(os.environ.get("TRACEGROVE_TOKENS", "{}"))
+
+
+def tracegrove_auth(get_response):
+    def middleware(request):
+        header = request.headers.get("Authorization", "")
+        request.subject = TOKENS.get(header.removeprefix("Bearer "))
+        return get_response(request)
+
+    return middleware

package/samples/django-notes/notes/migrations/0001_initial.py

@@ -0,0 +1,19 @@
+import uuid
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+    dependencies = []
+    operations = [
+        migrations.CreateModel(
+            name="Note",
+            fields=[
+                ("id", models.UUIDField(default=uuid.uuid4, primary_key=True, serialize=False)),
+                ("owner", models.CharField(max_length=200)),
+                ("title", models.CharField(max_length=200)),
+                ("body", models.TextField()),
+            ],
+        ),
+    ]

package/samples/django-notes/notes/models.py

@@ -0,0 +1,13 @@
+import uuid
+
+from django.db import models
+
+
+class Note(models.Model):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
+    owner = models.CharField(max_length=200)
+    title = models.CharField(max_length=200)
+    body = models.TextField()
+
+    def as_json(self):
+        return {"id": str(self.id), "owner": self.owner, "title": self.title, "body": self.body}

package/samples/django-notes/notes/views.py

@@ -0,0 +1,33 @@
+import json
+
+from django.http import HttpResponse, JsonResponse
+
+from .models import Note
+
+
+def health(request):
+    return JsonResponse({"ok": True})
+
+
+def notes(request):
+    if not request.subject:
+        return JsonResponse({"error": "unauthorized"}, status=401)
+    if request.method == "POST":
+        data = json.loads(request.body or "{}")
+        note = Note.objects.create(owner=request.subject, title=data["title"], body=data["body"])
+        return JsonResponse({"note": note.as_json()}, status=201)
+    return JsonResponse({"notes": [n.as_json() for n in Note.objects.filter(owner=request.subject)]})
+
+
+def note(request, note_id):
+    if not request.subject:
+        return JsonResponse({"error": "unauthorized"}, status=401)
+    found = Note.objects.filter(id=note_id).first()
+    if found is None:
+        return JsonResponse({"error": "not_found"}, status=404)
+    if found.owner != request.subject:
+        return JsonResponse({"error": "forbidden"}, status=403)
+    if request.method == "DELETE":
+        found.delete()
+        return HttpResponse(status=204)
+    return JsonResponse({"note": found.as_json()})