@nanobpm/urban 0.57.0 → 0.59.0

package/dist/context/conformance/index.d.ts

@@ -1 +1,66 @@
-export {};
+/** Whether the corpus expects a validator to accept or reject an input. */
+export type ConformanceExpectation = "accept" | "reject";
+/** A single corpus entry: an input and the outcome every conformant validator must produce. */
+export interface ConformanceCase {
+    /** Unique, stable, human-readable case name. */
+    readonly name: string;
+    /** The required outcome. */
+    readonly expect: ConformanceExpectation;
+    /** The (untrusted) value fed to the validator. */
+    readonly input: unknown;
+    /** Why this case exists / what rule it exercises. */
+    readonly note: string;
+}
+/**
+ * The minimal validator contract the corpus tests. A conformant validator maps
+ * an untrusted value to an accept/reject decision via `{ ok }`.
+ * `validateMemoryRecord` (result form) adapts to this shape via
+ * {@link fromResultValidator}; the boolean `isMemoryRecord` conforms by wrapping
+ * its result — `(input) => ({ ok: isMemoryRecord(input) })`.
+ */
+export type ConformanceValidator = (input: unknown) => {
+    readonly ok: boolean;
+};
+/** The outcome of running one case through a validator. */
+export interface ConformanceCaseResult {
+    readonly case: ConformanceCase;
+    readonly expected: ConformanceExpectation;
+    readonly actual: ConformanceExpectation;
+    readonly passed: boolean;
+}
+/** The aggregate report from {@link runConformance}. */
+export interface ConformanceReport {
+    readonly total: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly results: readonly ConformanceCaseResult[];
+    readonly failures: readonly ConformanceCaseResult[];
+}
+/**
+ * The full conformance corpus: exhaustive scope × valid/invalid triples, plus
+ * structural and vocabulary-drift cases. Deterministic and stable — treat it as
+ * the versioned contract fixture both producer and consumer are held to.
+ */
+export declare const corpus: readonly ConformanceCase[];
+/** The subset of the corpus that must be accepted. */
+export declare const validFixtures: readonly ConformanceCase[];
+/** The subset of the corpus that must be rejected. */
+export declare const invalidFixtures: readonly ConformanceCase[];
+/**
+ * Adapt a `{ ok } | { ... }`-returning validator (like `validateMemoryRecord`)
+ * to the {@link ConformanceValidator} shape. Any function returning an object
+ * with a boolean `ok` already conforms; this is a typed identity helper.
+ */
+export declare function fromResultValidator(validate: (input: unknown) => {
+    readonly ok: boolean;
+}): ConformanceValidator;
+/**
+ * Run `validate` against the corpus (or a supplied subset) and return a
+ * structured report. Pure: does not throw and does not depend on a test runner.
+ */
+export declare function runConformance(validate: ConformanceValidator, cases?: readonly ConformanceCase[]): ConformanceReport;
+/**
+ * Assert full conformance: throws with a readable summary if any case fails.
+ * Consumers can call this in their own test suite to be held to the contract.
+ */
+export declare function assertConformance(validate: ConformanceValidator, cases?: readonly ConformanceCase[]): void;

package/dist/context/conformance/index.js

