@githolon/dsl 0.101.6 → 0.102.0

package/src/activity.ts

@@ -25,7 +25,7 @@ export type ActivitySeverity = "info" | "success" | "warning" | "critical";
 /** A declared navigation target: the referenced aggregate/contract TYPE + the payload field path holding its
  *  id. Replaces the enricher's blind id-probing — the reference is declared, not guessed. */
 export interface ActivityRefInput {
-  /** The target type — an aggregate handle or a `contract(...)` (reuse contracts for the nav target). */
+  /** The target type — an aggregate handle or a `recordContract(...)` (reuse contracts for the nav target). */
   readonly type: AggregateHandle | ContractHandle;
   /** The payload field path holding the target's id (dotted for nested, e.g. `"location.siteId"`), OR the
    *  sentinel `"@created"` — the id the LAW MINTED for this intent's created aggregate of `type` (read from
@@ -187,7 +187,7 @@ export function normalizeActivity(
     const targetId = (r?.type as { id?: unknown })?.id;
     const isTarget = typeof targetId === "string" && ((r.type as { __isAggregateHandle?: unknown }).__isAggregateHandle === true || isContractHandle(r.type));
     if (!isTarget) {
-      throw new Error(`${where}: ref '${name}'.type must be an aggregate handle or a contract(...) (got ${typeof r?.type}).`);
+      throw new Error(`${where}: ref '${name}'.type must be an aggregate handle or a recordContract(...) (got ${typeof r?.type}).`);
     }
     if (typeof r.from !== "string" || r.from.length === 0) {
       throw new Error(`${where}: ref '${name}'.from must be a payload field path string.`);

package/src/aggregate.ts

@@ -324,11 +324,27 @@ export interface AudienceMethods<Id extends string, F extends Record<string, Fie
 /** A legal Dart TYPE identifier for `.dartName()` — PascalCase-ish (leading upper, then word chars). */
 const DART_TYPE_NAME_RE = /^[A-Z][A-Za-z0-9_]*$/;
 
+type AggregateOptions = {
+  invariant?: AggregateInvariantFn;
+  invariantDeclassify?: string;
+  cap?: number;
+  visibility?: ReadVisibility;
+  global?: boolean;
+  attributed?: boolean;
+};
+
 export function aggregate<const Id extends string, F extends Record<string, Field>>(
   id: Id,
   fields: F,
-  opts?: { invariant?: AggregateInvariantFn; invariantDeclassify?: string; cap?: number; visibility?: ReadVisibility; global?: boolean; attributed?: boolean },
+  opts?: AggregateOptions,
 ): AggregateHandle<Id, F> & AudienceMethods<Id, F> {
+  if (["user", "identity"].includes(id.toLowerCase())) {
+    throw new Error(
+      `aggregate '${id}': '${id}' is a first-class Nomos authority concept, not application state. Sorry mate, that ` +
+        `concept is already taken by the framework; model the business concept as Person, Customer, ` +
+        `Employee, Member, or another domain-specific name.`,
+    );
+  }
   for (const reserved of [
     OWNER_FIELD,
     OWNED_KEY_PAYLOAD_FIELD,
@@ -620,6 +636,13 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
             `matching ${DART_TYPE_NAME_RE} (PascalCase — a leading uppercase letter, then letters/digits/underscore)`,
         );
       }
+      if (name === "User" || name === "Identity") {
+        throw new Error(
+          `aggregate '${id}': .dartName(${JSON.stringify(name)}) cannot claim a first-class Nomos authority type. ` +
+            `Sorry mate, that concept is already taken by the framework; use Person, Customer, ` +
+            `Employee, Member, or another domain-specific name.`,
+        );
+      }
       return build(audience, visibility, contracts, name);
     },
     }) as unknown as AggregateHandle<Id, F> & AudienceMethods<Id, F>;

package/src/application_composition.ts

