@narumitw/pi-sync-daemon 0.9.0 → 0.10.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.
Files changed (102) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +11 -1
  3. package/dist/cli.js +2 -0
  4. package/dist/client-transport.d.ts +14 -0
  5. package/dist/client-transport.js +66 -0
  6. package/dist/client.d.ts +15 -8
  7. package/dist/client.js +116 -86
  8. package/dist/consent.js +33 -11
  9. package/dist/daemon-debug.d.ts +3 -0
  10. package/dist/daemon-debug.js +33 -0
  11. package/dist/daemon-recovery.d.ts +4 -0
  12. package/dist/daemon-recovery.js +75 -0
  13. package/dist/engine/backends/git/git-backend.d.ts +8 -0
  14. package/dist/engine/backends/git/git-backend.js +39 -12
  15. package/dist/engine/backends/git/git-runner.js +6 -1
  16. package/dist/engine/backends/git/git-storage.js +5 -9
  17. package/dist/engine/backends/publication-encoding.d.ts +3 -0
  18. package/dist/engine/backends/publication-encoding.js +19 -0
  19. package/dist/engine/backends/s3/s3-backend.js +10 -12
  20. package/dist/engine/backends/sync-backend.d.ts +4 -0
  21. package/dist/engine/backends/webdav/webdav-backend.d.ts +0 -2
  22. package/dist/engine/backends/webdav/webdav-backend.js +15 -26
  23. package/dist/engine/backends/webdav/webdav-client.js +10 -0
  24. package/dist/engine/commands/command-types.d.ts +1 -0
  25. package/dist/engine/debug-log.d.ts +27 -0
  26. package/dist/engine/debug-log.js +134 -0
  27. package/dist/engine/ignore/ignore-initialization.d.ts +5 -1
  28. package/dist/engine/ignore/ignore-initialization.js +50 -14
  29. package/dist/engine/ignore/ignore-settings.js +11 -14
  30. package/dist/engine/ignore/ignore-source.d.ts +1 -1
  31. package/dist/engine/ignore/ignore-source.js +1 -1
  32. package/dist/engine/paths.d.ts +2 -0
  33. package/dist/engine/paths.js +7 -1
  34. package/dist/engine/settings/config-file.d.ts +10 -1
  35. package/dist/engine/settings/config-file.js +62 -17
  36. package/dist/engine/settings/config.d.ts +7 -0
  37. package/dist/engine/settings/config.js +49 -14
  38. package/dist/engine/snapshot/snapshot-apply.d.ts +2 -1
  39. package/dist/engine/snapshot/snapshot-apply.js +30 -8
  40. package/dist/engine/snapshot/snapshot-codec.js +3 -1
  41. package/dist/engine/snapshot/snapshot-payload.d.ts +4 -0
  42. package/dist/engine/snapshot/snapshot-payload.js +32 -0
  43. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +2 -0
  44. package/dist/engine/snapshot/snapshot-transaction-images.js +34 -0
  45. package/dist/engine/snapshot/snapshot-transaction.d.ts +4 -1
  46. package/dist/engine/snapshot/snapshot-transaction.js +50 -7
  47. package/dist/engine/snapshot/snapshot-types.d.ts +10 -2
  48. package/dist/engine/snapshot/snapshot.d.ts +3 -1
  49. package/dist/engine/snapshot/snapshot.js +64 -25
  50. package/dist/engine/state/lock.d.ts +2 -1
  51. package/dist/engine/state/lock.js +157 -17
  52. package/dist/engine/sync/continuous-sync.d.ts +10 -1
  53. package/dist/engine/sync/continuous-sync.js +35 -11
  54. package/dist/engine/sync/initialization.d.ts +1 -1
  55. package/dist/engine/sync/initialization.js +2 -2
  56. package/dist/engine/sync/local-fields.d.ts +6 -1
  57. package/dist/engine/sync/local-fields.js +42 -19
  58. package/dist/engine/sync/merged-sync.js +13 -10
  59. package/dist/engine/sync/remote-snapshot.js +18 -3
  60. package/dist/engine/sync/session-push.js +13 -4
  61. package/dist/engine/sync/startup-bootstrap.d.ts +1 -0
  62. package/dist/engine/sync/startup-bootstrap.js +105 -0
  63. package/dist/engine/sync/startup-recovery-evidence.d.ts +1 -0
  64. package/dist/engine/sync/startup-recovery-evidence.js +37 -0
  65. package/dist/engine/sync/startup-timings.d.ts +9 -2
  66. package/dist/engine/sync/startup-timings.js +80 -8
  67. package/dist/engine/sync/sync-error-guidance.js +22 -4
  68. package/dist/engine/sync/sync-inspection.js +4 -7
  69. package/dist/engine/sync/sync-local.d.ts +2 -1
  70. package/dist/engine/sync/sync-local.js +3 -1
  71. package/dist/engine/sync/sync-mutations.js +13 -7
  72. package/dist/engine/sync/sync-policy.d.ts +2 -0
  73. package/dist/engine/sync/sync-policy.js +9 -1
  74. package/dist/engine/sync/sync-state.d.ts +8 -3
  75. package/dist/engine/sync/sync-state.js +12 -4
  76. package/dist/engine/ui/sync-format.d.ts +16 -5
  77. package/dist/engine/ui/sync-format.js +23 -55
  78. package/dist/engine/ui/transfer-review.d.ts +2 -1
  79. package/dist/engine/ui/transfer-review.js +3 -3
  80. package/dist/engine-service.d.ts +6 -0
  81. package/dist/engine-service.js +54 -10
  82. package/dist/identity.d.ts +5 -2
  83. package/dist/identity.js +36 -6
  84. package/dist/index.d.ts +2 -1
  85. package/dist/index.js +2 -1
  86. package/dist/monitor.js +20 -1
  87. package/dist/paged-review.d.ts +35 -0
  88. package/dist/paged-review.js +177 -0
  89. package/dist/participant-ledger.d.ts +16 -0
  90. package/dist/participant-ledger.js +149 -0
  91. package/dist/protocol.d.ts +15 -0
  92. package/dist/protocol.js +4 -0
  93. package/dist/server.d.ts +7 -0
  94. package/dist/server.js +268 -120
  95. package/dist/service-host.d.ts +2 -1
  96. package/dist/service-host.js +29 -9
  97. package/dist/state-wait-jobs.d.ts +8 -0
  98. package/dist/state-wait-jobs.js +23 -0
  99. package/dist/state-wait.d.ts +7 -0
  100. package/dist/state-wait.js +34 -0
  101. package/docs/architecture.md +23 -1
  102. package/package.json +1 -1
