tracegrove 0.0.0-stage → 0.3.0

package/docs/work-report-attachment.md

@@ -0,0 +1,127 @@
+# Attach a retained report to existing work
+
+Receipt import and work attachment are separate delivery stages. An import can be
+acknowledged while attachment is still prepared, unknown, or awaiting review.
+Neither stage approves or completes work.
+
+Bind the work before execution. For example, an operator-owned `work-binding.json`:
+
+```json
+{"workId":"00000000-0000-4000-8000-000000000003","requirementRefs":[]}
+```
+
+Replace the example with the actual work UUID and agreed requirement refs. Empty
+requirement refs do not assert a native work contract or permission to complete it.
+Planning freezes the parsed binding into the request digest:
+
+```sh
+tracegrove plan --config ./verification/workflow.yaml --purpose work_proof --work-binding ./work-binding.json --output ./request.json
+tracegrove run --request ./request.json --state-dir ./run-state --json
+```
+
+An unbound historical campaign cannot acquire a work binding during export.
+Run a new, explicitly bound campaign if it is genuinely a new requested effort.
+Normal unbound planning remains unchanged. SDK callers supply the same typed
+`workBinding` to `plan`; it is copied and validated before planning.
+
+Ingest and import the result using the [result sink](result-sink.md) and
+[AWR delivery](awr-delivery.md). After import acknowledgement, create a protected
+`target.json` with the actual work type, the same full UUID, its native workspace,
+and the exact native `updated_at` value. Preserve timestamp precision and offset:
+
+```json
+{"entityType":"task","entityId":"00000000-0000-4000-8000-000000000003","workspaceId":"00000000-0000-4000-8000-000000000001","expectedUpdatedAt":"2026-10-18T01:00:00.123456Z"}
+```
+
+```sh
+tracegrove report-prepare --sink ./retained-results --id <result-id> --target ./target.json --json
+tracegrove report-inspect --sink ./retained-results --id <result-id> --json
+tracegrove report-attach --sink ./retained-results --id <result-id> --json
+```
+
+Preparation and inspection are offline. Attachment uses the protected credential
+environment described in the AWR guide. It calls the existing authenticated receipt
+read endpoint with the frozen workspace UUID, then the existing artifact-create
+endpoint with a stable Idempotency-Key header and deterministic artifact UUID.
+The snapshot workspace must match the frozen import destination. Preparation
+requires a timestamp supplied from an authorized native work read; it does not
+fetch or invent one. The examples are placeholders, not observed work state.
+The API receives `expected_scope.workspace_id` and
+`expected_scope.expected_updated_at` on every attempt. The snapshot is a condition
+on attachment admission, not proof that execution tested that work revision.
+The returned artifact must match the exact workspace, work type/ID, report link,
+evidence metadata, and artifact UUID before the sender records acknowledgement.
+
+The report link is the existing private OrgX work-ledger receipt page. It does not
+create another object store or save an expiring signed URL. Before each fresh
+attachment attempt, the sender compares the full hosted receipt's canonical bytes
+with the frozen receipt digest and freshly checks the retained local archive.
+A substituted report, missing import, foreign target ID, or corrupted archive blocks
+the attempt. Changing a target type, workspace or timestamp after preparation also
+conflicts. Projects, initiatives, workstreams, milestones and tasks are supported.
+
+The artifact is born `in_review`, with `external_unverified` provenance and an
+explicit product verdict in its preview. A failed product campaign stays failed;
+attaching its evidence does not label the product as passing. The link serves the
+redacted imported report, not the full local bundle, recordings or raw observations.
+Protected publication of those additional bytes remains a separate integration.
+
+## Independent retries
+
+The attachment outbox stores a separate immutable intent and acknowledgement from
+the AWR import. Both stages reuse `LocalDeliveryJournal`, which owns bounded
+attempt history, synced intent/attempt/acknowledgement records, version checks and
+in-flight exclusion on the existing fenced ledger. Existing AWR journal event names
+and receipt shapes remain readable; no migration or extra database is introduced.
+
+If artifact creation succeeds but the response is lost, attachment becomes
+`acknowledgement_unknown`. Reopen and retry with the same result ID: the exact
+payload, artifact UUID and idempotency key are reused. A failed local acknowledgement
+write is recovered the same way. Receipt import is not repeated, and no runner,
+fixture seeder or completion service is invoked. A confirmed retry reports
+`attached`, with a separate `recordedArtifactStatus`. Evaluation or human review
+may have changed that status since creation; a retry records the returned status
+without confusing it with delivery or native work acceptance. Historical
+acknowledgement is not a fresh read; acknowledged retries make no network call.
+
+The scoped intent uses `workflow.report-attachment/v2`. A v1 journal has no atomic
+snapshot and is refused with a reconciliation message. Keep that journal and
+reconcile any prior artifact with the original sender; this version does not
+rewrite it, silently attach a snapshot later, or generate a replacement identity.
+
+## Host authority and limits
+
+`LocalReportAttachmentOutbox` exports typed `ReportAttachmentAuthority` and
+`ReportAttachmentTransport` ports. The authority must resolve the target's actual
+type, owner and workspace and authorize the side effects, including any artifact
+evaluation costs. It is checked after readback and immediately before recording a
+POST attempt. A lost response does not turn into a new approval grant.
+
+The CLI represents a local operator's explicit configuration. Local labels and
+no-op callbacks do not authenticate a tenant. Scoped attachment requires the
+native API and migration in [OrgX #3663](https://github.com/hopeatina/orgx/pull/3663).
+That transaction checks workspace ownership, locks the work target, and compares
+the frozen workspace and timestamp before insertion. Matching historical retries
+return the original artifact after a work change, subject to current workspace
+access. The sender makes no separate mutable target read before POST and has no
+unscoped fallback. An older strict API rejects the unknown scope field; a missing
+native function must fail without a direct insert. Deploy the native migration
+and API before using scoped delivery. Hosted tenant qualification still needs
+live acceptance evidence; local transport tests do not establish it.
+
+A native HTTP 409 produces a conflict with instructions to preserve the delivery
+and reconcile its receipt. HTTP 400/401/403/404/422 blocks delivery and asks the
+operator to check scope, access and contract support. Provider response text is
+discarded. Connection loss, throttling and unavailable services retain an unknown
+acknowledgement and the same retry key. None of these errors refreshes the
+timestamp, strips the assertion, reimports the receipt or reruns the campaign.
+
+`OrgxReportAttachmentHttpTransport` reuses the import transport's credential,
+same-origin, redirect, deadline and bounded-response handling. It exposes no work
+completion or outcome API. Full native proof, task acceptance, delayed outcomes,
+live hosted qualification, and actual widget-host/mobile packs remain separate gates.
+
+Conformance runs import/readback/attachment over real loopback HTTP with simulated
+native authorization and storage. It drops the first artifact acknowledgement after
+admission, reopens the sender, and requires one import, one artifact, identical POST
+bytes, separate stage states, and no completion calls. It is not live OrgX evidence.

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "tracegrove",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "private": false,
+  "description": "tracegrove: behaviour tests against your real app, drafted by Claude Code or Codex, sealed as re-verifiable 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/cleanup-followups.md", "docs/source-review.md", "docs/source-promotion.md", "docs/git-source-resolution.md", "docs/git-object-proof.md", "docs/local-review-store.md", "docs/local-scenario-store.md", "docs/local-execution-recovery.md", "docs/qualification-registration.md", "docs/qualification-results.md", "docs/replay-assessment.md", "docs/scenario-activation.md", "docs/scenario-structure.md", "docs/verified-bundles.md", "docs/developer-ux.md", "docs/architecture.md", "docs/browser-driver.md", "docs/portable-environments.md", "docs/examples/portable-environments", "docs/native-jobs.md", "docs/result-sink.md", "docs/awr-delivery.md", "docs/work-report-attachment.md", "docs/mcp-driver.md", "conformance/coordination-vectors.json", "LICENSE", "README.md", "docs/images/ui-run.png"],
+  "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"
+  }
+}

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()})

