tracegrove 0.0.0-stage → 0.3.0

package/samples/notes-django/app/django_app.py

@@ -0,0 +1,119 @@
+"""Local Django notes API: real file persistence, no ORM or database connection."""
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from importlib.metadata import version
+import json
+import os
+from pathlib import Path
+from uuid import UUID, uuid4
+from wsgiref.simple_server import WSGIRequestHandler, make_server
+
+import django
+from django.conf import settings
+from django.core.wsgi import get_wsgi_application
+from django.http import HttpResponse, JsonResponse
+from django.urls import re_path
+
+
+@dataclass(frozen=True)
+class Note:
+    id: str
+    title: str
+    body: str
+    ownerId: str
+    createdAt: str
+
+    @classmethod
+    def create(cls, payload: object, owner: str) -> "Note":
+        if not isinstance(payload, dict) or not all(isinstance(payload.get(key), str) for key in ("title", "body")):
+            raise ValueError("invalid_note")
+        return cls(str(uuid4()), payload["title"], payload["body"], owner, datetime.now(timezone.utc).isoformat())
+
+
+class NoteStore:
+    def __init__(self, root: Path):
+        self.root = root
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def path(self, identifier: str) -> Path:
+        return self.root / f"{UUID(identifier)}.json"
+
+    def read(self, identifier: str) -> Note | None:
+        try:
+            return Note(**json.loads(self.path(identifier).read_text()))
+        except (ValueError, FileNotFoundError):
+            return None
+
+    def write(self, note: Note) -> None:
+        path = self.path(note.id)
+        temporary = path.with_suffix(".tmp")
+        temporary.write_text(json.dumps(asdict(note)))
+        temporary.replace(path)
+
+    def owned(self, owner: str) -> list[dict]:
+        return [asdict(note) for path in sorted(self.root.glob("*.json"))
+                if (note := self.read(path.stem)) is not None and note.ownerId == owner]
+
+
+class NotesAPI:
+    def __init__(self, store: NoteStore, tokens: dict[str, str], build: str):
+        self.store, self.tokens, self.build = store, tokens, build
+
+    def health(self, request):
+        return JsonResponse({"ok": True, "build": self.build, "notes": len(list(self.store.root.glob("*.json")))})
+
+    def notes(self, request, identifier: str | None = None):
+        authorization = request.headers.get("Authorization", "")
+        owner = self.tokens.get(authorization[7:]) if authorization.startswith("Bearer ") else None
+        if not owner:
+            return JsonResponse({"error": "unauthorized"}, status=401)
+        if identifier is None:
+            if request.method == "GET":
+                return JsonResponse({"notes": self.store.owned(owner)})
+            if request.method == "POST":
+                try:
+                    note = Note.create(json.loads(request.body or b"{}"), owner)
+                except (ValueError, UnicodeDecodeError):
+                    return JsonResponse({"error": "invalid_note"}, status=400)
+                self.store.write(note)
+                return JsonResponse({"note": asdict(note)}, status=201)
+            return JsonResponse({"error": "method_not_allowed"}, status=405)
+        note = self.store.read(identifier)
+        if note is None:
+            return JsonResponse({"error": "not_found"}, status=404)
+        if note.ownerId != owner:
+            return JsonResponse({"error": "forbidden"}, status=403)
+        if request.method == "GET":
+            return JsonResponse({"note": asdict(note)})
+        if request.method == "DELETE":
+            self.store.path(identifier).unlink()
+            return HttpResponse(status=204)
+        return JsonResponse({"error": "method_not_allowed"}, status=405)
+
+
+class QuietHandler(WSGIRequestHandler):
+    def log_message(self, format, *args):
+        pass
+
+
+def check_dependencies() -> None:
+    # Fail readiness when the installed versions disagree with the pinned input.
+    for line in Path(__file__).with_name("requirements.lock").read_text().splitlines():
+        if line and not line.startswith("#"):
+            name, expected = line.split()[0].split("==")
+            if version(name) != expected:
+                raise RuntimeError("Install the dependencies from app/requirements.lock")
+
+
+check_dependencies()
+settings.configure(DEBUG=False, ROOT_URLCONF=__name__, ALLOWED_HOSTS=["127.0.0.1"],
+                   INSTALLED_APPS=[], DATABASES={}, MIDDLEWARE=[], DATA_UPLOAD_MAX_MEMORY_SIZE=65536)
+django.setup()
+api = NotesAPI(NoteStore(Path(os.environ["NOTES_DIR"])), json.loads(os.environ["NOTES_TOKENS"]),
+               os.environ.get("NOTES_BUILD", "django-sample"))
+urlpatterns = [re_path(r"^health$", api.health), re_path(r"^notes(?:/(?P<identifier>[^/]+))?$", api.notes)]
+
+if __name__ == "__main__":
+    with make_server("127.0.0.1", int(os.environ.get("PORT", "0")), get_wsgi_application(), handler_class=QuietHandler) as server:
+        print(f"listening {server.server_port}", flush=True)
+        server.serve_forever()

package/samples/notes-django/app/requirements.lock

@@ -0,0 +1,4 @@
+# Pure-Python wheels downloaded from PyPI; installs require these exact hashes.
+asgiref==3.12.1 --hash=sha256:fe386d1c2bff7259ea95929266d12a8cf9a8b5a1c2598402967d8792e7a7c094
+Django==6.1.2 --hash=sha256:141efee6ec64d1db6db90683bf734c550102450f444fb099063b0be1bd27d991
+sqlparse==0.6.0 --hash=sha256:b861c0288ce2fa56209a9a6412d2e066ac664b3873b89c26c9d8415e8e32996f

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

@@ -0,0 +1,47 @@
+// Local native application: file-backed notes over MCP and independent HTTP readback.
+// Implements the bounded JSON-response 2025-11-25 transport, not an MCP widget host.
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, writeFileSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { send, readBody } from './http.mjs';
+
+const directory = process.env.NOTES_DIR;
+if (!directory) throw new Error('NOTES_DIR is required');
+mkdirSync(directory, { recursive: true });
+const tokens = JSON.parse(process.env.NOTES_TOKENS ?? '{}');
+const server = createServer(async (request, response) => {
+  try {
+    const path = new URL(request.url ?? '/', 'http://127.0.0.1').pathname;
+    if (request.method === 'GET' && path === '/health') return send(response, 200, { ok: true, notes: readdirSync(directory).length });
+    const token = String(request.headers.authorization ?? '').replace(/^Bearer /, '');
+    if (!Object.hasOwn(tokens, token)) return send(response, 401, { error: 'unauthorized' });
+    const ownerId = tokens[token];
+    const match = path.match(/^\/notes\/([0-9a-f-]{36})$/);
+    if (request.method === 'GET' && match) {
+      let note;
+      try { note = JSON.parse(readFileSync(join(directory, `${match[1]}.json`), 'utf8')); }
+      catch { return send(response, 404, { error: 'not_found' }); }
+      if (note.ownerId !== ownerId) return send(response, 403, { error: 'forbidden' });
+      return send(response, 200, { note });
+    }
+    if (path !== '/mcp') return send(response, 404, { error: 'not_found' });
+    if (request.method !== 'POST') return send(response, 405, { error: 'method_not_allowed' });
+    const message = await readBody(request);
+    if (message.jsonrpc !== '2.0' || typeof message.method !== 'string') return send(response, 400, { error: 'invalid_request' });
+    if (message.id === undefined) { response.writeHead(202); response.end(); return; }
+    const reply = result => send(response, 200, { jsonrpc: '2.0', id: message.id, result });
+    if (message.method === 'initialize') return reply({ protocolVersion: '2025-11-25', capabilities: { tools: {} }, serverInfo: { name: 'native-notes', version: '1.0.0' } });
+    if (message.method === 'tools/list') return reply({ tools: [{ name: 'notes.create', inputSchema: { type: 'object', properties: { title: { type: 'string' }, body: { type: 'string' } }, required: ['title', 'body'], additionalProperties: false } }] });
+    if (message.method === 'tools/call' && message.params?.name === 'notes.create') {
+      const input = message.params.arguments;
+      if (!input || typeof input.title !== 'string' || typeof input.body !== 'string') return reply({ isError: true, content: [{ type: 'text', text: 'Invalid note input' }] });
+      const note = { id: randomUUID(), title: input.title, body: input.body, ownerId };
+      writeFileSync(join(directory, `${note.id}.json`), JSON.stringify(note));
+      return reply({ content: [{ type: 'text', text: JSON.stringify({ note }) }], structuredContent: { note }, isError: false });
+    }
+    return send(response, 200, { jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'Unsupported method or tool' } });
+  } catch { send(response, 400, { error: 'invalid_request' }); }
+});
+server.listen(Number(process.env.PORT ?? 0), '127.0.0.1');
+process.on('SIGTERM', () => server.close(() => process.exit(0)));

