@githolon/dsl 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.5.0",
+  "version": "0.6.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/aggregate.ts

@@ -25,6 +25,46 @@ import type { Field } from "./fields.js";
 export type AggregateInvariantVerdict = { accept: true } | { reject: string };
 export type AggregateInvariantFn = (snapshot: Record<string, unknown>) => AggregateInvariantVerdict;
 
+/**
+ * READ VISIBILITY (slice 5.1, `host_routes_only.md` §5.1) — the DECLARED posture
+ * of an aggregate's data on the read side. `public` (the DEFAULT, and the only
+ * value before this existed) means any peer may read the type; `requires(cap)`
+ * makes the type PRIVATE: a read that touches it (a `query` returning it, a
+ * `count`/`sum` over it, a by-id read of one of its instances) is served ONLY to a
+ * principal that effectively holds `cap` in THIS workspace's own folded
+ * role-bindings (the kernel `identity::authz` path, lifted from the write gate).
+ *
+ * THE LAW DECIDES, NOT THE HOST: the visibility rides IN the law package (the
+ * `nomosReadVisibility` USD era key — OMITTED when every aggregate is public, so
+ * an all-public domain hashes byte-identically to before this existed) and the
+ * githolon enforces it at the one wasm read boundary. The host only STAMPS the
+ * presented principal (an impure identity read) and relays the githolon's verdict.
+ *
+ * `cap` is a CAPABILITY NAME (the same vocabulary as a role's caps / a directive
+ * name — see `framework/rbac.ts`): the workspace's owner authors a `grant` of a
+ * role carrying `cap` to the reader's principal (e.g. at birth, over the
+ * secret-gated author lane). A degenerate identity catalogue (role ≡ cap) means
+ * "holds an active, unexpired, non-revoked binding whose role grants `cap`".
+ */
+export type ReadVisibility = { readonly requires: string };
+
+/** Capability/role names: a non-empty token, no whitespace or quotes (it rides a USD string + a JSON leaf). */
+const READ_CAP_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+
+/**
+ * Declare an aggregate PRIVATE behind a capability — the value for
+ * `aggregate(id, fields, { visibility: requires("readEntry") })`. The only
+ * non-default {@link ReadVisibility}; `public` is the omitted default.
+ */
+export function requires(capability: string): ReadVisibility {
+  if (!READ_CAP_NAME_RE.test(capability)) {
+    throw new Error(
+      `requires(): capability must match ${READ_CAP_NAME_RE} (a capability/role name); got ${JSON.stringify(capability)}`,
+    );
+  }
+  return { requires: capability };
+}
+
 /**
  * An aggregate has two genuinely different kinds of member, and the DSL keeps them
  * APART so no downstream layer ever has to re-derive the distinction:
@@ -89,17 +129,57 @@ export interface AggregateHandle<
    * cap-free domains hash byte-identically to before this key existed.
    */
   readonly cap?: number;
+  /**
+   * READ VISIBILITY (slice 5.1). PRESENT only when the type is declared PRIVATE
+   * (`visibility: requires(cap)`); OMITTED ENTIRELY for the default `public`, so a
+   * public-only domain is byte-identical to before this key existed (the
+   * `nomosReadVisibility` era key is likewise omitted). See {@link ReadVisibility}.
+   */
+  readonly visibility?: ReadVisibility;
+  /**
+   * E2E ENCRYPTION (e2e_encryption.md slice 2) — the STORED field names whose values
+   * are `.encrypted()`, SORTED. PRESENT only when ≥1 field is encrypted; OMITTED
+   * otherwise (a plaintext aggregate is byte-identical, and the `nomosEncryption` era
+   * key is likewise omitted). `aggregate()` enforces that an encrypted field's
+   * aggregate is `visibility: requires(cap)` (the scope) and its driver is Lww-class.
+   */
+  readonly encryptedFields?: string[];
 }
 
 export function aggregate<const Id extends string, F extends Record<string, Field>>(
   id: Id,
   fields: F,
-  opts?: { invariant?: AggregateInvariantFn; cap?: number },
+  opts?: { invariant?: AggregateInvariantFn; cap?: number; visibility?: ReadVisibility },
 ): AggregateHandle<Id, F> {
   const { stored, hasMany } = partitionFields(fields);
   if (opts?.cap !== undefined && (!Number.isInteger(opts.cap) || opts.cap < 1)) {
     throw new Error(`aggregate '${id}': cap must be a positive integer (got ${opts.cap})`);
   }
+  if (opts?.visibility !== undefined && !READ_CAP_NAME_RE.test(opts.visibility.requires)) {
+    throw new Error(`aggregate '${id}': visibility.requires must be a capability name`);
+  }
+  // E2E ENCRYPTION (slice 2): the fields marked `.encrypted()`, validated. An encrypted
+  // field's VALUE is sealed to the aggregate's read scope, so the aggregate MUST be
+  // private, and the driver must be Lww-class (the ciphertext envelope is replaced
+  // wholesale — additive/counter merges over ciphertext are meaningless).
+  const encryptedFields = Object.entries(stored)
+    .filter(([, f]) => (f as Field).isEncrypted === true)
+    .map(([name]) => name)
+    .sort();
+  if (encryptedFields.length > 0) {
+    if (opts?.visibility === undefined) {
+      throw new Error(
+        `aggregate '${id}': field(s) ${encryptedFields.join(", ")} are .encrypted() but the aggregate is not private — add { visibility: requires("<cap>") } (the encryption scope IS the read scope)`,
+      );
+    }
+    for (const name of encryptedFields) {
+      if (!isLwwClass((stored[name] as Field).driver)) {
+        throw new Error(
+          `aggregate '${id}': field '${name}' is .encrypted() but its merge driver is not Lww-class — an encrypted value is a ciphertext envelope replaced wholesale, so only Lww / MapOf(Lww) are valid`,
+        );
+      }
+    }
+  }
   return {
     id,
     fields: stored as StoredFields<F>,
@@ -109,9 +189,18 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
       ? { hasInvariant: true as const, invariant: opts.invariant }
       : {}),
     ...(opts?.cap !== undefined ? { cap: opts.cap } : {}),
+    ...(opts?.visibility !== undefined ? { visibility: opts.visibility } : {}),
+    ...(encryptedFields.length > 0 ? { encryptedFields } : {}),
   };
 }
 
