@pithy-sh/core 0.12.0 → 0.14.0

package/dist/capability/personRows.d.ts

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { z } from "zod";
+import { type ErasingPurgeContribution, type PurgeContext } from "./purge";
+/**
+ * The purge contribution most capabilities need, written once (#814): rows in D1 that name a person by a column,
+ * exported on an access request and deleted by a purge.
+ *
+ * `@pithy-sh/rating`'s ratings, `@pithy-sh/leaderboard`'s entries, `@pithy-sh/matchmaking`'s friendships — each is
+ * a table whose rows carry the person's id in a column, and nothing else to do with them than read them out and
+ * delete them. A capability with more to do — bytes in R2, an address rather than an id, a row that must be
+ * anonymized — writes its own contribution with the same types.
+ *
+ * **One transaction.** The deletes are one `d1.batch()`, in the order the tables are listed, so a failure leaves
+ * every row where it was and the retried step erases the lot. **Idempotent**: a second run deletes nothing.
+ */
+/** One table a person's rows are in, and how they are found and exported. */
+export interface PersonTable {
+    /** The table's camelCase name, as the capability's tables map keys it. */
+    readonly table: string;
+    /** Its row schema. Rows are decoded through it, so the export carries the app shape and never SQLite's. */
+    readonly schema: z.ZodObject;
+    /** The columns that name the person. A row is theirs when any of them is the subject's id. */
+    readonly columns: readonly string[];
+    /**
+     * Columns a row must also hold exactly — `{ subjectType: "user" }`, where one id column names people and
+     * organizations both and only a person's rows are theirs.
+     */
+    readonly match?: Readonly<Record<string, string>>;
+    /** The key the rows are exported under — `ratings`, `entries`. */
+    readonly as: string;
+    /** A column to read them in, so an export reads the same twice. */
+    readonly orderBy?: string;
+    /** Columns the export leaves out — a credential, or another person's data the row carries beside theirs. */
+    readonly omit?: readonly string[];
+    /**
+     * A per-row redaction, for a credential that sits in a column only some rows hold it in — a Google Play purchase
+     * token keys a purchase row on that rail alone. It is handed the decoded row, before `omit` drops any column, and
+     * returns the row to export.
+     */
+    readonly redact?: (row: Record<string, unknown>) => Record<string, unknown>;
+}
+/** What {@link personRowsPurge} is built from. */
+export interface PersonRowsPurgeInput {
+    /** The capability, for the fault a missing binding raises. */
+    readonly capability: string;
+    /** The one sentence the purge records with this step. */
+    readonly summary: string;
+    /** The D1 binding the tables live in. */
+    readonly database?: string;
+    /** The tables, in the order a purge deletes from them — children before the rows they reference. */
+    readonly tables: readonly PersonTable[];
+}
+/**
+ * The export half alone: every row naming the person in `tables`, decoded, under each table's key. For a
+ * contribution that **retains** its rows (#814) — `@pithy-sh/payments` keeps a purchase for tax law, and still
+ * answers for it.
+ */
+export declare function personRowsExport(input: Omit<PersonRowsPurgeInput, "summary">): (context: PurgeContext) => Promise<Record<string, unknown>>;
+/** Build a user contribution that exports, then on a purge deletes, every row naming the person in `tables`. */
+export declare function personRowsPurge(input: PersonRowsPurgeInput): ErasingPurgeContribution;
+//# sourceMappingURL=personRows.d.ts.map

package/dist/capability/personRows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"personRows.d.ts","sourceRoot":"","sources":["../../src/capability/personRows.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,EAAE,KAAK,wBAAwB,EAAc,KAAK,YAAY,EAAgB,MAAM,SAAS,CAAC;AAErG;;;;;;;;;;;GAWG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2GAA2G;IAC3G,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC;IAC7B,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,kEAAkE;IAClE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4GAA4G;IAC5G,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7E;AAED,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oGAAoG;IACpG,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC;AAiBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,GAC3C,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAmB7D;AAED,gHAAgH;AAChH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,wBAAwB,CAmBrF"}

