@nitpicker/archive 0.0.0 → 0.25.1

package/lib/populate-ref-tables/upsert-one-header-set.js

@@ -0,0 +1,208 @@
+import { computeContentHash } from './compute-content-hash.js';
+import { computeHeaderFlags } from './compute-header-flags.js';
+import { headerValueCacheKey } from './header-value-cache-key.js';
+/**
+ * Rows inserted per INSERT statement into `header_set_entries`. Each row
+ * binds 5 params so 500 rows = 2500 params — safely under SQLite's
+ * default variable limit.
+ */
+const ENTRY_INSERT_CHUNK_SIZE = 500;
+/**
+ * Upserts one decomposed header set and its entries + flags, returning
+ * the `header_sets.id`. Shared by the bulk archive populate
+ * ({@link ./populate-header-tables.ts}) and the crawler's per-response
+ * write path, so both produce byte-identical header rows for the same
+ * raw `responseHeaders` value.
+ *
+ * Set-id resolution order:
+ *
+ * 1. `raw_json_hash` cache — same JSON key ordering as a previous row.
+ * 2. `raw_hash` cache — same sorted-entries identity, different JSON key
+ *    ordering. This branch links the new `raw_json_hash` to the existing
+ *    setId in the in-process map so subsequent same-JSON hits fast-path.
+ * 3. Otherwise INSERT a new `header_sets` row.
+ *
+ * Entries + flags are inserted once per `setId` per process (guarded by
+ * `setIdsProcessedThisRun`); already-inserted rows short-circuit
+ * cheaply, and preloaded-but-unprocessed setIds (partial prior run) get
+ * their entries / flags repaired via `INSERT OR IGNORE`.
+ * @param trx - Knex instance or transaction connected to the archive DB.
+ * @param decomposed - Result of `decomposeHeaderSet` (never `null` — the
+ *   caller short-circuits null decompositions to `header_set_id = null`).
+ * @param caches - The in-process caches, mutated in place. Create via
+ *   {@link ./create-header-table-caches.ts}.
+ * @returns The `header_sets.id` for this set.
+ * @example
+ * const decomposed = decomposeHeaderSet(rawJson);
+ * if (decomposed !== null) {
+ *   const setId = await upsertOneHeaderSet(knex, decomposed, caches);
+ * }
+ */
+export async function upsertOneHeaderSet(trx, decomposed, caches) {
+    const rawJsonHashHex = decomposed.rawJsonHash.toString('hex');
+    const rawHashHex = decomposed.rawHash.toString('hex');
+    let setId = caches.setIdByRawJsonHash.get(rawJsonHashHex);
+    if (setId === undefined) {
+        setId = caches.setIdByRawHash.get(rawHashHex);
+        if (setId === undefined) {
+            setId = await insertHeaderSet(trx, decomposed);
+            caches.setIdByRawJsonHash.set(rawJsonHashHex, setId);
+            caches.setIdByRawHash.set(rawHashHex, setId);
+        }
+        else {
+            // Same sorted-entries identity as an existing row, different JSON
+            // key ordering. Reuse the existing setId; the raw_json_hash of
+            // this variant has no persistent home in the 0.13 schema
+            // (raw_json_hash is UNIQUE per row) — linking it in the
+            // in-process map is enough for id resolution.
+            caches.setIdByRawJsonHash.set(rawJsonHashHex, setId);
+        }
+    }
+    if (caches.setIdsProcessedThisRun.has(setId)) {
+        return setId;
+    }
+    const nameIds = await resolveNameIds(trx, decomposed.entries, caches.nameIdCache);
+    const valueIds = await resolveValueIds(trx, decomposed.entries, caches.valueIdCache);
+    const entryRows = decomposed.entries.map((entry, index) => ({
+        header_set_id: setId,
+        name_id: nameIds[index],
+        occurrence: entry.occurrence,
+        value_id: valueIds[index],
+        is_volatile: entry.isVolatile ? 1 : 0,
+    }));
+    for (let index = 0; index < entryRows.length; index += ENTRY_INSERT_CHUNK_SIZE) {
+        const chunk = entryRows.slice(index, index + ENTRY_INSERT_CHUNK_SIZE);
+        await trx('header_set_entries')
+            .insert(chunk)
+            .onConflict(['header_set_id', 'name_id', 'occurrence'])
+            .ignore();
+    }
+    const flags = computeHeaderFlags(decomposed.entries);
+    await trx('header_flags')
+        .insert({ header_set_id: setId, ...flags })
+        .onConflict('header_set_id')
+        .ignore();
+    caches.setIdsProcessedThisRun.add(setId);
+    return setId;
+}
+/**
+ * Inserts a new `header_sets` row and returns its id. Neither
+ * `raw_json_hash` nor `raw_hash` collided with an existing row when
+ * this is called — the caller has already checked both caches.
+ * @param trx - Knex instance.
+ * @param decomposed - Result of `decomposeHeaderSet`.
+ * @returns The newly-inserted `header_sets.id`.
+ */
+async function insertHeaderSet(trx, decomposed) {
+    const rows = await trx('header_sets')
+        .insert({
+        raw_json_hash: decomposed.rawJsonHash,
+        raw_hash: decomposed.rawHash,
+        stable_hash: decomposed.stableHash,
+        volatile_hash: decomposed.volatileHash,
+        entry_count: decomposed.entryCount,
+        stable_entry_count: decomposed.stableEntryCount,
+    })
+        .returning('id');
+    const first = rows[0];
+    if (first === undefined) {
+        throw new Error('upsertOneHeaderSet: header_sets INSERT returned no rows despite absent conflict');
+    }
+    return first.id;
+}
+/**
+ * Resolves the `name_id` for every entry in `entries`, inserting new
+ * names into `header_name_refs` as needed. Mutates `cache` with any new
+ * ids.
+ * @param trx - Knex instance.
+ * @param entries - Decomposed entries.
+ * @param cache - Name → id cache; mutated in place.
+ * @returns Parallel array of name ids (same order as `entries`).
+ */
+async function resolveNameIds(trx, entries, cache) {
+    const missing = new Set();
+    for (const entry of entries) {
+        if (!cache.has(entry.name)) {
+            missing.add(entry.name);
+        }
+    }
+    if (missing.size > 0) {
+        const missingNames = [...missing];
+        // Chunked like the entries insert below: knex compiles a multi-row
+        // insert-with-onConflict into a compound SELECT, and SQLite rejects
+        // more than 500 compound terms per statement.
+        for (let index = 0; index < missingNames.length; index += ENTRY_INSERT_CHUNK_SIZE) {
+            const chunk = missingNames.slice(index, index + ENTRY_INSERT_CHUNK_SIZE);
+            await trx('header_name_refs')
+                .insert(chunk.map((name) => ({ name })))
+                .onConflict('name')
+                .ignore();
+            const inserted = await trx('header_name_refs')
+                .select('id', 'name')
+                .whereIn('name', chunk);
+            for (const row of inserted) {
+                cache.set(row.name, row.id);
+            }
+        }
+    }
+    return entries.map((entry) => {
+        const id = cache.get(entry.name);
+        if (id === undefined) {
+            throw new Error(`upsertOneHeaderSet: name_id not resolved for ${entry.name}`);
+        }
+        return id;
+    });
+}
+/**
+ * Resolves the `value_id` for every entry in `entries`, inserting new
+ * values into `header_value_refs` as needed. Values are hashed once and
+ * deduped by `(hash, value)` per the 0.13 UNIQUE constraint.
+ *
+ * The read-back after INSERT narrows on `.whereIn('value', ...)` — the
+ * string values just written — instead of binding the Buffer hashes into
+ * a `WHERE hash IN (...)`: a Buffer[] IN would return the correct rows
+ * in theory but leans on libsql's BLOB-parameter round-trip behaviour,
+ * while string values compare reliably. The cache key still includes the
+ * hash, so hash-distinct entries stay disambiguated.
+ * @param trx - Knex instance.
+ * @param entries - Decomposed entries.
+ * @param cache - `hexHash|value → id` cache; mutated in place.
+ * @returns Parallel array of value ids (same order as `entries`).
+ */
+async function resolveValueIds(trx, entries, cache) {
+    const hashByEntryIndex = entries.map((entry) => computeContentHash(entry.value));
+    const missing = [];
+    const missingKeys = new Set();
+    for (const [i, entry] of entries.entries()) {
+        const hash = hashByEntryIndex[i];
+        const key = headerValueCacheKey(hash, entry.value);
+        if (!cache.has(key) && !missingKeys.has(key)) {
+            missing.push({ key, hash, value: entry.value });
+            missingKeys.add(key);
+        }
+    }
+    // Chunked like the entries insert: knex compiles a multi-row
+    // insert-with-onConflict into a compound SELECT, and SQLite rejects
+    // more than 500 compound terms per statement.
+    for (let index = 0; index < missing.length; index += ENTRY_INSERT_CHUNK_SIZE) {
+        const chunk = missing.slice(index, index + ENTRY_INSERT_CHUNK_SIZE);
+        await trx('header_value_refs')
+            .insert(chunk.map(({ hash, value }) => ({ hash, value })))
+            .onConflict(['hash', 'value'])
+            .ignore();
+        const inserted = await trx('header_value_refs')
+            .select('id', 'hash', 'value')
+            .whereIn('value', chunk.map((m) => m.value));
+        for (const row of inserted) {
+            cache.set(headerValueCacheKey(Buffer.from(row.hash), row.value), row.id);
+        }
+    }
+    return entries.map((entry, i) => {
+        const key = headerValueCacheKey(hashByEntryIndex[i], entry.value);
+        const id = cache.get(key);
+        if (id === undefined) {
+            throw new Error(`upsertOneHeaderSet: value_id not resolved for ${entry.value.slice(0, 40)}…`);
+        }
+        return id;
+    });
+}

