@githolon/dsl 0.113.4 → 0.115.0

package/src/composed_wire_identity.ts

@@ -0,0 +1,24 @@
+// NOMOS — The wire identity of an operation field under OpenUSD composition.
+//
+// Node-free on purpose: the compatibility graph reaches this from the law bundle (the release law's
+// plans bundle for a neutral platform), where `codegen_call_proto.ts` cannot live (it mints stable
+// ids through `node:crypto`). Both the generated codecs and the compatibility requirement derive a
+// nested member's allocation here, so the two can never disagree (CAP-681).
+
+/**
+ * OpenUSD composition may share structurally identical anonymous records between
+ * operation contracts. `compileSparseLawGraphUsda` records that sharing by
+ * redirecting each duplicate field path to the canonical field prim. The wire
+ * identity must follow that composed path too; using the duplicate graph-local
+ * SID makes generated clients speak a different Protobuf schema from the law the
+ * kernel actually installs.
+ */
+export function composedWireIdentity(
+  paths: ReadonlyMap<string, string>,
+  entity: { readonly id: string; readonly sid: string; readonly wireKey?: string },
+): string {
+  if (entity.wireKey !== undefined) return entity.wireKey;
+  const path = paths.get(entity.id);
+  const canonical = path?.match(/\/(?:Fields\/f_|Variants\/v_)([0-9a-f]{16})$/i)?.[1];
+  return canonical ?? entity.sid;
+}

package/src/directive.ts

@@ -536,6 +536,12 @@ export interface Directive<P = unknown> extends AuthenticatedMember {
    * `attestationAuthorizedGate`/`.attestationAuthorized()` naming convention; the declaration is the noun.)
    */
   readonly birthsChild?: boolean;
+  /** THE TYPED BIRTH KEY of a business birth (`birth(Aggregate, spec)`): the key's typed-id family, brand and
+   * the name's namespace. Lowered to the `nomos:birthKeyType` / `nomos:birthKeyBrand` /
+   * `nomos:birthKeyNamespace` era keys on the birthing intent; the kernel then requires every carried recipe
+   * of this intent to carry `nomos:birthKey`, checks its shape, and re-derives the child's name from it.
+   * Absent on every other directive (and on all historical law), so those chains replay unchanged. */
+  readonly birthKey?: import("./births.js").BirthKeyDeclaration;
   /** Additional ordinary offers which the born workspace's typed law requires in genesis.
    * This is compiler/runtime metadata attached only to a birthing directive. It contains no
    * payload or fallback value: the kernel checks that the re-derived recipe invokes each named

package/src/domain_requirements.ts

@@ -0,0 +1,75 @@
+/**
+ * PER-DOMAIN UNIT REQUIREMENTS (CAP-666): what a generated client pins beside the unit set.
+ *
+ * An application is compiled against one law, named by its unit set (CAP-773). That one identity is
+ * what a workspace serves as a whole, so an app pinned to it alone goes stale the moment a rollout moves
+ * a domain the app never touches. Each application domain has its own unit in `build/<name>.units`
+ * (`domain:<key>`) and its own slice of the generated compatibility requirement
+ * (`<name>.compatibility.usda`, the `NomosCompatibilityDomain` the kernel's Compatibility Desk judges).
+ * This module names both per domain key, from the same in-memory units and interfaces the compiler
+ * just emitted, so the generated Dart/TS clients, `NomosApprovedModel`, the model-adoption desk and the
+ * client inventory all carry one contract per domain and never infer it from installed law.
+ *
+ * Era rule: the requirement is derived from existing artifacts and written into no law, unit or
+ * package. Unchanged law keeps every identity it had; only the generated client gains the table.
+ */
+import { emitApplicationCompatibilityUsda } from "./compatibility_usda.js";
+import type { DomainInterface } from "./compatibility_graph.js";
+import type { LawUnit } from "./law_units.js";
+
+export interface DomainUnitRequirement {
+  /** The application domain key. */
+  readonly domainKey: string;
+  /** The hash of its law unit (`domain:<key>` in the unit set), 64 lowercase hex. */
+  readonly unitSha256: string;
+  /** sha256 of the domain's own compatibility requirement USDA (the one-domain `emitApplicationCompatibilityUsda`). */
+  readonly requirementSha256: string;
+}
+
+const HEX64 = /^[0-9a-f]{64}$/;
+
+/** The USDA requirement for exactly one domain: the slice a client carries and the kernel judges. */
+export function domainRequirementUsda(domainKey: string, domainInterface: DomainInterface): string {
+  return emitApplicationCompatibilityUsda({ [domainKey]: domainInterface });
+}
+
+/**
+ * One requirement per application domain the package exposes an interface for, sorted by domain key. A
+ * domain unit without an interface (a private or framework domain) names no requirement and is omitted;
+ * an interface whose domain has no unit is a compiler defect and refuses.
+ */
+export function domainRequirementsOf(
+  units: readonly Pick<LawUnit, "key" | "kind" | "domain" | "hash">[],
+  interfaces: Readonly<Record<string, DomainInterface>>,
+  sha256Hex: (utf8: string) => string,
+): DomainUnitRequirement[] {
+  const unitByDomain = new Map<string, string>();
+  for (const unit of units) {
+    if (unit.kind === "domain" && unit.domain !== undefined) unitByDomain.set(unit.domain, unit.hash);
+  }
+  return Object.keys(interfaces).sort().map((domainKey) => {
+    const unitSha256 = unitByDomain.get(domainKey);
+    if (unitSha256 === undefined) {
+      throw new Error(`domain requirements: '${domainKey}' has a compatibility interface but no law unit; the unit split and the interface disagree`);
+    }
+    const requirementSha256 = sha256Hex(domainRequirementUsda(domainKey, interfaces[domainKey]!));
+    for (const [name, value] of [["unit", unitSha256], ["requirement", requirementSha256]] as const) {
+      if (!HEX64.test(value)) throw new Error(`domain requirements: '${domainKey}' ${name} identity must be 64 lowercase hex, not '${value}'`);
+    }
+    return { domainKey, unitSha256, requirementSha256 };
+  });
+}
+
+/** Refuse a hand-supplied table that is not what the compiler would emit (generators take it as an input). */
+export function assertDomainRequirements(requirements: readonly DomainUnitRequirement[]): void {
+  const seen = new Set<string>();
+  for (const requirement of requirements) {
+    if (!requirement.domainKey || seen.has(requirement.domainKey)) {
+      throw new Error(`domain requirements: '${requirement.domainKey}' is empty or named twice`);
+    }
+    seen.add(requirement.domainKey);
+    for (const [name, value] of [["unit", requirement.unitSha256], ["requirement", requirement.requirementSha256]] as const) {
+      if (!HEX64.test(value)) throw new Error(`domain requirements: '${requirement.domainKey}' ${name} identity must be 64 lowercase hex, not '${value}'`);
+    }
+  }
+}