package/dist/capability/personRows.js

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { exportRows, purgeBinding } from "./purge.js";
+import { createDatabase } from "../data/db.js";
+import { sql } from "kysely";
+//#region src/capability/personRows.ts
+/** `(column = id OR column = id …) AND match…` over a table's person columns. */
+function theirs({ columns, match }, id) {
+	return (eb) => eb.and([eb.or(columns.map((column) => eb(sql.ref(column), "=", id))), ...Object.entries(match ?? {}).map(([column, value]) => eb(sql.ref(column), "=", value))]);
+}
+/**
+* The export half alone: every row naming the person in `tables`, decoded, under each table's key. For a
+* contribution that **retains** its rows (#814) — `@pithy-sh/payments` keeps a purchase for tax law, and still
+* answers for it.
+*/
+function personRowsExport(input) {
+	const database = input.database ?? "DB";
+	return async ({ subject, env }) => {
+		const db = createDatabase(purgeBinding(env, database, input.capability), {});
+		const read = await Promise.all(input.tables.map(async (table) => {
+			let query = db.selectFrom(table.table).selectAll().where(theirs(table, subject.id));
+			if (table.orderBy) query = query.orderBy(sql.ref(table.orderBy));
+			const rows = (await query.execute()).map((row) => {
+				const parsed = table.schema.parse(row);
+				const decoded = table.redact ? table.redact(parsed) : parsed;
+				for (const column of table.omit ?? []) delete decoded[column];
+				return decoded;
+			});
+			return [table.as, exportRows(rows)];
+		}));
+		return Object.fromEntries(read);
+	};
+}
+/** Build a user contribution that exports, then on a purge deletes, every row naming the person in `tables`. */
+function personRowsPurge(input) {
+	const database = input.database ?? "DB";
+	const open = (env) => {
+		const d1 = purgeBinding(env, database, input.capability);
+		return {
+			d1,
+			db: createDatabase(d1, {})
+		};
+	};
+	return {
+		subject: "user",
+		summary: input.summary,
+		erase: async ({ subject, env }) => {
+			const { d1, db } = open(env);
+			const statements = input.tables.map((table) => {
+				const compiled = db.deleteFrom(table.table).where(theirs(table, subject.id)).compile();
+				return d1.prepare(compiled.sql).bind(...compiled.parameters);
+			});
+			if (statements.length > 0) await d1.batch(statements);
+		},
+		export: personRowsExport(input)
+	};
+}
+//#endregion
+export { personRowsExport, personRowsPurge };

package/dist/capability/purge.d.ts

@@ -20,6 +20,21 @@ import { z } from "zod";
  * a step is retried after a failure that may have come after its rows were already gone, and erasing
  * nothing must then succeed.
  *
+ * ## The same contribution answers an export (#622)
+ *
+ * An access request arrives before an erasure, not after. So a contribution may also say what this capability
+ * holds about the subject, on the read side: `export` answers one JSON object, and the control plane's export
+ * route assembles one document from every composed contribution, in the same order the purge runs them. A
+ * contribution with no `export` is listed as holding rows it did not say how to export, which is the honest
+ * answer and the one an operator can act on.
+ *
+ * ## Or it keeps them, and says why (#814)
+ *
+ * Not every row about a person should go. A payment record is kept for tax law, a suppression has to outlive the
+ * person or the unsubscribe stops holding, and the audit trail is the record of who acted. So a contribution has a
+ * third disposition beside erase and anonymize: `retain`, with a one-sentence basis written for the person. The
+ * purge records that step as retained and erases nothing of it; the export carries the rows and the basis.
+ *
  * ## An adopter declares one too
  *
  * On their own `app` capability, for their own tables, with the same types. The contract is exported for
@@ -27,9 +42,11 @@ import { z } from "zod";
  */
 /**
  * The kinds of subject a purge erases. Closed, so a typo is refused where it is written rather than becoming
- * a contribution no purge ever asks for. `organization` joins when organization state does (#623).
+ * a contribution no purge ever asks for. `organization` joined with organization state (#623): a capability
+ * holding rows scoped to a tenant declares one for it, and the organization purge runs it.
  */
 export declare const PurgeSubject: z.ZodEnum<{
+    organization: "organization";
     user: "user";
 }>;
 export type PurgeSubject = z.output<typeof PurgeSubject>;
