Skip to content

Commit 601e87c

Browse files
docs(specs): name repo.sync and repo.isAncestor as the reconcile mechanism
Mechanism-only wording: reconcile moves from hand-rolled git plumbing to gitsheets' sync primitive, and the hot-reload pre-check to repo.isAncestor. Outcomes, conflict-branch naming and the single write-lock critical section for ref move + rebuild are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011Q2tgjZEUrtvVk6k8SpdXJ
1 parent 2d1c108 commit 601e87c

1 file changed

Lines changed: 3 additions & 3 deletions

File tree

‎specs/behaviors/storage.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ Invariants:
6666

6767
- `CFP_DATA_REPO_PATH` points at the **bare gitdir** (no `.git` subdirectory inside it; the path itself is the gitdir).
6868
- `openPublicStore` calls `openRepo({ gitDir: repoPath })` with `workTree` omitted, putting hologit on the `createWorkspaceFromRef(HEAD)` path.
69-
- The reconcile state machine uses git plumbing (`update-ref`, `merge-tree --write-tree`, `commit-tree`) instead of working-tree-touching commands (`merge --ff-only`, `rebase`, `reset --hard`). See [`apps/api/src/store/reconcile.ts`](../../apps/api/src/store/reconcile.ts).
69+
- The reconcile state machine is gitsheets' `repo.sync()`, which fast-forwards, replays and preserves conflicts against the object database and moves refs with compare-and-swap, never touching a working tree (no `merge --ff-only`, `rebase` or `reset --hard`). See [`apps/api/src/store/reconcile.ts`](../../apps/api/src/store/reconcile.ts).
7070
- The pod's data volume is `emptyDir` — re-cloned on every pod start, updated incrementally via `git fetch` within a pod's lifetime.
7171

7272
Local dev mirrors this: the sibling clone the app reads is bare. Contributors who want a working tree to browse/edit by hand clone *from* the bare local into a second working directory and push/pull between them.
@@ -344,14 +344,14 @@ A push to the configured `CFP_DATA_BRANCH` from outside the API (typically a mer
344344
- **Endpoint** — `POST /api/_internal/reload-data`. Hidden from the public OpenAPI doc; not advertised externally.
345345
- **Auth** — `Authorization: Bearer <token>` where the token matches the `CFP_DATA_RELOAD_SECRET` env var (a Kubernetes Secret in production). Constant-time comparison. When the env var is unset, the endpoint is registered but every request gets 503 ("hot-reload not configured").
346346
- **Body** — `{ branch?: string, commitHash?: string }`. Both optional. `branch`, if given, must equal `CFP_DATA_BRANCH`, otherwise `400`: the public store reads `HEAD`, so reconciling any other ref would desync silently. `commitHash` is the commit the caller observed pushing; the endpoint uses it to short-circuit when the pod already has it.
347-
- **Cheap pre-check** — if `commitHash` is an ancestor of local HEAD (`git merge-base --is-ancestor`), respond 200 noChanges immediately without fetching or taking the write lock. This covers the common self-trigger where the API's own push daemon prompted the workflow.
347+
- **Cheap pre-check** — if `commitHash` is an ancestor of local HEAD (gitsheets `repo.isAncestor`), respond 200 noChanges immediately without fetching or taking the write lock. This covers the common self-trigger where the API's own push daemon prompted the workflow.
348348
- **Reconcile + rebuild** — otherwise run the same reconciliation state machine the boot path uses (`fastify.reconcileDataRepo`):
349349
- If the branch didn't move (`in-sync`, `pushed-ahead`, `fetch-failed`), skip the rebuild and return 200 noChanges with the outcome.
350350
- Otherwise refresh the public store, rebuild the in-memory state, the revocation set and the FTS index from the new tree, then return 200 with the outcome, the old and new commit, and `rebuilt: true`.
351351
- **Incremental by default** — the rebuild applies only what changed: for each in-memory sheet, the records that differ between the pre-reconcile commit and the new HEAD are unindexed (old version) and re-indexed (new version) in the live state and the FTS index. The result must equal a full rebuild from the new tree, every primary map and secondary index included, so no lookup path can serve pre-reload contents.
352352
- **Full-rebuild fallback** — a full rebuild replaces the incremental one when any `.gitsheets/` config changed between the two commits, or when more than 5,000 records changed (a bulk import merge). The full rebuild constructs a fresh `InMemoryState` first; only after that succeeds does it mutate the live Maps in place, replacing **every** collection from the fresh one. The FTS engine's `reload(state)` drops and re-inserts every FTS5 table.
353353
- **Failure** — if either rebuild throws partway, the route returns 500 and the operator should restart the pod.
354-
- **Concurrency** — the fetch runs outside any lock, so a slow network never blocks writes. The ref move, store refresh, rebuild and swap all run inside the repository's write lock (gitsheets `repo.withLock`), the same mutex `transact` holds. A write issued during a reload waits for it and then applies on top of the reloaded state; no write can land between the ref move and the swap, so none is lost.
354+
- **Concurrency** — the fetch runs outside any lock, so a slow network never blocks writes. The ref move (`repo.sync()`), store refresh, rebuild and swap all run inside one critical section of the repository's write lock (gitsheets `repo.withLock`), the same mutex `transact` holds. A write issued during a reload waits for it and then applies on top of the reloaded state; no write can land between the ref move and the swap, so none is lost.
355355

356356
The GitHub Actions workflow that calls this endpoint lives in the `codeforphilly-data` repo (`.github/workflows/notify-deployments.yml`), not in this app repo. It fires on push to `CFP_DATA_BRANCH` and posts `{ branch, commitHash: <github.sha> }` with the secret as a bearer token.
357357

0 commit comments

Comments
 (0)