package/samples/notes-mcp/tracegrove/notes.flow.yaml

@@ -0,0 +1,20 @@
+title: MCP creation is independently visible through the notes API
+effects:
+  maxMcpCalls: 1
+  allowedMcpTools: [notes.create]
+steps:
+  - name: create
+    mcp:
+      endpoint: /mcp
+      tool: notes.create
+      arguments: { title: Protocol proof, body: Saved by the native application }
+    expect:
+      json: { structuredContent.note.title: Protocol proof }
+    save: { noteId: structuredContent.note.id }
+  - GET: /notes/{noteId}
+    expect:
+      status: 200
+      json: { note.title: Protocol proof, note.ownerId: alice }
+  - GET: /notes/{noteId}
+    as: intruder
+    expect: 403

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

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

package/samples/report-jobs/README.md

@@ -0,0 +1,30 @@
+# Report jobs
+
+This sample runs a local HTTP API and a separate Node worker against one persisted
+SQLite queue. Only the worker publishes report rows. Duplicate owner/request keys
+reuse one job, cancellation waits for a worker acknowledgement, and failed jobs
+leave no report. Fixture cleanup deletes its owned job and report atomically.
+
+Generate the sample with `tracegrove sample-config --sample report-jobs --output
+<empty-directory>`. From that directory, run `tracegrove test`. Sample generation
+also compiles the low-level corpus and prints its config path; pass that exact
+path to `workflow-verify plan` or `doctor`. Compilation checks the installed Node
+runtime but does not start the API or worker.
+
+All flows use the existing HTTP submit/readback/oracle contracts. A 202 submission
+alone cannot satisfy the completion case: it polls job state, reads the persisted
+report independently, checks one-job idempotency and verifies owner isolation.
+`effects.maxJobs: 1` declares each flow's admitted job ceiling; it does not impose
+a quota on an arbitrary external provider.
+
+The `REPORTS_TEST_DROP_REPORT=1` application flag is a controlled defect: the
+worker records success without inserting the report. The completion flow must
+fail on independent report readback, while retaining its sealed failed attempt.
+The flag is part of the frozen app launch configuration. It is not a normal
+successful lane.
+
+The package's pinned Node 22 range supplies `node:sqlite`; no database server,
+account, model call or OrgX connection is needed. The core attests the complete
+application source set, including worker and storage code. This is local
+application/job behavior, not a separately issued worker attestation, hosted
+provider qualification, a native `job.submit` adapter, or crash-recovery proof.

package/samples/report-jobs/app/jobs-api.mjs

