@githolon/dsl 0.108.2 → 0.108.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.108.2",
+  "version": "0.108.3",
   "type": "module",
   "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",

package/src/codegen_ts.ts

@@ -1127,6 +1127,9 @@ export interface TsClientOptions {
   /** Emit the structural holon factory for the compiler-owned headless artifact. The ordinary tenant
    * client leaves this false so framework transport types never enter its public declaration graph. */
   readonly exportHolonFactory?: boolean;
+  /** Emit only the fixed framework operator call set (identity, lifecycle and birth). This is the
+   * small server/operator companion: exact generated USDA calls, no application/read runtime. */
+  readonly frameworkOperatorOnly?: boolean;
   /** Exact law identities and paths from the same in-memory USDA render which produced the shipped
    * closure. This is compiler input for generated call encoders, never a checked-in sidecar. */
   readonly callUsda?: readonly {
@@ -2136,6 +2139,158 @@ export function generateTsClient(
       }
     }
   }
+  if (opts.frameworkOperatorOnly === true) {
+    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 capabilityReferenceTypes = new Set<string>();
+    for (const mod of modules) {
+      const domain = mod.domain ?? mod.name;
+      const law = callUsdaByDomain.get(domain);
+      if (law === undefined) continue;
+      const authored = authoredDirectivesByDomain.get(domain) ?? [];
+      for (const capability of mod.impureCapabilities ?? []) {
+        for (const receipt of [
+          capability.complete,
+          capability.fail,
+          capability.block,
+          capability.deadLetter,
+        ]) {
+          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`,
+            );
+          }
+          const payloadType = tsTypeOfPayload(
+            directive.payloadSchema as z.ZodTypeAny,
+            [],
+          );
+          for (const referenceType of payloadReferenceTypes(
+            directive.payloadSchema as z.ZodTypeAny,
+          )) {
+            capabilityReferenceTypes.add(referenceType);
+          }
+          capabilityReceiptByKey.set(`${domain}\u0000${receipt.id}`, {
+            domain,
+            directiveId: receipt.id,
+            payloadType,
+            encoder: emitTsCallUsdaEncoder(
+              law.graph,
+              law.paths,
+              domain,
+              receipt.id,
+              payloadType,
+            ),
+          });
+        }
+      }
+    }
+    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}".`,
+      `// No application runtime and no authority live here. Do not edit.`,
+      ``,
+      ...TS_CALL_USDA_PRELUDE,
+      `/** A SHA-256 digest in canonical Nomos wire form. */`,
+      `export type Sha256Digest = string & { readonly __nomosSha256Digest: unique symbol };`,
+      `/** A Git object address in canonical gix custody form. */`,
+      `export type GitObjectId = string & { readonly __nomosGitObjectId: unique symbol };`,
+      `/** Exact compiler-authored framework call. Bytes are internal transport, while callers retain the nominal method and payload type. */`,
+      `export interface NomosFrameworkCall<Domain extends string = string, Directive extends string = string> {`,
+      `  readonly domain: Domain;`,
+      `  readonly directive: Directive;`,
+      `  readonly canonicalUsda: Uint8Array;`,
+      `  readonly routingCandidates: readonly string[];`,
+      `}`,
+      `declare const _nomosAggregateType: unique symbol;`,
+      ...[...capabilityReferenceTypes].sort().map(
+        (id) => `export type ${id} = { readonly [_nomosAggregateType]?: ${JSON.stringify(id)} };`,
+      ),
+      `export interface NomosRef<TAggregate> {`,
+      `  readonly [_nomosAggregateType]: (aggregate: TAggregate) => TAggregate;`,
+      `  readonly workspace: string;`,
+      `  readonly type: string;`,
+      `  readonly id: string;`,
+      `  readonly address: string;`,
+      `}`,
+      `/** Construct a typed address after the operator has independently established that the referenced task exists. A reference is not authority. */`,
+      `export const nomosRef = <TAggregate>(workspace: string, type: string, id: string): NomosRef<TAggregate> => ({`,
+      `  workspace, type, id,`,
+      `  address: "nomos://" + encodeURIComponent(workspace) + "/" + encodeURIComponent(type) + "/" + encodeURIComponent(id),`,
+      `} as unknown as NomosRef<TAggregate>);`,
+      `const _nmsReferenceTypeMatches = (actual: string, expected: string): boolean =>`,
+      `  expected === "" || actual === expected || actual.endsWith("." + expected);`,
+      `const _nmsReferenceId = (value: unknown, expectedType: string, workspace: string, field: string): string => {`,
+      `  if (typeof value !== "object" || value === null) throw new TypeError(field + " must be a NomosRef");`,
+      `  const ref = value as { workspace?: unknown; type?: unknown; id?: unknown };`,
+      `  if (typeof ref.id !== "string" || ref.id.length === 0 || typeof ref.type !== "string" || ref.type.length === 0 || typeof ref.workspace !== "string" || ref.workspace.length === 0) throw new TypeError(field + " must carry a complete NomosRef { workspace, type, id }");`,
+      `  if (!_nmsReferenceTypeMatches(ref.type, expectedType)) throw new TypeError(field + " refers to " + ref.type + "; expected " + expectedType);`,
+      `  if (workspace !== "" && ref.workspace !== workspace) throw new TypeError(field + " belongs to workspace " + ref.workspace + "; this call is bound to " + workspace);`,
+      `  return ref.id;`,
+      `};`,
+      ...operatorEncoders.flatMap((entry) => entry.encoder.source),
+      ...capabilityReceipts.flatMap((entry) => entry.encoder.source),
+      `export const nomosFrameworkCalls = {`,
+      ...[...new Set(operatorDefinitions.map((entry) => entry.group))].flatMap(
+        (group) => [
+          `  ${group}: {`,
+          ...operatorDefinitions
+            .filter((entry) => entry.group === group)
+            .flatMap((definition) => {
+              const alternatives = operatorEncoders.filter(
+                (entry) => entry.group === group && entry.kind === definition.kind
+              );
+              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(
+                  (entry) =>
+                    `        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 + "'.");`,
+              `      }`,
+              `    },`,
+            ];
+            }),
+          `  },`,
+        ]
+      ),
+      `} 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);`,
+            `    },`,
+          ]),
+        `  },`,
+      ]),
+      `} as const;`,
+      ``,
+    ].join("\n");
+  }
   out.push(
     `// AUTO-GENERATED by nomos-compile — typed TS application implementation for package "${opts.packageName}".`,
     `// Regenerated on every compile; do not edit. Framework binding types below are deliberately private:`,

package/src/compile_package_main.ts

@@ -5646,6 +5646,9 @@ async function main(): Promise<void> {
   const headlessClientDeclarationPath = path.join(outDir, `${cfg.name}.headless.d.mts`);
   const operatorPath = path.join(outDir, `${cfg.name}.operator.mjs`);
   const operatorDeclarationPath = path.join(outDir, `${cfg.name}.operator.d.mts`);
+  const frameworkOperatorPath = path.join(outDir, `${cfg.name}.framework.mjs`);
+  const frameworkOperatorDeclarationPath = path.join(outDir, `${cfg.name}.framework.d.mts`);
+  const frameworkOperatorSourcePath = path.join(outDir, `${cfg.name}.framework.ts`);
   const clientOptions = {
     packageName: cfg.name,
     domainHash,
@@ -5665,6 +5668,10 @@ async function main(): Promise<void> {
     exportHolonFactory: true,
   });
   const operatorSource = generateTsLifecycleOperator(clientOptions.callUsda);
+  const frameworkOperatorSource = generateTsClient(presentationDomainModules, {
+    ...clientOptions,
+    frameworkOperatorOnly: true,
+  });
   const runtimePath = path.join(DSL_DIR, "runtime", "generated-application-host.js");
   if (!existsSync(runtimePath)) {
     fail("the compiler-private generated application runtime is missing — reinstall @githolon/dsl");
@@ -6050,6 +6057,43 @@ async function main(): Promise<void> {
       rmSync(operatorPath, { force: true });
       rmSync(operatorDeclarationPath, { force: true });
     }
+    const frameworkOperatorDeclaration = ts.transpileDeclaration(frameworkOperatorSource, {
+      fileName: `${cfg.name}.framework.ts`,
+      compilerOptions: {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.ESNext,
+        strict: true,
+      },
+      reportDiagnostics: true,
+    });
+    const frameworkOperatorErrors = (frameworkOperatorDeclaration.diagnostics ?? []).filter(
+      (diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error,
+    );
+    if (frameworkOperatorErrors.length > 0) {
+      fail(`generated TypeScript framework operator declarations are invalid — this is a Nomos codegen bug:\n${frameworkOperatorErrors.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")).join("\n")}`);
+    }
+    writeFileSync(frameworkOperatorDeclarationPath, frameworkOperatorDeclaration.outputText, "utf8");
+    writeFileSync(frameworkOperatorSourcePath, frameworkOperatorSource, "utf8");
+    await esbuildMod.build({
+      stdin: {
+        contents: frameworkOperatorSource,
+        loader: "ts",
+        resolveDir: outDir,
+        sourcefile: `${cfg.name}.framework.ts`,
+      },
+      outfile: frameworkOperatorPath,
+      bundle: true,
+      platform: "neutral",
+      format: "esm",
+      target: "es2022",
+      legalComments: "none",
+      logLevel: "silent",
+    });
+    writeFileSync(
+      frameworkOperatorPath,
+      canonicalizeGeneratedClientJavascript(readFileSync(frameworkOperatorPath, "utf8")),
+      "utf8",
+    );
   } catch (e) {
     fail(`generated TypeScript application could not be sealed — this is a Nomos codegen bug: ${(e as Error).message}`);
   } finally {

package/src/framework_call_definitions.ts

@@ -18,9 +18,10 @@ import {
   seedReceivingGroupPolicy,
 } from "./framework/home.js";
 import { enrollDelegation, enrollFirstDevice, enrollSigner } from "./framework/signing_identity.js";
+import { grantAdmin } from "./framework/workspaces.js";
 
 export interface FixedFrameworkCallDefinition {
-  readonly group: "identity" | "lifecycle" | "birth";
+  readonly group: "identity" | "governance" | "lifecycle" | "birth";
   readonly kind: string;
   readonly directive: Directive<any>;
   /** Needed by the pre-bind Dart birth ceremony before an application exists. */
@@ -40,6 +41,7 @@ export const fixedFrameworkCallDefinitions: readonly FixedFrameworkCallDefinitio
   { group: "identity", kind: "enrollSigner", directive: enrollSigner, dartBirth: true, requiredApplicationHome: true },
   { group: "identity", kind: "setAuthProvider", directive: setAuthProvider, requiredApplicationHome: true },
   { group: "identity", kind: "birthReceivingGroup", directive: receivingGroupBirth, dartBirth: true, requiredApplicationHome: true },
+  { group: "governance", kind: "grantAdmin", directive: grantAdmin },
   { group: "lifecycle", kind: "installDomain", directive: installDomain },
   { group: "lifecycle", kind: "stageDomain", directive: stageDomain },
   { group: "lifecycle", kind: "promoteDomain", directive: promoteDomain },