@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
package/dist/session/ledger.js
CHANGED
|
@@ -24,7 +24,9 @@ var _a;
|
|
|
24
24
|
import { createHash } from "node:crypto";
|
|
25
25
|
import { readdirSync, readFileSync } from "node:fs";
|
|
26
26
|
import { DocBodyProjection } from "../contract/doc-body.js";
|
|
27
|
+
import { CarrierSeal } from "../infra/carrier-seal.js";
|
|
27
28
|
import { BriefRenderer } from "../render/brief.js";
|
|
29
|
+
import { CarrierIntegrity } from "./carrier-integrity.js";
|
|
28
30
|
import { targetFaces } from "./faces.js";
|
|
29
31
|
import { HandoffSchema } from "./handoff-schema.js";
|
|
30
32
|
import { LineIdentity } from "./line-identity.js";
|
|
@@ -245,9 +247,10 @@ export class Ledger {
|
|
|
245
247
|
return this.#basis().resolve(this.#basis().relativize(value));
|
|
246
248
|
}
|
|
247
249
|
// ---- the single author's write/read primitives ----
|
|
248
|
-
/** Persist a JSON artifact — the ledger's single write point (engine sole author).
|
|
250
|
+
/** Persist a JSON artifact — the ledger's single write point (engine sole author).
|
|
251
|
+
* Returns the digest of the written bytes (the carrier record's `carrierDigest`). */
|
|
249
252
|
#persist(name, data) {
|
|
250
|
-
this.#workspace.
|
|
253
|
+
return this.#workspace.writeJsonHashed(name, data);
|
|
251
254
|
}
|
|
252
255
|
/** Read a JSON artifact; null when missing/corrupt (the ledger's read face keeps the
|
|
253
256
|
* collapsed contract — the tri-state discrimination lives at the read-back
|
|
@@ -385,6 +388,11 @@ export class Ledger {
|
|
|
385
388
|
verdict: init.verdict ?? { treeClean: true, targetAction: true },
|
|
386
389
|
violations: init.violations ?? [],
|
|
387
390
|
carrierPath: init.carrierPath ?? null,
|
|
391
|
+
// The digest column exists only on rounds that recorded one (a legacy record
|
|
392
|
+
// keeps no key at all — the read then compares nothing, zero migration).
|
|
393
|
+
...(init.carrierDigest === undefined ? {} : { carrierDigest: init.carrierDigest }),
|
|
394
|
+
// …and the same for the draft path column (P31 §2.3).
|
|
395
|
+
...(init.draftPath === undefined ? {} : { draftPath: init.draftPath }),
|
|
388
396
|
};
|
|
389
397
|
const existing = records.findIndex((candidate) => candidate.op === record.op &&
|
|
390
398
|
candidate.cycle === record.cycle &&
|
|
@@ -617,9 +625,13 @@ export class Ledger {
|
|
|
617
625
|
// The fix-awaited face — a drifted wave BRIEF reopens at review (D30/D16), else fix.
|
|
618
626
|
if (this.briefDrifted(waveKey))
|
|
619
627
|
return { kind: "review" };
|
|
628
|
+
// The `--reviews` identity is the ROUTE's own (P31 §2.3): the round read resolves
|
|
629
|
+
// the FINAL carrier the record names, so a draft beside it never becomes the input
|
|
630
|
+
// — the board's `next:` and the dispatch's read the same file by construction.
|
|
620
631
|
return {
|
|
621
632
|
kind: "fix",
|
|
622
|
-
reviews:
|
|
633
|
+
reviews: route.reviews ??
|
|
634
|
+
this.resolveHandoffPath("review", "wave", { tasks: waveKey, round: latestReview }),
|
|
623
635
|
};
|
|
624
636
|
}
|
|
625
637
|
return null;
|
|
@@ -1058,11 +1070,40 @@ export class Ledger {
|
|
|
1058
1070
|
carrier.findings = init.findings;
|
|
1059
1071
|
return carrier;
|
|
1060
1072
|
}
|
|
1061
|
-
/** Persist a handoff payload
|
|
1062
|
-
* write
|
|
1073
|
+
/** Persist a handoff payload as the round's FINAL carrier — the engine's single-author
|
|
1074
|
+
* write, at a name the child's DRAFT never occupies (P31 §2.3). Returns the final
|
|
1075
|
+
* path (what the round is judged by), the draft path it landed beside, and the
|
|
1076
|
+
* payload's digest, so the round record can remember all three.
|
|
1077
|
+
*
|
|
1078
|
+
* The digest covers the PAYLOAD, never the file bytes that hold it: `H = sha256(JSON
|
|
1079
|
+
* containing H)` is unsatisfiable, so the value is taken BEFORE the `contentSha256`
|
|
1080
|
+
* key joins the payload — the key is appended LAST and the payload is written once
|
|
1081
|
+
* (the read recomputes by the same rule: drop the key, re-serialize, sha256). The
|
|
1082
|
+
* draft is neither written nor deleted here: it is the child's artifact, and the
|
|
1083
|
+
* final is the engine's answer to it.
|
|
1084
|
+
*
|
|
1085
|
+
* P31 §2.4 — the write CLOSES the carrier: the final and the draft name beside it
|
|
1086
|
+
* land at `0o444` in the same step, so a carrier is read-only from the instant the
|
|
1087
|
+
* engine authored it. A name that never landed (a round whose child wrote no draft,
|
|
1088
|
+
* a round-less family whose draft IS the final) is not an error — the seal is
|
|
1089
|
+
* idempotent and absence is the round's own fact. */
|
|
1063
1090
|
persistHandoff(op, type, params, data) {
|
|
1064
|
-
this
|
|
1065
|
-
|
|
1091
|
+
const draftName = this.handoffName(op, type, params);
|
|
1092
|
+
const payload = { ...data };
|
|
1093
|
+
// The engine owns this key — a caller-supplied value never seeds a self-covering digest.
|
|
1094
|
+
delete payload.contentSha256;
|
|
1095
|
+
const digest = CarrierIntegrity.digestOf(payload);
|
|
1096
|
+
payload.contentSha256 = digest;
|
|
1097
|
+
const finalName = this.#naming.finalName(draftName, params.round);
|
|
1098
|
+
this.#persist(finalName, payload);
|
|
1099
|
+
// The carrier is read-only the moment it exists; the draft beside it closes with it.
|
|
1100
|
+
CarrierSeal.seal(this.#workspace.resolve(finalName));
|
|
1101
|
+
CarrierSeal.seal(this.#workspace.resolve(draftName));
|
|
1102
|
+
return {
|
|
1103
|
+
path: this.#workspace.resolve(finalName),
|
|
1104
|
+
draftPath: this.#workspace.resolve(draftName),
|
|
1105
|
+
digest,
|
|
1106
|
+
};
|
|
1066
1107
|
}
|
|
1067
1108
|
/** The handoff file NAME a read actually resolves — the canonical family name, or a
|
|
1068
1109
|
* DOCUMENT line's retired `spec` twin when the canonical file is absent (the
|
|
@@ -1075,6 +1116,13 @@ export class Ledger {
|
|
|
1075
1116
|
* spelling). */
|
|
1076
1117
|
resolveHandoffName(op, type, params = {}) {
|
|
1077
1118
|
const canonical = this.handoffName(op, type, params);
|
|
1119
|
+
// P31 §2.3 — the FINAL carrier wins the read whenever the round has one: it is the
|
|
1120
|
+
// round's finalized answer, and the draft beside it is the child's raw input (an
|
|
1121
|
+
// un-materialized payload whose findings carry no engine id). A round-less family
|
|
1122
|
+
// (implement) has one name only, so `final` equals the canonical spelling.
|
|
1123
|
+
const final = this.#naming.finalName(canonical, params.round);
|
|
1124
|
+
if (final !== canonical && this.#read(final) !== null)
|
|
1125
|
+
return final;
|
|
1078
1126
|
if (!RETIRED_SPEC_LINE_KEYS.has(type) || this.#read(canonical) !== null) {
|
|
1079
1127
|
return canonical;
|
|
1080
1128
|
}
|
|
@@ -1093,9 +1141,55 @@ export class Ledger {
|
|
|
1093
1141
|
* alias keys on the line's declared word (`phase-spec` / `overall` / `single-spec`,
|
|
1094
1142
|
* the same basis as `rowFor`'s) and never covers the node shapes. Every WRITE goes
|
|
1095
1143
|
* through `persistHandoff`'s current spelling — the alias is read-only, and the name
|
|
1096
|
-
* it resolves is `resolveHandoffName`'s ONE answer.
|
|
1144
|
+
* it resolves is `resolveHandoffName`'s ONE answer.
|
|
1145
|
+
*
|
|
1146
|
+
* P31 §2.2 — the read is CHECKED: the (op, type, round) round's latest recorded
|
|
1147
|
+
* attempt supplies the digest the engine wrote, and `CarrierIntegrity.read` compares
|
|
1148
|
+
* the bytes against it before they are parsed (a mismatch throws
|
|
1149
|
+
* `CarrierMismatchError`, never a silently-judged tampered carrier). A legacy record
|
|
1150
|
+
* with no digest — or no record at all — reads as present facts, zero comparison. */
|
|
1097
1151
|
readHandoff(op, type, params) {
|
|
1098
|
-
|
|
1152
|
+
const name = this.resolveHandoffName(op, type, params);
|
|
1153
|
+
const bytes = CarrierIntegrity.read(this.#workspace.resolve(name), this.#carrierDigestOf(op, type, params));
|
|
1154
|
+
if (bytes === null)
|
|
1155
|
+
return null;
|
|
1156
|
+
try {
|
|
1157
|
+
return JSON.parse(bytes);
|
|
1158
|
+
}
|
|
1159
|
+
catch {
|
|
1160
|
+
return null;
|
|
1161
|
+
}
|
|
1162
|
+
}
|
|
1163
|
+
/** The digest the round recorded for the carrier this read resolves — its LATEST
|
|
1164
|
+
* attempt of the (op, type, round) identity (a re-dispatch supersedes its
|
|
1165
|
+
* predecessor, the same rule the round-read gate applies). Null when no record
|
|
1166
|
+
* carries one: the present-facts face (legacy rows, and reads of a round that never
|
|
1167
|
+
* booked its own carrier). */
|
|
1168
|
+
#carrierDigestOf(op, type, params) {
|
|
1169
|
+
return this.#latestRecordOf(op, type, params)?.carrierDigest ?? null;
|
|
1170
|
+
}
|
|
1171
|
+
/** The latest recorded attempt of an (op, type, round) identity — null when the line
|
|
1172
|
+
* carries no record for it (a legacy row, or a round never dispatched). ONE basis for
|
|
1173
|
+
* every "what did that round record" question (the digest the read compares against,
|
|
1174
|
+
* the carrier path `--reviews` names). */
|
|
1175
|
+
#latestRecordOf(op, type, params) {
|
|
1176
|
+
const mode = RoundRecords.opOf(op) ?? op;
|
|
1177
|
+
const round = params.round === undefined ? null : Number(params.round);
|
|
1178
|
+
return this.recordsOf(this.#roundKey(type, params), type)
|
|
1179
|
+
.filter((record) => record.op === mode)
|
|
1180
|
+
.filter((record) => round === null || record.cycle === round)
|
|
1181
|
+
.reduce((newest, record) => (newest === null || record.attempt >= newest.attempt ? record : newest), null);
|
|
1182
|
+
}
|
|
1183
|
+
/** The review carrier a round's fix leg reads as `--reviews` — the round's OWN
|
|
1184
|
+
* recorded carrier path (the FINAL carrier, P31 §2.3) when the record names one, and
|
|
1185
|
+
* the resolved family name (the draft spelling — legacy rows, and a round that
|
|
1186
|
+
* persisted no carrier) otherwise. Record-present means final-wins: a draft sitting
|
|
1187
|
+
* beside a final never becomes the judged input. */
|
|
1188
|
+
#reviewsPathOf(type, params, round) {
|
|
1189
|
+
const recorded = this.#latestRecordOf("review", type, { ...params, round })?.carrierPath;
|
|
1190
|
+
if (typeof recorded === "string" && recorded !== "")
|
|
1191
|
+
return recorded;
|
|
1192
|
+
return this.resolveHandoffPath("review", type, { ...params, round });
|
|
1099
1193
|
}
|
|
1100
1194
|
/** The retired document-line carrier name of one round — `spec-review-{round}.json` /
|
|
1101
1195
|
* `spec-fix-{round}.json`. It lives here, never in the family table: it is a read
|
|
@@ -1151,10 +1245,13 @@ export class Ledger {
|
|
|
1151
1245
|
* `{line}-{op}-{round}.json`, plus a document line's retired `spec` twin (the
|
|
1152
1246
|
* pre-rename name a still-unbooked draft can carry). Null for a non-handoff file. */
|
|
1153
1247
|
static #handoffOwner(name, families) {
|
|
1248
|
+
// A FINAL carrier (`<stem>.c{round}.json`, P31 §2.3) is the same artifact as its
|
|
1249
|
+
// draft — the cycle is the name's own suffix, never a second family.
|
|
1250
|
+
const draft = name.replace(/\.c\d+\.json$/, ".json");
|
|
1154
1251
|
for (const [family, record] of Object.entries(families)) {
|
|
1155
1252
|
const [op = "", type = ""] = family.split(".");
|
|
1156
1253
|
for (const spelling of _a.#familySpellings(record.name, type)) {
|
|
1157
|
-
const captures = _a.#familyCaptures(spelling,
|
|
1254
|
+
const captures = _a.#familyCaptures(spelling, draft);
|
|
1158
1255
|
if (captures === null)
|
|
1159
1256
|
continue;
|
|
1160
1257
|
const key = type === "wave" ? (captures.tasks ?? "") : type;
|
|
@@ -1308,7 +1405,7 @@ export class Ledger {
|
|
|
1308
1405
|
// source shared with the fix leg below (`HandoffSchema.conclusionOf`).
|
|
1309
1406
|
status: this.#handoffSchema.conclusionOf("judge", carrier),
|
|
1310
1407
|
findings: this.#findingsOf(carrier),
|
|
1311
|
-
reviewsPath: this
|
|
1408
|
+
reviewsPath: this.#reviewsPathOf(type, params, round),
|
|
1312
1409
|
consecutiveS1: this.#consecutiveS1Run(type, params, round),
|
|
1313
1410
|
};
|
|
1314
1411
|
}
|
|
@@ -1328,7 +1425,7 @@ export class Ledger {
|
|
|
1328
1425
|
// work plane reads its status) — the same `conclusionOf` single source (D27).
|
|
1329
1426
|
status: this.#handoffSchema.conclusionOf(this.planeOf("fix"), fixCarrier),
|
|
1330
1427
|
findings: this.#findingsOf(reviewCarrier),
|
|
1331
|
-
reviewsPath: this
|
|
1428
|
+
reviewsPath: this.#reviewsPathOf(type, params, round),
|
|
1332
1429
|
consecutiveS1: this.#consecutiveS1Run(type, params, round),
|
|
1333
1430
|
};
|
|
1334
1431
|
}
|
package/dist/session/next.js
CHANGED
|
@@ -134,15 +134,16 @@ export const NEXT_HOP_REASON = {
|
|
|
134
134
|
/** The review-cycle soft-cap suggestion (the C5-0 suggestion face — user adjudicates). */
|
|
135
135
|
export const SOFT_CAP_SUGGESTION = "BLOCKED: review-cycle-cap — user adjudicates";
|
|
136
136
|
/** The fix-route readback suffix — appended verbatim to the fix findings path on the
|
|
137
|
-
* route's `next:` render (`(confirm the reviews handoff · if a finding needs a
|
|
138
|
-
*
|
|
139
|
-
* anti-blind-fix mechanical guard is the ledger round / C5-1,
|
|
140
|
-
* reminds the orchestrator to confirm the captured findings and, when a
|
|
141
|
-
* needs a user ruling, record
|
|
142
|
-
*
|
|
143
|
-
* `
|
|
144
|
-
* ruling's destination when it asserts a
|
|
145
|
-
|
|
137
|
+
* route's `next:` render (`(confirm the reviews handoff · if a finding needs a ruling,
|
|
138
|
+
* record it beside that handoff — same path with .json replaced by .rulings.json)`), a
|
|
139
|
+
* pure wording prompt: the anti-blind-fix mechanical guard is the ledger round / C5-1,
|
|
140
|
+
* the suffix only reminds the orchestrator to confirm the captured findings and, when a
|
|
141
|
+
* finding needs a user ruling, to record it in the SIDECAR beside the reviews handoff
|
|
142
|
+
* (the carrier's bytes are frozen — the ruling never edits them; P31 §2.1/§2.5).
|
|
143
|
+
* `annotate` names the carrier action alone — distinct from `backfill` (a durable fact
|
|
144
|
+
* landed into its owning doc), which stays the ruling's destination when it asserts a
|
|
145
|
+
* project-level fact. */
|
|
146
|
+
export const FIX_READBACK_SUFFIX = "(confirm the reviews handoff · if a finding needs a ruling, record it beside that handoff — same path with .json replaced by .rulings.json)";
|
|
146
147
|
/** The failure face — a BLOCKED/TIMEOUT round goes the stderr CDD_BLOCKED channel and
|
|
147
148
|
* produces no `next:` line on any op. Exported as the ONE failure-status set: the
|
|
148
149
|
* skill-anatomy contract's `edgeConditionWords` derivation reads it to exclude the
|
|
@@ -51,4 +51,19 @@ export class ReviewedIdentity {
|
|
|
51
51
|
return "branch";
|
|
52
52
|
return null;
|
|
53
53
|
}
|
|
54
|
+
/** Whether one binding phase is gated by the round's own-bytes measurement
|
|
55
|
+
* (`touchedDoc`) — the second half of this file's one judgment: `legOf` says WHICH
|
|
56
|
+
* leg a completed round writes, this says whether that leg is CONDITIONAL.
|
|
57
|
+
*
|
|
58
|
+
* The split's ground is whether the phase is EXPECTED to rewrite the document it
|
|
59
|
+
* judges: a `fix` is (so an untouched claim keeps the old binding and the next
|
|
60
|
+
* review reports drift), a `review` / `branch-review` is not (its job is to
|
|
61
|
+
* conclude on existing bytes, so a completed conclusion binds them — otherwise
|
|
62
|
+
* every review leaves no trace and the line is dispatched forever). `implement`
|
|
63
|
+
* binds nothing (`legOf` answers null), so its answer never applies.
|
|
64
|
+
*
|
|
65
|
+
* Pure: it reads the phase and nothing else. */
|
|
66
|
+
static gatedByTouchedDoc(phase) {
|
|
67
|
+
return phase === "fix";
|
|
68
|
+
}
|
|
54
69
|
}
|
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
// packages/cdd-engine/src-next/session/round-naming.ts
|
|
2
2
|
// P11 T4 — the round-naming single source: the frame → artifact-name derivations
|
|
3
3
|
// (report · evidence · brief) the lifecycle's read-back and the dry-run preview
|
|
4
|
-
// share, plus the frame → family-op mapping those names key on. The handoff carrier
|
|
5
|
-
// name is NOT derived here — it stays with the Ledger's HANDOFF_FAMILIES table
|
|
6
|
-
// naming table is the single truth, never a second list)
|
|
4
|
+
// share, plus the frame → family-op mapping those names key on. The handoff carrier's
|
|
5
|
+
// DRAFT name is NOT derived here — it stays with the Ledger's HANDOFF_FAMILIES table
|
|
6
|
+
// (the naming table is the single truth, never a second list); the FINAL name (P31
|
|
7
|
+
// §2.3) is that name with its suffix swapped, so the rule runs on the filled name.
|
|
7
8
|
//
|
|
8
9
|
// Module-level exports are the class — zero behavior-carrying bare functions.
|
|
9
|
-
import { TargetFaceTable } from "./faces.js";
|
|
10
|
+
import { TargetFaceTable, targetFaces } from "./faces.js";
|
|
10
11
|
/**
|
|
11
12
|
* RoundNaming — the one home of a round's prescribed artifact names. A frame's
|
|
12
13
|
* report / evidence / brief names derive here, so every consumer (the lifecycle's
|
|
@@ -19,6 +20,45 @@ export class RoundNaming {
|
|
|
19
20
|
constructor(workspace) {
|
|
20
21
|
this.#workspace = workspace;
|
|
21
22
|
}
|
|
23
|
+
/** The two carrier-name shapes this engine MINTS — the draft family spelling
|
|
24
|
+
* (`{line}-{op}[-{round}].json`) and its final twin (`…[-{round}].c{N}.json`). The
|
|
25
|
+
* line words come from the ONE target-face table (the wave line's spelling is the
|
|
26
|
+
* `tasks-` spine, never the `wave` word itself) and the ops from the ONE op
|
|
27
|
+
* vocabulary, so neither set is re-spelled here. */
|
|
28
|
+
static #CARRIER = RoundNaming.#carrierPattern();
|
|
29
|
+
/** The carrier-name predicate's compiled pattern — `tasks-{tasks}` is the one
|
|
30
|
+
* wave-only line (implement exists there alone), the other line words take the
|
|
31
|
+
* round-bearing ops. */
|
|
32
|
+
static #carrierPattern() {
|
|
33
|
+
const lines = Object.keys(targetFaces).filter((word) => word !== "wave");
|
|
34
|
+
return new RegExp(`^(?:tasks-.+-(?:implement|review|fix)(?:-\\d+)?|(?:${lines.join("|")})-(?:review|fix)(?:-\\d+)?)(?:\\.c\\d+)?\\.json$`);
|
|
35
|
+
}
|
|
36
|
+
/** The carrier's FINAL name of one round — the draft family name with its `.json`
|
|
37
|
+
* suffix swapped for `.c{round}.json` (P31 §2.3: the finalized carrier never
|
|
38
|
+
* overwrites the child's draft, so the two names share the stem and differ in the
|
|
39
|
+
* suffix). The draft spelling stays the Ledger's family table (`handoffName` — the
|
|
40
|
+
* naming truth); this rule runs on the name that table filled, so the two spellings
|
|
41
|
+
* cannot drift. A round-less family has no cycle to key on: the family name comes
|
|
42
|
+
* back unchanged, never a `.c.json` malformed suffix. */
|
|
43
|
+
finalName(draftName, round = undefined) {
|
|
44
|
+
if (round === undefined)
|
|
45
|
+
return draftName;
|
|
46
|
+
return `${draftName.replace(/\.json$/, "")}.c${round}.json`;
|
|
47
|
+
}
|
|
48
|
+
/** The final carrier's on-disk path — `finalName` resolved against the workspace
|
|
49
|
+
* (the name is the input, so an absolute path is never re-joined). */
|
|
50
|
+
finalPath(draftName, round = undefined) {
|
|
51
|
+
return this.#workspace.resolve(this.finalName(draftName, round));
|
|
52
|
+
}
|
|
53
|
+
/** Whether a workspace file name is one of the two carrier shapes this engine mints.
|
|
54
|
+
* Every neighbouring artifact — `progress.json` · `base.json` · the test-evidence
|
|
55
|
+
* sibling · a carrier's `.rulings.json` sidecar · a report · a crash record — is NOT
|
|
56
|
+
* a carrier, so the sweep that seals carriers can never touch them. Static: the
|
|
57
|
+
* judgment reads a NAME and nothing else, so the seal sweep (`CarrierSeal`) applies
|
|
58
|
+
* the same predicate without holding a workspace. */
|
|
59
|
+
static isCarrierName(name) {
|
|
60
|
+
return RoundNaming.#CARRIER.test(name);
|
|
61
|
+
}
|
|
22
62
|
/** The handoff-family op of a frame — branch-review rides the review family. The
|
|
23
63
|
* artifact stems embed this op, so the mapping is a naming fact owned here (the
|
|
24
64
|
* lifecycle's op read delegates, never a second copy of the rule). */
|
package/dist/session/run.js
CHANGED
|
@@ -20,7 +20,8 @@
|
|
|
20
20
|
import { readFileSync } from "node:fs";
|
|
21
21
|
import { PlanDocType } from "../contract/doc.js";
|
|
22
22
|
import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
|
|
23
|
-
import {
|
|
23
|
+
import { CarrierSeal } from "../infra/carrier-seal.js";
|
|
24
|
+
import { Ledger, RoundViolation, } from "./ledger.js";
|
|
24
25
|
import { NextStepRouter } from "./next.js";
|
|
25
26
|
import { PipelineFrontier } from "./pipeline.js";
|
|
26
27
|
import { ReviewedIdentity } from "./reviewed-identity.js";
|
|
@@ -33,6 +34,11 @@ export const EMPTY_RUN_STATE = {
|
|
|
33
34
|
frontier: () => [],
|
|
34
35
|
markDone: () => undefined,
|
|
35
36
|
};
|
|
37
|
+
/** The P31 §2.7 write-back observation — the round could not tell whether it touched
|
|
38
|
+
* the reviewed document (no dispatch baseline, or git unreadable). The bind keeps
|
|
39
|
+
* today's behaviour and this entry records the blindness; it is SOFT, so it never
|
|
40
|
+
* flips the verdict or blocks the next dispatch. */
|
|
41
|
+
const WRITE_BACK_UNMEASURED = "the reviewed-revision write-back could not measure whether this round touched the document (no dispatch baseline or an unreadable repository) — the current bytes were bound";
|
|
36
42
|
/**
|
|
37
43
|
* PlanStructure — one plan document's STRUCTURE face: the task-id set and each task's
|
|
38
44
|
* declared `DependsOn` set (design spec §7.3).
|
|
@@ -427,11 +433,12 @@ export class Lifecycle {
|
|
|
427
433
|
// -------------------------------------------------------------------------
|
|
428
434
|
/** Bookkeeping — persist the round's handoff carrier and record the round. The
|
|
429
435
|
* persisted carrier is either the dispatch's materialized form (the production
|
|
430
|
-
* read-back reconstruct — outcome.carrier
|
|
431
|
-
*
|
|
432
|
-
*
|
|
433
|
-
*
|
|
434
|
-
*
|
|
436
|
+
* read-back reconstruct — outcome.carrier) or — on the INJECTED face alone (an
|
|
437
|
+
* outcome carrying no verdict) — the engine-built fallback from the outcome fields.
|
|
438
|
+
* Either way it lands as the FINAL carrier beside the child's draft, never over it
|
|
439
|
+
* (P31 §2.3: the draft keeps the child's bytes, the final carries the engine's
|
|
440
|
+
* materialization, and the record names both paths). A production round that wrote
|
|
441
|
+
* no carrier is booked with `carrierPath: null` and no file at either name: the
|
|
435
442
|
* completion criterion owns the absence (§3.3), and a re-dispatch's draft read must
|
|
436
443
|
* see the child's own draft, never an engine synthesis of it. A failure round
|
|
437
444
|
* WITHOUT a carrier leaves the child's draft untouched (no-overwrite on failure) but
|
|
@@ -441,6 +448,8 @@ export class Lifecycle {
|
|
|
441
448
|
#bookkeep(frame, outcome) {
|
|
442
449
|
const blocked = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
|
|
443
450
|
let carrierPath = null;
|
|
451
|
+
let carrierDigest = null;
|
|
452
|
+
let draftPath = null;
|
|
444
453
|
if (outcome.carrier !== undefined || (outcome.verdict === undefined && !blocked)) {
|
|
445
454
|
const op = this.#opOf(frame.phase);
|
|
446
455
|
// T2 — the engine-built fallback rides the FRAME's op-derived plane (never the
|
|
@@ -463,12 +472,35 @@ export class Lifecycle {
|
|
|
463
472
|
// (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
|
|
464
473
|
if (plane === "work" && carrier.status === undefined && outcome.status !== undefined)
|
|
465
474
|
carrier.status = outcome.status;
|
|
466
|
-
|
|
475
|
+
// P31 §2.2/§2.3 — the persist hands the FINAL carrier path, the draft path it
|
|
476
|
+
// landed beside and the payload digest, so the round record can name both
|
|
477
|
+
// artifacts and replay the comparison on every later read of this carrier.
|
|
478
|
+
const persisted = this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
|
|
479
|
+
carrierPath = persisted.path;
|
|
480
|
+
carrierDigest = persisted.digest;
|
|
481
|
+
draftPath = persisted.draftPath;
|
|
482
|
+
}
|
|
483
|
+
else {
|
|
484
|
+
// P31 T5 §2.4 — a round that books NO carrier still owns its two names: the
|
|
485
|
+
// draft the child may have written before the round failed must not stay
|
|
486
|
+
// writable. The persistence seals its own pair above; this is the failure
|
|
487
|
+
// face's leg (the lifecycle's terminals seal too — one invariant, two entry
|
|
488
|
+
// points, so an injected dispatcher can never leave the window open).
|
|
489
|
+
this.#sealRoundCarriers(frame);
|
|
467
490
|
}
|
|
468
491
|
// The recorded CYCLE is the frame's own round — its identity (fix-K ⟷ review-K ·
|
|
469
492
|
// D28): a skipped cycle records its own number, never a flattened ordinal. The
|
|
470
493
|
// attempt was allocated once by the frame builder and rides both the record and
|
|
471
494
|
// the round log's name.
|
|
495
|
+
//
|
|
496
|
+
// P31 §2.7 — the write-back's three states become a graded entry HERE, before the
|
|
497
|
+
// record is written: an UNMEASURABLE range (`null`) keeps today's bind and books
|
|
498
|
+
// one soft observation (never a verdict flip); `true` / `false` / unmeasured ride
|
|
499
|
+
// the write-back gate below.
|
|
500
|
+
const violations = [
|
|
501
|
+
...(outcome.violations ?? []),
|
|
502
|
+
...(outcome.touchedDoc === null ? [RoundViolation.soft(WRITE_BACK_UNMEASURED)] : []),
|
|
503
|
+
];
|
|
472
504
|
const record = this.#ledger.recordRound(frame.key, {
|
|
473
505
|
op: this.#opOf(frame.phase),
|
|
474
506
|
cycle: frame.round,
|
|
@@ -481,8 +513,10 @@ export class Lifecycle {
|
|
|
481
513
|
treeClean: outcome.treeClean ?? true,
|
|
482
514
|
targetAction: !blocked,
|
|
483
515
|
},
|
|
484
|
-
violations
|
|
516
|
+
violations,
|
|
485
517
|
carrierPath,
|
|
518
|
+
carrierDigest,
|
|
519
|
+
draftPath,
|
|
486
520
|
}, frame.type);
|
|
487
521
|
// The completed-round revision write-back is gated on the round's VERDICT (a
|
|
488
522
|
// hard-failed round must not bind the current revision — that would silently
|
|
@@ -497,7 +531,20 @@ export class Lifecycle {
|
|
|
497
531
|
// real run records nothing while the preview still states the brief leg. The
|
|
498
532
|
// record methods keep their own defensive narrowing; an unreadable input records
|
|
499
533
|
// nothing (present facts only).
|
|
500
|
-
|
|
534
|
+
//
|
|
535
|
+
// P31 §2.7 — the bind is conditional on the round's OWN bytes, but ONLY where the
|
|
536
|
+
// phase is expected to produce those bytes (P32 §2.1): a READABLE range that
|
|
537
|
+
// touched the document not at all (`false`) keeps the OLD binding on a `fix` round,
|
|
538
|
+
// so the existing drift / reopen face pushes the line back to review instead of
|
|
539
|
+
// silently closing it on bytes the round never delivered. A `review` /
|
|
540
|
+
// `branch-review` is not gated: its job is to conclude on bytes it does not write,
|
|
541
|
+
// and a completed conclusion must bind them or the drift identity never closes.
|
|
542
|
+
// WHICH phases are gated is the judgment's own cell
|
|
543
|
+
// (`ReviewedIdentity.gatedByTouchedDoc`), beside the leg decision; `true`, `null`
|
|
544
|
+
// (unmeasurable — its soft entry is booked above) and `undefined` (hermetic /
|
|
545
|
+
// injected dispatchers) keep today's bind.
|
|
546
|
+
const leg = record.verdict.targetAction &&
|
|
547
|
+
(!ReviewedIdentity.gatedByTouchedDoc(frame.phase) || outcome.touchedDoc !== false)
|
|
501
548
|
? ReviewedIdentity.legOf(frame.phase, frame.target.kind)
|
|
502
549
|
: null;
|
|
503
550
|
if (leg !== null) {
|
|
@@ -603,6 +650,15 @@ export class Lifecycle {
|
|
|
603
650
|
#opOf(phase) {
|
|
604
651
|
return phase === "branch-review" ? "review" : phase;
|
|
605
652
|
}
|
|
653
|
+
/** P31 §2.4 — seal one round's OWN carrier names (its draft and its final). The
|
|
654
|
+
* derivation is the same pair the lifecycle's preflight opens; a round-less family
|
|
655
|
+
* (implement) resolves both to one path, so the seal is idempotent by construction. */
|
|
656
|
+
#sealRoundCarriers(frame) {
|
|
657
|
+
const op = this.#opOf(frame.phase);
|
|
658
|
+
const draftName = this.#ledger.handoffName(op, frame.type, frame.params);
|
|
659
|
+
CarrierSeal.seal(this.#ledger.handoffPath(op, frame.type, frame.params));
|
|
660
|
+
CarrierSeal.seal(this.#ledger.naming().finalPath(draftName, frame.params.round));
|
|
661
|
+
}
|
|
606
662
|
// -------------------------------------------------------------------------
|
|
607
663
|
// next routing + the capsule interaction
|
|
608
664
|
// -------------------------------------------------------------------------
|
|
@@ -701,12 +757,15 @@ export class Lifecycle {
|
|
|
701
757
|
const naming = this.#ledger.naming();
|
|
702
758
|
// The failure face's handoff is the crash record — the engine's own postmortem
|
|
703
759
|
// artifact, its existence the emission condition; the success face keeps the
|
|
704
|
-
// round's handoff carrier path
|
|
705
|
-
//
|
|
760
|
+
// round's handoff carrier path — the FINAL carrier the round wrote (P31 §2.3),
|
|
761
|
+
// resolved through the ledger's ONE read-name rule (the draft's family spelling is
|
|
762
|
+
// the fallback, never the cell's own derivation). The crash name derives from the
|
|
763
|
+
// frame through the ONE naming source (`RoundNaming`), the same name the lifecycle
|
|
764
|
+
// wrote it under.
|
|
706
765
|
const crash = failure ? this.#ledger.readCrash(naming.crashName(frame)) : null;
|
|
707
766
|
const handoff = crash !== null
|
|
708
767
|
? naming.crashPath(frame)
|
|
709
|
-
: this.#ledger.
|
|
768
|
+
: this.#ledger.resolveHandoffPath(op, frame.type, frame.params);
|
|
710
769
|
return this.#capsule.emit(outcome.status, handoff, hop, crash !== null, summary);
|
|
711
770
|
}
|
|
712
771
|
/** The frame's RouteTarget — the dispatch-ready literal's target identity (the
|