+/** Lww-class driver: a wholesale-replace merge (`Lww`, or `MapOf` wrapping an Lww-class inner). */
+function isLwwClass(driver: { kind: string; inner?: { kind: string } }): boolean {
+  if (driver.kind === "Lww") return true;
+  if (driver.kind === "MapOf" && driver.inner) return isLwwClass(driver.inner as { kind: string });
+  return false;
+}
+
 /**
  * A bound aggregate reference — a handle pinned to a concrete INSTANCE id.
  *

package/src/codegen_proof.ts

@@ -188,6 +188,77 @@ export interface TsProofOptions {
   readonly domainHash: string;
 }
 
+/** The machine-readable OFFLINE legs for ONE domain (the `@nomos-proof-legs`
+ *  marker shape; the `proof-legs.json` index is a map of these by domain key). */
+export interface ProofLegs {
+  readonly domain: string;
+  readonly directiveId: string;
+  readonly aggregateId: string;
+  readonly payload: Record<string, unknown>;
+  readonly autoStamped: readonly string[];
+  readonly mintField?: string;
+  readonly query?: { readonly id: string; readonly params: Record<string, unknown> };
+  readonly count?: { readonly id: string; readonly group: string };
+}
+
+/** Synthesize the offline legs for one domain module, or `null` when it has no
+ *  creating write (nothing to prove). The SINGLE source of the leg-selection
+ *  logic — `generateTsProof` (the .mts marker) and `proofLegsIndex` (the
+ *  per-domain index) both call this, so the offline lane proves any domain the
+ *  same way the generated proof proves its primary one. */
+export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
+  const createDir = (mod.directives as Directive<unknown>[]).find(
+    (d) => d?.marker === "creates" && typeof d.payloadSchema === "object",
+  );
+  if (createDir === undefined) return null;
+  const domain = mod.domain ?? mod.name;
+  const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === createDir.aggregateId);
+  if (agg === undefined) return null;
+  const synth = synthesizePayload(createDir.payloadSchema as z.ZodTypeAny, `${domain}/${createDir.id}`);
+  const mintField = mintedCreateField(createDir, agg);
+  const baseValue: Record<string, unknown> = { ...synth.value };
+  if (mintField !== undefined) delete baseValue[mintField];
+  const query = ((mod.queries ?? []) as QueryDecl[]).find(
+    (q) => q.returns === agg.id && q.key.length > 0 && q.key.every((k) => !k.includes(".") && baseValue[k] !== undefined),
+  );
+  const count = (mod.counts ?? [])
+    .map((raw) => finishCount(raw))
+    .find((c) => c.of === agg.id && (c as { where?: unknown }).where == null && (c.by == null || baseValue[c.by] !== undefined));
+  return {
+    domain,
+    directiveId: createDir.id,
+    aggregateId: agg.id,
+    payload: baseValue,
+    autoStamped: synth.autoStamped,
+    ...(mintField !== undefined ? { mintField } : {}),
+    ...(query ? { query: { id: query.id, params: Object.fromEntries(query.key.map((k) => [k, baseValue[k]])) } } : {}),
+    ...(count ? { count: { id: count.id, group: count.by != null ? String(baseValue[count.by]) : "" } } : {}),
+  };
+}
+
+/** The per-domain legs index for `build/<name>.proof-legs.json` — every domain
+ *  with a creating write, plus the default (the first, which the .mts proves).
+ *  `githolon proof [--domain <key>]` runs any of these offline. */
+export function proofLegsIndex(modules: readonly DomainModule[]): { default: string; domains: Record<string, ProofLegs> } | null {
+  const domains: Record<string, ProofLegs> = {};
+  let first: string | undefined;
+  for (const mod of modules) {
+    // FAIL SOFT per-module: a sibling domain whose payload can't be synthesized
+    // (an exotic zod shape synthesizePayload throws on) must not lose the index
+    // for the domains that DO synthesize — skip it, keep the rest.
+    let legs: ProofLegs | null;
+    try {
+      legs = proofLegsForModule(mod);
+    } catch {
+      continue;
+    }
+    if (legs === null) continue;
+    domains[legs.domain] = legs;
+    if (first === undefined) first = legs.domain;
+  }
+  return first === undefined ? null : { default: first, domains };
+}
+
 export function generateTsProof(modules: readonly DomainModule[], opts: TsProofOptions): string {
   // The proof drives the FIRST domain that has a creating write — without one
   // there is nothing to author, so there is nothing to prove.
@@ -203,7 +274,11 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   const factory = tsClientFactoryName(domain);
   const hashConst = tsHashConstName(opts.packageName);
 
-  const createDir = (mod.directives as Directive<unknown>[]).find((d) => d?.marker === "creates")!;
+  // SAME predicate as the mod selection above AND proofLegsForModule — so the
+  // proof body, its marker, and the index can never describe different directives.
+  const createDir = (mod.directives as Directive<unknown>[]).find(
+    (d) => d?.marker === "creates" && typeof d.payloadSchema === "object",
+  )!;
   const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === createDir.aggregateId);
   if (agg === undefined) {
     throw new Error(
@@ -260,17 +335,9 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   const listAccessor = `list${agg.id}s`;
 
   // THE MACHINE-READABLE LEGS (parsed by `githolon`'s offline proof runner —
-  // cli/src/proof_offline.ts — instead of regex-scraping the generated source).
-  const legsMarker = JSON.stringify({
-    domain,
-    directiveId: createDir.id,
-    aggregateId: agg.id,
-    payload: baseValue,
-    autoStamped: synth.autoStamped,
-    ...(mintField !== undefined ? { mintField } : {}),
-    ...(query && queryParamsObj ? { query: { id: query.id, params: queryParamsObj } } : {}),
-    ...(count ? { count: { id: count.id, group: count.by != null ? String(baseValue[count.by]) : "" } } : {}),
-  });
+  // cli/src/proof_offline.ts). The ONE leg-synthesis (`proofLegsForModule`) feeds
+  // both this marker and the per-domain `proof-legs.json` index, so they never drift.
+  const legsMarker = JSON.stringify(proofLegsForModule(mod));
 
   let step = 0;
   const n = () => ++step;

package/src/compile_package_main.ts

@@ -104,7 +104,7 @@ import {
 } from "./stable_ids.js";
 import type { UsdLayer } from "./usd.js";
 import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
-import { generateTsProof } from "./codegen_proof.js";
+import { generateTsProof, proofLegsIndex } from "./codegen_proof.js";
 
 const DSL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -1287,10 +1287,20 @@ async function main(): Promise<void> {
   //        synthesizer can't sample yet still compiles — the skip names its remedy.
   let proofPath: string | undefined;
   let proofSkip: string | undefined;
+  let proofDomains: string[] = [];
   try {
     const proofSrc = generateTsProof(domainModules, { packageName: cfg.name, domainHash });
     proofPath = path.join(outDir, `${cfg.name}.proof.mts`);
     writeFileSync(proofPath, proofSrc, "utf8");
+    // THE PER-DOMAIN LEGS INDEX: every domain with a creating write, so
+    // `githolon proof --domain <key>` proves ANY of them offline (the .mts
+    // proves the primary one live). A multi-domain package no longer locks the
+    // proof to whichever domain happens to be first.
+    const legsIndex = proofLegsIndex(domainModules);
+    if (legsIndex !== null) {
+      writeFileSync(path.join(outDir, `${cfg.name}.proof-legs.json`), JSON.stringify(legsIndex, null, 2) + "\n", "utf8");
+      proofDomains = Object.keys(legsIndex.domains);
+    }
   } catch (e) {
     proofSkip = (e as Error).message;
   }
@@ -1385,6 +1395,9 @@ async function main(): Promise<void> {
     console.log(`prove it OFFLINE first: npx githolon proof        # the generated proof's offline legs on a LOCAL holon (no cloud workspace)`);
     console.log(`  inner loop:           npx githolon dev          # watch -> recompile -> law live locally -> offline proof, on every save`);
     console.log(`  then the cloud loop:  npx githolon proof --live # throwaway workspace, retired on exit (--keep keeps it)`);
+    if (proofDomains.length > 1) {
+      console.log(`  this package proves ${proofDomains.length} domains (${proofDomains.join(", ")}) — default '${proofDomains[0]}'; pick another: npx githolon proof --domain <key>`);
+    }
   } else {
     console.log(`prove it: npm run e2e   # offline write -> sync -> admission -> cloud query, live`);
   }

package/src/fields.ts

@@ -115,8 +115,22 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * `Schema` (which is driver-only, see `encodeKernelSchema`), so it changes no hash.
    */
   readonly isOptional: boolean;
+  /**
+   * E2E ENCRYPTION (e2e_encryption.md slice 2): mark this field's VALUE encrypted — its
+   * plaintext is sealed (XChaCha20-Poly1305) by the author client and rides as an opaque
+   * ciphertext envelope in the `Str` leaf. PRESENT only when declared; OMITTED otherwise
+   * so a plaintext domain is byte-identical (the `nomosEncryption` era key is likewise
+   * omitted). VALID ONLY on a field whose aggregate is `visibility: requires(cap)` (the
+   * encryption scope ≡ the read scope) and whose driver is Lww-class (the envelope is
+   * replaced wholesale; additive/counter merges over ciphertext are meaningless) —
+   * `aggregate()` enforces both, else a compile-time throw. (Flag named `isEncrypted` —
+   * the `encrypted()` METHOD sets it, mirroring `optional()`/`isOptional`.)
+   */
+  readonly isEncrypted?: true;
   /** Returns a copy with the chosen driver (kind literal preserved). */
   merge(driver: Driver): Field<T, K>;
+  /** Mark this field's value ENCRYPTED (sets {@link Field.isEncrypted}). Chainable + non-destructive. */
+  encrypted(): Field<T, K>;
   /**
    * Mark this (scalar) field OPTIONAL: a folded aggregate may lack it, so the
    * generated Dart type is nullable + tolerant. Chainable + non-destructive (kind
@@ -139,6 +153,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     isOptional?: boolean;
     mapValueKind?: FieldKind;
     jsonShape?: "object";
+    encrypted?: true;
   } = {},
 ): Field<T, K> {
   const isOptional = extra.isOptional ?? false;
@@ -152,6 +167,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.viaField !== undefined ? { viaField: extra.viaField } : {}),
     ...(extra.mapValueKind !== undefined ? { mapValueKind: extra.mapValueKind } : {}),
     ...(extra.jsonShape !== undefined ? { jsonShape: extra.jsonShape } : {}),
+    ...(extra.encrypted ? { isEncrypted: true as const } : {}),
     merge(d: Driver) {
       return makeField<T, K>(kind, zod, d, extra);
     },
@@ -164,6 +180,12 @@ function makeField<T, K extends FieldKind = FieldKind>(
         isOptional: true,
       });
     },
+    encrypted(): Field<T, K> {
+      // Carry the flag through merge/optional (extra is threaded), so `.merge(Lww).encrypted()`
+      // and `.encrypted().merge(Lww)` agree. The wire schema is UNCHANGED (driver-only) — the
+      // `nomosEncryption` era key, built by aggregate()/manifest, is what carries the fact.
+      return makeField<T, K>(kind, zod, driver, { ...extra, encrypted: true });
+    },
   };
   return f;
 }

package/src/framework/encryption_identity.ts

@@ -0,0 +1,92 @@
+// 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/encryption_identity.ts — the E2E ENCRYPTION KEY REGISTRY (slice 1 of the
+ * `architecture/e2e_encryption.md` arc). Tenant-agnostic framework MECHANISM, the
+ * encryption sibling of `framework/rbac.ts`'s authority registry.
+ *
+ * THE ROLE: the key-handoff lane (slice 4) wraps a scope's epoch secret TO a grant
+ * recipient's X25519 PUBLIC key. To do that it must look up "principal → encryption
+ * public key" on-chain. This module is that registry: a principal PUBLISHES its X25519
+ * public key (the secret stays client-side — WebCrypto non-extractable / native keystore
+ * / ~/.holon, never on any chain), and `grant`/the fan-out gate resolve it by principal.
+ *
+ * PRINCIPAL-KEYED, NOT device-keyed — deliberately. The read-visibility grant
+ * (`rbac.ts`) targets a `principal` (the auth-provider uid), and the launch platforms use
+ * bare auth-provider principals with no full Actor/DeviceKey model. So the encryption key
+ * is keyed by the SAME principal the grant targets — one decoupled registry a tenant
+ * composes WITHOUT the full `identity.ts` domain. (Multi-device per principal, and the
+ * ed25519 `encKeyProof` binding the X25519 key to a signing identity, are refinements;
+ * v1 binds publication to the authoring principal via the intent's own author signature.)
+ *
+ * SECURITY NOTE — publication is only as strong as the authoring identity. A
+ * `publishEncKey` authored under a VERIFIED `x-nomos-auth` token genuinely binds the
+ * X25519 key to that principal; under the transitional bare-claim lane it is spoofable
+ * exactly like every other bare write. The key-distribution gate (slice 4) must treat a
+ * recipient with no published key as "not yet a member" (fail-closed), never wrap to a
+ * default. Auth-as-capability (slice 5.3) hardens the binding.
+ */
+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, type PlannedOp } from "../ops.js";
+import { query } from "../query.js";
+
+/** Base64 of a 32-byte X25519 public key (≈44 chars). The wrap target. */
+const X25519_PUB_B64_RE = /^[A-Za-z0-9+/]{42,44}={0,2}$/;
+
+/**
+ * The per-principal encryption-key record. Multi-instance, keyed
+ * `enc-key-<principal>` (mirrors `rbac.ts`'s `user-permissions-<userId>`). `encPublicKey`
+ * is the published X25519 public key; a re-publish (Lww) is a client-driven key rotation
+ * (which the owner should follow with a scope epoch rotation so new wraps target it).
+ */
+export const EncKey = aggregate("EncKey", {
+  principal: t.string().merge(Lww),
+  encPublicKey: t.string().merge(Lww), // base64 X25519 (32 bytes)
+  publishedAt: t.string().merge(Lww), // ISO-8601, caller-stamped (determinism)
+});
+export type EncKeyHandle = typeof EncKey;
+
+/** Deterministic per-principal instance id — `enc-key-<principal>`. */
+export function encKeyInstanceId(principal: string): string {
+  return `enc-key-${principal}`;
+}
+
+/** The framework PRIMITIVE plan: publish (or rotate) `principal`'s X25519 public key. */
+export function writeEncKey(p: { principal: string; encPublicKey: string; publishedAt: string }): PlannedOp[] {
+  if (!X25519_PUB_B64_RE.test(p.encPublicKey)) {
+    throw new Error(`publishEncKey: encPublicKey must be base64 of a 32-byte X25519 key`);
+  }
+  const k = instance(EncKey, encKeyInstanceId(p.principal));
+  return [
+    set(k, "principal", p.principal),
+    set(k, "encPublicKey", p.encPublicKey),
+    set(k, "publishedAt", p.publishedAt),
+  ];
+}
+
+/**
+ * `publishEncKey` — the framework directive a principal authors to publish its X25519
+ * encryption public key. `.ensures(EncKey)` (upsert-by-deterministic-key — first publish
+ * materializes, a re-publish rotates). Generic (not tenant-specific), so it ships as a
+ * full directive, not just a plan builder.
+ */
+export const publishEncKey = directive("publishEncKey")
+  .ensures(EncKey)
+  .payload(
+    z.object({
+      principal: z.string().min(1),
+      encPublicKey: z.string().min(1),
+      publishedAt: z.string().min(1),
+    }),
+  )
+  .plan((p) => writeEncKey(p));
+
+/** Resolve a principal's published encryption key — the wrap-target lookup (slice 4). */
+export const encKeyByPrincipal = query("encKeyByPrincipal").key("principal").returns(EncKey);

package/src/framework/encryption_scope.ts

@@ -0,0 +1,158 @@
+// 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/encryption_scope.ts — THE GROUP-KEY EVENTS (e2e_encryption.md slice 4).
+ * RFC 9420 (MLS) mapped onto the event-sourced ledger, SENDER-KEYS variant (flat
+ * per-epoch direct-wrap; TreeKEM dropped — small scopes, §4 of the sheet).
+ *
+ * A SCOPE is the read cap (`requires("readNote")` ≡ the MLS group). Each scope has
+ * EPOCHS; a write encrypts a field with the scope's CURRENT epoch key. The epoch key
+ * itself NEVER lands on-chain — only its WRAPS do: per member, the epoch key
+ * HPKE-sealed to that member's published X25519 key (`encryption_identity.ts`).
+ * Wrapped keys are CIPHERTEXT, safe to publish. A reader replays the WrappedKey
+ * events addressed to its principal, unwraps with its device key (host-side, never
+ * in the wasm), and decrypts the fields it is authorized for.
+ *
+ * THE EVENTS (this module's aggregates):
+ *  - `KeyScope`   — the per-scope head: `currentEpoch`. A write's envelope epoch must
+ *    equal this at the write's position (the gate enforces it — slice 5).
+ *  - `WrappedKey` — one epoch-key wrap to one member (keyed scope|epoch|principal).
+ *
+ * THE DIRECTIVE: `advanceKeyEpoch` opens a new epoch and FANS OUT the wraps to every
+ * member IN ONE INTENT (the membership change is a single visible, owner-authored
+ * event). The wraps are computed CLIENT-SIDE by the committer (who holds the epoch
+ * secret + looks up each recipient's pubkey) and ride in the payload as opaque
+ * ciphertext; the plan only stores the facts. Forward-only revocation = an advance
+ * whose fan-out OMITS the removed member (slice 5 gates the roster + the rotation).
+ *
+ * NON-DELEGATABLE (critical #2): an encrypted scope's `nomosEncryption` carries
+ * `delegatable:false`; the slice-5 fan-out gate derives the roster from DIRECT grants
+ * only and refuses a wrap to a delegation-sourced member.
+ */
+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, withMarker, type PlannedOp } from "../ops.js";
+import { query } from "../query.js";
+
+const CAP_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+const B64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+/** Deterministic ids — the scope head + a per-member wrap, both replay-stable. */
+export function keyScopeInstanceId(scope: string): string {
+  return `keyscope-${scope}`;
+}
+export function wrappedKeyInstanceId(scope: string, epoch: number, principal: string): string {
+  return `wrapkey-${scope}-${epoch}-${principal}`;
+}
+
+/**
+ * The per-scope key-schedule HEAD. `currentEpoch` is advisory-read here; the gate
+ * (slice 5) enforces that an encrypted-field write's envelope epoch == this value at
+ * the write's position, and that an advance only ever increments it.
+ */
+export const KeyScope = aggregate("KeyScope", {
+  scope: t.string().merge(Lww),
+  currentEpoch: t.int().merge(Lww),
+  openedAt: t.string().merge(Lww),
+});
+export type KeyScopeHandle = typeof KeyScope;
+
+/**
+ * ONE wrapped epoch key, addressed to ONE member. `hpkeEpk` is the ephemeral HPKE
+ * public key, `ct` the sealed epoch secret — both opaque base64 ciphertext, safe
+ * on-chain. `recipientPubKey` pins which device key it was sealed to (audit). Keyed
+ * `wrapkey-<scope>-<epoch>-<principal>` so a re-offer is idempotent.
+ */
+export const WrappedKey = aggregate("WrappedKey", {
+  scope: t.string().merge(Lww),
+  epoch: t.int().merge(Lww),
+  recipientPrincipal: t.string().merge(Lww),
+  recipientPubKey: t.string().merge(Lww), // base64 X25519 the wrap was sealed to
+  hpkeEpk: t.string().merge(Lww), // base64 HPKE ephemeral public key
+  ct: t.string().merge(Lww), // base64 sealed epoch secret
+});
+export type WrappedKeyHandle = typeof WrappedKey;
+
+/** One wrap entry in an `advanceKeyEpoch` payload (computed client-side). */
+const wrapEntrySchema = z.object({
+  recipientPrincipal: z.string().min(1),
+  recipientPubKey: z.string().regex(B64_RE),
+  hpkeEpk: z.string().regex(B64_RE),
+  ct: z.string().regex(B64_RE),
+});
+export type WrapEntry = z.infer<typeof wrapEntrySchema>;
+
+/** Build the plan ops for one wrap — a deterministic-keyed WrappedKey record. */
+function writeWrap(scope: string, epoch: number, w: WrapEntry): PlannedOp[] {
+  const wk = instance(WrappedKey, wrappedKeyInstanceId(scope, epoch, w.recipientPrincipal));
+  // The first op MATERIALIZES this new sibling bucket (`ensures` — a re-offer is idempotent);
+  // the rest mutate it. Without the marker the referential gate rejects a set on an absent id.
+  return [
+    withMarker(set(wk, "scope", scope), "ensures"),
+    set(wk, "epoch", epoch),
+    set(wk, "recipientPrincipal", w.recipientPrincipal),
+    set(wk, "recipientPubKey", w.recipientPubKey),
+    set(wk, "hpkeEpk", w.hpkeEpk),
+    set(wk, "ct", w.ct),
+  ];
+}
+
+/**
+ * `advanceKeyEpoch` — open a new epoch for `scope` and FAN OUT the wraps to every
+ * member, in ONE intent. `epoch` is the new epoch number; `wraps` are the
+ * client-computed per-member seals of the new epoch secret. The plan bumps the
+ * `KeyScope` head and writes each `WrappedKey`. (Slice 5's fan-out gate verifies the
+ * roster == the direct-grant members at this position, that the epoch increments, and
+ * — for a revoke — that the removed member is omitted.)
+ */
+export const advanceKeyEpoch = directive("advanceKeyEpoch")
+  .ensures(KeyScope)
+  .payload(
+    z.object({
+      scope: z.string().regex(CAP_RE),
+      epoch: z.number().int().nonnegative(),
+      openedAt: z.string().min(1), // ISO-8601, caller-stamped (determinism)
+      wraps: z.array(wrapEntrySchema),
+    }),
+  )
+  .plan((p) => {
+    const ks = instance(KeyScope, keyScopeInstanceId(p.scope));
+    const ops: PlannedOp[] = [
+      withMarker(set(ks, "scope", p.scope), "ensures"), // upsert the scope head (first advance creates it)
+      set(ks, "currentEpoch", p.epoch),
+      set(ks, "openedAt", p.openedAt),
+    ];
+    for (const w of p.wraps) ops.push(...writeWrap(p.scope, p.epoch, w));
+    return ops;
+  });
+
+/**
+ * `wrapKey` — write ONE wrap (the single-member handoff). Beyond its use as a primitive,
+ * its `.ensures(WrappedKey)` DECLARATION makes `WrappedKey` an ENSURED type, so the
+ * deterministic-keyed `WrappedKey` sibling rows that `advanceKeyEpoch` fans out are
+ * admitted by the id-mint gate (the sanctioned upsert-by-deterministic-key category).
+ */
+export const wrapKey = directive("wrapKey")
+  .ensures(WrappedKey)
+  .payload(
+    z.object({
+      scope: z.string().regex(CAP_RE),
+      epoch: z.number().int().nonnegative(),
+      recipientPrincipal: z.string().min(1),
+      recipientPubKey: z.string().regex(B64_RE),
+      hpkeEpk: z.string().regex(B64_RE),
+      ct: z.string().regex(B64_RE),
+    }),
+  )
+  .plan((p) => writeWrap(p.scope, p.epoch, p));
+
+/** A reader fetches the wraps addressed to it for a scope+epoch (then unwraps host-side). */
+export const wrappedKeysByRecipient = query("wrappedKeysByRecipient").key("recipientPrincipal").returns(WrappedKey);
+/** The current epoch of a scope (the writer reads it to tag its envelope). */
+export const keyScopeByScope = query("keyScopeByScope").key("scope").returns(KeyScope);

package/src/index.ts

@@ -13,12 +13,14 @@ export {
   aggregate,
   instance,
   forwardRef,
+  requires,
   type AggregateHandle,
   type BoundAggregate,
   type StoredFields,
   type HasManyFields,
   type AggregateInvariantFn,
   type AggregateInvariantVerdict,
+  type ReadVisibility,
 } from "./aggregate.js";
 export {
   t,
@@ -202,6 +204,30 @@ export {
   type Scope,
   type RoleCatalogue,
 } from "./framework/rbac.js";
+// E2E ENCRYPTION (e2e_encryption.md slice 1) — the published per-principal X25519
+// encryption-key registry; the wrap-target lookup the key-handoff fan-out resolves.
+export {
+  EncKey,
+  encKeyInstanceId,
+  writeEncKey,
+  publishEncKey,
+  encKeyByPrincipal,
+  type EncKeyHandle,
+} from "./framework/encryption_identity.js";
+// E2E ENCRYPTION (slice 4) — the group-key events (RFC 9420 sender-keys on the ledger).
+export {
+  KeyScope,
+  WrappedKey,
+  advanceKeyEpoch,
+  wrapKey,
+  wrappedKeysByRecipient,
+  keyScopeByScope,
+  keyScopeInstanceId,
+  wrappedKeyInstanceId,
+  type KeyScopeHandle,
+  type WrappedKeyHandle,
+  type WrapEntry,
+} from "./framework/encryption_scope.js";
 export {
   IMPURE_CAPABILITY_STATUSES,
   IMPURE_CAPABILITY_ENVELOPE,

package/src/manifest.ts

@@ -89,6 +89,22 @@ export interface CanonicalAggregate {
   readonly hasInvariant?: true;
   /** The LAW-DECLARED instance cap; omitted when uncapped (hash-stable). */
   readonly cap?: number;
+  /**
+   * READ VISIBILITY (slice 5.1) — the capability a read TOUCHING this type requires.
+   * PRESENT only when the type is declared `visibility: requires(cap)` (PRIVATE);
+   * OMITTED ENTIRELY for the default `public`, so a public-only domain is
+   * byte-identical in the manifest to before this key existed (golden hashes
+   * UNCHANGED — mirrors `cap`/`hasInvariant`). It IS law (the githolon refuses an
+   * unauthorized read on it), so adding/changing it MOVES the hash.
+   */
+  readonly requiresRead?: string;
+  /**
+   * E2E ENCRYPTION (slice 2) — the STORED field names whose values are `.encrypted()`,
+   * SORTED. PRESENT only when ≥1 field is encrypted; OMITTED otherwise (a plaintext
+   * aggregate is byte-identical). It IS law (the gate enforces the envelope + the scope),
+   * so adding/changing it MOVES the hash. The scope is the aggregate's `requiresRead`.
+   */
+  readonly encryptedFields?: string[];
 }
 
 /** One captured directive contract — NO `plan`/`scopeFrom` behaviour. */
@@ -1003,6 +1019,12 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
       ...(agg.hasInvariant === true ? { hasInvariant: true as const } : {}),
       // The LAW-DECLARED instance cap — hash-bearing (it IS law), omit-when-absent.
       ...(agg.cap !== undefined ? { cap: agg.cap } : {}),
+      // READ VISIBILITY (slice 5.1) — the capability a read of this type requires.
+      // Hash-bearing (it IS law); omit-when-public so all-public domains are byte-stable.
+      ...(agg.visibility !== undefined ? { requiresRead: agg.visibility.requires } : {}),
+      // E2E ENCRYPTION (slice 2) — the encrypted field names. Hash-bearing law;
+      // omit-when-none so plaintext aggregates are byte-stable.
+      ...(agg.encryptedFields !== undefined ? { encryptedFields: [...agg.encryptedFields] } : {}),
     }))
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 
@@ -1026,6 +1048,23 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
     }))
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 
+  // E2E ENCRYPTION — critical #5 (e2e_encryption.md §5), the captured-read seal, COMPILE
+  // half. A captured read (`read()` on the write path) of a PRIVATE query would record its
+  // plaintext result onto the intent as PUBLIC, signed, replay-verified chain data —
+  // bypassing the read gate AND the encryption envelope. Forbid it: a `requires(cap)`
+  // query can NEVER be a captured read. (The one gate re-asserts this at admission/replay
+  // via `cap_for_query`, so a hand-crafted raw intent is refused on every peer too.)
+  const privateTypes = new Set(aggregates.filter((a) => a.requiresRead !== undefined).map((a) => a.id));
+  for (const d of directives) {
+    for (const cr of d.capturedReads ?? []) {
+      if (privateTypes.has(cr.returns)) {
+        throw new Error(
+          `directive '${d.id}': captured read '${cr.queryId}' returns the PRIVATE type '${cr.returns}' — a .reads() of a requires(cap) query would write its plaintext onto the chain as public data. Private data may only leave via the gated read path (query/qbyid), never a captured read.`,
+        );
+      }
+    }
+  }
+
   // exists_ entries are COUNT declarations in the IR — merge them into `counts` so the
   // Rust engine sees them as ordinary counts (the marker lives only in the DSL/codegen
   // layer). Combine mod.counts + normalized exists_ before canonicalizing counts.

