@githolon/dsl 0.52.0 → 0.54.0

package/src/law_check.ts

@@ -30,7 +30,7 @@ import { z } from "zod";
 import type { AggregateHandle } from "./aggregate.js";
 import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
-import type { Field } from "./fields.js";
+import type { Field, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
 import type { FieldOp, PlannedOp } from "./ops.js";
 import { deterministicPorts } from "./ctx.js";
 import { synthesizePayload, withBirthProbeGlobals, type SynthesizedPayload } from "./codegen_proof.js";
@@ -526,6 +526,136 @@ function encryptionGroupingFindings(mod: DomainModule, aggById: ReadonlyMap<stri
   return out;
 }
 
+// ── TWIN 5 (#30) — DOTTED QUERY KEY resolves in the target VO's descriptor tree ─────
+// A query keyed on a nested path (`location.postalAddress.postalCode`) indexes a string leaf
+// inside a value-object field. The projection walks that path at fold time (kernel-native, era-
+// ruled); if the path names a subfield the VO shape does NOT have, the query would just never
+// match — a silent dead index. So we refuse it at COMPILE, naming the valid dotted leaf paths.
+// PAYLOAD-INDEPENDENT (a pure declaration-vs-shape mismatch) ⇒ a REFUSE, not a warn.
+
+/** The scalar VO leaf kinds a dotted key may terminate on (the projection stores STRING keys, so
+ *  only these produce an index row; an `object`/`array`/`map`/`geometry` is not a queryable leaf). */
+function isScalarLeafDescriptor(d: ValueObjectFieldDescriptor): boolean {
+  return d.type === "string" || d.type === "number" || d.type === "boolean" || d.type === "enum" || d.type === "literal";
+}
+
+/** Enumerate every dotted leaf path reachable through `object`/`geometry` refs under one VO
+ *  descriptor, `prefix`-rooted. Arrays/maps are not name-addressable, so they are not descended. */
+function voLeafPaths(
+  desc: ValueObjectDescriptor,
+  byName: ReadonlyMap<string, ValueObjectDescriptor>,
+  prefix: string,
+  seen: ReadonlySet<string>,
+): string[] {
+  if (desc.fields === undefined) return []; // a geo/union VO exposes no named structural subfields here
+  if (seen.has(desc.name)) return []; // cycle guard (a VO transitively nesting itself)
+  const nextSeen = new Set(seen).add(desc.name);
+  const out: string[] = [];
+  for (const [name, f] of Object.entries(desc.fields)) {
+    const path = `${prefix}.${name}`;
+    if (isScalarLeafDescriptor(f)) {
+      out.push(path);
+    } else if ((f.type === "object" || f.type === "geometry") && byName.has(f.ref)) {
+      out.push(...voLeafPaths(byName.get(f.ref)!, byName, path, nextSeen));
+    }
+  }
+  return out;
+}
+
+/** Resolve a dotted path (segments AFTER the lead VO field) through a VO descriptor tree. Returns
+ *  `"leaf"` if it lands on a scalar leaf, `"nonleaf"` if it resolves but to a non-scalar node (an
+ *  object/array/map — not indexable), or `undefined` if a segment is absent. */
+function resolveVoPath(
+  rootDesc: ValueObjectDescriptor,
+  byName: ReadonlyMap<string, ValueObjectDescriptor>,
+  segments: readonly string[],
+): "leaf" | "nonleaf" | undefined {
+  let desc: ValueObjectDescriptor | undefined = rootDesc;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i]!;
+    const f = desc?.fields?.[seg];
+    if (f === undefined) return undefined;
+    const isLast = i === segments.length - 1;
+    if (isLast) return isScalarLeafDescriptor(f) ? "leaf" : "nonleaf";
+    // A non-terminal segment must descend into a nested VO by ref.
+    if ((f.type === "object" || f.type === "geometry") && byName.has(f.ref)) {
+      desc = byName.get(f.ref);
+    } else {
+      return undefined; // a scalar/array/map mid-path can't be descended by name
+    }
+  }
+  return undefined;
+}
+
+function dottedQueryKeyFindings(mod: DomainModule, aggById: ReadonlyMap<string, AggregateHandle>): Finding[] {
+  const domain = mod.domain ?? mod.name;
+  const out: Finding[] = [];
+
+  // ONE dotted-key checker, shared by query `.key` and count/sum/min/max/exists `.by` (both index
+  // or group BY a nested VO leaf and both silently mismatch on a bad path). `noun`/`verb` name the
+  // read shape in the message; `aggId` is the target aggregate type; `key` is the (dotted) field.
+  const checkDotted = (noun: string, readId: string, verb: string, aggId: string, key: string): void => {
+    if (!key.includes(".")) return; // a flat key is judged by kind routing at the gate, not here
+    const [lead, ...rest] = key.split(".");
+    const agg = aggById.get(aggId);
+    if (agg === undefined) return; // foreign/framework target — the runtime gate arbitrates
+    const field = agg.fields[lead!] as Field | undefined;
+    const vo = field?.valueObject;
+    if (field === undefined || vo === undefined) {
+      const voFields = Object.entries(agg.fields)
+        .filter(([, f]) => (f as Field).valueObject !== undefined)
+        .map(([n]) => n)
+        .sort();
+      out.push({
+        domain,
+        directiveId: readId,
+        level: "refuse",
+        what: `${noun} '${readId}' ${verb} the dotted path '${key}', but '${lead}' is ${field === undefined ? `not a field of '${aggId}'` : `not a value-object field on '${aggId}' (a dotted key descends a VO leaf)`}`,
+        fix: `${verb} a value-object field's subfield — VO fields on '${aggId}': ${voFields.length ? voFields.join(", ") : "(none)"} — or use a flat top-level key`,
+      });
+      return;
+    }
+    const byName = new Map<string, ValueObjectDescriptor>();
+    byName.set(vo.descriptor.name, vo.descriptor);
+    for (const d of vo.dependencies) byName.set(d.name, d);
+    const verdict = resolveVoPath(vo.descriptor, byName, rest);
+    if (verdict === "leaf") return; // resolves to an indexable scalar leaf — good
+    const valid = voLeafPaths(vo.descriptor, byName, lead!, new Set()).sort();
+    out.push({
+      domain,
+      directiveId: readId,
+      level: "refuse",
+      what: `${noun} '${readId}' ${verb} '${key}', which ${verdict === "nonleaf" ? `resolves to a non-scalar node in the '${vo.name}' value object (only a scalar leaf is indexable)` : `does not resolve in the '${vo.name}' value object's shape`}`,
+      fix: `${verb} a scalar subfield — valid dotted paths under '${lead}': ${valid.length ? valid.join(", ") : "(none)"}`,
+    });
+  };
+
+  for (const q of mod.queries ?? []) for (const k of q.key) checkDotted("query", q.id, "is keyed on", q.returns, k);
+  // count/sum/min/max/exists `.by` GROUP-BY a nested VO leaf (now maintained on both snapshot sides,
+  // #30 follow-up) — a bad dotted path would silently group nothing, so validate it here too.
+  for (const c of mod.counts ?? []) {
+    const d = finishCount(c);
+    if (d.by !== undefined) checkDotted("count", d.id, "groups by", d.of, d.by);
+  }
+  for (const s of mod.sums ?? []) {
+    const d = finishSum(s);
+    if (d.by !== undefined) checkDotted("sum", d.id, "groups by", d.of, d.by);
+  }
+  for (const m of mod.mins ?? []) {
+    const d = finishExtremum(m);
+    if (d.by !== undefined) checkDotted("min", d.id, "groups by", d.of, d.by);
+  }
+  for (const m of mod.maxes ?? []) {
+    const d = finishExtremum(m);
+    if (d.by !== undefined) checkDotted("max", d.id, "groups by", d.of, d.by);
+  }
+  for (const e of mod.exists_ ?? []) {
+    const d = finishExists(e);
+    if (d.by !== undefined) checkDotted("exists", d.id, "groups by", d.of, d.by);
+  }
+  return out;
+}
+
 // ── TWIN 3 (slice 2) — INVARIANT SAMPLE-PROBE (aggregate + workspace invariants) ────
 // An aggregate invariant (`aggregate(id, fields, { invariant })`) runs on every touching event; a
 // workspaceInvariant(id).on(dir).reads(...).assert(...) runs at the gate. We probe each like a plan:
