@githolon/dsl 0.35.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.35.0",
+  "version": "0.36.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/attested.ts

@@ -28,6 +28,8 @@ import { NomosSourceFrontier } from "./attested_core.js";
 
 export {
   trustSource,
+  trustParent,
+  PARENT_TRUST_SENTINEL,
   foreignQuery,
   isTrustSourceDecl,
   NomosSourceFrontier,

package/src/attested_core.ts

@@ -94,6 +94,27 @@ export function trustSource(workspace: string, opts: TrustSourceOptions): TrustS
   return decl;
 }
 
+/** K2's genesis sentinel — `trustParent()` declares `genesis: "@parent"`; the kernel derives
+ *  identity from the reader's OWN birth certificate (kernel mirror:
+ *  `nomos_executor::PARENT_TRUST_SENTINEL`). */
+export const PARENT_TRUST_SENTINEL = "@parent";
+
+/**
+ * DECLARE trust in the reader's PARENT (K2, stage 4 — §1.3): the accepted attestor set is
+ * DERIVED from the reader's own birth certificate (`BirthAttestation.parentKey`, seeded at
+ * birth by the parent's offer-effect) plus any delegation cert the envelope carries that the
+ * parent key signed — zero hand-pinned keys, one-hop vouching by construction. `workspace`
+ * remains the ROUTABLE name (transport must know whom to ask); identity is the derived chain,
+ * never the name. Rotation = the source serves a fresh parent-signed delegation — no reader
+ * law change ever.
+ */
+export function trustParent(
+  workspace: string,
+  opts: Omit<TrustSourceOptions, "genesis" | "keyHashes" | "roster"> = {},
+): TrustSourceDecl {
+  return trustSource(workspace, { ...opts, genesis: PARENT_TRUST_SENTINEL, roster: "derived" });
+}
+
 /** Shape predicate for compile discovery (the `isQueryDecl` pattern). */
 export function isTrustSourceDecl(v: unknown): v is TrustSourceDecl {
   return (

package/src/framework/attested_receipts.ts

@@ -0,0 +1,185 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * framework/attested_receipts.ts — ATTESTATION RECEIPTS + EQUIVOCATION ACCOUNTABILITY
+ * (attested reads slice B, stage 3 — `architecture/attested_reads_design.md` §5).
+ *
+ * The SOURCE's ledger must REMEMBER what it vouched: every attested-read signature the
+ * read-attestor emits is leaf-accumulated (`sha256hex(attested_read_signed_bytes)` — derived,
+ * never carried) and SEALED into the source's own chain as one {@link NomosAttestationReceipt}
+ * per batch — one write covers up to 1024 reads. The seal is an ORDINARY OFFER
+ * ({@link recordAttestationBatch}, authored AS the enrolled `workspace:read-attestor` through
+ * the one gate); the kernel's `attestation_ledger_violation` arm DEMANDS the receipt's
+ * `batchRoot` be the Merkle root of its carried leaves on every door, so a chain-committed
+ * receipt is always internally consistent. The adapter only SCHEDULES the seal (the debounced-
+ * admission-alarm precedent: scheduling affects WHEN, never WHAT or WHETHER).
+ *
+ * The READER's half: {@link reportSourceEquivocation} folds a {@link NomosSourceDishonor} fact
+ * from two mutually-incriminating signed envelopes (same source key, same fold_root, same
+ * (queryId, args), DIVERGENT canonical results). The kernel verifies the evidence — pure
+ * carried bytes, the xwi posture — at author, edge admission, AND verify_chain; a forged or
+ * non-contradictory report is a typed refusal (`EquivocationEvidenceInvalid`). Once folded,
+ * a trust edge declaring `onDishonor: "refuse"` refuses every LATER attestation from that
+ * `(genesis, keyHash)` — position-aware like revocation, never retroactive.
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww } from "../drivers.js";
+import { directive } from "../directive.js";
+import { set } from "../ops.js";
+import { query } from "../query.js";
+
+/** The framework-reserved receipt instance-id prefix (kernel mirror:
+ *  `nomos_executor::ATTESTATION_RECEIPT_PREFIX`). */
+export const ATTESTATION_RECEIPT_PREFIX = "attest-receipt:";
+
+/** The receipt instance id for a batch. */
+export function attestationReceiptId(batchId: string): string {
+  return ATTESTATION_RECEIPT_PREFIX + batchId;
+}
+
+/** The framework-reserved dishonor instance-id prefix (kernel mirror:
+ *  `nomos_executor::SOURCE_DISHONOR_PREFIX`). */
+export const SOURCE_DISHONOR_PREFIX = "source-dishonor:";
+
+/** The dishonor instance id for a proven `(sourceGenesis, keyHash)`. */
+export function sourceDishonorId(sourceGenesis: string, keyHash: string): string {
+  return `${SOURCE_DISHONOR_PREFIX}${sourceGenesis}:${keyHash}`;
+}
+
+/**
+ * NomosAttestationReceipt (§5.1) — ONE sealed batch of attested-read receipt leaves in the
+ * SOURCE's own chain. Each leaf = `sha256hex(attested_read_signed_bytes)` — it commits to the
+ * FULL attestation (query, args, canonical result, head, fold_root, epoch, time) with zero
+ * extra signed bytes and NO reader identity (least-disclosure). `receiptPath` (the kernel
+ * query op) serves Merkle inclusion `{batchRoot, index, path}` from the folded `leaves`.
+ */
+export const NomosAttestationReceipt = aggregate("NomosAttestationReceipt", {
+  /** `"<epoch>-<nSealedReceiptsInFold>-<keyHash8>"` — chain-derived mint (collision-free across remounts); promised on every envelope's `receipt_hint`. */
+  batchId: t.string().merge(Lww),
+  /** sha256 Merkle root over the batch's leaf hashes (kernel-verified == root(leaves) at the gate). */
+  batchRoot: t.string().merge(Lww),
+  /** The leaf count (kernel-verified == leaves.length at the gate). */
+  leafCount: t.int().merge(Lww),
+  /** The leaf hashes, in serve order (JSON array) — what `receiptPath` serves from. */
+  leaves: t.json().merge(Lww),
+  /** The `attested_at_ms` range the batch covers. */
+  firstAt: t.int().merge(Lww),
+  lastAt: t.int().merge(Lww),
+  /** The source chain position when the batch sealed. */
+  headAtSeal: t.string().merge(Lww),
+  foldRootAtSeal: t.string().merge(Lww),
+  /** Which read-attestor key signed every member of this batch (`sha256hex(pubkey)`). */
+  signerKeyHash: t.string().merge(Lww),
+});
+
+/** Audit read: the source's sealed receipt stream, by batch id. */
+export const attestationReceiptByBatch = query("attestationReceiptByBatch")
+  .key("batchId")
+  .returns(NomosAttestationReceipt);
+
+/**
+ * `recordAttestationBatch` (§5.2) — THE SEAL. One authored intent per batch, authored AS the
+ * enrolled `workspace:read-attestor` through the NORMAL offer gate (the key is an enrolled
+ * signer precisely so it can do this — §1.2's "one key, two duties"). The payload is the
+ * kernel's own `attestationOpenBatch` snapshot, carried verbatim by the adapter; the gate
+ * re-derives the Merkle root and refuses any drift (`AttestationReceiptInvalid`) — the
+ * adapter carries, never computes. Seal triggers (leafCount ≥ 1024 / age ≥ 60s / epoch change
+ * / unmount) are the kernel's verdict on the same snapshot; a failed seal retries, never
+ * drops silently.
+ */
+export const recordAttestationBatch = directive("recordAttestationBatch")
+  .ensures(NomosAttestationReceipt)
+  .payload(
+    z.object({
+      batchId: z.string().min(1),
+      batchRoot: z.string().min(1),
+      leafCount: z.number().int().positive(),
+      leaves: z.array(z.string().min(1)).min(1),
+      firstAt: z.number().int().nonnegative(),
+      lastAt: z.number().int().nonnegative(),
+      headAtSeal: z.string(),
+      foldRootAtSeal: z.string(),
+      signerKeyHash: z.string().min(1),
+    }),
+  )
+  .plan((p) => {
+    const r = instance(NomosAttestationReceipt, attestationReceiptId(p.batchId));
+    return [
+      set(r, "batchId", p.batchId),
+      set(r, "batchRoot", p.batchRoot),
+      set(r, "leafCount", p.leafCount),
+      set(r, "leaves", JSON.stringify(p.leaves)),
+      set(r, "firstAt", p.firstAt),
+      set(r, "lastAt", p.lastAt),
+      set(r, "headAtSeal", p.headAtSeal),
+      set(r, "foldRootAtSeal", p.foldRootAtSeal),
+      set(r, "signerKeyHash", p.signerKeyHash),
+    ];
+  });
+
+/**
+ * NomosSourceDishonor (§5.3) — a PROVEN equivocation, folded in the READER's (or a
+ * governor's) chain at `source-dishonor:<sourceGenesis>:<keyHash>`. The full evidence (the
+ * two signed envelopes) rides the committed intent's payload — the fact aggregate carries
+ * the identity tuple + when it was proven. Once folded, `onDishonor: "refuse"` trust edges
+ * refuse every LATER attestation from this `(genesis, keyHash)` (position-aware).
+ */
+export const NomosSourceDishonor = aggregate("NomosSourceDishonor", {
+  /** The equivocating source chain's genesis oid (its true identity). */
+  sourceGenesis: t.string().merge(Lww),
+  /** The equivocating read-attestor key (`sha256hex(pubkey)`). */
+  keyHash: t.string().merge(Lww),
+  /** The fold-root BOTH envelopes pinned — the state the source spoke of with two tongues. */
+  foldRoot: t.string().merge(Lww),
+  /** When the reporter proved it (ms — the reporter's clock, informational). */
+  provenAtMs: t.int().merge(Lww),
+});
+
+/** Audit read: the folded dishonor facts, by source genesis. */
+export const sourceDishonorByGenesis = query("sourceDishonorByGenesis")
+  .key("sourceGenesis")
+  .returns(NomosSourceDishonor);
+
+/** One carried evidence envelope (an attested read exactly as captured — §5.3 walk 1). */
+const evidenceEnvelope = z.object({
+  queryId: z.string().min(1),
+  args: z.record(z.string(), z.string()).default({}),
+  result: z.unknown(),
+  attestation: z.record(z.string(), z.unknown()),
+});
+
+/**
+ * `reportSourceEquivocation` (§5.3) — carry TWO signed attested-read envelopes; the KERNEL
+ * gate verifies (pure carried bytes): both ed25519 signatures, same source key, same
+ * `(source_genesis, fold_root, queryId, canonical args)`, DIVERGENT canonical results — and
+ * that the folded fact's id names exactly the proven `(genesis, keyHash)`. Forged or
+ * non-contradictory evidence is `EquivocationEvidenceInvalid` on every door. The plan trusts
+ * the payload's identity mirrors ONLY because the gate re-derives them from the evidence.
+ */
+export const reportSourceEquivocation = directive("reportSourceEquivocation")
+  .ensures(NomosSourceDishonor)
+  .payload(
+    z.object({
+      a: evidenceEnvelope,
+      b: evidenceEnvelope,
+      /** Mirror of the proven identity (kernel-checked against the verified evidence). */
+      sourceGenesis: z.string().min(1),
+      keyHash: z.string().min(1),
+      foldRoot: z.string().min(1),
+      provenAtMs: z.number().int().nonnegative(),
+    }),
+  )
+  .plan((p) => {
+    const d = instance(NomosSourceDishonor, sourceDishonorId(p.sourceGenesis, p.keyHash));
+    return [
+      set(d, "sourceGenesis", p.sourceGenesis),
+      set(d, "keyHash", p.keyHash),
+      set(d, "foldRoot", p.foldRoot),
+      set(d, "provenAtMs", p.provenAtMs),
+    ];
+  });

package/src/framework/source_roster.ts

@@ -0,0 +1,96 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * framework/source_roster.ts — K3 TRACKED ROSTERS (attested reads slice B, stage 5 —
+ * `architecture/attested_reads_design.md` §1.5).
+ *
+ * The reader's chain maintains a {@link NomosSourceRoster} per trusted source: a reader-side
+ * mirror of the SOURCE's own read-attestor signer roster, delivered as ATTESTED READS of the
+ * source's signer chain itself (the kernel-native `attestorRoster` query — the roster rides
+ * the SAME attested-read machinery as any foreign premise). `roster: "tracked"` on the trust
+ * edge activates the folded roster inside `accepted_keys`; rotation then needs ZERO reader
+ * law deploys, and a source-side revocation propagates on the reader's next sync.
+ *
+ * THE GROUNDED RECURSION (§1.5.2): a roster read's envelope is verified against the accepted
+ * set AS ALREADY FOLDED in the reader's prefix — the FIRST sync therefore verifies against
+ * the bootstrap trust (the K1 pins or the K2 birth-cert-derived key), which exists by
+ * construction before any roster does; every later sync verifies against the roster its own
+ * prefix folded. Deterministic at replay: the roster is reader-chain state.
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww } from "../drivers.js";
+import { directive, type Directive } from "../directive.js";
+import { set } from "../ops.js";
+import { read } from "../read.js";
+import { foreignQuery } from "../attested_core.js";
+
+/** The framework-reserved roster instance-id prefix (kernel mirror:
+ *  `nomos_executor::SOURCE_ROSTER_PREFIX`). */
+export const SOURCE_ROSTER_PREFIX = "source-roster:";
+
+/** The roster instance id for a source genesis. */
+export function sourceRosterId(sourceGenesis: string): string {
+  return SOURCE_ROSTER_PREFIX + sourceGenesis;
+}
+
+/** The kernel-native source-side roster query id (`nomos_executor::ATTESTOR_ROSTER_QUERY`). */
+export const ATTESTOR_ROSTER_QUERY_ID = "attestorRoster";
+
+/**
+ * NomosSourceRoster (§1.5) — the reader's folded mirror of one source's read-attestor
+ * roster, keyed by the source's TRUE identity (`source-roster:<genesis>`). `rosterJson` is
+ * the `keyHash → leaf` map exactly as the source's signer chain folds it (a key is ACCEPTED
+ * iff its leaf's `status == "active"` — the position-aware revocation mirror); the kernel's
+ * `accepted_keys` reads THIS under `roster: "tracked"`.
+ */
+export const NomosSourceRoster = aggregate("NomosSourceRoster", {
+  /** The routable source name the edge was declared under (diagnostics). */
+  source: t.string().merge(Lww),
+  /** The `keyHash → enrollment leaf` map, JSON — as attested by the source's own chain. */
+  rosterJson: t.json().merge(Lww),
+  /** The source's `SignerEpoch` at the attested sync. */
+  currentEpoch: t.int().merge(Lww),
+});
+
+/** One roster row as the source's `attestorRoster` query answers it. */
+interface AttestorRosterRow {
+  id: string;
+  data: {
+    genesis: string;
+    currentEpoch: number;
+    keys: Record<string, unknown>;
+  };
+}
+
+/**
+ * BUILD the reader-side `syncSourceRoster` framework directive for ONE tracked source
+ * (§1.5.1) — export the result from the law that declares `trustSource(sourceWs, { roster:
+ * "tracked", … })`. Its plan performs `read(attestorRoster, {}, { from: sourceWs })` (an
+ * ordinary attested read — verified by the five-step arm against the accepted set the reader's
+ * PREFIX already folds: pins/birth-cert first, then the roster itself) and folds the answer
+ * into {@link NomosSourceRoster}. One directive per tracked source per law (the id embeds
+ * nothing — a law tracking several sources exports several via distinct ids).
+ */
+export function sourceRosterSync(sourceWs: string, directiveId = "syncSourceRoster"): Directive<Record<string, never>> {
+  const rosterQuery = foreignQuery(ATTESTOR_ROSTER_QUERY_ID);
+  return directive(directiveId)
+    .ensures(NomosSourceRoster)
+    .payload(z.object({}).strict())
+    .plan(() => {
+      const rows = read<AttestorRosterRow[]>(rosterQuery, {}, { from: sourceWs });
+      if (rows.length === 0) throw new Error("attestor-roster-empty");
+      const d = rows[0]!.data;
+      const r = instance(NomosSourceRoster, sourceRosterId(d.genesis));
+      return [
+        set(r, "source", sourceWs),
+        set(r, "rosterJson", JSON.stringify(d.keys ?? {})),
+        set(r, "currentEpoch", d.currentEpoch ?? 0),
+      ];
+    })
+    .readsFrom(sourceWs, rosterQuery) as Directive<Record<string, never>>;
+}

