isomorphic-jj 1.8.0 → 1.9.2

package/CHANGELOG.md

@@ -1,5 +1,376 @@
 # Changelog
 
+## 1.9.2 — 2026-09-26 — auto-snapshot mtime comparison (#41)
+
+### Fixed
+
+- **`getModifiedFiles()`/`snapshot()` no longer treat every previously-tracked
+  file as "modified" on every call (#41).** Both compared `fs.stat().mtime`
+  values with `!==`. `mtime` is a `Date`, and `fs.promises.stat()` returns a
+  fresh `Date` instance on every call — two stats of the same, unchanged file
+  are never `===`/`!==`-equal even when the underlying timestamp is
+  identical (object identity, not value equality). Fixed by normalizing both
+  sides through a new `mtimeMs()` helper before comparing, and by storing
+  tracked mtimes as plain epoch-ms numbers going forward (numbers round-trip
+  through the JSON-based `Storage` persistence exactly, unlike `Date`, which
+  serializes to an ISO string and never comes back as a `Date` on reload).
+  `mtimeMs()` deliberately duck-types the Date case (checks for a `.getTime`
+  method) rather than using `instanceof Date`: under Jest's
+  `--experimental-vm-modules`, each test file's `Date` constructor can be a
+  different realm than the one `fs`'s internal `Stats` object was built
+  with, so a real `Date` from `fs.promises.stat()` can fail `instanceof
+  Date` — silently reintroducing the exact bug this fix is for, only inside
+  the test suite that's supposed to catch it.
+
+  **Real-world impact, not just a wrong return value.** Every repository
+  created with a Git backend wraps `graph.updateChange()` in middleware that
+  syncs to Git and mints a new commit (`syncChangeToGit()`). Because
+  `autoSnapshotWorkingCopy()` — which runs before `status()`/`describe()`/
+  `diff()`/`read()`/`file.*` — treated the file list as "always modified", it
+  called `graph.updateChange()` on essentially every one of those calls even
+  when nothing on disk had changed, silently minting a spurious Git commit
+  and changing the working-copy change's `commitId` each time. This is
+  exactly what forced the `{ autoSnapshot: false }` workaround added in
+  `tests/integration/undo-restore-residuals.test.js` for issue #37(c) (see
+  PR #40) — that test's own before/after `commitId` comparisons were being
+  contaminated by these spurious commits. That workaround has been removed
+  now that the underlying bug is fixed; the test passes with auto-snapshot
+  enabled.
+
+  **Why existing tests never caught this.** The in-memory `MockFS` fixture
+  used across almost this whole test suite stores `mtime` as a plain
+  `Date.now()` number, not a `Date` instance — numbers compare by value with
+  `!==`, so `MockFS`-backed tests never exercised the object-identity bug a
+  real filesystem's `Date`-returning `stat()` hits on every call. Added
+  regression tests in `tests/unit/core/working-copy.test.js` using a
+  `RealDateStatFS` wrapper that returns a fresh `Date` instance per `stat()`
+  call (mirroring real `fs` semantics) and asserting that two consecutive
+  `getModifiedFiles()`/`snapshot()` calls with no real file changes in
+  between report zero modified/added/deleted files. Verified against a
+  negative control: reverting just the comparison fix reproduces exactly the
+  "every tracked file looks modified" symptom described in #41.
+
+### Testing
+
+1839 tests passing (2 new regression tests for #41), including the
+previously-`autoSnapshot: false`-gated issue #37(c) test now passing with
+auto-snapshot enabled; lint (0 errors), format:check, typecheck, and build
+all green; all 12 `examples/*.mjs` run clean.
+
+## 1.9.1 — 2026-09-26 — undo/restore/abandon/squash follow-ups
+
+Three bug-fix follow-ups to 1.9.0's undo/abandon/squash work (#29/#30),
+found by continued use of the same graph/working-copy machinery. Grouped
+into one patch release because all three touch overlapping code
+(`computeGraphReversal()`/`applyGraphReversal()`, the `all()` revset, and
+the synthetic-empty-change pattern `new()`/`squash()` share).
+
+### Fixed
+
+- **`restore()`/`undo()` now record their own `changeSnapshot`, so undoing
+  a restore (or undoing an undo) actually reverts something (#37a).**
+  1.9.0 taught `describe()`/`squash()`/`abandon()` to snapshot the
+  ChangeGraph state they were about to overwrite so a later `undo()` could
+  put it back — but `undo()` and `operations.restore()` themselves never
+  did the same for THEIR OWN oplog entries. Repro: `describe("old")` →
+  `describe("new")` → `restore(<op before the second describe>)` (now
+  "old") → `undo()`. Expected: back to "new". Actual: still "old", because
+  the restore's own oplog entry carried no `changeSnapshot` for
+  `computeGraphReversal()` to find — undoing it moved the working-copy
+  pointer/files but left the change record exactly as the restore had
+  left it. Both `undo()` and `restore()` now capture ground-truth "what
+  am I about to overwrite" (the same way `undo()` already did for
+  `redo()`'s benefit, under `redoChangeSnapshot`) and record it as their
+  own `changeSnapshot`. Extended `redo()` the same way for symmetry, since
+  it shares the identical gap.
+- **`log()` no longer lists changes orphaned by an undone `new()`/`squash()`
+  (#37b).** `undo()`/`redo()`/`operations.restore()` deliberately never
+  delete a change record a reverted `new()`/`squash()` created — they only
+  un-reference it (matching real jj's "hidden, not gone" model for
+  unreachable commits, and this package's own history-editing tests rely
+  on rebasing back onto one still working) — but `log()`'s default
+  `all()` revset was a flat `graph.getAll()`, so the orphan kept showing
+  up as an ordinary visible change forever. `all()`/`builtin_log()` now
+  exclude changes that are BOTH unreachable from every tracked head
+  (working copy, bookmarks, tags — the closest available proxy for real
+  jj's explicitly-maintained View heads, since this package doesn't thread
+  the operation log's `view.heads` through to the revset engine) AND
+  "discardable" (no file diff versus its own parent, and undescribed —
+  including this package's own `'(no description)'`/`'(no description
+  set)'` sentinel strings, which `new()`/`squash()` write when no message
+  is given). The change record itself is still resolvable directly by its
+  change id, matching real jj's hidden-not-gone semantics for unreachable
+  commits. Merge commits are conservatively never treated as "empty" by
+  this rule.
+- **`undo()`/`restore()` now restore the ORIGINAL commit id instead of
+  minting a new one (#37c).** Reverting a `changeSnapshot` went through
+  the same `graph.updateChange()` every normal mutation uses, which fires
+  the git-sync middleware and creates a brand-new commit from the
+  *current* tree — even though the snapshot being reapplied already
+  carried the correct, original commit id from before the reverted
+  operation ran. Since undo/restore are pure reverts, not edits, this
+  undermined the "change id survives, commit id only changes on content
+  edit" story for the revert itself. `applyGraphReversal()` (used by both
+  `undo()` and `restore()`) and `redo()`'s equivalent now write the
+  snapshot verbatim via the un-wrapped graph store, bypassing the git-sync
+  hook entirely and restoring the original commit id byte-for-byte.
+- **`abandon()` of the working-copy change now moves `@` off it (#38).**
+  `abandon(<changeId of @>)` correctly marked the change abandoned but
+  left `@` pointing at it — `status()`/`log()` kept showing the working
+  copy sitting on a change flagged abandoned. Real jj instead moves `@` to
+  a new empty change on the abandoned change's own parent(s). `abandon()`
+  now detects that case and calls `new({ parents: change.parents })` —
+  reusing `new()`'s own "create an empty change with given parents" logic
+  rather than duplicating it — which is exactly the workaround callers
+  previously had to reach for themselves.
+- **`squash()` of the working-copy change no longer gives the new `@` an
+  empty `fileSnapshot` (#39).** 1.9.0 fixed `squash()` to actually move
+  the source's file content into the destination (#30), but when the
+  squashed source WAS the working-copy change, the new `@` squash creates
+  afterward was still hard-coded to `fileSnapshot: {}` instead of starting
+  from the destination's (now-merged) tree — so `status()`/`snapshot()`
+  saw every on-disk file as untracked/new until something rewrote it and
+  triggered a fresh auto-snapshot. The new `@` now starts as a copy of the
+  destination's `fileSnapshot`, matching real `jj squash` (the new
+  working-copy change looks identical to its new parent until you touch
+  something), and the working directory is synced to match too (a no-op
+  in the common case where source's parent already was the destination,
+  but necessary whenever they aren't adjacent).
+
+### Testing
+
+1837 tests passing, including 12 new regression tests added by this pass;
+lint (0 errors), format:check, typecheck, and build all still green; all
+12 `examples/*.mjs` run clean. New test files:
+`tests/integration/undo-restore-residuals.test.js` (#37a/b/c),
+`tests/integration/abandon-working-copy.test.js` (#38),
+`tests/integration/squash-working-copy-file-snapshot.test.js` (#39). Each
+fix was verified against a negative control (reverting just that fix
+reproduces the exact wrong behavior described in its issue) before moving
+to the next.
+
+## 1.9.0 — merge the scoped and unscoped version lineages
+
+No code change — a deliberate, one-time exception to this family's usual
+"version restarts at 0.0.0 on a scope move" convention, forced by making
+the unscoped `isomorphic-jj` mirror permanent (see the unscoped-mirror
+workflow's own history) rather than a one-off "final release" bridge:
+`isomorphic-jj`'s unscoped name already had real published history through
+**1.8.0** from before the `@johnhenry/*` rename, while the scoped package
+had separately restarted at 0.0.0 and reached 0.4.0. Both names publish
+the same version on every release from here on, so the shared version has
+to sit above BOTH names' currently-published maximum, or the unscoped
+mirror's `npm install isomorphic-jj` would move npm's `latest` tag
+*backward* in version number the moment it published. `1.9.0` is one
+minor above the unscoped side's existing 1.8.0 ceiling — chosen over a
+patch bump because this release also carries real new functionality
+(0.3.0/0.4.0's `jj converge`, N-way divergence resolution, and the four
+other jj-v0.45 fixes), not just the version-numbering fix itself.
+
+Going forward, `publish.yml`/`publish-unscoped.yml` both preflight-check
+that the tag being published is strictly greater than whatever's
+currently live under EITHER name before publishing either one, so this
+can't silently regress again.
+
+## 0.4.0 — `converge()` resolves any number of divergent copies
+
+Follow-up to 0.3.0's `converge()` (#32): it originally capped automatic
+resolution at exactly two divergent copies, throwing `CONVERGE_AMBIGUOUS`
+for a third. That cap is gone — `converge()` now resolves any number of
+copies of one change id in a single call. Real jj's own CLI still only
+converges one *change id* per invocation as of v0.45.1 (an explicit TODO
+in its own source: "consider adding logic to deal with more than one
+divergent change-id in one invocation"), which is what this package's
+changeId-at-a-time API already matched — this follow-up instead closes
+the gap in what happens *within* that one change id, where real jj's
+underlying engine (`TruncatedEvolutionGraph`/`find_divergent_changes`)
+already resolves every divergent revision together, not just a pair.
+
+### Changed
+
+- **`converge()` is N-way, not pairwise.** The per-path resolution rule
+  generalizes directly: for each file, collect every DISTINCT value across
+  all copies that differs from the shared base. Zero distinct changed
+  values means nobody touched it; exactly one means only one side (or
+  several copies that happened to make the identical change) touched it,
+  and that value wins; two or more is a genuine conflict between that many
+  copies. `CONVERGE_AMBIGUOUS` no longer exists — there is nothing left for
+  it to guard against.
+- **A conflict with more than two disagreeing copies carries a new `sides`
+  shape.** Every other conflict in this codebase (from `merge()`/
+  `rebase()`) is inherently two-sided and keeps `sides: { base, left,
+  right }`. An N-way `converge()` conflict instead gets `sides: { base,
+  versions }`, where `versions` is `Array<{ commitId, content }>` — one
+  entry per distinct disagreeing value, so a caller can tell which
+  divergent copy contributed which content without decoding a fixed
+  left/right pair. Added `ConflictModel.createNWayConflict()` as the one
+  place that builds this shape.
+
+## 0.3.0 — Track jj through v0.45.1
+
+Five fixes/additions found via real usage of isomorphic-jj in a browser
+showcase app (ORRERY), spanning the browser entry, op-log/undo, and
+graph-rewrite (squash/rebase/abandon) machinery — grouped into one release
+because several of them touch the same shared machinery. Also closes the
+version gap to jj v0.45.1 (v0.45.0 added `jj converge`; v0.45.1 was
+patch-only, no JS-relevant changes).
+
+### Fixed
+
+- **The `/browser` entry can now actually run in a bundle (#28).**
+  `createBrowserFS()` called `require('@isomorphic-git/lightning-fs')`,
+  which doesn't exist in an ESM browser bundle; it's now an async
+  `import()`, and also accepts an injected `fs` (an instance, or a
+  LightningFS-shaped constructor) so callers can bring `memfs` or their
+  own. The four protobuf-backed stores (`JJCheckout`, `JJTreeState`,
+  `JJOperationStore`, `JJViewStore`) loaded their `.proto` schemas via
+  `protobuf.load()` against a `__dirname`-derived filesystem path, which
+  has no meaning in a bundle; they now build a `protobufjs` `Root` from
+  precompiled reflection JSON (`src/protos/*.json.js`, regenerated by
+  `npm run build:protos`, wired into `npm run build`) via the
+  dependency-free `protobufjs/light.js` entry point. Bundling a real
+  scratch app (`esbuild --platform=browser`) against the fix surfaced
+  several more Node-only assumptions that block a real browser run, fixed
+  the same way (isomorphic, not bundler-specific hacks): a bare
+  `import path from 'path'` (→ `src/utils/posix-path.js`, a tiny
+  POSIX-only join/dirname/resolve — this also fixes a latent Windows bug,
+  since Node's `path.join` uses backslashes there and git/jj paths must
+  never); `import crypto from 'crypto'` / dynamic `import('crypto')` (→
+  `randomHex()` in `id-generation.js`, built on the `crypto.getRandomValues`
+  global that file already used elsewhere); direct `Buffer.from`/
+  `Buffer.isBuffer` calls (→ `src/utils/bytes.js`, which only ever needs
+  `Uint8Array` and prefers a real `Buffer` when present so existing Node
+  behavior is unchanged); `fs.promises.mkdir(p, { recursive: true })`
+  (LightningFS silently ignores `recursive` and throws `ENOENT` on a
+  missing parent — `src/utils/mkdirp.js` walks and creates each segment
+  instead); and a few `readFile`/`writeFile` calls using the hyphenated
+  `'utf-8'` spelling (LightningFS only accepts the exact string `'utf8'`).
+  Verified end-to-end by bundling a scratch app and running it in real
+  headless Chromium: createBrowserFS → createJJ → git.init → write →
+  describe → log all completed successfully against IndexedDB-backed
+  LightningFS.
+- **`undo()`/`operations.restore()` now revert graph rewrites, and `undo()`
+  walks progressively further back instead of undoing itself (#29).**
+  `squash()`/`moveChange()` (rebase)/`abandon()` never recorded a
+  changeSnapshot, so undo() had nothing to restore their in-place
+  ChangeGraph mutations — the DAG stayed rewritten after "undoing" them.
+  They now do, the same mechanism issue #12 introduced for `describe()`.
+  Calling `undo()` twice also only undid the undo: since `undo()` is
+  itself recorded as a new operation, a second `undo()` naively targeting
+  the log's raw parent chain landed back on the just-undone operation
+  instead of stepping further into the past — contradicting real jj's
+  documented behavior (`jj-undo(1)`: "If jj undo is used repeatedly, it
+  will restore increasingly older operations"). A new `resolveUndoTarget()`
+  recognizes 'undo'/'redo' bookkeeping operations in the log and steps
+  past them. `operations.restore()` previously only touched bookmarks and
+  the working-copy pointer; it now shares the same
+  `computeGraphReversal()`/`applyGraphReversal()` primitive as `undo()`/
+  `redo()` to fully revert the graph, files, and conflict state to any
+  earlier operation. Also fixed in passing: `undo()` used to
+  unconditionally clear ALL conflicts whenever the operation being undone
+  hadn't recorded its own conflict snapshot (true for every op except
+  `merge()`) — undoing an unrelated `describe()` silently wiped conflicts
+  from an earlier, unrelated `merge()`.
+- **`squash()` merges file content, not just descriptions (#30).** It
+  combined the two descriptions into the destination but never moved the
+  source change's file contents into it — the squashed change's tree was
+  left completely unchanged. It now computes what source actually changed
+  relative to its own parent (added/modified/deleted paths) and folds just
+  that diff onto dest, rather than overwriting dest's whole snapshot with
+  source's.
+- **`abandon(changeId)` re-parents children (#30).** It set the abandoned
+  flag but left children pointing at the abandoned commit; it now
+  re-parents every child onto the abandoned change's own parent(s)
+  (matching real `jj abandon`), including making a child a root when the
+  abandoned change had no parent.
+- **`edit()`/`new()` fully sync the working copy (#30).** They wrote the
+  target change's files but only ever overlaid them on top of whatever was
+  already on disk, so a file present in the previously-checked-out change
+  but absent from the target leaked into the next snapshot. Both now go
+  through a shared `syncWorkingCopyFiles()` helper that deletes every
+  currently-tracked file NOT in the target snapshot in addition to writing
+  everything the target has. `new()` previously didn't touch the working
+  directory at all when targeting a change other than the current head's
+  default parent; it now checks the target out too.
+- **`rebase()` performs a real three-way merge and detects conflicts
+  (#31).** Rebasing a change onto a sibling that edited the same lines
+  kept the rebased change's file contents verbatim and recorded no
+  conflict. `moveChange()` (which `rebase()` delegates to) now runs the
+  same `detectConflicts()` three-way merge `merge()` already used, against
+  (old base = the change's own parent before reparenting, old commit = the
+  change's own content, new base = the new parent's content), recording
+  any detected conflict the same way `merge()` does.
+
+### Added
+
+- **`converge(changeId)` — auto-resolve divergent commits (#32, jj
+  v0.45.0).** A change is divergent when more than one visible commit
+  shares its change id; this package's `divergent()` revset already
+  modeled that (`c.divergent === true`, plus a changeId-occurrence count
+  across the graph), but nothing ever actually produced a divergent
+  change — the flag was set nowhere, and `ChangeGraph.nodes` being a
+  `Map<changeId, change>` made two entries genuinely sharing a changeId
+  structurally impossible via `addChange()`. `ChangeGraph.addDivergentCopy()`
+  is the actual producer: it stores a second commit under a synthetic
+  internal key while keeping its own `changeId` field equal to the
+  original's, which is what activates `divergent()` for real (previously
+  dead code) and gives `converge()` something to resolve.
+  `converge({ changeId })` (a bare changeId string also works) attempts
+  automatic resolution using the same three-way-merge/conflict-detection
+  machinery `rebase()` uses (#31) — reused, not duplicated a third time in
+  this codebase. On success, it creates one replacement commit (a fresh
+  commit id, the merged file content, combined description) under the same
+  change id and drops the superseded copy. On a genuine per-path conflict,
+  it's reported as data (`{ resolved: false, conflicts }`), matching
+  `merge()`'s own non-throwing convention for conflicts, and the conflict
+  is recorded the normal way. Throws `NOT_DIVERGENT` when there's nothing
+  to converge, and `CONVERGE_AMBIGUOUS` when more than two visible copies
+  exist — automatic resolution only attempts a pairwise merge, matching
+  real jj's non-interactive mode aborting resolution it can't disambiguate
+  rather than guessing.
+- **`ChangeGraph.deleteChange()`** — outright removal of a change record,
+  as distinct from `abandon()`'s soft-delete (`abandoned: true`) flag.
+  Added for undo()/redo()/operations.restore() to reverse an `addChange()`
+  when winding the graph back (#29), though in practice undo() never calls
+  it — see the doc comment on `computeGraphReversal()` for why a newly
+  created change is deliberately left in the graph (unreferenced, not
+  deleted) rather than torn down, matching real jj's "hidden, not gone"
+  model for unreachable commits.
+
+### Judgment calls worth flagging
+
+- **`write()`'s commit id/fileSnapshot staying stale until the next
+  snapshot is intentional, not a bug (#30).** jj has no staging area, but
+  real jj also doesn't recompute a tree/commit hash on every file write —
+  only when an actual `jj` command runs and snapshots the working copy.
+  `write()` is the equivalent of editing a file with your OS's own tools
+  outside of jj; `describe()`/`new()`/`edit()`/`status()`/etc. are the
+  equivalent of running a jj command. Documented rather than changed.
+- **Divergent copies are modeled as "another commit sharing a changeId",
+  not "two independent changeIds grouped together" (#32)** — matching what
+  the pre-existing (if previously non-functional) `divergent()` revset
+  already implied, rather than inventing a parallel representation.
+  Converge only handles the common case where the two copies share the
+  same parent(s) (a real divergence — two rewrites of one prior position
+  in history) and are leaves (no children of their own); this package's
+  graph model references parents by changeId, not by a more granular
+  commit-level pointer the way real jj's does, so a divergent copy's own
+  independent descendants aren't distinguishable from the primary copy's —
+  documented as a known limitation of the simplified graph model rather
+  than a full rewrite of how parent/child edges are stored.
+
+### Testing
+
+1823 tests passing (was 1732 at the start of this pass); lint (0 errors),
+format:check, typecheck, and build all still green. New test files:
+`tests/integration/undo-redo-graph-rewrites.test.js`,
+`tests/integration/squash-merge-abandon-reparent-file-sync.test.js`,
+`tests/integration/rebase-conflict-detection.test.js`,
+`tests/integration/converge.test.js`, plus new unit coverage for
+`src/utils/posix-path.js`, `src/utils/bytes.js`, `src/utils/mkdirp.js`,
+and `ChangeGraph`'s `deleteChange()`/`addDivergentCopy()`/
+`getDivergentSiblings()`/`deleteDivergentCopy()`.
+
 ## 0.2.0 — 2026-09-02
 
 The first `@johnhenry/isomorphic-jj` release since 0.1.0, and the first

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 [fullname]
+Copyright (c) 2025 John Henry
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,7 +1,5 @@
 # @johnhenry/isomorphic-jj
 
-> **This package has moved to `@johnhenry/isomorphic-jj`.** This is the final release under the old name.
-
 > **Jujutsu version control for JavaScript**—stable change IDs, fearless undo, and no staging area. Works in Node.js and browsers.
 
 Full documentation: [opensource.johnhenry.me/isomorphic-jj](https://opensource.johnhenry.me/isomorphic-jj/)
@@ -39,6 +37,29 @@ await jj.undo();
 
 ---
 
+## Contents
+
+- [Try it in 60 seconds](#try-it-in-60-seconds)
+- [Quick Start](#quick-start)
+- [Examples](#examples)
+- [What's New in v1.0](#whats-new-in-v10)
+- [How is this Different?](#how-is-this-different)
+- [Features](#features)
+- [Use Cases](#use-cases)
+- [API Reference](#api-reference)
+- [Why isomorphic-jj?](#why-isomorphic-jj)
+- [Architecture](#architecture)
+- [Project Status](#project-status)
+- [Installation & Environment](#installation--environment)
+- [Security model](#security-model)
+- [Contributing](#contributing)
+- [FAQ](#faq)
+- [Family](#family)
+- [License](#license)
+- [Acknowledgments](#acknowledgments)
+
+---
+
 ## Try it in 60 seconds
 
 ### CLI
@@ -86,7 +107,7 @@ console.log(await jj.log({ limit: 5 }));
 import { createJJ } from '@johnhenry/isomorphic-jj';
 import { createBrowserFS } from '@johnhenry/isomorphic-jj/browser';
 
-const fs = createBrowserFS({ name: 'my-repo' });
+const fs = await createBrowserFS({ name: 'my-repo' });
 const jj = await createJJ({ fs, dir: '/repo' });
 // Same API as Node from here on — see examples/12-browser.mjs.
 ```
@@ -189,7 +210,7 @@ isomorphic-jj v1.0 now implements virtually all commonly-used JJ CLI commands:
 See [ROADMAP.md](./ROADMAP.md) for the release-by-release feature comparison and what's still planned.
 
 ### Testing & Quality
-- **1730 tests** passing — ~97% statement / 91% branch coverage
+- **1823 tests** passing — ~97% statement / 91% branch coverage
 - **100% backward compatible** - All existing code continues to work
 - **Zero breaking changes** - Deprecated features show warnings but still function
 
@@ -254,7 +275,7 @@ import git from 'isomorphic-git';
 import http from 'isomorphic-git/http/web';
 
 // Create browser filesystem (uses IndexedDB)
-const fs = createBrowserFS({ name: 'my-repo' });
+const fs = await createBrowserFS({ name: 'my-repo' });
 
 const jj = await createJJ({ fs, dir: '/repo', git, http });
 await jj.git.init({ userName: 'User', userEmail: 'user@example.com' });
@@ -732,7 +753,7 @@ import { createBrowserFS, requestPersistentStorage } from '@johnhenry/isomorphic
 const persistent = await requestPersistentStorage();
 
 // Create filesystem with IndexedDB backend
-const fs = createBrowserFS({ backend: 'idb', name: 'my-repo' });
+const fs = await createBrowserFS({ backend: 'idb', name: 'my-repo' });
 
 // Check browser capabilities
 import { detectCapabilities } from '@johnhenry/isomorphic-jj/browser';
@@ -905,8 +926,8 @@ const jj: JJ = await createJJ(options: CreateJJOptions);
 - **Repository**: `init()`, `status()`, `stats()`
 - **Files**: `write()`, `read()`, `cat()`, `move()` (deprecated for history), `remove()`, `listFiles()` | **Namespace**: `file.write()`, `file.show()`, `file.list()`, `file.move()`, `file.remove()`
 - **Changes**: `describe()`, `new()`, `amend()`, `commit()`, `edit()`, `show()`
-- **History**: `log()`, `obslog()`, `squash()`, `split()`, `rebase()`, `abandon()`, `unabandon()`
-- **Operations**: `undo()`, `operations.list()`, `operations.at()`
+- **History**: `log()`, `obslog()`, `squash()`, `split()`, `rebase()`, `abandon()`, `unabandon()`, `converge()`
+- **Operations**: `undo()`, `redo()`, `operations.list()`, `operations.at()`, `operations.restore()`
 - **Bookmarks**: `bookmark.list()`, `bookmark.set()`, `bookmark.move()`, `bookmark.delete()`
 - **Git**: `git.init()`, `git.fetch()`, `git.push()`, `git.import()`, `git.export()`
 - **Remotes**: `remote.add()`, `remote.fetch()`, `remote.push()`
@@ -999,10 +1020,10 @@ repo/
 
 ## Project Status
 
-**Current Version**: 0.2.0 (`@johnhenry/isomorphic-jj`; same library/API lineage as the old `isomorphic-jj`, which reached v1.7.0 before the rename — see the provenance note at the top of this file)
-**Test Coverage**: 1730 tests passing, ~97% statements / 91% branches
-**JJ CLI parity**: tracks Jujutsu through v0.44
-**Status**: Actively developed; broad JJ CLI semantic parity, used in the examples/apps in this repo and in [JJHub](#related-projects). Not yet 1.0 — API surface can still shift; pin a version and read the CHANGELOG before upgrading.
+**Current Version**: 0.3.0 (`@johnhenry/isomorphic-jj`; same library/API lineage as the old `isomorphic-jj`, which reached v1.7.0 before the rename — see the provenance note at the top of this file)
+**Test Coverage**: 1823 tests passing, ~97% statements / 91% branches
+**JJ CLI parity**: tracks Jujutsu through v0.45.1
+**Status**: Actively developed; broad JJ CLI semantic parity, used in the examples/apps in this repo and in [JJHub](#family). Not yet 1.0 — API surface can still shift; pin a version and read the CHANGELOG before upgrading.
 
 **Completed:**
 - ✅ v0.1: Core JJ experience (stable IDs, undo, bookmarks, revsets)
@@ -1014,6 +1035,7 @@ repo/
 - ✅ v1.5: Parity refresh tracking jj through **v0.43** — new revsets (`change_id`, `commit_id`, `subject`, `author_name`/`email`, `committer*`, `signed`, `divergent`, `merges`, `forks`, `first_parent`, `first_ancestors`, `fork_point`, `merge_point`, `exactly`, `present`, `coalesce`, `remote_tags`, `ancestors(x, depth)`), working `tags()`/`remote_tags()` revsets, and new commands: `revert()`, `redo()`, `sign()`/`unsign()`, `file.search()`, `bookmark.advance()`, `tag.set()`. See [CHANGELOG.md](./CHANGELOG.md).
 - ✅ 0.1.0 (post-rename): Parity refresh tracking jj through **v0.44** — `tag.track()`/`tag.untrack()`, the `builtin_log()` revset alias, and `file.search({ nameOnly: true })`; `git_refs()`/`git_head()` documented as deprecated (jj removed both in v0.43). See [CHANGELOG.md](./CHANGELOG.md) for what was deliberately left for a maintainer call (`jj run`, fetch-time remote tag/bookmark import).
 - ✅ 0.2.0: Storage-layer audit fixes — same-process storage locking, `undo()` reverting in-place graph/tag mutations, ambiguous change-id detection, categorized `push()` error codes, a conflict-marker newline fix, atomic protobuf writes, and open-ended revset ranges (`..b`, `a..`, `::`). See [CHANGELOG.md](./CHANGELOG.md).
+- ✅ 0.3.0: Parity refresh tracking jj through **v0.45.1** — a working `/browser` entry (async `createBrowserFS()`, bundle-safe protobuf schema loading, no stray Node-only imports), `undo()`/`operations.restore()` reverting graph rewrites with real progressive undo/redo, `squash()`/`abandon()`/`edit()`/`new()` fully syncing content instead of only metadata, `rebase()` performing a real three-way merge and recording conflicts, and the new `converge()` command (jj v0.45.0) to auto-resolve divergent commits. See [CHANGELOG.md](./CHANGELOG.md).
 
 See [ROADMAP.md](./ROADMAP.md) for detailed plans, and [CHANGELOG.md](./CHANGELOG.md) for the release history.
 
@@ -1023,7 +1045,7 @@ See [ROADMAP.md](./ROADMAP.md) for detailed plans, and [CHANGELOG.md](./CHANGELO
 
 ### Requirements
 
-- **Node.js**: 20.0.0 or higher (uses the Web Crypto global, stabilized in Node 20; Node 18 is EOL)
+- **Node.js**: 26.0.0 or higher, matching `engines.node` and CI (uses the Web Crypto global, stabilized in Node 20 — the family floor is higher than the functional minimum)
 - **Browsers**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
 - **Optional**: Git CLI (for JJ CLI interop testing)
 
@@ -1044,6 +1066,58 @@ See [ROADMAP.md](./ROADMAP.md) for detailed plans, and [CHANGELOG.md](./CHANGELO
 
 ---
 
+## Security model
+
+isomorphic-jj is a headless reimplementation of JJ's model, not a wrapper
+around the `jj` or `git` binaries — that architectural choice is also its
+main security property. It does not run a sandbox and does not vet the
+repositories you point it at.
+
+**What isomorphic-jj guarantees:**
+
+- **No shell-out, ever.** The library never spawns a child process to run
+  `git`, `jj`, or any other binary — repository paths, branch/bookmark
+  names, and commit messages are handled as plain JS values through
+  `isomorphic-git`'s and `protobufjs`'s pure-JS encoders, never interpolated
+  into a shell command string. This removes the whole class of
+  shell-injection risk that a CLI-wrapping library (like `simple-git`) has
+  to defend against by construction, not by escaping.
+- **Storage writes are atomic.** `jj-operation-store.js`, `jj-view-store.js`,
+  and `jj-tree-state.js` route every write through a shared
+  `atomicWriteFile()` temp+rename helper, and same-process concurrent writes
+  to the same path are serialized through a path-keyed async mutex — a
+  crash or a racing autosnapshot mid-write cannot leave a truncated or
+  undecodable store file. Fixed in [PR #19](https://github.com/johnhenry/isomorphic-jj/pull/19) (0.2.0); scoped to
+  same-process concurrency — cross-process locking is not yet implemented
+  (see "still yours" below).
+
+**What is still yours:**
+
+- **Remote authentication and transport trust.** `git.push()`/`git.fetch()`
+  delegate to `isomorphic-git`'s HTTP client (and, in the browser, whatever
+  CORS proxy you configure) — isomorphic-jj neither stores nor validates
+  credentials, and does not verify a remote server's identity beyond what
+  that HTTP layer does. A misconfigured or malicious CORS proxy sees
+  everything a normal Git remote would.
+- **Custom merge drivers run arbitrary code with full process access.**
+  `mergeDrivers.register()` lets you register a function per file
+  pattern (`'*.json'`, `'package.json'`, …); a registered driver — yours or
+  a dependency's — executes with the same privileges as the rest of your
+  process during every merge that touches a matching path. isomorphic-jj
+  does not sandbox driver execution; treat a third-party merge driver the
+  same as any other third-party code you'd `require()`.
+- **Cross-process locking is not implemented.** The same-process mutex
+  above does not protect a repository opened by two separate OS processes
+  at once (e.g. two CLI invocations, or a CLI run concurrently with a
+  long-running server process) — don't rely on isomorphic-jj to serialize
+  those for you.
+- **No allowlisting of untrusted repository content.** Cloning or importing
+  a Git history runs its objects through the same parsing code regardless
+  of whether you trust the source, matching `isomorphic-git`'s own model —
+  this library adds no additional vetting layer.
+
+---
+
 ## Contributing
 
 We welcome contributions! Here's how to help:
@@ -1085,7 +1159,7 @@ A: Yes! Colocated repos expose normal Git commits. Git users never see JJ metada
 A: Comparable to isomorphic-git for Git operations. JJ metadata (JSON) is fast in Node, acceptable in browsers. Large histories need pagination.
 
 **Q: Does this support all JJ features?**
-A: Broad semantic parity (tracks Jujutsu through v0.44), not every CLI/UX detail — it's a library, not a terminal UI. See [ROADMAP.md](./ROADMAP.md) for what's planned and what's deliberately out of scope.
+A: Broad semantic parity (tracks Jujutsu through v0.45.1), not every CLI/UX detail — it's a library, not a terminal UI. See [ROADMAP.md](./ROADMAP.md) for what's planned and what's deliberately out of scope.
 
 **Q: Can I migrate my Git repo?**
 A: Yes! `jj.git.init()` works on existing Git repositories.
@@ -1095,22 +1169,35 @@ A: JJ's model genuinely improves common workflows—stable change IDs, fearless
 
 ---
 
-## Related Projects
-
-### JJHub
-
-[JJHub](https://jjhub.erisera.com) is a Jujutsu-native overlay on GitHub, built
-on this library (it uses `createJJ` directly): stable change IDs and stacked
-PRs on top of your existing GitHub repos, platform-wide undo, and an MCP
-server so coding agents get the same fearless-undo, no-staging-area workflow.
-Install the CLI with `npm i -g jjhub`.
-
-### Others
-
-- [isomorphic-git](https://isomorphic-git.org/) - Pure JS Git implementation (our foundation)
-- [Jujutsu](https://jj-vcs.github.io/jj/) - The original JJ version control system
-- [simple-git](https://github.com/steveukx/git-js) - Git wrapper for Node.js
-- [Git plumbing vs porcelain](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain) - Architecture pattern we follow
+## Family
+
+isomorphic-jj has no other package in the `@johnhenry` npm scope yet — it
+consumes and is consumed by projects outside that scope. Those relationships
+are still concrete enough to document precisely, so they're recorded here
+rather than under a vaguer "see also".
+
+- **[JJHub](https://jjhub.erisera.com)** — a Jujutsu-native overlay on GitHub,
+  and the closest thing this library has to a downstream consumer: it calls
+  `createJJ()` directly (not a wrapped or forked copy) to get stable change
+  IDs and stacked PRs on top of existing GitHub repos, platform-wide undo,
+  and an MCP server exposing the same fearless-undo, no-staging-area
+  workflow to coding agents. JJHub is a private Erisera product, not a
+  `@johnhenry/*` package — install its CLI with `npm i -g jjhub`.
+- **[`isomorphic-git`](https://github.com/isomorphic-git/isomorphic-git)** —
+  a real, non-optional dependency: this library's Git backend support
+  (`jj.git.init/clone/push/fetch`) is built directly on isomorphic-git's
+  pure-JS Git object model, not a fork or reimplementation of it. Peer
+  dependency, not bundled — see [Installation & Environment](#installation--environment).
+
+### Prior art
+
+- [Jujutsu](https://jj-vcs.github.io/jj/) — the original JJ version control
+  system this library reimplements the semantics of (headlessly, in JS; not
+  a wrapper around the `jj` binary).
+- [simple-git](https://github.com/steveukx/git-js) — a Git CLI wrapper for
+  Node.js; unlike isomorphic-jj, it shells out to the `git` binary rather
+  than reimplementing the object model in JS.
+- [Git plumbing vs porcelain](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain) — the architecture pattern this library's own layering follows.
 
 ---