@githolon/dsl 0.100.5 → 0.100.6

package/src/birth_meter_ensure.ts

@@ -42,6 +42,44 @@ import {
   retireChildRequiresBirth,
   retireChildNotReclaimed,
 } from "./framework/birth_meter.js";
+import { RelationTuple, relationTupleInstanceId, relationTuplesByObject } from "./framework/relations.js";
+import { GENESIS_WARRANT_ID, GenesisWarrant, seedGenesis } from "./framework/genesis.js";
+import {
+  BIRTH_ATTESTATION_ID,
+  BirthAttestation,
+  birthAttestation,
+  seedBirthAttestation,
+} from "./framework/home.js";
+import { requireParentAttestedBirth } from "./births.js";
+import {
+  SignerDelegation,
+  enrollDelegation,
+  enrollSigner,
+  identityRelations,
+  signerDelegationByUser,
+  signerObject,
+} from "./framework/signing_identity.js";
+import { AuthProvider, authProvider, setAuthProvider } from "./framework/auth_provider_law.js";
+import { refAs, workspaceInvariant } from "./framework/workspace_invariant.js";
+
+/** Lightweight copy of the framework's founding-signer guard, kept here to avoid importing the whole
+ * governance module (whose unrelated captured-read laws would otherwise survive into every child lump). */
+const bornFounderSignerWriteOnce = workspaceInvariant("FounderSignerWriteOnce")
+  .on("enrollSigner")
+  .reads((ctx) => [
+    refAs(
+      "tuple",
+      "RelationTuple",
+      "pre:" + relationTupleInstanceId(signerObject(String((ctx.intent ?? {}).principal ?? "")), "signer"),
+    ),
+  ])
+  .assert(({ tuple }, ctx) => {
+    const subjects = (tuple as { subjects?: Record<string, unknown> })?.subjects ?? {};
+    const want = "key:" + String((ctx?.intent ?? {}).keyHash ?? "");
+    return Object.keys(subjects).every((key) => key === want)
+      ? { accept: true }
+      : { reject: "founding-signer-already-enrolled" };
+  });
 
 /**
  * The sanctioning declaration — an `ensures(NomosBirthRecord)` directive whose plan emits ZERO ops.
@@ -70,36 +108,126 @@ export function withBirthMeterExports<M extends Record<string, unknown>>(mod: M)
       (v as { birthsChild?: boolean }).birthsChild === true &&
       typeof (v as Directive<unknown>).plan === "function",
   );
-  if (!declaresBirth) return mod;
+  // A law that accepts the kernel-injected birth attestation is itself a possible CHILD even if it never
+  // births anything. Such a law must also accept the framework-owned founding signer step, otherwise the
+  // child can replay but can never sign its first write or birth a descendant without tenant recipe work.
+  const acceptsBirth = Object.values(mod).some(
+    (v) =>
+      v !== null &&
+      typeof v === "object" &&
+      (v as { id?: unknown }).id === "seedBirthAttestation" &&
+      typeof (v as Directive<unknown>).plan === "function",
+  );
+  if (!declaresBirth && !acceptsBirth) return mod;
   const out: Record<string, unknown> = { ...mod };
-  // Business birth hides framework maintenance declarations from the generated application facade while
-  // retaining them in certified law for the operator's structural offer discovery. A non-business
-  // `.births()` law keeps its existing explicit generated surface.
-  const businessInternal = Object.values(mod).some(
-    (v) => v !== null && typeof v === "object" && (v as { businessBirth?: unknown }).businessBirth !== undefined,
+  const internal = <T extends object>(v: T): T => ({ ...v, businessBirthInternal: true }) as T;
+  const hasOwn = (key: string): boolean => Object.prototype.hasOwnProperty.call(out, key);
+  const isGeneratedInternal = (value: unknown): boolean =>
+    value !== null &&
+    typeof value === "object" &&
+    (value as { businessBirthInternal?: unknown }).businessBirthInternal === true;
+  const reservedNameError = (key: string): Error => new Error(
+    `Nomos internal export name '${key}' is reserved inside a birth-capable law, but the tenant module ` +
+      "already exports a different concept there. Nomos will not silently overwrite or reroute it; rename " +
+      "the tenant export.",
   );
-  const presented = <T extends object>(v: T): T =>
-    businessInternal ? ({ ...v, businessBirthInternal: true } as T) : v;
-  if (!("nomosBirthRecordEnsure" in out)) out["nomosBirthRecordEnsure"] = presented(nomosBirthRecordEnsure);
-  if (!("NomosBirthRecord" in out)) out["NomosBirthRecord"] = presented(NomosBirthRecord);
-  if (!("NomosChildLifecycle" in out)) out["NomosChildLifecycle"] = presented(NomosChildLifecycle);
-  if (!("BirthPolicy" in out)) out["BirthPolicy"] = presented(BirthPolicy);
-  if (!("BirthGrant" in out)) out["BirthGrant"] = presented(BirthGrant);
-  if (!("retireChild" in out)) out["retireChild"] = presented(retireChild);
-  if (!("reclaimChild" in out)) out["reclaimChild"] = presented(reclaimChild);
-  if (!("retireChildAsAdmin" in out)) out["retireChildAsAdmin"] = presented(retireChildAsAdmin);
-  if (!("reclaimChildAsAdmin" in out)) out["reclaimChildAsAdmin"] = presented(reclaimChildAsAdmin);
-  if (!("reclaimChildRequiresRetired" in out)) out["reclaimChildRequiresRetired"] = reclaimChildRequiresRetired;
-  if (!("reclaimChildAsAdminRequiresRetired" in out)) {
-    out["reclaimChildAsAdminRequiresRetired"] = reclaimChildAsAdminRequiresRetired;
-  }
-  if (!("retireChildRequiresBirth" in out)) out["retireChildRequiresBirth"] = retireChildRequiresBirth;
-  if (!("retireChildNotReclaimed" in out)) out["retireChildNotReclaimed"] = retireChildNotReclaimed;
-  if (!("retireChildAsAdminRequiresBirth" in out)) {
-    out["retireChildAsAdminRequiresBirth"] = retireChildAsAdminRequiresBirth;
-  }
-  if (!("retireChildAsAdminNotReclaimed" in out)) {
-    out["retireChildAsAdminNotReclaimed"] = retireChildAsAdminNotReclaimed;
-  }
+  /** Reserve a framework-only JS export slot as well as its stable law id. The keys are deliberately obscure,
+   * but obscurity is collision avoidance, not collision handling: an occupied slot is always a loud refusal. */
+  const reserve = <T>(key: string, canonical: T): void => {
+    if (!hasOwn(key)) {
+      out[key] = canonical;
+      return;
+    }
+    const existing = out[key];
+    if (existing !== canonical && !isGeneratedInternal(existing)) throw reservedNameError(key);
+  };
+  /**
+   * Framework ownership follows the stable law id, not the tenant's export key. Older laws commonly
+   * re-exported `enrollSigner`/`seedGenesis` under their public names; merely adding a second hidden
+   * `__nomos_*` binding leaves BOTH declarations discoverable and lets codegen expose the old one. Mark
+   * every matching binding internal, and add the canonical declaration only when the law carried none.
+   */
+  const internalize = <T extends { readonly id: string }>(key: string, canonical: T): void => {
+    if (hasOwn(key)) {
+      const existing = out[key];
+      const sameGeneratedId =
+        isGeneratedInternal(existing) &&
+        (existing as { id?: unknown }).id === canonical.id;
+      if (existing !== canonical && !sameGeneratedId) throw reservedNameError(key);
+    }
+    let found = false;
+    for (const [exportName, value] of Object.entries(out)) {
+      if (
+        value !== null &&
+        typeof value === "object" &&
+        (value as { id?: unknown }).id === canonical.id
+      ) {
+        const isCanonicalSingleton = value === canonical;
+        const isNomosGeneratedBinding =
+          (value as { businessBirthInternal?: unknown }).businessBirthInternal === true;
+        if (!isCanonicalSingleton && !isNomosGeneratedBinding) {
+          throw new Error(
+            `Nomos framework id '${canonical.id}' is reserved inside a birth-capable law, but export ` +
+              `'${exportName}' declares a different tenant-owned concept with that id. Nomos will not ` +
+              `silently reinterpret it as framework machinery; rename the tenant concept.`,
+          );
+        }
+        out[exportName] = internal(value);
+        found = true;
+      }
+    }
+    if (!found) out[key] = internal(canonical);
+  };
+  // THE BORN-WORKSPACE CORE: the kernel appends enrollSigner -> attestation -> warrant to every valid birth.
+  // Carry the law needed to judge that internal step in every possible child, plus the write-once guard that
+  // keeps the founding lane a genesis primitive. These declarations are certified but never tenant-facing.
+  internalize("__nomos_RelationTuple", RelationTuple);
+  reserve("__nomos_identityRelations", identityRelations);
+  internalize("__nomos_enrollSigner", enrollSigner);
+  internalize("__nomos_relationTuplesByObject", relationTuplesByObject);
+  internalize("__nomos_GenesisWarrant", GenesisWarrant);
+  internalize("__nomos_seedGenesis", seedGenesis);
+  internalize("__nomos_BirthAttestation", BirthAttestation);
+  internalize("__nomos_seedBirthAttestation", seedBirthAttestation);
+  internalize("__nomos_birthAttestation", birthAttestation);
+  internalize("__nomos_AuthProvider", AuthProvider);
+  internalize("__nomos_setAuthProvider", setAuthProvider);
+  internalize("__nomos_authProvider", authProvider);
+  reserve("__nomos_founderSignerWriteOnce", bornFounderSignerWriteOnce);
+  if (!declaresBirth) return out as M;
+  // Birth lifecycle is Nomos machinery for every birth-capable law. It remains certified/routable law,
+  // but no generated tenant API gets a second maintenance lane beside business `birth(...)`.
+  internalize("__nomos_nomosBirthRecordEnsure", nomosBirthRecordEnsure);
+  internalize("__nomos_NomosBirthRecord", NomosBirthRecord);
+  internalize("__nomos_NomosChildLifecycle", NomosChildLifecycle);
+  internalize("__nomos_BirthPolicy", BirthPolicy);
+  internalize("__nomos_BirthGrant", BirthGrant);
+  internalize("__nomos_retireChild", retireChild);
+  internalize("__nomos_reclaimChild", reclaimChild);
+  internalize("__nomos_retireChildAsAdmin", retireChildAsAdmin);
+  internalize("__nomos_reclaimChildAsAdmin", reclaimChildAsAdmin);
+  reserve("__nomos_reclaimChildRequiresRetired", reclaimChildRequiresRetired);
+  reserve("__nomos_reclaimChildAsAdminRequiresRetired", reclaimChildAsAdminRequiresRetired);
+  reserve("__nomos_retireChildRequiresBirth", retireChildRequiresBirth);
+  reserve("__nomos_retireChildNotReclaimed", retireChildNotReclaimed);
+  reserve("__nomos_retireChildAsAdminRequiresBirth", retireChildAsAdminRequiresBirth);
+  reserve("__nomos_retireChildAsAdminNotReclaimed", retireChildAsAdminNotReclaimed);
+  // ONE BIRTH LANE ALSO MEANS ONE PRIVATE SIGNING LANE. The client completes a `.births()` offer's signer
+  // enrollment, delegation and cert retry internally; therefore every birth-declaring parent law must carry
+  // the declarations that make those framework writes lawful. Previously only the newer `businessBirth`
+  // helper composed them, while an ordinary `.births()` directive forced the harness/app to understand
+  // `enrollDelegation` (or failed as an unverifiable black box). Auto-compose the exact same framework
+  // declarations for ALL births and mark them presentation-internal: they remain certified/routable law,
+  // but never appear in TS/Dart/OpenAPI tenant surfaces.
+  internalize("__nomos_SignerDelegation", SignerDelegation);
+  internalize("__nomos_enrollDelegation", enrollDelegation);
+  internalize("__nomos_signerDelegationByUser", signerDelegationByUser);
+  reserve("__nomos_parentAttestedBirth", internal({
+    ...requireParentAttestedBirth,
+    ownerObject: GENESIS_WARRANT_ID,
+    ownerField: "principal",
+    certObject: BIRTH_ATTESTATION_ID,
+    certField: "certChain",
+  }));
   return out as M;
 }