@@ -0,0 +1,65 @@
+import { createServer } from 'node:http';
+import { fork } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { JobStore, validJobInput } from './store.mjs';
+import { nativeBridge } from './native-bridge.mjs';
+import { send, readBody } from './http.mjs';
+
+const dir = process.env.REPORTS_DIR;
+if (!dir) throw new Error('REPORTS_DIR is required');
+mkdirSync(dir, { recursive: true });
+const store = new JobStore(join(dir, 'reports.sqlite'));
+const tokens = JSON.parse(process.env.REPORTS_TOKENS ?? '{}');
+const worker = fork(new URL('./worker.mjs', import.meta.url), [join(dir, 'reports.sqlite')], {
+  stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+  env: { REPORTS_TEST_DROP_REPORT: process.env.REPORTS_TEST_DROP_REPORT ?? '0' },
+});
+let ready = false;
+const nativeReady = nativeBridge(store, tokens, () => ready);
+worker.on('message', message => { if (message?.type === 'ready') { ready = true; nativeReady(); } });
+worker.on('exit', () => { ready = false; });
+const view = job => ({ id: job.id, requestKey: job.request_key, title: job.title, mode: job.mode,
+  status: job.status, workerPid: job.worker_pid, apiPid: process.pid });
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+  if (req.method === 'GET' && url.pathname === '/health') return send(res, ready ? 200 : 503, { ok: ready, workerPid: worker.pid, apiPid: process.pid });
+  const authorization = req.headers.authorization ?? '';
+  const token = authorization.startsWith('Bearer ') ? authorization.slice(7) : '';
+  const owner = Object.hasOwn(tokens, token) ? tokens[token] : null;
+  if (typeof owner !== 'string' || !owner) return send(res, 401, { error: 'unauthorized' });
+  try {
+    if (url.pathname === '/jobs' && req.method === 'GET') return send(res, 200, { jobs: store.list(owner).map(view) });
+    if (url.pathname === '/jobs' && req.method === 'POST') {
+      if (!ready) return send(res, 503, { error: 'worker_unavailable' });
+      const body = await readBody(req);
+      if (!validJobInput(body)) return send(res, 400, { error: 'invalid_job' });
+      const result = store.submit(owner, body);
+      if (result.conflict) return send(res, 409, { error: 'idempotency_conflict' });
+      return send(res, result.duplicate ? 200 : 202, { job: view(result.job), deduplicated: result.duplicate });
+    }
+    const match = /^\/(jobs|reports)\/([0-9a-f-]{36})(\/cancel)?$/.exec(url.pathname);
+    if (!match) return send(res, 404, { error: 'not_found' });
+    const [, resource, id, cancel] = match;
+    const job = store.get(id);
+    if (!job) return send(res, 404, { error: 'not_found' });
+    if (job.owner_id !== owner) return send(res, 403, { error: 'forbidden' });
+    if (resource === 'reports' && req.method === 'GET' && !cancel) {
+      const report = store.report(id);
+      return report ? send(res, 200, { report }) : send(res, 404, { error: 'report_absent' });
+    }
+    if (resource !== 'jobs') return send(res, 405, { error: 'method_not_allowed' });
+    if (cancel && req.method === 'POST') return send(res, store.requestCancel(id) ? 202 : 409, { requested: true });
+    if (!cancel && req.method === 'GET') return send(res, 200, { job: view(job) });
+    if (!cancel && req.method === 'DELETE') { store.remove(id); return send(res, 204); }
+    return send(res, 405, { error: 'method_not_allowed' });
+  } catch { return send(res, 400, { error: 'bad_request' }); }
+});
+server.listen(Number(process.env.PORT ?? 0), '127.0.0.1', () => {
+  process.send?.({ type: 'listening', port: server.address().port });
+});
+process.on('SIGTERM', () => {
+  const close = () => server.close(() => { store.close(); process.exit(0); });
+  if (worker.exitCode !== null || worker.signalCode !== null) close();
+  else { worker.once('exit', close); worker.kill('SIGTERM'); }
+});

package/samples/report-jobs/app/native-bridge.mjs

