@githolon/dsl 0.1.0

package/src/codegen_usda.ts

@@ -0,0 +1,388 @@
+// 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}.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * TS → `.usda` — render a COMPILED DOMAIN as a real OpenUSD stage (Jack 2026-06-08).
+ *
+ * This is the ABSTRACT REPRESENTATION of the domain's LAW — for studying the holon as a maths object,
+ * NOT the org-data digital twin. The structure IS the scene. The sibling `emitDomainDot` renders the
+ * same structure as a 2D Graphviz graph; this renders it as a navigable 3D USD stage.
+ *
+ * It lays out the FULL NOMOS FLOW as a vertical stack, so the application reads top-to-bottom:
+ *
+ *     INTENTS        (Cone,    top)     — the dispatch boundary: the ONLY thing a client sends in.
+ *        │ dispatches
+ *     DIRECTIVES     (Cube,    upper)   — the sealed plan that computes events from intent payload + ports.
+ *        │ creates / mutates
+ *     AGGREGATES     (Sphere,  middle)  — the consistency boundaries / identity units the events fold
+ *        │ reads                          into; reference edges between them = the implicit *Id graph.
+ *     READ PROJECTIONS (Capsule, bottom) — the named, maintained reads back OUT: query/count/sum/
+ *                                          derived/combined.
+ *
+ * Aggregates sit on a CIRCLE in the ground plane; intents/directives float above their target, read
+ * projections hang below. Edges are thin `Cylinder` tubes (AR Quick Look renders meshes, not curves),
+ * coloured by kind via bound `UsdPreviewSurface` materials. The whole thing is re-centred so the
+ * CENTROID sits at the origin (the orbit pivot on spacebar), with an explicit `Camera` aimed there.
+ *
+ * PURE `DomainModule → string`, deterministic (sorted iteration; build-time trig only — no clock/rng),
+ * no file IO. Like `emitDomainDot` it is a PRESENTATION projection — NOT part of the domain identity.
+ */
+import type { Field } from "./fields.js";
+import type { DomainModule } from "./codegen_dart.js";
+
+export interface UsdaOptions {
+  /** Tube radius for the flow edges (stage units). Default 0.3. */
+  readonly edgeRadius?: number;
+}
+
+type Vec3 = readonly [number, number, number];
+const add = (a: Vec3, b: Vec3): Vec3 => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+const sub = (a: Vec3, b: Vec3): Vec3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const scale = (a: Vec3, s: number): Vec3 => [a[0] * s, a[1] * s, a[2] * s];
+const len = (a: Vec3): number => Math.sqrt(a[0] * a[0] + a[1] * a[1] + a[2] * a[2]);
+/** round to 4dp, drop −0 — deterministic, stable text. */
+const f = (n: number): string => `${Number(n.toFixed(4)) + 0}`;
+const v3 = (a: Vec3): string => `(${f(a[0])}, ${f(a[1])}, ${f(a[2])})`;
+
+const COLOR = {
+  aggregate: [0.2, 0.45, 0.85] as Vec3, // blue   — Sphere
+  directive: [0.95, 0.6, 0.15] as Vec3, // orange — Cube
+  intent: [0.6, 0.3, 0.8] as Vec3, // purple — Cone (dispatch boundary)
+  projection: [0.25, 0.7, 0.55] as Vec3, // teal-green — Capsule (read-out)
+  creates: [0.25, 0.75, 0.35] as Vec3, // green     — directive→aggregate (create)
+  mutates: [0.9, 0.45, 0.2] as Vec3, // orange-red — directive→aggregate (mutate)
+  ref: [0.4, 0.75, 0.8] as Vec3, // teal      — aggregate→aggregate reference
+  intentEdge: [0.72, 0.55, 0.92] as Vec3, // light purple — intent→directive
+  readEdge: [0.85, 0.78, 0.35] as Vec3, // yellow    — aggregate→projection
+};
+type ColorKey = keyof typeof COLOR;
+
+/** USD triple-quoted string literal (carries newlines + quotes faithfully for a `plan` body). */
+function usdString3(s: string): string {
+  return `"""${s.replace(/"""/g, '\\"\\"\\"')}"""`;
+}
+
+/** A `UsdPreviewSurface` material so the colour survives in AR Quick Look (RealityKit ignores displayColor). */
+function material(matPath: string, color: Vec3): string {
+  return [
+    `        def Material "${matPath.split("/").pop()}"`,
+    `        {`,
+    `            token outputs:surface.connect = <${matPath}/surface.outputs:surface>`,
+    `            def Shader "surface"`,
+    `            {`,
+    `                uniform token info:id = "UsdPreviewSurface"`,
+    `                color3f inputs:diffuseColor = ${v3(color)}`,
+    `                float inputs:metallic = 0`,
+    `                float inputs:roughness = 0.55`,
+    `                token outputs:surface`,
+    `            }`,
+    `        }`,
+  ].join("\n");
+}
+
+/** Infer the aggregate a `*Id`/`*Ids` field points at: strip the suffix, match an aggregate id (ci). */
+function inferRefTarget(fieldName: string, aggIdByLower: Map<string, string>): string | undefined {
+  const base = fieldName.replace(/Ids?$/, "");
+  if (base === fieldName) return undefined; // no Id/Ids suffix → not a reference field
+  return aggIdByLower.get(base.toLowerCase());
+}
+
+/** A read projection normalized for rendering: which aggregate it reads, its kind, optional 2nd read. */
+interface Proj {
+  readonly id: string;
+  readonly kind: string;
+  readonly of: string;
+  readonly reads?: string;
+}
+
+/** Collect the domain's declared read projections (queries/counts/sums/deriveds/combineds). */
+function projectionsOf(mod: DomainModule): Proj[] {
+  const m = mod as unknown as Record<string, unknown[]>;
+  const out: Proj[] = [];
+  const id = (p: unknown) => String((p as { id: string }).id);
+  for (const q of (m.queries ?? []) as { id: string; returns: string }[]) out.push({ id: id(q), kind: "query", of: q.returns });
+  for (const c of (m.counts ?? []) as { of: string }[]) out.push({ id: id(c), kind: "count", of: c.of });
+  for (const s of (m.sums ?? []) as { of: string }[]) out.push({ id: id(s), kind: "sum", of: s.of });
+  for (const d of (m.deriveds ?? []) as { of: string }[]) out.push({ id: id(d), kind: "derived", of: d.of });
+  for (const cb of (m.combineds ?? []) as { of: string; reads?: string }[])
+    out.push({ id: id(cb), kind: "combined", of: cb.of, ...(cb.reads ? { reads: cb.reads } : {}) });
+  return out.sort((x, y) => x.id.localeCompare(y.id));
+}
+
+/** Render a compiled domain as a real `.usda` stage (the full nomos flow, laid out for legibility). */
+export function emitDomainUsda(mod: DomainModule, opts: UsdaOptions = {}): string {
+  const edgeRadius = opts.edgeRadius ?? 0.3;
+  const aggregates = [...mod.aggregates].sort((x, y) => x.id.localeCompare(y.id));
+  const directives = [...mod.directives].sort((x, y) => x.id.localeCompare(y.id));
+  const projections = projectionsOf(mod);
+  const safe = (s: string) => s.replace(/[^A-Za-z0-9_]/g, "_");
+  const domainPath = `/Domain_${safe(mod.name)}`;
+  const matPath = (key: ColorKey) => `${domainPath}/Materials/Mat_${key}`;
+
+  const N = Math.max(aggregates.length, 1);
+  const R = Math.max(7, N * 1.7); // ring radius — grows with the aggregate count
+
+  // ── aggregate positions: a circle in the ground (XZ) plane ──
+  const aggPos = new Map<string, Vec3>();
+  const aggAngle = new Map<string, number>();
+  aggregates.forEach((a, i) => {
+    const θ = (2 * Math.PI * i) / N;
+    aggPos.set(a.id, [R * Math.cos(θ), 0, R * Math.sin(θ)]);
+    aggAngle.set(a.id, θ);
+  });
+  const dirOf = (target: string): { outward: Vec3; tangent: Vec3; base: Vec3 } | undefined => {
+    const base = aggPos.get(target);
+    const θ = aggAngle.get(target);
+    if (!base || θ === undefined) return undefined;
+    return { base, outward: [Math.cos(θ), 0, Math.sin(θ)], tangent: [-Math.sin(θ), 0, Math.cos(θ)] };
+  };
+
+  // group directives + projections by the aggregate they touch (for tangential fanning)
+  const groupBy = <T>(items: T[], key: (t: T) => string): Map<string, T[]> => {
+    const g = new Map<string, T[]>();
+    for (const it of items) (g.get(key(it)) ?? g.set(key(it), []).get(key(it))!).push(it);
+    return g;
+  };
+
+  // ── directive positions: above the target aggregate (y=+7), fanned tangentially ──
+  const dirPos = new Map<string, Vec3>();
+  for (const [target, ids] of groupBy(directives, (d) => d.aggregateId)) {
+    const g = dirOf(target);
+    ids.forEach((d, j) => {
+      const spread = (j - (ids.length - 1) / 2) * 3;
+      dirPos.set(
+        d.id,
+        g ? add(add(add(g.base, scale(g.outward, 3)), [0, 7, 0]), scale(g.tangent, spread)) : [0, 7, 0],
+      );
+    });
+  }
+  // ── intent positions: one per directive (the dispatch front-door), 4.5 above its directive ──
+  const intentPos = new Map<string, Vec3>();
+  for (const d of directives) intentPos.set(d.id, add(dirPos.get(d.id)!, [0, 4.5, 0]));
+
+  // ── projection positions: below the target aggregate (y=−7), fanned tangentially + outward ──
+  const projPos = new Map<string, Vec3>();
+  for (const [target, projs] of groupBy(projections, (p) => p.of)) {
+    const g = dirOf(target);
+    projs.forEach((p, j) => {
+      const spread = (j - (projs.length - 1) / 2) * 3;
+      projPos.set(
+        p.id,
+        g ? add(add(add(g.base, scale(g.outward, 4)), [0, -7, 0]), scale(g.tangent, spread)) : [0, -7, 0],
+      );
+    });
+  }
+
+  // ── centre the whole thing so the CENTROID is at the origin (the orbit pivot) ──
+  const all: Vec3[] = [...aggPos.values(), ...dirPos.values(), ...intentPos.values(), ...projPos.values()];
+  const centroid: Vec3 = all.length
+    ? scale(all.reduce<Vec3>((acc, p) => add(acc, p), [0, 0, 0]), 1 / all.length)
+    : [0, 0, 0];
+  const off = (p: Vec3): Vec3 => sub(p, centroid);
+
+  const aggIdByLower = new Map<string, string>();
+  for (const a of aggregates) aggIdByLower.set(a.id.toLowerCase(), a.id);
+
+  // ── a thin Cylinder mesh spanning p0→p1 (an edge), oriented + coloured + material-bound ──
+  const edgeTube = (name: string, p0: Vec3, p1: Vec3, radius: number, key: ColorKey): string => {
+    const d = sub(p1, p0);
+    const L = len(d);
+    const mid = scale(add(p0, p1), 0.5);
+    let q: readonly [number, number, number, number] = [1, 0, 0, 0]; // (w, x, y, z) rotate +Z → edge dir
+    if (L >= 1e-9) {
+      const u: Vec3 = [d[0] / L, d[1] / L, d[2] / L];
+      const dot = u[2];
+      if (dot < -0.999999) q = [0, 1, 0, 0];
+      else if (dot <= 0.999999) {
+        const ax = -u[1];
+        const ay = u[0];
+        const an = Math.sqrt(ax * ax + ay * ay);
+        const angle = Math.acos(dot);
+        const s = Math.sin(angle / 2);
+        q = [Math.cos(angle / 2), (ax / an) * s, (ay / an) * s, 0];
+      }
+    }
+    return [
+      `        def Cylinder "${name}" (`,
+      `            prepend apiSchemas = ["MaterialBindingAPI"]`,
+      `        )`,
+      `        {`,
+      `            uniform token axis = "Z"`,
+      `            double radius = ${radius}`,
+      `            double height = ${f(L)}`,
+      `            double3 xformOp:translate = ${v3(mid)}`,
+      `            quatd xformOp:orient = (${f(q[0])}, ${f(q[1])}, ${f(q[2])}, ${f(q[3])})`,
+      `            uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:orient"]`,
+      `            color3f[] primvars:displayColor = [${v3(COLOR[key])}]`,
+      `            rel material:binding = <${matPath(key)}>`,
+      `        }`,
+    ].join("\n");
+  };
+
+  // ── a Gprim node (Sphere/Cube/Cone/Capsule) at a position, coloured + material-bound + metadata ──
+  const node = (kind: string, name: string, sizeAttrs: string[], pos: Vec3, key: ColorKey, meta: string[]): string =>
+    [
+      `        def ${kind} "${safe(name)}" (`,
+      `            prepend apiSchemas = ["MaterialBindingAPI"]`,
+      `        )`,
+      `        {`,
+      ...sizeAttrs.map((s) => `            ${s}`),
+      `            double3 xformOp:translate = ${v3(pos)}`,
+      `            uniform token[] xformOpOrder = ["xformOp:translate"]`,
+      `            color3f[] primvars:displayColor = [${v3(COLOR[key])}]`,
+      `            rel material:binding = <${matPath(key)}>`,
+      ...meta.map((s) => `            ${s}`),
+      `        }`,
+    ].join("\n");
+
+  const lines: string[] = [];
+  lines.push(`#usda 1.0`);
+  lines.push(`(`);
+  lines.push(`    doc = "Nomos compiled domain '${mod.name}' — abstract law structure (holon-maths projection)"`);
+  lines.push(`    defaultPrim = "Domain_${safe(mod.name)}"`);
+  lines.push(`    metersPerUnit = 1`);
+  lines.push(`    upAxis = "Y"`);
+  lines.push(`)`);
+  lines.push(``);
+  lines.push(`def Xform "Domain_${safe(mod.name)}"`);
+  lines.push(`{`);
+
+  // ── MATERIALS — one UsdPreviewSurface per colour so AR Quick Look shows them ──
+  lines.push(`    def Scope "Materials"`);
+  lines.push(`    {`);
+  for (const key of Object.keys(COLOR) as ColorKey[]) lines.push(material(matPath(key), COLOR[key]));
+  lines.push(`    }`);
+
+  // ── INTENTS — Cone prims (the dispatch boundary); one per directive ──
+  lines.push(`    def Scope "Intents"`);
+  lines.push(`    {`);
+  for (const d of directives) {
+    lines.push(
+      node(
+        "Cone",
+        `${d.id}Intent`,
+        [`uniform token axis = "Y"`, `double height = 2`, `double radius = 0.9`],
+        off(intentPos.get(d.id)!),
+        "intent",
+        [
+          `custom string nomos:kind = "intent"`,
+          `rel nomos:dispatches = <${domainPath}/Directives/${safe(d.id)}>`,
+        ],
+      ),
+    );
+  }
+  lines.push(`    }`);
+
+  // ── AGGREGATE TYPES — Sphere prims (the consistency boundaries / identity units) ──
+  lines.push(`    def Scope "Aggregates"`);
+  lines.push(`    {`);
+  for (const a of aggregates) {
+    const fields = Object.keys(a.fields as Record<string, Field>).sort();
+    const hasInv = Boolean((a as unknown as { invariant?: unknown }).invariant);
+    lines.push(
+      node("Sphere", a.id, [`double radius = 1.2`], off(aggPos.get(a.id)!), "aggregate", [
+        `custom string nomos:kind = "aggregate"`,
+        `custom string[] nomos:fields = [${fields.map((x) => `"${x}"`).join(", ")}]`,
+        `custom bool nomos:hasAggregateInvariant = ${hasInv ? "true" : "false"}`,
+      ]),
+    );
+  }
+  lines.push(`    }`);
+
+  // ── DIRECTIVES — Cube prims (the write transitions), each carrying its `plan` lump ──
+  lines.push(`    def Scope "Directives"`);
+  lines.push(`    {`);
+  for (const d of directives) {
+    const planSrc = String((d as unknown as { plan: unknown }).plan ?? "");
+    lines.push(
+      node("Cube", d.id, [`double size = 1.6`], off(dirPos.get(d.id)!), "directive", [
+        `custom string nomos:kind = "directive"`,
+        `custom string nomos:marker = "${d.marker}"`,
+        `rel nomos:target = <${domainPath}/Aggregates/${safe(d.aggregateId)}>`,
+        `custom string nomos:plan = ${usdString3(planSrc)}`,
+      ]),
+    );
+  }
+  lines.push(`    }`);
+
+  // ── READ PROJECTIONS — Capsule prims (the maintained reads back out) ──
+  lines.push(`    def Scope "Projections"`);
+  lines.push(`    {`);
+  for (const p of projections) {
+    const meta = [
+      `custom string nomos:kind = "projection"`,
+      `custom string nomos:projectionKind = "${p.kind}"`,
+      `rel nomos:reads = <${domainPath}/Aggregates/${safe(p.of)}>`,
+    ];
+    if (p.reads) meta.push(`rel nomos:reads2 = <${domainPath}/Aggregates/${safe(p.reads)}>`);
+    lines.push(
+      node(
+        "Capsule",
+        `${p.id}__${p.kind}`,
+        [`uniform token axis = "Z"`, `double height = 1.4`, `double radius = 0.7`],
+        off(projPos.get(p.id)!),
+        "projection",
+        meta,
+      ),
+    );
+  }
+  lines.push(`    }`);
+
+  // ── THE FLOW — Cylinder tubes wiring the four layers together ──
+  lines.push(`    def Scope "Flow"`);
+  lines.push(`    {`);
+  // intent → directive
+  for (const d of directives)
+    lines.push(edgeTube(`${safe(d.id)}Intent__dispatches__${safe(d.id)}`, off(intentPos.get(d.id)!), off(dirPos.get(d.id)!), edgeRadius * 0.7, "intentEdge"));
+  // directive →(marker)→ aggregate
+  for (const d of directives) {
+    const to = aggPos.get(d.aggregateId);
+    if (!to) continue;
+    const key: ColorKey = d.marker === "mutates" ? "mutates" : "creates";
+    lines.push(edgeTube(`${safe(d.id)}__${d.marker}__${safe(d.aggregateId)}`, off(dirPos.get(d.id)!), off(to), edgeRadius, key));
+  }
+  // aggregate →ref→ aggregate (declared refAggregateId OR inferred *Id/*Ids)
+  const drawnRef = new Set<string>();
+  for (const a of aggregates) {
+    const from = aggPos.get(a.id)!;
+    for (const [fname, fld] of Object.entries(a.fields as Record<string, Field>)) {
+      const declared = (fld as unknown as { refAggregateId?: string }).refAggregateId;
+      const target = declared ?? inferRefTarget(fname, aggIdByLower);
+      if (!target || target === a.id) continue;
+      const to = aggPos.get(target);
+      const k = `${a.id}->${target}`;
+      if (!to || drawnRef.has(k)) continue;
+      drawnRef.add(k);
+      lines.push(edgeTube(`${safe(a.id)}__ref__${safe(target)}`, off(from), off(to), edgeRadius * 0.7, "ref"));
+    }
+  }
+  // aggregate →read→ projection
+  for (const p of projections) {
+    const from = aggPos.get(p.of);
+    if (from) lines.push(edgeTube(`${safe(p.of)}__read__${safe(p.id)}_${p.kind}`, off(from), off(projPos.get(p.id)!), edgeRadius * 0.7, "readEdge"));
+    const from2 = p.reads ? aggPos.get(p.reads) : undefined;
+    if (from2) lines.push(edgeTube(`${safe(p.reads!)}__read__${safe(p.id)}_${p.kind}`, off(from2), off(projPos.get(p.id)!), edgeRadius * 0.7, "readEdge"));
+  }
+  lines.push(`    }`);
+
+  lines.push(`}`);
+
+  // ── an explicit camera aimed at the centroid (origin), so non-Quick-Look viewers frame it too ──
+  const h = R * 0.7;
+  const dist = R * 2.6;
+  const pitch = -(Math.atan2(h, dist) * 180) / Math.PI;
+  lines.push(``);
+  lines.push(`def Camera "centroidCamera"`);
+  lines.push(`{`);
+  lines.push(`    float focalLength = 35`);
+  lines.push(`    float horizontalAperture = 36`);
+  lines.push(`    float2 clippingRange = (0.1, ${f(dist * 3)})`);
+  lines.push(`    double3 xformOp:translate = (0, ${f(h)}, ${f(dist)})`);
+  lines.push(`    double xformOp:rotateX = ${f(pitch)}`);
+  lines.push(`    uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateX"]`);
+  lines.push(`}`);
+
+  return lines.join("\n") + "\n";
+}

