@githolon/dsl 0.70.1 → 0.71.0

package/dart/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.47.0
+
+- **Fix: `NomosBridge.createWorkspace` hardcoded `domain: "workspaces"`** in the underlying signed offer —
+  a tenant birthing through their OWN platform's custom law (e.g. a `birthEstateWorkspace` directive under a
+  `co2_platform` domain) was refused, because the sealed intent always claimed `domain: "workspaces"`
+  regardless of which law actually declares the requested `directiveId`. Added a `domain` parameter
+  (default `"workspaces"`, fully back-compatible) — call
+  `bridge.createWorkspace(domain: 'co2_platform', directiveId: 'birthEstateWorkspace', domainHash: ..., ...)`
+  to birth through a custom platform law. **This release was overdue**: the fix landed in `nomos_flutter`
+  0.52.2's bundled JS runtime, but this Dart-level API surface lives in `nomos_client` and was never
+  republished alongside it — a real release-process gap, not a client-side workaround. Requires
+  `nomos_flutter >= 0.52.2` to match the bundled runtime behavior.
+
 ## 0.46.0
 
 - Custody lifecycle on `NomosBridge`/`NomosSession`: `connect(..., onCustodyBreak: CustodyBreakPolicy)`,

package/dart/lib/src/webview_bridge.dart

@@ -1169,10 +1169,18 @@ class NomosBridge {
       }));
 
   /// MAKE A WORKSPACE — the one-call tenant path. A child workspace under a platform/[parent] is a SIGNED
-  /// control-plane offer; the holon seals `createWorkspace` (or [directiveId] `birthChild`) with the
-  /// requester's device key ([authorSecret], as [actor], e.g. `user:<uid>`) and relays it to the parent's
-  /// gateway. Returns the worker verdict (`{ok, status, body}`). The tenant move is one line:
+  /// control-plane offer; the holon seals `createWorkspace` (or [directiveId] `birthChild`, or ANY
+  /// tenant-defined `.births()` directive — see [domain]) with the requester's device key ([authorSecret],
+  /// as [actor], e.g. `user:<uid>`) and relays it to the parent's gateway. Returns the worker verdict
+  /// (`{ok, status, body}`). The tenant move is one line:
   /// `await bridge.createWorkspace(name: 'foo', parent: 'my-platform', actor: 'user:$uid', authorSecret: key)`.
+  ///
+  /// [domain] defaults to `'workspaces'` (the generic root-style governance law every platform's
+  /// createWorkspace/birthChild rides). To birth through the PARENT'S OWN custom platform law instead (e.g.
+  /// a tenant `birthEstateWorkspace` under a `co2_platform` domain), pass that domain's key + [domainHash]:
+  /// `bridge.createWorkspace(domain: 'co2_platform', directiveId: 'birthEstateWorkspace', domainHash: ...)`.
+  /// The kernel looks up `(domain, directiveId)` in the ACTIVE installed law — [domain] must name the law
+  /// that actually declares [directiveId], never assume `'workspaces'`.
   Future<Map<String, Object?>> createWorkspace({
     required String parent,
     required String actor,
@@ -1180,6 +1188,7 @@ class NomosBridge {
     String? name,
     Object? payload,
     String directiveId = 'createWorkspace',
+    String domain = 'workspaces',
     String? domainHash,
     String? authToken,
   }) async {
@@ -1192,6 +1201,7 @@ class NomosBridge {
       if (name != null) 'name': name,
       if (payload != null) 'payload': payload,
       'directiveId': directiveId,
+      'domain': domain,
       if (domainHash != null) 'domainHash': domainHash,
       if (authToken != null) 'authToken': authToken,
     }));

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