@@ -0,0 +1,282 @@
+// NOMOS — OpenUSD is the application/package IR. JavaScript config is authoring input only.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { usdaString, usdaStringArray } from "./usd_layers.js";
+
+export type PartKind = "component" | "assembly" | "group";
+
+export interface CompositionArc {
+  /** Content-addressed package/part asset, relative to the application stage or a resolver URI. */
+  readonly asset: string;
+  /** Absolute prim path exported by that asset. */
+  readonly prim: `/${string}`;
+}
+
+export interface ApplicationPart {
+  readonly name: string;
+  readonly kind: PartKind;
+  /** A package or part composed greedily into the application namespace. */
+  readonly reference?: CompositionArc;
+  /** The selectively loaded business replica for this known part. */
+  readonly payload?: CompositionArc;
+  /** Stable application-level address; never a workspace or Holon identifier. */
+  readonly address?: string;
+  readonly children?: readonly ApplicationPart[];
+}
+
+export interface ApplicationCompositionConfig {
+  readonly application: string;
+  /** Optional concrete instance identity. Omit for a reusable application definition. */
+  readonly instance?: string;
+  readonly root: ApplicationPart;
+  readonly outDir?: string;
+}
+
+export interface PackageRootPart {
+  readonly name: string;
+  readonly kind: Exclude<PartKind, "group">;
+}
+
+const safeUsdName = (value: string, what: string): void => {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new Error(`${what} '${value}' is not a USD identifier (letters, digits and '_' only; cannot start with a digit)`);
+  }
+};
+
+const validateArc = (arc: CompositionArc, at: string): void => {
+  if (arc.asset.length === 0 || /[@\r\n]/.test(arc.asset)) {
+    throw new Error(`${at} names an unsafe or empty asset path`);
+  }
+  if (!/^\/(?:[A-Za-z_][A-Za-z0-9_]*)(?:\/[A-Za-z_][A-Za-z0-9_]*)*$/.test(arc.prim)) {
+    throw new Error(`${at} must name an absolute exported prim path`);
+  }
+};
+
+/** Fail-closed structural validation before a composition is emitted. */
+export function validateApplicationComposition(config: ApplicationCompositionConfig): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(config.application)) {
+    throw new Error(`application '${config.application}' is not a safe content/artifact name`);
+  }
+  safeUsdName(config.root.name, "application root");
+  if (config.root.kind !== "assembly") {
+    throw new Error(`application root '${config.root.name}' must be an assembly, got ${config.root.kind}`);
+  }
+
+  const addresses = new Set<string>();
+  const visit = (part: ApplicationPart, at: string): void => {
+    safeUsdName(part.name, `part at ${at}`);
+    const here = `${at}/${part.name}`;
+    const children = part.children ?? [];
+    const siblingNames = new Set<string>();
+    for (const child of children) {
+      if (siblingNames.has(child.name)) throw new Error(`namespace collision at ${here}: child '${child.name}' appears more than once`);
+      siblingNames.add(child.name);
+    }
+    if (part.kind === "component" && children.length > 0) {
+      throw new Error(`component '${here}' cannot declare child parts`);
+    }
+    if (part.kind === "group") {
+      if (part.reference !== undefined || part.payload !== undefined || part.address !== undefined) {
+        throw new Error(`group '${here}' is namespace glue and cannot carry a reference, payload or part address`);
+      }
+    }
+    if (part.payload !== undefined && part.reference === undefined) {
+      throw new Error(`part '${here}' declares a payload without the package/part reference that makes it known`);
+    }
+    if (part.reference !== undefined) validateArc(part.reference, `reference on '${here}'`);
+    if (part.payload !== undefined) validateArc(part.payload, `payload on '${here}'`);
+    if (part.address !== undefined) {
+      if (part.address.trim().length === 0) throw new Error(`part '${here}' has an empty address`);
+      if (addresses.has(part.address)) throw new Error(`part address '${part.address}' is used more than once`);
+      addresses.add(part.address);
+    }
+    for (const child of children) visit(child, here);
+  };
+  visit(config.root, "");
+}
+
+function emitPart(part: ApplicationPart, indent: string, rootMetadata?: readonly string[]): string[] {
+  const metadata = [
+    `${indent}    kind = ${usdaString(part.kind)}`,
+    ...(part.reference !== undefined
+      ? [`${indent}    prepend references = @${part.reference.asset}@<${part.reference.prim}>`]
+      : []),
+    ...(part.payload !== undefined
+      ? [`${indent}    prepend payload = @${part.payload.asset}@<${part.payload.prim}>`]
+      : []),
+  ];
+  const body = [
+    ...(rootMetadata ?? []),
+    ...(part.address !== undefined
+      ? [`${indent}    custom string nomos:partAddress = ${usdaString(part.address)}`]
+      : []),
+    ...(part.children ?? []).flatMap((child) => ["", ...emitPart(child, `${indent}    `)]),
+  ];
+  return [
+    `${indent}def Scope ${usdaString(part.name)} (`,
+    ...metadata,
+    `${indent})`,
+    `${indent}{`,
+    ...body,
+    `${indent}}`,
+  ];
+}
+
+/** Emit the application definition itself. This USDA is the configuration that travels. */
+export function applicationCompositionUsda(config: ApplicationCompositionConfig): string {
+  validateApplicationComposition(config);
+  return [
+    "#usda 1.0",
+    "(",
+    `    defaultPrim = ${usdaString(config.root.name)}`,
+    ")",
+    "",
+    ...emitPart(config.root, "", [
+      `    custom string nomos:application = ${usdaString(config.application)}`,
+      ...(config.instance !== undefined
+        ? [`    custom string nomos:applicationInstance = ${usdaString(config.instance)}`]
+        : []),
+    ]),
+    "",
+  ].join("\n");
+}
+
+/**
+ * Publish one package root as a real OpenUSD asset. The root references the authored layer stack;
+ * it does not embed a second JSON law or executable application lump.
+ */
+export function packageAssetUsda(input: {
+  readonly packageName: string;
+  readonly packageIdentity: string;
+  readonly domains: readonly string[];
+  readonly root: PackageRootPart;
+  readonly lawAsset: string;
+}): string {
+  safeUsdName(input.root.name, "package root");
+  if (input.root.kind !== "component" && input.root.kind !== "assembly") {
+    throw new Error(`package root '${input.root.name}' must be a component or assembly`);
+  }
+  if (input.domains.length === 0) throw new Error(`package '${input.packageName}' exports no domains`);
+  if (/[@\r\n:]/.test(input.packageName) || /[@\r\n]/.test(input.packageIdentity)) {
+    throw new Error("package name or identity is unsafe for a content-addressed asset identifier");
+  }
+  if (input.lawAsset.length === 0 || /[@\r\n]/.test(input.lawAsset)) throw new Error("package law asset path is unsafe or empty");
+  return [
+    "#usda 1.0",
+    "(",
+    `    defaultPrim = ${usdaString(input.root.name)}`,
+    ")",
+    "",
+    `def Scope ${usdaString(input.root.name)} (`,
+    `    kind = ${usdaString(input.root.kind)}`,
+    `    prepend references = @${input.lawAsset}@</Nomos>`,
+    `    assetInfo = {`,
+    `        asset identifier = @nomos:package:${input.packageName}:${input.packageIdentity}@`,
+    `        string name = ${usdaString(input.packageName)}`,
+    `    }`,
+    `)`,
+    `{`,
+    `    custom string nomos:packageName = ${usdaString(input.packageName)}`,
+    `    custom string[] nomos:domains = ${usdaStringArray(input.domains)}`,
+    `    custom string nomos:rootPart = ${usdaString(input.root.name)}`,
+    `}`,
+    "",
+  ].join("\n");
+}
+
+const isResolverAsset = (asset: string): boolean => /^[A-Za-z][A-Za-z0-9+.-]*:/.test(asset);
+
+function mapArcs(part: ApplicationPart, map: (arc: CompositionArc) => CompositionArc): ApplicationPart {
+  return {
+    ...part,
+    ...(part.reference !== undefined ? { reference: map(part.reference) } : {}),
+    ...(part.payload !== undefined ? { payload: map(part.payload) } : {}),
+    ...(part.children !== undefined ? { children: part.children.map((child) => mapArcs(child, map)) } : {}),
+  };
+}
+
+/** Compile an authoring config into the sole travelling application configuration: USDA. */
+export function compileApplicationComposition(
+  config: ApplicationCompositionConfig,
+  configPath: string,
+  options: { readonly requireUsdcat?: boolean } = {},
+): { readonly outputPath: string; readonly usda: string; readonly referencedAssets: readonly string[] } {
+  const configDir = path.dirname(configPath);
+  const outDir = path.resolve(configDir, config.outDir ?? "build");
+  mkdirSync(outDir, { recursive: true });
+  const outputPath = path.join(outDir, `${config.application}.application.usda`);
+  const referencedAssets = new Set<string>();
+  const validateLocalReferences = (part: ApplicationPart, at: string): void => {
+    const here = `${at}/${part.name}`;
+    if (part.reference !== undefined && !isResolverAsset(part.reference.asset)) {
+      const absolute = path.resolve(configDir, part.reference.asset);
+      if (!existsSync(absolute)) throw new Error(`application asset not found: ${absolute}`);
+      const exported = packageRootOfUsda(absolute);
+      if (!exported.identifier.startsWith("nomos:package:")) {
+        throw new Error(`reference on '${here}' does not resolve to a published Nomos package asset: ${absolute}`);
+      }
+      if (part.reference.prim !== `/${exported.name}`) {
+        throw new Error(`reference on '${here}' asks for '${part.reference.prim}', but '${absolute}' exports '/${exported.name}'`);
+      }
+      if (part.kind !== exported.kind) {
+        throw new Error(`part '${here}' declares kind '${part.kind}', but referenced package root '/${exported.name}' declares kind '${exported.kind}'`);
+      }
+    }
+    for (const child of part.children ?? []) validateLocalReferences(child, here);
+  };
+  validateLocalReferences(config.root, "");
+  const resolved = mapArcs(config.root, (arc) => {
+    if (isResolverAsset(arc.asset)) {
+      throw new Error(`asset resolver cannot yet prove '${arc.asset}' locally; refusing an unresolved application composition`);
+    }
+    const absolute = path.resolve(configDir, arc.asset);
+    if (!existsSync(absolute)) throw new Error(`application asset not found: ${absolute}`);
+    referencedAssets.add(absolute);
+    const relative = path.relative(outDir, absolute).split(path.sep).join("/");
+    return { ...arc, asset: relative.startsWith(".") ? relative : `./${relative}` };
+  });
+  const usda = applicationCompositionUsda({ ...config, root: resolved });
+  const candidatePath = path.join(outDir, `.${config.application}.application.candidate.usda`);
+  writeFileSync(candidatePath, usda, "utf8");
+
+  const usdcat = existsSync("/usr/bin/usdcat") ? "/usr/bin/usdcat" : undefined;
+  try {
+    if (usdcat === undefined && options.requireUsdcat === true) {
+      throw new Error("stock OpenUSD `usdcat` is required but was not found at /usr/bin/usdcat");
+    }
+    if (usdcat !== undefined) {
+      for (const asset of [...referencedAssets].sort()) {
+        execFileSync(usdcat, ["--loadOnly", asset], { stdio: ["ignore", "ignore", "pipe"] });
+      }
+      execFileSync(usdcat, ["--loadOnly", candidatePath], { stdio: ["ignore", "ignore", "pipe"] });
+      execFileSync(usdcat, ["--flatten", candidatePath], { stdio: ["ignore", "ignore", "pipe"] });
+    }
+    renameSync(candidatePath, outputPath);
+  } catch (error) {
+    rmSync(candidatePath, { force: true });
+    throw error;
+  }
+  return { outputPath, usda, referencedAssets: [...referencedAssets].sort() };
+}
+
+export function isApplicationCompositionConfig(value: unknown): value is ApplicationCompositionConfig {
+  if (value === null || typeof value !== "object") return false;
+  const candidate = value as { application?: unknown; root?: unknown };
+  return typeof candidate.application === "string" && candidate.root !== null && typeof candidate.root === "object";
+}
+
+/** Read-only helper used by diagnostics and future asset resolvers. */
+export function packageRootOfUsda(assetPath: string): { readonly name: string; readonly kind: string; readonly identifier: string } {
+  const text = readFileSync(assetPath, "utf8");
+  const name = /defaultPrim\s*=\s*"([A-Za-z_][A-Za-z0-9_]*)"/.exec(text)?.[1];
+  if (name === undefined) throw new Error(`package asset '${assetPath}' has no defaultPrim`);
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const kind = new RegExp(`def\\s+Scope\\s+"${escaped}"\\s*\\([\\s\\S]*?kind\\s*=\\s*"([^"]+)"`).exec(text)?.[1];
+  if (kind === undefined) throw new Error(`package asset '${assetPath}' root '${name}' has no kind`);
+  const identifier = /asset\s+identifier\s*=\s*@([^@]+)@/.exec(text)?.[1];
+  if (identifier === undefined) throw new Error(`package asset '${assetPath}' root '${name}' has no content identifier`);
+  return { name, kind, identifier };
+}