package/src/build_package.ts

@@ -75,6 +75,7 @@ import { collectValueObjectDescriptors } from "./value_object.js";
 import { emitUsd } from "./usd.js";
 import { expandCapabilityExports } from "./capability_exports.js";
 import { RelationTuple, relationTuplesByObject } from "./framework/relations.js";
+import { signerDelegationByUser } from "./framework/signing_identity.js";
 import { AuthProvider, setAuthProvider, authProvider } from "./framework/workspaces.js";
 import { parentAttestedBirthMarker } from "./births.js";
 import { discoverUnsanctionedEnsures, sanctioningEnsureDirective } from "./secondary_ensure.js";
@@ -125,7 +126,10 @@ export function contractsOf(mod: Mod): import("./contract.js").ContractHandle[]
 
 /** Collect every exported `Directive` ({id, plan, aggregateId} duck-type). */
 export function directivesOf(mod: Mod): Directive<any>[] {
-  const out: Directive<any>[] = [];
+  // One wire directive id is one law declaration. Merge seams may retain both an old tenant re-export and
+  // Nomos's presentation-internal wrapper under different JS keys; later wins so the framework wrapper
+  // controls codegen without duplicating the hashed/routable law.
+  const byId = new Map<string, Directive<any>>();
   for (const v of Object.values(mod)) {
     if (
       v &&
@@ -134,10 +138,10 @@ export function directivesOf(mod: Mod): Directive<any>[] {
       typeof (v as { plan?: unknown }).plan === "function" &&
       typeof (v as { aggregateId?: unknown }).aggregateId === "string"
     ) {
-      out.push(v as Directive<any>);
+      byId.set((v as { id: string }).id, v as Directive<any>);
     }
   }
-  return out;
+  return [...byId.values()];
 }
 
 /** The NAMED-KEYS spec for one engine domain (the serialization of `module(...)`). */
@@ -306,7 +310,11 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   }
   const readModels = spec.readModelAggregates ?? aggregates.map((a) => a.id);
 
