Optics public API closeout

[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/API_optics-public-api-closeout.md
Archived source	docs/archive/backlog/github-issue-migration-2026-06-01/docs/method/backlog/v18.0.0/API_optics-public-api-closeout.md
Original lane	v18.0.0
Original id	API_optics-public-api-closeout
Original legend	API
Original feature	graph-model-substrate
Original blocked_by	API_no-full-materialization-first-use-optics
Original blocks	RELEASE_v18-public-release-blockers

Original backlog card

Optics public API closeout

Status: branch-local implementation evidence exists, but the release-complete
claim is superseded by API_no-full-materialization-first-use-optics.

Design

0265 v18 Optics public API closeout

Why

Optics are part of the public-facing v18 value proposition. The current
Worldline-first API exposes events.optic(), but the release is not honest
until that path has a pinned coordinate, documented success setup, public
tests, recovery guidance, and package-surface contract.

Shipping with only an exposed narrow handle and a common
E_OPTIC_NO_BOUNDED_BASIS failure path would make Optics feel like a promise
that users cannot exercise. Shipping a setup path that requires first-use
application developers to reopen the deprecated graph-first API would also
undercut the v18 Worldline-first story.

The design now carries a 20-slice PRD and test plan for closing this release
gate. The default product targets are a Worldline-first basis setup path such
as worldline.prepareOpticBasis() and a pinned coordinate capture path such as
worldline.coordinate(), followed by coherent public node and property optic
reads through coordinate.optic().

The implementation has since exposed a sharper release blocker:
prepareOpticBasis() currently creates that basis by calling
graph.materialize() before checkpoint creation. That is useful branch-local
API evidence, but it is not an honest bounded first-use Optics path.

Done Looks Like

• A Worldline-first public basis setup path exists, is documented, and does not
  require first-use users to open openWarpGraph(...).
• A Worldline-first public coordinate capture path exists and pins the causal
  position used by downstream optic reads.
• openWarpWorldline(...).coordinate().optic().node(id).read() succeeds in a
  public-path fixture with real checkpoint-tail indexed evidence.
• openWarpWorldline(...).coordinate().optic().node(id).prop(key).read()
  succeeds in the same public-path fixture.
• Reads from one coordinate stay coherent when the live worldline advances
  between awaited reads.
• Success and failure tests prove optic reads do not fall back to whole-graph
  materialization.
• Basis setup itself does not perform full graph materialization on the
  documented first-use path.
• Docs show how the bounded checkpoint-tail basis is created or verified before
  the first coordinate optic read.
• Docs explain E_OPTIC_NO_BOUNDED_BASIS, E_OPTIC_TAIL_BUDGET_EXCEEDED, and
  recovery actions.
• Consumer type tests prove the intended public coordinate optic chain works
  without importing internal paths.
• The package-surface decision is explicit: coordinate, optic, and result nouns
  are either exported public types or intentionally opaque chain-return values.
• docs/BEARING.md tracks slices 133 through 152 until the PRD, tests, docs,
  and release gate evidence are complete.

Release Rule

v18.0.0 is blocked until this card and
API_no-full-materialization-first-use-optics are complete. The release is also
blocked by PERF_bounded-memory-large-graph-product-gate. Tagging and registry
publish work must wait behind all three gates.

[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. This does not close Optics public API closeout by itself; it removes the dishonest first-use materialization path before bounded-memory gate work continues.

[flyingrobots]

Completed as the V18-GP1 public Optics closeout goalpost.

This closure proves the public openWarpWorldline(...).prepareOpticBasis() -> coordinate() -> coordinate.optic() node/property read path and first-use honesty. It does not close the broader bounded-memory public-path product gate; #549 remains open for normal public reads, writes, content lookup, and sync under an explicit memory budget.

Deterministic evidence:

• Repro command run on 2026-06-06: npx vitest run test/conformance/v18FirstUseOpticsHonesty.test.ts test/conformance/v18CoordinateOpticPublicPath.test.ts test/conformance/v17CheckpointTailOpticReadBasis.test.ts test/unit/scripts/public-api-cost-inventory.test.ts test/unit/scripts/v18-worldline-api-doc-guard.test.ts test/unit/scripts/v18-package-surface-audit.test.ts test/unit/scripts/release-policy-shape.test.ts
• Result: 7 test files passed, 51 tests passed.
• test/conformance/v18FirstUseOpticsHonesty.test.ts proves prepareOpticBasis() verifies an existing checkpoint-tail basis without full-residency operations, write operations, full tree-map reads, materialization helpers, snapshot cloning, or observer setup.
• test/conformance/v18CoordinateOpticPublicPath.test.ts proves public coordinate node/property read success, tail folding, stable coordinate reads while live worldline advances, absence results, blank target behavior, missing checkpoint failure, and prepared-basis requirement.
• test/conformance/v17CheckpointTailOpticReadBasis.test.ts proves lower-level missing basis, tail budget, missing shard, and invalid shard failures fail closed without materialization.
• test/unit/scripts/public-api-cost-inventory.test.ts, test/unit/scripts/v18-worldline-api-doc-guard.test.ts, and test/unit/scripts/v18-package-surface-audit.test.ts prove docs, cost labels, and package surface stay aligned with the public coordinate Optics story.
• npm run typecheck:consumer passed, proving the public chain typechecks from package exports.
• Docs reconciliation is included in PR Reconcile V18 closeout docs #645.

No v18 release tag was created.