Skip to content

refactor(storage): add bounded context offload lifecycle - #4159

Merged
likun666661 merged 2 commits into
mainfrom
refactor/context-offload-bounded-lifecycle
Aug 29, 2026
Merged

refactor(storage): add bounded context offload lifecycle#4159
likun666661 merged 2 commits into
mainfrom
refactor/context-offload-bounded-lifecycle

Conversation

@likun666661

Copy link
Copy Markdown
Member

Summary

  • Extend the context-offload authority with atomic reference copy, Session retirement, and bounded garbage collection.
  • Add schema v2 with an indexed context_gc_candidates eligibility set, so GC selects bounded metadata batches instead of scanning or anti-joining the complete blob population.
  • Keep logical and physical usage counters transactionally consistent across copy, release, retirement, shared blobs, and GC.
  • Add v1-to-v2 orphan migration, failpoint rollback coverage, and EXPLAIN QUERY PLAN assertions for the Session and GC indexes.

This is a stacked, storage-only follow-up to #4078. Its base is refactor/context-offload-sqlite-foundation; it should be rebased to main after #4078 merges. No runtime consumer is wired yet, so this does not change production behavior.

Refs #4071
Depends on #4078

Bounded-work contracts

  • Session retirement starts from context_refs_session and is proportional to references owned by that Session.
  • Last-reference release records eligibility transactionally in context_gc_candidates.
  • GC reads at most maxBlobs + 1 indexed candidate rows, obeys both blob and byte budgets, and never materializes payloads while selecting work.
  • Copy points new Session-owned refs at existing immutable blobs; physical usage does not increase.

Verification

  • npm --workspace @maka/core run build
  • npm --workspace @maka/storage run build
  • NODE_NO_WARNINGS=1 node --test packages/storage/dist/__tests__/sqlite-context-offload-store.test.js — 16/16 pass
  • NODE_NO_WARNINGS=1 node --test --test-reporter=dot "packages/storage/dist/**/*.test.js" — full storage suite passes
  • npx biome check on all changed TypeScript files
  • npm run check:asf-headers

AI use

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool and scope: OpenAI Codex contributed repository inspection, lifecycle and schema design, implementation, tests, and PR text. The commit includes the required Generated-by trailer.

Checklist

  • Tests cover the change and fail without it
  • Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

  • Yes
  • No — storage contracts remain unwired to production consumers

Base automatically changed from refactor/context-offload-sqlite-foundation to main August 29, 2026 10:22
@likun666661
likun666661 force-pushed the refactor/context-offload-bounded-lifecycle branch from 8ffaf9b to 9b04195 Compare August 29, 2026 10:23

@Astro-Han Astro-Han left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approved.

@likun666661
likun666661 merged commit 8b93dd5 into main Aug 29, 2026
2 checks passed
@likun666661
likun666661 deleted the refactor/context-offload-bounded-lifecycle branch August 29, 2026 10:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants