@pithy-sh/core 0.13.0 → 0.14.0

package/src/capability/personRows.ts

@@ -0,0 +1,125 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { type Expression, type ExpressionBuilder, type Kysely, type SqlBool, sql } from "kysely";
+import type { z } from "zod";
+import { createDatabase } from "../data/db";
+import { type ErasingPurgeContribution, exportRows, type PurgeContext, purgeBinding } 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[];
+}
+
+/** An untyped Kysely: each table is named by the input, not by a typed map. */
+type Untyped = Kysely<Record<string, Record<string, unknown>>>;
+
+/** `(column = id OR column = id …) AND match…` over a table's person columns. */
+function theirs(
+  { columns, match }: Pick<PersonTable, "columns" | "match">,
+  id: string,
+): (eb: ExpressionBuilder<Record<string, Record<string, unknown>>, string>) => Expression<SqlBool> {
+  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.
+ */
+export function personRowsExport(
+  input: Omit<PersonRowsPurgeInput, "summary">,
+): (context: PurgeContext) => Promise<Record<string, unknown>> {
+  const database = input.database ?? "DB";
+  return async ({ subject, env }) => {
+    const db = createDatabase(purgeBinding<D1Database>(env, database, input.capability), {}) as unknown as Untyped;
+    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) as Record<string, unknown>;
+          const decoded = table.redact ? table.redact(parsed) : parsed;
+          for (const column of table.omit ?? []) delete decoded[column];
+          return decoded;
+        });
+        return [table.as, exportRows(rows)] as const;
+      }),
+    );
+    return Object.fromEntries(read);
+  };
+}
+
+/** Build a user contribution that exports, then on a purge deletes, every row naming the person in `tables`. */
+export function personRowsPurge(input: PersonRowsPurgeInput): ErasingPurgeContribution {
+  const database = input.database ?? "DB";
+  const open = (env: Record<string, unknown>) => {
+    const d1 = purgeBinding<D1Database>(env, database, input.capability);
+    return { d1, db: createDatabase(d1, {}) as unknown as Untyped };
+  };
+  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 as unknown[]));
+      });
+      if (statements.length > 0) await d1.batch(statements);
+    },
+    export: personRowsExport(input),
+  };
+}

package/src/capability/purge.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
-import { ValidationError } from "../error/pithyError";
+import { InternalError, ValidationError } from "../error/pithyError";
 
 /**
  * How a capability says what erasing one subject means for its own rows — the purge contribution.
@@ -31,6 +31,13 @@ import { ValidationError } from "../error/pithyError";
  * 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
@@ -55,30 +62,73 @@ export interface PurgeContext {
   readonly subject: { readonly type: PurgeSubject; readonly id: string };
   /** 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>;
-  /**
-   * 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: a contribution without one 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>>;
+  /** 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 function isRetained(contribution: PurgeContribution): contribution is RetainingPurgeContribution {
+  return contribution.retain !== undefined;
 }
 
 /** One step of a purge: which capability it runs, and the contribution that capability declared. */
@@ -123,15 +173,43 @@ export function assertPurgeContributions(capability: string, contributions: read
         action: "Give it an `export` that answers what this capability holds about the subject, or leave it out.",
       });
     }
+    if (contribution.retain !== undefined) {
+      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: string, subject: PurgeSubject, contribution: PurgeContribution): void {
+  const basis = (contribution.retain as { basis?: unknown } | undefined)?.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 !== undefined) {
+    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. */
 export function purgeSteps(
   capabilities: readonly { readonly name: string; readonly purge?: readonly PurgeContribution[] }[],
@@ -145,16 +223,21 @@ export function purgeSteps(
   return steps;
 }
 
+/** 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 =
-  | {
-      readonly capability: string;
-      readonly summary: string;
-      readonly state: "exported";
-      readonly data: Record<string, unknown>;
-    }
-  | { readonly capability: string; readonly summary: string; readonly state: "not_exported" }
-  | { readonly capability: string; readonly summary: string; readonly state: "unavailable" };
+  | (PurgeExportEntryBase & { readonly state: "exported"; readonly data: Record<string, unknown> })
+  | (PurgeExportEntryBase & { readonly state: "not_exported" })
+  | (PurgeExportEntryBase & { readonly state: "unavailable" });
 
 /** Whether an export answered what the contract promises: one plain object. */
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -173,7 +256,9 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 export async function purgeExports(steps: readonly PurgeStep[], context: PurgeContext): Promise<PurgeExportEntry[]> {
   return Promise.all(
     steps.map(async ({ step, contribution }): Promise<PurgeExportEntry> => {
-      const base = { capability: step, summary: contribution.summary };
+      const base: PurgeExportEntryBase = 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 === undefined) return { ...base, state: "not_exported" };
       try {
@@ -185,3 +270,55 @@ export async function purgeExports(steps: readonly PurgeStep[], context: PurgeCo
     }),
   );
 }
+
+/**
+ * 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 function purgeBinding<T>(
+  env: Record<string, unknown>,
+  name: string,
+  capability: string,
+  kind = "D1 database",
+): T {
+  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 as 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 function exportRows<T>(rows: readonly T[]): Record<string, unknown>[] {
+  return JSON.parse(JSON.stringify(rows)) as Record<string, unknown>[];
+}
+
+/**
+ * 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).
+ */
+export function credentialFields(value: unknown, path = ""): string[] {
+  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)];
+  });
+}

package/src/capability/settings.ts

@@ -169,6 +169,13 @@ 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. */

package/src/capability/vectorIndex.ts

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "../error/pithyError";
+
+/**
+ * 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 function assertVectorIndexContributions(
+  capability: string,
+  indexes: readonly VectorIndexContribution[],
+  jobs: readonly string[],
+): void {
+  const seen = new Set<string>();
+  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"}`,
+      });
+    }
+  }
+}