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

package/dist/esm/migrations/0001_initial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"0001_initial.js","sourceRoot":"","sources":["../../../src/migrations/0001_initial.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Initial durable run and attempt schema.\n *\n * @since 0.1.0\n */\n\nimport * as Dialect from \"@smthrs/database/Dialect\"\nimport * as Effect from \"effect/Effect\"\nimport * as SqlClient from \"effect/unstable/sql/SqlClient\"\n\n/**\n * Creates the `flows_runs` and `flows_attempts` tables and their indexes.\n *\n * @category migrations\n * @since 0.1.0\n */\nexport const initial: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {\n  const sql = yield* SqlClient.SqlClient\n\n  yield* sql`CREATE TABLE flows_runs (\n    ${Dialect.rowId(sql)}\n    run_id TEXT PRIMARY KEY CHECK (length(run_id) > 0),\n    status TEXT NOT NULL,\n    created_at_ms ${Dialect.integer(sql)} NOT NULL CHECK (${\n    Dialect.isInteger(sql, sql`created_at_ms`)\n  } AND created_at_ms >= 0 AND created_at_ms <= 9007199254740991),\n    started_at_ms ${Dialect.integer(sql)} CHECK (started_at_ms IS NULL OR (${\n    Dialect.isInteger(sql, sql`started_at_ms`)\n  } AND started_at_ms >= 0 AND started_at_ms <= 9007199254740991)),\n    finished_at_ms ${Dialect.integer(sql)} CHECK (finished_at_ms IS NULL OR (${\n    Dialect.isInteger(sql, sql`finished_at_ms`)\n  } AND finished_at_ms >= 0 AND finished_at_ms <= 9007199254740991)),\n    owner_host_id TEXT,\n    owner_pid ${Dialect.integer(sql)},\n    owner_nonce TEXT,\n    heartbeat_at_ms ${Dialect.integer(sql)} CHECK (heartbeat_at_ms IS NULL OR (${\n    Dialect.isInteger(sql, sql`heartbeat_at_ms`)\n  } AND heartbeat_at_ms >= 0 AND heartbeat_at_ms <= 9007199254740991)),\n    claim_host_id TEXT,\n    claim_pid ${Dialect.integer(sql)},\n    claim_nonce TEXT,\n    claimed_at_ms ${Dialect.integer(sql)} CHECK (claimed_at_ms IS NULL OR (${\n    Dialect.isInteger(sql, sql`claimed_at_ms`)\n  } AND claimed_at_ms >= 0 AND claimed_at_ms <= 9007199254740991)),\n    parent_run_id TEXT CHECK (parent_run_id IS NULL OR length(parent_run_id) > 0),\n    cancel_requested_at_ms ${Dialect.integer(sql)} CHECK (cancel_requested_at_ms IS NULL OR (${\n    Dialect.isInteger(sql, sql`cancel_requested_at_ms`)\n  } AND cancel_requested_at_ms >= 0 AND cancel_requested_at_ms <= 9007199254740991)),\n    waiting_reason TEXT CHECK (waiting_reason IS NULL OR length(waiting_reason) > 0),\n    waiting_wake_at_ms ${Dialect.integer(sql)} CHECK (waiting_wake_at_ms IS NULL OR (${\n    Dialect.isInteger(sql, sql`waiting_wake_at_ms`)\n  } AND waiting_wake_at_ms >= 0 AND waiting_wake_at_ms <= 9007199254740991)),\n    waiting_token TEXT CHECK (waiting_token IS NULL OR length(waiting_token) > 0),\n    state_json TEXT NOT NULL CHECK (${Dialect.jsonValid(sql, sql`state_json`)}),\n    CHECK (status IN ('pending', 'running', 'suspended', 'completed', 'failed', 'cancelled')),\n    CHECK (\n      (\n        status = 'running' AND\n        owner_host_id IS NOT NULL AND\n        length(owner_host_id) > 0 AND\n        owner_pid IS NOT NULL AND\n        ${Dialect.isInteger(sql, sql`owner_pid`)} AND owner_pid >= 0 AND\n        owner_nonce IS NOT NULL AND\n        length(owner_nonce) > 0 AND\n        heartbeat_at_ms IS NOT NULL\n      ) OR (\n        status <> 'running' AND\n        owner_host_id IS NULL AND\n        owner_pid IS NULL AND\n        owner_nonce IS NULL AND\n        heartbeat_at_ms IS NULL\n      )\n    ),\n    CHECK (\n      (claim_host_id IS NULL AND claim_pid IS NULL AND claim_nonce IS NULL AND claimed_at_ms IS NULL) OR\n      (claim_host_id IS NOT NULL AND length(claim_host_id) > 0 AND\n       claim_pid IS NOT NULL AND ${Dialect.isInteger(sql, sql`claim_pid`)} AND claim_pid >= 0 AND\n       claim_nonce IS NOT NULL AND length(claim_nonce) > 0 AND claimed_at_ms IS NOT NULL)\n    ),\n    CHECK (\n      (waiting_reason IS NULL AND waiting_wake_at_ms IS NULL AND waiting_token IS NULL) OR\n      waiting_reason IS NOT NULL\n    ),\n    FOREIGN KEY (parent_run_id) REFERENCES flows_runs (run_id)\n  )`\n\n  yield* sql`CREATE INDEX flows_runs_parent_run_id_idx ON flows_runs (parent_run_id)`\n  yield* sql`CREATE INDEX flows_runs_cancel_requested_idx ON flows_runs (cancel_requested_at_ms) WHERE cancel_requested_at_ms IS NOT NULL`\n  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`\n\n  yield* sql`CREATE TABLE flows_attempts (\n    run_id TEXT NOT NULL CHECK (length(run_id) > 0),\n    step_key_digest TEXT NOT NULL CHECK (length(step_key_digest) > 0),\n    attempt ${Dialect.integer(sql)} NOT NULL CHECK (${\n    Dialect.isInteger(sql, sql`attempt`)\n  } AND attempt >= 0 AND attempt <= 9007199254740991),\n    state TEXT NOT NULL CHECK (length(state) > 0),\n    started_at_ms ${Dialect.integer(sql)} NOT NULL CHECK (${\n    Dialect.isInteger(sql, sql`started_at_ms`)\n  } AND started_at_ms >= 0 AND started_at_ms <= 9007199254740991),\n    finished_at_ms ${Dialect.integer(sql)} CHECK (finished_at_ms IS NULL OR (${\n    Dialect.isInteger(sql, sql`finished_at_ms`)\n  } AND finished_at_ms >= 0 AND finished_at_ms <= 9007199254740991)),\n    heartbeat_at_ms ${Dialect.integer(sql)} CHECK (heartbeat_at_ms IS NULL OR (${\n    Dialect.isInteger(sql, sql`heartbeat_at_ms`)\n  } AND heartbeat_at_ms >= 0 AND heartbeat_at_ms <= 9007199254740991)),\n    checkpoint_json TEXT CHECK (checkpoint_json IS NULL OR ${Dialect.jsonValid(sql, sql`checkpoint_json`)}),\n    error_json TEXT CHECK (error_json IS NULL OR ${Dialect.jsonValid(sql, sql`error_json`)}),\n    outcome_json TEXT CHECK (outcome_json IS NULL OR ${Dialect.jsonValid(sql, sql`outcome_json`)}),\n    meta_json TEXT NOT NULL CHECK (${Dialect.jsonValid(sql, sql`meta_json`)}),\n    PRIMARY KEY (run_id, step_key_digest, attempt),\n    FOREIGN KEY (run_id) REFERENCES flows_runs (run_id)\n  )`\n})\n"]}