@@ -731,6 +861,7 @@ export function checkDomainModules(
     // Slice-2/slice-3 twins over the whole module: invariant sample-probes + encryption grouping.
     findings.push(...invariantFindings(mod, aggById));
     findings.push(...encryptionGroupingFindings(mod, aggById));
+    findings.push(...dottedQueryKeyFindings(mod, aggById));
   }
 
   // The BIRTH-RECIPE twin (unify): fold the scattered `.births()` recipe diagnostics into the

package/src/ops.ts

@@ -44,6 +44,16 @@ export interface FieldOp {
    */
   readonly marker?: PlannedEventMarker;
   readonly field: string;
+  /**
+   * The op TARGET aggregate's declared {@link Field} for `field`, captured from the fluent handle
+   * (`instance(Agg,id)` / `existing(Agg,id)` / `ensure(Agg,id)` / a bare handle) at op-construction —
+   * the ONE point that KNOWS the target's schema. Wire encoding resolves the field kind + merge driver
+   * from THIS (the op's real target), never from the directive's dispatch/primary aggregate: a plan that
+   * fans a VO/json (or a RemoveWins/LastPosition) write out to a SIBLING aggregate would otherwise lose
+   * its field metadata and mis-encode (a VO object throwing "kernel scalars are Str|Int only"). Internal,
+   * transient (never wire-serialized) — so carrying the Field object costs no hash and crosses no boundary.
+   */
+  readonly targetField?: Field;
   readonly kind: "set" | "addToSet" | "setEntry" | "increment" | "decrement" | "removeFromSet";
   readonly value?: unknown;
   readonly items?: readonly string[];
@@ -104,7 +114,7 @@ type Fields<A> = A extends Target<string, infer F> ? F : never;
  * PrincipalEvidence conversion — and ONLY that one, so writing un-endorsed identity (or the wrong
  * endorsement) into an authority/standing sink does not typecheck. The read/wire type is unchanged.
  */
-type AcceptedValue<F> = F extends { readonly facet: "authority" }
+export type AcceptedValue<F> = F extends { readonly facet: "authority" }
   ? FieldValue<F> | EndorsedAuthority<FieldValue<F>>
   : F extends { readonly facet: "standing" }
     ? FieldValue<F> | EndorsedStanding<FieldValue<F>>
@@ -121,6 +131,14 @@ function addressOf(agg: Target): { aggregateId: string; aggregateType?: string }
   return { aggregateId: (agg as AggregateHandle).id };
 }
 
+/** Capture the target aggregate's declared Field for `field` (see {@link FieldOp.targetField}). Both
+ *  an `AggregateHandle` and a `BoundAggregate` carry `.fields`, so a fanned-out sibling op keeps its
+ *  target's schema. Returns `{}` (no key) when the field is unknown — byte-identical to before. */
+function targetFieldOf(agg: Target, field: string): { targetField?: Field } {
+  const f = (agg as { fields?: Record<string, Field> }).fields?.[field];
+  return f ? { targetField: f } : {};
+}
+
 /**
  * Set a scalar (or map-whole/ref) field. Field name + value type are both checked.
  *
@@ -154,13 +172,14 @@ export function set<
   if (endorsement) {
     return {
       ...addressOf(agg),
+      ...targetFieldOf(agg, field),
       field,
       kind: "set",
       value: endorsement.principal,
       endorsement: { facet: endorsement.facet, reason: endorsement.reason },
     };
   }
-  return { ...addressOf(agg), field, kind: "set", value };
+  return { ...addressOf(agg), ...targetFieldOf(agg, field), field, kind: "set", value };
 }
 
 /** Return the same field op with an explicit per-aggregate event marker. */
@@ -185,7 +204,7 @@ export function addToSet<
   }[keyof Fields<A>] &
     string,
 >(agg: A, field: K, items: readonly string[]): FieldOp {
-  return { ...addressOf(agg), field, kind: "addToSet", items };
+  return { ...addressOf(agg), ...targetFieldOf(agg, field), field, kind: "addToSet", items };
 }
 
 /**
@@ -203,7 +222,7 @@ function counterDelta<A extends Target, K extends CounterKey<A>>(
   if (!Number.isInteger(amount) || amount < 0) {
     throw new Error(`${kind}('${String(field)}', ${amount}): amount must be a non-negative integer.`);
   }
-  return { ...addressOf(agg), field: field as string, kind, value: amount };
+  return { ...addressOf(agg), ...targetFieldOf(agg, field as string), field: field as string, kind, value: amount };
 }
 /** A counter field key — `kind:"counter"` only (an `int` is NOT a counter; that would not converge). */
 type CounterKey<A> = {
@@ -234,7 +253,7 @@ export function removeFromSet<
   }[keyof Fields<A>] &
     string,
 >(agg: A, field: K, items: readonly string[]): FieldOp {
-  return { ...addressOf(agg), field, kind: "removeFromSet", items };
+  return { ...addressOf(agg), ...targetFieldOf(agg, field), field, kind: "removeFromSet", items };
 }
 
 /** Set one entry of a map field. The map's value type is checked. */
@@ -250,7 +269,7 @@ export function setEntry<
   key: string,
   value: FieldValue<Fields<A>[K]> extends Record<string, infer V> ? V : never,
 ): FieldOp {
-  return { ...addressOf(agg), field, kind: "setEntry", entryKey: key, value };
+  return { ...addressOf(agg), ...targetFieldOf(agg, field), field, kind: "setEntry", entryKey: key, value };
 }
 
 export type { Field };

package/src/path.ts

@@ -0,0 +1,115 @@
+// 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.
+
+/**
+ * TYPED PATH HANDLES (#29) — a type-safe way to spell a projection field PATH (a top-level
+ * field OR a dotted path into a value object's subfields) as a compile-checked reference
+ * instead of a bare string.
+ *
+ *     spatial("sitesByBounds").of(EstateSite).on(path(EstateSite).location.point)
+ *     query("sitesByCity").key(path(EstateSite).location.address.city).returns(EstateSite)
+ *
+ * `path(EstateSite)` returns a typed PROXY whose members are the aggregate's declared fields;
+ * descending through a value-object field (`.location.point`) is checked against the VO's TS
+ * shape at every hop — a typo'd subfield is a COMPILE error. The resulting {@link PathRef}
+ * COMPILES TO THE DOTTED STRING (`"location.point"`), so it is PURE SUGAR: `.on(path(...).x.y)`
+ * and `.on("x.y")` produce byte-identical declarations (hash-equal — the era-safety contract).
+ *
+ * ACCEPTANCE: {@link spatial}'s `.on(...)` and {@link query}'s `.key(...)` accept a `PathRef`
+ * anywhere they accept the string spelling, and coerce it to the string at build via
+ * {@link pathString}. Nothing else in the pipeline sees a `PathRef` — it collapses to a string
+ * the moment a declaration is built.
+ */
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field, FieldValue } from "./fields.js";
+
+/**
+ * A typed reference to a projection field PATH — the dotted string it denotes rides `.path`,
+ * and it stringifies to that same path (so `String(ref)` / a template literal / `.toString()`
+ * all yield `"location.point"`). `Leaf` carries the TS type of the value AT the path (for future
+ * leaf-kind constraints, e.g. spatial wanting a geometry); v1 accepts any leaf.
+ */
+export interface PathRef<Leaf = unknown> {
+  readonly __isPathRef: true;
+  /** The dotted path string this handle denotes (e.g. `"location.point"`). */
+  readonly path: string;
+  toString(): string;
+  /** Phantom to keep `Leaf` load-bearing for inference. */
+  readonly _leaf?: Leaf;
+}
+
+/** A plain (indexable) OBJECT value — the only leaf kind you may descend INTO. Arrays and
+ *  functions are terminals (you index an array element by nothing meaningful in a field path). */
+type IsPlainObject<V> = V extends readonly unknown[]
+  ? false
+  : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    V extends (...args: any[]) => any
+    ? false
+    : V extends object
+      ? true
+      : false;
+
+/**
+ * A node in a typed path: it IS a {@link PathRef} for the value at this position (so you may
+ * STOP here and pass it to `.on(...)`/`.key(...)`), AND — when the value is a plain object —
+ * exposes each of its subfields as a further node (so you may DESCEND). `NonNullable` unwraps
+ * an optional VO field so `.location.point` descends through `location?: SiteLocation`.
+ */
+export type PathNode<V> = PathRef<V> &
+  (IsPlainObject<NonNullable<V>> extends true
+    ? { readonly [K in keyof NonNullable<V> & string]-?: PathNode<NonNullable<NonNullable<V>[K]>> }
+    : unknown);
+
+/** The ROOT of a typed path: the aggregate's declared fields, each a descendable {@link PathNode}. */
+export type PathRoot<F extends Record<string, Field>> = {
+  readonly [K in keyof F & string]-?: PathNode<FieldValue<F[K]>>;
+};
+
+/** Recognize a {@link PathRef} at runtime (so `.on(...)`/`.key(...)` can coerce it). */
+export function isPathRef(v: unknown): v is PathRef {
+  return typeof v === "object" && v !== null && (v as { __isPathRef?: boolean }).__isPathRef === true;
+}
+
+/** Coerce a field spelling — a plain string OR a {@link PathRef} — to its dotted-string form.
+ *  This is the ONE point a typed path collapses to the string the rest of the pipeline sees. */
+export function pathString(field: string | PathRef): string {
+  return isPathRef(field) ? field.path : field;
+}
+
+/** The proxy node: carries its accumulated dotted path, deepens on any non-reserved property
+ *  access, and stringifies to the path. Reserved keys (`path`/`toString`/the brand) resolve on
+ *  the base so a subfield can never be named after them without ambiguity being caught here. */
+function makePathNode(path: string): PathRef {
+  const base = {
+    __isPathRef: true as const,
+    path,
+    toString(): string {
+      return path;
+    },
+  };
+  return new Proxy(base, {
+    get(target, prop, receiver) {
+      if (typeof prop === "symbol" || prop in target) {
+        return Reflect.get(target, prop, receiver);
+      }
+      const next = path === "" ? String(prop) : `${path}.${String(prop)}`;
+      return makePathNode(next);
+    },
+  }) as PathRef;
+}
+
+/**
+ * Begin a typed field PATH rooted at an aggregate. `path(EstateSite).location.point` descends the
+ * declared fields + value-object shapes (checked by tsc at every hop) and denotes the dotted string
+ * `"location.point"`. Pure sugar — pass the result to {@link spatial}'s `.on(...)` or {@link query}'s
+ * `.key(...)`, which coerce it to the identical string a hand-written spelling would produce.
+ */
+export function path<Id extends string, F extends Record<string, Field>>(
+  _aggregate: AggregateHandle<Id, F>,
+): PathRoot<F> {
+  return makePathNode("") as unknown as PathRoot<F>;
+}