-  const queries = [...(spec.queries ?? [])];
+  // As with directives, one stable query id is one declaration. This also makes an internal framework
+  // wrapper win over an older public re-export discovered earlier in the module bag.
+  const queryById = new Map<string, QueryDecl>();
+  for (const query of spec.queries ?? []) queryById.set(query.id, query);
+  const queries = [...queryById.values()];
   const counts = [...(spec.counts ?? [])];
   const spatials = [...(spec.spatials ?? [])];
   const deriveds = [...(spec.deriveds ?? [])];
@@ -316,7 +324,23 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   const mins = [...(spec.mins ?? [])];
   const maxes = [...(spec.maxes ?? [])];
   const workspaceTypes = [...(spec.workspaceTypes ?? [])];
-  const workspaceInvariants = [...(spec.workspaceInvariants ?? [])];
+  // Invariants exported by framework auto-composition must enter the manifest at this same seam; callers of
+  // composeDomainModule (tests and package builders alike) should not need to rediscover/rethread them.
+  const workspaceInvariantById = new Map<string, WorkspaceInvariantDecl>();
+  for (const value of Object.values(merged)) {
+    if (
+      value !== null &&
+      typeof value === "object" &&
+      (value as { __isWorkspaceInvariant?: unknown }).__isWorkspaceInvariant === true
+    ) {
+      const invariant = value as WorkspaceInvariantDecl;
+      workspaceInvariantById.set(invariant.id, invariant);
+    }
+  }
+  for (const invariant of spec.workspaceInvariants ?? []) {
+    workspaceInvariantById.set(invariant.id, invariant);
+  }
+  const workspaceInvariants = [...workspaceInvariantById.values()];
   if (declaresBirth) {
     const haveInvariant = new Set(workspaceInvariants.map((w) => w.id));
     for (const lifecycle of [
@@ -343,10 +367,21 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   if (declaresBirth) {
     const haveQuery = new Set(queries.map((q) => q.id));
     for (const q of BIRTH_FRAMEWORK_QUERIES) {
-      if (!haveQuery.has(q.id)) queries.push(q);
+      if (!haveQuery.has(q.id)) {
+        queries.push({ ...q, businessBirthInternal: true } as QueryDecl);
+      }
     }
     // The inheritance read (`.reads("authProvider")` on birthHome) routes like any declared query.
     if (!haveQuery.has(authProvider.id)) queries.push(authProvider);
+    // The client's private birth ceremony checks the actor's delegation before creating it. Carry the
+    // structural read in certified routing law for every `.births()` domain, but keep it off tenant codegen.
+    if (!haveQuery.has(signerDelegationByUser.id)) {
+      const internalDelegationQuery: QueryDecl & { readonly businessBirthInternal: true } = {
+        ...signerDelegationByUser,
+        businessBirthInternal: true,
+      };
+      queries.push(internalDelegationQuery);
+    }
   }
   const relationTypes = [...(spec.relationTypes ?? [])];
   // RELATION-USING LAW AUTO-COMPOSES ITS AUDIT READ (co2 recovery DX — same idiom as the meter

package/src/business_birth.ts

@@ -229,7 +229,7 @@ function lowerOne(decl: BusinessBirthDecl, domain: string): Record<string, unkno
     __nomos_birthAttestation: internalSurface(birthAttestation),
     __nomos_RelationTuple: internalSurface(RelationTuple),
     __nomos_relationTuplesByObject: internalSurface(relationTuplesByObject),
-    __nomos_identityRelations: identityRelations,
+    __nomos_identityRelations: internalSurface(identityRelations),
     __nomos_enrollSigner: internalDirective(enrollSigner),
     __nomos_enrollFirstDevice: internalDirective(enrollFirstDevice),
     __nomos_SignerDelegation: internalSurface(SignerDelegation),
@@ -238,19 +238,19 @@ function lowerOne(decl: BusinessBirthDecl, domain: string): Record<string, unkno
     __nomos_AuthProvider: internalSurface(AuthProvider),
     __nomos_setAuthProvider: internalDirective(setAuthProvider),
     __nomos_authProvider: internalSurface(authProvider),
-    // Exact export keys prevent the generic `.births()` auto-compose seam from inserting a second,
-    // unmarked copy. The values are still the canonical framework declarations.
-    NomosBirthRecord: internalSurface(NomosBirthRecord),
-    NomosChildLifecycle: internalSurface(NomosChildLifecycle),
-    BirthPolicy: internalSurface(BirthPolicy),
-    BirthGrant: internalSurface(BirthGrant),
-    nomosBirthRecordEnsure: internalDirective(nomosBirthRecordEnsure),
+    // Obscure framework export keys minimize accidental tenant collisions. Stable law ids remain the real
+    // identity; the generic composition seam rejects a tenant-owned declaration with any of those ids.
+    __nomos_NomosBirthRecord: internalSurface(NomosBirthRecord),
+    __nomos_NomosChildLifecycle: internalSurface(NomosChildLifecycle),
+    __nomos_BirthPolicy: internalSurface(BirthPolicy),
+    __nomos_BirthGrant: internalSurface(BirthGrant),
+    __nomos_nomosBirthRecordEnsure: internalDirective(nomosBirthRecordEnsure),
     __nomos_birthRecordsByPrincipal: internalSurface(birthRecordsByPrincipal),
     __nomos_childLifecyclesByPrincipal: internalSurface(childLifecyclesByPrincipal),
     __nomos_childLifecyclesByStatus: internalSurface(childLifecyclesByStatus),
     __nomos_birthPolicy: internalSurface(birthPolicy),
     __nomos_birthGrantByPrincipal: internalSurface(birthGrantByPrincipal),
-    __nomos_parentAttestedBirth: businessParentAttestedBirth,
+    __nomos_parentAttestedBirth: internalSurface(businessParentAttestedBirth),
   };
 }
 
@@ -268,6 +268,28 @@ export function expandBusinessBirthExports<M extends Record<string, unknown>>(
     );
   }
   const lowered = lowerOne(declarations[0]!, domain);
