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

package/dist/esm/DeferredClockFold.d.ts

@@ -0,0 +1,354 @@
+/**
+ * The deferred/clock fold: `flows_clock_deadlines` and the mutable half of
+ * `flows_deferred_completions` rebuilt from the journal.
+ *
+ * Every change to either table is journalled on the run's own stream in the
+ * transaction that makes it:
+ *
+ * - `flows.engine.clock-scheduled` when a clock row is inserted;
+ * - `flows.engine.clock-completed` when a clock fires or its run settles
+ *   first (`completeClock`, `completeRunClocks`);
+ * - `flows.engine.deferred-completed` when the first completion wins, naming
+ *   the row and the {@link JournalEvent.contentDigest} of its encoded `exit`
+ *   and `metadata`;
+ * - `flows.engine.deferred-consumed` when a run first observes a result.
+ *
+ * The journal is redacted and replayed to sync subscribers, so it never
+ * carries a completion's value (issue #72). A clock row holds no value at
+ * all, so the fold rebuilds it whole. A completion row's value stays in the
+ * row: the fold rebuilds its `completed_at_ms` and `consumed_at_ms`, and a
+ * rebuild checks the stored text against the recorded digests. A completion
+ * the journal names but no row holds, or holds with other bytes, is a typed
+ * {@link FoldIncomplete}, never a silent gap.
+ *
+ * Compaction deletes a run's entries below its floor, so the fold's state at
+ * the floor has to survive in the floor's checkpoint: {@link checkpointState}
+ * adds it under {@link checkpointKey}, and a rebuild of a compacted run whose
+ * floor checkpoint lacks it fails {@link FoldIncomplete} with reason
+ * `checkpoint_missing`. A rewind archives the suffix and removes the rows it
+ * explains (`@smthrs/time-travel`), so the remaining journal still explains
+ * the remaining rows.
+ *
+ * @since 1.0.0
+ */
+import { DurableWriter } from "@smthrs/database/DurableWriter";
+import { Journal, JournalEvent, Projection } from "@smthrs/journal";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+/**
+ * The journal event types the fold reads.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const eventTypes: ReadonlyArray<string>;
+/**
+ * The key a checkpoint's state keeps the fold under.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const checkpointKey = "flows.engine.deferred-clock";
+/**
+ * A clock as the journal records it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Clock: Schema.Struct<{
+    readonly flowName: Schema.NonEmptyString;
+    readonly executionId: Schema.NonEmptyString;
+    readonly clockName: Schema.NonEmptyString;
+    readonly deferredName: Schema.NonEmptyString;
+    readonly dueAtMs: Schema.Int;
+    readonly completedAtMs: Schema.NullOr<Schema.Int>;
+}>;
+/**
+ * A clock as the journal records it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Clock = typeof Clock.Type;
+/**
+ * A deferred completion as the journal records it. A completion journalled
+ * before the fold existed carried its (redacted) value instead of digests and
+ * no completion time: `exitDigest` and `metadataDigest` are then absent and
+ * `completedAtMs` is `null`, and a rebuild keeps the row's own stamp.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Deferred: Schema.Struct<{
+    readonly flowName: Schema.NonEmptyString;
+    readonly executionId: Schema.NonEmptyString;
+    readonly deferredName: Schema.NonEmptyString;
+    readonly completedAtMs: Schema.NullOr<Schema.Int>;
+    readonly exitDigest: Schema.optionalKey<Schema.String>;
+    readonly metadataDigest: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly consumedAtMs: Schema.NullOr<Schema.Int>;
+}>;
+/**
+ * A deferred completion as the journal records it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Deferred = typeof Deferred.Type;
+/**
+ * The folded clocks and completions, keyed by their row address.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface State {
+    readonly clocks: ReadonlyMap<string, Clock>;
+    readonly deferreds: ReadonlyMap<string, Deferred>;
+}
+/**
+ * The empty fold.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const initial: State;
+/**
+ * The key of a clock row.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const clockKey: (address: {
+    readonly flowName: string;
+    readonly executionId: string;
+    readonly clockName: string;
+}) => string;
+/**
+ * The key of a completion row.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const deferredKey: (address: {
+    readonly flowName: string;
+    readonly executionId: string;
+    readonly deferredName: string;
+}) => string;
+/**
+ * Folds one committed journal entry. First writes win: a clock keeps its first
+ * schedule and first completion, and a completion its first recording and
+ * first consumption, exactly as the rows do. An entry of another type, or one
+ * whose payload names no row, leaves the state unchanged.
+ *
+ * @category folds
+ * @since 1.0.0
+ */
+export declare const reduce: (state: State, entry: JournalEvent.Entry) => State;
+/**
+ * The fold as a journal projection, for `Journal.project` over one run.
+ *
+ * @category folds
+ * @since 1.0.0
+ */
+export declare const projection: Projection.Projection<State>;
+/**
+ * The checkpoint encoding of the fold.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Encoded: Schema.Struct<{
+    readonly clocks: Schema.$Array<Schema.Struct<{
+        readonly flowName: Schema.NonEmptyString;
+        readonly executionId: Schema.NonEmptyString;
+        readonly clockName: Schema.NonEmptyString;
+        readonly deferredName: Schema.NonEmptyString;
+        readonly dueAtMs: Schema.Int;
+        readonly completedAtMs: Schema.NullOr<Schema.Int>;
+    }>>;
+    readonly deferreds: Schema.$Array<Schema.Struct<{
+        readonly flowName: Schema.NonEmptyString;
+        readonly executionId: Schema.NonEmptyString;
+        readonly deferredName: Schema.NonEmptyString;
+        readonly completedAtMs: Schema.NullOr<Schema.Int>;
+        readonly exitDigest: Schema.optionalKey<Schema.String>;
+        readonly metadataDigest: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly consumedAtMs: Schema.NullOr<Schema.Int>;
+    }>>;
+}>;
+/**
+ * The checkpoint encoding of the fold.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Encoded = typeof Encoded.Type;
+/**
+ * Encodes the fold for a checkpoint.
+ *
+ * @category folds
+ * @since 1.0.0
+ */
+export declare const encode: (state: State) => Encoded;
+/**
+ * Decodes the fold a checkpoint kept, or `None` when the checkpoint state
+ * holds none under {@link checkpointKey}.
+ *
+ * @category folds
+ * @since 1.0.0
+ */
+export declare const fromCheckpoint: (checkpointState: unknown) => Option.Option<State>;
+/**
+ * Why a rebuild could not reconstruct the tables.
+ *
+ * - `row_missing`: the journal names a completion no row holds.
+ * - `digest_mismatch`: the row holds other bytes than the journal recorded.
+ * - `run_missing`: a clock's run has no `flows_runs` row to hang it on.
+ * - `checkpoint_missing`: a compacted run's floor checkpoint keeps no fold.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare const FoldIncompleteReason: Schema.Literals<readonly ["row_missing", "digest_mismatch", "run_missing", "checkpoint_missing"]>;
+/**
+ * One reference a rebuild could not join.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare const Unjoined: Schema.Struct<{
+    readonly reason: Schema.Literals<readonly ["row_missing", "digest_mismatch", "run_missing", "checkpoint_missing"]>;
+    readonly executionId: Schema.String;
+    readonly flowName: Schema.optionalKey<Schema.String>;
+    readonly name: Schema.optionalKey<Schema.String>;
+}>;
+/**
+ * One reference a rebuild could not join.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export type Unjoined = typeof Unjoined.Type;
+declare const FoldIncomplete_base: Schema.Class<FoldIncomplete, Schema.TaggedStruct<"@smthrs/engine-store/DeferredClockFold/FoldIncomplete", {
+    readonly code: Schema.Literal<"fold_incomplete">;
+    readonly message: Schema.String;
+    readonly unjoined: Schema.$Array<Schema.Struct<{
+        readonly reason: Schema.Literals<readonly ["row_missing", "digest_mismatch", "run_missing", "checkpoint_missing"]>;
+        readonly executionId: Schema.String;
+        readonly flowName: Schema.optionalKey<Schema.String>;
+        readonly name: Schema.optionalKey<Schema.String>;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The journal references state the store no longer holds. The rebuild wrote
+ * nothing.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class FoldIncomplete extends FoldIncomplete_base {
+}
+/**
+ * The fold of one run's entries up to and including `upTo`, for the state of
+ * a checkpoint at `upTo`. It starts from the run's floor checkpoint when the
+ * run was compacted before.
+ *
+ * @category operations
+ * @since 1.0.0
+ */
+export declare const capture: (runId: string, upTo: number) => Effect.Effect<{
+    readonly clocks: readonly {
+        readonly flowName: string;
+        readonly executionId: string;
+        readonly clockName: string;
+        readonly deferredName: string;
+        readonly dueAtMs: number;
+        readonly completedAtMs: number | null;
+    }[];
+    readonly deferreds: readonly {
+        readonly executionId: string;
+        readonly flowName: string;
+        readonly completedAtMs: number | null;
+        readonly deferredName: string;
+        readonly consumedAtMs: number | null;
+        readonly exitDigest?: string;
+        readonly metadataDigest?: string | null;
+    }[];
+}, import("effect/unstable/sql/SqlError").SqlError | Journal.JournalError | FoldIncomplete, SqlClient.SqlClient | Journal.Journal>;
+/**
+ * A checkpoint state that keeps the fold: `base` (an object, or nothing) with
+ * the run's fold up to `upTo` under {@link checkpointKey}. A composition that
+ * compacts runs writes its checkpoints through this, so compaction cannot
+ * lose the deferred/clock history.
+ *
+ * @category operations
+ * @since 1.0.0
+ */
+export declare const checkpointState: (runId: string, upTo: number, base?: Readonly<Record<string, unknown>> | undefined) => Effect.Effect<{
+    "flows.engine.deferred-clock": {
+        readonly clocks: readonly {
+            readonly flowName: string;
+            readonly executionId: string;
+            readonly clockName: string;
+            readonly deferredName: string;
+            readonly dueAtMs: number;
+            readonly completedAtMs: number | null;
+        }[];
+        readonly deferreds: readonly {
+            readonly executionId: string;
+            readonly flowName: string;
+            readonly completedAtMs: number | null;
+            readonly deferredName: string;
+            readonly consumedAtMs: number | null;
+            readonly exitDigest?: string;
+            readonly metadataDigest?: string | null;
+        }[];
+    };
+}, import("effect/unstable/sql/SqlError").SqlError | Journal.JournalError | FoldIncomplete, SqlClient.SqlClient | Journal.Journal>;
+/**
+ * What a {@link rebuild} read and wrote.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Rebuilt {
+    /** Runs with deferred or clock entries, or with a compaction floor. */
+    readonly runs: number;
+    /** Clock rows written. */
+    readonly clocks: number;
+    /** Completion rows whose completion and consumption were rewritten. */
+    readonly deferreds: number;
+    /** Completion rows no journal entry explains, left as they are. */
+    readonly unexplained: number;
+}
+/**
+ * Rebuilds `flows_clock_deadlines` and the completion and consumption stamps
+ * of `flows_deferred_completions` from the journal.
+ *
+ * Every run with deferred or clock entries, and every compacted run, is
+ * folded in sequence order, from its floor checkpoint when it was compacted;
+ * a compacted run whose floor keeps no fold fails, even one that never had a
+ * clock, because the journal can no longer say. Every reference is joined
+ * before anything is written: a completion with no row or with other bytes,
+ * a clock whose run is gone, or a compacted run whose floor keeps no fold
+ * fails {@link FoldIncomplete} listing each one, and nothing is written.
+ * Otherwise, in one writer transaction, the clock table is replaced by the
+ * fold's clocks and each folded completion row gets the fold's
+ * `completed_at_ms` and `consumed_at_ms`. A completion row the journal does
+ * not explain is left alone and counted.
+ *
+ * Run it on a quiescent store, as a restore does.
+ *
+ * @category operations
+ * @since 1.0.0
+ */
+export declare const rebuild: () => Effect.Effect<{
+    runs: number;
+    clocks: number;
+    deferreds: number;
+    unexplained: number;
+}, import("effect/unstable/sql/SqlError").SqlError | import("@smthrs/database/DurableWriter").DatabaseError | Journal.JournalError | FoldIncomplete, SqlClient.SqlClient | DurableWriter | Journal.Journal>;
+export {};
+//# sourceMappingURL=DeferredClockFold.d.ts.map

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

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