Repository navigation
feat(api): expose each project's change journal at /v2/projects/{id}/changes - #2118
Merged
Merged
Conversation
…changes
Core already records every accepted note create, update, move and delete
in an ordered per-project journal, but nothing exposed it. A client that
was away (a reload, a dropped live-update stream) could only refetch
everything. This route answers "what changed since position N" in one
call. Tracked as BMEM-115.
- GET /v2/projects/{project_id}/changes?after=N&limit=M returns head,
after, next_after, has_more and up to limit changes in position order.
- head is read first and rows are capped at head, so next_after never
passes head and after=head always returns no changes.
- after > head returns 409 {"code": "cursor_ahead_of_head", "head": N},
the case where a cursor outlives a restored database.
- No cached_read dependency: a cached page would hide new changes.
- ProjectRepository.list_accepted_note_changes gains an optional limit;
the export caller is unchanged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Drew Cain <groksrc@gmail.com>
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
groksrc
commented
Nov 14, 2026
groksrc
left a comment
Member
Author
There was a problem hiding this comment.
Review result: no blocking findings.
This endpoint satisfies the core change-journal contract without exposing internal journal columns or allowing the read cache to hide new changes.
Verified at head a7be835a707465e48f4477b97a5a015443126842:
project_router.pyreads the committed journal head first, caps rows at that head, and returns the required cursor and HTTP 409 semantics.project_repository.pyappliesLIMITafter position ordering and leaves unlimited callers unchanged.- The response models document every field and expose none of
entity_id, internalproject_id,actor_user_profile_id, ormaterialized_at. - Route tests cover create, update, move, delete, pagination, freshness, invalid bounds, the cursor-ahead conflict, unknown-project parity, and cache exclusion.
- The focused SQLite review run passed:
22 passed in 201.27s. - All 51 reported GitHub checks are successful at this head, including SQLite, PostgreSQL, coverage, CodeQL, DCO, and the pull-request title gate.
- The repository diff contains no board ticket key.
Next step: land this core pull request before the Cloud pull request, then update Cloud’s core pin to the commit on main that contains this change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
GET /v2/projects/{project_id}/changes?after=N&limit=M, which answers "what changed in this project since journal position N" in one call. Core already writes every accepted note create, update, move and delete to an ordered per-project journal (accepted_project_note_change, positioned byproject.partition_position), but nothing exposed it. Without this, a client that was away (a page reload, a dropped live-update stream) can only refetch everything. Tracked as BMEM-115.Response
{ "head": 42, "after": 40, "next_after": 42, "has_more": false, "changes": [ {"position": 41, "operation": "moved", "note_external_id": "…", "permalink": "…", "title": "…", "file_path": "archive/a.md", "previous_file_path": "notes/a.md", "accepted_at": "…", "source": "move_note", "db_version": 3, "db_checksum": "…", "actor_kind": null, "actor_name": null} ] }headis the project's journal position when the request was read. Every change at or below it is committed.changesholdsafter < position <= head, in order, at mostlimit(default 200, 1–1000).next_afteris the last returned position, orafterwhen the page is empty. The client passes it asafternext time.has_moreisnext_after < head.after > headreturns 409{"detail": {"code": "cursor_ahead_of_head", "head": N}}. That happens when a cursor outlives its journal, for example after a database restore. The client must resync from scratch.entity_id,project_id,actor_user_profile_id,materialized_at) are not exposed.Design notes
headfirst, then the rows capped athead. A writer claims a position withUPDATE project SET partition_position = partition_position + 1 … RETURNINGand inserts its row in the same transaction. The update locks the project row, so every position at or below a committed head is already visible. Rows committed after the head read wait for the next page.cached_read: a cached page would hide new changes. A test asserts the route has no read-cache dependency.ProjectRepository.list_accepted_note_changesgains an optionallimit(applied afterORDER BY). The export caller passes nothing and is unchanged. A smallget_partition_positionreader was added.Tests
New
tests/api/v2/test_project_changes_router.pydrives real API writes and reads them back:previous_file_pathon the move and the deleted note's id and path on the delete;after=headreturns no changes; paging withlimit=2over five changes returns each once, in order;after > head→ 409;after=-1,limit=0,limit=1001→ 422; an unknown project id gets the same 404 body as/directory/tree;head,next_after,has_moreand the 409.Repository tests cover
limitpaging andget_partition_position.Ran locally on revision
a7be835a:tests/okfandtests/api/v2/test_project_router.py: 198 passed on SQLite;ruff checkandruff formatclean;ty check src tests test-intreports only the existing unresolved optionalpymilvusimport.The full suite runs in CI (
test.yml).Follow-up
basicmachines-co/basic-memory-cloudwill proxy this route atGET /api/v2/projects/{project_id}/changesin a separate PR that bumps its core pin.🤖 Generated with Claude Code