@nitpicker/archive 0.0.0 → 0.25.0

package/lib/meta/types.js

@@ -0,0 +1,65 @@
+/**
+ * Shared type definitions for archive-side meta processing helpers under {@link ./}.
+ *
+ * Mirrors the shape of {@link Meta} after archive-side
+ * derivation: flat columns persisted to the `pages` table, denormalised
+ * aggregates, per-row shapes for `page_jsonld` / `page_tags`, and the summary
+ * objects returned by `get-page-detail` consumers.
+ * @module
+ */
+import { compareSemver } from './compare-semver.js';
+/**
+ * Error thrown by `assert-compatible-version` when the archive's
+ * `info.version` is older than the format version this build accepts.
+ *
+ * Catch this at CLI / viewer boundaries to print a friendly message; do not
+ * confuse with generic `Error` thrown by `Database.connect` (lockfile / I/O).
+ * @example
+ * try {
+ *   const accessor = await Archive.openCached(filePath);
+ * } catch (error) {
+ *   if (error instanceof IncompatibleArchiveError) {
+ *     // Message names the migration script(s) to run.
+ *     console.error(error.message);
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ */
+export class IncompatibleArchiveError extends Error {
+    archiveVersion;
+    requiredVersion;
+    /**
+     * @param archiveVersion - The `info.version` value read from the archive
+     *   (or `'unknown'` when the column is missing / null).
+     * @param requiredVersion - The minimum format version this build accepts
+     *   (semver string, e.g. `'0.13.0'`).
+     */
+    constructor(archiveVersion, requiredVersion) {
+        super(`Archive uses Nitpicker ${archiveVersion}; this build requires ${requiredVersion} or newer. ` +
+            `Run ${suggestMigrationScript(archiveVersion)} to produce an upgraded copy next to it.`);
+        this.archiveVersion = archiveVersion;
+        this.requiredVersion = requiredVersion;
+        this.name = 'IncompatibleArchiveError';
+    }
+}
+/**
+ * Selects the migration script an operator should run to bring
+ * `archiveVersion` up to the current {@link IncompatibleArchiveError.requiredVersion}.
+ * Chained: pre-0.10 archives run migrate-to-0.10 first, then
+ * migrate-to-0.13 — so the message points at BOTH steps in order.
+ * 0.10.0-through-0.12.x archives only need migrate-to-0.13.
+ *
+ * Uses {@link compareSemver} instead of `<` string comparison: `'0.9.0'`
+ * lexicographically compares GREATER than `'0.10.0'` (because `'9' > '1'`),
+ * which would misroute pre-0.10 archives into the single-step hint and
+ * make the resulting migrator invocation fail with a confusing error.
+ * @param archiveVersion - Semver read from `info.version`, or `'unknown'`.
+ * @returns Bracketed command string for embedding into the error message.
+ */
+function suggestMigrationScript(archiveVersion) {
+    if (archiveVersion === 'unknown' || compareSemver(archiveVersion, '0.10.0') < 0) {
+        return '`node scripts/migrate-to-0.10.mjs <path>` (then `node scripts/migrate-to-0.13.mjs <path>`)';
+    }
+    return '`node scripts/migrate-to-0.13.mjs <path>`';
+}

package/lib/migrate-content-items-alias-of-id.d.ts

@@ -0,0 +1,52 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `content_items.alias_of_id` column to archives created before
+ * this feature, then ensures its index exists.
+ *
+ * `content_items` 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 `content_items` predates this change. This
+ * mirrors {@link import('./migrate-page-meta-body-hash.js').migratePageMetaBodyHash}'s
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * Uses a raw `ALTER TABLE` (not the knex schema builder) so the retrofitted
+ * column's `REFERENCES content_items(id) DEFERRABLE INITIALLY DEFERRED`
+ * constraint matches the fresh-archive DDL bit-for-bit — the same
+ * self-referencing shape as `redirect_dest_id` (see
+ * `create-entity-tables.ts`'s JSDoc on why that FK must be deferred: a
+ * lower-id row can reference a higher-id row within the same write).
+ *
+ * The index is created here — unconditionally, after the column-add guard,
+ * not inside `createEntityTables`'s DDL — for both a fresh archive (where
+ * `alias_of_id` 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 `alias_of_id` at that point; an unconditional
+ * `CREATE INDEX ... alias_of_id` 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 compute values for
+ * existing rows (they stay `NULL`). That computation runs separately, from
+ * `backfillAliasOfId` during a viewer-read-model build, since it requires
+ * comparing every page's title and (for the trailing-slash tier) its
+ * `body_hash` against every other page.
+ *
+ * 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 `content_items`'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 migrateContentItemsAliasOfId(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-content-items-alias-of-id.js

