tracegrove 0.0.0-stage → 0.3.1

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 }

package/schema/tracegrove_cli-error_v1.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "command": {
+      "anyOf": [
+        {
+          "enum": [
+            "help",
+            "init",
+            "test",
+            "status",
+            "heal",
+            "list",
+            "compile",
+            "show",
+            "ui",
+            "discover",
+            "check",
+            "draft",
+            "settings",
+            "sample-config",
+            "validate",
+            "doctor",
+            "plan",
+            "seed",
+            "run",
+            "controller",
+            "cases",
+            "rerun",
+            "inspect",
+            "export",
+            "verify-bundle",
+            "result-ingest",
+            "results",
+            "awr-prepare",
+            "awr-inspect",
+            "awr-deliver",
+            "report-prepare",
+            "report-inspect",
+            "report-attach",
+            "verify-cleanup",
+            "source-resolve",
+            "recovery-status",
+            "source-materialize",
+            "schema"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "errorClass": {
+      "enum": [
+        "blocked",
+        "conflict",
+        "invalid_input",
+        "infrastructure_failure",
+        "unexpected_failure"
+      ],
+      "type": "string"
+    },
+    "exitCode": {
+      "anyOf": [
+        {
+          "const": 2,
+          "type": "number"
+        },
+        {
+          "const": 3,
+          "type": "number"
+        }
+      ]
+    },
+    "omittedReasonCount": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "reasons": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "enum": [
+              "unknown_command",
+              "unknown_flag",
+              "duplicate_flag",
+              "unexpected_argument",
+              "invalid_boolean",
+              "missing_argument",
+              "conflicting_flags",
+              "invalid_argument",
+              "config_not_found",
+              "invalid_authoring_file",
+              "invalid_yaml",
+              "no_flows",
+              "no_flows_selected",
+              "unknown_profile",
+              "launch_executable_missing",
+              "application_runtime_unrecognized",
+              "command_adapter_unqualified",
+              "run_not_found",
+              "execution_not_found",
+              "invalid_request_file",
+              "invalid_port",
+              "prerequisite_unavailable",
+              "state_conflict",
+              "invalid_document",
+              "invalid_json",
+              "input_unavailable",
+              "access_denied",
+              "infrastructure_failure",
+              "unexpected_failure"
+            ],
+            "type": "string"
+          },
+          "message": {
+            "maxLength": 512,
+            "minLength": 1,
+            "type": "string"
+          },
+          "recovery": {
+            "maxLength": 512,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "code",
+          "message",
+          "recovery"
+        ],
+        "type": "object"
+      },
+      "maxItems": 32,
+      "minItems": 1,
+      "type": "array"
+    },
+    "schemaVersion": {
+      "const": "tracegrove.cli-error/v1",
+      "type": "string"
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "command",
+    "errorClass",
+    "exitCode",
+    "reasons",
+    "omittedReasonCount"
+  ],
+  "type": "object"
+}

package/schema/tracegrove_config_v1.json

