@openclaw/fs-safe 0.16.0 → 0.18.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 (705) hide show
  1. package/CHANGELOG.md +91 -0
  2. package/README.md +8 -1
  3. package/dist/absolute-path.d.ts +0 -1
  4. package/dist/absolute-path.js +2 -8
  5. package/dist/advanced.d.ts +2 -1
  6. package/dist/advanced.js +2 -0
  7. package/dist/archive-crc32.d.ts +0 -1
  8. package/dist/archive-deadline.d.ts +0 -1
  9. package/dist/archive-deadline.js +22 -23
  10. package/dist/archive-durability.d.ts +0 -1
  11. package/dist/archive-entry.d.ts +0 -1
  12. package/dist/archive-errors.d.ts +0 -1
  13. package/dist/archive-gzip-tail.d.ts +0 -1
  14. package/dist/archive-input.d.ts +0 -1
  15. package/dist/archive-kind.d.ts +0 -1
  16. package/dist/archive-limits.d.ts +0 -1
  17. package/dist/archive-merge.d.ts +3 -4
  18. package/dist/archive-merge.js +17 -7
  19. package/dist/archive-native.d.ts +3 -14
  20. package/dist/archive-native.js +46 -70
  21. package/dist/archive-options.d.ts +9 -2
  22. package/dist/archive-parser-errors.d.ts +0 -1
  23. package/dist/archive-parser.wasm +0 -0
  24. package/dist/archive-plan.d.ts +10 -1
  25. package/dist/archive-plan.js +31 -21
  26. package/dist/archive-policy.d.ts +0 -1
  27. package/dist/archive-read.d.ts +0 -1
  28. package/dist/archive-staging.d.ts +0 -1
  29. package/dist/archive-tar-inspect.d.ts +0 -1
  30. package/dist/archive-tar-stream.d.ts +0 -1
  31. package/dist/archive-tar-wasm.d.ts +0 -1
  32. package/dist/archive-tar.d.ts +0 -1
  33. package/dist/archive-zip-admission.d.ts +0 -1
  34. package/dist/archive-zip-count.d.ts +0 -1
  35. package/dist/archive-zip-count.js +21 -1
  36. package/dist/archive-zip-directory.d.ts +0 -1
  37. package/dist/archive-zip-directory.js +23 -1
  38. package/dist/archive-zip-entry.d.ts +0 -1
  39. package/dist/archive-zip-integrity.d.ts +0 -1
  40. package/dist/archive-zip-loader.d.ts +2 -1
  41. package/dist/archive-zip-loader.js +7 -0
  42. package/dist/archive-zip-manifest.d.ts +0 -1
  43. package/dist/archive-zip-names.d.ts +0 -1
  44. package/dist/archive-zip-names.js +7 -2
  45. package/dist/archive-zip-preflight.d.ts +0 -1
  46. package/dist/archive.d.ts +0 -1
  47. package/dist/archive.js +93 -164
  48. package/dist/async-lock.d.ts +0 -1
  49. package/dist/atomic.d.ts +0 -1
  50. package/dist/bounded-read-stream.d.ts +0 -1
  51. package/dist/bounded-read.d.ts +0 -1
  52. package/dist/byte-budget.d.ts +0 -1
  53. package/dist/byte-view.d.ts +2 -0
  54. package/dist/byte-view.js +13 -0
  55. package/dist/clone-metadata.d.ts +0 -1
  56. package/dist/config.d.ts +0 -1
  57. package/dist/containment.d.ts +0 -1
  58. package/dist/copy-file-input.d.ts +0 -1
  59. package/dist/copy-policy.d.ts +0 -1
  60. package/dist/copy-publication.d.ts +0 -1
  61. package/dist/copy-tree-portable.d.ts +0 -1
  62. package/dist/copy-tree-portable.js +9 -6
  63. package/dist/copy.d.ts +0 -1
  64. package/dist/copy.js +5 -5
  65. package/dist/create-directory.d.ts +0 -2
  66. package/dist/create-directory.js +3 -22
  67. package/dist/create-file-async.d.ts +0 -1
  68. package/dist/create-file.d.ts +0 -1
  69. package/dist/create-file.js +3 -14
  70. package/dist/create-owned-file.d.ts +0 -1
  71. package/dist/create.d.ts +1 -2
  72. package/dist/create.js +1 -1
  73. package/dist/creation-darwin.d.ts +0 -2
  74. package/dist/creation-darwin.js +0 -9
  75. package/dist/creation-file-state.d.ts +0 -1
  76. package/dist/creation-path.d.ts +2 -1
  77. package/dist/creation-path.js +12 -0
  78. package/dist/creation-permissions.d.ts +0 -1
  79. package/dist/creation-permissions.js +28 -38
  80. package/dist/deny-mutations.d.ts +2 -3
  81. package/dist/deny-mutations.js +55 -35
  82. package/dist/device-path.d.ts +0 -1
  83. package/dist/directory-durability.d.ts +6 -7
  84. package/dist/directory-entry-path.d.ts +0 -1
  85. package/dist/directory-guard.d.ts +2 -7
  86. package/dist/directory-guard.js +25 -56
  87. package/dist/directory-mode-node.d.ts +0 -1
  88. package/dist/directory-mode-owner.d.ts +0 -1
  89. package/dist/directory-receipt.d.ts +2 -3
  90. package/dist/directory-receipt.js +15 -19
  91. package/dist/durability.d.ts +0 -1
  92. package/dist/effective-uid.d.ts +0 -1
  93. package/dist/error-detail.d.ts +0 -1
  94. package/dist/errors.d.ts +0 -1
  95. package/dist/file-cleanup.d.ts +1 -1
  96. package/dist/file-cleanup.js +7 -4
  97. package/dist/file-contents.d.ts +5 -0
  98. package/dist/file-contents.js +40 -0
  99. package/dist/file-handle-transfer.d.ts +0 -1
  100. package/dist/file-hash.d.ts +0 -1
  101. package/dist/file-hash.js +186 -70
  102. package/dist/file-identity.d.ts +0 -1
  103. package/dist/file-lock-sync-acquisition.d.ts +22 -0
  104. package/dist/file-lock-sync-acquisition.js +98 -0
  105. package/dist/file-lock-sync-admission.d.ts +0 -2
  106. package/dist/file-lock-sync-admission.js +9 -48
  107. package/dist/file-lock-sync-root-acquire.d.ts +0 -1
  108. package/dist/file-lock-sync-root-acquire.js +35 -98
  109. package/dist/file-lock-sync-root-arbitration.d.ts +0 -1
  110. package/dist/file-lock-sync-root-held.d.ts +1 -3
  111. package/dist/file-lock-sync-root-held.js +7 -5
  112. package/dist/file-lock-sync-root-io.d.ts +0 -1
  113. package/dist/file-lock-sync-root-mutation.d.ts +4 -5
  114. package/dist/file-lock-sync-root-mutation.js +7 -9
  115. package/dist/file-lock-sync-root-options.d.ts +0 -1
  116. package/dist/file-lock-sync-root-registration.d.ts +0 -1
  117. package/dist/file-lock-sync-root.d.ts +1 -2
  118. package/dist/file-lock-sync-root.js +14 -87
  119. package/dist/file-lock-sync-stale-admission.d.ts +2 -7
  120. package/dist/file-lock-sync-stale-admission.js +24 -23
  121. package/dist/file-lock-sync.d.ts +0 -1
  122. package/dist/file-lock-sync.js +46 -128
  123. package/dist/file-lock.d.ts +0 -1
  124. package/dist/file-observation.d.ts +0 -1
  125. package/dist/file-store-boundary.d.ts +0 -2
  126. package/dist/file-store-boundary.js +6 -26
  127. package/dist/file-store-copy-source.d.ts +1 -2
  128. package/dist/file-store-copy-source.js +1 -1
  129. package/dist/file-store-limit.d.ts +1 -2
  130. package/dist/file-store-limit.js +2 -3
  131. package/dist/file-store-path.d.ts +0 -1
  132. package/dist/file-store-prune.d.ts +0 -1
  133. package/dist/file-store-sync-directory.d.ts +0 -1
  134. package/dist/file-store-sync-directory.js +194 -231
  135. package/dist/file-store-sync-write.d.ts +0 -1
  136. package/dist/file-store-sync-write.js +16 -26
  137. package/dist/file-store.d.ts +0 -1
  138. package/dist/file-store.js +6 -7
  139. package/dist/file-sync.d.ts +0 -1
  140. package/dist/filename.d.ts +0 -1
  141. package/dist/filename.js +1 -7
  142. package/dist/fs.d.ts +0 -1
  143. package/dist/guarded-mkdir.d.ts +0 -1
  144. package/dist/guarded-mkdir.js +6 -27
  145. package/dist/guarded-mutation.d.ts +0 -7
  146. package/dist/guarded-mutation.js +6 -11
  147. package/dist/guest-dispatch-python.d.ts +0 -1
  148. package/dist/guest-dispatch-python.js +41 -90
  149. package/dist/guest-native-python.d.ts +0 -1
  150. package/dist/guest.d.ts +0 -1
  151. package/dist/home-dir.d.ts +0 -1
  152. package/dist/index.d.ts +0 -1
  153. package/dist/install-path.d.ts +0 -1
  154. package/dist/install-path.js +2 -5
  155. package/dist/json-document-store.d.ts +0 -1
  156. package/dist/json-durable-queue-directory.d.ts +13 -1
  157. package/dist/json-durable-queue-directory.js +134 -0
  158. package/dist/json-durable-queue-ownership.d.ts +0 -1
  159. package/dist/json-durable-queue-ownership.js +43 -66
  160. package/dist/json-durable-queue-read.d.ts +0 -1
  161. package/dist/json-durable-queue-read.js +6 -6
  162. package/dist/json-durable-queue.d.ts +0 -1
  163. package/dist/json-durable-queue.js +17 -139
  164. package/dist/json-store.d.ts +0 -1
  165. package/dist/json-stringify.d.ts +0 -1
  166. package/dist/json.d.ts +0 -1
  167. package/dist/json.js +38 -90
  168. package/dist/local-file-access.d.ts +0 -1
  169. package/dist/local-file-access.js +3 -10
  170. package/dist/local-file-descriptor.d.ts +0 -1
  171. package/dist/local-roots.d.ts +0 -1
  172. package/dist/local-roots.js +19 -21
  173. package/dist/lock-config.d.ts +0 -1
  174. package/dist/move-path-cleanup.d.ts +5 -20
  175. package/dist/move-path-cleanup.js +57 -21
  176. package/dist/move-path-stage.d.ts +0 -1
  177. package/dist/move-path.d.ts +0 -1
  178. package/dist/move-path.js +62 -39
  179. package/dist/mutation-authority.d.ts +0 -1
  180. package/dist/native-binding.d.ts +0 -1
  181. package/dist/native-config.d.ts +0 -1
  182. package/dist/native-directory-observation.d.ts +0 -1
  183. package/dist/native-fallback-warning.d.ts +0 -1
  184. package/dist/native-operations.d.ts +1 -5
  185. package/dist/native-operations.js +2 -6
  186. package/dist/native-parent-admission.d.ts +0 -1
  187. package/dist/native-pinned-write-windows.d.ts +0 -1
  188. package/dist/native-pinned-write.d.ts +0 -1
  189. package/dist/native-pinned-write.js +4 -10
  190. package/dist/native-policy-directory-observation.d.ts +0 -1
  191. package/dist/native-policy-parent-windows.d.ts +0 -1
  192. package/dist/native-rename-outcome.d.ts +0 -1
  193. package/dist/native-staged-file.d.ts +17 -4
  194. package/dist/native-staged-file.js +63 -68
  195. package/dist/native.d.ts +0 -1
  196. package/dist/native.js +2 -2
  197. package/dist/opened-file-failure.d.ts +0 -1
  198. package/dist/opened-realpath.d.ts +0 -1
  199. package/dist/opened-realpath.js +11 -2
  200. package/dist/output.d.ts +0 -1
  201. package/dist/overwrite-file-handle.d.ts +0 -1
  202. package/dist/owner-dacl.d.ts +0 -1
  203. package/dist/path-case.d.ts +0 -1
  204. package/dist/path-policy.d.ts +0 -1
  205. package/dist/path-prefix.d.ts +0 -1
  206. package/dist/path-scope-lexical.d.ts +0 -1
  207. package/dist/path-segment-route.d.ts +0 -1
  208. package/dist/path-suffix-aliases.d.ts +0 -1
  209. package/dist/path.d.ts +0 -1
  210. package/dist/path.js +2 -1
  211. package/dist/permission-exec.d.ts +0 -1
  212. package/dist/permission-exec.js +19 -25
  213. package/dist/permissions-public.d.ts +0 -1
  214. package/dist/permissions-windows.d.ts +2 -10
  215. package/dist/permissions-windows.js +10 -30
  216. package/dist/permissions.d.ts +0 -1
  217. package/dist/permissions.js +11 -33
  218. package/dist/pinned-mutation-admission.d.ts +0 -1
  219. package/dist/pinned-mutation-observation.d.ts +0 -1
  220. package/dist/pinned-mutation-shared-route.d.ts +0 -1
  221. package/dist/pinned-open.d.ts +1 -1
  222. package/dist/pinned-open.js +1 -1
  223. package/dist/pinned-operation.d.ts +0 -1
  224. package/dist/pinned-write-input.d.ts +0 -1
  225. package/dist/pinned-write-input.js +11 -1
  226. package/dist/pinned-write-mode.d.ts +3 -4
  227. package/dist/pinned-write-mode.js +15 -8
  228. package/dist/pinned-write-staged.d.ts +0 -1
  229. package/dist/pinned-write-staged.js +10 -11
  230. package/dist/pinned-write-types.d.ts +9 -21
  231. package/dist/pinned-write.d.ts +0 -1
  232. package/dist/pinned-write.js +17 -13
  233. package/dist/positional-read.d.ts +0 -1
  234. package/dist/private-directory.d.ts +0 -1
  235. package/dist/private-producer-handoff-sync.d.ts +0 -1
  236. package/dist/private-producer-handoff-sync.js +9 -51
  237. package/dist/private-producer-handoff.d.ts +20 -1
  238. package/dist/private-producer-handoff.js +69 -46
  239. package/dist/private-temp-workspace.d.ts +0 -1
  240. package/dist/private-temp-workspace.js +11 -36
  241. package/dist/publish-copy-stage.d.ts +0 -1
  242. package/dist/publish-file-failure.d.ts +0 -1
  243. package/dist/publish-file.d.ts +2 -3
  244. package/dist/publish-file.js +56 -96
  245. package/dist/read-open-flags.d.ts +0 -1
  246. package/dist/read-opened-file.d.ts +0 -1
  247. package/dist/realpath.d.ts +0 -1
  248. package/dist/recursive-mkdir-path.d.ts +0 -1
  249. package/dist/regular-file.d.ts +0 -1
  250. package/dist/regular-file.js +107 -178
  251. package/dist/replace-directory.d.ts +0 -1
  252. package/dist/replace-file-copy-fallback.d.ts +0 -1
  253. package/dist/replace-file-copy-fallback.js +42 -29
  254. package/dist/replace-file-copy-source.d.ts +0 -1
  255. package/dist/replace-file-copy-source.js +19 -23
  256. package/dist/replace-file-descriptor.d.ts +0 -1
  257. package/dist/replace-file-descriptor.js +16 -17
  258. package/dist/replace-file-mode.d.ts +0 -1
  259. package/dist/replace-file-rename-policy.d.ts +0 -1
  260. package/dist/replace-file-temp-owner.d.ts +12 -13
  261. package/dist/replace-file-temp-owner.js +72 -91
  262. package/dist/replace-file.d.ts +0 -1
  263. package/dist/replace-file.js +9 -13
  264. package/dist/retained-directory-replacement.d.ts +0 -1
  265. package/dist/root-boundary.d.ts +0 -1
  266. package/dist/root-context.d.ts +0 -1
  267. package/dist/root-create-input.d.ts +0 -1
  268. package/dist/root-directory-creation.d.ts +0 -1
  269. package/dist/root-directory-list.d.ts +0 -1
  270. package/dist/root-directory-list.js +20 -3
  271. package/dist/root-directory.d.ts +0 -1
  272. package/dist/root-entries.d.ts +0 -1
  273. package/dist/root-errors.d.ts +0 -1
  274. package/dist/root-file-final-admission.d.ts +1 -2
  275. package/dist/root-file-final-admission.js +5 -2
  276. package/dist/root-file.d.ts +0 -1
  277. package/dist/root-file.js +3 -2
  278. package/dist/root-impl.d.ts +2 -10
  279. package/dist/root-impl.js +164 -111
  280. package/dist/root-move-noreplace.d.ts +2 -1
  281. package/dist/root-move-noreplace.js +2 -2
  282. package/dist/root-move-preflight.d.ts +0 -1
  283. package/dist/root-observed-path.d.ts +0 -1
  284. package/dist/root-options.d.ts +0 -1
  285. package/dist/root-path-errors.d.ts +0 -1
  286. package/dist/root-path-existing.d.ts +3 -1
  287. package/dist/root-path-existing.js +39 -18
  288. package/dist/root-path-observation.d.ts +0 -1
  289. package/dist/root-path-stat.d.ts +0 -1
  290. package/dist/root-path.d.ts +0 -1
  291. package/dist/root-path.js +60 -188
  292. package/dist/root-paths-lexical.d.ts +0 -1
  293. package/dist/root-paths.d.ts +0 -1
  294. package/dist/root-read-admission.d.ts +0 -1
  295. package/dist/root-read-admission.js +31 -39
  296. package/dist/root-remove-identity.d.ts +0 -1
  297. package/dist/root-remove-receipt.d.ts +0 -1
  298. package/dist/root-remove.d.ts +0 -1
  299. package/dist/root-remove.js +15 -1
  300. package/dist/root-symlink-policy.d.ts +0 -1
  301. package/dist/root-walk.d.ts +0 -1
  302. package/dist/root-write-admission.d.ts +0 -1
  303. package/dist/root-write-compatibility.d.ts +0 -1
  304. package/dist/root-write-complete-parent.d.ts +0 -1
  305. package/dist/root-write-lock-binding.d.ts +0 -1
  306. package/dist/root-write-mode.d.ts +0 -1
  307. package/dist/root-write-publication.d.ts +0 -1
  308. package/dist/root-write-verification.d.ts +0 -1
  309. package/dist/root.d.ts +0 -1
  310. package/dist/safe-path-segment.d.ts +1 -2
  311. package/dist/safe-path-segment.js +2 -5
  312. package/dist/secret-file.d.ts +0 -1
  313. package/dist/secret-file.js +7 -17
  314. package/dist/secret-read-async.d.ts +0 -1
  315. package/dist/secret-read-async.js +5 -5
  316. package/dist/secret-read-policy.d.ts +0 -1
  317. package/dist/secret.d.ts +0 -1
  318. package/dist/secure-file-windows.d.ts +0 -6
  319. package/dist/secure-file-windows.js +13 -28
  320. package/dist/secure-file.d.ts +0 -1
  321. package/dist/secure-file.js +9 -9
  322. package/dist/secure-temp-dir.d.ts +0 -1
  323. package/dist/secure-temp-repair.d.ts +0 -1
  324. package/dist/sibling-staged-file.d.ts +0 -1
  325. package/dist/sibling-staged-file.js +32 -39
  326. package/dist/sibling-temp.d.ts +0 -1
  327. package/dist/sidecar-lock-acquire.d.ts +1 -2
  328. package/dist/sidecar-lock-acquire.js +35 -58
  329. package/dist/sidecar-lock-admission-context.d.ts +0 -1
  330. package/dist/sidecar-lock-admission-parser.d.ts +0 -1
  331. package/dist/sidecar-lock-admission.d.ts +1 -5
  332. package/dist/sidecar-lock-admission.js +1 -7
  333. package/dist/sidecar-lock-handle.d.ts +3 -1
  334. package/dist/sidecar-lock-handle.js +6 -0
  335. package/dist/sidecar-lock-policy.d.ts +3 -1
  336. package/dist/sidecar-lock-policy.js +16 -0
  337. package/dist/sidecar-lock-reclaim.d.ts +1 -2
  338. package/dist/sidecar-lock-reclaim.js +11 -8
  339. package/dist/sidecar-lock-registration.d.ts +13 -0
  340. package/dist/sidecar-lock-registration.js +47 -0
  341. package/dist/sidecar-lock-root.d.ts +0 -1
  342. package/dist/sidecar-lock-stale-admission.d.ts +0 -1
  343. package/dist/sidecar-lock-target.d.ts +0 -1
  344. package/dist/sidecar-lock-types.d.ts +0 -1
  345. package/dist/sidecar-lock.d.ts +0 -1
  346. package/dist/sidecar-lock.js +19 -88
  347. package/dist/staged-directory.d.ts +2 -3
  348. package/dist/staged-file-settlement.d.ts +0 -1
  349. package/dist/staged-file-types.d.ts +0 -1
  350. package/dist/standalone-publication-path.d.ts +0 -1
  351. package/dist/stat-observation.d.ts +0 -1
  352. package/dist/store.d.ts +0 -1
  353. package/dist/strict-file-identity.d.ts +1 -2
  354. package/dist/strict-file-identity.js +9 -9
  355. package/dist/string-coerce.d.ts +0 -1
  356. package/dist/suppressed-error.d.ts +0 -1
  357. package/dist/symlink-parents.d.ts +0 -1
  358. package/dist/symlink-parents.js +2 -27
  359. package/dist/temp-cleanup.d.ts +0 -1
  360. package/dist/temp-target.d.ts +0 -1
  361. package/dist/temp-target.js +7 -46
  362. package/dist/temp-workspace-admission.d.ts +0 -8
  363. package/dist/temp-workspace-admission.js +0 -4
  364. package/dist/temp-workspace-child-admission.d.ts +0 -4
  365. package/dist/temp-workspace-child-admission.js +0 -12
  366. package/dist/temp-workspace-descriptor.d.ts +0 -6
  367. package/dist/temp-workspace-descriptor.js +0 -2
  368. package/dist/temp-workspace-identity.d.ts +0 -1
  369. package/dist/temp-workspace-owner.d.ts +1 -1
  370. package/dist/temp-workspace-owner.js +49 -26
  371. package/dist/temp-workspace-permissions.d.ts +0 -1
  372. package/dist/temp-workspace-types.d.ts +0 -1
  373. package/dist/temp.d.ts +0 -1
  374. package/dist/test-hooks.d.ts +0 -1
  375. package/dist/text-atomic.d.ts +0 -1
  376. package/dist/timing.d.ts +0 -1
  377. package/dist/trash.d.ts +0 -1
  378. package/dist/types.d.ts +0 -1
  379. package/dist/unicode-path.d.ts +0 -1
  380. package/dist/unicode-path.js +3 -0
  381. package/dist/walk.d.ts +0 -1
  382. package/dist/walk.js +4 -2
  383. package/dist/windows-command.d.ts +0 -1
  384. package/dist/windows-owner.d.ts +0 -1
  385. package/dist/windows-owner.js +4 -1
  386. package/dist/windows-path-alias.d.ts +0 -1
  387. package/dist/windows-path-alias.js +7 -43
  388. package/dist/windows-path-syntax.d.ts +5 -0
  389. package/dist/windows-path-syntax.js +21 -0
  390. package/dist/windows-security-command.d.ts +0 -1
  391. package/dist/windows-security-facts.d.ts +0 -1
  392. package/dist/write-file-handle.d.ts +7 -1
  393. package/dist/write-file-handle.js +23 -0
  394. package/dist/write-open-flags.d.ts +0 -1
  395. package/dist/write-open-flags.js +1 -8
  396. package/dist/write-queue.d.ts +0 -1
  397. package/dist/write-queue.js +1 -4
  398. package/docs/advanced.md +68 -1
  399. package/docs/archive.md +41 -2
  400. package/docs/atomic.md +43 -5
  401. package/docs/contributing.md +4 -0
  402. package/docs/copy.md +2 -0
  403. package/docs/creation.md +8 -4
  404. package/docs/durability.md +35 -0
  405. package/docs/file-contents.md +68 -0
  406. package/docs/json.md +5 -4
  407. package/docs/local-roots.md +2 -0
  408. package/docs/mutation-policy-proof.md +11 -7
  409. package/docs/native.md +9 -8
  410. package/docs/path.md +4 -4
  411. package/docs/permissions.md +6 -0
  412. package/docs/public-api.md +5 -0
  413. package/docs/quickstart.md +1 -1
  414. package/docs/reading.md +2 -2
  415. package/docs/regular-file.md +3 -0
  416. package/docs/root.md +19 -0
  417. package/docs/secret-file.md +4 -0
  418. package/docs/sidecar-lock.md +9 -1
  419. package/docs/staged-file.md +4 -3
  420. package/docs/store.md +3 -1
  421. package/docs/temp.md +4 -1
  422. package/docs/types.md +18 -2
  423. package/docs/walk.md +7 -0
  424. package/docs/writing.md +18 -5
  425. package/package.json +8 -9
  426. package/dist/absolute-path.d.ts.map +0 -1
  427. package/dist/advanced.d.ts.map +0 -1
  428. package/dist/archive-crc32.d.ts.map +0 -1
  429. package/dist/archive-deadline.d.ts.map +0 -1
  430. package/dist/archive-durability.d.ts.map +0 -1
  431. package/dist/archive-entry.d.ts.map +0 -1
  432. package/dist/archive-errors.d.ts.map +0 -1
  433. package/dist/archive-gzip-tail.d.ts.map +0 -1
  434. package/dist/archive-input.d.ts.map +0 -1
  435. package/dist/archive-kind.d.ts.map +0 -1
  436. package/dist/archive-limits.d.ts.map +0 -1
  437. package/dist/archive-merge.d.ts.map +0 -1
  438. package/dist/archive-native.d.ts.map +0 -1
  439. package/dist/archive-options.d.ts.map +0 -1
  440. package/dist/archive-parser-errors.d.ts.map +0 -1
  441. package/dist/archive-plan.d.ts.map +0 -1
  442. package/dist/archive-policy.d.ts.map +0 -1
  443. package/dist/archive-read.d.ts.map +0 -1
  444. package/dist/archive-staging.d.ts.map +0 -1
  445. package/dist/archive-tar-inspect.d.ts.map +0 -1
  446. package/dist/archive-tar-stream.d.ts.map +0 -1
  447. package/dist/archive-tar-wasm.d.ts.map +0 -1
  448. package/dist/archive-tar.d.ts.map +0 -1
  449. package/dist/archive-zip-admission.d.ts.map +0 -1
  450. package/dist/archive-zip-count.d.ts.map +0 -1
  451. package/dist/archive-zip-directory.d.ts.map +0 -1
  452. package/dist/archive-zip-entry.d.ts.map +0 -1
  453. package/dist/archive-zip-integrity.d.ts.map +0 -1
  454. package/dist/archive-zip-loader.d.ts.map +0 -1
  455. package/dist/archive-zip-manifest.d.ts.map +0 -1
  456. package/dist/archive-zip-names.d.ts.map +0 -1
  457. package/dist/archive-zip-preflight.d.ts.map +0 -1
  458. package/dist/archive.d.ts.map +0 -1
  459. package/dist/async-lock.d.ts.map +0 -1
  460. package/dist/atomic.d.ts.map +0 -1
  461. package/dist/bounded-read-stream.d.ts.map +0 -1
  462. package/dist/bounded-read.d.ts.map +0 -1
  463. package/dist/byte-budget.d.ts.map +0 -1
  464. package/dist/clone-metadata.d.ts.map +0 -1
  465. package/dist/config.d.ts.map +0 -1
  466. package/dist/containment.d.ts.map +0 -1
  467. package/dist/copy-file-input.d.ts.map +0 -1
  468. package/dist/copy-policy.d.ts.map +0 -1
  469. package/dist/copy-publication.d.ts.map +0 -1
  470. package/dist/copy-tree-portable.d.ts.map +0 -1
  471. package/dist/copy.d.ts.map +0 -1
  472. package/dist/create-directory.d.ts.map +0 -1
  473. package/dist/create-file-async.d.ts.map +0 -1
  474. package/dist/create-file.d.ts.map +0 -1
  475. package/dist/create-owned-file.d.ts.map +0 -1
  476. package/dist/create.d.ts.map +0 -1
  477. package/dist/creation-darwin.d.ts.map +0 -1
  478. package/dist/creation-file-state.d.ts.map +0 -1
  479. package/dist/creation-path.d.ts.map +0 -1
  480. package/dist/creation-permissions.d.ts.map +0 -1
  481. package/dist/deny-mutations.d.ts.map +0 -1
  482. package/dist/device-path.d.ts.map +0 -1
  483. package/dist/directory-durability.d.ts.map +0 -1
  484. package/dist/directory-entry-path.d.ts.map +0 -1
  485. package/dist/directory-guard.d.ts.map +0 -1
  486. package/dist/directory-mode-node.d.ts.map +0 -1
  487. package/dist/directory-mode-owner.d.ts.map +0 -1
  488. package/dist/directory-receipt.d.ts.map +0 -1
  489. package/dist/durability.d.ts.map +0 -1
  490. package/dist/effective-uid.d.ts.map +0 -1
  491. package/dist/error-detail.d.ts.map +0 -1
  492. package/dist/errors.d.ts.map +0 -1
  493. package/dist/file-cleanup.d.ts.map +0 -1
  494. package/dist/file-handle-transfer.d.ts.map +0 -1
  495. package/dist/file-hash.d.ts.map +0 -1
  496. package/dist/file-identity.d.ts.map +0 -1
  497. package/dist/file-lock-sync-admission.d.ts.map +0 -1
  498. package/dist/file-lock-sync-root-acquire.d.ts.map +0 -1
  499. package/dist/file-lock-sync-root-arbitration.d.ts.map +0 -1
  500. package/dist/file-lock-sync-root-held.d.ts.map +0 -1
  501. package/dist/file-lock-sync-root-io.d.ts.map +0 -1
  502. package/dist/file-lock-sync-root-mutation.d.ts.map +0 -1
  503. package/dist/file-lock-sync-root-options.d.ts.map +0 -1
  504. package/dist/file-lock-sync-root-registration.d.ts.map +0 -1
  505. package/dist/file-lock-sync-root.d.ts.map +0 -1
  506. package/dist/file-lock-sync-stale-admission.d.ts.map +0 -1
  507. package/dist/file-lock-sync.d.ts.map +0 -1
  508. package/dist/file-lock.d.ts.map +0 -1
  509. package/dist/file-observation.d.ts.map +0 -1
  510. package/dist/file-store-boundary.d.ts.map +0 -1
  511. package/dist/file-store-copy-source.d.ts.map +0 -1
  512. package/dist/file-store-limit.d.ts.map +0 -1
  513. package/dist/file-store-path.d.ts.map +0 -1
  514. package/dist/file-store-prune.d.ts.map +0 -1
  515. package/dist/file-store-sync-directory.d.ts.map +0 -1
  516. package/dist/file-store-sync-write.d.ts.map +0 -1
  517. package/dist/file-store.d.ts.map +0 -1
  518. package/dist/file-sync.d.ts.map +0 -1
  519. package/dist/filename.d.ts.map +0 -1
  520. package/dist/fs.d.ts.map +0 -1
  521. package/dist/guarded-mkdir.d.ts.map +0 -1
  522. package/dist/guarded-mutation.d.ts.map +0 -1
  523. package/dist/guest-dispatch-python.d.ts.map +0 -1
  524. package/dist/guest-native-python.d.ts.map +0 -1
  525. package/dist/guest.d.ts.map +0 -1
  526. package/dist/home-dir.d.ts.map +0 -1
  527. package/dist/index.d.ts.map +0 -1
  528. package/dist/install-path.d.ts.map +0 -1
  529. package/dist/json-document-store.d.ts.map +0 -1
  530. package/dist/json-durable-queue-directory.d.ts.map +0 -1
  531. package/dist/json-durable-queue-ownership.d.ts.map +0 -1
  532. package/dist/json-durable-queue-paths.d.ts +0 -11
  533. package/dist/json-durable-queue-paths.d.ts.map +0 -1
  534. package/dist/json-durable-queue-paths.js +0 -42
  535. package/dist/json-durable-queue-read.d.ts.map +0 -1
  536. package/dist/json-durable-queue.d.ts.map +0 -1
  537. package/dist/json-store.d.ts.map +0 -1
  538. package/dist/json-stringify.d.ts.map +0 -1
  539. package/dist/json.d.ts.map +0 -1
  540. package/dist/local-file-access.d.ts.map +0 -1
  541. package/dist/local-file-descriptor.d.ts.map +0 -1
  542. package/dist/local-roots.d.ts.map +0 -1
  543. package/dist/lock-config.d.ts.map +0 -1
  544. package/dist/move-path-cleanup.d.ts.map +0 -1
  545. package/dist/move-path-stage.d.ts.map +0 -1
  546. package/dist/move-path.d.ts.map +0 -1
  547. package/dist/mutation-authority.d.ts.map +0 -1
  548. package/dist/native-binding.d.ts.map +0 -1
  549. package/dist/native-config.d.ts.map +0 -1
  550. package/dist/native-directory-observation.d.ts.map +0 -1
  551. package/dist/native-fallback-warning.d.ts.map +0 -1
  552. package/dist/native-operations.d.ts.map +0 -1
  553. package/dist/native-parent-admission.d.ts.map +0 -1
  554. package/dist/native-pinned-write-windows.d.ts.map +0 -1
  555. package/dist/native-pinned-write.d.ts.map +0 -1
  556. package/dist/native-policy-directory-observation.d.ts.map +0 -1
  557. package/dist/native-policy-parent-windows.d.ts.map +0 -1
  558. package/dist/native-rename-outcome.d.ts.map +0 -1
  559. package/dist/native-staged-file.d.ts.map +0 -1
  560. package/dist/native.d.ts.map +0 -1
  561. package/dist/opened-file-failure.d.ts.map +0 -1
  562. package/dist/opened-realpath.d.ts.map +0 -1
  563. package/dist/output.d.ts.map +0 -1
  564. package/dist/overwrite-file-handle.d.ts.map +0 -1
  565. package/dist/owner-dacl.d.ts.map +0 -1
  566. package/dist/path-case.d.ts.map +0 -1
  567. package/dist/path-policy.d.ts.map +0 -1
  568. package/dist/path-prefix.d.ts.map +0 -1
  569. package/dist/path-scope-lexical.d.ts.map +0 -1
  570. package/dist/path-segment-route.d.ts.map +0 -1
  571. package/dist/path-suffix-aliases.d.ts.map +0 -1
  572. package/dist/path.d.ts.map +0 -1
  573. package/dist/permission-exec.d.ts.map +0 -1
  574. package/dist/permissions-public.d.ts.map +0 -1
  575. package/dist/permissions-windows.d.ts.map +0 -1
  576. package/dist/permissions.d.ts.map +0 -1
  577. package/dist/pinned-mutation-admission.d.ts.map +0 -1
  578. package/dist/pinned-mutation-observation.d.ts.map +0 -1
  579. package/dist/pinned-mutation-shared-route.d.ts.map +0 -1
  580. package/dist/pinned-open.d.ts.map +0 -1
  581. package/dist/pinned-operation.d.ts.map +0 -1
  582. package/dist/pinned-write-input.d.ts.map +0 -1
  583. package/dist/pinned-write-mode.d.ts.map +0 -1
  584. package/dist/pinned-write-staged.d.ts.map +0 -1
  585. package/dist/pinned-write-types.d.ts.map +0 -1
  586. package/dist/pinned-write.d.ts.map +0 -1
  587. package/dist/positional-read.d.ts.map +0 -1
  588. package/dist/private-directory.d.ts.map +0 -1
  589. package/dist/private-producer-handoff-sync.d.ts.map +0 -1
  590. package/dist/private-producer-handoff.d.ts.map +0 -1
  591. package/dist/private-temp-workspace.d.ts.map +0 -1
  592. package/dist/publish-copy-stage.d.ts.map +0 -1
  593. package/dist/publish-file-failure.d.ts.map +0 -1
  594. package/dist/publish-file.d.ts.map +0 -1
  595. package/dist/read-open-flags.d.ts.map +0 -1
  596. package/dist/read-opened-file.d.ts.map +0 -1
  597. package/dist/realpath.d.ts.map +0 -1
  598. package/dist/recursive-mkdir-path.d.ts.map +0 -1
  599. package/dist/regular-file.d.ts.map +0 -1
  600. package/dist/replace-directory.d.ts.map +0 -1
  601. package/dist/replace-file-copy-fallback.d.ts.map +0 -1
  602. package/dist/replace-file-copy-source.d.ts.map +0 -1
  603. package/dist/replace-file-descriptor.d.ts.map +0 -1
  604. package/dist/replace-file-mode.d.ts.map +0 -1
  605. package/dist/replace-file-rename-policy.d.ts.map +0 -1
  606. package/dist/replace-file-temp-owner.d.ts.map +0 -1
  607. package/dist/replace-file.d.ts.map +0 -1
  608. package/dist/retained-directory-replacement.d.ts.map +0 -1
  609. package/dist/root-boundary.d.ts.map +0 -1
  610. package/dist/root-context.d.ts.map +0 -1
  611. package/dist/root-create-input.d.ts.map +0 -1
  612. package/dist/root-directory-creation.d.ts.map +0 -1
  613. package/dist/root-directory-list.d.ts.map +0 -1
  614. package/dist/root-directory.d.ts.map +0 -1
  615. package/dist/root-entries.d.ts.map +0 -1
  616. package/dist/root-errors.d.ts.map +0 -1
  617. package/dist/root-file-final-admission.d.ts.map +0 -1
  618. package/dist/root-file.d.ts.map +0 -1
  619. package/dist/root-impl.d.ts.map +0 -1
  620. package/dist/root-move-noreplace.d.ts.map +0 -1
  621. package/dist/root-move-preflight.d.ts.map +0 -1
  622. package/dist/root-observed-path.d.ts.map +0 -1
  623. package/dist/root-options.d.ts.map +0 -1
  624. package/dist/root-path-errors.d.ts.map +0 -1
  625. package/dist/root-path-existing.d.ts.map +0 -1
  626. package/dist/root-path-observation.d.ts.map +0 -1
  627. package/dist/root-path-stat.d.ts.map +0 -1
  628. package/dist/root-path-symlink.d.ts +0 -7
  629. package/dist/root-path-symlink.d.ts.map +0 -1
  630. package/dist/root-path-symlink.js +0 -55
  631. package/dist/root-path.d.ts.map +0 -1
  632. package/dist/root-paths-lexical.d.ts.map +0 -1
  633. package/dist/root-paths.d.ts.map +0 -1
  634. package/dist/root-read-admission.d.ts.map +0 -1
  635. package/dist/root-remove-identity.d.ts.map +0 -1
  636. package/dist/root-remove-receipt.d.ts.map +0 -1
  637. package/dist/root-remove.d.ts.map +0 -1
  638. package/dist/root-symlink-policy.d.ts.map +0 -1
  639. package/dist/root-walk.d.ts.map +0 -1
  640. package/dist/root-write-admission.d.ts.map +0 -1
  641. package/dist/root-write-compatibility.d.ts.map +0 -1
  642. package/dist/root-write-complete-parent.d.ts.map +0 -1
  643. package/dist/root-write-lock-binding.d.ts.map +0 -1
  644. package/dist/root-write-mode.d.ts.map +0 -1
  645. package/dist/root-write-publication.d.ts.map +0 -1
  646. package/dist/root-write-verification.d.ts.map +0 -1
  647. package/dist/root.d.ts.map +0 -1
  648. package/dist/safe-path-segment.d.ts.map +0 -1
  649. package/dist/secret-file.d.ts.map +0 -1
  650. package/dist/secret-read-async.d.ts.map +0 -1
  651. package/dist/secret-read-policy.d.ts.map +0 -1
  652. package/dist/secret.d.ts.map +0 -1
  653. package/dist/secure-file-windows.d.ts.map +0 -1
  654. package/dist/secure-file.d.ts.map +0 -1
  655. package/dist/secure-temp-dir.d.ts.map +0 -1
  656. package/dist/secure-temp-repair.d.ts.map +0 -1
  657. package/dist/sibling-staged-file.d.ts.map +0 -1
  658. package/dist/sibling-temp.d.ts.map +0 -1
  659. package/dist/sidecar-lock-acquire.d.ts.map +0 -1
  660. package/dist/sidecar-lock-admission-context.d.ts.map +0 -1
  661. package/dist/sidecar-lock-admission-parser.d.ts.map +0 -1
  662. package/dist/sidecar-lock-admission.d.ts.map +0 -1
  663. package/dist/sidecar-lock-handle.d.ts.map +0 -1
  664. package/dist/sidecar-lock-policy.d.ts.map +0 -1
  665. package/dist/sidecar-lock-reclaim.d.ts.map +0 -1
  666. package/dist/sidecar-lock-root.d.ts.map +0 -1
  667. package/dist/sidecar-lock-stale-admission.d.ts.map +0 -1
  668. package/dist/sidecar-lock-target.d.ts.map +0 -1
  669. package/dist/sidecar-lock-types.d.ts.map +0 -1
  670. package/dist/sidecar-lock.d.ts.map +0 -1
  671. package/dist/staged-directory.d.ts.map +0 -1
  672. package/dist/staged-file-settlement.d.ts.map +0 -1
  673. package/dist/staged-file-types.d.ts.map +0 -1
  674. package/dist/standalone-publication-path.d.ts.map +0 -1
  675. package/dist/stat-observation.d.ts.map +0 -1
  676. package/dist/store.d.ts.map +0 -1
  677. package/dist/strict-file-identity.d.ts.map +0 -1
  678. package/dist/string-coerce.d.ts.map +0 -1
  679. package/dist/suppressed-error.d.ts.map +0 -1
  680. package/dist/symlink-parents.d.ts.map +0 -1
  681. package/dist/temp-cleanup.d.ts.map +0 -1
  682. package/dist/temp-target.d.ts.map +0 -1
  683. package/dist/temp-workspace-admission.d.ts.map +0 -1
  684. package/dist/temp-workspace-child-admission.d.ts.map +0 -1
  685. package/dist/temp-workspace-descriptor.d.ts.map +0 -1
  686. package/dist/temp-workspace-identity.d.ts.map +0 -1
  687. package/dist/temp-workspace-owner.d.ts.map +0 -1
  688. package/dist/temp-workspace-permissions.d.ts.map +0 -1
  689. package/dist/temp-workspace-types.d.ts.map +0 -1
  690. package/dist/temp.d.ts.map +0 -1
  691. package/dist/test-hooks.d.ts.map +0 -1
  692. package/dist/text-atomic.d.ts.map +0 -1
  693. package/dist/timing.d.ts.map +0 -1
  694. package/dist/trash.d.ts.map +0 -1
  695. package/dist/types.d.ts.map +0 -1
  696. package/dist/unicode-path.d.ts.map +0 -1
  697. package/dist/walk.d.ts.map +0 -1
  698. package/dist/windows-command.d.ts.map +0 -1
  699. package/dist/windows-owner.d.ts.map +0 -1
  700. package/dist/windows-path-alias.d.ts.map +0 -1
  701. package/dist/windows-security-command.d.ts.map +0 -1
  702. package/dist/windows-security-facts.d.ts.map +0 -1
  703. package/dist/write-file-handle.d.ts.map +0 -1
  704. package/dist/write-open-flags.d.ts.map +0 -1
  705. package/dist/write-queue.d.ts.map +0 -1
