@oscaner-skills/cdd-engine 4.7.0 → 4.8.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.
@@ -88,7 +88,10 @@ export class DispatchAuthority {
88
88
  : `${reason} · ${render.detail}`;
89
89
  }
90
90
  const command = render.command === undefined ? "" : render.command(verdict.next);
91
- return `${reason} · next: ${command}`;
91
+ // The reopen flag rides the command the renderer produced — the SAME review
92
+ // command, one flag added (`--recover`), never a second literal (P30 §2.3).
93
+ const recover = verdict.recover === true ? " --recover" : "";
94
+ return `${reason} · next: ${command}${recover}`;
92
95
  }
93
96
  /** The structure leg's verdict — the seam's refusal re-expressed as this chain's
94
97
  * first row. Its token is the refusing gate's own id (the table's structure rows:
@@ -210,9 +213,10 @@ export class DispatchAuthority {
210
213
  const ruling = request.type === "wave" ? this.#waveRuling(request) : this.#docRuling(request);
211
214
  if (ruling.kind === "allowed")
212
215
  return { allowed: true };
213
- const next = this.#hopOf(request.line);
216
+ const next = ruling.kind === "row" && ruling.hop !== undefined ? ruling.hop : this.#hopOf(request.line);
214
217
  const reason = ruling.kind === "row" ? ruling.reason : next.reason;
215
- return this.#refusal("line", reason, next, request.line);
218
+ const recover = ruling.kind === "row" ? ruling.recover : undefined;
219
+ return this.#refusal("line", reason, next, request.line, recover);
216
220
  }
217
221
  /** One refusal, with its drift diagnosis attached when the reason is a drift token
218
222
  * (§2.5 — one construction point, so no refusal has a second path to print by). The
@@ -220,13 +224,16 @@ export class DispatchAuthority {
220
224
  * second lookup of which line moved. It is absent exactly when the target records no
221
225
  * pair — a diagnosis never invents a fact, so an underivable identity prints the
222
226
  * bare token. */
223
- #refusal(leg, reason, next, facts) {
227
+ #refusal(leg, reason, next, facts, recover) {
224
228
  const drift = _a.#isDriftReason(reason)
225
229
  ? _a.#driftOf(next, facts)
226
230
  : undefined;
227
- return drift === undefined
228
- ? { allowed: false, leg, reason, next }
229
- : { allowed: false, leg, reason, next, drift };
231
+ const base = { allowed: false, leg, reason, next };
232
+ return {
233
+ ...base,
234
+ ...(drift === undefined ? {} : { drift }),
235
+ ...(recover === true ? { recover: true } : {}),
236
+ };
230
237
  }
231
238
  /** Whether a token names a moved reviewed identity — the two rows whose refusal line
232
239
  * must carry the diagnosis (§2.5). */
@@ -321,9 +328,15 @@ export class DispatchAuthority {
321
328
  return { kind: "allowed" };
322
329
  }
323
330
  // A pending fix is the line's own row: the fix it awaits is a present fact, and
324
- // the refusal names it whatever the requested verb was.
325
- if (phase.phase === "fix")
326
- return { kind: "row", reason: DISPATCH_REASON.pendingFix.token };
331
+ // the refusal names it whatever the requested verb was. On a DRIFTED line the same
332
+ // row is reopenable — the `next:` is then the review round the `--recover` flag
333
+ // reopens (P30 §2.3), never the fix the old design already outran.
334
+ if (phase.phase === "fix") {
335
+ const reopen = _a.#reopenHop(facts, request.type);
336
+ return reopen === null
337
+ ? { kind: "row", reason: DISPATCH_REASON.pendingFix.token }
338
+ : { kind: "row", reason: DISPATCH_REASON.pendingFix.token, recover: true, hop: reopen };
339
+ }
327
340
  if (phase.phase !== null)
328
341
  return { kind: "hop" };
329
342
  // The closed line: the doc shapes name their unchanged reviewed identity (the
@@ -334,6 +347,41 @@ export class DispatchAuthority {
334
347
  reason: unchanged ? DISPATCH_REASON.unchanged.token : DISPATCH_REASON.faceClosed.token,
335
348
  };
336
349
  }
