Skip to content

Commit 68968cf

Browse files
chore(plans): mark gitsheets-sync done
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011Q2tgjZEUrtvVk6k8SpdXJ
1 parent 6d2d51d commit 68968cf

1 file changed

Lines changed: 44 additions & 4 deletions

File tree

‎plans/gitsheets-sync.md‎

Lines changed: 44 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
---
2-
status: in-progress
2+
status: done
33
depends: [gitsheets-freshness]
44
specs:
55
- specs/behaviors/storage.md
6+
pr:
67
---
78

89
# Plan: replace hand-rolled reconcile with upstream `repo.sync()`
@@ -48,11 +49,11 @@ spec already defines, and map upstream outcomes onto it.
4849
## Validation
4950

5051
- [x] Upstream issue filed and linked here (gitsheets#301)
51-
- [ ] The existing reconcile test matrix (ff, replay, escape-hatch,
52+
- [x] The existing reconcile test matrix (ff, replay, escape-hatch,
5253
in-sync) passes unchanged against `repo.sync()`
53-
- [ ] No `merge-tree`, `commit-tree`, `update-ref` or `merge-base` left in
54+
- [x] No `merge-tree`, `commit-tree`, `update-ref` or `merge-base` left in
5455
`apps/api/src`
55-
- [ ] `type-check` + `lint` + full api suite green
56+
- [x] `type-check` + `lint` + full api suite green
5657

5758
## Risks / unknowns
5859

@@ -61,4 +62,43 @@ spec already defines, and map upstream outcomes onto it.
6162

6263
## Notes
6364

65+
- gitsheets#301 shipped in 2.8.0 (`repo.sync()` + `repo.isAncestor`);
66+
develop already ran ^2.9.0.
67+
- Outcome mapping: gitsheets `ahead` → `pushed-ahead`; the rest pass
68+
through. `conflict` can't occur (we always pass `onConflict:
69+
'preserve-branch'`) and throws if it ever does. gitsheets returns the
70+
conflict branch as `refs/heads/conflicts/<UTC>`; we strip `refs/heads/`,
71+
so the name operators see is unchanged.
72+
- **Atomicity.** `repo.sync()` takes its own handle's write lock and throws
73+
`lock_held` inside `withLock`. Syncing first and rebuilding in a second
74+
`withLock` leaves a gap: a write queued on the lock runs between the two,
75+
and write handlers validate against (and spread from) the in-memory
76+
state, which still holds pre-reload data. A write could then put stale
77+
fields back on disk over what the reload brought in. Instead, the
78+
serving repository's `withLock` still wraps the whole reconcile, and
79+
`reconcileDataRepo` syncs through a short-lived side `Repository` on the
80+
same gitdir, whose lock is uncontended. The side handle has no live
81+
sheets and no daemon, so we refresh the store ourselves and pass the
82+
ahead/replayed tip to `fastify.pushDaemon.notifyCommit`, as before.
83+
- The fetch is still a lock-free `git fetch` with an explicit refspec,
84+
run before the lock. `sync({ fetch: true })` would fetch inside the same
85+
call that locks, so it can't fetch outside our critical section.
86+
- Behavior differences: the replay committer is now passed explicitly
87+
rather than set with `git config user.name/email` on the repo; the
88+
container entrypoint already configures that identity. The standalone
89+
`reconcileDataRepo` no longer pushes the working branch by default.
90+
Pushing always goes through the `push` hand-off, which the API already
91+
used. The conflict-branch name comes from the wall clock inside
92+
gitsheets (the `now` option is gone, and tests fake `Date`).
93+
- New test `holds the write lock from the ref move through the rebuild`
94+
(internal-reload). It holds the lock, queues the reload and then a write,
95+
and asserts that the ref doesn't move until the lock frees and that
96+
nothing commits before the rebuild. Both "sync, then withLock" variants
97+
fail it.
98+
6499
## Follow-ups
100+
101+
- Upstream ask (not yet filed) — let `repo.sync()` run inside a caller's
102+
critical section, either an `afterMove` callback run under its lock or a
103+
lock-held mode inside `withLock`. A fetch-only primitive would also let
104+
us drop the side handle and the last raw `git fetch`.

0 commit comments

Comments
 (0)