feat: resume retained materialization predecessors by flyingrobots · Pull Request #771 · git-stunts/git-warp

flyingrobots · 2026-07-24T13:46:48Z

Summary

retain a canonical replay basis alongside materialization roots in descriptor schema v4
reopen exact retained materializations without covered patch replay
find causally compatible retained predecessors and replay only the suffix
keep workspace ownership, promotion, pruning, and integrity validation inside the git-cas boundary
document the full-state replay basis as a compatibility bridge rather than the bounded-memory endpoint

Safety and compatibility

exact resume is disabled for receipt-producing reads
predecessor resume is disabled for receipt- or diff-producing reads
current-schema cache keys are lane-scoped before predecessor descriptors are read
predecessor discovery inspects at most 1,024 entries for the active lane and returns no predecessor above the bound, allowing normal fallback
replay bases are canonically decoded and verified against the retained state hash
descriptor pages and bundles carry explicit staging-workspace retention witnesses
legacy v2/v3 anchors remain reachable until successful v4 promotion, then are removed through the cache API

Validation

npm run lint
npm run typecheck
npm run typecheck:consumer
npm run test:local — 584 files passed, 1 skipped; 7,173 tests passed, 2 skipped
npm run build
npm run typecheck:surface
npm run lint:md
npm run lint:links
npm run lint:docs-topology
focused review-repair unit and integration suites — 65 passed
coverage suite — 605 files passed, 1 skipped; 7,334 tests passed, 2 skipped; 92.94% line coverage against the 92.93% ratchet
Graft structural review — 37 files, zero detected public breaking changes
repository IRONCLAD pre-push gate — all gates passed

Refs #738
Refs #759

coderabbitai · 2026-07-24T13:47:24Z

📝 Walkthrough

Walkthrough

Retained materialization support now stores a canonical replay basis, upgrades descriptors to schema v4, resumes exact or compatible predecessor materializations, and replays only predecessor suffixes when eligible. CAS adapters, controller wiring, shared caching, ports, fixtures, tests, and documentation are updated accordingly.

Changes

Retained materialization resume

Layer / File(s)	Summary
Replay-basis contracts and shared caches `src/domain/materialization/`, `src/infrastructure/adapters/GitCasMaterializationDescriptor.ts`, `src/infrastructure/codecs/WarpStateCborCodec.ts`, `src/ports/`, `src/domain/warp/RuntimeHostBoot.ts`	Materialization roots and promotion contracts include `replay-basis`; descriptors use schema v4; canonical full-state decoding and shared page-cache wiring are added.
CAS replay-basis and predecessor acquisition `src/infrastructure/adapters/GitCasMaterializationPredecessorResolver.ts`, `src/infrastructure/adapters/GitCasMaterializationReplayBasis.ts`, `src/infrastructure/adapters/GitCasMaterializationStoreAdapter.ts`, `test/helpers/`, `test/unit/infrastructure/adapters/`, `test/integration/infrastructure/adapters/*`	Git CAS stores and validates replay-basis assets, scans bounded paged v4 entries for compatible predecessors, stages retained assets, and cleans up legacy entries.
Exact and predecessor controller resume `src/domain/services/controllers/*`	Live materialization first attempts retained exact or predecessor resume, passes replay-basis roots through reduction, replays predecessor suffixes, and falls back to state-cache or ordinary replay.
Resume validation and behavior documentation `docs/topics/cas-first-memoized-materialization.md`, `test/integration/api/materialization.retainedResume.test.ts`, `test/unit/domain/*`	Documentation and tests cover schema v4 semantics, replay-basis restoration, predecessor selection, suffix replay, cache activity, and updated root fixtures.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Runtime
  participant MaterializeLiveStrategy
  participant RetainedMaterializationResumeStrategy
  participant MaterializationStore
  participant GitCasCache
  participant ReplayBasis
  Runtime->>MaterializeLiveStrategy: materialize coordinate
  MaterializeLiveStrategy->>RetainedMaterializationResumeStrategy: tryResume coordinate
  RetainedMaterializationResumeStrategy->>MaterializationStore: acquire exact or predecessor
  MaterializationStore->>GitCasCache: inspect v4 cache entries
  GitCasCache-->>MaterializationStore: compatible retained coordinate
  MaterializationStore->>ReplayBasis: load canonical replay basis
  ReplayBasis-->>MaterializationStore: validated WarpState
  MaterializationStore-->>RetainedMaterializationResumeStrategy: acquired materialization
  RetainedMaterializationResumeStrategy-->>MaterializeLiveStrategy: resumed MaterializeResult

