@oisin-ee/pi-dogsled 0.34.2 → 0.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,13 +13,13 @@ Install the binary on each Herdr host. Use the same release tag in each command.
13
13
  Binary:
14
14
 
15
15
  ```sh
16
- mise use github:oisin-ee/dogsled@v0.34.2 # x-release-please-version
16
+ mise use github:oisin-ee/dogsled@v0.35.0 # x-release-please-version
17
17
  ```
18
18
 
19
19
  Pi (extension, tools, the `todo` tool, and skill), from npm:
20
20
 
21
21
  ```sh
22
- pi install npm:@oisin-ee/pi-dogsled@0.34.2 # x-release-please-version
22
+ pi install npm:@oisin-ee/pi-dogsled@0.35.0 # x-release-please-version
23
23
  ```
24
24
 
25
25
  At session start the extension compares its version with `dogsled --version` and warns when they differ.
@@ -338,6 +338,22 @@ These reports do not change release decisions.
338
338
 
339
339
  See [Agent lifecycle and recovery](docs/lifecycle.md) for command limits, custody, origin release certificates, and migration.
340
340
 
341
+ ## Transfers
342
+
343
+ ```sh
344
+ dogsled transfer send worker --files notes.md
345
+ dogsled transfer send worker --changes --include-worktree
346
+ dogsled transfer list
347
+ dogsled transfer show TRANSFER_ID
348
+ dogsled transfer apply TRANSFER_ID --check
349
+ dogsled transfer apply TRANSFER_ID
350
+ dogsled transfer drop TRANSFER_ID
351
+ ```
352
+
353
+ A transfer stores files or changes for another agent and puts one notice in its inbox.
354
+ Nothing is applied until the recipient runs `apply`, which writes working files only.
355
+ See [Send files and changes to another agent](docs/transfer.md).
356
+
341
357
  ## Inbox
342
358
 
343
359
  Every message to an agent goes through one inbox on the agent's host: a child's final reply, a blocked report, an admitted ticket, a launch failure, and a message from another agent.
@@ -617,6 +633,12 @@ dogsled repo list --json
617
633
  ```
618
634
 
619
635
  The portal’s New picker searches repository names and descriptions, newest pushes first.
636
+ It receives catalogue updates through the existing portal stream, without another subscription or polling.
637
+ A successful hourly refresh clears the warning in the open picker without losing your draft or valid selection.
638
+ If the selected repository disappears, select a repository before sending. The picker never switches targets silently.
639
+ Portal snapshots use version 2; observation IPC remains version 1.
640
+ After a coordinated release rollout, restart `serve` and `web`, then reload existing portal tabs.
641
+ Older portal clients can report a decoding error until reloaded.
620
642
  `GET /api/repos` and `repo list --json` return `{repos, error}` from the published catalogue.
621
643
  Each repository contains `slug`, `description`, `pushed_at`, and `private`.
622
644
  Without a publication, readers report that the catalogue is unavailable.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oisin-ee/pi-dogsled",
3
- "version": "0.34.2",
3
+ "version": "0.35.0",
4
4
  "description": "Pi extension for dogsled: the board, the /dogsled panel, the inbox reader, and the dogsled tools. Needs the dogsled binary of the same version.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/pi/activity.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  // Session-scoped telemetry. Hooks reduce compact facts; only the publisher performs I/O.
2
2
  import { randomUUID } from "node:crypto";
3
+ import { existsSync } from "node:fs";
3
4
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
4
5
  import type { PortalClient } from "./portal-client.ts";
5
6
 
@@ -187,24 +188,45 @@ export class ActivityPublisher {
187
188
  private lastAttempt = -Infinity;
188
189
  private retryAt = -Infinity;
189
190
  private retryDelay = 500;
190
- private lastBackoff: string | undefined;
191
191
  private timer: ReturnType<typeof setTimeout> | undefined;
192
- private heartbeat: ReturnType<typeof setInterval>;
192
+ private heartbeat: ReturnType<typeof setInterval> | undefined;
193
193
  private controller: AbortController | undefined;
194
194
  private flight: Promise<void> | undefined;
195
195
  private readonly client: Client;
196
196
  private readonly pane: string;
197
197
  private readonly evidence: Evidence;
198
+ private readonly exists: (path: string) => boolean;
199
+ private readonly report: (message: string) => void;
198
200
 
199
- constructor(client: Client, pane: string, evidence: Evidence, idle: boolean) {
201
+ constructor(
202
+ client: Client,
203
+ pane: string,
204
+ evidence: Evidence,
205
+ idle: boolean,
206
+ report: (message: string) => void,
207
+ exists: (path: string) => boolean = existsSync,
208
+ ) {
200
209
  this.client = client;
201
210
  this.pane = pane;
202
211
  this.evidence = { ...evidence };
212
+ this.exists = exists;
213
+ this.report = report;
203
214
  this.path = `/api/agents/local/${encodeURIComponent(pane)}/activity`;
204
215
  this.reducer = new ActivityReducer(idle);
205
216
  this.pending = this.reducer.snapshot();
217
+ this.evidenceReady();
218
+ }
219
+
220
+ evidenceReady(): void {
221
+ if (
222
+ this.disposed ||
223
+ this.stopped ||
224
+ this.request ||
225
+ this.stamp ||
226
+ !this.exists(this.evidence.session_file)
227
+ )
228
+ return;
206
229
  this.request = this.registration(null, 0);
207
- this.diagnostic("POST", 0, "start", "bootstrap");
208
230
  this.heartbeat = setInterval(() => {
209
231
  if (this.disposed || this.stopped) return;
210
232
  this.pending = this.reducer.snapshot();
@@ -221,7 +243,14 @@ export class ActivityPublisher {
221
243
  }
222
244
 
223
245
  private schedule(): void {
224
- if (this.disposed || this.stopped || this.busy || this.timer) return;
246
+ if (
247
+ this.disposed ||
248
+ this.stopped ||
249
+ this.busy ||
250
+ this.timer ||
251
+ (!this.request && !this.stamp)
252
+ )
253
+ return;
225
254
  this.timer = setTimeout(
226
255
  () => {
227
256
  if (this.disposed) return;
@@ -314,7 +343,7 @@ export class ActivityPublisher {
314
343
  code === "sequence_conflict" ||
315
344
  (status === 404 && code !== "agent_missing")
316
345
  ) {
317
- this.stop(request.method, status, code);
346
+ this.stop(status, code);
318
347
  return;
319
348
  }
320
349
  // A 5xx may follow a committed mutation, even with a typed error body.
@@ -332,7 +361,7 @@ export class ActivityPublisher {
332
361
  code === "upstream_unavailable")
333
362
  )
334
363
  this.request = this.registration(null, 0);
335
- this.backoff(request.method, status, "retry", code);
364
+ this.backoff();
336
365
  return;
337
366
  }
338
367
  if (
@@ -347,10 +376,10 @@ export class ActivityPublisher {
347
376
  this.sequence = 0;
348
377
  this.pending = this.reducer.snapshot();
349
378
  this.request = { method: "GET", path: this.path };
350
- this.backoff(request.method, status, "discover", code);
379
+ this.backoff();
351
380
  return;
352
381
  }
353
- this.stop(request.method, status, code);
382
+ this.stop(status, code);
354
383
  return;
355
384
  }
356
385
  if (request.method === "GET") {
@@ -363,7 +392,7 @@ export class ActivityPublisher {
363
392
  !counter(body["producer"]["generation"]) ||
364
393
  (body["producer"]["id"] !== null && !text(body["producer"]["id"], 256))
365
394
  ) {
366
- this.stop(request.method, status);
395
+ this.stop(status);
367
396
  return;
368
397
  }
369
398
  const detail = body["detail"];
@@ -374,7 +403,7 @@ export class ActivityPublisher {
374
403
  if (body["producer"]["id"] !== null && !retired) {
375
404
  // Generation-0 probes renew sampling interest by design without claiming the live generation.
376
405
  this.request = this.registration(null, 0);
377
- this.backoff(request.method, status, "wait_owner");
406
+ this.backoff();
378
407
  return;
379
408
  }
380
409
  this.request = this.registration(body["epoch"], body["producer"]["generation"]);
@@ -392,10 +421,9 @@ export class ActivityPublisher {
392
421
  body.generation !== this.stamp.generation ||
393
422
  body.session !== this.stamp.session))
394
423
  ) {
395
- this.stop(request.method, status);
424
+ this.stop(status);
396
425
  return;
397
426
  }
398
- if (request.method === "POST") this.diagnostic("POST", status, "ack", "publishing");
399
427
  this.stamp = {
400
428
  epoch: body.epoch,
401
429
  generation: body.generation,
@@ -403,14 +431,13 @@ export class ActivityPublisher {
403
431
  session: body.session,
404
432
  };
405
433
  this.request = undefined;
406
- this.lastBackoff = undefined;
407
434
  this.retryDelay = 500;
408
435
  this.retryAt = -Infinity;
409
436
  }
410
437
  } catch {
411
438
  // Offline and ambiguous outcomes are telemetry gaps, never hook failures.
412
439
  if (this.disposed) return;
413
- this.backoff(request.method, 0, "retry_transport", "transport");
440
+ this.backoff();
414
441
  } finally {
415
442
  if (!this.disposed) {
416
443
  this.busy = false;
@@ -434,34 +461,22 @@ export class ActivityPublisher {
434
461
  };
435
462
  }
436
463
 
437
- private diagnostic(method: string, status: number, code: string, decision: string): void {
438
- // Match the extension's console reporting; never log response text or native evidence.
439
- console.error(
440
- `[dogsled activity] pane=${encodeURIComponent(this.pane).slice(0, 384)} method=${method} status=${status} code=${code} decision=${decision}`,
441
- );
442
- }
443
-
444
- private backoff(method: string, status: number, decision: string, code = "recovery"): void {
445
- const key = `${method}:${code}:${decision}`;
446
- if (this.lastBackoff !== key) {
447
- this.diagnostic(method, status, code, decision);
448
- this.lastBackoff = key;
449
- }
464
+ private backoff(): void {
450
465
  this.retryAt = performance.now() + this.retryDelay;
451
466
  this.retryDelay = Math.min(5000, this.retryDelay * 2);
452
467
  }
453
468
 
454
- private stop(method: string, status: number, code = "invalid_response"): void {
455
- this.diagnostic(method, status, code, "stop");
469
+ private stop(status: number, code = "invalid_response"): void {
470
+ if (this.stopped) return;
456
471
  this.stopped = true;
457
472
  clearInterval(this.heartbeat);
458
473
  if (this.timer) clearTimeout(this.timer);
474
+ this.report(`Dogsled live activity stopped: ${code} (HTTP ${status})`);
459
475
  }
460
476
 
461
477
  dispose(): void {
462
478
  if (this.disposed) return;
463
479
  this.disposed = true;
464
- this.diagnostic(this.request?.method ?? "PUT", 0, "dispose", "stop");
465
480
  clearInterval(this.heartbeat);
466
481
  if (this.timer) clearTimeout(this.timer);
467
482
  this.controller?.abort();
@@ -500,7 +515,19 @@ export function registerActivity(pi: ExtensionAPI, client: Client, pane: string
500
515
  const session_id = ctx.sessionManager.getSessionId();
501
516
  if (!session_file || !text(session_file, 4096) || !text(session_id, 1024) || !text(pane, 128))
502
517
  return;
503
- runtime = new ActivityPublisher(client, pane, { session_file, session_id }, ctx.isIdle());
518
+ runtime = new ActivityPublisher(
519
+ client,
520
+ pane,
521
+ { session_file, session_id },
522
+ ctx.isIdle(),
523
+ (message) => {
524
+ try {
525
+ ctx.ui.notify(message, "warning");
526
+ } catch {
527
+ /* A notification failure must not escape telemetry. */
528
+ }
529
+ },
530
+ );
504
531
  } catch {
505
532
  /* Missing native evidence leaves detail unavailable. */
506
533
  }
@@ -517,6 +544,13 @@ export function registerActivity(pi: ExtensionAPI, client: Client, pane: string
517
544
  });
518
545
  pi.on("agent_settled", () => {
519
546
  runtime?.event({ type: "settled" });
547
+ runtime?.evidenceReady();
548
+ });
549
+ pi.on("turn_end", () => {
550
+ runtime?.evidenceReady();
551
+ });
552
+ pi.on("message_start", () => {
553
+ runtime?.evidenceReady();
520
554
  });
521
555
  pi.on("message_update", (event) => {
522
556
  if (event.message.role !== "assistant") return;
@@ -540,6 +574,7 @@ export function registerActivity(pi: ExtensionAPI, client: Client, pane: string
540
574
  });
541
575
  pi.on("message_end", (event) => {
542
576
  if (event.message.role === "assistant") runtime?.event({ type: "message_end" });
577
+ runtime?.evidenceReady();
543
578
  });
544
579
  pi.on("tool_execution_start", (event) => {
545
580
  runtime?.event({
package/pi/observation.ts CHANGED
@@ -24,12 +24,19 @@ export type Spawn = (binary: string, args: string[]) => Watcher;
24
24
 
25
25
  const spawnWatcher: Spawn = (binary, args) => spawn(binary, args, { stdio: ["ignore", "pipe", "pipe"] });
26
26
 
27
+ /** A publication result, or the CLI's terminal JSON error from stdout. */
28
+ type Parsed = Observed & { terminal?: true };
29
+
27
30
  /** One line of `dogsled board --watch --json`. */
28
- export function parseFrame(line: string): Observed {
31
+ export function parseFrame(line: string): Parsed {
29
32
  let value: unknown;
30
33
  try { value = JSON.parse(line); } catch { return { error: "Dogsled observation sent an invalid frame" }; }
31
34
  if (!value || typeof value !== "object") return { error: "Dogsled observation sent an invalid frame" };
32
35
  const frame = value as Record<string, unknown>;
36
+ // main emits { error, deadline } on failure, outside the revisioned publication stream.
37
+ if (!("revision" in frame) && typeof frame["error"] === "string" && typeof frame["deadline"] === "boolean") {
38
+ return { error: clean(frame["error"]), terminal: true };
39
+ }
33
40
  if (typeof frame["revision"] !== "number") return { error: "Dogsled observation sent an invalid frame" };
34
41
  if (typeof frame["error"] === "string") return { error: clean(frame["error"]) };
35
42
  try {
@@ -72,12 +79,17 @@ export class Observation {
72
79
  }
73
80
  this.watcher = watcher;
74
81
  let stderr = "";
82
+ let terminalError: string | undefined;
75
83
  watcher.stderr?.setEncoding("utf8");
76
84
  watcher.stderr?.on("data", (chunk: string) => { stderr = (stderr + chunk).slice(-2_000); });
77
85
  const lines = createInterface({ input: watcher.stdout! });
78
86
  lines.on("line", line => {
79
87
  if (!current()) return;
80
88
  const observed = parseFrame(line);
89
+ if (observed.terminal) {
90
+ terminalError = observed.error;
91
+ return;
92
+ }
81
93
  // Revisions only move forward within one subscription.
82
94
  if (observed.frame) {
83
95
  if (observed.frame.revision <= this.revision) return;
@@ -93,7 +105,8 @@ export class Observation {
93
105
  if (!current()) return;
94
106
  this.watcher = undefined;
95
107
  this.revision = 0;
96
- this.listener({ error: `Dogsled observation unavailable: ${clean(detail)}` });
108
+ // Report the CLI cause once, after stdout has drained, rather than its generic exit code.
109
+ this.listener({ error: terminalError ?? `Dogsled observation unavailable: ${clean(detail)}` });
97
110
  };
98
111
  watcher.once("close", code => ended(stderr.trim() || `dogsled board exited with ${code ?? "a signal"}`));
99
112
  watcher.once("error", error => ended(String(error)));
package/pi/todo/README.md CHANGED
@@ -74,9 +74,23 @@ An active unit stays required for the sessions that implement code.
74
74
 
75
75
  ## State
76
76
 
77
- Each task change is saved as a `todo-state` entry on the session branch. A resumed session, a `/tree` move,
78
- and calls made from inside codemode all see the list of the current branch.
77
+ Task changes use `todo-delta` entries when they are smaller than a full `todo-state` snapshot.
78
+ Version 1 deltas contain changed roots or subtasks by unit ID, removed IDs, and order changes.
79
+ Each order change places one ID after another ID under a parent, or at the start when `after` is null.
80
+ A null parent identifies the root list. Changing one child does not copy its siblings.
81
+ Full snapshots replace the preceding list. Lists without stable IDs use full snapshots.
82
+ Before the first delta, the writer adds a `todo-state` fence with `format: "todo-delta/1"`.
83
+ The fence carries the current list. Every later full snapshot carries the same format key.
84
+ A plain snapshot after a fence fails with `INVALID_TODO_DELTA: unfenced snapshot after delta history`.
85
+ Each delta's changed tasks are validated on read. Cross-task rules are validated on the list each reader returns.
86
+
87
+ All readers replay the entries on the current branch. A resumed session, a `/tree` move,
88
+ and calls made from inside codemode see that branch's list.
89
+ Contract revisions and seals keep the identity of the entry that first introduced them.
90
+ A delta applies to the preceding list with those origins resolved, as each task mutation does.
79
91
  Old flat snapshots retain their recorded statuses and read with empty subtasks.
92
+ Older extensions refuse a session after its first delta. Use the updated extension to read or change that session.
93
+ Sessions without a fence remain readable by both versions.
80
94
 
81
95
  ## Widget
82
96
 
@@ -0,0 +1,223 @@
1
+ import { DELTA_ENTRY, STATE_ENTRY, indexed, leafTask } from "./delta.ts";
2
+ import type { Immutable, ListIndex, TodoDelta } from "./delta.ts";
3
+ import type { Subtask, TodoList } from "./wasm.ts";
4
+ import { deltaData, snapshotData } from "./delta-validation.ts";
5
+ import { History } from "./history.ts";
6
+ import { OrderIndex } from "./order-index.ts";
7
+ import { Provenance } from "./provenance.ts";
8
+ import { parse } from "./wasm.ts";
9
+
10
+ interface BranchEntry {
11
+ readonly type: string;
12
+ readonly customType?: string;
13
+ readonly data?: unknown;
14
+ readonly id?: string;
15
+ }
16
+ interface ListFrame {
17
+ readonly changed: readonly Immutable<Subtask>[];
18
+ readonly entry: BranchEntry;
19
+ readonly fenced: boolean;
20
+ readonly progress: boolean;
21
+ readonly list: TodoList;
22
+ readonly snapshot: TodoList;
23
+ }
24
+ interface TaskRecord {
25
+ readonly revision: number;
26
+ readonly task: Immutable<Subtask>;
27
+ }
28
+ interface ListVersion {
29
+ readonly hasBase: boolean;
30
+ readonly orders: Readonly<OrderIndex>;
31
+ readonly revision: number;
32
+ readonly size: number;
33
+ readonly tasks: Readonly<History<string, TaskRecord | undefined>>;
34
+ }
35
+ const step = 1,
36
+ empty = 0,
37
+ required = (
38
+ version: Readonly<ListVersion>,
39
+ unitId: string,
40
+ provenance: Readonly<Provenance>,
41
+ ): Immutable<Subtask> => {
42
+ const record = version.tasks.get(unitId, version.revision);
43
+ if (record === undefined) {
44
+ throw new Error("INVALID_TODO_DELTA: order names a missing task");
45
+ }
46
+ const task = structuredClone(record.task);
47
+ if (record.revision < version.revision && task.unit !== undefined) {
48
+ provenance.resolve(task.unit, "");
49
+ }
50
+ return task;
51
+ },
52
+ materialize = (version: Readonly<ListVersion>, provenance: Readonly<Provenance>): TodoList => {
53
+ if (!version.hasBase) {
54
+ throw new Error("INVALID_TODO_DELTA: no stable-ID base snapshot");
55
+ }
56
+ const list = parse({
57
+ tasks: version.orders.ids(null, version.revision).map((unitId) =>
58
+ Object.assign({}, required(version, unitId, provenance), {
59
+ subtasks: version.orders
60
+ .ids(unitId, version.revision)
61
+ .map((childId) => required(version, childId, provenance)),
62
+ }),
63
+ ),
64
+ });
65
+ if (
66
+ list.tasks.reduce((count, root) => count + step + (root.subtasks?.length ?? empty), empty) !==
67
+ version.size
68
+ ) {
69
+ throw new Error("INVALID_TODO_DELTA: tasks missing from order");
70
+ }
71
+ return list;
72
+ };
73
+
74
+ /** Owns one linear replay, retaining changed values rather than full-list copies. */
75
+ class BranchState {
76
+ readonly #provenance = new Provenance();
77
+ #tasks = new History<string, TaskRecord | undefined>();
78
+ #orders = new OrderIndex();
79
+ #known = new Set<string>();
80
+ #revision = empty;
81
+ #hasBase = false;
82
+ #fenced = false;
83
+ #latest: ListFrame | undefined = undefined;
84
+
85
+ #record(task: Immutable<Subtask>, entry: BranchEntry): void {
86
+ if (task.unit !== undefined) {
87
+ this.#provenance.resolve(structuredClone(task.unit), entry.id ?? "");
88
+ }
89
+ }
90
+
91
+ #index(index: Readonly<ListIndex>): void {
92
+ for (const [unitId, task] of index.tasks) {
93
+ this.#tasks.set(unitId, this.#revision, { revision: this.#revision, task });
94
+ }
95
+ for (const [parent, ids] of index.orders) {
96
+ let after: string | null = null;
97
+ for (const unitId of ids) {
98
+ this.#orders.apply({ after, id: unitId, parent }, this.#revision);
99
+ after = unitId;
100
+ }
101
+ }
102
+ }
103
+
104
+ #replace(index: Readonly<ListIndex> | undefined): void {
105
+ this.#hasBase = index !== undefined;
106
+ this.#known = new Set(index?.tasks.keys());
107
+ this.#tasks = new History();
108
+ this.#orders = new OrderIndex();
109
+ if (index !== undefined) {
110
+ this.#index(index);
111
+ }
112
+ }
113
+
114
+ #full(entry: BranchEntry, data: unknown): ListFrame {
115
+ const { fenced, list } = snapshotData(data);
116
+ if (this.#fenced && !fenced) {
117
+ throw new Error("INVALID_TODO_DELTA: unfenced snapshot after delta history");
118
+ }
119
+ const progress = JSON.stringify(this.#latest?.list ?? { tasks: [] }) !== JSON.stringify(list),
120
+ index = indexed(list),
121
+ changed = list.tasks.flatMap((root) => [leafTask(root), ...(root.subtasks ?? [])]),
122
+ provenance = this.#provenance;
123
+ this.#fenced ||= fenced;
124
+ this.#replace(index);
125
+ for (const task of changed) {
126
+ this.#record(task, entry);
127
+ }
128
+ return {
129
+ changed,
130
+ entry,
131
+ fenced: this.#fenced,
132
+ list,
133
+ progress,
134
+ get snapshot(): TodoList {
135
+ return provenance.list(list);
136
+ },
137
+ };
138
+ }
139
+
140
+ #changed(delta: TodoDelta, entry: BranchEntry): boolean {
141
+ let progress = false;
142
+ for (const change of delta.changed) {
143
+ progress ||=
144
+ JSON.stringify(this.#tasks.get(change.id, this.#revision)?.task) !==
145
+ JSON.stringify(change.task);
146
+ this.#known.add(change.id);
147
+ this.#tasks.set(change.id, this.#revision, { revision: this.#revision, task: change.task });
148
+ this.#record(change.task, entry);
149
+ }
150
+ return progress;
151
+ }
152
+
153
+ #removed(ids: readonly string[]): boolean {
154
+ let progress = false;
155
+ for (const unitId of ids) {
156
+ progress = this.#known.delete(unitId) || progress;
157
+ this.#tasks.set(unitId, this.#revision, undefined);
158
+ this.#orders.apply(unitId, this.#revision);
159
+ }
160
+ return progress;
161
+ }
162
+
163
+ #apply(delta: TodoDelta, entry: BranchEntry): boolean {
164
+ const removed = this.#removed(delta.removed);
165
+ let progress = this.#changed(delta, entry) || removed;
166
+ for (const order of delta.orders) {
167
+ if (!this.#known.has(order.id) || (order.parent !== null && !this.#known.has(order.parent))) {
168
+ throw new Error("INVALID_TODO_DELTA: order names a missing task");
169
+ }
170
+ progress = this.#orders.apply(order, this.#revision) || progress;
171
+ }
172
+ return progress;
173
+ }
174
+
175
+ #delta(entry: BranchEntry, data: unknown): ListFrame {
176
+ const delta = deltaData(data);
177
+ if (!this.#hasBase) {
178
+ throw new Error("INVALID_TODO_DELTA: no stable-ID base snapshot");
179
+ }
180
+ const progress = this.#apply(delta, entry),
181
+ version: ListVersion = {
182
+ hasBase: this.#hasBase,
183
+ orders: this.#orders,
184
+ revision: this.#revision,
185
+ size: this.#known.size,
186
+ tasks: this.#tasks,
187
+ },
188
+ provenance = this.#provenance;
189
+ let list: TodoList | undefined = undefined;
190
+ return {
191
+ changed: delta.changed.map((change) => change.task),
192
+ entry,
193
+ fenced: this.#fenced,
194
+ get list(): TodoList {
195
+ list ??= materialize(version, provenance);
196
+ return list;
197
+ },
198
+ progress,
199
+ get snapshot(): TodoList {
200
+ return provenance.list(this.list);
201
+ },
202
+ };
203
+ }
204
+
205
+ // Full snapshots replace the index. Deltas touch only changed tasks and links.
206
+ public read(entry: BranchEntry): ListFrame | undefined {
207
+ if (entry.type !== "custom") {
208
+ return undefined;
209
+ }
210
+ if (entry.customType === STATE_ENTRY || entry.customType === DELTA_ENTRY) {
211
+ this.#revision += step;
212
+ this.#latest =
213
+ entry.customType === STATE_ENTRY
214
+ ? this.#full(entry, entry.data)
215
+ : this.#delta(entry, entry.data);
216
+ return this.#latest;
217
+ }
218
+ return undefined;
219
+ }
220
+ }
221
+
222
+ export { BranchState };
223
+ export type { BranchEntry, ListFrame };