@@ -0,0 +1,69 @@
+/**
+ * Adds the `content_items.alias_of_id` column to archives created before
+ * this feature, then ensures its index exists.
+ *
+ * `content_items` 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 `content_items` predates this change. This
+ * mirrors {@link import('./migrate-page-meta-body-hash.js').migratePageMetaBodyHash}'s
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * Uses a raw `ALTER TABLE` (not the knex schema builder) so the retrofitted
+ * column's `REFERENCES content_items(id) DEFERRABLE INITIALLY DEFERRED`
+ * constraint matches the fresh-archive DDL bit-for-bit — the same
+ * self-referencing shape as `redirect_dest_id` (see
+ * `create-entity-tables.ts`'s JSDoc on why that FK must be deferred: a
+ * lower-id row can reference a higher-id row within the same write).
+ *
+ * The index is created here — unconditionally, after the column-add guard,
+ * not inside `createEntityTables`'s DDL — for both a fresh archive (where
+ * `alias_of_id` 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 `alias_of_id` at that point; an unconditional
+ * `CREATE INDEX ... alias_of_id` 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 compute values for
+ * existing rows (they stay `NULL`). That computation runs separately, from
+ * `backfillAliasOfId` during a viewer-read-model build, since it requires
+ * comparing every page's title and (for the trailing-slash tier) its
+ * `body_hash` against every other page.
+ *
+ * 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 `content_items`'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 migrateContentItemsAliasOfId(instance, onLog) {
+    const hasContentItems = await instance.schema.hasTable('content_items');
+    if (!hasContentItems) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('content_items', 'alias_of_id');
+    if (!hasColumn) {
+        await instance.raw('ALTER TABLE content_items ADD COLUMN alias_of_id INTEGER REFERENCES content_items(id) DEFERRABLE INITIALLY DEFERRED');
+        const message = '[migrate] content_items.alias_of_id column added';
+        if (onLog) {
+            onLog(message);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.error(message);
+        }
+    }
+    await instance.raw('CREATE INDEX IF NOT EXISTS idx_content_items_alias_of_id ON content_items(alias_of_id)');
+}

package/lib/migrate-content-items-dedupe-cap-event-id.d.ts

@@ -0,0 +1,46 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `content_items.dedupe_cap_event_id` column to archives created
+ * before this feature.
+ *
+ * `content_items` 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 `content_items` predates this change. This
+ * mirrors {@link import('./migrate-content-items-alias-of-id.js').migrateContentItemsAliasOfId}'s
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * Uses a raw `ALTER TABLE` (not the knex schema builder) so the retrofitted
+ * column's `REFERENCES dedupe_cap_events(id) DEFERRABLE INITIALLY DEFERRED`
+ * constraint matches the fresh-archive DDL bit-for-bit.
+ *
+ * Unlike `migrateContentItemsAliasOfId`, this migration never creates an
+ * index for the column — `--dedupe-cap` is opt-in and the number of rows a
+ * cap event ever marks is small (capped shapes × matching URLs), so there is
+ * no measured hot path to justify one. See `createEntityTables`'s DDL
+ * comment for the same reasoning.
+ *
+ * Only adds the column — it does not compute values for existing rows (they
+ * stay `NULL`). That computation runs separately, from
+ * `backfillDedupeCapEventId` during a viewer-read-model build, since it
+ * requires recomputing `computeShapeKey` against every internal page's URL
+ * and matching it against `dedupe_cap_events.shape_key`.
+ *
+ * Idempotent: adding the column is a no-op once it exists. Guards on
+ * `content_items`'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).
+ * @example
+ * ```ts
+ * await migrateContentItemsDedupeCapEventId(knex);
+ * ```
+ */
+export declare function migrateContentItemsDedupeCapEventId(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-content-items-dedupe-cap-event-id.js

@@ -0,0 +1,62 @@
+/**
+ * Adds the `content_items.dedupe_cap_event_id` column to archives created
+ * before this feature.
+ *
+ * `content_items` 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 `content_items` predates this change. This
+ * mirrors {@link import('./migrate-content-items-alias-of-id.js').migrateContentItemsAliasOfId}'s
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * Uses a raw `ALTER TABLE` (not the knex schema builder) so the retrofitted
+ * column's `REFERENCES dedupe_cap_events(id) DEFERRABLE INITIALLY DEFERRED`
+ * constraint matches the fresh-archive DDL bit-for-bit.
+ *
+ * Unlike `migrateContentItemsAliasOfId`, this migration never creates an
+ * index for the column — `--dedupe-cap` is opt-in and the number of rows a
+ * cap event ever marks is small (capped shapes × matching URLs), so there is
+ * no measured hot path to justify one. See `createEntityTables`'s DDL
+ * comment for the same reasoning.
+ *
+ * Only adds the column — it does not compute values for existing rows (they
+ * stay `NULL`). That computation runs separately, from
+ * `backfillDedupeCapEventId` during a viewer-read-model build, since it
+ * requires recomputing `computeShapeKey` against every internal page's URL
+ * and matching it against `dedupe_cap_events.shape_key`.
+ *
+ * Idempotent: adding the column is a no-op once it exists. Guards on
+ * `content_items`'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).
+ * @example
+ * ```ts
+ * await migrateContentItemsDedupeCapEventId(knex);
+ * ```
+ */
+export async function migrateContentItemsDedupeCapEventId(instance, onLog) {
+    const hasContentItems = await instance.schema.hasTable('content_items');
+    if (!hasContentItems) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('content_items', 'dedupe_cap_event_id');
+    if (!hasColumn) {
+        await instance.raw('ALTER TABLE content_items ADD COLUMN dedupe_cap_event_id INTEGER REFERENCES dedupe_cap_events(id) DEFERRABLE INITIALLY DEFERRED');
+        const message = '[migrate] content_items.dedupe_cap_event_id column added';
+        if (onLog) {
+            onLog(message);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.error(message);
+        }
+    }
+}

package/lib/migrate-content-items-is-metadata-only.d.ts

@@ -0,0 +1,44 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `content_items.is_metadata_only` column to archives created
+ * before this feature.
+ *
+ * `content_items` 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 `content_items` predates this change. This
+ * mirrors {@link import('./migrate-content-items-dedupe-cap-event-id.js').migrateContentItemsDedupeCapEventId}'s
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * Unlike that migration, this column is `NOT NULL DEFAULT 0` (not nullable):
+ * SQLite requires a `DEFAULT` on `ALTER TABLE ... ADD COLUMN ... NOT NULL`,
+ * and the fresh-archive DDL carries the same `DEFAULT 0` so both paths stay
+ * bit-for-bit identical (see `createEntityTables`'s DDL comment). Existing
+ * rows backfill to `0` (not metadata-only) — a strict-pending row from
+ * before this migration was always resumed as a full-scrape target anyway
+ * (the bug this column fixes), so `0` preserves that prior behaviour rather
+ * than silently reclassifying already-crawled archives.
+ *
+ * No index: the only reader (`getCrawlingState`) already filters to
+ * `scraped = 0 AND is_external = 0` first, a small set. See
+ * `createEntityTables`'s DDL comment for the same "no speculative index"
+ * reasoning applied to `dedupe_cap_event_id`.
+ *
+ * Idempotent: adding the column is a no-op once it exists. Guards on
+ * `content_items`'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).
+ * @example
+ * ```ts
+ * await migrateContentItemsIsMetadataOnly(knex);
+ * ```
+ */
+export declare function migrateContentItemsIsMetadataOnly(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-content-items-is-metadata-only.js

@@ -0,0 +1,60 @@
+/**
+ * Adds the `content_items.is_metadata_only` column to archives created
+ * before this feature.
+ *
+ * `content_items` 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 `content_items` predates this change. This
+ * mirrors {@link import('./migrate-content-items-dedupe-cap-event-id.js').migrateContentItemsDedupeCapEventId}'s
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * Unlike that migration, this column is `NOT NULL DEFAULT 0` (not nullable):
+ * SQLite requires a `DEFAULT` on `ALTER TABLE ... ADD COLUMN ... NOT NULL`,
+ * and the fresh-archive DDL carries the same `DEFAULT 0` so both paths stay
+ * bit-for-bit identical (see `createEntityTables`'s DDL comment). Existing
+ * rows backfill to `0` (not metadata-only) — a strict-pending row from
+ * before this migration was always resumed as a full-scrape target anyway
+ * (the bug this column fixes), so `0` preserves that prior behaviour rather
+ * than silently reclassifying already-crawled archives.
+ *
+ * No index: the only reader (`getCrawlingState`) already filters to
+ * `scraped = 0 AND is_external = 0` first, a small set. See
+ * `createEntityTables`'s DDL comment for the same "no speculative index"
+ * reasoning applied to `dedupe_cap_event_id`.
+ *
+ * Idempotent: adding the column is a no-op once it exists. Guards on
+ * `content_items`'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).
+ * @example
+ * ```ts
+ * await migrateContentItemsIsMetadataOnly(knex);
+ * ```
+ */
+export async function migrateContentItemsIsMetadataOnly(instance, onLog) {
+    const hasContentItems = await instance.schema.hasTable('content_items');
+    if (!hasContentItems) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('content_items', 'is_metadata_only');
+    if (!hasColumn) {
+        await instance.raw('ALTER TABLE content_items ADD COLUMN is_metadata_only INTEGER NOT NULL DEFAULT 0');
+        const message = '[migrate] content_items.is_metadata_only column added';
+        if (onLog) {
+            onLog(message);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.error(message);
+        }
+    }
+}

package/lib/migrate-entity-tables.d.ts

@@ -0,0 +1,55 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the 0.13 entity / edge tables (issue #192) to archives created
+ * before the 0.13 format.
+ *
+ * These are the 6 core normalised tables (`content_items`, `page_meta`,
+ * `resource_items`, `anchor_edges`, `resource_ref_edges`, `image_items`) that
+ * replace the legacy write model in the 0.13 format. Fresh archives get
+ * them via `initSchema`; this migration is called only by
+ * `scripts/migrate-to-0.13.mjs` as its schema catch-up step for pre-0.13
+ * input archives. The archive-open path (`db-ops/lifecycle/init.ts`) does
+ * not run it — `assertCompatibleVersion` guarantees every openable
+ * archive already has the full table set.
+ *
+ * The migration is intentionally table-only. It does not back-fill any data
+ * from `pages` / `resources` / `anchors` / `images` — that is the job of the
+ * population steps (`populateRefTables` + `populateEntityTables`), which
+ * read from the legacy tables and write
+ * the entity rows in a single WAL transaction with `.bak` protection. This
+ * migration only guarantees the empty tables exist so the populate step can
+ * INSERT into them without hitting `SQLITE_ERROR: no such table:
+ * content_items`.
+ *
+ * **Blocked-by contract**: `createEntityTables` references the
+ * 0.13 ref tables (`url_refs`, `content_type_refs`, `text_refs`,
+ * `json_refs`, `blob_refs`, `header_sets`) via `REFERENCES`. On an
+ * existing archive, `migrateRefTables` MUST have run first so the
+ * ref tables exist by the time this migration is applied.
+ * `scripts/migrate-to-0.13.mjs` orders the two calls statically so this
+ * ordering is enforced there, not here.
+ *
+ * `content_items` also declares `dedupe_cap_event_id REFERENCES
+ * dedupe_cap_events(id)` — an adjunct table (`createAdjunctTables`), not a
+ * ref table. This function only creates the empty tables (schema-only, see
+ * above), so it does not itself need `dedupe_cap_events` to exist. Callers
+ * that write data into `content_items` afterward do: under `PRAGMA
+ * foreign_keys = ON`, SQLite refuses to even prepare an INSERT/UPDATE
+ * against a table with an unresolvable `REFERENCES` target, so
+ * `scripts/migrate-to-0.13.mjs` creates adjunct tables immediately after
+ * this migration and before any entity-table data write.
+ *
+ * **Idempotency**: `createEntityTables` itself uses
+ * `CREATE TABLE IF NOT EXISTS` / `CREATE INDEX IF NOT EXISTS` for every
+ * statement, so calling it multiple times against any DB state is safe.
+ * That means this wrapper does not need a defensive sentinel — the
+ * "content_items exists but page_meta was dropped externally" partial-
+ * corruption case is fully repaired on next open because every CREATE
+ * statement individually checks its own existence. The one thing the
+ * wrapper adds beyond the primitive is a log line, which we still want
+ * to emit only when creation actually happened, so we probe
+ * `content_items` first and short-circuit when the schema is already
+ * fully installed.
+ * @param instance - The Knex query builder instance connected to the database.
+ */
+export declare function migrateEntityTables(instance: Knex): Promise<void>;

package/lib/migrate-entity-tables.js

@@ -0,0 +1,66 @@
+import { createEntityTables } from './create-entity-tables.js';
+/**
+ * Adds the 0.13 entity / edge tables (issue #192) to archives created
+ * before the 0.13 format.
+ *
+ * These are the 6 core normalised tables (`content_items`, `page_meta`,
+ * `resource_items`, `anchor_edges`, `resource_ref_edges`, `image_items`) that
+ * replace the legacy write model in the 0.13 format. Fresh archives get
+ * them via `initSchema`; this migration is called only by
+ * `scripts/migrate-to-0.13.mjs` as its schema catch-up step for pre-0.13
+ * input archives. The archive-open path (`db-ops/lifecycle/init.ts`) does
+ * not run it — `assertCompatibleVersion` guarantees every openable
+ * archive already has the full table set.
+ *
+ * The migration is intentionally table-only. It does not back-fill any data
+ * from `pages` / `resources` / `anchors` / `images` — that is the job of the
+ * population steps (`populateRefTables` + `populateEntityTables`), which
+ * read from the legacy tables and write
+ * the entity rows in a single WAL transaction with `.bak` protection. This
+ * migration only guarantees the empty tables exist so the populate step can
+ * INSERT into them without hitting `SQLITE_ERROR: no such table:
+ * content_items`.
+ *
+ * **Blocked-by contract**: `createEntityTables` references the
+ * 0.13 ref tables (`url_refs`, `content_type_refs`, `text_refs`,
+ * `json_refs`, `blob_refs`, `header_sets`) via `REFERENCES`. On an
+ * existing archive, `migrateRefTables` MUST have run first so the
+ * ref tables exist by the time this migration is applied.
+ * `scripts/migrate-to-0.13.mjs` orders the two calls statically so this
+ * ordering is enforced there, not here.
+ *
+ * `content_items` also declares `dedupe_cap_event_id REFERENCES
+ * dedupe_cap_events(id)` — an adjunct table (`createAdjunctTables`), not a
+ * ref table. This function only creates the empty tables (schema-only, see
+ * above), so it does not itself need `dedupe_cap_events` to exist. Callers
+ * that write data into `content_items` afterward do: under `PRAGMA
+ * foreign_keys = ON`, SQLite refuses to even prepare an INSERT/UPDATE
+ * against a table with an unresolvable `REFERENCES` target, so
+ * `scripts/migrate-to-0.13.mjs` creates adjunct tables immediately after
+ * this migration and before any entity-table data write.
+ *
+ * **Idempotency**: `createEntityTables` itself uses
+ * `CREATE TABLE IF NOT EXISTS` / `CREATE INDEX IF NOT EXISTS` for every
+ * statement, so calling it multiple times against any DB state is safe.
+ * That means this wrapper does not need a defensive sentinel — the
+ * "content_items exists but page_meta was dropped externally" partial-
+ * corruption case is fully repaired on next open because every CREATE
+ * statement individually checks its own existence. The one thing the
+ * wrapper adds beyond the primitive is a log line, which we still want
+ * to emit only when creation actually happened, so we probe
+ * `content_items` first and short-circuit when the schema is already
+ * fully installed.
+ * @param instance - The Knex query builder instance connected to the database.
+ */
+export async function migrateEntityTables(instance) {
+    const hasContentItems = await instance.schema.hasTable('content_items');
+    if (hasContentItems) {
+        // Fast path: fully installed. `createEntityTables` would
+        // still be a safe no-op, but re-running it just to be defensive
+        // wastes 15 IF NOT EXISTS round-trips on every archive open.
+        return;
+    }
+    await createEntityTables(instance);
+    // eslint-disable-next-line no-console
+    console.error('[migrate] 0.13 entity/edge tables created');
+}

package/lib/migrate-info-created-cwd.d.ts

@@ -0,0 +1,17 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `info.createdCwd` 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. A stub missing this column simply falls back to
+ * `Archive.resume`'s own `process.cwd()`, same as before this column existed.
+ * @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 migrateInfoCreatedCwd(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-info-created-cwd.js

@@ -0,0 +1,36 @@
+/**
+ * Adds the `info.createdCwd` 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. A stub missing this column simply falls back to
+ * `Archive.resume`'s own `process.cwd()`, same as before this column existed.
+ * @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 migrateInfoCreatedCwd(instance, onLog) {
+    const hasInfo = await instance.schema.hasTable('info');
+    if (!hasInfo) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('info', 'createdCwd');
+    if (hasColumn) {
+        return;
+    }
+    await instance.schema.table('info', (t) => {
+        t.string('createdCwd');
+    });
+    const message = '[migrate] info.createdCwd column added';
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/migrate-info-main-content-selector.d.ts

@@ -0,0 +1,16 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `info.mainContentSelector` 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 declare function migrateInfoMainContentSelector(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/migrate-info-main-content-selector.js

@@ -0,0 +1,35 @@
+/**
+ * Adds the `info.mainContentSelector` 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 migrateInfoMainContentSelector(instance, onLog) {
+    const hasInfo = await instance.schema.hasTable('info');
+    if (!hasInfo) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('info', 'mainContentSelector');
+    if (hasColumn) {
+        return;
+    }
+    await instance.schema.table('info', (t) => {
+        t.string('mainContentSelector');
+    });
+    const message = '[migrate] info.mainContentSelector column added';
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/migrate-info-request-header-names.d.ts

@@ -0,0 +1,16 @@
+import type { Knex } from 'knex';
+/**
+ * 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 declare function migrateInfoRequestHeaderNames(instance: Knex, onLog?: (message: string) => void): Promise<void>;