@oscaner-skills/cdd-engine 4.8.0 → 4.9.1
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/dist/contract/completion-criterion.js +45 -16
- package/dist/contract/invariants.js +26 -1
- package/dist/contract/rules.js +12 -6
- package/dist/face/board-view.js +6 -6
- package/dist/face/cli.js +10 -0
- package/dist/face/lifecycle.js +292 -5
- package/dist/infra/carrier-seal.js +110 -0
- package/dist/infra/git.js +26 -0
- package/dist/infra/workspace.js +20 -3
- package/dist/render/templates.js +6 -0
- package/dist/session/carrier-integrity.js +128 -0
- package/dist/session/carrier-rulings.js +167 -0
- package/dist/session/ledger.js +109 -12
- package/dist/session/next.js +10 -9
- package/dist/session/reviewed-identity.js +15 -0
- package/dist/session/round-naming.js +44 -4
- package/dist/session/run.js +71 -12
- package/package.json +1 -1
|
@@ -23,8 +23,8 @@
|
|
|
23
23
|
// Module-level exports are types / the declared registry / the class — zero
|
|
24
24
|
// behavior-carrying bare functions.
|
|
25
25
|
var _a, _b;
|
|
26
|
-
import { readFileSync } from "node:fs";
|
|
27
26
|
import path from "node:path";
|
|
27
|
+
import { CarrierIntegrity, CarrierMismatchError } from "../session/carrier-integrity.js";
|
|
28
28
|
import { RoundViolation, } from "../session/ledger.js";
|
|
29
29
|
/**
|
|
30
30
|
* CommitsSinceGroupBase — the implement criterion: the round is done when the GROUP
|
|
@@ -214,18 +214,12 @@ export const FIX_DISPOSITIONS_UNRECORDED = "the requesting review round records
|
|
|
214
214
|
* answers from the carrier, never from the diff.
|
|
215
215
|
*/
|
|
216
216
|
export class FixDispositions {
|
|
217
|
-
/** The requesting carrier's path — the
|
|
218
|
-
* row's records are already the key's)
|
|
219
|
-
* legacy record without `carrierPath` falls back to
|
|
217
|
+
/** The requesting carrier's path — the LATEST attempt of the same-cycle review of the
|
|
218
|
+
* SAME key (the row's records are already the key's), the record whose digest the
|
|
219
|
+
* checked read compares against; a legacy record without `carrierPath` falls back to
|
|
220
|
+
* the route's `--reviews` path. */
|
|
220
221
|
static requesterPathOf(records, cycle, reviewsPath) {
|
|
221
|
-
|
|
222
|
-
if (record.op !== "review" || record.cycle !== cycle)
|
|
223
|
-
continue;
|
|
224
|
-
if (!record.verdict.targetAction)
|
|
225
|
-
continue;
|
|
226
|
-
return record.carrierPath ?? reviewsPath;
|
|
227
|
-
}
|
|
228
|
-
return reviewsPath;
|
|
222
|
+
return _b.#requesterOf(records, cycle)?.carrierPath ?? reviewsPath;
|
|
229
223
|
}
|
|
230
224
|
/** Read the requesting carrier's input set (the findings, deduped by disposition
|
|
231
225
|
* key in carrier order). The read is synchronous on purpose: the input is ONE small
|
|
@@ -235,17 +229,33 @@ export class FixDispositions {
|
|
|
235
229
|
* Every path resolves against `repoRoot`, never `process.cwd()`: the engine runs
|
|
236
230
|
* from a subdirectory too, `--reviews` arrives repoRoot-relative and a record's
|
|
237
231
|
* `carrierPath` arrives absolute — both must land on the one basis (`RepoRoot`'s
|
|
238
|
-
* rule). The reported `path` is the resolved one, so a failure names a real file.
|
|
232
|
+
* rule). The reported `path` is the resolved one, so a failure names a real file.
|
|
233
|
+
*
|
|
234
|
+
* P31 §2.2 — the read is the ONE checked carrier read (`CarrierIntegrity.read`):
|
|
235
|
+
* the requesting round's recorded digest decides ok / mismatch, so a tampered
|
|
236
|
+
* input throws instead of being judged as if the round had written those bytes. */
|
|
239
237
|
static requesterInputOf(records, cycle, reviewsPath, repoRoot) {
|
|
240
|
-
const
|
|
238
|
+
const requester = _b.#requesterOf(records, cycle);
|
|
239
|
+
const declared = requester?.carrierPath ?? reviewsPath;
|
|
241
240
|
if (declared === null)
|
|
242
241
|
return { kind: "unrecorded" };
|
|
243
242
|
const target = path.resolve(repoRoot, declared);
|
|
244
243
|
let carrier;
|
|
245
244
|
try {
|
|
246
|
-
|
|
245
|
+
// P31 §2.2 — the input carrier is read through the ONE checked seam: the
|
|
246
|
+
// requesting review record's digest when it declared the path, no comparison on
|
|
247
|
+
// the legacy `--reviews` fallback. A mismatch is NOT an `unreadable` input (that
|
|
248
|
+
// would silently judge the tampered bytes): the error propagates and the CLI's
|
|
249
|
+
// blocked channel names it.
|
|
250
|
+
const bytes = CarrierIntegrity.read(target, _b.#requesterDigestOf(requester));
|
|
251
|
+
if (bytes === null) {
|
|
252
|
+
return { kind: "unreadable", path: target, detail: "the file is absent or not JSON" };
|
|
253
|
+
}
|
|
254
|
+
carrier = JSON.parse(bytes);
|
|
247
255
|
}
|
|
248
|
-
catch {
|
|
256
|
+
catch (raw) {
|
|
257
|
+
if (raw instanceof CarrierMismatchError)
|
|
258
|
+
throw raw;
|
|
249
259
|
return { kind: "unreadable", path: target, detail: "the file is absent or not JSON" };
|
|
250
260
|
}
|
|
251
261
|
const findings = carrier?.findings;
|
|
@@ -266,6 +276,25 @@ export class FixDispositions {
|
|
|
266
276
|
}
|
|
267
277
|
return { kind: "read", path: target, findings: set.findings };
|
|
268
278
|
}
|
|
279
|
+
/** THE requesting record — the LATEST attempt of the same-cycle review (a re-dispatch
|
|
280
|
+
* supersedes its predecessor, the same rule the ledger's checked carrier read and the
|
|
281
|
+
* dispatch gate apply). Path AND digest come from this one record, so a re-dispatched
|
|
282
|
+
* review is never read against its predecessor's digest: the gate and this criterion
|
|
283
|
+
* cannot disagree about which review round the fix is answering. */
|
|
284
|
+
static #requesterOf(records, cycle) {
|
|
285
|
+
return records
|
|
286
|
+
.filter((record) => record.op === "review" && record.cycle === cycle)
|
|
287
|
+
.reduce((newest, record) => newest === undefined || record.attempt >= newest.attempt ? record : newest, undefined);
|
|
288
|
+
}
|
|
289
|
+
/** The digest the requesting review round recorded — read off the SAME record
|
|
290
|
+
* `requesterPathOf` selects. Null when that record declared no path (the legacy
|
|
291
|
+
* `--reviews` fallback carries no digest, so the read performs no comparison) or when
|
|
292
|
+
* the record predates the digest column. */
|
|
293
|
+
static #requesterDigestOf(record) {
|
|
294
|
+
if (record === undefined || record.carrierPath === null)
|
|
295
|
+
return null;
|
|
296
|
+
return record.carrierDigest ?? null;
|
|
297
|
+
}
|
|
269
298
|
/** The carrier's `dispositions` map — null when the slot is absent or not an
|
|
270
299
|
* object (the criterion's own shape refusal; the schema only pins the slot type). */
|
|
271
300
|
static dispositionsOf(carrier) {
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
// cross-doc-chain · section-scoped-domain ·
|
|
10
10
|
// phase-design-spec-is-phase-spec;
|
|
11
11
|
// the change-history family — change-history-version-unique ·
|
|
12
|
-
// change-history-row-shape ·
|
|
12
|
+
// change-history-header-columns · change-history-row-shape ·
|
|
13
13
|
// change-history-latest-matches-front-matter ·
|
|
14
14
|
// front-matter-version-in-lineage ·
|
|
15
15
|
// change-history-row-not-in-other-table · list-marker-not-doubled;
|
|
@@ -447,6 +447,31 @@ export class ChangeHistoryRowShapeInvariant extends Invariant {
|
|
|
447
447
|
return findings;
|
|
448
448
|
}
|
|
449
449
|
}
|
|
450
|
+
/** The DECLARED `## Change history` column set — the header must equal it cell for
|
|
451
|
+
* cell (after `trim`). The row-shape leg judges a row against whatever the header
|
|
452
|
+
* declares; this declaration is what makes the header itself a judged fact. */
|
|
453
|
+
export const CHANGE_HISTORY_COLUMNS = ["Version", "date", "summary", "author"];
|
|
454
|
+
/** change-history-header-columns — the `## Change history` header must BE the declared
|
|
455
|
+
* column set: a grown, dropped or renamed column silently redefines what every row
|
|
456
|
+
* means, so it is reported once, independently of the row widths (the two legs are
|
|
457
|
+
* orthogonal: this one reads the header, `change-history-row-shape` reads the rows
|
|
458
|
+
* against that header). An absent section / header judges nothing here. */
|
|
459
|
+
export class ChangeHistoryHeaderColumnsInvariant extends Invariant {
|
|
460
|
+
name = "change-history-header-columns";
|
|
461
|
+
evaluate(ctx) {
|
|
462
|
+
const header = this.changeHistory(ctx).headerRow;
|
|
463
|
+
if (header === null || header.length === 0)
|
|
464
|
+
return [];
|
|
465
|
+
const cells = header.map((cell) => cell.trim());
|
|
466
|
+
const declared = CHANGE_HISTORY_COLUMNS;
|
|
467
|
+
const conforms = cells.length === declared.length && cells.every((cell, index) => cell === declared[index]);
|
|
468
|
+
if (conforms)
|
|
469
|
+
return [];
|
|
470
|
+
return [
|
|
471
|
+
this.finding(ctx, "Change history", `the Change-history header reads "${cells.join(" | ")}" against the declared "${declared.join(" | ")}"`, `write the header as | ${declared.join(" | ")} | — the column set is declared, not free-form`),
|
|
472
|
+
];
|
|
473
|
+
}
|
|
474
|
+
}
|
|
450
475
|
/** change-history-latest-matches-front-matter — the front-matter `version:` IS the
|
|
451
476
|
* lineage's newest numeric version: appending a row lifts both in the same edit, so
|
|
452
477
|
* the two sides can never disagree. */
|
package/dist/contract/rules.js
CHANGED
|
@@ -18,15 +18,15 @@
|
|
|
18
18
|
// multi-surface strategies of the old family were split per leg (uniqueness → three,
|
|
19
19
|
// order → one section-order row, selfBounded → one lineage row), so a declaration row
|
|
20
20
|
// never hides a second rule. Version ORDER stays presentation, not data integrity; the
|
|
21
|
-
// header-to-newest-row agreement and the row's cell shape
|
|
22
|
-
// own (`change-history-latest-matches-front-matter` ·
|
|
23
|
-
//
|
|
24
|
-
// version).
|
|
21
|
+
// header-to-newest-row agreement, the header's own column set and the row's cell shape
|
|
22
|
+
// are declared legs of their own (`change-history-latest-matches-front-matter` ·
|
|
23
|
+
// `change-history-header-columns` · `change-history-row-shape`), and the lineage
|
|
24
|
+
// identity read is membership-plus-anchor (the first cell must BE a version).
|
|
25
25
|
//
|
|
26
26
|
// Module-level exports are types / the declared data — zero behavior-carrying bare
|
|
27
27
|
// functions.
|
|
28
|
-
import { ChangeHistoryLatestMatchesFrontMatterInvariant, ChangeHistoryRowShapeInvariant, ChangeHistoryVersionUniqueInvariant, ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, FrontMatterVersionInLineageInvariant, HollowInvariant, LedgerLayeringRule, LedgerTaskSetRule, LinkShapeInvariant, ListMarkerInvariant, PhaseDesignSpecIsPhaseSpecInvariant, PhaseIdUniqueInvariant, PresenceInvariant, ResidueInvariant, RowHomeInvariant, SectionOrderInvariant, SectionScopedDomainInvariant, SiblingScanInvariant, SlugRefInvariant, TaskIdUniqueInvariant, WaveWidthInvariant, } from "./invariants.js";
|
|
29
|
-
/** The rule registry — doc scope
|
|
28
|
+
import { ChangeHistoryHeaderColumnsInvariant, ChangeHistoryLatestMatchesFrontMatterInvariant, ChangeHistoryRowShapeInvariant, ChangeHistoryVersionUniqueInvariant, ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, FrontMatterVersionInLineageInvariant, HollowInvariant, LedgerLayeringRule, LedgerTaskSetRule, LinkShapeInvariant, ListMarkerInvariant, PhaseDesignSpecIsPhaseSpecInvariant, PhaseIdUniqueInvariant, PresenceInvariant, ResidueInvariant, RowHomeInvariant, SectionOrderInvariant, SectionScopedDomainInvariant, SiblingScanInvariant, SlugRefInvariant, TaskIdUniqueInvariant, WaveWidthInvariant, } from "./invariants.js";
|
|
29
|
+
/** The rule registry — doc scope 24 rows + ledger scope 2 rows = 26. */
|
|
30
30
|
export const RULE_REGISTRY = [
|
|
31
31
|
{ scope: "doc", id: "presence", docKeys: "all", create: () => new PresenceInvariant() },
|
|
32
32
|
{
|
|
@@ -41,6 +41,12 @@ export const RULE_REGISTRY = [
|
|
|
41
41
|
docKeys: "all",
|
|
42
42
|
create: () => new ChangeHistoryRowShapeInvariant(),
|
|
43
43
|
},
|
|
44
|
+
{
|
|
45
|
+
scope: "doc",
|
|
46
|
+
id: "change-history-header-columns",
|
|
47
|
+
docKeys: "all",
|
|
48
|
+
create: () => new ChangeHistoryHeaderColumnsInvariant(),
|
|
49
|
+
},
|
|
44
50
|
{
|
|
45
51
|
scope: "doc",
|
|
46
52
|
id: "change-history-latest-matches-front-matter",
|
package/dist/face/board-view.js
CHANGED
|
@@ -44,6 +44,7 @@ import { RepoRoot } from "../infra/root.js";
|
|
|
44
44
|
import { ENGINE_RUNTIME } from "../infra/runtime.js";
|
|
45
45
|
import { SlugIndex } from "../infra/slug-index.js";
|
|
46
46
|
import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
|
|
47
|
+
import { CarrierIntegrity } from "../session/carrier-integrity.js";
|
|
47
48
|
import { TaskGraph } from "../session/graph.js";
|
|
48
49
|
import { Ledger, RoundRecords } from "../session/ledger.js";
|
|
49
50
|
import { PipelineFrontier } from "../session/pipeline.js";
|
|
@@ -265,13 +266,12 @@ export class BoardView {
|
|
|
265
266
|
}
|
|
266
267
|
/** One round's findings count — the `findings` array length of the carrier the round
|
|
267
268
|
* persisted (the judge plane's declared field). Zero when the record carries no
|
|
268
|
-
* carrier path or the file is absent
|
|
269
|
-
*
|
|
269
|
+
* carrier path or the file is absent (present facts only). P31 §2.2 — the read goes
|
|
270
|
+
* through the ONE checked seam: a carrier whose bytes no longer match the recorded
|
|
271
|
+
* digest THROWS (`carrier-mismatch` rides the CLI's blocked channel), never a
|
|
272
|
+
* silent zero. */
|
|
270
273
|
static #findingsCountOf(record) {
|
|
271
|
-
const
|
|
272
|
-
if (at === null)
|
|
273
|
-
return 0;
|
|
274
|
-
const text = BoardView.#read(at);
|
|
274
|
+
const text = CarrierIntegrity.readFor(record);
|
|
275
275
|
if (text === null)
|
|
276
276
|
return 0;
|
|
277
277
|
try {
|
package/dist/face/cli.js
CHANGED
|
@@ -60,6 +60,7 @@ import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
|
|
|
60
60
|
import { BriefRenderer } from "../render/brief.js";
|
|
61
61
|
import { IssueBodyRenderer } from "../render/issue-body.js";
|
|
62
62
|
import { TemplateAssembler } from "../render/templates.js";
|
|
63
|
+
import { CarrierMismatchError } from "../session/carrier-integrity.js";
|
|
63
64
|
import { DispatchAuthority, } from "../session/dispatch-authority.js";
|
|
64
65
|
import { TargetFaceTable, targetFaces, } from "../session/faces.js";
|
|
65
66
|
import { TaskGraph } from "../session/graph.js";
|
|
@@ -222,6 +223,15 @@ export class Cli {
|
|
|
222
223
|
* invalid argument (incl. the preAction conditional-required) · excess args ·
|
|
223
224
|
* missing required) → 2, an unexpected error → 1. */
|
|
224
225
|
#normalizeExit(err) {
|
|
226
|
+
// P31 §2.2 — a carrier whose bytes no longer digest to the recorded value is a
|
|
227
|
+
// hard stop on the CDD_BLOCKED channel (the ordered-rank of every blocked gate),
|
|
228
|
+
// with the existing blocked exit code. The read faces that can meet it (board's
|
|
229
|
+
// `+N` count, the fix criterion's input, the ledger's carrier read) all throw it
|
|
230
|
+
// through their own seam.
|
|
231
|
+
if (err instanceof CarrierMismatchError) {
|
|
232
|
+
this.#io.stderr(`${this.#words.station("blocked")} ${err.message}\n`);
|
|
233
|
+
return 1;
|
|
234
|
+
}
|
|
225
235
|
if (err instanceof CommanderError) {
|
|
226
236
|
if (err.code === "commander.help")
|
|
227
237
|
return err.exitCode === 0 ? 0 : 2;
|
package/dist/face/lifecycle.js
CHANGED
|
@@ -15,15 +15,19 @@ var _a;
|
|
|
15
15
|
// The module exports the shared seams + the lifecycle class — zero behavior-carrying
|
|
16
16
|
// bare functions.
|
|
17
17
|
import { existsSync, readFileSync } from "node:fs";
|
|
18
|
+
import path from "node:path";
|
|
18
19
|
import process from "node:process";
|
|
19
20
|
import { printParseErrorCode } from "jsonc-parser";
|
|
20
21
|
import { CompletionCriteria, FixDispositions } from "../contract/completion-criterion.js";
|
|
21
22
|
import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
|
|
23
|
+
import { CarrierSeal } from "../infra/carrier-seal.js";
|
|
22
24
|
import { GitClient } from "../infra/git.js";
|
|
23
25
|
import { ProcessFacts } from "../infra/proc.js";
|
|
24
26
|
import { RoundLog } from "../infra/round-log.js";
|
|
25
27
|
import { BriefRenderer } from "../render/brief.js";
|
|
26
28
|
import { TemplateAssembler } from "../render/templates.js";
|
|
29
|
+
import { CarrierIntegrity, CarrierMismatchError } from "../session/carrier-integrity.js";
|
|
30
|
+
import { CarrierRulings } from "../session/carrier-rulings.js";
|
|
27
31
|
import { TargetFaceTable } from "../session/faces.js";
|
|
28
32
|
import { HandoffSchema } from "../session/handoff-schema.js";
|
|
29
33
|
import { InFlight } from "../session/inflight.js";
|
|
@@ -200,8 +204,19 @@ export class CliLifecycle {
|
|
|
200
204
|
violations: [ABORT_INTERRUPTED],
|
|
201
205
|
carrierPath: null,
|
|
202
206
|
}, "wave");
|
|
207
|
+
// P31 T5 §2.4 — the killed round's carrier names close with its abort record: the
|
|
208
|
+
// draft the dead child may have left writable and the final it never materialized.
|
|
209
|
+
// The identity is the record's OWN (the same op/cycle the abort booked), never a
|
|
210
|
+
// re-derivation from the current frontier.
|
|
211
|
+
this.#sealRoundCarriersOf(op, "wave", _a.#waveParams(key, cycle, op));
|
|
203
212
|
return true;
|
|
204
213
|
}
|
|
214
|
+
/** The handoff params of a wave round, replayed from a dead holder's record — the
|
|
215
|
+
* same shaping the frame builder applies (the implement family is round-less, the
|
|
216
|
+
* review / fix families carry the cycle). */
|
|
217
|
+
static #waveParams(key, cycle, op) {
|
|
218
|
+
return op === "implement" ? { tasks: key } : { tasks: key, round: cycle };
|
|
219
|
+
}
|
|
205
220
|
/** One dispatch — the round's work, the observation facts every record carries (the
|
|
206
221
|
* dispatch baseline HEAD captured before the spawn, the dispatch-after
|
|
207
222
|
* `treeClean` observation) and the TERMINAL VERDICT the round is booked under
|
|
@@ -228,6 +243,9 @@ export class CliLifecycle {
|
|
|
228
243
|
...drafted,
|
|
229
244
|
dispatchBase: this.#dispatchBase,
|
|
230
245
|
treeClean: await this.#git.isClean(this.#scene.workspace.root.repoRoot),
|
|
246
|
+
// P31 §2.7 — whether THIS round's commits touched the document its write-back
|
|
247
|
+
// binds. Measured once, here, from the same baseline the postmortem reads.
|
|
248
|
+
touchedDoc: await this.#touchedDocOf(carried),
|
|
231
249
|
};
|
|
232
250
|
const judged = await this.#verdictOf(carried, observed);
|
|
233
251
|
// The death faces author their own entry AND emit their own line (`#reject`), so
|
|
@@ -247,6 +265,31 @@ export class CliLifecycle {
|
|
|
247
265
|
violations: judged.violations,
|
|
248
266
|
};
|
|
249
267
|
}
|
|
268
|
+
/** The document path the round's write-back would bind (P31 §2.7) — the doc leg's
|
|
269
|
+
* target document, the branch leg's plan document. The wave leg binds a brief
|
|
270
|
+
* PROJECTION rather than a document, so it does not participate (null). */
|
|
271
|
+
#reviewedDocTargetOf(frame) {
|
|
272
|
+
if (frame.target.kind === "plan" || frame.target.kind === "spec")
|
|
273
|
+
return frame.target.doc;
|
|
274
|
+
if (frame.type === "branch")
|
|
275
|
+
return this.#scene.planPath;
|
|
276
|
+
return null;
|
|
277
|
+
}
|
|
278
|
+
/** Whether this round's own commits touched that document — `true` / `false` read off
|
|
279
|
+
* the `dispatchBase..HEAD` path set, `null` when the range cannot be read (no
|
|
280
|
+
* baseline / unreadable repo), `undefined` when the leg binds no document. The four
|
|
281
|
+
* states stay distinct all the way to the bookkeep: only `false` may skip the bind,
|
|
282
|
+
* and `null` books its own soft observation. */
|
|
283
|
+
async #touchedDocOf(frame) {
|
|
284
|
+
const target = this.#reviewedDocTargetOf(frame);
|
|
285
|
+
if (target === null)
|
|
286
|
+
return undefined;
|
|
287
|
+
const repoRoot = this.#scene.workspace.root.repoRoot;
|
|
288
|
+
const touched = await this.#git.pathsSince(repoRoot, this.#dispatchBase);
|
|
289
|
+
if (touched === null)
|
|
290
|
+
return null;
|
|
291
|
+
return touched.includes(path.relative(repoRoot, path.resolve(repoRoot, target)));
|
|
292
|
+
}
|
|
250
293
|
/** The round's concluded status under its verdict — a done round keeps its handoff
|
|
251
294
|
* conclusion (APPROVED when the handoff was never written: the completion criterion
|
|
252
295
|
* concluded it), and a hard-failed round concludes BLOCKED — or keeps TIMEOUT, the
|
|
@@ -471,6 +514,34 @@ export class CliLifecycle {
|
|
|
471
514
|
this.#io.stderr("CDD_BLOCKED: no host harness detected (run cdd from within a supported harness)\n");
|
|
472
515
|
return { status: "BLOCKED" };
|
|
473
516
|
}
|
|
517
|
+
// P31 T5 §2.4 — the preflight half of the seal cycle: the workspace's ORPHAN
|
|
518
|
+
// carriers first (a process killed outside the engine leaves a writable carrier
|
|
519
|
+
// behind), then this round's OWN two names become writable — its draft for the
|
|
520
|
+
// child, its final for the materialization. The scope is the round's own paths,
|
|
521
|
+
// never the directory or the slug: an input carrier of an earlier round (the fix
|
|
522
|
+
// leg's `--reviews`) stays 0o444 for the whole dispatch.
|
|
523
|
+
this.#openRoundCarriers(frame);
|
|
524
|
+
// P31 T3 — the carrier-integrity gate: the fix round's requesting carrier is
|
|
525
|
+
// compared against the digest its round recorded BEFORE the in-flight record and
|
|
526
|
+
// the child, so a tampered input never reaches a child (the read-back and the CLI
|
|
527
|
+
// catch are the fallbacks, never the gate). It runs BEFORE the ruling gate: the
|
|
528
|
+
// integrity diagnostic is the fact, and a sidecar judged against tampered bytes
|
|
529
|
+
// would name a ruling reason for a carrier whose bytes simply changed.
|
|
530
|
+
const carrierRefusal = this.#carrierRefusal(frame);
|
|
531
|
+
if (carrierRefusal !== null) {
|
|
532
|
+
this.#sealRoundCarriers(frame);
|
|
533
|
+
this.#blocked(carrierRefusal, false);
|
|
534
|
+
return { status: "BLOCKED", violations: [RoundViolation.hard(carrierRefusal)] };
|
|
535
|
+
}
|
|
536
|
+
// P31 T2 — the ruling sidecar gate: a sidecar the strict schema refuses stops the
|
|
537
|
+
// round HERE, before the in-flight record is acquired and before any child exists
|
|
538
|
+
// (a written-but-invisible ruling is the defect this gate removes).
|
|
539
|
+
const rulingsRefusal = this.#rulingsRefusal(frame);
|
|
540
|
+
if (rulingsRefusal !== null) {
|
|
541
|
+
this.#sealRoundCarriers(frame);
|
|
542
|
+
this.#blocked(rulingsRefusal, false);
|
|
543
|
+
return { status: "BLOCKED", violations: [RoundViolation.hard(rulingsRefusal)] };
|
|
544
|
+
}
|
|
474
545
|
const prompt = this.#template.render(this.#valuesOf(frame));
|
|
475
546
|
const row = HOSTS[host];
|
|
476
547
|
const cliName = row.cli;
|
|
@@ -482,7 +553,17 @@ export class CliLifecycle {
|
|
|
482
553
|
// A sibling dispatch that won the lock in between makes `acquire` throw
|
|
483
554
|
// `HoldingError` (carrying the holder's facts), which rides the CLI's held BLOCK.
|
|
484
555
|
this.#dispatchBase = await this.#git.head(this.#scene.workspace.root.repoRoot);
|
|
485
|
-
|
|
556
|
+
try {
|
|
557
|
+
await this.#inflight.acquire(await this.#recordOf(frame), { recover: this.#recover });
|
|
558
|
+
}
|
|
559
|
+
catch (raw) {
|
|
560
|
+
// P31 T5 §2.4 — the preflight half already opened this round's two names, so
|
|
561
|
+
// EVERY exit after it closes them, including this one: a losing dispatch (the
|
|
562
|
+
// gate→acquire race the CLI renders as the held BLOCK) must not leave a
|
|
563
|
+
// writable carrier behind for the next preflight sweep to recover.
|
|
564
|
+
this.#sealRoundCarriers(frame);
|
|
565
|
+
throw raw;
|
|
566
|
+
}
|
|
486
567
|
// The round's own log file — created BEFORE the spawn (append stream open, zero
|
|
487
568
|
// bytes), so the channel exists from the dispatch's first millisecond. A create
|
|
488
569
|
// failure is a named soft observation and the round continues on the CPU leg
|
|
@@ -713,6 +794,11 @@ export class CliLifecycle {
|
|
|
713
794
|
// carrier; a review writes its own draft (INPUT_REVIEWS === OUTPUT_HANDOFF
|
|
714
795
|
// would be a short-circuit).
|
|
715
796
|
INPUT_REVIEWS: op === "fix" ? this.#rel(this.#reviewsPath(frame) ?? "") : "",
|
|
797
|
+
// P31 T2 — the ruling sidecar rides the fix input side alone (the review round's
|
|
798
|
+
// own context has no sidecar yet). The path derives from the requesting carrier
|
|
799
|
+
// by the ONE `.json` → `.rulings.json` rule; an absent sidecar leaves the slot
|
|
800
|
+
// empty, so the assembler drops the line entirely.
|
|
801
|
+
INPUT_RULINGS: this.#rulingsInputOf(frame),
|
|
716
802
|
// The kind-named judged-doc anchors (the semantic retirement of the generic
|
|
717
803
|
// INPUT_DOC): the plan/branch lines carry the plan document (INPUT_PLAN — the
|
|
718
804
|
// doc path on a plan line, the plan path on a branch line, whose review/fix
|
|
@@ -797,6 +883,47 @@ export class CliLifecycle {
|
|
|
797
883
|
return lines.slice(-STDOUT_TAIL_MAX);
|
|
798
884
|
}
|
|
799
885
|
// -------------------------------------------------------------------------
|
|
886
|
+
// the carrier seal cycle (P31 T5 §2.4) — the round's own write window
|
|
887
|
+
// -------------------------------------------------------------------------
|
|
888
|
+
/** P31 §2.4 preflight — recover the workspace's orphans, then open THIS round's own
|
|
889
|
+
* two names. The sweep runs FIRST so a carrier this round is about to own (a stale
|
|
890
|
+
* draft of a retried round) is already closed when it is reopened here: the window
|
|
891
|
+
* is the two names, never a third file. */
|
|
892
|
+
#openRoundCarriers(frame) {
|
|
893
|
+
CarrierSeal.sweep(this.#scene.workspace.path, []);
|
|
894
|
+
for (const name of this.#roundCarrierNames(frame))
|
|
895
|
+
CarrierSeal.unseal(name);
|
|
896
|
+
}
|
|
897
|
+
/** P31 §2.4 terminal — close the round's own write window. Every exit path that ran
|
|
898
|
+
* the preflight half calls this (a gate refusal, a death face, an abort fold), so no
|
|
899
|
+
* terminal leaves an engine carrier writable. */
|
|
900
|
+
#sealRoundCarriers(frame) {
|
|
901
|
+
this.#sealRoundCarriersOf(this.#opOf(frame), frame.type, frame.params);
|
|
902
|
+
}
|
|
903
|
+
/** The seal of one (op, type, params) identity — the frame-shaped callers and the
|
|
904
|
+
* dead-holder fold share this ONE derivation. */
|
|
905
|
+
#sealRoundCarriersOf(op, type, params) {
|
|
906
|
+
for (const name of this.#roundCarrierNamesOf(op, type, params))
|
|
907
|
+
CarrierSeal.seal(name);
|
|
908
|
+
}
|
|
909
|
+
/** A frame's own carrier paths — the child's draft (`Ledger#handoffPath`, the family
|
|
910
|
+
* table's fill) and the engine's final (`RoundNaming#finalPath`, `.c{N}` suffixed).
|
|
911
|
+
* A round-less family (implement) resolves both to the same path — one name, sealed
|
|
912
|
+
* once. */
|
|
913
|
+
#roundCarrierNames(frame) {
|
|
914
|
+
return this.#roundCarrierNamesOf(this.#opOf(frame), frame.type, frame.params);
|
|
915
|
+
}
|
|
916
|
+
/** `#roundCarrierNames` over an identity — the abort fold's entry (it holds a dead
|
|
917
|
+
* holder's op/cycle, never a frame). */
|
|
918
|
+
#roundCarrierNamesOf(op, type, params) {
|
|
919
|
+
const ledger = this.#scene.ledger;
|
|
920
|
+
const draftName = ledger.handoffName(op, type, params);
|
|
921
|
+
return [
|
|
922
|
+
this.#scene.workspace.resolve(draftName),
|
|
923
|
+
this.#naming.finalPath(draftName, params.round),
|
|
924
|
+
];
|
|
925
|
+
}
|
|
926
|
+
// -------------------------------------------------------------------------
|
|
800
927
|
// the read-back reconstruct (§3.6) — the draft is the round's content
|
|
801
928
|
// -------------------------------------------------------------------------
|
|
802
929
|
/** The ONE draft-read point — the frame's handoff draft read with the lenient
|
|
@@ -917,11 +1044,24 @@ export class CliLifecycle {
|
|
|
917
1044
|
// carriers the ledger reads back, never a schema-validated draft).
|
|
918
1045
|
const status = schema.conclusionOf(plane, draft) ?? "BLOCKED";
|
|
919
1046
|
const carrier = this.#materialize(frame, plane, draft, status);
|
|
1047
|
+
// P31 §2.2 — the disposition summary reads the REQUESTING carrier. A mismatch
|
|
1048
|
+
// found here (the bytes moved inside the round) is a BLOCKED outcome: the read-back
|
|
1049
|
+
// is the FALLBACK behind the pre-dispatch gate, never the gate itself.
|
|
1050
|
+
let summary;
|
|
1051
|
+
try {
|
|
1052
|
+
summary = this.#dispositionsSummary(frame, plane, carrier);
|
|
1053
|
+
}
|
|
1054
|
+
catch (raw) {
|
|
1055
|
+
if (!(raw instanceof CarrierMismatchError))
|
|
1056
|
+
throw raw;
|
|
1057
|
+
this.#blocked(raw.message, false);
|
|
1058
|
+
return { status: "BLOCKED", violations: [RoundViolation.hard(raw.message)] };
|
|
1059
|
+
}
|
|
920
1060
|
return {
|
|
921
1061
|
status,
|
|
922
1062
|
findings: plane === "judge" ? schema.findingsOf(findings) : undefined,
|
|
923
1063
|
carrier,
|
|
924
|
-
dispositionsSummary:
|
|
1064
|
+
dispositionsSummary: summary,
|
|
925
1065
|
};
|
|
926
1066
|
}
|
|
927
1067
|
/** The fix round's ONE summary line (design spec §3.4) — computed from the PERSISTED
|
|
@@ -943,8 +1083,12 @@ export class CliLifecycle {
|
|
|
943
1083
|
/** The requesting review carrier's path — the fix round's `--reviews` input, or the
|
|
944
1084
|
* ledger's resolved review handoff path when the route carried none (the ONE
|
|
945
1085
|
* resolution the round context's INPUT_REVIEWS and the disposition summary share).
|
|
946
|
-
*
|
|
947
|
-
* the
|
|
1086
|
+
* Four layers, ONE identity (P31 §2.3): the explicit `--reviews` flag → the
|
|
1087
|
+
* same-cycle review record's own `carrierPath` (the FINAL carrier the round wrote) →
|
|
1088
|
+
* the ledger's resolved family name (a draft, or a migrated line's retired twin —
|
|
1089
|
+
* the carrier that EXISTS, never the never-minted canonical spelling) → the legacy
|
|
1090
|
+
* `null`. Record-present means final-wins: a draft sitting beside the final never
|
|
1091
|
+
* becomes the judged input.
|
|
948
1092
|
*
|
|
949
1093
|
* A same-cycle review record that RECORDED no carrier path, with no carrier at
|
|
950
1094
|
* either spelling on disk, leaves the requester input UNRECORDED: the answer is
|
|
@@ -955,6 +1099,9 @@ export class CliLifecycle {
|
|
|
955
1099
|
#reviewsPath(frame) {
|
|
956
1100
|
if (this.#reviews !== null)
|
|
957
1101
|
return this.#reviews;
|
|
1102
|
+
const recorded = this.#requesterRecord(frame)?.carrierPath;
|
|
1103
|
+
if (typeof recorded === "string" && recorded !== "")
|
|
1104
|
+
return recorded;
|
|
958
1105
|
const resolved = this.#scene.ledger.resolveHandoffPath("review", frame.type, frame.params);
|
|
959
1106
|
if (existsSync(resolved))
|
|
960
1107
|
return resolved;
|
|
@@ -963,6 +1110,136 @@ export class CliLifecycle {
|
|
|
963
1110
|
.some((record) => record.op === "review" && record.cycle === frame.round && record.carrierPath === null);
|
|
964
1111
|
return legacy ? null : resolved;
|
|
965
1112
|
}
|
|
1113
|
+
/** The same-cycle review record this fix round answers — its LATEST attempt (a
|
|
1114
|
+
* re-dispatched review supersedes its predecessor, the same rule the round-read gate
|
|
1115
|
+
* applies). Null when the line records no review for this cycle. ONE basis for the
|
|
1116
|
+
* requesting carrier's path and its digest. */
|
|
1117
|
+
#requesterRecord(frame) {
|
|
1118
|
+
const reviewed = this.#scene.ledger
|
|
1119
|
+
.recordsOf(frame.key, frame.type)
|
|
1120
|
+
.filter((record) => record.op === "review" && record.cycle === frame.round);
|
|
1121
|
+
return reviewed.reduce((newest, record) => (newest === null || record.attempt >= newest.attempt ? record : newest), null);
|
|
1122
|
+
}
|
|
1123
|
+
/** The fix input's carrier-integrity gate — the `carrier-mismatch` refusal when the
|
|
1124
|
+
* requesting review carrier no longer digests to the value its round recorded, null
|
|
1125
|
+
* when the round may proceed (P31 §2.2). Only the fix face reads a carrier that
|
|
1126
|
+
* already existed before this dispatch (`INPUT_REVIEWS` is its own input), so every
|
|
1127
|
+
* other phase has no gate to set. A carrier with no recorded digest — a legacy round,
|
|
1128
|
+
* or a resolved path no record declared — is read as present facts: no comparison,
|
|
1129
|
+
* no refusal. */
|
|
1130
|
+
#carrierRefusal(frame) {
|
|
1131
|
+
if (this.#opOf(frame) !== "fix")
|
|
1132
|
+
return null;
|
|
1133
|
+
const carrier = this.#reviewsPath(frame);
|
|
1134
|
+
if (carrier === null)
|
|
1135
|
+
return null;
|
|
1136
|
+
const digest = this.#requesterDigest(frame);
|
|
1137
|
+
if (digest === null)
|
|
1138
|
+
return null;
|
|
1139
|
+
try {
|
|
1140
|
+
CarrierIntegrity.read(path.resolve(this.#repoRootValue().absolute, carrier), digest);
|
|
1141
|
+
return null;
|
|
1142
|
+
}
|
|
1143
|
+
catch (raw) {
|
|
1144
|
+
if (raw instanceof CarrierMismatchError)
|
|
1145
|
+
return raw.message;
|
|
1146
|
+
throw raw;
|
|
1147
|
+
}
|
|
1148
|
+
}
|
|
1149
|
+
/** The digest the requesting review round recorded — the same-cycle review record's
|
|
1150
|
+
* latest attempt (the round `#reviewsPath` resolves). Null when no record carries
|
|
1151
|
+
* one: the present-facts read. */
|
|
1152
|
+
#requesterDigest(frame) {
|
|
1153
|
+
return this.#requesterRecord(frame)?.carrierDigest ?? null;
|
|
1154
|
+
}
|
|
1155
|
+
/** The fix round's ruling sidecar as the round-context value — the repo-relative
|
|
1156
|
+
* sidecar path when a conforming sidecar sits beside the requesting carrier, plus the
|
|
1157
|
+
* ruling bodies it carries, the empty string otherwise (off the fix face, with no
|
|
1158
|
+
* resolved carrier, and when the sidecar is absent — the assembler drops the empty
|
|
1159
|
+
* line). The strict judgment is the dispatch gate's `#rulingsRefusal`; this cell
|
|
1160
|
+
* names the file the round may read AND states the verdicts (§2.5 AC: the rendered
|
|
1161
|
+
* text matches the sidecar), so a ruling is never merely a path the child must
|
|
1162
|
+
* re-open to discover. */
|
|
1163
|
+
#rulingsInputOf(frame) {
|
|
1164
|
+
if (this.#opOf(frame) !== "fix")
|
|
1165
|
+
return "";
|
|
1166
|
+
const carrier = this.#reviewsPath(frame);
|
|
1167
|
+
if (carrier === null)
|
|
1168
|
+
return "";
|
|
1169
|
+
const verdict = this.#rulingsVerdict(frame, carrier);
|
|
1170
|
+
if (verdict.kind !== "ok")
|
|
1171
|
+
return "";
|
|
1172
|
+
const sidecar = this.#rel(CarrierRulings.pathFor(carrier));
|
|
1173
|
+
return [sidecar, ...verdict.rulings.map((ruling) => this.#rulingLine(ruling))].join("\n");
|
|
1174
|
+
}
|
|
1175
|
+
/** One rendering of a recorded ruling — the finding id it answers and the ruling's
|
|
1176
|
+
* own text VERBATIM (never re-worded: the sidecar is the orchestrator's words, and
|
|
1177
|
+
* the round context quotes them). Indented under the sidecar path's bullet so the
|
|
1178
|
+
* cell reads as one input. */
|
|
1179
|
+
#rulingLine(ruling) {
|
|
1180
|
+
return ` - \`${ruling.finding}\` — ${ruling.ruling}`;
|
|
1181
|
+
}
|
|
1182
|
+
/** The pre-dispatch ruling gate — the strict sidecar verdict's refusal reason, or null
|
|
1183
|
+
* when the round may proceed (no fix face, no resolved carrier, an absent sidecar, or
|
|
1184
|
+
* a conforming one). A refusal is HARD and lands before the in-flight record and the
|
|
1185
|
+
* child, so a broken ruling set can never be dispatched unnoticed (§2.6).
|
|
1186
|
+
*
|
|
1187
|
+
* A `carrier-mismatch` from the sidecar's id read is the integrity refusal, never a
|
|
1188
|
+
* ruling reason: a tampered carrier is not judged (its id set is not a fact this
|
|
1189
|
+
* round may read), so the diagnostic names the bytes that changed. */
|
|
1190
|
+
#rulingsRefusal(frame) {
|
|
1191
|
+
if (this.#opOf(frame) !== "fix")
|
|
1192
|
+
return null;
|
|
1193
|
+
const carrier = this.#reviewsPath(frame);
|
|
1194
|
+
if (carrier === null)
|
|
1195
|
+
return null;
|
|
1196
|
+
let verdict;
|
|
1197
|
+
try {
|
|
1198
|
+
verdict = this.#rulingsVerdict(frame, carrier);
|
|
1199
|
+
}
|
|
1200
|
+
catch (raw) {
|
|
1201
|
+
if (!(raw instanceof CarrierMismatchError))
|
|
1202
|
+
throw raw;
|
|
1203
|
+
return raw.message;
|
|
1204
|
+
}
|
|
1205
|
+
return verdict.kind === "invalid" ? `rulings sidecar — ${verdict.reason}` : null;
|
|
1206
|
+
}
|
|
1207
|
+
/** The strict sidecar verdict over the requesting carrier's CHECKED id set — one call
|
|
1208
|
+
* shape for the gate and the round-context cell, so neither can read the ids by a
|
|
1209
|
+
* path the other does not take. */
|
|
1210
|
+
#rulingsVerdict(frame, carrier) {
|
|
1211
|
+
return CarrierRulings.verdict(carrier, this.#carrierFindingIds(frame, carrier));
|
|
1212
|
+
}
|
|
1213
|
+
/** The requesting carrier's engine-written finding ids (`F1`, `F2` …) — the id set a
|
|
1214
|
+
* ruling must name. The read is the ONE checked carrier read (`CarrierIntegrity.read`,
|
|
1215
|
+
* the digest its review round recorded): a tampered carrier is never observed at all —
|
|
1216
|
+
* the mismatch throws and the integrity refusal wins over any ruling reason. An absent
|
|
1217
|
+
* or unparseable carrier declares no ids, so any ruling beside it is refused by the
|
|
1218
|
+
* strict schema instead of being accepted against an empty set. */
|
|
1219
|
+
#carrierFindingIds(frame, carrier) {
|
|
1220
|
+
const ids = new Set();
|
|
1221
|
+
let carrierJson;
|
|
1222
|
+
try {
|
|
1223
|
+
const bytes = CarrierIntegrity.read(path.resolve(this.#repoRootValue().absolute, carrier), this.#requesterDigest(frame));
|
|
1224
|
+
if (bytes === null)
|
|
1225
|
+
return ids;
|
|
1226
|
+
carrierJson = JSON.parse(bytes);
|
|
1227
|
+
}
|
|
1228
|
+
catch (raw) {
|
|
1229
|
+
if (raw instanceof CarrierMismatchError)
|
|
1230
|
+
throw raw;
|
|
1231
|
+
return ids;
|
|
1232
|
+
}
|
|
1233
|
+
const findings = carrierJson?.findings;
|
|
1234
|
+
if (!Array.isArray(findings))
|
|
1235
|
+
return ids;
|
|
1236
|
+
for (const finding of findings) {
|
|
1237
|
+
const id = finding?.id;
|
|
1238
|
+
if (typeof id === "string")
|
|
1239
|
+
ids.add(id);
|
|
1240
|
+
}
|
|
1241
|
+
return ids;
|
|
1242
|
+
}
|
|
966
1243
|
/** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
|
|
967
1244
|
* same-command resume's decision source: the attempted handoff + the resume
|
|
968
1245
|
* command) + NO carrier (the bookkeep leaves the draft untouched). The crash
|
|
@@ -1002,6 +1279,11 @@ export class CliLifecycle {
|
|
|
1002
1279
|
// failure is named, never a silent absence (§3.3). The cause rides the death facts'
|
|
1003
1280
|
// existing vocabulary (no new enum row).
|
|
1004
1281
|
const violations = [RoundViolation.hard(reason, cause)];
|
|
1282
|
+
// P31 T5 §2.4 — the death face seals the round's own names: the draft the child may
|
|
1283
|
+
// have written before it died, and the final the round never materialized. A seal
|
|
1284
|
+
// here keeps the failure face from leaving the writable window open for whatever
|
|
1285
|
+
// the late-landing child still tries to write.
|
|
1286
|
+
this.#sealRoundCarriers(frame);
|
|
1005
1287
|
if (death.termination === null)
|
|
1006
1288
|
return { status: "BLOCKED", violations };
|
|
1007
1289
|
return { status: "TIMEOUT", termination: death.termination, violations };
|
|
@@ -1214,7 +1496,12 @@ export class CliLifecycle {
|
|
|
1214
1496
|
// the retained `--spec` flag.
|
|
1215
1497
|
return `cdd review --type ${frame.type} --spec ${this.#docOf(frame)}`;
|
|
1216
1498
|
case "fix": {
|
|
1217
|
-
|
|
1499
|
+
// The `--reviews` input is the SAME carrier the fix prompt names (P31 §2.3): one
|
|
1500
|
+
// four-layer resolution, never a second family spelling spliced here. The
|
|
1501
|
+
// fallback fires only when the recorded face resolves to `null` (a legacy record
|
|
1502
|
+
// with no carrier on disk) — the never-null guard keeps a command shape.
|
|
1503
|
+
const findings = this.#reviewsPath(frame) ??
|
|
1504
|
+
scene.ledger.resolveHandoffPath("review", frame.type, frame.params);
|
|
1218
1505
|
const target = frame.target.kind === "plan"
|
|
1219
1506
|
? `--plan ${frame.target.doc}`
|
|
1220
1507
|
: frame.target.kind === "spec"
|