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

package/src/EngineStoreMetrics.ts

@@ -0,0 +1,331 @@
+/**
+ * Standard metric definitions for the engine-store hot paths.
+ *
+ * This module only defines the metric handles, following the shape of
+ * `RunStoreMetrics` and Effect's `ClusterMetrics`. The dispatch seam
+ * (`internal/ActionPersistence`), the plan scheduler, the workspace sandbox,
+ * and the run driver update them as outcomes are decided. No exporter ships in
+ * this package; provide one — for example `@smthrs/observability` — and
+ * these series appear in it.
+ *
+ * Counters over an effect's exit are keyed by {@link ExitTag} records, so an
+ * update is a lookup rather than a branch, and durations land in
+ * `Metric.timer` histograms through Effect's own `Effect.trackDuration`. The
+ * same exit observation annotates the operation span with its outcome; none of
+ * the instrumentation combinators alters the instrumented effect's result or
+ * cause.
+ *
+ * @since 0.1.0
+ */
+
+import * as Cause from "effect/Cause"
+import type * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import type * as Exit from "effect/Exit"
+import * as Metric from "effect/Metric"
+
+/**
+ * How an instrumented effect exited: `Success`, `Failure` (any non-interrupt
+ * cause), or `Interrupt` (an interrupt-only cause — in this store that is the
+ * fencing self-interruption as well as caller cancellation).
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ExitTag = "Success" | "Failure" | "Interrupt"
+
+/** Rewrites an outcome tag (`HeartbeatFresh`) as an attribute value (`heartbeat_fresh`). */
+const attributeValue = (tag: string): string => tag.replace(/(?<=[a-z0-9])(?=[A-Z])/g, "_").toLowerCase()
+
+/** Builds the tag-keyed record of attributed counter views for one operation. */
+const byOutcome = <const Tags extends ReadonlyArray<string>>(
+  metric: Metric.Metric<number, Metric.CounterState<number>>,
+  attributes: Readonly<Record<string, string>>,
+  tags: Tags
+): { readonly [Tag in Tags[number]]: Metric.Metric<number, Metric.CounterState<number>> } =>
+  Object.fromEntries(
+    tags.map((tag) => [tag, Metric.withAttributes(metric, { ...attributes, outcome: attributeValue(tag) })])
+  ) as { [Tag in Tags[number]]: Metric.Metric<number, Metric.CounterState<number>> }
+
+/**
+ * Classifies an exit for an {@link ExitTag}-keyed counter record.
+ *
+ * @category accessors
+ * @since 0.1.0
+ */
+export const exitTag = <A, E>(exit: Exit.Exit<A, E>): ExitTag =>
+  exit._tag === "Success" ? "Success" : Cause.hasInterruptsOnly(exit.cause) ? "Interrupt" : "Failure"
+
+/**
+ * Observes an effect with a duration timer and an exit-outcome counter.
+ *
+ * Composes Effect's own `Effect.trackDuration` (monotonic clock, records on
+ * success, failure, and interruption alike) with an `Effect.onExit` counter
+ * update and current-span annotation, so the instrumented effect's exit —
+ * value, cause, and interruption — propagates byte-identically. This is the
+ * dual-instrument shape production Effect services use for hot-path
+ * operations.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const observe = (instruments: {
+  readonly timer: Metric.Histogram<Duration.Duration>
+  readonly counter: { readonly [Tag in ExitTag]: Metric.Metric<number, Metric.CounterState<number>> }
+}) =>
+<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  effect.pipe(
+    Effect.trackDuration(instruments.timer),
+    Effect.onExit((exit) => {
+      const tag = exitTag(exit)
+      return Effect.annotateCurrentSpan({ outcome: attributeValue(tag) }).pipe(
+        Effect.andThen(Metric.update(instruments.counter[tag], 1))
+      )
+    })
+  )
+
+const exitTags = ["Success", "Failure", "Interrupt"] as const
+
+/**
+ * Counter over durable action dispatches through
+ * `internal/ActionPersistence`, dimensioned by exit `outcome` (`success`,
+ * `failure`, or `interrupt`). A cache-served replay and a fresh execution
+ * both count: the dispatch is the unit the engine retries and fences.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const dispatches = Metric.counter("flows_engine_dispatches", {
+  description: "Durable action dispatches by exit outcome"
+})
+
+/**
+ * Latency histogram over durable action dispatches, from admission through
+ * settlement (cache verification, execution, copy-back, and the terminal
+ * row included).
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const dispatchDuration = Metric.timer("flows_engine_dispatch_duration", {
+  description: "Durable action dispatch duration"
+})
+
+/**
+ * `dispatches` views keyed by {@link ExitTag}.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const dispatch = byOutcome(dispatches, {}, exitTags)
+
+/**
+ * Counter over scheduler admission passes that launched work. The
+ * completion-driven scheduler re-computes the ready set after every terminal
+ * event; only a pass that admits at least one node counts, so the series
+ * reads as "how many times the scheduler opened dispatch permits", not as
+ * event-loop noise.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const schedulerAdmissions = Metric.counter("flows_engine_scheduler_admissions", {
+  description: "Plan scheduler admission passes that launched at least one dispatch"
+})
+
+/**
+ * Latency histogram over one scheduler dispatch, admission through terminal
+ * event: measurement, keying, the durable-action seam, and every rebase turn
+ * of the same node's loop land in a single observation.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const schedulerDispatchDuration = Metric.timer("flows_engine_scheduler_dispatch_duration", {
+  description: "Duration of one scheduler dispatch, admission through terminal event"
+})
+
+/**
+ * Counter over plan node settlements, dimensioned by the scheduler `outcome`
+ * (`built`, `clean`, `failed`, `skipped`, or `deferred`) — the per-node
+ * evaluation vocabulary `PlanScheduler` journals.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const schedulerNodes = Metric.counter("flows_engine_scheduler_nodes", {
+  description: "Plan node settlements by evaluation outcome"
+})
+
+/**
+ * `schedulerNodes` views keyed by `PlanScheduler.Outcome`.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const node = byOutcome(
+  schedulerNodes,
+  {},
+  ["built", "clean", "failed", "skipped", "deferred"] as const
+)
+
+/**
+ * Counter over isolated workspace executions (`WorkspaceSandbox.execute`),
+ * dimensioned by exit `outcome`. An `Invalidated` verdict is a `success`
+ * exit — the transaction ran and answered; the verdict itself is journaled.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const sandboxExecutions = Metric.counter("flows_engine_sandbox_executions", {
+  description: "Isolated workspace executions by exit outcome"
+})
+
+/**
+ * `sandboxExecutions` views keyed by {@link ExitTag}.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const sandboxExecution = byOutcome(sandboxExecutions, {}, exitTags)
+
+/**
+ * Latency histogram over isolated workspace executions.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const sandboxExecutionDuration = Metric.timer("flows_engine_sandbox_execution_duration", {
+  description: "Isolated workspace execution duration"
+})
+
+/**
+ * Counter over sandbox materializations (`WorkspaceSandbox.materialize` —
+ * the one host write), dimensioned by exit `outcome`.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const sandboxMaterializations = Metric.counter("flows_engine_sandbox_materializations", {
+  description: "Sandbox copy-back materializations by exit outcome"
+})
+
+/**
+ * `sandboxMaterializations` views keyed by {@link ExitTag}.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const materialization = byOutcome(sandboxMaterializations, {}, exitTags)
+
+/**
+ * Latency histogram over sandbox materializations.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const materializationDuration = Metric.timer("flows_engine_sandbox_materialization_duration", {
+  description: "Sandbox copy-back materialization duration"
+})
+
+/**
+ * Counter over copy-back compare-and-set refusals: the preflight found host
+ * state that moved after the transaction's base snapshot. The engine answers
+ * one with a rebase or a conflict strategy, so the rate is contention
+ * evidence, not an error rate.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const materializationConflicts = Metric.counter("flows_engine_sandbox_conflicts", {
+  description: "Sandbox copy-back compare-and-set refusals"
+})
+
+/**
+ * Counter over step-boundary settlements at the dispatch seam, dimensioned by
+ * `outcome`: `clean` evidence, an `expected`-mode `deviation`, or a hard
+ * `violation` (undeclared write, missing declared output, surviving declared
+ * removal), with `refused` for a host that could not settle at all.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const boundarySettlements = Metric.counter("flows_engine_boundary_settlements", {
+  description: "Step boundary settlements by outcome"
+})
+
+/**
+ * `boundarySettlements` views keyed by settlement classification.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const boundarySettlement = byOutcome(
+  boundarySettlements,
+  {},
+  ["Clean", "Deviation", "Violation", "Refused"] as const
+)
+
+/**
+ * Counter over the EFFECTIVE step-boundary cache decisions at the dispatch
+ * seam, dimensioned by `outcome`. `flows_step_cache_lookups` counts raw row
+ * presence at `CacheStore.get`; this series records what the dispatch
+ * actually did with the row after read-set verification and output
+ * materialization — `verified_hit` served the cached result, and every other
+ * outcome fell through to a real execution (`miss` no row,
+ * `unverifiable_evidence` a row whose recorded evidence cannot justify reuse,
+ * `unmeasurable` a host that could not re-measure the read set,
+ * `stale_read_set` a measured mismatch, `replay_failed` verified evidence the
+ * host could not re-materialize). Each decision is counted where it takes
+ * effect: `verified_hit` as the cached result is returned, a fall-through
+ * outcome as the dispatch proceeds past its refusal handling — so a
+ * cache-consulting dispatch that fails or is fenced out mid-decision (a
+ * journal failure on the provenance emit, a strict corruption verdict)
+ * records no decision, and its exit lands in {@link dispatches}. At most one
+ * decision is counted per cache-consulting dispatch.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const stepCacheDecisions = Metric.counter("flows_engine_step_cache_decisions", {
+  description: "Effective step-boundary cache decisions at the dispatch seam"
+})
+
+/**
+ * `stepCacheDecisions` views keyed by decision.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const stepCacheDecision = byOutcome(
+  stepCacheDecisions,
+  {},
+  ["VerifiedHit", "Miss", "UnverifiableEvidence", "Unmeasurable", "StaleReadSet", "ReplayFailed"] as const
+)
+
+/**
+ * Counter over the run driver's claim-and-activate decisions, dimensioned by
+ * `outcome`. These are the engine-level decisions taken BEFORE or AFTER the
+ * store-level compare-and-swaps `RunStoreMetrics` counts: a `terminal` or
+ * `heartbeat_fresh` refusal never reaches the store, `steal_refused_owner_alive`
+ * is the liveness probe declining, and `claim_lost`/`activation_lost` are the
+ * driver observing a lost store CAS.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const claims = Metric.counter("flows_engine_claims", {
+  description: "Run driver claim-and-activate decisions by outcome"
+})
+
+/**
+ * `claims` views keyed by driver decision.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const claim = byOutcome(
+  claims,
+  {},
+  ["Activated", "Terminal", "HeartbeatFresh", "StealRefusedOwnerAlive", "ClaimLost", "ActivationLost"] as const
+)

package/src/Errors.ts

@@ -0,0 +1,28 @@
+/**
+ * The public, stable error contract of `@smthrs/engine-store`.
+ *
+ * Every error here carries a `code` literal that is part of the public API:
+ * consumers may switch on `code` (or `_tag`) and the strings will not change
+ * without a major version. The classes themselves are declared next to the
+ * logic that raises them (`internal/ActionPersistence.ts`,
+ * `@smthrs/flow/Action`, and `@smthrs/flow/FlowRuntime`); this module is the
+ * barrel-exported surface so that `internal/` never has to be imported by
+ * consumers.
+ *
+ * Related documentation: `docs/troubleshooting.md` names every code and
+ * what to change; `docs/api.md` carries the schemas.
+ *
+ * @since 0.1.0
+ */
+
+export { IrreversibleRetryRequiresIdempotencyKey } from "@smthrs/flow/Action"
+export { FlowCycleDetected } from "@smthrs/flow/FlowRuntime"
+export {
+  AttemptAdmissionRejected,
+  AttemptEvidenceQuarantined,
+  AttemptSuspended,
+  CacheConflictDetected,
+  CacheCorruptionDetected
+} from "./internal/ActionPersistence.ts"
+export { RetentionError, RetentionErrorCode } from "./internal/RetentionOps.ts"
+export { RunCatalogError, RunCatalogErrorCode } from "./internal/RunCatalogOps.ts"

