@githolon/dsl 0.60.1 → 0.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.60.1",
+  "version": "0.61.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/directive.ts

@@ -163,6 +163,18 @@ export interface Directive<P = unknown> {
     /** The payload field holding the claimed issuer (the gate asserts it == the prefix AuthProvider.issuer). */
     readonly verifiedViaField: string;
   };
+
+  /**
+   * THE LAWFUL-RECOVERY GATE (architecture/lawful_recovery.md). Present IFF this directive declares
+   * `.certifiesEra()`: it is the CUSTODIAN-authored `certifyEra` verb. Lowered into the `nomosEraCertGate`
+   * USD era key (the directive id + the payload field carrying the signed `EraCertification`), so the kernel
+   * admits this intent by verifying its author against the pinned `K_root` via the carried certification —
+   * NOT the workspace signer roster — and the walk waives the identity attestation for the oids it covers.
+   * The kernel hardcodes NEITHER; it reads both from this declaration. Framework `certifyEra` default field.
+   */
+  readonly certifiesEraGate?: {
+    readonly certField: string;
+  };
   /**
    * The directive's DECLARED read boundary: the ref types its `plan` may READ (the
    * "IR for law boundaries" decision — the boundary is part of the domain identity).
@@ -318,6 +330,14 @@ export interface RequirableDirective<P> extends Directive<P> {
     keyHashField?: string;
     verifiedViaField?: string;
   }): RequirableDirective<P>;
+  /**
+   * Declare this directive the CUSTODIAN-authored `certifyEra` recovery verb (architecture/lawful_recovery.md).
+   * Its author is verified to the pinned `K_root` via the carried [`EraCertification`] (NOT the workspace
+   * signer roster), and the kernel walk WAIVES the identity attestation for the oids the certification covers
+   * (the law/plan gate stays enforced). Emits the `nomosEraCertGate` era key naming this directive + the
+   * payload field holding the artifact (default `certification`). Returns a NEW requirable directive.
+   */
+  certifiesEra(opts?: { certField?: string }): RequirableDirective<P>;
   /**
    * Declare the directive's READ boundary. TWO argument kinds, one declaration site:
    *   * a STRING declares a ref TYPE its `plan` may read (the original boundary —
@@ -679,6 +699,16 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
         },
       });
     },
+    certifiesEra(opts?: { certField?: string }): RequirableDirective<P> {
+      // LAWFUL RECOVERY: this directive is the custodian-authored `certifyEra` verb. Lower its id + the
+      // payload field carrying the signed `EraCertification` into the `nomosEraCertGate` era key — the kernel
+      // reads both from the law (hardcoding neither) to admit the intent (author verified to K_root) + waive
+      // the identity attestation for the certified oids. Default field HERE (the framework convention).
+      return makeRequirable({
+        ...base,
+        certifiesEraGate: { certField: opts?.certField ?? "certification" },
+      });
+    },
     reads(...reads: (string | QueryDecl)[]): RequirableDirective<P> {
       // Split by argument kind: strings are the ref-type boundary; QueryDecls are the
       // captured-read lane (#58). Both accumulate, dedup (ref types by value, queries

package/src/framework/era_certification.ts

@@ -0,0 +1,79 @@
+// NOMOS — LAWFUL RECOVERY (architecture/lawful_recovery.md). The `certifyEra` verb, shipped in the `nomos`
+// CONTROLLER domain (installed in EVERY workspace via bootstrap/installDomain) so ANY chain can fold a
+// custodian's recovery fact. A CUSTODIAN (root operator / a platform over its subtree) folds a SIGNED,
+// in-chain `EraCertification` that WAIVES the IDENTITY ATTESTATION for a named set of intent oids — while
+// the law/plan gate stays fully enforced. A custodian may VOUCH IDENTITY (heal a ForgedPrincipal/BadSignature
+// scar left by a lost enrollment or a compaction), never authorize an unlawful write.
+//
+// THE CRYPTO LIVES IN THE KERNEL: `.certifiesEra()` emits the `nomosEraCertGate` era key (this directive id +
+// the payload field carrying the artifact). The kernel then (a) ADMITS this intent by verifying its author
+// against the pinned `K_root` via the carried certification — NOT the workspace signer roster, since the
+// custodian is not enrolled here — and (b) in verify_chain, pre-scans the timeline for certifications and
+// WAIVES the identity attestation for the oids they cover. The DSL plan only FOLDS the fact (audit surface);
+// the plan CANNOT and does not verify the signature — that is the kernel's, on every lane.
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { Lww } from "../drivers.js";
+import { t } from "../fields.js";
+import { directive } from "../directive.js";
+import { set, type PlannedOp } from "../ops.js";
+import { query } from "../query.js";
+
+/** THE FOLDED RECOVERY FACT — one per certification, content-addressed (`era-certification:<id>`), append-
+ *  only. The `certification` field holds the exact signed artifact JSON the kernel verified; the flat fields
+ *  make it queryable (who certified what, when, why). NOT truth about the waiver — the kernel's verify is —
+ *  just the AUDIT record that a custodian acted, and its attribution. */
+export const EraCertification = aggregate("EraCertification", {
+  /** The signed artifact JSON verbatim (workspaceId, intentOids, waives, reason, custodianKey, signature,
+   *  certChain) — the exact bytes the kernel's `era_cert::verify` checked against K_root + this chain. */
+  certification: t.string().merge(Lww),
+  /** The custodian's public key (base64) — WHO vouched (audit; the kernel proved it roots at K_root). */
+  custodianKey: t.string().merge(Lww),
+  /** The operator's mandatory justification (audit). */
+  reason: t.string().merge(Lww),
+  /** The custodian's HLC at issue (audit). */
+  certifiedAt: t.string().merge(Lww),
+});
+
+const eraCertPayload = z.object({
+  /** The content-addressed id for the folded fact (`sha256(canonical artifact)` — caller-computed). */
+  certId: z.string().min(1),
+  /** The signed `EraCertification` artifact (the kernel verifies it against K_root + this chain's self-id). */
+  certification: z.string().min(1),
+  /** The custodian public key (base64) — audit; the kernel derives authority from the artifact's certChain. */
+  custodianKey: z.string().min(1),
+  /** The mandatory operator justification. */
+  reason: z.string().min(1),
+  /** ISO-8601, caller-stamped (the timestamp doctrine — the plan reads no clock). */
+  certifiedAt: z.string().min(1),
+});
+
+/**
+ * `certifyEra` — THE LAWFUL OPERATOR RECOVERY VERB. A custodian offers this against the SCARRED workspace;
+ * the kernel admits it by verifying the carried certification's author to the pinned `K_root` (root operator
+ * = a certification signed directly by K_root; a platform custodian = a certChain to K_root, scoped to its
+ * subtree). The plan folds the audit fact; the kernel's verify_chain pre-scan reads the SAME certification
+ * from this intent's payload and WAIVES the identity attestation for the oids it names. `.requires` NOTHING:
+ * authorization is the K_root-rooted signature (the whole point — the custodian is not an enrolled signer of
+ * the child), enforced by the era gate, not a relation.
+ */
+export const certifyEra = directive("certifyEra")
+  .ensures(EraCertification)
+  .payload(eraCertPayload)
+  .plan((p): PlannedOp[] => {
+    const fact = instance(EraCertification, `era-certification:${p.certId}`);
+    return [
+      set(fact, "certification", p.certification),
+      set(fact, "custodianKey", p.custodianKey),
+      set(fact, "reason", p.reason),
+      set(fact, "certifiedAt", p.certifiedAt),
+    ];
+  })
+  // Emit the `nomosEraCertGate` era key (this directive id + the `certification` payload field). The kernel
+  // reads both from the law, admitting the intent (author verified to K_root) + waiving the certified oids.
+  .certifiesEra();
+
+/** Read the folded certifications by custodian (audit / `githolon gov certifications`). */
+export const eraCertificationsByCustodian = query("eraCertificationsByCustodian")
+  .key("custodianKey")
+  .returns(EraCertification);

