@githolon/dsl 0.65.0 → 0.66.0

package/dart/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.43.0
+
+- `NomosBridge.foreignReader({cloud})` — a `NomosForeignReader` backed by the device's multi-workspace bridge
+  plane, so a generated `ForeignRef` (`t.foreignRef`) resolves against real data: it mounts the foreign
+  workspace on demand (`connect(session: ws, allowUnborn: true)`, idempotent) and reads it
+  (`session(ws).queryById(id)`); `watch` re-reads on each sync tick. A locator resolver, not a foreign key —
+  the foreign holon is mounted only when you resolve. Requires `nomos_types >= 0.1.1` (the `ForeignRef` types).
+
 ## 0.41.0
 - `NomosTestHarness` emits named phase-progress diagnostics (install → spawn runner → await ready → connect, plus per-session progress in `cluster`) and each `connect()` carries a `connectTimeout` (default 120s) that throws a NAMED remedy instead of hanging — so a multi-test AppSim run can tell install vs runner-wait vs session-block vs deadlock (co2 feedback).
 

package/dart/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.41.0
+version: 0.43.0
 
 environment:
   sdk: ^3.5.0
@@ -20,7 +20,7 @@ dependencies:
   # The pure-data core (wire types, offer codec, NomosReads, schema validation, error
   # info). nomos_client depends on and re-exports it, so existing imports are unchanged.
   # For local monorepo dev, pubspec_overrides.yaml points this at ../dart_types.
-  nomos_types: ^0.1.0
+  nomos_types: ^0.1.1
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart_types/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.1.1
+
+- Add `t.foreignRef` runtime types: `ForeignRef<T>` (a typed cross-workspace locator), `NomosForeignReader` /
+  `NomosForeignWorkspaceReader`, the sealed `ForeignResolveResult<T>` (`ForeignFound`/`ForeignNotFound`/
+  `ForeignDenied`/`ForeignUnreachable`), and `ForeignAttestation`. Generated read models type a `foreignRef`
+  field as `ForeignRef<Target>`; `.resolve/.resolveResult/.watch/.exists` are the informational lookup,
+  `.attest` is gated on the attested-read lane. Purely additive.
+
 ## 0.1.0
 - Initial release. The pure-data core split out of `nomos_client`: kernel wire types,
   the offer codec, `NomosReads`, the tri-state `NomosSlot`, aggregate metadata, schema

package/dart_types/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Pure kernel wire/data types for Nomos Dart frontends — no transport, no bridge,
   no runtime. The hand-written serde-JSON-compatible types plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.1.0
+version: 0.1.1
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/aggregate.ts

@@ -14,6 +14,7 @@
  * string: a typo'd handle is a compile error.
  */
 import type { Field } from "./fields.js";
+import { satisfiesContract, type ContractHandle } from "./contract.js";
 
 /**
  * A pure, replay-stable predicate over one aggregate's PROJECTED snapshot —
@@ -155,6 +156,10 @@ export interface AggregateHandle<
   readonly hasMany: HasManyFields<F>;
   /** Brand so a plain string is never accepted where a handle is required. */
   readonly __isAggregateHandle: true;
+  /** DOMAIN CONTRACTS this aggregate `.implements(...)` — the stable public shapes it satisfies (compile-
+   *  checked). Codegen marks the aggregate as implementing them so cross-domain refs can target the CONTRACT
+   *  instead of this concrete type. Additive metadata (not hashed law). OMITTED when it implements none. */
+  readonly implementsContracts?: readonly string[];
   /**
    * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`)
    * ONLY on the framework-owned aggregate singletons declared in `dsl/src/framework/` — most
@@ -235,6 +240,9 @@ export interface AudienceMethods<Id extends string, F extends Record<string, Fie
   /** The owner (+ per-record grantees) read; owner = the verified author, stamped into `ownerField`
    *  (default `__owner`); operator-blind. NOTE: full owned read-scoping + E2E land in the next slice. */
   owned(ownerField?: string): AggregateHandle<Id, F>;
