@githolon/dsl 0.101.5 → 0.102.0

package/src/codegen_dart.ts

@@ -19,17 +19,17 @@
  *   - a Dart enum per `t.enum([...])` field;
  *   - a Dart intent class per domain action — a pure typed DTO. Each class exposes its
  *     `domain` / `intentType` (so the call site never hand-types a string) and a
- *     `toPayloadJson()` that serialises only its typed fields to data. It builds no
+ *     internal `nmsInternalToPayloadJson()` seam that serialises only its typed fields to data. It builds no
  *     `Event` and no `Hlc`: the GitHolon executes the installed domain plan.
  *   - a single generic effectful write verb [`offer`] that ships {domain, intentType,
- *     toPayloadJson()} to the GitHolon `author(domain, intentType, payloadJson, actor)`.
+ *     nmsInternalToPayloadJson()} to the GitHolon `author(domain, intentType, payloadJson, actor)`.
  *
  * It does NOT hand-write the fixed wire types (`Value`/`Op`/`Event`/...): those
  * live hand-written in `dart_types/lib/src/wire.dart`. Only the per-domain shapes are
  * generated, so they stay reproducible from the domain definitions.
  */
 import { z } from "zod";
-import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, brandedIdMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
+import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf, brandedIdMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
 import { recursiveTypeBaseName, zodUnwrapLazy } from "./zod_lazy.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
@@ -53,12 +53,25 @@ import type { WorkspaceTypeDecl } from "./workspace_type.js";
 import { defaultActivityDescriptor } from "./activity.js";
 import { activityKey } from "./activity.js";
 import { BUSINESS_CORRECTION_DIRECTIVE } from "./framework/business_corrections.js";
+import { isBusinessIntent } from "./intent.js";
+import { contractTypeName } from "./contract.js";
+import { isNamespacedAggregate, qualifyReadProjectionType } from "./read_projection_namespace.js";
+import { recipientMetaOf } from "./recipient.js";
 
 /** A directive of any payload type. `Directive<P>` is invariant in `P`, so the
  * generator (which only introspects shapes) takes the `any`-payload form. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyDirective = Directive<any>;
 
+/** Public business actions accept input facts. Private directive DTOs retain their wire-oriented name. */
+export function dartActionInputClassName(directive: AnyDirective): string {
+  const businessBirth = (directive as { businessBirth?: { aggregateId?: string } }).businessBirth;
+  if (businessBirth?.aggregateId !== undefined && !isBusinessIntent(directive)) {
+    return `Create${concreteClassName(businessBirth.aggregateId)}Input`;
+  }
+  return `${cap(directive.id)}${isBusinessIntent(directive) ? "Input" : "Payload"}`;
+}
+
 // ---- Zod payload introspection --------------------------------------------
 
 /** How a typed payload field serialises into the payload-as-DATA JSON the engine reads. */
@@ -69,18 +82,22 @@ export type ToJsonWrap =
   | "json" // nested object — emit the field's `Map<String, Object?>` directly.
   | "vo" // a declared value object — emit `.toJson()` (the generated VO class).
   | "voList" // a list of value objects — emit `.map((e) => e.toJson()).toList()`.
-  | "wrapped"; // a typed-id class or unit extension type — emit `.value` (the wire scalar).
+  | "wrapped" // a standalone branded-id or unit extension type — emit `.value`.
+  | "ref" // an aggregate-specific NomosRef<T> — emit its `.id` wire scalar.
+  | "recipient"; // a framework-created Recipient<User> — emit its private delivery address.
 
 export interface PayloadFieldSpec {
   name: string;
   dartType: string;
+  /** Aggregate wire type when this field is a NomosRef<T>. */
+  referenceType?: string;
   /** for enums: the Dart enum type name + raw values. */
   enumValues?: string[];
-  /** how this field serialises into `toPayloadJson()`. */
+  /** how this field serialises into `nmsInternalToPayloadJson()`. */
   toJson: ToJsonWrap;
   /**
    * Whether the payload field is OPTIONAL (Zod `.optional()`/`.default()`). Optional
-   * fields are nullable in Dart and OMITTED from `toPayloadJson()` when null — so the
+   * fields are nullable in Dart and OMITTED from `nmsInternalToPayloadJson()` when null — so the
    * engine's `.plan()` sees exactly the present-field set its TS Zod schema would (it
    * only emits ops for present fields). Required fields are always emitted.
    */
@@ -89,11 +106,67 @@ export interface PayloadFieldSpec {
    * NULL SEMANTICS (null_semantics.md): the payload field ADMITS a domain `null` (its zod is
    * `.nullable()`, a `t.nullable(...)`/`t.clearable(...)` sink). It generates as the sealed
    * tri-state [NomosSlot] so the call site says OMITTED / EXPLICIT-NULL / PRESENT explicitly —
-   * `toPayloadJson` then omits, writes a real `null`, or writes the value accordingly.
+   * `nmsInternalToPayloadJson` then omits, writes a real `null`, or writes the value accordingly.
    * `false`/absent for a plain field (byte-identical to a pre-feature payload). */
   nullAdmits?: boolean;
 }
 
+export interface DartBusinessRecordInput {
+  readonly idField: string;
+  readonly workspaceField: string;
+  readonly argument: string;
+  readonly dartType: string;
+}
+
+/**
+ * Resolve `.fromRecord(field)` against the directive's target aggregate. The
+ * aggregate owns the foreign-reference pairing, so authors name only the
+ * business id field and cannot accidentally pair it with the wrong workspace.
+ */
+export function dartBusinessRecordInputs(
+  directive: AnyDirective,
+  aggregates: readonly AggregateHandle[],
+): DartBusinessRecordInput[] {
+  const declared = directive.businessRecordInputs ?? [];
+  if (declared.length === 0) return [];
+  const aggregate = aggregates.find((candidate) => candidate.id === directive.aggregateId);
+  if (aggregate === undefined) {
+    throw new Error(`${directive.id}.fromRecord(): target aggregate '${directive.aggregateId}' is not generated`);
+  }
+  const payloadNames = new Set(introspectPayload(directive.payloadSchema as z.ZodTypeAny, new Map()).map((spec) => spec.name));
+  const seenArguments = new Set<string>();
+  return declared.map((input) => {
+    const field = aggregate.fields[input.field] as Field | undefined;
+    if (field?.kind !== "ref" || field.foreignRef === undefined) {
+      throw new Error(
+        `${directive.id}.fromRecord('${input.field}'): '${directive.aggregateId}.${input.field}' must be a foreignRef field`,
+      );
+    }
+    const workspaceField = field.foreignRef.workspaceField;
+    if (!payloadNames.has(input.field) || !payloadNames.has(workspaceField)) {
+      throw new Error(
+        `${directive.id}.fromRecord('${input.field}'): payload must carry both '${input.field}' and its declared locator '${workspaceField}'`,
+      );
+    }
+    const fallback = input.field.endsWith("Id") ? input.field.slice(0, -2) : `${input.field}Record`;
+    const argument = input.as ?? fallback;
+    if (!/^[a-z][A-Za-z0-9_]*$/.test(argument)) {
+      throw new Error(`${directive.id}.fromRecord('${input.field}'): '${argument}' is not a lowerCamelCase Dart argument`);
+    }
+    if (seenArguments.has(argument) || (payloadNames.has(argument) && argument !== input.field && argument !== workspaceField)) {
+      throw new Error(`${directive.id}.fromRecord('${input.field}'): business argument '${argument}' collides with another payload field`);
+    }
+    seenArguments.add(argument);
+    const target = field.foreignRef.targetAggregateId;
+    return {
+      idField: input.field,
+      workspaceField,
+      argument,
+      dartType: field.foreignRef.targetIsContract === true ? contractTypeName(target) : concreteClassName(target),
+    };
+  });
+}
+
 type ZodInternalDef = {
   type?: string | z.ZodTypeAny;
   innerType?: z.ZodTypeAny;
@@ -269,11 +342,11 @@ export function introspectPayload(
 
 /**
  * The aggregate ids a directive set references via `idOf(Agg)` in its TOP-LEVEL payload fields
- * (dart_codegen_parity.md P2). A cross-domain `idOf` types the field as the sibling domain's typed
- * id class (`ListingId`) — which lives in the OWNING domain's generated file, so the referencing
+ * (dart_codegen_parity.md P2). A cross-domain `idOf` types the field as `NomosRef<SiblingAggregate>`;
+ * the aggregate type lives in the owning domain's generated file, so the referencing
  * domain's file must import it (flat: a relative `<domain>.dart`; layered: the sibling TYPES file).
  * Returns EVERY idOf target (same- and cross-domain); the caller filters to the cross-domain ones it
- * must import (a same-domain target's id class is declared locally). Nullable/optional-wrapped
+ * must import (a same-domain target aggregate is declared locally). Nullable/optional-wrapped
  * idOf fields are unwrapped by `idOfMetaOf`.
  */
 export function collectPayloadIdOfTargets(directives: readonly { payloadSchema?: z.ZodTypeAny }[]): Set<string> {
@@ -305,6 +378,9 @@ function introspectField(
   enumDartTypes: Map<string, string>,
   lazyNames?: Map<z.ZodTypeAny, string>,
 ): Omit<PayloadFieldSpec, "optional"> {
+  if (recipientMetaOf(zt) !== undefined) {
+    return { name, dartType: "Recipient<User>", toJson: "recipient" };
+  }
   // RECURSIVE `z.lazy` (a self-referencing tree/JSON payload): if the compiler synthesized a
   // typed recursive class for this knot (`lazyNames`), the field IS that class (toJson via its
   // `.toJson()`). Without a synthesized class (no map, or a degraded knot) it resolves one level
@@ -334,11 +410,20 @@ function introspectField(
   const tn = zodTypeName(zt);
   switch (tn) {
     case "ZodString": {
-      // idOf(Agg) (dart_codegen_parity.md P2): wire-identical to z.string(), but the Dart
-      // field is the aggregate's TYPED id class — cross-aggregate id mixups fail to compile.
+      // idOf(Agg): wire-identical to z.string(), but the public Dart value is the ONE
+      // workspace-qualified aggregate reference. NomosRef<Site> and NomosRef<Asset> are
+      // different compile-time types; serialization keeps the kernel's string id wire.
       const idAgg = idOfMetaOf(zt);
       if (idAgg !== undefined) {
-        return { name, dartType: typedIdClassForAggregateType(idAgg), toJson: "wrapped" };
+        const targetClass = idOfTargetKindOf(zt) === "contract"
+          ? contractTypeName(idAgg)
+          : concreteClassName(idAgg);
+        return {
+          name,
+          dartType: `NomosRef<${targetClass}>`,
+          referenceType: idAgg,
+          toJson: "ref",
+        };
       }
       // brandedId("SiteId"): a standalone nominal string → the generated extension type.
       const brand = brandedIdMetaOf(zt);
@@ -447,24 +532,30 @@ interface AggFieldSpec {
   kind: MaterializedFieldKind;
   dartType: string;
   enumValues?: string[];
-  /** For an own-id string field represented as a typed aggregate id value class. */
+  /** For an own-id string field represented as `NomosRef<TAggregate>`. */
   valueClass?: string;
+  /** Stable wire type for an own-id field's canonical reference. */
+  valueAggregateType?: string;
   /**
-   * For a `ref`-kind field: the TYPED id class of the target aggregate (e.g. a
-   * `Building.siteId` ref → `SiteId`). The field's Dart type is this typed id (NOT a
+   * For a `ref`-kind field: the generated class of the target aggregate (e.g. a
+   * `Building.siteId` ref → `NomosRef<Site>`). The field's Dart type is this reference (NOT a
    * bare `String`), so a cross-aggregate ref carries its target's TYPE — passing a
-   * `RoomId` where a `SiteId` is expected is a compile error. `undefined` for a
+   * `NomosRef<Room>` where a `NomosRef<Site>` is expected is a compile error. `undefined` for a
    * non-ref field (or a ref whose target type is unknown — falls back to `String`).
    */
   refIdClass?: string;
+  /** The target aggregate's stable wire type, carried in the runtime reference triple. */
+  refAggregateType?: string;
   /**
    * For a `t.foreignRef` field (a TYPED CROSS-WORKSPACE LOCATOR, not an atomic FK): the target
    * aggregate's Dart class (e.g. `CatalogueListing`). The field's Dart type is `ForeignRef<Target>`
-   * (from the shared `nomos_types` runtime), NOT the target's typed-id class — so the app can
+   * (from the shared `nomos_types` runtime), rather than a same-workspace `NomosRef` — so the app can
    * `resolve`/`watch`/`attest` the foreign target on demand. `undefined` for a plain same-workspace
-   * `ref` field (which stays its target's typed id class via {@link refIdClass}).
+   * `ref` field (which stays `NomosRef<Target>` via {@link refIdClass}).
    */
   foreignRefTarget?: string;
+  /** The target aggregate's domain-qualified kernel type carried by the locator. */
+  foreignRefAggregateType?: string;
   /**
    * For a `t.foreignRef` field: the wire name of the SIBLING field on THIS aggregate holding the foreign
    * WORKSPACE id (the locator's `workspace`, dynamic per row). `undefined` for a non-foreignRef field.
@@ -601,11 +692,7 @@ function dartTypeNameFromField(raw: string): string {
 }
 
 function aggregateIdDartType(aggregateType: string): string {
-  return typedIdClassForAggregateType(aggregateType);
-}
-
-function aggregateIdFromRowExpr(aggregateType: string, rowIdExpr: string): string {
-  return `${aggregateIdDartType(aggregateType)}.fromRow(${rowIdExpr})`;
+  return `NomosRef<${concreteClassName(aggregateType)}>`;
 }
 
 function aggregateFieldSpecForKey(
@@ -613,7 +700,7 @@ function aggregateFieldSpecForKey(
   aggregateType: string,
   keyField: string,
   enumDartTypes: Map<string, string>,
-  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
   ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
 ): AggFieldSpec | undefined {
   const agg = aggregatesById.get(aggregateType);
@@ -621,9 +708,16 @@ function aggregateFieldSpecForKey(
   if (field === undefined || field.kind === "hasMany") return undefined;
   const valueClass =
     field.kind === "string" && (ownIdFieldsByAggregate.get(aggregateType)?.has(keyField) ?? false)
-      ? aggregateIdDartType(aggregateType)
+      ? concreteClassName(aggregateType)
       : undefined;
-  return aggFieldSpec(keyField, field, enumDartTypes, refIdClassForAggregate, valueClass);
+  return aggFieldSpec(
+    keyField,
+    field,
+    enumDartTypes,
+    refIdClassForAggregate,
+    valueClass,
+    valueClass === undefined ? undefined : aggregateType,
+  );
 }
 
 function readKeyParamSpec(
@@ -632,10 +726,10 @@ function readKeyParamSpec(
 ): { dartType: string; valueExpr: string } {
   if (fieldSpec === undefined) return { dartType: "String", valueExpr: paramName };
   if (fieldSpec.valueClass !== undefined) {
-    return { dartType: fieldSpec.valueClass, valueExpr: `${paramName}.value` };
+    return { dartType: `NomosRef<${fieldSpec.valueClass}>`, valueExpr: `NmsInternalNomosRefs.id(${paramName})` };
   }
   if (fieldSpec.kind === "ref" && fieldSpec.refIdClass !== undefined) {
-    return { dartType: fieldSpec.refIdClass, valueExpr: `${paramName}.value` };
+    return { dartType: `NomosRef<${fieldSpec.refIdClass}>`, valueExpr: `NmsInternalNomosRefs.id(${paramName})` };
   }
   if (fieldSpec.kind === "enum") {
     return { dartType: fieldSpec.dartType, valueExpr: `${paramName}.wire` };
@@ -658,7 +752,7 @@ function refIdClassResolver(mod: DomainModule): (aggregateType: string) => strin
   }
   return (aggregateType: string): string => {
     const imp = imports.get(aggregateType);
-    const cls = typedIdClassForAggregateType(aggregateType);
+    const cls = concreteClassName(aggregateType);
     return imp === undefined ? cls : `${imp.prefix}.${cls}`;
   };
 }
@@ -736,8 +830,10 @@ function aggFieldSpec(
   wireName: string,
   field: Field,
   enumDartTypes: Map<string, string>,
-  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
   valueClass?: string,
+  valueAggregateType?: string,
+  aggregateWireTypeForAggregate: (aggregateType: string) => string = (aggregateType) => aggregateType,
 ): AggFieldSpec {
   const name = dartMemberName(wireName);
   // Collections are ALWAYS empty-defaultable; scalars are optional only when the DSL
@@ -749,9 +845,11 @@ function aggFieldSpec(
         name,
         wireName,
         kind: field.kind,
-        dartType: valueClass ?? "String",
+        dartType: valueClass === undefined ? "String" : `NomosRef<${valueClass}>`,
         optional,
-        ...(valueClass !== undefined ? { valueClass } : {}),
+        ...(valueClass !== undefined && valueAggregateType !== undefined
+          ? { valueClass, valueAggregateType }
+          : {}),
       };
     case "json":
       // A NAMED VALUE OBJECT (`ValueObject.field()`) types as its generated Dart class
@@ -786,7 +884,7 @@ function aggFieldSpec(
         // 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`
+          ? contractTypeName(field.foreignRef.targetAggregateId)
           : concreteClassName(field.foreignRef.targetAggregateId);
         return {
           name,
@@ -795,12 +893,14 @@ function aggFieldSpec(
           dartType: `ForeignRef<${target}>`,
           optional,
           foreignRefTarget: target,
+          foreignRefAggregateType: aggregateWireTypeForAggregate(
+            field.foreignRef.targetAggregateId,
+          ),
           foreignRefWorkspaceField: field.foreignRef.workspaceField,
         };
       }
-      // A plain same-workspace `ref` field carries ANOTHER aggregate's id — type it as that target's
-      // TYPED id class (cross-aggregate ref typing), so e.g. a `Building.siteId`
-      // ref is a `SiteId`, never a bare String. The target wire id is recorded on
+      // A plain same-workspace `ref` field carries ANOTHER aggregate's identity — type it as
+      // `NomosRef<Target>` (cross-aggregate ref typing), never a bare String. The target wire id is recorded on
       // the field (`refAggregateId`); fall back to `String` only if it is absent.
       const targetType = field.refAggregateId;
       const refIdClass =
@@ -811,9 +911,14 @@ function aggFieldSpec(
         name,
         wireName,
         kind: field.kind,
-        dartType: refIdClass ?? "String",
+        dartType: refIdClass === undefined ? "String" : `NomosRef<${refIdClass}>`,
         optional,
-        ...(refIdClass !== undefined ? { refIdClass } : {}),
+        ...(refIdClass !== undefined && targetType !== undefined
+          ? {
+              refIdClass,
+              refAggregateType: aggregateWireTypeForAggregate(targetType),
+            }
+          : {}),
       };
     }
     case "int":
@@ -824,7 +929,16 @@ function aggFieldSpec(
     case "counter":
       return { name, wireName, kind: "int", dartType: "int", optional };
     case "position":
-      return { name, wireName, kind: "string", dartType: valueClass ?? "String", optional, ...(valueClass !== undefined ? { valueClass } : {}) };
+      return {
+        name,
+        wireName,
+        kind: "string",
+        dartType: valueClass === undefined ? "String" : `NomosRef<${valueClass}>`,
+        optional,
+        ...(valueClass !== undefined && valueAggregateType !== undefined
+          ? { valueClass, valueAggregateType }
+          : {}),
+      };
     case "bool":
       return { name, wireName, kind: field.kind, dartType: "bool", optional };
     case "enum": {
@@ -872,10 +986,11 @@ function aggFieldSpec(
 function aggregateFieldSpecs(
   agg: AggregateHandle,
   enumDartTypes: Map<string, string>,
-  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
   ownIdFields: ReadonlySet<string> = new Set(),
+  aggregateWireTypeForAggregate: (aggregateType: string) => string = (aggregateType) => aggregateType,
 ): AggFieldSpec[] {
-  const used = new Set<string>(["aggregateId"]);
+  const used = new Set<string>(["ref"]);
   const internal = new Set(agg.internalFields ?? []);
   // `agg.fields` is STORED fields only — virtual `t.hasMany` inverses are in `agg.hasMany`
   // and never reach Dart materialization (they are served by the inverse read index).
@@ -884,7 +999,7 @@ function aggregateFieldSpecs(
     .map(([name, f]) => {
       const valueClass =
         f.kind === "string" && ownIdFields.has(name)
-          ? aggregateIdDartType(agg.id)
+          ? concreteClassName(agg.id)
           : undefined;
       const base = aggFieldSpec(
         name,
@@ -892,6 +1007,10 @@ function aggregateFieldSpecs(
         enumDartTypes,
         refIdClassForAggregate,
         valueClass,
+        valueClass === undefined
+          ? undefined
+          : aggregateWireTypeForAggregate(agg.id),
+        aggregateWireTypeForAggregate,
       );
       // PARTIAL-FOLD DOCTRINE (every read-model field is nullable). The projection
       // serves PARTIAL folds: a freshly-created or not-yet-fully-folded aggregate may
@@ -923,6 +1042,12 @@ function aggregateFieldSpecs(
         ? { ...surfacedSpec, nullAdmits: true, ...(nmeta.nullReason !== undefined ? { nullReason: nmeta.nullReason } : {}) }
         : surfacedSpec;
       if (used.has(spec.name)) {
+        if (spec.name === "ref") {
+          throw new Error(
+            `aggregate '${agg.id}' field '${spec.wireName}' collides with Nomos's canonical record reference 'ref' — ` +
+              `rename the business field; NomosRef<${concreteClassName(agg.id)}> is the one generated identity for this aggregate`,
+          );
+        }
         throw new Error(
           `aggregate '${agg.id}' field '${spec.wireName}' maps to duplicate Dart field '${spec.name}'`,
         );
@@ -938,21 +1063,9 @@ export function cap(s: string): string {
   return s.charAt(0).toUpperCase() + s.slice(1);
 }
 
-// ---- typed-id naming (the type-safety keystone, generalized) ----------------
-//
-// A DISTINCT typed id class is emitted PER AGGREGATE so passing one aggregate's
-// id where another's is expected is a COMPILE ERROR. The class NAME must be a pure
-// function of the aggregate's wire TYPE (e.g. `SiteRootAggregate`) so three sites
-// agree on it everywhere it is referenced — the typed-id class declaration, every
-// `createX` factory's return type, AND every cross-aggregate REF field that targets
-// that type. Convention: strip a trailing `RootAggregate`/`Aggregate` suffix and
-// append `Id` — `SiteRootAggregate → SiteId`, `ThingAggregate → ThingId`,
-// `TrackableThing → TrackableThingId`, `BuildingAggregate → BuildingId`. The
-// `RootAggregate` strip BEFORE `Aggregate` keeps the proven `SiteId` byte-identical.
-
 // ---- Dart product-name registry (`.dartName`, architecture/dart_naming.md) ----
 // A wire id → declared Dart base name map. When an aggregate declared `.dartName("Site")`,
-// EVERY Dart naming derivation (concrete class, `<stem>ReadModel`, `<stem>Id`,
+// EVERY Dart naming derivation (concrete class, `<stem>ReadModel`, `NomosRef<Concrete>`,
 // `read/watch<Name>ById`, `ForeignRef<Target>`) consults this instead of stemming the wire id.
 // Populated per-domain by `registerDartNames` at each Dart-emit entry point. NON-law, Dart-only
 // (TS codegen never reads it); empty ⇒ every derivation is byte-identical to before this existed.
@@ -1002,24 +1115,6 @@ function dartNameStem(aggregateType: string): string {
   return cap(stem === "" ? aggregateType : stem);
 }
 
-/** The typed-id class name for an aggregate WIRE TYPE (e.g. `SiteRootAggregate` →
- * `SiteId`). Pure + deterministic: the SAME wire type ALWAYS yields the SAME name,
- * so the id-class decl, the `createX` factory return, and every typed ref field that
- * points at this type all agree. Honours `.dartName` (`Site` → `SiteId`). */
-export function typedIdClassForAggregateType(aggregateType: string): string {
-  const declared = dartNameByWireId.get(aggregateType);
-  if (declared !== undefined) return `${declared}Id`;
-  let stem = aggregateType;
-  if (stem.endsWith("RootAggregate")) {
-    stem = stem.slice(0, -"RootAggregate".length);
-  } else if (stem.endsWith("Aggregate")) {
-    stem = stem.slice(0, -"Aggregate".length);
-  }
-  // Empty stem (a type literally named `Aggregate`) is impossible for registered
-  // aggregates, but guard so the name is always a legal identifier.
-  return `${cap(stem === "" ? aggregateType : stem)}Id`;
-}
-
 /** Collect all enum value-sets across aggregates + directives, name each ONCE. */
 function collectEnums(
   aggregates: AggregateHandle[],
@@ -1271,16 +1366,17 @@ function emitPermissionVocabulary(vocab: PermissionVocabulary | undefined): stri
 function emitAggregate(
   agg: AggregateHandle,
   enumDartTypes: Map<string, string>,
-  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
   ownIdFields: ReadonlySet<string> = new Set(),
+  aggregateWireTypeForAggregate: (aggregateType: string) => string = (aggregateType) => aggregateType,
 ): string {
   const className = concreteClassName(agg.id); // wire id (already PascalCase) unless `.dartName` overrides.
-  const idType = aggregateIdDartType(agg.id);
   const specs = aggregateFieldSpecs(
     agg,
     enumDartTypes,
     refIdClassForAggregate,
     ownIdFields,
+    aggregateWireTypeForAggregate,
   );
   // ATTRIBUTED READS (field_provenance.md): the `.attributed()` field names — drives the
   // `$provenance` map + per-field `<field>Provenance` getters + `lastAuthors`. Empty for
@@ -1300,14 +1396,9 @@ function emitAggregate(
   // nullable (`String?`/`int?`/`Enum?`); collections (`set`/`map`) keep their non-null
   // container type but default to EMPTY when absent.
   const fieldDecls = [
-    `  /// The kernel aggregate id (the \`{type,id,data}\` row's \`id\`) — the id the`,
-    `  /// indexed/by-id accessor matched on (e.g. the siteId). Empty string only when`,
-    `  /// the aggregate is built from a bare \`data\` map with no row id (e.g. a unit test).`,
-    `  final ${idType} aggregateId;`,
-    `  /// THE ONE REFERENCE (architecture/nomos_ref.md): this instance's canonical, workspace-qualified`,
-    `  /// [NomosRef] (\`nomos://<workspace>/<type>/<id>\`) — composed at decode from the session workspace +`,
-    `  /// the row's type/id. Workspace is '' when decoded off the bare bridge (the client accessors fill it).`,
-    `  final NomosRef ref;`,
+    `  /// The canonical workspace-qualified identity of this ${className}. Pass this exact value`,
+    `  /// to generated actions, find and watch methods; never copy its id into application state.`,
+    `  final NomosRef<${className}> ref;`,
     ...(attributedFields.length > 0
       ? [
           `  /// ATTRIBUTED READS (field_provenance.md): per-field author provenance for the`,
@@ -1335,8 +1426,7 @@ function emitAggregate(
     }),
   ].join("\n");
   const ctorParams = [
-    `    this.aggregateId = const ${idType}.fromRow(''),`,
-    `    this.ref = const NomosRef(workspace: '', type: '${agg.id}', id: ''),`,
+    `    required this.ref,`,
     ...(attributedFields.length > 0 ? [`    this.\$provenance = const {},`] : []),
     ...specs.map(
       // A required scalar stays `required`; an optional scalar OR a collection is not
@@ -1358,8 +1448,7 @@ function emitAggregate(
   // flat-projection reader from `subscriptions.dart`. The kernel aggregate [id] is
   // threaded from the row id (GAP 2) — defaulting to '' for a bare-map call.
   const parseLines = [
-    `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
-    `      ref: NomosRef(workspace: workspace, type: type.isEmpty ? '${agg.id}' : type, id: id),`,
+    `      ref: NmsInternalNomosRefs.create<${className}>(workspace: _location, type: _kind.isEmpty ? '${aggregateWireTypeForAggregate(agg.id)}' : _kind, id: id),`,
     ...(attributedFields.length > 0
       ? [`      \$provenance: FieldProvenance.mapFromJson(data['__prov']),`]
       : []),
@@ -1376,7 +1465,7 @@ function emitAggregate(
   // distinct aggregates). An optional scalar compares with `==` (null-safe); a
   // collection compares set/map-wise (always non-null after the empty default).
   const eqLines = [
-    `other.aggregateId == aggregateId`,
+    `other.ref == ref`,
     ...specs.map((s) =>
       s.kind === "set"
         ? `other.${s.name}.length == ${s.name}.length && other.${s.name}.containsAll(${s.name})`
@@ -1387,7 +1476,7 @@ function emitAggregate(
   ].join(" &&\n      ");
 
   const hashLines = [
-    `        aggregateId,`,
+    `        ref,`,
     ...specs.map((s) =>
       s.kind === "set" || s.kind === "map"
         ? `        Object.hashAll(${s.name}${s.kind === "map" ? ".entries.map((e) => Object.hash(e.key, e.value))" : ""}),`
@@ -1401,7 +1490,7 @@ function emitAggregate(
     `/// Deserialized via [${className}.fromJson] from the FLAT, already-decoded`,
     `/// projection \`data\` map (the \`{type,id,data}\` row \`query()\`/\`query_by_id()\``,
     `/// emits) — e.g. \`{"name":"HQ","createdAt":1000}\`. The kernel aggregate`,
-    `/// [aggregateId] is carried from the row \`id\`. Read it reactively through the`,
+    `/// [ref] is composed from the row's workspace, type and id. Read it reactively through the`,
     `/// generated \`watch…\` accessors below. The projection serves PARTIAL folds, so`,
     `/// EVERY scalar field is nullable — \`null\` when a freshly-folded aggregate has not`,
     `/// yet folded it (never a strict cast that throws); collections default to EMPTY.`,
@@ -1417,10 +1506,7 @@ function emitAggregate(
     `  /// decoded to bare JSON), carrying the kernel aggregate [id] from the row \`id\``,
     `  /// (defaults to '' for a bare-map call). PARTIAL folds: every scalar decodes`,
     `  /// \`null\` when absent (never throws); absent collections decode empty.`,
-    `  ///`,
-    `  /// [workspace] + [type] compose the canonical [ref] (both optional — the client accessors thread the`,
-    `  /// session workspace + the row type; a bare decode leaves workspace '' and falls back to the type '${agg.id}').`,
-    `  factory ${className}.fromJson(Map<String, dynamic> data, [String id = '', String workspace = '', String type = '']) {`,
+    `  factory ${className}.fromJson(Map<String, dynamic> data, [String id = '', String _location = '', String _kind = '']) {`,
     `    return ${className}(`,
     parseLines,
     `    );`,
@@ -1620,7 +1706,9 @@ function unionArmClassName(unionName: string, armKey: string): string {
 function dartTypeOfVoField(f: ValueObjectFieldDescriptor, voName: string, fieldName: string): string {
   switch (f.type) {
     case "string":
-      return f.brand ?? "String"; // a brandedId(...) → the generated extension-type wrapper
+      return f.idOf !== undefined
+        ? `NomosRef<${concreteClassName(f.idOf)}>`
+        : f.brand ?? "String"; // a brandedId(...) → the generated extension-type wrapper
     case "number":
       // a UNIT-tagged number is the generated zero-cost extension type; `.int()` is Dart int.
       if (f.unit !== undefined) return f.unit;
@@ -1653,6 +1741,10 @@ function voFromExpr(
 ): string {
   switch (f.type) {
     case "string":
+      if (f.idOf !== undefined) {
+        const target = concreteClassName(f.idOf);
+        return `NmsInternalNomosRefs.create<${target}>(workspace: '', type: '${f.idOf}', id: ${expr} as String)`;
+      }
       return f.brand !== undefined ? `${f.brand}(${expr} as String)` : `${expr} as String`;
     case "enum":
       // TOLERANT typed decode — an unknown wire value becomes the sentinel case.
@@ -1684,6 +1776,7 @@ function voToJsonExpr(f: ValueObjectFieldDescriptor, expr: string, depth = 0): s
     case "number":
       return f.unit !== undefined ? `${expr}.value` : expr;
     case "string":
+      if (f.idOf !== undefined) return `NmsInternalNomosRefs.id(${expr})`;
       return f.brand !== undefined ? `${expr}.value` : expr; // a brandedId extension type → its wire string
     case "boolean":
     case "literal":
@@ -2113,7 +2206,7 @@ function contractFromExpr(field: Field, wire: string): string {
  * 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 cls = contractTypeName(c.id);
   const fields = Object.entries(c.fields).map(([wireName, f]) => ({
     wireName,
     member: dartMemberName(wireName),
@@ -2154,37 +2247,19 @@ export function generateDartContracts(
      *  `ReferenceCode.field()`) render inside the DTOs, and their classes are HOISTED there (layer-zero),
      *  so contracts.dart must import it (co2 #117b). */
     readonly frameworkImportUri?: string;
-    /** Local aggregates' typed-id class names — a contract named after a local aggregate must NOT
-     *  re-declare its `<X>Id` (the aggregate's own class, with `.fromRow`, already exists). */
-    readonly aggregateIdClassNames?: ReadonlySet<string>;
   } = {},
 ): string {
   const sorted = [...contracts].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-  // CONTRACT TYPED IDS (co2 #117a): `idOf(SomeContract)` in a payload types the field `<ContractId>Id` —
-  // exactly like an aggregate's typed id — but a contract has no aggregate emitter to declare the class.
-  // Emit each contract's id as a ZERO-COST String extension type here (the shared layer every domain
-  // imports): a const ctor from the wire string + `.value` — the exact surface the generated payloads use.
-  const idTypes = sorted
-    .map((c) => typedIdClassForAggregateType(c.id))
-    .filter((cls) => !(opts.aggregateIdClassNames?.has(cls) ?? false))
-    .map((cls) => [
-      `/// TYPED CONTRACT ID \`${cls}\` — a ZERO-COST nominal String (Dart extension type): the id of the`,
-      `/// foreign aggregate behind the contract, as \`idOf(<Contract>)\` payload fields carry it. Construct`,
-      `/// it from a \`ForeignRef.id\` / a queried row id: \`${cls}(ref.id)\`; \`.value\` is the wire string.`,
-      `extension type const ${cls}(String value) {}`,
-    ].join("\n"));
   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`,
+    `// ignore_for_file: unused_import, invalid_use_of_internal_member`,
     `library;`,
     ``,
-    `import 'package:nomos_client/nomos_client.dart';`,
+    `import 'package:nomos_client/src/nms_generated_runtime.dart';`,
     ...(opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
     ``,
-    ...idTypes,
-    ``,
     ...sorted.map(emitDartContractClass),
     ``,
   ].join("\n");
@@ -2213,7 +2288,18 @@ export function collectActivityDescriptors(modules: readonly DomainModule[]): Pa
   const out: PackageActivityEntry[] = [];
   for (const mod of modules) {
     const domain = mod.domain ?? mod.name;
-    for (const d of mod.directives as AnyDirective[]) {
+    const privateAggregateIds = new Set(
+      mod.aggregates
+        .filter((aggregate) => aggregate.framework === true || (aggregate as { businessBirthInternal?: unknown }).businessBirthInternal === true)
+        .map((aggregate) => aggregate.id),
+    );
+    const storyDirectives = mod.applicationIntents === undefined
+      ? mod.directives
+      : [
+          ...mod.applicationIntents,
+          ...mod.directives.filter((d) => d.id === BUSINESS_CORRECTION_DIRECTIVE),
+        ];
+    for (const d of storyDirectives as AnyDirective[]) {
       if ((d as { businessBirthInternal?: unknown }).businessBirthInternal === true) {
         if (d.id === BUSINESS_CORRECTION_DIRECTIVE) {
           const kind = `${domain}.correction`;
@@ -2244,7 +2330,7 @@ export function collectActivityDescriptors(modules: readonly DomainModule[]): Pa
       const outputs = [
         { marker: d.marker, aggregateId: d.aggregateId },
         ...(d.secondaryOutputs ?? []),
-      ];
+      ].filter((output) => !privateAggregateIds.has(output.aggregateId));
       const seen = new Set<string>();
       const refs: Array<{ name: string; type: string; from: string }> = [];
       for (const output of outputs) {
@@ -2260,12 +2346,14 @@ export function collectActivityDescriptors(modules: readonly DomainModule[]): Pa
       out.push({
         domain,
         directiveId: d.id,
-        desc: desc ?? defaultActivityDescriptor({
-          domain,
-          directiveId: d.id,
-          ...(d.description === undefined ? {} : { description: d.description }),
-          refs,
-        }),
+        desc: desc === undefined
+          ? defaultActivityDescriptor({
+              domain,
+              directiveId: d.id,
+              ...(d.description === undefined ? {} : { description: d.description }),
+              refs,
+            })
+          : { ...desc, refs: desc.refs.filter((ref) => !privateAggregateIds.has(ref.type)) },
         declared: desc !== undefined,
       });
     }
@@ -2308,7 +2396,7 @@ function emitDartActivityArm(e: PackageActivityEntry): string[] {
     `        return ActivityEvent(`,
     `          eventId: ${e.correction === true ? "_activityOpaqueCorrectionId((rawRow['intentId'] ?? '') as String)" : "(rawRow['intentId'] ?? '') as String"},`,
     `          kind: ${dartLit(desc.kind)},`,
-    `          actorSubject: actorSubject,`,
+    `          performedBy: actorSubject,`,
     `          occurredAt: (rawRow['occurredAt'] ?? '') as String,`,
     `          title: renderActivityTemplate(${dartLit(desc.title)}, vars),`,
     `          message: renderActivityTemplate(${dartLit(desc.message)}, vars),`,
@@ -2349,10 +2437,10 @@ export function generateDartActivityRegistry(entries: readonly PackageActivityEn
     `//`,
     `// Some baseline-only registries need neither payload interpolation nor one of the aggregate lists.`,
     `// Keep generated packages analyzer-clean without branching the shared renderer shape per directive mix.`,
-    `// ignore_for_file: unused_import, unused_element, unused_local_variable`,
+    `// ignore_for_file: unused_import, unused_element, unused_local_variable, invalid_use_of_internal_member`,
     `library;`,
     ``,
-    `import 'package:nomos_client/nomos_client.dart';`,
+    `import 'package:nomos_client/src/nms_generated_runtime.dart';`,
     ``,
     `/// One business-readable difference found while proving a candidate model against history.`,
     `enum NomosModelDifferenceKind { rules, outcome, evidence }`,
@@ -2456,7 +2544,7 @@ export function generateDartActivityRegistry(entries: readonly PackageActivityEn
     `  final String label;`,
     `  final String summary;`,
     `  final Map<String, dynamic>? details;`,
-    `  final List<NomosRef> refs;`,
+    `  final List<NomosRef<Object?>> refs;`,
     `  const NomosDescribeItem({required this.kind, required this.id, required this.label, required this.summary, this.details, this.refs = const []});`,
     `}`,
     ``,
@@ -2665,7 +2753,7 @@ function foreignRefExpr(s: AggFieldSpec, aggregate: string): string {
   // workspace resolves to not-found, never throws).
   const wsExpr = `(readStrOrNull(data, '${wsField}') ?? '')`;
   const build = (idVar: string): string =>
-    `ForeignRef<${target}>(id: ${idVar}, workspace: ${wsExpr}, type: '${target}', fromJson: ${target}.fromJson)`;
+    `NmsInternalForeignRefs.create<${target}>(id: ${idVar}, workspace: ${wsExpr}, type: '${s.foreignRefAggregateType ?? target}', fromJson: ${target}.fromJson)`;
   return s.optional
     ? `() { final v = ${idReader}; return v == null ? null : ${build("v")}; }()`
     : build(idReader);
@@ -2680,7 +2768,7 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
   switch (s.kind) {
     case "ref": {
       // A `t.foreignRef` field decodes to the shared `ForeignRef<Target>` locator (raw id + sibling
-      // workspace field + the target `fromJson`), not a typed-id class.
+      // workspace field + the target `fromJson`), not a same-workspace NomosRef.
       if (s.foreignRefTarget !== undefined) return foreignRefExpr(s, aggregate);
       // A ref reads its id STRING, then wraps it via `.fromRow` (NOT the public
       // `.fromMinted`, which asserts the type tag). A ref may
@@ -2692,8 +2780,8 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
         : `readStr(data, '${aggregate}', '${s.wireName}')`;
       if (s.refIdClass === undefined) return reader;
       return opt
-        ? `() { final v = ${reader}; return v == null ? null : ${s.refIdClass}.fromRow(v); }()`
-        : `${s.refIdClass}.fromRow(${reader})`;
+        ? `() { final v = ${reader}; return v == null ? null : NmsInternalNomosRefs.create<${s.refIdClass}>(workspace: _location, type: '${s.refAggregateType}', id: v); }()`
+        : `NmsInternalNomosRefs.create<${s.refIdClass}>(workspace: _location, type: '${s.refAggregateType}', id: ${reader})`;
     }
     // `position` normalizes to `string`, `counter` to `int` in `aggFieldSpec` — unreachable here.
     case "position":
@@ -2703,8 +2791,8 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
           ? `readStrOrNull(data, '${s.wireName}')`
           : `readStr(data, '${aggregate}', '${s.wireName}')`;
         return opt
-          ? `() { final v = ${reader}; return v == null ? null : ${s.valueClass}.fromRow(v); }()`
-          : `${s.valueClass}.fromRow(${reader})`;
+          ? `() { final v = ${reader}; return v == null ? null : NmsInternalNomosRefs.create<${s.valueClass}>(workspace: _location, type: '${s.valueAggregateType}', id: v); }()`
+          : `NmsInternalNomosRefs.create<${s.valueClass}>(workspace: _location, type: '${s.valueAggregateType}', id: ${reader})`;
       }
       return opt
         ? `readStrOrNull(data, '${s.wireName}')`
@@ -2772,15 +2860,15 @@ function slotDecodeCallback(s: AggFieldSpec, mode: "aggregate" | "readModel"): s
       // read through the normal field path). A plain ref keeps its typed-id decode.
       if (s.foreignRefTarget !== undefined) {
         const t = s.foreignRefTarget;
-        return `(v) => ForeignRef<${t}>(id: v as String, workspace: '', type: '${t}', fromJson: ${t}.fromJson)`;
+        return `(v) => NmsInternalForeignRefs.create<${t}>(id: v as String, workspace: '', type: '${t}', fromJson: ${t}.fromJson)`;
       }
       return s.refIdClass !== undefined
-        ? `(v) => ${s.refIdClass}.fromRow(v as String)`
+        ? `(v) => NmsInternalNomosRefs.create<${s.refIdClass}>(workspace: _location, type: '${s.refAggregateType}', id: v as String)`
         : `(v) => v as String`;
     case "position":
     case "string":
       return s.valueClass !== undefined
-        ? `(v) => ${s.valueClass}.fromRow(v as String)`
+        ? `(v) => NmsInternalNomosRefs.create<${s.valueClass}>(workspace: _location, type: '${s.valueAggregateType}', id: v as String)`
         : `(v) => v as String`;
     case "json":
       if (s.voClass !== undefined) {
@@ -2832,9 +2920,9 @@ function readModelDartType(s: AggFieldSpec): string {
   switch (s.kind) {
     case "ref":
       // A `t.foreignRef` field surfaces as the typed cross-workspace `ForeignRef<Target>` locator; a plain
-      // same-workspace ref stays its target's typed-id class (or a bare String when the target is unknown).
+      // same-workspace ref stays `NomosRef<Target>` (or a bare String when the target is unknown).
       if (s.foreignRefTarget !== undefined) return `ForeignRef<${s.foreignRefTarget}>`;
-      return s.refIdClass ?? "String";
+      return s.refIdClass === undefined ? "String" : `NomosRef<${s.refIdClass}>`;
     case "json":
       // A `t.jsonObject()` leaf (`jsonShape:"object"`, e.g. `location`) is the DECODED
       // structured JSON OBJECT (`Map<String, Object?>`, strict). A plain `t.json()` leaf
@@ -2848,7 +2936,7 @@ function readModelDartType(s: AggFieldSpec): string {
     // so these labels are unreachable at runtime — present for FieldKind exhaustiveness.
     case "position":
     case "string":
-      return s.valueClass ?? "String";
+      return s.valueClass === undefined ? "String" : `NomosRef<${s.valueClass}>`;
     case "counter":
     case "int":
       return "int";
@@ -2897,15 +2985,15 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
   switch (s.kind) {
     case "ref": {
       // A `t.foreignRef` field decodes to the shared `ForeignRef<Target>` locator (same as the aggregate
-      // class); a plain same-workspace ref stays its target's typed-id class.
+      // class); a plain same-workspace ref stays `NomosRef<Target>`.
       if (s.foreignRefTarget !== undefined) return foreignRefExpr(s, aggregate);
       const reader = opt
         ? `readStrOrNull(data, '${s.wireName}')`
         : `readStr(data, '${aggregate}', '${s.wireName}')`;
       if (s.refIdClass === undefined) return reader;
       return opt
-        ? `() { final v = ${reader}; return v == null ? null : ${s.refIdClass}.fromRow(v); }()`
-        : `${s.refIdClass}.fromRow(${reader})`;
+        ? `() { final v = ${reader}; return v == null ? null : NmsInternalNomosRefs.create<${s.refIdClass}>(workspace: _location, type: '${s.refAggregateType}', id: v); }()`
+        : `NmsInternalNomosRefs.create<${s.refIdClass}>(workspace: _location, type: '${s.refAggregateType}', id: ${reader})`;
     }
     case "position":
     case "string":
@@ -2914,8 +3002,8 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
           ? `readStrOrNull(data, '${s.wireName}')`
           : `readStr(data, '${aggregate}', '${s.wireName}')`;
         return opt
-          ? `() { final v = ${reader}; return v == null ? null : ${s.valueClass}.fromRow(v); }()`
-          : `${s.valueClass}.fromRow(${reader})`;
+          ? `() { final v = ${reader}; return v == null ? null : NmsInternalNomosRefs.create<${s.valueClass}>(workspace: _location, type: '${s.valueAggregateType}', id: v); }()`
+          : `NmsInternalNomosRefs.create<${s.valueClass}>(workspace: _location, type: '${s.valueAggregateType}', id: ${reader})`;
       }
       return opt
         ? `readStrOrNull(data, '${s.wireName}')`
@@ -2970,8 +3058,8 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
 }
 
 /** Emit the generated typed read-model class for one aggregate. The class
- * (`SiteReadModel`, …) carries the kernel aggregate [aggregateId] (threaded from the
- * `{type,id,data}` row id like the aggregate class) plus a DSL-named typed field per DSL
+ * (`SiteReadModel`, …) carries the canonical aggregate-typed [ref] (composed from the
+ * `{type,id,data}` row location) plus a DSL-named typed field per DSL
  * field declaration, and a [fromProjected] factory that reads the read engine's
  * already-decoded projected `data` shape. */
 function emitReadModel(
@@ -2979,17 +3067,18 @@ function emitReadModel(
   enumDartTypes: Map<string, string>,
   deriveds: DerivedDecl[] = [],
   combineds: CombinedDecl[] = [],
-  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
   ownIdFields: ReadonlySet<string> = new Set(),
+  aggregateWireTypeForAggregate: (aggregateType: string) => string = (aggregateType) => aggregateType,
 ): string {
   const className = readModelClassName(agg.id);
-  const idType = aggregateIdDartType(agg.id);
   const wireType = agg.id;
   const specs = aggregateFieldSpecs(
     agg,
     enumDartTypes,
     refIdClassForAggregate,
     ownIdFields,
+    aggregateWireTypeForAggregate,
   );
 
   // DERIVED/COMBINED read fields are engine-projected JSON leaves. Their value schema is
@@ -3002,13 +3091,9 @@ function emitReadModel(
   // optional json-object leaf) is nullable; a PERMISSIVE json leaf is already the
   // nullable `Object?` (no extra `?`); a collection keeps its non-null container.
   const fieldDecls = [
-    `  /// The kernel aggregate id (the \`{type,id,data}\` row's \`id\`, e.g. the siteId).`,
-    `  /// Empty string only when built from a bare \`data\` map with no row id (a unit test).`,
-    `  final ${idType} aggregateId;`,
-    `  /// THE ONE REFERENCE (architecture/nomos_ref.md): this row's canonical, workspace-qualified [NomosRef]`,
-    `  /// (\`nomos://<workspace>/<type>/<id>\`) — composed at decode from the session workspace + the row's`,
-    `  /// type/id. The generated client accessors thread the session workspace; a bare decode leaves it ''.`,
-    `  final NomosRef ref;`,
+    `  /// The canonical workspace-qualified identity of this ${concreteClassName(agg.id)}.`,
+    `  /// Pass this exact value to generated actions, find and watch methods.`,
+    `  final NomosRef<${concreteClassName(agg.id)}> ref;`,
     ...specs.flatMap((s) => {
       const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
       // SURFACED MERGE CONFLICTS: pending observations surface typed; resolve = ordinary next write.
@@ -3032,8 +3117,7 @@ function emitReadModel(
     ),
   ].join("\n");
   const ctorParams = [
-    `    this.aggregateId = const ${idType}.fromRow(''),`,
-    `    this.ref = const NomosRef(workspace: '', type: '${agg.id}', id: ''),`,
+    `    required this.ref,`,
     ...specs.map((s) =>
       // A required field is `required`; an optional scalar, a collection, OR a
       // permissive json leaf (already nullable `Object?`) takes its default/null.
@@ -3074,8 +3158,7 @@ function emitReadModel(
         ];
 
   const parseLines = [
-    `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
-    `      ref: NomosRef(workspace: workspace, type: type.isEmpty ? '${agg.id}' : type, id: id),`,
+    `      ref: NmsInternalNomosRefs.create<${concreteClassName(agg.id)}>(workspace: _location, type: _kind.isEmpty ? '${aggregateWireTypeForAggregate(agg.id)}' : _kind, id: id),`,
     ...specs.map((s) =>
       s.surfaced === true
         ? `      ${s.name}: SurfacedValue.decode<${readModelDartType(s)}>(data, '${s.wireName}', ${slotDecodeCallback(s, "readModel")}),`
@@ -3111,10 +3194,7 @@ function emitReadModel(
     `  /// already decoded to bare/structured JSON), carrying the kernel aggregate [id] from`,
     `  /// the row \`id\` (defaults to '' for a bare-map call). PARTIAL folds: every scalar`,
     `  /// decodes \`null\` when absent (never throws); absent collections decode empty.`,
-    `  ///`,
-    `  /// [workspace] + [type] compose the canonical [ref] (both optional — the client accessors thread the`,
-    `  /// session workspace + the row type; a bare decode leaves workspace '' and falls back to the type '${agg.id}').`,
-    `  factory ${className}.fromProjected(Map<String, dynamic> data, [String id = '', String workspace = '', String type = '']) {`,
+    `  factory ${className}.fromProjected(Map<String, dynamic> data, [String id = '', String _location = '', String _kind = '']) {`,
     `    return ${className}(`,
     parseLines,
     `    );`,
@@ -3124,39 +3204,63 @@ function emitReadModel(
   ].join("\n");
 }
 
-// ---- public intent payload class -------------------------------------------
+// ---- typed action input class ----------------------------------------------
 
 function emitDirective(
   d: AnyDirective,
   domainName: string,
   enumDartTypes: Map<string, string>,
   lazyNames?: Map<z.ZodTypeAny, string>,
+  aggregates: readonly AggregateHandle[] = [],
 ): string {
-  const className = `${cap(d.id)}Payload`;
+  const className = dartActionInputClassName(d);
   const specs = introspectPayload(d.payloadSchema as z.ZodTypeAny, enumDartTypes, lazyNames);
+  const recordInputs = dartBusinessRecordInputs(d, aggregates);
+  const principalField = d.businessPrincipalField;
+  const derivedFields = new Set([
+    ...recordInputs.flatMap((input) => [input.idField, input.workspaceField]),
+    ...(principalField === undefined ? [] : [principalField]),
+  ]);
+  const publicSpecs = specs.filter((spec) => !derivedFields.has(spec.name));
+  const internalPayloadArguments = [
+    ...(principalField === undefined ? [] : ["required String nmsInternalPrincipal"]),
+    ...(recordInputs.length === 0
+      ? []
+      : [
+          "required String Function(Object record) nmsInternalLocationOf",
+          "required String Function(Object record) nmsInternalIdOf",
+        ]),
+  ];
+  const internalPayloadSignature = internalPayloadArguments.length === 0
+    ? ""
+    : `{${internalPayloadArguments.join(", ")}}`;
 
   // Field decls: optional payload fields are nullable Dart fields (omitted from the
   // payload JSON when null); required fields are non-null + `required` in the ctor.
-  const fieldDecls = specs
+  const fieldDecls = [
+    ...publicSpecs
     .map((s) =>
       s.nullAdmits === true
         ? `  final NomosSlot<${stripNullable(s.dartType)}> ${s.name};`
         : `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`,
-    )
-    .join("\n");
-  const ctorParams = specs
+    ),
+    ...recordInputs.map((input) => `  final ${input.dartType} ${input.argument};`),
+  ].join("\n");
+  const ctorParams = [
+    ...publicSpecs
     .map((s) =>
       // A null-admitting slot defaults to Omitted (the call site chooses Present/ExplicitNull);
       // an optional field defaults to null; a required field is `required`.
       s.nullAdmits === true
         ? `    this.${s.name} = const NomosSlot.omitted(),`
         : `    ${s.optional ? "" : "required "}this.${s.name},`,
-    )
-    .join("\n");
+    ),
+    ...recordInputs.map((input) => `    required this.${input.argument},`),
+  ].join("\n");
   // Zero-field payload (e.g. a `.births()` sanctioning directive with an empty
   // object schema): `const X({});` / a dangling blank field block is INVALID Dart —
   // emit a plain `const X();` and an empty map literal instead.
-  const hasFields = specs.length > 0;
+  const hasFields = publicSpecs.length > 0 || recordInputs.length > 0;
   const ctorLines = hasFields
     ? [`  const ${className}({`, ctorParams, `  });`]
     : [`  const ${className}();`];
@@ -3166,17 +3270,17 @@ function emitDirective(
   // fields are written only when present (mirrors the engine's Zod: ops are emitted
   // only for present fields).
   const requiredEntries = specs
-    .filter((s) => !s.optional && s.nullAdmits !== true)
+    .filter((s) => !derivedFields.has(s.name) && !s.optional && s.nullAdmits !== true)
     .map((s) => `    '${s.name}': ${toJsonExpr(s, s.name)},`);
   const optionalLines = specs
-    .filter((s) => s.optional && s.nullAdmits !== true)
+    .filter((s) => !derivedFields.has(s.name) && s.optional && s.nullAdmits !== true)
     .map(
       (s) =>
         `    if (${s.name} != null) '${s.name}': ${toJsonExpr(s, `${s.name}!`)},`,
     );
   // NULL SEMANTICS: a null-admitting field writes through its slot — Omitted writes nothing,
   // ExplicitNull writes a real `null`, Present writes the encoded value (null_semantics.md).
-  const slotSpecs = specs.filter((s) => s.nullAdmits === true);
+  const slotSpecs = specs.filter((s) => !derivedFields.has(s.name) && s.nullAdmits === true);
   const slotWriteLines = slotSpecs.map(
     (s) => `    ${s.name}.writeTo(data, '${s.name}', (v) => ${toJsonExpr(s, "v")});`,
   );
@@ -3186,51 +3290,43 @@ function emitDirective(
 
   return [
     `/// ${docFirst}`,
+    `/// Business facts accepted by this generated application action.`,
     `///`,
-    `/// Generated typed intent DTO for '${d.id}' (marker: ${d.marker},`,
-    `/// aggregate: ${d.aggregateId}). It carries its [domain] + [intentType] and a`,
-    `/// [toPayloadJson] that ships only typed fields as data. It builds no`,
-    `/// \`Event\` and no \`Hlc\`. Pass it to [offer]; the GitHolon executes`,
-    `/// the installed domain plan.`,
-    `class ${className} implements NomosIntent {`,
-    `  /// The policy domain this intent belongs to (the kernel \`author\` \`domain\`).`,
-    `  static const String domainName = '${domainName}';`,
-    `  /// The public intent type within [domainName] — never hand-typed at the call site.`,
-    `  static const String intentTypeName = '${d.id}';`,
-    `  /// The aggregate this intent targets (provenance only; the engine binds the instance).`,
-    `  static const String aggregateId = '${d.aggregateId}';`,
-    `  /// The referential marker (creates/mutates/ensures/archives).`,
-    `  static const String marker = '${d.marker}';`,
+    `/// Pass this value straight to the generated domain application. It is a command,`,
+    `/// not application state; do not retain it in a repository or submit it through runtime APIs.`,
+    `class ${className} {`,
     ``,
     ...(hasFields ? [fieldDecls, ``] : []),
     `  /// ${docFirst}`,
     ...ctorLines,
     ``,
-    `  @override`,
-    `  String get domain => domainName;`,
-    ``,
-    `  @override`,
-    `  String get intentType => intentTypeName;`,
-    ``,
-    `  /// Serialise this payload to the intent DATA JSON (the shape the`,
-    `  /// domain Zod schema validates inside the engine). Optional fields are`,
-    `  /// omitted when null; a null-admitting field writes through its tri-state slot.`,
-    `  @override`,
+    `  /// Nomos implementation seam used only by the generated application package.`,
+    `  /// Tenant code should pass this object to the generated domain application instead.`,
     ...(hasSlots
       ? [
-          `  Map<String, Object?> toPayloadJson() {`,
+          `  Map<String, Object?> nmsInternalToPayloadJson(${internalPayloadSignature}) {`,
           `    final data = <String, Object?>{`,
           ...requiredEntries,
           ...optionalLines,
+          ...(principalField === undefined ? [] : [`      '${principalField}': nmsInternalPrincipal,`]),
+          ...recordInputs.flatMap((input) => [
+            `      '${input.workspaceField}': nmsInternalLocationOf(${input.argument}),`,
+            `      '${input.idField}': nmsInternalIdOf(${input.argument}),`,
+          ]),
           `    };`,
           ...slotWriteLines,
           `    return data;`,
           `  }`,
         ]
       : [
-          `  Map<String, Object?> toPayloadJson() => <String, Object?>{`,
+          `  Map<String, Object?> nmsInternalToPayloadJson(${internalPayloadSignature}) => <String, Object?>{`,
           ...requiredEntries,
           ...optionalLines,
+          ...(principalField === undefined ? [] : [`    '${principalField}': nmsInternalPrincipal,`]),
+          ...recordInputs.flatMap((input) => [
+            `    '${input.workspaceField}': nmsInternalLocationOf(${input.argument}),`,
+            `    '${input.idField}': nmsInternalIdOf(${input.argument}),`,
+          ]),
           `  };`,
         ]),
     `}`,
@@ -3252,6 +3348,10 @@ export function toJsonExpr(spec: PayloadFieldSpec, accessor: string): string {
       return `${accessor}.map((e) => e.toJson()).toList()`;
     case "wrapped":
       return `${accessor}.value`;
+    case "ref":
+      return `NmsInternalNomosRefs.id(${accessor})`;
+    case "recipient":
+      return `NmsInternalRecipients.address(${accessor})`;
   }
 }
 
@@ -3316,7 +3416,7 @@ export function synthesizeRecursivePayloadTypes(
         const b = brandedIdMetaOf(zt);
         if (b !== undefined) return { type: "string", brand: b };
         const idAgg = idOfMetaOf(zt);
-        if (idAgg !== undefined) return { type: "string", brand: `${idAgg}Id` };
+        if (idAgg !== undefined) return { type: "string", idOf: idAgg };
         return { type: "string" };
       }
       case "ZodNumber": {
@@ -3450,7 +3550,7 @@ function emitQueryReads(
   q: QueryDecl,
   aggregatesById: Map<string, AggregateHandle>,
   enumDartTypes: Map<string, string>,
-  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
   ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
 ): string {
   const agg = q.returns; // the aggregate TYPE id (== the wire id, used for field/index lookups).
@@ -3507,12 +3607,12 @@ function emitAggregateByIdReads(agg: AggregateHandle): string {
     `/// (\`null\` until/unless it has been folded). Emits the current value, then`,
     `/// re-emits on each projection tick. Primary-key lookup (#140) — O(1).`,
     `Stream<${cls}?> watch${cls}ById(NomosReads reads, ${idType} id) =>`,
-    `    reads.watchById(id.value, ${cls}.fromJson);`,
+    `    reads.watchById(NmsInternalNomosRefs.id(id), ${cls}.fromJson);`,
     ``,
     `/// One-shot typed by-id read: the CURRENT \`${cls}\` with kernel aggregate id`,
     `/// [id], or \`null\` when no such aggregate has been folded. O(1).`,
     `${cls}? read${cls}ById(NomosReads reads, ${idType} id) =>`,
-    `    reads.readById(id.value, ${cls}.fromJson);`,
+    `    reads.readById(NmsInternalNomosRefs.id(id), ${cls}.fromJson);`,
   ].join("\n");
 }
 
@@ -3541,7 +3641,7 @@ function emitCountReads(
   c: ReturnType<typeof finishCount>,
   aggregatesById: Map<string, AggregateHandle>,
   enumDartTypes: Map<string, string>,
-  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
   ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
 ): string {
   const method = readMethodName(c.id);
@@ -3593,7 +3693,7 @@ function emitSumReads(
   s: ReturnType<typeof finishSum>,
   aggregatesById: Map<string, AggregateHandle>,
   enumDartTypes: Map<string, string>,
-  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
   ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
 ): string {
   const method = readMethodName(s.id);
@@ -3647,7 +3747,7 @@ function emitMinReads(
   e: ReturnType<typeof finishExtremum>,
   aggregatesById: Map<string, AggregateHandle>,
   enumDartTypes: Map<string, string>,
-  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
   ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
 ): string {
   const method = readMethodName(e.id);
@@ -3700,7 +3800,7 @@ function emitMaxReads(
   e: ReturnType<typeof finishExtremum>,
   aggregatesById: Map<string, AggregateHandle>,
   enumDartTypes: Map<string, string>,
-  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
   ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
 ): string {
   const method = readMethodName(e.id);
@@ -3755,7 +3855,7 @@ function emitExistsReads(
   e: ReturnType<typeof finishExists>,
   aggregatesById: Map<string, AggregateHandle>,
   enumDartTypes: Map<string, string>,
-  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  refIdClassForAggregate: (aggregateType: string) => string = concreteClassName,
   ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
 ): string {
   const method = readMethodName(e.id);
@@ -3837,23 +3937,10 @@ function emitOrderedReads(d: OrderedReadDecl): string {
   ].join("\n");
 }
 
-// ---- minted typed-id creates (the kernel id-mint keystone) -----------------
-//
-// A `.creates` directive whose payload carries a target-id field (the id bound to the
-// NEW aggregate) is a KERNEL-MINTED create: the frontend must NOT pass a raw id. For
-// such a directive we emit, ALONGSIDE the plain payload DTO:
-//   * a typed id value class (e.g. `SiteId`) wrapping the kernel-minted string, so a
-//     raw `String` is never accepted where a minted id is required, and
-//   * a top-level `create…({Minter mint, …})` factory that calls the KERNEL mint (no
-//     raw id param, NO seed) to RESERVE the typed id and builds the payload from it — so
-//     the only way to construct a minted create at the call site is THROUGH the kernel
-//     mint, and the dev never sees a uuid/seed/nonce.
-//
-// THE MODEL: the KERNEL mints `<Type>_<uuidv7>` from the HOST-INJECTED rng; the id is
-// CAPTURED in the create event and READ on replay (never re-minted). The UUID body is
-// opaque uniqueness only — NOT time/order; intent HLCs carry ordering. There is NO
-// `mintSeed` payload field any more — the id itself is the proof. The factory passes
-// NOTHING to the mint but the aggregate type.
+// ---- legacy payload-bound own-id discovery ---------------------------------
+// Some old laws copied a payload string into their created aggregate's own id field. We still trace
+// that shape so decoded legacy fields become `NomosRef<TAggregate>`. No FooId class or frontend mint
+// factory is emitted; current creates are law-minted and return their canonical reference.
 
 /**
  * The target-id field of a minted create: the payload field bound to the aggregate the
@@ -3868,11 +3955,11 @@ function emitOrderedReads(d: OrderedReadDecl): string {
  * Mechanism: probe each top-level STRING field with a unique sentinel, run `.plan()`, find
  * the `Create` event whose `__type` == the directive's `.creates` aggregate, and map its
  * `__id` sentinel back to the payload field. Returns `undefined` when the created aggregate's
- * id is not a verbatim top-level payload string (then no minting factory is emitted).
+ * id is not a verbatim top-level payload string.
  *
  * `agg` is the `.creates` target handle (`directive.aggregateId`), required by `executeDirectiveToIntent`.
- * If the plan cannot be traced, emit no factory. Guessing by field name makes the
- * public Dart surface lie about aggregate identity.
+ * If the plan cannot be traced, do not classify an own-id field. Guessing by field name would make
+ * the decoded Dart surface lie about aggregate identity.
  */
 function mintedIdField(
   d: AnyDirective,
@@ -3987,161 +4074,6 @@ function sampleFromZod(zt: z.ZodTypeAny): unknown {
   }
 }
 
-/** The Dart typed-id class name for a minted create's id field. Unified on the
- * aggregate WIRE TYPE (so `createSite`'s `siteId` → `SiteId`, the same name a ref
- * targeting `SiteRootAggregate` uses), NOT on the payload field name.
- * The minting factory uses `FooId._(mintedId)` (the truly private ctor, same file). */
-function typedIdClassName(aggregateType: string): string {
-  return typedIdClassForAggregateType(aggregateType);
-}
-
-/** Emit a typed id value class for an aggregate TYPE. Type-safe: a raw `String` — or
- * another aggregate's typed id — is a COMPILE ERROR where a [${cls}] is required (the
- * value classes are distinct nominal types). Public constructors:
- *   * [${cls}] / [${cls}.fromString] — non-strict wrappers for app route params,
- *     existing refs, and test fixtures.
- *   * [${cls}.fromMinted] — STRICT: asserts the kernel type tag matches.
- * One row-id constructor:
- *   * [${cls}.fromRow] — wraps a kernel-stored row/ref id when deserializing a
- *     projection row. This intentionally does NOT enforce the minted type tag because
-   *     reads may include not-yet-minted ids; write admission remains the mint gate.
- */
-function emitTypedIdClass(aggregateType: string): string {
-  const cls = typedIdClassName(aggregateType);
-  return [
-    `/// Typed id for \`${aggregateType}\`. A DISTINCT nominal type so a raw String — or`,
-    `/// ANOTHER aggregate's typed id — is a COMPILE ERROR where a [${cls}] is required.`,
-    `/// [fromMinted] is the strict constructor for ids reserved by the kernel mint.`,
-    `/// [${cls}] / [fromString] / [fromRow] are non-strict wrappers for route params,`,
-    `/// existing refs, and generated projection decoding.`,
-    `class ${cls} {`,
-    `  /// The kernel-minted id string (\`${aggregateType}_<uuidv7>\`).`,
-    `  /// The UUID body is opaque uniqueness only — NOT time/order; intent HLCs carry ordering.`,
-    `  final String value;`,
-    `  const ${cls}(this.value);`,
-    `  const ${cls}._(this.value);`,
-    `  factory ${cls}.fromString(String value) => ${cls}.fromRow(value);`,
-    `  /// Wrap a kernel-stored row/ref id while decoding a projection row. This is`,
-    `  /// intentionally non-strict: old ledgers and cross-domain refs may not carry the`,
-    `  /// minted type tag, so admission/minting is enforced on writes, not reads.`,
-    `  const ${cls}.fromRow(this.value);`,
-    `  /// Wrap an ALREADY-kernel-minted id string (e.g. one read back from a query).`,
-    `  /// STRICT: asserts the type tag matches \`${aggregateType}\` — a wrong-typed id throws.`,
-    `  /// A minted id is \`<TypeTag>_<uuidv7>\`, so the tag is the prefix before the FIRST \`_\`.`,
-    `  /// Do not read time or ordering from the UUID body; it is an opaque uniqueness token.`,
-    `  factory ${cls}.fromMinted(String minted) {`,
-    `    final i = minted.indexOf('_');`,
-    `    final tag = i < 0 ? minted : minted.substring(0, i);`,
-    `    if (tag != '${aggregateType}') {`,
-    `      throw ArgumentError('id "$minted" is not a ${aggregateType} id (tag "$tag")');`,
-    `    }`,
-    `    return ${cls}._(minted);`,
-    `  }`,
-    `  @override`,
-    `  bool operator ==(Object other) => other is ${cls} && other.value == value;`,
-    `  @override`,
-    `  int get hashCode => value.hashCode;`,
-    `  @override`,
-    `  String toString() => '${cls}($value)';`,
-    `}`,
-  ].join("\n");
-}
-
-/** Emit the top-level minted `create…(...)` factory function: it calls the KERNEL mint
- * (NO raw id param, NO seed) to RESERVE a typed id and builds the payload from it,
- * returning `(payload, typedId)`. This is the ONLY way to construct a minted create at the
- * call site — the dev supplies NOTHING about the id. The factory itself contains NO
- * id/uuid/seed construction — only the runtime kernel-mint call via [mint]. */
-function emitMintedFactory(
-  d: AnyDirective,
-  _domainName: string,
-  idField: PayloadFieldSpec,
-  specs: PayloadFieldSpec[],
-  aggregateType: string,
-): string {
-  const className = `${cap(d.id)}Payload`;
-  const idCls = typedIdClassName(aggregateType);
-  const fnName = d.id; // e.g. `createSite` — the typed minting factory.
-  // The caller supplies every field EXCEPT the minted id (the kernel mint produces it).
-  // Optional fields become optional named params. There is NO seed/author param: the
-  // kernel mints the UUIDv7 from the host-injected rng — the dev touches none of it.
-  const callerFields = specs.filter((s) => s.name !== idField.name);
-  const ctorParams = callerFields
-    .map((s) => `  ${s.optional ? "" : "required "}${s.dartType}${s.optional ? "?" : ""} ${s.name},`)
-    .join("\n");
-  const forwarded = callerFields.map((s) => `    ${s.name}: ${s.name},`).join("\n");
-  return [
-    `/// KERNEL-MINTED \`${d.id}\` factory: calls [mint] (the kernel id-mint) to RESERVE a`,
-    `/// fresh typed [${idCls}] — NO raw id param, NO seed — and ships the minted id in the`,
-    `/// payload, so the kernel GATE verifies its shape + type tag on author. The kernel`,
-    `/// mints the \`${aggregateType}_<uuidv7>\` from the HOST-INJECTED rng (native OsRng / web`,
-    `/// crypto). The UUID body is opaque uniqueness only — NOT time/order; intent HLCs carry`,
-    `/// ordering. This factory builds NO id/uuid/seed itself — only the runtime mint call.`,
-    `/// Returns the [${className}] AND the minted [${idCls}] (so the caller can reference the`,
-    `/// new aggregate). This is the type-safe create path: the frontend cannot supply a raw id.`,
-    `(${className}, ${idCls}) ${fnName}({`,
-    `  required Minter mint,`,
-    ctorParams,
-    `}) {`,
-    `  final mintedId = mint(aggregateType: '${aggregateType}');`,
-    `  final payload = ${className}(`,
-    `    ${idField.name}: mintedId,`,
-    forwarded,
-    `  );`,
-    `  return (payload, ${idCls}._(mintedId));`,
-    `}`,
-  ].join("\n");
-}
-
-/** Emit the typed-id keystone for a domain (GENERALIZED across ALL aggregates):
- *   1. a DISTINCT typed id value class PER AGGREGATE (so cross-aggregate type
- *      confusion is a compile error + ref fields have a target type to name); and
- *   2. a kernel-minting `create…` factory for every `.creates` directive whose real
- *      plan trace proves a payload field is the created aggregate id.
- * Every aggregate gets a typed id even if it has no minting factory (a singleton /
- * kernel-minted create), because OTHER aggregates' ref fields may target it.
- * Returns `""` when the domain has no aggregates (nothing to emit). */
-function emitMintedCreates(
-  aggregates: AggregateHandle[],
-  directives: AnyDirective[],
-  domainName: string,
-  enumDartTypes: Map<string, string>,
-  /** Aggregate ids whose typed-id CLASS is emitted in the shared `nomos_framework.dart` (imported
-   *  here), so it must NOT be re-declared. Minting FACTORIES still emit and reference the imported
-   *  class. Empty = emit every id class locally (the single-domain / shared-file path). */
-  skipIdClassFor: ReadonlySet<string> = new Set(),
-): string {
-  const blocks: string[] = [];
-
-  // (1) A typed id class per aggregate. Dedup by the typed-id class NAME: two wire
-  // types never collide on a name (the name is a pure function of the type), and a
-  // domain that re-exports a framework aggregate must not emit its id class twice.
-  // Framework-shared aggregates are emitted ONCE in the package's `nomos_framework.dart`,
-  // so their id class is SKIPPED here (referenced via import).
-  const emittedIdClasses = new Set<string>();
-  for (const agg of aggregates) {
-    if (skipIdClassFor.has(agg.id)) continue;
-    const cls = typedIdClassForAggregateType(agg.id);
-    if (emittedIdClasses.has(cls)) continue;
-    emittedIdClasses.add(cls);
-    blocks.push(emitTypedIdClass(agg.id));
-  }
-
-  // (2) A minting factory per qualifying create — the kernel mints the `.creates` target's
-  // id, identified MARKER-DRIVEN by running the real `.plan()` (see `mintedIdField`).
-  const aggById = new Map<string, AggregateHandle>();
-  for (const a of aggregates) aggById.set(a.id, a);
-  for (const d of directives) {
-    if (d.marker !== "creates") continue;
-    const specs = introspectPayload(d.payloadSchema as z.ZodTypeAny, enumDartTypes);
-    const idField = mintedIdField(d, aggById.get(d.aggregateId), specs);
-    if (idField === undefined) continue;
-    const aggregateType = d.aggregateId;
-    blocks.push(emitMintedFactory(d, domainName, idField, specs, aggregateType));
-  }
-  return blocks.join("\n\n");
-}
-
 function collectOwnIdFieldsByAggregate(
   aggregates: AggregateHandle[],
   directives: AnyDirective[],
@@ -4180,6 +4112,18 @@ export interface DomainModule {
   domain?: string;
   aggregates: AggregateHandle[];
   directives: AnyDirective[];
+  /**
+   * The domain's complete public business language. When present, generated
+   * application clients publish only these intent methods; their private
+   * constituent directives have already been inlined into the executable plans.
+   * Application metadata only: executable law remains in {@link directives}.
+   */
+  applicationIntents?: AnyDirective[];
+  /**
+   * Durable cross-workspace business sharing policies. Code-generation metadata
+   * only: the order and receipt directives remain ordinary certified law.
+   */
+  applicationWorkspaceSharing?: import("./workspace_sharing.js").WorkspaceSharingPolicy[];
   /**
    * SECONDARY-CREATE AUTO-DECLARE (secondary_ensure.ts) — the aggregate TYPES whose deterministic
    * secondary `ensure(...)` `composeDomainModule` plan-probed and SANCTIONED by injecting a no-op
@@ -4346,7 +4290,7 @@ export interface DomainModule {
   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 +
+   * (`recordContract(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`
@@ -4425,12 +4369,12 @@ export interface DomainModule {
   permissionVocabulary?: PermissionVocabulary;
   /**
    * Extra Dart imports needed by this generated file. Used when a domain has typed
-   * refs to aggregate id classes emitted by another generated domain file.
+   * refs to aggregate classes emitted by another generated domain file.
    */
   dartImports?: DartImport[];
   /**
    * Mapping from referenced aggregate wire type to the Dart import prefix that exposes
-   * that aggregate's typed id class. This preserves cross-domain ref typing without
+   * that aggregate's generated class. This preserves cross-domain ref typing without
    * forcing every domain into one giant generated library.
    */
   dartRefImports?: DartRefImport[];
@@ -4438,15 +4382,19 @@ export interface DomainModule {
 
 /** Options controlling FRAMEWORK-SHARED aggregate deduplication (Dart-codegen hygiene). */
 export interface GenerateDartDomainOptions {
+  /** Package-wide aggregate ownership used to emit canonical domain-qualified reference types. */
+  readonly packageAggregateDomains?: Readonly<
+    Record<string, { domain: string; name: string; namespaced?: boolean }>
+  >;
   /**
-   * Aggregate ids whose Dart surface (projection class, read model, typed-id class, by-id accessors)
+   * Aggregate ids whose Dart surface (projection class, read model, by-id accessors)
    * is emitted ONCE per package in the shared `nomos_framework.dart` and MUST NOT be re-emitted here —
    * this domain REFERENCES them via {@link frameworkImportUri}. Empty/absent ⇒ emit everything locally
    * (the legacy single-file behaviour; byte-identical to before this option existed).
    */
   readonly skipAggregateIds?: ReadonlySet<string>;
   /**
-   * Framework-shared DIRECTIVE ids whose generated payload class (+ minted-create factory) is emitted
+   * Framework-shared DIRECTIVE ids whose generated payload class is emitted
    * ONCE per package in the shared file and MUST NOT be re-emitted here. The domain still OFFERS them
    * (the client offer methods stay per-domain); only the payload TYPE moves to the shared file.
    */
@@ -4480,7 +4428,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   mod = {
     ...mod,
     aggregates: publicAggregates,
-    directives: mod.directives.filter(
+    directives: (mod.applicationIntents ?? mod.directives).filter(
       (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
     ),
     ...(mod.queries === undefined
@@ -4498,10 +4446,16 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   const codegenDirectives = mod.directives
     .filter((d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true)
     .map((d) => {
-      const businessBirth = (d as { businessBirth?: { publicPayloadSchema?: z.ZodTypeAny } }).businessBirth;
+      const businessBirth = (d as { businessBirth?: { aggregateId?: string; publicPayloadSchema?: z.ZodTypeAny } }).businessBirth;
       return businessBirth?.publicPayloadSchema === undefined
         ? d
-        : { ...d, payloadSchema: businessBirth.publicPayloadSchema } as AnyDirective;
+        : {
+            ...d,
+            // Frontend-only name: the lowered framework directive remains `nomosBirth<Aggregate>` in law,
+            // while tenant code receives the ordinary business input `Create<Aggregate>Input`.
+            id: isBusinessIntent(d) ? d.id : `create${businessBirth.aggregateId ?? cap(d.id)}`,
+            payloadSchema: businessBirth.publicPayloadSchema,
+          } as AnyDirective;
     });
   const skipAggregateIds = opts.skipAggregateIds ?? new Set<string>();
   const skipDirectiveIds = opts.skipDirectiveIds ?? new Set<string>();
@@ -4530,13 +4484,12 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   // in local VO descriptors OR directive payloads gets ONE zero-cost wrapper. Opaque by design —
   // no generated arithmetic/conversions (a physics library is not a type system).
   const unitNames = new Set<string>();
-  // brandedId(...) names → their own zero-cost String extension type (the standalone twin of
-  // the aggregate typed-id classes). Collected from VO descriptors AND directive payloads.
+  // brandedId(...) names → their own zero-cost String extension type. These represent external
+  // nominal strings, never aggregate identity. Collected from VO descriptors and directive payloads.
   const brandNames = new Set<string>();
   const walkUnitField = (f: ValueObjectFieldDescriptor): void => {
     if (f.type === "number" && f.unit !== undefined) unitNames.add(f.unit);
-    // A standalone brandedId declares its own extension type; an idOf REFERENCE does NOT — the aggregate
-    // emits the canonical `<Agg>Id` class (with `.fromRow`), so re-declaring it here dup'd the symbol (co2).
+    // A standalone brandedId declares its own extension type; an idOf REFERENCE does not.
     else if (f.type === "string" && f.brand !== undefined && f.idOf === undefined) brandNames.add(f.brand);
     else if (f.type === "array") walkUnitField(f.items);
     else if (f.type === "map") walkUnitField(f.values);
@@ -4552,8 +4505,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     if (schema && typeof schema === "object" && zodTypeName(schema as z.ZodTypeAny) === "ZodObject") {
       try {
         for (const spec of introspectPayload(schema as z.ZodTypeAny, new Map())) {
-          // A spec whose brand a VO descriptor already registered is a brandedId, not a unit —
-          // and neither is an aggregate typed-id (`<Agg>Id`, emitted by the id machinery).
+          // A wrapped spec whose brand a VO descriptor already registered is a brandedId, not a unit.
           if (spec.toJson === "wrapped" && !spec.dartType.endsWith("Id") && !brandNames.has(spec.dartType)) {
             unitNames.add(spec.dartType);
           }
@@ -4621,8 +4573,19 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     domainKey,
   );
   const refIdClassForAggregate = refIdClassResolver(mod);
+  const packageAggregateDomains = opts.packageAggregateDomains ?? {};
   const aggregatesById = new Map<string, AggregateHandle>();
   for (const a of mod.aggregates) aggregatesById.set(a.id, a);
+  const aggregateWireTypeForAggregate = (aggregateType: string): string => {
+    const local = aggregatesById.get(aggregateType);
+    if (local !== undefined && !isNamespacedAggregate(local)) return aggregateType;
+    const owner = packageAggregateDomains[aggregateType];
+    if (owner?.namespaced === false) return aggregateType;
+    const domain = owner?.domain ?? (local === undefined ? undefined : domainKey);
+    return domain === undefined
+      ? aggregateType
+      : qualifyReadProjectionType(domain, aggregateType);
+  };
   const ownIdFieldsByAggregate = collectOwnIdFieldsByAggregate(
     mod.aggregates,
     codegenDirectives,
@@ -4637,24 +4600,16 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
         dartTypes,
         refIdClassForAggregate,
         ownIdFieldsByAggregate.get(a.id) ?? new Set(),
+        aggregateWireTypeForAggregate,
       ),
     )
     .join("\n\n");
   // the runtime aggregate-meta registry (lookup by op.aggregateType — generic surfaces).
   const aggregateMetaBlock = emitAggregateMetaRegistry(domainKey, localAggregates);
   const dirBlock = localDirectives
-    .map((d) => emitDirective(d, domainKey, dartTypes, recursiveTypes.names))
+    .map((d) => emitDirective(d, domainKey, dartTypes, recursiveTypes.names, mod.aggregates))
     .join("\n\n");
 
-  // TYPED IDS + MINTED CREATES (the id-mint keystone, GENERALIZED): a DISTINCT typed
-  // id class for EVERY aggregate (cross-aggregate type-confusion is a compile error;
-  // ref fields name their target's typed id), plus a top-level `create…` factory that
-  // mints THROUGH the kernel (no raw id) for every `.creates` directive carrying a
-  // `mintSeed` + an own-id field.
-  // Minted-create factories for framework directives (if any) live in the shared file — pass only the
-  // LOCAL directives here; framework typed-id classes are likewise skipped (referenced via import).
-  const mintedBlock = emitMintedCreates(mod.aggregates, localDirectives, domainKey, dartTypes, skipAggregateIds);
-
   // PROVIDER SDK (the symmetric twin of the peer payload classes): for each declared
   // `impureCapability` capability, a typed Obligation/Result/Failure + handler typedef + dispatcher.
   // ADDITIVE + omit-when-empty: a domain with no `impureCapabilities` emits nothing (and the
@@ -4696,6 +4651,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
         combinedsByType.get(a.id) ?? [],
         refIdClassForAggregate,
         ownIdFieldsByAggregate.get(a.id) ?? new Set(),
+        aggregateWireTypeForAggregate,
       ),
     )
     .join("\n\n");
@@ -4821,7 +4777,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     `// Regenerate: \`npx tsx src/emit_dart.ts\` from ts_packages/co2-nomos-domains.`,
     `//`,
     `// ignore_for_file: unnecessary_this, prefer_const_constructors, constant_identifier_names`,
-    `// ignore_for_file: unused_import`,
+    `// ignore_for_file: unused_import, invalid_use_of_internal_member`,
     ``,
     // A nullable plain-`t.json()` read-model slot decode re-stringifies via `jsonEncode`.
     ...(needsJsonConvert ? [`import 'dart:convert';`] : []),
@@ -4830,7 +4786,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     // `../wire.dart` path into the framework (which broke when the generated dir moved
     // out of nomos_client into the co-located tenant package). The framework barrel
     // re-exports wire/dispatch/subscriptions/provider, so one import covers them all.
-    `import 'package:nomos_client/nomos_client.dart';`,
+    `import 'package:nomos_client/src/nms_generated_runtime.dart';`,
     // FRAMEWORK-SHARED aggregates (RelationTuple, …) are emitted ONCE per package in the shared
     // file; import it so this domain's read accessors / ref-id fields resolve those symbols.
     ...(opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
@@ -4887,13 +4843,6 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     `// ---- public intents (typed DTOs; ship via the generic offer() verb) ----`,
     dirBlock,
     ``,
-    ...(mintedBlock !== ""
-      ? [
-          `// ---- typed ids + minted creates (kernel id-mint: per-aggregate typed id classes + create… factories) ----`,
-          mintedBlock,
-          ``,
-        ]
-      : []),
     `// ---- read accessors (typed subscriptions over the GitHolon query()/query_by_id() surface) ----`,
     readBlock,
     ``,