@githolon/dsl 0.16.3 → 0.18.0

package/src/codegen_ts.ts

@@ -534,7 +534,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       // the obligation the birth provider materializes. parentWs = "root" for a top-level platform,
       // else the parent holon's own name. timestamps ride IN the payload (the determinism doctrine);
       // a platform's foundingAdminHash = sha256(your chosen platformAdminKey) — the host never mints it.
-      const emit = (name: string, doc: string, params: string[], lane: { kind: "boot" } | { kind: "offer"; parentWs: string; directiveId: "createWorkspace" | "birthPlatform" }) => {
+      const emit = (name: string, doc: string, params: string[], lane: { kind: "boot" } | { kind: "offer"; parentWs: string; directiveId: "createWorkspace" | "birthChild" }) => {
         if (emittedBirths.has(name)) return;
         emittedBirths.add(name);
         const sig = `opts: NomosBirthAuth & { cloud: string; ${params.join("; ")} }`;
@@ -547,14 +547,18 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           );
           return;
         }
-        const isPlatformOffer = lane.directiveId === "birthPlatform";
+        // A platform birth is birthChild WITH genesis (the tier collapsed onto #creator; birthPlatform is
+        // gone). The genesis stamps ride IN the payload (the determinism doctrine): foundingAdminHash =
+        // sha256(your chosen platformAdminKey), bornAt = the ISO birth time. The host replays the
+        // law-authored chain — it mints no genesis.
+        const isPlatformOffer = lane.directiveId === "birthChild";
         const bodyFields = [
           `name: opts.name`,
           `parent: ${lane.parentWs}`,
           `principal: opts.principal ?? ""`,
           `requestedBy: opts.principal ?? ""`,
           `requestedAt: Date.now()`,
-          ...(isPlatformOffer ? [`foundingAdminHash: await nomosKeyHash(opts.platformAdminKey)`] : []),
+          ...(isPlatformOffer ? [`foundingAdminHash: await nomosKeyHash(opts.platformAdminKey)`, `bornAt: new Date().toISOString()`] : []),
         ];
         out.push(
           `/** ${doc} */`,
@@ -570,13 +574,13 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         const isPlatform = t.childIds.length > 0;
         if (!childIds.has(t.id)) {
           // A TOP-LEVEL type: a workspace births on the boot lane; a platform-kind
-          // coordinator births via the root holon's birthPlatform offer.
+          // coordinator births via the root holon's birthChild offer (with genesis).
           emit(
             fnName(t.id),
-            `Birth a '${t.id}' workspace${isPlatform ? " (a platform-kind coordinator: hosts its own subtree; PRESENT your chosen platformAdminKey) via root's birthPlatform offer" : " on the boot lane (the one-time secret comes back)"} — derived from the taxonomy. Placement is automatic (measured shape) — no tier to pick.`,
+            `Birth a '${t.id}' workspace${isPlatform ? " (a platform-kind coordinator: hosts its own subtree; PRESENT your chosen platformAdminKey) via root's birthChild offer" : " on the boot lane (the one-time secret comes back)"} — derived from the taxonomy. Placement is automatic (measured shape) — no tier to pick.`,
             isPlatform ? [`name: string`, `platformAdminKey: string`] : [`name: string`],
             isPlatform
-              ? { kind: "offer", parentWs: `"root"`, directiveId: "birthPlatform" }
+              ? { kind: "offer", parentWs: `"root"`, directiveId: "birthChild" }
               : { kind: "boot" },
           );
         }
@@ -587,11 +591,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           const childIsPlatform = child.childIds.length > 0;
           emit(
             fnName(child.id),
-            `Birth a '${child.id}' under a '${t.id}' — the taxonomy's hasMany edge, a governance offer on the parent holon (POST /v2/workspaces/<${parentParam}>/${childIsPlatform ? "birthPlatform" : "createWorkspace"}; lineage + pool enforced by the parent's law).${childIsPlatform ? " PRESENT your chosen platformAdminKey." : ""} Placement is automatic (measured shape).`,
+            `Birth a '${child.id}' under a '${t.id}' — the taxonomy's hasMany edge, a governance offer on the parent holon (POST /v2/workspaces/<${parentParam}>/${childIsPlatform ? "birthChild" : "createWorkspace"}; lineage + pool enforced by the parent's law).${childIsPlatform ? " PRESENT your chosen platformAdminKey." : ""} Placement is automatic (measured shape).`,
             childIsPlatform
               ? [`${parentParam}: string`, `name: string`, `platformAdminKey: string`]
               : [`${parentParam}: string`, `name: string`],
-            { kind: "offer", parentWs: `opts.${parentParam}`, directiveId: childIsPlatform ? "birthPlatform" : "createWorkspace" },
+            { kind: "offer", parentWs: `opts.${parentParam}`, directiveId: childIsPlatform ? "birthChild" : "createWorkspace" },
           );
         }
       }

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 —

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 });
+    },
   };
 }