@pithy-sh/core 0.11.0 → 0.13.0

package/src/privacy/encryptedColumns.ts

@@ -0,0 +1,185 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { Capability } from "../capability/capability";
+import { ValidationError } from "../error/pithyError";
+import {
+  BlindIndexNormalizerName,
+  encryptedLayout,
+  encryptedSpecOf,
+  hasEncryptedFields,
+  sqlIdentifier,
+} from "./encrypted";
+
+/**
+ * **Every encrypted column a project holds, derived from its schemas** (#390).
+ *
+ * The rotator runs in the secrets manager, which never reads `pithy.config.ts`. So it learns the encrypted columns
+ * the way it learns `rotateEveryDays`: `pithy secrets provision` and `pithy deploy` stamp it with them, and this is
+ * the derivation they stamp. It reads the same markers #132's inventory walks, so a field marked `encrypted()`
+ * tomorrow joins rotation on the next deploy, with no registration step.
+ *
+ * It is also how an app Worker reports its own retirement verdict: the same walk over its own capabilities, so what
+ * the dashboard reads and what the rotator acts on are one derivation.
+ *
+ * ## D1 only, and what that excludes
+ *
+ * A KV `list()` returns keys, never values, so a KV envelope cannot be found by key version: no stale query, no
+ * compare-and-swap and no count. An encrypted field in a KV store is refused at boot (`refuseEncryptedKvStores`), and
+ * any this derivation still meets is reported as **unrotatable** rather than stamped, because nothing can ever prove
+ * those values re-sealed. An unrotatable field blocks retirement.
+ */
+
+/** A SQL identifier as `CamelCasePlugin` writes one: what a stamp may name, so nothing else reaches the rotator's SQL. */
+const SqlName = z.string().regex(/^[a-z_][a-z0-9_]*$/, "A SQL identifier: lowercase letters, digits and underscores.");
+
+/** A JSON path of object keys, the only kind an encrypted field is reached by. */
+const JsonPath = z
+  .string()
+  .regex(/^\$(\.[A-Za-z_$][A-Za-z0-9_$]*)+$/, "A JSON path of object keys, such as `$.phone`.");
+
+/** One encrypted column, as the rotator is stamped with it. */
+export const EncryptedColumn = z
+  .object({
+    name: z.string().describe("The table's declared name: what the AAD binds, never the SQL table name."),
+    path: z.string().describe("The field path the AAD binds: `diagnosis`, or `profile.phone` inside a JSON column."),
+    table: SqlName.describe("The SQL table, as `CamelCasePlugin` writes it."),
+    column: SqlName.describe("The SQL column holding the envelope, or the JSON column the field sits inside."),
+    jsonPath: JsonPath.nullable().describe(
+      "The JSON path of a field inside a JSON column, such as `$.phone`. Null for a field in its own column.",
+    ),
+    primaryKey: SqlName.describe("The SQL column of the table's app-assigned primary key."),
+    binding: z
+      .string()
+      .regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "A binding name.")
+      .describe("The D1 binding the table lives in. Workers that share a binding share the database."),
+    index: z
+      .object({
+        column: SqlName.describe("The SQL column of the field's blind index."),
+        normalizer: BlindIndexNormalizerName.describe("The normalizer the index hashes with."),
+      })
+      .nullable()
+      .describe("The field's blind index, or null for a field with none."),
+  })
+  .describe("One encrypted column the rotator re-seals: where it is, and what its ciphertexts bind.");
+export type EncryptedColumn = z.output<typeof EncryptedColumn>;
+
+/** What the rotator is stamped with: the columns, and what the derivation could not cover. */
+export const EncryptedColumnStamp = z
+  .object({
+    columns: z.array(EncryptedColumn).describe("Every encrypted D1 column the project's schemas declare."),
+    unread: z
+      .array(z.string())
+      .describe(
+        "Every schema source the derivation could not read, such as a Worker whose `pithy.config.ts` would not load. Non-empty means coverage is incomplete, and no version is retired.",
+      ),
+    unrotatable: z
+      .array(z.string())
+      .describe(
+        "Every encrypted field whose storage is not D1, as `<capability>:<container>.<schema>:<path>`. Each blocks retirement.",
+      ),
+  })
+  .describe("The encrypted columns a project holds, derived from its schemas, as the rotator is stamped with them.");
+export type EncryptedColumnStamp = z.output<typeof EncryptedColumnStamp>;
+
+/** A SQL JSON path from object keys. Each key is an identifier, which `encryptedLayout` has already required. */
+function jsonPathOf(segments: readonly string[]): string {
+  return `$.${segments.join(".")}`;
+}
+
+/** Where an encrypted field sits in one KV store's parts, for the unrotatable list. */
+export function kvEncryptedPaths(store: { key: z.ZodType; value: z.ZodType; metadata?: z.ZodType }): string[] {
+  const paths: string[] = [];
+  for (const [part, schema] of [
+    ["key", store.key],
+    ["value", store.value],
+    ["metadata", store.metadata],
+  ] as const) {
+    if (!schema || !hasEncryptedFields(schema)) continue;
+    if (encryptedSpecOf(schema)) {
+      paths.push(part);
+      continue;
+    }
+    const located = encryptedLayout(schema).fields.map((field) => `${part}.${field.path}`);
+    paths.push(...(located.length > 0 ? located : [part]));
+  }
+  return paths;
+}
+
+/**
+ * Derive the encrypted columns of a set of composed capabilities. **Refuses** a D1 table with an encrypted field and
+ * no `encryptedTable()` declaration, and a table whose layout cannot be sealed or rotated, naming the capability and
+ * the table: a column the rotator cannot re-seal is a version that can never be retired.
+ */
+export function deriveEncryptedColumns(capabilities: readonly Capability[]): EncryptedColumnStamp {
+  const columns: EncryptedColumn[] = [];
+  const unrotatable: string[] = [];
+  for (const capability of capabilities) {
+    for (const [container, database] of Object.entries(capability.databases ?? {})) {
+      for (const [table, schema] of Object.entries(database.tables)) {
+        const layout = encryptedLayout(schema as z.ZodType);
+        if (layout.fields.length === 0 && layout.problems.length === 0 && !hasEncryptedFields(schema as z.ZodType))
+          continue;
+        const where = `${capability.name}'s ${container}.${table} table`;
+        if (layout.declaration === null) {
+          throw new ValidationError({
+            message: `${where} holds an encrypted field and declares no table.`,
+            action:
+              "Wrap its schema in encryptedTable(schema, { name, key }): the rotator re-seals by that name and key.",
+          });
+        }
+        if (layout.problems.length > 0) {
+          throw new ValidationError({
+            message: `${where} cannot be rotated as declared. ${layout.problems.join(" ")}`,
+            action: "Fix the schema's encrypted fields and their blindIndex columns.",
+          });
+        }
+        for (const field of layout.fields) {
+          const [head, ...rest] = field.segments as [string, ...string[]];
+          columns.push({
+            name: layout.declaration.name,
+            path: field.path,
+            table: sqlIdentifier(table),
+            column: sqlIdentifier(head),
+            jsonPath: rest.length > 0 ? jsonPathOf(rest) : null,
+            primaryKey: sqlIdentifier(layout.declaration.key),
+            binding: database.binding,
+            index:
+              field.indexField && field.spec.index
+                ? { column: sqlIdentifier(field.indexField), normalizer: field.spec.index }
+                : null,
+          });
+        }
+      }
+    }
+    for (const [container, namespace] of Object.entries(capability.kvNamespaces ?? {})) {
+      for (const [name, store] of Object.entries(namespace.stores)) {
+        for (const path of kvEncryptedPaths(store)) unrotatable.push(`${capability.name}:${container}.${name}:${path}`);
+      }
+    }
+  }
+  return { columns, unread: [], unrotatable };
+}
+
+/**
+ * **Refuse a KV store that holds an encrypted field, at boot** (#390). A KV envelope can never be found by key
+ * version, so it could never be rotated, and encryption that cannot rotate reads as the feature and is not. The
+ * refusal names the schema, the field and D1, and it reads through `.optional()`, `.nullable()`, `.default()` and
+ * nesting, by the wrapper walk the markers use. `@pithy-sh/vector`'s filterable check is the precedent.
+ */
+export function refuseEncryptedKvStores(capabilities: readonly Capability[]): void {
+  for (const capability of capabilities) {
+    for (const [container, namespace] of Object.entries(capability.kvNamespaces ?? {})) {
+      for (const [name, store] of Object.entries(namespace.stores)) {
+        const [path] = kvEncryptedPaths(store);
+        if (path === undefined) continue;
+        throw new ValidationError({
+          message: `${capability.name}'s KV store ${container}.${name} holds an encrypted field at "${path}". Encrypted fields rest in D1.`,
+          action:
+            "Move the field to a D1 table declared with encryptedTable(). A KV entry cannot be found by key version, so it could never be rotated.",
+        });
+      }
+    }
+  }
+}

package/src/privacy/fieldRotation.ts

@@ -0,0 +1,234 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { Capability } from "../capability/capability";
+import { decryptValue, EncryptedEnvelope, type EncryptionConfig, encryptValue } from "../crypto/envelope";
+import { FIELD_KEYS_BINDING, type FieldKeys, liveVersions, resolveFieldKeys } from "../crypto/fieldKeys";
+import { InternalError } from "../error/pithyError";
+import { blindIndexValue } from "./blindIndex";
+import { deriveEncryptedColumns, type EncryptedColumn, type EncryptedColumnStamp } from "./encryptedColumns";
+import { type RetirementVerdict, retirementVerdict, versionsDue } from "./retirement";
+import { fieldContext } from "./sealed";
+
+/**
+ * **Re-sealing an encrypted column in place, and the guard on retiring a version** (#390).
+ *
+ * Rotation is lazy: every write seals under the current version, so a row moves off an old key the next time it is
+ * written, and nothing re-seals between rotations. At each rotation the manager's rotator adds a version, re-seals the
+ * rows still under the version **leaving the window** — and only those — and retires it once the guard reads clean.
+ * The SQL that finds those rows, re-seals one, and counts what is left lives here, beside the derivation it reads, so
+ * the rotator and the app Worker's own retirement report count one way.
+ *
+ * - **A stale row is found by `json_extract`, not by a scan of plaintext.** An envelope carries its `keyVersion` in
+ *   the clear, and a blind index its version prefix, so the count and the batch are one indexed-or-not `WHERE`.
+ * - **Each re-seal is a compare-and-swap** on the version it read: `UPDATE … WHERE <pk> = ? AND json_extract(col,
+ *   '$.keyVersion') = <version read>`. A row the application re-sealed in between is skipped, never overwritten.
+ * - **A field inside a JSON column** is an envelope JSON string at its JSON path, so its version is
+ *   `json_extract(json_extract(col, '$.path'), '$.keyVersion')` and its re-seal is a `json_set` of that path.
+ */
+
+/** Quote a SQL identifier. Every identifier here comes from a validated stamp; this keeps it an identifier. */
+function quote(identifier: string): string {
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+
+/** The SQL that reads the key version of a column's envelope. */
+function envelopeVersion(column: EncryptedColumn): string {
+  const col = quote(column.column);
+  return column.jsonPath === null
+    ? `json_extract(${col}, '$.keyVersion')`
+    : `json_extract(json_extract(${col}, '${column.jsonPath}'), '$.keyVersion')`;
+}
+
+/** The SQL that reads the version prefix of a blind-index value. */
+function indexVersion(indexColumn: string): string {
+  const col = quote(indexColumn);
+  return `CAST(substr(${col}, 1, instr(${col}, ':') - 1) AS INTEGER)`;
+}
+
+/** The SQL predicate a row is stale under: its envelope, or its index, carries one of `count` versions. */
+function stalePredicate(column: EncryptedColumn, count: number): string {
+  const marks = Array.from({ length: count }, () => "?").join(", ");
+  const envelope = `${envelopeVersion(column)} IN (${marks})`;
+  return column.index ? `(${envelope} OR ${indexVersion(column.index.column)} IN (${marks}))` : envelope;
+}
+
+/** The bindings for {@link stalePredicate}. */
+function staleBindings(column: EncryptedColumn, versions: readonly number[]): number[] {
+  return column.index ? [...versions, ...versions] : [...versions];
+}
+
+/** How many rows of one column still hold an envelope or an index under any of `versions`. */
+export async function countStale(
+  d1: D1Database,
+  column: EncryptedColumn,
+  versions: readonly number[],
+): Promise<number> {
+  if (versions.length === 0) return 0;
+  const row = await d1
+    .prepare(`SELECT COUNT(*) AS count FROM ${quote(column.table)} WHERE ${stalePredicate(column, versions.length)}`)
+    .bind(...staleBindings(column, versions))
+    .first<{ count: number }>();
+  return Number(row?.count ?? 0);
+}
+
+/** One stale row, as a batch reads it. */
+interface StaleRow {
+  pk: string;
+  stored: string | null;
+  index: string | null;
+}
+
+/** One batch's outcome. */
+export interface ResealResult {
+  /** Rows re-sealed and re-indexed under the current version. */
+  resealed: number;
+  /** Rows the application re-sealed between the read and the write: left alone. */
+  skipped: number;
+  /** Rows that would not open. Never described: what failed to open is ciphertext. */
+  failed: number;
+}
+
+/** The envelope a stored column holds at the field's path, or `null` where it holds none. */
+function envelopeAt(column: EncryptedColumn, stored: string | null): EncryptedEnvelope | null {
+  if (stored === null) return null;
+  let value: unknown = JSON.parse(stored);
+  if (column.jsonPath !== null) {
+    for (const segment of column.jsonPath.slice(2).split(".")) {
+      if (typeof value !== "object" || value === null) return null;
+      value = (value as Record<string, unknown>)[segment];
+    }
+    if (value === undefined || value === null) return null;
+    value = typeof value === "string" ? JSON.parse(value) : value;
+  }
+  if (value === null) return null;
+  return EncryptedEnvelope.parse(value);
+}
+
+/**
+ * Re-seal one batch of a column's rows still under `version`, onto `config`'s current version, re-indexing each in
+ * the same write. Every write is a compare-and-swap on the version read, so a row the application re-sealed in
+ * between is skipped. A row that will not open is counted and left, never described.
+ */
+export async function resealBatch(
+  d1: D1Database,
+  column: EncryptedColumn,
+  config: EncryptionConfig,
+  version: number,
+  limit: number,
+): Promise<ResealResult> {
+  const result: ResealResult = { resealed: 0, skipped: 0, failed: 0 };
+  const current = Number(config.currentVersion);
+  const index = column.index ? `, ${quote(column.index.column)} AS "index"` : `, NULL AS "index"`;
+  const { results } = await d1
+    .prepare(
+      `SELECT ${quote(column.primaryKey)} AS pk, ${quote(column.column)} AS stored${index} FROM ${quote(column.table)} WHERE ${stalePredicate(column, 1)} LIMIT ?`,
+    )
+    .bind(...staleBindings(column, [version]), limit)
+    .all<StaleRow>();
+  for (const row of results) {
+    let envelope: EncryptedEnvelope | null;
+    let plaintext: string | null = null;
+    let sealed: EncryptedEnvelope | null = null;
+    let indexValue: string | null = row.index;
+    try {
+      envelope = envelopeAt(column, row.stored);
+      const context = fieldContext(column.name, column.path, String(row.pk));
+      if (envelope !== null) {
+        plaintext = await decryptValue(config, context, envelope, { keys: FIELD_KEYS_BINDING });
+        sealed = await encryptValue(config, context, plaintext, { keys: FIELD_KEYS_BINDING });
+      }
+      if (column.index && plaintext !== null) {
+        const value: unknown = JSON.parse(plaintext);
+        if (typeof value !== "string") throw new InternalError({ detail: "an indexed field opened to a non-string" });
+        indexValue = await blindIndexValue(config, current, column.index.normalizer, value);
+      }
+    } catch {
+      // No binding: what failed to open is ciphertext, and its text belongs nowhere.
+      result.failed += 1;
+      continue;
+    }
+    const readVersion = envelope?.keyVersion ?? null;
+    const set: string[] = [];
+    const values: unknown[] = [];
+    if (sealed !== null) {
+      if (column.jsonPath === null) {
+        set.push(`${quote(column.column)} = ?`);
+      } else {
+        set.push(`${quote(column.column)} = json_set(${quote(column.column)}, '${column.jsonPath}', ?)`);
+      }
+      values.push(JSON.stringify(sealed));
+    }
+    if (column.index) {
+      set.push(`${quote(column.index.column)} = ?`);
+      values.push(indexValue);
+    }
+    if (set.length === 0) {
+      result.failed += 1;
+      continue;
+    }
+    const swapped = await d1
+      .prepare(
+        `UPDATE ${quote(column.table)} SET ${set.join(", ")} WHERE ${quote(column.primaryKey)} = ? AND ${envelopeVersion(column)} IS ?${column.index ? ` AND ${quote(column.index.column)} IS ?` : ""}`,
+      )
+      .bind(...values, row.pk, readVersion, ...(column.index ? [row.index] : []))
+      .run();
+    if ((swapped.meta.changes ?? 0) > 0) result.resealed += 1;
+    else result.skipped += 1;
+  }
+  return result;
+}
+
+/** Whether an `env` slot is a D1 binding. */
+function isD1(value: unknown): value is D1Database {
+  return typeof value === "object" && value !== null && typeof (value as { prepare?: unknown }).prepare === "function";
+}
+
+/**
+ * **This Worker's own retirement verdict**, for the manifest's posture block: the guard over its own capabilities'
+ * encrypted columns, read through its own D1 bindings and its own `PITHY_FIELD_KEYS`. The same derivation and the
+ * same counts the rotator acts on, so what the dashboard shows is what the rotator would decide.
+ *
+ * **It never throws.** A derivation that refuses, a key set that will not resolve, a binding the Worker lacks and a
+ * count that fails are each incomplete coverage: the guard could not read something, so it is not clean.
+ */
+export async function readRetirement(
+  env: Record<string, unknown>,
+  capabilities: readonly Capability[],
+): Promise<RetirementVerdict> {
+  let stamp: EncryptedColumnStamp;
+  try {
+    stamp = deriveEncryptedColumns(capabilities);
+  } catch {
+    return retirementVerdict({ versions: [], stale: 0, coverageComplete: false, unrotatable: 0 });
+  }
+  const keys = env[FIELD_KEYS_BINDING];
+  let coverageComplete = true;
+  let versions: number[] = [];
+  let current: number | undefined;
+  if (stamp.columns.length > 0 || keys !== undefined) {
+    try {
+      const config = await resolveFieldKeys(keys as FieldKeys | undefined);
+      versions = liveVersions(config);
+      current = Number(config.currentVersion);
+    } catch {
+      coverageComplete = false;
+    }
+  }
+  const due = current === undefined ? [] : versionsDue(versions, current);
+  let stale = 0;
+  for (const column of stamp.columns) {
+    const d1 = env[column.binding];
+    if (!isD1(d1)) {
+      coverageComplete = false;
+      continue;
+    }
+    try {
+      stale += await countStale(d1, column, due);
+    } catch {
+      coverageComplete = false;
+    }
+  }
+  return retirementVerdict({ versions, current, stale, coverageComplete, unrotatable: stamp.unrotatable.length });
+}

package/src/privacy/inventory.ts

@@ -0,0 +1,147 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+import type { Capability } from "../capability/capability";
+import { BUILT_IN_PRIVACY_CLASSES } from "./classes";
+import { classifyPrivacy, type PrivacyField } from "./classify";
+import { encryptedLayout } from "./encrypted";
+import { kvEncryptedPaths } from "./encryptedColumns";
+import {
+  type EncryptedFieldRecord,
+  PRIVACY_SOURCES,
+  type PrivacyInventory,
+  type PrivacyInventorySchema,
+} from "./report";
+
+/**
+ * **What this Worker holds, derived from the code that is running** (#132).
+ *
+ * The inventory is computed at runtime from the composed capabilities' storage schemas — the Zod objects that
+ * *are* the table definitions, already in the deployed bundle — not stamped at build. A stamped artifact is
+ * skippable (a raw `wrangler deploy` ships the last stamp) and a drifted one is worse than none, because a
+ * dashboard acts on it. A derivation cannot be skipped, cannot be edited out of the adopter's repository, and
+ * cannot disagree with the code: it is the code. Unmark a `phi()` field and that field leaves the report on the
+ * next deploy, with no build step, generated file or person in between.
+ *
+ * ## What it walks
+ *
+ * {@link PRIVACY_SOURCES}, and nothing else: every composed capability's **D1 tables**, and its **KV stores** —
+ * the key segments, the value and the metadata, since a KV entry stores all three. That is where persisted data
+ * lives and what an auditor asks about. R2 objects, Vectorize metadata, Durable Object storage, email templates
+ * and request bodies are not walked, and the report names its sources so that is a stated fact rather than an
+ * implied guarantee.
+ *
+ * ## What a path looks like
+ *
+ * A D1 field is its column path: `email`, `address.line1`, or `profile.phone` for a marked field inside a JSON column,
+ * which `redact` reads field by field. A KV field leads with the part of the entry it is in: `key.email`, `value.token`,
+ * `metadata.ip`, `value[].email` for an array value — or `value` alone when the whole value is marked. It is the path
+ * `pithy privacy scan` writes for the same field.
+ *
+ * ## The per-field record
+ *
+ * `{ path, class }`, from `classifyPrivacy`, with `truncated: true` where a read ran out of its budget, or was cut at
+ * the depth limit on a chain of schemas not yet read, and it assumed every class, and `sameAs` on a reference: a
+ * position written out under another path once the list reached its cap on paths, listed once per class marked
+ * beneath it. The counts count each record, a reference included. Since #390 it also carries `encryptedAtRest`
+ * beside `class`, so "which of your PHI fields are encrypted" is one more derivation rather than a second thing to
+ * maintain, and it is absent where the core cannot say.
+ *
+ * ## What it costs
+ *
+ * Nothing until it is read. {@link lazyPrivacyInventory} walks on first read and caches for the isolate, so a
+ * Worker whose control plane is never called never walks.
+ */
+
+/** The marked fields of a KV store: its key segments, value and metadata, each under its own prefix. */
+function kvFields(store: { key: z.ZodType; value: z.ZodType; metadata?: z.ZodType }): PrivacyField[] {
+  const parts: [string, z.ZodType | undefined][] = [
+    ["key", store.key],
+    ["value", store.value],
+    ["metadata", store.metadata],
+  ];
+  return parts.flatMap(([part, schema]) => {
+    if (!schema) return [];
+    const under = (path: string) => (path === "" || path.startsWith("[") ? `${part}${path}` : `${part}.${path}`);
+    // A reference names a path in the same list, so it takes the same prefix.
+    return classifyPrivacy(schema).map((field) =>
+      field.sameAs === undefined
+        ? { ...field, path: under(field.path) }
+        : { ...field, path: under(field.path), sameAs: under(field.sameAs) },
+    );
+  });
+}
+
+/**
+ * A field record with whether it rests encrypted (#390). **Left out where the core cannot say**: a class assumed past a
+ * budget or a cut, and a reference, which stands for paths it never wrote out. Never defaulted to `false`.
+ */
+function withEncryption(field: PrivacyField, encrypted: ReadonlySet<string>, unrotatable: boolean): PrivacyField {
+  if (field.truncated || field.sameAs !== undefined) return field;
+  const atRest = encrypted.has(field.path);
+  return atRest && unrotatable
+    ? { ...field, encryptedAtRest: true, unrotatable: true }
+    : { ...field, encryptedAtRest: atRest };
+}
+
+/** Classes in the order every report lists them: the built-ins first, then each other class by name. */
+function ordered(classes: Iterable<string>): string[] {
+  const builtIn: readonly string[] = BUILT_IN_PRIVACY_CLASSES;
+  const all = [...new Set(classes)];
+  return [...builtIn.filter((name) => all.includes(name)), ...all.filter((name) => !builtIn.includes(name)).sort()];
+}
+
+/** Walk every composed capability's D1 tables and KV stores. See the module note for exactly what is covered. */
+export function privacyInventory(capabilities: readonly Capability[]): PrivacyInventory {
+  const schemas: PrivacyInventorySchema[] = [];
+  let schemasWalked = 0;
+  for (const capability of capabilities) {
+    for (const [container, database] of Object.entries(capability.databases ?? {})) {
+      for (const [name, table] of Object.entries(database.tables)) {
+        schemasWalked += 1;
+        const paths = new Set(encryptedLayout(table as z.ZodType).fields.map((field) => field.path));
+        const fields = classifyPrivacy(table as z.ZodType).map((field) => withEncryption(field, paths, false));
+        const encrypted: EncryptedFieldRecord[] = [...paths].map((path) => ({ path }));
+        if (fields.length > 0 || encrypted.length > 0) {
+          schemas.push({ capability: capability.name, storage: "d1", container, name, fields, encrypted });
+        }
+      }
+    }
+    for (const [container, namespace] of Object.entries(capability.kvNamespaces ?? {})) {
+      for (const [name, store] of Object.entries(namespace.stores)) {
+        schemasWalked += 1;
+        // An encrypted field in KV is refused at boot; one this walk still meets is reported, and it is unrotatable.
+        const paths = new Set(kvEncryptedPaths(store));
+        const fields = kvFields(store).map((field) => withEncryption(field, paths, true));
+        const encrypted: EncryptedFieldRecord[] = [...paths].map((path) => ({ path, unrotatable: true }));
+        if (fields.length > 0 || encrypted.length > 0) {
+          schemas.push({ capability: capability.name, storage: "kv", container, name, fields, encrypted });
+        }
+      }
+    }
+  }
+  const tally = new Map<string, number>();
+  for (const schema of schemas)
+    for (const field of schema.fields) tally.set(field.class, (tally.get(field.class) ?? 0) + 1);
+  const observed = ordered(tally.keys());
+  const counts = Object.fromEntries(observed.map((name) => [name, tally.get(name) ?? 0]));
+  const encryptedFields = schemas.reduce((sum, schema) => sum + schema.encrypted.length, 0);
+  const unrotatable = schemas.reduce(
+    (sum, schema) => sum + schema.encrypted.filter((field) => field.unrotatable).length,
+    0,
+  );
+  return { sources: [...PRIVACY_SOURCES], schemasWalked, schemas, counts, observed, encryptedFields, unrotatable };
+}
+
+/**
+ * The inventory, walked on first read and cached for the isolate. `capabilities` is a thunk because the
+ * composed set is only known once assembly has run, and reading it is itself deferred to the first call.
+ */
+export function lazyPrivacyInventory(capabilities: () => readonly Capability[]): () => PrivacyInventory {
+  let cached: PrivacyInventory | undefined;
+  return () => {
+    cached ??= privacyInventory(capabilities());
+    return cached;
+  };
+}