tracegrove 0.0.0-stage → 0.3.1

package/samples/notes-api/verification/fixtures/existing-note.recipe.yaml

@@ -0,0 +1,29 @@
+schemaVersion: workflow.seed-recipe/v1
+ref: { id: example.recipe.existing-note, revision: "1" }
+intent: One pre-existing note owned by the persona that the case must leave intact.
+modelCatalogRef: null
+actionRegistryRef: { $file: ../actions/notes.registry.yaml }
+entities:
+  - entityKey: existing_note
+    modelId: note
+    actionId: notes.create/v1
+    dependsOn: []
+    traits: []
+    values:
+      title: { kind: literal, value: Existing note }
+      body: { kind: generator, generatorId: words, args: { count: 6 } }
+    outputNames: [noteId]
+    readback:
+      actionId: notes.read/v1
+      predicate:
+        kind: all
+        predicates:
+          - { kind: status_equals, value: 200 }
+          - { kind: json_path_equals, path: body.note.title, value: Existing note }
+    cleanup:
+      actionId: notes.delete/v1
+      absenceReadback: { actionId: notes.read/v1, expectStatus: 404 }
+relationBindings: []
+cleanupStrategy: reverse_dependency_order
+lifecyclePolicy: application_api
+generation: { logicalSeed: notes-existing-note-1, generatorVersion: "1", locale: en-US, timezone: UTC, logicalClock: "2026-10-10T00:00:00Z" }

package/samples/notes-api/verification/hosts/local-process.yaml

@@ -0,0 +1,27 @@
+schemaVersion: workflow.host-plan/v1
+ref: { id: example.host.local-process, revision: "1" }
+placement: local
+adapter: local_process
+launch:
+  componentId: notes-api
+  command: node
+  args: [app/app.mjs]
+  cwd: ..
+  env: { NOTES_BUILD: sample }
+  portEnv: PORT
+  dataDirEnv: NOTES_DIR
+  credentialsEnv: NOTES_TOKENS
+  readiness: { path: /health, timeoutMs: 5000 }
+  identitySourceFiles: [app/app.mjs, app/http.mjs]
+  issuedCredentials:
+    - { name: owner_token, subject: alice }
+    - { name: intruder_token, subject: bob }
+mockResponsesRef: null
+transportPolicy: in_process
+isolationPolicy: fresh_directory_and_port
+networkRules: [loopback_only]
+requestedResources: { cpu: 1, memoryMb: 128, diskMb: 16 }
+requiredCapabilities: [shell, network_origin:loopback, confirmed_cancel, artifact_delivery]
+captureRequirements: []
+sessionLifetimeMs: 120000
+cleanupReserveMs: 10000

package/samples/notes-api/verification/hosts/mock-loopback.yaml

@@ -0,0 +1,14 @@
+schemaVersion: workflow.host-plan/v1
+ref: { id: example.host.mock-loopback, revision: "1" }
+placement: local
+adapter: mock_loopback
+launch: null
+mockResponsesRef: { $file: ../mocks/notes.responses.yaml }
+transportPolicy: in_process
+isolationPolicy: fresh_directory_and_port
+networkRules: [loopback_only]
+requestedResources: { cpu: 1, memoryMb: 64, diskMb: 1 }
+requiredCapabilities: [network_origin:loopback, confirmed_cancel, artifact_delivery]
+captureRequirements: []
+sessionLifetimeMs: 60000
+cleanupReserveMs: 5000

package/samples/notes-api/verification/mocks/notes.responses.yaml

@@ -0,0 +1,5 @@
+schemaVersion: workflow.mock-responses/v1
+ref: { id: example.mock.notes, revision: "1" }
+routes:
+  - { method: POST, path: /notes, status: 201, body: { note: { id: 00000000-0000-4000-8000-000000000001, title: Stub note, body: stub } }, requireBearer: true }
+  - { method: GET, path: "/notes/{id}", status: 200, body: { note: { id: 00000000-0000-4000-8000-000000000001, title: Stub note, body: stub } }, requireBearer: true }

package/samples/notes-api/verification/personas/owner.yaml