package/samples/django-notes/notesite/settings.py

@@ -0,0 +1,17 @@
+"""Tracegrove sample: minimal Django notes API. The database lives in the per-run data dir."""
+import os
+
+SECRET_KEY = "tracegrove-sample-not-secret"
+DEBUG = True
+ALLOWED_HOSTS = ["127.0.0.1", "localhost"]
+INSTALLED_APPS = ["notes"]
+MIDDLEWARE = ["notes.auth.tracegrove_auth"]
+ROOT_URLCONF = "notesite.urls"
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": os.path.join(os.environ.get("TRACEGROVE_DATA_DIR", "."), "db.sqlite3"),
+    }
+}
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
+USE_TZ = True

package/samples/django-notes/notesite/urls.py

@@ -0,0 +1,9 @@
+from django.urls import path
+
+from notes import views
+
+urlpatterns = [
+    path("health", views.health),
+    path("notes", views.notes),
+    path("notes/<uuid:note_id>", views.note),
+]

package/samples/django-notes/requirements.txt

@@ -0,0 +1 @@
+django==6.1.2

package/samples/django-notes/tracegrove/notes/crud.flow.yaml

@@ -0,0 +1,27 @@
+title: Create, read, deny a stranger and delete a note
+tags: [notes]
+steps:
+  - name: create
+    POST: /notes
+    json: { title: Fresh note, body: from Django }
+    expect: 201
+    save: { noteId: note.id }
+
+  - name: read back
+    GET: /notes/{noteId}
+    observe: true
+    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: 204
+
+  - name: gone
+    GET: /notes/{noteId}
+    observe: true
+    expect: 404

