@githolon/dsl 0.108.4 → 0.108.6

package/src/codegen_dart_framework_calls.ts

@@ -10,7 +10,9 @@ import {
   type DartCallUsdaFieldAccess,
 } from "./codegen_call_usda.js";
 import type { LawGraph } from "./law_graph.js";
+import { isBusinessIntent } from "./intent.js";
 import { fixedFrameworkCallDefinitions } from "./framework_call_definitions.js";
+import { collectFixedFrameworkDartEnums } from "./framework_call_dart_enums.js";
 import { APPLICATION_HOME_DOMAIN } from "./framework/application_home_domain.js";
 import { workspaceSharingInvitationRedeemPayload } from "./workspace_sharing.js";
 import { zodArrayElement, zodDef, zodObjectShape } from "./zod_introspection.js";
@@ -104,6 +106,7 @@ export interface DartFrameworkCallLaw {
 export function generateDartApplicationFrameworkCalls(
   laws: readonly DartFrameworkCallLaw[],
 ): string | undefined {
+  const frameworkEnumDartTypes = collectFixedFrameworkDartEnums().dartTypes;
   const fixedEmitted = FIXED_CALLS.flatMap((definition) => laws.flatMap((law) => {
     const declares = law.graph.nodes.some((node) =>
       node.kind === "intent" &&
@@ -118,7 +121,7 @@ export function generateDartApplicationFrameworkCalls(
     }
     const fields = introspectPayload(
       directive.payloadSchema as z.ZodTypeAny,
-      new Map(),
+      frameworkEnumDartTypes,
     );
     const parameterType = (field: (typeof fields)[number]) => field.nullAdmits === true
       ? `NomosSlot<${field.dartType}>`
@@ -170,7 +173,67 @@ export function generateDartApplicationFrameworkCalls(
         routeByDirective: true as const,
       };
     }));
-  const emitted = [...fixedEmitted, ...invitationEmitted];
+  // Existing-home device recovery is APPLICATION LAW, not a framework backdoor.
+  // Select it structurally from the composed graph: an enrolled-device-authored
+  // public intent with no local effects, directing one or more atomic effects through
+  // the target child's verified-birth-parent recovery door. A recovery may need to
+  // advance several typed child-owned facts together (for example policy, signer, and
+  // verifier epoch); every target must independently declare the narrow recovery door.
+  // The host never chooses an operation name and the compiler refuses an ambiguous or
+  // differently-shaped candidate.
+  const recoveryCandidates = laws.flatMap((law) =>
+    (law.module.applicationIntents ?? []).flatMap((candidate) => {
+      if (
+        !isBusinessIntent(candidate) ||
+        candidate.offerAuthenticationProof !== "enrolledDevice" ||
+        candidate.steps.length !== 0 ||
+        candidate.workspaceEffects.length === 0 ||
+        !candidate.workspaceEffects.every(
+          (effect) => effect.target.acceptsVerifiedBirthParentRecoveryGate === true,
+        )
+      ) return [];
+      const fields = introspectPayload(candidate.contract.accepts, new Map());
+      if (
+        fields.length !== 1 ||
+        fields[0]!.name !== "user" ||
+        fields[0]!.dartType !== "String" ||
+        fields[0]!.shape !== "scalar" ||
+        fields[0]!.optional ||
+        fields[0]!.nullAdmits === true
+      ) {
+        throw new Error(
+          `Dart framework call codegen: existing receiving-group recovery intent '${candidate.id}' must accept exactly { user: string }`,
+        );
+      }
+      const payloadType = `({String user})`;
+      const access = new Map<string, DartCallUsdaFieldAccess>([[
+        "user",
+        { value: "payload.user" },
+      ]]);
+      const encoder = emitDartCallUsdaEncoder(
+        law.graph,
+        law.paths,
+        law.graph.domain.entity.label,
+        candidate.id,
+        payloadType,
+        access,
+      );
+      return [{
+        kind: "recoverExistingReceivingGroupDevice",
+        directive: candidate.id,
+        domain: law.graph.domain.entity.label,
+        fields,
+        payloadType,
+        encoder,
+        routeByDirective: false as const,
+      }];
+    }));
+  if (recoveryCandidates.length > 1) {
+    throw new Error(
+      `Dart framework call codegen: application composes ${recoveryCandidates.length} existing receiving-group recovery intents; exactly one is allowed`,
+    );
+  }
+  const emitted = [...fixedEmitted, ...invitationEmitted, ...recoveryCandidates];
   if (emitted.length === 0) return undefined;
 
   const certificateEntry = emitted.find((entry) =>
@@ -211,7 +274,10 @@ export function generateDartApplicationFrameworkCalls(
       .filter((definition) => definition.dartBirth === true)
       .map((definition) => [
         definition.kind,
-        introspectPayload(definition.directive.payloadSchema as z.ZodTypeAny, new Map()),
+        introspectPayload(
+          definition.directive.payloadSchema as z.ZodTypeAny,
+          frameworkEnumDartTypes,
+        ),
       ] as const),
   );
   // The runtime interface is deliberately exhaustive. A composed application implements every
@@ -221,10 +287,29 @@ export function generateDartApplicationFrameworkCalls(
     ...fixedFrameworkCallDefinitions
       .filter((definition) => definition.dartBirth === true)
       .map((definition) => definition.kind),
+    "recoverExistingReceivingGroupDevice",
     "redeemInvitation",
   ])].flatMap((kind) => {
     const alternatives = emitted.filter((entry) => entry.kind === kind);
-    const fields = alternatives[0]?.fields ?? fixedMethodFields.get(kind) ?? invitationContractFields;
+    const fields = alternatives[0]?.fields ?? fixedMethodFields.get(kind) ??
+      (kind === "recoverExistingReceivingGroupDevice"
+        ? [{ name: "user", dartType: "String", shape: "scalar", optional: false } satisfies PayloadFieldSpec]
+        : invitationContractFields);
+    if (kind === "recoverExistingReceivingGroupDevice") {
+      const recovery = alternatives[0];
+      return [
+        `  @override`,
+        `  NmsGeneratedCall recoverExistingReceivingGroupDevice({required String user}) {`,
+        ...(recovery === undefined
+          ? [`    throw StateError("The compiled application has no existing receiving-group device recovery law.");`]
+          : [
+              `    final payload = (user: user,);`,
+              `    return ${recovery.encoder.functionName}(payload);`,
+            ]),
+        `  }`,
+        ``,
+      ];
+    }
     const routeByDirective = kind === "redeemInvitation" || alternatives.some((entry) => entry.routeByDirective);
     const parameterType = (field: (typeof fields)[number]) => field.nullAdmits === true
       ? `NomosSlot<${field.dartType}>`

package/src/codegen_ts.ts

@@ -955,7 +955,7 @@ function tsBaseTypeOfField(field: Field): string {
 function tsQueryReferenceId(field: Field, expression: string): string {
   if (field.kind !== "ref") {
     throw new Error(
-      `TypeScript query codegen: '${expression}' is not a declared reference field`,
+      `TypeScript query codegen: '${expression}' is not a declared reference field`
     );
   }
   return field.foreignRef !== undefined
@@ -1980,7 +1980,7 @@ export function generateTsClient(
       .map((definition) => ({
         group: definition.group,
         kind: definition.kind,
-        directiveId: definition.directive.id,
+        directiveId: definition.routeId ?? definition.directive.id,
         payloadType: tsTypeOfPayload(
           definition.directive.payloadSchema as z.ZodTypeAny,
           []
@@ -2056,7 +2056,7 @@ export function generateTsClient(
   ];
   const fixedFrameworkPayloadSchemas = new Map<string, z.ZodTypeAny>(
     fixedFrameworkCallDefinitions.map((definition) => [
-      definition.directive.id,
+      definition.routeId ?? definition.directive.id,
       definition.directive.payloadSchema as z.ZodTypeAny,
     ])
   );
@@ -2140,19 +2140,27 @@ export function generateTsClient(
     }
   }
   if (opts.frameworkOperatorOnly === true) {
-    const fixedGroups = new Set(["identity", "governance", "lifecycle", "birth"]);
+    const fixedGroups = new Set([
+      "identity",
+      "governance",
+      "lifecycle",
+      "birth",
+    ]);
     const operatorDefinitions = frameworkCallMethodDefinitions.filter(
       (definition) => fixedGroups.has(definition.group)
     );
     const operatorEncoders = frameworkCallEncoders.filter((entry) =>
       fixedGroups.has(entry.group)
     );
-    const capabilityReceiptByKey = new Map<string, {
-      readonly domain: string;
-      readonly directiveId: string;
-      readonly payloadType: string;
-      readonly encoder: ReturnType<typeof emitTsCallUsdaEncoder>;
-    }>();
+    const capabilityReceiptByKey = new Map<
+      string,
+      {
+        readonly domain: string;
+        readonly directiveId: string;
+        readonly payloadType: string;
+        readonly encoder: ReturnType<typeof emitTsCallUsdaEncoder>;
+      }
+    >();
     const capabilityReferenceTypes = new Set<string>();
     for (const mod of modules) {
       const domain = mod.domain ?? mod.name;
@@ -2166,18 +2174,20 @@ export function generateTsClient(
           capability.block,
           capability.deadLetter,
         ]) {
-          const directive = authored.find((candidate) => candidate.id === receipt.id);
+          const directive = authored.find(
+            (candidate) => candidate.id === receipt.id
+          );
           if (directive === undefined) {
             throw new Error(
-              `TypeScript capability receipt codegen: '${domain}/${receipt.id}' has no authored directive`,
+              `TypeScript capability receipt codegen: '${domain}/${receipt.id}' has no authored directive`
             );
           }
           const payloadType = tsTypeOfPayload(
             directive.payloadSchema as z.ZodTypeAny,
-            [],
+            []
           );
           for (const referenceType of payloadReferenceTypes(
-            directive.payloadSchema as z.ZodTypeAny,
+            directive.payloadSchema as z.ZodTypeAny
           )) {
             capabilityReferenceTypes.add(referenceType);
           }
@@ -2190,14 +2200,16 @@ export function generateTsClient(
               law.paths,
               domain,
               receipt.id,
-              payloadType,
+              payloadType
             ),
           });
         }
       }
     }
-    const capabilityReceipts = [...capabilityReceiptByKey.values()].sort((left, right) =>
-      left.domain.localeCompare(right.domain) || left.directiveId.localeCompare(right.directiveId)
+    const capabilityReceipts = [...capabilityReceiptByKey.values()].sort(
+      (left, right) =>
+        left.domain.localeCompare(right.domain) ||
+        left.directiveId.localeCompare(right.directiveId)
     );
     return [
       `// AUTO-GENERATED by nomos-compile — exact framework operators for package "${opts.packageName}".`,
@@ -2216,9 +2228,14 @@ export function generateTsClient(
       `  readonly routingCandidates: readonly string[];`,
       `}`,
       `declare const _nomosAggregateType: unique symbol;`,
-      ...[...capabilityReferenceTypes].sort().map(
-        (id) => `export type ${id} = { readonly [_nomosAggregateType]?: ${JSON.stringify(id)} };`,
-      ),
+      ...[...capabilityReferenceTypes]
+        .sort()
+        .map(
+          (id) =>
+            `export type ${id} = { readonly [_nomosAggregateType]?: ${JSON.stringify(
+              id
+            )} };`
+        ),
       `export interface NomosRef<TAggregate> {`,
       `  readonly [_nomosAggregateType]: (aggregate: TAggregate) => TAggregate;`,
       `  readonly workspace: string;`,
@@ -2251,42 +2268,59 @@ export function generateTsClient(
             .filter((entry) => entry.group === group)
             .flatMap((definition) => {
               const alternatives = operatorEncoders.filter(
-                (entry) => entry.group === group && entry.kind === definition.kind
+                (entry) =>
+                  entry.group === group && entry.kind === definition.kind
               );
-              const domainType = alternatives
-                .map((entry) => JSON.stringify(entry.domain))
-                .join(" | ") || "never";
+              const domainType =
+                alternatives
+                  .map((entry) => JSON.stringify(entry.domain))
+                  .join(" | ") || "never";
               return [
-              `    ${definition.kind}(input: { readonly domain: ${domainType}; readonly workspace: string } & ${definition.payloadType}): NomosFrameworkCall<${domainType}, ${JSON.stringify(definition.directiveId)}> {`,
-              `      const { domain, workspace, ...payload } = input;`,
-              `      switch (domain) {`,
-              ...alternatives
-                .map(
+                `    ${
+                  definition.kind
+                }(input: { readonly domain: ${domainType}; readonly workspace: string } & ${
+                  definition.payloadType
+                }): NomosFrameworkCall<${domainType}, ${JSON.stringify(
+                  definition.directiveId
+                )}> {`,
+                `      const { domain, workspace, ...payload } = input;`,
+                `      switch (domain) {`,
+                ...alternatives.map(
                   (entry) =>
-                    `        case ${JSON.stringify(entry.domain)}: return ${entry.encoder.functionName}(payload, workspace);`
+                    `        case ${JSON.stringify(entry.domain)}: return ${
+                      entry.encoder.functionName
+                    }(payload, workspace);`
                 ),
-              `        default: throw new Error("The compiled application has no '${definition.kind}' call in domain '" + domain + "'.");`,
-              `      }`,
-              `    },`,
-            ];
+                `        default: throw new Error("The compiled application has no '${definition.kind}' call in domain '" + domain + "'.");`,
+                `      }`,
+                `    },`,
+              ];
             }),
           `  },`,
         ]
       ),
       `} as const;`,
       `export const nomosCapabilityReceipts = {`,
-      ...[...new Set(capabilityReceipts.map((entry) => entry.domain))].flatMap((domain) => [
-        `  ${tsKey(domain)}: {`,
-        ...capabilityReceipts
-          .filter((entry) => entry.domain === domain)
-          .flatMap((entry) => [
-            `    ${tsKey(entry.directiveId)}(input: { readonly workspace: string } & ${entry.payloadType}): NomosFrameworkCall<${JSON.stringify(domain)}, ${JSON.stringify(entry.directiveId)}> {`,
-            `      const { workspace, ...payload } = input;`,
-            `      return ${entry.encoder.functionName}(payload, workspace);`,
-            `    },`,
-          ]),
-        `  },`,
-      ]),
+      ...[...new Set(capabilityReceipts.map((entry) => entry.domain))].flatMap(
+        (domain) => [
+          `  ${tsKey(domain)}: {`,
+          ...capabilityReceipts
+            .filter((entry) => entry.domain === domain)
+            .flatMap((entry) => [
+              `    ${tsKey(
+                entry.directiveId
+              )}(input: { readonly workspace: string } & ${
+                entry.payloadType
+              }): NomosFrameworkCall<${JSON.stringify(
+                domain
+              )}, ${JSON.stringify(entry.directiveId)}> {`,
+              `      const { workspace, ...payload } = input;`,
+              `      return ${entry.encoder.functionName}(payload, workspace);`,
+              `    },`,
+            ]),
+          `  },`,
+        ]
+      ),
       `} as const;`,
       ``,
     ].join("\n");
@@ -3514,10 +3548,7 @@ export function generateTsClient(
                 : ("string" as const),
             value:
               kind === "reference"
-                ? tsQueryReferenceId(
-                    field,
-                    `input[${JSON.stringify(key)}]`,
-                  )
+                ? tsQueryReferenceId(field, `input[${JSON.stringify(key)}]`)
                 : `input[${JSON.stringify(key)}]`,
             kind,
           };
@@ -5144,25 +5175,69 @@ export function generateTsClient(
                   `TypeScript source-trust codegen: '${domain}/${sourceTrust.viaDirectiveId}' has no nominal encoder`
                 );
               }
+              const satisfactionQuery =
+                sourceTrust.satisfiedByQueryId === undefined
+                  ? undefined
+                  : (mod.queries as QueryDecl[]).find(
+                      (query) => query.id === sourceTrust.satisfiedByQueryId
+                    );
+              if (
+                sourceTrust.satisfiedByQueryId !== undefined &&
+                satisfactionQuery === undefined
+              ) {
+                throw new Error(
+                  `TypeScript source-trust codegen: '${domain}/${d.id}' names missing satisfaction query '${sourceTrust.satisfiedByQueryId}'`
+                );
+              }
+              if (
+                satisfactionQuery !== undefined &&
+                satisfactionQuery.returns !==
+                  authoredDirectivesByDomain
+                    .get(domain)
+                    ?.find(
+                      (directive) => directive.id === sourceTrust.viaDirectiveId
+                    )?.aggregateId
+              ) {
+                throw new Error(
+                  `TypeScript source-trust codegen: '${domain}/${d.id}' satisfaction query '${satisfactionQuery.id}' does not return the trust aggregate`
+                );
+              }
+              const satisfactionArgs = sourceTrust.satisfiedByQueryArgs ?? {};
+              if (
+                satisfactionQuery !== undefined &&
+                (satisfactionQuery.key.some(
+                  (key) => satisfactionArgs[key] === undefined
+                ) ||
+                  Object.keys(satisfactionArgs).some(
+                    (key) => !satisfactionQuery.key.includes(key)
+                  ))
+              ) {
+                throw new Error(
+                  `TypeScript source-trust codegen: '${domain}/${d.id}' satisfaction query '${satisfactionQuery.id}' has mismatched keys`
+                );
+              }
+              // A typed satisfaction query makes source trust a law fact. The
+              // kernel's foreign-read policy gates the single business offer;
+              // the client must not query and silently grant authority first.
+              if (satisfactionQuery !== undefined) return [];
+              const indent = "      ";
               return [
-                `      const _sourceWorkspace = String(${payloadPath(
+                `${indent}const _sourceWorkspace = String(${payloadPath(
                   inputPayload,
                   sourceTrust.fromPayload
                 )} ?? "");`,
-                `      if (!_sourceWorkspace.trim()) throw new Error(${JSON.stringify(
+                `${indent}if (!_sourceWorkspace.trim()) throw new Error(${JSON.stringify(
                   `${d.id} needs a source workspace`
                 )});`,
-                `      const _sourceGenesis = await holon.__nomosWorkspaceGenesis(_sourceWorkspace);`,
-                `      const _sourceTrustCall = {`,
+                `${indent}const _sourceGenesis = await holon.__nomosWorkspaceGenesis(_sourceWorkspace);`,
+                `${indent}const _sourceTrustCall = {`,
                 ...copiedTrustFields,
-                `        ${JSON.stringify(
+                `${indent}  ${JSON.stringify(
                   sourceTrust.genesisField
                 )}: _sourceGenesis,`,
-                `        ${JSON.stringify(
-                  sourceTrust.keyHashesField
-                )}: [],`,
-                `      } satisfies ${payloadType};`,
-                `      await _commit(holon.offerCall(${encoder}(_sourceTrustCall, holon.workspace), { domainHash, actor, returnCreated: true }) as Promise<_NomosRawWriteResult>);`,
+                `${indent}  ${JSON.stringify(sourceTrust.keyHashesField)}: [],`,
+                `${indent}} satisfies ${payloadType};`,
+                `${indent}await _commit(holon.offerCall(${encoder}(_sourceTrustCall, holon.workspace), { domainHash, actor, returnCreated: true }) as Promise<_NomosRawWriteResult>);`,
               ];
             })();
       const sealPrelude =