package/lib/populate-ref-tables/volatile-header-names.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Header names — always lower-cased — that are EXCLUDED from `stable_hash`.
+ * These change on every response (timestamps / request IDs / cache
+ * telemetry) and would defeat the dedup goal if hashed alongside the
+ * stable set.
+ *
+ * `set-cookie` sits here because per-session cookies rotate constantly on
+ * authenticated sites — it is deliberately classified as volatile even
+ * though it is technically a stable security signal.
+ *
+ * Any header not in this set is
+ * treated as **stable** by {@link ./header-stability.ts:isVolatileHeader}
+ * — the safer default because a genuinely volatile header misclassified
+ * as stable only weakens dedup (its per-response values fork
+ * otherwise-identical stable profiles into separate `stable_hash`
+ * clusters), while a stable header misclassified as volatile would drop
+ * a meaningful signal from `stable_hash` and falsely cluster distinct
+ * header configurations together.
+ */
+export declare const VOLATILE_HEADER_NAMES: ReadonlySet<string>;

package/lib/populate-ref-tables/volatile-header-names.js

@@ -0,0 +1,33 @@
+/**
+ * Header names — always lower-cased — that are EXCLUDED from `stable_hash`.
+ * These change on every response (timestamps / request IDs / cache
+ * telemetry) and would defeat the dedup goal if hashed alongside the
+ * stable set.
+ *
+ * `set-cookie` sits here because per-session cookies rotate constantly on
+ * authenticated sites — it is deliberately classified as volatile even
+ * though it is technically a stable security signal.
+ *
+ * Any header not in this set is
+ * treated as **stable** by {@link ./header-stability.ts:isVolatileHeader}
+ * — the safer default because a genuinely volatile header misclassified
+ * as stable only weakens dedup (its per-response values fork
+ * otherwise-identical stable profiles into separate `stable_hash`
+ * clusters), while a stable header misclassified as volatile would drop
+ * a meaningful signal from `stable_hash` and falsely cluster distinct
+ * header configurations together.
+ */
+export const VOLATILE_HEADER_NAMES = new Set([
+    'date',
+    'expires',
+    'last-modified',
+    'etag',
+    'age',
+    'via',
+    'x-cache',
+    'cf-ray',
+    'x-request-id',
+    'set-cookie',
+    'server-timing',
+    'x-amz-request-id',
+]);

