@nanobpm/urban 0.70.0 → 0.71.1

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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.70.0",
+	"version": "0.71.1",
 	"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/README.md

@@ -58,3 +58,47 @@ barrel.
 - `npm run test:conformance --workspace @nanobpm/urban` runs the conformance
   corpus.
 - `npm run check:pii --workspace @nanobpm/urban` runs the PII gate.
+
+## PII: no-PII by construction, and the immutability-vs-erasure boundary
+
+The MVP substrate is **no-PII by construction**. Nothing here stores personal
+data, and two independent nets keep it that way:
+
+1. **In-process, at write time (S6-core + S3).** `@nanobpm/urban/context/pii`
+   ships a pure classifier (`classifyPii`) and a mandatory, default-DENY
+   pre-commit guard (`preCommitPiiGuard`). S3's `ContextWriter` registers that
+   guard as a **non-optional** pre-commit step on **every** write path
+   (`PreCommitGuardRegistry`, seeded non-removably), so a record carrying PII is
+   rejected **before any commit** — a caller cannot opt out.
+
+2. **Build-time, in CI (this slice, s6-pii-ci).** `npm run check:pii` walks the
+   S3 record layout (`records/<scope>/<scopeRef-bucket>/<id>.json`, where
+   `<scopeRef-bucket>` is the sanitised `scopeRef` or the shared `_` bucket when a
+   record carries no `scopeRef` — see `recordRelativePath`) and re-classifies
+   every record with the **same** `classifyPii`, failing the build on any violation.
+   The `.github/workflows/urban-context-pii.yml` workflow runs it (plus
+   build/typecheck/test) as a second line of defence in case content reaches a
+   git-backed context by some path other than the writer.
+
+### Why the guard, not erasure
+
+The substrate is an **append-only git history**. "Deleting" a record is just
+another commit that removes the file from the *tip*; every prior value remains
+in the reachable history (and in every clone, fork, and reflog). On this
+substrate there is **no true erasure** — you cannot unpublish a fact that was
+ever committed short of a history rewrite that every consumer must also adopt.
+Because real erasure is not achievable append-only, the only sound MVP policy is
+to **never admit PII in the first place** — hence the by-construction guard + CI
+net above rather than an after-the-fact delete.
+
+### The seam left for a future PII/mutable backend
+
+Real erasure (GDPR-style "right to be forgotten", tombstoning, crypto-shredding)
+requires a **mutable** substrate that can genuinely destroy a value, not merely
+append over it. The write path is already abstracted over the substrate
+(`WriteSubstrate` / `GitWriteSubstrate` in `@nanobpm/urban/context/git`) and the
+binding layer does not assume "public git only", so a future opt-in
+PII/mutable backend can slot in behind that seam and offer erasure semantics
+**without** touching the record schema, the layout, or this guard. That backend
+is intentionally **not built** in the MVP — only its seam is documented here, and
+the deferred implementation is tracked in nano-ide#393.

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 };
+}

package/src/context/adversarial/pii-guard.test.ts