package/samples/django-notes/tracegrove.config.yaml

@@ -0,0 +1,7 @@
+project: django-notes
+app:
+  adapter: django
+  sources: ["**/*.py"]
+personas:
+  owner: { subject: alice }
+  intruder: { subject: bob }

package/samples/fastapi-notes/app/main.py

@@ -0,0 +1,69 @@
+"""Tracegrove sample: a FastAPI notes API backed by SQLite in the per-run data dir."""
+import json
+import os
+import sqlite3
+import uuid
+
+from fastapi import Depends, FastAPI, Header, HTTPException, Response
+from pydantic import BaseModel
+
+DB = os.path.join(os.environ.get("TRACEGROVE_DATA_DIR", "."), "notes.sqlite3")
+# Test-mode auth: tracegrove issues one random bearer token per persona per run.
+TRACEGROVE_TOKENS = json.loads(os.environ.get("TRACEGROVE_TOKENS", "{}"))
+
+app = FastAPI()
+
+
+def db() -> sqlite3.Connection:
+    conn = sqlite3.connect(DB)
+    conn.row_factory = sqlite3.Row
+    conn.execute("create table if not exists notes (id text primary key, owner text, title text, body text)")
+    return conn
+
+
+def current_user(authorization: str = Header("")) -> str:
+    subject = TRACEGROVE_TOKENS.get(authorization.removeprefix("Bearer "))
+    if not subject:
+        raise HTTPException(status_code=401, detail="unauthorized")
+    return subject
+
+
+class NoteIn(BaseModel):
+    title: str
+    body: str
+
+
+@app.get("/health")
+def health():
+    return {"ok": True}
+
+
+@app.post("/notes", status_code=201)
+def create(note: NoteIn, user: str = Depends(current_user)):
+    row = {"id": str(uuid.uuid4()), "owner": user, "title": note.title, "body": note.body}
+    with db() as conn:
+        conn.execute("insert into notes values (:id, :owner, :title, :body)", row)
+    return {"note": row}
+
+
+def owned(note_id: str, user: str) -> dict:
+    with db() as conn:
+        row = conn.execute("select * from notes where id = ?", (note_id,)).fetchone()
+    if row is None:
+        raise HTTPException(status_code=404, detail="not_found")
+    if row["owner"] != user:
+        raise HTTPException(status_code=403, detail="forbidden")
+    return dict(row)
+
+
+@app.get("/notes/{note_id}")
+def read(note_id: str, user: str = Depends(current_user)):
+    return {"note": owned(note_id, user)}
+
+
+@app.delete("/notes/{note_id}", status_code=204)
+def delete(note_id: str, user: str = Depends(current_user)):
+    owned(note_id, user)
+    with db() as conn:
+        conn.execute("delete from notes where id = ?", (note_id,))
+    return Response(status_code=204)

package/samples/fastapi-notes/requirements.txt

@@ -0,0 +1,2 @@
+fastapi==0.143.3
+uvicorn==0.54.0

package/samples/fastapi-notes/tracegrove/notes/crud.flow.yaml

