@githolon/dsl 0.45.0 → 0.46.0

package/dart/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.32.0
+
+- SPATIAL READS: `NomosBbox` + `NomosBridge.spatialWithin(spatialId, bbox)` + `watchSpatial(...)` — the R*Tree probe surfaces on the bridge; generated clients (tooling ≥0.46) emit typed `sitesByBounds({required NomosBbox bbox})` + watch accessors.
+- Analyzer-clean under strict lints (curly-braces rule) — the two remaining unbraced ifs in the bridge are gone.
+
 ## 0.31.0
 
 - `NomosFieldMeta.fromBirth` — the registry surfaces BIRTH-PRESENCE LAW (`.fromBirth()` fields, tooling ≥0.42): a gate invariant guarantees the field present on every row, and the generated read models type it non-nullable.

package/dart/lib/src/webview_bridge.dart

@@ -275,6 +275,23 @@ class NomosCreated {
   String toString() => id;
 }
 
+/// A geographic bounding box for spatial reads (`[minLng, minLat] .. [maxLng, maxLat]`,
+/// RFC 7946 lng/lat order — the R*Tree probe's extent).
+class NomosBbox {
+  final double minLng;
+  final double minLat;
+  final double maxLng;
+  final double maxLat;
+  const NomosBbox({
+    required this.minLng,
+    required this.minLat,
+    required this.maxLng,
+    required this.maxLat,
+  });
+  Map<String, Object?> toJson() =>
+      {'minLng': minLng, 'minLat': minLat, 'maxLng': maxLng, 'maxLat': maxLat};
+}
+
 /// The result of [NomosBridge.offerCreates]: the new local [head] plus every aggregate the plan minted.
 class NomosOfferOutcome {
   final String head;
@@ -341,8 +358,9 @@ class NomosBridge {
   Future<void> get ready => _ready.future;
 
   void _onMessage(Map<String, Object?> m) {
-    if (m['v'] != kWebviewBridgeVersion)
+    if (m['v'] != kWebviewBridgeVersion) {
       return; // a foreign-version message is ignored (forward-compatible)
+    }
     final event = m['event'];
     if (event == 'ready') {
       if (!_ready.isCompleted) _ready.complete();
@@ -411,8 +429,9 @@ class NomosBridge {
     if (event == 'span') {
       // LIVE per-layer span: { event:'span', span:{ phase:'begin'|'end', id, track, name, kind, t0|t1 } }.
       _spanBuffer.add(m);
-      if (_spanBuffer.length > 400)
+      if (_spanBuffer.length > 400) {
         _spanBuffer.removeRange(0, _spanBuffer.length - 400);
+      }
       if (!_spanEvents.isClosed) _spanEvents.add(m);
       return;
     }
@@ -761,6 +780,13 @@ class NomosBridge {
   Future<List<Map<String, dynamic>>> queryById(String id) async =>
       _asRows(await _call('queryById', {'id': id}));
 
+  /// THE SPATIAL READ: rows of the declared spatial index's of-type whose geometry
+  /// intersects [bbox] — an R*Tree probe on the local projection, same row shape as [query].
+  Future<List<Map<String, dynamic>>> spatialWithin(
+          String spatialId, NomosBbox bbox) async =>
+      _asRows(await _call(
+          'spatialWithin', {'spatialId': spatialId, 'bbox': bbox.toJson()}));
+
   /// A maintained O(1) count / sum.
   Future<int> count(String countId, [String group = '']) async =>
       ((_asMap(await _call('count', {'countId': countId, 'group': group}))[
@@ -914,6 +940,10 @@ class NomosBridge {
   Stream<List<dynamic>> watchById(String id) =>
       _watchStream(kind: 'byId', id: id);
 
+  /// Reactive SPATIAL read: re-emits the R*Tree probe's rows whenever they change locally.
+  Stream<List<dynamic>> watchSpatial(String spatialId, NomosBbox bbox) =>
+      _watchStream(kind: 'spatial', spatialId: spatialId, bbox: bbox);
+
   /// SHAPE COMPATIBILITY (#72): one-shot verdict for this client's structural [requirement]
   /// (its baked `…InterfaceJson`, decoded) against the workspace's ON-LEDGER offer (auto-sourced).
   /// `{ ok, missing[], incompatible[] }` — names the exact directive/aggregate/field, not a hash.
@@ -953,7 +983,9 @@ class NomosBridge {
       {required String kind,
       String? queryId,
       Map<String, Object?>? params,
-      String? id}) {
+      String? id,
+      String? spatialId,
+      NomosBbox? bbox}) {
     final subId = 'w${++_seq}';
     late final StreamController<List<dynamic>> ctrl;
     ctrl = StreamController<List<dynamic>>(
@@ -962,7 +994,9 @@ class NomosBridge {
         'kind': kind,
         if (queryId != null) 'queryId': queryId,
         if (params != null) 'params': params,
-        if (id != null) 'id': id
+        if (id != null) 'id': id,
+        if (spatialId != null) 'spatialId': spatialId,
+        if (bbox != null) 'bbox': bbox.toJson(),
       }),
       onCancel: () async {
         _watches.remove(subId);

package/dart/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.31.0
+version: 0.32.0
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_dart.ts

@@ -810,19 +810,21 @@ function collectEnums(
   // hand-maintained `hide` list on the package barrel. The prefix is the field's
   // semantic home, not an accident of import order.
   const domainPrefix = dartTypeNameFromField(domainKey);
-  const register = (preferredName: string, values: readonly string[]) => {
+  // SEMANTIC ENUM NAMES (co2 feedback): the type is named by its SEMANTIC HOME —
+  // `<Domain><Owner><Field>` (`EstateSiteStatus`, not `EstateStatus5Enum`). The owner is the
+  // aggregate (or the payload's target aggregate / directive) the field lives on. A value-set
+  // shared across owners keeps the FIRST owner's name (one identical type, aggregates register
+  // before payloads so the aggregate's name wins). Numeric suffixes survive only as the
+  // last-resort collision guard — with owner-qualified bases they should never fire.
+  const register = (preferredName: string, values: readonly string[], owner = "") => {
     const key = values.join("|");
     if (dartTypes.has(key)) return;
-    // Two DIFFERENT value-sets WITHIN one domain can prefer the SAME name (e.g.
-    // several `status` fields with distinct literal lists all want `StatusEnum`).
-    // Suffix on collision so each distinct value-set gets a UNIQUE Dart enum
-    // (`EstateStatusEnum`, `EstateStatus2Enum`).
-    const base = `${domainPrefix}${dartTypeNameFromField(preferredName)}Enum`;
+    const base = `${domainPrefix}${dartTypeNameFromField(owner)}${dartTypeNameFromField(preferredName)}`;
     let name = base;
     let n = 1;
     while (usedNames.has(name)) {
       n += 1;
-      name = `${domainPrefix}${dartTypeNameFromField(preferredName)}${n}Enum`;
+      name = `${base}${n}`;
     }
     usedNames.add(name);
     dartTypes.set(key, name);
@@ -846,7 +848,7 @@ function collectEnums(
     )) {
       if (field.kind === "enum") {
         // Unwrap `.optional()` so an optional enum field still registers its options.
-        register(name, zodEnumValues(unwrapZod(field.zod)));
+        register(name, zodEnumValues(unwrapZod(field.zod)), agg.id);
       }
     }
   }
@@ -856,7 +858,7 @@ function collectEnums(
     for (const [name, zt] of Object.entries(shape)) {
       const inner = unwrapZod(zt as z.ZodTypeAny);
       if (zodTypeName(inner) === "ZodEnum") {
-        register(name, zodEnumValues(inner));
+        register(name, zodEnumValues(inner), (d as { aggregateId?: string }).aggregateId ?? d.id);
       }
     }
   }
@@ -1246,7 +1248,8 @@ const geometryCoordsDart: Record<string, string> = {
  * VOs stay separate types (VO names are package-unique, so so are these).
  */
 function voEnumName(voName: string, fieldName: string): string {
-  return `${voName}${dartTypeNameFromField(fieldName)}Enum`;
+  // SEMANTIC NAME (co2 feedback): `<VoName><Field>` — `SiteLocationSource`, not `…SourceEnum`.
+  return `${voName}${dartTypeNameFromField(fieldName)}`;
 }
 
 /** The tolerant-decode SENTINEL case name — dodge a literal enum value that would
@@ -1399,16 +1402,24 @@ function emitVoHelpers(): string {
     `/// Deep json equality for generated value-object classes (toJson-based).`,
     `bool _voJsonEq(Object? a, Object? b) {`,
     `  if (a is Map && b is Map) {`,
-    `    if (a.length != b.length) return false;`,
+    `    if (a.length != b.length) {`,
+    `      return false;`,
+    `    }`,
     `    for (final k in a.keys) {`,
-    `      if (!b.containsKey(k) || !_voJsonEq(a[k], b[k])) return false;`,
+    `      if (!b.containsKey(k) || !_voJsonEq(a[k], b[k])) {`,
+    `        return false;`,
+    `      }`,
     `    }`,
     `    return true;`,
     `  }`,
     `  if (a is List && b is List) {`,
-    `    if (a.length != b.length) return false;`,
+    `    if (a.length != b.length) {`,
+    `      return false;`,
+    `    }`,
     `    for (var i = 0; i < a.length; i++) {`,
-    `      if (!_voJsonEq(a[i], b[i])) return false;`,
+    `      if (!_voJsonEq(a[i], b[i])) {`,
+    `        return false;`,
+    `      }`,
     `    }`,
     `    return true;`,
     `  }`,

package/src/codegen_dart_client.ts

@@ -137,7 +137,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     // appear — only the actor identity (the bridge owns signing).
     const gate = (d as { requiresRelationGate?: { relation: string } }).requiresRelationGate;
     const gateGuard = gate !== undefined
-      ? `    if (actor == null || actor!.trim().isEmpty) throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, requires: ${dartStr(gate.relation)});`
+      ? `    if (actor == null || actor!.trim().isEmpty) {\n      throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, requires: ${dartStr(gate.relation)});\n    }`
       : "";
     const gateDoc = gate !== undefined
       ? `  /// GATED: needs an \`actor\` (the \`${gate.relation}\` relation) — throws MissingOfferAuthority otherwise.`
@@ -218,6 +218,23 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     );
   }
 
+  // ── declared spatial indexes → typed bbox reads (lane-2 read-serving) ──
+  for (const sp of (mod.spatials ?? []) as { id: string; of: string; on: string }[]) {
+    const model = readModelClassName(sp.of);
+    const m = safeMethod(lcFirst(camel(sp.id)));
+    methods.push(
+      `  /// Declared spatial index \`${sp.id}\` — rows of \`${sp.of}\` whose \`${sp.on}\` geometry`,
+      `  /// intersects [bbox] (an R*Tree probe on the local projection, never a scan).`,
+      `  Future<List<${model}>> ${m}({required NomosBbox bbox}) async =>`,
+      `      (await bridge.spatialWithin(${dartStr(sp.id)}, bbox)).map((r) => ${rowToModel(model, "r")}).toList();`,
+      ``,
+      `  /// Reactive \`${sp.id}\` — re-emits when the probe's rows change locally.`,
+      `  Stream<List<${model}>> watch${cap(camel(sp.id))}({required NomosBbox bbox}) =>`,
+      `      bridge.watchSpatial(${dartStr(sp.id)}, bbox).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
+      ``,
+    );
+  }
+
   // ── counts / sums → O(1) typed reads ──
   for (const c of (mod.counts ?? []).map((raw) => finishCount(raw))) {
     const m = safeMethod(lcFirst(camel(c.id)));

package/src/codegen_proof.ts

@@ -98,13 +98,13 @@ function sampleString(zt: z.ZodTypeAny, field: string): string {
 }
 
 /** 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): unknown {
+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.
   const vo = voMetaOf(zt);
-  if (vo !== undefined) return voSample(vo);
+  if (vo !== undefined) return voSample(vo, { includeOptional: voIncludeOptional });
   switch (zodKind(zt)) {
     case "string":
       return sampleString(zt, field);
@@ -120,14 +120,14 @@ function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string): unknown {
     }
     case "array": {
       const el = zodArrayElement(zt);
-      return zodKind(el) === "string" ? ["sample-a"] : [sampleOfZod(el, field, where)];
+      return zodKind(el) === "string" ? ["sample-a"] : [sampleOfZod(el, field, 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);
+        out[name] = sampleOfZod(raw as z.ZodTypeAny, name, where, voIncludeOptional);
       }
       return out;
     }
@@ -136,10 +136,10 @@ function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string): unknown {
     case "nullable":
     case "optional":
     case "default":
-      return sampleOfZod(zodDef(zt).innerType!, field, where);
+      return sampleOfZod(zodDef(zt).innerType!, field, where, voIncludeOptional);
     case "union": {
       const first = zodDef(zt).options?.[0];
-      if (first !== undefined) return sampleOfZod(first, field, where);
+      if (first !== undefined) return sampleOfZod(first, field, where, voIncludeOptional);
       throw new Error(`codegen-proof: empty union at field '${field}' of ${where}`);
     }
     default:
@@ -154,7 +154,7 @@ function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string): unknown {
  * optional/defaulted fields omitted, required `…At` strings omitted (auto-stamped
  * by the generated client), everything else sampled by {@link sampleOfZod}.
  */
-export function synthesizePayload(schema: z.ZodTypeAny, where: string): SynthesizedPayload {
+export function synthesizePayload(schema: z.ZodTypeAny, where: string, opts?: { voIncludeOptional?: boolean }): SynthesizedPayload {
   if (zodKind(schema) !== "object") {
     throw new Error(`codegen-proof: ${where} payload is not a zod object — the proof can only synthesize object payloads`);
   }
@@ -166,7 +166,7 @@ export function synthesizePayload(schema: z.ZodTypeAny, where: string): Synthesi
     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);
+    value[name] = sampleOfZod(f, name, where, opts?.voIncludeOptional === true);
   }
   return { value, autoStamped };
 }
@@ -598,6 +598,35 @@ export interface BornContextAuthority {
 
 /** Run a directive's plan with a synthesized+probe payload under birth-probe globals and return the drained
  *  field ops (authoring sink + returned ops). `undefined` ⇒ the plan couldn't be probed. */
+/** Run a directive's plan on an EXPLICIT payload under the deterministic probe ports, returning the
+ *  emitted ops (undefined when the plan throws) — the payload-parameterized sibling of {@link probePlanOps}. */
+function probePlanOpsWithPayload(
+  dir: Directive<unknown>,
+  probePayload: Record<string, unknown>,
+  _where: string,
+): FieldOp[] | undefined {
+  let ops: FieldOp[] | undefined;
+  try {
+    withBirthProbeGlobals(() => {
+      __resetAuthoring();
+      __resetReads();
+      __resetBirths();
+      try {
+        const returned = dir.plan(probePayload as never, deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }));
+        const drained = [...__drainAuthoring(), ...(Array.isArray(returned) ? returned : [])];
+        ops = drained.filter((o): o is FieldOp => (o as { kind?: string }).kind !== "strike");
+      } finally {
+        __resetAuthoring();
+        __resetReads();
+        __resetBirths();
+      }
+    });
+  } catch {
+    return undefined;
+  }
+  return ops;
+}
+
 function probePlanOps(
   dir: Directive<unknown>,
   where: string,
@@ -1575,6 +1604,22 @@ export interface ProofLegs {
   readonly mintField?: string;
   readonly query?: { readonly id: string; readonly params: Record<string, unknown> };
   readonly count?: { readonly id: string; readonly group: 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. */
+  readonly spatial?: { readonly id: string };
+  /** EVERY OTHER standalone create (co2 feedback: the proof exercises ALL VO-bearing creates, not just
+   *  the first) — each dispatched + asserted exactly like the primary. Additive: absent on older files. */
+  readonly extraCreates?: readonly {
+    readonly directiveId: string;
+    readonly aggregateId: string;
+    readonly payload: Record<string, unknown>;
+    readonly autoStamped: readonly string[];
+    readonly mintField?: string;
+    readonly query?: { readonly id: string; readonly params: Record<string, unknown> };
+    readonly count?: { readonly id: string; readonly group: string };
+    readonly spatial?: { readonly id: string };
+  }[];
   /** THE CHILD-BIRTH LEG — present iff this domain has a `.births()` directive (it is `child-birth-provable`).
    *  When this domain is itself the BORN child's law (no standalone create), the index also registers the
    *  child domain key pointing at the SAME leg, so `proof --domain <child>` resolves through the parent birth. */
@@ -1603,14 +1648,69 @@ function isStandaloneCreate(d: Directive<unknown> | undefined): boolean {
     && d.requiresRelationGate === undefined;
 }
 
-export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
-  const createDir = (mod.directives as Directive<unknown>[]).find((d) => isStandaloneCreate(d));
-  if (createDir === undefined) return null;
-  const domain = mod.domain ?? mod.name;
+/** Does `v` carry an RFC 7946 geometry object at `segs` (walked into the composite)? */
+function geometryAtPath(v: unknown, segs: readonly string[]): boolean {
+  let cur: unknown = v;
+  for (const s of segs) {
+    if (cur === null || typeof cur !== "object") return false;
+    cur = (cur as Record<string, unknown>)[s];
+  }
+  return (
+    cur !== null && typeof cur === "object" &&
+    typeof (cur as { type?: unknown }).type === "string" &&
+    (cur as { coordinates?: unknown }).coordinates !== undefined
+  );
+}
+
+/** Build ONE standalone-create leg entry (payload + matched query/count + the spatial-membership
+ *  assertion when a declared spatial index covers the type and the plan-probe lands a geometry on
+ *  the indexed path — trying the optionals-included VO sample when the default omits it). */
+function createLegFor(
+  mod: DomainModule,
+  createDir: Directive<unknown>,
+  domain: string,
+): {
+  directiveId: string; aggregateId: string; payload: Record<string, unknown>;
+  autoStamped: readonly string[]; mintField?: string;
+  query?: { id: string; params: Record<string, unknown> };
+  count?: { id: string; group: string };
+  spatial?: { id: string };
+} | null {
   const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === createDir.aggregateId);
   if (agg === undefined) return null;
-  const synth = synthesizePayload(createDir.payloadSchema as z.ZodTypeAny, `${domain}/${createDir.id}`);
+  const where = `${domain}/${createDir.id}`;
+  let synth = synthesizePayload(createDir.payloadSchema as z.ZodTypeAny, where);
   const mintField = mintedCreateField(createDir, agg);
+
+  // SPATIAL MEMBERSHIP: probe the plan — does the create set the indexed head field with a geometry
+  // at the declared path? If the default sample omits an optional geometry, retry with the
+  // optionals-included VO sample and adopt IT as the leg's payload (so the proof exercises the
+  // geometry the index needs).
+  let spatial: { id: string } | undefined;
+  const spatials = ((mod.spatials ?? []) as { id: string; of: string; on: string }[]).filter((sp) => sp.of === agg.id);
+  if (spatials.length > 0) {
+    const probeWith = (sy: SynthesizedPayload): FieldOp[] | undefined => {
+      const probePayload: Record<string, unknown> = { ...sy.value };
+      for (const f of sy.autoStamped) probePayload[f] = "2026-01-01T00:00:00Z";
+      const probed = probePlanOpsWithPayload(createDir, probePayload, where);
+      return probed;
+    };
+    const hits = (ops: FieldOp[] | undefined, sp: { on: string }): boolean => {
+      if (ops === undefined) return false;
+      const [head, ...segs] = sp.on.split(".");
+      return ops.some((o) => (o as { kind?: string }).kind === "set" && (o as { field?: string }).field === head && geometryAtPath((o as { value?: unknown }).value, segs));
+    };
+    let ops = probeWith(synth);
+    let matched = spatials.find((sp) => hits(ops, sp));
+    if (matched === undefined) {
+      const richer = synthesizePayload(createDir.payloadSchema as z.ZodTypeAny, where, { voIncludeOptional: true });
+      ops = probeWith(richer);
+      matched = spatials.find((sp) => hits(ops, sp));
+      if (matched !== undefined) synth = richer; // the geometry-bearing sample becomes the leg's payload
+    }
+    if (matched !== undefined) spatial = { id: matched.id };
+  }
+
   const baseValue: Record<string, unknown> = { ...synth.value };
   if (mintField !== undefined) delete baseValue[mintField];
   const query = ((mod.queries ?? []) as QueryDecl[]).find(
@@ -1620,8 +1720,6 @@ export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
     .map((raw) => finishCount(raw))
     .find((c) => c.of === agg.id && (c as { where?: unknown }).where == null && (c.by == null || baseValue[c.by] !== undefined));
   return {
-    domain,
-    legs: ["compile-valid", "standalone-provable"],
     directiveId: createDir.id,
     aggregateId: agg.id,
     payload: baseValue,
@@ -1629,6 +1727,23 @@ export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
     ...(mintField !== undefined ? { mintField } : {}),
     ...(query ? { query: { id: query.id, params: Object.fromEntries(query.key.map((k) => [k, baseValue[k]])) } } : {}),
     ...(count ? { count: { id: count.id, group: count.by != null ? String(baseValue[count.by]) : "" } } : {}),
+    ...(spatial !== undefined ? { spatial } : {}),
+  };
+}
+
+export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
+  const domain = mod.domain ?? mod.name;
+  const creates = (mod.directives as Directive<unknown>[]).filter((d) => isStandaloneCreate(d));
+  const legsBuilt = creates
+    .map((d) => { try { return createLegFor(mod, d, domain); } catch { return null; } })
+    .filter((l): l is NonNullable<typeof l> => l !== null);
+  if (legsBuilt.length === 0) return null;
+  const [primary, ...extras] = legsBuilt;
+  return {
+    domain,
+    legs: ["compile-valid", "standalone-provable"],
+    ...primary!,
+    ...(extras.length > 0 ? { extraCreates: extras } : {}),
   };
 }
 
@@ -1683,6 +1798,8 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
           ...(standalone.mintField !== undefined ? { mintField: standalone.mintField } : {}),
           ...(standalone.query !== undefined ? { query: standalone.query } : {}),
           ...(standalone.count !== undefined ? { count: standalone.count } : {}),
+          ...(standalone.spatial !== undefined ? { spatial: standalone.spatial } : {}),
+          ...(standalone.extraCreates !== undefined ? { extraCreates: standalone.extraCreates } : {}),
         }
       : {}),
     ...(childBirthWithSetup !== undefined ? { childBirth: childBirthWithSetup } : {}),

package/src/codegen_ts.ts

@@ -438,6 +438,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  watchById(aggregateId: string, cb: (rows: unknown) => void, opts?: { intervalMs?: number }): () => void;`,
     `  /** Declared-count / declared-sum O(1) reads (maintained by the read engine). */`,
     `  count(countId: string, groupKey?: string): Promise<number>;`,
+  `  /** THE SPATIAL READ (R*Tree probe): rows intersecting the bbox — same row shape as query(). */`,
+  `  spatialWithin(spatialId: string, bbox: { minLng: number; minLat: number; maxLng: number; maxLat: number }): Promise<unknown>;`,
     `  sum(sumId: string, groupKey?: string): Promise<number>;`,
     ...(anyPackedTaxonomy(modules)
       ? [
@@ -824,6 +826,12 @@ 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(${JSON.stringify(sp.id)}, bbox) as Promise<Row<${sp.of}Data>[]>,`,
+      );
+    }
     for (const q of (mod.queries ?? []) as QueryDecl[]) {
       const agg = aggByType.get(q.returns);
       const params = q.key

package/src/value_object.ts

@@ -349,6 +349,7 @@ function sampleOfDescriptorField(
   f: ValueObjectFieldDescriptor,
   fieldName: string,
   byName: Map<string, ValueObjectDescriptor>,
+  includeOptional = false,
 ): unknown {
   switch (f.type) {
     case "string": return `sample-${fieldName}`;
@@ -356,17 +357,17 @@ 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)];
+    case "array": return [sampleOfDescriptorField(f.items, fieldName, byName, includeOptional)];
     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);
+      return sampleOfDescriptor(dep, byName, includeOptional);
     }
   }
 }
 
-function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueObjectDescriptor>): unknown {
+function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueObjectDescriptor>, includeOptional = false): unknown {
   if (d.geometry !== undefined) return GEOMETRY_SAMPLES[d.geometry];
   if (d.union !== undefined) {
     // FIRST declared arm (keys are sorted — deterministic); `example:` overrides upstream.
@@ -378,15 +379,15 @@ function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueO
     }
     const out: Record<string, unknown> = { type: key };
     for (const [k, f] of Object.entries(arm.fields)) {
-      if (f.optional === true) continue;
-      out[k] = sampleOfDescriptorField(f, k, byName);
+      if (f.optional === true && !includeOptional) continue;
+      out[k] = sampleOfDescriptorField(f, k, byName, includeOptional);
     }
     return out;
   }
   const out: Record<string, unknown> = {};
   for (const [k, f] of Object.entries(d.fields ?? {})) {
-    if (f.optional === true) continue; // optional → omitted (mirrors payload synthesis)
-    out[k] = sampleOfDescriptorField(f, k, byName);
+    if (f.optional === true && !includeOptional) continue; // optional → omitted (mirrors payload synthesis)
+    out[k] = sampleOfDescriptorField(f, k, byName, includeOptional);
   }
   return out;
 }
@@ -397,12 +398,12 @@ 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): unknown {
+export function voSample(meta: ValueObjectFieldMeta, opts?: { includeOptional?: boolean }): 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);
+  return sampleOfDescriptor(meta.descriptor, byName, opts?.includeOptional === true);
 }
 
 function makeValueObject<T>(