@githolon/dsl 0.2.2 → 0.3.0

package/src/compile_package_main.ts

@@ -55,7 +55,13 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import type { AggregateHandle } from "./aggregate.js";
-import { generateDartDomain, type DomainModule } from "./codegen_dart.js";
+import {
+  generateDartDomain,
+  type DartImport,
+  type DartRefImport,
+  type DomainModule,
+  type PermissionVocabulary,
+} from "./codegen_dart.js";
 import type { AnyCount } from "./count.js";
 import type { QueryDecl } from "./query.js";
 import type { SpatialDecl } from "./spatial.js";
@@ -76,6 +82,11 @@ import {
   type Mod,
 } from "./build_package.js";
 import { collectEngineRouting } from "./engine_entry.js";
+import { resolveWorkspaceTypes, type WorkspaceTypeDecl } from "./workspace_type.js";
+import { canonicalTaxonomyFragment, validateWorkspaceTaxonomyAndRoutes } from "./workspace_routing.js";
+import { shardingLawModule, type ShardingLawSpec } from "./workspace_sharding.js";
+import type { AnyExtremum } from "./extremum.js";
+import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import {
   emitLayeredDomain,
   flattenLayeredUsd,
@@ -96,12 +107,35 @@ interface DomainConfig {
   readonly queries?: readonly string[];
   readonly counts?: readonly string[];
   readonly sums?: readonly string[];
+  /** Maintained MIN/MAX reads (#47) — export names, config-named like sums. */
+  readonly mins?: readonly string[];
+  readonly maxes?: readonly string[];
   readonly spatials?: readonly string[];
   readonly deriveds?: readonly string[];
   readonly combineds?: readonly string[];
+  readonly workspaceTypes?: readonly string[];
+  /** Export-name escape hatch for workspace invariants (auto-discovered by shape otherwise). */
+  readonly workspaceInvariants?: readonly string[];
   readonly impureCapabilities?: readonly string[];
   readonly extraAggregates?: readonly string[];
   readonly readModelAggregates?: readonly string[];
+  // DART CODEGEN HINTS (#codegen_dart; NEVER law: none of these enter the USD IR,
+  // the package bytes, or the identity manifest — they shape ONLY the generated
+  // `dart/` frontend, so adding them does not move the domainHash):
+  /** LITERAL extra imports for the generated `<domain>.dart` (e.g. a sibling
+   * domain file whose types this domain's payloads reference). */
+  readonly dartImports?: readonly DartImport[];
+  /** LITERAL cross-domain read-model routing: an aggregate TYPE this domain
+   * references resolves through the named import prefix instead of a local decl. */
+  readonly dartRefImports?: readonly DartRefImport[];
+  /** EXPORT-NAME escape hatch (resolved on the merged module exports, like
+   * `impureCapabilities`): `resourceTypes` names a `readonly string[]` export and
+   * `roleCatalogue` a `Record<string, string[]>` export; together they emit the
+   * frontend permission vocabulary (PermissionRoles/PermissionCapabilities). */
+  readonly permissionVocabulary?: {
+    readonly resourceTypes: string;
+    readonly roleCatalogue: string;
+  };
 }
 
 interface PackageConfig {
@@ -153,6 +187,14 @@ function isQueryDecl(v: unknown): v is QueryDecl {
   );
 }
 
+function isWorkspaceInvariantDecl(v: unknown): v is WorkspaceInvariantDecl {
+  return (
+    !!v &&
+    typeof v === "object" &&
+    (v as { __isWorkspaceInvariant?: unknown }).__isWorkspaceInvariant === true
+  );
+}
+
 function isSpatialDecl(v: unknown): v is SpatialDecl {
   return (
     !!v &&
@@ -200,7 +242,8 @@ function isCountDecl(v: unknown): v is AnyCount {
     typeof o.on !== "string" && // spatial
     typeof o.fn !== "function" && // derived/combined
     !Array.isArray(o.key) && // query
-    !("field" in o) && // sum / extremum
+    !("field" in o) && // extremum
+    !("sumField" in o) && // sum (the SumDecl/Sum-builder mark — never a count)
     !("orderBy" in o) && // ordered read
     !("_existsMarker" in o) && // exists
     typeof o.refField !== "string" && // combined
@@ -210,6 +253,28 @@ function isCountDecl(v: unknown): v is AnyCount {
   );
 }
 
+/**
+ * Scan merged exports for `workspaceType(...)` decls (sharding §10 slice 1) by the
+ * `__isWorkspaceType` brand — individual exports AND exported arrays. Dedupe is BY
+ * REFERENCE here and BY ID (divergence-refused) in `resolveWorkspaceTypes`; the
+ * generic `discover()`'s JSON dedupe key is unusable for these decls (they carry
+ * aggregate handles whose zod schemas do not stringify).
+ */
+function discoverWorkspaceTypes(merged: Mod): WorkspaceTypeDecl[] {
+  const out: WorkspaceTypeDecl[] = [];
+  const isDecl = (v: unknown): v is WorkspaceTypeDecl =>
+    !!v && typeof v === "object" &&
+    (v as { __isWorkspaceType?: unknown }).__isWorkspaceType === true;
+  const push = (v: WorkspaceTypeDecl) => {
+    if (!out.includes(v)) out.push(v);
+  };
+  for (const v of Object.values(merged)) {
+    if (isDecl(v)) push(v);
+    else if (Array.isArray(v)) for (const el of v) if (isDecl(el)) push(el);
+  }
+  return out;
+}
+
 /** Scan merged exports for decls matching `match`: individual exports AND exported arrays. */
 function discover<T>(merged: Mod, match: (v: unknown) => v is T): T[] {
   const seen = new Set<string>();
@@ -228,6 +293,66 @@ function discover<T>(merged: Mod, match: (v: unknown) => v is T): T[] {
   return out;
 }
 
+/** Validate the LITERAL dart-codegen import hints (config data, not module exports). */
+function checkDartImports(domainKey: string, imports: readonly DartImport[] | undefined): void {
+  for (const imp of imports ?? []) {
+    if (typeof imp?.uri !== "string" || (imp.prefix !== undefined && typeof imp.prefix !== "string")) {
+      fail(`domain '${domainKey}': each dartImports entry must be { uri, prefix? }; got ${JSON.stringify(imp)}`);
+    }
+  }
+}
+
+function checkDartRefImports(domainKey: string, imports: readonly DartRefImport[] | undefined): void {
+  for (const imp of imports ?? []) {
+    if (
+      typeof imp?.aggregateType !== "string" ||
+      typeof imp?.uri !== "string" ||
+      typeof imp?.prefix !== "string"
+    ) {
+      fail(
+        `domain '${domainKey}': each dartRefImports entry must be { aggregateType, uri, prefix }; got ${JSON.stringify(imp)}`,
+      );
+    }
+  }
+}
+
+/** Resolve the permissionVocabulary EXPORT NAMES on the merged exports, fail-closed. */
+function resolvePermissionVocabulary(
+  domainKey: string,
+  merged: Mod,
+  cfg: DomainConfig["permissionVocabulary"],
+): PermissionVocabulary | undefined {
+  if (cfg === undefined) return undefined;
+  if (typeof cfg?.resourceTypes !== "string" || typeof cfg?.roleCatalogue !== "string") {
+    fail(
+      `domain '${domainKey}': permissionVocabulary must be { resourceTypes: "<exportName>", roleCatalogue: "<exportName>" }; got ${JSON.stringify(cfg)}`,
+    );
+  }
+  const resourceTypes = merged[cfg.resourceTypes];
+  if (!Array.isArray(resourceTypes) || !resourceTypes.every((t) => typeof t === "string")) {
+    fail(
+      `domain '${domainKey}': permissionVocabulary.resourceTypes names export '${cfg.resourceTypes}', which the modules do not export as a string[]`,
+    );
+  }
+  const roleCatalogue = merged[cfg.roleCatalogue];
+  if (
+    !roleCatalogue ||
+    typeof roleCatalogue !== "object" ||
+    Array.isArray(roleCatalogue) ||
+    !Object.values(roleCatalogue).every(
+      (caps) => Array.isArray(caps) && caps.every((c) => typeof c === "string"),
+    )
+  ) {
+    fail(
+      `domain '${domainKey}': permissionVocabulary.roleCatalogue names export '${cfg.roleCatalogue}', which the modules do not export as a Record<string, string[]>`,
+    );
+  }
+  return {
+    resourceTypes: resourceTypes as string[],
+    roleCatalogue: roleCatalogue as Record<string, string[]>,
+  };
+}
+
 /** Resolve explicit EXPORT NAMES (the config escape hatch) on the merged exports. */
 function resolveNamed<T>(merged: Mod, names: readonly string[] | undefined, what: string): T[] {
   const out: T[] = [];
@@ -338,6 +463,7 @@ async function main(): Promise<void> {
   const eagerLump = process.env.NOMOS_LUMP_BOOT === "eager";
   const entryImports: string[] = [];
   const entryDomains: string[] = [];
+  const entryMintInstalls: string[] = []; // route-tagged in-plan mints (taxonomy packages only)
   const routingInput: Record<string, Mod[]> = {};
   const domainModules: DomainModule[] = [];
   const layered = layeredFlag || cfg.layered === true;
@@ -363,11 +489,127 @@ async function main(): Promise<void> {
         sourceExprs.push(`() => require(${JSON.stringify(abs)})`);
       }
     }
-    entryDomains.push(`    ${JSON.stringify(d.key)}: [${sourceExprs.join(", ")}],`);
-    routingInput[d.key] = mods;
-
     let merged: Mod = {};
     for (const m of mods) merged = { ...merged, ...m };
+    let shardingSums: AnySum[] = [];
+    let shardingModForDomain: Mod | undefined;
+    let shardingLazyExpr: string | undefined;
+
+    // ── THE DERIVED PLACEMENT LAW (sharding slice 2): a taxonomy with PACKED axes
+    //    appends the framework placement module (`workspace_sharding.ts`) to this
+    //    domain — in the composed manifests (hash-bearing law) AND the generated
+    //    entry (the plan ships in the lump). Taxonomy-free domains append NOTHING:
+    //    their package bytes / hashes do not move (the slice-1 stability law). ──
+    const workspaceTypes = [
+      ...discoverWorkspaceTypes(merged),
+      ...resolveNamed<WorkspaceTypeDecl>(merged, d.workspaceTypes, "workspaceTypes"),
+    ];
+    if (workspaceTypes.length > 0) {
+      let spec: ShardingLawSpec | undefined;
+      try {
+        const types = resolveWorkspaceTypes(workspaceTypes, d.name ?? d.key);
+        const axes = [...types.values()]
+          .filter((t) => t.mode === "packed")
+          .map((p) => {
+            const parent = [...types.values()].find((t) => t.childIds.includes(p.id));
+            // SLICE-2 STATIC MAP: shard count = the parent's .pool(n), default 1 (the
+            // degenerate coordinator+sole-shard layout, §6's no-flag-day migration).
+            return { axisType: p.id, axisRoot: p.rootId, shardCount: parent?.poolSize ?? 1 };
+          })
+          .sort((a, b) => (a.axisType < b.axisType ? -1 : 1));
+        if (axes.length > 0) spec = { axes };
+      } catch (e) {
+        fail((e as Error).message);
+      }
+      if (spec !== undefined) {
+        // SLICE 3a (#41): derive the directive ROUTES over the TENANT modules (the SAME
+        // derivation the canonical manifest records) and feed them into the placement
+        // law, so it emits the per-directive HOMING INVARIANT — the wrong-home gate
+        // moves from the edge bailiff into THE CHAIN GATE ITSELF.
+        // SLICE 3 (#42): also feed the PACKED HOMING TABLE (aggregate → axis) — the
+        // engine-side route-tag mint wrapper tags in-plan `create(Agg)` mints of
+        // packed-homed aggregates with the dispatched intent's home tag (§4).
+        try {
+          const fragment = canonicalTaxonomyFragment({
+            name: d.name ?? d.key,
+            aggregates: aggregatesOf(merged),
+            directives: directivesOf(merged),
+            workspaceTypes,
+          });
+          if (fragment.routes !== undefined && fragment.routes.length > 0) {
+            spec = { ...spec, routes: fragment.routes };
+          }
+          const packedAxes = new Set(spec.axes.map((a) => a.axisType));
+          const packedHomes = Object.fromEntries(
+            Object.entries(fragment.homes ?? {}).filter(([, home]) => packedAxes.has(home)),
+          );
+          if (Object.keys(packedHomes).length > 0) spec = { ...spec, homes: packedHomes };
+        } catch (e) {
+          fail((e as Error).message);
+        }
+        const shardingMod = shardingLawModule(spec) as Mod;
+        mods.push(shardingMod);
+        merged = { ...merged, ...shardingMod };
+        shardingModForDomain = shardingMod;
+        // The derived sharding law's MAINTAINED SUMS (`nomosEstateSummary` — the §5.1
+        // estate total over subtotal rows) must reach the read manifest + identity:
+        // sums are config-named (never auto-discovered — hash stability for existing
+        // packages), so the appended module's sums thread through explicitly here.
+        shardingSums = Object.values(shardingMod).filter(
+          (v): v is AnySum =>
+            !!v && typeof v === "object" &&
+            typeof (v as { id?: unknown }).id === "string" &&
+            typeof (v as { of?: unknown }).of === "string" &&
+            typeof (v as { sumField?: unknown }).sumField === "string",
+        );
+        const specJson = JSON.stringify(spec);
+        if (eagerLump) {
+          if (!entryImports.some((l) => l.includes("workspace-sharding"))) {
+            entryImports.push(
+              `import { shardingLawModule as __nomosShardingLaw, installRouteTaggedMint as __nomosInstallMint } from "@githolon/dsl/workspace-sharding";`,
+            );
+          }
+          sourceExprs.push(`__nomosShardingLaw(${specJson})`);
+        } else {
+          shardingLazyExpr = `() => (require("@githolon/dsl/workspace-sharding") as any).shardingLawModule(${specJson})`;
+          sourceExprs.push(shardingLazyExpr);
+        }
+        // ROUTE-TAGGED IN-PLAN MINTS (§4, slice 3): installed AFTER registerEngine at
+        // the lump's top level — pre-freeze, taxonomy packages only (a taxonomy-free
+        // lump never imports the module: the slice-1 hash-stability law).
+        entryMintInstalls.push(
+          eagerLump
+            ? `__nomosInstallMint(${specJson});`
+            : `(require("@githolon/dsl/workspace-sharding") as any).installRouteTaggedMint(${specJson});`,
+        );
+      }
+    }
+
+    entryDomains.push(`    ${JSON.stringify(d.key)}: [${sourceExprs.join(", ")}],`);
+    routingInput[d.key] = mods;
+    // ── THE AUX INVARIANT-ROUTING KEY (#47, sharding slice 7 — the invariant-gate
+    //    flame pass): in a LAZY lump, the derived sharding law registers a SECOND
+    //    time under its own domain key, and the ROUTING table points the sharding
+    //    workspace-invariant ids at THAT key only. A per-write homing-invariant
+    //    dispatch (`workspaceInvariantReads`/`workspaceInvariant`) then forces ONLY
+    //    the small framework module — never the tenant domain's whole zod/module
+    //    graph (the measured ~30 ms-per-dispatch floor on co2 estate_structures).
+    //    Directive dispatch is untouched (the sharding directives stay registered
+    //    under `d.key` — the wire domain every host lane already speaks); the
+    //    canonical manifests are untouched (identity hashes do not move); eager
+    //    lumps are untouched (no routing table — the pre-#34 equivalence shape);
+    //    taxonomy-free packages emit NOTHING here (the slice-1 byte-stability law).
+    if (shardingModForDomain !== undefined && shardingLazyExpr !== undefined && !eagerLump) {
+      const auxKey = `${d.key}/nomos-sharding`;
+      if (cfg.domains.some((x) => x.key === auxKey) || routingInput[auxKey] !== undefined) {
+        fail(
+          `domain key '${auxKey}' is reserved for the derived sharding law's invariant routing — rename the domain`,
+        );
+      }
+      entryDomains.push(`    ${JSON.stringify(auxKey)}: [${shardingLazyExpr}],`);
+      routingInput[d.key] = mods.filter((m) => m !== shardingModForDomain);
+      routingInput[auxKey] = [shardingModForDomain];
+    }
 
     const queries = [
       ...discover<QueryDecl>(merged, isQueryDecl),
@@ -389,7 +631,13 @@ async function main(): Promise<void> {
       ...discover<CombinedDecl>(merged, isCombinedDecl),
       ...resolveNamed<CombinedDecl>(merged, d.combineds, "combineds"),
     ];
-    const sums = resolveNamed<AnySum>(merged, d.sums, "sums");
+    const workspaceInvariants = [
+      ...discover<WorkspaceInvariantDecl>(merged, isWorkspaceInvariantDecl),
+      ...resolveNamed<WorkspaceInvariantDecl>(merged, d.workspaceInvariants, "workspaceInvariants"),
+    ];
+    const sums = [...resolveNamed<AnySum>(merged, d.sums, "sums"), ...shardingSums];
+    const mins = resolveNamed<AnyExtremum>(merged, d.mins, "mins");
+    const maxes = resolveNamed<AnyExtremum>(merged, d.maxes, "maxes");
     const impureCapabilities = resolveNamed<ImpureCapabilityDecl>(
       merged,
       d.impureCapabilities,
@@ -397,6 +645,11 @@ async function main(): Promise<void> {
     );
     const extraAggregates = resolveNamed<AggregateHandle>(merged, d.extraAggregates, "extraAggregates");
 
+    // Dart-codegen hints (frontend-only — never law; see DomainConfig):
+    checkDartImports(d.key, d.dartImports);
+    checkDartRefImports(d.key, d.dartRefImports);
+    const permissionVocabulary = resolvePermissionVocabulary(d.key, merged, d.permissionVocabulary);
+
     domainModules.push(
       composeDomainModule({
         name: d.name ?? d.key,
@@ -412,10 +665,82 @@ async function main(): Promise<void> {
         ...(combineds.length > 0 ? { combineds } : {}),
         ...(impureCapabilities.length > 0 ? { impureCapabilities } : {}),
         ...(sums.length > 0 ? { sums } : {}),
+        ...(mins.length > 0 ? { mins } : {}),
+        ...(maxes.length > 0 ? { maxes } : {}),
+        ...(workspaceTypes.length > 0 ? { workspaceTypes } : {}),
+        ...(workspaceInvariants.length > 0 ? { workspaceInvariants } : {}),
         ...(spatials.length > 0 ? { spatials } : {}),
+        ...(d.dartImports !== undefined && d.dartImports.length > 0
+          ? { dartImports: d.dartImports }
+          : {}),
+        ...(d.dartRefImports !== undefined && d.dartRefImports.length > 0
+          ? { dartRefImports: d.dartRefImports }
+          : {}),
+        ...(permissionVocabulary !== undefined ? { permissionVocabulary } : {}),
       }),
     );
 
+    // ── THE TAXONOMY GATE (sharding §10 slice 1 + slice 2; fail-closed, BEFORE
+    //    identity emission): resolve the declared workspace types, run the homing
+    //    walk (nearest packed axis via t.ref chains), the directive cross-home
+    //    check, AND the slice-2 route derivation (per-directive home keys). A
+    //    no-path / ambiguous / cross-home / unroutable law is a NAMED COMPILE
+    //    ERROR here — never a domain silently recorded as identity-excluded.
+    const composed = domainModules[domainModules.length - 1]!;
+    if (composed.workspaceTypes !== undefined && composed.workspaceTypes.length > 0) {
+      try {
+        validateWorkspaceTaxonomyAndRoutes(composed);
+      } catch (e) {
+        fail((e as Error).message);
+      }
+    }
+    // ── THE SCOPE GATE (sharding §5, slice 3; fail-closed): every `scoped(read, Ws)`
+    //    must name a DECLARED, DEDICATED workspace type of THIS domain's taxonomy
+    //    (the coordinator type that holds the subtotal rows). A scoped read in a
+    //    taxonomy-free domain, or scoped to a packed type, is a NAMED compile error.
+    {
+      const declaredScopes = new Map<string, string>(); // type id -> mode
+      const globalAggIds = new Set<string>(); // §5.4 — replicated reference data
+      if (workspaceTypes.length > 0) {
+        try {
+          for (const [id, ty] of resolveWorkspaceTypes(workspaceTypes, d.name ?? d.key)) {
+            declaredScopes.set(id, ty.mode);
+            for (const g of ty.globalIds) globalAggIds.add(g);
+          }
+        } catch { /* already failed above */ }
+      }
+      for (const read of [...(composed.counts ?? []), ...(composed.sums ?? [])]) {
+        const scope = (read as { scope?: unknown }).scope;
+        if (scope === undefined) continue;
+        const id = (read as { id?: unknown }).id;
+        if (typeof scope !== "string" || !declaredScopes.has(scope)) {
+          fail(
+            `domain '${d.key}': read '${String(id)}' is scoped to '${String(scope)}', which is not a ` +
+              `declared workspace type of this domain — declare the taxonomy (workspaceType(...)) ` +
+              `in the same domain, or drop the scope.`,
+          );
+        }
+        if (declaredScopes.get(scope) !== "dedicated") {
+          fail(
+            `domain '${d.key}': read '${String(id)}' is scoped to PACKED type '${scope}' — estate ` +
+              `scope must name the DEDICATED coordinator type (the holon that holds the subtotal rows).`,
+          );
+        }
+        // §5.4 (slice 4): a `.global(...)` aggregate is coordinator-homed reference
+        // data REPLICATED to every shard — an estate-scoped tally over it would sum
+        // the SAME rows once per shard. Its home-scope read on the coordinator IS
+        // the estate value already.
+        const ofType = (read as { of?: unknown }).of;
+        if (typeof ofType === "string" && globalAggIds.has(ofType)) {
+          fail(
+            `domain '${d.key}': read '${String(id)}' is scoped over GLOBAL aggregate '${ofType}' — ` +
+              `global reference data is replicated to every shard, so an estate-scoped tally would ` +
+              `count it once per shard. Drop the scope: the coordinator's home-scope read IS the estate value.`,
+          );
+        }
+      }
+    }
+
     // ── opt-in: ONE USD LAYER PER MODULE (Φ applied per module, not once over the
     //    composed fold) — the layered emission `usd_layers.ts` proves flattens back
     //    to the EXACT canonical IR (asserted below, fail-closed). Per-module decls
@@ -550,6 +875,10 @@ async function main(): Promise<void> {
     ...(eagerLump ? [] : [`  routing: ${JSON.stringify(routing)},`]),
     ...(zodSeedNames.length > 0 ? [`  seeds: [${zodSeedNames.join(", ")}],`] : []),
     `});`,
+    // ROUTE-TAGGED IN-PLAN MINTS (sharding §4, slice 3): wraps globalThis.plan +
+    // globalThis.nomos.mint at top-level eval — pre-freeze, after registerEngine's
+    // own assignments. Empty (and therefore byte-absent) for taxonomy-free packages.
+    ...entryMintInstalls,
     ``,
   ].join("\n");
   const entryPath = path.join(outDir, ".nomos_entry.ts");
@@ -787,6 +1116,13 @@ async function main(): Promise<void> {
   console.log(`  identity   ${rel(manifestsPath)} (${Object.keys(identity.manifests).length} domain(s)${identity.excluded.length ? `, ${identity.excluded.length} EXCLUDED (palette gap)` : ""})`);
   for (const [dom, h] of Object.entries(identity.hashes)) console.log(`             ${dom.padEnd(20)} ${h}`);
   for (const ex of identity.excluded) console.log(`             EXCLUDED ${ex.domain}: ${ex.reason}`);
+  for (const m of domainModules) {
+    if (m.workspaceTypes !== undefined && m.workspaceTypes.length > 0) {
+      console.log(
+        `  taxonomy   ${m.domain ?? m.name}: ${m.workspaceTypes.length} workspace type(s) — homing derived from t.ref chains; birth lanes typed in the client`,
+      );
+    }
+  }
   console.log(`  client     ${rel(clientPath)} (typed TS client — payloads, read models, query accessors)`);
   if (proofPath !== undefined) {
     console.log(`  proof      ${rel(proofPath)} (a runnable e2e GENERATED from your law — run: githolon proof)`);

package/src/engine_entry.ts

@@ -59,6 +59,7 @@ import type { WireEvent, WireHlc } from "./wire.js";
 import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import type { InvariantBody, InvariantEvidence, InvariantVerdict } from "./relation.js";
+import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { QueryRow } from "./report.js";
 
 /** One bundled domain module: a bag of named exports the entry scans by SHAPE. */
@@ -91,6 +92,8 @@ export interface EngineRouting {
   readonly combinedOf?: Record<string, readonly string[]>;
   readonly aggregateInvariantOf?: Record<string, readonly string[]>;
   readonly relationOf?: Record<string, readonly string[]>;
+  /** workspace-invariant id → declaring domain keys (#266 — the gate's reads/assert dispatches). */
+  readonly workspaceInvariantOf?: Record<string, readonly string[]>;
 }
 
 /** The one declarative input: dispatch key → ORDERED module list (later wins). */
@@ -216,6 +219,8 @@ interface DomainSlice {
   invariants: Map<string, InvariantBody>;
   /** aggregate type → aggregate-invariant body. */
   aggInvariants: Map<string, AggregateInvariantFn>;
+  /** workspace-invariant id → its declaration (#266 — `reads`/`assert` bodies ship HERE). */
+  wsInvariants: Map<string, WorkspaceInvariantDecl>;
 }
 
 /** Build one domain's slice from its merged module exports (the original scans). */
@@ -288,7 +293,28 @@ function buildDomainSlice(mod: DomainModuleExports): DomainSlice {
     }
   }
 
-  return { registry, deriveds, combineds, invariants, aggInvariants };
+  // ── workspace-invariant id → declaration — from the SAME exports (#266, by shape) ──
+  const wsInvariants = new Map<string, WorkspaceInvariantDecl>();
+  for (const v of Object.values(mod)) {
+    if (
+      v &&
+      typeof v === "object" &&
+      (v as { __isWorkspaceInvariant?: boolean }).__isWorkspaceInvariant === true
+    ) {
+      const w = v as WorkspaceInvariantDecl;
+      if (typeof w.reads !== "function" || typeof w.assert !== "function") {
+        // A declaration MUST ship both executable halves — fail-closed at boot, exactly
+        // like a relation/aggregate invariant with a missing body.
+        throw new Error(
+          `engine bundle: workspace invariant "${w.id}" declares no executable reads/assert ` +
+            `body — the gate would have nothing to evaluate (docs/workspace_invariant.md).`,
+        );
+      }
+      wsInvariants.set(w.id, w);
+    }
+  }
+
+  return { registry, deriveds, combineds, invariants, aggInvariants, wsInvariants };
 }
 
 /**
@@ -306,6 +332,7 @@ export function collectEngineRouting(
   const combinedOf: Record<string, string[]> = {};
   const aggregateInvariantOf: Record<string, string[]> = {};
   const relationOf: Record<string, string[]> = {};
+  const workspaceInvariantOf: Record<string, string[]> = {};
   const add = (map: Record<string, string[]>, key: string, domainName: string) => {
     const list = map[key] ?? (map[key] = []);
     if (!list.includes(domainName)) list.push(domainName);
@@ -316,8 +343,9 @@ export function collectEngineRouting(
     for (const type of slice.combineds.keys()) add(combinedOf, type, domainName);
     for (const type of slice.aggInvariants.keys()) add(aggregateInvariantOf, type, domainName);
     for (const relationId of slice.invariants.keys()) add(relationOf, relationId, domainName);
+    for (const wsInvariantId of slice.wsInvariants.keys()) add(workspaceInvariantOf, wsInvariantId, domainName);
   }
-  return { derivedOf, combinedOf, aggregateInvariantOf, relationOf };
+  return { derivedOf, combinedOf, aggregateInvariantOf, relationOf, workspaceInvariantOf };
 }
 
 /**
@@ -458,6 +486,80 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     return JSON.stringify(verdict);
   }
 
+  /** Every domain key whose merged module declares a given workspace invariant (routed when lazy). */
+  function wsInvariantDomains(id?: string): readonly string[] {
+    if (routing.workspaceInvariantOf !== undefined && id !== undefined) {
+      return routing.workspaceInvariantOf[id] ?? [];
+    }
+    return domainNames;
+  }
+
+  /** Resolve ONE declared workspace invariant by id (later domain wins — the one fold order). */
+  function wsInvariantById(id: string): WorkspaceInvariantDecl | undefined {
+    let found: WorkspaceInvariantDecl | undefined;
+    for (const domainName of wsInvariantDomains(id)) {
+      const hit = sliceOf(domainName)?.wsInvariants.get(id);
+      if (hit !== undefined) found = hit;
+    }
+    return found;
+  }
+
+  // ── the three WORKSPACE-INVARIANT dispatches (#266 — wire shapes are the gate oracle's
+  //    contract, EXACT: see admission-peer EngineWorkspaceInvariant + plan_workspace_invariant*) ──
+
+  /** `{workspaceInvariantList:{}}` → the DECLARED set `[{id,on},…]` sorted by id (discovery). */
+  function planWorkspaceInvariantList(): string {
+    const declared = new Map<string, { id: string; on: string }>();
+    const domains =
+      routing.workspaceInvariantOf !== undefined
+        ? [...new Set(Object.values(routing.workspaceInvariantOf).flat())]
+        : domainNames;
+    for (const domainName of domains) {
+      const slice = sliceOf(domainName);
+      if (slice === undefined) continue;
+      for (const w of slice.wsInvariants.values()) declared.set(w.id, { id: w.id, on: w.on });
+    }
+    return JSON.stringify([...declared.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)));
+  }
+
+  /** `{workspaceInvariantReads:{id}, payload}` → the bounded ref-set `[{name,aggregate,id},…]`. */
+  function planWorkspaceInvariantReads(job: {
+    intent?: { workspaceInvariantReads?: { id?: string }; payload?: unknown };
+  }): string {
+    const id = job.intent?.workspaceInvariantReads?.id;
+    if (typeof id !== "string") {
+      throw new Error(
+        `engine workspaceInvariantReads: job.intent.workspaceInvariantReads must carry {id}; got ${JSON.stringify(job.intent)}`,
+      );
+    }
+    const decl = wsInvariantById(id);
+    if (decl === undefined) {
+      throw new Error(`engine workspaceInvariantReads: no workspace invariant registered for "${id}"`);
+    }
+    const intent = (job.intent?.payload ?? {}) as Record<string, unknown>;
+    return JSON.stringify(decl.reads({ intent }));
+  }
+
+  /** `{workspaceInvariant:{id,on}, payload?}` + priorState (named snapshots) → {accept}|{reject}. */
+  function planWorkspaceInvariantAssert(job: {
+    intent?: { workspaceInvariant?: { id?: string }; payload?: unknown };
+    priorState?: Record<string, unknown>;
+  }): string {
+    const id = job.intent?.workspaceInvariant?.id;
+    if (typeof id !== "string") {
+      throw new Error(
+        `engine workspaceInvariant: job.intent.workspaceInvariant must carry {id}; got ${JSON.stringify(job.intent)}`,
+      );
+    }
+    const decl = wsInvariantById(id);
+    if (decl === undefined) {
+      throw new Error(`engine workspaceInvariant: no workspace invariant registered for "${id}"`);
+    }
+    const snapshots = (job.priorState ?? {}) as Record<string, Record<string, unknown>>;
+    const intent = (job.intent?.payload ?? {}) as Record<string, unknown>;
+    return JSON.stringify(decl.assert(snapshots, { intent }));
+  }
+
   function planDerive(job: {
     intent?: { derive?: { of?: string } };
     priorState?: Record<string, unknown>;
@@ -527,8 +629,26 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     queryRows?: unknown[];
     priorState?: Record<string, unknown>;
   }): string {
-    // Branch order mirrors emit_engine.ts: aggregateInvariant → invariant → derive →
-    // combine → report (the gate's most recent dispatch key wins over older fan-outs).
+    // Branch order mirrors emit_engine.ts: workspace-invariant trio → aggregateInvariant →
+    // invariant → derive → combine → report (the gate's most recent dispatch key wins).
+    const wsJob = job as {
+      intent?: {
+        workspaceInvariantList?: unknown;
+        workspaceInvariantReads?: { id?: string };
+        workspaceInvariant?: { id?: string };
+        payload?: unknown;
+      };
+      priorState?: Record<string, unknown>;
+    };
+    if (wsJob.intent?.workspaceInvariantList !== undefined) {
+      return planWorkspaceInvariantList();
+    }
+    if (wsJob.intent?.workspaceInvariantReads !== undefined) {
+      return planWorkspaceInvariantReads(wsJob);
+    }
+    if (wsJob.intent?.workspaceInvariant !== undefined) {
+      return planWorkspaceInvariantAssert(wsJob);
+    }
     if (job.intent?.aggregateInvariant !== undefined) {
       return planAggInvariant(
         job as { intent?: { aggregateInvariant?: { of?: string } }; priorState?: Record<string, unknown> },

package/src/framework/workspace_invariant.ts

@@ -75,9 +75,16 @@ export type WorkspaceInvariantReads = (ctx: { intent: Record<string, unknown> })
 /**
  * The post-apply predicate over the resolved snapshots, keyed by each ref's binding `name`.
  * PURE over the named map (no clock, no IO, no live reads) — runs in the sealed engine.
+ *
+ * The OPTIONAL second argument carries the authored intent payload (`ctx.intent`) — the
+ * SAME committed fact the `reads` body derived its ref-set from (never a live read), so a
+ * predicate may compare a payload-carried value against the resolved snapshots (the
+ * wrong-home homing invariant compares the payload's home key against the shard's own
+ * declared identity). Predicates that ignore it are unchanged (#266 signature, additive).
  */
 export type WorkspaceInvariantAssert = (
   snapshots: Record<string, Record<string, unknown>>,
+  ctx?: { intent: Record<string, unknown> },
 ) => WorkspaceInvariantVerdict;
 
 /** A complete, registered workspace-invariant declaration (the `.assert` terminal yields this). */

package/src/index.ts

@@ -52,6 +52,12 @@ export {
   type StrikeOp,
 } from "./ops.js";
 export { directive, type Directive, type ReferentialMarker } from "./directive.js";
+// FIRST-CLASS WORKSPACE TYPES (sharding §10 RATIFIED, slice 1) live on the SUBPATH
+// `@githolon/dsl/workspace-type` (`workspaceType("estate").root(Estate).hasMany(...)`),
+// NOT this 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; same
+// reason `build-package` is subpath-only). The decls are compile-lane: the manifest
+// lowering + homing walk + derived birth lanes consume them; the sealed engine never does.
 // THE AGGREGATE AUTHORING SURFACE (Nomos owns every birth): `create(agg)` mints + records and returns
 // a DDD-fluent `AggregateRef`; the dev `.set`/`.add`(collection)/`.setEntry`(map)/`.relate`(reference)
 // — naming no id. A directive's `.plan` calls these and returns `[]` (the recorded graph is the write