dsh-boost 0.0.0-stage → 0.1.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/LICENSE +202 -0
- package/NOTICE +29 -0
- package/README.en.md +526 -0
- package/README.md +444 -2
- package/cordis.patch.yml +40 -0
- package/dist/admission/fixed-cost.d.ts +23 -0
- package/dist/admission/fixed-cost.js +61 -0
- package/dist/admission/fixed-cost.js.map +1 -0
- package/dist/admission/ledger.d.ts +113 -0
- package/dist/admission/ledger.js +176 -0
- package/dist/admission/ledger.js.map +1 -0
- package/dist/admission/retrieval.d.ts +65 -0
- package/dist/admission/retrieval.js +162 -0
- package/dist/admission/retrieval.js.map +1 -0
- package/dist/admission/usage.d.ts +75 -0
- package/dist/admission/usage.js +124 -0
- package/dist/admission/usage.js.map +1 -0
- package/dist/config.d.ts +43 -0
- package/dist/config.js +103 -0
- package/dist/config.js.map +1 -0
- package/dist/gate/binding.d.ts +113 -0
- package/dist/gate/binding.js +297 -0
- package/dist/gate/binding.js.map +1 -0
- package/dist/gate/decide.d.ts +82 -0
- package/dist/gate/decide.js +163 -0
- package/dist/gate/decide.js.map +1 -0
- package/dist/gate/guard.d.ts +69 -0
- package/dist/gate/guard.js +195 -0
- package/dist/gate/guard.js.map +1 -0
- package/dist/gate/invalidate.d.ts +112 -0
- package/dist/gate/invalidate.js +111 -0
- package/dist/gate/invalidate.js.map +1 -0
- package/dist/gate/plan.d.ts +86 -0
- package/dist/gate/plan.js +222 -0
- package/dist/gate/plan.js.map +1 -0
- package/dist/hooks/clock.d.ts +68 -0
- package/dist/hooks/clock.js +82 -0
- package/dist/hooks/clock.js.map +1 -0
- package/dist/hooks/execute.d.ts +79 -0
- package/dist/hooks/execute.js +128 -0
- package/dist/hooks/execute.js.map +1 -0
- package/dist/hooks/llm-stream.d.ts +283 -0
- package/dist/hooks/llm-stream.js +1086 -0
- package/dist/hooks/llm-stream.js.map +1 -0
- package/dist/hooks/pending.d.ts +89 -0
- package/dist/hooks/pending.js +115 -0
- package/dist/hooks/pending.js.map +1 -0
- package/dist/hooks/post-execute.d.ts +257 -0
- package/dist/hooks/post-execute.js +1950 -0
- package/dist/hooks/post-execute.js.map +1 -0
- package/dist/hooks/session-state.d.ts +158 -0
- package/dist/hooks/session-state.js +168 -0
- package/dist/hooks/session-state.js.map +1 -0
- package/dist/hooks/synthesize.d.ts +74 -0
- package/dist/hooks/synthesize.js +100 -0
- package/dist/hooks/synthesize.js.map +1 -0
- package/dist/host/loader.d.ts +23 -0
- package/dist/host/loader.js +31 -0
- package/dist/host/loader.js.map +1 -0
- package/dist/host/platform.d.ts +18 -0
- package/dist/host/platform.js +19 -0
- package/dist/host/platform.js.map +1 -0
- package/dist/host/root.d.ts +25 -0
- package/dist/host/root.js +64 -0
- package/dist/host/root.js.map +1 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +984 -0
- package/dist/index.js.map +1 -0
- package/dist/projection/apply.d.ts +174 -0
- package/dist/projection/apply.js +137 -0
- package/dist/projection/apply.js.map +1 -0
- package/dist/projection/canonicalise.d.ts +43 -0
- package/dist/projection/canonicalise.js +43 -0
- package/dist/projection/canonicalise.js.map +1 -0
- package/dist/projection/counters.d.ts +65 -0
- package/dist/projection/counters.js +88 -0
- package/dist/projection/counters.js.map +1 -0
- package/dist/projection/truncate.d.ts +47 -0
- package/dist/projection/truncate.js +57 -0
- package/dist/projection/truncate.js.map +1 -0
- package/dist/prompt/protocol.d.ts +45 -0
- package/dist/prompt/protocol.js +56 -0
- package/dist/prompt/protocol.js.map +1 -0
- package/dist/receipts/store.d.ts +198 -0
- package/dist/receipts/store.js +734 -0
- package/dist/receipts/store.js.map +1 -0
- package/dist/scope/doc.d.ts +117 -0
- package/dist/scope/doc.js +158 -0
- package/dist/scope/doc.js.map +1 -0
- package/dist/scope/resolve.d.ts +91 -0
- package/dist/scope/resolve.js +146 -0
- package/dist/scope/resolve.js.map +1 -0
- package/dist/scope/store.d.ts +135 -0
- package/dist/scope/store.js +573 -0
- package/dist/scope/store.js.map +1 -0
- package/dist/selector/jev.d.ts +93 -0
- package/dist/selector/jev.js +171 -0
- package/dist/selector/jev.js.map +1 -0
- package/dist/tools/boost.d.ts +380 -0
- package/dist/tools/boost.js +801 -0
- package/dist/tools/boost.js.map +1 -0
- package/dist/tools/family.d.ts +26 -0
- package/dist/tools/family.js +26 -0
- package/dist/tools/family.js.map +1 -0
- package/dist/types.d.ts +130 -0
- package/dist/types.js +21 -0
- package/dist/types.js.map +1 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +75 -4
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Guard evaluation: the zero-token admission check on a receipt.
|
|
3
|
+
*
|
|
4
|
+
* A guard is a predicate over the canonical receipt a call produced. It is the
|
|
5
|
+
* only verification the fast path gets, so the rule is fail-closed: every
|
|
6
|
+
* ambiguity — a pointer that is not RFC 6901, a segment that cannot name an
|
|
7
|
+
* array element, a path that runs into a scalar, a value of the wrong type —
|
|
8
|
+
* is `fail`, never `pass`, and no path throws.
|
|
9
|
+
*
|
|
10
|
+
* `ok` reads `isError`, never the text, and only a literal `ok: true` passes.
|
|
11
|
+
* `text_contains` / `text_not_contains` are byte-faithful, case-sensitive
|
|
12
|
+
* `String#includes` checks on the canonical text: no trim, no normalisation,
|
|
13
|
+
* no regex.
|
|
14
|
+
*
|
|
15
|
+
* The evaluators do not rely on `parsePlan` having rejected bad guards: within
|
|
16
|
+
* the forms, `ok` must be literally `true`, an empty `text_contains` operand
|
|
17
|
+
* is a `fail` rather than vacuously true (`text_not_contains: ''` is already
|
|
18
|
+
* vacuously false), and a non-object guard is a `fail` instead of a throw.
|
|
19
|
+
*
|
|
20
|
+
* `json_equals` parses the whole text as JSON and walks the pointer by hand.
|
|
21
|
+
* A pointer is `''` (the whole document) or starts with `/`; anything else is
|
|
22
|
+
* malformed. Resolution follows only own properties (`Object.hasOwn`), so
|
|
23
|
+
* `/__proto__` and `/constructor` cannot read an inherited value. An array
|
|
24
|
+
* accepts only canonical decimal indices (`0`, `12` — not `01`, `1.0`, `-`,
|
|
25
|
+
* ` 1` or `+1`) that are inside its length, and a segment applied to a
|
|
26
|
+
* non-container fails. Escapes are RFC 6901: `~1` is `/` and `~0` is `~`
|
|
27
|
+
* (`~01` is therefore the literal `~1`), and any other `~` sequence is
|
|
28
|
+
* malformed even when the raw segment is a real key.
|
|
29
|
+
*
|
|
30
|
+
* Comparison is `===`, deliberately not `==`: `1` is not `'1'`, and `true` is
|
|
31
|
+
* not `1`. JSON cannot produce `NaN`, and `null`, arrays and objects can never
|
|
32
|
+
* equal a `string | number | boolean`, so a resolved value of one of those
|
|
33
|
+
* kinds fails. A JSON parse error is a `fail` value, not an exception.
|
|
34
|
+
*
|
|
35
|
+
* `GuardResult` includes `'unknown'` because the task interface names it, but
|
|
36
|
+
* no v1 guard form is undecidable: this module returns only `'pass'` or
|
|
37
|
+
* `'fail'`. There is no fifth form (`exit_code` / `stderr_empty` are forbidden
|
|
38
|
+
* by design §5.2), so a guard matching none of the four forms fails closed.
|
|
39
|
+
*
|
|
40
|
+
* Within the gate's contract, guards come from `parsePlan` (exactly one form
|
|
41
|
+
* key per guard) and receipts from `canonicalise`; the defensive checks above
|
|
42
|
+
* are this module's floor, not a full re-validation of either input. A receipt
|
|
43
|
+
* is never projected here — guards read the canonical original.
|
|
44
|
+
*
|
|
45
|
+
* @module dsh-boost/gate/guard
|
|
46
|
+
*/
|
|
47
|
+
import type { CanonicalReceipt } from '../projection/canonicalise.js';
|
|
48
|
+
import type { Guard } from './plan.js';
|
|
49
|
+
/**
|
|
50
|
+
* Outcome of one guard. `'unknown'` is part of the agreed interface but is
|
|
51
|
+
* never produced: every guard form v1 accepts is decidable.
|
|
52
|
+
*/
|
|
53
|
+
export type GuardResult = 'pass' | 'fail' | 'unknown';
|
|
54
|
+
/**
|
|
55
|
+
* Evaluate one guard. Dispatch is by presence of the form key, so a guard
|
|
56
|
+
* matching none of the four forms falls through to `fail` instead of passing.
|
|
57
|
+
* A non-object guard fails before dispatch: the `in` operator would throw, and
|
|
58
|
+
* throwing would abort the turn instead of falling back to the model.
|
|
59
|
+
*/
|
|
60
|
+
export declare function evaluateGuard(g: Guard, r: CanonicalReceipt): GuardResult;
|
|
61
|
+
/**
|
|
62
|
+
* Evaluate guards left to right and stop at the first failure. An empty list
|
|
63
|
+
* passes vacuously. `failed` is the exact guard object passed in, so a caller
|
|
64
|
+
* can identify which guard rejected the receipt.
|
|
65
|
+
*/
|
|
66
|
+
export declare function evaluateAll(guards: Guard[], r: CanonicalReceipt): {
|
|
67
|
+
ok: boolean;
|
|
68
|
+
failed?: Guard;
|
|
69
|
+
};
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Guard evaluation: the zero-token admission check on a receipt.
|
|
3
|
+
*
|
|
4
|
+
* A guard is a predicate over the canonical receipt a call produced. It is the
|
|
5
|
+
* only verification the fast path gets, so the rule is fail-closed: every
|
|
6
|
+
* ambiguity — a pointer that is not RFC 6901, a segment that cannot name an
|
|
7
|
+
* array element, a path that runs into a scalar, a value of the wrong type —
|
|
8
|
+
* is `fail`, never `pass`, and no path throws.
|
|
9
|
+
*
|
|
10
|
+
* `ok` reads `isError`, never the text, and only a literal `ok: true` passes.
|
|
11
|
+
* `text_contains` / `text_not_contains` are byte-faithful, case-sensitive
|
|
12
|
+
* `String#includes` checks on the canonical text: no trim, no normalisation,
|
|
13
|
+
* no regex.
|
|
14
|
+
*
|
|
15
|
+
* The evaluators do not rely on `parsePlan` having rejected bad guards: within
|
|
16
|
+
* the forms, `ok` must be literally `true`, an empty `text_contains` operand
|
|
17
|
+
* is a `fail` rather than vacuously true (`text_not_contains: ''` is already
|
|
18
|
+
* vacuously false), and a non-object guard is a `fail` instead of a throw.
|
|
19
|
+
*
|
|
20
|
+
* `json_equals` parses the whole text as JSON and walks the pointer by hand.
|
|
21
|
+
* A pointer is `''` (the whole document) or starts with `/`; anything else is
|
|
22
|
+
* malformed. Resolution follows only own properties (`Object.hasOwn`), so
|
|
23
|
+
* `/__proto__` and `/constructor` cannot read an inherited value. An array
|
|
24
|
+
* accepts only canonical decimal indices (`0`, `12` — not `01`, `1.0`, `-`,
|
|
25
|
+
* ` 1` or `+1`) that are inside its length, and a segment applied to a
|
|
26
|
+
* non-container fails. Escapes are RFC 6901: `~1` is `/` and `~0` is `~`
|
|
27
|
+
* (`~01` is therefore the literal `~1`), and any other `~` sequence is
|
|
28
|
+
* malformed even when the raw segment is a real key.
|
|
29
|
+
*
|
|
30
|
+
* Comparison is `===`, deliberately not `==`: `1` is not `'1'`, and `true` is
|
|
31
|
+
* not `1`. JSON cannot produce `NaN`, and `null`, arrays and objects can never
|
|
32
|
+
* equal a `string | number | boolean`, so a resolved value of one of those
|
|
33
|
+
* kinds fails. A JSON parse error is a `fail` value, not an exception.
|
|
34
|
+
*
|
|
35
|
+
* `GuardResult` includes `'unknown'` because the task interface names it, but
|
|
36
|
+
* no v1 guard form is undecidable: this module returns only `'pass'` or
|
|
37
|
+
* `'fail'`. There is no fifth form (`exit_code` / `stderr_empty` are forbidden
|
|
38
|
+
* by design §5.2), so a guard matching none of the four forms fails closed.
|
|
39
|
+
*
|
|
40
|
+
* Within the gate's contract, guards come from `parsePlan` (exactly one form
|
|
41
|
+
* key per guard) and receipts from `canonicalise`; the defensive checks above
|
|
42
|
+
* are this module's floor, not a full re-validation of either input. A receipt
|
|
43
|
+
* is never projected here — guards read the canonical original.
|
|
44
|
+
*
|
|
45
|
+
* @module dsh-boost/gate/guard
|
|
46
|
+
*/
|
|
47
|
+
/** The one place a predicate becomes a verdict. */
|
|
48
|
+
function verdict(holds) {
|
|
49
|
+
return holds ? 'pass' : 'fail';
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* `ok` asserts the receipt is not an error. The value must be the literal
|
|
53
|
+
* `true`: a hand-built `{ ok: false }` (or `1`, or `'no'`) asserting an error
|
|
54
|
+
* must not be read as "success is fine".
|
|
55
|
+
*/
|
|
56
|
+
function evaluateOk(g, r) {
|
|
57
|
+
return verdict(g.ok === true && !r.isError);
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Case-sensitive substring presence, on the canonical text exactly as
|
|
61
|
+
* received. An empty operand would be true for every text and could smuggle a
|
|
62
|
+
* constant through `guard-trivial`, so it fails closed here too.
|
|
63
|
+
*/
|
|
64
|
+
function evaluateContains(g, r) {
|
|
65
|
+
return verdict(g.text_contains.length > 0 && r.text.includes(g.text_contains));
|
|
66
|
+
}
|
|
67
|
+
/** Case-sensitive substring absence; used to exclude error footers and stacks. */
|
|
68
|
+
function evaluateNotContains(g, r) {
|
|
69
|
+
return verdict(!r.text.includes(g.text_not_contains));
|
|
70
|
+
}
|
|
71
|
+
/** A canonical array index: unsigned, no leading zero, no decimal, no padding. */
|
|
72
|
+
const ARRAY_INDEX = /^(?:0|[1-9][0-9]*)$/;
|
|
73
|
+
/**
|
|
74
|
+
* Decode one RFC 6901 reference token. `~0` is `~` and `~1` is `/`; scanning
|
|
75
|
+
* left to right makes `~01` the literal `~1` (the replacement order the RFC
|
|
76
|
+
* prescribes). A `~` followed by anything else, including the end of the
|
|
77
|
+
* segment, is malformed and yields `undefined`.
|
|
78
|
+
*/
|
|
79
|
+
function decodeSegment(segment) {
|
|
80
|
+
let decoded = '';
|
|
81
|
+
for (let i = 0; i < segment.length; i += 1) {
|
|
82
|
+
const char = segment[i];
|
|
83
|
+
if (char !== '~') {
|
|
84
|
+
decoded += char;
|
|
85
|
+
continue;
|
|
86
|
+
}
|
|
87
|
+
const escaped = segment[i + 1];
|
|
88
|
+
if (escaped === '0')
|
|
89
|
+
decoded += '~';
|
|
90
|
+
else if (escaped === '1')
|
|
91
|
+
decoded += '/';
|
|
92
|
+
else
|
|
93
|
+
return undefined;
|
|
94
|
+
i += 1;
|
|
95
|
+
}
|
|
96
|
+
return decoded;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Resolve one already-decoded segment. Objects accept any own key; arrays
|
|
100
|
+
* accept only a canonical decimal index inside their length. Both use
|
|
101
|
+
* `Object.hasOwn`, so an inherited property never resolves, and both refuse to
|
|
102
|
+
* descend into a primitive (`null`, string, number, boolean).
|
|
103
|
+
*/
|
|
104
|
+
function resolveSegment(target, segment) {
|
|
105
|
+
if (Array.isArray(target)) {
|
|
106
|
+
if (!ARRAY_INDEX.test(segment))
|
|
107
|
+
return { found: false };
|
|
108
|
+
const index = Number(segment);
|
|
109
|
+
if (index >= target.length)
|
|
110
|
+
return { found: false };
|
|
111
|
+
if (!Object.hasOwn(target, segment))
|
|
112
|
+
return { found: false };
|
|
113
|
+
return { found: true, value: target[index] };
|
|
114
|
+
}
|
|
115
|
+
if (typeof target !== 'object' || target === null)
|
|
116
|
+
return { found: false };
|
|
117
|
+
if (!Object.hasOwn(target, segment))
|
|
118
|
+
return { found: false };
|
|
119
|
+
return { found: true, value: target[segment] };
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Resolve an RFC 6901 pointer against an already-parsed JSON document.
|
|
123
|
+
*
|
|
124
|
+
* `''` is the whole document; any other pointer must start with `/`. The empty
|
|
125
|
+
* pointer is handled before splitting, so the whole-document case never enters
|
|
126
|
+
* the array-index rule (`''.split('/').slice(1)` would be `[]` anyway, but the
|
|
127
|
+
* early return states the intent). Missing keys, malformed escapes,
|
|
128
|
+
* non-canonical or out-of-range array indices, and hops through scalars all
|
|
129
|
+
* return `found: false` — this function never throws.
|
|
130
|
+
*/
|
|
131
|
+
function resolvePointer(document, pointer) {
|
|
132
|
+
if (pointer === '')
|
|
133
|
+
return { found: true, value: document };
|
|
134
|
+
if (!pointer.startsWith('/'))
|
|
135
|
+
return { found: false };
|
|
136
|
+
let current = document;
|
|
137
|
+
for (const raw of pointer.split('/').slice(1)) {
|
|
138
|
+
const segment = decodeSegment(raw);
|
|
139
|
+
if (segment === undefined)
|
|
140
|
+
return { found: false };
|
|
141
|
+
const next = resolveSegment(current, segment);
|
|
142
|
+
if (!next.found)
|
|
143
|
+
return { found: false };
|
|
144
|
+
current = next.value;
|
|
145
|
+
}
|
|
146
|
+
return { found: true, value: current };
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Parse the canonical text, resolve the pointer, and compare with `===`.
|
|
150
|
+
* A parse error, a malformed pointer, a missing path, or a non-scalar target is
|
|
151
|
+
* `fail`; there is no coercion between JSON types.
|
|
152
|
+
*/
|
|
153
|
+
function evaluateJsonEquals(g, r) {
|
|
154
|
+
let document;
|
|
155
|
+
try {
|
|
156
|
+
document = JSON.parse(r.text);
|
|
157
|
+
}
|
|
158
|
+
catch {
|
|
159
|
+
return 'fail';
|
|
160
|
+
}
|
|
161
|
+
const resolved = resolvePointer(document, g.json_equals.pointer);
|
|
162
|
+
return verdict(resolved.found && resolved.value === g.json_equals.value);
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* Evaluate one guard. Dispatch is by presence of the form key, so a guard
|
|
166
|
+
* matching none of the four forms falls through to `fail` instead of passing.
|
|
167
|
+
* A non-object guard fails before dispatch: the `in` operator would throw, and
|
|
168
|
+
* throwing would abort the turn instead of falling back to the model.
|
|
169
|
+
*/
|
|
170
|
+
export function evaluateGuard(g, r) {
|
|
171
|
+
if (typeof g !== 'object' || g === null)
|
|
172
|
+
return 'fail';
|
|
173
|
+
if ('ok' in g)
|
|
174
|
+
return evaluateOk(g, r);
|
|
175
|
+
if ('text_contains' in g)
|
|
176
|
+
return evaluateContains(g, r);
|
|
177
|
+
if ('text_not_contains' in g)
|
|
178
|
+
return evaluateNotContains(g, r);
|
|
179
|
+
if ('json_equals' in g)
|
|
180
|
+
return evaluateJsonEquals(g, r);
|
|
181
|
+
return 'fail';
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* Evaluate guards left to right and stop at the first failure. An empty list
|
|
185
|
+
* passes vacuously. `failed` is the exact guard object passed in, so a caller
|
|
186
|
+
* can identify which guard rejected the receipt.
|
|
187
|
+
*/
|
|
188
|
+
export function evaluateAll(guards, r) {
|
|
189
|
+
for (const guard of guards) {
|
|
190
|
+
if (evaluateGuard(guard, r) !== 'pass')
|
|
191
|
+
return { ok: false, failed: guard };
|
|
192
|
+
}
|
|
193
|
+
return { ok: true };
|
|
194
|
+
}
|
|
195
|
+
//# sourceMappingURL=guard.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../src/gate/guard.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Guard evaluation: the zero-token admission check on a receipt.\n *\n * A guard is a predicate over the canonical receipt a call produced. It is the\n * only verification the fast path gets, so the rule is fail-closed: every\n * ambiguity — a pointer that is not RFC 6901, a segment that cannot name an\n * array element, a path that runs into a scalar, a value of the wrong type —\n * is `fail`, never `pass`, and no path throws.\n *\n * `ok` reads `isError`, never the text, and only a literal `ok: true` passes.\n * `text_contains` / `text_not_contains` are byte-faithful, case-sensitive\n * `String#includes` checks on the canonical text: no trim, no normalisation,\n * no regex.\n *\n * The evaluators do not rely on `parsePlan` having rejected bad guards: within\n * the forms, `ok` must be literally `true`, an empty `text_contains` operand\n * is a `fail` rather than vacuously true (`text_not_contains: ''` is already\n * vacuously false), and a non-object guard is a `fail` instead of a throw.\n *\n * `json_equals` parses the whole text as JSON and walks the pointer by hand.\n * A pointer is `''` (the whole document) or starts with `/`; anything else is\n * malformed. Resolution follows only own properties (`Object.hasOwn`), so\n * `/__proto__` and `/constructor` cannot read an inherited value. An array\n * accepts only canonical decimal indices (`0`, `12` — not `01`, `1.0`, `-`,\n * ` 1` or `+1`) that are inside its length, and a segment applied to a\n * non-container fails. Escapes are RFC 6901: `~1` is `/` and `~0` is `~`\n * (`~01` is therefore the literal `~1`), and any other `~` sequence is\n * malformed even when the raw segment is a real key.\n *\n * Comparison is `===`, deliberately not `==`: `1` is not `'1'`, and `true` is\n * not `1`. JSON cannot produce `NaN`, and `null`, arrays and objects can never\n * equal a `string | number | boolean`, so a resolved value of one of those\n * kinds fails. A JSON parse error is a `fail` value, not an exception.\n *\n * `GuardResult` includes `'unknown'` because the task interface names it, but\n * no v1 guard form is undecidable: this module returns only `'pass'` or\n * `'fail'`. There is no fifth form (`exit_code` / `stderr_empty` are forbidden\n * by design §5.2), so a guard matching none of the four forms fails closed.\n *\n * Within the gate's contract, guards come from `parsePlan` (exactly one form\n * key per guard) and receipts from `canonicalise`; the defensive checks above\n * are this module's floor, not a full re-validation of either input. A receipt\n * is never projected here — guards read the canonical original.\n *\n * @module dsh-boost/gate/guard\n */\n\nimport type { CanonicalReceipt } from '../projection/canonicalise.js'\nimport type { Guard } from './plan.js'\n\n/**\n * Outcome of one guard. `'unknown'` is part of the agreed interface but is\n * never produced: every guard form v1 accepts is decidable.\n */\nexport type GuardResult = 'pass' | 'fail' | 'unknown'\n\n/** The one place a predicate becomes a verdict. */\nfunction verdict(holds: boolean): GuardResult {\n return holds ? 'pass' : 'fail'\n}\n\n/**\n * `ok` asserts the receipt is not an error. The value must be the literal\n * `true`: a hand-built `{ ok: false }` (or `1`, or `'no'`) asserting an error\n * must not be read as \"success is fine\".\n */\nfunction evaluateOk(g: { ok: true }, r: CanonicalReceipt): GuardResult {\n return verdict(g.ok === true && !r.isError)\n}\n\n/**\n * Case-sensitive substring presence, on the canonical text exactly as\n * received. An empty operand would be true for every text and could smuggle a\n * constant through `guard-trivial`, so it fails closed here too.\n */\nfunction evaluateContains(g: { text_contains: string }, r: CanonicalReceipt): GuardResult {\n return verdict(g.text_contains.length > 0 && r.text.includes(g.text_contains))\n}\n\n/** Case-sensitive substring absence; used to exclude error footers and stacks. */\nfunction evaluateNotContains(g: { text_not_contains: string }, r: CanonicalReceipt): GuardResult {\n return verdict(!r.text.includes(g.text_not_contains))\n}\n\n/** A canonical array index: unsigned, no leading zero, no decimal, no padding. */\nconst ARRAY_INDEX = /^(?:0|[1-9][0-9]*)$/\n\n/**\n * Decode one RFC 6901 reference token. `~0` is `~` and `~1` is `/`; scanning\n * left to right makes `~01` the literal `~1` (the replacement order the RFC\n * prescribes). A `~` followed by anything else, including the end of the\n * segment, is malformed and yields `undefined`.\n */\nfunction decodeSegment(segment: string): string | undefined {\n let decoded = ''\n for (let i = 0; i < segment.length; i += 1) {\n const char = segment[i]\n if (char !== '~') {\n decoded += char\n continue\n }\n const escaped = segment[i + 1]\n if (escaped === '0') decoded += '~'\n else if (escaped === '1') decoded += '/'\n else return undefined\n i += 1\n }\n return decoded\n}\n\n/** A pointer walk either yields a value or misses; JSON cannot produce `undefined`. */\ntype Resolved = { found: true; value: unknown } | { found: false }\n\n/**\n * Resolve one already-decoded segment. Objects accept any own key; arrays\n * accept only a canonical decimal index inside their length. Both use\n * `Object.hasOwn`, so an inherited property never resolves, and both refuse to\n * descend into a primitive (`null`, string, number, boolean).\n */\nfunction resolveSegment(target: unknown, segment: string): Resolved {\n if (Array.isArray(target)) {\n if (!ARRAY_INDEX.test(segment)) return { found: false }\n const index = Number(segment)\n if (index >= target.length) return { found: false }\n if (!Object.hasOwn(target, segment)) return { found: false }\n return { found: true, value: target[index] }\n }\n if (typeof target !== 'object' || target === null) return { found: false }\n if (!Object.hasOwn(target, segment)) return { found: false }\n return { found: true, value: (target as Record<string, unknown>)[segment] }\n}\n\n/**\n * Resolve an RFC 6901 pointer against an already-parsed JSON document.\n *\n * `''` is the whole document; any other pointer must start with `/`. The empty\n * pointer is handled before splitting, so the whole-document case never enters\n * the array-index rule (`''.split('/').slice(1)` would be `[]` anyway, but the\n * early return states the intent). Missing keys, malformed escapes,\n * non-canonical or out-of-range array indices, and hops through scalars all\n * return `found: false` — this function never throws.\n */\nfunction resolvePointer(document: unknown, pointer: string): Resolved {\n if (pointer === '') return { found: true, value: document }\n if (!pointer.startsWith('/')) return { found: false }\n let current = document\n for (const raw of pointer.split('/').slice(1)) {\n const segment = decodeSegment(raw)\n if (segment === undefined) return { found: false }\n const next = resolveSegment(current, segment)\n if (!next.found) return { found: false }\n current = next.value\n }\n return { found: true, value: current }\n}\n\n/**\n * Parse the canonical text, resolve the pointer, and compare with `===`.\n * A parse error, a malformed pointer, a missing path, or a non-scalar target is\n * `fail`; there is no coercion between JSON types.\n */\nfunction evaluateJsonEquals(\n g: { json_equals: { pointer: string; value: string | number | boolean } },\n r: CanonicalReceipt,\n): GuardResult {\n let document: unknown\n try {\n document = JSON.parse(r.text)\n } catch {\n return 'fail'\n }\n const resolved = resolvePointer(document, g.json_equals.pointer)\n return verdict(resolved.found && resolved.value === g.json_equals.value)\n}\n\n/**\n * Evaluate one guard. Dispatch is by presence of the form key, so a guard\n * matching none of the four forms falls through to `fail` instead of passing.\n * A non-object guard fails before dispatch: the `in` operator would throw, and\n * throwing would abort the turn instead of falling back to the model.\n */\nexport function evaluateGuard(g: Guard, r: CanonicalReceipt): GuardResult {\n if (typeof g !== 'object' || g === null) return 'fail'\n if ('ok' in g) return evaluateOk(g, r)\n if ('text_contains' in g) return evaluateContains(g, r)\n if ('text_not_contains' in g) return evaluateNotContains(g, r)\n if ('json_equals' in g) return evaluateJsonEquals(g, r)\n return 'fail'\n}\n\n/**\n * Evaluate guards left to right and stop at the first failure. An empty list\n * passes vacuously. `failed` is the exact guard object passed in, so a caller\n * can identify which guard rejected the receipt.\n */\nexport function evaluateAll(guards: Guard[], r: CanonicalReceipt): { ok: boolean; failed?: Guard } {\n for (const guard of guards) {\n if (evaluateGuard(guard, r) !== 'pass') return { ok: false, failed: guard }\n }\n return { ok: true }\n}\n"]}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* External invalidation sources and the double-projection guard.
|
|
3
|
+
*
|
|
4
|
+
* These are **pure predicates over a text the caller supplies**. They do not
|
|
5
|
+
* read the session, the history, or any host service, and they cannot by
|
|
6
|
+
* themselves observe that the host rewrote anything: only a caller that holds
|
|
7
|
+
* the anchored receipt's current text can.
|
|
8
|
+
*
|
|
9
|
+
* The host has two external rewrite sources (design §5.2-7):
|
|
10
|
+
*
|
|
11
|
+
* - the tool-result pruner replaces an oversized **session surface node's**
|
|
12
|
+
* middle in place with a fixed marker, at a step boundary before a model
|
|
13
|
+
* request;
|
|
14
|
+
* - compaction replaces older history with a summary, so a stored anchor no
|
|
15
|
+
* longer names any text the model can see.
|
|
16
|
+
*
|
|
17
|
+
* Either way the anchor is stale: projecting from it would emit a value out of
|
|
18
|
+
* text the model can no longer see, and a guard evaluated against the old text
|
|
19
|
+
* would claim a check the model never gets. Both must abandon the decision and
|
|
20
|
+
* fall back to the main model (design §5.2-3).
|
|
21
|
+
*
|
|
22
|
+
* **Where each source is observable.** The pruner never touches the object
|
|
23
|
+
* flowing through the `tools/post-execute` waterfall — it rewrites surface
|
|
24
|
+
* nodes before a model request (`dsh-compaction-basic`). A `post-execute`
|
|
25
|
+
* listener therefore cannot see the pruner's output, and `looksPruned` there
|
|
26
|
+
* only catches a receipt whose **tool output itself** happens to contain the
|
|
27
|
+
* 39-byte literal (for example, a `read` of a session log). That is a safe
|
|
28
|
+
* conservative outcome, not pruner detection. The caller that can observe a
|
|
29
|
+
* pruned or compacted receipt is the **model-request path** (`llm/stream`,
|
|
30
|
+
* `options.messages`); the stream hook owns that identity check with its own
|
|
31
|
+
* anchor probes plus `looksPruned` below. Nothing here claims the
|
|
32
|
+
* post-execute call site detects the host pruner or compaction.
|
|
33
|
+
*
|
|
34
|
+
* The second guard is independent and simpler: a receipt that already carries
|
|
35
|
+
* the host spill footer has been retained once already, so projecting it again
|
|
36
|
+
* would hide the original twice and point the model at a second-hand footer.
|
|
37
|
+
* The notice predicate is injected rather than imported — the host's spill
|
|
38
|
+
* policy is an optional peer and its recognition rule belongs to the caller.
|
|
39
|
+
*
|
|
40
|
+
* Everything here is pure: a string comparison, a predicate call, and a plain
|
|
41
|
+
* session-keyed map with no persistence, timers, or I/O. The hook that consumes
|
|
42
|
+
* these functions must never throw (the host turns a throwing listener into a
|
|
43
|
+
* tool error and loses the real output, `dsh-tools/lib/pipeline.js:538-550`),
|
|
44
|
+
* so the hook wraps the calls; these functions themselves are total — a
|
|
45
|
+
* malformed anchor record yields `undefined`, never a `TypeError`.
|
|
46
|
+
*
|
|
47
|
+
* @module dsh-boost/gate/invalidate
|
|
48
|
+
*/
|
|
49
|
+
/**
|
|
50
|
+
* The host pruner's exact replacement marker.
|
|
51
|
+
*
|
|
52
|
+
* Verified against the installed package rather than copied from the plan:
|
|
53
|
+
* `@deepseek-ai/dsh-compaction-tool-result-pruner@0.2.2-rc.4`, source
|
|
54
|
+
* `src/config.ts:7` (`export const PRUNE_MARKER = '\n\n[... tool result middle
|
|
55
|
+
* pruned ...]\n\n'`), compiled as `lib/index.js:8`. It matches the plan's
|
|
56
|
+
* literal exactly. Do not "clean up" the surrounding blank lines: they are part
|
|
57
|
+
* of the injected span and of this comparison.
|
|
58
|
+
*/
|
|
59
|
+
export declare const PRUNE_MARKER = "\n\n[... tool result middle pruned ...]\n\n";
|
|
60
|
+
/**
|
|
61
|
+
* What the decision path remembers about one substitution step.
|
|
62
|
+
*
|
|
63
|
+
* `anchors` maps a receipt id to the canonical original text as it arrived;
|
|
64
|
+
* `stepId` names the step the anchors belong to. This is an anchor record, not
|
|
65
|
+
* a dispatch queue: the pending-substitution queue stores its own entry, and
|
|
66
|
+
* the same post-execute decision writes both.
|
|
67
|
+
*/
|
|
68
|
+
export interface ReceiptAnchors {
|
|
69
|
+
stepId: string;
|
|
70
|
+
anchors: Record<string, string>;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Per-session receipt anchors.
|
|
74
|
+
*
|
|
75
|
+
* A plain `Map` behind three methods: no persistence, no timers, no I/O. It is
|
|
76
|
+
* written by the decision path and read by the invalidation check, both in
|
|
77
|
+
* `post-execute`; Task 23b fills it.
|
|
78
|
+
*/
|
|
79
|
+
export declare class AnchorStore {
|
|
80
|
+
private readonly bySession;
|
|
81
|
+
/** Remember `a` as the pending anchors for `sessionId`, replacing any earlier record. */
|
|
82
|
+
set(sessionId: string, a: ReceiptAnchors): void;
|
|
83
|
+
/** The pending anchors for `sessionId`, or `undefined` when there is none. */
|
|
84
|
+
get(sessionId: string): ReceiptAnchors | undefined;
|
|
85
|
+
/** Drop the pending anchors for `sessionId`; clearing an absent key is a no-op. */
|
|
86
|
+
clear(sessionId: string): void;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Whether this text contains the host pruner's marker.
|
|
90
|
+
*
|
|
91
|
+
* Exactly `text.includes(PRUNE_MARKER)` — no prefix matching, no regex, no
|
|
92
|
+
* trimming. This is the whole detection: a caller that can see a pruned
|
|
93
|
+
* surface node (the model-request path) uses it, while a caller that cannot
|
|
94
|
+
* (post-execute) only catches a tool output that literally contains the marker.
|
|
95
|
+
* If the host ever changes the wording this returns `false` and detection fails
|
|
96
|
+
* in the safe direction: at worst the plugin prunes one more time than needed,
|
|
97
|
+
* and a stale anchor is never let through, because an anchor/text mismatch
|
|
98
|
+
* still raises `compaction-reset` on the path that can establish the identity.
|
|
99
|
+
* A near miss in ordinary output is likewise not a prune, so text that merely
|
|
100
|
+
* looks like the marker is left alone.
|
|
101
|
+
*/
|
|
102
|
+
export declare function looksPruned(text: string): boolean;
|
|
103
|
+
/**
|
|
104
|
+
* Whether the receipt already carries the host spill footer.
|
|
105
|
+
*
|
|
106
|
+
* The answer is the injected predicate's: the caller owns the recognition rule
|
|
107
|
+
* (Task 23b/T25 supply the host's `hasSpillNotice` through a dynamic import),
|
|
108
|
+
* and this module must not import `@deepseek-ai/dsh-spill-policy` — it is an
|
|
109
|
+
* optional peer, and a static import would make the degraded path unreachable.
|
|
110
|
+
* Injecting it also keeps the guard testable without a host.
|
|
111
|
+
*/
|
|
112
|
+
export declare function alreadySpilled(text: string, hasNotice: (t: string) => boolean): boolean;
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* External invalidation sources and the double-projection guard.
|
|
3
|
+
*
|
|
4
|
+
* These are **pure predicates over a text the caller supplies**. They do not
|
|
5
|
+
* read the session, the history, or any host service, and they cannot by
|
|
6
|
+
* themselves observe that the host rewrote anything: only a caller that holds
|
|
7
|
+
* the anchored receipt's current text can.
|
|
8
|
+
*
|
|
9
|
+
* The host has two external rewrite sources (design §5.2-7):
|
|
10
|
+
*
|
|
11
|
+
* - the tool-result pruner replaces an oversized **session surface node's**
|
|
12
|
+
* middle in place with a fixed marker, at a step boundary before a model
|
|
13
|
+
* request;
|
|
14
|
+
* - compaction replaces older history with a summary, so a stored anchor no
|
|
15
|
+
* longer names any text the model can see.
|
|
16
|
+
*
|
|
17
|
+
* Either way the anchor is stale: projecting from it would emit a value out of
|
|
18
|
+
* text the model can no longer see, and a guard evaluated against the old text
|
|
19
|
+
* would claim a check the model never gets. Both must abandon the decision and
|
|
20
|
+
* fall back to the main model (design §5.2-3).
|
|
21
|
+
*
|
|
22
|
+
* **Where each source is observable.** The pruner never touches the object
|
|
23
|
+
* flowing through the `tools/post-execute` waterfall — it rewrites surface
|
|
24
|
+
* nodes before a model request (`dsh-compaction-basic`). A `post-execute`
|
|
25
|
+
* listener therefore cannot see the pruner's output, and `looksPruned` there
|
|
26
|
+
* only catches a receipt whose **tool output itself** happens to contain the
|
|
27
|
+
* 39-byte literal (for example, a `read` of a session log). That is a safe
|
|
28
|
+
* conservative outcome, not pruner detection. The caller that can observe a
|
|
29
|
+
* pruned or compacted receipt is the **model-request path** (`llm/stream`,
|
|
30
|
+
* `options.messages`); the stream hook owns that identity check with its own
|
|
31
|
+
* anchor probes plus `looksPruned` below. Nothing here claims the
|
|
32
|
+
* post-execute call site detects the host pruner or compaction.
|
|
33
|
+
*
|
|
34
|
+
* The second guard is independent and simpler: a receipt that already carries
|
|
35
|
+
* the host spill footer has been retained once already, so projecting it again
|
|
36
|
+
* would hide the original twice and point the model at a second-hand footer.
|
|
37
|
+
* The notice predicate is injected rather than imported — the host's spill
|
|
38
|
+
* policy is an optional peer and its recognition rule belongs to the caller.
|
|
39
|
+
*
|
|
40
|
+
* Everything here is pure: a string comparison, a predicate call, and a plain
|
|
41
|
+
* session-keyed map with no persistence, timers, or I/O. The hook that consumes
|
|
42
|
+
* these functions must never throw (the host turns a throwing listener into a
|
|
43
|
+
* tool error and loses the real output, `dsh-tools/lib/pipeline.js:538-550`),
|
|
44
|
+
* so the hook wraps the calls; these functions themselves are total — a
|
|
45
|
+
* malformed anchor record yields `undefined`, never a `TypeError`.
|
|
46
|
+
*
|
|
47
|
+
* @module dsh-boost/gate/invalidate
|
|
48
|
+
*/
|
|
49
|
+
/**
|
|
50
|
+
* The host pruner's exact replacement marker.
|
|
51
|
+
*
|
|
52
|
+
* Verified against the installed package rather than copied from the plan:
|
|
53
|
+
* `@deepseek-ai/dsh-compaction-tool-result-pruner@0.2.2-rc.4`, source
|
|
54
|
+
* `src/config.ts:7` (`export const PRUNE_MARKER = '\n\n[... tool result middle
|
|
55
|
+
* pruned ...]\n\n'`), compiled as `lib/index.js:8`. It matches the plan's
|
|
56
|
+
* literal exactly. Do not "clean up" the surrounding blank lines: they are part
|
|
57
|
+
* of the injected span and of this comparison.
|
|
58
|
+
*/
|
|
59
|
+
export const PRUNE_MARKER = '\n\n[... tool result middle pruned ...]\n\n';
|
|
60
|
+
/**
|
|
61
|
+
* Per-session receipt anchors.
|
|
62
|
+
*
|
|
63
|
+
* A plain `Map` behind three methods: no persistence, no timers, no I/O. It is
|
|
64
|
+
* written by the decision path and read by the invalidation check, both in
|
|
65
|
+
* `post-execute`; Task 23b fills it.
|
|
66
|
+
*/
|
|
67
|
+
export class AnchorStore {
|
|
68
|
+
bySession = new Map();
|
|
69
|
+
/** Remember `a` as the pending anchors for `sessionId`, replacing any earlier record. */
|
|
70
|
+
set(sessionId, a) {
|
|
71
|
+
this.bySession.set(sessionId, a);
|
|
72
|
+
}
|
|
73
|
+
/** The pending anchors for `sessionId`, or `undefined` when there is none. */
|
|
74
|
+
get(sessionId) {
|
|
75
|
+
return this.bySession.get(sessionId);
|
|
76
|
+
}
|
|
77
|
+
/** Drop the pending anchors for `sessionId`; clearing an absent key is a no-op. */
|
|
78
|
+
clear(sessionId) {
|
|
79
|
+
this.bySession.delete(sessionId);
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Whether this text contains the host pruner's marker.
|
|
84
|
+
*
|
|
85
|
+
* Exactly `text.includes(PRUNE_MARKER)` — no prefix matching, no regex, no
|
|
86
|
+
* trimming. This is the whole detection: a caller that can see a pruned
|
|
87
|
+
* surface node (the model-request path) uses it, while a caller that cannot
|
|
88
|
+
* (post-execute) only catches a tool output that literally contains the marker.
|
|
89
|
+
* If the host ever changes the wording this returns `false` and detection fails
|
|
90
|
+
* in the safe direction: at worst the plugin prunes one more time than needed,
|
|
91
|
+
* and a stale anchor is never let through, because an anchor/text mismatch
|
|
92
|
+
* still raises `compaction-reset` on the path that can establish the identity.
|
|
93
|
+
* A near miss in ordinary output is likewise not a prune, so text that merely
|
|
94
|
+
* looks like the marker is left alone.
|
|
95
|
+
*/
|
|
96
|
+
export function looksPruned(text) {
|
|
97
|
+
return text.includes(PRUNE_MARKER);
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Whether the receipt already carries the host spill footer.
|
|
101
|
+
*
|
|
102
|
+
* The answer is the injected predicate's: the caller owns the recognition rule
|
|
103
|
+
* (Task 23b/T25 supply the host's `hasSpillNotice` through a dynamic import),
|
|
104
|
+
* and this module must not import `@deepseek-ai/dsh-spill-policy` — it is an
|
|
105
|
+
* optional peer, and a static import would make the degraded path unreachable.
|
|
106
|
+
* Injecting it also keeps the guard testable without a host.
|
|
107
|
+
*/
|
|
108
|
+
export function alreadySpilled(text, hasNotice) {
|
|
109
|
+
return hasNotice(text);
|
|
110
|
+
}
|
|
111
|
+
//# sourceMappingURL=invalidate.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"invalidate.js","sourceRoot":"","sources":["../../src/gate/invalidate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,6CAA6C,CAAA;AAezE;;;;;;GAMG;AACH,MAAM,OAAO,WAAW;IACL,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAA;IAE9D,yFAAyF;IACzF,GAAG,CAAC,SAAiB,EAAE,CAAiB;QACtC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAA;IAClC,CAAC;IAED,8EAA8E;IAC9E,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;IACtC,CAAC;IAED,mFAAmF;IACnF,KAAK,CAAC,SAAiB;QACrB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IAClC,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAA;AACpC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,SAAiC;IAC5E,OAAO,SAAS,CAAC,IAAI,CAAC,CAAA;AACxB,CAAC","sourcesContent":["/**\n * External invalidation sources and the double-projection guard.\n *\n * These are **pure predicates over a text the caller supplies**. They do not\n * read the session, the history, or any host service, and they cannot by\n * themselves observe that the host rewrote anything: only a caller that holds\n * the anchored receipt's current text can.\n *\n * The host has two external rewrite sources (design §5.2-7):\n *\n * - the tool-result pruner replaces an oversized **session surface node's**\n * middle in place with a fixed marker, at a step boundary before a model\n * request;\n * - compaction replaces older history with a summary, so a stored anchor no\n * longer names any text the model can see.\n *\n * Either way the anchor is stale: projecting from it would emit a value out of\n * text the model can no longer see, and a guard evaluated against the old text\n * would claim a check the model never gets. Both must abandon the decision and\n * fall back to the main model (design §5.2-3).\n *\n * **Where each source is observable.** The pruner never touches the object\n * flowing through the `tools/post-execute` waterfall — it rewrites surface\n * nodes before a model request (`dsh-compaction-basic`). A `post-execute`\n * listener therefore cannot see the pruner's output, and `looksPruned` there\n * only catches a receipt whose **tool output itself** happens to contain the\n * 39-byte literal (for example, a `read` of a session log). That is a safe\n * conservative outcome, not pruner detection. The caller that can observe a\n * pruned or compacted receipt is the **model-request path** (`llm/stream`,\n * `options.messages`); the stream hook owns that identity check with its own\n * anchor probes plus `looksPruned` below. Nothing here claims the\n * post-execute call site detects the host pruner or compaction.\n *\n * The second guard is independent and simpler: a receipt that already carries\n * the host spill footer has been retained once already, so projecting it again\n * would hide the original twice and point the model at a second-hand footer.\n * The notice predicate is injected rather than imported — the host's spill\n * policy is an optional peer and its recognition rule belongs to the caller.\n *\n * Everything here is pure: a string comparison, a predicate call, and a plain\n * session-keyed map with no persistence, timers, or I/O. The hook that consumes\n * these functions must never throw (the host turns a throwing listener into a\n * tool error and loses the real output, `dsh-tools/lib/pipeline.js:538-550`),\n * so the hook wraps the calls; these functions themselves are total — a\n * malformed anchor record yields `undefined`, never a `TypeError`.\n *\n * @module dsh-boost/gate/invalidate\n */\n\n/**\n * The host pruner's exact replacement marker.\n *\n * Verified against the installed package rather than copied from the plan:\n * `@deepseek-ai/dsh-compaction-tool-result-pruner@0.2.2-rc.4`, source\n * `src/config.ts:7` (`export const PRUNE_MARKER = '\\n\\n[... tool result middle\n * pruned ...]\\n\\n'`), compiled as `lib/index.js:8`. It matches the plan's\n * literal exactly. Do not \"clean up\" the surrounding blank lines: they are part\n * of the injected span and of this comparison.\n */\nexport const PRUNE_MARKER = '\\n\\n[... tool result middle pruned ...]\\n\\n'\n\n/**\n * What the decision path remembers about one substitution step.\n *\n * `anchors` maps a receipt id to the canonical original text as it arrived;\n * `stepId` names the step the anchors belong to. This is an anchor record, not\n * a dispatch queue: the pending-substitution queue stores its own entry, and\n * the same post-execute decision writes both.\n */\nexport interface ReceiptAnchors {\n stepId: string\n anchors: Record<string, string>\n}\n\n/**\n * Per-session receipt anchors.\n *\n * A plain `Map` behind three methods: no persistence, no timers, no I/O. It is\n * written by the decision path and read by the invalidation check, both in\n * `post-execute`; Task 23b fills it.\n */\nexport class AnchorStore {\n private readonly bySession = new Map<string, ReceiptAnchors>()\n\n /** Remember `a` as the pending anchors for `sessionId`, replacing any earlier record. */\n set(sessionId: string, a: ReceiptAnchors): void {\n this.bySession.set(sessionId, a)\n }\n\n /** The pending anchors for `sessionId`, or `undefined` when there is none. */\n get(sessionId: string): ReceiptAnchors | undefined {\n return this.bySession.get(sessionId)\n }\n\n /** Drop the pending anchors for `sessionId`; clearing an absent key is a no-op. */\n clear(sessionId: string): void {\n this.bySession.delete(sessionId)\n }\n}\n\n/**\n * Whether this text contains the host pruner's marker.\n *\n * Exactly `text.includes(PRUNE_MARKER)` — no prefix matching, no regex, no\n * trimming. This is the whole detection: a caller that can see a pruned\n * surface node (the model-request path) uses it, while a caller that cannot\n * (post-execute) only catches a tool output that literally contains the marker.\n * If the host ever changes the wording this returns `false` and detection fails\n * in the safe direction: at worst the plugin prunes one more time than needed,\n * and a stale anchor is never let through, because an anchor/text mismatch\n * still raises `compaction-reset` on the path that can establish the identity.\n * A near miss in ordinary output is likewise not a prune, so text that merely\n * looks like the marker is left alone.\n */\nexport function looksPruned(text: string): boolean {\n return text.includes(PRUNE_MARKER)\n}\n\n/**\n * Whether the receipt already carries the host spill footer.\n *\n * The answer is the injected predicate's: the caller owns the recognition rule\n * (Task 23b/T25 supply the host's `hasSpillNotice` through a dynamic import),\n * and this module must not import `@deepseek-ai/dsh-spill-policy` — it is an\n * optional peer, and a static import would make the degraded path unreachable.\n * Injecting it also keeps the guard testable without a host.\n */\nexport function alreadySpilled(text: string, hasNotice: (t: string) => boolean): boolean {\n return hasNotice(text)\n}\n\n"]}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Plan parsing: model-written text becomes typed candidates.
|
|
3
|
+
*
|
|
4
|
+
* The model may write one `<CHISEL_PLAN>` block listing candidate tool calls.
|
|
5
|
+
* This module is the only place that text becomes data; guard evaluation,
|
|
6
|
+
* binding and the selector all trust what it returns, so parsing is strict:
|
|
7
|
+
* a document either yields a fully validated plan or exactly one error code
|
|
8
|
+
* (`no-plan`, `bad-json`, `bad-shape`). Nothing is ever thrown and no partial
|
|
9
|
+
* plan escapes.
|
|
10
|
+
*
|
|
11
|
+
* Only the first block counts. The block is located with two linear `indexOf`
|
|
12
|
+
* scans (opening tag, then the next closing tag); a pathological document with
|
|
13
|
+
* many unterminated openers must not stall the event loop. A second block is
|
|
14
|
+
* ignored even when the first is malformed, and an opening tag without its
|
|
15
|
+
* closing tag is not a block at all (`no-plan`).
|
|
16
|
+
*
|
|
17
|
+
* "Only literals" is enforced against what JSON can carry: `JSON.parse` cannot
|
|
18
|
+
* produce a function, so the rule reduces to "`args` may contain no
|
|
19
|
+
* `$`-prefixed key other than `$public`". That restriction covers the whole
|
|
20
|
+
* `args` tree, including inside a `$public` subtree; the sanctioned template
|
|
21
|
+
* (`{ after, field }`, with `$scalar`/`$single` as *values*) has no nested
|
|
22
|
+
* `$`-prefixed key, so the two rules never conflict. The `$public` subtree is
|
|
23
|
+
* otherwise preserved verbatim: its `after`/`field` semantics are validated by
|
|
24
|
+
* binding (task 12), not here. A root-level `$public` (the whole `args` object
|
|
25
|
+
* replaced by a scalar) is also left to binding to reject.
|
|
26
|
+
*
|
|
27
|
+
* Candidate ids are single capital ASCII letters (`A`–`Z`) because the
|
|
28
|
+
* selector answers with exactly one character equal to a candidate id; that
|
|
29
|
+
* also means a plan with more than 26 candidates is rejected. `tool` must be
|
|
30
|
+
* non-empty after trimming. `args` is capped at 64 levels of nesting and may
|
|
31
|
+
* not use the prototype-affecting keys `__proto__`, `constructor` or
|
|
32
|
+
* `prototype`: those collide in receipt hashing today and would pollute any
|
|
33
|
+
* future merge of `args`.
|
|
34
|
+
*
|
|
35
|
+
* @module dsh-boost/gate/plan
|
|
36
|
+
*/
|
|
37
|
+
/** A deterministic receipt predicate. `ok` alone is trivial (design §5.2). */
|
|
38
|
+
export type Guard = {
|
|
39
|
+
ok: true;
|
|
40
|
+
} | {
|
|
41
|
+
text_contains: string;
|
|
42
|
+
} | {
|
|
43
|
+
text_not_contains: string;
|
|
44
|
+
} | {
|
|
45
|
+
json_equals: {
|
|
46
|
+
pointer: string;
|
|
47
|
+
value: string | number | boolean;
|
|
48
|
+
};
|
|
49
|
+
};
|
|
50
|
+
/** One tool call the model proposed. */
|
|
51
|
+
export interface Candidate {
|
|
52
|
+
id: string;
|
|
53
|
+
tool: string;
|
|
54
|
+
args: Record<string, unknown>;
|
|
55
|
+
guards: Guard[];
|
|
56
|
+
}
|
|
57
|
+
/** A parsed plan: documentation plus the candidate steps. */
|
|
58
|
+
export interface Plan {
|
|
59
|
+
goal: string;
|
|
60
|
+
steps: Candidate[];
|
|
61
|
+
}
|
|
62
|
+
/** Why a document did not yield a plan. */
|
|
63
|
+
type PlanError = 'no-plan' | 'bad-json' | 'bad-shape';
|
|
64
|
+
/**
|
|
65
|
+
* Parse the first `<CHISEL_PLAN>` block out of one model response.
|
|
66
|
+
*
|
|
67
|
+
* Returns `{ plan }` only when the whole block is understood: a non-empty
|
|
68
|
+
* `steps` array whose ids are unique capital letters, each with a non-empty
|
|
69
|
+
* tool, a literal `args` object and decodable guards. Everything else collapses
|
|
70
|
+
* to one error code, so callers can never act on half a plan. `goal` is
|
|
71
|
+
* documentation: a missing or non-string value becomes `''`, never an error.
|
|
72
|
+
*/
|
|
73
|
+
export declare function parsePlan(text: string): {
|
|
74
|
+
plan: Plan;
|
|
75
|
+
} | {
|
|
76
|
+
error: PlanError;
|
|
77
|
+
};
|
|
78
|
+
/**
|
|
79
|
+
* Whether a candidate has nothing to check.
|
|
80
|
+
*
|
|
81
|
+
* True when every guard is `{ ok: true }`, including the empty array: nothing
|
|
82
|
+
* to check means nothing to check. Any non-`ok` guard makes the candidate
|
|
83
|
+
* non-trivial, which is what substitution requires (design §5.2, `guard-trivial`).
|
|
84
|
+
*/
|
|
85
|
+
export declare function isTrivial(c: Candidate): boolean;
|
|
86
|
+
export {};
|