package/src/combined.ts

@@ -0,0 +1,195 @@
+// 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.
+
+/**
+ * `combined(id)` builder — an ENGINE-PROJECTED, CROSS-AGGREGATE read field
+ * (read-engine: combined read fields). The "combine data" capability: a read that
+ * JOINS one aggregate to a RELATED one and materialises the composed value on the
+ * owner's row.
+ *
+ * READ-CLOSURE, the JOIN half. A {@link query} declares a NAMED, INDEXED set read; a
+ * {@link count} a NAMED, MAINTAINED tally; a `derived` a NAMED, PURE FUNCTION of ONE
+ * aggregate's folded fields; a `combined` declares a NAMED field computed from the
+ * owner aggregate AND a RELATED one reached by a typed REF edge (e.g. `Building.siteName
+ * = the parent Site's name`). Like `derived`, the value is NEVER stamped into a kernel
+ * op/event — it is computed BY THE ENGINE during the projection projection and stored
+ * ONLY in the read model, so on a re-fold it is always re-derivable. UNLIKE `derived`,
+ * the engine eval is fed the related aggregate's folded `data` (resolved by the owner's
+ * ref id) via the SAME query-port path a report's `.render` consumes — so the compose fn
+ * is `(owner, related) => value`.
+ *
+ * ── The CROSS-AGGREGATE INVALIDATION axis (the hard part this primitive declares) ──
+ * A combined field on aggregate A that reads aggregate B must be RECOMPUTED when B
+ * changes — not only when A changes. The declaration therefore names the QUERIED type
+ * (`reads`): the read engine recomputes every owner-A's combined field whenever a
+ * projection delta touches an aggregate of that queried type. The compose fn body
+ * (`.as(...)`) is executable behaviour — it ships in the engine bundle and is NOT hashed
+ * into the domain identity (the same rule `derived`'s `.as` / directives' `.plan` follow).
+ *
+ * The TYPE-STATE mirrors {@link derived}: `combined(id)` yields a {@link TypelessCombined}
+ * whose ONLY method is `.of(...)`; `.of(...)` yields a {@link CombinedOf} whose ONLY
+ * method is `.joins(...)`; `.joins(...)` yields a {@link CombinedJoins} carrying `.as`;
+ * the finished {@link CombinedDecl} is produced solely by `.as(...)`. So a combined field
+ * with no owner-type, no join edge, or no compose fn cannot be CONSTRUCTED — "every
+ * combined field names the owner it lives on, the ref edge it joins through, the type it
+ * queries, AND a compose fn" is a type-level property, before any runtime check.
+ */
+import type { z } from "zod";
+import type { AggregateHandle } from "./aggregate.js";
+
+/**
+ * The compose function: maps the OWNER aggregate's folded fields (`owner`, a plain JSON
+ * object — the projection's projected `data` for it) and the RELATED aggregate's folded
+ * fields (`related`, the queried aggregate's `data`, or `undefined` when the ref is unset
+ * / the related aggregate is absent or archived) to the combined value. MUST be pure (no
+ * ports, no I/O): the engine runs it over the host-fed `owner` (`priorState`) + `related`
+ * (a query-port row) and stores the result verbatim into the read model. The value is any
+ * JSON-serialisable scalar / object the read schema can decode (the smallest-first target
+ * is a parent-name `string`).
+ */
+export type CombineFn = (
+  owner: Record<string, unknown>,
+  related: Record<string, unknown> | undefined,
+) => unknown;
+
+/**
+ * A FINISHED combined-field declaration (the read engine's input shape, mirroring {@link
+ * DerivedDecl} but with the JOIN axis): an id (the stored projection field name), the
+ * OWNER aggregate TYPE (`of`), the REF FIELD on the owner that points at the related
+ * aggregate (`refField`), the RELATED aggregate TYPE the read QUERIES (`reads` — the
+ * invalidation trigger), and the pure compose `fn`.
+ */
+export interface CombinedDecl {
+  /** The combined field's NAME — the key the read model stores it under. */
+  readonly id: string;
+  /** The OWNER aggregate TYPE id the field lives on, e.g. `BuildingAggregate`. */
+  readonly of: string;
+  /** The owner's REF FIELD whose value is the related aggregate's id, e.g. `siteId`. */
+  readonly refField: string;
+  /** The RELATED aggregate TYPE the field reads (the cross-aggregate invalidation key),
+   *  e.g. `SiteRootAggregate`. A delta touching this type recomputes every owner's field. */
+  readonly reads: string;
+  /** The JSON value schema the engine-projected field returns. */
+  readonly returns: z.ZodTypeAny;
+  /** The pure compose fn `(owner, related) => value`. */
+  readonly fn: CombineFn;
+}
+
+/**
+ * The {@link CombinedJoins} BUILDER: it has named its owner-type AND its join edge, so
+ * `.as(...)` (which fixes the compose fn and yields the finished {@link CombinedDecl}) is
+ * available. This is the ONLY shape carrying `.as` — see {@link TypelessCombined}.
+ */
+export interface CombinedJoins {
+  readonly id: string;
+  readonly of: string;
+  readonly refField: string;
+  readonly reads: string;
+  /**
+   * Declare the projected value schema. A combined field without a return schema is not a
+   * read contract, because the read model/Dart surface would have to guess.
+   */
+  returns(schema: z.ZodTypeAny): CombinedReturns;
+}
+
+/**
+ * The {@link CombinedReturns} BUILDER: it has named owner, join edge, related type, AND
+ * value schema, so `.as(...)` can fix the executable body and yield the finished decl.
+ */
+export interface CombinedReturns {
+  readonly id: string;
+  readonly of: string;
+  readonly refField: string;
+  readonly reads: string;
+  /** The JSON value schema the engine-projected field returns. */
+  readonly returns: z.ZodTypeAny;
+  /**
+   * Fix the PURE compose fn, producing the finished declaration. The fn receives the
+   * owner's folded fields AND the related aggregate's folded fields and returns the value.
+   */
+  as(fn: CombineFn): CombinedDecl;
+}
+
+/**
+ * The {@link CombinedOf} BUILDER: it has named its owner-type, so `.joins(...)` (which
+ * names the REF FIELD + the related aggregate TYPE) is available. It deliberately has NO
+ * `.as` — the join edge is a prerequisite, not optional.
+ */
+export interface CombinedOf {
+  readonly id: string;
+  readonly of: string;
+  /**
+   * Declare the JOIN: the owner's REF FIELD (`refField`, whose value is the related
+   * aggregate's id) AND the RELATED aggregate TYPE this field reads (a typed HANDLE —
+   * never a string id, so a typo'd related type is a compile error). The related type is
+   * carried as the CROSS-AGGREGATE INVALIDATION key. Returns the {@link CombinedJoins}
+   * builder (the only shape exposing `.as`).
+   */
+  joins(refField: string, related: AggregateHandle): CombinedJoins;
+}
+
+/**
+ * The INITIAL, un-typed combined field — its ONLY method is `.of(...)`. It deliberately
+ * has NO `.joins`/`.as` and is not a {@link CombinedDecl}, so skipping the owner-type is a
+ * COMPILE error and a type-less combined field cannot be constructed. THIS is the
+ * type-level "every combined field names the owner it lives on" property.
+ */
+export interface TypelessCombined {
+  readonly id: string;
+  /**
+   * Declare the OWNER aggregate TYPE this field lives on. Takes a typed HANDLE (never the
+   * string id) — a typo'd handle is a compile error, the same convention as `derived`'s
+   * `.of(...)`. Returns the {@link CombinedOf} builder.
+   */
+  of(aggregate: AggregateHandle): CombinedOf;
+}
+
+/**
+ * Begin a combined-field declaration. Returns a {@link TypelessCombined}: until `.of(...)`
+ * then `.joins(...)` are called, neither `.as` nor a usable declaration exists — the
+ * owner-type AND the join edge are prerequisites, not optional.
+ */
+export function combined<const Id extends string>(id: Id): TypelessCombined {
+  return {
+    id,
+    of(aggregate: AggregateHandle): CombinedOf {
+      const ofType = aggregate.id;
+      return {
+        id,
+        of: ofType,
+        joins(refField: string, related: AggregateHandle): CombinedJoins {
+          const readsType = related.id;
+          return {
+            id,
+            of: ofType,
+            refField,
+            reads: readsType,
+            returns(schema: z.ZodTypeAny): CombinedReturns {
+              return {
+                id,
+                of: ofType,
+                refField,
+                reads: readsType,
+                returns: schema,
+                as(fn: CombineFn): CombinedDecl {
+                  return {
+                    id,
+                    of: ofType,
+                    refField,
+                    reads: readsType,
+                    returns: schema,
+                    fn,
+                  };
+                },
+              };
+            },
+          };
+        },
+      };
+    },
+  };
+}