dsh-boost 0.1.1 → 0.1.2
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.en.md +97 -33
- package/README.md +85 -32
- package/dist/gate/decide.js +33 -2
- package/dist/gate/decide.js.map +1 -1
- package/dist/hooks/llm-stream.js +129 -54
- package/dist/hooks/llm-stream.js.map +1 -1
- package/dist/hooks/post-execute.js +104 -21
- package/dist/hooks/post-execute.js.map +1 -1
- package/dist/hooks/session-state.js +18 -8
- package/dist/hooks/session-state.js.map +1 -1
- package/dist/index.js +371 -67
- package/dist/index.js.map +1 -1
- package/dist/scope/doc.js.map +1 -1
- package/dist/scope/store.js +24 -9
- package/dist/scope/store.js.map +1 -1
- package/package.json +8 -4
- package/dist/admission/fixed-cost.d.ts +0 -23
- package/dist/admission/ledger.d.ts +0 -113
- package/dist/admission/retrieval.d.ts +0 -65
- package/dist/admission/usage.d.ts +0 -75
- package/dist/config.d.ts +0 -43
- package/dist/gate/binding.d.ts +0 -113
- package/dist/gate/decide.d.ts +0 -82
- package/dist/gate/guard.d.ts +0 -69
- package/dist/gate/invalidate.d.ts +0 -112
- package/dist/gate/plan.d.ts +0 -86
- package/dist/hooks/clock.d.ts +0 -68
- package/dist/hooks/execute.d.ts +0 -79
- package/dist/hooks/llm-stream.d.ts +0 -283
- package/dist/hooks/pending.d.ts +0 -89
- package/dist/hooks/post-execute.d.ts +0 -257
- package/dist/hooks/session-state.d.ts +0 -158
- package/dist/hooks/synthesize.d.ts +0 -74
- package/dist/host/loader.d.ts +0 -23
- package/dist/host/platform.d.ts +0 -18
- package/dist/host/root.d.ts +0 -25
- package/dist/projection/apply.d.ts +0 -174
- package/dist/projection/canonicalise.d.ts +0 -43
- package/dist/projection/counters.d.ts +0 -65
- package/dist/projection/truncate.d.ts +0 -47
- package/dist/prompt/protocol.d.ts +0 -45
- package/dist/receipts/store.d.ts +0 -198
- package/dist/scope/doc.d.ts +0 -117
- package/dist/scope/resolve.d.ts +0 -91
- package/dist/scope/store.d.ts +0 -135
- package/dist/selector/jev.d.ts +0 -93
- package/dist/tools/boost.d.ts +0 -380
- package/dist/tools/family.d.ts +0 -26
|
@@ -1,45 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* The plan-protocol system prompt section.
|
|
3
|
-
*
|
|
4
|
-
* This module owns the literal text that teaches the model to write a
|
|
5
|
-
* `<CHISEL_PLAN>` block: the block shape, the candidate-id rule, the `args`
|
|
6
|
-
* restrictions, the `$public` template, the guard vocabulary and the tools
|
|
7
|
-
* substitution covers. Nothing here parses or validates a plan —
|
|
8
|
-
* `src/gate/plan.ts`, `src/gate/binding.ts`, `src/gate/guard.ts` and
|
|
9
|
-
* `src/gate/decide.ts` are the authority, and the text agrees with them.
|
|
10
|
-
*
|
|
11
|
-
* The referent is the most load-bearing claim: `decide` evaluates every
|
|
12
|
-
* candidate's guards against `receipts.get(stepId)` — the receipt that just
|
|
13
|
-
* arrived — not against the candidate's own not-yet-existing result. With no
|
|
14
|
-
* such receipt nothing is viable, and several candidates whose guards pass on
|
|
15
|
-
* that one receipt are alternatives for the selector, not a queue. The text
|
|
16
|
-
* states this before the example because a guard aimed at the candidate's own
|
|
17
|
-
* output fails every time.
|
|
18
|
-
*
|
|
19
|
-
* `after:"root"` is taught because T23b keys the just-arrived receipt as
|
|
20
|
-
* `root`; an earlier executed candidate's receipt is keyed by its id. `$scalar`
|
|
21
|
-
* needs the whole receipt to be one token (a one-path glob); an identifier
|
|
22
|
-
* needs un-numbered output (a line-start `X: "value"`), which read/grep do not
|
|
23
|
-
* provide; a multi-line value must be typed literally. `$single` is accepted
|
|
24
|
-
* by binding but has no producer among the read/grep/glob receipts, so it is
|
|
25
|
-
* deliberately not taught.
|
|
26
|
-
*
|
|
27
|
-
* The section is registered with `interpolate: false`; the text is still kept
|
|
28
|
-
* free of `{{` so a later relaxation of that flag cannot rewrite it. The budget
|
|
29
|
-
* is 1500 characters; the test pins it because this text is a permanent cost.
|
|
30
|
-
*
|
|
31
|
-
* @module dsh-boost/prompt/protocol
|
|
32
|
-
*/
|
|
33
|
-
/** Section name the protocol is registered under (design §5.3). */
|
|
34
|
-
export declare const PROTOCOL_NAME = "dsh-boost";
|
|
35
|
-
/** Section order: alongside the other tool-contract sections. */
|
|
36
|
-
export declare const PROTOCOL_ORDER = 100;
|
|
37
|
-
/**
|
|
38
|
-
* The protocol section's body, injected verbatim.
|
|
39
|
-
*
|
|
40
|
-
* Order is what the model needs first: where the block goes and which one
|
|
41
|
-
* counts, what the guards read, the example and the sentence that repeats its
|
|
42
|
-
* operand, the literal `args` rules, the guard vocabulary, the substituted
|
|
43
|
-
* tools, and finally `$public` with its two binding sources and its limits.
|
|
44
|
-
*/
|
|
45
|
-
export declare const PROTOCOL_TEXT = "Plan one <CHISEL_PLAN> block in visible text, not reasoning;only the first counts. It describes your next call, so guards test the receipt that just arrived, not that call's own result. No receipt, no substitution. Several steps passing on one receipt are alternatives;one is chosen. Omit when unsure;any failure runs the call normally.\n<CHISEL_PLAN>\n{\"goal\":\"g\",\"steps\":[{\"id\":\"A\",\"tool\":\"read\",\"args\":{\"file_path\":\"/repo/b.ts\"},\"guards\":[{\"text_contains\":\"2 matches\"}]}]}\n</CHISEL_PLAN>\nThe guard reads the incoming receipt, which says \"2 matches\".\nid:one capital A-Z, unique,max 26 steps.\nargs:object,not $public itself,depth<=64,no prototype keys,no $-key except $public.\nguards:>=1 other than {\"ok\":true};each guard object has exactly one form key.\n{\"ok\":true}:no error. {\"text_contains\":\"s\"}:s expected present. {\"text_not_contains\":\"s\"}:s expected absent, such as an error footer. Both case-sensitive,s non-empty,never guessed. {\"json_equals\":{\"pointer\":\"/a/b\",\"value\":\"v\"}}:the whole receipt must be JSON.\nSubstituted:read, grep, glob;others run normally.\n$public copies a value instead of retyping it:{\"$public\":{\"after\":\"root\",\"field\":\"$scalar\"}}. after:\"root\"=the incoming receipt,or a step that already ran. field:\"$scalar\"=the whole receipt is one token (a one-path glob);or X=exactly one line-start X:\"value\" or X=\"value\" (double-quoted, non-empty), which needs un-numbered output,so not read or grep. A multi-line value cannot be projected;type it literally. Else that step is skipped.";
|
package/dist/receipts/store.d.ts
DELETED
|
@@ -1,198 +0,0 @@
|
|
|
1
|
-
/** Why a receipt exists. `substitute-settled` is its own line because the store is append-only. */
|
|
2
|
-
export type ReceiptKind = 'substitute' | 'substitute-settled' | 'shadow' | 'projection' | 'skip' | 'reset';
|
|
3
|
-
/** Fields every receipt carries, before the store fills the derived ones. */
|
|
4
|
-
type ReceiptCore = {
|
|
5
|
-
ts: string;
|
|
6
|
-
sessionId: string;
|
|
7
|
-
turn: number;
|
|
8
|
-
stepId?: string;
|
|
9
|
-
kind: ReceiptKind;
|
|
10
|
-
code: string;
|
|
11
|
-
tool?: string;
|
|
12
|
-
[k: string]: unknown;
|
|
13
|
-
};
|
|
14
|
-
/**
|
|
15
|
-
* One line of the audit log.
|
|
16
|
-
*
|
|
17
|
-
* Invariant (plan line 581): a receipt with `kind === 'projection'` always
|
|
18
|
-
* carries `unit: 'raw'` as a literal — T19/T26 filter on it, so a projection
|
|
19
|
-
* receipt without it would be invisible to the counters. The plan keeps
|
|
20
|
-
* `Receipt` an interface, which cannot pair `kind` with `unit`, so `buildReceipt`
|
|
21
|
-
* enforces the invariant by construction: it overwrites `unit` with `'raw'` on
|
|
22
|
-
* every projection receipt, ignoring any caller-supplied value, because the
|
|
23
|
-
* literal is the invariant rather than a parameter. A projection receipt is
|
|
24
|
-
* never rejected for shape; it must remain auditable.
|
|
25
|
-
*/
|
|
26
|
-
export interface Receipt extends ReceiptCore {
|
|
27
|
-
version: 1;
|
|
28
|
-
receipt_hash: string;
|
|
29
|
-
preview: string;
|
|
30
|
-
}
|
|
31
|
-
/** What callers hand to `append`; the store fills `version`, `receipt_hash` and `preview`. */
|
|
32
|
-
type ReceiptInput = ReceiptCore & {
|
|
33
|
-
version?: 1;
|
|
34
|
-
preview?: string;
|
|
35
|
-
};
|
|
36
|
-
/** Tuning knobs; the defaults are the design's (§5.3). */
|
|
37
|
-
interface ReceiptStoreOptions {
|
|
38
|
-
fsyncEveryLines?: number;
|
|
39
|
-
maxBytes?: number;
|
|
40
|
-
maxLines?: number;
|
|
41
|
-
}
|
|
42
|
-
/**
|
|
43
|
-
* `sha256(stable JSON)` of the fields that identify a call, first 16 hex chars.
|
|
44
|
-
*
|
|
45
|
-
* `args` is part of the payload on purpose: without it, two different calls of
|
|
46
|
-
* the same tool in one turn would collide. A missing `args` hashes like `{}`,
|
|
47
|
-
* and object keys are sorted recursively so insertion order cannot change the
|
|
48
|
-
* hash. An own `__proto__` key is an ordinary key, not the prototype setter.
|
|
49
|
-
*
|
|
50
|
-
* Args deeper than {@link MAX_RECEIPT_ARGS_DEPTH} are cut with a marker before
|
|
51
|
-
* hashing, exactly as they are before storing: otherwise the recursive walk or
|
|
52
|
-
* `JSON.stringify` would throw and the receipt (the audit evidence) would be
|
|
53
|
-
* lost. Two trees that differ only below the bound therefore hash alike; the
|
|
54
|
-
* plan parser refuses such trees, and a call whose args are deeper did not come
|
|
55
|
-
* from a plan.
|
|
56
|
-
*/
|
|
57
|
-
export declare function receiptHash(r: {
|
|
58
|
-
sessionId: string;
|
|
59
|
-
turn: number;
|
|
60
|
-
stepId?: string;
|
|
61
|
-
tool?: string;
|
|
62
|
-
args?: unknown;
|
|
63
|
-
}): string;
|
|
64
|
-
/**
|
|
65
|
-
* Append-only, crash-safe, bounded store of receipts per session.
|
|
66
|
-
*
|
|
67
|
-
* See the module docs for the write and read paths. Concurrent method calls on
|
|
68
|
-
* one instance are safe: writes are serialised through an internal promise
|
|
69
|
-
* chain. The store is single-writer per root by design — rotation counters are
|
|
70
|
-
* per instance, so two instances (or processes) writing one root can exceed the
|
|
71
|
-
* shard caps and lose receipts. The plugin owns exactly one store per root.
|
|
72
|
-
*/
|
|
73
|
-
export declare class ReceiptStore {
|
|
74
|
-
private readonly root;
|
|
75
|
-
private readonly fsyncEveryLines;
|
|
76
|
-
private readonly maxBytes;
|
|
77
|
-
private readonly maxLines;
|
|
78
|
-
/** *Consecutive* write failures; reset by any successful append. */
|
|
79
|
-
private failureCount;
|
|
80
|
-
/**
|
|
81
|
-
* Shard reads skipped by whole-store scans since the last scan that read
|
|
82
|
-
* every shard (EACCES, EISDIR, …). A fully readable scan resets it to zero,
|
|
83
|
-
* so a repaired shard drops `ERR_RECEIPTS_UNREADABLE` instead of pinning it
|
|
84
|
-
* for the life of the process. Named scans neither count here nor reset it:
|
|
85
|
-
* they do not cover the shard set status reports.
|
|
86
|
-
*/
|
|
87
|
-
private readFailureCount;
|
|
88
|
-
/** Whether the most recent whole-store scan hit {@link MAX_SCAN_SHARDS}. */
|
|
89
|
-
private scanCapHit;
|
|
90
|
-
private linesSinceSync;
|
|
91
|
-
private readonly pending;
|
|
92
|
-
private readonly states;
|
|
93
|
-
private readonly dirty;
|
|
94
|
-
private readonly disposed;
|
|
95
|
-
private readonly disposedOrder;
|
|
96
|
-
private dirReady;
|
|
97
|
-
/** Writes run one at a time so rotation and buffer replay cannot interleave. */
|
|
98
|
-
private chain;
|
|
99
|
-
constructor(root: string, opts?: ReceiptStoreOptions);
|
|
100
|
-
/**
|
|
101
|
-
* Append one receipt. Never rejects: a serialisation or write failure is
|
|
102
|
-
* counted and buffered. The session id is encoded only for the shard name;
|
|
103
|
-
* the stored receipt keeps the original id.
|
|
104
|
-
*/
|
|
105
|
-
append(receipt: ReceiptInput): Promise<void>;
|
|
106
|
-
/** Force the buffered lines and the current shards to disk (called at turn end). */
|
|
107
|
-
flush(): Promise<void>;
|
|
108
|
-
/** Number of receipts readable for `sessionId` (`.1` plus current). */
|
|
109
|
-
count(sessionId: string): Promise<number>;
|
|
110
|
-
/**
|
|
111
|
-
* Shard reads that the most recent whole-store scan skipped.
|
|
112
|
-
*
|
|
113
|
-
* A single unreadable shard (EACCES, a directory named `x.jsonl`, …) must
|
|
114
|
-
* not abort the whole scan: `boost status` would turn that into
|
|
115
|
-
* `ERR_BOOST_INTERNAL` for the entire ledger. Scans skip the shard and count
|
|
116
|
-
* it here so status can report a stable degraded code.
|
|
117
|
-
*
|
|
118
|
-
* The count describes the skipped reads **since the last whole-store scan
|
|
119
|
-
* that read every shard**, not the process lifetime: a fully readable scan
|
|
120
|
-
* resets it, so repairing the shard and re-running `status` drops the code,
|
|
121
|
-
* as the README instructs. A named `scan(sessionId)`/`count(sessionId)`
|
|
122
|
-
* neither contributes to nor clears it, because it does not cover the shard
|
|
123
|
-
* set the status total claims.
|
|
124
|
-
*/
|
|
125
|
-
readErrors(): number;
|
|
126
|
-
/**
|
|
127
|
-
* Whether the most recent whole-store scan stopped at {@link MAX_SCAN_SHARDS}.
|
|
128
|
-
*
|
|
129
|
-
* `status` reports a total over the shards it read, so a capped scan is a
|
|
130
|
-
* lower bound, not a total. The flag is per scan (false on the next full
|
|
131
|
-
* scan that fits), which lets the operator see the condition clear; the
|
|
132
|
-
* numeric totals stay unchanged and under-count, the safe direction.
|
|
133
|
-
*/
|
|
134
|
-
scanTruncated(): boolean;
|
|
135
|
-
/**
|
|
136
|
-
* Yield readable receipts, oldest first: `.1` before the current shard.
|
|
137
|
-
*
|
|
138
|
-
* The optional `sessionId` is encoded to its shard name; the receipts keep
|
|
139
|
-
* their original `sessionId`. With no argument, every shard under `receipts/`
|
|
140
|
-
* is visited (encoded shard names sorted for determinism, capped at
|
|
141
|
-
* {@link MAX_SCAN_SHARDS}), and each receipt supplies its own id from its
|
|
142
|
-
* body. Unparseable middle lines are skipped; an unfinished trailing line is
|
|
143
|
-
* ignored by the read and only the next write repairs it.
|
|
144
|
-
*
|
|
145
|
-
* A whole-store scan also maintains the two status readings: a shard it
|
|
146
|
-
* cannot read increments {@link readErrors} (a fully readable scan resets
|
|
147
|
-
* it), and more shards than the cap sets {@link scanTruncated}. Named scans
|
|
148
|
-
* touch neither, because they are not the population `status` totals.
|
|
149
|
-
*/
|
|
150
|
-
scan(sessionId?: string): AsyncIterable<Receipt>;
|
|
151
|
-
/**
|
|
152
|
-
* Forget one session's shard state and silence later receipts for it.
|
|
153
|
-
*
|
|
154
|
-
* Called from the plugin's `session/disposed` handler after `flush()`. It
|
|
155
|
-
* evicts the cached counters, forgets any buffered lines for that session
|
|
156
|
-
* **only when no write failure is outstanding**, and remembers the id
|
|
157
|
-
* (bounded FIFO) so a hook that lands after disposal records nothing instead
|
|
158
|
-
* of recreating state nothing will ever clear.
|
|
159
|
-
*
|
|
160
|
-
* The conditional drop is the "flush before eviction" promise: a successful
|
|
161
|
-
* flush has already drained `pending`, so the loop is a no-op; a failed one
|
|
162
|
-
* leaves the session's lines there, and they are the only copy of that
|
|
163
|
-
* evidence. They stay queued for the next flush — the buffer is bounded by
|
|
164
|
-
* {@link MAX_PENDING_LINES} and is emptied once {@link stopped} is reached,
|
|
165
|
-
* so retaining them cannot grow without limit.
|
|
166
|
-
*/
|
|
167
|
-
disposeSession(sessionId: string): void;
|
|
168
|
-
/** Consecutive write failures; a successful append resets it to zero. */
|
|
169
|
-
failures(): number;
|
|
170
|
-
/** Fail-closed gate: true after {@link STOPPED_AFTER_FAILURES} consecutive write failures. */
|
|
171
|
-
stopped(): boolean;
|
|
172
|
-
private appendNow;
|
|
173
|
-
/** The serialised body of {@link flush}; a failure is counted, never thrown. */
|
|
174
|
-
private flushNow;
|
|
175
|
-
/**
|
|
176
|
-
* Count one write failure and enforce the buffer bound.
|
|
177
|
-
*
|
|
178
|
-
* Once the store is `stopped()` (three consecutive failures) it is
|
|
179
|
-
* fail-closed: appends are still attempted so a recovered disk can reset the
|
|
180
|
-
* count, but the replay buffer is dropped instead of growing for as long as
|
|
181
|
-
* the outage lasts. Before that point `MAX_PENDING_LINES` is the hard cap.
|
|
182
|
-
*/
|
|
183
|
-
private recordFailure;
|
|
184
|
-
/** Replay buffered lines in order; the head stays queued until its write succeeds. */
|
|
185
|
-
private drainPending;
|
|
186
|
-
private writeLine;
|
|
187
|
-
private ensureDir;
|
|
188
|
-
/** Cached line/byte counters, loaded (and repaired) from disk on first use. */
|
|
189
|
-
private stateFor;
|
|
190
|
-
private rotateIfFull;
|
|
191
|
-
private syncIfDue;
|
|
192
|
-
private syncDirty;
|
|
193
|
-
private syncSession;
|
|
194
|
-
private shardPath;
|
|
195
|
-
/** Encoded shard base names present under `receipts/`, sorted. */
|
|
196
|
-
private listShardNames;
|
|
197
|
-
}
|
|
198
|
-
export {};
|
package/dist/scope/doc.d.ts
DELETED
|
@@ -1,117 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Scope document model: where the plugin is allowed to act.
|
|
3
|
-
*
|
|
4
|
-
* `scope.json` is the single source of truth for the exposure surface (design
|
|
5
|
-
* §5.5). This module only parses an already-read value; it never touches the
|
|
6
|
-
* filesystem. Task 9's store owns reading, locking and writing.
|
|
7
|
-
*
|
|
8
|
-
* The input is the JSON-decoded value `JSON.parse` produces for `scope.json`,
|
|
9
|
-
* not an arbitrary host object: exotic in-memory shapes (throwing getters,
|
|
10
|
-
* inherited fields) are outside the contract and are not defended against.
|
|
11
|
-
*
|
|
12
|
-
* Parsing is fail-closed in three ordered stages. **Type delimitation runs
|
|
13
|
-
* before the version checks**: a non-object, `null` or an array is a parse
|
|
14
|
-
* failure even when it carries a `version` property. Then a numeric `version`
|
|
15
|
-
* greater than `2` is a **future version**: it is a valid document written by a
|
|
16
|
-
* newer plugin, so reads degrade but writes must never rewrite it (the field
|
|
17
|
-
* set may be newer than this parser knows). Finally anything whose `version` is
|
|
18
|
-
* not exactly `2` — version 1, a missing or non-numeric version — is an
|
|
19
|
-
* **unknown version**; a version 1 document is the one upgradeable case, and
|
|
20
|
-
* the command decides when to upgrade it.
|
|
21
|
-
*
|
|
22
|
-
* A matching stage rejects immediately, and no failure returns a partial
|
|
23
|
-
* document: every failure comes back as a fresh deep copy of `DEFAULT_SCOPE`,
|
|
24
|
-
* the strictest exposure (`selected + []`), so a malformed or newer-versioned
|
|
25
|
-
* file degrades to "nobody sees it" rather than crashing the agent.
|
|
26
|
-
*
|
|
27
|
-
* Individual fields are guarded on the strict side too: an unknown `mode` is
|
|
28
|
-
* `'selected'`, a non-array `workspaceIds` is `[]`, non-string members are
|
|
29
|
-
* dropped, a non-boolean `shadow` is `true`, an unknown `projection` is
|
|
30
|
-
* `'shadow'`, and a non-finite `revision` is `0`. `updatedAt` is never
|
|
31
|
-
* validated beyond being a string.
|
|
32
|
-
*
|
|
33
|
-
* @module dsh-boost/scope/doc
|
|
34
|
-
*/
|
|
35
|
-
import type { ProjectionMode } from '../projection/apply.js';
|
|
36
|
-
/** Stable rejection code: the file names a version this parser does not know. */
|
|
37
|
-
export declare const ERR_SCOPE_UNKNOWN_VERSION = "ERR_SCOPE_UNKNOWN_VERSION";
|
|
38
|
-
/**
|
|
39
|
-
* Stable rejection code: the file's version is a number newer than this parser
|
|
40
|
-
* (version 3+). Reads degrade like any other failure, but the document is
|
|
41
|
-
* **read-only**: it may carry fields and workspace ids this parser would prune,
|
|
42
|
-
* so writing it back would silently lose the user's configuration.
|
|
43
|
-
*/
|
|
44
|
-
export declare const ERR_SCOPE_FUTURE_VERSION = "ERR_SCOPE_FUTURE_VERSION";
|
|
45
|
-
/** Stable rejection code: the file is not a scope document at all. */
|
|
46
|
-
export declare const ERR_SCOPE_PARSE_FAILED = "ERR_SCOPE_PARSE_FAILED";
|
|
47
|
-
/** Stable rejection code: the file exists but could not be read. */
|
|
48
|
-
export declare const ERR_SCOPE_READ_FAILED = "ERR_SCOPE_READ_FAILED";
|
|
49
|
-
/** Stable rejection code: the write's base revision is stale. */
|
|
50
|
-
export declare const ERR_SCOPE_REVISION_CONFLICT = "ERR_SCOPE_REVISION_CONFLICT";
|
|
51
|
-
/** Stable rejection code: another writer holds the scope lock. */
|
|
52
|
-
export declare const ERR_SCOPE_LOCKED = "ERR_SCOPE_LOCKED";
|
|
53
|
-
/**
|
|
54
|
-
* Stable rejection code: the write was cancelled through its `AbortSignal`.
|
|
55
|
-
*
|
|
56
|
-
* Checked at every await boundary of the write path. A cancellation is not a
|
|
57
|
-
* storage failure — the file is left exactly as it was — so the caller can
|
|
58
|
-
* report it without implying the scope is damaged.
|
|
59
|
-
*/
|
|
60
|
-
export declare const ERR_SCOPE_ABORTED = "ERR_SCOPE_ABORTED";
|
|
61
|
-
/** Every stable scope failure code (design §5.5 plus the future-version split). */
|
|
62
|
-
export type ScopeCode = typeof ERR_SCOPE_UNKNOWN_VERSION | typeof ERR_SCOPE_FUTURE_VERSION | typeof ERR_SCOPE_PARSE_FAILED | typeof ERR_SCOPE_READ_FAILED | typeof ERR_SCOPE_REVISION_CONFLICT | typeof ERR_SCOPE_LOCKED | typeof ERR_SCOPE_ABORTED;
|
|
63
|
-
/** A parsed `scope.json` document, version 2 (design §5.5). */
|
|
64
|
-
export interface ScopeDoc {
|
|
65
|
-
version: 2;
|
|
66
|
-
/** Incremented by the store on every successful write. */
|
|
67
|
-
revision: number;
|
|
68
|
-
/** Last write time, when the store recorded one; never validated further. */
|
|
69
|
-
updatedAt?: string;
|
|
70
|
-
mode: 'selected' | 'global';
|
|
71
|
-
workspaceIds: string[];
|
|
72
|
-
/** Shadow accounting switch (`boost shadow on|off`). */
|
|
73
|
-
shadow: boolean;
|
|
74
|
-
/** Projection shape: off, accounting only, or real replacement. */
|
|
75
|
-
projection: ProjectionMode;
|
|
76
|
-
}
|
|
77
|
-
/**
|
|
78
|
-
* The strictest exposure and the fallback for every failure: nobody sees the
|
|
79
|
-
* plugin until the user opts in.
|
|
80
|
-
*/
|
|
81
|
-
export declare const DEFAULT_SCOPE: ScopeDoc;
|
|
82
|
-
/**
|
|
83
|
-
* Read one `scope.json` value, as produced by `JSON.parse`.
|
|
84
|
-
*
|
|
85
|
-
* A value whose type or version is wrong is rejected with a stable code and a
|
|
86
|
-
* deep copy of `DEFAULT_SCOPE`; a version 2 object yields a complete document
|
|
87
|
-
* built from its fields, with every malformed field degraded to its strict
|
|
88
|
-
* value.
|
|
89
|
-
*/
|
|
90
|
-
export declare function parseScope(raw: unknown): {
|
|
91
|
-
doc: ScopeDoc;
|
|
92
|
-
code?: 'ERR_SCOPE_UNKNOWN_VERSION' | 'ERR_SCOPE_FUTURE_VERSION' | 'ERR_SCOPE_PARSE_FAILED';
|
|
93
|
-
};
|
|
94
|
-
/**
|
|
95
|
-
* The upgrade base for a version 1 document.
|
|
96
|
-
*
|
|
97
|
-
* Reading a v1 file still degrades to {@link DEFAULT_SCOPE} and reports
|
|
98
|
-
* {@link ERR_SCOPE_UNKNOWN_VERSION} (design §5.5 rule 3: unknown versions are
|
|
99
|
-
* read-only). Only the explicit `scope-set` upgrade may rewrite it, and this
|
|
100
|
-
* function answers "what did the user's v1 file actually say" for that one
|
|
101
|
-
* write: `version` becomes 2 and `revision` starts at the degraded read's 0,
|
|
102
|
-
* while every recognised field keeps its value (strict side for malformed
|
|
103
|
-
* ones). Never use this on the read path — a v1 document is not a valid v2
|
|
104
|
-
* document and must keep presenting as invisible until upgraded.
|
|
105
|
-
*
|
|
106
|
-
* `undefined` for anything that is not a plain object with `version === 1`,
|
|
107
|
-
* including v2, future versions, missing versions and non-objects.
|
|
108
|
-
*/
|
|
109
|
-
export declare function parseVersionOneScope(raw: unknown): ScopeDoc | undefined;
|
|
110
|
-
/**
|
|
111
|
-
* Whether the plugin may act for an agent in `workspaceId`.
|
|
112
|
-
*
|
|
113
|
-
* An agent with no workspace has the global view, and the plugin never injects
|
|
114
|
-
* into the global view (design §5.5), so `undefined` is always invisible.
|
|
115
|
-
* `mode: 'global'` widens to any *defined* workspace id, not to `undefined`.
|
|
116
|
-
*/
|
|
117
|
-
export declare function isVisible(doc: ScopeDoc, workspaceId: string | undefined): boolean;
|
package/dist/scope/resolve.d.ts
DELETED
|
@@ -1,91 +0,0 @@
|
|
|
1
|
-
import type { ScopeStore } from './store.js';
|
|
2
|
-
/**
|
|
3
|
-
* The host's workspace registry.
|
|
4
|
-
*
|
|
5
|
-
* The host exposes only the synchronous `list()` and the asynchronous
|
|
6
|
-
* `resolveByPath()`; there is no `byPath`. `workspaceIdOf` uses `list()`
|
|
7
|
-
* exclusively so it can stay synchronous. `resolveByPath` is optional here
|
|
8
|
-
* because a test double need not provide the pre-warm path.
|
|
9
|
-
*/
|
|
10
|
-
export interface WorkspaceRegistry {
|
|
11
|
-
list(): readonly {
|
|
12
|
-
id: string;
|
|
13
|
-
path: string;
|
|
14
|
-
}[];
|
|
15
|
-
resolveByPath?(path: string): Promise<{
|
|
16
|
-
id: string;
|
|
17
|
-
} | undefined>;
|
|
18
|
-
}
|
|
19
|
-
/**
|
|
20
|
-
* The agent shape this module reads.
|
|
21
|
-
*
|
|
22
|
-
* Looser than `AgentLike`: the brief's tests pass agents without an `id` (and
|
|
23
|
-
* `resolveVisible` passes `unknown`), so the header is optional here.
|
|
24
|
-
*/
|
|
25
|
-
type AgentWithCwd = {
|
|
26
|
-
session?: {
|
|
27
|
-
header?: {
|
|
28
|
-
cwd?: string;
|
|
29
|
-
};
|
|
30
|
-
};
|
|
31
|
-
};
|
|
32
|
-
/**
|
|
33
|
-
* Resolve the host workspace UUID for an agent's cwd.
|
|
34
|
-
*
|
|
35
|
-
* The cwd is matched against `registry.list()` by exact `path` equality, so
|
|
36
|
-
* `/w/a` does not match a workspace at `/w/ab` (or at `/w/a/`). This is the
|
|
37
|
-
* **synchronous fallback** for a registry without `resolveByPath`; the async
|
|
38
|
-
* {@link workspaceIdFor} is the production path because `Workspace.path` is a
|
|
39
|
-
* canonical realpath while `Session.header.cwd` is only guaranteed absolute.
|
|
40
|
-
* Any missing or malformed link in the chain — no agent, no session, a
|
|
41
|
-
* non-string cwd, no registry, a `list()` that is not an array, throws, or
|
|
42
|
-
* contains non-object entries — yields `undefined`, which `isVisible` treats as
|
|
43
|
-
* invisible. This function never throws, even when called outside
|
|
44
|
-
* `resolveVisible`.
|
|
45
|
-
*/
|
|
46
|
-
export declare function workspaceIdOf(agent: AgentWithCwd | undefined, registry: WorkspaceRegistry | undefined): string | undefined;
|
|
47
|
-
/**
|
|
48
|
-
* Resolve the workspace UUID, preferring the host's canonical lookup.
|
|
49
|
-
*
|
|
50
|
-
* `Workspace.path` is the canonical realpath (`dsh-workspace/src/types.ts`),
|
|
51
|
-
* while `Session.header.cwd` is only guaranteed absolute
|
|
52
|
-
* (`dsh-session/src/index.ts`), so a symlinked cwd or one with a trailing
|
|
53
|
-
* slash never matches byte-for-byte. `resolveByPath` is the registry's
|
|
54
|
-
* canonical resolver and is used whenever it exists; its `undefined` answer is
|
|
55
|
-
* authoritative (the workspace is not registered), while a registry without it
|
|
56
|
-
* falls back to the synchronous exact match. A throwing resolver is a
|
|
57
|
-
* resolution failure and fails closed (`undefined` -> invisible), never a
|
|
58
|
-
* crash and never a silent exact-match second guess.
|
|
59
|
-
*
|
|
60
|
-
* Never throws.
|
|
61
|
-
*/
|
|
62
|
-
export declare function workspaceIdFor(agent: AgentWithCwd | undefined, registry: WorkspaceRegistry | undefined): Promise<string | undefined>;
|
|
63
|
-
/**
|
|
64
|
-
* Visibility plus the workspace id the judgement was made against.
|
|
65
|
-
*
|
|
66
|
-
* `resolveVisible` is the boolean projection of this result. `apply` also needs
|
|
67
|
-
* the id: the stream hook's `resolveSession` map must carry the same canonical
|
|
68
|
-
* workspace id the judgement used, or a symlinked cwd would be judged visible
|
|
69
|
-
* and then refused by the substitution path.
|
|
70
|
-
*/
|
|
71
|
-
export declare function resolveWorkspace(store: ScopeStore, agent: unknown, registry: WorkspaceRegistry | undefined): Promise<{
|
|
72
|
-
visible: boolean;
|
|
73
|
-
workspaceId?: string;
|
|
74
|
-
}>;
|
|
75
|
-
/**
|
|
76
|
-
* Whether the plugin may act for `agent`, caching the judgement for the
|
|
77
|
-
* synchronous prompt provider.
|
|
78
|
-
*
|
|
79
|
-
* Never throws: a degraded read, a throwing registry, or a malformed `list()`
|
|
80
|
-
* all resolve to `false`. When the agent has a session id the result (including
|
|
81
|
-
* a failure's `false`) is written with `store.remember` before returning, so a
|
|
82
|
-
* subsequent synchronous `judgement(key)` sees the same answer.
|
|
83
|
-
*
|
|
84
|
-
* A degraded store read (missing, unreadable, corrupt or newer-versioned
|
|
85
|
-
* `scope.json`) is a *definitive* `false` for this resolution, not an unknown:
|
|
86
|
-
* it is cached like any other judgement. It is not sticky — the next
|
|
87
|
-
* `resolveVisible` call re-reads the store and overwrites the same key, so a
|
|
88
|
-
* repaired scope document self-heals the cache on the following resolution.
|
|
89
|
-
*/
|
|
90
|
-
export declare function resolveVisible(store: ScopeStore, agent: unknown, registry: WorkspaceRegistry | undefined): Promise<boolean>;
|
|
91
|
-
export {};
|
package/dist/scope/store.d.ts
DELETED
|
@@ -1,135 +0,0 @@
|
|
|
1
|
-
import type { ScopeCode, ScopeDoc } from './doc.js';
|
|
2
|
-
/** Stable code logged when a live-pid lock is reclaimed on age alone. */
|
|
3
|
-
export declare const ERR_SCOPE_LOCK_TAKEOVER = "ERR_SCOPE_LOCK_TAKEOVER";
|
|
4
|
-
/** Test seam and operator hook for the lock's time-based takeover. */
|
|
5
|
-
export interface ScopeStoreOptions {
|
|
6
|
-
/** Age after which a live-pid lock is ignored (defaults to ten dead-pid timeouts). */
|
|
7
|
-
lockTakeoverMs?: number;
|
|
8
|
-
/** Age after which a dead-pid lock is reclaimable (defaults to 60 s). */
|
|
9
|
-
lockStaleMs?: number;
|
|
10
|
-
/** Clock, injectable so tests do not sleep. */
|
|
11
|
-
now?: () => number;
|
|
12
|
-
/** Sink for the takeover warning; defaults to a process warning. */
|
|
13
|
-
warn?: (message: string) => void;
|
|
14
|
-
}
|
|
15
|
-
export declare class ScopeStore {
|
|
16
|
-
private readonly dir;
|
|
17
|
-
private readonly file;
|
|
18
|
-
private readonly lockFile;
|
|
19
|
-
private readonly lockStaleMs;
|
|
20
|
-
private readonly lockTakeoverMs;
|
|
21
|
-
private readonly now;
|
|
22
|
-
private readonly warn;
|
|
23
|
-
private cached?;
|
|
24
|
-
private lockOwner?;
|
|
25
|
-
private readonly judgements;
|
|
26
|
-
constructor(dir: string, options?: ScopeStoreOptions);
|
|
27
|
-
/**
|
|
28
|
-
* Read the current document. Never throws and never writes: every stat,
|
|
29
|
-
* read, JSON or shape failure comes back as a fresh `DEFAULT_SCOPE` plus
|
|
30
|
-
* `degraded: 'scope-degraded'` and the stable code.
|
|
31
|
-
*/
|
|
32
|
-
read(): Promise<{
|
|
33
|
-
doc: ScopeDoc;
|
|
34
|
-
degraded?: 'scope-degraded';
|
|
35
|
-
code?: ScopeCode;
|
|
36
|
-
}>;
|
|
37
|
-
/**
|
|
38
|
-
* Compare-and-swap write. Returns the new document (revision `baseRevision + 1`,
|
|
39
|
-
* `updatedAt` now) and leaves it cached.
|
|
40
|
-
*
|
|
41
|
-
* A missing file is a first write: the base is `DEFAULT_SCOPE` at revision 0,
|
|
42
|
-
* so it succeeds only when the caller passes 0. A corrupt or version 1 file
|
|
43
|
-
* is also based on the strict default, which is how `boost scope set`
|
|
44
|
-
* explicitly upgrades a version 1 document. A **future** version (a numeric
|
|
45
|
-
* version greater than 2) is refused with `ERR_SCOPE_FUTURE_VERSION` before
|
|
46
|
-
* the mutation: the newer field set cannot be represented here, so rewriting
|
|
47
|
-
* it would silently drop configuration. An existing file that cannot be read
|
|
48
|
-
* at all is `ERR_SCOPE_READ_FAILED` — never overwritten blindly.
|
|
49
|
-
*/
|
|
50
|
-
write(mutate: (doc: ScopeDoc) => ScopeDoc, baseRevision: number, options?: {
|
|
51
|
-
signal?: AbortSignal;
|
|
52
|
-
}): Promise<ScopeDoc>;
|
|
53
|
-
/** Cache one agent's visibility judgement; the only writer of this cache. */
|
|
54
|
-
remember(key: string, visible: boolean): void;
|
|
55
|
-
/**
|
|
56
|
-
* Drop one session's cached judgement on session disposal.
|
|
57
|
-
*
|
|
58
|
-
* The judgement map is per session and otherwise lives as long as the plugin;
|
|
59
|
-
* without this a process that served many sessions would retain one boolean
|
|
60
|
-
* (and its string key) per session forever.
|
|
61
|
-
*/
|
|
62
|
-
forget(key: string): void;
|
|
63
|
-
/** Synchronous per-agent lookup: a miss is `fallback`, and fail-closed is `false`. */
|
|
64
|
-
judgement(key: string, fallback?: boolean): boolean;
|
|
65
|
-
/** Async read path: stat + read + decode, all failures degraded. */
|
|
66
|
-
private readDisk;
|
|
67
|
-
/**
|
|
68
|
-
* Reuse the previous parse only when the exact bytes and mtime were already
|
|
69
|
-
* parsed. Byte identity is a stronger key than mtime+revision: an external
|
|
70
|
-
* edit that keeps both cannot be served from the old parse.
|
|
71
|
-
*/
|
|
72
|
-
private decodeFromCache;
|
|
73
|
-
/** Sync read path, used only inside the write lock (see the module comment). */
|
|
74
|
-
private readDiskSync;
|
|
75
|
-
/** The write path must be able to create `<root>/boost` on a fresh install. */
|
|
76
|
-
private ensureDirectory;
|
|
77
|
-
/**
|
|
78
|
-
* Take the write lock, reclaiming a stale lock at most once.
|
|
79
|
-
*
|
|
80
|
-
* Two independent staleness rules:
|
|
81
|
-
*
|
|
82
|
-
* 1. dead-owner reclaim — older than `lockStaleMs` **and** the recorded pid is
|
|
83
|
-
* dead (or unrecorded/unparseable/out of pid range);
|
|
84
|
-
* 2. bounded takeover — the lock's `startedAt` (falling back to mtime) is
|
|
85
|
-
* older than `lockTakeoverMs`, **even when its pid is alive**. A pid is
|
|
86
|
-
* reused after a crash, so rule 1 alone can leave `scope.lock` held for the
|
|
87
|
-
* whole process lifetime in a container. The hold window is one small
|
|
88
|
-
* synchronous write, so a lock this old is a crashed writer.
|
|
89
|
-
*
|
|
90
|
-
* The takeover re-reads the lock immediately before unlinking and refuses if
|
|
91
|
-
* its bytes or mtime changed, which narrows the cross-process race. Two
|
|
92
|
-
* writers can still judge the same lock stale; `releaseLock` only removes a
|
|
93
|
-
* lock whose content it wrote, and the CAS revision check still refuses to
|
|
94
|
-
* merge divergent writes, so the residual race cannot corrupt the document.
|
|
95
|
-
*
|
|
96
|
-
* When that first read finds **no** lock there is nothing to compare against,
|
|
97
|
-
* so the reclaim is refused with `ERR_SCOPE_LOCKED`. `createLock` already saw
|
|
98
|
-
* the file exist; a lock created between that failure and the read is
|
|
99
|
-
* indistinguishable from one a live writer still owns, and unlinking it
|
|
100
|
-
* would lose that writer's update. Refusing is safe (the caller retries) and
|
|
101
|
-
* the alternative is the one case the changed-lock guard cannot cover.
|
|
102
|
-
*/
|
|
103
|
-
private acquireLock;
|
|
104
|
-
/** `open(lock, 'wx')`; false means another writer holds it. */
|
|
105
|
-
private createLock;
|
|
106
|
-
/**
|
|
107
|
-
* One read of the lock: bytes, mtime and the owner fields they record.
|
|
108
|
-
*
|
|
109
|
-
* `undefined` means absent (the `EEXIST` raced a release): the caller may
|
|
110
|
-
* retry the create. An unreadable-but-present lock is returned with the mtime
|
|
111
|
-
* and no owner fields, so it becomes reclaimable only after the dead-pid
|
|
112
|
-
* timeout — never immediately, because an unreadable live lock must not be
|
|
113
|
-
* evicted on a guess.
|
|
114
|
-
*/
|
|
115
|
-
private readLock;
|
|
116
|
-
/** Age from `startedAt` when it is usable, otherwise from the file's mtime. */
|
|
117
|
-
private ageOf;
|
|
118
|
-
/** Whether the lock is reclaimable, and whether that decision needs a warning. */
|
|
119
|
-
private classifyLock;
|
|
120
|
-
/**
|
|
121
|
-
* Remove the lock only if it still contains exactly what this acquisition
|
|
122
|
-
* wrote. An unconditional unlink would delete a replacement lock another
|
|
123
|
-
* writer created after a stale-reclaim race. Every error is swallowed:
|
|
124
|
-
* cleanup must never mask the causal error (rule 8), and a lock left behind
|
|
125
|
-
* is reclaimable after 60 s while a masked conflict is not diagnosable.
|
|
126
|
-
*/
|
|
127
|
-
private releaseLock;
|
|
128
|
-
/**
|
|
129
|
-
* Serialize `doc` into a temporary file, fsync it, and rename it over
|
|
130
|
-
* `scope.json`. Returns the stored file's mtime and the exact text written
|
|
131
|
-
* (for the cache). A failed write removes the temporary file; the caller's
|
|
132
|
-
* `finally` removes the lock.
|
|
133
|
-
*/
|
|
134
|
-
private writeAtomic;
|
|
135
|
-
}
|