dsh-boost 0.0.0-stage → 0.1.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/LICENSE +202 -0
- package/NOTICE +29 -0
- package/README.en.md +476 -0
- package/README.md +408 -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 +276 -0
- package/dist/hooks/llm-stream.js +1008 -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 +247 -0
- package/dist/hooks/post-execute.js +1776 -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 +18 -0
- package/dist/host/root.js +43 -0
- package/dist/host/root.js.map +1 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +866 -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 +367 -0
- package/dist/tools/boost.js +768 -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 +113 -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,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Workspace resolution: map a session cwd to a host workspace UUID and answer
|
|
3
|
+
* "may the plugin act for this agent?" from the scope document.
|
|
4
|
+
*
|
|
5
|
+
* `scope.json` lists workspace **ids**, while a session header carries a
|
|
6
|
+
* **cwd path**, so visibility is a registry lookup, never a path comparison.
|
|
7
|
+
* The production resolver (`resolveWorkspace` / `workspaceIdFor`) is
|
|
8
|
+
* asynchronous and prefers the registry's canonical `resolveByPath`, because
|
|
9
|
+
* `Workspace.path` is a realpath while `Session.header.cwd` is only absolute.
|
|
10
|
+
* `workspaceIdOf` remains the synchronous exact-match fallback for a registry
|
|
11
|
+
* that offers only `list()`, and the section provider stays synchronous by
|
|
12
|
+
* reading the cached judgement.
|
|
13
|
+
*
|
|
14
|
+
* Everything is fail-closed. No agent, no session, no cwd, no registry, no
|
|
15
|
+
* matching entry, a throwing `list()`, or a malformed list all mean "no
|
|
16
|
+
* workspace id", and `isVisible` treats that as invisible. `workspaceIdOf` is
|
|
17
|
+
* total on purpose: it is the synchronous accessor a later pre-warm path will
|
|
18
|
+
* call directly, so a broken registry degrades to `undefined` here instead of
|
|
19
|
+
* relying on `resolveVisible`'s catch.
|
|
20
|
+
*
|
|
21
|
+
* ## Why `resolveVisible` writes the cache
|
|
22
|
+
*
|
|
23
|
+
* `resolveVisible` is the asynchronous `when` path. Besides returning the
|
|
24
|
+
* judgement it stores it with `store.remember(key, visible)`, keyed by
|
|
25
|
+
* `agent.session.header.id`. The `systemPrompt` section provider is
|
|
26
|
+
* synchronous and can only read `store.judgement(key)`; without this write the
|
|
27
|
+
* protocol section would never appear, with no error anywhere. An agent with
|
|
28
|
+
* no session id has no key to store under, so its judgement is returned but
|
|
29
|
+
* nothing is cached. A resolution failure is remembered as `false`, which is
|
|
30
|
+
* the same fail-closed answer the provider's fallback would give.
|
|
31
|
+
*
|
|
32
|
+
* @module dsh-boost/scope/resolve
|
|
33
|
+
*/
|
|
34
|
+
import { isVisible } from './doc.js';
|
|
35
|
+
/** The session id, when the agent has one; that is the judgement-cache key. */
|
|
36
|
+
function agentKeyOf(agent) {
|
|
37
|
+
const id = agent?.session?.header?.id;
|
|
38
|
+
return typeof id === 'string' ? id : undefined;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Resolve the host workspace UUID for an agent's cwd.
|
|
42
|
+
*
|
|
43
|
+
* The cwd is matched against `registry.list()` by exact `path` equality, so
|
|
44
|
+
* `/w/a` does not match a workspace at `/w/ab` (or at `/w/a/`). This is the
|
|
45
|
+
* **synchronous fallback** for a registry without `resolveByPath`; the async
|
|
46
|
+
* {@link workspaceIdFor} is the production path because `Workspace.path` is a
|
|
47
|
+
* canonical realpath while `Session.header.cwd` is only guaranteed absolute.
|
|
48
|
+
* Any missing or malformed link in the chain — no agent, no session, a
|
|
49
|
+
* non-string cwd, no registry, a `list()` that is not an array, throws, or
|
|
50
|
+
* contains non-object entries — yields `undefined`, which `isVisible` treats as
|
|
51
|
+
* invisible. This function never throws, even when called outside
|
|
52
|
+
* `resolveVisible`.
|
|
53
|
+
*/
|
|
54
|
+
export function workspaceIdOf(agent, registry) {
|
|
55
|
+
const cwd = agent?.session?.header?.cwd;
|
|
56
|
+
if (typeof cwd !== 'string')
|
|
57
|
+
return undefined;
|
|
58
|
+
try {
|
|
59
|
+
const workspaces = registry?.list();
|
|
60
|
+
if (!Array.isArray(workspaces))
|
|
61
|
+
return undefined;
|
|
62
|
+
return workspaces.find(workspace => workspace?.path === cwd)?.id;
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
return undefined;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Resolve the workspace UUID, preferring the host's canonical lookup.
|
|
70
|
+
*
|
|
71
|
+
* `Workspace.path` is the canonical realpath (`dsh-workspace/src/types.ts`),
|
|
72
|
+
* while `Session.header.cwd` is only guaranteed absolute
|
|
73
|
+
* (`dsh-session/src/index.ts`), so a symlinked cwd or one with a trailing
|
|
74
|
+
* slash never matches byte-for-byte. `resolveByPath` is the registry's
|
|
75
|
+
* canonical resolver and is used whenever it exists; its `undefined` answer is
|
|
76
|
+
* authoritative (the workspace is not registered), while a registry without it
|
|
77
|
+
* falls back to the synchronous exact match. A throwing resolver is a
|
|
78
|
+
* resolution failure and fails closed (`undefined` -> invisible), never a
|
|
79
|
+
* crash and never a silent exact-match second guess.
|
|
80
|
+
*
|
|
81
|
+
* Never throws.
|
|
82
|
+
*/
|
|
83
|
+
export async function workspaceIdFor(agent, registry) {
|
|
84
|
+
const cwd = agent?.session?.header?.cwd;
|
|
85
|
+
if (typeof cwd !== 'string')
|
|
86
|
+
return undefined;
|
|
87
|
+
const resolveByPath = registry?.resolveByPath;
|
|
88
|
+
if (typeof resolveByPath === 'function') {
|
|
89
|
+
try {
|
|
90
|
+
const workspace = await resolveByPath.call(registry, cwd);
|
|
91
|
+
return typeof workspace?.id === 'string' ? workspace.id : undefined;
|
|
92
|
+
}
|
|
93
|
+
catch {
|
|
94
|
+
return undefined;
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
return workspaceIdOf(agent, registry);
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Visibility plus the workspace id the judgement was made against.
|
|
101
|
+
*
|
|
102
|
+
* `resolveVisible` is the boolean projection of this result. `apply` also needs
|
|
103
|
+
* the id: the stream hook's `resolveSession` map must carry the same canonical
|
|
104
|
+
* workspace id the judgement used, or a symlinked cwd would be judged visible
|
|
105
|
+
* and then refused by the substitution path.
|
|
106
|
+
*/
|
|
107
|
+
export async function resolveWorkspace(store, agent, registry) {
|
|
108
|
+
try {
|
|
109
|
+
const key = agentKeyOf(agent);
|
|
110
|
+
let workspaceId;
|
|
111
|
+
let visible = false;
|
|
112
|
+
try {
|
|
113
|
+
workspaceId = await workspaceIdFor(agent, registry);
|
|
114
|
+
const { doc } = await store.read();
|
|
115
|
+
visible = isVisible(doc, workspaceId);
|
|
116
|
+
}
|
|
117
|
+
catch {
|
|
118
|
+
visible = false;
|
|
119
|
+
}
|
|
120
|
+
if (key !== undefined)
|
|
121
|
+
store.remember(key, visible);
|
|
122
|
+
return { visible, ...(workspaceId === undefined ? {} : { workspaceId }) };
|
|
123
|
+
}
|
|
124
|
+
catch {
|
|
125
|
+
return { visible: false };
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Whether the plugin may act for `agent`, caching the judgement for the
|
|
130
|
+
* synchronous prompt provider.
|
|
131
|
+
*
|
|
132
|
+
* Never throws: a degraded read, a throwing registry, or a malformed `list()`
|
|
133
|
+
* all resolve to `false`. When the agent has a session id the result (including
|
|
134
|
+
* a failure's `false`) is written with `store.remember` before returning, so a
|
|
135
|
+
* subsequent synchronous `judgement(key)` sees the same answer.
|
|
136
|
+
*
|
|
137
|
+
* A degraded store read (missing, unreadable, corrupt or newer-versioned
|
|
138
|
+
* `scope.json`) is a *definitive* `false` for this resolution, not an unknown:
|
|
139
|
+
* it is cached like any other judgement. It is not sticky — the next
|
|
140
|
+
* `resolveVisible` call re-reads the store and overwrites the same key, so a
|
|
141
|
+
* repaired scope document self-heals the cache on the following resolution.
|
|
142
|
+
*/
|
|
143
|
+
export async function resolveVisible(store, agent, registry) {
|
|
144
|
+
return (await resolveWorkspace(store, agent, registry)).visible;
|
|
145
|
+
}
|
|
146
|
+
//# sourceMappingURL=resolve.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/scope/resolve.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Workspace resolution: map a session cwd to a host workspace UUID and answer\n * \"may the plugin act for this agent?\" from the scope document.\n *\n * `scope.json` lists workspace **ids**, while a session header carries a\n * **cwd path**, so visibility is a registry lookup, never a path comparison.\n * The production resolver (`resolveWorkspace` / `workspaceIdFor`) is\n * asynchronous and prefers the registry's canonical `resolveByPath`, because\n * `Workspace.path` is a realpath while `Session.header.cwd` is only absolute.\n * `workspaceIdOf` remains the synchronous exact-match fallback for a registry\n * that offers only `list()`, and the section provider stays synchronous by\n * reading the cached judgement.\n *\n * Everything is fail-closed. No agent, no session, no cwd, no registry, no\n * matching entry, a throwing `list()`, or a malformed list all mean \"no\n * workspace id\", and `isVisible` treats that as invisible. `workspaceIdOf` is\n * total on purpose: it is the synchronous accessor a later pre-warm path will\n * call directly, so a broken registry degrades to `undefined` here instead of\n * relying on `resolveVisible`'s catch.\n *\n * ## Why `resolveVisible` writes the cache\n *\n * `resolveVisible` is the asynchronous `when` path. Besides returning the\n * judgement it stores it with `store.remember(key, visible)`, keyed by\n * `agent.session.header.id`. The `systemPrompt` section provider is\n * synchronous and can only read `store.judgement(key)`; without this write the\n * protocol section would never appear, with no error anywhere. An agent with\n * no session id has no key to store under, so its judgement is returned but\n * nothing is cached. A resolution failure is remembered as `false`, which is\n * the same fail-closed answer the provider's fallback would give.\n *\n * @module dsh-boost/scope/resolve\n */\nimport { isVisible } from './doc.js'\nimport type { ScopeStore } from './store.js'\n\n/**\n * The host's workspace registry.\n *\n * The host exposes only the synchronous `list()` and the asynchronous\n * `resolveByPath()`; there is no `byPath`. `workspaceIdOf` uses `list()`\n * exclusively so it can stay synchronous. `resolveByPath` is optional here\n * because a test double need not provide the pre-warm path.\n */\nexport interface WorkspaceRegistry {\n list(): readonly { id: string; path: string }[]\n resolveByPath?(path: string): Promise<{ id: string } | undefined>\n}\n\n/**\n * The agent shape this module reads.\n *\n * Looser than `AgentLike`: the brief's tests pass agents without an `id` (and\n * `resolveVisible` passes `unknown`), so the header is optional here.\n */\ntype AgentWithCwd = { session?: { header?: { cwd?: string } } }\n\n/** The session id, when the agent has one; that is the judgement-cache key. */\nfunction agentKeyOf(agent: unknown): string | undefined {\n const id = (agent as { session?: { header?: { id?: unknown } } } | undefined)?.session?.header?.id\n return typeof id === 'string' ? id : undefined\n}\n\n/**\n * Resolve the host workspace UUID for an agent's cwd.\n *\n * The cwd is matched against `registry.list()` by exact `path` equality, so\n * `/w/a` does not match a workspace at `/w/ab` (or at `/w/a/`). This is the\n * **synchronous fallback** for a registry without `resolveByPath`; the async\n * {@link workspaceIdFor} is the production path because `Workspace.path` is a\n * canonical realpath while `Session.header.cwd` is only guaranteed absolute.\n * Any missing or malformed link in the chain — no agent, no session, a\n * non-string cwd, no registry, a `list()` that is not an array, throws, or\n * contains non-object entries — yields `undefined`, which `isVisible` treats as\n * invisible. This function never throws, even when called outside\n * `resolveVisible`.\n */\nexport function workspaceIdOf(\n agent: AgentWithCwd | undefined,\n registry: WorkspaceRegistry | undefined,\n): string | undefined {\n const cwd = agent?.session?.header?.cwd\n if (typeof cwd !== 'string') return undefined\n try {\n const workspaces = registry?.list()\n if (!Array.isArray(workspaces)) return undefined\n return workspaces.find(workspace => workspace?.path === cwd)?.id\n } catch {\n return undefined\n }\n}\n\n/**\n * Resolve the workspace UUID, preferring the host's canonical lookup.\n *\n * `Workspace.path` is the canonical realpath (`dsh-workspace/src/types.ts`),\n * while `Session.header.cwd` is only guaranteed absolute\n * (`dsh-session/src/index.ts`), so a symlinked cwd or one with a trailing\n * slash never matches byte-for-byte. `resolveByPath` is the registry's\n * canonical resolver and is used whenever it exists; its `undefined` answer is\n * authoritative (the workspace is not registered), while a registry without it\n * falls back to the synchronous exact match. A throwing resolver is a\n * resolution failure and fails closed (`undefined` -> invisible), never a\n * crash and never a silent exact-match second guess.\n *\n * Never throws.\n */\nexport async function workspaceIdFor(\n agent: AgentWithCwd | undefined,\n registry: WorkspaceRegistry | undefined,\n): Promise<string | undefined> {\n const cwd = agent?.session?.header?.cwd\n if (typeof cwd !== 'string') return undefined\n const resolveByPath = registry?.resolveByPath\n if (typeof resolveByPath === 'function') {\n try {\n const workspace = await resolveByPath.call(registry, cwd)\n return typeof workspace?.id === 'string' ? workspace.id : undefined\n } catch {\n return undefined\n }\n }\n return workspaceIdOf(agent, registry)\n}\n\n/**\n * Visibility plus the workspace id the judgement was made against.\n *\n * `resolveVisible` is the boolean projection of this result. `apply` also needs\n * the id: the stream hook's `resolveSession` map must carry the same canonical\n * workspace id the judgement used, or a symlinked cwd would be judged visible\n * and then refused by the substitution path.\n */\nexport async function resolveWorkspace(\n store: ScopeStore,\n agent: unknown,\n registry: WorkspaceRegistry | undefined,\n): Promise<{ visible: boolean; workspaceId?: string }> {\n try {\n const key = agentKeyOf(agent)\n let workspaceId: string | undefined\n let visible = false\n try {\n workspaceId = await workspaceIdFor(agent as AgentWithCwd | undefined, registry)\n const { doc } = await store.read()\n visible = isVisible(doc, workspaceId)\n } catch {\n visible = false\n }\n if (key !== undefined) store.remember(key, visible)\n return { visible, ...(workspaceId === undefined ? {} : { workspaceId }) }\n } catch {\n return { visible: false }\n }\n}\n\n/**\n * Whether the plugin may act for `agent`, caching the judgement for the\n * synchronous prompt provider.\n *\n * Never throws: a degraded read, a throwing registry, or a malformed `list()`\n * all resolve to `false`. When the agent has a session id the result (including\n * a failure's `false`) is written with `store.remember` before returning, so a\n * subsequent synchronous `judgement(key)` sees the same answer.\n *\n * A degraded store read (missing, unreadable, corrupt or newer-versioned\n * `scope.json`) is a *definitive* `false` for this resolution, not an unknown:\n * it is cached like any other judgement. It is not sticky — the next\n * `resolveVisible` call re-reads the store and overwrites the same key, so a\n * repaired scope document self-heals the cache on the following resolution.\n */\nexport async function resolveVisible(\n store: ScopeStore,\n agent: unknown,\n registry: WorkspaceRegistry | undefined,\n): Promise<boolean> {\n return (await resolveWorkspace(store, agent, registry)).visible\n}\n"]}
|
|
@@ -0,0 +1,135 @@
|
|
|
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
|
+
}
|