@githolon/dsl 0.48.1 → 0.50.0

package/src/codegen_dart_client.ts

@@ -36,7 +36,7 @@ import type { DomainModule } from "./codegen_dart.js";
 import { cap, readModelClassName } from "./codegen_dart.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
-import { autoStampFields } from "./codegen_ts.js";
+import { autoStampFields, domainEncryptionMap, type EncDomainMap, type InterfaceAggShape } from "./codegen_ts.js";
 
 const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
 const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
@@ -127,6 +127,24 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   const aggById = new Map<string, AggregateHandle>();
   for (const a of mod.aggregates) aggById.set(a.id, a);
 
+  // THE E2E-SEALING MAP (the sealing client) — non-null iff a field is `.encrypted()`. When null NOTHING
+  // below emits (the generated Dart client is byte-identical to a pre-sealing compile). Same map + sids as
+  // the TS client (one source of truth: `domainEncryptionMap`); requires the baked interface for the sids.
+  const encMap: EncDomainMap | null =
+    opts.interface !== undefined
+      ? domainEncryptionMap(mod, opts.interface as { aggregates?: Record<string, InterfaceAggShape> })
+      : null;
+  const encPresent = encMap !== null;
+  /** The distinct scopes a read of `typeId` must inject keys for (empty ⇒ nothing encrypted on it). */
+  const readScopesFor = (typeId: string): string[] => {
+    const r = encMap?.reads?.[typeId];
+    return r === undefined ? [] : [...new Set(Object.values(r).map((x) => x.scope))].sort();
+  };
+  const keysArg = (typeId: string): string => {
+    const scopes = readScopesFor(typeId);
+    return scopes.length ? `, await _readKeys([${scopes.map((s) => dartStr(s)).join(", ")}])` : "";
+  };
+
   const methods: string[] = [];
 
   // ── directives → typed offer ──
@@ -148,6 +166,34 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const gateDoc = gate !== undefined
       ? `  /// GATED: needs an \`actor\` (the \`${gate.relation}\` relation) — throws MissingOfferAuthority otherwise.`
       : "";