+  /** DOMAIN CONTRACTS: assert this aggregate satisfies `contract`'s public shape (compile-checked — a
+   *  mismatch throws naming the field). Chainable; records the contract so cross-domain refs can target it. */
+  implements(contract: ContractHandle): AggregateHandle<Id, F> & AudienceMethods<Id, F>;
 }
 
 export function aggregate<const Id extends string, F extends Record<string, Field>>(
@@ -354,16 +362,26 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
   const build = (
     audience: Audience | undefined,
     visibility: ReadVisibility | undefined,
+    contracts: readonly string[] = [],
   ): AggregateHandle<Id, F> & AudienceMethods<Id, F> => ({
     ...base,
     ...(audience !== undefined ? { audience } : {}),
     ...(visibility !== undefined ? { visibility } : {}),
-    public: () => build({ kind: "public" }, undefined),
+    ...(contracts.length > 0 ? { implementsContracts: contracts } : {}),
+    public: () => build({ kind: "public" }, undefined, contracts),
     readableBy: (cap: string) => {
       const v = requires(cap); // validates the capability name
-      return build({ kind: "readableBy", cap: v.requires }, v);
+      return build({ kind: "readableBy", cap: v.requires }, v, contracts);
+    },
+    owned: (ownerField: string = OWNER_FIELD) => build({ kind: "owned", ownerField }, undefined, contracts),
+    // DOMAIN CONTRACTS: assert this aggregate satisfies `contractHandle`'s public shape — compile-checked
+    // NOW (a mismatch throws a typed error naming the field). Records the contract so cross-domain refs may
+    // target it. Chainable (`.implements(A).implements(B)`); the aggregate keeps its concrete fields.
+    implements: (contractHandle: ContractHandle) => {
+      const verdict = satisfiesContract(id, stored as Record<string, Field>, contractHandle);
+      if (!verdict.ok) throw new Error(verdict.reason);
+      return build(audience, visibility, contracts.includes(contractHandle.id) ? contracts : [...contracts, contractHandle.id]);
     },
-    owned: (ownerField: string = OWNER_FIELD) => build({ kind: "owned", ownerField }, undefined),
   });
 
   // Legacy `{ visibility: requires(cap) }` IS `readableBy(cap)` — carry both so existing law is unchanged.

package/src/build_package.ts

@@ -99,6 +99,17 @@ export function aggregatesOf(mod: Mod): AggregateHandle[] {
   return out;
 }
 
+/** Collect every exported `contract(...)` handle (`__isContract` duck-type). */
+export function contractsOf(mod: Mod): import("./contract.js").ContractHandle[] {
+  const out: import("./contract.js").ContractHandle[] = [];
+  for (const v of Object.values(mod)) {
+    if (v && typeof v === "object" && (v as { __isContract?: boolean }).__isContract === true) {
+      out.push(v as import("./contract.js").ContractHandle);
+    }
+  }
+  return out;
+}
+
 /** Collect every exported `Directive` ({id, plan, aggregateId} duck-type). */
 export function directivesOf(mod: Mod): Directive<any>[] {
   const out: Directive<any>[] = [];
@@ -262,6 +273,12 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   // the additive `nomosValueObjects` USD key. Omit-when-empty (era rule): a VO-free domain's
   // module — and thus its USD/package bytes — is byte-identical to before VOs existed.
   const valueObjects = collectValueObjectDescriptors(aggregates);
+  // DOMAIN CONTRACTS (domain_contracts.md): the public DTO shapes this domain declares, discovered by
+  // shape across the merged module list. Deduped by id (later-wins), sorted for byte-determinism. Omit-
+  // when-empty (era rule): a contract-free domain's module/USD/package bytes are byte-identical.
+  const contractById = new Map<string, import("./contract.js").ContractHandle>();
+  for (const c of contractsOf(merged)) contractById.set(c.id, c);
+  const contracts = [...contractById.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
   // SPATIAL × VO PAIRING (fail at build, not at fold): a spatial index over a VO-typed field
   // must index a GEO value object (an RFC 7946 geometry — the R*Tree's bbox source). A
   // structural VO (e.g. a PostalAddress) has no geometry to index. Non-VO fields (a
@@ -394,6 +411,9 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     // Omit-when-empty — the `nomosValueObjects` era rule: a VO-free domain's USD/package
     // bytes are byte-identical to before value objects existed.
     ...(valueObjects.length > 0 ? { valueObjects } : {}),
+    // Omit-when-empty — the `nomosContracts` era rule: a contract-free domain's USD/package bytes
+    // are byte-identical to before domain contracts existed (pure additive typing metadata).
+    ...(contracts.length > 0 ? { contracts } : {}),
     // THE PEER-SOVEREIGN ROOT-OF-TRUST: omit-when-false — a law that doesn't require parent-attested
     // birth is byte-identical in the canonical manifest/USD (the nomosParentAttestedBirth era rule).
     ...(parentAttestedBirth ? { parentAttestedBirth } : {}),

package/src/codegen_dart.ts

@@ -744,7 +744,11 @@ function aggFieldSpec(
       // workspace field give the app `resolve`/`watch`/`attest` on demand, without cloning the other holon.
       // This takes precedence over the same-workspace typed-id path below.
       if (field.foreignRef !== undefined) {
-        const target = field.foreignRef.targetAggregateId;
+        // A contract target names the shared DTO class `<ContractId>Contract` (emitted into the shared
+        // `contracts.dart`); the aggregate class is `<ContractId>` and must not collide, hence the suffix.
+        const target = field.foreignRef.targetIsContract === true
+          ? `${field.foreignRef.targetAggregateId}Contract`
+          : field.foreignRef.targetAggregateId;
         return {
           name,
           wireName,
@@ -1904,6 +1908,100 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
   ].join("\n");
 }
 
+/** The Dart type a CONTRACT field decodes to (domain_contracts.md) — a public DTO leaf. Contracts are
+ *  plain shapes (no merge state), so map by kind: scalars to their Dart primitive, a named VO to its class,
+ *  a ref/foreignRef to the raw id String. Everything is nullable (a projected DTO is a partial fold). */
+function dartTypeOfContractField(field: Field): string {
+  switch (field.kind) {
+    case "int":
+    case "counter":
+      return "int";
+    case "bool":
+      return "bool";
+    case "json":
+      return field.valueObject !== undefined ? field.valueObject.name : "Map<String, dynamic>";
+    default:
+      // string / enum / position / ref / foreignRef — all carried as a String on the wire.
+      return "String";
+  }
+}
+
+/** The fromJson decode expression for a CONTRACT field, reading `data['<wire>']`. */
+function contractFromExpr(field: Field, wire: string): string {
+  const acc = `data['${wire}']`;
+  switch (field.kind) {
+    case "int":
+    case "counter":
+      return `(${acc} as num?)?.toInt()`;
+    case "bool":
+      return `${acc} as bool?`;
+    case "json":
+      if (field.valueObject !== undefined) {
+        return `${acc} == null ? null : ${field.valueObject.name}.fromProjected((${acc} as Map).cast<String, Object?>())`;
+      }
+      return `${acc} == null ? null : (${acc} as Map).cast<String, dynamic>()`;
+    default:
+      return `${acc} as String?`;
+  }
+}
+
+/**
+ * Emit an immutable Dart class for ONE domain contract (a public DTO — architecture/domain_contracts.md).
+ * The class is `<ContractId>Contract` (the suffix keeps it distinct from an identically-named aggregate's
+ * `<ContractId>` read-model class). `final` fields + a `const` ctor + a `fromJson(Map, [id])` factory. Pure —
+ * references only nomos_types primitives (+ any VO class, which is shared). Emitted into `contracts.dart`.
+ */
+function emitDartContractClass(c: import("./contract.js").ContractHandle): string {
+  const cls = `${c.id}Contract`;
+  const fields = Object.entries(c.fields).map(([wireName, f]) => ({
+    wireName,
+    member: dartMemberName(wireName),
+    dartType: dartTypeOfContractField(f as Field),
+    from: contractFromExpr(f as Field, wireName),
+  }));
+  return [
+    `/// Generated domain CONTRACT '${c.id}' (architecture/domain_contracts.md) — a public DTO: a named,`,
+    `/// stable shape other domains reference WITHOUT importing the concrete aggregate. Immutable; decoded`,
+    `/// from a projection row via [${cls}.fromJson]. Fields are nullable (a projected DTO is a partial fold).`,
+    `class ${cls} {`,
+    `  final String id;`,
+    ...fields.map((x) => `  final ${x.dartType}? ${x.member};`),
+    ``,
+    `  const ${cls}({`,
+    `    this.id = '',`,
+    ...fields.map((x) => `    this.${x.member},`),
+    `  });`,
+    ``,
+    `  factory ${cls}.fromJson(Map<String, dynamic> data, [String id = '']) => ${cls}(`,
+    `        id: id,`,
+    ...fields.map((x) => `        ${x.member}: ${x.from},`),
+    `      );`,
+    `}`,
+  ].join("\n");
+}
+
+/**
+ * The full source of the shared `contracts.dart` file — every domain contract's DTO class, emitted ONCE
+ * per package into the TYPES package (both the flat and the layered emit). Carries the standard support
+ * import header so `compile_package_main`'s uniform rewrite (→ vendored relative / → nomos_types) applies;
+ * the classes themselves reference only nomos_types primitives (+ shared VO classes), so the file is PURE.
+ */
+export function generateDartContracts(contracts: readonly import("./contract.js").ContractHandle[]): string {
+  const sorted = [...contracts].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return [
+    `// GENERATED by nomos-compile — the package's shared domain CONTRACTS (public DTOs). DO NOT EDIT.`,
+    `// Every domain depends on this shared layer; no domain imports another's concrete types (the acyclic graph).`,
+    `//`,
+    `// ignore_for_file: unused_import`,
+    `library;`,
+    ``,
+    `import 'package:nomos_client/nomos_client.dart';`,
+    ``,
+    ...sorted.map(emitDartContractClass),
+    ``,
+  ].join("\n");
+}
+
 /** True when ANY aggregate field in the module is `t.evidence()` — gates emitting the
  * shared [emitEvidenceRefClass] once. */
 function moduleUsesEvidence(aggregates: readonly AggregateHandle[]): boolean {
@@ -3578,6 +3676,15 @@ export interface DomainModule {
    * additive `nomosValueObjects` USD key (`usd.ts`).
    */
   valueObjects?: readonly ValueObjectDescriptor[];
+  /**
+   * DOMAIN CONTRACTS (`architecture/domain_contracts.md`) — the public DTO shapes this domain declares
+   * (`contract(id, fields)`), discovered by shape and composed across the domain's modules. ADDITIVE +
+   * OPTIONAL: a contract-free domain omits this entirely and is byte-identical to before contracts existed.
+   * Contracts are PURE typing/codegen metadata (NOT hashed law); they drive the additive `nomosContracts`
+   * IR key + the shared `contracts.dart` DTO classes + the TS `<Id>Contract` interfaces. `implementedBy`
+   * lists the concrete aggregate ids that `.implements(...)` this contract (from `implementsContracts`).
+   */
+  contracts?: readonly import("./contract.js").ContractHandle[];
   /**
    * The domain's FIRST-CLASS WORKSPACE TYPES (`workspace_type.ts`; sharding §10
    * RATIFIED, slice 1) — the law-declared workspace taxonomy

package/src/codegen_ts.ts

@@ -499,8 +499,14 @@ function tsBaseTypeOfField(field: Field): string {
     case "ref": {
       // A `t.foreignRef` field surfaces as a TYPED cross-workspace locator (hydrated by the accessors from
       // the raw id + the declared workspace field); a plain same-workspace `t.ref` stays the id string.
-      const fr = (field as { foreignRef?: { targetAggregateId: string } }).foreignRef;
-      return fr !== undefined ? `ForeignRef<${fr.targetAggregateId}Data>` : "string";
+      const fr = (field as { foreignRef?: { targetAggregateId: string; targetIsContract?: boolean } }).foreignRef;
+      // A contract target types against the shared `<ContractId>Contract` interface (the public DTO),
+      // not the concrete `<Agg>Data` — that is how the reference stays acyclic.
+      return fr !== undefined
+        ? fr.targetIsContract === true
+          ? `ForeignRef<${fr.targetAggregateId}Contract>`
+          : `ForeignRef<${fr.targetAggregateId}Data>`
+        : "string";
     }
     case "json":
       // A NAMED VALUE OBJECT field reads as its generated interface (`value_object.ts`);
@@ -1218,6 +1224,24 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     }
   }
 
+  // ── domain contracts: one `<Id>Contract` interface per public DTO shape, deduped across domains ──
+  const contractByIdTs = new Map<string, import("./contract.js").ContractHandle>();
+  for (const mod of modules) {
+    for (const c of ((mod as { contracts?: readonly import("./contract.js").ContractHandle[] }).contracts ?? [])) {
+      contractByIdTs.set(c.id, c);
+    }
+  }
+  if (contractByIdTs.size > 0) {
+    out.push(`// ── domain contracts (public DTO shapes — architecture/domain_contracts.md) ──`, ``);
+    for (const [, c] of [...contractByIdTs].sort(([a], [b]) => a.localeCompare(b))) {
+      out.push(`export interface ${c.id}Contract {`);
+      for (const [name, field] of Object.entries(c.fields)) {
+        out.push(`  ${name}?: ${tsTypeOfField(field as Field)};`);
+      }
+      out.push(`}`, ``);
+    }
+  }
+
   out.push(`// ── read models (projection \`data\` shapes; partial-fold optional, EXCEPT .fromBirth()`, `//    fields — their presence is gate law, so the type is non-optional) ──`, ``);
   const foreignRefFields: { agg: string; field: string; workspaceField: string; target: string }[] = [];
   // wrap a read accessor return expression through the foreignRef row-hydrator (identity + byte-identical

package/src/compile_package_main.ts

@@ -55,11 +55,13 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import type { AggregateHandle } from "./aggregate.js";
 import {
   generateDartDomain,
+  generateDartContracts,
   type DartImport,
   type DartRefImport,
   type DomainModule,
   type PermissionVocabulary,
 } from "./codegen_dart.js";
+import type { ContractHandle } from "./contract.js";
 import { generateDartBridgeClient } from "./codegen_dart_client.js";
 import {
   isFrameworkAggregate,
@@ -445,6 +447,55 @@ const DART_GENERATED_SUBDIR = path.join("src", "generated");
 /** The shared basename of the framework-dedup file emitted once per package. */
 const FRAMEWORK_FILE = "nomos_framework";
 
+/** The shared basename of the domain-contracts DTO file emitted once per package (domain_contracts.md). */
+const CONTRACTS_FILE = "contracts";
+
+/** Collect every domain contract across the package's modules, deduped by id (later-wins). Sorted by id.
+ *  Empty when no domain declares a contract (contract-free packages emit no `contracts.dart`). */
+function collectPackageContracts(modules: readonly DomainModule[]): ContractHandle[] {
+  const byId = new Map<string, ContractHandle>();
+  for (const m of modules) for (const c of (m.contracts ?? [])) byId.set(c.id, c);
+  return [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+/**
+ * CIRCULAR-DEPENDENCY GUARD (domain_contracts.md). A `t.foreignRef` targeting a CONCRETE aggregate makes
+ * the referencing domain's generated file import the target domain's file. Two domains that concretely
+ * reference each other (A→B and B→A) form an import cycle — the exact anti-pattern domain contracts exist
+ * to break. Build the concrete domain→domain edge set and FAIL on any 2-cycle, pointing at contracts as the
+ * fix. Contract-mediated refs go through `contracts.dart`, so they create NO concrete edge and never trip this.
+ */
+function guardNoConcreteImportCycle(
+  modules: readonly DomainModule[],
+  aggIdToDartFile: ReadonlyMap<string, string>,
+): void {
+  const edges = new Map<string, Set<string>>(); // fromDomainFile → { toDomainFile }
+  for (const mod of modules) {
+    for (const agg of mod.aggregates) {
+      for (const f of Object.values(agg.fields as Record<string, { foreignRef?: { targetAggregateId: string; targetIsContract?: boolean } }>)) {
+        const fr = f.foreignRef;
+        if (fr === undefined || fr.targetIsContract === true) continue; // contract edges route via contracts.dart
+        const to = aggIdToDartFile.get(fr.targetAggregateId);
+        if (to === undefined || to === mod.name) continue;
+        (edges.get(mod.name) ?? edges.set(mod.name, new Set()).get(mod.name)!).add(to);
+      }
+    }
+  }
+  for (const [from, tos] of edges) {
+    for (const to of tos) {
+      if (edges.get(to)?.has(from) && from < to) {
+        fail(
+          `domain contracts: concrete cross-domain import cycle between '${from}' and '${to}' — their ` +
+            `generated Dart files would import each other (a t.foreignRef in each targets a concrete aggregate ` +
+            `owned by the other). Break it with a domain CONTRACT: declare a contract(...) for the shared shape, ` +
+            `.implements(...) it on the owning aggregate, and point the foreignRef at the CONTRACT (it resolves ` +
+            `through the shared contracts.dart, keeping the domain graph acyclic).`,
+        );
+      }
+    }
+  }
+}
+
 /** FRAMEWORK-SHARED symbol dedup, shared by the flat emit and the layered-packages emit (Dart-codegen
  *  hygiene): framework-owned symbols fold into MANY domains, so their generated Dart would be DEFINED
  *  once per domain — a package barrel re-exporting ≥2 domains then COLLIDES. THREE kinds are deduped,
@@ -673,6 +724,25 @@ function emitDart(
   if (shared.frameworkMod !== undefined) {
     writeGenerated(FRAMEWORK_FILE, generateDartDomain(shared.frameworkMod));
   }
+  // 2a-bis. the shared DOMAIN CONTRACTS file (`contracts.dart`) — every public DTO class, ONCE. Pure
+  //         (nomos_types + VOs). A foreignRef targeting a contract imports THIS, never the concrete domain.
+  const packageContracts = collectPackageContracts(modules);
+  const contractsImportUri = packageContracts.length > 0 ? `${CONTRACTS_FILE}.dart` : undefined;
+  if (packageContracts.length > 0) {
+    writeGenerated(CONTRACTS_FILE, generateDartContracts(packageContracts));
+  }
+  // CROSS-DOMAIN `t.foreignRef` (auto import). A foreignRef field typed `ForeignRef<CatalogueListing>` +
+  // `CatalogueListing.fromJson` needs the TARGET aggregate's Dart class — which lives in the target DOMAIN's
+  // generated file. Within ONE package the compiler knows which domain owns each aggregate, so we auto-emit
+  // the import (no manual `dartImports` config). Map every aggregate id → its domain's generated file base.
+  const aggIdToDartFile = new Map<string, string>();
+  for (const m of modules) {
+    for (const agg of (m.aggregates as { id: string }[])) aggIdToDartFile.set(agg.id, m.name);
+  }
+  // CIRCULAR-DEP GUARD (domain_contracts.md): concrete-domain → concrete-domain import edges (from
+  // concrete-aggregate-target foreignRefs). A 2-cycle A→B & B→A is the anti-pattern contracts exist to
+  // break — fail with a clear diagnostic. Contract-mediated refs go through contracts.dart (no concrete edge).
+  guardNoConcreteImportCycle(modules, aggIdToDartFile);
 
   // 2b. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
   //     CLIENT (`<name>.client.dart`, the Flutter sibling of `<name>.client.ts`).
@@ -684,7 +754,35 @@ function emitDart(
     // framework import. Only pass the import when this domain actually folds a framework symbol.
     const { modForDart, skips, foldsFramework } = domainDedupOpts(mod, shared);
     const domainFrameworkImport = foldsFramework ? frameworkImportUri : undefined;
-    const src = generateDartDomain(modForDart, {
+    // AUTO cross-domain foreignRef imports: for each foreignRef whose target aggregate lives in ANOTHER
+    // tenant domain, import that domain's generated file so `ForeignRef<Target>` + `Target.fromJson` resolve.
+    // A target that is framework-shared resolves via the frameworkImportUri (not in the tenant map), so it is
+    // skipped here. Merged with any manual `dartImports`; deduped by uri.
+    const foreignRefImportUris = new Set<string>();
+    for (const agg of (modForDart.aggregates as { fields: Record<string, { foreignRef?: { targetAggregateId: string; targetIsContract?: boolean } }> }[])) {
+      for (const f of Object.values(agg.fields)) {
+        const fr = f.foreignRef;
+        if (fr === undefined) continue;
+        // A CONTRACT target resolves through the shared `contracts.dart` (the acyclic edge), NEVER the
+        // concrete target domain — so estate never imports catalogue. (The contract id may EQUAL an
+        // aggregate id, so this branch MUST precede the concrete-file lookup.)
+        if (fr.targetIsContract === true) {
+          if (contractsImportUri !== undefined) foreignRefImportUris.add(contractsImportUri);
+          continue;
+        }
+        const targetFile = aggIdToDartFile.get(fr.targetAggregateId);
+        if (targetFile !== undefined && targetFile !== modForDart.name) foreignRefImportUris.add(`${targetFile}.dart`);
+      }
+    }
+    const mergedDartImports = [
+      ...(modForDart.dartImports ?? []),
+      ...[...foreignRefImportUris]
+        .filter((uri) => !(modForDart.dartImports ?? []).some((i) => i.uri === uri))
+        .sort()
+        .map((uri) => ({ uri })),
+    ];
+    const modForDartWithImports = mergedDartImports.length > 0 ? { ...modForDart, dartImports: mergedDartImports } : modForDart;
+    const src = generateDartDomain(modForDartWithImports, {
       ...skips,
       ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
     });
@@ -721,6 +819,7 @@ function emitDart(
       ? `export '${genRel}/nomos_client.dart';`
       : `export 'package:nomos_client/nomos_client.dart';`,
     ...(hasFrameworkSymbols ? [`export '${genRel}/${FRAMEWORK_FILE}.dart';`] : []),
+    ...(contractsImportUri !== undefined ? [`export '${genRel}/${CONTRACTS_FILE}.dart';`] : []),
     ...modules.flatMap((m) => [
       `export '${genRel}/${m.name}.dart';`,
       `export '${genRel}/${m.name}.client.dart';`,
@@ -857,18 +956,29 @@ function emitDartPackages(
   // ── the TYPES package — pure data, `nomos_types` only ──
   const typesGen = freshGenDir(packages.types);
   const typesSources = new Map<string, string>(); // fileBase → src (for alias validation + purity)
+  // The SIBLING generated type files a types-package file MAY import (a cross-domain `t.foreignRef` types its
+  // field as the target aggregate's class, which lives in the target domain's file). A sibling types file is
+  // still PURE (no runtime/bridge surface — the purity gate exists to keep nomos_client out, not to isolate
+  // domain files from each other; Dart allows type-import cycles for mutual refs).
+  const siblingTypeFiles = new Set<string>([...modules.map((m) => `${m.name}.dart`), `${FRAMEWORK_FILE}.dart`, `${CONTRACTS_FILE}.dart`]);
   const writeTypes = (fileBase: string, src: string): void => {
     if (!src.includes(DART_PACKAGE_IMPORT)) {
       fail(`generated Dart for '${fileBase}' does not carry the expected support import — codegen_dart header drifted`);
     }
     const pure = src.replace(DART_PACKAGE_IMPORT, DART_TYPES_IMPORT);
-    // PURITY, fail-closed: only the nomos_types barrel + the relative framework file may be imported.
+    // PURITY, fail-closed: only the nomos_types barrel, the framework file, and SIBLING generated type files
+    // (cross-domain foreignRef targets) may be imported. Runtime/bridge surfaces (nomos_client) stay out.
     for (const line of pure.split("\n")) {
       const m = /^import\s+'([^']+)'/.exec(line.trim());
-      if (m !== null && m[1] !== "package:nomos_types/nomos_types.dart" && m[1] !== `${FRAMEWORK_FILE}.dart`) {
+      if (
+        m !== null &&
+        m[1] !== "package:nomos_types/nomos_types.dart" &&
+        m[1] !== `${FRAMEWORK_FILE}.dart` &&
+        !siblingTypeFiles.has(m[1]!)
+      ) {
         fail(
           `types-package purity: generated '${fileBase}.dart' imports '${m[1]}' — a types file may only ` +
-            `import the nomos_types core (runtime/bridge surfaces belong in the client package)`,
+            `import the nomos_types core, the framework file, or a sibling generated domain file`,
         );
       }
     }
@@ -879,11 +989,42 @@ function emitDartPackages(
   };
 
   if (shared.frameworkMod !== undefined) writeTypes(FRAMEWORK_FILE, generateDartDomain(shared.frameworkMod));
+  // DOMAIN CONTRACTS (layered): the shared `contracts.dart` DTO file in the TYPES package (pure —
+  // nomos_types + VOs). A contract-target foreignRef imports THIS sibling, never the concrete domain.
+  const packageContracts = collectPackageContracts(modules);
+  const contractsImportUri = packageContracts.length > 0 ? `${CONTRACTS_FILE}.dart` : undefined;
+  if (packageContracts.length > 0) writeTypes(CONTRACTS_FILE, generateDartContracts(packageContracts));
+  // CROSS-DOMAIN foreignRef (layered): map aggregate id → its domain's type file, so a foreignRef field's
+  // target class resolves via a sibling import (the purity gate now permits sibling type files).
+  const aggIdToTypeFile = new Map<string, string>();
+  for (const m of modules) for (const agg of (m.aggregates as { id: string }[])) aggIdToTypeFile.set(agg.id, m.name);
+  // CIRCULAR-DEP GUARD (domain_contracts.md) — the layered path emits per-domain type files too, so the
+  // same concrete-import-cycle guard applies (contract-mediated refs route via contracts.dart, no cycle).
+  guardNoConcreteImportCycle(modules, aggIdToTypeFile);
   const perDomain = modules.map((mod) => ({ mod, dd: domainDedupOpts(mod, shared) }));
   for (const { mod, dd } of perDomain) {
+    const frImports = new Set<string>();
+    for (const agg of (dd.modForDart.aggregates as { fields: Record<string, { foreignRef?: { targetAggregateId: string; targetIsContract?: boolean } }> }[])) {
+      for (const f of Object.values(agg.fields)) {
+        const fr = f.foreignRef;
+        if (fr === undefined) continue;
+        // A contract target resolves via contracts.dart (the acyclic edge), not the concrete domain file.
+        if (fr.targetIsContract === true) {
+          if (contractsImportUri !== undefined) frImports.add(contractsImportUri);
+          continue;
+        }
+        const tf = aggIdToTypeFile.get(fr.targetAggregateId);
+        if (tf !== undefined && tf !== dd.modForDart.name) frImports.add(`${tf}.dart`);
+      }
+    }
+    const merged = [
+      ...(dd.modForDart.dartImports ?? []),
+      ...[...frImports].filter((uri) => !(dd.modForDart.dartImports ?? []).some((i) => i.uri === uri)).sort().map((uri) => ({ uri })),
+    ];
+    const modForTypes = merged.length > 0 ? { ...dd.modForDart, dartImports: merged } : dd.modForDart;
     writeTypes(
       mod.name,
-      generateDartDomain(dd.modForDart, {
+      generateDartDomain(modForTypes, {
         ...dd.skips,
         ...(dd.foldsFramework ? { frameworkImportUri: `${FRAMEWORK_FILE}.dart` } : {}),
       }),

package/src/contract.ts

@@ -0,0 +1,110 @@
+// NOMOS — DOMAIN CONTRACTS (architecture/domain_contracts.md). A CONTRACT is a named, stable PUBLIC SHAPE a
+// domain exports so OTHER domains reference it WITHOUT importing the concrete aggregate implementation — the
+// Nomos2 equivalent of Nomos1 "contracts". It preserves a layered, acyclic domain graph: everything depends
+// on the shared contracts layer, never on each other's private generated types.
+//
+// A contract is PURE TYPING/CODEGEN metadata — NOT hashed law. The kernel folds aggregates, not contracts; an
+// aggregate's domainHash moves only when its OWN fields change. Contracts ride the IR as ADDITIVE metadata
+// (like value objects — era-safe, omit-when-empty) and are stable-id tracked for evolution.
+//
+//   const CatalogueListingContract = contract("CatalogueListing", { listingId: t.string(), name: t.string() });
+//   const CatalogueListing = aggregate("CatalogueListing", { listingId: t.string().merge(Lww), … })
+//     .implements(CatalogueListingContract);                 // ← compile-checked: the aggregate SATISFIES the shape
+//   const EstateAsset = aggregate("EstateAsset", {
+//     listing: t.foreignRef({ workspace: "catalogueWorkspaceName", target: CatalogueListingContract, domain: "catalogue" }),
+//   });                                                       // ← references the CONTRACT, not the concrete aggregate
+import type { Field } from "./fields.js";
+
+/** A contract's declared field — the SAME `t.*` field builders aggregates use (the merge DRIVER is ignored;
+ *  a contract is a shape, not stored state). So a contract field can be a scalar, an enum, a value object, or
+ *  a ref, exactly like an aggregate field. */
+export type ContractField = Field;
+
+/** A named public shape a domain exports (and other domains reference). Structurally comparable to an
+ *  aggregate for the `.implements` satisfaction check. */
+export interface ContractHandle<
+  Id extends string = string,
+  F extends Record<string, ContractField> = Record<string, ContractField>,
+> {
+  /** The wire id — the literal you passed in (the STABLE public name). */
+  readonly id: Id;
+  /** The contract's PUBLIC fields (name → typed shape). */
+  readonly fields: F;
+  /** Brand so a plain string / an aggregate is never accepted where a contract is required. */
+  readonly __isContract: true;
+}
+
+/** True iff `x` is a contract handle (not an aggregate handle or a string). */
+export function isContractHandle(x: unknown): x is ContractHandle {
+  return typeof x === "object" && x !== null && (x as { __isContract?: unknown }).__isContract === true;
+}
+
+/**
+ * Declare a domain CONTRACT — a named public shape. Reuse the `t.*` field builders for the fields (the merge
+ * driver is irrelevant — a contract is a shape). Export it; a concrete aggregate `.implements(...)` it, and
+ * other domains reference it via `t.ref` / `t.foreignRef`. Purely additive: a package with no contract emits
+ * byte-identically to before.
+ */
+export function contract<const Id extends string, const F extends Record<string, ContractField>>(
+  id: Id,
+  fields: F,
+): ContractHandle<Id, F> {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new Error("contract(id, fields): the id must be a non-empty string (the stable public name).");
+  }
+  if (typeof fields !== "object" || fields === null || Object.keys(fields).length === 0) {
+    throw new Error(`contract('${id}'): declare at least one field (a contract is a public shape).`);
+  }
+  return { id, fields, __isContract: true };
+}
+
+/** The result of checking whether an aggregate satisfies a contract's shape. */
+export type ContractSatisfaction = { ok: true } | { ok: false; reason: string };
+
+/**
+ * Structural satisfaction check (`.implements`): the aggregate must carry EVERY contract field, each with a
+ * compatible KIND (and, for refs/VOs, a compatible target/VO name). EXTRA aggregate fields are fine — that is
+ * the whole point (private implementation stays behind the boundary). Pure — no IO. The compiler calls this
+ * at `aggregate(...).implements(contract)` and throws a typed error naming the field on a mismatch.
+ */
+export function satisfiesContract(
+  aggregateId: string,
+  aggregateFields: Record<string, Field>,
+  contractHandle: ContractHandle,
+): ContractSatisfaction {
+  for (const [name, cField] of Object.entries(contractHandle.fields)) {
+    const aField = aggregateFields[name];
+    if (aField === undefined) {
+      return {
+        ok: false,
+        reason:
+          `aggregate '${aggregateId}' does not satisfy contract '${contractHandle.id}': missing field '${name}' ` +
+          `(the contract requires a '${cField.kind}' field named '${name}'). Add it, or drop it from the contract.`,
+      };
+    }
+    // KIND compatibility. A contract's `ref`/`foreignRef` matches the aggregate's `ref`/`foreignRef` (both
+    // store an id string); the counter/position kinds read-collapse to int/string, so a contract may declare
+    // the collapsed kind. Everything else must match exactly.
+    const norm = (k: string): string => (k === "counter" ? "int" : k === "position" ? "string" : k);
+    if (norm(aField.kind) !== norm(cField.kind)) {
+      return {
+        ok: false,
+        reason:
+          `aggregate '${aggregateId}' does not satisfy contract '${contractHandle.id}': field '${name}' is ` +
+          `'${aField.kind}' but the contract requires '${cField.kind}'. Align the field type.`,
+      };
+    }
+    // For a value-object field, the VO NAME must match (same public structured shape).
+    const aVo = aField.valueObject?.name;
+    const cVo = cField.valueObject?.name;
+    if (cVo !== undefined && aVo !== cVo) {
+      return {
+        ok: false,
+        reason:
+          `aggregate '${aggregateId}' does not satisfy contract '${contractHandle.id}': field '${name}' uses ` +
+          `value object '${aVo ?? "(none)"}' but the contract requires '${cVo}'.`,
+      };
+    }
+  }
+  return { ok: true };
+}

package/src/fields.ts

@@ -17,6 +17,7 @@
 import { z } from "zod";
 import { Conflict, Counter, LastPosition, Lww, type Driver } from "./drivers.js";
 import type { AggregateHandle } from "./aggregate.js";
+import type { ContractHandle } from "./contract.js";
 import type { FieldFacet } from "./principal_evidence.js";
 
 /**
@@ -282,6 +283,10 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
     readonly workspaceField: string;
     readonly targetAggregateId: string;
     readonly targetDomain?: string;
+    /** TRUE iff the target is a domain CONTRACT (a public shape), not a concrete aggregate — codegen then
+     *  references the contract type (in the shared contracts layer) so the referring domain does not import
+     *  the target's concrete implementation. */
+    readonly targetIsContract?: boolean;
   };
   /** For `t.ref` (the target) AND `t.hasMany` (the child type): the related aggregate's wire id. */
   readonly refAggregateId?: string;
@@ -411,7 +416,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
   driver: Driver,
   extra: {
     refWorkspace?: string;
-    foreignRef?: { workspaceField: string; targetAggregateId: string; targetDomain?: string };
+    foreignRef?: { workspaceField: string; targetAggregateId: string; targetDomain?: string; targetIsContract?: boolean };
     refAggregateId?: string;
     /** LAZY target resolution — `t.ref(() => Agg)` / `t.hasMany(() => Agg)`. Breaks a BIDIRECTIONAL
      *  declaration cycle (a Parent's `hasMany(Child)` ⇄ a Child's `ref(Parent)`): the thunk is stored and
@@ -782,15 +787,17 @@ export const t = {
    */
   foreignRef(opts: {
     workspace: string;
-    target: AggregateHandle<string, Record<string, Field>>;
+    target: AggregateHandle<string, Record<string, Field>> | ContractHandle,
     domain?: string;
   }): Field<string, "ref"> {
+    const isContract = (opts.target as { __isContract?: unknown }).__isContract === true;
     return makeField<string, "ref">("ref", z.string(), Conflict, {
       refAggregateId: opts.target.id,
       foreignRef: {
         workspaceField: opts.workspace,
         targetAggregateId: opts.target.id,
         ...(opts.domain !== undefined ? { targetDomain: opts.domain } : {}),
+        ...(isContract ? { targetIsContract: true } : {}),
       },
     });
   },

package/src/index.ts

@@ -135,6 +135,7 @@ export {
 // — naming no id. A directive's `.plan` calls these and returns `[]` (the recorded graph is the write
 // surface). The dev never sees a "prim" — that is the GitHolon's internal OpenUSD IR.
 export { create, existing, ensure, type AggregateRef } from "./authoring.js";
+export { contract, isContractHandle, satisfiesContract, type ContractHandle, type ContractField, type ContractSatisfaction } from "./contract.js";
 // THE CAPTURED READ — a plan reads O(1) DSL queries via `read(query, args)`; the result is committed as
 // the intent's read footprint (deterministic replay + stale-premise detection). The dev calls typed DSL
 // queries; the library routes them here. The host capability is `nomos.read` (twin of `nomos.rng`).

package/src/usd.ts

@@ -615,6 +615,64 @@ export interface UsdLayer {
      */
     readonly usages?: readonly import("./value_object.js").ValueObjectUsage[];
   };
+  /**
+   * DOMAIN CONTRACTS (`architecture/domain_contracts.md`) — the public DTO shapes the domain declares.
+   * ADDITIVE + hash-inert (like `nomosValueObjects`): omit-when-empty, so a contract-free domain is
+   * byte-identical. Each contract carries its public field shapes (name/kind, VO name, ref target) and
+   * the concrete aggregate ids that `.implements(...)` it. Drives the shared `contracts.dart` + TS interfaces.
+   */
+  readonly nomosContracts?: {
+    readonly v: 1;
+    readonly contracts: readonly {
+      readonly id: string;
+      readonly fields: readonly { readonly name: string; readonly kind: string; readonly vo?: string; readonly refTarget?: string }[];
+      readonly implementedBy: readonly string[];
+    }[];
+  };
+}
+
+/** The `nomosContracts` descriptor type — a domain's public DTO shapes (era-safe, hash-inert). */
+export type NomosContracts = NonNullable<UsdLayer["nomosContracts"]>;
+
+/**
+ * Build the additive `nomosContracts` descriptor for a module: each declared contract's public field
+ * shapes + the concrete aggregate ids that `.implements(...)` it. Returns undefined when the module
+ * declares no contract (omit-when-empty — a contract-free domain is byte-identical). SHARED by the
+ * whole-doc emit (`usd.ts`) and the layered emit (`usd_layers.ts`) so both produce identical bytes.
+ */
+export function buildNomosContracts(module: {
+  readonly aggregates: readonly { id: string; implementsContracts?: readonly string[] }[];
+  readonly contracts?: readonly import("./contract.js").ContractHandle[];
+}): NomosContracts | undefined {
+  const declared = module.contracts;
+  if (declared === undefined || declared.length === 0) return undefined;
+  // implementedBy: aggregate ids per contract id (from `.implements(...)`), sorted for determinism.
+  const implByContract = new Map<string, string[]>();
+  for (const agg of module.aggregates) {
+    for (const cid of agg.implementsContracts ?? []) {
+      const l = implByContract.get(cid) ?? [];
+      l.push(agg.id);
+      implByContract.set(cid, l);
+    }
+  }
+  const contracts = [...declared]
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .map((c) => ({
+      id: c.id,
+      fields: Object.entries(c.fields).map(([name, f]) => {
+        const field = f as import("./fields.js").Field;
+        const vo = field.valueObject?.name;
+        const refTarget = field.foreignRef?.targetAggregateId ?? field.refAggregateId;
+        return {
+          name,
+          kind: field.kind,
+          ...(vo !== undefined ? { vo } : {}),
+          ...(refTarget !== undefined ? { refTarget } : {}),
+        };
+      }),
+      implementedBy: (implByContract.get(c.id) ?? []).slice().sort(),
+    }));
+  return { v: 1 as const, contracts };
 }
 
 /** The reserved variant name declaring a set's DEFAULT (USD has a default variant). */
@@ -1366,6 +1424,8 @@ export function emitUsd(
               ...(voUsages.length > 0 ? { usages: voUsages } : {}),
             }
           : undefined;
+      // DOMAIN CONTRACTS: the additive `nomosContracts` descriptor (hash-inert, omit-when-empty).
+      const nomosContracts = buildNomosContracts(l.module);
       const flowEndorse = [...l.module.directives]
         .flatMap((d) => harvestPrincipalFlows(d as never).map((f) => ({ directiveId: d.id, sink: f.sink, facet: f.facet, reason: f.reason })))
         .sort((a, b) =>
@@ -1419,6 +1479,7 @@ export function emitUsd(
         ...(eraCertGate !== undefined ? { nomosEraCertGate: eraCertGate } : {}),
         ...(nomosForeignRefs !== undefined ? { nomosForeignRefs } : {}),
         ...(nomosValueObjects !== undefined ? { nomosValueObjects } : {}),
+        ...(nomosContracts !== undefined ? { nomosContracts } : {}),
         ...(Object.keys(visAggregates).length > 0
           ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }
           : {}),

package/src/usd_layers.ts

@@ -206,6 +206,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosValueObjects !== undefined
       ? [`${indent}custom string nomos:valueObjectsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosValueObjects)))}`]
       : []),
+    ...(layer.nomosContracts !== undefined
+      ? [`${indent}custom string nomos:contractsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosContracts)))}`]
+      : []),
     ...(layer.nomosForeignRefs !== undefined
       ? [`${indent}custom string nomos:foreignRefsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosForeignRefs)))}`]
       : []),
@@ -953,6 +956,34 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
     }
         let foreignRefs: UsdLayer["nomosForeignRefs"];
     for (const l of stack) { if (l.nomosForeignRefs !== undefined) foreignRefs = l.nomosForeignRefs; }
+    // DOMAIN CONTRACTS: union the per-layer contract descriptors by id (later-wins on the shape),
+    // sorted by id — byte-identical to the composed emit (which sorts contracts by id). implementedBy
+    // is unioned across layers so a contract declared in one module and implemented in a same-layer
+    // aggregate stays intact. Omit-when-empty.
+    let contracts: UsdLayer["nomosContracts"];
+    {
+      type C = NonNullable<UsdLayer["nomosContracts"]>["contracts"][number];
+      const byId = new Map<string, C>();
+      const implById = new Map<string, Set<string>>();
+      for (const l of stack) {
+        if (l.nomosContracts === undefined) continue;
+        for (const c of l.nomosContracts.contracts) {
+          byId.set(c.id, c);
+          const s = implById.get(c.id) ?? new Set<string>();
+          for (const a of c.implementedBy) s.add(a);
+          implById.set(c.id, s);
+        }
+      }
+      if (byId.size > 0) {
+        contracts = {
+          v: 1,
+          contracts: [...byId.keys()].sort().map((id) => ({
+            ...byId.get(id)!,
+            implementedBy: [...(implById.get(id) ?? [])].sort(),
+          })),
+        };
+      }
+    }
 return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
@@ -979,6 +1010,7 @@ return {
       ...(eraCertGate !== undefined ? { nomosEraCertGate: eraCertGate } : {}),
       ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
       ...(foreignRefs !== undefined ? { nomosForeignRefs: foreignRefs } : {}),
+      ...(contracts !== undefined ? { nomosContracts: contracts } : {}),
     };
   });
 
@@ -1119,6 +1151,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const eraCertGateByDomain = new Map<string, UsdLayer["nomosEraCertGate"]>();
   const valueObjectsByDomain = new Map<string, UsdLayer["nomosValueObjects"]>();
   const foreignRefsByDomain = new Map<string, UsdLayer["nomosForeignRefs"]>();
+  const contractsByDomain = new Map<string, UsdLayer["nomosContracts"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -1218,6 +1251,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof frHex === "string") {
         foreignRefsByDomain.set(domain, JSON.parse(unhexUtf8(frHex)) as UsdLayer["nomosForeignRefs"]);
       }
+      // DOMAIN CONTRACTS: the hex-carried public DTO descriptor set (descriptive, not a gate).
+      const ctHex = p.attrs.get("nomos:contractsHex");
+      if (typeof ctHex === "string") {
+        contractsByDomain.set(domain, JSON.parse(unhexUtf8(ctHex)) as UsdLayer["nomosContracts"]);
+      }
     }
   }
 
@@ -1329,6 +1367,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const eraCertGate = eraCertGateByDomain.get(domain);
       const valueObjects = valueObjectsByDomain.get(domain);
       const foreignRefs2 = foreignRefsByDomain.get(domain);
+      const contracts2 = contractsByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -1355,6 +1394,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(eraCertGate !== undefined ? { nomosEraCertGate: eraCertGate } : {}),
         ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
       ...(foreignRefs2 !== undefined ? { nomosForeignRefs: foreignRefs2 } : {}),
+      ...(contracts2 !== undefined ? { nomosContracts: contracts2 } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));