@joe-broadhead/opencode-mem 0.9.14 → 0.11.3

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 (143) hide show
  1. package/CHANGELOG.md +1856 -0
  2. package/README.md +15 -7
  3. package/SECURITY.md +3 -1
  4. package/docs/agent-instructions.md +1 -1
  5. package/docs/agent-protocol.md +7 -7
  6. package/docs/permissions.md +16 -0
  7. package/package.json +8921 -1070
  8. package/shared/page-paths.js +44 -0
  9. package/skills/mem.pages/SKILL.md +3 -1
  10. package/skills/mem.usage/SKILL.md +15 -15
  11. package/src/action-grant-keys.js +159 -0
  12. package/src/action-grant.js +439 -0
  13. package/src/actions.js +1690 -0
  14. package/src/backend/records.js +25 -2
  15. package/src/backend/v3.js +76 -22
  16. package/src/call-shapes.js +17 -16
  17. package/src/collector-lock.js +533 -62
  18. package/src/collector-service.js +153 -26
  19. package/src/collector.js +623 -30
  20. package/src/config.js +88 -7
  21. package/src/connect.js +106 -8
  22. package/src/credentials.js +123 -25
  23. package/src/events.js +174 -3
  24. package/src/forget-turn.js +141 -0
  25. package/src/host-refusal.js +78 -0
  26. package/src/index.js +209 -22
  27. package/src/jobs/host.js +557 -0
  28. package/src/ops/codes.js +110 -0
  29. package/src/ops/copy-lineage.js +42 -0
  30. package/src/ops/index.js +28 -0
  31. package/src/ops/space-ops.js +1936 -0
  32. package/src/outlinks.js +103 -0
  33. package/src/p2-reservation.js +151 -0
  34. package/src/permissions.js +30 -0
  35. package/src/plugins/descriptor.js +62 -0
  36. package/src/plugins/discovery.js +318 -0
  37. package/src/plugins/grants.js +178 -0
  38. package/src/plugins/locate.js +319 -0
  39. package/src/plugins/manifest.js +1162 -0
  40. package/src/plugins/source-contract/index.js +34 -0
  41. package/src/plugins/source-contract/policy.js +102 -0
  42. package/src/plugins/source-contract/vendor/PROVENANCE.json +17 -0
  43. package/src/plugins/source-contract/vendor/RELEASE-SHA256SUMS +3 -0
  44. package/src/plugins/source-contract/vendor/RELEASE.json +17 -0
  45. package/src/plugins/source-contract/vendor/SHA256SUMS +41 -0
  46. package/src/plugins/source-contract/vendor/THIRD-PARTY-NOTICES.md +35 -0
  47. package/src/plugins/source-contract/vendor/broker-client.js +93 -0
  48. package/src/plugins/source-contract/vendor/chunks/chunk-3M5PAKSS.js +84 -0
  49. package/src/plugins/source-contract/vendor/chunks/chunk-4ERCA4TK.js +185 -0
  50. package/src/plugins/source-contract/vendor/chunks/chunk-6HDIB2SA.js +183 -0
  51. package/src/plugins/source-contract/vendor/chunks/chunk-ELPJD3ND.js +10 -0
  52. package/src/plugins/source-contract/vendor/chunks/chunk-HLVAKAYG.js +10 -0
  53. package/src/plugins/source-contract/vendor/chunks/chunk-I2RXJJJM.js +81 -0
  54. package/src/plugins/source-contract/vendor/chunks/chunk-KWEWSZ4V.js +505 -0
  55. package/src/plugins/source-contract/vendor/chunks/chunk-KYWBTAF4.js +182 -0
  56. package/src/plugins/source-contract/vendor/chunks/chunk-Q3RQA5J2.js +249 -0
  57. package/src/plugins/source-contract/vendor/chunks/chunk-RRUAIQ4I.js +156 -0
  58. package/src/plugins/source-contract/vendor/chunks/chunk-RYNKNCPP.js +165 -0
  59. package/src/plugins/source-contract/vendor/chunks/chunk-W5SHR7DQ.js +9477 -0
  60. package/src/plugins/source-contract/vendor/chunks/chunk-ZUKF7P6U.js +653 -0
  61. package/src/plugins/source-contract/vendor/cursor.js +26 -0
  62. package/src/plugins/source-contract/vendor/descriptor.js +34 -0
  63. package/src/plugins/source-contract/vendor/events.js +257 -0
  64. package/src/plugins/source-contract/vendor/index.js +10 -0
  65. package/src/plugins/source-contract/vendor/params.js +22 -0
  66. package/src/plugins/source-contract/vendor/permission.js +28 -0
  67. package/src/plugins/source-contract/vendor/pick.js +22 -0
  68. package/src/plugins/source-contract/vendor/read.js +29 -0
  69. package/src/plugins/source-contract/vendor/registry.js +23 -0
  70. package/src/plugins/source-contract/vendor/schema.js +17 -0
  71. package/src/plugins/source-contract/vendor/schemas/output.agenda.json +96 -0
  72. package/src/plugins/source-contract/vendor/schemas/output.countdown.json +28 -0
  73. package/src/plugins/source-contract/vendor/schemas/output.image.json +28 -0
  74. package/src/plugins/source-contract/vendor/schemas/output.inbox.json +84 -0
  75. package/src/plugins/source-contract/vendor/schemas/output.links.json +46 -0
  76. package/src/plugins/source-contract/vendor/schemas/output.list.json +57 -0
  77. package/src/plugins/source-contract/vendor/schemas/output.metric.json +61 -0
  78. package/src/plugins/source-contract/vendor/schemas/output.note.json +14 -0
  79. package/src/plugins/source-contract/vendor/schemas/output.progress.json +50 -0
  80. package/src/plugins/source-contract/vendor/schemas/output.record.json +38 -0
  81. package/src/plugins/source-contract/vendor/schemas/output.table.json +61 -0
  82. package/src/plugins/source-contract/vendor/schemas/output.thread.json +62 -0
  83. package/src/plugins/source-contract/vendor/schemas/sources.json +819 -0
  84. package/src/plugins/source-contract/vendor/schemas.js +19 -0
  85. package/src/plugins/source-contract/vendor/tools-rpc.js +42 -0
  86. package/src/plugins/verify.js +56 -0
  87. package/src/protocol.js +11 -6
  88. package/src/recall.js +92 -5
  89. package/src/records.js +61 -2
  90. package/src/requests.js +216 -0
  91. package/src/runtime.js +89 -7
  92. package/src/setup-time.js +68 -0
  93. package/src/skills.js +230 -8
  94. package/src/source-ids.js +25 -0
  95. package/src/sources/declaration.js +365 -0
  96. package/src/sources/reads.js +772 -0
  97. package/src/sources/rpc.js +151 -0
  98. package/src/sources.js +389 -92
  99. package/src/spaces.js +283 -11
  100. package/src/spool.js +61 -4
  101. package/src/stated.js +10 -5
  102. package/src/storable.js +139 -0
  103. package/src/tools/commitments.js +74 -23
  104. package/src/tools/held-write.js +46 -19
  105. package/src/tools/index.js +28 -0
  106. package/src/tools/ingest.js +38 -2
  107. package/src/tools/memory.js +56 -25
  108. package/src/tools/page.js +212 -95
  109. package/src/tools/recall.js +218 -4
  110. package/src/tools/share.js +42 -3
  111. package/src/tools/shared.js +84 -6
  112. package/src/tools/space-lifecycle.js +278 -0
  113. package/src/tools/spaces.js +381 -30
  114. package/src/tools/status.js +9 -2
  115. package/src/tools/wiki.js +231 -116
  116. package/src/util.js +110 -6
  117. package/src/vendor/source-contract/README.md +24 -0
  118. package/src/vendor/source-contract/THIRD-PARTY-NOTICES.md +35 -0
  119. package/src/vendor/source-contract/VENDOR.json +81 -0
  120. package/src/vendor/source-contract/chunks/chunk-3M5PAKSS.js +84 -0
  121. package/src/vendor/source-contract/chunks/chunk-6HDIB2SA.js +183 -0
  122. package/src/vendor/source-contract/chunks/chunk-HLVAKAYG.js +10 -0
  123. package/src/vendor/source-contract/chunks/chunk-I2RXJJJM.js +81 -0
  124. package/src/vendor/source-contract/chunks/chunk-KWEWSZ4V.js +505 -0
  125. package/src/vendor/source-contract/chunks/chunk-W5SHR7DQ.js +9477 -0
  126. package/src/vendor/source-contract/chunks/chunk-ZUKF7P6U.js +653 -0
  127. package/src/vendor/source-contract/cursor.js +26 -0
  128. package/src/vendor/source-contract/events.js +257 -0
  129. package/src/vendor/source-contract/registry.js +23 -0
  130. package/src/vendor/source-contract/tools-rpc.js +42 -0
  131. package/src/views/access-reads.js +256 -0
  132. package/src/views/communities.js +77 -0
  133. package/src/views/contracts.js +1082 -23
  134. package/src/views/inbox-bytes.js +103 -0
  135. package/src/views/profile.js +31 -0
  136. package/src/views/receipt.js +26 -1
  137. package/src/views/records-reads.js +520 -41
  138. package/src/views/rpc.js +153 -25
  139. package/src/views/shape.js +8 -5
  140. package/src/views/write-state.js +89 -0
  141. package/src/wiki-ingest.js +215 -0
  142. package/src/wiki-state.js +228 -0
  143. package/views/pages.html +2 -2