package/dist/esm/migrations/0002_lineage.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 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 declare const lineage: Effect.Effect<void, unknown, SqlClient.SqlClient>;
+//# sourceMappingURL=0002_lineage.d.ts.map

package/dist/esm/migrations/0002_lineage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"0002_lineage.d.ts","sourceRoot":"","sources":["../../../src/migrations/0002_lineage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,SAAS,CASpE,CAAA"}

package/dist/esm/migrations/0002_lineage.js

@@ -0,0 +1,33 @@
+/**
+ * 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.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)`;
+});
+//# sourceMappingURL=0002_lineage.js.map

package/dist/esm/migrations/0002_lineage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"0002_lineage.js","sourceRoot":"","sources":["../../../src/migrations/0002_lineage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAA;AACnD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAsD,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAC5F,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,CAAA;IAEtC,KAAK,CAAC,CAAC,GAAG,CAAA,wGAAwG,CAAA;IAClH,KAAK,CAAC,CAAC,GAAG,CAAA,mDAAmD,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,qCAC/E,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAA,eAAe,CAC3C,iEAAiE,CAAA;IAEjE,KAAK,CAAC,CAAC,GAAG,CAAA,sFAAsF,CAAA;AAClG,CAAC,CAAC,CAAA","sourcesContent":["/**\n * Trampoline lineage columns on `flows_runs`.\n *\n * A round is its own run row, chained to the previous round through the `parent_run_id`\n * column this table already reserved for continue-as-new, and these two\n * columns are what make the chain readable as a lineage rather than as an\n * anonymous ancestry: which lineage a round belongs to, and which round of it\n * this is. They are NOT `flows_run_parents` edges — that table is the subflow\n * DAG cycle detection walks, and a lineage is a chain of successive\n * executions of one run rather than a parent spawning a child.\n *\n * Append-only, as every migration after the first must be: both columns are\n * nullable, so every row an earlier build wrote stays valid and reads back as\n * \"round 0 of its own lineage\".\n *\n * @since 0.1.0\n */\n\nimport * as Dialect from \"@smthrs/database/Dialect\"\nimport * as Effect from \"effect/Effect\"\nimport * as SqlClient from \"effect/unstable/sql/SqlClient\"\n\n/**\n * Adds `lineage_id` and `round_ordinal` to `flows_runs` and indexes the pair.\n *\n * @category migrations\n * @since 0.1.0\n */\nexport const lineage: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {\n  const sql = yield* SqlClient.SqlClient\n\n  yield* sql`ALTER TABLE flows_runs ADD COLUMN lineage_id TEXT CHECK (lineage_id IS NULL OR length(lineage_id) > 0)`\n  yield* sql`ALTER TABLE flows_runs ADD COLUMN round_ordinal ${Dialect.integer(sql)} CHECK (round_ordinal IS NULL OR (${\n    Dialect.isInteger(sql, sql`round_ordinal`)\n  } AND round_ordinal >= 0 AND round_ordinal <= 9007199254740991))`\n\n  yield* sql`CREATE UNIQUE INDEX flows_runs_lineage_idx ON flows_runs (lineage_id, round_ordinal)`\n})\n"]}

