@githolon/dsl 0.65.1 → 0.67.0

package/dart/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.44.0
+
+- Activity-feed runtime reads on `NomosBridge`/`NomosSession`: `activityLog({base, limit})` — the committed
+  intent log as raw rows `{intentId, domain, directiveId, actorSubject, occurredAt, payload}` (decoded
+  payload; the verified author; the physical HLC) — and `watchActivity({base})`, a stream re-deriving the
+  feed on every sync tick. Generic (raw Maps); the generated `renderActivity` (from directives' declared
+  `.activity()` metadata) types them into `ActivityEvent`s. Requires `nomos_types >= 0.1.2`.
+
 ## 0.43.0
 
 - `NomosBridge.foreignReader({cloud})` — a `NomosForeignReader` backed by the device's multi-workspace bridge

package/dart/lib/src/webview_bridge.dart

@@ -1168,6 +1168,26 @@ class NomosBridge {
         .toList();
   }
 
+  /// RUNTIME activity feed — per-committed-intent rows (newest-first) from the local ledger, each carrying
+  /// `{intentId, domain, directiveId, actorSubject, occurredAt, payload}` (payload = the DECODED directive
+  /// payload). `base` = a commit-oid cursor (only intents newer than it); omitted = from the tip bounded by
+  /// `limit` (default 200). Generic raw rows — the typed shaping is the codegen `renderActivity`.
+  Future<List<Map<String, dynamic>>> activityLog(
+      {String? base, int? limit}) async {
+    final r = _asMap(await _call('activityLog', {
+      if (base != null) 'base': base,
+      if (limit != null) 'limit': limit,
+    }));
+    return ((r['rows'] as List?) ?? const [])
+        .map((e) => (e as Map).cast<String, dynamic>())
+        .toList();
+  }
+
+  /// Watch the RUNTIME activity feed: a stream that re-emits the newest-first activity rows on every local
+  /// change (doorbell/sync tick). `base` = a commit-oid cursor. Cancelling drops the watch on the runner.
+  Stream<List<dynamic>> watchActivity({String? base, String? session}) =>
+      _watchStream(kind: 'activity', base: base, session: session);
+
   /// Mint an ed25519 DEVICE KEY in-kernel → `{secret, public}` (base64). The SECRET stays on this device
   /// (persist it in secure storage); pass it to [connect] as `authorSecret` (or per-offer `signWith`) so the
   /// holon SIGNS each intent. The PUBLIC half is what gets enrolled so the gate re-verifies the signature on
