@githolon/dsl 0.49.0 → 0.50.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,23 @@ 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>;`,
+        ]
+      : [
+          `  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 +624,106 @@ 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; },`,
+      `  };`,
+      `}`,
+      ``,
+    );
+  }
+
   const anyAutoStamp = modules.some((mod) =>
     (mod.directives as Directive<unknown>[]).some(
       (d) =>
@@ -769,6 +1004,13 @@ 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();
+    };
     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 +1026,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 +1049,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 +1064,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 +1073,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 +1083,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 +1130,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 +1170,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 +1191,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)});`]
         : []),

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";