@@ -165,14 +165,62 @@ async function openProducerSource(params, identity, links = 1n) {
165
165
  }
166
166
  return fallback;
167
167
  }
168
- function inspectHandoff(params, handle, identity, state, links) {
169
- assertParents(params);
170
- const opened = inspectSourceDescriptor(handle, identity, links);
171
- if (state.cleanup !== "removed") {
172
- inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, links, "isolated producer path");
168
+ export class FileHandoff {
169
+ paths;
170
+ identity;
171
+ createdLabels;
172
+ siblingOwned = false;
173
+ publication = "not-published";
174
+ cleanup = "preserved";
175
+ closeFailed = false;
176
+ constructor(paths, identity, createdLabels = false) {
177
+ this.paths = paths;
178
+ this.identity = identity;
179
+ this.createdLabels = createdLabels;
180
+ }
181
+ inspect(owner, links) {
182
+ assertParents(this.paths);
183
+ const opened = inspectLinkedFile(() => fsSync.fstatSync(owner.fd, { bigint: true }), this.identity, links, this.createdLabels ? "created file descriptor" : "isolated producer descriptor");
184
+ if (this.cleanup !== "removed") {
185
+ inspectLinkedFile(() => fsSync.lstatSync(this.paths.sourcePath, { bigint: true }), this.identity, links, this.createdLabels ? "created file stage" : "isolated producer path");
186
+ }
187
+ const named = this.publication === "published"
188
+ ? inspectLinkedFile(() => fsSync.lstatSync(this.paths.targetPath, { bigint: true }), this.identity, links, this.createdLabels ? "created file destination" : "isolated producer sibling")
189
+ : undefined;
190
+ return { opened, named };
191
+ }
192
+ publish() {
193
+ this.publication = "indeterminate";
194
+ try {
195
+ fsSync.linkSync(this.paths.sourcePath, this.paths.targetPath);
196
+ }
197
+ catch (error) {
198
+ const normalized = normalizeLinkError(error);
199
+ if (normalized instanceof FsSafeError &&
200
+ (normalized.code === "already-exists" || normalized.code === "helper-unavailable")) {
201
+ this.publication = "not-published";
202
+ }
203
+ throw normalized;
204
+ }
205
+ this.publication = "published";
206
+ }
207
+ retireSource() {
208
+ this.cleanup = "failed";
209
+ fsSync.unlinkSync(this.paths.sourcePath);
210
+ this.cleanup = "removed";
211
+ }
212
+ failure(failures, aggregateMessage) {
213
+ const primary = failures[0];
214
+ // Collision-as-no-op callers must still observe a failed settlement.
215
+ return new FsSafeError(this.closeFailed || failures.length > 1 ? "helper-failed" : primary instanceof FsSafeError ? primary.code : "helper-failed", "created file publication failed", {
216
+ cause: failures.length === 1 ? primary : new AggregateError(failures, aggregateMessage),
217
+ details: {
218
+ publication: { status: this.publication }, cleanup: this.cleanup,
219
+ resources: this.closeFailed ? "close-failed" : "closed",
220
+ path: this.paths.targetPath, dev: this.identity.dev, ino: this.identity.ino,
221
+ },
222
+ });
173
223
  }
174
- const named = state.publication === "published" ? inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, links, "isolated producer sibling") : undefined;
175
- return { opened, named };
176
224
  }