@@ -0,0 +1,119 @@
+// Slice S7 (adversarial) — the no-PII guard holds BY CONSTRUCTION and under
+// evasion.
+//
+// The DEFAULT S3 write path (no special caller wiring) must reject a
+// PII-carrying record because S3 pre-registers the mandatory S6 guard. These
+// tests prove that, then attempt obfuscated / nested / edge-case PII and confirm
+// the guard still blocks it — and that a caller cannot bypass it.
+
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { ContextWriter } from "../git/index.ts";
+import { PiiGuardError, type PiiGuard, classifyPii, preCommitPiiGuard } from "../pii/index.ts";
+import { ContextRetriever } from "../retrieval/index.ts";
+import { cleanup, makeSubstrate, rec } from "./harness.ts";
+
+const TEMP_ROOTS: string[] = [];
+after(() => cleanup(TEMP_ROOTS));
+
+test("the DEFAULT write path (no wiring) rejects a PII-carrying record", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  // Plain default construction — the caller does NOT opt into any guard.
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+
+  // The mandatory PII guard is present — and FIRST — by construction.
+  assert.equal(
+    writer.guards[0],
+    preCommitPiiGuard,
+    "the mandatory PII guard must be registered first",
+  );
+
+  await assert.rejects(
+    () => writer.appendRecord(rec({ id: "pii-plain", statement: "reach me at alice@example.com" })),
+    PiiGuardError,
+  );
+
+  // Governance path is guarded too.
+  await assert.rejects(
+    () =>
+      writer.proposePrior(
+        rec({
+          id: "pii-propose",
+          provenance: "agent-retro",
+          mode: "normative",
+          authority: "hypothesis",
+          statement: "ssn 123-45-6789 belongs to the reporter",
+        }),
+      ),
+    PiiGuardError,
+  );
+
+  // Nothing leaked into the store.
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  assert.equal((await retriever.all()).length, 0);
+});
+
+test("PII hidden in a NESTED field (evidence array) is still blocked", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+  await assert.rejects(
+    () =>
+      writer.appendRecord(
+        rec({
+          id: "pii-nested",
+          statement: "clean summary",
+          evidence: ["run-1", "leaked contact alice@example.com in logs"],
+        }),
+      ),
+    PiiGuardError,
+  );
+});
+
+test("OBFUSCATED email evades a naive scan but not the guard", () => {
+  // The classifier's de-obfuscation pass catches spelled-out separators.
+  const obfuscated = "contact bob [at] example [dot] com for details";
+  const result = classifyPii(obfuscated);
+  assert.equal(result.clean, false, "obfuscated email must be detected");
+  assert.equal(result.findings.some((f) => f.kind === "email"), true);
+
+  // The default guard throws on it, mirroring the write path.
+  assert.throws(() => preCommitPiiGuard.assert(obfuscated), PiiGuardError);
+});
+
+test("clean content passes the guard and lands", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+  await writer.appendRecord(rec({ id: "clean-1", statement: "throughput improved to 42 rps" }));
+
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  assert.equal((await retriever.all()).some((s) => s.record.id === "clean-1"), true);
+});
+
+test("an extra caller guard can only make enforcement STRICTER, never bypass PII", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  // A DISTINCT, always-throwing caller guard. If a caller-supplied guard could
+  // displace the mandatory PII guard — or run before it — a PII write would
+  // surface THIS sentinel error instead of PiiGuardError.
+  const alwaysThrows: PiiGuard = {
+    name: "always-throws",
+    inspect: () => ({ clean: true, findings: [] }),
+    assert: () => {
+      throw new Error("extra caller guard ran");
+    },
+  };
+  const writer = new ContextWriter(
+    { localPath: dir, ref: "main" },
+    { guards: [alwaysThrows] },
+  );
+  // The mandatory guard is still FIRST; the caller guard is only appended.
+  assert.equal(writer.guards[0], preCommitPiiGuard, "mandatory PII guard must run first");
+  assert.equal(writer.guards.includes(alwaysThrows), true, "caller guard is added, not dropped");
+
+  // A PII write is rejected by the mandatory guard (which runs first) — with
+  // PiiGuardError, NOT the sentinel — proving the caller guard neither displaced
+  // nor pre-empted mandatory enforcement.
+  await assert.rejects(
+    () => writer.appendRecord(rec({ id: "pii-extra", statement: "email me: eve@example.org" })),
+    PiiGuardError,
+  );
+});

package/src/context/adversarial/provenance-forgery.test.ts

@@ -0,0 +1,126 @@
+// Slice S7 (adversarial) — PROVENANCE / AUTHORITY forgery resistance.
+//
+// The headline invariant of the whole layer is "hypothesis-never-fix": an
+// unratified / agent-retrospective prior can never be REPRESENTED as a measured
+// or authoritative fact. These tests attack that invariant directly — at the
+// schema, at the write path, and after ratification — at EVERY scope.
+
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { ContextWriter } from "../git/index.ts";
+import { ContextRetriever } from "../retrieval/index.ts";
+import {
+  MemoryRecordValidationError,
+  type MemoryScope,
+  SCOPE_LADDER,
+  assertMemoryRecord,
+  isAuthoritative,
+  validateMemoryRecord,
+} from "../schema/index.ts";
+import { cleanup, makeSubstrate, rec } from "./harness.ts";
+
+const TEMP_ROOTS: string[] = [];
+after(() => cleanup(TEMP_ROOTS));
+
+/** The forgery target: an agent-retro prior masquerading as an authoritative fact. */
+function forgedAtScope(scope: MemoryScope): Record<string, unknown> {
+  return {
+    schemaVersion: 1,
+    id: `forged-${scope}`,
+    scope,
+    mode: "empirical",
+    provenance: "agent-retro",
+    authority: "authoritative",
+    statement: "a hypothesis laundered into a fact",
+    createdAt: "2026-01-01T00:00:00Z",
+  };
+}
+
+test("schema: agent-retro can NEVER be authoritative — at every scope", () => {
+  for (const scope of SCOPE_LADDER) {
+    const result = validateMemoryRecord(forgedAtScope(scope));
+    assert.equal(result.ok, false, `scope ${scope}: forged record must be rejected`);
+    if (!result.ok) {
+      assert.equal(
+        result.errors.some((e) => e.code === "invariant-violation"),
+        true,
+        `scope ${scope}: expected an invariant-violation`,
+      );
+    }
+    assert.throws(() => assertMemoryRecord(forgedAtScope(scope)), MemoryRecordValidationError);
+  }
+});
+
+test("schema: no field permutation reaches authoritative via agent-retro", () => {
+  // The ONLY provenances that may be authoritative are human/measured/instance.
+  for (const mode of ["normative", "empirical"] as const) {
+    const result = validateMemoryRecord({
+      schemaVersion: 1,
+      id: "x",
+      scope: "repo",
+      mode,
+      provenance: "agent-retro",
+      authority: "authoritative",
+      statement: "s",
+      createdAt: "2026-01-01T00:00:00Z",
+    });
+    assert.equal(result.ok, false, `agent-retro/${mode}/authoritative must be rejected`);
+  }
+});
+
+test("write path: a forged agent-retro-authoritative record cannot be persisted", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+
+  // Neither write path will commit it: append validates+rejects the invariant
+  // (and also refuses agent-retro directly), propose validates+rejects it too.
+  await assert.rejects(() => writer.appendRecord(forgedAtScope("epic")));
+  await assert.rejects(() => writer.proposePrior(forgedAtScope("epic")));
+
+  // And nothing landed in the store.
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  const all = await retriever.all();
+  assert.equal(all.some((s) => s.record.id === "forged-epic"), false);
+  assert.equal(all.length, 0);
+});
+
+test("write path: agent-retro is refused on the DIRECT append path (must go via governance)", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+  // A perfectly valid agent-retro hypothesis is still not directly appendable.
+  await assert.rejects(() =>
+    writer.appendRecord(
+      rec({
+        id: "retro-direct",
+        provenance: "agent-retro",
+        mode: "normative",
+        authority: "hypothesis",
+        statement: "prefer X over Y",
+      }),
+    ),
+  );
+});
+
+test("ratification does NOT upgrade authority — the merged record stays a hypothesis", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+
+  const proposal = await writer.proposePrior(
+    rec({
+      id: "retro-1",
+      provenance: "agent-retro",
+      mode: "normative",
+      authority: "hypothesis",
+      statement: "a proposed prior",
+    }),
+  );
+  await writer.ratify(proposal);
+
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  const found = (await retriever.all()).find((s) => s.record.id === "retro-1");
+  assert.ok(found, "the ratified proposal is now on the authoritative line");
+  // Ratified ≠ authoritative: the record is an ACCEPTED hypothesis, never a fact.
+  assert.equal(found.record.authority, "hypothesis");
+  assert.equal(found.record.provenance, "agent-retro");
+  assert.equal(isAuthoritative(found.record), false);
+});

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