@@ -1,7 +1,8 @@
1
1
  import { type EngineContext } from "./engine/host.js";
2
- import type { Execution } from "./protocol.js";
2
+ import { type Execution } from "./protocol.js";
3
3
  /** One service process owns one root; tests must use a separate process per root. */
4
4
  export declare function installServiceHost(root: string, ignoreFileOperationsAvailable?: boolean): {
5
+ cleanupRequired: () => boolean;
5
6
  run<T>(execution: Execution, action: () => Promise<T>): Promise<T>;
6
7
  };
7
8
  export declare function createServiceContext(execution: Execution): EngineContext;
@@ -7,6 +7,10 @@ import { readConsent } from "./consent.js";
7
7
  import { configureEngineHost } from "./engine/host.js";
8
8
  import { canonicalRootGuard, processExists } from "./identity.js";
9
9
  import { withCleanup } from "./lifecycle.js";
10
+ import { OWNERSHIP_CLEANUP_REQUIRED } from "./protocol.js";
11
+ class OwnershipCleanupError extends Error {
12
+ code = OWNERSHIP_CLEANUP_REQUIRED;
13
+ }
10
14
  const scope = new AsyncLocalStorage();
11
15
  /** One service process owns one root; tests must use a separate process per root. */
12
16
  export function installServiceHost(root, ignoreFileOperationsAvailable) {
@@ -27,7 +31,7 @@ export function installServiceHost(root, ignoreFileOperationsAvailable) {
27
31
  const owner = current();
28
32
  assertRoot();
29
33
  if (poisoned)
30
- throw new Error("Daemon ownership cleanup is uncertain; stop and reconcile before retrying.");
34
+ throw new OwnershipCleanupError("Daemon ownership cleanup is uncertain; stop and reconcile before retrying.");
31
35
  const missing = [...new Set(targets)].filter((target) => !owner.held.has(target)).sort();
32
36
  if (!missing.length)
33
37
  return action();
@@ -52,16 +56,17 @@ export function installServiceHost(root, ignoreFileOperationsAvailable) {
52
56
  }, async () => {
53
57
  // Release by request identity even when a grant response was lost. A cancelled
54
58
  // prompt is not evidence that a granted remote writer stopped.
55
- const results = await Promise.allSettled(requested.map(({ client, reservation }) => {
59
+ const results = await Promise.allSettled(requested.map(async ({ client, reservation }) => {
56
60
  const peer = peers.find((peer) => peer.id === client);
57
- return peer && !processExists(peer.pid)
58
- ? Promise.resolve(true)
59
- : owner.execution.request("queue-release", { reservation }, client);
61
+ if (peer && !processExists(peer.pid))
62
+ return;
63
+ if ((await owner.execution.request("queue-release", { reservation }, client)) !== true)
64
+ throw new Error("File-queue release was not acknowledged.");
60
65
  }));
61
66
  const failure = results.find((result) => result.status === "rejected");
62
67
  if (failure?.status === "rejected") {
63
68
  poisoned = true;
64
- throw new Error("File-queue release is uncertain; stop the daemon and keep grants quarantined until owner exit.", { cause: failure.reason });
69
+ throw new OwnershipCleanupError("File-queue release is uncertain; stop the daemon and keep grants quarantined until owner exit.", { cause: failure.reason });
65
70
  }
66
71
  });
67
72
  }
@@ -71,7 +76,7 @@ export function installServiceHost(root, ignoreFileOperationsAvailable) {
71
76
  root: () => {
72
77
  assertRoot();
73
78
  if (poisoned)
74
- throw new Error("Daemon ownership cleanup is uncertain; stop and reconcile before restarting.");
79
+ throw new OwnershipCleanupError("Daemon ownership cleanup is uncertain; stop and reconcile before restarting.");
75
80
  return root;
76
81
  },
77
82
  reserveTargets: reserve,
@@ -106,7 +111,9 @@ export function installServiceHost(root, ignoreFileOperationsAvailable) {
106
111
  }
107
112
  catch (error) {
108
113
  poisoned = true;
109
- throw error;
114
+ throw new OwnershipCleanupError("Pi settings lock release failed; stop and reconcile before restarting.", {
115
+ cause: error,
116
+ });
110
117
  }
111
118
  });
112
119
  });
