@holmes-lab/holmes-kit 0.35.20 → 0.35.22
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/CHANGELOG.md +79 -0
- package/README.md +2 -2
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/doctor.d.ts +35 -0
- package/dist/holmes/cli/doctor.js +278 -1
- package/dist/holmes/cli/runtime-binding.js +190 -174
- package/dist/holmes/cli/settings-merge.d.ts +1 -0
- package/dist/holmes/cli/settings-merge.js +6 -2
- package/dist/holmes/cpg/scan-cache.d.ts +1 -0
- package/dist/holmes/cpg/scan-cache.js +11 -0
- package/dist/holmes/hooks/rtm-refresh-child.d.ts +16 -0
- package/dist/holmes/hooks/rtm-refresh-child.js +49 -15
- package/dist/holmes/hooks/rtm-refresh.d.ts +22 -0
- package/dist/holmes/hooks/rtm-refresh.js +117 -13
- package/dist/holmes/mcp/handlers/graph-operations.js +7 -4
- package/dist/holmes/mcp/handlers/requirement-triage.js +6 -2
- package/dist/holmes/mcp/requirement-triage-evidence.d.ts +7 -0
- package/dist/holmes/mcp/requirement-triage-evidence.js +18 -7
- package/dist/holmes/project/bounded-io.d.ts +1 -0
- package/dist/holmes/project/bounded-io.js +3 -1
- package/dist/holmes/refresh/freshness-coordinator.d.ts +15 -0
- package/dist/holmes/refresh/freshness-coordinator.js +46 -3
- package/package.json +1 -1
|
@@ -39,13 +39,15 @@ exports.recordRefreshFailure = recordRefreshFailure;
|
|
|
39
39
|
exports.armWorkerDeadline = armWorkerDeadline;
|
|
40
40
|
exports.lowerOwnPriority = lowerOwnPriority;
|
|
41
41
|
exports.armSupersedeWatch = armSupersedeWatch;
|
|
42
|
+
exports.armRefreshWorkerTimers = armRefreshWorkerTimers;
|
|
42
43
|
exports.runRefreshChild = runRefreshChild;
|
|
43
44
|
exports.defaultRefreshChildDeps = defaultRefreshChildDeps;
|
|
44
|
-
// @implements A-SPEC-719, A-SPEC-734
|
|
45
|
+
// @implements A-SPEC-719, A-SPEC-734, A-SPEC-719.7
|
|
45
46
|
// @implements A-SPEC-566.4
|
|
46
47
|
// @implements A-SPEC-768.4
|
|
47
48
|
// @implements A-SPEC-719.1
|
|
48
49
|
// @implements A-SPEC-719.2
|
|
50
|
+
// @implements A-SPEC-719.6
|
|
49
51
|
// @implements A-SPEC-769.9
|
|
50
52
|
/**
|
|
51
53
|
* The detached refresh child — the ONLY place this slice touches the scan/build machinery. Spawned
|
|
@@ -57,15 +59,30 @@ const fs = __importStar(require("node:fs"));
|
|
|
57
59
|
const os = __importStar(require("node:os"));
|
|
58
60
|
const path = __importStar(require("node:path"));
|
|
59
61
|
const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
|
|
60
|
-
const
|
|
62
|
+
const probeHead = (root) => {
|
|
61
63
|
try {
|
|
62
|
-
const {
|
|
63
|
-
|
|
64
|
+
const { headProbe } = require('./rtm-refresh');
|
|
65
|
+
const { GIT_TIMEOUT_MS } = require('../project/bounded-io');
|
|
66
|
+
// @implements A-SPEC-719.6 — the worker's own scan may have timed out a git call on this root: ask anyway, with
|
|
67
|
+
// the ordinary 5 s bound, rather than be skipped by the memory and publish every finished refresh `retry-at`.
|
|
68
|
+
return headProbe(root, { timeoutMs: GIT_TIMEOUT_MS, ignoreBlock: true });
|
|
64
69
|
}
|
|
65
70
|
catch {
|
|
66
|
-
return null;
|
|
71
|
+
return { head: null, unanswered: true };
|
|
67
72
|
}
|
|
68
73
|
};
|
|
74
|
+
const currentHead = (root) => probeHead(root).head;
|
|
75
|
+
/**
|
|
76
|
+
* @implements A-SPEC-719.5 — the head a completion is written against. When git did not answer, the lease's own head:
|
|
77
|
+
* a mismatch would publish `stale` (no retry pause) and throw a finished refresh away; `retry-at` paces the retry.
|
|
78
|
+
*/
|
|
79
|
+
function completionHead(root, generation, probe) {
|
|
80
|
+
const p = probe(root);
|
|
81
|
+
if (!p.unanswered)
|
|
82
|
+
return p;
|
|
83
|
+
const leased = (0, freshness_coordinator_1.leaseHead)(root, generation);
|
|
84
|
+
return { head: leased === undefined ? null : leased, unanswered: true };
|
|
85
|
+
}
|
|
69
86
|
// @implements A-SPEC-768.4
|
|
70
87
|
/** The error as a bounded reason: its message (never a stack), at most REFRESH_FAILURE_REASON_MAX characters. */
|
|
71
88
|
function failureReason(error) {
|
|
@@ -87,7 +104,7 @@ function recordRefreshFailure(root, generation, head, now, failure) {
|
|
|
87
104
|
function armWorkerDeadline(root, generation, opts) {
|
|
88
105
|
const timer = setTimeout(() => {
|
|
89
106
|
try {
|
|
90
|
-
recordRefreshFailure(root, generation,
|
|
107
|
+
recordRefreshFailure(root, generation, completionHead(root, generation, probeHead).head, (opts.now ?? (() => new Date()))(), { stage: 'child', reason: `worker exceeded ${opts.ms} ms` });
|
|
91
108
|
}
|
|
92
109
|
catch { /* fail-soft: ending is what matters */ }
|
|
93
110
|
opts.exit();
|
|
@@ -115,7 +132,9 @@ function lowerOwnPriority(setPriority = (p) => os.setPriority(p)) {
|
|
|
115
132
|
* 2026-10-15: nine superseded jarvis workers kept embedding for 2–4 h because the lease was asked only between phases.
|
|
116
133
|
*/
|
|
117
134
|
function armSupersedeWatch(root, generation, opts) {
|
|
118
|
-
|
|
135
|
+
// @implements A-SPEC-719.4 — by default only a readable newer lease or a removed workspace ends the worker:
|
|
136
|
+
// `ownsLease` read a missing or unreadable receipt as "not owned" and ended live workers on a transient read.
|
|
137
|
+
const owns = opts.owns ?? ((r, g) => !(0, freshness_coordinator_1.leaseSuperseded)(r, g));
|
|
119
138
|
const timer = setInterval(() => {
|
|
120
139
|
let current = true;
|
|
121
140
|
try {
|
|
@@ -123,7 +142,7 @@ function armSupersedeWatch(root, generation, opts) {
|
|
|
123
142
|
}
|
|
124
143
|
catch {
|
|
125
144
|
current = true;
|
|
126
|
-
} //
|
|
145
|
+
} // a throwing check is not a supersession
|
|
127
146
|
if (current)
|
|
128
147
|
return;
|
|
129
148
|
clearInterval(timer);
|
|
@@ -131,6 +150,15 @@ function armSupersedeWatch(root, generation, opts) {
|
|
|
131
150
|
}, opts.intervalMs);
|
|
132
151
|
timer.unref?.();
|
|
133
152
|
}
|
|
153
|
+
/**
|
|
154
|
+
* @implements A-SPEC-719.5 — the worker's two timers, armed as one tested unit: the deadline inside the lease cap
|
|
155
|
+
* (A-SPEC-719.1/719.4) and the supersede watch (A-SPEC-719.2). The main block calls only this.
|
|
156
|
+
*/
|
|
157
|
+
function armRefreshWorkerTimers(root, generation, deps = {}) {
|
|
158
|
+
const exit = deps.exit ?? (() => process.exit(0));
|
|
159
|
+
(deps.deadline ?? armWorkerDeadline)(root, generation, { ms: freshness_coordinator_1.FRESHNESS_WORKER_DEADLINE_MS, exit });
|
|
160
|
+
(deps.watch ?? armSupersedeWatch)(root, generation, { intervalMs: exports.REFRESH_SUPERSEDE_POLL_MS, exit });
|
|
161
|
+
}
|
|
134
162
|
/**
|
|
135
163
|
* One refresh run for one lease generation. Every phase that writes is preceded by a lease check,
|
|
136
164
|
* so a superseded worker, or one whose root was removed, stops without writing (A-SPEC-724). Any
|
|
@@ -171,19 +199,28 @@ async function runRefreshChild(root, generation, deps) {
|
|
|
171
199
|
requirement = { status: 'unavailable' };
|
|
172
200
|
failure ??= { stage: 'requirement', reason: failureReason(error) };
|
|
173
201
|
}
|
|
202
|
+
const final = completionHead(root, generation, deps.headProbe ?? ((r) => ({ head: deps.head(r), unanswered: false })));
|
|
203
|
+
// A-SPEC-719.5 — retry after the pause rather than publish `stale`; A-SPEC-719.7 — only when the lease named a commit:
|
|
204
|
+
// a lease taken under a git that refused completes under null as 0.35.20 did (a git that refuses for good would
|
|
205
|
+
// otherwise keep intake refused and re-run the whole refresh every pause).
|
|
206
|
+
if (final.unanswered && final.head !== null) {
|
|
207
|
+
recordRefreshFailure(root, generation, final.head, new Date(), { stage: 'child', reason: 'git did not answer for HEAD at completion' });
|
|
208
|
+
return;
|
|
209
|
+
}
|
|
174
210
|
(0, freshness_coordinator_1.completeRefresh)(root, generation, {
|
|
175
211
|
graph: 'current',
|
|
176
212
|
sourceSemantic: source.lane,
|
|
177
213
|
requirementSemantic: requirement.status === 'discharged' ? 'current'
|
|
178
214
|
: requirement.status === 'not-applicable' ? 'not-adopted'
|
|
179
215
|
: requirement.status === 'suppressed' ? 'suppressed' : 'failed',
|
|
180
|
-
head:
|
|
216
|
+
head: final.head,
|
|
181
217
|
...(failure ? { failure } : {}),
|
|
182
218
|
}, new Date());
|
|
183
219
|
}
|
|
184
220
|
catch (error) {
|
|
185
221
|
try {
|
|
186
|
-
|
|
222
|
+
const head = completionHead(root, generation, deps.headProbe ?? ((r) => ({ head: deps.head(r), unanswered: false }))).head;
|
|
223
|
+
recordRefreshFailure(root, generation, head, new Date(), { stage, reason: failureReason(error) });
|
|
187
224
|
}
|
|
188
225
|
catch { /* fail-soft */ }
|
|
189
226
|
}
|
|
@@ -195,6 +232,7 @@ function defaultRefreshChildDeps(env = process.env) {
|
|
|
195
232
|
const suppressed = typeof env.HOLMES_NO_SEMANTIC_WARM === 'string' && env.HOLMES_NO_SEMANTIC_WARM !== '';
|
|
196
233
|
return {
|
|
197
234
|
head: currentHead,
|
|
235
|
+
headProbe: probeHead,
|
|
198
236
|
refreshGraph: async (root) => {
|
|
199
237
|
const { makeHandlers } = require('../mcp/handlers');
|
|
200
238
|
const { LocalMarkdownRepository } = require('../spec/spec-store');
|
|
@@ -227,12 +265,8 @@ if (require.main === module) {
|
|
|
227
265
|
const root = process.argv[2];
|
|
228
266
|
const generation = process.argv[3];
|
|
229
267
|
lowerOwnPriority(); // A-SPEC-719.2 — background work yields to foreground sessions
|
|
230
|
-
// @implements A-SPEC-719.1 — never outlive the lease cap
|
|
231
|
-
if (root && generation)
|
|
232
|
-
armWorkerDeadline(root, generation, { ms: freshness_coordinator_1.FRESHNESS_WORKER_MAX_MS, exit: () => process.exit(0) });
|
|
233
|
-
// @implements A-SPEC-719.2 — end promptly once superseded
|
|
234
268
|
if (root && generation)
|
|
235
|
-
|
|
269
|
+
armRefreshWorkerTimers(root, generation);
|
|
236
270
|
// fail-soft: a failed refresh leaves the old graph, which the advisory tolerates
|
|
237
271
|
if (root && generation)
|
|
238
272
|
void runRefreshChild(root, generation, defaultRefreshChildDeps()).catch(() => undefined);
|
|
@@ -1,3 +1,18 @@
|
|
|
1
|
+
/** @implements A-SPEC-719.9 — 0.35.20's lease probe bound: an answer slower than this is remembered as a timeout. */
|
|
2
|
+
export declare const LEASE_SLOW_GIT_MS = 2000;
|
|
3
|
+
/** Test seam: forget every remembered slow-read head. */
|
|
4
|
+
export declare function forgetSlowLeaseHeads(): void;
|
|
5
|
+
/**
|
|
6
|
+
* Same resolution as the child's `headOf`: full commit id, or null outside a repository.
|
|
7
|
+
* @implements A-SPEC-734 (round 13) — through the per-kind memory: a root whose git already timed out is not asked.
|
|
8
|
+
*/
|
|
9
|
+
export declare function headProbe(root: string, opts?: {
|
|
10
|
+
timeoutMs?: number;
|
|
11
|
+
ignoreBlock?: boolean;
|
|
12
|
+
}): {
|
|
13
|
+
head: string | null;
|
|
14
|
+
unanswered: boolean;
|
|
15
|
+
};
|
|
1
16
|
/** @deprecated A compatibility observation interval; receipt leases are the source of truth. */
|
|
2
17
|
export declare const RTM_REFRESH_TTL_MS: number;
|
|
3
18
|
export declare const RTM_REFRESH_MARKER: string;
|
|
@@ -12,6 +27,13 @@ export interface RtmRefreshOpts {
|
|
|
12
27
|
};
|
|
13
28
|
ttlMs?: number;
|
|
14
29
|
head?: string | null;
|
|
30
|
+
/** @implements A-SPEC-719.4 — test seam for the HEAD probe used when `head` is not given. */
|
|
31
|
+
headProbe?: (root: string, opts?: {
|
|
32
|
+
ignoreBlock?: boolean;
|
|
33
|
+
}) => {
|
|
34
|
+
head: string | null;
|
|
35
|
+
unanswered: boolean;
|
|
36
|
+
};
|
|
15
37
|
}
|
|
16
38
|
export type FreshnessBridgeObservation = {
|
|
17
39
|
status: 'spawned';
|
|
@@ -33,11 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
-
exports.RTM_REFRESH_MARKER = exports.RTM_REFRESH_TTL_MS = void 0;
|
|
36
|
+
exports.RTM_REFRESH_MARKER = exports.RTM_REFRESH_TTL_MS = exports.LEASE_SLOW_GIT_MS = void 0;
|
|
37
|
+
exports.forgetSlowLeaseHeads = forgetSlowLeaseHeads;
|
|
38
|
+
exports.headProbe = headProbe;
|
|
37
39
|
exports.maybeSpawnRtmRefresh = maybeSpawnRtmRefresh;
|
|
38
40
|
exports.requestBackgroundFreshness = requestBackgroundFreshness;
|
|
39
41
|
// @implements A-SPEC-724, A-SPEC-723, A-SPEC-719, A-SPEC-734
|
|
40
|
-
// @implements A-SPEC-719.1
|
|
42
|
+
// @implements A-SPEC-719.1, A-SPEC-719.4, A-SPEC-719.5, A-SPEC-719.6, A-SPEC-719.8, A-SPEC-719.9, A-SPEC-719.10, A-SPEC-719.11, A-SPEC-719.12, A-SPEC-719.13
|
|
41
43
|
/**
|
|
42
44
|
* Graph freshness, kept by the product itself. The impact advisory's quality factor was MEASURED to
|
|
43
45
|
* be staleness (an 8-day-old graph found 7 advisories; a 1-second reindex found 17), so the Stop
|
|
@@ -49,17 +51,51 @@ const fs = __importStar(require("node:fs"));
|
|
|
49
51
|
const path = __importStar(require("node:path"));
|
|
50
52
|
const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
|
|
51
53
|
const bounded_io_1 = require("../project/bounded-io");
|
|
54
|
+
/** @implements A-SPEC-719.9 — 0.35.20's lease probe bound: an answer slower than this is remembered as a timeout. */
|
|
55
|
+
exports.LEASE_SLOW_GIT_MS = 2000;
|
|
56
|
+
/**
|
|
57
|
+
* @implements A-SPEC-719.10 — the head a slow lease read answered, per root, for as long as that read keeps the
|
|
58
|
+
* root's repo git blocked: the MCP bridge's next request finds its probe skipped and would lease null — a new
|
|
59
|
+
* refresh against a receipt already current at the commit, each time the previous one ended (0.35.20's storm).
|
|
60
|
+
*/
|
|
61
|
+
const SLOW_LEASE_HEADS = new Map();
|
|
62
|
+
const SLOW_LEASE_HEAD_MS = 60_000;
|
|
63
|
+
/** Test seam: forget every remembered slow-read head. */
|
|
64
|
+
function forgetSlowLeaseHeads() { SLOW_LEASE_HEADS.clear(); }
|
|
65
|
+
/** @implements A-SPEC-719.11 — the key bounded-io's git-timeout memory uses: an alias resolves to the same entry. */
|
|
66
|
+
const slowLeaseKey = (root) => {
|
|
67
|
+
try {
|
|
68
|
+
return fs.realpathSync.native(root);
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
return path.resolve(root);
|
|
72
|
+
}
|
|
73
|
+
};
|
|
52
74
|
/**
|
|
53
75
|
* Same resolution as the child's `headOf`: full commit id, or null outside a repository.
|
|
54
76
|
* @implements A-SPEC-734 (round 13) — through the per-kind memory: a root whose git already timed out is not asked.
|
|
55
77
|
*/
|
|
56
|
-
function
|
|
78
|
+
function headProbe(root, opts = {}) {
|
|
57
79
|
try {
|
|
58
|
-
|
|
59
|
-
|
|
80
|
+
// @implements A-SPEC-719.5 — `--verify -q` exits 1 silently for an unborn HEAD, so a refusal (128: dubious
|
|
81
|
+
// ownership, an unknown extension, a broken gitdir) is told apart from a repository with no commit yet.
|
|
82
|
+
// @implements A-SPEC-719.8 — the lease waits as long as the worker and intake do (5 s): at 2 s a git answering in
|
|
83
|
+
// 2–5 s leased a null head, the worker completed against the commit as `stale`, and every request spawned anew.
|
|
84
|
+
const r = (0, bounded_io_1.gitOnce)(root, ['-C', root, 'rev-parse', '--verify', '-q', 'HEAD'], 'repo', { timeout: opts.timeoutMs ?? bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: opts.ignoreBlock });
|
|
85
|
+
if (r.status === 0 && r.error === undefined)
|
|
86
|
+
return { head: r.stdout.trim() || null, unanswered: false };
|
|
87
|
+
// @implements A-SPEC-719.4 — no exit status (timed out, killed, or skipped by the per-kind memory) is not "no
|
|
88
|
+
// repository": a null head would lease a generation the live worker's HEAD never matches, every request.
|
|
89
|
+
if (r.error?.code === 'ENOENT')
|
|
90
|
+
return { head: null, unanswered: false };
|
|
91
|
+
if (!(0, bounded_io_1.gitEntryAbove)(root))
|
|
92
|
+
return { head: null, unanswered: false }; // the tree says: no repository
|
|
93
|
+
if (r.status === 1)
|
|
94
|
+
return { head: null, unanswered: false }; // a repository with an unborn HEAD
|
|
95
|
+
return { head: null, unanswered: true };
|
|
60
96
|
}
|
|
61
97
|
catch {
|
|
62
|
-
return null;
|
|
98
|
+
return { head: null, unanswered: true };
|
|
63
99
|
} // bounded: a hung git must never hold the Stop hook
|
|
64
100
|
}
|
|
65
101
|
/** @deprecated A compatibility observation interval; receipt leases are the source of truth. */
|
|
@@ -77,9 +113,68 @@ function maybeSpawnRtmRefresh(opts) {
|
|
|
77
113
|
return { status: 'failed' }; // nothing to refresh
|
|
78
114
|
// The lease must name the HEAD the child completes against (A-SPEC-719): a null lease in a git
|
|
79
115
|
// workspace could only ever complete as stale, so intake would never see current evidence.
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
116
|
+
let head;
|
|
117
|
+
// @implements A-SPEC-719.11 — the lease time follows the probe: stamped before a probe that waits for git, a refresh
|
|
118
|
+
// completing meanwhile looked "completed in the future" and every such request spawned again (also in 0.35.20).
|
|
119
|
+
const started = Date.now();
|
|
120
|
+
let now = opts.now;
|
|
121
|
+
const workspaceId = (0, freshness_coordinator_1.workspaceIdFor)(opts.root);
|
|
122
|
+
if (opts.head !== undefined)
|
|
123
|
+
head = opts.head;
|
|
124
|
+
else {
|
|
125
|
+
const read = opts.headProbe ?? headProbe;
|
|
126
|
+
// @implements A-SPEC-719.11 — keyed as the git-timeout memory is, so an alias spelling finds the remembered head.
|
|
127
|
+
const key = slowLeaseKey(opts.root);
|
|
128
|
+
// @implements A-SPEC-719.9 — a read that answered only past 0.35.20's 2 s bound is remembered as that timeout
|
|
129
|
+
// was, so the caller's later git reads (the Stop hook's evaluation) skip instead of each waiting for this git.
|
|
130
|
+
const remember = (probe, from) => {
|
|
131
|
+
if (probe.unanswered)
|
|
132
|
+
return;
|
|
133
|
+
if (Date.now() - from >= exports.LEASE_SLOW_GIT_MS) {
|
|
134
|
+
(0, bounded_io_1.noteGitFailure)(opts.root, { code: 'ETIMEDOUT' }, 'repo');
|
|
135
|
+
SLOW_LEASE_HEADS.set(key, { head: probe.head, at: Date.now() });
|
|
136
|
+
// @implements A-SPEC-719.13 — while the root's git is still blocked, later probes are skipped: keep the head
|
|
137
|
+
// this fast answer gave (forgetting it leased null, and the worker completed stale, for the rest of the minute).
|
|
138
|
+
}
|
|
139
|
+
else if ((0, bounded_io_1.gitRootBlocked)(opts.root, 'repo'))
|
|
140
|
+
SLOW_LEASE_HEADS.set(key, { head: probe.head, at: Date.now() });
|
|
141
|
+
else
|
|
142
|
+
SLOW_LEASE_HEADS.delete(key);
|
|
143
|
+
};
|
|
144
|
+
const probe = read(opts.root);
|
|
145
|
+
remember(probe, started);
|
|
146
|
+
head = probe.head;
|
|
147
|
+
if (probe.unanswered) {
|
|
148
|
+
// @implements A-SPEC-719.6 — join a live lease rather than supersede it (the 719.4 defect); with none, lease a
|
|
149
|
+
// null head as 0.35.20 did, so a git that refuses for good still refreshes.
|
|
150
|
+
const live = (0, freshness_coordinator_1.leaseLive)(opts.root, new Date(now));
|
|
151
|
+
if (live !== null)
|
|
152
|
+
return { status: 'coalesced', generation: live.generation };
|
|
153
|
+
// @implements A-SPEC-719.10 — within the minute, the head this process's slow read answered.
|
|
154
|
+
const remembered = SLOW_LEASE_HEADS.get(key);
|
|
155
|
+
const age = remembered === undefined ? NaN : Date.now() - remembered.at;
|
|
156
|
+
head = remembered !== undefined && age >= 0 && age < SLOW_LEASE_HEAD_MS ? remembered.head : null;
|
|
157
|
+
// @implements A-SPEC-719.11 — a receipt the worker wrote `stale` at the remembered head says HEAD moved: leased
|
|
158
|
+
// again, that head re-spawned the refresh on every request of the minute. Read once more past the memory.
|
|
159
|
+
if (remembered !== undefined && head === remembered.head
|
|
160
|
+
&& (0, freshness_coordinator_1.readFreshnessReceipt)(opts.root, { workspaceId, head, now: new Date(now) })?.state === 'stale') {
|
|
161
|
+
SLOW_LEASE_HEADS.delete(key);
|
|
162
|
+
const again = Date.now();
|
|
163
|
+
const fresh = read(opts.root, { ignoreBlock: true });
|
|
164
|
+
remember(fresh, again);
|
|
165
|
+
head = fresh.unanswered ? null : fresh.head;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
// @implements A-SPEC-719.12 — only a completion stamped inside this request's own wait moves its time; the
|
|
169
|
+
// caller's clock stands otherwise (719.11 added the whole wait, and an exact TTL boundary drifted by the probe).
|
|
170
|
+
const waited = Date.now() - started;
|
|
171
|
+
if (waited > 0) {
|
|
172
|
+
const done = Date.parse((0, freshness_coordinator_1.readFreshnessReceipt)(opts.root, { workspaceId, head, now: new Date(opts.now) })?.completedAt ?? '');
|
|
173
|
+
if (Number.isFinite(done) && done > opts.now && done <= opts.now + waited)
|
|
174
|
+
now = opts.now + waited;
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
const decision = (0, freshness_coordinator_1.requestRefresh)(opts.root, { workspaceId, head, now: new Date(now) });
|
|
83
178
|
if (!decision.spawn)
|
|
84
179
|
return { status: 'coalesced', generation: decision.receipt.generation };
|
|
85
180
|
// Retained only for tools that still display the former marker. The receipt
|
|
@@ -87,12 +182,21 @@ function maybeSpawnRtmRefresh(opts) {
|
|
|
87
182
|
const marker = path.join(opts.root, exports.RTM_REFRESH_MARKER);
|
|
88
183
|
try {
|
|
89
184
|
fs.mkdirSync(path.dirname(marker), { recursive: true });
|
|
90
|
-
fs.writeFileSync(marker, String(
|
|
91
|
-
fs.utimesSync(marker, new Date(
|
|
185
|
+
fs.writeFileSync(marker, String(now));
|
|
186
|
+
fs.utimesSync(marker, new Date(now), new Date(now));
|
|
92
187
|
}
|
|
93
188
|
catch { /* an unwritable marker is not a reason to skip the refresh itself */ }
|
|
94
189
|
try {
|
|
95
|
-
const
|
|
190
|
+
const fail = () => (0, freshness_coordinator_1.completeRefresh)(opts.root, decision.receipt.generation, {
|
|
191
|
+
graph: 'failed', sourceSemantic: 'failed', requirementSemantic: 'failed', head: decision.receipt.head,
|
|
192
|
+
}, new Date(now));
|
|
193
|
+
const child = opts.spawn(opts.execPath, [opts.scriptPath, opts.root, decision.receipt.generation], { detached: true, stdio: 'ignore', windowsHide: true });
|
|
194
|
+
// @implements A-SPEC-719.4 — ENOENT/EAGAIN arrive as an 'error' event on the next tick, not a throw: unheard,
|
|
195
|
+
// it ended the MCP server or the Stop hook and left a pid-less `refreshing` lease.
|
|
196
|
+
child?.on?.('error', () => { try {
|
|
197
|
+
fail();
|
|
198
|
+
}
|
|
199
|
+
catch { /* fail-soft */ } });
|
|
96
200
|
child?.unref?.();
|
|
97
201
|
// @implements A-SPEC-719.1 — the lease names its worker, so a live refresh is not taken for a crashed one.
|
|
98
202
|
if (typeof child?.pid === 'number') {
|
|
@@ -106,7 +210,7 @@ function maybeSpawnRtmRefresh(opts) {
|
|
|
106
210
|
catch {
|
|
107
211
|
(0, freshness_coordinator_1.completeRefresh)(opts.root, decision.receipt.generation, {
|
|
108
212
|
graph: 'failed', sourceSemantic: 'failed', requirementSemantic: 'failed', head: decision.receipt.head,
|
|
109
|
-
}, new Date(
|
|
213
|
+
}, new Date(now));
|
|
110
214
|
return { status: 'failed' };
|
|
111
215
|
}
|
|
112
216
|
}
|
|
@@ -39,13 +39,14 @@ exports.warmRequirementSemanticCache = warmRequirementSemanticCache;
|
|
|
39
39
|
exports.headOf = headOf;
|
|
40
40
|
exports.refreshSemanticVectors = refreshSemanticVectors;
|
|
41
41
|
exports.createGraphOperationsHandlers = createGraphOperationsHandlers;
|
|
42
|
-
// @implements A-SPEC-719, A-SPEC-734, A-SPEC-741.1, A-SPEC-758.1, A-SPEC-688.1
|
|
42
|
+
// @implements A-SPEC-719, A-SPEC-734, A-SPEC-741.1, A-SPEC-758.1, A-SPEC-688.1, A-SPEC-719.5, A-SPEC-719.8
|
|
43
43
|
// @implements A-SPEC-614, A-SPEC-613, A-SPEC-100.2, A-SPEC-121.2, A-SPEC-128, A-SPEC-139, A-SPEC-189, A-SPEC-280, A-SPEC-282, A-SPEC-283, A-SPEC-419, A-SPEC-433, A-SPEC-469, A-SPEC-478, A-SPEC-568.1, A-SPEC-568.2, A-SPEC-569.1, A-SPEC-569.2, A-SPEC-569.3, A-SPEC-589
|
|
44
44
|
// @implements A-SPEC-632
|
|
45
45
|
const fs = __importStar(require("node:fs"));
|
|
46
46
|
const path = __importStar(require("node:path"));
|
|
47
47
|
const hash_cache_1 = require("../../cpg/hash-cache");
|
|
48
48
|
const root_1 = require("../../project/root");
|
|
49
|
+
const bounded_io_1 = require("../../project/bounded-io");
|
|
49
50
|
const rtm_builder_1 = require("../../rtm/rtm-builder");
|
|
50
51
|
const graph_store_1 = require("../../rtm/graph-store");
|
|
51
52
|
const assoc_arm_1 = require("../../assoc/assoc-arm");
|
|
@@ -55,7 +56,6 @@ const tier_1 = require("../../semantic/tier");
|
|
|
55
56
|
const vector_cache_1 = require("../../semantic/vector-cache");
|
|
56
57
|
const embedder_1 = require("../../semantic/embedder");
|
|
57
58
|
const unreadable_paths_1 = require("../../semantic/unreadable-paths");
|
|
58
|
-
const bounded_io_1 = require("../../project/bounded-io");
|
|
59
59
|
const vector_coverage_1 = require("../../semantic/vector-coverage");
|
|
60
60
|
// @implements A-SPEC-283 — bumped whenever the graph's node/edge shape changes, so a store written
|
|
61
61
|
// by an older build is rebuilt rather than read with new assumptions.
|
|
@@ -140,9 +140,12 @@ async function warmRequirementSemanticCache(root, specs) {
|
|
|
140
140
|
}
|
|
141
141
|
/** The commit the verdict describes. null when this is not a Git tree — never a fabricated value. */
|
|
142
142
|
function headOf(root) {
|
|
143
|
+
// @implements A-SPEC-719.5 — the lease, the worker and triage read HEAD through one probe (scrubbed env, bounded):
|
|
144
|
+
// an exported GIT_DIR made this raw call read another repository than the lease, and every completion `stale`.
|
|
143
145
|
try {
|
|
144
|
-
|
|
145
|
-
|
|
146
|
+
// @implements A-SPEC-719.8 — with 0.35.20's 5 s bound and past the timeout memory, as its raw read was.
|
|
147
|
+
const { headProbe } = require('../../hooks/rtm-refresh');
|
|
148
|
+
return headProbe(root, { timeoutMs: bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: true }).head;
|
|
146
149
|
}
|
|
147
150
|
catch {
|
|
148
151
|
return null;
|
|
@@ -39,7 +39,6 @@ exports.createRequirementTriageHandlers = createRequirementTriageHandlers;
|
|
|
39
39
|
// @implements A-SPEC-743, A-SPEC-742, A-SPEC-729, A-SPEC-723, A-SPEC-719, A-SPEC-734, A-SPEC-723.1
|
|
40
40
|
// @implements A-SPEC-713
|
|
41
41
|
/** Read-only MCP projection of the pure requirement lifecycle triage model. */
|
|
42
|
-
const node_child_process_1 = require("node:child_process");
|
|
43
42
|
const crypto = __importStar(require("node:crypto"));
|
|
44
43
|
const path = __importStar(require("node:path"));
|
|
45
44
|
const test_evidence_1 = require("../../review/test-evidence");
|
|
@@ -94,9 +93,14 @@ function lineageOf(id, byId) {
|
|
|
94
93
|
}
|
|
95
94
|
return null;
|
|
96
95
|
}
|
|
96
|
+
/**
|
|
97
|
+
* @implements A-SPEC-719.6 — through the lease's scrubbed probe (an exported GIT_DIR named another repository).
|
|
98
|
+
* @implements A-SPEC-719.7 — past the process's git-timeout memory, as the raw read of 0.35.20 was.
|
|
99
|
+
*/
|
|
97
100
|
function headOf(root) {
|
|
98
101
|
try {
|
|
99
|
-
|
|
102
|
+
const { headProbe } = require('../../hooks/rtm-refresh');
|
|
103
|
+
return headProbe(root, { timeoutMs: bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: true }).head ?? '';
|
|
100
104
|
}
|
|
101
105
|
catch {
|
|
102
106
|
return '';
|
|
@@ -72,6 +72,13 @@ export declare function validateTriageArtifact(root: string, digest: string, exp
|
|
|
72
72
|
* freshness receipt is the current one for this workspace and HEAD. Callers run their own
|
|
73
73
|
* deterministic refusals first and call this immediately before their first write.
|
|
74
74
|
*/
|
|
75
|
+
/**
|
|
76
|
+
* @implements A-SPEC-719.6 — the HEAD intake judges evidence against, read through the same scrubbed probe as the lease
|
|
77
|
+
* and the worker: the raw `rev-parse HEAD` followed an exported GIT_DIR to another repository and never matched.
|
|
78
|
+
* @implements A-SPEC-719.7 — past the process's git-timeout memory: another call timing out on this root must not
|
|
79
|
+
* leave intake judging against no HEAD for the memory's whole window.
|
|
80
|
+
*/
|
|
81
|
+
export declare function intakeHead(root: string): string | null;
|
|
75
82
|
export declare function validateRequirementIntake(root: string, triageEvidence: unknown): {
|
|
76
83
|
ok: true;
|
|
77
84
|
} | {
|
|
@@ -40,14 +40,14 @@ exports.consumeRequirementTriageEvidence = consumeRequirementTriageEvidence;
|
|
|
40
40
|
exports.hasRequirementIntakeRecord = hasRequirementIntakeRecord;
|
|
41
41
|
exports.everSealedInLedger = everSealedInLedger;
|
|
42
42
|
exports.validateTriageArtifact = validateTriageArtifact;
|
|
43
|
+
exports.intakeHead = intakeHead;
|
|
43
44
|
exports.validateRequirementIntake = validateRequirementIntake;
|
|
44
|
-
// @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734
|
|
45
|
+
// @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734, A-SPEC-719.6
|
|
45
46
|
// @implements A-SPEC-713
|
|
46
47
|
/** Content-addressed, isolated persistence for advisory requirement triage results. */
|
|
47
48
|
const crypto = __importStar(require("node:crypto"));
|
|
48
49
|
const fs = __importStar(require("node:fs"));
|
|
49
50
|
const path = __importStar(require("node:path"));
|
|
50
|
-
const node_child_process_1 = require("node:child_process");
|
|
51
51
|
const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
|
|
52
52
|
const ledger_store_1 = require("../governance/ledger-store");
|
|
53
53
|
const provenance_chain_1 = require("../governance/provenance-chain");
|
|
@@ -229,16 +229,27 @@ function validateTriageArtifact(root, digest, expected) {
|
|
|
229
229
|
* freshness receipt is the current one for this workspace and HEAD. Callers run their own
|
|
230
230
|
* deterministic refusals first and call this immediately before their first write.
|
|
231
231
|
*/
|
|
232
|
+
/**
|
|
233
|
+
* @implements A-SPEC-719.6 — the HEAD intake judges evidence against, read through the same scrubbed probe as the lease
|
|
234
|
+
* and the worker: the raw `rev-parse HEAD` followed an exported GIT_DIR to another repository and never matched.
|
|
235
|
+
* @implements A-SPEC-719.7 — past the process's git-timeout memory: another call timing out on this root must not
|
|
236
|
+
* leave intake judging against no HEAD for the memory's whole window.
|
|
237
|
+
*/
|
|
238
|
+
function intakeHead(root) {
|
|
239
|
+
try {
|
|
240
|
+
const { headProbe } = require('../hooks/rtm-refresh');
|
|
241
|
+
return headProbe(root, { timeoutMs: bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: true }).head;
|
|
242
|
+
}
|
|
243
|
+
catch {
|
|
244
|
+
return null;
|
|
245
|
+
} // non-git root is null
|
|
246
|
+
}
|
|
232
247
|
function validateRequirementIntake(root, triageEvidence) {
|
|
233
248
|
const evidence = triageEvidence;
|
|
234
249
|
if (!evidence || typeof evidence.digest !== 'string' || typeof evidence.promptDigest !== 'string') {
|
|
235
250
|
return { ok: false, reason: '새 REQ에는 requirement_triage가 발급한 현재 triage_evidence {digest,promptDigest}가 필요합니다. 같은 prompt로 requirement_triage(persist:true)를 실행한 뒤 다시 시도하십시오.' };
|
|
236
251
|
}
|
|
237
|
-
|
|
238
|
-
try {
|
|
239
|
-
head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
|
|
240
|
-
}
|
|
241
|
-
catch { /* non-git root is null */ }
|
|
252
|
+
const head = intakeHead(root);
|
|
242
253
|
const workspaceId = (0, freshness_coordinator_1.workspaceIdFor)(root);
|
|
243
254
|
const artifact = validateTriageArtifact(root, evidence.digest, { promptDigest: evidence.promptDigest, workspaceId, head });
|
|
244
255
|
if (!artifact.ok)
|
|
@@ -46,6 +46,7 @@ export declare function gitOnce(root: string, args: string[], kind: GitKind, opt
|
|
|
46
46
|
input?: string;
|
|
47
47
|
timeout?: number;
|
|
48
48
|
env?: NodeJS.ProcessEnv;
|
|
49
|
+
ignoreBlock?: boolean;
|
|
49
50
|
}): SpawnSyncReturns<string>;
|
|
50
51
|
/** Test seam: forget every blocked root. */
|
|
51
52
|
export declare function resetGitBlocked(): void;
|
|
@@ -104,7 +104,9 @@ function noteGitFailure(root, err, kind = 'worktree') {
|
|
|
104
104
|
* 27–32 s — measured).
|
|
105
105
|
*/
|
|
106
106
|
function gitOnce(root, args, kind, opts = {}) {
|
|
107
|
-
|
|
107
|
+
// @implements A-SPEC-719.6 — `ignoreBlock` asks anyway (its own timeout is still recorded): the refresh worker's final
|
|
108
|
+
// HEAD read was skipped because the worker's own scan had timed out a git call, and every refresh ended `retry-at`.
|
|
109
|
+
if (!opts.ignoreBlock && gitRootBlocked(root, kind)) {
|
|
108
110
|
const error = Object.assign(new Error(`git ${args[0] ?? ''}: not asked — a git child for this root timed out within the last minute`), { code: 'EBLOCKED' });
|
|
109
111
|
return { pid: 0, output: [null, '', ''], stdout: '', stderr: '', status: null, signal: null, error };
|
|
110
112
|
}
|
|
@@ -45,6 +45,11 @@ export declare const FRESHNESS_RETRY_MS: number;
|
|
|
45
45
|
* 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
|
|
46
46
|
*/
|
|
47
47
|
export declare const FRESHNESS_WORKER_MAX_MS: number;
|
|
48
|
+
/**
|
|
49
|
+
* @implements A-SPEC-719.4 — the worker ends itself this long after it starts: two minutes inside the cap, which counts
|
|
50
|
+
* from the earlier `startedAt`, so the lease never expires while its worker may still run.
|
|
51
|
+
*/
|
|
52
|
+
export declare const FRESHNESS_WORKER_DEADLINE_MS: number;
|
|
48
53
|
/**
|
|
49
54
|
* A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
|
|
50
55
|
* someone edits, so without an interval the graph would never refresh between commits — the former
|
|
@@ -68,12 +73,22 @@ export declare function requestRefresh(root: string, input: RefreshRequest): {
|
|
|
68
73
|
spawn: boolean;
|
|
69
74
|
receipt: FreshnessReceipt;
|
|
70
75
|
};
|
|
76
|
+
/** @implements A-SPEC-719.5 — the head `generation`'s lease was taken for; undefined when that lease is not current. */
|
|
77
|
+
export declare function leaseHead(root: string, generation: string): string | null | undefined;
|
|
78
|
+
/** @implements A-SPEC-719.6 — the stored lease while it is `refreshing` and not expired at `now`, else null. */
|
|
79
|
+
export declare function leaseLive(root: string, now: Date): FreshnessReceipt | null;
|
|
71
80
|
/**
|
|
72
81
|
* True only while `generation` still holds the live lease in an existing root. A worker asks this
|
|
73
82
|
* before each phase that writes, so a superseded or orphaned child stops instead of recreating
|
|
74
83
|
* `.ax` under a root that was removed (A-SPEC-724).
|
|
75
84
|
*/
|
|
76
85
|
export declare function ownsLease(root: string, generation: string): boolean;
|
|
86
|
+
/**
|
|
87
|
+
* @implements A-SPEC-719.4 — whether a worker for `generation` should end: its workspace is gone, or a READABLE receipt
|
|
88
|
+
* names another generation or a finished state. A missing or unreadable receipt is not an answer (a reader can meet
|
|
89
|
+
* another process's rename on Windows) — the caller asks again at its next poll, and the worker deadline still bounds it.
|
|
90
|
+
*/
|
|
91
|
+
export declare function leaseSuperseded(root: string, generation: string): boolean;
|
|
77
92
|
/**
|
|
78
93
|
* @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
|
|
79
94
|
* crashed one. Writes only while that generation still holds the `refreshing` lease.
|
|
@@ -33,17 +33,20 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
-
exports.FRESHNESS_REREFRESH_MS = exports.FRESHNESS_WORKER_MAX_MS = exports.FRESHNESS_RETRY_MS = exports.FRESHNESS_LEASE_MS = exports.FRESHNESS_RECEIPT_FILE = exports.REFRESH_FAILURE_REASON_MAX = void 0;
|
|
36
|
+
exports.FRESHNESS_REREFRESH_MS = exports.FRESHNESS_WORKER_DEADLINE_MS = exports.FRESHNESS_WORKER_MAX_MS = exports.FRESHNESS_RETRY_MS = exports.FRESHNESS_LEASE_MS = exports.FRESHNESS_RECEIPT_FILE = exports.REFRESH_FAILURE_REASON_MAX = void 0;
|
|
37
37
|
exports.intakeUsable = intakeUsable;
|
|
38
38
|
exports.lexicalOnly = lexicalOnly;
|
|
39
39
|
exports.readFreshnessReceipt = readFreshnessReceipt;
|
|
40
40
|
exports.requestRefresh = requestRefresh;
|
|
41
|
+
exports.leaseHead = leaseHead;
|
|
42
|
+
exports.leaseLive = leaseLive;
|
|
41
43
|
exports.ownsLease = ownsLease;
|
|
44
|
+
exports.leaseSuperseded = leaseSuperseded;
|
|
42
45
|
exports.recordLeaseWorker = recordLeaseWorker;
|
|
43
46
|
exports.completeRefresh = completeRefresh;
|
|
44
47
|
exports.workspaceIdFor = workspaceIdFor;
|
|
45
48
|
// @implements A-SPEC-719, A-SPEC-768.4
|
|
46
|
-
// @implements A-SPEC-719.1
|
|
49
|
+
// @implements A-SPEC-719.1, A-SPEC-719.4, A-SPEC-719.5, A-SPEC-719.6
|
|
47
50
|
/**
|
|
48
51
|
* The durable source of truth for refresh work. A receipt names the workspace and
|
|
49
52
|
* commit it describes, so an old detached worker cannot make a newer tree look
|
|
@@ -66,6 +69,11 @@ exports.FRESHNESS_RETRY_MS = 30 * 1000;
|
|
|
66
69
|
* 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
|
|
67
70
|
*/
|
|
68
71
|
exports.FRESHNESS_WORKER_MAX_MS = 30 * 60 * 1000;
|
|
72
|
+
/**
|
|
73
|
+
* @implements A-SPEC-719.4 — the worker ends itself this long after it starts: two minutes inside the cap, which counts
|
|
74
|
+
* from the earlier `startedAt`, so the lease never expires while its worker may still run.
|
|
75
|
+
*/
|
|
76
|
+
exports.FRESHNESS_WORKER_DEADLINE_MS = exports.FRESHNESS_WORKER_MAX_MS - 2 * 60 * 1000;
|
|
69
77
|
/**
|
|
70
78
|
* A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
|
|
71
79
|
* someone edits, so without an interval the graph would never refresh between commits — the former
|
|
@@ -159,11 +167,18 @@ function expired(receipt, now) {
|
|
|
159
167
|
if (!Number.isFinite(started))
|
|
160
168
|
return true;
|
|
161
169
|
const age = now.getTime() - started;
|
|
162
|
-
|
|
170
|
+
// @implements A-SPEC-719.5 — capped both ways: a lease stamped 30 minutes ahead (clock skew, a foreign pid from a
|
|
171
|
+
// shared VM) is as spent as one 30 minutes old, whatever its pid says.
|
|
172
|
+
if (Math.abs(age) >= exports.FRESHNESS_WORKER_MAX_MS)
|
|
163
173
|
return true;
|
|
164
174
|
// @implements A-SPEC-719.1 — a running worker keeps its lease; a crashed one frees it after the short lease.
|
|
165
175
|
if (receipt.pid !== undefined && processAlive(receipt.pid))
|
|
166
176
|
return false;
|
|
177
|
+
// @implements A-SPEC-719.4 — a lease stamped in the future (a clock step, a workspace shared with a VM) never ages;
|
|
178
|
+
// once its named worker is gone, more than one short lease ahead is as dead as one short lease behind. Without a
|
|
179
|
+
// pid nothing says the worker is gone, so the former rule stands.
|
|
180
|
+
if (receipt.pid !== undefined && age <= -exports.FRESHNESS_LEASE_MS)
|
|
181
|
+
return true;
|
|
167
182
|
return age >= exports.FRESHNESS_LEASE_MS;
|
|
168
183
|
}
|
|
169
184
|
function stale(receipt) {
|
|
@@ -204,6 +219,16 @@ function requestRefresh(root, input) {
|
|
|
204
219
|
writeReceipt(root, receipt);
|
|
205
220
|
return { spawn: true, receipt };
|
|
206
221
|
}
|
|
222
|
+
/** @implements A-SPEC-719.5 — the head `generation`'s lease was taken for; undefined when that lease is not current. */
|
|
223
|
+
function leaseHead(root, generation) {
|
|
224
|
+
const receipt = storedReceipt(root);
|
|
225
|
+
return receipt !== null && receipt.generation === generation && receipt.state === 'refreshing' ? receipt.head : undefined;
|
|
226
|
+
}
|
|
227
|
+
/** @implements A-SPEC-719.6 — the stored lease while it is `refreshing` and not expired at `now`, else null. */
|
|
228
|
+
function leaseLive(root, now) {
|
|
229
|
+
const receipt = storedReceipt(root);
|
|
230
|
+
return receipt !== null && receipt.state === 'refreshing' && !expired(receipt, now) ? receipt : null;
|
|
231
|
+
}
|
|
207
232
|
/**
|
|
208
233
|
* True only while `generation` still holds the live lease in an existing root. A worker asks this
|
|
209
234
|
* before each phase that writes, so a superseded or orphaned child stops instead of recreating
|
|
@@ -213,6 +238,24 @@ function ownsLease(root, generation) {
|
|
|
213
238
|
const receipt = storedReceipt(root);
|
|
214
239
|
return receipt !== null && receipt.generation === generation && receipt.state === 'refreshing';
|
|
215
240
|
}
|
|
241
|
+
/**
|
|
242
|
+
* @implements A-SPEC-719.4 — whether a worker for `generation` should end: its workspace is gone, or a READABLE receipt
|
|
243
|
+
* names another generation or a finished state. A missing or unreadable receipt is not an answer (a reader can meet
|
|
244
|
+
* another process's rename on Windows) — the caller asks again at its next poll, and the worker deadline still bounds it.
|
|
245
|
+
*/
|
|
246
|
+
function leaseSuperseded(root, generation) {
|
|
247
|
+
try {
|
|
248
|
+
if (!fs.statSync(path.join(root, '.ax')).isDirectory())
|
|
249
|
+
return true;
|
|
250
|
+
}
|
|
251
|
+
catch {
|
|
252
|
+
return true;
|
|
253
|
+
}
|
|
254
|
+
const receipt = storedReceipt(root);
|
|
255
|
+
if (receipt === null)
|
|
256
|
+
return false;
|
|
257
|
+
return receipt.generation !== generation || receipt.state !== 'refreshing';
|
|
258
|
+
}
|
|
216
259
|
/**
|
|
217
260
|
* @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
|
|
218
261
|
* crashed one. Writes only while that generation still holds the `refreshing` lease.
|