@githolon/dsl 0.52.0 → 0.54.0

package/src/codegen_ts.ts

@@ -55,6 +55,14 @@ const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUp
 const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
 const upperSnake = (s: string) => s.replace(/[-\s]+/g, "_").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
 
+/** A count/sum group-by field → a valid TS param identifier. A DOTTED group-by (`location.source`,
+ *  the #30 follow-up) camel-joins into `locationSource` (a bare `location.source` is not a legal
+ *  positional param name); a flat field is unchanged. Mirrors the Dart `dartKeyParam`. */
+const tsGroupParam = (by: string) => {
+  const parts = by.split(".").filter((p) => p !== "");
+  return parts.length <= 1 ? by : parts[0]! + parts.slice(1).map((p) => p[0]!.toUpperCase() + p.slice(1)).join("");
+};
+
 // ── NAME NORMALIZATION (no naming convention to learn) ────────────────────────────
 // `nomos.package.mjs` names and domain keys may be ANY string — kebab-case,
 // snake_case, space-separated, PascalCase. Artifact FILENAMES keep the raw name
@@ -381,8 +389,11 @@ function tsTypeOfField(field: Field): string {
     case "set":
       return "string[]"; // `t.set(t.string())` is the one set shape (fields.ts)
     case "map": {
+      // A map of a NAMED value object (`t.map(VO.field())`) types each entry as the VO
+      // interface; scalar-valued maps keep their primitive value type.
       const v =
-        field.mapValueKind === "string" ? "string"
+        field.mapValueVo !== undefined ? field.mapValueVo.name
+        : field.mapValueKind === "string" ? "string"
         : field.mapValueKind === "int" ? "number"
         : "unknown";
       return `Record<string, ${v}>`;
@@ -399,13 +410,22 @@ const geometryCoordsTs: Record<string, string> = {
   Point: "number[]",
   LineString: "number[][]",
   Polygon: "number[][][]",
+  MultiPoint: "number[][]",
+};
+
+/** The `geo.*` factory name for a geometry kind (used in generated doc comments). */
+const geometryFactoryName: Record<string, string> = {
+  Point: "point",
+  LineString: "lineString",
+  Polygon: "polygon",
+  MultiPoint: "multiPoint",
 };
 
 /** One descriptor field → its TS type text. NO FALLBACK (the descriptor set is closed). */
 function tsTypeOfVoField(f: ValueObjectFieldDescriptor): string {
   switch (f.type) {
     case "string":
-      return "string";
+      return f.brand ?? "string"; // a brandedId(...) → the emitted branded alias
     case "number":
       return "number"; // `.int()`/units are Dart-side nominal products; TS keeps one number
     case "boolean":
@@ -416,18 +436,36 @@ function tsTypeOfVoField(f: ValueObjectFieldDescriptor): string {
       return JSON.stringify(f.value);
     case "array":
       return `${paren(tsTypeOfVoField(f.items))}[]`;
+    case "map":
+      return `Record<string, ${tsTypeOfVoField(f.values)}>`;
     case "object":
     case "geometry":
       return f.ref; // the named VO interface (emitted alongside)
   }
 }
 
+/** Every branded-id name a VO descriptor carries (recursing arrays/maps/union arms) — one
+ *  `export type <Brand> = string & {…}` alias is emitted per distinct brand. */
+function voBrandNames(d: ValueObjectDescriptor): Set<string> {
+  const brands = new Set<string>();
+  const walk = (f: ValueObjectFieldDescriptor): void => {
+    if (f.type === "string" && f.brand !== undefined) brands.add(f.brand);
+    else if (f.type === "array") walk(f.items);
+    else if (f.type === "map") walk(f.values);
+  };
+  for (const f of Object.values(d.fields ?? {})) walk(f);
+  for (const arm of Object.values(d.union ?? {})) {
+    if ("fields" in arm) for (const f of Object.values(arm.fields)) walk(f);
+  }
+  return brands;
+}
+
 /** Emit one `export interface <VO> { ... }` from its canonical descriptor. A geo VO
  *  emits the fixed RFC 7946 shape (`{ type: "<kind>"; coordinates: ... }`). */
 function emitValueObjectTs(d: ValueObjectDescriptor): string[] {
   if (d.geometry !== undefined) {
     return [
-      `/** RFC 7946 ${d.geometry} — a \`geo.${d.geometry === "Point" ? "point" : d.geometry === "LineString" ? "lineString" : "polygon"}(...)\` value object. */`,
+      `/** RFC 7946 ${d.geometry} — a \`geo.${geometryFactoryName[d.geometry]}(...)\` value object. */`,
       `export interface ${d.name} { type: ${JSON.stringify(d.geometry)}; coordinates: ${geometryCoordsTs[d.geometry]}; }`,
       ``,
     ];
@@ -596,7 +634,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  count(countId: string, groupKey?: string): Promise<number>;`,
   `  /** THE SPATIAL READ (R*Tree probe): rows intersecting the bbox — same row shape as query().`,
   `   *  OPTIONAL member: structural binding tolerates a pre-spatial holon (the accessor then throws at call). */`,
-  `  spatialWithin?(spatialId: string, bbox: { minLng: number; minLat: number; maxLng: number; maxLat: number }): Promise<unknown>;`,
+  `  spatialWithin?(spatialId: string, bbox: { minX: number; minY: number; maxX: number; maxY: number } | { minLng: number; minLat: number; maxLng: number; maxLat: number }): Promise<unknown>;`,
     `  sum(sumId: string, groupKey?: string): Promise<number>;`,
     ...(anyPackedTaxonomy(modules)
       ? [
@@ -609,10 +647,33 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  deadLetters(): Promise<{ id?: string; oid: string; source: string; error: string; domain?: string | null; directiveId?: string | null; at: string }[]>;`,
     `  retryDeadLetter(id: string): Promise<{ ok: boolean; head?: string; alreadyOnMain?: boolean; error?: string }>;`,
     `  discardDeadLetter(id: string): Promise<{ ok: boolean; removed: number }>;`,
-    `  /** THE CONNECT-TIME COMPAT CLASSIFIER (§5) — OPTIONAL: a holon from @githolon/client's connect()`,
-    `   *  attaches it (implemented by \`checkCompat\`); the generated factory hands over this client's baked`,
-    `   *  compat manifest so a law-hash mismatch logs a warning. DIAGNOSIS only — never throws, never gates. */`,
-    `  checkCompat?(compat: { lawHash: string; interfaceHash: string; packageName: string }): void;`,
+    `  /** THE COMPAT SUPERPOWER (#72b) — OPTIONAL: a holon from @githolon/client's connect() attaches it.`,
+    `   *  The factory hands over this client's baked compat manifest + structural interface (the requirement),`,
+    `   *  and the holon computes the LIVE per-member verdict on \`holon.compat\`. A KNOWN-incompatible directive`,
+    `   *  then refuses CLIENT-SIDE at write time (LawMismatchError), never as a server 422. */`,
+    `  checkCompat?(compat: { lawHash: string; interfaceHash: string; packageName: string }, requirement?: unknown): NomosCompatVerdict | null;`,
+    `  /** The live compat verdict (set by checkCompat). \`has(memberId)\` is the dark-launch feature flag;`,
+    `   *  \`refresh()\` re-derives against the current projection. Absent until the factory binds. */`,
+    `  compat?: NomosCompatVerdict;`,
+    `  /** Subscribe to holon events. \`lawChanged\` fires when a synced install/upgrade/retire moves the`,
+    `   *  workspace's offer under this live client (the compat verdict re-derived). Returns unsubscribe. */`,
+    `  on?(event: "lawChanged", cb: (compat: NomosCompatVerdict) => void): () => void;`,
+    `}`,
+    ``,
+    `/** THE LIVE COMPAT VERDICT (#72b) stashed on \`holon.compat\`. \`verdict\` is the three-state roll-up;`,
+    ` *  \`members\` names each directive/aggregate's own \`{ ok, reason? }\`; \`install\` is the deployed law's`,
+    ` *  lifecycle phase. \`has(id)\` = the feature flag; \`refresh()\` re-evaluates against the projection. */`,
+    `export interface NomosCompatVerdict {`,
+    `  generatedFor: string;`,
+    `  workspaceRuns: string[];`,
+    `  matches: boolean;`,
+    `  offerKnown: boolean;`,
+    `  structurallyCompatible: boolean | null;`,
+    `  verdict: "compatible" | "degraded" | "incompatible";`,
+    `  members: Record<string, { ok: boolean; reason?: string }>;`,
+    `  install: { phase: string; supersededBy?: string };`,
+    `  has(memberId: string): boolean;`,
+    `  refresh(): Promise<NomosCompatVerdict | null>;`,
     `}`,
     ``,
     `/** AUTHORITY IS UNFORGEABLE-BY-CONSTRUCTION: a GATED directive (one carrying a \`.requires(relation)\` write`,
@@ -944,6 +1005,14 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   }
   if (voByName.size > 0) {
     out.push(`// ── value objects (named, composable json-object leaves — value_object.ts) ──`, ``);
+    // BRANDED-ID aliases (brandedId(...)) — one nominal `string & { __brand }` per distinct
+    // brand any VO carries; wire-identical to a string, a compile error to cross-assign.
+    const brands = new Set<string>();
+    for (const [, d] of voByName) for (const b of voBrandNames(d)) brands.add(b);
+    for (const b of [...brands].sort()) {
+      out.push(`/** Branded id \`${b}\` — a nominal string (\`brandedId("${b}")\`); wire-identical to a string. */`);
+      out.push(`export type ${b} = string & { readonly __brand: "${b}" };`, ``);
+    }
     for (const [, d] of [...voByName].sort(([a], [b]) => a.localeCompare(b))) {
       out.push(...emitValueObjectTs(d));
     }
@@ -1290,7 +1359,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     for (const sp of (mod.spatials ?? []) as { id: string; of: string; on: string }[]) {
       methods.push(
         `    /** Declared spatial index \`${sp.id}\` — rows of \`${sp.of}\` whose \`${sp.on}\` geometry intersects the bbox (R*Tree probe). */`,
-        `    ${lcFirst(camel(sp.id))}: (bbox: { minLng: number; minLat: number; maxLng: number; maxLat: number }) => (holon.spatialWithin ?? (() => { throw new Error("this holon predates spatial reads — upgrade @githolon/client"); }))(${JSON.stringify(sp.id)}, bbox) as Promise<Row<${sp.of}Data>[]>,`,
+        `    ${lcFirst(camel(sp.id))}: (bbox: { minX: number; minY: number; maxX: number; maxY: number } | { minLng: number; minLat: number; maxLng: number; maxLat: number }) => (holon.spatialWithin ?? (() => { throw new Error("this holon predates spatial reads — upgrade @githolon/client"); }))(${JSON.stringify(sp.id)}, bbox) as Promise<Row<${sp.of}Data>[]>,`,
       );
     }
     for (const q of (mod.queries ?? []) as QueryDecl[]) {
@@ -1326,19 +1395,21 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
 
     for (const c of (mod.counts ?? []).map((raw) => finishCount(raw))) {
       const grouped = c.by != null;
+      const p = grouped ? tsGroupParam(c.by!) : "";
       methods.push(
         `    /** Declared count \`${c.id}\` — the maintained O(1) ${grouped ? `tally per \`${c.by}\`` : "grand total"}. */`,
         grouped
-          ? `    ${lcFirst(camel(c.id))}: (${c.by}: string) => holon.count(${JSON.stringify(c.id)}, ${c.by}),`
+          ? `    ${lcFirst(camel(c.id))}: (${p}: string) => holon.count(${JSON.stringify(c.id)}, ${p}),`
           : `    ${lcFirst(camel(c.id))}: () => holon.count(${JSON.stringify(c.id)}),`,
       );
     }
     for (const s of (mod.sums ?? []).map((raw) => finishSum(raw))) {
       const grouped = s.by != null;
+      const p = grouped ? tsGroupParam(s.by!) : "";
       methods.push(
         `    /** Declared sum \`${s.id}\` — the maintained O(1) ${grouped ? `total per \`${s.by}\`` : "grand total"}. */`,
         grouped
-          ? `    ${lcFirst(camel(s.id))}: (${s.by}: string) => holon.sum(${JSON.stringify(s.id)}, ${s.by}),`
+          ? `    ${lcFirst(camel(s.id))}: (${p}: string) => holon.sum(${JSON.stringify(s.id)}, ${p}),`
           : `    ${lcFirst(camel(s.id))}: () => holon.sum(${JSON.stringify(s.id)}),`,
       );
     }
@@ -1369,7 +1440,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `  const actor = opts.actor;`,
       ...(encPresent ? [`  const keyStore = opts.keyStore;`] : []),
       ...(opts.compat !== undefined
-        ? [`  holon.checkCompat?.(${compatConstName(opts.packageName)});`]
+        ? [
+            opts.interface !== undefined
+              ? `  holon.checkCompat?.(${compatConstName(opts.packageName)}, ${interfaceConstName(opts.packageName)});`
+              : `  holon.checkCompat?.(${compatConstName(opts.packageName)});`,
+          ]
         : []),
       `  return {`,
       `    domain: ${JSON.stringify(domain)} as const,`,

package/src/compat_package_main.ts

@@ -0,0 +1,187 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * `githolon compat <target> [--config …] [--json]` — THE CI GATE (task #31, the compat superpower).
+ *
+ * Compares the CURRENT build's structural interface (`build/<name>.interface.json`, the client's
+ * REQUIREMENT) against a TARGET's installed law (the workspace OFFER), PER MEMBER, via the #72
+ * subtype relation (`memberVerdicts`). Exits NON-ZERO on any incompatible member — so a client/law
+ * mismatch is caught in CI, before it ships. The target is:
+ *   • a deploy.json (`build/<name>.deploy.json`) — its staged `.interface` is the offer;
+ *   • an `.interface.json` (or a build/package DIR containing one) — the offer directly;
+ *   • a LIVE workspace URL (`https://host/v2/workspaces/<ws>` or `https://host --workspace <ws>`) —
+ *     connect()s and reads the on-ledger offer (`holon.interfaceOffer()`).
+ *
+ * Human report by default; `--json` emits the machine surface (the per-member array + verdict).
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+import { memberVerdicts, type DomainInterface, type MemberVerdict } from "./shape_compat.js";
+
+interface PackageConfig {
+  name: string;
+}
+type InterfaceMap = Record<string, DomainInterface>;
+
+function fail(msg: string): never {
+  console.error(`githolon compat: ${msg}`);
+  process.exit(2);
+}
+
+/** Merge a per-domain interface map into ONE flat interface (directives + aggregates unioned). */
+function mergeInterfaces(byDomain: InterfaceMap | undefined): DomainInterface {
+  const out: DomainInterface = { v: 1, domain: "*", directives: {}, aggregates: {} };
+  for (const di of Object.values(byDomain ?? {})) {
+    if (!di || typeof di !== "object") continue;
+    Object.assign(out.directives, di.directives ?? {});
+    Object.assign(out.aggregates, di.aggregates ?? {});
+  }
+  return out;
+}
+
+/** The package name from `nomos.package.mjs` (only field we need — to locate `build/<name>.interface.json`). */
+async function loadPackageName(configArg: string): Promise<{ name: string; dir: string }> {
+  const configPath = path.resolve(process.cwd(), configArg);
+  if (!existsSync(configPath)) fail(`config not found: ${configPath} (pass the package config, or run from the package dir)`);
+  const { pathToFileURL } = await import("node:url");
+  const cfg = ((await import(`${pathToFileURL(configPath).href}?t=${Date.now()}`)) as { default?: PackageConfig }).default;
+  if (!cfg || typeof cfg.name !== "string") fail(`config must default-export { name, … }`);
+  return { name: cfg.name, dir: path.dirname(configPath) };
+}
+
+/** The CURRENT build's interface — `build/<name>.interface.json`. Requires a prior `githolon compile`. */
+function loadCurrentInterface(pkgDir: string, name: string): InterfaceMap {
+  const p = path.join(pkgDir, "build", `${name}.interface.json`);
+  if (!existsSync(p)) {
+    fail(
+      `no current interface at ${p} — run \`githolon compile\` first so the build carries the structural interface this checks.`,
+    );
+  }
+  try {
+    return JSON.parse(readFileSync(p, "utf8")) as InterfaceMap;
+  } catch (e) {
+    fail(`could not parse ${p}: ${(e as Error).message}`);
+  }
+}
+
+/** Read a TARGET offer from a file path (deploy.json / interface.json / dir). Returns `{ offer, source }`. */
+function loadFileOffer(arg: string): { offer: InterfaceMap; source: string } {
+  const abs = path.resolve(process.cwd(), arg);
+  if (!existsSync(abs)) fail(`target not found: ${abs}`);
+  let file = abs;
+  if (statSync(abs).isDirectory()) {
+    const scan = (d: string): string | undefined => {
+      if (!existsSync(d)) return undefined;
+      const hit =
+        readdirSync(d).find((f) => f.endsWith(".deploy.json")) ?? readdirSync(d).find((f) => f.endsWith(".interface.json"));
+      return hit !== undefined ? path.join(d, hit) : undefined;
+    };
+    const found = scan(abs) ?? scan(path.join(abs, "build"));
+    if (found === undefined) fail(`no *.deploy.json or *.interface.json under ${abs}`);
+    file = found;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    fail(`could not parse ${file}: ${(e as Error).message}`);
+  }
+  const p = parsed as Record<string, unknown>;
+  // A deploy.json carries `{ …, interface }`; a bare interface.json IS the {[domain]: interface} map.
+  const offer = (p.interface !== undefined ? p.interface : p) as InterfaceMap;
+  if (offer === null || typeof offer !== "object") fail(`target ${file} carries no structural interface`);
+  return { offer, source: file };
+}
+
+/** Read a LIVE workspace's on-ledger offer via connect() (`@githolon/client`). */
+async function loadLiveOffer(url: string, workspaceFlag?: string): Promise<{ offer: InterfaceMap; source: string }> {
+  const m = /^(https?:\/\/[^/]+)(?:\/v2\/workspaces\/([^/?#]+))?/.exec(url);
+  if (!m) fail(`could not parse the live target URL: ${url}`);
+  const cloud = m[1]!;
+  const workspace = workspaceFlag ?? m[2];
+  if (!workspace) fail(`live target needs a workspace — use https://host/v2/workspaces/<ws> or add --workspace <ws>`);
+  let connect: (opts: { cloud: string; workspace: string }) => Promise<{ interfaceOffer(): Promise<InterfaceMap | null> }>;
+  try {
+    ({ connect } = (await import("@githolon/client")) as unknown as { connect: typeof connect });
+  } catch {
+    fail(`live target needs @githolon/client installed (it is a dependency of githolon)`);
+  }
+  const holon = await connect({ cloud, workspace });
+  const offer = await holon.interfaceOffer();
+  if (offer === null) fail(`workspace '${workspace}' exposes no on-ledger structural interface (pre-#72e law)`);
+  return { offer, source: `${cloud}/v2/workspaces/${workspace}` };
+}
+
+interface MemberReport {
+  member: string;
+  kind: "directive" | "aggregate";
+  ok: boolean;
+  reason?: string;
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  const flagVal = (name: string): string | undefined => {
+    const i = argv.indexOf(name);
+    if (i >= 0) return argv[i + 1];
+    const inline = argv.find((a) => a.startsWith(`${name}=`));
+    return inline?.slice(name.length + 1);
+  };
+  const asJson = argv.includes("--json");
+  const configArg = flagVal("--config") ?? "nomos.package.mjs";
+  const workspaceFlag = flagVal("--workspace");
+  // The positional target = the first non-flag arg that isn't a flag VALUE.
+  const flagsWithVals = new Set(["--config", "--workspace"]);
+  const target = argv.find((a, i) => !a.startsWith("--") && !(i > 0 && flagsWithVals.has(argv[i - 1]!)));
+  if (!target) fail(`usage: githolon compat <workspace-url | deploy.json | interface.json | dir> [--config <cfg>] [--workspace <ws>] [--json]`);
+
+  const { name, dir } = await loadPackageName(configArg);
+  const current = loadCurrentInterface(dir, name);
+
+  const { offer, source } = /^https?:\/\//.test(target)
+    ? await loadLiveOffer(target, workspaceFlag)
+    : loadFileOffer(target);
+
+  // The subtype check is PER MEMBER over the merged interfaces (directives keyed by id, aggregates by label).
+  const verdicts = memberVerdicts(mergeInterfaces(current), mergeInterfaces(offer));
+  // Tag each member's kind for the report (a directive id vs an aggregate label).
+  const merged = mergeInterfaces(current);
+  const dirIds = new Set(Object.keys(merged.directives));
+  const reports: MemberReport[] = Object.entries(verdicts)
+    .map(([member, v]: [string, MemberVerdict]) => ({
+      member,
+      kind: (dirIds.has(member) ? "directive" : "aggregate") as MemberReport["kind"],
+      ok: v.ok,
+      ...(v.reason !== undefined ? { reason: v.reason } : {}),
+    }))
+    .sort((a, b) => (a.member < b.member ? -1 : a.member > b.member ? 1 : 0));
+
+  const incompatible = reports.filter((r) => !r.ok);
+  const verdict = incompatible.length > 0 ? "incompatible" : "compatible";
+
+  if (asJson) {
+    process.stdout.write(JSON.stringify({ package: name, target: source, verdict, members: reports }) + "\n");
+    process.exit(incompatible.length > 0 ? 1 : 0);
+  }
+
+  console.log(`githolon compat: package '${name}' vs ${source}`);
+  console.log(`  ${reports.length} member(s) checked — ${verdict.toUpperCase()}`);
+  for (const r of reports) {
+    const mark = r.ok ? "  ✓ " : "  ✗ ";
+    console.log(`${mark}${r.kind} '${r.member}'${r.ok ? "" : ` — ${r.reason}`}`);
+  }
+  if (incompatible.length > 0) {
+    console.log(
+      `\ngitholon compat: ${incompatible.length} incompatible member(s) — this client cannot ship against that law. ` +
+        `Recompile + regenerate the client (githolon compile), or deploy a law that still exposes these members.`,
+    );
+  } else {
+    console.log(`\ngitholon compat: all members compatible — safe to ship.`);
+  }
+  process.exit(incompatible.length > 0 ? 1 : 0);
+}
+
+void main();

package/src/compile_package_main.ts

@@ -1676,6 +1676,7 @@ async function main(): Promise<void> {
   let proofSkip: string | undefined;
   let proofDomains: string[] = [];
   let birthWarnings: string[] = [];
+  let proofNotes: string[] = [];
   try {
     const proofSrc = generateTsProof(domainModules, { packageName: cfg.name, domainHash });
     proofPath = path.join(outDir, `${cfg.name}.proof.mts`);
@@ -1689,6 +1690,9 @@ async function main(): Promise<void> {
       writeFileSync(path.join(outDir, `${cfg.name}.proof-legs.json`), JSON.stringify(legsIndex, null, 2) + "\n", "utf8");
       proofDomains = Object.keys(legsIndex.domains);
       birthWarnings = Object.values(legsIndex.domains).flatMap((l) => l.birthDiagnostics ?? []);
+      // TAXONOMY AUDIT: every creating directive not covered by a leg is NAMED-WHY (exact-path synthesis
+      // failure / attestation lane / gated-create authority gap) — never a silent drop.
+      proofNotes = Object.values(legsIndex.domains).flatMap((l) => l.proofDiagnostics ?? []);
     }
   } catch (e) {
     proofSkip = (e as Error).message;
@@ -1699,7 +1703,10 @@ async function main(): Promise<void> {
   if (proofSkip !== undefined && birthWarnings.length === 0) {
     try {
       const idx = proofLegsIndex(domainModules);
-      if (idx !== null) birthWarnings = Object.values(idx.domains).flatMap((l) => l.birthDiagnostics ?? []);
+      if (idx !== null) {
+        birthWarnings = Object.values(idx.domains).flatMap((l) => l.birthDiagnostics ?? []);
+        proofNotes = Object.values(idx.domains).flatMap((l) => l.proofDiagnostics ?? []);
+      }
     } catch { /* diagnostics are best-effort */ }
   }
 
@@ -1817,6 +1824,9 @@ async function main(): Promise<void> {
   for (const w of birthWarnings) {
     console.log(`  ⚠ births   ${w}`);
   }
+  for (const w of proofNotes) {
+    console.log(`  – proof    NAMED-WHY (unproven directive): ${w}`);
+  }
   // ── THE AUTHOR-TIME GATE (architecture/author_time_gate.md) — the static twins of the kernel
   //    gate's refusal vocabulary, unified into ONE report. `githolon check` runs the same pass;
   //    compile runs it implicitly and REFUSES on any refuse-level finding (a statically-provable

package/src/fields.ts

@@ -76,9 +76,11 @@ export const evidenceRefSchema: z.ZodType<EvidenceRefValue> = z.object({
 // The descriptor types live HERE (dependency-free) so `Field` can carry the metadata
 // without a `fields.ts → value_object.ts` cycle; `value_object.ts` re-exports them.
 
-/** The RFC 7946 geometry kinds a `geo.*` value object can declare (Point is the
- *  spatial-index-blessed one; see `spatial.ts`). */
-export type GeometryKind = "Point" | "LineString" | "Polygon";
+/** The RFC 7946 geometry kinds a `geo.*` value object can declare. Point is the ONLY
+ *  spatial-index-blessed one (the kernel R*Tree indexes point bounding boxes; see
+ *  `spatial.ts`) — LineString/Polygon/MultiPoint round-trip as typed geometry but are
+ *  NOT yet indexable (non-point R*Tree ingestion is future kernel work). */
+export type GeometryKind = "Point" | "LineString" | "Polygon" | "MultiPoint";
 
 /**
  * One field of a value-object DESCRIPTOR — the canonical, JSON-schema-ish shape that
@@ -88,7 +90,10 @@ export type GeometryKind = "Point" | "LineString" | "Polygon";
  * not expressible — the v1 constrained set).
  */
 export type ValueObjectFieldDescriptor =
-  | { readonly type: "string"; readonly optional?: true }
+  /** A plain string, OR a BRANDED nominal string when `brand` is present (a `brandedId(...)`
+   * — the generated TS branded alias / Dart extension-type wrapper's name). Wire-identical
+   * to a plain string; the brand is a compile-time nominal tag only. */
+  | { readonly type: "string"; readonly brand?: string; readonly optional?: true }
   /** `int: true` when the zod carried `.int()` (Dart `int`, TS `number`); `unit` when the field
    * was declared through `unit(...)` — the generated Dart extension-type wrapper's name. */
   | { readonly type: "number"; readonly int?: true; readonly unit?: string; readonly optional?: true }
@@ -97,6 +102,9 @@ export type ValueObjectFieldDescriptor =
   /** A `z.literal(<string>)` — a CONSTANT discriminator-style member (generated as a getter). */
   | { readonly type: "literal"; readonly value: string; readonly optional?: true }
   | { readonly type: "array"; readonly items: ValueObjectFieldDescriptor; readonly optional?: true }
+  /** A MAP/RECORD (`z.record(z.string(), X)`) — string-keyed entries of `values`. TS
+   * `Record<string, V>`, Dart `Map<String, V>`; the wire is a plain json object. */
+  | { readonly type: "map"; readonly values: ValueObjectFieldDescriptor; readonly optional?: true }
   /** A nested value object, referenced BY NAME (its own descriptor rides alongside). */
   | { readonly type: "object"; readonly ref: string; readonly optional?: true }
   /** A nested GEO value object (RFC 7946 geometry), referenced by name. */
@@ -203,6 +211,15 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * {@link ValueObjectFieldMeta}). `undefined` for every non-VO field.
    */
   readonly valueObject?: ValueObjectFieldMeta;
+  /**
+   * For a `t.map(inner)` whose INNER value is a NAMED VALUE OBJECT (`t.map(VO.field())`):
+   * the inner VO's metadata, so codegen surfaces the map as `Map<String, VoClass>` /
+   * `Record<string, VoClass>` (each entry decoded via `VoClass.fromProjected`) instead of
+   * the raw `Map<String, Object?>` / `Record<string, unknown>`. FRONTEND/IR-ONLY (the wire
+   * driver is `MapOf(Lww)` exactly as for a plain json-valued map — NO hash change).
+   * `undefined` for a non-map field or a map of scalars.
+   */
+  readonly mapValueVo?: ValueObjectFieldMeta;
   /**
    * Whether a folded aggregate may LACK this field. A SCALAR field
    * (`string`/`int`/`enum`/`ref`/`json`) that a `.creates` directive does not
@@ -279,6 +296,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     mapValueKind?: FieldKind;
     jsonShape?: "object";
     valueObject?: ValueObjectFieldMeta;
+    mapValueVo?: ValueObjectFieldMeta;
     encrypted?: true;
     meta?: true;
     facet?: FieldFacet;
@@ -297,6 +315,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.mapValueKind !== undefined ? { mapValueKind: extra.mapValueKind } : {}),
     ...(extra.jsonShape !== undefined ? { jsonShape: extra.jsonShape } : {}),
     ...(extra.valueObject !== undefined ? { valueObject: extra.valueObject } : {}),
+    ...(extra.mapValueVo !== undefined ? { mapValueVo: extra.mapValueVo } : {}),
     ...(extra.encrypted ? { isEncrypted: true as const } : {}),
     ...(extra.meta ? { isMeta: true as const } : {}),
     ...(extra.fromBirth ? { isFromBirth: true as const } : {}),
@@ -442,7 +461,13 @@ export const t = {
       "map",
       z.record(z.string(), inner.zod),
       { kind: "MapOf", inner: inner.driver },
-      { mapValueKind: inner.kind },
+      {
+        mapValueKind: inner.kind,
+        // A map of a NAMED value object (`t.map(VO.field())`) carries the inner VO's
+        // metadata so codegen types each entry as the VO class (frontend-only; the wire
+        // driver is `MapOf(Lww)` either way — no hash change).
+        ...(inner.valueObject !== undefined ? { mapValueVo: inner.valueObject } : {}),
+      },
     );
   },
   /** Arbitrary JSON-string leaf (used inside maps); encodes as a Str at op time. The

package/src/index.ts

@@ -51,6 +51,8 @@ export {
   unit,
   idOf,
   idOfMetaOf,
+  brandedId,
+  brandedIdMetaOf,
   voMetaOf,
   voSample,
   NOMOS_VO_BRAND,
@@ -65,6 +67,7 @@ export {
   type GeoPointValue,
   type GeoLineStringValue,
   type GeoPolygonValue,
+  type GeoMultiPointValue,
   type ValueObjectUsage,
 } from "./value_object.js";
 export {
@@ -201,6 +204,16 @@ export {
   type OfSpatial,
   type TypelessSpatial,
 } from "./spatial.js";
+// TYPED PATH HANDLES (#29): `path(Agg).location.point` — a compile-checked field-path reference that
+// collapses to the dotted string, accepted by `spatial(...).on(...)` and `query(...).key(...)`.
+export {
+  path,
+  isPathRef,
+  pathString,
+  type PathRef,
+  type PathNode,
+  type PathRoot,
+} from "./path.js";
 export {
   sum,
   finishSum,