package/dist/esm/migrations/0003_execution_revisions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Durable database identity and coalesced execution change tracking.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+/**
+ * Retains one current revision per run ID, including deleted IDs forever.
+ * Triggers participate in the mutating transaction, including raw SQL writes.
+ * @category migrations
+ * @since 1.0.0
+ */
+export declare const executionRevisions: Effect.Effect<void, unknown, SqlClient.SqlClient>;
+//# sourceMappingURL=0003_execution_revisions.d.ts.map

package/dist/esm/migrations/0003_execution_revisions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"0003_execution_revisions.d.ts","sourceRoot":"","sources":["../../../src/migrations/0003_execution_revisions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,SAAS,CAoD/E,CAAA"}

package/dist/esm/migrations/0003_execution_revisions.js

@@ -0,0 +1,58 @@
+/**
+ * Durable database identity and coalesced execution change tracking.
+ *
+ * @since 1.0.0
+ */
+import * as Dialect from "@smthrs/database/Dialect";
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+/**
+ * Retains one current revision per run ID, including deleted IDs forever.
+ * Triggers participate in the mutating transaction, including raw SQL writes.
+ * @category migrations
+ * @since 1.0.0
+ */
+export const executionRevisions = Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql `CREATE TABLE flows_run_source (
+    singleton ${Dialect.integer(sql)} PRIMARY KEY CHECK (singleton = 1),
+    source TEXT NOT NULL CHECK (length(source) = 32 AND ${sql.literal(Dialect.isPostgres(sql) ? "source !~ '[^0-9a-f]'" : "source NOT GLOB '*[^0-9a-f]*'")}),
+    revision ${Dialect.integer(sql)} NOT NULL CHECK (${Dialect.isInteger(sql, sql `revision`)} AND revision >= 0 AND revision <= 9007199254740991)
+  )`;
+    yield* sql `INSERT INTO flows_run_source VALUES (1, ${sql.literal(Dialect.isPostgres(sql) ? "replace(gen_random_uuid()::text, '-', '')" : "lower(hex(randomblob(16)))")}, 0)`;
+    yield* sql `CREATE TABLE flows_run_changes (
+    run_id TEXT PRIMARY KEY NOT NULL CHECK (length(run_id) > 0),
+    revision ${Dialect.integer(sql)} NOT NULL UNIQUE CHECK (${Dialect.isInteger(sql, sql `revision`)} AND revision > 0 AND revision <= 9007199254740991),
+    deleted ${Dialect.integer(sql)} NOT NULL CHECK (deleted IN (0, 1))
+  )`;
+    yield* sql `ALTER TABLE flows_runs ADD COLUMN cancel_acknowledgement_json TEXT
+    CHECK (cancel_acknowledgement_json IS NULL OR ${Dialect.jsonValid(sql, sql `cancel_acknowledgement_json`)})`;
+    // Old rows receive a real baseline revision; their prior mutation order is unknown.
+    yield* sql `INSERT INTO flows_run_changes (run_id, revision, deleted)
+    SELECT run_id, ROW_NUMBER() OVER (ORDER BY created_at_ms, run_id), 0 FROM flows_runs`;
+    yield* sql `UPDATE flows_run_source SET revision = (SELECT COUNT(*) FROM flows_run_changes)`;
+    for (const [operation, row, deleted] of [["INSERT", "NEW", 0], ["UPDATE", "NEW", 0], ["DELETE", "OLD", 1]]) {
+        yield* Dialect.trigger(sql, {
+            name: `flows_runs_revision_${operation.toLowerCase()}`,
+            table: "flows_runs",
+            event: `AFTER ${operation}`,
+            body: `
+        ${Dialect.isPostgres(sql)
+                ? "IF NOT EXISTS (SELECT 1 FROM flows_run_source WHERE singleton = 1) THEN RAISE EXCEPTION 'execution source identity is missing' USING ERRCODE = '23514'; END IF;"
+                : "SELECT CASE WHEN NOT EXISTS (SELECT 1 FROM flows_run_source WHERE singleton = 1) THEN RAISE(ABORT, 'execution source identity is missing') END;"}
+        UPDATE flows_run_source SET revision = revision + 1 WHERE singleton = 1;
+        INSERT INTO flows_run_changes (run_id, revision, deleted)
+          SELECT ${row}.run_id, revision, ${deleted} FROM flows_run_source WHERE singleton = 1
+          ON CONFLICT (run_id) DO UPDATE SET revision = excluded.revision, deleted = excluded.deleted;
+      `
+        });
+    }
+    yield* Dialect.trigger(sql, {
+        name: `flows_runs_identity_immutable`,
+        table: `flows_runs`,
+        event: "BEFORE UPDATE OF run_id",
+        when: `NEW.run_id <> OLD.run_id`,
+        reject: "run identity is immutable"
+    });
+});
+//# sourceMappingURL=0003_execution_revisions.js.map

