@githolon/dsl 0.49.0 → 0.51.0

package/src/codegen_ts.ts

@@ -72,6 +72,118 @@ export const interfaceConstName = (packageName: string): string => `${upperSnake
 /** `tool-library` → `TOOL_LIBRARY_COMPAT` — the baked client/law compat manifest (§5). */
 export const compatConstName = (packageName: string): string => `${upperSnake(packageName)}_COMPAT`;
 
+/** `tool-library` → `TOOL_LIBRARY_ENCRYPTION` — the baked E2E-sealing map (the sealing client). */
+export const encryptionConstName = (packageName: string): string => `${upperSnake(packageName)}_ENCRYPTION`;
+
+// ── E2E SEALING MAP (the sealing client) ──────────────────────────────────────────
+// The compiler already knows everything the sealing plumbing needs: which fields are
+// `.encrypted()` (`agg.encryptedFields`), their read/encryption SCOPE (`agg.visibility.requires`,
+// the `requires(cap)` that IS the scope), and their #58 STABLE SIDS (via the baked structural
+// interface — sid-keyed, carrying each field's label). This map is baked into the generated
+// client like the domainHash — never fetched at runtime — so a sealing write is byte-identical
+// to a hand-plumbed one. ADDITIVE: a domain with no encrypted field contributes NOTHING (the
+// map is null and no const/helper/keyStore surface is emitted — byte-identical generated client).
+
+/** One encrypted field's seal coordinates: the scope cap + the stable (agg,field) sids. */
+export interface EncFieldMap {
+  readonly scope: string;
+  readonly aggSid: string;
+  readonly fieldSid: string;
+}
+/** Per-domain: which directive payload fields seal, and which read-model fields decrypt. */
+export interface EncDomainMap {
+  /** directiveId → (payload field → seal coordinates). */
+  readonly directives: Record<string, Record<string, EncFieldMap>>;
+  /** aggregate type id → (field → { scope }) — the fields a read decrypts under `scope`. */
+  readonly reads: Record<string, Record<string, { scope: string }>>;
+}
+
+/** The sid-keyed read shape of ONE domain's interface (mirrors `shape_compat.ts` DomainInterface). */
+export interface InterfaceAggShape {
+  readonly sid: string;
+  readonly label: string;
+  readonly fields: Record<string, { kind: string; label: string }>;
+}
+
+/** Resolve (aggLabel, fieldLabel) → their STABLE SIDS from the baked domain interface. The seal binds
+ *  the ciphertext to these sids so a rename of the type/field never breaks decryption (#58). */
+function resolveSids(
+  domainIface: { aggregates?: Record<string, InterfaceAggShape> } | undefined,
+  aggLabel: string,
+  fieldLabel: string,
+): { aggSid: string; fieldSid: string } | undefined {
+  const aggs = domainIface?.aggregates;
+  if (aggs === undefined) return undefined;
+  for (const [aggSid, a] of Object.entries(aggs)) {
+    if (a.label !== aggLabel) continue;
+    for (const [fieldSid, f] of Object.entries(a.fields ?? {})) {
+      if (f.label === fieldLabel) return { aggSid: a.sid ?? aggSid, fieldSid };
+    }
+  }
+  return undefined;
+}
+
+/** Build ONE domain's E2E-sealing map, or `null` when no field is `.encrypted()`. Resolves sids from the
+ *  domain's baked interface — REQUIRES it when any field is encrypted (an encrypted aggregate is always
+ *  private, so the interface is present). Shared by the TS + Dart client generators (one source of truth). */
+export function domainEncryptionMap(
+  mod: DomainModule,
+  domainIface: { aggregates?: Record<string, InterfaceAggShape> } | undefined,
+): EncDomainMap | null {
+  const domain = mod.domain ?? mod.name;
+  const aggs = mod.aggregates as AggregateHandle[];
+  const directives: Record<string, Record<string, EncFieldMap>> = {};
+  const reads: Record<string, Record<string, { scope: string }>> = {};
+  for (const agg of aggs) {
+    const scope = agg.visibility?.requires;
+    const encFields = agg.encryptedFields;
+    if (encFields === undefined || encFields.length === 0 || scope === undefined) continue;
+    const r: Record<string, { scope: string }> = {};
+    for (const f of encFields) r[f] = { scope };
+    reads[agg.id] = r;
+  }
+  for (const d of mod.directives as Directive<unknown>[]) {
+    const aggId = (d as { aggregateId?: string }).aggregateId;
+    const agg = aggs.find((a) => a.id === aggId);
+    const scope = agg?.visibility?.requires;
+    const encFields = agg?.encryptedFields;
+    if (agg === undefined || encFields === undefined || encFields.length === 0 || scope === undefined) continue;
+    const schema = (d as { payloadSchema?: unknown }).payloadSchema;
+    if (typeof schema !== "object" || schema === null || zodKind(schema as z.ZodTypeAny) !== "object") continue;
+    const shapeKeys = new Set(Object.keys(zodObjectShape(schema as z.ZodTypeAny)));
+    const fmap: Record<string, EncFieldMap> = {};
+    for (const f of encFields) {
+      if (!shapeKeys.has(f)) continue; // the directive doesn't carry this field on its payload
+      const sids = resolveSids(domainIface, agg.id, f);
+      if (sids === undefined) {
+        throw new Error(
+          `codegen: cannot resolve stable ids for encrypted field ${agg.id}.${f} in domain '${domain}' — ` +
+            `the package structural interface (with stable ids) is required to bake the E2E-sealing map`,
+        );
+      }
+      fmap[f] = { scope, aggSid: sids.aggSid, fieldSid: sids.fieldSid };
+    }
+    if (Object.keys(fmap).length > 0) directives[d.id] = fmap;
+  }
+  return Object.keys(directives).length > 0 || Object.keys(reads).length > 0 ? { directives, reads } : null;
+}
+
+/** Build the package's E2E-sealing map keyed by domain, or `null` when no field is `.encrypted()`
+ *  anywhere (the additive-zero case). */
+function buildEncryptionMap(
+  modules: readonly DomainModule[],
+  ifaceByDomain: Record<string, { aggregates?: Record<string, InterfaceAggShape> }> | undefined,
+): Record<string, EncDomainMap> | null {
+  const out: Record<string, EncDomainMap> = {};
+  let any = false;
+  for (const mod of modules) {
+    const domain = mod.domain ?? mod.name;
+    const m = domainEncryptionMap(mod, ifaceByDomain?.[domain]);
+    if (m !== null) { out[domain] = m; any = true; }
+  }
+  return any ? out : null;
+}
+
 // ── zod → TS (the same `_def ?? def` convention as codegen_dart's walker) ─────────
 // The walkers are exported: codegen_proof.ts synthesizes SAMPLE payloads from the
 // same zod shapes this file derives TYPES from — one introspection, two emitters.
@@ -405,6 +517,14 @@ function anyPackedTaxonomy(modules: readonly DomainModule[]): boolean {
 
 export function generateTsClient(modules: readonly DomainModule[], opts: TsClientOptions): string {
   const hashConst = tsHashConstName(opts.packageName);
+  // THE E2E-SEALING MAP (the sealing client): non-null iff any field is `.encrypted()`. When null,
+  // NOTHING below emits — the generated client is byte-identical to a pre-sealing compile.
+  const encMap = buildEncryptionMap(
+    modules,
+    opts.interface as Record<string, { aggregates?: Record<string, InterfaceAggShape> }> | undefined,
+  );
+  const encPresent = encMap !== null;
+  const encConst = encryptionConstName(opts.packageName);
   const out: string[] = [];
   out.push(
     `// AUTO-GENERATED by nomos-compile — typed TS client for package "${opts.packageName}".`,
