You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 601e87c
Browse filesBrowse the repository at this point in the historyBrowse 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
Copy file name to clipboardExpand all lines: specs/behaviors/storage.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -66,7 +66,7 @@ Invariants:
66
66
67
67
-`CFP_DATA_REPO_PATH` points at the **bare gitdir** (no `.git` subdirectory inside it; the path itself is the gitdir).
68
68
-`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).
70
70
- The pod's data volume is `emptyDir` — re-cloned on every pod start, updated incrementally via `git fetch` within a pod's lifetime.
71
71
72
72
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
344
344
-**Endpoint** — `POST /api/_internal/reload-data`. Hidden from the public OpenAPI doc; not advertised externally.
345
345
-**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").
346
346
-**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.
348
348
-**Reconcile + rebuild** — otherwise run the same reconciliation state machine the boot path uses (`fastify.reconcileDataRepo`):
349
349
- If the branch didn't move (`in-sync`, `pushed-ahead`, `fetch-failed`), skip the rebuild and return 200 noChanges with the outcome.
350
350
- 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`.
351
351
-**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.
352
352
-**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.
353
353
-**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.
355
355
356
356
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.
0 commit comments