@githolon/dsl 0.98.3 → 0.100.0

package/dart/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.62.0
+
+- Generated business clients expose one `birth(payload)` method. The bound session supplies its verified
+  principal from the authentication token, and Nomos owns the identity, provenance, persistence, and
+  recovery ceremony beneath the business call.
+
 ## 0.61.3
 
 - cloudBound seeds the KEYLESS enroll-once delegation (mintKeylessDelegation) so a keyless private home

package/dart/lib/src/webview_bridge.dart

@@ -829,6 +829,9 @@ class NomosBridge {
   // caches the per-workspace [NomosSession] handle so `bridge.session(ws)` is stable + cheap.
   final Set<String> _sessionNames = {};
   final Map<String, NomosSession> _sessionViews = {};
+  // The gate-bound identity retained from each session's auth token. Generated clients consume this so
+  // application code never has to thread an actor into ordinary business methods.
+  final Map<String, String> _sessionPrincipals = {};
   // [acquireSession]'s per-workspace single-flight: workspace → the in-flight open every concurrent
   // acquirer joins (removed when it completes; a live session then hits the fast path instead).
   final Map<String, Future<NomosSession>> _acquiring = {};
@@ -1079,6 +1082,21 @@ class NomosBridge {
           .map((e) => (e as Map).cast<String, dynamic>())
           .toList();
 
+  String? _principalFromToken(String? token) {
+    if (token == null || token.isEmpty) return null;
+    try {
+      final parts = token.split('.');
+      if (parts.length < 2) return null;
+      final payload = jsonDecode(utf8.decode(base64Url.decode(base64Url.normalize(parts[1]))));
+      final sub = payload is Map ? payload['sub'] : null;
+      if (sub is! String || sub.trim().isEmpty) return null;
+      final value = sub.trim();
+      return value.contains(':') ? value : 'user:$value';
+    } catch (_) {
+      return null;
+    }
+  }
+
   // ── the runtime-aware surface (the boundary the generated Dart client wraps) ──
 
   /// THE PRIMARY MULTI-WORKSPACE ENTRY. Return a [NomosSession] handle pinned to [workspace] — the object a
@@ -1103,6 +1121,16 @@ class NomosBridge {
   List<String> get connectedSessions =>
       List.unmodifiable(_eventPlane._sessionNames);
 
+  /// The identity already proved by this bound session. Null on an unauthenticated/local-only session, or
+  /// on a multi-session plane whose identity would be ambiguous. Generated business methods use this by
+  /// default; an explicit client actor remains an advanced override.
+  String? get principal {
+    final plane = _eventPlane;
+    final scoped = _sessionName;
+    if (scoped != null) return plane._sessionPrincipals[scoped];
+    return plane._sessionPrincipals.length == 1 ? plane._sessionPrincipals.values.first : null;
+  }
+
   /// ENUMERATE THE LOCAL PLANE — every workspace on this device + its lifecycle STATE and sync posture:
   /// `[{ session, workspace, state, mounted, parked, syncPosture }]`. The explicit **`state`** (co2 DX ask)
   /// is the field to branch on — it removes the "listed but `session(ws)` fails on first op" footgun:
@@ -1173,6 +1201,8 @@ class NomosBridge {
       if (onCustodyBreak != null) 'onCustodyBreak': onCustodyBreak.wire,
     }));
     _eventPlane._sessionNames.add(ws); // the open succeeded — the session is real now
+    final boundPrincipal = _principalFromToken(authToken);
+    if (boundPrincipal != null) _eventPlane._sessionPrincipals[ws] = boundPrincipal;
     _eventPlane._lastRecovery = (r['recovery'] as Map?)?.cast<String, Object?>();
   }
 
@@ -1428,6 +1458,12 @@ class NomosBridge {
             .map((m) => (m['workspace'] ?? '').toString())
             .where((s) => s.isNotEmpty),
     ]..removeWhere((s) => s.isEmpty);
+    final birthPrincipal = actor ?? principal;
+    if (birthPrincipal != null && birthPrincipal.isNotEmpty) {
+      for (final born in bornNames) {
+        _eventPlane._sessionPrincipals[born] = birthPrincipal;
+      }
+    }
     // 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(

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

package/dart/test/webview_bridge_test.dart

@@ -452,6 +452,21 @@ void main() {
     expect((req['args'] as Map)['allowUnborn'], isTrue);
   });
 