@@ -0,0 +1,27 @@
+title: Create, read, deny a stranger and delete a note
+tags: [notes]
+steps:
+  - name: create
+    POST: /notes
+    json: { title: Fresh note, body: from FastAPI }
+    expect: 201
+    save: { noteId: note.id }
+
+  - name: read back
+    GET: /notes/{noteId}
+    observe: true
+    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: 204
+
+  - name: gone
+    GET: /notes/{noteId}
+    observe: true
+    expect: 404

package/samples/fastapi-notes/tracegrove.config.yaml

@@ -0,0 +1,8 @@
+project: fastapi-notes
+app:
+  adapter: fastapi
+  entry: app.main:app
+  sources: [app/**/*.py]
+personas:
+  owner: { subject: alice }
+  intruder: { subject: bob }

package/samples/notes-api/app/app.mjs

@@ -0,0 +1,67 @@
+// Tracegrove sample: a real file-backed notes API. No dependencies. Not a mock.
+// Env: PORT, NOTES_DIR, NOTES_TOKENS (JSON object token -> userId), NOTES_BUILD (display only).
+import { createServer } from 'node:http';
+import { mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { send, readBody } from './http.mjs';
+
+const port = Number(process.env.PORT ?? 0);
+const dir = process.env.NOTES_DIR ?? './notes-data';
+const tokens = JSON.parse(process.env.NOTES_TOKENS ?? '{}');
+const build = process.env.NOTES_BUILD ?? 'dev';
+mkdirSync(dir, { recursive: true });
+
+function notePath(id) { if (!/^[0-9a-f-]{36}$/.test(id)) return null; return join(dir, `${id}.json`); }
+function readNote(id) { const p = notePath(id); if (!p || !existsSync(p)) return null; return JSON.parse(readFileSync(p, 'utf8')); }
+function writeNote(note) { const p = notePath(note.id); const tmp = `${p}.tmp`; writeFileSync(tmp, JSON.stringify(note)); renameSync(tmp, p); }
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+  if (req.method === 'GET' && url.pathname === '/health') {
+    const count = readdirSync(dir).filter((f) => f.endsWith('.json')).length;
+    return send(res, 200, { ok: true, build, notes: count });
+  }
+  const auth = req.headers.authorization ?? '';
+  const token = auth.startsWith('Bearer ') ? auth.slice(7) : null;
+  const userId = token ? tokens[token] : undefined;
+  if (!userId) return send(res, 401, { error: 'unauthorized' });
+  if (req.method === 'GET' && url.pathname === '/ui') {
+    res.writeHead(200, { 'content-type': 'text/html' });
+    res.end(`<!doctype html><html lang="en"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Notes</title>
+      <main><h1>Notes</h1><button onclick="fetch('/notes').then(r=>r.json()).then(data=>document.querySelector('[role=status]').textContent=data.notes.map(n=>n.title).join(', '))">Refresh</button>
+      <p role="status" data-testid="notes">Not loaded</p></main></html>`);
+    return;
+  }
+  const match = url.pathname.match(/^\/notes(?:\/([^/]+))?$/);
+  if (!match) return send(res, 404, { error: 'not_found' });
+  const id = match[1];
+  try {
+    if (req.method === 'POST' && !id) {
+      const body = await readBody(req);
+      if (typeof body.title !== 'string' || typeof body.body !== 'string') return send(res, 400, { error: 'invalid_note' });
+      const note = { id: randomUUID(), title: body.title, body: body.body, ownerId: userId, createdAt: new Date().toISOString() };
+      writeNote(note);
+      return send(res, 201, { note });
+    }
+    if (req.method === 'GET' && !id) {
+      const notes = readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => JSON.parse(readFileSync(join(dir, f), 'utf8'))).filter((n) => n.ownerId === userId);
+      return send(res, 200, { notes });
+    }
+    if (id) {
+      const note = readNote(id);
+      if (!note) return send(res, 404, { error: 'not_found' });
+      if (note.ownerId !== userId) return send(res, 403, { error: 'forbidden' });
+      if (req.method === 'GET') return send(res, 200, { note });
+      if (req.method === 'DELETE') { unlinkSync(notePath(id)); return send(res, 204); }
+    }
+    return send(res, 405, { error: 'method_not_allowed' });
+  } catch (error) {
+    return send(res, 400, { error: 'bad_request', detail: String(error && error.message) });
+  }
+});
+server.listen(port, '127.0.0.1', () => {
+  const address = server.address();
+  process.stdout.write(`listening ${typeof address === 'object' && address ? address.port : port}\n`);
+});
+process.on('SIGTERM', () => server.close(() => process.exit(0)));