@@ -0,0 +1,16 @@
+schemaVersion: workflow.persona/v1
+ref: { id: example.persona.owner, revision: "1" }
+traits: [new_user]
+accountBindingRef: null
+roleScopes: [notes.owner]
+stateRecipeRef: null
+dataVolumeRecipeRef: null
+entitlementRef: null
+connectorStateRef: null
+authRecipeRef: { $file: ../auth/host-issued-owner.yaml }
+locale: en-US
+timezone: UTC
+viewport: { width: 1280, height: 800 }
+inputMode: keyboard
+reducedMotion: true
+cleanupPolicyRef: null

package/samples/notes-api/verification/policies/no-authoring-inference.yaml

@@ -0,0 +1,10 @@
+schemaVersion: workflow.intelligence-policy/v1
+ref: { id: example.policy.no-authoring-inference, revision: "1" }
+stages:
+  analysis: { allowed: false, maxCalls: 0, maxTokens: 0, costCeilingCents: 0 }
+  drafting: { allowed: false, maxCalls: 0, maxTokens: 0, costCeilingCents: 0 }
+  discovery: { allowed: false, maxCalls: 0, maxTokens: 0, costCeilingCents: 0 }
+  diagnosis: { allowed: false, maxCalls: 0, maxTokens: 0, costCeilingCents: 0 }
+  evaluation: { allowed: false, maxCalls: 0, maxTokens: 0, costCeilingCents: 0 }
+  benchmark: { allowed: false, maxCalls: 0, maxTokens: 0, costCeilingCents: 0 }
+replayInference: none

package/samples/notes-api/verification/runners/http.yaml

@@ -0,0 +1,5 @@
+schemaVersion: workflow.runner-profile/v1
+ref: { id: tracegrove.runner.http, revision: "1" }
+adapter: http
+maxStepsPerCase: 50
+cancellation: confirmed

package/samples/notes-api/verification/surfaces/http-api.binding.yaml

@@ -0,0 +1,11 @@
+schemaVersion: workflow.surface-binding/v1
+ref: { id: example.surface.notes-http, revision: "1" }
+kind: http_api
+packRef: { $file: ./http-api.pack.yaml }
+driverProfileRef: null
+componentProfileRef: { $file: ../components/notes-api.profile.yaml }
+interaction: protocol
+configurationSchemaRef: null
+configurationRef: null
+variantPolicyRef: null
+requiredCapabilities: [http.request, observe]

package/samples/notes-api/verification/surfaces/http-api.pack.yaml

@@ -0,0 +1,7 @@
+schemaVersion: workflow.surface-pack/v1
+ref: { id: tracegrove.pack.http-api, revision: "1" }
+kind: http_api
+protocol: http
+stepKinds: [http.request, observe]
+oracles: [http.observation/1, step.result/1]
+captureFormats: [application/json]

package/samples/notes-api/verification/workflow.yaml

@@ -0,0 +1,27 @@
+schemaVersion: workflow.config/v1
+project: notes
+suiteRef: ./cases/notes.suite.yaml
+defaultProfile: native-real
+outputDir: ./verification-output
+sourceSetRef: null
+executionHostRef: ./hosts/local-process.yaml
+intelligencePolicyRef: ./policies/no-authoring-inference.yaml
+profiles:
+  native-real:
+    class: isolated_candidate
+    environmentPlanRef: ./environments/local-notes.yaml
+    hostPlanRef: null
+    personaRef: ./personas/owner.yaml
+    fixturePlanRef: null
+    fidelityProfileRef: ./fidelity/full-live-sandbox.yaml
+    runnerRef: ./runners/http.yaml
+    budget: { deadlineMs: 60000, costCeilingCents: 0 }
+  offline-contract:
+    class: isolated_candidate
+    environmentPlanRef: ./environments/mock-notes.yaml
+    hostPlanRef: ./hosts/mock-loopback.yaml
+    personaRef: ./personas/owner.yaml
+    fixturePlanRef: null
+    fidelityProfileRef: ./fidelity/mock-contract.yaml
+    runnerRef: ./runners/http.yaml
+    budget: { deadlineMs: 20000, costCeilingCents: 0 }

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