package/src/usd.ts

@@ -213,6 +213,37 @@ export interface UsdLayer {
     /** directive id → the SORTED query ids its plan may read. */
     readonly directives: Record<string, string[]>;
   };
+  /**
+   * THE READ-VISIBILITY GATE DECLARATION (slice 5.1, `host_routes_only.md` §5.1).
+   * Present IFF ≥1 aggregate of this layer is declared PRIVATE (`visibility:
+   * requires(cap)`): the law's EXPLICIT opt-in to the githolon gating its own
+   * reads. The one wasm read boundary serves a read touching a private type ONLY to
+   * a principal that effectively holds the required `cap` in this workspace's own
+   * folded role-bindings (the kernel `identity::authz` path). OMITTED for all-public
+   * law (byte-identical hash — the EXACT `nomosReadGate`/`nomosInvariantGate` era
+   * discipline; every pre-slice-5.1 chain serves reads exactly as before, and a
+   * public type is never gated). Keyed by aggregate TYPE name → required capability.
+   */
+  readonly nomosReadVisibility?: {
+    readonly v: 1;
+    /** Aggregate TYPE name → the capability a read touching it requires. SORTED by type name. */
+    readonly aggregates: Record<string, { requires: string }>;
+  };
+  /**
+   * THE ENCRYPTION GATE DECLARATION (e2e_encryption.md slice 2). Present IFF ≥1 field of
+   * this layer is `.encrypted()`: the law's EXPLICIT opt-in to at-rest field ciphertext.
+   * The gate enforces the envelope structure + `scope == the aggregate's read cap` +
+   * `epoch ≤ active` on every encrypted-field write (key-free, every peer); a key-holder
+   * decrypts at read time. OMITTED for plaintext law (byte-identical hash — the EXACT
+   * `nomosReadVisibility` era discipline; every pre-encryption chain replays as before).
+   * `scope` is the aggregate's `requires(cap)`; `delegatable:false` — an encrypted scope
+   * is NON-DELEGATABLE (the adversarial-review fix: a delegated read cap must NOT mint a
+   * key), so the key roster is direct grants only. Keyed by aggregate TYPE, SORTED.
+   */
+  readonly nomosEncryption?: {
+    readonly v: 1;
+    readonly aggregates: Record<string, { scope: string; fields: string[]; delegatable: false }>;
+  };
 }
 
 /** The reserved variant name declaring a set's DEFAULT (USD has a default variant). */
