@oscaner-skills/cdd-engine 4.12.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.
- package/README.md +22 -0
- package/README.zh-CN.md +22 -0
- package/dist/contract/invariants.js +11 -6
- package/dist/face/artifacts.js +13 -4
- package/dist/face/board-view.js +326 -58
- package/dist/face/cli.js +180 -63
- package/dist/face/declare.js +10 -6
- package/dist/face/lifecycle.js +119 -102
- 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 +11 -2
- 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/inflight.js +5 -2
- package/dist/session/ledger.js +171 -239
- package/dist/session/next.js +62 -15
- package/dist/session/round-artifacts.js +635 -0
- package/dist/session/round-naming.js +16 -81
- package/dist/session/run.js +14 -13
- package/package.json +1 -1
package/dist/face/lifecycle.js
CHANGED
|
@@ -26,8 +26,8 @@ import { ProcessFacts } from "../infra/proc.js";
|
|
|
26
26
|
import { RoundLog } from "../infra/round-log.js";
|
|
27
27
|
import { BriefRenderer } from "../render/brief.js";
|
|
28
28
|
import { TemplateAssembler } from "../render/templates.js";
|
|
29
|
+
import { ABSENT_READ, ArtifactReads } from "../session/artifact-reads.js";
|
|
29
30
|
import { CarrierIntegrity, CarrierMismatchError } from "../session/carrier-integrity.js";
|
|
30
|
-
import { CarrierRulings } from "../session/carrier-rulings.js";
|
|
31
31
|
import { TargetFaceTable } from "../session/faces.js";
|
|
32
32
|
import { HandoffSchema } from "../session/handoff-schema.js";
|
|
33
33
|
import { InFlight } from "../session/inflight.js";
|
|
@@ -49,6 +49,9 @@ const STRUCTURE_CHANGED = "the plan's structure changed inside this round (the T
|
|
|
49
49
|
* (`interrupted`, the vocabulary's new literal) and prose. One entry, one cause: the
|
|
50
50
|
* fold records WHY the round has no conclusion, never a second diagnosis. */
|
|
51
51
|
const ABORT_INTERRUPTED = RoundViolation.hard("the dispatch was interrupted outside the engine — its in-flight record named a dead holder at takeover, so the round concluded nothing (the same command re-offers it)", "interrupted");
|
|
52
|
+
/** The no-sidecar cell — off the fix face, an unattributable carrier, or a matrix
|
|
53
|
+
* `absent`: the slot stays empty and the gate has nothing to refuse. */
|
|
54
|
+
const NO_ARTIFACT = { kind: "read", value: ABSENT_READ };
|
|
52
55
|
/**
|
|
53
56
|
* CliLifecycle — the lifecycle's dispatch-seam production default (the split contract's
|
|
54
57
|
* lifecycle face; face/cli.ts re-exports it as HarnessDispatch so the composition
|
|
@@ -99,6 +102,12 @@ export class CliLifecycle {
|
|
|
99
102
|
/** Whether this invocation asked to take over a dead holder's record (the
|
|
100
103
|
* `--recover` flag — the only takeover path). */
|
|
101
104
|
#recover;
|
|
105
|
+
/** The artifact matrix this dispatch holds — the composition root's single instance,
|
|
106
|
+
* handed to the seal sweep so the carrier set is read out of ONE table, and read by
|
|
107
|
+
* the rulings face for the sidecar's name. Required: a dispatch that holds no table
|
|
108
|
+
* can not answer "is there a sidecar", and the old nullable field let that wiring bug
|
|
109
|
+
* read as a legal `absent` (the visibility rule's exact inversion). */
|
|
110
|
+
#artifacts;
|
|
102
111
|
/** The HEAD the current dispatch started from (null off a repo / before a spawn) —
|
|
103
112
|
* the postmortem baseline of `commitsSince` AND the in-flight record's
|
|
104
113
|
* `dispatchBase` cell (the killed round's group baseline a takeover restores, §2.2). */
|
|
@@ -126,6 +135,7 @@ export class CliLifecycle {
|
|
|
126
135
|
this.#git = opts.git ?? new GitClient();
|
|
127
136
|
this.#proc = opts.proc ?? ProcessFacts;
|
|
128
137
|
this.#recover = opts.recover ?? false;
|
|
138
|
+
this.#artifacts = opts.artifacts;
|
|
129
139
|
this.#sync = opts.sync ?? new Terminator();
|
|
130
140
|
this.#template = opts.template ?? new TemplateAssembler();
|
|
131
141
|
this.#brief = opts.brief ?? new BriefRenderer();
|
|
@@ -202,7 +212,7 @@ export class CliLifecycle {
|
|
|
202
212
|
dispatchBase: record.dispatchBase,
|
|
203
213
|
verdict: { treeClean: true, targetAction: false },
|
|
204
214
|
violations: [ABORT_INTERRUPTED],
|
|
205
|
-
}
|
|
215
|
+
});
|
|
206
216
|
// P31 T5 §2.4 — the killed round's carrier names close with its abort record: the
|
|
207
217
|
// draft the dead child may have left writable and the final it never materialized.
|
|
208
218
|
// The identity is the record's OWN (op / cycle / attempt), never a re-derivation
|
|
@@ -303,10 +313,11 @@ export class CliLifecycle {
|
|
|
303
313
|
* records, the persisted carrier, the round's baseline) plus the work plane's
|
|
304
314
|
* evidence gate, and the graded entries decide the verdict: a round with no hard
|
|
305
315
|
* entry is done. The judgment's two provider cells are supplied HERE, the single
|
|
306
|
-
* point: `records` is the key's in-register history read
|
|
307
|
-
*
|
|
308
|
-
*
|
|
309
|
-
*
|
|
316
|
+
* point: `records` is the key's in-register history read LITERALLY on that key (the
|
|
317
|
+
* row is the row — a retired spelling reads as absent, P36 §3), and `reviewsPath` is
|
|
318
|
+
* the fix route's `--reviews` carrier, the requester record's own carrier path, or
|
|
319
|
+
* the ledger's resolved review-carrier name — canonical, or the round's landed
|
|
320
|
+
* `final`, never a historical twin's spelling.
|
|
310
321
|
*
|
|
311
322
|
* A death face (a killed child, a non-zero exit, a rejected draft) already carries
|
|
312
323
|
* its authored hard entry and needs no second judgment — the criterion table and
|
|
@@ -366,7 +377,7 @@ export class CliLifecycle {
|
|
|
366
377
|
const judged = await CompletionCriteria.of(this.#opOf(frame)).judge({
|
|
367
378
|
record: this.#judgedRecordOf(frame, outcome),
|
|
368
379
|
row: this.#rowOf(frame),
|
|
369
|
-
records: scene.ledger.recordsOf(frame.key
|
|
380
|
+
records: scene.ledger.recordsOf(frame.key),
|
|
370
381
|
carrier: outcome.carrier ?? null,
|
|
371
382
|
reviewsPath: this.#reviewsPath(frame),
|
|
372
383
|
git: this.#git,
|
|
@@ -422,8 +433,7 @@ export class CliLifecycle {
|
|
|
422
433
|
#rowOf(frame) {
|
|
423
434
|
const ledger = this.#scene.ledger;
|
|
424
435
|
const data = ledger.readProgress();
|
|
425
|
-
return ((data === null ? undefined : Ledger.rowFor(data, frame.key
|
|
426
|
-
ledger.entryFor(frame.key));
|
|
436
|
+
return ((data === null ? undefined : Ledger.rowFor(data, frame.key)) ?? ledger.entryFor(frame.key));
|
|
427
437
|
}
|
|
428
438
|
/** The evidence gate as a graded entry (design spec §3.3) — the work plane's wave /
|
|
429
439
|
* branch rounds write the evidence file at the round identity's own name
|
|
@@ -539,14 +549,18 @@ export class CliLifecycle {
|
|
|
539
549
|
}
|
|
540
550
|
// P31 T2 — the ruling sidecar gate: a sidecar the strict schema refuses stops the
|
|
541
551
|
// round HERE, before the in-flight record is acquired and before any child exists
|
|
542
|
-
// (a written-but-invisible ruling is the defect this gate removes).
|
|
543
|
-
|
|
544
|
-
|
|
552
|
+
// (a written-but-invisible ruling is the defect this gate removes). The judgment is
|
|
553
|
+
// ONE value computed here and handed to BOTH consumers (the gate and the prompt's
|
|
554
|
+
// round-context cell), so the `misplaced` / `invalid` / `ok` answers can never
|
|
555
|
+
// disagree between them — not even across a writer that lands mid-dispatch.
|
|
556
|
+
const artifactCell = this.#artifactCellOf(frame);
|
|
557
|
+
const artifactRefusal = this.#artifactRefusalOf(artifactCell);
|
|
558
|
+
if (artifactRefusal !== null) {
|
|
545
559
|
this.#sealRoundCarriers(frame);
|
|
546
|
-
this.#blocked(
|
|
547
|
-
return { status: "BLOCKED", violations: [RoundViolation.hard(
|
|
560
|
+
this.#blocked(artifactRefusal, false);
|
|
561
|
+
return { status: "BLOCKED", violations: [RoundViolation.hard(artifactRefusal)] };
|
|
548
562
|
}
|
|
549
|
-
const prompt = this.#template.render(this.#valuesOf(frame));
|
|
563
|
+
const prompt = this.#template.render(this.#valuesOf(frame, artifactCell));
|
|
550
564
|
const row = HOSTS[host];
|
|
551
565
|
const cliName = row.cli;
|
|
552
566
|
const args = [...row.invoke.split(" ").filter((part) => part.length > 0)];
|
|
@@ -783,7 +797,7 @@ export class CliLifecycle {
|
|
|
783
797
|
* (empty-valued keys are dropped), so each mode's round context carries only the
|
|
784
798
|
* facts the mode reads. The review criteria/lens are NOT values — they fold into
|
|
785
799
|
* the review type's fixed prefix (§3.7). */
|
|
786
|
-
#valuesOf(frame) {
|
|
800
|
+
#valuesOf(frame, artifactCell) {
|
|
787
801
|
const scene = this.#scene;
|
|
788
802
|
const op = this.#opOf(frame);
|
|
789
803
|
const role = this.#roleOf(frame);
|
|
@@ -808,10 +822,13 @@ export class CliLifecycle {
|
|
|
808
822
|
// would be a short-circuit).
|
|
809
823
|
INPUT_REVIEWS: op === "fix" ? this.#rel(this.#reviewsPath(frame) ?? "") : "",
|
|
810
824
|
// P31 T2 — the ruling sidecar rides the fix input side alone (the review round's
|
|
811
|
-
// own context has no sidecar yet). The path
|
|
812
|
-
//
|
|
813
|
-
//
|
|
814
|
-
|
|
825
|
+
// own context has no sidecar yet). The path is the matrix's `rulings` row rendered
|
|
826
|
+
// from the REVIEWED carrier's identity and the strict schema read composed beside
|
|
827
|
+
// it (`#artifactReadOf`), handed in as the dispatch's ONE judgment: the gate that
|
|
828
|
+
// just approved this dispatch and this slot are the same value, never two reads.
|
|
829
|
+
// An absent, unattributable or refused sidecar leaves the slot empty and the
|
|
830
|
+
// assembler drops the line.
|
|
831
|
+
INPUT_RULINGS: this.#rulingsInputOf(artifactCell),
|
|
815
832
|
// The kind-named judged-doc anchors (the semantic retirement of the generic
|
|
816
833
|
// INPUT_DOC): the plan line carries the plan document as its judged doc
|
|
817
834
|
// (INPUT_PLAN) AND its design-spec reference (INPUT_SPEC — the `spec:`
|
|
@@ -909,7 +926,7 @@ export class CliLifecycle {
|
|
|
909
926
|
* draft of a retried round) is already closed when it is reopened here: the window
|
|
910
927
|
* is the two names, never a third file. */
|
|
911
928
|
#openRoundCarriers(frame) {
|
|
912
|
-
CarrierSeal.sweep(this.#scene.workspace.path, []);
|
|
929
|
+
CarrierSeal.sweep(this.#scene.workspace.path, [], this.#artifacts);
|
|
913
930
|
for (const name of this.#roundCarrierNames(frame))
|
|
914
931
|
CarrierSeal.unseal(name);
|
|
915
932
|
}
|
|
@@ -1101,7 +1118,7 @@ export class CliLifecycle {
|
|
|
1101
1118
|
#dispositionsSummary(frame, plane, carrier) {
|
|
1102
1119
|
if (plane !== "work" || this.#opOf(frame) !== "fix")
|
|
1103
1120
|
return undefined;
|
|
1104
|
-
const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key
|
|
1121
|
+
const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key), frame.round, this.#reviewsPath(frame), this.#repoRootValue().absolute);
|
|
1105
1122
|
if (requester.kind !== "read")
|
|
1106
1123
|
return undefined;
|
|
1107
1124
|
const counts = new FixDispositions().summaryOf(carrier, requester.findings);
|
|
@@ -1142,7 +1159,7 @@ export class CliLifecycle {
|
|
|
1142
1159
|
* requesting carrier's path and its digest. */
|
|
1143
1160
|
#requesterRecord(frame) {
|
|
1144
1161
|
const reviewed = this.#scene.ledger
|
|
1145
|
-
.recordsOf(frame.key
|
|
1162
|
+
.recordsOf(frame.key)
|
|
1146
1163
|
.filter((record) => record.op === "review" && record.cycle === frame.round);
|
|
1147
1164
|
return reviewed.reduce((newest, record) => (newest === null || record.attempt >= newest.attempt ? record : newest), null);
|
|
1148
1165
|
}
|
|
@@ -1152,7 +1169,13 @@ export class CliLifecycle {
|
|
|
1152
1169
|
* already existed before this dispatch (`INPUT_REVIEWS` is its own input), so every
|
|
1153
1170
|
* other phase has no gate to set. A carrier with no recorded digest — a legacy round,
|
|
1154
1171
|
* or a resolved path no record declared — is read as present facts: no comparison,
|
|
1155
|
-
* no refusal.
|
|
1172
|
+
* no refusal.
|
|
1173
|
+
*
|
|
1174
|
+
* The repo-relative carrier → absolute erasure is spelled here, and again inside the
|
|
1175
|
+
* sidecar seam (`session/artifact-reads.ts`), BY DESIGN: this one feeds the digest
|
|
1176
|
+
* read of the carrier's own bytes, that one feeds the schema's `carrier` comparison
|
|
1177
|
+
* and the sidecar's id set. The two are different reads of different files, not two
|
|
1178
|
+
* names for one fact. */
|
|
1156
1179
|
#carrierRefusal(frame) {
|
|
1157
1180
|
if (this.#opOf(frame) !== "fix")
|
|
1158
1181
|
return null;
|
|
@@ -1179,92 +1202,86 @@ export class CliLifecycle {
|
|
|
1179
1202
|
return this.#requesterRecord(frame)?.carrierDigest ?? null;
|
|
1180
1203
|
}
|
|
1181
1204
|
/** The fix round's ruling sidecar as the round-context value — the repo-relative
|
|
1182
|
-
* sidecar path
|
|
1183
|
-
*
|
|
1184
|
-
* resolved carrier, and when the sidecar is absent — the assembler drops the empty
|
|
1185
|
-
* line). The strict judgment is the dispatch gate's `#rulingsRefusal`; this cell
|
|
1186
|
-
* names the file the round may read AND states the verdicts (§2.5 AC: the rendered
|
|
1187
|
-
* text matches the sidecar), so a ruling is never merely a path the child must
|
|
1188
|
-
* re-open to discover. */
|
|
1189
|
-
#rulingsInputOf(frame) {
|
|
1190
|
-
if (this.#opOf(frame) !== "fix")
|
|
1191
|
-
return "";
|
|
1192
|
-
const carrier = this.#reviewsPath(frame);
|
|
1193
|
-
if (carrier === null)
|
|
1194
|
-
return "";
|
|
1195
|
-
const verdict = this.#rulingsVerdict(frame, carrier);
|
|
1196
|
-
if (verdict.kind !== "ok")
|
|
1197
|
-
return "";
|
|
1198
|
-
const sidecar = this.#rel(CarrierRulings.pathFor(carrier));
|
|
1199
|
-
return [sidecar, ...verdict.rulings.map((ruling) => this.#rulingLine(ruling))].join("\n");
|
|
1200
|
-
}
|
|
1201
|
-
/** One rendering of a recorded ruling — the finding id it answers and the ruling's
|
|
1202
|
-
* own text VERBATIM (never re-worded: the sidecar is the orchestrator's words, and
|
|
1203
|
-
* the round context quotes them). Indented under the sidecar path's bullet so the
|
|
1204
|
-
* cell reads as one input. */
|
|
1205
|
-
#rulingLine(ruling) {
|
|
1206
|
-
return ` - \`${ruling.finding}\` — ${ruling.ruling}`;
|
|
1207
|
-
}
|
|
1208
|
-
/** The pre-dispatch ruling gate — the strict sidecar verdict's refusal reason, or null
|
|
1209
|
-
* when the round may proceed (no fix face, no resolved carrier, an absent sidecar, or
|
|
1210
|
-
* a conforming one). A refusal is HARD and lands before the in-flight record and the
|
|
1211
|
-
* child, so a broken ruling set can never be dispatched unnoticed (§2.6).
|
|
1205
|
+
* sidecar path alone, the empty string otherwise (off the fix face and when the
|
|
1206
|
+
* sidecar is absent — the assembler drops the empty line).
|
|
1212
1207
|
*
|
|
1213
|
-
*
|
|
1214
|
-
*
|
|
1215
|
-
*
|
|
1216
|
-
|
|
1208
|
+
* One input, one reading: the round context names WHERE the rulings live, exactly as
|
|
1209
|
+
* `INPUT_REVIEWS` names the carrier it qualifies (spec §2.10). The ruling bodies stay
|
|
1210
|
+
* in the sidecar — the child opens the file — so the prompt tail carries no text whose
|
|
1211
|
+
* length the orchestrator's ruling set decides, and the sidecar keeps its single
|
|
1212
|
+
* source. The path is the artifact matrix's `rulings` render of the REVIEWED round's
|
|
1213
|
+
* identity, never a tail replacement on the carrier's name: the carrier's own spelling
|
|
1214
|
+
* (draft or final) can no longer move it.
|
|
1215
|
+
*
|
|
1216
|
+
* The judgment is the dispatch's OWN cell — the value the gate just read — so the cell
|
|
1217
|
+
* can never name a ruling set the refusal is about to reject. */
|
|
1218
|
+
#rulingsInputOf(cell) {
|
|
1219
|
+
if (cell.kind !== "read")
|
|
1220
|
+
return "";
|
|
1221
|
+
const { read } = cell.value;
|
|
1222
|
+
return read.kind === "ok" ? this.#rel(read.path) : "";
|
|
1223
|
+
}
|
|
1224
|
+
/** The artifact-identity gate as a PURE read — the `--dry-run` face's entry to the
|
|
1225
|
+
* same judgment the real dispatch applies before it takes the in-flight record and
|
|
1226
|
+
* before any child exists. The preview renders the returned reason verbatim, so a
|
|
1227
|
+
* dry run can never forecast a dispatch the real run would refuse (one read, two
|
|
1228
|
+
* faces). Nothing here writes: the read is the matrix's plus the strict schema's. */
|
|
1229
|
+
artifactRefusal(frame) {
|
|
1230
|
+
return this.#artifactRefusalOf(this.#artifactCellOf(frame));
|
|
1231
|
+
}
|
|
1232
|
+
/** The dispatch's artifact judgment — computed ONCE, then consumed by the gate and by
|
|
1233
|
+
* the prompt's round-context cell. Off the fix face there is nothing to read (no
|
|
1234
|
+
* requesting carrier, no sidecar), so the cell is the no-sidecar value; otherwise the
|
|
1235
|
+
* one read is taken here, and a tampered requesting carrier becomes the integrity arm
|
|
1236
|
+
* instead of a read (its id set is not a fact this round may read). */
|
|
1237
|
+
#artifactCellOf(frame) {
|
|
1217
1238
|
if (this.#opOf(frame) !== "fix")
|
|
1218
|
-
return
|
|
1219
|
-
const carrier = this.#reviewsPath(frame);
|
|
1220
|
-
if (carrier === null)
|
|
1221
|
-
return null;
|
|
1222
|
-
let verdict;
|
|
1239
|
+
return NO_ARTIFACT;
|
|
1223
1240
|
try {
|
|
1224
|
-
|
|
1241
|
+
return { kind: "read", value: this.#artifactReadOf(frame, "rulings") };
|
|
1225
1242
|
}
|
|
1226
1243
|
catch (raw) {
|
|
1227
1244
|
if (!(raw instanceof CarrierMismatchError))
|
|
1228
1245
|
throw raw;
|
|
1229
|
-
return raw.message;
|
|
1230
|
-
}
|
|
1231
|
-
return verdict.kind === "invalid" ? `rulings sidecar — ${verdict.reason}` : null;
|
|
1232
|
-
}
|
|
1233
|
-
/** The strict sidecar verdict over the requesting carrier's CHECKED id set — one call
|
|
1234
|
-
* shape for the gate and the round-context cell, so neither can read the ids by a
|
|
1235
|
-
* path the other does not take. */
|
|
1236
|
-
#rulingsVerdict(frame, carrier) {
|
|
1237
|
-
return CarrierRulings.verdict(carrier, this.#carrierFindingIds(frame, carrier));
|
|
1238
|
-
}
|
|
1239
|
-
/** The requesting carrier's engine-written finding ids (`F1`, `F2` …) — the id set a
|
|
1240
|
-
* ruling must name. The read is the ONE checked carrier read (`CarrierIntegrity.read`,
|
|
1241
|
-
* the digest its review round recorded): a tampered carrier is never observed at all —
|
|
1242
|
-
* the mismatch throws and the integrity refusal wins over any ruling reason. An absent
|
|
1243
|
-
* or unparseable carrier declares no ids, so any ruling beside it is refused by the
|
|
1244
|
-
* strict schema instead of being accepted against an empty set. */
|
|
1245
|
-
#carrierFindingIds(frame, carrier) {
|
|
1246
|
-
const ids = new Set();
|
|
1247
|
-
let carrierJson;
|
|
1248
|
-
try {
|
|
1249
|
-
const bytes = CarrierIntegrity.read(path.resolve(this.#repoRootValue().absolute, carrier), this.#requesterDigest(frame));
|
|
1250
|
-
if (bytes === null)
|
|
1251
|
-
return ids;
|
|
1252
|
-
carrierJson = JSON.parse(bytes);
|
|
1253
|
-
}
|
|
1254
|
-
catch (raw) {
|
|
1255
|
-
if (raw instanceof CarrierMismatchError)
|
|
1256
|
-
throw raw;
|
|
1257
|
-
return ids;
|
|
1258
|
-
}
|
|
1259
|
-
const findings = carrierJson?.findings;
|
|
1260
|
-
if (!Array.isArray(findings))
|
|
1261
|
-
return ids;
|
|
1262
|
-
for (const finding of findings) {
|
|
1263
|
-
const id = finding?.id;
|
|
1264
|
-
if (typeof id === "string")
|
|
1265
|
-
ids.add(id);
|
|
1246
|
+
return { kind: "mismatch", message: raw.message };
|
|
1266
1247
|
}
|
|
1267
|
-
|
|
1248
|
+
}
|
|
1249
|
+
/** The ONE artifact read of this round's `kind` — delegated to the frame-free seam
|
|
1250
|
+
* (`session/artifact-reads.ts`), so this face keeps only the frame-level facts: the
|
|
1251
|
+
* requesting carrier and the digest its record remembered. The board reads the SAME
|
|
1252
|
+
* seam with its own workspace, so the prompt cell, the gate and the board can never
|
|
1253
|
+
* compose two different judgments (spec §2.3). */
|
|
1254
|
+
#artifactReadOf(frame, kind) {
|
|
1255
|
+
return new ArtifactReads(this.#artifacts, this.#scene.workspace).read(kind, this.#reviewsPath(frame) ?? "", this.#requesterDigest(frame));
|
|
1256
|
+
}
|
|
1257
|
+
/** The pre-dispatch artifact gate over the dispatch's ONE cell — the refusal reason of
|
|
1258
|
+
* this round's resolved `rulings` kind, or null when the round may proceed (no fix
|
|
1259
|
+
* face, no resolved carrier, an absent sidecar, or one conforming). A refusal is HARD
|
|
1260
|
+
* and lands before the in-flight record and the child, so a broken ruling set can
|
|
1261
|
+
* never be dispatched unnoticed (§2.4).
|
|
1262
|
+
*
|
|
1263
|
+
* Two refusal shapes, two words: a name that attributes to the identity but is NOT
|
|
1264
|
+
* its rendered name is `artifact-identity` (the four-section report — every candidate
|
|
1265
|
+
* listed, never a pick), while a present-but-unreadable file or a schema violation
|
|
1266
|
+
* keeps today's `rulings sidecar — <reason>` (the reason verbatim from the read).
|
|
1267
|
+
*
|
|
1268
|
+
* A `carrier-mismatch` from the sidecar's id read is the integrity refusal, never a
|
|
1269
|
+
* ruling reason: a tampered carrier is not judged (its id set is not a fact this
|
|
1270
|
+
* round may read), so the diagnostic names the bytes that changed. */
|
|
1271
|
+
#artifactRefusalOf(cell) {
|
|
1272
|
+
if (cell.kind === "mismatch")
|
|
1273
|
+
return cell.message;
|
|
1274
|
+
const read = cell.value.read;
|
|
1275
|
+
if (read.kind === "invalid")
|
|
1276
|
+
return `rulings sidecar — ${read.reason}`;
|
|
1277
|
+
if (read.kind !== "misplaced")
|
|
1278
|
+
return null;
|
|
1279
|
+
return this.#words.artifactIdentity({
|
|
1280
|
+
kind: "rulings",
|
|
1281
|
+
derived: this.#rel(this.#scene.workspace.resolve(read.derived)),
|
|
1282
|
+
found: read.found.map((name) => this.#rel(this.#scene.workspace.resolve(name))),
|
|
1283
|
+
identity: read.identity,
|
|
1284
|
+
});
|
|
1268
1285
|
}
|
|
1269
1286
|
/** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
|
|
1270
1287
|
* same-command resume's decision source: the attempted handoff + the resume
|
package/dist/face/preview.js
CHANGED
|
@@ -78,6 +78,15 @@ export class Preview {
|
|
|
78
78
|
lines.push(this.#words.inFlightWords().corruptLocked);
|
|
79
79
|
return lines;
|
|
80
80
|
}
|
|
81
|
+
/** The read-only artifact-identity block — the dispatch gate REFUSED this dispatch
|
|
82
|
+
* (`misplaced` sidecar / unreadable one / a schema violation), so the preview prints
|
|
83
|
+
* the gate's OWN reason verbatim: one read, two faces, and a dry run can never
|
|
84
|
+
* forecast a dispatch the real run would refuse. Exit 1 at the caller; nothing is
|
|
85
|
+
* written, moved or deleted (the repair is the orchestrator's). */
|
|
86
|
+
artifactBlock(verb, reason) {
|
|
87
|
+
const [head, ...sections] = reason.split("\n");
|
|
88
|
+
return [`cdd ${verb}: preview (no repo changes)`, ` refused: ${head ?? ""}`, ...sections];
|
|
89
|
+
}
|
|
81
90
|
/** The `lock:` row's value — the holder's identity facts, the lock-without-record
|
|
82
91
|
* shape, or the free state (one row, three facts). */
|
|
83
92
|
#lockValueOf(state) {
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
// The route-borne prose (the fix readback suffix · the soft-cap message) rides
|
|
19
19
|
// declared constants from session/next.ts, rendered by reference, never restated.
|
|
20
20
|
// Module-level exports are the class — zero behavior-carrying bare functions.
|
|
21
|
-
import { FIX_READBACK_SUFFIX, NEXT_HOP_REASON } from "../session/next.js";
|
|
21
|
+
import { FIX_READBACK_SLOT, FIX_READBACK_SUFFIX, NEXT_HOP_REASON, } from "../session/next.js";
|
|
22
22
|
import { REFS } from "./host.js";
|
|
23
23
|
/**
|
|
24
24
|
* RouteRenderer — the single route → `next:` literal face (D40). One instance holds
|
|
@@ -153,7 +153,13 @@ export class RouteRenderer {
|
|
|
153
153
|
* <readback>` (the readback suffix the declared constant, rendered by reference).
|
|
154
154
|
* Every embedded path value (the doc-id for the doc shapes · `--reviews`)
|
|
155
155
|
* is normalized to the repoRoot-relative shape (D47); the wave face's `<type-arg>`
|
|
156
|
-
* is a task key, not a path — passed through as-is.
|
|
156
|
+
* is a task key, not a path — passed through as-is.
|
|
157
|
+
*
|
|
158
|
+
* The readback sentence's PATH is a value the route carries (`Route.rulings`, rendered
|
|
159
|
+
* by the router from the carrier's own round identity): this face fills the declared
|
|
160
|
+
* slot and derives nothing. A route with no `rulings` value — a carrier the matrix
|
|
161
|
+
* cannot place — omits the sentence whole, so the line never prints an empty slot nor
|
|
162
|
+
* falls back to the naming rule the sentence used to teach. */
|
|
157
163
|
#fixText(route, target) {
|
|
158
164
|
if (route.reviews === undefined)
|
|
159
165
|
return this.#words.routeWord("fix");
|
|
@@ -161,22 +167,32 @@ export class RouteRenderer {
|
|
|
161
167
|
const type = target?.type ?? null;
|
|
162
168
|
const id = target?.id ?? "";
|
|
163
169
|
const reviews = this.#rel(route.reviews);
|
|
170
|
+
const readback = this.#readbackOf(route);
|
|
164
171
|
if (type === "wave") {
|
|
165
|
-
return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${id} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews}
|
|
172
|
+
return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${id} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews}${readback}`;
|
|
166
173
|
}
|
|
167
174
|
if (type === "plan") {
|
|
168
|
-
return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews}
|
|
175
|
+
return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews}${readback}`;
|
|
169
176
|
}
|
|
170
177
|
if (type === "branch") {
|
|
171
178
|
// The branch fix literal carries the workspace-identity `--plan` (isomorphic
|
|
172
179
|
// with the wave fix branch — a plan-less target resolves to the empty
|
|
173
180
|
// ref.short() directory, the workspace double identity).
|
|
174
|
-
return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews}
|
|
181
|
+
return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews}${readback}`;
|
|
175
182
|
}
|
|
176
183
|
if (type === null)
|
|
177
|
-
return `${verb} ${this.#flag("reviews")} ${reviews}
|
|
184
|
+
return `${verb} ${this.#flag("reviews")} ${reviews}${readback}`;
|
|
178
185
|
// phase-spec · overall · single-spec — the declared shapes ride `--spec`.
|
|
179
|
-
return `${verb} ${this.#flag("type")} ${type} ${this.#flag("spec")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews}
|
|
186
|
+
return `${verb} ${this.#flag("type")} ${type} ${this.#flag("spec")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews}${readback}`;
|
|
187
|
+
}
|
|
188
|
+
/** The fix readback sentence with the route's sidecar path in its value slot — the
|
|
189
|
+
* empty string when the route carries none (zero slot, zero sentence). The path is
|
|
190
|
+
* normalized through the ONE basis, exactly as the gate's `derived:` row is, so the
|
|
191
|
+
* two faces print one path byte for byte. */
|
|
192
|
+
#readbackOf(route) {
|
|
193
|
+
if (route.rulings === undefined)
|
|
194
|
+
return "";
|
|
195
|
+
return ` ${FIX_READBACK_SUFFIX.replace(FIX_READBACK_SLOT, this.#rel(route.rulings))}`;
|
|
180
196
|
}
|
|
181
197
|
/** The face-to-face handoff render — the pipeline entry: a `ref` fills the declared
|
|
182
198
|
* instruction phrase (`route to {ref} skill`, the word table's `handoffRef` row)
|
package/dist/face/words.js
CHANGED
|
@@ -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: {
|
|
@@ -156,8 +170,9 @@ export const CAPSULE_WORDS = {
|
|
|
156
170
|
syntax: "! unparseable",
|
|
157
171
|
empty: "(empty plan)",
|
|
158
172
|
orphan: "! no-spec",
|
|
159
|
-
orphanSpec: "the
|
|
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:`)",
|
|
160
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)",
|
|
161
176
|
cellEmpty: "",
|
|
162
177
|
},
|
|
163
178
|
/** The cut-short round's late-landing hint — every kill / timeout / crash message
|
|
@@ -339,6 +354,32 @@ export class Words {
|
|
|
339
354
|
softViolation(message) {
|
|
340
355
|
return CAPSULE_WORDS.softViolation.replace("{message}", message);
|
|
341
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
|
+
}
|
|
342
383
|
/** The in-flight wording rows — the held report, the takeover hint, the two corrupt
|
|
343
384
|
* shapes and the canonical recovery sentences (one source; the CLI fills the held
|
|
344
385
|
* slots, never re-types a row). */
|
|
@@ -406,12 +447,17 @@ export class Words {
|
|
|
406
447
|
planOrphanWord() {
|
|
407
448
|
return CAPSULE_WORDS.planRead.orphan;
|
|
408
449
|
}
|
|
409
|
-
/** The `spec-absent` orphan diagnostic — the plan's slug
|
|
410
|
-
*
|
|
411
|
-
planOrphanSpec(slug
|
|
412
|
-
return CAPSULE_WORDS.planRead.orphanSpec
|
|
413
|
-
|
|
414
|
-
|
|
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));
|
|
415
461
|
}
|
|
416
462
|
/** The `slug-absent` diagnostic — the plan parses but declares no identity key. */
|
|
417
463
|
planSlugMissing() {
|
|
@@ -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
|
|
11
|
-
//
|
|
12
|
-
// records
|
|
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
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
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
|
-
|
|
54
|
-
|
|
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
|
|
74
|
-
* sealed. An unreadable entry (a vanished race) is not a stray — the
|
|
75
|
-
* invents a recovery it did not make. */
|
|
76
|
-
static #isStray(target, name, keep) {
|
|
77
|
-
if (
|
|
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 (
|
|
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) {
|