@@ -1 +1,215 @@
-export {};
+// Slice S2 (conformance) — the shared conformance corpus + a reusable runner.
+//
+// Published as `@nanobpm/urban/context/conformance`. This subpath IS the
+// contract: BOTH the producer (this repo) and the consumer
+// (`nanobpm/nano-workforce#291`) are held to the SAME corpus, and the
+// adversarial slice (S7) imports the corpus + runner from here directly. It is
+// intentionally self-contained — it does NOT re-export the schema module, so a
+// consumer can import it without pulling the whole schema surface, and the top
+// barrel never sees a duplicate symbol.
+//
+// The runner is a PURE function over a validator callback (no test framework),
+// so any party can point it at their own validator and get a structured report.
+// The `.conformance.ts` sibling wires it into `node:test` for `test:conformance`.
+import { MEMORY_RECORD_SCHEMA_VERSION, SCOPE_LADDER } from "../schema/index.js";
+/**
+ * Every (provenance, mode, authority) triple that is VALID by the schema
+ * invariants. Instantiated across all scopes below, this covers every
+ * scope × provenance × mode combination that a well-formed record can take.
+ */
+const VALID_TRIPLES = [
+    { provenance: "human", mode: "normative", authority: "hypothesis" },
+    { provenance: "human", mode: "normative", authority: "authoritative" },
+    { provenance: "human", mode: "empirical", authority: "hypothesis" },
+    { provenance: "human", mode: "empirical", authority: "authoritative" },
+    { provenance: "agent-retro", mode: "normative", authority: "hypothesis" },
+    { provenance: "agent-retro", mode: "empirical", authority: "hypothesis" },
+    { provenance: "measured", mode: "empirical", authority: "authoritative" },
+    { provenance: "instance", mode: "empirical", authority: "authoritative" },
+];
+/**
+ * Every (provenance, mode, authority) triple that MUST be rejected by the
+ * invariants, with the rule it violates. The first two are the headline
+ * hypothesis-never-fix invariant (agent-retro can never be authoritative).
+ */
+const INVALID_TRIPLES = [
+    { provenance: "agent-retro", mode: "normative", authority: "authoritative", why: "hypothesis-never-fix: agent-retro can never be authoritative" },
+    { provenance: "agent-retro", mode: "empirical", authority: "authoritative", why: "hypothesis-never-fix: agent-retro can never be authoritative" },
+    { provenance: "measured", mode: "empirical", authority: "hypothesis", why: "measured must be authoritative" },
+    { provenance: "measured", mode: "normative", authority: "authoritative", why: "measured must be empirical, not normative" },
+    { provenance: "instance", mode: "empirical", authority: "hypothesis", why: "instance must be authoritative" },
+    { provenance: "instance", mode: "normative", authority: "authoritative", why: "instance must be empirical, not normative" },
+];
+function baseRecord(scope, triple) {
+    return {
+        schemaVersion: MEMORY_RECORD_SCHEMA_VERSION,
+        id: `rec-${scope}-${triple.provenance}-${triple.mode}-${triple.authority}`,
+        scope,
+        mode: triple.mode,
+        provenance: triple.provenance,
+        authority: triple.authority,
+        statement: `example ${triple.mode} ${triple.provenance} record at ${scope} scope`,
+        createdAt: "2026-01-01T00:00:00.000Z",
+    };
+}
+function buildCombinationalCases() {
+    const cases = [];
+    for (const scope of SCOPE_LADDER) {
+        for (const triple of VALID_TRIPLES) {
+            cases.push({
+                name: `accept ${scope}/${triple.mode}/${triple.provenance}/${triple.authority}`,
+                expect: "accept",
+                input: baseRecord(scope, triple),
+                note: "well-formed record; valid vocabulary + consistent invariants",
+            });
+        }
+        for (const triple of INVALID_TRIPLES) {
+            cases.push({
+                name: `reject ${scope}/${triple.mode}/${triple.provenance}/${triple.authority}`,
+                expect: "reject",
+                input: baseRecord(scope, triple),
+                note: triple.why,
+            });
+        }
+    }
+    return cases;
+}
+/** Structural / vocabulary-drift rejects that are independent of scope. */
+const STRUCTURAL_CASES = [
+    { name: "reject non-object (number)", expect: "reject", input: 42, note: "record must be an object" },
+    { name: "reject non-object (null)", expect: "reject", input: null, note: "record must be an object" },
+    { name: "reject non-object (array)", expect: "reject", input: [], note: "record must be a plain object, not an array" },
+    {
+        name: "reject unsupported schemaVersion",
+        expect: "reject",
+        input: { schemaVersion: 2, id: "x", scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+        note: "schemaVersion must be exactly 1",
+    },
+    {
+        name: "reject missing schemaVersion",
+        expect: "reject",
+        input: { id: "x", scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+        note: "schemaVersion is required",
+    },
+    {
+        name: "reject missing id",
+        expect: "reject",
+        input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+        note: "id is required",
+    },
+    {
+        name: "reject empty statement",
+        expect: "reject",
+        input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "", createdAt: "2026-01-01T00:00:00.000Z" },
+        note: "statement must be non-empty",
+    },
+    {
+        name: "reject drifted scope vocabulary",
+        expect: "reject",
+        input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "galaxy", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+        note: "scope must be in the ladder vocabulary",
+    },
+    {
+        name: "reject drifted mode vocabulary",
+        expect: "reject",
+        input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "prescriptive", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+        note: "mode must be normative|empirical",
+    },
+    {
+        name: "reject drifted provenance vocabulary",
+        expect: "reject",
+        input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "empirical", provenance: "robot", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+        note: "provenance must be in the vocabulary",
+    },
+    {
+        name: "reject drifted authority vocabulary",
+        expect: "reject",
+        input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "empirical", provenance: "human", authority: "supreme", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+        note: "authority must be hypothesis|authoritative",
+    },
+    {
+        name: "reject non-ISO timestamp",
+        expect: "reject",
+        input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "yesterday" },
+        note: "createdAt must be ISO-8601",
+    },
+    {
+        name: "reject wrong-typed id",
+        expect: "reject",
+        input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: 123, scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+        note: "id must be a string",
+    },
+    {
+        name: "reject wrong-typed evidence",
+        expect: "reject",
+        input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "empirical", provenance: "measured", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z", evidence: "not-an-array" },
+        note: "evidence, if present, must be a string array",
+    },
+    {
+        name: "accept well-formed measured record with evidence + optionals",
+        expect: "accept",
+        input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "instance", scopeRef: "elem-7", subject: "latency", mode: "empirical", provenance: "measured", authority: "authoritative", statement: "p99 improved", createdAt: "2026-01-01T00:00:00.000Z", evidence: ["run-1", "run-2"], supersedes: "rec-old" },
+        note: "optional fields accepted when well-typed",
+    },
+];
+/**
+ * The full conformance corpus: exhaustive scope × valid/invalid triples, plus
+ * structural and vocabulary-drift cases. Deterministic and stable — treat it as
+ * the versioned contract fixture both producer and consumer are held to.
+ */
+export const corpus = [...buildCombinationalCases(), ...STRUCTURAL_CASES];
+/** The subset of the corpus that must be accepted. */
+export const validFixtures = corpus.filter((c) => c.expect === "accept");
+/** The subset of the corpus that must be rejected. */
+export const invalidFixtures = corpus.filter((c) => c.expect === "reject");
+// ---------------------------------------------------------------------------
+// The runner
+// ---------------------------------------------------------------------------
+/**
+ * Adapt a `{ ok } | { ... }`-returning validator (like `validateMemoryRecord`)
+ * to the {@link ConformanceValidator} shape. Any function returning an object
+ * with a boolean `ok` already conforms; this is a typed identity helper.
+ */
+export function fromResultValidator(validate) {
+    return (input) => ({ ok: validate(input).ok });
+}
+/**
+ * Run `validate` against the corpus (or a supplied subset) and return a
+ * structured report. Pure: does not throw and does not depend on a test runner.
+ */
+export function runConformance(validate, cases = corpus) {
+    const results = cases.map((c) => {
+        // A validator that throws (even accidentally) must not crash the run: treat
+        // a throw as a rejection so the runner stays pure and the doc above holds.
+        let ok;
+        try {
+            ok = validate(c.input).ok;
+        }
+        catch {
+            ok = false;
+        }
+        const actual = ok ? "accept" : "reject";
+        return { case: c, expected: c.expect, actual, passed: actual === c.expect };
+    });
+    const failures = results.filter((r) => !r.passed);
+    return {
+        total: results.length,
+        passed: results.length - failures.length,
+        failed: failures.length,
+        results,
+        failures,
+    };
+}
+/**
+ * Assert full conformance: throws with a readable summary if any case fails.
+ * Consumers can call this in their own test suite to be held to the contract.
+ */
+export function assertConformance(validate, cases = corpus) {
+    const report = runConformance(validate, cases);
+    if (report.failed > 0) {
+        const detail = report.failures
+            .map((f) => `  - ${f.case.name}: expected ${f.expected}, got ${f.actual} (${f.case.note})`)
+            .join("\n");
+        throw new Error(`conformance failed: ${report.failed}/${report.total} case(s):\n${detail}`);
+    }
+}

package/dist/context/conformance/records.conformance.js

@@ -0,0 +1,52 @@
+// Runnable conformance suite — matched by the pre-declared `test:conformance`
+// glob (src/context/conformance/**/*.conformance.ts). It holds THIS repo's
+// producer validator (`validateMemoryRecord`) to the shared corpus. The consumer
+// (nano-workforce#291) imports the same `corpus` + `runConformance`/
+// `assertConformance` and runs it against its own validator, so both sides prove
+// they agree on the exact same fixtures.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { validateMemoryRecord } from "../schema/index.js";
+import { corpus, runConformance, assertConformance, fromResultValidator, validFixtures, invalidFixtures, } from "./index.js";
+const validator = fromResultValidator(validateMemoryRecord);
+test("corpus is non-trivial and partitioned", () => {
+    assert.ok(corpus.length >= 50, `expected a substantial corpus, got ${corpus.length}`);
+    assert.ok(validFixtures.length > 0);
+    assert.ok(invalidFixtures.length > 0);
+    assert.equal(validFixtures.length + invalidFixtures.length, corpus.length);
+    // Case names must be unique so failures are unambiguous.
+    assert.equal(new Set(corpus.map((c) => c.name)).size, corpus.length);
+});
+test("producer validator satisfies the full conformance corpus", () => {
+    const report = runConformance(validator);
+    assert.equal(report.failed, 0, `failures:\n${report.failures.map((f) => `${f.case.name}: expected ${f.expected}, got ${f.actual}`).join("\n")}`);
+    assert.equal(report.passed, report.total);
+});
+test("assertConformance does not throw for the producer validator", () => {
+    assert.doesNotThrow(() => assertConformance(validator));
+});
+test("runConformance treats a throwing validator as a rejection instead of crashing", () => {
+    const throwing = () => {
+        throw new Error("boom");
+    };
+    // The runner must stay pure: no throw escapes, and every case is scored `reject`.
+    let report;
+    assert.doesNotThrow(() => {
+        report = runConformance(throwing);
+    });
+    assert.ok(report);
+    if (report) {
+        assert.equal(report.total, corpus.length);
+        // Every case scores `reject`; only the corpus's reject-cases can pass.
+        const rejectCount = corpus.filter((c) => c.expect === "reject").length;
+        assert.equal(report.passed, rejectCount);
+        assert.equal(report.results.every((r) => r.actual === "reject"), true);
+    }
+});
+// Per-case granularity: one sub-test per fixture so a regression names the exact case.
+for (const c of corpus) {
+    test(`case: ${c.name}`, () => {
+        const actual = validator(c.input).ok ? "accept" : "reject";
+        assert.equal(actual, c.expect, `${c.name} — ${c.note}`);
+    });
+}

