Skip to content

feat: membook migrate — the write half of the version machinery#28

Merged
hiranofficial merged 1 commit into
mainfrom
feat/v02-version-machinery
Jul 26, 2026
Merged

feat: membook migrate — the write half of the version machinery#28
hiranofficial merged 1 commit into
mainfrom
feat/v02-version-machinery

Conversation

@hiranofficial

Copy link
Copy Markdown
Contributor

Step 0 of the v0.2 sequence (docs/design/v0.2-workspaces.md §9): the version machinery lands before `xgit` forces the memfile bump in anger. The read half (dispatch, tolerance, the future-file error) already existed; this is the write half.

What

  • `Memfile.version` (spec): `parseMemfile` now reports the version a file declared on disk. After read-widening it is the only remaining trace of what the file actually said — `migrate` and `status` cannot recover it from the frontmatter shape.
  • `membook migrate [--dry-run]`: rewrites every memory to the current canonical form in one pass a human reviews and commits. Older versions come forward (parse → re-emit at current, no upgrade chain — the per-version schemas already widen), and hand-drifted files return to canonical serialization, which is the same promise kept by the same rewrite: canonical bytes are what keep every future diff clean.
  • What it cannot read, it does not touch: malformed files stay in place and are reported; a file from a newer Membook is skipped with its version named, never downgraded by an older tool.
  • `membook status` reports the version spread (`byVersion`, `belowCurrent`) as information, not a health warning — mixed-version stores stay legal indefinitely, per the ruling.
  • Instrumentation: a `migrate` event on every non-dry pass, including the found-nothing case — the only way the log can tell an unmigrated store from an unexamined one.

Honesty note

With only memfile v1 in existence, the older-version branch cannot be exercised against a real old file yet; the golden v1-under-v2 fixture lands with the bump itself (design §9). What is proven today: convergence (rewrite → byte-identical canonical → second pass finds nothing), dry-run writes nothing, future files and malformed files untouched, and the pass reindexes.

Verified

  • 474 tests green across the four packages, including a real-binary test (drift a file → `node dist/cli.js migrate` → exact canonical bytes restored).
  • Live on this repo's own store: `migrate --dry-run` reports all 11 memories already canonical; hand-drifting a committed memory and running a real `migrate` restored it to a clean `git status`, byte for byte.

Commit is unsigned — the ssh-agent had no key in this session.

@hiranofficial
hiranofficial merged commit 47f6d4e into main Jul 26, 2026
15 checks passed
@hiranofficial
hiranofficial deleted the feat/v02-version-machinery branch July 26, 2026 19:41
@github-actions github-actions Bot mentioned this pull request Jul 26, 2026
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