package/src/engine_entry.ts

@@ -73,7 +73,6 @@ import {
   nomosSourceFrontierEnsure,
   withAttestedReadExports,
 } from "./attested.js";
-import type { OpenApiDoc } from "./codegen_openapi.js";
 import type { Directive } from "./directive.js";
 import type { AggregateHandle, AggregateInvariantFn, AggregateInvariantVerdict } from "./aggregate.js";
 import type { Ports } from "./ctx.js";
@@ -178,18 +177,6 @@ export interface EngineEntryConfig {
    * `sideEffects: false` (a bare side-effect import would be tree-shaken away).
    */
   readonly seeds?: readonly unknown[];
-  /**
-   * Compiler-derived self-description. It is a presentation projection held inside the separately
-   * routed `describe` plan, never executable law IR. Ordinary offer/read plans omit it completely,
-   * so OpenAPI/JSON-Schema generation cannot sit on their parse or readiness flame path.
-   */
-  readonly openapiDocument?: OpenApiDoc;
-  /**
-   * The package's OpenAPI document title (the compiler's `"<name> (nomos package)"`). Baked into
-   * the lump so `describe` reproduces the compiler's public description byte-for-byte without
-   * the kernel knowing the package name. The kernel MAY override it (the workspace-level title).
-   */
-  readonly packageTitle?: string;
   /** Compiler-generated nominal encoders keyed by the exact target Directive singleton. Source law
    * can name a target by type, while the runtime emits only canonical USDA. */
   readonly workspaceEffectTargets?: readonly {
@@ -297,7 +284,7 @@ function mergeModules(mods: readonly DomainModuleExports[], domain: string): Dom
   // without per-piece re-exports (capability_exports.ts).
   // METERED BIRTH: a `.births()`-declaring domain gains the birth-meter structural exports
   // (the sanctioning `nomosBirthRecordEnsure` + the meter aggregates) at this same seam, so
-  // the registry + `describe()` see the exact surface the composed manifest carries.
+  // the registry sees the exact surface the composed manifest carries.
   // ROLE SUGAR: lift every `role(...).emit()` into its grant/revoke/seed directives at the SAME
   // engine merge point so the registry dispatches them (the compiler saw them via the same expander).
   return expandRoleExports(
@@ -650,8 +637,6 @@ export interface RegisteredEngine {
   prepareDomain(domain: string): { complete: boolean; initialized: number; total: number };
   /** Compiler/tooling probe: force one domain and prove an exact routed offer is registered. */
   hasDirective(domain: string, directiveId: string): boolean;
-  /** The G1 self-describe verb: the lump's own merged OpenAPI, derived from its modules. */
-  describe(opts?: { lawHash?: string; title?: string }): OpenApiDoc;
 }
 
 /**
@@ -1155,42 +1140,13 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     };
   }
 
-  /**
-   * THE SELF-DESCRIBE VERB (G1) — the lump's OWN OpenAPI, derived from the SAME modules it
-   * dispatches. The kernel selects the content-addressed describe plan from the native USD
-   * package in custody, so the workspace's API surface is a pure,
-   * deterministic function of installed law — NOT a host-staged blob. Its public `paths` reproduce
-   * the public description the compiler derived; describe also carries a private, law-derived
-   * framework routing manifest which the host consumes internally and never publishes.
-   * `opts.lawHash`/`opts.title` are injected by the kernel at describe-time (the version stamp +
-   * package title), matching the compiler's `domainHash`/`"<name> (nomos package)"`.
-   */
-  function describe(opts?: { lawHash?: string; title?: string }): OpenApiDoc {
-    const document = config.openapiDocument;
-    if (document === undefined) {
-      throw new Error("engine describe: selected plan has no compiled OpenAPI projection");
-    }
-    const lawHash = opts?.lawHash;
-    const title = opts?.title ?? config.packageTitle ?? document.info["title"];
-    const priorInfo = document.info;
-    const info: Record<string, unknown> = {
-      ...priorInfo,
-      ...(title === undefined ? {} : { title }),
-      version: lawHash === undefined ? (priorInfo["version"] ?? "0") : lawHash.slice(0, 12),
-    };
-    if (lawHash === undefined) delete info["x-nomos-law-hash"];
-    else info["x-nomos-law-hash"] = lawHash;
-    return { ...document, info };
-  }
-
   // The engine evals the bundle as a classic script and FREEZES globalThis before
-  // dispatch — assign all entries NOW, at top-level eval. `describe` is the G1 self-
-  // describe verb (the kernel `describe` run mode evals `globalThis.describe(opts)`).
+  // dispatch — assign all entries NOW, at top-level eval. There is no `describe` entry: the
+  // kernel derives a workspace's description from its installed law (CAP-658).
   (globalThis as { plan?: unknown }).plan = plan;
   (globalThis as { planReport?: unknown }).planReport = planReport;
   (globalThis as { __nomosPrepareDomain?: unknown }).__nomosPrepareDomain = prepareDomain;
   (globalThis as { __nomosHasDirective?: unknown }).__nomosHasDirective = hasDirective;
-  (globalThis as { describe?: unknown }).describe = describe;
 
-  return { plan, planReport, prepareDomain, hasDirective, describe } as RegisteredEngine;
+  return { plan, planReport, prepareDomain, hasDirective } as RegisteredEngine;
 }

package/src/engine_javascript.ts

@@ -2,21 +2,27 @@
  * Canonicalise esbuild's non-semantic install-topology noise before the executable law is hashed.
  *
  * A workspace dependency is labelled `../../dsl/src/...`; the same published dependency is labelled
- * `node_modules/@githolon/dsl/src/...`. Esbuild can also leave either one or two newlines after its
+ * `node_modules/@githolon/dsl/src/...`. A dependency reached through a symlinked `node_modules` (a git
+ * worktree links the main checkout's) is labelled by its real path, climbing out and back down through
+ * another directory: `../../../../platform/nomos2/node_modules/zod/...`. Everything up to the last
+ * `node_modules/` in an esbuild label describes the install, never the law. Esbuild can also leave either one or two newlines after its
  * `"use strict"` prologue. None of those bytes describe business law, so they must not give the same
  * law two identities.
  *
  * Replacements are deliberately restricted to esbuild's generated comment/function labels. Tenant
  * strings and executable imports remain byte-significant.
  */
+/** An esbuild label's install prefix: an optional climb (`../`), any directories, then `node_modules/`. */
+const INSTALLED = String.raw`(?:(?:\.\.\/)+(?:[^\s"/]+\/)*?)?node_modules\/`;
+
 export function canonicalizeEngineJavascript(source: string): string {
   const body = source
     .replace(/\r\n?/g, "\n")
     .replace(/^[ \t]*"use strict";[ \t]*(?:\n|$)/gm, "")
-    .replace(/^(\s*\/\/ )(?:(?:\.\.\/)+dsl\/src\/|node_modules\/@githolon\/dsl\/src\/)/gm, "$1@githolon/dsl/src/")
-    .replace(/"(?:(?:\.\.\/)+dsl\/src\/|node_modules\/@githolon\/dsl\/src\/)([^"]+)"\(\) \{/g, '"@githolon/dsl/src/$1"() {')
-    .replace(/^(\s*\/\/ )(?:(?:\.\.\/)+node_modules\/zod\/|node_modules\/zod\/)/gm, "$1zod/")
-    .replace(/"(?:(?:\.\.\/)+node_modules\/zod\/|node_modules\/zod\/)([^"]+)"\(\) \{/g, '"zod/$1"() {')
+    .replace(new RegExp(`^(\\s*\\/\\/ )(?:(?:\\.\\.\\/)+dsl\\/src\\/|${INSTALLED}@githolon\\/dsl\\/src\\/)`, "gm"), "$1@githolon/dsl/src/")
+    .replace(new RegExp(`"(?:(?:\\.\\.\\/)+dsl\\/src\\/|${INSTALLED}@githolon\\/dsl\\/src\\/)([^"]+)"\\(\\) \\{`, "g"), '"@githolon/dsl/src/$1"() {')
+    .replace(new RegExp(`^(\\s*\\/\\/ )${INSTALLED}zod\\/`, "gm"), "$1zod/")
+    .replace(new RegExp(`"${INSTALLED}zod\\/([^"]+)"\\(\\) \\{`, "g"), '"zod/$1"() {')
     .replace(/\n[ \t]*\n/g, "\n")
     .trim();
   return `"use strict";\n${body}\n`;
@@ -25,7 +31,7 @@ export function canonicalizeEngineJavascript(source: string): string {
 /** Remove the same install-topology label from the sealed generated application bundle. */
 export function canonicalizeGeneratedClientJavascript(source: string): string {
   return source.replace(
-    /^(\s*\/\/ )(?:(?:\.\.\/)+dsl\/runtime\/|node_modules\/@githolon\/dsl\/runtime\/)/gm,
+    new RegExp(`^(\\s*\\/\\/ )(?:(?:\\.\\.\\/)+dsl\\/runtime\\/|${INSTALLED}@githolon\\/dsl\\/runtime\\/)`, "gm"),
     "$1@githolon/dsl/runtime/",
   );
 }

package/src/fields.ts

@@ -243,6 +243,97 @@ export function isGitObjectIdSchema(schema: z.ZodTypeAny): boolean {
   return false;
 }
 
+// ── TYPED IDS (aggregate fields) ─────────────────────────────────────────────────────────────────────
+// An identifier is never a plain string. `t.brandedId(Name)` and `t.uuid()` are the aggregate-field forms of
+// the payload-side `brandedId(...)` schema: wire-identical to a string, nominal at compile time (a plain
+// `string` is not assignable), and recognised by codegen, which emits the branded type in both generated
+// clients. `t.ref(Aggregate)` is the aggregate-field form of `idOf(Aggregate)`. A birth key MUST be one of
+// these (see `births.ts`).
+
+declare const NOMOS_TYPED_ID: unique symbol;
+/** A nominal id: a string at run time and on the wire, a distinct type per `Brand` at compile time. */
+export type TypedId<Brand extends string> = string & { readonly [NOMOS_TYPED_ID]: Brand };
+/** The brand a `t.uuid()` field carries. */
+export type Uuid = TypedId<"Uuid">;
+
+/** The same global symbol `value_object.ts` stamps on `brandedId(...)` payload schemas (kept as `Symbol.for`
+ * here because value_object.ts imports this module). */
+const BRANDED_ID_SYMBOL: unique symbol = Symbol.for("nomos.brandedId") as never;
+/** Marks a `t.uuid()` schema, so a birth key can be classified as a uuid without reading names. */
+export const NOMOS_UUID_BRAND: unique symbol = Symbol.for("nomos.uuid");
+
+const TYPED_ID_BRAND_RE = /^[A-Z][A-Za-z0-9_]*$/;
+/** Canonical lowercase RFC 9562 text form (any version) — the one spelling a `t.uuid()` admits. */
+export const CANONICAL_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The longest id (UTF-8 bytes) a typed id admits — mirrored by the kernel's birth-key shape check. */
+export const TYPED_ID_MAX_BYTES = 256;
+
+/** Why `value` is not a well-formed typed id value (`undefined` when it is). One rule set, mirrored by
+ * the kernel (`kernel/src/birth_stage.rs` `typed_birth_key_refusal`): a non-empty string of at most
+ * {@link TYPED_ID_MAX_BYTES} UTF-8 bytes with no control character (U+0000–U+001F, U+007F — which also keeps
+ * the unit separator that delimits `(namespace, key)` out of every key). */
+export function typedIdShapeRefusal(value: unknown): string | undefined {
+  if (typeof value !== "string") return `an id is a string; got ${value === null ? "null" : typeof value}`;
+  if (value.length === 0) return "an id is non-empty";
+  if (utf8ByteLength(value) > TYPED_ID_MAX_BYTES) {
+    return `an id is at most ${TYPED_ID_MAX_BYTES} UTF-8 bytes`;
+  }
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(value)) return "an id carries no control character";
+  return undefined;
+}
+
+/** UTF-8 length of a JS string, counted by code point. The sealed engine (QuickJS) has no TextEncoder, and
+ * this rule runs inside law plans and payload validation there. A lone surrogate counts 3 bytes (U+FFFD). */
+function utf8ByteLength(value: string): number {
+  let bytes = 0;
+  for (const char of value) {
+    const code = char.codePointAt(0)!;
+    bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+  }
+  return bytes;
+}
+
+function typedIdSchema(): z.ZodString {
+  return z.string().superRefine((value, ctx) => {
+    const refusal = typedIdShapeRefusal(value);
+    if (refusal !== undefined) ctx.addIssue({ code: "custom", message: refusal });
+  });
+}
+
+/**
+ * Make a typed id VALUE of `brand` from its wire text, checking the shared shape. This is the one
+ * sanctioned door from text to an id (a constant the law owns, a value read off another system); a
+ * `"Uuid"` brand also requires the canonical uuid spelling. Never cast a string to {@link TypedId}.
+ */
+export function typedId<const Brand extends string>(brand: Brand, value: string): TypedId<Brand> {
+  if (!TYPED_ID_BRAND_RE.test(brand)) {
+    throw new Error(`typedId: '${brand}' must be a capitalized identifier (the brand's type name)`);
+  }
+  const refusal = typedIdShapeRefusal(value);
+  if (refusal !== undefined) throw new Error(`typedId(${brand}): ${refusal}`);
+  if (brand === "Uuid" && !CANONICAL_UUID_RE.test(value)) {
+    throw new Error("typedId(Uuid): expected a canonical lowercase uuid");
+  }
+  return value as TypedId<Brand>;
+}
+
+/** Whether a schema is a `t.uuid()` id (through omission/null wrappers). */
+export function isUuidIdSchema(schema: z.ZodTypeAny): boolean {
+  let current: z.ZodTypeAny | undefined = schema;
+  for (let hops = 0; current !== undefined && hops < 16; hops++) {
+    if ((current as unknown as Record<symbol, unknown>)[NOMOS_UUID_BRAND] === true) return true;
+    const raw = current as unknown as {
+      _def?: { type?: unknown; innerType?: z.ZodTypeAny };
+      def?: { type?: unknown; innerType?: z.ZodTypeAny };
+    };
+    const def = raw._def ?? raw.def;
+    if (def?.type !== "optional" && def?.type !== "default" && def?.type !== "nullable") return false;
+    current = def.innerType;
+  }
+  return false;
+}
+
 export const nomosRefValueSchema: z.ZodType<NomosRefValue> = z.object({
   workspace: z.string().min(1),
   type: z.string().min(1),
@@ -1107,6 +1198,24 @@ export const t = {
   gitObjectId(): Field<GitObjectId, "string"> {
     return makeField<GitObjectId, "string">("string", gitObjectId(), FirstWriterWins);
   },
+  /** A NOMINAL id field: `estateId: t.brandedId("EstateId")`. Wire-identical to a string; the DSL value
+   * type is {@link TypedId}`<Name>` (a plain string is a compile error) and both generated clients emit
+   * the branded `Name` type. Values come from a payload of the same brand or {@link typedId}. */
+  brandedId<const Name extends string>(name: Name): Field<TypedId<Name>, "string"> {
+    if (!TYPED_ID_BRAND_RE.test(name)) {
+      throw new Error(`t.brandedId: '${name}' must be a capitalized identifier — it becomes the generated type's name.`);
+    }
+    const schema = typedIdSchema();
+    Object.defineProperty(schema, BRANDED_ID_SYMBOL, { value: name, enumerable: false });
+    return makeField<TypedId<Name>, "string">("string", schema as unknown as z.ZodType<TypedId<Name>>, FirstWriterWins);
+  },
+  /** A uuid id field in its canonical lowercase spelling. Generated clients emit the branded `Uuid`. */
+  uuid(): Field<Uuid, "string"> {
+    const schema = z.string().regex(CANONICAL_UUID_RE, "expected a canonical lowercase uuid");
+    Object.defineProperty(schema, BRANDED_ID_SYMBOL, { value: "Uuid", enumerable: false });
+    Object.defineProperty(schema, NOMOS_UUID_BRAND, { value: true, enumerable: false });
+    return makeField<Uuid, "string">("string", schema as unknown as z.ZodType<Uuid>, FirstWriterWins);
+  },
   int(rules: IntRules = {}): Field<number, "int"> {
     for (const [name, value] of [["minimum", rules.minimum], ["maximum", rules.maximum]] as const) {
       if (value !== undefined && !Number.isSafeInteger(value)) {

package/src/identity_usda.ts

@@ -180,11 +180,13 @@ function emitValue(value: PlainValue, primName: string, indent: number, key?: st
 // general USD parser: it reads `def Scope "<name>" { … }` nesting and `custom uniform <type>
 // nomos:<attr> = <literal>` attributes, which is all this layer ever contains.
 
-interface Prim {
+/** One prim of the exact typed subset this module writes (also the baseline artifact's host format). */
+export interface IdentityPrim {
   readonly name: string;
   readonly attrs: Record<string, unknown>;
-  readonly children: Prim[];
+  readonly children: IdentityPrim[];
 }
+type Prim = IdentityPrim;
 
 // Attributes are written bare when the `NomosEntity` schema declares their type, and with
 // `custom uniform` only where a prim carries something the schema does not describe.
@@ -437,9 +439,14 @@ function readEntityForest(
   }
 }
 
-/** Render the committed identity layer. Deterministic: every map is emitted in sorted key order. */
-export function serializeIdentityUsda(lock: CompilerIdentityModel): string {
+/**
+ * Render the identity scopes (`Entities`, `ValueContracts`, `Domains`) at `indent`. The committed
+ * identity layer hosts them under `NomosIdentity`; a released baseline (baseline_usda.ts) hosts the
+ * same scopes under its own root so continuity has exactly one encoding.
+ */
+export function renderIdentityScopes(lock: CompilerIdentityModel, indent: number): string[] {
   if (lock.identity !== undefined) validateLawIdentityRegistry(lock.identity);
+  const p = pad(indent);
   const entities = Object.entries(lock.identity?.entities ?? {}).sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0));
   const domains = Object.entries(lock.domains).sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0));
   const contracts = new Map<string, unknown>();
@@ -456,7 +463,45 @@ export function serializeIdentityUsda(lock: CompilerIdentityModel): string {
       renderedContracts.set(field.contract, rendered);
     }
   }
+  return [
+    `${p}def Scope "Entities"`,
+    `${p}{`,
+    ...emitEntityForest(Object.fromEntries(entities), indent + 4),
+    `${p}}`,
+    `${p}def Scope "ValueContracts"`,
+    `${p}{`,
+    ...[...contracts.entries()].sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0)).flatMap(([identity, shape]) => [
+      `${p}    def Scope ${quote(`c_${identity}`)}`,
+      `${p}    {`,
+      ...emitValue(shape, "Shape", indent + 8),
+      `${p}    }`,
+    ]),
+    `${p}}`,
+    `${p}def Scope "Domains"`,
+    `${p}{`,
+    ...domains.flatMap(([name, domain]) => {
+      const aggregates = Object.entries(domain.stableIds.aggregates).sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0));
+      return [
+        `${p}    def Scope ${quote(`d_${domain.stableIds.domain}`)}`,
+        `${p}    {`,
+        `${p}        custom uniform string nomos:name = ${quote(name)}`,
+        `${p}        custom uniform string nomos:sid = ${quote(domain.stableIds.domain)}`,
+        ...(domain.schemas === undefined ? [] : emitValue(domain.schemas, "Schemas", indent + 8)),
+        ...(aggregates.length === 0 ? [] : [
+          `${p}        def Scope "Aggregates"`,
+          `${p}        {`,
+          ...aggregates.flatMap(([label, aggregate]) => emitAggregate(label, aggregate, indent + 12)),
+          `${p}        }`,
+        ]),
+        `${p}    }`,
+      ];
+    }),
+    `${p}}`,
+  ];
+}
 
+/** Render the committed identity layer. Deterministic: every map is emitted in sorted key order. */
+export function serializeIdentityUsda(lock: CompilerIdentityModel): string {
   return [
     "#usda 1.0",
     "(",
@@ -470,65 +515,30 @@ export function serializeIdentityUsda(lock: CompilerIdentityModel): string {
     "",
     'def Scope "NomosIdentity"',
     "{",
-    '    def Scope "Entities"',
-    "    {",
-    ...emitEntityForest(Object.fromEntries(entities), 8),
-    "    }",
-    '    def Scope "ValueContracts"',
-    "    {",
-    ...[...contracts.entries()].sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0)).flatMap(([identity, shape]) => [
-      `        def Scope ${quote(`c_${identity}`)}`,
-      "        {",
-      ...emitValue(shape, "Shape", 12),
-      "        }",
-    ]),
-    "    }",
-    '    def Scope "Domains"',
-    "    {",
-    ...domains.flatMap(([name, domain]) => {
-      const aggregates = Object.entries(domain.stableIds.aggregates).sort(([l], [r]) => (l < r ? -1 : l > r ? 1 : 0));
-      return [
-        `        def Scope ${quote(`d_${domain.stableIds.domain}`)}`,
-        "        {",
-        `            custom uniform string nomos:name = ${quote(name)}`,
-        `            custom uniform string nomos:sid = ${quote(domain.stableIds.domain)}`,
-        ...(domain.schemas === undefined ? [] : emitValue(domain.schemas, "Schemas", 12)),
-        ...(aggregates.length === 0 ? [] : [
-          '            def Scope "Aggregates"',
-          "            {",
-          ...aggregates.flatMap(([label, aggregate]) => emitAggregate(label, aggregate, 16)),
-          "            }",
-        ]),
-        "        }",
-      ];
-    }),
-    "    }",
+    ...renderIdentityScopes(lock, 4),
     "}",
     "",
   ].join("\n");
 }
 
