@oscaner-skills/cdd-engine 4.10.0 → 4.12.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/dist/contract/completion-criterion.js +19 -28
- package/dist/contract/doc.js +24 -0
- package/dist/contract/invariants.js +11 -8
- package/dist/contract/judge.js +45 -4
- package/dist/contract/project.js +12 -1
- package/dist/contract/task-block-grammar.js +3 -1
- package/dist/face/board-view.js +327 -138
- package/dist/face/cli.js +172 -63
- package/dist/face/gate.js +6 -3
- package/dist/face/lifecycle.js +191 -128
- package/dist/face/words.js +51 -0
- package/dist/infra/plan-source.js +359 -0
- package/dist/infra/runtime.js +20 -52
- package/dist/render/brief.js +34 -32
- package/dist/render/templates.js +63 -29
- package/dist/session/carrier-integrity.js +0 -8
- package/dist/session/dispatch-authority.js +1 -1
- package/dist/session/handoff-schema.js +135 -73
- package/dist/session/ledger.js +269 -104
- package/dist/session/pipeline.js +2 -2
- package/dist/session/preflight.js +65 -34
- package/dist/session/round-naming.js +138 -89
- package/dist/session/run.js +73 -74
- package/package.json +1 -1
package/dist/session/ledger.js
CHANGED
|
@@ -23,6 +23,7 @@
|
|
|
23
23
|
var _a;
|
|
24
24
|
import { createHash } from "node:crypto";
|
|
25
25
|
import { readdirSync, readFileSync } from "node:fs";
|
|
26
|
+
import { basename } from "node:path";
|
|
26
27
|
import { DocBodyProjection } from "../contract/doc-body.js";
|
|
27
28
|
import { CarrierSeal } from "../infra/carrier-seal.js";
|
|
28
29
|
import { BriefRenderer } from "../render/brief.js";
|
|
@@ -33,6 +34,10 @@ import { LineIdentity } from "./line-identity.js";
|
|
|
33
34
|
import { NextStepRouter } from "./next.js";
|
|
34
35
|
import { RoundNaming } from "./round-naming.js";
|
|
35
36
|
import { EMPTY_RUN_STATE } from "./run.js";
|
|
37
|
+
/** The cause a declared BLOCKED / TIMEOUT round books on the entry it synthesizes when
|
|
38
|
+
* it authored NO fact of its own — the round's own conclusion (`round-blocked`),
|
|
39
|
+
* never `contract-violation`: nothing about the record broke (P34 T5). */
|
|
40
|
+
export const CONCLUDED_BLOCKED_CAUSE = "round-blocked";
|
|
36
41
|
/** The graded-violation literals' ONE construction point — the cause vocabulary is
|
|
37
42
|
* a declared convergence point, so its shape is held here rather than copied per
|
|
38
43
|
* call site. `cause` defaults to `contract-violation`, the ledger's existing row
|
|
@@ -107,9 +112,29 @@ export class RoundRecords {
|
|
|
107
112
|
dispatchBase: null,
|
|
108
113
|
verdict: { treeClean: true, targetAction: true },
|
|
109
114
|
violations: [],
|
|
110
|
-
carrierPath: null,
|
|
111
115
|
};
|
|
112
116
|
}
|
|
117
|
+
/** Whether a record OWNS its carrier path (spec §2.7) — no other record of the same
|
|
118
|
+
* line sits on that path with a larger `(cycle, attempt)`. New records are each
|
|
119
|
+
* their own owner (their names are unique by identity), so the judgment only
|
|
120
|
+
* discriminates LEGACY rows: a row whose carrier path was overwritten by a later
|
|
121
|
+
* round is present facts, never a mismatch (the engine cannot tell a lawful
|
|
122
|
+
* overwrite from a tamper). The path comes in as a projection — the record's own
|
|
123
|
+
* identity, never a stored cell (`RoundRecords` has no workspace to resolve a
|
|
124
|
+
* name). */
|
|
125
|
+
static ownerOf(records, record, pathOf) {
|
|
126
|
+
const path = pathOf(record);
|
|
127
|
+
if (path === "")
|
|
128
|
+
return false;
|
|
129
|
+
return !records.some((other) => RoundRecords.#laterRound(other, record) && pathOf(other) === path);
|
|
130
|
+
}
|
|
131
|
+
/** Whether `other` is the later round of the two — `(cycle, attempt)` order, the
|
|
132
|
+
* round identity's own sequence. Identical identities are not later. */
|
|
133
|
+
static #laterRound(other, record) {
|
|
134
|
+
return other.cycle === record.cycle
|
|
135
|
+
? other.attempt > record.attempt
|
|
136
|
+
: other.cycle > record.cycle;
|
|
137
|
+
}
|
|
113
138
|
/** The op a recorded mode key belongs to — branch-review rides the review family;
|
|
114
139
|
* an unknown mode key reads null (a hand-written row is not a round record). */
|
|
115
140
|
static opOf(mode) {
|
|
@@ -192,7 +217,8 @@ export class ReviewRefs {
|
|
|
192
217
|
export class Ledger {
|
|
193
218
|
/** The one dispatch workspace this ledger records. */
|
|
194
219
|
#workspace;
|
|
195
|
-
/** The handoff-family
|
|
220
|
+
/** The handoff-family key set, keyed by `op.type` — the loud unknown-family check's
|
|
221
|
+
* input (the file names are the naming face's one mint, never a table here). */
|
|
196
222
|
#families;
|
|
197
223
|
/** The C5 next router — the closure-side judge of the round carriers (stateless;
|
|
198
224
|
* the `closedWaves()` read face and the wave gate share the same router). */
|
|
@@ -215,12 +241,19 @@ export class Ledger {
|
|
|
215
241
|
* dispatch input (a backfill touching other tasks, or a Constraints reword, must
|
|
216
242
|
* not void a reviewed wave). */
|
|
217
243
|
#brief = new BriefRenderer();
|
|
244
|
+
/** The plan read seam (D30) — the reviewed brief's ONLY read of `reviewed.plan`:
|
|
245
|
+
* the drift judgment re-reads the path the round recorded, through the same
|
|
246
|
+
* per-command `PlanSource` the dispatch read its plan through. The ledger itself
|
|
247
|
+
* never opens a file for the brief, so the observation face can never make the
|
|
248
|
+
* hash subject drift. */
|
|
249
|
+
#plan;
|
|
218
250
|
/** The round-naming single source over this ledger's workspace — the crash
|
|
219
251
|
* artifact names derive here (zero second derivation). */
|
|
220
252
|
#naming;
|
|
221
|
-
constructor(workspace, config) {
|
|
253
|
+
constructor(workspace, config, plan) {
|
|
222
254
|
this.#workspace = workspace;
|
|
223
255
|
this.#families = config.handoffNamespace().families;
|
|
256
|
+
this.#plan = plan;
|
|
224
257
|
this.#naming = new RoundNaming(workspace);
|
|
225
258
|
}
|
|
226
259
|
/** The review-reference face — the refKind three-type derivation + binding (T25). */
|
|
@@ -387,12 +420,10 @@ export class Ledger {
|
|
|
387
420
|
dispatchBase: init.dispatchBase ?? null,
|
|
388
421
|
verdict: init.verdict ?? { treeClean: true, targetAction: true },
|
|
389
422
|
violations: init.violations ?? [],
|
|
390
|
-
carrierPath: init.carrierPath ?? null,
|
|
391
423
|
// 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).
|
|
424
|
+
// keeps no key at all — the read then compares nothing, zero migration). The
|
|
425
|
+
// carrier PATH is never written (spec §2.10): it is derived from this identity.
|
|
393
426
|
...(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 }),
|
|
396
427
|
};
|
|
397
428
|
const existing = records.findIndex((candidate) => candidate.op === record.op &&
|
|
398
429
|
candidate.cycle === record.cycle &&
|
|
@@ -426,6 +457,22 @@ export class Ledger {
|
|
|
426
457
|
row.reviewedRevision = revision;
|
|
427
458
|
this.writeProgress(data);
|
|
428
459
|
}
|
|
460
|
+
/** Record a branch line's reviewed PLAN revision (P21 §4.1) — the plan
|
|
461
|
+
* document's body revision as the round LEFT it. The read rides the ledger's own
|
|
462
|
+
* `PlanSource` (the ONE plan read point), so a round that edited its plan binds the
|
|
463
|
+
* edited bytes — never the dispatch-time snapshot — while a non-ready read records
|
|
464
|
+
* nothing (present facts only, the symmetric failure face to `recordReviewedBrief`).
|
|
465
|
+
* The recorded path is normalized HERE, not by the caller (the same discipline
|
|
466
|
+
* `#briefRevision` keeps): the drift comparator relativizes only its current side,
|
|
467
|
+
* so an absolute argv-erasure shape handed in by a future caller would otherwise
|
|
468
|
+
* read as a false drift. */
|
|
469
|
+
recordReviewedPlanRevision(key, planPath, identity) {
|
|
470
|
+
const read = this.#plan.readPath(planPath);
|
|
471
|
+
const text = read.text();
|
|
472
|
+
if (text === null)
|
|
473
|
+
return;
|
|
474
|
+
this.recordReviewedRevision(key, this.#refs.docRevision(this.#rel(planPath), text), identity);
|
|
475
|
+
}
|
|
429
476
|
/** Record a wave line's reviewed BRIEF revision (D30) — the hash of the wave's
|
|
430
477
|
* TASK-ONLY projection (P29 §2.2: the task sections, `## Constraints` excluded).
|
|
431
478
|
* A backfill touching OTHER tasks leaves this projection byte-identical, and so
|
|
@@ -439,14 +486,21 @@ export class Ledger {
|
|
|
439
486
|
/** The wave line's reviewed-basis revision (D30) — the hash of the wave's TASK-ONLY
|
|
440
487
|
* projection (`BriefRenderer#taskBody`: the task sections, `## Constraints`
|
|
441
488
|
* excluded — P29 §2.2). The `plan` layer is the plan the brief renders from, the
|
|
442
|
-
* `brief_hash` layer the projection's own digest.
|
|
443
|
-
*
|
|
489
|
+
* `brief_hash` layer the projection's own digest. The read rides the injected
|
|
490
|
+
* `PlanSource` (the ONE plan read seam), so a non-ready read — an unreadable plan,
|
|
491
|
+
* a grammar break — records nothing. Null when the plan is unreadable or a
|
|
492
|
+
* requested task is absent (present facts only). */
|
|
444
493
|
#briefRevision(waveKey, planPath) {
|
|
494
|
+
const read = this.#plan.readPath(planPath);
|
|
495
|
+
const text = read.text();
|
|
496
|
+
const doc = read.doc();
|
|
497
|
+
if (text === null || doc === null)
|
|
498
|
+
return null;
|
|
445
499
|
try {
|
|
446
500
|
const tasks = waveKey.split(",").map((part) => Number(part));
|
|
501
|
+
const brief = this.#brief.taskBody(text, doc, tasks);
|
|
447
502
|
// The plan layer is stored repoRoot-relative (P9 T4 §2.7) — one basis with
|
|
448
|
-
// every persisted path field
|
|
449
|
-
const brief = this.#brief.taskBody(readFileSync(this.#abs(planPath), "utf8"), tasks);
|
|
503
|
+
// every persisted path field.
|
|
450
504
|
return this.#refs.briefRevision(this.#rel(planPath), brief);
|
|
451
505
|
}
|
|
452
506
|
catch {
|
|
@@ -1039,13 +1093,13 @@ export class Ledger {
|
|
|
1039
1093
|
// -------------------------------------------------------------------------
|
|
1040
1094
|
// handoff — naming / carrier / single-author persist
|
|
1041
1095
|
// -------------------------------------------------------------------------
|
|
1042
|
-
/** The family
|
|
1043
|
-
* (loud on an unknown family: the
|
|
1096
|
+
/** The family key check of an op/type pair — the engine-config handoff namespace data
|
|
1097
|
+
* (loud on an unknown family: the key set is the resolution truth, never a second list;
|
|
1098
|
+
* the NAME is the naming face's one mint). */
|
|
1044
1099
|
#family(op, type) {
|
|
1045
|
-
|
|
1046
|
-
if (family === undefined)
|
|
1100
|
+
if (!this.#families.includes(`${op}.${type}`)) {
|
|
1047
1101
|
throw new Error(`unknown handoff family: ${op}.${type}`);
|
|
1048
|
-
|
|
1102
|
+
}
|
|
1049
1103
|
}
|
|
1050
1104
|
/** The carrier PLANE of an op — the ONE op-derived derivation (`HandoffSchema.planeOf`).
|
|
1051
1105
|
* The plane-aware read/write/bookkeep spine: a judge-plane round (review) rides the
|
|
@@ -1054,11 +1108,20 @@ export class Ledger {
|
|
|
1054
1108
|
planeOf(op) {
|
|
1055
1109
|
return HandoffSchema.planeOf(op);
|
|
1056
1110
|
}
|
|
1057
|
-
/** The canonical handoff file name — the
|
|
1111
|
+
/** The canonical handoff file name — the round identity's DRAFT, rendered by the
|
|
1112
|
+
* ONE naming rule (`RoundNaming#renderName`). The family key set still guards the
|
|
1113
|
+
* op/type pairs (a loud unknown-family throw), but it spells no name: the renderer
|
|
1114
|
+
* does, so the draft, its final, the report, the log and the crash record cannot
|
|
1115
|
+
* drift apart. */
|
|
1058
1116
|
handoffName(op, type, params = {}) {
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
1117
|
+
this.#family(op, type);
|
|
1118
|
+
return RoundNaming.renderName(_a.#artifactOf(op, type, params), "draft");
|
|
1119
|
+
}
|
|
1120
|
+
/** The identity of one (op, type, params) triple — the ONE adapter from the
|
|
1121
|
+
* params-carrying surface onto the naming renderer. */
|
|
1122
|
+
static #artifactOf(op, type, params) {
|
|
1123
|
+
const artifactOp = (RoundRecords.opOf(op) ?? op);
|
|
1124
|
+
return RoundNaming.artifactOf(artifactOp, type, params);
|
|
1062
1125
|
}
|
|
1063
1126
|
/** The canonical on-disk handoff path. */
|
|
1064
1127
|
handoffPath(op, type, params = {}) {
|
|
@@ -1071,9 +1134,9 @@ export class Ledger {
|
|
|
1071
1134
|
return carrier;
|
|
1072
1135
|
}
|
|
1073
1136
|
/** 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).
|
|
1075
|
-
*
|
|
1076
|
-
*
|
|
1137
|
+
* write, at a name the child's DRAFT never occupies (P31 §2.3). Writes the final,
|
|
1138
|
+
* seals the draft + final pair, returns the payload digest the record remembers — the
|
|
1139
|
+
* record names neither path, it derives both from its own identity.
|
|
1077
1140
|
*
|
|
1078
1141
|
* The digest covers the PAYLOAD, never the file bytes that hold it: `H = sha256(JSON
|
|
1079
1142
|
* containing H)` is unsatisfiable, so the value is taken BEFORE the `contentSha256`
|
|
@@ -1085,16 +1148,17 @@ export class Ledger {
|
|
|
1085
1148
|
* P31 §2.4 — the write CLOSES the carrier: the final and the draft name beside it
|
|
1086
1149
|
* land at `0o444` in the same step, so a carrier is read-only from the instant the
|
|
1087
1150
|
* engine authored it. A name that never landed (a round whose child wrote no draft,
|
|
1088
|
-
* a
|
|
1151
|
+
* a legacy cycle-less name whose draft IS the final) is not an error — the seal is
|
|
1089
1152
|
* idempotent and absence is the round's own fact. */
|
|
1090
1153
|
persistHandoff(op, type, params, data) {
|
|
1091
|
-
const
|
|
1154
|
+
const artifact = _a.#artifactOf(op, type, params);
|
|
1155
|
+
const draftName = RoundNaming.renderName(artifact, "draft");
|
|
1092
1156
|
const payload = { ...data };
|
|
1093
1157
|
// The engine owns this key — a caller-supplied value never seeds a self-covering digest.
|
|
1094
1158
|
delete payload.contentSha256;
|
|
1095
1159
|
const digest = CarrierIntegrity.digestOf(payload);
|
|
1096
1160
|
payload.contentSha256 = digest;
|
|
1097
|
-
const finalName =
|
|
1161
|
+
const finalName = RoundNaming.renderName(artifact, "final");
|
|
1098
1162
|
this.#persist(finalName, payload);
|
|
1099
1163
|
// The carrier is read-only the moment it exists; the draft beside it closes with it.
|
|
1100
1164
|
CarrierSeal.seal(this.#workspace.resolve(finalName));
|
|
@@ -1115,20 +1179,55 @@ export class Ledger {
|
|
|
1115
1179
|
* shapes; it is READ-ONLY (every write goes through `persistHandoff`'s canonical
|
|
1116
1180
|
* spelling). */
|
|
1117
1181
|
resolveHandoffName(op, type, params = {}) {
|
|
1118
|
-
|
|
1182
|
+
// The attempt the read resolves is the round's LATEST recorded one unless the
|
|
1183
|
+
// caller names it: a re-dispatched review lands at `-a{n}`, and its fix leg only
|
|
1184
|
+
// knows the cycle. Without this the read would address attempt 1's name (or its
|
|
1185
|
+
// final) while the digest gate compares the latest attempt's — a false mismatch.
|
|
1186
|
+
const resolved = this.#attemptAware(op, type, params);
|
|
1187
|
+
const canonical = this.handoffName(op, type, resolved);
|
|
1119
1188
|
// P31 §2.3 — the FINAL carrier wins the read whenever the round has one: it is the
|
|
1120
1189
|
// 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).
|
|
1122
|
-
|
|
1123
|
-
const final = this.#naming.finalName(canonical, params.round);
|
|
1190
|
+
// un-materialized payload whose findings carry no engine id).
|
|
1191
|
+
const final = RoundNaming.renderName(_a.#artifactOf(op, type, resolved), "final");
|
|
1124
1192
|
if (final !== canonical && this.#read(final) !== null)
|
|
1125
1193
|
return final;
|
|
1126
|
-
if (!RETIRED_SPEC_LINE_KEYS.has(type)
|
|
1127
|
-
return canonical;
|
|
1194
|
+
if (!RETIRED_SPEC_LINE_KEYS.has(type)) {
|
|
1195
|
+
return this.#legacyCarrierName(op, type, resolved) ?? canonical;
|
|
1128
1196
|
}
|
|
1197
|
+
if (this.#read(canonical) !== null)
|
|
1198
|
+
return canonical;
|
|
1129
1199
|
const retired = _a.#retiredCarrierName(op, params);
|
|
1130
1200
|
return this.#read(retired) === null ? canonical : retired;
|
|
1131
1201
|
}
|
|
1202
|
+
/** The pre-P34 cycle-less spelling of the round's own family name — the ONE carrier
|
|
1203
|
+
* the P34 respelling moved (`tasks-{tasks}-implement.json` → `…-implement-{cycle}.json`),
|
|
1204
|
+
* so a folded legacy record (no recorded path, no digest) still resolves its own
|
|
1205
|
+
* bytes instead of reading as absent while the orphan scan still claims the file.
|
|
1206
|
+
* The rung is READ-ONLY and cycle-1 · attempt-1 alone: the legacy spelling carried
|
|
1207
|
+
* neither coordinate, so no later cycle or attempt may read it. null when the op is
|
|
1208
|
+
* not an implement, the round is past its first cycle/attempt, the family does not
|
|
1209
|
+
* exist, the legacy name IS the canonical one, or the file is absent. */
|
|
1210
|
+
#legacyCarrierName(op, type, params) {
|
|
1211
|
+
if (RoundRecords.opOf(op) !== "implement")
|
|
1212
|
+
return null;
|
|
1213
|
+
if ((params.round ?? 1) !== 1 || (params.attempt ?? 1) !== 1)
|
|
1214
|
+
return null;
|
|
1215
|
+
if (!this.#families.includes(`${op}.${type}`))
|
|
1216
|
+
return null;
|
|
1217
|
+
const legacy = this.handoffName(op, type, { tasks: params.tasks });
|
|
1218
|
+
if (legacy === this.handoffName(op, type, params))
|
|
1219
|
+
return null;
|
|
1220
|
+
return this.#read(legacy) === null ? null : legacy;
|
|
1221
|
+
}
|
|
1222
|
+
/** The params one READ resolves under — the caller's attempt when it names one, else
|
|
1223
|
+
* the round's latest recorded attempt (a fix leg knows the cycle, not the review's
|
|
1224
|
+
* attempt). Absent records leave the params untouched (the present-facts face). */
|
|
1225
|
+
#attemptAware(op, type, params) {
|
|
1226
|
+
if (params.attempt !== undefined)
|
|
1227
|
+
return params;
|
|
1228
|
+
const latest = this.#latestRecordOf(op, type, params)?.attempt;
|
|
1229
|
+
return latest === undefined ? params : { ...params, attempt: latest };
|
|
1230
|
+
}
|
|
1132
1231
|
/** The resolved handoff path — `resolveHandoffName`'s on-disk form (the read face's
|
|
1133
1232
|
* single path exit; the writers keep `handoffPath`). */
|
|
1134
1233
|
resolveHandoffPath(op, type, params = {}) {
|
|
@@ -1169,27 +1268,63 @@ export class Ledger {
|
|
|
1169
1268
|
return this.#latestRecordOf(op, type, params)?.carrierDigest ?? null;
|
|
1170
1269
|
}
|
|
1171
1270
|
/** 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).
|
|
1173
|
-
*
|
|
1174
|
-
* the
|
|
1271
|
+
* carries no record for it (a legacy row, or a round never dispatched). When the
|
|
1272
|
+
* caller NAMES an attempt (`params.attempt`), that attempt is the one selected: the
|
|
1273
|
+
* name a read resolves and the digest it compares against come from the SAME record,
|
|
1274
|
+
* so a re-dispatched cycle (attempt 2 booked, attempt 1's final still on disk by
|
|
1275
|
+
* conservation) can never read attempt 1's bytes against attempt 2's digest. */
|
|
1175
1276
|
#latestRecordOf(op, type, params) {
|
|
1176
1277
|
const mode = RoundRecords.opOf(op) ?? op;
|
|
1177
1278
|
const round = params.round === undefined ? null : Number(params.round);
|
|
1178
1279
|
return this.recordsOf(this.#roundKey(type, params), type)
|
|
1179
1280
|
.filter((record) => record.op === mode)
|
|
1180
1281
|
.filter((record) => round === null || record.cycle === round)
|
|
1282
|
+
.filter((record) => params.attempt === undefined || record.attempt === params.attempt)
|
|
1181
1283
|
.reduce((newest, record) => (newest === null || record.attempt >= newest.attempt ? record : newest), null);
|
|
1182
1284
|
}
|
|
1183
|
-
/** The review carrier a round's fix leg reads as `--reviews` — the
|
|
1184
|
-
*
|
|
1185
|
-
* the
|
|
1186
|
-
*
|
|
1187
|
-
*
|
|
1285
|
+
/** The review carrier a round's fix leg reads as `--reviews` — the same-cycle review
|
|
1286
|
+
* record's own carrier identity through the ONE accessor (step ① the recorded path,
|
|
1287
|
+
* step ②③ the read ladder a pre-P31 row needs). A record that resolves no carrier
|
|
1288
|
+
* (the ladder's candidates are all absent) reads `""` — the soft `unrecorded` face,
|
|
1289
|
+
* never a fabricated name. No record at all falls back to the family name of the
|
|
1290
|
+
* cycle's latest review attempt (attempt 1 when none): a fix leg knows the cycle,
|
|
1291
|
+
* never the review's attempt, so the FRAME's attempt is deliberately not inherited. */
|
|
1188
1292
|
#reviewsPathOf(type, params, round) {
|
|
1189
|
-
const
|
|
1293
|
+
const reviewParams = { tasks: params.tasks, round };
|
|
1294
|
+
const record = this.#latestRecordOf("review", type, reviewParams);
|
|
1295
|
+
if (record === null)
|
|
1296
|
+
return this.resolveHandoffPath("review", type, reviewParams);
|
|
1297
|
+
return this.carrierPathOf(type, String(this.#roundKey(type, params)), record);
|
|
1298
|
+
}
|
|
1299
|
+
/** One record's carrier PATH — the ONE read face of a record's carrier identity
|
|
1300
|
+
* (spec §2.10), so no consumer spells `record.carrierPath` itself. Step ① returns the
|
|
1301
|
+
* path the record already remembers (the historical fact — a pre-P34 row keeps its
|
|
1302
|
+
* own spelling, zero migration). Step ② otherwise resolves the read ladder
|
|
1303
|
+
* `resolveHandoffName` owns, seeded with the record's FULL identity (line · op ·
|
|
1304
|
+
* cycle · attempt) — a bare `renderPath("final")` would miss a pre-P31 row that never
|
|
1305
|
+
* minted the `.c{cycle}` spelling. Step ③ probes the ladder's answer: a ladder that
|
|
1306
|
+
* reports a never-minted name reads as "no carrier" (empty), never as a path. */
|
|
1307
|
+
carrierPathOf(type, key, record) {
|
|
1308
|
+
const recorded = record.carrierPath;
|
|
1190
1309
|
if (typeof recorded === "string" && recorded !== "")
|
|
1191
1310
|
return recorded;
|
|
1192
|
-
|
|
1311
|
+
const name = this.#resolvedCarrierName(type, key, record);
|
|
1312
|
+
return this.#read(name) === null ? "" : this.#workspace.resolve(name);
|
|
1313
|
+
}
|
|
1314
|
+
/** Step ② of `carrierPathOf` — the NAME the record's identity resolves to: the
|
|
1315
|
+
* retired `spec-{op}-{round}.json` spelling for a migrated row (its `spec` family is
|
|
1316
|
+
* not in the live config table, so the ladder would throw), the read ladder's answer
|
|
1317
|
+
* for every live line. */
|
|
1318
|
+
#resolvedCarrierName(type, key, record) {
|
|
1319
|
+
if (key === RETIRED_SPEC_KEY) {
|
|
1320
|
+
return _a.#retiredCarrierName(record.op, { round: record.cycle });
|
|
1321
|
+
}
|
|
1322
|
+
const params = {
|
|
1323
|
+
tasks: type === "wave" ? key : undefined,
|
|
1324
|
+
round: record.cycle,
|
|
1325
|
+
attempt: record.attempt,
|
|
1326
|
+
};
|
|
1327
|
+
return this.resolveHandoffName(record.op, type, params);
|
|
1193
1328
|
}
|
|
1194
1329
|
/** The retired document-line carrier name of one round — `spec-review-{round}.json` /
|
|
1195
1330
|
* `spec-fix-{round}.json`. It lives here, never in the family table: it is a read
|
|
@@ -1197,31 +1332,53 @@ export class Ledger {
|
|
|
1197
1332
|
static #retiredCarrierName(op, params) {
|
|
1198
1333
|
return `${RETIRED_SPEC_KEY}-${op}-${params.round ?? ""}.json`;
|
|
1199
1334
|
}
|
|
1200
|
-
/** The workspace's ORPHAN handoff
|
|
1201
|
-
* (line key, op,
|
|
1202
|
-
*
|
|
1203
|
-
*
|
|
1204
|
-
*
|
|
1205
|
-
*
|
|
1206
|
-
*
|
|
1207
|
-
*
|
|
1335
|
+
/** The workspace's ORPHAN handoff files — the carrier files (draft or final) whose
|
|
1336
|
+
* (line key, op, cycle, attempt) never landed in `progress.json`. The board and the
|
|
1337
|
+
* `--dry-run` preview render them; this is a PURE READ — the engine never writes,
|
|
1338
|
+
* moves or deletes a carrier. The family names are the ledger's own single naming
|
|
1339
|
+
* truth (no second pattern), and the owning row is read through the ONE basis
|
|
1340
|
+
* `rowFor` establishes — the file's own line word IS its declaration — so a
|
|
1341
|
+
* migrated workspace's carrier resolves its live row instead of reading as an
|
|
1342
|
+
* orphan.
|
|
1343
|
+
*
|
|
1344
|
+
* OWNERSHIP IS THE RECORD, NEVER ITS VERDICT (spec §2.12): a round that acted and
|
|
1345
|
+
* then failed still owns the file it wrote — completion is the judgment face, and
|
|
1346
|
+
* reading it here would relabel an honest failure's carrier as an orphan and hand it
|
|
1347
|
+
* to a recovery pass that deletes child work.
|
|
1348
|
+
*
|
|
1349
|
+
* The identity is the fast tier; the LEGACY tier compares the record's own carrier
|
|
1350
|
+
* path by basename (a pre-P34 row remembers an absolute path while the scan yields a
|
|
1351
|
+
* bare name), read once through `carrierPathOf` — the only accessor of the record's
|
|
1352
|
+
* carrier identity. */
|
|
1208
1353
|
orphanHandoffs() {
|
|
1209
1354
|
const progress = this.readProgress() ?? this.emptyProgress();
|
|
1210
1355
|
const orphans = [];
|
|
1211
1356
|
for (const name of this.#workspaceFiles()) {
|
|
1212
|
-
const owner = _a.#handoffOwner(name
|
|
1357
|
+
const owner = _a.#handoffOwner(name);
|
|
1213
1358
|
if (owner === null)
|
|
1214
1359
|
continue;
|
|
1215
|
-
const
|
|
1216
|
-
const
|
|
1217
|
-
|
|
1218
|
-
.
|
|
1219
|
-
if (!
|
|
1360
|
+
const records = RoundRecords.of(_a.#ownerRow(progress, owner.key));
|
|
1361
|
+
const identity = `${owner.op}:${owner.round}:${owner.attempt}`;
|
|
1362
|
+
const claimed = records.some((record) => `${record.op}:${record.cycle}:${record.attempt}` === identity ||
|
|
1363
|
+
basename(this.carrierPathOf(owner.type, owner.key, record)) === name);
|
|
1364
|
+
if (!claimed)
|
|
1220
1365
|
orphans.push(name);
|
|
1221
|
-
}
|
|
1222
1366
|
}
|
|
1223
1367
|
return orphans.sort();
|
|
1224
1368
|
}
|
|
1369
|
+
/** The row one carrier file's line word resolves to. The retired `spec` twin is a FILE
|
|
1370
|
+
* NAME a live row already outlived: the workspace holds ONE identity document, so the
|
|
1371
|
+
* word resolves onto whichever document word that row now declares (`phase-spec` /
|
|
1372
|
+
* `overall` / `single-spec`), never onto a row name the migration retired. Every other
|
|
1373
|
+
* word — a wave's tasks, `plan`, `branch` — reads through `rowFor`'s ONE basis. */
|
|
1374
|
+
static #ownerRow(progress, key) {
|
|
1375
|
+
if (key !== RETIRED_SPEC_KEY)
|
|
1376
|
+
return _a.rowFor(progress, key, _a.#lineWord(key));
|
|
1377
|
+
const literal = _a.rowFor(progress, key, null);
|
|
1378
|
+
if (literal !== undefined)
|
|
1379
|
+
return literal;
|
|
1380
|
+
return progress.waves.find((row) => RETIRED_SPEC_LINE_KEYS.has(row.wave));
|
|
1381
|
+
}
|
|
1225
1382
|
/** A handoff file's key as a declared line word — the three document words declare
|
|
1226
1383
|
* themselves; every other key (a wave's tasks, `plan`, `branch`) declares nothing
|
|
1227
1384
|
* and reads literally. */
|
|
@@ -1240,51 +1397,54 @@ export class Ledger {
|
|
|
1240
1397
|
return [];
|
|
1241
1398
|
}
|
|
1242
1399
|
}
|
|
1243
|
-
/** Which recorded round one handoff file belongs to — the
|
|
1244
|
-
*
|
|
1245
|
-
*
|
|
1246
|
-
*
|
|
1247
|
-
|
|
1400
|
+
/** Which recorded round one handoff file belongs to — the ONE renderer read
|
|
1401
|
+
* backwards: `<line>-<op>[-<cycle>][-a<attempt>][.c<cycle>].json`, the retired
|
|
1402
|
+
* document-line `spec` twin included (a still-unbooked draft can carry it). The
|
|
1403
|
+
* parse yields the same four coordinates the naming face renders, so the orphan
|
|
1404
|
+
* test compares an identity with an identity — never a spelling with a spelling.
|
|
1405
|
+
* Null for a non-carrier file. */
|
|
1406
|
+
static #handoffOwner(name) {
|
|
1248
1407
|
// A FINAL carrier (`<stem>.c{round}.json`, P31 §2.3) is the same artifact as its
|
|
1249
1408
|
// draft — the cycle is the name's own suffix, never a second family.
|
|
1250
1409
|
const draft = name.replace(/\.c\d+\.json$/, ".json");
|
|
1251
|
-
|
|
1252
|
-
|
|
1253
|
-
|
|
1254
|
-
|
|
1255
|
-
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
|
-
|
|
1259
|
-
|
|
1260
|
-
|
|
1261
|
-
|
|
1262
|
-
|
|
1263
|
-
|
|
1410
|
+
const wave = _a.#WAVE_CARRIER.exec(draft);
|
|
1411
|
+
if (wave !== null) {
|
|
1412
|
+
const [, line = "", op = "", cycle, attempt] = wave;
|
|
1413
|
+
// The wave row keys the task GROUP alone — the `tasks-` spine is the name's, not
|
|
1414
|
+
// the key's. The legacy cycle-less implement spelling is the fixed family's round 1.
|
|
1415
|
+
return {
|
|
1416
|
+
type: "wave",
|
|
1417
|
+
key: line.replace(/^tasks-/, ""),
|
|
1418
|
+
op,
|
|
1419
|
+
round: cycle === undefined ? 1 : Number(cycle),
|
|
1420
|
+
attempt: _a.#attemptOf(attempt),
|
|
1421
|
+
};
|
|
1422
|
+
}
|
|
1423
|
+
const line = _a.#LINE_CARRIER.exec(draft);
|
|
1424
|
+
if (line !== null) {
|
|
1425
|
+
const [, key = "", op = "", cycle = "", attempt] = line;
|
|
1426
|
+
return {
|
|
1427
|
+
type: key,
|
|
1428
|
+
key,
|
|
1429
|
+
op,
|
|
1430
|
+
round: Number(cycle),
|
|
1431
|
+
attempt: _a.#attemptOf(attempt),
|
|
1432
|
+
};
|
|
1264
1433
|
}
|
|
1265
1434
|
return null;
|
|
1266
1435
|
}
|
|
1267
|
-
/** The
|
|
1268
|
-
*
|
|
1269
|
-
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
*
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
static #familyCaptures(spelling, name) {
|
|
1280
|
-
const escaped = spelling.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
1281
|
-
const pattern = new RegExp(`^${escaped
|
|
1282
|
-
.replace("\\{tasks\\}", "(?<tasks>.+?)")
|
|
1283
|
-
.replace("\\{round\\}", "(?<round>\\d+)")}$`);
|
|
1284
|
-
const match = pattern.exec(name);
|
|
1285
|
-
if (match === null)
|
|
1286
|
-
return null;
|
|
1287
|
-
return { tasks: match.groups?.tasks ?? null, round: match.groups?.round ?? null };
|
|
1436
|
+
/** The wave line's carrier spelling, read backwards — the task key is a lazy span,
|
|
1437
|
+
* the op one of the three words, the cycle and the attempt optional (the legacy
|
|
1438
|
+
* cycle-less implement name harvests no cycle). */
|
|
1439
|
+
static #WAVE_CARRIER = /^(tasks-.+?)-(implement|review|fix)(?:-(\d+))?(?:-a(\d+))?\.json$/;
|
|
1440
|
+
/** The single-target lines' carrier spelling — `branch` and the doc words (the
|
|
1441
|
+
* words of the ONE target-face table, the retired `spec` twin included), every one
|
|
1442
|
+
* of which carries its cycle. */
|
|
1443
|
+
static #LINE_CARRIER = new RegExp(`^(${[...Object.keys(targetFaces).filter((word) => word !== "wave"), RETIRED_SPEC_KEY].join("|")})-(review|fix)-(\\d+)(?:-a(\\d+))?\\.json$`);
|
|
1444
|
+
/** An absent attempt segment is the first attempt — the naming face never renders
|
|
1445
|
+
* `-a1`, so the parse and the render agree on the identity of attempt 1. */
|
|
1446
|
+
static #attemptOf(captured) {
|
|
1447
|
+
return captured === undefined ? 1 : Number(captured);
|
|
1288
1448
|
}
|
|
1289
1449
|
// -------------------------------------------------------------------------
|
|
1290
1450
|
// crash — the lane crash → recovery record
|
|
@@ -1337,7 +1497,10 @@ export class Ledger {
|
|
|
1337
1497
|
#consecutiveS1Run(type, params, round) {
|
|
1338
1498
|
let run = 0;
|
|
1339
1499
|
for (let index = round; index >= 1; index--) {
|
|
1340
|
-
|
|
1500
|
+
// The frame's attempt belongs to the op it was allocated for — a review read
|
|
1501
|
+
// resolves the review's own latest attempt (the ledger's own fallback), never
|
|
1502
|
+
// the fix frame's.
|
|
1503
|
+
const carrier = this.readHandoff("review", type, { tasks: params.tasks, round: index });
|
|
1341
1504
|
if (carrier === null)
|
|
1342
1505
|
break;
|
|
1343
1506
|
if (this.#blockerCountOf(carrier) === 0)
|
|
@@ -1393,8 +1556,11 @@ export class Ledger {
|
|
|
1393
1556
|
consecutiveS1: 0,
|
|
1394
1557
|
};
|
|
1395
1558
|
}
|
|
1559
|
+
// The review side is addressed by the CYCLE alone: an attempt belongs to the op it
|
|
1560
|
+
// was allocated for, so a fix at attempt 2 must never address the review's `-a2`
|
|
1561
|
+
// (the read's own attempt fallback resolves the review's latest recorded one).
|
|
1562
|
+
const reviewParams = { tasks: params.tasks, round };
|
|
1396
1563
|
if (op === "review") {
|
|
1397
|
-
const reviewParams = { ...params, round };
|
|
1398
1564
|
const carrier = this.readHandoff("review", type, reviewParams);
|
|
1399
1565
|
if (carrier === null)
|
|
1400
1566
|
return null;
|
|
@@ -1405,8 +1571,8 @@ export class Ledger {
|
|
|
1405
1571
|
// source shared with the fix leg below (`HandoffSchema.conclusionOf`).
|
|
1406
1572
|
status: this.#handoffSchema.conclusionOf("judge", carrier),
|
|
1407
1573
|
findings: this.#findingsOf(carrier),
|
|
1408
|
-
reviewsPath: this.#reviewsPathOf(type,
|
|
1409
|
-
consecutiveS1: this.#consecutiveS1Run(type,
|
|
1574
|
+
reviewsPath: this.#reviewsPathOf(type, reviewParams, round),
|
|
1575
|
+
consecutiveS1: this.#consecutiveS1Run(type, reviewParams, round),
|
|
1410
1576
|
};
|
|
1411
1577
|
}
|
|
1412
1578
|
// op === "fix" — the C5-1 fingerprint: the fix round judges the source review's input
|
|
@@ -1414,9 +1580,8 @@ export class Ledger {
|
|
|
1414
1580
|
// matching the review branch's contract: a fix whose blocker set was never read must
|
|
1415
1581
|
// not be judged a clean zero-findings round — the next-hop derivation cannot close a
|
|
1416
1582
|
// line it could not read.
|
|
1417
|
-
const reviewParams = { ...params, round };
|
|
1418
1583
|
const reviewCarrier = this.readHandoff("review", type, reviewParams);
|
|
1419
|
-
const fixCarrier = this.readHandoff("fix", type,
|
|
1584
|
+
const fixCarrier = this.readHandoff("fix", type, { ...params, round });
|
|
1420
1585
|
if (reviewCarrier === null || fixCarrier === null)
|
|
1421
1586
|
return null;
|
|
1422
1587
|
return {
|
|
@@ -1425,8 +1590,8 @@ export class Ledger {
|
|
|
1425
1590
|
// work plane reads its status) — the same `conclusionOf` single source (D27).
|
|
1426
1591
|
status: this.#handoffSchema.conclusionOf(this.planeOf("fix"), fixCarrier),
|
|
1427
1592
|
findings: this.#findingsOf(reviewCarrier),
|
|
1428
|
-
reviewsPath: this.#reviewsPathOf(type,
|
|
1429
|
-
consecutiveS1: this.#consecutiveS1Run(type,
|
|
1593
|
+
reviewsPath: this.#reviewsPathOf(type, reviewParams, round),
|
|
1594
|
+
consecutiveS1: this.#consecutiveS1Run(type, reviewParams, round),
|
|
1430
1595
|
};
|
|
1431
1596
|
}
|
|
1432
1597
|
}
|
package/dist/session/pipeline.js
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
//
|
|
13
13
|
// Constructed with the node's `Ledger` (the `Ledger` / `Lifecycle` shape: one read
|
|
14
14
|
// face injected, no global state). The plan is never read here — the guarded plan
|
|
15
|
-
// read stays on the board side and rides in as `
|
|
15
|
+
// read stays on the board side and rides in as `plan`, so this module holds
|
|
16
16
|
// zero file-system read and no second plan parse.
|
|
17
17
|
//
|
|
18
18
|
// The four rules over the ONE `PIPELINE_FACES` order:
|
|
@@ -172,7 +172,7 @@ export class PipelineFrontier {
|
|
|
172
172
|
* alone would fall into rule 2 and render the wave face's own exit
|
|
173
173
|
* (`PIPELINE_NEXT.wave`), a worse literal than the one being removed. */
|
|
174
174
|
#waveState(input) {
|
|
175
|
-
const graph = input.
|
|
175
|
+
const graph = input.plan.graph();
|
|
176
176
|
const waveKey = graph === null ? null : this.#waveKeyOf(graph);
|
|
177
177
|
const entered = graph !== null && this.#wavesEntered(graph);
|
|
178
178
|
return {
|