177
225
  async function handoffFile(params) {
178
226
  const created = "source" in params ? params : undefined;
@@ -186,9 +234,7 @@ async function handoffFile(params) {
186
234
  const owners = new Set(handle ? [handle] : []);
187
235
  const failures = [];
188
236
  let unregister;
189
- const state = {
190
- siblingOwned: false, publication: "not-published", cleanup: "preserved", closeFailed: false,
191
- };
237
+ const state = new FileHandoff(params, identity);
192
238
  async function close(owned) {
193
239
  // Final creation consumes its pin before close can release and recycle it.
194
240
  // Legacy temporary handoff retains its historical FileHandle close retry.
@@ -209,7 +255,7 @@ async function handoffFile(params) {
209
255
  handle = await openProducerSource({ ...params, readWrite: "readWrite" in params && params.readWrite }, identity);
210
256
  owners.add(handle);
211
257
  }
212
- inspectHandoff(params, handle, identity, state, 1n);
258
+ state.inspect(handle, 1n);
213
259
  if (created?.verifyDescriptor)
214
260
  await created.verifyDescriptor(handle.fd, params.sourcePath, 1);
215
261
  if (!created) {
@@ -220,20 +266,8 @@ async function handoffFile(params) {
220
266
  });
221
267
  }
222
268
  assertSynchronousCallbackResult(created?.assertBeforeMutation?.(), "assertBeforeMutation");
223
- inspectHandoff(params, handle, identity, state, 1n);
224
- state.publication = "indeterminate";
225
- try {
226
- fsSync.linkSync(params.sourcePath, params.targetPath);
227
- }
228
- catch (error) {
229
- const normalized = normalizeLinkError(error);
230
- if (normalized instanceof FsSafeError &&
231
- (normalized.code === "already-exists" || normalized.code === "helper-unavailable")) {
232
- state.publication = "not-published";
233
- }
234
- throw normalized;
235
- }
236
- state.publication = "published";
269
+ state.inspect(handle, 1n);
270
+ state.publish();
237
271
  state.siblingOwned = !created;
238
272
  try {
239
273
  assertSynchronousCallbackResult(created?.onPublished?.(), "onPublished");
@@ -241,7 +275,7 @@ async function handoffFile(params) {
241
275
  catch (error) {
242
276
  failures.push(error);
243
277
  }
244
- inspectHandoff(params, handle, identity, state, 2n);
278
+ state.inspect(handle, 2n);
245
279
  if (process.platform === "win32") {
246
280
  // Legacy Windows unlink retains a delete-pending name until handles
247
281
  // opened through that name close. Transfer the pin before retiring it.
@@ -250,26 +284,24 @@ async function handoffFile(params) {
250
284
  : await openProducerSource({ ...params, sourcePath: params.targetPath,
251
285
  readWrite: "readWrite" in params && params.readWrite }, identity, 2n);
252
286
  owners.add(sibling);
253
- inspectHandoff(params, sibling, identity, state, 2n);
287
+ state.inspect(sibling, 2n);
254
288
  if (created?.verifyDescriptor)
255
289
  await created.verifyDescriptor(sibling.fd, params.targetPath, 2);
256
- inspectHandoff(params, sibling, identity, state, 2n);
290
+ state.inspect(sibling, 2n);
257
291
  inspectSourceDescriptor(handle, identity, 2n);
258
292
  await close(handle);
259
293
  handle = sibling;
260
294
  // The old handle's close yielded; both names must still be ours.
261
- inspectHandoff(params, handle, identity, state, 2n);
295
+ state.inspect(handle, 2n);
262
296
  }
263
297
  if (created?.verifyDescriptor)
264
298
  await created.verifyDescriptor(handle.fd, process.platform === "win32" ? params.targetPath : params.sourcePath, 2);
265
299
  assertSynchronousCallbackResult(created?.assertBeforeMutation?.(), "assertBeforeMutation");
266
- inspectHandoff(params, handle, identity, state, 2n);
267
- state.cleanup = "failed";
268
- fsSync.unlinkSync(params.sourcePath);
269
- state.cleanup = "removed";
300
+ state.inspect(handle, 2n);
301
+ state.retireSource();
270
302
  if (created?.verifyDescriptor)
271
303
  await created.verifyDescriptor(handle.fd, params.targetPath, 1);
272
- const { opened, named } = inspectHandoff(params, handle, identity, state, 1n);
304
+ const { opened, named } = state.inspect(handle, 1n);
273
305
  const originalMode = identity.mode & 511n;
274
306
  if (!created && process.platform === "win32" && (originalMode & 128n) === 0n &&
275
307
  ((opened.mode & 511n) !== originalMode || (named.mode & 511n) !== originalMode)) {
@@ -277,7 +309,7 @@ async function handoffFile(params) {
277
309
  // admitted sibling inode, without reopening or chmodding its pathname.
278
310
  assertParents(params);
279
311
  fsSync.fchmodSync(handle.fd, Number(originalMode));
280
- const restored = inspectHandoff(params, handle, identity, state, 1n);
312
+ const restored = state.inspect(handle, 1n);
281
313
  if ((restored.opened.mode & 511n) !== originalMode || (restored.named.mode & 511n) !== originalMode) {
282
314
  throw pathMismatch("isolated producer read-only mode could not be restored");
283
315
  }
@@ -314,18 +346,9 @@ async function handoffFile(params) {
314
346
  failures.push(error);
315
347
  }
316
348
  }
317
- const primary = failures[0];
318
- const cause = combinedFailure(primary, failures.slice(1));
319
349
  if (!created)
320
- throw cause;
321
- throw new FsSafeError(state.closeFailed || failures.length > 1 ? "helper-failed" : primary instanceof FsSafeError ? primary.code : "helper-failed", "created file publication failed", {
322
- cause,
323
- details: {
324
- publication: { status: state.publication }, cleanup: state.cleanup,
325
- resources: state.closeFailed ? "close-failed" : "closed",
326
- path: params.targetPath, dev: identity.dev, ino: identity.ino,
327
- },
328
- });
350
+ throw combinedFailure(failures[0], failures.slice(1));
351
+ throw state.failure(failures, "isolated producer handoff and settlement failed");
329
352
  }
330
353
  export function handoffPrivateProducerFile(params) {
331
354
  return handoffFile(params);
@@ -5,4 +5,3 @@ export declare function tempWorkspace(options: TempWorkspaceOptions): Promise<Te
5
5
  export declare function withTempWorkspace<T>(options: TempWorkspaceOptions, run: (workspace: TempWorkspace) => Promise<T>): Promise<T>;
6
6
  export declare function tempWorkspaceSync(options: TempWorkspaceOptions): TempWorkspaceSync;
7
7
  export declare function withTempWorkspaceSync<T>(options: TempWorkspaceOptions, run: (workspace: TempWorkspaceSync) => T): T;
8
- //# sourceMappingURL=private-temp-workspace.d.ts.map
@@ -9,10 +9,10 @@ import { inspectDirectoryIdentitySync } from "./directory-guard.js";
9
9
  import { throwFsSafeReadError } from "./root-errors.js";
10
10
  import { matchRootFileOpenFailure, openRootFileSync, } from "./root-file.js";
11
11
  import { registerTempPathForExit, } from "./temp-cleanup.js";
12
- import { TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner, } from "./temp-workspace-owner.js";
12
+ import { TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner, throwTempWorkspaceCreationFailure, } from "./temp-workspace-owner.js";
13
13
  import { assertNoWindowsPathAlias, hasWindowsPathAlias, } from "./windows-path-alias.js";
14
14
  import { TempWorkspaceRetainedChild } from "./temp-workspace-descriptor.js";
15
- import { admitRetainedTempWorkspaceChild, admitRetainedTempWorkspaceChildSync, validateInitialTempWorkspaceChild, } from "./temp-workspace-child-admission.js";
15
+ import { validateInitialTempWorkspaceChild } from "./temp-workspace-child-admission.js";
16
16
  import { admitTempWorkspaceRoot, admitTempWorkspaceRootSync, } from "./temp-workspace-admission.js";
17
17
  import { validateTempWorkspaceDirMode } from "./temp-workspace-permissions.js";
18
18
  function resolveTempWorkspaceCleanupSafety(value) {
@@ -125,36 +125,6 @@ function tempWorkspaceChildPrefix(root, options, scopedPrefix) {
125
125
  assertNoWindowsPathAlias(childPrefix, "filesystem", "temp workspace path uses a Windows filesystem namespace alias");
126
126
  return childPrefix;
127
127
  }
128
- function throwTempWorkspaceCreationFailure(error, retainedChild, capability, owner) {
129
- try {
130
- if (owner)
131
- owner.cleanupSync();
132
- else {
133
- const closeErrors = [];
134
- try {
135
- retainedChild?.close();
136
- }
137
- catch (closeError) {
138
- closeErrors.push(closeError);
139
- }
140
- try {
141
- capability.close();
142
- }
143
- catch (closeError) {
144
- closeErrors.push(closeError);
145
- }
146
- if (closeErrors.length === 1)
147
- throw closeErrors[0];
148
- if (closeErrors.length > 1) {
149
- throw new AggregateError(closeErrors, "temp workspace admission descriptor close failed");
150
- }
151
- }
152
- }
153
- catch (cleanupError) {
154
- throw new AggregateError([error, cleanupError], "temp workspace creation and cleanup both failed");
155
- }
156
- throw error;
157
- }
158
128
  function registerTempWorkspace(dir, retainedChild, capability, admission, dirMode) {
159
129
  let owner;
160
130
  let stat;
@@ -201,9 +171,9 @@ async function createTempWorkspace(options, scopedPrefix = false) {
201
171
  // Retain while the child still has its private creation mode so an
202
172
  // explicit dirMode such as 0 cannot make identity descriptor acquisition fail.
203
173
  retainedChild = TempWorkspaceRetainedChild.retain(dir, stat);
204
- const modeInitialization = admitRetainedTempWorkspaceChild(retainedChild, needsModeInitialization, admission, dirMode);
205
- if (modeInitialization)
206
- await modeInitialization;
174
+ if (needsModeInitialization) {
175
+ await retainedChild.initializeMode(dirMode, admission.ownerUid, admission.assertCurrent);
176
+ }
207
177
  }
208
178
  catch (error) {
209
179
  throwTempWorkspaceCreationFailure(error, retainedChild, capability);
@@ -294,7 +264,12 @@ function createTempWorkspaceSync(options, scopedPrefix = false) {
294
264
  }
295
265
  const needsModeInitialization = validateInitialTempWorkspaceChild(stat, admission.ownerUid, dirMode);
296
266
  retainedChild ??= TempWorkspaceRetainedChild.retain(dir, stat);
297
- admitRetainedTempWorkspaceChildSync(retainedChild, needsModeInitialization, admission, dirMode);
267
+ if (needsModeInitialization) {
268
+ retainedChild.initializeModeSync(dirMode, admission.ownerUid, admission.assertCurrent);
269
+ }
270
+ else {
271
+ retainedChild.discardInitialReceipt();
272
+ }
298
273
  }
299
274
  catch (error) {
300
275
  throwTempWorkspaceCreationFailure(error, retainedChild, capability);
@@ -11,4 +11,3 @@ export declare function publishCopyStage(params: {
11
11
  onPublicationAttempt?: () => void;
12
12
  onPublished?: (identity: PublishedWriteIdentity) => void;
13
13
  }): void;
14
- //# sourceMappingURL=publish-copy-stage.d.ts.map
@@ -25,4 +25,3 @@ export type PublishFailureState = {
25
25
  export declare function rememberCreatedTarget(state: PublishFailureState, identity: FileIdentityStat, phase: PublishFileExclusiveFailurePhase): void;
26
26
  export declare function publicationFailure(error: unknown, state: PublishFailureState, cleanup: PublishFileExclusiveCleanup): FsSafeError;
27
27
  export declare function directorySyncFailure(error: unknown): PublishFileExclusiveDirectorySyncFailure;
28
- //# sourceMappingURL=publish-file-failure.d.ts.map
@@ -1,4 +1,4 @@
1
- import { type Stats } from "node:fs";
1
+ import { type BigIntStats, type Stats } from "node:fs";
2
2
  import { type DirectoryReceipt, type DirectorySyncOutcome } from "./directory-durability.js";
3
3
  import { type FileIdentityStat } from "./file-identity.js";
4
4
  import { type PublishFileExclusiveSyncFailurePolicy } from "./publish-file-failure.js";
@@ -16,6 +16,5 @@ export declare function publishFileExclusive(params: {
16
16
  expectedSourceIdentity?: FileIdentityStat;
17
17
  strategy: PublishFileExclusiveStrategy;
18
18
  onSyncFailure?: PublishFileExclusiveSyncFailurePolicy;
19
- parentReceipt?: DirectoryReceipt;
19
+ parentReceipt?: DirectoryReceipt<Stats | BigIntStats>;
20
20
  }): Promise<PublishFileExclusiveResult>;
21
- //# sourceMappingURL=publish-file.d.ts.map
@@ -15,6 +15,8 @@ import { directorySyncFailure, publicationFailure, rememberCreatedTarget, } from
15
15
  import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
16
16
  import { getFsSafeTestHooks } from "./test-hooks.js";
17
17
  import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
18
+ import { hasErrorCode } from "./file-cleanup.js";
19
+ import { writeAllToFile } from "./write-file-handle.js";
18
20
  const HARDLINK_FALLBACK_CODES = new Set(["EPERM", "EXDEV", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
19
21
  const NATIVE_COPY_FALLBACK_CODES = new Set(["EINVAL", "ENOSYS", "ENOTSUP", "EOPNOTSUPP", "EPERM", "EXDEV"]);
20
22
  export function isHardlinkFallbackError(error) {
@@ -41,7 +43,7 @@ async function openNativeParent(filePath) {
41
43
  throw error;
42
44
  }
43
45
  }
44
- async function assertPinnedSourceCurrent(params) {
46
+ function assertPinnedSourceCurrent(params) {
45
47
  // Windows file indexes can exceed Number.MAX_SAFE_INTEGER, so publication
46
48
  // fences must compare bigint stats instead of rounded numeric identities.
47
49
  const opened = fsSync.fstatSync(params.handle.fd, { bigint: true });
@@ -54,6 +56,23 @@ async function assertPinnedSourceCurrent(params) {
54
56
  throw new FsSafeError("path-mismatch", "publication source changed during operation");
55
57
  }
56
58
  }
59
+ function assertPublishedTargetCurrent(targetPath, identity, message) {
60
+ const current = fsSync.lstatSync(targetPath, { bigint: true });
61
+ if (current.isSymbolicLink() || !current.isFile() || !sameFileIdentity(current, identity)) {
62
+ throw new FsSafeError("path-mismatch", message);
63
+ }
64
+ }
65
+ function assertRenamedSourceAbsent(sourcePath) {
66
+ try {
67
+ fsSync.lstatSync(sourcePath);
68
+ }
69
+ catch (error) {
70
+ if (hasErrorCode(error, "ENOENT"))
71
+ return;
72
+ throw error;
73
+ }
74
+ throw new FsSafeError("path-mismatch", "no-replace publication source still exists");
75
+ }
57
76
  async function copyPinnedSource(params) {
58
77
  if (params.native && params.targetNativeParent) {
59
78
  const closeFd = captureNativeFdClose(params.native);
@@ -131,15 +150,9 @@ async function copyPinnedSource(params) {
131
150
  if (bytesRead === 0) {
132
151
  break;
133
152
  }
134
- hash.update(buffer.subarray(0, bytesRead));
135
- let written = 0;
136
- while (written < bytesRead) {
137
- const result = await target.write(buffer, written, bytesRead - written, position + written);
138
- if (result.bytesWritten <= 0) {
139
- throw new FsSafeError("helper-failed", "exclusive publication copy made no progress");
140
- }
141
- written += result.bytesWritten;
142
- }
153
+ const chunk = buffer.subarray(0, bytesRead);
154
+ hash.update(chunk);
155
+ await writeAllToFile(target, chunk, { position });
143
156
  position += bytesRead;
144
157
  }
145
158
  await target.sync();
@@ -208,6 +221,7 @@ export async function publishFileExclusive(params) {
208
221
  let parent;
209
222
  let sourceNativeParent;
210
223
  let targetNativeParent;
224
+ let copiedTarget;
211
225
  const strategy = params.strategy;
212
226
  const failure = {
213
227
  phase: strategy === "rename-noreplace" ? "rename-create" : "hardlink-create",
@@ -232,8 +246,20 @@ export async function publishFileExclusive(params) {
232
246
  : sourceIdentity))) {
233
247
  throw new FsSafeError("path-mismatch", "publication source identity did not match");
234
248
  }
249
+ const assertSourceCurrent = () => assertPinnedSourceCurrent({ sourcePath, handle: source, identity: sourceExactIdentity });
250
+ const finishPublication = async (method, handle, identity) => {
251
+ const verifyPhase = failure.phase;
252
+ const directorySync = await syncPublishedParent({ parent: parent, failure, method, targetPath });
253
+ failure.phase = verifyPhase;
254
+ if (method === "rename-noreplace")
255
+ assertRenamedSourceAbsent(sourcePath);
256
+ else
257
+ assertSourceCurrent();
258
+ assertPublishedTargetCurrent(targetPath, identity, "publication target changed during directory sync");
259
+ return { method, identity: fsSync.fstatSync(handle.fd), directorySync };
260
+ };
235
261
  await parent.assertCurrent();
236
- await assertPinnedSourceCurrent({ sourcePath, handle: source, identity: sourceExactIdentity });
262
+ assertSourceCurrent();
237
263
  const native = strategy === "rename-noreplace"
238
264
  ? requireNativeBinding()
239
265
  : getNativeBinding();
@@ -248,33 +274,10 @@ export async function publishFileExclusive(params) {
248
274
  // A failed post-rename fence must not delete the only remaining name.
249
275
  failure.preserveTarget = true;
250
276
  await getFsSafeTestHooks()?.afterPublishTargetCreated?.("rename-noreplace", targetPath, sourceExactIdentity);
251
- const targetExactIdentity = fsSync.lstatSync(targetPath, { bigint: true });
252
- if (targetExactIdentity.isSymbolicLink() ||
253
- !targetExactIdentity.isFile() ||
254
- !sameFileIdentity(targetExactIdentity, sourceExactIdentity)) {
255
- throw new FsSafeError("path-mismatch", "no-replace publication target changed");
256
- }
257
- try {
258
- fsSync.lstatSync(sourcePath);
259
- throw new FsSafeError("path-mismatch", "no-replace publication source still exists");
260
- }
261
- catch (error) {
262
- if (error.code !== "ENOENT") {
263
- throw error;
264
- }
265
- }
277
+ assertPublishedTargetCurrent(targetPath, sourceExactIdentity, "no-replace publication target changed");
278
+ assertRenamedSourceAbsent(sourcePath);
266
279
  syncFileBestEffortSync(sourceNativeParent.handle.fd);
267
- const targetIdentity = fsSync.lstatSync(targetPath);
268
- return {
269
- method: "rename-noreplace",
270
- identity: targetIdentity,
271
- directorySync: await syncPublishedParent({
272
- parent,
273
- failure,
274
- method: "rename-noreplace",
275
- targetPath,
276
- }),
277
- };
280
+ return await finishPublication("rename-noreplace", source, sourceExactIdentity);
278
281
  }
279
282
  try {
280
283
  if (native) {
@@ -285,24 +288,9 @@ export async function publishFileExclusive(params) {
285
288
  }
286
289
  rememberCreatedTarget(failure, sourceExactIdentity, "hardlink-verify");
287
290
  await getFsSafeTestHooks()?.afterPublishTargetCreated?.("hardlink", targetPath, sourceExactIdentity);
288
- const targetExactIdentity = fsSync.lstatSync(targetPath, { bigint: true });
289
- if (targetExactIdentity.isSymbolicLink() ||
290
- !targetExactIdentity.isFile() ||
291
- !sameFileIdentity(targetExactIdentity, sourceExactIdentity)) {
292
- throw new FsSafeError("path-mismatch", "hardlink publication target changed");
293
- }
294
- await assertPinnedSourceCurrent({ sourcePath, handle: source, identity: sourceExactIdentity });
295
- const targetIdentity = fsSync.lstatSync(targetPath);
296
- return {
297
- method: "hardlink",
298
- identity: targetIdentity,
299
- directorySync: await syncPublishedParent({
300
- parent,
301
- failure,
302
- method: "hardlink",
303
- targetPath,
304
- }),
305
- };
291
+ assertPublishedTargetCurrent(targetPath, sourceExactIdentity, "hardlink publication target changed");
292
+ assertSourceCurrent();
293
+ return await finishPublication("hardlink", source, sourceExactIdentity);
306
294
  }
307
295
  catch (error) {
308
296
  if (failure.targetCreated ||
@@ -312,48 +300,19 @@ export async function publishFileExclusive(params) {
312
300
  }
313
301
  }
314
302
  failure.phase = "copy-create";
315
- let target;
316
- let targetIdentity;
317
- try {
318
- const copied = await copyPinnedSource({
319
- source,
320
- targetPath,
321
- native,
322
- targetNativeParent,
323
- failure,
324
- });
325
- target = copied.handle;
326
- targetIdentity = fsSync.fstatSync(target.fd);
327
- const targetPathStat = fsSync.lstatSync(targetPath);
328
- const targetPathExactStat = fsSync.lstatSync(targetPath, { bigint: true });
329
- const copiedBack = await hashFileHandle(target, native);
330
- const sourceAfter = await hashFileHandle(source, native);
331
- if (targetPathStat.isSymbolicLink() ||
332
- targetPathExactStat.isSymbolicLink() ||
333
- !sameFileIdentity(targetPathExactStat, copied.exactIdentity) ||
334
- copiedBack.bytes !== copied.bytes ||
335
- copiedBack.digest !== copied.digest ||
336
- sourceAfter.bytes !== copied.bytes ||
337
- sourceAfter.digest !== copied.digest) {
338
- throw new FsSafeError("path-mismatch", "exclusive publication copy failed content fencing");
339
- }
340
- await assertPinnedSourceCurrent({ sourcePath, handle: source, identity: sourceExactIdentity });
341
- const directorySync = await syncPublishedParent({
342
- parent,
343
- failure,
344
- method: "exclusive-copy",
345
- targetPath,
346
- });
347
- return { method: "exclusive-copy", identity: targetPathStat, directorySync };
348
- }
349
- catch (error) {
350
- await target?.close().catch(() => undefined);
351
- target = undefined;
352
- throw error;
353
- }
354
- finally {
355
- await target?.close().catch(() => undefined);
303
+ const copied = await copyPinnedSource({ source, targetPath, native, targetNativeParent, failure });
304
+ copiedTarget = copied.handle;
305
+ const copiedBack = await hashFileHandle(copiedTarget, native);
306
+ const sourceAfter = await hashFileHandle(source, native);
307
+ assertPublishedTargetCurrent(targetPath, copied.exactIdentity, "exclusive publication copy failed content fencing");
308
+ if (copiedBack.bytes !== copied.bytes ||
309
+ copiedBack.digest !== copied.digest ||
310
+ sourceAfter.bytes !== copied.bytes ||
311
+ sourceAfter.digest !== copied.digest) {
312
+ throw new FsSafeError("path-mismatch", "exclusive publication copy failed content fencing");
356
313
  }
314
+ assertSourceCurrent();
315
+ return await finishPublication("exclusive-copy", copiedTarget, copied.exactIdentity);
357
316
  }
358
317
  catch (error) {
359
318
  if (!failure.targetCreated)
@@ -365,6 +324,7 @@ export async function publishFileExclusive(params) {
365
324
  throw publicationFailure(error, failure, cleanup);
366
325
  }
367
326
  finally {
327
+ await copiedTarget?.close().catch(() => undefined);
368
328
  await sourceNativeParent?.handle.close().catch(() => undefined);
369
329
  await targetNativeParent?.handle.close().catch(() => undefined);
370
330
  await source.close().catch(() => undefined);
@@ -5,4 +5,3 @@ export declare function resolveReadOpenFlags(options?: {
5
5
  followSymlinks?: boolean;
6
6
  }): number;
7
7
  export {};
8
- //# sourceMappingURL=read-open-flags.d.ts.map
@@ -18,4 +18,3 @@ export declare function readOpenedFileSafely(params: {
18
18
  maxBytes?: number;
19
19
  }): Promise<ReadResult>;
20
20
  export {};
21
- //# sourceMappingURL=read-opened-file.d.ts.map
@@ -1,4 +1,3 @@
1
1
  export declare const realpathSync: ((input: string) => string) & {
2
2
  native: (input: string) => string;
3
3
  };
4
- //# sourceMappingURL=realpath.d.ts.map
@@ -1,3 +1,2 @@
1
1
  /** Bun's Windows recursive mkdir cannot inspect existing relative dot components. */
2
2
  export declare function recursiveMkdirPath(directory: string): string;
3
- //# sourceMappingURL=recursive-mkdir-path.d.ts.map
@@ -35,4 +35,3 @@ export declare function readRegularFileSync(params: {
35
35
  export declare function appendRegularFile(options: AppendRegularFileOptions): Promise<void>;
36
36
  export declare function appendRegularFileSync(options: AppendRegularFileOptions): void;
37
37
  export {};
38
- //# sourceMappingURL=regular-file.d.ts.map