@nanobpm/urban 0.57.0 → 0.59.0

package/dist/context/schema/index.js

@@ -1 +1,330 @@
-export {};
+// Slice S2 (schema) — the memory-record schema for the Urban context layer.
+//
+// This module is the RECORD HALF of the published `@nanobpm/urban/context`
+// contract (imported as `@nanobpm/urban/context/schema`). The consumer repo
+// (`nanobpm/nano-workforce#291`), the git substrate/governance slice (S3), and
+// the adversarial slice (S7) all build against the types + validator exported
+// here, so the surface is deliberately small, stable, and versioned-friendly.
+//
+// The central design goal is a FORGERY-RESISTANT-BY-CONSTRUCTION encoding of the
+// "hypothesis-never-fix" invariant: an unratified / agent-retrospective prior
+// can never be *represented* as a measured / authoritative fact. This is not a
+// runtime policy layered on top — it is baked into the controlled vocabulary and
+// the cross-field validation rules below, so no code path (governance, retrieval,
+// or a hostile caller) can construct a record that launders a hypothesis into a
+// fact. S3 relies on this to gate its write path; S7 attacks it directly.
+// ---------------------------------------------------------------------------
+// Versioning
+// ---------------------------------------------------------------------------
+/**
+ * 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 const MEMORY_RECORD_SCHEMA_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Controlled vocabulary
+// ---------------------------------------------------------------------------
+/**
+ * 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 const SCOPE_LADDER = ["element", "instance", "epic", "repo", "corpus"];
+/**
+ * Whether the record asserts a norm (`normative` — "this is how it should be")
+ * or an observation (`empirical` — "this is what was measured/seen").
+ */
+export const MEMORY_MODES = ["normative", "empirical"];
+/**
+ * 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 const PROVENANCES = ["human", "agent-retro", "measured", "instance"];
+/**
+ * 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 const AUTHORITIES = ["hypothesis", "authoritative"];
+// ---------------------------------------------------------------------------
+// Small, assertion-free narrowing helpers
+// ---------------------------------------------------------------------------
+// A "plain object" is one whose untrusted properties we can read WITHOUT risking
+// a throw: it must carry `Object.prototype` (or a null prototype) and expose only
+// own data properties. Objects with accessor properties (getters/setters) or
+// exotic prototypes are rejected, because reading such a property could throw
+// (e.g. `{ get id() { throw ... } }`) and break `validateMemoryRecord`'s "never
+// throws" contract for hostile inputs. Any reflection error is likewise swallowed
+// as a rejection rather than allowed to propagate.
+function isPlainObject(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return false;
+    try {
+        const proto = Object.getPrototypeOf(v);
+        if (proto !== Object.prototype && proto !== null)
+            return false;
+        for (const key of Reflect.ownKeys(v)) {
+            const descriptor = Object.getOwnPropertyDescriptor(v, key);
+            if (descriptor === undefined || descriptor.get !== undefined || descriptor.set !== undefined) {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isNonEmptyString(v) {
+    return typeof v === "string" && v.length > 0;
+}
+function includes(vocabulary, v) {
+    return typeof v === "string" && vocabulary.some((entry) => entry === v);
+}
+// Single source of truth for how a controlled-vocabulary field fails: absent is
+// `missing-field`, a non-string is `wrong-type` (so callers can tell a bad type
+// apart from a drifted value), and a string outside the ladder is
+// `invalid-vocabulary`. Shared by scope/mode/provenance/authority.
+function vocabularyCode(value) {
+    if (value === undefined)
+        return "missing-field";
+    if (typeof value !== "string")
+        return "wrong-type";
+    return "invalid-vocabulary";
+}
+// Single source of truth for how a non-empty-string field fails: absent is
+// `missing-field`, an empty string is `empty-string` (a valid type callers can
+// surface distinctly in UX), and any other non-string is `wrong-type`. Shared by
+// required (`id`, `statement`) and optional (`scopeRef`, `supersedes`) fields;
+// optional callers guard `undefined` before calling so it never surfaces.
+function nonEmptyStringCode(value) {
+    if (value === undefined)
+        return "missing-field";
+    if (value === "")
+        return "empty-string";
+    return "wrong-type";
+}
+function isIsoTimestamp(v) {
+    if (typeof v !== "string" || v.length === 0)
+        return false;
+    // Require a real, round-trippable ISO-8601 instant (date + time + zone).
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/.test(v)) {
+        return false;
+    }
+    return Number.isFinite(Date.parse(v));
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((entry) => typeof entry === "string");
+}
+/**
+ * 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 function checkInvariants(ctx) {
+    const errors = [];
+    // Cross-field invariants are whole-record violations (they constrain the
+    // mode/provenance/authority triple jointly), so report them at the empty
+    // (whole-record) path rather than mis-pointing consumers at `authority`.
+    const push = (message) => errors.push({ path: "", code: "invariant-violation", message });
+    if (ctx.provenance === "agent-retro" && ctx.authority === "authoritative") {
+        push("hypothesis-never-fix: an 'agent-retro' prior is unratified and can never be 'authoritative'. Ratification is governance's job (S3: merge of the proposing PR).");
+    }
+    if (ctx.provenance === "measured" && ctx.authority !== "authoritative") {
+        push("a 'measured' record is an empirical fact and must be 'authoritative'.");
+    }
+    if (ctx.provenance === "measured" && ctx.mode !== "empirical") {
+        push("a 'measured' record is an observation and must have mode 'empirical', not 'normative'.");
+    }
+    if (ctx.provenance === "instance" && ctx.authority !== "authoritative") {
+        push("an 'instance' observation is a fact and must be 'authoritative'.");
+    }
+    if (ctx.provenance === "instance" && ctx.mode !== "empirical") {
+        push("an 'instance' observation must have mode 'empirical', not 'normative'.");
+    }
+    if (ctx.mode === "normative" && !(ctx.provenance === "human" || ctx.provenance === "agent-retro")) {
+        push("a 'normative' record asserts a norm and may only be authored by 'human' or proposed by 'agent-retro'.");
+    }
+    return errors;
+}
+/** Convenience predicate: is this a ratified, authoritative fact/fix? */
+export function isAuthoritative(record) {
+    return record.authority === "authoritative";
+}
+// ---------------------------------------------------------------------------
+// The validator
+// ---------------------------------------------------------------------------
+/**
+ * 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 function validateMemoryRecord(input) {
+    const errors = [];
+    if (!isPlainObject(input)) {
+        return {
+            ok: false,
+            errors: [{ path: "", code: "not-an-object", message: "record must be a plain object." }],
+        };
+    }
+    // Version first — a wrong version means the rest of the shape is unreliable.
+    // Distinguish an absent version (missing-field, like every other required
+    // field), a wrong-typed version (wrong-type, e.g. a string), and a
+    // present-but-unsupported numeric version (unsupported-schema-version) so the
+    // structured error is honest and consistent with the other required fields.
+    if (input.schemaVersion !== MEMORY_RECORD_SCHEMA_VERSION) {
+        const version = input.schemaVersion;
+        const versionCode = version === undefined ? "missing-field" : typeof version !== "number" ? "wrong-type" : "unsupported-schema-version";
+        errors.push({
+            path: "schemaVersion",
+            code: versionCode,
+            message: versionCode === "missing-field"
+                ? "schemaVersion is required."
+                : versionCode === "wrong-type"
+                    ? "schemaVersion must be a number."
+                    : `unsupported schemaVersion; expected ${MEMORY_RECORD_SCHEMA_VERSION}.`,
+        });
+    }
+    // Capture fields into const locals: TypeScript's aliased-condition narrowing
+    // persists a type-guard result across statements only for `const` references,
+    // not for repeated property accesses. This lets us build the typed record at
+    // the end WITHOUT any `as` cast (forbidden by the biome plugin).
+    const idVal = input.id;
+    const statementVal = input.statement;
+    const createdAtVal = input.createdAt;
+    const scopeVal = input.scope;
+    const modeVal = input.mode;
+    const provenanceVal = input.provenance;
+    const authorityVal = input.authority;
+    const idOk = isNonEmptyString(idVal);
+    if (!idOk) {
+        errors.push({
+            path: "id",
+            code: nonEmptyStringCode(idVal),
+            message: "id must be a non-empty string.",
+        });
+    }
+    const statementOk = isNonEmptyString(statementVal);
+    if (!statementOk) {
+        errors.push({
+            path: "statement",
+            code: nonEmptyStringCode(statementVal),
+            message: "statement must be a non-empty string.",
+        });
+    }
+    const createdAtOk = isIsoTimestamp(createdAtVal);
+    if (!createdAtOk) {
+        errors.push({
+            path: "createdAt",
+            code: createdAtVal === undefined ? "missing-field" : "invalid-timestamp",
+            message: "createdAt must be an ISO-8601 timestamp with a timezone.",
+        });
+    }
+    const scopeOk = includes(SCOPE_LADDER, scopeVal);
+    if (!scopeOk) {
+        errors.push({ path: "scope", code: vocabularyCode(scopeVal), message: `scope must be one of: ${SCOPE_LADDER.join(", ")}.` });
+    }
+    const modeOk = includes(MEMORY_MODES, modeVal);
+    if (!modeOk) {
+        errors.push({ path: "mode", code: vocabularyCode(modeVal), message: `mode must be one of: ${MEMORY_MODES.join(", ")}.` });
+    }
+    const provenanceOk = includes(PROVENANCES, provenanceVal);
+    if (!provenanceOk) {
+        errors.push({ path: "provenance", code: vocabularyCode(provenanceVal), message: `provenance must be one of: ${PROVENANCES.join(", ")}.` });
+    }
+    const authorityOk = includes(AUTHORITIES, authorityVal);
+    if (!authorityOk) {
+        errors.push({ path: "authority", code: vocabularyCode(authorityVal), message: `authority must be one of: ${AUTHORITIES.join(", ")}.` });
+    }
+    // Optional fields: reject wrong types, ignore when absent.
+    const scopeRefVal = input.scopeRef;
+    const subjectVal = input.subject;
+    const evidenceVal = input.evidence;
+    const supersedesVal = input.supersedes;
+    if (scopeRefVal !== undefined && !isNonEmptyString(scopeRefVal)) {
+        errors.push({ path: "scopeRef", code: nonEmptyStringCode(scopeRefVal), message: "scopeRef, if present, must be a non-empty string." });
+    }
+    if (subjectVal !== undefined && typeof subjectVal !== "string") {
+        errors.push({ path: "subject", code: "wrong-type", message: "subject, if present, must be a string." });
+    }
+    if (evidenceVal !== undefined && !isStringArray(evidenceVal)) {
+        errors.push({ path: "evidence", code: "wrong-type", message: "evidence, if present, must be an array of strings." });
+    }
+    if (supersedesVal !== undefined && !isNonEmptyString(supersedesVal)) {
+        errors.push({ path: "supersedes", code: nonEmptyStringCode(supersedesVal), message: "supersedes, if present, must be a non-empty string." });
+    }
+    // Cross-field invariants can only run once the vocabulary fields are sound.
+    if (modeOk && provenanceOk && authorityOk) {
+        for (const err of checkInvariants({ mode: modeVal, provenance: provenanceVal, authority: authorityVal })) {
+            errors.push(err);
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    // All guards passed; aliased narrowing makes the const locals fully typed here.
+    if (!scopeOk || !modeOk || !provenanceOk || !authorityOk || !idOk || !statementOk || !createdAtOk) {
+        return { ok: false, errors: [{ path: "", code: "wrong-type", message: "internal: unexpected narrowing failure." }] };
+    }
+    const record = {
+        schemaVersion: MEMORY_RECORD_SCHEMA_VERSION,
+        id: idVal,
+        scope: scopeVal,
+        mode: modeVal,
+        provenance: provenanceVal,
+        authority: authorityVal,
+        statement: statementVal,
+        createdAt: createdAtVal,
+        ...(isNonEmptyString(scopeRefVal) ? { scopeRef: scopeRefVal } : {}),
+        ...(typeof subjectVal === "string" ? { subject: subjectVal } : {}),
+        ...(isStringArray(evidenceVal) ? { evidence: evidenceVal } : {}),
+        ...(isNonEmptyString(supersedesVal) ? { supersedes: supersedesVal } : {}),
+    };
+    return { ok: true, record };
+}
+/** Type guard form of {@link validateMemoryRecord}. */
+export function isMemoryRecord(input) {
+    return validateMemoryRecord(input).ok;
+}
+/** Error thrown by {@link assertMemoryRecord}. Carries the structured errors. */
+export class MemoryRecordValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(`invalid memory record: ${errors.map((e) => `${e.path || "<record>"}: ${e.message}`).join("; ")}`);
+        this.name = "MemoryRecordValidationError";
+        this.errors = errors;
+    }
+}
+/**
+ * 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 function assertMemoryRecord(input) {
+    const result = validateMemoryRecord(input);
+    if (!result.ok) {
+        throw new MemoryRecordValidationError(result.errors);
+    }
+    return result.record;
+}