@amaranthic/hernex 0.0.0-stage → 0.2.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 (259) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +66 -2
  3. package/dist/ai.d.ts +11 -0
  4. package/dist/ai.d.ts.map +1 -0
  5. package/dist/ai.js +11 -0
  6. package/dist/ai.js.map +1 -0
  7. package/dist/checkpoints/FileCheckpointStore.d.ts +95 -0
  8. package/dist/checkpoints/FileCheckpointStore.d.ts.map +1 -0
  9. package/dist/checkpoints/FileCheckpointStore.js +412 -0
  10. package/dist/checkpoints/FileCheckpointStore.js.map +1 -0
  11. package/dist/checkpoints/index.d.ts +7 -0
  12. package/dist/checkpoints/index.d.ts.map +1 -0
  13. package/dist/checkpoints/index.js +7 -0
  14. package/dist/checkpoints/index.js.map +1 -0
  15. package/dist/checkpoints/types.d.ts +157 -0
  16. package/dist/checkpoints/types.d.ts.map +1 -0
  17. package/dist/checkpoints/types.js +6 -0
  18. package/dist/checkpoints/types.js.map +1 -0
  19. package/dist/engine/AgentEngine.d.ts +156 -0
  20. package/dist/engine/AgentEngine.d.ts.map +1 -0
  21. package/dist/engine/AgentEngine.js +288 -0
  22. package/dist/engine/AgentEngine.js.map +1 -0
  23. package/dist/engine/engineConfig.d.ts +138 -0
  24. package/dist/engine/engineConfig.d.ts.map +1 -0
  25. package/dist/engine/engineConfig.js +6 -0
  26. package/dist/engine/engineConfig.js.map +1 -0
  27. package/dist/engine/eventQueue.d.ts +42 -0
  28. package/dist/engine/eventQueue.d.ts.map +1 -0
  29. package/dist/engine/eventQueue.js +93 -0
  30. package/dist/engine/eventQueue.js.map +1 -0
  31. package/dist/engine/index.d.ts +7 -0
  32. package/dist/engine/index.d.ts.map +1 -0
  33. package/dist/engine/index.js +6 -0
  34. package/dist/engine/index.js.map +1 -0
  35. package/dist/engine/runTurn.d.ts +17 -0
  36. package/dist/engine/runTurn.d.ts.map +1 -0
  37. package/dist/engine/runTurn.js +684 -0
  38. package/dist/engine/runTurn.js.map +1 -0
  39. package/dist/errors.d.ts +142 -0
  40. package/dist/errors.d.ts.map +1 -0
  41. package/dist/errors.js +174 -0
  42. package/dist/errors.js.map +1 -0
  43. package/dist/events/checkpointEvents.d.ts +20 -0
  44. package/dist/events/checkpointEvents.d.ts.map +1 -0
  45. package/dist/events/checkpointEvents.js +6 -0
  46. package/dist/events/checkpointEvents.js.map +1 -0
  47. package/dist/events/errorEvents.d.ts +23 -0
  48. package/dist/events/errorEvents.d.ts.map +1 -0
  49. package/dist/events/errorEvents.js +6 -0
  50. package/dist/events/errorEvents.js.map +1 -0
  51. package/dist/events/index.d.ts +11 -0
  52. package/dist/events/index.d.ts.map +1 -0
  53. package/dist/events/index.js +6 -0
  54. package/dist/events/index.js.map +1 -0
  55. package/dist/events/stepEvents.d.ts +68 -0
  56. package/dist/events/stepEvents.d.ts.map +1 -0
  57. package/dist/events/stepEvents.js +6 -0
  58. package/dist/events/stepEvents.js.map +1 -0
  59. package/dist/events/streamEvents.d.ts +41 -0
  60. package/dist/events/streamEvents.d.ts.map +1 -0
  61. package/dist/events/streamEvents.js +6 -0
  62. package/dist/events/streamEvents.js.map +1 -0
  63. package/dist/events/toolEvents.d.ts +62 -0
  64. package/dist/events/toolEvents.d.ts.map +1 -0
  65. package/dist/events/toolEvents.js +6 -0
  66. package/dist/events/toolEvents.js.map +1 -0
  67. package/dist/events/types.d.ts +37 -0
  68. package/dist/events/types.d.ts.map +1 -0
  69. package/dist/events/types.js +6 -0
  70. package/dist/events/types.js.map +1 -0
  71. package/dist/hooks/composeAgentHooks.d.ts +14 -0
  72. package/dist/hooks/composeAgentHooks.d.ts.map +1 -0
  73. package/dist/hooks/composeAgentHooks.js +142 -0
  74. package/dist/hooks/composeAgentHooks.js.map +1 -0
  75. package/dist/hooks/index.d.ts +7 -0
  76. package/dist/hooks/index.d.ts.map +1 -0
  77. package/dist/hooks/index.js +6 -0
  78. package/dist/hooks/index.js.map +1 -0
  79. package/dist/hooks/types.d.ts +133 -0
  80. package/dist/hooks/types.d.ts.map +1 -0
  81. package/dist/hooks/types.js +6 -0
  82. package/dist/hooks/types.js.map +1 -0
  83. package/dist/index.d.ts +26 -0
  84. package/dist/index.d.ts.map +1 -0
  85. package/dist/index.js +25 -0
  86. package/dist/index.js.map +1 -0
  87. package/dist/model/ProviderRegistry.d.ts +62 -0
  88. package/dist/model/ProviderRegistry.d.ts.map +1 -0
  89. package/dist/model/ProviderRegistry.js +114 -0
  90. package/dist/model/ProviderRegistry.js.map +1 -0
  91. package/dist/model/providers/alibaba.d.ts +11 -0
  92. package/dist/model/providers/alibaba.d.ts.map +1 -0
  93. package/dist/model/providers/alibaba.js +16 -0
  94. package/dist/model/providers/alibaba.js.map +1 -0
  95. package/dist/model/providers/anthropic.d.ts +11 -0
  96. package/dist/model/providers/anthropic.d.ts.map +1 -0
  97. package/dist/model/providers/anthropic.js +16 -0
  98. package/dist/model/providers/anthropic.js.map +1 -0
  99. package/dist/model/providers/cohere.d.ts +11 -0
  100. package/dist/model/providers/cohere.d.ts.map +1 -0
  101. package/dist/model/providers/cohere.js +16 -0
  102. package/dist/model/providers/cohere.js.map +1 -0
  103. package/dist/model/providers/compatible.d.ts +11 -0
  104. package/dist/model/providers/compatible.d.ts.map +1 -0
  105. package/dist/model/providers/compatible.js +17 -0
  106. package/dist/model/providers/compatible.js.map +1 -0
  107. package/dist/model/providers/deepseek.d.ts +11 -0
  108. package/dist/model/providers/deepseek.d.ts.map +1 -0
  109. package/dist/model/providers/deepseek.js +16 -0
  110. package/dist/model/providers/deepseek.js.map +1 -0
  111. package/dist/model/providers/google.d.ts +11 -0
  112. package/dist/model/providers/google.d.ts.map +1 -0
  113. package/dist/model/providers/google.js +16 -0
  114. package/dist/model/providers/google.js.map +1 -0
  115. package/dist/model/providers/groq.d.ts +11 -0
  116. package/dist/model/providers/groq.d.ts.map +1 -0
  117. package/dist/model/providers/groq.js +16 -0
  118. package/dist/model/providers/groq.js.map +1 -0
  119. package/dist/model/providers/mistral.d.ts +11 -0
  120. package/dist/model/providers/mistral.d.ts.map +1 -0
  121. package/dist/model/providers/mistral.js +16 -0
  122. package/dist/model/providers/mistral.js.map +1 -0
  123. package/dist/model/providers/openai.d.ts +11 -0
  124. package/dist/model/providers/openai.d.ts.map +1 -0
  125. package/dist/model/providers/openai.js +16 -0
  126. package/dist/model/providers/openai.js.map +1 -0
  127. package/dist/model/providers/openrouter.d.ts +14 -0
  128. package/dist/model/providers/openrouter.d.ts.map +1 -0
  129. package/dist/model/providers/openrouter.js +20 -0
  130. package/dist/model/providers/openrouter.js.map +1 -0
  131. package/dist/model/providers/togetherai.d.ts +11 -0
  132. package/dist/model/providers/togetherai.d.ts.map +1 -0
  133. package/dist/model/providers/togetherai.js +16 -0
  134. package/dist/model/providers/togetherai.js.map +1 -0
  135. package/dist/model/providers/vercelGateway.d.ts +14 -0
  136. package/dist/model/providers/vercelGateway.d.ts.map +1 -0
  137. package/dist/model/providers/vercelGateway.js +19 -0
  138. package/dist/model/providers/vercelGateway.js.map +1 -0
  139. package/dist/model/providers/xai.d.ts +11 -0
  140. package/dist/model/providers/xai.d.ts.map +1 -0
  141. package/dist/model/providers/xai.js +16 -0
  142. package/dist/model/providers/xai.js.map +1 -0
  143. package/dist/model/resolveModel.d.ts +45 -0
  144. package/dist/model/resolveModel.d.ts.map +1 -0
  145. package/dist/model/resolveModel.js +109 -0
  146. package/dist/model/resolveModel.js.map +1 -0
  147. package/dist/model/types.d.ts +98 -0
  148. package/dist/model/types.d.ts.map +1 -0
  149. package/dist/model/types.js +6 -0
  150. package/dist/model/types.js.map +1 -0
  151. package/dist/runtime.d.ts +74 -0
  152. package/dist/runtime.d.ts.map +1 -0
  153. package/dist/runtime.js +41 -0
  154. package/dist/runtime.js.map +1 -0
  155. package/dist/storage/atomicFile.d.ts +28 -0
  156. package/dist/storage/atomicFile.d.ts.map +1 -0
  157. package/dist/storage/atomicFile.js +56 -0
  158. package/dist/storage/atomicFile.js.map +1 -0
  159. package/dist/storage/homeDirectory.d.ts +21 -0
  160. package/dist/storage/homeDirectory.d.ts.map +1 -0
  161. package/dist/storage/homeDirectory.js +36 -0
  162. package/dist/storage/homeDirectory.js.map +1 -0
  163. package/dist/storage/index.d.ts +10 -0
  164. package/dist/storage/index.d.ts.map +1 -0
  165. package/dist/storage/index.js +10 -0
  166. package/dist/storage/index.js.map +1 -0
  167. package/dist/storage/jsonl.d.ts +46 -0
  168. package/dist/storage/jsonl.d.ts.map +1 -0
  169. package/dist/storage/jsonl.js +121 -0
  170. package/dist/storage/jsonl.js.map +1 -0
  171. package/dist/storage/lock.d.ts +47 -0
  172. package/dist/storage/lock.d.ts.map +1 -0
  173. package/dist/storage/lock.js +126 -0
  174. package/dist/storage/lock.js.map +1 -0
  175. package/dist/storage/valueCodec.d.ts +68 -0
  176. package/dist/storage/valueCodec.d.ts.map +1 -0
  177. package/dist/storage/valueCodec.js +140 -0
  178. package/dist/storage/valueCodec.js.map +1 -0
  179. package/dist/tasks/TaskManager.d.ts +155 -0
  180. package/dist/tasks/TaskManager.d.ts.map +1 -0
  181. package/dist/tasks/TaskManager.js +774 -0
  182. package/dist/tasks/TaskManager.js.map +1 -0
  183. package/dist/tasks/index.d.ts +7 -0
  184. package/dist/tasks/index.d.ts.map +1 -0
  185. package/dist/tasks/index.js +6 -0
  186. package/dist/tasks/index.js.map +1 -0
  187. package/dist/tasks/types.d.ts +160 -0
  188. package/dist/tasks/types.d.ts.map +1 -0
  189. package/dist/tasks/types.js +8 -0
  190. package/dist/tasks/types.js.map +1 -0
  191. package/dist/threads/FileThreadStore.d.ts +118 -0
  192. package/dist/threads/FileThreadStore.d.ts.map +1 -0
  193. package/dist/threads/FileThreadStore.js +320 -0
  194. package/dist/threads/FileThreadStore.js.map +1 -0
  195. package/dist/threads/index.d.ts +7 -0
  196. package/dist/threads/index.d.ts.map +1 -0
  197. package/dist/threads/index.js +7 -0
  198. package/dist/threads/index.js.map +1 -0
  199. package/dist/threads/types.d.ts +230 -0
  200. package/dist/threads/types.d.ts.map +1 -0
  201. package/dist/threads/types.js +6 -0
  202. package/dist/threads/types.js.map +1 -0
  203. package/dist/tools/AgentTool.d.ts +38 -0
  204. package/dist/tools/AgentTool.d.ts.map +1 -0
  205. package/dist/tools/AgentTool.js +6 -0
  206. package/dist/tools/AgentTool.js.map +1 -0
  207. package/dist/tools/BashTool.d.ts +61 -0
  208. package/dist/tools/BashTool.d.ts.map +1 -0
  209. package/dist/tools/BashTool.js +142 -0
  210. package/dist/tools/BashTool.js.map +1 -0
  211. package/dist/tools/EditFileTool.d.ts +49 -0
  212. package/dist/tools/EditFileTool.d.ts.map +1 -0
  213. package/dist/tools/EditFileTool.js +114 -0
  214. package/dist/tools/EditFileTool.js.map +1 -0
  215. package/dist/tools/GlobTool.d.ts +48 -0
  216. package/dist/tools/GlobTool.d.ts.map +1 -0
  217. package/dist/tools/GlobTool.js +117 -0
  218. package/dist/tools/GlobTool.js.map +1 -0
  219. package/dist/tools/GrepTool.d.ts +73 -0
  220. package/dist/tools/GrepTool.d.ts.map +1 -0
  221. package/dist/tools/GrepTool.js +250 -0
  222. package/dist/tools/GrepTool.js.map +1 -0
  223. package/dist/tools/ReadFileTool.d.ts +51 -0
  224. package/dist/tools/ReadFileTool.d.ts.map +1 -0
  225. package/dist/tools/ReadFileTool.js +153 -0
  226. package/dist/tools/ReadFileTool.js.map +1 -0
  227. package/dist/tools/TaskManagerTool.d.ts +102 -0
  228. package/dist/tools/TaskManagerTool.d.ts.map +1 -0
  229. package/dist/tools/TaskManagerTool.js +130 -0
  230. package/dist/tools/TaskManagerTool.js.map +1 -0
  231. package/dist/tools/ToolExecutionContext.d.ts +61 -0
  232. package/dist/tools/ToolExecutionContext.d.ts.map +1 -0
  233. package/dist/tools/ToolExecutionContext.js +8 -0
  234. package/dist/tools/ToolExecutionContext.js.map +1 -0
  235. package/dist/tools/ToolRegistry.d.ts +82 -0
  236. package/dist/tools/ToolRegistry.d.ts.map +1 -0
  237. package/dist/tools/ToolRegistry.js +116 -0
  238. package/dist/tools/ToolRegistry.js.map +1 -0
  239. package/dist/tools/WriteFileTool.d.ts +46 -0
  240. package/dist/tools/WriteFileTool.d.ts.map +1 -0
  241. package/dist/tools/WriteFileTool.js +87 -0
  242. package/dist/tools/WriteFileTool.js.map +1 -0
  243. package/dist/tools/index.d.ts +17 -0
  244. package/dist/tools/index.d.ts.map +1 -0
  245. package/dist/tools/index.js +17 -0
  246. package/dist/tools/index.js.map +1 -0
  247. package/dist/tools/internal/bashEnvironment.d.ts +20 -0
  248. package/dist/tools/internal/bashEnvironment.d.ts.map +1 -0
  249. package/dist/tools/internal/bashEnvironment.js +65 -0
  250. package/dist/tools/internal/bashEnvironment.js.map +1 -0
  251. package/dist/tools/internal/pathGuard.d.ts +27 -0
  252. package/dist/tools/internal/pathGuard.d.ts.map +1 -0
  253. package/dist/tools/internal/pathGuard.js +99 -0
  254. package/dist/tools/internal/pathGuard.js.map +1 -0
  255. package/dist/tools/prompts.d.ts +33 -0
  256. package/dist/tools/prompts.d.ts.map +1 -0
  257. package/dist/tools/prompts.js +48 -0
  258. package/dist/tools/prompts.js.map +1 -0
  259. package/package.json +64 -4