package/src/application_topology.ts

@@ -0,0 +1,151 @@
+import type { DomainModule } from "./codegen_dart.js";
+
+type BusinessBirthMetadata = {
+  readonly aggregateId?: unknown;
+};
+
+type TopologyDirective = DomainModule["directives"][number] & {
+  readonly birthsChild?: unknown;
+  readonly businessBirth?: BusinessBirthMetadata;
+  readonly businessBirthInternal?: unknown;
+};
+
+export interface ApplicationTopology {
+  /** Co-resident business domains bound to the application workspace. */
+  readonly rootDomains: readonly string[];
+  /** Deterministic primary facet for generated narration/scenarios; not a storage-topology choice. */
+  readonly homeDomain: string;
+  readonly homeModule: DomainModule;
+}
+
+const domainOf = (module: DomainModule): string => module.domain ?? module.name;
+
+const publicLanguageOf = (module: DomainModule): readonly TopologyDirective[] =>
+  (module.applicationIntents ?? module.directives)
+    .filter((directive) =>
+      (directive as TopologyDirective).businessBirthInternal !== true,
+    ) as readonly TopologyDirective[];
+
+/**
+ * Resolve which business domains run together in the application workspace.
+ *
+ * This is deliberately inferred from business law rather than configured as a framework topology knob:
+ *
+ * Domains are vocabulary, not storage partitions. They are co-resident by default. A declared
+ * cross-domain business birth is the evidence that its target belongs in a child workspace.
+ *
+ * The primary domain is only a deterministic generated-surface/narration choice: an explicit receiving-group
+ * language wins, then a literal `home`, then declaration order. It does not move the other root domains.
+ */
+export function resolveApplicationTopology(
+  modules: readonly DomainModule[],
+): ApplicationTopology {
+  if (modules.length === 0) {
+    throw new Error("generated application topology has no business domains");
+  }
+
+  const byDomain = new Map<string, DomainModule>();
+  for (const module of modules) {
+    const domain = domainOf(module);
+    if (byDomain.has(domain)) {
+      throw new Error(
+        `generated application topology contains domain '${domain}' more than once`,
+      );
+    }
+    byDomain.set(domain, module);
+  }
+
+  if (modules.length === 1) {
+    const homeModule = modules[0]!;
+    const homeDomain = domainOf(homeModule);
+    return { rootDomains: [homeDomain], homeDomain, homeModule };
+  }
+
+  const declaredReceivingGroups = modules.filter((module) =>
+    publicLanguageOf(module).some((directive) =>
+      directive.id === "nomosInternalBirthReceivingGroup7c1f5e" &&
+      directive.birthsChild === true &&
+      directive.aggregateId === "NomosInternalReceivingGroup7c1f5e",
+    ),
+  );
+  if (declaredReceivingGroups.length > 1) {
+    throw new Error(
+      `generated application topology has more than one receiving-group domain: ${declaredReceivingGroups
+        .map(domainOf)
+        .sort()
+        .join(", ")}. An accountable participant gets one receiving group; keep one group birth language.`,
+    );
+  }
+
+  const aggregateOwners = new Map<string, Set<string>>();
+  for (const module of modules) {
+    const domain = domainOf(module);
+    for (const aggregate of module.aggregates) {
+      const owners = aggregateOwners.get(aggregate.id) ?? new Set<string>();
+      owners.add(domain);
+      aggregateOwners.set(aggregate.id, owners);
+    }
+  }
+
+  const targetedByAnotherDomain = new Set<string>();
+  const childrenByDomain = new Map<string, Set<string>>();
+  const birthSources = new Set<string>();
+  for (const module of modules) {
+    const source = domainOf(module);
+    for (const directive of publicLanguageOf(module)) {
+      const aggregateId = directive.businessBirth?.aggregateId;
+      if (typeof aggregateId !== "string") continue;
+      const owners = aggregateOwners.get(aggregateId);
+      if (owners === undefined || owners.size !== 1) {
+        throw new Error(
+          `generated application topology cannot locate the one domain owning born aggregate ` +
+            `'${aggregateId}' from '${source}/${directive.id}'`,
+        );
+      }
+      const target = [...owners][0]!;
+      birthSources.add(source);
+      if (target !== source) {
+        targetedByAnotherDomain.add(target);
+        const children = childrenByDomain.get(source) ?? new Set<string>();
+        children.add(target);
+        childrenByDomain.set(source, children);
+      }
+    }
+  }
+
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const walk = (domain: string, path: readonly string[]): void => {
+    if (visiting.has(domain)) {
+      throw new Error(
+        `generated application topology contains a cross-workspace birth cycle: ${[...path, domain].join(" -> ")}`,
+      );
+    }
+    if (visited.has(domain)) return;
+    visiting.add(domain);
+    for (const child of childrenByDomain.get(domain) ?? []) walk(child, [...path, domain]);
+    visiting.delete(domain);
+    visited.add(domain);
+  };
+  for (const domain of byDomain.keys()) walk(domain, []);
+
+  const rootModules = modules.filter((module) => !targetedByAnotherDomain.has(domainOf(module)));
+  const rootDomains = rootModules.map(domainOf);
+  if (rootDomains.length === 0) {
+    throw new Error(
+      "Nomos cannot determine an application workspace because every business domain is born by another domain.",
+    );
+  }
+
+  const receivingGroupModule = declaredReceivingGroups[0];
+  if (receivingGroupModule !== undefined && !rootModules.includes(receivingGroupModule)) {
+    throw new Error(
+      `generated application topology places its receiving-group domain '${domainOf(receivingGroupModule)}' inside a child workspace`,
+    );
+  }
+  const homeModule = receivingGroupModule
+    ?? rootModules.find((module) => domainOf(module) === "home")
+    ?? rootModules.find((module) => birthSources.has(domainOf(module)))
+    ?? rootModules[0]!;
+  return { rootDomains, homeDomain: domainOf(homeModule), homeModule };
+}

package/src/attested_core.ts

@@ -341,7 +341,7 @@ export function sourceFrontierId(sourceGenesis: string): string {
  * it); the gate's monotone arm refuses any attestation BEHIND it. Reader-chain state — re-folded
  * at replay, so the predicate is deterministic forever.
  */
-export const NomosSourceFrontier = aggregate("NomosSourceFrontier", {
+export const NomosSourceFrontier = Object.assign(aggregate("NomosSourceFrontier", {
   /** The source workspace name the edge was declared under (routing/diagnostics). */
   source: t.string().merge(Lww),
   /** The highest source signer-epoch an admitted attestation has shown this reader. */
@@ -350,7 +350,7 @@ export const NomosSourceFrontier = aggregate("NomosSourceFrontier", {
   maxAttestedAtSeen: t.int().merge(Lww),
   /** The source head oid at the highest-seen position (diagnostics/audit). */
   headAtMax: t.string().merge(Lww),
-}).public();
+}).public(), { businessBirthInternal: true as const });
 
 
 // ── the ensure() hook — breaks the read.ts → authoring.ts module-init cycle ────────────────────

package/src/authoring_context.ts

@@ -0,0 +1,9 @@
+// NOMOS — internal compile boundary. This identifier is replaced with the literal `true` only
+// while building the executable law. Ordinary tenant-domain imports leave it undefined, so every
+// declaration-time validation still runs in Node and fails beside the code that caused it.
+declare const __nmsRuntimeLaw: boolean | undefined;
+
+/** True only inside compiler-emitted executable law, never in tenant authoring code. */
+export function isRuntimeLaw(): boolean {
+  return typeof __nmsRuntimeLaw !== "undefined" && __nmsRuntimeLaw === true;
+}

package/src/birth_meter_ensure.ts

@@ -76,7 +76,7 @@ const bornFounderSignerWriteOnce = workspaceInvariant("FounderSignerWriteOnce")
     refAs(
       "tuple",
       "RelationTuple",
-      "pre:" + relationTupleInstanceId(signerObject(String((ctx.intent ?? {}).principal ?? "")), "signer"),
+      "pre:" + relationTupleInstanceId(signerObject(String(ctx.principal ?? "")), "signer"),
     ),
   ])
   .assert(({ tuple }, ctx) => {

package/src/births.ts

@@ -6,6 +6,7 @@
 import { z } from "zod";
 import type { AggregateHandle } from "./aggregate.js";
 import type { AggregateRef } from "./authoring.js";
+import type { Ports } from "./ctx.js";
 import type { Field, FieldValue } from "./fields.js";
 
 /**
@@ -72,15 +73,23 @@ export interface BusinessBirthDecl<
 > {
   readonly __isBusinessBirth: true;
   readonly aggregate: AggregateHandle<string, F>;
-  readonly payloadSchema: z.ZodObject<z.ZodRawShape>;
+  readonly payloadSchema: z.ZodObject<z.ZodRawShape> & z.ZodType<P>;
   /** A stable business key the caller already knows (an estate reference, account number, etc.). */
   readonly key: (payload: P) => string;
   /** The declared business fact used by {@link key}; retained for generated clients to pre-address custody. */
   readonly keyField: string;
   /** Framework-derived initial authoring. Tenant code marks aggregate fields `.fromBirth()` instead. */
-  readonly plan: (root: AggregateRef<F>, payload: P) => unknown;
+  readonly plan: (root: AggregateRef<F>, payload: P, ctx: Ports) => unknown;
+  /** Business roles the founder holds from the first valid state. Nomos seats them inside genesis. */
+  readonly founderRoles: readonly string[];
+  /** The business noun those founder roles govern. */
+  readonly founderScope: string;
   /** Optional business noun used only to make the durable address readable. Defaults to the aggregate id. */
   readonly namespace?: string;
+  /** Owning business domain, needed only when another domain composes this birth into a wider intent. */
+  readonly domain?: string;
+  /** Name the owning business domain once so other intents can compose this birth without a raw recipe. */
+  readonly inDomain: (domain: string) => BusinessBirthDecl<P, F>;
 }
 
 export type BirthFactKeys<F extends Record<string, Field>> = {
@@ -99,6 +108,18 @@ export interface BusinessBirthSpec<F extends Record<string, Field>> {
   /** One declared birth fact that gives this business life its stable address. */
   readonly key: BirthStringFactKeys<F>;
   readonly namespace?: string;
+  /** Business policy: roles held by the founder from the aggregate's first valid state. */
+  readonly founder?: {
+    readonly roles: readonly string[];
+    /** Business noun governed by those roles. Defaults to the born aggregate noun. */
+    readonly scope?: string;
+  };
+  /** Additional atomic business initialization which belongs to the same birth. */
+  readonly initialise?: (
+    root: AggregateRef<F>,
+    payload: BusinessBirthPayload<F>,
+    ctx: Ports,
+  ) => unknown;
 }
 
 /** @internal Record an already-lowered child recipe during a framework directive plan. Application law
@@ -137,19 +158,46 @@ export function birth<F extends Record<string, Field>>(
       );
     }
     const payloadSchema = z.object(Object.fromEntries(facts.map(([name, field]) => [name, field.zod])));
+    const founderRoles = [...new Set(spec.founder?.roles ?? [])];
+    for (const role of founderRoles) {
+      if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(role)) {
+        throw new Error(
+          `birth(${aggregate.id}): founder role '${role}' is not a business role name`,
+        );
+      }
+    }
+    const founderScope = (spec.founder?.scope ?? aggregate.id)
+      .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+      .toLowerCase();
+    if (!/^[a-z][a-z0-9-]*$/.test(founderScope)) {
+      throw new Error(
+        `birth(${aggregate.id}): founder scope '${founderScope}' is not a business noun`,
+      );
+    }
     type Payload = BusinessBirthPayload<F>;
-    return {
+    const declaration = {
       __isBusinessBirth: true,
       aggregate,
       payloadSchema,
       key: (payload: Payload) => String(payload[spec.key]),
       keyField: spec.key,
-      plan: (root: AggregateRef<F>, payload: Payload) => {
+      plan: (root: AggregateRef<F>, payload: Payload, ctx: Ports) => {
         const writable = root as unknown as { set(field: string, value: unknown): unknown };
         for (const [name] of facts) writable.set(name, payload[name as keyof Payload]);
+        return spec.initialise?.(root, payload, ctx);
       },
+      founderRoles,
+      founderScope,
       ...(spec.namespace !== undefined ? { namespace: spec.namespace } : {}),
-    } as BusinessBirthDecl<Payload, F>;
+    };
+    const inDomain = (domain: string): BusinessBirthDecl<Payload, F> => {
+      const name = domain.trim();
+      if (!/^[a-z][a-z0-9_-]*$/.test(name)) {
+        throw new Error(`birth(${aggregate.id}).inDomain(...): '${domain}' is not a business domain name`);
+      }
+      return { ...declaration, domain: name, inDomain } as unknown as BusinessBirthDecl<Payload, F>;
+    };
+    return { ...declaration, inDomain } as unknown as BusinessBirthDecl<Payload, F>;
   }
   footprint.push(recipeOrAggregate as BirthRecipe);
 }