package/dist/context/schema/index.d.ts

@@ -1 +1,135 @@
-export {};
+/**
+ * The only schema version this module accepts. Records must carry it explicitly
+ * so a future producer can bump the shape while old consumers reject-with-reason
+ * instead of silently mis-reading a newer record.
+ */
+export declare const MEMORY_RECORD_SCHEMA_VERSION: 1;
+export type MemoryRecordSchemaVersion = typeof MEMORY_RECORD_SCHEMA_VERSION;
+/**
+ * The scope ladder — the granularity a record is attached to, from the most
+ * specific (a single ladder `element`) up to the whole `corpus`. The array
+ * order IS the ladder order (specific → general) and is exported so callers can
+ * reason about containment without re-deriving it.
+ */
+export declare const SCOPE_LADDER: readonly ["element", "instance", "epic", "repo", "corpus"];
+export type MemoryScope = (typeof SCOPE_LADDER)[number];
+/**
+ * Whether the record asserts a norm (`normative` — "this is how it should be")
+ * or an observation (`empirical` — "this is what was measured/seen").
+ */
+export declare const MEMORY_MODES: readonly ["normative", "empirical"];
+export type MemoryMode = (typeof MEMORY_MODES)[number];
+/**
+ * Where the record came from:
+ *  - `human`       — authored by a person.
+ *  - `agent-retro` — a retrospective prior PROPOSED by an agent. Always a
+ *                    hypothesis until ratified by governance (S3: merge of a bot
+ *                    PR). By construction it can never be authoritative here.
+ *  - `measured`    — produced by an empirical measurement. Authoritative fact.
+ *  - `instance`    — observed directly from a concrete instance run. Fact.
+ */
+export declare const PROVENANCES: readonly ["human", "agent-retro", "measured", "instance"];
+export type MemoryProvenance = (typeof PROVENANCES)[number];
+/**
+ * The authority tier — the forgery target. `hypothesis` is a not-yet-ratified
+ * claim; `authoritative` is a ratified fact/fix. The invariants below make it
+ * impossible for an `agent-retro` (or otherwise unratified) record to carry the
+ * `authoritative` tier. Governance (S3) is the ONLY thing that legitimately
+ * mints `authoritative` records, via the ratification transition it owns.
+ */
+export declare const AUTHORITIES: readonly ["hypothesis", "authoritative"];
+export type MemoryAuthority = (typeof AUTHORITIES)[number];
+/**
+ * A memory record. The required fields form the stable published contract; the
+ * optional fields are additive and safe for consumers to ignore.
+ */
+export interface MemoryRecord {
+    /** Discriminates the schema version (see MEMORY_RECORD_SCHEMA_VERSION). */
+    readonly schemaVersion: MemoryRecordSchemaVersion;
+    /** Stable, non-empty identifier for the record. */
+    readonly id: string;
+    /** The ladder level this record is attached to. */
+    readonly scope: MemoryScope;
+    /** Normative vs empirical. */
+    readonly mode: MemoryMode;
+    /** Where the record came from. */
+    readonly provenance: MemoryProvenance;
+    /** Hypothesis vs authoritative — constrained by provenance (see invariants). */
+    readonly authority: MemoryAuthority;
+    /** The claim/observation the record carries. Non-empty. */
+    readonly statement: string;
+    /** ISO-8601 timestamp of when the record was created. */
+    readonly createdAt: string;
+    /** Optional: the specific target within `scope` (e.g. an element id). */
+    readonly scopeRef?: string;
+    /** Optional: free-form subject/topic the record is about. */
+    readonly subject?: string;
+    /** Optional: references (ids/urls) backing an empirical/measured claim. */
+    readonly evidence?: readonly string[];
+    /** Optional: id of a record this one supersedes. */
+    readonly supersedes?: string;
+}
+/** A machine-readable validation failure code. */
+export type ValidationCode = "not-an-object" | "unsupported-schema-version" | "missing-field" | "wrong-type" | "empty-string" | "invalid-vocabulary" | "invalid-timestamp" | "invariant-violation";
+/** A single, human- and machine-readable validation error. */
+export interface ValidationError {
+    /** Dotted path to the offending field (empty for whole-record errors). */
+    readonly path: string;
+    /** Stable machine code. */
+    readonly code: ValidationCode;
+    /** Human-readable explanation. */
+    readonly message: string;
+}
+/** The result of validating an untrusted value. */
+export type ValidationResult = {
+    readonly ok: true;
+    readonly record: MemoryRecord;
+} | {
+    readonly ok: false;
+    readonly errors: readonly ValidationError[];
+};
+/** The three vocabulary fields the cross-field invariants constrain. */
+export interface InvariantContext {
+    readonly mode: MemoryMode;
+    readonly provenance: MemoryProvenance;
+    readonly authority: MemoryAuthority;
+}
+/**
+ * Enumerates every invariant violation in `ctx`. An empty array means the
+ * (mode, provenance, authority) triple is internally consistent.
+ *
+ * The rules, together, guarantee the hypothesis-never-fix invariant:
+ *   R1  agent-retro ⇒ hypothesis          (a proposed prior is never a fact)
+ *   R2  measured    ⇒ authoritative       (a measurement is a fact, not a guess)
+ *   R3  measured    ⇒ empirical           (you cannot "measure" a norm)
+ *   R4  instance    ⇒ authoritative       (a real observation is a fact)
+ *   R5  instance    ⇒ empirical           (an observation is not a norm)
+ *   R6  normative   ⇒ human | agent-retro (only people/agents author norms)
+ *
+ * A consequence worth stating explicitly (and tested by S7): the ONLY way to
+ * reach `authoritative` is provenance ∈ {human, measured, instance}; agent-retro
+ * is structurally excluded, so an unratified prior can never be laundered into a
+ * fact by any field permutation.
+ */
+export declare function checkInvariants(ctx: InvariantContext): readonly ValidationError[];
+/** Convenience predicate: is this a ratified, authoritative fact/fix? */
+export declare function isAuthoritative(record: MemoryRecord): boolean;
+/**
+ * Validate an untrusted value as a MemoryRecord. On success returns the record
+ * narrowed to `MemoryRecord`; on failure returns EVERY error found (not just the
+ * first) so callers can surface all problems at once. Never throws.
+ */
+export declare function validateMemoryRecord(input: unknown): ValidationResult;
+/** Type guard form of {@link validateMemoryRecord}. */
+export declare function isMemoryRecord(input: unknown): input is MemoryRecord;
+/** Error thrown by {@link assertMemoryRecord}. Carries the structured errors. */
+export declare class MemoryRecordValidationError extends Error {
+    readonly errors: readonly ValidationError[];
+    constructor(errors: readonly ValidationError[]);
+}
+/**
+ * Throwing form: returns the validated record or throws
+ * {@link MemoryRecordValidationError}. Handy for governance/write paths that
+ * treat an invalid record as a hard failure.
+ */
+export declare function assertMemoryRecord(input: unknown): MemoryRecord;