@@ -0,0 +1,121 @@
1
+ /**
2
+ * @fileoverview Robust append-only JSONL parser and appender with torn-tail recovery and tagged value codec.
3
+ * @packageDocumentation
4
+ */
5
+ import { existsSync } from "node:fs";
6
+ import { appendFile, mkdir, readFile, truncate } from "node:fs/promises";
7
+ import path from "node:path";
8
+ import { decodeValue, encodeValue } from "./valueCodec.js";
9
+ /**
10
+ * Type guard for checking if a parsed JSON object is a JsonlEnvelope.
11
+ *
12
+ * @param value - Value to inspect.
13
+ * @returns True if value conforms to JsonlEnvelope shape.
14
+ */
15
+ export function isJsonlEnvelope(value) {
16
+ return (typeof value === "object" &&
17
+ value !== null &&
18
+ value.version === 1 &&
19
+ "value" in value &&
20
+ typeof value.value === "object" &&
21
+ value.value !== null &&
22
+ "type" in value.value);
23
+ }
24
+ /**
25
+ * Appends a record to a JSONL file with trailing newline using a versioned tagged envelope.
26
+ *
27
+ * Before appending, if the file contains a torn non-newline-terminated final line,
28
+ * it is verified and repaired under the caller's lock before appending. Truncate
29
+ * failures propagate fail-closed.
30
+ *
31
+ * @param filePath - The target JSONL file.
32
+ * @param record - Record or value to serialize and append.
33
+ * @throws {TypeError} If record contains non-serializable values (e.g. functions, cycles).
34
+ * @throws {Error} If torn-tail repair or write fails.
35
+ */
36
+ export async function appendJsonl(filePath, record) {
37
+ const absolutePath = path.resolve(filePath);
38
+ const parentDir = path.dirname(absolutePath);
39
+ if (!existsSync(parentDir)) {
40
+ await mkdir(parentDir, { recursive: true });
41
+ }
42
+ if (existsSync(absolutePath)) {
43
+ const existingContent = await readFile(absolutePath, "utf-8");
44
+ if (existingContent.length > 0 && !existingContent.endsWith("\n")) {
45
+ const lastNewlineIndex = existingContent.lastIndexOf("\n");
46
+ const tornLine = lastNewlineIndex === -1
47
+ ? existingContent
48
+ : existingContent.slice(lastNewlineIndex + 1);
49
+ let isMalformed = false;
50
+ try {
51
+ JSON.parse(tornLine);
52
+ }
53
+ catch {
54
+ isMalformed = true;
55
+ }
56
+ if (isMalformed) {
57
+ const validBytes = lastNewlineIndex === -1
58
+ ? 0
59
+ : Buffer.byteLength(existingContent.slice(0, lastNewlineIndex + 1), "utf-8");
60
+ await truncate(absolutePath, validBytes);
61
+ }
62
+ else {
63
+ await appendFile(absolutePath, "\n", "utf-8");
64
+ }
65
+ }
66
+ }
67
+ const envelope = {
68
+ version: 1,
69
+ value: encodeValue(record),
70
+ };
71
+ const line = JSON.stringify(envelope) + "\n";
72
+ await appendFile(absolutePath, line, "utf-8");
73
+ }
74
+ /**
75
+ * Reads all records from a JSONL file, recovering only from torn non-newline-terminated final lines.
76
+ *
77
+ * Malformed middle lines or newline-terminated malformed lines remain fatal and throw.
78
+ * Truncate failures propagate immediately. Legacy untagged raw JSON lines are parsed as fallback.
79
+ *
80
+ * @param filePath - The JSONL file to read.
81
+ * @returns Array of parsed records.
82
+ * @throws {Error} When encountering corrupted middle or newline-terminated records.
83
+ */
84
+ export async function readJsonl(filePath) {
85
+ const absolutePath = path.resolve(filePath);
86
+ if (!existsSync(absolutePath)) {
87
+ return [];
88
+ }
89
+ const content = await readFile(absolutePath, "utf-8");
90
+ if (!content.trim()) {
91
+ return [];
92
+ }
93
+ const lines = content.split("\n");
94
+ const records = [];
95
+ for (let i = 0; i < lines.length; i++) {
96
+ const rawLine = lines[i];
97
+ if (rawLine.trim().length === 0) {
98
+ continue;
99
+ }
100
+ try {
101
+ const parsed = JSON.parse(rawLine);
102
+ if (isJsonlEnvelope(parsed)) {
103
+ records.push(decodeValue(parsed.value));
104
+ }
105
+ else {
106
+ records.push(parsed);
107
+ }
108
+ }
109
+ catch (parseError) {
110
+ const isFinalNonTerminatedLine = i === lines.length - 1 && !content.endsWith("\n");
111
+ if (isFinalNonTerminatedLine) {
112
+ const validBytes = Buffer.byteLength(lines.slice(0, i).join("\n") + (i > 0 ? "\n" : ""), "utf-8");
113
+ await truncate(absolutePath, validBytes);
114
+ break;
115
+ }
116
+ throw new Error(`Corrupt JSONL entry at line ${i + 1} in "${filePath}": ${parseError.message}`);
117
+ }
118
+ }
119
+ return records;
120
+ }
121
+ //# sourceMappingURL=jsonl.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"jsonl.js","sources":["../../src/storage/jsonl.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,47 @@
1
+ /**
2
+ * @fileoverview File-based exclusive locking for multi-process and multi-worker coordination.
3
+ * @packageDocumentation
4
+ */
5
+ /**
6
+ * Payload written to the exclusive lock file for ownership validation.
7
+ */
8
+ export interface LockPayload {
9
+ /** Process identifier of the lock owner. */
10
+ readonly pid: number;
11
+ /** Unique cryptographically random token verifying ownership. */
12
+ readonly token: string;
13
+ /** Epoch timestamp in milliseconds when the lock was created. */
14
+ readonly createdAt: number;
15
+ }
16
+ /**
17
+ * Options for acquiring an exclusive file lock.
18
+ */
19
+ export interface FileLockOptions {
20
+ /**
21
+ * Maximum duration in milliseconds to wait before timing out.
22
+ * Defaults to 10,000ms.
23
+ */
24
+ readonly timeoutMs?: number;
25
+ /**
26
+ * Polling retry interval in milliseconds when contention (`EEXIST`) occurs.
27
+ * Defaults to 25ms.
28
+ */
29
+ readonly retryIntervalMs?: number;
30
+ }
31
+ /**
32
+ * Executes an operation while holding an exclusive file lock.
33
+ *
34
+ * Contention (`EEXIST`) is retried until `timeoutMs` expires. All non-contention
35
+ * errors (such as `EACCES`, `ENOSPC`, or `EIO`) fail immediately without retry.
36
+ * Ownership is verified on release using a cryptographic token. If both the inner
37
+ * operation and lock release encounter errors, they are preserved via `AggregateError`.
38
+ *
39
+ * @param lockPath - Path to the lock file.
40
+ * @param operation - Async function to run under the lock.
41
+ * @param optionsOrTimeout - Optional lock options or timeout in milliseconds (defaults to 10000ms).
42
+ * @returns Result of the executed operation.
43
+ * @throws {HernexLockError} When acquisition times out or token validation fails.
44
+ * @throws {AggregateError} When both the operation and lock release throw.
45
+ */
46
+ export declare function withFileLock<T>(lockPath: string, operation: () => Promise<T>, optionsOrTimeout?: number | FileLockOptions): Promise<T>;
47
+ //# sourceMappingURL=lock.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,126 @@
1
+ /**
2
+ * @fileoverview File-based exclusive locking for multi-process and multi-worker coordination.
3
+ * @packageDocumentation
4
+ */
5
+ import { randomUUID } from "node:crypto";
6
+ import { existsSync } from "node:fs";
7
+ import { mkdir, open, readFile, unlink } from "node:fs/promises";
8
+ import path from "node:path";
9
+ import { HernexLockError } from "../errors.js";
10
+ /**
11
+ * Executes an operation while holding an exclusive file lock.
12
+ *
13
+ * Contention (`EEXIST`) is retried until `timeoutMs` expires. All non-contention
14
+ * errors (such as `EACCES`, `ENOSPC`, or `EIO`) fail immediately without retry.
15
+ * Ownership is verified on release using a cryptographic token. If both the inner
16
+ * operation and lock release encounter errors, they are preserved via `AggregateError`.
17
+ *
18
+ * @param lockPath - Path to the lock file.
19
+ * @param operation - Async function to run under the lock.
20
+ * @param optionsOrTimeout - Optional lock options or timeout in milliseconds (defaults to 10000ms).
21
+ * @returns Result of the executed operation.
22
+ * @throws {HernexLockError} When acquisition times out or token validation fails.
23
+ * @throws {AggregateError} When both the operation and lock release throw.
24
+ */
25
+ export async function withFileLock(lockPath, operation, optionsOrTimeout) {
26
+ const timeoutMs = typeof optionsOrTimeout === "number"
27
+ ? optionsOrTimeout
28
+ : (optionsOrTimeout?.timeoutMs ?? 10000);
29
+ const retryIntervalMs = typeof optionsOrTimeout === "object" && optionsOrTimeout !== null
30
+ ? (optionsOrTimeout.retryIntervalMs ?? 25)
31
+ : 25;
32
+ const absoluteLock = path.resolve(lockPath);
33
+ const parentDir = path.dirname(absoluteLock);
34
+ if (!existsSync(parentDir)) {
35
+ await mkdir(parentDir, { recursive: true });
36
+ }
37
+ const token = randomUUID();
38
+ const payload = {
39
+ pid: process.pid,
40
+ token,
41
+ createdAt: Date.now(),
42
+ };
43
+ const startTime = Date.now();
44
+ let acquired = false;
45
+ while (!acquired) {
46
+ try {
47
+ const handle = await open(absoluteLock, "wx");
48
+ try {
49
+ await handle.writeFile(JSON.stringify(payload), "utf-8");
50
+ }
51
+ finally {
52
+ await handle.close();
53
+ }
54
+ acquired = true;
55
+ }
56
+ catch (error) {
57
+ const errno = error?.code;
58
+ if (errno !== "EEXIST") {
59
+ // Clean up partial lock file if open succeeded before writeFile threw
60
+ try {
61
+ await unlink(absoluteLock);
62
+ }
63
+ catch {
64
+ // Ignore unlink error on write failure cleanup
65
+ }
66
+ throw error;
67
+ }
68
+ if (Date.now() - startTime >= timeoutMs) {
69
+ throw new HernexLockError(`Failed to acquire lock at "${absoluteLock}" within ${timeoutMs}ms.`, absoluteLock);
70
+ }
71
+ await new Promise((resolve) => setTimeout(resolve, retryIntervalMs));
72
+ }
73
+ }
74
+ let operationError = null;
75
+ let operationResult;
76
+ try {
77
+ operationResult = await operation();
78
+ }
79
+ catch (error) {
80
+ operationError = error;
81
+ }
82
+ let releaseError = null;
83
+ try {
84
+ let content = null;
85
+ try {
86
+ content = await readFile(absoluteLock, "utf-8");
87
+ }
88
+ catch (readError) {
89
+ if (readError?.code !== "ENOENT") {
90
+ throw readError;
91
+ }
92
+ }
93
+ if (content !== null) {
94
+ let parsed = null;
95
+ try {
96
+ parsed = JSON.parse(content);
97
+ }
98
+ catch {
99
+ throw new HernexLockError(`Corrupted lock file at "${absoluteLock}": invalid JSON content.`, absoluteLock);
100
+ }
101
+ if (parsed?.token === token) {
102
+ await unlink(absoluteLock);
103
+ }
104
+ else {
105
+ throw new HernexLockError(`Lock token mismatch at "${absoluteLock}": expected "${token}", found "${parsed?.token ?? "unknown"}".`, absoluteLock);
106
+ }
107
+ }
108
+ else {
109
+ throw new HernexLockError(`Lock file at "${absoluteLock}" was unexpectedly removed before release.`, absoluteLock);
110
+ }
111
+ }
112
+ catch (error) {
113
+ releaseError = error;
114
+ }
115
+ if (operationError && releaseError) {
116
+ throw new AggregateError([operationError, releaseError], `Operation failed and lock release also failed at "${absoluteLock}".`);
117
+ }
118
+ if (operationError) {
119
+ throw operationError;
120
+ }
121
+ if (releaseError) {
122
+ throw releaseError;
123
+ }
124
+ return operationResult;
125
+ }
126
+ //# sourceMappingURL=lock.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lock.js","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,68 @@
1
+ /**
2
+ * @fileoverview Tagged lossless value codec for binary, URLs, and complex message payloads.
3
+ * @packageDocumentation
4
+ */
5
+ /**
6
+ * Tagged discriminated union of JSON-serializable representations for arbitrary JavaScript values.
7
+ */
8
+ export type EncodedValue = {
9
+ readonly type: "string";
10
+ readonly value: string;
11
+ } | {
12
+ readonly type: "number";
13
+ readonly value: number;
14
+ } | {
15
+ readonly type: "nan";
16
+ } | {
17
+ readonly type: "infinity";
18
+ } | {
19
+ readonly type: "negativeInfinity";
20
+ } | {
21
+ readonly type: "negativeZero";
22
+ } | {
23
+ readonly type: "boolean";
24
+ readonly value: boolean;
25
+ } | {
26
+ readonly type: "null";
27
+ } | {
28
+ readonly type: "undefined";
29
+ } | {
30
+ readonly type: "buffer";
31
+ readonly base64: string;
32
+ } | {
33
+ readonly type: "uint8array";
34
+ readonly base64: string;
35
+ } | {
36
+ readonly type: "url";
37
+ readonly href: string;
38
+ } | {
39
+ readonly type: "array";
40
+ readonly items: readonly EncodedValue[];
41
+ } | {
42
+ readonly type: "object";
43
+ readonly entries: Record<string, EncodedValue>;
44
+ } | {
45
+ readonly type: "binary";
46
+ readonly base64: string;
47
+ };
48
+ /**
49
+ * Encodes an arbitrary JavaScript value into a lossless tagged JSON-safe representation.
50
+ *
51
+ * 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.
54
+ *
55
+ * @param value - Any JavaScript value.
56
+ * @param seen - Internal Set of traversed objects to detect circular references.
57
+ * @returns Lossless tagged EncodedValue.
58
+ * @throws {TypeError} When value contains functions, symbols, bigint, circular references, or unsupported prototypes.
59
+ */
60
+ export declare function encodeValue(value: unknown, seen?: WeakSet<object>): EncodedValue;
61
+ /**
62
+ * Decodes a tagged EncodedValue back to its original JavaScript form.
63
+ *
64
+ * @param encoded - The EncodedValue.
65
+ * @returns Restored original JavaScript value.
66
+ */
67
+ export declare function decodeValue(encoded: EncodedValue): unknown;
68
+ //# sourceMappingURL=valueCodec.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,140 @@
1
+ /**
2
+ * @fileoverview Tagged lossless value codec for binary, URLs, and complex message payloads.
3
+ * @packageDocumentation
4
+ */
5
+ /**
6
+ * Encodes an arbitrary JavaScript value into a lossless tagged JSON-safe representation.
7
+ *
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.
11
+ *
12
+ * @param value - Any JavaScript value.
13
+ * @param seen - Internal Set of traversed objects to detect circular references.
14
+ * @returns Lossless tagged EncodedValue.
15
+ * @throws {TypeError} When value contains functions, symbols, bigint, circular references, or unsupported prototypes.
16
+ */
17
+ export function encodeValue(value, seen = new WeakSet()) {
18
+ if (value === null) {
19
+ return { type: "null" };
20
+ }
21
+ if (value === undefined) {
22
+ return { type: "undefined" };
23
+ }
24
+ if (typeof value === "string") {
25
+ return { type: "string", value };
26
+ }
27
+ if (typeof value === "boolean") {
28
+ return { type: "boolean", value };
29
+ }
30
+ if (typeof value === "number") {
31
+ if (Number.isNaN(value)) {
32
+ return { type: "nan" };
33
+ }
34
+ if (value === Infinity) {
35
+ return { type: "infinity" };
36
+ }
37
+ if (value === -Infinity) {
38
+ return { type: "negativeInfinity" };
39
+ }
40
+ if (Object.is(value, -0)) {
41
+ return { type: "negativeZero" };
42
+ }
43
+ return { type: "number", value };
44
+ }
45
+ if (typeof value === "bigint") {
46
+ throw new TypeError("Cannot encode value: bigint is not supported.");
47
+ }
48
+ if (typeof value === "symbol") {
49
+ throw new TypeError("Cannot encode value: symbols are not serializable.");
50
+ }
51
+ if (typeof value === "function") {
52
+ throw new TypeError("Cannot encode value: functions are not serializable.");
53
+ }
54
+ if (typeof value === "object") {
55
+ if (seen.has(value)) {
56
+ throw new TypeError("Cannot encode value: circular reference detected.");
57
+ }
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"}".`);
87
+ }
88
+ const entries = {};
89
+ for (const [k, v] of Object.entries(value)) {
90
+ entries[k] = encodeValue(v, seen);
91
+ }
92
+ return { type: "object", entries };
93
+ }
94
+ throw new TypeError(`Cannot encode value: unsupported type "${typeof value}".`);
95
+ }
96
+ /**
97
+ * Decodes a tagged EncodedValue back to its original JavaScript form.
98
+ *
99
+ * @param encoded - The EncodedValue.
100
+ * @returns Restored original JavaScript value.
101
+ */
102
+ export function decodeValue(encoded) {
103
+ switch (encoded.type) {
104
+ case "null":
105
+ return null;
106
+ case "undefined":
107
+ return undefined;
108
+ case "string":
109
+ case "number":
110
+ case "boolean":
111
+ return encoded.value;
112
+ case "nan":
113
+ return NaN;
114
+ case "infinity":
115
+ return Infinity;
116
+ case "negativeInfinity":
117
+ return -Infinity;
118
+ case "negativeZero":
119
+ return -0;
120
+ case "buffer":
121
+ case "binary":
122
+ return Buffer.from(encoded.base64, "base64");
123
+ case "uint8array": {
124
+ const buf = Buffer.from(encoded.base64, "base64");
125
+ return new Uint8Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
126
+ }
127
+ case "url":
128
+ return new URL(encoded.href);
129
+ case "array":
130
+ return encoded.items.map(decodeValue);
131
+ case "object": {
132
+ const result = {};
133
+ for (const [k, v] of Object.entries(encoded.entries)) {
134
+ result[k] = decodeValue(v);
135
+ }
136
+ return result;
137
+ }
138
+ }
139
+ }
140
+ //# sourceMappingURL=valueCodec.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"valueCodec.js","sources":["../../src/storage/valueCodec.ts"],"names":[],"mappings":"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"}