blogwright-analytics 0.3.3

package/dist/aws/s3tables.js

@@ -0,0 +1,281 @@
+import { AwsError } from 'blogwright-core';
+import { rethrowWithContext } from './errors.js';
+/**
+ * Amazon S3 Tables control-plane client - create/get/delete for table buckets,
+ * namespaces and tables (the `s3tables` API, REST-JSON). It lives in
+ * `blogwright-analytics`, not in core: core's `SIGNING_NAMES` gains no `s3tables`
+ * key, and every request signs through the `{ service: 's3tables', signingName:
+ * 's3tables' }` descriptor the plugin transport seam accepts (see
+ * `packages/core/src/aws/endpoint.ts`'s `ServiceDescriptor`), which resolves to
+ * the canonical `s3tables.<region>.amazonaws.com` host. Operation names, methods
+ * and URI templates below follow the published S3 Tables API reference - GetTable
+ * is the one operation that is not path-templated like its siblings; it takes its
+ * identifiers as query parameters (`/get-table?tableBucketARN=&namespace=&name=`).
+ * The floci emulator does not implement this service, so it is covered by
+ * transport mocks in tests.
+ *
+ * `createTable`'s `schema` parameter mirrors `CreateTableRequest.metadata.iceberg`
+ * (`TableMetadata` is a union whose sole member today is `iceberg: IcebergMetadata`).
+ * Field names below are verified against the service's `IcebergMetadata`,
+ * `IcebergSchema`, `SchemaField`, `IcebergPartitionSpec` and `IcebergPartitionField`
+ * shapes: `IcebergMetadata.schema.fields` (not `schemaV2`, which exists only for
+ * nested/complex Iceberg types this table never uses) carries `{ name, type, id,
+ * required }` - already camelCase on the wire - while `IcebergPartitionSpec.fields`
+ * carries `IcebergPartitionField`, whose `source-id` and `field-id` are genuinely
+ * hyphenated JSON keys, not a documentation typo. This client accepts `sourceId`/
+ * `fieldId` (idiomatic TypeScript) and translates to the wire's hyphenated keys
+ * itself - that translation is this client's concern, not its callers'. A schema
+ * field's `id` is optional in the API (auto-assigned when omitted) but required
+ * here: a partition field can only reference an id the caller already knows, and
+ * schema and partition spec travel in the same `CreateTable` request, so an
+ * auto-assigned id would not exist yet for `sourceId` to reference.
+ */
+const SERVICE = { service: 's3tables', signingName: 's3tables' };
+/** The only table format S3 Tables accepts today; named so `createTable` never repeats the literal. */
+const ICEBERG_FORMAT = 'ICEBERG';
+const PATHS = {
+    buckets: '/buckets',
+    bucket: (tableBucketArn) => `/buckets/${encodeURIComponent(tableBucketArn)}`,
+    namespaces: (tableBucketArn) => `/namespaces/${encodeURIComponent(tableBucketArn)}`,
+    namespace: (tableBucketArn, namespace) => `/namespaces/${encodeURIComponent(tableBucketArn)}/${encodeURIComponent(namespace)}`,
+    tables: (tableBucketArn, namespace) => `/tables/${encodeURIComponent(tableBucketArn)}/${encodeURIComponent(namespace)}`,
+    table: (tableBucketArn, namespace, name) => `/tables/${encodeURIComponent(tableBucketArn)}/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}`,
+    getTable: '/get-table',
+};
+function normalizeTableBucket(res) {
+    return { arn: res.arn ?? '', name: res.name ?? '' };
+}
+// GetNamespace's response carries no `tableBucketARN` field (only the response of
+// CreateNamespace does), so the bucket ARN comes from what the caller already
+// passed in, not from the response.
+function normalizeNamespace(res, tableBucketArn, fallback) {
+    return { name: res.namespace?.[0] ?? fallback, tableBucketArn };
+}
+function normalizeTable(res, fallbackName) {
+    return {
+        arn: res.tableARN ?? '',
+        name: res.name ?? fallbackName,
+        metadataLocation: res.metadataLocation,
+    };
+}
+/** Translate the client's camelCase `IcebergTableSchema` into the wire's `IcebergMetadata` shape - the one place `source-id`/`field-id`'s hyphenated JSON keys are spelled out. */
+function buildIcebergMetadata(schema) {
+    return {
+        iceberg: {
+            schema: {
+                fields: schema.fields.map((f) => ({
+                    name: f.name,
+                    type: f.type,
+                    id: f.id,
+                    ...(f.required !== undefined ? { required: f.required } : {}),
+                })),
+            },
+            ...(schema.partitionSpec && schema.partitionSpec.length > 0
+                ? {
+                    partitionSpec: {
+                        fields: schema.partitionSpec.map((p) => ({
+                            name: p.name,
+                            'source-id': p.sourceId,
+                            transform: p.transform,
+                            ...(p.fieldId !== undefined ? { 'field-id': p.fieldId } : {}),
+                        })),
+                    },
+                }
+                : {}),
+        },
+    };
+}
+/**
+ * True when a `create*` failure should be swallowed as "the resource already
+ * exists". S3 Tables answers a duplicate name with `ConflictException`, whose
+ * only status in the service model is 409, and 409 is the signal this client has
+ * to match on: S3 Tables returns the exception name in an `x-amzn-ErrorType`
+ * header, while core's `parseError` (`packages/core/src/aws/signer.ts`) reads
+ * only the response body, and an S3 Tables error body carries `{"message": ...}`
+ * and nothing else. So every failure from this service arrives as
+ * `AwsError.code === "Http<status>"`, and `AwsError.isAlreadyExists` - which
+ * tests `code` against `/Conflict/i` - never matches here on its own. The
+ * `statusCode === 409` limb below is what actually makes `createTableBucket`,
+ * `createNamespace` and `createTable` idempotent, mirroring how `isNotFound`
+ * survives the same gap on its `statusCode === 404` limb.
+ *
+ * The accepted gap: S3 Tables documents `ConflictException` generically - "the
+ * request failed because there is a conflict with a previous write; retry" - and
+ * has no dedicated already-exists exception for these operations, so a genuine
+ * concurrent write conflict on `create*` reads as success here rather than being
+ * retried or surfaced. A confirming `get*` after the 409 would narrow it without
+ * any new signal, at the cost of a round trip on a path callers already reconcile
+ * read-then-create; not taking it is a deliberate trade, not a missing capability.
+ *
+ * The durable fix is core-level and deliberately not made here (this task must
+ * not touch `packages/core`): `parseError` should read `x-amzn-errortype` and
+ * `x-amzn-requestid` from the headers it already receives, which would hand every
+ * rest-json client its real error code and a request id to quote to AWS support,
+ * and would subsume this 409 limb. Until then, for this service
+ * `AwsError.requestId` is always `undefined` and any narrowing written as
+ * `err.code === 'NotFoundException'` silently never matches - worth knowing
+ * before adding one in tasks 34-36.
+ */
+function isAlreadyExists(err) {
+    return err instanceof AwsError && (err.isAlreadyExists || err.statusCode === 409);
+}
+/** S3 Tables control-plane client, over the shared SigV4 transport. */
+export class S3TablesClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async call(method, path, payload, query) {
+        const res = await this.client.send({
+            service: SERVICE,
+            method,
+            path,
+            ...(query ? { query } : {}),
+            headers: { 'content-type': 'application/json' },
+            ...(payload !== undefined ? { body: JSON.stringify(payload) } : {}),
+        });
+        const text = res.text();
+        return (text ? JSON.parse(text) : {});
+    }
+    /**
+     * Create a table bucket. Idempotent: an already-existing bucket of the same
+     * name is not an error.
+     *
+     * Deliberately returns `void`, discarding the response's `arn`, rather than
+     * surfacing it: `getTableBucket` is ARN-keyed with no name-based lookup, so a
+     * caller that wants the ARN has to compute it before calling `createTableBucket`
+     * anyway - to run its own `getTableBucket` existence check first, per the usual
+     * read-then-create reconcile pattern - using the fixed
+     * `arn:aws:s3tables:<region>:<accountId>:bucket/<name>` form and the account id
+     * a `PluginContext` already carries. By the time `createTableBucket` runs, the
+     * caller already holds the ARN it needs; echoing the response's `arn` back would
+     * be redundant on the happy path, and unavailable on the already-exists path
+     * (the error body carries no `arn`), so returning it from only one of the two
+     * branches would be a false economy. `createNamespace` needs no such lookup at
+     * all (its identity is exactly its inputs); `createTable`'s identity is genuinely
+     * unrecoverable from its inputs (a table ARN carries an opaque generated id, not
+     * a name), but `getTable` is already name-keyed via `/get-table`'s query
+     * parameters, so a caller hydrates a table's ARN with a lookup, not by
+     * reconstructing it.
+     */
+    async createTableBucket(name) {
+        try {
+            await this.call('PUT', PATHS.buckets, { name });
+        }
+        catch (err) {
+            if (isAlreadyExists(err))
+                return;
+            rethrowWithContext(err, 'createTableBucket', name);
+        }
+    }
+    /** Fetch a table bucket by ARN; undefined when it does not exist. */
+    async getTableBucket(tableBucketArn) {
+        try {
+            const res = await this.call('GET', PATHS.bucket(tableBucketArn));
+            return normalizeTableBucket(res);
+        }
+        catch (err) {
+            if (err instanceof AwsError && err.isNotFound)
+                return undefined;
+            rethrowWithContext(err, 'getTableBucket', tableBucketArn);
+        }
+    }
+    /** Delete a table bucket. No-op when it does not exist, so teardown is re-runnable. */
+    async deleteTableBucket(tableBucketArn) {
+        try {
+            await this.call('DELETE', PATHS.bucket(tableBucketArn));
+        }
+        catch (err) {
+            if (err instanceof AwsError && err.isNotFound)
+                return;
+            rethrowWithContext(err, 'deleteTableBucket', tableBucketArn);
+        }
+    }
+    /** Create a namespace in a table bucket. Idempotent: an already-existing namespace is not an error. */
+    async createNamespace(tableBucketArn, namespace) {
+        try {
+            await this.call('PUT', PATHS.namespaces(tableBucketArn), { namespace: [namespace] });
+        }
+        catch (err) {
+            if (isAlreadyExists(err))
+                return;
+            rethrowWithContext(err, 'createNamespace', `${tableBucketArn}/${namespace}`);
+        }
+    }
+    /** Fetch a namespace by bucket ARN and name; undefined when it does not exist. */
+    async getNamespace(tableBucketArn, namespace) {
+        try {
+            const res = await this.call('GET', PATHS.namespace(tableBucketArn, namespace));
+            return normalizeNamespace(res, tableBucketArn, namespace);
+        }
+        catch (err) {
+            if (err instanceof AwsError && err.isNotFound)
+                return undefined;
+            rethrowWithContext(err, 'getNamespace', `${tableBucketArn}/${namespace}`);
+        }
+    }
+    /** Delete a namespace. No-op when it does not exist, so teardown is re-runnable. */
+    async deleteNamespace(tableBucketArn, namespace) {
+        try {
+            await this.call('DELETE', PATHS.namespace(tableBucketArn, namespace));
+        }
+        catch (err) {
+            if (err instanceof AwsError && err.isNotFound)
+                return;
+            rethrowWithContext(err, 'deleteNamespace', `${tableBucketArn}/${namespace}`);
+        }
+    }
+    /**
+     * Create an Iceberg table in a namespace, carrying its schema (and, when given,
+     * its partition spec) so the table is never created schema-less. This matters
+     * beyond correctness-in-general: Firehose matches incoming record keys to
+     * Iceberg column names *exactly* and silently routes anything that does not
+     * match to the error bucket (see the analytics plugin spec's §Record
+     * transformation), so a schema-less table here fails every subsequent record
+     * with no error surfacing anywhere - the corruption this parameter exists to
+     * prevent. Idempotent: an already-existing table is not an error (its schema is
+     * not reconciled against `schema` on that path - S3 Tables has no
+     * update-schema-on-conflict operation for `CreateTable` to fall back to).
+     */
+    async createTable(tableBucketArn, namespace, name, schema) {
+        try {
+            await this.call('PUT', PATHS.tables(tableBucketArn, namespace), {
+                name,
+                format: ICEBERG_FORMAT,
+                metadata: buildIcebergMetadata(schema),
+            });
+        }
+        catch (err) {
+            if (isAlreadyExists(err))
+                return;
+            rethrowWithContext(err, 'createTable', `${tableBucketArn}/${namespace}/${name}`);
+        }
+    }
+    /** Fetch a table by bucket ARN, namespace and name; undefined when it does not exist. */
+    async getTable(tableBucketArn, namespace, name) {
+        try {
+            const res = await this.call('GET', PATHS.getTable, undefined, {
+                tableBucketARN: tableBucketArn,
+                namespace,
+                name,
+            });
+            return normalizeTable(res, name);
+        }
+        catch (err) {
+            if (err instanceof AwsError && err.isNotFound)
+                return undefined;
+            rethrowWithContext(err, 'getTable', `${tableBucketArn}/${namespace}/${name}`);
+        }
+    }
+    /** Delete a table. No-op when it does not exist, so teardown is re-runnable. */
+    async deleteTable(tableBucketArn, namespace, name) {
+        try {
+            await this.call('DELETE', PATHS.table(tableBucketArn, namespace, name));
+        }
+        catch (err) {
+            if (err instanceof AwsError && err.isNotFound)
+                return;
+            rethrowWithContext(err, 'deleteTable', `${tableBucketArn}/${namespace}/${name}`);
+        }
+    }
+}

package/dist/backfill.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `blogwright analytics backfill`: the optional, one-shot, hand-run pull of
+ * history that predates the Firehose delivery, from the CloudWatch log group
+ * the site's own delivery already writes into the `page_views` table. This is
+ * the change spec's
+ * [§Analytics pipeline → Backfill of historical logs](../../../.specs/changes/merged/2026-07-26-analytics_plugin.md),
+ * and it is explicitly **not** part of the steady-state pipeline, which stays
+ * the push path §Shape draws: CloudFront → Firehose → Iceberg, with no
+ * operator in the loop.
+ *
+ * ## The identical-row property
+ *
+ * A record backfilled from CloudWatch and the same record delivered through
+ * Firehose produce the same `page_views` row, and that is a property of code
+ * reuse rather than of two implementations agreeing. This module owns no
+ * mapping at all: it hands each event to `mapRecord` - the same function the
+ * transform Lambda's envelope calls - which derives `event_time`, the `day`
+ * partition, `visitor_key` and `is_bot`, and applies the same drop rules. The
+ * historical day's salt is derivable for the same reason the spec gives: the
+ * per-day salt is `HMAC-SHA256(secret, day)` over one long-lived stored secret
+ * that is never rewritten, and `mapRecord` derives it from the record's own
+ * day, so a record from three months ago hashes under the salt it would have
+ * hashed under then.
+ *
+ * ## Idempotency, by construction rather than by de-duplication
+ *
+ * Three bounds, and none of them inspects a row to decide:
+ *
+ * 1. **Only whole UTC days strictly before the recorded bound.** The
+ *    `analytics-log-delivery` node records {@link CREATED_DAY_KEY} the first
+ *    time it creates its delivery, and never advances it. Firehose received
+ *    nothing before its delivery existed, so every day this command touches is
+ *    a day the Firehose path has no rows in, and the two row sets are
+ *    disjoint. The boundary day itself is never backfilled - up to one day of
+ *    history at the seam is the spec's stated precision limit, accepted rather
+ *    than patched with a row-level de-duplication pass.
+ * 2. **A day that already holds rows is skipped**, counted through the
+ *    existing `AnalyticsQuery` port. That is what makes a re-run a no-op and a
+ *    crashed run resumable, and it is only sound because each day is inserted
+ *    in one transaction: a partially written day would be counted as occupied
+ *    and its remainder lost.
+ * 3. **A mapped row whose own `day` is not the day being written is not
+ *    inserted.** The CloudWatch window is a request for a day's events and
+ *    AWS's `endTime` is not documented as exclusive; the row's own `day` is,
+ *    so that - not the window - is what decides which day a row belongs to.
+ *    Without it a record on the far side of midnight could reach the day the
+ *    Firehose delivery already covers.
+ *
+ * ## What it refuses, and why the refusal is not optional
+ *
+ * With no bound in the plugin's scoped state there is nothing to compute a
+ * range from, and there is no safe default: "everything" would insert days
+ * Firehose already delivered and silently double every row in them. So this
+ * command refuses, before any AWS call, in both of the two states that leave
+ * it without one - no delivery record at all, and a delivery record with no
+ * {@link CREATED_DAY_KEY}. The second is reachable and is not a corruption:
+ * the delivery node's `read` hydrates a delivery it finds already attached
+ * without writing the day, because `DescribeDeliveries` reports no creation
+ * date and a fabricated later bound is the one error direction that corrupts
+ * data rather than merely losing some.
+ *
+ * ## Ports
+ *
+ * The read is core's existing `LogsClient.filterEvents` over
+ * `ctx.clients.logsUsEast1` - no new client and no new core operation. The
+ * count is one named query through `AnalyticsQuery`. The write crosses
+ * `AnalyticsIngest`. This module names no vendor library and issues no
+ * statement of its own.
+ */
+import { type PluginContext } from 'blogwright-core';
+import { type AnalyticsConfig } from './config.js';
+import type { AnalyticsIngest, AnalyticsQuery } from './ports.js';
+/**
+ * The slice of a plugin context this command reads, taken as a `Pick` of
+ * core's own `PluginContext` rather than a restatement of it, the way
+ * `DashboardCommandContext` and `DuckDbSessionContext` already are: the
+ * members cannot drift from the SPI, any `PluginContext<AnalyticsConfig>`
+ * satisfies it, and a test builds what it needs instead of the SPI's sixteen.
+ *
+ * `store`, `save`, `record` and `siteState` are deliberately absent, and their
+ * absence is a statement: **a backfill writes no state.** It reads the bound
+ * the delivery node recorded and nothing else, so a run that crashes halfway
+ * leaves the plugin's state object exactly as it found it, and the only thing
+ * that makes a second run different from the first is what is in the table.
+ */
+export type BackfillContext = Pick<PluginContext<AnalyticsConfig>, 'env' | 'config' | 'pluginConfig' | 'names' | 'clients' | 'state' | 'logger'>;
+/** The two ports {@link runBackfill} is driven over. */
+export interface BackfillPorts {
+    /** Reads the table - one named `row-count` per candidate day. */
+    readonly query: AnalyticsQuery;
+    /** Writes the table - one call per day that turned out to have rows. */
+    readonly ingest: AnalyticsIngest;
+}
+/**
+ * Run the backfill. Fails rather than continuing when a day's insert fails: a
+ * report saying five days landed while one in the middle did not would leave
+ * an operator unable to tell which history they have, and the occupancy check
+ * makes re-running after a fix cost nothing for the days that did land.
+ */
+export declare function runBackfill(ctx: BackfillContext, ports: BackfillPorts): Promise<void>;

