pi-braid 0.43.27 → 0.43.28
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 +31 -0
- package/build-info.json +4 -4
- package/dist/extensions/orchestrator/index.js +71 -5
- package/dist/lib/orchestrator/workers.d.ts +122 -6
- package/dist/lib/orchestrator/workers.js +246 -4
- package/docs/LOCAL_DEV.md +1 -1
- package/package.json +1 -1
- package/src/extensions/orchestrator/index.ts +87 -4
- package/src/lib/orchestrator/workers.ts +337 -11
package/CHANGELOG.md
CHANGED
|
@@ -96,6 +96,37 @@ record; the tag scheme above applies unchanged.
|
|
|
96
96
|
note that a clean disable releases it, because a refusal an operator cannot act on
|
|
97
97
|
is a support ticket.
|
|
98
98
|
|
|
99
|
+
## Core — 0.43.28 (2026-11-06: the queue is read from the registry, not remembered by the seat)
|
|
100
|
+
|
|
101
|
+
- **A registry that records what a worker does but not where it sits in a queue
|
|
102
|
+
makes the seat the queue.** The entry now carries `priority` (lower runs
|
|
103
|
+
sooner, unranked last) and `dependsOn`, admission refuses an unknown id, a
|
|
104
|
+
self-dependency and an edge that would close a loop (the refusal prints the
|
|
105
|
+
loop), and `update-worker` may move a rank but never a dependency, because a
|
|
106
|
+
worker that gains a dependency after it started is a second unit of work
|
|
107
|
+
wearing the first one's id.
|
|
108
|
+
|
|
109
|
+
- **`blocked` is computed, never stored.** A row waiting on an id that has not
|
|
110
|
+
delivered reports `blocked` with the blocking ids named, while the stored
|
|
111
|
+
lifecycle status is reported beside it and never overwritten. Satisfaction is
|
|
112
|
+
`merged` or `completed` and nothing else: a worker that closed, errored,
|
|
113
|
+
stalled or was caught false-done did not deliver the thing the next one waits
|
|
114
|
+
for. A closed row still satisfies its dependents, so the listing reads
|
|
115
|
+
satisfaction against the whole registry before it filters.
|
|
116
|
+
|
|
117
|
+
- **The listing is actionable order and the old registry still loads.** Rows
|
|
118
|
+
with no unsatisfied dependency come first by rank, ties by admission time and
|
|
119
|
+
id, and blocked rows follow with a `blocked-by:` marker. A registry written by
|
|
120
|
+
0.43.27 has neither field, normalizes to unranked and wait-free on read, and
|
|
121
|
+
writes nothing back.
|
|
122
|
+
|
|
123
|
+
- **Measured before the merge.** 17 fixtures in the new file, red and green
|
|
124
|
+
around every refusal; the planted revert disables cycle detection and two of
|
|
125
|
+
them redden; the core chain reports 343 fixtures passed; placement reports 0
|
|
126
|
+
hits with 269 excluded; and the satisfaction rule was re-derived outside the
|
|
127
|
+
suite on one registry built by hand, where a dependency in `closed`, `error`,
|
|
128
|
+
`stalled` or `false-done` blocks its dependent and `merged` releases it.
|
|
129
|
+
|
|
99
130
|
## Core — 0.43.27 (2026-11-05: the ship list stays as it was, and a dropped promise is a failed gate)
|
|
100
131
|
|
|
101
132
|
- **A case nobody listens to is not a passing case.** Half the fixtures here
|
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.43.28",
|
|
4
|
+
"sha": "84bca2ae7321767336ee75712aebdae2531b6bc4",
|
|
5
|
+
"shaShort": "84bca2ae",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-11-
|
|
8
|
+
"packedAt": "2026-11-06T07:08:09.776Z"
|
|
9
9
|
}
|
|
@@ -18,6 +18,9 @@ import { execFileSync } from "node:child_process";
|
|
|
18
18
|
import { Type } from "typebox";
|
|
19
19
|
import { createLogger } from "../../lib/core/logger.js";
|
|
20
20
|
import { acquireLock, releaseLock, getConflicts, getAllLocks, createWorkerBranch, deleteWorkerBranch, getDiff, getCurrentBranch, findRepoRoot, branchExists, gitAvailable, worktreeForBranch, scanAddedLinesForSlop, registerWorker, updateWorker, closeWorker, recordWorkerMerge, readWorkers, checkWorker, parseWorkerStatus, parseWorkerOutcome, decideAdmission, recordAdmissionRefusal, resolveRequestId, computeWorkerStats, workerEffectEvidenceForEntry, locateResultSchema, readPopulationStamps, populationRefusalDetail, WORKER_EFFECT_EVIDENCE_FLAG, WORKER_SPECS, WORKER_OUTCOMES, WORKER_STATUSES, WORKER_STATUS_LAYERS, } from "../../lib/orchestrator/index.js";
|
|
21
|
+
// The queue-fact readers come from their module directly: the barrel above is
|
|
22
|
+
// one way into the library, not the only one, and it does not re-export these.
|
|
23
|
+
import { normalizeDependsOn, orderWorkerRows, validateDependencies, } from "../../lib/orchestrator/workers.js";
|
|
21
24
|
const log = createLogger("orchestrator");
|
|
22
25
|
// Helpers
|
|
23
26
|
/**
|
|
@@ -313,7 +316,23 @@ function textResult(text, details = {}) {
|
|
|
313
316
|
/** One-line registry listing for a worker entry. */
|
|
314
317
|
function workerLine(entry) {
|
|
315
318
|
const closed = entry.closedAt ? ` closed=${entry.closedAt}` : "";
|
|
316
|
-
|
|
319
|
+
// Printed only when the row carries one: an unranked, wait-free row keeps the
|
|
320
|
+
// line it had before the queue facts existed.
|
|
321
|
+
const priority = typeof entry.priority === "number" ? ` priority=${entry.priority}` : "";
|
|
322
|
+
const dependsOn = Array.isArray(entry.dependsOn) && entry.dependsOn.length > 0
|
|
323
|
+
? ` depends-on=${entry.dependsOn.join(", ")}`
|
|
324
|
+
: "";
|
|
325
|
+
return ` ${entry.workerId} spec=${entry.spec} status=${entry.status} pane=${entry.pane ?? "-"} session=${entry.workerSession ?? "-"} output=${entry.outputFile ?? "-"} branch=${entry.branch ?? "-"}${closed}${priority}${dependsOn}`;
|
|
326
|
+
}
|
|
327
|
+
/**
|
|
328
|
+
* One listing entry: the row line, plus the ids holding it after it, indented
|
|
329
|
+
* under the row so the marker can never be read as a row of its own.
|
|
330
|
+
*/
|
|
331
|
+
function workerListLine(row) {
|
|
332
|
+
const line = workerLine(row.entry);
|
|
333
|
+
if (row.blockedBy.length === 0)
|
|
334
|
+
return line;
|
|
335
|
+
return `${line}\n blocked-by: ${row.blockedBy.join(", ")}`;
|
|
317
336
|
}
|
|
318
337
|
/**
|
|
319
338
|
* Render the fleet statistics as the block `list-workers` appends when stats
|
|
@@ -339,6 +358,8 @@ function formatCheckVerdict(verdict) {
|
|
|
339
358
|
return [
|
|
340
359
|
`Worker ${verdict.workerId}`,
|
|
341
360
|
`status: ${verdict.status}`,
|
|
361
|
+
`storedStatus: ${verdict.storedStatus}`,
|
|
362
|
+
`blockedBy: ${verdict.blockedBy.length > 0 ? verdict.blockedBy.join(", ") : "-"}`,
|
|
342
363
|
`reason: ${verdict.reason}`,
|
|
343
364
|
`outputFile: ${verdict.outputFile ?? "-"} (${age})`,
|
|
344
365
|
`sessionGrowthAgeSec: ${verdict.sessionGrowthAgeSec ?? "-"}`,
|
|
@@ -457,6 +478,20 @@ const orchestrateTool = {
|
|
|
457
478
|
status: Type.Optional(Type.String({
|
|
458
479
|
description: "Lifecycle status for update-worker (see the tool description).",
|
|
459
480
|
})),
|
|
481
|
+
priority: Type.Optional(
|
|
482
|
+
// `{ anyOf: [{ type: "number" }, { type: "null" }] }` written as its own
|
|
483
|
+
// keywords: the builder's named constructors have no null literal, and the
|
|
484
|
+
// schema this hand-built object emits is plain JSON Schema.
|
|
485
|
+
Type.Unsafe({
|
|
486
|
+
anyOf: [{ type: "number" }, { type: "null" }],
|
|
487
|
+
description: "Queue rank: lower runs sooner; null is unranked, which sorts after every ranked row. " +
|
|
488
|
+
"spawn-worker/register-worker record it at admission; update-worker changes or clears it.",
|
|
489
|
+
})),
|
|
490
|
+
dependsOn: Type.Optional(Type.Array(Type.String(), {
|
|
491
|
+
description: "Worker ids this row waits for (spawn-worker/register-worker only: dependencies are fixed at admission). " +
|
|
492
|
+
"Refused when an id is unknown, is this worker's own id, or would close a loop; a refused admission writes nothing. " +
|
|
493
|
+
"check-worker reports `blocked`, naming these ids, while any of them is not merged or completed.",
|
|
494
|
+
})),
|
|
460
495
|
phase: Type.Optional(Type.String({
|
|
461
496
|
description: "update-worker: checkpoint phase the worker is in (e.g. impl, gates). Requires lastStep; the registry stamps the time.",
|
|
462
497
|
})),
|
|
@@ -498,7 +533,7 @@ const orchestrateTool = {
|
|
|
498
533
|
})),
|
|
499
534
|
}),
|
|
500
535
|
execute: async (_id, params, _signal, _onUpdate, _ctx) => {
|
|
501
|
-
const { action, workerId, slug, files, branch, baseBranch, cwd: explicitCwd, spec, outputFile, pane, workspace, workerSession, status, phase, lastStep, requestId, outcome, gates, includeClosed, includeStats, liveStatus, } = params;
|
|
536
|
+
const { action, workerId, slug, files, branch, baseBranch, cwd: explicitCwd, spec, outputFile, pane, workspace, workerSession, status, priority, dependsOn, phase, lastStep, requestId, outcome, gates, includeClosed, includeStats, liveStatus, } = params;
|
|
502
537
|
const repoRoot = resolveCwd(explicitCwd, files);
|
|
503
538
|
switch (action) {
|
|
504
539
|
case "spawn-worker": {
|
|
@@ -518,8 +553,16 @@ const orchestrateTool = {
|
|
|
518
553
|
// live row for one worker. A different request, or the same id
|
|
519
554
|
// describing different work, is refused with both ids named.
|
|
520
555
|
const effectiveRequestId = resolveRequestId(workerId, requestId);
|
|
521
|
-
const
|
|
522
|
-
const
|
|
556
|
+
const registryAtSpawn = readWorkers(projectCwd);
|
|
557
|
+
const existing = registryAtSpawn.workers[workerId];
|
|
558
|
+
// Dependencies are part of what the work is, so a retry carries the same
|
|
559
|
+
// set; changing them under the same request id is different work.
|
|
560
|
+
const dependsOnIds = normalizeDependsOn(dependsOn);
|
|
561
|
+
const decision = decideAdmission(existing, effectiveRequestId, {
|
|
562
|
+
spec,
|
|
563
|
+
files,
|
|
564
|
+
dependsOn: dependsOnIds,
|
|
565
|
+
});
|
|
523
566
|
if (decision.action === "reuse" && decision.entry) {
|
|
524
567
|
return textResult(reuseReport(decision.entry, effectiveRequestId), {
|
|
525
568
|
entry: decision.entry,
|
|
@@ -533,6 +576,12 @@ const orchestrateTool = {
|
|
|
533
576
|
recordAdmissionRefusal(workerId, effectiveRequestId, projectCwd);
|
|
534
577
|
throw new Error(`spawn-worker: ${decision.reason}.`);
|
|
535
578
|
}
|
|
579
|
+
// A dependency that cannot be satisfied refuses the spawn before a
|
|
580
|
+
// branch or a lock exists, so a refused spawn leaves nothing to undo.
|
|
581
|
+
const dependencyRefusal = validateDependencies(workerId, dependsOnIds, registryAtSpawn);
|
|
582
|
+
if (dependencyRefusal) {
|
|
583
|
+
throw new Error(`spawn-worker: ${dependencyRefusal.message}.`);
|
|
584
|
+
}
|
|
536
585
|
const conflicts = filesHeldByOthers(files, workerId, repoRoot);
|
|
537
586
|
if (conflicts.length > 0) {
|
|
538
587
|
return textResult(`CONFLICT: ${conflicts.length} file(s) already locked by other workers:\n${conflictLines(conflicts)}\n\nResolve conflicts before spawning this worker.`);
|
|
@@ -553,6 +602,8 @@ const orchestrateTool = {
|
|
|
553
602
|
files,
|
|
554
603
|
branch: branchName,
|
|
555
604
|
outputFile,
|
|
605
|
+
priority,
|
|
606
|
+
dependsOn: dependsOnIds,
|
|
556
607
|
requestId: effectiveRequestId,
|
|
557
608
|
}, projectCwd);
|
|
558
609
|
}
|
|
@@ -620,6 +671,8 @@ When the worker signals completion, use orchestrate action=verify-and-merge to r
|
|
|
620
671
|
files,
|
|
621
672
|
branch,
|
|
622
673
|
outputFile,
|
|
674
|
+
priority,
|
|
675
|
+
dependsOn,
|
|
623
676
|
pane,
|
|
624
677
|
workerSession,
|
|
625
678
|
requestId,
|
|
@@ -643,6 +696,8 @@ When the worker signals completion, use orchestrate action=verify-and-merge to r
|
|
|
643
696
|
files,
|
|
644
697
|
branch,
|
|
645
698
|
outputFile,
|
|
699
|
+
priority,
|
|
700
|
+
dependsOn,
|
|
646
701
|
pane,
|
|
647
702
|
workerSession,
|
|
648
703
|
requestId,
|
|
@@ -653,6 +708,12 @@ When the worker signals completion, use orchestrate action=verify-and-merge to r
|
|
|
653
708
|
if (!workerId) {
|
|
654
709
|
throw new Error("update-worker requires workerId");
|
|
655
710
|
}
|
|
711
|
+
if (dependsOn !== undefined) {
|
|
712
|
+
throw new Error("update-worker: dependencies are fixed at admission — dependsOn is admitted by " +
|
|
713
|
+
"spawn-worker/register-worker only. A worker that gains a dependency after it " +
|
|
714
|
+
"started is a second unit of work wearing the first one's id; close the entry and " +
|
|
715
|
+
"admit it again.");
|
|
716
|
+
}
|
|
656
717
|
const patch = {};
|
|
657
718
|
if (pane !== undefined)
|
|
658
719
|
patch.pane = pane;
|
|
@@ -668,6 +729,8 @@ When the worker signals completion, use orchestrate action=verify-and-merge to r
|
|
|
668
729
|
patch.files = files;
|
|
669
730
|
if (status !== undefined)
|
|
670
731
|
patch.status = parseWorkerStatus(status);
|
|
732
|
+
if (priority !== undefined)
|
|
733
|
+
patch.priority = priority;
|
|
671
734
|
if (phase !== undefined || lastStep !== undefined) {
|
|
672
735
|
if (!phase || !lastStep) {
|
|
673
736
|
throw new Error("update-worker: a checkpoint needs both phase and lastStep (the last completed step within that phase).");
|
|
@@ -716,7 +779,10 @@ When the worker signals completion, use orchestrate action=verify-and-merge to r
|
|
|
716
779
|
counts.set(entry.status, (counts.get(entry.status) ?? 0) + 1);
|
|
717
780
|
const closedCount = all.filter((entry) => entry.closedAt).length;
|
|
718
781
|
const byStatus = WORKER_STATUSES.map((s) => `${s}=${counts.get(s) ?? 0}`).join(" ");
|
|
719
|
-
|
|
782
|
+
// Actionable order over the rows being shown, with satisfaction read
|
|
783
|
+
// against every row: a closed dependency still counts as delivered.
|
|
784
|
+
const ordered = orderWorkerRows(shown, registry);
|
|
785
|
+
const lines = [...ordered.ready, ...ordered.blocked].map(workerListLine).join("\n");
|
|
720
786
|
return textResult(`Workers (${repoRoot ?? process.cwd()}):\n${lines}\ncounts: total=${all.length} live=${all.length - closedCount} closed=${closedCount} | ${byStatus}${statsSuffix}`, details);
|
|
721
787
|
}
|
|
722
788
|
case "close-worker": {
|
|
@@ -8,6 +8,12 @@
|
|
|
8
8
|
* session growth, branch commits, result schema) — never from the worker's
|
|
9
9
|
* own claim alone.
|
|
10
10
|
*
|
|
11
|
+
* Each row also carries its queue rank and the worker ids it waits for, so the
|
|
12
|
+
* order workers may run in is read from the registry: `orderWorkerRows`
|
|
13
|
+
* prints it, and a verdict says `blocked` while a dependency has not been
|
|
14
|
+
* delivered. Both facts are the registry's own; no caller has to remember
|
|
15
|
+
* which piece of work lands first.
|
|
16
|
+
*
|
|
11
17
|
* Registry file location: ~/.pi/agent/braid/projects/<sanitized-cwd>/workers.json
|
|
12
18
|
* (per-CWD, beside locks.json, shared across all agents on the same project).
|
|
13
19
|
*
|
|
@@ -68,6 +74,17 @@ export interface WorkerEntry {
|
|
|
68
74
|
outputFile: string | null;
|
|
69
75
|
branch: string | null;
|
|
70
76
|
files: string[];
|
|
77
|
+
/**
|
|
78
|
+
* Queue rank: lower runs sooner. Null is unranked, which sorts after every
|
|
79
|
+
* ranked row. Filled with null on a row admitted before the field existed.
|
|
80
|
+
*/
|
|
81
|
+
priority: number | null;
|
|
82
|
+
/**
|
|
83
|
+
* Worker ids this row waits for, in declared order. Empty means it waits for
|
|
84
|
+
* nothing. Fixed at admission: a dependency gained after the work started is
|
|
85
|
+
* a second unit of work wearing the first one's id.
|
|
86
|
+
*/
|
|
87
|
+
dependsOn: string[];
|
|
71
88
|
spawnedAt: string;
|
|
72
89
|
lastSeenAt: string | null;
|
|
73
90
|
resultAt: string | null;
|
|
@@ -107,6 +124,13 @@ export interface RegisterWorkerInput {
|
|
|
107
124
|
files?: string[];
|
|
108
125
|
branch?: string;
|
|
109
126
|
outputFile?: string;
|
|
127
|
+
/** Queue rank: lower runs sooner; null or absent is unranked. */
|
|
128
|
+
priority?: number | null;
|
|
129
|
+
/**
|
|
130
|
+
* Worker ids this row waits for. Refused when an id is unknown, is this
|
|
131
|
+
* row's own id, or would close a dependency loop.
|
|
132
|
+
*/
|
|
133
|
+
dependsOn?: string[];
|
|
110
134
|
/**
|
|
111
135
|
* Worker handle, when the caller already has it at admission time. Absent
|
|
112
136
|
* stays null: a handle is never invented, and a pane is a place to look, not
|
|
@@ -129,6 +153,10 @@ export interface RegisterWorkerResult {
|
|
|
129
153
|
reason?: string;
|
|
130
154
|
/** True when a live entry already admitted this request and was reused. */
|
|
131
155
|
reused?: boolean;
|
|
156
|
+
/** Machine-readable reason when the admission itself was refused. */
|
|
157
|
+
refusedBy?: DependencyRefusalReason;
|
|
158
|
+
/** The dependency id the refusal names. */
|
|
159
|
+
offendingId?: string;
|
|
132
160
|
}
|
|
133
161
|
export interface UpdateWorkerPatch {
|
|
134
162
|
pane?: string;
|
|
@@ -138,6 +166,8 @@ export interface UpdateWorkerPatch {
|
|
|
138
166
|
branch?: string;
|
|
139
167
|
files?: string[];
|
|
140
168
|
status?: WorkerStatus;
|
|
169
|
+
/** Queue rank to set; null clears it back to unranked. */
|
|
170
|
+
priority?: number | null;
|
|
141
171
|
/** Resume point to record; stamped with the write time. */
|
|
142
172
|
checkpoint?: WorkerCheckpointInput;
|
|
143
173
|
}
|
|
@@ -156,10 +186,20 @@ export interface WorkerCheckOptions {
|
|
|
156
186
|
now?: number;
|
|
157
187
|
/** Frozen-session threshold in seconds; defaults to 600. */
|
|
158
188
|
stalledAfterSec?: number;
|
|
189
|
+
/**
|
|
190
|
+
* The registry the entry belongs to, which is what its dependencies are
|
|
191
|
+
* resolved against. checkWorker always supplies it; a caller that omits it
|
|
192
|
+
* leaves dependency satisfaction unread, so no row is reported blocked.
|
|
193
|
+
*/
|
|
194
|
+
registry?: WorkerRegistry;
|
|
159
195
|
}
|
|
160
196
|
export interface WorkerCheckResult {
|
|
161
197
|
workerId: string;
|
|
162
198
|
status: WorkerVerdictStatus;
|
|
199
|
+
/** The row's own stored status, beside the verdict — never replaced by it. */
|
|
200
|
+
storedStatus: WorkerStatus;
|
|
201
|
+
/** Dependency ids nothing has satisfied yet; empty when the row may run. */
|
|
202
|
+
blockedBy: string[];
|
|
163
203
|
reason: string;
|
|
164
204
|
outputFile: string | null;
|
|
165
205
|
outputExists: boolean;
|
|
@@ -188,12 +228,36 @@ export interface WorkerCheckResult {
|
|
|
188
228
|
effectEvidence: WorkerEffectEvidence | null;
|
|
189
229
|
}
|
|
190
230
|
/**
|
|
191
|
-
*
|
|
192
|
-
* the
|
|
193
|
-
* statement about evidence rather than a lifecycle state a caller sets. No
|
|
194
|
-
* stored row carries it, so the on-disk status set is unchanged.
|
|
231
|
+
* Why a dependency edge was refused at admission: the id is not in the registry,
|
|
232
|
+
* the row names itself, or the edge would close a loop.
|
|
195
233
|
*/
|
|
196
|
-
export type
|
|
234
|
+
export type DependencyRefusalReason = "unknown-dependency" | "self-dependency" | "dependency-cycle";
|
|
235
|
+
/** One refused dependency edge, as the admission reports it. */
|
|
236
|
+
export interface DependencyRefusal {
|
|
237
|
+
reason: DependencyRefusalReason;
|
|
238
|
+
/** The offending id: the unknown one, the row's own, or where a loop starts. */
|
|
239
|
+
id: string;
|
|
240
|
+
/**
|
|
241
|
+
* The loop from the admitted row back to itself, e.g. `[a, b, a]`; empty
|
|
242
|
+
* when the refusal names no loop.
|
|
243
|
+
*/
|
|
244
|
+
path: string[];
|
|
245
|
+
/** The refusal in one sentence, prefixed with its reason token. */
|
|
246
|
+
message: string;
|
|
247
|
+
}
|
|
248
|
+
/** One listing row: the entry, and the dependency ids still blocking it. */
|
|
249
|
+
export interface WorkerOrderRow {
|
|
250
|
+
entry: WorkerEntry;
|
|
251
|
+
blockedBy: string[];
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* A status the registry reports. `resumable` and `blocked` are derived, never
|
|
255
|
+
* stored: `resumable` says the entry is mid-flight with a checkpoint to resume
|
|
256
|
+
* from, `blocked` that a dependency has not been delivered. Both are statements
|
|
257
|
+
* about evidence rather than lifecycle states a caller sets, so no stored row
|
|
258
|
+
* carries either and the on-disk status set is unchanged.
|
|
259
|
+
*/
|
|
260
|
+
export type WorkerVerdictStatus = WorkerStatus | "resumable" | "blocked";
|
|
197
261
|
export declare const WORKER_REGISTRY_VERSION = 1;
|
|
198
262
|
/**
|
|
199
263
|
* Spec names a worker result may declare: the accepted set, and the one source
|
|
@@ -203,7 +267,10 @@ export declare const WORKER_REGISTRY_VERSION = 1;
|
|
|
203
267
|
export declare const WORKER_SPECS: readonly string[];
|
|
204
268
|
export declare const WORKER_STATUSES: readonly WorkerStatus[];
|
|
205
269
|
export declare const WORKER_OUTCOMES: readonly WorkerOutcome[];
|
|
206
|
-
/**
|
|
270
|
+
/**
|
|
271
|
+
* Statuses check-worker may report: the stored statuses plus the derived ones,
|
|
272
|
+
* `resumable` and `blocked`, which no row ever carries on disk.
|
|
273
|
+
*/
|
|
207
274
|
export declare const WORKER_VERDICT_STATUSES: readonly WorkerVerdictStatus[];
|
|
208
275
|
/** Statuses a worker's result schema may self-report. */
|
|
209
276
|
export declare const RESULT_SCHEMA_STATUSES: readonly string[];
|
|
@@ -268,6 +335,7 @@ export interface WorkerAdmissionDecision {
|
|
|
268
335
|
export declare function decideAdmission(existing: WorkerEntry | undefined, requestId: string, request: {
|
|
269
336
|
spec?: string;
|
|
270
337
|
files?: string[];
|
|
338
|
+
dependsOn?: readonly string[];
|
|
271
339
|
}): WorkerAdmissionDecision;
|
|
272
340
|
/**
|
|
273
341
|
* Persist a refused admission against the live worker that refused it. A
|
|
@@ -278,6 +346,48 @@ export declare function decideAdmission(existing: WorkerEntry | undefined, reque
|
|
|
278
346
|
* refuses nothing.
|
|
279
347
|
*/
|
|
280
348
|
export declare function recordAdmissionRefusal(workerId: string, requestId: string, cwd?: string): boolean;
|
|
349
|
+
/** Priority values the registry accepts: finite numbers, or null for unranked. */
|
|
350
|
+
export declare function normalizePriority(raw: unknown): number | null;
|
|
351
|
+
/**
|
|
352
|
+
* Dependency ids as the registry stores them: strings, trimmed, non-empty,
|
|
353
|
+
* first occurrence kept. A malformed or absent value waits for nothing.
|
|
354
|
+
*/
|
|
355
|
+
export declare function normalizeDependsOn(raw: unknown): string[];
|
|
356
|
+
/** Statuses that satisfy a dependency edge; a failed worker delivered nothing. */
|
|
357
|
+
export declare const WORKER_SATISFYING_STATUSES: readonly WorkerStatus[];
|
|
358
|
+
/** True when the row that id names delivered the work a dependent waits for. */
|
|
359
|
+
export declare function isDependencySatisfied(entry: WorkerEntry | undefined): boolean;
|
|
360
|
+
/**
|
|
361
|
+
* The dependency ids of one row that nothing has satisfied yet, in declared
|
|
362
|
+
* order. An id with no row at all is unsatisfied: admission refuses unknown ids,
|
|
363
|
+
* so a missing one means the row was hand-edited or removed, and neither is a
|
|
364
|
+
* delivery.
|
|
365
|
+
*/
|
|
366
|
+
export declare function unsatisfiedDependencies(entry: WorkerEntry, registry: WorkerRegistry): string[];
|
|
367
|
+
/**
|
|
368
|
+
* Decide whether `dependsOn` may be recorded for `workerId`, against the graph
|
|
369
|
+
* the registry holds now. Null means the edges stand. A refused edge writes
|
|
370
|
+
* nothing: the caller reports the reason and the id, and the row is untouched.
|
|
371
|
+
*
|
|
372
|
+
* A row naming itself is refused as a self-dependency before the unknown check,
|
|
373
|
+
* which would otherwise answer `unknown-dependency` for an id that is by
|
|
374
|
+
* construction not admitted yet and hide the actual defect.
|
|
375
|
+
*/
|
|
376
|
+
export declare function validateDependencies(workerId: string, dependsOn: readonly string[], registry: WorkerRegistry): DependencyRefusal | null;
|
|
377
|
+
/**
|
|
378
|
+
* Split listing rows into the order they may be acted on: rows whose
|
|
379
|
+
* dependencies are all satisfied first, then blocked rows, each group ranked by
|
|
380
|
+
* priority ascending with unranked rows after every ranked one, ties by
|
|
381
|
+
* admission time and then id so the order is total.
|
|
382
|
+
*
|
|
383
|
+
* Satisfaction is read against the whole registry rather than the rows being
|
|
384
|
+
* printed: a closed row still satisfies its dependents, so it must be read
|
|
385
|
+
* before a listing that hides closed rows is filtered.
|
|
386
|
+
*/
|
|
387
|
+
export declare function orderWorkerRows(entries: readonly WorkerEntry[], registry: WorkerRegistry): {
|
|
388
|
+
ready: WorkerOrderRow[];
|
|
389
|
+
blocked: WorkerOrderRow[];
|
|
390
|
+
};
|
|
281
391
|
/**
|
|
282
392
|
* Admit a worker. Refuses when a live (not closed) entry exists for the
|
|
283
393
|
* same workerId; a closed entry is rolled over (retries are countable).
|
|
@@ -591,6 +701,12 @@ export declare function workerEffectEvidenceForEntry(entry: WorkerEntry, opts?:
|
|
|
591
701
|
* recorded gate exited 0. None of the three is the no-effect-evidence flag;
|
|
592
702
|
* the flag is a field on the verdict, never a different status, and a row
|
|
593
703
|
* that is not a terminal completion carries null.
|
|
704
|
+
*
|
|
705
|
+
* A row whose `dependsOn` holds an id that is not `merged` or `completed`
|
|
706
|
+
* reads as `blocked`, naming each blocking id with the status it carries; the
|
|
707
|
+
* row's own stored status travels beside the verdict, so a blocked row and a
|
|
708
|
+
* ready one are never the same answer. The dependencies are read against the
|
|
709
|
+
* registry the row belongs to, which checkWorker supplies.
|
|
594
710
|
*/
|
|
595
711
|
export declare function evaluateWorker(entry: WorkerEntry, opts?: WorkerCheckOptions): WorkerCheckResult;
|
|
596
712
|
/**
|