@githolon/dsl 0.114.0 → 0.116.2

package/src/value_identity.ts

@@ -0,0 +1,355 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * VALUE IDENTITY FOR TYPED VALUE OBJECTS — `nomos.vo-canonical.v1` (CAP-853).
+ *
+ * A value object's DESCRIPTOR is the canonical identity of its SHAPE. This module gives its
+ * VALUES one canonical identity too, so law can ask "is this the same value?" and "what is this
+ * value's content digest?" without `JSON.stringify` (whose bytes depend on key insertion order,
+ * and so change when a value round-trips through storage).
+ *
+ * THE ENCODING (`nomos.vo-canonical.v1`) is RFC 8785 (JSON Canonicalization Scheme) applied to the
+ * value AFTER the VO's descriptor has judged it:
+ *
+ *   - object members are emitted in UTF-16 code-unit order of their names (RFC 8785 §3.2.3);
+ *   - numbers use the ECMAScript Number-to-String spelling (RFC 8785 §3.2.2.3): `1`, `1.5`,
+ *     `1e+21`, `1e-7`; integer and float fields share that one spelling, so a float stored as a
+ *     double and read back as `2` is the same value as the authored `2`; `-0` is `0`;
+ *     NaN and ±Infinity are refused;
+ *   - strings use the RFC 8785 escapes (`\"`, `\\`, `\b \f \n \r \t`, other controls `\u00xx`,
+ *     everything else verbatim); a string that is not well-formed UTF-16 (a lone surrogate) is
+ *     refused, so its UTF-8 bytes are always defined;
+ *   - ABSENT IS NOT NULL. An absent optional member (missing, or present as `undefined`) is
+ *     omitted, exactly as storage omits it (`wire_encode.ts`); `null` is emitted only where the
+ *     descriptor declares the member nullable and is otherwise refused. `{}` and `{"a":null}` are
+ *     different values;
+ *   - a `variant(...)` carries its case in the `type` member (and a named-VO arm nests its value
+ *     under `value`), so the chosen case is always part of the encoding;
+ *   - `idOf(...)`, `brandedId(...)` and units are their wire strings/numbers; a `sha256Digest()`
+ *     member must be 64 lowercase hex characters;
+ *   - list order is significant; map (`z.record`) entry order is not.
+ *
+ * Validation is part of the encoding: a value the descriptor does not admit (an undeclared member,
+ * a missing required member, an enum outside its values, a non-integer in an `.int()` field, a
+ * wrong variant case) has NO canonical form and throws. Equality is byte equality of the encoding.
+ * The DIGEST is SHA-256 over the UTF-8 bytes of the encoding, computed through the deterministic
+ * `nomos.sha256` port of the sealed engine (the same port that names keyed births), so every peer
+ * and every replay derives the same digest. Outside an engine there is no fallback: a test installs
+ * the port. A future change to any rule above is a NEW encoding id; a stored digest should keep
+ * {@link VO_CANONICAL_ENCODING} beside it.
+ *
+ * Conformance vectors: `dsl/conformance/vo_canonical.v1.json`, replayed by the TypeScript suite,
+ * the sealed engine (`testing/test/value_contract.test.mjs`) and the Dart runtime
+ * (`dsl/dart/test/vo_canonical_test.dart`). Keep this file node-builtin-free: it rides the runtime
+ * barrel into the engine bundle.
+ */
+
+import type {
+  GeometryKind,
+  Sha256Digest,
+  ValueObjectDescriptor,
+  ValueObjectFieldDescriptor,
+} from "./fields.js";
+
+/** The versioned id of the canonical value encoding. A change to the encoding is a new id. */
+export const VO_CANONICAL_ENCODING = "nomos.vo-canonical.v1" as const;
+export type VoCanonicalEncoding = typeof VO_CANONICAL_ENCODING;
+
+/**
+ * The value-identity operations every value object carries (and {@link valueIdentity} derives for
+ * lists and maps of them). Usable inside `.plan()` and invariant `.assert(...)` bodies.
+ */
+export interface ValueIdentity<T> {
+  /** The encoding these operations implement (`nomos.vo-canonical.v1`). */
+  readonly encoding: VoCanonicalEncoding;
+  /** The canonical encoding of `value` (throws when the descriptor does not admit the value). */
+  canonical(value: T): string;
+  /**
+   * Value equality over the canonical encoding. `undefined` (an absent optional) equals only
+   * `undefined`; a value the descriptor does not admit throws rather than comparing unequal.
+   */
+  equals(a: T | undefined, b: T | undefined): boolean;
+  /** SHA-256 (lowercase hex) of the canonical encoding's UTF-8 bytes, via the engine's port. */
+  digest(value: T): Sha256Digest;
+}
+
+/** The value-object descriptors a value may reference, by name. */
+export type ValueObjectTypes = ReadonlyMap<string, ValueObjectDescriptor>;
+
+export class VoCanonicalError extends TypeError {
+  constructor(at: string, problem: string) {
+    super(`${VO_CANONICAL_ENCODING}: ${at} ${problem}`);
+    this.name = "VoCanonicalError";
+  }
+}
+
+// ── RFC 8785 primitives ───────────────────────────────────────────────────────────────
+
+const PLAIN_STRING = /^[^"\\\u0000-\u001f\ud800-\udfff]*$/;
+
+function canonicalString(value: string, at: string): string {
+  if (PLAIN_STRING.test(value)) return `"${value}"`;
+  let out = '"';
+  for (let i = 0; i < value.length; i++) {
+    const c = value.charCodeAt(i);
+    if (c >= 0xd800 && c <= 0xdbff) {
+      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : -1;
+      if (next < 0xdc00 || next > 0xdfff) throw new VoCanonicalError(at, "is not well-formed UTF-16 (a lone high surrogate)");
+      out += value[i]! + value[i + 1]!;
+      i++;
+      continue;
+    }
+    if (c >= 0xdc00 && c <= 0xdfff) throw new VoCanonicalError(at, "is not well-formed UTF-16 (a lone low surrogate)");
+    switch (c) {
+      case 0x22: out += '\\"'; break;
+      case 0x5c: out += "\\\\"; break;
+      case 0x08: out += "\\b"; break;
+      case 0x0c: out += "\\f"; break;
+      case 0x0a: out += "\\n"; break;
+      case 0x0d: out += "\\r"; break;
+      case 0x09: out += "\\t"; break;
+      default:
+        out += c < 0x20 ? `\\u00${c < 0x10 ? "0" : ""}${c.toString(16)}` : value[i]!;
+    }
+  }
+  return `${out}"`;
+}
+
+function canonicalNumber(value: number, at: string): string {
+  if (!Number.isFinite(value)) throw new VoCanonicalError(at, "is not a finite number (NaN and Infinity have no canonical form)");
+  // ECMAScript Number::toString IS the RFC 8785 number spelling; String(-0) is "0".
+  return String(value);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function members(entries: readonly (readonly [string, string])[]): string {
+  // Keys are compared as UTF-16 code units: the default Array#sort order, as RFC 8785 requires.
+  const sorted = [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${sorted.map(([k, v]) => `${canonicalString(k, "member name")}:${v}`).join(",")}}`;
+}
+
+/**
+ * @internal RFC 8785 canonical JSON of an UNTYPED json value (no descriptor): object members sorted,
+ * `undefined` members omitted, ECMAScript number spelling. Used where law compares plain json leaves
+ * (point guards, birth keys); typed value objects use their descriptor-driven identity instead.
+ */
+export function canonicalJsonValue(value: unknown, at = "value"): string {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "string": return canonicalString(value, at);
+    case "number": return canonicalNumber(value, at);
+    case "boolean": return value ? "true" : "false";
+    case "object": {
+      if (Array.isArray(value)) {
+        const out: string[] = [];
+        for (let i = 0; i < value.length; i++) {
+          if (value[i] === undefined) throw new VoCanonicalError(`${at}[${i}]`, "is undefined (a list has no absent elements)");
+          out.push(canonicalJsonValue(value[i], `${at}[${i}]`));
+        }
+        return `[${out.join(",")}]`;
+      }
+      if (!isPlainObject(value)) throw new VoCanonicalError(at, "is not a plain json object");
+      return members(Object.keys(value)
+        .filter((k) => value[k] !== undefined)
+        .map((k) => [k, canonicalJsonValue(value[k], `${at}.${k}`)] as const));
+    }
+    default:
+      throw new VoCanonicalError(at, `is a ${typeof value}, which json cannot carry`);
+  }
+}
+
+// ── descriptor-driven encoding ───────────────────────────────────────────────────────
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+function canonicalField(
+  d: ValueObjectFieldDescriptor,
+  value: unknown,
+  types: ValueObjectTypes,
+  at: string,
+): string {
+  if (value === undefined) throw new VoCanonicalError(at, "is absent, but only an optional member may be absent");
+  if (value === null) {
+    if (d.nullable === true) return "null";
+    throw new VoCanonicalError(at, "is null, but its descriptor does not declare it nullable");
+  }
+  switch (d.type) {
+    case "string": {
+      if (typeof value !== "string") throw new VoCanonicalError(at, "must be a string");
+      if (d.digest === "sha256" && !SHA256_HEX.test(value)) {
+        throw new VoCanonicalError(at, "must be a SHA-256 digest: 64 lowercase hexadecimal characters");
+      }
+      if (d.idOf !== undefined && value.length === 0) throw new VoCanonicalError(at, `must be a non-empty ${d.idOf} id`);
+      return canonicalString(value, at);
+    }
+    case "enum":
+      if (typeof value !== "string" || !d.values.includes(value)) {
+        throw new VoCanonicalError(at, `must be one of ${d.values.map((v) => `'${v}'`).join(", ")}`);
+      }
+      return canonicalString(value, at);
+    case "literal":
+      if (value !== d.value) throw new VoCanonicalError(at, `must be the literal '${d.value}'`);
+      return canonicalString(value, at);
+    case "boolean":
+      if (typeof value !== "boolean") throw new VoCanonicalError(at, "must be a boolean");
+      return value ? "true" : "false";
+    case "number":
+      if (typeof value !== "number") throw new VoCanonicalError(at, "must be a number");
+      if (d.int === true && !Number.isSafeInteger(value)) throw new VoCanonicalError(at, "must be an exact (safe) integer");
+      return canonicalNumber(value, at);
+    case "array": {
+      if (!Array.isArray(value)) throw new VoCanonicalError(at, "must be a list");
+      const out: string[] = [];
+      for (let i = 0; i < value.length; i++) out.push(canonicalField(d.items, value[i], types, `${at}[${i}]`));
+      return `[${out.join(",")}]`;
+    }
+    case "map": {
+      if (!isPlainObject(value)) throw new VoCanonicalError(at, "must be a string-keyed map (a plain object)");
+      return members(Object.keys(value).map((k) => [k, canonicalField(d.values, value[k], types, `${at}[${JSON.stringify(k)}]`)] as const));
+    }
+    case "object":
+    case "geometry": {
+      const target = types.get(d.ref);
+      if (target === undefined) throw new VoCanonicalError(at, `references the undeclared value object '${d.ref}'`);
+      return canonicalValueObject(target, value, types, at);
+    }
+  }
+}
+
+function canonicalMembers(
+  fields: Readonly<Record<string, ValueObjectFieldDescriptor>>,
+  object: Record<string, unknown>,
+  types: ValueObjectTypes,
+  at: string,
+  extra: readonly (readonly [string, string])[] = [],
+  reserved: readonly string[] = [],
+): string {
+  for (const key of Object.keys(object)) {
+    if (!(key in fields) && !reserved.includes(key) && object[key] !== undefined) {
+      throw new VoCanonicalError(`${at}.${key}`, "is not a declared member");
+    }
+  }
+  const out: (readonly [string, string])[] = [...extra];
+  for (const key of Object.keys(fields)) {
+    const member = fields[key]!;
+    const value = Object.prototype.hasOwnProperty.call(object, key) ? object[key] : undefined;
+    if (value === undefined) {
+      if (member.optional === true) continue; // ABSENT: omitted, exactly as storage omits it
+      throw new VoCanonicalError(`${at}.${key}`, "is a required member but is absent");
+    }
+    out.push([key, canonicalField(member, value, types, `${at}.${key}`)]);
+  }
+  return members(out);
+}
+
+const POSITION_DEPTH: Record<GeometryKind, number> = { Point: 0, LineString: 1, MultiPoint: 1, Polygon: 2 };
+const MIN_LENGTH: Record<GeometryKind, readonly number[]> = { Point: [], LineString: [2], MultiPoint: [0], Polygon: [0, 4] };
+
+function canonicalCoordinates(kind: GeometryKind, value: unknown, depth: number, at: string): string {
+  if (!Array.isArray(value)) throw new VoCanonicalError(at, "must be a list");
+  if (depth === 0) {
+    if (value.length < 2 || value.length > 3) throw new VoCanonicalError(at, "must be a position: [lng, lat] or [lng, lat, altitude]");
+    return `[${value.map((n, i) => {
+      if (typeof n !== "number") throw new VoCanonicalError(`${at}[${i}]`, "must be a number");
+      return canonicalNumber(n, `${at}[${i}]`);
+    }).join(",")}]`;
+  }
+  const min = MIN_LENGTH[kind][POSITION_DEPTH[kind] - depth] ?? 0;
+  if (value.length < min) throw new VoCanonicalError(at, `must hold at least ${min} entries`);
+  return `[${value.map((v, i) => canonicalCoordinates(kind, v, depth - 1, `${at}[${i}]`)).join(",")}]`;
+}
+
+/**
+ * The `nomos.vo-canonical.v1` encoding of `value` as an instance of the value object `descriptor`
+ * (nested value objects resolve through `types`). Throws {@link VoCanonicalError} when the
+ * descriptor does not admit the value.
+ */
+export function canonicalValueObject(
+  descriptor: ValueObjectDescriptor,
+  value: unknown,
+  types: ValueObjectTypes,
+  at: string = descriptor.name,
+): string {
+  if (!isPlainObject(value)) throw new VoCanonicalError(at, `must be a ${descriptor.name} object`);
+  if (descriptor.fields !== undefined) return canonicalMembers(descriptor.fields, value, types, at);
+  if (descriptor.union !== undefined) {
+    const kase = value["type"];
+    if (typeof kase !== "string" || !Object.prototype.hasOwnProperty.call(descriptor.union, kase)) {
+      throw new VoCanonicalError(`${at}.type`, `must name a declared case of ${descriptor.name} (${Object.keys(descriptor.union).join(", ")})`);
+    }
+    const arm = descriptor.union[kase]!;
+    const type = [["type", canonicalString(kase, `${at}.type`)]] as const;
+    if ("ref" in arm) {
+      const target = types.get(arm.ref);
+      if (target === undefined) throw new VoCanonicalError(at, `references the undeclared value object '${arm.ref}'`);
+      return canonicalMembers(
+        { value: { type: "object", ref: arm.ref } },
+        value, types, at, type, ["type"],
+      );
+    }
+    return canonicalMembers(arm.fields, value, types, at, type, ["type"]);
+  }
+  if (descriptor.geometry !== undefined) {
+    const kind = descriptor.geometry;
+    for (const key of Object.keys(value)) {
+      if (key !== "type" && key !== "coordinates" && value[key] !== undefined) {
+        throw new VoCanonicalError(`${at}.${key}`, "is not a member of an RFC 7946 geometry");
+      }
+    }
+    if (value["type"] !== kind) throw new VoCanonicalError(`${at}.type`, `must be '${kind}'`);
+    return members([
+      ["type", canonicalString(kind, `${at}.type`)],
+      ["coordinates", canonicalCoordinates(kind, value["coordinates"], POSITION_DEPTH[kind], `${at}.coordinates`)],
+    ]);
+  }
+  throw new VoCanonicalError(at, `has no fields, cases or geometry in its descriptor`);
+}
+
+/** The canonical encoding of a value typed by one descriptor FIELD (a list, map, or nested VO). */
+export function canonicalDescribedValue(
+  field: ValueObjectFieldDescriptor,
+  value: unknown,
+  types: ValueObjectTypes,
+  at = "value",
+): string {
+  return canonicalField(field, value, types, at);
+}
+
+/** SHA-256 of `text`'s UTF-8 bytes through the ONE deterministic host port, `nomos.sha256`. */
+function portSha256(text: string): Sha256Digest {
+  const host = (globalThis as { nomos?: { sha256?: (s: string) => string } }).nomos;
+  if (host === undefined || typeof host.sha256 !== "function") {
+    throw new Error(
+      `${VO_CANONICAL_ENCODING}: digest() needs the deterministic \`nomos.sha256\` port of the Nomos engine. ` +
+        "It runs inside .plan() and invariant bodies; a test installs globalThis.nomos.sha256.",
+    );
+  }
+  const digest = host.sha256(text);
+  if (typeof digest !== "string" || !SHA256_HEX.test(digest)) {
+    throw new Error(`${VO_CANONICAL_ENCODING}: the nomos.sha256 port returned a malformed digest`);
+  }
+  return digest as Sha256Digest;
+}
+
+/** Build the identity operations over one canonical-encoding function. */
+export function identityOf<T>(encode: (value: unknown) => string): ValueIdentity<T> {
+  return {
+    encoding: VO_CANONICAL_ENCODING,
+    canonical: (value: T) => encode(value),
+    equals(a: T | undefined, b: T | undefined): boolean {
+      if (a === undefined || b === undefined) return a === b;
+      return encode(a) === encode(b);
+    },
+    digest: (value: T) => portSha256(encode(value)),
+  };
+}

