skarbiec upgrade

Invocation#

skarbiec upgrade [--apply] [--snapshot <path>]

Purpose#

Bring the configured vault to the current schema in one idempotent pass: the v2 envelope for its items and grants, a permanent item_uid on every item, and a payload fingerprint on every active item, so the duplicate report and the duplicate refusal cover the whole vault.

Required inputs and options#

• No positional input. Without --apply it reports what the pass would change and writes nothing. --snapshot names the backup path the envelope migration is preceded by; otherwise a timestamped path beside the vault is chosen.

Output and state effects#

• Prints ok, applied, vault, and three sections. envelope: from, to, needed and, once applied, snapshot plus item, revision and grant counts. item_uids: items and, before applying, missing with the ids; once applied, stamped with the ids; the vault is saved once and only when something changed, and item-uids-backfilled is appended when it stamped anything. fingerprints: applied, stamped, the stamped ids, already_stamped, and one entry per unreadable item with the error its decryption gave. The envelope migration rewrites the file after a mode-0600 snapshot; the identifier and fingerprint steps touch the cleartext envelope only, so no payload is re-encrypted, no item gains a revision, and revision, updated_at and current stay as they were. A vault with no fingerprint salt has one minted; an existing salt always wins. Each step skips what already has it, so a second run changes nothing and reports zero.

Refusals#

• upgrade snapshot already exists: <path>; name another with --snapshot; open vault snapshot source <path> and create upgrade snapshot <path> with the cause when the file cannot be copied; migrate item <id>: <cause> and migration produces duplicate canonical item id: <id> when the envelope migration cannot be completed, in which case the snapshot is what to restore. An item it cannot decrypt is reported with that item's own error instead of being skipped silently, and an item whose fingerprint matches another is stamped rather than refused, because finding those pairs is what the pass is for. Fails when the configured vault cannot be opened or saved.