package/lib/redirect-table.d.ts

@@ -0,0 +1,9 @@
+import type { Knex } from 'knex';
+/**
+ * Returns a Knex subquery builder that joins `content_items` with their
+ * redirect destinations (resolved via `url_refs` for both sides). When
+ * `includeNull` is true, also includes pages without redirects
+ * (self-referencing).
+ * @param includeNull - Whether to include non-redirected pages in the result. Defaults to `true`.
+ */
+export declare function redirectTable(includeNull?: boolean): (qb: Knex.QueryBuilder<Record<string, unknown>, unknown>) => Promise<void>;

package/lib/redirect-table.js

@@ -0,0 +1,28 @@
+/**
+ * Returns a Knex subquery builder that joins `content_items` with their
+ * redirect destinations (resolved via `url_refs` for both sides). When
+ * `includeNull` is true, also includes pages without redirects
+ * (self-referencing).
+ * @param includeNull - Whether to include non-redirected pages in the result. Defaults to `true`.
+ */
+export function redirectTable(includeNull = true) {
+    return async (qb) => {
+        const list = qb
+            .select('A.id as fromId', 'A_url.url as from', 'B_url.url as to', 'B.id as toId')
+            .from('content_items as A')
+            .join('url_refs as A_url', 'A.url_id', 'A_url.id')
+            .join('content_items as B', (j) => {
+            j.on('A.redirect_dest_id', '=', 'B.id').andOnNotNull('A.redirect_dest_id');
+        })
+            .join('url_refs as B_url', 'B.url_id', 'B_url.id');
+        if (includeNull) {
+            await list.union(async (qb) => {
+                await qb
+                    .select('A.id as fromId', 'A_url.url as from', 'A_url.url as to', 'A.id as toId')
+                    .from('content_items as A')
+                    .join('url_refs as A_url', 'A.url_id', 'A_url.id')
+                    .whereNull('A.redirect_dest_id');
+            });
+        }
+    };
+}