+  for (const [key, generated] of Object.entries(lowered)) {
+    if (!Object.prototype.hasOwnProperty.call(mod, key)) continue;
+    const existing = mod[key];
+    const sameGeneratedDeclaration =
+      existing !== null &&
+      typeof existing === "object" &&
+      generated !== null &&
+      typeof generated === "object" &&
+      (((existing as { businessBirthInternal?: unknown }).businessBirthInternal === true &&
+        (generated as { businessBirthInternal?: unknown }).businessBirthInternal === true &&
+        (existing as { id?: unknown }).id === (generated as { id?: unknown }).id) ||
+       ((existing as { businessBirth?: unknown }).businessBirth !== undefined &&
+        (generated as { businessBirth?: unknown }).businessBirth !== undefined &&
+        (existing as { id?: unknown }).id === (generated as { id?: unknown }).id));
+    if (!sameGeneratedDeclaration) {
+      throw new Error(
+        `Nomos internal export name '${key}' is reserved by birth(${declarations[0]!.aggregate.id}), but ` +
+          "the tenant module already exports a different concept there. Nomos will not silently overwrite " +
+          "or reroute it; rename the tenant export.",
+      );
+    }
+  }
   return { ...mod, ...lowered };
 }
 

package/src/codegen_dart_client.ts

@@ -939,13 +939,17 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `    if (b is NomosSession) await b.assertCompatible(interface);`,
     `  }`,
     ``,
-    `  /// THE ONE DISPATCH LANE every generated directive method routes through: lazy preflight, then`,
-    `  /// the session's offer (the generated-internal use of the engine-level lane).`,
-    `  Future<NomosOfferOutcome> _offer(String directiveId, Object? payload, {List<Map<String, Object?>>? attestations}) async {`,
-    `    await _preflightOnce();`,
-    `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: directiveId, payload: payload, actor: actor, domainHash: domainHash, attestations: attestations);`,
-    `  }`,
-    ``,
+    ...(dirs.length > 0 || birthDirs.some((d) => (d as { businessBirth?: unknown }).businessBirth !== undefined)
+      ? [
+          `  /// THE ONE DISPATCH LANE every generated directive method routes through: lazy preflight, then`,
+          `  /// the session's offer (the generated-internal use of the engine-level lane).`,
+          `  Future<NomosOfferOutcome> _offer(String directiveId, Object? payload, {List<Map<String, Object?>>? attestations}) async {`,
+          `    await _preflightOnce();`,
+          `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: directiveId, payload: payload, actor: actor, domainHash: domainHash, attestations: attestations);`,
+          `  }`,
+          ``,
+        ]
+      : []),
     ...(encPresent ? dartEncClassMembers(encMap!) : []),
     // THE OWNER CEREMONY (slice 2): grantAndWrap / revokeAndRotate / rotate — the operator-blind key-epoch
     // handshake as one call. Bind `actor` (the owner) to author the fan-out. Only for a domain with a scope.

