@githolon/dsl 0.102.4 → 0.103.0

package/src/engine_entry.ts

@@ -63,13 +63,7 @@ import { synthesizeBirthQuotaInvariants } from "./birth_meter.js";
 import { withBirthMeterExports } from "./birth_meter_ensure.js";
 import { expandRoleExports } from "./role.js";
 import { withAttestedReadExports } from "./attested.js";
-import { generateOpenApiFragment, mergeOpenApiFragments, type OpenApiDoc } from "./codegen_openapi.js";
-import type { QueryDecl } from "./query.js";
-import type { AnyCount } from "./count.js";
-import type { AnySum } from "./sum.js";
-import type { AnyExtremum } from "./extremum.js";
-import type { SpatialDecl } from "./spatial.js";
-import type { DomainModule } from "./codegen_dart.js";
+import type { OpenApiDoc } from "./codegen_openapi.js";
 import type { Directive } from "./directive.js";
 import type { AggregateHandle, AggregateInvariantFn, AggregateInvariantVerdict } from "./aggregate.js";
 import type { Ports } from "./ctx.js";
@@ -84,6 +78,7 @@ import { expandBusinessBirthExports, isBusinessBirthDirective } from "./business
 import { withOwnedCustodyExports } from "./framework/owned_custody.js";
 import { withBusinessCorrectionExports } from "./framework/business_corrections.js";
 import { withClearDirectives } from "./clear_directive.js";
+import { withWorkspaceSharingInvitationExports } from "./workspace_sharing.js";
 import {
   applicationLanguageOf,
   assertApplicationLanguageCoversAuthoredDirectives,
@@ -123,6 +118,19 @@ export interface EngineRouting {
   readonly relationOf?: Record<string, readonly string[]>;
   /** workspace-invariant id → declaring domain keys (#266 — the gate's reads/assert dispatches). */
   readonly workspaceInvariantOf?: Record<string, readonly string[]>;
+  /**
+   * Dispatch-domain label → canonical USDA domain identity (`d_<sid>`). Tuple object types use this
+   * durable namespace so a domain rename cannot rewrite Zanzibar identity.
+   */
+  readonly relationNamespaceOf?: Record<string, string>;
+  /**
+   * Domain key → every non-global aggregate type in the complete compiled domain. A selectively
+   * sliced plan may retain a secondary aggregate only inside a closure, so reconstructing this set
+   * from the slice's exported declarations can silently lose the type's namespace.
+   */
+  readonly namespacedAggregatesOf?: Record<string, readonly string[]>;
+  /** Domain key → every local relation shape in the complete compiled domain, for the same reason. */
+  readonly qualifiableRelationsOf?: Record<string, readonly string[]>;
 }
 
 /** The one declarative input: dispatch key → ORDERED module list (later wins). */
@@ -133,6 +141,19 @@ export interface EngineEntryConfig {
    * Values may be thunks (lazy boot — see the module header).
    */
   readonly domains: Record<string, readonly DomainModuleSource[]>;
+  /**
+   * Compiler-authenticated exact routes may share one domain-agnostic framework plan. When the
+   * requested dispatch domain is absent from `domains`, prepare and execute this sole registry while
+   * retaining the requested domain for relation namespacing. Never authored by tenant code.
+   */
+  readonly routedDomainFallback?: string;
+  /**
+   * Domain-local dependency initializers emitted by the compiler. They run one per
+   * `prepareDomain()` call before the domain's composable sources and their exports are discarded.
+   * This turns a tenant module's cross-domain ES import closure into bounded maintenance quanta
+   * without registering the imported domain's declarations in the caller's slice.
+   */
+  readonly preloads?: Record<string, readonly (() => unknown)[]>;
   /** Optional report registry: `reportId` → a factory `(actor) => Report`. */
   readonly reports?: Record<string, (actor: string) => EngineReport>;
   /** REQUIRED when any domain module is a thunk; ignored otherwise. */
@@ -147,16 +168,11 @@ export interface EngineEntryConfig {
    */
   readonly seeds?: readonly unknown[];
   /**
-   * THE SELF-DESCRIBE INPUT (G1 — openapi residue removal): the per-domain read/maintenance
-   * decls the OpenAPI fragment needs that are NOT discoverable by shape from the live module
-   * exports alone (queries/counts/sums/mins/maxes/spatials/workspaceInvariants — the compiler
-   * already auto-discovered + named-resolved them when it composed each DomainModule). The
-   * directives + aggregates ARE discovered from the modules; these ride alongside so the
-   * lump's `globalThis.describe` reproduces the EXACT `<name>.openapi.json` the compiler wrote
-   * (byte-identity, no Rust re-implementation, no drift). Keyed by domain dispatch key, in the
-   * same declaration order as `domains`. Omitted ⇒ describe still emits offers from directives.
+   * Compiler-derived self-description. It is a presentation projection held inside the separately
+   * routed `describe` plan, never executable law IR. Ordinary offer/read plans omit it completely,
+   * so OpenAPI/JSON-Schema generation cannot sit on their parse or readiness flame path.
    */
-  readonly openapiDecls?: Record<string, OpenApiDomainDecls>;
+  readonly openapiDocument?: OpenApiDoc;
   /**
    * The package's OpenAPI document title (the compiler's `"<name> (nomos package)"`). Baked into
    * the lump so `describe` reproduces the compiler's `<name>.openapi.json` byte-for-byte without
@@ -165,17 +181,6 @@ export interface EngineEntryConfig {
   readonly packageTitle?: string;
 }
 
-/** The openapi-relevant decls one domain contributes beyond its directives/aggregates. */
-export interface OpenApiDomainDecls {
-  readonly queries?: readonly QueryDecl[];
-  readonly counts?: readonly AnyCount[];
-  readonly sums?: readonly AnySum[];
-  readonly mins?: readonly AnyExtremum[];
-  readonly maxes?: readonly AnyExtremum[];
-  readonly spatials?: readonly SpatialDecl[];
-  readonly workspaceInvariants?: readonly WorkspaceInvariantDecl[];
-}
-
 interface RegistryEntry {
   directive: Directive<unknown>;
   agg: AggregateHandle;
@@ -264,6 +269,7 @@ function mergeModules(mods: readonly DomainModuleExports[], domain: string): Dom
       [...directivesOf(merged).values()],
       domain,
     );
+    merged = withWorkspaceSharingInvitationExports(merged, applicationLanguage.workspaceSharing);
   }
   merged = expandBusinessBirthExports(merged, domain);
   merged = withOwnedCustodyExports(merged);
@@ -327,6 +333,20 @@ function buildDomainSlice(mod: DomainModuleExports, domain: string): DomainSlice
     ? discoveredDirectives
     : executableDirectivesForLanguage(applicationLanguage, discoveredDirectives, domain);
   const dirs = new Map(executableDirectives.map((directive) => [directive.id, directive]));
+  // A directive already owns the typed aggregate handle it targets. Retain that
+  // link unconditionally in the EXECUTABLE slice instead of requiring a second
+  // aggregate re-export. For a cross-workspace birth this does not copy child
+  // schema into the parent's canonical law: it only gives this selected runtime
+  // plan enough structure to register and validate its declared offer. Canonical
+  // package composition keeps its separate child-law dependency rule.
+  for (const directive of discoveredDirectives) {
+    if (directive.aggregate !== undefined) {
+      aggs.set(directive.aggregate.id, directive.aggregate);
+    }
+    for (const output of directive.secondaryOutputs ?? []) {
+      if (output.aggregate !== undefined) aggs.set(output.aggregate.id, output.aggregate);
+    }
+  }
   // RELATIONS AUTO-ENSURE (mirror of composeDomainModule): a relate-family directive `.ensures(RelationTuple)`
   // needs the framework aggregate registered for DISPATCH too — without it the directive is silently dropped
   // below. Inject iff a directive targets it and the dev didn't already export the handle.
@@ -496,12 +516,16 @@ export function collectEngineRouting(
   const aggregateInvariantOf: Record<string, string[]> = {};
   const relationOf: Record<string, string[]> = {};
   const workspaceInvariantOf: Record<string, string[]> = {};
+  const namespacedAggregatesOf: Record<string, string[]> = {};
+  const qualifiableRelationsOf: Record<string, string[]> = {};
   const add = (map: Record<string, string[]>, key: string, domainName: string) => {
     const list = map[key] ?? (map[key] = []);
     if (!list.includes(domainName)) list.push(domainName);
   };
   for (const [domainName, mods] of Object.entries(domains)) {
     const slice = buildDomainSlice(mergeModules(mods, domainName), domainName);
+    namespacedAggregatesOf[domainName] = [...slice.qualifiableAggregates].sort();
+    qualifiableRelationsOf[domainName] = [...slice.qualifiableRelations].sort();
     // Type-keyed dispatches arrive with the ROW's type — QUALIFIED for a namespaced aggregate (the
     // runtime `__type` stamp), bare for a global one / a pre-namespacing row. Route BOTH keys so
     // either era resolves to the declaring domain (the slice lookup strips the qualifier back off).
@@ -513,7 +537,15 @@ export function collectEngineRouting(
     for (const relationId of slice.invariants.keys()) add(relationOf, relationId, domainName);
     for (const wsInvariantId of slice.wsInvariants.keys()) add(workspaceInvariantOf, wsInvariantId, domainName);
   }
-  return { derivedOf, combinedOf, aggregateInvariantOf, relationOf, workspaceInvariantOf };
+  return {
+    derivedOf,
+    combinedOf,
+    aggregateInvariantOf,
+    relationOf,
+    workspaceInvariantOf,
+    namespacedAggregatesOf,
+    qualifiableRelationsOf,
+  };
 }
 
 /**
@@ -551,6 +583,10 @@ function portsFromHost(principalRaw = ""): Ports {
 export interface RegisteredEngine {
   plan(job: unknown): WireEvent[] | { events: WireEvent[]; strikes?: string[]; endorse?: { sink: string; facet: string; reason: string | null }[] };
   planReport(job: unknown): string;
+  /** Initialize at most one lazy dependency/module, or compose an initialized domain slice. */
+  prepareDomain(domain: string): { complete: boolean; initialized: number; total: number };
+  /** Compiler/tooling probe: force one domain and prove an exact routed offer is registered. */
+  hasDirective(domain: string, directiveId: string): boolean;
   /** The G1 self-describe verb: the lump's own merged OpenAPI, derived from its modules. */
   describe(opts?: { lawHash?: string; title?: string }): OpenApiDoc;
 }
@@ -565,6 +601,8 @@ export interface RegisteredEngine {
  */
 export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
   const domainNames = Object.keys(config.domains);
+  const sourceDomainFor = (requested: string): string =>
+    config.domains[requested] !== undefined ? requested : (config.routedDomainFallback ?? requested);
   const lazy = Object.values(config.domains).some((mods) =>
     mods.some((m) => typeof m === "function"),
   );
@@ -581,15 +619,61 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
 
   // ── domain key → its slice (forced once per sandbox; eager boot forces ALL now) ──
   const sliceCache = new Map<string, DomainSlice>();
+  const initializedPreloads = new Map<string, number>();
+  const initializedSources = new Map<string, DomainModuleExports[]>();
+  function prepareDomain(domainName: string): { complete: boolean; initialized: number; total: number } {
+    domainName = sourceDomainFor(domainName);
+    const sources = config.domains[domainName];
+    if (sources === undefined) return { complete: true, initialized: 0, total: 0 };
+    const preloads = config.preloads?.[domainName] ?? [];
+    const total = preloads.length + sources.length;
+    if (sliceCache.has(domainName)) {
+      return { complete: true, initialized: total, total };
+    }
+    const preloaded = initializedPreloads.get(domainName) ?? 0;
+    if (preloaded < preloads.length) {
+      preloads[preloaded]!();
+      initializedPreloads.set(domainName, preloaded + 1);
+      return { complete: false, initialized: preloaded + 1, total };
+    }
+    let initialized = initializedSources.get(domainName);
+    if (initialized === undefined) {
+      initialized = [];
+      initializedSources.set(domainName, initialized);
+    }
+    if (initialized.length < sources.length) {
+      const source = sources[initialized.length]!;
+      initialized.push(typeof source === "function" ? source() : source);
+      return { complete: false, initialized: preloads.length + initialized.length, total };
+    }
+    const slice = buildDomainSlice(mergeModules(initialized, domainName), domainName);
+    // The compiler computes these classifications from the complete domain before plan slicing.
+    // Prefer that authenticated inventory over the reduced export bag: a closure-retained secondary
+    // aggregate/relation is executable law even when tree-shaking removes its top-level export.
+    const compiledAggregates = routing.namespacedAggregatesOf?.[domainName];
+    if (compiledAggregates !== undefined) {
+      slice.qualifiableAggregates = new Set(compiledAggregates);
+    }
+    const compiledRelations = routing.qualifiableRelationsOf?.[domainName];
+    if (compiledRelations !== undefined) {
+      slice.qualifiableRelations = new Set(compiledRelations);
+    }
+    sliceCache.set(domainName, slice);
+    initializedSources.delete(domainName);
+    initializedPreloads.delete(domainName);
+    return { complete: true, initialized: total, total };
+  }
   function sliceOf(domainName: string): DomainSlice | undefined {
+    domainName = sourceDomainFor(domainName);
     const cached = sliceCache.get(domainName);
     if (cached !== undefined) return cached;
     const sources = config.domains[domainName];
     if (sources === undefined) return undefined;
-    const forced = sources.map((m) => (typeof m === "function" ? m() : m));
-    const slice = buildDomainSlice(mergeModules(forced, domainName), domainName);
-    sliceCache.set(domainName, slice);
-    return slice;
+    while (!prepareDomain(domainName).complete) { /* synchronous compatibility lane */ }
+    return sliceCache.get(domainName);
+  }
+  function hasDirective(domainName: string, directiveId: string): boolean {
+    return sliceOf(domainName)?.registry.has(directiveId) === true;
   }
   if (!lazy) for (const domainName of domainNames) sliceOf(domainName);
 
@@ -698,23 +782,9 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     return found;
   }
 
-  // ── the three WORKSPACE-INVARIANT dispatches (#266 — wire shapes are the gate oracle's
-  //    contract, EXACT: see admission-peer EngineWorkspaceInvariant + plan_workspace_invariant*) ──
-
-  /** `{workspaceInvariantList:{}}` → the DECLARED set `[{id,on},…]` sorted by id (discovery). */
-  function planWorkspaceInvariantList(): string {
-    const declared = new Map<string, { id: string; on: string }>();
-    const domains =
-      routing.workspaceInvariantOf !== undefined
-        ? [...new Set(Object.values(routing.workspaceInvariantOf).flat())]
-        : domainNames;
-    for (const domainName of domains) {
-      const slice = sliceOf(domainName);
-      if (slice === undefined) continue;
-      for (const w of slice.wsInvariants.values()) declared.set(w.id, { id: w.id, on: w.on });
-    }
-    return JSON.stringify([...declared.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)));
-  }
+  // Workspace-invariant read selection uses typed USDA interpreted by Rust whenever the
+  // compiler can describe it. This dispatch remains the deterministic JavaScript fallback
+  // for tenant selectors that deliberately exceed that bounded read algebra.
 
   /** `{workspaceInvariantReads:{id}, payload}` → the bounded ref-set `[{name,aggregate,id},…]`. */
   function planWorkspaceInvariantReads(job: {
@@ -732,11 +802,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
       throw new Error(`engine workspaceInvariantReads: no workspace invariant registered for "${id}"`);
     }
     const intent = (job.intent?.payload ?? {}) as Record<string, unknown>;
-    // LAW-GATED AUTHZ: the captured author identity (a top-level sibling of `intent`, set by the wasm
-    // author leg + replayed verbatim) — the governance invariant reads it to gate by the AUTHOR.
     const principal = (job.capturedPorts?.principal ?? "") as string;
-    // VA-core (Phase 3): the kernel-DERIVED author-verified flag (`captured_ports.principal_verified`),
-    // threaded the same way as `principal`, so an invariant may gate on a VERIFIED author (e.g. enrollSignerSelf).
     const principalVerified = job.capturedPorts?.principal_verified === true;
     return JSON.stringify(decl.reads({ intent, principal, principalVerified }));
   }
@@ -848,20 +914,16 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     queryRows?: unknown[];
     priorState?: Record<string, unknown>;
   }): string {
-    // Branch order mirrors emit_engine.ts: workspace-invariant trio → aggregateInvariant →
+    // Branch order mirrors emit_engine.ts: workspace-invariant bodies → aggregateInvariant →
     // invariant → derive → combine → report (the gate's most recent dispatch key wins).
     const wsJob = job as {
       intent?: {
-        workspaceInvariantList?: unknown;
         workspaceInvariantReads?: { id?: string };
         workspaceInvariant?: { id?: string };
         payload?: unknown;
       };
       priorState?: Record<string, unknown>;
     };
-    if (wsJob.intent?.workspaceInvariantList !== undefined) {
-      return planWorkspaceInvariantList();
-    }
     if (wsJob.intent?.workspaceInvariantReads !== undefined) {
       return planWorkspaceInvariantReads(wsJob);
     }
@@ -934,7 +996,12 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     // token qualifies explicitly. (`module.domain` === `intent.domain`.) Synchronous plan execution ⇒
     // cleared in the `finally`.
     const slice = sliceOf(domain)!;
-    __setDispatchContext({ domain, qualifiable: slice.qualifiableRelations, qualifiableAggregates: slice.qualifiableAggregates });
+    __setDispatchContext({
+      domain,
+      relationNamespace: routing.relationNamespaceOf?.[domain] ?? domain,
+      qualifiable: slice.qualifiableRelations,
+      qualifiableAggregates: slice.qualifiableAggregates,
+    });
     let wire: ReturnType<typeof executeDirectiveToIntent>;
     try {
       wire = executeDirectiveToIntent(entry.directive, entry.agg, intent.payload as never, ctx);
@@ -952,6 +1019,28 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     // `captured_ports.births` and folds it after admit; decode_plan_output ignores it for the byte-compare),
     // so a birth-free intent still emits the bare event array, byte-identical (the era rule).
     const births = wire.births;
+    // CURRENT KERNELS expose a Rust-owned plan sink inside the sealed engine. Hand the completed
+    // typed wire values to it while they are still native QuickJS objects, so the kernel can build
+    // and meter `Event`s directly instead of walking a second returned object graph. This is an
+    // execution ABI, not authority: the same values still pass the ordinary kernel gates, and old
+    // kernels/packages retain the returned-value lane below for era replay.
+    const submitNativePlan = (globalThis as unknown as {
+      nomos?: {
+        __submitPlan?: (
+          events: WireEvent[],
+          strikes: string[],
+          endorse: { sink: string; facet: string; reason: string | null }[],
+          births: { workspace: string; genesisChain: unknown }[],
+        ) => void;
+      };
+    }).nomos?.__submitPlan;
+    if (typeof submitNativePlan === "function") {
+      submitNativePlan(wire.events, wire.strikes, endorse ?? [], births ?? []);
+      // The Rust sink now owns the result. Return the smallest lawful sentinel; the kernel ignores
+      // it when a native submission is present and reconstructs compatibility bytes from its typed
+      // events. This avoids retaining and re-traversing the large event graph at the ABI boundary.
+      return [];
+    }
     if (!wire.strikes.length && !(endorse && endorse.length) && !(births && births.length)) return wire.events;
     return {
       events: wire.events,
@@ -972,58 +1061,21 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
    * package title), matching the compiler's `domainHash`/`"<name> (nomos package)"`.
    */
   function describe(opts?: { lawHash?: string; title?: string }): OpenApiDoc {
-    const lawHash = opts?.lawHash;
-    const fragments: OpenApiDoc[] = [];
-    for (const domainName of domainNames) {
-      const sources = config.domains[domainName];
-      if (sources === undefined) continue;
-      const merged = mergeModules(sources.map((m) => (typeof m === "function" ? m() : m)), domainName);
-      // Aggregates dedup by wire id + RelationTuple auto-ensure (the compose contract) — openapi
-      // reads aggregates only for the hasMany inverse indexes, so this matches composeDomainModule.
-      const byId = aggregatesOf(merged);
-      const discoveredDirectives = [...directivesOf(merged).values()];
-      const applicationLanguage = applicationLanguageOf([merged], domainName);
-      const directives = applicationLanguage === undefined
-        ? discoveredDirectives
-        : executableDirectivesForLanguage(applicationLanguage, discoveredDirectives, domainName);
-      const applicationIntents = applicationLanguage === undefined
-        ? undefined
-        : [
-            ...applicationLanguage.intents,
-            ...directives.filter((directive) =>
-              isBusinessBirthDirective(directive) &&
-              !applicationLanguage.intents.some((intent) => intent.id === directive.id)),
-          ];
-      if (!byId.has(RelationTuple.id) && directives.some((d) => d.aggregateId === RelationTuple.id)) {
-        byId.set(RelationTuple.id, RelationTuple);
-      }
-      const decls = config.openapiDecls?.[domainName] ?? {};
-      const module = {
-        name: domainName,
-        domain: domainName,
-        aggregates: [...byId.values()],
-        directives,
-        ...(applicationIntents === undefined ? {} : { applicationIntents }),
-        ...(decls.queries && decls.queries.length > 0 ? { queries: [...decls.queries] } : {}),
-        ...(decls.counts && decls.counts.length > 0 ? { counts: [...decls.counts] } : {}),
-        ...(decls.sums && decls.sums.length > 0 ? { sums: [...decls.sums] } : {}),
-        ...(decls.mins && decls.mins.length > 0 ? { mins: [...decls.mins] } : {}),
-        ...(decls.maxes && decls.maxes.length > 0 ? { maxes: [...decls.maxes] } : {}),
-        ...(decls.spatials && decls.spatials.length > 0 ? { spatials: [...decls.spatials] } : {}),
-        ...(decls.workspaceInvariants && decls.workspaceInvariants.length > 0
-          ? { workspaceInvariants: [...decls.workspaceInvariants] }
-          : {}),
-      } as unknown as DomainModule;
-      fragments.push(generateOpenApiFragment(module, {
-        ...(lawHash !== undefined ? { lawHash } : {}),
-        includeFrameworkRoutes: true,
-      }));
+    const document = config.openapiDocument;
+    if (document === undefined) {
+      throw new Error("engine describe: selected plan has no compiled OpenAPI projection");
     }
-    const title = opts?.title ?? config.packageTitle;
-    return mergeOpenApiFragments(fragments, {
-      ...(title !== undefined ? { title } : {}),
-      ...(lawHash !== undefined ? { lawHash } : {}),
-    });
+    const lawHash = opts?.lawHash;
+    const title = opts?.title ?? config.packageTitle ?? document.info["title"];
+    const priorInfo = document.info;
+    const info: Record<string, unknown> = {
+      ...priorInfo,
+      ...(title === undefined ? {} : { title }),
+      version: lawHash === undefined ? (priorInfo["version"] ?? "0") : lawHash.slice(0, 12),
+    };
+    if (lawHash === undefined) delete info["x-nomos-law-hash"];
+    else info["x-nomos-law-hash"] = lawHash;
+    return { ...document, info };
   }
 
   // The engine evals the bundle as a classic script and FREEZES globalThis before
@@ -1031,7 +1083,9 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
   // describe verb (the kernel `describe` run mode evals `globalThis.describe(opts)`).
   (globalThis as { plan?: unknown }).plan = plan;
   (globalThis as { planReport?: unknown }).planReport = planReport;
+  (globalThis as { __nomosPrepareDomain?: unknown }).__nomosPrepareDomain = prepareDomain;
+  (globalThis as { __nomosHasDirective?: unknown }).__nomosHasDirective = hasDirective;
   (globalThis as { describe?: unknown }).describe = describe;
 
-  return { plan, planReport, describe } as RegisteredEngine;
+  return { plan, planReport, prepareDomain, hasDirective, describe } as RegisteredEngine;
 }