package/dart_types/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.2.0
+
+- `NomosPrincipal` / `NomosDeviceSecret` — branded identity types for the generated cross-workspace birth
+  methods (`.births()` directives). `actor`/`authorSecret` were previously bare, adjacent, same-shaped
+  strings — a transposition footgun with no compiler check. `NomosPrincipal.user(uid)`/`.parse('user:<uid>')`
+  and the opaque `NomosDeviceSecret` (redacts in `toString()`) make swapping them a type error. Purely
+  additive.
+
 ## 0.1.4
 
 - Custody-lifecycle types: `NomosCustodyBreak`, `NomosCustodyStatus`, `NomosCustodyEvent`,

package/dart_types/lib/nomos_types.dart

@@ -33,6 +33,9 @@ export 'src/errors.dart';
 export 'src/foreign_ref.dart';
 export 'src/activity.dart';
 export 'src/nomos_ref.dart';
+// Branded identity wrappers (NomosPrincipal / NomosDeviceSecret) for the generated cross-workspace
+// birth methods — actor/authorSecret are distinct types, so a transposition is a compile error.
+export 'src/principal.dart';
 // The CUSTODY-LIFECYCLE types (rebirth_and_custody_lifecycle.md): NomosCustodyBreak / NomosCustodyStatus /
 // CustodyBreakPolicy — custody incompatibility as a first-class, typed, app-decidable event. Pure data.
 export 'src/custody.dart';

package/dart_types/lib/src/principal.dart

@@ -0,0 +1,56 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/// BRANDED IDENTITY TYPES for the generated cross-workspace birth methods.
+///
+/// A `.births()` directive's generated wrapper takes an `actor` (WHO births) and an optional
+/// `authorSecret` (the signing key). Both were previously bare strings — two adjacent same-shaped
+/// params that a caller can transpose with NO compiler error and a silent runtime failure (the same
+/// bug class as a raw `domain`/`directiveId` swap). These wrappers make the transposition a type
+/// error: `NomosPrincipal` and `NomosDeviceSecret` are distinct types, so passing one where the other
+/// belongs won't compile. The generated method unwraps `.wire` to call the (unchanged) runtime
+/// primitive `NomosBridge.createWorkspace(actor: String, authorSecret: String?, …)`.
+
+/// A verified principal identity (`user:<uid>` on the wire). Construct with [NomosPrincipal.user]
+/// from a bare uid, or [NomosPrincipal.parse] from a `user:<uid>` wire string.
+class NomosPrincipal {
+  /// The bare uid (no `user:` prefix).
+  final String uid;
+  const NomosPrincipal._(this.uid);
+
+  /// From a bare uid (e.g. an auth-provider user id) — the common case.
+  factory NomosPrincipal.user(String uid) => NomosPrincipal._(uid);
+
+  /// From a `user:<uid>` wire string — throws [ArgumentError] on any other shape.
+  factory NomosPrincipal.parse(String wire) {
+    if (!wire.startsWith('user:')) {
+      throw ArgumentError('NomosPrincipal.parse: expected "user:<uid>", got "$wire"');
+    }
+    return NomosPrincipal._(wire.substring(5));
+  }
+
+  /// The wire form the kernel seals as the captured principal: `user:<uid>`.
+  String get wire => 'user:$uid';
+
+  @override
+  bool operator ==(Object other) => other is NomosPrincipal && other.uid == uid;
+  @override
+  int get hashCode => uid.hashCode;
+  @override
+  String toString() => wire;
+}
+
+/// A device signing secret (base64). A distinct type from [NomosPrincipal] so it can't be swapped
+/// with `actor`; its [toString] NEVER leaks the secret (redacted), so it is safe in logs/errors.
+class NomosDeviceSecret {
+  final String _base64;
+  const NomosDeviceSecret(this._base64);
+
+  /// The base64 wire form handed to the (unchanged) runtime primitive.
+  String get wire => _base64;
+
+  @override
+  String toString() => 'NomosDeviceSecret(***)';
+}

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

package/package.json

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

@@ -184,9 +184,14 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   const methods: string[] = [];
 
   // ── directives → typed offer ──
-  const dirs = (mod.directives as AnyDirective[]).filter(
+  // A `.births()` directive (birthsChild === true) is NOT a same-workspace write — it is a signed
+  // cross-workspace governance offer to a PARENT. It gets a typed `bridge.createWorkspace(...)` wrapper
+  // (below), NOT an `offerOutcome`; excluded here so a frontend dev can never call it as a local write.
+  const allDirs = (mod.directives as AnyDirective[]).filter(
     (d) => d && typeof d.id === "string" && typeof (d as { payloadSchema?: unknown }).payloadSchema === "object",
   );
+  const birthDirs = allDirs.filter((d) => (d as { birthsChild?: boolean }).birthsChild === true);
+  const dirs = allDirs.filter((d) => (d as { birthsChild?: boolean }).birthsChild !== true);
   for (const d of dirs) {
     const payloadClass = `${cap(d.id)}Payload`;
     const stamps = autoStampFields((d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema);
@@ -268,6 +273,43 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     }
   }
 
+  // ── `.births()` directives → typed CROSS-WORKSPACE birth (bridge.createWorkspace) ──
+  // Each births a CHILD WORKSPACE under `parent` via a signed governance offer routed by the PARENT'S
+  // law (POST /v2/workspaces/<parent>/<directiveId>) — never a same-workspace write. The declaring
+  // domain's key + directiveId + baked domainHash are all bound at codegen time, so a frontend dev
+  // never hand-writes the four raw strings this replaces (the co2 production bug).
+  for (const d of birthDirs) {
+    const payloadClass = `${cap(d.id)}Payload`;
+    const method = safeMethod(d.id);
+    methods.push(
+      `  /// Births a CHILD WORKSPACE named by \`${payloadClass}\` under [parent], via a SIGNED cross-workspace`,
+      `  /// governance offer to the parent's \`${domain}/${d.id}\` law (POST /v2/workspaces/<parent>/${d.id}) —`,
+      `  /// NOT a same-workspace write, which is why it takes [parent]/[actor] (the requesting principal, e.g.`,
+      `  /// \`user:<uid>\`) unlike the other generated methods. The declaring domain, directiveId, and law hash`,
+      `  /// are baked in. Returns the parent gateway's verdict; [authorSecret] defaults to the bridge's device key.`,
+      `  /// [actor] is a [NomosPrincipal] and [authorSecret] a [NomosDeviceSecret] — distinct types so the two`,
+      `  /// can never be transposed (a bare-string swap would silently misfire).`,
+      `  Future<Map<String, Object?>> ${method}({`,
+      `    required String parent,`,
+      `    required NomosPrincipal actor,`,
+      `    NomosDeviceSecret? authorSecret,`,
+      `    required ${payloadClass} payload,`,
+      `    String? authToken,`,
+      `  }) =>`,
+      `      bridge.createWorkspace(`,
+      `        domain: ${dartStr(domain)},`,
+      `        directiveId: ${dartStr(d.id)},`,
+      `        domainHash: domainHash,`,
+      `        parent: parent,`,
+      `        actor: actor.wire,`,
+      `        authorSecret: authorSecret?.wire,`,
+      `        payload: payload.toPayloadJson(),`,
+      `        authToken: authToken,`,
+      `      );`,
+      ``,
+    );
+  }
+
   // ── declared queries → one-shot + reactive ──
   for (const q of (mod.queries ?? []) as QueryDecl[]) {
     const model = readModelClassName(q.returns);

package/src/codegen_ts.ts

@@ -787,6 +787,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   );
   const encPresent = encMap !== null;
   const encConst = encryptionConstName(opts.packageName);
+  // A package declaring ≥1 `.births()` directive emits the branded identity wrappers (below) its typed
+  // birth methods take for `actor`/`authorSecret`. Births-free packages emit nothing (byte-identical).
+  const hasBirths = modules.some((m) =>
+    (m.directives as Directive<unknown>[]).some((d) => (d as { birthsChild?: boolean })?.birthsChild === true),
+  );
   // ACTIVITY FEED (architecture/activity_descriptors.md): the package's declared `.activity(...)` descriptors.
   // Empty ⇒ NOTHING activity-related emits (byte-identical to a pre-activity compile).
   const activityEntries = collectActivityDescriptors(modules);
@@ -950,9 +955,17 @@ 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; returnCreated?: boolean }): Promise<string>;`,
+    `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean }): Promise<string | { head: string; created?: { type: string; id: string }[]; workspace?: string }>;`,
     `  /** Opaque-bytes offer — retained for carriers that already hold an encoded envelope (back-compat). */`,
     `  offer(intentBytes: string | Uint8Array): Promise<string>;`,
+    ...(hasBirths
+      ? [
+          `  /** BIRTH A CHILD WORKSPACE (a signed CROSS-WORKSPACE governance offer to \`parent\`) — OPTIONAL:`,
+          `   *  @githolon/client's connect() attaches it. The generated \`.births()\` methods call this, binding`,
+          `   *  the declaring domain/directiveId/law hash so a frontend dev never hand-writes those raw strings. */`,
+          `  createWorkspace?(opts: { domain: string; directiveId: string; domainHash?: string; parent: string; actor: string; authorSecret?: string; payload?: unknown; name?: string; authToken?: string }): Promise<{ ok?: boolean; status?: number; body?: unknown }>;`,
+        ]
+      : []),
     `  /** The workspace this holon is bound to — the \`workspace\` of every [NomosRef] this client composes. */`,
     `  workspace: string;`,
     ...(encPresent
@@ -1046,6 +1059,25 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     ``,
   );
 
+  // BRANDED IDENTITY WRAPPERS for the typed cross-workspace birth methods: `actor` (NomosPrincipal) and
+  // `authorSecret` (NomosDeviceSecret) are distinct branded strings, so a caller can't transpose the two
+  // (a bare-string swap would compile and silently misfire). Emitted iff the package declares `.births()`.
+  if (hasBirths) {
+    out.push(
+      `/** A verified principal identity (\`user:<uid>\` on the wire) — construct with [nomosPrincipal]. A distinct`,
+      ` *  branded type from [NomosDeviceSecret] so the two birth-method params can never be transposed. */`,
+      `export type NomosPrincipal = string & { readonly __nomosPrincipal: unique symbol };`,
+      `/** A device signing secret (base64) — construct with [nomosDeviceSecret]. Distinct from [NomosPrincipal]. */`,
+      `export type NomosDeviceSecret = string & { readonly __nomosDeviceSecret: unique symbol };`,
+      `/** Brand a principal: a bare uid (\`ada\`) or a wire string (\`user:ada\`) → \`user:ada\`. */`,
+      `export const nomosPrincipal = (uidOrWire: string): NomosPrincipal =>`,
+      `  (uidOrWire.startsWith("user:") ? uidOrWire : \`user:\${uidOrWire}\`) as NomosPrincipal;`,
+      `/** Brand a device signing secret (base64). */`,
+      `export const nomosDeviceSecret = (base64: string): NomosDeviceSecret => base64 as NomosDeviceSecret;`,
+      ``,
+    );
+  }
+
   if (encPresent) {
     out.push(
       `// ── E2E SEALING (the sealing client) — baked map + KeyStore + seal/read helpers ──`,
@@ -1723,6 +1755,27 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed, lazyReg, d.id)};`,
         ``,
       );
+      // A `.births()` directive is NOT a same-workspace write — it is a signed CROSS-WORKSPACE governance
+      // offer to a PARENT. It gets a typed `holon.createWorkspace(...)` wrapper (declaring domain +
+      // directiveId + baked domainHash bound at codegen time), NOT an `offerDirective`, so a frontend dev
+      // never hand-writes the four raw strings this replaces (the co2 production bug).
+      if ((d as { birthsChild?: boolean }).birthsChild === true) {
+        const birthPayload = stamps.length ? `stampNow(payload, ${JSON.stringify(stamps)})` : "payload";
+        const gateBirthDoc = gate ? ` GATED: needs \`actor\` (\`${gate.relation}\`).` : "";
+        methods.push(
+          `    /** Births a CHILD WORKSPACE (named by \`${payloadName}\`) under \`parent\`, via a SIGNED cross-workspace`,
+          `     *  governance offer to the parent's \`${domain}/${d.id}\` law (POST /v2/workspaces/<parent>/${d.id}) — NOT a`,
+          `     *  same-workspace write, hence \`parent\`/\`actor\` (the requesting principal, e.g. \`user:<uid>\`) unlike the`,
+          `     *  other methods. Declaring domain, directiveId, and law hash are baked in; returns the parent gateway's`,
+          `     *  verdict. \`authorSecret\` defaults to the holon's device key.${gateBirthDoc} */`,
+          `    ${d.id}: (opts: { parent: string; actor: NomosPrincipal; authorSecret?: NomosDeviceSecret; payload: ${payloadName}; authToken?: string }): Promise<{ ok?: boolean; status?: number; body?: unknown }> => {`,
+          ...(gateGuard ? [`      if (!opts.actor || !opts.actor.trim()) throw new MissingOfferAuthority(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${JSON.stringify(gate!.relation)});`] : []),
+          `      const _payload = opts.payload;`,
+          `      return (holon.createWorkspace ?? (() => { throw new Error("this holon predates cross-workspace births — upgrade @githolon/client"); }))({ domain: ${JSON.stringify(domain)}, directiveId: ${JSON.stringify(d.id)}, domainHash, parent: opts.parent, actor: opts.actor, authorSecret: opts.authorSecret, payload: ${birthPayload.replace("payload", "_payload")}, authToken: opts.authToken });`,
+          `    },`,
+        );
+        continue;
+      }
       // 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.