350
+ /** Whether the line sits at the REOPENABLE face — `reviewGate` open (the document
351
+ * drifted past what the review bound) AND a fix still owed (P30 §2.3's condition
352
+ * pair ①②). Read from the ledger's own derivations (`reviewGate` · `pendingFix`),
353
+ * never a second walk: the refusal's `--recover` hint and the CLI's reopen leg judge
354
+ * the same pair. */
355
+ static #reopenable(facts, type) {
356
+ const { lineKey: key, doc, ledger } = facts;
357
+ if (key === null || doc === null)
358
+ return false;
359
+ if (type === "wave")
360
+ return false;
361
+ return ledger.reviewGate(key, doc, type).kind === "open" && ledger.pendingFix(key, type);
362
+ }
363
+ /** The reopenable line's REVIEW hop — the round `--recover` makes dispatchable, built
364
+ * through the ONE hop assembly (`Ledger#nextHopOf`) so the refusal's `next:` is the
365
+ * same command the capsule and the board render (P30 §2.3). Null when the line is
366
+ * not reopenable (the refusal then keeps the frontier's own hop). */
367
+ static #reopenHop(facts, type) {
368
+ if (!_a.#reopenable(facts, type))
369
+ return null;
370
+ const { lineKey: key, doc } = facts;
371
+ if (key === null || doc === null)
372
+ return null;
373
+ // The render target's own shape (a branch line carries its plan as `plan`, every
374
+ // doc shape carries the document as `id`) — the frontier's own construction.
375
+ const target = type === "branch" ? { type: "branch", id: "branch", plan: doc } : { type, id: doc };
376
+ return facts.ledger.nextHopOf({
377
+ type,
378
+ key,
379
+ route: { kind: "review" },
380
+ target,
381
+ doc,
382
+ docClassOf: facts.docClassOf,
383
+ });
384
+ }
337
385
  /** The phase the requested verb dispatches on this face — the review verb asks for
338
386
  * the face's OWN review lead (the branch line's `branch-review`). */
339
387
  #expectedPhase(type, verb) {
@@ -28,11 +28,18 @@
28
28
  // behavior-carrying bare functions (the plan's zero-bare-function discipline).
