@nitpicker/archive 0.0.0-stage → 0.25.0

package/lib/verify-migration/check-reader-parity.js

@@ -0,0 +1,182 @@
+import { MigrationVerificationError } from './types.js';
+/**
+ * Compares totals reported by 0.13 readers (which query the 0.13
+ * entity tables exclusively) against equivalent inline SQL against the
+ * still-present legacy write-model tables (`pages` / `anchors` / `images` /
+ * `resources` / `resources-referrers`). A mismatch here means either the
+ * 0.13 populates lost rows or one of the new reader implementations
+ * has a filter/predicate off-by-one relative to its legacy counterpart.
+ *
+ * This is deliberately lighter than the "byte-identical items array"
+ * verification issue #195 acceptance references — running every reader on
+ * every archive and diffing full result sets would balloon the migrator's
+ * runtime and require importing `@nitpicker/query` back into the crawler
+ * package (a dependency inversion). The seven totals below capture every
+ * reader whose scope was flagged in issue #195 and catch the classes of
+ * regression the 0.13 row-count invariants cannot: predicate drift
+ * inside a reader function (e.g. a `WHERE contentType='text/html'` filter
+ * silently swapping meaning between `pages.contentType` and
+ * `content_type_refs.raw`).
+ * @param trx - The open migration transaction.
+ * @throws {MigrationVerificationError} If any pair of totals disagrees.
+ */
+export async function checkReaderParity(trx) {
+    const checks = [
+        {
+            label: 'listPages default (scraped=1, redirect null, html-or-null)',
+            legacy: async () => scalar(trx('pages')
+                .where('scraped', 1)
+                .whereNull('redirectDestId')
+                .where((qb) => {
+                qb.where('isSkipped', 0).orWhereNull('isSkipped');
+            })
+                .where((qb) => {
+                qb.whereNull('contentType').orWhere('contentType', 'text/html');
+            })
+                .count({ count: '*' })),
+            current: async () => scalar(trx('content_items as ci')
+                .leftJoin('content_type_refs as ctr', 'ctr.id', 'ci.content_type_id')
+                .where('ci.scraped', 1)
+                .whereNull('ci.redirect_dest_id')
+                .where((qb) => {
+                qb.where('ci.is_skipped', 0).orWhereNull('ci.is_skipped');
+            })
+                .where((qb) => {
+                qb.whereNull('ctr.raw').orWhere('ctr.raw', 'text/html');
+            })
+                .count({ count: '*' })),
+        },
+        {
+            label: 'listImages total',
+            legacy: async () => scalar(trx('images').count({ count: '*' })),
+            current: async () => scalar(trx('image_items').count({ count: '*' })),
+        },
+        {
+            label: 'listResources total',
+            legacy: async () => scalar(trx('resources').count({ count: '*' })),
+            current: async () => scalar(trx('resource_items').count({ count: '*' })),
+        },
+        {
+            label: 'listLinks broken (status=404 through redirect)',
+            legacy: async () => scalar(trx('anchors')
+                .join('pages as dest', 'anchors.hrefId', 'dest.id')
+                .leftJoin('pages as canonical', 'dest.redirectDestId', 'canonical.id')
+                .whereRaw('COALESCE("canonical"."status", "dest"."status") = 404')
+                .count({ count: '*' })),
+            current: async () => scalar(trx('anchor_edges as ae')
+                .join('content_items as dest', 'ae.href_page_id', 'dest.id')
+                .leftJoin('content_items as canonical', 'dest.redirect_dest_id', 'canonical.id')
+                .whereRaw('COALESCE("canonical"."status", "dest"."status") = 404')
+                .sum({ count: 'ae.count' })),
+        },
+        {
+            label: 'checkHeaders scope (internal html scraped, no redirect)',
+            legacy: async () => scalar(trx('pages')
+                .where({ scraped: 1, isExternal: 0, contentType: 'text/html' })
+                .whereNull('redirectDestId')
+                .count({ count: '*' })),
+            current: async () => scalar(trx('content_items as ci')
+                .join('content_type_refs as ctr', 'ctr.id', 'ci.content_type_id')
+                .where({
+                'ci.scraped': 1,
+                'ci.is_external': 0,
+                'ctr.raw': 'text/html',
+            })
+                .whereNull('ci.redirect_dest_id')
+                .count({ count: '*' })),
+        },
+        {
+            label: 'findDuplicates(title) group count',
+            legacy: async () => scalar(trx
+                .count({ count: '*' })
+                .from(trx('pages')
+                .select('title')
+                .where({ scraped: 1, isExternal: 0, contentType: 'text/html' })
+                .whereNull('redirectDestId')
+                .whereNotNull('title')
+                .whereNot('title', '')
+                .groupBy('title')
+                .having(trx.raw('count(*) > 1'))
+                .as('g'))),
+            current: async () => scalar(trx.count({ count: '*' }).from(trx('content_items as ci')
+                .join('content_type_refs as ctr', 'ctr.id', 'ci.content_type_id')
+                .join('page_meta as pm', 'pm.page_id', 'ci.id')
+                .join('text_refs as tr', 'tr.id', 'pm.title_text_id')
+                .select('pm.title_text_id')
+                .where({
+                'ci.scraped': 1,
+                'ci.is_external': 0,
+                'ctr.raw': 'text/html',
+            })
+                .whereNull('ci.redirect_dest_id')
+                .whereNotNull('pm.title_text_id')
+                .whereNot('tr.text', '')
+                .groupBy('pm.title_text_id')
+                .having(trx.raw('count(*) > 1'))
+                .as('g'))),
+        },
+        {
+            label: 'findMismatches(canonical) count',
+            legacy: async () => scalar(trx('pages')
+                .where({ scraped: 1, isExternal: 0, contentType: 'text/html' })
+                .whereNull('redirectDestId')
+                .whereNotNull('canonical')
+                .whereNot('canonical', '')
+                .whereRaw('canonical != url')
+                .count({ count: '*' })),
+            current: async () => scalar(trx('content_items as ci')
+                .join('content_type_refs as ctr', 'ctr.id', 'ci.content_type_id')
+                .join('page_meta as pm', 'pm.page_id', 'ci.id')
+                .join('url_refs as canonical_ur', 'canonical_ur.id', 'pm.canonical_url_id')
+                .where({
+                'ci.scraped': 1,
+                'ci.is_external': 0,
+                'ctr.raw': 'text/html',
+            })
+                .whereNull('ci.redirect_dest_id')
+                .whereNotNull('pm.canonical_url_id')
+                .whereNot('canonical_ur.url', '')
+                .whereRaw('"pm"."canonical_url_id" != "ci"."url_id"')
+                .count({ count: '*' })),
+        },
+    ];
+    const failures = [];
+    // Zero-vs-zero cannot detect a "populate silently produced no rows"
+    // bug, so a check whose LEGACY side returns 0 is skipped rather than
+    // counted as pass — the parity check exists to catch predicate drift
+    // once both sides have rows to compare. `checkContentItemsCount` etc.
+    // already guard the "current is empty when legacy is not" direction
+    // upstream in {@link verifyMigration}.
+    let comparedChecks = 0;
+    for (const { label, legacy, current } of checks) {
+        const [legacyValue, currentValue] = await Promise.all([legacy(), current()]);
+        if (legacyValue === 0 && currentValue === 0) {
+            continue;
+        }
+        comparedChecks++;
+        if (legacyValue !== currentValue) {
+            failures.push(`${label}: legacy=${legacyValue}, current=${currentValue}`);
+        }
+    }
+    if (failures.length > 0) {
+        throw new MigrationVerificationError({
+            check: '#9 reader parity',
+            context: {
+                failures: failures.join('; '),
+                compared_checks: comparedChecks,
+            },
+        });
+    }
+}
+/**
+ * Extracts the single numeric value from a Knex `count()` / `sum()` result.
+ * SQLite returns strings for aggregate expressions; we coerce and treat
+ * `null` as `0` (an empty aggregate).
+ * @param queryBuilder - The pending Knex query that resolves to a single
+ *   aggregate row.
+ * @returns The aggregate value as a JS number.
+ */
+async function scalar(queryBuilder) {
+    const rows = (await queryBuilder);
+    return Number(rows[0]?.count ?? 0);
+}

