feat: add working-set overlay writes

Author: flyingrobots

ARCHITECTURE.md

@@ -50,7 +50,7 @@ git-warp now also includes a separate **working-set** substrate family. It is in
 The v1 model is deliberately narrow:
 
 - a working set pins an explicit frontier snapshot plus an optional Lamport ceiling
-- the overlay identity exists, but remains empty in v1
+- overlay writes live in a separate working-set patch-log ref
 - materialized state is derived/cache only
 - no Git worktree assumption leaks into the API
 
@@ -159,7 +159,7 @@ src/
 |   |   +-- BitmapNeighborProvider.js   # Bitmap-backed neighbor provider
 |   |   +-- HealthCheckService.js    # K8s-style probes
 |   |   +-- GitLogParser.js          # Binary stream parsing
-|   |   +-- WorkingSetService.js     # Pinned coordinate descriptors
+|   |   +-- WorkingSetService.js     # Pinned coordinates + working-set overlays
 |   +-- errors/             # Domain-specific errors
 |   |   +-- IndexError.js
 |   |   +-- ShardLoadError.js

CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [14.6.0] — 2026-03-16
+
+### Added
+
+- **Working-set overlay write API** — Added `WarpGraph.createWorkingSetPatch()` and `WarpGraph.patchWorkingSet()` so a pinned working set can diverge through its own overlay patch-log while reusing the standard patch builder and mutation kernel.
+
+### Changed
+
+- **Working-set materialization now replays base plus overlay** — `materializeWorkingSet()` now reduces the pinned base observation together with the current overlay patch-log, and `getWorkingSet()` / `listWorkingSets()` reconcile overlay metadata from the overlay ref so callers see the current head and patch count.
+- **Working-set documentation now reflects real overlay behavior** — Updated `README.md`, `ARCHITECTURE.md`, `docs/WORKING_SETS.md`, `docs/GUIDE.md`, `docs/TTD.md`, and `docs/CLI_GUIDE.md` so the docs describe overlay patch logs, the library-first write API, and the CLI boundary accurately instead of talking about permanently empty overlays.
+
+### Fixed
+
+- **Dropping a working set now removes its overlay ref too** — `dropWorkingSet()` now cleans up both the descriptor ref and the overlay patch-log ref, preventing orphaned overlay heads from remaining reachable after a working set is deleted.
+
 ## [14.5.0] — 2026-03-16
 
 ### Added

README.md

@@ -11,12 +11,12 @@
   <img src="docs/images/hero.gif" alt="git-warp CLI demo" width="600">
 </p>
 
-## What's New in v14.5.0
+## What's New in v14.6.0
 
-- **Working-set foundation is now part of the substrate** — `WarpGraph` now exposes explicit coordinate materialization plus durable working-set descriptors through `materializeCoordinate()`, `createWorkingSet()`, `getWorkingSet()`, `listWorkingSets()`, `dropWorkingSet()`, and `materializeWorkingSet()`. Working sets pin a frontier plus optional Lamport ceiling without assuming a Git worktree or making cached materializations authoritative.
-- **The main CLI now has a top-level `working-set` family** — `git warp working-set create|list|show|materialize|drop` manages pinned working-set descriptors directly from the main package, with no extra package to version or keep in sync.
-- **TTD stays read-only and architecture stays hex-clean** — the debugger remains a thin inspection family (`debug ...` + `seek`), while durable coordinate management lives beside it as a separate substrate family. This keeps “debug” from becoming a side-effecting mutation channel.
-- **Working-set docs are now first-class** — [docs/WORKING_SETS.md](docs/WORKING_SETS.md), [ARCHITECTURE.md](ARCHITECTURE.md), [docs/GUIDE.md](docs/GUIDE.md), and [docs/CLI_GUIDE.md](docs/CLI_GUIDE.md) now document the pinned-coordinate model, the non-authoritative cache boundary, and the CLI/API contract together.
+- **Working sets can now diverge through overlay patch logs** — `WarpGraph` now exposes `createWorkingSetPatch()` and `patchWorkingSet()` so a working set can continue from its pinned base observation through a separate overlay ref, while live writer refs stay untouched.
+- **Working-set materialization now replays base plus overlay** — `materializeWorkingSet()` and `getWorkingSet()` now reflect the current overlay patch-log head and replay the full working-set view instead of treating overlays as empty identity only.
+- **The working-set architecture stays hex-clean** — overlay writes reuse the existing patch builder and mutation kernel rather than introducing a second ad hoc working-set mutation engine.
+- **Docs now describe the real substrate boundary** — [docs/WORKING_SETS.md](docs/WORKING_SETS.md), [ARCHITECTURE.md](ARCHITECTURE.md), [docs/GUIDE.md](docs/GUIDE.md), and [docs/CLI_GUIDE.md](docs/CLI_GUIDE.md) now explain the split between descriptor lifecycle in the CLI and overlay writes in the library API.
 
 See the [full changelog](CHANGELOG.md) for complete release details.
 
