@githolon/dsl 0.52.0 → 0.54.0

package/src/value_object.ts

@@ -44,11 +44,12 @@
  * `t.jsonObject()` field. The `nomosValueObjects` USD key is emitted IFF a domain's
  * aggregates carry ≥1 VO field; a VO-free domain's package bytes are untouched.
  *
- * THE v1 CONSTRAINED FIELD SET (no fallback — anything else throws at compile):
- * `z.string()` · `z.number()` (int or float) · `z.boolean()` · `z.enum([...])` ·
- * `z.array(<any of these>)` · a nested `ValueObject` · and `.optional()` on any of
- * them (arrays of optionals excluded). Unions, records, maps, tuples, dates etc. are
- * deliberately OUT — this surface is forever; grow it deliberately.
+ * THE CONSTRAINED FIELD SET (no fallback — anything else throws at compile):
+ * `z.string()` (plain, `brandedId(...)`, or `idOf(...)`) · `z.number()` (int/float/`unit(...)`) ·
+ * `z.boolean()` · `z.enum([...])` · `z.literal("x")` · `z.array(<any of these>)` ·
+ * `z.record(z.string(), <any of these>)` · a nested `ValueObject` · a `variant(...)` sum ·
+ * and `.optional()` on any of them (arrays/records of optionals excluded). Tuples, dates,
+ * non-string-keyed records etc. are deliberately OUT — grow this surface deliberately.
  */
 import { z } from "zod";
 
