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

package/dist/esm/RunCatalogRead.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The workspace run catalog read.
+ *
+ * `@smthrs/sync` serves a workspace subscription over a `RunCatalog`, and its
+ * own implementations are static or in-process. This is the durable source a
+ * `RunCatalog.makePolling` catalog reads, so a follower learns of a run
+ * another engine created.
+ *
+ * The operation lives in `internal/RunCatalogOps.ts`, beside the other
+ * modules that read this package's own tables; this module is the public
+ * surface, so `internal/` is never imported by a consumer.
+ *
+ * @since 0.1.0
+ */
+export { defaultLimit, layer, type ListOptions, make, RunCatalogError, RunCatalogErrorCode, RunCatalogRead, type Service } from "./internal/RunCatalogOps.ts";
+export { Filters, type ListRunsOptions, maximumPageSize, type RunPage } from "./internal/RunListing.ts";
+//# sourceMappingURL=RunCatalogRead.d.ts.map

package/dist/esm/RunCatalogRead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunCatalogRead.d.ts","sourceRoot":"","sources":["../../src/RunCatalogRead.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,EACL,KAAK,WAAW,EAChB,IAAI,EACJ,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,KAAK,OAAO,EACb,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EAAE,OAAO,EAAE,KAAK,eAAe,EAAE,eAAe,EAAE,KAAK,OAAO,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/esm/RunCatalogRead.js

@@ -0,0 +1,17 @@
+/**
+ * The workspace run catalog read.
+ *
+ * `@smthrs/sync` serves a workspace subscription over a `RunCatalog`, and its
+ * own implementations are static or in-process. This is the durable source a
+ * `RunCatalog.makePolling` catalog reads, so a follower learns of a run
+ * another engine created.
+ *
+ * The operation lives in `internal/RunCatalogOps.ts`, beside the other
+ * modules that read this package's own tables; this module is the public
+ * surface, so `internal/` is never imported by a consumer.
+ *
+ * @since 0.1.0
+ */
+export { defaultLimit, layer, make, RunCatalogError, RunCatalogErrorCode, RunCatalogRead } from "./internal/RunCatalogOps.js";
+export { Filters, maximumPageSize } from "./internal/RunListing.js";
+//# sourceMappingURL=RunCatalogRead.js.map

package/dist/esm/RunCatalogRead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunCatalogRead.js","sourceRoot":"","sources":["../../src/RunCatalogRead.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,EAEL,IAAI,EACJ,eAAe,EACf,mBAAmB,EACnB,cAAc,EAEf,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EAAE,OAAO,EAAwB,eAAe,EAAgB,MAAM,0BAA0B,CAAA","sourcesContent":["/**\n * The workspace run catalog read.\n *\n * `@smthrs/sync` serves a workspace subscription over a `RunCatalog`, and its\n * own implementations are static or in-process. This is the durable source a\n * `RunCatalog.makePolling` catalog reads, so a follower learns of a run\n * another engine created.\n *\n * The operation lives in `internal/RunCatalogOps.ts`, beside the other\n * modules that read this package's own tables; this module is the public\n * surface, so `internal/` is never imported by a consumer.\n *\n * @since 0.1.0\n */\n\nexport {\n  defaultLimit,\n  layer,\n  type ListOptions,\n  make,\n  RunCatalogError,\n  RunCatalogErrorCode,\n  RunCatalogRead,\n  type Service\n} from \"./internal/RunCatalogOps.ts\"\n\nexport { Filters, type ListRunsOptions, maximumPageSize, type RunPage } from \"./internal/RunListing.ts\"\n"]}

