@nanobpm/urban 0.57.0 → 0.59.0

package/src/context/schema/schema.test.ts

@@ -0,0 +1,251 @@
+// Unit tests for the memory-record schema (slice S2). Run via
+// `npm run test --workspace @nanobpm/urban` (node --test, src/**/*.test.ts).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  validateMemoryRecord,
+  isMemoryRecord,
+  assertMemoryRecord,
+  MemoryRecordValidationError,
+  checkInvariants,
+  isAuthoritative,
+  SCOPE_LADDER,
+  MEMORY_MODES,
+  PROVENANCES,
+  AUTHORITIES,
+  MEMORY_RECORD_SCHEMA_VERSION,
+  type MemoryRecord,
+  type ValidationResult,
+} from "./index.ts";
+
+function base(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    schemaVersion: MEMORY_RECORD_SCHEMA_VERSION,
+    id: "rec-1",
+    scope: "repo",
+    mode: "empirical",
+    provenance: "human",
+    authority: "authoritative",
+    statement: "the tests pass",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+test("accepts a well-formed record and narrows it", () => {
+  const result = validateMemoryRecord(base());
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    const rec: MemoryRecord = result.record;
+    assert.equal(rec.id, "rec-1");
+    assert.equal(rec.schemaVersion, MEMORY_RECORD_SCHEMA_VERSION);
+    assert.equal(isAuthoritative(rec), true);
+  }
+});
+
+test("accepts optional fields when well-typed and drops absent ones", () => {
+  const result = validateMemoryRecord(base({ provenance: "measured", scopeRef: "elem-1", subject: "latency", evidence: ["run-1"], supersedes: "rec-0" }));
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.record.scopeRef, "elem-1");
+    assert.deepEqual(result.record.evidence, ["run-1"]);
+    assert.equal("subject" in result.record, true);
+  }
+  const bare = validateMemoryRecord(base());
+  if (bare.ok) {
+    assert.equal("scopeRef" in bare.record, false);
+    assert.equal("evidence" in bare.record, false);
+  }
+});
+
+test("rejects a non-object with a clear error", () => {
+  const result = validateMemoryRecord(42);
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.errors[0]?.code, "not-an-object");
+  }
+});
+
+test("never throws on hostile inputs: throwing getters and exotic prototypes are rejected, not read", () => {
+  // A throwing getter must not be invoked — it is rejected as not-an-object.
+  const withThrowingGetter = {
+    get id(): string {
+      throw new Error("hostile getter must never be read");
+    },
+  };
+  let hostile: ValidationResult | undefined;
+  assert.doesNotThrow(() => {
+    hostile = validateMemoryRecord(withThrowingGetter);
+  });
+  assert.equal(hostile?.ok, false);
+  if (hostile && !hostile.ok) {
+    assert.equal(hostile.errors[0]?.code, "not-an-object");
+  }
+
+  // A non-plain prototype (class instance) is likewise rejected up front.
+  class Exotic {
+    id = "";
+  }
+  const proto = validateMemoryRecord(new Exotic());
+  assert.equal(proto.ok, false);
+  if (!proto.ok) {
+    assert.equal(proto.errors[0]?.code, "not-an-object");
+  }
+
+  // A null-prototype object with only data properties is still a plain object.
+  const nullProto: Record<string, unknown> = Object.create(null);
+  nullProto.schemaVersion = MEMORY_RECORD_SCHEMA_VERSION;
+  assert.doesNotThrow(() => validateMemoryRecord(nullProto));
+});
+
+test("reports every problem, not just the first", () => {
+  const result = validateMemoryRecord({ schemaVersion: 9, scope: "galaxy", mode: "x" });
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.ok(result.errors.length >= 3);
+    const codes = new Set(result.errors.map((e) => e.code));
+    assert.ok(codes.has("unsupported-schema-version"));
+    assert.ok(codes.has("invalid-vocabulary"));
+    assert.ok(codes.has("missing-field"));
+  }
+});
+
+test("distinguishes missing, wrong-typed, and unsupported schemaVersion", () => {
+  const missing = validateMemoryRecord(base({ schemaVersion: undefined }));
+  assert.equal(missing.ok, false);
+  if (!missing.ok) {
+    assert.equal(missing.errors.find((e) => e.path === "schemaVersion")?.code, "missing-field");
+  }
+  const wrongType = validateMemoryRecord(base({ schemaVersion: "1" }));
+  assert.equal(wrongType.ok, false);
+  if (!wrongType.ok) {
+    assert.equal(wrongType.errors.find((e) => e.path === "schemaVersion")?.code, "wrong-type");
+  }
+  const unsupported = validateMemoryRecord(base({ schemaVersion: 9 }));
+  assert.equal(unsupported.ok, false);
+  if (!unsupported.ok) {
+    assert.equal(unsupported.errors.find((e) => e.path === "schemaVersion")?.code, "unsupported-schema-version");
+  }
+});
+
+test("rejects drifted vocabulary on each controlled field", () => {
+  assert.equal(validateMemoryRecord(base({ scope: "galaxy" })).ok, false);
+  assert.equal(validateMemoryRecord(base({ mode: "prescriptive" })).ok, false);
+  assert.equal(validateMemoryRecord(base({ provenance: "robot" })).ok, false);
+  assert.equal(validateMemoryRecord(base({ authority: "supreme" })).ok, false);
+});
+
+test("distinguishes wrong-type from drifted vocabulary on controlled fields", () => {
+  for (const field of ["scope", "mode", "provenance", "authority"]) {
+    const wrongType = validateMemoryRecord(base({ [field]: 42 }));
+    assert.equal(wrongType.ok, false);
+    if (!wrongType.ok) {
+      const err = wrongType.errors.find((e) => e.path === field);
+      assert.equal(err?.code, "wrong-type", `${field}: a non-string must report wrong-type, not invalid-vocabulary`);
+    }
+    const drifted = validateMemoryRecord(base({ [field]: "not-in-ladder" }));
+    assert.equal(drifted.ok, false);
+    if (!drifted.ok) {
+      const err = drifted.errors.find((e) => e.path === field);
+      assert.equal(err?.code, "invalid-vocabulary", `${field}: a drifted string must report invalid-vocabulary`);
+    }
+  }
+});
+
+test("distinguishes empty-string from wrong-type on optional non-empty-string fields", () => {
+  for (const field of ["scopeRef", "supersedes"]) {
+    const empty = validateMemoryRecord(base({ [field]: "" }));
+    assert.equal(empty.ok, false);
+    if (!empty.ok) {
+      const err = empty.errors.find((e) => e.path === field);
+      assert.equal(err?.code, "empty-string", `${field}: an empty string is a valid type and must report empty-string, not wrong-type`);
+    }
+    const wrongType = validateMemoryRecord(base({ [field]: 42 }));
+    assert.equal(wrongType.ok, false);
+    if (!wrongType.ok) {
+      const err = wrongType.errors.find((e) => e.path === field);
+      assert.equal(err?.code, "wrong-type", `${field}: a non-string must report wrong-type`);
+    }
+  }
+});
+
+test("rejects non-ISO timestamps but accepts offset zones", () => {
+  assert.equal(validateMemoryRecord(base({ createdAt: "yesterday" })).ok, false);
+  assert.equal(validateMemoryRecord(base({ createdAt: "2026-01-01" })).ok, false);
+  assert.equal(validateMemoryRecord(base({ createdAt: "2026-01-01T12:00:00+13:00" })).ok, true);
+});
+
+// --- The hypothesis-never-fix invariant, at every scope -------------------
+
+test("INVARIANT: agent-retro can never be authoritative, at any scope", () => {
+  for (const scope of SCOPE_LADDER) {
+    for (const mode of MEMORY_MODES) {
+      const result = validateMemoryRecord(base({ scope, mode, provenance: "agent-retro", authority: "authoritative" }));
+      assert.equal(result.ok, false, `agent-retro/authoritative must be rejected at ${scope}/${mode}`);
+      if (!result.ok) {
+        assert.ok(result.errors.some((e) => e.code === "invariant-violation"));
+      }
+    }
+  }
+});
+
+test("agent-retro as a hypothesis is accepted at every scope and mode", () => {
+  for (const scope of SCOPE_LADDER) {
+    for (const mode of MEMORY_MODES) {
+      assert.equal(validateMemoryRecord(base({ scope, mode, provenance: "agent-retro", authority: "hypothesis" })).ok, true);
+    }
+  }
+});
+
+test("measured/instance must be empirical + authoritative", () => {
+  assert.equal(validateMemoryRecord(base({ provenance: "measured", authority: "hypothesis" })).ok, false);
+  assert.equal(validateMemoryRecord(base({ provenance: "measured", mode: "normative", authority: "authoritative" })).ok, false);
+  assert.equal(validateMemoryRecord(base({ provenance: "instance", authority: "hypothesis" })).ok, false);
+  assert.equal(validateMemoryRecord(base({ provenance: "instance", mode: "normative", authority: "authoritative" })).ok, false);
+  assert.equal(validateMemoryRecord(base({ provenance: "measured", mode: "empirical", authority: "authoritative" })).ok, true);
+  assert.equal(validateMemoryRecord(base({ provenance: "instance", mode: "empirical", authority: "authoritative" })).ok, true);
+});
+
+test("only human/agent-retro may author a normative record", () => {
+  assert.equal(validateMemoryRecord(base({ mode: "normative", provenance: "human", authority: "hypothesis" })).ok, true);
+  assert.equal(validateMemoryRecord(base({ mode: "normative", provenance: "agent-retro", authority: "hypothesis" })).ok, true);
+  assert.equal(validateMemoryRecord(base({ mode: "normative", provenance: "measured", authority: "authoritative" })).ok, false);
+});
+
+test("checkInvariants: the only route to authoritative excludes agent-retro", () => {
+  for (const provenance of PROVENANCES) {
+    for (const mode of MEMORY_MODES) {
+      const errs = checkInvariants({ provenance, mode, authority: "authoritative" });
+      if (provenance === "agent-retro") {
+        assert.ok(errs.length > 0, "agent-retro must never validate as authoritative");
+      }
+    }
+  }
+});
+
+test("assertMemoryRecord throws MemoryRecordValidationError carrying structured errors", () => {
+  assert.throws(
+    () => assertMemoryRecord(base({ provenance: "agent-retro", authority: "authoritative" })),
+    (err: unknown) => {
+      assert.ok(err instanceof MemoryRecordValidationError);
+      assert.ok(err.errors.length > 0);
+      return true;
+    },
+  );
+  const ok = assertMemoryRecord(base());
+  assert.equal(ok.id, "rec-1");
+});
+
+test("isMemoryRecord is a usable type guard", () => {
+  const v: unknown = base();
+  assert.equal(isMemoryRecord(v), true);
+  assert.equal(isMemoryRecord(42), false);
+});
+
+test("vocabulary arrays are the expected controlled sets", () => {
+  assert.deepEqual([...SCOPE_LADDER], ["element", "instance", "epic", "repo", "corpus"]);
+  assert.deepEqual([...MEMORY_MODES], ["normative", "empirical"]);
+  assert.deepEqual([...PROVENANCES], ["human", "agent-retro", "measured", "instance"]);
+  assert.deepEqual([...AUTHORITIES], ["hypothesis", "authoritative"]);
+});

package/src/runtime/browser/runtime.browser.js

@@ -321,6 +321,36 @@ function interpTemplate(tpl, row) {
       })
     : tpl;
 }
+
+// Format a single-field cell value per a column's opt-in `col.format` (issue
+// #327). This runs in the browser, so it is the ONLY place that can render a
+// stored UTC ISO timestamp in the VIEWER'S local timezone — the server never
+// knows the viewer's zone, so a server-formatted string would always be wrong
+// for someone. Currently the sole format is "datetime": a parseable ISO/date
+// value → "11:42am Aug 19" (h:mm + lowercase am/pm, then short-month day), both
+// parts in local time. Defensive by construction: an empty value, an unparseable
+// date, or any unknown format returns the raw text verbatim — a mis-set format
+// never blanks a cell or throws, matching how an unrecognised link.kind degrades
+// to plain text. Display-only: the untransformed rawText still drives the badge
+// gate/tooltip and any sort/groupBy (those key off the real field).
+/** @param {any} format
+ * @param {string} raw
+ * @returns {string} */
+function fmtCellValue(format, raw) {
+  if (format !== "datetime" || raw === "") return raw;
+  const d = new Date(raw);
+  if (Number.isNaN(d.getTime())) return raw;
+  // Present in a stable en-US format ("11:42am Aug 19") regardless of the
+  // viewer's locale ordering (e.g. en-GB would emit "19 Aug"), while the ABSENCE
+  // of a `timeZone` option keeps both parts in the viewer's LOCAL zone. hour12
+  // forces am/pm; the replace lowercases "AM"/"a.m."/… to "am"/"pm" and drops the
+  // separating space so the output is exactly "11:42am".
+  const time = d
+    .toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit", hour12: true })
+    .replace(/\s*([AaPp])\.?\s*[Mm]\.?$/, (_m, p) => p.toLowerCase() + "m");
+  const date = d.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+  return time + " " + date;
+}
 /** @param {any} node */
 function renderText(node) {
   const v = node.props.variant;
@@ -641,9 +671,15 @@ function gridCell(col, row, role) {
   // field-derived defaults. Kept separate from the (possibly templated) display
   // text so a template never re-lights or blanks a badge.
   const rawText = row[col.field] == null ? "" : String(row[col.field]);
+  // Per-column display format (issue #327): an opt-in `col.format` transforms the
+  // single-field value for display only (e.g. "datetime" → the viewer's local
+  // time). rawText above stays untransformed so the badge gate/tooltip and any
+  // sort/groupBy still key off the real field. A col.template composes its own
+  // {{field}} tokens and therefore wins over the formatted field text below.
+  const fieldText = col.format ? fmtCellValue(col.format, rawText) : rawText;
   // Visible text: a col.template (interpolated from the row) wins over the
-  // raw field value, else the field value is shown verbatim.
-  const text = typeof col.template === "string" ? interpTemplate(col.template, row) : rawText;
+  // formatted/raw field value, else the field value is shown verbatim.
+  const text = typeof col.template === "string" ? interpTemplate(col.template, row) : fieldText;
   // 1. badge — a compact status indicator. When the row's field value is
   //    non-empty (truthy after trimming) render a small circular badge (e.g. a
   //    red "1" dot flagging an incident) whose tooltip is the full field text;
@@ -2176,4 +2212,4 @@ function boot() {
 // renderer functions / RENDERERS registry can be imported directly.
 if (typeof document !== "undefined" && document.getElementById("page")) boot();
 
-export { RENDERERS, renderText, renderButton, renderProse, renderNav };
+export { RENDERERS, renderText, renderButton, renderProse, renderNav, fmtCellValue, gridCell };

package/src/runtime/browser/runtime.browser.test.ts

@@ -7,7 +7,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { PAGE_NODE_TYPES } from "@nanobpm/nano-app-schema";
-import { RENDERERS, renderText } from "./runtime.browser.js";
+import { RENDERERS, renderText, fmtCellValue, gridCell } from "./runtime.browser.js";
 
 // ── Minimal fake DOM ────────────────────────────────────────────────────────
 // Just enough of the Element/Document surface that el()/renderText touch:
@@ -116,3 +116,45 @@ test("#291: renderText degrades to empty text (never throws) on a missing text p
   assert.equal(node.tagName, "P");
   assert.equal(node.textContent, "");
 });
+
+test('#327: fmtCellValue "datetime" renders an ISO timestamp in the viewer\'s local time as "h:mmam Mon D"', () => {
+  const iso = "2026-08-18T23:42:47.788Z";
+  const out = fmtCellValue("datetime", iso);
+  // Shape: h:mm + lowercase am/pm (no separating space), then short-month day.
+  assert.match(out, /^\d{1,2}:\d{2}(am|pm) [A-Z][a-z]{2} \d{1,2}$/, `unexpected shape: ${out}`);
+  // Local, not UTC: the hour/minute/am-pm/day track the runner's local zone, so
+  // the assertion is timezone-independent (derives the expectation from the same
+  // Date in local time) yet still proves the value isn't rendered as raw UTC.
+  const d = new Date(iso);
+  let h = d.getHours() % 12;
+  if (h === 0) h = 12;
+  const mm = String(d.getMinutes()).padStart(2, "0");
+  const ampm = d.getHours() < 12 ? "am" : "pm";
+  assert.ok(out.startsWith(`${h}:${mm}${ampm} `), `local time prefix wrong: ${out}`);
+  assert.ok(out.endsWith(` ${d.getDate()}`), `local day suffix wrong: ${out}`);
+});
+
+test("#327: fmtCellValue passes through empty, unparseable, and unknown-format values verbatim (never blank/throw)", () => {
+  assert.equal(fmtCellValue("datetime", ""), "");
+  assert.equal(fmtCellValue("datetime", "not-a-date"), "not-a-date");
+  // An unknown format is a no-op — a mis-set column shows its raw value, not blank.
+  assert.equal(fmtCellValue("nope", "2026-08-18T23:42:47.788Z"), "2026-08-18T23:42:47.788Z");
+});
+
+test("#327: gridCell applies col.format to the cell text, leaving an unformatted column verbatim", (t) => {
+  t.after(installFakeDom());
+  const iso = "2026-08-18T23:42:47.788Z";
+  const formatted = gridCell(
+    { field: "updated_at", header: "Updated", format: "datetime" },
+    { updated_at: iso },
+    "secondary",
+  );
+  assert.match(
+    formatted.textContent,
+    /^\d{1,2}:\d{2}(am|pm) [A-Z][a-z]{2} \d{1,2}$/,
+    `cell not local-formatted: ${formatted.textContent}`,
+  );
+  // No `format` → the field value renders exactly as stored (backward compatible).
+  const plain = gridCell({ field: "updated_at", header: "Updated" }, { updated_at: iso }, "secondary");
+  assert.equal(plain.textContent, iso);
+});

package/src/runtime/core/modules/pages.test.ts

@@ -378,10 +378,12 @@ test("renderer interpolates a column's per-cell template into DOM text (#214)",
   // resolving to prototype cruft — guard the own-property gate explicitly.
   assert.match(js, /Object\.prototype\.hasOwnProperty\.call\(row, key\) \? row\[key\] : null/);
   assert.match(js, /return v == null \? "" : String\(v\);/);
-  // gridCell keeps the raw single-field value separate (drives the badge gate)
-  // and lets a string template win for the rendered text.
+  // gridCell keeps the raw single-field value separate (drives the badge gate),
+  // applies an opt-in col.format to the field text (#327), and lets a string
+  // template win for the rendered text over that formatted/raw field value.
   assert.match(js, /const rawText = row\[col\.field\] == null \? "" : String\(row\[col\.field\]\);/);
-  assert.match(js, /const text = typeof col\.template === "string" \? interpTemplate\(col\.template, row\) : rawText;/);
+  assert.match(js, /const fieldText = col\.format \? fmtCellValue\(col\.format, rawText\) : rawText;/);
+  assert.match(js, /const text = typeof col\.template === "string" \? interpTemplate\(col\.template, row\) : fieldText;/);
 });
 
 test("renderer renders a column's subtitle as a muted second line, never an href (#257)", async () => {