package/samples/notes-api/app/http.mjs

@@ -0,0 +1,16 @@
+import { randomUUID } from 'node:crypto';
+
+export function send(res, status, body) {
+  const text = body === undefined ? '' : JSON.stringify(body);
+  res.writeHead(status, { 'content-type': 'application/json', 'x-request-id': randomUUID(), 'content-length': Buffer.byteLength(text) });
+  res.end(text);
+}
+
+export function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = ''; req.setEncoding('utf8');
+    req.on('data', chunk => { data += chunk; if (data.length > 65536) { reject(new Error('too large')); req.destroy(); } });
+    req.on('end', () => { try { resolve(data ? JSON.parse(data) : {}); } catch (error) { reject(error); } });
+    req.on('error', reject);
+  });
+}

package/samples/notes-api/tracegrove/fixtures/existing-note.fixture.yaml

@@ -0,0 +1,12 @@
+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 }

package/samples/notes-api/tracegrove/notes/create-read-delete.flow.yaml

@@ -0,0 +1,35 @@
+title: Create a note, read it back, deny a stranger, delete it and keep other notes intact
+risk: critical
+tags: [notes, authz]
+given:
+  existing: existing-note
+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
+    expect: { status: 200, json: { note.title: Fresh note, note.body: Written through the real API. } }
+
+  - name: intruder is denied
+    GET: /notes/{noteId}
+    as: intruder
+    expect: { status: 403, absent: [note] }
+
+  - name: delete
+    DELETE: /notes/{noteId}
+    expect: 204
+
+  - name: gone
+    GET: /notes/{noteId}
+    observe: true
+    expect: 404
+
+  - name: existing note untouched
+    GET: /notes/{existing.noteId}
+    observe: true
+    expect: { status: 200, json: { note.title: Existing note } }

package/samples/notes-api/tracegrove/notes/list.flow.yaml

@@ -0,0 +1,25 @@
+title: A new note shows up in the owner's list and nowhere else
+tags: [notes, smoke]
+steps:
+  - name: create
+    POST: /notes
+    json: { title: Listed note, body: visible to its owner }
+    expect: 201
+    save: { noteId: note.id }
+
+  - name: owner sees it
+    GET: /notes
+    expect:
+      status: 200
+      count: { notes: 1 }
+      json: { "notes[0].title": Listed note }
+
+  - name: stranger sees an empty list
+    GET: /notes
+    as: intruder
+    expect: { status: 200, count: { notes: 0 } }
+
+  - name: anonymous is rejected
+    GET: /notes
+    as: none
+    expect: 401

package/samples/notes-api/tracegrove.config.yaml

@@ -0,0 +1,15 @@
+project: notes
+app:
+  adapter: node
+  entry: app/app.mjs
+  health: /health
+  sources: [app/**]
+  env:
+    NOTES_BUILD: sample
+  inject:
+    port: PORT
+    dataDir: NOTES_DIR
+    tokens: NOTES_TOKENS
+personas:
+  owner: { subject: alice }
+  intruder: { subject: bob }

package/samples/notes-api/verification/actions/notes.registry.yaml

@@ -0,0 +1,6 @@
+schemaVersion: workflow.action-registry/v1
+ref: { id: example.actions.notes, revision: "1" }
+actions:
+  - { actionId: notes.create/v1, kind: http.request, effect: create, method: POST, path: /notes, body: { title: "{title}", body: "{body}" }, auth: { kind: persona }, expectStatus: 201, captures: [ { name: noteId, from: json, path: note.id } ] }
+  - { actionId: notes.read/v1, kind: http.request, effect: read, method: GET, path: "/notes/{noteId}", body: null, auth: { kind: persona }, expectStatus: null, captures: [] }
+  - { actionId: notes.delete/v1, kind: http.request, effect: delete, method: DELETE, path: "/notes/{noteId}", body: null, auth: { kind: persona }, expectStatus: 204, captures: [] }