apunkt/SurfSense
1
0
Fork 0
mirror of https://github.com/MODSetter/SurfSense.git synced 2026-07-26 23:51:14 +02:00
Code Issues Projects Releases Packages Wiki Activity

plans: pin phase 3 write path to commit_staged_filesystem_state

Browse source
This commit is contained in:
CREDO23 2026-07-24 19:33:59 +02:00
parent ea5fbec911
commit ea4d03b707
1 changed files with 13 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

21
plans/git-native-kb/03-commit-write-path.md
View file

@ -8,23 +8,24 @@ Turn staged agent/editor/upload writes into **one atomic git commit** per turn/s
## Locked model ## Locked model
- **One commit per agent turn.** Repoint `KnowledgeBasePersistenceMiddleware` (`.../main_agent/middleware/kb_persistence/middleware.py`, `aafter_agent`) from "write folders/documents/chunks to Postgres" to "flush staged working-tree ops → `GitRepoService.commit(message, author)`" under the Phase-1 per-workspace lock. - **One commit per agent turn.** The commit body is the free function `commit_staged_filesystem_state(...)` in `.../kb_persistence/middleware.py` (called by both `aafter_agent` **and** the stream-task fallback — repoint the function, not just the middleware). Change it from "write folders/documents/chunks to Postgres" to "apply staged ops to the git working tree → one `GitRepoService.commit(message, author)`" under the Phase-1 Redis lock.
- **Author attribution.** Commit author = the acting user (or `agent` for autonomous writes); message summarizes the turn's ops. - **Preserve the existing op ordering** (already there for correctness): staged_dirs → moves → writes/edits (skip paths also queued for `rm`; `_final_path` chases move aliases) → file deletes → dir deletes. Apply that order to the working tree, then one commit. Full state-key list + author details: [`00c-shared-contract.md`](00c-shared-contract.md) C4.
- **Author attribution.** Commit author = `created_by_id` (acting user id already passed to the middleware), or `agent` for autonomous writes; message summarizes the turn's ops.
- **Editor saves & upload-extracted markdown use the same commit path** (one write path). Connector-indexable content (Notion/Drive) commits via the same service on sync. - **Editor saves & upload-extracted markdown use the same commit path** (one write path). Connector-indexable content (Notion/Drive) commits via the same service on sync.
- **No Postgres content writes here** — chunk/embedding refresh is Phase 4 (triggered off the commit). - **No Postgres content writes here** — chunk/embedding refresh is Phase 4 (triggered off the commit).
## Work items ## Work items
1. In `kb_persistence/middleware.py`: replace the ordered Postgres write pass with a `GitRepoService.commit(...)` of the staged tree ops (create/write/edit/move/rm/mkdir already tracked in state). 1. In `commit_staged_filesystem_state`: replace the ordered Postgres write pass with working-tree ops + `GitRepoService.commit(...)`, reading the staged ops from the existing state keys (`files`, `staged_dirs`, `pending_moves`, `pending_deletes`, `pending_dir_deletes`, `dirty_paths`, `doc_id_by_path`, …; see C4). Keep the same ordering and the `_final_path` move-alias resolution.
2. Emit the new commit SHA into state/event so Phase 4's indexer and Phase 6's projector can consume it. 2. Emit the new commit SHA into state/event so Phase 4's indexer and Phase 6's projector can consume it. Keep the `dispatch_custom_event` (`document_created/updated/deleted`, `folder_deleted`) calls — the UI depends on them.
3. Route editor save (`source_markdown` write) and upload-extracted markdown through `GitRepoService.write_file` + commit (behind `KB_GIT_ENABLED`). 3. Route editor save (`source_markdown` write) and upload-extracted markdown through `GitRepoService.write_file` + commit (behind `KB_GIT_ENABLED`).
4. Remove the now-dead "stage then persist to Postgres" branches for flagged workspaces (keep unflagged path intact during rollout). 4. Remove the now-dead "stage then persist to Postgres" branches for flagged workspaces (keep unflagged path intact during rollout). **Note:** the `DocumentRevision`/`FolderRevision` snapshot code (gated by `flags.enable_action_log`) lives inside this function — its removal is Phase 4; sequence the two together for flagged workspaces.
## Tests ## Tests
- An agent turn with N file ops produces **exactly one** commit containing all N changes (atomic). - An agent turn with N file ops produces **exactly one** commit containing all N changes (atomic), in the correct order (write-then-move lands at the final path; write+rm in one turn creates nothing).
- Editor save produces one commit; commit author + message are correct. - Editor save produces one commit; commit author (`created_by_id`) + message are correct.
- A failed turn does not leave a partial commit (all-or-nothing). - A failed turn does not leave a partial commit (all-or-nothing) and does not release the lock mid-write.
- The commit SHA is surfaced for downstream consumers (indexer/projector). - The commit SHA is surfaced for downstream consumers (indexer/projector).
## Out of scope ## Out of scope
@ -32,6 +33,10 @@ Turn staged agent/editor/upload writes into **one atomic git commit** per turn/s
- Building the chunk/embedding index from the commit → Phase 4. - Building the chunk/embedding index from the commit → Phase 4.
- Zero row projection → Phase 6. - Zero row projection → Phase 6.
## Resolved (see [`00c-shared-contract.md`](00c-shared-contract.md))
- **Author identity + staged-op state keys:** C4 (both already exist in the current middleware).
## Open questions ## Open questions
1. Commit message format (structured for later `git log` parsing vs. freeform). 1. Commit message format (structured for later `git log` parsing vs. freeform).