package/src/value_object.ts

@@ -66,7 +66,14 @@ import {
   type ValueObjectDescriptor,
   type ValueObjectFieldDescriptor,
   type ValueObjectFieldMeta,
+  type TypedId,
 } from "./fields.js";
+import {
+  canonicalDescribedValue,
+  canonicalValueObject,
+  identityOf,
+  type ValueIdentity,
+} from "./value_identity.js";
 // LOCAL zod introspection (the same `_def ?? def` convention as codegen_ts.ts) —
 // deliberately NOT imported from codegen_ts.js: this module rides the RUNTIME barrel
 // (the engine lump bundles it, `--platform=neutral`), and codegen_ts transitively
@@ -131,7 +138,7 @@ export interface OptionalValueObject<T = unknown> {
  * Carries the zod (validation + TS inference), the canonical descriptor (the IR/codegen
  * shape), and lowers onto an aggregate via {@link ValueObject.field}.
  */
-export interface ValueObject<T = unknown> {
+export interface ValueObject<T = unknown> extends ValueIdentity<T> {
   readonly __isValueObject: true;
   /** The declared name — the generated TS interface / Dart class name. */
   readonly name: string;
@@ -167,6 +174,10 @@ export interface ValueObject<T = unknown> {
   merge(driver: Driver): Field<T, "json">;
   /** Phantom to keep T load-bearing for inference. */
   readonly _t?: T;
+  // VALUE IDENTITY (CAP-853, `value_identity.ts`): `canonical(v)` is the `nomos.vo-canonical.v1`
+  // encoding (RFC 8785 over the descriptor-judged value), `equals(a, b)` compares encodings,
+  // `digest(v)` is its SHA-256 through the engine's deterministic port. Use them in `.plan()` and
+  // invariant bodies instead of `JSON.stringify`, whose bytes depend on key order.
 }
 
 /** Infer the authored TS type of a ValueObject. */
@@ -434,14 +445,16 @@ export const NOMOS_BRANDED_ID_BRAND: unique symbol = Symbol.for("nomos.brandedId
 
 const BRAND_NAME_RE = /^[A-Z][A-Za-z0-9_]*$/;
 
-/** Declare a NOMINAL string id: `siteId: brandedId("SiteId")`. */
-export function brandedId(name: string): z.ZodType<string> {
+/** Declare a NOMINAL string id: `siteId: brandedId("SiteId")`. The parsed value is typed
+ * {@link TypedId}`<"SiteId">` in law code too (the same type a `t.brandedId("SiteId")` field holds), so a
+ * plain string is a compile error on both sides of the wire. */
+export function brandedId<const Name extends string>(name: Name): z.ZodType<TypedId<Name>> {
   if (!BRAND_NAME_RE.test(name)) {
     throw new Error(`brandedId: '${name}' must be a capitalized identifier — it becomes the generated branded type's name.`);
   }
   const schema = z.string();
   Object.defineProperty(schema, NOMOS_BRANDED_ID_BRAND, { value: name, enumerable: false });
-  return schema;
+  return schema as unknown as z.ZodType<TypedId<Name>>;
 }
 
 /** Resolve the `brandedId(...)` brand name of a schema (through optional/default/nullable). */
@@ -645,6 +658,20 @@ export function voMetaOf(zt: z.ZodTypeAny): ValueObjectFieldMeta | undefined {
   return undefined;
 }
 
+/**
+ * VALUE IDENTITY for a constrained schema built FROM value objects — `valueIdentity(z.array(Site))`,
+ * `valueIdentity(z.record(z.string(), Reading))`, `valueIdentity(Site.zod.optional())` — the same
+ * `nomos.vo-canonical.v1` encoding a value object's own `canonical` / `equals` / `digest` use, derived
+ * from the same descriptor rules (an out-of-set schema throws, exactly as in `valueObject(...)`).
+ * Declare it at module scope and call it inside `.plan()` / invariant bodies.
+ */
+export function valueIdentity<T>(schema: z.ZodType<T> | ValueObject<T>): ValueIdentity<T> {
+  if (isValueObject(schema)) return schema as ValueObject<T>;
+  const deps = new Map<string, ValueObjectDescriptor>();
+  const field = describeZod("valueIdentity", "value", schema as z.ZodTypeAny, deps);
+  return identityOf<T>((value) => canonicalDescribedValue(field, value, deps));
+}
+
 /** The blessed lawful sample per RFC 7946 geometry kind (proof synthesis + docs). */
 const GEOMETRY_SAMPLES: Record<GeometryKind, unknown> = {
   Point: { type: "Point", coordinates: [0, 0] },
@@ -764,7 +791,11 @@ function makeValueObject<T>(
   // serialized directly. voMetaOf() is the one resolver every introspector uses; aggregate
   // fields separately copy the canonical descriptor into their stable value contract.
   Object.defineProperty(zodSchema, NOMOS_VO_BRAND, { value: meta, enumerable: false });
+  const types = new Map<string, ValueObjectDescriptor>(
+    [descriptor, ...dependencies].map((d) => [d.name, d] as const),
+  );
   const vo: ValueObject<T> = {
+    ...identityOf<T>((value) => canonicalValueObject(descriptor, value, types)),
     __isValueObject: true,
     name,
     zod: zodSchema,

package/src/wire.ts

@@ -211,6 +211,8 @@ export interface WireIntent {
     workspace: string;
     genesisChain: unknown;
     parentWorkspaceRoles?: readonly import("./births.js").WorkspaceRole[];
+    /** The typed key the workspace name hashes (business births under typed-key law → `nomos:birthKey`). */
+    birthKey?: string;
   }[];
   /** Exact target calls authored by source law. The OpenUSD bytes come from a compiler-generated
    * encoder for the target Directive object; no public operation string or generic payload crosses. */

package/src/wire_paths.ts

@@ -0,0 +1,17 @@
+// NOMOS — The one spelling of a nested operation field's ledger label.
+//
+// A top-level payload field is ledgered under its own name. A field INSIDE a structural value
+// (a record member, a map value, a list element, a union variant) is ledgered under a path built
+// from these segments, so its transport allocation survives a change elsewhere in the structure
+// (the 1 October 2026 `canvasRequirements` incident: nested `isRequired` keys moved because their
+// structural sids moved). law_graph.ts allocates by these paths; baseline_export.ts recovers the
+// same paths from released law so the two agree without a sidecar.
+
+/** A record member beneath `parent`. */
+export const nestedMemberPath = (parent: string, name: string): string => `${parent}.${name}`;
+/** The element of a list beneath `parent`. */
+export const listElementPath = (parent: string): string => `${parent}[]`;
+/** The value of a map beneath `parent`. */
+export const mapValuePath = (parent: string): string => `${parent}{}`;
+/** One variant of a union beneath `parent`, by its discriminator label or ordinal. */
+export const unionVariantPath = (parent: string, variant: string): string => `${parent}|${variant}|`;

package/src/workspace_routing.ts

@@ -164,7 +164,7 @@ export function routeTagHexOfMintedId(id: string): string | undefined {
 // ── the plan trace (the mint-front-door family, aimed at HOMES) ──────────────────────
 
 /** Build a schema-valid probe payload: every top-level string field gets its sentinel. */
-function buildProbePayload(
+export function buildProbePayload(
   schema: z.ZodTypeAny,
   sentinelOf: Map<string, string>,
   jsonSafe = false,