-/** Read the committed identity layer back into the compiler's in-memory lock model. */
-export function parseIdentityUsda(text: string): CompilerIdentityModel {
-  if (!text.startsWith("#usda")) {
-    throw new Error(`${NOMOS_IDENTITY_FILENAME} is not a USDA layer`);
-  }
-  if (!text.includes(NOMOS_IDENTITY_LAYER_FORMAT)) {
-    throw new Error(
-      `${NOMOS_IDENTITY_FILENAME} is not ${NOMOS_IDENTITY_LAYER_FORMAT} — refusing to guess an identity encoding`,
-    );
-  }
+/** The `NomosEntity` schema block a layer hosting identity scopes declares once at its top. */
+export const NOMOS_IDENTITY_ENTITY_SCHEMA = NOMOS_ENTITY_SCHEMA;
+
+/** Read the root prims of a layer written in this module's typed subset. */
+export function parseIdentityPrims(text: string, filename: string = NOMOS_IDENTITY_FILENAME): IdentityPrim[] {
   const roots: Prim[] = [];
   // Skip the layer header before scanning. `customLayerData = { … }` closes with a braced line of
   // its own, which the prim reader would otherwise treat as the end of the enclosing scope and stop
   // before reaching the first prim. Root prims sit at column 0, so that is where parsing starts.
   const lines = text.split(/\r?\n/);
   const firstPrim = lines.findIndex((line) => /^def\s+Scope\s/.test(line));
-  if (firstPrim === -1) throw new Error(`${NOMOS_IDENTITY_FILENAME} has no NomosIdentity prim`);
+  if (firstPrim === -1) throw new Error(`${filename} has no root prim`);
   parsePrims(lines.slice(firstPrim), 0, roots);
-  const root = roots.find((prim) => prim.name === "NomosIdentity");
-  if (root === undefined) throw new Error(`${NOMOS_IDENTITY_FILENAME} has no NomosIdentity prim`);
+  return roots;
+}
 
+/** Read identity scopes (`Entities`, `ValueContracts`, `Domains`) hosted under `root`. */
+export function readIdentityScopes(root: IdentityPrim, filename: string = NOMOS_IDENTITY_FILENAME): CompilerIdentityModel {
   const entities: Record<string, LawIdentityEntity> = {};
   readEntityForest(childNamed(root, "Entities")?.children ?? [], undefined, entities);
   const identity: LawIdentityRegistry = { v: 1, entities };
@@ -538,7 +548,7 @@ export function parseIdentityUsda(text: string): CompilerIdentityModel {
   for (const prim of childNamed(root, "ValueContracts")?.children ?? []) {
     const identity = prim.name.replace(/^c_/u, "");
     const shape = childNamed(prim, "Shape");
-    if (!identity || shape === undefined) throw new Error(`${NOMOS_IDENTITY_FILENAME} has an invalid value-contract prim ${prim.name}`);
+    if (!identity || shape === undefined) throw new Error(`${filename} has an invalid value-contract prim ${prim.name}`);
     contracts.set(identity, readValue(shape));
   }
 
@@ -569,6 +579,22 @@ export function parseIdentityUsda(text: string): CompilerIdentityModel {
   return { v: 1, domains, ...(Object.keys(entities).length === 0 ? {} : { identity }) };
 }
 
+/** Read the committed identity layer back into the compiler's in-memory lock model. */
+export function parseIdentityUsda(text: string): CompilerIdentityModel {
+  if (!text.startsWith("#usda")) {
+    throw new Error(`${NOMOS_IDENTITY_FILENAME} is not a USDA layer`);
+  }
+  if (!text.includes(NOMOS_IDENTITY_LAYER_FORMAT)) {
+    throw new Error(
+      `${NOMOS_IDENTITY_FILENAME} is not ${NOMOS_IDENTITY_LAYER_FORMAT} — refusing to guess an identity encoding`,
+    );
+  }
+  const roots = parseIdentityPrims(text);
+  const root = roots.find((prim) => prim.name === "NomosIdentity");
+  if (root === undefined) throw new Error(`${NOMOS_IDENTITY_FILENAME} has no NomosIdentity prim`);
+  return readIdentityScopes(root);
+}
+
 /** An empty identity layer — the first compile of a package that has never been compiled. */
 export function emptyIdentityLock(): CompilerIdentityModel {
   return { v: 1, domains: {}, identity: emptyLawIdentityRegistry() };

package/src/index.ts

@@ -49,6 +49,9 @@ export {
   forwardRef,
   requires,
   OWNER_FIELD,
+  BIRTH_KEY_WRITE_ONCE_CODE,
+  isBirthKeyWriteOnceRefusal,
+  birthKeyWriteOnceFields,
   type AggregateHandle,
   type AudienceMethods,
   type Audience,
@@ -89,6 +92,14 @@ export {
   isGitObjectIdSchema,
   NOMOS_SHA256_DIGEST_BRAND,
   NOMOS_GIT_OBJECT_ID_BRAND,
+  // TYPED IDS: `t.brandedId(Name)` / `t.uuid()` / `t.idOf(Agg)` fields carry `TypedId<Brand>` values;
+  // `typedId(brand, text)` is the one sanctioned door from text to an id.
+  type TypedId,
+  type Uuid,
+  typedId,
+  typedIdShapeRefusal,
+  isUuidIdSchema,
+  NOMOS_UUID_BRAND,
   // FIELD FACETS (the endorse model — security_model.md): authority/standing/attribution gate
   // set() acceptance of PrincipalEvidence; secret/public are the confidentiality lattice.
   authorityField,
@@ -391,9 +402,14 @@ export {
   type GenesisChainOrBuilder,
   type BusinessBirthDecl,
   type BusinessBirthSpec,
+  CHOOSING_A_BIRTH_KEY_DOC,
   type BusinessBirthPayload,
   type BirthFactKeys,
-  type BirthStringFactKeys,
+  type BirthKeyFactKeys,
+  type BirthKeyType,
+  type BirthKeyDeclaration,
+  birthKeyTypeOfField,
+  birthKeyShapeRefusal,
 } 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
@@ -827,6 +843,14 @@ export {
   seedGenesis,
   type GenesisWarrantHandle,
 } from "./framework/genesis.js";
+// TOKEN-FREE FOUNDING (identity target model D22) — the founding record and the kernel-appended birth
+// origin a founded child carries instead of a BirthAttestation: operator tooling reads its lineage by them.
+export {
+  FoundingPrincipal,
+  FOUNDING_PRINCIPAL_ID,
+  BirthOrigin,
+  BIRTH_ORIGIN_ID,
+} from "./framework/founding_genesis.js";
 // E2E ENCRYPTION (slice 4) — the group-key events (RFC 9420 sender-keys on the ledger).
 export {
   KeyScope,

package/src/intent.ts

@@ -1136,6 +1136,11 @@ class IntentBuilder<I> {
         ? {}
         : {
             birthsChild: true,
+            // The composed intent births through the declared birth's lowered plan, so it carries the same
+            // typed-key declaration (the kernel's `nomos:birthKeyType` era key) as that birth directive.
+            ...(birthSteps[0]?.directive.birthKey === undefined
+              ? {}
+              : { birthKey: birthSteps[0]!.directive.birthKey }),
             ...(bindBusinessBirthPolicy === undefined
               ? {}
               : { [BUSINESS_BIRTH_POLICY_BINDING]: bindBusinessBirthPolicy }),