@githolon/dsl 0.53.0 → 0.54.1

package/src/authoring.ts

@@ -24,8 +24,8 @@
  * So a `.plan` that fluently authors and `return []`s still emits its events — the recorded ops are real.
  */
 import type { AggregateHandle } from "./aggregate.js";
-import type { Field } from "./fields.js";
-import type { FieldOp, PlannedOp, PlannedEventMarker } from "./ops.js";
+import type { Field, FieldValue } from "./fields.js";
+import type { AcceptedValue, FieldOp, PlannedOp, PlannedEventMarker } from "./ops.js";
 import { endorsementOf } from "./principal_evidence.js";
 import { __qualifyAggregateType } from "./framework/relations.js";
 import { __registerEnsure } from "./attested_core.js";
@@ -52,14 +52,53 @@ function mint(typeTag: string): string {
   return (globalThis as unknown as { nomos: NomosMint }).nomos.mint(typeTag);
 }
 
-/** A reference to an aggregate the dev HOLDS — minted-new (`create`) or bound-to-existing (`existing`). */
-export interface AggregateRef {
+/**
+ * `true` iff `F` is the WIDE, un-inferred field map (`Record<string, Field>`) — i.e. the ref
+ * came from an untyped handle. Used to DEGRADE the typed member signatures back to today's
+ * permissive `string`/`unknown` shape so every pre-existing plain-string call still compiles
+ * (the backward-compat contract: a typed handle catches typos, an untyped one is unchanged).
+ */
+type UntypedFields<F> = string extends keyof F ? true : false;
+
+/** Map-kind field keys of `F` (value type is a `Record<string, …>`) — the keys `.setEntry` accepts. */
+type MapKeyOf<F extends Record<string, Field>> = {
+  [K in keyof F]: FieldValue<F[K]> extends Record<string, unknown> ? K : never;
+}[keyof F] &
+  string;
+/** The per-entry VALUE type of a map field `F[K]`. */
+type MapValueOf<Fld> = FieldValue<Fld> extends Record<string, infer V> ? V : unknown;
+
+/**
+ * A reference to an aggregate the dev HOLDS — minted-new (`create`) or bound-to-existing (`existing`).
+ *
+ * TYPED BY THE FIELD MAP (#29): when the source handle carries a concrete field map `F`
+ * (the usual `create(EstateDrawing)`), `.set("transform", value)` is checked by tsc — the
+ * field NAME must be a key of `F`, the VALUE type must match the field's declared kind, and a
+ * `t.set(...)` field REJECTS `.set` at the type level (the type-level twin of the runtime
+ * AddWins refusal — use `.add(...)`). An UNTYPED handle (`AggregateHandle` with the wide
+ * `Record<string, Field>`) degrades to the historical permissive `string`/`unknown` signature,
+ * so every plain-string authoring site compiles unchanged.
+ */
+export interface AggregateRef<F extends Record<string, Field> = Record<string, Field>> {
   readonly __type: string;
   readonly __id: string;
-  /** Set a scalar field (Lww). */
-  set(field: string, value: unknown): this;
-  /** Set one entry of a map field (per-key Lww). */
-  setEntry(field: string, key: string, value: unknown): this;
+  /** Set a scalar/map-whole/ref field (Lww). Field name + value type are checked against `F`;
+   *  a `t.set(...)` field is refused (use `.add`). */
+  set<K extends keyof F & string>(
+    field: UntypedFields<F> extends true
+      ? string
+      : K &
+          (F[K] extends { kind: "set" }
+            ? `TYPE ERROR: '${K}' is a set field — .set would OVERWRITE the merge; use .add("${K}", value)`
+            : K),
+    value: UntypedFields<F> extends true ? unknown : AcceptedValue<F[K]>,
+  ): this;
+  /** Set one entry of a map field (per-key Lww). On a typed handle the field must be a map field. */
+  setEntry<K extends MapKeyOf<F>>(
+    field: UntypedFields<F> extends true ? string : K,
+    key: string,
+    value: UntypedFields<F> extends true ? unknown : MapValueOf<F[K]>,
+  ): this;
   /** Add to a collection: a `t.hasMany` relation → writes the child's back-ref; a `t.set` → AddToSet on self. */
   add(field: string, value: unknown): this;
   /** Relate to another aggregate by reference (writes the ref field on THIS aggregate). */
@@ -87,7 +126,18 @@ class Ref implements AggregateRef {
     const resolved: Partial<FieldOp> = endorsement
       ? { ...extra, value: endorsement.principal, endorsement: { facet: endorsement.facet, reason: endorsement.reason } }
       : extra;
-    const op: FieldOp = { aggregateId: this.__id, aggregateType: this.__type, field, kind, ...resolved };
+    // Capture the TARGET aggregate's Field so a fanned-out sibling write keeps its schema at wire encode
+    // (see FieldOp.targetField). The handle KNOWS its fields — thread that, don't re-resolve from the
+    // directive's primary aggregate. Absent field ⇒ no key (byte-identical to before).
+    const targetField = (this.handle.fields as Record<string, Field>)[field];
+    const op: FieldOp = {
+      aggregateId: this.__id,
+      aggregateType: this.__type,
+      ...(targetField ? { targetField } : {}),
+      field,
+      kind,
+      ...resolved,
+    };
     sink.push(this.marker ? { ...op, marker: this.marker } : op);
   }
   set(field: string, value: unknown): this {
@@ -121,16 +171,23 @@ class Ref implements AggregateRef {
   }
 }
 
-/** Ask Nomos to CREATE a new aggregate of the handle's type → a fluent reference (id minted, no choice). */
-export function create(agg: AggregateHandle): AggregateRef {
+/** Ask Nomos to CREATE a new aggregate of the handle's type → a fluent reference (id minted, no choice).
+ *  The returned ref is TYPED by the handle's field map `F` (see {@link AggregateRef}). */
+export function create<Id extends string, F extends Record<string, Field>>(
+  agg: AggregateHandle<Id, F>,
+): AggregateRef<F> {
   // READ-PROJECTION NAMESPACING: mint under the QUALIFIED type tag — the kernel's id-mint gate
   // verifies a Create's id was minted for EXACTLY the declared (qualified) `__type`.
-  return new Ref(agg, mint(__qualifyAggregateType(agg.id)), "creates");
+  return new Ref(agg, mint(__qualifyAggregateType(agg.id)), "creates") as unknown as AggregateRef<F>;
 }
 
-/** A reference to an EXISTING aggregate the dev already holds an id for (e.g. from the payload / a read). */
-export function existing(agg: AggregateHandle, id: string): AggregateRef {
-  return new Ref(agg, id, null);
+/** A reference to an EXISTING aggregate the dev already holds an id for (e.g. from the payload / a read).
+ *  TYPED by the handle's field map `F`. */
+export function existing<Id extends string, F extends Record<string, Field>>(
+  agg: AggregateHandle<Id, F>,
+  id: string,
+): AggregateRef<F> {
+  return new Ref(agg, id, null) as unknown as AggregateRef<F>;
 }
 
 /**
@@ -139,8 +196,11 @@ export function existing(agg: AggregateHandle, id: string): AggregateRef {
  * carries ONE referential marker for its primary aggregate; the SECOND+ aggregate it touches declares its
  * own birth through this (the fluent sibling of the typed `withMarker(set(instance(Agg, id), …), "ensures")`).
  */
-export function ensure(agg: AggregateHandle, id: string): AggregateRef {
-  return new Ref(agg, id, "ensures");
+export function ensure<Id extends string, F extends Record<string, Field>>(
+  agg: AggregateHandle<Id, F>,
+  id: string,
+): AggregateRef<F> {
+  return new Ref(agg, id, "ensures") as unknown as AggregateRef<F>;
 }
 
 // Register ensure() for the foreign read lane (attested reads — see attested_core.ts; the

package/src/codegen_dart.ts

@@ -29,7 +29,7 @@
  * generated, so they stay reproducible from the domain definitions.
  */
 import { z } from "zod";
-import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
+import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, brandedIdMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
@@ -257,6 +257,11 @@ function introspectField(
       if (idAgg !== undefined) {
         return { name, dartType: typedIdClassForAggregateType(idAgg), toJson: "wrapped" };
       }
+      // brandedId("SiteId"): a standalone nominal string → the generated extension type.
+      const brand = brandedIdMetaOf(zt);
+      if (brand !== undefined) {
+        return { name, dartType: brand, toJson: "wrapped" };
+      }
       return { name, dartType: "String", toJson: "scalar" };
     }
     case "ZodNumber":
@@ -384,6 +389,12 @@ interface AggFieldSpec {
    * `undefined` for a non-map field.
    */
   mapValueKind?: FieldKind;
+  /**
+   * For a `t.map(VO.field())` field: the inner VO's generated Dart class name. The map
+   * surfaces as `Map<String, VoClass>` and decodes each entry via `VoClass.fromProjected`
+   * (per-entry typed decode). `undefined` for a map of scalars / plain json.
+   */
+  mapValueVoClass?: string;
   /**
    * For a `json`-kind field lowered from a NAMED VALUE OBJECT (`ValueObject.field()`):
    * the generated Dart class name. The field decodes via `readJsonObject…` +
@@ -697,13 +708,20 @@ function aggFieldSpec(
       // every other map keeps the flat-string `Map<String, String>`. The wire driver is
       // identical for both, so this is a frontend-only type choice (no hash change).
       const jsonValued = field.mapValueKind === "json";
+      const mapVoClass = field.mapValueVo?.name;
       return {
         name,
         wireName,
         kind: field.kind,
-        dartType: jsonValued ? "Map<String, Object?>" : "Map<String, String>",
+        dartType:
+          mapVoClass !== undefined
+            ? `Map<String, ${mapVoClass}>`
+            : jsonValued
+              ? "Map<String, Object?>"
+              : "Map<String, String>",
         optional: false,
         ...(field.mapValueKind !== undefined ? { mapValueKind: field.mapValueKind } : {}),
+        ...(mapVoClass !== undefined ? { mapValueVoClass: mapVoClass } : {}),
       };
     }
     case "hasMany":
@@ -1237,6 +1255,15 @@ const geometryCoordsDart: Record<string, string> = {
   Point: "List<double>",
   LineString: "List<List<double>>",
   Polygon: "List<List<List<double>>>",
+  MultiPoint: "List<List<double>>",
+};
+
+/** The `geo.*` factory name for a geometry kind (used in generated doc comments). */
+const geometryFactoryNameDart: Record<string, string> = {
+  Point: "point",
+  LineString: "lineString",
+  Polygon: "polygon",
+  MultiPoint: "multiPoint",
 };
 
 /**
@@ -1296,6 +1323,7 @@ function voEnumFields(d: ValueObjectDescriptor): { fieldName: string; values: re
   const walk = (fieldName: string, f: ValueObjectFieldDescriptor, owner?: string): void => {
     if (f.type === "enum") out.push({ fieldName, values: f.values, ...(owner !== undefined ? { owner } : {}) });
     else if (f.type === "array") walk(fieldName, f.items, owner);
+    else if (f.type === "map") walk(fieldName, f.values, owner);
   };
   for (const [fieldName, f] of Object.entries(d.fields ?? {})) walk(fieldName, f);
   // union arms: enums are owned by the ARM CLASS (`<Union><ArmCap>`) so two arms' same-named
@@ -1318,7 +1346,7 @@ function unionArmClassName(unionName: string, armKey: string): string {
 function dartTypeOfVoField(f: ValueObjectFieldDescriptor, voName: string, fieldName: string): string {
   switch (f.type) {
     case "string":
-      return "String";
+      return f.brand ?? "String"; // a brandedId(...) → the generated extension-type wrapper
     case "number":
       // a UNIT-tagged number is the generated zero-cost extension type; `.int()` is Dart int.
       if (f.unit !== undefined) return f.unit;
@@ -1332,6 +1360,8 @@ function dartTypeOfVoField(f: ValueObjectFieldDescriptor, voName: string, fieldN
       return "String"; // surfaced as a constant getter, not a ctor param
     case "array":
       return `List<${dartTypeOfVoField(f.items, voName, fieldName)}>`;
+    case "map":
+      return `Map<String, ${dartTypeOfVoField(f.values, voName, fieldName)}>`;
     case "object":
     case "geometry":
       return f.ref; // the named VO class (emitted alongside / imported)
@@ -1349,7 +1379,7 @@ function voFromExpr(
 ): string {
   switch (f.type) {
     case "string":
-      return `${expr} as String`;
+      return f.brand !== undefined ? `${f.brand}(${expr} as String)` : `${expr} as String`;
     case "enum":
       // TOLERANT typed decode — an unknown wire value becomes the sentinel case.
       return `${voEnumName(voName, fieldName)}.fromWire(${expr} as String)`;
@@ -1360,6 +1390,10 @@ function voFromExpr(
       return `${expr} as String`;
     case "boolean":
       return `${expr} as bool`;
+    case "map": {
+      const kv = `k${depth}`, vv = `v${depth}`;
+      return `(${expr} as Map).map((${kv}, ${vv}) => MapEntry(${kv} as String, ${voFromExpr(f.values, vv, voName, fieldName, depth + 1)}))`;
+    }
     case "array": {
       const v = `e${depth}`;
       return `(${expr} as List).map((${v}) => ${voFromExpr(f.items, v, voName, fieldName, depth + 1)}).toList()`;
@@ -1376,11 +1410,16 @@ function voToJsonExpr(f: ValueObjectFieldDescriptor, expr: string, depth = 0): s
     case "number":
       return f.unit !== undefined ? `${expr}.value` : expr;
     case "string":
+      return f.brand !== undefined ? `${expr}.value` : expr; // a brandedId extension type → its wire string
     case "boolean":
     case "literal":
       return expr;
     case "enum":
       return `${expr}.wire`; // the exact wire string the law's zod enum validates
+    case "map": {
+      const inner = voToJsonExpr(f.values, `v${depth}`, depth + 1);
+      return inner === `v${depth}` ? expr : `${expr}.map((k${depth}, v${depth}) => MapEntry(k${depth}, ${inner}))`;
+    }
     case "array": {
       const inner = voToJsonExpr(f.items, `e${depth}`, depth + 1);
       return inner === `e${depth}` ? expr : `${expr}.map((e${depth}) => ${inner}).toList()`;
@@ -1656,6 +1695,7 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
       Point: `(m['coordinates']! as List).map((e0) => (e0 as num).toDouble()).toList()`,
       LineString: `(m['coordinates']! as List).map((e0) => (e0 as List).map((e1) => (e1 as num).toDouble()).toList()).toList()`,
       Polygon: `(m['coordinates']! as List).map((e0) => (e0 as List).map((e1) => (e1 as List).map((e2) => (e2 as num).toDouble()).toList()).toList()).toList()`,
+      MultiPoint: `(m['coordinates']! as List).map((e0) => (e0 as List).map((e1) => (e1 as num).toDouble()).toList()).toList()`,
     };
     return [
       `/// RFC 7946 ${d.geometry} — a \`geo.*\` value object ('${d.name}'). Positions are`,
@@ -1767,9 +1807,11 @@ function collectionDefaultParam(s: AggFieldSpec): string {
     case "set":
       return `this.${s.name} = const <String>{},`;
     case "map":
-      return isJsonValuedMap(s)
-        ? `this.${s.name} = const <String, Object?>{},`
-        : `this.${s.name} = const <String, String>{},`;
+      return s.mapValueVoClass !== undefined
+        ? `this.${s.name} = const <String, ${s.mapValueVoClass}>{},`
+        : isJsonValuedMap(s)
+          ? `this.${s.name} = const <String, Object?>{},`
+          : `this.${s.name} = const <String, String>{},`;
     default:
       // An optional scalar — nullable, no default needed (defaults to null).
       return `this.${s.name},`;
@@ -1860,6 +1902,10 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
       // A `json`-valued map decodes each entry value back to its OBJECT (so a
       // value-object map — e.g. `customFields`, each entry the canonical
       // `CustomField.toJson()` — round-trips losslessly); a string-valued map stays flat.
+      if (s.mapValueVoClass !== undefined) {
+        // A map of a NAMED value object: decode each entry to its typed VO class.
+        return `readJsonMapOrEmpty(data, '${aggregate}', '${s.wireName}').map((k, v) => MapEntry(k, ${s.mapValueVoClass}.fromProjected((v! as Map).cast<String, Object?>())))`;
+      }
       return isJsonValuedMap(s)
         ? `readJsonMapOrEmpty(data, '${aggregate}', '${s.wireName}')`
         : `readStrMapOrEmpty(data, '${aggregate}', '${s.wireName}')`;
@@ -1917,7 +1963,11 @@ function readModelDartType(s: AggFieldSpec): string {
     case "set":
       return "Set<String>";
     case "map":
-      return isJsonValuedMap(s) ? "Map<String, Object?>" : "Map<String, String>";
+      return s.mapValueVoClass !== undefined
+        ? `Map<String, ${s.mapValueVoClass}>`
+        : isJsonValuedMap(s)
+          ? "Map<String, Object?>"
+          : "Map<String, String>";
   }
 }
 
@@ -1929,9 +1979,11 @@ function readModelDefaultParam(s: AggFieldSpec): string {
     case "set":
       return `this.${s.name} = const <String>{},`;
     case "map":
-      return isJsonValuedMap(s)
-        ? `this.${s.name} = const <String, Object?>{},`
-        : `this.${s.name} = const <String, String>{},`;
+      return s.mapValueVoClass !== undefined
+        ? `this.${s.name} = const <String, ${s.mapValueVoClass}>{},`
+        : isJsonValuedMap(s)
+          ? `this.${s.name} = const <String, Object?>{},`
+          : `this.${s.name} = const <String, String>{},`;
     default:
       // An optional scalar, an optional OBJECT json leaf (nullable `Map`), OR a
       // permissive plain-json leaf (already-nullable `Object?`) — nullable, defaults to
@@ -2006,6 +2058,10 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
     case "set":
       return `readSetOrEmpty(data, '${aggregate}', '${s.wireName}')`;
     case "map":
+      if (s.mapValueVoClass !== undefined) {
+        // A map of a NAMED value object: decode each entry to its typed VO class.
+        return `readJsonMapOrEmpty(data, '${aggregate}', '${s.wireName}').map((k, v) => MapEntry(k, ${s.mapValueVoClass}.fromProjected((v! as Map).cast<String, Object?>())))`;
+      }
       return isJsonValuedMap(s)
         ? `readJsonMapOrEmpty(data, '${aggregate}', '${s.wireName}')`
         : `readStrMapOrEmpty(data, '${aggregate}', '${s.wireName}')`;
@@ -3267,9 +3323,14 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   // in local VO descriptors OR directive payloads gets ONE zero-cost wrapper. Opaque by design —
   // no generated arithmetic/conversions (a physics library is not a type system).
   const unitNames = new Set<string>();
+  // brandedId(...) names → their own zero-cost String extension type (the standalone twin of
+  // the aggregate typed-id classes). Collected from VO descriptors AND directive payloads.
+  const brandNames = new Set<string>();
   const walkUnitField = (f: ValueObjectFieldDescriptor): void => {
     if (f.type === "number" && f.unit !== undefined) unitNames.add(f.unit);
+    else if (f.type === "string" && f.brand !== undefined) brandNames.add(f.brand);
     else if (f.type === "array") walkUnitField(f.items);
+    else if (f.type === "map") walkUnitField(f.values);
   };
   for (const d of localValueObjects) {
     for (const f of Object.values(d.fields ?? {})) walkUnitField(f);
@@ -3282,7 +3343,22 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     if (schema && typeof schema === "object" && zodTypeName(schema as z.ZodTypeAny) === "ZodObject") {
       try {
         for (const spec of introspectPayload(schema as z.ZodTypeAny, new Map())) {
-          if (spec.toJson === "wrapped" && !spec.dartType.endsWith("Id")) unitNames.add(spec.dartType);
+          // A spec whose brand a VO descriptor already registered is a brandedId, not a unit —
+          // and neither is an aggregate typed-id (`<Agg>Id`, emitted by the id machinery).
+          if (spec.toJson === "wrapped" && !spec.dartType.endsWith("Id") && !brandNames.has(spec.dartType)) {
+            unitNames.add(spec.dartType);
+          }
+        }
+        // Directly-scanned brandedId payload fields (incl. `<Brand>` ending in "Id", which the
+        // unit filter skips) — the payload-only lane still emits their extension type.
+        const rawShape = (zodDef(schema as z.ZodTypeAny) as { shape?: Record<string, z.ZodTypeAny> | (() => Record<string, z.ZodTypeAny>) }).shape;
+        const shp = typeof rawShape === "function" ? rawShape() : rawShape ?? {};
+        for (let zt of Object.values(shp)) {
+          for (let hops = 0; hops < 8 && (zodTypeName(zt) === "ZodOptional" || zodTypeName(zt) === "ZodDefault" || zodTypeName(zt) === "ZodArray"); hops++) {
+            zt = zodTypeName(zt) === "ZodArray" ? zodArrayElement(zt) : zodInnerType(zt);
+          }
+          const b = brandedIdMetaOf(zt);
+          if (b !== undefined) brandNames.add(b);
         }
       } catch { /* an unsupported payload shape is reported by the payload emitter, not here */ }
     }
@@ -3293,8 +3369,14 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     `/// error. Opaque tag only — no arithmetic/conversions are generated.`,
     `extension type const ${u}(double value) {}`,
   ].join("\n")).join("\n\n");
+  const brandBlock = [...brandNames].sort().map((b) => [
+    `/// BRANDED ID \`${b}\` — a ZERO-COST nominal String (Dart extension type; \`brandedId("${b}")\`):`,
+    `/// passing a bare String (or another brand) where [${b}] is required is a COMPILE error.`,
+    `extension type const ${b}(String value) {}`,
+  ].join("\n")).join("\n\n");
   const voBlock = [
     ...(unitBlock !== "" ? [unitBlock] : []),
+    ...(brandBlock !== "" ? [brandBlock] : []),
     ...(localValueObjects.length > 0
       ? [
           emitVoHelpers(),

package/src/codegen_dart_client.ts

@@ -360,7 +360,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `// client file gives an app the whole typed surface.`,
     `export '${mod.name}.dart';`,
     ...(opts.frameworkImportUri !== undefined ? [`export '${opts.frameworkImportUri}';`] : []),
-    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion${encPresent ? ", NomosScopeKey, NomosKeyStore, EncryptionKeyUnavailable, WrappedKeyStore, NomosEncryption, NomosEpochResult, EncryptionMemberKeyMissing, EncryptionRosterMismatch" : ""};`,
+    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion, NomosCompat, NomosCompatMember${encPresent ? ", NomosScopeKey, NomosKeyStore, EncryptionKeyUnavailable, WrappedKeyStore, NomosEncryption, NomosEpochResult, EncryptionMemberKeyMissing, EncryptionRosterMismatch" : ""};`,
     ``,
     `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,
     `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
@@ -440,6 +440,23 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
           `  /// the workspace's installed law changes (a synced install/upgrade from another peer).`,
           `  Stream<Map<String, Object?>> watchCompatibility() => bridge.watchCompatibility(_requirement);`,
           ``,
+          ...(opts.compat !== undefined
+            ? [
+                `  /// THE COMPAT SUPERPOWER (#72b): compute the LIVE per-member verdict for THIS client against the`,
+                `  /// workspace's on-ledger offer + arm the pre-call refusal. Await it after connect so a KNOWN-`,
+                `  /// incompatible directive throws [LawMismatchError] CLIENT-SIDE at write time (never a server 422).`,
+                `  Future<NomosCompat?> checkCompat() => bridge.checkCompat(`,
+                `      (jsonDecode(${compatConstNameDart(mod.name)}) as Map).cast<String, Object?>(), _requirement);`,
+                ``,
+                `  /// THE FEATURE FLAG (dark-launch): true iff [member] exists on the offer AND is compatible — ship`,
+                `  /// UI with a member dark, deploy the law, it lights up. Await [checkCompat] once first to arm it.`,
+                `  Future<bool> has(String member) => bridge.compatHas(member);`,
+                ``,
+                `  /// COMPAT SUPERPOWER live events: emits the fresh verdict when a synced law change moves the offer.`,
+                `  Stream<NomosCompat> get onLawChanged => bridge.onLawChanged;`,
+                ``,
+              ]
+            : []),
         ]
       : []),
     ...methods,

package/src/codegen_openapi.ts

@@ -170,7 +170,7 @@ export function generateOpenApiFragment(
   }
   for (const sp of module.spatials ?? []) {
     getRead(sp.id, `spatial: ${sp.of} by ${sp.on} bbox`, { kind: "spatial", spatialId: sp.id, on: sp.on }, [
-      { name: "bbox", in: "query", required: true, schema: { type: "string" }, description: "minLng,minLat,maxLng,maxLat" },
+      { name: "bbox", in: "query", required: true, schema: { type: "string" }, description: "minX,minY,maxX,maxY" },
     ]);
   }
 

package/src/codegen_proof.ts

@@ -97,19 +97,68 @@ function sampleString(zt: z.ZodTypeAny, field: string): string {
   return readable;
 }
 
-/** One sample value for one zod shape. NO FALLBACK: an unhandled shape throws, naming its remedy. */
-function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string, voIncludeOptional = false): unknown {
-  // VALUE OBJECTS FIRST (vo_authoring_end_to_end.md slice C): a declared VO carries its own
-  // lawful sample (the author's validated `example`, the blessed geometry sample, or per-field
-  // descriptor synthesis) — the raw-zod walk below cannot see constraints like geo's min-2
-  // coordinates and would synthesize a value the law itself refuses.
+// Candidate numbers probed against a field's own schema (in a sensible order) so a `.min()/.max()/
+// .int()/.positive()` constraint is respected — the number sibling of SUBJECT_CANDIDATES. `1` first
+// keeps the guestbook golden output stable; the rest cover common bounds (lat/lng, non-negative, etc.).
+const NUMBER_CANDIDATES: readonly number[] = [1, 0, -1, 2, 10, 100, 0.5, -90, 90, 180, -180, 1000000];
+function sampleNumber(zt: z.ZodTypeAny): number {
+  for (const cand of NUMBER_CANDIDATES) if (zt.safeParse(cand).success) return cand;
+  return 1; // no candidate fits an exotic bound — the whole-payload safeParse / VO validate names the field
+}
+
+/** The leaf identifier of a full path (`a.b[0].c` → `c`) — the readable `sample-<leaf>` string base. */
+function leafOfPath(path: string): string {
+  const m = path.match(/([A-Za-z0-9_$]+)(?:\[\d+\])*$/);
+  return m ? m[1]! : path;
+}
+
+/** Append zod-issue path segments (numeric → `[i]`, string → `.name`) onto a base path. */
+function joinIssuePath(base: string, segs: readonly PropertyKey[]): string {
+  let out = base;
+  for (const s of segs) out += typeof s === "number" ? `[${s}]` : out.length ? `.${String(s)}` : String(s);
+  return out;
+}
+
+/**
+ * One sample value for one zod shape, threading the FULL PATH from the payload root so any failure
+ * names the exact field (`controlPoints[0].geoPoint.latitude`, never a bare leaf or "field ?"). NO
+ * FALLBACK: an unhandled shape throws, naming the path and the remedy.
+ */
+function sampleOfZod(zt: z.ZodTypeAny, path: string, where: string, voIncludeOptional = false): unknown {
+  // VALUE OBJECTS FIRST (vo_authoring_end_to_end.md slice C): a declared VO carries its own lawful
+  // sample (the author's validated `example`, the blessed geometry sample, or per-field descriptor
+  // synthesis, recursing through nested VOs / arrays-of-VOs / unions). The raw-zod walk below cannot
+  // see interior constraints (geo's min-2 coordinates, a `.min()` on a subfield), so after building the
+  // descriptor-shaped sample we RE-VALIDATE it against the VO's OWN zod: a violation the descriptor
+  // couldn't capture is reported at its EXACT interior path with the escape hatch (declare an example).
   const vo = voMetaOf(zt);
-  if (vo !== undefined) return voSample(vo, { includeOptional: voIncludeOptional });
+  if (vo !== undefined) {
+    const sample = voSample(vo, { includeOptional: voIncludeOptional, path });
+    // Re-validate against a REAL zod: `zt` is either a genuine ZodType (has safeParse) or the VO HANDLE
+    // (a first-class schema whose validator lives on `.zod`). Skip only if neither is callable.
+    const validator: z.ZodTypeAny | undefined =
+      typeof (zt as { safeParse?: unknown }).safeParse === "function"
+        ? zt
+        : typeof ((zt as { zod?: { safeParse?: unknown } }).zod?.safeParse) === "function"
+          ? (zt as unknown as { zod: z.ZodTypeAny }).zod
+          : undefined;
+    if (vo.example === undefined && validator !== undefined) {
+      const parsed = validator.safeParse(sample);
+      if (!parsed.success) {
+        const iss = parsed.error.issues[0];
+        const at = joinIssuePath(path, iss?.path ?? []);
+        throw new Error(
+          `codegen-proof: ${where} — field '${at}': the synthesized sample violates value object '${vo.name}''s schema (${iss?.message ?? "invalid"}) — the descriptor cannot see this constraint, so declare a lawful \`example\` on valueObject("${vo.name}", …, { example: … }) and proof synthesis will use it instead of guessing the interior`,
+        );
+      }
+    }
+    return sample;
+  }
   switch (zodKind(zt)) {
     case "string":
-      return sampleString(zt, field);
+      return sampleString(zt, leafOfPath(path));
     case "number":
-      return 1;
+      return sampleNumber(zt);
     case "boolean":
       return true;
     case "enum":
@@ -120,14 +169,17 @@ function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string, voIncludeOp
     }
     case "array": {
       const el = zodArrayElement(zt);
-      return zodKind(el) === "string" ? ["sample-a"] : [sampleOfZod(el, field, where, voIncludeOptional)];
+      // A one-element array satisfies `.min(1)` coverage; a string element keeps the readable
+      // `sample-a` (constraint-probed) so golden outputs stay stable.
+      if (zodKind(el) === "string") return [sampleString(el, "a")];
+      return [sampleOfZod(el, `${path}[0]`, where, voIncludeOptional)];
     }
     case "object": {
       const out: Record<string, unknown> = {};
       for (const [name, raw] of Object.entries(zodObjectShape(zt))) {
         const k = zodKind(raw as z.ZodTypeAny);
         if (k === "optional" || k === "default") continue; // optional → omit
-        out[name] = sampleOfZod(raw as z.ZodTypeAny, name, where, voIncludeOptional);
+        out[name] = sampleOfZod(raw as z.ZodTypeAny, joinIssuePath(path, [name]), where, voIncludeOptional);
       }
       return out;
     }
@@ -136,15 +188,15 @@ function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string, voIncludeOp
     case "nullable":
     case "optional":
     case "default":
-      return sampleOfZod(zodDef(zt).innerType!, field, where, voIncludeOptional);
+      return sampleOfZod(zodDef(zt).innerType!, path, where, voIncludeOptional);
     case "union": {
       const first = zodDef(zt).options?.[0];
-      if (first !== undefined) return sampleOfZod(first, field, where, voIncludeOptional);
-      throw new Error(`codegen-proof: empty union at field '${field}' of ${where}`);
+      if (first !== undefined) return sampleOfZod(first, path, where, voIncludeOptional);
+      throw new Error(`codegen-proof: ${where} — field '${path}': an empty union has no arm to sample`);
     }
     default:
       throw new Error(
-        `codegen-proof: cannot synthesize a sample for zod shape '${zodKind(zt)}' (field '${field}' of ${where}) — reshape the payload to a sampleable type, or prove that directive by hand in test/e2e.mts`,
+        `codegen-proof: ${where} — field '${path}': cannot synthesize a sample for zod shape '${zodKind(zt)}' — reshape it to a sampleable type (string/number/boolean/enum/array/object/nested valueObject), or prove that directive by hand in test/e2e.mts`,
       );
   }
 }
@@ -166,7 +218,7 @@ export function synthesizePayload(schema: z.ZodTypeAny, where: string, opts?: {
     const k = zodKind(f);
     if (k === "optional" || k === "default") continue; // optional → omit
     if (stamped.has(name)) continue; // `…At` → omit; the client stamps it
-    value[name] = sampleOfZod(f, name, where, opts?.voIncludeOptional === true);
+    value[name] = sampleOfZod(f, name, where, opts?.voIncludeOptional === true); // path root = the payload field name
   }
   return { value, autoStamped };
 }
@@ -1735,6 +1787,12 @@ export interface ProofLegs {
    *  discoverable-but-suspect (the leg's `recipeIssues`). Printed by the compile summary; the offline
    *  runner fails fast on recipe issues with the same words. Additive: absent on older files. */
   readonly birthDiagnostics?: readonly string[];
+  /** PROOF TAXONOMY DIAGNOSTICS (co2 ask: every directive is either PROVEN or NAMED-WHY): one line per
+   *  creating directive that drops out of the offline proof, saying exactly why — a payload the synthesizer
+   *  couldn't sample (carrying the EXACT field path from {@link synthesizePayload}), an attestation-authorized
+   *  create (needs a signed §3 quote), or a gated create with no seedable authority (the relation-bootstrap
+   *  gap). Never a silent drop. Printed by the compile summary. Additive: absent on older files. */
+  readonly proofDiagnostics?: readonly string[];
   /** SPATIAL MEMBERSHIP (lane-2 read-serving): present when a declared spatial index covers the created
    *  aggregate AND the plan-probe proved the synthesized payload lands a geometry on the indexed path —
    *  the offline runner asserts `spatialWithin(id, world)` contains the created row. */
@@ -1927,10 +1985,49 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
     for (const issue of r.leg?.recipeIssues ?? []) birthDiagnostics.push(`${domain}/${d.id}: ${issue}`);
   }
 
+  // PROOF TAXONOMY AUDIT (co2 ask: every creating directive is PROVEN or NAMED-WHY). Walk every `.creates`
+  // directive; if it is NOT represented by a proven leg, say exactly why — the synthesis failure names the
+  // EXACT unsampleable field path; an attestation/gated create names the lane that DOES prove it.
+  const proofDiagnostics: string[] = [];
+  const provenCreateIds = new Set<string>();
+  if (standalone !== null) {
+    if (standalone.directiveId !== undefined) provenCreateIds.add(standalone.directiveId);
+    for (const ec of standalone.extraCreates ?? []) provenCreateIds.add(ec.directiveId);
+  }
+  if (relationBootstrap !== undefined) provenCreateIds.add(relationBootstrap.gatedDirectiveId);
+  for (const d of mod.directives as Directive<unknown>[]) {
+    if (d?.marker !== "creates" || typeof d.payloadSchema !== "object" || d.birthsChild === true) continue;
+    if (provenCreateIds.has(d.id)) continue; // proven by some leg — nothing to name
+    const who = `${domain}/${d.id}`;
+    if (d.attestationAuthorizedGate !== undefined) {
+      proofDiagnostics.push(
+        `${who}: creates ${d.aggregateId} but is ATTESTATION-AUTHORIZED (needs a signed §3 attestation quote no synthesizer can produce) — proven via the born-child / attestation lane, not the standalone offline proof`,
+      );
+      continue;
+    }
+    if (d.requiresRelationGate !== undefined) {
+      // A gated create with no discoverable authority path (else it would be in provenCreateIds via the
+      // relation-bootstrap leg) — name the exact seeding gap (the negative conformance leg still proves the gate).
+      const gap = diagnoseRelationBootstrapGap(mod);
+      proofDiagnostics.push(gap ?? `${who}: creates ${d.aggregateId} gated by .requires("${d.requiresRelationGate.relation}") — no seedable authority path found; prove it by hand or expose a granter/seed`);
+      continue;
+    }
+    // An UNGATED standalone create that still isn't proven ⇒ its payload could not be synthesized. Re-run the
+    // synthesis to capture the exact-path reason (createLegFor swallowed it to keep the index resilient).
+    try {
+      synthesizePayload(d.payloadSchema as z.ZodTypeAny, who);
+      // Synthesis succeeded but the leg was still dropped (e.g. the aggregate isn't composed) — name that.
+      proofDiagnostics.push(`${who}: creates ${d.aggregateId} but no offline leg was built (its aggregate '${d.aggregateId}' is not composed in this package, or its create-leg probe failed) — prove it by hand in test/e2e.mts`);
+    } catch (e) {
+      proofDiagnostics.push(`${who}: creates ${d.aggregateId} but its payload could not be synthesized for the offline proof — ${(e as Error)?.message ?? e}`);
+    }
+  }
+
   return {
     domain,
     legs,
     ...(birthDiagnostics.length > 0 ? { birthDiagnostics } : {}),
+    ...(proofDiagnostics.length > 0 ? { proofDiagnostics } : {}),
     ...(standalone !== null
       ? {
           directiveId: standalone.directiveId,