package/dist/esm/RunChangeFeed.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Coalesced execution catch-up with permanent deletion evidence.
+ *
+ * @since 1.0.0
+ */
+import { RunStoreError } from "@smthrs/run-store/RunStore";
+import { Context, Effect, Layer } from "effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import type { Position } from "./ExecutionSnapshot.ts";
+/**
+ * A live-row change or retained tombstone.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Change extends Position {
+    readonly runId: string;
+    readonly deleted: boolean;
+}
+/**
+ * One catch-up page at an engine watermark.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Page extends Position {
+    readonly changes: ReadonlyArray<Change>;
+    /** Resume here, including across gaps from coalesced changes. */
+    readonly nextRevision: number;
+    readonly hasMore: boolean;
+}
+/**
+ * Bounded state-feed operations.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Service {
+    readonly current: Effect.Effect<Position, RunStoreError>;
+    readonly changesSince: (options: Position & {
+        readonly limit: number;
+    }) => Effect.Effect<Page, RunStoreError>;
+}
+declare const RunChangeFeed_base: Context.ServiceClass<RunChangeFeed, "@smthrs/engine-store/RunChangeFeed", Service>;
+/**
+ * Durable change-feed service.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export declare class RunChangeFeed extends RunChangeFeed_base {
+}
+/**
+ * Maximum change-feed page size.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const maximumPageSize = 1000;
+/**
+ * Constructs the feed without polling or retention timers.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: () => Effect.Effect<Service, never, SqlClient.SqlClient>;
+/**
+ * Provides the SQL feed.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layer: Layer.Layer<RunChangeFeed, never, SqlClient.SqlClient>;
+export {};
+//# sourceMappingURL=RunChangeFeed.d.ts.map

package/dist/esm/RunChangeFeed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunChangeFeed.d.ts","sourceRoot":"","sources":["../../src/RunChangeFeed.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAU,MAAM,QAAQ,CAAA;AACvD,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAGtD;;;;;GAKG;AACH,MAAM,WAAW,MAAO,SAAQ,QAAQ;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AACD;;;;;GAKG;AACH,MAAM,WAAW,IAAK,SAAQ,QAAQ;IACpC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACvC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AACD;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAA;IACxD,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,QAAQ,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAAA;CAC9G;;AACD;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,kBAA+E;CAAG;AACrH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,OAAO,CAAA;AAQnC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,QAAO,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,CA8CrE,CAAA;AACJ;;;;;GAKG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,CAAuC,CAAA"}

package/dist/esm/RunChangeFeed.js

@@ -0,0 +1,81 @@
+/**
+ * Coalesced execution catch-up with permanent deletion evidence.
+ *
+ * @since 1.0.0
+ */
+import { 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.js";
+/**
+ * Durable change-feed service.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export class RunChangeFeed extends Context.Service()("@smthrs/engine-store/RunChangeFeed") {
+}
+/**
+ * Maximum change-feed page size.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const maximumPageSize = 1000;
+const Options = Schema.Struct({
+    source: Read.Source,
+    revision: Read.Natural,
+    limit: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: maximumPageSize }))
+});
+const ChangeRow = Schema.Struct({ run_id: Read.Identifier, revision: Read.Natural, deleted: Schema.Literals([0, 1]) });
+/**
+ * Constructs the feed without polling or retention timers.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = () => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    return {
+        current: Read.boundary("RunChangeFeed.current", Read.position(sql)),
+        changesSince: (options) => Read.boundary("RunChangeFeed.changesSince", Effect.gen(function* () {
+            const input = yield* Read.decode(Options, options);
+            return yield* Read.transaction(sql, Effect.gen(function* () {
+                const at = yield* Read.position(sql);
+                if (input.source !== at.source || input.revision > at.revision) {
+                    return yield* Effect.fail(new RunStoreError({
+                        method: "RunChangeFeed.changesSince",
+                        code: "invalid_run",
+                        message: "change cursor requires an explicit source rebuild",
+                        cause: { requested: input, observed: at }
+                    }));
+                }
+                const rows = yield* sql `SELECT run_id, revision, deleted FROM flows_run_changes
+          WHERE revision > ${input.revision} AND revision <= ${at.revision}
+          ORDER BY revision LIMIT ${input.limit + 1}`;
+                const decoded = yield* Effect.forEach(rows, (row) => Read.decode(ChangeRow, row));
+                const changes = decoded.slice(0, input.limit).map((row) => ({
+                    runId: row.run_id,
+                    source: at.source,
+                    revision: row.revision,
+                    deleted: row.deleted === 1
+                }));
+                const hasMore = decoded.length > input.limit;
+                return {
+                    ...at,
+                    changes,
+                    hasMore,
+                    nextRevision: hasMore ? changes[changes.length - 1].revision : at.revision
+                };
+            }));
+        }))
+    };
+});
+/**
+ * Provides the SQL feed.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer = Layer.effect(RunChangeFeed)(make());
+//# sourceMappingURL=RunChangeFeed.js.map

package/dist/esm/RunChangeFeed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunChangeFeed.js","sourceRoot":"","sources":["../../src/RunChangeFeed.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Coalesced execution catch-up with permanent deletion evidence.\n *\n * @since 1.0.0\n */\n\nimport { RunStoreError } from \"@smthrs/run-store/RunStore\"\nimport { Context, Effect, Layer, Schema } from \"effect\"\nimport * as SqlClient from \"effect/unstable/sql/SqlClient\"\nimport type { Position } from \"./ExecutionSnapshot.ts\"\nimport * as Read from \"./internal/ExecutionSnapshotRead.ts\"\n\n/**\n * A live-row change or retained tombstone.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Change extends Position {\n  readonly runId: string\n  readonly deleted: boolean\n}\n/**\n * One catch-up page at an engine watermark.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Page extends Position {\n  readonly changes: ReadonlyArray<Change>\n  /** Resume here, including across gaps from coalesced changes. */\n  readonly nextRevision: number\n  readonly hasMore: boolean\n}\n/**\n * Bounded state-feed operations.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Service {\n  readonly current: Effect.Effect<Position, RunStoreError>\n  readonly changesSince: (options: Position & { readonly limit: number }) => Effect.Effect<Page, RunStoreError>\n}\n/**\n * Durable change-feed service.\n *\n * @category services\n * @since 1.0.0\n */\nexport class RunChangeFeed extends Context.Service<RunChangeFeed, Service>()(\"@smthrs/engine-store/RunChangeFeed\") {}\n/**\n * Maximum change-feed page size.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const maximumPageSize = 1000\nconst Options = Schema.Struct({\n  source: Read.Source,\n  revision: Read.Natural,\n  limit: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: maximumPageSize }))\n})\nconst ChangeRow = Schema.Struct({ run_id: Read.Identifier, revision: Read.Natural, deleted: Schema.Literals([0, 1]) })\n\n/**\n * Constructs the feed without polling or retention timers.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const make = (): Effect.Effect<Service, never, SqlClient.SqlClient> =>\n  Effect.gen(function*() {\n    const sql = yield* SqlClient.SqlClient\n    return {\n      current: Read.boundary(\"RunChangeFeed.current\", Read.position(sql)),\n      changesSince: (options) =>\n        Read.boundary(\n          \"RunChangeFeed.changesSince\",\n          Effect.gen(function*() {\n            const input = yield* Read.decode(Options, options)\n            return yield* Read.transaction(\n              sql,\n              Effect.gen(function*() {\n                const at = yield* Read.position(sql)\n                if (input.source !== at.source || input.revision > at.revision) {\n                  return yield* Effect.fail(\n                    new RunStoreError({\n                      method: \"RunChangeFeed.changesSince\",\n                      code: \"invalid_run\",\n                      message: \"change cursor requires an explicit source rebuild\",\n                      cause: { requested: input, observed: at }\n                    })\n                  )\n                }\n                const rows = yield* sql`SELECT run_id, revision, deleted FROM flows_run_changes\n          WHERE revision > ${input.revision} AND revision <= ${at.revision}\n          ORDER BY revision LIMIT ${input.limit + 1}`\n                const decoded = yield* Effect.forEach(rows, (row) => Read.decode(ChangeRow, row))\n                const changes = decoded.slice(0, input.limit).map((row) => ({\n                  runId: row.run_id,\n                  source: at.source,\n                  revision: row.revision,\n                  deleted: row.deleted === 1\n                }))\n                const hasMore = decoded.length > input.limit\n                return {\n                  ...at,\n                  changes,\n                  hasMore,\n                  nextRevision: hasMore ? changes[changes.length - 1]!.revision : at.revision\n                }\n              })\n            )\n          })\n        )\n    }\n  })\n/**\n * Provides the SQL feed.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layer: Layer.Layer<RunChangeFeed, never, SqlClient.SqlClient> = Layer.effect(RunChangeFeed)(make())\n"]}

