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

package/dist/esm/internal/RunDriver.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Claim-gated durable flow run lifecycle.
+ *
+ * @since 0.1.0
+ */
+import { DurableWriter } from "@smthrs/database/DurableWriter";
+import { FlowEngine } from "@smthrs/engine";
+import { Flow, FlowRuntime } from "@smthrs/flow";
+import { Journal } from "@smthrs/journal";
+import { Ownership, RunStore } from "@smthrs/run-store";
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Scope from "effect/Scope";
+import * as DurableEngineState from "../DurableEngineState.ts";
+import * as WakeBus from "../WakeBus.ts";
+/**
+ * Raised when a flow (directly or through mutual ancestry) attempts to
+ * execute an execution id that already appears in its own persisted
+ * `parentExecutionId` chain.
+ *
+ * Detection walks the already-persisted parent chain from the requesting
+ * parent upward — an O(depth) check, not a dependency-graph DFS — because
+ * `parentExecutionId` is the only edge our runtime model can express.
+ *
+ * The class is declared by `@smthrs/flow` (it is part of the `execute`
+ * contract) and re-exported here for the detector's callers.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export declare const FlowCycleDetected: typeof FlowRuntime.FlowCycleDetected;
+/**
+ * The value form of {@link FlowCycleDetected}.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export type FlowCycleDetected = FlowRuntime.FlowCycleDetected;
+/**
+ * Why the engine itself asked a parked execution to resume.
+ *
+ * The operator's own resume is absent on purpose: it is the one wake a host
+ * has already claimed before the engine hears about it.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type RequestedResumeReason = "deferred" | "clock" | "parent";
+/**
+ * Why a wake is scheduled for an execution.
+ *
+ * Only `operator` is recovery consent for a quarantine park. `delegated` is a
+ * host taking up a control delegation it has already claimed, so, like
+ * `operator`, it is not recorded back to the host as a request.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type ScheduledResumeReason = RequestedResumeReason | "operator" | "delegated";
+/**
+ * Dependencies for the run driver.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Dependencies {
+    readonly owner: Ownership.OwnerId;
+    readonly journalSource: string;
+    /**
+     * Liveness arbitration before a steal, consulted only for a run whose lease
+     * has already expired. Optional: the default is
+     * `Ownership.leaseLiveness(Ownership.heartbeatStaleAfter)`, which has no
+     * evidence beyond the lease and therefore reports the owner gone, so a
+     * composition that supplies nothing still reclaims hard-killed runs.
+     */
+    readonly isAlive?: Ownership.LivenessCheck | undefined;
+    readonly canExecute?: ((row: RunStore.RunRow) => Effect.Effect<boolean>) | undefined;
+    readonly canActivate?: ((row: RunStore.RunRow) => Effect.Effect<boolean>) | undefined;
+    /**
+     * Records, for a host that keeps one, that this driver has asked a
+     * SUSPENDED execution to resume.
+     *
+     * Every wake the engine itself initiates passes through here: a durable
+     * clock firing, a durable deferred completing (a signal, a queue offer, a
+     * registration-time sweep of completions taken while the host was down),
+     * and a child settling under a parent that parked on it. A host that guards
+     * re-entry into a parked run — `AgentSession` refuses a round for a parked
+     * control row that nobody asked for — otherwise cannot tell those from its
+     * own heartbeat sweep, and a run that slept never settled.
+     *
+     * An operator resume is NOT recorded: `Control.resume` and
+     * `ControlLive.decide` claim the control row themselves, and recording a
+     * second request for the resume a host is already taking up would buy that
+     * park a second re-drive.
+     *
+     * Optional. A composition with no such host leaves it undefined and the
+     * wake is exactly what it was.
+     */
+    readonly requestResume?: ((executionId: string, reason: RequestedResumeReason) => Effect.Effect<void>) | undefined;
+    readonly engine: Effect.Effect<FlowRuntime.FlowRuntime["Service"]>;
+    /**
+     * In-process wake bus announced to whenever a durable write makes a run
+     * runnable — a scheduled resume (deferred, clock, operator) and a run
+     * settling terminally. Optional so a direct construction without one keeps
+     * the pre-existing polling-only behavior: the default drops every wake,
+     * which the engine's suspension polling schedule already covers.
+     */
+    readonly wakeBus?: WakeBus.Service | undefined;
+    /**
+     * Runs inside the uninterruptible finalizer that retains a suspended run's
+     * flow scope, immediately after the entry is inserted and before the round's
+     * settlement can start.
+     *
+     * Private to `packages/smithers/flows/engine-store/test`. That boundary is where a pending
+     * interruption first becomes observable again, and no public seam reaches
+     * it, so the regression proving the retention is released there — rather
+     * than stranded until the driver's own scope closes — raises the
+     * interruption from here. This module is not exported from the package
+     * (`"./internal/*": null`), and production compositions leave the hook
+     * undefined, which costs one `undefined` check per suspension.
+     */
+    readonly unsafeOnScopeRetained?: ((runId: string) => Effect.Effect<void>) | undefined;
+}
+/**
+ * Claim-gated operations composed into the encoded flow engine.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Service {
+    readonly register: FlowEngine.Encoded["register"];
+    /**
+     * The encoded `execute`, widened for direct driver callers: an absent
+     * `round` admits the execution as round zero of its own lineage. Nested
+     * direct callers observe its latest round; encoded callers read one round.
+     * To decode a terminal result, direct nested callers must register the
+     * terminal flow's codec in this driver, even if another worker ran it.
+     * A missing codec is a wiring defect, as with the typed Trampoline; it
+     * fails fast rather than suspending terminal work with no future wake.
+     */
+    readonly execute: <const Discard extends boolean>(flow: Flow.Any, options: {
+        readonly executionId: string;
+        readonly payload: object;
+        readonly discard: Discard;
+        readonly parent?: FlowRuntime.FlowInstance["Service"] | undefined;
+        readonly round?: Parameters<FlowEngine.Encoded["execute"]>[1]["round"] | undefined;
+        readonly follow?: boolean | undefined;
+    }) => Effect.Effect<Discard extends true ? void : Flow.Result<unknown, unknown>, FlowCycleDetected>;
+    readonly poll: FlowEngine.Encoded["poll"];
+    readonly interrupt: FlowEngine.Encoded["interrupt"];
+    readonly interruptUnsafe: FlowEngine.Encoded["interruptUnsafe"];
+    readonly resume: FlowEngine.Encoded["resume"];
+    readonly scheduleResume: (flowName: string, executionId: string, reason: ScheduledResumeReason, sourceId?: string | undefined) => Effect.Effect<void>;
+    readonly active: Effect.Effect<ReadonlySet<string>>;
+    /**
+     * The runs whose parked flow scope this driver still holds. Cancellation
+     * and re-drive both release; the set is the leak assertion's observation
+     * point.
+     */
+    readonly retainedRuns: Effect.Effect<ReadonlySet<string>>;
+}
+/**
+ * The effect kind a detached child spawn is journaled under, and therefore the
+ * kind an engine composition registers a spawn-compensation handler for.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const spawnEffectKind: "flows/engine-store/child-spawn";
+/**
+ * Compares encoded JSON payloads structurally. Object key order is not part
+ * of JSON identity, while array order and array length are.
+ *
+ * Values outside JSON compare unequal unless both arguments are the same
+ * reference.
+ *
+ * @since 1.0.0
+ * @category guards
+ * @private
+ */
+export declare const samePayload: (left: unknown, right: unknown) => boolean;
+/**
+ * Constructs a scoped run driver.
+ *
+ * Every start and wake enters the same keyed coordinator and then the same
+ * exact-snapshot claim/activation path.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const make: (dependencies: Dependencies) => Effect.Effect<Service, never, Crypto.Crypto | DurableEngineState.DurableEngineState | DurableWriter | Journal.Journal | RunStore.RunStore | Scope.Scope>;
+//# sourceMappingURL=RunDriver.d.ts.map

package/dist/esm/internal/RunDriver.d.ts.map

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