@ultimat3/jobs 12.0.0 → 13.0.0

package/CLAUDE.md

@@ -388,6 +388,73 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   ABANDONED round does not release**: it is still enqueueing, so handing the lock over is that same
   double-fire delivered by the shutdown, and a lease row expiring on its own is the safe end —
   `jobs.scheduler.drain-abandoned` is the line that says so.
+- **`exportRows()` is a FACTORY over `job()`, and the part KEY is what makes at-least-once safe**
+  (`As of 2026-08-24`). Same rule `backfill()`, `purge()` and `webhook()` follow. The paging is
+  `backfill-pass.ts`'s and never a second idiom — `inBatches()`, one page per `step.run`, and what
+  a step persists is the CURSOR and two counters, never the page.
+
+  **One object per PAGE, not one per export**, and that is the whole design rather than a
+  simplification: `StorageDriver.put()` buffers by construction — `packages/storage/src/driver.ts`
+  says the server-side path "is for objects that FIT IN MEMORY" — so a single-object export holds
+  the entire dataset, which is the failure this factory exists to prevent. Because a part is named
+  by its page INDEX, a page that runs twice rewrites the same object with the same bytes: there is
+  no idempotency argument to make about the app's rows, and no append anywhere, because a duplicate
+  part cannot be expressed. `export-pass.test.ts` proves it by deleting a mid-run checkpoint and
+  re-running, which is exactly the window at-least-once opens.
+
+  **The interleaving assertion is the memory guard, not `maxPartBytes`.** `maxPartBytes` bounds one
+  page; it cannot see a rewrite that accumulates every page and writes at the end. The test records
+  how many checkpoints had LANDED at each `put` — `0,1,2,…` for a streaming pass and a flat run of
+  the final count for a buffering one — and it is the only thing in the suite that fails on that
+  rewrite.
+
+  **An export gets NO cross-tenant escape, and `backfill()` does.** The asymmetry is deliberate and
+  is the direction of the data: a sweep that rewrites every tenant's rows is an operator action
+  with an audit trail, while an export READS every tenant's rows into one object somebody can
+  download. `tenant: 'none'` therefore fails closed on a tenant-scoped entity
+  (`X_TENANCY_ACTOR_ORG_REQUIRED`) and is for tables with no tenant column at all.
+
+  **The format is the framework's and the columns are the app's.** The csv formula guard (a cell
+  leading `=`, `+`, `-`, `@`, TAB or CR is evaluated by every spreadsheet) and RFC-4180 quoting are
+  identical for a bank and a blog; which columns leave the building never is. The guard is on
+  STRINGS only — prefixing every leading `-` would turn a refund column into text.
+- **`webhook()` is a FACTORY over `job()` and delivers ONE event to ONE endpoint** (`As of
+  2026-08-24`). Same rule `backfill()` and `purge()` follow. The unit is the ENDPOINT and not the
+  event, because retry, backoff and disable-after-N are all per-endpoint facts: a job that fanned
+  out inside one body would retry every subscriber because one of them was down, which is the
+  defect `15-adding-a-feature.md` already names for a mail loop under a single step. **Which
+  endpoints exist is the app's** (axiom 8) — the fan-out is the app's own loop, one `enqueue` per
+  endpoint, and the idempotency key is `<name>:<endpointId>:<eventId>` for the same reason: a key
+  on the event alone would dedupe every subscriber's delivery into the first one's row.
+
+  Four things are load-bearing and none is an implementation detail. **The endpoint is never
+  checkpointed**: it carries the secret, and a `step.run` output is written to `x_job_steps` — so
+  this body uses NO steps and re-reads both seams per attempt. **The signature's timestamp is SEND
+  time**, so a delivery retried three days later is signed again now and a receiver's freshness
+  window measures the request rather than the age of the fact behind it. **The endpoint row's own
+  `headers` merge UNDER the framework's**, because a row that could set
+  `x-ultimate-webhook-signature` is a row that can forge one. **`redirect: 'manual'`**, because
+  following a 3xx re-POSTs a body signed for one host to whatever the receiver named, signature
+  and all.
+
+  The ledger is a SEAM (`WebhookLedger`), the shape `PurgeTarget` already has: retention is seven
+  years for one business and thirty days for the next, so shipping a schema would be shipping one
+  of those answers. `record()` answers the consecutive-failure count rather than that being a
+  second method — the number the mechanism disables on must not be readable from before the row it
+  is deciding about. Every attempt is recorded BEFORE the throw: a failure the ledger cannot see is
+  an endpoint that never gets disabled. Re-enabling is always the app's.
+
+  **The wire format is `@ultimat3/core`'s, RE-EXPORTED and never re-declared** (`As of
+  2026-08-24`). `packages/core/src/webhook-signature.ts` states
+  `v1:<timestampSeconds>:<eventId>:<topic>:<body>` once — the canonical string, the mac, the three
+  header names and the parse a receiver reads back — because this package signs a delivery,
+  `@ultimat3/http` verifies one, and neither may import the other. Exactly the argument
+  `timing-safe-equal.ts` makes for itself. It shipped for one release as two implementations held
+  together by a hex literal asserted in two test files; that works and is not a single source of
+  truth. Core's own suite now pins the thing neither package could: that the SENDING form
+  (`body: string`) and the RECEIVING form (`body: Uint8Array`) are the same function over the same
+  bytes. **Never re-declare the canonical string here** — a second spelling is what the move
+  deleted.
 - **`backfill()` is a FACTORY over `job()`, never a ninth primitive.** Same rule `llm()` follows
   in `@ultimat3/ai`: a new capability arrives as a factory over an existing primitive, so a
   backfill inherits `.enqueue()`, the retry policy, the cancellation, the dead-letter path and

package/README.md

@@ -337,6 +337,140 @@ export const hourly = task({
 without writing any of the above. It needs a `worker` to run it and a `scheduler` to fire it: a
 deployment with neither has no background work at all, and this is one more thing it does not do.
 
+## Exporting a large dataset is a job too
+
+`exportRows()` is a factory over `job()` that streams a paged read to object storage with a
+resumable cursor. It exists for one reason: `const all = await repo.all(); await disk.put(key,
+csv(all))` works on 200 rows and OOM-kills the pod on two million.
+
+```ts
+import type { ReadBuilder } from '@ultimat3/entity';
+import { exportRows, t } from '@ultimat3/jobs';
+import { formatMoney, type Money } from '@ultimat3/money';
+import { disk } from '@ultimat3/storage';
+import { formatDate, instant } from '@ultimat3/time';
+
+interface Order {
+  readonly id: string;
+  readonly placedAt: Date;
+  readonly total: Money;
+}
+
+// The app's own chain: `source` takes whatever `db.orders.where(…)` answers.
+declare const db: {
+  readonly orders: { where(filter: { readonly orgId: string }): ReadBuilder<Order> };
+};
+
+export const exportOrders = exportRows({
+  name: 'orders.export',
+  input: t.object({ orgId: t.string, exportId: t.string }),
+  // The security boundary of the whole feature — an export concentrates one tenant's rows into a
+  // single downloadable object.
+  tenant: ({ orgId }) => orgId,
+  prefix: ({ orgId, exportId }) => `exports/${orgId}/${exportId}`,
+  source: ({ input }) => db.orders.where({ orgId: input.orgId }),
+  format: 'csv',
+  columns: ['id', 'placedAt', 'total'],
+  row: (order) => ({
+    id: order.id,
+    // A date gets its zone and a Money its currency HERE, where the app knows which it means.
+    // `instant()` is the check that turns a stored `Date` into one nothing can format zone-less.
+    placedAt: formatDate(instant(order.placedAt), { locale: 'en', zone: 'UTC' }),
+    total: formatMoney(order.total, 'en'),
+  }),
+  sink: disk('exports'),   // a StorageDriver already IS an ExportSink
+});
+```
+
+The artifact is one object per page plus a manifest:
+
+```
+exports/<orgId>/<exportId>/part-00000.csv
+exports/<orgId>/<exportId>/part-00001.csv
+exports/<orgId>/<exportId>/manifest.json
+```
+
+| Rule | Why |
+|---|---|
+| one object per PAGE, never one per export | `put()` buffers by construction — its own header says the server-side path "is for objects that FIT IN MEMORY" — so a single-object export holds the whole dataset, which is the failure this exists to prevent |
+| the part key is the page INDEX | so a page that runs twice REWRITES its part. At-least-once needs no idempotency argument about your rows here: a duplicate part cannot be expressed |
+| a step persists the CURSOR and two counters | never the page — `steps.ts` retains a completed step's output for the whole run, so checkpointing rows keeps every exported row until the job ends |
+| every line ends in a newline, header in part 0 only | `cat part-*` is one valid file, which is what makes the parts an artifact rather than fragments |
+| `maxPartBytes` is a heap bound, not a file-size preference | one page is encoded whole before it is written; `X_EXPORT_PART_TOO_LARGE` names the `batch` to lower |
+| a `row()` key `columns` does not carry is REFUSED | both encoders would drop it in silence, and `row: (r) => ({ ...r })` picks up every column the entity gains from the next migration on |
+| csv cells leading `=`, `+`, `-`, `@`, TAB or CR are neutralised | Excel, Sheets and LibreOffice EVALUATE them, so a user-named record is code execution in the reviewer's spreadsheet. Strings only — a negative number stays a number |
+| the manifest COUNTS parts, never lists them | `exportPartKey(prefix, i, format)` rebuilds every key, and a list is the one thing in the pass that would grow with the export |
+| `tenant: 'none'` gets no cross-tenant escape | `backfill()` does (`backfill-scope.ts`) because its lazy chain leaves an author nothing to wrap. An export does not, and the difference is the direction of the data: a sweep rewrites rows under audit, an export writes every tenant's rows into one downloadable object |
+| `rate` has no default, unlike a backfill's | a backfill competes for WRITE capacity on rows the app is still serving; an export is a bounded read somebody is usually waiting for. Declare it for an export big enough to matter to the pool |
+
+`ExportSink` is a seam and not a `@ultimat3/storage` import, for the reason `PurgeTarget` is one:
+this package holds no storage dependency, and taking one so a queue could name a disk would put the
+object store on tier 3's import graph.
+
+## Outbound webhooks are jobs too
+
+`webhook()` is a factory over `job()` and delivers **one event to one endpoint**. Retry with
+backoff, disable-after-N and the ledger are all per-endpoint facts, so the endpoint is the unit: a
+job that fanned out inside one body would retry every subscriber because one of them was down.
+**Which endpoints exist is the app's** — the fan-out is your own `for` loop over your own
+subscription table, one `enqueue` per endpoint.
+
+```ts
+import { memoryWebhookLedger, webhook } from '@ultimat3/jobs';
+
+declare const db: {
+  endpoints: { byId(id: string): Promise<{ id: string; url: string; secret: string } | null> };
+  events: { byId(id: string): Promise<{ topic: string; body: string } | null> };
+};
+
+export const deliver = webhook({
+  name: 'partner.webhooks',
+  tenant: 'none',
+  // Read once per ATTEMPT and never checkpointed: the endpoint carries a secret, and a step's
+  // output is written to `x_job_steps`.
+  endpoint: ({ endpointId }) => db.endpoints.byId(endpointId),
+  event: ({ eventId }) => db.events.byId(eventId),
+  ledger: memoryWebhookLedger(), // dev only — a bounded ring in one heap
+  disableAfter: 10,
+});
+
+// The fan-out is yours, because the subscription table is yours.
+declare function subscribersOf(topic: string): Promise<readonly { id: string }[]>;
+declare const event: { readonly id: string };
+
+for (const endpoint of await subscribersOf('orders.paid')) {
+  await deliver.enqueue({ endpointId: endpoint.id, eventId: event.id });
+}
+```
+
+The delivery carries three headers beyond `content-type`, and the signature is over
+`v1:<timestampSeconds>:<eventId>:<topic>:<body>`:
+
+```
+x-ultimate-webhook-id:        evt_01HZ
+x-ultimate-webhook-topic:     orders.paid
+x-ultimate-webhook-signature: t=1700000000,v1=<hex hmac-sha256>
+```
+
+The receiving half is `verifyWebhookSignature(request, { secret })` in `@ultimat3/http`. The format
+itself — the canonical string, the mac and the header names — is **one module in `@ultimat3/core`**
+(`webhook-signature.ts`), re-exported by both packages and re-declared by neither: this package
+signs, `http` verifies, and neither may import the other, so the one copy lives at the tier both
+can reach. Same argument `timing-safe-equal.ts` makes for itself.
+
+| Rule | Why |
+|---|---|
+| the timestamp is **inside** the mac | a captured delivery re-dated to slip back into a receiver's freshness window no longer verifies |
+| the timestamp is SEND time, not event time | a retry three days later signs again now, so the window measures the request rather than the age of the fact |
+| `:` is refused in an id or a topic | one mac over `v1:t:evt:01HZ:orders.paid:<body>` would otherwise authenticate two different id/topic splits — the same delivery under a label the sender never wrote |
+| the endpoint's own `headers` merge **under** the framework's | an endpoint row that could set `x-ultimate-webhook-signature` is an endpoint row that can forge one |
+| `redirect: 'manual'` | following a 3xx would re-POST a body signed for one host to whatever the receiver named |
+| the endpoint is never checkpointed | a `step.run` output lands in `x_job_steps`, and the endpoint carries the secret |
+| every attempt is recorded **before** the throw | a failure the ledger cannot see is a failure the consecutive count cannot see, which is an endpoint that never gets disabled |
+| a `Retry-After` the receiver names is honoured | `X_WEBHOOK_DELIVERY_THROTTLED` carries `meta.retryAfterSeconds`, which the nack waits out (clamped by `retry.maxDelay`) rather than guessing a curve against an answer it already has |
+| re-enabling is always yours | an endpoint the framework un-disabled on its own is a retry loop with no end |
+| `WebhookLedger` is a seam, not a table | retention is seven years for one business and thirty days for the next, so shipping a schema would ship one of those answers |
+
 ## The deadline cancels
 
 A job's `timeout` aborts `ctx.signal` **before** it fails the attempt, because the nack that
@@ -504,6 +638,17 @@ and never detects the occurrence the pod it replaced dropped (`catchUp` and `max
 update runs two leaders.
 
 ```ts
+import {
+  createPgLeaseLeader,
+  createScheduler,
+  type JobDriver,
+  type PgExecutor,
+  pgSchedulerState,
+} from '@ultimat3/jobs';
+
+declare const driver: JobDriver;
+declare const executor: PgExecutor;   // `@ultimat3/cli`'s pgExecutorFor(client)
+
 createScheduler({
   driver,
   state: pgSchedulerState(executor),
@@ -518,6 +663,10 @@ expiry and needs no connection affinity. `acquire()` is also the renewal, called
 is how a demoted node finds out.
 
 ```ts