package/dist/esm/migrations/0003_execution_revisions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"0003_execution_revisions.js","sourceRoot":"","sources":["../../../src/migrations/0003_execution_revisions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAA;AACnD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAsD,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IACvG,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,CAAA;IACtC,KAAK,CAAC,CAAC,GAAG,CAAA;gBACI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;0DAEhC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,+BAA+B,CACjG;eACa,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,oBAC/B,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAA,UAAU,CACtC;IACE,CAAA;IACF,KAAK,CAAC,CAAC,GAAG,CAAA,2CACR,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,2CAA2C,CAAC,CAAC,CAAC,4BAA4B,CAClH,MAAM,CAAA;IACN,KAAK,CAAC,CAAC,GAAG,CAAA;;eAEG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,2BAC/B,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAA,UAAU,CACtC;cACY,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;IAC9B,CAAA;IACF,KAAK,CAAC,CAAC,GAAG,CAAA;oDACwC,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAA,6BAA6B,CAAC,GAAG,CAAA;IAC7G,oFAAoF;IACpF,KAAK,CAAC,CAAC,GAAG,CAAA;yFAC6E,CAAA;IACvF,KAAK,CAAC,CAAC,GAAG,CAAA,iFAAiF,CAAA;IAC3F,KAAK,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAU,EAAE,CAAC;QACpH,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;YAC1B,IAAI,EAAE,uBAAuB,SAAS,CAAC,WAAW,EAAE,EAAE;YACtD,KAAK,EAAE,YAAY;YACnB,KAAK,EAAE,SAAS,SAAS,EAAE;YAC3B,IAAI,EAAE;UAEJ,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;gBACrB,CAAC,CAAC,iKAAiK;gBACnK,CAAC,CAAC,iJACN;;;mBAGa,GAAG,sBAAsB,OAAO;;OAE5C;SACF,CAAC,CAAA;IACJ,CAAC;IACD,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;QAC1B,IAAI,EAAE,+BAA+B;QACrC,KAAK,EAAE,YAAY;QACnB,KAAK,EAAE,yBAAyB;QAChC,IAAI,EAAE,0BAA0B;QAChC,MAAM,EAAE,2BAA2B;KACpC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA","sourcesContent":["/**\n * Durable database identity and coalesced execution change tracking.\n *\n * @since 1.0.0\n */\n\nimport * as Dialect from \"@smthrs/database/Dialect\"\nimport * as Effect from \"effect/Effect\"\nimport * as SqlClient from \"effect/unstable/sql/SqlClient\"\n\n/**\n * Retains one current revision per run ID, including deleted IDs forever.\n * Triggers participate in the mutating transaction, including raw SQL writes.\n * @category migrations\n * @since 1.0.0\n */\nexport const executionRevisions: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {\n  const sql = yield* SqlClient.SqlClient\n  yield* sql`CREATE TABLE flows_run_source (\n    singleton ${Dialect.integer(sql)} PRIMARY KEY CHECK (singleton = 1),\n    source TEXT NOT NULL CHECK (length(source) = 32 AND ${\n    sql.literal(Dialect.isPostgres(sql) ? \"source !~ '[^0-9a-f]'\" : \"source NOT GLOB '*[^0-9a-f]*'\")\n  }),\n    revision ${Dialect.integer(sql)} NOT NULL CHECK (${\n    Dialect.isInteger(sql, sql`revision`)\n  } AND revision >= 0 AND revision <= 9007199254740991)\n  )`\n  yield* sql`INSERT INTO flows_run_source VALUES (1, ${\n    sql.literal(Dialect.isPostgres(sql) ? \"replace(gen_random_uuid()::text, '-', '')\" : \"lower(hex(randomblob(16)))\")\n  }, 0)`\n  yield* sql`CREATE TABLE flows_run_changes (\n    run_id TEXT PRIMARY KEY NOT NULL CHECK (length(run_id) > 0),\n    revision ${Dialect.integer(sql)} NOT NULL UNIQUE CHECK (${\n    Dialect.isInteger(sql, sql`revision`)\n  } AND revision > 0 AND revision <= 9007199254740991),\n    deleted ${Dialect.integer(sql)} NOT NULL CHECK (deleted IN (0, 1))\n  )`\n  yield* sql`ALTER TABLE flows_runs ADD COLUMN cancel_acknowledgement_json TEXT\n    CHECK (cancel_acknowledgement_json IS NULL OR ${Dialect.jsonValid(sql, sql`cancel_acknowledgement_json`)})`\n  // Old rows receive a real baseline revision; their prior mutation order is unknown.\n  yield* sql`INSERT INTO flows_run_changes (run_id, revision, deleted)\n    SELECT run_id, ROW_NUMBER() OVER (ORDER BY created_at_ms, run_id), 0 FROM flows_runs`\n  yield* sql`UPDATE flows_run_source SET revision = (SELECT COUNT(*) FROM flows_run_changes)`\n  for (const [operation, row, deleted] of [[\"INSERT\", \"NEW\", 0], [\"UPDATE\", \"NEW\", 0], [\"DELETE\", \"OLD\", 1]] as const) {\n    yield* Dialect.trigger(sql, {\n      name: `flows_runs_revision_${operation.toLowerCase()}`,\n      table: \"flows_runs\",\n      event: `AFTER ${operation}`,\n      body: `\n        ${\n        Dialect.isPostgres(sql)\n          ? \"IF NOT EXISTS (SELECT 1 FROM flows_run_source WHERE singleton = 1) THEN RAISE EXCEPTION 'execution source identity is missing' USING ERRCODE = '23514'; END IF;\"\n          : \"SELECT CASE WHEN NOT EXISTS (SELECT 1 FROM flows_run_source WHERE singleton = 1) THEN RAISE(ABORT, 'execution source identity is missing') END;\"\n      }\n        UPDATE flows_run_source SET revision = revision + 1 WHERE singleton = 1;\n        INSERT INTO flows_run_changes (run_id, revision, deleted)\n          SELECT ${row}.run_id, revision, ${deleted} FROM flows_run_source WHERE singleton = 1\n          ON CONFLICT (run_id) DO UPDATE SET revision = excluded.revision, deleted = excluded.deleted;\n      `\n    })\n  }\n  yield* Dialect.trigger(sql, {\n    name: `flows_runs_identity_immutable`,\n    table: `flows_runs`,\n    event: \"BEFORE UPDATE OF run_id\",\n    when: `NEW.run_id <> OLD.run_id`,\n    reject: \"run identity is immutable\"\n  })\n})\n"]}

