@githolon/dsl 0.102.4 → 0.103.0

package/src/codegen_ts.ts

@@ -43,7 +43,7 @@ import {
   OWNED_PREMINTED_RECORDS_PAYLOAD_FIELD,
   type AggregateHandle,
 } from "./aggregate.js";
-import type { Field, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
+import { isSha256DigestSchema, type Field, type ValueObjectDescriptor, type ValueObjectFieldDescriptor } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
 import { OWNED_DEVICE_APPROVAL_DIRECTIVE, ownedRecordActionDirectiveId } from "./framework/owned_custody.js";
@@ -51,7 +51,7 @@ import { BUSINESS_CORRECTION_DIRECTIVE } from "./framework/business_corrections.
 import { collectActivityDescriptors, type PackageActivityEntry } from "./codegen_dart.js";
 import type { NomosCompat } from "./compat_manifest.js";
 import type { QueryDecl } from "./query.js";
-import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf } from "./value_object.js";
+import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf, versionedRefOfMetaOf } from "./value_object.js";
 import { recursiveTypeBaseName, zodUnwrapLazy } from "./zod_lazy.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
@@ -119,7 +119,7 @@ const tsOptAccess = (name: string): string =>
   /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? `.${name}` : `.[${JSON.stringify(name)}]`;
 
 // ── NAME NORMALIZATION (no naming convention to learn) ────────────────────────────
-// `nomos.package.mjs` names and domain keys may be ANY string — kebab-case,
+// `nomos.project.ts` names and domain keys may be ANY string — kebab-case,
 // snake_case, space-separated, PascalCase. Artifact FILENAMES keep the raw name
 // verbatim; generated SYMBOLS normalize it:
 
@@ -308,6 +308,17 @@ function tsTypeOfZod(
   reg?: LazyTypeRegistry,
   path = "",
 ): string {
+  if (isSha256DigestSchema(zt)) return "Sha256Digest";
+  const versioned = versionedRefOfMetaOf(zt);
+  if (versioned !== undefined) {
+    const target = versioned.targetKind === "contract"
+      ? contractTypeName(versioned.targetAggregateType)
+      : versioned.targetAggregateType;
+    const series = versioned.seriesKind === "contract"
+      ? contractTypeName(versioned.seriesAggregateType)
+      : versioned.seriesAggregateType;
+    return `VersionedNomosRef<${target}, ${series}>`;
+  }
   if (recipientMetaOf(zt) !== undefined) return "Recipient<User>";
   const aggregateType = idOfMetaOf(zt);
   if (aggregateType !== undefined) {
@@ -339,6 +350,8 @@ function tsTypeOfZod(
       return "number"; // `.int()` is a runtime constraint; TS has one number type
     case "boolean":
       return "boolean";
+    case "null":
+      return "null";
     case "enum":
       return union(zodEnumValues(zt).map((v) => JSON.stringify(v)));
     case "literal": {
@@ -471,7 +484,7 @@ function tsTypeOfPayload(
   reg?: LazyTypeRegistry,
   pathPrefix = "",
 ): string {
-  if (zodKind(schema) !== "object" || (autoStamped.length === 0 && minted.length === 0 && autoPlaced.length === 0 && privateFields.length === 0)) {
+  if (zodKind(schema) !== "object") {
     return tsTypeOfZod(schema, "", reg, pathPrefix);
   }
   const stamped = new Set(autoStamped);
@@ -485,8 +498,10 @@ function tsTypeOfPayload(
     .map(([name, raw]) => {
     let f = raw as z.ZodTypeAny;
     let optional = stamped.has(name) || mintedSet.has(name) || placedSet.has(name);
+    let schemaOptional = false;
     while (zodKind(f) === "optional" || zodKind(f) === "default") {
       optional = true;
+      schemaOptional = true;
       f = zodDef(f).innerType!;
     }
     const note = stamped.has(name)
@@ -495,6 +510,13 @@ function tsTypeOfPayload(
           ? " // picked LEAST-LOADED over the coordinator's law-state at offer when omitted (sharding §3)"
           : "";
     const fieldPath = pathPrefix === "" ? name : `${pathPrefix}.${name}`;
+    const optionalReferenceTarget = schemaOptional ? idOfMetaOf(raw as z.ZodTypeAny) : undefined;
+    if (optionalReferenceTarget !== undefined) {
+      const target = idOfTargetKindOf(raw as z.ZodTypeAny) === "contract"
+        ? contractTypeName(optionalReferenceTarget)
+        : optionalReferenceTarget;
+      return `  ${name}: NomosOptionalRef<${target}>; // required choice: absent or present`;
+    }
     return `  ${name}${optional ? "?" : ""}: ${tsTypeOfZod(f, "  ", reg, fieldPath)};${note}`;
   });
   return fields.length ? `{\n${fields.join("\n")}\n}` : "Record<string, never>";
@@ -522,7 +544,7 @@ function tsTypeOfField(field: Field): string {
 function tsBaseTypeOfField(field: Field): string {
   switch (field.kind) {
     case "string":
-      return "string";
+      return isSha256DigestSchema(field.zod as z.ZodTypeAny) ? "Sha256Digest" : "string";
     case "int":
       return "number";
     // STRUCTURAL CRDT scalars (read-collapsed): a counter reads as its net number, a position as its
@@ -543,6 +565,16 @@ function tsBaseTypeOfField(field: Field): string {
       // Both reference shapes keep aggregate identity typed. A same-workspace edge is the canonical
       // NomosRef<TAggregate>; a foreign edge adds its decoder/read helpers.
       const fr = (field as { foreignRef?: { targetAggregateId: string; targetIsContract?: boolean } }).foreignRef;
+      const vr = field.versionedForeignRef;
+      if (vr !== undefined) {
+        const target = vr.targetIsContract === true
+          ? contractTypeName(vr.targetAggregateId)
+          : vr.targetAggregateId;
+        const series = vr.seriesIsContract === true
+          ? contractTypeName(vr.seriesAggregateId)
+          : vr.seriesAggregateId;
+        return `VersionedNomosRef<${target}, ${series}>`;
+      }
       // A contract target types against the shared `<ContractId>Contract` interface (the public DTO),
       // not the concrete `<Agg>Data` — that is how the reference stays acyclic.
       return fr !== undefined
@@ -599,7 +631,7 @@ function tsTypeOfVoField(f: ValueObjectFieldDescriptor): string {
     case "string":
       return f.idOf !== undefined
         ? `NomosRef<${f.idOfContract === true ? contractTypeName(f.idOf) : f.idOf}>`
-        : f.brand ?? "string"; // a brandedId(...) → the emitted branded alias
+        : f.digest === "sha256" ? "Sha256Digest" : f.brand ?? "string";
     case "number":
       return "number"; // `.int()`/units are Dart-side nominal products; TS keeps one number
     case "boolean":
@@ -699,9 +731,9 @@ function aggregatesOf(mod: Record<string, unknown>): AggregateHandle[] {
 // ── the generator ─────────────────────────────────────────────────────────────────
 
 export interface TsClientOptions {
-  /** The package name (`nomos.package.mjs` `name`) — used for the hash constant. */
+  /** The package name (`nomos.project.ts` `name`) — used for the hash constant. */
   readonly packageName: string;
-  /** sha256 of the built `.package.usda` — the law this client offers under. */
+  /** Content identity of the built typed USDA closure (`.law.usdz`). */
   readonly domainHash: string;
   /** The package's STRUCTURAL INTERFACE (#72) — directives (payload shapes) + aggregates
    *  (read shapes, sid-keyed), keyed by domain. Baked in so `connect()` can negotiate
@@ -1024,6 +1056,36 @@ function anyPackedTaxonomy(modules: readonly DomainModule[]): boolean {
   return false;
 }
 
+/** Whether a schema contains the framework SHA-256 semantic string, including nested
+ * value objects/arrays. Used only to keep its declaration omit-when-unused. */
+function zodUsesSha256Digest(schema: z.ZodTypeAny, seen = new Set<z.ZodTypeAny>()): boolean {
+  if (seen.has(schema)) return false;
+  seen.add(schema);
+  if (isSha256DigestSchema(schema)) return true;
+  switch (zodKind(schema)) {
+    case "optional":
+    case "default":
+    case "nullable": {
+      const inner = zodDef(schema).innerType;
+      return inner !== undefined && zodUsesSha256Digest(inner, seen);
+    }
+    case "array":
+      return zodUsesSha256Digest(zodArrayElement(schema), seen);
+    case "object":
+      return Object.values(zodObjectShape(schema)).some((field) => zodUsesSha256Digest(field, seen));
+    case "record": {
+      const value = zodDef(schema).valueType;
+      return value !== undefined && zodUsesSha256Digest(value, seen);
+    }
+    case "union":
+      return (zodDef(schema).options ?? []).some((option) => zodUsesSha256Digest(option, seen));
+    case "lazy":
+      return zodUsesSha256Digest(zodUnwrapLazy(schema), seen);
+    default:
+      return false;
+  }
+}
+
 export function generateTsClient(modules: readonly DomainModule[], opts: TsClientOptions): string {
   const topologyModules = modules;
   // A public business birth can target a deliberately hidden root aggregate. Its private binder still
@@ -1136,6 +1198,27 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       ),
     ),
   );
+  const hasVersionedRefs = modules.some((m) =>
+    m.aggregates.some((a) =>
+      Object.values(a.fields as Record<string, Field>).some((field) => field.versionedForeignRef !== undefined),
+    ) || (m.directives as Directive<unknown>[]).some((directive) => {
+      const birth = (directive as { businessBirth?: { publicPayloadSchema?: z.ZodTypeAny } }).businessBirth;
+      const schema = birth?.publicPayloadSchema ?? (directive as { payloadSchema?: z.ZodTypeAny }).payloadSchema;
+      return schema !== undefined && zodKind(schema) === "object" &&
+        Object.values(zodObjectShape(schema)).some((field) => versionedRefOfMetaOf(field) !== undefined);
+    }),
+  );
+  const hasSha256Digests = modules.some((module) =>
+    module.aggregates.some((aggregate) =>
+      Object.values(aggregate.fields as Record<string, Field>).some((field) =>
+        isSha256DigestSchema(field.zod as z.ZodTypeAny),
+      ),
+    ) || (module.directives as Directive<unknown>[]).some((directive) => {
+      const birth = (directive as { businessBirth?: { publicPayloadSchema?: z.ZodTypeAny } }).businessBirth;
+      const schema = birth?.publicPayloadSchema ?? (directive as { payloadSchema?: z.ZodTypeAny }).payloadSchema;
+      return schema !== undefined && zodUsesSha256Digest(schema);
+    }),
+  );
   const hasConflictResolvers = modules.some(
     (m) => ((m as { surfacedResolvers?: readonly unknown[] }).surfacedResolvers?.length ?? 0) > 0,
   );
@@ -1182,6 +1265,20 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     ``,
     `import { nomosInternalOpenGeneratedApplication, nomosInternalOpenGeneratedChildApplication${hasInvitations ? ", nomosInternalCreateInvitation, nomosInternalRedeemInvitation" : ""} } from "@githolon/client/_generated_application_host_7c1f5e";`,
     ``,
+    ...(hasSha256Digests
+      ? [
+          `/** A SHA-256 digest in canonical Nomos wire form: 64 lowercase hexadecimal characters. */`,
+          `export type Sha256Digest = string & { readonly __nomosSha256Digest: unique symbol };`,
+          `/** Validate and construct a Sha256Digest before an offer is assembled. */`,
+          `export const sha256Digest = (value: string): Sha256Digest => {`,
+          `  if (!/^[0-9a-f]{64}$/.test(value)) {`,
+          `    throw new TypeError("expected a 64-character lowercase hexadecimal SHA-256 digest");`,
+          `  }`,
+          `  return value as Sha256Digest;`,
+          `};`,
+          ``,
+        ]
+      : []),
     `interface _NomosApplicationStatus {`,
     `  readonly phase: "opening" | "current" | "saving" | "receiving" | "catching-up" | "offline" | "attention";`,
     `  readonly localChanges: number;`,
@@ -1210,7 +1307,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         ]
       : []),
     ``,
-    `/** sha256 of the deployed \`.package.usda\` — the installed law this client offers under. */`,
+    `/** Content identity of the installed typed USDA closure (transported as \`.law.usdz\`). */`,
     `const ${hashConst} = ${JSON.stringify(opts.domainHash)};`,
     ``,
     ...(clientInterface !== undefined
@@ -1248,6 +1345,15 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  /** Stable, portable nomos:// address. An address identifies a record; it never grants authority. */`,
     `  readonly address: string;`,
     `}`,
+    `/** An optional first-class relationship expressed as a REQUIRED business choice.`,
+    ` *  Use NomosOptionalRef.absent() to deliberately omit it or present(ref) to supply it. */`,
+    `export type NomosOptionalRef<TAggregate> =`,
+    `  | { readonly kind: "absent" }`,
+    `  | { readonly kind: "present"; readonly reference: NomosRef<TAggregate> };`,
+    `export const NomosOptionalRef = {`,
+    `  absent: (): { readonly kind: "absent" } => ({ kind: "absent" }),`,
+    `  present: <TAggregate>(reference: NomosRef<TAggregate>): NomosOptionalRef<TAggregate> => ({ kind: "present", reference }),`,
+    `} as const;`,
     `interface _NomosReferenceData<TAggregate> extends NomosRef<TAggregate> { workspace: string; type: string; id: string; address: string }`,
     `const _nmsReferenceData = <TAggregate>(ref: NomosRef<TAggregate>): _NomosReferenceData<TAggregate> => ref as _NomosReferenceData<TAggregate>;`,
     `const _nmsRef = <TAggregate>(workspace: string, type: string, id: string): NomosRef<TAggregate> => ({`,
@@ -1360,18 +1466,23 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `/** Finish a business action without leaking ledger heads or framework write envelopes. */`,
     `async function _commit(r: Promise<_NomosRawWriteResult>): Promise<void> { void await r; }`,
     `/** Turn the sealed intent's complete affected set into its generated, business-named result. */`,
-    `async function _businessResult<TResult>(ws: string, outputs: readonly { member: string; type: string; many?: boolean }[], r: Promise<_NomosRawWriteResult>): Promise<TResult> {`,
+    `async function _businessResult<TResult>(ws: string, outputs: readonly { member: string; type: string; many?: boolean; optional?: boolean }[], r: Promise<_NomosRawWriteResult>): Promise<TResult> {`,
     `  const result = await r;`,
     `  if (typeof result === "string" || !Array.isArray(result.affected)) {`,
     `    throw new Error("Nomos committed the business action without returning its affected records");`,
     `  }`,
-    `  const answer: Record<string, NomosRef<_NomosAnyAggregate> | readonly NomosRef<_NomosAnyAggregate>[]> = {};`,
+    `  const answer: Record<string, NomosRef<_NomosAnyAggregate> | readonly NomosRef<_NomosAnyAggregate>[] | undefined> = {};`,
     `  for (const output of outputs) {`,
     `    const matches = result.affected.filter((affected) => affected.type === output.type || affected.type.endsWith("." + output.type));`,
     `    if (output.many) {`,
     `      answer[output.member] = matches.map((match) => _nmsRef<_NomosAnyAggregate>(ws, match.type, match.id));`,
     `      continue;`,
     `    }`,
+    `    if (output.optional) {`,
+    `      if (matches.length > 1) throw new Error(\`Nomos expected at most one affected \${output.type} record, received \${matches.length}\`);`,
+    `      answer[output.member] = matches.length === 0 ? undefined : _nmsRef<_NomosAnyAggregate>(ws, matches[0]!.type, matches[0]!.id);`,
+    `      continue;`,
+    `    }`,
     `    if (matches.length !== 1) throw new Error(\`Nomos expected one affected ${"${output.type}"} record, received ${"${matches.length}"}\`);`,
     `    answer[output.member] = _nmsRef<_NomosAnyAggregate>(ws, matches[0]!.type, matches[0]!.id);`,
     `  }`,
@@ -1447,6 +1558,34 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `    async exists() { return (await this.resolveResult()).status === "found"; },`,
     `  };`,
     `}`,
+    ...(hasVersionedRefs
+      ? [
+          `export type ReferenceFreshness<TVersion> =`,
+          `  | { readonly status: "current"; readonly latest: NomosRef<TVersion> }`,
+          `  | { readonly status: "stale"; readonly latest: NomosRef<TVersion> }`,
+          `  | { readonly status: "unavailable"; readonly reason: string };`,
+          `/** An immutable publication pin plus the stable series which declares its current publication.`,
+          ` *  freshness() is O(current state): it never reconstructs the pinned record or walks history. */`,
+          `export interface VersionedNomosRef<TVersion, TSeries> {`,
+          `  readonly pinned: NomosRef<TVersion>;`,
+          `  readonly series: NomosRef<TSeries>;`,
+          `  freshness(): Promise<ReferenceFreshness<TVersion>>;`,
+          `}`,
+          `type _NomosRawAddress = { workspace: string; type: string; id: string };`,
+          `function _versionedNomosRef<TVersion, TSeries>(nomos: NomosHolon, raw: { pinned: _NomosRawAddress; series: _NomosRawAddress }, currentField: string): VersionedNomosRef<TVersion, TSeries> {`,
+          `  const pinned = _nmsRef<TVersion>(raw.pinned.workspace, raw.pinned.type, raw.pinned.id);`,
+          `  const series = _nmsRef<TSeries>(raw.series.workspace, raw.series.type, raw.series.id);`,
+          `  return { pinned, series, async freshness() {`,
+          `    if (nomos.checkRefFreshness === undefined) return { status: "unavailable", reason: "installed Nomos runtime does not support reference freshness" };`,
+          `    const result = await nomos.checkRefFreshness([{ pinned: raw.pinned, series: raw.series, currentField }]);`,
+          `    const outcome = result.unique[0]?.outcome;`,
+          `    if (outcome?.status === "current") return { status: "current", latest: pinned };`,
+          `    if (outcome?.status === "stale" && outcome.latest !== undefined) return { status: "stale", latest: _nmsRef<TVersion>(outcome.latest.workspace, outcome.latest.type, outcome.latest.id) };`,
+          `    return { status: "unavailable", reason: String(outcome?.status ?? "unknown") };`,
+          `  } };`,
+          `}`,
+        ]
+      : []),
     ``,
     `/** Arbitrary JSON — the type a RECURSIVE \`z.lazy\` payload subtree degrades to (a self-`,
     ` *  referencing tree/JSON schema can't be a finite named literal, so the engine validates it`,
@@ -1542,12 +1681,12 @@ 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 }[]; affected?: { type: string; id: string }[]; workspace?: string; born?: unknown; birthOutcomes?: unknown }>;`,
+    `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean }): Promise<string | { head: string; created?: { type: string; id: string }[]; affected?: { type: string; id: string }[]; workspace?: string; born?: unknown; birthOutcomes?: unknown }>;`,
     ...(sourceTrustPresent
       ? [
-          `  /** FRAMEWORK-INTERNAL: obtain the source workspace's signed answer. Generated business`,
-          `   *  actions privately establish trust and carry it; application code never receives this seam. */`,
-          `  fetchAttestedRead(from: string, queryId: string, args?: Record<string, unknown>): Promise<{ queryId: string; result: unknown; attestation: unknown }>;`,
+          `  /** FRAMEWORK-INTERNAL: inspect a sibling's immutable custody identity before authoring`,
+          `   *  the ordinary source-enrolment offer. This identity is never accepted as read proof. */`,
+          `  __nomosWorkspaceGenesis(from: string): Promise<string>;`,
         ]
       : []),
     ...(hasCorrections
@@ -1578,6 +1717,12 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  __nomosChildWorkspaces?(): Promise<readonly { workspace: string; status: "active" | "retired" | "reclaimed" | "unknown"; bornAt: string | null }[]>;`,
     `  /** FRAMEWORK-INTERNAL child navigation captured by generated description links. */`,
     `  __nomosOpenChild?(workspace: string): Promise<NomosHolon>;`,
+    ...(hasVersionedRefs
+      ? [
+          `  /** Framework-private O(current-state) version check used by generated VersionedNomosRef. */`,
+          `  checkRefFreshness?(refs: readonly { pinned: _NomosRawAddress; series: _NomosRawAddress; currentField: string }[]): Promise<{ unique: { outcome: { status: string; latest?: _NomosRawAddress } }[]; order: number[] }>;`,
+        ]
+      : []),
     `  /** FRAMEWORK-INTERNAL exact-history adoption seam. Generated clients expose only`,
     `   *  \`model.adopt()\` and a chained \`decision.accept(reason)\`. */`,
     `  __nomosAdoptModel?(domain: string, candidateHash: string, opts?: { because?: string }): Promise<__NomosModelAdoptionWire>;`,
@@ -1617,7 +1762,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           `  /** FRAMEWORK-INTERNAL: prepare the atomic law payload behind share/unshare/transfer. */`,
           `  __nomosPrepareOwnedRecordAction?(args: { action: "share" | "unshare" | "transfer"; scope: string; record: NomosRef<_NomosAnyAggregate>; peer: string }): Promise<Record<string, unknown>>;`,
           `  /** FRAMEWORK-INTERNAL: derive the deterministic unborn child's owned key before atomic genesis. */`,
-          `  __nomosOwnedBirthScopeKey?(args: { scope: string; namespace: string; key: unknown }): Promise<NomosScopeKey & { workspace: string }>;`,
+          `  __nomosOwnedBirthScopeKey?(args: { scope: string; namespace: string; key: unknown; record: { type: string; id: string } }): Promise<NomosScopeKey & { workspace: string }>;`,
           ...(ownedPresent
             ? [
                 `  /** FRAMEWORK-INTERNAL: make the opaque request for this session's not-yet-approved device. */`,
@@ -1655,12 +1800,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   `   *  OPTIONAL member: structural binding tolerates a pre-spatial holon (the accessor then throws at call). */`,
   `  spatialWithin?(spatialId: string, bbox: { minX: number; minY: number; maxX: number; maxY: number } | { minLng: number; minLat: number; maxLng: number; maxLat: number }): Promise<unknown>;`,
     `  sum(sumId: string, groupKey?: string): Promise<number>;`,
-    ...(anyPackedTaxonomy(modules)
-      ? [
-          `  /** THE LOGICAL PAGED ROW SURFACE (sharding §5.3, ruling 2) — present on a ROUTED holon. */`,
-          `  pages?(queryId: string, params?: Record<string, unknown>, page?: { pageSize?: number; cursor?: string | null }): Promise<{ rows: unknown[]; cursor: string | null; done: boolean }>;`,
-        ]
-      : []),
+    `  /** Bounded authenticated query page. Optional only so generated clients diagnose an old runtime cleanly. */`,
+    `  queryPage?(queryId: string, params?: Record<string, unknown>, page?: { pageSize?: number; cursor?: string | null }, keys?: readonly unknown[], principal?: string): Promise<{ rows: unknown[]; cursor: string | null; done: boolean }>;`,
     `  /** The DEAD-LETTER QUEUE — refused-but-legitimate intents the app must handle`,
     `   *  explicitly (inspect → retry after a law fix → or discard). Work is never lost. */`,
     `  deadLetters(): Promise<{ id?: string; oid: string; source: string; error: string; domain?: string | null; directiveId?: string | null; at: string }[]>;`,
@@ -1681,6 +1822,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `   *  and the holon computes the LIVE per-member verdict on \`holon.compat\`. A KNOWN-incompatible directive`,
     `   *  then refuses CLIENT-SIDE at write time (LawMismatchError), never as a server 422. */`,
     `  checkCompat?(compat: { lawHash: string; interfaceHash: string; packageName: string }, requirement?: unknown): NomosCompatVerdict | null;`,
+    `  /** Framework-private readiness hint; generated domain bindings keep first-use plan work off the offer path. */`,
+    `  prepareDomain?(domain: string, packageHash: string): void;`,
     `  /** RELEASE COHERENCE: throws a typed KernelCoherenceError at bind if the cloud's kernel lacks a`,
     `   *  capability this law requires (e.g. \`compoundKeys\`) — instead of an opaque deep fold refusal. */`,
     `  assertKernelCoherence?(requiresKernel: readonly string[], opts?: { lawHash?: string }): unknown;`,
@@ -2136,7 +2279,13 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `const _nmsWireReferences = <T extends object>(payload: T, fields: Readonly<Record<string, string>>, workspace: string): T => {`,
       `  const out = { ...payload } as Record<string, unknown>;`,
       `  for (const [field, expectedType] of Object.entries(fields)) {`,
-      `    const value = out[field];`,
+      `    let value = out[field];`,
+      `    if (typeof value === "object" && value !== null && "kind" in value) {`,
+      `      const choice = value as { kind?: unknown; reference?: unknown };`,
+      `      if (choice.kind === "absent") { delete out[field]; continue; }`,
+      `      if (choice.kind !== "present") throw new TypeError(field + " must choose NomosOptionalRef.absent() or .present(ref)");`,
+      `      value = choice.reference;`,
+      `    }`,
       `    if (value !== undefined) out[field] = _nmsReferenceId(value, expectedType, workspace, field);`,
       `  }`,
       `  return out as T;`,
@@ -2144,52 +2293,36 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       ``,
     );
   }
-  if (anyRecipientPayload) {
+  if (hasVersionedRefs) {
     out.push(
-      `const _nmsWireRecipients = <T extends object>(payload: T, fields: readonly string[]): T => {`,
+      `const _nmsWireVersionedReferences = <T extends object>(payload: T, fields: readonly string[]): T => {`,
       `  const out = { ...payload } as Record<string, unknown>;`,
       `  for (const field of fields) {`,
-      `    const value = out[field];`,
-      `    if (value !== undefined) out[field] = _nmsRecipientAddress(value, field);`,
+      `    const value = out[field] as { pinned?: unknown; series?: unknown } | undefined;`,
+      `    if (value === undefined) continue;`,
+      `    if (typeof value !== "object" || value === null) throw new TypeError(field + " must be a VersionedNomosRef returned by the generated application");`,
+      `    const address = (part: unknown, label: string): _NomosRawAddress => {`,
+      `      if (typeof part !== "object" || part === null) throw new TypeError(field + "." + label + " must carry a NomosRef");`,
+      `      const ref = _nmsReferenceData(part as NomosRef<_NomosAnyAggregate>);`,
+      `      if (!ref.workspace || !ref.type || !ref.id) throw new TypeError(field + "." + label + " must carry a complete NomosRef");`,
+      `      return { workspace: ref.workspace, type: ref.type, id: ref.id };`,
+      `    };`,
+      `    out[field] = { pinned: address(value.pinned, "pinned"), series: address(value.series, "series") };`,
       `  }`,
       `  return out as T;`,
       `};`,
       ``,
     );
   }
-
-  if (sourceTrustPresent) {
+  if (anyRecipientPayload) {
     out.push(
-      `/** Private dynamic-source composition. A business action names a source record; Nomos fetches its`,
-      ` *  signed answer, derives the portable source identity, seats the law-declared trust policy and`,
-      ` *  carries the envelope on the offer. None of these values are application arguments. */`,
-      `type _NomosAttestedEntry = { queryId: string; result: unknown; attestation: Record<string, unknown> };`,
-      `const _nmsAttestedEntry = (value: unknown): _NomosAttestedEntry => {`,
-      `  const raw = typeof value === "object" && value !== null && "entry" in value`,
-      `    ? (value as { entry?: unknown }).entry`,
-      `    : value;`,
-      `  if (typeof raw !== "object" || raw === null) throw new Error("Nomos source did not return an attested business record");`,
-      `  const entry = raw as { queryId?: unknown; result?: unknown; attestation?: unknown };`,
-      `  if (typeof entry.queryId !== "string" || typeof entry.attestation !== "object" || entry.attestation === null) {`,
-      `    throw new Error("Nomos source omitted its signed identity");`,
+      `const _nmsWireRecipients = <T extends object>(payload: T, fields: readonly string[]): T => {`,
+      `  const out = { ...payload } as Record<string, unknown>;`,
+      `  for (const field of fields) {`,
+      `    const value = out[field];`,
+      `    if (value !== undefined) out[field] = _nmsRecipientAddress(value, field);`,
       `  }`,
-      `  return entry as _NomosAttestedEntry;`,
-      `};`,
-      `const _nmsSourceGenesis = (entry: _NomosAttestedEntry): string => {`,
-      `  const value = entry.attestation.source_genesis;`,
-      `  if (typeof value !== "string" || value.length === 0) throw new Error("Nomos source omitted its genesis identity");`,
-      `  return value;`,
-      `};`,
-      `const _nmsSourceKeyHash = async (entry: _NomosAttestedEntry): Promise<string> => {`,
-      `  const publicKey = entry.attestation.public_key;`,
-      `  if (typeof publicKey !== "string" || publicKey.length === 0) throw new Error("Nomos source omitted its attestation key");`,
-      `  let bytes: Uint8Array;`,
-      `  try {`,
-      `    if (typeof atob === "function") bytes = Uint8Array.from(atob(publicKey), (character) => character.charCodeAt(0));`,
-      `    else bytes = Uint8Array.from((globalThis as unknown as { Buffer: { from(value: string, encoding: string): Uint8Array } }).Buffer.from(publicKey, "base64"));`,
-      `  } catch { throw new Error("Nomos source returned an invalid attestation key"); }`,
-      `  const digest = await crypto.subtle.digest("SHA-256", bytes as unknown as BufferSource);`,
-      `  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");`,
+      `  return out as T;`,
       `};`,
       ``,
     );
@@ -2261,14 +2394,16 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
 
   out.push(`// ── read models (projection \`data\` shapes; partial-fold optional, EXCEPT .fromBirth()`, `//    fields — their presence is gate law, so the type is non-optional) ──`, ``);
   const foreignRefFields: { agg: string; field: string; workspaceField: string; target: string }[] = [];
+  const atomicRefFields: { agg: string; field: string }[] = [];
+  const versionedRefFields: { agg: string; field: string; currentField: string }[] = [];
   // wrap a read accessor return expression through the foreignRef row-hydrator (identity + byte-identical
   // when the package declares no foreignRef, so non-foreignRef packages are unchanged).
   // Every read accessor's rows get their canonical `.ref` stamped from `holon.workspace` (additive); a
   // foreignRef-declaring package ALSO hydrates its foreignRef fields into typed locators first.
   const wrapP = (expr: string): string =>
-    `_businessRecordsP(_stampRefsP(holon.workspace, ${foreignRefFields.length > 0 ? `_hydrateP(holon, ${expr})` : expr}))`;
+    `_businessRecordsP(_stampRefsP(holon.workspace, ${foreignRefFields.length + atomicRefFields.length + versionedRefFields.length > 0 ? `_hydrateP(holon, ${expr})` : expr}))`;
   const wrapRows = (expr: string): string =>
-    `_businessRecords(_stampRefs(holon.workspace, ${foreignRefFields.length > 0 ? `_hydrateRows(holon, ${expr})` : expr}))`;
+    `_businessRecords(_stampRefs(holon.workspace, ${foreignRefFields.length + atomicRefFields.length + versionedRefFields.length > 0 ? `_hydrateRows(holon, ${expr})` : expr}))`;
   // ATTRIBUTED READS (architecture/field_provenance.md): the shared provenance shape +
   // per-aggregate accessors — emitted ONLY when the package declares ≥1 `.attributed()`
   // field, so a provenance-free package's client is byte-identical (the era rule).
@@ -2297,6 +2432,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       out.push(`  ${tsKey(name)}${required ? "" : "?"}: ${tsTypeOfField(field as Field)};`);
       const fr = (field as { foreignRef?: { workspaceField: string; targetAggregateId: string } }).foreignRef;
       if (fr !== undefined) foreignRefFields.push({ agg: typeId, field: name, workspaceField: fr.workspaceField, target: fr.targetAggregateId });
+      if ((field as Field).nomosRef !== undefined) atomicRefFields.push({ agg: typeId, field: name });
+      const vr = (field as Field).versionedForeignRef;
+      if (vr !== undefined) versionedRefFields.push({ agg: typeId, field: name, currentField: vr.currentField });
     }
     if (attributed.length > 0) {
       out.push(
@@ -2337,7 +2475,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   // row into a `ForeignRef<TargetAggregate>` — reading the foreign id (the field) + the foreign workspace id (the
   // declared sibling field). The read model stays honest (the field is the raw stored id string); this gives
   // the TYPED locator with resolve/watch on top, without cloning the other holon.
-  if (foreignRefFields.length > 0) {
+  if (foreignRefFields.length + atomicRefFields.length + versionedRefFields.length > 0) {
     const byAgg = new Map<string, typeof foreignRefFields>();
     for (const f of foreignRefFields) { const l = byAgg.get(f.agg) ?? []; l.push(f); byAgg.set(f.agg, l); }
     out.push(`// ── foreign-ref locators (t.foreignRef): typed cross-workspace edges (resolve/watch on demand) ──`);
@@ -2360,15 +2498,27 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     // `row.data.<field>.id` is still the raw id. Identity for any aggregate without foreignRefs.
     const hydrateSpecs: Record<string, { field: string; wsField: string; target: string }[]> = {};
     for (const f of foreignRefFields) { (hydrateSpecs[f.agg] ??= []).push({ field: f.field, wsField: f.workspaceField, target: f.target }); }
+    const atomicSpecs: Record<string, { field: string }[]> = {};
+    for (const f of atomicRefFields) { (atomicSpecs[f.agg] ??= []).push({ field: f.field }); }
+    const versionedSpecs: Record<string, { field: string; currentField: string }[]> = {};
+    for (const f of versionedRefFields) { (versionedSpecs[f.agg] ??= []).push({ field: f.field, currentField: f.currentField }); }
     out.push(
       `const _FOREIGN_REFS: Record<string, { field: string; wsField: string; target: string }[]> = ${JSON.stringify(hydrateSpecs)};`,
+      `const _ATOMIC_REFS: Record<string, { field: string }[]> = ${JSON.stringify(atomicSpecs)};`,
+      `const _VERSIONED_REFS: Record<string, { field: string; currentField: string }[]> = ${JSON.stringify(versionedSpecs)};`,
       `function _hydrateRows<T>(nomos: NomosForeignReader, rows: Row<T>[]): Row<T>[] {`,
       `  return rows.map((row) => {`,
       `    const raw = row as Row<T> & { type: string };`,
-      `    const specs = _FOREIGN_REFS[raw.type];`,
-      `    if (specs === undefined || row.data == null) return row;`,
+      `    const specs = _FOREIGN_REFS[raw.type] ?? [];`,
+      `    const atomic = _ATOMIC_REFS[raw.type] ?? [];`,
+      `    const versioned = _VERSIONED_REFS[raw.type] ?? [];`,
+      `    if ((specs.length + atomic.length + versioned.length) === 0 || row.data == null) return row;`,
       `    const data: Record<string, unknown> = { ...(row.data as Record<string, unknown>) };`,
       `    for (const s of specs) { const v = data[s.field]; if (typeof v === "string") data[s.field] = foreignRef(nomos, s.target, v, String(data[s.wsField] ?? "")); }`,
+      `    for (const s of atomic) { const v = data[s.field] as { workspace: string; type: string; id: string } | undefined; if (v && typeof v === "object") data[s.field] = _nmsRef(v.workspace, v.type, v.id); }`,
+      ...(hasVersionedRefs
+        ? [`    for (const s of versioned) { const v = data[s.field] as { pinned: _NomosRawAddress; series: _NomosRawAddress } | undefined; if (v && typeof v === "object") data[s.field] = _versionedNomosRef(nomos as NomosHolon, v, s.currentField); }`]
+        : []),
       `    return { ...row, data: data as T };`,
       `  });`,
       `}`,
@@ -2621,6 +2771,44 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     const runtimeTypeOf = (aggregate: AggregateHandle): string => isNamespacedAggregate(aggregate)
       ? qualifyReadProjectionType(domain, aggregate.id)
       : aggregate.id;
+    const versionedFactories = new Map<string, ReturnType<typeof versionedRefOfMetaOf>>();
+    for (const directive of dirs) {
+      if (!isBusinessIntent(directive)) continue;
+      const schema = (directive as { payloadSchema: z.ZodTypeAny }).payloadSchema;
+      if (zodKind(schema) !== "object") continue;
+      for (const [field, fieldSchema] of Object.entries(zodObjectShape(schema))) {
+        const meta = versionedRefOfMetaOf(fieldSchema as z.ZodTypeAny);
+        if (meta === undefined) continue;
+        const method = `pin${cap(camel(field))}`;
+        const prior = versionedFactories.get(method);
+        if (prior !== undefined && JSON.stringify(prior) !== JSON.stringify(meta)) {
+          throw new Error(`generated version-pin factory '${method}' names incompatible reference contracts`);
+        }
+        versionedFactories.set(method, meta);
+      }
+    }
+    for (const [method, meta] of [...versionedFactories].sort(([a], [b]) => a.localeCompare(b))) {
+      if (meta === undefined) continue;
+      const target = meta.targetKind === "contract"
+        ? contractTypeName(meta.targetAggregateType)
+        : meta.targetAggregateType;
+      const series = meta.seriesKind === "contract"
+        ? contractTypeName(meta.seriesAggregateType)
+        : meta.seriesAggregateType;
+      const seriesInput = meta.seriesKind === "contract"
+        ? meta.seriesAggregateType
+        : series;
+      methods.push(
+        `    /** Pin one immutable publication to its stable series. The current pointer is compiled law. */`,
+        `    ${method}: (pinned: NomosRef<${target}>, series: NomosRef<${seriesInput}>): VersionedNomosRef<${target}, ${series}> => {`,
+        `      const p = _nmsReferenceData(pinned); const s = _nmsReferenceData(series);`,
+        `      _nmsReferenceId(pinned, ${JSON.stringify(meta.targetAggregateType)}, "", "pinned");`,
+        `      _nmsReferenceId(series, ${JSON.stringify(meta.seriesAggregateType)}, "", "series");`,
+        `      if (p.workspace !== s.workspace) throw new TypeError("A version and its stable series must share one workspace");`,
+        `      return _versionedNomosRef<${target}, ${series}>(holon, { pinned: { workspace: p.workspace, type: p.type, id: p.id }, series: { workspace: s.workspace, type: s.type, id: s.id } }, ${JSON.stringify(meta.currentField)});`,
+        `    },`,
+      );
+    }
     // E2E READ INJECTION: the distinct encryption scopes a read of `typeId` must inject keys for (empty
     // ⇒ nothing encrypted on that type ⇒ the accessor is emitted plain, unchanged). The `_readKeys` helper
     // returns undefined when no keyStore is bound, so an injected accessor still behaves as today offline.
@@ -2739,13 +2927,21 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
             .filter(([name, field]) => name !== mint?.field && recipientMetaOf(field) !== undefined)
             .map(([name]) => name)
         : [];
+      const versionedReferencePayloadFields = zodKind(schema) === "object"
+        ? Object.entries(zodObjectShape(schema))
+            .filter(([name, field]) => name !== mint?.field && versionedRefOfMetaOf(field) !== undefined)
+            .map(([name]) => name)
+        : [];
       const wireReferences = (expr: string): string => {
         const references = referencePayloadFields.length === 0
           ? expr
           : `_nmsWireReferences(${expr}, ${JSON.stringify(referencePayloadTypes)}, holon.workspace)`;
-        return recipientPayloadFields.length === 0
+        const versioned = versionedReferencePayloadFields.length === 0
           ? references
-          : `_nmsWireRecipients(${references}, ${JSON.stringify(recipientPayloadFields)})`;
+          : `_nmsWireVersionedReferences(${references}, ${JSON.stringify(versionedReferencePayloadFields)})`;
+        return recipientPayloadFields.length === 0
+          ? versioned
+          : `_nmsWireRecipients(${versioned}, ${JSON.stringify(recipientPayloadFields)})`;
       };
       const stamps = autoStampFields(schema);
       const placed = placementDirs.has(d.id) ? ["shard"] : [];
@@ -2811,26 +3007,16 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       const ownedBirthPrelude = ownedBirthDescriptor === undefined
         ? ""
         : `      if (!holon.__nomosOwnedBirthScopeKey) throw new Error("this holon predates automatic .owned() birth custody — upgrade @githolon/client");\n` +
-          `      const _ownedBirthKey = await holon.__nomosOwnedBirthScopeKey({ scope: ${JSON.stringify(ownedBirthDescriptor.scope)}, namespace: ${JSON.stringify(businessBirth!.namespace)}, key: (${inputPayload} as Record<string, unknown>)[${JSON.stringify(businessBirth!.keyField)}] });`;
+          `      const _ownedBirthKey = await holon.__nomosOwnedBirthScopeKey({ scope: ${JSON.stringify(ownedBirthDescriptor.scope)}, namespace: ${JSON.stringify(businessBirth!.namespace)}, key: (${inputPayload} as Record<string, unknown>)[${JSON.stringify(businessBirth!.keyField)}], record: { type: ${JSON.stringify(ownedRuntimeType)}, id: ${JSON.stringify(businessBirth!.rootId)} } });`;
       const paramSig = `${argumentName}: ${payloadName}`;
-      const sourceQueryArgs = sourceTrust === undefined
-        ? ""
-        : Object.entries(sourceTrust.queryArgs)
-            .sort(([a], [b]) => a.localeCompare(b))
-            .map(([argument, field]) => `${JSON.stringify(argument)}: (${argumentName} as Record<string, unknown>)[${JSON.stringify(field)}]`)
-            .join(", ");
-      const sourceQueryReferenceTypes = sourceTrust === undefined
-        ? {}
-        : Object.fromEntries(Object.entries(sourceTrust.queryArgs).flatMap(([argument, field]) => {
-            const type = referencePayloadTypes[field];
-            return type === undefined ? [] : [[argument, type]];
-          }));
+      const payloadPath = (root: string, path: string): string =>
+        path.split(".").reduce((expr, part) => `${expr}[${JSON.stringify(part)}]`, `(${root} as { [key: string]: any })`);
       const copiedTrustFields = sourceTrust === undefined
         ? []
         : Object.entries(sourceTrust.copy)
             .sort(([a], [b]) => a.localeCompare(b))
             .map(([target, field]) =>
-              `        ${JSON.stringify(target)}: (${inputPayload} as Record<string, unknown>)[${JSON.stringify(field)}],`);
+              `        ${JSON.stringify(target)}: ${payloadPath(inputPayload, field)},`);
       const copiedTrustReferenceTypes = sourceTrust === undefined
         ? {}
         : Object.fromEntries(Object.entries(sourceTrust.copy).flatMap(([target, field]) => {
@@ -2840,25 +3026,23 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       const sourceTrustPrelude = sourceTrust === undefined
         ? []
         : [
-            `      const _sourceWorkspace = String((${inputPayload} as Record<string, unknown>)[${JSON.stringify(sourceTrust.fromPayload)}] ?? "");`,
+            `      const _sourceWorkspace = String(${payloadPath(inputPayload, sourceTrust.fromPayload)} ?? "");`,
             `      if (!_sourceWorkspace.trim()) throw new Error(${JSON.stringify(`${d.id} needs a source workspace`)});`,
-            `      const _sourceQueryArgs = _nmsWireReferences({ ${sourceQueryArgs} }, ${JSON.stringify(sourceQueryReferenceTypes)}, _sourceWorkspace);`,
-            `      const _sourceEntry = _nmsAttestedEntry(await holon.fetchAttestedRead(_sourceWorkspace, ${JSON.stringify(sourceTrust.queryId)}, _sourceQueryArgs));`,
+            `      const _sourceGenesis = await holon.__nomosWorkspaceGenesis(_sourceWorkspace);`,
             `      await _commit(holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(sourceTrust.viaDirectiveId)}, _nmsWireReferences({`,
             ...copiedTrustFields,
-            `        ${JSON.stringify(sourceTrust.genesisField)}: _nmsSourceGenesis(_sourceEntry),`,
-            `        ${JSON.stringify(sourceTrust.keyHashesField)}: [await _nmsSourceKeyHash(_sourceEntry)],`,
+            `        ${JSON.stringify(sourceTrust.genesisField)}: _sourceGenesis,`,
+            `        ${JSON.stringify(sourceTrust.keyHashesField)}: [${JSON.stringify("0".repeat(64))}],`,
             `      }, ${JSON.stringify(copiedTrustReferenceTypes)}, _sourceWorkspace), { domainHash, actor, returnCreated: true }) as Promise<_NomosRawWriteResult>);`,
           ];
-      const offerExtra = sourceTrust === undefined ? "" : ", attestations: [_sourceEntry]";
       const sealPrelude = wantSeal
         ? `      const _sealed = await _sealFields(holon, keyStore, ${encConst}[${JSON.stringify(domain)}].directives[${JSON.stringify(d.id)}] as Record<string, { scope: string; aggSid: string; fieldSid: string; owned?: true }>, ${inputPayload} as Record<string, unknown>, true${ownedBirthDescriptor !== undefined ? ", _ownedBirthKey" : ", undefined"}${ownedRecordPrelude ? ", _ownedRecord" : ""}) as ${payloadName};`
         : "";
       const pv = wantSeal ? "_sealed" : inputPayload;
       // MULTI-OUTPUT: name every aggregate this directive writes (primary marker target + declared
       // secondaryOutputs), so the frontend dev sees "writes A + B" at the call site (not one by convention).
-      const dd = d as unknown as { aggregateId: string; marker: string; secondaryOutputs?: readonly { aggregateId: string; marker: string; many?: true }[] };
-      const allOutputs = [{ aggregateId: dd.aggregateId, marker: dd.marker, many: false }, ...(dd.secondaryOutputs ?? []).map((output) => ({ ...output, many: output.many === true }))]
+      const dd = d as unknown as { aggregateId: string; marker: string; outputCardinality?: "many" | "optional"; secondaryOutputs?: readonly { aggregateId: string; marker: string; many?: true; optional?: true }[] };
+      const allOutputs = [{ aggregateId: dd.aggregateId, marker: dd.marker, many: dd.outputCardinality === "many", optional: dd.outputCardinality === "optional" }, ...(dd.secondaryOutputs ?? []).map((output) => ({ ...output, many: output.many === true, optional: output.optional === true }))]
         .filter((output) => publicAggregateIds.has(output.aggregateId))
         .filter((output, index, outputs) =>
           outputs.findIndex((candidate) => candidate.aggregateId === output.aggregateId) === index);
@@ -2886,7 +3070,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           resultMembers.add(field);
           return output.many
             ? `  readonly ${tsKey(field)}: readonly NomosRef<${output.aggregateId}>[];`
-            : `  readonly ${tsKey(field)}: NomosRef<${output.aggregateId}>;`;
+            : output.optional
+              ? `  readonly ${tsKey(field)}: NomosRef<${output.aggregateId}> | undefined;`
+              : `  readonly ${tsKey(field)}: NomosRef<${output.aggregateId}>;`;
         });
         out.push(
           `/** Every business record affected by \`${domain}/${d.id}\`. No ledger or transport receipt leaks through this type. */`,
@@ -2976,10 +3162,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           member: tsResultMemberName(output.aggregateId),
           type: output.aggregateId,
           ...(output.many ? { many: true } : {}),
+          ...(output.optional ? { optional: true } : {}),
         })));
         const mintedCall = hasBusinessResult
-          ? `_businessResult<${resultName}>(holon.workspace, ${resultSpec}, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor, returnCreated: true${offerExtra} }) as Promise<_NomosRawWriteResult>)`
-          : `_commit(holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor, returnCreated: true${offerExtra} }) as Promise<_NomosRawWriteResult>)`;
+          ? `_businessResult<${resultName}>(holon.workspace, ${resultSpec}, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor, returnCreated: true }) as Promise<_NomosRawWriteResult>)`
+          : `_commit(holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor, returnCreated: true }) as Promise<_NomosRawWriteResult>)`;
         methods.push(
           `    /** Author \`${domain}/${d.id}\`: the generated client MINTS \`${mint.field}\` internally`,
           `     *  — ids are not application input — ${hasBusinessResult ? `and returns its typed ${resultName}` : "and keeps framework write details private"}.${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
@@ -3004,10 +3191,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         member: tsResultMemberName(output.aggregateId),
         type: output.aggregateId,
         ...(output.many ? { many: true } : {}),
+        ...(output.optional ? { optional: true } : {}),
       })));
       const commitCall = hasBusinessResult
-        ? `_businessResult<${resultName}>(holon.workspace, ${resultSpec}, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true${offerExtra} }) as Promise<_NomosRawWriteResult>)`
-        : `_commit(holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true${offerExtra} }) as Promise<_NomosRawWriteResult>)`;
+        ? `_businessResult<${resultName}>(holon.workspace, ${resultSpec}, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true }) as Promise<_NomosRawWriteResult>)`
+        : `_commit(holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true }) as Promise<_NomosRawWriteResult>)`;
       const outcomeDoc =
         d.marker === "creates"
           ? `Author \`${domain}/${d.id}\`: the LAW mints the ${d.aggregateId ?? "aggregate"} identity and returns every affected business reference — no id input and no query-after.`
@@ -3066,7 +3254,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       const qOwned = qScopes.some((scope) => scope.owned === true);
       const qScopeJson = JSON.stringify(qScopes);
       methods.push(
-        `    /** Declared query \`${q.id}\` (indexed probe — routed by the read manifest).${qScopes.length ? " Encrypted fields decrypt automatically when this signed-in application holds their keys." : ""} */`,
+        `    /** @deprecated Whole-result reads scale with result size. Use ${lcFirst(camel(q.id))}Pages() for bounded UX.${qScopes.length ? " Encrypted fields decrypt automatically when this signed-in application holds their keys." : ""} */`,
         qScopes.length
           ? qOwned
             ? `    ${lcFirst(camel(q.id))}: async (params: { ${params} }) => ${wrapP(`_readWithOwnedKeys(holon, keyStore, ${qScopeJson}, (keys) => holon.query(${JSON.stringify(q.id)}, ${wireParams}, keys) as Promise<Row<${q.returns}>[]>)`)},`
@@ -3085,18 +3273,21 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
             : `        ${lcFirst(camel(q.id))}: async (params: { ${params} }) => ${wrapP(`historic.query(${JSON.stringify(q.id)}, ${wireParams}, await _readKeys(holon, keyStore, ${qScopeJson})) as Promise<Row<${q.returns}>[]>`)},`
           : `        ${lcFirst(camel(q.id))}: (params: { ${params} }) => ${wrapP(`historic.query(${JSON.stringify(q.id)}, ${wireParams}) as Promise<Row<${q.returns}>[]>`)},`,
       );
-      // THE LOGICAL PAGED ROW SURFACE (sharding §5.3, ruling 2 — slice 4): emitted
-      // ONLY for packed-taxonomy domains (taxonomy-free clients stay byte-identical).
-      // The dev sees ordinary pagination; the shard walk is the implementation.
-      if (anyPackedTaxonomy(modules)) {
-        methods.push(
-          `    /** \`${q.id}\`, paged at estate width (ruling 2): ordinary pagination, stable cursor. */`,
-          `    ${lcFirst(camel(q.id))}Pages: (params: { ${params} }, page?: { pageSize?: number; cursor?: string | null }) => {`,
-          `      if (!holon.pages) throw new Error("pages() needs the ROUTED holon - connect() to the logical (coordinator) workspace, not a shard");`,
-          `      return (holon.pages(${JSON.stringify(q.id)}, ${wireParams}, page) as Promise<{ rows: Row<${q.returns}>[]; cursor: string | null; done: boolean }>).then((result) => ({ ...result, rows: ${wrapRows("result.rows")} }));`,
-          `    },`,
-        );
-      }
+      const queryPageCall = qScopes.length
+        ? qOwned
+          ? `_readWithOwnedKeys(holon, keyStore, ${qScopeJson}, (keys) => (holon.queryPage ?? (() => { throw new Error("bounded reads need a current @githolon/client"); }))(${JSON.stringify(q.id)}, ${wireParams}, page, keys) as Promise<{ rows: Row<${q.returns}>[]; cursor: string | null; done: boolean }>)`
+          : `(holon.queryPage ?? (() => { throw new Error("bounded reads need a current @githolon/client"); }))(${JSON.stringify(q.id)}, ${wireParams}, page, await _readKeys(holon, keyStore, ${qScopeJson})) as Promise<{ rows: Row<${q.returns}>[]; cursor: string | null; done: boolean }>`
+        : `(holon.queryPage ?? (() => { throw new Error("bounded reads need a current @githolon/client"); }))(${JSON.stringify(q.id)}, ${wireParams}, page) as Promise<{ rows: Row<${q.returns}>[]; cursor: string | null; done: boolean }>`;
+      methods.push(
+        `    /** Bounded \`${q.id}\` read. This is the default estate-scale surface: stable opaque cursor, no whole-result hydration. */`,
+        `    ${lcFirst(camel(q.id))}Pages: async (params: { ${params} }, page: { pageSize?: number; cursor?: string | null } = {}) => {`,
+        // Parenthesize the asserted Promise before awaiting it. Without these parens TypeScript
+        // parses `await call as Promise<Page>` as `(await call) as Promise<Page>`, leaving `result`
+        // incorrectly typed as a Promise and making every generated `.rows` access invalid.
+        `      const result = await (${queryPageCall});`,
+        `      return { ...result, rows: ${wrapRows("result.rows")} };`,
+        `    },`,
+      );
     }
 
     for (const c of (mod.counts ?? []).map((raw) => finishCount(raw))) {
@@ -3482,6 +3673,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `function ${tsClientFactoryName(domain)}(holon: NomosHolon) {`,
       `  const domainHash = ${hashConst};`,
       `  const actor = holon.principal;`,
+      `  holon.prepareDomain?.(${JSON.stringify(domain)}, domainHash);`,
       ...(encPresent ? [`  const keyStore: NomosKeyStore | undefined = ${domScopes.length > 0 ? `{ scopeKey: async (scope) => { if (!holon.__nomosScopeKey) throw new Error("encrypted business data needs the current @githolon/client"); return holon.__nomosScopeKey({ scope }); }, readKeys: async (scopes) => { if (!holon.__nomosScopeKeys) throw new Error("encrypted business data needs the current @githolon/client"); return holon.__nomosScopeKeys({ scopes }); } }` : "undefined"};`] : []),
       ...(ownedScope !== undefined && Object.keys(ownedActions).length > 0
         ? [
@@ -3767,7 +3959,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       ` *  or parallel cache around it. Nomos owns offline custody and synchronization. */`,
       `export function ${applicationOpener}(options: ${applicationName}OpenOptions): Promise<${applicationName}> {`,
       `  return nomosInternalOpenGeneratedApplication(`,
-      `    { cloud: options.cloud, application: options.application, signIn: options.signIn },`,
+      `    { cloud: options.cloud, application: options.application, signIn: options.signIn, lawHash: ${hashConst} },`,
       `    (holon, user) => _nomosBind${applicationName}(holon as NomosHolon, user),`,
       `  );`,
       `}`,