@githolon/dsl 0.103.4 → 0.103.5

package/src/codegen_ts.ts

@@ -43,7 +43,7 @@ import {
   OWNED_PREMINTED_RECORDS_PAYLOAD_FIELD,
   type AggregateHandle,
 } from "./aggregate.js";
-import { isSha256DigestSchema, type Field, type ValueObjectDescriptor, type ValueObjectFieldDescriptor } from "./fields.js";
+import { isGitObjectIdSchema, 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, versionedRefOfMetaOf } from "./value_object.js";
+import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf, refOfMetaOf, versionedRefOfMetaOf } from "./value_object.js";
 import { recursiveTypeBaseName, zodUnwrapLazy } from "./zod_lazy.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
@@ -309,6 +309,14 @@ function tsTypeOfZod(
   path = "",
 ): string {
   if (isSha256DigestSchema(zt)) return "Sha256Digest";
+  if (isGitObjectIdSchema(zt)) return "GitObjectId";
+  const addressed = refOfMetaOf(zt);
+  if (addressed !== undefined) {
+    const target = addressed.targetKind === "contract"
+      ? contractTypeName(addressed.aggregateType)
+      : addressed.aggregateType;
+    return `NomosRef<${target}>`;
+  }
   const versioned = versionedRefOfMetaOf(zt);
   if (versioned !== undefined) {
     const target = versioned.targetKind === "contract"
@@ -544,7 +552,11 @@ function tsTypeOfField(field: Field): string {
 function tsBaseTypeOfField(field: Field): string {
   switch (field.kind) {
     case "string":
-      return isSha256DigestSchema(field.zod as z.ZodTypeAny) ? "Sha256Digest" : "string";
+      return isSha256DigestSchema(field.zod as z.ZodTypeAny)
+        ? "Sha256Digest"
+        : isGitObjectIdSchema(field.zod as z.ZodTypeAny)
+          ? "GitObjectId"
+          : "string";
     case "int":
       return "number";
     // STRUCTURAL CRDT scalars (read-collapsed): a counter reads as its net number, a position as its
@@ -801,11 +813,11 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[], describeM
     `type NomosModelAdoption =`,
     `  | { status: "adopted"; summary: string; review: NomosModelReview }`,
     `  | { status: "needs-decision"; summary: string; review: NomosModelReview; accept(because: string): Promise<NomosModelAdoption> }`,
-    `  | { status: "blocked"; summary: string; review: NomosModelReview };`,
+    `  | { status: "blocked"; summary: string; error: string; review: NomosModelReview };`,
     `type NomosModelRestoration =`,
     `  | { status: "restored"; summary: string; review: NomosModelReview }`,
     `  | { status: "needs-decision"; summary: string; review: NomosModelReview; accept(because: string): Promise<NomosModelRestoration> }`,
-    `  | { status: "blocked"; summary: string; review: NomosModelReview };`,
+    `  | { status: "blocked"; summary: string; error: string; review: NomosModelReview };`,
     `interface __NomosModelReportWire {`,
     `  sourceVerified: boolean; complete: boolean; promotable: boolean;`,
     `  replayedIntents: number; candidateIntents: number; evolve: { ok: boolean };`,
@@ -813,7 +825,7 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[], describeM
     `  divergences: { kind: string; domain?: string; directiveId?: string; admitted?: boolean }[];`,
     `}`,
     `interface __NomosModelAdoptionWire {`,
-    `  ok: boolean; stage: "promoted" | "identity" | "preflight" | "acceptance" | "admission";`,
+    `  ok: boolean; stage: "promoted" | "identity" | "staging-required" | "preflight" | "acceptance" | "admission";`,
     `  report?: __NomosModelReportWire; error?: string;`,
     `}`,
     `interface __NomosModelRestorationWire {`,
@@ -852,7 +864,8 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[], describeM
     `  holon: NomosHolon, domain: string, candidateHash: string, because?: string,`,
     `): Promise<NomosModelAdoption> {`,
     `  if (!holon.__nomosAdoptModel) {`,
-    `    return { status: "blocked", summary: "This device needs the current Nomos client before it can adopt a model.", review: _nomosModelReview() };`,
+    `    const error = "This device needs the current Nomos client before it can adopt a model.";`,
+    `    return { status: "blocked", summary: error, error, review: _nomosModelReview() };`,
     `  }`,
     `  const raw = await holon.__nomosAdoptModel(domain, candidateHash, because === undefined ? {} : { because });`,
     `  const review = _nomosModelReview(raw.report);`,
@@ -880,13 +893,14 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[], describeM
     `        : raw.report !== undefined && !raw.report.evolve.ok`,
     `          ? "This model cannot yet interpret every existing value. Nothing changed and the current model remains active."`,
     `          : "The workspace changed or refused this adoption. Nothing changed; ask Nomos to try again.";`,
-    `  return { status: "blocked", summary, review };`,
+    `  return { status: "blocked", summary, error: raw.error ?? summary, review };`,
     `}`,
     `async function _nomosRestorePreviousModel(`,
     `  holon: NomosHolon, domain: string, currentHash: string, because?: string,`,
     `): Promise<NomosModelRestoration> {`,
     `  if (!holon.__nomosRestorePreviousModel) {`,
-    `    return { status: "blocked", summary: "This device needs the current Nomos client before it can restore a model.", review: _nomosModelReview() };`,
+    `    const error = "This device needs the current Nomos client before it can restore a model.";`,
+    `    return { status: "blocked", summary: error, error, review: _nomosModelReview() };`,
     `  }`,
     `  const raw = await holon.__nomosRestorePreviousModel(domain, currentHash, because === undefined ? {} : { because });`,
     `  const review = _nomosModelReview(raw.report);`,
@@ -918,7 +932,7 @@ function emitTsActivityBlock(entries: readonly PackageActivityEntry[], describeM
     `            : raw.report !== undefined && !raw.report.evolve.ok`,
     `              ? "The previous model cannot safely interpret every existing value. Nothing changed and the current model remains active."`,
     `              : "The workspace refused restoration. Nothing changed and the current model remains active.";`,
-    `  return { status: "blocked", summary, review };`,
+    `  return { status: "blocked", summary, error: raw.error ?? summary, review };`,
     `}`,
     ``,
     `// ── activity feed (architecture/activity_descriptors.md) — typed rows folded from the intent log ──`,
@@ -1086,6 +1100,35 @@ function zodUsesSha256Digest(schema: z.ZodTypeAny, seen = new Set<z.ZodTypeAny>(
   }
 }
 
+/** Whether a schema contains the framework Git object-id semantic string. */
+function zodUsesGitObjectId(schema: z.ZodTypeAny, seen = new Set<z.ZodTypeAny>()): boolean {
+  if (seen.has(schema)) return false;
+  seen.add(schema);
+  if (isGitObjectIdSchema(schema)) return true;
+  switch (zodKind(schema)) {
+    case "optional":
+    case "default":
+    case "nullable": {
+      const inner = zodDef(schema).innerType;
+      return inner !== undefined && zodUsesGitObjectId(inner, seen);
+    }
+    case "array":
+      return zodUsesGitObjectId(zodArrayElement(schema), seen);
+    case "object":
+      return Object.values(zodObjectShape(schema)).some((field) => zodUsesGitObjectId(field, seen));
+    case "record": {
+      const value = zodDef(schema).valueType;
+      return value !== undefined && zodUsesGitObjectId(value, seen);
+    }
+    case "union":
+      return (zodDef(schema).options ?? []).some((option) => zodUsesGitObjectId(option, seen));
+    case "lazy":
+      return zodUsesGitObjectId(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
@@ -1219,6 +1262,17 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       return schema !== undefined && zodUsesSha256Digest(schema);
     }),
   );
+  const hasGitObjectIds = modules.some((module) =>
+    module.aggregates.some((aggregate) =>
+      Object.values(aggregate.fields as Record<string, Field>).some((field) =>
+        isGitObjectIdSchema(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 && zodUsesGitObjectId(schema);
+    }),
+  );
   const hasConflictResolvers = modules.some(
     (m) => ((m as { surfacedResolvers?: readonly unknown[] }).surfacedResolvers?.length ?? 0) > 0,
   );
@@ -1279,6 +1333,20 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           ``,
         ]
       : []),
+    ...(hasGitObjectIds
+      ? [
+          `/** A Git object address in the canonical gix custody spelling. */`,
+          `export type GitObjectId = string & { readonly __nomosGitObjectId: unique symbol };`,
+          `/** Validate and construct a GitObjectId before an offer is assembled. */`,
+          `export const gitObjectId = (value: string): GitObjectId => {`,
+          `  if (!/^[0-9a-f]{40}$/.test(value)) {`,
+          `    throw new TypeError("expected a 40-character lowercase hexadecimal Git object id");`,
+          `  }`,
+          `  return value as GitObjectId;`,
+          `};`,
+          ``,
+        ]
+      : []),
     `interface _NomosApplicationStatus {`,
     `  readonly phase: "opening" | "current" | "saving" | "receiving" | "catching-up" | "offline" | "attention";`,
     `  readonly localChanges: number;`,
@@ -1294,6 +1362,12 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  currentStatus(): Promise<_NomosApplicationStatus>;`,
     `  watchStatus(listener: (status: _NomosApplicationStatus) => void): () => void;`,
     `}`,
+    `interface _NomosApplicationModelLifecycle {`,
+    `  readonly model: {`,
+    `    adopt(): Promise<NomosModelAdoption>;`,
+    `    restorePrevious(): Promise<NomosModelRestoration>;`,
+    `  };`,
+    `}`,
     ...(hasInvitations
       ? [
           `interface _NomosApplicationInvitations {`,
@@ -2290,6 +2364,17 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `  }`,
       `  return out as T;`,
       `};`,
+      `const _nmsWireAddressReferences = <T extends object>(payload: T, fields: Readonly<Record<string, string>>): T => {`,
+      `  const out = { ...payload } as Record<string, unknown>;`,
+      `  for (const [field, expectedType] of Object.entries(fields)) {`,
+      `    const value = out[field];`,
+      `    if (value === undefined) continue;`,
+      `    _nmsReferenceId(value, expectedType, "", field);`,
+      `    const ref = value as { workspace: string; type: string; id: string };`,
+      `    out[field] = { workspace: ref.workspace, type: ref.type, id: ref.id };`,
+      `  }`,
+      `  return out as T;`,
+      `};`,
       ``,
     );
   }
@@ -2922,6 +3007,13 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
               ]),
           )
         : {};
+      const addressReferencePayloadTypes = zodKind(schema) === "object"
+        ? Object.fromEntries(
+            Object.entries(zodObjectShape(schema))
+              .filter(([name, field]) => name !== mint?.field && refOfMetaOf(field) !== undefined)
+              .map(([name, field]) => [name, refOfMetaOf(field)!.aggregateType]),
+          )
+        : {};
       const recipientPayloadFields = zodKind(schema) === "object"
         ? Object.entries(zodObjectShape(schema))
             .filter(([name, field]) => name !== mint?.field && recipientMetaOf(field) !== undefined)
@@ -2936,9 +3028,12 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         const references = referencePayloadFields.length === 0
           ? expr
           : `_nmsWireReferences(${expr}, ${JSON.stringify(referencePayloadTypes)}, holon.workspace)`;
-        const versioned = versionedReferencePayloadFields.length === 0
+        const addressed = Object.keys(addressReferencePayloadTypes).length === 0
           ? references
-          : `_nmsWireVersionedReferences(${references}, ${JSON.stringify(versionedReferencePayloadFields)})`;
+          : `_nmsWireAddressReferences(${references}, ${JSON.stringify(addressReferencePayloadTypes)})`;
+        const versioned = versionedReferencePayloadFields.length === 0
+          ? addressed
+          : `_nmsWireVersionedReferences(${addressed}, ${JSON.stringify(versionedReferencePayloadFields)})`;
         return recipientPayloadFields.length === 0
           ? versioned
           : `_nmsWireRecipients(${versioned}, ${JSON.stringify(recipientPayloadFields)})`;
@@ -3825,7 +3920,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       ),
       `type _${applicationName}Business = ${applicationType};`,
       `export type ${applicationName}Status = _NomosApplicationStatus;`,
-      `export type ${applicationName} = _${applicationName}Business & _NomosApplicationParticipant & _NomosApplicationLifecycle${hasInvitations ? " & _NomosApplicationInvitations" : ""};`,
+      `export type ${applicationName} = _${applicationName}Business & _NomosApplicationParticipant & _NomosApplicationLifecycle & _NomosApplicationModelLifecycle${hasInvitations ? " & _NomosApplicationInvitations" : ""};`,
       `export interface ${applicationName}OpenOptions {`,
       `  /** Nomos Cloud serving this deployed application. Configure it once at the app boundary. */`,
       `  readonly cloud: string;`,
@@ -3843,12 +3938,13 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `function _nomosBind${applicationName}(`,
       `  holon: NomosHolon,`,
       `  user: { readonly identityId: string; readonly identityAddress: string },`,
-      `): _${applicationName}Business & _NomosApplicationParticipant${hasInvitations ? " & _NomosApplicationInvitations" : ""} {`,
+      `): _${applicationName}Business & _NomosApplicationParticipant & _NomosApplicationModelLifecycle${hasInvitations ? " & _NomosApplicationInvitations" : ""} {`,
       ...clientDomains.map((domain, index) =>
         `  const _nmsRoot${index} = ${tsClientFactoryName(domain)}(holon);`),
       `  const domains = [${clientDomains.map((_domain, index) => `_nmsRoot${index}`).join(", ")}] as const;`,
       `  const application: Record<string, unknown> = {};`,
       `  application.currentUser = { identity: { id: user.identityId, address: user.identityAddress } } as User;`,
+      `  application.model = _nmsRoot${clientDomains.indexOf(homeDomain)}.model;`,
       ...(hasInvitations
         ? [
             `  for (const reserved of ["recipient", "createInvitation", "redeemInvitation"] as const) {`,
@@ -3875,14 +3971,14 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `  const routedOwnedActions = new Map<string, Array<(...args: unknown[]) => Promise<unknown>>>();`,
       `  for (const domain of domains) for (const [name, value] of Object.entries(domain)) {`,
       `    if (privateMembers.has(name)) continue;`,
-      `    if (name === "past") { pasts.push(value as typeof pasts[number]); continue; }`,
-      `    if (name === "conflicts") { conflictSets.push(value as Record<string, unknown>); continue; }`,
+      `    if (name === "past") { pasts.push(value as unknown as typeof pasts[number]); continue; }`,
+      `    if (name === "conflicts") { conflictSets.push(value as unknown as Record<string, unknown>); continue; }`,
       ...(hasCorrections
-        ? [`    if (name === "corrections") { correctionSets.push({ domain: String(domain.domain), value: value as typeof correctionSets[number]["value"] }); continue; }`]
+        ? [`    if (name === "corrections") { correctionSets.push({ domain: String(domain.domain), value: value as unknown as typeof correctionSets[number]["value"] }); continue; }`]
         : []),
       `    if (name === "share" || name === "unshare" || name === "transfer") {`,
       `      const candidates = routedOwnedActions.get(name) ?? [];`,
-      `      candidates.push(value as (...args: unknown[]) => Promise<unknown>); routedOwnedActions.set(name, candidates); continue;`,
+      `      candidates.push(value as unknown as (...args: unknown[]) => Promise<unknown>); routedOwnedActions.set(name, candidates); continue;`,
       `    }`,
       `    if (singletonMembers.has(name) && name in application) continue;`,
       `    if (name in application) throw new Error("Nomos application member collision: '" + name + "' is declared by more than one business domain; rename one of them");`,
@@ -3952,7 +4048,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `    }`,
       `    throw unsupported ?? new Error(name + " needs a generated owned record reference");`,
       `  };`,
-      `  return application as unknown as _${applicationName}Business & _NomosApplicationParticipant${hasInvitations ? " & _NomosApplicationInvitations" : ""};`,
+      `  return application as unknown as _${applicationName}Business & _NomosApplicationParticipant & _NomosApplicationModelLifecycle${hasInvitations ? " & _NomosApplicationInvitations" : ""};`,
       `}`,
       `/** Open the one durable, signed-in ${opts.packageName} business application.`,
       ` *  Keep and pass this object down as application state; do not create a repository, runtime host`,