package/lib/verify-migration/check-resource-items-count.d.ts

@@ -0,0 +1,17 @@
+import type { Knex } from 'knex';
+/**
+ * Verifies 0.13 invariant #6: every legacy `resources` row is mirrored
+ * by one row in `resource_items`.
+ *
+ * `populateResourceItems` fills `resource_items` with the same PK as
+ * `resources.id`
+ * (see `populate-resource-items.ts`); the invariant is broken only if the
+ * populate loop skipped rows during URL / header-set / content-type
+ * resolution. The paired invariant `resource_ref_edges = "resources-referrers"`
+ * is left unchecked here because issue #194's spec list stops at the
+ * six enumerated checks, and `resource_ref_edges` populate is a straight
+ * `INSERT … SELECT` (no dedup, no resolution) with negligible failure surface.
+ * @param trx - Knex instance or transaction connected to the populated archive.
+ * @throws {MigrationVerificationError} when the row counts diverge.
+ */
+export declare function checkResourceItemsCount(trx: Knex): Promise<void>;

package/lib/verify-migration/check-resource-items-count.js

@@ -0,0 +1,33 @@
+import { MigrationVerificationError } from './types.js';
+/**
+ * Verifies 0.13 invariant #6: every legacy `resources` row is mirrored
+ * by one row in `resource_items`.
+ *
+ * `populateResourceItems` fills `resource_items` with the same PK as
+ * `resources.id`
+ * (see `populate-resource-items.ts`); the invariant is broken only if the
+ * populate loop skipped rows during URL / header-set / content-type
+ * resolution. The paired invariant `resource_ref_edges = "resources-referrers"`
+ * is left unchecked here because issue #194's spec list stops at the
+ * six enumerated checks, and `resource_ref_edges` populate is a straight
+ * `INSERT … SELECT` (no dedup, no resolution) with negligible failure surface.
+ * @param trx - Knex instance or transaction connected to the populated archive.
+ * @throws {MigrationVerificationError} when the row counts diverge.
+ */
+export async function checkResourceItemsCount(trx) {
+    const resourceItemsRows = await trx('resource_items').count({
+        n: '*',
+    });
+    const resourcesRows = await trx('resources').count({ n: '*' });
+    const resourceItemsCount = Number(resourceItemsRows[0].n);
+    const resourcesCount = Number(resourcesRows[0].n);
+    if (resourceItemsCount !== resourcesCount) {
+        throw new MigrationVerificationError({
+            check: '#6 resource_items row count',
+            context: {
+                resource_items: resourceItemsCount,
+                resources: resourcesCount,
+            },
+        });
+    }
+}

package/lib/verify-migration/check-url-round-trip.d.ts

@@ -0,0 +1,43 @@
+import type { Knex } from 'knex';
+/**
+ * Verifies 0.13 invariant #8: `content_items.url_id → url_refs.url`
+ * round-trips back to the original `pages.url` on a deterministic
+ * ≤ {@link SAMPLE_SIZE} sample.
+ *
+ * A mismatch means one of two things:
+ *
+ * - `populate-url-refs.ts` collapsed two distinct URLs into the same
+ *   `url_refs.id` (BINARY collation bug, whitespace normalisation, …).
+ * - `populate-content-items.ts` associated a page id with the wrong
+ *   `url_ref.id` (row-order dependency in the batch resolver).
+ *
+ * Additionally an FK gap (`content_items.url_id` pointing at a
+ * non-existent `url_refs.id`) or a missing `pages` row surfaces as a
+ * `roundTripUrl` / `sourceUrl` of `null`; the check treats either as a
+ * round-trip failure. LEFT JOINs are used deliberately so orphan rows
+ * are observable — an INNER JOIN would silently drop them and let the
+ * bug the invariant is meant to catch slip through.
+ *
+ * Sampling is **deterministic**: stride = ⌈count(content_items) / N⌉
+ * gives approximately {@link SAMPLE_SIZE} rows spread across the id
+ * range for large archives, and the full table for archives with
+ * ≤ {@link SAMPLE_SIZE} rows. Deterministic sampling means the same
+ * archive always produces the same verdict; a random sample would let a
+ * failing archive pass on retry if the offending rows happen to fall
+ * outside the second draw.
+ *
+ * The check throws when the sampled row count is smaller than expected
+ * (LEFT JOINs may return `null` sides but never fewer rows than the
+ * driving `content_items` set — a shortfall means SQLite silently
+ * dropped rows we intended to inspect). "Expected" is a separate
+ * `COUNT(*)` against the same `(id % stride) = 0` predicate, not a
+ * `floor(total / stride)` estimate: `content_items.id` is copied
+ * verbatim from the legacy `pages.id`, which accumulates gaps over an
+ * archive's crawl history (redirect consolidation, deleted pages, …).
+ * A density estimate over-counts whenever the id range is sparser than
+ * `[1, total]`, which produced false-positive failures on real
+ * multi-thousand-page archives.
+ * @param trx - Knex instance or transaction connected to the populated archive.
+ * @throws {MigrationVerificationError} when at least one sampled URL does not round-trip.
+ */
+export declare function checkUrlRoundTrip(trx: Knex): Promise<void>;