@@ -72,7 +72,7 @@ If you are new to git-warp, start with the **[Guide](docs/GUIDE.md)**. For deepe
 - **[Architecture](ARCHITECTURE.md)**: Deep dive into the hexagonal "Ports and Adapters" design.
 - **[CLI Guide](docs/CLI_GUIDE.md)**: Command-by-command reference with examples, flags, and output formats.
 - **[Time Travel Debugger](docs/TTD.md)**: Architecture and scope of the thin debugger CLI surface.
-- **[Working Sets](docs/WORKING_SETS.md)**: Pinned observation coordinates, empty-overlay v1 semantics, and the working-set API/CLI surface.
+- **[Working Sets](docs/WORKING_SETS.md)**: Pinned observation coordinates, overlay patch-log semantics, and the working-set API/CLI surface.
 - **[Protocol Specs](docs/specs/)**: Binary formats for Audit Receipts, Content Attachments, and BTRs.
 - **[ADR Registry](adr/)**: Architectural Decision Records (e.g., edge-property internal canonicalization).
 - **[Cookbook](examples/)**: Functional examples of Event Sourcing, Pathfinding, and Multi-Writer setups.

docs/CLI_GUIDE.md

@@ -707,7 +707,7 @@ The `working-set` family creates and manages durable descriptors for explicit ob
 - the current frontier snapshot
 - an optional Lamport ceiling
 - optional owner/scope/lease metadata
-- an empty overlay identity for future evolution
+- an overlay identity and patch-log ref for future divergent writes
 
 This is **not** part of the read-only Time Travel Debugger family. `working-set` creates durable descriptor refs, while TTD only inspects substrate facts.
 
@@ -752,19 +752,19 @@ git warp working-set show --repo ./team-repo review-auth
 git warp working-set show --repo ./team-repo review-auth --json
 ```
 
-Use this to inspect the pinned frontier, Lamport ceiling, metadata, and overlay identity without materializing state.
+Use this to inspect the pinned frontier, Lamport ceiling, metadata, and current overlay patch-log head without materializing state.
 
 ### `working-set materialize <id>` — Replay the pinned coordinate
 
 ```bash
-# Materialize the pinned base observation
+# Materialize the pinned coordinate
 git warp working-set materialize --repo ./team-repo review-auth
 
 # Include reducer receipts
 git warp working-set materialize --repo ./team-repo review-auth --receipts --json
 ```
 
-This always replays the pinned coordinate, even if the live frontier has advanced since the descriptor was created.
+This always replays the pinned coordinate plus any overlay patches already committed through the library API, even if the live frontier has advanced since the descriptor was created.
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
@@ -778,6 +778,22 @@ git warp working-set drop --repo ./team-repo review-auth
 
 This removes the descriptor ref. It does not mutate patch history.
 
+### Overlay writes stay in the library API
+
+The CLI deliberately does **not** grow a second patch DSL for working-set overlay writes.
+
+```javascript
+const builder = await graph.createWorkingSetPatch('review-auth');
+builder.setProperty('task:oauth', 'status', 'needs-review');
+await builder.commit();
+
+await graph.patchWorkingSet('review-auth', (p) => {
+  p.setProperty('task:oauth', 'owner', 'alice');
+});
+```
+
+That keeps the CLI thin and keeps overlay writes on the same mutation kernel as normal graph patches.
+
 ### Complete flag reference for `working-set`
 
 | Subcommand | Flags |

docs/GUIDE.md

@@ -1171,13 +1171,13 @@ git warp seek --no-persistent-cache --tick 5
 
 ### Working Sets
 
-Working sets pin an explicit observation coordinate for later reuse without creating a Git worktree. In v1, a working set records:
+Working sets pin an explicit observation coordinate for later reuse without creating a Git worktree. A working set records:
 
 - the graph name
 - a pinned frontier snapshot
 - an optional Lamport ceiling
 - optional owner/scope/lease metadata
-- an empty overlay identity for future evolution
+- an overlay identity and patch-log ref for future divergent writes
 
 Materialized state remains derived/cache only. The descriptor is the durable part.
 
@@ -1208,6 +1208,10 @@ const workingSet = await graph.createWorkingSet({
 });
 
 const state = await graph.materializeWorkingSet(workingSet.workingSetId);
+
+await graph.patchWorkingSet(workingSet.workingSetId, (p) => {
+  p.setProperty('task:oauth', 'status', 'needs-review');
+});
 ```
 
 Use [docs/WORKING_SETS.md](WORKING_SETS.md) for the dedicated working-set model and [docs/CLI_GUIDE.md](CLI_GUIDE.md) for the full CLI flags.

docs/TTD.md

