pi-braid 0.43.26 → 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 CHANGED
@@ -96,6 +96,55 @@ 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
+
130
+ ## Core — 0.43.27 (2026-11-05: the ship list stays as it was, and a dropped promise is a failed gate)
131
+
132
+ - **A case nobody listens to is not a passing case.** Half the fixtures here
133
+ predate the `node:test` rule and carry a helper that calls `fn()` and moves on;
134
+ handed an `async` case it drops the promise, prints its green line and exits 0
135
+ before the case can fail. `packages/core/scripts/check-async-cases.mjs` scans
136
+ every fixture for that shape and fails on a call site that passes an async
137
+ case, while accepting a helper that chains or awaits. Measured before wiring:
138
+ 442 fixtures, 51 helpers that drop the promise, 0 async cases handed to one, so
139
+ the gate closes a shape rather than a current pile of failures.
140
+
141
+ - **A repository tool is not a package entry point.** 0.43.26's notes name
142
+ `packages/core/scripts/prepare-worktree.mjs`, which lives in the repository. An
143
+ attempt to add it to `files[]` was reverted: the fleet pack gate's rule is that
144
+ the tarball ships no `scripts/` entry from outside `scripts/fleet/**`, and the
145
+ gate failed on the addition with the extra path named. The note needs no
146
+ correction; the package needs no new file.
147
+
99
148
  ## Core — 0.43.26 (2026-11-05: a new fixture imports node:test, and a worktree resolves what the primary resolves)
100
149
 
101
150
  - **A rule where there was only habit.** 278 of the 440 test files under
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.26",
4
- "sha": "41a1a6d79780d94ab878547ee2b620c41882e8e1",
5
- "shaShort": "41a1a6d7",
3
+ "version": "0.43.28",
4
+ "sha": "84bca2ae7321767336ee75712aebdae2531b6bc4",
5
+ "shaShort": "84bca2ae",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-11-05T17:17:27.329Z"
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
- return ` ${entry.workerId} spec=${entry.spec} status=${entry.status} pane=${entry.pane ?? "-"} session=${entry.workerSession ?? "-"} output=${entry.outputFile ?? "-"} branch=${entry.branch ?? "-"}${closed}`;
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 existing = readWorkers(projectCwd).workers[workerId];
522
- const decision = decideAdmission(existing, effectiveRequestId, { spec, files });
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
- const lines = shown.map(workerLine).join("\n");
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
- * A status the registry reports. `resumable` is derived, never stored: it says
192
- * the entry is mid-flight with a checkpoint to resume from, which is a
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 WorkerVerdictStatus = WorkerStatus | "resumable";
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
- /** Statuses check-worker may report: the stored statuses plus `resumable`. */
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
  /**