@@ -310,6 +341,19 @@ export function emitUsd(
       for (const k of [...rgQueries.keys()].sort()) readGateQueries[k] = rgQueries.get(k)!;
       const readGateDirectives: Record<string, string[]> = {};
       for (const k of [...rgDirectives.keys()].sort()) readGateDirectives[k] = rgDirectives.get(k)!;
+      // THE READ-VISIBILITY GATE (slice 5.1): every aggregate the manifest carries a
+      // `requiresRead` for, keyed by TYPE name → required cap. SORTED keys
+      // (byte-determinism); omit-when-empty so an all-public layer is byte-identical.
+      const visAggregates: Record<string, { requires: string }> = {};
+      const encAggregates: Record<string, { scope: string; fields: string[]; delegatable: false }> = {};
+      for (const a of [...manifest.aggregates].sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0))) {
+        if (a.requiresRead !== undefined) visAggregates[a.id] = { requires: a.requiresRead };
+        // THE ENCRYPTION GATE (slice 2): an aggregate with encrypted field(s) — its scope
+        // is its read cap (aggregate()/the gate guarantee they coincide). delegatable:false.
+        if (a.encryptedFields !== undefined && a.encryptedFields.length > 0 && a.requiresRead !== undefined) {
+          encAggregates[a.id] = { scope: a.requiresRead, fields: [...a.encryptedFields], delegatable: false };
+        }
+      }
       return {
         path: l.path,
         prims: encodeModuleToPrims(l.path, l.module),
@@ -336,6 +380,12 @@ export function emitUsd(
               },
             }
           : {}),
