@githolon/dsl 0.44.0 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.44.0",
+  "version": "0.45.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/build_package.ts

@@ -238,15 +238,63 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   // hand-rolled `t.jsonObject()` GeoJSON leaf) pass through unchecked, exactly as before.
   for (const s of spatials) {
     const agg = byId.get(s.of);
-    const field = agg?.fields[s.on];
-    const vo = field?.valueObject;
-    if (vo !== undefined && vo.geometry === undefined) {
+    const [head, ...pathSegs] = s.on.split(".");
+    const field = agg?.fields[head!];
+    if (agg !== undefined && field === undefined) {
       throw new Error(
-        `build-package: spatial '${s.id}' indexes '${s.of}.${s.on}', a '${vo.name}' value object with NO ` +
-          `geometry — the R*Tree needs an RFC 7946 geometry leaf. Give the geometry its OWN field ` +
-          `(e.g. \`point: geo.point().field()\`) and index that (v1: no sub-path indexing).`,
+        `build-package: spatial '${s.id}' indexes '${s.of}.${s.on}', but '${head}' is not a declared field of '${s.of}'.`,
       );
     }
+    const vo = field?.valueObject;
+    if (pathSegs.length === 0) {
+      if (vo !== undefined && vo.geometry === undefined) {
+        throw new Error(
+          `build-package: spatial '${s.id}' indexes '${s.of}.${s.on}', a '${vo.name}' value object with NO ` +
+            `geometry — the R*Tree needs an RFC 7946 geometry leaf. Index the nested geometry by path ` +
+            `(e.g. \`.on("${s.on}.point")\`) or give the geometry its OWN field.`,
+        );
+      }
+      continue;
+    }
+    // SUB-PATH SPATIAL (lane 2): the path is walked inside the composite leaf by the projection.
+    // When the head is a DECLARED VO, prove at build that the path lands on an RFC 7946 geometry
+    // (typo'd paths refuse here, not silently index nothing). A plain t.jsonObject() head passes
+    // unchecked — the same trust posture as a top-level hand-rolled geometry leaf.
+    if (vo !== undefined) {
+      const byName = new Map(vo.dependencies.map((d) => [d.name, d]));
+      byName.set(vo.descriptor.name, vo.descriptor);
+      let cur = vo.descriptor;
+      for (let i = 0; i < pathSegs.length; i++) {
+        const seg = pathSegs[i]!;
+        const f = cur.fields?.[seg];
+        if (f === undefined) {
+          throw new Error(
+            `build-package: spatial '${s.id}' path '${s.on}' — '${seg}' is not a field of value object '${cur.name}'.`,
+          );
+        }
+        const last = i === pathSegs.length - 1;
+        if (last) {
+          if (f.type !== "geometry") {
+            throw new Error(
+              `build-package: spatial '${s.id}' path '${s.on}' lands on a '${f.type}' field — the R*Tree needs ` +
+                `an RFC 7946 geometry leaf (a \`geo.*\` value object) at the end of the path.`,
+            );
+          }
+        } else {
+          if (f.type !== "object") {
+            throw new Error(
+              `build-package: spatial '${s.id}' path '${s.on}' — '${seg}' is a '${f.type}' field, not a nested ` +
+                `value object; the path cannot continue through it.`,
+            );
+          }
+          const next = byName.get(f.ref);
+          if (next === undefined) {
+            throw new Error(`build-package: spatial '${s.id}' path '${s.on}' — no descriptor for nested VO '${f.ref}'.`);
+          }
+          cur = next;
+        }
+      }
+    }
   }
   const dartImports = [...(spec.dartImports ?? [])];
   // THE PEER-SOVEREIGN ROOT-OF-TRUST: a home/child law that exports `requireParentAttestedBirth` declares

package/src/spatial.ts

@@ -72,8 +72,14 @@ export interface OfSpatial<F extends Record<string, Field> = Record<string, Fiel
    * declaration. `field` is `keyof`-checked against the `of`-aggregate's fields — a
    * typo'd field is a compile error (the same convention as `count`'s `.by(...)` is
    * a field of the type / `query`'s key fields).
+   *
+   * SUB-PATH SPATIAL (lane 2): `field` may be a DOTTED PATH into a composite value-object
+   * leaf (`"location.point"`) — the projection walks the decoded JSON to the nested
+   * geometry natively (one copy of the truth; NO denormalized sibling field). The head
+   * must be a declared field; when it is a declared VO, the sub-path is descriptor-checked
+   * at build to land on an RFC 7946 geometry.
    */
-  on(field: StringKeyOf<F>): SpatialDecl;
+  on(field: StringKeyOf<F> | `${StringKeyOf<F>}.${string}`): SpatialDecl;
 }
 
 /**

package/src/value_object.ts

@@ -630,9 +630,10 @@ function geoZod(kind: GeometryKind, coordinates: z.ZodTypeAny): z.ZodTypeAny {
  * The GEO value objects — RFC 7946 geometries as named VOs, and THE BLESSED WAY to
  * declare a spatial-indexable field: give the geometry its OWN aggregate field
  * (`point: GeoPoint.field()`) and pair it with `spatial(id).of(Agg).on("point")` —
- * the R*Tree indexes the field's GeoJSON geometry directly. (v1 boundary: the spatial
- * lane indexes a TOP-LEVEL field; a geometry nested inside another VO — e.g.
- * `location.point` — is data, not an indexable path.)
+ * the R*Tree indexes the field's GeoJSON geometry directly. SUB-PATH SPATIAL (lane 2):
+ * a geometry NESTED inside a composite VO is ALSO indexable by dotted path —
+ * `spatial(id).of(Agg).on("location.point")` — the projection walks the decoded leaf to the
+ * geometry natively (one copy of the truth; requires kernel ≥ the lane-2 artifact).
  */
 export const geo = {
   /** An RFC 7946 **Point** (`{type:"Point", coordinates:[lng,lat(,alt)?]}`) — the v1