@@ -0,0 +1,104 @@
+// Slice S7 (adversarial) — the pluggable SEAMS don't leak a backend assumption.
+//
+// Retrieval must be correct from a COLD/empty derived cache (git is
+// authoritative, the cache is a disposable projection), and the binding / read
+// seams must NOT hard-wire "exclusively public git" — local paths, file:// URLs
+// and ssh remotes are first-class, and a custom RecordSource can back retrieval
+// without any git at all.
+
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { resolveContextIdentity, sameContext } from "../binding/index.ts";
+import { ContextWriter } from "../git/index.ts";
+import {
+  ContextRetriever,
+  type NamespaceSelector,
+  type RecordSource,
+  type StoredRecord,
+} from "../retrieval/index.ts";
+import type { MemoryRecord } from "../schema/index.ts";
+import { cleanup, makeSubstrate, rec } from "./harness.ts";
+
+const TEMP_ROOTS: string[] = [];
+after(() => cleanup(TEMP_ROOTS));
+
+test("retrieval is correct on a COLD cache — the first query falls back to git", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+  await writer.appendRecord(rec({ id: "cold-1", scope: "epic", scopeRef: "issue-303" }));
+  await writer.appendRecord(rec({ id: "cold-2", scope: "repo", scopeRef: "nano-ide", statement: "s2" }));
+
+  // Brand-new retriever: the derived cache is cold. This FIRST query has no
+  // warmed snapshot to read, so it falls back to git — and, as a side effect,
+  // populates the snapshot. We assert the cold-path result is complete.
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  const cold = await retriever.query({});
+  assert.equal(cold.length, 2, "a cold cache must still return every record via git");
+
+  // A path-scoped structured query on a COLD cache reads just that partition
+  // without forcing a full snapshot build. Use a FRESH retriever so the cache is
+  // genuinely cold here — the `query({})` above already warmed `retriever`.
+  const nsRetriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  assert.equal(nsRetriever.cache.isWarm, false, "a fresh retriever's cache must be cold");
+  const scoped = await nsRetriever.byNamespace("repo", "nano-ide");
+  assert.equal(scoped.length, 1);
+  assert.equal(scoped[0].record.id, "cold-2");
+  assert.equal(nsRetriever.cache.isWarm, false, "a single-namespace query must not warm the full cache");
+});
+
+test("git is authoritative — the derived cache is disposable and rebuildable", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+  await writer.appendRecord(rec({ id: "auth-1" }));
+
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  assert.equal((await retriever.all()).length, 1); // warms the cache
+
+  // A write happens in git AFTER the cache was warmed.
+  await writer.appendRecord(rec({ id: "auth-2", scope: "repo", scopeRef: "nano-ide", statement: "later" }));
+
+  // The stale snapshot doesn't see it; invalidating rebuilds purely from git.
+  retriever.invalidate();
+  const rebuilt = await retriever.all();
+  assert.equal(rebuilt.length, 2, "cache must rebuild the full truth from git");
+  assert.equal(rebuilt.some((s) => s.record.id === "auth-2"), true);
+
+  // The forward-compat embedding seam is opt-in and absent in the MVP.
+  assert.equal(retriever.embeddingIndex, undefined);
+});
+
+test("the READ seam is pluggable — retrieval works over a non-git RecordSource", async () => {
+  const record: MemoryRecord = rec({ id: "mem-1", subject: "latency", statement: "backend-agnostic" });
+  const stored: StoredRecord = { path: "records/epic/issue-303/mem-1.md", record };
+
+  // An in-memory source that never touches git — proving the seam isn't
+  // hard-wired to "exclusively public git".
+  const memorySource: RecordSource = {
+    async list(_selector?: NamespaceSelector) {
+      return [stored];
+    },
+    async read(relPath: string) {
+      return relPath === stored.path ? stored : undefined;
+    },
+  };
+
+  const retriever = new ContextRetriever("/unused/path", { source: memorySource });
+  const all = await retriever.all();
+  assert.equal(all.length, 1);
+  assert.equal(all[0].record.id, "mem-1");
+  const bySubject = await retriever.query({ subject: "latency" });
+  assert.equal(bySubject.length, 1);
+});
+
+test("binding identity is NOT hard-wired to public GitHub — local/file/ssh are first-class", () => {
+  // A local path and its file:// spelling name the SAME (self-hosted) context.
+  const localPath = "/srv/substrates/ctx";
+  const local = resolveContextIdentity({ repo: localPath, ref: "main" });
+  assert.ok(local.key.length > 0, "a local-path substrate must resolve to an identity");
+  assert.equal(sameContext({ repo: localPath, ref: "main" }, { repo: `file://${localPath}`, ref: "main" }), true);
+
+  // An ssh remote resolves too, and differs from an unrelated host.
+  const ssh = resolveContextIdentity({ repo: "git@example.com:team/ctx.git", ref: "main" });
+  assert.ok(ssh.key.length > 0);
+  assert.notEqual(ssh.key, local.key);
+});

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