@@ -0,0 +1,19 @@
+title: A seeded note appears in the authenticated browser
+tags: [browser, smoke]
+given: { existing: existing-note }
+browser:
+  allowPaths: [/ui, /notes]
+  allowMethods: [GET, HEAD]
+steps:
+  - name: open notes
+    browser: { kind: navigate, path: /ui }
+    expect: { status: 200 }
+  - name: refresh notes
+    browser: { kind: click, target: { by: role, role: button, name: Refresh } }
+  - name: note is visible
+    browser: { kind: read, target: { by: testId, name: notes } }
+    expect: { text: Existing note }
+  - name: independent API readback
+    GET: /notes/{existing.noteId}
+    observe: true
+    expect: { status: 200, json: { note.title: Existing note } }

package/samples/notes-browser/verification/cases/notes.browser.yaml

@@ -0,0 +1,63 @@
+schemaVersion: workflow.case/v1
+ref: { id: example.notes.browser, revision: "1" }
+purpose: Read a seeded note through the authenticated browser and confirm its state through an independent API readback.
+workflowId: notes.browser
+requirementRefs: []
+sourceRefs: []
+sourceAnalysisRef: null
+risk: standard
+surface: hybrid
+surfaceBindingRef: { $file: ../surfaces/http-api.binding.yaml }
+proofClaim: The locally launched application displays a seeded note through its authenticated UI, agrees with an independent API readback, and records the browser interaction. This establishes local application behavior only.
+environmentClasses: [isolated_candidate]
+requiredCapabilities: [ui.navigate, ui.action, ui.observe, observe, fixture.http]
+requiredBoundaries:
+  - { boundaryId: application, mode: real }
+  - { boundaryId: storage, mode: real }
+dependencyCases: []
+personaRef: { $file: ../personas/owner.yaml }
+datasetRef: null
+fixturePlanRef: { $file: ../fixtures/existing-note.plan.yaml }
+navigationRef: null
+preconditions: []
+steps:
+  - { id: navigate, kind: ui.navigate, path: /ui, timeoutMs: 5000, inputs: {}, retry: { attempts: 1 } }
+  - id: refresh
+    kind: ui.action
+    timeoutMs: 5000
+    inputs: {}
+    retry: { attempts: 1 }
+    command: { kind: click, target: { by: role, role: button, name: Refresh } }
+  - id: read_dom
+    kind: ui.observe
+    timeoutMs: 5000
+    inputs: {}
+    retry: { attempts: 1 }
+    target: { by: testId, name: notes }
+    predicate: { kind: json_path_equals, path: browser.text, value: Existing note }
+    pollIntervalMs: 50
+  - id: read_api
+    kind: observe
+    timeoutMs: 5000
+    inputs: { existingId: { kind: fixture, entityKey: existing_note, outputName: noteId } }
+    retry: { attempts: 1 }
+    readback: { kind: http, method: GET, path: "/notes/{existingId}", auth: { kind: persona } }
+    predicate: { kind: json_path_equals, path: body.note.title, value: Existing note }
+    pollIntervalMs: 50
+    captures: []
+assertions:
+  - { id: a.browser, stepId: read_dom, required: true, environmentClasses: [isolated_candidate], oracle: { name: browser.observation, version: "1" }, predicate: { kind: json_path_equals, path: browser.text, value: Existing note }, coverageTags: [notes.ui] }
+  - { id: a.readback, stepId: read_api, required: true, environmentClasses: [isolated_candidate], oracle: { name: http.observation, version: "1" }, predicate: { kind: all, predicates: [ { kind: status_equals, value: 200 }, { kind: json_path_equals, path: body.note.title, value: Existing note } ] }, coverageTags: [notes.read] }
+effects:
+  mode: read_only
+  allowedHosts: ["launch://notes-api"]
+  allowedMethods: [GET, HEAD]
+  allowedResourcePrefixes: [/ui, /notes]
+  maxCreates: 1
+  maxMessages: 0
+  maxJobs: 0
+  cleanupRecipeRef: null
+limits: { deadlineMs: 30000, maxProviderRequests: 0, maxTokens: 0, costCeilingCents: 0, maxBrowserActions: 50, maxArtifactBytes: 2097152, diagnosticRetries: 0, concurrencyGroup: notes }
+capture: { stepEvents: true, networkMetadata: true, trace: optional, video: required, redactionPolicyRef: null, retentionPolicyRef: null }
+baselineRef: null
+generation: null