@@ -166,5 +166,5 @@ Likely future TTD-adjacent extensions:
 - additional debug topics once their substrate facts are stable
 - entity-local slice inspection at historical coordinates once substrate support exists
 - richer provenance drilldown over conflict anchors
-- overlay-aware working-set/worldline coordinates once overlay writes exist
+- overlay-aware working-set/worldline debugger views over the new overlay patch-log substrate
 - higher-level debugger panels in XYPH, not in git-warp

docs/WORKING_SETS.md

@@ -1,6 +1,6 @@
 # Working Sets
 
-**Status:** v1 foundation active.
+**Status:** v1 substrate active.
 
 Working sets give git-warp a durable way to pin explicit observation coordinates without assuming a Git worktree, a browser UI, or higher-level XYPH semantics.
 
@@ -13,23 +13,23 @@ A working set is a durable descriptor that records:
 - pinned frontier snapshot
 - optional Lamport ceiling
 - optional owner/scope/lease metadata
-- overlay identity for future evolution
+- overlay identity plus a patch-log ref for divergent writes
 
-In v1, the overlay exists only as identity:
+A newly created working set still starts with an empty overlay:
 
 - `overlay.kind = patch-log`
 - `overlay.headPatchSha = null`
 - `overlay.patchCount = 0`
 
-That means a newly created working set reads exactly like its base observation.
+That means a newly created working set reads exactly like its base observation until an overlay patch is committed.
 
 ## Truth Boundary
 
 The authoritative pieces are:
 
 - the working-set descriptor
 - the pinned base observation coordinate
-- the future overlay identity
+- the overlay patch-log ref and its patch chain
 
 Materialized state is **derived only**:
 
@@ -67,6 +67,15 @@ const ws = await graph.createWorkingSet({
 const descriptor = await graph.getWorkingSet('review-auth');
 const all = await graph.listWorkingSets();
 const state = await graph.materializeWorkingSet('review-auth');
+
+await graph.patchWorkingSet('review-auth', (p) => {
+  p.setProperty('task:oauth', 'status', 'needs-review');
+});
+
+const builder = await graph.createWorkingSetPatch('review-auth');
+builder.setProperty('task:oauth', 'owner', 'alice');
+await builder.commit();
+
 await graph.dropWorkingSet('review-auth');
 ```
 
@@ -91,22 +100,23 @@ git warp working-set materialize review-auth --receipts
 git warp working-set drop review-auth
 ```
 
+The CLI manages descriptor lifecycle and replay. Overlay writes are available through the library API, not through a separate working-set patch DSL in the CLI.
+
 `working-set` is intentionally a top-level family rather than a `debug` subcommand because it creates durable descriptor refs.
 
 ## Relationship to TTD
 
 The Time Travel Debugger stays read-only:
 
 - `seek` and `debug ...` inspect substrate facts
-- `working-set ...` pins reusable coordinates
+- `working-set ...` manages durable coordinates and overlay patch logs
 
-That boundary keeps the debugger from turning into a mutation channel.
+That boundary keeps the debugger from turning into a mutation channel while still letting higher layers build real fork/worldline behavior on top of working sets.
 
 ## Deferred from v1
 
-Not part of this foundation slice:
+Deferred from this slice:
 
-- overlay writes
 - collapse/merge semantics
 - worldline governance
 - arbitrary higher-level meaning

index.d.ts

@@ -2055,8 +2055,8 @@ export default class WarpGraph {
    * Creates a durable working-set descriptor pinned to the current frontier
    * plus an optional Lamport ceiling.
    *
-   * Working sets do not duplicate the graph. In v1 they record a pinned base
-   * observation plus empty overlay identity for future divergent writes.
+   * Working sets do not duplicate the graph. They record a pinned base
+   * observation plus overlay identity for future divergent writes.
    */
   createWorkingSet(options?: WorkingSetCreateOptions): Promise<WorkingSetDescriptor>;
 
@@ -2071,13 +2071,16 @@ export default class WarpGraph {
 
   /**
    * Materializes a working set's pinned base observation plus overlay.
-   *
-   * In v1 the overlay remains empty, so this replays only the pinned base
-   * coordinate.
    */
   materializeWorkingSet(workingSetId: string, options: { receipts: true }): Promise<{ state: WarpStateV5; receipts: TickReceipt[] }>;
   materializeWorkingSet(workingSetId: string, options?: { receipts?: false }): Promise<WarpStateV5>;
 
+  /** Creates a patch builder that writes into a working set's overlay patch-log. */
+  createWorkingSetPatch(workingSetId: string): Promise<PatchBuilderV2>;
+
+  /** Convenience wrapper that creates and commits a working-set overlay patch. */
+  patchWorkingSet(workingSetId: string, build: (p: PatchBuilderV2) => void | Promise<void>): Promise<string>;
+
   /**
    * The provenance index mapping entities to contributing patches.
    * Available after materialize() has been called.

jsr.json

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