tracegrove 0.3.0 → 0.3.1

package/docs/architecture.md

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

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

package/docs/cleanup-followups.md

@@ -1,74 +0,0 @@
-# Signed cleanup follow-ups
-
-An executing worker's cleanup report cannot release a hosted persona. A separate
-collector may sign a follow-up after observing the execution-owned resources.
-The follow-up is a new immutable record; it does not rewrite the attempt receipt.
-
-The ownership ledger supplies a `CleanupExpectation` containing the exact scope,
-attempt, worker, fencing generation, coordination version, admitted effects,
-unresolved effects and owned resource identities. HTTP absence and host stop are
-distinct obligations. The collector signs the canonical follow-up with an
-Ed25519 key kept outside the executing worker. Its scope-bound observer grant
-comes from protected control-plane configuration, not from the submitted proof.
-
-`verifyCleanupFollowup` validates the signature against that configuration and
-the complete expected manifest. It rejects unknown/revoked keys, executing-worker
-signers, altered bindings, changed resource/effect closure, unresolved effects,
-missing or wrong-kind observations, duplicate identities and stale/future evidence.
-The evidence window is at most five minutes. Status-only HTTP absence requires a
-GET/HEAD observation returning 404 or 410; a 200 response cannot qualify.
-
-The signature includes the algorithm, key ID and follow-up under the
-`tracegrove.signed-cleanup-followup/v1` domain separator. The signature field is
-excluded from signed bytes; the returned proof digest covers the complete envelope.
-The expectation digest includes every expectation field. Base64url signatures
-must use canonical unpadded encoding. Key IDs select configured public keys;
-the verifier never trusts a public key carried by the proof itself.
-
-`deriveCleanupExpectation` combines the current coordination snapshot with the
-protected ownership record. Missing host inventory prevents derivation. Admitted
-effects without independent resolution remain unresolved; extra effects and
-duplicate resources are refused. Takeover derives the current worker and fence
-while retaining prior resource identities. `ownershipLedgerHeadDigest` anchors
-the expectation to the exact canonical ledger event, including issuer receipts.
-The helper cannot establish that caller-supplied files came from that ledger.
-
-## Offline inspection
-
-```sh
-workflow-verify verify-cleanup --proof followup.json \
-  --expectation expected.json --trust observers.json --json
-```
-
-The trust file uses this shape, containing public keys only:
-
-```json
-{
-  "schemaVersion": "workflow.cleanup-observers/v1",
-  "observers": [{
-    "keyId": "configured-collector-key",
-    "scopeId": "workspace-scope",
-    "observerId": "independent-collector",
-    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
-  }]
-}
-```
-
-Exit 0 means the supplied files pass signature and expectation checks. Exit 2
-means validation failed. JSON output always reports `hostedReleaseAdmitted: false`.
-Inputs are limited to 4 MiB per file. A local trust file is useful for inspection
-and cannot configure a hosted authority or provision a signing key.
-
-## Remaining hosted requirements
-
-The control plane must independently establish ownership and provider receipts,
-qualify the collector and provision/revoke its protected signing authority.
-The storage owner must load the current expectation and lease, recheck time and
-fencing under its admission lock, then append cleanup admission and persona
-release atomically. This verifier does not implement that storage transaction,
-prove provider absence from a digest alone, or authorize compensation actions.
-Worker release through the ordinary coordination port remains refused.
-
-Local tests use ephemeral keys. One native HTTP case rejects observed presence,
-deletes an owned test resource and verifies a separately observed absence; it is
-local conformance evidence, not a qualified staging or provider receipt.

package/docs/developer-ux.md