package/samples/notes-browser/verification/cases/notes.suite.yaml

@@ -0,0 +1,4 @@
+schemaVersion: workflow.suite/v1
+id: notes.browser.suite
+cases:
+  - { caseRef: ./notes.browser.yaml, required: true, profiles: [native-real] }

package/samples/notes-browser/verification/runners/http.yaml

@@ -0,0 +1,5 @@
+schemaVersion: workflow.runner-profile/v1
+ref: { id: tracegrove.runner.browser, revision: "1" }
+adapter: browser
+maxStepsPerCase: 50
+cancellation: confirmed

package/samples/notes-browser/verification/surfaces/http-api.binding.yaml

@@ -0,0 +1,11 @@
+schemaVersion: workflow.surface-binding/v1
+ref: { id: example.surface.notes-browser, revision: "1" }
+kind: web
+packRef: { $file: ./http-api.pack.yaml }
+driverProfileRef: null
+componentProfileRef: { $file: ../components/notes-api.profile.yaml }
+interaction: hybrid
+configurationSchemaRef: null
+configurationRef: null
+variantPolicyRef: null
+requiredCapabilities: [http.request, observe, ui.navigate, ui.action, ui.observe]

package/samples/notes-browser/verification/surfaces/http-api.pack.yaml

@@ -0,0 +1,7 @@
+schemaVersion: workflow.surface-pack/v1
+ref: { id: tracegrove.pack.browser, revision: "1" }
+kind: web
+protocol: playwright
+stepKinds: [http.request, observe, ui.navigate, ui.action, ui.observe]
+oracles: [http.observation/1, browser.observation/1, step.result/1]
+captureFormats: [application/json, video/webm]

package/samples/notes-django/README.md

@@ -0,0 +1,21 @@
+# Django notes sample
+
+This local Django application uses real HTTP and file-backed persistence. It has no ORM models, database connection, OrgX SDK, provider account or authoring inference. The runner uses the same cases, fixtures, assertions and HTTP adapter as the Node notes sample.
+
+Use Python 3.13 and the verifier's supported Node 22 runtime. From this generated sample directory:
+
+```sh
+python3.13 -m venv .venv
+.venv/bin/python -m pip install --require-hashes -r app/requirements.lock
+workflow-verify doctor --config verification/workflow.yaml
+workflow-verify plan --config verification/workflow.yaml --output request.json
+workflow-verify run --request request.json --json
+```
+
+The launch recipe issues temporary owner and intruder credentials, allocates a fresh loopback port and writes notes inside the attempt's owned workspace. The local supervisor terminates the application group and removes that workspace after confirmed cleanup. No application data is written into the sample's source directory.
+
+The source identity binds `app/django_app.py` and `app/requirements.lock`. The launcher observes Python's executable version and digest separately. Startup refuses installed dependency versions that disagree with the lock. This establishes local behavior; it does not attest installed dependency bytes or prove a production deployment.
+
+The lock pins Django 6.1.2, asgiref and sqlparse to the downloaded pure-Python wheel hashes. Install with `--require-hashes`; do not replace the lock with an unpinned install. These dependencies use BSD licenses and remain distributed separately from this sample's Apache-2.0 source. The [Django standalone-settings documentation](https://docs.djangoproject.com/en/6.1/topics/settings/#using-settings-without-setting-django-settings-module) describes the settings/setup path.
+
+Export the completed execution with `workflow-verify export`, then use `workflow-verify verify-bundle` to check its saved evidence. Product assertions, successful cleanup and a verified local bundle each describe their own evidence; none enables hosted execution.

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'] });
+}