@githolon/dsl 0.16.3 → 0.18.0

package/src/index.ts

@@ -94,6 +94,18 @@ export { create, existing, ensure, type AggregateRef } from "./authoring.js";
 // `nomos-compile` REFUSES law that references read() (a named compile error, never a runtime halt).
 // The captured-reads wave (task #58) wires the capability in and lifts the refusal.
 export { read } from "./read.js";
+// THE BIRTH EFFECT (G3 — birth is a declared kernel primitive): a `.births()` directive's plan records the
+// child's genesis recipe via `birth(recipe)` (reuse `buildGenesisChain`); it rides the committed intent as a
+// declared output, and the kernel — reading the `.births` declaration off the law manifest (the
+// `nomosBirthGate` era key, never domain state) — spawns + self-validates the child after the offer admits.
+export { birth, type BirthRecipe } from "./births.js";
+// THE PEER-SOVEREIGN ROOT-OF-TRUST (the BirthAttestation cert chain): a home/child law exports
+// `requireParentAttestedBirth` to declare it requires a parent-attested-birth cert chain (the
+// `nomosParentAttestedBirth` era key); the kernel verify doors then verify the travelling chain to K_root.
+export {
+  requireParentAttestedBirth,
+  type ParentAttestedBirthMarker,
+} from "./births.js";
 export {
   query,
   hasManyIndexes,
@@ -247,6 +259,28 @@ export {
   signerObject,
   SIGNER_RELATION,
   enrollSigner,
+  // VA-core — SignerEpoch + self-bind enroll/revoke + the strict-increment & verified-enroll gates.
+  SignerEpoch,
+  SIGNER_EPOCH_ID,
+  signerEpochCurrent,
+  advanceSignerEpoch,
+  signerEpochStrictlyIncreases,
+  enrollSignerSelf,
+  enrollSignerSelfRequiresVerified,
+  revokeSigner,
+  revokeSignerEpochStrictlyIncreases,
+  signerTuplesByObject,
+  signerTupleInstanceId,
+  // THE ENROLL-ONCE DELEGATION (the peer-sovereign root-of-trust) — the per-user tenant-signed cert the
+  // kernel reads to assemble U's home cert chain at birth.
+  SignerDelegation,
+  SIGNER_DELEGATION_PREFIX,
+  signerDelegationInstanceId,
+  enrollDelegation,
+  signerDelegationByUser,
+  type SignerDelegationHandle,
+  type SignerEpochHandle,
+  type SignerAuthority,
 } from "./framework/signing_identity.js";
 // THE HOME HOLON (home_holons_and_cross_custody.md §4) — the identity-role law: the shared-with-me access
 // index + the owner lane to maintain it (the key directory is the `signer` relation above).
@@ -262,6 +296,14 @@ export {
   seedHomeOwner,
   writeHomeOwner,
   homeNameBindsOwner,
+  homeNameOf,
+  birthHome,
+  // THE PEER-SOVEREIGN ROOT-OF-TRUST (the BirthAttestation cert chain).
+  BirthAttestation,
+  BIRTH_ATTESTATION_ID,
+  seedBirthAttestation,
+  birthAttestation,
+  parentAttestedBirth,
 } from "./framework/home.js";
 // THE GENESIS WARRANT (identity_keys.md step 0) — the in-history birth fact that lets
 // the gate's genesis clause admit a founding control-plane grant on a virgin chain.

package/src/usd.ts

@@ -285,6 +285,33 @@ export interface UsdLayer {
       }
     >;
   };
+  /**
+   * THE BIRTH GATE DECLARATION (G3 — birth is a declared kernel primitive, the unix model). Present IFF ≥1
+   * directive declares `.births()`: the SORTED set of their ids. A directive named here BIRTHS a child
+   * workspace as the defined CONSEQUENCE of its offer — after the offer admits, the kernel reads THIS
+   * declaration (the SAME way it reads `nomosReadGate`/`nomosInvariantGate` — never a domain aggregate),
+   * takes the genesis recipe the intent carried (its `captured_ports.births`), spawns the child's custody,
+   * and self-validates the child's whole genesis through the child's OWN gate (the `materialize_genesis`
+   * keystone). The kernel reads NO domain schema; it reads its own manifest declaration + the carried
+   * recipe. OMITTED for law with no birth directive (the era rule — byte-identical hash; every pre-feature
+   * chain replays green, the birth effect inert). SORTED keys for byte-determinism.
+   */
+  readonly nomosBirthGate?: {
+    readonly v: 1;
+    /** The directive ids declared `.births()` — SORTED. */
+    readonly directives: string[];
+  };
+  /**
+   * THE PEER-SOVEREIGN ROOT-OF-TRUST (the BirthAttestation cert chain). Present IFF the law declares
+   * `requireParentAttestedBirth`: a warranted workspace running this law MUST travel with a SIGNED cert
+   * chain proving its founder was VERIFIED by its parent at birth, rooting at the pinned `K_root`. The
+   * kernel's verify doors (author / receive / verify_chain) verify the travelling chain OFFLINE — no
+   * cross-ws read. OMITTED for law that doesn't declare it (the era rule — byte-identical hash; every
+   * pre-feature + legacy/non-warranted chain replays green, the check inert).
+   */
+  readonly nomosParentAttestedBirth?: {
+    readonly v: 1;
+  };
   /**
    * STABLE IDENTIFIERS (#58 — names are labels, identity is minted). The layer's
    * domain/aggregate/field sids + label lineages, carried verbatim from the canonical
@@ -721,6 +748,21 @@ export function emitUsd(
       }
       const nomosAttestationGate =
         Object.keys(attestationReq).length > 0 ? { v: 1 as const, directives: attestationReq } : undefined;
+      // THE BIRTH GATE (G3 — birth is a declared kernel primitive): the SORTED set of directive ids
+      // declaring `.births()`. The kernel reads this off the manifest (never a domain aggregate) to know an
+      // admitted directive births, then folds the recipe the intent carried. Omit-when-empty (era rule —
+      // a birth-free layer is byte-identical apart from the always-on stableIds key).
+      const birthDirectives = [...l.module.directives]
+        .filter((d) => (d as { birthsChild?: boolean }).birthsChild === true)
+        .map((d) => d.id)
+        .sort();
+      const nomosBirthGate =
+        birthDirectives.length > 0 ? { v: 1 as const, directives: birthDirectives } : undefined;
+      // THE PEER-SOVEREIGN ROOT-OF-TRUST: the home/child law declared it requires a parent-attested-birth
+      // cert chain (the `requireParentAttestedBirth` sentinel, discovered by composeDomainModule). Emit the
+      // era key iff true; omit otherwise (a law that doesn't require it is byte-identical — the era rule).
+      const nomosParentAttestedBirth =
+        (l.module as { parentAttestedBirth?: boolean }).parentAttestedBirth === true ? { v: 1 as const } : undefined;
       // THE CAPTURED-READ GATE DECLARATION (#58): collected from the canonical
       // manifest's per-directive `capturedReads` (omit-when-empty — read-free law's
       // USD is byte-identical apart from the always-on stableIds key).
@@ -850,6 +892,8 @@ export function emitUsd(
         ...(nomosRelations !== undefined ? { nomosRelations } : {}),
         ...(nomosRelationGate !== undefined ? { nomosRelationGate } : {}),
         ...(nomosAttestationGate !== undefined ? { nomosAttestationGate } : {}),
+        ...(nomosBirthGate !== undefined ? { nomosBirthGate } : {}),
+        ...(nomosParentAttestedBirth !== undefined ? { nomosParentAttestedBirth } : {}),
         ...(Object.keys(visAggregates).length > 0
           ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }
           : {}),

package/src/usd_layers.ts

@@ -177,6 +177,12 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosAttestationGate !== undefined
       ? [`${indent}custom string nomos:attestationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttestationGate)))}`]
       : []),
+    ...(layer.nomosBirthGate !== undefined
+      ? [`${indent}custom string nomos:birthGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosBirthGate)))}`]
+      : []),
+    ...(layer.nomosParentAttestedBirth !== undefined
+      ? [`${indent}custom string nomos:parentAttestedBirthHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosParentAttestedBirth)))}`]
+      : []),
   ];
 }
 
@@ -765,6 +771,23 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         attestationGate = { v: 1, directives: rec };
       }
     }
+    // THE BIRTH GATE (G3): the SORTED union of every layer's `.births()` directive ids. Omit-when-empty
+    // (era rule). The set is the contract; order is incidental (sorted for byte-determinism).
+    let birthGate: UsdLayer["nomosBirthGate"];
+    {
+      const b = new Set<string>();
+      for (const l of stack) {
+        if (l.nomosBirthGate === undefined) continue;
+        for (const id of l.nomosBirthGate.directives) b.add(id);
+      }
+      if (b.size > 0) birthGate = { v: 1, directives: [...b].sort() };
+    }
+    // THE PEER-SOVEREIGN ROOT-OF-TRUST: the era key is present iff ANY layer in the stack declares it
+    // (a boolean union — once required, required). Omit-when-absent (era rule).
+    let parentAttestedBirth: UsdLayer["nomosParentAttestedBirth"];
+    if (stack.some((l) => l.nomosParentAttestedBirth !== undefined)) {
+      parentAttestedBirth = { v: 1 };
+    }
     return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
@@ -781,6 +804,8 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(relations !== undefined ? { nomosRelations: relations } : {}),
       ...(relationGate !== undefined ? { nomosRelationGate: relationGate } : {}),
       ...(attestationGate !== undefined ? { nomosAttestationGate: attestationGate } : {}),
+      ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
+      ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
     };
   });
 
@@ -908,6 +933,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const relationsByDomain = new Map<string, UsdLayer["nomosRelations"]>();
   const relationGateByDomain = new Map<string, UsdLayer["nomosRelationGate"]>();
   const attestationGateByDomain = new Map<string, UsdLayer["nomosAttestationGate"]>();
+  const birthGateByDomain = new Map<string, UsdLayer["nomosBirthGate"]>();
+  const parentAttestedBirthByDomain = new Map<string, UsdLayer["nomosParentAttestedBirth"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -959,6 +986,16 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof attGateHex === "string") {
         attestationGateByDomain.set(domain, JSON.parse(unhexUtf8(attGateHex)) as UsdLayer["nomosAttestationGate"]);
       }
+      // THE BIRTH GATE (G3): the hex-carried `.births()` directive set.
+      const birthGateHex = p.attrs.get("nomos:birthGateHex");
+      if (typeof birthGateHex === "string") {
+        birthGateByDomain.set(domain, JSON.parse(unhexUtf8(birthGateHex)) as UsdLayer["nomosBirthGate"]);
+      }
+      // THE PEER-SOVEREIGN ROOT-OF-TRUST: the hex-carried parent-attested-birth era marker.
+      const pabHex = p.attrs.get("nomos:parentAttestedBirthHex");
+      if (typeof pabHex === "string") {
+        parentAttestedBirthByDomain.set(domain, JSON.parse(unhexUtf8(pabHex)) as UsdLayer["nomosParentAttestedBirth"]);
+      }
     }
   }
 
@@ -1056,6 +1093,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const rel = relationsByDomain.get(domain);
       const relGate = relationGateByDomain.get(domain);
       const attGate = attestationGateByDomain.get(domain);
+      const birthGate = birthGateByDomain.get(domain);
+      const parentAttestedBirth = parentAttestedBirthByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -1072,6 +1111,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(rel !== undefined ? { nomosRelations: rel } : {}),
         ...(relGate !== undefined ? { nomosRelationGate: relGate } : {}),
         ...(attGate !== undefined ? { nomosAttestationGate: attGate } : {}),
+        ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
+        ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));

package/src/wire.ts

@@ -40,6 +40,10 @@ export type WireValue =
   | { Set: string[] }
   | { Map: Record<string, WireField> }
   | { Evidence: WireEvidenceRef }
+  // First-class canonical JSON (RFC 8785 / JCS) — the committed form of a `t.json()` leaf. The
+  // value rides INLINE (`{Json: <any json>}`), not as a string-of-JSON; the kernel canonicalises
+  // it at the boundary (`canonical_json.rs`) and decodes the variant directly into structured JSON.
+  | { Json: unknown }
   // ── STRUCTURAL CRDT state values (only seen when reading RAW folded state back; the read MODEL
   //    collapses them via the kernel `observed_value` to Int/Str/Set, so typed reads stay scalar) ──
   | { Counter: Record<string, { pos: number; neg: number }> }
@@ -135,6 +139,15 @@ export interface WireIntent {
    * empty so a principal-free intent is byte-identical.
    */
   endorse?: { sink: string; facet: string; reason: string | null }[];
+  /**
+   * THE BIRTH EFFECT (G3 — birth is a declared kernel primitive, the unix model): the genesis recipe(s) a
+   * `.births()` directive's plan produced (`birth(recipe)`). It rides the intent as a DECLARED OUTPUT — the
+   * kernel reads the `.births` DECLARATION off the law manifest (the `nomosBirthGate` era key, NOT domain
+   * state), then takes this recipe off the admitted intent and spawns + self-validates the child through the
+   * child's OWN gate. A verify-input WITNESS (rides the carried `captured_ports`, never the events nor the
+   * OID). OMITTED when empty so a birth-free intent is byte-identical to before this existed (the era rule).
+   */
+  births?: { workspace: string; genesisChain: unknown }[];
 }
 
 /**

package/src/wire_encode.ts

@@ -22,6 +22,7 @@
 import { encodeDriver } from "./drivers.js";
 import { __resetAuthoring, __drainAuthoring } from "./authoring.js";
 import { __resetReads, __drainReads } from "./read.js";
+import { __resetBirths, __drainBirths } from "./births.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { Field, EvidenceRefValue } from "./fields.js";
 import type { Directive, ReferentialMarker } from "./directive.js";
@@ -86,14 +87,18 @@ function encodeKernelValue(field: Field | undefined, value: unknown): WireValue
       },
     };
   }
+  // A `t.json()` leaf lowers to the FIRST-CLASS kernel `Value::Json` (RFC 8785 / JCS), NOT a
+  // `Value::Str` holding JSON-shaped text. Checked BEFORE the scalar fallthroughs so EVERY json
+  // value — object, array, string, number, boolean, null — commits as one consistent value kind
+  // (the kernel canonicalises it at the boundary). This is the new-era encoding; a package compiled
+  // before this change froze the old `{ Str: JSON.stringify(value) }` lump and replays unchanged.
+  if (field?.kind === "json") return { Json: value };
   // For scalar Set/SetEntry the kernel expects Str or Int. Maps store leaves;
   // a map's entry value is a leaf scalar.
   if (typeof value === "number" && Number.isInteger(value)) return { Int: value };
   if (typeof value === "string") return { Str: value };
   if (typeof value === "boolean") return { Str: String(value) };
   // Enum values are strings; refs are id strings — both handled above.
-  // Anything else (object/array as a scalar) is JSON-encoded into a Str leaf.
-  if (field?.kind === "json") return { Str: JSON.stringify(value) };
   throw new Error(
     `Cannot encode value ${JSON.stringify(value)} for field '${field?.kind ?? "?"}': ` +
       `kernel scalars are Str | Int only.`,
@@ -196,9 +201,15 @@ export function executeDirectiveToIntent<P>(
   // The plan may also READ (O(1) DSL queries via `read(...)`) — captured into the footprint below.
   __resetAuthoring();
   __resetReads();
+  __resetBirths();
   const returned = directive.plan(parsed, ctx);
   const planned = [...__drainAuthoring(), ...returned];
   const reads = __drainReads();
+  // THE BIRTH EFFECT (G3 — birth is a declared kernel primitive): a `.births()` directive's plan records
+  // the child's genesis recipe via `birth(recipe)`; it rides the intent as a DECLARED output (like a
+  // captured read), drained here. Empty for every non-birth directive — OMITTED below so a birth-free
+  // intent is byte-identical (the era rule).
+  const births = __drainBirths();
 
   // Partition the plan output: STRIKE ops route onto the intent's `strikes` channel
   // (the kernel's strikeout / revert facet, folded by parity); FIELD ops group into
@@ -302,6 +313,7 @@ export function executeDirectiveToIntent<P>(
     events,
     ...(reads.length ? { reads } : {}),
     ...(endorse.length ? { endorse } : {}),
+    ...(births.length ? { births } : {}),
   };
 }