@githolon/dsl 0.65.1 → 0.67.0

package/src/compile_package_main.ts

@@ -55,11 +55,15 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import type { AggregateHandle } from "./aggregate.js";
 import {
   generateDartDomain,
+  generateDartContracts,
+  generateDartActivityRegistry,
+  collectActivityDescriptors,
   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,
@@ -426,6 +430,7 @@ const DART_SUPPORT_CORE_SRC = [
   // The foreign-ref locator runtime (ForeignRef<T>/NomosForeignReader/…, t.foreignRef) — a generated read
   // model with a `t.foreignRef` field references `ForeignRef<Target>` through the barrel, so it must vendor.
   "foreign_ref.dart",
+  "activity.dart",
 ] as const;
 // The RUNTIME support files, vendored from `nomos_client` (dsl/dart/lib/src): the async WebView
 // bridge the generated `<name>.client.dart` drives, and the provider surface. Their
@@ -445,6 +450,59 @@ 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";
+
+/** The shared basename of the ACTIVITY REGISTRY file emitted once per package (activity_descriptors.md).
+ *  Absent when no directive declares `.activity(...)` — an activity-free package emits no `activity_registry.dart`. */
+const ACTIVITY_FILE = "activity_registry";
+
+/** 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,7 +731,21 @@ 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));
+  }
+  // 2a-ter. the shared ACTIVITY REGISTRY (`activity_registry.dart`) — the pure `renderActivity`, ONCE. Emitted
+  //         iff a directive opts in via `.activity(...)` (activity-free packages stay byte-identical). Pure
+  //         (nomos_types), so the client folds typed activity rows from the intent log with no runtime import.
+  const packageActivity = collectActivityDescriptors(modules);
+  const activityImportUri = packageActivity.length > 0 ? `${ACTIVITY_FILE}.dart` : undefined;
+  if (packageActivity.length > 0) {
+    writeGenerated(ACTIVITY_FILE, generateDartActivityRegistry(packageActivity));
+  }
   // 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
@@ -682,6 +754,10 @@ function emitDart(
   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`).
@@ -698,11 +774,18 @@ function emitDart(
     // 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 } }> }[])) {
+    for (const agg of (modForDart.aggregates as { fields: Record<string, { foreignRef?: { targetAggregateId: string; targetIsContract?: boolean } }> }[])) {
       for (const f of Object.values(agg.fields)) {
-        const tid = f.foreignRef?.targetAggregateId;
-        if (tid === undefined) continue;
-        const targetFile = aggIdToDartFile.get(tid);
+        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`);
       }
     }
@@ -726,6 +809,7 @@ function emitDart(
       ...(compat !== undefined ? { compat } : {}),
       supportImport,
       ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
+      ...(packageActivity.length > 0 ? { emitActivity: true, ...(activityImportUri !== undefined ? { activityImportUri } : {}) } : {}),
     });
     const cp = path.join(genDir, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");
@@ -751,6 +835,8 @@ 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';`] : []),
+    ...(activityImportUri !== undefined ? [`export '${genRel}/${ACTIVITY_FILE}.dart';`] : []),
     ...modules.flatMap((m) => [
       `export '${genRel}/${m.name}.dart';`,
       `export '${genRel}/${m.name}.client.dart';`,
@@ -775,8 +861,10 @@ function emitDart(
 /** The pure-core support import generated TYPES files carry in layered-packages mode. */
 const DART_TYPES_IMPORT = `import 'package:nomos_types/nomos_types.dart';`;
 /** Version constraints the scaffolded pubspecs pin — move together with the Dart packages' releases. */
-const NOMOS_TYPES_DEP = "^0.1.0";
-const NOMOS_CLIENT_DEP = "^0.38.0";
+// FLOOR = the release carrying every symbol generated code may reference (0.1.2: ActivityEvent).
+const NOMOS_TYPES_DEP = "^0.1.2";
+// FLOOR = the release carrying the bridge methods generated clients call (0.44.0: activityLog/watchActivity).
+const NOMOS_CLIENT_DEP = "^0.44.0";
 
 const isPubPackageName = (s: string): boolean => /^[a-z][a-z0-9_]*$/.test(s);
 
@@ -891,7 +979,7 @@ function emitDartPackages(
   // 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`]);
+  const siblingTypeFiles = new Set<string>([...modules.map((m) => `${m.name}.dart`), `${FRAMEWORK_FILE}.dart`, `${CONTRACTS_FILE}.dart`, `${ACTIVITY_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`);
@@ -920,17 +1008,35 @@ 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));
+  // ACTIVITY REGISTRY (layered): the pure `renderActivity` in the TYPES package (nomos_types only). The
+  // client resolves it through the types-package barrel (which re-exports every types file). Opt-in only.
+  const packageActivity = collectActivityDescriptors(modules);
+  if (packageActivity.length > 0) writeTypes(ACTIVITY_FILE, generateDartActivityRegistry(packageActivity));
   // 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 } }> }[])) {
+    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 tid = f.foreignRef?.targetAggregateId;
-        const tf = tid !== undefined ? aggIdToTypeFile.get(tid) : undefined;
+        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`);
       }
     }
@@ -1002,6 +1108,7 @@ function emitDartPackages(
       ...(compat !== undefined ? { compat } : {}),
       supportImport: "package",
       typesImportUri,
+      ...(packageActivity.length > 0 ? { emitActivity: true } : {}),
     });
     const cp = path.join(clientGen, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");

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/directive.ts

@@ -23,6 +23,7 @@ import type { Ports } from "./ctx.js";
 import type { CertifiedReadDecl } from "./certified_read.js";
 import type { RelationDecl } from "./relation.js";
 import type { QueryDecl } from "./query.js";
+import { normalizeActivity, type ActivityInput, type ActivityDescriptor } from "./activity.js";
 import { BIRTH_METER_QUERIES } from "./birth_meter.js";
 import {
   isFromPayloadRef,
@@ -115,6 +116,15 @@ export interface Directive<P = unknown> {
    * byte-identical in the canonical manifest to before `description` existed).
    */
   readonly description?: string;
+  /**
+   * OPT-IN user-facing ACTIVITY metadata (`architecture/activity_descriptors.md`) — the kind/title/message
+   * template, refs, params, category/icon/severity a client uses to render a typed activity row from this
+   * directive's intents (no string-enricher). Set by `.activity({...})`; NON-LAW, additive (same class as
+   * `description` — a directive that never declares activity is byte-identical). Normalized + validated at
+   * author time. `undefined` ⇒ this directive contributes no activity row. (The setter is `.activity({...})`;
+   * this stored field is `activityDescriptor` to avoid a method/field name clash on `RequirableDirective`.)
+   */
+  readonly activityDescriptor?: ActivityDescriptor;
   /**
    * NATIVE ZANZIBAR write-authz (P4): the RELATION the captured author must HOLD to author this
    * directive, and the OBJECT it is checked on. The ONE gate runs `engine.check(schema, object,
@@ -414,6 +424,14 @@ export interface RequirableDirective<P> extends Directive<P> {
    * calls this declares no prose (codegen falls back to a default derived from the id).
    */
   doc(description: string): RequirableDirective<P>;
+  /**
+   * Declare OPT-IN user-facing ACTIVITY metadata (`architecture/activity_descriptors.md`) — a stable `kind`,
+   * a `{actor}`+params message template, navigation `refs`, display `params` (payload field paths), and
+   * category/icon/severity. Codegen emits a typed activity descriptor + `renderActivity` so a client folds
+   * typed activity rows from the intent log (no string-enricher). Validated at author time (unknown template
+   * var / missing payload field refuse). Non-law, additive; a directive that never calls it is byte-identical.
+   */
+  activity(input: ActivityInput): RequirableDirective<P>;
   /**
    * Declare the directive's CertifiedReads (survival Constraint 5; `certified_read.md`
    * §"Tenant authoring") — the profiled, named write-path reads its `decide()` consults, the
@@ -810,6 +828,11 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
     doc(description: string): RequirableDirective<P> {
       return makeRequirable({ ...base, description });
     },
+    activity(input: ActivityInput): RequirableDirective<P> {
+      // Normalize + validate against this directive's payload (unknown template var / missing payload field
+      // refuse here). Non-law, additive — stored like `description`.
+      return makeRequirable({ ...base, activityDescriptor: normalizeActivity(base.id, input, base.payloadSchema) });
+    },
     readsCertified(reads: Record<string, CertifiedReadDecl>): RequirableDirective<P> {
       // Accumulate onto any prior declared CertifiedReads (a repeated local name's later decl
       // wins) — additive, non-destructive. The local binding NAME (the key) is what `decide`

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,8 @@ 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";
+export { normalizeActivity, renderActivityTemplate, activityKey, type ActivityInput, type ActivityDescriptor, type ActivityRefInput, type ActivitySeverity } from "./activity.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));