hired.persistence.migrate#

One-time migration of legacy flat per-user data to the Storage v2 layout.

Storage v1 kept every store kind flat under users/<user>/<kind>/ with extension-less files. Storage v2 (see hired.persistence.base) splits the data into a cross-JD user/ subtree and per-engagement jds/<jd_id>/ subtrees, and gives every file a proper extension.

This module moves the data once, idempotently:

  • facts/ qa/ → user/info/<kind>/<name>.json

  • uploads/ → user/raw/<name> (filename kept)

  • synopsis/synopsis.md → user/info/synopsis.md

  • jobs/ reports/ report_history/ company/ interview_prep/

    → jds/<jd_id>/<kind>/<rel>.json

Engagements are grouped by company when company research seeds the slugs: if a company/<slug> entry exists (or a prior partial run already created jds/<slug>/), all items whose key equals <slug> or starts with <slug>- land in that company’s single workspace (so a company’s several role reports + its shared research + prep stay together). Without any such seed, each top-level key becomes its own engagement; pass a custom company_of to force grouping.

The migration is resumable: it is gated on “any legacy directory remains”, moves files individually, refuses to overwrite an existing destination, and removes the empty legacy directories only after every move succeeds. So an interrupted run (crash, disk-full) is simply re-run — already-moved files are skipped and the remaining ones complete. The intelligence of the package is unaffected — this is deterministic file plumbing, run automatically via ensure_v2() on first v2 access, or explicitly (with migrate_user_to_v2(), optionally dry_run=True).

Functions

ensure_v2([user, root])

Migrate the user to v2 if a legacy layout is detected.

is_legacy_layout([user, root])

True iff any legacy v1 flat directory remains for this user.

migrate_user_to_v2([user, root, company_of, ...])

Migrate one user's flat v1 data to the v2 layout.
hired.persistence.migrate.ensure_v2(user='me', *, root=None)[source]#

Migrate the user to v2 if a legacy layout is detected. Returns True if migrated.

Return type:

bool

hired.persistence.migrate.is_legacy_layout(user='me', *, root=None)[source]#

True iff any legacy v1 flat directory remains for this user.

Gated on the presence of legacy dirs, not on the existence of user/ — a fully-migrated user has had its legacy dirs removed, so this returns False; a partially-migrated (interrupted) user still has some, so a re-run resumes.

Return type:

bool

hired.persistence.migrate.migrate_user_to_v2(user='me', *, root=None, company_of=None, dry_run=False)[source]#

Migrate one user’s flat v1 data to the v2 layout. Returns the move plan.

Idempotent: a no-op (empty plan) if the user is already on v2 or has no legacy data. With dry_run=True nothing is moved — the returned [(src, dst), ...] plan can be inspected first.

Return type:

list[tuple[str, str]]