package/dist/esm/RunState.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The envelope a durable run's state is persisted inside.
+ *
+ * The engine never stores a flow's payload bare — it wraps it in a versioned
+ * struct, so a store row written by an older build decodes under a known
+ * shape instead of being guessed at. `version` is a literal rather than a
+ * number for exactly that reason: a future revision adds a new literal and
+ * both remain decodable.
+ *
+ * Time travel reads these rows too, deriving the state AT a frame by
+ * replaying run-decision records rather than trusting the row's latest value.
+ *
+ * @since 0.1.0
+ */
+import { CapabilityPattern } from "@smthrs/capability/Capability";
+import * as Schema from "effect/Schema";
+/**
+ * What a linked child does when the run that spawned it ends.
+ *
+ * `cancel` is the default and the shape a `.child()` boundary takes: the
+ * parent is waiting on this child, so a parent that stops waiting — because it
+ * completed, failed, or was cancelled — leaves nothing behind. `detach` is the
+ * shape a fire-and-forget spawn takes: the parent deliberately did not wait,
+ * so the child outlives it and keeps its own claim and its own journal.
+ *
+ * The policy is recorded on the CHILD rather than on the edge because it is a
+ * property of how the child was started, and because a child with two parents
+ * (the diamond `flows_run_parents` permits) must answer the question once.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export declare const OnParentExit: Schema.Literals<readonly ["cancel", "detach"]>;
+/**
+ * The value form of {@link OnParentExit}.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type OnParentExit = typeof OnParentExit.Type;
+/**
+ * The versioned state stored for a durable flow run: which flow it is, the
+ * encoded `payload` it was started with, and — as they arrive — its
+ * `result` and its cancellation timestamp.
+ *
+ * `parentExecutionId` is present only on a child run, and is what makes a
+ * spawned subflow reachable from the run that spawned it. `onParentExit`
+ * travels with it: it is what the parent's terminal transition reads to decide
+ * whether this child ends with it.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export declare const RunState: Schema.Struct<{
+    readonly version: Schema.Literal<1>;
+    readonly flowName: Schema.NonEmptyString;
+    readonly payload: Schema.Unknown;
+    readonly capabilityCeilings: Schema.optionalKey<Schema.$Array<Schema.$Array<typeof CapabilityPattern>>>;
+    readonly forkKeyRunIds: Schema.optionalKey<Schema.$Array<Schema.NonEmptyString>>;
+    readonly parentExecutionId: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly onParentExit: Schema.optionalKey<Schema.Literals<readonly ["cancel", "detach"]>>;
+    readonly maxRounds: Schema.optionalKey<Schema.Int>;
+    readonly deadline: Schema.optionalKey<Schema.Struct<{
+        readonly startedAtMs: Schema.Number;
+        readonly deadlineMs: Schema.Number;
+    }>>;
+    readonly result: Schema.optionalKey<Schema.Unknown>;
+    readonly cancellation: Schema.optionalKey<Schema.Struct<{
+        readonly interruptedAtMs: Schema.Number;
+    }>>;
+}>;
+/**
+ * The value form of {@link RunState}.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type RunState = typeof RunState.Type;
+/**
+ * Why a driver released a run it still owned, recorded on its
+ * `interrupt-released` run decision.
+ *
+ * `lease-lapsed` means the host went `unconfirmedMs` without confirming its
+ * run lease (a stalled or overloaded host), so the heartbeat loop stopped the
+ * run's work before a peer could take it. `interrupted` is any other
+ * interruption that was not a cancellation, usually a host shutdown.
+ *
+ * Decisions written before this field existed carry no cause; read them with
+ * {@link releaseCauseOf}, which answers `undefined` for them.
+ *
+ * @since 1.0.0
+ * @category schemas
+ */
+export declare const ReleaseCause: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"lease-lapsed">;
+    readonly unconfirmedMs: Schema.Int;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"interrupted">;
+}>]>;
+/**
+ * The value form of {@link ReleaseCause}.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type ReleaseCause = typeof ReleaseCause.Type;
+/**
+ * The release cause a run decision payload records, or `undefined` for a
+ * decision that is not `interrupt-released`, one written before causes were
+ * recorded, or one whose cause does not decode.
+ *
+ * @since 1.0.0
+ * @category decoding
+ */
+export declare const releaseCauseOf: (decision: unknown) => ReleaseCause | undefined;
+//# sourceMappingURL=RunState.d.ts.map

