@githolon/dsl 0.108.1 → 0.108.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.108.1",
+  "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/relations.ts

@@ -211,10 +211,20 @@ export const RelationshipSubjectValue = valueObject("RelationshipSubject", {
   ownedCustody: OwnedCustodyValue.optional(),
 });
 
+// Historical RelationTuple law declared this map value as `t.json()`, but the
+// kernel has always admitted and stored only the nominal RelationshipSubject
+// palette for this framework field. Keep that exact prior declaration as the
+// source of the explicit evolution edge: this is a type-disclosure refinement
+// of existing structured custody, not a JSON parser or a business-data cast.
+const LegacyRelationshipSubjects = t.map(t.json()).merge(MapOf(Lww));
+
 export const RelationTuple = aggregate("RelationTuple", {
   object: t.string().merge(Lww),
   relation: t.string().merge(Lww),
-  subjects: t.map(RelationshipSubjectValue.field()).merge(MapOf(Lww)),
+  subjects: t
+    .map(RelationshipSubjectValue.field())
+    .merge(MapOf(Lww))
+    .evolvesFrom(LegacyRelationshipSubjects),
 }).public();
 export type RelationTupleHandle = typeof RelationTuple;
 

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 },

package/src/stable_ids_for_module.ts

@@ -50,7 +50,16 @@ export function stableIdsForModule(mod: DomainModule): StableIds {
       const evolutions =
         handle === undefined || schema === undefined || driver === undefined || details === undefined
           ? []
-          : fieldEvolutionRules(handle, pf, aggSid, pf?.sid ?? mintFieldSid(aggSid, fieldName), details, driver, schema);
+          : fieldEvolutionRules(
+              handle,
+              pf,
+              aggSid,
+              pf?.sid ?? mintFieldSid(aggSid, fieldName),
+              details,
+              driver,
+              schema,
+              { aggregateId: agg.id, fieldName },
+            );
       fields[fieldName] = {
         sid: pf?.sid ?? mintFieldSid(aggSid, fieldName),
         ...(pf?.was !== undefined && pf.was.length > 0 ? { was: pf.was } : {}),
@@ -147,6 +156,7 @@ function fieldEvolutionRules(
   target: { contract: string; shape: unknown },
   driver: unknown,
   targetSchema: string,
+  identity: { aggregateId: string; fieldName: string },
 ): StableFieldEvolution[] {
   const bySource = new Map<string, StableFieldEvolution>();
   const add = (rule: StableFieldEvolution, origin: string) => {
@@ -172,7 +182,10 @@ function fieldEvolutionRules(
       source.contract,
       encodeDriver(declaration.source.driver),
     );
-    if (declaration.mode === "identity" && !safeIdentityProjection(source.shape, target.shape)) {
+    if (
+      declaration.mode === "identity" &&
+      !safeIdentityProjection(source.shape, target.shape, identity)
+    ) {
       throw new Error(
         `.evolvesFrom(source) is not a safe identity widening: some source values are not valid ` +
           `under the target field. Supply a finite business transform as the second argument.`,
@@ -247,12 +260,30 @@ function fieldEvolutionRules(
 
 /** Explicit identity projection: the tenant declares the business meaning is continuous;
  * the compiler still proves every old value is accepted and its physical decoding is unchanged. */
-function safeIdentityProjection(sourceShape: unknown, targetShape: unknown): boolean {
+function safeIdentityProjection(
+  sourceShape: unknown,
+  targetShape: unknown,
+  identity?: { aggregateId: string; fieldName: string },
+): boolean {
   if (sourceShape === null || targetShape === null || typeof sourceShape !== "object" || typeof targetShape !== "object") {
     return canonicalJson(sourceShape) === canonicalJson(targetShape);
   }
   const source = sourceShape as Record<string, unknown>;
   const target = targetShape as Record<string, unknown>;
+  // RelationTuple.subjects is a kernel-native framework palette, not a tenant
+  // JSON field. Historical DSL metadata called its map leaf `json`, while the
+  // kernel already admitted/stored only RelationshipSubject values. The typed
+  // value-object declaration therefore discloses the existing contract without
+  // changing physical decoding or widening what old writers can author. Keep
+  // this proof bound to the one kernel-special field; arbitrary JSON->VO
+  // narrowing remains refused below.
+  if (
+    identity?.aggregateId === "RelationTuple" &&
+    identity.fieldName === "subjects" &&
+    isRelationshipSubjectDisclosure(source, target)
+  ) {
+    return true;
+  }
   const physical = (shape: Record<string, unknown>) => {
     const { kind, mapValueKind, jsonShape, encrypted } = shape;
     // `t.ref` and `t.foreignRef` store the target aggregate id as the same Str
@@ -267,6 +298,21 @@ function safeIdentityProjection(sourceShape: unknown, targetShape: unknown): boo
     && jsonSchemaSubset(source.jsonSchema, target.jsonSchema);
 }
 
+function isRelationshipSubjectDisclosure(
+  source: Record<string, unknown>,
+  target: Record<string, unknown>,
+): boolean {
+  const targetVo = target.mapValueVo as
+    | { descriptor?: { name?: unknown } }
+    | undefined;
+  return source.kind === "map" &&
+    target.kind === "map" &&
+    source.mapValueKind === "json" &&
+    target.mapValueKind === "json" &&
+    source.mapValueVo === undefined &&
+    targetVo?.descriptor?.name === "RelationshipSubject";
+}
+
 /** Automatic widening is stricter: every non-schema business descriptor must remain
  * identical. Brands, units, references and null meaning require an explicit declaration. */
 function safeAutomaticWidening(sourceShape: unknown, targetShape: unknown): boolean {
@@ -310,7 +356,21 @@ function jsonSchemaSubset(source: unknown, target: unknown): boolean {
         return false;
       }
     }
-    if (s.additionalProperties !== false && t.additionalProperties === false) return false;
+    const sourceAdditional = s.additionalProperties;
+    const targetAdditional = t.additionalProperties;
+    if (sourceAdditional !== false) {
+      if (targetAdditional === false) return false;
+      if (targetAdditional !== undefined && targetAdditional !== true) {
+        if (
+          sourceAdditional === undefined ||
+          sourceAdditional === true ||
+          typeof sourceAdditional !== "object" ||
+          !jsonSchemaSubset(sourceAdditional, targetAdditional)
+        ) {
+          return false;
+        }
+      }
+    }
   }
   if (sourceTypes.has("array") && s.items !== undefined && t.items !== undefined) {
     if (!jsonSchemaSubset(s.items, t.items)) return false;