@@ -0,0 +1,233 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "agent": {
+      "additionalProperties": false,
+      "description": "Agent settings. .tracegrove/settings.json (written by tracegrove ui) and CLI flags override these per developer.",
+      "properties": {
+        "maxBudgetUsd": {
+          "description": "Spend cap per draft run, passed to Claude Code as --max-budget-usd.",
+          "exclusiveMinimum": 0,
+          "maximum": 100,
+          "type": "number"
+        },
+        "model": {
+          "description": "Explicit model passed to the agent CLI. Defaults: claude-haiku-5-5 for claude; gpt-6-luna for codex.",
+          "maxLength": 120,
+          "minLength": 1,
+          "type": "string"
+        },
+        "provider": {
+          "default": "claude",
+          "description": "Coding agent that drafts and repairs flows: claude (Claude Code CLI), codex (Codex CLI) or none.",
+          "enum": [
+            "claude",
+            "codex",
+            "none"
+          ],
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "app": {
+      "additionalProperties": false,
+      "properties": {
+        "adapter": {
+          "description": "Launch preset: node, fastapi, django or command.",
+          "enum": [
+            "node",
+            "fastapi",
+            "django",
+            "command"
+          ],
+          "type": "string"
+        },
+        "entry": {
+          "description": "node: script path; fastapi: module:app; django: folder containing manage.py.",
+          "type": "string"
+        },
+        "env": {
+          "additionalProperties": {
+            "type": "string"
+          },
+          "default": {},
+          "description": "Extra env; {port} and {dataDir} are substituted.",
+          "propertyNames": {
+            "type": "string"
+          },
+          "type": "object"
+        },
+        "health": {
+          "default": "/health",
+          "description": "GET path that returns 2xx once the app is ready.",
+          "pattern": "^\\/",
+          "type": "string"
+        },
+        "inject": {
+          "additionalProperties": false,
+          "default": {
+            "dataDir": "TRACEGROVE_DATA_DIR",
+            "port": "PORT",
+            "tokens": "TRACEGROVE_TOKENS"
+          },
+          "properties": {
+            "dataDir": {
+              "default": "TRACEGROVE_DATA_DIR",
+              "type": "string"
+            },
+            "port": {
+              "default": "PORT",
+              "type": "string"
+            },
+            "tokens": {
+              "default": "TRACEGROVE_TOKENS",
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "nativeJobs": {
+          "const": "node_ipc/v1",
+          "description": "Opt in to the application-owned native Node job bridge.",
+          "type": "string"
+        },
+        "python": {
+          "description": "fastapi/django: interpreter (default .venv/bin/python when present, else python3).",
+          "type": "string"
+        },
+        "readyTimeoutMs": {
+          "default": 20000,
+          "exclusiveMinimum": 0,
+          "maximum": 300000,
+          "type": "integer"
+        },
+        "root": {
+          "default": ".",
+          "description": "App directory relative to this file; the launch cwd.",
+          "type": "string"
+        },
+        "run": {
+          "description": "command adapter: shell command that starts the app on $PORT.",
+          "type": "string"
+        },
+        "sources": {
+          "description": "Globs (relative to root) whose bytes are attested as the tested source.",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "type": "array"
+        }
+      },
+      "required": [
+        "adapter"
+      ],
+      "type": "object"
+    },
+    "defaults": {
+      "additionalProperties": false,
+      "default": {
+        "caseTimeoutMs": 30000,
+        "stepTimeoutMs": 5000
+      },
+      "properties": {
+        "caseTimeoutMs": {
+          "default": 30000,
+          "exclusiveMinimum": 0,
+          "maximum": 600000,
+          "type": "integer"
+        },
+        "stepTimeoutMs": {
+          "default": 5000,
+          "exclusiveMinimum": 0,
+          "maximum": 120000,
+          "type": "integer"
+        }
+      },
+      "type": "object"
+    },
+    "personas": {
+      "additionalProperties": {
+        "additionalProperties": false,
+        "properties": {
+          "inputMode": {
+            "enum": [
+              "pointer",
+              "touch",
+              "keyboard"
+            ],
+            "type": "string"
+          },
+          "locale": {
+            "maxLength": 16,
+            "minLength": 2,
+            "type": "string"
+          },
+          "reducedMotion": {
+            "type": "boolean"
+          },
+          "subject": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "timezone": {
+            "maxLength": 64,
+            "minLength": 1,
+            "type": "string"
+          },
+          "viewport": {
+            "additionalProperties": false,
+            "properties": {
+              "height": {
+                "maximum": 2147483647,
+                "minimum": 1,
+                "type": "integer"
+              },
+              "width": {
+                "maximum": 2147483647,
+                "minimum": 1,
+                "type": "integer"
+              }
+            },
+            "required": [
+              "width",
+              "height"
+            ],
+            "type": "object"
+          }
+        },
+        "required": [
+          "subject"
+        ],
+        "type": "object"
+      },
+      "description": "Callers. The first one is the default `as:` for every step.",
+      "propertyNames": {
+        "pattern": "^[A-Za-z][A-Za-z0-9_-]*$",
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "project": {
+      "description": "Short project name, shown in reports and run summaries.",
+      "pattern": "^[A-Za-z][A-Za-z0-9_-]*$",
+      "type": "string"
+    },
+    "testDir": {
+      "default": "tracegrove",
+      "description": "Folder holding *.flow.yaml and fixtures/, relative to this file.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "project",
+    "app",
+    "personas"
+  ],
+  "type": "object"
+}