@githolon/dsl 0.2.3 → 0.4.0

package/src/manifest.ts

@@ -43,6 +43,11 @@ import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import type { CertifiedReadDecl } from "./certified_read.js";
 import type { RelationDecl } from "./relation.js";
+import { type CanonicalWorkspaceType } from "./workspace_type.js";
+import {
+  canonicalTaxonomyFragment,
+  type CanonicalDirectiveRoute,
+} from "./workspace_routing.js";
 
 /** One captured `[fieldName, zodKind]` payload field, with optionality. */
 export interface CanonicalPayloadField {
@@ -221,6 +226,13 @@ export interface CanonicalCount {
   readonly where?: CanonicalPred;
   /** The group-by field, in DECLARED form. OMITTED for a grand-total count. */
   readonly by?: string;
+  /**
+   * THE ESTATE SCOPE (sharding §5, slice 3): the workspace-type id this read is
+   * lifted to via `scoped(read, Ws)` — its per-shard values ride the §5.2 delta
+   * lane as gate-recomputed coordinator subtotals. OMITTED for home-scope reads
+   * (every pre-slice-3 count is byte-identical — the `cap(n)` discipline).
+   */
+  readonly scope?: string;
 }
 
 /**
@@ -263,6 +275,8 @@ export interface CanonicalSum {
   readonly where?: CanonicalPred;
   /** The group-by field. OMITTED for a grand-total sum. */
   readonly by?: string;
+  /** THE ESTATE SCOPE (sharding §5, slice 3) — see {@link CanonicalCount.scope}. */
+  readonly scope?: string;
 }
 
 /**
@@ -320,6 +334,12 @@ export interface CanonicalExtremum {
   readonly where?: CanonicalPred;
   /** The group-by field. OMITTED for a grand-total extremum. */
   readonly by?: string;
+  /** THE ESTATE SCOPE (sharding §5, slice 8) — see {@link CanonicalCount.scope}:
+   *  per-shard extremums ride the §5.2 delta lane as gate-adjudicated coordinator
+   *  subtotals (extremize-on-monotone; retractions re-derive). OMITTED for
+   *  home-scope extremums, so an unscoped declaration is byte-identical to before
+   *  this key existed (golden hashes UNCHANGED). */
+  readonly scope?: string;
 }
 
 /**
@@ -428,6 +448,29 @@ export interface CanonicalManifest {
    * (non-optional at both TS and manifest levels), optional predicate, and `limit`.
    */
   readonly orderedReads?: CanonicalOrderedRead[];
+  /**
+   * The domain's FIRST-CLASS WORKSPACE TYPES (sharding §10 RATIFIED, slice 1), SORTED
+   * by id. OMITTED ENTIRELY when the domain declares none — so a taxonomy-free domain
+   * is byte-identical to before this key existed (pinned golden hashes UNCHANGED; the
+   * `cap(n)` discipline). The taxonomy IS law: a type's root/mode/children/globals/
+   * pool/cap all move the domain hash (per-type optional keys omitted-when-absent).
+   */
+  readonly workspaceTypes?: CanonicalWorkspaceType[];
+  /**
+   * The DERIVED HOMING TABLE (aggregate wire id → workspace-type id) — present iff
+   * {@link workspaceTypes} is. Derived (never hand-written) by the fail-closed homing
+   * walk over the aggregates' `t.ref` chains, and HASH-BEARING: a homing move is a
+   * law change (placement of FACTS is custody, but which chain a fact is BORN into
+   * is law — the shard gate's `wrong-home` invariant pins to this table).
+   */
+  readonly homes?: Record<string, string>;
+  /**
+   * THE DERIVED DIRECTIVE ROUTING TABLE (sharding slice 2) — present only when the
+   * domain declares a taxonomy with at least one packed-homed directive, SORTED by
+   * directive id, HASH-BEARING (the client routes by it; the shard gate's typed
+   * `wrong-home` refusal pins to it). OMITTED ENTIRELY otherwise (hash-stable).
+   */
+  readonly routes?: CanonicalDirectiveRoute[];
 }
 
 /** Minimal structural view of Zod 4 schema internals we read deterministically. */
@@ -690,15 +733,16 @@ function canonicalCounts(
 ): { counts?: CanonicalCount[] } {
   if (declared === undefined || declared.length === 0) return {};
   const counts: CanonicalCount[] = [...declared]
-    .map(finishCount)
-    .map((c) => ({
+    .map((raw) => ({ finished: finishCount(raw), scope: (raw as { scope?: unknown }).scope }))
+    .map(({ finished: c, scope }) => ({
       id: c.id,
       of: c.of,
-      // OMIT-WHEN-ABSENT: `where` and `by` are omitted when not declared so a
-      // predicate-free or grand-total count is byte-identical to the legacy form
-      // (hash-stable — the same discipline as every other optional manifest key).
+      // OMIT-WHEN-ABSENT: `where`, `by` and `scope` are omitted when not declared so
+      // a predicate-free / grand-total / home-scope count is byte-identical to the
+      // legacy form (hash-stable — the same discipline as every other optional key).
       ...(c.where !== undefined ? { where: c.where } : {}),
       ...(c.by !== undefined ? { by: c.by } : {}),
+      ...(typeof scope === "string" ? { scope } : {}),
     }))
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
   return { counts };
@@ -733,13 +777,14 @@ function canonicalSpatials(
 function canonicalSums(declared: AnySum[] | undefined): { sums?: CanonicalSum[] } {
   if (declared === undefined || declared.length === 0) return {};
   const sums: CanonicalSum[] = [...declared]
-    .map(finishSum)
-    .map((s) => ({
+    .map((raw) => ({ finished: finishSum(raw), scope: (raw as { scope?: unknown }).scope }))
+    .map(({ finished: s, scope }) => ({
       id: s.id,
       of: s.of,
       sumField: s.sumField,
       ...(s.where !== undefined ? { where: s.where } : {}),
       ...(s.by !== undefined ? { by: s.by } : {}),
+      ...(typeof scope === "string" ? { scope } : {}),
     }))
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
   return { sums };
@@ -802,14 +847,17 @@ function canonicalExtrema(
 ): { mins?: CanonicalExtremum[] } | { maxes?: CanonicalExtremum[] } {
   if (declared === undefined || declared.length === 0) return {};
   const items: CanonicalExtremum[] = [...declared]
-    .map(finishExtremum)
-    .map((e) => ({
+    .map((raw) => ({ finished: finishExtremum(raw), scope: (raw as { scope?: unknown }).scope }))
+    .map(({ finished: e, scope }) => ({
       id: e.id,
       kind: e.kind,
       of: e.of,
       valueField: e.valueField,
       ...(e.where !== undefined ? { where: e.where } : {}),
       ...(e.by !== undefined ? { by: e.by } : {}),
+      // OMIT-WHEN-ABSENT (the canonicalSums discipline): a home-scope extremum is
+      // byte-identical to before the scope key existed — hash-stable by default.
+      ...(typeof scope === "string" ? { scope } : {}),
     }))
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
   return { [keyName]: items };
@@ -901,6 +949,16 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
     ...(canonicalExtrema(mod.mins, "mins") as { mins?: CanonicalExtremum[] }),
     ...(canonicalExtrema(mod.maxes, "maxes") as { maxes?: CanonicalExtremum[] }),
     ...canonicalOrderedReads(mod.orderedReads),
+    // Omit-when-empty: a taxonomy-free domain contributes NO taxonomy key (hash-
+    // stable). When declared, this RUNS the fail-closed homing walk AND the slice-2
+    // route derivation — an unhomeable or unroutable taxonomy never produces an
+    // identity (workspace_type.ts + workspace_routing.ts).
+    ...canonicalTaxonomyFragment({
+      name: mod.name,
+      aggregates: mod.aggregates,
+      directives: mod.directives,
+      ...(mod.workspaceTypes !== undefined ? { workspaceTypes: mod.workspaceTypes } : {}),
+    }),
   };
 }
 

package/src/usd.ts

@@ -170,6 +170,24 @@ export interface UsdLayer {
    * same discipline as `queries`/`references`/`reads`/`emits`).
    */
   readonly variantSets?: Record<string, Record<string, UsdPrim[]>>;
+  /**
+   * THE INVARIANT-GATE DECLARATION (#41 — "the law is the era"). Present IFF the layer's
+   * module declares ≥1 invariant (aggregate or workspace): the law's EXPLICIT opt-in to
+   * invariant EXECUTION at the one gate. The wasm gate runs the engine-backed invariant
+   * oracles for an intent only when the law resolved for that intent carries this key —
+   * every bundle compiled before #41 (whose declared invariants the gate held as hashed-
+   * but-inert law) lacks it, so chains sealed under the inert gate replay green forever.
+   * OMITTED (`undefined`) for invariant-free law — byte-identical hash, same discipline
+   * as `queries`/`references`. Hand-adding it to a foreign bundle only opts IN to
+   * stricter checking; removing it makes new law, for that law's own chains (status quo).
+   */
+  readonly nomosInvariantGate?: {
+    readonly v: 1;
+    /** Aggregate types whose declared `invariant` bodies the gate executes, sorted. */
+    readonly aggregates?: string[];
+    /** Declared workspace invariants `{id, on}` the gate executes, sorted by id. */
+    readonly workspaceInvariants?: { id: string; on: string }[];
+  };
 }
 
 /** The reserved variant name declaring a set's DEFAULT (USD has a default variant). */
@@ -239,12 +257,31 @@ export function emitUsd(
       // which already applies omit-when-empty: `queries` is present here ONLY when the
       // module declared them, so a query-free layer is byte-identical to before.
       const manifest = domainManifest(l.module);
+      // THE INVARIANT-GATE DECLARATION (#41): presence-only, derived from the SAME module
+      // the lump's executable bodies come from — sorted, omit-when-empty (hash-stable for
+      // invariant-free law; see the `UsdLayer.nomosInvariantGate` banner for the era rule).
+      const invariantAggregates = l.module.aggregates
+        .filter((a) => a.hasInvariant === true)
+        .map((a) => a.id)
+        .sort();
+      const wsInvariants = [...(l.module.workspaceInvariants ?? [])]
+        .map((w) => ({ id: w.id, on: w.on }))
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
       return {
         path: l.path,
         prims: encodeModuleToPrims(l.path, l.module),
         ...(manifest.queries !== undefined ? { queries: manifest.queries } : {}),
         ...(manifest.deriveds !== undefined ? { deriveds: manifest.deriveds } : {}),
         ...(manifest.combineds !== undefined ? { combineds: manifest.combineds } : {}),
+        ...(invariantAggregates.length > 0 || wsInvariants.length > 0
+          ? {
+              nomosInvariantGate: {
+                v: 1 as const,
+                ...(invariantAggregates.length > 0 ? { aggregates: invariantAggregates } : {}),
+                ...(wsInvariants.length > 0 ? { workspaceInvariants: wsInvariants } : {}),
+              },
+            }
+          : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));