@githolon/dsl 0.37.0 → 0.38.0

package/dart/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.29.0
+
+- LAW-MINTED IDS RETURN TO THE CALLER: `NomosBridge.offerCreates(...)` → `NomosOfferOutcome{head, created}` — a `.creates` plan mints its aggregate id inside the sealed intent (payloads never carry one); the offer now hands the minted ids back, so generated create methods return the typed id with no query-after round-trip. New types `NomosOfferOutcome` / `NomosCreated`.
+- `NomosBridge.mintId(typeTag)` — reserve a kernel-minted typed id (`<TypeTag>_<uuidv7>`) via the holon's front-door mint, for app-side references. (`.creates` payloads still carry NO id — the law mints those.)
+- Generated Dart clients (`nomos-compile` ≥0.38 tooling): `.creates(...)` directive methods now return `Future<NomosOfferOutcome>` instead of `Future<String>` — `outcome.created.single.id` is the new aggregate's typed id.
+
 ## 0.28.0
 
 - `NomosTestHarness` (`nomos_headless.dart`): ephemeral real-law fixtures — one call births a throwaway cloud workspace, deploys compiled `*.deploy.json` law, and hands out independent client replicas (`connect(clientId:)`) over the node runner. Identity defaults to the `githolon login --agent` session (`~/.holon/credentials.json`). Live-proven: birth → deploy → write on one replica → converge + typed read on another, 14s end-to-end.

package/dart/lib/src/webview_bridge.dart

@@ -265,6 +265,23 @@ class SyncStatus {
       );
 }
 
+/// One law-minted aggregate from a `.creates(...)` offer: the full typed [id] (`<domain>.<Type>_<uuidv7>`)
+/// and its [type] (`<domain>.<Type>`).
+class NomosCreated {
+  final String type;
+  final String id;
+  const NomosCreated({required this.type, required this.id});
+  @override
+  String toString() => id;
+}
+
+/// The result of [NomosBridge.offerCreates]: the new local [head] plus every aggregate the plan minted.
+class NomosOfferOutcome {
+  final String head;
+  final List<NomosCreated> created;
+  const NomosOfferOutcome({required this.head, required this.created});
+}
+
 /// THE BRIDGE. Construct over a [BridgeTransport], `await ready`, then `connect(...)` and drive the holon.
 class NomosBridge {
   final BridgeTransport _transport;
@@ -509,6 +526,42 @@ class NomosBridge {
     return r['head'].toString();
   }
 
+  /// [offerDirective], answering the LAW-MINTED ids too. A `.creates(...)` plan mints its aggregate id
+  /// inside the sealed intent (callers never supply one); the runner hands back what was minted, so a
+  /// generated create method returns the typed id with NO query-after round-trip. [created] is empty for
+  /// pure mutations.
+  Future<NomosOfferOutcome> offerCreates({
+    required String domain,
+    required String directiveId,
+    required Object? payload,
+    String? actor,
+    String? domainHash,
+  }) async {
+    final r = _asMap(await _call('offerDirective', {
+      'domain': domain,
+      'directiveId': directiveId,
+      'payload': payload,
+      if (actor != null) 'actor': actor,
+      if (domainHash != null) 'domainHash': domainHash,
+    }));
+    return NomosOfferOutcome(
+      head: r['head'].toString(),
+      created: ((r['created'] as List?) ?? const [])
+          .whereType<Map>()
+          .map((m) => NomosCreated(
+              type: (m['type'] ?? '').toString(),
+              id: (m['id'] ?? '').toString()))
+          .toList(),
+    );
+  }
+
+  /// Reserve a KERNEL-MINTED typed id (`<TypeTag>_<uuidv7>`) via the holon's front-door mint — for app-side
+  /// references (routing keys, optimistic UI). `.creates` payloads still carry NO id: the LAW mints those
+  /// (see [offerCreates], which returns them).
+  Future<String> mintId(String typeTag) async =>
+      (_asMap(await _call('mintId', {'typeTag': typeTag}))['id'] ?? '')
+          .toString();
+
   /// UNDO the most-recent action via the kernel STRIKE primitive (the fold drops the struck intent by parity).
   /// [scope] `'all'` undoes any author's most-recent action; `'user'` only THIS replica's own. [actions] is the
   /// app's set of undoable directive ids (so undo never strikes a framework/control intent). [domain] +

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

package/dart/test/test_harness_test.dart

@@ -44,7 +44,9 @@ void main() {
       try {
         final writer = await harness.connect(clientId: 'writer');
         final reader = await harness.connect(clientId: 'reader');
-        await writer.offerDirective(
+        final minted = await writer.mintId('Fixture');
+        expect(minted, startsWith('Fixture_'));
+        final outcome = await writer.offerCreates(
             domain: 'guestbook',
             directiveId: 'signGuestbook',
             payload: {
@@ -53,10 +55,13 @@ void main() {
               'mood': 'delighted',
               'signedAt': DateTime.now().toUtc().toIso8601String(),
             });
+        expect(outcome.created, hasLength(1));
+        expect(outcome.created.single.type, 'guestbook.GuestbookEntry');
         await writer.sync(admit: true);
         await reader.sync(admit: false);
         final rows = await reader.query('entriesByAuthor', {'author': 'harness'});
         expect(rows, hasLength(1));
+        expect(rows.first['id'], outcome.created.single.id);
         expect(
             (rows.first['data'] as Map)['message'], 'ephemeral fixture green');
         stdout.writeln(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.37.0",
+  "version": "0.38.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/codegen_dart_client.ts

@@ -142,7 +142,29 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const gateDoc = gate !== undefined
       ? `  /// GATED: needs an \`actor\` (the \`${gate.relation}\` relation) — throws MissingOfferAuthority otherwise.`
       : "";
-    if (stamps.length > 0) {
+    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.
+      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.`] : []),
+        ...(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.`,

package/src/codegen_ts.ts

@@ -400,7 +400,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  /** THE ONE ENCODER offer (the single v2-envelope codec lives in @githolon/client \`encodeIntentOfferBytes\`):`,
     `   *  hand the holon a PLANNED directive + the verified \`actor\`; the holon encodes + offers. The generated`,
     `   *  client calls THIS, never building offer bytes itself — so there is exactly ONE copy of the wire format. */`,
-    `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string }): Promise<string>;`,
+    `  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>;`,
     `  query(queryId: string, params?: Record<string, unknown>): Promise<unknown>;`,
@@ -753,6 +753,22 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         continue;
       }
       const offerPayload = stamps.length ? `stampNow(payload, ${JSON.stringify(stamps)})` : `payload`;
+      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 (payload: ${payloadName}): Promise<{ head: string; id: string }> => {`,
+          ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
+          `      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 (gateGuard) {
         // GATED directive: a block body that throws MissingOfferAuthority when no actor is bound — an