@githolon/dsl 0.1.0

package/src/manifest.ts

@@ -0,0 +1,947 @@
+// 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.
+
+/**
+ * Domain identity = canonical SEMANTIC manifest hash (#136).
+ *
+ * "The bundle is not the law." A domain's IDENTITY in the certification gate is a
+ * content hash. Historically that hash was `sha256(stripPathMarkers(esbuild_bundle))`
+ * (see `golden/build_golden.mjs`): it depended on esbuild's output format — version,
+ * whitespace, declaration ordering — and on the domain's file LOCATION. That is
+ * fragile: a bundler upgrade or a file move changes the identity of unchanged logic.
+ *
+ * This module derives identity instead from the domain's CANONICAL MANIFEST — built
+ * directly from the in-memory DSL objects (`DomainModule`). It captures the domain's
+ * CONTRACT: its aggregates' field→driver schemas, and each directive's target /
+ * marker / required capability / scope-presence / payload SHAPE. It deliberately does
+ * NOT capture executable `plan`/`scopeFrom` BEHAVIOUR — that is a separate
+ * `artifact_hash` (out of scope here). The consequence is the desired property:
+ * refactoring a directive's `plan` body while keeping its signature identical does
+ * NOT change the domain hash. The hash tracks the contract, not the code, and is
+ * independent of both bundling AND file location while remaining sensitive to real
+ * semantic/contract changes.
+ */
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { encodeKernelSchema, encodeRefMode } from "./wire_encode.js";
+import type { WireSchema, WireRefMode } from "./wire.js";
+import type { DomainModule } from "./codegen_dart.js";
+import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
+import type { QueryDecl } from "./query.js";
+import { finishCount, type AnyCount } from "./count.js";
+import type { SpatialDecl } from "./spatial.js";
+import { finishSum, type AnySum } from "./sum.js";
+import { finishExtremum, type AnyExtremum } from "./extremum.js";
+import { existsAsCount, type AnyExists } from "./exists.js";
+import type { OrderedReadDecl } from "./ordered_read.js";
+import type { CanonicalPred } from "./predicate.js";
+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";
+
+/** One captured `[fieldName, zodKind]` payload field, with optionality. */
+export interface CanonicalPayloadField {
+  /** The payload field name. */
+  readonly name: string;
+  /** The Zod 4 `def.type` of the field's unwrapped type, e.g. "string". */
+  readonly type: string;
+  /** True when the field is `optional` / `default` wrapped. */
+  readonly optional: boolean;
+}
+
+/** One captured projected read-field return schema. */
+export interface CanonicalProjectionReturn {
+  /** The Zod 4 `def.type` of the unwrapped return type, e.g. "boolean". */
+  readonly type: string;
+  /** True when the projected value may be null/absent. */
+  readonly nullable: boolean;
+  /** The return value as standard JSON Schema, emitted from the same TS/Zod source. */
+  readonly jsonSchema: unknown;
+}
+
+/** One captured aggregate: its id + its field→driver schema (keys SORTED). */
+export interface CanonicalAggregate {
+  readonly id: string;
+  readonly schema: WireSchema;
+  /**
+   * PRESENCE ONLY — the body is executable (like a directive `plan`), NOT hashed.
+   * OMITTED ENTIRELY when absent, so a predicate-free aggregate is byte-identical
+   * in the manifest to before this field existed (golden hashes UNCHANGED).
+   */
+  readonly hasInvariant?: true;
+  /** The LAW-DECLARED instance cap; omitted when uncapped (hash-stable). */
+  readonly cap?: number;
+}
+
+/** One captured directive contract — NO `plan`/`scopeFrom` behaviour. */
+export interface CanonicalDirective {
+  readonly id: string;
+  /** The target aggregate id. */
+  readonly target: string;
+  readonly marker: WireRefMode;
+  /** The required capability — defaults to the directive id. */
+  readonly requiresCapability: string;
+  /** Whether the directive declares a `scopeFrom` (presence only, not behaviour). */
+  readonly scopeFrom: boolean;
+  /** The payload's top-level object shape as SORTED `[name, type]` pairs. */
+  readonly payload: CanonicalPayloadField[];
+  /**
+   * The directive payload as standard JSON Schema, emitted from the same TS/Zod source
+   * that the sealed GitHolon engine validates. This is the cross-language validation
+   * artifact: Dart/hosts can validate dynamic maps with a JSON Schema library without
+   * re-authoring the schema in Dart.
+   */
+  readonly payloadJsonSchema: unknown;
+  /**
+   * The directive's DECLARED read boundary (sorted ref types). The "IR for law
+   * boundaries": the boundary is part of the domain identity. OMITTED ENTIRELY when
+   * the directive declares no reads — so a boundary-free directive is byte-identical
+   * to before this key existed (pinned golden hashes stay UNCHANGED).
+   */
+  readonly reads?: string[];
+  /**
+   * The directive's DECLARED emit boundary: event type → `{ max? }`. Keys sorted by
+   * `canonicalJson`. OMITTED ENTIRELY when the directive declares no emits, for the
+   * same omit-when-empty hash-invariance reason as {@link reads}.
+   */
+  readonly emits?: Record<string, { max?: number }>;
+  /**
+   * The directive's DECLARED CertifiedReads (survival Constraint 5; `certified_read.md`): the
+   * profiled write-path reads its `decide()` consults, as `query_id → { sql, multiRow,
+   * uniqueTieBreakers }`. SORTED BY `query_id` (the SET of declared reads is the contract).
+   * Part of the domain identity: the gate DERIVES the required-read set from these `query_id`s
+   * (the vacuous-pass close), and the SQL RECIPE + shape are captured so a recipe change moves
+   * the hash (a different read = a different contract). OMITTED ENTIRELY when the directive
+   * declares no write-path read — so a read-free directive is byte-identical in the manifest to
+   * before this key existed (pinned golden hashes stay UNCHANGED).
+   */
+  readonly certifiedReads?: CanonicalCertifiedRead[];
+  /**
+   * The directive's DECLARED required HOST CAPABILITY ports (`TARGET_deps.dot` cluster_ports;
+   * the HOST/PORT axis, invariant 3): the capability ports the host must PROVIDE for the
+   * directive to run, checked FAIL-CLOSED (`required ⊆ provided`) at policy LOAD. SORTED (the
+   * SET is the contract; order is incidental). DISTINCT from {@link requiresCapability} (the
+   * AUTHZ axis "may this actor?", a single string) — this is the HOST axis "can this host
+   * physically?" (a set of open-set port ids). Part of the domain identity: a different required
+   * port is a different contract, so adding/changing one MOVES the hash. OMITTED ENTIRELY when
+   * the directive declares no host capability — so a host-capability-free directive is
+   * byte-identical in the manifest to before this key existed (pinned golden hashes stay
+   * UNCHANGED), exactly how {@link reads}/{@link relations} stay hash-neutral.
+   */
+  readonly requiresHostCapability?: string[];
+  /**
+   * The directive's DECLARED cross-workspace relations (`cross_workspace.md` §2): the relations
+   * a cross-workspace PR proposing this directive is adjudicated against. Each carries the
+   * source/target endpoints, the bounded evidence read it discloses (the disclosure contract +
+   * anti-smuggle key, §2.4), and whether an invariant guards it (PRESENCE only — the predicate
+   * body is executable behaviour, NOT hashed, exactly like a directive `plan`). SORTED BY the
+   * relation `id`. Part of the domain identity: the gate (`kernel::manifest_view`) resolves the
+   * relation by the proposed directive + verifies a carried witness against the declared evidence
+   * read; a recipe change (different aggregate/fields/predicate) MOVES the hash. OMITTED ENTIRELY
+   * when the directive declares no relation — so a relation-free directive is byte-identical in
+   * the manifest to before this key existed (pinned golden hashes stay UNCHANGED).
+   */
+  readonly relations?: CanonicalRelation[];
+}
+
+/** One captured cross-workspace relation — the SEMANTIC half of X1 in the manifest
+ * (`cross_workspace.md` §2.1 / §2.4). `id`/`source`/`target`/`proposes` are the endpoints +
+ * the proposed directive; `evidence` is the bounded declared read (disclosure contract +
+ * anti-smuggle key); `hasInvariant` is the guard's PRESENCE (the body is executable, NOT
+ * hashed). A recipe change moves the domain hash. */
+export interface CanonicalRelation {
+  readonly id: string;
+  readonly source: string;
+  readonly target: string;
+  readonly proposes: string;
+  readonly evidence: CanonicalRelationEvidence;
+  readonly hasInvariant: boolean;
+}
+
+/** The bounded evidence read a relation discloses over the SOURCE, in the manifest: the source
+ * aggregate, the exact SELECT fields (SORTED — the set is the contract), the WHERE predicate,
+ * and the freshness `kind`. This IS the disclosure contract + the anti-smuggle key. */
+export interface CanonicalRelationEvidence {
+  readonly aggregate: string;
+  readonly select: string[];
+  readonly where: string;
+  readonly kind: string;
+}
+
+/** One captured DECLARED CertifiedRead — the profiled write-path read identity in the manifest.
+ * `queryId` is the gate's required-read key; `sql`/`multiRow`/`uniqueTieBreakers` are the recipe
+ * + shape the admission re-run + the profile pin (a recipe change moves the domain hash). */
+export interface CanonicalCertifiedRead {
+  readonly queryId: string;
+  readonly sql: string;
+  readonly multiRow: boolean;
+  readonly uniqueTieBreakers: string[];
+}
+
+/**
+ * One captured query declaration — the read-side closure's named, INDEXED read.
+ * `key` is the index column order, PRESERVED (NOT sorted): the order of the index
+ * key fields is part of the contract, so two queries differing only in key order
+ * are distinct identities.
+ */
+export interface CanonicalQuery {
+  readonly id: string;
+  /** Index key fields, in DECLARED order (index column order — preserved). */
+  readonly key: string[];
+  /** The aggregate TYPE id the query returns, e.g. `SampleThingAggregate`. */
+  readonly returns: string;
+}
+
+/**
+ * One captured count declaration — the read-side closure's named, MAINTAINED tally.
+ * Mirrors {@link CanonicalQuery}: a count's `of`-type + (optional) `where` predicate +
+ * (optional) `by` group-by field are part of the domain CONTRACT (changing them changes
+ * the maintained counter), so they are part of the identity.
+ *
+ * OMIT-WHEN-ABSENT:
+ *   `where` is OMITTED ENTIRELY for a predicate-free count — so an unfiltered count is
+ *   byte-identical in the manifest to before `where` existed (golden hashes UNCHANGED).
+ *   `by` is OMITTED ENTIRELY for a grand-total count (same discipline, always was).
+ */
+export interface CanonicalCount {
+  readonly id: string;
+  /** The aggregate TYPE id the count tallies, e.g. `SiteRootAggregate`. */
+  readonly of: string;
+  /**
+   * The predicate filtering which aggregates are counted. OMITTED when no predicate
+   * (an unfiltered count is byte-identical in the manifest to before this existed).
+   * The canonical form is insertion-order–independent (clauses sorted deterministically
+   * by `canonicalizePred`), so byte-identical predicate logic → byte-identical hash.
+   */
+  readonly where?: CanonicalPred;
+  /** The group-by field, in DECLARED form. OMITTED for a grand-total count. */
+  readonly by?: string;
+}
+
+/**
+ * One captured SPATIAL index declaration — the read-side closure's named, MAINTAINED
+ * GEOSPATIAL (R*Tree) index. Mirrors {@link CanonicalCount}: a spatial index's `of`-type and
+ * the geometry field it indexes (`on`) are part of the domain CONTRACT (changing either
+ * changes the maintained bounding-box index), so they are part of the identity. There is no
+ * optional/omit-when-absent sub-field — both `id`/`of`/`on` are always present.
+ */
+export interface CanonicalSpatial {
+  readonly id: string;
+  /** The aggregate TYPE id the spatial index covers, e.g. `TrackableAsset`. */
+  readonly of: string;
+  /** The GeoJSON geometry field whose bounding box is indexed, e.g. `geoPosition`. */
+  readonly on: string;
+}
+
+/**
+ * One captured sum declaration — the read-side closure's named, MAINTAINED numeric
+ * aggregation. Analogous to {@link CanonicalCount}: a sum's `of`-type, `sumField`,
+ * optional `where` predicate, and optional `by` group-by field are all part of the
+ * domain CONTRACT. Changing any of them changes the meaning of the maintained total.
+ *
+ * OMIT-WHEN-ABSENT: `where` and `by` are OMITTED ENTIRELY when not declared — so a
+ * predicate-free, grand-total sum is byte-identical to the minimal `{id, of, sumField}`
+ * form (golden hashes stable). Same discipline as {@link CanonicalCount}.
+ */
+export interface CanonicalSum {
+  readonly id: string;
+  /** The aggregate TYPE id the sum tallies. */
+  readonly of: string;
+  /**
+   * The `int`-kind field whose values are accumulated, e.g. `"itemValue"`. MUST be
+   * an `int`-kind field of the `of`-aggregate (validated at manifest-load in Rust).
+   */
+  readonly sumField: string;
+  /**
+   * The predicate filtering which aggregates contribute. OMITTED when no predicate.
+   */
+  readonly where?: CanonicalPred;
+  /** The group-by field. OMITTED for a grand-total sum. */
+  readonly by?: string;
+}
+
+/**
+ * One captured DERIVED read field — the read-side closure's engine-projected pure field.
+ * Mirrors {@link CanonicalCount}: a derived field's NAME (`id`) + the aggregate it derives
+ * from (`of`) are part of the domain CONTRACT (the read schema), so they are part of the
+ * identity. The fn BODY is DELIBERATELY NOT captured — it is executable behaviour, exactly
+ * like a directive's `plan` (which `domainManifest` also omits), so refactoring the derive
+ * fn while keeping its `(id, of)` identical does NOT change the domain hash.
+ */
+export interface CanonicalDerived {
+  readonly id: string;
+  /** The aggregate TYPE id the field is derived from, e.g. `SupportSessionAggregate`. */
+  readonly of: string;
+  /** The projected value schema. The fn body is not hashed; the value contract is. */
+  readonly returns: CanonicalProjectionReturn;
+}
+
+/**
+ * One captured COMBINED read field — the read-side closure's engine-projected CROSS-
+ * AGGREGATE JOIN field. Mirrors {@link CanonicalDerived} but with the JOIN axis: a
+ * combined field's NAME (`id`), the OWNER aggregate (`of`), the REF FIELD it joins
+ * through (`refField`), and the RELATED type it queries (`reads`) are all part of the
+ * domain CONTRACT (the read schema + the cross-aggregate invalidation edge), so they are
+ * part of the identity. The fn BODY is DELIBERATELY NOT captured — executable behaviour,
+ * exactly like a directive's `plan` / a derived field's fn, so refactoring the compose fn
+ * while keeping its `(id, of, refField, reads)` identical does NOT change the domain hash.
+ */
+export interface CanonicalCombined {
+  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 invalidation key), e.g. `SiteRootAggregate`. */
+  readonly reads: string;
+  /** The projected value schema. The fn body is not hashed; the value contract is. */
+  readonly returns: CanonicalProjectionReturn;
+}
+
+/**
+ * One captured MIN or MAX declaration — structurally identical to {@link CanonicalSum}
+ * (same `of`/`valueField`/`where?`/`by?` shape) except it carries an explicit `kind`
+ * discriminant (`"min"` | `"max"`). OMIT-WHEN-ABSENT: `where` and `by` follow the same
+ * omit-when-not-declared discipline as `CanonicalSum`.
+ */
+export interface CanonicalExtremum {
+  readonly id: string;
+  readonly kind: "min" | "max";
+  /** The aggregate TYPE id the extremum tallies. */
+  readonly of: string;
+  /** The `int`-kind field being extremised. */
+  readonly valueField: string;
+  /** The predicate filtering which aggregates contribute. OMITTED when no predicate. */
+  readonly where?: CanonicalPred;
+  /** The group-by field. OMITTED for a grand-total extremum. */
+  readonly by?: string;
+}
+
+/**
+ * One captured ORDERED READ declaration — an order-sensitive row read with a MANDATORY
+ * declared total order. `orderKey` is NON-OPTIONAL (a missing key is a manifest
+ * validation error, rejected LOUDLY at parse with no fallback). `limit` = 1 for `first`,
+ * `n` for `take(n)`. OMIT-WHEN-ABSENT: `where` is omitted when no predicate.
+ */
+export interface CanonicalOrderedRead {
+  readonly id: string;
+  /** The aggregate TYPE id the read returns. */
+  readonly of: string;
+  /** The REQUIRED total-order key (a declared scalar field of `of`). */
+  readonly orderKey: string;
+  /** Whether to sort descending. Default absent = ascending. */
+  readonly orderDesc?: true;
+  /** The optional predicate. OMITTED when no predicate. */
+  readonly where?: CanonicalPred;
+  /** LIMIT — 1 for `first`, n for `take(n)`. */
+  readonly limit: number;
+}
+
+/**
+ * A workspace invariant's PRESENCE in the hashed identity surface (#266): its id + the
+ * directive it fires `on`. PRESENCE ONLY — the executable `reads`/`assert` bodies are NOT
+ * hashed (they ship in the engine bundle), exactly like the aggregate `hasInvariant` flag.
+ * Changing a body does NOT move the domain hash; adding/removing an invariant DOES (it is law).
+ */
+export interface CanonicalWorkspaceInvariant {
+  readonly id: string;
+  readonly on: string;
+}
+
+/** A domain's canonical semantic manifest — the hashed identity surface. */
+export interface CanonicalManifest {
+  readonly domain: string;
+  readonly aggregates: CanonicalAggregate[];
+  readonly directives: CanonicalDirective[];
+  /**
+   * The domain's WORKSPACE INVARIANTS (#266), SORTED by id, PRESENCE ONLY (id + `on`).
+   * OMITTED ENTIRELY when the domain declares none — so an invariant-free domain is
+   * byte-identical to before this key existed (pinned golden hashes UNCHANGED).
+   */
+  readonly workspaceInvariants?: CanonicalWorkspaceInvariant[];
+  /**
+   * The domain's NAMED, INDEXED read declarations, SORTED by id. OMITTED ENTIRELY
+   * when the domain declares no query — so a query-free domain is byte-identical to
+   * before this key existed (the pinned golden hash stays UNCHANGED). Each query's
+   * `key` preserves its DECLARED order (index column order), unlike a directive's
+   * incidental read SET.
+   */
+  readonly queries?: CanonicalQuery[];
+  /**
+   * The domain's NAMED, MAINTAINED count declarations, SORTED by id. OMITTED ENTIRELY
+   * when the domain declares no count — so a count-free domain is byte-identical to
+   * before this key existed (the pinned golden hash stays UNCHANGED), exactly like
+   * {@link queries}. The aggregation analogue of the read-side closure. Each entry may
+   * carry an optional `where` predicate (Slice 1 — omit-when-absent; predicate-free
+   * counts are byte-identical to before `where` was introduced).
+   */
+  readonly counts?: CanonicalCount[];
+  /**
+   * The domain's NAMED, MAINTAINED SPATIAL (R*Tree) index declarations, SORTED by id.
+   * OMITTED ENTIRELY when the domain declares no spatial index — so a spatial-free domain is
+   * byte-identical to before this key existed (the pinned golden hash stays UNCHANGED),
+   * exactly like {@link counts}. The geospatial analogue of the read-side closure. Each entry
+   * carries `{id, of, on}` — the geometry field whose bounding box the engine maintains.
+   */
+  readonly spatials?: CanonicalSpatial[];
+  /**
+   * The domain's NAMED, MAINTAINED sum declarations, SORTED by id. OMITTED ENTIRELY
+   * when the domain declares no sum — so a sum-free domain is byte-identical to before
+   * this key existed (the pinned golden hash stays UNCHANGED), exactly like
+   * {@link counts}. The numeric-accumulation analogue of count (Slice 1).
+   */
+  readonly sums?: CanonicalSum[];
+  /**
+   * The domain's DERIVED read-field declarations, SORTED by id. OMITTED ENTIRELY when the
+   * domain declares no derived field — so a derived-free domain is byte-identical to before
+   * this key existed (the pinned golden hash stays UNCHANGED), exactly like {@link counts}.
+   * Each carries ONLY `{id, of}` — the fn body is NOT hashed (executable behaviour, like a
+   * directive's `plan`).
+   */
+  readonly deriveds?: CanonicalDerived[];
+  /**
+   * The domain's COMBINED read-field declarations, SORTED by id. OMITTED ENTIRELY when the
+   * domain declares no combined field — so a combined-free domain is byte-identical to
+   * before this key existed (the pinned golden hash stays UNCHANGED), exactly like
+   * {@link deriveds}. Each carries `{id, of, refField, reads}` — the fn body is NOT hashed.
+   */
+  readonly combineds?: CanonicalCombined[];
+  /**
+   * The domain's MAINTAINED MIN declarations, SORTED by id. OMITTED ENTIRELY when the
+   * domain declares no min — so a min-free domain is byte-identical to before this key
+   * existed (golden hashes unchanged). Same omit-when-absent discipline as `sums`.
+   */
+  readonly mins?: CanonicalExtremum[];
+  /**
+   * The domain's MAINTAINED MAX declarations, SORTED by id. OMITTED ENTIRELY when the
+   * domain declares no max. Same discipline as `mins`.
+   */
+  readonly maxes?: CanonicalExtremum[];
+  /**
+   * The domain's ORDERED ROW READ declarations (first/take.orderBy), SORTED by id.
+   * OMITTED ENTIRELY when the domain declares none. Each carries the REQUIRED `orderKey`
+   * (non-optional at both TS and manifest levels), optional predicate, and `limit`.
+   */
+  readonly orderedReads?: CanonicalOrderedRead[];
+}
+
+/** Minimal structural view of Zod 4 schema internals we read deterministically. */
+interface ZodLike {
+  _def?: {
+    type?: string;
+    innerType?: ZodLike;
+    shape?: Record<string, ZodLike> | (() => Record<string, ZodLike>);
+  };
+  def?: {
+    type?: string;
+    innerType?: ZodLike;
+    shape?: Record<string, ZodLike> | (() => Record<string, ZodLike>);
+  };
+  shape?: Record<string, ZodLike>;
+}
+
+function zodDef(zod: ZodLike): NonNullable<ZodLike["_def"]> {
+  return zod._def ?? zod.def ?? {};
+}
+
+function zodTypeName(zod: ZodLike): string {
+  const def = zodDef(zod);
+  return def.type ?? "unknown";
+}
+
+function zodObjectShape(zod: ZodLike): Record<string, ZodLike> | undefined {
+  const shape = zodDef(zod).shape;
+  if (typeof shape === "function") return shape();
+  if (shape !== undefined) return shape;
+  return zod.shape;
+}
+
+/**
+ * Sort an object's keys so the schema's field order is irrelevant to identity. The
+ * authored field order on an aggregate or payload is incidental; only the SET of
+ * field→driver / field→type pairs is the contract.
+ */
+function sortedSchema(schema: WireSchema): WireSchema {
+  const out: WireSchema = {};
+  for (const key of Object.keys(schema).sort()) out[key] = schema[key]!;
+  return out;
+}
+
+/**
+ * Unwrap ZodOptional / ZodDefault to recover `{ optional, type }`. The OPTIONALITY
+ * is part of the contract (an optional field is a different shape); the wrapper
+ * identity (Optional vs Default) is NOT — both mean "may be absent" to a caller.
+ */
+function unwrapPayloadType(zod: ZodLike): { optional: boolean; type: string } {
+  let cur = zod;
+  let optional = false;
+  // Peel optional/default wrappers (possibly nested) to the inner contract type.
+  while (zodTypeName(cur) === "optional" || zodTypeName(cur) === "default") {
+    optional = true;
+    const inner = zodDef(cur).innerType;
+    if (inner === undefined) break;
+    cur = inner;
+  }
+  return { optional, type: zodTypeName(cur) };
+}
+
+function unwrapProjectionReturn(zod: ZodLike): { nullable: boolean; type: string } {
+  let cur = zod;
+  let nullable = false;
+  while (
+    zodTypeName(cur) === "optional" ||
+    zodTypeName(cur) === "default" ||
+    zodTypeName(cur) === "nullable"
+  ) {
+    nullable = true;
+    const inner = zodDef(cur).innerType;
+    if (inner === undefined) break;
+    cur = inner;
+  }
+  return { nullable, type: zodTypeName(cur) };
+}
+
+function canonicalProjectionReturn(schema: unknown): CanonicalProjectionReturn {
+  const { nullable, type } = unwrapProjectionReturn(schema as ZodLike);
+  return {
+    type,
+    nullable,
+    jsonSchema: z.toJSONSchema(schema as z.ZodTypeAny),
+  };
+}
+
+/**
+ * Canonically capture a directive's payload: the top-level object's fields as
+ * SORTED `[name, type]` pairs (with optionality). A non-object top-level schema
+ * (rare) captures as a single synthetic field carrying its type name.
+ */
+function canonicalPayload(payloadSchema: unknown): CanonicalPayloadField[] {
+  const zod = payloadSchema as ZodLike;
+  const shape = zodObjectShape(zod);
+  if (zodTypeName(zod) !== "object" || shape === undefined) {
+    // Not a top-level object: thing the bare type so a shape change still moves
+    // the hash, without inventing field structure.
+    return [{ name: "", type: zodTypeName(zod), optional: false }];
+  }
+  return Object.keys(shape)
+    .sort()
+    .map((name) => {
+      const { optional, type } = unwrapPayloadType(shape[name]!);
+      return { name, type, optional };
+    });
+}
+
+function canonicalPayloadJsonSchema(payloadSchema: unknown): unknown {
+  return z.toJSONSchema(payloadSchema as z.ZodTypeAny);
+}
+
+/**
+ * Canonicalize a directive's declared READ boundary into a manifest fragment.
+ * OMIT-WHEN-EMPTY: returns `{}` (no `reads` key at all) when nothing is declared —
+ * the omission, not an empty array, is what keeps boundary-free hashes unchanged.
+ * When non-empty, returns a SORTED `reads` array (order is incidental to the boundary).
+ */
+function canonicalReads(declared: string[]): { reads?: string[] } {
+  if (declared.length === 0) return {};
+  return { reads: [...declared].sort() };
+}
+
+/**
+ * Canonicalize a directive's declared required HOST CAPABILITY ports into a manifest fragment
+ * (the HOST/PORT axis, invariant 3). OMIT-WHEN-EMPTY: returns `{}` (no `requiresHostCapability`
+ * key at all) when the directive declares none — the omission, not an empty array, is what keeps
+ * host-capability-free hashes UNCHANGED. When non-empty, returns a SORTED `requiresHostCapability`
+ * array (order is incidental to the port SET). DISTINCT from `canonicalReads`/`requiresCapability`
+ * (the two axes — HOST vs AUTHZ — never conflate in the manifest).
+ */
+function canonicalHostCapabilities(declared: string[]): { requiresHostCapability?: string[] } {
+  if (declared.length === 0) return {};
+  return { requiresHostCapability: [...declared].sort() };
+}
+
+/**
+ * Canonicalize a directive's declared EMIT boundary into a manifest fragment.
+ * OMIT-WHEN-EMPTY: returns `{}` (no `emits` key) when nothing is declared. When
+ * non-empty, returns an `emits` object whose keys `canonicalJson` will sort, each
+ * value `{ max }` only when a bound is set (so `{}` vs `{max}` differs in identity).
+ */
+function canonicalEmits(
+  declared: Record<string, { max?: number }>,
+): { emits?: Record<string, { max?: number }> } {
+  const keys = Object.keys(declared);
+  if (keys.length === 0) return {};
+  const emits: Record<string, { max?: number }> = {};
+  for (const key of keys.sort()) {
+    const max = declared[key]!.max;
+    emits[key] = max !== undefined ? { max } : {};
+  }
+  return { emits };
+}
+
+/**
+ * Canonicalize a directive's declared CertifiedReads into a manifest fragment (survival
+ * Constraint 5). OMIT-WHEN-EMPTY: returns `{}` (no `certifiedReads` key) when the directive
+ * declares none — the omission keeps read-free hashes unchanged. When non-empty, returns a
+ * `certifiedReads` array SORTED BY `queryId` (the SET of declared reads is the contract), each
+ * carrying its `queryId` + the profiled `sql`/`multiRow`/`uniqueTieBreakers` recipe (so a recipe
+ * change moves the domain hash — a different read is a different contract). The local binding
+ * NAME (the `reads:{}` key) is incidental to identity (it is `decide`'s ergonomics), so it is
+ * NOT captured — only the `query_id` + recipe.
+ */
+function canonicalCertifiedReads(
+  declared: Record<string, CertifiedReadDecl>,
+): { certifiedReads?: CanonicalCertifiedRead[] } {
+  const decls = Object.values(declared);
+  if (decls.length === 0) return {};
+  const certifiedReads: CanonicalCertifiedRead[] = decls
+    .map((d) => ({
+      queryId: d.queryId,
+      sql: d.sql,
+      multiRow: d.multiRow,
+      uniqueTieBreakers: [...d.uniqueTieBreakers],
+    }))
+    .sort((a, b) => (a.queryId < b.queryId ? -1 : a.queryId > b.queryId ? 1 : 0));
+  return { certifiedReads };
+}
+
+/**
+ * Canonicalize a directive's declared cross-workspace relations into a manifest fragment
+ * (`cross_workspace.md` §2). OMIT-WHEN-EMPTY: returns `{}` (no `relations` key) when the
+ * directive declares none — the omission keeps relation-free hashes unchanged. When non-empty,
+ * a `relations` array SORTED BY relation `id`, each carrying the endpoints + the bounded
+ * evidence read (SELECT fields SORTED) + `hasInvariant` (presence only). A recipe change
+ * (aggregate/fields/predicate) MOVES the domain hash — a different relation is a different
+ * contract. The invariant PREDICATE body is NOT captured (executable behaviour, like `plan`).
+ */
+function canonicalRelations(
+  declared: RelationDecl[],
+): { relations?: CanonicalRelation[] } {
+  if (declared.length === 0) return {};
+  const relations: CanonicalRelation[] = declared
+    .map((r) => ({
+      id: r.id,
+      source: r.source,
+      target: r.target,
+      proposes: r.proposes,
+      evidence: {
+        aggregate: r.evidence.aggregate,
+        select: [...r.evidence.select].sort(),
+        where: r.evidence.where,
+        kind: r.evidence.kind,
+      },
+      hasInvariant: r.hasInvariant,
+    }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { relations };
+}
+
+/**
+ * Canonicalize a domain's declared QUERIES into a manifest fragment.
+ * OMIT-WHEN-EMPTY: returns `{}` (no `queries` key at all) when the domain declares
+ * none — the omission, not an empty array, is what keeps query-free hashes unchanged.
+ * When non-empty, returns a `queries` array SORTED by id (the SET of queries is the
+ * contract), each carrying its `key` in DECLARED order (index column order, NOT
+ * sorted) and its `returns` aggregate type id.
+ */
+function canonicalQueries(
+  declared: QueryDecl[] | undefined,
+): { queries?: CanonicalQuery[] } {
+  if (declared === undefined || declared.length === 0) return {};
+  const queries: CanonicalQuery[] = [...declared]
+    .map((q) => ({ id: q.id, key: [...q.key], returns: q.returns }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { queries };
+}
+
+/**
+ * Canonicalize a domain's WORKSPACE INVARIANTS into a manifest fragment (#266) — the
+ * presence-only analogue of {@link canonicalQueries}. OMIT-WHEN-EMPTY: returns `{}` (no key)
+ * when none are declared, so an invariant-free domain hashes identically to before. Each entry
+ * is PRESENCE ONLY (id + the directive it is `on`), SORTED by id; the executable `reads`/
+ * `assert` bodies are NEVER hashed (they ship in the engine bundle). So changing a body leaves
+ * the hash unchanged, while adding/removing an invariant moves it (it is law — #131).
+ */
+function canonicalWorkspaceInvariants(
+  declared: WorkspaceInvariantDecl[] | undefined,
+): { workspaceInvariants?: CanonicalWorkspaceInvariant[] } {
+  if (declared === undefined || declared.length === 0) return {};
+  const workspaceInvariants: CanonicalWorkspaceInvariant[] = [...declared]
+    .map((wi) => ({ id: wi.id, on: wi.on }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { workspaceInvariants };
+}
+
+/**
+ * Canonicalize a domain's declared COUNTS into a manifest fragment — the aggregation
+ * analogue of {@link canonicalQueries}.
+ * OMIT-WHEN-EMPTY: returns `{}` (no `counts` key at all) when the domain declares none —
+ * the omission, not an empty array, is what keeps count-free hashes unchanged. When
+ * non-empty, returns a `counts` array SORTED by id (the SET of counts is the contract),
+ * each carrying its `of`-type and — only when declared — its `by` group-by field (a
+ * grand-total count omits `by` entirely, so it adds no phantom key to the hash).
+ */
+function canonicalCounts(
+  declared: AnyCount[] | undefined,
+): { counts?: CanonicalCount[] } {
+  if (declared === undefined || declared.length === 0) return {};
+  const counts: CanonicalCount[] = [...declared]
+    .map(finishCount)
+    .map((c) => ({
+      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).
+      ...(c.where !== undefined ? { where: c.where } : {}),
+      ...(c.by !== undefined ? { by: c.by } : {}),
+    }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { counts };
+}
+
+/**
+ * Canonicalize a domain's declared SPATIAL indexes into a manifest fragment — the
+ * geospatial analogue of {@link canonicalCounts}.
+ * OMIT-WHEN-EMPTY: returns `{}` (no `spatials` key at all) when the domain declares none —
+ * the omission, not an empty array, is what keeps spatial-free hashes unchanged. When
+ * non-empty, returns a `spatials` array SORTED by id (the SET of spatial indexes is the
+ * contract), each carrying its `of`-type and the `on` geometry field whose bounding box is
+ * indexed.
+ */
+function canonicalSpatials(
+  declared: SpatialDecl[] | undefined,
+): { spatials?: CanonicalSpatial[] } {
+  if (declared === undefined || declared.length === 0) return {};
+  const spatials: CanonicalSpatial[] = [...declared]
+    .map((s) => ({ id: s.id, of: s.of, on: s.on }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { spatials };
+}
+
+/**
+ * Canonicalize a domain's declared SUMS into a manifest fragment — the numeric-
+ * accumulation analogue of {@link canonicalCounts}.
+ * OMIT-WHEN-EMPTY: returns `{}` (no `sums` key at all) when the domain declares none.
+ * When non-empty, returns a `sums` array SORTED by id. `where` and `by` are omitted
+ * when not declared (same omit-when-absent discipline as `CanonicalCount`).
+ */
+function canonicalSums(declared: AnySum[] | undefined): { sums?: CanonicalSum[] } {
+  if (declared === undefined || declared.length === 0) return {};
+  const sums: CanonicalSum[] = [...declared]
+    .map(finishSum)
+    .map((s) => ({
+      id: s.id,
+      of: s.of,
+      sumField: s.sumField,
+      ...(s.where !== undefined ? { where: s.where } : {}),
+      ...(s.by !== undefined ? { by: s.by } : {}),
+    }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { sums };
+}
+
+/**
+ * Canonicalize a domain's declared DERIVED read fields into a manifest fragment — the
+ * engine-projected analogue of {@link canonicalCounts}.
+ * OMIT-WHEN-EMPTY: returns `{}` (no `deriveds` key at all) when the domain declares none —
+ * the omission, not an empty array, is what keeps derived-free hashes unchanged. When
+ * non-empty, returns a `deriveds` array SORTED by id (the SET of derived fields is the
+ * contract), each carrying ONLY its `{id, of}` — the fn BODY is NOT hashed (executable
+ * behaviour, exactly like a directive's `plan` body, which this manifest also omits).
+ */
+function canonicalDeriveds(
+  declared: DerivedDecl[] | undefined,
+): { deriveds?: CanonicalDerived[] } {
+  if (declared === undefined || declared.length === 0) return {};
+  const deriveds: CanonicalDerived[] = [...declared]
+    .map((d) => ({ id: d.id, of: d.of, returns: canonicalProjectionReturn(d.returns) }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { deriveds };
+}
+
+/**
+ * Canonicalize a domain's declared COMBINED read fields into a manifest fragment — the
+ * cross-aggregate JOIN analogue of {@link canonicalDeriveds}.
+ * OMIT-WHEN-EMPTY: returns `{}` (no `combineds` key at all) when the domain declares none —
+ * the omission, not an empty array, is what keeps combined-free hashes unchanged. When
+ * non-empty, returns a `combineds` array SORTED by id (the SET of combined fields is the
+ * contract), each carrying `{id, of, refField, reads}` — the JOIN edge + invalidation key
+ * are part of the contract; the fn BODY is NOT hashed (executable behaviour, like a
+ * directive's `plan` body, which this manifest also omits).
+ */
+function canonicalCombineds(
+  declared: CombinedDecl[] | undefined,
+): { combineds?: CanonicalCombined[] } {
+  if (declared === undefined || declared.length === 0) return {};
+  const combineds: CanonicalCombined[] = [...declared]
+    .map((c) => ({
+      id: c.id,
+      of: c.of,
+      refField: c.refField,
+      reads: c.reads,
+      returns: canonicalProjectionReturn(c.returns),
+    }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { combineds };
+}
+
+/**
+ * Canonicalize a domain's declared MINS or MAXES into a manifest fragment.
+ * OMIT-WHEN-EMPTY: returns `{}` (no key at all) when the domain declares none.
+ * When non-empty, returns the array SORTED by id. `where` and `by` follow the same
+ * omit-when-not-declared discipline as {@link canonicalSums}.
+ */
+function canonicalExtrema(
+  declared: AnyExtremum[] | undefined,
+  keyName: "mins" | "maxes",
+): { mins?: CanonicalExtremum[] } | { maxes?: CanonicalExtremum[] } {
+  if (declared === undefined || declared.length === 0) return {};
+  const items: CanonicalExtremum[] = [...declared]
+    .map(finishExtremum)
+    .map((e) => ({
+      id: e.id,
+      kind: e.kind,
+      of: e.of,
+      valueField: e.valueField,
+      ...(e.where !== undefined ? { where: e.where } : {}),
+      ...(e.by !== undefined ? { by: e.by } : {}),
+    }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { [keyName]: items };
+}
+
+/**
+ * Canonicalize a domain's declared ORDERED READS (first/take) into a manifest fragment.
+ * OMIT-WHEN-EMPTY: returns `{}` (no key at all) when the domain declares none.
+ * When non-empty, returns an `orderedReads` array SORTED by id. `where` is omitted when
+ * not declared; `orderDesc` is omitted when false (default = ascending). `orderKey` is
+ * ALWAYS present (it is required — never optional).
+ */
+function canonicalOrderedReads(
+  declared: OrderedReadDecl[] | undefined,
+): { orderedReads?: CanonicalOrderedRead[] } {
+  if (declared === undefined || declared.length === 0) return {};
+  const items: CanonicalOrderedRead[] = [...declared]
+    .map((d) => ({
+      id: d.id,
+      of: d.of,
+      orderKey: d.orderKey,
+      // OMIT-WHEN-DEFAULT: only include `orderDesc` when it is `true` (non-default).
+      ...(d.orderDesc ? { orderDesc: true as const } : {}),
+      ...(d.where !== undefined ? { where: d.where } : {}),
+      limit: d.limit,
+    }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { orderedReads: items };
+}
+
+/**
+ * Build the canonical semantic manifest for a domain module — purely from the
+ * in-memory DSL objects. No file reads, no bundle, no esbuild: the manifest is a
+ * function of the module alone, so it is bundler- AND location-independent.
+ */
+export function domainManifest(mod: DomainModule): CanonicalManifest {
+  const aggregates: CanonicalAggregate[] = mod.aggregates
+    .map((agg) => ({
+      id: agg.id,
+      schema: sortedSchema(encodeKernelSchema(agg)),
+      // OMIT-WHEN-ABSENT: only emit `hasInvariant` when the aggregate declares one,
+      // so a predicate-free aggregate is byte-identical in the manifest to before this
+      // key existed (golden hashes UNCHANGED — mirrors directive `plan` omission).
+      ...(agg.hasInvariant === true ? { hasInvariant: true as const } : {}),
+      // The LAW-DECLARED instance cap — hash-bearing (it IS law), omit-when-absent.
+      ...(agg.cap !== undefined ? { cap: agg.cap } : {}),
+    }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  const directives: CanonicalDirective[] = mod.directives
+    .map((d) => ({
+      id: d.id,
+      target: d.aggregateId,
+      marker: encodeRefMode(d.marker),
+      requiresCapability: d.requiresCapability ?? d.id,
+      scopeFrom: d.scopeFrom !== undefined,
+      payload: canonicalPayload(d.payloadSchema),
+      payloadJsonSchema: canonicalPayloadJsonSchema(d.payloadSchema),
+      // Omit-when-empty: a directive declaring NO boundary contributes neither key,
+      // so its canonical manifest is byte-identical to before the boundary existed.
+      ...canonicalReads(d.declaredReads),
+      ...canonicalEmits(d.declaredEmits),
+      ...canonicalCertifiedReads(d.declaredCertifiedReads),
+      ...canonicalRelations(d.declaredRelations),
+      ...canonicalHostCapabilities(d.declaredHostCapabilities),
+    }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  // exists_ entries are COUNT declarations in the IR — merge them into `counts` so the
+  // Rust engine sees them as ordinary counts (the marker lives only in the DSL/codegen
+  // layer). Combine mod.counts + normalized exists_ before canonicalizing counts.
+  const existsAsCountDecls: AnyCount[] = (mod.exists_ ?? []).map(existsAsCount);
+  const allCounts: AnyCount[] = [...(mod.counts ?? []), ...existsAsCountDecls];
+
+  // Omit-when-empty: a domain declaring NO query / NO count / NO sum contributes neither
+  // key, so its canonical manifest is byte-identical to before the read-closure layer
+  // existed. `sums` follows the same omit-when-empty discipline as `counts`.
+  return {
+    domain: mod.name,
+    aggregates,
+    directives,
+    ...canonicalWorkspaceInvariants(mod.workspaceInvariants),
+    ...canonicalQueries(mod.queries),
+    ...canonicalCounts(allCounts.length > 0 ? allCounts : undefined),
+    ...canonicalSpatials(mod.spatials),
+    ...canonicalSums(mod.sums),
+    ...canonicalDeriveds(mod.deriveds),
+    ...canonicalCombineds(mod.combineds),
+    ...(canonicalExtrema(mod.mins, "mins") as { mins?: CanonicalExtremum[] }),
+    ...(canonicalExtrema(mod.maxes, "maxes") as { maxes?: CanonicalExtremum[] }),
+    ...canonicalOrderedReads(mod.orderedReads),
+  };
+}
+
+/** Recursively sort object keys; arrays are already in sorted/stable order. */
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(obj).sort()) out[key] = canonicalize(obj[key]);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Serialize ANY value to JSON with recursively SORTED object keys (byte-stable).
+ * Used for the domain manifest here AND reused by the composed-IR layer (#137) to
+ * hash a flattened stage — the canonicalizer is value-generic, so the input type is
+ * `unknown` rather than narrowed to `CanonicalManifest`.
+ */
+export function canonicalJson(manifest: unknown): string {
+  return JSON.stringify(canonicalize(manifest));
+}
+
+/** The domain's content-hash identity: sha256 hex of its canonical manifest JSON. */
+export function domainHash(mod: DomainModule): string {
+  return createHash("sha256").update(canonicalJson(domainManifest(mod)), "utf8").digest("hex");
+}
+
+/**
+ * The SHIPPED ARTIFACT bytes for a domain (#136) — the EXACT canonical-manifest JSON
+ * bytes whose sha256 IS the domain's identity. This is the byte string an emit step
+ * writes to `<domain>.manifest.json` and the gate's reproducibility check recomputes
+ * `hash_code` over. The invariant the whole gate rests on:
+ *
+ *   sha256(emitManifestBytes(mod)) === domainHash(mod)
+ *
+ * i.e. the file bytes equal the bytes `domainHash` hashes (compact, recursively
+ * sorted keys, UTF-8). "The bundle is not the law" — THIS is.
+ */
+export function emitManifestBytes(mod: DomainModule): Buffer {
+  return Buffer.from(canonicalJson(domainManifest(mod)), "utf8");
+}