@smthrs/engine-store 0.0.0-stage → 1.0.0-rc.3

package/CHANGELOG.md

@@ -0,0 +1,247 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- `EngineStateFault`: a durable engine-state invariant that breaks (a JSON
+  column that cannot be written or read back, or a row a lost first-writer
+  transaction expected) dies with this tagged defect, carrying `reason` and
+  `field`, instead of a plain `Error`. Its message is unchanged.
+
+### Fixed
+
+- Failed unknown effect-boundary appends now warn with their cause, run ID, and
+  action key while preserving the primary outcome. Missing completed-lineage
+  flow registration now exposes the tagged `FlowEngine.FlowNotRegistered` defect.
+
+- Durable engine-state JSON codec and missing first-writer row defects now
+  expose `EngineStateFault` with typed reasons, optional field, and cause.
+
+- Cache replay and workspace copy-back confine to a Windows drive root instead
+  of failing with `host_unavailable`. Breaking: `StepBoundary.makeFileSystem`
+  and `WorkspaceSandbox.makeFileSystem` take the host `Path` after `fs`, and
+  `StepBoundary.layer`, `WorkspaceSandbox.layerFileSystem`, and
+  `StepSandbox.layer` require `Path.Path` (`NodePath.layer` on Node). The Node
+  and Bun runtimes already provide it (#2302).
+
+### Security
+
+- Workspace copy-back can no longer be redirected outside the workspace by a
+  symlink swapped in between its confinement check and its write. Every
+  copy-back host call (lock, preflight, apply, rollback) now goes through
+  `@smthrs/kernel/FileSystem`'s `confined` view: one descriptor-relative,
+  no-follow request against the root pinned for that commit. The path-based
+  `realPath`/`readLink` confinement pre-check is gone. Breaking: a copy-back
+  through a symlink that stays inside the root is refused with
+  `path_escapes_workspace` instead of followed, and
+  `WorkspaceSandbox.layerFileSystem` and `StepSandbox.layer` fail to build with
+  `host_unavailable` over a plain path-based `FileSystem`. Compose them over
+  `@smthrs/platform-node`'s `AtomicFileSystem.layer` (which `NodeHost` and
+  `BunHost` already provide), the kernel-guarded `FileSystem.layer`, or an
+  in-memory volume wrapped in `withIsolatedFileSystem`.
+
+### Added
+
+- `EngineStore.Options.requestResume` reports every wake this engine itself
+  initiates against a parked execution: a durable deferred completing, a
+  durable clock firing, and a child settling under a parent that parked on it.
+  An operator's own resume is not reported, because the host that asked for it
+  has already claimed the run. A host that refuses to re-enter a parked run
+  nobody asked for had no way to tell an engine wake from its own heartbeat
+  sweep, so a run that slept, or whose child parked, never settled. Optional: a
+  composition without such a host leaves it undefined and every wake is exactly
+  what it was.
+
+### Changed
+
+- Breaking: `DurableEngineState.staleRunningRuns` returns
+  `ReadonlyArray<StaleRunningRow>` (`{ runId, heartbeatAtMs }`) instead of run
+  ids, so a sweep can scope a steal refusal to the lease it was refused
+  against. Custom `DurableEngineState` implementations must return the frozen
+  heartbeat with each run id; callers read `row.runId`.
+
+### Fixed
+
+- Compiled `stop-merge` recovery retains the stopped attempt's `skipped`
+  outcome. `PlanMergeStore` persists eligible peers and atomically commits
+  merge completion with its plan, source observations, and append event.
+  Reopening can recover recorded merge-only extensions from the original base;
+  intervening manual generations still require their approved plan. Generated
+  IDs avoid ordinary user IDs without treating names or bodies as authority.
+  Compose the new layer on the scheduler's database. Migration `3005` refuses
+  old observation heads whose merge state is unknown; finish on the prior
+  runtime or reconcile unfinished effects before starting a new run.
+
+- Compiled recovery binds the normalized runtime environment before dispatch
+  for all effect tiers. Changing `Options.environment` no longer repeats a
+  completed action under a fresh key. Nested environment options are copied at
+  construction. `PlanInputStore.Address` now requires `environmentDigest`,
+  derived by `StepKey.environmentIdentity`; migration `3004` refuses older
+  observation heads whose original environment is unknown instead of guessing.
+  Existing action keys are unchanged. Recover with the original environment,
+  or reconcile unfinished effects before intentionally starting new work.
+
+- `PlanInputStore` persists source digests and glob membership before compiled
+  dispatch. Reopening a self-updating run replays its original key instead of
+  observing its own output as a new input. Appended generations retain earlier
+  pins; corrupt, missing, incompatible or unfenced observations are refused.
+  The new layer is required on the scheduler's database and is included in
+  `TestStores`. Migration `3003` refuses compiled recovery for older runs that
+  already had attempts but no input observations; finish them before upgrading
+  or explicitly reconcile their effects. Changed approved graphs require a
+  new run, not replacement within an observed run.
+
+- File inputs are classified relative to each reader's predecessors. Explicit
+  read-before-write sequences pin initial sources, and intermediate reads see
+  preceding outputs. Future writers/removers no longer cause late source
+  remeasurement or expand source-glob membership. Durable input snapshots now
+  preserve that selection across reopening as well.
+
+- Ready-work admission uses `@smthrs/plan/Scheduling` for priority, aging, plan-
+  order ties and step/agent caps. Priority plus waiting age is compared exactly
+  even outside the safe-number range. This does not change the interpreter's
+  separate execution path or claim conditional scheduling parity.
+
+- Plan scheduling preserves declared effect tiers. Compensable and irreversible
+  work uses run-local, structurally scoped execution keys and never publishes a
+  shared-cache result. Durable replay survives reopening the database;
+  compensable retries restore their pre-image and keyless irreversible retries
+  remain refused. An irreversible conflict fails without automatic rebase or
+  merge execution. Compensable merge elaboration preserves the stopped node's
+  tier instead of turning it into shared-cache work.
+
+- Cancellation through any trampoline round now reaches live successors and
+  linked child lineages, including children created by earlier rounds. Requests
+  and handoffs serialize in the owning write transaction; local interruption
+  is sent only after commit and does not wait on user cleanup. Normal parent
+  exit resolves child policy from the round that created the edge and preserves
+  it across handoffs. Fork ancestry alone does not propagate cancellation.
+
+- Fixed the CommonJS build of the migration set. esbuild compiles a default
+  import of a sibling module under `"type": "module"` to Node-style interop,
+  where `import_x.default` is the sibling's whole exports object rather than
+  the Effect it exported, so `set.migrations["0001_initial"]` and
+  `set.migrations["0002_selection_store"]` had no `pipe` in `dist/cjs` and
+  every `require` consumer failed at schema time. `migrations/0001_initial`
+  now exports the named `initial` binding, `migrations/0002_selection_store`
+  exports the named `selectionStore` binding, neither has a default export,
+  and `Migrations` imports both by name.
+
+## [1.0.0-rc.0] - 2026-09-01
+
+### Release notes
+
+> **Issue links.** This package was imported from the `smithersai/flows`
+> repository, so the issue numbers cited below resolve there. Issues opened
+> since the import resolve in `smithersai/smithers`, which `package.json`
+> names as this package's repository.
+
+> **Databases.** Smithers 1.0.0-rc.0 stores run state in local SQLite only (`@effect/sql-sqlite-node` over Node.js `node:sqlite`). PostgreSQL and PGlite are not supported: no client layer or migration ladder ships, `SMITHERS_BACKEND=pglite|postgres` and `--backend pglite|postgres` exit with `unsupported_database`, and the 0.x `smithers migrate --to` database move is removed. Projects that ran 0.x on PGlite or PostgreSQL must finish or discard their runs on 0.x; there is no import path.
+
+### Added
+
+- Added persisted plan scheduling and reconciliation, workspace and step
+  sandboxes, selection and training, local/remote artifact and cache sync,
+  metrics, in-process wakes, bounded retention, run-catalog reads, artifact
+  garbage collection, and hot backup/verify/restore/fence operations.
+- Added cross-process artifact backup leases and frozen-root verification so a
+  backup cannot race artifact sweep or publish an incomplete manifest.
+
+### Changed
+
+- Required an owner-liveness probe when constructing the durable engine.
+- `DurableEngineState` now requires Effect's `SqlClient` service plus
+  `DurableWriter` (the renamed `Database` service).
+- Made durable state, journal records, plan mutations, and multi-row selection
+  updates transactional, with strict numeric bounds and host-independent
+  UTF-16 ordering.
+- Snapshot caller-owned descriptors and bytes before asynchronous work, and
+  bind checkpoint operations to the configured repository workspace.
+- Derived workspace-revision and bundle-identity strings from domain-tagged
+  canonical JSON. Their persisted values now change.
+- Removed the internal `@slop` review markers from every published JSDoc block.
+  They shipped in `src/**/*.ts` and the generated declarations, so a consumer's
+  editor hover showed a repository to-do instead of the contract.
+- Repointed every JSDoc design reference, every reference in the package's own
+  `docs/` prose, and the remaining references in test headers at their published
+  `docs/pages` successors. The imported `docs/specs` tree and the
+  `.smithers/tickets` notes do not exist in this repository, so each pointer
+  named a file no reader could open.
+- Renamed the durable `flows.engine.cache-conflict` payload field `key` to
+  `cacheKey`. `@smthrs/journal` reads a field named `key` as a credential and
+  replaces its value with `[REDACTED]`, which erased the very content address
+  the conflict record exists to preserve.
+- Renamed the dispatch observability field `key` to `stepKey` on every log
+  annotation and span attribute this package writes. The same journal rule that
+  redacts a durable `key` also redacts a log annotation named `key`, and
+  `RedactedLogger` is installed by `@smthrs/flows`' `NodeRuntime` and by the
+  `smithers` binary, so every dispatch line an operator read said
+  `key=[REDACTED]` and no longer named which step it described. Span attributes
+  take the new name too, so a trace and a log line agree.
+- Validated `DisasterRecovery` `maxFileSizeBytes` at option admission. A
+  fractional, NaN, infinite, negative, or unsafe value now fails with the new
+  `invalid_options` code instead of dying inside `BigInt`.
+
+### Fixed
+
+- Prevented torn scheduler/journal settlements, retention partial deletes,
+  mutable boundary evidence, forged materialization conflicts, ambiguous
+  deviation identities, and failure-Exit corruption after in-memory restart.
+- Made artifact GC and disaster recovery fail closed on corrupt durable roots,
+  and made the local CAS coordinate writers and sweepers across processes.
+- Required explicit whole-tree write verification before admitting a sealed
+  result to the cross-run cache.
+- Quarantined corrupt boundary evidence off succeeded attempt rows after
+  journalling the inconsistency, so a later resume returns the durable outcome
+  without re-executing the action
+  ([#171](https://github.com/smithersai/flows/issues/171)).
+- Included recorded-row provenance in corruption journal identities so an
+  identically re-corrupted row records a new incident after healing
+  ([#172](https://github.com/smithersai/flows/issues/172)).
+- Reduced a live failure value to inert JSON before it reaches the attempt row,
+  so a boundary refusal, a sandbox refusal, or any `Data.TaggedError` settles
+  the attempt instead of being refused by the store as a non-plain object. A
+  value JSON cannot express at all now records as `null` rather than as a
+  dropped key the replay decoder could not read. The reduction reads own data
+  properties only, so persisting a failure no longer runs the failing value's
+  getters, `toJSON`, or proxy traps, and it is bounded by the depth, node, and
+  character allowances the attempt store admits, so an outsized failure records
+  as `null` instead of being refused and leaving the row `running`.
+- Enumerated a declared tree artifact in full. `.git`, `.jj`, and `node_modules`
+  are pruned from glob expansion only; pruning them from `filesUnder` and
+  `entriesUnder` left files out of a tree's captured identity and left stale
+  copies of them behind on replay.
+- Derived glob-pruning exemptions from every full include that shares a walk
+  prefix. An ignored-directory segment after a wildcard now remains in a
+  declared read set instead of disappearing from boundary measurement, while a
+  root glob still skips undeclared repository metadata and dependency trees.
+- Charged the persisted cause envelope and interrupt reasons against one node
+  budget, with a replayable one-reason fallback when it is exhausted. A large
+  interrupted fan-out can no longer make `AttemptStore.finish` reject the
+  terminal update and leave the attempt `running`.
+- Reduced array-buffer views to a bounded marker before own-key enumeration and
+  charged every other enumerated key against a shared walk allowance. A large
+  typed-array defect can no longer materialize one property name per byte on
+  the terminal failure path.
+- Measured the encoded backup manifest against `maxFileSizeBytes` before its
+  final write. Backup can no longer report success for a manifest that verify
+  and restore reject under the same file-size option.
+- Dropped quarantined boundary evidence by omitting the key rather than writing
+  `undefined` over it, which the attempt store refuses.
+
+## [0.1.0] - 2026-08-05
+
+### Fixed
+
+- Removed composition-time throws and structural boundary sniffing by using
+  Deferred service wiring and Schema-backed boundary descriptors.
+- Supervised ownership heartbeats through structured interruption races.
+
+### Added
+
+- Added the journal-backed engine composition, claim-gated run
+  driver, durable deferred and absolute-clock state, action persistence
+  wiring, and deterministic test layers.
+- Added SQL-backed deferred completions and clock deadlines with owner-fenced
+  scheduling, first-writer completion, and restart recovery.

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,147 @@
-# Temporary Holding Version
+# @smthrs/engine-store
 
-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 an exact
+`4.0.0-rc.115` peer dependency. Keep the application on that version so
+all Smithers packages share one Effect runtime.
+
+**Documentation:** https://engine-store.smithers.sh
+
+The durable half of the Smithers flow engine. It persists every step a flow
+takes to a SQLite database, so a flow that crashes, is killed, or waits for a
+week resumes where it stopped instead of starting over.
+
+It is an [Effect](https://effect.website) library: every surface it exports is
+a `Layer` you compose or an `Effect` you run.
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+Node.js 26.4.0 or later. The package ships as both ESM and CommonJS with
+TypeScript declarations.
+
+## Testing
+
+`smthrs test '//packages/smithers/flows/engine-store:test'` runs the existing
+suite on SQLite and real PostgreSQL. By default the matrix starts and cleans
+up its own disposable PostgreSQL server. To use an existing server, supply
+`SMITHERS_TEST_PG_URL` before invoking the command; the target declares that
+connection in its environment and execution key.
+
+The canonical override accepts a credential-free `postgres:` or `postgresql:`
+URL with optional `sslmode` and positive, at most two-digit `connect_timeout`.
+Declared configuration is visible in plans, so passwords, credential files,
+service configuration and other query options are refused without echoing the
+URL. An unavailable configured server fails the PostgreSQL leg. The direct
+matrix script retains its existing password support and disposable-server path.
+
+## The shortest real use
+
+`EngineStore.layer` is the composition. It provides `FlowRuntime`, the service
+that executes a flow durably, and the snapshot boundary the engine measures
+each step against:
+
+```ts
+import { EngineStore } from "@smthrs/engine-store"
+import { FlowRuntime } from "@smthrs/flow"
+import { Effect } from "effect"
+
+const engineLayer = EngineStore.layer({
+  owner: { hostId: "worker-a" },
+  journalSource: "engine-store"
+})
+
+const program = Effect.gen(function*() {
+  return yield* FlowRuntime.FlowRuntime
+}).pipe(Effect.provide(engineLayer))
+```
+
+`engineLayer` still needs the storage it composes: `DurableWriter`, `Journal`, `RunStore`,
+`AttemptStore`, `CacheStore`, `DurableEngineState`, `StepBoundary`, `Jj`,
+`OwnerIdentity`, Effect's `Crypto`, and a `Scope`. Supply the same `DurableWriter`
+used by the journal and run store. A missing service is an unmet
+requirement in the layer's type, so a bad composition fails to compile rather
+than at run time. Run the schema migrations before any SQL-backed service reads
+the database, and provide `OwnerIdentity.layer` unless the host mints its own
+owner tokens.
+
+[The quickstart](https://engine-store.smithers.sh/quickstart/) wires all of it
+over one SQLite file and watches a sealed step replay after a restart.
+
+If you want the wiring rather than control over it, reach for
+[`@smthrs/flows`](https://flows.smithers.sh) instead. It ships `NodeRuntime`,
+which composes this package with the flow language, the journal, the run and
+cache stores, and the artifact tier over one file.
+
+## What it gives you
+
+- **Durable attempts.** A step opens a row before its body runs and settles it
+  afterwards, so a restart replays the recorded result instead of executing the
+  body a second time.
+- **One owner per run.** Every durable write is fenced against the owner that
+  claimed the run, so two processes over one database cannot both drive it. A
+  dead owner's runs are reclaimed under a liveness check you choose.
+- **Waits that outlive the process.** A parked run holds a durable deferred or
+  clock row, so a timer set by a process that has since died still fires.
+- **Declared file boundaries.** The engine measures the tree a step actually
+  touched against what it declared, refuses a step that wrote outside it, and
+  admits only whole-tree evidence into the cache other runs read.
+- **Explicit deletion.** Old run history and unreferenced artifacts go away
+  when you run a retention or garbage-collection pass, never on a schedule you
+  did not set.
+
+Every durable write is one transaction. A lifecycle event is written inside the
+same transaction that carries the state transition it describes: the attempt
+row with its start and finish records, the run-row compare-and-set with its
+decision, the deferred or clock row with its record, the cache entry with its
+provenance. Either both halves are durable or neither is, so audit, sync, and
+time travel never read a hole. No local transaction makes a remote effect
+atomic, so external effects still need idempotency keys, fencing, or
+compensation.
+
+Closing an engine's Effect scope releases its run ownership across the full
+claim, execution, and settlement lifetime. An interrupted partial claim is
+abandoned; an activated run returns to `suspended`, preserving any declared
+approval, timer, or event wait. This lets a replacement engine in the same
+process resume with a new owner nonce without weakening the PID liveness
+check. Only a persisted operator cancellation closes the run as `cancelled`.
+
+## Browser imports and native durable execution
+
+The entry point bundles for a browser. The two host reads it once made
+directly, `process.pid` and `randomUUID` from `node:crypto`, enter through the
+injectable `OwnerIdentity` service, and the SQL contracts it imports are
+driver-neutral.
+
+Bundling is not running. The durable backing is SQLite or PostgreSQL, composed by the
+aggregate [`@smthrs/flows` runtime](../README.md) with native Node.js or Bun
+host adapters and the selected SQL client over these driver-neutral stores. A browser or edge deployment
+can import the types and browser-safe in-memory helpers, but cannot execute
+durable flows; supplying an alternative browser SQL client is not a supported
+runtime.
+
+## Documentation
+
+The full documentation is at <https://engine-store.smithers.sh>:
+
+- [Installation](https://engine-store.smithers.sh/installation/): runtime
+  requirements, import forms, and the storage packages a runnable composition
+  adds.
+- [Quickstart](https://engine-store.smithers.sh/quickstart/): compose a durable
+  engine over SQLite and watch a step replay after a restart.
+- [Compose a durable engine](https://engine-store.smithers.sh/guides/compose-a-durable-engine/):
+  the required and optional services, and what each one changes.
+- [API reference](https://engine-store.smithers.sh/reference/api/): every public
+  export, with signatures and error codes.
+- [Observe executions and page runs](https://engine-store.smithers.sh/guides/observe-executions/):
+  coherent snapshots, filtered keyset pages, durable children and revisioned catch-up.
+- [Troubleshooting](https://engine-store.smithers.sh/troubleshooting/): each
+  typed failure, its cause, and its fix.
+
+See also [durable execution](https://smithers.sh/docs/concepts/durable-execution/)
+and [content addressing](https://smithers.sh/docs/concepts/content-addressing/)
+on smithers.sh.
+
+List reads of durable wait state skip corrupt rows and log storage-integrity warnings; point reads still fail for an invalid row.

package/dist/cjs/ArtifactGc.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Mark/sweep garbage collection for the content-addressed artifact store.
+ *
+ * The artifact tier is the one store in the composition with true *garbage*:
+ * every output over the inline bound is spilled to `.flows/objects` by digest
+ * (`StepBoundary`), nothing ever deletes a published blob, and a blob whose
+ * every referencing row is gone is unreachable forever. The step cache is
+ * deliberately NOT collected here — its rows are the *roots* of this graph,
+ * they never become unreachable, and removing one is the policy decision
+ * `CacheStore.evict` already serves.
+ *
+ * The design combines the two prior arts on the shelf:
+ *
+ * - **Reachability from durable roots** — git's `git gc` marks from refs;
+ *   Skyframe deletes what a keyed graph walk cannot reach. Here the roots are
+ *   every attempt row of every existing (never-deleted) run and every step
+ *   cache entry; each carries boundary evidence, and
+ *   `StepBoundary.referencedDigests` names the blobs that evidence needs.
+ *   Attempt checkpoints are roots too: they are opaque executable state, so
+ *   the mark keeps digest-shaped strings found in their JSON.
+ * - **A grace period over mtime** — git refuses to prune unreachable objects
+ *   younger than `gc.pruneExpire` (two weeks), jj keeps operations newer than
+ *   its keep bound, and Bazel's disk-cache collector
+ *   (`reference/bazel/.../remote/disk/DiskCacheGarbageCollector.java`) fences
+ *   on mtime. The cutoff is the collection start time minus the grace period,
+ *   sampled before resolving policy pins or scanning roots and held fixed
+ *   through inventory and deletion. Only mtimes strictly before it are
+ *   eligible: a blob published — or freshened by a dedupe `put` — at or after
+ *   collection start survives, including same-millisecond writes at zero
+ *   grace, no lock required.
+ *
+ * Collection NEVER runs automatically. `gc()` is an explicit verb because
+ * deletion is irreversible, and a human approving a plan must approve the
+ * deletions too. The opt-in {@link ArtifactGcPolicy} layer
+ * configures *how* an invocation collects (grace bound, pinned digests); it
+ * does not schedule anything.
+ *
+ * @since 0.1.0
+ */
+import * as ArtifactSweep from "@smthrs/artifacts/ArtifactSweep";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+/**
+ * Stable error codes returned by artifact garbage collection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const ArtifactGcErrorCode: Schema.Literals<readonly ["invalid_options", "mark_failed", "sweep_failed"]>;
+/**
+ * Stable error codes returned by artifact garbage collection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ArtifactGcErrorCode = typeof ArtifactGcErrorCode.Type;
+declare const ArtifactGcError_base: Schema.Class<ArtifactGcError, Schema.TaggedStruct<"@smthrs/engine-store/ArtifactGcError", {
+    readonly code: Schema.Literals<readonly ["invalid_options", "mark_failed", "sweep_failed"]>;
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A collection that could not complete. `mark_failed` means the live set
+ * could not be computed — nothing was deleted. `sweep_failed` means the live
+ * set held but a deletion refused; everything already swept was garbage, so a
+ * re-run converges from wherever the failure stopped it.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class ArtifactGcError extends ArtifactGcError_base {
+}
+/**
+ * The opt-in collection policy. Explicit {@link GcOptions} on a `gc()` call
+ * override the installed policy; the policy overrides the defaults.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Policy {
+    /** Grace bound applied when a `gc()` call does not name one. */
+    readonly graceMs?: number | undefined;
+    /**
+     * Digests held live regardless of reachability — the seam for references
+     * this composition's tables cannot see (an external index, an export a
+     * human wants kept). Resolved fresh on every collection.
+     */
+    readonly pins?: Effect.Effect<ReadonlyArray<string>> | undefined;
+}
+declare const ArtifactGcPolicy_base: Context.ServiceClass<ArtifactGcPolicy, "@smthrs/engine-store/ArtifactGcPolicy", Policy>;
+/**
+ * Service tag for the opt-in collection policy.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class ArtifactGcPolicy extends ArtifactGcPolicy_base {
+}
+/**
+ * Installs a collection policy.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerPolicy: (policy: Policy) => Layer.Layer<ArtifactGcPolicy>;
+/**
+ * Options for one explicit collection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface GcOptions {
+    /**
+     * How recently a blob must have been written or freshened to survive
+     * unreferenced. Defaults to the installed {@link ArtifactGcPolicy}'s bound,
+     * then to {@link defaultGraceMs}.
+     */
+    readonly graceMs?: number | undefined;
+    /** Digests held live for this collection, unioned with the policy's pins. */
+    readonly pins?: ReadonlyArray<string> | undefined;
+    /** Compute and report without deleting anything. */
+    readonly dryRun?: boolean | undefined;
+}
+/**
+ * What one collection did.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface GcReport {
+    /** Blobs the inventory enumerated. */
+    readonly scannedBlobs: number;
+    /** Distinct digests the mark phase proved live, pins included. */
+    readonly liveDigests: number;
+    /** Digests deleted — or, under `dryRun`, the ones a real run would delete. */
+    readonly sweptDigests: ReadonlyArray<string>;
+    /** Bytes the swept blobs held. */
+    readonly reclaimedBytes: number;
+    /** Unreferenced blobs retained by the grace bound or a freshen race. */
+    readonly keptByGrace: number;
+    readonly dryRun: boolean;
+}
+/**
+ * Explicit artifact garbage collection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    /**
+     * Marks the live set from the durable roots, then sweeps every blob that
+     * is both outside it and older than the grace bound. Explicit only —
+     * nothing in the engine composition ever calls this.
+     */
+    readonly gc: (options?: GcOptions) => Effect.Effect<GcReport, ArtifactGcError>;
+}
+declare const ArtifactGc_base: Context.ServiceClass<ArtifactGc, "@smthrs/engine-store/ArtifactGc", Service>;
+/**
+ * Service tag for artifact garbage collection.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class ArtifactGc extends ArtifactGc_base {
+}
+/**
+ * Two weeks, git's `gc.pruneExpire` default. The bound is deliberately far
+ * beyond any live attempt's duration: a blob spilled by a running step is
+ * unreferenced until its attempt row finishes, and the grace period is the
+ * only thing protecting it in that window.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultGraceMs: number;
+/**
+ * Construction options.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface MakeOptions {
+    /** Rows per mark-phase page. Defaults to 500. */
+    readonly pageSize?: number | undefined;
+}
+/**
+ * Builds the collector over the composition's own durable tables and the
+ * host-local sweep surface.
+ *
+ * The mark phase reads `flows_step_cache` and `flows_attempts` directly, the
+ * same way `DurableEngineState` range-scans `flows_runs`: this package
+ * composes every one of those migrations, so the schema is its own. Every run
+ * present in `flows_runs` is a live root — there is no deleted state, and the
+ * attempt table's foreign key guarantees each attempt's run exists — so the
+ * scan is simply *all* attempt rows plus *all* cache entries, paged by
+ * primary key so no page holds more than `pageSize` rows in memory.
+ *
+ * Ordering is the safety argument. The live set is computed BEFORE the
+ * inventory, so a root recorded during the sweep can only be missed, never
+ * half-seen — and the blob such a root references is protected anyway: a
+ * fresh publication carries a fresh mtime, a re-publication of existing bytes
+ * freshens the blob's mtime (`ArtifactStore.put`), and the sweep's deletion
+ * is fenced on that mtime (`ArtifactSweep.remove`'s `ifUnmodifiedSinceMs`).
+ * A crash mid-sweep deletes some garbage and no live blobs; re-running
+ * converges.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (options?: MakeOptions) => Effect.Effect<Service, never, SqlClient.SqlClient | ArtifactSweep.ArtifactSweep>;
+/**
+ * Provides the artifact garbage collector. Install {@link layerPolicy} into
+ * this layer's inputs to configure collection; nothing schedules `gc()` —
+ * invoking it stays an explicit caller decision.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: (options?: MakeOptions) => Layer.Layer<ArtifactGc, never, SqlClient.SqlClient | ArtifactSweep.ArtifactSweep>;
+/**
+ * Provides the artifact garbage collector over a filesystem objects directory:
+ * {@link layer} with `ArtifactSweep.layerFileSystem` beneath it. Pass the same
+ * `directory` and `coordination` the paired `ArtifactStore.layerFileSystem`
+ * publishes with.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerFileSystem: (options?: MakeOptions & ArtifactSweep.SweepOptions) => Layer.Layer<ArtifactGc, never, SqlClient.SqlClient | FileSystem.FileSystem>;
+export {};
+//# sourceMappingURL=ArtifactGc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactGc.d.ts","sourceRoot":"","sources":["../../src/ArtifactGc.ts"],"names":[],"mappings":"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"}