@@ -450,8 +570,27 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean }): Promise<string>;`,
     `  /** Opaque-bytes offer — retained for carriers that already hold an encoded envelope (back-compat). */`,
     `  offer(intentBytes: string | Uint8Array): Promise<string>;`,
-    `  query(queryId: string, params?: Record<string, unknown>): Promise<unknown>;`,
-    `  queryById(aggregateId: string): Promise<unknown>;`,
+    ...(encPresent
+      ? [
+          `  /** \`keys\` (E2E sealing): the reader's held scope keys, injected so encrypted fields decrypt;`,
+          `   *  absent ⇒ encrypted fields stay opaque envelopes (today's behavior). */`,
+          `  query(queryId: string, params?: Record<string, unknown>, keys?: readonly NomosScopeKey[]): Promise<unknown>;`,
+          `  queryById(aggregateId: string, keys?: readonly NomosScopeKey[]): Promise<unknown>;`,
+          `  /** THE AUTHOR-SIDE SEAL: encrypt a plaintext field value into its on-chain ciphertext envelope`,
+          `   *  (bound to the scope + stable sids). OPTIONAL: structural binding tolerates a pre-sealing holon`,
+          `   *  (the write path then throws with an upgrade hint before any plaintext dispatch). */`,
+          `  cryptoSealField?(args: { scopeKey: string; scope: string; epoch: number; aggSid: string; fieldSid: string; plaintext: string }): Promise<string>;`,
+          `  /** Unwrap an on-chain WrappedKey with this device's secret → the base64 scope key (default KeyStore). */`,
+          `  cryptoUnwrapKey?(args: { secret: string; hpkeEpk: string; ct: string }): Promise<string>;`,
+          `  /** OWNER CEREMONY (slice 2): HPKE-wrap a scope epoch secret TO a member's published X25519 pubkey. */`,
+          `  cryptoWrapKey?(args: { recipientPub: string; scopeKey: string }): Promise<{ hpkeEpk: string; ct: string }>;`,
+          `  /** OWNER CEREMONY (slice 2): mint a fresh X25519 keypair — the source of a fresh epoch secret (32 bytes of its secret). */`,
+          `  cryptoKeygen?(): Promise<{ public: string; secret: string }>;`,
+        ]
+      : [
+          `  query(queryId: string, params?: Record<string, unknown>): Promise<unknown>;`,
+          `  queryById(aggregateId: string): Promise<unknown>;`,
+        ]),
     `  watchById(aggregateId: string, cb: (rows: unknown) => void, opts?: { intervalMs?: number }): () => void;`,
     `  /** Declared-count / declared-sum O(1) reads (maintained by the read engine). */`,
     `  count(countId: string, groupKey?: string): Promise<number>;`,
@@ -489,6 +628,265 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     ``,
   );
 
+  if (encPresent) {
+    out.push(
+      `// ── E2E SEALING (the sealing client) — baked map + KeyStore + seal/read helpers ──`,
+      `// The map below is baked at COMPILE time from the SAME descriptors + stable-id lockfile the law was`,
+      `// compiled with (never fetched). A sealing write is byte-indistinguishable from a hand-plumbed one.`,
+      ``,
+      `/** Per directive: which payload fields seal → their { scope, aggSid, fieldSid }. Per aggregate: which`,
+      ` *  read-model fields are encrypted (+ their scope). Keyed by domain. */`,
+      `export const ${encConst} = ${JSON.stringify(encMap)} as const;`,
+      ``,
+      `/** A held scope key: the base64 symmetric key + the epoch it belongs to (forward-only rotation). */`,
+      `export interface NomosScopeKey { scope: string; epoch: number; key: string }`,
+      ``,
+      `/** The app-supplied KEY CUSTODY surface. Supply one to \`<domain>Client(holon, { keyStore })\` and the`,
+      ` *  generated methods seal writes + decrypt reads automatically. \`wrappedKeyStore\` is the default over`,
+      ` *  the on-chain WrappedKeys; an app may implement this to source keys from a secure enclave. */`,
+      `export interface NomosKeyStore {`,
+      `  /** The CURRENT (highest-epoch) scope key, for SEALING a write. undefined ⇒ EncryptionKeyUnavailable. */`,
+      `  scopeKey(scope: string): Promise<NomosScopeKey | undefined>;`,
+      `  /** EVERY held key for these scopes (all epochs), injected on reads so old ciphertext also decrypts. */`,
+      `  readKeys(scopes: readonly string[]): Promise<NomosScopeKey[]>;`,
+      `}`,
+      ``,
+      `/** Thrown when a write must seal an encrypted field but the KeyStore holds no key for its scope — the`,
+      ` *  write NEVER falls through to a plaintext dispatch (the sid-envelope gate would refuse it anyway). */`,
+      `export class EncryptionKeyUnavailable extends Error {`,
+      `  readonly code = "nomos.crypto.key_unavailable";`,
+      `  readonly recommendedAction = "obtainScopeKey";`,
+      `  constructor(readonly scope: string, readonly field: string) {`,
+      "    super(`cannot seal encrypted field \"${field}\": no scope key held for \"${scope}\" — obtain it (be granted the cap + wrapped the scope epoch) before writing`);",
+      `    this.name = "EncryptionKeyUnavailable";`,
+      `  }`,
+      `}`,
+      ``,
+      `/** Seal the mapped encrypted fields of a payload before dispatch. No keyStore / \`seal:false\` ⇒ passthrough`,
+      ` *  (today's behavior). A held key seals; a missing key throws EncryptionKeyUnavailable (never plaintext). */`,
+      `const _sealFields = async (`,
+      `  holon: NomosHolon,`,
+      `  keyStore: NomosKeyStore | undefined,`,
+      `  fieldMap: Record<string, { scope: string; aggSid: string; fieldSid: string }>,`,
+      `  payload: Record<string, unknown>,`,
+      `  seal: boolean,`,
+      `): Promise<Record<string, unknown>> => {`,
+      `  if (seal === false || keyStore == null) return payload;`,
+      `  let out: Record<string, unknown> | undefined;`,
+      `  for (const field of Object.keys(fieldMap)) {`,
+      `    const v = payload[field];`,
+      `    if (v === undefined || v === null) continue;`,
+      `    const m = fieldMap[field]!;`,
+      `    const sk = await keyStore.scopeKey(m.scope);`,
+      `    if (!sk) throw new EncryptionKeyUnavailable(m.scope, field);`,
+      `    if (!holon.cryptoSealField) throw new Error("this holon predates E2E sealing — upgrade @githolon/client");`,
+      `    const envelope = await holon.cryptoSealField({ scopeKey: sk.key, scope: m.scope, epoch: sk.epoch, aggSid: m.aggSid, fieldSid: m.fieldSid, plaintext: String(v) });`,
+      `    (out ??= { ...payload })[field] = envelope;`,
+      `  }`,
+      `  return out ?? payload;`,
+      `};`,
+      ``,
+      `/** The read keys to inject for the given scopes, or undefined when there is nothing to inject`,
+      ` *  (no keyStore, or no held keys) — the read then behaves exactly as today (opaque envelopes). */`,
+      `const _readKeys = async (keyStore: NomosKeyStore | undefined, scopes: readonly string[]): Promise<NomosScopeKey[] | undefined> => {`,
+      `  if (keyStore == null || scopes.length === 0) return undefined;`,
+      `  const keys = await keyStore.readKeys(scopes);`,
+      `  return keys.length ? keys : undefined;`,
+      `};`,
+      ``,
+      `/** THE DEFAULT KeyStore — unwraps this principal's on-chain WrappedKeys with its device secret, caching`,
+      ` *  per scope. Mirror of the documented reader handshake (e2e_encryption.md): the secret stays client-side,`,
+      ` *  the operator stays blind. Key custody (where \`deviceSecret\` lives) remains the app's concern. */`,
+      `export function wrappedKeyStore(opts: { holon: NomosHolon; principal: string; deviceSecret: string }): NomosKeyStore {`,
+      `  const { holon, principal, deviceSecret } = opts;`,
+      `  const cache = new Map<string, Promise<NomosScopeKey[]>>();`,
+      `  const loadScope = (scope: string): Promise<NomosScopeKey[]> => {`,
+      `    let p = cache.get(scope);`,
+      `    if (p !== undefined) return p;`,
+      `    p = (async () => {`,
+      `      const rows = (await holon.query("wrappedKeysByRecipient", { recipientPrincipal: principal })) as { data?: Record<string, unknown> }[];`,
+      `      const held: NomosScopeKey[] = [];`,
+      `      for (const row of rows ?? []) {`,
+      `        const d = (row.data ?? row) as Record<string, unknown>;`,
+      `        if (String(d.scope) !== scope) continue;`,
+      `        if (!holon.cryptoUnwrapKey) throw new Error("this holon predates E2E unwrap — upgrade @githolon/client");`,
+      `        const key = await holon.cryptoUnwrapKey({ secret: deviceSecret, hpkeEpk: String(d.hpkeEpk), ct: String(d.ct) });`,
+      `        held.push({ scope, epoch: Number(d.epoch) || 0, key });`,
+      `      }`,
+      `      held.sort((a, b) => b.epoch - a.epoch);`,
+      `      return held;`,
+      `    })();`,
+      `    cache.set(scope, p);`,
+      `    return p;`,
+      `  };`,
+      `  return {`,
+      `    async scopeKey(scope) { return (await loadScope(scope))[0]; },`,
+      `    async readKeys(scopes) { const all: NomosScopeKey[] = []; for (const s of scopes) all.push(...(await loadScope(s))); return all; },`,
+      `  };`,
+      `}`,
+      ``,
+      `// ── E2E OWNER CEREMONY (the sealing client, slice 2) — grantAndWrap / revokeAndRotate / rotate ──`,
+      `// The owner-side twin of the KeyStore. It composes the framework key-epoch fan-out (\`advanceKeyEpoch\`,`,
+      `// dispatched by its REAL id — never an \`export const alias\`) with the domain's own grant/revoke`,
+      `// directive, resolving the roster + each member's wrap-target pubkey FROM THE CHAIN, so the`,
+      `// operator-blind handshake (grant → advance epoch → wrap to every member) is ONE call.`,
+      ``,
+      `/** Base64 ⇄ bytes that work in both the browser (atob/btoa) and Node (Buffer) — the generated`,
+      ` *  client is zero-import, so it derives a fresh 32-byte epoch secret from a keygen without a lib. */`,
+      `const _b64ToBytes = (b64: string): Uint8Array => {`,
+      `  if (typeof atob === "function") { const s = atob(b64); const u = new Uint8Array(s.length); for (let i = 0; i < s.length; i++) u[i] = s.charCodeAt(i); return u; }`,
+      `  return Uint8Array.from((globalThis as unknown as { Buffer: { from(s: string, e: string): Uint8Array } }).Buffer.from(b64, "base64"));`,
+      `};`,
+      `const _bytesToB64 = (u: Uint8Array): string => {`,
+      `  if (typeof btoa === "function") { let s = ""; for (const b of u) s += String.fromCharCode(b); return btoa(s); }`,
+      `  return (globalThis as unknown as { Buffer: { from(u: Uint8Array): { toString(e: string): string } } }).Buffer.from(u).toString("base64");`,
+      `};`,
+      ``,
+      `/** Thrown by the owner ceremony when a roster member has NO wrap-target key (no publishEncKey on chain,`,
+      ` *  no prior wrap, no supplied override) — the ceremony NEVER wraps to a default (fail-closed; a member`,
+      ` *  with no key is "not yet a member", per e2e_encryption.md's FOOTGUNS). */`,
+      `export class EncryptionMemberKeyMissing extends Error {`,
+      `  readonly code = "nomos.crypto.member_key_missing";`,
+      `  readonly recommendedAction = "publishEncKey";`,
+      `  constructor(readonly principal: string, readonly scope: string) {`,
+      "    super(`cannot wrap the \"${scope}\" scope key to member \"${principal}\": no encryption public key on chain (publishEncKey) and none supplied — a keyless member is not yet wrappable (fail-closed)`);",
+      `    this.name = "EncryptionMemberKeyMissing";`,
+      `  }`,
+      `}`,
+      ``,
+      `/** Thrown when the resolved roster != the caller's declared \`expectRoster\` BEFORE dispatch — pre-firing`,
+      ` *  the kernel fan-out gate (wrap set == roster) so a rotation against a stale roster view never spends`,
+      ` *  an epoch on the chain. */`,
+      `export class EncryptionRosterMismatch extends Error {`,
+      `  readonly code = "nomos.crypto.roster_mismatch";`,
+      `  readonly recommendedAction = "reconcileRoster";`,
+      `  constructor(readonly scope: string, readonly missing: readonly string[], readonly extra: readonly string[]) {`,
+      "    super(`roster for \"${scope}\" != expected (the fan-out gate would refuse): missing [${missing.join(\", \")}], unexpected [${extra.join(\", \")}]`);",
+      `    this.name = "EncryptionRosterMismatch";`,
+      `  }`,
+      `}`,
+      ``,
+      `/** The owner-ceremony surface — attached as \`<domain>Client(holon, { actor }).encryption\`. All three`,
+      ` *  verbs open a FRESH epoch (a fresh 32-byte secret) and fan the wraps to the resolved roster; the`,
+      ` *  membership change (if any) is the domain grant/revoke dispatched first, in the same call. */`,
+      `export interface NomosEncryption {`,
+      `  /** The encryption scopes this domain defines (each a \`requires(cap)\`). */`,
+      `  readonly scopes: readonly string[];`,
+      `  /** The CURRENT roster of a scope (active direct-grant members, principal-form). Defaults to the sole scope. */`,
+      `  roster(scope?: string): Promise<string[]>;`,
+      `  /** Grant a newcomer + open a fresh epoch wrapping the key to EVERY member (incl. the newcomer). Dispatches`,
+      `   *  \`grantDirective(grantPayload)\` first, then \`advanceKeyEpoch\`. \`publicKey\` is the newcomer's X25519 key`,
+      `   *  (else resolved from an on-chain publishEncKey). Existing members' keys come from their prior wraps. */`,
+      `  grantAndWrap(args: { principal: string; publicKey?: string; scope?: string; grantDirective: string; grantPayload: Record<string, unknown>; scopeKey?: string; memberKeys?: Record<string, string>; expectRoster?: readonly string[]; openedAt?: string }): Promise<{ head: string; epoch: number; roster: string[] }>;`,
+      `  /** Revoke a member + open a fresh epoch re-wrapping the key to the SURVIVORS only. FORWARD-ONLY: the removed`,
+      `   *  member gets no NEW reads, but old ciphertext it already holds a key for stays readable (not re-encrypted). */`,
+      `  revokeAndRotate(args: { principal: string; scope?: string; revokeDirective: string; revokePayload: Record<string, unknown>; scopeKey?: string; memberKeys?: Record<string, string>; expectRoster?: readonly string[]; openedAt?: string }): Promise<{ head: string; epoch: number; roster: string[] }>;`,
+      `  /** Routine rotation — open a fresh epoch re-wrapping the key to the CURRENT roster (no membership change). */`,
+      `  rotate(args?: { scope?: string; scopeKey?: string; memberKeys?: Record<string, string>; expectRoster?: readonly string[]; openedAt?: string }): Promise<{ head: string; epoch: number; roster: string[] }>;`,
+      `}`,
+      ``,
+      `/** Build the owner ceremony for one domain (thin: all mechanism lives here; the factory just wires it). */`,
+      `function _ownerEncryption(holon: NomosHolon, cfg: { domain: string; domainHash?: string; actor?: string; scopes: readonly string[] }): NomosEncryption {`,
+      `  const { domain, domainHash, actor, scopes } = cfg;`,
+      `  const defScope = (scope?: string): string => {`,
+      `    if (scope) return scope;`,
+      `    if (scopes.length === 1) return scopes[0]!;`,
+      "    throw new Error(`this domain defines ${scopes.length} encryption scopes [${scopes.join(\", \")}] — pass { scope } to pick one`);",
+      `  };`,
+      `  // A BARE scope IS \`workspace:self#<relation>\` (the era rule); a per-record scope is \`<type>:<id>#<relation>\`.`,
+      `  const parseScope = (scope: string): { object: string; relation: string } => {`,
+      `    const h = scope.indexOf("#");`,
+      `    return h < 0 ? { object: "workspace:self", relation: scope } : { object: scope.slice(0, h), relation: scope.slice(h + 1) };`,
+      `  };`,
+      `  const readRoster = async (scope: string): Promise<string[]> => {`,
+      `    const { object, relation } = parseScope(scope);`,
+      "    const rows = (await holon.queryById(`reltuple-${object}-${relation}`)) as { data?: { subjects?: Record<string, unknown> } }[] | undefined;",
+      `    const subjects = rows?.[0]?.data?.subjects ?? {};`,
+      `    const out: string[] = [];`,
+      `    for (const [subj, leafRaw] of Object.entries(subjects)) {`,
+      `      let leaf: { status?: string };`,
+      `      try { leaf = typeof leafRaw === "string" ? JSON.parse(leafRaw) : (leafRaw as { status?: string }); } catch { leaf = {}; }`,
+      `      if (leaf?.status !== undefined && leaf.status !== "active") continue;`,
+      `      out.push(subj.startsWith("user:") ? subj.slice(5) : subj);`,
+      `    }`,
+      `    return out.sort();`,
+      `  };`,
+      `  const currentEpoch = async (scope: string): Promise<number> => {`,
+      "    const rows = (await holon.queryById(`keyscope-${scope}`)) as { data?: { currentEpoch?: number } }[] | undefined;",
+      `    const e = rows?.[0]?.data?.currentEpoch;`,
+      `    return typeof e === "number" ? e : -1;`,
+      `  };`,
+      `  const freshScopeKey = async (): Promise<string> => {`,
+      `    if (!holon.cryptoKeygen) throw new Error("this holon predates E2E keygen — upgrade @githolon/client");`,
+      `    const kp = await holon.cryptoKeygen();`,
+      `    return _bytesToB64(_b64ToBytes(kp.secret).subarray(0, 32)); // the 32-byte epoch secret; NEVER lands on chain`,
+      `  };`,
+      `  const memberPubKey = async (principal: string, hints: { publicKey?: string; principal?: string; memberKeys?: Record<string, string> }): Promise<string | undefined> => {`,
+      `    if (hints.memberKeys?.[principal]) return hints.memberKeys[principal];`,
+      `    if (hints.principal === principal && hints.publicKey) return hints.publicKey;`,
+      `    // Published enc key (encKeyByPrincipal) — present only when the domain composed the registry; tolerate absence.`,
+      `    try {`,
+      `      const reg = (await holon.query("encKeyByPrincipal", { principal })) as { data?: { encPublicKey?: string } }[] | undefined;`,
+      `      const pub = Array.isArray(reg) ? reg[0]?.data?.encPublicKey : undefined;`,
+      `      if (pub) return pub;`,
+      `    } catch { /* not routed — fall through to the prior-wrap lane */ }`,
+      `    // The member's most-recent WrappedKey pins the pubkey it was last sealed to (rotation needs no re-publish).`,
+      `    try {`,
+      `      const wraps = (await holon.query("wrappedKeysByRecipient", { recipientPrincipal: principal })) as { data?: { epoch?: number; recipientPubKey?: string } }[] | undefined;`,
+      `      let best: { epoch: number; pub: string } | undefined;`,
+      `      for (const w of Array.isArray(wraps) ? wraps : []) { const d = w.data ?? {}; if (d.recipientPubKey && (best === undefined || (d.epoch ?? 0) >= best.epoch)) best = { epoch: d.epoch ?? 0, pub: d.recipientPubKey }; }`,
+      `      if (best) return best.pub;`,
+      `    } catch { /* not routed */ }`,
+      `    return undefined;`,
+      `  };`,
+      `  const advance = async (scope: string, opts: { add?: { principal: string; publicKey?: string }; remove?: readonly string[]; scopeKey?: string; memberKeys?: Record<string, string>; expectRoster?: readonly string[]; openedAt?: string }): Promise<{ head: string; epoch: number; roster: string[] }> => {`,
+      `    const roster = new Set(await readRoster(scope));`,
+      `    if (opts.add) roster.add(opts.add.principal);`,
+      `    for (const p of opts.remove ?? []) roster.delete(p);`,
+      `    const members = [...roster].sort();`,
+      `    // PRE-FIRE the fan-out gate: if the caller declared the roster it means to wrap, refuse on drift.`,
+      `    if (opts.expectRoster !== undefined) {`,
+      `      const want = new Set(opts.expectRoster);`,
+      `      const missing = [...want].filter((m) => !roster.has(m)).sort();`,
+      `      const extra = members.filter((m) => !want.has(m));`,
+      `      if (missing.length || extra.length) throw new EncryptionRosterMismatch(scope, missing, extra);`,
+      `    }`,
+      `    const key = opts.scopeKey ?? await freshScopeKey();`,
+      `    if (!holon.cryptoWrapKey) throw new Error("this holon predates E2E wrap — upgrade @githolon/client");`,
+      `    const wraps: { recipientPrincipal: string; recipientPubKey: string; hpkeEpk: string; ct: string }[] = [];`,
+      `    for (const principal of members) {`,
+      `      const pub = await memberPubKey(principal, { publicKey: opts.add?.publicKey, principal: opts.add?.principal, memberKeys: opts.memberKeys });`,
+      `      if (!pub) throw new EncryptionMemberKeyMissing(principal, scope);`,
+      `      const w = await holon.cryptoWrapKey({ recipientPub: pub, scopeKey: key });`,
+      `      wraps.push({ recipientPrincipal: principal, recipientPubKey: pub, hpkeEpk: w.hpkeEpk, ct: w.ct });`,
+      `    }`,
+      `    const epoch = (await currentEpoch(scope)) + 1; // forward-only: strictly increments`,
+      "    const head = await holon.offerDirective(domain, \"advanceKeyEpoch\", { scope, epoch, openedAt: opts.openedAt ?? new Date().toISOString(), wraps }, { domainHash, actor });",
+      `    return { head, epoch, roster: members };`,
+      `  };`,
+      `  return {`,
+      `    scopes,`,
+      `    roster: (scope) => readRoster(defScope(scope)),`,
+      `    async grantAndWrap(args) {`,
+      `      const scope = defScope(args.scope);`,
+      `      await holon.offerDirective(domain, args.grantDirective, args.grantPayload, { domainHash, actor });`,
+      `      return advance(scope, { add: { principal: args.principal, publicKey: args.publicKey }, scopeKey: args.scopeKey, memberKeys: args.memberKeys, expectRoster: args.expectRoster, openedAt: args.openedAt });`,
+      `    },`,
+      `    async revokeAndRotate(args) {`,
+      `      const scope = defScope(args.scope);`,
+      `      await holon.offerDirective(domain, args.revokeDirective, args.revokePayload, { domainHash, actor });`,
+      `      return advance(scope, { remove: [args.principal], scopeKey: args.scopeKey, memberKeys: args.memberKeys, expectRoster: args.expectRoster, openedAt: args.openedAt });`,
+      `    },`,
+      `    async rotate(args) {`,
+      `      const scope = defScope(args?.scope);`,
+      `      return advance(scope, { scopeKey: args?.scopeKey, memberKeys: args?.memberKeys, expectRoster: args?.expectRoster, openedAt: args?.openedAt });`,
+      `    },`,
+      `  };`,
+      `}`,
+      ``,
+    );
+  }
+
   const anyAutoStamp = modules.some((mod) =>
     (mod.directives as Directive<unknown>[]).some(
       (d) =>
@@ -769,6 +1167,23 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       } catch { /* the compile gate already failed a bad taxonomy loudly */ }
     }
     const methods: string[] = [];
+    // E2E READ INJECTION: the distinct encryption scopes a read of `typeId` must inject keys for (empty
+    // ⇒ nothing encrypted on that type ⇒ the accessor is emitted plain, unchanged). The `_readKeys` helper
+    // returns undefined when no keyStore is bound, so an injected accessor still behaves as today offline.
+    const readScopesFor = (typeId: string): string[] => {
+      const r = encMap?.[domain]?.reads?.[typeId];
+      return r === undefined ? [] : [...new Set(Object.values(r).map((x) => x.scope))].sort();
+    };
+    // The DISTINCT encryption scopes this domain defines (across encrypted reads + sealing directives) —
+    // the set the owner ceremony rotates. Empty ⇒ no `encryption` surface is emitted for this domain.
+    const domScopes: string[] = (() => {
+      const dm = encMap?.[domain];
+      if (dm === undefined) return [];
+      const s = new Set<string>();
+      for (const r of Object.values(dm.reads)) for (const f of Object.values(r)) s.add(f.scope);
+      for (const dir of Object.values(dm.directives)) for (const f of Object.values(dir)) s.add(f.scope);
+      return [...s].sort();
+    })();
     for (const d of dirs) {
       let payloadName = `${cap(d.id)}Payload`;
       if (usedPayloadNames.has(payloadName)) payloadName = `${cap(camel(domain))}${cap(d.id)}Payload`;
@@ -784,6 +1199,16 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       const gateGuard = gate !== undefined
         ? `      if (!actor || !actor.trim()) throw new MissingOfferAuthority(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${JSON.stringify(gate.relation)});\n`
         : "";
+      // E2E SEALING (the sealing client): a directive with `.encrypted()` payload fields seals them
+      // (via the KeyStore) BEFORE dispatch. `wantSeal` forces an async block body + a `callOpts.seal`
+      // escape hatch, and `pv` (the sealed copy) replaces `payload` downstream. Non-encrypted directives
+      // are byte-identical (wantSeal === false ⇒ no prelude, no extra param, plain `payload`).
+      const wantSeal = encMap?.[domain]?.directives?.[d.id] !== undefined;
+      const paramSig = wantSeal ? `payload: ${payloadName}, callOpts?: { seal?: boolean }` : `payload: ${payloadName}`;
+      const sealPrelude = wantSeal
+        ? `      const _sealed = await _sealFields(holon, keyStore, ${encConst}[${JSON.stringify(domain)}].directives[${JSON.stringify(d.id)}] as Record<string, { scope: string; aggSid: string; fieldSid: string }>, payload as Record<string, unknown>, callOpts?.seal !== false) as ${payloadName};`
+        : "";
+      const pv = wantSeal ? "_sealed" : "payload";
       out.push(
         `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema).${stamps.length ? ` Omitted ${stamps.map((s) => `\`${s}\``).join("/")} auto-stamp(s) ISO now() at offer.` : ""}${mint ? ` Omitted \`${mint.field}\` is KERNEL-MINTED at offer (returned on the result).` : ""}${placed.length ? " Omitted `shard` is picked LEAST-LOADED at offer (the routed holon)." : ""} */`,
         `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed)};`,
@@ -797,13 +1222,14 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
               ? `, { tagHex: routeTagOfId(payload.${mint.tagFromIdField}) }`
               : "";
         const body = stamps.length
-          ? `stampNow({ ...payload, ${mint.field} }, ${JSON.stringify(stamps)})`
-          : `{ ...payload, ${mint.field} }`;
+          ? `stampNow({ ...${pv}, ${mint.field} }, ${JSON.stringify(stamps)})`
+          : `{ ...${pv}, ${mint.field} }`;
         methods.push(
           `    /** Author \`${domain}/${d.id}\`: the front-door MINTS \`${mint.field}\` (route-tagged) when omitted`,
           `     *  — ids stay internal plumbing — and returns it with the new local head.${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
-          `    ${d.id}: async (payload: ${payloadName}): Promise<{ head: string; ${mint.field}: string }> => {`,
+          `    ${d.id}: async (${paramSig}): Promise<{ head: string; ${mint.field}: string }> => {`,
           ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
+          ...(sealPrelude ? [sealPrelude] : []),
           `      const ${mint.field} = payload.${mint.field} ?? (await (holon as NomosRoutedHolon).mint(${JSON.stringify(mint.mintType)}${mintOpts}));`,
           `      const head = await holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor });`,
           `      return { head, ${mint.field} };`,
@@ -811,7 +1237,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         );
         continue;
       }
-      const offerPayload = stamps.length ? `stampNow(payload, ${JSON.stringify(stamps)})` : `payload`;
+      const offerPayload = stamps.length ? `stampNow(${pv}, ${JSON.stringify(stamps)})` : pv;
       if (d.marker === "creates") {
         // LAW-MINTED ID RETURN: a `.creates` plan mints its aggregate id inside the sealed intent (the payload
         // carries none). The holon hands the minted ids back on the offer (`returnCreated`), so the create
@@ -820,8 +1246,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         methods.push(
           `    /** Author \`${domain}/${d.id}\`: the LAW mints the ${d.aggregateId ?? "aggregate"} id inside the sealed intent`,
           `     *  and it returns here with the new local head — no id in the payload, no query-after.${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
-          `    ${d.id}: async (payload: ${payloadName}): Promise<{ head: string; id: string }> => {`,
+          `    ${d.id}: async (${paramSig}): Promise<{ head: string; id: string }> => {`,
           ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
+          ...(sealPrelude ? [sealPrelude] : []),
           `      const r = await (holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>);`,
           `      return typeof r === "object" && r !== null ? { head: r.head, id: r.created?.[0]?.id ?? "" } : { head: String(r), id: "" };`,
           `    },`,
@@ -829,7 +1256,19 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         continue;
       }
       const offerCall = `holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor })`;
-      if (gateGuard) {
+      if (wantSeal) {
+        // SEALING directive (optionally also gated): an ASYNC block — seal the encrypted fields via the
+        // bound { keyStore } (+ throw MissingOfferAuthority first if gated) before dispatch.
+        methods.push(
+          `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
+          `     *  Encrypted field(s) are SEALED via the bound { keyStore } before dispatch (pass { seal: false } to skip).${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
+          `    ${d.id}: async (${paramSig}): Promise<string> => {`,
+          ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
+          sealPrelude,
+          `      return ${offerCall};`,
+          `    },`,
+        );
+      } else if (gateGuard) {
         // GATED directive: a block body that throws MissingOfferAuthority when no actor is bound — an
         // actorless gated offer can't be constructed (the war: the gate is structural, not just kernel-side).
         methods.push(
@@ -864,9 +1303,12 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           return `${JSON.stringify(k)}: ${t}`;
         })
         .join("; ");
+      const qScopes = readScopesFor(q.returns);
       methods.push(
-        `    /** Declared query \`${q.id}\` (indexed probe — routed by the read manifest). */`,
-        `    ${lcFirst(camel(q.id))}: (params: { ${params} }) => holon.query(${JSON.stringify(q.id)}, params) as Promise<Row<${q.returns}Data>[]>,`,
+        `    /** Declared query \`${q.id}\` (indexed probe — routed by the read manifest).${qScopes.length ? " Encrypted field(s) decrypt when the bound { keyStore } holds the scope key; else they stay opaque envelopes." : ""} */`,
+        qScopes.length
+          ? `    ${lcFirst(camel(q.id))}: async (params: { ${params} }) => holon.query(${JSON.stringify(q.id)}, params, await _readKeys(keyStore, ${JSON.stringify(qScopes)})) as Promise<Row<${q.returns}Data>[]>,`
+          : `    ${lcFirst(camel(q.id))}: (params: { ${params} }) => holon.query(${JSON.stringify(q.id)}, params) as Promise<Row<${q.returns}Data>[]>,`,
       );
       // THE LOGICAL PAGED ROW SURFACE (sharding §5.3, ruling 2 — slice 4): emitted
       // ONLY for packed-taxonomy domains (taxonomy-free clients stay byte-identical).
@@ -901,11 +1343,16 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       );
     }
     for (const agg of mod.aggregates as AggregateHandle[]) {
+      const aScopes = readScopesFor(agg.id);
       methods.push(
-        `    /** Read one ${agg.id} by aggregate id. */`,
-        `    ${lcFirst(camel(agg.id))}ById: (id: string) => holon.queryById(id) as Promise<Row<${agg.id}Data>[]>,`,
+        `    /** Read one ${agg.id} by aggregate id.${aScopes.length ? " Encrypted field(s) decrypt when the bound { keyStore } holds the scope key." : ""} */`,
+        aScopes.length
+          ? `    ${lcFirst(camel(agg.id))}ById: async (id: string) => holon.queryById(id, await _readKeys(keyStore, ${JSON.stringify(aScopes)})) as Promise<Row<${agg.id}Data>[]>,`
+          : `    ${lcFirst(camel(agg.id))}ById: (id: string) => holon.queryById(id) as Promise<Row<${agg.id}Data>[]>,`,
         `    /** Every ${agg.id} (the type-index probe — O(result), not a scan). */`,
-        `    list${agg.id}s: () => holon.query("aggregatesByType", { __type: ${JSON.stringify(agg.id)} }) as Promise<Row<${agg.id}Data>[]>,`,
+        aScopes.length
+          ? `    list${agg.id}s: async () => holon.query("aggregatesByType", { __type: ${JSON.stringify(agg.id)} }, await _readKeys(keyStore, ${JSON.stringify(aScopes)})) as Promise<Row<${agg.id}Data>[]>,`
+          : `    list${agg.id}s: () => holon.query("aggregatesByType", { __type: ${JSON.stringify(agg.id)} }) as Promise<Row<${agg.id}Data>[]>,`,
         `    /** Watch one ${agg.id} by aggregate id (local reactive read; returns stop()). */`,
         `    watch${agg.id}ById: (id: string, cb: (rows: Row<${agg.id}Data>[]) => void, opts?: { intervalMs?: number }) =>`,
         `      holon.watchById(id, cb as (rows: unknown) => void, opts),`,
@@ -917,9 +1364,10 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       ` *  Pass \`{ actor }\` (the verified principal uid) to author AS that user — every write seals it as`,
       ` *  the captured principal, so the ReBAC \`.requires(...)\` gate + the integrity-dual endorse model`,
       ` *  judge the real author. Omit it for open (un-gated) domains. */`,
-      `export function ${tsClientFactoryName(domain)}(holon: NomosHolon, opts: { domainHash?: string; actor?: string } = {}) {`,
+      `export function ${tsClientFactoryName(domain)}(holon: NomosHolon, opts: { domainHash?: string; actor?: string${encPresent ? "; keyStore?: NomosKeyStore" : ""} } = {}) {`,
       `  const domainHash = opts.domainHash ?? ${hashConst};`,
       `  const actor = opts.actor;`,
+      ...(encPresent ? [`  const keyStore = opts.keyStore;`] : []),
       ...(opts.compat !== undefined
         ? [`  holon.checkCompat?.(${compatConstName(opts.packageName)});`]
         : []),
@@ -929,6 +1377,14 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       ...(opts.interface !== undefined
         ? [`    interface: ${interfaceConstName(opts.packageName)}[${JSON.stringify(domain)}],`]
         : []),
+      // THE OWNER CEREMONY (slice 2): only for a domain that actually defines an encryption scope.
+      ...(domScopes.length > 0
+        ? [
+            `    /** OWNER CEREMONY (slice 2): grantAndWrap / revokeAndRotate / rotate — the operator-blind`,
+            `     *  key-epoch handshake as one call. Bind \`{ actor }\` (the owner) to author the fan-out. */`,
+            `    encryption: _ownerEncryption(holon, { domain: ${JSON.stringify(domain)}, domainHash, actor, scopes: ${JSON.stringify(domScopes)} }) as NomosEncryption,`,
+          ]
+        : []),
       ...methods,
       `  };`,
       `}`,

package/src/compile_package_main.ts

@@ -121,6 +121,7 @@ import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
 import { generateOpenApiFragment, mergeOpenApiFragments } from "./codegen_openapi.js";
 import { domainInterface, type DomainInterface } from "./shape_compat.js";
 import { generateTsProof, proofLegsIndex } from "./codegen_proof.js";
+import { checkDomainModules, formatFindings, hasRefusal } from "./law_check.js";
 import type { NomosCompat } from "./compat_manifest.js";
 
 const DSL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -1816,6 +1817,24 @@ async function main(): Promise<void> {
   for (const w of birthWarnings) {
     console.log(`  ⚠ births   ${w}`);
   }
+  // ── THE AUTHOR-TIME GATE (architecture/author_time_gate.md) — the static twins of the kernel
+  //    gate's refusal vocabulary, unified into ONE report. `githolon check` runs the same pass;
+  //    compile runs it implicitly and REFUSES on any refuse-level finding (a statically-provable
+  //    runtime refusal shipped as law). Warns/notes are printed but never block the compile.
+  const checkFindings = checkDomainModules(domainModules);
+  if (checkFindings.length > 0) {
+    console.log(`  check      ${checkFindings.length} finding(s) (githolon check):`);
+    for (const line of formatFindings(checkFindings)) {
+      const mark = line.includes("REFUSE") ? "✗" : line.includes("WARN") ? "⚠" : "•";
+      console.log(`             ${mark} ${line}`);
+    }
+    if (hasRefusal(checkFindings)) {
+      // Emit the artifacts (already written) but REFUSE the compile: a refuse-level finding is a
+      // statically-provable runtime gate refusal — shipping it as law would fail at first dispatch.
+      console.error(`  ✗ check    REFUSED — fix the refuse-level finding(s) above (or run \`githolon check\`)`);
+      process.exitCode = 1;
+    }
+  }
   if (dartOut !== undefined) {
     const supportText =
       dartSupportImport === "vendored" ? "vendored nomos_client support" : "package nomos_client imports";