@githolon/dsl 0.114.0 → 0.115.0

package/src/codegen_ts.ts

@@ -35,6 +35,7 @@ import { refusalContracts, tsRefusalDecoder, tsRefusalDecoders } from "./codegen
  * Like every emitter here: NO FALLBACK. An unsupported zod shape throws at compile
  * time, never degrades to `any` silently.
  */
+import { assertDomainRequirements, type DomainUnitRequirement } from "./domain_requirements.js";
 import type { z } from "zod";
 import { generateTsWorkspaceAccessRead } from "./codegen_workspace_access.js";
 
@@ -45,6 +46,7 @@ import {
   OWNED_PREMINTED_RECORDS_PAYLOAD_FIELD,
   type AggregateHandle,
 } from "./aggregate.js";
+import { BUSINESS_BIRTH_KEY_PAYLOAD_FIELD } from "./births.js";
 import {
   isGitObjectIdSchema,
   isSha256DigestSchema,
@@ -86,6 +88,7 @@ import {
   collectValueObjectDescriptors,
   idOfMetaOf,
   idOfTargetKindOf,
+  brandedIdMetaOf,
   refOfMetaOf,
   versionedRefOfMetaOf,
   voMetaOf,
@@ -230,6 +233,13 @@ export const tsApplicationName = (packageName: string): string =>
 export const tsHashConstName = (packageName: string): string =>
   `${upperSnake(packageName)}_DOMAIN_HASH`;
 
+/** `tool-library` → `TOOL_LIBRARY_DOMAIN_REQUIREMENTS` — the per-domain unit requirements const (CAP-666).
+ *  Module-private: the sealed Reception exports only the receiver, the definition, the value helpers and
+ *  the `<domain>Client` factories, so the table reaches tenants as `<Name>ApplicationDefinition
+ *  .compatibility.domainRequirements`, mirroring Dart's `frameworkCalls.domainRequirements`. */
+export const tsDomainRequirementsConstName = (packageName: string): string =>
+  `${upperSnake(packageName)}_DOMAIN_REQUIREMENTS`;
+
 /** `tool-library` → `TOOL_LIBRARY_INTERFACE` — the baked structural-interface const (#72). */
 export const interfaceConstName = (packageName: string): string =>
   `${upperSnake(packageName)}_COMPATIBILITY_MATRIX_USDA`;
@@ -431,6 +441,18 @@ function mintLazyTypeName(reg: LazyTypeRegistry, path: string): string {
  *  (never `JsonValue`) — see {@link LazyTypeRegistry}. `reg` is absent only for standalone callers
  *  (e.g. a query return) that can't host a named decl; a recursive lazy there is the one place the
  *  `JsonValue` safety valve applies (query returns are read models, never recursive in practice). */
+/** BRANDED-ID ALIASES REACHED WHILE GENERATING ONE CLIENT. {@link generateTsClient} opens the sink and
+ *  emits one `export type <Brand> = string & { readonly __brand }` per name it collected, so every
+ *  `brandedId(...)` / `t.brandedId(...)` / `t.uuid()` value is typed by its brand in payloads AND read models.
+ *  A standalone caller with no open sink keeps the plain `string` (it has nowhere to declare an alias). */
+let brandedIdSink: Set<string> | undefined;
+
+function brandedIdTsType(brand: string): string {
+  if (brandedIdSink === undefined) return "string";
+  brandedIdSink.add(brand);
+  return brand;
+}
+
 function tsTypeOfZod(
   zt: z.ZodTypeAny,
   indent: string,
@@ -468,6 +490,8 @@ function tsTypeOfZod(
         : aggregateType;
     return `NomosRef<${target}>`;
   }
+  const brand = brandedIdMetaOf(zt);
+  if (brand !== undefined && zodKind(zt) === "string") return brandedIdTsType(brand);
   // A DECLARED VALUE OBJECT keeps its NAME (vo_first_class.md): the payload
   // references the same exported interface the read model uses — one name, both directions —
   // instead of an anonymous inline literal type. Checked on the BARE object only: optional/
@@ -882,12 +906,15 @@ export function tsTypeOfField(field: Field): string {
 
 function tsBaseTypeOfField(field: Field): string {
   switch (field.kind) {
-    case "string":
-      return isSha256DigestSchema(field.zod as z.ZodTypeAny)
-        ? "Sha256Digest"
-        : isGitObjectIdSchema(field.zod as z.ZodTypeAny)
-        ? "GitObjectId"
-        : "string";
+    case "string": {
+      const schema = field.zod as z.ZodTypeAny;
+      if (isSha256DigestSchema(schema)) return "Sha256Digest";
+      if (isGitObjectIdSchema(schema)) return "GitObjectId";
+      // TYPED IDS on aggregate fields (`t.brandedId(Name)` / `t.uuid()`): the read model types them exactly as
+      // a payload of the same schema — never a bare string.
+      const brand = brandedIdMetaOf(schema);
+      return brand !== undefined ? brandedIdTsType(brand) : "string";
+    }
     case "int":
       return "number";
     // STRUCTURAL CRDT scalars (read-collapsed): a counter reads as its net number, a position as its
@@ -1131,6 +1158,10 @@ export interface TsClientOptions {
   /** THE LAW this client is generated against: the unit set identity of `build/<name>.units` (CAP-773,
    * law_unit_set_identity.ts). Never the package closure, and never sent to the kernel with an offer. */
   readonly domainHash: string;
+  /** THE PER-DOMAIN REQUIREMENTS (CAP-666): per application domain key, its unit hash and its generated
+   * requirement identity. Carried by the definition's `compatibility.domainRequirements` only when present
+   * (the era rule). */
+  readonly domainRequirements?: readonly DomainUnitRequirement[];
   /** Sibling lossless USDZ transport carried by the generated client when its signed-in workspace
    * still serves the predecessor model. The archive is never canonical state and is not embedded. */
   readonly lawAssetName?: string;
@@ -1421,6 +1452,20 @@ function zodUsesGitObjectId(
 export function generateTsClient(
   modules: readonly DomainModule[],
   opts: TsClientOptions
+): string {
+  const outerSink = brandedIdSink;
+  brandedIdSink = new Set<string>();
+  try {
+    return generateTsClientBody(modules, opts, brandedIdSink);
+  } finally {
+    brandedIdSink = outerSink;
+  }
+}
+
+function generateTsClientBody(
+  modules: readonly DomainModule[],
+  opts: TsClientOptions,
+  brandSink: Set<string>,
 ): string {
   if (opts.callUsda === undefined) {
     throw new Error(
@@ -1451,6 +1496,8 @@ export function generateTsClient(
     )
   );
   const topologyModules = modules;
+  // Branded-id aliases already declared (by the value-object block); the rest are declared at the end.
+  const emittedBrands = new Set<string>();
   // A public business birth can target a deliberately hidden root aggregate. Its private binder still
   // needs a nominal type, but unrelated framework records must remain absent even from generated source.
   const publicBusinessAggregateIds = new Set(
@@ -1589,6 +1636,8 @@ export function generateTsClient(
           opts.interface as unknown as Record<string, DomainInterface>
         );
   const hashConst = tsHashConstName(opts.packageName);
+  const domainRequirements = [...(opts.domainRequirements ?? [])].sort((a, b) => a.domainKey < b.domainKey ? -1 : a.domainKey > b.domainKey ? 1 : 0);
+  assertDomainRequirements(domainRequirements);
   // 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.
   const encMap = buildEncryptionMap(
@@ -2216,6 +2265,20 @@ export function generateTsClient(
     ` *  workspace serves a closure its own kernel composes from those units; compatibility is the kernel's verdict. */`,
     `const ${hashConst} = ${JSON.stringify(opts.domainHash)};`,
     ``,
+    ...(domainRequirements.length === 0
+      ? []
+      : [
+          `/** THE PER-DOMAIN REQUIREMENTS (CAP-666) this client was generated against: for each application domain,`,
+          ` *  the hash of its law unit (\`domain:<key>\` of the unit set) and the sha256 of its generated compatibility`,
+          ` *  requirement. A workspace serving exactly that unit for the key is current for this build whatever else`,
+          ` *  its unit set carries. Identities the adoption inventory and the support policy name; never a verdict. */`,
+          `const ${tsDomainRequirementsConstName(opts.packageName)} = Object.freeze({`,
+          ...domainRequirements.map((requirement) =>
+            `  ${JSON.stringify(requirement.domainKey)}: Object.freeze({ domainKey: ${JSON.stringify(requirement.domainKey)}, `
+            + `unitSha256: ${JSON.stringify(requirement.unitSha256)}, requirementSha256: ${JSON.stringify(requirement.requirementSha256)} }),`),
+          `} as const);`,
+          ``,
+        ]),
     ...(clientInterface !== undefined
       ? [
           `/** Canonical compiler-authored USDA compatibility matrix. The application carries`,
@@ -3729,6 +3792,7 @@ export function generateTsClient(
     for (const [, d] of voByName)
       for (const b of voBrandNames(d)) brands.add(b);
     for (const b of [...brands].sort()) {
+      emittedBrands.add(b);
       out.push(
         `/** Branded id \`${b}\` — a nominal string (\`brandedId("${b}")\`); wire-identical to a string. */`
       );
@@ -4697,7 +4761,7 @@ export function generateTsClient(
             publicPayloadSchema: z.ZodTypeAny;
             rootId: string;
             namespace: string;
-            keyField: string;
+            keyField?: string;
           };
         }
       ).businessBirth;
@@ -4926,17 +4990,29 @@ export function generateTsClient(
         businessBirth === undefined || encFields === undefined
           ? undefined
           : Object.values(encFields).find((field) => field.owned === true);
+      // A minted birth (the default) has no business key, but an owned birth seals to the child's address
+      // before dispatch: reserve the key from the kernel's own minter and hand it to the law (CAP-804).
+      const mintedOwnedBirth =
+        ownedBirthDescriptor !== undefined && businessBirth!.keyField === undefined;
       const ownedBirthPrelude =
         ownedBirthDescriptor === undefined
           ? ""
           : `      if (!holon.__nomosOwnedBirthScopeKey) throw new Error("this holon predates automatic .owned() birth custody — upgrade @githolon/runtime");\n` +
+            (mintedOwnedBirth
+              ? `      if (!holon.mint) throw new Error("this holon predates minted birth keys — upgrade @githolon/runtime");\n` +
+                `      const _birthKey = await holon.mint(${JSON.stringify(
+                  businessBirth!.aggregateId
+                )});\n`
+              : "") +
             `      const _ownedBirthKey = await holon.__nomosOwnedBirthScopeKey({ scope: ${JSON.stringify(
               ownedBirthDescriptor.scope
             )}, namespace: ${JSON.stringify(
               businessBirth!.namespace
-            )}, key: ${inputPayload}[${JSON.stringify(
-              businessBirth!.keyField
-            )}], record: { type: ${JSON.stringify(
+            )}, key: ${
+              mintedOwnedBirth
+                ? "_birthKey"
+                : `${inputPayload}[${JSON.stringify(businessBirth!.keyField)}]`
+            }, record: { type: ${JSON.stringify(
               ownedRuntimeType
             )}, id: ${JSON.stringify(businessBirth!.rootId)} } });`;
       const paramSig = `${argumentName}: ${payloadName}`;
@@ -5268,6 +5344,10 @@ export function generateTsClient(
           type: `${payloadName} & { readonly principal: string; readonly bornAt: string${ownedSeedFields} }`,
         });
       }
+      // A minted birth's law admits a key the client reserved ahead of dispatch (CAP-804).
+      if (businessBirth !== undefined && businessBirth.keyField === undefined) {
+        callExtraFields.set(BUSINESS_BIRTH_KEY_PAYLOAD_FIELD, { type: "string", optional: true });
+      }
       // The public payload remains purely application-authored. The private encoder
       // type additionally admits the custody facts injected by the generated client
       // after it obtains them from the framework-owned key ceremony.
@@ -5420,6 +5500,10 @@ export function generateTsClient(
               ownedBirthDescriptor !== undefined
                 ? `, [_OWNED_KEY_PAYLOAD_FIELD]: _ownedBirthKey.ownedKeySubject`
                 : ""
+            }${
+              ownedBirthDescriptor !== undefined && businessBirth.keyField === undefined
+                ? `, ${JSON.stringify(BUSINESS_BIRTH_KEY_PAYLOAD_FIELD)}: _birthKey`
+                : ""
             } }`
           )};`,
           `      const result = await holon.offerCall(_call, { actor: principal, returnCreated: true });`,
@@ -7076,6 +7160,7 @@ export function generateTsClient(
       `  compatibility: {`,
       `    lawIdentity: sha256Digest(${hashConst}),`,
       `    matrixUsda: ${clientInterface === undefined ? "new Uint8Array()" : interfaceConstName(opts.packageName)},`,
+      ...(domainRequirements.length === 0 ? [] : [`    domainRequirements: ${tsDomainRequirementsConstName(opts.packageName)},`]),
       `    readyCommands: [${rootBirths
         .map(
           (birth) =>
@@ -7093,6 +7178,20 @@ export function generateTsClient(
     );
   }
 
+  // TYPED-ID ALIASES reached by payloads and read models (beyond those the value objects declared above).
+  // TS hoists type aliases, so declaring them last is fine; sorted for byte-determinism.
+  const remainingBrands = [...brandSink].filter((brand) => !emittedBrands.has(brand)).sort();
+  if (remainingBrands.length > 0) {
+    out.push(`// ── typed ids (brandedId / t.brandedId / t.uuid) — nominal strings, wire-identical to a string ──`);
+    for (const b of remainingBrands) {
+      out.push(
+        `/** Branded id \`${b}\` — a nominal string (\`brandedId("${b}")\`); wire-identical to a string. */`,
+        `export type ${b} = string & { readonly __brand: "${b}" };`,
+        ``
+      );
+    }
+  }
+
   // RECURSIVE PAYLOAD TYPES (`z.lazy`): emit each minted named alias once. Sorted by name for
   // byte-determinism; TS hoists type aliases so referencing them above is fine.
   if (lazyReg.decls.size > 0) {

package/src/compatibility_graph.ts

@@ -18,6 +18,7 @@ import type { Field } from "./fields.js";
 import type { GeometryKind } from "./value_object.js";
 import { isBusinessIntent } from "./intent.js";
 import { isFrameworkAggregate } from "./framework/framework_aggregates.js";
+import { composedWireIdentity } from "./composed_wire_identity.js";
 import type {
   LawAnonymousValueTypeNode,
   LawAggregateNode,
@@ -42,6 +43,21 @@ export interface PayloadFieldShape {
   readonly type?: string;
 }
 
+/**
+ * One member of a nested record value. Two laws can agree on every nested name and kind while
+ * their generated codecs disagree on the Protobuf field numbers (the 1 October 2026
+ * `EstateAsset.canvasRequirements{}.isRequired` incident), so the member carries the allocation
+ * the generated codec actually encodes and decodes it under, plus any retained aliases.
+ */
+export interface CompatibilityRecordField {
+  readonly required: boolean;
+  readonly type: string;
+  /** Canonical Protobuf allocation the generated codec uses for this member. */
+  readonly wireKey?: string;
+  /** Previously shipped allocations this codec still decodes during an overlap window. */
+  readonly wireAliases?: readonly string[];
+}
+
 /**
  * The compatibility vocabulary for domain values. This is a graph rather than
  * an inline tree so recursive values and shared nested value objects remain
@@ -68,9 +84,7 @@ export type CompatibilityValueShape =
   | { readonly kind: "map"; readonly value: string }
   | {
       readonly kind: "record";
-      readonly fields: Readonly<
-        Record<string, { readonly required: boolean; readonly type: string }>
-      >;
+      readonly fields: Readonly<Record<string, CompatibilityRecordField>>;
     }
   | { readonly kind: "sum"; readonly variants: readonly string[] }
   | { readonly kind: "recursive"; readonly body: string };
@@ -352,10 +366,31 @@ export function domainInterface(
  * workspace offers are now two projections of the same graph/USDA, rather than
  * independently interpreting DomainModule and hoping the shapes coincide.
  */
-export function domainInterfaceFromLawGraph(graph: LawGraph): DomainInterface {
+export function domainInterfaceFromLawGraph(
+  graph: LawGraph,
+  /** The composed law layer's path index. Nested members of a record that OpenUSD composition
+   *  shares with another contract take the canonical prim's allocation, exactly as the generated
+   *  codecs do through `composedWireIdentity`; without the index each member's own identity is
+   *  its allocation. */
+  paths: ReadonlyMap<string, string> = new Map()
+): DomainInterface {
   const nodes = new Map<string, LawGraph["nodes"][number]>(
     graph.nodes.map((node) => [node.entity.id, node])
   );
+  // The nested allocation is the one fact the generated Dart/TS codecs and installed law must
+  // agree on. It is derived here from the same identity the codecs derive it from, never from
+  // the member's name.
+  const nestedWire = (entity: {
+    readonly id: string;
+    readonly sid: string;
+    readonly wireKey?: string;
+    readonly wireAliases?: readonly string[];
+  }): Pick<CompatibilityRecordField, "wireKey" | "wireAliases"> => ({
+    wireKey: composedWireIdentity(paths, entity),
+    ...(entity.wireAliases === undefined || entity.wireAliases.length === 0
+      ? {}
+      : { wireAliases: entity.wireAliases }),
+  });
   const sorted = <T>(
     entries: readonly (readonly [string, T])[]
   ): Record<string, T> =>
@@ -587,6 +622,7 @@ export function domainInterfaceFromLawGraph(graph: LawGraph): DomainInterface {
                     {
                       required: field.required,
                       type: resolvedTypeId(field.value.id),
+                      ...nestedWire(field.entity),
                     },
                   ] as const,
                 ];
@@ -653,6 +689,7 @@ export function domainInterfaceFromLawGraph(graph: LawGraph): DomainInterface {
                 {
                   required: field.required,
                   type: resolvedTypeId(field.value.id),
+                  ...nestedWire(field.entity),
                 },
               ] as const,
             ];

package/src/compatibility_usda.ts

@@ -60,10 +60,14 @@ function canonicalCompatibilityTypes(
         value = `sum(${type.variants.map(ref).sort().map(fingerprintAtom).join("")})`;
         break;
       case "record":
+        // Two records with identical names and kinds but different nested allocations are
+        // different contracts; interning them as one would erase the very evidence the kernel
+        // judges, so the allocation and its aliases are part of the fingerprint.
         value = `record(${Object.entries(type.fields)
           .sort(([left], [right]) => left.localeCompare(right))
           .map(([name, field]) =>
-            `${fingerprintAtom(name)}${field.required ? "1" : "0"}${fingerprintAtom(ref(field.type))}`)
+            `${fingerprintAtom(name)}${field.required ? "1" : "0"}${fingerprintAtom(ref(field.type))}` +
+            `${fingerprintAtom(field.wireKey ?? "")}${[...(field.wireAliases ?? [])].sort().map(fingerprintAtom).join("")}`)
           .join("")})`;
         break;
     }
@@ -146,6 +150,12 @@ function emitType(lines: string[], type: CompatibilityValueShape, typeRef: (id:
           `                            def NomosCompatibilityValueField "${numbered("f", index)}"`,
           "                            {",
           `                                custom uniform string nomos:name = ${usdaString(name)}`,
+          ...(field.wireKey === undefined ? [] : [
+            `                                custom uniform string nomos:wireKey = ${usdaString(field.wireKey)}`,
+          ]),
+          ...(field.wireAliases === undefined || field.wireAliases.length === 0 ? [] : [
+            `                                custom uniform string[] nomos:wireAliases = [${field.wireAliases.map(usdaString).join(", ")}]`,
+          ]),
           `                                custom uniform bool nomos:required = ${field.required}`,
           `                                custom rel nomos:type = <${typeRef(field.type)}>`,
           "                            }",