package/src/query.ts

@@ -29,6 +29,12 @@
  */
 import type { AggregateHandle } from "./aggregate.js";
 import type { Field } from "./fields.js";
+import { pathString, type PathRef } from "./path.js";
+
+/** A key argument accepted by `.key(...)`: a plain (dotted) string OR a typed {@link PathRef}
+ *  (`path(Agg).location.point`). A PathRef is self-validating at construction, so it collapses to
+ *  its dotted string here and is exempt from the string-literal compatibility check below. */
+type KeyArg = string | PathRef;
 
 type StringKeyOf<T> = Extract<keyof T, string>;
 
@@ -47,12 +53,12 @@ export type QueryableFieldPath<F extends Record<string, Field>> =
   | `${JsonFieldKeys<F>}.${string}`;
 
 type QueryKeyCompatibility<
-  K extends readonly string[],
+  K extends readonly KeyArg[],
   F extends Record<string, Field>,
-> = Exclude<K[number], QueryableFieldPath<F>> extends never
+> = Exclude<Extract<K[number], string>, QueryableFieldPath<F>> extends never
   ? unknown
   : {
-      readonly __query_key_error__: `query key '${Exclude<K[number], QueryableFieldPath<F>>}' is not a field on returned aggregate`;
+      readonly __query_key_error__: `query key '${Exclude<Extract<K[number], string>, QueryableFieldPath<F>>}' is not a field on returned aggregate`;
     };
 
 /**
@@ -107,9 +113,10 @@ export function hasManyIndexes(agg: AggregateHandle): QueryDecl[] {
  * fixes the returned aggregate type and yields the finished {@link QueryDecl}) is
  * available. This is the ONLY shape carrying `.returns` — see {@link KeylessQuery}.
  */
