@smthrs/artifacts 0.0.0-stage → 1.0.0-rc.12

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# @smthrs/artifacts
+
+## [Unreleased]
+
+### Fixed
+
+- The filesystem store syncs the real ancestors of a Windows drive directory.
+  Breaking: `makeFileSystem(fs, path, options)` takes the host `Path`, and
+  `layerFileSystem` requires `Path.Path` (`NodePath.layer` on Node) (#2302).
+- The filesystem store's `get`, `has`, and `findMissing` refuse a symlinked
+  objects root, fanout, or blob as `unavailable` instead of following it.
+- Artifact locks refuse a symlinked `.locks` directory before and after
+  creating it and recheck its identity before every lock-file mutation;
+  `FileLease.hold` takes a `guard` option for that check.
+- `RemoteArtifacts` never follows redirects (fetch runs with
+  `redirect: "manual"`), and allows plain `http:` only for the literal
+  loopback hosts `localhost`, `127.0.0.1`, and `[::1]`. Breaking: an
+  `http://*.localhost` endpoint is refused.
+
+## [1.0.0-rc.0] - 2026-08-31
+
+### Added
+
+- New package. The content-addressed artifact store extracted out of
+  `@smthrs/engine-store`'s `StepBoundary`: `ArtifactStore` (contract,
+  filesystem, memory, and no-op implementations), `RemoteArtifacts` (the
+  dumb-HTTP CAS client), and `CombinedArtifacts` (local-first, remote-second
+  read-through with local write-back).
+- Two improvements taken while moving, both from Bazel's `DiskCacheClient`: a
+  two-hex-prefix fanout directory layout, and an fsync of the temp file before
+  the rename that publishes it. There is no compatibility shim for the old flat
+  layout.
+
+### Changed
+
+- Snapshotted all caller-owned byte arrays at Effect start and copied every
+  read result.
+- Added strict SHA-256 address validation, typed configuration and crypto
+  failures, finite remote deadlines and body limits, and deterministic
+  `findMissing` deduplication.
+- Added workspace-wide writer/sweeper coordination with crash recovery, and
+  reclaimed crash-orphaned lock files in the same conservative scratch sweep
+  that reclaims `.tmp-*` payloads.
+- Made download policy immutable and consistent across constructors and layers.
+- Made `CombinedArtifacts.get`'s local write-back opportunistic: a local tier
+  that cannot store bytes the shared tier already served costs the next read a
+  round trip instead of failing this one. `minimal` now repairs a corrupt local
+  address, because an address the local tier already claims must be one it can
+  serve.
+- Applied caller-configured headers before the protocol's own, so a configured
+  `content-range`, `content-type`, or `content-length` can no longer overwrite
+  a chunked upload's computed headers.
+- Reported a refused byte snapshot as `unavailable`, the host-refusal code,
+  rather than as a crypto `digest_failed`.
+- Ignored a resume prefix past the safe integer range instead of trusting a
+  rounded offset.
+- Gave `ArtifactSweep` its own `SweepOptions` rather than the store's options,
+  which carried a `durability` field it ignored, and exported
+  `ArtifactStore.defaultDirectory` so the store and its sweep name one
+  directory.
+- Classified a backup-lease marker another process already reaped as a clean
+  release rather than logging a release failure.
+- Stopped a lock heartbeat from freshening a lock file it no longer owns. A
+  holder reaped as stale and replaced kept touching that path every 10 seconds,
+  which held the replacement fresh past every stale bound, so a replacement that
+  was then hard-killed blocked the digest for as long as the reaped holder ran.
+  A lock that is gone or now names another owner ends the heartbeat; a read the
+  host refused for any other reason skips one beat and retries, so a transient
+  refusal cannot retire a lock still held.
+- Made per-digest lock bookkeeping per execution rather than per construction.
+  A lock effect built once and run repeatedly, which is how the backup lease
+  heartbeats, retired its entry underneath a live holder, and the next caller
+  minted a second in-process semaphore for the same digest.
+- Documented that reclaiming a stale lock measures and then removes in separate
+  steps, so simultaneous reclaims of one stale lock can both proceed, and that
+  `ifUnmodifiedSinceMs` and the backup lease are the fences that do not depend
+  on it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# `@smthrs/artifacts`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as a `^4.0.4` peer dependency. Install one
+`effect` release in that range so all Smithers packages share one Effect
+runtime.
+
+**Documentation:** https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/artifacts/docs
+
+The content-addressed artifact store: bytes addressed by their own SHA-256
+digest. You hand it a `Uint8Array`, it hands back a 64 character address, and
+any store holding those bytes returns them for that address after checking that
+they still hash to it.
+
+Reach for it when you cache or ship large byte payloads, a compiled bundle, a
+build log, a model transcript, a tarball, and you care that a read either
+returns the exact bytes that were published or fails. It opens no file and no
+socket by itself: the filesystem and the network arrive as Effect's
+`FileSystem` and `HttpClient` services, which is what lets the same store code
+run in Node.js, in Bun, in a browser tab, and inside a sandbox.
+
+## Install
+
+```bash
+npm install @smthrs/artifacts@next effect
+```
+
+`@effect/platform-node` supplies the Node.js implementations of the services
+the store asks for. The filesystem store needs exclusive writable handles,
+symlink inspection, and (by default) file and directory syncing. Compose it
+with the trusted host filesystem before applying the capability kernel to
+workflow services; `NodeRuntime.layerHost` and `BunRuntime.layerHost` do this.
+The guarded native filesystem refuses open handles and cannot back this store,
+even with `durability: "best-effort"`. Use `layerMemory` on hosts without those
+filesystem capabilities.
+
+## Publish bytes and read them back
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem"
+import * as NodePath from "@effect/platform-node/NodePath"
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+
+const layer = ArtifactStore.layerFileSystem({ directory: ".flows/objects" }).pipe(
+  Layer.provideMerge(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer, NodeCrypto.layer))
+)
+
+const program = Effect.gen(function*() {
+  const store = yield* ArtifactStore.ArtifactStore
+  const bytes = new TextEncoder().encode("the bytes a build step produced")
+
+  const address = yield* store.put(bytes)
+  const again = yield* store.put(bytes)
+
+  console.log(address)
+  console.log(again === address)
+  console.log(new TextDecoder().decode(yield* store.get(address)))
+})
+
+await Effect.runPromise(program.pipe(Effect.provide(layer)))
+```
+
+```text
+6bb29e0869012afcfc246886c647422236e0b7d3419d3dc4ded8da758a4dfeb3
+true
+the bytes a build step produced
+```
+
+One blob landed on disk, under the first two characters of its own address. The
+second `put` measured the bytes, took the digest's lock, verified the blob
+already there, freshened its modification time, and synced it, then returned the
+same address without rewriting the payload.
+
+## The stores you can compose
+
+Every implementation is the same four operations, `put`, `get`, `has`, and
+`findMissing`, so a composition swaps one for another without touching a
+caller:
+
+| Constructor                    | What backs it                               | Use it for                                 |
+| ------------------------------ | ------------------------------------------- | ------------------------------------------ |
+| `ArtifactStore.makeFileSystem` | A directory, reached through `FileSystem`   | The durable local tier                     |
+| `ArtifactStore.makeMemory`     | A private `Map`                             | Tests, and hosts with no durable disk      |
+| `ArtifactStore.makeNoop`       | Nothing, with per-method overrides          | Declaring a tier honestly unavailable      |
+| `RemoteArtifacts.make`         | An HTTP cache, reached through `HttpClient` | The tier several machines share            |
+| `CombinedArtifacts.make`       | A local store in front of a shared one      | Read local first, fall through, write back |
+
+`ArtifactSweep` enumerates an objects directory and deletes one blob behind a
+modification time fence, and `ArtifactBackupLease` keeps a sweep from deleting
+a blob a running backup is still copying.
+
+Every export, option, and error code is in the
+[API reference](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/artifacts/docs/api.md).
+
+## What it guarantees
+
+- **Every read is digest verified.** A truncated blob left by a crashing
+  writer, a corrupted disk, or a mis-serving shared tier is refused with
+  `ArtifactCorruption`, never handed back as the recorded artifact. The memory
+  store is the one deliberate exception: its address space is a private `Map`
+  keyed by the digest it measured, so the address and the content cannot
+  disagree.
+- **Publication is atomic.** Bytes land at a temp path in the destination
+  directory, are fsynced, and are renamed into place. Temp names fold a random
+  per-instance token, so two processes publishing the same digest into one
+  workspace never share a scratch path.
+- **An existing blob is verified on every `put`.** The objects directory is
+  shared, so a remembered proof could outlive the bytes it proved. A mismatch
+  or failing read falls through to the atomic rewrite and heals the address.
+- **The endpoint and its credentials are a capability, never an input.** They
+  arrive as layer construction options, so they are never hashed into a cache
+  key and never recorded. `RemoteArtifacts` refuses a non-HTTPS endpoint, and
+  any endpoint carrying credentials, a query, or a fragment, at construction.
+  The sanitized message names only the violated rule, so the failure text never
+  echoes the endpoint.
+
+Every `put` snapshots its bytes when the Effect begins. Stores never retain a
+caller-owned buffer, and every successful `get` returns a new byte array.
+
+## Defaults
+
+| Boundary                                  | Default                 | Guarantee                                                                    |
+| ----------------------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| Filesystem directory                      | `.flows/objects`        | Two-hex fanout, atomic publication, digest verification, required fsync      |
+| Cross-process coordination                | `required`              | Writers and sweepers share per-digest lock files; stale owners are recovered |
+| Remote request, upload, download deadline | 60 seconds each         | No remote exchange can wait forever                                          |
+| Maximum downloaded blob                   | 256 MiB                 | The body is rejected before or while buffering past the limit                |
+| `findMissing` batch and response          | 1,000 digests / 256 KiB | Inputs are validated and deduplicated in first-seen order                    |
+
+`invalid_configuration` and `invalid_digest` are permanent caller failures.
+`ArtifactMissing` is an ordinary miss, and `ArtifactCorruption` is an integrity
+failure. `digest_failed`, `unavailable`, and `transport_failed` describe host
+or transport failures whose retryability depends on the host and operation.
+[Troubleshooting](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/artifacts/docs/troubleshooting.md) lists each
+one with what to change.
+
+## Prior art
+
+The contract's ergonomics follow Effect's own `KeyValueStore`: one small set of
+total operations over one address space, so memory, filesystem, and network
+implementations are the same shape. Everything else follows Bazel's
+remote-cache classes: `findMissing` is
+[`MissingDigestsFinder`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/remote/common/MissingDigestsFinder.java),
+one batched probe whose result is a subset of its input; the two-hex fanout and
+the fsync before the rename are
+[`DiskCacheClient`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/remote/disk/DiskCacheClient.java);
+and the wire protocol, CAS blobs under `/cas/base16-key`, is
+[`HttpCacheClient`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/remote/http/HttpCacheClient.java).
+Where this package deviates, and why, is in
+[content addressing](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/artifacts/docs/concepts/content-addressing.md).
+
+## Where it fits
+
+This package is one piece of the Smithers durable flow engine, whose whole
+surface is re-exported by [`@smthrs/flows`](https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/docs). Inside
+that engine the artifact store is the byte half of the result cache:
+[`@smthrs/step-cache`](https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/step-cache/docs) records what a step
+returned, and any part of that result too large to sit inline is spilled here
+and referenced by digest.
+
+Install `@smthrs/artifacts` on its own when a content-addressed byte store is
+all you want. Nothing in it knows what a flow, a step, or a run is.
+
+Reclaiming published artifacts is an explicit operation, never a side effect of
+a store call. The `.tmp-*` sweep in `layerFileSystem` reclaims crash orphans
+only. `ArtifactSweep` is the deletion surface, and the mark phase that decides
+what is live belongs to
+[`@smthrs/engine-store`](https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/engine-store/docs).
+
+## License
+
+MIT

package/dist/cjs/ArtifactBackupLease.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cross-process exclusion between a filesystem artifact backup and garbage
+ * collection.
+ *
+ * A backup holds one heartbeat-backed marker for the duration of its database
+ * snapshot and blob copy. Sweep deletion checks that marker while holding the
+ * same short-lived global gate. Publication remains unconstrained: new blobs
+ * may appear during a backup, but a blob already referenced by the frozen
+ * database cannot disappear underneath it.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+/**
+ * Runs `effect` while sweep deletion is fenced across every process using
+ * this objects directory. A crashed holder is recovered after its heartbeat
+ * becomes stale.
+ *
+ * @category combinators
+ * @since 1.0.0-rc.0
+ */
+export declare const withLease: <A, E, R, E2>(fs: FileSystem.FileSystem, directory: string, effect: Effect.Effect<A, E, R>, failure: (cause: unknown) => E2) => Effect.Effect<A, E | E2, R>;
+/**
+ * Runs one sweep deletion only when no live backup lease exists. The marker
+ * check and `effect` share the global gate, closing the check/delete race.
+ * `None` means a backup deliberately fenced the operation.
+ *
+ * @category combinators
+ * @since 1.0.0-rc.0
+ */
+export declare const unlessActive: <A, E, R, E2>(fs: FileSystem.FileSystem, directory: string, effect: Effect.Effect<A, E, R>, failure: (cause: unknown) => E2) => Effect.Effect<Option.Option<A>, E | E2, R>;
+//# sourceMappingURL=ArtifactBackupLease.d.ts.map

package/dist/cjs/ArtifactBackupLease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactBackupLease.d.ts","sourceRoot":"","sources":["../../src/ArtifactBackupLease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAqDvC;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EACnC,IAAI,UAAU,CAAC,UAAU,EACzB,WAAW,MAAM,EACjB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9B,SAAS,CAAC,KAAK,EAAE,OAAO,KAAK,EAAE,KAC9B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAoHzB,CAAA;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EACtC,IAAI,UAAU,CAAC,UAAU,EACzB,WAAW,MAAM,EACjB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9B,SAAS,CAAC,KAAK,EAAE,OAAO,KAAK,EAAE,KAC9B,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CASzC,CAAA"}

package/dist/cjs/ArtifactBackupLease.js

@@ -0,0 +1,183 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ArtifactBackupLease_exports = {};
+__export(ArtifactBackupLease_exports, {
+  unlessActive: () => unlessActive,
+  withLease: () => withLease
+});
+module.exports = __toCommonJS(ArtifactBackupLease_exports);
+var Clock = __toESM(require("effect/Clock"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Option = __toESM(require("effect/Option"), 1);
+var PlatformError = __toESM(require("effect/PlatformError"), 1);
+var Random = __toESM(require("effect/Random"), 1);
+var ArtifactLocks = __toESM(require("./internal/ArtifactLocks.js"), 1);
+const markerName = ".backup-lease";
+const gateName = ".backup-lease-gate";
+const heartbeatEvery = "10 seconds";
+const staleAfterMs = 6e4;
+const acquireWithin = "2 minutes";
+const retryEvery = "25 millis";
+const isReason = (cause, tag) => cause instanceof PlatformError.PlatformError && cause.reason._tag === tag;
+const token = Effect.gen(function* () {
+  const first = yield* Random.nextIntBetween(0, Number.MAX_SAFE_INTEGER, { halfOpen: true });
+  const second = yield* Random.nextIntBetween(0, Number.MAX_SAFE_INTEGER, { halfOpen: true });
+  return `${first.toString(36)}-${second.toString(36)}-${yield* Clock.currentTimeMillis}`;
+});
+const gate = (fs, directory, effect, failure) => ArtifactLocks.withDigest(fs, directory, gateName, effect, failure);
+const activeMarker = (fs, directory, failure) => Effect.gen(function* () {
+  const path = `${directory}/${markerName}`;
+  const info = yield* fs.stat(path).pipe(
+    Effect.map(Option.some),
+    Effect.catch(
+      (cause) => isReason(cause, "NotFound") ? Effect.succeed(Option.none()) : Effect.fail(failure(cause))
+    )
+  );
+  if (Option.isNone(info)) return false;
+  const modified = Option.getOrUndefined(info.value.mtime);
+  const now = yield* Clock.currentTimeMillis;
+  if (modified === void 0 || now - modified.getTime() <= staleAfterMs) return true;
+  yield* fs.remove(path).pipe(
+    Effect.catch(
+      (cause) => isReason(cause, "NotFound") ? Effect.void : Effect.fail(failure(cause))
+    )
+  );
+  return false;
+});
+const withLease = (fs, directory, effect, failure) => Effect.gen(function* () {
+  const owner = yield* token;
+  const marker = `${directory}/${markerName}`;
+  yield* fs.makeDirectory(directory, { recursive: true }).pipe(Effect.mapError(failure));
+  let ownsMarker = false;
+  const acquire = Effect.gen(function* () {
+    while (true) {
+      const acquired = yield* gate(
+        fs,
+        directory,
+        Effect.gen(function* () {
+          if (yield* activeMarker(fs, directory, failure)) return false;
+          return yield* Effect.uninterruptible(
+            fs.writeFileString(marker, owner, { flag: "wx", mode: 384 }).pipe(
+              Effect.andThen(Effect.sync(() => {
+                ownsMarker = true;
+                return true;
+              })),
+              Effect.catch(
+                (cause) => isReason(cause, "AlreadyExists") ? Effect.succeed(false) : Effect.fail(failure(cause))
+              )
+            )
+          );
+        }),
+        failure
+      );
+      if (acquired) return;
+      yield* Effect.sleep(retryEvery);
+    }
+  }).pipe(
+    Effect.timeout(acquireWithin),
+    Effect.catchTag("TimeoutError", (cause) => Effect.fail(failure(cause)))
+  );
+  return yield* Effect.acquireUseRelease(
+    Effect.void,
+    () => acquire.pipe(Effect.andThen(
+      Effect.scoped(Effect.gen(function* () {
+        yield* Effect.forkScoped(
+          Effect.gen(function* () {
+            while (true) {
+              yield* Effect.sleep(heartbeatEvery);
+              const reclaimed = yield* gate(
+                fs,
+                directory,
+                fs.readFileString(marker).pipe(
+                  Effect.map(Option.some),
+                  Effect.catch(
+                    (cause) => isReason(cause, "NotFound") ? Effect.succeed(Option.none()) : Effect.fail(cause)
+                  ),
+                  Effect.flatMap((found) => {
+                    if (Option.getOrUndefined(found) !== owner) {
+                      return Effect.as(
+                        Effect.logWarning(
+                          "Artifact backup lease was reclaimed while its backup was still running"
+                        ),
+                        true
+                      );
+                    }
+                    return Effect.flatMap(Clock.currentTimeMillis, (now) => {
+                      const timestamp = new Date(now);
+                      return Effect.as(fs.utimes(marker, timestamp, timestamp), false);
+                    });
+                  }),
+                  Effect.mapError(failure)
+                ),
+                failure
+              ).pipe(
+                // A failed heartbeat is retried on the next tick, but a
+                // minute of them lets the marker go stale, so each one is
+                // reported rather than dropped.
+                Effect.catch(
+                  (cause) => Effect.as(Effect.logWarning("Artifact backup lease heartbeat failed", cause), false)
+                )
+              );
+              if (reclaimed) return;
+            }
+          })
+        );
+        return yield* effect;
+      }))
+    )),
+    () => ownsMarker ? gate(
+      fs,
+      directory,
+      fs.readFileString(marker).pipe(
+        Effect.flatMap((found) => found === owner ? fs.remove(marker) : Effect.void),
+        // A backup whose heartbeat lapsed has its marker reaped by whoever
+        // noticed, so `NotFound` is the ordinary end of a slow lease, not a
+        // fault: there is nothing left to release and nothing left to leak.
+        // The sibling release in `internal/ArtifactLocks.ts` classifies the
+        // same cause the same way.
+        Effect.catch(
+          (cause) => isReason(cause, "NotFound") ? Effect.void : Effect.fail(cause)
+        )
+      ),
+      failure
+    ).pipe(
+      Effect.catch((cause) => Effect.logWarning("Artifact backup lease release failed", cause))
+    ) : Effect.void
+  );
+});
+const unlessActive = (fs, directory, effect, failure) => gate(
+  fs,
+  directory,
+  Effect.gen(function* () {
+    if (yield* activeMarker(fs, directory, failure)) return Option.none();
+    return Option.some(yield* effect);
+  }),
+  failure
+);
+//# sourceMappingURL=ArtifactBackupLease.js.map

package/dist/cjs/ArtifactBackupLease.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ArtifactBackupLease.ts"],
+  "sourcesContent": ["/**\n * Cross-process exclusion between a filesystem artifact backup and garbage\n * collection.\n *\n * A backup holds one heartbeat-backed marker for the duration of its database\n * snapshot and blob copy. Sweep deletion checks that marker while holding the\n * same short-lived global gate. Publication remains unconstrained: new blobs\n * may appear during a backup, but a blob already referenced by the frozen\n * database cannot disappear underneath it.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Clock from \"effect/Clock\"\nimport * as Effect from \"effect/Effect\"\nimport type * as FileSystem from \"effect/FileSystem\"\nimport * as Option from \"effect/Option\"\nimport * as PlatformError from \"effect/PlatformError\"\nimport * as Random from \"effect/Random\"\nimport * as ArtifactLocks from \"./internal/ArtifactLocks.ts\"\n\nconst markerName = \".backup-lease\"\nconst gateName = \".backup-lease-gate\"\nconst heartbeatEvery = \"10 seconds\"\nconst staleAfterMs = 60_000\nconst acquireWithin = \"2 minutes\"\nconst retryEvery = \"25 millis\"\n\nconst isReason = (cause: unknown, tag: PlatformError.SystemErrorTag): boolean =>\n  cause instanceof PlatformError.PlatformError && cause.reason._tag === tag\n\nconst token = Effect.gen(function*() {\n  const first = yield* Random.nextIntBetween(0, Number.MAX_SAFE_INTEGER, { halfOpen: true })\n  const second = yield* Random.nextIntBetween(0, Number.MAX_SAFE_INTEGER, { halfOpen: true })\n  return `${first.toString(36)}-${second.toString(36)}-${yield* Clock.currentTimeMillis}`\n})\n\nconst gate = <A, E, R, E2>(\n  fs: FileSystem.FileSystem,\n  directory: string,\n  effect: Effect.Effect<A, E, R>,\n  failure: (cause: unknown) => E2\n): Effect.Effect<A, E | E2, R> => ArtifactLocks.withDigest(fs, directory, gateName, effect, failure)\n\nconst activeMarker = <E>(\n  fs: FileSystem.FileSystem,\n  directory: string,\n  failure: (cause: unknown) => E\n): Effect.Effect<boolean, E> =>\n  Effect.gen(function*() {\n    const path = `${directory}/${markerName}`\n    const info = yield* fs.stat(path).pipe(\n      Effect.map(Option.some),\n      Effect.catch((cause): Effect.Effect<Option.Option<FileSystem.File.Info>, E> =>\n        isReason(cause, \"NotFound\") ? Effect.succeed(Option.none()) : Effect.fail(failure(cause))\n      )\n    )\n    if (Option.isNone(info)) return false\n    const modified = Option.getOrUndefined(info.value.mtime)\n    const now = yield* Clock.currentTimeMillis\n    if (modified === undefined || now - modified.getTime() <= staleAfterMs) return true\n    yield* fs.remove(path).pipe(\n      Effect.catch((cause): Effect.Effect<void, E> =>\n        isReason(cause, \"NotFound\") ? Effect.void : Effect.fail(failure(cause))\n      )\n    )\n    return false\n  })\n\n/**\n * Runs `effect` while sweep deletion is fenced across every process using\n * this objects directory. A crashed holder is recovered after its heartbeat\n * becomes stale.\n *\n * @category combinators\n * @since 1.0.0-rc.0\n */\nexport const withLease = <A, E, R, E2>(\n  fs: FileSystem.FileSystem,\n  directory: string,\n  effect: Effect.Effect<A, E, R>,\n  failure: (cause: unknown) => E2\n): Effect.Effect<A, E | E2, R> =>\n  Effect.gen(function*() {\n    const owner = yield* token\n    const marker = `${directory}/${markerName}`\n    yield* fs.makeDirectory(directory, { recursive: true }).pipe(Effect.mapError(failure))\n\n    let ownsMarker = false\n    const acquire = Effect.gen(function*() {\n      while (true) {\n        const acquired = yield* gate(\n          fs,\n          directory,\n          Effect.gen(function*() {\n            if (yield* activeMarker(fs, directory, failure)) return false\n            return yield* Effect.uninterruptible(\n              fs.writeFileString(marker, owner, { flag: \"wx\", mode: 0o600 }).pipe(\n                Effect.andThen(Effect.sync(() => {\n                  ownsMarker = true\n                  return true\n                })),\n                Effect.catch((cause): Effect.Effect<boolean, E2> =>\n                  isReason(cause, \"AlreadyExists\") ? Effect.succeed(false) : Effect.fail(failure(cause))\n                )\n              )\n            )\n          }),\n          failure\n        )\n        if (acquired) return\n        yield* Effect.sleep(retryEvery)\n      }\n    }).pipe(\n      Effect.timeout(acquireWithin),\n      Effect.catchTag(\"TimeoutError\", (cause) => Effect.fail(failure(cause)))\n    )\n\n    // Install marker cleanup before acquisition, including gate release. The\n    // marker write and ownership bookkeeping complete in one interruption mask.\n    return yield* Effect.acquireUseRelease(\n      Effect.void,\n      () =>\n        acquire.pipe(Effect.andThen(\n          Effect.scoped(Effect.gen(function*() {\n            yield* Effect.forkScoped(\n              Effect.gen(function*() {\n                while (true) {\n                  yield* Effect.sleep(heartbeatEvery)\n                  const reclaimed = yield* gate(\n                    fs,\n                    directory,\n                    fs.readFileString(marker).pipe(\n                      Effect.map(Option.some),\n                      Effect.catch((cause) =>\n                        isReason(cause, \"NotFound\") ? Effect.succeed(Option.none<string>()) : Effect.fail(cause)\n                      ),\n                      Effect.flatMap((found) => {\n                        // A missing or foreign marker means a sweep judged this\n                        // lease stale and reaped it: deletion is no longer\n                        // fenced while the backup still copies. The sibling\n                        // `internal/ArtifactLocks.ts` heartbeat reports the same\n                        // loss the same way. A reaped marker is never handed\n                        // back, so the loss is reported once and the heartbeat\n                        // ends instead of repeating it every tick.\n                        if (Option.getOrUndefined(found) !== owner) {\n                          return Effect.as(\n                            Effect.logWarning(\n                              \"Artifact backup lease was reclaimed while its backup was still running\"\n                            ),\n                            true\n                          )\n                        }\n                        return Effect.flatMap(Clock.currentTimeMillis, (now) => {\n                          const timestamp = new Date(now)\n                          return Effect.as(fs.utimes(marker, timestamp, timestamp), false)\n                        })\n                      }),\n                      Effect.mapError(failure)\n                    ),\n                    failure\n                  ).pipe(\n                    // A failed heartbeat is retried on the next tick, but a\n                    // minute of them lets the marker go stale, so each one is\n                    // reported rather than dropped.\n                    Effect.catch((cause) =>\n                      Effect.as(Effect.logWarning(\"Artifact backup lease heartbeat failed\", cause), false)\n                    )\n                  )\n                  if (reclaimed) return\n                }\n              })\n            )\n            return yield* effect\n          }))\n        )),\n      () =>\n        ownsMarker\n          ? gate(\n            fs,\n            directory,\n            fs.readFileString(marker).pipe(\n              Effect.flatMap((found) => found === owner ? fs.remove(marker) : Effect.void),\n              // A backup whose heartbeat lapsed has its marker reaped by whoever\n              // noticed, so `NotFound` is the ordinary end of a slow lease, not a\n              // fault: there is nothing left to release and nothing left to leak.\n              // The sibling release in `internal/ArtifactLocks.ts` classifies the\n              // same cause the same way.\n              Effect.catch((cause): Effect.Effect<void, PlatformError.PlatformError> =>\n                isReason(cause, \"NotFound\") ? Effect.void : Effect.fail(cause)\n              )\n            ),\n            failure\n          ).pipe(\n            Effect.catch((cause) => Effect.logWarning(\"Artifact backup lease release failed\", cause))\n          )\n          : Effect.void\n    )\n  })\n\n/**\n * Runs one sweep deletion only when no live backup lease exists. The marker\n * check and `effect` share the global gate, closing the check/delete race.\n * `None` means a backup deliberately fenced the operation.\n *\n * @category combinators\n * @since 1.0.0-rc.0\n */\nexport const unlessActive = <A, E, R, E2>(\n  fs: FileSystem.FileSystem,\n  directory: string,\n  effect: Effect.Effect<A, E, R>,\n  failure: (cause: unknown) => E2\n): Effect.Effect<Option.Option<A>, E | E2, R> =>\n  gate(\n    fs,\n    directory,\n    Effect.gen(function*() {\n      if (yield* activeMarker(fs, directory, failure)) return Option.none<A>()\n      return Option.some(yield* effect)\n    }),\n    failure\n  )\n"],
+  "mappings": "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",
+  "names": []
+}