Skip to content

feat(lockfile): switch drift.lock to versioned TOML array-of-tables format#30

Merged
laulauland merged 2 commits into
mainfrom
lau/lockfile-toml-format
May 8, 2026
Merged

feat(lockfile): switch drift.lock to versioned TOML array-of-tables format#30
laulauland merged 2 commits into
mainfrom
lau/lockfile-toml-format

Conversation

@laulauland
Copy link
Copy Markdown
Member

Summary

drift.lock now uses a versioned TOML format:

version = 1

[[bindings]]
doc = "docs/auth.md"
target = "src/auth/login.ts"
sig = "a1b2c3d4e5f6a7b8"

The new format reduces spurious merge conflicts on disjoint edits (each binding is a separate block with its own metadata) and adds explicit lockfile versioning for future migrations.

Compatibility

  • Existing pre-TOML lockfiles are still readable: drift check, drift status, and drift refs parse the legacy line-based format unchanged.
  • The next mutating command (drift link, drift unlink) rewrites drift.lock to version = 1 TOML.
  • After that rewrite, older drift binaries can no longer read the lockfile. Teams pinning drift in CI or dev environments should upgrade all installations together before running commands that modify drift.lock.

Doc updates

  • README.md — TOML examples for the lockfile and origin-qualified anchors
  • docs/DESIGN.md — TOML data model, on-disk format section, and lockfile.zig description
  • docs/DECISIONS.md — new §11 covering format, canonical sort, and forward-compat parser rules
  • .claude/skills/drift/SKILL.md — TOML anchor and origin examples
  • docs/CLI.mddrift link description references the TOML lockfile

Test plan

  • zig build test — all 293 tests pass, including new TOML parser/serializer tests, version handling, and the legacy-line-format compatibility test
  • drift check clean on this repo's own (already-rewritten) drift.lock
  • Property tests in the merge oracle confirmed the format substantially reduces spurious merge conflicts vs. the line format

laulauland added 2 commits May 7, 2026 10:48
…ormat

drift.lock now uses TOML with `version = 1` and `[[bindings]]` tables.
Each binding is a separate block with its own metadata, which reduces
spurious merge conflicts on disjoint edits and adds explicit version
tagging for future migrations.

Compatibility:
- drift check, drift status, and drift refs still read the legacy
  line-based format; pre-TOML lockfiles work unchanged.
- The next mutating command (drift link, drift unlink) rewrites
  drift.lock to TOML.
- After that rewrite, older drift binaries can no longer read the
  lockfile. Teams pinning drift in CI or dev environments should
  upgrade all installations together before running commands that
  modify drift.lock.
Require version = 1 for TOML lockfiles, reject unsupported or out-of-subset TOML constructs, and add basic-string escaping/decoding for lockfile values.
@laulauland laulauland merged commit a2524c6 into main May 8, 2026
5 checks passed
@laulauland laulauland deleted the lau/lockfile-toml-format branch May 8, 2026 14:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant