@nitpicker/crawler 0.11.0 → 0.13.0

package/lib/archive/test-utils/setup-legacy-fk-db.js

@@ -0,0 +1,270 @@
+/**
+ * Provisions the pre-0.13 legacy table shape on a test database:
+ * the five legacy write-model tables (`pages` / `anchors` / `images` /
+ * `resources` / `resources-referrers`) plus the five adjunct tables in
+ * their old form whose FK columns still point at `pages(id)`
+ * (`page_html_ref` / `page_tags` / `page_jsonld` / `page_errors` /
+ * `analysis_violations`, with their companion tables `page_html_blobs` /
+ * `analysis_text_refs`).
+ *
+ * `initSchema` no longer creates any of these shapes — fresh archives get
+ * neither the legacy write-model tables nor `pages(id)`-referencing
+ * adjunct tables — so specs that exercise the migration input format
+ * (`scripts/migrate-to-0.13.mjs` integration, `retargetLegacyFkTables`,
+ * `dropLegacyTables`) build it through this helper instead. The DDL is a
+ * verbatim copy of what pre-0.13 archives actually contain: the legacy
+ * write-model tables match the pre-0.13 `initSchema`, and the adjunct
+ * tables match the `scripts/migrate-to-0.10.mjs` / lazy-runtime-migration
+ * output of that era.
+ *
+ * Any current-form adjunct tables already present (e.g. created by
+ * `Archive.create()` on the current schema) are dropped first so the
+ * old-FK versions can take their place — callers get a deterministic
+ * "genuine pre-0.13 archive" shape regardless of how the underlying DB
+ * was provisioned.
+ * @param db - Knex connected to the test DB (or a transaction).
+ * @example
+ * await createRefTables(db);
+ * await createEntityTables(db);
+ * await setupLegacyFkDb(db);
+ * await db('pages').insert({ url: 'https://example.com/', scraped: 1, isTarget: 1 });
+ */
+export async function setupLegacyFkDb(db) {
+    // Children before parents so the drops never trip FK enforcement
+    // when the caller has `PRAGMA foreign_keys = ON`.
+    await db.raw('DROP TABLE IF EXISTS "page_html_ref"');
+    await db.raw('DROP TABLE IF EXISTS "page_html_blobs"');
+    await db.raw('DROP TABLE IF EXISTS "analysis_violations"');
+    await db.raw('DROP TABLE IF EXISTS "analysis_text_refs"');
+    await db.raw('DROP TABLE IF EXISTS "page_tags"');
+    await db.raw('DROP TABLE IF EXISTS "page_jsonld"');
+    await db.raw('DROP TABLE IF EXISTS "page_errors"');
+    await db.schema
+        .createTable('pages', (t) => {
+        t.increments('id');
+        t.string('url', 8190).notNullable().unique();
+        t.integer('redirectDestId').unsigned().references('pages.id').defaultTo(null);
+        t.boolean('scraped').notNullable();
+        t.boolean('isTarget').notNullable();
+        t.boolean('isExternal');
+        t.integer('status');
+        t.string('statusText');
+        t.string('contentType').nullable();
+        t.integer('contentLength').unsigned().nullable();
+        t.json('responseHeaders').nullable();
+        // Document basics
+        t.string('lang');
+        t.string('dir');
+        t.string('charset');
+        t.string('baseHref');
+        t.text('viewport_raw');
+        t.string('themeColor');
+        t.string('applicationName');
+        t.string('author');
+        t.string('generator');
+        t.string('publisher');
+        // Title / description / keywords (top-level Meta fields)
+        t.string('title');
+        t.text('description');
+        t.text('keywords');
+        // Robots
+        t.text('robots_raw');
+        t.integer('robots_noindex');
+        t.integer('robots_nofollow');
+        t.integer('robots_noarchive');
+        t.integer('robots_noimageindex');
+        t.string('googlebot');
+        // Link (1:1 only — array shapes live in meta_extras)
+        t.string('canonical', 8190);
+        t.string('amphtml', 8190);
+        t.string('manifest', 8190);
+        t.string('icon_href', 8190);
+        t.string('appleTouchIcon_href', 8190);
+        // Open Graph
+        t.string('og_type');
+        t.string('og_title');
+        t.string('og_url', 8190);
+        t.string('og_site_name');
+        t.text('og_description');
+        t.string('og_image', 8190);
+        t.string('og_image_alt');
+        t.string('og_image_width');
+        t.string('og_image_height');
+        t.string('og_locale');
+        t.string('og_article_published_time');
+        t.string('og_article_modified_time');
+        // Twitter
+        t.string('twitter_card');
+        t.string('twitter_site');
+        t.string('twitter_creator');
+        t.string('twitter_title');
+        t.text('twitter_description');
+        t.string('twitter_image', 8190);
+        // One-offs
+        t.string('fb_app_id');
+        t.string('verification_google');
+        t.integer('formatDetection_telephone');
+        // Within-archive observation timestamps (UNIX ms)
+        t.integer('firstCrawledAt');
+        t.integer('lastCrawledAt');
+        // Denormalised aggregates
+        t.integer('tag_count');
+        t.integer('jsonld_count');
+        t.text('tags_providers_csv');
+        // Catch-all JSON for nested Meta sub-objects not flattened above
+        t.json('meta_extras');
+        // Crawl lifecycle
+        t.boolean('isSkipped');
+        t.string('skipReason');
+        t.integer('order').unsigned().nullable();
+        t.string('source').notNullable().defaultTo('crawled');
+        t.index('isExternal');
+        t.index('contentType');
+        t.index('scraped');
+        t.index('redirectDestId');
+        t.index('order');
+        t.index('robots_noindex');
+        t.index('og_type');
+        t.index('source');
+    })
+        .createTable('anchors', (t) => {
+        t.increments('id');
+        t.integer('pageId').notNullable().unsigned().references('pages.id');
+        t.integer('hrefId').notNullable().unsigned().references('pages.id');
+        t.string('hash');
+        t.string('textContent').nullable();
+        t.index('pageId');
+        t.index('hrefId');
+    })
+        .createTable('images', (t) => {
+        t.increments('id');
+        t.integer('pageId').notNullable().unsigned().references('pages.id');
+        t.string('src', 8190);
+        t.string('currentSrc', 8190);
+        t.string('alt');
+        t.float('width').unsigned().notNullable();
+        t.float('height').unsigned().notNullable();
+        t.integer('naturalWidth').unsigned().notNullable();
+        t.integer('naturalHeight').unsigned().notNullable();
+        t.boolean('isLazy');
+        t.integer('viewportWidth').unsigned().notNullable();
+        t.string('sourceCode');
+        t.index('pageId');
+    })
+        .createTable('resources', (t) => {
+        t.increments('id');
+        t.string('url', 8190).notNullable().unique();
+        t.boolean('isExternal');
+        t.integer('status');
+        t.string('statusText');
+        t.string('contentType').nullable();
+        t.integer('contentLength').unsigned().nullable();
+        t.string('compress').nullable();
+        t.string('cdn').nullable();
+        t.json('responseHeaders').nullable();
+        t.string('source').notNullable().defaultTo('crawled');
+        t.index('source');
+    })
+        .createTable('resources-referrers', (t) => {
+        t.increments('id');
+        t.integer('resourceId').notNullable().unsigned().references('resources.id');
+        t.integer('pageId').notNullable().unsigned().references('pages.id');
+        t.unique(['resourceId', 'pageId']);
+        t.index('resourceId');
+        t.index('pageId');
+    });
+    // Adjunct tables in their pre-0.13 shape: FK columns point at
+    // `pages(id)` — the exact declarations that
+    // `scripts/migrate-to-0.10.mjs` and the runtime lazy migrations of
+    // that era produced.
+    await db.schema.createTable('page_errors', (t) => {
+        t.increments('id');
+        t.integer('pageId').notNullable().unsigned().references('pages.id');
+        t.string('phase').notNullable();
+        t.text('message').notNullable();
+        t.integer('createdAt').notNullable();
+        t.index('pageId');
+    });
+    await db.schema.createTable('page_tags', (t) => {
+        t.increments('id');
+        t.integer('pageId')
+            .notNullable()
+            .unsigned()
+            .references('pages.id')
+            .onDelete('CASCADE');
+        t.string('provider').notNullable();
+        t.string('category');
+        t.string('externalId');
+        t.string('version');
+        t.integer('confidence');
+        t.json('categories');
+        t.json('sources');
+        t.index('pageId');
+        t.index('provider');
+        t.index('externalId');
+    });
+    await db.raw('CREATE INDEX page_tags_provider_extId ON page_tags(provider, externalId)');
+    await db.raw('CREATE INDEX page_tags_provider_pageId ON page_tags(provider, pageId)');
+    await db.schema.createTable('page_jsonld', (t) => {
+        t.increments('id');
+        t.integer('pageId')
+            .notNullable()
+            .unsigned()
+            .references('pages.id')
+            .onDelete('CASCADE');
+        t.string('kind').notNullable();
+        t.string('type');
+        t.text('raw').notNullable();
+        t.json('parsed');
+        t.text('parseError');
+        t.index('pageId');
+        t.index('type');
+    });
+    await db.raw('CREATE INDEX page_jsonld_type_pageId ON page_jsonld(type, pageId)');
+    await db.raw(`
+		CREATE TABLE analysis_text_refs (
+			id integer primary key,
+			text text not null,
+			sha256 text not null,
+			unique(sha256, text)
+		)
+	`);
+    await db.raw(`
+		CREATE TABLE analysis_violations (
+			id integer primary key,
+			page_id integer not null references pages(id),
+			validator text not null,
+			severity text not null,
+			rule text not null,
+			message_text_id integer not null references analysis_text_refs(id),
+			code_text_id integer references analysis_text_refs(id),
+			page_url_sort_key text not null,
+			message_sort_key text not null,
+			code_sort_key text not null
+		)
+	`);
+    await db.raw('CREATE INDEX av_url_order ON analysis_violations(page_url_sort_key, id)');
+    await db.raw('CREATE INDEX av_filter_url ON analysis_violations(validator, severity, rule, page_url_sort_key, id)');
+    await db.raw('CREATE INDEX av_validator_url ON analysis_violations(validator, page_url_sort_key, id)');
+    await db.raw('CREATE INDEX av_severity_url ON analysis_violations(severity, page_url_sort_key, id)');
+    await db.raw('CREATE INDEX av_rule_url ON analysis_violations(rule, page_url_sort_key, id)');
+    await db.raw('CREATE INDEX av_message_order ON analysis_violations(message_sort_key, id)');
+    await db.raw('CREATE INDEX av_code_order ON analysis_violations(code_sort_key, id)');
+    await db.raw('CREATE INDEX av_page ON analysis_violations(page_id, id)');
+    await db.raw(`
+		CREATE TABLE page_html_blobs (
+			hash         BLOB PRIMARY KEY,
+			body         BLOB NOT NULL,
+			codec        TEXT NOT NULL CHECK(codec IN ('zstd', 'none')),
+			size_raw     INTEGER NOT NULL,
+			size_stored  INTEGER NOT NULL
+		) WITHOUT ROWID
+	`);
+    await db.raw(`
+		CREATE TABLE page_html_ref (
+			page_id  INTEGER PRIMARY KEY REFERENCES pages(id) ON DELETE CASCADE,
+			hash     BLOB NOT NULL REFERENCES page_html_blobs(hash)
+		) WITHOUT ROWID
+	`);
+    await db.raw('CREATE INDEX idx_page_html_ref_hash ON page_html_ref(hash)');
+}

