@oscaner-skills/cdd-engine 4.2.0 → 4.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +38 -9
- package/README.zh-CN.md +43 -9
- package/dist/contract/completion-criterion.js +351 -0
- package/dist/contract/declare.js +181 -43
- package/dist/contract/doc.js +84 -271
- package/dist/contract/frontmatter.js +2 -1
- package/dist/contract/home-extractors.js +49 -316
- package/dist/contract/invariants.js +400 -296
- package/dist/contract/judge.js +74 -49
- package/dist/contract/lint.js +3 -2
- package/dist/contract/liveness-signal.js +103 -0
- package/dist/contract/markdown-document.js +410 -0
- package/dist/contract/markdown-tree-types.js +6 -0
- package/dist/contract/markdown-tree.js +137 -0
- package/dist/contract/project.js +1 -1
- package/dist/contract/rules.js +106 -0
- package/dist/contract/selector-engine.js +332 -0
- package/dist/contract/selector-spec.js +74 -0
- package/dist/contract/skill-anatomy.js +29 -1
- package/dist/contract/task-block-grammar.js +285 -0
- package/dist/contract/task-blocks.js +65 -0
- package/dist/contract/translate.js +21 -0
- package/dist/contract/wave-width.js +15 -0
- package/dist/face/board-view.js +401 -131
- package/dist/face/capsule.js +66 -89
- package/dist/face/cli.js +116 -35
- package/dist/face/declare.js +36 -18
- package/dist/face/gate.js +117 -40
- package/dist/face/init.js +1 -1
- package/dist/face/lifecycle.js +540 -123
- package/dist/face/preview.js +43 -10
- package/dist/face/route-render.js +51 -21
- package/dist/face/termination.js +135 -261
- package/dist/face/words.js +134 -12
- package/dist/infra/atomic.js +15 -0
- package/dist/infra/git.js +25 -0
- package/dist/infra/proc.js +150 -0
- package/dist/infra/round-log.js +104 -0
- package/dist/infra/runtime.js +16 -4
- package/dist/infra/workspace.js +7 -2
- package/dist/render/brief.js +15 -17
- package/dist/render/skeleton.js +41 -28
- package/dist/render/templates.js +128 -84
- package/dist/session/faces.js +47 -20
- package/dist/session/graph.js +13 -37
- package/dist/session/handoff-schema.js +16 -8
- package/dist/session/inflight.js +282 -0
- package/dist/session/ledger.js +581 -136
- package/dist/session/line-identity.js +33 -0
- package/dist/session/next.js +138 -80
- package/dist/session/preflight.js +276 -68
- package/dist/session/round-naming.js +56 -8
- package/dist/session/run.js +317 -78
- package/dist/session/wave.js +94 -14
- package/package.json +13 -3
package/dist/contract/judge.js
CHANGED
|
@@ -10,10 +10,11 @@
|
|
|
10
10
|
import { Words } from "../face/words.js";
|
|
11
11
|
import { declaredRegistries } from "./declare.js";
|
|
12
12
|
import { docTypeParsers } from "./doc.js";
|
|
13
|
-
import {
|
|
14
|
-
import {
|
|
13
|
+
import { NodeFs } from "./invariants.js";
|
|
14
|
+
import { MarkdownTree } from "./markdown-tree.js";
|
|
15
15
|
import { DOC_KEYS, Projector } from "./project.js";
|
|
16
|
-
import {
|
|
16
|
+
import { RULE_REGISTRY } from "./rules.js";
|
|
17
|
+
import { RowSource, Translator } from "./translate.js";
|
|
17
18
|
/**
|
|
18
19
|
* The contract coordinator — the interpreter's single face. One instance; the
|
|
19
20
|
* strategy set is stateless (each strategy reads its judgment data from the
|
|
@@ -21,24 +22,26 @@ import { Translator } from "./translate.js";
|
|
|
21
22
|
*
|
|
22
23
|
* The P7 structure-plane canonicalize seam (design spec §2.1) + the T6 front-matter
|
|
23
24
|
* delivery seam (§2.2): the Contract self-holds a Translator, and validate()
|
|
24
|
-
* canonicalizes EVERY body line once at the row source — the normalized view
|
|
25
|
-
*
|
|
25
|
+
* canonicalizes EVERY body line once at the row source — the normalized view the
|
|
26
|
+
* parse face and the tree both read. The split order is RAW-first: the raw
|
|
26
27
|
* content resolves its front-matter head BEFORE any canonicalize (front matter is
|
|
27
28
|
* data — the canonicalize view would silently rewrite registered Chinese aliases
|
|
28
29
|
* inside header values), then the post-fence body lines canonicalize and the SAME
|
|
29
|
-
* typed head rides into parse(lines, head)
|
|
30
|
-
*
|
|
31
|
-
*
|
|
30
|
+
* typed head rides into parse(lines, head). Every valuePattern judgment face
|
|
31
|
+
* (presence occurrenceNodes · domain carrierNodes · section-scoped · crosslink)
|
|
32
|
+
* matches the view, so the legacy Chinese charter
|
|
32
33
|
* markers (the doc-arch decision-group / upstream-endorsements leaves) match their
|
|
33
34
|
* English canonical element patterns through the recognition face — never a second
|
|
34
35
|
* hand-written zh pattern. The view is never written back: the source document
|
|
35
36
|
* stays byte-identical and the original lines remain in input.content.
|
|
37
|
+
*
|
|
38
|
+
* The strategy composition is DECLARED, not hard-coded (P21 §3.1): `policy()` walks
|
|
39
|
+
* the rule declaration surface's doc-scope rows and instantiates each row's factory,
|
|
40
|
+
* and `ruleRows()` returns the same rows for the `checked` list — one list, one
|
|
41
|
+
* source, zero declaration re-copy.
|
|
36
42
|
*/
|
|
37
43
|
export class Contract {
|
|
38
|
-
/** The per-doc-key policy sets — the
|
|
39
|
-
* All fifteen strategies are registry-driven and judge every doc type, so the
|
|
40
|
-
* per-key sets are the same ordered family; the record keying is what a future
|
|
41
|
-
* per-type ordering/selection change would carry. */
|
|
44
|
+
/** The per-doc-key policy sets — the declaration-derived doc-scope strategy family. */
|
|
42
45
|
#strategies;
|
|
43
46
|
/** The projection carrier — the derived parse/skeleton faces the judgment reads. */
|
|
44
47
|
#projector;
|
|
@@ -47,26 +50,77 @@ export class Contract {
|
|
|
47
50
|
* of the P7 translation layer); embedded like the projector, so the production
|
|
48
51
|
* construction points (`new Contract()`) stay argument-free. */
|
|
49
52
|
#translator;
|
|
53
|
+
/** The row source — the ONE canonicalize seam (split + canonicalize once). */
|
|
54
|
+
#rowSource;
|
|
50
55
|
constructor() {
|
|
51
|
-
this.#strategies = Contract
|
|
56
|
+
this.#strategies = Contract.policy();
|
|
52
57
|
this.#projector = new Projector(declaredRegistries);
|
|
53
58
|
this.#translator = new Translator(new Words());
|
|
59
|
+
this.#rowSource = new RowSource(this.#translator);
|
|
60
|
+
}
|
|
61
|
+
/** The declared doc-scope strategy composition — derived from `RULE_REGISTRY`
|
|
62
|
+
* (only `scope: "doc"` rows; a doc judgment never runs a ledger rule). One
|
|
63
|
+
* strategy instance per row per construction. */
|
|
64
|
+
static policy() {
|
|
65
|
+
const declarations = RULE_REGISTRY.filter((declaration) => declaration.scope === "doc");
|
|
66
|
+
const policy = {};
|
|
67
|
+
for (const key of DOC_KEYS) {
|
|
68
|
+
policy[key] = declarations
|
|
69
|
+
.filter((declaration) => declaration.docKeys === "all" || declaration.docKeys.includes(key))
|
|
70
|
+
.map((declaration) => declaration.create());
|
|
71
|
+
}
|
|
72
|
+
return policy;
|
|
73
|
+
}
|
|
74
|
+
/** The checked-list data face — every declaration row (both scopes), in registry
|
|
75
|
+
* order. The pre-flight renders these rows; it never writes a second list. */
|
|
76
|
+
static ruleRows() {
|
|
77
|
+
return RULE_REGISTRY;
|
|
54
78
|
}
|
|
55
|
-
/** validate(doc) — split, parse, compose, run, aggregate. The single judgment entry.
|
|
79
|
+
/** validate(doc) — split, parse, compose, run, aggregate. The single doc judgment entry.
|
|
56
80
|
* The RAW content resolves its front-matter head first (the data plane — never
|
|
57
81
|
* canonicalized); the post-fence body lines canonicalize ONCE at the row source
|
|
58
82
|
* (the normalized view), and the SAME typed head rides into parse(lines, head)
|
|
59
83
|
* and JudgeContext.head (§2.2's delivery seam — the chain facts the head carries
|
|
60
84
|
* are the same record the invariants judge). The source stays intact. */
|
|
61
85
|
validate(input) {
|
|
62
|
-
const
|
|
63
|
-
const
|
|
64
|
-
const
|
|
65
|
-
|
|
86
|
+
const context = this.#contextOf(input);
|
|
87
|
+
const findings = [];
|
|
88
|
+
for (const strategy of this.#strategies[input.docKey]) {
|
|
89
|
+
findings.push(...strategy.evaluate(context));
|
|
90
|
+
}
|
|
91
|
+
return findings;
|
|
92
|
+
}
|
|
93
|
+
/** validateLedger(input, ledger) — the ledger-scope judgment entry (P21 §3.1): the
|
|
94
|
+
* plan document under judgment plus the ledger fact bundle, judged by every
|
|
95
|
+
* `scope: "ledger"` declaration applicable to the input's doc key. Two arguments,
|
|
96
|
+
* one judgment — the doc-scope rules never run here (and vice versa). */
|
|
97
|
+
validateLedger(input, ledger) {
|
|
98
|
+
const context = this.#contextOf(input);
|
|
99
|
+
const findings = [];
|
|
100
|
+
for (const declaration of RULE_REGISTRY) {
|
|
101
|
+
if (declaration.scope !== "ledger")
|
|
102
|
+
continue;
|
|
103
|
+
if (declaration.docKeys !== "all" && !declaration.docKeys.includes(input.docKey))
|
|
104
|
+
continue;
|
|
105
|
+
const rule = declaration.create();
|
|
106
|
+
findings.push(...rule.evaluate(context, ledger));
|
|
107
|
+
}
|
|
108
|
+
return findings;
|
|
109
|
+
}
|
|
110
|
+
/** The assembled judgment context — the shared split/parse/translate seam of both
|
|
111
|
+
* entries (one context construction, one canonicalize pass). */
|
|
112
|
+
#contextOf(input) {
|
|
113
|
+
// The row source resolves the raw front-matter head, then canonicalizes the
|
|
114
|
+
// body ONCE (never a per-line translator API): the line face, the tree face and
|
|
115
|
+
// the parse face all read the same normalized bytes.
|
|
116
|
+
const { head, text, lines } = this.#rowSource.read(input.content);
|
|
117
|
+
const tree = MarkdownTree.parse(text);
|
|
118
|
+
const parsed = docTypeParsers[input.docKey].parse(lines, head, tree);
|
|
119
|
+
return {
|
|
66
120
|
docKey: input.docKey,
|
|
67
121
|
parsed,
|
|
68
122
|
head,
|
|
69
|
-
|
|
123
|
+
tree,
|
|
70
124
|
path: input.path,
|
|
71
125
|
root: input.root,
|
|
72
126
|
slices: this.#projector.slices()[input.docKey],
|
|
@@ -77,36 +131,7 @@ export class Contract {
|
|
|
77
131
|
translator: this.#translator,
|
|
78
132
|
slugIndex: input.slugIndex,
|
|
79
133
|
fs: input.fs ?? new NodeFs(),
|
|
134
|
+
taskLayers: input.taskLayers,
|
|
80
135
|
};
|
|
81
|
-
const findings = [];
|
|
82
|
-
for (const strategy of this.#strategies[input.docKey]) {
|
|
83
|
-
findings.push(...strategy.evaluate(context));
|
|
84
|
-
}
|
|
85
|
-
return findings;
|
|
86
|
-
}
|
|
87
|
-
/** The declared strategy composition — one ordered family set per doc key. */
|
|
88
|
-
static #buildPolicy() {
|
|
89
|
-
const family = [
|
|
90
|
-
new PresenceInvariant(),
|
|
91
|
-
new UniquenessInvariant(),
|
|
92
|
-
new DomainInvariant(),
|
|
93
|
-
new CrosslinkInvariant(),
|
|
94
|
-
new OrderInvariant(),
|
|
95
|
-
new ContinuityInvariant(),
|
|
96
|
-
new ResidueInvariant(),
|
|
97
|
-
new HollowInvariant(),
|
|
98
|
-
new SelfBoundedInvariant(),
|
|
99
|
-
new LinkShapeInvariant(),
|
|
100
|
-
new FileExistenceInvariant(),
|
|
101
|
-
new SiblingScanInvariant(),
|
|
102
|
-
new SlugRefInvariant(),
|
|
103
|
-
new CrossDocChainInvariant(),
|
|
104
|
-
new SectionScopedDomainInvariant(),
|
|
105
|
-
];
|
|
106
|
-
const policy = {};
|
|
107
|
-
for (const key of DOC_KEYS) {
|
|
108
|
-
policy[key] = family;
|
|
109
|
-
}
|
|
110
|
-
return policy;
|
|
111
136
|
}
|
|
112
137
|
}
|
package/dist/contract/lint.js
CHANGED
|
@@ -41,7 +41,8 @@ export class LintPass extends MarkdownPrimitives {
|
|
|
41
41
|
#proseToken;
|
|
42
42
|
/** The derived `DependsOn id` value pattern (whole-token — the declared-edge values). */
|
|
43
43
|
#depIdToken;
|
|
44
|
-
/** The prose-owning task
|
|
44
|
+
/** The prose-owning task sections of the plan — the scanning-semantics surface (the
|
|
45
|
+
* reader's field keys; the declared anchors are the `#### Key` headings). */
|
|
45
46
|
#proseFieldKeys = ["Objective", "Acceptance"];
|
|
46
47
|
constructor() {
|
|
47
48
|
super();
|
|
@@ -50,7 +51,7 @@ export class LintPass extends MarkdownPrimitives {
|
|
|
50
51
|
this.#proseToken = new RegExp(this.#valuePatternOf(planEntries, "Task prose reference"), "g");
|
|
51
52
|
this.#depIdToken = new RegExp(this.#valuePatternOf(planEntries, "DependsOn id"));
|
|
52
53
|
for (const key of this.#proseFieldKeys) {
|
|
53
|
-
this.#valuePatternOf(planEntries,
|
|
54
|
+
this.#valuePatternOf(planEntries, `#### ${key}`);
|
|
54
55
|
}
|
|
55
56
|
}
|
|
56
57
|
/** run — the single observation entry: one Warn per offending surface. */
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/contract/liveness-signal.ts
|
|
2
|
+
// P22 T5 — the liveness signal contract + the four-state judge (design spec §4.2/§4.3).
|
|
3
|
+
// Both legs are evidence the CHILD itself produces, and nothing else can move them:
|
|
4
|
+
// · `LogGrowth` — the round log file's size (bytes arriving; zero parsing);
|
|
5
|
+
// · `CpuAdvance` — the process group's cumulative CPU (the additional leg).
|
|
6
|
+
// The retired workspace-mtime leg is GONE: a third party's writes into the tree could
|
|
7
|
+
// self-certify progress, which is exactly the false "still working" reading the phase
|
|
8
|
+
// removes. Its exclusion plane (`Sampler.excludesFor`, the tree walk) died with it, so
|
|
9
|
+
// "the engine's own writes never certify progress" is now structural rather than a
|
|
10
|
+
// declared exclusion.
|
|
11
|
+
//
|
|
12
|
+
// `LIVENESS_SIGNALS` is a PER-ROUND factory, never a module-level instance array: the
|
|
13
|
+
// sampler builds this round's signals from this round's context, so the self-held
|
|
14
|
+
// `readableAt` state cannot leak across rounds (a previous round's "was readable" must
|
|
15
|
+
// never testify for the next one). Each entry NAMES its leg, so the postmortem cells
|
|
16
|
+
// (`logSize` / `cpuMs`) address their leg by name, never by array position.
|
|
17
|
+
//
|
|
18
|
+
// `readableAt` is the tick at which the leg was last READ, retained across unreadable
|
|
19
|
+
// ticks — so "readable somewhere inside the window" is a judgeable present fact instead
|
|
20
|
+
// of a lost past.
|
|
21
|
+
//
|
|
22
|
+
// Module-level exports are types / the declared registry / the classes — zero
|
|
23
|
+
// behavior-carrying bare functions.
|
|
24
|
+
import { ProcessFacts } from "../infra/proc.js";
|
|
25
|
+
import { RoundLog } from "../infra/round-log.js";
|
|
26
|
+
/**
|
|
27
|
+
* LogGrowth — the round log's size. The file is created before the spawn (zero bytes)
|
|
28
|
+
* and only ever appended to, so it is readable and flat from the first tick: a child
|
|
29
|
+
* that never writes a byte reaches `stalled` instead of sitting in `unknown` until the
|
|
30
|
+
* wall-clock ceiling. A vanished / unreadable file is a null reading, not a throw.
|
|
31
|
+
*/
|
|
32
|
+
export class LogGrowth {
|
|
33
|
+
#path;
|
|
34
|
+
#clock;
|
|
35
|
+
#readableAt = null;
|
|
36
|
+
constructor(path, clock = Date.now) {
|
|
37
|
+
this.#path = path;
|
|
38
|
+
this.#clock = clock;
|
|
39
|
+
}
|
|
40
|
+
sample() {
|
|
41
|
+
const now = this.#clock();
|
|
42
|
+
const value = RoundLog.sizeOf(this.#path);
|
|
43
|
+
if (value !== null)
|
|
44
|
+
this.#readableAt = now;
|
|
45
|
+
return { value, readableAt: this.#readableAt };
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* CpuAdvance — the process group's cumulative CPU through the ONE OS read face
|
|
50
|
+
* (`ProcessFacts.groupCpuMs`; `ps` stays inside `infra/proc.ts`). An unreadable `ps`
|
|
51
|
+
* (no such group, no `ps` at all) is a null reading: it contributes neither progress,
|
|
52
|
+
* nor unknown, nor a blocked stall.
|
|
53
|
+
*/
|
|
54
|
+
export class CpuAdvance {
|
|
55
|
+
#pgid;
|
|
56
|
+
#clock;
|
|
57
|
+
#readableAt = null;
|
|
58
|
+
constructor(pgid, clock = Date.now) {
|
|
59
|
+
this.#pgid = pgid;
|
|
60
|
+
this.#clock = clock;
|
|
61
|
+
}
|
|
62
|
+
sample() {
|
|
63
|
+
const now = this.#clock();
|
|
64
|
+
const value = ProcessFacts.groupCpuMs(this.#pgid);
|
|
65
|
+
if (value !== null)
|
|
66
|
+
this.#readableAt = now;
|
|
67
|
+
return { value, readableAt: this.#readableAt };
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
/** The per-round signal registry — the log leg and the additional CPU leg. Factories,
|
|
71
|
+
* not instances: one round's self-held state is built for that round alone. */
|
|
72
|
+
export const LIVENESS_SIGNALS = [
|
|
73
|
+
{ leg: "log", create: (context) => new LogGrowth(context.logPath) },
|
|
74
|
+
{ leg: "cpu", create: (context) => new CpuAdvance(context.pgid) },
|
|
75
|
+
];
|
|
76
|
+
/**
|
|
77
|
+
* LivenessJudge — the four-state truth table of design spec §4.2, pure logic:
|
|
78
|
+
* · any leg advanced over its previous reading → `progress`;
|
|
79
|
+
* · otherwise, at least one leg was readable inside `[now - windowMs, now]` →
|
|
80
|
+
* `idled` while the idle window is open, `stalled` (the group kill) once it is
|
|
81
|
+
* spent;
|
|
82
|
+
* · otherwise (no leg readable anywhere in the window) → `unknown`, which never
|
|
83
|
+
* kills (fail-open).
|
|
84
|
+
* An unreadable leg (`value === null`) is neutral: it neither advances, nor conjures
|
|
85
|
+
* `unknown`, nor blocks a stall. A leg that was readable earlier in the window and has
|
|
86
|
+
* since gone unreadable keeps that `readableAt`, so it still authorizes the stall.
|
|
87
|
+
*/
|
|
88
|
+
export class LivenessJudge {
|
|
89
|
+
verdict(input) {
|
|
90
|
+
const advanced = input.readings.some((reading, index) => {
|
|
91
|
+
const previous = input.previous[index] ?? null;
|
|
92
|
+
return reading.value !== null && previous !== null && reading.value > previous;
|
|
93
|
+
});
|
|
94
|
+
if (advanced)
|
|
95
|
+
return "progress";
|
|
96
|
+
const readableInWindow = input.readings.some((reading) => reading.readableAt !== null &&
|
|
97
|
+
reading.readableAt >= input.now - input.windowMs &&
|
|
98
|
+
reading.readableAt <= input.now);
|
|
99
|
+
if (!readableInWindow)
|
|
100
|
+
return "unknown";
|
|
101
|
+
return input.idleMs < input.windowMs ? "idled" : "stalled";
|
|
102
|
+
}
|
|
103
|
+
}
|