package/lib/verify-migration/check-url-round-trip.js

@@ -0,0 +1,112 @@
+import { MigrationVerificationError } from './types.js';
+/**
+ * Sample size for the URL round-trip smoke test — a 1,000-row sample per
+ * issue #194.
+ * Not statistical coverage — URL normalisation bugs tend to be systematic
+ * (all rows with a particular scheme or host), so a modest evenly-spread
+ * sample catches them reliably.
+ */
+const SAMPLE_SIZE = 1000;
+/**
+ * Verifies 0.13 invariant #8: `content_items.url_id → url_refs.url`
+ * round-trips back to the original `pages.url` on a deterministic
+ * ≤ {@link SAMPLE_SIZE} sample.
+ *
+ * A mismatch means one of two things:
+ *
+ * - `populate-url-refs.ts` collapsed two distinct URLs into the same
+ *   `url_refs.id` (BINARY collation bug, whitespace normalisation, …).
+ * - `populate-content-items.ts` associated a page id with the wrong
+ *   `url_ref.id` (row-order dependency in the batch resolver).
+ *
+ * Additionally an FK gap (`content_items.url_id` pointing at a
+ * non-existent `url_refs.id`) or a missing `pages` row surfaces as a
+ * `roundTripUrl` / `sourceUrl` of `null`; the check treats either as a
+ * round-trip failure. LEFT JOINs are used deliberately so orphan rows
+ * are observable — an INNER JOIN would silently drop them and let the
+ * bug the invariant is meant to catch slip through.
+ *
+ * Sampling is **deterministic**: stride = ⌈count(content_items) / N⌉
+ * gives approximately {@link SAMPLE_SIZE} rows spread across the id
+ * range for large archives, and the full table for archives with
+ * ≤ {@link SAMPLE_SIZE} rows. Deterministic sampling means the same
+ * archive always produces the same verdict; a random sample would let a
+ * failing archive pass on retry if the offending rows happen to fall
+ * outside the second draw.
+ *
+ * The check throws when the sampled row count is smaller than expected
+ * (LEFT JOINs may return `null` sides but never fewer rows than the
+ * driving `content_items` set — a shortfall means SQLite silently
+ * dropped rows we intended to inspect). "Expected" is a separate
+ * `COUNT(*)` against the same `(id % stride) = 0` predicate, not a
+ * `floor(total / stride)` estimate: `content_items.id` is copied
+ * verbatim from the legacy `pages.id`, which accumulates gaps over an
+ * archive's crawl history (redirect consolidation, deleted pages, …).
+ * A density estimate over-counts whenever the id range is sparser than
+ * `[1, total]`, which produced false-positive failures on real
+ * multi-thousand-page archives.
+ * @param trx - Knex instance or transaction connected to the populated archive.
+ * @throws {MigrationVerificationError} when at least one sampled URL does not round-trip.
+ */
+export async function checkUrlRoundTrip(trx) {
+    const totalRows = await trx('content_items').count({ n: '*' });
+    const total = Number(totalRows[0].n);
+    if (total === 0) {
+        return;
+    }
+    // stride = ⌈total / SAMPLE_SIZE⌉ so `id % stride = 0` picks approximately
+    // SAMPLE_SIZE rows evenly across the id range for large archives, and the
+    // full table for archives ≤ SAMPLE_SIZE.
+    const stride = Math.max(1, Math.ceil(total / SAMPLE_SIZE));
+    const matchingRows = await trx('content_items')
+        .whereRaw('(id % ?) = 0', [stride])
+        .count({ n: '*' });
+    const expectedSize = Math.min(SAMPLE_SIZE, Number(matchingRows[0].n));
+    const sample = await trx('content_items as ci')
+        .leftJoin('pages as p', 'p.id', 'ci.id')
+        .leftJoin('url_refs as ur', 'ur.id', 'ci.url_id')
+        .select('ci.id as id', 'p.url as sourceUrl', 'ur.url as roundTripUrl')
+        .whereRaw('(ci.id % ?) = 0', [stride])
+        .orderBy('ci.id')
+        .limit(SAMPLE_SIZE);
+    if (sample.length < expectedSize) {
+        // LEFT JOINs preserve driving-table row counts (`p.id` / `url_refs.id`
+        // are PKs → 1:1 or 0:1 match). A shortfall means SQLite silently
+        // dropped rows the WHERE clause matched — a real integrity signal.
+        throw new MigrationVerificationError({
+            check: '#8 URL round-trip',
+            context: {
+                content_items_total: total,
+                stride,
+                expected_sample_size: expectedSize,
+                actual_sample_size: sample.length,
+                reason: 'sample query returned fewer rows than expected',
+            },
+        });
+    }
+    for (const row of sample) {
+        if (row.sourceUrl === null || row.roundTripUrl === null) {
+            throw new MigrationVerificationError({
+                check: '#8 URL round-trip',
+                context: {
+                    page_id: row.id,
+                    source_url: row.sourceUrl,
+                    round_trip_url: row.roundTripUrl,
+                    sample_size: sample.length,
+                    reason: 'orphan row — pages or url_refs join returned null (FK gap)',
+                },
+            });
+        }
+        if (row.sourceUrl !== row.roundTripUrl) {
+            throw new MigrationVerificationError({
+                check: '#8 URL round-trip',
+                context: {
+                    page_id: row.id,
+                    source_url: row.sourceUrl,
+                    round_trip_url: row.roundTripUrl,
+                    sample_size: sample.length,
+                },
+            });
+        }
+    }
+}

package/lib/verify-migration/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared type definitions for 0.13 migration verification.
+ *
+ * These are the acceptance-invariant checks that `scripts/migrate-to-0.13.mjs`
+ * runs at the end of the migration to confirm that the 0.13 entity /
+ * edge populates produced a consistent archive. Each check is one file
+ * under `verify-migration/` and throws {@link MigrationVerificationError} on mismatch;
+ * the orchestrator {@link ./verify-migration.ts} chains them in the
+ * order defined by issue #194.
+ * @module
+ */
+/**
+ * Row-count snapshot collected by every successful verify run and returned
+ * by {@link import('./verify-migration.js').verifyMigration}.
+ * The migration script logs these on the successful path so operators can
+ * eyeball migration outcomes from stdout without re-opening the archive.
+ */
+export interface MigrationVerificationSummary {
+    /** `count(*) FROM content_items` — matches `count(pages)`. */
+    readonly contentItems: number;
+    /** `count(*) FROM page_meta` — matches `count(pages WHERE scraped=1)`. */
+    readonly pageMeta: number;
+    /** `count(*) FROM anchor_edges` — always ≤ `count(anchors)`. */
+    readonly anchorEdges: number;
+    /** `SUM(count) FROM anchor_edges` — matches `count(anchors)`. */
+    readonly anchorEdgesSum: number;
+    /** `count(*) FROM image_items` — matches `count(images)`. */
+    readonly imageItems: number;
+    /** `count(*) FROM resource_items` — matches `count(resources)`. */
+    readonly resourceItems: number;
+}
+/**
+ * Structured details of a single migration invariant that failed. Attached to
+ * {@link MigrationVerificationError} so operators can see which check tripped
+ * without parsing the error message.
+ */
+export interface MigrationVerificationErrorDetails {
+    /**
+     * Human-readable check identifier matching issue #194's numbered list
+     * (e.g. `'#3'` for the anchor-edge dedup range check). Included in the
+     * error message so migration logs point at the exact clause.
+     */
+    readonly check: string;
+    /**
+     * Optional structured payload — typically `expected` / `actual` counts or
+     * the offending page id from the URL round-trip sample. Rendered into the
+     * error message so operators can diagnose without re-running the check.
+     */
+    readonly context?: Readonly<Record<string, string | number | null>>;
+}
+/**
+ * Error thrown by any 0.13 check when an invariant does not hold. The
+ * migration script catches this at the top level and aborts with a non-zero
+ * exit code; the enclosing transaction rolls back so the archive returns to
+ * its pre-populate state (ref tables from ref populate stay populated but are
+ * additive).
+ *
+ * Prefer a single error class with a structured {@link details} payload over
+ * one subclass per check: eight subclasses would create eight nearly
+ * identical constructors, and callers (script + integration test) only need
+ * to distinguish "verification failed" from other error kinds.
+ */
+export declare class MigrationVerificationError extends Error {
+    readonly details: MigrationVerificationErrorDetails;
+    /**
+     * @param details - Structured description of which check failed and why.
+     *   Rendered into the error message on construction.
+     */
+    constructor(details: MigrationVerificationErrorDetails);
+}

