blogwright-analytics 0.3.3

package/README.md

@@ -0,0 +1,162 @@
+# blogwright-analytics
+
+Traffic analytics for [blogwright](https://github.com/antstanley/blogwright): a second
+CloudFront access-log delivery routed through Amazon Data Firehose into an Apache Iceberg
+table in an S3 Tables bucket, with a local SvelteKit dashboard that reads that table
+through DuckDB. The site's existing CloudWatch log delivery is untouched - one CloudFront
+delivery source carries several deliveries, so this one is added beside it.
+
+This package owns the whole pipeline: its own four AWS service clients (S3 Tables,
+Firehose, Glue, Lambda), the twelve resource nodes those clients reconcile, the
+record-transform Lambda, the named query set, and the dashboard application. It depends
+on `blogwright-core` (ports, the SigV4 transport and signer, the S3 and Secrets Manager
+clients) and on DuckDB, which is reached only through the `AnalyticsQuery` port's one
+adapter. It never imports the CLI.
+
+## Install
+
+The plugin is not shipped with the CLI. A repo that never installs it pays nothing:
+
+```sh
+blogwright plugin add analytics
+```
+
+`analytics` resolves to the package `blogwright-analytics`, installed at the running
+CLI's own version and pinned exactly, so the CLI and its plugins cannot drift apart
+between two checkouts of the same repo. `blogwright plugin list` shows it once installed,
+and `blogwright plugin remove analytics` offers to tear its resources down first.
+
+## Commands
+
+Once installed, the plugin answers `blogwright analytics <action> [env]`. The environment
+defaults to `production` and `--env` overrides the positional, exactly as for a built-in
+command. Five actions are the steady state:
+
+| Action | What it does |
+| --- | --- |
+| `blogwright analytics init [env]` | Asks for the `analytics` config block - namespace, table, bot handling, dashboard port - and splices it into `config/<env>.jsonc`. `blogwright init` asks the same questions as part of the first-run wizard. |
+| `blogwright analytics bootstrap [env]` | Provisions the pipeline: the S3 Tables bucket, its namespace and the `page_views` table, the Glue `s3tablescatalog` federation, the `visitor_key` salt secret, the transform Lambda and its execution role, the Firehose error bucket, delivery role and delivery stream, and the CloudWatch delivery destination and delivery. |
+| `blogwright analytics status [env]` | Reports each node present or missing, then the Firehose stream's delivery health and the table's current row count. An environment that was never bootstrapped is not an error: every node reports missing and the command exits 0. |
+| `blogwright analytics dashboard [env]` | Serves the prebuilt dashboard from `dist/app` on `127.0.0.1` (port 4317 by default) and answers its named queries against the table. |
+| `blogwright analytics destroy [env] --yes` | Removes the plugin's own resources. The Glue federation is the one exception and is never deleted - see below. |
+
+Two things the table does not say. The plugin's resources are recorded in their own state
+object, `state/<env>.analytics.json`: `blogwright bootstrap` provisions none of them, and
+`blogwright destroy --yes` refuses while that object exists and names
+`blogwright analytics destroy <env> --yes` as the way through. And the dashboard's server
+answers only the queries this package defines by name - the seven the dashboard charts
+(`views-over-time`, `unique-visitors`, `top-paths`, `referrers`, `countries`,
+`status-codes`, `cache-hit-ratio`) plus the `row-count` that `analytics status` reads.
+It never executes SQL supplied over its socket, and it binds loopback only.
+
+### `blogwright analytics backfill [env]` - optional, one-shot
+
+A sixth action, deliberately not in the table above, because it is not part of
+the steady state. Firehose only carries what CloudFront produced after its
+delivery existed; `backfill` is the hand-run pull of the history that came
+before it, and once it has run there is no reason to run it again.
+
+It reads the CloudWatch log group the site's own delivery already writes -
+`/<siteName>/<env>/cloudfront`, bounded by `retention.cloudfrontDays` - and
+maps every event through the same code the transform Lambda runs, so a record
+produces the same `page_views` row whichever path carried it, `visitor_key`
+included: the day's salt is `HMAC-SHA256(secret, day)` over the same stored
+secret, so a historical day's salt is derivable and the raw IP is no more
+stored here than it is there.
+
+**It cannot double-count, and not by de-duplicating.** The
+`analytics-log-delivery` node records the UTC day it first created the
+delivery, once and never again, and the backfill inserts only whole days
+*strictly before* that day - Firehose received nothing before its delivery
+existed, so the two paths never write the same day. Within that range each day
+is one transaction, a day the table already holds rows for is skipped, and a
+row whose own `day` is not the day being written is not inserted. So a re-run
+inserts nothing, and a run that crashed resumes where it stopped.
+
+The boundary day itself is never backfilled. Up to one day of history at the
+seam is lost, which is the accepted precision limit rather than an oversight:
+buying it back would mean comparing rows, and comparing rows is the thing this
+design does not do.
+
+The command refuses, before it calls AWS at all, when the plugin's state
+carries no delivery record - run `blogwright analytics bootstrap <env>` first -
+and also when it carries a delivery with no recorded day, which is what a state
+file that lost the key looks like. There is no default in that case: assuming
+"everything" would insert days Firehose has already delivered and double every
+row in them, so the command says what to supply instead. Its report names every
+day it inserted, every day it skipped and why, and the boundary day it left
+alone.
+
+## Everything is created in us-east-1
+
+Every resource this plugin owns is created in `us-east-1` regardless of `config.region`,
+and every node's title says so rather than diverging silently.
+
+CloudFront forces it. CloudFront is a global service whose logging control plane lives in
+`us-east-1` alone, and standard logging accepts a Firehose delivery stream only there, so
+the stream has to be in that region. Everything the stream reaches has to follow: the
+table bucket and its Iceberg table, the Glue federation the stream writes through, the
+transform Lambda the stream invokes, the Firehose error bucket, and the salt secret the
+Lambda reads. The two IAM roles are global, and state the pipeline they serve instead.
+
+That is why this package builds its own S3 and Secrets Manager clients over the host's
+`signingUsEast1` signer rather than reusing `ctx.clients.s3` and `ctx.clients.secrets`:
+the host's pair signs in `config.region`, which would put the error bucket, and the salt,
+in a region the transform function cannot read from.
+
+## Privacy
+
+**The raw viewer IP is never stored.** `c-ip` is selected from CloudFront only so the
+transform Lambda can derive `visitor_key` from it, and no column of the `page_views` table
+holds it: it has no entry in the field-to-column map, and the transform discards it after
+hashing. `visitor_key` is a SHA-256 digest over the viewer IP, the user agent and that
+day's salt, and the salt is `HMAC-SHA256(secret, day)` over one long-lived random secret
+held in Secrets Manager - never the date alone, which anyone holding the table could
+compute and then brute-force back across a 32-bit address space. The consequence is
+deliberate and stated where it matters: a `visitor_key` is not comparable across days, so
+a monthly unique-visitor figure is the sum of daily uniques rather than a distinct count.
+
+**`cs(Cookie)` and `x-forwarded-for` are never selected**, so they never leave CloudFront
+for this pipeline: they reach neither Firehose, nor the transform, nor the table. This
+governs the analytics delivery only. The site's existing CloudWatch delivery is created
+with no field list, so AWS's default set - which includes both - still applies to that
+copy; narrowing it is a change to the site's own node, not this one.
+
+No cookie is set and no identifier is written to a visitor's browser. Bot traffic is
+flagged rather than dropped (`is_bot` is a column, and filtering is a query default), so
+a heuristic that turns out to be wrong is a query change and not lost data.
+
+## Shared state, and what teardown leaves behind
+
+One resource is account-and-region scoped rather than per-environment: the Glue
+`s3tablescatalog` federation that Firehose reaches S3 Tables through. Two environments of
+the same site share it. Its node therefore adopts an existing federation rather than
+failing, and its `delete()` is a no-op - tearing down staging must not break production,
+and the Glue API this package speaks exposes no delete operation at all. Everything else
+the plugin creates is per-environment and is removed by
+`blogwright analytics destroy <env> --yes`.
+
+Rows are never aged out. The table is append-only and partitioned by `day`, so expiring
+old data would mean whole-partition deletes issued on a schedule; S3 Tables offers no
+row-retention setting for a table you create. The site's `retention.cloudfrontDays`
+governs only the CloudWatch copy of the logs.
+
+## Configuration
+
+The `analytics` block in `config/<env>.jsonc`, all of it optional:
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `namespace` | `web` | Iceberg namespace holding the table. |
+| `table` | `page_views` | Iceberg table the page views land in. |
+| `bots` | `flag` | `flag` keeps bot rows and marks them; `filter` excludes them from queries. |
+| `dashboard.port` | `4317` | Port the local dashboard binds on `127.0.0.1`. |
+| `tableBucket` | `<env>-<siteName>-analytics` | S3 Tables bucket holding the namespace. |
+| `saltSecretName` | `<siteName>/<env>/analytics-salt` | Secrets Manager secret the daily salt is derived from. |
+
+The last two carry the environment in their defaults and are not asked by the wizard: a
+prompt whose default is wrong for every environment but one is worse than no prompt. Write
+them into the block by hand to override either, where the same validator still checks
+them. Do not take the environment out of either default: without it two environments
+resolve to the same Iceberg table and the same salt, and `blogwright analytics destroy`
+in staging would delete production's data.

package/dist/adapters/duckdb-ingest.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The real {@link AnalyticsIngest}: DuckDB with the S3 Tables catalog attached
+ * writable, inserting one whole UTC day per transaction. It is the write half
+ * of the change spec's §Backfill of historical logs - "written through the
+ * DuckDB dependency the dashboard already ships, behind a write port of its
+ * own" - and it shares every part of the session with the read adapter beside
+ * it through `duckdb-session.ts`: the same credential secret, the same attach
+ * target, the same quoting and the same rule that no vendor error object
+ * escapes. The one clause that differs is `READ_ONLY`, which this session
+ * omits.
+ *
+ * **The steady-state pipeline does not come through here.** Firehose writes
+ * the table itself; this module exists for the one-shot `analytics backfill`
+ * action and is constructed only by that command. The dashboard's session is a
+ * different object with `readOnly: true`, so nothing the server can be asked
+ * to do reaches a writable connection.
+ *
+ * ## One day, one transaction
+ *
+ * `insertDay` is atomic by construction: `BEGIN TRANSACTION`, the day's rows,
+ * `COMMIT`. That is what makes the backfill's idempotency hold under a crash -
+ * a day is in the table or it is not, so the occupancy check the command runs
+ * before each day cannot see half of one and skip the rest. A failure rolls
+ * back and propagates: the command stops rather than carrying on to later
+ * days, because a run that reported five days inserted while one failed in the
+ * middle would leave an operator with no way to tell which history they have.
+ *
+ * The rows are batched into statements rather than sent one at a time, because
+ * a day of a blog's traffic is thousands of rows and one round trip each would
+ * make a backfill slower than the log read that feeds it. {@link
+ * INSERT_BATCH_ROWS} bounds the statement; every batch is inside the one
+ * transaction, so the batching is invisible to a reader of the table.
+ *
+ * ## Why the column list comes from `schema.ts`
+ *
+ * Every statement names all twenty columns in `PAGE_VIEWS_COLUMNS`' order and
+ * binds a value or a NULL for each, rather than naming only the columns a row
+ * happens to carry. Two reasons: a batch's rows do not all carry the same
+ * optional columns, so a per-row column list would mean a statement per row;
+ * and the cast each value is written through comes from the column's own
+ * `icebergType`, so a column added to the table is a column this module writes
+ * without being edited - the same property `map-record.ts` has on the read
+ * side.
+ */
+import type { CredentialProvider } from 'blogwright-core';
+import type { AnalyticsIngest } from '../ports.js';
+import { type DuckDbConnect, type DuckDbSessionContext } from './duckdb-session.js';
+/** What {@link createDuckDbAnalyticsIngest} is built from. */
+export interface DuckDbAnalyticsIngestOptions {
+    /**
+     * The plugin context. The session resolves the analytics config from it
+     * itself, so no caller can hand this adapter a bucket name that dropped the
+     * environment - the same seal the read adapter is held to, and it matters
+     * more here: a write against the wrong environment's table cannot be undone
+     * by re-running the command.
+     */
+    readonly ctx: DuckDbSessionContext;
+    /** Credentials for the catalog, resolved through core's provider chain. */
+    readonly credentials: CredentialProvider;
+    /**
+     * How a DuckDB connection is obtained. Defaults to the session's own
+     * `connectDuckDb`; a test substitutes a recording connection here.
+     */
+    readonly connect?: DuckDbConnect | undefined;
+}
+/**
+ * Build the DuckDB-backed {@link AnalyticsIngest}. Returns the port and
+ * nothing wider, so a caller can insert days and can neither run a statement
+ * of its own nor read the table back through it.
+ *
+ * The connection is opened lazily on the first insert, so constructing this at
+ * the plugin's composition root costs nothing on a run that refuses before it
+ * reaches the table - which is what the backfill's missing-`createdDay`
+ * refusal does.
+ */
+export declare function createDuckDbAnalyticsIngest(opts: DuckDbAnalyticsIngestOptions): AnalyticsIngest;

package/dist/adapters/duckdb-ingest.js

@@ -0,0 +1,173 @@
+/**
+ * The real {@link AnalyticsIngest}: DuckDB with the S3 Tables catalog attached
+ * writable, inserting one whole UTC day per transaction. It is the write half
+ * of the change spec's §Backfill of historical logs - "written through the
+ * DuckDB dependency the dashboard already ships, behind a write port of its
+ * own" - and it shares every part of the session with the read adapter beside
+ * it through `duckdb-session.ts`: the same credential secret, the same attach
+ * target, the same quoting and the same rule that no vendor error object
+ * escapes. The one clause that differs is `READ_ONLY`, which this session
+ * omits.
+ *
+ * **The steady-state pipeline does not come through here.** Firehose writes
+ * the table itself; this module exists for the one-shot `analytics backfill`
+ * action and is constructed only by that command. The dashboard's session is a
+ * different object with `readOnly: true`, so nothing the server can be asked
+ * to do reaches a writable connection.
+ *
+ * ## One day, one transaction
+ *
+ * `insertDay` is atomic by construction: `BEGIN TRANSACTION`, the day's rows,
+ * `COMMIT`. That is what makes the backfill's idempotency hold under a crash -
+ * a day is in the table or it is not, so the occupancy check the command runs
+ * before each day cannot see half of one and skip the rest. A failure rolls
+ * back and propagates: the command stops rather than carrying on to later
+ * days, because a run that reported five days inserted while one failed in the
+ * middle would leave an operator with no way to tell which history they have.
+ *
+ * The rows are batched into statements rather than sent one at a time, because
+ * a day of a blog's traffic is thousands of rows and one round trip each would
+ * make a backfill slower than the log read that feeds it. {@link
+ * INSERT_BATCH_ROWS} bounds the statement; every batch is inside the one
+ * transaction, so the batching is invisible to a reader of the table.
+ *
+ * ## Why the column list comes from `schema.ts`
+ *
+ * Every statement names all twenty columns in `PAGE_VIEWS_COLUMNS`' order and
+ * binds a value or a NULL for each, rather than naming only the columns a row
+ * happens to carry. Two reasons: a batch's rows do not all carry the same
+ * optional columns, so a per-row column list would mean a statement per row;
+ * and the cast each value is written through comes from the column's own
+ * `icebergType`, so a column added to the table is a column this module writes
+ * without being edited - the same property `map-record.ts` has on the read
+ * side.
+ */
+import { PAGE_VIEWS_COLUMNS } from '../schema.js';
+import { createDuckDbSession, quoteIdentifier, } from './duckdb-session.js';
+/**
+ * How many rows one `INSERT` statement carries. Chosen against the statement
+ * rather than against the data: twenty columns a row, so five hundred rows is
+ * ten thousand bound placeholders - large enough that a day of a blog's
+ * traffic is a handful of statements, small enough to stay well inside any
+ * parser's limits and to keep one failure's error message readable.
+ */
+const INSERT_BATCH_ROWS = 500;
+/** The SQL type each Iceberg column type is cast to on the way in. */
+const SQL_TYPES = {
+    string: 'VARCHAR',
+    timestamp: 'TIMESTAMP',
+    date: 'DATE',
+    int: 'INTEGER',
+    long: 'BIGINT',
+    double: 'DOUBLE',
+    boolean: 'BOOLEAN',
+};
+/** The column list every insert names, in the table's own order. */
+const COLUMN_LIST = PAGE_VIEWS_COLUMNS.map((column) => quoteIdentifier(column.name)).join(', ');
+/**
+ * The placeholder one row's column binds to. Row index and column name, so a
+ * batch's placeholders are unique and a failure's message points at a row
+ * rather than at a position.
+ */
+function placeholder(rowIndex, column) {
+    return `r${rowIndex}_${column}`;
+}
+/**
+ * One batch as a statement and its bindings: every column cast to the type
+ * `schema.ts` declares for it, and every absent optional column bound as NULL
+ * rather than omitted. An absent value is what "the request had nothing to say
+ * for this field" means, and it is exactly what the Firehose path writes for
+ * the same record.
+ */
+function insertStatement(relation, rows) {
+    const bindings = {};
+    const tuples = rows.map((row, rowIndex) => {
+        const values = PAGE_VIEWS_COLUMNS.map((column) => {
+            const name = placeholder(rowIndex, column.name);
+            const value = row[column.name];
+            bindings[name] = value === undefined ? null : value;
+            return `CAST($${name} AS ${SQL_TYPES[column.icebergType]})`;
+        });
+        return `(${values.join(', ')})`;
+    });
+    return {
+        sql: `INSERT INTO ${relation} (${COLUMN_LIST}) VALUES ${tuples.join(', ')}`,
+        bindings,
+    };
+}
+/** `rows` in chunks of at most {@link INSERT_BATCH_ROWS}. */
+function batched(rows) {
+    const batches = [];
+    for (let start = 0; start < rows.length; start += INSERT_BATCH_ROWS) {
+        batches.push(rows.slice(start, start + INSERT_BATCH_ROWS));
+    }
+    return batches;
+}
+/**
+ * Build the DuckDB-backed {@link AnalyticsIngest}. Returns the port and
+ * nothing wider, so a caller can insert days and can neither run a statement
+ * of its own nor read the table back through it.
+ *
+ * The connection is opened lazily on the first insert, so constructing this at
+ * the plugin's composition root costs nothing on a run that refuses before it
+ * reaches the table - which is what the backfill's missing-`createdDay`
+ * refusal does.
+ */
+export function createDuckDbAnalyticsIngest(opts) {
+    const session = createDuckDbSession({
+        ctx: opts.ctx,
+        credentials: opts.credentials,
+        readOnly: false,
+        connect: opts.connect,
+    });
+    function contextualise(day, err) {
+        return new Error(`analytics ingest of day ${day} into ${session.attachTarget} failed while ${session.detail(err, 'inserting the rows')}`);
+    }
+    return {
+        async insertDay(day, rows) {
+            // Both refusals are the port's documented contract, checked before a
+            // connection is opened so a caller's mistake costs no AWS round trip.
+            if (rows.length === 0) {
+                throw new Error(`analytics ingest was asked to insert day ${day} with no rows`);
+            }
+            const foreign = rows.find((row) => row.day !== day);
+            if (foreign !== undefined) {
+                throw new Error(`analytics ingest was asked to insert day ${day} carrying a row for day ${foreign.day}`);
+            }
+            let connection;
+            try {
+                connection = await session.open();
+            }
+            catch (err) {
+                throw contextualise(day, err);
+            }
+            try {
+                await session.step('beginning the transaction', () => connection.run('BEGIN TRANSACTION', {}));
+            }
+            catch (err) {
+                throw contextualise(day, err);
+            }
+            try {
+                for (const batch of batched(rows)) {
+                    const statement = insertStatement(session.relation, batch);
+                    await session.step('inserting the rows', () => connection.run(statement.sql, statement.bindings));
+                }
+                await session.step('committing the transaction', () => connection.run('COMMIT', {}));
+            }
+            catch (err) {
+                // Best effort, and deliberately not reported: the failure a caller
+                // needs to read is the one that ended the insert, not a second one
+                // raised while unwinding it. A rollback that itself fails leaves the
+                // connection unusable, which is why the command above stops at the
+                // first failing day rather than trying the next one on it.
+                try {
+                    await connection.run('ROLLBACK', {});
+                }
+                catch {
+                    /* the original failure is the one worth raising */
+                }
+                throw contextualise(day, err);
+            }
+        },
+    };
+}

package/dist/adapters/duckdb-query.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The real {@link AnalyticsQuery}: DuckDB with the S3 Tables catalog attached
+ * read-only. Everything about the session - the credential secret, the attach,
+ * the quoting and the translation of vendor errors - belongs to
+ * `duckdb-session.ts`, which the write adapter beside this one shares; what
+ * lives here is only what reading a named query adds to it.
+ *
+ * **Read-only is a property of the connection, not of this module's shape.**
+ * The session is built with `readOnly: true`, so the `ATTACH` carries
+ * `READ_ONLY` and DuckDB itself refuses a write on it. `AnalyticsQuery.run` is
+ * the whole surface this adapter returns, so there is no statement to supply
+ * and no write path to reach even before that.
+ */
+import type { CredentialProvider } from 'blogwright-core';
+import type { AnalyticsQuery } from '../ports.js';
+import { type PreparedQuery } from '../queries.js';
+import { type DuckDbConnect, type DuckDbSessionContext } from './duckdb-session.js';
+/** What {@link createDuckDbAnalyticsQuery} is built from. */
+export interface DuckDbAnalyticsQueryOptions {
+    /**
+     * The plugin context. The session resolves the analytics config from it
+     * itself: `tableBucket` is sealed under task 44's `ENV_DERIVED` symbol and
+     * `resolveAnalyticsConfig` is the only way to it, so no caller can hand this
+     * adapter a bucket name that dropped the environment.
+     */
+    readonly ctx: DuckDbSessionContext;
+    /**
+     * Credentials for the catalog, resolved through core's provider chain
+     * (`createCredentialProvider`). A test passes `staticCredentials`.
+     */
+    readonly credentials: CredentialProvider;
+    /**
+     * How a DuckDB connection is obtained. Defaults to the session's own
+     * `connectDuckDb`; a test substitutes a recording connection here.
+     */
+    readonly connect?: DuckDbConnect | undefined;
+}
+/**
+ * The statement a prepared query actually runs as: its definition's SQL with
+ * the fixed relation name rewritten to `relation`. Raises when a definition
+ * names no relation at all, because a statement that reads nothing would
+ * otherwise return an empty result that looks like "no traffic that week".
+ */
+export declare function bindPageViewsRelation(prepared: PreparedQuery, relation: string): string;
+/**
+ * Build the DuckDB-backed {@link AnalyticsQuery}. Returns the port and nothing
+ * wider: `run(name, params)` is the whole surface, so there is no statement to
+ * supply and no write path to reach. Construct it at the plugin's composition
+ * root - the dashboard, status and backfill commands - and hand every domain
+ * module the port.
+ *
+ * The connection is opened lazily on the first query and then reused, so
+ * building the adapter touches neither the network nor the native library, and
+ * the dashboard binds its port before AWS is ever consulted.
+ */
+export declare function createDuckDbAnalyticsQuery(opts: DuckDbAnalyticsQueryOptions): AnalyticsQuery;

package/dist/adapters/duckdb-query.js

@@ -0,0 +1,80 @@
+/**
+ * The real {@link AnalyticsQuery}: DuckDB with the S3 Tables catalog attached
+ * read-only. Everything about the session - the credential secret, the attach,
+ * the quoting and the translation of vendor errors - belongs to
+ * `duckdb-session.ts`, which the write adapter beside this one shares; what
+ * lives here is only what reading a named query adds to it.
+ *
+ * **Read-only is a property of the connection, not of this module's shape.**
+ * The session is built with `readOnly: true`, so the `ATTACH` carries
+ * `READ_ONLY` and DuckDB itself refuses a write on it. `AnalyticsQuery.run` is
+ * the whole surface this adapter returns, so there is no statement to supply
+ * and no write path to reach even before that.
+ */
+import { PAGE_VIEWS_RELATION, prepareQuery, } from '../queries.js';
+import { createDuckDbSession, } from './duckdb-session.js';
+/**
+ * {@link PAGE_VIEWS_RELATION} wherever a statement names it as a whole word.
+ * The word boundaries matter: `daily_page_views` must not match, and a bound
+ * relation contains the literal `page_views` inside its own quotes, which a
+ * replacement callback (rather than a replacement string) leaves alone.
+ */
+const PAGE_VIEWS_RELATION_PATTERN = new RegExp(String.raw `\b${PAGE_VIEWS_RELATION}\b`, 'g');
+/**
+ * The statement a prepared query actually runs as: its definition's SQL with
+ * the fixed relation name rewritten to `relation`. Raises when a definition
+ * names no relation at all, because a statement that reads nothing would
+ * otherwise return an empty result that looks like "no traffic that week".
+ */
+export function bindPageViewsRelation(prepared, relation) {
+    let bindings = 0;
+    const sql = prepared.sql.replaceAll(PAGE_VIEWS_RELATION_PATTERN, () => {
+        bindings += 1;
+        return relation;
+    });
+    if (bindings === 0) {
+        throw new Error(`analytics query "${prepared.name}" names no ${PAGE_VIEWS_RELATION} relation to bind, so it would read nothing`);
+    }
+    return sql;
+}
+/**
+ * Build the DuckDB-backed {@link AnalyticsQuery}. Returns the port and nothing
+ * wider: `run(name, params)` is the whole surface, so there is no statement to
+ * supply and no write path to reach. Construct it at the plugin's composition
+ * root - the dashboard, status and backfill commands - and hand every domain
+ * module the port.
+ *
+ * The connection is opened lazily on the first query and then reused, so
+ * building the adapter touches neither the network nor the native library, and
+ * the dashboard binds its port before AWS is ever consulted.
+ */
+export function createDuckDbAnalyticsQuery(opts) {
+    const session = createDuckDbSession({
+        ctx: opts.ctx,
+        credentials: opts.credentials,
+        readOnly: true,
+        connect: opts.connect,
+    });
+    function contextualise(name, err) {
+        return new Error(`analytics query "${name}" against ${session.attachTarget} failed while ${session.detail(err, 'running the query')}`);
+    }
+    return {
+        async run(name, params) {
+            const prepared = prepareQuery(name, params, session.config);
+            const sql = bindPageViewsRelation(prepared, session.relation);
+            let connection;
+            try {
+                connection = await session.open();
+            }
+            catch (err) {
+                throw contextualise(prepared.name, err);
+            }
+            try {
+                return await session.step('executing the statement', () => connection.run(sql, prepared.bindings));
+            }
+            catch (err) {
+                throw contextualise(prepared.name, err);
+            }
+        },
+    };
+}