Skip to content

feat(memory): add bounded pagination for Memory changes and history #1657

Description

@knqiufan

Feature description

Add bounded Memory change/history queries for the history portion of D2 in RFC #1455, as a focused deliverable related to #1321.

Problem and proposed solution

At aa697c5315204249e090acdf1a00d0582e851c5f, POST /v1/memory/changes accepts scope_id and since_revision but no page size or cursor. The backend reads Artifact revisions before filtering the requested range and assembling revision changes.

Define a query with deterministic revision/change ordering, a bounded page, and an opaque continuation cursor. A limit on revision count alone is insufficient if a single revision contains many changes.

Acceptance criteria

  • Specify page-size bounds, ordering, lower/upper revision boundaries, end-of-list semantics, and cursor validity/expiry.
  • Preserve existing documented semantics: since_revision is an exclusive lower bound; 0 requests history from revision 1; a positive nonexistent revision is an error. Explicitly document the existing omitted/null behavior and any versioned migration.
  • Define a stable upper boundary or another explicit consistency strategy when new revisions arrive during traversal.
  • Bound a page even when one revision has a large change set. Specify continuation within a revision or another explicit bounded representation, preserving precise revision/entry references.
  • Do not load all historical revisions and then slice the result. Document and measure remaining per-revision/manifest costs and address anything that violates the declared bound.
  • Preserve authorization on every page; reject mismatched, tampered, or expired cursors without leaking another Scope's history.
  • Retain change metadata and exact references without expanding all entry bodies; details remain separately retrievable under current authorization.
  • Test empty, multi-page, and large-single-revision histories; revision-boundary inputs; invalid cursors; concurrent new revisions; and authorization changes.
  • Define an additive/versioned compatibility path. Existing consumers must not silently receive only a first page where they previously received a complete result.
  • Update OpenAPI, generate derived code with make api-generate, and run make contract-test, focused behavior tests, and required checks.

Alternatives considered

  • Loading complete history and paginating in Desktop: unbounded Server and network cost.
  • Limiting revision count alone: does not bound a large change set inside one revision.
  • Using Candidate history as Memory history: different authoritative data and semantics.

Additional context

Desktop consumer: #1654.
Related entry-pagination deliverable: #1656.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions