@githolon/dsl 0.17.0 → 0.19.0

package/src/compile_package_main.ts

@@ -61,30 +61,37 @@ import {
   type PermissionVocabulary,
 } from "./codegen_dart.js";
 import { generateDartBridgeClient } from "./codegen_dart_client.js";
-import type { AnyCount } from "./count.js";
+import { finishCount, type AnyCount } from "./count.js";
 import type { QueryDecl } from "./query.js";
 import type { SpatialDecl } from "./spatial.js";
-import type { AnySum } from "./sum.js";
+import { finishSum, type AnySum } from "./sum.js";
 import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import type { ImpureCapabilityDecl } from "./codegen_provider_dart.js";
 import {
   aggregatesOf,
   buildIdentity,
-  buildReadManifest,
   composeDomainModule,
   directivesOf,
   emitUsdJsonForModules,
   packageUsda,
   sha256HexUtf8,
-  writeIdentity,
   type Mod,
 } from "./build_package.js";
 import { collectEngineRouting } from "./engine_entry.js";
+import {
+  discover,
+  isCountDecl,
+  isQueryDecl,
+  isSpatialDecl,
+  isSumDecl,
+  isWorkspaceInvariantDecl,
+  type DeclBag,
+} from "./decl_shapes.js";
 import { resolveWorkspaceTypes, type WorkspaceTypeDecl } from "./workspace_type.js";
 import { canonicalTaxonomyFragment, validateWorkspaceTaxonomyAndRoutes } from "./workspace_routing.js";
 import { shardingLawModule, type ShardingLawSpec } from "./workspace_sharding.js";