package/dist/esm/RunState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunState.d.ts","sourceRoot":"","sources":["../../src/RunState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AAEjE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAKvC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,gDAAwC,CAAA;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;EAkBnB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY;;;;;IAMvB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAInD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,OAAO,KAAG,YAAY,GAAG,SAMjE,CAAA"}

package/dist/esm/RunState.js

@@ -0,0 +1,109 @@
+/**
+ * The envelope a durable run's state is persisted inside.
+ *
+ * The engine never stores a flow's payload bare — it wraps it in a versioned
+ * struct, so a store row written by an older build decodes under a known
+ * shape instead of being guessed at. `version` is a literal rather than a
+ * number for exactly that reason: a future revision adds a new literal and
+ * both remain decodable.
+ *
+ * Time travel reads these rows too, deriving the state AT a frame by
+ * replaying run-decision records rather than trusting the row's latest value.
+ *
+ * @since 0.1.0
+ */
+import { CapabilityPattern } from "@smthrs/capability/Capability";
+import { Flow } from "@smthrs/flow";
+import * as Schema from "effect/Schema";
+/** @private */
+const PositiveSafeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+/**
+ * What a linked child does when the run that spawned it ends.
+ *
+ * `cancel` is the default and the shape a `.child()` boundary takes: the
+ * parent is waiting on this child, so a parent that stops waiting — because it
+ * completed, failed, or was cancelled — leaves nothing behind. `detach` is the
+ * shape a fire-and-forget spawn takes: the parent deliberately did not wait,
+ * so the child outlives it and keeps its own claim and its own journal.
+ *
+ * The policy is recorded on the CHILD rather than on the edge because it is a
+ * property of how the child was started, and because a child with two parents
+ * (the diamond `flows_run_parents` permits) must answer the question once.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const OnParentExit = Schema.Literals(["cancel", "detach"]);
+/**
+ * The versioned state stored for a durable flow run: which flow it is, the
+ * encoded `payload` it was started with, and — as they arrive — its
+ * `result` and its cancellation timestamp.
+ *
+ * `parentExecutionId` is present only on a child run, and is what makes a
+ * spawned subflow reachable from the run that spawned it. `onParentExit`
+ * travels with it: it is what the parent's terminal transition reads to decide
+ * whether this child ends with it.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const RunState = Schema.Struct({
+    version: Schema.Literal(1),
+    flowName: Schema.NonEmptyString,
+    payload: Schema.Unknown,
+    capabilityCeilings: Schema.optionalKey(Schema.Array(Schema.Array(CapabilityPattern))),
+    // Key origins are immutable fork metadata, independent of the chosen frame.
+    // Copied attempts, not ancestry alone, authorize reuse of an origin's key.
+    forkKeyRunIds: Schema.optionalKey(Schema.Array(Schema.NonEmptyString)),
+    parentExecutionId: Schema.optionalKey(Schema.NonEmptyString),
+    onParentExit: Schema.optionalKey(OnParentExit),
+    maxRounds: Schema.optionalKey(PositiveSafeInt),
+    // The lineage deadline a round after a handoff runs under, copied from the
+    // `Flow.Handoff` that opened it.
+    deadline: Schema.optionalKey(Flow.LineageDeadline),
+    result: Schema.optionalKey(Schema.Unknown),
+    cancellation: Schema.optionalKey(Schema.Struct({
+        interruptedAtMs: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0))
+    }))
+});
+/**
+ * Why a driver released a run it still owned, recorded on its
+ * `interrupt-released` run decision.
+ *
+ * `lease-lapsed` means the host went `unconfirmedMs` without confirming its
+ * run lease (a stalled or overloaded host), so the heartbeat loop stopped the
+ * run's work before a peer could take it. `interrupted` is any other
+ * interruption that was not a cancellation, usually a host shutdown.
+ *
+ * Decisions written before this field existed carry no cause; read them with
+ * {@link releaseCauseOf}, which answers `undefined` for them.
+ *
+ * @since 1.0.0
+ * @category schemas
+ */
+export const ReleaseCause = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("lease-lapsed"),
+        unconfirmedMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+    }),
+    Schema.Struct({ kind: Schema.Literal("interrupted") })
+]);
+const decodeReleaseCause = Schema.decodeUnknownOption(ReleaseCause);
+/**
+ * The release cause a run decision payload records, or `undefined` for a
+ * decision that is not `interrupt-released`, one written before causes were
+ * recorded, or one whose cause does not decode.
+ *
+ * @since 1.0.0
+ * @category decoding
+ */
+export const releaseCauseOf = (decision) => {
+    if (decision === null || typeof decision !== "object")
+        return undefined;
+    const record = decision;
+    if (record.decision !== "interrupt-released")
+        return undefined;
+    const decoded = decodeReleaseCause(record.cause);
+    return decoded._tag === "Some" ? decoded.value : undefined;
+};
+//# sourceMappingURL=RunState.js.map

