Bounded-memory large-graph product gate

[flyingrobots]

Migrated from Method backlog

GitHub Issues are now the live work tracker. Repository docs remain Method evidence.

Field	Value
Source backlog	docs/method/backlog/v18.0.0/PERF_bounded-memory-large-graph-product-gate.md
Archived source	docs/archive/backlog/github-issue-migration-2026-06-01/docs/method/backlog/v18.0.0/PERF_bounded-memory-large-graph-product-gate.md
Original lane	v18.0.0
Original id	PERF_bounded-memory-large-graph-product-gate
Original legend	PERF
Original feature	graph-model-substrate
Original blocked_by	API_no-full-materialization-first-use-optics
Original blocks	API_optics-public-api-closeout, RELEASE_v18-public-release-blockers

Original backlog card

Bounded-memory large-graph product gate

Why

V18 is blocked until git-warp can honestly operate on graphs larger than the
memory footprint git-warp is allowed to use. The release cannot rely on full
graph state, full indexes, full patch arrays, full snapshots, or full result
arrays fitting in process memory.

This is now a v18 release gate, not a later aspiration. The Optics honesty gate
removes the immediate first-use materialization footgun; this gate proves the
broader product invariant:

normal public reads, writes, content lookup, and sync must run through bounded
providers under an explicit git-warp memory budget

Done Looks Like

• WarpMemoryPool or an equivalent memory-budget contract exists with leases,
  bounded buffers, bounded shard caches, chunk policy, budget errors, and
  observable metrics.
• A conformance fixture creates or opens a graph larger than a reasonable fixed
  git-warp memory pool and exercises the public first-use API without full
  residency.
• Blessed public paths fail tests if they call materialize(),
  _materializeGraph(), full snapshot creation, full node/edge array
  construction, observer snapshot cloning, or unbounded result collection.
• Patch history can be consumed through a bounded patch-stream substrate with
  controlled decode windows.
• Read-basis and index construction are stream-built or shard-built rather than
  derived from a full in-memory WarpState.
• Sharded fact indexes cover node liveness, edge endpoints, properties, content
  references, observed dots, and provenance needed by public reads and writes.
• Existing-entity writes use targeted fact resolvers instead of _cachedState
  or equivalent full-state access.
• Public reads expose bounded, streaming, or cursor contracts. Array-producing
  helpers require explicit limits or are classified as diagnostic, offline, or
  legacy.
• Query APIs have budget enforcement and explain their cost path, including
  exact-id, prefix/index, tail scan, missing index, and rejected full-scan cases.
• Content reads perform bounded content-reference lookup before streaming bytes;
  byte streaming alone is not enough.
• Sync uses cursors or batches at the protocol boundary and does not accumulate
  an unbounded patches array before returning.
• worldline.capabilities() or equivalent capability reporting makes bounded,
  streaming, cursor, transitional, diagnostic, offline, and legacy surfaces
  inspectable.
• Operator tooling can run a memory-budget doctor or equivalent report that
  identifies unsafe public paths and missing bases or indexes.
• Bounded mode rejects legacy full-residency APIs unless the caller explicitly
  opts into diagnostic or offline full-residency behavior.

Non-Goals

• Native Continuum witnesshood.
• Echo scheduler parity.
• Distributed braid or plural-site semantics beyond what the v18 large-graph
  conformance needs.
• Making every global graph question cheap. Global questions may remain
  expensive, but their memory strategy must be explicit and bounded.

Starting Points

• Design
• WarpWorldline.ts
• WarpGraph.ts
• SyncController tests
• v20 streaming backlog note
• out-of-core materialization backlog note

[flyingrobots]

Design docs now tracking the release gates:

• Optics first-use materialization gate: docs/design/0266-v18-no-full-materialization-first-use-optics/v18-no-full-materialization-first-use-optics.md
• Bounded-memory large-graph gate: docs/design/0267-v18-bounded-memory-large-graph-product-gate/v18-bounded-memory-large-graph-product-gate.md
• Optics closeout status update: docs/design/0265-v18-optics-public-api-closeout/v18-optics-public-api-closeout.md

v18 is blocked by both gates.

[flyingrobots]

Gate 1 design is now in repo at docs/design/0269-v18-gate-1-optics-honesty/v18-gate-1-optics-honesty.md. Gate 1 does not implement the memory pool or bounded-memory platform, but it adds the public API cost inventory and first-use tripwires that gate 2 will build on.