package/src/compile_package_main.ts

@@ -598,10 +598,13 @@ function collectDartSharedSymbols(
   const frameworkAggById = new Map<string, AggregateHandle>();
   const frameworkDirById = new Map<string, ModDirective>();
   const frameworkQueryById = new Map<string, ModQuery>();
+  const isInternal = (value: unknown): boolean =>
+    !!value && typeof value === "object"
+      && (value as { businessBirthInternal?: unknown }).businessBirthInternal === true;
   for (const mod of modules) {
-    for (const a of mod.aggregates) if (isFrameworkAggregate(a)) frameworkAggById.set(a.id, a);
-    for (const d of mod.directives) if (isFrameworkDirective(d)) frameworkDirById.set(d.id, d);
-    for (const q of mod.queries ?? []) if (isFrameworkQuery(q)) frameworkQueryById.set(q.id, q);
+    for (const a of mod.aggregates) if (!isInternal(a) && isFrameworkAggregate(a)) frameworkAggById.set(a.id, a);
+    for (const d of mod.directives) if (!isInternal(d) && isFrameworkDirective(d)) frameworkDirById.set(d.id, d);
+    for (const q of mod.queries ?? []) if (!isInternal(q) && isFrameworkQuery(q)) frameworkQueryById.set(q.id, q);
   }
   const frameworkAggs = [...frameworkAggById.values()];
   const frameworkDirs = [...frameworkDirById.values()];
@@ -1773,7 +1776,9 @@ async function main(): Promise<void> {
     if (directivesOf(merged).some((dir) => (dir as { birthsChild?: boolean }).birthsChild === true)) {
       const haveQuery = new Set(queries.map((q) => q.id));
       for (const q of BIRTH_FRAMEWORK_QUERIES) {
-        if (!haveQuery.has(q.id)) queries.push(q);
+        if (!haveQuery.has(q.id)) {
+          queries.push({ ...q, businessBirthInternal: true } as QueryDecl);
+        }
       }
     }
     // RELATION-USING LAW AUTO-COMPOSES ITS AUDIT READ (co2 recovery DX, same idiom as the birth-meter
@@ -2583,12 +2588,16 @@ async function main(): Promise<void> {
   // the read overlay; the workspace's full spec is the runtime merge of installed packages' specs
   // (currentLaw); the host ingests it and builds its router from it — no domain/directive name in host
   // source. Self-describing for the whole web ecosystem (Swagger/codegen/Hono/agent tool-calling).
-  const openapi = mergeOpenApiFragments(
+  const publicOpenapi = mergeOpenApiFragments(
     domainModules.map((m) => generateOpenApiFragment(m, { lawHash: domainHash })),
     { title: `${cfg.name} (nomos package)`, lawHash: domainHash },
   );
+  const runtimeOpenapi = mergeOpenApiFragments(
+    domainModules.map((m) => generateOpenApiFragment(m, { lawHash: domainHash, includeFrameworkRoutes: true })),
+    { title: `${cfg.name} (nomos package)`, lawHash: domainHash },
+  );
   const openapiPath = path.join(outDir, `${cfg.name}.openapi.json`);
-  writeFileSync(openapiPath, JSON.stringify(openapi, null, 2) + "\n", "utf8");
+  writeFileSync(openapiPath, JSON.stringify(publicOpenapi, null, 2) + "\n", "utf8");
 
   // ── 4. the one-call deploy body (package only) ──
   // SELF-DESCRIBING: `summary` states what the (otherwise hex-opaque) package
@@ -2620,7 +2629,7 @@ async function main(): Promise<void> {
     interface: packageInterface,
     // THE SELF-DESCRIBING API: this package's OpenAPI spec (law-derived). The worker stages it on the
     // manifest overlay; a read serves the workspace's merged spec; the host builds its router from it.
-    openapi,
+    openapi: runtimeOpenapi,
     // THE CLIENT/LAW COMPAT MANIFEST (§5): a DIAGNOSIS surface (law hash + interface hash + generator
     // provenance) the connect-time classifier reads. Frontend-only — the package bytes above ignore it.
     nomosCompat,
@@ -2895,7 +2904,7 @@ async function main(): Promise<void> {
   }
   console.log(`  client     ${rel(clientPath)} (typed TS client — payloads, read models, query accessors)`);
   for (const note of recursiveNotes) console.log(`  note       ${note}`);
-  console.log(`  openapi    ${rel(openapiPath)} (${Object.keys(openapi.paths).length} operation(s) — the law's self-describing API; the host's runtime routing table)`);
+  console.log(`  openapi    ${rel(openapiPath)} (${Object.keys(publicOpenapi.paths).length} operation(s) — the public business API; private framework routes ride only in the deploy manifest)`);
   if (proofPath !== undefined) {
     console.log(`  proof      ${rel(proofPath)} (a runnable e2e GENERATED from your law — run: githolon proof)`);
   } else {

package/src/shape_compat.ts

@@ -123,6 +123,10 @@ function aggFieldReadKind(f: Field): string {
  *  stable-id surface. Without stable ids (pre-#58) aggregate fields key by NAME and the
  *  kind comes from the field declaration — a graceful, rename-unaware fallback. */
 export function domainInterface(mod: DomainModule, stableIds?: StableIds): DomainInterface {
+  const isInternal = (value: unknown): boolean =>
+    !!value &&
+    typeof value === "object" &&
+    (value as { businessBirthInternal?: unknown }).businessBirthInternal === true;
   const enumTypes = new Map<string, string>();
   // DETERMINISTIC KEY ORDER — directive ids, aggregate sids, and field keys are SORTED, so the
   // emitted interface is byte-stable and the layered-USD fold (which merges + sorts) reproduces it
@@ -134,21 +138,27 @@ export function domainInterface(mod: DomainModule, stableIds?: StableIds): Domai
   };
   const directives: Record<string, DirectivePayloadShape> = {};
   const dirEntries: Array<[string, DirectivePayloadShape]> = [];
-  for (const d of (mod.directives ?? []) as Array<{ id?: unknown; payloadSchema?: unknown }>) {
+  for (const d of (mod.directives ?? []) as Array<{
+    id?: unknown;
+    payloadSchema?: unknown;
+    businessBirth?: { publicPayloadSchema?: unknown };
+  }>) {
     if (!d || typeof d.id !== "string") continue;
+    if (isInternal(d)) continue;
     const fieldEntries: Array<[string, PayloadFieldShape]> = [];
-    const schema = d.payloadSchema;
+    const schema = d.businessBirth?.publicPayloadSchema ?? d.payloadSchema;
     if (schema && typeof schema === "object") {
       for (const spec of introspectPayload(schema as z.ZodTypeAny, enumTypes)) {
         fieldEntries.push([spec.name, { kind: payloadFieldKind(spec), optional: !!spec.optional }]);
       }
     }
-    dirEntries.push([d.id, { fields: sortedRec(fieldEntries) }]);
+    dirEntries.push([d.businessBirth === undefined ? d.id : "birth", { fields: sortedRec(fieldEntries) }]);
   }
   Object.assign(directives, sortedRec(dirEntries));
   const aggregates: Record<string, AggregateReadShape> = {};
   const aggEntries: Array<[string, AggregateReadShape]> = [];
   for (const agg of (mod.aggregates ?? []) as Array<{ id: string; fields: Record<string, Field> }>) {
+    if (isInternal(agg)) continue;
     const label = agg.id;
     const sa = stableIds?.aggregates?.[label];
     const aggSid = sa?.sid ?? label;
@@ -168,6 +178,7 @@ export function domainInterface(mod: DomainModule, stableIds?: StableIds): Domai
   const foreignReadEntries: Array<[string, ForeignEdge[]]> = [];
   for (const d of (mod.directives ?? []) as Array<{ id?: unknown; declaredForeignReads?: ForeignEdge[] }>) {
     if (!d || typeof d.id !== "string") continue;
+    if (isInternal(d)) continue;
     if (d.declaredForeignReads !== undefined && d.declaredForeignReads.length > 0) {
       foreignReadEntries.push([d.id, d.declaredForeignReads.map((e) => ({ ...e }))]);
     }