29
29
  /** One finding row — the shared base declaration of the judge plane (severity +
30
30
  * lens + summary required; the extra review columns — section / line / fix — are
31
- * declared optional, and unknown extra fields ride along). */
31
+ * declared optional, and unknown extra fields ride along).
32
+ *
33
+ * `id` is declared OPTIONAL on purpose (P30 §2.5): the engine writes the stable key
34
+ * (`F1`, `F2` … in carrier order) at materialize and overwrites whatever the child
35
+ * put there, so the prompt shows the field exists while the child owes nothing. A
36
+ * required `id` would push an engine-owned value onto the child and add a pointless
37
+ * read-back BLOCK face for a field the engine always rewrites. */
32
38
  const FINDING = {
33
39
  type: "object",
34
40
  required: ["severity", "lens", "summary"],
35
41
  properties: {
42
+ id: { type: "string" },
36
43
  severity: { type: "string", enum: ["blocker", "warn", "nit"] },
37
44
  lens: { type: "string" },
38
45
  section: { type: "string" },
@@ -29,6 +29,7 @@
29
29
  //
30
30
  // Module-level exports are types / the error class / the class — zero
31
31
  // behavior-carrying bare functions.
32
+ var _a;
32
33
  import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
33
34
  import path from "node:path";
34
35
  import lockfile from "proper-lockfile";
@@ -63,6 +64,15 @@ export class InFlight {
63
64
  static LOCK_STALE_MS = 12 * 60 * 60 * 1000;
64
65
  /** The lock's refresh interval (ms). */
65
66
  static LOCK_UPDATE_MS = 60 * 1000;
67
+ /** The three takeover reasons of a stale tree — ONE literal per morphology (spec
68
+ * §2.1①: a dead holder, a corrupt record with a leftover lock, a lock with no record
69
+ * behind it). Shared by `acquire({ recover })`'s pre-step and the abort fold, so a
70
+ * takeover can never be named two ways. */
71
+ static STEAL_REASON = {
72
+ deadHolder: "the holder is dead",
73
+ corruptRecord: "the record is corrupt and the lock is left behind",
74
+ lockOnly: "a lock without a record",
75
+ };
66
76
  #root;
67
77
  #slug;
68
78
  #liveness;
@@ -76,7 +86,7 @@ export class InFlight {
76
86
  }
77
87
  /** The record's absolute path (`<workspaceRoot>/in-flight.json`). */
78
88
  path() {
79
- return path.join(this.#root.path, InFlight.FILE);
89
+ return path.join(this.#root.path, _a.FILE);
80
90
  }
81
91
  /** The lock directory's absolute path (`proper-lockfile`'s default carrier). */
82
92
  lockPath() {
@@ -96,19 +106,19 @@ export class InFlight {
96
106
  * → live-holder guard → lock → record. The guard is the class's OWN fail-closed
97
107
  * check that a standing record is never displaced while its holder lives: the
98
108
  * pre-flight gate is the primary guard, this one keeps the invariant true for any
99
- * other write point. `stealStale` only acts HERE: a standing record whose holder is
109
+ * other write point. `recover` only acts HERE: a standing record whose holder is
100
110
  * dead (or a corrupt record with a leftover lock) is taken over first; a live holder
101
111
  * is never displaced. A failed lock throws `HoldingError` carrying the holder's
102
112
  * facts and leaves the record bytes untouched. */
103
113
  async acquire(record, options = {}) {
104
114
  this.ensureMarker();
105
- if (options.stealStale === true)
115
+ if (options.recover === true)
106
116
  await this.#stealIfDead();
107
117
  await this.#refuseLiveHolder();
108
118
  try {
109
119
  this.#unlock = await lockfile.lock(this.path(), {
110
- stale: InFlight.LOCK_STALE_MS,
111
- update: InFlight.LOCK_UPDATE_MS,
120
+ stale: _a.LOCK_STALE_MS,
121
+ update: _a.LOCK_UPDATE_MS,
112
122
  realpath: false,
113
123
  retries: 0,
114
124
  });
@@ -187,7 +197,22 @@ export class InFlight {
187
197
  return { kind: "absent" };
188
198
  return { kind: "corrupt", locked: existsSync(this.lockPath()) };
189
199
  }
190
- /** Take the record over explicitly — the `--steal-stale` path. The precondition is
200
+ /** The tree's STALE in-flight — the three takeover morphologies of spec §2.1①
201
+ * define the answer, so every reader names the same stale face: a dead holder's
202
+ * readable record, a corrupt record with a leftover lock, or a lock with no record
203
+ * behind it. Null when the tree is FREE or a LIVE holder stands (a live holder is
204
+ * never displaced). ONE predicate for `acquire({ recover })`'s pre-step, the abort
205
+ * fold and the composition root's reopen judgment — a stale tree can never be
206
+ * named two ways. */
207
+ async staleState() {
208
+ const state = await this.inspect();
209
+ if (state.kind === "held")
210
+ return state.alive ? null : state;
211
+ if (state.kind === "corrupt")
212
+ return state.locked ? state : null;
213
+ return existsSync(this.lockPath()) ? state : null;
214
+ }
215
+ /** Take the record over explicitly — the `--recover` path. The precondition is
191
216
  * that the holder cannot be alive: a readable record whose pid is live is refused
192
217
  * (the flag never crosses "alive → no takeover"); a corrupt record has no live
193
218
  * fact to honor and is cleared. Clears the lock, then the record. */
@@ -209,22 +234,21 @@ export class InFlight {
209
234
  rmSync(this.path(), { force: true });
210
235
  return record;
211
236
  }
212
- /** The `stealStale` pre-step of acquire: take over a standing record whose holder is
237
+ /** The `recover` pre-step of acquire: take over a standing record whose holder is
213
238
  * dead, a corrupt record with a leftover lock, or a lock remnant with no record —
214
- * and do nothing while the holder is alive (the lock then refuses the acquire). */
239
+ * and do nothing while the holder is alive (the lock then refuses the acquire).
240
+ * The morphology predicate is `staleState()`; this only names the takeover. */
215
241
  async #stealIfDead() {
216
- const state = await this.inspect();
217
- if (state.kind === "held" && !state.alive) {
218
- await this.steal("the holder is dead");
242
+ const stale = await this.staleState();
243
+ if (stale === null)
219
244
  return;
220
- }
221
- if (state.kind === "corrupt" && state.locked) {
222
- await this.steal("the record is corrupt and the lock is left behind");
245
+ if (stale.kind === "held") {
246
+ await this.steal(_a.STEAL_REASON.deadHolder);
223
247
  return;
224
248
  }
225
- if (state.kind === "absent" && existsSync(this.lockPath())) {
226
- await this.steal("a lock without a record");
227
- }
249
+ await this.steal(stale.kind === "corrupt"
250
+ ? _a.STEAL_REASON.corruptRecord
251
+ : _a.STEAL_REASON.lockOnly);
228
252
  }
229
253
  /** The refusal message — the holder's identity facts as plain text (the words
230
254
  * table owns the CLI's held report; this is the thrown carrier's own summary). */
@@ -232,7 +256,7 @@ export class InFlight {
232
256
  if (holder === null) {
233
257
  return `another dispatch holds the in-flight lock under ${this.#root.path} — the standing record is unreadable (dispatch ${this.#slug} refuses to overwrite it)`;
234
258
  }
235
- return `another dispatch is in flight: pid ${holder.pid} (${holder.command}), slug ${holder.slug}, started ${new Date(holder.startedAt).toISOString()} — it must finish, or its record must be taken over with --steal-stale`;
259
+ return `another dispatch is in flight: pid ${holder.pid} (${holder.command}), slug ${holder.slug}, started ${new Date(holder.startedAt).toISOString()} — it must finish, or its record must be taken over with --recover`;
236
260
  }
237
261
  /** The record write — the JSON shape through the ONE atomic write seam, with the
238
262
  * repo's single trailing newline. */
@@ -275,8 +299,10 @@ export class InFlight {
275
299
  attempt: typeof row.attempt === "number" ? row.attempt : null,
276
300
  briefHash: typeof row.briefHash === "string" ? row.briefHash : null,
277
301
  plan: typeof row.plan === "string" ? row.plan : null,
302
+ dispatchBase: typeof row.dispatchBase === "string" ? row.dispatchBase : null,
278
303
  sampledAt: typeof row.sampledAt === "number" ? row.sampledAt : null,
279
304
  verdict: typeof row.verdict === "string" ? row.verdict : null,
280
305
  };
281
306
  }
282
307
  }
308
+ _a = InFlight;
@@ -688,7 +688,10 @@ export class Ledger {
688
688
  * (a recorded round is a present fact — the same-doc re-review stays refused until
689
689
  * its fix lands). A completed fix (the latest review cycle IS in the fix
690
690
  * completion set) is NOT the pending face — the completed-fix line's re-review
691
- * reopens through the fix round's C5 route (the legacy judgment). */
691
+ * reopens through the fix round's C5 route (the legacy judgment).
692
+ *
693
+ * A SUPERSEDED review (P30 §2.3) is not a candidate: the reopen replaced its
694
+ * judgment, so the fix it awaited is no longer owed. */
692
695
  #pendingFix(key, type) {
693
696
  const data = this.readProgress();
694
697
  if (data === null)
@@ -696,7 +699,7 @@ export class Ledger {
696
699
  const row = _a.rowFor(data, key, type);
697
700
  if (row === undefined)
698
701
  return false;
699
- const reviews = this.#latestCompletedCycleOfRow(row, "review");
702
+ const reviews = this.#latestLiveCycleOfRow(row, "review");
700
703
  if (reviews === 0)
701
704
  return false;
702
705
  if (this.#completedCyclesOfRow(row, "fix").includes(reviews))
@@ -707,6 +710,12 @@ export class Ledger {
707
710
  // stores no status field · D27), never a second read of the carrier here.
708
711
  return carried === null || carried.status === undefined || carried.status !== "APPROVED";
709
712
  }
713
+ /** The line's derived pending-fix fact — the PUBLIC read face of `#pendingFix`
714
+ * (the `--recover` reopen's condition ②, P30 §2.3). One derivation, two readers;
715
+ * never a second walk from the face. */
716
+ pendingFix(key, type) {
717
+ return this.#pendingFix(key, type);
718
+ }
710
719
  /** Read one counter — a failure-category count on record (0 when the file is
711
720
  * missing). The RETIRED key derives from the round records: the soft entries of
712
721
  * every row plus the one each dirty-tree observation derives (design spec §3.3) —
@@ -831,7 +840,7 @@ export class Ledger {
831
840
  if (row === undefined)
832
841
  return { kind: "review" };
833
842
  const reviewLead = targetFaces[type].product.reviewLead;
834
- const reviews = this.#latestCompletedCycleOfRow(row, reviewLead);
843
+ const reviews = this.#latestLiveCycleOfRow(row, reviewLead);
835
844
  if (reviews === 0)
836
845
  return { kind: "review" };
837
846
  if (!this.#completedCyclesOfRow(row, "fix").includes(reviews)) {
@@ -960,6 +969,44 @@ export class Ledger {
960
969
  const cycles = this.#completedCyclesOfRow(row, mode);
961
970
  return cycles.length > 0 ? Math.max(...cycles) : 0;
962
971
  }
972
+ /** The latest completed cycle of a row + mode that no later round SUPERSEDED — the
973
+ * active-hop read of a reopenable line (P30 §2.3: `--recover` replaced the old
974
+ * review's judgment, so it may no longer lead this line's hop). Deliberately a
975
+ * SEPARATE reader from `#latestCompletedCycleOfRow`: closure is a ledger-wide-order
976
+ * fact, and a supersede must never make a closed line look open (`#rowClosed` and the
977
+ * wave-line closure judgment keep the unfiltered read). 0 when none. */
978
+ #latestLiveCycleOfRow(row, mode) {
979
+ const op = RoundRecords.opOf(mode);
980
+ if (op === null)
981
+ return 0;
982
+ const cycles = RoundRecords.of(row)
983
+ .filter((record) => record.op === op && record.verdict.targetAction && record.supersededBy === undefined)
984
+ .map((record) => record.cycle);
985
+ return cycles.length > 0 ? Math.max(...cycles) : 0;
986
+ }
987
+ /** Stamp a completed review round as SUPERSEDED (P30 §2.3) — the `--recover` reopen'
988
+ * s ONE write. It writes no fake completed fix: the old review keeps its own verdict
989
+ * and gains `supersededBy: { cycle, cause: "recover" }`, and the fix identity stays
990
+ * with its requesting review's cycle (D28 unchanged). Idempotent: a second stamp of
991
+ * the same record is a no-op rewrite. Returns whether a completed review of that
992
+ * cycle was stamped. */
993
+ supersedeReview(key, type, cycle, byCycle) {
994
+ const data = this.readProgress();
995
+ if (data === null)
996
+ return false;
997
+ const row = _a.rowFor(data, key, type);
998
+ if (row === undefined)
999
+ return false;
1000
+ const records = [...RoundRecords.of(row)];
1001
+ const index = records.findIndex((record) => record.op === "review" && record.cycle === cycle && record.verdict.targetAction);
1002
+ const target = records[index];
1003
+ if (target === undefined)
1004
+ return false;
1005
+ records[index] = { ...target, supersededBy: { cycle: byCycle, cause: "recover" } };
1006
+ row.rounds = records;
1007
+ this.writeProgress(data);
1008
+ return true;
1009
+ }
963
1010
  /** One mode's completed cycles on a row — the row-level twin of `completedCycles`. */
964
1011
  #completedCyclesOfRow(row, mode) {
965
1012
  const op = RoundRecords.opOf(mode);
@@ -79,7 +79,7 @@ export class PreFlight {
79
79
  gates.push("in-flight");
80
80
  const inFlight = await ctx.inflight.inspect();
81
81
  checked.push(this.#inFlightRow(inFlight));
82
- const held = this.#inFlightRefusal(inFlight, ctx.stealStale === true);
82
+ const held = this.#inFlightRefusal(inFlight, ctx.recover === true);
83
83
  if (held !== null) {
84
84
  return this.#refusal({
85
85
  ok: false,
@@ -223,9 +223,9 @@ export class PreFlight {
223
223
  }
224
224
  /** The in-flight gate's refusal — the three-state judgment + the explicit takeover
225
225
  * flag. A live holder is always refused (the flag never crosses "alive"); a dead
226
- * holder or a corrupt-record-with-lock passes only under `stealStale`; a corrupt
226
+ * holder or a corrupt-record-with-lock passes only under `recover`; a corrupt
227
227
  * record with no lock behind it is no holder at all (pass, named on the row). */
228
- #inFlightRefusal(state, stealStale) {
228
+ #inFlightRefusal(state, recover) {
229
229
  if (state.kind === "held") {
230
230
  if (state.alive) {
231
231
  return {
@@ -233,14 +233,14 @@ export class PreFlight {
233
233
  message: this.#words.inFlightBlocked(state.record, true),
234
234
  };
235
235
  }
236
- if (stealStale)
236
+ if (recover)
237
237
  return null;
238
238
  return {
239
239
  reason: "held",
240
240
  message: this.#words.inFlightBlocked(state.record, false),
241
241
  };
242
242
  }
243
- if (state.kind === "corrupt" && state.locked && !stealStale) {
243
+ if (state.kind === "corrupt" && state.locked && !recover) {
244
244
  return {
245
245
  reason: "corrupt-record",
246
246
  message: this.#words.inFlightWords().corruptLocked,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.7.0",
3
+ "version": "4.8.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {