@oisin-ee/pi-dogsled 0.34.2 → 0.36.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 +24 -2
- package/package.json +1 -1
- package/pi/activity.ts +67 -32
- package/pi/observation.ts +15 -2
- package/pi/todo/README.md +16 -2
- package/pi/todo/src/branch-state.ts +223 -0
- package/pi/todo/src/delta-fixture.ts +141 -0
- package/pi/todo/src/delta-review-fixture.ts +63 -0
- package/pi/todo/src/delta-sequence-fixture.ts +59 -0
- package/pi/todo/src/delta-validation.ts +78 -0
- package/pi/todo/src/delta-worker-fixture.ts +102 -0
- package/pi/todo/src/delta.ts +152 -0
- package/pi/todo/src/generated/todo_core.d.ts +9 -0
- package/pi/todo/src/generated/todo_core.js +24 -0
- package/pi/todo/src/generated/todo_core_bg.wasm +0 -0
- package/pi/todo/src/generated/todo_core_bg.wasm.d.ts +1 -0
- package/pi/todo/src/history.ts +54 -0
- package/pi/todo/src/old-lifecycle-fixture.ts +106 -0
- package/pi/todo/src/old-provider-fixture.ts +290 -0
- package/pi/todo/src/old-reminder-fixture.ts +31 -0
- package/pi/todo/src/old-state-fixture.ts +106 -0
- package/pi/todo/src/old-tool-fixture.ts +61 -0
- package/pi/todo/src/order-index.ts +109 -0
- package/pi/todo/src/provenance.ts +54 -0
- package/pi/todo/src/provider.ts +34 -33
- package/pi/todo/src/reminder.ts +67 -17
- package/pi/todo/src/seal-reference-fixture.ts +59 -0
- package/pi/todo/src/snapshot-reference-fixture.ts +88 -0
- package/pi/todo/src/state.ts +88 -92
- package/pi/todo/src/tool.ts +4 -3
- package/pi/todo/src/wasm.ts +1 -0
- package/plugins/dogsled/skills/dogsled/references/commands.md +18 -0
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.
|
|
16
|
+
mise use github:oisin-ee/dogsled@v0.36.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.
|
|
22
|
+
pi install npm:@oisin-ee/pi-dogsled@0.36.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.
|
|
3
|
+
"version": "0.36.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(
|
|
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 (
|
|
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(
|
|
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(
|
|
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(
|
|
379
|
+
this.backoff();
|
|
351
380
|
return;
|
|
352
381
|
}
|
|
353
|
-
this.stop(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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
|
|
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(
|
|
455
|
-
this.
|
|
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(
|
|
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):
|
|
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
|
-
|
|
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
|
-
|
|
78
|
-
|
|
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 };
|