id: "GW20-017"
title: "Read entity support slices without prior whole-graph materialization"
type: "feature"
status: "planned"
milestone: "v20.1.0"
category: "required"
workstream: "query"
issue: "#973"
baseline_commit: "ceb58e656ec5bc85f0ae5991bf2a55599693bbb3"
feedback_sections: [12]
prerequisites: [473]

Feature

LLM prompt

Complete GW20-017: Read entity support slices without prior whole-graph materialization.
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.
Problem to resolve:
The internal materializeSlice requires cached full state and reports whole-history work in the single-writer experiment. No supported public slice answers it.
Acceptance checks:
Expose a supported basis-bound slice reading without a prior full materialization.
Select entity footprints and all required causal and lifecycle support through bounded demand.
Separate an entity footprint from a causal down-set. Never claim that every single-writer causal cone is small.
For independent entity edits, work tracks selected support rather than unrelated retained history.
For dense causal dependencies, report actual support, cost, cursor, and incompleteness honestly.
No private import, cached full-graph prerequisite, or hidden whole-source scan can satisfy the public witness.
Trace the actual footprint index and declared-read expansion. The existing controller does not traverse writer-parent edges in its backward-cone loop.
Use selected footprints plus required read, membership, lifecycle, and policy support to the chosen basis.
Do not drop required support to shrink a benchmark. Dense dependencies may legitimately require broad work and must report it.
Read these source paths:
src/domain/services/controllers/ProvenanceController.ts
src/domain/services/provenance/ProvenanceIndex.ts
src/domain/warp/RuntimePatchCollector.ts
Prerequisites: #473
Scope exclusions: The v21 retained-root migration or the v22 strand-collapse optic. Do not transfer this public defect to those larger projects.
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 12.
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: #973.

Read these source and test surfaces before work:

• src/domain/services/controllers/ProvenanceController.ts
• src/domain/services/provenance/ProvenanceIndex.ts
• src/domain/warp/RuntimePatchCollector.ts

2. Problem Description

The internal materializeSlice requires cached full state and reports whole-history work in the single-writer experiment. No supported public slice answers it.

2b. Proposed Solution

Build a public slice consumer of the supported provenance and footprint boundary. Preserve dependency closure and explicit support budgets.

2c. Alternatives considered and rejected

Reject a private-import workaround. It does not provide a supported application contract.
Reject a documentation-only substitute when this task requires runtime behavior.
Keep larger storage and package redesigns under their existing issues.

2d. Acceptance Criteria

• Expose a supported basis-bound slice reading without a prior full materialization.
• Select entity footprints and all required causal and lifecycle support through bounded demand.
• Separate an entity footprint from a causal down-set. Never claim that every single-writer causal cone is small.
• For independent entity edits, work tracks selected support rather than unrelated retained history.
• For dense causal dependencies, report actual support, cost, cursor, and incompleteness honestly.
• No private import, cached full-graph prerequisite, or hidden whole-source scan can satisfy the public witness.
• Trace the actual footprint index and declared-read expansion. The existing controller does not traverse writer-parent edges in its backward-cone loop.
• Use selected footprints plus required read, membership, lifecycle, and policy support to the chosen basis.
• Do not drop required support to shrink a benchmark. Dense dependencies may legitimately require broad work and must report it.

2e. Test Plan

Golden: Use 50 entities and 100, 400, and 1600 patches. Read one entity without pre-materialization. Count touched patches and compare exact values.

Edges: Single and multiple writers; cross-entity reads; shared patch batches; removes; missing support; cancellation; dense dependency controls.

Known failure modes: preserve typed refusal, atomic publication, and complete evidence. Do not conceal unavailable support.

Fuzz and stress: use fixed fixture sizes and seeds. Apply the roadmap resource guards. Do not start an unbounded campaign.

3. Prerequisites

• Materialization-free provenance readings #473 must be integrated. The slice consumer requires the supported basis-owned provenance producer.

4. Scope

In: The internal materializeSlice requires cached full state and reports whole-history work in the single-writer experiment. No supported public slice answers it.

Out: The v21 retained-root migration or the v22 strand-collapse optic. Do not transfer this public defect to those larger projects.

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

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

• #567
• #626
• #814