Coldkeep v1.13.7 — SQLite-First Repository Portability Baseline

[franchoy]

Coldkeep v1.13.7 — SQLite-First Repository Portability Baseline

Coldkeep v1.13.7 establishes the contract and executable evidence required for a future SQLite-first, directory-portable local repository while preserving PostgreSQL as the current normal runtime backend.

This release defines repository portability as a complete catalog-plus-payload invariant rather than treating the SQLite catalog file as independently portable.

Highlights

• Inventoried the current repository initialization and backend-selection behavior.

• Defined the future local SQLite catalog target:

  <repository-root>/.coldkeep/catalog.sqlite
  

• Defined repository portability across:

  • catalog state
  • payload storage
  • clean closure and reopen
  • verification
  • restoration
  • encryption and external-key boundaries
  • failure and refusal behavior

• Reviewed existing SQLite and PostgreSQL compatibility evidence.

• Added direct repository-root relocation coverage.

• Corrected a real migration-idempotency defect discovered by the new portability guard.

• Preserved existing CLI, backend-default, storage-format, repository-format, and output contracts.

Migration-idempotency correction

The initial relocation guard exposed a schema-reopen defect in the physical_file compatibility backfill.

On repeated migration, an already-mapped logical file could receive an additional synthetic physical mapping. This increased the number of physical_file rows without updating logical_file.ref_count, causing repository verification to fail correctly.

The SQLite and PostgreSQL backfills now create a synthetic physical mapping only when a logical file has no existing physical mappings.

The correction preserves:

• existing physical mappings
• multiple physical mappings for one logical file
• legacy unmapped logical-file backfill
• ref-count mismatch detection
• SQLite/PostgreSQL catalog semantics

No schema version, storage format, or repository format changed.

Direct portability evidence

The new TestSQLiteRepositoryRelocationReopenVerifyRestoreIntegration guard proves through explicit SQLite test seams that Coldkeep can:

1. create a file-backed SQLite catalog under .coldkeep/catalog.sqlite
2. store payload data under a repository-owned containers/ directory
3. store and verify representative content
4. cleanly close the repository
5. rename the complete repository root
6. reopen using destination paths only
7. rerun migrations without mutating valid physical mappings
8. verify the relocated catalog and payload
9. restore the stored file
10. reproduce the original bytes exactly
11. operate without the original repository root

Current backend posture

This release does not switch Coldkeep to SQLite as its normal runtime backend.

• PostgreSQL remains the current normal local runtime backend.
• COLDKEEP_STORAGE_CONTEXT=local remains PostgreSQL-backed.
• SQLite remains simulated/test-only in normal production startup.
• coldkeep init does not create a local SQLite repository.
• PostgreSQL remains supported and mandatory in release validation.
• SQLite-first does not mean SQLite-only.

The SQLite repository layout defined by this release is a future contract target and a test-proven seam, not yet a user-facing runtime mode.

Not included

v1.13.7 does not add:

• a normal SQLite local runtime mode
• an SQLite backend-default transition
• automatic repository-root discovery
• repository move or copy commands
• live-copy guarantees
• recursive-copy validation
• interrupted-copy recovery
• repository identity or writable clone semantics
• snapshot relocation matrices
• codec relocation matrices
• packed/legacy relocation matrices
• cross-platform relocation guarantees
• PostgreSQL backup or restore automation

Validation

The complete pre-release Profile A gate passed, including:

• live PostgreSQL schema-rerun validation
• SQLite migration-idempotency regressions
• repository relocation integration coverage
• targeted and full race validation
• Go formatting, vet, and lint checks
• plain and AES-GCM integration matrices
• stress and long-running lifecycle suites
• ref-count containment tests
• adversarial suites
• smoke tests for both codecs
• benchmark regression checks
• legacy compatibility validation
• local cross-platform approximation
• critical coverage reporting
• snapshot release gate

All required pull-request checks passed, including the authoritative CI benchmark results, Codacy, CodeQL, and cross-platform validation.

The full main branch CI also passed after merge.

Compatibility

No manual migration or configuration change is required when upgrading.

Existing PostgreSQL deployments, schemas, payload formats, CLI commands, JSON contracts, and stored repositories remain compatible.

Next release

The planned next release is:

v1.13.8 — Restore / Remove Contract Split and Stored-Path Boundary

It will focus on separating restore and removal semantics and clarifying ownership of logical paths, physical mappings, repository payload locations, restore destinations, snapshot retention, and removal selectors.

---

This discussion was created from the release Coldkeep v1.13.7 — SQLite-First Repository Portability Baseline.