@githolon/dsl 0.81.0 → 0.83.0

package/dart/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.55.1
+
+- Add `deriveWorkspaceName(namespace, key)` — re-derive the workspace name a keyed birth
+  (`birth.keyed`) produced, so a born workspace is addressable from its key with zero persistence
+  (byte-identical to @githolon/dsl + @githolon/client; contract-tested vectors). Replaces hand-rolled
+  `<x>WorkspaceFor<Id>` helpers.
+- Expose `bridge.issueDelegationCert({signerSecret, grantorId, relation, subject, epoch, certChain})` —
+  issue a role-delegation cert (the `.delegatedRole()` lane) from the public client; deliver via
+  `acceptDelegatedRole`. Runner bundle rebuilt.
+
 ## 0.55.0
 
 - **Security: enrollSigner self-binds** (device can only enroll itself; cross-principal forgery closed

package/dart/lib/nomos_client.dart

@@ -31,6 +31,7 @@ library;
 export 'package:nomos_types/nomos_types.dart';
 // homeNameOf(subject) — the canonical home-workspace name (parity with @githolon/client + the law side).
 export 'src/home.dart';
+export 'src/workspace_name.dart';
 // THE WEBVIEW BRIDGE (app-binding boundary) — the async Dart runtime that drives the REAL githolon running
 // in a WebView, so the generated typed client never needs a `MemoryPersistence` fake.
 export 'src/webview_bridge.dart';

package/dart/lib/src/webview_bridge.dart

@@ -1827,6 +1827,33 @@ class NomosBridge {
           Map<String, Object?> args) async =>
       _asMap(await _call('attestationSign', {'args': args}));
 
+  /// Issue a ROLE-DELEGATION cert (the `.delegatedRole()` lane, kernel `delegationCertSign` op). A platform
+  /// signs — with its grantor secret `signerSecret` (base64) — a cert granting `relation` to `subject`,
+  /// carrying the lineage `certChain` up to K_root. Returns `{ certString }`; deliver it into the target
+  /// home via the tenant's `acceptDelegatedRole` directive (the one gate re-verifies it to K_root on every
+  /// lane). OURS = the op; operating the grantor secret + choosing who to grant is the TENANT.
+  ///   final res = await bridge.issueDelegationCert(signerSecret: sP, grantorId: 'co2-platform',
+  ///       relation: 'co2EstateCreator', subject: userSubject, epoch: 1, certChain: [rootLink]);
+  ///   final certString = res['certString'] as String;
+  Future<Map<String, Object?>> issueDelegationCert({
+    required String signerSecret,
+    required String grantorId,
+    required String relation,
+    required String subject,
+    int epoch = 1,
+    List<Object?>? certChain,
+  }) async =>
+      _asMap(await _call('issueDelegationCert', {
+        'args': {
+          'signerSecret': signerSecret,
+          'grantorId': grantorId,
+          'relation': relation,
+          'subject': subject,
+          'epoch': epoch,
+          if (certChain != null) 'certChain': certChain,
+        },
+      }));
+
   /// A declared query's rows from the local projection. `keys` (E2E sealing) injects the reader's held
   /// scope keys so encrypted fields AEAD-open in-wasm; absent ⇒ they stay opaque envelopes (today's
   /// behavior). `principal` stamps the private-read gate (defaults to the connection's bound principal).

package/dart/lib/src/workspace_name.dart

@@ -0,0 +1,24 @@
+import 'dart:convert';
+
+import 'package:crypto/crypto.dart';
+
+/// The unit separator (0x1F) that disambiguates `(namespace, key)` in the name hash input.
+final String workspaceNameSep = String.fromCharCode(31);
+
+/// Re-derive the workspace name a keyed birth produced, so you can ADDRESS a born workspace from a key you
+/// own — with zero persistence, on any device, any time.
+///
+/// A workspace exists to be used, and using it means finding it again. When a law births a child with
+/// `birth.keyed({ key, namespace })` (the `@githolon/dsl` verb), the workspace name is
+/// `<namespace>-<sha256(namespace + SEP + key)[:40]>`. This function computes the IDENTICAL name — it is the
+/// byte-for-byte mirror of `@githolon/dsl`'s `workspaceNameForKey` and `@githolon/client`'s
+/// `deriveWorkspaceName`, contract-tested against shared vectors. So instead of persisting a minted name or
+/// hand-rolling an `estateWorkspaceForEstateId` helper, you write:
+///
+/// ```dart
+/// final ws = deriveWorkspaceName('estate', estateId); // open / sync / mount it
+/// ```
+String deriveWorkspaceName(String namespace, String key) {
+  final digest = sha256.convert(utf8.encode('$namespace$workspaceNameSep$key')).toString();
+  return '$namespace-${digest.substring(0, 40)}';
+}

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

package/dart/test/workspace_name_test.dart

@@ -0,0 +1,24 @@
+import 'package:nomos_client/src/workspace_name.dart';
+import 'package:test/test.dart';
+
+// CONTRACT VECTORS — shared byte-for-byte with @githolon/dsl `workspaceNameForKey` and @githolon/client
+// `deriveWorkspaceName`. Generated with real sha256 (node crypto). If any of the three derivations drifts,
+// a workspace born by one peer becomes unaddressable by another — so these must never change silently.
+void main() {
+  group('deriveWorkspaceName — the shared birth-name derivation', () {
+    test('matches the cross-language reference vectors', () {
+      expect(deriveWorkspaceName('estate', 'estate-abc123'),
+          'estate-83662e729ba18cd04bde52c7a8d854594833d70e');
+      expect(deriveWorkspaceName('home', 'user:ada'),
+          'home-561af44c94b5b80824f1a9e8cfa1095105f3cb34');
+      expect(deriveWorkspaceName('catalogue', 'cat-42'),
+          'catalogue-f50bf3b9732dc36961b05b8e6503d96df5f3e88e');
+    });
+
+    test('is deterministic and namespaced (no cross-namespace collision)', () {
+      expect(deriveWorkspaceName('estate', 'z'), deriveWorkspaceName('estate', 'z'));
+      expect(deriveWorkspaceName('estate', 'z'), isNot(deriveWorkspaceName('catalogue', 'z')));
+      expect(deriveWorkspaceName('estate', 'z').startsWith('estate-'), isTrue);
+    });
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.81.0",
+  "version": "0.83.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/births.ts

@@ -80,14 +80,35 @@ export function birth(recipe: BirthRecipe): void {
 }
 
 // `nomos.sha256` — the trustless pure hash bound in the sealed engine (like `nomos.mint`), used to derive a
-// singleton child's DETERMINISTIC name in-law so every peer re-derives the same name.
+// keyed child's DETERMINISTIC, ADDRESSABLE name in-law so every peer — and every CLIENT — re-derives the
+// same name from the same key.
 declare const nomos: { sha256(input: string): string };
 
+/**
+ * THE ONE WORKSPACE-NAME DERIVATION — shared verbatim by the law (this engine), the Dart client, and the TS
+ * client, so a workspace born under a key is ADDRESSABLE from that key on every peer with zero persistence.
+ *
+ *   name = `<namespace>-<sha256(namespace + "" + key)[:40]>`
+ *
+ * A workspace exists to be USED, and using it means finding it again — so a birth's name is NEVER opaque or
+ * minted-and-forgotten; it is a pure function of a key the caller already owns (a business id, an owner uid).
+ * The `` (unit separator) makes `(ns,key)` unambiguous. `nomos.sha256` returns lowercase hex.
+ *
+ * The client mirror is `deriveWorkspaceName(namespace, key)` in `nomos_client` (Dart) and `@githolon/client`
+ * (TS) — byte-identical output is contract-tested against {@link WORKSPACE_NAME_VECTORS}.
+ */
+export const WORKSPACE_NAME_SEP = "\u001f"; // unit separator disambiguates (namespace,key)
+export function workspaceNameForKey(namespace: string, key: string): string {
+  return namespace + "-" + nomos.sha256(String(namespace) + WORKSPACE_NAME_SEP + String(key)).slice(0, 40);
+}
+
 /** A genesis chain, or a builder that receives the resolved child workspace name (so a seed step can embed
  *  it — e.g. `seedEstate` needs to write its own `estateName`). Passing a builder is the common case. */
-export type GenesisChainOrBuilder = unknown | ((childWorkspace: string) => unknown);
+// An array of genesis steps, OR a builder that receives the resolved child name. Typed as `unknown[]`
+// (not `unknown`) so the union doesn't collapse — the builder's `childWorkspace` param infers as `string`.
+export type GenesisChainOrBuilder = readonly unknown[] | ((childWorkspace: string) => readonly unknown[]);
 function resolveChain(child: string, c: GenesisChainOrBuilder): unknown {
-  return typeof c === "function" ? (c as (w: string) => unknown)(child) : c;
+  return typeof c === "function" ? c(child) : c;
 }
 
 /** A `create()`d aggregate reference — the birth's audit record, whose MINTED (captured, replay-stable) id
@@ -97,30 +118,56 @@ interface MintedRef {
 }
 
 /**
- * THE BIRTH CARDINALITY DECISION — stated at the call site so an agent models it right by default.
- *
- * A born child's workspace name is its IDENTITY. The wrong instinct (births are deterministic, so derive the
- * name from a stable field like the owner) silently caps the parent at ONE child per owner. So the choice is
- * explicit and NAMED, exactly like a merge driver states convergence:
- *
- *   • `birth.instance(...)` — MANY children per parent. The child's workspace id is MINTED from `from` (an
- *     aggregate you `create()` for the birth) — its id already rides the committed intent (captured), so the
- *     child name reproduces byte-identically at replay. Nomos mints the identity; you never hand-roll it.
+ * `birth.keyed(...)` — THE way to birth a child workspace. A workspace exists to be USED, and using it means
+ * FINDING IT AGAIN, so its name is ALWAYS derived from a `key` the caller owns (a business id, an owner uid)
+ * via {@link workspaceNameForKey}. The client re-derives the SAME name with `deriveWorkspaceName(namespace,
+ * key)` — so the born workspace is addressable from the key alone, with zero persistence. Same key ⇒ same
+ * workspace (re-birth is idempotent). This is the only birth verb you need.
  *
- *   • `birth.singleton(...)` — EXACTLY ONE child per `keyedBy`. The name is DERIVED deterministically in-law,
- *     so a re-birth is idempotent (same name → the child self-validates to the same identity). This is the
- *     RIGHT tool for a home (one home per user), and the ONLY case where a name-from-a-field is correct.
- *
- * Raw {@link birth} stays the low-level escape hatch for an externally-determined name.
+ * ```ts
+ * export const birthEstate = directive("birthEstate")
+ *   .creates(EstateBirth)
+ *   .payload(z.object({ estateId: z.string(), owner: z.string(), frameworkHash: z.string(), lawHash: z.string(), bornAt: z.string() }))
+ *   .plan((p) => {
+ *     birth.keyed({ key: p.estateId, namespace: "estate", genesisChain: (ws) => [
+ *       { domain: "bootstrap", directiveId: "installDomain", actor: p.owner, payload: { domainHash: p.frameworkHash }, domainHash: p.frameworkHash, domainPackageB64: "" },
+ *       { domain: "nomos",     directiveId: "installDomain", actor: p.owner, payload: { domainHash: p.lawHash },       domainHash: p.lawHash,       domainPackageB64: "" },
+ *       { domain: "estate",    directiveId: "seedEstate", actor: p.owner, payload: { estateId: p.estateId, workspaceName: ws, bornAt: p.bornAt } },
+ *     ] });
+ *     return [];
+ *   })
+ *   .births().requires("estateCreator");
+ * // app (Dart / TS): final ws = client.deriveWorkspaceName('estate', estateId); // open it, any time, any device
+ * ```
+ */
+export const birthKeyed = ({
+  key,
+  namespace,
+  genesisChain,
+}: {
+  /** The id you already own that this workspace is FOR (an estateId, an owner uid). The client addresses the
+   *  born workspace by re-deriving its name from this same key — so pick a key the client will have in hand. */
+  key: string;
+  /** The workspace-name namespace (e.g. `"estate"` → `estate-<hash>`). Groups a domain's children. */
+  namespace: string;
+  genesisChain: GenesisChainOrBuilder;
+}): string => {
+  const child = workspaceNameForKey(namespace, String(key));
+  footprint.push({ workspace: child, genesisChain: resolveChain(child, genesisChain) });
+  return child;
+};
+
+/**
+ * @deprecated Use {@link birthKeyed}. `birth.instance` mints a name the caller THROWS AWAY — so the born
+ * workspace can never be found again except via the birth result. A workspace is a custodial thing you birth
+ * in order to use; there is no workspace you make and never address later. Birth by a key you own instead.
  */
 export const birthInstance = ({
   from,
   prefix = "",
   genesisChain,
 }: {
-  /** The `create()`d audit record whose minted, captured id names the child (replay-stable uniqueness). */
   from: MintedRef;
-  /** Optional human-legible workspace-name prefix (e.g. `"estate-"`). */
   prefix?: string;
   genesisChain: GenesisChainOrBuilder;
 }): string => {
@@ -129,29 +176,34 @@ export const birthInstance = ({
   return child;
 };
 
+/**
+ * `birth.singleton(...)` — a keyed birth whose key is a NATURAL single key (one home per user: key = owner).
+ * Sugar over {@link birthKeyed}: `birth.singleton({ keyedBy: owner, namespace: "home" })`. Same addressing
+ * story — the client re-derives with `deriveWorkspaceName(namespace, keyedBy)`.
+ */
 export const birthSingleton = ({
   keyedBy,
   namespace,
   genesisChain,
 }: {
-  /** The key the child is a singleton OF (e.g. the owner). One child per distinct key; re-birth idempotent. */
+  /** The natural single key (e.g. the owner). One workspace per key; re-birth idempotent. */
   keyedBy: string | readonly string[];
-  /** Optional name namespace/prefix (e.g. `"home"` → `home-<hash>`). */
-  namespace?: string;
+  /** The workspace-name namespace (e.g. `"home"`). */
+  namespace: string;
   genesisChain: GenesisChainOrBuilder;
 }): string => {
-  const parts = (Array.isArray(keyedBy) ? keyedBy : [keyedBy]).map(String);
-  const child = (namespace ? namespace + "-" : "") + nomos.sha256(JSON.stringify(parts)).slice(0, 40);
-  footprint.push({ workspace: child, genesisChain: resolveChain(child, genesisChain) });
-  return child;
+  const key = (Array.isArray(keyedBy) ? keyedBy : [keyedBy]).map(String).join(WORKSPACE_NAME_SEP);
+  return birthKeyed({ key, namespace, genesisChain });
 };
 
-// Function/namespace declaration merging: attach the two cardinality verbs to `birth` so the call site reads
-// `birth.instance(...)` / `birth.singleton(...)` — with full types AND the runtime assignment in one place.
+// Function/namespace declaration merging: attach the birth verbs to `birth` so the call site reads
+// `birth.keyed(...)` — with full types AND the runtime assignment in one place.
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace birth {
-  export const instance = birthInstance;
+  export const keyed = birthKeyed;
   export const singleton = birthSingleton;
+  /** @deprecated Use `birth.keyed` — see {@link birthInstance}. */
+  export const instance = birthInstance;
 }
 
 /**

package/src/index.ts

@@ -198,7 +198,16 @@ export {
 // child's genesis recipe via `birth(recipe)` (reuse `buildGenesisChain`); it rides the committed intent as a
 // declared output, and the kernel — reading the `.births` declaration off the law manifest (the
 // `nomosBirthGate` era key, never domain state) — spawns + self-validates the child after the offer admits.
-export { birth, type BirthRecipe } from "./births.js";
+export {
+  birth,
+  workspaceNameForKey,
+  WORKSPACE_NAME_SEP,
+  birthKeyed,
+  birthSingleton,
+  birthInstance,
+  type BirthRecipe,
+  type GenesisChainOrBuilder,
+} from "./births.js";
 // THE PEER-SOVEREIGN ROOT-OF-TRUST (the BirthAttestation cert chain): a home/child law exports
 // `requireParentAttestedBirth` to declare it requires a parent-attested-birth cert chain (the
 // `nomosParentAttestedBirth` era key); the kernel verify doors then verify the travelling chain to K_root.