@@ -0,0 +1,30 @@
+import { validJobInput } from './store.mjs';
+
+/** The application owns auth and queue semantics; the worker and SQLite store remain real. */
+export function nativeBridge(store, tokens, workerReady) {
+  if (process.env.TRACEGROVE_NATIVE_JOBS !== 'node_ipc/v1') return () => {};
+  const empty = status => ({ jobId: null, status, requestKey: null, output: null, workerId: null });
+  process.on('message', request => {
+    if (request?.kind !== 'tracegrove.job.request') return;
+    const { command, credential } = request;
+    const owner = Object.hasOwn(tokens, credential) ? tokens[credential] : null;
+    let result = empty('forbidden');
+    if (typeof owner === 'string' && command.queue === 'reports') {
+      let job;
+      if (command.action === 'submit') {
+        const input = { ...command.payload, requestKey: command.requestKey };
+        if (!workerReady() || !validJobInput(input)) result = empty('conflict');
+        else { const submitted = store.submit(owner, input); job = submitted.job; if (submitted.conflict) result = empty('conflict'); }
+      } else {
+        job = store.get(command.jobId);
+        if (!job) result = empty('missing');
+        else if (job.owner_id !== owner) { job = null; result = empty('forbidden'); }
+        else if (command.action === 'cancel') { store.requestCancel(job.id); job = store.get(job.id); }
+      }
+      if (job) result = { jobId: job.id, status: job.status, requestKey: job.request_key,
+        output: { report: store.report(job.id), apiPid: process.pid, totalJobs: store.list(owner).length }, workerId: job.worker_pid ? String(job.worker_pid) : null };
+    }
+    process.send?.({ kind: 'tracegrove.job.response', id: request.id, result });
+  });
+  return () => process.send?.({ kind: 'tracegrove.job.ready', version: 1, queues: ['reports'] });
+}

package/samples/report-jobs/app/store.mjs