Possibly related PRs

git-stunts/git-warp#751: Extends the retained CAS materialization foundation in the same domain and storage layers.
git-stunts/git-warp#754: Shares exact retained-resume and descriptor machinery.
git-stunts/git-warp#762: Modifies the coupled descriptor and controller retained-materialization paths.

Poem

A rabbit found a replay root,
And cached it snug and tight.
V4 hops through predecessor trails,
Then replays just the suffix right.
No receipt, no diff, just roots in flight—
Thump-thump, the state is light!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 4.17% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately reflects the main retained-predecessor resume change.
Description check	✅ Passed	The description is mostly complete with summary, issue refs, safety notes, and validation, though it omits the template's explicit ADR checklist.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-07-24T13:54:36Z

Release Preflight

package version: 18.2.1
prerelease: false
npm dist-tag on release: latest
npm pack dry-run: passed
jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Main Push Release Branch Check will run final preflight and create v18.2.1. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.

coderabbitai

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/topics/cas-first-memoized-materialization.md`:
- Around line 87-95: Update the lifecycle diagram and its “Check the WARP state
cache” step to show that MaterializeLiveStrategy.materialize() first attempts
retained exact and compatible-predecessor resume, then reads the WARP state
cache only when retained resume does not apply. Preserve the existing branching
and behavior descriptions while correcting the documented lookup order.

In `@src/infrastructure/adapters/GitCasMaterializationPredecessorResolver.ts`:
- Around line 17-18: Update the predecessor resolution flow around
acquireBestCompatiblePredecessorLocked to scope cache keys and scan-budget
accounting by lane and coordinate before reading descriptors, preventing one
lane’s entries from consuming another’s budget. Convert
storageError('materialization cache exceeds predecessor scan limit') into a null
predecessor result so MaterializeLiveStrategy.materialize() can fall back to
resolveConfiguredStateCache instead of propagating the error.

In `@test/helpers/InMemoryMaterializationStore.ts`:
- Around line 125-127: Update the replay-basis handling in
InMemoryMaterializationStore to store a detached codec round-trip snapshot
rather than request.replayBasis directly, and apply the same conversion when
returning the basis so callers receive a fresh instance. Preserve the existing
replayBases keying and behavior for undefined bases.

In
`@test/integration/infrastructure/adapters/GitCasMaterializationStoreAdapter.integration.test.ts`:
- Line 384: Update the fixture’s replayBasis setup near
MaterializationRoot.retained so it does not alias replayBasis to
provenanceSupport. Either create a dedicated ninth bundle containing the
replay-basis member, or use MaterializationRoot.unavailable() when the fixture
does not intend to provide replay data.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 10800259-9856-4f2b-9c86-d7fcc9da2d61

📥 Commits

Reviewing files that changed from the base of the PR and between 800a1e6 and ef0f104.

📒 Files selected for processing (34)

docs/topics/cas-first-memoized-materialization.md
src/domain/materialization/MaterializationRoots.ts
src/domain/materialization/TrieMaterializationReader.ts
src/domain/services/controllers/MaterializationRetention.ts
src/domain/services/controllers/MaterializeController.ts
src/domain/services/controllers/MaterializeHelpers.ts
src/domain/services/controllers/MaterializeLiveStrategy.ts
src/domain/services/controllers/MaterializeSessionBridge.ts
src/domain/services/controllers/MaterializeStrategyRuntime.ts
src/domain/services/controllers/RetainedMaterializationResumeStrategy.ts
src/domain/warp/RuntimeHostBoot.ts
src/infrastructure/adapters/GitCasMaterializationDescriptor.ts
src/infrastructure/adapters/GitCasMaterializationPredecessorResolver.ts
src/infrastructure/adapters/GitCasMaterializationReplayBasis.ts
src/infrastructure/adapters/GitCasMaterializationStoreAdapter.ts
src/infrastructure/adapters/GitCasMaterializationStoreTypes.ts
src/infrastructure/adapters/GitCasMaterializationStoreWitness.ts
src/infrastructure/adapters/GitCasMaterializationWorkspace.ts
src/infrastructure/codecs/WarpStateCborCodec.ts
src/ports/MaterializationStorePort.ts
src/ports/MaterializationWorkspacePort.ts
test/helpers/InMemoryGitCasFacade.ts
test/helpers/InMemoryMaterializationStore.ts
test/integration/api/materialization.retainedResume.test.ts
test/integration/infrastructure/adapters/GitCasMaterializationStoreAdapter.integration.test.ts
test/unit/domain/materialization/MaterializationIdentity.test.ts
test/unit/domain/materialization/TrieMaterializationReader.test.ts
test/unit/domain/services/controllers/MaterializeController.liveNodeRead.test.ts
test/unit/domain/services/controllers/MaterializeController.stateSession.test.ts
test/unit/domain/services/controllers/MaterializeController.test.ts
test/unit/domain/warp/hydrateCheckpointIndex.regression.test.ts
test/unit/infrastructure/adapters/GitCasMaterializationStoreAdapter.lifecycle.test.ts
test/unit/infrastructure/adapters/GitCasMaterializationStoreAdapter.resume.test.ts
test/unit/infrastructure/adapters/GitCasMaterializationStoreAdapter.test.ts

📜 Review details

⏰ Context from checks skipped due to timeout. (3)

GitHub Check: coverage-threshold
GitHub Check: test-node (22)
GitHub Check: preflight

🧰 Additional context used

📓 Path-based instructions (5)

src/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

src/**/*.{ts,tsx,js,jsx}: Do not introduce any, as any, as unknown as, unknown (outside adapters), Record<string, unknown> (outside adapters), *Like placeholder types, JSON.parse/JSON.stringify (outside adapters), fetch (outside adapters), process.env (outside adapters), @ts-ignore, or z.any() in core code; use validated boundary models and ports instead.
Use constructor-injected ports for external capabilities; do not rely on ambient dependencies for I/O, clocks, persistence, or entropy.
Do not create utils.ts, helpers.ts, misc.ts, or common.ts; name files after the actual concept they model.
Prefer one file per class, type, or object; if a file accumulates peer concepts, split it.
Keep helper corridors, fake shape trust, transitional duplication, and compile-time theater out of the codebase; runtime-honest TypeScript must reflect actual behavior.
No enum usage; prefer runtime-backed domain forms and unions.
Do not use boolean trap parameters; prefer named option objects or separate methods.
Avoid magic strings or numbers when a named constant should exist.
Keep domain bytes as Uint8Array; Buffer belongs in infrastructure adapters.

Files:

src/domain/services/controllers/MaterializeHelpers.ts
src/domain/services/controllers/MaterializeStrategyRuntime.ts
src/infrastructure/codecs/WarpStateCborCodec.ts
src/infrastructure/adapters/GitCasMaterializationWorkspace.ts
src/ports/MaterializationWorkspacePort.ts
src/infrastructure/adapters/GitCasMaterializationStoreTypes.ts
src/domain/warp/RuntimeHostBoot.ts
src/infrastructure/adapters/GitCasMaterializationReplayBasis.ts
src/infrastructure/adapters/GitCasMaterializationDescriptor.ts
src/domain/materialization/TrieMaterializationReader.ts
src/infrastructure/adapters/GitCasMaterializationStoreWitness.ts
src/domain/materialization/MaterializationRoots.ts
src/domain/services/controllers/MaterializeSessionBridge.ts
src/ports/MaterializationStorePort.ts
src/infrastructure/adapters/GitCasMaterializationPredecessorResolver.ts
src/domain/services/controllers/MaterializationRetention.ts
src/domain/services/controllers/MaterializeController.ts
src/domain/services/controllers/MaterializeLiveStrategy.ts
src/domain/services/controllers/RetainedMaterializationResumeStrategy.ts
src/infrastructure/adapters/GitCasMaterializationStoreAdapter.ts

src/domain/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

src/domain/**/*.{ts,tsx,js,jsx}: In src/domain/**, do not use Date.now(), new Date(), Date(), performance.now(), Math.random(), crypto.randomUUID(), crypto.getRandomValues(), setTimeout, setInterval, raw new Error(...)/new TypeError(...), or direct imports from Node built-ins; time, entropy, and external capabilities must enter through ports or parameters, and domain errors should extend WarpError.
Construct domain objects only in core when doing so establishes validated runtime truth; do not build infrastructure adapters, host APIs, persistence implementations, wall clocks, or entropy sources inside core.
Prefer discriminated unions and explicit result types instead of boolean-flag bags, and model expected failures as return values rather than exceptions.
src/domain/ must not import host APIs or Node-specific globals; hexagonal architecture boundaries are mandatory.
Domain code must not use the wall clock directly; time must enter through a port or parameter.

Files:

src/domain/services/controllers/MaterializeHelpers.ts
src/domain/services/controllers/MaterializeStrategyRuntime.ts
src/domain/warp/RuntimeHostBoot.ts
src/domain/materialization/TrieMaterializationReader.ts
src/domain/materialization/MaterializationRoots.ts
src/domain/services/controllers/MaterializeSessionBridge.ts
src/domain/services/controllers/MaterializationRetention.ts
src/domain/services/controllers/MaterializeController.ts
src/domain/services/controllers/MaterializeLiveStrategy.ts
src/domain/services/controllers/RetainedMaterializationResumeStrategy.ts

src/domain/**/!(*.test).{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use explicit domain concepts with validated constructors, Object.freeze, and instanceof dispatch; domain objects should be runtime-backed nouns, not ad hoc shape bags.

Files:

src/domain/services/controllers/MaterializeHelpers.ts
src/domain/services/controllers/MaterializeStrategyRuntime.ts
src/domain/warp/RuntimeHostBoot.ts
src/domain/materialization/TrieMaterializationReader.ts
src/domain/materialization/MaterializationRoots.ts
src/domain/services/controllers/MaterializeSessionBridge.ts
src/domain/services/controllers/MaterializationRetention.ts
src/domain/services/controllers/MaterializeController.ts
src/domain/services/controllers/MaterializeLiveStrategy.ts
src/domain/services/controllers/RetainedMaterializationResumeStrategy.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{ts,tsx,js,jsx}: Do not use direct imports from src/infrastructure/** in src/domain/** or src/ports/**; depend on a port instead.
Do not use direct Node built-ins in src/domain/** or src/ports/**; use a port instead.

Files:

src/domain/services/controllers/MaterializeHelpers.ts
test/unit/domain/materialization/TrieMaterializationReader.test.ts
src/domain/services/controllers/MaterializeStrategyRuntime.ts
src/infrastructure/codecs/WarpStateCborCodec.ts
test/unit/domain/services/controllers/MaterializeController.liveNodeRead.test.ts
src/infrastructure/adapters/GitCasMaterializationWorkspace.ts
test/unit/domain/warp/hydrateCheckpointIndex.regression.test.ts
test/integration/infrastructure/adapters/GitCasMaterializationStoreAdapter.integration.test.ts
src/ports/MaterializationWorkspacePort.ts
src/infrastructure/adapters/GitCasMaterializationStoreTypes.ts
src/domain/warp/RuntimeHostBoot.ts
test/unit/domain/materialization/MaterializationIdentity.test.ts
test/helpers/InMemoryMaterializationStore.ts
test/unit/infrastructure/adapters/GitCasMaterializationStoreAdapter.resume.test.ts
src/infrastructure/adapters/GitCasMaterializationReplayBasis.ts
src/infrastructure/adapters/GitCasMaterializationDescriptor.ts
src/domain/materialization/TrieMaterializationReader.ts
src/infrastructure/adapters/GitCasMaterializationStoreWitness.ts
src/domain/materialization/MaterializationRoots.ts
src/domain/services/controllers/MaterializeSessionBridge.ts
src/ports/MaterializationStorePort.ts
src/infrastructure/adapters/GitCasMaterializationPredecessorResolver.ts
src/domain/services/controllers/MaterializationRetention.ts
test/unit/domain/services/controllers/MaterializeController.test.ts
test/integration/api/materialization.retainedResume.test.ts
src/domain/services/controllers/MaterializeController.ts
test/helpers/InMemoryGitCasFacade.ts
test/unit/infrastructure/adapters/GitCasMaterializationStoreAdapter.test.ts
src/domain/services/controllers/MaterializeLiveStrategy.ts
test/unit/infrastructure/adapters/GitCasMaterializationStoreAdapter.lifecycle.test.ts
test/unit/domain/services/controllers/MaterializeController.stateSession.test.ts
src/domain/services/controllers/RetainedMaterializationResumeStrategy.ts
src/infrastructure/adapters/GitCasMaterializationStoreAdapter.ts

src/ports/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

In src/ports/**, do not import Node built-ins or src/infrastructure/**; ports must stay abstract and depend only on boundary-safe types.

Files:

src/ports/MaterializationWorkspacePort.ts
src/ports/MaterializationStorePort.ts

🪛 ast-grep (0.44.1)

test/integration/infrastructure/adapters/GitCasMaterializationStoreAdapter.integration.test.ts

[warning] Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import { execFile } from 'node:child_process';
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').