+        ...(Object.keys(visAggregates).length > 0
+          ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }
+          : {}),
+        ...(Object.keys(encAggregates).length > 0
+          ? { nomosEncryption: { v: 1 as const, aggregates: encAggregates } }
+          : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));

package/src/usd_layers.ts

@@ -348,6 +348,12 @@ export function usdaLayerText(
     ...(layer.nomosReadGate !== undefined
       ? [`        custom string nomos:readGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadGate)))}`]
       : []),
+    ...(layer.nomosReadVisibility !== undefined
+      ? [`        custom string nomos:readVisibilityHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadVisibility)))}`]
+      : []),
+    ...(layer.nomosEncryption !== undefined
+      ? [`        custom string nomos:encryptionHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosEncryption)))}`]
+      : []),
     ``,
     ...body,
     `    }`,
@@ -502,6 +508,36 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         readGate = { v: 1, queries: queriesRec, directives: directivesRec };
       }
     }
+    // The read-visibility gate (slice 5.1): per-aggregate required-read caps merged
+    // later-wins, SORTED keys (matching the composed emission). Omit-when-empty.
+    let readVisibility: UsdLayer["nomosReadVisibility"];
+    {
+      const a = new Map<string, { requires: string }>();
+      for (const l of stack) {
+        if (l.nomosReadVisibility === undefined) continue;
+        for (const [type, spec] of Object.entries(l.nomosReadVisibility.aggregates)) a.set(type, spec);
+      }
+      if (a.size > 0) {
+        const aggregatesRec: Record<string, { requires: string }> = {};
+        for (const k of [...a.keys()].sort()) aggregatesRec[k] = a.get(k)!;
+        readVisibility = { v: 1, aggregates: aggregatesRec };
+      }
+    }
+    // The encryption gate (slice 2): per-aggregate encrypted-field sets merged later-wins,
+    // SORTED keys (matching the composed emission). Omit-when-empty.
+    let encryption: UsdLayer["nomosEncryption"];
+    {
+      const a = new Map<string, { scope: string; fields: string[]; delegatable: false }>();
+      for (const l of stack) {
+        if (l.nomosEncryption === undefined) continue;
+        for (const [type, spec] of Object.entries(l.nomosEncryption.aggregates)) a.set(type, spec);
+      }
+      if (a.size > 0) {
+        const aggregatesRec: Record<string, { scope: string; fields: string[]; delegatable: false }> = {};
+        for (const k of [...a.keys()].sort()) aggregatesRec[k] = a.get(k)!;
+        encryption = { v: 1, aggregates: aggregatesRec };
+      }
+    }
     return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
@@ -510,6 +546,8 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(combineds !== undefined ? { combineds } : {}),
       ...(stableIds !== undefined ? { nomosStableIds: stableIds } : {}),
       ...(readGate !== undefined ? { nomosReadGate: readGate } : {}),
+      ...(readVisibility !== undefined ? { nomosReadVisibility: readVisibility } : {}),
+      ...(encryption !== undefined ? { nomosEncryption: encryption } : {}),
     };
   });
 
@@ -629,6 +667,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const domainByScope = new Map<string, string>();
   const stableIdsByDomain = new Map<string, UsdLayer["nomosStableIds"]>();
   const readGateByDomain = new Map<string, UsdLayer["nomosReadGate"]>();
+  const readVisibilityByDomain = new Map<string, UsdLayer["nomosReadVisibility"]>();
+  const encryptionByDomain = new Map<string, UsdLayer["nomosEncryption"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -642,6 +682,16 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof rgHex === "string") {
         readGateByDomain.set(domain, JSON.parse(unhexUtf8(rgHex)) as UsdLayer["nomosReadGate"]);
       }
+      // THE READ-VISIBILITY GATE (slice 5.1): the hex-carried per-aggregate cap map.
+      const rvHex = p.attrs.get("nomos:readVisibilityHex");
+      if (typeof rvHex === "string") {
+        readVisibilityByDomain.set(domain, JSON.parse(unhexUtf8(rvHex)) as UsdLayer["nomosReadVisibility"]);
+      }
+      // THE ENCRYPTION GATE (slice 2): the hex-carried per-aggregate encrypted-field map.
+      const encHex = p.attrs.get("nomos:encryptionHex");
+      if (typeof encHex === "string") {
+        encryptionByDomain.set(domain, JSON.parse(unhexUtf8(encHex)) as UsdLayer["nomosEncryption"]);
+      }
     }
   }
 
@@ -731,6 +781,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const b = buckets.get(domain)!;
       const sids = stableIdsByDomain.get(domain);
       const rg = readGateByDomain.get(domain);
+      const rv = readVisibilityByDomain.get(domain);
+      const enc = encryptionByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -739,6 +791,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(b.combineds.length > 0 ? { combineds: [...b.combineds].sort(byId) } : {}),
         ...(sids !== undefined ? { nomosStableIds: sids } : {}),
         ...(rg !== undefined ? { nomosReadGate: rg } : {}),
+        ...(rv !== undefined ? { nomosReadVisibility: rv } : {}),
+        ...(enc !== undefined ? { nomosEncryption: enc } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));

package/src/wire_encode.ts

@@ -139,9 +139,12 @@ function encodeKernelFieldOp(op: FieldOp, field: Field | undefined): WireFieldOp
  * to test domain LIFECYCLE.
  *
  * For a KERNEL-BACKED local harness — admission through the real gate, folds,
- * reads, the whole lifecycle on the same engine plane the cloud edge runs — use
- * the CLI: `githolon proof` (the generated proof's offline legs on a local
- * holon) and `githolon dev` (the watch→recompile→law-live→proof inner loop).
+ * reads, minted ids, the whole lifecycle on the same engine plane the cloud
+ * edge runs — use the CLI, NOT this function:
+ *   • `githolon dev --once` — ONE compile → law-live-locally → proof cycle, then
+ *     exit (the CI/smoke lane for lifecycle + id-mint tests — a non-zero exit
+ *     names the jam). `githolon dev` (no flag) is the same on a watch loop.
+ *   • `githolon proof` — the generated proof's offline legs on a local holon.
  * Those mint ids, run the gate, and fold — exactly what this function does NOT.
  */
 export function executeDirectiveToIntent<P>(