Skip to content

feat(api): expose each project's change journal at /v2/projects/{id}/changes - #2118

Merged
groksrc merged 1 commit into
mainfrom
shipright/BMEM-115
Nov 14, 2026
Merged

groksrc merged 1 commit into
mainfrom
shipright/BMEM-115

Conversation

@groksrc

@groksrc groksrc commented Nov 14, 2026

Copy link
Copy Markdown
Member

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 by project.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}
  ]
}
  • head is the project's journal position when the request was read. Every change at or below it is committed.
  • changes holds after < position <= head, in order, at most limit (default 200, 1–1000).
  • next_after is the last returned position, or after when the page is empty. The client passes it as after next time. has_more is next_after < head.
  • after > head returns 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.
  • Internal columns (entity_id, project_id, actor_user_profile_id, materialized_at) are not exposed.

Design notes

  • Consistency: the route reads head first, then the rows capped at head. A writer claims a position with UPDATE project SET partition_position = partition_position + 1 … RETURNING and 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.
  • No cached_read: a cached page would hide new changes. A test asserts the route has no read-cache dependency.
  • Repository: ProjectRepository.list_accepted_note_changes gains an optional limit (applied after ORDER BY). The export caller passes nothing and is unchanged. A small get_partition_position reader was added.
  • Known gaps, stated in the OpenAPI description: the journal does not yet record files written straight to storage (WebDAV, sync tools, direct uploads), notes removed by a folder delete, or non-Markdown files. Clients that need those still need a full reload.

Tests

New tests/api/v2/test_project_changes_router.py drives real API writes and reads them back:

  • create, update, move, delete → four changes in order, with previous_file_path on the move and the deleted note's id and path on the delete;
  • after=head returns no changes; paging with limit=2 over five changes returns each once, in order;
  • a change made after one read appears on the next read;
  • after > head → 409; after=-1, limit=0, limit=1001 → 422; an unknown project id gets the same 404 body as /directory/tree;
  • the response hides internal columns; the OpenAPI description names head, next_after, has_more and the 409.

Repository tests cover limit paging and get_partition_position.

Ran locally on revision a7be835a:

  • new and repository tests: 22 passed on SQLite, 22 passed on Postgres (testcontainers);
  • tests/okf and tests/api/v2/test_project_router.py: 198 passed on SQLite;
  • ruff check and ruff format clean; ty check src tests test-int reports only the existing unresolved optional pymilvus import.

The full suite runs in CI (test.yml).

Follow-up

basicmachines-co/basic-memory-cloud will proxy this route at GET /api/v2/projects/{project_id}/changes in a separate PR that bumps its core pin.

🤖 Generated with Claude Code

…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>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-14T21:25:11.976162Z a7be835 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@groksrc groksrc left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.py reads the committed journal head first, caps rows at that head, and returns the required cursor and HTTP 409 semantics.
  • project_repository.py applies LIMIT after position ordering and leaves unlimited callers unchanged.
  • The response models document every field and expose none of entity_id, internal project_id, actor_user_profile_id, or materialized_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.

@groksrc groksrc added the review:done Automated review found no blocking issues label Nov 14, 2026
@groksrc
groksrc merged commit fdc6e37 into main Nov 14, 2026
52 checks passed
@groksrc
groksrc deleted the shipright/BMEM-115 branch November 14, 2026 23:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:done Automated review found no blocking issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant