id: "GW20-002"
title: "Remove the 1000-object checkpoint retention failure"
type: "bug"
status: "planned"
milestone: "v20.1.0"
category: "required"
workstream: "storage"
issue: "#958"
baseline_commit: "ceb58e656ec5bc85f0ae5991bf2a55599693bbb3"
feedback_sections: [2]
prerequisites: []

Bug

LLM prompt

Complete GW20-002: Remove the 1000-object checkpoint retention failure.
Read this entire task and its current GitHub issue before implementation.
Verify the current mainline and all prerequisite integrations.
Read AGENTS.md and the three TypeScript policy documents.
Use runtime-backed domain values and injected ports.
Keep parsing and codecs at the adapter boundary.
Preserve v20 APIs, stored identities, CRDT semantics, and failure meanings.
Use one coherent issue, PR, and mainline integration. Do not leave a broken intermediate state.
Reproduce the symptom in Docker. Fill Diagnosis with evidence before fix work.
Test each hypothesis against the actual execution path.
Problem to resolve:
The report records permanent checkpoint failure near 1600 live nodes. The nested failure rejects a cat-file batch with 1028 objects.
Acceptance checks:
A 5000-node Lane creates a retained checkpoint and reads exact values after reopen.
Checkpoint runs with 999, 1000, and 1001 metadata targets succeed within bounded request windows.
Repeated checkpoints and add/remove churn do not cause a target-count failure.
Missing objects, type mismatches, and publication races fail without a false retention receipt.
Consume a released git-cas fix and update the lockfile. Do not bypass retention or raise the Plumbing safety limit.
Every backend window stays within both 1000 objects and 65536 encoded command bytes, including SHA-256 identifiers.
Chunk metadata reads in the git-cas adapter for every consumer. Bound additional root-set admission buffers without redesigning root-set authority.
Preserve request order, duplicate results, cached entries, and per-target failures across windows. Publish retention only after all windows pass.
Read these source paths:
src/infrastructure/adapters/GitCasMaterializationWorkspace.ts
src/infrastructure/adapters/CborCheckpointStoreAdapter.ts
src/domain/services/controllers/CheckpointController.ts
Prerequisites: None established. Recheck external readiness.
Scope exclusions: Local vendoring, unrelated package extraction, or disabling retention checks.
Run all tests and benchmarks in COPY-based Docker without host repository mounts.
Use the project guarded runner and the shared git-locks authority.
Lock host/heavy-work and the exact worker key together for expensive work.
Limit build caches to 20 GiB, test data to 4 GiB, and logs to 128 MiB.
Require 50 GiB free on host and Docker backing storage before heavy work.
Enforce disk accounting, CPU, memory, timeout, and child-process shutdown.
Do not start an unguarded workload. Do not bypass a resource refusal.
Require full touched-code coverage for refactors and an all-green manual SSJS scorecard.
Record source, image, command, fixtures, results, limits, and the regression witness.
Commit only your own files. Do not amend, rebase, force, push, or publish without authorization.
Report incomplete or blocked checks. Do not claim completion from a narrow green test.
Link the issue, coherent PR, and actual mainline integration when those actions are authorized.

1. Background Context

Source: FEEDBACK-git-warp.md, sections 2.
The report SHA-256 is 9b15209d51cd705059a9e6bfebf0f6681ff832924c1462b99ff3cfebde6bacae.
The report uses npm git-warp 20.0.0 and git-cas 6.5.11.
Its runtime results come from macOS host experiments. This planning task did not rerun them.
Source review baseline: ceb58e65.

Tracker: #958.

Read these source and test surfaces before work:

• src/infrastructure/adapters/GitCasMaterializationWorkspace.ts
• src/infrastructure/adapters/CborCheckpointStoreAdapter.ts
• src/domain/services/controllers/CheckpointController.ts

Upstream source review used each repository's verified origin/main:

• git-cas RootSetPersistence
• git-cas GitPersistenceAdapter
• Plumbing GitCatFileSession

External gate: release the diagnosed git-cas correction before the git-warp dependency PR can complete.

2. Observed

The report records permanent checkpoint failure near 1600 live nodes. The nested failure rejects a cat-file batch with 1028 objects.

2b. Expected

A 5000-node Lane creates a retained checkpoint and reads exact values after reopen.

2c. Reproduction

Source report: repro/r15-checkpoint-node-limit.ts, repro/r14-retention-cause.ts, and repro/r16-limit-after-removal.ts. Not rerun here.

Golden regression: Checkpoint 500, 1500, 1600, and 5000 live nodes. Repeat at least three checkpoints, reopen, and verify retained content.

2d. Blast radius

Population: Lanes with enough retained metadata targets to exceed a backend request window.
Observed population count: unknown. The report measures fixtures, not deployed users.
No user-count query exists in this task. Do not infer a count from fixture size.
Since: reported in v20.0.0 on 2026-10-06. The introducing commit remains unverified.
Downstream: The report records permanent checkpoint failure near 1600 live nodes. The nested failure rejects a cat-file batch with 1028 objects.

2e. Hypothesis

On git-cas main, RootSetPersistence.#assertTargets calls readObjectInfos for every target. GitPersistenceAdapter sends all uncached targets to infoMany. Trace this exact publication route. Reject the hypothesis if the failing request comes from a different route.

2f. Diagnosis

3. Prerequisites

External gate: diagnose, fix, and release compatible git-cas metadata and root-set admission windows. Verify exact released versions before dependency adoption.

None established as an internal issue dependency. Verify the current boundary and external readiness before activation.

4. Scope

In: The report records permanent checkpoint failure near 1600 live nodes. The nested failure rejects a cat-file batch with 1028 objects.

Out: Local vendoring, unrelated package extraction, or disabling retention checks.

Safe intermediate state: one independently mergeable PR passes its relevant checks after its prerequisites.
Existing supported applications remain usable. Historical data remains intact.

5. Why now

This flaw blocks a supported Synapse store workflow or gives its operator incorrect guidance.
Resolve it within v20.1.0 without reducing the existing causal-history commitment.

6. Risks

Source inspection does not establish runtime or performance results.
Preserve historical identities, validation, and evidence. Do not weaken refusal to obtain a green result.
If the fix requires a breaking contract, record the conflict before activation. Do not hide it within a minor release.

7. Definition of Done

A reproducible regression fails on the baseline and passes on the candidate.

• A 5000-node Lane creates a retained checkpoint and reads exact values after reopen.
• Checkpoint runs with 999, 1000, and 1001 metadata targets succeed within bounded request windows.
• Repeated checkpoints and add/remove churn do not cause a target-count failure.
• Missing objects, type mismatches, and publication races fail without a false retention receipt.
• Consume a released git-cas fix and update the lockfile. Do not bypass retention or raise the Plumbing safety limit.
• Every backend window stays within both 1000 objects and 65536 encoded command bytes, including SHA-256 identifiers.
• Chunk metadata reads in the git-cas adapter for every consumer. Bound additional root-set admission buffers without redesigning root-set authority.
• Preserve request order, duplicate results, cached entries, and per-target failures across windows. Publish retention only after all windows pass.

Golden: Checkpoint 500, 1500, 1600, and 5000 live nodes. Repeat at least three checkpoints, reopen, and verify retained content.

Edges: Cached and uncached metadata; duplicate targets; zero targets; missing targets; mixed object types; normal GC.

All acceptance checks have evidence from the exact candidate.
Relevant lint, typecheck, compatibility, and Docker checks pass.
The manual SSJS scorecard is green. Refactor coverage reaches 100% on touched code.
Record the issue, PR, and mainline integration commit. Record any external release gate.
A required check with missing evidence remains incomplete.

8. Stakeholders

James Ross: git-warp maintainer and acceptance owner.
Synapse store authors: applications need correct writes, reads, history, and operational guidance.
Library and CLI consumers: existing v20 contracts must remain usable.

9. Related Issues

• #895