@@ -0,0 +1,74 @@
+import { DatabaseSync } from 'node:sqlite';
+import { randomUUID } from 'node:crypto';
+
+export function validJobInput(input) {
+  return typeof input.requestKey === 'string' && !!input.requestKey && input.requestKey.length <= 100 &&
+    typeof input.title === 'string' && !!input.title && input.title.length <= 200 && ['succeed', 'fail', 'hold'].includes(input.mode);
+}
+
+/** Example application storage, separate from Tracegrove's authority and ledger. */
+export class JobStore {
+  constructor(path) {
+    this.db = new DatabaseSync(path);
+    this.db.exec(`PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL;
+      CREATE TABLE IF NOT EXISTS jobs (
+        id TEXT PRIMARY KEY, owner_id TEXT NOT NULL, request_key TEXT NOT NULL,
+        title TEXT NOT NULL, mode TEXT NOT NULL, status TEXT NOT NULL,
+        worker_pid INTEGER, UNIQUE(owner_id,request_key)
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS reports (
+        job_id TEXT PRIMARY KEY, content TEXT NOT NULL, worker_pid INTEGER NOT NULL
+      ) STRICT;`);
+  }
+  transaction(action) {
+    this.db.exec('BEGIN IMMEDIATE');
+    try { const value = action(); this.db.exec('COMMIT'); return value; }
+    catch (error) { this.db.exec('ROLLBACK'); throw error; }
+  }
+  get(id) { return this.db.prepare('SELECT * FROM jobs WHERE id=?').get(id) ?? null; }
+  list(owner) { return this.db.prepare('SELECT * FROM jobs WHERE owner_id=? ORDER BY id').all(owner); }
+  submit(owner, input) {
+    return this.transaction(() => {
+      const existing = this.db.prepare('SELECT * FROM jobs WHERE owner_id=? AND request_key=?').get(owner, input.requestKey);
+      if (existing) return existing.title === input.title && existing.mode === input.mode
+        ? { job: existing, duplicate: true } : { conflict: true };
+      const id = randomUUID();
+      this.db.prepare('INSERT INTO jobs(id,owner_id,request_key,title,mode,status) VALUES(?,?,?,?,?,?)')
+        .run(id, owner, input.requestKey, input.title, input.mode, 'queued');
+      return { job: this.get(id), duplicate: false };
+    });
+  }
+  claim() {
+    return this.transaction(() => {
+      const row = this.db.prepare("SELECT * FROM jobs WHERE status IN ('queued','cancel_requested') ORDER BY rowid LIMIT 1").get();
+      if (!row) return null;
+      if (row.status === 'cancel_requested') {
+        this.db.prepare("UPDATE jobs SET status='cancelled', worker_pid=? WHERE id=?").run(process.pid, row.id);
+        return null;
+      }
+      this.db.prepare("UPDATE jobs SET status='running', worker_pid=? WHERE id=?").run(process.pid, row.id);
+      return this.get(row.id);
+    });
+  }
+  requestCancel(id) {
+    return this.db.prepare("UPDATE jobs SET status='cancel_requested' WHERE id=? AND status IN ('queued','running','cancel_requested')").run(id).changes > 0;
+  }
+  finish(id, dropReport = false) {
+    return this.transaction(() => {
+      const job = this.get(id);
+      if (!job || !['running', 'cancel_requested'].includes(job.status)) return;
+      const status = job.status === 'cancel_requested' ? 'cancelled' : job.mode === 'fail' ? 'failed' : 'succeeded';
+      if (status === 'succeeded' && !dropReport) this.db.prepare('INSERT INTO reports(job_id,content,worker_pid) VALUES(?,?,?)')
+        .run(id, `Report: ${job.title}`, process.pid);
+      this.db.prepare('UPDATE jobs SET status=?, worker_pid=? WHERE id=?').run(status, process.pid, id);
+    });
+  }
+  report(id) { return this.db.prepare('SELECT * FROM reports WHERE job_id=?').get(id) ?? null; }
+  remove(id) {
+    this.transaction(() => {
+      this.db.prepare('DELETE FROM reports WHERE job_id=?').run(id);
+      this.db.prepare('DELETE FROM jobs WHERE id=?').run(id);
+    });
+  }
+  close() { this.db.close(); }
+}

package/samples/report-jobs/app/worker.mjs

@@ -0,0 +1,22 @@
+import { setTimeout as pause } from 'node:timers/promises';
+import { JobStore } from './store.mjs';
+
+const store = new JobStore(process.argv[2]);
+let busy = false;
+const tick = async () => {
+  if (busy) return;
+  busy = true;
+  try {
+    const job = store.claim();
+    if (!job) return;
+    // Hold mode exercises a genuine worker acknowledgement of cancellation.
+    while (job.mode === 'hold' && store.get(job.id)?.status === 'running') await pause(25);
+    store.finish(job.id, process.env.REPORTS_TEST_DROP_REPORT === '1');
+  } catch { process.exitCode = 1; shutdown(); }
+  finally { busy = false; }
+};
+const timer = setInterval(() => { void tick(); }, 25);
+function shutdown() { clearInterval(timer); store.close(); process.exit(process.exitCode ?? 0); }
+process.on('SIGTERM', shutdown);
+process.on('disconnect', shutdown);
+process.send?.({ type: 'ready' });

package/samples/report-jobs/tracegrove/fixtures/failed-job.fixture.yaml

@@ -0,0 +1,12 @@
+create:
+  POST: /jobs
+  json: { requestKey: { uuid: true }, title: Failed report, mode: fail }
+  expect: 202
+save: { jobId: job.id }
+readback:
+  GET: /jobs/{jobId}
+  expect: { status: 200, json: { job.title: Failed report } }
+cleanup:
+  DELETE: /jobs/{jobId}
+  expect: 204
+  gone: { GET: "/jobs/{jobId}", status: 404 }

package/samples/report-jobs/tracegrove/fixtures/held-job.fixture.yaml

@@ -0,0 +1,12 @@
+create:
+  POST: /jobs
+  json: { requestKey: { uuid: true }, title: Held report, mode: hold }
+  expect: 202
+save: { jobId: job.id }
+readback:
+  GET: /jobs/{jobId}
+  expect: { status: 200, json: { job.title: Held report } }
+cleanup:
+  DELETE: /jobs/{jobId}
+  expect: 204
+  gone: { GET: "/jobs/{jobId}", status: 404 }

package/samples/report-jobs/tracegrove/fixtures/success-job.fixture.yaml

@@ -0,0 +1,12 @@
+create:
+  POST: /jobs
+  json: { requestKey: { uuid: true }, title: Weekly review, mode: succeed }
+  expect: 202
+save: { jobId: job.id, requestKey: job.requestKey }
+readback:
+  GET: /jobs/{jobId}
+  expect: { status: 200, json: { job.title: Weekly review } }
+cleanup:
+  DELETE: /jobs/{jobId}
+  expect: 204
+  gone: { GET: "/jobs/{jobId}", status: 404 }

package/samples/report-jobs/tracegrove/reports/cancellation.flow.yaml

@@ -0,0 +1,15 @@
+title: Cancellation is acknowledged by the worker and leaves no report
+tags: [jobs, cancellation]
+effects: { maxJobs: 1 }
+given: { report: held-job }
+steps:
+  - name: request cancellation
+    POST: /jobs/{report.jobId}/cancel
+    expect: 202
+  - name: worker acknowledges cancellation
+    GET: /jobs/{report.jobId}
+    observe: true
+    expect: { status: 200, json: { job.status: cancelled }, present: [job.workerPid] }
+  - name: no report was published
+    GET: /reports/{report.jobId}
+    expect: 404

package/samples/report-jobs/tracegrove/reports/completion.flow.yaml

@@ -0,0 +1,31 @@
+title: One queued report produces one persisted output for its owner
+tags: [jobs, smoke]
+effects: { maxJobs: 1 }
+given: { report: success-job }
+steps:
+  - name: redeliver the same request
+    POST: /jobs
+    json: { requestKey: "{report.requestKey}", title: Weekly review, mode: succeed }
+    expect: { status: 200, json: { deduplicated: true } }
+  - name: only one job exists
+    GET: /jobs
+    expect: { status: 200, count: { jobs: 1 } }
+  - name: worker completes the job
+    GET: /jobs/{report.jobId}
+    observe: true
+    expect: { status: 200, json: { job.status: succeeded }, present: [job.workerPid] }
+  - name: read persisted output independently
+    GET: /reports/{report.jobId}
+    expect: { status: 200, json: { report.content: "Report: Weekly review" } }
+  - name: another owner cannot read the job
+    GET: /jobs/{report.jobId}
+    as: intruder
+    expect: 403
+  - name: another owner cannot read the report
+    GET: /reports/{report.jobId}
+    as: intruder
+    expect: 403
+  - name: an anonymous caller is rejected
+    GET: /reports/{report.jobId}
+    as: none
+    expect: 401

package/samples/report-jobs/tracegrove/reports/failure.flow.yaml

@@ -0,0 +1,12 @@
+title: A failed worker job exposes failure and leaves no report
+tags: [jobs, failure]
+effects: { maxJobs: 1 }
+given: { report: failed-job }
+steps:
+  - name: worker records its failure
+    GET: /jobs/{report.jobId}
+    observe: true
+    expect: { status: 200, json: { job.status: failed }, present: [job.workerPid] }
+  - name: failure did not publish a report
+    GET: /reports/{report.jobId}
+    expect: 404

package/samples/report-jobs/tracegrove.config.yaml

@@ -0,0 +1,10 @@
+project: reports
+app:
+  adapter: node
+  entry: app/jobs-api.mjs
+  sources: [app/**]
+  inject: { port: PORT, dataDir: REPORTS_DIR, tokens: REPORTS_TOKENS }
+personas:
+  owner: { subject: alice }
+  intruder: { subject: bob }
+defaults: { stepTimeoutMs: 3000, caseTimeoutMs: 20000 }

package/samples/report-native/README.md

@@ -0,0 +1,11 @@
+# Native report jobs
+
+Generate with `tracegrove sample-config --sample report-native --output <folder>`.
+The generator composes this config and these flows with the shared report-jobs
+application, SQLite store, and independent worker. No application code is copied
+into a second source of truth in this sample directory.
+
+Run `tracegrove test --config <folder>/tracegrove.config.yaml`. Submission,
+readback, and cancellation use the native Node IPC bridge. HTTP serves only
+application readiness. See `docs/native-jobs.md` for the typed bridge contract,
+effect limits, scope, and qualification boundaries.

package/samples/report-native/tracegrove/cancellation.flow.yaml

@@ -0,0 +1,11 @@
+title: Native cancellation waits for a real worker acknowledgement
+effects: { maxJobs: 1 }
+steps:
+  - job: { action: submit, queue: reports, requestKey: cancellation, payload: { title: Held report, mode: hold } }
+    save: { jobId: jobId }
+  - job: { action: read, queue: reports, jobId: '{jobId}' }
+    expect: { json: { status: running } }
+  - job: { action: cancel, queue: reports, jobId: '{jobId}' }
+    expect: { present: [jobId] }
+  - job: { action: read, queue: reports, jobId: '{jobId}' }
+    expect: { json: { status: cancelled, output.report: null }, present: [workerId] }

package/samples/report-native/tracegrove/completion.flow.yaml

@@ -0,0 +1,22 @@
+title: Native submission deduplicates and an independent native read observes persisted worker output
+effects: { maxJobs: 3 }
+steps:
+  - name: submit report
+    job: { action: submit, queue: reports, requestKey: completion, payload: { title: Native report, mode: succeed } }
+    save: { jobId: jobId }
+    expect: { present: [jobId] }
+  - name: duplicate delivery
+    job: { action: submit, queue: reports, requestKey: completion, payload: { title: Native report, mode: succeed } }
+    expect: { json: { output.totalJobs: 1 } }
+  - name: conflicting delivery
+    job: { action: submit, queue: reports, requestKey: completion, payload: { title: Changed report, mode: succeed } }
+    expect: { json: { status: conflict } }
+  - name: another persona cannot read the job
+    as: intruder
+    job: { action: read, queue: reports, jobId: '{jobId}' }
+    expect: { json: { status: forbidden } }
+  - name: independent persisted output
+    job: { action: read, queue: reports, jobId: '{jobId}' }
+    expect:
+      json: { status: succeeded, output.report.content: 'Report: Native report', output.totalJobs: 1 }
+      present: [workerId]

package/samples/report-native/tracegrove/failure.flow.yaml

@@ -0,0 +1,7 @@
+title: A native provider failure remains a failed job with no persisted report
+effects: { maxJobs: 1 }
+steps:
+  - job: { action: submit, queue: reports, requestKey: failure, payload: { title: Failed report, mode: fail } }
+    save: { jobId: jobId }
+  - job: { action: read, queue: reports, jobId: '{jobId}' }
+    expect: { json: { status: failed, output.report: null }, present: [workerId] }

package/samples/report-native/tracegrove.config.yaml

@@ -0,0 +1,11 @@
+project: native_reports
+app:
+  adapter: node
+  nativeJobs: node_ipc/v1
+  entry: app/jobs-api.mjs
+  sources: [app/**]
+  inject: { port: PORT, dataDir: REPORTS_DIR, tokens: REPORTS_TOKENS }
+personas:
+  owner: { subject: alice }
+  intruder: { subject: bob }
+defaults: { stepTimeoutMs: 3000, caseTimeoutMs: 20000 }