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

package/src/RunStoreMetrics.ts

@@ -0,0 +1,165 @@
+/**
+ * Standard metric definitions for fenced run persistence.
+ *
+ * This module only defines the metric handles, following the shape of Effect's
+ * `ClusterMetrics`. `RunStore` updates them as compare-and-swap outcomes are
+ * decided, so every driver that persists through the store — the engine, a
+ * sweeper, a foreign process — lands in the same counters. No exporter ships
+ * in this package; provide one — for example `@smthrs/observability` —
+ * and these counters appear in it.
+ *
+ * Each exported record maps an outcome's `_tag` to an attributed view of the
+ * counter, so an update is a lookup rather than a branch:
+ * `Metric.update(RunStoreMetrics.claim[outcome._tag], 1)`.
+ *
+ * @since 0.1.0
+ */
+
+import * as Metric from "effect/Metric"
+
+/**
+ * Counter over ownership claim compare-and-swaps, dimensioned by `op`
+ * (`claim`, `claim_and_own`, `activate`, `abandon_claim`, `recover_claim`, or
+ * `steal`) and `outcome` (the
+ * operation's result tag in snake case, or `failure` or `interrupt` when the
+ * call did not return one).
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const claims = Metric.counter("flows_run_claims", {
+  description: "Ownership claim compare-and-swaps by operation and outcome"
+})
+
+/**
+ * Counter over fenced run state transitions, dimensioned by `outcome`
+ * (`transitioned`, `fence_lost`, `not_found`, `guard_failed`, `failure`, or
+ * `interrupt`) and `to` (the requested target status).
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const transitions = Metric.counter("flows_run_transitions", {
+  description: "Fenced run state transitions by outcome and target status"
+})
+
+/**
+ * Counter over fenced ownership heartbeats, dimensioned by `outcome`
+ * (`updated`, `fence_lost`, `not_found`, `failure`, or `interrupt`). A
+ * `fence_lost` heartbeat is the fencing event: the writer discovered another
+ * owner holds the run.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const heartbeats = Metric.counter("flows_run_heartbeats", {
+  description: "Fenced ownership heartbeats by outcome"
+})
+
+/** Rewrites an outcome tag (`AlreadyClaimed`) as an attribute value (`already_claimed`). */
+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>> }
+
+const claimTags = ["Claimed", "NotFound", "AlreadyClaimed", "HeartbeatFresh", "SnapshotChanged"] as const
+
+/**
+ * `claims` views for `RunStore.claim`, keyed by `ClaimOutcome` tag.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const claim = byOutcome(claims, { op: "claim" }, claimTags)
+
+/**
+ * `claims` views for `RunStore.claimAndOwn`, keyed by `ClaimAndOwnOutcome`
+ * tag.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const claimAndOwn = byOutcome(
+  claims,
+  { op: "claim_and_own" },
+  ["Activated", "NotFound", "AlreadyClaimed", "HeartbeatFresh", "SnapshotChanged", "EvidenceRequired"] as const
+)
+
+/**
+ * `claims` views for `RunStore.activate`, keyed by `ActivateOutcome` tag. A
+ * `claim_lost` activation is a fencing event: the held claim was recovered or
+ * replaced before the activation ran.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const activate = byOutcome(
+  claims,
+  { op: "activate" },
+  ["Activated", "ClaimLost", "SnapshotChanged"] as const
+)
+
+/**
+ * `claims` views for `RunStore.abandonClaim`, keyed by outcome tag.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.0
+ */
+export const abandonClaim = byOutcome(
+  claims,
+  { op: "abandon_claim" },
+  ["Abandoned", "ClaimLost"] as const
+)
+
+/**
+ * `claims` views for `RunStore.recoverClaim`, keyed by outcome tag.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.0
+ */
+export const recoverClaim = byOutcome(
+  claims,
+  { op: "recover_claim" },
+  ["Recovered", "NotFound", "ClaimFresh", "ClaimChanged", "LivenessUnconfirmed"] as const
+)
+
+/**
+ * `claims` views for `RunStore.steal`, keyed by `StealOutcome` tag.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const steal = byOutcome(
+  claims,
+  { op: "steal" },
+  ["Claimed", "NotFound", "AlreadyClaimed", "HeartbeatFresh", "SnapshotChanged", "LivenessUnconfirmed"] as const
+)
+
+/**
+ * `heartbeats` views keyed by `HeartbeatOutcome` tag.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const heartbeat = byOutcome(heartbeats, {}, ["Updated", "FenceLost", "NotFound"] as const)
+
+/**
+ * `transitions` views keyed by `TransitionOutcome` tag. `RunStore` adds the
+ * `to` attribute at the update site, because the target status is call input
+ * rather than a closed set this module should restate.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const transition = byOutcome(
+  transitions,
+  {},
+  ["Transitioned", "FenceLost", "NotFound", "GuardFailed"] as const
+)

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Durable run state: what is running now, and who owns it.
+ *
+ * `RunStore` and `AttemptStore` hold the executable authoritative state that
+ * recovery reads; `Ownership` supplies the liveness evidence and heartbeat
+ * supervision that arbitrate it. The fencing token they trade in, `OwnerId`,
+ * is defined by `@smthrs/journal`, because the journal is what it fences, and
+ * is re-exported from `Ownership` here, so importing it needs no second
+ * package.
+ *
+ * This entry point is browser-bundleable: every service here is written
+ * against the driver-neutral `@smthrs/database` contract. The test double,
+ * which binds a Node SQLite database, lives under an explicit subpath:
+ *
+ * ```ts
+ * import { AttemptStore, Ownership, RunStore } from "@smthrs/run-store"
+ * import * as TestRunStore from "@smthrs/run-store/test/TestRunStore"
+ * ```
+ *
+ * @since 0.1.0
+ */
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as RunStore from "./RunStore.ts"
+
+/**
+ * @category metrics
+ * @since 0.1.0
+ */
+export * as RunStoreMetrics from "./RunStoreMetrics.ts"
+
+/**
+ * @category ownership
+ * @since 0.1.0
+ */
+export * as Ownership from "./Ownership.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as AttemptStore from "./AttemptStore.ts"
+
+/**
+ * @category migrations
+ * @since 0.1.0
+ */
+export * as Migrations from "./Migrations.ts"

