@nitpicker/archive 0.0.0 → 0.25.1

package/lib/migrate-info-request-header-names.js

@@ -0,0 +1,35 @@
+/**
+ * Adds the `info.requestHeaderNames` column to archives created before it
+ * existed. `CREATE TABLE IF NOT EXISTS` (used for `info` itself) cannot
+ * retrofit a new column onto an already-existing table, so this lightweight,
+ * `hasColumn`-guarded `ALTER TABLE` runs on every `initSchema` call —
+ * idempotent, and self-healing for archives whose provisioning crashed
+ * partway through.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migrateInfoRequestHeaderNames(instance, onLog) {
+    const hasInfo = await instance.schema.hasTable('info');
+    if (!hasInfo) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('info', 'requestHeaderNames');
+    if (hasColumn) {
+        return;
+    }
+    await instance.schema.table('info', (t) => {
+        t.json('requestHeaderNames');
+    });
+    const message = '[migrate] info.requestHeaderNames column added';
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // oxlint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/migrate-info-roots.d.ts

@@ -0,0 +1,20 @@
+import type { Knex } from 'knex';
+/**
+ * Bring an archive's `info` table to the current shape: add `roots` (seeded
+ * from `baseUrl`) and drop the obsolete `scope` column.
+ *
+ * Idempotent: calling this multiple times on an up-to-date schema is a no-op.
+ * Archives where `baseUrl` is NULL receive an empty `roots` array rather than
+ * throwing.
+ *
+ * When the migration actually runs (i.e. either column transition was
+ * performed), a single notice is written to stderr so the user knows the
+ * file was upgraded.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migrateInfoRoots(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-info-roots.js

@@ -0,0 +1,52 @@
+/**
+ * Bring an archive's `info` table to the current shape: add `roots` (seeded
+ * from `baseUrl`) and drop the obsolete `scope` column.
+ *
+ * Idempotent: calling this multiple times on an up-to-date schema is a no-op.
+ * Archives where `baseUrl` is NULL receive an empty `roots` array rather than
+ * throwing.
+ *
+ * When the migration actually runs (i.e. either column transition was
+ * performed), a single notice is written to stderr so the user knows the
+ * file was upgraded.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migrateInfoRoots(instance, onLog) {
+    const hasInfo = await instance.schema.hasTable('info');
+    if (!hasInfo) {
+        return;
+    }
+    const hasRoots = await instance.schema.hasColumn('info', 'roots');
+    const hasScope = await instance.schema.hasColumn('info', 'scope');
+    if (hasRoots && !hasScope) {
+        return;
+    }
+    const changes = [];
+    if (!hasRoots) {
+        await instance.schema.table('info', (t) => {
+            t.json('roots');
+        });
+        await instance.raw(`UPDATE info SET roots = json_array(baseUrl) WHERE roots IS NULL AND baseUrl IS NOT NULL`);
+        await instance.raw(`UPDATE info SET roots = '[]' WHERE roots IS NULL`);
+        changes.push('roots seeded');
+    }
+    if (hasScope) {
+        await instance.schema.table('info', (t) => {
+            t.dropColumn('scope');
+        });
+        changes.push('scope dropped');
+    }
+    const message = `[migrate] info table upgraded (${changes.join(', ')})`;
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // oxlint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/migrate-inventory-runs-to-list-reconcile-runs.d.ts

@@ -0,0 +1,34 @@
+import type { Knex } from 'knex';
+/**
+ * Renames the legacy `inventory_runs` table to `list_reconcile_runs` for
+ * archives created before the rename (issue #354: the old name implied
+ * `--inventory`-only despite `--recrawl` writing to the same table via the
+ * same {@link import('./db-ops/list-reconcile/record-list-reconcile-run.js').recordListReconcileRun}
+ * path).
+ *
+ * Must run BEFORE {@link import('./init-schema.js').initSchema} in the boot
+ * sequence, not alongside the other column-adding `migrate*` functions
+ * that run after it. `initSchema` unconditionally re-runs
+ * `createAdjunctTables`, which creates `list_reconcile_runs` fresh
+ * (`CREATE TABLE IF NOT EXISTS`) if it doesn't see the new name yet — so if
+ * this rename ran after `initSchema`, it would find `list_reconcile_runs`
+ * already present (empty) and skip, silently orphaning the old table's
+ * rows. Running first guarantees `initSchema` sees the already-renamed
+ * table and its `IF NOT EXISTS` guard is a no-op.
+ *
+ * A straight `renameTable` (not the convert-then-drop pattern used for
+ * `page_tags` → `technology_signals`/`page_technologies`) because this is a
+ * pure name change with no data-shape change — the row shape is identical
+ * before and after.
+ *
+ * Idempotent: a no-op once `inventory_runs` is gone (either because this
+ * function already ran, or the archive was created after the rename
+ * shipped and never had the old name).
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migrateInventoryRunsToListReconcileRuns(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-inventory-runs-to-list-reconcile-runs.js

@@ -0,0 +1,51 @@
+/**
+ * Renames the legacy `inventory_runs` table to `list_reconcile_runs` for
+ * archives created before the rename (issue #354: the old name implied
+ * `--inventory`-only despite `--recrawl` writing to the same table via the
+ * same {@link import('./db-ops/list-reconcile/record-list-reconcile-run.js').recordListReconcileRun}
+ * path).
+ *
+ * Must run BEFORE {@link import('./init-schema.js').initSchema} in the boot
+ * sequence, not alongside the other column-adding `migrate*` functions
+ * that run after it. `initSchema` unconditionally re-runs
+ * `createAdjunctTables`, which creates `list_reconcile_runs` fresh
+ * (`CREATE TABLE IF NOT EXISTS`) if it doesn't see the new name yet — so if
+ * this rename ran after `initSchema`, it would find `list_reconcile_runs`
+ * already present (empty) and skip, silently orphaning the old table's
+ * rows. Running first guarantees `initSchema` sees the already-renamed
+ * table and its `IF NOT EXISTS` guard is a no-op.
+ *
+ * A straight `renameTable` (not the convert-then-drop pattern used for
+ * `page_tags` → `technology_signals`/`page_technologies`) because this is a
+ * pure name change with no data-shape change — the row shape is identical
+ * before and after.
+ *
+ * Idempotent: a no-op once `inventory_runs` is gone (either because this
+ * function already ran, or the archive was created after the rename
+ * shipped and never had the old name).
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migrateInventoryRunsToListReconcileRuns(instance, onLog) {
+    const hasOldTable = await instance.schema.hasTable('inventory_runs');
+    if (!hasOldTable) {
+        return;
+    }
+    const hasNewTable = await instance.schema.hasTable('list_reconcile_runs');
+    if (hasNewTable) {
+        return;
+    }
+    await instance.schema.renameTable('inventory_runs', 'list_reconcile_runs');
+    const message = '[migrate] inventory_runs renamed to list_reconcile_runs';
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // oxlint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/migrate-list-reconcile-runs-exclude-skipped.d.ts

@@ -0,0 +1,25 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `list_reconcile_runs.exclude_skipped` column to archives created
+ * before it existed. `CREATE TABLE IF NOT EXISTS` (used for
+ * `list_reconcile_runs` itself) cannot retrofit a new column onto an
+ * already-existing table, so this lightweight, `hasColumn`-guarded
+ * `ALTER TABLE` runs on every `initSchema` call — idempotent, and
+ * self-healing for archives whose provisioning crashed partway through.
+ *
+ * Pre-migration rows stay `NULL`: those runs predate ingestion-side
+ * exclusion (issue #260), so their excluded URLs were imported as real
+ * pages/resources rather than recorded as skipped — `NULL` means "not
+ * measured", not `0`.
+ *
+ * The column is pure audit output: written once per run and read back
+ * only by `listReconcileRuns` display surfaces, never consumed by any
+ * runtime decision — matching `scope_skipped` / `invalid_skipped`.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migrateListReconcileRunsExcludeSkipped(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-list-reconcile-runs-exclude-skipped.js

@@ -0,0 +1,44 @@
+/**
+ * Adds the `list_reconcile_runs.exclude_skipped` column to archives created
+ * before it existed. `CREATE TABLE IF NOT EXISTS` (used for
+ * `list_reconcile_runs` itself) cannot retrofit a new column onto an
+ * already-existing table, so this lightweight, `hasColumn`-guarded
+ * `ALTER TABLE` runs on every `initSchema` call — idempotent, and
+ * self-healing for archives whose provisioning crashed partway through.
+ *
+ * Pre-migration rows stay `NULL`: those runs predate ingestion-side
+ * exclusion (issue #260), so their excluded URLs were imported as real
+ * pages/resources rather than recorded as skipped — `NULL` means "not
+ * measured", not `0`.
+ *
+ * The column is pure audit output: written once per run and read back
+ * only by `listReconcileRuns` display surfaces, never consumed by any
+ * runtime decision — matching `scope_skipped` / `invalid_skipped`.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migrateListReconcileRunsExcludeSkipped(instance, onLog) {
+    const hasTable = await instance.schema.hasTable('list_reconcile_runs');
+    if (!hasTable) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('list_reconcile_runs', 'exclude_skipped');
+    if (hasColumn) {
+        return;
+    }
+    await instance.schema.table('list_reconcile_runs', (t) => {
+        t.integer('exclude_skipped');
+    });
+    const message = '[migrate] list_reconcile_runs.exclude_skipped column added';
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // oxlint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/migrate-list-reconcile-runs-invalid-skipped.d.ts

@@ -0,0 +1,16 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `list_reconcile_runs.invalid_skipped` column to archives created
+ * before it existed. `CREATE TABLE IF NOT EXISTS` (used for
+ * `list_reconcile_runs` itself) cannot retrofit a new column onto an
+ * already-existing table, so this lightweight, `hasColumn`-guarded
+ * `ALTER TABLE` runs on every `initSchema` call — idempotent, and
+ * self-healing for archives whose provisioning crashed partway through.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migrateListReconcileRunsInvalidSkipped(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-list-reconcile-runs-invalid-skipped.js

@@ -0,0 +1,35 @@
+/**
+ * Adds the `list_reconcile_runs.invalid_skipped` column to archives created
+ * before it existed. `CREATE TABLE IF NOT EXISTS` (used for
+ * `list_reconcile_runs` itself) cannot retrofit a new column onto an
+ * already-existing table, so this lightweight, `hasColumn`-guarded
+ * `ALTER TABLE` runs on every `initSchema` call — idempotent, and
+ * self-healing for archives whose provisioning crashed partway through.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migrateListReconcileRunsInvalidSkipped(instance, onLog) {
+    const hasTable = await instance.schema.hasTable('list_reconcile_runs');
+    if (!hasTable) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('list_reconcile_runs', 'invalid_skipped');
+    if (hasColumn) {
+        return;
+    }
+    await instance.schema.table('list_reconcile_runs', (t) => {
+        t.integer('invalid_skipped');
+    });
+    const message = '[migrate] list_reconcile_runs.invalid_skipped column added';
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // oxlint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/migrate-main-contents-columns.d.ts

@@ -0,0 +1,26 @@
+import type { Knex } from 'knex';
+/**
+ * Add the beholder `MainContentsData` / `ScrollHeightData` denormalised
+ * aggregate columns to `page_meta` on archives created before this feature.
+ *
+ * `page_meta` is provisioned via a bare `CREATE TABLE IF NOT EXISTS` in
+ * {@link import('./create-entity-tables.js').createEntityTables}, which
+ * self-heals a *missing table* on every `initSchema` call but is a no-op
+ * against an *existing* table — adding a column to the DDL string never
+ * reaches an archive whose `page_meta` predates this change. This mirrors
+ * {@link import('./migrate-info-roots.js').migrateInfoRoots}'s `info.roots`
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column set that
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * Idempotent: a no-op once the columns exist. Guards on `page_meta`'s
+ * existence defensively, though by the time this runs (after `initSchema`,
+ * itself after `assertCompatibleVersion` rejects pre-0.13 archives) the
+ * table is always present.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migrateMainContentsColumns(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-main-contents-columns.js

@@ -0,0 +1,61 @@
+/**
+ * Add the beholder `MainContentsData` / `ScrollHeightData` denormalised
+ * aggregate columns to `page_meta` on archives created before this feature.
+ *
+ * `page_meta` is provisioned via a bare `CREATE TABLE IF NOT EXISTS` in
+ * {@link import('./create-entity-tables.js').createEntityTables}, which
+ * self-heals a *missing table* on every `initSchema` call but is a no-op
+ * against an *existing* table — adding a column to the DDL string never
+ * reaches an archive whose `page_meta` predates this change. This mirrors
+ * {@link import('./migrate-info-roots.js').migrateInfoRoots}'s `info.roots`
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column set that
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * Idempotent: a no-op once the columns exist. Guards on `page_meta`'s
+ * existence defensively, though by the time this runs (after `initSchema`,
+ * itself after `assertCompatibleVersion` rejects pre-0.13 archives) the
+ * table is always present.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migrateMainContentsColumns(instance, onLog) {
+    const hasPageMeta = await instance.schema.hasTable('page_meta');
+    if (!hasPageMeta) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('page_meta', 'main_content_word_count');
+    if (hasColumn) {
+        return;
+    }
+    await instance.schema.table('page_meta', (t) => {
+        t.string('main_content_node_name');
+        t.string('main_content_id');
+        t.string('main_content_role');
+        t.string('main_content_selector');
+        t.text('main_content_class_list');
+        t.integer('main_content_word_count');
+        t.integer('main_content_body_word_count');
+        t.integer('main_content_heading_count');
+        t.integer('main_content_image_count');
+        t.integer('main_content_table_count');
+        t.integer('main_content_button_count');
+        t.integer('main_content_iframe_count');
+        t.integer('main_content_video_count');
+        t.integer('main_content_audio_count');
+        t.integer('main_content_canvas_count');
+        t.integer('scroll_height_desktop');
+        t.integer('scroll_height_mobile');
+    });
+    const message = '[migrate] page_meta.main_content_* / scroll_height_* columns added';
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // oxlint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/migrate-page-meta-body-hash.d.ts

@@ -0,0 +1,44 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `page_meta.body_hash` column to archives created before this
+ * feature, then ensures its index exists.
+ *
+ * `page_meta` is provisioned via a bare `CREATE TABLE IF NOT EXISTS` in
+ * {@link import('./create-entity-tables.js').createEntityTables}, which
+ * self-heals a *missing table* on every `initSchema` call but is a no-op
+ * against an *existing* table — adding a column to the DDL string never
+ * reaches an archive whose `page_meta` predates this change. This mirrors
+ * {@link import('./migrate-main-contents-columns.js').migrateMainContentsColumns}'s
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * The index is created here — unconditionally, after the column-add guard,
+ * not inside `createEntityTables`'s DDL — for both a fresh archive (where
+ * `body_hash` already exists from the DDL, so only the index still needs
+ * creating) and a legacy archive (where the column is added just above,
+ * then the index follows in the same call). `createEntityTables` runs
+ * unconditionally on every archive open, including legacy archives that
+ * still lack `body_hash` at that point; an unconditional
+ * `CREATE INDEX ... body_hash` there would fail with `no such column` before
+ * this migration ever runs. This function is the one place guaranteed to
+ * run only after the column is confirmed present, for both archive kinds.
+ *
+ * Only adds the column and its index — it does not backfill values for
+ * existing rows (they stay `NULL`). That backfill runs separately, from
+ * `backfillBodyHashFromHtmlBlobs` during a viewer-read-model build, since it
+ * requires decompressing every page's stored HTML and is too heavy to run on
+ * every archive open.
+ *
+ * Idempotent: adding the column is a no-op once it exists (the index
+ * creation always runs, but `IF NOT EXISTS` makes repeat runs a no-op too).
+ * Guards on `page_meta`'s existence defensively, though by the time this
+ * runs (after `initSchema`, itself after `assertCompatibleVersion` rejects
+ * pre-0.13 archives) the table is always present.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migratePageMetaBodyHash(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-page-meta-body-hash.js

@@ -0,0 +1,63 @@
+/**
+ * Adds the `page_meta.body_hash` column to archives created before this
+ * feature, then ensures its index exists.
+ *
+ * `page_meta` is provisioned via a bare `CREATE TABLE IF NOT EXISTS` in
+ * {@link import('./create-entity-tables.js').createEntityTables}, which
+ * self-heals a *missing table* on every `initSchema` call but is a no-op
+ * against an *existing* table — adding a column to the DDL string never
+ * reaches an archive whose `page_meta` predates this change. This mirrors
+ * {@link import('./migrate-main-contents-columns.js').migrateMainContentsColumns}'s
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * The index is created here — unconditionally, after the column-add guard,
+ * not inside `createEntityTables`'s DDL — for both a fresh archive (where
+ * `body_hash` already exists from the DDL, so only the index still needs
+ * creating) and a legacy archive (where the column is added just above,
+ * then the index follows in the same call). `createEntityTables` runs
+ * unconditionally on every archive open, including legacy archives that
+ * still lack `body_hash` at that point; an unconditional
+ * `CREATE INDEX ... body_hash` there would fail with `no such column` before
+ * this migration ever runs. This function is the one place guaranteed to
+ * run only after the column is confirmed present, for both archive kinds.
+ *
+ * Only adds the column and its index — it does not backfill values for
+ * existing rows (they stay `NULL`). That backfill runs separately, from
+ * `backfillBodyHashFromHtmlBlobs` during a viewer-read-model build, since it
+ * requires decompressing every page's stored HTML and is too heavy to run on
+ * every archive open.
+ *
+ * Idempotent: adding the column is a no-op once it exists (the index
+ * creation always runs, but `IF NOT EXISTS` makes repeat runs a no-op too).
+ * Guards on `page_meta`'s existence defensively, though by the time this
+ * runs (after `initSchema`, itself after `assertCompatibleVersion` rejects
+ * pre-0.13 archives) the table is always present.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migratePageMetaBodyHash(instance, onLog) {
+    const hasPageMeta = await instance.schema.hasTable('page_meta');
+    if (!hasPageMeta) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('page_meta', 'body_hash');
+    if (!hasColumn) {
+        await instance.schema.table('page_meta', (t) => {
+            t.binary('body_hash');
+        });
+        const message = '[migrate] page_meta.body_hash column added';
+        if (onLog) {
+            onLog(message);
+        }
+        else {
+            // oxlint-disable-next-line no-console
+            console.error(message);
+        }
+    }
+    await instance.raw('CREATE INDEX IF NOT EXISTS idx_page_meta_body_hash ON page_meta(body_hash)');
+}

package/lib/migrate-page-meta-console-error-count.d.ts

@@ -0,0 +1,27 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `page_meta.console_error_count` column to archives created
+ * before this feature (issue #228).
+ *
+ * `page_meta` is provisioned via a bare `CREATE TABLE IF NOT EXISTS` in
+ * {@link import('./create-entity-tables.js').createEntityTables}, which
+ * self-heals a *missing table* on every `initSchema` call but is a no-op
+ * against an *existing* table — adding a column to the DDL string never
+ * reaches an archive whose `page_meta` predates this change. Same
+ * catch-up shape as {@link import('./migrate-page-meta-body-hash.js').migratePageMetaBodyHash}.
+ *
+ * Unlike `body_hash`, there is no separate backfill step: a page that has
+ * never been re-scraped since this feature shipped has no
+ * `page_console_logs` rows either, so `0` (the value `replaceConsoleLogs`
+ * writes for a page with no error/pageerror entries) is already the
+ * correct value, not a placeholder pending backfill.
+ *
+ * Idempotent: adding the column is a no-op once it exists.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migratePageMetaConsoleErrorCount(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-page-meta-console-error-count.js

@@ -0,0 +1,45 @@
+/**
+ * Adds the `page_meta.console_error_count` column to archives created
+ * before this feature (issue #228).
+ *
+ * `page_meta` is provisioned via a bare `CREATE TABLE IF NOT EXISTS` in
+ * {@link import('./create-entity-tables.js').createEntityTables}, which
+ * self-heals a *missing table* on every `initSchema` call but is a no-op
+ * against an *existing* table — adding a column to the DDL string never
+ * reaches an archive whose `page_meta` predates this change. Same
+ * catch-up shape as {@link import('./migrate-page-meta-body-hash.js').migratePageMetaBodyHash}.
+ *
+ * Unlike `body_hash`, there is no separate backfill step: a page that has
+ * never been re-scraped since this feature shipped has no
+ * `page_console_logs` rows either, so `0` (the value `replaceConsoleLogs`
+ * writes for a page with no error/pageerror entries) is already the
+ * correct value, not a placeholder pending backfill.
+ *
+ * Idempotent: adding the column is a no-op once it exists.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migratePageMetaConsoleErrorCount(instance, onLog) {
+    const hasPageMeta = await instance.schema.hasTable('page_meta');
+    if (!hasPageMeta) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('page_meta', 'console_error_count');
+    if (!hasColumn) {
+        await instance.schema.table('page_meta', (t) => {
+            t.integer('console_error_count');
+        });
+        const message = '[migrate] page_meta.console_error_count column added';
+        if (onLog) {
+            onLog(message);
+        }
+        else {
+            // oxlint-disable-next-line no-console
+            console.error(message);
+        }
+    }
+}

package/lib/migrate-page-meta-custom-element-count.d.ts

@@ -0,0 +1,33 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `page_meta.main_content_custom_element_count` column to archives
+ * created before this feature.
+ *
+ * `page_meta` is provisioned via a bare `CREATE TABLE IF NOT EXISTS` in
+ * {@link import('./create-entity-tables.js').createEntityTables}, which
+ * self-heals a *missing table* on every `initSchema` call but is a no-op
+ * against an *existing* table — adding a column to the DDL string never
+ * reaches an archive whose `page_meta` predates this change. Same catch-up
+ * shape as {@link import('./migrate-page-meta-console-error-count.js').migratePageMetaConsoleErrorCount}.
+ *
+ * Deliberately its own file rather than an addition to
+ * {@link import('./migrate-main-contents-columns.js').migrateMainContentsColumns}:
+ * that migration early-returns once its sentinel column
+ * (`main_content_word_count`) already exists, so an archive that predates
+ * only this one column (but already has the other sixteen main-content
+ * columns) would never reach an appended `ALTER TABLE` inside it.
+ *
+ * No separate backfill: a page that has never been re-scraped since this
+ * feature shipped stays `NULL` (unknown), which is correct — it is not
+ * conflated with `0` (capture succeeded, zero custom elements found). See
+ * {@link import('./meta/compute-main-contents-denormalized.js').computeMainContentsDenormalized}.
+ *
+ * Idempotent: adding the column is a no-op once it exists.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migratePageMetaCustomElementCount(instance: Knex, onLog?: (message: string) => void): Promise<void>;