package/dist/esm/migrations/0004_waiting_request.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The question a parked run is waiting on an answer to.
+ *
+ * `waiting_reason` and `waiting_token` say THAT a run is parked on a human
+ * decision and which wait point holds it; neither says what was asked. A
+ * `HumanTask` park therefore left the prompt, the kind of answer it wants, and
+ * the attempt budget nowhere a reader could find them: the question lived only
+ * in the action payload of an execution that had already released its owner,
+ * so the approvals inbox could describe the gate as "something is waiting" and
+ * no more (run-3, `coding-clarification`).
+ *
+ * This column is that missing half. It is the JSON the wait declared about
+ * itself — for `HumanTask`, `{kind, name, prompt, attempt, maxAttempts}` — and
+ * it is written and cleared with the other three waiting columns, so it can
+ * never describe a wait the run is no longer holding.
+ *
+ * Append-only, as every migration after the first must be: the column is
+ * nullable, so every row an earlier build wrote stays valid and reads back as
+ * a park that declared no question.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+/**
+ * Adds `waiting_request` to `flows_runs`.
+ *
+ * @category migrations
+ * @since 1.0.0
+ */
+export declare const waitingRequest: Effect.Effect<void, unknown, SqlClient.SqlClient>;
+//# sourceMappingURL=0004_waiting_request.d.ts.map