@@ -1594,6 +1614,7 @@ class NomosBridge {
       String? id,
       String? spatialId,
       NomosBbox? bbox,
+      String? base,
       String? session}) {
     final subId = 'w${++_seq}';
     late final StreamController<List<dynamic>> ctrl;
@@ -1606,6 +1627,7 @@ class NomosBridge {
         if (id != null) 'id': id,
         if (spatialId != null) 'spatialId': spatialId,
         if (bbox != null) 'bbox': bbox.toJson(),
+        if (base != null) 'base': base,
         if (session != null) 'session': session,
       }),
       onCancel: () async {
@@ -1709,6 +1731,9 @@ class NomosSession extends NomosBridge {
           [String? session]) =>
       parent.watchSpatial(spatialId, bbox, session ?? workspace);
   @override
+  Stream<List<dynamic>> watchActivity({String? base, String? session}) =>
+      parent.watchActivity(base: base, session: session ?? workspace);
+  @override
   Stream<Map<String, Object?>> watchCompatibility(
           Map<String, Object?> requirement,
           [String? session]) =>

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.43.0
+version: 0.44.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.1
+  nomos_types: ^0.1.2
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart_types/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.1.2
+
+- Activity-feed runtime types: `ActivityEvent` (the shared activity row — kind/actor/occurredAt, rendered
+  title+message, stable `titleKey`/`messageKey` + params for localization, typed `refs`, category/icon/
+  severity, domain/directiveId provenance), `ActivityRef`, `ActivitySeverity`, `renderActivityTemplate`.
+  Consumed by the generated `renderActivity`/`describe`/`describeHistory`. Purely additive.
+
 ## 0.1.1
 
 - Add `t.foreignRef` runtime types: `ForeignRef<T>` (a typed cross-workspace locator), `NomosForeignReader` /

package/dart_types/lib/nomos_types.dart

@@ -31,3 +31,4 @@ export 'src/errors.dart';
 // `NomosForeignReader`/`NomosForeignWorkspaceReader` read surfaces + the named resolve outcomes. Pure data +
 // abstract interfaces (no bridge) — so both the layered TYPES package and nomos_client resolve them.
 export 'src/foreign_ref.dart';
+export 'src/activity.dart';

package/dart_types/lib/src/activity.dart

@@ -0,0 +1,160 @@
+// NOMOS — the ACTIVITY-FEED runtime types (directive `.activity(...)` descriptors). The shared, tenant-
+// agnostic shape a client renders from the intent log: a directive DECLARES its activity metadata (kind,
+// message template, refs, params) and the generated `renderActivity` turns each committed intent into an
+// [ActivityEvent] — no string-enricher guessing meaning beside the truth. The kernel/ledger stays the audit
+// truth; this is a pure client-side human projection.
+//
+// These live in the pure `nomos_types` core (no bridge/lifecycle) so BOTH the layered TYPES package (where
+// the generated pure `renderActivity` lives) AND the runtime `nomos_client` package resolve them.
+library;
+
+/// A declared navigation target on an activity row: the referenced aggregate/contract TYPE + the resolved id
+/// (read from a payload field the directive named). Replaces the old enricher's blind id-probing — the app
+/// knows exactly what `id` points at and can deep-link/resolve it.
+class ActivityRef {
+  final String type;
+  final String id;
+  const ActivityRef({required this.type, required this.id});
+
+  factory ActivityRef.fromJson(Map<String, dynamic> j) =>
+      ActivityRef(type: (j['type'] ?? '') as String, id: (j['id'] ?? '') as String);
+  Map<String, dynamic> toJson() => {'type': type, 'id': id};
+
+  @override
+  bool operator ==(Object other) => other is ActivityRef && other.type == type && other.id == id;
+  @override
+  int get hashCode => Object.hash(type, id);
+}
+
+/// Row prominence — a declared default the app may style or threshold on.
+enum ActivitySeverity {
+  info,
+  success,
+  warning,
+  critical;
+
+  static ActivitySeverity fromWire(String? s) {
+    switch (s) {
+      case 'success':
+        return ActivitySeverity.success;
+      case 'warning':
+        return ActivitySeverity.warning;
+      case 'critical':
+        return ActivitySeverity.critical;
+      default:
+        return ActivitySeverity.info;
+    }
+  }
+
+  String get wire => name;
+}
+
+/// A rendered activity row — the tenant-agnostic "tiny shared activity contract". Produced by the generated
+/// `renderActivity(intentMeta, payload)` from a directive's declared `.activity(...)` descriptor. The UI
+/// consumes this directly (title/message already interpolated; `refs` for navigation; `titleKey`/`messageKey`
+/// + `params` for later localization).
+class ActivityEvent {
+  /// The intent id — a stable per-event identity (dedupe/order key).
+  final String eventId;
+
+  /// The declared STABLE event kind (e.g. `"site.created"`).
+  final String kind;
+
+  /// The intent's author (principal) — the "who".
+  final String actorSubject;
+
+  /// When it happened (the intent's physical HLC timestamp, ISO-8601 when available).
+  final String occurredAt;
+
+  /// The rendered title (template interpolated); [titleKey] + [params] localize it later.
+  final String title;
+
+  /// The rendered message (template interpolated); [messageKey] + [params] localize it later.
+  final String message;
+
+  /// Stable i18n key for the title (`activity.<kind>.title`).
+  final String titleKey;
+
+  /// Stable i18n key for the message (`activity.<kind>.message`).
+  final String messageKey;
+
+  /// The interpolation params (name → display value, read from the payload) — for localized re-rendering.
+  final Map<String, String> params;
+
+  /// Declared navigation targets (name → typed ref).
+  final Map<String, ActivityRef> refs;
+
+  /// Optional grouping category (e.g. `"estate"`).
+  final String? category;
+
+  /// Optional default icon token (app-interpreted).
+  final String? icon;
+
+  /// Row prominence (default [ActivitySeverity.info]).
+  final ActivitySeverity severity;
+
+  /// Provenance — the domain + directive that produced this event.
+  final String domain;
+  final String directiveId;
+
+  const ActivityEvent({
+    required this.eventId,
+    required this.kind,
+    required this.actorSubject,
+    required this.occurredAt,
+    required this.title,
+    required this.message,
+    required this.titleKey,
+    required this.messageKey,
+    required this.params,
+    required this.refs,
+    required this.severity,
+    required this.domain,
+    required this.directiveId,
+    this.category,
+    this.icon,
+  });
+
+  factory ActivityEvent.fromJson(Map<String, dynamic> j) => ActivityEvent(
+        eventId: (j['eventId'] ?? '') as String,
+        kind: (j['kind'] ?? '') as String,
+        actorSubject: (j['actorSubject'] ?? '') as String,
+        occurredAt: (j['occurredAt'] ?? '') as String,
+        title: (j['title'] ?? '') as String,
+        message: (j['message'] ?? '') as String,
+        titleKey: (j['titleKey'] ?? '') as String,
+        messageKey: (j['messageKey'] ?? '') as String,
+        params: ((j['params'] as Map?)?.cast<String, dynamic>() ?? const {})
+            .map((k, v) => MapEntry(k, '$v')),
+        refs: ((j['refs'] as Map?)?.cast<String, dynamic>() ?? const {})
+            .map((k, v) => MapEntry(k, ActivityRef.fromJson((v as Map).cast<String, dynamic>()))),
+        category: j['category'] as String?,
+        icon: j['icon'] as String?,
+        severity: ActivitySeverity.fromWire(j['severity'] as String?),
+        domain: (j['domain'] ?? '') as String,
+        directiveId: (j['directiveId'] ?? '') as String,
+      );
+
+  Map<String, dynamic> toJson() => {
+        'eventId': eventId,
+        'kind': kind,
+        'actorSubject': actorSubject,
+        'occurredAt': occurredAt,
+        'title': title,
+        'message': message,
+        'titleKey': titleKey,
+        'messageKey': messageKey,
+        'params': params,
+        'refs': refs.map((k, v) => MapEntry(k, v.toJson())),
+        if (category != null) 'category': category,
+        if (icon != null) 'icon': icon,
+        'severity': severity.wire,
+        'domain': domain,
+        'directiveId': directiveId,
+      };
+}
+
+/// Interpolate `{name}` placeholders in [template] from [vars] — the render helper the generated
+/// `renderActivity` uses. A missing var renders empty (the compiler already validated every placeholder).
+String renderActivityTemplate(String template, Map<String, String> vars) =>
+    template.replaceAllMapped(RegExp(r'\{([a-zA-Z0-9_]+)\}'), (m) => vars[m.group(1)] ?? '');

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.1
+version: 0.1.2
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.65.1",
+  "version": "0.67.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/activity.ts

@@ -0,0 +1,179 @@
+// NOMOS — DIRECTIVE ACTIVITY DESCRIPTORS (architecture/activity_descriptors.md). A directive OPT-IN declares
+// its own user-facing activity metadata, so a client can fold typed activity rows straight from the intent
+// log — no string-enricher guessing meaning beside the truth. The kernel/ledger stays the audit truth; this
+// is a pure CLIENT-SIDE human projection, declared where the event semantics live.
+//
+//   directive("createSite").creates(EstateSite).payload(SitePayload)
+//     .activity({
+//       kind: "site.created",                       // STABLE event id (seeds the i18n keys)
+//       title: "Created site",
+//       message: "{actor} created {siteName}",       // {actor} + declared params
+//       category: "estate", icon: "add_location", severity: "info",
+//       refs: { site: { type: EstateSite, from: "siteId" } },   // navigation target (type + payload path)
+//       params: { siteName: "name" },                // display value ← payload field path
+//     })
+//
+// NON-LAW, additive metadata (same class as `.doc()`): a directive that never calls `.activity()` is
+// byte-identical in the canonical manifest.
+import { z } from "zod";
+import type { AggregateHandle } from "./aggregate.js";
+import { isContractHandle, type ContractHandle } from "./contract.js";
+
+/** How prominent an activity row is — a declared default the app may style/threshold on. */
+export type ActivitySeverity = "info" | "success" | "warning" | "critical";
+
+/** A declared navigation target: the referenced aggregate/contract TYPE + the payload field path holding its
+ *  id. Replaces the enricher's blind id-probing — the reference is declared, not guessed. */
+export interface ActivityRefInput {
+  /** The target type — an aggregate handle or a `contract(...)` (reuse contracts for the nav target). */
+  readonly type: AggregateHandle | ContractHandle;
+  /** The payload field path holding the target's id (dotted for nested, e.g. `"location.siteId"`). */
+  readonly from: string;
+}
+
+/** The `.activity({...})` input (declarative — field PATHS, never functions, so it generates to Dart too). */
+export interface ActivityInput {
+  /** STABLE event id (e.g. `"site.created"`) — the wire kind + the seed for the i18n keys. */
+  readonly kind: string;
+  /** Default (English) title; falls back to `kind` if omitted. */
+  readonly title?: string;
+  /** Message template — `{actor}` + any declared `params` name in braces (e.g. `"{actor} created {siteName}"`). */
+  readonly message: string;
+  /** Optional grouping category (e.g. `"estate"`). */
+  readonly category?: string;
+  /** Optional default icon token (app-interpreted). */
+  readonly icon?: string;
+  /** Row prominence (default `"info"`). */
+  readonly severity?: ActivitySeverity;
+  /** Navigation targets: name → { target type, payload path to its id }. */
+  readonly refs?: Record<string, ActivityRefInput>;
+  /** Display values: template-param name → payload field path (dotted ok). */
+  readonly params?: Record<string, string>;
+}
+
+/** The NORMALIZED, serializable descriptor stored on the directive + emitted to codegen/IR. */
+export interface ActivityDescriptor {
+  readonly kind: string;
+  readonly title: string;
+  readonly message: string;
+  readonly category?: string;
+  readonly icon?: string;
+  readonly severity: ActivitySeverity;
+  /** Refs sorted by name; `type` is the target's wire id (a string). */
+  readonly refs: readonly { readonly name: string; readonly type: string; readonly from: string }[];
+  /** Params sorted by name. */
+  readonly params: readonly { readonly name: string; readonly from: string }[];
+  /** Stable i18n keys derived from `kind` (`activity.<kind>.title` / `.message`). */
+  readonly titleKey: string;
+  readonly messageKey: string;
+}
+
+const SEVERITIES: ReadonlySet<string> = new Set(["info", "success", "warning", "critical"]);
+
+/** The i18n key for a `kind` + slot — stable, derived (never hand-authored). */
+export function activityKey(kind: string, slot: "title" | "message"): string {
+  return `activity.${kind}.${slot}`;
+}
+
+/** Interpolate `{name}` placeholders in a template from `vars` (a missing var renders as the empty string —
+ *  the compile-time validator already guarantees every placeholder is declared, so this is defensive only).
+ *  The ONE render helper shared by the TS + Dart renderers (each reimplements the same trivial substitution). */
+export function renderActivityTemplate(template: string, vars: Record<string, string>): string {
+  return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (_m, name: string) => vars[name] ?? "");
+}
+
+/** The `{placeholder}` names referenced by a template. */
+function templateVars(template: string): string[] {
+  const out: string[] = [];
+  for (const m of template.matchAll(/\{([a-zA-Z0-9_]+)\}/g)) out.push(m[1]!);
+  return out;
+}
+
+/** Top-level payload field names (best-effort — a plain `z.object`); `undefined` when the schema isn't a
+ *  destructurable object (validation of `from` roots is then skipped, staying permissive). */
+function payloadFieldNames(schema: unknown): Set<string> | undefined {
+  const def = (schema as { _def?: { shape?: unknown }; def?: { shape?: unknown } })?._def
+    ?? (schema as { def?: { shape?: unknown } })?.def;
+  const shape = (def as { shape?: unknown })?.shape;
+  const resolved = typeof shape === "function" ? (shape as () => Record<string, unknown>)() : shape;
+  if (resolved === undefined || resolved === null || typeof resolved !== "object") return undefined;
+  return new Set(Object.keys(resolved as Record<string, unknown>));
+}
+
+/**
+ * Validate + normalize an `.activity({...})` input at author time (throws a typed error naming the problem).
+ * Checks: `kind`/`message` non-empty; `severity` valid; every message/title `{placeholder}` is `actor` or a
+ * declared param; every ref/param `from` ROOT names a real payload field (when the payload shape is
+ * introspectable). Returns the serializable {@link ActivityDescriptor}. Pure.
+ */
+export function normalizeActivity(directiveId: string, input: ActivityInput, payloadSchema?: unknown): ActivityDescriptor {
+  const where = `directive '${directiveId}' .activity(...)`;
+  if (typeof input.kind !== "string" || input.kind.trim().length === 0) {
+    throw new Error(`${where}: 'kind' must be a non-empty stable string (e.g. "site.created").`);
+  }
+  if (typeof input.message !== "string" || input.message.trim().length === 0) {
+    throw new Error(`${where}: 'message' must be a non-empty template string.`);
+  }
+  const severity = input.severity ?? "info";
+  if (!SEVERITIES.has(severity)) {
+    throw new Error(`${where}: 'severity' must be one of info|success|warning|critical (got '${severity}').`);
+  }
+  const params = Object.entries(input.params ?? {}).map(([name, from]) => {
+    if (typeof from !== "string" || from.length === 0) {
+      throw new Error(`${where}: param '${name}' must map to a payload field path string.`);
+    }
+    return { name, from };
+  });
+  const paramNames = new Set(params.map((p) => p.name));
+  // Every {placeholder} must be `actor` or a declared param — an undeclared var is a typo, refuse it.
+  for (const tmpl of [input.title ?? "", input.message]) {
+    for (const v of templateVars(tmpl)) {
+      if (v !== "actor" && !paramNames.has(v)) {
+        throw new Error(
+          `${where}: template references '{${v}}' but no such param is declared (known: actor${
+            paramNames.size > 0 ? ", " + [...paramNames].join(", ") : ""
+          }). Declare it in params or fix the template.`,
+        );
+      }
+    }
+  }
+  const refs = Object.entries(input.refs ?? {}).map(([name, r]) => {
+    const targetId = (r?.type as { id?: unknown })?.id;
+    const isTarget = typeof targetId === "string" && ((r.type as { __isAggregateHandle?: unknown }).__isAggregateHandle === true || isContractHandle(r.type));
+    if (!isTarget) {
+      throw new Error(`${where}: ref '${name}'.type must be an aggregate handle or a contract(...) (got ${typeof r?.type}).`);
+    }
+    if (typeof r.from !== "string" || r.from.length === 0) {
+      throw new Error(`${where}: ref '${name}'.from must be a payload field path string.`);
+    }
+    return { name, type: targetId as string, from: r.from };
+  });
+  // Best-effort payload-field existence check (root of a dotted path).
+  const fields = payloadFieldNames(payloadSchema);
+  if (fields !== undefined) {
+    for (const { name, from } of [...params, ...refs.map((r) => ({ name: `ref ${r.name}`, from: r.from }))]) {
+      const root = from.split(".")[0]!;
+      if (!fields.has(root)) {
+        throw new Error(
+          `${where}: ${name} reads payload field '${root}' which the payload does not declare ` +
+            `(known: ${[...fields].sort().join(", ")}). Fix the path or add the field.`,
+        );
+      }
+    }
+  }
+  return {
+    kind: input.kind,
+    title: input.title ?? input.kind,
+    message: input.message,
+    ...(input.category !== undefined ? { category: input.category } : {}),
+    ...(input.icon !== undefined ? { icon: input.icon } : {}),
+    severity,
+    refs: refs.sort((a, b) => a.name.localeCompare(b.name)),
+    params: params.sort((a, b) => a.name.localeCompare(b.name)),
+    titleKey: activityKey(input.kind, "title"),
+    messageKey: activityKey(input.kind, "message"),
+  };
+}
+
+/** Re-exported so directive.ts can accept the zod payload type in the `.activity` overload without a cycle. */
+export type { z };

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 } : {}),