@nanobpm/urban 0.71.0 → 0.72.0

package/dist/context/adversarial/harness.d.ts

@@ -0,0 +1,24 @@
+import type { MemoryRecord } from "../schema/index.ts";
+/**
+ * Run a git command in `cwd`, returning trimmed stdout. Every invocation is
+ * routed through {@link hardenedGitArgs} (the repo's single source of truth for
+ * `core.hooksPath=/dev/null`), so `init`/`commit`/`checkout` can never execute a
+ * hook from global templates or local config — keeping the harness deterministic
+ * and closing the CI code-execution vector.
+ */
+export declare function git(cwd: string, ...args: string[]): Promise<string>;
+/**
+ * Create a fresh temp git repo with a single seed commit on `main`, register it
+ * for cleanup in `roots`, and return its absolute path. This stands in for the
+ * local working copy S1 resolves a binding to — the substrate S3 writes and S4
+ * reads.
+ */
+export declare function makeSubstrate(roots: string[]): Promise<string>;
+/**
+ * Best-effort recursive cleanup of every registered temp root. Per-root failures
+ * (e.g. a transient EBUSY/EPERM) are swallowed so teardown can never fail an
+ * otherwise-correct suite.
+ */
+export declare function cleanup(roots: readonly string[]): Promise<void>;
+/** A well-formed measured/authoritative record, with per-test overrides. */
+export declare function rec(overrides?: Partial<MemoryRecord>): MemoryRecord;

package/dist/context/adversarial/harness.js