package/dist/esm/migrations/0004_waiting_request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"0004_waiting_request.d.ts","sourceRoot":"","sources":["../../../src/migrations/0004_waiting_request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,SAAS,CAK3E,CAAA"}

package/dist/esm/migrations/0004_waiting_request.js

@@ -0,0 +1,37 @@
+/**
+ * The question a parked run is waiting on an answer to.
+ *
+ * `waiting_reason` and `waiting_token` say THAT a run is parked on a human
+ * decision and which wait point holds it; neither says what was asked. A
+ * `HumanTask` park therefore left the prompt, the kind of answer it wants, and
+ * the attempt budget nowhere a reader could find them: the question lived only
+ * in the action payload of an execution that had already released its owner,
+ * so the approvals inbox could describe the gate as "something is waiting" and
+ * no more (run-3, `coding-clarification`).
+ *
+ * This column is that missing half. It is the JSON the wait declared about
+ * itself — for `HumanTask`, `{kind, name, prompt, attempt, maxAttempts}` — and
+ * it is written and cleared with the other three waiting columns, so it can
+ * never describe a wait the run is no longer holding.
+ *
+ * Append-only, as every migration after the first must be: the column is
+ * nullable, so every row an earlier build wrote stays valid and reads back as
+ * a park that declared no question.
+ *
+ * @since 1.0.0
+ */
+import * as Dialect from "@smthrs/database/Dialect";
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+/**
+ * Adds `waiting_request` to `flows_runs`.
+ *
+ * @category migrations
+ * @since 1.0.0
+ */
+export const waitingRequest = Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql `ALTER TABLE flows_runs ADD COLUMN waiting_request TEXT
+    CHECK (waiting_request IS NULL OR ${Dialect.jsonValid(sql, sql `waiting_request`)})`;
+});
+//# sourceMappingURL=0004_waiting_request.js.map

package/dist/esm/migrations/0004_waiting_request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"0004_waiting_request.js","sourceRoot":"","sources":["../../../src/migrations/0004_waiting_request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAA;AACnD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsD,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IACnG,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,CAAA;IAEtC,KAAK,CAAC,CAAC,GAAG,CAAA;wCAC4B,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAA,iBAAiB,CAAC,GAAG,CAAA;AACvF,CAAC,CAAC,CAAA","sourcesContent":["/**\n * The question a parked run is waiting on an answer to.\n *\n * `waiting_reason` and `waiting_token` say THAT a run is parked on a human\n * decision and which wait point holds it; neither says what was asked. A\n * `HumanTask` park therefore left the prompt, the kind of answer it wants, and\n * the attempt budget nowhere a reader could find them: the question lived only\n * in the action payload of an execution that had already released its owner,\n * so the approvals inbox could describe the gate as \"something is waiting\" and\n * no more (run-3, `coding-clarification`).\n *\n * This column is that missing half. It is the JSON the wait declared about\n * itself — for `HumanTask`, `{kind, name, prompt, attempt, maxAttempts}` — and\n * it is written and cleared with the other three waiting columns, so it can\n * never describe a wait the run is no longer holding.\n *\n * Append-only, as every migration after the first must be: the column is\n * nullable, so every row an earlier build wrote stays valid and reads back as\n * a park that declared no question.\n *\n * @since 1.0.0\n */\n\nimport * as Dialect from \"@smthrs/database/Dialect\"\nimport * as Effect from \"effect/Effect\"\nimport * as SqlClient from \"effect/unstable/sql/SqlClient\"\n\n/**\n * Adds `waiting_request` to `flows_runs`.\n *\n * @category migrations\n * @since 1.0.0\n */\nexport const waitingRequest: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {\n  const sql = yield* SqlClient.SqlClient\n\n  yield* sql`ALTER TABLE flows_runs ADD COLUMN waiting_request TEXT\n    CHECK (waiting_request IS NULL OR ${Dialect.jsonValid(sql, sql`waiting_request`)})`\n})\n"]}

