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

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

@@ -0,0 +1,276 @@
+/**
+ * Durable action dispatch at the engine encoded seam.
+ *
+ * Governing design: `packages/smithers/flows/plan/docs/concepts/step-keys.md`.
+ *
+ * @since 0.1.0
+ */
+import { Action } from "@smthrs/flow";
+import type { FileBoundary } from "@smthrs/flow/FileBoundary";
+import { Journal } from "@smthrs/journal";
+import { Jj } from "@smthrs/kernel";
+import { AttemptStore, Ownership, RunStore } from "@smthrs/run-store";
+import { CacheStore } from "@smthrs/step-cache";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as ReplayOnly from "../ReplayOnly.ts";
+import * as StepBoundary from "../StepBoundary.ts";
+import * as AttemptAdmission from "./AttemptAdmission.ts";
+import * as CacheAgeVerdicts from "./CacheAgeVerdicts.ts";
+/**
+ * The boundary declaration an action may carry alongside its input.
+ *
+ * Aliased to `FileBoundary` rather than re-declared so the dispatch path and
+ * the `@smthrs/flow` declaration cannot drift apart; it is a distinct name only
+ * because "metadata" is how the action input refers to it.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type BoundaryMetadata = FileBoundary;
+/**
+ * Everything one dispatch of a durable action needs: the opaque `action`
+ * body, which `attempt` this is, the step `key` it is cached under, its trust
+ * `tier`, and the boundary it declared, if any.
+ *
+ * The `key` is a digest of the caller's declaration, so two dispatches sharing
+ * one carry the same claim about their inputs — which is what makes the
+ * attempt row and the cache row addressable by it.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface ActionInput {
+    readonly action: unknown;
+    readonly attempt: number;
+    readonly key: string;
+    readonly tier: Action.Tier;
+    /**
+     * The caller declares this sealed step's recorded result is one of many
+     * legitimate results; a same-key divergence is expected, not a hermeticity
+     * violation.
+     */
+    readonly nondeterministic?: true | undefined;
+    readonly metadata?: BoundaryMetadata | undefined;
+    /**
+     * The engine's `SnapshotBoundary` preparation for a compensable attempt:
+     * restore the retry sequence's original handle, then take this attempt's.
+     * Evaluated only when the attempt actually executes, after the journal and
+     * cache lookups, and its handle is persisted in the attempt row before the
+     * body runs.
+     */
+    readonly snapshot?: Effect.Effect<unknown> | undefined;
+}
+declare const AttemptSuspended_base: Schema.Class<AttemptSuspended, Schema.TaggedStruct<"@smthrs/engine-store/AttemptSuspended", {
+    readonly code: Schema.Literal<"attempt_suspended">;
+    readonly runId: Schema.String;
+    readonly keyDigest: Schema.String;
+    readonly attempt: Schema.Int;
+}>, Cause.YieldableError>;
+/**
+ * The attempt stopped without settling — it is durably parked, not failed.
+ *
+ * The distinction matters to the driver: a suspended attempt keeps its row and
+ * its attempt number, so resuming continues the same attempt rather than
+ * burning a new one against the retry budget.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export declare class AttemptSuspended extends AttemptSuspended_base {
+}
+declare const AttemptAdmissionRejected_base: Schema.Class<AttemptAdmissionRejected, Schema.TaggedStruct<"@smthrs/engine-store/AttemptAdmissionRejected", {
+    readonly code: Schema.Literal<"attempt_admission_rejected">;
+    readonly keyDigest: Schema.String;
+    readonly outcome: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * The attempt was not admitted, so its body never ran.
+ *
+ * `outcome` names which admission check refused — a superseded fence, a live
+ * same-key attempt, an already-settled row. Because the body did not execute,
+ * this failure is always safe to surface without compensation.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export declare class AttemptAdmissionRejected extends AttemptAdmissionRejected_base {
+}
+declare const CacheConflictDetected_base: Schema.Class<CacheConflictDetected, Schema.TaggedStruct<"@smthrs/engine-store/CacheConflictDetected", {
+    readonly code: Schema.Literal<"cache_conflict_detected">;
+    readonly keyDigest: Schema.String;
+    readonly recordedRunId: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * Two different runs recorded results under the same step key.
+ *
+ * The key is a digest of the declaration, so a conflict means the declaration
+ * does not fully describe what the step depends on: same key, different
+ * answer. `recordedRunId` names the run that got there first, so the
+ * divergence can be investigated rather than silently resolved.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export declare class CacheConflictDetected extends CacheConflictDetected_base {
+}
+declare const CacheCorruptionDetected_base: Schema.Class<CacheCorruptionDetected, Schema.TaggedStruct<"@smthrs/engine-store/CacheCorruptionDetected", {
+    readonly code: Schema.Literal<"cache_corruption_detected">;
+    readonly keyDigest: Schema.String;
+    readonly path: Schema.String;
+    readonly recordedDigest: Schema.String;
+    readonly measuredDigest: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * A cached output's bytes no longer hash to the digest recorded for them.
+ *
+ * Unlike a succeeded attempt row, a shared cache row is evictable: the entry is
+ * dropped and the next dispatch re-executes and re-captures cleanly (issue
+ * #164). Reported rather than swallowed so a failing disk is visible.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export declare class CacheCorruptionDetected extends CacheCorruptionDetected_base {
+}
+declare const AttemptEvidenceQuarantined_base: Schema.Class<AttemptEvidenceQuarantined, Schema.TaggedStruct<"@smthrs/engine-store/AttemptEvidenceQuarantined", {
+    readonly code: Schema.Literal<"attempt_evidence_quarantined">;
+    readonly keyDigest: Schema.String;
+    readonly attempt: Schema.Int;
+    readonly path: Schema.String;
+    readonly recordedDigest: Schema.String;
+    readonly measuredDigest: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * Corrupt recorded evidence on a SUCCEEDED durable attempt row under the
+ * strict verdict (issue #171).
+ *
+ * Distinct from {@link CacheCorruptionDetected} on purpose: a corrupt shared
+ * cache row is evictable — the next dispatch re-executes and re-captures
+ * cleanly (issue #164) — but a succeeded attempt row records that this run's
+ * side effects already ran, so eviction/re-execution would violate
+ * exactly-once for irreversible actions. The corrupt boundary evidence is
+ * quarantined off the succeeded row instead: the driver parks the first
+ * detection in the `quarantine` waiting state, and the next explicit resume
+ * returns the durable outcome without re-materializing the poisoned evidence
+ * or re-executing the action.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export declare class AttemptEvidenceQuarantined extends AttemptEvidenceQuarantined_base {
+}
+/**
+ * Extracts an {@link AttemptEvidenceQuarantined} carried anywhere in a flow
+ * result's cause — as a typed failure or squashed into a defect — so the
+ * driver can park the run instead of settling it `failed` (issue #171).
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export declare const evidenceQuarantined: (cause: Cause.Cause<unknown>) => AttemptEvidenceQuarantined | undefined;
+/**
+ * What the action dispatcher is constructed with: the run it belongs to, the
+ * ownership fence it writes under, and the `execute` function that actually
+ * runs an action body.
+ *
+ * Everything durable — the attempt row, the cache row, the journal record — is
+ * this module's job; `execute` is the only part it delegates, which is what
+ * keeps the persistence discipline in one place regardless of what a flow
+ * runtime does with the body.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Dependencies {
+    readonly runId: string;
+    readonly owner: Ownership.OwnerId;
+    readonly sourceId: string;
+    /** Runs one action body. The only part of a dispatch this module delegates. */
+    readonly execute: (input: ActionInput) => Effect.Effect<unknown, unknown>;
+    /** Repository authority reserved for engine bookkeeping. */
+    readonly engineJj?: Jj.Jj | undefined;
+    /**
+     * Makes a retry of an irreversible action recognizable downstream. Its
+     * absence is what
+     * {@link Action.IrreversibleRetryRequiresIdempotencyKey} reports.
+     */
+    readonly idempotencyKey?: string | undefined;
+    /**
+     * The incarnation-wide admission mutex (issues #102, #103). `EngineStore`
+     * passes one shared instance per store incarnation so every dispatch of a
+     * given attempt key in this process serializes through it; when omitted, a
+     * fresh mutex private to this `make` call is used — correct only when all
+     * same-key dispatches share the returned executor.
+     */
+    readonly admission?: AttemptAdmission.Service | undefined;
+    /** Shared by callers that construct an executor for every dispatch in a run. */
+    readonly cacheAgeVerdict?: ReturnType<typeof CacheAgeVerdicts.make> | undefined;
+    /**
+     * Present on a replay-only engine: every settled dispatch is reported to it,
+     * and a dispatch that would execute a body dies with `WouldExecute` first.
+     */
+    readonly replayOnly?: ReplayOnly.Service | undefined;
+}
+/**
+ * The earliest boundary snapshot handle persisted for an action key's
+ * surviving attempts, walking `earliest` through `latest`. An attempt row
+ * without one (it crashed before its snapshot was persisted) is skipped.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export declare const earliestBoundarySnapshot: (attempts: AttemptStore.Service, runId: string, stepKeyDigest: string, range: {
+    readonly earliest: number;
+    readonly latest: number;
+}) => Effect.Effect<Option.Option<unknown>>;
+/**
+ * Maximum nesting copied from one live failure value.
+ *
+ * The bounds here are the store's own admission limits, less the envelope
+ * `persistCause` wraps around a reduced value, and never tighter: a value the
+ * store would have persisted must not be thrown away here. `AttemptStore`
+ * admits 128 levels, and a reduced value sits three levels down, inside
+ * `{ reasons: [{ error }] }`.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export declare const maxInertJsonDepth: number;
+/**
+ * Maximum JSON values copied from one persisted cause.
+ *
+ * The budget is spent across the cause object, its reasons array, every reason
+ * envelope, and every reduced leaf. A cause that cannot fit collapses to one
+ * bounded reason before it reaches `AttemptStore`. Own-key enumeration has a
+ * separate allowance of the same size so ignored keys cannot make traversal
+ * unbounded.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export declare const maxInertJsonNodes: number;
+/**
+ * Maximum UTF-16 units copied from one persisted cause, keys included.
+ *
+ * Spent across every caller-supplied key and string leaf. This bounds text the
+ * reduction inspects and retains, not the serialized byte length: numeric
+ * spellings, punctuation, and the fixed cause envelope are outside this
+ * character count and are bounded separately by {@link maxInertJsonNodes}.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export declare const maxInertJsonCharacters: number;
+/**
+ * Constructs the encoded action executor. The action itself stays opaque;
+ * the supplied dispatcher is the only physical execution point.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const make: (deps: Dependencies) => (input: ActionInput) => Effect.Effect<unknown, unknown, import("effect/Crypto").Crypto | StepBoundary.Service | CacheStore.CacheStore | Journal.Journal | RunStore.RunStore | Jj.Jj | AttemptStore.AttemptStore>;
+export {};
+//# sourceMappingURL=ActionPersistence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ActionPersistence.d.ts","sourceRoot":"","sources":["../../../src/internal/ActionPersistence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,MAAM,EAAe,MAAM,cAAc,CAAA;AAElD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAAE,OAAO,EAAgC,MAAM,iBAAiB,CAAA;AACvE,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAA;AAEnC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAGrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAA;AAGlD,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;AAGzD,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;AAYzD;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAA;AAE3C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAA;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,IAAI,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAA;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,SAAS,CAAA;CACvD;;;;;;;AAED;;;;;;;;;GASG;AACH,qBAAa,gBAAiB,SAAQ,qBAQrC;CAAG;;;;;;AAEJ;;;;;;;;;GASG;AACH,qBAAa,wBAAyB,SAAQ,6BAO7C;CAAG;;;;;;AAEJ;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,0BAO1C;CAAG;;;;;;;;AAEJ;;;;;;;;;GASG;AACH,qBAAa,uBAAwB,SAAQ,4BAS5C;CAAG;;;;;;;;;AAEJ;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,0BAA2B,SAAQ,+BAU/C;CAAG;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAC9B,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,KAC1B,0BAA0B,GAAG,SAY/B,CAAA;AAgED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,OAAO,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IACzE,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC,OAAO,GAAG,SAAS,CAAA;IACzD,gFAAgF;IAChF,QAAQ,CAAC,eAAe,CAAC,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,IAAI,CAAC,GAAG,SAAS,CAAA;IAC/E;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,GAAG,SAAS,CAAA;CACrD;AAqFD;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,YAAY,CAAC,OAAO,EAC9B,OAAO,MAAM,EACb,eAAe,MAAM,EACrB,OAAO;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAC5D,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAQnC,CAAA;AAaJ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,QAAoC,CAAA;AAElE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,QAAoC,CAAA;AAElE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,QAAa,CAAA;AAwRhD;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,YAAY,qNAu3DtC,CAAA"}