Goalpost: v19 Runtime, Lane, and Observation public API

[flyingrobots]

Goal

Implement the accepted v19 public programming model:

Write intents. Observe lanes. Keep receipts.

The normative design is docs/topics/api/README.md.

Why This Goalpost Reopened

The original closure evidence correctly proved the first v19 Timeline/Reading facade at commit 059dbf478d1f42b810f3c43ee486e20af36eaf3b. That facade has since been superseded by the accepted Runtime/Lane/Observer/Observation vocabulary checkpoint.

The old evidence remains valid historical evidence. It is not evidence that the revised release contract is implemented.

Canonical Surface

Root runtime values:

Runtime

Core grammar:

An Observer runs against a Lane, producing an Observation
that emits Readings and leaves a Receipt.

Operation outcomes:

derived
plural
conflict
obstruction

Epistemic support remains a separate algebra.

Supported expert surfaces:

@git-stunts/git-warp/charts
@git-stunts/git-warp/diagnostics
@git-stunts/git-warp/advanced
@git-stunts/git-warp/testing

There is no public /graph, /browser, or /legacy surface.

Acceptance

• Root runtime values contain exactly Runtime.
• Runtime.open() owns production composition; close() releases local resources only.
• Lane replaces Timeline; worldline and strand kinds are mutually exclusive runtime truths.
• Wesley-generated *.intents and *.observers return validated domain objects.
• Lane.observe(observer) synchronously constructs one dormant Observation.
• Iterator demand, convenience consumption, and awaiting receipt share exactly one execution.
• Receipt-only consumption drains with backpressure and does not materialize Reading streams.
• Reading.value is canonical across TypeScript, CLI JSON, MCP, fixtures, and envelopes.
• Operational outcomes and epistemic support cannot alias.
• previewSettlement() returns inspectable presentation containing an immutable SettlementPlan.
• settle() accepts only a validated plan and revalidates current frontiers.
• Graph-shaped derived views ship only through /charts.
• CLI and MCP surfaces use the same vocabulary and Receipt renderer.
• Vocabulary conformance tests reject legacy nouns outside migration, substrate, and formal exceptions.
• README, migration docs, generated reference, CLI help, MCP descriptions, and consumer fixtures agree with runtime behavior.

Non-Goals

This goalpost does not promise WARP DRIVE, WARP-TTD, offline bundles, common-basis braid validation, or a legacy graph compatibility package. Those surfaces remain unadvertised until separately implemented and evidenced.

[coderabbitai]

🔗 Related PRs

#574 - Gate 1: enforce first-use optics honesty [merged]
#726 - Move graph exports behind v19 public API boundary [merged]
#729 - Add v19 timeline intents, readings, and drafts [merged]
#733 - Enforce the v19 public API contract [merged]
#745 - Seal Git substrate out of v19 receipts and evidence [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[flyingrobots]

Implementation Slice Map

Recommended execution order:

1. v19: audit and enforce root export boundary #721 - Audit and enforce root export boundary.
2. v19: move storage and substrate compatibility to explicit subpaths #720 - Move storage and substrate compatibility to explicit subpaths.
3. v19: introduce openWarp and Timeline facade #722 - Introduce openWarp and Timeline facade.
4. v19: add intent builders and receipt-returning writes #713 - Add intent builders and receipt-returning writes.
5. v19: add reading builders and receipt-bearing read results #723 - Add reading builders and receipt-bearing read results.
6. v19: add draft timeline previewJoin and join API #714 - Add draft timeline previewJoin() and join() API.
7. v19: add public API consumer and boundary tests #725 - Add public API consumer and boundary tests.
8. v19: update README reference docs and migration examples #724 - Update README, reference docs, and migration examples.

Execution rule: each slice should land with RED/GREEN coverage where behavior changes, and root-export boundary tests should prevent graph-shaped symbols from returning to root.

Planning docs are prepared on branch continuum-observer-runtime-facade in commit 64a0bf8f:

• docs/topics/api/README.md
• docs/migrations/v19/README.md

Core invariant:

Write intents. Read timelines. Keep receipts.

[flyingrobots]

Closure evidence

PR #733 merged as 059dbf478d1f42b810f3c43ee486e20af36eaf3b and satisfies the goalpost acceptance contract:

• Root runtime values are exactly openWarp, intent, and reading; supported companion nouns are type exports. [cite: index.ts#13-58@059dbf478d1f42b810f3c43ee486e20af36eaf3b]
• The AST-backed contract rejects star/namespace leakage, locks root and expert surfaces, and limits package/JSR exports to root, storage, advanced, and diagnostics; deleted browser and legacy entry points are absent. [cite: test/unit/scripts/v19-public-api-boundary.test.ts#194-262@059dbf478d1f42b810f3c43ee486e20af36eaf3b]
• The README first-use path imports only the three root values and obtains storage from the storage subpath, then writes intents and reads receipt-bearing results. [cite: README.md#55-105@059dbf478d1f42b810f3c43ee486e20af36eaf3b]
• ReadingResult carries both value and a validated ReadReceipt. [cite: src/domain/api/ReadingResult.ts#10-31@059dbf478d1f42b810f3c43ee486e20af36eaf3b]
• Receipt outcomes are exactly accepted, obstructed, conflicted, underdetermined, and rejected; write remains a separate operation axis with runtime settlement validation. [cite: src/domain/api/ReceiptOutcome.ts#1-18@059dbf478d1f42b810f3c43ee486e20af36eaf3b] [cite: src/domain/api/WriteReceipt.ts#14-49@059dbf478d1f42b810f3c43ee486e20af36eaf3b] [cite: src/domain/api/WriteReceipt.ts#67-88@059dbf478d1f42b810f3c43ee486e20af36eaf3b]
• The migration map records removed, renamed, and moved graph/worldline/patch/optic symbols, including advanced coordinate capture and deleted compatibility nouns. [cite: docs/migrations/v19/README.md#232-268@059dbf478d1f42b810f3c43ee486e20af36eaf3b]

All 17 final-head checks passed, CodeRabbit approved, and the final thread audit reported 14/14 resolved.