package/src/compile_package_main.ts

@@ -433,6 +433,9 @@ const DART_SUPPORT_CORE_SRC = [
   "foreign_ref.dart",
   "activity.dart",
   "nomos_ref.dart",
+  // Branded identity wrappers (NomosPrincipal/NomosDeviceSecret) — the generated cross-workspace birth
+  // methods type `actor`/`authorSecret` as these (not bare strings), so both must vendor. Pure data.
+  "principal.dart",
   // The custody-lifecycle types (NomosCustodyBreak/NomosCustodyStatus/CustodyBreakPolicy) — the generated
   // client + the vendored bridge reference them through the barrel, so they must vendor. Pure data.
   "custody.dart",
@@ -865,11 +868,15 @@ 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.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";
+/** Version constraints the scaffolded pubspecs pin — move together with the Dart packages' releases.
+ *  Caret on 0.x is EXACT-MINOR (`^0.45.0` = `<0.46.0`), so these must track the CURRENT release, not
+ *  just the floor generated code needs — a lagging pin forces tenants into dependency_overrides. */
+// 0.1.4: custody-lifecycle types (CustodyBreakPolicy et al).
+// 0.2.0: branded birth identities (NomosPrincipal/NomosDeviceSecret) — the generated cross-workspace
+//        `.births()` methods type actor/authorSecret as these, so a layered package needs nomos_types 0.2.0.
+const NOMOS_TYPES_DEP = "^0.2.0";
+// 0.46.0: custody lifecycle on NomosBridge/NomosSession (onCustodyBreak/custodyStatus/salvage lanes).
+const NOMOS_CLIENT_DEP = "^0.46.0";
 
 const isPubPackageName = (s: string): boolean => /^[a-z][a-z0-9_]*$/.test(s);