@oscaner-skills/cdd-engine 4.11.0 → 4.13.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.
@@ -129,6 +129,20 @@ export const CAPSULE_WORDS = {
129
129
  * spec §3.3): the round still concludes, and this line names what was booked.
130
130
  * Fill slot: {message}. */
131
131
  softViolation: "round soft violation: {message}",
132
+ /** The `misplaced = block` report (spec §2.4) — the reason word plus the four
133
+ * sections: the rendered name, every name found in its place, the identity itself
134
+ * and the repair the orchestrator owns. Fill slots: {kind} / {derived} /
135
+ * {found} / {identity}; the repair sentence is fixed (the engine only refuses). */
136
+ artifactIdentity: {
137
+ reason: "artifact-identity · the round's `{kind}` sidecar sits off its rendered name",
138
+ derived: " derived: {derived}",
139
+ found: " found: {found}",
140
+ identity: " identity: {identity}",
141
+ repair: [
142
+ " repair: rename the found file to the derived name — the engine never moves,",
143
+ " rewrites or deletes an artifact; the workspace is yours",
144
+ ],
145
+ },
132
146
  /** The in-flight rows (P21 §2.2) — the held report, the takeover hint, the two
133
147
  * corrupt shapes and the three canonical recovery sentences. */
134
148
  inFlight: {
@@ -145,6 +159,22 @@ export const CAPSULE_WORDS = {
145
159
  "discard the ones that are broken",
146
160
  ],
147
161
  },
162
+ /** The plan-read rows (spec §2.1 · §2.4 · §2.7) — the vocabulary the `PlanRead`
163
+ * value emits: the two read-failure marks, the healthy-but-empty mark, the
164
+ * orphan mark, the program face's undeclared cell and the two orphan
165
+ * diagnostics.
166
+ * `planReadWord(cause)` reads only `io` / `syntax`; the remaining rows are
167
+ * peers, never members of the failure vocabulary. */
168
+ planRead: {
169
+ io: "! unreadable",
170
+ syntax: "! unparseable",
171
+ empty: "(empty plan)",
172
+ orphan: "! no-spec",
173
+ orphanSpec: "the slug names no identity document (index clean miss): {slug} — no overall / phase-spec / single-spec declares it (every plan is written for one phase; add that document or fix the plan's `slug:`)",
174
+ slugMissing: "the plan declares no `slug:` key — add `slug: <workspace-key>` to the plan's front-matter and re-run",
175
+ discarded: "{roots} — {count} discarded candidate(s): the index cannot answer an absence from this surface — check those files (an unreadable or unregistered document hides an identity)",
176
+ cellEmpty: "",
177
+ },
148
178
  /** The cut-short round's late-landing hint — every kill / timeout / crash message
149
179
  * carries it: the child may have written more after the engine stopped watching. */
150
180
  lateLanding: "a late write may land after the round was cut short — check the working tree before starting the review",
