@pithy-sh/core 0.11.0 → 0.12.0

package/dist/privacy/encryptedColumns.js

@@ -0,0 +1,134 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ValidationError } from "../error/pithyError.js";
+import { BlindIndexNormalizerName, encryptedLayout, encryptedSpecOf, hasEncryptedFields, sqlIdentifier } from "./encrypted.js";
+import { z } from "zod";
+//#region src/privacy/encryptedColumns.ts
+/**
+* **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. */
+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.");
+/** What the rotator is stamped with: the columns, and what the derivation could not cover. */
+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.");
+/** A SQL JSON path from object keys. Each key is an identifier, which `encryptedLayout` has already required. */
+function jsonPathOf(segments) {
+	return `$.${segments.join(".")}`;
+}
+/** Where an encrypted field sits in one KV store's parts, for the unrotatable list. */
+function kvEncryptedPaths(store) {
+	const paths = [];
+	for (const [part, schema] of [
+		["key", store.key],
+		["value", store.value],
+		["metadata", store.metadata]
+	]) {
+		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.
+*/
+function deriveEncryptedColumns(capabilities) {
+	const columns = [];
+	const unrotatable = [];
+	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);
+			if (layout.fields.length === 0 && layout.problems.length === 0 && !hasEncryptedFields(schema)) 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;
+				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.
+*/
+function refuseEncryptedKvStores(capabilities) {
+	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 === void 0) 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."
+		});
+	}
+}
+//#endregion
+export { EncryptedColumn, EncryptedColumnStamp, deriveEncryptedColumns, kvEncryptedPaths, refuseEncryptedKvStores };

package/dist/privacy/fieldRotation.d.ts

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { D1Database } from "@cloudflare/workers-types";
+import type { Capability } from "../capability/capability";
+import { type EncryptionConfig } from "../crypto/envelope";
+import { type EncryptedColumn } from "./encryptedColumns";
+import { type RetirementVerdict } from "./retirement";
+/** How many rows of one column still hold an envelope or an index under any of `versions`. */
+export declare function countStale(d1: D1Database, column: EncryptedColumn, versions: readonly number[]): Promise<number>;
+/** 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;
+}
+/**
+ * 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 declare function resealBatch(d1: D1Database, column: EncryptedColumn, config: EncryptionConfig, version: number, limit: number): Promise<ResealResult>;
+/**
+ * **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 declare function readRetirement(env: Record<string, unknown>, capabilities: readonly Capability[]): Promise<RetirementVerdict>;
+//# sourceMappingURL=fieldRotation.d.ts.map

package/dist/privacy/fieldRotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldRotation.d.ts","sourceRoot":"","sources":["../../src/privacy/fieldRotation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAmC,KAAK,gBAAgB,EAAgB,MAAM,oBAAoB,CAAC;AAI1G,OAAO,EAA0B,KAAK,eAAe,EAA6B,MAAM,oBAAoB,CAAC;AAC7G,OAAO,EAAE,KAAK,iBAAiB,EAAkC,MAAM,cAAc,CAAC;AAmDtF,8FAA8F;AAC9F,wBAAsB,UAAU,CAC9B,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAAC,MAAM,CAAC,CAOjB;AASD,2BAA2B;AAC3B,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;CAChB;AAkBD;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,YAAY,CAAC,CA6DvB;AAOD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,YAAY,EAAE,SAAS,UAAU,EAAE,GAClC,OAAO,CAAC,iBAAiB,CAAC,CAmC5B"}

package/dist/privacy/fieldRotation.js

@@ -0,0 +1,186 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError } from "../error/pithyError.js";
+import { EncryptedEnvelope, decryptValue, encryptValue } from "../crypto/envelope.js";
+import { FIELD_KEYS_BINDING, liveVersions, resolveFieldKeys } from "../crypto/fieldKeys.js";
+import { blindIndexValue } from "./blindIndex.js";
+import { deriveEncryptedColumns } from "./encryptedColumns.js";
+import { retirementVerdict, versionsDue } from "./retirement.js";
+import { fieldContext } from "./sealed.js";
+//#region src/privacy/fieldRotation.ts
+/**
+* **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) {
+	return `"${identifier.replace(/"/g, "\"\"")}"`;
+}
+/** The SQL that reads the key version of a column's envelope. */
+function envelopeVersion(column) {
+	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) {
+	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, count) {
+	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, versions) {
+	return column.index ? [...versions, ...versions] : [...versions];
+}
+/** How many rows of one column still hold an envelope or an index under any of `versions`. */
+async function countStale(d1, column, versions) {
+	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();
+	return Number(row?.count ?? 0);
+}
+/** The envelope a stored column holds at the field's path, or `null` where it holds none. */
+function envelopeAt(column, stored) {
+	if (stored === null) return null;
+	let value = 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[segment];
+		}
+		if (value === void 0 || 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.
+*/
+async function resealBatch(d1, column, config, version, limit) {
+	const result = {
+		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();
+	for (const row of results) {
+		let envelope;
+		let plaintext = null;
+		let sealed = null;
+		let indexValue = 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 = 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 {
+			result.failed += 1;
+			continue;
+		}
+		const readVersion = envelope?.keyVersion ?? null;
+		const set = [];
+		const values = [];
+		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;
+		}
+		if (((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()).meta.changes ?? 0) > 0) result.resealed += 1;
+		else result.skipped += 1;
+	}
+	return result;
+}
+/** Whether an `env` slot is a D1 binding. */
+function isD1(value) {
+	return typeof value === "object" && value !== null && typeof value.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.
+*/
+async function readRetirement(env, capabilities) {
+	let stamp;
+	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 = [];
+	let current;
+	if (stamp.columns.length > 0 || keys !== void 0) try {
+		const config = await resolveFieldKeys(keys);
+		versions = liveVersions(config);
+		current = Number(config.currentVersion);
+	} catch {
+		coverageComplete = false;
+	}
+	const due = current === void 0 ? [] : 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
+	});
+}
+//#endregion
+export { countStale, readRetirement, resealBatch };

