@amaranthic/hernex 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. package/CHANGELOG.md +261 -0
  2. package/README.md +2 -2
  3. package/dist/checkpoints/FileCheckpointStore.d.ts.map +1 -1
  4. package/dist/checkpoints/FileCheckpointStore.js +105 -15
  5. package/dist/checkpoints/FileCheckpointStore.js.map +1 -1
  6. package/dist/checkpoints/types.d.ts +4 -4
  7. package/dist/checkpoints/types.d.ts.map +1 -1
  8. package/dist/engine/AgentEngine.d.ts +4 -4
  9. package/dist/engine/AgentEngine.d.ts.map +1 -1
  10. package/dist/engine/AgentEngine.js +9 -7
  11. package/dist/engine/AgentEngine.js.map +1 -1
  12. package/dist/engine/engineConfig.d.ts +2 -2
  13. package/dist/engine/engineConfig.d.ts.map +1 -1
  14. package/dist/engine/index.d.ts +1 -1
  15. package/dist/engine/index.d.ts.map +1 -1
  16. package/dist/engine/index.js.map +1 -1
  17. package/dist/engine/runTurn.d.ts.map +1 -1
  18. package/dist/engine/runTurn.js +85 -51
  19. package/dist/engine/runTurn.js.map +1 -1
  20. package/dist/errors.d.ts +52 -0
  21. package/dist/errors.d.ts.map +1 -1
  22. package/dist/errors.js +45 -0
  23. package/dist/errors.js.map +1 -1
  24. package/dist/events/checkpointEvents.d.ts +1 -1
  25. package/dist/events/index.d.ts +4 -4
  26. package/dist/events/index.d.ts.map +1 -1
  27. package/dist/events/stepEvents.d.ts +1 -1
  28. package/dist/events/stepEvents.d.ts.map +1 -1
  29. package/dist/events/streamEvents.d.ts +2 -2
  30. package/dist/events/toolEvents.d.ts +4 -2
  31. package/dist/events/toolEvents.d.ts.map +1 -1
  32. package/dist/events/types.d.ts +7 -0
  33. package/dist/events/types.d.ts.map +1 -1
  34. package/dist/events/types.js +20 -1
  35. package/dist/events/types.js.map +1 -1
  36. package/dist/hooks/composeAgentHooks.d.ts.map +1 -1
  37. package/dist/hooks/composeAgentHooks.js +19 -7
  38. package/dist/hooks/composeAgentHooks.js.map +1 -1
  39. package/dist/hooks/types.d.ts +1 -1
  40. package/dist/hooks/types.d.ts.map +1 -1
  41. package/dist/index.d.ts +8 -6
  42. package/dist/index.d.ts.map +1 -1
  43. package/dist/index.js +7 -6
  44. package/dist/index.js.map +1 -1
  45. package/dist/model/resolveModel.d.ts.map +1 -1
  46. package/dist/model/resolveModel.js +1 -1
  47. package/dist/model/resolveModel.js.map +1 -1
  48. package/dist/model/types.d.ts.map +1 -1
  49. package/dist/runtime.d.ts.map +1 -1
  50. package/dist/runtime.js +1 -1
  51. package/dist/runtime.js.map +1 -1
  52. package/dist/storage/atomicFile.d.ts +1 -1
  53. package/dist/storage/atomicFile.d.ts.map +1 -1
  54. package/dist/storage/atomicFile.js +28 -2
  55. package/dist/storage/atomicFile.js.map +1 -1
  56. package/dist/storage/homeDirectory.d.ts +1 -1
  57. package/dist/storage/homeDirectory.d.ts.map +1 -1
  58. package/dist/storage/index.d.ts +1 -0
  59. package/dist/storage/index.d.ts.map +1 -1
  60. package/dist/storage/index.js +1 -0
  61. package/dist/storage/index.js.map +1 -1
  62. package/dist/storage/jsonl.d.ts +9 -0
  63. package/dist/storage/jsonl.d.ts.map +1 -1
  64. package/dist/storage/jsonl.js +22 -1
  65. package/dist/storage/jsonl.js.map +1 -1
  66. package/dist/storage/lock.d.ts +23 -0
  67. package/dist/storage/lock.d.ts.map +1 -1
  68. package/dist/storage/lock.js +149 -1
  69. package/dist/storage/lock.js.map +1 -1
  70. package/dist/storage/valueCodec.d.ts +10 -4
  71. package/dist/storage/valueCodec.d.ts.map +1 -1
  72. package/dist/storage/valueCodec.js +65 -40
  73. package/dist/storage/valueCodec.js.map +1 -1
  74. package/dist/storage/workspaceLock.d.ts +38 -0
  75. package/dist/storage/workspaceLock.d.ts.map +1 -0
  76. package/dist/storage/workspaceLock.js +77 -0
  77. package/dist/storage/workspaceLock.js.map +1 -0
  78. package/dist/tasks/TaskManager.d.ts +1 -1
  79. package/dist/tasks/TaskManager.d.ts.map +1 -1
  80. package/dist/tasks/TaskManager.js +52 -16
  81. package/dist/tasks/TaskManager.js.map +1 -1
  82. package/dist/tasks/types.d.ts +8 -2
  83. package/dist/tasks/types.d.ts.map +1 -1
  84. package/dist/threads/FileThreadStore.d.ts +3 -3
  85. package/dist/threads/FileThreadStore.d.ts.map +1 -1
  86. package/dist/threads/FileThreadStore.js +18 -14
  87. package/dist/threads/FileThreadStore.js.map +1 -1
  88. package/dist/threads/index.d.ts +2 -0
  89. package/dist/threads/index.d.ts.map +1 -1
  90. package/dist/threads/index.js +2 -0
  91. package/dist/threads/index.js.map +1 -1
  92. package/dist/threads/transcriptMigration.d.ts +52 -0
  93. package/dist/threads/transcriptMigration.d.ts.map +1 -0
  94. package/dist/threads/transcriptMigration.js +100 -0
  95. package/dist/threads/transcriptMigration.js.map +1 -0
  96. package/dist/threads/transcriptProjection.d.ts +21 -0
  97. package/dist/threads/transcriptProjection.d.ts.map +1 -0
  98. package/dist/threads/transcriptProjection.js +123 -0
  99. package/dist/threads/transcriptProjection.js.map +1 -0
  100. package/dist/threads/types.d.ts +29 -9
  101. package/dist/threads/types.d.ts.map +1 -1
  102. package/dist/threads/types.js +1 -1
  103. package/dist/tools/BashTool.d.ts.map +1 -1
  104. package/dist/tools/BashTool.js +37 -21
  105. package/dist/tools/BashTool.js.map +1 -1
  106. package/dist/tools/EditFileTool.d.ts.map +1 -1
  107. package/dist/tools/EditFileTool.js +62 -57
  108. package/dist/tools/EditFileTool.js.map +1 -1
  109. package/dist/tools/GlobTool.d.ts +4 -4
  110. package/dist/tools/GlobTool.d.ts.map +1 -1
  111. package/dist/tools/GlobTool.js +6 -6
  112. package/dist/tools/GlobTool.js.map +1 -1
  113. package/dist/tools/GrepTool.d.ts +8 -5
  114. package/dist/tools/GrepTool.d.ts.map +1 -1
  115. package/dist/tools/GrepTool.js +45 -19
  116. package/dist/tools/GrepTool.js.map +1 -1
  117. package/dist/tools/ReadFileTool.d.ts.map +1 -1
  118. package/dist/tools/ReadFileTool.js.map +1 -1
  119. package/dist/tools/TaskManagerTool.d.ts +1 -1
  120. package/dist/tools/TaskManagerTool.d.ts.map +1 -1
  121. package/dist/tools/TaskManagerTool.js +5 -3
  122. package/dist/tools/TaskManagerTool.js.map +1 -1
  123. package/dist/tools/ToolExecutionContext.d.ts +3 -3
  124. package/dist/tools/WriteFileTool.d.ts +1 -1
  125. package/dist/tools/WriteFileTool.d.ts.map +1 -1
  126. package/dist/tools/WriteFileTool.js +49 -44
  127. package/dist/tools/WriteFileTool.js.map +1 -1
  128. package/dist/tools/internal/pathGuard.d.ts +2 -2
  129. package/dist/tools/internal/pathGuard.d.ts.map +1 -1
  130. package/dist/tools/internal/pathGuard.js +3 -3
  131. package/dist/tools/internal/pathGuard.js.map +1 -1
  132. package/dist/tools/prompts.d.ts.map +1 -1
  133. package/dist/tools/prompts.js +7 -7
  134. package/dist/tools/prompts.js.map +1 -1
  135. package/package.json +6 -5
@@ -1 +1 @@
1
- {"version":3,"file":"jsonl.js","sources":["../../src/storage/jsonl.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"jsonl.js","sources":["../../src/storage/jsonl.ts"],"names":[],"mappings":"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"}
@@ -27,12 +27,35 @@ export interface FileLockOptions {
27
27
  * Defaults to 25ms.
28
28
  */
29
29
  readonly retryIntervalMs?: number;
30
+ /**
31
+ * Maximum age of a lock in milliseconds before it is considered stale, even if process
32
+ * liveness cannot be disproven.
33
+ *
34
+ * Note on distributed/network filesystems:
35
+ * Process liveness checks (`process.kill(pid, 0)`) are strictly local to the current host kernel.
36
+ * Clustered or shared network file systems (NFS, SMB, CIFS) span multiple hosts that do not share
37
+ * process identifiers; in multi-host topologies, configure `staleMs` to recover abandoned locks.
38
+ */
39
+ readonly staleMs?: number;
30
40
  }
41
+ /**
42
+ * Checks whether a process with the given PID is running on the local host.
43
+ *
44
+ * Uses `process.kill(pid, 0)` which performs permission and existence checks without
45
+ * sending an actual signal.
46
+ *
47
+ * @param pid - Local operating system process identifier to probe.
48
+ * @returns `true` if the process exists and is active; `false` if `ESRCH` (process not found).
49
+ */
50
+ export declare function isProcessAlive(pid: number): boolean;
31
51
  /**
32
52
  * Executes an operation while holding an exclusive file lock.
33
53
  *
34
54
  * Contention (`EEXIST`) is retried until `timeoutMs` expires. All non-contention
35
55
  * errors (such as `EACCES`, `ENOSPC`, or `EIO`) fail immediately without retry.
56
+ * If an existing lock is held by a terminated local process or its age exceeds `staleMs`,
57
+ * it is safely reclaimed via an atomic staging and compare-and-swap sequence without
58
+ * displacing live owners.
36
59
  * Ownership is verified on release using a cryptographic token. If both the inner
37
60
  * operation and lock release encounter errors, they are preserved via `AggregateError`.
38
61
  *
@@ -1 +1 @@
1
- {"version":3,"file":"lock.d.ts","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,eAAe,GAC1C,OAAO,CAAC,CAAC,CAAC,CA0HZ"}
1
+ {"version":3,"file":"lock.d.ts","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAgBH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAenD;AA8ED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,eAAe,GAC1C,OAAO,CAAC,CAAC,CAAC,CAoLZ"}
@@ -4,14 +4,102 @@
4
4
  */
5
5
  import { randomUUID } from "node:crypto";
6
6
  import { existsSync } from "node:fs";
7
- import { mkdir, open, readFile, unlink } from "node:fs/promises";
7
+ import { mkdir, open, readFile, rename, stat, unlink, writeFile, } from "node:fs/promises";
8
8
  import path from "node:path";
9
9
  import { HernexLockError } from "../errors.js";
10
+ /**
11
+ * Checks whether a process with the given PID is running on the local host.
12
+ *
13
+ * Uses `process.kill(pid, 0)` which performs permission and existence checks without
14
+ * sending an actual signal.
15
+ *
16
+ * @param pid - Local operating system process identifier to probe.
17
+ * @returns `true` if the process exists and is active; `false` if `ESRCH` (process not found).
18
+ */
19
+ export function isProcessAlive(pid) {
20
+ if (typeof pid !== "number" || pid <= 0 || !Number.isInteger(pid)) {
21
+ return false;
22
+ }
23
+ try {
24
+ process.kill(pid, 0);
25
+ return true;
26
+ }
27
+ catch (error) {
28
+ const code = error?.code;
29
+ if (code === "ESRCH") {
30
+ return false;
31
+ }
32
+ // EPERM indicates the process exists on this host but is owned by another user
33
+ return true;
34
+ }
35
+ }
36
+ /**
37
+ * Inspects an existing lock file to determine if it is stale or abandoned.
38
+ *
39
+ * @param lockPath - Absolute path to the lock file.
40
+ * @param staleMs - Optional stale threshold in milliseconds.
41
+ * @returns Lock inspection result.
42
+ */
43
+ async function inspectLock(lockPath, staleMs) {
44
+ let content;
45
+ try {
46
+ content = await readFile(lockPath, "utf-8");
47
+ }
48
+ catch (error) {
49
+ if (error?.code === "ENOENT") {
50
+ return { isStale: false };
51
+ }
52
+ throw error;
53
+ }
54
+ if (!content || content.trim() === "") {
55
+ try {
56
+ const stats = await stat(lockPath);
57
+ if (Date.now() - stats.mtimeMs > (staleMs ?? 1000)) {
58
+ return { isStale: true, reason: "empty_or_abandoned" };
59
+ }
60
+ }
61
+ catch {
62
+ return { isStale: false };
63
+ }
64
+ return { isStale: false };
65
+ }
66
+ let parsed;
67
+ try {
68
+ parsed = JSON.parse(content);
69
+ }
70
+ catch {
71
+ try {
72
+ const stats = await stat(lockPath);
73
+ if (Date.now() - stats.mtimeMs > (staleMs ?? 1000)) {
74
+ return { isStale: true, reason: "corrupted_payload" };
75
+ }
76
+ }
77
+ catch {
78
+ return { isStale: false };
79
+ }
80
+ return { isStale: false };
81
+ }
82
+ if (typeof parsed?.pid !== "number" ||
83
+ typeof parsed?.token !== "string" ||
84
+ typeof parsed?.createdAt !== "number") {
85
+ return { isStale: true, reason: "malformed_fields" };
86
+ }
87
+ if (staleMs !== undefined && Date.now() - parsed.createdAt > staleMs) {
88
+ return { isStale: true, payload: parsed, reason: "stale_ms_exceeded" };
89
+ }
90
+ if (!isProcessAlive(parsed.pid)) {
91
+ return { isStale: true, payload: parsed, reason: "process_terminated" };
92
+ }
93
+ return { isStale: false, payload: parsed };
94
+ }
10
95
  /**
11
96
  * Executes an operation while holding an exclusive file lock.
12
97
  *
13
98
  * Contention (`EEXIST`) is retried until `timeoutMs` expires. All non-contention
14
99
  * errors (such as `EACCES`, `ENOSPC`, or `EIO`) fail immediately without retry.
100
+ * If an existing lock is held by a terminated local process or its age exceeds `staleMs`,
101
+ * it is safely reclaimed via an atomic staging and compare-and-swap sequence without
102
+ * displacing live owners.
15
103
  * Ownership is verified on release using a cryptographic token. If both the inner
16
104
  * operation and lock release encounter errors, they are preserved via `AggregateError`.
17
105
  *
@@ -29,6 +117,9 @@ export async function withFileLock(lockPath, operation, optionsOrTimeout) {
29
117
  const retryIntervalMs = typeof optionsOrTimeout === "object" && optionsOrTimeout !== null
30
118
  ? (optionsOrTimeout.retryIntervalMs ?? 25)
31
119
  : 25;
120
+ const staleMs = typeof optionsOrTimeout === "object" && optionsOrTimeout !== null
121
+ ? optionsOrTimeout.staleMs
122
+ : undefined;
32
123
  const absoluteLock = path.resolve(lockPath);
33
124
  const parentDir = path.dirname(absoluteLock);
34
125
  if (!existsSync(parentDir)) {
@@ -65,6 +156,63 @@ export async function withFileLock(lockPath, operation, optionsOrTimeout) {
65
156
  }
66
157
  throw error;
67
158
  }
159
+ // Check if existing lock is stale and can be safely reclaimed
160
+ const inspection = await inspectLock(absoluteLock, staleMs);
161
+ if (inspection.isStale) {
162
+ const reclaimLockPath = `${absoluteLock}.reclaim`;
163
+ let reclaimHandle = null;
164
+ try {
165
+ reclaimHandle = await open(reclaimLockPath, "wx");
166
+ }
167
+ catch (reclaimErr) {
168
+ if (reclaimErr?.code === "EEXIST") {
169
+ try {
170
+ const reclaimStats = await stat(reclaimLockPath);
171
+ if (Date.now() - reclaimStats.mtimeMs > 5000) {
172
+ await unlink(reclaimLockPath);
173
+ }
174
+ }
175
+ catch {
176
+ // Ignore stats/unlink errors on secondary contention
177
+ }
178
+ }
179
+ }
180
+ if (reclaimHandle !== null) {
181
+ try {
182
+ await reclaimHandle.close();
183
+ // Re-verify under arbitration lock to avoid displacing newly active owners
184
+ const recheck = await inspectLock(absoluteLock, staleMs);
185
+ if (recheck.isStale) {
186
+ const stagingPath = `${absoluteLock}.staging.${process.pid}.${token}.${Date.now()}`;
187
+ await writeFile(stagingPath, JSON.stringify(payload), "utf-8");
188
+ try {
189
+ await rename(stagingPath, absoluteLock);
190
+ acquired = true;
191
+ }
192
+ catch (renameErr) {
193
+ try {
194
+ await unlink(stagingPath);
195
+ }
196
+ catch {
197
+ // Ignore staging cleanup error
198
+ }
199
+ throw renameErr;
200
+ }
201
+ }
202
+ }
203
+ finally {
204
+ try {
205
+ await unlink(reclaimLockPath);
206
+ }
207
+ catch {
208
+ // Ignore reclaim lock unlink error
209
+ }
210
+ }
211
+ }
212
+ }
213
+ if (acquired) {
214
+ break;
215
+ }
68
216
  if (Date.now() - startTime >= timeoutMs) {
69
217
  throw new HernexLockError(`Failed to acquire lock at "${absoluteLock}" within ${timeoutMs}ms.`, absoluteLock);
70
218
  }
@@ -1 +1 @@
1
- {"version":3,"file":"lock.js","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"lock.js","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"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"}
@@ -41,6 +41,7 @@ export type EncodedValue = {
41
41
  } | {
42
42
  readonly type: "object";
43
43
  readonly entries: Record<string, EncodedValue>;
44
+ readonly isNullPrototype?: boolean;
44
45
  } | {
45
46
  readonly type: "binary";
46
47
  readonly base64: string;
@@ -49,18 +50,23 @@ export type EncodedValue = {
49
50
  * Encodes an arbitrary JavaScript value into a lossless tagged JSON-safe representation.
50
51
  *
51
52
  * Supports primitives, special numbers (NaN, Infinity, -Infinity, -0), Buffer, Uint8Array,
52
- * URL, arrays, and plain objects. Rejects circular references, functions, symbols, bigint,
53
- * and unsupported prototypes fail-closed with a TypeError.
53
+ * URL, arrays, and plain objects (including null-prototype dictionaries). Allows shared
54
+ * acyclic references (diamond structures) while rejecting true circular references fail-closed.
55
+ * Rejects functions, symbols, bigint, and unsupported prototypes fail-closed with a TypeError.
56
+ * Safely preserves special object keys (such as `__proto__`) without altering object prototypes.
54
57
  *
55
58
  * @param value - Any JavaScript value.
56
- * @param seen - Internal Set of traversed objects to detect circular references.
59
+ * @param ancestors - Internal Set of active call-stack ancestor objects to detect circular reference cycles.
57
60
  * @returns Lossless tagged EncodedValue.
58
61
  * @throws {TypeError} When value contains functions, symbols, bigint, circular references, or unsupported prototypes.
59
62
  */
60
- export declare function encodeValue(value: unknown, seen?: WeakSet<object>): EncodedValue;
63
+ export declare function encodeValue(value: unknown, ancestors?: Set<object>): EncodedValue;
61
64
  /**
62
65
  * Decodes a tagged EncodedValue back to its original JavaScript form.
63
66
  *
67
+ * Preserves null prototypes when indicated by `isNullPrototype`, and defines properties
68
+ * using safe own-property definition semantics to prevent prototype tampering.
69
+ *
64
70
  * @param encoded - The EncodedValue.
65
71
  * @returns Restored original JavaScript value.
66
72
  */
@@ -1 +1 @@
1
- {"version":3,"file":"valueCodec.d.ts","sources":["../../src/storage/valueCodec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,GACrC;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,IAAI,GAAE,OAAO,CAAC,MAAM,CAAiB,GACpC,YAAY,CA2Fd;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAqC1D"}
1
+ {"version":3,"file":"valueCodec.d.ts","sources":["../../src/storage/valueCodec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,GACrC;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,GACnE;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC/C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,SAAS,GAAE,GAAG,CAAC,MAAM,CAAa,GACjC,YAAY,CA8Gd;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CA8C1D"}
@@ -6,15 +6,17 @@
6
6
  * Encodes an arbitrary JavaScript value into a lossless tagged JSON-safe representation.
7
7
  *
8
8
  * Supports primitives, special numbers (NaN, Infinity, -Infinity, -0), Buffer, Uint8Array,
9
- * URL, arrays, and plain objects. Rejects circular references, functions, symbols, bigint,
10
- * and unsupported prototypes fail-closed with a TypeError.
9
+ * URL, arrays, and plain objects (including null-prototype dictionaries). Allows shared
10
+ * acyclic references (diamond structures) while rejecting true circular references fail-closed.
11
+ * Rejects functions, symbols, bigint, and unsupported prototypes fail-closed with a TypeError.
12
+ * Safely preserves special object keys (such as `__proto__`) without altering object prototypes.
11
13
  *
12
14
  * @param value - Any JavaScript value.
13
- * @param seen - Internal Set of traversed objects to detect circular references.
15
+ * @param ancestors - Internal Set of active call-stack ancestor objects to detect circular reference cycles.
14
16
  * @returns Lossless tagged EncodedValue.
15
17
  * @throws {TypeError} When value contains functions, symbols, bigint, circular references, or unsupported prototypes.
16
18
  */
17
- export function encodeValue(value, seen = new WeakSet()) {
19
+ export function encodeValue(value, ancestors = new Set()) {
18
20
  if (value === null) {
19
21
  return { type: "null" };
20
22
  }
@@ -52,50 +54,66 @@ export function encodeValue(value, seen = new WeakSet()) {
52
54
  throw new TypeError("Cannot encode value: functions are not serializable.");
53
55
  }
54
56
  if (typeof value === "object") {
55
- if (seen.has(value)) {
57
+ if (ancestors.has(value)) {
56
58
  throw new TypeError("Cannot encode value: circular reference detected.");
57
59
  }
58
- seen.add(value);
59
- if (Buffer.isBuffer(value)) {
60
- return {
61
- type: "buffer",
62
- base64: value.toString("base64"),
63
- };
64
- }
65
- if (value instanceof Uint8Array) {
66
- const buffer = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
67
- return {
68
- type: "uint8array",
69
- base64: buffer.toString("base64"),
70
- };
71
- }
72
- if (value instanceof URL) {
73
- return {
74
- type: "url",
75
- href: value.href,
76
- };
77
- }
78
- if (Array.isArray(value)) {
79
- return {
80
- type: "array",
81
- items: value.map((item) => encodeValue(item, seen)),
82
- };
83
- }
84
- const proto = Object.getPrototypeOf(value);
85
- if (proto !== Object.prototype && proto !== null) {
86
- throw new TypeError(`Cannot encode value: unsupported prototype "${proto?.constructor?.name ?? "unknown"}".`);
60
+ ancestors.add(value);
61
+ try {
62
+ if (Buffer.isBuffer(value)) {
63
+ return {
64
+ type: "buffer",
65
+ base64: value.toString("base64"),
66
+ };
67
+ }
68
+ if (value instanceof Uint8Array) {
69
+ const buffer = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
70
+ return {
71
+ type: "uint8array",
72
+ base64: buffer.toString("base64"),
73
+ };
74
+ }
75
+ if (value instanceof URL) {
76
+ return {
77
+ type: "url",
78
+ href: value.href,
79
+ };
80
+ }
81
+ if (Array.isArray(value)) {
82
+ return {
83
+ type: "array",
84
+ items: value.map((item) => encodeValue(item, ancestors)),
85
+ };
86
+ }
87
+ const proto = Object.getPrototypeOf(value);
88
+ if (proto !== Object.prototype && proto !== null) {
89
+ throw new TypeError(`Cannot encode value: unsupported prototype "${proto?.constructor?.name ?? "unknown"}".`);
90
+ }
91
+ const isNullPrototype = proto === null;
92
+ const entries = Object.create(null);
93
+ for (const [k, v] of Object.entries(value)) {
94
+ Object.defineProperty(entries, k, {
95
+ value: encodeValue(v, ancestors),
96
+ enumerable: true,
97
+ writable: true,
98
+ configurable: true,
99
+ });
100
+ }
101
+ return isNullPrototype
102
+ ? { type: "object", entries, isNullPrototype: true }
103
+ : { type: "object", entries };
87
104
  }
88
- const entries = {};
89
- for (const [k, v] of Object.entries(value)) {
90
- entries[k] = encodeValue(v, seen);
105
+ finally {
106
+ ancestors.delete(value);
91
107
  }
92
- return { type: "object", entries };
93
108
  }
94
109
  throw new TypeError(`Cannot encode value: unsupported type "${typeof value}".`);
95
110
  }
96
111
  /**
97
112
  * Decodes a tagged EncodedValue back to its original JavaScript form.
98
113
  *
114
+ * Preserves null prototypes when indicated by `isNullPrototype`, and defines properties
115
+ * using safe own-property definition semantics to prevent prototype tampering.
116
+ *
99
117
  * @param encoded - The EncodedValue.
100
118
  * @returns Restored original JavaScript value.
101
119
  */
@@ -129,9 +147,16 @@ export function decodeValue(encoded) {
129
147
  case "array":
130
148
  return encoded.items.map(decodeValue);
131
149
  case "object": {
132
- const result = {};
150
+ const result = encoded.isNullPrototype
151
+ ? Object.create(null)
152
+ : {};
133
153
  for (const [k, v] of Object.entries(encoded.entries)) {
134
- result[k] = decodeValue(v);
154
+ Object.defineProperty(result, k, {
155
+ value: decodeValue(v),
156
+ enumerable: true,
157
+ writable: true,
158
+ configurable: true,
159
+ });
135
160
  }
136
161
  return result;
137
162
  }
@@ -1 +1 @@
1
- {"version":3,"file":"valueCodec.js","sources":["../../src/storage/valueCodec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsBH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CACzB,KAAc,EACd,IAAI,GAAoB,IAAI,OAAO,EAAE;IAErC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC/B,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACnC,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpC,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACzB,CAAC;QACD,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC9B,CAAC;QACD,IAAI,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC;YACxB,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC;QACtC,CAAC;QACD,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;QAClC,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACnC,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,SAAS,CAAC,oDAAoD,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,sDAAsD,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAEhB,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;aACjC,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;YAC7E,OAAO;gBACL,IAAI,EAAE,YAAY;gBAClB,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;aAClC,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,YAAY,GAAG,EAAE,CAAC;YACzB,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,IAAI,EAAE,KAAK,CAAC,IAAI;aACjB,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;aACpD,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACjD,MAAM,IAAI,SAAS,CACjB,+CAA+C,KAAK,EAAE,WAAW,EAAE,IAAI,IAAI,SAAS,IAAI,CACzF,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAiC,EAAE,CAAC;QACjD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3C,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,IAAI,SAAS,CAAC,0CAA0C,OAAO,KAAK,IAAI,CAAC,CAAC;AAClF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAqB;IAC/C,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,MAAM;YACT,OAAO,IAAI,CAAC;QACd,KAAK,WAAW;YACd,OAAO,SAAS,CAAC;QACnB,KAAK,QAAQ,CAAC;QACd,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,OAAO,CAAC,KAAK,CAAC;QACvB,KAAK,KAAK;YACR,OAAO,GAAG,CAAC;QACb,KAAK,UAAU;YACb,OAAO,QAAQ,CAAC;QAClB,KAAK,kBAAkB;YACrB,OAAO,CAAC,QAAQ,CAAC;QACnB,KAAK,cAAc;YACjB,OAAO,CAAC,CAAC,CAAC;QACZ,KAAK,QAAQ,CAAC;QACd,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC/C,KAAK,YAAY,EAAE,CAAC;YAClB,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAClD,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;QAC3F,CAAC;QACD,KAAK,KAAK;YACR,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/B,KAAK,OAAO;YACV,OAAO,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACxC,KAAK,QAAQ,EAAE,CAAC;YACd,MAAM,MAAM,GAA4B,EAAE,CAAC;YAC3C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrD,MAAM,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;YAC7B,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"valueCodec.js","sources":["../../src/storage/valueCodec.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,38 @@
1
+ /**
2
+ * @fileoverview Deterministic multi-file workspace mutation locking.
3
+ * @packageDocumentation
4
+ */
5
+ import { type ResolveHomeDirectoryOptions } from "./homeDirectory.js";
6
+ import { type FileLockOptions } from "./lock.js";
7
+ /**
8
+ * Derives the exclusive lock file path for a specific target file within a workspace.
9
+ *
10
+ * Placed in `<homeDirectory>/locks/workspaces/<workspaceHash>/<targetHash>.lock` outside
11
+ * the workspace tree so locking never interferes with workspace file content or git status.
12
+ *
13
+ * @param workingDirectory - Absolute workspace root path.
14
+ * @param relativeFilePath - Normalized relative path within the workspace.
15
+ * @param homeDirectory - Optional explicit storage home directory override.
16
+ * @returns Absolute path to the lock file.
17
+ */
18
+ export declare function getWorkspaceLockPath(workingDirectory: string, relativeFilePath: string, homeDirectory?: string): string;
19
+ /**
20
+ * Executes an operation under exclusive file locks for one or more workspace target files.
21
+ *
22
+ * Invariants enforced:
23
+ * - Target paths are normalized, made relative to `workingDirectory`, and deduplicated.
24
+ * - Multi-file locks are acquired in strictly deterministic lexicographical order.
25
+ * This mathematically prevents lock inversion and deadlocks across concurrent mutations.
26
+ * - Holds locks across the entire transaction boundary (before pre-state capture/reading,
27
+ * through mutation, and through post-state checkpoint finalization).
28
+ * - All acquired locks are safely released in reverse order upon completion or failure.
29
+ *
30
+ * @typeParam T - The return type of the executed operation.
31
+ * @param workingDirectory - Absolute workspace root path.
32
+ * @param targetPaths - One or more target file paths relative to or within the workspace.
33
+ * @param operation - The asynchronous transaction callback to execute.
34
+ * @param options - Optional file lock and home directory configuration.
35
+ * @returns The resolved result of the executed operation.
36
+ */
37
+ export declare function withWorkspaceFileLock<T>(workingDirectory: string, targetPaths: string | readonly string[], operation: () => Promise<T>, options?: FileLockOptions & ResolveHomeDirectoryOptions): Promise<T>;
38
+ //# sourceMappingURL=workspaceLock.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"workspaceLock.d.ts","sources":["../../src/storage/workspaceLock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAY/D;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,gBAAgB,EAAE,MAAM,EACxB,gBAAgB,EAAE,MAAM,EACxB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAcR;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACvC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,CAAC,EAAE,eAAe,GAAG,2BAA2B,GACtD,OAAO,CAAC,CAAC,CAAC,CAoCZ"}
@@ -0,0 +1,77 @@
1
+ /**
2
+ * @fileoverview Deterministic multi-file workspace mutation locking.
3
+ * @packageDocumentation
4
+ */
5
+ import { createHash } from "node:crypto";
6
+ import path from "node:path";
7
+ import { resolveHomeDirectory, } from "./homeDirectory.js";
8
+ import { withFileLock } from "./lock.js";
9
+ /**
10
+ * Computes a deterministic hexadecimal hash digest of a path string.
11
+ *
12
+ * @param input - The raw path string to hash.
13
+ * @returns A 24-character hexadecimal hash digest.
14
+ */
15
+ function hashPathSegment(input) {
16
+ return createHash("sha256").update(input).digest("hex").slice(0, 24);
17
+ }
18
+ /**
19
+ * Derives the exclusive lock file path for a specific target file within a workspace.
20
+ *
21
+ * Placed in `<homeDirectory>/locks/workspaces/<workspaceHash>/<targetHash>.lock` outside
22
+ * the workspace tree so locking never interferes with workspace file content or git status.
23
+ *
24
+ * @param workingDirectory - Absolute workspace root path.
25
+ * @param relativeFilePath - Normalized relative path within the workspace.
26
+ * @param homeDirectory - Optional explicit storage home directory override.
27
+ * @returns Absolute path to the lock file.
28
+ */
29
+ export function getWorkspaceLockPath(workingDirectory, relativeFilePath, homeDirectory) {
30
+ const canonicalWorkspace = path.resolve(workingDirectory);
31
+ const normalizedRelative = path.normalize(relativeFilePath);
32
+ const workspaceHash = hashPathSegment(canonicalWorkspace);
33
+ const fileHash = hashPathSegment(normalizedRelative);
34
+ const storageHome = resolveHomeDirectory({ homeDirectory });
35
+ return path.join(storageHome, "locks", "workspaces", workspaceHash, `${fileHash}.lock`);
36
+ }
37
+ /**
38
+ * Executes an operation under exclusive file locks for one or more workspace target files.
39
+ *
40
+ * Invariants enforced:
41
+ * - Target paths are normalized, made relative to `workingDirectory`, and deduplicated.
42
+ * - Multi-file locks are acquired in strictly deterministic lexicographical order.
43
+ * This mathematically prevents lock inversion and deadlocks across concurrent mutations.
44
+ * - Holds locks across the entire transaction boundary (before pre-state capture/reading,
45
+ * through mutation, and through post-state checkpoint finalization).
46
+ * - All acquired locks are safely released in reverse order upon completion or failure.
47
+ *
48
+ * @typeParam T - The return type of the executed operation.
49
+ * @param workingDirectory - Absolute workspace root path.
50
+ * @param targetPaths - One or more target file paths relative to or within the workspace.
51
+ * @param operation - The asynchronous transaction callback to execute.
52
+ * @param options - Optional file lock and home directory configuration.
53
+ * @returns The resolved result of the executed operation.
54
+ */
55
+ export async function withWorkspaceFileLock(workingDirectory, targetPaths, operation, options) {
56
+ const rawList = Array.isArray(targetPaths) ? targetPaths : [targetPaths];
57
+ if (rawList.length === 0) {
58
+ return await operation();
59
+ }
60
+ const canonicalWorkspace = path.resolve(workingDirectory);
61
+ const normalizedPaths = Array.from(new Set(rawList.map((p) => {
62
+ const resolved = path.isAbsolute(p)
63
+ ? path.resolve(p)
64
+ : path.resolve(canonicalWorkspace, p);
65
+ return path.relative(canonicalWorkspace, resolved);
66
+ }))).sort();
67
+ const acquireRecursive = async (index) => {
68
+ if (index >= normalizedPaths.length) {
69
+ return await operation();
70
+ }
71
+ const relPath = normalizedPaths[index];
72
+ const lockPath = getWorkspaceLockPath(canonicalWorkspace, relPath, options?.homeDirectory);
73
+ return await withFileLock(lockPath, () => acquireRecursive(index + 1), options);
74
+ };
75
+ return await acquireRecursive(0);
76
+ }
77
+ //# sourceMappingURL=workspaceLock.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"workspaceLock.js","sources":["../../src/storage/workspaceLock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EACL,oBAAoB,GAErB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAwB,MAAM,WAAW,CAAC;AAE/D;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,gBAAwB,EACxB,gBAAwB,EACxB,aAAsB;IAEtB,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1D,MAAM,kBAAkB,GAAG,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAC5D,MAAM,aAAa,GAAG,eAAe,CAAC,kBAAkB,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,eAAe,CAAC,kBAAkB,CAAC,CAAC;IAErD,MAAM,WAAW,GAAG,oBAAoB,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,IAAI,CACd,WAAW,EACX,OAAO,EACP,YAAY,EACZ,aAAa,EACb,GAAG,QAAQ,OAAO,CACnB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,gBAAwB,EACxB,WAAuC,EACvC,SAA2B,EAC3B,OAAuD;IAEvD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACzE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;IAED,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1D,MAAM,eAAe,GAAG,KAAK,CAAC,IAAI,CAChC,IAAI,GAAG,CACL,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAChB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YACjC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YACjB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC,QAAQ,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;IACrD,CAAC,CAAC,CACH,CACF,CAAC,IAAI,EAAE,CAAC;IAET,MAAM,gBAAgB,GAAG,KAAK,EAAE,KAAa,EAAc,EAAE;QAC3D,IAAI,KAAK,IAAI,eAAe,CAAC,MAAM,EAAE,CAAC;YACpC,OAAO,MAAM,SAAS,EAAE,CAAC;QAC3B,CAAC;QACD,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAE,CAAC;QACxC,MAAM,QAAQ,GAAG,oBAAoB,CACnC,kBAAkB,EAClB,OAAO,EACP,OAAO,EAAE,aAAa,CACvB,CAAC;QACF,OAAO,MAAM,YAAY,CACvB,QAAQ,EACR,GAAG,EAAE,CAAC,gBAAgB,CAAC,KAAK,GAAG,CAAC,CAAC,EACjC,OAAO,CACR,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO,MAAM,gBAAgB,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC"}
@@ -58,7 +58,7 @@ export declare class TaskManager {
58
58
  private getTaskDirectory;
59
59
  /**
60
60
  * Spawns and registers a new shell process as a managed task.
61
- * This is the sole execution owner for subprocess spawning across Harnex.
61
+ * This is the sole execution owner for subprocess spawning across Hernex.
62
62
  *
63
63
  * @param input - Process parameters including command string, cwd, timeout, and environment allowlist.
64
64
  * @param options - Optional observers such as streaming onOutput callback.
@@ -1 +1 @@
1
- {"version":3,"file":"TaskManager.d.ts","sources":["../../src/tasks/TaskManager.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"TaskManager.d.ts","sources":["../../src/tasks/TaskManager.ts"],"names":[],"mappings":"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"}