release: prepare v19.0.0

Author: flyingrobots

ARCHITECTURE.md

@@ -10,10 +10,10 @@ If you are learning the product for the first time, start with:
 
 ## Release posture
 
-`v18.2.1` is the current published release. Mainline development is preparing
-the v19 application boundary: callers open an opaque storage handle, write
-intents, read timelines, and keep receipts. Git history and git-cas remain
-separate infrastructure concerns composed behind that handle.
+`v19.0.0` is the current release. Applications open a `Runtime`, address
+causal `Lane`s, write validated `Intent`s, consume bounded `Observation`
+streams of `Reading`s, and keep `Receipt`s. Git history and git-cas remain
+separate infrastructure concerns composed behind the Runtime.
 
 The longer release notes live in [CHANGELOG.md](CHANGELOG.md). The runtime
 architecture below describes current implementation boundaries, not aspirational
@@ -23,18 +23,19 @@ roadmap state.
 
 ```text
 ┌──────────────────────────────────────────────────┐
-│ openWarp() -> Warp -> Timeline                    │
-│ intent · reading · tick · receipt                 │
+│ Runtime.open() -> Runtime -> Lane                │
+│ Intent · Observer · Observation                  │
+│ Reading · Receipt                                │
 ├──────────────────────────────────────────────────┤
-│ Opaque storage composition                        │
-│ GitStorage.open()                                  │
+│ Runtime-owned storage composition                │
+│ GitStorage.open() behind the Runtime boundary    │
 ├──────────┬───────────┬────────────┬──────────────┤
 │  Query   │  Patch    │ Materialize│    Sync      │
 │Controller│Controller │ Controller │  Controller  │
 │  Strand  │Checkpoint │ Provenance │ Comparison   │
 ├──────────┴───────────┴────────────┴──────────────┤
-│ Domain services and semantic storage ports        │
-│ CorePersistence · RuntimeStorageProviderPort      │
+│ Domain services and semantic storage ports       │
+│ CorePersistence · RuntimeStorageProviderPort     │
 ├───────────────────────┬──────────────────────────┤
 │ GitTimelineHistory    │ GitCasRepositoryAdapter  │
 │ Adapter               │ content/cache/retention  │
@@ -59,9 +60,9 @@ The system decomposes into three moments:
 - **Folding** — re-expresses admitted history (checkpoints, materialization)
 - **Revelation** — exposes truth under bounded rights (queries, observers)
 
-`openWarp()` gives application code a `Warp` handle. `warp.timeline(name)`
-opens one named admitted causal lane without exposing the internal worldline,
-graph, persistence, or CAS vocabulary.
+`Runtime.open()` gives application code a `Runtime` handle.
+`runtime.lane(name)` opens one named admitted causal lane without exposing the
+internal worldline, graph, persistence, or CAS vocabulary.
 
 ### Graph-shaped readings
 
@@ -153,17 +154,17 @@ services.
 9 controllers, one per capability namespace. Each accepts a typed
 dependency bag and owns the orchestration for its domain:
 
-| Controller | Capability | Key responsibility |
-|-----------|------------|-------------------|
-| QueryController | query | Node/edge reads, observers, worldlines |
-| PatchController | patches | Patch creation, commit, deterministic fold |
-| MaterializeController | materialize | Full and incremental materialization |
-| SyncController | sync | Frontier, sync, serve |
-| StrandController | strands | Strand lifecycle, braid, collapse |
-| CheckpointController | checkpoint | Checkpoint create/restore |
-| ProvenanceController | provenance | Provenance index, BTR access |
-| ComparisonController | comparison | Coordinate comparison, transfer planning |
-| SubscriptionController | subscriptions | Reactive state change notification |
+| Controller             | Capability    | Key responsibility                         |
+| ---------------------- | ------------- | ------------------------------------------ |
+| QueryController        | query         | Node/edge reads, observers, worldlines     |
+| PatchController        | patches       | Patch creation, commit, deterministic fold |
+| MaterializeController  | materialize   | Full and incremental materialization       |
+| SyncController         | sync          | Frontier, sync, serve                      |
+| StrandController       | strands       | Strand lifecycle, braid, collapse          |
+| CheckpointController   | checkpoint    | Checkpoint create/restore                  |
+| ProvenanceController   | provenance    | Provenance index, BTR access               |
+| ComparisonController   | comparison    | Coordinate comparison, transfer planning   |
+| SubscriptionController | subscriptions | Reactive state change notification         |
 
 ### Streams and bounded storage ports
 
@@ -175,11 +176,11 @@ arrays, cursors, or generated records into `WarpStream` at the boundary.
 The stream layer keeps large reads from pretending to be ordinary in-memory
 arrays. Current advanced ports that use this boundary include:
 
-| Port | Streamed surface | Role |
-| --- | --- | --- |
-| `CommitPort` | `logNodesStream(...)` | Git commit-log chunks without loading the full log |
-| `PatchJournalPort` | `scanPatchRange(...)` | Patch journal entries over a writer/range |
-| `IndexStorePort` | `writeShards(...)`, `scanShards(...)` | Bitmap/index shards as bounded stream units |
+| Port               | Streamed surface                      | Role                                               |
+| ------------------ | ------------------------------------- | -------------------------------------------------- |
+| `CommitPort`       | `logNodesStream(...)`                 | Git commit-log chunks without loading the full log |
+| `PatchJournalPort` | `scanPatchRange(...)`                 | Patch journal entries over a writer/range          |
+| `IndexStorePort`   | `writeShards(...)`, `scanShards(...)` | Bitmap/index shards as bounded stream units        |
 
 `CheckpointStorePort` is the checkpoint storage boundary. It does not expose a
 general stream API today, but it sits beside the streamed stores because it

CHANGELOG.md

@@ -7,19 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Added
+## [19.0.0] - 2026-07-27
+
+### Release notes
 
-- Added root `intent` builders, the runtime-backed `Intent` noun,
-  `Timeline.write(intent)`, and `WriteReceipt` results with the public
+`v19.0.0` replaces the graph-first v18 application surface with one
+intent-and-observer runtime boundary. Applications open `Runtime`, address
+causal `Lane`s, write validated `Intent`s, consume bounded `Observation`
+streams of `Reading`s, and retain `Receipt`s. Formal coordinates and optics,
+receipt inspection, charts, and test harnesses live on explicit package
+subpaths rather than widening the root.
+
+This is an intentional breaking release. A repository with retained v18 state
+must be migrated once, while all writers are stopped, with the packaged
+`git-warp-v18-to-v19` command. The migration rehearses in a disposable
+repository before a compare-and-swap promotion and preserves additive recovery
+refs. No v18 compatibility runtime remains in the product code.
+
+The exact merged-main Node 22/Linux release gate measured a representative
+16-property scan over the authentic approximately 2 MiB migrated-v18 fixture at
+31.1% lower cold wall time, 32.1% lower warm wall time, 20.1–21.3% lower
+operation CPU, and 46.6% fewer Git commands than published v18.2.1. The
+one-shot migration cost is measured and reported separately from steady-state
+reads.
+
+### Added
+
+- Added the root `Runtime` value plus type-only contracts for `Lane`, `Intent`,
+  `Observer`, `Observation`, `Reading`, `Evidence`, `Tick`, settlement, and
+  `Receipt`.
+- Added Wesley-generated domain `Intent` and `Observer` builders,
+  `Lane.write(intent)`, and `WriteReceipt` results with the public
   `AdmissionOutcome` axis: `derived`, `plural`, `conflict`, and `obstruction`.
   Each variant carries its required typed witness and reports admission rather
   than completed settlement.
-- Added root `reading` builders, the runtime-backed `Reading` noun,
-  `Timeline.read(reading)`, and receipt-bearing `ReadingResult` values for
-  first-use property and node-existence reads.
-- Added `Timeline.draft(name)`, draft writes, `Timeline.previewJoin(draft)`,
-  and `Timeline.join(draft)` with join receipts for first-use speculative
-  workflows.
+- Added synchronous `Lane.observe(observer)` construction, lazy single-execution
+  `Observation` streams, strict bounded convenience consumers, and completed
+  `ObservationReceipt`s.
+- Added persisted `Runtime.fork()` and `Runtime.strand()` lanes plus immutable,
+  revalidated `Runtime.previewSettlement()` plans and `Runtime.settle()`
+  receipts for speculative workflows.
 - Added idempotent `GitStorage.close()` and async-disposal support to release
   local Git and git-cas processes without changing history or retention.
 - Added the one-shot `git-warp-v18-to-v19` retained-substrate migrator. It
@@ -35,14 +62,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Added the v19 `openWarp()` product opener. `Warp` and `Timeline` are returned
-  as runtime handles and exported from the root as companion types.
-- Moved supported storage, formal WARP, and operator inspection exports out of
-  the package root into the explicit `storage`, `advanced`, and `diagnostics`
-  subpaths. The package root now rejects graph-first compatibility nouns
-  through the v19 public API boundary audit.
+- Made `Runtime.open()` the sole production composition root and `Lane` the
+  public causal-history handle, replacing `openWarp()`, `Warp`, and `Timeline`
+  application vocabulary.
+- Kept storage composition behind `Runtime`, moved formal WARP and operator
+  inspection exports to the explicit `advanced` and `diagnostics` subpaths,
+  and locked npm and JSR publication to the same root, charts, diagnostics,
+  advanced, and testing contract. The package root rejects graph-first
+  compatibility nouns through the v19 public API boundary audit.
 - Moved formal coordinate capture to advanced `captureCoordinate()` so the root
-  `Timeline` exposes opaque ticks but no coordinate machinery.
+  contracts expose opaque tick and coordinate-reference types but no coordinate
+  machinery.
 - Bound ticks to the exact timeline runtime that created them and made bounded
   traversal reuse one request-scoped checkpoint basis and tail support index.
 - Locked the package root to the v19 facade allowlist so support ports,
@@ -61,7 +91,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Raised the coverage ratchet from `92.10%` to `92.62%` after adding targeted
   coverage for bounded query node paging and memory-budget rejection paths and
   removing retired compatibility surfaces.
-- Upgraded `@git-stunts/git-cas` to `^6.5.3` so Git-backed materializations can
+- Upgraded `@git-stunts/git-cas` to `^6.5.5` so Git-backed materializations can
   use managed `CacheSet` retention, opaque page and bundle handles, and
   persistent Git object sessions.
 - Replaced the raw-Git grep check with a TypeScript AST gate that keeps
@@ -151,6 +181,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Prepared each Observation's timeline basis once, reused one coordinate optic
+  across its readings, and cached the immutable checkpoint basis for captured
+  coordinates. Live optics remain uncached so they continue to observe current
+  history.
 - Reused repository-scoped Git object sessions across immutable history and
   CAS operations, then closed history, materialization, and CAS owners at
   application, CLI, migration, and test boundaries. This removes repeated

README.md

@@ -45,11 +45,17 @@ It lets you:
 
 ## Latest release
 
-`v18.2.1` corrects the WARP-owned state-cache materialization path introduced
-in `v18.2.0`. Live materialization now uses current writer-frontier coordinates
-for exact and compatible predecessor snapshot reuse, publishes replay results
-under their real coordinate, and keeps diff-producing or receipt-producing reads
-replay-backed so callers receive complete diff and provenance data.
+`v19.0.0` replaces the graph-first application API with one public runtime
+boundary: open `Runtime`, address causal `Lane`s, write validated `Intent`s,
+consume bounded `Observation` streams of `Reading`s, and retain `Receipt`s.
+Existing repositories with retained v18 state require the packaged one-shot
+migration below before any v19 process opens them.
+
+The exact merged-main release gate's representative migrated-v18 retained scan
+was 31.1% faster cold, 32.1% faster warm, used 20.1–21.3% less operation CPU,
+and issued 46.6% fewer Git commands than published v18.2.1. These measurements
+cover the bounded 16-property fixture workload; they are not a universal
+workload claim.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full in-repository release notes.
 
@@ -96,9 +102,7 @@ if (write.outcome.kind === 'conflict' || write.outcome.kind === 'obstruction') {
   throw new Error(write.reason ?? `write admission was ${write.outcome.kind}`);
 }
 
-const observation = events.observe(
-  users.observers.roleOf({ subject: 'user:alice' })
-);
+const observation = events.observe(users.observers.roleOf({ subject: 'user:alice' }));
 
 for await (const reading of observation) {
   console.log(reading.value);
@@ -452,7 +456,13 @@ Check [CHANGELOG.md](CHANGELOG.md), the topic docs, and the package registry for
 
 ### What about performance and scale?
 
-Strong for offline/moderate causal workloads thanks to bounded support and holographic slices. Not for high-frequency real-time (use **[Echo](https://github.com/flyingrobots/echo)**).
+The exact merged-main v19 release gate measured its representative migrated-v18
+retained scan at 31.1–32.1% lower wall time, 20.1–21.3% lower operation CPU,
+and 46.6% fewer Git commands than v18.2.1. A separate 256 MiB logical Observer
+stream completes under a 64 MiB old-space cap. These are bounded workload
+contracts, not a claim that every repository or query has the same speedup. For
+high-frequency real-time execution, use
+**[Echo](https://github.com/flyingrobots/echo)**.
 
 ### How does it relate to Echo and Continuum?
 

docs/topics/README.md

@@ -5,17 +5,16 @@ specific task.
 
 ## Current release
 
-`v18.2.1` keeps the public docs focused around the shipped v18 read model and
-corrects the WARP state-cache materialization topic: live materialization can
-reuse coordinate-addressed snapshots, while diff and receipt reads remain
-replay-backed. Operator workflows live outside the topic shelf in
-[Operations](../operations/). The full release narrative lives in the root
-[CHANGELOG](../../CHANGELOG.md).
+`v19.0.0` ships the Runtime, Lane, Intent, Observer, Observation, Reading, and
+Receipt application vocabulary, bounded retained reads, and the one-shot
+v18-to-v19 substrate migration. Operator workflows live outside the topic
+shelf in [Operations](../operations/). The full breaking-change, migration,
+and performance narrative lives in the root [CHANGELOG](../../CHANGELOG.md).
 
 ## Start here
 
-- [Getting started](getting-started.md): install the package, open a worldline,
-  write a patch, read it back, and sync WARP refs.
+- [Getting started](getting-started.md): install the package, open a Runtime and
+  Lane, write an Intent, observe a bounded value, and keep its Receipt.
 - [v19 public vocabulary checkpoint](api/): follow the accepted Runtime, Lane,
   Intent, Observer, Observation, Reading, and Receipt contract.
 - [Generated v19 public vocabulary](vocabulary.generated.md): use the canonical

jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "18.2.1",
+  "version": "19.0.0",
   "imports": {
     "roaring": "npm:roaring@^2.7.0"
   },

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "18.2.1",
+  "version": "19.0.0",
   "description": "Git-native causal history runtime for intent writes, timeline reads, and receipts.",
   "type": "module",
   "license": "Apache-2.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/warp-adapters",
-  "version": "18.2.1",
+  "version": "19.0.0",
   "description": "Infrastructure adapters: Git/CAS, crypto, and HTTP for git-warp.",
   "private": true,
   "type": "module",

packages/warp-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/warp-kernel",
-  "version": "18.2.1",
+  "version": "19.0.0",
   "description": "Domain engine: services, WarpState, and controllers for git-warp.",
   "private": true,
   "type": "module",

packages/warp-kernel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/warp-orset",
-  "version": "18.2.1",
+  "version": "19.0.0",
   "description": "ORSet engine: trie, cursor, cache, and session primitives for git-warp.",
   "private": true,
   "type": "module",