+import { type AnyJobHandle, task } from '@ultimat3/jobs';
+
+declare const sendDigest: AnyJobHandle;   // the job this cron puts on the queue
+
 export const nightlyDigest = task({
   cron: '0 3 * * *',
   tz: 'UTC',                      // REQUIRED — a cron without a timezone is a bug

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/jobs",
-  "version": "12.0.0",
+  "version": "13.0.0",
   "description": "Durable background work: steps, transactional outbox, cron tasks, one driver interface",
   "license": "MIT",
   "type": "module",
@@ -32,9 +32,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "12.0.0",
-    "@ultimat3/entity": "12.0.0",
-    "@ultimat3/schema": "12.0.0",
-    "@ultimat3/time": "12.0.0"
+    "@ultimat3/core": "13.0.0",
+    "@ultimat3/entity": "13.0.0",
+    "@ultimat3/schema": "13.0.0",
+    "@ultimat3/time": "13.0.0"
   }
 }

package/src/errors.ts

@@ -26,6 +26,16 @@ export const JOB_OWNED_ERROR_CODES = [
   'X_JOB_ROW_STATUS_UNKNOWN',
   'X_ACTION_JOB_UNBRIDGED',
   'X_JOB_CLAIM_QUEUES_EMPTY',
+  'X_WEBHOOK_ENDPOINT_UNKNOWN',
+  'X_WEBHOOK_ENDPOINT_INVALID',
+  'X_WEBHOOK_ENDPOINT_DISABLED',
+  'X_WEBHOOK_EVENT_UNKNOWN',
+  'X_WEBHOOK_EVENT_INVALID',
+  'X_WEBHOOK_DELIVERY_FAILED',
+  'X_WEBHOOK_DELIVERY_THROTTLED',
+  'X_WEBHOOK_DELIVERY_REJECTED',
+  'X_EXPORT_ROW_INVALID',
+  'X_EXPORT_PART_TOO_LARGE',
 ] as const;
 
 /**
@@ -64,6 +74,16 @@ export const JOB_ERROR_TITLES: Readonly<Record<JobOwnedErrorCode, string>> = {
   X_JOB_ROW_STATUS_UNKNOWN: 'a queue row carries a status this build does not know',
   X_ACTION_JOB_UNBRIDGED: 'an action projection was registered as a job',
   X_JOB_CLAIM_QUEUES_EMPTY: 'a claim named no queue, and the drivers do not agree what that means',
+  X_WEBHOOK_ENDPOINT_UNKNOWN: 'no endpoint carries this id',
+  X_WEBHOOK_ENDPOINT_INVALID: 'the endpoint cannot be delivered to as declared',
+  X_WEBHOOK_ENDPOINT_DISABLED: 'the endpoint takes no deliveries',
+  X_WEBHOOK_EVENT_UNKNOWN: 'no event carries this id',
+  X_WEBHOOK_EVENT_INVALID: 'the event cannot be signed as declared',
+  X_WEBHOOK_DELIVERY_FAILED: 'the endpoint did not accept the delivery',
+  X_WEBHOOK_DELIVERY_THROTTLED: 'the endpoint asked for the delivery later, and said when',
+  X_WEBHOOK_DELIVERY_REJECTED: 'the endpoint refused the delivery in a way a retry cannot change',
+  X_EXPORT_ROW_INVALID: 'row() answered something the declared columns do not carry',
+  X_EXPORT_PART_TOO_LARGE: 'one page encoded to more bytes than a part may hold',
 };
 
 // One unconditional call, so a second package claiming one of jobs' codes throws
@@ -93,6 +113,28 @@ registerErrorRetry({
   X_BACKFILL_STALLED: 'terminal',
   X_BACKFILL_ENVIRONMENT: 'terminal',
   X_BACKFILL_APPLIED: 'terminal',
+  // The one retryable webhook code, and the reason the split exists at all: a 5xx, a 429 or a
+  // connection that never opened is the same request landing later, which is what the job's retry
+  // policy is for.
+  X_WEBHOOK_DELIVERY_FAILED: 'retryable',
+  // `retry-after` and not `retryable`: the receiver NAMED a delay, so `statedDelayMs` reads
+  // `meta.retryAfterSeconds` and the nack waits that long (clamped by the policy's `maxDelay`)
+  // instead of guessing a curve against an answer it was already given.
+  X_WEBHOOK_DELIVERY_THROTTLED: 'retry-after',
+  // The rest are `terminal` and every one is LISTED rather than left to the default, because
+  // `classifyThrown` reads an unregistered code carrying `terminal` as UNCLASSIFIED — which spends
+  // a delivery's whole retry policy re-proving that a 404 endpoint is still a 404.
+  X_WEBHOOK_DELIVERY_REJECTED: 'terminal',
+  X_WEBHOOK_ENDPOINT_UNKNOWN: 'terminal',
+  X_WEBHOOK_ENDPOINT_INVALID: 'terminal',
+  X_WEBHOOK_ENDPOINT_DISABLED: 'terminal',
+  X_WEBHOOK_EVENT_UNKNOWN: 'terminal',
+  X_WEBHOOK_EVENT_INVALID: 'terminal',
+  // Both export codes are refusals of the DECLARATION and not of the data: the same `row()` over
+  // the same page answers the same way on every attempt, so an unclassified reading would spend
+  // the whole retry policy proving it.
+  X_EXPORT_ROW_INVALID: 'terminal',
+  X_EXPORT_PART_TOO_LARGE: 'terminal',
 });
 
 // No `docs:` on any class below, here or in `backfill-errors.ts`. `UltimateError` fills it from

package/src/export-errors.ts

@@ -0,0 +1,50 @@
+// The two `X_EXPORT_*` codes an export pass can end on, apart from `errors.ts` for the reason
+// `backfill-errors.ts` and `webhook-errors.ts` are: one file, one job, and `errors.ts` holds the
+// registry — the codes, the titles and the single `registerErrorCodes()` call.
+//
+// Both are TERMINAL and both are refusals of the DECLARATION rather than of the data: the same
+// `row()` over the same page answers the same way on every attempt, so retrying spends a policy
+// proving it.
+
+import { UltimateError } from '@ultimat3/core';
+
+/**
+ * `row()` answered something the declaration did not promise: a column missing, a column nobody
+ * declared, or a value no format can carry.
+ *
+ * The extra-column half is the one worth the code. A `row()` that returns a key `columns` omits is
+ * silently DROPPED by both encoders — so an export that was supposed to carry a column carries the
+ * rest of the file looking perfectly correct, and the gap is found by whoever consumes it, later.
+ * The reverse — a column nobody declared — is how PII leaves through an export nobody reviewed:
+ * `row: (r) => ({ ...r })` picks up every column the entity gains from then on.
+ *
+ * `cause` names the COLUMN and never the value: a cell is user data by definition, and a cause
+ * reaches the log store as a field nothing can redact.
+ */
+export class ExportRowInvalidError extends UltimateError {
+  constructor(input: { export: string; column: string; reason: string }) {
+    super({
+      code: 'X_EXPORT_ROW_INVALID',
+      cause: `export "${input.export}" row() answered a "${input.column}" that ${input.reason}`,
+      fix: `return exactly the declared columns from row() on exportRows("${input.export}"), each one a string, a finite number, a boolean or null — format a date with an explicit timeZone and a Money with its own currency before it gets here`,
+      meta: { column: input.column },
+    });
+  }
+}
+
+/**
+ * One page encoded to more bytes than a part may hold. The memory bound made mechanical: this
+ * factory exists because accumulating a result set before writing it is the failure it prevents,
+ * and "we hold a page, not a dataset" is only true while a page is bounded. A row that is a
+ * megabyte of JSON turns `batch: 1_000` into a gigabyte in one buffer.
+ */
+export class ExportPartTooLargeError extends UltimateError {
+  constructor(input: { export: string; part: number; bytes: number; maxBytes: number }) {
+    super({
+      code: 'X_EXPORT_PART_TOO_LARGE',
+      cause: `export "${input.export}" part ${input.part} encoded to ${input.bytes} bytes and a part may hold ${input.maxBytes}`,
+      fix: `lower batch on exportRows("${input.export}") until a page fits, or raise maxPartBytes if this deployment really can hold that much per part — the number is a heap bound, not a file-size preference`,
+      meta: { part: input.part, bytes: input.bytes, maxBytes: input.maxBytes },
+    });
+  }
+}

