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.
Files changed (110) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +29 -0
  3. package/README.en.md +476 -0
  4. package/README.md +408 -2
  5. package/cordis.patch.yml +40 -0
  6. package/dist/admission/fixed-cost.d.ts +23 -0
  7. package/dist/admission/fixed-cost.js +61 -0
  8. package/dist/admission/fixed-cost.js.map +1 -0
  9. package/dist/admission/ledger.d.ts +113 -0
  10. package/dist/admission/ledger.js +176 -0
  11. package/dist/admission/ledger.js.map +1 -0
  12. package/dist/admission/retrieval.d.ts +65 -0
  13. package/dist/admission/retrieval.js +162 -0
  14. package/dist/admission/retrieval.js.map +1 -0
  15. package/dist/admission/usage.d.ts +75 -0
  16. package/dist/admission/usage.js +124 -0
  17. package/dist/admission/usage.js.map +1 -0
  18. package/dist/config.d.ts +43 -0
  19. package/dist/config.js +103 -0
  20. package/dist/config.js.map +1 -0
  21. package/dist/gate/binding.d.ts +113 -0
  22. package/dist/gate/binding.js +297 -0
  23. package/dist/gate/binding.js.map +1 -0
  24. package/dist/gate/decide.d.ts +82 -0
  25. package/dist/gate/decide.js +163 -0
  26. package/dist/gate/decide.js.map +1 -0
  27. package/dist/gate/guard.d.ts +69 -0
  28. package/dist/gate/guard.js +195 -0
  29. package/dist/gate/guard.js.map +1 -0
  30. package/dist/gate/invalidate.d.ts +112 -0
  31. package/dist/gate/invalidate.js +111 -0
  32. package/dist/gate/invalidate.js.map +1 -0
  33. package/dist/gate/plan.d.ts +86 -0
  34. package/dist/gate/plan.js +222 -0
  35. package/dist/gate/plan.js.map +1 -0
  36. package/dist/hooks/clock.d.ts +68 -0
  37. package/dist/hooks/clock.js +82 -0
  38. package/dist/hooks/clock.js.map +1 -0
  39. package/dist/hooks/execute.d.ts +79 -0
  40. package/dist/hooks/execute.js +128 -0
  41. package/dist/hooks/execute.js.map +1 -0
  42. package/dist/hooks/llm-stream.d.ts +276 -0
  43. package/dist/hooks/llm-stream.js +1008 -0
  44. package/dist/hooks/llm-stream.js.map +1 -0
  45. package/dist/hooks/pending.d.ts +89 -0
  46. package/dist/hooks/pending.js +115 -0
  47. package/dist/hooks/pending.js.map +1 -0
  48. package/dist/hooks/post-execute.d.ts +247 -0
  49. package/dist/hooks/post-execute.js +1776 -0
  50. package/dist/hooks/post-execute.js.map +1 -0
  51. package/dist/hooks/session-state.d.ts +158 -0
  52. package/dist/hooks/session-state.js +168 -0
  53. package/dist/hooks/session-state.js.map +1 -0
  54. package/dist/hooks/synthesize.d.ts +74 -0
  55. package/dist/hooks/synthesize.js +100 -0
  56. package/dist/hooks/synthesize.js.map +1 -0
  57. package/dist/host/loader.d.ts +23 -0
  58. package/dist/host/loader.js +31 -0
  59. package/dist/host/loader.js.map +1 -0
  60. package/dist/host/platform.d.ts +18 -0
  61. package/dist/host/platform.js +19 -0
  62. package/dist/host/platform.js.map +1 -0
  63. package/dist/host/root.d.ts +18 -0
  64. package/dist/host/root.js +43 -0
  65. package/dist/host/root.js.map +1 -0
  66. package/dist/index.d.ts +13 -0
  67. package/dist/index.js +866 -0
  68. package/dist/index.js.map +1 -0
  69. package/dist/projection/apply.d.ts +174 -0
  70. package/dist/projection/apply.js +137 -0
  71. package/dist/projection/apply.js.map +1 -0
  72. package/dist/projection/canonicalise.d.ts +43 -0
  73. package/dist/projection/canonicalise.js +43 -0
  74. package/dist/projection/canonicalise.js.map +1 -0
  75. package/dist/projection/counters.d.ts +65 -0
  76. package/dist/projection/counters.js +88 -0
  77. package/dist/projection/counters.js.map +1 -0
  78. package/dist/projection/truncate.d.ts +47 -0
  79. package/dist/projection/truncate.js +57 -0
  80. package/dist/projection/truncate.js.map +1 -0
  81. package/dist/prompt/protocol.d.ts +45 -0
  82. package/dist/prompt/protocol.js +56 -0
  83. package/dist/prompt/protocol.js.map +1 -0
  84. package/dist/receipts/store.d.ts +198 -0
  85. package/dist/receipts/store.js +734 -0
  86. package/dist/receipts/store.js.map +1 -0
  87. package/dist/scope/doc.d.ts +117 -0
  88. package/dist/scope/doc.js +158 -0
  89. package/dist/scope/doc.js.map +1 -0
  90. package/dist/scope/resolve.d.ts +91 -0
  91. package/dist/scope/resolve.js +146 -0
  92. package/dist/scope/resolve.js.map +1 -0
  93. package/dist/scope/store.d.ts +135 -0
  94. package/dist/scope/store.js +573 -0
  95. package/dist/scope/store.js.map +1 -0
  96. package/dist/selector/jev.d.ts +93 -0
  97. package/dist/selector/jev.js +171 -0
  98. package/dist/selector/jev.js.map +1 -0
  99. package/dist/tools/boost.d.ts +367 -0
  100. package/dist/tools/boost.js +768 -0
  101. package/dist/tools/boost.js.map +1 -0
  102. package/dist/tools/family.d.ts +26 -0
  103. package/dist/tools/family.js +26 -0
  104. package/dist/tools/family.js.map +1 -0
  105. package/dist/types.d.ts +113 -0
  106. package/dist/types.js +21 -0
  107. package/dist/types.js.map +1 -0
  108. package/locale/en.json +6 -0
  109. package/locale/zh.json +6 -0
  110. 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
+ }