package/lib/release-finished-statements.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Gives the event loop one turn so that the native memory of SQL statements
+ * that already finished is freed before the next statement runs.
+ *
+ * The libsql binding (`libsql-dialect.ts` runs Knex on it) keeps each
+ * statement's compiled program and bound values, and a `SELECT`'s row cursor
+ * with its in-memory sort / `GROUP BY` tree, until the JavaScript wrapper
+ * object is finalized. Node runs those N-API finalizers from a `setImmediate`,
+ * not inside garbage collection itself, so a loop that only ever awaits
+ * synchronous libsql calls (every Knex call on this driver resolves through
+ * promise microtasks, never through the macrotask queue) can collect the
+ * wrappers and still release nothing: the finalizers wait for a turn of the
+ * loop that the loop never gets. Measured on the viewer read model build
+ * (one transaction, one statement per 500-row chunk): the native side grew by
+ * hundreds of MiB per bulk-insert phase and only shrank at `COMMIT`; forcing
+ * garbage collection after every chunk did not change that, one turn of the
+ * event loop after every chunk did. `scripts/bench-read-model-build.mjs`
+ * reproduces both sides of that with `--gc` and `--regions` (see
+ * `scripts/README.md`).
+ *
+ * The rule for callers: a loop that runs statements awaits this once per
+ * iteration, after the iteration's statements. An iteration may run more
+ * than one statement (a chunk's `INSERT` and the upsert derived from it); the
+ * turn at its end releases all of them, and a statement that runs once
+ * outside any loop is released by the next loop's turn.
+ *
+ * Why not reuse one prepared statement per table instead: the row cursors of
+ * chunked `SELECT`s hold their sort trees the same way, and every bulk path
+ * goes through Knex, which prepares a new statement per call. One turn per
+ * iteration covers both, costs microseconds, and changes no SQL.
+ *
+ * Why not in `libsql-dialect.ts` for every query: a transaction that yields
+ * between statements is fine for the archive (one connection, no
+ * interleaving), but every caller would pay the turn, including per-request
+ * viewer queries that run one statement and hold nothing worth a turn.
+ * @example
+ * for (const chunk of chunks) {
+ *   await trx('viewer_pages').insert(chunk);
+ *   await releaseFinishedStatements();
+ * }
+ */
+export declare function releaseFinishedStatements(): Promise<void>;

package/lib/release-finished-statements.js

@@ -0,0 +1,45 @@
+import { setImmediate as nextTurn } from 'node:timers/promises';
+/**
+ * Gives the event loop one turn so that the native memory of SQL statements
+ * that already finished is freed before the next statement runs.
+ *
+ * The libsql binding (`libsql-dialect.ts` runs Knex on it) keeps each
+ * statement's compiled program and bound values, and a `SELECT`'s row cursor
+ * with its in-memory sort / `GROUP BY` tree, until the JavaScript wrapper
+ * object is finalized. Node runs those N-API finalizers from a `setImmediate`,
+ * not inside garbage collection itself, so a loop that only ever awaits
+ * synchronous libsql calls (every Knex call on this driver resolves through
+ * promise microtasks, never through the macrotask queue) can collect the
+ * wrappers and still release nothing: the finalizers wait for a turn of the
+ * loop that the loop never gets. Measured on the viewer read model build
+ * (one transaction, one statement per 500-row chunk): the native side grew by
+ * hundreds of MiB per bulk-insert phase and only shrank at `COMMIT`; forcing
+ * garbage collection after every chunk did not change that, one turn of the
+ * event loop after every chunk did. `scripts/bench-read-model-build.mjs`
+ * reproduces both sides of that with `--gc` and `--regions` (see
+ * `scripts/README.md`).
+ *
+ * The rule for callers: a loop that runs statements awaits this once per
+ * iteration, after the iteration's statements. An iteration may run more
+ * than one statement (a chunk's `INSERT` and the upsert derived from it); the
+ * turn at its end releases all of them, and a statement that runs once
+ * outside any loop is released by the next loop's turn.
+ *
+ * Why not reuse one prepared statement per table instead: the row cursors of
+ * chunked `SELECT`s hold their sort trees the same way, and every bulk path
+ * goes through Knex, which prepares a new statement per call. One turn per
+ * iteration covers both, costs microseconds, and changes no SQL.
+ *
+ * Why not in `libsql-dialect.ts` for every query: a transaction that yields
+ * between statements is fine for the archive (one connection, no
+ * interleaving), but every caller would pay the turn, including per-request
+ * viewer queries that run one statement and hold nothing worth a turn.
+ * @example
+ * for (const chunk of chunks) {
+ *   await trx('viewer_pages').insert(chunk);
+ *   await releaseFinishedStatements();
+ * }
+ */
+export async function releaseFinishedStatements() {
+    await nextTurn();
+}

package/lib/resolve-redirect-chain.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The destination of a redirect chain and the source URLs that point at it.
+ */
+export interface RedirectChain {
+    /** The final destination URL the chain lands on (normalised). */
+    destUrl: string;
+    /**
+     * The source URLs that redirect to {@link RedirectChain.destUrl}: the originally requested
+     * URL followed by every intermediate hop. Empty when the page was not
+     * redirected at all.
+     */
+    sources: string[];
+}
+/**
+ * Splits a page's redirect chain into its final destination and the list of
+ * source URLs that point at it.
+ *
+ * The archive stores redirects as edges: every source URL carries a
+ * `redirectDestId` pointing at the destination page, and only the destination
+ * holds content. This helper applies the shared convention — the last entry of
+ * `redirectPaths` is the destination, while the originally requested URL plus
+ * every intermediate hop are the sources. When the page was not redirected,
+ * the destination is the page URL itself and there are no sources.
+ *
+ * Used by both `Database.updatePage` (which renders and stores the
+ * destination) and `Database.recordRedirect` (the #73 convergence
+ * optimisation, which records the edge for a destination already rendered
+ * elsewhere without touching its content).
+ * @param pageUrl - The originally requested URL (normalised, without hash/auth).
+ * @param redirectPaths - The redirect hop URLs captured during fetch, in order.
+ * @returns The destination URL and the source URLs pointing to it.
+ */
+export declare function resolveRedirectChain(pageUrl: string, redirectPaths: readonly string[]): RedirectChain;

package/lib/resolve-redirect-chain.js

@@ -0,0 +1,27 @@
+/**
+ * Splits a page's redirect chain into its final destination and the list of
+ * source URLs that point at it.
+ *
+ * The archive stores redirects as edges: every source URL carries a
+ * `redirectDestId` pointing at the destination page, and only the destination
+ * holds content. This helper applies the shared convention — the last entry of
+ * `redirectPaths` is the destination, while the originally requested URL plus
+ * every intermediate hop are the sources. When the page was not redirected,
+ * the destination is the page URL itself and there are no sources.
+ *
+ * Used by both `Database.updatePage` (which renders and stores the
+ * destination) and `Database.recordRedirect` (the #73 convergence
+ * optimisation, which records the edge for a destination already rendered
+ * elsewhere without touching its content).
+ * @param pageUrl - The originally requested URL (normalised, without hash/auth).
+ * @param redirectPaths - The redirect hop URLs captured during fetch, in order.
+ * @returns The destination URL and the source URLs pointing to it.
+ */
+export function resolveRedirectChain(pageUrl, redirectPaths) {
+    if (redirectPaths.length === 0) {
+        return { destUrl: pageUrl, sources: [] };
+    }
+    const paths = [...redirectPaths];
+    const destUrl = paths.pop();
+    return { destUrl, sources: [pageUrl, ...paths] };
+}

package/lib/resource.d.ts

@@ -0,0 +1,46 @@
+import type { ArchiveAccessor } from './archive-accessor.js';
+import type { DB_Resource } from './types.js';
+/**
+ * Represents a sub-resource (CSS, JS, image, font, etc.) stored in the archive.
+ *
+ * Provides access to the resource's HTTP metadata and referrer information.
+ * Instances are created by {@link ArchiveAccessor.getResources}.
+ */
+export default class Resource {
+    #private;
+    /**
+     * The content length of the resource in bytes, or null if unknown.
+     */
+    get contentLength(): number | null;
+    /**
+     * The MIME content type of the resource (e.g., `"text/css"`, `"application/javascript"`), or null if unknown.
+     */
+    get contentType(): string | null;
+    /**
+     * Whether this resource is hosted on an external domain.
+     */
+    get isExternal(): boolean;
+    /**
+     * The HTTP response status code, or null if not yet fetched.
+     */
+    get status(): number | null;
+    /**
+     * The HTTP response status text (e.g., `"OK"`, `"Not Found"`), or null if not yet fetched.
+     */
+    get statusText(): string | null;
+    /**
+     * The URL of the resource.
+     */
+    get url(): string | null;
+    /**
+     * Creates a new Resource instance.
+     * @param archive - The ArchiveAccessor used for querying referrer data.
+     * @param raw - The raw database row for this resource.
+     */
+    constructor(archive: ArchiveAccessor, raw: DB_Resource);
+    /**
+     * Retrieves the page URLs that reference this resource.
+     * @returns An array of page URL strings that include or reference this resource.
+     */
+    getReferrers(): Promise<string[]>;
+}

package/lib/resource.js

@@ -0,0 +1,62 @@
+/**
+ * Represents a sub-resource (CSS, JS, image, font, etc.) stored in the archive.
+ *
+ * Provides access to the resource's HTTP metadata and referrer information.
+ * Instances are created by {@link ArchiveAccessor.getResources}.
+ */
+export default class Resource {
+    #archive;
+    #raw;
+    /**
+     * The content length of the resource in bytes, or null if unknown.
+     */
+    get contentLength() {
+        return this.#raw.contentLength;
+    }
+    /**
+     * The MIME content type of the resource (e.g., `"text/css"`, `"application/javascript"`), or null if unknown.
+     */
+    get contentType() {
+        return this.#raw.contentType;
+    }
+    /**
+     * Whether this resource is hosted on an external domain.
+     */
+    get isExternal() {
+        return !!this.#raw.isExternal;
+    }
+    /**
+     * The HTTP response status code, or null if not yet fetched.
+     */
+    get status() {
+        return this.#raw.status;
+    }
+    /**
+     * The HTTP response status text (e.g., `"OK"`, `"Not Found"`), or null if not yet fetched.
+     */
+    get statusText() {
+        return this.#raw.statusText;
+    }
+    /**
+     * The URL of the resource.
+     */
+    get url() {
+        return this.#raw.url;
+    }
+    /**
+     * Creates a new Resource instance.
+     * @param archive - The ArchiveAccessor used for querying referrer data.
+     * @param raw - The raw database row for this resource.
+     */
+    constructor(archive, raw) {
+        this.#archive = archive;
+        this.#raw = raw;
+    }
+    /**
+     * Retrieves the page URLs that reference this resource.
+     * @returns An array of page URL strings that include or reference this resource.
+     */
+    async getReferrers() {
+        return this.#archive.getReferrersOfResource(this.#raw.id);
+    }
+}

package/lib/retarget-legacy-fk-tables.d.ts

@@ -0,0 +1,61 @@
+import type { Knex } from 'knex';
+/**
+ * Rewrites the FK declarations of the adjunct tables from the legacy
+ * `pages(id)` to `content_items(id)` by rebuilding each table, converts
+ * `page_tags` (if present) into `technology_signals` / `page_technologies`,
+ * AND drops the legacy `analysis_violations` / `analysis_text_refs` tables
+ * (analyze output that that no reader or writer uses).
+ * SQLite has no `ALTER TABLE … DROP CONSTRAINT`, so the only way to change
+ * an FK target is to recreate the table:
+ *
+ * 1. Stage each {@link RETARGET_TABLES} table's rows into a constraint-free
+ *    `<table>__retarget` copy (`CREATE TABLE … AS SELECT *`) and drop the
+ *    original, freeing its index names. `page_tags`, if present, is read
+ *    into memory here too (converted via `convertLegacyPageTagsToInserts` —
+ *    the same helper `migrate-page-tags-to-page-technologies.ts` uses for
+ *    already-0.13+ archives) but NOT staged the same way: it has no
+ *    current-schema table to retarget onto, so there is nothing to copy
+ *    back — only something to drop, once its data lives in the tables
+ *    from step 2.
+ * 2. Recreate every {@link RETARGET_TABLES} table through
+ *    {@link createAdjunctTables} — the same DDL fresh archives get, so
+ *    migrated archives end up identical in shape and index naming.
+ *    Rebuilding the DDL inline here instead would recreate the exact
+ *    drift this function repairs. This same call also creates
+ *    `technology_signals` / `page_technologies` (idempotent
+ *    `hasTable`-guarded DDL — a no-op if a prior partial run already
+ *    created them).
+ * 3. Copy the staged {@link RETARGET_TABLES} rows back using the recreated
+ *    table's own column list (read via `pragma_table_info`). A column the
+ *    canonical DDL has but the input archive lacks aborts the INSERT with
+ *    a clear error — never a silent data drop. The converted `page_tags`
+ *    signals/technologies are inserted here too, then `page_tags` itself
+ *    is dropped (not recreated).
+ *
+ * A rename-based recipe (`ALTER TABLE x RENAME TO x__retarget`, skip
+ * copy #1) is deliberately NOT used: SQLite keeps the renamed table's
+ * indexes attached under their original names, which collide with the
+ * index names {@link createAdjunctTables} declares — and the old index
+ * names vary by the era of the archive's original provisioning, so
+ * dropping them first would require enumerating unknown names. The
+ * copy-out is cheap at these tables' scale (a handful of rows per page).
+ *
+ * Adjunct tables that do not exist on the input archive are simply created
+ * empty by step 2.
+ *
+ * The migrated-archive PK-preservation contract makes the copy safe:
+ * `content_items.id` reuses the legacy `pages.id` values verbatim, so
+ * every staged `pageId` / `page_id` resolves to the same row under the
+ * new FK target. Run inside a transaction with `PRAGMA foreign_keys = ON`
+ * so the copy-back doubles as a row-level FK validation — a stale id
+ * aborts the transaction here rather than surfacing later as a
+ * `foreign_key_check` finding.
+ * @param trx - Knex transaction on the archive being migrated
+ *   (`scripts/migrate-to-0.13.mjs` is the caller).
+ * @example
+ * await db.transaction(async (trx) => {
+ *   await retargetLegacyFkTables(trx);
+ * });
+ * // pragma_foreign_key_list('page_errors') now reports content_items.
+ */
+export declare function retargetLegacyFkTables(trx: Knex): Promise<void>;