@@ -42,23 +59,68 @@ export interface PurgeContext {
     };
     /** The Worker's bindings for this run, from which the contribution opens its own database. */
     readonly env: Record<string, unknown>;
+    /**
+     * The subject's email address, read on demand from the capability that owns the subject — `null` when it has
+     * none, or no longer has one (#814). For a capability that holds rows by address rather than by id: a tester's
+     * membership, a suppression, an invitation.
+     *
+     * **A function, never a value**, so the address is read inside the step that needs it and is never carried in
+     * a Workflow's journal, where a purge would otherwise leave it behind. Absent where nobody can say, and a
+     * contribution that needs it then finds nothing by address.
+     */
+    readonly address?: () => Promise<string | null>;
 }
-/** One capability's answer to "how are this subject's rows erased". */
-export interface PurgeContribution {
+/** What every contribution says, whichever its disposition. */
+interface PurgeContributionBase {
     /** The kind of subject this erases. */
     readonly subject: PurgeSubject;
     /**
-     * One sentence on what is erased or anonymized — `Deletes the user's uploads and their stored bytes.`
+     * One sentence on what is erased, anonymized or kept — `Deletes the user's uploads and their stored bytes.`
      * Recorded with the step that ran it, so the trail says what a purge did and not only that it ran.
      */
     readonly summary: string;
+    /**
+     * What this capability holds about the subject, as one JSON object — the read side of `erase` (#622). It
+     * answers an access request, so it carries the subject's own data and never a credential: no session token,
+     * no provider token, no push token. Optional on an erasing contribution: one without it is listed in the
+     * export as rows it erases and did not say how to export. A throw costs this capability's entry, never the
+     * document.
+     */
+    readonly export?: (context: PurgeContext) => Promise<Record<string, unknown>>;
+}
+/** A contribution that erases or anonymizes the subject's rows. */
+export interface ErasingPurgeContribution extends PurgeContributionBase {
     /**
      * Erase or anonymize this subject's rows. **Idempotent**: run again after it succeeded, or after a failure
      * that came once the rows were gone, it must succeed having found nothing to do. Throwing fails this step
      * and only this step.
      */
     readonly erase: (context: PurgeContext) => Promise<void>;
+    /** Never set on an erasing contribution. */
+    readonly retain?: undefined;
+}
+/**
+ * A contribution that **keeps** the subject's rows through a purge, and says why (#814). A payment record kept
+ * for tax law, a suppression that must outlive the person or the unsubscribe stops holding, the audit trail of
+ * who acted. The purge records the step as retained and never erases a row of it; the export carries the rows
+ * and the basis, because rows that are kept are rows that are answered for.
+ */
+export interface RetainingPurgeContribution extends PurgeContributionBase {
+    /** Why the rows are kept, in one sentence written for the person — `Kept for tax records.` */
+    readonly retain: {
+        readonly basis: string;
+    };
+    /** Required: what is kept is exported. */
+    readonly export: (context: PurgeContext) => Promise<Record<string, unknown>>;
+    /** Never set on a retaining contribution. */
+    readonly erase?: undefined;
 }
+/** One capability's answer to "what happens to this subject's rows": erased, anonymized, or kept and why. */
+export type PurgeContribution = ErasingPurgeContribution | RetainingPurgeContribution;
+/** What a purge does with a contribution's rows: `erase` (or anonymize), or `retain`. */
+export type PurgeDisposition = "erase" | "retain";
+/** Whether a contribution keeps the subject's rows rather than erasing them. */
+export declare function isRetained(contribution: PurgeContribution): contribution is RetainingPurgeContribution;
 /** One step of a purge: which capability it runs, and the contribution that capability declared. */
 export interface PurgeStep {
     /** The step's name — the capability's, so a retried step names who failed. */
@@ -77,4 +139,51 @@ export declare function purgeSteps(capabilities: readonly {
     readonly name: string;
     readonly purge?: readonly PurgeContribution[];
 }[], subject: PurgeSubject): PurgeStep[];
+/** What every export entry says: the capability, its sentence, and what a purge does with its rows. */
+interface PurgeExportEntryBase {
+    readonly capability: string;
+    readonly summary: string;
+    /** `erase` — a purge erases or anonymizes these rows — or `retain`, a purge keeps them (#814). */
+    readonly disposition: PurgeDisposition;
+    /** For `retain`, why the rows are kept, in the sentence the contribution wrote for the person. */
+    readonly basis?: string;
+}
+/** What one step's export answered: its data, that it declared none, or that it could not be read. */
+export type PurgeExportEntry = (PurgeExportEntryBase & {
+    readonly state: "exported";
+    readonly data: Record<string, unknown>;
+}) | (PurgeExportEntryBase & {
+    readonly state: "not_exported";
+}) | (PurgeExportEntryBase & {
+    readonly state: "unavailable";
+});
+/**
+ * Read every step's export for one subject — the export document's body, in step order (#622).
+ *
+ * **Each read is guarded on its own and they run concurrently**, the shape the user pane's sub-reads have
+ * (#380): one capability whose table will not read costs its own entry as `unavailable`, and the rest of the
+ * document still answers the request. What the read threw is not carried — it names a query and a table, and
+ * the document crosses a trust boundary. An answer that is not one object is `unavailable` too, because the
+ * document promises an object per capability and a client validates it.
+ */
+export declare function purgeExports(steps: readonly PurgeStep[], context: PurgeContext): Promise<PurgeExportEntry[]>;
+/**
+ * One binding a contribution opens off a run's env — or a wiring fault naming it and the capability (#814). The
+ * purge and the export both run in the adopter's Worker, so a missing binding is that Worker's wiring, and the
+ * fault says which binding to add rather than failing deep inside a query.
+ */
+export declare function purgeBinding<T>(env: Record<string, unknown>, name: string, capability: string, kind?: string): T;
+/**
+ * Rows as an export carries them (#814): plain JSON, a `Date` as its ISO-8601 string — the shape the export
+ * document crosses the wire in, so what a contribution answers is what a reader parses, and a test compares
+ * exactly that.
+ */
+export declare function exportRows<T>(rows: readonly T[]): Record<string, unknown>[];
+/**
+ * Every path in an export's data whose field name holds a credential — empty for an export that carries none.
+ * Each capability's export test asserts it empty, so a column added later with a token in it fails the build
+ * rather than reaching an access request (#814).
+ */
+export declare function credentialFields(value: unknown, path?: string): string[];
+export {};
 //# sourceMappingURL=purge.d.ts.map

package/dist/capability/purge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"purge.d.ts","sourceRoot":"","sources":["../../src/capability/purge.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY;;EAItB,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,8FAA8F;IAC9F,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED,oGAAoG;AACpG,MAAM,WAAW,SAAS;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAAG,IAAI,CA8B9G;AAED,6GAA6G;AAC7G,wBAAgB,UAAU,CACxB,YAAY,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;CAAE,EAAE,EACjG,OAAO,EAAE,YAAY,GACpB,SAAS,EAAE,CAOb"}
+{"version":3,"file":"purge.d.ts","sourceRoot":"","sources":["../../src/capability/purge.ts"],"names":[],"mappings":"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"}

package/dist/capability/purge.js

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { ValidationError } from "../error/pithyError.js";
+import { InternalError, ValidationError } from "../error/pithyError.js";
 import { z } from "zod";
 //#region src/capability/purge.ts
 /**
@@ -22,6 +22,21 @@ import { z } from "zod";
 * a step is retried after a failure that may have come after its rows were already gone, and erasing
 * nothing must then succeed.
 *
+* ## The same contribution answers an export (#622)
+*
+* An access request arrives before an erasure, not after. So a contribution may also say what this capability
+* holds about the subject, on the read side: `export` answers one JSON object, and the control plane's export
+* route assembles one document from every composed contribution, in the same order the purge runs them. A
+* contribution with no `export` is listed as holding rows it did not say how to export, which is the honest
+* answer and the one an operator can act on.
+*
+* ## Or it keeps them, and says why (#814)
+*
+* Not every row about a person should go. A payment record is kept for tax law, a suppression has to outlive the
+* person or the unsubscribe stops holding, and the audit trail is the record of who acted. So a contribution has a
+* third disposition beside erase and anonymize: `retain`, with a one-sentence basis written for the person. The
+* purge records that step as retained and erases nothing of it; the export carries the rows and the basis.
+*
 * ## An adopter declares one too
 *
 * On their own `app` capability, for their own tables, with the same types. The contract is exported for
@@ -29,9 +44,14 @@ import { z } from "zod";
 */
 /**
 * The kinds of subject a purge erases. Closed, so a typo is refused where it is written rather than becoming
-* a contribution no purge ever asks for. `organization` joins when organization state does (#623).
+* a contribution no purge ever asks for. `organization` joined with organization state (#623): a capability
+* holding rows scoped to a tenant declares one for it, and the organization purge runs it.
 */
-const PurgeSubject = z.enum(["user"]).describe("The kind of subject a purge erases. `user` is one person's account in `@pithy-sh/auth`, identified by its user id.");
+const PurgeSubject = z.enum(["user", "organization"]).describe("The kind of subject a purge erases. `user` is one person's account in `@pithy-sh/auth`, identified by its user id. `organization` is one tenant in `@pithy-sh/organization`, identified by its organization id.");
+/** Whether a contribution keeps the subject's rows rather than erasing them. */
+function isRetained(contribution) {
+	return contribution.retain !== void 0;
+}
 /**
 * Refuse a capability's purge contributions that no purge could run as declared: an unknown subject, two for
 * one subject, or one with nothing to record. Called by `defineCapability`, so the refusal names the capability
@@ -54,12 +74,36 @@ function assertPurgeContributions(capability, contributions) {
 			message: `The ${capability} capability's ${subject.data} purge has no summary.`,
 			action: "Say in one sentence what it erases. The purge records it with the step."
 		});
+		if (contribution.export !== void 0 && typeof contribution.export !== "function") throw new ValidationError({
+			message: `The ${capability} capability's ${subject.data} purge has an export that is not a function.`,
+			action: "Give it an `export` that answers what this capability holds about the subject, or leave it out."
+		});
+		if (contribution.retain !== void 0) {
+			assertRetention(capability, subject.data, contribution);
+			continue;
+		}
 		if (typeof contribution.erase !== "function") throw new ValidationError({
 			message: `The ${capability} capability's ${subject.data} purge has no erase function.`,
-			action: "Give it an `erase` that removes or anonymizes the subject's rows."
+			action: "Give it an `erase` that removes or anonymizes the subject's rows, or a `retain` that says why it keeps them."
 		});
 	}
 }
+/** Refuse a retaining contribution the person could not be answered with: no basis, no export, or an erase too. */
+function assertRetention(capability, subject, contribution) {
+	const basis = contribution.retain?.basis;
+	if (typeof basis !== "string" || basis.trim() === "") throw new ValidationError({
+		message: `The ${capability} capability's ${subject} purge retains the rows with no basis.`,
+		action: "Say in one sentence, written for the person, why they are kept — `Kept for tax records.`"
+	});
+	if (typeof contribution.export !== "function") throw new ValidationError({
+		message: `The ${capability} capability's ${subject} purge retains the rows and has no export.`,
+		action: "Give it an `export`: rows that are kept are rows an access request is answered with."
+	});
+	if (contribution.erase !== void 0) throw new ValidationError({
+		message: `The ${capability} capability's ${subject} purge both retains and erases the rows.`,
+		action: "Declare one disposition: `retain` with its basis, or `erase`."
+	});
+}
 /** The steps a purge of `subject` runs, in composition order — libraries first, the adopter's `app` last. */
 function purgeSteps(capabilities, subject) {
 	const steps = [];
@@ -72,5 +116,94 @@ function purgeSteps(capabilities, subject) {
 	}
 	return steps;
 }
+/** Whether an export answered what the contract promises: one plain object. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Read every step's export for one subject — the export document's body, in step order (#622).
+*
+* **Each read is guarded on its own and they run concurrently**, the shape the user pane's sub-reads have
+* (#380): one capability whose table will not read costs its own entry as `unavailable`, and the rest of the
+* document still answers the request. What the read threw is not carried — it names a query and a table, and
+* the document crosses a trust boundary. An answer that is not one object is `unavailable` too, because the
+* document promises an object per capability and a client validates it.
+*/
+async function purgeExports(steps, context) {
+	return Promise.all(steps.map(async ({ step, contribution }) => {
+		const base = isRetained(contribution) ? {
+			capability: step,
+			summary: contribution.summary,
+			disposition: "retain",
+			basis: contribution.retain.basis
+		} : {
+			capability: step,
+			summary: contribution.summary,
+			disposition: "erase"
+		};
+		const read = contribution.export;
+		if (read === void 0) return {
+			...base,
+			state: "not_exported"
+		};
+		try {
+			const data = await read(context);
+			return isRecord(data) ? {
+				...base,
+				state: "exported",
+				data
+			} : {
+				...base,
+				state: "unavailable"
+			};
+		} catch {
+			return {
+				...base,
+				state: "unavailable"
+			};
+		}
+	}));
+}
+/**
+* One binding a contribution opens off a run's env — or a wiring fault naming it and the capability (#814). The
+* purge and the export both run in the adopter's Worker, so a missing binding is that Worker's wiring, and the
+* fault says which binding to add rather than failing deep inside a query.
+*/
+function purgeBinding(env, name, capability, kind = "D1 database") {
+	const binding = env[name];
+	if (typeof binding !== "object" || binding === null) throw new InternalError({
+		message: `The ${capability} capability's ${kind} is not bound, so its purge step could not run.`,
+		action: `Bind the ${kind} named ${name} to the Worker that runs the purge.`,
+		detail: `${capability} purge contribution found no ${name} binding on the env`
+	});
+	return binding;
+}
+/**
+* Rows as an export carries them (#814): plain JSON, a `Date` as its ISO-8601 string — the shape the export
+* document crosses the wire in, so what a contribution answers is what a reader parses, and a test compares
+* exactly that.
+*/
+function exportRows(rows) {
+	return JSON.parse(JSON.stringify(rows));
+}
+/**
+* A field name that holds a credential — a token, a secret, a password, a digest of one, a sealed value. What an
+* export never carries (#814): an access request is answered with what is held, never with the means to act as
+* the person or to reach what they shared.
+*/
+const CREDENTIAL_FIELD = /secret|token|password|credential|digest|private_?key|encrypted/i;
+/**
+* Every path in an export's data whose field name holds a credential — empty for an export that carries none.
+* Each capability's export test asserts it empty, so a column added later with a token in it fails the build
+* rather than reaching an access request (#814).
+*/
+function credentialFields(value, path = "") {
+	if (Array.isArray(value)) return value.flatMap((item, index) => credentialFields(item, `${path}[${index}]`));
+	if (typeof value !== "object" || value === null) return [];
+	return Object.entries(value).flatMap(([key, inner]) => {
+		const here = path ? `${path}.${key}` : key;
+		return [...CREDENTIAL_FIELD.test(key) ? [here] : [], ...credentialFields(inner, here)];
+	});
+}
 //#endregion
-export { PurgeSubject, assertPurgeContributions, purgeSteps };
+export { PurgeSubject, assertPurgeContributions, credentialFields, exportRows, isRetained, purgeBinding, purgeExports, purgeSteps };

package/dist/capability/settings.d.ts

@@ -142,6 +142,16 @@ export interface SettingsAccountReader {
      * Asked by secrets of the manager token the runtime token superseded, which nothing revokes for you.
      */
     accountToken(name: string): Promise<boolean>;
+    /**
+     * **Whether an R2 bucket's objects under `prefix` are under an indefinite lock (#822)** — `locked`, `unlocked`, or
+     * `missing` when no bucket of that name exists on the account. Asked by audit, whose checkpoints are evidence only
+     * while nothing can replace them. Optional, so a reader built before the question existed still compiles; a
+     * check asking a reader without it reports the environment unanswered rather than guessing.
+     */
+    r2BucketLock?(request: {
+        bucket: string;
+        prefix: string;
+    }): Promise<"locked" | "unlocked" | "missing">;
 }
 /** What {@link SettingsAccountReader.appRows} is asked. */
 export interface AppRowsRequest {

package/dist/capability/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/capability/settings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/capability/settings.ts"],"names":[],"mappings":"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"}

package/dist/capability/vectorIndex.d.ts

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * A Vectorize index a capability owns and re-embeds itself — the contribution `pithy vector reprocess` reads.
+ *
+ * ## Why a contribution
+ *
+ * `@pithy-sh/vector` re-embeds the indexes an adopter declares in `vector({ indexes })`. A capability that
+ * builds an index of its own — `@pithy-sh/support`'s semantic message index — uses vector's public modules to
+ * embed and to re-embed, and runs vector's reprocess orchestration in a Workflow it hosts, over its own corpus.
+ * What it cannot do is teach vector's CLI that the index exists: capabilities depend on core seams, never on
+ * each other. So it says so here, on its own `Capability`, the way it states its migrations and its purge, and
+ * `pithy vector reprocess` reads every composed declaration — in a project that never composes `vector()` too.
+ *
+ * ## What the CLI does with one
+ *
+ * It starts `reprocessJob`, one of this capability's own `workflows`, under the deployed name every Workflow
+ * gets — `<project>-<env>-<capability>-<job>` — with the parameters every reprocess takes: `{ index, all }`.
+ * A model change, a repair and a full rebuild (`--all`) are then the same three cases they are for any index.
+ */
+export interface VectorIndexContribution {
+    /**
+     * The index's name as `pithy vector reprocess --index` takes it — `support-messages`. Unique across the
+     * project, and never one of the adopter's own `vector()` index keys.
+     */
+    readonly name: string;
+    /** The job, in this capability's `workflows`, that re-embeds the index. */
+    readonly reprocessJob: string;
+}
+/**
+ * Refuse a declaration no reprocess could run: a duplicate name, or a job the capability does not register.
+ * Called by `defineCapability`, so the mistake is named where it is written rather than on the day somebody
+ * changes a model.
+ */
+export declare function assertVectorIndexContributions(capability: string, indexes: readonly VectorIndexContribution[], jobs: readonly string[]): void;
+//# sourceMappingURL=vectorIndex.d.ts.map

package/dist/capability/vectorIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vectorIndex.d.ts","sourceRoot":"","sources":["../../src/capability/vectorIndex.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,SAAS,uBAAuB,EAAE,EAC3C,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,IAAI,CAiBN"}

package/dist/capability/vectorIndex.js

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError } from "../error/pithyError.js";
+//#region src/capability/vectorIndex.ts
+/**
+* Refuse a declaration no reprocess could run: a duplicate name, or a job the capability does not register.
+* Called by `defineCapability`, so the mistake is named where it is written rather than on the day somebody
+* changes a model.
+*/
+function assertVectorIndexContributions(capability, indexes, jobs) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const index of indexes) {
+		if (seen.has(index.name)) throw new InternalError({
+			message: `The ${capability} capability declares the vector index \`${index.name}\` twice.`,
+			detail: `vectorIndexes on ${capability} repeats ${index.name}`
+		});
+		seen.add(index.name);
+		if (!jobs.includes(index.reprocessJob)) throw new InternalError({
+			message: `The ${capability} capability's vector index \`${index.name}\` names a reprocess job it does not register.`,
+			detail: `vectorIndexes on ${capability}: no workflow job ${index.reprocessJob}; registered: ${jobs.join(", ") || "none"}`
+		});
+	}
+}
+//#endregion
+export { assertVectorIndexContributions };