@oscaner-skills/cdd-engine 4.12.0 → 4.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -0
- package/README.zh-CN.md +22 -0
- package/dist/contract/census.js +134 -0
- package/dist/contract/invariants.js +11 -6
- package/dist/contract/pins.js +893 -0
- package/dist/contract/review-criteria.js +332 -0
- package/dist/face/artifacts.js +13 -4
- package/dist/face/board-view.js +414 -71
- package/dist/face/capsule.js +7 -5
- package/dist/face/cli.js +192 -63
- package/dist/face/declare.js +10 -6
- package/dist/face/lifecycle.js +303 -114
- package/dist/face/preview.js +9 -0
- package/dist/face/route-render.js +23 -7
- package/dist/face/words.js +53 -7
- package/dist/infra/carrier-seal.js +47 -24
- package/dist/infra/plan-source.js +180 -78
- package/dist/infra/slug-index.js +58 -27
- package/dist/infra/workspace.js +19 -1
- package/dist/render/templates.js +84 -16
- package/dist/session/artifact-reads.js +108 -0
- package/dist/session/carrier-rulings.js +98 -45
- package/dist/session/dispatch-authority.js +2 -3
- package/dist/session/handoff-schema.js +137 -5
- package/dist/session/inflight.js +5 -2
- package/dist/session/ledger.js +178 -248
- package/dist/session/next.js +62 -15
- package/dist/session/round-artifacts.js +645 -0
- package/dist/session/round-naming.js +16 -81
- package/dist/session/run.js +19 -16
- package/package.json +1 -1
package/dist/session/ledger.js
CHANGED
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
// carrying bare functions (the plan's zero-bare-function discipline).
|
|
23
23
|
var _a;
|
|
24
24
|
import { createHash } from "node:crypto";
|
|
25
|
-
import {
|
|
25
|
+
import { readFileSync } from "node:fs";
|
|
26
26
|
import { basename } from "node:path";
|
|
27
27
|
import { DocBodyProjection } from "../contract/doc-body.js";
|
|
28
28
|
import { CarrierSeal } from "../infra/carrier-seal.js";
|
|
@@ -32,6 +32,7 @@ import { targetFaces } from "./faces.js";
|
|
|
32
32
|
import { HandoffSchema } from "./handoff-schema.js";
|
|
33
33
|
import { LineIdentity } from "./line-identity.js";
|
|
34
34
|
import { NextStepRouter } from "./next.js";
|
|
35
|
+
import { ArtifactRegistry, roundIdentityKey } from "./round-artifacts.js";
|
|
35
36
|
import { RoundNaming } from "./round-naming.js";
|
|
36
37
|
import { EMPTY_RUN_STATE } from "./run.js";
|
|
37
38
|
/** The cause a declared BLOCKED / TIMEOUT round books on the entry it synthesizes when
|
|
@@ -147,21 +148,6 @@ export class RoundRecords {
|
|
|
147
148
|
return Array.from({ length: count }, (_unused, index) => index + 1);
|
|
148
149
|
}
|
|
149
150
|
}
|
|
150
|
-
/** The retired phase-spec row key — the spelling the round records carried before the
|
|
151
|
-
* target vocabulary unified on `phase-spec` (P22 D73). Rows already on disk keep it
|
|
152
|
-
* byte-frozen; the row read normalizes it (see `Ledger.rowFor`). */
|
|
153
|
-
const RETIRED_SPEC_KEY = "spec";
|
|
154
|
-
/** The identity-DOCUMENT line words a retired `spec` row may belong to — the words a
|
|
155
|
-
* workspace's document line keys under after the vocabulary unification. A workspace
|
|
156
|
-
* holds at most ONE identity document, so a retired `spec` row is exactly that
|
|
157
|
-
* document's line: `phase-spec` (the pre-rename default), a charter's `overall`, or a
|
|
158
|
-
* standalone `single-spec`. The plan line carried `plan` before the rename too and
|
|
159
|
-
* never lived under `spec`, so it stays out. */
|
|
160
|
-
const RETIRED_SPEC_LINE_KEYS = new Set([
|
|
161
|
-
"phase-spec",
|
|
162
|
-
"overall",
|
|
163
|
-
"single-spec",
|
|
164
|
-
]);
|
|
165
151
|
/**
|
|
166
152
|
* ReviewRefs — the review-reference face (T25): the two-layer bindings (`docRevision`
|
|
167
153
|
* — the doc hash from its content · `briefRevision` — the wave's task-only projection
|
|
@@ -221,8 +207,13 @@ export class Ledger {
|
|
|
221
207
|
* input (the file names are the naming face's one mint, never a table here). */
|
|
222
208
|
#families;
|
|
223
209
|
/** The C5 next router — the closure-side judge of the round carriers (stateless;
|
|
224
|
-
* the `closedWaves()` read face and the wave gate share the same router).
|
|
225
|
-
|
|
210
|
+
* the `closedWaves()` read face and the wave gate share the same router). Built in
|
|
211
|
+
* the constructor body, never as a field initializer: the injected artifact matrix
|
|
212
|
+
* is a constructor argument, and a field initializer runs before it is assigned. */
|
|
213
|
+
#router;
|
|
214
|
+
/** The artifact matrix this ledger's names resolve through — the composition root's
|
|
215
|
+
* single instance, held (never minted) so a read face asks one table. */
|
|
216
|
+
#artifacts;
|
|
226
217
|
/** The handoff-schema face — the conclusion single source (`conclusionOf`), one
|
|
227
218
|
* instance per ledger (the round verdict derives from the op's carrier plane at
|
|
228
219
|
* judgment time · D27). */
|
|
@@ -250,11 +241,22 @@ export class Ledger {
|
|
|
250
241
|
/** The round-naming single source over this ledger's workspace — the crash
|
|
251
242
|
* artifact names derive here (zero second derivation). */
|
|
252
243
|
#naming;
|
|
253
|
-
|
|
244
|
+
/** `artifacts` is the composition root's matrix, and it is OPTIONAL here — unlike
|
|
245
|
+
* `CliLifecycle#artifacts`, which is required because a wiring bug there would read as
|
|
246
|
+
* a legal `absent` carrier. The null callers are hermetic fixtures that read the
|
|
247
|
+
* ledger's own record face, and the TWO cells `null` silences stay on the observation
|
|
248
|
+
* side of the house: `orphanHandoffs()` ⇒ `[]`, and — because the router below is
|
|
249
|
+
* built from this same value — the fix hop's read-back hint (`Route.rulings`)
|
|
250
|
+
* vanishes, which the render face prints as zero sentence rather than an empty slot.
|
|
251
|
+
* Neither is an identity judgment: `null` can not turn a judgment into a visible
|
|
252
|
+
* `absent`. Production passes the single instance at every construction point. */
|
|
253
|
+
constructor(workspace, config, plan, artifacts) {
|
|
254
254
|
this.#workspace = workspace;
|
|
255
255
|
this.#families = config.handoffNamespace().families;
|
|
256
256
|
this.#plan = plan;
|
|
257
257
|
this.#naming = new RoundNaming(workspace);
|
|
258
|
+
this.#artifacts = artifacts ?? null;
|
|
259
|
+
this.#router = new NextStepRouter(this.#artifacts);
|
|
258
260
|
}
|
|
259
261
|
/** The review-reference face — the refKind three-type derivation + binding (T25). */
|
|
260
262
|
refs() {
|
|
@@ -301,36 +303,29 @@ export class Ledger {
|
|
|
301
303
|
}
|
|
302
304
|
/** Read progress.json; null when missing/corrupt (the ledger never invents state). */
|
|
303
305
|
readProgress() {
|
|
304
|
-
return this.#read(
|
|
306
|
+
return this.#read(this.#progressName());
|
|
305
307
|
}
|
|
306
308
|
/** Write progress.json — the progress single-author write. */
|
|
307
309
|
writeProgress(data) {
|
|
308
|
-
this.#persist(
|
|
310
|
+
this.#persist(this.#progressName(), data);
|
|
311
|
+
}
|
|
312
|
+
/** The progress row's name — the injected matrix's render when the composition root
|
|
313
|
+
* wired one, else the matrix's module-level entry to the SAME row render (the
|
|
314
|
+
* fixture plane constructs a ledger with no matrix; the spelling still has one
|
|
315
|
+
* home and the two entry forms cannot drift — `nameOf` delegates to `render`). */
|
|
316
|
+
#progressName() {
|
|
317
|
+
const identity = { domain: "workspace", tasks: null };
|
|
318
|
+
return (this.#artifacts?.render(identity, "progress") ?? ArtifactRegistry.nameOf("progress", null));
|
|
309
319
|
}
|
|
310
320
|
/** The ledger-row lookup single point — a scalar key (or the single-task wave key
|
|
311
321
|
* `"1"`) resolves the `{ task }` row; a multi-task wave key (`"1,2"`) the `{ wave }` row.
|
|
312
|
-
*
|
|
313
|
-
*
|
|
314
|
-
*
|
|
315
|
-
*
|
|
316
|
-
*
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
* pure function of the progress data, so every face — this class and the board's
|
|
320
|
-
* read-only line face — enters through this ONE lookup (no second key spelling). */
|
|
321
|
-
static rowFor(data, key, identity = null) {
|
|
322
|
-
const literal = data.waves.find((row) => row.wave === String(key));
|
|
323
|
-
if (literal !== undefined || !_a.#retiredSpecApplies(key, identity))
|
|
324
|
-
return literal;
|
|
325
|
-
return data.waves.find((row) => row.wave === RETIRED_SPEC_KEY);
|
|
326
|
-
}
|
|
327
|
-
/** Whether a retired `spec` row IS the requested line — the requested word must be a
|
|
328
|
-
* document-line word and, when the declaration is known, BE that declaration. */
|
|
329
|
-
static #retiredSpecApplies(key, identity) {
|
|
330
|
-
const word = String(key);
|
|
331
|
-
if (!RETIRED_SPEC_LINE_KEYS.has(word))
|
|
332
|
-
return false;
|
|
333
|
-
return identity === null ? word === "phase-spec" : word === identity;
|
|
322
|
+
* The lookup is LITERAL: the pre-`phase-spec` `spec` row key is no longer recognized
|
|
323
|
+
* (a retired workspace's document row reads as absent, and its carrier files land on
|
|
324
|
+
* the `orphan:` observation face instead of a silent alias). A row read is a pure
|
|
325
|
+
* function of the progress data, so every face — this class and the board's read-only
|
|
326
|
+
* line face — enters through this ONE lookup (no second key spelling). */
|
|
327
|
+
static rowFor(data, key) {
|
|
328
|
+
return data.waves.find((row) => row.wave === String(key));
|
|
334
329
|
}
|
|
335
330
|
/** The fresh row for an absent key — always the wave form (a single trivial
|
|
336
331
|
* wave `"1"` is still the `{ wave: "1" }` row — one row form, T26). */
|
|
@@ -350,25 +345,26 @@ export class Ledger {
|
|
|
350
345
|
.map((record) => record.cycle)),
|
|
351
346
|
];
|
|
352
347
|
}
|
|
353
|
-
/** The row's round records — the ONE read face the ledger's consumers share.
|
|
354
|
-
*
|
|
355
|
-
*
|
|
356
|
-
|
|
348
|
+
/** The row's round records — the ONE read face the ledger's consumers share. The
|
|
349
|
+
* read is literal (`rowFor`'s ONE basis): the retired `spec` row resolves for no
|
|
350
|
+
* document word, so a legacy row contributes no records and the board shows its
|
|
351
|
+
* line as missing. */
|
|
352
|
+
recordsOf(key) {
|
|
357
353
|
const data = this.readProgress();
|
|
358
354
|
if (data === null)
|
|
359
355
|
return [];
|
|
360
|
-
return RoundRecords.of(_a.rowFor(data, key
|
|
356
|
+
return RoundRecords.of(_a.rowFor(data, key));
|
|
361
357
|
}
|
|
362
358
|
/** One op's COMPLETED cycles on a key — only `verdict.targetAction === true` records.
|
|
363
359
|
* The completion questions read this face; the dispatch-number allocation reads
|
|
364
360
|
* `roundCount` (every in-register cycle). The caller holding the line's DECLARED
|
|
365
361
|
* word passes it, so a migrated row is judged as that line (one basis with
|
|
366
362
|
* `rowFor`'s). */
|
|
367
|
-
completedCycles(key, op
|
|
363
|
+
completedCycles(key, op) {
|
|
368
364
|
const data = this.readProgress();
|
|
369
365
|
if (data === null)
|
|
370
366
|
return [];
|
|
371
|
-
return RoundRecords.of(_a.rowFor(data, key
|
|
367
|
+
return RoundRecords.of(_a.rowFor(data, key))
|
|
372
368
|
.filter((record) => record.op === op && record.verdict.targetAction)
|
|
373
369
|
.map((record) => record.cycle);
|
|
374
370
|
}
|
|
@@ -376,22 +372,22 @@ export class Ledger {
|
|
|
376
372
|
* (the round COUNT: the length of the recorded cycle identity set — for a
|
|
377
373
|
* contiguous review line this equals the latest cycle, but the identity is the
|
|
378
374
|
* cycle list, never the count, and a re-attempt at an existing cycle adds none). */
|
|
379
|
-
roundCount(key, mode
|
|
375
|
+
roundCount(key, mode) {
|
|
380
376
|
const data = this.readProgress();
|
|
381
377
|
if (data === null)
|
|
382
378
|
return 0;
|
|
383
|
-
return this.#cyclesOf(_a.rowFor(data, key
|
|
379
|
+
return this.#cyclesOf(_a.rowFor(data, key), mode).length;
|
|
384
380
|
}
|
|
385
381
|
/** Whether a dispatch key + mode has a round REGISTERED for a given CYCLE — the
|
|
386
382
|
* identity test for the register (a fix cycle that skipped a number is present at
|
|
387
383
|
* its own number, not at its ordinal — D28). This is the test/seeding face: it
|
|
388
384
|
* answers register membership, NOT completion (a hard-failed round is registered),
|
|
389
385
|
* so no production completion question reads it — those read `completedCycles`. */
|
|
390
|
-
roundRecorded(key, mode, cycle
|
|
386
|
+
roundRecorded(key, mode, cycle) {
|
|
391
387
|
const data = this.readProgress();
|
|
392
388
|
if (data === null)
|
|
393
389
|
return false;
|
|
394
|
-
return this.#cyclesOf(_a.rowFor(data, key
|
|
390
|
+
return this.#cyclesOf(_a.rowFor(data, key), mode).includes(cycle);
|
|
395
391
|
}
|
|
396
392
|
/** Record a dispatched round — the on-disk round record (the ledger edge of the
|
|
397
393
|
* ExecutionState carrier: TaskGraph in memory, the ledger on disk). Every dispatched
|
|
@@ -404,9 +400,9 @@ export class Ledger {
|
|
|
404
400
|
* identity does not double it. A caller holding the line's DECLARED word passes it
|
|
405
401
|
* too, so a migrated row is APPENDED TO rather than forked into a second identity
|
|
406
402
|
* row (the same one basis `rowFor` reads by). */
|
|
407
|
-
recordRound(key, init
|
|
403
|
+
recordRound(key, init) {
|
|
408
404
|
const data = this.readProgress() ?? this.emptyProgress();
|
|
409
|
-
let row = _a.rowFor(data, key
|
|
405
|
+
let row = _a.rowFor(data, key);
|
|
410
406
|
if (row === undefined) {
|
|
411
407
|
row = this.entryFor(key);
|
|
412
408
|
data.waves.push(row);
|
|
@@ -447,9 +443,9 @@ export class Ledger {
|
|
|
447
443
|
* recorded revision, and BLOCKs revision-aware when unchanged). The kind IS part
|
|
448
444
|
* of the identity: a doc line binds a doc-revision (T7), a wave line a
|
|
449
445
|
* brief-revision (D30) — one row, one reviewed identity. */
|
|
450
|
-
recordReviewedRevision(key, revision
|
|
446
|
+
recordReviewedRevision(key, revision) {
|
|
451
447
|
const data = this.readProgress() ?? this.emptyProgress();
|
|
452
|
-
let row = _a.rowFor(data, key
|
|
448
|
+
let row = _a.rowFor(data, key);
|
|
453
449
|
if (row === undefined) {
|
|
454
450
|
row = this.entryFor(key);
|
|
455
451
|
data.waves.push(row);
|
|
@@ -466,12 +462,12 @@ export class Ledger {
|
|
|
466
462
|
* `#briefRevision` keeps): the drift comparator relativizes only its current side,
|
|
467
463
|
* so an absolute argv-erasure shape handed in by a future caller would otherwise
|
|
468
464
|
* read as a false drift. */
|
|
469
|
-
recordReviewedPlanRevision(key, planPath
|
|
465
|
+
recordReviewedPlanRevision(key, planPath) {
|
|
470
466
|
const read = this.#plan.readPath(planPath);
|
|
471
467
|
const text = read.text();
|
|
472
468
|
if (text === null)
|
|
473
469
|
return;
|
|
474
|
-
this.recordReviewedRevision(key, this.#refs.docRevision(this.#rel(planPath), text)
|
|
470
|
+
this.recordReviewedRevision(key, this.#refs.docRevision(this.#rel(planPath), text));
|
|
475
471
|
}
|
|
476
472
|
/** Record a wave line's reviewed BRIEF revision (D30) — the hash of the wave's
|
|
477
473
|
* TASK-ONLY projection (P29 §2.2: the task sections, `## Constraints` excluded).
|
|
@@ -510,11 +506,11 @@ export class Ledger {
|
|
|
510
506
|
/** A line's recorded reviewed identity — null when none on record (a line with no
|
|
511
507
|
* reviewed identity keeps the legacy closed face). Callers narrow by `kind`: a doc
|
|
512
508
|
* line binds a doc-revision, a wave line a brief-revision (the kinds never mix). */
|
|
513
|
-
reviewedRevisionOf(key
|
|
509
|
+
reviewedRevisionOf(key) {
|
|
514
510
|
const data = this.readProgress();
|
|
515
511
|
if (data === null)
|
|
516
512
|
return null;
|
|
517
|
-
return _a.rowFor(data, key
|
|
513
|
+
return _a.rowFor(data, key)?.reviewedRevision ?? null;
|
|
518
514
|
}
|
|
519
515
|
/** Record a wave row's plan-task snapshot — the task set the plan carried at the
|
|
520
516
|
* instant the wave CLOSED. The write is IDEMPOTENT: an existing snapshot is never
|
|
@@ -545,8 +541,8 @@ export class Ledger {
|
|
|
545
541
|
/** The doc line's recorded reviewed doc revision — the doc-revision narrowing of
|
|
546
542
|
* `reviewedRevisionOf` (null when none on record, or when a non-doc kind sits on
|
|
547
543
|
* the row — a doc line is never a wave line). */
|
|
548
|
-
reviewedDocRevisionOf(key
|
|
549
|
-
const reviewed = this.reviewedRevisionOf(key
|
|
544
|
+
reviewedDocRevisionOf(key) {
|
|
545
|
+
const reviewed = this.reviewedRevisionOf(key);
|
|
550
546
|
return reviewed !== null && reviewed.kind === "doc-revision" ? reviewed : null;
|
|
551
547
|
}
|
|
552
548
|
/** The doc line's identity verdict (T7) — the current doc revision vs the line's
|
|
@@ -557,8 +553,8 @@ export class Ledger {
|
|
|
557
553
|
* `same` → unchanged (the revision-aware BLOCK). Null when no reviewed revision
|
|
558
554
|
* is on record or the doc is unreadable (the legacy closed face keeps its
|
|
559
555
|
* generic message — only present facts land). */
|
|
560
|
-
docLineVerdict(key, doc
|
|
561
|
-
const pair = this.#docRevisionPair(key, doc
|
|
556
|
+
docLineVerdict(key, doc) {
|
|
557
|
+
const pair = this.#docRevisionPair(key, doc);
|
|
562
558
|
if (pair === null)
|
|
563
559
|
return null;
|
|
564
560
|
return this.#identity.verdict(pair.reviewed, { ref: pair.current }) === "same"
|
|
@@ -570,8 +566,8 @@ export class Ledger {
|
|
|
570
566
|
* unreadable). ONE read for TWO consumers: the drift verdict (`docLineVerdict`) and
|
|
571
567
|
* the refusal's mandatory diagnosis (`docDriftHashes`), so the two can never
|
|
572
568
|
* compare different bytes. */
|
|
573
|
-
#docRevisionPair(key, doc
|
|
574
|
-
const reviewed = this.reviewedDocRevisionOf(key
|
|
569
|
+
#docRevisionPair(key, doc) {
|
|
570
|
+
const reviewed = this.reviewedDocRevisionOf(key);
|
|
575
571
|
if (reviewed === null)
|
|
576
572
|
return null;
|
|
577
573
|
try {
|
|
@@ -590,8 +586,8 @@ export class Ledger {
|
|
|
590
586
|
* the review bound, on the ONE persisted basis) and both hash ends. Null when there
|
|
591
587
|
* is no recorded revision or the document is unreadable: a diagnosis never invents
|
|
592
588
|
* a fact. */
|
|
593
|
-
docDriftHashes(key, doc
|
|
594
|
-
const pair = this.#docRevisionPair(key, doc
|
|
589
|
+
docDriftHashes(key, doc) {
|
|
590
|
+
const pair = this.#docRevisionPair(key, doc);
|
|
595
591
|
if (pair === null)
|
|
596
592
|
return null;
|
|
597
593
|
return {
|
|
@@ -623,11 +619,11 @@ export class Ledger {
|
|
|
623
619
|
* re-review resumes the same round (nothing pre-binds). `unbound` (no identity on
|
|
624
620
|
* record / an unreadable doc) keeps the legacy round/route judgment. */
|
|
625
621
|
reviewGate(key, doc, type) {
|
|
626
|
-
const verdict = this.docLineVerdict(key, doc
|
|
622
|
+
const verdict = this.docLineVerdict(key, doc);
|
|
627
623
|
if (verdict === "drift")
|
|
628
624
|
return { kind: "open" };
|
|
629
625
|
if (verdict === "same") {
|
|
630
|
-
const reviewed = this.reviewedDocRevisionOf(key
|
|
626
|
+
const reviewed = this.reviewedDocRevisionOf(key);
|
|
631
627
|
if (reviewed === null)
|
|
632
628
|
return { kind: "unbound" };
|
|
633
629
|
return { kind: "same", pending: this.#pendingFix(key, type), reviewed };
|
|
@@ -682,8 +678,11 @@ export class Ledger {
|
|
|
682
678
|
// The `--reviews` identity is the ROUTE's own (P31 §2.3): the round read resolves
|
|
683
679
|
// the FINAL carrier the record names, so a draft beside it never becomes the input
|
|
684
680
|
// — the board's `next:` and the dispatch's read the same file by construction.
|
|
681
|
+
// The router's own fix payload rides through: its `rulings` value (the rendered
|
|
682
|
+
// sidecar path) is part of the ONE fix hop, so this fallback-only repair must not
|
|
683
|
+
// rebuild the route from scratch and silently drop it.
|
|
685
684
|
return {
|
|
686
|
-
|
|
685
|
+
...route,
|
|
687
686
|
reviews: route.reviews ??
|
|
688
687
|
this.resolveHandoffPath("review", "wave", { tasks: waveKey, round: latestReview }),
|
|
689
688
|
};
|
|
@@ -762,7 +761,7 @@ export class Ledger {
|
|
|
762
761
|
const data = this.readProgress();
|
|
763
762
|
if (data === null)
|
|
764
763
|
return false;
|
|
765
|
-
const row = _a.rowFor(data, key
|
|
764
|
+
const row = _a.rowFor(data, key);
|
|
766
765
|
if (row === undefined)
|
|
767
766
|
return false;
|
|
768
767
|
const reviews = this.#latestLiveCycleOfRow(row, "review");
|
|
@@ -862,7 +861,7 @@ export class Ledger {
|
|
|
862
861
|
const data = this.readProgress();
|
|
863
862
|
if (data === null)
|
|
864
863
|
return false;
|
|
865
|
-
const row = _a.rowFor(data, key
|
|
864
|
+
const row = _a.rowFor(data, key);
|
|
866
865
|
if (row === undefined)
|
|
867
866
|
return false;
|
|
868
867
|
return this.#rowClosed(type, type === "wave" ? { tasks: String(key) } : {}, row);
|
|
@@ -902,7 +901,7 @@ export class Ledger {
|
|
|
902
901
|
const data = this.readProgress();
|
|
903
902
|
if (data === null)
|
|
904
903
|
return { kind: "review" };
|
|
905
|
-
const row = _a.rowFor(data, key
|
|
904
|
+
const row = _a.rowFor(data, key);
|
|
906
905
|
if (row === undefined)
|
|
907
906
|
return { kind: "review" };
|
|
908
907
|
const reviewLead = targetFaces[type].product.reviewLead;
|
|
@@ -1056,11 +1055,11 @@ export class Ledger {
|
|
|
1056
1055
|
* with its requesting review's cycle (D28 unchanged). Idempotent: a second stamp of
|
|
1057
1056
|
* the same record is a no-op rewrite. Returns whether a completed review of that
|
|
1058
1057
|
* cycle was stamped. */
|
|
1059
|
-
supersedeReview(key,
|
|
1058
|
+
supersedeReview(key, cycle, byCycle) {
|
|
1060
1059
|
const data = this.readProgress();
|
|
1061
1060
|
if (data === null)
|
|
1062
1061
|
return false;
|
|
1063
|
-
const row = _a.rowFor(data, key
|
|
1062
|
+
const row = _a.rowFor(data, key);
|
|
1064
1063
|
if (row === undefined)
|
|
1065
1064
|
return false;
|
|
1066
1065
|
const records = [...RoundRecords.of(row)];
|
|
@@ -1169,15 +1168,13 @@ export class Ledger {
|
|
|
1169
1168
|
digest,
|
|
1170
1169
|
};
|
|
1171
1170
|
}
|
|
1172
|
-
/** The handoff file NAME a read
|
|
1173
|
-
*
|
|
1174
|
-
*
|
|
1175
|
-
*
|
|
1176
|
-
*
|
|
1177
|
-
*
|
|
1178
|
-
*
|
|
1179
|
-
* shapes; it is READ-ONLY (every write goes through `persistHandoff`'s canonical
|
|
1180
|
-
* spelling). */
|
|
1171
|
+
/** The handoff file NAME a read resolves — the canonical family name, or the round's
|
|
1172
|
+
* FINAL when that is what landed (the finalized answer, not the child's raw draft).
|
|
1173
|
+
* The retired `spec` twin and the cycle-less implement rung are gone (P36 §3): the
|
|
1174
|
+
* answer is the ladder's, never a historical spelling, so the old carriers read as
|
|
1175
|
+
* absent here and surface as `orphan:` observations instead of silent aliases. The
|
|
1176
|
+
* read is READ-ONLY — every write goes through `persistHandoff`'s canonical
|
|
1177
|
+
* spelling. */
|
|
1181
1178
|
resolveHandoffName(op, type, params = {}) {
|
|
1182
1179
|
// The attempt the read resolves is the round's LATEST recorded one unless the
|
|
1183
1180
|
// caller names it: a re-dispatched review lands at `-a{n}`, and its fix leg only
|
|
@@ -1191,33 +1188,7 @@ export class Ledger {
|
|
|
1191
1188
|
const final = RoundNaming.renderName(_a.#artifactOf(op, type, resolved), "final");
|
|
1192
1189
|
if (final !== canonical && this.#read(final) !== null)
|
|
1193
1190
|
return final;
|
|
1194
|
-
|
|
1195
|
-
return this.#legacyCarrierName(op, type, resolved) ?? canonical;
|
|
1196
|
-
}
|
|
1197
|
-
if (this.#read(canonical) !== null)
|
|
1198
|
-
return canonical;
|
|
1199
|
-
const retired = _a.#retiredCarrierName(op, params);
|
|
1200
|
-
return this.#read(retired) === null ? canonical : retired;
|
|
1201
|
-
}
|
|
1202
|
-
/** The pre-P34 cycle-less spelling of the round's own family name — the ONE carrier
|
|
1203
|
-
* the P34 respelling moved (`tasks-{tasks}-implement.json` → `…-implement-{cycle}.json`),
|
|
1204
|
-
* so a folded legacy record (no recorded path, no digest) still resolves its own
|
|
1205
|
-
* bytes instead of reading as absent while the orphan scan still claims the file.
|
|
1206
|
-
* The rung is READ-ONLY and cycle-1 · attempt-1 alone: the legacy spelling carried
|
|
1207
|
-
* neither coordinate, so no later cycle or attempt may read it. null when the op is
|
|
1208
|
-
* not an implement, the round is past its first cycle/attempt, the family does not
|
|
1209
|
-
* exist, the legacy name IS the canonical one, or the file is absent. */
|
|
1210
|
-
#legacyCarrierName(op, type, params) {
|
|
1211
|
-
if (RoundRecords.opOf(op) !== "implement")
|
|
1212
|
-
return null;
|
|
1213
|
-
if ((params.round ?? 1) !== 1 || (params.attempt ?? 1) !== 1)
|
|
1214
|
-
return null;
|
|
1215
|
-
if (!this.#families.includes(`${op}.${type}`))
|
|
1216
|
-
return null;
|
|
1217
|
-
const legacy = this.handoffName(op, type, { tasks: params.tasks });
|
|
1218
|
-
if (legacy === this.handoffName(op, type, params))
|
|
1219
|
-
return null;
|
|
1220
|
-
return this.#read(legacy) === null ? null : legacy;
|
|
1191
|
+
return canonical;
|
|
1221
1192
|
}
|
|
1222
1193
|
/** The params one READ resolves under — the caller's attempt when it names one, else
|
|
1223
1194
|
* the round's latest recorded attempt (a fix leg knows the cycle, not the review's
|
|
@@ -1234,13 +1205,10 @@ export class Ledger {
|
|
|
1234
1205
|
return this.#workspace.resolve(this.resolveHandoffName(op, type, params));
|
|
1235
1206
|
}
|
|
1236
1207
|
/** Read a handoff carrier; null when missing/corrupt. A DOCUMENT-line read falls
|
|
1237
|
-
*
|
|
1238
|
-
*
|
|
1239
|
-
*
|
|
1240
|
-
*
|
|
1241
|
-
* the same basis as `rowFor`'s) and never covers the node shapes. Every WRITE goes
|
|
1242
|
-
* through `persistHandoff`'s current spelling — the alias is read-only, and the name
|
|
1243
|
-
* it resolves is `resolveHandoffName`'s ONE answer.
|
|
1208
|
+
* through `resolveHandoffName`'s ONE answer, which no longer carries a historical
|
|
1209
|
+
* spelling (P36 §3): a retired `spec-<op>-<round>.json` carrier reads as absent —
|
|
1210
|
+
* the file stays on disk untouched and surfaces as an `orphan:` observation. Every
|
|
1211
|
+
* WRITE goes through `persistHandoff`'s current spelling.
|
|
1244
1212
|
*
|
|
1245
1213
|
* P31 §2.2 — the read is CHECKED: the (op, type, round) round's latest recorded
|
|
1246
1214
|
* attempt supplies the digest the engine wrote, and `CarrierIntegrity.read` compares
|
|
@@ -1276,7 +1244,7 @@ export class Ledger {
|
|
|
1276
1244
|
#latestRecordOf(op, type, params) {
|
|
1277
1245
|
const mode = RoundRecords.opOf(op) ?? op;
|
|
1278
1246
|
const round = params.round === undefined ? null : Number(params.round);
|
|
1279
|
-
return this.recordsOf(this.#roundKey(type, params)
|
|
1247
|
+
return this.recordsOf(this.#roundKey(type, params))
|
|
1280
1248
|
.filter((record) => record.op === mode)
|
|
1281
1249
|
.filter((record) => round === null || record.cycle === round)
|
|
1282
1250
|
.filter((record) => params.attempt === undefined || record.attempt === params.attempt)
|
|
@@ -1311,14 +1279,11 @@ export class Ledger {
|
|
|
1311
1279
|
const name = this.#resolvedCarrierName(type, key, record);
|
|
1312
1280
|
return this.#read(name) === null ? "" : this.#workspace.resolve(name);
|
|
1313
1281
|
}
|
|
1314
|
-
/** Step ② of `carrierPathOf` — the NAME the record's identity resolves to: the
|
|
1315
|
-
*
|
|
1316
|
-
*
|
|
1317
|
-
*
|
|
1282
|
+
/** Step ② of `carrierPathOf` — the NAME the record's identity resolves to: the read
|
|
1283
|
+
* ladder's answer, seeded with the record's full identity. A retired `spec` row's
|
|
1284
|
+
* carrier is no longer a named exception: the row itself no longer resolves, so the
|
|
1285
|
+
* files stay orphan observations. */
|
|
1318
1286
|
#resolvedCarrierName(type, key, record) {
|
|
1319
|
-
if (key === RETIRED_SPEC_KEY) {
|
|
1320
|
-
return _a.#retiredCarrierName(record.op, { round: record.cycle });
|
|
1321
|
-
}
|
|
1322
1287
|
const params = {
|
|
1323
1288
|
tasks: type === "wave" ? key : undefined,
|
|
1324
1289
|
round: record.cycle,
|
|
@@ -1326,125 +1291,92 @@ export class Ledger {
|
|
|
1326
1291
|
};
|
|
1327
1292
|
return this.resolveHandoffName(record.op, type, params);
|
|
1328
1293
|
}
|
|
1329
|
-
/** The
|
|
1330
|
-
*
|
|
1331
|
-
*
|
|
1332
|
-
|
|
1333
|
-
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
*
|
|
1337
|
-
*
|
|
1338
|
-
* moves or deletes a carrier. The family names are the ledger's own single naming
|
|
1339
|
-
* truth (no second pattern), and the owning row is read through the ONE basis
|
|
1340
|
-
* `rowFor` establishes — the file's own line word IS its declaration — so a
|
|
1341
|
-
* migrated workspace's carrier resolves its live row instead of reading as an
|
|
1342
|
-
* orphan.
|
|
1294
|
+
/** The workspace's ORPHAN handoff files — the TWO-TIER judgment (spec §2.5, an
|
|
1295
|
+
* explicit narrowing of the single-tier "a name `attribute` does not know is an
|
|
1296
|
+
* orphan" reading):
|
|
1297
|
+
*
|
|
1298
|
+
* (i) the name does not attribute at all — a matrix-external name, an unknown
|
|
1299
|
+
* spelling. Observation, never a refusal;
|
|
1300
|
+
* (ii) the name attributes to the ROUND domain's carrier pair (`draft` /
|
|
1301
|
+
* `final`) and no progress record claims it — a carrier already on disk that
|
|
1302
|
+
* the ledger never booked stays visible, so a recovery pass can see it.
|
|
1343
1303
|
*
|
|
1344
|
-
*
|
|
1345
|
-
*
|
|
1346
|
-
*
|
|
1347
|
-
*
|
|
1304
|
+
* Every other attributable name is NOT an orphan: the workspace literals and the
|
|
1305
|
+
* brief are the board's own bookkeeping, the four document rows are identity
|
|
1306
|
+
* documents, and `rulings` / `report` / `log` / `crash` / `evidence` are the
|
|
1307
|
+
* board's own observations and attachments, not handoff carriers. Reading tier (ii)
|
|
1308
|
+
* literally over those kinds would flood the board with `orphan:` rows for files it
|
|
1309
|
+
* wrote or the orchestrator recorded (the 51 rulings sidecars this very workspace
|
|
1310
|
+
* holds).
|
|
1348
1311
|
*
|
|
1349
|
-
* The
|
|
1350
|
-
*
|
|
1351
|
-
*
|
|
1352
|
-
*
|
|
1312
|
+
* The candidate set is the WHOLE directory (`Workspace#names()`, the same read the
|
|
1313
|
+
* artifact matrix's `misplaced` judgment uses), not the names a carrier pattern
|
|
1314
|
+
* recognized — tier (i) can only exist if unrecognized names are looked at.
|
|
1315
|
+
*
|
|
1316
|
+
* Claiming keeps BOTH tiers P34/D89 delivered: the record's `(op, cycle, attempt)`
|
|
1317
|
+
* equals the name's identity read through `roundIdentityKey` (the matrix's own key, so a
|
|
1318
|
+
* cycle-less name is never claimed by a cycle-1 record — only the attempt default
|
|
1319
|
+
* folds), or the record's own `carrierPath` basename equals the name (a pre-P34 record
|
|
1320
|
+
* remembers an absolute path while the scan yields a bare name — read once through
|
|
1321
|
+
* `carrierPathOf`, the only accessor of that fact). Completion is irrelevant:
|
|
1322
|
+
* ownership is the record (spec §2.12), so an honestly failed round's carrier is
|
|
1323
|
+
* owned. Zero writes: this is a PURE READ, the engine never moves or deletes.
|
|
1324
|
+
*
|
|
1325
|
+
* A ledger constructed with NO matrix answers `[]`: attribution is the matrix's, and
|
|
1326
|
+
* "no matrix" has no second name grammar to fall back on. */
|
|
1353
1327
|
orphanHandoffs() {
|
|
1328
|
+
const artifacts = this.#artifacts;
|
|
1329
|
+
if (artifacts === null)
|
|
1330
|
+
return [];
|
|
1354
1331
|
const progress = this.readProgress() ?? this.emptyProgress();
|
|
1355
1332
|
const orphans = [];
|
|
1356
|
-
for (const name of this.#
|
|
1357
|
-
const
|
|
1358
|
-
if (
|
|
1359
|
-
continue;
|
|
1360
|
-
const records = RoundRecords.of(_a.#ownerRow(progress, owner.key));
|
|
1361
|
-
const identity = `${owner.op}:${owner.round}:${owner.attempt}`;
|
|
1362
|
-
const claimed = records.some((record) => `${record.op}:${record.cycle}:${record.attempt}` === identity ||
|
|
1363
|
-
basename(this.carrierPathOf(owner.type, owner.key, record)) === name);
|
|
1364
|
-
if (!claimed)
|
|
1333
|
+
for (const name of this.#workspace.names()) {
|
|
1334
|
+
const attributed = artifacts.attribute(name);
|
|
1335
|
+
if (attributed === null) {
|
|
1365
1336
|
orphans.push(name);
|
|
1337
|
+
continue;
|
|
1338
|
+
}
|
|
1339
|
+
if (attributed.kind !== "draft" && attributed.kind !== "final")
|
|
1340
|
+
continue;
|
|
1341
|
+
if (attributed.identity.domain !== "round")
|
|
1342
|
+
continue;
|
|
1343
|
+
if (this.#claimed(progress, attributed.identity, name))
|
|
1344
|
+
continue;
|
|
1345
|
+
orphans.push(name);
|
|
1366
1346
|
}
|
|
1367
1347
|
return orphans.sort();
|
|
1368
1348
|
}
|
|
1369
|
-
/**
|
|
1370
|
-
*
|
|
1371
|
-
*
|
|
1372
|
-
*
|
|
1373
|
-
*
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
|
-
|
|
1380
|
-
|
|
1381
|
-
|
|
1382
|
-
|
|
1383
|
-
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
|
|
1387
|
-
|
|
1388
|
-
|
|
1389
|
-
|
|
1390
|
-
|
|
1391
|
-
|
|
1392
|
-
return readdirSync(this.#workspace.path, { withFileTypes: true })
|
|
1393
|
-
.filter((entry) => entry.isFile())
|
|
1394
|
-
.map((entry) => entry.name);
|
|
1395
|
-
}
|
|
1396
|
-
catch {
|
|
1397
|
-
return [];
|
|
1398
|
-
}
|
|
1399
|
-
}
|
|
1400
|
-
/** Which recorded round one handoff file belongs to — the ONE renderer read
|
|
1401
|
-
* backwards: `<line>-<op>[-<cycle>][-a<attempt>][.c<cycle>].json`, the retired
|
|
1402
|
-
* document-line `spec` twin included (a still-unbooked draft can carry it). The
|
|
1403
|
-
* parse yields the same four coordinates the naming face renders, so the orphan
|
|
1404
|
-
* test compares an identity with an identity — never a spelling with a spelling.
|
|
1405
|
-
* Null for a non-carrier file. */
|
|
1406
|
-
static #handoffOwner(name) {
|
|
1407
|
-
// A FINAL carrier (`<stem>.c{round}.json`, P31 §2.3) is the same artifact as its
|
|
1408
|
-
// draft — the cycle is the name's own suffix, never a second family.
|
|
1409
|
-
const draft = name.replace(/\.c\d+\.json$/, ".json");
|
|
1410
|
-
const wave = _a.#WAVE_CARRIER.exec(draft);
|
|
1411
|
-
if (wave !== null) {
|
|
1412
|
-
const [, line = "", op = "", cycle, attempt] = wave;
|
|
1413
|
-
// The wave row keys the task GROUP alone — the `tasks-` spine is the name's, not
|
|
1414
|
-
// the key's. The legacy cycle-less implement spelling is the fixed family's round 1.
|
|
1415
|
-
return {
|
|
1416
|
-
type: "wave",
|
|
1417
|
-
key: line.replace(/^tasks-/, ""),
|
|
1418
|
-
op,
|
|
1419
|
-
round: cycle === undefined ? 1 : Number(cycle),
|
|
1420
|
-
attempt: _a.#attemptOf(attempt),
|
|
1421
|
-
};
|
|
1422
|
-
}
|
|
1423
|
-
const line = _a.#LINE_CARRIER.exec(draft);
|
|
1424
|
-
if (line !== null) {
|
|
1425
|
-
const [, key = "", op = "", cycle = "", attempt] = line;
|
|
1426
|
-
return {
|
|
1427
|
-
type: key,
|
|
1428
|
-
key,
|
|
1429
|
-
op,
|
|
1430
|
-
round: Number(cycle),
|
|
1431
|
-
attempt: _a.#attemptOf(attempt),
|
|
1432
|
-
};
|
|
1433
|
-
}
|
|
1434
|
-
return null;
|
|
1349
|
+
/** Whether a progress record claims one attributed carrier name — the identity tier
|
|
1350
|
+
* first (the record's own `(op, cycle, attempt)` through the matrix's OWN identity key),
|
|
1351
|
+
* the recorded-path tier second (a pre-P34 record's absolute `carrierPath` compared by
|
|
1352
|
+
* basename).
|
|
1353
|
+
*
|
|
1354
|
+
* The first tier compares with `roundIdentityKey`, so it answers exactly the question
|
|
1355
|
+
* the matrix answered when it attributed the name: a cycle-less spelling
|
|
1356
|
+
* (`tasks-<n>-implement.json`) is the cycle-less identity, NEVER a cycle-1 record's
|
|
1357
|
+
* name (the renderer mints `tasks-<n>-implement-1.json` for cycle 1 — two coordinates,
|
|
1358
|
+
* spec §2.2). Only the `attempt` default folds (attempt 1 and an absent attempt render
|
|
1359
|
+
* the same name). A cycle-less carrier therefore stays claimed only through tier two —
|
|
1360
|
+
* a record that REMEMBERS that path — which is exactly the division spec §2.5 states. */
|
|
1361
|
+
#claimed(progress, identity, name) {
|
|
1362
|
+
const { type, key } = _a.#lineOf(identity.line);
|
|
1363
|
+
const records = RoundRecords.of(_a.rowFor(progress, key));
|
|
1364
|
+
const expected = roundIdentityKey(identity);
|
|
1365
|
+
return records.some((record) => roundIdentityKey({
|
|
1366
|
+
domain: "round",
|
|
1367
|
+
line: identity.line,
|
|
1368
|
+
op: record.op,
|
|
1369
|
+
cycle: record.cycle,
|
|
1370
|
+
attempt: record.attempt,
|
|
1371
|
+
}) === expected || basename(this.carrierPathOf(type, key, record)) === name);
|
|
1435
1372
|
}
|
|
1436
|
-
/** The
|
|
1437
|
-
* the
|
|
1438
|
-
*
|
|
1439
|
-
static #
|
|
1440
|
-
|
|
1441
|
-
|
|
1442
|
-
|
|
1443
|
-
static #LINE_CARRIER = new RegExp(`^(${[...Object.keys(targetFaces).filter((word) => word !== "wave"), RETIRED_SPEC_KEY].join("|")})-(review|fix)-(\\d+)(?:-a(\\d+))?\\.json$`);
|
|
1444
|
-
/** An absent attempt segment is the first attempt — the naming face never renders
|
|
1445
|
-
* `-a1`, so the parse and the render agree on the identity of attempt 1. */
|
|
1446
|
-
static #attemptOf(captured) {
|
|
1447
|
-
return captured === undefined ? 1 : Number(captured);
|
|
1373
|
+
/** The progress row one carrier identity belongs to: a wave line keys the task GROUP
|
|
1374
|
+
* (the `tasks-` spine is the name's, never the key's), every other line word keys
|
|
1375
|
+
* itself. */
|
|
1376
|
+
static #lineOf(line) {
|
|
1377
|
+
return line.startsWith("tasks-")
|
|
1378
|
+
? { type: "wave", key: line.slice("tasks-".length) }
|
|
1379
|
+
: { type: line, key: line };
|
|
1448
1380
|
}
|
|
1449
1381
|
// -------------------------------------------------------------------------
|
|
1450
1382
|
// crash — the lane crash → recovery record
|
|
@@ -1472,17 +1404,15 @@ export class Ledger {
|
|
|
1472
1404
|
/** The handoff findings presented as round findings — entries with an unknown severity
|
|
1473
1405
|
* are dropped (never invented into the judgment domain). */
|
|
1474
1406
|
#findingsOf(carrier) {
|
|
1407
|
+
// Rule zero (class-size limit): this file is well past the limit and predates it —
|
|
1408
|
+
// splitting it is P39's work (design spec D95 ②), not this round's.
|
|
1475
1409
|
if (!Array.isArray(carrier.findings))
|
|
1476
1410
|
return [];
|
|
1477
|
-
|
|
1478
|
-
|
|
1479
|
-
|
|
1480
|
-
|
|
1481
|
-
|
|
1482
|
-
const summary = entry?.summary;
|
|
1483
|
-
findings.push({ severity, summary: typeof summary === "string" ? summary : undefined });
|
|
1484
|
-
}
|
|
1485
|
-
return findings;
|
|
1411
|
+
// The ONE projection (P37 §2.1 · §5.1): the handoff schema's own findings row,
|
|
1412
|
+
// over the whole carrier at once — a consumer of this face and a consumer of the
|
|
1413
|
+
// read-back face see the same cells (id / impact / regrade included), and the
|
|
1414
|
+
// unknown-severity drop is the same rule, applied once.
|
|
1415
|
+
return this.#handoffSchema.findingsOf(carrier.findings);
|
|
1486
1416
|
}
|
|
1487
1417
|
/** The blocker count of a handoff carrier's findings — the C5-1 severity count. */
|
|
1488
1418
|
#blockerCountOf(carrier) {
|
|
@@ -1539,7 +1469,7 @@ export class Ledger {
|
|
|
1539
1469
|
// cycle 2 (D28). A count comparison would flatten that to 1 and refuse the read.
|
|
1540
1470
|
// Completion is the recorded VERDICT, never membership — every dispatched round
|
|
1541
1471
|
// is recorded now, so a failed round's cycle is in register but reads no carrier.
|
|
1542
|
-
const recorded = this.recordsOf(this.#roundKey(type, params)
|
|
1472
|
+
const recorded = this.recordsOf(this.#roundKey(type, params))
|
|
1543
1473
|
.filter((record) => record.op === op && record.cycle === round)
|
|
1544
1474
|
.reduce((latest, record) => latest === undefined || record.attempt >= latest.attempt ? record : latest, undefined);
|
|
1545
1475
|
if (recorded === undefined || !recorded.verdict.targetAction)
|