@githolon/dsl 0.67.0 → 0.68.0

package/dart/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.45.0
+
+- `offerOutcome(...)` — the one outcome-returning offer lane generated clients now call for EVERY directive:
+  returns `NomosOfferOutcome` with workspace-stamped `created` (`NomosCreated` gains `workspace` + a
+  `NomosRef get ref` view). Activity raw rows carry `created` + `workspace`. Requires `nomos_types >= 0.1.3`.
+
 ## 0.44.0
 
 - Activity-feed runtime reads on `NomosBridge`/`NomosSession`: `activityLog({base, limit})` — the committed

package/dart/lib/src/webview_bridge.dart

@@ -23,6 +23,7 @@ import 'package:nomos_types/nomos_types.dart'
         nomosErrorFromInfo,
         NomosTraceContext,
         NomosErrorInfo,
+        NomosRef,
         NomosForeignReader,
         NomosForeignWorkspaceReader,
         ForeignAttestation;
@@ -104,7 +105,15 @@ class SyncStatus {
 class NomosCreated {
   final String type;
   final String id;
-  const NomosCreated({required this.type, required this.id});
+
+  /// The workspace the offer ran on (NomosRef). Additive — defaults to '' on older runners that
+  /// don't stamp it; then [ref] is workspace-blank (still a valid locator on the local plane).
+  final String workspace;
+  const NomosCreated({required this.type, required this.id, this.workspace = ''});
+
+  /// The canonical [NomosRef] view — the `{workspace,type,id}` triple, followable/serializable
+  /// (`nomos://<workspace>/<type>/<id>`). One reference, everywhere.
+  NomosRef get ref => NomosRef(workspace: workspace, type: type, id: id);
   @override
   String toString() => id;
 }
@@ -604,6 +613,10 @@ class NomosOfferOutcome {
   final String head;
   final List<NomosCreated> created;
 
+  /// The workspace the offer ran on (NomosRef). Additive; '' on older runners. Each [created] ref already
+  /// carries this, so `outcome.created.first.ref` is the full followable `{workspace,type,id}` locator.
+  final String workspace;
+
   /// The born child workspace name(s), when the offer ran a `.births()` directive (else empty). Each is a
   /// LOCAL workspace on this device's plane, resident in the shared engine plane the moment it is born:
   /// `bridge.session(name)` returns its handle, and `bridge.connect(session: name)` (no `restoreFrom`) mounts
@@ -616,6 +629,7 @@ class NomosOfferOutcome {
   const NomosOfferOutcome({
     required this.head,
     required this.created,
+    this.workspace = '',
     this.born = const [],
     this.birthOutcomes = const [],
   });
@@ -965,6 +979,32 @@ class NomosBridge {
     List<Map<String, Object?>>? attestations,
     bool? force,
     String? session,
+  }) =>
+      offerOutcome(
+        domain: domain,
+        directiveId: directiveId,
+        payload: payload,
+        actor: actor,
+        domainHash: domainHash,
+        attestations: attestations,
+        force: force,
+        session: session,
+      );
+
+  /// THE ONE OUTCOME-RETURNING OFFER LANE — [offerDirective] answering the full typed [NomosOfferOutcome]
+  /// (head + law-minted `created` NomosRefs + births), for EVERY generated method (create or mutate). A pure
+  /// mutation returns `created: []`; a `.creates(...)` plan returns the minted aggregate id(s), each already
+  /// carrying the session [workspace] so `outcome.created.first.ref` is a complete followable NomosRef with no
+  /// query-after round-trip. [offerCreates] is the historical alias (identical behavior).
+  Future<NomosOfferOutcome> offerOutcome({
+    required String domain,
+    required String directiveId,
+    required Object? payload,
+    String? actor,
+    String? domainHash,
+    List<Map<String, Object?>>? attestations,
+    bool? force,
+    String? session,
   }) async {
     final r = _asMap(await _call('offerDirective', {
       'domain': domain,
@@ -992,13 +1032,17 @@ class NomosBridge {
             .map((m) => (m['workspace'] ?? '').toString())
             .where((s) => s.isNotEmpty),
     ]..removeWhere((s) => s.isEmpty);
+    // The offer ran on this workspace (NomosRef) — stamp every minted ref with it so it is a complete locator.
+    final ws = (r['workspace'] ?? '').toString();
     return NomosOfferOutcome(
       head: r['head'].toString(),
+      workspace: ws,
       created: ((r['created'] as List?) ?? const [])
           .whereType<Map>()
           .map((m) => NomosCreated(
               type: (m['type'] ?? '').toString(),
-              id: (m['id'] ?? '').toString()))
+              id: (m['id'] ?? '').toString(),
+              workspace: ws))
           .toList(),
       born: bornNames,
       birthOutcomes: births,

package/dart/pubspec.lock

@@ -191,7 +191,7 @@ packages:
       path: "../dart_types"
       relative: true
     source: path
-    version: "0.1.0"
+    version: "0.1.2"
   package_config:
     dependency: transitive
     description:

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.44.0
+version: 0.45.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.2
+  nomos_types: ^0.1.3
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart_types/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.1.3
+
+- `NomosRef` — THE one typed reference `{workspace, type, id}`: value semantics, the canonical
+  `nomos://<workspace>/<type>/<id>` uri (`uri`/`parse`, encode round-trip), `fromJson` (object or uri),
+  `resolve()` over the multi-workspace reader. `ActivityRef` gains `workspace` + a `.ref` view; `ForeignRef`
+  gains `.ref`. Every reference shape now converges on the one triple. Purely additive.
+
 ## 0.1.2
 
 - Activity-feed runtime types: `ActivityEvent` (the shared activity row — kind/actor/occurredAt, rendered

package/dart_types/lib/nomos_types.dart

@@ -32,3 +32,4 @@ export 'src/errors.dart';
 // abstract interfaces (no bridge) — so both the layered TYPES package and nomos_client resolve them.
 export 'src/foreign_ref.dart';
 export 'src/activity.dart';
+export 'src/nomos_ref.dart';

package/dart_types/lib/src/activity.dart

@@ -8,22 +8,35 @@
 // the generated pure `renderActivity` lives) AND the runtime `nomos_client` package resolve them.
 library;
 
+import 'nomos_ref.dart';
+
 /// 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};
+  /// The source workspace (additive — empty on rows rendered before refs carried it).
+  final String workspace;
+
+  const ActivityRef({required this.type, required this.id, this.workspace = ''});
+
+  /// The canonical reference view (`nomos://<workspace>/<type>/<id>`).
+  NomosRef get ref => NomosRef(workspace: workspace, type: type, id: id);
+
+  factory ActivityRef.fromJson(Map<String, dynamic> j) => ActivityRef(
+      type: (j['type'] ?? '') as String,
+      id: (j['id'] ?? '') as String,
+      workspace: (j['workspace'] ?? '') as String);
+  Map<String, dynamic> toJson() =>
+      {'type': type, 'id': id, if (workspace.isNotEmpty) 'workspace': workspace};
 
   @override
-  bool operator ==(Object other) => other is ActivityRef && other.type == type && other.id == id;
+  bool operator ==(Object other) =>
+      other is ActivityRef && other.type == type && other.id == id && other.workspace == workspace;
   @override
-  int get hashCode => Object.hash(type, id);
+  int get hashCode => Object.hash(type, id, workspace);
 }
 
 /// Row prominence — a declared default the app may style or threshold on.

package/dart_types/lib/src/foreign_ref.dart

@@ -14,6 +14,8 @@
 // this barrel, and its `NomosBridge` implements [NomosForeignReader] over the device's multi-workspace plane.
 library;
 
+import 'nomos_ref.dart';
+
 /// Reads a FOREIGN workspace on demand — the surface a [ForeignRef] resolves against. It is STRUCTURAL: any
 /// object with this shape works. `nomos_client`'s `NomosBridge` implements it over the device's local
 /// multi-workspace plane (`bridge.session(ws).queryById(id)`, mounting the workspace lazily); the TS twin is
@@ -111,6 +113,10 @@ class ForeignRef<T> {
   /// The foreign aggregate type this locator points at.
   final String type;
 
+  /// The canonical reference view (`nomos://<workspace>/<type>/<id>`) — a [ForeignRef] IS a typed view over
+  /// the one reference triple.
+  NomosRef get ref => NomosRef(workspace: workspace, type: type, id: id);
+
   /// The target's decoder (the aggregate `fromJson` factory), applied to a resolved row's flat `data` map.
   final T Function(Map<String, dynamic> data, [String id]) _decode;
 

package/dart_types/lib/src/nomos_ref.dart

@@ -0,0 +1,75 @@
+// NOMOS — THE ONE REFERENCE (architecture/nomos_ref.md). A [NomosRef] is the canonical, globally-unique,
+// workspace-qualified identity of an aggregate instance: `{ workspace, type, id }`, with the stable string
+// form `nomos://<workspace>/<type>/<id>`. It travels WITH the data by default — every generated read row,
+// write outcome, and activity ref carries (or views as) one — so a dev holding a thing can always point at
+// it: no client-side UUID pre-minting, no loose {workspaceId, id} string pairs, no re-query-and-diff.
+//
+// A NomosRef is a LOCATOR (like ForeignRef, which remains the TYPED per-field view): `resolve` is an
+// informational read over the device's multi-workspace plane; law-grade attestation stays on the declared
+// attested-read lane. Pure nomos_types — no bridge/lifecycle imports.
+library;
+
+import 'foreign_ref.dart';
+
+/// The canonical typed reference to an aggregate instance: workspace + aggregate type + instance id.
+/// Value semantics; `uri` is the stable interop string (`nomos://<workspace>/<type>/<id>`).
+class NomosRef {
+  /// The workspace holding the instance.
+  final String workspace;
+
+  /// The aggregate TYPE (the read-projection type tag, e.g. `estate.EstateSite` or `EstateSite`).
+  final String type;
+
+  /// The instance id (law-minted or law-defined).
+  final String id;
+
+  const NomosRef({required this.workspace, required this.type, required this.id});
+
+  /// The stable string form — survives URLs, nav params, JSON, logs. Segments are URI-encoded so a
+  /// workspace/type/id containing `/` or spaces round-trips.
+  String get uri =>
+      'nomos://${Uri.encodeComponent(workspace)}/${Uri.encodeComponent(type)}/${Uri.encodeComponent(id)}';
+
+  /// Parse a `nomos://<workspace>/<type>/<id>` string (the inverse of [uri]). Throws [FormatException]
+  /// on anything else.
+  factory NomosRef.parse(String uri) {
+    final u = Uri.tryParse(uri);
+    if (u == null || u.scheme != 'nomos') {
+      throw FormatException('NomosRef.parse: not a nomos:// uri', uri);
+    }
+    // nomos://<ws>/<type>/<id> — the workspace lands as the authority (host), type/id as path segments.
+    final ws = Uri.decodeComponent(u.host);
+    final segs = u.pathSegments.map(Uri.decodeComponent).toList();
+    if (ws.isEmpty || segs.length != 2 || segs[0].isEmpty || segs[1].isEmpty) {
+      throw FormatException('NomosRef.parse: expected nomos://<workspace>/<type>/<id>', uri);
+    }
+    return NomosRef(workspace: ws, type: segs[0], id: segs[1]);
+  }
+
+  /// Accepts the `{workspace,type,id}` object OR the `nomos://` uri string.
+  factory NomosRef.fromJson(Object? j) {
+    if (j is String) return NomosRef.parse(j);
+    final m = (j as Map).cast<String, dynamic>();
+    return NomosRef(
+      workspace: (m['workspace'] ?? '') as String,
+      type: (m['type'] ?? '') as String,
+      id: (m['id'] ?? '') as String,
+    );
+  }
+
+  Map<String, dynamic> toJson() => {'workspace': workspace, 'type': type, 'id': id};
+
+  /// Informational lookup of the referenced instance over the device's multi-workspace plane (the same
+  /// reader `ForeignRef.resolve` uses — `bridge.foreignReader()` in nomos_client). Returns the raw
+  /// `{type,id,data}` rows for the id in the ref's workspace (empty ⇒ not found / not visible).
+  Future<List<Map<String, dynamic>>> resolve(NomosForeignReader nomos) =>
+      nomos.foreignWorkspace(workspace).queryById(id);
+
+  @override
+  bool operator ==(Object other) =>
+      other is NomosRef && other.workspace == workspace && other.type == type && other.id == id;
+  @override
+  int get hashCode => Object.hash(workspace, type, id);
+  @override
+  String toString() => uri;
+}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.67.0",
+  "version": "0.68.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

@@ -27,7 +27,9 @@ export type ActivitySeverity = "info" | "success" | "warning" | "critical";
 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"`). */
+  /** The payload field path holding the target's id (dotted for nested, e.g. `"location.siteId"`), OR the
+   *  sentinel `"@created"` — the id the LAW MINTED for this intent's created aggregate of `type` (read from
+   *  the sealed Create events at render time; the fix for "a .creates payload carries no id"). */
   readonly from: string;
 }
 
@@ -106,7 +108,12 @@ function payloadFieldNames(schema: unknown): Set<string> | undefined {
  * 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 {
+export function normalizeActivity(
+  directiveId: string,
+  input: ActivityInput,
+  payloadSchema?: unknown,
+  createdAggregateIds?: readonly string[],
+): 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").`);
@@ -148,10 +155,21 @@ export function normalizeActivity(directiveId: string, input: ActivityInput, pay
     }
     return { name, type: targetId as string, from: r.from };
   });
-  // Best-effort payload-field existence check (root of a dotted path).
+  // "@created" refs: the id comes from the intent's sealed Create events, not the payload — so the
+  // directive must actually CREATE that aggregate type (when the creates-set is known, enforce it).
+  for (const r of refs) {
+    if (r.from === "@created" && createdAggregateIds !== undefined && !createdAggregateIds.includes(r.type)) {
+      throw new Error(
+        `${where}: ref '${r.name}' uses "@created" but this directive does not .creates ${r.type} ` +
+          `(creates: ${createdAggregateIds.length > 0 ? createdAggregateIds.join(", ") : "nothing"}). ` +
+          `"@created" binds to the law-minted id of a created aggregate.`,
+      );
+    }
+  }
+  // Best-effort payload-field existence check (root of a dotted path). "@created" is not a payload path.
   const fields = payloadFieldNames(payloadSchema);
   if (fields !== undefined) {
-    for (const { name, from } of [...params, ...refs.map((r) => ({ name: `ref ${r.name}`, from: r.from }))]) {
+    for (const { name, from } of [...params, ...refs.filter((r) => r.from !== "@created").map((r) => ({ name: `ref ${r.name}`, from: r.from }))]) {
       const root = from.split(".")[0]!;
       if (!fields.has(root)) {
         throw new Error(

package/src/codegen_dart.ts

@@ -1197,6 +1197,10 @@ function emitAggregate(
     `  /// 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;`,
     ...specs.flatMap((s) => {
       const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
       // NULL SEMANTICS: a null-admitting field is the sealed tri-state slot (Omitted / ExplicitNull /
@@ -1208,6 +1212,7 @@ function emitAggregate(
   ].join("\n");
   const ctorParams = [
     `    this.aggregateId = const ${idType}.fromRow(''),`,
+    `    this.ref = const NomosRef(workspace: '', type: '${agg.id}', id: ''),`,
     ...specs.map(
       // A required scalar stays `required`; an optional scalar OR a collection is not
       // `required` (an absent optional scalar is null; an absent collection is empty).
@@ -1229,6 +1234,7 @@ function emitAggregate(
   // 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),`,
     ...specs.map((s) =>
       s.nullAdmits === true
         ? `      ${s.name}: NomosSlot.decode<${stripNullable(s.dartType)}>(data, '${s.wireName}', ${slotDecodeCallback(s, "aggregate")}),`
@@ -1281,7 +1287,10 @@ 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.`,
-    `  factory ${className}.fromJson(Map<String, dynamic> data, [String id = '']) {`,
+    `  ///`,
+    `  /// [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 = '']) {`,
     `    return ${className}(`,
     parseLines,
     `    );`,
@@ -2034,9 +2043,14 @@ const dartLit = (s: string): string => `'${s.replace(/\\/g, "\\\\").replace(/'/g
 function emitDartActivityArm(e: PackageActivityEntry): string[] {
   const { directiveId, desc } = e;
   const paramEntries = desc.params.map((p) => `        ${dartLit(p.name)}: _activityPayloadPath(payload, ${dartLit(p.from)}),`);
-  const refEntries = desc.refs.map(
-    (r) => `          ${dartLit(r.name)}: ActivityRef(type: ${dartLit(r.type)}, id: _activityPayloadPath(payload, ${dartLit(r.from)})),`,
-  );
+  const refEntries = desc.refs.map((r) => {
+    // A `from: "@created"` ref reads the id the LAW MINTED (the row's `created` list, first type match); any
+    // other `from` is a payload path. Every ref carries the session workspace (the row's `workspace`).
+    const id = r.from === "@created"
+      ? `_activityCreatedId(created, ${dartLit(r.type)})`
+      : `_activityPayloadPath(payload, ${dartLit(r.from)})`;
+    return `          ${dartLit(r.name)}: ActivityRef(workspace: workspace, type: ${dartLit(r.type)}, id: ${id}),`;
+  });
   return [
     `    case ${dartLit(directiveId)}:`,
     `      {`,
@@ -2113,12 +2127,28 @@ export function generateDartActivityRegistry(entries: readonly PackageActivityEn
     `  return cur == null ? '' : '\$cur';`,
     `}`,
     ``,
+    `/// The id the LAW minted for a \`from: "@created"\` ref — the first entry of the row's \`created\` list`,
+    `/// whose type matches the declared aggregate (the runtime type is uuid-stripped + may be namespaced, so`,
+    `/// match on equality OR \`<domain>.<Type>\` suffix). '' when the holon returned no created list (era-safe).`,
+    `String _activityCreatedId(List<Map<String, dynamic>> created, String declared) {`,
+    `  for (final c in created) {`,
+    `    final t = (c['type'] ?? '') as String;`,
+    `    if (t == declared || t.endsWith('.\$declared')) return (c['id'] ?? '') as String;`,
+    `  }`,
+    `  return '';`,
+    `}`,
+    ``,
     `/// Fold ONE committed-intent raw row into a typed [ActivityEvent], or null when the directive declares`,
-    `/// no \`.activity(...)\`. rawRow = { intentId, domain, directiveId, actorSubject, occurredAt, payload }.`,
+    `/// no \`.activity(...)\`. rawRow = { intentId, domain, directiveId, actorSubject, occurredAt, payload,`,
+    `/// created, workspace } — \`created\` (\`[{type,id}]\`) backs \`from: "@created"\` refs; \`workspace\` stamps them.`,
     `ActivityEvent? renderActivity(Map<String, dynamic> rawRow) {`,
     `  final directiveId = (rawRow['directiveId'] ?? '') as String;`,
     `  final actorSubject = (rawRow['actorSubject'] ?? '') as String;`,
+    `  final workspace = (rawRow['workspace'] ?? '') as String;`,
     `  final payload = ((rawRow['payload'] as Map?)?.cast<String, dynamic>()) ?? const <String, dynamic>{};`,
+    `  final created = ((rawRow['created'] as List?) ?? const <dynamic>[])`,
+    `      .map((e) => (e as Map).cast<String, dynamic>())`,
+    `      .toList();`,
     `  switch (directiveId) {`,
     ...sorted.flatMap(emitDartActivityArm),
     `    default:`,
@@ -2524,6 +2554,10 @@ function emitReadModel(
     `  /// 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;`,
     ...specs.flatMap((s) => {
       const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
       return s.nullAdmits === true
@@ -2541,6 +2575,7 @@ function emitReadModel(
   ].join("\n");
   const ctorParams = [
     `    this.aggregateId = const ${idType}.fromRow(''),`,
+    `    this.ref = const NomosRef(workspace: '', type: '${agg.id}', id: ''),`,
     ...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.
@@ -2558,6 +2593,7 @@ function emitReadModel(
 
   const parseLines = [
     `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
+    `      ref: NomosRef(workspace: workspace, type: type.isEmpty ? '${agg.id}' : type, id: id),`,
     ...specs.map((s) =>
       s.nullAdmits === true
         ? `      ${s.name}: NomosSlot.decode<${stripNullable(readModelDartType(s))}>(data, '${s.wireName}', ${slotDecodeCallback(s, "readModel")}),`
@@ -2591,7 +2627,10 @@ 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.`,
-    `  factory ${className}.fromProjected(Map<String, dynamic> data, [String id = '']) {`,
+    `  ///`,
+    `  /// [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 = '']) {`,
     `    return ${className}(`,
     parseLines,
     `    );`,

package/src/codegen_dart_client.ts

@@ -87,10 +87,11 @@ function dartKeyParam(key: string): string {
   return safeMethod(safe);
 }
 
-/** Parse ONE bridge row (`{type,id,data}`) into a typed read model. Works for a `Map` (one-shot
+/** Parse ONE bridge row (`{type,id,data}`) into a typed read model, composing the canonical `.ref` from the
+ * session workspace (`_ws`, a getter on the client) + the row's type/id. Works for a `Map` (one-shot
  * `query`/`queryById` rows) or a `dynamic` (`watch` stream rows) — indexing resolves on both. */
 function rowToModel(model: string, rowVar: string): string {
-  return `${model}.fromProjected((${rowVar}['data'] as Map).cast<String, dynamic>(), (${rowVar}['id'] ?? '').toString())`;
+  return `${model}.fromProjected((${rowVar}['data'] as Map).cast<String, dynamic>(), (${rowVar}['id'] ?? '').toString(), _ws, (${rowVar}['type'] ?? '').toString())`;
 }
 
 export interface DartBridgeClientOptions {
@@ -199,16 +200,19 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     // E2E SEALING (the sealing client): a directive with `.encrypted()` payload fields SEALS them via the
     // bound [keyStore] before dispatch (a missing key throws [EncryptionKeyUnavailable] — never a plaintext
     // write). One async block covers creates + mutate + gated + stamps; `seal: false` is the escape hatch.
+    // THE ONE WRITE OUTCOME (architecture/nomos_ref.md): EVERY directive method returns Future<NomosOfferOutcome>
+    // via the ONE lane `bridge.offerOutcome` — `outcome.created` carries every minted aggregate (each with its
+    // typed `.ref`), `outcome.head` the new local head. The breaking cut: creates AND non-creates alike.
+    const createsDoc = (d as { marker?: string }).marker === "creates"
+      ? ` The LAW mints the ${(d as { aggregateId?: string }).aggregateId ?? "aggregate"} id inside the sealed intent — it rides back on \`outcome.created\` (no id in the payload, no query-after).`
+      : "";
+    const stampsDoc = stamps.length > 0 ? `\n  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.` : "";
     if (encMap?.directives?.[d.id] !== undefined) {
-      const isCreates = (d as { marker?: string }).marker === "creates";
-      const retType = isCreates ? "NomosOfferOutcome" : "String";
-      const offerFn = isCreates ? "offerCreates" : "offerDirective";
       methods.push(
-        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
-        `  /// Encrypted field(s) are SEALED via the bound [keyStore] before dispatch (pass \`seal: false\` to skip).`,
-        ...(stamps.length > 0 ? [`  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`] : []),
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
+        `  /// Encrypted field(s) are SEALED via the bound [keyStore] before dispatch (pass \`seal: false\` to skip).${stampsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
-        `  Future<${retType}> ${method}(${payloadClass} payload, {bool seal = true}) async {`,
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload, {bool seal = true}) async {`,
         ...(gateGuard ? [gateGuard] : []),
         `    final data = payload.toPayloadJson();`,
         ...(stamps.length > 0
@@ -218,64 +222,42 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
             ]
           : []),
         `    await _sealPayload(data, ${dartStr(d.id)}, seal);`,
-        `    return bridge.${offerFn}(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
+        `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
         `  }`,
         ``,
       );
       continue;
     }
-    if ((d as { marker?: string }).marker === "creates") {
-      // LAW-MINTED ID RETURN: a `.creates` plan mints its aggregate id inside the sealed intent (the payload
-      // carries none — callers never supply ids). The bridge's offerCreates hands the minted ids back with the
-      // head, so the create method returns the typed id with NO query-after round-trip.
+    if (stamps.length > 0) {
       methods.push(
-        `  /// Author \`${domain}/${d.id}\` — the LAW mints the ${(d as { aggregateId?: string }).aggregateId ?? "aggregate"} id inside the sealed`,
-        `  /// intent; it returns here (\`outcome.created\`) with the new local head. No id in the payload, no query-after.`,
-        ...(stamps.length > 0 ? [`  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`] : []),
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}${stampsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
         `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) {`,
         ...(gateGuard ? [gateGuard] : []),
         `    final data = payload.toPayloadJson();`,
-        ...(stamps.length > 0
-          ? [
-              `    final now = DateTime.now().toUtc().toIso8601String();`,
-              ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
-            ]
-          : []),
-        `    return bridge.offerCreates(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
-        `  }`,
-        ``,
-      );
-    } else if (stamps.length > 0) {
-      methods.push(
-        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
-        `  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`,
-        ...(gateDoc ? [gateDoc] : []),
-        `  Future<String> ${method}(${payloadClass} payload) {`,
-        ...(gateGuard ? [gateGuard] : []),
-        `    final data = payload.toPayloadJson();`,
         `    final now = DateTime.now().toUtc().toIso8601String();`,
         ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
-        `    return bridge.offerDirective(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
+        `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
         `  }`,
         ``,
       );
     } else if (gateGuard) {
       // A gated directive with no `…At` sugar still needs a block body for the throw guard.
       methods.push(
-        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
         gateDoc,
-        `  Future<String> ${method}(${payloadClass} payload) {`,
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) {`,
         gateGuard,
-        `    return bridge.offerDirective(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
+        `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
         `  }`,
         ``,
       );
     } else {
       methods.push(
-        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
-        `  Future<String> ${method}(${payloadClass} payload) =>`,
-        `      bridge.offerDirective(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
+        ...(gateDoc ? [gateDoc] : []),
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) =>`,
+        `      bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
         ``,
       );
     }
@@ -440,7 +422,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `// client file gives an app the whole typed surface.`,
     ...(opts.typesImportUri !== undefined ? [`export '${opts.typesImportUri}';`] : [`export '${mod.name}.dart';`]),
     ...(opts.typesImportUri === undefined && opts.frameworkImportUri !== undefined ? [`export '${opts.frameworkImportUri}';`] : []),
-    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion, NomosCompat, NomosCompatMember${encPresent ? ", NomosScopeKey, NomosKeyStore, EncryptionKeyUnavailable, WrappedKeyStore, NomosEncryption, NomosEpochResult, EncryptionMemberKeyMissing, EncryptionRosterMismatch" : ""};`,
+    `export '${supportImport}' show NomosBridge, NomosSession, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion, NomosCompat, NomosCompatMember, NomosOfferOutcome, NomosCreated, NomosRef${encPresent ? ", NomosScopeKey, NomosKeyStore, EncryptionKeyUnavailable, WrappedKeyStore, NomosEncryption, NomosEpochResult, EncryptionMemberKeyMissing, EncryptionRosterMismatch" : ""};`,
     ``,
     `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,
     `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
@@ -490,6 +472,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       : []),
     `  ${className}(this.bridge, {this.domainHash = ${hashConst}, this.actor${encPresent ? ", this.keyStore" : ""}});`,
     ``,
+    `  /// The session workspace this client is bound to (from the [NomosSession] handle, when constructed with`,
+    `  /// one) — the \`workspace\` of every read row's canonical [NomosRef]. '' on a bare (non-session) bridge.`,
+    `  String get _ws {`,
+    `    final b = bridge;`,
+    `    return b is NomosSession ? b.workspace : '';`,
+    `  }`,
+    ``,
     ...(encPresent ? dartEncClassMembers(encMap!) : []),
     // THE OWNER CEREMONY (slice 2): grantAndWrap / revokeAndRotate / rotate — the operator-blind key-epoch
     // handshake as one call. Bind `actor` (the owner) to author the fan-out. Only for a domain with a scope.

package/src/codegen_ts.ts

@@ -679,7 +679,14 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[]): string[]
     const { directiveId, desc } = e;
     const params = desc.params.map((p) => `${_actLit(p.name)}: _activityPayloadPath(row.payload, ${_actLit(p.from)})`).join(", ");
     const refs = desc.refs
-      .map((r) => `${_actLit(r.name)}: { type: ${_actLit(r.type)}, id: _activityPayloadPath(row.payload, ${_actLit(r.from)}) }`)
+      .map((r) => {
+        // A `from: "@created"` ref reads the id the LAW MINTED (the row's `created` list, first type match);
+        // any other `from` is a payload path. Every ref carries the session workspace (the row's `workspace`).
+        const id = r.from === "@created"
+          ? `_activityCreatedId(row.created, ${_actLit(r.type)})`
+          : `_activityPayloadPath(row.payload, ${_actLit(r.from)})`;
+        return `${_actLit(r.name)}: { workspace: row.workspace ?? "", type: ${_actLit(r.type)}, id: ${id} }`;
+      })
       .join(", ");
     return [
       `  ${_actLit(directiveId)}: (row: ActivityRawRow): ActivityEvent => {`,
@@ -699,8 +706,9 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[]): string[]
   };
   return [
     `// ── activity feed (architecture/activity_descriptors.md) — typed rows folded from the intent log ──`,
-    `/** A declared navigation target on an activity row (the referenced type + the resolved id). */`,
-    `export interface ActivityRef { type: string; id: string }`,
+    `/** A declared navigation target on an activity row: the canonical [NomosRef] triple (workspace + type +`,
+    ` *  resolved id). A \`from: "@created"\` ref resolves the id the LAW minted; others a payload path. */`,
+    `export interface ActivityRef { workspace: string; type: string; id: string }`,
     `/** A rendered activity row — produced by \`renderActivity\` from a directive's declared \`.activity(...)\`. */`,
     `export interface ActivityEvent {`,
     `  eventId: string; kind: string; actorSubject: string; occurredAt: string;`,
@@ -711,7 +719,7 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[]): string[]
     `  domain: string; directiveId: string;`,
     `}`,
     `/** The runtime's per-committed-intent RAW ROW (the shape \`holon.watchActivity\`/\`activityLog\` yield). */`,
-    `export interface ActivityRawRow { intentId: string; domain: string; directiveId: string; actorSubject: string; occurredAt: string; payload: Record<string, unknown> }`,
+    `export interface ActivityRawRow { intentId: string; domain: string; directiveId: string; actorSubject: string; occurredAt: string; payload: Record<string, unknown>; created?: { type: string; id: string }[]; workspace?: string }`,
     `/** A NARRATIVE over the activity log (for an in-app LLM): the filtered events + a plain-English \`transcript\``,
     ` *  (ONE LINE PER EVENT, oldest-first, \`"<occurredAt> — <title>: <message>"\`) — grounding text over the`,
     ` *  VERIFIED log, never raw payloads. Produced by the client's \`describe\` / \`describeHistory\`. */`,
@@ -729,6 +737,14 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[]): string[]
     `  }`,
     `  return cur === null || cur === undefined ? "" : String(cur);`,
     `}`,
+    `/** The id the LAW minted for a \`from: "@created"\` ref — the first entry of the row's \`created\` list whose`,
+    ` *  type matches the declared aggregate (the runtime type is uuid-stripped + may be namespaced, so match on`,
+    ` *  equality OR \`<domain>.<Type>\` suffix). "" when the holon returned no created list (era-safe). */`,
+    `function _activityCreatedId(created: { type: string; id: string }[] | undefined, declared: string): string {`,
+    `  if (created === undefined) return "";`,
+    `  for (const c of created) if (c.type === declared || c.type.endsWith("." + declared)) return c.id;`,
+    `  return "";`,
+    `}`,
     `/** Interpolate \`{name}\` placeholders in a template from vars (a missing var renders empty). */`,
     `function _renderActivityTemplate(template: string, vars: Record<string, string>): string {`,
     `  return template.replace(/\\{([a-zA-Z0-9_]+)\\}/g, (_m, name: string) => vars[name] ?? "");`,
@@ -813,8 +829,46 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           ``,
         ]
       : []),
-    `/** One projection row: the aggregate's wire type, its id, and the folded fields. */`,
-    `export interface Row<T> { type: string; id: string; data: T }`,
+    `/** THE ONE REFERENCE (architecture/nomos_ref.md) — the canonical, workspace-qualified identity of an`,
+    ` *  aggregate instance: \`{ workspace, type, id }\`, with the stable interop string`,
+    ` *  \`nomos://<workspace>/<type>/<id>\`. Carried on every read \`Row.ref\` + write outcome + activity ref. */`,
+    `export interface NomosRef { workspace: string; type: string; id: string }`,
+    `/** The stable \`nomos://<workspace>/<type>/<id>\` string form (each segment URI-encoded — a workspace/`,
+    ` *  type/id containing \`/\` or spaces round-trips). Survives URLs, nav params, JSON, logs. */`,
+    `export function nomosRefUri(ref: NomosRef): string {`,
+    `  return "nomos://" + encodeURIComponent(ref.workspace) + "/" + encodeURIComponent(ref.type) + "/" + encodeURIComponent(ref.id);`,
+    `}`,
+    `/** Parse a \`nomos://<workspace>/<type>/<id>\` string back into a [NomosRef] (the inverse of [nomosRefUri]);`,
+    ` *  throws on anything else. */`,
+    `export function parseNomosRef(uri: string): NomosRef {`,
+    "  const m = /^nomos:\\/\\/([^/]+)\\/([^/]+)\\/([^/]+)$/.exec(uri);",
+    `  if (m === null) throw new Error("parseNomosRef: expected nomos://<workspace>/<type>/<id>: " + uri);`,
+    `  return { workspace: decodeURIComponent(m[1]!), type: decodeURIComponent(m[2]!), id: decodeURIComponent(m[3]!) };`,
+    `}`,
+    `/** One projection row: the aggregate's wire type, its id, the folded fields, and the canonical [NomosRef]`,
+    ` *  (composed at decode from the session workspace + the row's type/id — additive, the \`data\` is untouched). */`,
+    `export interface Row<T> { type: string; id: string; data: T; ref: NomosRef }`,
+    `/** Stamp each row's canonical [NomosRef] from the session \`ws\` + the row's type/id (additive — already-`,
+    ` *  stamped rows pass through). */`,
+    `function _stampRefs<T>(ws: string, rows: Row<T>[]): Row<T>[] {`,
+    `  return rows.map((r) => (r.ref !== undefined ? r : { ...r, ref: { workspace: ws, type: r.type, id: r.id } }));`,
+    `}`,
+    `function _stampRefsP<T>(ws: string, p: Promise<Row<T>[]>): Promise<Row<T>[]> { return p.then((rows) => _stampRefs(ws, rows)); }`,
+    `/** THE TYPED WRITE OUTCOME (architecture/nomos_ref.md) — every generated directive method returns this.`,
+    ` *  \`created\` is EVERY aggregate the plan minted (typed [NomosRef]s, composed with the session workspace;`,
+    ` *  \`[]\` on a holon too old to return them — never a fake id). \`target\` is the addressed instance for a`,
+    ` *  front-door-mint lane (statically known); omitted otherwise. \`head\` is the new local head. */`,
+    `export interface NomosOutcome { head: string; created: NomosRef[]; target?: NomosRef }`,
+    `/** Fold a holon offer result (a bare head, or \`{ head, created }\` under returnCreated) into a [NomosOutcome]`,
+    ` *  — composing each created \`{type,id}\` with the session \`ws\`. \`target\` rides through when the caller`,
+    ` *  statically knows the addressed instance (the front-door mint). */`,
+    `async function _outcome(ws: string, r: Promise<string | { head: string; created?: { type: string; id: string }[] }>, target?: NomosRef): Promise<NomosOutcome> {`,
+    `  const v = await r;`,
+    `  const obj = typeof v === "object" && v !== null;`,
+    `  const head = obj ? v.head : String(v);`,
+    `  const created = (obj ? v.created ?? [] : []).map((c) => ({ workspace: ws, type: c.type, id: c.id }));`,
+    `  return target !== undefined ? { head, created, target } : { head, created };`,
+    `}`,
     // MULTI-WORKSPACE LOCATORS (t.foreignRef): a TYPED cross-workspace edge — the foreign aggregate's id +
     // the foreign workspace id (from a sibling field). NOT an atomic FK: it does not clone/open the other
     // holon; `resolve`/`watch` open it ON DEMAND over a realm (openRealm's `.workspace(ws)` surface).
@@ -899,6 +953,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean }): Promise<string>;`,
     `  /** Opaque-bytes offer — retained for carriers that already hold an encoded envelope (back-compat). */`,
     `  offer(intentBytes: string | Uint8Array): Promise<string>;`,
+    `  /** The workspace this holon is bound to — the \`workspace\` of every [NomosRef] this client composes. */`,
+    `  workspace: string;`,
     ...(encPresent
       ? [
           `  /** \`keys\` (E2E sealing): the reader's held scope keys, injected so encrypted fields decrypt;`,
@@ -1341,8 +1397,12 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   const foreignRefFields: { agg: string; field: string; workspaceField: string; target: string }[] = [];
   // wrap a read accessor return expression through the foreignRef row-hydrator (identity + byte-identical
   // when the package declares no foreignRef, so non-foreignRef packages are unchanged).
-  const wrapP = (expr: string): string => (foreignRefFields.length > 0 ? `_hydrateP(${expr})` : expr);
-  const wrapRows = (expr: string): string => (foreignRefFields.length > 0 ? `_hydrateRows(${expr})` : expr);
+  // Every read accessor's rows get their canonical `.ref` stamped from `holon.workspace` (additive); a
+  // foreignRef-declaring package ALSO hydrates its foreignRef fields into typed locators first.
+  const wrapP = (expr: string): string =>
+    `_stampRefsP(holon.workspace, ${foreignRefFields.length > 0 ? `_hydrateP(${expr})` : expr})`;
+  const wrapRows = (expr: string): string =>
+    `_stampRefs(holon.workspace, ${foreignRefFields.length > 0 ? `_hydrateRows(${expr})` : expr})`;
   for (const [typeId, agg] of [...aggByType].sort(([a], [b]) => a.localeCompare(b))) {
     out.push(`export interface ${typeId}Data {`);
     for (const [name, field] of Object.entries(agg.fields)) {
@@ -1663,6 +1723,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed, lazyReg, d.id)};`,
         ``,
       );
+      // THE ONE WRITE OUTCOME (architecture/nomos_ref.md): EVERY directive method returns Promise<NomosOutcome>
+      // — `created` (typed refs of all minted aggregates, from returnCreated) + `head`, plus `target` for the
+      // front-door-mint lane (the one statically-known addressed instance). One async block covers every case.
       if (mint !== undefined) {
         const mintOpts =
           mint.homeKeyField !== undefined
@@ -1675,65 +1738,31 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           : `{ ...${pv}, ${mint.field} }`;
         methods.push(
           `    /** Author \`${domain}/${d.id}\`: the front-door MINTS \`${mint.field}\` (route-tagged) when omitted`,
-          `     *  — ids stay internal plumbing — and returns it with the new local head.${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
-          `    ${d.id}: async (${paramSig}): Promise<{ head: string; ${mint.field}: string }> => {`,
+          `     *  — ids stay internal plumbing — and returns the outcome (\`target\` = the minted ${dd.aggregateId ?? "aggregate"}).${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
+          `    ${d.id}: async (${paramSig}): Promise<NomosOutcome> => {`,
           ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
           ...(sealPrelude ? [sealPrelude] : []),
           `      const ${mint.field} = payload.${mint.field} ?? (await (holon as NomosRoutedHolon).mint(${JSON.stringify(mint.mintType)}${mintOpts}));`,
-          `      const head = await holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor });`,
-          `      return { head, ${mint.field} };`,
+          `      return _outcome(holon.workspace, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor, returnCreated: true }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>, { workspace: holon.workspace, type: ${JSON.stringify(dd.aggregateId ?? mint.mintType)}, id: ${mint.field} });`,
           `    },`,
         );
         continue;
       }
       const offerPayload = stamps.length ? `stampNow(${pv}, ${JSON.stringify(stamps)})` : pv;
-      if (d.marker === "creates") {
-        // LAW-MINTED ID RETURN: a `.creates` plan mints its aggregate id inside the sealed intent (the payload
-        // carries none). The holon hands the minted ids back on the offer (`returnCreated`), so the create
-        // method returns the typed id with NO query-after. Older holons (pre-returnCreated) answer a bare head
-        // string — degrade to id:"" rather than refuse (structural binding, era-safe).
-        methods.push(
-          `    /** Author \`${domain}/${d.id}\`: the LAW mints the ${d.aggregateId ?? "aggregate"} id inside the sealed intent`,
-          `     *  and it returns here with the new local head — no id in the payload, no query-after.${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
-          `    ${d.id}: async (${paramSig}): Promise<{ head: string; id: string }> => {`,
-          ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
-          ...(sealPrelude ? [sealPrelude] : []),
-          `      const r = await (holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>);`,
-          `      return typeof r === "object" && r !== null ? { head: r.head, id: r.created?.[0]?.id ?? "" } : { head: String(r), id: "" };`,
-          `    },`,
-        );
-        continue;
-      }
-      const offerCall = `holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor })`;
-      if (wantSeal) {
-        // SEALING directive (optionally also gated): an ASYNC block — seal the encrypted fields via the
-        // bound { keyStore } (+ throw MissingOfferAuthority first if gated) before dispatch.
-        methods.push(
-          `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
-          `     *  Encrypted field(s) are SEALED via the bound { keyStore } before dispatch (pass { seal: false } to skip).${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
-          `    ${d.id}: async (${paramSig}): Promise<string> => {`,
-          ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
-          sealPrelude,
-          `      return ${offerCall};`,
-          `    },`,
-        );
-      } else if (gateGuard) {
-        // GATED directive: a block body that throws MissingOfferAuthority when no actor is bound — an
-        // actorless gated offer can't be constructed (the war: the gate is structural, not just kernel-side).
-        methods.push(
-          `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
-          `     *  GATED: needs \`{ actor }\` (the \`${gate!.relation}\` relation) — throws MissingOfferAuthority otherwise. */`,
-          `    ${d.id}: (payload: ${payloadName}): Promise<string> => {`,
-          gateGuard.replace(/\n$/, ""),
-          `      return ${offerCall};`,
-          `    },`,
-        );
-      } else {
-        methods.push(
-          `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head. */`,
-          `    ${d.id}: (payload: ${payloadName}) => ${offerCall},`,
-        );
-      }
+      const outcomeDoc =
+        d.marker === "creates"
+          ? `Author \`${domain}/${d.id}\`: the LAW mints the ${d.aggregateId ?? "aggregate"} id inside the sealed intent; it rides back on \`outcome.created\` — no id in the payload, no query-after.`
+          : `Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOutcome] (\`head\` + any \`created\` refs).`;
+      const sealDoc = wantSeal ? " Encrypted field(s) are SEALED via the bound { keyStore } before dispatch (pass { seal: false } to skip)." : "";
+      const gateDoc = gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`) — throws MissingOfferAuthority otherwise.` : "";
+      methods.push(
+        `    /** ${outcomeDoc}${sealDoc}${gateDoc} */`,
+        `    ${d.id}: async (${paramSig}): Promise<NomosOutcome> => {`,
+        ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
+        ...(sealPrelude ? [sealPrelude] : []),
+        `      return _outcome(holon.workspace, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>);`,
+        `    },`,
+      );
     }
 
     for (const sp of (mod.spatials ?? []) as { id: string; of: string; on: string }[]) {
@@ -1806,9 +1835,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           : `    list${agg.id}s: () => ${wrapP(`holon.query("aggregatesByType", { __type: ${JSON.stringify(agg.id)} }) as Promise<Row<${agg.id}Data>[]>`)},`,
         `    /** Watch one ${agg.id} by aggregate id (local reactive read; returns stop()). */`,
         `    watch${agg.id}ById: (id: string, cb: (rows: Row<${agg.id}Data>[]) => void, opts?: { intervalMs?: number }) =>`,
-        foreignRefFields.length > 0
-          ? `      holon.watchById(id, ((rows: Row<${agg.id}Data>[]) => cb(_hydrateRows(rows))) as (rows: unknown) => void, opts),`
-          : `      holon.watchById(id, cb as (rows: unknown) => void, opts),`,
+        `      holon.watchById(id, ((rows: Row<${agg.id}Data>[]) => cb(${wrapRows("rows")})) as (rows: unknown) => void, opts),`,
       );
     }
 

package/src/compile_package_main.ts

@@ -431,6 +431,7 @@ const DART_SUPPORT_CORE_SRC = [
   // model with a `t.foreignRef` field references `ForeignRef<Target>` through the barrel, so it must vendor.
   "foreign_ref.dart",
   "activity.dart",
+  "nomos_ref.dart",
 ] as const;
 // The RUNTIME support files, vendored from `nomos_client` (dsl/dart/lib/src): the async WebView
 // bridge the generated `<name>.client.dart` drives, and the provider surface. Their
@@ -861,10 +862,10 @@ function emitDart(
 /** The pure-core support import generated TYPES files carry in layered-packages mode. */
 const DART_TYPES_IMPORT = `import 'package:nomos_types/nomos_types.dart';`;
 /** Version constraints the scaffolded pubspecs pin — move together with the Dart packages' releases. */
-// FLOOR = the release carrying every symbol generated code may reference (0.1.2: ActivityEvent).
-const NOMOS_TYPES_DEP = "^0.1.2";
-// FLOOR = the release carrying the bridge methods generated clients call (0.44.0: activityLog/watchActivity).
-const NOMOS_CLIENT_DEP = "^0.44.0";
+// FLOOR = the release carrying every symbol generated code may reference (0.1.3: NomosRef).
+const NOMOS_TYPES_DEP = "^0.1.3";
+// FLOOR = the release carrying the bridge methods generated clients call (0.45.0: offerOutcome/NomosCreated.ref).
+const NOMOS_CLIENT_DEP = "^0.45.0";
 
 const isPubPackageName = (s: string): boolean => /^[a-z][a-z0-9_]*$/.test(s);
 

package/src/directive.ts

@@ -830,8 +830,13 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
     },
     activity(input: ActivityInput): RequirableDirective<P> {
       // Normalize + validate against this directive's payload (unknown template var / missing payload field
-      // refuse here). Non-law, additive — stored like `description`.
-      return makeRequirable({ ...base, activityDescriptor: normalizeActivity(base.id, input, base.payloadSchema) });
+      // refuse here). "@created" refs are checked against the aggregates this directive CREATES (the primary
+      // .creates target + any .alsoCreates). Non-law, additive — stored like `description`.
+      const createdIds = [
+        ...(base.marker === "creates" ? [base.aggregateId] : []),
+        ...(base.secondaryOutputs ?? []).filter((o) => o.marker === "creates").map((o) => o.aggregateId),
+      ];
+      return makeRequirable({ ...base, activityDescriptor: normalizeActivity(base.id, input, base.payloadSchema, createdIds) });
     },
     readsCertified(reads: Record<string, CertifiedReadDecl>): RequirableDirective<P> {
       // Accumulate onto any prior declared CertifiedReads (a repeated local name's later decl