package/dist/esm/test/TestRunStore.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Deterministic bundle of the production run and attempt services.
+ *
+ * @since 0.1.0
+ */
+import * as Layer from "effect/Layer";
+import * as AttemptStore from "../AttemptStore.ts";
+import * as RunStore from "../RunStore.ts";
+/**
+ * Provides the production SQLite run and attempt stores over an in-memory
+ * database. Migrations run before either service is exposed.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<AttemptStore.AttemptStore | RunStore.RunStore, import("effect/unstable/sql/SqlError").SqlError | import("effect/unstable/sql/Migrator").MigrationError, never>;
+//# sourceMappingURL=TestRunStore.d.ts.map

package/dist/esm/test/TestRunStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestRunStore.d.ts","sourceRoot":"","sources":["../../../src/test/TestRunStore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAA;AAElD,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,4KAEjB,CAAA"}

package/dist/esm/test/TestRunStore.js

@@ -0,0 +1,19 @@
+/**
+ * Deterministic bundle of the production run and attempt services.
+ *
+ * @since 0.1.0
+ */
+import * as TestDatabase from "@smthrs/database/test/TestDatabase";
+import * as Layer from "effect/Layer";
+import * as AttemptStore from "../AttemptStore.js";
+import * as Migrations from "../Migrations.js";
+import * as RunStore from "../RunStore.js";
+/**
+ * Provides the production SQLite run and attempt stores over an in-memory
+ * database. Migrations run before either service is exposed.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = Layer.mergeAll(RunStore.layer, AttemptStore.layer).pipe(Layer.provide(Layer.provideMerge(Migrations.layer, TestDatabase.layer)));
+//# sourceMappingURL=TestRunStore.js.map

package/dist/esm/test/TestRunStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestRunStore.js","sourceRoot":"","sources":["../../../src/test/TestRunStore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,YAAY,MAAM,oCAAoC,CAAA;AAClE,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,IAAI,CAC1E,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CACxE,CAAA","sourcesContent":["/**\n * Deterministic bundle of the production run and attempt services.\n *\n * @since 0.1.0\n */\n\nimport * as TestDatabase from \"@smthrs/database/test/TestDatabase\"\nimport * as Layer from \"effect/Layer\"\nimport * as AttemptStore from \"../AttemptStore.ts\"\nimport * as Migrations from \"../Migrations.ts\"\nimport * as RunStore from \"../RunStore.ts\"\n\n/**\n * Provides the production SQLite run and attempt stores over an in-memory\n * database. Migrations run before either service is exposed.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer = Layer.mergeAll(RunStore.layer, AttemptStore.layer).pipe(\n  Layer.provide(Layer.provideMerge(Migrations.layer, TestDatabase.layer))\n)\n"]}

package/docs/README.md