@@ -1,315 +0,0 @@
-# Tracegrove developer UX redesign
-
-Status: phase 1 is implemented in the draft PR (see Phasing). Node, FastAPI and Django samples pass end to end through it.
-
-## The problem today
-
-Writing one HTTP test for the notes sample takes **19 YAML files across 13 folders** (`workflow.yaml`, suite, case, persona, auth recipe, component profile with a hand-pinned sha256, environment plan, host plan, runner, surface pack, surface binding, fidelity profile, intelligence policy, action registry, seed recipe, fixture plan, a materialized payload with a pinned digest, …). Every file carries `schemaVersion`, `ref.id` and `ref.revision`. Running it is four commands (`doctor`, `plan --output request.json`, `run --request`, `verify-bundle`) and the results land in `.workflow-verify/executions/<uuid>/`, a folder name nobody can find again.
-
-The kernel underneath (frozen corpus, digests, independent readback, owned cleanup, sealed bundles) is the valuable part, and it stays exactly as it is. What is missing is a front door.
-
-## Design principles
-
-1. **One config, one file per test.** Everything else is derived, with an escape hatch to the strict v1 corpus when you need it.
-2. **Convention over configuration.** Paths, ids, names and defaults come from where files live. Nothing has an id you have to invent.
-3. **Compile, don't replace.** The new files compile into the existing `workflow.*/v1` documents, so every guarantee (digests, attestation, cleanup proof, `verify-bundle`) still holds and the evidence is identical in kind.
-4. **One command to run.** `tracegrove test` plans, runs, reports and verifies. The frozen request is still written, just not by you.
-5. **Framework presets, not framework plugins.** FastAPI, Django and Node are a few lines of launch defaults, not a dependency on the user's stack.
-6. **Results you can find.** Human-named run folders, a `latest` pointer, Markdown + JSON + JUnit next to the sealed bundle.
-
-## What a user's repo looks like
-
-```text
-my-app/
-  tracegrove.config.yaml          # the only config file
-  tracegrove/                     # tests live here (configurable: testDir)
-    notes/
-      create-read-delete.flow.yaml
-      authz.flow.yaml
-    fixtures/
-      existing-note.fixture.yaml
-  .tracegrove/                    # generated, gitignored
-    runs/
-      2026-10-16T14-22-03Z_pass_3f9a1c/
-        summary.md  summary.json  junit.xml  bundle/
-      latest -> 2026-10-16T14-22-03Z_pass_3f9a1c
-    compiled/                     # the derived v1 corpus, for inspection or ejection
-    state/                        # ledger
-```
-
-## Naming conventions
-
-| Thing | Convention | Derived id |
-| --- | --- | --- |
-| Test file | `tracegrove/<area>/<behavior>.flow.yaml`, kebab-case | case id `<area>.<behavior>` |
-| Fixture file | `tracegrove/fixtures/<name>.fixture.yaml` | entity key `<name>` |
-| Step | `name:` in plain words, optional | `snake_case(name)`, else `<method>_<n>` |
-| Assertion | from a step's `expect:` | `<step>.expect` |
-| Persona | key under `personas:` | credential `<persona>_token` |
-| Saved value | `save: { noteId: note.id }` | referenced as `{noteId}` anywhere later |
-| Fixture output | `{existing.noteId}` | input from fixture `existing`, output `noteId` |
-| Tags | `tags: [smoke, authz]` | coverage tags; filter with `--tag` |
-| Run folder | `<UTC timestamp>_<outcome>_<short execution id>` | sortable, greppable |
-
-## The config file
-
-```yaml
-# tracegrove.config.yaml
-project: notes
-app:
-  adapter: node                 # node | fastapi | django | command
-  entry: app/app.mjs            # node: script; fastapi: module:app; django: manage.py dir
-  health: /health
-  sources: [app/**]             # files whose digest is attested as "what was tested"
-  env:
-    NOTES_BUILD: sample
-  inject:                       # where tracegrove hands the app its port, data dir and tokens
-    port: PORT
-    dataDir: NOTES_DIR
-    tokens: NOTES_TOKENS
-personas:
-  owner: { subject: alice }     # first persona is the default caller
-  intruder: { subject: bob }
-```
-
-Defaults when omitted: `testDir: tracegrove`, `inject` = `PORT`, `TRACEGROVE_DATA_DIR`, `TRACEGROVE_TOKENS`, `health: /health`, deadline 60 s, sources = all tracked-looking files under the app dir excluding `node_modules`, `.venv`, `__pycache__`, `.git`, `.tracegrove`.
-
-## Adapter presets
-
-| `adapter` | Launch it compiles to | Notes |
-| --- | --- | --- |
-| `node` | `node <entry>` with `PORT` set | Any Express/Fastify/Hono/Nest app that reads `PORT`. |
-| `fastapi` | `<python> -m uvicorn <entry> --host 127.0.0.1 --port {port}` | `python:` defaults to `.venv/bin/python` if present, else `python3`. |
-| `django` | `<python> manage.py migrate --noinput && <python> manage.py runserver 127.0.0.1:{port} --noreload` | Point `DATABASES` at `TRACEGROVE_DATA_DIR` for a fresh database per run (the sample does). |
-| `command` | Reserved for a qualified application-runtime adapter | Currently BLOCKED: a shell wrapper cannot attest the application interpreter. |
-
-`{port}` and `{dataDir}` are substituted in `args` and `env` values. Tracegrove picks a free loopback port itself (the "assigned" port mode), so apps no longer need to print `listening <port>`.
-
-**Auth hook.** Tracegrove issues a random bearer token per persona per run and passes `{token: subject}` as JSON in the `tokens` env var. The app adds about five lines in test mode to accept them:
-
-```python
-# FastAPI
-tokens = json.loads(os.environ.get("TRACEGROVE_TOKENS", "{}"))
-def current_user(authorization: str = Header("")):
-    sub = tokens.get(authorization.removeprefix("Bearer "))
-    if not sub: raise HTTPException(401)
-    return sub
-```
-
-```python
-# Django middleware
-TOKENS = json.loads(os.environ.get("TRACEGROVE_TOKENS", "{}"))
-def tracegrove_auth(get_response):
-    def mw(request):
-        sub = TOKENS.get(request.headers.get("Authorization", "").removeprefix("Bearer "))
-        if sub: request.user = User.objects.get_or_create(username=sub)[0]
-        return get_response(request)
-    return mw
-```
-
-```js
-// Express
-const tokens = JSON.parse(process.env.TRACEGROVE_TOKENS ?? '{}');
-app.use((req, _res, next) => { req.user = tokens[(req.headers.authorization ?? '').slice(7)]; next(); });
-```
-
-`tracegrove init` prints the right snippet for the detected framework.
-
-## A test
-
-```yaml
-# tracegrove/notes/create-read-delete.flow.yaml
-title: Create a note, read it back, keep other notes intact, delete it
-risk: critical                  # critical | standard (default) | exploratory
-tags: [notes]
-given:
-  existing: existing-note       # tracegrove/fixtures/existing-note.fixture.yaml
-steps:
-  - name: create
-    POST: /notes
-    json: { title: Fresh note, body: Written through the real API. }
-    expect: { status: 201 }
-    save: { noteId: note.id }
-
-  - name: read back
-    GET: /notes/{noteId}
-    observe: true               # independent readback, polled until it holds
-    expect: { status: 200, json: { note.title: Fresh note } }
-
-  - name: intruder is denied
-    GET: /notes/{noteId}
-    as: intruder
-    expect: { status: 403, absent: [note] }
-
-  - name: delete
-    DELETE: /notes/{noteId}
-    expect: { status: 204 }
-
-  - name: gone
-    GET: /notes/{noteId}
-    observe: true
-    expect: { status: 404 }
-
-  - name: existing note untouched
-    GET: /notes/{existing.noteId}
-    observe: true
-    expect: { status: 200, json: { note.title: Existing note } }
-```
-
-Rules: one HTTP verb key per step; use block style (or quotes) for values containing `{` or `[`, because YAML reads them as inline maps and lists; `json:` is the request body; `expect.json` keys are dot paths into the response body; `absent` lists paths that must not exist; the effect envelope (allowed methods, path prefixes, max creates) is derived from the steps and fixtures, so the safety rails stay on without being written by hand.
-
-## A fixture
-
-```yaml
-# tracegrove/fixtures/existing-note.fixture.yaml
-create:
-  POST: /notes
-  json: { title: Existing note, body: { words: 6 } }
-  expect: 201
-save: { noteId: note.id }
-readback:
-  GET: /notes/{noteId}
-  expect: { status: 200, json: { note.title: Existing note } }
-cleanup:
-  DELETE: /notes/{noteId}
-  expect: 204
-  gone: { GET: "/notes/{noteId}", status: 404 }
-```
-
-`{ words: 6 }` uses the deterministic generator; the logical payload is materialized at compile time, so there is no digest to paste.
-
-## TypeScript authoring
-
-Use `tracegrove.config.ts` instead of the YAML config for editor completion and
-shared constants. Flows and fixtures can independently use `.flow.ts` and
-`.fixture.ts`; YAML and TypeScript files can coexist when their logical names
-differ. They all compile through the same Zod schemas into the same corpus.
-
-```ts
-// tracegrove.config.ts
-import { defineConfig } from 'workflow-verify/authoring';
-
-export default defineConfig({
-  project: 'notes',
-  app: { adapter: 'node', entry: 'app/app.mjs' },
-  personas: { owner: { subject: 'alice' } },
-});
-```
-
-```ts
-// tracegrove/notes/health.flow.ts
-import { flow } from 'workflow-verify/authoring';
-
-export default flow({
-  title: 'The application is ready',
-  steps: [{ GET: '/health', expect: 200 }],
-});
-```
-
-`fixture({...})` supplies the same editor types for fixture recipes. The helpers
-preserve input values; the ordinary compiler validates and fills defaults. Run
-your TypeScript checker for editor contracts and `tracegrove check` for canonical
-runtime validation. `test`, `list`, `compile`, discovery and Grove use either
-config format. `init` preserves an existing TypeScript config.
-
-TypeScript authoring executes trusted project code, including during `check` and
-discovery; it is outside the application sandbox. Each module loads in a fresh
-Node process so edits to imported helpers are seen on the next compilation.
-Evaluation is limited to five seconds and a 1 MiB JSON-compatible default export.
-Console output does not contaminate CLI JSON. Errors report the failing module
-without forwarding arbitrary module diagnostics.
-
-Use Node 22's erasable TypeScript: include extensions on relative imports and use
-`import type` for types. Enums, parameter properties, JSX, and tsconfig path aliases
-are not transformed. The package's Node version requirement still applies. Keep
-one project config; discovery rejects competing YAML and TypeScript configs.
-An explicit `--config` on `test`, `list`, or `compile` selects a format when both
-are intentionally present.
-
-## Command reference
-
-```text
-tracegrove init                     detect FastAPI / Django / Node, write config + an example flow + .gitignore entry
-tracegrove test [--grep notes] [--tag smoke] [--json]
-                                    compile, plan, run, write the run folder, verify the bundle
-tracegrove list                     list flows with their derived ids, tags and steps
-tracegrove show [--run latest]      print a run's summary
-tracegrove compile                  write the derived v1 corpus to .tracegrove/compiled (to inspect or eject)
-```
-
-Exit codes are unchanged (0 pass, 1 assertion failure, 2 blocked, 3 infrastructure, 4 cancelled). `workflow-verify` and all of its low-level commands keep working; the compiled folder is a normal `workflow.yaml` project, so `workflow-verify plan --config .tracegrove/compiled/workflow.yaml` still works.
-
-## Output a human reads first
-
-```text
-tracegrove · notes · app sha 3e8d13bc9bd1
-
-  PASS    notes.create-read-delete   6 steps  28 ms
-  FAIL    notes.authz                3 steps  14 ms
-          step "intruder is denied": expected status 403, got 200
-          GET /notes/9c1e… -> 200 {"note":{"id":"9c1e…","title":"Fresh note"}}
-  ERROR   notes.crud                 5 steps   0 ms
-          (app startup): application exited before becoming ready; last app output:
-          | ERROR:    Error loading ASGI app. Could not import module "app.mian".
-
-1 passed, 1 failed · run .tracegrove/runs/2026-10-16T14-22-03Z_fail_3f9a1c
-```
-
-`summary.md` carries the same table plus per-step request/response excerpts; `junit.xml` lets GitHub Actions, GitLab and Buildkite annotate failures with no plugin.
-
-## Forking it into your own repo
-
-1. `npm i -D tracegrove` once it is published (today: install the packed archive, as the `tracegrove-notes-api` repo does).
-2. `npx tracegrove init` writes `tracegrove.config.yaml`, `tracegrove/example.flow.yaml` and adds `.tracegrove/` to `.gitignore`.
-3. Paste the printed auth snippet into the app's test-mode auth.
-4. `npx tracegrove test`.
-5. CI: one step, `npx tracegrove test`, then upload `.tracegrove/runs/latest` as an artifact.
-
-## Phasing
-
-| Phase | Scope | In the draft PR |
-| --- | --- | --- |
-| 1 | Config + flow + fixture compiler, node/fastapi/django presets, assigned port mode, app-output-on-startup-failure, `test`/`list`/`compile`/`show`/`init`, run folders with summary.md/json/junit, Node/FastAPI/Django samples | Yes; generic command host remains unqualified |
-| 2 | `lanes:` with an offline mock lane compiled from recorded responses; `--update-snapshots` to record them | No |
-| 3 | `tracegrove.config.ts` with `defineConfig`, `flow()` and `fixture()` for editor completion; canonical JSON Schema for YAML | Implemented through the shared compiler; no alternative executor |
-| 4 | Login-recipe personas (POST /login, cookie or token capture) for apps whose auth can't be patched; external `url:` targets with declared, unverified identity | No |
-| 5 | Browser surface using shared typed `browser:` commands, independent DOM/API checks, and verified Grove recording playback | Implemented locally; staging qualification remains open |
-
-## Structured command failures
-
-An uncaught command failure with `--json`, `--json true` or `--json=true` writes one
-`tracegrove.cli-error/v1` result to stdout and no exception diagnostic to stderr. The strict
-schema is exported as `schema/tracegrove_cli-error_v1.json` and `CliErrorReport` from the
-protocol package. For example, `tracegrove run --json` returns exit 2 and:
-
-```json
-{"schemaVersion":"tracegrove.cli-error/v1","command":"run","errorClass":"blocked","exitCode":2,"reasons":[{"code":"missing_argument","message":"A required option or option value is missing.","recovery":"Run tracegrove help and correct the command options."}],"omittedReasonCount":0}
-```
-
-Messages and recovery actions come from a controlled public vocabulary. Raw exception text,
-stacks, supplied argument values, configuration contents and arbitrary internal reason codes
-are omitted. At most 32 reasons are returned; `omittedReasonCount` reports any remainder.
-Unknown prerequisites use `prerequisite_unavailable`. Unknown command names become `command: null`.
-This trades detailed candidate diagnostics for a bounded machine result; keep private evidence
-under its existing access policy when investigating a failure.
-
-Existing process exit statuses are preserved: blocked/conflict/schema failures use 2;
-infrastructure and unexpected failures use 3. A top-level JSON parse failure retains its legacy
-exit 3 with `errorClass: invalid_input` and `invalid_json`. The report's exit code equals the
-process status. It does not assert that execution never started or authorize a retry: a failure
-can follow partial effects, and uncertain ownership must be reconciled before replay.
-
-Doctor retains `tracegrove.doctor/v1`. Completed test/run results and assertion failures retain
-their existing JSON and exit codes 0/1/2/3/4. Returned check/verification results keep their existing
-schemas. `--json false` and `--json=false` keep prose errors, and `--jsonl` keeps its existing event
-stream and top-level error behavior. Successful reports, doctor reports and artifacts are outside
-this error envelope's omission policy; this change establishes no artifact redaction guarantee.
-
-## Found along the way
-
-- The bundle verifier re-derived "infrastructure failed" only from step reason codes, so any run whose app never started produced a bundle that failed its own verification. The PR fixes this by also reading the sealed `host.failed` event; that evidence can only move a cell away from passed.
-
-## Open questions for Hope
-
-- Package and binary name: `tracegrove` for both (recommended), keeping `workflow-verify` as an alias.
-- Default test folder: `tracegrove/` (recommended) versus `tests/tracegrove/` to sit beside pytest/jest.