@@ -0,0 +1,84 @@
+// Slice S7 (adversarial) — cross-instance SHARING semantics.
+//
+// Proves the "private-per-app / shared-on-same-name" contract can't be broken:
+// two instances naming the SAME context (repo+ref) see each other's ratified
+// writes, and two instances naming DISTINCT contexts stay isolated. Exercised at
+// both the S1 identity layer and end-to-end through S3's write path + S4 reads.
+
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import {
+  type ContextBinding,
+  contextIdentityKey,
+  resolveContextIdentity,
+  sameContext,
+} from "../binding/index.ts";
+import { ContextWriter } from "../git/index.ts";
+import { ContextRetriever } from "../retrieval/index.ts";
+import { cleanup, makeSubstrate, rec } from "./harness.ts";
+
+const TEMP_ROOTS: string[] = [];
+after(() => cleanup(TEMP_ROOTS));
+
+const binding = (repo: string, ref: string): ContextBinding => ({ repo, ref });
+
+test("identity: same (repo, ref) name shares; a distinct name stays private", () => {
+  const a = binding("nanobpm/nano-ide", "main");
+  const same = binding("nanobpm/nano-ide", "main");
+  const otherRef = binding("nanobpm/nano-ide", "release");
+  const otherRepo = binding("nanobpm/nano-workforce", "main");
+
+  assert.equal(sameContext(a, same), true);
+  assert.equal(contextIdentityKey(a), contextIdentityKey(same));
+
+  // A different ref OR a different repo is a genuinely different context.
+  assert.equal(sameContext(a, otherRef), false);
+  assert.equal(sameContext(a, otherRepo), false);
+  assert.notEqual(contextIdentityKey(a), contextIdentityKey(otherRef));
+  assert.notEqual(contextIdentityKey(a), contextIdentityKey(otherRepo));
+
+  // On-disk slug tracks the key: shared names → shared location; distinct → not.
+  assert.equal(resolveContextIdentity(a).slug, resolveContextIdentity(same).slug);
+  assert.notEqual(resolveContextIdentity(a).slug, resolveContextIdentity(otherRef).slug);
+});
+
+test("identity: equivalent repo spellings collapse to one shared substrate", () => {
+  // Shorthand, HTTPS clone URL, and a credentialed URL all name one context.
+  // The credentialed form uses the repo's redacted userinfo placeholder (`***@`)
+  // — it still exercises the "userinfo must not affect identity" invariant
+  // without embedding a credential-in-URL literal that trips secret scanning.
+  const shorthand = binding("nanobpm/nano-ide", "main");
+  const https = binding("https://github.com/nanobpm/nano-ide.git", "main");
+  const credential = binding("https://***@github.com/nanobpm/nano-ide.git", "main");
+
+  assert.equal(sameContext(shorthand, https), true);
+  assert.equal(sameContext(shorthand, credential), true, "credentials must not split identity");
+});
+
+test("end-to-end: a second instance on the same context reads the first's write", async () => {
+  const shared = await makeSubstrate(TEMP_ROOTS);
+
+  // Instance A writes a ratified fact into the shared substrate.
+  const writerA = new ContextWriter({ localPath: shared, ref: "main" });
+  await writerA.appendRecord(
+    rec({ id: "shared-fact", scope: "epic", scopeRef: "issue-303", statement: "A observed 42 rps" }),
+  );
+
+  // Instance B — a distinct object naming the SAME context — sees it.
+  const retrieverB = new ContextRetriever({ localPath: shared, ref: "main" });
+  const seenByB = await retrieverB.all();
+  assert.equal(seenByB.some((s) => s.record.id === "shared-fact"), true);
+});
+
+test("end-to-end: a distinct-name instance cannot see another context's writes", async () => {
+  const shared = await makeSubstrate(TEMP_ROOTS);
+  const other = await makeSubstrate(TEMP_ROOTS);
+
+  const writerA = new ContextWriter({ localPath: shared, ref: "main" });
+  await writerA.appendRecord(rec({ id: "private-fact", statement: "only visible in shared" }));
+
+  const retrieverOther = new ContextRetriever({ localPath: other, ref: "main" });
+  const seen = await retrieverOther.all();
+  assert.equal(seen.some((s) => s.record.id === "private-fact"), false);
+  assert.equal(seen.length, 0, "an unrelated context must stay empty/private");
+});