package/src/EventTypes.ts

@@ -0,0 +1,27 @@
+/**
+ * Stable engine journal record names shared with replay consumers.
+ *
+ * @since 1.0.0
+ */
+
+/**
+ * Persisted event types and the child-spawn effect kind. Writers and readers
+ * share these identities; changing a value requires migrating stored history.
+ * `childSpawnKind` names the effect inside a boundary, not its event type.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export const EventTypes = {
+  runDecision: "flows.engine.run-decision",
+  attemptStarted: "flows.engine.attempt-started",
+  attemptFinished: "flows.engine.attempt-finished",
+  snapshotIdentified: "flows.engine.snapshot-identified",
+  planRecorded: "flows.engine.plan-recorded",
+  subgraphAppended: "flows.engine.subgraph-appended",
+  deferredCompleted: "flows.engine.deferred-completed",
+  deferredConsumed: "flows.engine.deferred-consumed",
+  clockScheduled: "flows.engine.clock-scheduled",
+  clockCompleted: "flows.engine.clock-completed",
+  childSpawnKind: "flows/engine-store/child-spawn"
+} as const

package/src/ExecutionFacts.ts

@@ -0,0 +1,125 @@
+/** Native lifecycle facts captured using the owning store transaction.
+ * @since 1.0.0
+ */
+
+import * as Sha256 from "@smthrs/crypto/Sha256"
+import { FlowEngine } from "@smthrs/engine"
+import { DurableDeferred } from "@smthrs/flow"
+import { ExecutionFact, type Journal, Redaction } from "@smthrs/journal"
+import type { RunStore } from "@smthrs/run-store"
+import { Effect, Option, Schema } from "effect"
+import type * as DurableEngineState from "./DurableEngineState.ts"
+import * as JournalRecords from "./internal/JournalRecords.ts"
+import * as StateTransaction from "./internal/StateTransaction.ts"
+
+/** Captured native services; never substitute an ambient control journal.
+ * @category models
+ * @since 1.0.0
+ */
+export interface Options {
+  readonly runs: RunStore.Service
+  readonly state: Pick<DurableEngineState.Service, "waiting" | "runParents" | "transaction">
+  readonly journal: Journal.Service
+  readonly sourceId: string
+}
+
+/** Read the semantic subset shared with ExecutionSnapshot inside its caller's transaction.
+ * @category queries
+ * @since 1.0.0
+ */
+export const observe = (
+  row: RunStore.RunRow,
+  state: Pick<Options["state"], "waiting" | "runParents">
+): Effect.Effect<ExecutionFact.Observation, Schema.SchemaError> =>
+  Effect.gen(function*() {
+    const waiting = yield* state.waiting(row.runId)
+    const parents = row.parentRunId === null ? yield* state.runParents(row.runId) : []
+    const firstParent = [...parents].sort((a, b) => a.seq - b.seq || a.parentId.localeCompare(b.parentId))[0]
+    const encoded = yield* Schema.decodeUnknownEffect(
+      Schema.fromJsonString(
+        Schema.Struct({
+          flowName: Schema.NonEmptyString,
+          onParentExit: Schema.optional(Schema.Literals(["cancel", "detach"]))
+        })
+      )
+    )(row.stateJson)
+    let point: string | null = null
+    if (Option.isSome(waiting) && waiting.value.token !== null) {
+      try {
+        const { deferredName } = DurableDeferred.TokenParsed.fromString(waiting.value.token)
+        if (deferredName.startsWith("WaitFor/")) {
+          point = deferredName.slice("WaitFor/".length)
+        }
+      } catch { /* An opaque plugin token remains an operational address only. */ }
+    }
+    return yield* Schema.decodeUnknownEffect(ExecutionFact.Observation)({
+      executionId: row.runId,
+      flowName: encoded.flowName,
+      status: row.status,
+      createdAtMs: row.createdAtMs,
+      startedAtMs: row.startedAtMs,
+      finishedAtMs: row.finishedAtMs,
+      parentRunId: row.parentRunId ?? firstParent?.parentId ?? null,
+      lineageId: row.lineageId ?? row.runId,
+      roundOrdinal: row.roundOrdinal ?? 0,
+      cancelRequestedAtMs: row.cancelRequestedAtMs,
+      treeVersion: 1,
+      parentPolicy: encoded.onParentExit ?? "cancel",
+      waiting: Option.isNone(waiting) ? null : {
+        reason: waiting.value.reason,
+        wakeAtMs: waiting.value.wakeAt,
+        tokenDigest: waiting.value.token === null ? null : Sha256.digestSync(waiting.value.token),
+        point,
+        request: waiting.value.request === undefined ? null : Redaction.redact(waiting.value.request)
+      }
+    })
+  })
+
+/** Fact admission and cancellation intent share the same native writer transaction.
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = (options: Options) => {
+  const transactState = StateTransaction.make(options.state, options.journal)
+  const fact = (executionId: string, baseline: "created" | "legacy" = "legacy") =>
+    options.runs.get(executionId).pipe(
+      Effect.flatMap((row) => observe(row, options.state)),
+      Effect.map((observation) => ({ version: 1 as const, baseline, observation })),
+      // Invalid semantic metadata must not prevent the driver's existing
+      // corruption/invalid-round path from settling the run. Record a named
+      // coverage failure; never normalize a bad ordinal or invent ancestry.
+      Effect.catchTag("SchemaError", () =>
+        Effect.succeed({ version: 1 as const, unavailable: "invalid-observation" as const }))
+    )
+  const cancelled = (executionId: string) =>
+    Effect.gen(function*() {
+      const executionFact = yield* fact(executionId)
+      yield* options.journal.emitDurableUnfenced(JournalRecords.runDecision({
+        runId: executionId,
+        lineageId: FlowEngine.Lineage.root(executionId),
+        sourceId: options.sourceId
+      }, { decision: "cancel-requested", executionFact }))
+    })
+  const requestCancel = (executionId: string, at: number) =>
+    transactState(Effect.gen(function*() {
+      const outcome = yield* options.runs.requestCancel(executionId, at)
+      if (outcome._tag === "CancelRequested") yield* cancelled(executionId)
+      return outcome
+    }))
+  const requestCancelLineage = (executionId: string, at: number) =>
+    transactState(Effect.gen(function*() {
+      const before = yield* options.runs.lineage(executionId)
+      const outcome = yield* options.runs.requestCancelLineage(executionId, at)
+      if (outcome._tag === "CancelRequested") {
+        // The set update excludes terminal/already-requested rows. Record exactly
+        // the rows it changed, not a guessed terminal cancellation timestamp.
+        for (const row of before) {
+          if (row.cancelRequestedAtMs === null && !["completed", "failed", "cancelled"].includes(row.status)) {
+            yield* cancelled(row.runId)
+          }
+        }
+      }
+      return outcome
+    }))
+  return { fact, requestCancel, requestCancelLineage }
+}

package/src/ExecutionSnapshot.ts

@@ -0,0 +1,186 @@
+/**
+ * Revisioned, round-scoped engine observations.
+ *
+ * @since 1.0.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import type { RunStoreError } from "@smthrs/run-store/RunStore"
+import { Context, Effect, Layer, Schema } from "effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+import * as Read from "./internal/ExecutionSnapshotRead.ts"
+import * as Relations from "./internal/ExecutionSnapshotRelations.ts"
+
+export type { RelatedOptions, RelatedPage } from "./internal/ExecutionSnapshotRelations.ts"
+
+/**
+ * Engine database identity and observed watermark.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Position = Read.Position
+/**
+ * An authoritative execution row.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Observed = Read.Observed
+/**
+ * A structured durable wait.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Waiting = Read.Waiting
+/**
+ * Absence is explicit; deleted distinguishes retained deletion evidence.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Missing extends Position {
+  readonly _tag: "Missing"
+  readonly runId: string
+  readonly deleted: boolean
+}
+/**
+ * One requested execution observation.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Snapshot = Observed | Missing
+/**
+ * Coherent observations in request order, including duplicates.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Batch extends Position {
+  readonly snapshots: ReadonlyArray<Snapshot>
+}
+/**
+ * Maximum IDs admitted by one read.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const maximumBatchSize = 200
+/**
+ * Reserves a deferred SQLite / repeatable-read PostgreSQL read transaction
+ * without the durable writer's admission lock. An existing transaction is
+ * reused with its caller-selected isolation.
+ * The supplied effect must contain observations only.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const withReadTransaction = Read.transaction
+/**
+ * Engine observation operations.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Service {
+  readonly read: (runIds: ReadonlyArray<string>) => Effect.Effect<Batch, RunStoreError>
+  readonly related: (options: Relations.RelatedOptions) => Effect.Effect<Relations.RelatedPage, RunStoreError>
+}
+/**
+ * Engine observation service.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export class ExecutionSnapshot extends Context.Service<ExecutionSnapshot, Service>()(
+  "@smthrs/engine-store/ExecutionSnapshot"
+) {}
+
+/**
+ * Guard for applying observations and tombstones to a source-bound projection.
+ * Source replacement requires an explicit rebuild, never a revision comparison.
+ * @category guards
+ * @since 1.0.0
+ */
+export const isNewer = (incoming: Position, current: Position): boolean =>
+  incoming.source === current.source && incoming.revision > current.revision
+
+/**
+ * Constructs the SQL read port; migrations must already be applied.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = (): Effect.Effect<Service, never, SqlClient.SqlClient> =>
+  Effect.gen(function*() {
+    const sql = yield* SqlClient.SqlClient
+    const read: Service["read"] = (runIds) =>
+      Read.boundary(
+        "ExecutionSnapshot.read",
+        Effect.gen(function*() {
+          const ids = yield* Read.decode(
+            Schema.Array(Read.Identifier).check(Schema.isMaxLength(maximumBatchSize)),
+            runIds
+          )
+          const batch = yield* Read.transaction(
+            sql,
+            Effect.gen(function*() {
+              const at = yield* Read.position(sql)
+              if (ids.length === 0) return { ...at, snapshots: [] }
+              const rows = yield* Dialect.query(
+                sql,
+                `SELECT ${Read.selectColumns} FROM flows_runs r
+            LEFT JOIN flows_run_changes c ON c.run_id = r.run_id
+            WHERE r.run_id IN (${ids.map(() => "?").join(",")})`,
+                ids
+              )
+              const snapshots = new Map<string, Snapshot>()
+              for (const row of rows) {
+                const value = yield* Read.observed(row, at)
+                snapshots.set(value.runId, value)
+              }
+              const changes = yield* Dialect.query<{ run_id: string; revision: number; deleted: number }>(
+                sql,
+                `SELECT run_id, revision, deleted FROM flows_run_changes WHERE run_id IN (${
+                  ids.map(() => "?").join(",")
+                })`,
+                ids
+              )
+              for (const change of changes) {
+                if (snapshots.has(change.run_id)) continue
+                const revision = yield* Read.decode(
+                  Read.Natural.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(at.revision)),
+                  change.revision
+                )
+                yield* Read.decode(Schema.Literal(1), change.deleted)
+                snapshots.set(change.run_id, {
+                  _tag: "Missing",
+                  runId: change.run_id,
+                  source: at.source,
+                  revision,
+                  deleted: true
+                })
+              }
+              return {
+                ...at,
+                snapshots: ids.map((runId): Snapshot =>
+                  snapshots.get(runId) ?? { _tag: "Missing", runId, ...at, deleted: false }
+                )
+              }
+            })
+          )
+          return yield* Read.coherentBatch(ids, batch)
+        })
+      )
+    return { read, related: Relations.make(sql, read) }
+  })
+
+/**
+ * Provides the SQL observation port.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer: Layer.Layer<ExecutionSnapshot, never, SqlClient.SqlClient> = Layer.effect(ExecutionSnapshot)(make())