@@ -0,0 +1,142 @@
+---
+title: "@smthrs/run-store"
+description: "Durable run state and fenced ownership for long-running jobs: which runs exist, what each one is doing, which process owns it, and how a restart takes one back safely."
+---
+
+`@smthrs/run-store` keeps the live state of long-running jobs in a SQL database.
+It answers two questions about every run: what is it doing right now, and which
+process is allowed to touch it.
+
+It is an [Effect](https://effect.website) library of two services, `RunStore`
+and `AttemptStore`, plus the ownership arbitration that decides who holds a run.
+
+## What it solves
+
+A process that owns a long job can die at any moment. Two things then go wrong.
+The work is stranded, because nothing else knows the job existed or how far it
+got. And picking the job back up is dangerous, because the process you assume is
+dead may still be alive and writing.
+
+This package handles both in the database rather than in your code:
+
+- **One row is the authority.** `RunStore` keeps a row per run holding its
+  status, its owner, its heartbeat, whether cancellation was requested, and the
+  executable state a resume re-enters. A restarted process reads that row
+  instead of replaying a log to work out where it was.
+- **Every owned write carries a fence.** An owner identity is
+  `{ hostId, pid, nonce }`, and all three fields are compared inside the same
+  SQL statement as the mutation they guard. There is no window between checking
+  ownership and using it, so two processes cannot both win.
+- **Competition is a value, not an error.** Losing a race returns
+  `AlreadyClaimed`, `HeartbeatFresh`, or `FenceLost` as an ordinary success
+  value you branch on. The error channel is reserved for real defects such as an
+  invalid argument or a corrupt row.
+- **Step attempts inherit the run's fence.** `AttemptStore` records when each
+  execution of a step started, the checkpoints it wrote, and how it ended, and
+  refuses every write from a process that no longer owns the run.
+
+The stores carry no database of their own. They are written against the
+driver-neutral [`@smthrs/database`](/api/database) contract, so the same code
+runs over a local SQLite file, over a server, or over an in-memory database in a
+test.
+
+## 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. [Installation](./installation.md) covers the import
+forms and the two services a composition has to supply.
+
+## Take a run, do the work, settle it
+
+This program creates a run, claims ownership of it, and finishes it. The stores
+are the production ones. `TestRunStore.layer` provides them over a migrated
+in-memory database, so the file runs with no configuration:
+
+```ts
+import { RunStore } from "@smthrs/run-store"
+import type { OwnerId } from "@smthrs/run-store/Ownership"
+import * as TestRunStore from "@smthrs/run-store/test/TestRunStore"
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+
+const owner: OwnerId = { hostId: "worker-1", pid: 4102, nonce: "9c31-af02" }
+
+const program = Effect.gen(function*() {
+  const runs = yield* RunStore.RunStore
+
+  yield* runs.create("build-42", JSON.stringify({ step: "checkout" }))
+
+  const nowMs = yield* Clock.currentTimeMillis
+  const taken = yield* runs.claimAndOwn(
+    "build-42",
+    { status: "pending", owner: null, heartbeatAtMs: null },
+    owner,
+    nowMs
+  )
+  if (taken._tag !== "Activated") return `another process has it: ${taken._tag}`
+
+  // Do the work here, heartbeating while it runs.
+
+  const settled = yield* runs.transitionOwned(
+    "build-42",
+    owner,
+    "completed",
+    JSON.stringify({ step: "done" })
+  )
+  return `run ended as ${settled._tag}`
+})
+
+console.log(
+  await Effect.runPromise(
+    program.pipe(Effect.provide(TestRunStore.layer), Effect.scoped)
+  )
+)
+```
+
+```text
+run ended as Transitioned
+```
+
+The second argument to `claimAndOwn` is the row as you last read it, restated as
+the three fields a claim guards. The third argument is the new owner. The claim
+is admitted only while the row still matches. If a peer took the run between
+your read and your write, this caller loses the race and leaves the peer's
+ownership unchanged. The example then returns before calling `transitionOwned`.
+
+## How this relates to @smthrs/flows
+
+`@smthrs/run-store` is one of the storage services inside
+[`@smthrs/flows`](/api/flows), the package that carries the whole Smithers
+durable flow engine in a single dependency. When you write a flow with
+`@smthrs/flows` and run it on a Node host, this package is the code deciding
+which process owns your run and what a restart re-enters. Flow authors never
+call it.
+
+Reach for `@smthrs/run-store` directly when you are building the host rather
+than the flow: a scheduler, a worker pool, or any service that hands durable
+work between processes and needs ownership arbitration it can trust. Most hosts
+do not wire it by hand even then.
+[`@smthrs/engine-store`](/api/engine-store) already composes these stores with
+the journal, the step cache, and the engine's own state into one storage ladder,
+and `@smthrs/flows/NodeRuntime` builds that ladder over a single SQLite file.
+
+Above all of it sits [`smithers`](/api/cli), the command line that plans, runs,
+and inspects durable flows without your writing a host at all. Start there if
+you want to run flows rather than build the machinery underneath them.
+
+## Where to go next
+
+- [Quickstart](./quickstart.md) drives one run through its whole lifecycle,
+  including a step attempt, against an in-memory database.
+- [Fencing and ownership](./concepts/fencing.md) explains the compare-and-swap
+  every write goes through, and [the heartbeat lease](./concepts/leases.md)
+  explains how a run is judged stale.
+- [Claim a run and finish it](./guides/claim-and-finish-a-run.md) and
+  [take over a stalled run](./guides/recover-a-stalled-run.md) are the two
+  paths a host has to get right.
+- [Compose the stores into a host](./guides/compose-the-stores.md) gives the
+  layer order that satisfies both services.
+- [API reference](./api.md) documents every export.
+- [Troubleshooting](./troubleshooting.md) lists each refused outcome and typed
+  error, and what to change.