-export interface Query<K extends readonly string[] = readonly string[]> {
+export interface Query<K extends readonly KeyArg[] = readonly KeyArg[]> {
   readonly id: string;
-  readonly key: readonly [...K];
+  /** The index key fields, coerced to their dotted-string form (a {@link PathRef} collapses to `.path`). */
+  readonly key: readonly string[];
   /**
    * Fix the aggregate TYPE this query returns, producing the finished declaration.
    * Takes a typed HANDLE (never the string id) — a typo'd handle is a compile
@@ -133,7 +140,7 @@ export interface KeylessQuery {
    * over. Order is significant (index column order) and is PRESERVED, never sorted.
    * Returns the registerable {@link Query} (the only shape exposing `.returns`).
    */
-  key<const K extends readonly [string, ...string[]]>(...fields: K): Query<K>;
+  key<const K extends readonly [KeyArg, ...KeyArg[]]>(...fields: K): Query<K>;
 }
 
 /**
@@ -144,9 +151,11 @@ export interface KeylessQuery {
 export function query<const Id extends string>(id: Id): KeylessQuery {
   return {
     id,
-    key<const K extends readonly [string, ...string[]]>(...fields: K): Query<K> {
-      // Preserve declared order — this list is the index's column order, not a set.
-      const keyFields = [...fields] as unknown as readonly [...K];
+    key<const K extends readonly [KeyArg, ...KeyArg[]]>(...fields: K): Query<K> {
+      // Preserve declared order — this list is the index's column order, not a set. A typed
+      // PathRef (`path(Agg).location.point`) collapses to its dotted string here, so the rest of
+      // the pipeline only ever sees strings (era-safe: byte-identical to the hand-written spelling).
+      const keyFields: readonly string[] = fields.map((f) => pathString(f as KeyArg));
       return {
         id,
         key: keyFields,

package/src/shape_compat.ts

@@ -179,6 +179,52 @@ export function domainInterface(mod: DomainModule, stableIds?: StableIds): Domai
   };
 }
 
+/** One member's structural verdict — `ok`, plus the exact break `reason` when not. */
+export interface MemberVerdict {
+  readonly ok: boolean;
+  readonly reason?: string;
+}
+
+/** PER-MEMBER structural verdict (#72b, the compat superpower): the SAME subtype relation as
+ *  {@link compatible}, decomposed to ONE verdict per callable MEMBER — keyed by directive id
+ *  (writes) AND by aggregate label (reads). A generated client method (or the CLI gate) consults
+ *  its own member so a KNOWN-incompatible call refuses CLIENT-SIDE, never as a server 422. */
+export function memberVerdicts(client: DomainInterface, workspace: DomainInterface): Record<string, MemberVerdict> {
+  const out: Record<string, MemberVerdict> = {};
+
+  // WRITES — contravariant, one verdict per directive the client calls.
+  for (const [did, cShape] of Object.entries(client.directives)) {
+    const wShape = workspace.directives[did];
+    if (!wShape) { out[did] = { ok: false, reason: `directive '${did}' is not installed on the workspace` }; continue; }
+    const reasons: string[] = [];
+    for (const [f, wf] of Object.entries(wShape.fields)) {
+      if (wf.optional) continue;
+      const cf = cShape.fields[f];
+      if (!cf || cf.optional) reasons.push(`workspace requires field '${f}' the client does not always send`);
+    }
+    for (const [f, cf] of Object.entries(cShape.fields)) {
+      const wf = wShape.fields[f];
+      if (wf && wf.kind !== cf.kind) reasons.push(`field '${f}' kind ${cf.kind} ≠ workspace ${wf.kind}`);
+    }
+    out[did] = reasons.length ? { ok: false, reason: reasons.join("; ") } : { ok: true };
+  }
+
+  // READS — covariant by stable id, one verdict per aggregate the client reads (keyed by LABEL).
+  for (const [sid, cAgg] of Object.entries(client.aggregates)) {
+    const wAgg = workspace.aggregates[sid];
+    if (!wAgg) { out[cAgg.label] = { ok: false, reason: `aggregate '${cAgg.label}' is not served by the workspace` }; continue; }
+    const reasons: string[] = [];
+    for (const [fsid, cf] of Object.entries(cAgg.fields)) {
+      const wf = wAgg.fields[fsid];
+      if (!wf) reasons.push(`field '${cAgg.label}.${cf.label}' is not served`);
+      else if (wf.kind !== cf.kind) reasons.push(`field '${cAgg.label}.${cf.label}' read kind ${cf.kind} ≠ workspace ${wf.kind}`);
+    }
+    out[cAgg.label] = reasons.length ? { ok: false, reason: reasons.join("; ") } : { ok: true };
+  }
+
+  return out;
+}
+
 /** Decide whether a CLIENT interface is satisfied by a WORKSPACE interface (the offer).
  *  Pure + deterministic — the SAME relation runs at connect() and (mirrored) at the
  *  editor/CI. Names the exact directive / aggregate / field at fault, never a hash. */

package/src/spatial.ts

@@ -36,6 +36,7 @@
  */
 import type { AggregateHandle } from "./aggregate.js";
 import type { Field } from "./fields.js";
+import { pathString, type PathRef } from "./path.js";
 
 type StringKeyOf<T> = Extract<keyof T, string>;
 
@@ -51,7 +52,8 @@ export interface SpatialDecl {
   /**
    * The aggregate's GeoJSON GEOMETRY field name — the SOURCE of the bounding box the
    * R\*Tree indexes (e.g. `geoPosition`). The engine reads this field per aggregate,
-   * computes its `[minLng,minLat,maxLng,maxLat]` bbox, and upserts the R\*Tree row.
+   * computes its axis-neutral `[minX,minY,maxX,maxY]` bbox (the geographic case being
+   * `[minLng,minLat,maxLng,maxLat]`), and upserts the R\*Tree row.
    */
   readonly on: string;
 }
@@ -79,7 +81,7 @@ export interface OfSpatial<F extends Record<string, Field> = Record<string, Fiel
    * 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> | `${StringKeyOf<F>}.${string}`): SpatialDecl;
+  on(field: StringKeyOf<F> | `${StringKeyOf<F>}.${string}` | PathRef): SpatialDecl;
 }
 
 /**
@@ -112,8 +114,10 @@ export function spatial<const Id extends string>(id: Id): TypelessSpatial {
       return {
         id,
         of: aggregate.id,
-        on(field: StringKeyOf<F>): SpatialDecl {
-          return { id, of: aggregate.id, on: field };
+        on(field: StringKeyOf<F> | `${StringKeyOf<F>}.${string}` | PathRef): SpatialDecl {
+          // A typed PathRef (`path(Agg).location.point`) collapses to its dotted string here — pure
+          // sugar, byte-identical to the hand-written spelling (the era-safety contract).
+          return { id, of: aggregate.id, on: pathString(field) };
         },
       };
     },