-import type { AnyExtremum } from "./extremum.js";
+import { finishExtremum, type AnyExtremum } from "./extremum.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import { type RelationTypeDecl, isRelationTypeDecl, validateRelationType } from "./relation_schema.js";
 import {
@@ -97,7 +104,6 @@ import { domainManifest } from "./manifest.js";
 import type { WireSchema } from "./wire.js";
 import {
   deriveStableIdContinuity,
-  stableIdsFromManifestJson,
   type InferredRename,
   type StableIds,
 } from "./stable_ids.js";
@@ -192,37 +198,9 @@ function fail(msg: string): never {
 }
 
 // ── decl auto-discovery (by SHAPE, mirroring the engine entry's duck-types) ───────
-
-function isQueryDecl(v: unknown): v is QueryDecl {
-  return (
-    !!v &&
-    typeof v === "object" &&
-    typeof (v as { id?: unknown }).id === "string" &&
-    Array.isArray((v as { key?: unknown }).key) &&
-    ((v as { key: unknown[] }).key as unknown[]).every((k) => typeof k === "string") &&
-    typeof (v as { returns?: unknown }).returns === "string" &&
-    typeof (v as { fn?: unknown }).fn !== "function"
-  );
-}
-
-function isWorkspaceInvariantDecl(v: unknown): v is WorkspaceInvariantDecl {
-  return (
-    !!v &&
-    typeof v === "object" &&
-    (v as { __isWorkspaceInvariant?: unknown }).__isWorkspaceInvariant === true
-  );
-}
-
-function isSpatialDecl(v: unknown): v is SpatialDecl {
-  return (
-    !!v &&
-    typeof v === "object" &&
-    typeof (v as { id?: unknown }).id === "string" &&
-    typeof (v as { of?: unknown }).of === "string" &&
-    typeof (v as { on?: unknown }).on === "string" &&
-    typeof (v as { fn?: unknown }).fn !== "function"
-  );
-}
+// The query/workspace-invariant/spatial/sum/count predicates + `discover` live in the SHARED
+// bundle-safe `decl_shapes.ts` (imported above) — the lump's self-describe verb discovers by the
+// EXACT same shape so the kernel-served OpenAPI matches the compiled `<name>.openapi.json`.
 
 function isDerivedDecl(v: unknown): v is DerivedDecl {
   return (
@@ -250,35 +228,6 @@ function isCombinedDecl(v: unknown): v is CombinedDecl {
   );
 }
 
-/** A sum decl/builder — the `{id, of, sumField}` mark (counts/extremums never carry `sumField`). */
-function isSumDecl(v: unknown): v is AnySum {
-  if (!v || typeof v !== "object") return false;
-  const o = v as Record<string, unknown>;
-  return typeof o.id === "string" && typeof o.of === "string" && typeof o.sumField === "string";
-}
-
-/** A count decl/builder — `{id, of}` with NONE of the other decl families' marks. */
-function isCountDecl(v: unknown): v is AnyCount {
-  if (!v || typeof v !== "object") return false;
-  const o = v as Record<string, unknown>;
-  return (
-    typeof o.id === "string" &&
-    typeof o.of === "string" &&
-    typeof o.on !== "string" && // spatial
-    typeof o.fn !== "function" && // derived/combined
-    !Array.isArray(o.key) && // query
-    !("field" in o) && // extremum (wire-descriptor shape)
-    !("valueField" in o) && // extremum (the ExtremumDecl/Extremum-builder mark — never a count)
-    !("sumField" in o) && // sum (the SumDecl/Sum-builder mark — never a count)
-    !("orderBy" in o) && // ordered read
-    !("_existsMarker" in o) && // exists
-    typeof o.refField !== "string" && // combined
-    o.__isAggregateHandle !== true && // aggregate
-    typeof o.aggregateId !== "string" && // directive
-    typeof o.plan !== "function"
-  );
-}
-
 /**
  * Scan merged exports for `workspaceType(...)` decls (sharding §10 slice 1) by the
  * `__isWorkspaceType` brand — individual exports AND exported arrays. Dedupe is BY
@@ -301,24 +250,6 @@ function discoverWorkspaceTypes(merged: Mod): WorkspaceTypeDecl[] {
   return out;
 }
 
-/** Scan merged exports for decls matching `match`: individual exports AND exported arrays. */
-function discover<T>(merged: Mod, match: (v: unknown) => v is T): T[] {
-  const seen = new Set<string>();
-  const out: T[] = [];
-  const push = (v: T) => {
-    const key = JSON.stringify(v, (_k, val) => (typeof val === "function" ? "<fn>" : val));
-    if (!seen.has(key)) {
-      seen.add(key);
-      out.push(v);
-    }
-  };
-  for (const v of Object.values(merged)) {
-    if (match(v)) push(v);
-    else if (Array.isArray(v)) for (const el of v) if (match(el)) push(el);
-  }
-  return out;
-}
-
 /** Validate the LITERAL dart-codegen import hints (config data, not module exports). */
 function checkDartImports(domainKey: string, imports: readonly DartImport[] | undefined): void {
   for (const imp of imports ?? []) {
@@ -532,6 +463,12 @@ async function main(): Promise<void> {
   const entryMintInstalls: string[] = []; // route-tagged in-plan mints (taxonomy packages only)
   const routingInput: Record<string, Mod[]> = {};
   const domainModules: DomainModule[] = [];
+  // THE SELF-DESCRIBE DECLS (G1): per domain key, the FINISHED plain read/maintenance decls the
+  // lump's `globalThis.describe` needs that it cannot rediscover by shape alone (mins/maxes are
+  // config-named; sharding sums are framework-appended). Plain JSON (finishCount/Sum/Extremum
+  // pass finished decls through), serialized into the generated entry as `openapiDecls`, so the
+  // kernel-run describe reproduces THIS compile's `<name>.openapi.json` byte-for-byte.
+  const openapiDeclsByDomain: Record<string, unknown> = {};
   const layered = layeredFlag || cfg.layered === true;
   const layeredDomains: { key: string; inputs: LayeredModuleInput[] }[] = [];
   let importSeq = 0;
@@ -831,6 +768,24 @@ async function main(): Promise<void> {
     //    no-path / ambiguous / cross-home / unroutable law is a NAMED COMPILE
     //    ERROR here — never a domain silently recorded as identity-excluded.
     const composed = domainModules[domainModules.length - 1]!;
+
+    // ── THE SELF-DESCRIBE DECLS (G1): the FINISHED plain read/maintenance decls the lump's
+    //    `describe` reconstructs the openapi fragment from. Directives + aggregates are read from
+    //    the live module exports IN the lump; these ride alongside (mins/maxes are config-named +
+    //    sharding sums are framework-appended — not shape-rediscoverable). Omit-when-empty so a
+    //    decl-free domain contributes nothing (and offers still derive from its directives).
+    {
+      const declsForDomain: Record<string, unknown[]> = {};
+      if (queries.length > 0) declsForDomain.queries = queries.map((q) => ({ id: q.id, key: [...q.key], returns: q.returns }));
+      if (counts.length > 0) declsForDomain.counts = counts.map((c) => finishCount(c));
+      if (sums.length > 0) declsForDomain.sums = sums.map((s) => finishSum(s));
+      if (mins.length > 0) declsForDomain.mins = mins.map((e) => finishExtremum(e));
+      if (maxes.length > 0) declsForDomain.maxes = maxes.map((e) => finishExtremum(e));
+      if (spatials.length > 0) declsForDomain.spatials = spatials.map((s) => ({ id: s.id, of: s.of, on: s.on }));
+      if (workspaceInvariants.length > 0) declsForDomain.workspaceInvariants = workspaceInvariants.map((w) => ({ id: w.id, on: w.on }));
+      if (Object.keys(declsForDomain).length > 0) openapiDeclsByDomain[d.key] = declsForDomain;
+    }
+
     if (composed.workspaceTypes !== undefined && composed.workspaceTypes.length > 0) {
       try {
         validateWorkspaceTaxonomyAndRoutes(composed);
@@ -948,10 +903,6 @@ async function main(): Promise<void> {
   const priorLock: StableIdLock | undefined = existsSync(lockPath)
     ? (JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLock)
     : undefined;
-  const priorBuildManifestsPath = path.join(outDir, "domain_identity_manifests.json");
-  const priorBuildManifests: Record<string, string> | undefined = existsSync(priorBuildManifestsPath)
-    ? (JSON.parse(readFileSync(priorBuildManifestsPath, "utf8")) as Record<string, string>)
-    : undefined;
   const inferredRenames: { domain: string; renames: InferredRename[] }[] = [];
   const nextLock: StableIdLock = { v: 1, domains: {} };
   for (const mod of domainModules) {
@@ -977,23 +928,14 @@ async function main(): Promise<void> {
       // it carries no stable ids either.
       continue;
     }
-    // Continuity source: the lockfile first (durable, committed), else the prior build.
+    // Continuity source: the committed nomos.stable-ids.json lockfile (the canonical identity ledger).
+    // (The old "else the prior build's domain_identity_manifests.json" fallback is gone with that sidecar.)
     let prior: StableIds | undefined;
     let priorSchemas: Record<string, WireSchema> | undefined;
     const locked = priorLock?.domains[identityName];
     if (locked !== undefined) {
       prior = locked.stableIds;
       priorSchemas = locked.schemas;
-    } else if (priorBuildManifests?.[identityName] !== undefined) {
-      prior = stableIdsFromManifestJson(priorBuildManifests[identityName]!);
-      try {
-        const parsed = JSON.parse(priorBuildManifests[identityName]!) as {
-          aggregates?: { id: string; schema: WireSchema }[];
-        };
-        priorSchemas = Object.fromEntries((parsed.aggregates ?? []).map((a) => [a.id, a.schema]));
-      } catch {
-        priorSchemas = undefined;
-      }
     }
     const { continuity, inferred } = deriveStableIdContinuity(
       identityName,
@@ -1132,6 +1074,14 @@ async function main(): Promise<void> {
     ...(entryReports.length > 0 ? [`  reports: {`, ...entryReports, `  },`] : []),
     ...(eagerLump ? [] : [`  routing: ${JSON.stringify(routing)},`]),
     ...(zodSeedNames.length > 0 ? [`  seeds: [${zodSeedNames.join(", ")}],`] : []),
+    // THE SELF-DESCRIBE INPUTS (G1): the finished read/maintenance decls + the package title, baked
+    // into the lump so `globalThis.describe` reproduces this compile's `<name>.openapi.json` over the
+    // FOLDED LAW — the kernel serves the spec, the host stages nothing. Omit-when-empty (decl-free
+    // packages: offers still derive from directives; the title default is the workspace-level title).
+    ...(Object.keys(openapiDeclsByDomain).length > 0
+      ? [`  openapiDecls: ${JSON.stringify(openapiDeclsByDomain)},`]
+      : []),
+    `  packageTitle: ${JSON.stringify(`${cfg.name} (nomos package)`)},`,
     `});`,
     // ROUTE-TAGGED IN-PLAN MINTS (sharding §4, slice 3): wraps globalThis.plan +
     // globalThis.nomos.mint at top-level eval — pre-freeze, after registerEngine's
@@ -1321,15 +1271,13 @@ async function main(): Promise<void> {
     layeredFileCount = relPaths.length;
   }
 
-  // ── 3. the READ manifest + IDENTITY artifacts ──
-  // These are generated from the same source functions embedded into USDA by emitUsd().
-  // They remain local diagnostics for now; the deploy/cloud/runtime contract ignores them.
-  const readManifest = buildReadManifest(domainModules);
-  const readPath = path.join(outDir, "domain_manifests.json");
-  writeFileSync(readPath, JSON.stringify(readManifest, null, 2) + "\n", "utf8");
-
+  // ── 3. the IDENTITY emit (for the summary's per-domain identityHash) ──
+  // The admission identity is carried INSIDE the package USD IR (emitUsd) + the committed
+  // nomos.stable-ids.json lockfile; the deploy/cloud/runtime contract uses neither a read-manifest nor an
+  // identity-manifest sidecar. The old domain_manifests.json / domain_identity_*.json build files were
+  // local diagnostics the contract ignored — REMOVED (they only confused /build consumers). We still
+  // compute the identity to surface its per-domain hash in the summary below.
   const identity = buildIdentity(domainModules);
-  const { manifestsPath } = writeIdentity(identity, outDir);
 
   // ── 3b. the OpenAPI spec — THE PACKAGE'S SELF-DESCRIPTION (the host's runtime routing table;
   // architecture/githolon_host_contract.md "The Self-Describing API"). Each domain emits its fragment
@@ -1463,8 +1411,12 @@ async function main(): Promise<void> {
       `  layered    ${rel(layeredRootPath)} (${layeredFileCount} module layer(s) in build/layers/ — flatten-verified byte-identical to the canonical IR)`,
     );
   }
-  console.log(`  read       ${rel(readPath)} (${Object.keys(readManifest.aggregateFieldKinds).length} aggregate(s), ${readManifest.queries.length} quer(y/ies), ${readManifest.counts.length} count(s), ${readManifest.sums?.length ?? 0} sum(s))`);
-  console.log(`  identity   ${rel(manifestsPath)} (${Object.keys(identity.manifests).length} domain(s)${identity.excluded.length ? `, ${identity.excluded.length} EXCLUDED (palette gap)` : ""})`);
+  {
+    const sum = (pick: (m: (typeof domainModules)[number]) => readonly unknown[] | undefined) =>
+      domainModules.reduce((n, m) => n + (pick(m)?.length ?? 0), 0);
+    console.log(`  reads      ${sum((m) => m.queries)} quer(y/ies), ${sum((m) => m.counts)} count(s), ${sum((m) => m.sums)} sum(s) — declared (routed via the openapi)`);
+  }
+  console.log(`  identity   ${Object.keys(identity.manifests).length} domain(s) (carried in the package IR + nomos.stable-ids.json; no sidecar files)${identity.excluded.length ? ` — ${identity.excluded.length} EXCLUDED (palette gap)` : ""}`);
   for (const [dom, h] of Object.entries(identity.hashes)) console.log(`             ${dom.padEnd(20)} ${h}`);
   for (const ex of identity.excluded) console.log(`             EXCLUDED ${ex.domain}: ${ex.reason}`);
   // STABLE IDS (#58): the minted/carried identity surface + every INFERRED rename —
@@ -1500,8 +1452,8 @@ async function main(): Promise<void> {
   console.log(`  deploy     ${rel(deployPath)}`);
   console.log(``);
   console.log(`deploy (Nomos Cloud):`);
-  console.log(`  githolon ws create <ws> && githolon deploy <ws>   # the secret is saved + sent for you`);
-  console.log(`  # raw lane: curl -X POST -H 'content-type: application/json' -H 'Authorization: Bearer <workspaceSecret>' \\`);
+  console.log(`  githolon login --agent && githolon ws create <ws> && githolon deploy <ws>   # no secret — deploy is OPEN, kernel-judged at the offer gate`);
+  console.log(`  # raw lane: curl -X POST -H 'content-type: application/json' -H 'x-nomos-principal: <your-auth-uid>' \\`);
   console.log(`  #   --data-binary @${rel(deployPath)} https://nomos.captainapp.co.uk/v2/workspaces/<ws>/domains`);
   if (proofPath !== undefined) {
     console.log(`prove it OFFLINE first: npx githolon proof        # the generated proof's offline legs on a LOCAL holon (no cloud workspace)`);

package/src/decl_shapes.ts

@@ -0,0 +1,122 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted remotes are
+// replaceable custody/transport, not truth. ⇒ ONE Nomos GitHolon wasm32-wasip1 artifact.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * decl_shapes.ts — THE DUCK-TYPE PREDICATES for the read/maintenance decl families, hoisted
+ * into ONE bundle-safe module so the COMPILER (`compile_package_main.ts`) and the LUMP's own
+ * self-describe verb (`engine_entry.ts` `describe`) discover decls by the EXACT same shape.
+ *
+ * Why shared: the kernel-served OpenAPI (G1 — openapi residue removal) is produced by the lump
+ * running `generateOpenApiFragment` over the SAME modules it dispatches; if the lump discovered
+ * queries/counts/sums/spatials by a DIFFERENT shape than the compiler did when it wrote
+ * `<name>.openapi.json`, the kernel-served spec would drift from the compiled one. One predicate
+ * set ⇒ one shape ⇒ byte-identity.
+ *
+ * ENGINE-BUNDLE-SAFE: imports NO node builtin (only DSL types) — it bundles under esbuild
+ * `--platform=neutral` into the sealed QuickJS lump.
+ */
+import type { QueryDecl } from "./query.js";
+import type { SpatialDecl } from "./spatial.js";
+import type { AnySum } from "./sum.js";
+import type { AnyCount } from "./count.js";
+import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
+
+/** A merged domain-module exports bag (scanned by shape). */
+export type DeclBag = Record<string, unknown>;
+
+/** A declared query — `{id, key:string[], returns}` with no projection `fn` (that marks derived/combined). */
+export function isQueryDecl(v: unknown): v is QueryDecl {
+  return (
+    !!v &&
+    typeof v === "object" &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    Array.isArray((v as { key?: unknown }).key) &&
+    ((v as { key: unknown[] }).key as unknown[]).every((k) => typeof k === "string") &&
+    typeof (v as { returns?: unknown }).returns === "string" &&
+    typeof (v as { fn?: unknown }).fn !== "function"
+  );
+}
+
+/** A workspace invariant — branded `__isWorkspaceInvariant`. */
+export function isWorkspaceInvariantDecl(v: unknown): v is WorkspaceInvariantDecl {
+  return (
+    !!v &&
+    typeof v === "object" &&
+    (v as { __isWorkspaceInvariant?: unknown }).__isWorkspaceInvariant === true
+  );
+}
+
+/** A spatial index — `{id, of, on}` with no projection `fn`. */
+export function isSpatialDecl(v: unknown): v is SpatialDecl {
+  return (
+    !!v &&
+    typeof v === "object" &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    typeof (v as { of?: unknown }).of === "string" &&
+    typeof (v as { on?: unknown }).on === "string" &&
+    typeof (v as { fn?: unknown }).fn !== "function"
+  );
+}
+
+/** A sum decl/builder — the `{id, of, sumField}` mark (counts/extremums never carry `sumField`). */
+export function isSumDecl(v: unknown): v is AnySum {
+  if (!v || typeof v !== "object") return false;
+  const o = v as Record<string, unknown>;
+  return typeof o.id === "string" && typeof o.of === "string" && typeof o.sumField === "string";
+}
+
+/** A count decl/builder — `{id, of}` with NONE of the other decl families' marks. */
+export function isCountDecl(v: unknown): v is AnyCount {
+  if (!v || typeof v !== "object") return false;
+  const o = v as Record<string, unknown>;
+  return (
+    typeof o.id === "string" &&
+    typeof o.of === "string" &&
+    typeof o.on !== "string" && // spatial
+    typeof o.fn !== "function" && // derived/combined
+    !Array.isArray(o.key) && // query
+    !("field" in o) && // extremum (wire-descriptor shape)
+    !("valueField" in o) && // extremum (the ExtremumDecl/Extremum-builder mark — never a count)
+    !("sumField" in o) && // sum (the SumDecl/Sum-builder mark — never a count)
+    !("orderBy" in o) && // ordered read
+    !("_existsMarker" in o) && // exists
+    typeof o.refField !== "string" && // combined
+    o.__isAggregateHandle !== true && // aggregate
+    typeof o.aggregateId !== "string" && // directive
+    typeof o.plan !== "function"
+  );
+}
+
+/** An extremum decl/builder — `{id, of, valueField}` with `{kind:"min"|"max"}` (the #47 read). */
+export function isExtremumDecl(v: unknown): boolean {
+  if (!v || typeof v !== "object") return false;
+  const o = v as Record<string, unknown>;
+  return (
+    typeof o.id === "string" &&
+    typeof o.of === "string" &&
+    typeof o.valueField === "string" &&
+    (o.kind === "min" || o.kind === "max")
+  );
+}
+
+/**
+ * Scan merged exports for decls matching `match`: individual exports AND exported arrays, deduped
+ * by a function-blind JSON key (the SAME dedup `compile_package_main.ts` `discover` uses).
+ */
+export function discover<T>(merged: DeclBag, match: (v: unknown) => v is T): T[] {
+  const seen = new Set<string>();
+  const out: T[] = [];
+  const push = (v: T) => {
+    const key = JSON.stringify(v, (_k, val) => (typeof val === "function" ? "<fn>" : val));
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(v);
+    }
+  };
+  for (const v of Object.values(merged)) {
+    if (match(v)) push(v);
+    else if (Array.isArray(v)) for (const el of v) if (match(el)) push(el);
+  }
+  return out;
+}

package/src/directive.ts

@@ -141,6 +141,20 @@ export interface Directive<P = unknown> {
    * relation-free directive's canonical manifest is byte-identical to before this existed.
    */
   readonly declaredRelations: RelationDecl[];
+  /**
+   * BIRTH IS AN EXPLICIT, DECLARED KERNEL PRIMITIVE (G3 — the unix model). When `true`, this directive
+   * BIRTHS a child workspace as the defined CONSEQUENCE of its offer: its `plan` produces the child's
+   * genesis recipe (`birth(recipe)`) onto the intent's birth effect, and the kernel — reading THIS
+   * declaration off the law manifest (the `nomosBirthGate` era key, the SAME way it reads `.reads`/
+   * `.creates`/invariants — NOT domain state) — spawns the child's custody and self-validates its whole
+   * genesis through the child's OWN gate after this offer admits. The kernel NEVER scans a tenant/governance
+   * aggregate to detect a birth (a circular dependency, forbidden): the birth is declared, like a syscall.
+   * Lowered into the `nomosBirthGate` USD era key (emitted iff a package declares ≥1 birth directive), so
+   * pre-feature chains carry no key and replay byte-green (the era rule). `false` ⇒ a non-birthing directive.
+   * (FIELD `birthsChild` vs the chainable method `.births()` — the `requiresRelationGate`/`.requires()` and
+   * `attestationAuthorizedGate`/`.attestationAuthorized()` naming convention; the declaration is the noun.)
+   */
+  readonly birthsChild?: boolean;
   /**
    * The directive's DECLARED required HOST CAPABILITIES — the capability PORTS the HOST must
    * PROVIDE for this directive to run (`OFFER_KERNEL_ARCHITECTURE.dot` cluster_ports / `OFFER_FLOW.dot`
@@ -243,6 +257,16 @@ export interface RequirableDirective<P> extends Directive<P> {
    * Returns a NEW requirable directive.
    */
   requiresHostCapability(...portIds: string[]): RequirableDirective<P>;
+  /**
+   * Declare this directive a BIRTH primitive (G3 — the unix model): birthing a child workspace is the
+   * defined CONSEQUENCE of its offer. The `plan` must record the child's genesis recipe (`birth(recipe)`,
+   * reusing `buildGenesisChain`) onto the intent's birth effect; the kernel reads THIS declaration off the
+   * law manifest (the `nomosBirthGate` era key — NOT domain state) and, after the offer admits, spawns the
+   * child's custody + self-validates its genesis through the child's OWN gate. Purely additive +
+   * non-destructive — a directive that never calls this is NOT a birth primitive and is byte-identical in
+   * the canonical manifest to before this existed (the era rule). Returns a NEW requirable directive.
+   */
+  births(): RequirableDirective<P>;
 }
 
 /** Stage 1: id + a referential marker (which fixes the target aggregate). */
@@ -409,6 +433,12 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       const merged = [...new Set([...base.declaredHostCapabilities, ...portIds])].sort();
       return makeRequirable({ ...base, declaredHostCapabilities: merged });
     },
+    births(): RequirableDirective<P> {
+      // BIRTH AS A DECLARED KERNEL PRIMITIVE (G3): mark this directive a birth — its plan's `birth(recipe)`
+      // rides the intent, and the kernel (reading the `nomosBirthGate` era key, not domain state) executes
+      // the birth after admit. Era-ruled: a non-birthing directive omits the flag and is byte-identical.
+      return makeRequirable({ ...base, birthsChild: true });
+    },
   };
 }
 

package/src/engine_entry.ts

@@ -54,6 +54,13 @@
 import { executeDirectiveToIntent } from "./wire_encode.js";
 import { expandCapabilityExports } from "./capability_exports.js";
 import { RelationTuple } from "./framework/relations.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 { Directive } from "./directive.js";
 import type { AggregateHandle, AggregateInvariantFn, AggregateInvariantVerdict } from "./aggregate.js";
 import type { Ports } from "./ctx.js";
@@ -120,6 +127,34 @@ export interface EngineEntryConfig {
    * `sideEffects: false` (a bare side-effect import would be tree-shaken away).
    */
   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.
+   */
+  readonly openapiDecls?: Record<string, OpenApiDomainDecls>;
+  /**
+   * 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
+   * the kernel knowing the package name. The kernel MAY override it (the workspace-level title).
+   */
+  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 {
@@ -395,6 +430,8 @@ 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;
+  /** The G1 self-describe verb: the lump's own merged OpenAPI, derived from its modules. */
+  describe(opts?: { lawHash?: string; title?: string }): OpenApiDoc;
 }
 
 /**
@@ -543,7 +580,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
   /** `{workspaceInvariantReads:{id}, payload}` → the bounded ref-set `[{name,aggregate,id},…]`. */
   function planWorkspaceInvariantReads(job: {
     intent?: { workspaceInvariantReads?: { id?: string }; payload?: unknown };
-    capturedPorts?: { principal?: string };
+    capturedPorts?: { principal?: string; principal_verified?: boolean };
   }): string {
     const id = job.intent?.workspaceInvariantReads?.id;
     if (typeof id !== "string") {
@@ -559,14 +596,17 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     // 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;
-    return JSON.stringify(decl.reads({ intent, principal }));
+    // 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 }));
   }
 
   /** `{workspaceInvariant:{id,on}, payload?}` + priorState (named snapshots) → {accept}|{reject}. */
   function planWorkspaceInvariantAssert(job: {
     intent?: { workspaceInvariant?: { id?: string }; payload?: unknown };
     priorState?: Record<string, unknown>;
-    capturedPorts?: { principal?: string };
+    capturedPorts?: { principal?: string; principal_verified?: boolean };
   }): string {
     const id = job.intent?.workspaceInvariant?.id;
     if (typeof id !== "string") {
@@ -581,7 +621,9 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     const snapshots = (job.priorState ?? {}) as Record<string, Record<string, unknown>>;
     const intent = (job.intent?.payload ?? {}) as Record<string, unknown>;
     const principal = (job.capturedPorts?.principal ?? "") as string;
-    return JSON.stringify(decl.assert(snapshots, { intent, principal }));
+    // VA-core (Phase 3): the kernel-DERIVED author-verified flag — threaded like `principal`.
+    const principalVerified = job.capturedPorts?.principal_verified === true;
+    return JSON.stringify(decl.assert(snapshots, { intent, principal, principalVerified }));
   }
 
   function planDerive(job: {
@@ -717,7 +759,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
   function plan(job: {
     intent?: { domain?: string; directiveId?: string; payload?: unknown };
     capturedPorts?: { principal?: string };
-  }): WireEvent[] | { events: WireEvent[]; strikes?: string[]; endorse?: { sink: string; facet: string; reason: string | null }[] } {
+  }): WireEvent[] | { events: WireEvent[]; strikes?: string[]; endorse?: { sink: string; facet: string; reason: string | null }[]; births?: { workspace: string; genesisChain: unknown }[] } {
     const intent = job.intent ?? {};
     const domain = intent.domain;
     const directiveId = intent.directiveId;
@@ -739,18 +781,77 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     // it to check the law's nomosFlowGate.endorse; decode_plan_output ignores it for the byte-compare),
     // so a principal-free intent still emits the bare array, byte-identical.
     const endorse = wire.endorse;
-    if (!wire.strikes.length && !(endorse && endorse.length)) return wire.events;
+    // THE BIRTH EFFECT (G3): a `.births()` directive's plan recorded the child's genesis recipe; it rides the
+    // plan-output object as a TRANSIENT verify-input (like `endorse` — the kernel reads it onto the intent's
+    // `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;
+    if (!wire.strikes.length && !(endorse && endorse.length) && !(births && births.length)) return wire.events;
     return {
       events: wire.events,
       ...(wire.strikes.length ? { strikes: wire.strikes } : {}),
       ...(endorse && endorse.length ? { endorse } : {}),
+      ...(births && births.length ? { births } : {}),
     };
   }
 
+  /**
+   * THE SELF-DESCRIBE VERB (G1) — the lump's OWN OpenAPI, derived from the SAME modules it
+   * dispatches. The kernel runs this over the FOLDED law (the lump IS `nomos:executable:
+   * javascriptHex` in the package USDA in custody), so the workspace's API surface is a pure,
+   * deterministic function of installed law — NOT a host-staged blob. It reproduces, byte for
+   * byte, the `<name>.openapi.json` the compiler wrote: per domain (declaration order) build the
+   * openapi-relevant DomainModule (directives + aggregates from the live exports; queries/counts/
+   * sums/mins/maxes/spatials/workspaceInvariants from `config.openapiDecls`), `generateOpenApi
+   * Fragment`, then `mergeOpenApiFragments` — the EXACT calls compile_package_main makes.
+   * `opts.lawHash`/`opts.title` are injected by the kernel at describe-time (the version stamp +
+   * 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)));
+      // 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 directives = [...directivesOf(merged).values()];
+      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,
+        ...(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 } : {}));
+    }
+    const title = opts?.title ?? config.packageTitle;
+    return mergeOpenApiFragments(fragments, {
+      ...(title !== undefined ? { title } : {}),
+      ...(lawHash !== undefined ? { lawHash } : {}),
+    });
+  }
+
   // The engine evals the bundle as a classic script and FREEZES globalThis before
-  // dispatch — assign both entries NOW, at top-level eval.
+  // dispatch — assign all entries NOW, at top-level eval. `describe` is the G1 self-
+  // 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 { describe?: unknown }).describe = describe;
 
-  return { plan, planReport } as RegisteredEngine;
+  return { plan, planReport, describe } as RegisteredEngine;
 }