package/src/usd.ts

@@ -348,6 +348,18 @@ export interface UsdLayer {
       }
     >;
   };
+  /**
+   * THE LAWFUL-RECOVERY GATE (architecture/lawful_recovery.md). Present IFF a directive declares
+   * `.certifiesEra()`: names that directive id + the payload field carrying the signed `EraCertification`.
+   * The kernel's `nomosEraCertGate` arm admits the custodian-authored intent (verified to `K_root` via the
+   * certification, not the signer roster) + the walk waives the identity attestation for the certified oids.
+   * OMITTED for law with no certifyEra directive (the era rule — byte-identical hash; the arm inert).
+   */
+  readonly nomosEraCertGate?: {
+    readonly v: 1;
+    readonly directiveId: string;
+    readonly certField: string;
+  };
   /**
    * 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
@@ -1204,6 +1216,14 @@ export function emitUsd(
       }
       const nomosVerifiedFirstEnroll =
         Object.keys(firstEnrollReq).length > 0 ? { v: 1 as const, directives: firstEnrollReq } : undefined;
+      // LAWFUL RECOVERY: the sole `.certifiesEra()` directive (if any) → the `nomosEraCertGate` era key.
+      // (One certifyEra verb per controller law; the last declared wins — the framework declares exactly one.)
+      let eraCertGate: UsdLayer["nomosEraCertGate"];
+      for (const d of [...l.module.directives].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+        if (d.certifiesEraGate !== undefined) {
+          eraCertGate = { v: 1 as const, directiveId: d.id, certField: d.certifiesEraGate.certField };
+        }
+      }
       // 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).
@@ -1358,6 +1378,7 @@ export function emitUsd(
         ...(nomosBirthRecordGate !== undefined ? { nomosBirthRecordGate } : {}),
         ...(nomosParentAttestedBirth !== undefined ? { nomosParentAttestedBirth } : {}),
         ...(nomosVerifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll } : {}),
+        ...(eraCertGate !== undefined ? { nomosEraCertGate: eraCertGate } : {}),
         ...(nomosValueObjects !== undefined ? { nomosValueObjects } : {}),
         ...(Object.keys(visAggregates).length > 0
           ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }

package/src/usd_layers.ts

@@ -200,6 +200,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosVerifiedFirstEnroll !== undefined
       ? [`${indent}custom string nomos:verifiedFirstEnrollHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosVerifiedFirstEnroll)))}`]
       : []),
+    ...(layer.nomosEraCertGate !== undefined
+      ? [`${indent}custom string nomos:eraCertGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosEraCertGate)))}`]
+      : []),
     ...(layer.nomosValueObjects !== undefined
       ? [`${indent}custom string nomos:valueObjectsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosValueObjects)))}`]
       : []),
@@ -910,6 +913,11 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         verifiedFirstEnroll = { v: 1, directives: rec };
       }
     }
+    // LAWFUL RECOVERY: the single `nomosEraCertGate` (later-wins across the stack — one certifyEra verb).
+    let eraCertGate: UsdLayer["nomosEraCertGate"];
+    for (const l of stack) {
+      if (l.nomosEraCertGate !== undefined) eraCertGate = l.nomosEraCertGate;
+    }
     // FIRST-CLASS VALUE OBJECTS (+ the VO↔field usage pointers): descriptors merged
     // later-wins per NAME, usages later-wins per (aggregate, field), both SORTED —
     // so the layered fold stays byte-homomorphic with `emitUsd`'s composed emission.
@@ -956,6 +964,7 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(birthRecordGate !== undefined ? { nomosBirthRecordGate: birthRecordGate } : {}),
       ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
       ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
+      ...(eraCertGate !== undefined ? { nomosEraCertGate: eraCertGate } : {}),
       ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
     };
   });
@@ -1094,6 +1103,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const birthRecordGateByDomain = new Map<string, UsdLayer["nomosBirthRecordGate"]>();
   const parentAttestedBirthByDomain = new Map<string, UsdLayer["nomosParentAttestedBirth"]>();
   const verifiedFirstEnrollByDomain = new Map<string, UsdLayer["nomosVerifiedFirstEnroll"]>();
+  const eraCertGateByDomain = new Map<string, UsdLayer["nomosEraCertGate"]>();
   const valueObjectsByDomain = new Map<string, UsdLayer["nomosValueObjects"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
@@ -1181,6 +1191,10 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof vfeHex === "string") {
         verifiedFirstEnrollByDomain.set(domain, JSON.parse(unhexUtf8(vfeHex)) as UsdLayer["nomosVerifiedFirstEnroll"]);
       }
+      const ecgHex = p.attrs.get("nomos:eraCertGateHex");
+      if (typeof ecgHex === "string") {
+        eraCertGateByDomain.set(domain, JSON.parse(unhexUtf8(ecgHex)) as UsdLayer["nomosEraCertGate"]);
+      }
       // FIRST-CLASS VALUE OBJECTS: the hex-carried descriptor set (descriptive, not a gate).
       const voHex = p.attrs.get("nomos:valueObjectsHex");
       if (typeof voHex === "string") {
@@ -1290,6 +1304,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const birthRecordGate = birthRecordGateByDomain.get(domain);
       const parentAttestedBirth = parentAttestedBirthByDomain.get(domain);
       const verifiedFirstEnroll = verifiedFirstEnrollByDomain.get(domain);
+      const eraCertGate = eraCertGateByDomain.get(domain);
       const valueObjects = valueObjectsByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
@@ -1314,6 +1329,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(birthRecordGate !== undefined ? { nomosBirthRecordGate: birthRecordGate } : {}),
         ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
         ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
+        ...(eraCertGate !== undefined ? { nomosEraCertGate: eraCertGate } : {}),
         ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
       };
     })