package/dist/esm/RunState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunState.js","sourceRoot":"","sources":["../../src/RunState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AACnC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,eAAe;AACf,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAA;AAE1E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAA;AAUjE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC,cAAc;IAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;IACvB,kBAAkB,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACrF,4EAA4E;IAC5E,2EAA2E;IAC3E,aAAa,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACtE,iBAAiB,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,cAAc,CAAC;IAC5D,YAAY,EAAE,MAAM,CAAC,WAAW,CAAC,YAAY,CAAC;IAC9C,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC;IAC9C,2EAA2E;IAC3E,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC;IAClD,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC;IAC1C,YAAY,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;QAC7C,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;KACvE,CAAC,CAAC;CACJ,CAAC,CAAA;AAUF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC;IACvC,MAAM,CAAC,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC;QACpC,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;KAClE,CAAC;IACF,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;CACvD,CAAC,CAAA;AAUF,MAAM,kBAAkB,GAAG,MAAM,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAA;AAEnE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAAiB,EAA4B,EAAE;IAC5E,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACvE,MAAM,MAAM,GAAG,QAAqE,CAAA;IACpF,IAAI,MAAM,CAAC,QAAQ,KAAK,oBAAoB;QAAE,OAAO,SAAS,CAAA;IAC9D,MAAM,OAAO,GAAG,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAChD,OAAO,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC5D,CAAC,CAAA","sourcesContent":["/**\n * The envelope a durable run's state is persisted inside.\n *\n * The engine never stores a flow's payload bare — it wraps it in a versioned\n * struct, so a store row written by an older build decodes under a known\n * shape instead of being guessed at. `version` is a literal rather than a\n * number for exactly that reason: a future revision adds a new literal and\n * both remain decodable.\n *\n * Time travel reads these rows too, deriving the state AT a frame by\n * replaying run-decision records rather than trusting the row's latest value.\n *\n * @since 0.1.0\n */\n\nimport { CapabilityPattern } from \"@smthrs/capability/Capability\"\nimport { Flow } from \"@smthrs/flow\"\nimport * as Schema from \"effect/Schema\"\n\n/** @private */\nconst PositiveSafeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))\n\n/**\n * What a linked child does when the run that spawned it ends.\n *\n * `cancel` is the default and the shape a `.child()` boundary takes: the\n * parent is waiting on this child, so a parent that stops waiting — because it\n * completed, failed, or was cancelled — leaves nothing behind. `detach` is the\n * shape a fire-and-forget spawn takes: the parent deliberately did not wait,\n * so the child outlives it and keeps its own claim and its own journal.\n *\n * The policy is recorded on the CHILD rather than on the edge because it is a\n * property of how the child was started, and because a child with two parents\n * (the diamond `flows_run_parents` permits) must answer the question once.\n *\n * @since 0.1.0\n * @category schemas\n */\nexport const OnParentExit = Schema.Literals([\"cancel\", \"detach\"])\n\n/**\n * The value form of {@link OnParentExit}.\n *\n * @since 0.1.0\n * @category models\n */\nexport type OnParentExit = typeof OnParentExit.Type\n\n/**\n * The versioned state stored for a durable flow run: which flow it is, the\n * encoded `payload` it was started with, and — as they arrive — its\n * `result` and its cancellation timestamp.\n *\n * `parentExecutionId` is present only on a child run, and is what makes a\n * spawned subflow reachable from the run that spawned it. `onParentExit`\n * travels with it: it is what the parent's terminal transition reads to decide\n * whether this child ends with it.\n *\n * @since 0.1.0\n * @category schemas\n */\nexport const RunState = Schema.Struct({\n  version: Schema.Literal(1),\n  flowName: Schema.NonEmptyString,\n  payload: Schema.Unknown,\n  capabilityCeilings: Schema.optionalKey(Schema.Array(Schema.Array(CapabilityPattern))),\n  // Key origins are immutable fork metadata, independent of the chosen frame.\n  // Copied attempts, not ancestry alone, authorize reuse of an origin's key.\n  forkKeyRunIds: Schema.optionalKey(Schema.Array(Schema.NonEmptyString)),\n  parentExecutionId: Schema.optionalKey(Schema.NonEmptyString),\n  onParentExit: Schema.optionalKey(OnParentExit),\n  maxRounds: Schema.optionalKey(PositiveSafeInt),\n  // The lineage deadline a round after a handoff runs under, copied from the\n  // `Flow.Handoff` that opened it.\n  deadline: Schema.optionalKey(Flow.LineageDeadline),\n  result: Schema.optionalKey(Schema.Unknown),\n  cancellation: Schema.optionalKey(Schema.Struct({\n    interruptedAtMs: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0))\n  }))\n})\n\n/**\n * The value form of {@link RunState}.\n *\n * @since 0.1.0\n * @category models\n */\nexport type RunState = typeof RunState.Type\n\n/**\n * Why a driver released a run it still owned, recorded on its\n * `interrupt-released` run decision.\n *\n * `lease-lapsed` means the host went `unconfirmedMs` without confirming its\n * run lease (a stalled or overloaded host), so the heartbeat loop stopped the\n * run's work before a peer could take it. `interrupted` is any other\n * interruption that was not a cancellation, usually a host shutdown.\n *\n * Decisions written before this field existed carry no cause; read them with\n * {@link releaseCauseOf}, which answers `undefined` for them.\n *\n * @since 1.0.0\n * @category schemas\n */\nexport const ReleaseCause = Schema.Union([\n  Schema.Struct({\n    kind: Schema.Literal(\"lease-lapsed\"),\n    unconfirmedMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))\n  }),\n  Schema.Struct({ kind: Schema.Literal(\"interrupted\") })\n])\n\n/**\n * The value form of {@link ReleaseCause}.\n *\n * @since 1.0.0\n * @category models\n */\nexport type ReleaseCause = typeof ReleaseCause.Type\n\nconst decodeReleaseCause = Schema.decodeUnknownOption(ReleaseCause)\n\n/**\n * The release cause a run decision payload records, or `undefined` for a\n * decision that is not `interrupt-released`, one written before causes were\n * recorded, or one whose cause does not decode.\n *\n * @since 1.0.0\n * @category decoding\n */\nexport const releaseCauseOf = (decision: unknown): ReleaseCause | undefined => {\n  if (decision === null || typeof decision !== \"object\") return undefined\n  const record = decision as { readonly decision?: unknown; readonly cause?: unknown }\n  if (record.decision !== \"interrupt-released\") return undefined\n  const decoded = decodeReleaseCause(record.cause)\n  return decoded._tag === \"Some\" ? decoded.value : undefined\n}\n"]}