@@ -71,6 +72,8 @@ type ZodInternalDef = {
   innerType?: z.ZodTypeAny;
   element?: z.ZodTypeAny;
   entries?: Record<string, string | number>;
+  valueType?: z.ZodTypeAny;
+  keyType?: z.ZodTypeAny;
 };
 function zodDef(zt: z.ZodTypeAny): ZodInternalDef {
   const raw = zt as unknown as { _def?: ZodInternalDef; def?: ZodInternalDef };
@@ -93,6 +96,17 @@ function zodArrayElement(zt: z.ZodTypeAny): z.ZodTypeAny {
   if (typeof def.type !== "string" && def.type !== undefined) return def.type;
   throw new Error("valueObject: ZodArray has no element type");
 }
+/** The VALUE schema of a `z.record(z.string(), V)` (across zod v4's def encodings). */
+function zodRecordValue(zt: z.ZodTypeAny): z.ZodTypeAny {
+  const def = zodDef(zt);
+  if (def.valueType !== undefined) return def.valueType;
+  throw new Error("valueObject: ZodRecord has no value type");
+}
+/** The KEY schema of a `z.record(K, V)` — v1 requires a plain `z.string()` key. */
+function zodRecordKeyKind(zt: z.ZodTypeAny): string {
+  const def = zodDef(zt);
+  return def.keyType !== undefined ? zodKind(def.keyType) : "string";
+}
 
 export type { GeometryKind, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
 
@@ -254,6 +268,43 @@ export function idOf(aggregate: { id: string } | string): z.ZodType<string> {
   return schema;
 }
 
+/**
+ * THE BRANDED-ID BRAND (dart_codegen_parity.md P2 — the standalone twin of {@link idOf}) —
+ * `brandedId("SiteId")` is a NOMINAL string: wire-identical to `z.string()` (validation +
+ * domainHash untouched) but the generated TS is a branded alias
+ * (`type SiteId = string & { readonly __brand }`) and the generated Dart a zero-cost
+ * extension type (`extension type const SiteId(String value) {}`), so passing a bare string
+ * — or another brand — where a `SiteId` belongs is a COMPILE error. Unlike `idOf`, it is NOT
+ * bound to an aggregate handle: use it for any nominal string id (external refs, opaque
+ * tokens) inside VO shapes / payloads. Identity + codec only — no generated behaviour.
+ */
+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> {
+  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;
+}
+
+/** Resolve the `brandedId(...)` brand name of a schema (through optional/default/nullable). */
+export function brandedIdMetaOf(zt: z.ZodTypeAny): string | undefined {
+  let cur: z.ZodTypeAny | undefined = zt;
+  for (let hops = 0; cur !== undefined && hops < 16; hops++) {
+    const branded = (cur as unknown as Record<symbol, unknown>)[NOMOS_BRANDED_ID_BRAND];
+    if (typeof branded === "string") return branded;
+    const kind = zodKind(cur);
+    if (kind !== "optional" && kind !== "default" && kind !== "nullable") return undefined;
+    cur = zodDef(cur).innerType;
+  }
+  return undefined;
+}
+
 /** Resolve the `idOf(...)` aggregate type of a payload schema (through optional/default). */
 export function idOfMetaOf(zt: z.ZodTypeAny): string | undefined {
   let cur: z.ZodTypeAny | undefined = zt;
@@ -310,8 +361,28 @@ function describeZod(
   const ownBrand = (schema as unknown as Record<symbol, unknown>)[NOMOS_VO_BRAND];
   if (ownBrand !== undefined) return takeVoField(ownBrand as ValueObjectFieldMeta, deps);
   switch (zodKind(schema)) {
-    case "string":
-      return { type: "string" };
+    case "string": {
+      const brand = (schema as unknown as Record<symbol, unknown>)[NOMOS_BRANDED_ID_BRAND]
+        ?? (schema as unknown as Record<symbol, unknown>)[NOMOS_IDOF_BRAND];
+      // idOf's brand is the aggregate type name; a payload idOf surfaces as `<Agg>Id`.
+      const brandName =
+        typeof (schema as unknown as Record<symbol, unknown>)[NOMOS_BRANDED_ID_BRAND] === "string"
+          ? (brand as string)
+          : typeof brand === "string"
+            ? `${brand}Id`
+            : undefined;
+      return brandName !== undefined ? { type: "string", brand: brandName } : { type: "string" };
+    }
+    case "record": {
+      if (zodRecordKeyKind(schema) !== "string") {
+        throw new Error(`valueObject '${voName}': field '${path}' — only string-keyed records (z.record(z.string(), …)) are in the v1 set.`);
+      }
+      const values = describeZod(voName, `${path}{}`, zodRecordValue(schema), deps);
+      if (values.optional === true) {
+        throw new Error(`valueObject '${voName}': field '${path}' is a record of optionals — not expressible in the v1 set.`);
+      }
+      return { type: "map", values };
+    }
     case "number": {
       const unitName = (schema as unknown as Record<symbol, unknown>)[NOMOS_UNIT_BRAND];
       return {
@@ -391,6 +462,7 @@ const GEOMETRY_SAMPLES: Record<GeometryKind, unknown> = {
   Point: { type: "Point", coordinates: [0, 0] },
   LineString: { type: "LineString", coordinates: [[0, 0], [1, 1]] },
   Polygon: { type: "Polygon", coordinates: [[[0, 0], [0, 1], [1, 1], [0, 0]]] },
+  MultiPoint: { type: "MultiPoint", coordinates: [[0, 0], [1, 1]] },
 };
 
 function sampleOfDescriptorField(
@@ -398,6 +470,7 @@ function sampleOfDescriptorField(
   fieldName: string,
   byName: Map<string, ValueObjectDescriptor>,
   includeOptional = false,
+  path = fieldName,
 ): unknown {
   switch (f.type) {
     case "string": return `sample-${fieldName}`;
@@ -405,37 +478,43 @@ function sampleOfDescriptorField(
     case "literal": return f.value;
     case "boolean": return true;
     case "enum": return f.values[0];
-    case "array": return [sampleOfDescriptorField(f.items, fieldName, byName, includeOptional)];
+    case "array": return [sampleOfDescriptorField(f.items, fieldName, byName, includeOptional, `${path}[0]`)];
+    case "map": return { key: sampleOfDescriptorField(f.values, fieldName, byName, includeOptional, `${path}.key`) };
     case "geometry": return GEOMETRY_SAMPLES[f.geometry];
     case "object": {
       const dep = byName.get(f.ref);
-      if (dep === undefined) throw new Error(`voSample: nested value object '${f.ref}' has no descriptor`);
-      return sampleOfDescriptor(dep, byName, includeOptional);
+      if (dep === undefined) throw new Error(`voSample: field '${path}' — nested value object '${f.ref}' has no descriptor`);
+      return sampleOfDescriptor(dep, byName, includeOptional, path);
     }
   }
 }
 
-function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueObjectDescriptor>, includeOptional = false): unknown {
+function sampleOfDescriptor(
+  d: ValueObjectDescriptor,
+  byName: Map<string, ValueObjectDescriptor>,
+  includeOptional = false,
+  path = d.name,
+): unknown {
   if (d.geometry !== undefined) return GEOMETRY_SAMPLES[d.geometry];
   if (d.union !== undefined) {
     // FIRST declared arm (keys are sorted — deterministic); `example:` overrides upstream.
     const [key, arm] = Object.entries(d.union)[0]!;
     if ("ref" in arm) {
       const dep = byName.get(arm.ref);
-      if (dep === undefined) throw new Error(`voSample: union arm VO '${arm.ref}' has no descriptor`);
-      return { type: key, value: sampleOfDescriptor(dep, byName) };
+      if (dep === undefined) throw new Error(`voSample: field '${path}' — union arm VO '${arm.ref}' has no descriptor`);
+      return { type: key, value: sampleOfDescriptor(dep, byName, includeOptional, `${path}.value`) };
     }
     const out: Record<string, unknown> = { type: key };
     for (const [k, f] of Object.entries(arm.fields)) {
       if (f.optional === true && !includeOptional) continue;
-      out[k] = sampleOfDescriptorField(f, k, byName, includeOptional);
+      out[k] = sampleOfDescriptorField(f, k, byName, includeOptional, `${path}.${k}`);
     }
     return out;
   }
   const out: Record<string, unknown> = {};
   for (const [k, f] of Object.entries(d.fields ?? {})) {
     if (f.optional === true && !includeOptional) continue; // optional → omitted (mirrors payload synthesis)
-    out[k] = sampleOfDescriptorField(f, k, byName, includeOptional);
+    out[k] = sampleOfDescriptorField(f, k, byName, includeOptional, `${path}.${k}`);
   }
   return out;
 }
@@ -446,12 +525,14 @@ function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueO
  * VOs). Proof synthesis calls this instead of guessing at the raw zod — which is exactly the
  * lane that refused its own sample on constrained shapes (geo min-2 coordinates).
  */
-export function voSample(meta: ValueObjectFieldMeta, opts?: { includeOptional?: boolean }): unknown {
+export function voSample(meta: ValueObjectFieldMeta, opts?: { includeOptional?: boolean; path?: string }): unknown {
   if (meta.example !== undefined) return meta.example;
   const byName = new Map<string, ValueObjectDescriptor>();
   for (const d of meta.dependencies) byName.set(d.name, d);
   byName.set(meta.descriptor.name, meta.descriptor);
-  return sampleOfDescriptor(meta.descriptor, byName, opts?.includeOptional === true);
+  // `path` (when the caller threads the payload-root field path) makes any interior failure name the
+  // FULL path (`georef.controlPoints[0].geoPoint`), not a bare VO name — the exact-field-path contract.
+  return sampleOfDescriptor(meta.descriptor, byName, opts?.includeOptional === true, opts?.path ?? meta.descriptor.name);
 }
 
 function makeValueObject<T>(
@@ -692,6 +773,11 @@ export interface GeoPolygonValue {
   type: "Polygon";
   coordinates: number[][][];
 }
+/** The authored TS shape of a `geo.multiPoint(...)` value (RFC 7946 MultiPoint). */
+export interface GeoMultiPointValue {
+  type: "MultiPoint";
+  coordinates: number[][];
+}
 
 function geoZod(kind: GeometryKind, coordinates: z.ZodTypeAny): z.ZodTypeAny {
   return z.object({ type: z.literal(kind), coordinates });
@@ -739,6 +825,18 @@ export const geo = {
       "Polygon",
     );
   },
+  /** An RFC 7946 **MultiPoint** (an array of positions). Round-trips as typed geometry;
+   *  NOT yet spatial-indexable (the R*Tree is point-only — non-point indexing is future
+   *  kernel work). */
+  multiPoint(name = "GeoMultiPoint"): ValueObject<GeoMultiPointValue> {
+    return makeValueObject<GeoMultiPointValue>(
+      name,
+      geoZod("MultiPoint", z.array(positionZod)) as z.ZodType<GeoMultiPointValue>,
+      { name, geometry: "MultiPoint" },
+      [],
+      "MultiPoint",
+    );
+  },
 };
 
 // ── module-plane collection (composeDomainModule / codegen) ──────────────────────────
@@ -795,7 +893,9 @@ export function collectValueObjectDescriptors(
   const byName = new Map<string, ValueObjectDescriptor>();
   for (const agg of aggregates) {
     for (const field of Object.values(agg.fields)) {
-      const meta = field.valueObject;
+      // A VO can ride a field directly (`VO.field()`) OR as a map's value
+      // (`t.map(VO.field())` → `field.mapValueVo`); collect the descriptor set of both.
+      for (const meta of [field.valueObject, field.mapValueVo]) {
       if (meta === undefined) continue;
       const all = [meta.descriptor, ...meta.dependencies];
       for (const d of all) {
@@ -808,6 +908,7 @@ export function collectValueObjectDescriptors(
         }
         byName.set(d.name, d);
       }
+      }
     }
   }
   return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));

package/src/wire_encode.ts

@@ -77,8 +77,18 @@ export function encodeKernelSchema(agg: AggregateHandle): WireSchema {
   return out;
 }
 
-/** Map an authored op value onto the kernel `Value` shape, given the field kind. */
-function encodeKernelValue(field: Field | undefined, value: unknown): WireValue {
+/** A shape description for a value that failed to encode (diagnostics only). */
+function describeShape(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "anonymous object";
+  return typeof value;
+}
+
+/** Map an authored op value onto the kernel `Value` shape, given the field kind.
+ *  `op` is passed purely for a NAMED diagnostic (aggregate + field + expected VO type) when a value
+ *  can't be lowered — never `field '?'`. */
+function encodeKernelValue(field: Field | undefined, value: unknown, op?: FieldOp): WireValue {
   // An `evidence` field encodes as the FIRST-CLASS kernel `Value::Evidence` (NOT a JSON
   // string): the authored {hash, mediaType, byteLength, storageClass} maps to the
   // kernel's snake_case serde shape + the `Git`/`External` unit-variant. Checked BEFORE
@@ -100,15 +110,49 @@ function encodeKernelValue(field: Field | undefined, value: unknown): WireValue
   // (the kernel canonicalises it at the boundary). This is the new-era encoding; a package compiled
   // before this change froze the old `{ Str: JSON.stringify(value) }` lump and replays unchanged.
   if (field?.kind === "json") return { Json: value };
+  // A `t.map(t.json())` / `t.map(VO.field())` ENTRY value is a json leaf too. Its wire DRIVER is
+  // `MapOf(Lww)` (whose leaves are ordinary kernel `Value`s), so a json-valued entry lowers to the SAME
+  // first-class `Value::Json` a top-level json field does — the map entry round-trips as its OBJECT, not a
+  // JSON-shaped `Str`. Checked BEFORE the scalar fallthroughs. SAME-ERA treatment as the top-level json
+  // field (the new-era compiler emits Json unconditionally; an older bundle froze its own lump). A
+  // string/int-valued map (`mapValueKind !== "json"`) is UNTOUCHED here → its entries stay Str/Int,
+  // byte-identical. `mapValueKind === "json"` is set for BOTH `t.map(t.json())` and a VO-valued map
+  // (`t.map(VO.field())`, whose inner field is json-kind).
+  // ERA GUARD (2026-07-04 regression fix): ONLY structured values (object/array) take the Json
+  // lane. A STRING entry into a json-kind map stays Value::Str — that is the historical wire
+  // shape for every pre-stringified leaf, most critically writeTuple's relation `subjects`
+  // entries, which the kernel's authz fold parses as Str. Routing strings to Json broke
+  // relation seating repo-wide (warrant_flip/va_core/relation-bootstrap all red). Objects were
+  // previously a REFUSAL here, so giving them the Json lane changes only the case that threw.
+  if (field?.kind === "map" && field.mapValueKind === "json" && typeof value === "object" && value !== null) {
+    return { Json: value };
+  }
   // For scalar Set/SetEntry the kernel expects Str or Int. Maps store leaves;
   // a map's entry value is a leaf scalar.
   if (typeof value === "number" && Number.isInteger(value)) return { Int: value };
   if (typeof value === "string") return { Str: value };
   if (typeof value === "boolean") return { Str: String(value) };
   // Enum values are strings; refs are id strings — both handled above.
+  // NAMED diagnostic (never `field '?'`): identify the aggregate + field + the shape we got, and — when the
+  // field metadata was UNAVAILABLE (a sibling write whose target schema didn't reach the encoder) — say so,
+  // since that is the classic cause of a VO/json object arriving at the scalar fallthrough.
+  const aggName = op?.aggregateType ?? op?.aggregateId ?? "?";
+  const fieldName = op?.field ?? "?";
+  if (field === undefined) {
+    throw new Error(
+      `sibling write ${aggName}.${fieldName} got ${describeShape(value)} but its field metadata was ` +
+        `unavailable, so it could not be encoded — declare the write against the target aggregate's handle ` +
+        `(instance/existing/ensure(TargetAgg, id)) so the field kind is known.`,
+    );
+  }
+  // Name the expected VO: a top-level VO field carries it on `valueObject`, a VO-valued MAP entry on
+  // `mapValueVo` (the inner value's VO metadata) — so a bad `t.map(VO.field())` entry names its VO too.
+  const expected = field.valueObject?.name ?? field.mapValueVo?.name;
+  const kindLabel = field.kind === "map" ? `map (${field.mapValueKind ?? "?"}-valued)` : field.kind;
   throw new Error(
-    `Cannot encode value ${JSON.stringify(value)} for field '${field?.kind ?? "?"}': ` +
-      `kernel scalars are Str | Int only.`,
+    `${aggName}.${fieldName} is a '${kindLabel}' field${expected ? ` (value object ${expected})` : ""}, ` +
+      `but got ${describeShape(value)} (${JSON.stringify(value)}) — kernel scalars are Str | Int only. ` +
+      `A structured value needs a json/value-object field; a set/map needs its additive write.`,
   );
 }
 
@@ -123,7 +167,7 @@ function encodeKernelFieldOp(op: FieldOp, field: Field | undefined): WireFieldOp
       wireOp =
         driver === "LastPosition"
           ? { SetPosition: String(op.value) }
-          : { Set: encodeKernelValue(field, op.value) };
+          : { Set: encodeKernelValue(field, op.value, op) };
       break;
     case "addToSet":
       // On a remove-wins set the add grows the 2-phase set's `adds`; on AddWins it is the plain union.
@@ -149,7 +193,7 @@ function encodeKernelFieldOp(op: FieldOp, field: Field | undefined): WireFieldOp
       break;
     case "setEntry":
       wireOp = {
-        SetEntry: { key: op.entryKey!, value: encodeKernelValue(field, op.value) },
+        SetEntry: { key: op.entryKey!, value: encodeKernelValue(field, op.value, op) },
       };
       break;
   }
@@ -294,14 +338,18 @@ export function executeDirectiveToIntent<P>(
       explicitMarker.set(op.aggregateId, encoded);
     }
     // Field kinds are known for ops targeting the directive's own aggregate — by
-    // TYPE for a bound op (`aggregateType`), else by id for an unbound op. Ops
-    // fanning out to siblings encode by value-kind (the `json` path needs the kind).
+    // TYPE for a bound op (`aggregateType`), else by id for an unbound op.
     const isOwnTarget =
       op.aggregateType !== undefined ? op.aggregateType === agg.id : op.aggregateId === agg.id;
     // A bucket is the own target if ANY of its ops target the directive's own aggregate.
     if (isOwnTarget) ownTarget.set(op.aggregateId, true);
     else if (!ownTarget.has(op.aggregateId)) ownTarget.set(op.aggregateId, false);
-    const field = isOwnTarget ? fieldsOf[op.field] : undefined;
+    // Resolve the field's schema from the OP'S OWN TARGET aggregate, not the dispatch primary: a fanned-out
+    // sibling op carries its target's Field (`op.targetField`, captured at op-construction where the handle
+    // knew its schema). For an own-target op `op.targetField` IS `fieldsOf[op.field]` (same Field object), so
+    // this is byte-identical for every primary write; it only supplies metadata that was previously LOST on a
+    // sibling write (a VO/json value that used to throw, a RemoveWins/LastPosition driver that used to mis-lower).
+    const field = op.targetField ?? (isOwnTarget ? fieldsOf[op.field] : undefined);
     bucket.push(encodeKernelFieldOp(op, field));
   }