package/lib/verify-migration/types.js

@@ -0,0 +1,63 @@
+/**
+ * Shared type definitions for 0.13 migration verification.
+ *
+ * These are the acceptance-invariant checks that `scripts/migrate-to-0.13.mjs`
+ * runs at the end of the migration to confirm that the 0.13 entity /
+ * edge populates produced a consistent archive. Each check is one file
+ * under `verify-migration/` and throws {@link MigrationVerificationError} on mismatch;
+ * the orchestrator {@link ./verify-migration.ts} chains them in the
+ * order defined by issue #194.
+ * @module
+ */
+/**
+ * Error thrown by any 0.13 check when an invariant does not hold. The
+ * migration script catches this at the top level and aborts with a non-zero
+ * exit code; the enclosing transaction rolls back so the archive returns to
+ * its pre-populate state (ref tables from ref populate stay populated but are
+ * additive).
+ *
+ * Prefer a single error class with a structured {@link details} payload over
+ * one subclass per check: eight subclasses would create eight nearly
+ * identical constructors, and callers (script + integration test) only need
+ * to distinguish "verification failed" from other error kinds.
+ */
+export class MigrationVerificationError extends Error {
+    details;
+    /**
+     * @param details - Structured description of which check failed and why.
+     *   Rendered into the error message on construction.
+     */
+    constructor(details) {
+        const contextText = details.context === undefined
+            ? ''
+            : ' — ' +
+                Object.entries(details.context)
+                    .map(([key, value]) => 
+                // Render null as the parenthesised literal `(null)` so
+                // operators reading the log can distinguish "the sample
+                // query returned no rows" from a caller that passed the
+                // four-character string `"null"`. Strings get quoted for
+                // the same reason.
+                `${key}=${formatContextValue(value)}`)
+                    .join(', ');
+        super(`migration verification failed ${details.check}${contextText}`);
+        this.details = details;
+        this.name = 'MigrationVerificationError';
+    }
+}
+/**
+ * Renders one context value for {@link MigrationVerificationError}'s message.
+ * `null` becomes the literal `(null)`; strings are wrapped in double quotes;
+ * numbers pass through as their decimal representation. The intent is to
+ * make missing-vs-present distinguishable in operator logs.
+ * @param value - Value from `MigrationVerificationErrorDetails.context`.
+ */
+function formatContextValue(value) {
+    if (value === null) {
+        return '(null)';
+    }
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    return String(value);
+}

package/lib/verify-migration/verify-migration.d.ts

@@ -0,0 +1,41 @@
+import type { MigrationVerificationSummary } from './types.js';
+import type { Knex } from 'knex';
+/**
+ * Runs every 0.13 migration acceptance invariant against a populated archive and
+ * returns the verified row-count summary on success. The migration script
+ * (`scripts/migrate-to-0.13.mjs`) calls this **inside** the same
+ * `knex.transaction()` block that ran `populateEntityTables` so a thrown
+ * {@link MigrationVerificationError} rolls back the entire entity populate — ref
+ * tables from ref populate stay committed because they live in a separate, additive
+ * transaction and never lose facts on re-run.
+ *
+ * The returned {@link MigrationVerificationSummary} is echoed to stdout by the
+ * migration script so operators can eyeball migration outcomes (`did we lose
+ * rows silently within the invariant window?`) from batch pipeline logs
+ * without re-opening the archive. Callers must run this inside a `db.transaction()`
+ * for the counts and the JOIN-based checks (#7 / #8) to see a consistent
+ * snapshot of the archive.
+ *
+ * Checks run sequentially in issue #194's numbered order so error messages
+ * pinpoint the earliest broken invariant. Sequential (rather than parallel)
+ * execution keeps the failure diagnostics focused: fanning eight COUNTs out
+ * at once would return the first-completed rejection rather than the
+ * lowest-numbered one, which surprises operators reading migration logs.
+ * The individual COUNT queries are fast enough at any real archive scale
+ * for sequential wall-clock cost to be irrelevant.
+ *
+ * Non-{@link MigrationVerificationError} exceptions from a check (e.g. a
+ * transient libsql error or a schema-drift SqliteError) are wrapped in a
+ * {@link MigrationVerificationError} so the migration script's `catch` sees a
+ * uniform failure surface — otherwise operators grepping stderr for
+ * `migration verification failed` would miss driver-side errors.
+ * @param trx - Knex instance or transaction connected to the archive
+ *   **after** every 0.13 migration populate has run. Must be a transaction
+ *   in production so ref counts, JOIN samples, and error rollback see the
+ *   same snapshot; non-transactional callers (unit tests) work but do not
+ *   get snapshot isolation.
+ * @returns Row-count summary of the verified archive.
+ * @throws {MigrationVerificationError} on the first invariant that does not
+ *   hold; subsequent checks are skipped.
+ */
+export declare function verifyMigration(trx: Knex): Promise<MigrationVerificationSummary>;