+    // E2E SEALING (the sealing client): a directive with `.encrypted()` payload fields SEALS them via the
+    // bound [keyStore] before dispatch (a missing key throws [EncryptionKeyUnavailable] — never a plaintext
+    // write). One async block covers creates + mutate + gated + stamps; `seal: false` is the escape hatch.
+    if (encMap?.directives?.[d.id] !== undefined) {
+      const isCreates = (d as { marker?: string }).marker === "creates";
+      const retType = isCreates ? "NomosOfferOutcome" : "String";
+      const offerFn = isCreates ? "offerCreates" : "offerDirective";
+      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).`,
+        ...(stamps.length > 0 ? [`  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`] : []),
+        ...(gateDoc ? [gateDoc] : []),
+        `  Future<${retType}> ${method}(${payloadClass} payload, {bool seal = true}) async {`,
+        ...(gateGuard ? [gateGuard] : []),
+        `    final data = payload.toPayloadJson();`,
+        ...(stamps.length > 0
+          ? [
+              `    final now = DateTime.now().toUtc().toIso8601String();`,
+              ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
+            ]
+          : []),
+        `    await _sealPayload(data, ${dartStr(d.id)}, seal);`,
+        `    return bridge.${offerFn}(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
+        `  }`,
+        ``,
+      );
+      continue;
+    }
     if ((d as { marker?: string }).marker === "creates") {
       // LAW-MINTED ID RETURN: a `.creates` plan mints its aggregate id inside the sealed intent (the payload
       // carries none — callers never supply ids). The bridge's offerCreates hands the minted ids back with the
@@ -213,9 +259,9 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const argMap = `{${q.key.map((k) => `${dartStr(k)}: ${dartKeyParam(k)}`).join(", ")}}`;
     const m = safeMethod(lcFirst(camel(q.id)));
     methods.push(
-      `  /// Declared query \`${q.id}\` (indexed probe — routed by the read manifest).`,
+      `  /// Declared query \`${q.id}\` (indexed probe — routed by the read manifest).${readScopesFor(q.returns).length ? " Encrypted field(s) decrypt when the bound [keyStore] holds the scope key; else they stay opaque envelopes." : ""}`,
       `  Future<List<${model}>> ${m}({${params}}) async =>`,
-      `      (await bridge.query(${dartStr(q.id)}, ${argMap})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      `      (await bridge.query(${dartStr(q.id)}, ${argMap}${keysArg(q.returns)})).map((r) => ${rowToModel(model, "r")}).toList();`,
       ``,
       `  /// Reactive \`${q.id}\` — re-emits on every local change (cancel the subscription to stop).`,
       `  Stream<List<${model}>> watch${cap(camel(q.id))}({${params}}) =>`,
@@ -267,9 +313,9 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const lc = lcFirst(camel(agg.id));
     const Cap = cap(camel(agg.id));
     methods.push(
-      `  /// Read one ${agg.id} by aggregate id.`,
+      `  /// Read one ${agg.id} by aggregate id.${readScopesFor(agg.id).length ? " Encrypted field(s) decrypt when the bound [keyStore] holds the scope key." : ""}`,
       `  Future<List<${model}>> ${safeMethod(`${lc}ById`)}(String id) async =>`,
-      `      (await bridge.queryById(id)).map((r) => ${rowToModel(model, "r")}).toList();`,
+      `      (await bridge.queryById(id${keysArg(agg.id)})).map((r) => ${rowToModel(model, "r")}).toList();`,
       ``,
       `  /// Watch one ${agg.id} by aggregate id (local reactive read).`,
       `  Stream<List<${model}>> watch${Cap}ById(String id) =>`,
@@ -277,7 +323,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       ``,
       `  /// Every ${agg.id} (the type-index probe — O(result), not a scan).`,
       `  Future<List<${model}>> ${safeMethod(`list${Cap}s`)}() async =>`,
-      `      (await bridge.query('aggregatesByType', {'__type': ${dartStr(agg.id)}})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      `      (await bridge.query('aggregatesByType', {'__type': ${dartStr(agg.id)}}${keysArg(agg.id)})).map((r) => ${rowToModel(model, "r")}).toList();`,
       ``,
     );
   }
@@ -305,7 +351,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `// client file gives an app the whole typed surface.`,
     `export '${mod.name}.dart';`,
     ...(opts.frameworkImportUri !== undefined ? [`export '${opts.frameworkImportUri}';`] : []),
-    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion;`,
+    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion${encPresent ? ", NomosScopeKey, NomosKeyStore, EncryptionKeyUnavailable, WrappedKeyStore" : ""};`,
     ``,
     `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,
     `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
@@ -344,8 +390,18 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `  /// The verified principal uid every offer is authored as (sealed as \`security.actor\` by the one encoder).`,
     `  /// Null ⇒ open (un-gated) authoring; a gated directive then throws [MissingOfferAuthority].`,
     `  final String? actor;`,
-    `  ${className}(this.bridge, {this.domainHash = ${hashConst}, this.actor});`,
+    ...(encPresent
+      ? [
+          ``,
+          `  /// THE KEY CUSTODY surface (E2E sealing). When set, encrypted directive fields SEAL automatically`,
+          `  /// before dispatch and encrypted read fields DECRYPT automatically; null ⇒ ciphertext passes through`,
+          `  /// unchanged (today's behavior). See [WrappedKeyStore] for the default over the on-chain WrappedKeys.`,
+          `  final NomosKeyStore? keyStore;`,
+        ]
+      : []),
+    `  ${className}(this.bridge, {this.domainHash = ${hashConst}, this.actor${encPresent ? ", this.keyStore" : ""}});`,
     ``,
+    ...(encPresent ? dartEncClassMembers(encMap!) : []),
     ...(opts.interface !== undefined
       ? [
           `  /// This client's structural interface requirement (#72) as JSON — hand it to the`,
@@ -370,3 +426,42 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ``,
   ].join("\n");
 }
+
+/** The in-class E2E-sealing members: the baked map + the seal/read private helpers. */
+function dartEncClassMembers(encMap: EncDomainMap): string[] {
+  return [
+    `  /// The baked E2E-sealing map (compile-time, from the SAME sids the law was compiled with): which`,
+    `  /// directive payload fields seal → { scope, aggSid, fieldSid }, and which read-model fields decrypt.`,
+    `  static final Map<String, dynamic> encryptionMap = (jsonDecode(${dartRawJson(encMap)}) as Map).cast<String, dynamic>();`,
+    ``,
+    `  /// Seal the mapped encrypted fields of \`data\` in place before dispatch. No keyStore / \`seal == false\``,
+    `  /// ⇒ passthrough (today's behavior); a held key seals; a missing key throws [EncryptionKeyUnavailable].`,
+    `  Future<void> _sealPayload(Map<String, dynamic> data, String directiveId, bool seal) async {`,
+    `    if (!seal || keyStore == null) return;`,
+    `    final fields = (encryptionMap['directives'] as Map)[directiveId] as Map?;`,
+    `    if (fields == null) return;`,
+    `    for (final entry in fields.entries) {`,
+    `      final field = entry.key as String;`,
+    `      final m = entry.value as Map;`,
+    `      if (data[field] == null) continue;`,
+    `      final scope = m['scope'] as String;`,
+    `      final sk = await keyStore!.scopeKey(scope);`,
+    `      if (sk == null) throw EncryptionKeyUnavailable(scope, field);`,
+    `      data[field] = await bridge.cryptoSealField(`,
+    `        scopeKey: sk.key, scope: scope, epoch: sk.epoch,`,
+    `        aggSid: m['aggSid'] as String, fieldSid: m['fieldSid'] as String,`,
+    `        plaintext: data[field].toString(),`,
+    `      );`,
+    `    }`,
+    `  }`,
+    ``,
+    `  /// The read keys to inject for \`scopes\`, or null when there is nothing to inject (no keyStore / no`,
+    `  /// held keys) — the read then behaves exactly as today (encrypted fields stay opaque envelopes).`,
+    `  Future<List<NomosScopeKey>?> _readKeys(List<String> scopes) async {`,
+    `    if (keyStore == null || scopes.isEmpty) return null;`,
+    `    final keys = await keyStore!.readKeys(scopes);`,
+    `    return keys.isEmpty ? null : keys;`,
+    `  }`,
+    ``,
+  ];
+}

package/src/codegen_proof.ts

@@ -659,6 +659,33 @@ function probePlanOps(
   return { ops, synth, probePayload };
 }
 
+/**
+ * Compile-side plan-probe of a directive's SECONDARY deterministic ENSURES — the aggregate TYPES its
+ * plan introduces via `ensure(Agg, "det:id")` (an `ensures`-marked op at a dev-chosen deterministic id),
+ * beyond whatever its PRIMARY referential marker declares. This is the discovery half of the "secondary
+ * create auto-declare" DX (`secondary_ensure.ts`): the kernel's id-mint gate admits an Ensure-introduced
+ * typed id ONLY when the certified manifest declares `Ensure → Type`, so `composeDomainModule` sanctions
+ * each discovered type with a no-op ensures directive.
+ *
+ * BEST-EFFORT (the reliability caveat): runs the plan ONCE under a synthesized payload + the deterministic
+ * probe ports. A plan that can't be probed (unsynthesizable payload / throws) or that ensures CONDITIONALLY
+ * on a payload shape the synthesis didn't hit yields fewer (or no) types — in which case the runtime
+ * id-mint gate still refuses the un-sanctioned ensure exactly as before (NO regression, NO weakening: the
+ * courtesy simply didn't fire). Returns the sorted set of ensured types (INCLUDING the directive's own
+ * primary target if it marks `ensures`; the caller subtracts the domain-wide declared set).
+ */
+export function probeEnsuredTypes(dir: Directive<unknown>, where: string): string[] {
+  const probed = probePlanOps(dir, where);
+  if (probed === undefined) return [];
+  const out = new Set<string>();
+  for (const o of probed.ops) {
+    if ((o as { marker?: string }).marker !== "ensures") continue;
+    const ty = o.aggregateType;
+    if (typeof ty === "string" && ty.length > 0) out.add(ty);
+  }
+  return [...out].sort();
+}
+
 /** The `status` of a `subjects` setEntry leaf (`writeTuple`/`removeTuple` lowers a JSON `{status, …}` leaf).
  *  `"active"` = a POSITIVE grant; `"revoked"` = a REVOKE. `undefined` ⇒ not a parseable subject leaf. */
 function subjectLeafStatus(op: FieldOp): string | undefined {
@@ -1357,7 +1384,7 @@ export interface ChildBirthParentSetup {
 /** A stub `nomos` global (mint + sha256) so a `.births()` plan that mints / hashes a child name runs to
  *  completion at codegen. The hash is a deterministic STUB (the codegen never needs the real digest — the
  *  recipe's workspace is read at RUNTIME from the offer's `born`); mint mirrors `harvestPrincipalFlows`. */
-function withBirthProbeGlobals<T>(run: () => T): T {
+export function withBirthProbeGlobals<T>(run: () => T): T {
   const g = globalThis as unknown as { nomos?: { mint?: (t: string) => string; sha256?: (s: string) => string; read?: unknown } };
   const had = "nomos" in g;
   const prior = g.nomos;

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)});`]
         : []),