@@ -120,8 +127,21 @@ export function installServiceHost(root, ignoreFileOperationsAvailable) {
120
127
  status: (_ctx, value, presentation) => current().execution.emit("status", { value, presentation }),
121
128
  });
122
129
  return {
130
+ cleanupRequired: () => poisoned,
123
131
  run(execution, action) {
124
- return scope.run({ execution, held: new Set() }, action);
132
+ return scope.run({ execution, held: new Set() }, async () => {
133
+ try {
134
+ return await action();
135
+ }
136
+ catch (error) {
137
+ if (error instanceof AggregateError) {
138
+ const cleanup = error.errors.find((entry) => entry instanceof OwnershipCleanupError);
139
+ if (cleanup)
140
+ throw new OwnershipCleanupError(`${error.message} ${cleanup.message}`, { cause: error });
141
+ }
142
+ throw error;
143
+ }
144
+ });
125
145
  },
126
146
  };
127
147
  }
@@ -0,0 +1,8 @@
1
+ export declare const STATE_WAIT_FAILURE_LIMIT = 3;
2
+ export declare function stateWaitResult(reply: unknown): {
3
+ reply: Record<string, unknown>;
4
+ version: string;
5
+ finished: string[];
6
+ missing: string[];
7
+ };
8
+ export declare function stateWaitJobs<Waiter>(waiters: Map<string, Waiter>): string[];
@@ -0,0 +1,23 @@
1
+ import { DAEMON_JOB_CAPACITY, record, validId } from "./protocol.js";
2
+ export const STATE_WAIT_FAILURE_LIMIT = 3;
3
+ export function stateWaitResult(reply) {
4
+ if (!record(reply) ||
5
+ typeof reply.stateRevision !== "string" ||
6
+ !/^[0-9]{1,40}$/u.test(reply.stateRevision) ||
7
+ !Array.isArray(reply.finished) ||
8
+ !Array.isArray(reply.missing) ||
9
+ !reply.finished.every(validId) ||
10
+ !reply.missing.every(validId))
11
+ throw new Error("Invalid daemon state-wait response.");
12
+ return { reply, version: reply.stateRevision, finished: reply.finished, missing: reply.missing };
13
+ }
14
+ export function stateWaitJobs(waiters) {
15
+ if (waiters.size <= DAEMON_JOB_CAPACITY)
16
+ return [...waiters.keys()];
17
+ const batch = [...waiters.entries()].slice(0, DAEMON_JOB_CAPACITY);
18
+ return batch.map(([id, waiter]) => {
19
+ waiters.delete(id);
20
+ waiters.set(id, waiter);
21
+ return id;
22
+ });
23
+ }
@@ -0,0 +1,7 @@
1
+ export declare class ParticipantStateWait {
2
+ private revision;
3
+ private wake?;
4
+ get version(): string;
5
+ changed(): void;
6
+ wait(version: unknown, signal: AbortSignal | undefined): Promise<void> | undefined;
7
+ }
@@ -0,0 +1,34 @@
1
+ import { STATE_WAIT_HEARTBEAT_MS } from "./protocol.js";
2
+ export class ParticipantStateWait {
3
+ revision = 0n;
4
+ wake;
5
+ get version() {
6
+ return this.revision.toString();
7
+ }
8
+ changed() {
9
+ this.revision++;
10
+ this.wake?.();
11
+ }
12
+ wait(version, signal) {
13
+ signal?.throwIfAborted();
14
+ this.wake?.();
15
+ if (version !== this.version)
16
+ return;
17
+ return new Promise((resolve, reject) => {
18
+ const finish = () => {
19
+ clearTimeout(timer);
20
+ signal?.removeEventListener("abort", abort);
21
+ this.wake = undefined;
22
+ resolve();
23
+ };
24
+ const abort = () => {
25
+ reject(signal?.reason);
26
+ finish();
27
+ };
28
+ const timer = setTimeout(finish, STATE_WAIT_HEARTBEAT_MS);
29
+ timer.unref();
30
+ this.wake = finish;
31
+ signal?.addEventListener("abort", abort, { once: true });
32
+ });
33
+ }
34
+ }
@@ -64,7 +64,7 @@ A version 6 snapshot carries portable intent (a versioned fingerprint of ordered
64
64
  | `ctx.isIdle()` | Current participating-client facts, not a captured Pi context | `service-host.ts` |
65
65
  | Protected sessions and missing-settings guard | All live client PIDs, including retired clients; separate from active participation | `server.ts`, `service-host.ts` |
66
66
  | `ctx.ui.notify`, status | Bounded events | `server.ts`, `service-host.ts` |
67
- | Confirm/select/exact merge review | Job-bound callbacks; revalidation after response | `service-host.ts`, `engine/ui/merge-review.ts` |
67
+ | Confirm/select/exact merge review | Job-bound callbacks; revalidation after response; directional TUI review sends compact summary lines and the full path list as separate fields | `service-host.ts`, `engine/ui/transfer-review.ts` |
68
68
  | Reload | Explicit client callback after the existing user confirmation | `engine/sync/sync-mutations.ts` |
69
69
  | `ctx.model`, `modelRegistry.streamSimple` | Explicit selected model identity/signature; independent public SDK runtime | `model-signature.ts`, `resolver-host.ts` |
70
70
  | `withFileMutationQueue` | Participating Pi queue grants plus daemon-local queue | `service-host.ts`, Pi adapter `daemon/apply-gate.ts` |
@@ -129,6 +129,8 @@ After quiescence, the authenticated final fence returns `RemoteError.name = "Dae
129
129
 
130
130
  A later command can reconnect after a cancelled or failed unpublished attach. First, Pi Sync confirms the old connection's detach and drain, then releases its local queue grants. It uses a fresh client ID and generation for the next connection. Daemon retirement records stay intact, so late requests cannot revive the old attempt. Failed cleanup blocks a new identity and operation; it does not release uncertain grants. A cancelled or submitted operation is never replayed by this recovery.
131
131
 
132
+ Reattachment is ordered with facts updates. If reattachment fails, cancellation releases a model-binding callback that is still waiting for its turn. A callback that already started must finish its work and recheck ownership before returning a binding.
133
+
132
134
  ### Recovering expired contact
133
135
 
134
136
  A running daemon can expire a Pi session's heartbeat after a computer sleeps. A
@@ -149,6 +151,18 @@ publishes fresh facts after confirmation. The binding and consent checks still
149
151
  apply. A failed or uncertain repair does not start a replacement owner, release
150
152
  uncertain grants, or resubmit work.
151
153
 
154
+ ### Read-only configured startup
155
+
156
+ An attached interactive client can become ready without joining the foreground job queue when the daemon can confirm that no recovery is needed. If another client is in a human review, the owner requires exact evidence of that job's live operation lock and the same pending uncommitted review. It queues initialization if ready publication would invalidate the review's participant generation. Active writes, open reservations, uncertain ownership, pending recovery, and unsupported settings/state layouts also use queued initialization. The owner rechecks settings, consent, recovery, and participant evidence after the ledger write and before exposing ready facts. Pi tries the fast path only with active contact and no pending or uncertain contact repair. Pi orders bootstrap with facts publication and samples facts when each update starts, so an older snapshot cannot overwrite confirmed readiness. If contact changes after the daemon accepts readiness, a current client with a confirmed reply keeps readiness without treating it as proof of active contact. If the reply is lost or its session is no longer current, Pi stops using that connection and drains and retires the original participant. Retirement stops it from authorizing work and keeps PID-based file protection. Unconfirmed cleanup retains recovery evidence; Pi does not retry the bootstrap or publish facts from the old session. Use the [daemon CLI recovery guide](../../pi-sync/docs/daemon-migration.md#recover-from-uncertain-daemon-cleanup) if the client has retired and cannot run `/sync daemon recover`. Attach admission still waits for an active file reservation. This is not an atomic guarantee against external filesystem changes; later transfers keep their fresh checks.
157
+
158
+ ### Local transport and ledger writes
159
+
160
+ An owner that advertises `stateWait` in its attach reply supports one cancellable `state-wait` request per client. It returns events, the complete pending callback set, contact state, and terminal job IDs. The client fetches each terminal result once. A separate per-participant revision wakes the waiter on changes even if no event was emitted. Idle waits return at the heartbeat interval. If more jobs are still waiting locally than fit in a request, the client rotates through the IDs. A failed observation does not cancel a submitted job. After three consecutive failures, the client polls the original job ID for its result. Older peers use the existing polling routes. If either path cannot find the result of a submitted job, the client treats the outcome as uncertain before it requests cancellation. A cancellation acknowledgement does not prove that an absent job never ran. The client blocks new jobs and contact repair until it is disposed. It still drains queue-release callbacks, and the caller must reconcile the original outcome before retrying.
161
+
162
+ A facts update skips a ledger rewrite only after the serialized writer confirms that the same ledger image was already published. A queued or failed attempt is not evidence of publication. The update still confirms contact, checks ownership, and runs the monitor hook. Changed facts, including busy state and live-session protection, retain the existing acknowledgment and persistence boundaries.
163
+
164
+ A client with a paged review presenter can opt into on-demand exact details at attach. The client can cancel before fetching any page. For these paged reviews, approval requires the verified exact details for the same pending offer. The owner binds the offer to the client generation and callback/job, and consumes it once. Without support on both sides, the client receives the existing eager review.
165
+
152
166
  ## Repository lifetime smoke
153
167
 
154
168
  After the repository build, run the standalone real-clock smoke from the repository root. It loads the built package directory through real Pi RPC, tests no-client CLI exit and last-Pi exit, restarts through the next eligible Pi, and retains an explicitly reviewed grant beyond the grace period. It uses only owned loopback provider/storage fixtures and preserves recovery bytes. It takes about two minutes; it is not a Vitest case.
@@ -161,6 +175,12 @@ node node_modules/.cache/pi-extensions-test/packages/pi-sync/test/idle-exit-cli-
161
175
 
162
176
  Do not rebuild while a smoke-owned daemon is running. Linux containers need an init process to reap detached children. This smoke does not verify native Windows behavior, terminal logout, physical power loss, or real-data cutover.
163
177
 
178
+ ### Backend observations and publication
179
+
180
+ Git can read the head and its snapshot from one fresh observation for scoped callers that retain later apply and publication checks. Independent reads of a snapshot still verify reachability from a fresh head. The cache reuses validated manifest and tree data for the exact commit, not the mutable branch revision. Snapshot validation reuses a verified checksum only for the same exact encoded payload and digest; path, selection, manifest, and pointer checks still run.
181
+
182
+ S3 and WebDAV encode an owned publication image while checking remote conditional support. Neither stages or publishes the snapshot before the probe and cleanup succeed. Conditional checks still run on every publication; WebDAV tries the target collection first, then creates missing ancestors as needed.
183
+
164
184
  ## Package upgrades
165
185
 
166
186
  The authenticated `hello` response reports the running package build separately from its protocol
@@ -213,6 +233,8 @@ These guarantees cover cooperating registered clients. Unregistered old Pi versi
213
233
 
214
234
  ### Agent-directory recovery evidence
215
235
 
236
+ Directional apply does not rewrite an independent regular file when its exact spelling and bytes already match. It keeps the same target queue and verifies the omitted file before accepting the result. An intervening edit blocks acceptance; rollback journals cover only actual mutations. These checks do not reserve the filesystem against unrelated writers.
237
+
216
238
  Version 10 journals use unique workspace slots. Scratch files get separate unique slots in private directories on the destination filesystem. Recovery reads only the names that the durable journal or scratch record identifies. A failed publication can leave unrecorded objects, but it cannot block a new slot or authorize deleting the old one. The synced path policy excludes these private objects. Older journals keep their exact paths and identity checks; an upgrade does not adopt unrecorded data.
217
239
 
218
240
  Apply under an ignore-file or mixed legacy policy uses transaction journal version 12 for directory scope or version 13 for selected paths. The journal binds the setup, destination, local-field policy, and reserved filenames, plus exact local source evidence for ignore-file setups. Merge journals version 3, accepted baselines, and retained conflict evidence also bind the local policy. These are private records, not part of the portable selection. Pending recovery checks the recorded binding under mutation ownership. A journal without the required binding cannot authorize replay under an activated policy. Completed cleanup does not replay file changes. Preserve uncertain evidence; do not replay under different rules or treat a downgrade after v6 publication as rollback. See [ADR 0008](../../../docs/adr/0008-pi-sync-ignore-file.md) for the contract and activation gates.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-sync-daemon",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "description": "A local synchronization daemon with a versioned client API.",
5
5
  "type": "module",
6
6
  "license": "MIT",