package/src/internal/Boundary.ts

@@ -0,0 +1,130 @@
+/**
+ * Inert text and JSON admission for values crossing run-store boundaries.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+
+import * as BoundedJson from "@smthrs/canonical/BoundedJson"
+
+/**
+ * Maximum UTF-16 length of one durable identifier.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export const maximumIdentifierLength = 1_024
+
+/**
+ * Resource limits for one admitted JSON tree.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export type JsonLimits = Omit<BoundedJson.Limits, "maxTotalMembers">
+
+/**
+ * Detached JSON value accepted by the persistence boundary.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export type Json = BoundedJson.Json
+
+/**
+ * Compares admitted JSON trees while ignoring object key order.
+ *
+ * Array order remains significant. `undefined` represents an absent optional
+ * tree and equals only `undefined`.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export const sameJson = (left: Json | undefined, right: Json | undefined): boolean => {
+  if (left === right) return true
+  if (left === undefined || right === undefined) return false
+  if (left === null || right === null) return false
+  if (typeof left !== "object" || typeof right !== "object") return false
+  if (Array.isArray(left)) {
+    if (!Array.isArray(right) || left.length !== right.length) return false
+    for (let index = 0; index < left.length; index++) {
+      if (!sameJson(left[index], right[index])) return false
+    }
+    return true
+  }
+  if (Array.isArray(right)) return false
+  const leftObject = left as { readonly [key: string]: Json }
+  const rightObject = right as { readonly [key: string]: Json }
+  const leftKeys = Object.keys(leftObject)
+  if (leftKeys.length !== Object.keys(rightObject).length) return false
+  for (const key of leftKeys) {
+    if (!Object.hasOwn(rightObject, key) || !sameJson(leftObject[key], rightObject[key])) return false
+  }
+  return true
+}
+
+/**
+ * Result of admitting or refusing an unknown JSON candidate.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export type JsonResult =
+  | { readonly ok: true; readonly value: Json; readonly bytes: number }
+  | { readonly ok: false; readonly complaint: string }
+
+/**
+ * Whether text has a complete UTF-16 encoding and contains no NUL.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export const isDurableText = (value: unknown, maximum = maximumIdentifierLength): value is string => {
+  if (typeof value !== "string" || value.length === 0 || value.length > maximum || value.includes("\0")) return false
+  for (let index = 0; index < value.length; index++) {
+    const unit = value.charCodeAt(index)
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+      const low = value.charCodeAt(++index)
+      if (!(low >= 0xdc00 && low <= 0xdfff)) return false
+    } else if (unit >= 0xdc00 && unit <= 0xdfff) return false
+  }
+  return true
+}
+
+/**
+ * Copies an inert JSON tree with a cumulative member budget for run state.
+ * @private
+ * @since 1.0.0
+ */
+export const admitJson = (input: unknown, limits: JsonLimits): JsonResult => {
+  const result = BoundedJson.admit(input, { ...limits, maxTotalMembers: limits.maxMembers })
+  return result.ok ? result : { ok: false, complaint: result.complaint }
+}
+
+/**
+ * Parses and bounds JSON text while preserving the caller's original bytes.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export const admitJsonText = (
+  input: unknown,
+  limits: JsonLimits
+):
+  | { readonly ok: true; readonly value: string; readonly json: Json }
+  | { readonly ok: false; readonly complaint: string } =>
+{
+  if (typeof input !== "string" || input.length === 0) return { ok: false, complaint: "must be non-empty JSON text" }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(input) as unknown
+  } catch {
+    return { ok: false, complaint: "must be valid JSON text" }
+  }
+  const admitted = admitJson(parsed, limits)
+  if (!admitted.ok) return admitted
+  if (limits.maxBytes !== undefined && new TextEncoder().encode(input).byteLength > limits.maxBytes) {
+    return { ok: false, complaint: "exceeds the JSON byte limit" }
+  }
+  return { ok: true, value: input, json: admitted.value }
+}

package/src/internal/Companion.ts

@@ -0,0 +1,64 @@
+/**
+ * The run store's companion journal stream.
+ *
+ * Facts the run store records about a run go to the run's `run-store`
+ * companion stream (`JournalEvent.companionRunId`), never to the run's own
+ * stream: engine, control, and time-travel consumers read that stream by
+ * position, and a rewind or compaction of it must not truncate a store fact.
+ *
+ * @since 1.0.0
+ * @private
+ */
+
+import { Journal, type JournalError } from "@smthrs/journal/Journal"
+import * as JournalEvent from "@smthrs/journal/JournalEvent"
+import { Effect, Option } from "effect"
+
+/**
+ * The companion stream name.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const stream = "run-store"
+
+/**
+ * The producer every run-store fact is appended under.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const sourceId = "flows.run-store"
+
+/**
+ * Appends one fact to the run's companion stream through the journal in the
+ * caller's context.
+ *
+ * The journal is resolved at call time: the ordinary composition builds the
+ * store beside the journal (`Layer.mergeAll(SqlJournal.layer(...),
+ * RunStore.layer)`), so the journal reaches the store only through the
+ * caller's context. A caller running without a journal records nothing. The
+ * append is unfenced — the store arbitrated the change in the same serialized
+ * transaction — and joins that transaction as a savepoint, so a rolled-back
+ * change leaves no fact.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const append = (
+  runId: string,
+  eventType: string,
+  payload: Readonly<Record<string, unknown>>
+): Effect.Effect<void, JournalError> =>
+  Effect.flatMap(Effect.serviceOption(Journal), (journal) =>
+    Option.isNone(journal)
+      ? Effect.void
+      : journal.value.emitDurableUnfenced(
+        new JournalEvent.Input({
+          runId: JournalEvent.companionRunId(stream, runId),
+          sourceId: sourceId as JournalEvent.SourceId,
+          eventType,
+          payload: { runId, ...payload },
+          meta: { runId }
+        })
+      ).pipe(Effect.asVoid))

package/src/internal/SpanOutcome.ts

@@ -0,0 +1,71 @@
+/**
+ * Closes every store operation span with an `outcome` attribute, so a trace
+ * viewer never sees a span that ended without saying how. `RunStore` and
+ * `AttemptStore` share these observers so the guide can describe one rule.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+
+import * as Cause from "effect/Cause"
+import * as Effect from "effect/Effect"
+import * as Metric from "effect/Metric"
+
+/** Maps a PascalCase outcome tag to its snake_case span attribute. */
+const outcomeValue = (tag: string): string => tag.replace(/(?<=[a-z0-9])(?=[A-Z])/g, "_").toLowerCase()
+
+/** Classifies a non-success exit for the span `outcome` attribute. */
+const causeOutcome = <E>(cause: Cause.Cause<E>): "failure" | "interrupt" =>
+  Cause.hasInterruptsOnly(cause) ? "interrupt" : "failure"
+
+/**
+ * Observes a store operation's exit onto its span, and, when the operation
+ * has an outcome-keyed counter, updates it in the same observation: the
+ * domain tag (`claimed`, `fence_lost`) on success, `failure` or `interrupt`
+ * otherwise, so a span never closes without saying how and a failed write
+ * still lands in the counter. `exitMetric` is the counter view carrying every
+ * attribute but `outcome`, which this observer adds for a non-success exit.
+ * `Effect.onExit` only reads the exit; the value, cause, and interruption
+ * propagate byte-identically.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export const observeOutcome = <A extends { readonly _tag: string }>(
+  metricOf?: ((outcome: A) => Metric.Metric<number, Metric.CounterState<number>>) | undefined,
+  exitMetric?: Metric.Metric<number, Metric.CounterState<number>> | undefined
+) =>
+<E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  effect.pipe(
+    Effect.onExit((exit) => {
+      if (exit._tag === "Success") {
+        return Effect.annotateCurrentSpan({ outcome: outcomeValue(exit.value._tag) }).pipe(
+          Effect.andThen(metricOf === undefined ? Effect.void : Metric.update(metricOf(exit.value), 1))
+        )
+      }
+      const outcome = causeOutcome(exit.cause)
+      return Effect.annotateCurrentSpan({ outcome }).pipe(
+        Effect.andThen(
+          exitMetric === undefined ? Effect.void : Metric.update(Metric.withAttributes(exitMetric, { outcome }), 1)
+        )
+      )
+    })
+  )
+
+/**
+ * `observeOutcome` for operations whose success carries no domain outcome
+ * tag: `create` inserts or fails, `get` returns the row or fails, and
+ * `acknowledgeCancel` reports whether the guarded update matched. The span
+ * still closes with `success`, `failure`, or `interrupt`.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export const observeExit = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  effect.pipe(
+    Effect.onExit((exit) =>
+      Effect.annotateCurrentSpan({
+        outcome: exit._tag === "Success" ? "success" : causeOutcome(exit.cause)
+      })
+    )
+  )

package/src/migrations/0001_initial.ts

@@ -0,0 +1,114 @@
+/**
+ * Initial durable run and attempt schema.
+ *
+ * @since 0.1.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Creates the `flows_runs` and `flows_attempts` tables and their indexes.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export const initial: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+
+  yield* sql`CREATE TABLE flows_runs (
+    ${Dialect.rowId(sql)}
+    run_id TEXT PRIMARY KEY CHECK (length(run_id) > 0),
+    status TEXT NOT NULL,
+    created_at_ms ${Dialect.integer(sql)} NOT NULL CHECK (${
+    Dialect.isInteger(sql, sql`created_at_ms`)
+  } AND created_at_ms >= 0 AND created_at_ms <= 9007199254740991),
+    started_at_ms ${Dialect.integer(sql)} CHECK (started_at_ms IS NULL OR (${
+    Dialect.isInteger(sql, sql`started_at_ms`)
+  } AND started_at_ms >= 0 AND started_at_ms <= 9007199254740991)),
+    finished_at_ms ${Dialect.integer(sql)} CHECK (finished_at_ms IS NULL OR (${
+    Dialect.isInteger(sql, sql`finished_at_ms`)
+  } AND finished_at_ms >= 0 AND finished_at_ms <= 9007199254740991)),
+    owner_host_id TEXT,
+    owner_pid ${Dialect.integer(sql)},
+    owner_nonce TEXT,
+    heartbeat_at_ms ${Dialect.integer(sql)} CHECK (heartbeat_at_ms IS NULL OR (${
+    Dialect.isInteger(sql, sql`heartbeat_at_ms`)
+  } AND heartbeat_at_ms >= 0 AND heartbeat_at_ms <= 9007199254740991)),
+    claim_host_id TEXT,
+    claim_pid ${Dialect.integer(sql)},
+    claim_nonce TEXT,
+    claimed_at_ms ${Dialect.integer(sql)} CHECK (claimed_at_ms IS NULL OR (${
+    Dialect.isInteger(sql, sql`claimed_at_ms`)
+  } AND claimed_at_ms >= 0 AND claimed_at_ms <= 9007199254740991)),
+    parent_run_id TEXT CHECK (parent_run_id IS NULL OR length(parent_run_id) > 0),
+    cancel_requested_at_ms ${Dialect.integer(sql)} CHECK (cancel_requested_at_ms IS NULL OR (${
+    Dialect.isInteger(sql, sql`cancel_requested_at_ms`)
+  } AND cancel_requested_at_ms >= 0 AND cancel_requested_at_ms <= 9007199254740991)),
+    waiting_reason TEXT CHECK (waiting_reason IS NULL OR length(waiting_reason) > 0),
+    waiting_wake_at_ms ${Dialect.integer(sql)} CHECK (waiting_wake_at_ms IS NULL OR (${
+    Dialect.isInteger(sql, sql`waiting_wake_at_ms`)
+  } AND waiting_wake_at_ms >= 0 AND waiting_wake_at_ms <= 9007199254740991)),
+    waiting_token TEXT CHECK (waiting_token IS NULL OR length(waiting_token) > 0),
+    state_json TEXT NOT NULL CHECK (${Dialect.jsonValid(sql, sql`state_json`)}),
+    CHECK (status IN ('pending', 'running', 'suspended', 'completed', 'failed', 'cancelled')),
+    CHECK (
+      (
+        status = 'running' AND
+        owner_host_id IS NOT NULL AND
+        length(owner_host_id) > 0 AND
+        owner_pid IS NOT NULL AND
+        ${Dialect.isInteger(sql, sql`owner_pid`)} AND owner_pid >= 0 AND
+        owner_nonce IS NOT NULL AND
+        length(owner_nonce) > 0 AND
+        heartbeat_at_ms IS NOT NULL
+      ) OR (
+        status <> 'running' AND
+        owner_host_id IS NULL AND
+        owner_pid IS NULL AND
+        owner_nonce IS NULL AND
+        heartbeat_at_ms IS NULL
+      )
+    ),
+    CHECK (
+      (claim_host_id IS NULL AND claim_pid IS NULL AND claim_nonce IS NULL AND claimed_at_ms IS NULL) OR
+      (claim_host_id IS NOT NULL AND length(claim_host_id) > 0 AND
+       claim_pid IS NOT NULL AND ${Dialect.isInteger(sql, sql`claim_pid`)} AND claim_pid >= 0 AND
+       claim_nonce IS NOT NULL AND length(claim_nonce) > 0 AND claimed_at_ms IS NOT NULL)
+    ),
+    CHECK (
+      (waiting_reason IS NULL AND waiting_wake_at_ms IS NULL AND waiting_token IS NULL) OR
+      waiting_reason IS NOT NULL
+    ),
+    FOREIGN KEY (parent_run_id) REFERENCES flows_runs (run_id)
+  )`
+
+  yield* sql`CREATE INDEX flows_runs_parent_run_id_idx ON flows_runs (parent_run_id)`
+  yield* sql`CREATE INDEX flows_runs_cancel_requested_idx ON flows_runs (cancel_requested_at_ms) WHERE cancel_requested_at_ms IS NOT NULL`
+  yield* sql`CREATE INDEX flows_runs_waiting_reason_wake_at_idx ON flows_runs (waiting_reason, waiting_wake_at_ms) WHERE waiting_reason IS NOT NULL`
+
+  yield* sql`CREATE TABLE flows_attempts (
+    run_id TEXT NOT NULL CHECK (length(run_id) > 0),
+    step_key_digest TEXT NOT NULL CHECK (length(step_key_digest) > 0),
+    attempt ${Dialect.integer(sql)} NOT NULL CHECK (${
+    Dialect.isInteger(sql, sql`attempt`)
+  } AND attempt >= 0 AND attempt <= 9007199254740991),
+    state TEXT NOT NULL CHECK (length(state) > 0),
+    started_at_ms ${Dialect.integer(sql)} NOT NULL CHECK (${
+    Dialect.isInteger(sql, sql`started_at_ms`)
+  } AND started_at_ms >= 0 AND started_at_ms <= 9007199254740991),
+    finished_at_ms ${Dialect.integer(sql)} CHECK (finished_at_ms IS NULL OR (${
+    Dialect.isInteger(sql, sql`finished_at_ms`)
+  } AND finished_at_ms >= 0 AND finished_at_ms <= 9007199254740991)),
+    heartbeat_at_ms ${Dialect.integer(sql)} CHECK (heartbeat_at_ms IS NULL OR (${
+    Dialect.isInteger(sql, sql`heartbeat_at_ms`)
+  } AND heartbeat_at_ms >= 0 AND heartbeat_at_ms <= 9007199254740991)),
+    checkpoint_json TEXT CHECK (checkpoint_json IS NULL OR ${Dialect.jsonValid(sql, sql`checkpoint_json`)}),
+    error_json TEXT CHECK (error_json IS NULL OR ${Dialect.jsonValid(sql, sql`error_json`)}),
+    outcome_json TEXT CHECK (outcome_json IS NULL OR ${Dialect.jsonValid(sql, sql`outcome_json`)}),
+    meta_json TEXT NOT NULL CHECK (${Dialect.jsonValid(sql, sql`meta_json`)}),
+    PRIMARY KEY (run_id, step_key_digest, attempt),
+    FOREIGN KEY (run_id) REFERENCES flows_runs (run_id)
+  )`
+})

package/src/migrations/0002_lineage.ts

@@ -0,0 +1,38 @@
+/**
+ * Trampoline lineage columns on `flows_runs`.
+ *
+ * A round is its own run row, chained to the previous round through the `parent_run_id`
+ * column this table already reserved for continue-as-new, and these two
+ * columns are what make the chain readable as a lineage rather than as an
+ * anonymous ancestry: which lineage a round belongs to, and which round of it
+ * this is. They are NOT `flows_run_parents` edges — that table is the subflow
+ * DAG cycle detection walks, and a lineage is a chain of successive
+ * executions of one run rather than a parent spawning a child.
+ *
+ * Append-only, as every migration after the first must be: both columns are
+ * nullable, so every row an earlier build wrote stays valid and reads back as
+ * "round 0 of its own lineage".
+ *
+ * @since 0.1.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Adds `lineage_id` and `round_ordinal` to `flows_runs` and indexes the pair.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export const lineage: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+
+  yield* sql`ALTER TABLE flows_runs ADD COLUMN lineage_id TEXT CHECK (lineage_id IS NULL OR length(lineage_id) > 0)`
+  yield* sql`ALTER TABLE flows_runs ADD COLUMN round_ordinal ${Dialect.integer(sql)} CHECK (round_ordinal IS NULL OR (${
+    Dialect.isInteger(sql, sql`round_ordinal`)
+  } AND round_ordinal >= 0 AND round_ordinal <= 9007199254740991))`
+
+  yield* sql`CREATE UNIQUE INDEX flows_runs_lineage_idx ON flows_runs (lineage_id, round_ordinal)`
+})