@@ -1,61 +1,228 @@
1
1
  import fs from "node:fs"
2
2
  import os from "node:os"
3
3
  import path from "node:path"
4
+ import { execFileSync } from "node:child_process"
4
5
  import { randomUUID } from "node:crypto"
5
6
 
6
7
  /** A lease whose heartbeat is older than this belongs to a process that stopped. */
7
8
  export const LEASE_STALE_MS = 10 * 60_000
8
9
 
10
+ /**
11
+ * A same-host pid that is alive but not provably the lease's holder is kept for
12
+ * this long and no longer: half an hour of silence is 30 missed heartbeats of
13
+ * the collector's 60 seconds (HEARTBEAT_MS), far past any healthy holder — one
14
+ * that was merely asleep, or stopped, beats within a minute of waking. It can
15
+ * be this short because a holder that wakes after losing its lease stops
16
+ * before its next read or write (stillHolder, src/collector-service.js), so the
17
+ * cost of recovering early is a moment's overlap, not two collectors writing.
18
+ */
19
+ export const LEASE_CEILING_MS = 30 * 60_000
20
+
21
+ /** A recorded process start and the lease's own `since` are compared with this much slack (ps reports whole seconds). */
22
+ const START_SLACK_MS = 2_000
23
+
24
+ /** The machine that wrote the lease records its hostname, so a pid can be checked only where it means something. */
25
+ const HOST = os.hostname()
26
+
27
+ /** A pid's start on Linux, in wall-clock milliseconds, from /proc (the tick rate is calibrated against this process's own). */
28
+ function linuxStarted(pid) {
29
+ try {
30
+ const ticksOf = (text) => Number(String(text).slice(String(text).lastIndexOf(") ") + 2).split(" ")[19])
31
+ const ticks = ticksOf(fs.readFileSync(`/proc/${pid}/stat`, "utf8"))
32
+ const btime = Number(/^btime (\d+)$/m.exec(fs.readFileSync("/proc/stat", "utf8"))?.[1])
33
+ const ownTicks = ticksOf(fs.readFileSync("/proc/self/stat", "utf8"))
34
+ if (!Number.isFinite(ticks) || !Number.isFinite(btime) || !Number.isFinite(ownTicks) || ownTicks <= 0) return null
35
+ const ownSeconds = (Date.now() - process.uptime() * 1000) / 1000 - btime
36
+ if (!(ownSeconds > 0)) return null
37
+ const hz = ownTicks / ownSeconds
38
+ return btime * 1000 + (ticks / hz) * 1000
39
+ } catch {
40
+ return null
41
+ }
42
+ }
43
+
44
+ /** A pid's start from `ps -o lstart=` (macOS, and Linux without /proc), in wall-clock milliseconds. */
45
+ function psStarted(pid) {
46
+ try {
47
+ const text = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
48
+ encoding: "utf8",
49
+ timeout: 2_000,
50
+ stdio: ["ignore", "pipe", "ignore"],
51
+ env: { ...process.env, LC_ALL: "C" },
52
+ }).trim()
53
+ const at = Date.parse(text)
54
+ return Number.isFinite(at) ? at : null
55
+ } catch {
56
+ return null
57
+ }
58
+ }
59
+
60
+ /** When a pid's process started, as wall-clock milliseconds, or null when this machine cannot say. */
61
+ function processStarted(pid) {
62
+ return (process.platform === "linux" ? linuxStarted(pid) : null) ?? psStarted(pid)
63
+ }
64
+
9
65
  /**
10
66
  * One collector per machine (docs/design/memory-v1-contracts.md §4.4): a lease
11
67
  * on `collector.lock` beside the spool, held by one OpenCode process and kept
12
68
  * alive by a heartbeat (the file's modification time). Every other process
13
- * sees a fresh lease and skips; a lease whose heartbeat is older than ten
14
- * minutes is taken over.
69
+ * sees a fresh lease and skips. A lease is taken over only when it has been
70
+ * abandoned:
71
+ *
72
+ * 1. its holder's process is gone;
73
+ * 2. its pid is alive but is not the holder — a later process took that pid
74
+ * (it started after the lease was written), or the pid is the taking
75
+ * process's own, which cannot be the holder of a lease it does not hold;
76
+ * 3. a same-host pid that is alive but not provably the holder has not beaten
77
+ * for half an hour (LEASE_CEILING_MS, 30 missed 60-second beats), so such a
78
+ * lease is never kept forever. A live, healthy holder never misses that
79
+ * long.
80
+ *
81
+ * A record from another machine, or one with no usable pid, is judged by its
82
+ * heartbeat alone, as before: a pid means nothing elsewhere, and a holder that
83
+ * wakes after losing its lease stops rather than writes.
15
84
  *
16
85
  * Built on the same file primitives as the spool's cross-process claims
17
- * (src/spool.js): no-clobber creation and atomic rename. The spool's own
18
- * helpers are one-shot claims with no heartbeat, so the lease is its own:
86
+ * (src/spool.js): no-clobber hard links and checks made through one open file.
87
+ * The spool's own helpers are one-shot claims with no heartbeat, so the lease
88
+ * is its own:
19
89
  *
20
90
  * - **create** writes the record to a private temp file and hard-links it to
21
91
  * `collector.lock`; `link` fails when the name exists, so exactly one of
22
- * several racing processes creates it, and nobody ever reads a half-written
92
+ * several racing processes creates it — and nobody ever reads a half-written
23
93
  * lock;
24
- * - **take over** renames the stale lock to a name of the taker's own (one
25
- * rename wins), checks that what it moved is the stale lease it judged
26
- * (same holder and heartbeat) and puts it back if not, then creates;
27
- * - **heartbeat** sets the file's times, only while the record is still this
28
- * holder's;
29
- * - **release** removes the file, only while it is still this holder's.
94
+ * - **take over** is a claim plus a removal, and both are no-clobber hard
95
+ * links, which is the whole of the exclusivity:
96
+ * the taker hard-links a **takeover claim** whose name is the inode of the
97
+ * stale lease it judged (`collector.lock.take-<dev>-<ino>`). Two takers of
98
+ * one lease can therefore never both hold it, and only the claim's holder
99
+ * removes the name — so the window between a taker's stat of the name and
100
+ * its unlink of it, which gave two takers two leases on `a13b245f`, can be
101
+ * entered by one process only. The claim is re-checked immediately before the
102
+ * unlink, the lease is re-read and must still be the very one judged (same
103
+ * id, inode and heartbeat: a holder that beat, or a taker that won first,
104
+ * stands), and the name is removed only while it still points at that inode;
105
+ * - **fence** every protected action: the token is the inode this holder
106
+ * created, and `heartbeat()` (run before every read and every write:
107
+ * `stillHolder`, src/collector-service.js) proves the name still holds that
108
+ * inode with this holder's record. A taker whose lease was removed anyway —
109
+ * a stopped taker resumed, a claim stolen from a dead one — cannot act, so a
110
+ * moment of double ownership never becomes two collectors collecting;
111
+ * - **beat and release** open the lock file first and work through that open
112
+ * file (fstat, the record, futimes), then check the name still points at it:
113
+ * a takeover between the read and the write can never be mistaken for
114
+ * holding the lease, and a beat is never applied to another holder's lock.
115
+ * A holder that lost its lease this way learns it from `heartbeat()` (and
116
+ * from `acquire()` before its next run), so it stops rather than writes.
30
117
  *
31
- * `onStale` (tests only) runs between judging a lease stale and moving it, the
32
- * window in which another process may beat or take it.
118
+ * A claim, or a temp file, left by a taker is recovered by its owner being
119
+ * **provably dead**, never by age: `acquire()` sweeps the lock's directory and
120
+ * removes a file of its own whose recorded pid no longer runs, or whose pid now
121
+ * belongs to a process that started after the file was written. A file from
122
+ * another machine, or a damaged one, cannot be judged that way at all and ages
123
+ * out at the lease ceiling (LEASE_CEILING_MS, thirty minutes of silence, as a
124
+ * lease does). So a live process's claim is never removed, however old: a taker
125
+ * stopped mid-takeover keeps its claim until it resumes or dies — killing it
126
+ * frees the claim at the next `acquire()`, and no other process can tell a
127
+ * stopped taker from a slow one without opening exactly this window.
33
128
  *
34
- * @param {{ file: string, staleMs?: number, now?: () => number, id?: string, pid?: number, log?: any, onStale?: (lease: object) => void }} input
129
+ * **The residual, stated plainly.** POSIX has no compare-and-unlink, so a
130
+ * recovery that removes a dead claim and then links its own is still a read and
131
+ * an unlink. A sweeper preempted between them can remove the claim a second
132
+ * taker linked in between (`dropGone` narrows this to a single syscall gap by
133
+ * requiring the very inode it judged). That needs a crashed claim, a sweeper
134
+ * and a second preemption, and it leaves two `owned: true`. The fence is what
135
+ * makes it harmless: the displaced owner's `held()`/`heartbeat()` fail, so it
136
+ * takes no further guarded action, and every local write it already had in
137
+ * flight is fenced again at its commit (`writeStatus`). Only a call already
138
+ * sent to the records service can land, which no token of this machine can
139
+ * stop; the run then stops before the next one.
140
+ *
141
+ * A filesystem without hard links (FAT, exFAT, SMB without Unix extensions)
142
+ * makes `link` fail and `acquire()` throw: the collector refuses to collect
143
+ * rather than risk two collectors.
144
+ *
145
+ * `onStale` (tests only) runs between judging a lease stale and claiming it,
146
+ * the window in which another process may beat or take it. `onStep` (tests
147
+ * only) reports each step of a takeover and of a beat, so a crash at every one
148
+ * can be replayed. `startedAt` (tests only) answers when a pid's process
149
+ * started.
150
+ *
151
+ * @param {{ file: string, staleMs?: number, ceilingMs?: number, now?: () => number, id?: string, pid?: number, log?: any, onStale?: (lease: object) => void, onStep?: (step: string) => void, startedAt?: (pid: number) => number | null }} input
35
152
  */