package/dist/privacy/inventory.d.ts

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Capability } from "../capability/capability";
+import { type PrivacyInventory } from "./report";
+/** Walk every composed capability's D1 tables and KV stores. See the module note for exactly what is covered. */
+export declare function privacyInventory(capabilities: readonly Capability[]): PrivacyInventory;
+/**
+ * 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 declare function lazyPrivacyInventory(capabilities: () => readonly Capability[]): () => PrivacyInventory;
+//# sourceMappingURL=inventory.d.ts.map

package/dist/privacy/inventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../../src/privacy/inventory.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAK3D,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,UAAU,CAAC;AAgFlB,iHAAiH;AACjH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,gBAAgB,CAuCtF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,SAAS,UAAU,EAAE,GAAG,MAAM,gBAAgB,CAMtG"}

package/dist/privacy/inventory.js

@@ -0,0 +1,154 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { BUILT_IN_PRIVACY_CLASSES } from "./classes.js";
+import { classifyPrivacy } from "./classify.js";
+import { encryptedLayout } from "./encrypted.js";
+import { kvEncryptedPaths } from "./encryptedColumns.js";
+import { PRIVACY_SOURCES } from "./report.js";
+//#region src/privacy/inventory.ts
+/**
+* **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) {
+	return [
+		["key", store.key],
+		["value", store.value],
+		["metadata", store.metadata]
+	].flatMap(([part, schema]) => {
+		if (!schema) return [];
+		const under = (path) => path === "" || path.startsWith("[") ? `${part}${path}` : `${part}.${path}`;
+		return classifyPrivacy(schema).map((field) => field.sameAs === void 0 ? {
+			...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, encrypted, unrotatable) {
+	if (field.truncated || field.sameAs !== void 0) 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) {
+	const builtIn = 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. */
+function privacyInventory(capabilities) {
+	const schemas = [];
+	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).fields.map((field) => field.path));
+			const fields = classifyPrivacy(table).map((field) => withEncryption(field, paths, false));
+			const encrypted = [...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;
+			const paths = new Set(kvEncryptedPaths(store));
+			const fields = kvFields(store).map((field) => withEncryption(field, paths, true));
+			const encrypted = [...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 = /* @__PURE__ */ new Map();
+	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.
+*/
+function lazyPrivacyInventory(capabilities) {
+	let cached;
+	return () => {
+		cached ??= privacyInventory(capabilities());
+		return cached;
+	};
+}
+//#endregion
+export { lazyPrivacyInventory, privacyInventory };

package/dist/privacy/posture.d.ts

@@ -0,0 +1,114 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { type PrivacyInventory } from "./report";
+/**
+ * **What a project declares about privacy, and what its running code holds — side by side** (#132).
+ *
+ * Two facts with two provenances, and the asymmetry between them is the useful part.
+ *
+ * - **Declared** is an **attestation**. The root `pithy.config.ts` names the classes a project handles
+ *   (`privacy: { classes: ["pii", "phi"] }`), and `pithy deploy` writes them, with the console gate's verdict, into
+ *   {@link PRIVACY_ATTESTATION_VAR} on every Worker it ships — the mechanism a Worker already learns its own name
+ *   and project by. It is dated, and it describes the last deploy Pithy performed.
+ * - **Observed** is a **derivation** — the inventory, walked from the composed schemas inside the Worker. It
+ *   cannot be edited and cannot be stale.
+ *
+ * An attestation that disagrees with what the running code holds is itself the finding, which is why both are
+ * reported and neither is an error Pithy raises. A project declaring `phi` with no PHI field marked is an
+ * unfinished migration; one marking `phi` it never declared is a posture change nobody escalated.
+ *
+ * ## How stale an attestation can be
+ *
+ * **Usually it is absent rather than stale.** `pithy deploy` passes the var on wrangler's argv (`--var`), and a
+ * plain `wrangler deploy` uploads only the vars its config names — wrangler sends `keep_bindings` for plain-text
+ * vars only under `keep_vars: true` (read in wrangler 4.151.0's deploy path) — so a deploy Pithy did not perform
+ * drops the attestation, and the posture reads `unattested`. Under `keep_vars: true` the var survives a raw
+ * deploy and describes an older build. The Cloudflare version id cannot pair the two, because it is assigned at
+ * upload, after the var is written; the manifest carries {@link PrivacyAttestation.attestedAt} beside the
+ * version's own creation time instead, and a version created long after its attestation is that case.
+ */
+/** The var `pithy deploy` writes the attestation into. JSON, parsed by {@link privacyAttestation}. */
+export declare const PRIVACY_ATTESTATION_VAR = "PITHY_PRIVACY";
+/**
+ * The console gate's verdict at the deploy that wrote the attestation. `off` never appears: `pithy deploy`
+ * refuses a project whose rule is off, so no attestation is ever written for one.
+ */
+export declare const ConsoleGateVerdict: z.ZodEnum<{
+    enforced: "enforced";
+    not_required: "not_required";
+    unverifiable: "unverifiable";
+}>;
+export type ConsoleGateVerdict = z.output<typeof ConsoleGateVerdict>;
+/** What `pithy deploy` attests on a Worker it ships. */
+export declare const PrivacyAttestation: z.ZodObject<{
+    classes: z.ZodArray<z.ZodString>;
+    consoleGate: z.ZodEnum<{
+        enforced: "enforced";
+        not_required: "not_required";
+        unverifiable: "unverifiable";
+    }>;
+    reason: z.ZodNullable<z.ZodString>;
+    attestedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type PrivacyAttestation = z.output<typeof PrivacyAttestation>;
+/**
+ * Read the attestation off a Worker's `env`. **Never throws**: an absent var, a value that is not JSON, and one
+ * that does not parse are all `null`, which the posture reports as `unattested`. A string is parsed; an object
+ * — what wrangler hands a JSON-typed var — is taken as it is.
+ */
+export declare function privacyAttestation(env: unknown): PrivacyAttestation | null;
+/** The console gate as the manifest reports it: the attested verdict, or `unattested` when there is none. */
+export declare const ConsoleGateState: z.ZodEnum<{
+    enforced: "enforced";
+    not_required: "not_required";
+    unattested: "unattested";
+    unverifiable: "unverifiable";
+}>;
+export type ConsoleGateState = z.output<typeof ConsoleGateState>;
+/**
+ * The privacy block on `GET /control-plane/manifest`. Counts and classes only — no field names.
+ *
+ * **A project that declared nothing costs nothing.** When the attestation says no class is declared, the block
+ * says exactly that and the walk does not run: `observed`, `counts` and both deltas are null, and `sources` is
+ * empty, because nothing was looked at. That is the "behaves exactly as it does today" a project omitting the
+ * key is promised. Every other case walks — a declared project to compare against, and an **unattested** one
+ * because a Worker shipped around `pithy deploy` is precisely the one whose holdings someone needs to see.
+ */
+export declare const PrivacyPosture: z.ZodObject<{
+    declared: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    observed: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    counts: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    observedNotDeclared: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    declaredNotObserved: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    consoleGate: z.ZodEnum<{
+        enforced: "enforced";
+        not_required: "not_required";
+        unattested: "unattested";
+        unverifiable: "unverifiable";
+    }>;
+    consoleGateReason: z.ZodNullable<z.ZodString>;
+    attestedAt: z.ZodNullable<z.ZodISODateTime>;
+    sources: z.ZodArray<z.ZodEnum<{
+        d1: "d1";
+        kv: "kv";
+    }>>;
+    retirement: z.ZodOptional<z.ZodObject<{
+        blocked: z.ZodBoolean;
+        reasons: z.ZodArray<z.ZodEnum<{
+            "incomplete-coverage": "incomplete-coverage";
+            stale: "stale";
+            unrotatable: "unrotatable";
+        }>>;
+        liveVersions: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PrivacyPosture = z.output<typeof PrivacyPosture>;
+/** Whether an attestation says, explicitly, that the project declares no class — the one case that walks nothing. */
+export declare function declaresNothing(attestation: PrivacyAttestation | null): boolean;
+/**
+ * The posture: the attestation beside the inventory, and the delta both ways. `inventory` is a thunk, read only
+ * when something is declared or nothing is attested — see {@link PrivacyPosture}.
+ */
+export declare function privacyPosture(attestation: PrivacyAttestation | null, inventory: () => PrivacyInventory): PrivacyPosture;
+//# sourceMappingURL=posture.d.ts.map

package/dist/privacy/posture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posture.d.ts","sourceRoot":"","sources":["../../src/privacy/posture.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,sGAAsG;AACtG,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;EAI5B,CAAC;AACJ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE,wDAAwD;AACxD,eAAO,MAAM,kBAAkB;;;;;;;;;iBAc5B,CAAC;AACJ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAc1E;AAED,6GAA6G;AAC7G,eAAO,MAAM,gBAAgB;;;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsDxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,qHAAqH;AACrH,wBAAgB,eAAe,CAAC,WAAW,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAE/E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,kBAAkB,GAAG,IAAI,EACtC,SAAS,EAAE,MAAM,gBAAgB,GAChC,cAAc,CA8BhB"}