package/src/export-format.ts

@@ -0,0 +1,132 @@
+// One page of rows -> the bytes that page contributes to the artifact. Pure and synchronous, so
+// every hazard in it is testable without a queue, a source or a sink.
+//
+// The FORMAT is the framework's and the COLUMNS are the app's, which is exactly the line
+// `docs/idea/20-large-app-readiness.md` draws for this feature. Quoting and the spreadsheet
+// injection guard are identical for a bank and a blog and are the two things every hand-rolled
+// CSV exporter gets wrong; which columns leave the building never is.
+
+import { ExportRowInvalidError } from './export-errors';
+
+export const EXPORT_FORMATS = ['ndjson', 'csv'] as const;
+export type ExportFormat = (typeof EXPORT_FORMATS)[number];
+
+/** The file extension each format's parts carry. `Object.freeze<T>({…})`, so an extra key fails. */
+export const EXPORT_EXTENSION = Object.freeze<Record<ExportFormat, string>>({
+  ndjson: 'ndjson',
+  csv: 'csv',
+});
+
+/**
+ * What a cell may hold. Deliberately no `Date` and no `Money`: a date without an explicit IANA
+ * zone and a money as a float are both build errors everywhere else in this framework, and an
+ * export is the one surface where the wrong answer is archived rather than re-rendered. The app
+ * formats both before they get here, where it can see which zone and which currency it means.
+ */
+export type ExportValue = string | number | boolean | null;
+export type ExportRecord = Readonly<Record<string, ExportValue>>;
+
+/** Fields a spreadsheet EVALUATES when they lead a cell. See `guardFormula`. */
+const FORMULA_LEAD = /^[=+\-@\t\r]/;
+/** A cell that would otherwise break the row or the file it sits in. */
+const NEEDS_QUOTE = /[",\r\n]/;
+
+export interface EncodePageInput {
+  /** The export's name, for a refusal to name. Never rendered into the artifact. */
+  readonly subject: string;
+  readonly format: ExportFormat;
+  /** The declared columns, in order. The header's order and the ndjson key order alike. */
+  readonly columns: readonly string[];
+  readonly records: readonly ExportRecord[];
+  /** True for part 0 only: a csv header belongs in the file once, and parts concatenate. */
+  readonly header: boolean;
+}
+
+/**
+ * Refused rather than coerced, and BOTH directions matter. A missing column silently becomes an
+ * empty cell; an undeclared one is silently dropped — and `row: (r) => ({ ...r })` picks up every
+ * column the entity gains from the next migration on, which is how a column nobody reviewed leaves
+ * the building. Neither is visible in the artifact, which is why it has to be a refusal.
+ */
+function readCell(input: EncodePageInput, record: ExportRecord, column: string): ExportValue {
+  if (!Object.hasOwn(record, column)) {
+    throw new ExportRowInvalidError({
+      export: input.subject,
+      column,
+      reason: 'the declared columns name and row() did not answer',
+    });
+  }
+  const value = record[column];
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  // FINITE, not merely `typeof 'number'`: `NaN` and `Infinity` land in the file as the words `NaN`
+  // and `Infinity`, which no consumer parses back to a number and no reviewer notices in a
+  // million-row artifact.
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  throw new ExportRowInvalidError({
+    export: input.subject,
+    column,
+    reason: 'is not a string, a finite number, a boolean or null',
+  });
+}
+
+/** Every column, checked, plus a refusal for any key `columns` does not carry. */
+function project(input: EncodePageInput, record: ExportRecord): readonly ExportValue[] {
+  const cells = input.columns.map((column) => readCell(input, record, column));
+  for (const key of Object.keys(record)) {
+    if (input.columns.includes(key)) continue;
+    throw new ExportRowInvalidError({
+      export: input.subject,
+      column: key,
+      reason: 'row() answered and the declaration does not carry — it would be dropped in silence',
+    });
+  }
+  return cells;
+}
+
+/**
+ * A leading `=`, `+`, `-`, `@`, TAB or CR makes Excel, Sheets and LibreOffice EVALUATE the cell —
+ * so a record a user named `=cmd|'/c calc'!A1` is remote code execution in the reviewer's
+ * spreadsheet, and nothing in the exporting app looks wrong. A leading apostrophe is the one
+ * portable neutraliser.
+ *
+ * STRINGS only. Prefixing every leading `-` would turn a refund column into text in every
+ * spreadsheet that opened it, which is a data defect traded for a security one.
+ */
+const guardFormula = (value: string): string => (FORMULA_LEAD.test(value) ? `'${value}` : value);
+
+const csvCell = (value: ExportValue): string => {
+  if (value === null) return '';
+  if (typeof value !== 'string') return String(value);
+  const guarded = guardFormula(value);
+  return NEEDS_QUOTE.test(guarded) ? `"${guarded.split('"').join('""')}"` : guarded;
+};
+
+/** The csv header line, exported so the manifest and the first part cannot spell it differently. */
+export const csvHeader = (columns: readonly string[]): string =>
+  `${columns.map((column) => csvCell(column)).join(',')}\n`;
+
+/**
+ * The page's bytes. Every line ends in a newline in both formats, so `cat part-0000 part-0001` is
+ * a valid file — which is what makes one object per page a legitimate artifact rather than a pile
+ * of fragments.
+ */
+export function encodeExportPage(input: EncodePageInput): Uint8Array {
+  const lines: string[] = [];
+  if (input.format === 'csv' && input.header) lines.push(csvHeader(input.columns));
+  for (const record of input.records) {
+    const cells = project(input, record);
+    if (input.format === 'csv') {
+      lines.push(`${cells.map(csvCell).join(',')}\n`);
+      continue;
+    }
+    // Rebuilt in the declared column order rather than stringifying `record`: an object literal's
+    // key order is whatever `row()` happened to write, and two attempts of the same export must
+    // produce byte-identical parts — that is what makes a replayed page an overwrite.
+    const object: Record<string, ExportValue> = {};
+    input.columns.forEach((column, at) => {
+      object[column] = cells[at] ?? null;
+    });
+    lines.push(`${JSON.stringify(object)}\n`);
+  }
+  return new TextEncoder().encode(lines.join(''));
+}