package/lib/archive/types.d.ts

@@ -1,6 +1,25 @@
+import type { DomPathCandidate } from './populate-entity-tables/types.js';
+import type { PageData } from '../utils/types/types.js';
 import type { ParseURLOptions } from '@d-zero/shared/parse-url';
+/**
+ * A scraped page payload optionally enriched with the in-browser
+ * dom-path capture (`crawler/capture-image-dom-paths.ts`): every `<img>`
+ * of the rendered document as `{ outerHTML, path }` pairs in document
+ * order. The write path matches these against `imageList[].sourceCode`
+ * to resolve `image_items.dom_path_text_id`; when absent (capture
+ * failed, metadata-only scrape, or a caller that never renders), every
+ * image falls back to the synthetic `unknown/<n>` marker.
+ */
+export type PageDataWithDomPaths = PageData & {
+    /** In-browser dom-path capture for the rendered document's images. */
+    imageDomPaths?: readonly DomPathCandidate[];
+};
 /**
  * Event map for database-related events emitted by the Database and ArchiveAccessor classes.
+ * @example
+ * archive.on('error', (error) => {
+ *   console.error('database failure:', error.message);
+ * });
  */
 export interface DatabaseEvent {
     /** An error that occurred during a database operation. */
@@ -9,6 +28,9 @@ export interface DatabaseEvent {
 /**
  * Configuration stored in the archive database's `info` table.
  * Represents all crawling options that were used for the crawl session.
+ * @example
+ * const config = await archive.getConfig();
+ * console.log(config.roots, config.userAgent, config.parallels);
  */
 export interface Config extends Required<Pick<ParseURLOptions, 'disableQueries'>> {
     /** The starting URL for the crawl. Stored as a denormalised mirror of `roots[0]` so summary consumers can read a single URL without parsing the array. */
@@ -48,12 +70,11 @@ export interface Config extends Required<Pick<ParseURLOptions, 'disableQueries'>
 }
 /**
  * Provenance of a page or resource row — which crawler channel originally
- * inserted it. Stored as `pages.source` / `resources.source` in the
- * SQLite schema (NOT NULL DEFAULT `'crawled'`).
+ * inserted it. Stored as `content_items.source` / `resource_items.source`
+ * in the SQLite schema (NOT NULL DEFAULT `'crawled'`).
  *
  * - `'crawled'` — discovered via the recursive crawl rooted at `info.roots`.
- *   Default for pre-`--inventory` archives after the
- *   `migratePagesResourcesSource` runtime migration.
+ *   Default for rows that predate the `--inventory` feature.
  * - `'inventory-seed'` — supplied directly by a `crawl --inventory` URL
  *   list. For pages this is the HTML URL that was rendered; for resources
  *   this is a non-HTML URL handed in by the list (HEAD-fetched without
@@ -66,8 +87,55 @@ export interface Config extends Required<Pick<ParseURLOptions, 'disableQueries'>
  * Isolation queries (`listIsolatedPages` / `listUnusedResources`) judge
  * orphans by `referrer = 0`, NOT by this value — `source` only labels
  * the row.
+ * @example
+ * if (page.source !== 'crawled') {
+ *   // Row was introduced by a `crawl --inventory` pass.
+ * }
  */
 export type PageSource = 'crawled' | 'inventory-seed' | 'inventory-discovered';
+/**
+ * One row written to the `inventory_runs` audit table on each successful
+ * `--inventory <list>` invocation.
+ *
+ * Schema-mirror interface: every column on `inventory_runs` is represented
+ * here. Only `ran_at` is required — every other field is nullable so a
+ * raw-SQL backfill (a one-off `sqlite3 INSERT` recording an inventory
+ * pass that predates this table) can omit summary
+ * stats it cannot reconstruct.
+ *
+ * The audit log is append-only: there is intentionally no UPDATE path,
+ * no UNIQUE constraint on `source_file_sha256`, and no FK to pages /
+ * resources — re-applying the same list yields a second row. Duplicate
+ * detection is a read-side concern; `source_file_sha256` is recorded as
+ * the content-identity key it would use.
+ * @example
+ * await archive.recordInventoryRun({
+ *   ran_at: new Date().toISOString(),
+ *   list_label: 'prod-2026-06',
+ *   total_lines: 113_268,
+ *   new_pages: 1234,
+ *   new_resources: 56,
+ *   scope_skipped: 7,
+ * });
+ */
+export interface InventoryRunMeta {
+    /** ISO 8601 timestamp at which the run completed (e.g. `'2026-06-21T11:30:00+09:00'`). */
+    ran_at: string;
+    /** Human-readable identifier (e.g. `'prod-2026-06-21'`). `null` when the caller did not supply one. */
+    list_label?: string | null;
+    /** SHA-256 hex digest of the source file. `null` if hashing failed (e.g. file vanished mid-run). */
+    source_file_sha256?: string | null;
+    /** Number of non-empty lines in the input list (= URL count before scope filtering). */
+    total_lines?: number | null;
+    /** Number of new HTML seeds inserted as `content_items` rows by this run. */
+    new_pages?: number | null;
+    /** Number of new non-HTML URLs inserted as `resource_items` rows by this run. */
+    new_resources?: number | null;
+    /** Number of input URLs dropped because they fell outside the archived scope. */
+    scope_skipped?: number | null;
+    /** Free-form text for backfill annotations or operator notes. */
+    notes?: string | null;
+}
 /**
  * Filter type for querying pages from the database.
  *
@@ -78,16 +146,28 @@ export type PageSource = 'crawled' | 'inventory-seed' | 'inventory-discovered';
  * - `'no-page'` - Non-HTML resources (e.g., images, PDFs)
  * - `'external-no-page'` - External non-HTML resources
  * - `'internal-no-page'` - Internal non-HTML resources
+ * @example
+ * const internalHtmlPages = await accessor.getPages('internal-page');
  */
 export type PageFilter = 'page' | 'page-included-no-target' | 'external-page' | 'internal-page' | 'no-page' | 'external-no-page' | 'internal-no-page';
 /**
- * Raw database row representing a crawled page in the `pages` table (v2 schema).
+ * Flat page-row shape.
  *
- * Maps 1:1 to the columns defined by `archive/init-schema.ts`. Most meta
- * fields are derived from beholder 3.0.0's nested {@link import('@d-zero/beholder').Meta}
- * via `archive/meta/derive-flat-from-meta.ts` and are stored as plain
- * scalars for SQL-level filter / projection. The catch-all `meta_extras`
- * JSON column preserves nested sub-objects not flattened above.
+ * Serves two roles: (1) the read shape that
+ * `db-ops/pages/read/reconstruct-page-rows.ts` rebuilds by joining the
+ * entity / ref tables (`content_items` / `page_meta` / `url_refs` …), and
+ * (2) the raw row shape of the pre-0.13 legacy `pages` table, which only
+ * exists inside pre-0.13 input archives and is read by the 0.13 migration
+ * populate code. Most meta fields are derived from beholder 3.0.0's nested
+ * {@link import('@d-zero/beholder').Meta} via
+ * `archive/meta/derive-flat-from-meta.ts` and are stored as plain scalars
+ * for SQL-level filter / projection. The catch-all `meta_extras` JSON
+ * column preserves nested sub-objects not flattened above.
+ * @example
+ * const pages = await accessor.getPages('page');
+ * for (const page of pages) {
+ *   console.log(page.url, page.status, page.title);
+ * }
  */
 export interface DB_Page {
     /** Auto-incremented primary key. */
@@ -228,6 +308,12 @@ export interface DB_Page {
 /**
  * Raw database row representing a redirect relationship.
  * Maps a source page to its redirect destination.
+ * @example
+ * const redirect: DB_Redirect = {
+ *   pageId: 9, // destination page id
+ *   from: 'http://example.com/old',
+ *   fromId: 3,
+ * };
  */
 export interface DB_Redirect {
     /** The ID of the destination page after redirect. */
@@ -238,8 +324,12 @@ export interface DB_Redirect {
     fromId: number;
 }
 /**
- * Raw database row representing an anchor (link) found on a page.
- * Combines data from the `anchors` table and the linked `pages` table.
+ * Flat anchor-row shape reconstructed by joining `anchor_edges` with the
+ * destination's `content_items` row and the ref tables. Also mirrors the
+ * pre-0.13 legacy `anchors` join shape read by the migration populate code.
+ * @example
+ * const anchors = await accessor.getAnchorsOnPage(pageId);
+ * const brokenLinks = anchors.filter((a) => a.status === 404);
  */
 export interface DB_Anchor {
     /** The ID of the page that contains this anchor. */
@@ -266,6 +356,10 @@ export interface DB_Anchor {
 /**
  * Raw database row representing a referrer relationship.
  * Indicates which page links to which other page, potentially through redirects.
+ * @example
+ * const referrers = await accessor.getReferrersOfPage(pageId);
+ * // `through` differs from the destination URL when the link passed
+ * // through a redirect source.
  */
 export interface DB_Referrer {
     /** The ID of the page being referred to. */
@@ -282,7 +376,15 @@ export interface DB_Referrer {
     textContent: string | null;
 }
 /**
- * Raw database row representing an image element found on a page in the `images` table.
+ * Raw database row of the pre-0.13 legacy `images` table. The table only
+ * exists inside pre-0.13 input archives; current archives store images in
+ * `image_items`. This type is read exclusively by the 0.13 migration
+ * populate code (`populate-image-items.ts`), which converts these rows
+ * into `image_items` before the legacy table is dropped.
+ * @example
+ * // Inside migration populate code reading a pre-0.13 input archive:
+ * const images: DB_Image[] = await trx('images').where('pageId', pageId);
+ * const missingAlt = images.filter((img) => img.alt === null);
  */
 export interface DB_Image {
     /** Auto-incremented primary key. */
@@ -312,6 +414,14 @@ export interface DB_Image {
 }
 /**
  * Represents a page that links to another page (an incoming link).
+ * @example
+ * const referrer: Referrer = {
+ *   url: 'https://example.com/from',
+ *   through: 'https://example.com/old',
+ *   throughId: 3,
+ *   hash: null,
+ *   textContent: 'Link text',
+ * };
  */
 export interface Referrer {
     /** The URL of the referring page. */
@@ -327,6 +437,18 @@ export interface Referrer {
 }
 /**
  * Represents an outgoing link (anchor element) found on a page.
+ * @example
+ * const anchor: Anchor = {
+ *   url: 'https://example.com/about',
+ *   href: '/about',
+ *   isExternal: false,
+ *   title: null,
+ *   status: 200,
+ *   statusText: 'OK',
+ *   contentType: 'text/html',
+ *   hash: null,
+ *   textContent: 'About us',
+ * };
  */
 export interface Anchor {
     /** The resolved destination URL of the anchor. */
@@ -350,6 +472,8 @@ export interface Anchor {
 }
 /**
  * Represents a page that redirects to this page.
+ * @example
+ * const redirect: Redirect = { url: 'http://example.com/old', pageId: 3 };
  */
 export interface Redirect {
     /** The URL of the redirect source page. */
@@ -359,12 +483,19 @@ export interface Redirect {
 }
 /**
  * Raw database row representing a sub-resource (CSS, JS, image, etc.) in the `resources` table.
+ * @example
+ * const resources = await accessor.getResources();
+ * const notFound = resources.filter((r) => r.status === 404);
  */
 export interface DB_Resource {
     /** Auto-incremented primary key. */
     id: number;
-    /** The URL of the resource. */
-    url: string;
+    /**
+     * The URL of the resource, or `null` when its identity URL is a large
+     * `data:` URI routed to `blob_refs` instead of `url_refs` (mirrors
+     * `image_items`' src/blob convention — see `build-resource-query.ts`).
+     */
+    url: string | null;
     /** Whether the resource is hosted on an external domain (1) or internal (0). */
     isExternal: 0 | 1;
     /** HTTP response status code, or null if not yet fetched. */
@@ -386,6 +517,11 @@ export interface DB_Resource {
 }
 /**
  * Connection options for the archive's libsql-backed database.
+ * @example
+ * const db = await Database.connect({
+ *   filename: '/path/to/._nitpicker-site/db.sqlite',
+ *   readOnly: true,
+ * });
  */
 export interface DatabaseOption {
     /** The absolute file path to the SQLite database file. */

package/lib/archive/verify-migration/capture-rejection.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Awaits a rejecting promise and returns the thrown value. Fails the caller
+ * with a descriptive error if the promise resolves. Lets assertions treat
+ * the caught value as a normal object without needing a try/catch in the
+ * test body — the qa-engineer rule bans `if` / `switch` / try-catch inside
+ * test code because control flow inside a test hides which assertion is
+ * actually running when a check fails.
+ *
+ * The sentinel is a fresh `Symbol` per invocation so a genuine rejection
+ * whose reason is `undefined` is still correctly distinguished from a
+ * resolution to `undefined`.
+ *
+ * Shared by `check-reader-parity.spec.ts` and `verify-migration.spec.ts`
+ * (and any future verify-migration spec that needs to inspect a rejection
+ * reason). Not exported from the package — this is a test-only utility
+ * kept next to its callers.
+ * @param promise - The promise expected to reject.
+ * @returns The rejection reason.
+ * @example
+ * const error = await captureRejection(verifyMigration(db));
+ * expect(error).toBeInstanceOf(MigrationVerificationError);
+ * expect((error as MigrationVerificationError).details.check).toContain('#1');
+ */
+export declare function captureRejection(promise: Promise<unknown>): Promise<unknown>;

package/lib/archive/verify-migration/capture-rejection.js

@@ -0,0 +1,31 @@
+/**
+ * Awaits a rejecting promise and returns the thrown value. Fails the caller
+ * with a descriptive error if the promise resolves. Lets assertions treat
+ * the caught value as a normal object without needing a try/catch in the
+ * test body — the qa-engineer rule bans `if` / `switch` / try-catch inside
+ * test code because control flow inside a test hides which assertion is
+ * actually running when a check fails.
+ *
+ * The sentinel is a fresh `Symbol` per invocation so a genuine rejection
+ * whose reason is `undefined` is still correctly distinguished from a
+ * resolution to `undefined`.
+ *
+ * Shared by `check-reader-parity.spec.ts` and `verify-migration.spec.ts`
+ * (and any future verify-migration spec that needs to inspect a rejection
+ * reason). Not exported from the package — this is a test-only utility
+ * kept next to its callers.
+ * @param promise - The promise expected to reject.
+ * @returns The rejection reason.
+ * @example
+ * const error = await captureRejection(verifyMigration(db));
+ * expect(error).toBeInstanceOf(MigrationVerificationError);
+ * expect((error as MigrationVerificationError).details.check).toContain('#1');
+ */
+export async function captureRejection(promise) {
+    const sentinel = Symbol('did-not-throw');
+    const value = await promise.then(() => sentinel, (error) => error);
+    if (value === sentinel) {
+        throw new Error('captureRejection: promise resolved but was expected to reject — the code path under test is silently succeeding');
+    }
+    return value;
+}

package/lib/archive/verify-migration/check-anchor-edges-count.d.ts

@@ -0,0 +1,34 @@
+import type { Knex } from 'knex';
+/**
+ * Verifies 0.13 invariant #3: the `anchor_edges` dedup does not
+ * eliminate rows and does not create phantom rows.
+ *
+ * `populateAnchorEdges` collapses N `anchors` rows per `(pageId, hrefId)`
+ * pair into a single `anchor_edges` row with `count = N`. Two ways it
+ * could go wrong:
+ *
+ * - `count(anchor_edges) == 0 && count(anchors) > 0` — dedup annihilated
+ *   the graph. A populate bug or a group-by mis-key would trip this.
+ * - `count(anchor_edges) > count(anchors)` — dedup produced more rows than
+ *   inputs. Impossible under a correct `GROUP BY` but a phantom-insert bug
+ *   in the populate loop would trip this.
+ *
+ * `count(anchor_edges) == count(anchors)` is **not** a failure. Issue #194
+ * spelled the upper bound as `< count(anchors)` (strict), but a legitimate
+ * small crawl where every `(pageId, hrefId)` pair is unique produces one
+ * edge per anchor (count=1) and satisfies the identity naturally. Enforcing
+ * strict `<` would refuse to migrate such archives even though every other
+ * invariant holds; the true invariant is "no rows added or dropped by
+ * dedup" (`anchor_edges <= anchors`), so the code enforces the weaker,
+ * correct clause. Check #4 (`SUM(count) == count(anchors)`) already
+ * establishes that no rows were silently discarded when the counts happen
+ * to match.
+ *
+ * A trivial archive with zero `anchors` legitimately produces zero
+ * `anchor_edges`, so both counts being zero passes; a non-zero `anchor_edges`
+ * with a zero `anchors` still throws — that would mean rows appeared from
+ * nowhere.
+ * @param trx - Knex instance or transaction connected to the populated archive.
+ * @throws {MigrationVerificationError} when the invariant is violated.
+ */
+export declare function checkAnchorEdgesCount(trx: Knex): Promise<void>;