Safely restore one ordinary ZCode chat session from an old db.sqlite, then undo that exact restore if it was a mistake.
This is not a whole-database merge tool. It is deliberately conservative: incompatible schemas, existing sessions, key conflicts, workflow links, unknown associations, and partial recovery conditions stop the operation before writing.
- Dry-run by default. Only an explicit
--applychanges a database. - The source database is opened read-only.
- The target database is backed up with SQLite's online Backup API before every write.
- Ordinary
INSERTis used; conflicts are never silently ignored. - A JSON receipt records table names, primary keys, row hashes, counts, and backup paths—not message bodies.
- Undo verifies every restored row is unchanged and checks declared and semantic dependencies before deleting anything.
- Applied operations on the same target are serialized with a cross-process
.rescue.lockfile beside the target database. - Unrecognized triggers and cascading/
SET NULLforeign-key actions are rejected. Built-in ZCode guard/sequence triggers and official delete-action relationships are supported. AUTOINCREMENTrestore tables and NULL primary-key components are rejected in this version.- Crash states (
preparedandundo_prepared) can be reconciled on the next run. - No telemetry, upload, auto-update, or network access.
Backups contain the complete target database and are sensitive. Receipts contain local paths and session/row identifiers. Store both with the same care as the original database.
The first version supports ordinary chats whose records are contained in db.sqlite, including dynamically discovered session-owned tables and composite primary keys.
It does not currently restore:
- workflow or DWF runs;
- parent/child session trees or cross-session task links;
tasks-index.sqlite, rollout files, artifacts, or workspace files;- damaged SQLite databases;
- sessions that already exist in the target.
Runtime-presence rows are intentionally excluded. Purged or otherwise unsupported sessions are rejected rather than partially restored.
- Python 3.11 or later.
- A source ZCode SQLite backup and an existing target
db.sqlite. - Close every ZCode instance that could write the target before using
--apply.
python -m pip install .For development, install in editable mode:
python -m pip install -e .zcode-session-rescue list --source OLD_DBThis prints session IDs, titles, timestamps, and message counts without printing message bodies.
zcode-session-rescue check \
--source OLD_DB \
--target TARGET_DB \
--session SESSION_IDThe check is read-only. It reports the selected tables and row counts or explains why the restore is refused.
Close ZCode first. Run without --apply to repeat the dry-run:
zcode-session-rescue restore \
--source OLD_DB \
--target TARGET_DB \
--session SESSION_ID \
--operations-dir OUTPUT_DIRAfter reviewing the plan, apply it deliberately:
zcode-session-rescue restore \
--source OLD_DB \
--target TARGET_DB \
--session SESSION_ID \
--operations-dir OUTPUT_DIR \
--applyEach applied operation creates a unique directory containing:
target-before.sqlite: the pre-restore backup;receipt.json: the operation plan, row hashes, and final status.
Do not delete or edit the receipt if you may need undo.
Close ZCode first. Check undo without changing anything:
zcode-session-rescue undo --receipt RECEIPT_JSONApply undo only when every restored row is unchanged and no new dependency blocks deletion:
zcode-session-rescue undo --receipt RECEIPT_JSON --applyIf you opened the restored session and ZCode modified it, or continued the conversation, undo is expected to refuse. Use the pre-restore backup for a deliberate whole-database rollback instead; that is a separate operation and is not performed automatically.
Add --json to any command for machine-readable output:
zcode-session-rescue check \
--source OLD_DB \
--target TARGET_DB \
--session SESSION_ID \
--json0: successful command or dry-run;1: safety, validation, or operation error;2: command-line usage error.
python -m unittest discover -s tests -t . -vTests build temporary synthetic ZCode databases. They never require or modify a real user database.
Current validation covers schema inspection, composite keys, BLOB and Unicode values, conflicts, rollback, backup integrity, receipt crash states, exact undo, semantic dependencies, CLI behavior, and special-character paths.
Not yet accepted: opening a restored session in the real ZCode application, continuing that conversation, and GUI-level behavior. Those require a separate real-host acceptance pass.
MIT. See LICENSE.