@@ -0,0 +1,65 @@
+// Slice S7 (adversarial) — shared test harness.
+//
+// This module is NOT a test (no `*.test.ts` suffix, so `node --test` ignores it)
+// and NOT part of the published surface (the top barrel never re-exports the
+// adversarial slice). It only provides the local temp-git-substrate helpers the
+// adversarial suites drive S3's REAL write path through. Nothing here touches the
+// network or any external service.
+import { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { hardenedGitArgs } from "../binding/git-backend.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Run a git command in `cwd`, returning trimmed stdout. Every invocation is
+ * routed through {@link hardenedGitArgs} (the repo's single source of truth for
+ * `core.hooksPath=/dev/null`), so `init`/`commit`/`checkout` can never execute a
+ * hook from global templates or local config — keeping the harness deterministic
+ * and closing the CI code-execution vector.
+ */
+export async function git(cwd, ...args) {
+    const { stdout } = await execFileAsync("git", hardenedGitArgs(args), { cwd });
+    return stdout.trim();
+}
+/**
+ * Create a fresh temp git repo with a single seed commit on `main`, register it
+ * for cleanup in `roots`, and return its absolute path. This stands in for the
+ * local working copy S1 resolves a binding to — the substrate S3 writes and S4
+ * reads.
+ */
+export async function makeSubstrate(roots) {
+    const dir = await mkdtemp(join(tmpdir(), "s7-substrate-"));
+    roots.push(dir);
+    await git(dir, "init");
+    await writeFile(join(dir, "README.md"), "# context substrate\n", "utf8");
+    await git(dir, "add", "-A");
+    await git(dir, "-c", "user.name=seed", "-c", "user.email=seed@nanobpm.local", "commit", "--no-gpg-sign", "-m", "seed");
+    // Normalise the default branch name regardless of the host git's default.
+    await git(dir, "branch", "-M", "main");
+    return dir;
+}
+/**
+ * Best-effort recursive cleanup of every registered temp root. Per-root failures
+ * (e.g. a transient EBUSY/EPERM) are swallowed so teardown can never fail an
+ * otherwise-correct suite.
+ */
+export async function cleanup(roots) {
+    await Promise.all(roots.map((dir) => rm(dir, { recursive: true, force: true }).catch(() => undefined)));
+}
+/** A well-formed measured/authoritative record, with per-test overrides. */
+export function rec(overrides = {}) {
+    const base = {
+        schemaVersion: 1,
+        id: "rec-1",
+        scope: "epic",
+        scopeRef: "issue-303",
+        mode: "empirical",
+        provenance: "measured",
+        authority: "authoritative",
+        statement: "the measured throughput was 42 rps",
+        createdAt: "2026-01-01T00:00:00Z",
+    };
+    return { ...base, ...overrides };
+}

package/dist/runtime/core/context.d.ts

@@ -37,6 +37,22 @@ export interface AppApi {
      */
     sdk?: EngineSdkClient;
     env(name: string): string | undefined;
+    /**
+     * App clock seam — current time in ms since epoch, sourced from the runtime's injectable
+     * scheduler (`CreateUrbanAppOptions.scheduler`). The real wall clock in production; the virtual
+     * clock under the test kit. A handler doing time-bounded work (poll loops, backoff,
+     * budgets) should read `app.now()` instead of `Date.now()` so a whole-app `advanceTime()`
+     * bounds it deterministically rather than the loop burning real wall-time. See
+     * {@link AppApi.wait}.
+     */
+    now(): number;
+    /**
+     * Sleep `ms` on the app clock, resolving once that much time has elapsed on the runtime
+     * scheduler. Real timers in production (no behavior change on the live transport); under
+     * the test kit it advances with `advanceTime()`. Prefer over a hand-rolled `setTimeout`
+     * sleep in time-bounded work so the delay shares the engine's (virtual) clock.
+     */
+    wait(ms: number): Promise<void>;
     /**
      * Structured logger (see {@link Logger}). Callable for back-compat
      * (`log("info", msg, fields)`), but prefer the level methods and bound context:

package/dist/runtime/core/modules/scheduler.d.ts

@@ -9,3 +9,27 @@ export interface SchedulerDeps {
 export declare const MAX_TIMER_DELAY_MS = 2147483647;
 /** Default (live) scheduler seam, backed by the global timer functions. */
 export declare function defaultScheduler(): SchedulerDeps;
+/**
+ * The app-facing clock/`wait` seam handed to handlers (see `AppApi.now`/`AppApi.wait`).
+ * A narrow read-only projection of a {@link SchedulerDeps}: `now()` reads its clock and
+ * `wait(ms)` sleeps on its timer. Real wall clock + real timers in production; the
+ * virtual clock under the test kit — so time-bounded worker work advances with
+ * `advanceTime()` instead of burning real wall-time.
+ */
+export interface AppClock {
+    /** Current time in ms since epoch on the scheduler's clock. */
+    now(): number;
+    /** Resolve after `ms` have elapsed on the scheduler's clock (armed via its timer seam). */
+    wait(ms: number): Promise<void>;
+}
+/**
+ * Derive the app clock/`wait` seam from a scheduler — the single canonical mapping from the
+ * runtime's injectable timer seam to the surface handlers use, so worker/trigger/surface
+ * handlers doing time-bounded work share the same clock as the background loops (no drift
+ * between a handler's budget and the engine's timers). A non-positive/non-finite `wait`
+ * delay clamps to fire at the current instant, and a far-future delay clamps to
+ * {@link MAX_TIMER_DELAY_MS} — matching the same clamp the background loops apply to their
+ * `setTimer` delays (see `mountTriggers`/`mountInstanceTracking`) — so `app.wait()` can
+ * never reintroduce a Node `TimeoutOverflowWarning`.
+ */
+export declare function schedulerClock(sched: SchedulerDeps): AppClock;

package/dist/runtime/core/modules/scheduler.js

@@ -1,8 +1,8 @@
 // The injectable timer + clock seam shared by every background loop in urban (cron
-// triggers, the instance-tracking reconciler). Keeping one definition here — rather
-// than a copy per module — means a test's fake scheduler drives them all the same
-// way, and the "clamp a far-future delay to setTimeout's 32-bit range" rule has a
-// single home.
+// triggers, the instance-tracking reconciler) and the app clock/`wait` seam handed to
+// worker handlers. Keeping one definition here — rather than a copy per module — means a
+// test's fake scheduler drives them all the same way, and the "clamp a far-future delay to
+// setTimeout's 32-bit range" rule has a single home.
 /** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
 export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 function isTimerHandle(handle) {
@@ -19,3 +19,22 @@ export function defaultScheduler() {
         now: () => Date.now(),
     };
 }
+/**
+ * Derive the app clock/`wait` seam from a scheduler — the single canonical mapping from the
+ * runtime's injectable timer seam to the surface handlers use, so worker/trigger/surface
+ * handlers doing time-bounded work share the same clock as the background loops (no drift
+ * between a handler's budget and the engine's timers). A non-positive/non-finite `wait`
+ * delay clamps to fire at the current instant, and a far-future delay clamps to
+ * {@link MAX_TIMER_DELAY_MS} — matching the same clamp the background loops apply to their
+ * `setTimer` delays (see `mountTriggers`/`mountInstanceTracking`) — so `app.wait()` can
+ * never reintroduce a Node `TimeoutOverflowWarning`.
+ */
+export function schedulerClock(sched) {
+    return {
+        now: () => sched.now(),
+        wait: (ms) => new Promise((resolve) => {
+            const delay = Number.isFinite(ms) && ms > 0 ? Math.min(ms, MAX_TIMER_DELAY_MS) : 0;
+            sched.setTimer(() => resolve(), delay);
+        }),
+    };
+}

package/dist/runtime/core/modules/workers.d.ts

@@ -1,6 +1,7 @@
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
 import type { EngineJob } from "../host.ts";
 import { type DecisionEvaluator } from "./llm.ts";
+import { type SchedulerDeps } from "./scheduler.ts";
 /** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
  *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
  *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
@@ -34,4 +35,4 @@ export interface WorkersHandle extends Mounted {
     readonly jobTypes: string[];
 }
 /** Load handler modules and register a push worker per declared worker. */
-export declare function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<WorkersHandle>;
+export declare function mountWorkers(ctx: RuntimeContext, app: AppApi, sched?: SchedulerDeps): Promise<WorkersHandle>;

package/dist/runtime/core/modules/workers.js

@@ -7,6 +7,7 @@ import { runLlmJob } from "./llm.js";
 import { runInJobContext } from "../execContext.js";
 import { readLineage } from "../lineage.js";
 import { LineageStore } from "./lineage-store.js";
+import { defaultScheduler, schedulerClock } from "./scheduler.js";
 /** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
  *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
  *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
@@ -125,10 +126,18 @@ export function resolveHandler(mod, jobType) {
     return undefined;
 }
 /** Load handler modules and register a push worker per declared worker. */
-export async function mountWorkers(ctx, app) {
+export async function mountWorkers(ctx, app, sched = defaultScheduler()) {
     const decls = ctx.manifest.workers ?? [];
     const subs = [];
     const jobTypes = [];
+    // Bind the app clock/`wait` seam to the injected scheduler, so a handler's time-bounded
+    // work (poll loops, backoff, budgets) sources `now`/`wait` from the same clock that drives
+    // the engine's timers and the other background loops. Under the test kit that is the
+    // virtual clock, so `advanceTime()` bounds the loop instead of it burning real wall-time;
+    // in production it is the live scheduler (real timers) — no behavior change. Mirrors how
+    // `mountTriggers`/`mountInstanceTracking` receive the same seam.
+    const clock = schedulerClock(sched);
+    const clockedApp = { ...app, now: clock.now, wait: clock.wait };
     // The framework lineage projection (issue #254): each activated job records the `_urban.lineage`
     // edge its instance carries, so intent→progress lineage materialises for free. Absent when the
     // app configures no default data source.
@@ -195,7 +204,7 @@ export async function mountWorkers(ctx, app) {
         const wrapped = (job) => {
             if (lineageStore)
                 recordJobLineage(lineageStore, job, ctx.host.log);
-            return runInJobContext(jobExecContext(job, jobType), () => handler(job, withJobLog(app, job)));
+            return runInJobContext(jobExecContext(job, jobType), () => handler(job, withJobLog(clockedApp, job)));
         };
         const sub = await ctx.engine.registerWorker(jobType, wrapped, {
             workerName: `${ctx.manifest.id}:${jobType}`,

package/dist/runtime/core/runtime.d.ts

@@ -2,7 +2,7 @@ import type { EngineClient, HostContext } from "./host.ts";
 import { type AppManifest } from "./manifest.ts";
 import { DataLayer } from "./modules/datasource.ts";
 import { type Logger } from "./logger.ts";
-import type { SchedulerDeps } from "./modules/scheduler.ts";
+import { type SchedulerDeps } from "./modules/scheduler.ts";
 import { type SecurityPolicy } from "./modules/security.ts";
 import { type UrbanEvents, type UrbanExtension } from "./extensions.ts";
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
@@ -34,11 +34,13 @@ export interface CreateUrbanAppOptions {
     mount?: MountFlags;
     /**
      * Injectable timer + clock seam driving every background loop (the cron trigger loops
-     * and the instance-tracking reconciler). Defaults to the live scheduler (real timers,
-     * wall clock). The e2e test kit injects a manual scheduler so those loops advance
-     * deterministically over a virtual clock — the single seam that makes a whole-app
-     * `settle()` possible. Threaded verbatim into `mountTriggers` and `mountInstanceTracking`
-     * so one injected scheduler drives them both (no per-module wiring, no drift).
+     * and the instance-tracking reconciler) and the app clock/`wait` seam handed to worker
+     * handlers. Defaults to the live scheduler (real timers, wall clock). The e2e test kit
+     * injects a manual scheduler so those loops — and any time-bounded worker sourcing
+     * `app.now()`/`app.wait()` — advance deterministically over a virtual clock: the single
+     * seam that makes a whole-app `settle()` possible. Threaded verbatim into `mountWorkers`,
+     * `mountTriggers` and `mountInstanceTracking` so one injected scheduler drives them all
+     * (no per-module wiring, no drift).
      */
     scheduler?: SchedulerDeps;
     /**

package/dist/runtime/core/runtime.js

@@ -14,6 +14,7 @@ import { mountConnectors } from "./modules/connectors.js";
 import { mountSurfaces } from "./modules/surfaces.js";
 import { mountTriggers } from "./modules/triggers.js";
 import { mountInstanceTracking } from "./modules/instance-tracking.js";
+import { defaultScheduler, schedulerClock } from "./modules/scheduler.js";
 import { mountSecurity } from "./modules/security.js";
 import { EventBus } from "./events.js";
 import { createUrbanEvents, mountExtensions } from "./extensions.js";
@@ -157,6 +158,12 @@ export async function createUrbanApp(opts) {
                 if (flags.deploy)
                     describe.deploy = await deployModels(ctx);
                 data = flags.data ? await provisionData(ctx) : new DataLayer(new Map(), undefined, {});
+                // Resolve the injectable scheduler once (default: live real-timer seam) so the app
+                // clock/`wait` seam handed to handlers and every background loop share one clock —
+                // the single source the test kit swaps for a virtual clock to make `settle()` /
+                // `advanceTime()` bound the whole app (workers included).
+                const scheduler = opts.scheduler ?? defaultScheduler();
+                const clock = schedulerClock(scheduler);
                 const api = {
                     manifest,
                     data,
@@ -164,9 +171,11 @@ export async function createUrbanApp(opts) {
                     sdk: engineSdk(engine),
                     env: (n) => host.env(n),
                     log: appLog,
+                    now: clock.now,
+                    wait: clock.wait,
                 };
                 if (flags.workers) {
-                    const w = await mountWorkers(ctx, api);
+                    const w = await mountWorkers(ctx, api, scheduler);
                     mounted.push(w);
                     describe.workers = w.describe?.();
                     // Connector-pack workers share the `workers` flag: same lifecycle, same
@@ -191,13 +200,13 @@ export async function createUrbanApp(opts) {
                     describe.surfaces = s.describe();
                 }
                 if (flags.triggers) {
-                    const t = mountTriggers(ctx, api, opts.scheduler);
+                    const t = mountTriggers(ctx, api, scheduler);
                     routes.push(...t.routes);
                     mounted.push(t);
                     describe.triggers = t.describe?.();
                 }
                 if (flags.instanceTracking && (manifest.instanceTracking?.length ?? 0) > 0) {
-                    const it = mountInstanceTracking(ctx, api, opts.scheduler);
+                    const it = mountInstanceTracking(ctx, api, scheduler);
                     mounted.push(it);
                     describe.instanceTracking = it.describe?.();
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.71.0",
+	"version": "0.72.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",
@@ -101,7 +101,7 @@
 	"dependencies": {
 		"@nanobpm/nano-app-schema": "^0.9.0",
 		"@nanobpm/nano-sdk": "^1.2.5",
-		"@nanobpm/workflow": "^0.12.0",
+		"@nanobpm/workflow": "^0.13.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
 		"create-urban-app": "^0.15.0",
 		"yaml": "^2.9.0"

package/src/context/adversarial/conformance-drift.test.ts

@@ -0,0 +1,89 @@
+// Slice S7 (adversarial) — SCHEMA / vocabulary DRIFT guards + conformance.
+//
+// The shared conformance corpus (S2) is the contract BOTH producer and consumer
+// are held to. Here we (a) hold the producer's own validator to the full corpus,
+// and (b) attack the controlled vocabulary directly — drifted scope/mode/
+// provenance/authority values, and structurally malformed records, must all be
+// rejected with clear, structured errors.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  assertConformance,
+  corpus,
+  fromResultValidator,
+  invalidFixtures,
+  runConformance,
+  validFixtures,
+} from "../conformance/index.ts";
+import { isMemoryRecord, validateMemoryRecord } from "../schema/index.ts";
+
+test("the producer validator passes the FULL conformance corpus", () => {
+  // Result-form validator, adapted to the corpus's { ok } contract.
+  assert.doesNotThrow(() => assertConformance(fromResultValidator(validateMemoryRecord)));
+
+  const report = runConformance(fromResultValidator(validateMemoryRecord));
+  assert.equal(report.failed, 0, "no corpus case may fail");
+  assert.equal(report.total, corpus.length);
+  assert.ok(report.total > 0);
+});
+
+test("the boolean type-guard validator also conforms", () => {
+  const report = runConformance((input) => ({ ok: isMemoryRecord(input) }));
+  assert.equal(report.failed, 0);
+});
+
+test("every valid fixture is accepted and every invalid fixture is rejected", () => {
+  for (const c of validFixtures) {
+    assert.equal(validateMemoryRecord(c.input).ok, true, `should accept: ${c.name}`);
+  }
+  for (const c of invalidFixtures) {
+    assert.equal(validateMemoryRecord(c.input).ok, false, `should reject: ${c.name}`);
+  }
+});
+
+test("drifted vocabulary is rejected with the right structured code", () => {
+  const drifts: Array<{ field: string; value: string }> = [
+    { field: "scope", value: "galaxy" },
+    { field: "mode", value: "prescriptive" },
+    { field: "provenance", value: "robot" },
+    { field: "authority", value: "supreme" },
+  ];
+  for (const { field, value } of drifts) {
+    const input: Record<string, unknown> = {
+      schemaVersion: 1,
+      id: "x",
+      scope: "repo",
+      mode: "empirical",
+      provenance: "human",
+      authority: "authoritative",
+      statement: "s",
+      createdAt: "2026-01-01T00:00:00Z",
+    };
+    input[field] = value;
+    const result = validateMemoryRecord(input);
+    assert.equal(result.ok, false, `drifted ${field}=${value} must be rejected`);
+    if (!result.ok) {
+      assert.equal(
+        result.errors.some((e) => e.path === field && e.code === "invalid-vocabulary"),
+        true,
+        `expected invalid-vocabulary on ${field}`,
+      );
+    }
+  }
+});
+
+test("hostile inputs never crash the validator (throwing getters, exotic shapes)", () => {
+  const hostile = {
+    get id() {
+      throw new Error("boom");
+    },
+  };
+  // Must return a structured rejection, not propagate the throw.
+  assert.doesNotThrow(() => validateMemoryRecord(hostile));
+  assert.equal(validateMemoryRecord(hostile).ok, false);
+
+  for (const value of [42, null, undefined, "string", [], new Date()]) {
+    assert.equal(validateMemoryRecord(value).ok, false);
+  }
+});

package/src/context/adversarial/governance.test.ts

@@ -0,0 +1,97 @@
+// Slice S7 (adversarial) — GOVERNANCE can't be bypassed.
+//
+// A proposed prior is a bot "PR": it lives on its own branch and is NOT on the
+// authoritative line until MERGED (ratified). These tests prove an unmerged
+// proposal never acts as a ratified one, and that the ratify path refuses to be
+// steered onto an arbitrary branch or base.
+
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { ContextWriter, GovernanceError } from "../git/index.ts";
+import { ContextRetriever } from "../retrieval/index.ts";
+import { cleanup, git, makeSubstrate, rec } from "./harness.ts";
+
+const TEMP_ROOTS: string[] = [];
+after(() => cleanup(TEMP_ROOTS));
+
+function retro(id: string) {
+  return rec({
+    id,
+    provenance: "agent-retro",
+    mode: "normative",
+    authority: "hypothesis",
+    statement: `proposed prior ${id}`,
+  });
+}
+
+test("an UNMERGED proposal is invisible on the authoritative line", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+
+  const proposal = await writer.proposePrior(retro("gov-1"));
+  assert.equal(proposal.ratified, false);
+
+  // Before ratifying, a reader on main sees nothing — the hypothesis is parked
+  // on its own branch, not on the base line.
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  assert.equal((await retriever.all()).some((s) => s.record.id === "gov-1"), false);
+
+  // Only the merge ratifies it onto main.
+  await writer.ratify(proposal);
+  retriever.invalidate();
+  assert.equal((await retriever.all()).some((s) => s.record.id === "gov-1"), true);
+});
+
+test("ratify refuses a branch outside the proposal namespace", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+
+  // A real, existing branch that is NOT a proposal branch.
+  await git(dir, "branch", "sneaky-branch", "main");
+
+  await assert.rejects(
+    () =>
+      writer.ratify({
+        path: "whatever",
+        commit: "deadbeef",
+        branch: "sneaky-branch",
+        baseBranch: "main",
+        proposalId: "forged",
+        ratified: false,
+      }),
+    GovernanceError,
+  );
+});
+
+test("ratify refuses a proposal whose base was steered off the writer's own base", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+
+  const proposal = await writer.proposePrior(retro("gov-steer"));
+  // ProposalResult is a plain object; a hostile caller mutates the target base.
+  await assert.rejects(
+    () => writer.ratify({ ...proposal, baseBranch: "some-other-branch" }),
+    GovernanceError,
+  );
+
+  // The proposal is still unratified: main must NOT contain it.
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  assert.equal((await retriever.all()).some((s) => s.record.id === "gov-steer"), false);
+});
+
+test("ratify refuses a non-existent proposal branch", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+  await assert.rejects(
+    () =>
+      writer.ratify({
+        path: "p",
+        commit: "c",
+        branch: "context/proposal/does-not-exist",
+        baseBranch: "main",
+        proposalId: "ghost",
+        ratified: false,
+      }),
+    GovernanceError,
+  );
+});

package/src/context/adversarial/harness.ts

@@ -0,0 +1,84 @@
+// Slice S7 (adversarial) — shared test harness.
+//
+// This module is NOT a test (no `*.test.ts` suffix, so `node --test` ignores it)
+// and NOT part of the published surface (the top barrel never re-exports the
+// adversarial slice). It only provides the local temp-git-substrate helpers the
+// adversarial suites drive S3's REAL write path through. Nothing here touches the
+// network or any external service.
+
+import { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { hardenedGitArgs } from "../binding/git-backend.ts";
+import type { MemoryRecord } from "../schema/index.ts";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Run a git command in `cwd`, returning trimmed stdout. Every invocation is
+ * routed through {@link hardenedGitArgs} (the repo's single source of truth for
+ * `core.hooksPath=/dev/null`), so `init`/`commit`/`checkout` can never execute a
+ * hook from global templates or local config — keeping the harness deterministic
+ * and closing the CI code-execution vector.
+ */
+export async function git(cwd: string, ...args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync("git", hardenedGitArgs(args), { cwd });
+  return stdout.trim();
+}
+
+/**
+ * Create a fresh temp git repo with a single seed commit on `main`, register it
+ * for cleanup in `roots`, and return its absolute path. This stands in for the
+ * local working copy S1 resolves a binding to — the substrate S3 writes and S4
+ * reads.
+ */
+export async function makeSubstrate(roots: string[]): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "s7-substrate-"));
+  roots.push(dir);
+  await git(dir, "init");
+  await writeFile(join(dir, "README.md"), "# context substrate\n", "utf8");
+  await git(dir, "add", "-A");
+  await git(
+    dir,
+    "-c",
+    "user.name=seed",
+    "-c",
+    "user.email=seed@nanobpm.local",
+    "commit",
+    "--no-gpg-sign",
+    "-m",
+    "seed",
+  );
+  // Normalise the default branch name regardless of the host git's default.
+  await git(dir, "branch", "-M", "main");
+  return dir;
+}
+
+/**
+ * Best-effort recursive cleanup of every registered temp root. Per-root failures
+ * (e.g. a transient EBUSY/EPERM) are swallowed so teardown can never fail an
+ * otherwise-correct suite.
+ */
+export async function cleanup(roots: readonly string[]): Promise<void> {
+  await Promise.all(
+    roots.map((dir) => rm(dir, { recursive: true, force: true }).catch(() => undefined)),
+  );
+}
+
+/** A well-formed measured/authoritative record, with per-test overrides. */
+export function rec(overrides: Partial<MemoryRecord> = {}): MemoryRecord {
+  const base: MemoryRecord = {
+    schemaVersion: 1,
+    id: "rec-1",
+    scope: "epic",
+    scopeRef: "issue-303",
+    mode: "empirical",
+    provenance: "measured",
+    authority: "authoritative",
+    statement: "the measured throughput was 42 rps",
+    createdAt: "2026-01-01T00:00:00Z",
+  };
+  return { ...base, ...overrides };
+}