36
- export function createLease({ file, staleMs = LEASE_STALE_MS, now = Date.now, id = randomUUID(), pid = process.pid, log, onStale }) {
153
+ export function createLease({
154
+ file,
155
+ staleMs = LEASE_STALE_MS,
156
+ ceilingMs = LEASE_CEILING_MS,
157
+ now = Date.now,
158
+ id = randomUUID(),
159
+ pid = process.pid,
160
+ log,
161
+ onStale,
162
+ onStep,
163
+ startedAt = processStarted,
164
+ }) {
37
165
  const dir = path.dirname(file)
166
+ const base = path.basename(file)
167
+ /** The inode this holder's lease occupies: the token every protected action is checked against. */
168
+ let mine = null
38
169
 
170
+ /**
171
+ * A stat whose device and inode are bigints: NTFS file ids above 2^53 lose
172
+ * their low bits as JS numbers, so two different leases could compare equal.
173
+ */
174
+ function statOf(target) {
175
+ return fs.statSync(target, { bigint: true })
176
+ }
177
+
178
+ /**
179
+ * A file's modification time in milliseconds, keeping the sub-millisecond
180
+ * part a bigint stat reports only in whole nanoseconds: the heartbeat is
181
+ * compared and aged to the millisecond, and rounding it would make a beat
182
+ * look older than it is.
183
+ */
184
+ function heartbeatOf(stat) {
185
+ if (stat.mtimeNs === undefined) return Number(stat.mtimeMs)
186
+ return Number(stat.mtimeNs / 1_000_000n) + Number(stat.mtimeNs % 1_000_000n) / 1e6
187
+ }
188
+
189
+ /** Read the lease through one open file, so the record and the heartbeat it is judged by come from the same inode. */
39
190
  function readAt(target) {
40
- let stat
191
+ let fd
41
192
  try {
42
- stat = fs.statSync(target)
193
+ fd = fs.openSync(target, "r")
43
194
  } catch (error) {
44
195
  if (error?.code === "ENOENT") return null
45
196
  throw error
46
197
  }
47
- let record = {}
48
198
  try {
49
- record = JSON.parse(fs.readFileSync(target, "utf8"))
50
- } catch {
51
- record = {}
199
+ const stat = fs.fstatSync(fd, { bigint: true })
200
+ let record = {}
201
+ try {
202
+ record = JSON.parse(fs.readFileSync(fd, "utf8"))
203
+ } catch {
204
+ record = {}
205
+ }
206
+ return {
207
+ id: typeof record.id === "string" ? record.id : "",
208
+ pid: Number(record.pid) || 0,
209
+ host: typeof record.host === "string" ? record.host : "",
210
+ since: typeof record.since === "string" ? record.since : "",
211
+ heartbeat: heartbeatOf(stat),
212
+ ino: stat.ino,
213
+ dev: stat.dev,
214
+ }
215
+ } finally {
216
+ fs.closeSync(fd)
52
217
  }
53
- return {
54
- id: typeof record.id === "string" ? record.id : "",
55
- pid: Number(record.pid) || 0,
56
- host: typeof record.host === "string" ? record.host : "",
57
- since: typeof record.since === "string" ? record.since : "",
58
- heartbeat: stat.mtimeMs,
218
+ }
219
+
220
+ /** Read a lock file this process has open: its record, or {} when it is damaged. */
221
+ function readOpen(fd) {
222
+ try {
223
+ return JSON.parse(fs.readFileSync(fd, "utf8"))
224
+ } catch {
225
+ return {}
59
226
  }
60
227
  }
61
228
 
@@ -66,9 +233,55 @@ export function createLease({ file, staleMs = LEASE_STALE_MS, now = Date.now, id
66
233
 
67
234
  const isStale = (lease) => now() - lease.heartbeat >= staleMs
68
235
 
69
- function touch(target) {
70
- const seconds = now() / 1000
71
- fs.utimesSync(target, seconds, seconds)
236
+ /** The record's pid, when it is a process id this machine may look up: 0 for none, damaged, or negative. */
237
+ function holderPid(lease) {
238
+ const value = lease?.pid
239
+ return Number.isSafeInteger(value) && value > 0 ? value : 0
240
+ }
241
+
242
+ /** Is `target` still the file this process has open? */
243
+ function stillAtPath(target, stat) {
244
+ try {
245
+ const current = statOf(target)
246
+ return current.ino === stat.ino && current.dev === stat.dev
247
+ } catch {
248
+ return false
249
+ }
250
+ }
251
+
252
+ /** Does pid's process still run? */
253
+ function running(holder) {
254
+ try {
255
+ process.kill(holder, 0)
256
+ return true
257
+ } catch (error) {
258
+ return error?.code === "EPERM"
259
+ }
260
+ }
261
+
262
+ /**
263
+ * Has this lease been abandoned? A pid is checked only against this machine's
264
+ * processes: another host's record (a hostname that changed, a container made
265
+ * again over a kept state directory), or one with no usable pid, is judged by
266
+ * its heartbeat alone, as it always was.
267
+ */
268
+ function abandoned(lease) {
269
+ const recorded = holderPid(lease)
270
+ if (!recorded || lease.host !== HOST) return true
271
+ if (!running(recorded)) return true
272
+ // This process's own pid on a lease it does not hold: the record's holder
273
+ // is gone and this process inherited its pid.
274
+ if (recorded === pid && lease.id !== id) return true
275
+ // A process that started after the lease was written cannot be its holder.
276
+ const began = startedAt(recorded)
277
+ if (Number.isFinite(began)) {
278
+ const since = Date.parse(lease.since)
279
+ const held = Number.isFinite(since) ? since : lease.heartbeat
280
+ if (began > held + START_SLACK_MS) return true
281
+ }
282
+ // A pid that still runs is otherwise kept: only a silence past the ceiling
283
+ // recovers it.
284
+ return now() - lease.heartbeat >= ceilingMs
72
285
  }
73
286
 
74
287
  function unlinkQuiet(target) {
@@ -79,16 +292,91 @@ export function createLease({ file, staleMs = LEASE_STALE_MS, now = Date.now, id
79
292
  }
80
293
  }
81
294
 
295
+ /** Report a step to the test seam (tests only: a crash at each step, and the takeover's gap). */
296
+ function step(name) {
297
+ onStep?.(name)
298
+ }
299
+
300
+ /**
301
+ * Is `fd` this holder's lease, as the name proves it? Its record must be this
302
+ * holder's and the name must still point at the very inode this holder
303
+ * created: the token, re-verified before every action the lease guards.
304
+ * Returns that stat, or null.
305
+ */
306
+ function holds(fd) {
307
+ const stat = fs.fstatSync(fd, { bigint: true })
308
+ if (readOpen(fd).id !== id) return null
309
+ if (mine && (stat.ino !== mine.ino || stat.dev !== mine.dev)) return null
310
+ return stillAtPath(file, stat) ? stat : null
311
+ }
312
+
313
+ /**
314
+ * Beat on the locked file itself: open it, prove through that open file that
315
+ * it is this holder's lease, set its times through that open file, then check
316
+ * the name still points at what was opened. A takeover between any two of
317
+ * those steps leaves this process without the lease.
318
+ */
319
+ function beat() {
320
+ let fd
321
+ try {
322
+ fd = fs.openSync(file, "r+")
323
+ } catch (error) {
324
+ if (error?.code === "ENOENT") return false
325
+ throw error
326
+ }
327
+ try {
328
+ const stat = holds(fd)
329
+ if (!stat) return false
330
+ step("beat")
331
+ const seconds = now() / 1000
332
+ fs.futimesSync(fd, seconds, seconds)
333
+ if (!stillAtPath(file, stat)) return false
334
+ mine = { dev: stat.dev, ino: stat.ino }
335
+ return true
336
+ } catch {
337
+ return false
338
+ } finally {
339
+ fs.closeSync(fd)
340
+ }
341
+ }
342
+
343
+ /**
344
+ * Is this process still the holder, without beating? The same proof as
345
+ * `beat()`: an action taken only after this passes was taken by the holder.
346
+ */
347
+ function held() {
348
+ let fd
349
+ try {
350
+ fd = fs.openSync(file, "r")
351
+ } catch {
352
+ return false
353
+ }
354
+ try {
355
+ return Boolean(holds(fd))
356
+ } catch {
357
+ return false
358
+ } finally {
359
+ fs.closeSync(fd)
360
+ }
361
+ }
362
+
82
363
  /** Create the lock without clobbering one that exists; true when this holder made it. */
83
364
  function create() {
84
365
  const temp = `${file}.${id}.tmp`
85
- fs.writeFileSync(temp, JSON.stringify({ id, pid, host: os.hostname(), since: new Date(now()).toISOString() }), { mode: 0o600 })
366
+ const at = now()
367
+ fs.writeFileSync(temp, JSON.stringify({ id, pid, host: HOST, since: new Date(at).toISOString() }), { mode: 0o600 })
86
368
  try {
87
- touch(temp)
369
+ fs.utimesSync(temp, at / 1000, at / 1000)
370
+ const stat = statOf(temp)
371
+ step("create-temp")
88
372
  fs.linkSync(temp, file)
373
+ mine = { dev: stat.dev, ino: stat.ino }
374
+ step("create")
89
375
  return true
90
376
  } catch (error) {
91
377
  if (error?.code === "EEXIST") return false
378
+ // No hard links here (FAT, exFAT, SMB without Unix extensions): refuse to
379
+ // hold the lease at all rather than guess.
92
380
  throw error
93
381
  } finally {
94
382
  unlinkQuiet(temp)
@@ -96,41 +384,205 @@ export function createLease({ file, staleMs = LEASE_STALE_MS, now = Date.now, id
96
384
  }
97
385
 
98
386
  /**
99
- * Hold the lease: keep it (refreshing the heartbeat) when this holder has it,
100
- * create it when nobody does, take it over when its heartbeat is stale.
387
+ * The takeover claim on one lease, named for the inode it would remove: the
388
+ * single arbiter of which taker may remove that inode, so no two takers of one
389
+ * stale lease can both get past it. The name carries no lease of its own; its
390
+ * record says whose attempt it is.
391
+ */
392
+ function claimName(lease) {
393
+ return `${file}.take-${lease.dev}-${lease.ino}`
394
+ }
395
+
396
+ /** Create the claim without clobbering another taker's; true when this taker made it. */
397
+ function claim(target) {
398
+ const temp = `${target}.${id}.tmp`
399
+ const at = now()
400
+ fs.writeFileSync(temp, JSON.stringify({ id, pid, host: HOST, since: new Date(at).toISOString() }), { mode: 0o600 })
401
+ try {
402
+ fs.utimesSync(temp, at / 1000, at / 1000)
403
+ fs.linkSync(temp, target)
404
+ return true
405
+ } catch (error) {
406
+ if (error?.code === "EEXIST") return false
407
+ throw error
408
+ } finally {
409
+ unlinkQuiet(temp)
410
+ }
411
+ }
412
+
413
+ /** Is the claim at `target` this taker's own? */
414
+ function claimed(target) {
415
+ try {
416
+ return readAt(target)?.id === id
417
+ } catch {
418
+ return false
419
+ }
420
+ }
421
+
422
+ function dropClaim(target) {
423
+ if (claimed(target)) unlinkQuiet(target)
424
+ }
425
+
426
+ /**
427
+ * Has the owner of a file beside the lock gone? One of these is a claim, a
428
+ * temp file, or an aside an older build left: its record names the process
429
+ * that made it. It is judged exactly as a lease's holder is, and only that
430
+ * way: the pid no longer runs, or the pid now belongs to a process that
431
+ * started after the file was written. **Never by age** for a pid this machine
432
+ * can judge — a live taker that was stopped mid-takeover is indistinguishable
433
+ * from a slow one, and removing its claim is how a second taker gets past it
434
+ * (the residual above). A record this machine cannot judge at all — another
435
+ * host's, a damaged one, or a pid whose start time cannot be read (Windows
436
+ * has no `ps` and no `/proc`) — ages out at the lease ceiling, so no file can
437
+ * outlive every judgement.
438
+ */
439
+ function gone(record) {
440
+ if (!record) return true
441
+ const recorded = holderPid(record)
442
+ if (recorded && record.host === HOST) {
443
+ if (!running(recorded)) return true
444
+ const began = startedAt(recorded)
445
+ const since = Date.parse(record.since)
446
+ // An unreadable start time makes the pid unjudgeable: age it out rather
447
+ // than let a reused pid block the lock for as long as it lives.
448
+ if (!Number.isFinite(began) || !Number.isFinite(since)) return now() - record.heartbeat >= ceilingMs
449
+ return began > since + START_SLACK_MS
450
+ }
451
+ return now() - record.heartbeat >= ceilingMs
452
+ }
453
+
454
+ /**
455
+ * Remove a file beside the lock only while it is still the very file judged
456
+ * gone: another taker may have removed that one and linked its own in the
457
+ * meantime, and that live claim is not this process's to remove. This narrows
458
+ * the residual to one syscall gap (the stat below and the unlink).
459
+ */
460
+ function dropGone(target, judged) {
461
+ if (!judged) return false
462
+ try {
463
+ const current = readAt(target)
464
+ if (!current || current.ino !== judged.ino || current.dev !== judged.dev) return false
465
+ if (!gone(current)) return false
466
+ step("gone")
467
+ fs.unlinkSync(target)
468
+ return true
469
+ } catch {
470
+ return false
471
+ }
472
+ }
473
+
474
+ /**
475
+ * Win the right to remove this one stale lease, or stand down. `link` is
476
+ * no-clobber, so of any number of takers that judged the same lease exactly
477
+ * one holds the claim; a claim whose taker died is recovered, a live taker's
478
+ * is never touched.
479
+ */
480
+ function takeClaim(lease) {
481
+ const target = claimName(lease)
482
+ for (let attempt = 0; attempt < 2; attempt++) {
483
+ if (claim(target)) return target
484
+ const judged = readAt(target)
485
+ // Gone under this taker already: race for the claim once more.
486
+ if (!judged) continue
487
+ // Another taker's claim, and its taker is alive: stand down.
488
+ if (!gone(judged)) return null
489
+ // Its taker is provably dead: remove that very file and race for the
490
+ // claim again. A competing sweeper may take the removal first, or may
491
+ // have linked its own claim, and then this backs off.
492
+ if (!dropGone(target, judged)) return null
493
+ }
494
+ return null
495
+ }
496
+
497
+ /**
498
+ * Remove what an interrupted attempt of any process left beside the lock —
499
+ * a takeover claim, a temp file, an aside a build before this one made. A
500
+ * file whose owner is alive is left alone, whatever its age: only a provably
501
+ * dead owner frees one. This is what keeps crash recovery from leaving a
502
+ * stray file: the next start removes it.
503
+ */
504
+ function sweep() {
505
+ let names
506
+ try {
507
+ names = fs.readdirSync(dir)
508
+ } catch {
509
+ return
510
+ }
511
+ for (const name of names) {
512
+ if (name === base || !name.startsWith(`${base}.`)) continue
513
+ const target = path.join(dir, name)
514
+ let record = null
515
+ try {
516
+ record = readAt(target)
517
+ } catch {
518
+ record = null
519
+ }
520
+ if (!record || !gone(record)) continue
521
+ dropGone(target, record)
522
+ }
523
+ }
524
+
525
+ /**
526
+ * Hold the lease: keep it (beating) when this holder has it, create it when
527
+ * nobody does, take it over when its holder has abandoned it.
101
528
  *
102
529
  * @returns {{ owned: true, took?: "free" | "stale" } | { owned: false, holder: ReturnType<typeof holder> }}
103
530
  */
104
531
  function acquire() {
105
532
  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
106
- const current = holder()
533
+ sweep()
534
+ let current = holder()
107
535
  if (current && current.id === id) {
108
- touch(file)
109
- return { owned: true }
536
+ if (beat()) return { owned: true }
537
+ // Lost between the read and the beat (another process took the lease):
538
+ // judge the lock as it stands now, not the record that was read.
539
+ current = holder()
110
540
  }
111
541
  if (current && !isStale(current)) return { owned: false, holder: current }
542
+ if (current && !abandoned(current)) {
543
+ log?.info?.("collector lease left alone: its holder process is running", { pid: current.pid })
544
+ return { owned: false, holder: current }
545
+ }
112
546
  if (current) {
113
547
  onStale?.(current)
114
- const aside = `${file}.stale-${id}`
115
- try {
116
- fs.renameSync(file, aside)
117
- } catch (error) {
118
- if (error?.code !== "ENOENT") throw error
548
+ // One taker at a time per stale lease, keyed on the inode to be removed:
549
+ // two takers of one lease can never both get past this, so the gap
550
+ // between a taker's stat and its unlink is entered by one process only.
551
+ const target = takeClaim(current)
552
+ if (!target) {
553
+ log?.debug?.("collector lease takeover is another process's", { pid: current.pid })
554
+ return { owned: false, holder: holder() ?? current }
119
555
  }
120
- const moved = readAt(aside)
121
- if (moved && (moved.id !== current.id || moved.heartbeat !== current.heartbeat)) {
122
- // Someone took the stale lease, or its holder beat, between the read
123
- // and the rename: give it back unless the name is already taken again.
124
- try {
125
- fs.linkSync(aside, file)
126
- } catch {
127
- /* the name was taken again; that holder stands */
556
+ step("claim")
557
+ let removed = false
558
+ let replaced = false
559
+ try {
560
+ // Still the very lease this taker judged, and still this taker's to
561
+ // remove? A holder that beat, a taker that won first, or a claim that
562
+ // was taken from a taker thought dead all stand.
563
+ const again = readAt(file)
564
+ if (again) {
565
+ if (again.id !== current.id || again.ino !== current.ino || again.heartbeat !== current.heartbeat || !claimed(target)) {
566
+ replaced = true
567
+ } else {
568
+ const at = statOf(file)
569
+ if (at.ino === current.ino && at.dev === current.dev) {
570
+ step("stat")
571
+ fs.unlinkSync(file)
572
+ step("unlink")
573
+ removed = true
574
+ } else {
575
+ replaced = true
576
+ }
577
+ }
128
578
  }
129
- unlinkQuiet(aside)
130
- return { owned: false, holder: holder() ?? moved }
579
+ } catch {
580
+ /* the name went away under this taker: create() decides who wins */
581
+ } finally {
582
+ dropClaim(target)
131
583
  }
132
- unlinkQuiet(aside)
133
- if (moved) log?.info?.("collector lease taken over from a stopped process", { pid: moved.pid })
584
+ if (replaced) return { owned: false, holder: holder() ?? current }
585
+ if (removed) log?.info?.("collector lease taken over from a stopped process", { pid: current.pid })
134
586
  }
135
587
  if (create()) return { owned: true, took: current ? "stale" : "free" }
136
588
  return { owned: false, holder: holder() }
@@ -139,24 +591,43 @@ export function createLease({ file, staleMs = LEASE_STALE_MS, now = Date.now, id
139
591
  /** Refresh the heartbeat; false when the lease is no longer this holder's. */
140
592
  function heartbeat() {
141
593
  try {
142
- const current = holder()
143
- if (!current || current.id !== id) return false
144
- touch(file)
145
- return true
594
+ return beat()
146
595
  } catch {
147
596
  return false
148
597
  }
149
598
  }
150
599
 
151
- /** Give the lease up, if this holder still has it. */
600
+ /**
601
+ * Give the lease up, only while it is still this holder's: the record is read
602
+ * through this process's own open file, the name must still point at the very
603
+ * inode this holder created, and it is never moved or removed to find out
604
+ * whose it is.
605
+ */
152
606
  function release() {
607
+ let fd
153
608
  try {
154
- const current = holder()
155
- if (current && current.id === id) fs.unlinkSync(file)
609
+ fd = fs.openSync(file, "r+")
610
+ } catch {
611
+ return
612
+ }
613
+ try {
614
+ const stat = fs.fstatSync(fd, { bigint: true })
615
+ if (readOpen(fd).id !== id) return
616
+ if (mine && (stat.ino !== mine.ino || stat.dev !== mine.dev)) return
617
+ // A taker takes only an abandoned lease, and this process is running:
618
+ // its lease changes hands only if this check and the unlink straddle a
619
+ // clock jump past the ceiling — the inode check makes that the one
620
+ // window, and it is the smallest one these calls allow.
621
+ if (!stillAtPath(file, stat)) return
622
+ step("release")
623
+ fs.unlinkSync(file)
624
+ mine = null
156
625
  } catch {
157
626
  /* nothing to release */
627
+ } finally {
628
+ fs.closeSync(fd)
158
629
  }
159
630
  }
160
631
 
161
- return { id, file, acquire, heartbeat, release, holder, isStale }
632
+ return { id, file, acquire, heartbeat, release, holder, isStale, held }
162
633
  }