package/dist/backfill.js

@@ -0,0 +1,294 @@
+/**
+ * `blogwright analytics backfill`: the optional, one-shot, hand-run pull of
+ * history that predates the Firehose delivery, from the CloudWatch log group
+ * the site's own delivery already writes into the `page_views` table. This is
+ * the change spec's
+ * [§Analytics pipeline → Backfill of historical logs](../../../.specs/changes/merged/2026-07-26-analytics_plugin.md),
+ * and it is explicitly **not** part of the steady-state pipeline, which stays
+ * the push path §Shape draws: CloudFront → Firehose → Iceberg, with no
+ * operator in the loop.
+ *
+ * ## The identical-row property
+ *
+ * A record backfilled from CloudWatch and the same record delivered through
+ * Firehose produce the same `page_views` row, and that is a property of code
+ * reuse rather than of two implementations agreeing. This module owns no
+ * mapping at all: it hands each event to `mapRecord` - the same function the
+ * transform Lambda's envelope calls - which derives `event_time`, the `day`
+ * partition, `visitor_key` and `is_bot`, and applies the same drop rules. The
+ * historical day's salt is derivable for the same reason the spec gives: the
+ * per-day salt is `HMAC-SHA256(secret, day)` over one long-lived stored secret
+ * that is never rewritten, and `mapRecord` derives it from the record's own
+ * day, so a record from three months ago hashes under the salt it would have
+ * hashed under then.
+ *
+ * ## Idempotency, by construction rather than by de-duplication
+ *
+ * Three bounds, and none of them inspects a row to decide:
+ *
+ * 1. **Only whole UTC days strictly before the recorded bound.** The
+ *    `analytics-log-delivery` node records {@link CREATED_DAY_KEY} the first
+ *    time it creates its delivery, and never advances it. Firehose received
+ *    nothing before its delivery existed, so every day this command touches is
+ *    a day the Firehose path has no rows in, and the two row sets are
+ *    disjoint. The boundary day itself is never backfilled - up to one day of
+ *    history at the seam is the spec's stated precision limit, accepted rather
+ *    than patched with a row-level de-duplication pass.
+ * 2. **A day that already holds rows is skipped**, counted through the
+ *    existing `AnalyticsQuery` port. That is what makes a re-run a no-op and a
+ *    crashed run resumable, and it is only sound because each day is inserted
+ *    in one transaction: a partially written day would be counted as occupied
+ *    and its remainder lost.
+ * 3. **A mapped row whose own `day` is not the day being written is not
+ *    inserted.** The CloudWatch window is a request for a day's events and
+ *    AWS's `endTime` is not documented as exclusive; the row's own `day` is,
+ *    so that - not the window - is what decides which day a row belongs to.
+ *    Without it a record on the far side of midnight could reach the day the
+ *    Firehose delivery already covers.
+ *
+ * ## What it refuses, and why the refusal is not optional
+ *
+ * With no bound in the plugin's scoped state there is nothing to compute a
+ * range from, and there is no safe default: "everything" would insert days
+ * Firehose already delivered and silently double every row in them. So this
+ * command refuses, before any AWS call, in both of the two states that leave
+ * it without one - no delivery record at all, and a delivery record with no
+ * {@link CREATED_DAY_KEY}. The second is reachable and is not a corruption:
+ * the delivery node's `read` hydrates a delivery it finds already attached
+ * without writing the day, because `DescribeDeliveries` reports no creation
+ * date and a fabricated later bound is the one error direction that corrupts
+ * data rather than merely losing some.
+ *
+ * ## Ports
+ *
+ * The read is core's existing `LogsClient.filterEvents` over
+ * `ctx.clients.logsUsEast1` - no new client and no new core operation. The
+ * count is one named query through `AnalyticsQuery`. The write crosses
+ * `AnalyticsIngest`. This module names no vendor library and issues no
+ * statement of its own.
+ */
+import { colors } from 'blogwright-core';
+import { createAnalyticsClients } from './aws/clients.js';
+import { resolveAnalyticsConfig } from './config.js';
+import { CREATED_DAY_KEY, LOG_DELIVERY_NODE } from './nodes.js';
+import { ROW_COUNT_COLUMN, ROW_COUNT_QUERY } from './queries.js';
+import { mapRecord } from './transform/map-record.js';
+/** Milliseconds in a UTC day. Every day boundary in this module is computed from it. */
+const MS_PER_DAY = 86_400_000;
+/** `YYYY-MM-DD` - the shape both the state bound and the `day` column carry. */
+const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+/** The leading characters of an ISO-8601 instant that are its UTC day. */
+const ISO_DAY_LENGTH = 10;
+/** The UTC day an epoch-millisecond instant falls on. */
+function dayOf(milliseconds) {
+    return new Date(milliseconds).toISOString().slice(0, ISO_DAY_LENGTH);
+}
+/** Midnight UTC opening `day`, in epoch milliseconds. */
+function startOf(day) {
+    return Date.parse(`${day}T00:00:00.000Z`);
+}
+/**
+ * True for a `YYYY-MM-DD` that names a day that exists. The round trip is what
+ * rejects `2026-02-30`: `Date.parse` accepts it and rolls it forward to March,
+ * so a shape check alone would compute a range from a day the calendar does
+ * not have.
+ */
+function isCalendarDay(day) {
+    if (!DAY_PATTERN.test(day))
+        return false;
+    const start = startOf(day);
+    return !Number.isNaN(start) && dayOf(start) === day;
+}
+/**
+ * The idempotency bound: the UTC day the plugin's delivery was first created,
+ * off the `analytics-log-delivery` node's recorded outputs.
+ *
+ * Three refusals rather than one, because the operator's remedy differs. No
+ * record at all means the pipeline was never provisioned. A record with no
+ * day means the state file lost the key or was written by a `read` that
+ * adopted an existing delivery - and there the remedy is to supply the bound,
+ * not to re-bootstrap, because bootstrapping again will not write a key the
+ * node only writes when it creates the delivery. A malformed day is neither,
+ * and says what it found.
+ */
+function requireCreatedDay(ctx) {
+    const bootstrap = `blogwright analytics bootstrap ${ctx.env}`;
+    const recorded = ctx.state.resources[LOG_DELIVERY_NODE];
+    if (recorded === undefined) {
+        throw new Error(`blogwright analytics backfill needs the day the Firehose delivery was created, and the analytics state for "${ctx.env}" records no ${LOG_DELIVERY_NODE} at all - run \`${bootstrap}\` to provision the pipeline first`);
+    }
+    const day = recorded[CREATED_DAY_KEY];
+    if (typeof day !== 'string' || day === '') {
+        throw new Error(`blogwright analytics backfill needs the day the Firehose delivery was created, and the ${LOG_DELIVERY_NODE} entry in the analytics state for "${ctx.env}" carries no "${CREATED_DAY_KEY}" - it is written only when the delivery is first created, so \`${bootstrap}\` will not add it to a delivery that already exists; set "${CREATED_DAY_KEY}" on that entry to the UTC day the delivery was created (a day too early loses nothing, a day too late double-inserts)`);
+    }
+    if (!isCalendarDay(day)) {
+        throw new Error(`the ${LOG_DELIVERY_NODE} entry in the analytics state for "${ctx.env}" carries "${CREATED_DAY_KEY}": ${JSON.stringify(day)}, which is not a YYYY-MM-DD calendar day - \`${bootstrap}\` writes it in that form`);
+    }
+    return day;
+}
+/**
+ * The candidate days, oldest first: the `retention.cloudfrontDays` whole UTC
+ * days immediately before `createdDay`.
+ *
+ * Anchored on the bound rather than on the clock, and that is deliberate -
+ * this command reads no clock at all. The lower bound exists because the log
+ * group is the only thing that holds these events and its retention is what
+ * decides how far back they go; anchoring it on "today" would need a clock
+ * and would make the same command answer differently on two consecutive days
+ * for no gain, since a day CloudWatch has already expired simply reads back
+ * with no events and is reported as such.
+ */
+function candidateDays(createdDay, retentionDays) {
+    const boundary = startOf(createdDay);
+    const days = [];
+    for (let back = retentionDays; back >= 1; back -= 1) {
+        days.push(dayOf(boundary - back * MS_PER_DAY));
+    }
+    return days;
+}
+/**
+ * The rows already in the table for `day`, through the named `row-count`
+ * query. `includeBots` is bound explicitly rather than left to
+ * `config.analytics.bots`: this is the table's occupancy and not a dashboard
+ * figure, so a day holding nothing but bot traffic is an occupied day.
+ */
+async function rowsAlreadyIn(query, day) {
+    const rows = await query.run(ROW_COUNT_QUERY, {
+        range: { from: day, to: day },
+        includeBots: true,
+    });
+    const count = rows[0]?.[ROW_COUNT_COLUMN];
+    if (typeof count !== 'number') {
+        throw new Error(`the ${ROW_COUNT_QUERY} query answered no ${ROW_COUNT_COLUMN} for ${day}, so the backfill cannot tell whether that day is already in the table`);
+    }
+    return count;
+}
+/**
+ * One CloudWatch log event's message as a CloudFront record, or `undefined`
+ * when it is not one.
+ *
+ * The twin of `transform/handler.ts`'s `decodePayload`, and separate from it
+ * on purpose: the two envelopes differ (Firehose hands over base64, CloudWatch
+ * hands over the message text), and `map-record.ts` documents that parsing and
+ * its failures belong to each boundary rather than to the mapping. What the
+ * two share - what a record IS once parsed - is the type, not the parser.
+ */
+function recordFrom(message) {
+    let parsed;
+    try {
+        parsed = JSON.parse(message);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return undefined;
+    return parsed;
+}
+/**
+ * Map one day's log events. Every event goes through `mapRecord` and nothing
+ * else; what this adds is the two ways a mapped event still does not belong in
+ * this day's insert - it could not be mapped at all, or its own `day` says it
+ * belongs to another one.
+ */
+function mapDay(messages, day, saltSecret) {
+    const rows = [];
+    let unmappable = 0;
+    let foreign = 0;
+    let firstReason;
+    for (const message of messages) {
+        const record = recordFrom(message);
+        if (record === undefined) {
+            unmappable += 1;
+            firstReason ??= 'the log event is not a JSON object';
+            continue;
+        }
+        const mapped = mapRecord(record, saltSecret);
+        if (!mapped.mapped) {
+            unmappable += 1;
+            firstReason ??= mapped.reason;
+            continue;
+        }
+        if (mapped.row.day !== day) {
+            foreign += 1;
+            continue;
+        }
+        rows.push(mapped.row);
+    }
+    return { rows, unmappable, foreign, ...(firstReason === undefined ? {} : { firstReason }) };
+}
+/**
+ * The long-lived salt secret behind `visitor_key`, read once for the whole
+ * run through the plugin's own us-east-1 Secrets Manager client - the region
+ * pin, so the value read here is the value the transform Lambda reads.
+ *
+ * Read before the first day rather than on the first day that needs it: a run
+ * that discovered a missing secret after eighty-nine occupancy queries would
+ * have spent them for nothing, and an operator who has to fix the secret wants
+ * to know at the start.
+ */
+async function readSaltSecret(ctx, secretName) {
+    const secret = await createAnalyticsClients(ctx).secrets.getSecretValue(secretName);
+    if (secret === undefined || secret.trim() === '') {
+        throw new Error(`the analytics salt secret "${secretName}" holds no value: an unsalted visitor_key would identify the visitor it exists to hide, so the backfill stops instead - run \`blogwright analytics bootstrap ${ctx.env}\` to create the secret`);
+    }
+    return secret;
+}
+/** One day: count, read, map, insert - or say why it was skipped. */
+async function backfillDay(ctx, ports, day, saltSecret) {
+    const occupied = await rowsAlreadyIn(ports.query, day);
+    if (occupied > 0) {
+        ctx.logger.info(`  skipped ${day}: the table already holds ${occupied} rows for that day`);
+        return { day, inserted: 0, skipped: 'occupied' };
+    }
+    const start = startOf(day);
+    const events = await ctx.clients.logsUsEast1.filterEvents(ctx.names.cloudfrontLogGroup, {
+        startTime: start,
+        endTime: start + MS_PER_DAY,
+    });
+    const mapped = mapDay(events.map((event) => event.message), day, saltSecret);
+    // Reported per day rather than aggregated, and reported at all because the
+    // silent version of this is the failure mode the whole pipeline is written
+    // against: an operator whose log group carries a different field set sees an
+    // empty table and no error anywhere.
+    if (mapped.unmappable > 0) {
+        ctx.logger.warn(`${day}: ${mapped.unmappable} of ${events.length} log events could not be mapped and were not inserted - ${mapped.firstReason}`);
+    }
+    if (mapped.foreign > 0) {
+        ctx.logger.warn(`${day}: ${mapped.foreign} log events carried another day and were left to that day's own pass`);
+    }
+    if (mapped.rows.length === 0) {
+        ctx.logger.info(`  skipped ${day}: the log group holds no events for that day`);
+        return { day, inserted: 0, skipped: 'empty' };
+    }
+    await ports.ingest.insertDay(day, mapped.rows);
+    ctx.logger.info(`  inserted ${day}: ${mapped.rows.length} rows`);
+    return { day, inserted: mapped.rows.length };
+}
+/** Count the outcomes carrying `skipped`. */
+function countSkipped(outcomes, reason) {
+    return outcomes.filter((outcome) => outcome.skipped === reason).length;
+}
+/**
+ * Run the backfill. Fails rather than continuing when a day's insert fails: a
+ * report saying five days landed while one in the middle did not would leave
+ * an operator unable to tell which history they have, and the occupancy check
+ * makes re-running after a fix cost nothing for the days that did land.
+ */
+export async function runBackfill(ctx, ports) {
+    const createdDay = requireCreatedDay(ctx);
+    const config = resolveAnalyticsConfig(ctx);
+    const relation = `${config.namespace}.${config.table}`;
+    const days = candidateDays(createdDay, ctx.config.retention.cloudfrontDays);
+    ctx.logger.info(colors.bold(`Analytics backfill for "${ctx.env}" from ${ctx.names.cloudfrontLogGroup} into ${relation}`));
+    ctx.logger.info(`  ${days.length} whole UTC days from ${days[0]} to ${days.at(-1)}, bounded below by retention.cloudfrontDays`);
+    const saltSecret = await readSaltSecret(ctx, config.saltSecretName);
+    const outcomes = [];
+    for (const day of days) {
+        outcomes.push(await backfillDay(ctx, ports, day, saltSecret));
+    }
+    const insertedDays = outcomes.filter((outcome) => outcome.inserted > 0);
+    const insertedRows = insertedDays.reduce((total, outcome) => total + outcome.inserted, 0);
+    ctx.logger.ok(`backfill complete: inserted ${insertedRows} rows across ${insertedDays.length} days; skipped ${countSkipped(outcomes, 'occupied')} days already in the table and ${countSkipped(outcomes, 'empty')} with no events`);
+    ctx.logger.info(`  ${createdDay} is the day the Firehose delivery was created and is never backfilled - up to one day of history at the seam is the accepted precision limit`);
+}