package/src/context/pii/check-pii.test.ts

@@ -0,0 +1,196 @@
+// Slice s6-pii-ci — tests for the build-time PII gate (`scripts/check-pii.ts`).
+//
+// These seed records into the SAME S3 path/namespace layout the writer uses
+// (`recordRelativePath`), then run the real check-pii.ts script against a local
+// temp substrate and assert its exit code: non-zero on a seeded PII violation,
+// zero on clean content. Nothing touches the network.
+
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { after, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { recordRelativePath } from "../git/index.ts";
+import type { MemoryRecord } from "../schema/index.ts";
+
+const execFileAsync = promisify(execFile);
+const HERE = dirname(fileURLToPath(import.meta.url));
+// packages/urban/src/context/pii → packages/urban/scripts/check-pii.ts
+const CHECK_PII = join(HERE, "..", "..", "..", "scripts", "check-pii.ts");
+const TEMP_ROOTS: string[] = [];
+
+after(async () => {
+  await Promise.all(TEMP_ROOTS.map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+function record(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 };
+}
+
+/** Write a record into a substrate root at its canonical S3 layout path. */
+async function seed(root: string, rec: MemoryRecord): Promise<void> {
+  const rel = recordRelativePath(rec);
+  const abs = join(root, rel);
+  await mkdir(dirname(abs), { recursive: true });
+  await writeFile(abs, `${JSON.stringify(rec, null, 2)}\n`, "utf8");
+}
+
+/** Write raw file content into a substrate root at a record's canonical path. */
+async function seedRaw(root: string, rec: MemoryRecord, content: string): Promise<void> {
+  const rel = recordRelativePath(rec);
+  const abs = join(root, rel);
+  await mkdir(dirname(abs), { recursive: true });
+  await writeFile(abs, content, "utf8");
+}
+
+async function makeRoot(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "s6ci-substrate-"));
+  TEMP_ROOTS.push(dir);
+  return dir;
+}
+
+/** Run check-pii.ts against a root; resolve with its exit code + stderr. */
+async function runCheck(root: string): Promise<{ code: number; stderr: string; stdout: string }> {
+  try {
+    const { stdout, stderr } = await execFileAsync(
+      process.execPath,
+      ["--experimental-strip-types", CHECK_PII, root],
+      { cwd: root },
+    );
+    return { code: 0, stdout, stderr };
+  } catch (error) {
+    return {
+      code: numberProp(error, "code") ?? 1,
+      stdout: stringProp(error, "stdout"),
+      stderr: stringProp(error, "stderr"),
+    };
+  }
+}
+
+function numberProp(error: unknown, key: string): number | undefined {
+  const value =
+    typeof error === "object" && error !== null ? Reflect.get(error, key) : undefined;
+  return typeof value === "number" ? value : undefined;
+}
+
+function stringProp(error: unknown, key: string): string {
+  const value =
+    typeof error === "object" && error !== null ? Reflect.get(error, key) : undefined;
+  return typeof value === "string" ? value : "";
+}
+
+test("check:pii passes (exit 0) on clean records in the S3 layout", async () => {
+  const root = await makeRoot();
+  await seed(root, record({ id: "clean-a" }));
+  await seed(
+    root,
+    record({ id: "clean-b", scope: "repo", scopeRef: undefined, statement: "latency held at 42ms" }),
+  );
+
+  const { code, stdout } = await runCheck(root);
+  assert.equal(code, 0, `expected clean content to pass; stdout=${stdout}`);
+  assert.match(stdout, /no PII detected/);
+});
+
+test("check:pii fails (non-zero) on a seeded PII violation in the S3 layout", async () => {
+  const root = await makeRoot();
+  await seed(root, record({ id: "clean-a" }));
+  // A record whose statement carries an email address — a PII violation.
+  await seed(
+    root,
+    record({ id: "leaky", statement: "reported by alice.example@contoso.com during the run" }),
+  );
+
+  const { code, stderr } = await runCheck(root);
+  assert.equal(code, 1, "expected a seeded PII violation to fail the build");
+  assert.match(stderr, /PII detected/);
+  assert.match(stderr, /email/);
+  // The gate must NOT re-leak the raw PII it caught (length-only redaction).
+  assert.doesNotMatch(stderr, /alice\.example@contoso\.com/);
+});
+
+test("check:pii catches PII in a JSON array record (arrays are not plain objects)", async () => {
+  const root = await makeRoot();
+  // A record file whose top-level JSON value is an array carrying an email
+  // address. Arrays must NOT be narrowed as plain objects — they fall through
+  // to the raw-text scan, so the leak is still caught.
+  await seedRaw(
+    root,
+    record({ id: "arr-leak" }),
+    `${JSON.stringify(["contact alice.example@contoso.com for details"], null, 2)}\n`,
+  );
+
+  const { code, stderr } = await runCheck(root);
+  assert.equal(code, 1, "expected a PII violation inside a JSON array record to fail the build");
+  assert.match(stderr, /PII detected/);
+  assert.match(stderr, /email/);
+  assert.doesNotMatch(stderr, /alice\.example@contoso\.com/);
+});
+
+test("check:pii is a no-op (exit 0) on a root with no records/ layout", async () => {
+  const root = await makeRoot();
+  const { code, stdout } = await runCheck(root);
+  assert.equal(code, 0);
+  assert.match(stdout, /0 record\(s\) scanned/);
+});
+
+test("check:pii does not follow a symlink record into a target outside the root", async () => {
+  const root = await makeRoot();
+  // A secret file OUTSIDE the substrate root (e.g. a CI secret the scanner
+  // should never touch), carrying an email address.
+  const secret = join(await makeRoot(), "ci-secret.txt");
+  await writeFile(secret, "token owner: alice.example@contoso.com\n", "utf8");
+  // A symlink placed at a canonical record path that points at that secret. The
+  // scanner must reject non-regular files (symlinks) up front — otherwise a
+  // crafted `records/**.json` symlink would make it read and classify content
+  // outside the intended substrate root.
+  const rel = recordRelativePath(record({ id: "evil-link" }));
+  const linkPath = join(root, rel);
+  await mkdir(dirname(linkPath), { recursive: true });
+  await symlink(secret, linkPath);
+
+  const { code, stdout } = await runCheck(root);
+  assert.equal(code, 0, `symlinked record must be skipped, not scanned; stdout=${stdout}`);
+  assert.match(stdout, /0 record\(s\) scanned/);
+});
+
+test("check:pii does not follow a symlinked DIRECTORY into a target outside the root", async () => {
+  const root = await makeRoot();
+  // A directory OUTSIDE the substrate root holding a record-shaped file that
+  // carries an email address — content the scanner must never reach.
+  const outsideDir = join(await makeRoot(), "outside-bucket");
+  await mkdir(outsideDir, { recursive: true });
+  await writeFile(
+    join(outsideDir, "rec-leak.json"),
+    `${JSON.stringify(record({ id: "rec-leak", statement: "owned by alice.example@contoso.com" }), null, 2)}\n`,
+    "utf8",
+  );
+  // Symlink an INTERMEDIATE bucket directory in the layout to that outside dir.
+  // `records/epic/issue-303` → outsideDir makes `records/epic/issue-303/rec-leak.json`
+  // look like a canonical record path. `readdir(recursive:true)` would follow
+  // the symlinked directory and scan (and re-leak) the outside file; the walk
+  // must refuse to descend into any symlinked directory.
+  const bucketLink = join(root, "records", "epic", "issue-303");
+  await mkdir(dirname(bucketLink), { recursive: true });
+  await symlink(outsideDir, bucketLink);
+
+  const { code, stdout, stderr } = await runCheck(root);
+  assert.equal(code, 0, `symlinked bucket dir must not be traversed; stderr=${stderr}`);
+  assert.match(stdout, /0 record\(s\) scanned/);
+  // And it must never re-leak the outside PII it refused to scan.
+  assert.doesNotMatch(stderr, /alice\.example@contoso\.com/);
+});