@@ -324,6 +354,32 @@ export class Words {
324
354
  softViolation(message) {
325
355
  return CAPSULE_WORDS.softViolation.replace("{message}", message);
326
356
  }
357
+ /** The `misplaced = block` report (spec §2.4) — the reason word over the four
358
+ * fact sections. Every candidate is printed (never a first pick) and the identity
359
+ * section is the SAME identity the rendered name came from, so `derived:` and
360
+ * `identity:` can never name two different coordinates. */
361
+ artifactIdentity(facts) {
362
+ const row = CAPSULE_WORDS.artifactIdentity;
363
+ return [
364
+ row.reason.replace("{kind}", facts.kind),
365
+ row.derived.replace("{derived}", facts.derived),
366
+ row.found.replace("{found}", facts.found.length === 0 ? "(none)" : facts.found.join(" · ")),
367
+ row.identity.replace("{identity}", this.#identityWords(facts.identity)),
368
+ ...row.repair,
369
+ ].join("\n");
370
+ }
371
+ /** One identity as the report's `identity:` value — the round coordinates with the
372
+ * renderer's own attempt default (a missing attempt is attempt 1, so the printed
373
+ * coordinate never contradicts the rendered name). */
374
+ #identityWords(identity) {
375
+ if (identity.domain === "round") {
376
+ const cycle = identity.cycle === undefined ? "" : ` · cycle=${identity.cycle}`;
377
+ return `line=${identity.line} · op=${identity.op}${cycle} · attempt=${identity.attempt ?? 1}`;
378
+ }
379
+ if (identity.domain === "doc")
380
+ return `slug=${identity.slug} · doc-type=${identity.docType}`;
381
+ return `tasks=${identity.tasks ?? "(none)"}`;
382
+ }
327
383
  /** The in-flight wording rows — the held report, the takeover hint, the two corrupt
328
384
  * shapes and the canonical recovery sentences (one source; the CLI fills the held
329
385
  * slots, never re-types a row). */
@@ -376,6 +432,47 @@ export class Words {
376
432
  return CAPSULE_WORDS.lateLanding;
377
433
  }
378
434
  // -------------------------------------------------------------------------
435
+ // plan-read — the `PlanRead` value's word port
436
+ // -------------------------------------------------------------------------
437
+ /** One read-failure mark (`io` / `syntax`) — the failure vocabulary, and only it. */
438
+ planReadWord(cause) {
439
+ return CAPSULE_WORDS.planRead[cause];
440
+ }
441
+ /** The healthy plan carrying no task block yet — never folded into the failure
442
+ * vocabulary (a healthy empty state is not a read failure). */
443
+ planEmptyWord() {
444
+ return CAPSULE_WORDS.planRead.empty;
445
+ }
446
+ /** The orphan mark the doc face, the program cell and the plan row fold into. */
447
+ planOrphanWord() {
448
+ return CAPSULE_WORDS.planRead.orphan;
449
+ }
450
+ /** The `spec-absent` orphan diagnostic — the plan's slug alone (the identity is the
451
+ * slug; the retired derived path has no consumer left). */
452
+ planOrphanSpec(slug) {
453
+ return CAPSULE_WORDS.planRead.orphanSpec.replace("{slug}", slug);
454
+ }
455
+ /** The undecided-scan diagnostic — the dirty doc roots and the count of candidates
456
+ * they dropped (the fact that forbids answering "no plan" / "no identity"). */
457
+ planDiscardedWord(roots, discarded) {
458
+ return CAPSULE_WORDS.planRead.discarded
459
+ .replace("{roots}", roots.join(" · "))
460
+ .replace("{count}", String(discarded));
461
+ }
462
+ /** The `slug-absent` diagnostic — the plan parses but declares no identity key. */
463
+ planSlugMissing() {
464
+ return CAPSULE_WORDS.planRead.slugMissing;
465
+ }
466
+ /** The program face's undeclared cell — `""` belongs to that one semantic. */
467
+ get cellEmpty() {
468
+ return CAPSULE_WORDS.planRead.cellEmpty;
469
+ }
470
+ /** The stderr diagnostic prefix — delegated to the `warn` station row (one
471
+ * source, no second `CDD_WARN:` literal). */
472
+ get warnPrefix() {
473
+ return CAPSULE_WORDS.stations.warn;
474
+ }
475
+ // -------------------------------------------------------------------------
379
476
  // locale — the word-table locale face (the langs projection + the label rows)
380
477
  // -------------------------------------------------------------------------
381
478
  /** The locale key set — the word table's declared languages (the `langs`
@@ -7,19 +7,18 @@
7
7
  //
8
8
  // The sweep is the recovery leg of the invariant: a carrier left writable by a process
9
9
  // killed outside the engine is sealed by the NEXT dispatch's preflight. Its scope is
10
- // the carrier NAME shapes `RoundNaming.isCarrierName` mints — never the directory's
11
- // other JSON (`progress.json` · `base.json` · `*-test-evidence.json` · the crash
12
- // records) and never a `.rulings.json` sidecar.
10
+ // the matrix's `sealed` column, never a tail spelled here: a name the matrix attributes
11
+ // to a row marked `sealed` is sweepable, and every neighbour (`progress.json` ·
12
+ // `base.json` · `*-test-evidence.json` · the crash records · the orchestrator's rulings
13
+ // sidecar) answers `sealed: false` from its own row. A name no row attributes is not a
14
+ // carrier — the naming predicate that used to answer that fallback is retired, because
15
+ // a second name grammar beside the matrix is exactly the double expression this matrix
16
+ // exists to retire. With no matrix at all the sweep seals NOTHING: "no attribution"
17
+ // has no second answer.
13
18
  //
14
19
  // Module-level exports are the class — zero behavior-carrying bare functions.
15
20
  import { chmodSync, readdirSync, statSync } from "node:fs";
16
21
  import path from "node:path";
17
- import { RoundNaming } from "../session/round-naming.js";
18
- /** The ruling sidecar's suffix — a sidecar is written AFTER its carrier is sealed and
19
- * is never sealed itself (spec §2.1). The name rule lives with `CarrierRulings`; this
20
- * is the sweep's own belt-and-braces skip, so a future widening of the carrier
21
- * predicate can never sweep a sidecar. */
22
- const RULINGS_SUFFIX = ".rulings.json";
23
22
  /**
24
23
  * CarrierSeal — the permission-bit face of the engine's carriers. Stateless by
25
24
  * construction (every method is a judgment over a path), so the whole surface is
@@ -44,39 +43,46 @@ export class CarrierSeal {
44
43
  CarrierSeal.#chmod(target, CarrierSeal.WRITABLE);
45
44
  }
46
45
  /** Seal every ORPHAN carrier of one directory and return the names actually sealed.
47
- * An orphan is an engine carrier (the two name shapes `RoundNaming.isCarrierName`
48
- * mints) that is still writable — left behind by a process killed outside the
49
- * engine. `keep` names files the caller holds open itself (this round's own paths);
50
- * a `.rulings.json` sidecar is never touched. Everything else in the directory is
46
+ * An orphan is a name the matrix attributes to a `sealed` row that is still
47
+ * writable — left behind by a process killed outside the engine. `keep` names files
48
+ * the caller holds open itself (this round's own paths); a `.rulings.json` sidecar is
49
+ * never touched (its row is `sealed: false`). Everything else in the directory is
51
50
  * invisible to the sweep, and an already-sealed carrier is zero churn: not returned,
52
- * not rewritten, so an empty array means there was nothing to recover. */
53
- static sweep(directory, keep) {
54
- const strays = CarrierSeal.#strays(directory, keep);
51
+ * not rewritten, so an empty array means there was nothing to recover.
52
+ *
53
+ * `artifacts` is REQUIRED and nullable on purpose: `null` means "this caller holds no
54
+ * matrix", and the sweep then seals nothing — the retired naming predicate is not
55
+ * re-minted here as a fallback, because that would be a second name grammar beside
56
+ * the matrix (the very defect P36 retires). */
57
+ static sweep(directory, keep, artifacts) {
58
+ const strays = CarrierSeal.#strays(directory, keep, artifacts);
55
59
  for (const name of strays)
56
60
  CarrierSeal.seal(path.join(directory, name));
57
61
  return strays;
58
62
  }
59
63
  /** The directory's orphan carrier NAMES — the sweep's judgment, before any chmod. */
60
- static #strays(directory, keep) {
64
+ static #strays(directory, keep, artifacts) {
61
65
  const strays = [];
62
66
  for (const entry of CarrierSeal.#entries(directory)) {
63
67
  if (!entry.isFile())
64
68
  continue;
65
69
  const target = path.join(directory, entry.name);
66
- if (!CarrierSeal.#isStray(target, entry.name, keep))
70
+ if (!CarrierSeal.#isStray(target, entry.name, keep, artifacts))
67
71
  continue;
68
72
  strays.push(entry.name);
69
73
  }
70
74
  return strays;
71
75
  }
72
76
  /** Whether one directory entry is an orphan carrier the sweep must recover: a minted
73
- * carrier name, not held open by the caller, not a ruling sidecar, and NOT already
74
- * sealed. An unreadable entry (a vanished race) is not a stray — the sweep never
75
- * invents a recovery it did not make. */
76
- static #isStray(target, name, keep) {
77
- if (!RoundNaming.isCarrierName(name))
77
+ * carrier name, not held open by the caller, not the orchestrator's rulings sidecar,
78
+ * and NOT already sealed. An unreadable entry (a vanished race) is not a stray — the
79
+ * sweep never invents a recovery it did not make. */
80
+ static #isStray(target, name, keep, artifacts) {
81
+ if (CarrierSeal.#isSidecar(name, artifacts))
78
82
  return false;
79
- if (keep.includes(name) || name.endsWith(RULINGS_SUFFIX))
83
+ if (!CarrierSeal.#isSealedName(name, artifacts))
84
+ return false;
85
+ if (keep.includes(name))
80
86
  return false;
81
87
  try {
82
88
  return (statSync(target).mode & 0o777) !== CarrierSeal.SEALED;
@@ -85,6 +91,23 @@ export class CarrierSeal {
85
91
  return false;
86
92
  }
87
93
  }
94
+ /** Whether one name is the orchestrator's rulings sidecar — asked of the matrix
95
+ * (`attribute` answers the `rulings` kind for every spelling that attributes), so the
96
+ * sidecar tail has ONE spelling home and the sweep holds no second copy of it. */
97
+ static #isSidecar(name, artifacts) {
98
+ return artifacts?.attribute(name)?.kind === "rulings";
99
+ }
100
+ /** Whether one name belongs to a row the matrix marks `sealed`. The matrix's
101
+ * `sealed` column is the ONE answer for every kind a domain registers — the round
102
+ * rows included, which is what makes `draft` / `final` sweepable and the sidecar
103
+ * not. A name no row attributes is not a carrier, and a caller with no matrix has no
104
+ * attribution at all: both answer "not sealed", never a fallback grammar. */
105
+ static #isSealedName(name, artifacts) {
106
+ const attributed = artifacts?.attribute(name) ?? null;
107
+ if (attributed === null)
108
+ return false;
109
+ return artifacts?.rowOf(attributed.kind)?.sealed === true;
110
+ }
88
111
  /** The directory's entries — an unreadable directory (never created) holds no
89
112
  * orphans, so the sweep is a no-op rather than a failure. */
90
113
  static #entries(directory) {