content-script DB fix (PR #869) doesn't reach the real extension, and getExistingDB() throws on a never-visited-app profile

Start in src/lib/storage/db.ts and read getExistingDB(), then inspect src/lib/storage/db.test.ts and the existing FromExisting/IntoExisting helpers in crud.ts and capture.ts. Run the storage tests and add coverage for a real operation against a freshly deleted database. Review extension/src/offlinecv-core.ts and extension/offlinecv-pin.json for the separate integration work; done requires the fallback, updated documentation, passing tests, and the pinned extension resolving content-script calls to the existing-database variants.

Problem

PR #869 (fix/content-script-db-open-without-version, chore(db): open database without version parameters in content script to prevent upgrade hangs) set out to fix a real bug: the browser extension's content script calls this repo's storage functions, which open IndexedDB via getDB() at this repo's pinned DB_VERSION. If the extension's pinned commit is ahead of a stale, still-open offlinecv.org app tab, that version-mismatch open triggers an upgrade transaction that hangs waiting for the stale tab's connection to close — the content script hangs silently mid-capture.

The PR's fix (getExistingDB() in src/lib/storage/db.ts, plus a …FromExisting/…IntoExisting sibling for every content-script-reachable function) is the right shape of fix, but as merged it has two confirmed defects that mean the hang is not actually closed, and a new failure mode is introduced in its place. Both were found and verified during the /pr-review of PR #869 (review: https://github.com/offlinecv/OfflineCV/pull/869#pullrequestreview-4967949091, head SHA 1ce06ba70d4480f91ff15375640a87f32f42580e).

Defect 1 — the fix never reaches the real, pinned extension

packages/core/src/index.ts renames the barrel's re-exports (captureJob, getRecord, putRecord, deleteRecord, listRecordsUpdatedSince, getSyncCursor, setSyncCursor, listResumeChoices) to point at the new …FromExisting/…IntoExisting variants, under a docblock claiming this "keeps extension2/src/offlinecv-core.ts unchanged" (packages/core/src/index.ts:264), and src/lib/storage/db.ts:41 claims "the browser extension no longer calls this function directly."

Neither claim holds for the one real, pinned extension checkout present in this repo tree: extension/ (nested, gitignored, pinned via extension/offlinecv-pin.json to 116-Ideas/recruidea-extension, pin SHA acc841133f13b9ff26b6b8e8e99dad68e088dd22 as of PR #869's merge base). No extension2 directory exists anywhere in this repo — grep -rn "extension2" packages src docs outside packages/core/src/index.ts's own new comment returns nothing.

The real extension's own barrel, extension/src/offlinecv-core.ts, re-exports captureJob/getRecord/putRecord/deleteRecord/listRecordsUpdatedSince/getSyncCursor/setSyncCursor/listResumeChoices directly from ../../src/lib/storage/*.ts by relative import — never through the @offlinecv/core npm package. grep -rn "@offlinecv/core" extension/src returns zero matches. Concretely:

• extension/src/offlinecv-core.ts:43 — export { captureJob, type JobCaptureResult } from "../../src/lib/storage/capture.ts"; (the plain, unrenamed captureJob, not captureJobIntoExisting)
• extension/src/offlinecv-core.ts:107 — same pattern for getRecord/putRecord/deleteRecord/listRecordsUpdatedSince from crud.ts
• extension/src/offlinecv-core.ts:109 — export { getSyncCursor, setSyncCursor } from "../../src/lib/storage/sync-cursor.ts";
• extension/src/offlinecv-core.ts:148 — export { listResumeChoices, type ResumeChoice } from "../../src/lib/storage/resumes.ts";
• extension/src/capture/drain.ts:47 — import { captureJob, type JobCaptureResult } from "../offlinecv-core.ts";, then export function createDrainer(write: CaptureWriter = captureJob) — the extension's actual capture pipeline, calling the un-fixed captureJob

So after PR #869, the extension's real capture pipeline (drain.ts → captureJob → capture.ts's plain captureJob → getJob/saveJob → getRecord/putRecord → getDB()) is unchanged: it still opens at DB_VERSION and can still trigger the exact upgrade-transaction hang PR #869 was filed to close. Nothing in PR #869 touches extension/src/offlinecv-core.ts's imports, and nothing bumps extension/offlinecv-pin.json.

Defect 2 — getExistingDB() throws instead of "reading defensively as empty" on a never-visited-app profile

src/lib/storage/db.ts's new getExistingDB() (added in PR #869) opens indexedDB with no version argument, which is correct for its stated purpose (never trigger an upgrade). Its docblock (src/lib/storage/db.ts:154) also documents the one edge case it knows about — a profile where the app database doesn't exist yet (only the extension has ever been used there) — and claims: "Every caller here already reads a missing store defensively, and that empty-library reading is correct."

That claim is false. When the database doesn't exist yet, openDB(DB_NAME) (no version, no upgrade callback) creates an empty database at version 1 with zero object stores — IndexedDB always fires upgradeneeded going from "no database" to version 1, but since getExistingDB() passes no upgrade callback, nothing runs to create any stores. Every subsequent store operation (db.get, db.put, db.getAll, db.delete) against a store name that isn't in that empty database throws a synchronous NotFoundError — it does not resolve to undefined/[].

Verified directly, first with a minimal repro against raw idb/fake-indexeddb:

NotFoundError: No objectStore named jobs in this database

then end-to-end through the real code path (a temporary test calling captureJobIntoExisting against a freshly-deleted database):

NotFoundError: No objectStore named jobs in this database
 ❯ new NotFoundError node_modules/fake-indexeddb/build/esm/lib/errors.js:59:5
 ❯ FDBDatabase.transaction node_modules/fake-indexeddb/build/esm/FDBDatabase.js:146:15
 ❯ Proxy.method node_modules/idb/build/index.js:228:25
 ❯ getRecordFromExisting src/lib/storage/crud.ts:211:20
 ❯ getJobFromExisting src/lib/storage/jobs.ts:78:18
 ❯ captureJobVia src/lib/storage/capture.ts:140:20

src/lib/storage/db.test.ts's "creates an empty v1 database rather than upgrading, when none exists yet" test only asserts db.version and objectStoreNames — it never calls get/put/getAll/delete against that empty database, so it documents the empty-DB shape without ever exercising this throw. No test in the PR calls a real crud/capture function (captureJobIntoExisting, getRecordFromExisting, putRecordIntoExisting, etc.) against a database that doesn't exist yet.

Failure scenario (both defects combined)

A user installs the browser extension and captures a job posting before ever opening offlinecv.org in that browser profile (or after clearing site data) — a normal first-use path, and the exact case getExistingDB()'s own docblock calls out by name. Today (pre-#869) that capture hangs silently, mid-request, forever. After #869 lands as merged, once the extension repo eventually picks up a version that calls the new …FromExisting/…IntoExisting functions (defect 1 blocks this from happening automatically), the same capture will throw NotFoundError instead of hanging — a different symptom, still a broken capture, with the underlying database left in a broken empty-v1 state that also blocks the app's own later migration path from working normally (needs verification — see Acceptance Criteria).

Root cause

• Defect 1: @offlinecv/core (packages/core/src/index.ts) is a barrel the extension repo could consume, but is not the one the currently-pinned extension actually consumes. The real extension has its own, independently-maintained mirror barrel (extension/src/offlinecv-core.ts) that imports straight from src/lib/storage/*.ts by relative path, bypassing @offlinecv/core (and therefore this fix) entirely. PR #869 only edited the barrel nobody imports.
• Defect 2: getExistingDB() (src/lib/storage/db.ts:158) never runs upgrade(), so a database created fresh by this function has no object stores; every downstream caller (crud.ts's looseDB-based helpers, sync-cursor.ts) assumes IndexedDB reads/writes against a missing store degrade gracefully, but idb/native IndexedDB throw NotFoundError instead.

Implementation plan

1. Fix defect 2 first (self-contained, no cross-repo dependency). In src/lib/storage/db.ts, change getExistingDB() to detect the store-less/nonexistent-database case and fall back to the full, versioned getDB() opener in that branch:

   export async function getExistingDB(): Promise<IDBPDatabase<OfflineCvDB>> {
     if (existingDbPromise === null) {
       existingDbPromise = openDB<OfflineCvDB>(DB_NAME).then((db) => {
         if (db.objectStoreNames.length === 0) {
           db.close();
           return getDB(); // no stale-open-tab hang risk: nothing else can hold a connection to a database that doesn't exist yet
         }
         return db;
       });
     }
     return existingDbPromise;
   }
   

   Confirm this doesn't reintroduce the original hang: the fallback only triggers when the database is empty/nonexistent, which is precisely the case where no other connection (stale app tab or otherwise) can be holding it open, so getDB()'s versioned open+upgrade can't block on anything.
   Update the docblock at src/lib/storage/db.ts:154 to describe the actual fallback behavior instead of the false "reads defensively as empty" claim.
   Add a test to src/lib/storage/db.test.ts that calls a real crud/capture function (e.g. getRecordFromExisting("jobs", "some-id") or captureJobIntoExisting({...})) against a freshly-deleted database, asserting it resolves instead of throwing.

2. Fix defect 1 (cross-repo coordination — this is the part that actually closes the extension hang). This repo (offlinecv/OfflineCV) cannot single-handedly fix defect 1: the fix lives in the private 116-Ideas/recruidea-extension repo, checked out here at extension/.

   • In extension/src/offlinecv-core.ts, repoint every re-export this file currently takes from src/lib/storage/*.ts to the …FromExisting/…IntoExisting variant, matching what packages/core/src/index.ts already does (or import from @offlinecv/core directly instead of mirroring individual files, if that refactor is in scope).
   • Bump extension/offlinecv-pin.json's sha to a commit of offlinecv/OfflineCV that includes both this issue's fix and PR #869, and rebuild.
   • Confirm via grep -rn "@offlinecv/core" extension/src (if switching to the package) or a direct read of extension/src/offlinecv-core.ts (if keeping the mirror pattern) that every content-script-reachable function now resolves to a …FromExisting/…IntoExisting variant.
   • This step happens in the extension repo, not here — this offlinecv/OfflineCV issue tracks it because the pin file and its own docblock (src/lib/storage/db.ts DB_VERSION comment) are the only drift alarm this repo has; close this issue only once the extension repo's PR has landed and the pin is bumped.

3. Restore the actionable pin-bump instruction. src/lib/storage/db.ts's DB_VERSION docblock (currently starting ⚠️ Still worth bumping deliberately even though the browser extension no longer calls this function directly...) should go back to naming the concrete action once defect 1 is actually resolved — point at extension/offlinecv-pin.json and state plainly that this repo's CI never compiles the extension, so nothing else will catch a drift.

Acceptance criteria

• getExistingDB() falls back to getDB() when the opened database has zero object stores, and a test in src/lib/storage/db.test.ts calls a real crud/capture function (not just getExistingDB() itself) against a freshly-deleted database and asserts it succeeds instead of throwing NotFoundError.
• The fallback is verified not to reintroduce the original upgrade-transaction hang (e.g. a test or written justification that no other connection can be open against a database that doesn't exist yet).
• src/lib/storage/db.ts's getExistingDB() docblock no longer claims callers "already read a missing store defensively" — it describes the actual fallback behavior.
• extension/src/offlinecv-core.ts (in the 116-Ideas/recruidea-extension repo) repoints its re-exports to the …FromExisting/…IntoExisting variants (or to @offlinecv/core directly), verified by reading the file or grep -rn "@offlinecv/core" extension/src.
• extension/offlinecv-pin.json's sha is bumped to a commit that includes both this fix and PR #869, on its own commit per the pin file's existing convention.
• src/lib/storage/db.ts's DB_VERSION docblock once again names the concrete pin-bump action and points at extension/offlinecv-pin.json.
• Existing suite still green: npx vitest run src/lib/storage/ (277+ tests as of PR #869) and npm run check:core.
• No regression to the app's own (non-extension) getDB() call sites — they are untouched by this issue's scope.

References

• PR #869: https://github.com/offlinecv/OfflineCV/pull/869 (fix/content-script-db-open-without-version, head SHA 1ce06ba70d4480f91ff15375640a87f32f42580e)
• Review with full findings: https://github.com/offlinecv/OfflineCV/pull/869#pullrequestreview-4967949091
• src/lib/storage/db.ts — getExistingDB(), DB_VERSION docblock
• src/lib/storage/crud.ts — getRecordFromExisting, putRecordIntoExisting, getAllRecordsFromExisting, listRecordsUpdatedSinceFromExisting, deleteRecordFromExisting
• packages/core/src/index.ts — the barrel PR #869 edited (not the one the real extension consumes)
• extension/src/offlinecv-core.ts, extension/src/capture/drain.ts — the real extension's barrel and capture pipeline (private repo 116-Ideas/recruidea-extension, nested/gitignored checkout)
• extension/offlinecv-pin.json — the pin file that needs bumping once the extension-side fix lands