package/src/index.ts

@@ -124,6 +124,8 @@ export { read } from "./read.js";
 // surface (`trustSource`), the foreign query reference, and the reader-side SourceFrontier.
 export {
   trustSource,
+  trustParent,
+  PARENT_TRUST_SENTINEL,
   foreignQuery,
   NomosSourceFrontier,
   sourceFrontierId,
@@ -133,6 +135,31 @@ export {
   type TrustSourceOptions,
   type ForeignQueryRef,
 } from "./attested.js";
+// ATTESTATION RECEIPTS + EQUIVOCATION ACCOUNTABILITY (slice B stage 3 — §5): the source-side
+// sealed receipt batch + the reader-side proven-dishonor fact, both ordinary law the kernel's
+// `attestation_ledger_violation` arm guards on every door.
+export {
+  NomosAttestationReceipt,
+  recordAttestationBatch,
+  attestationReceiptByBatch,
+  attestationReceiptId,
+  ATTESTATION_RECEIPT_PREFIX,
+  NomosSourceDishonor,
+  reportSourceEquivocation,
+  sourceDishonorByGenesis,
+  sourceDishonorId,
+  SOURCE_DISHONOR_PREFIX,
+} from "./framework/attested_receipts.js";
+// K3 TRACKED ROSTERS (slice B stage 5 — §1.5): the reader-side folded source roster + the
+// per-source sync directive factory (roster updates ride the attested-read machinery itself,
+// grounded on the pins/birth-cert bootstrap).
+export {
+  NomosSourceRoster,
+  sourceRosterSync,
+  sourceRosterId,
+  SOURCE_ROSTER_PREFIX,
+  ATTESTOR_ROSTER_QUERY_ID,
+} from "./framework/source_roster.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