@githolon/dsl 0.2.2 → 0.3.0

package/src/workspace_type.ts

@@ -0,0 +1,609 @@
+// 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.
+
+/**
+ * `workspaceType(...)` — FIRST-CLASS WORKSPACE TYPES, the tenant DSL surface
+ * (`architecture/workspace_types_and_sharding.md`, §10 RATIFIED; slice 1).
+ *
+ * A workspace type is a law-declared node kind in the workspace tree — the
+ * genericization of the hand-written governance taxonomy (`framework/workspaces.ts`
+ * `CloudWorkspace.kind: "workspace" | "platform"`, `birthPlatform`, pools, `cap(n)`)
+ * into a feature any tenant declares. IMPORTED FROM THE SUBPATH
+ * `@githolon/dsl/workspace-type` — NOT the runtime barrel: the barrel is bundled
+ * into every tenant's engine lump, and a taxonomy-free domain's package bytes must
+ * not move (the hash-stability law; the `build-package` precedent). The decls are
+ * COMPILE-LANE — manifest lowering, the homing walk, and the derived birth lanes
+ * consume them; the sealed engine never does:
+ *
+ *     import { workspaceType } from "@githolon/dsl/workspace-type";
+ *
+ *     export const EstateWs = workspaceType("estate")
+ *       .root(Estate)                  // exactly one Estate aggregate per instance
+ *       .hasMany(() => SiteHome)       // the taxonomy: an Estate has Sites
+ *       .global(Catalogue);            // estate-wide reference data
+ *
+ *     export const SiteHome = workspaceType("site")
+ *       .root(Site)
+ *       .packed();                     // the shard axis (vs .dedicated())
+ *
+ * Everything else is DERIVED — Jack's ratified requirement is a FULLY TYPESAFE
+ * surface: a domain dev NEVER sees or manages a compound key. Homing is derived
+ * from the aggregates' existing `t.ref` chains (zero annotation); birth lanes are
+ * derived from `hasMany` over the EXISTING platform machinery
+ * (`POST /v1/platforms/...` — derived, never forked); minted-id home keys are
+ * internal plumbing (slice 2).
+ *
+ * THE HOMING WALK (this file): `home(aggregate)` = the NEAREST PACKED AXIS its
+ * `t.ref` chain reaches (`TrackableAsset.siteId → Site` ⇒ assets home on their
+ * site; `Room → Building → Site` transitively). An aggregate whose chain stops at
+ * a dedicated root homes on that root's type (the coordinator). FAIL-CLOSED, with
+ * named remedies:
+ *   * no path to any axis            → compile error (give it a ref / `.global(...)`
+ *                                      / `.coordinatorLocal(...)`);
+ *   * ambiguous nearest axis         → compile error (pin it, or break a ref chain);
+ *   * a directive whose declared surface (target + `.reads(...)`) spans two homes
+ *                                    → compile error (model it as the Order/Receipt
+ *                                      PR pair — `cross_workspace.md`).
+ *
+ * MANIFEST LOWERING (`manifest.ts` calls {@link canonicalWorkspaceTypesFragment}):
+ * the taxonomy AND the derived homing table are HASH-BEARING law — and OMITTED
+ * ENTIRELY when the domain declares no workspace type, so a taxonomy-free domain
+ * is byte-identical in the canonical manifest to before this feature existed
+ * (the `cap(n)` discipline; guestbook + co2 hashes PROVEN unmoved).
+ */
+import type { AggregateHandle } from "./aggregate.js";
+import type { Directive } from "./directive.js";
+
+/** A directive of any payload type (`Directive<P>` is invariant in `P` — same alias
+ * convention as `codegen_dart.ts`). */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyDirective = Directive<any>;
+
+/** How a workspace type's instances are hosted: one holon each, or packed into shards. */
+export type WorkspaceTypeMode = "dedicated" | "packed";
+
+/** A child reference — the decl itself, or a thunk for forward/circular declaration order. */
+export type WorkspaceTypeRef = WorkspaceTypeDecl | (() => WorkspaceTypeDecl);
+
+/**
+ * One declared workspace type. Chainable + immutable (every method returns a NEW
+ * decl), and discoverable by SHAPE at any stage via `__isWorkspaceType` — the same
+ * duck-typing discipline as `AggregateHandle`/`Directive`. Validation (a missing
+ * `.root`, a packed type with children, …) is FAIL-CLOSED at compile/lowering,
+ * never silently defaulted.
+ */
+export interface WorkspaceTypeDecl {
+  /** Brand for by-shape discovery (compile auto-discovery, like aggregates). */
+  readonly __isWorkspaceType: true;
+  /** The type's id — instance workspace names are composed from it by the lanes. */
+  readonly id: string;
+  /** The ROOT aggregate: exactly one instance per workspace of this type. */
+  readonly rootAggregate?: AggregateHandle;
+  /** `dedicated` (one holon per instance — default) or `packed` (the shard axis). */
+  readonly mode: WorkspaceTypeMode;
+  /** The taxonomy's `hasMany` edges (child workspace types). */
+  readonly childRefs: readonly WorkspaceTypeRef[];
+  /** Reference data homed HERE and replicated to descendant shards (slice 4 lane). */
+  readonly globalAggregates: readonly AggregateHandle[];
+  /** Aggregates PINNED to this (coordinator) type — the no-path named remedy. */
+  readonly coordinatorLocalAggregates: readonly AggregateHandle[];
+  /** The pool: how many live children this type's instances may parent. */
+  readonly poolSize?: number;
+  /** The law-declared instance limit for this type (the `cap(n)` discipline). */
+  readonly capCount?: number;
+  /** Declare the root aggregate (required — validated fail-closed at compile). */
+  root(agg: AggregateHandle): WorkspaceTypeDecl;
+  /** Declare a `hasMany` child type (the taxonomy edge a birth lane derives from). */
+  hasMany(child: WorkspaceTypeRef): WorkspaceTypeDecl;
+  /** Mark instances PACKED into shard holons (the shard axis). */
+  packed(): WorkspaceTypeDecl;
+  /** Mark instances DEDICATED (one holon each — the default, explicit form). */
+  dedicated(): WorkspaceTypeDecl;
+  /** Declare reference-data aggregates homed here, replicated to descendant shards. */
+  global(...aggs: AggregateHandle[]): WorkspaceTypeDecl;
+  /** PIN aggregates to this type (the named remedy for a no-path/ambiguous home). */
+  coordinatorLocal(...aggs: AggregateHandle[]): WorkspaceTypeDecl;
+  /** Declare the child pool (quota law: how many live children instances may parent). */
+  pool(n: number): WorkspaceTypeDecl;
+  /** Declare the instance cap (law-declared instance limit, like aggregate `cap`). */
+  cap(n: number): WorkspaceTypeDecl;
+}
+
+interface WorkspaceTypeState {
+  readonly id: string;
+  readonly rootAggregate?: AggregateHandle;
+  readonly mode: WorkspaceTypeMode;
+  readonly childRefs: readonly WorkspaceTypeRef[];
+  readonly globalAggregates: readonly AggregateHandle[];
+  readonly coordinatorLocalAggregates: readonly AggregateHandle[];
+  readonly poolSize?: number;
+  readonly capCount?: number;
+}
+
+function makeWorkspaceType(state: WorkspaceTypeState): WorkspaceTypeDecl {
+  return {
+    __isWorkspaceType: true,
+    ...state,
+    root(agg: AggregateHandle): WorkspaceTypeDecl {
+      return makeWorkspaceType({ ...state, rootAggregate: agg });
+    },
+    hasMany(child: WorkspaceTypeRef): WorkspaceTypeDecl {
+      return makeWorkspaceType({ ...state, childRefs: [...state.childRefs, child] });
+    },
+    packed(): WorkspaceTypeDecl {
+      return makeWorkspaceType({ ...state, mode: "packed" });
+    },
+    dedicated(): WorkspaceTypeDecl {
+      return makeWorkspaceType({ ...state, mode: "dedicated" });
+    },
+    global(...aggs: AggregateHandle[]): WorkspaceTypeDecl {
+      return makeWorkspaceType({
+        ...state,
+        globalAggregates: [...state.globalAggregates, ...aggs],
+      });
+    },
+    coordinatorLocal(...aggs: AggregateHandle[]): WorkspaceTypeDecl {
+      return makeWorkspaceType({
+        ...state,
+        coordinatorLocalAggregates: [...state.coordinatorLocalAggregates, ...aggs],
+      });
+    },
+    pool(n: number): WorkspaceTypeDecl {
+      if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`workspaceType '${state.id}': pool must be a positive integer (got ${n})`);
+      }
+      return makeWorkspaceType({ ...state, poolSize: n });
+    },
+    cap(n: number): WorkspaceTypeDecl {
+      if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`workspaceType '${state.id}': cap must be a positive integer (got ${n})`);
+      }
+      return makeWorkspaceType({ ...state, capCount: n });
+    },
+  };
+}
+
+/**
+ * Declare a workspace type. The id must be a lawful workspace-name segment
+ * (instances ride the existing `p--ws` name composition), so the same shape the
+ * cloud's name law accepts — and never `--`, the composer's reserved separator.
+ */
+export function workspaceType(id: string): WorkspaceTypeDecl {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(id) || id.includes("--")) {
+    throw new Error(
+      `workspaceType '${id}': the id must start alphanumeric and use only letters, ` +
+        `digits, '-' and '_' (it seeds instance workspace names), and must not ` +
+        `contain '--' (the reserved name-composition separator). Rename the type.`,
+    );
+  }
+  return makeWorkspaceType({
+    id,
+    mode: "dedicated",
+    childRefs: [],
+    globalAggregates: [],
+    coordinatorLocalAggregates: [],
+  });
+}
+
+// ── resolution ────────────────────────────────────────────────────────────────────
+
+/** One RESOLVED workspace type: thunks forced, aggregates reduced to wire ids. */
+export interface ResolvedWorkspaceType {
+  readonly id: string;
+  readonly rootId: string;
+  readonly mode: WorkspaceTypeMode;
+  readonly childIds: readonly string[];
+  readonly globalIds: readonly string[];
+  readonly coordinatorLocalIds: readonly string[];
+  readonly poolSize?: number;
+  readonly capCount?: number;
+}
+
+/**
+ * Resolve a set of declared workspace types into the closed taxonomy: force child
+ * thunks (forward refs), union in referenced child decls, dedupe by id, and
+ * validate FAIL-CLOSED with named remedies:
+ *   * a type without `.root(...)`            → error (declare the root aggregate);
+ *   * two divergent decls under one id       → error (one id, one law);
+ *   * a PACKED type with `hasMany` children  → error (shard-hosted subtrees are not
+ *     law yet — make it `.dedicated()` or flatten the taxonomy);
+ *   * a child id colliding with its parent   → error.
+ */
+export function resolveWorkspaceTypes(
+  declared: readonly WorkspaceTypeDecl[],
+  domainName: string,
+): Map<string, ResolvedWorkspaceType> {
+  // Force the closure over child refs first (a thunked child need not be exported).
+  const seen = new Map<string, WorkspaceTypeDecl>();
+  const queue: WorkspaceTypeDecl[] = [...declared];
+  while (queue.length > 0) {
+    const decl = queue.shift()!;
+    const prior = seen.get(decl.id);
+    if (prior !== undefined) {
+      if (prior !== decl && !sameDecl(prior, decl)) {
+        throw new Error(
+          `domain '${domainName}': workspaceType '${decl.id}' is declared twice with ` +
+            `DIVERGENT shapes — one id is one law. Reconcile the declarations.`,
+        );
+      }
+      continue;
+    }
+    seen.set(decl.id, decl);
+    for (const ref of decl.childRefs) queue.push(typeof ref === "function" ? ref() : ref);
+  }
+
+  const out = new Map<string, ResolvedWorkspaceType>();
+  for (const decl of seen.values()) {
+    if (decl.rootAggregate === undefined) {
+      throw new Error(
+        `domain '${domainName}': workspaceType '${decl.id}' declares no root aggregate — ` +
+          `every workspace type needs exactly one root. Fix: chain .root(<Aggregate>) ` +
+          `on the declaration.`,
+      );
+    }
+    const childIds = decl.childRefs.map((ref) => (typeof ref === "function" ? ref() : ref).id);
+    if (decl.mode === "packed" && childIds.length > 0) {
+      throw new Error(
+        `domain '${domainName}': workspaceType '${decl.id}' is .packed() but declares ` +
+          `hasMany children (${childIds.join(", ")}) — a packed (shard-axis) type cannot ` +
+          `parent child workspaces. Fix: make '${decl.id}' .dedicated(), or flatten the ` +
+          `taxonomy so the children hang off a dedicated ancestor.`,
+      );
+    }
+    if (childIds.includes(decl.id)) {
+      throw new Error(
+        `domain '${domainName}': workspaceType '${decl.id}' declares itself as its own ` +
+          `child — the taxonomy is a tree. Remove the self-edge.`,
+      );
+    }
+    out.set(decl.id, {
+      id: decl.id,
+      rootId: decl.rootAggregate.id,
+      mode: decl.mode,
+      childIds: [...new Set(childIds)].sort(),
+      globalIds: [...new Set(decl.globalAggregates.map((a) => a.id))].sort(),
+      coordinatorLocalIds: [...new Set(decl.coordinatorLocalAggregates.map((a) => a.id))].sort(),
+      ...(decl.poolSize !== undefined ? { poolSize: decl.poolSize } : {}),
+      ...(decl.capCount !== undefined ? { capCount: decl.capCount } : {}),
+    });
+  }
+
+  // One root aggregate ⇒ one type (two types claiming one root is two laws on one record).
+  const byRoot = new Map<string, string>();
+  for (const t of out.values()) {
+    const prior = byRoot.get(t.rootId);
+    if (prior !== undefined) {
+      throw new Error(
+        `domain '${domainName}': aggregate '${t.rootId}' is the root of BOTH workspaceType ` +
+          `'${prior}' and '${t.id}' — one root aggregate anchors one type. Split the roots.`,
+      );
+    }
+    byRoot.set(t.rootId, t.id);
+  }
+  return out;
+}
+
+/** Structural equality of two decls under one id (reference dedupe's slow path). */
+function sameDecl(a: WorkspaceTypeDecl, b: WorkspaceTypeDecl): boolean {
+  const ids = (refs: readonly WorkspaceTypeRef[]) =>
+    refs.map((r) => (typeof r === "function" ? r() : r).id).sort().join(",");
+  return (
+    a.rootAggregate?.id === b.rootAggregate?.id &&
+    a.mode === b.mode &&
+    ids(a.childRefs) === ids(b.childRefs) &&
+    a.globalAggregates.map((x) => x.id).sort().join(",") ===
+      b.globalAggregates.map((x) => x.id).sort().join(",") &&
+    a.coordinatorLocalAggregates.map((x) => x.id).sort().join(",") ===
+      b.coordinatorLocalAggregates.map((x) => x.id).sort().join(",") &&
+    a.poolSize === b.poolSize &&
+    a.capCount === b.capCount
+  );
+}
+
+// ── the homing walk ───────────────────────────────────────────────────────────────
+
+const NO_PATH_REMEDY =
+  "Fix one of: give it a t.ref chain that reaches an axis root; mark it " +
+  ".global(...) on the type that owns it (replicated reference data); or pin it " +
+  "with .coordinatorLocal(...) on the coordinator type.";
+
+/**
+ * Derive the homing table: aggregate wire id → workspace-type id. ZERO ANNOTATION
+ * in the common case — the walk follows the aggregates' existing same-workspace
+ * `t.ref` edges (cross-workspace refs are PR-tier, never homing edges) to the
+ * NEAREST PACKED AXIS root; an aggregate reaching only dedicated roots homes on the
+ * nearest one (the coordinator). TOTAL over the module's aggregates, FAIL-CLOSED:
+ * a no-path or ambiguous aggregate refuses to compile with a named remedy.
+ */
+export function deriveHoming(
+  aggregates: readonly AggregateHandle[],
+  types: ReadonlyMap<string, ResolvedWorkspaceType>,
+  domainName: string,
+): Record<string, string> {
+  const byId = new Map<string, AggregateHandle>();
+  for (const agg of aggregates) byId.set(agg.id, agg);
+
+  // Pins first: roots anchor their own type; globals/coordinatorLocals are explicit.
+  const homes: Record<string, string> = {};
+  const pin = (aggId: string, typeId: string, why: string) => {
+    const prior = homes[aggId];
+    if (prior !== undefined && prior !== typeId) {
+      throw new Error(
+        `domain '${domainName}': aggregate '${aggId}' is ${why} of workspaceType ` +
+          `'${typeId}' but already homes on '${prior}' — one aggregate, one home. ` +
+          `Remove one of the pins.`,
+      );
+    }
+    homes[aggId] = typeId;
+  };
+  for (const t of types.values()) {
+    if (!byId.has(t.rootId)) {
+      throw new Error(
+        `domain '${domainName}': workspaceType '${t.id}' roots on aggregate '${t.rootId}', ` +
+          `which this domain does not declare — the root must be one of the domain's ` +
+          `aggregates. Export it from a composed module (or extraAggregates).`,
+      );
+    }
+    pin(t.rootId, t.id, "the root");
+  }
+  for (const t of types.values()) {
+    for (const g of t.globalIds) pin(g, t.id, "a .global(...)");
+    for (const c of t.coordinatorLocalIds) pin(c, t.id, "a .coordinatorLocal(...)");
+  }
+
+  // THE FRAMEWORK SHARDING LAW homes on the COORDINATOR (sharding slices 2+3): the
+  // derived `Nomos*` aggregates (`workspace_sharding.ts` — the shard map, receipts,
+  // registry, policy, the §5.2 subtotal/frontier rows, deep-verify verdicts) carry
+  // no homing t.ref chain BY DESIGN (they reference homes as DATA, never as a
+  // homing edge), so they pin to the taxonomy's unique top dedicated type. (The
+  // receipt + identity rows physically FOLD in shard chains too — placement is
+  // custody; the pin only says their DIRECTIVES are coordinator law, never routed.)
+  // With NO unique coordinator the pin is a FAIL-CLOSED error, never a guess.
+  const FRAMEWORK_SHARDING_AGGREGATES = new Set([
+    "NomosShardAssignment", "NomosShardIdentity", "NomosHomeReceipt", "NomosShardRegistry",
+    "NomosShardPolicy", "NomosSummarySubtotal", "NomosSummaryFrontier", "NomosDeepVerify",
+    "NomosCheckpointSeal",
+  ]);
+  const childIdsAll = new Set([...types.values()].flatMap((t) => [...t.childIds]));
+  const coordinators = [...types.values()]
+    .filter((t) => t.mode === "dedicated" && !childIdsAll.has(t.id))
+    .map((t) => t.id)
+    .sort();
+  for (const agg of aggregates) {
+    if (!FRAMEWORK_SHARDING_AGGREGATES.has(agg.id) || homes[agg.id] !== undefined) continue;
+    if (coordinators.length !== 1) {
+      throw new Error(
+        `domain '${domainName}': framework aggregate '${agg.id}' homes on the coordinator, ` +
+          `but the taxonomy has ${coordinators.length === 0 ? "no" : "more than one"} top ` +
+          `dedicated type (${coordinators.join(", ") || "none"}) — pin it with ` +
+          `.coordinatorLocal(...) on the intended coordinator type.`,
+      );
+    }
+    pin(agg.id, coordinators[0]!, "the framework placement law (coordinator-pinned)");
+  }
+
+  const rootType = new Map<string, ResolvedWorkspaceType>();
+  for (const t of types.values()) rootType.set(t.rootId, t);
+
+  // BFS per unpinned aggregate over same-workspace ref edges, shortest first.
+  for (const agg of aggregates) {
+    if (homes[agg.id] !== undefined) continue;
+    const dist = new Map<string, number>([[agg.id, 0]]);
+    const frontier: string[] = [agg.id];
+    const packedHits = new Map<string, number>(); // typeId → distance
+    const dedicatedHits = new Map<string, number>();
+    while (frontier.length > 0) {
+      const cur = frontier.shift()!;
+      const d = dist.get(cur)!;
+      const t = rootType.get(cur);
+      if (t !== undefined && cur !== agg.id) {
+        (t.mode === "packed" ? packedHits : dedicatedHits).set(t.id, d);
+        continue; // a root is an axis terminus — the walk stops at it
+      }
+      const handle = byId.get(cur);
+      if (handle === undefined) continue; // a ref out of this domain — not a homing edge
+      for (const field of Object.values(handle.fields)) {
+        if (field.kind !== "ref" || field.refAggregateId === undefined) continue;
+        if (field.refWorkspace !== undefined) continue; // PR-tier edge, never homing
+        if (!dist.has(field.refAggregateId)) {
+          dist.set(field.refAggregateId, d + 1);
+          frontier.push(field.refAggregateId);
+        }
+      }
+    }
+    const pick = (hits: Map<string, number>, axisKind: string): string | undefined => {
+      if (hits.size === 0) return undefined;
+      const min = Math.min(...hits.values());
+      const nearest = [...hits.entries()].filter(([, d]) => d === min).map(([id]) => id).sort();
+      if (nearest.length > 1) {
+        throw new Error(
+          `domain '${domainName}': aggregate '${agg.id}' reaches ${axisKind} axes ` +
+            `${nearest.map((n) => `'${n}'`).join(" and ")} at the same ref distance — ` +
+            `its home is ambiguous. Fix: pin it (.coordinatorLocal(...) / .global(...)), ` +
+            `or restructure its t.ref chain so one axis is strictly nearer.`,
+        );
+      }
+      return nearest[0];
+    };
+    const home = pick(packedHits, "packed") ?? pick(dedicatedHits, "dedicated");
+    if (home === undefined) {
+      throw new Error(
+        `domain '${domainName}': aggregate '${agg.id}' has NO t.ref path to any ` +
+          `workspace-type root — it cannot be homed. ${NO_PATH_REMEDY}`,
+      );
+    }
+    homes[agg.id] = home;
+  }
+  return homes;
+}
+
+// ── directive cross-home check ────────────────────────────────────────────────────
+
+/**
+ * FAIL-CLOSED cross-home check over each directive's DECLARED surface (its target
+ * aggregate + its `.reads(...)` boundary): every declared-read type must be
+ * available at the target's home — same home, or `.global(...)` reference data
+ * (replicated to shards), or an ancestor coordinator's globals. A plan spanning two
+ * homes must be modeled as the Order/Receipt PR pair (`cross_workspace.md`), never
+ * as one intent the sharding layer would have to tear in half. (Instance-level
+ * wrong-home is the shard gate's runtime invariant — slice 2.)
+ */
+export function checkDirectiveHoming(
+  directives: readonly AnyDirective[],
+  homes: Readonly<Record<string, string>>,
+  types: ReadonlyMap<string, ResolvedWorkspaceType>,
+  domainName: string,
+): void {
+  const globalIds = new Set<string>();
+  for (const t of types.values()) for (const g of t.globalIds) globalIds.add(g);
+  for (const d of directives) {
+    const targetHome = homes[d.aggregateId];
+    if (targetHome === undefined) continue; // a foreign-domain target — not this law's walk
+    for (const read of d.declaredReads) {
+      const readHome = homes[read];
+      if (readHome === undefined || readHome === targetHome) continue;
+      if (globalIds.has(read)) continue; // replicated reference data — readable at any home
+      throw new Error(
+        `domain '${domainName}': directive '${d.id}' targets '${d.aggregateId}' ` +
+          `(home '${targetHome}') but declares a read of '${read}' (home '${readHome}') — ` +
+          `a plan cannot span two homes. Fix: mark '${read}' .global(...) on its owning ` +
+          `type (replicated reference data), or model the cross-home effect as an ` +
+          `Order/Receipt PR pair (cross_workspace.md).`,
+      );
+    }
+  }
+}
+
+// ── canonical-manifest lowering (hash-bearing, omitted-when-absent) ───────────────
+
+/** One captured workspace type in the canonical manifest — the hashed taxonomy law. */
+export interface CanonicalWorkspaceType {
+  readonly id: string;
+  /** The root aggregate's wire id. */
+  readonly root: string;
+  readonly mode: WorkspaceTypeMode;
+  /** Child type ids, SORTED. OMITTED when the type declares no children. */
+  readonly children?: string[];
+  /** Replicated reference-data aggregate ids, SORTED. OMITTED when none. */
+  readonly globals?: string[];
+  /** Pinned aggregate ids, SORTED. OMITTED when none. */
+  readonly coordinatorLocals?: string[];
+  /** The child pool. OMITTED when undeclared. */
+  readonly pool?: number;
+  /** The instance cap. OMITTED when undeclared. */
+  readonly cap?: number;
+}
+
+/** The manifest fragment the taxonomy lowers to: the types + the derived homing table. */
+export interface CanonicalWorkspaceTypesFragment {
+  workspaceTypes?: CanonicalWorkspaceType[];
+  homes?: Record<string, string>;
+}
+
+/**
+ * Lower a module's declared workspace types into its canonical-manifest fragment.
+ * OMIT-WHEN-EMPTY: returns `{}` (NEITHER key) when the module declares none — the
+ * omission, not an empty array, is what keeps taxonomy-free domains byte-identical
+ * to before this feature existed (guestbook + co2 hashes PROVEN unmoved). When
+ * declared: `workspaceTypes` SORTED by id (per-type optional keys omitted-when-absent,
+ * the `cap(n)` discipline) plus `homes` — the DERIVED homing table (aggregate →
+ * type id; `canonicalJson` sorts the record keys). Both are LAW: the domain hash
+ * moves when the taxonomy or a homing assignment moves. Runs the full fail-closed
+ * validation (resolution, the homing walk, the directive cross-home check) — an
+ * unhomeable taxonomy never produces an identity.
+ */
+export function canonicalWorkspaceTypesFragment(mod: {
+  readonly name: string;
+  readonly aggregates: readonly AggregateHandle[];
+  readonly directives: readonly AnyDirective[];
+  readonly workspaceTypes?: readonly WorkspaceTypeDecl[];
+}): CanonicalWorkspaceTypesFragment {
+  if (mod.workspaceTypes === undefined || mod.workspaceTypes.length === 0) return {};
+  const types = resolveWorkspaceTypes(mod.workspaceTypes, mod.name);
+  const homes = deriveHoming(mod.aggregates, types, mod.name);
+  checkDirectiveHoming(mod.directives, homes, types, mod.name);
+  const workspaceTypes: CanonicalWorkspaceType[] = [...types.values()]
+    .map((t) => ({
+      id: t.id,
+      root: t.rootId,
+      mode: t.mode,
+      ...(t.childIds.length > 0 ? { children: [...t.childIds] } : {}),
+      ...(t.globalIds.length > 0 ? { globals: [...t.globalIds] } : {}),
+      ...(t.coordinatorLocalIds.length > 0
+        ? { coordinatorLocals: [...t.coordinatorLocalIds] }
+        : {}),
+      ...(t.poolSize !== undefined ? { pool: t.poolSize } : {}),
+      ...(t.capCount !== undefined ? { cap: t.capCount } : {}),
+    }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { workspaceTypes, homes };
+}
+
+/**
+ * Validate a module's taxonomy FAIL-CLOSED (the compile gate `nomos-compile` runs
+ * BEFORE identity emission, so a homing error is a named COMPILE error — never a
+ * domain silently recorded as identity-excluded). Same machinery as the lowering;
+ * throwing is the verdict.
+ */
+export function validateWorkspaceTaxonomy(mod: {
+  readonly name: string;
+  readonly aggregates: readonly AggregateHandle[];
+  readonly directives: readonly AnyDirective[];
+  readonly workspaceTypes?: readonly WorkspaceTypeDecl[];
+}): void {
+  canonicalWorkspaceTypesFragment(mod);
+}
+
+// ── estate-scope reads (sharding §2/§5 — slice 3) ─────────────────────────────────
+
+/**
+ * Lift a declared `count(...)`/`sum(...)` read to ESTATE SCOPE (sharding §5): the
+ * read's per-shard values ride the §5.2 delta lane as gate-recomputed committed
+ * subtotals on the coordinator, and the logical workspace answers it O(1) from the
+ * maintained estate total — never a scatter-gather.
+ *
+ *     export const fxSiteCount = scoped(count("fxSiteCount").of(Site), EstateWs);
+ *
+ * Lives on THIS subpath (never the runtime barrel, and never a method on the
+ * count/sum builders) by the slice-1 hash-stability law: the builders' bytes ride
+ * every tenant's engine lump, and a taxonomy-free domain's package bytes must not
+ * move. The marker is HASH-BEARING (the canonical manifest's `scope` key,
+ * omitted-when-absent): scoping a read is a law change.
+ *
+ * PREDICATE-BEARING reads (slice 4): a `.where(...)`-filtered count/sum MAY be
+ * estate-scoped — the shard-side capture's oracle is the projection's MAINTAINED
+ * (predicate-aware) tally, and the suffix re-derivation evaluates the canonical
+ * predicate in its host fold (`engine.mjs evalCanonicalPred`). The predicate is
+ * hash-bearing through the canonical manifest's `where` key exactly as before.
+ *
+ * FAIL-CLOSED boundary (named): the scope must be a DECLARED workspace type (the
+ * compile gate additionally pins it to the coordinator type of a packed taxonomy).
+ */
+export function scoped<T extends { readonly id: string; readonly of: string }>(
+  read: T,
+  scope: WorkspaceTypeRef,
+): T & { readonly scope: string } {
+  const decl = typeof scope === "function" ? scope() : scope;
+  if (!decl || (decl as { __isWorkspaceType?: unknown }).__isWorkspaceType !== true) {
+    throw new Error(
+      `scoped(read, scope): the scope must be a workspaceType(...) declaration (got ${typeof scope})`,
+    );
+  }
+  const r = read as { id?: unknown; of?: unknown; _where?: unknown };
+  if (typeof r.id !== "string" || typeof r.of !== "string") {
+    throw new Error(
+      `scoped(read, scope): the read must be a count/sum with .of(...) declared (a named, maintained read)`,
+    );
+  }
+  if ((r.id as string).includes("|")) {
+    throw new Error(
+      `estate-scoped read '${String(r.id)}' contains '|' — the estate-summary bucket separator. ` +
+        `Rename the read (scoped read ids may not contain '|').`,
+    );
+  }
+  return Object.freeze({ ...(read as object), scope: decl.id }) as T & { readonly scope: string };
+}