+  test('a session retains the authenticated token subject as its default principal', () async {
+    await bridge.ready;
+    final payload = base64Url
+        .encode(utf8.encode(jsonEncode({'sub': 'ada'})))
+        .replaceAll('=', '');
+    await bridge.connect(
+      cloud: 'https://c',
+      workspace: 'authenticated',
+      authToken: 'header.$payload.signature',
+    );
+
+    expect(bridge.session('authenticated').principal, 'user:ada');
+    expect(bridge.principal, 'user:ada');
+  });
+
   test(
       'connect / query / queryById / count / sync / lawStatus all wrap the runner',
       () async {

package/package.json

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

@@ -3,6 +3,11 @@
 // wasm32-wasip1 artifact {kernel · projection · embedded
 // QuickJS engine}.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
 
+import type { z } from "zod";
+import type { AggregateHandle } from "./aggregate.js";
+import type { AggregateRef } from "./authoring.js";
+import type { Field } from "./fields.js";
+
 /**
  * THE BIRTH EFFECT — birth is an EXPLICIT, DECLARED kernel primitive (G3, the unix model).
  *
@@ -51,32 +56,71 @@ export function __drainBirths(): BirthRecipe[] {
  * chains carry no key, so they replay byte-green and the kernel does nothing). A plan may birth at most one
  * child per intent (one offer, one defined consequence — the unix model).
  *
- * TO BIRTH A LEAF CHILD RUNNING ITS OWN LAW (a home, an estate child) — copy `framework/home.ts`'s
- * `birthHome`. The recipe is just the two-layer law install + your own seed step; there is NO helper to
- * fabricate it and you do NOT need a new primitive (recursion is the law — a home births children exactly
- * as root births platforms). `buildGenesisChain` is the ONE builder for the PLATFORM shape (it adds the
- * `seedGenesis → grantAdmin → birthCloud` tail); a leaf just omits that tail:
+ * This is framework implementation plumbing. Application packages declare
+ * `birth(Aggregate, spec)` and never construct a recipe.
+ */
+/**
+ * A business thing that is important enough to have its own durable, sovereign life.
  *
- * ```ts
- * export const birthEstateChild = directive("birthEstateChild")
- *   .creates(EstateChild)
- *   .payload(z.object({ child: z.string(), owner: z.string(),
- *     frameworkHash: z.string(), lawHash: z.string(), bornAt: z.string() }))
- *   .plan((p) => {
- *     const actor = "user:" + p.owner;
- *     birth({ workspace: p.child, genesisChain: [
- *       { domain: "bootstrap", directiveId: "installDomain", actor, payload: { domainHash: p.frameworkHash }, domainHash: p.frameworkHash, domainPackageB64: "" },
- *       { domain: "nomos",     directiveId: "installDomain", actor, payload: { domainHash: p.lawHash },       domainHash: p.lawHash,       domainPackageB64: "" },
- *       { domain: "estate",    directiveId: "seedEstateChild", actor, payload: { owner: p.owner, bornAt: p.bornAt } },
- *     ] });
- *     return [];
- *   })
- *   .births()             // the kernel's run_birth_effect folds the recipe through the CHILD's own gate
- *   .requires("creator"); // grant the parent's owner #creator (self-bound) — the birth authority
- * ```
+ * This is the ONLY tenant-facing birth declaration. The composer lowers it to the framework's
+ * recipe/directive machinery; application code gets one generated `birth(payload)` method. Security,
+ * law selection, lineage, storage and recovery are deliberately absent from this shape.
  */
-export function birth(recipe: BirthRecipe): void {
-  footprint.push(recipe);
+export interface BusinessBirthDecl<
+  P extends Record<string, unknown> = Record<string, unknown>,
+  F extends Record<string, Field> = Record<string, Field>,
+> {
+  readonly __isBusinessBirth: true;
+  readonly aggregate: AggregateHandle<string, F>;
+  readonly payloadSchema: z.ZodObject<z.ZodRawShape>;
+  /** A stable business key the caller already knows (an estate reference, account number, etc.). */
+  readonly key: (payload: P) => string;
+  /** Author the born thing's initial business facts. Nomos supplies the durable identity and lifecycle. */
+  readonly plan: (root: AggregateRef<F>, payload: P) => unknown;
+  /** Optional business noun used only to make the durable address readable. Defaults to the aggregate id. */
+  readonly namespace?: string;
+}
+
+export interface BusinessBirthSpec<
+  P extends Record<string, unknown>,
+  F extends Record<string, Field>,
+> {
+  readonly payload: z.ZodType<P> & z.ZodObject<z.ZodRawShape>;
+  readonly key: (payload: P) => string;
+  readonly plan: (root: AggregateRef<F>, payload: P) => unknown;
+  readonly namespace?: string;
+}
+
+/** @internal Record an already-lowered child recipe during a framework directive plan. Application law
+ * declares `birth(Aggregate, spec)` and leaves the recipe, identity, and recovery machinery to Nomos. */
+export function birth(recipe: BirthRecipe): void;
+/** Declare that one business aggregate is given its own durable life. */
+export function birth<P extends Record<string, unknown>, F extends Record<string, Field>>(
+  aggregate: AggregateHandle<string, F>,
+  spec: BusinessBirthSpec<P, F>,
+): BusinessBirthDecl<P, F>;
+export function birth<P extends Record<string, unknown>, F extends Record<string, Field>>(
+  recipeOrAggregate: BirthRecipe | AggregateHandle<string, F>,
+  spec?: BusinessBirthSpec<P, F>,
+): void | BusinessBirthDecl<P, F> {
+  if (spec !== undefined) {
+    const aggregate = recipeOrAggregate as AggregateHandle<string, F>;
+    if (!aggregate || aggregate.__isAggregateHandle !== true) {
+      throw new Error("birth(Aggregate, spec): the first argument must be an aggregate handle");
+    }
+    if (!spec.payload || typeof (spec.payload as { safeParse?: unknown }).safeParse !== "function") {
+      throw new Error("birth(Aggregate, spec): spec.payload must be a z.object(...) schema");
+    }
+    return {
+      __isBusinessBirth: true,
+      aggregate,
+      payloadSchema: spec.payload,
+      key: spec.key,
+      plan: spec.plan,
+      ...(spec.namespace !== undefined ? { namespace: spec.namespace } : {}),
+    };
+  }
+  footprint.push(recipeOrAggregate as BirthRecipe);
 }
 
 // `nomos.sha256` — the trustless pure hash bound in the sealed engine (like `nomos.mint`), used to derive a
@@ -118,37 +162,20 @@ interface MintedRef {
 }
 
 /**
- * `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.
+ * @deprecated Tenant law should declare `birth(Aggregate, spec)`. This framework helper remains for the
+ * built-in framework laws that implement that declaration.
  *
- * ```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
- * ```
+ * Internal compatibility helper: derives a child address from a stable key. Application packages use
+ * `birth(Aggregate, spec)`; generated clients expose only `birth(businessFacts)`.
  */
 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. */
+  /** A stable id from which the framework can re-derive the durable address. */
   key: string;
-  /** The workspace-name namespace (e.g. `"estate"` → `estate-<hash>`). Groups a domain's children. */
+  /** Internal address namespace. */
   namespace: string;
   genesisChain: GenesisChainOrBuilder;
 }): string => {
@@ -177,6 +204,8 @@ export const birthInstance = ({
 };
 
 /**
+ * @deprecated Tenant law should declare `birth(Aggregate, spec)`. This is framework compatibility sugar.
+ *
  * `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)`.
@@ -200,7 +229,9 @@ export const birthSingleton = ({
 // `birth.keyed(...)` — with full types AND the runtime assignment in one place.
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace birth {
+  /** @deprecated Tenant law should use `birth(Aggregate, spec)`. Framework compatibility only. */
   export const keyed = birthKeyed;
+  /** @deprecated Tenant law should use `birth(Aggregate, spec)`. Framework compatibility only. */
   export const singleton = birthSingleton;
   /** @deprecated Use `birth.keyed` — see {@link birthInstance}. */
   export const instance = birthInstance;

package/src/build_package.ts

@@ -80,6 +80,7 @@ import { parentAttestedBirthMarker } from "./births.js";
 import { discoverUnsanctionedEnsures, sanctioningEnsureDirective } from "./secondary_ensure.js";
 import { assertIdOfLint } from "./idof_lint.js";
 import { assertSurfacedResolvers } from "./surfaced_lint.js";
+import { expandBusinessBirthExports } from "./business_birth.js";
 
 // ─────────────────────────────────────────────────────────────────────────────────
 // composeDomainModule — the named-keys `module(...)`
@@ -173,6 +174,7 @@ export interface DomainModuleSpec {
 export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   let merged: Mod = {};
   for (const m of spec.modules) merged = { ...merged, ...m };
+  merged = expandBusinessBirthExports(merged, spec.domain ?? spec.name);
   // `capability()` bundles expand into discoverable entries (the package plane's
   // merge point) — the quartet validation below then passes without re-exports.
   merged = expandCapabilityExports(merged);

package/src/business_birth.ts

@@ -0,0 +1,274 @@
+// NOMOS — one business birth at the tenant surface; compute-science mechanics lower here.
+
+import { z } from "zod";
+import { ensure } from "./authoring.js";
+import { directive, type Directive } from "./directive.js";
+import {
+  birth,
+  requireParentAttestedBirth,
+  workspaceNameForKey,
+  type BusinessBirthDecl,
+  type ParentAttestedBirthMarker,
+} from "./births.js";
+import { readFrameworkDeclared } from "./read.js";
+import { AuthProvider, authProvider, setAuthProvider } from "./framework/auth_provider_law.js";
+import {
+  BirthGrant,
+  BirthPolicy,
+  NomosBirthRecord,
+  birthGrantByPrincipal,
+  birthPolicy,
+  birthRecordsByPrincipal,
+} from "./birth_meter.js";
+import { nomosBirthRecordEnsure } from "./birth_meter_ensure.js";
+import { GENESIS_WARRANT_ID, GenesisWarrant, seedGenesis } from "./framework/genesis.js";
+import {
+  BIRTH_ATTESTATION_ID,
+  BirthAttestation,
+  birthAttestation,
+  seedBirthAttestation,
+} from "./framework/home.js";
+import { RelationTuple, relationTuplesByObject } from "./framework/relations.js";
+import {
+  SignerDelegation,
+  enrollDelegation,
+  enrollFirstDevice,
+  enrollSigner,
+  identityRelations,
+  signerDelegationByUser,
+} from "./framework/signing_identity.js";
+
+/** Private recipe selectors. The kernel resolves these against the parent's current installed law. */
+export const CURRENT_LAW_PREFIX = "nomos:current-law:";
+
+export interface BusinessBirthMetadata {
+  readonly aggregateId: string;
+  readonly publicPayloadSchema: z.ZodObject<z.ZodRawShape>;
+  readonly rootId: string;
+  readonly namespace: string;
+}
+
+export interface BusinessBirthDirective extends Directive<Record<string, unknown>> {
+  readonly businessBirth: BusinessBirthMetadata;
+}
+
+type BusinessBirthInternalDirective<P = Record<string, unknown>> = Directive<P> & {
+  readonly businessBirthInternal: true;
+};
+
+function internalDirective<P>(d: Directive<P>): BusinessBirthInternalDirective<P> {
+  return { ...d, businessBirthInternal: true } as BusinessBirthInternalDirective<P>;
+}
+
+/** Presentation-only marker: the declaration remains signed law, but tenant codegen omits it. */
+function internalSurface<T extends object>(value: T): T & { readonly businessBirthInternal: true } {
+  return { ...value, businessBirthInternal: true };
+}
+
+const INTERNAL_FIELDS = ["principal", "bornAt", "ownerKeyHash", "birthCert"] as const;
+const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
+
+/**
+ * Every business-born workspace verifies its own travelling birth certificate against its warrant owner.
+ * The locators are framework state, not fields the tenant must add to their business aggregate.
+ */
+const businessParentAttestedBirth: ParentAttestedBirthMarker = {
+  ...requireParentAttestedBirth,
+  ownerObject: GENESIS_WARRANT_ID,
+  ownerField: "principal",
+  certObject: BIRTH_ATTESTATION_ID,
+  certField: "certChain",
+};
+
+function businessBirthsOf(mod: Record<string, unknown>): BusinessBirthDecl[] {
+  return Object.values(mod).filter(
+    (v): v is BusinessBirthDecl =>
+      !!v && typeof v === "object" && (v as { __isBusinessBirth?: unknown }).__isBusinessBirth === true,
+  );
+}
+
+function lowerOne(decl: BusinessBirthDecl, domain: string): Record<string, unknown> {
+  const fields = (decl.payloadSchema as z.ZodObject<z.ZodRawShape>).shape;
+  for (const field of INTERNAL_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(fields, field)) {
+      throw new Error(
+        `birth(${decl.aggregate.id}): business payload field '${field}' is reserved by Nomos; ` +
+          "rename the business field (identity, provenance and lifecycle stay framework-owned)",
+      );
+    }
+  }
+
+  const stem = decl.aggregate.id.replace(/[^A-Za-z0-9]/g, "");
+  const namespace = (decl.namespace ?? decl.aggregate.id).replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+  const rootId = `${namespace}:self`;
+  const seedId = `nomosSeed${stem}`;
+  const birthId = `nomosBirth${stem}`;
+  const publicSchema = decl.payloadSchema as z.ZodObject<z.ZodRawShape>;
+  const internalSchema = publicSchema.extend({
+    principal: z.string().min(1),
+    bornAt: z.string().min(1),
+    ownerKeyHash: sha256Hex.optional(),
+    birthCert: z.string().optional(),
+  });
+
+  const seedBase = directive(seedId)
+    .ensures(decl.aggregate)
+    .payload(internalSchema)
+    .plan((p) => {
+      decl.plan(ensure(decl.aggregate, rootId), p);
+      return [];
+    });
+  const seed = {
+    ...seedBase,
+    businessBirthInternal: true,
+  } as BusinessBirthInternalDirective;
+
+  const birthBase = directive(birthId)
+    .creates(decl.aggregate)
+    .payload(internalSchema)
+    .plan((p) => {
+      const founder = p.principal as string;
+      const child = workspaceNameForKey(namespace, String(decl.key(p)));
+      const chain: Array<Record<string, unknown>> = [
+        {
+          domain: "bootstrap",
+          directiveId: "installDomain",
+          actor: founder,
+          payload: { domainHash: `${CURRENT_LAW_PREFIX}nomos` },
+          domainHash: `${CURRENT_LAW_PREFIX}nomos`,
+          domainPackageB64: "",
+        },
+        {
+          domain: "nomos",
+          directiveId: "installDomain",
+          actor: founder,
+          payload: { domainHash: `${CURRENT_LAW_PREFIX}${domain}` },
+          domainHash: `${CURRENT_LAW_PREFIX}${domain}`,
+          domainPackageB64: "",
+        },
+        {
+          domain,
+          directiveId: seedId,
+          actor: founder,
+          payload: p,
+        },
+      ];
+
+      const apRows = readFrameworkDeclared<Array<Record<string, unknown>>>("authProvider", { scope: "platform" });
+      const apRaw = Array.isArray(apRows) && apRows.length > 0 ? apRows[0] : undefined;
+      const ap = (apRaw && typeof apRaw === "object" && typeof (apRaw as { data?: unknown }).data === "object"
+        ? (apRaw as { data: Record<string, unknown> }).data
+        : apRaw) as Record<string, unknown> | undefined;
+      const apStr = (k: string): string | undefined => {
+        const v = ap?.[k];
+        return typeof v === "string" && v.length > 0 ? v : undefined;
+      };
+      let verified = false;
+      try { verified = typeof p.birthCert === "string" && JSON.parse(p.birthCert).verified === true; } catch {}
+      if (typeof p.ownerKeyHash === "string") {
+        chain.push({
+          domain,
+          directiveId: "enrollSigner",
+          actor: founder,
+          payload: {
+            keyHash: p.ownerKeyHash,
+            grantedBy: founder,
+            grantedAt: 1,
+            ...(verified && apStr("issuer") ? { verifiedVia: apStr("issuer") } : {}),
+          },
+        });
+      }
+      if (apStr("issuer")) {
+        chain.push({
+          domain,
+          directiveId: "setAuthProvider",
+          actor: founder,
+          payload: {
+            issuer: apStr("issuer"),
+            jwksUrl: apStr("jwksUrl") ?? apStr("issuer"),
+            ...(apStr("keys") ? { keys: apStr("keys") } : {}),
+            ...(apStr("audience") ? { audience: apStr("audience") } : {}),
+            ...(apStr("principalClaim") ? { principalClaim: apStr("principalClaim") } : {}),
+            ...(apStr("rootCert") ? { rootCert: apStr("rootCert") } : {}),
+            ...(apStr("deviceBindingClaim") ? { deviceBindingClaim: apStr("deviceBindingClaim") } : {}),
+            ...(apStr("requireDeviceBinding") ? { requireDeviceBinding: apStr("requireDeviceBinding") } : {}),
+            label: apStr("label") ?? "inherited-from-parent",
+            setBy: founder,
+            setAt: 1,
+          },
+        });
+      }
+      birth({ workspace: child, genesisChain: chain });
+      return [];
+    })
+    .reads(authProvider)
+    .births();
+
+  const metadata: BusinessBirthMetadata = {
+    aggregateId: decl.aggregate.id,
+    publicPayloadSchema: publicSchema,
+    rootId,
+    namespace,
+  };
+  const parent = { ...birthBase, businessBirth: metadata } as BusinessBirthDirective;
+  return {
+    [`__nomos_${birthId}`]: parent,
+    [`__nomos_${seedId}`]: seed,
+
+    // THE SOVEREIGN-WORKSPACE CORE. These are ordinary law declarations, composed automatically so the
+    // tenant's one business declaration is also a complete child law: it can fold the kernel-injected
+    // travelling attestation + warrant, seat its founding device, inherit its verifier, and verify itself
+    // offline after custody is moved or reopened. The generated tenant client hides every one of them.
+    __nomos_GenesisWarrant: internalSurface(GenesisWarrant),
+    __nomos_seedGenesis: internalDirective(seedGenesis),
+    __nomos_BirthAttestation: internalSurface(BirthAttestation),
+    __nomos_seedBirthAttestation: internalDirective(seedBirthAttestation),
+    __nomos_birthAttestation: internalSurface(birthAttestation),
+    __nomos_RelationTuple: internalSurface(RelationTuple),
+    __nomos_relationTuplesByObject: internalSurface(relationTuplesByObject),
+    __nomos_identityRelations: identityRelations,
+    __nomos_enrollSigner: internalDirective(enrollSigner),
+    __nomos_enrollFirstDevice: internalDirective(enrollFirstDevice),
+    __nomos_SignerDelegation: internalSurface(SignerDelegation),
+    __nomos_enrollDelegation: internalDirective(enrollDelegation),
+    __nomos_signerDelegationByUser: internalSurface(signerDelegationByUser),
+    __nomos_AuthProvider: internalSurface(AuthProvider),
+    __nomos_setAuthProvider: internalDirective(setAuthProvider),
+    __nomos_authProvider: internalSurface(authProvider),
+    // Exact export keys prevent the generic `.births()` auto-compose seam from inserting a second,
+    // unmarked copy. The values are still the canonical framework declarations.
+    NomosBirthRecord: internalSurface(NomosBirthRecord),
+    BirthPolicy: internalSurface(BirthPolicy),
+    BirthGrant: internalSurface(BirthGrant),
+    nomosBirthRecordEnsure: internalDirective(nomosBirthRecordEnsure),
+    __nomos_birthRecordsByPrincipal: internalSurface(birthRecordsByPrincipal),
+    __nomos_birthPolicy: internalSurface(birthPolicy),
+    __nomos_birthGrantByPrincipal: internalSurface(birthGrantByPrincipal),
+    __nomos_parentAttestedBirth: businessParentAttestedBirth,
+  };
+}
+
+/** Lower the one tenant-facing birth declaration into ordinary, gate-visible framework directives. */
+export function expandBusinessBirthExports<M extends Record<string, unknown>>(
+  mod: M,
+  domain: string,
+): Record<string, unknown> {
+  const declarations = businessBirthsOf(mod);
+  if (declarations.length === 0) return mod;
+  if (declarations.length > 1) {
+    throw new Error(
+      `domain '${domain}' declares ${declarations.length} business births; one generated birth(payload) cannot be ` +
+        "ambiguous — model one born aggregate root per domain",
+    );
+  }
+  const lowered = lowerOne(declarations[0]!, domain);
+  return { ...mod, ...lowered };
+}
+
+export function isBusinessBirthDirective(value: unknown): value is BusinessBirthDirective {
+  return !!value && typeof value === "object" && !!(value as { businessBirth?: unknown }).businessBirth;
+}
+
+export function isBusinessBirthInternalDirective(value: unknown): boolean {
+  return !!value && typeof value === "object" && (value as { businessBirthInternal?: unknown }).businessBirthInternal === true;
+}

package/src/codegen_dart.ts

@@ -4243,8 +4243,36 @@ export interface GenerateDartDomainOptions {
 
 /** Generate the full Dart source for one domain module. */
 export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOptions = {}): string {
+  const publicAggregates = mod.aggregates.filter(
+    (a) => (a as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+  );
+  const publicAggregateIds = new Set(publicAggregates.map((a) => a.id));
+  mod = {
+    ...mod,
+    aggregates: publicAggregates,
+    directives: mod.directives.filter(
+      (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+    ),
+    ...(mod.queries === undefined
+      ? {}
+      : { queries: mod.queries.filter((q) => (q as { businessBirthInternal?: unknown }).businessBirthInternal !== true) }),
+    ...(mod.readModelAggregates === undefined
+      ? {}
+      : { readModelAggregates: mod.readModelAggregates.filter((id) => publicAggregateIds.has(id)) }),
+  };
   registerDartNames(mod.aggregates); // `.dartName` overrides for this domain's Dart naming derivations.
   const domainKey = mod.domain ?? mod.name;
+  // ONE BUSINESS BIRTH: framework-only genesis/control directives remain law, but are not tenant DTOs.
+  // The one public parent directive is rendered against the business payload schema (identity/provenance
+  // fields are injected by the runtime). This is frontend codegen only; the composed manifest is untouched.
+  const codegenDirectives = mod.directives
+    .filter((d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true)
+    .map((d) => {
+      const businessBirth = (d as { businessBirth?: { publicPayloadSchema?: z.ZodTypeAny } }).businessBirth;
+      return businessBirth?.publicPayloadSchema === undefined
+        ? d
+        : { ...d, payloadSchema: businessBirth.publicPayloadSchema } as AnyDirective;
+    });
   const skipAggregateIds = opts.skipAggregateIds ?? new Set<string>();
   const skipDirectiveIds = opts.skipDirectiveIds ?? new Set<string>();
   const skipQueryIds = opts.skipQueryIds ?? new Set<string>();
@@ -4255,11 +4283,11 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   // their generated class — collected from the branded payload schemas, deduped by name against
   // the aggregate-derived set. Codegen-only: the IR key stays aggregate-derived (era rule).
   const aggVoNames = new Set((mod.valueObjects ?? []).map((d) => d.name));
-  const payloadVos = collectPayloadValueObjectDescriptors(mod.directives ?? []).filter((d) => !aggVoNames.has(d.name));
+  const payloadVos = collectPayloadValueObjectDescriptors(codegenDirectives).filter((d) => !aggVoNames.has(d.name));
   // RECURSIVE `z.lazy` payloads → synthesized recursive-class descriptors (full support). They
   // are codegen-only (like payloadVos): the law IR / domainHash never sees them (era rule). The
   // name map routes each recursive payload field to its class in [emitDirective].
-  const recursiveTypes = synthesizeRecursivePayloadTypes(mod.directives ?? []);
+  const recursiveTypes = synthesizeRecursivePayloadTypes(codegenDirectives);
   const recursiveDescriptors = [...recursiveTypes.descriptors.values()].filter(
     (d) => !aggVoNames.has(d.name) && !payloadVos.some((p) => p.name === d.name),
   );
@@ -4289,7 +4317,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
       if ("fields" in arm) for (const f of Object.values(arm.fields)) walkUnitField(f);
     }
   }
-  for (const dir of mod.directives ?? []) {
+  for (const dir of codegenDirectives) {
     const schema = (dir as { payloadSchema?: unknown }).payloadSchema;
     if (schema && typeof schema === "object" && zodTypeName(schema as z.ZodTypeAny) === "ZodObject") {
       try {
@@ -4353,7 +4381,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
           f.valueObject === undefined),
     ),
   );
-  const localDirectives = mod.directives.filter((d) => !skipDirectiveIds.has(d.id));
+  const localDirectives = codegenDirectives.filter((d) => !skipDirectiveIds.has(d.id));
   const localQueries = (mod.queries ?? []).filter((q) => !skipQueryIds.has(q.id));
   // Enums are collected from the LOCALLY-emitted symbols only — a framework directive/aggregate's
   // enums ride the shared `nomos_framework.dart`, so a domain that skips them emits no dangling enum.
@@ -4367,7 +4395,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   for (const a of mod.aggregates) aggregatesById.set(a.id, a);
   const ownIdFieldsByAggregate = collectOwnIdFieldsByAggregate(
     mod.aggregates,
-    mod.directives,
+    codegenDirectives,
     dartTypes,
   );
   const enumBlock = decls.join("\n\n");

package/src/codegen_dart_client.ts

@@ -167,6 +167,23 @@ export interface DartBridgeClientOptions {
 
 /** Generate the `<name>.client.dart` async bridge client for one domain module. */
 export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClientOptions): string {
+  const publicAggregates = mod.aggregates.filter(
+    (a) => (a as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+  );
+  const publicAggregateIds = new Set(publicAggregates.map((a) => a.id));
+  mod = {
+    ...mod,
+    aggregates: publicAggregates,
+    directives: mod.directives.filter(
+      (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+    ),
+    ...(mod.queries === undefined
+      ? {}
+      : { queries: mod.queries.filter((q) => (q as { businessBirthInternal?: unknown }).businessBirthInternal !== true) }),
+    ...(mod.readModelAggregates === undefined
+      ? {}
+      : { readModelAggregates: mod.readModelAggregates.filter((id) => publicAggregateIds.has(id)) }),
+  };
   registerDartNames(mod.aggregates); // `.dartName` overrides for read-model class names in the client.
   const domain = mod.domain ?? mod.name;
   const className = dartClientClassName(domain);
@@ -223,7 +240,9 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   // 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",
+    (d) => d && typeof d.id === "string"
+      && typeof (d as { payloadSchema?: unknown }).payloadSchema === "object"
+      && (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
   );
   const birthDirs = allDirs.filter((d) => (d as { birthsChild?: boolean }).birthsChild === true);
   const dirs = allDirs.filter((d) => (d as { birthsChild?: boolean }).birthsChild !== true);
@@ -324,6 +343,32 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const payloadClass = `${cap(d.id)}Payload`;
     const method = safeMethod(d.id);
     const gate = (d as { requiresRelationGate?: { relation: string } }).requiresRelationGate;
+    const businessBirth = (d as unknown as {
+      businessBirth?: { aggregateId: string; rootId: string };
+    }).businessBirth;
+    if (businessBirth !== undefined) {
+      methods.push(
+        `  /// Give one ${businessBirth.aggregateId} its own durable life. Nomos owns identity, authorship,`,
+        `  /// provenance, persistence and recovery; the app supplies only business facts.`,
+        `  Future<NomosRef> birth(${payloadClass} payload) async {`,
+        `    final principal = actor ?? bridge.principal;`,
+        `    if (principal == null || principal.trim().isEmpty) {`,
+        `      throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, requires: 'a signed-in Nomos session');`,
+        `    }`,
+        `    final data = payload.toPayloadJson();`,
+        `    data['principal'] = principal;`,
+        `    data['bornAt'] = DateTime.now().toUtc().toIso8601String();`,
+        `    final outcome = await _offer(${dartStr(d.id)}, data);`,
+        `    if (outcome.born.length != 1) {`,
+        `      throw StateError('birth() committed without returning exactly one born workspace');`,
+        `    }`,
+        `    await bridge.sync();`,
+        `    return NomosRef(workspace: outcome.born.single, type: ${dartStr(businessBirth.aggregateId)}, id: ${dartStr(businessBirth.rootId)});`,
+        `  }`,
+        ``,
+      );
+      continue;
+    }
     methods.push(
       `  /// Births a CHILD WORKSPACE named by \`${payloadClass}\` — a \`.births()\` offer on THIS client's`,
       `  /// session, whose workspace IS the parent (session_bound_clients.md ask 4: no loose parent string).`,

package/src/codegen_openapi.ts

@@ -99,6 +99,18 @@ export function generateOpenApiFragment(
   module: DomainModule,
   opts: OpenApiFragmentOptions = {},
 ): OpenApiDoc {
+  module = {
+    ...module,
+    aggregates: module.aggregates.filter(
+      (a) => (a as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+    ),
+    directives: module.directives.filter(
+      (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+    ),
+    ...(module.queries === undefined
+      ? {}
+      : { queries: module.queries.filter((q) => (q as { businessBirthInternal?: unknown }).businessBirthInternal !== true) }),
+  };
   const domain = domainKey(module);
   const paths: Record<string, Record<string, unknown>> = {};
 
@@ -111,12 +123,22 @@ export function generateOpenApiFragment(
 
   // OFFERABLE INTENTS → POST offers. The payload JSON Schema is the intent's own zod, lowered.
   for (const dir of module.directives as AnyDirective[]) {
+    if ((dir as { businessBirthInternal?: unknown }).businessBirthInternal === true) continue;
+    const businessBirth = (dir as {
+      businessBirth?: { aggregateId: string; publicPayloadSchema: unknown };
+    }).businessBirth;
+    const publicId = businessBirth === undefined ? dir.id : "birth";
+    const publicDir = businessBirth === undefined
+      ? dir
+      : { ...dir, payloadSchema: businessBirth.publicPayloadSchema } as AnyDirective;
     const invs = invariantsOf(dir.id);
     const op: Record<string, unknown> = {
-      operationId: `${domain}__${dir.id}`,
+      operationId: `${domain}__${publicId}`,
       tags: [domain],
-      summary: `offer: ${dir.id}`,
-      description: dir.marker && dir.aggregateId
+      summary: businessBirth === undefined ? `offer: ${dir.id}` : `birth ${businessBirth.aggregateId}`,
+      description: businessBirth !== undefined
+        ? `Give one ${businessBirth.aggregateId} its own durable life.`
+        : dir.marker && dir.aggregateId
         ? `Offer the \`${dir.id}\` intent (${dir.marker} ${dir.aggregateId}). Admitted or refused by the law; the plan is private.`
         : `Offer the \`${dir.id}\` intent. Admitted or refused by the law.`,
       "x-nomos": {
@@ -130,7 +152,7 @@ export function generateOpenApiFragment(
       },
       requestBody: {
         required: true,
-        content: { "application/json": { schema: payloadJsonSchema(dir, module) } },
+        content: { "application/json": { schema: payloadJsonSchema(publicDir, module) } },
       },
       responses: {
         "200": { description: "admitted — the sealed intent head" },
@@ -138,7 +160,7 @@ export function generateOpenApiFragment(
         "422": { description: "the law refused the intent (typed refusal)" },
       },
     };
-    (paths[`/${dir.id}`] ??= {}).post = op;
+    (paths[`/${publicId}`] ??= {}).post = op;
   }
 
   // QUERIES → GET reads. Declared queries + the implicit hasMany inverse indexes (the relation IS

package/src/codegen_proof.ts

@@ -1720,6 +1720,9 @@ interface DiscoveredGenesisStep {
  *  synthesized payload (the synthesizer only produces `sample-*` placeholders, which the child install
  *  would refuse). */
 export interface ChildBirthLeg {
+  /** Present for the one application-facing `birth(Aggregate, spec)` declaration. Proof renderers use the
+   *  business noun and keep the lowered framework ceremony out of normal output. */
+  readonly businessAggregateId?: string;
   /** The domain the `.births()` directive lives in. */
   readonly parentDomain: string;
   /** The `.births()` directive id the parent drives to birth the child. */
@@ -2021,9 +2024,11 @@ export function discoverChildBirthLegOrReason(
   if (frameworkHashField !== undefined) delete birthPayload[frameworkHashField];
   if (lawHashField !== undefined) delete birthPayload[lawHashField];
 
+  const businessAggregateId = (birthDir as unknown as { businessBirth?: { aggregateId?: string } }).businessBirth?.aggregateId;
   const leg: ChildBirthLeg = {
     parentDomain,
     birthDirectiveId: birthDir.id,
+    ...(businessAggregateId !== undefined ? { businessAggregateId } : {}),
     birthPayload,
     birthAutoStamped: synth.autoStamped,
     ...(actorField !== undefined ? { birthActorField: actorField } : {}),
@@ -2346,6 +2351,15 @@ function hasBirthDirective(mod: DomainModule): boolean {
  *  when it has a `.creates`; child-birth-provable when it has a `.births()`). NEVER null: every compiled
  *  domain is at least `compile-valid` (gaps 1+3 — every domain is proof-addressable). */
 export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[]): ProofLegs {
+  // Business-birth control declarations are proofed as part of the birth's child genesis, not as
+  // tenant-authored standalone/gated actions. Keep the full `modules` below for recipe resolution while
+  // removing the presentation-only internals from leg selection and diagnostics.
+  mod = {
+    ...mod,
+    directives: (mod.directives as Directive<unknown>[]).filter(
+      (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+    ),
+  };
   const domain = mod.domain ?? mod.name;
   const allBirths = modules.flatMap((m) => childBirthsForModule(m, modules));
   // The standalone-create leg (when the domain has a non-birth `.creates`). FAIL SOFT: an exotic payload

package/src/codegen_ts.ts

@@ -800,6 +800,27 @@ function anyPackedTaxonomy(modules: readonly DomainModule[]): boolean {
 }
 
 export function generateTsClient(modules: readonly DomainModule[], opts: TsClientOptions): string {
+  // Business-birth framework declarations remain in the certified module, but are not application
+  // vocabulary. Strip only the presentation marker here; manifests, hashes and the engine see the full law.
+  modules = modules.map((mod) => {
+    const publicAggregates = mod.aggregates.filter(
+      (a) => (a as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+    );
+    const publicAggregateIds = new Set(publicAggregates.map((a) => a.id));
+    return {
+      ...mod,
+      aggregates: publicAggregates,
+      directives: mod.directives.filter(
+        (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+      ),
+      ...(mod.queries === undefined
+        ? {}
+        : { queries: mod.queries.filter((q) => (q as { businessBirthInternal?: unknown }).businessBirthInternal !== true) }),
+      ...(mod.readModelAggregates === undefined
+        ? {}
+        : { readModelAggregates: mod.readModelAggregates.filter((id) => publicAggregateIds.has(id)) }),
+    };
+  });
   const hashConst = tsHashConstName(opts.packageName);
   // THE E2E-SEALING MAP (the sealing client): non-null iff any field is `.encrypted()`. When null,
   // NOTHING below emits — the generated client is byte-identical to a pre-sealing compile.
@@ -812,7 +833,10 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   // 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),
+    (m.directives as Directive<unknown>[]).some((d) =>
+      (d as { birthsChild?: boolean })?.birthsChild === true
+        && (d as { businessBirth?: unknown }).businessBirth === undefined,
+    ),
   );
   // SURFACED MERGE CONFLICTS: a package declaring ≥1 `.merge(Surfaced(...))` field emits the
   // `SurfacedValue<T>` union + guard (below). Surfaced-free packages emit nothing (byte-identical).
@@ -869,6 +893,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     ` *  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 }`,
+    `/** A newly born business root. The phantom type makes the returned reference aggregate-specific while`,
+    ` *  its runtime identity stays the one canonical {workspace,type,id} NomosRef. */`,
+    `export type NomosBorn<TData> = NomosRef & { readonly __nomosData?: TData };`,
     `/** 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 {`,
@@ -1025,7 +1052,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; returnCreated?: boolean; attestations?: readonly { queryId: string; result: unknown; attestation: unknown }[] }): Promise<string | { head: string; created?: { type: string; id: string }[]; workspace?: string }>;`,
+    `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean; attestations?: readonly { queryId: string; result: unknown; attestation: unknown }[] }): Promise<string | { head: string; created?: { type: string; id: string }[]; workspace?: string; born?: unknown; birthOutcomes?: unknown }>;`,
     `  /** Opaque-bytes offer — retained for carriers that already hold an encoded envelope (back-compat). */`,
     `  offer(intentBytes: string | Uint8Array): Promise<string>;`,
     ...(hasBirths
@@ -1038,6 +1065,10 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       : []),
     `  /** The workspace this holon is bound to — the \`workspace\` of every [NomosRef] this client composes. */`,
     `  workspace: string;`,
+    `  /** The identity already proved by this bound session (explicit principal or token subject). */`,
+    `  principal?: string;`,
+    `  /** Persist local custody and reconcile its configured remote. Business birth awaits this when available. */`,
+    `  sync?(): Promise<unknown>;`,
     ...(encPresent
       ? [
           `  /** \`keys\` (E2E sealing): the reader's held scope keys, injected so encrypted fields decrypt;`,
@@ -1808,7 +1839,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   for (const mod of modules) {
     const domain = mod.domain ?? mod.name;
     const dirs = (mod.directives as Directive<unknown>[]).filter(
-      (d) => d && typeof d.id === "string" && typeof (d as { payloadSchema?: unknown }).payloadSchema === "object",
+      (d) => d && typeof d.id === "string" && typeof (d as { payloadSchema?: unknown }).payloadSchema === "object"
+        && (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
     );
     out.push(`// ── domain "${domain}" ──`, ``);
 
@@ -1849,7 +1881,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       if (usedPayloadNames.has(payloadName)) payloadName = `${cap(camel(domain))}${cap(d.id)}Payload`;
       usedPayloadNames.add(payloadName);
       dirPayloadNames.set(d.id, payloadName);
-      const schema = (d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema;
+      const businessBirth = (d as unknown as {
+        businessBirth?: { aggregateId: string; publicPayloadSchema: z.ZodTypeAny; rootId: string; namespace: string };
+      }).businessBirth;
+      const schema = businessBirth?.publicPayloadSchema
+        ?? (d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema;
       const stamps = autoStampFields(schema);
       const mint = mintPlan?.get(d.id);
       const placed = placementDirs.has(d.id) ? ["shard"] : [];
@@ -1897,6 +1933,24 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed, lazyReg, d.id)};`,
         ``,
       );
+      // ONE BUSINESS BIRTH: the session is the parent; identity, timestamp, child addressing, law selection,
+      // provenance and device seating are internal. The app supplies only the declared business payload and
+      // receives the born root's typed NomosRef.
+      if (businessBirth !== undefined) {
+        methods.push(
+          `    /** Give one ${businessBirth.aggregateId} its own durable life. Nomos owns identity, provenance, persistence and recovery. */`,
+          `    birth: async (payload: ${payloadName}): Promise<NomosBorn<${businessBirth.aggregateId}Data>> => {`,
+          `      const principal = actor ?? holon.principal;`,
+          `      if (!principal || !principal.trim()) throw new Error("birth() needs a signed-in Nomos session");`,
+          `      const result = await holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, { ...payload, principal, bornAt: new Date().toISOString() }, { domainHash, actor: principal, returnCreated: true });`,
+          `      const born = typeof result === "object" && result !== null && Array.isArray(result.born) ? result.born[0] : undefined;`,
+          `      if (typeof born !== "object" || born === null || typeof born.workspace !== "string" || !born.workspace) throw new Error("birth() committed without returning the born workspace");`,
+          `      await holon.sync?.();`,
+          `      return { workspace: born.workspace, type: ${JSON.stringify(businessBirth.aggregateId)}, id: ${JSON.stringify(businessBirth.rootId)} };`,
+          `    },`,
+        );
+        continue;
+      }
       // 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
@@ -2118,7 +2172,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       ` *  judge the real author. Omit it for open (un-gated) domains. */`,
       `export function ${tsClientFactoryName(domain)}(holon: NomosHolon, opts: { domainHash?: string; actor?: string${encPresent ? "; keyStore?: NomosKeyStore" : ""} } = {}) {`,
       `  const domainHash = opts.domainHash ?? ${hashConst};`,
-      `  const actor = opts.actor;`,
+      `  const actor = opts.actor ?? holon.principal;`,
       ...(encPresent ? [`  const keyStore = opts.keyStore;`] : []),
       ...(opts.compat !== undefined
         ? [

package/src/compile_package_main.ts

@@ -93,6 +93,7 @@ import {
 import { synthesizePreconditionInvariants } from "./precondition.js";
 import { BIRTH_METER_QUERIES, synthesizeBirthQuotaInvariants } from "./birth_meter.js";
 import { withBirthMeterExports } from "./birth_meter_ensure.js";
+import { expandBusinessBirthExports } from "./business_birth.js";
 import { expandRoleExports, rolesOf } from "./role.js";
 import { collectEngineRouting } from "./engine_entry.js";
 import {
@@ -1051,7 +1052,7 @@ const NOMOS_TYPES_DEP = "^0.6.0";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.61.0";
+const NOMOS_CLIENT_DEP = "^0.62.0";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).
@@ -1616,6 +1617,7 @@ async function main(): Promise<void> {
     }
     let merged: Mod = {};
     for (const m of mods) merged = { ...merged, ...m };
+    merged = expandBusinessBirthExports(merged, d.key);
     // `capability()` bundles expand into discoverable entries (the CLI plane's
     // merge point) — queries/sums/sid-minting/manifests all see the pieces.
     merged = expandCapabilityExports(merged);
@@ -2959,19 +2961,16 @@ async function main(): Promise<void> {
     console.log(`    parses on every kernel (larger deploy body; may need the signed-upload deploy lane).`);
   }
   console.log(``);
-  console.log(`deploy (Nomos Cloud):`);
-  console.log(`  githolon login --agent && githolon ws create <ws> && githolon deploy <ws>   # no secret — deploy is OPEN, kernel-judged at the offer gate`);
-  console.log(`  # raw lane: curl -X POST -H 'content-type: application/json' -H 'x-nomos-principal: <your-auth-uid>' \\`);
-  console.log(`  #   --data-binary @${rel(deployPath)} https://nomos.captainapp.co.uk/v2/workspaces/<ws>/domains`);
+  console.log(`your business path:`);
   if (proofPath !== undefined) {
-    console.log(`prove it OFFLINE first: npx githolon proof        # the generated proof's offline legs on a LOCAL holon (no cloud workspace)`);
-    console.log(`  inner loop:           npx githolon dev          # watch -> recompile -> law live locally -> offline proof, on every save`);
-    console.log(`  then the cloud loop:  npx githolon proof --live # throwaway workspace, retired on exit (--keep keeps it)`);
+    console.log(`  npx githolon proof         # generated birth -> verify -> durable restore -> business read-back`);
+    console.log(`  npx githolon dev           # rerun that proof on every save`);
+    console.log(`  npx githolon proof --live  # the same business proof against Nomos Cloud`);
     if (proofDomains.length > 1) {
       console.log(`  this package proves ${proofDomains.length} domains (${proofDomains.join(", ")}) — default '${proofDomains[0]}'; pick another: npx githolon proof --domain <key>`);
     }
   } else {
-    console.log(`prove it: npm run e2e   # offline write -> sync -> admission -> cloud query, live`);
+    console.log(`  add a business birth declaration to generate an end-to-end proof`);
   }
 
   if (analyzeFlag) runDartAnalyze(dartOut);

package/src/engine_entry.ts

@@ -80,6 +80,7 @@ import type { CombinedDecl } from "./combined.js";
 import type { InvariantBody, InvariantEvidence, InvariantVerdict } from "./relation.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { QueryRow } from "./report.js";
+import { expandBusinessBirthExports } from "./business_birth.js";
 
 /** One bundled domain module: a bag of named exports the entry scans by SHAPE. */
 export type DomainModuleExports = Record<string, unknown>;
@@ -244,9 +245,10 @@ function combinedsOf(mod: DomainModuleExports): CombinedDecl[] {
 }
 
 /** Spread-merge a domain key's ORDERED module list (later wins on collision). */
-function mergeModules(mods: readonly DomainModuleExports[]): DomainModuleExports {
+function mergeModules(mods: readonly DomainModuleExports[], domain: string): DomainModuleExports {
   let merged: DomainModuleExports = {};
   for (const m of mods) merged = { ...merged, ...m };
+  merged = expandBusinessBirthExports(merged, domain);
   // `capability()` bundles expand into discoverable entries here — the engine
   // plane's ONE merge point, so the registry sees the task aggregate + quartet
   // without per-piece re-exports (capability_exports.ts).
@@ -465,7 +467,7 @@ export function collectEngineRouting(
     if (!list.includes(domainName)) list.push(domainName);
   };
   for (const [domainName, mods] of Object.entries(domains)) {
-    const slice = buildDomainSlice(mergeModules(mods));
+    const slice = buildDomainSlice(mergeModules(mods, domainName));
     // Type-keyed dispatches arrive with the ROW's type — QUALIFIED for a namespaced aggregate (the
     // runtime `__type` stamp), bare for a global one / a pre-namespacing row. Route BOTH keys so
     // either era resolves to the declaring domain (the slice lookup strips the qualifier back off).
@@ -551,7 +553,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     const sources = config.domains[domainName];
     if (sources === undefined) return undefined;
     const forced = sources.map((m) => (typeof m === "function" ? m() : m));
-    const slice = buildDomainSlice(mergeModules(forced));
+    const slice = buildDomainSlice(mergeModules(forced, domainName));
     sliceCache.set(domainName, slice);
     return slice;
   }
@@ -943,7 +945,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     for (const domainName of domainNames) {
       const sources = config.domains[domainName];
       if (sources === undefined) continue;
-      const merged = mergeModules(sources.map((m) => (typeof m === "function" ? m() : m)));
+      const merged = mergeModules(sources.map((m) => (typeof m === "function" ? m() : m)), domainName);
       // Aggregates dedup by wire id + RelationTuple auto-ensure (the compose contract) — openapi
       // reads aggregates only for the hasMany inverse indexes, so this matches composeDomainModule.
       const byId = aggregatesOf(merged);

package/src/index.ts

@@ -221,6 +221,8 @@ export {
   birthInstance,
   type BirthRecipe,
   type GenesisChainOrBuilder,
+  type BusinessBirthDecl,
+  type BusinessBirthSpec,
 } 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

package/src/law_check.ts

@@ -371,6 +371,9 @@ function planReturnFindings(domain: string, dir: Directive<unknown>, probe: Prob
 // Framework-consumed convention fields (auto-stamped `…At`, birth subject/time) are excluded.
 function unreadPayloadFindings(domain: string, dir: Directive<unknown>, probe: ProbeResult): Finding[] {
   if (probe.threw) return [];
+  // A business birth's public fields are consumed by its hidden child-seed directive. That seed is linted
+  // independently; warning again on the parent half is a false positive caused by the lowering boundary.
+  if ((dir as { businessBirth?: unknown }).businessBirth !== undefined) return [];
   const stamped = new Set(autoStampFields(dir.payloadSchema as z.ZodTypeAny));
   // The GATE reads some payload fields the PLAN never does: `.requires(rel, { objectFrom })` derives
   // the gate object from a named payload id field (per-record authz). Excluding it keeps a real
@@ -379,6 +382,14 @@ function unreadPayloadFindings(domain: string, dir: Directive<unknown>, probe: P
   const objectFromField = (dir as { requiresRelationGate?: { objectFrom?: { idField?: string } } })
     .requiresRelationGate?.objectFrom?.idField;
   if (typeof objectFromField === "string") gateConsumed.add(objectFromField);
+  const firstDeviceGate = (dir as {
+    firstDeviceEnrollGate?: { tokenField: string; keyHashField: string; verifiedViaField: string };
+  }).firstDeviceEnrollGate;
+  if (firstDeviceGate !== undefined) {
+    gateConsumed.add(firstDeviceGate.tokenField);
+    gateConsumed.add(firstDeviceGate.keyHashField);
+    gateConsumed.add(firstDeviceGate.verifiedViaField);
+  }
   // A dynamic .readsFrom(fromPayload("<wsField>"), …) edge routes the foreign read by a payload field the
   // ROUTING lane consumes (the plan may pass it straight to read(…, {from}) without a tracked property
   // read on the sampled path) — a declared trust-edge field is never a dead field.