@githolon/dsl 0.100.6 → 0.101.0

package/src/codegen_openapi.ts

@@ -44,6 +44,13 @@ import type { Field } from "./fields.js";
 type AnyDirective = Directive<unknown>;
 
 const GROUP_PARAM = { name: "group", in: "query", required: false, schema: { type: "string" } } as const;
+const AGGREGATE_TYPE_PARAM = {
+  name: "aggregateType",
+  in: "query",
+  required: false,
+  schema: { type: "string" },
+  description: "Framework-generated aggregate selector",
+} as const;
 
 /** Minimal OpenAPI 3.1 document shape we emit (open object — extensions ride as `x-…` keys). */
 export interface OpenApiDoc {
@@ -213,8 +220,8 @@ function generateOpenApiSurface(
   // read — the maintained "decisions needed" index (rows: {aggregateType, aggregateId, field,
   // observations}). DECLARED BY THE LAW ITSELF (the era-key idiom, like nomosInvariantGate):
   // emitted iff a Surfaced field is declared, so a Surfaced-free domain's fragment — and thus
-  // its openapi/package bytes — is byte-identical to before this existed. No params: the read
-  // is workspace-wide (the reserved id IS the selector).
+  // its openapi/package bytes — is byte-identical to before this existed. The generated client
+  // supplies aggregateType; no tenant code handles the heterogeneous workspace index.
   const declaresSurfaced = module.aggregates.some((a) =>
     Object.values((a.fields ?? {}) as Record<string, Field>).some(
       (f) => (f.driver as { kind?: string } | undefined)?.kind === "Surfaced",
@@ -223,8 +230,14 @@ function generateOpenApiSurface(
   if (declaresSurfaced) {
     getRead(
       "nomosPendingConflicts",
-      "pending Surfaced merge conflicts across the workspace (maintained; derived, not drained)",
+      "pending Surfaced merge conflicts for one generated aggregate (maintained; derived, not drained)",
       { kind: "pendingConflicts" },
+      [AGGREGATE_TYPE_PARAM],
+    );
+    getRead(
+      "nomosConflictSummary",
+      "workspace pending-conflict totals and aggregate breakdown",
+      { kind: "pendingConflictSummary" },
       [],
     );
   }
@@ -260,6 +273,14 @@ export function generateOpenApiFragment(
     ...(module.queries === undefined ? {} : { queries: module.queries.filter((q) => !isInternal(q)) }),
   };
   const publicDoc = generateOpenApiSurface(publicModule, opts);
+  // Manual conflict escalation is a BUSINESS capability exposed by the generated client, but
+  // its maintained workspace index is Nomos plumbing. Keep the reserved selector routable for
+  // that client without advertising `/nomosPendingConflicts` as tenant-authored business API.
+  const pendingConflictRoutes = ["/nomosPendingConflicts", "/nomosConflictSummary"] as const;
+  const frameworkConflictRoutes = Object.fromEntries(
+    pendingConflictRoutes.flatMap((path) => publicDoc.paths[path] === undefined ? [] : [[path, publicDoc.paths[path]]]),
+  );
+  for (const path of pendingConflictRoutes) delete publicDoc.paths[path];
   if (opts.includeFrameworkRoutes !== true) return publicDoc;
 
   const frameworkModule: DomainModule = {
@@ -276,10 +297,12 @@ export function generateOpenApiFragment(
     spatials: [],
   };
   const frameworkDoc = generateOpenApiSurface(frameworkModule, opts);
-  if (Object.keys(frameworkDoc.paths).length === 0) return publicDoc;
+  const frameworkPaths = { ...frameworkDoc.paths };
+  Object.assign(frameworkPaths, frameworkConflictRoutes);
+  if (Object.keys(frameworkPaths).length === 0) return publicDoc;
   return {
     ...publicDoc,
-    "x-nomos-framework-routes": { paths: frameworkDoc.paths },
+    "x-nomos-framework-routes": { paths: frameworkPaths },
   };
 }
 

package/src/codegen_proof.ts

@@ -34,7 +34,7 @@
  */
 import type { z } from "zod";
 
-import type { AggregateHandle } from "./aggregate.js";
+import { BUSINESS_BIRTH_SEED_PAYLOAD_FIELD, type AggregateHandle } from "./aggregate.js";
 import type { Field } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
@@ -44,6 +44,7 @@ import type { RelationTypeDecl, Rewrite } from "./relation_schema.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import { finishCount } from "./count.js";
 import { clearDirectiveId } from "./clear_directive.js";
+import type { DomainInterface } from "./shape_compat.js";
 import { voMetaOf, voSample } from "./value_object.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
@@ -1722,6 +1723,14 @@ export interface ChildBirthLeg {
   /** Present for the one application-facing `birth(Aggregate, spec)` declaration. Proof renderers use the
    *  business noun and keep the lowered framework ceremony out of normal output. */
   readonly businessAggregateId?: string;
+  /** Hidden data the offline product harness needs to perform the same child-addressed sealing as the
+   *  generated client. Present only for an encrypted `.owned()` business birth. */
+  readonly businessEncryption?: {
+    readonly scope: string;
+    readonly namespace: string;
+    readonly keyField: string;
+    readonly fields: Readonly<Record<string, { readonly aggSid: string; readonly fieldSid: string }>>;
+  };
   /** The domain the `.births()` directive lives in. */
   readonly parentDomain: string;
   /** The `.births()` directive id the parent drives to birth the child. */
@@ -1939,6 +1948,15 @@ export function discoverChildBirthLegOrReason(
   // SHAPE is read).
   const probePayload: Record<string, unknown> = { ...synth.value };
   for (const f of synth.autoStamped) probePayload[f] = "2026-01-01T00:00:00Z";
+  const businessBirth = (birthDir as unknown as {
+    businessBirth?: { aggregateId?: string; publicPayloadSchema?: z.ZodTypeAny };
+  }).businessBirth;
+  if (businessBirth !== undefined) {
+    // The real generated client fills this opaque carrier with locally sealed genesis facts. Discovery only
+    // needs the recipe's shape, so an empty JSON object preserves the synthesized plaintext facts while
+    // exercising the same parsing branch without inventing a key inside the compiler.
+    probePayload[BUSINESS_BIRTH_SEED_PAYLOAD_FIELD] = "{}";
+  }
   try {
     withBirthProbeGlobals(() => {
       __resetAuthoring();
@@ -2019,17 +2037,24 @@ export function discoverChildBirthLegOrReason(
   // The parent payload the leg dispatches: the synthesized values MINUS the framework/law-hash placeholders
   // (the runtime injects the REAL hashes onto those fields by name — a `sample-*` hash would fail the child
   // install) MINUS the auto-stamped fields (stamped at dispatch).
-  const birthPayload: Record<string, unknown> = { ...synth.value };
+  const publicSynth = businessBirth?.publicPayloadSchema === undefined
+    ? undefined
+    : synthesizePayload(businessBirth.publicPayloadSchema, `${parentDomain}/${birthDir.id} public birth`);
+  const birthPayload: Record<string, unknown> = {
+    ...(publicSynth?.value ?? synth.value),
+  };
   if (frameworkHashField !== undefined) delete birthPayload[frameworkHashField];
   if (lawHashField !== undefined) delete birthPayload[lawHashField];
 
-  const businessAggregateId = (birthDir as unknown as { businessBirth?: { aggregateId?: string } }).businessBirth?.aggregateId;
+  const businessAggregateId = businessBirth?.aggregateId;
   const leg: ChildBirthLeg = {
     parentDomain,
     birthDirectiveId: birthDir.id,
     ...(businessAggregateId !== undefined ? { businessAggregateId } : {}),
     birthPayload,
-    birthAutoStamped: synth.autoStamped,
+    birthAutoStamped: businessBirth !== undefined
+      ? [...new Set([...(publicSynth?.autoStamped ?? []), "bornAt"])]
+      : synth.autoStamped,
     ...(actorField !== undefined ? { birthActorField: actorField } : {}),
     ...(birthDir.requiresRelationGate !== undefined ? { birthRequiresRelation: birthDir.requiresRelationGate.relation } : {}),
     ...(frameworkHashField !== undefined ? { frameworkHashField } : {}),
@@ -2140,6 +2165,8 @@ export interface TsProofOptions {
   readonly packageName: string;
   /** sha256 of the built `.package.usda` — checked against the deploy response. */
   readonly domainHash: string;
+  /** Stable-id structural interface used to teach the offline harness the hidden owned-birth seal slots. */
+  readonly interface?: Readonly<Record<string, DomainInterface>>;
 }
 
 /** THE PROOF TAXONOMY (co2 feedback): which legs a domain carries.
@@ -2225,6 +2252,10 @@ export interface ProofLegs {
  *  domain proves via its bootstrap / child-birth / compile-valid legs instead. */
 function isStandaloneCreate(d: Directive<unknown> | undefined): boolean {
   return d?.marker === "creates" && typeof d.payloadSchema === "object"
+    // Framework lifecycle directives are installed in the certified law so the generated client can
+    // drive them behind its managed methods, but they are not tenant vocabulary. Selecting one here
+    // makes the generated proof call a method that the public generated client correctly does not expose.
+    && (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true
     && d.birthsChild !== true && d.attestationAuthorizedGate === undefined
     && d.requiresRelationGate === undefined
     // NOT a foreign-read directive (`.readsFrom(...)` — a static attested edge or a dynamic
@@ -2346,10 +2377,60 @@ function hasBirthDirective(mod: DomainModule): boolean {
   return (mod.directives as Directive<unknown>[]).some((d) => d?.birthsChild === true && typeof d.payloadSchema === "object");
 }
 
+function attachBusinessEncryption(
+  leg: ChildBirthLeg,
+  modules: readonly DomainModule[],
+  packageInterface: Readonly<Record<string, DomainInterface>> | undefined,
+): ChildBirthLeg {
+  if (leg.businessAggregateId === undefined || packageInterface === undefined) return leg;
+  const mod = modules.find((candidate) => (candidate.domain ?? candidate.name) === leg.parentDomain);
+  const aggregate = mod?.aggregates.find((candidate) => candidate.id === leg.businessAggregateId);
+  if (aggregate?.audience?.kind !== "owned" || (aggregate.encryptedFields?.length ?? 0) === 0) return leg;
+  const directive = (mod?.directives as Directive<unknown>[] | undefined)?.find(
+    (candidate) => candidate.id === leg.birthDirectiveId,
+  ) as (Directive<unknown> & {
+    businessBirth?: { namespace?: string; keyField?: string };
+  }) | undefined;
+  const namespace = directive?.businessBirth?.namespace;
+  const keyField = directive?.businessBirth?.keyField;
+  const offered = packageInterface[leg.parentDomain];
+  const offeredAggregate = offered === undefined
+    ? undefined
+    : Object.values(offered.aggregates).find((candidate) => candidate.label === leg.businessAggregateId);
+  if (namespace === undefined || keyField === undefined || offeredAggregate === undefined || aggregate.visibility === undefined) {
+    throw new Error(
+      `${leg.parentDomain}/${leg.birthDirectiveId}: Nomos could not derive the hidden owned-birth custody map`,
+    );
+  }
+  const fields: Record<string, { aggSid: string; fieldSid: string }> = {};
+  for (const field of aggregate.encryptedFields ?? []) {
+    const slot = Object.entries(offeredAggregate.fields).find(([, candidate]) => candidate.label === field);
+    if (slot === undefined) {
+      throw new Error(
+        `${leg.parentDomain}/${leg.birthDirectiveId}: owned birth field '${field}' has no stable interface slot`,
+      );
+    }
+    fields[field] = { aggSid: offeredAggregate.sid, fieldSid: slot[0] };
+  }
+  return {
+    ...leg,
+    businessEncryption: {
+      scope: aggregate.visibility.requires,
+      namespace,
+      keyField,
+      fields,
+    },
+  };
+}
+
 /** Build the legs for ONE domain module — every leg it carries (compile-valid always; standalone-provable
  *  when it has a `.creates`; child-birth-provable when it has a `.births()`). NEVER null: every compiled
  *  domain is at least `compile-valid` (gaps 1+3 — every domain is proof-addressable). */
-export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[]): ProofLegs {
+export function legsForDomain(
+  mod: DomainModule,
+  modules: readonly DomainModule[],
+  packageInterface?: Readonly<Record<string, DomainInterface>>,
+): ProofLegs {
   // Business-birth control declarations are proofed as part of the birth's child genesis, not as
   // tenant-authored standalone/gated actions. Keep the full `modules` below for recipe resolution while
   // removing the presentation-only internals from leg selection and diagnostics.
@@ -2399,7 +2480,7 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
       if (rb !== undefined && rb.bornContext === undefined) return { ...withParent, relationSetup: rb };
     }
     return withParent;
-  });
+  }).map((birthLeg) => attachBusinessEncryption(birthLeg, modules, packageInterface));
   const childBirthWithSetup = childBirths[0];
 
   // The relation-bootstrap leg (when the domain has a `.requires(R)`-gated directive AND a discoverable
@@ -2497,11 +2578,14 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
  *  domain key pointing at the parent birth that proves it. `githolon proof [--domain <key>]` resolves for
  *  every domain. The default is the first STANDALONE-provable domain (the live `.mts` lane needs one), else
  *  the first child-birth-provable, else the first compiled domain. */
-export function proofLegsIndex(modules: readonly DomainModule[]): { default: string; domains: Record<string, ProofLegs> } | null {
+export function proofLegsIndex(
+  modules: readonly DomainModule[],
+  packageInterface?: Readonly<Record<string, DomainInterface>>,
+): { default: string; domains: Record<string, ProofLegs> } | null {
   const domains: Record<string, ProofLegs> = {};
   const order: string[] = [];
   for (const mod of modules) {
-    const legs = legsForDomain(mod, modules);
+    const legs = legsForDomain(mod, modules, packageInterface);
     if (domains[legs.domain] === undefined) order.push(legs.domain);
     domains[legs.domain] = legs;
   }
@@ -2913,7 +2997,14 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     (m.directives as Directive<unknown>[]).some((d) => isStandaloneCreate(d));
   const hasBirth = (m: DomainModule): boolean => hasBirthDirective(m);
   const isBootstrapProvable = (m: DomainModule): boolean => {
-    try { return discoverRelationBootstrapLeg(m) !== undefined; } catch { return false; }
+    try {
+      return discoverRelationBootstrapLeg({
+        ...m,
+        directives: (m.directives as Directive<unknown>[]).filter(
+          (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+        ),
+      }) !== undefined;
+    } catch { return false; }
   };
   const mod = modules.find(hasStandaloneCreate) ?? modules.find(hasBirth) ?? modules.find(isBootstrapProvable);
   if (mod === undefined) {
@@ -2933,7 +3024,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   // THE MARKER (since 0.5.0) + the per-domain index are ONE synthesis (`legsForDomain`) — the proof body, its
   // marker, and the index can never describe different directives. The primary domain's legs carry whichever
   // of standalone / child-birth / relation-bootstrap it has.
-  const primaryLegs = legsForDomain(mod, modules);
+  const primaryLegs = legsForDomain(mod, modules, opts.interface);
   const childBirth = primaryLegs.childBirth;
 
   // The standalone-create lane needs an UNGATED create (isStandaloneCreate — never a gated/birth/attestation
@@ -2993,7 +3084,12 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   // THE AUTHORITY-CONFORMANCE LEG (the one-encoder + gate proof): the first gated (`.requires(...)`) directive
   // in the primary domain, proven locally — actor threads through the one encoder; an actorless gated offer
   // throws MissingOfferAuthority. `undefined` ⇒ a documented no-op (the domain authors openly).
-  const conformance = discoverAuthorityConformanceLeg(mod);
+  const conformance = discoverAuthorityConformanceLeg({
+    ...mod,
+    directives: (mod.directives as Directive<unknown>[]).filter(
+      (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+    ),
+  });
 
   // THE RELATION-BOOTSTRAP LEG (the seed-then-prove positive): grant relation R to the proof actor, then prove
   // a `.requires(R)`-gated write SUCCEEDS under that actor. `undefined` ⇒ no gated directive or no discoverable