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

package/dist/esm/EventTypes.js

@@ -0,0 +1,27 @@
+/**
+ * Stable engine journal record names shared with replay consumers.
+ *
+ * @since 1.0.0
+ */
+/**
+ * Persisted event types and the child-spawn effect kind. Writers and readers
+ * share these identities; changing a value requires migrating stored history.
+ * `childSpawnKind` names the effect inside a boundary, not its event type.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export const EventTypes = {
+    runDecision: "flows.engine.run-decision",
+    attemptStarted: "flows.engine.attempt-started",
+    attemptFinished: "flows.engine.attempt-finished",
+    snapshotIdentified: "flows.engine.snapshot-identified",
+    planRecorded: "flows.engine.plan-recorded",
+    subgraphAppended: "flows.engine.subgraph-appended",
+    deferredCompleted: "flows.engine.deferred-completed",
+    deferredConsumed: "flows.engine.deferred-consumed",
+    clockScheduled: "flows.engine.clock-scheduled",
+    clockCompleted: "flows.engine.clock-completed",
+    childSpawnKind: "flows/engine-store/child-spawn"
+};
+//# sourceMappingURL=EventTypes.js.map

package/dist/esm/EventTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventTypes.js","sourceRoot":"","sources":["../../src/EventTypes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,WAAW,EAAE,2BAA2B;IACxC,cAAc,EAAE,8BAA8B;IAC9C,eAAe,EAAE,+BAA+B;IAChD,kBAAkB,EAAE,kCAAkC;IACtD,YAAY,EAAE,4BAA4B;IAC1C,gBAAgB,EAAE,gCAAgC;IAClD,iBAAiB,EAAE,iCAAiC;IACpD,gBAAgB,EAAE,gCAAgC;IAClD,cAAc,EAAE,8BAA8B;IAC9C,cAAc,EAAE,8BAA8B;IAC9C,cAAc,EAAE,gCAAgC;CACxC,CAAA","sourcesContent":["/**\n * Stable engine journal record names shared with replay consumers.\n *\n * @since 1.0.0\n */\n\n/**\n * Persisted event types and the child-spawn effect kind. Writers and readers\n * share these identities; changing a value requires migrating stored history.\n * `childSpawnKind` names the effect inside a boundary, not its event type.\n *\n * @since 1.0.0\n * @category constants\n */\nexport const EventTypes = {\n  runDecision: \"flows.engine.run-decision\",\n  attemptStarted: \"flows.engine.attempt-started\",\n  attemptFinished: \"flows.engine.attempt-finished\",\n  snapshotIdentified: \"flows.engine.snapshot-identified\",\n  planRecorded: \"flows.engine.plan-recorded\",\n  subgraphAppended: \"flows.engine.subgraph-appended\",\n  deferredCompleted: \"flows.engine.deferred-completed\",\n  deferredConsumed: \"flows.engine.deferred-consumed\",\n  clockScheduled: \"flows.engine.clock-scheduled\",\n  clockCompleted: \"flows.engine.clock-completed\",\n  childSpawnKind: \"flows/engine-store/child-spawn\"\n} as const\n"]}

package/dist/esm/ExecutionFacts.d.ts

@@ -0,0 +1,59 @@
+/** Native lifecycle facts captured using the owning store transaction.
+ * @since 1.0.0
+ */
+import { ExecutionFact, type Journal } from "@smthrs/journal";
+import type { RunStore } from "@smthrs/run-store";
+import { Effect, Schema } from "effect";
+import type * as DurableEngineState from "./DurableEngineState.ts";
+/** Captured native services; never substitute an ambient control journal.
+ * @category models
+ * @since 1.0.0
+ */
+export interface Options {
+    readonly runs: RunStore.Service;
+    readonly state: Pick<DurableEngineState.Service, "waiting" | "runParents" | "transaction">;
+    readonly journal: Journal.Service;
+    readonly sourceId: string;
+}
+/** Read the semantic subset shared with ExecutionSnapshot inside its caller's transaction.
+ * @category queries
+ * @since 1.0.0
+ */
+export declare const observe: (row: RunStore.RunRow, state: Pick<Options["state"], "waiting" | "runParents">) => Effect.Effect<ExecutionFact.Observation, Schema.SchemaError>;
+/** Fact admission and cancellation intent share the same native writer transaction.
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: (options: Options) => {
+    fact: (executionId: string, baseline?: "created" | "legacy") => Effect.Effect<{
+        version: 1;
+        baseline: "created" | "legacy";
+        observation: {
+            readonly status: "running" | "suspended" | "failed" | "completed" | "pending" | "cancelled";
+            readonly createdAtMs: number & import("effect/Brand").Brand<"@smthrs/journal/TimestampMs">;
+            readonly lineageId: string & import("effect/Brand").Brand<"@smthrs/journal/JournalEvent/RunId">;
+            readonly parentRunId: (string & import("effect/Brand").Brand<"@smthrs/journal/JournalEvent/RunId">) | null;
+            readonly finishedAtMs: (number & import("effect/Brand").Brand<"@smthrs/journal/TimestampMs">) | null;
+            readonly startedAtMs: (number & import("effect/Brand").Brand<"@smthrs/journal/TimestampMs">) | null;
+            readonly executionId: string & import("effect/Brand").Brand<"@smthrs/journal/JournalEvent/RunId">;
+            readonly cancelRequestedAtMs: (number & import("effect/Brand").Brand<"@smthrs/journal/TimestampMs">) | null;
+            readonly waiting: {
+                readonly reason: string;
+                readonly wakeAtMs: (number & import("effect/Brand").Brand<"@smthrs/journal/TimestampMs">) | null;
+                readonly tokenDigest: string | null;
+                readonly request?: Schema.Json | undefined;
+                readonly point?: string | null | undefined;
+            } | null;
+            readonly flowName: string;
+            readonly roundOrdinal: number;
+            readonly treeVersion?: 1 | undefined;
+            readonly parentPolicy?: "cancel" | "detach" | undefined;
+        };
+    } | {
+        version: 1;
+        unavailable: "invalid-observation";
+    }, RunStore.RunStoreError, never>;
+    requestCancel: (executionId: string, at: number) => Effect.Effect<RunStore.RequestCancelOutcome, import("@smthrs/database/DurableWriter").DatabaseError | Journal.JournalError | RunStore.RunStoreError, never>;
+    requestCancelLineage: (executionId: string, at: number) => Effect.Effect<RunStore.RequestCancelOutcome, import("@smthrs/database/DurableWriter").DatabaseError | Journal.JournalError | RunStore.RunStoreError, never>;
+};
+//# sourceMappingURL=ExecutionFacts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionFacts.d.ts","sourceRoot":"","sources":["../../src/ExecutionFacts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAa,MAAM,iBAAiB,CAAA;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,MAAM,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,KAAK,KAAK,kBAAkB,MAAM,yBAAyB,CAAA;AAIlE;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,EAAE,SAAS,GAAG,YAAY,GAAG,aAAa,CAAC,CAAA;IAC1F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,OAAO,GAClB,KAAK,QAAQ,CAAC,MAAM,EACpB,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC,KACtD,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,EAAE,MAAM,CAAC,WAAW,CA2C1D,CAAA;AAEJ;;;GAGG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,OAAO;wBAER,MAAM,aAAY,SAAS,GAAG,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAmB7B,MAAM,MAAM,MAAM;wCAMX,MAAM,MAAM,MAAM;CAgB9D,CAAA"}

package/dist/esm/ExecutionFacts.js

@@ -0,0 +1,96 @@
+/** Native lifecycle facts captured using the owning store transaction.
+ * @since 1.0.0
+ */
+import * as Sha256 from "@smthrs/crypto/Sha256";
+import { FlowEngine } from "@smthrs/engine";
+import { DurableDeferred } from "@smthrs/flow";
+import { ExecutionFact, Redaction } from "@smthrs/journal";
+import { Effect, Option, Schema } from "effect";
+import * as JournalRecords from "./internal/JournalRecords.js";
+import * as StateTransaction from "./internal/StateTransaction.js";
+/** Read the semantic subset shared with ExecutionSnapshot inside its caller's transaction.
+ * @category queries
+ * @since 1.0.0
+ */
+export const observe = (row, state) => Effect.gen(function* () {
+    const waiting = yield* state.waiting(row.runId);
+    const parents = row.parentRunId === null ? yield* state.runParents(row.runId) : [];
+    const firstParent = [...parents].sort((a, b) => a.seq - b.seq || a.parentId.localeCompare(b.parentId))[0];
+    const encoded = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({
+        flowName: Schema.NonEmptyString,
+        onParentExit: Schema.optional(Schema.Literals(["cancel", "detach"]))
+    })))(row.stateJson);
+    let point = null;
+    if (Option.isSome(waiting) && waiting.value.token !== null) {
+        try {
+            const { deferredName } = DurableDeferred.TokenParsed.fromString(waiting.value.token);
+            if (deferredName.startsWith("WaitFor/")) {
+                point = deferredName.slice("WaitFor/".length);
+            }
+        }
+        catch { /* An opaque plugin token remains an operational address only. */ }
+    }
+    return yield* Schema.decodeUnknownEffect(ExecutionFact.Observation)({
+        executionId: row.runId,
+        flowName: encoded.flowName,
+        status: row.status,
+        createdAtMs: row.createdAtMs,
+        startedAtMs: row.startedAtMs,
+        finishedAtMs: row.finishedAtMs,
+        parentRunId: row.parentRunId ?? firstParent?.parentId ?? null,
+        lineageId: row.lineageId ?? row.runId,
+        roundOrdinal: row.roundOrdinal ?? 0,
+        cancelRequestedAtMs: row.cancelRequestedAtMs,
+        treeVersion: 1,
+        parentPolicy: encoded.onParentExit ?? "cancel",
+        waiting: Option.isNone(waiting) ? null : {
+            reason: waiting.value.reason,
+            wakeAtMs: waiting.value.wakeAt,
+            tokenDigest: waiting.value.token === null ? null : Sha256.digestSync(waiting.value.token),
+            point,
+            request: waiting.value.request === undefined ? null : Redaction.redact(waiting.value.request)
+        }
+    });
+});
+/** Fact admission and cancellation intent share the same native writer transaction.
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = (options) => {
+    const transactState = StateTransaction.make(options.state, options.journal);
+    const fact = (executionId, baseline = "legacy") => options.runs.get(executionId).pipe(Effect.flatMap((row) => observe(row, options.state)), Effect.map((observation) => ({ version: 1, baseline, observation })), 
+    // Invalid semantic metadata must not prevent the driver's existing
+    // corruption/invalid-round path from settling the run. Record a named
+    // coverage failure; never normalize a bad ordinal or invent ancestry.
+    Effect.catchTag("SchemaError", () => Effect.succeed({ version: 1, unavailable: "invalid-observation" })));
+    const cancelled = (executionId) => Effect.gen(function* () {
+        const executionFact = yield* fact(executionId);
+        yield* options.journal.emitDurableUnfenced(JournalRecords.runDecision({
+            runId: executionId,
+            lineageId: FlowEngine.Lineage.root(executionId),
+            sourceId: options.sourceId
+        }, { decision: "cancel-requested", executionFact }));
+    });
+    const requestCancel = (executionId, at) => transactState(Effect.gen(function* () {
+        const outcome = yield* options.runs.requestCancel(executionId, at);
+        if (outcome._tag === "CancelRequested")
+            yield* cancelled(executionId);
+        return outcome;
+    }));
+    const requestCancelLineage = (executionId, at) => transactState(Effect.gen(function* () {
+        const before = yield* options.runs.lineage(executionId);
+        const outcome = yield* options.runs.requestCancelLineage(executionId, at);
+        if (outcome._tag === "CancelRequested") {
+            // The set update excludes terminal/already-requested rows. Record exactly
+            // the rows it changed, not a guessed terminal cancellation timestamp.
+            for (const row of before) {
+                if (row.cancelRequestedAtMs === null && !["completed", "failed", "cancelled"].includes(row.status)) {
+                    yield* cancelled(row.runId);
+                }
+            }
+        }
+        return outcome;
+    }));
+    return { fact, requestCancel, requestCancelLineage };
+};
+//# sourceMappingURL=ExecutionFacts.js.map

package/dist/esm/ExecutionFacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionFacts.js","sourceRoot":"","sources":["../../src/ExecutionFacts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,EAAE,aAAa,EAAgB,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAExE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/C,OAAO,KAAK,cAAc,MAAM,8BAA8B,CAAA;AAC9D,OAAO,KAAK,gBAAgB,MAAM,gCAAgC,CAAA;AAalE;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,GAAoB,EACpB,KAAuD,EACO,EAAE,CAChE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IAC/C,MAAM,OAAO,GAAG,GAAG,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAClF,MAAM,WAAW,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACzG,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAC/C,MAAM,CAAC,cAAc,CACnB,MAAM,CAAC,MAAM,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC,cAAc;QAC/B,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;KACrE,CAAC,CACH,CACF,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;IAChB,IAAI,KAAK,GAAkB,IAAI,CAAA;IAC/B,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,EAAE,YAAY,EAAE,GAAG,eAAe,CAAC,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;YACpF,IAAI,YAAY,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBACxC,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;YAC/C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,iEAAiE,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;QAClE,WAAW,EAAE,GAAG,CAAC,KAAK;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,WAAW,EAAE,QAAQ,IAAI,IAAI;QAC7D,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,KAAK;QACrC,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,CAAC;QACnC,mBAAmB,EAAE,GAAG,CAAC,mBAAmB;QAC5C,WAAW,EAAE,CAAC;QACd,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,QAAQ;QAC9C,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YACvC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,MAAM;YAC5B,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,MAAM;YAC9B,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;YACzF,KAAK;YACL,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;SAC9F;KACF,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEJ;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAAgB,EAAE,EAAE;IACvC,MAAM,aAAa,GAAG,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3E,MAAM,IAAI,GAAG,CAAC,WAAmB,EAAE,WAAiC,QAAQ,EAAE,EAAE,CAC9E,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAChC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EACpD,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;IAC7E,mEAAmE;IACnE,sEAAsE;IACtE,sEAAsE;IACtE,MAAM,CAAC,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE,CAClC,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAU,EAAE,WAAW,EAAE,qBAA8B,EAAE,CAAC,CAAC,CACxF,CAAA;IACH,MAAM,SAAS,GAAG,CAAC,WAAmB,EAAE,EAAE,CACxC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,MAAM,aAAa,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;QAC9C,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,cAAc,CAAC,WAAW,CAAC;YACpE,KAAK,EAAE,WAAW;YAClB,SAAS,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC;YAC/C,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,EAAE,EAAE,QAAQ,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC,CAAC,CAAA;IACtD,CAAC,CAAC,CAAA;IACJ,MAAM,aAAa,GAAG,CAAC,WAAmB,EAAE,EAAU,EAAE,EAAE,CACxD,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAChC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;QAClE,IAAI,OAAO,CAAC,IAAI,KAAK,iBAAiB;YAAE,KAAK,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAA;QACrE,OAAO,OAAO,CAAA;IAChB,CAAC,CAAC,CAAC,CAAA;IACL,MAAM,oBAAoB,GAAG,CAAC,WAAmB,EAAE,EAAU,EAAE,EAAE,CAC/D,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAChC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;QACvD,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;QACzE,IAAI,OAAO,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YACvC,0EAA0E;YAC1E,sEAAsE;YACtE,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;gBACzB,IAAI,GAAG,CAAC,mBAAmB,KAAK,IAAI,IAAI,CAAC,CAAC,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBACnG,KAAK,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;gBAC7B,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAA;IAChB,CAAC,CAAC,CAAC,CAAA;IACL,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,oBAAoB,EAAE,CAAA;AACtD,CAAC,CAAA","sourcesContent":["/** Native lifecycle facts captured using the owning store transaction.\n * @since 1.0.0\n */\n\nimport * as Sha256 from \"@smthrs/crypto/Sha256\"\nimport { FlowEngine } from \"@smthrs/engine\"\nimport { DurableDeferred } from \"@smthrs/flow\"\nimport { ExecutionFact, type Journal, Redaction } from \"@smthrs/journal\"\nimport type { RunStore } from \"@smthrs/run-store\"\nimport { Effect, Option, Schema } from \"effect\"\nimport type * as DurableEngineState from \"./DurableEngineState.ts\"\nimport * as JournalRecords from \"./internal/JournalRecords.ts\"\nimport * as StateTransaction from \"./internal/StateTransaction.ts\"\n\n/** Captured native services; never substitute an ambient control journal.\n * @category models\n * @since 1.0.0\n */\nexport interface Options {\n  readonly runs: RunStore.Service\n  readonly state: Pick<DurableEngineState.Service, \"waiting\" | \"runParents\" | \"transaction\">\n  readonly journal: Journal.Service\n  readonly sourceId: string\n}\n\n/** Read the semantic subset shared with ExecutionSnapshot inside its caller's transaction.\n * @category queries\n * @since 1.0.0\n */\nexport const observe = (\n  row: RunStore.RunRow,\n  state: Pick<Options[\"state\"], \"waiting\" | \"runParents\">\n): Effect.Effect<ExecutionFact.Observation, Schema.SchemaError> =>\n  Effect.gen(function*() {\n    const waiting = yield* state.waiting(row.runId)\n    const parents = row.parentRunId === null ? yield* state.runParents(row.runId) : []\n    const firstParent = [...parents].sort((a, b) => a.seq - b.seq || a.parentId.localeCompare(b.parentId))[0]\n    const encoded = yield* Schema.decodeUnknownEffect(\n      Schema.fromJsonString(\n        Schema.Struct({\n          flowName: Schema.NonEmptyString,\n          onParentExit: Schema.optional(Schema.Literals([\"cancel\", \"detach\"]))\n        })\n      )\n    )(row.stateJson)\n    let point: string | null = null\n    if (Option.isSome(waiting) && waiting.value.token !== null) {\n      try {\n        const { deferredName } = DurableDeferred.TokenParsed.fromString(waiting.value.token)\n        if (deferredName.startsWith(\"WaitFor/\")) {\n          point = deferredName.slice(\"WaitFor/\".length)\n        }\n      } catch { /* An opaque plugin token remains an operational address only. */ }\n    }\n    return yield* Schema.decodeUnknownEffect(ExecutionFact.Observation)({\n      executionId: row.runId,\n      flowName: encoded.flowName,\n      status: row.status,\n      createdAtMs: row.createdAtMs,\n      startedAtMs: row.startedAtMs,\n      finishedAtMs: row.finishedAtMs,\n      parentRunId: row.parentRunId ?? firstParent?.parentId ?? null,\n      lineageId: row.lineageId ?? row.runId,\n      roundOrdinal: row.roundOrdinal ?? 0,\n      cancelRequestedAtMs: row.cancelRequestedAtMs,\n      treeVersion: 1,\n      parentPolicy: encoded.onParentExit ?? \"cancel\",\n      waiting: Option.isNone(waiting) ? null : {\n        reason: waiting.value.reason,\n        wakeAtMs: waiting.value.wakeAt,\n        tokenDigest: waiting.value.token === null ? null : Sha256.digestSync(waiting.value.token),\n        point,\n        request: waiting.value.request === undefined ? null : Redaction.redact(waiting.value.request)\n      }\n    })\n  })\n\n/** Fact admission and cancellation intent share the same native writer transaction.\n * @category constructors\n * @since 1.0.0\n */\nexport const make = (options: Options) => {\n  const transactState = StateTransaction.make(options.state, options.journal)\n  const fact = (executionId: string, baseline: \"created\" | \"legacy\" = \"legacy\") =>\n    options.runs.get(executionId).pipe(\n      Effect.flatMap((row) => observe(row, options.state)),\n      Effect.map((observation) => ({ version: 1 as const, baseline, observation })),\n      // Invalid semantic metadata must not prevent the driver's existing\n      // corruption/invalid-round path from settling the run. Record a named\n      // coverage failure; never normalize a bad ordinal or invent ancestry.\n      Effect.catchTag(\"SchemaError\", () =>\n        Effect.succeed({ version: 1 as const, unavailable: \"invalid-observation\" as const }))\n    )\n  const cancelled = (executionId: string) =>\n    Effect.gen(function*() {\n      const executionFact = yield* fact(executionId)\n      yield* options.journal.emitDurableUnfenced(JournalRecords.runDecision({\n        runId: executionId,\n        lineageId: FlowEngine.Lineage.root(executionId),\n        sourceId: options.sourceId\n      }, { decision: \"cancel-requested\", executionFact }))\n    })\n  const requestCancel = (executionId: string, at: number) =>\n    transactState(Effect.gen(function*() {\n      const outcome = yield* options.runs.requestCancel(executionId, at)\n      if (outcome._tag === \"CancelRequested\") yield* cancelled(executionId)\n      return outcome\n    }))\n  const requestCancelLineage = (executionId: string, at: number) =>\n    transactState(Effect.gen(function*() {\n      const before = yield* options.runs.lineage(executionId)\n      const outcome = yield* options.runs.requestCancelLineage(executionId, at)\n      if (outcome._tag === \"CancelRequested\") {\n        // The set update excludes terminal/already-requested rows. Record exactly\n        // the rows it changed, not a guessed terminal cancellation timestamp.\n        for (const row of before) {\n          if (row.cancelRequestedAtMs === null && ![\"completed\", \"failed\", \"cancelled\"].includes(row.status)) {\n            yield* cancelled(row.runId)\n          }\n        }\n      }\n      return outcome\n    }))\n  return { fact, requestCancel, requestCancelLineage }\n}\n"]}

package/dist/esm/ExecutionSnapshot.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Revisioned, round-scoped engine observations.
+ *
+ * @since 1.0.0
+ */
+import type { RunStoreError } from "@smthrs/run-store/RunStore";
+import { Context, Effect, Layer } from "effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import * as Read from "./internal/ExecutionSnapshotRead.ts";
+import * as Relations from "./internal/ExecutionSnapshotRelations.ts";
+export type { RelatedOptions, RelatedPage } from "./internal/ExecutionSnapshotRelations.ts";
+/**
+ * Engine database identity and observed watermark.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Position = Read.Position;
+/**
+ * An authoritative execution row.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Observed = Read.Observed;
+/**
+ * A structured durable wait.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Waiting = Read.Waiting;
+/**
+ * Absence is explicit; deleted distinguishes retained deletion evidence.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Missing extends Position {
+    readonly _tag: "Missing";
+    readonly runId: string;
+    readonly deleted: boolean;
+}
+/**
+ * One requested execution observation.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Snapshot = Observed | Missing;
+/**
+ * Coherent observations in request order, including duplicates.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Batch extends Position {
+    readonly snapshots: ReadonlyArray<Snapshot>;
+}
+/**
+ * Maximum IDs admitted by one read.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const maximumBatchSize = 200;
+/**
+ * Reserves a deferred SQLite / repeatable-read PostgreSQL read transaction
+ * without the durable writer's admission lock. An existing transaction is
+ * reused with its caller-selected isolation.
+ * The supplied effect must contain observations only.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const withReadTransaction: <A, E, R>(sql: SqlClient.SqlClient, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, import("effect/unstable/sql/SqlError").SqlError | E, R>;
+/**
+ * Engine observation operations.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Service {
+    readonly read: (runIds: ReadonlyArray<string>) => Effect.Effect<Batch, RunStoreError>;
+    readonly related: (options: Relations.RelatedOptions) => Effect.Effect<Relations.RelatedPage, RunStoreError>;
+}
+declare const ExecutionSnapshot_base: Context.ServiceClass<ExecutionSnapshot, "@smthrs/engine-store/ExecutionSnapshot", Service>;
+/**
+ * Engine observation service.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export declare class ExecutionSnapshot extends ExecutionSnapshot_base {
+}
+/**
+ * Guard for applying observations and tombstones to a source-bound projection.
+ * Source replacement requires an explicit rebuild, never a revision comparison.
+ * @category guards
+ * @since 1.0.0
+ */
+export declare const isNewer: (incoming: Position, current: Position) => boolean;
+/**
+ * Constructs the SQL read port; migrations must already be applied.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: () => Effect.Effect<Service, never, SqlClient.SqlClient>;
+/**
+ * Provides the SQL observation port.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layer: Layer.Layer<ExecutionSnapshot, never, SqlClient.SqlClient>;
+//# sourceMappingURL=ExecutionSnapshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionSnapshot.d.ts","sourceRoot":"","sources":["../../src/ExecutionSnapshot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAU,MAAM,QAAQ,CAAA;AACvD,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAC1D,OAAO,KAAK,IAAI,MAAM,qCAAqC,CAAA;AAC3D,OAAO,KAAK,SAAS,MAAM,0CAA0C,CAAA;AAErE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAA;AAE3F;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;AACpC;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;AACpC;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;AAClC;;;;;GAKG;AACH,MAAM,WAAW,OAAQ,SAAQ,QAAQ;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AACD;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAA;AACzC;;;;;GAKG;AACH,MAAM,WAAW,KAAM,SAAQ,QAAQ;IACrC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;CAC5C;AACD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAA;AACnC;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,iJAAmB,CAAA;AACnD;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAA;IACrF,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,cAAc,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,aAAa,CAAC,CAAA;CAC7G;;AACD;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,sBAEtC;CAAG;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,UAAU,QAAQ,EAAE,SAAS,QAAQ,KAAG,OACY,CAAA;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,IAAI,QAAO,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,CA8DrE,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,iBAAiB,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,CAA2C,CAAA"}

package/dist/esm/ExecutionSnapshot.js

@@ -0,0 +1,95 @@
+/**
+ * Revisioned, round-scoped engine observations.
+ *
+ * @since 1.0.0
+ */
+import * as Dialect from "@smthrs/database/Dialect";
+import { Context, Effect, Layer, Schema } from "effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import * as Read from "./internal/ExecutionSnapshotRead.js";
+import * as Relations from "./internal/ExecutionSnapshotRelations.js";
+/**
+ * Maximum IDs admitted by one read.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const maximumBatchSize = 200;
+/**
+ * Reserves a deferred SQLite / repeatable-read PostgreSQL read transaction
+ * without the durable writer's admission lock. An existing transaction is
+ * reused with its caller-selected isolation.
+ * The supplied effect must contain observations only.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const withReadTransaction = Read.transaction;
+/**
+ * Engine observation service.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export class ExecutionSnapshot extends Context.Service()("@smthrs/engine-store/ExecutionSnapshot") {
+}
+/**
+ * Guard for applying observations and tombstones to a source-bound projection.
+ * Source replacement requires an explicit rebuild, never a revision comparison.
+ * @category guards
+ * @since 1.0.0
+ */
+export const isNewer = (incoming, current) => incoming.source === current.source && incoming.revision > current.revision;
+/**
+ * Constructs the SQL read port; migrations must already be applied.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = () => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const read = (runIds) => Read.boundary("ExecutionSnapshot.read", Effect.gen(function* () {
+        const ids = yield* Read.decode(Schema.Array(Read.Identifier).check(Schema.isMaxLength(maximumBatchSize)), runIds);
+        const batch = yield* Read.transaction(sql, Effect.gen(function* () {
+            const at = yield* Read.position(sql);
+            if (ids.length === 0)
+                return { ...at, snapshots: [] };
+            const rows = yield* Dialect.query(sql, `SELECT ${Read.selectColumns} FROM flows_runs r
+            LEFT JOIN flows_run_changes c ON c.run_id = r.run_id
+            WHERE r.run_id IN (${ids.map(() => "?").join(",")})`, ids);
+            const snapshots = new Map();
+            for (const row of rows) {
+                const value = yield* Read.observed(row, at);
+                snapshots.set(value.runId, value);
+            }
+            const changes = yield* Dialect.query(sql, `SELECT run_id, revision, deleted FROM flows_run_changes WHERE run_id IN (${ids.map(() => "?").join(",")})`, ids);
+            for (const change of changes) {
+                if (snapshots.has(change.run_id))
+                    continue;
+                const revision = yield* Read.decode(Read.Natural.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(at.revision)), change.revision);
+                yield* Read.decode(Schema.Literal(1), change.deleted);
+                snapshots.set(change.run_id, {
+                    _tag: "Missing",
+                    runId: change.run_id,
+                    source: at.source,
+                    revision,
+                    deleted: true
+                });
+            }
+            return {
+                ...at,
+                snapshots: ids.map((runId) => snapshots.get(runId) ?? { _tag: "Missing", runId, ...at, deleted: false })
+            };
+        }));
+        return yield* Read.coherentBatch(ids, batch);
+    }));
+    return { read, related: Relations.make(sql, read) };
+});
+/**
+ * Provides the SQL observation port.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer = Layer.effect(ExecutionSnapshot)(make());
+//# sourceMappingURL=ExecutionSnapshot.js.map

package/dist/esm/ExecutionSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionSnapshot.js","sourceRoot":"","sources":["../../src/ExecutionSnapshot.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Revisioned, round-scoped engine observations.\n *\n * @since 1.0.0\n */\n\nimport * as Dialect from \"@smthrs/database/Dialect\"\nimport type { RunStoreError } from \"@smthrs/run-store/RunStore\"\nimport { Context, Effect, Layer, Schema } from \"effect\"\nimport * as SqlClient from \"effect/unstable/sql/SqlClient\"\nimport * as Read from \"./internal/ExecutionSnapshotRead.ts\"\nimport * as Relations from \"./internal/ExecutionSnapshotRelations.ts\"\n\nexport type { RelatedOptions, RelatedPage } from \"./internal/ExecutionSnapshotRelations.ts\"\n\n/**\n * Engine database identity and observed watermark.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Position = Read.Position\n/**\n * An authoritative execution row.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Observed = Read.Observed\n/**\n * A structured durable wait.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Waiting = Read.Waiting\n/**\n * Absence is explicit; deleted distinguishes retained deletion evidence.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Missing extends Position {\n  readonly _tag: \"Missing\"\n  readonly runId: string\n  readonly deleted: boolean\n}\n/**\n * One requested execution observation.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Snapshot = Observed | Missing\n/**\n * Coherent observations in request order, including duplicates.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Batch extends Position {\n  readonly snapshots: ReadonlyArray<Snapshot>\n}\n/**\n * Maximum IDs admitted by one read.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const maximumBatchSize = 200\n/**\n * Reserves a deferred SQLite / repeatable-read PostgreSQL read transaction\n * without the durable writer's admission lock. An existing transaction is\n * reused with its caller-selected isolation.\n * The supplied effect must contain observations only.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const withReadTransaction = Read.transaction\n/**\n * Engine observation operations.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Service {\n  readonly read: (runIds: ReadonlyArray<string>) => Effect.Effect<Batch, RunStoreError>\n  readonly related: (options: Relations.RelatedOptions) => Effect.Effect<Relations.RelatedPage, RunStoreError>\n}\n/**\n * Engine observation service.\n *\n * @category services\n * @since 1.0.0\n */\nexport class ExecutionSnapshot extends Context.Service<ExecutionSnapshot, Service>()(\n  \"@smthrs/engine-store/ExecutionSnapshot\"\n) {}\n\n/**\n * Guard for applying observations and tombstones to a source-bound projection.\n * Source replacement requires an explicit rebuild, never a revision comparison.\n * @category guards\n * @since 1.0.0\n */\nexport const isNewer = (incoming: Position, current: Position): boolean =>\n  incoming.source === current.source && incoming.revision > current.revision\n\n/**\n * Constructs the SQL read port; migrations must already be applied.\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    const read: Service[\"read\"] = (runIds) =>\n      Read.boundary(\n        \"ExecutionSnapshot.read\",\n        Effect.gen(function*() {\n          const ids = yield* Read.decode(\n            Schema.Array(Read.Identifier).check(Schema.isMaxLength(maximumBatchSize)),\n            runIds\n          )\n          const batch = yield* Read.transaction(\n            sql,\n            Effect.gen(function*() {\n              const at = yield* Read.position(sql)\n              if (ids.length === 0) return { ...at, snapshots: [] }\n              const rows = yield* Dialect.query(\n                sql,\n                `SELECT ${Read.selectColumns} FROM flows_runs r\n            LEFT JOIN flows_run_changes c ON c.run_id = r.run_id\n            WHERE r.run_id IN (${ids.map(() => \"?\").join(\",\")})`,\n                ids\n              )\n              const snapshots = new Map<string, Snapshot>()\n              for (const row of rows) {\n                const value = yield* Read.observed(row, at)\n                snapshots.set(value.runId, value)\n              }\n              const changes = yield* Dialect.query<{ run_id: string; revision: number; deleted: number }>(\n                sql,\n                `SELECT run_id, revision, deleted FROM flows_run_changes WHERE run_id IN (${\n                  ids.map(() => \"?\").join(\",\")\n                })`,\n                ids\n              )\n              for (const change of changes) {\n                if (snapshots.has(change.run_id)) continue\n                const revision = yield* Read.decode(\n                  Read.Natural.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(at.revision)),\n                  change.revision\n                )\n                yield* Read.decode(Schema.Literal(1), change.deleted)\n                snapshots.set(change.run_id, {\n                  _tag: \"Missing\",\n                  runId: change.run_id,\n                  source: at.source,\n                  revision,\n                  deleted: true\n                })\n              }\n              return {\n                ...at,\n                snapshots: ids.map((runId): Snapshot =>\n                  snapshots.get(runId) ?? { _tag: \"Missing\", runId, ...at, deleted: false }\n                )\n              }\n            })\n          )\n          return yield* Read.coherentBatch(ids, batch)\n        })\n      )\n    return { read, related: Relations.make(sql, read) }\n  })\n\n/**\n * Provides the SQL observation port.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layer: Layer.Layer<ExecutionSnapshot, never, SqlClient.SqlClient> = Layer.effect(ExecutionSnapshot)(make())\n"]}

package/dist/esm/Inconsistency.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Receiver for detected engine inconsistencies.
+ *
+ * Modeled on Skyframe's `GraphInconsistencyReceiver`: the store layer detects
+ * an invariant violation — today, a content-addressed cache key that produced
+ * a different result than the recorded row — and this service decides whether
+ * the run fails or tolerates it. Either way the conflict is journaled, so the
+ * detector is never wired to /dev/null.
+ *
+ * The `note` signature deliberately matches the plugin spec's
+ * `cacheInconsistency` hook (`(event) => Effect<InconsistencyVerdict>`); the
+ * strict layer is the future default plugin.
+ *
+ * The core default is strict so an invariant violation cannot pass silently.
+ *
+ * Governing designs: `docs/concepts/attempts-and-replay.md` and
+ * `apps/site/src/content/docs/docs/concepts/flows-actions-plans.mdx`.
+ *
+ * @since 0.1.0
+ */
+import { Journal } from "@smthrs/journal";
+import type { Ownership } from "@smthrs/run-store";
+import type { CacheStore } from "@smthrs/step-cache";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+/**
+ * Decision returned by an inconsistency receiver.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type InconsistencyVerdict = "fail" | "tolerate";
+/**
+ * A content-addressed cache key that produced a result different from the
+ * recorded row — a hermeticity/determinism violation.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface CacheConflict {
+    readonly key: string;
+    readonly existing: CacheStore.CacheEntry | undefined;
+    readonly attempted: CacheStore.CacheEntry;
+}
+/**
+ * Recorded boundary evidence whose blob no longer hashes to its recorded
+ * digest — on-disk corruption of the content-addressed store, detected while
+ * replaying a verified cache hit or a succeeded attempt (issue #150).
+ * Distinct from a transient host failure, which merely refuses the replay
+ * and stays retryable.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface BlobCorruption {
+    /** The run that observed the corruption; the journaling target. */
+    readonly runId: string;
+    readonly keyDigest: string;
+    readonly path: string;
+    readonly recordedDigest: string;
+    readonly measuredDigest: string;
+    /**
+     * Provenance of the corrupt evidence when it came from a shared cache row;
+     * absent when it came from this run's own succeeded attempt row.
+     */
+    readonly recordedRunId?: string | undefined;
+    readonly recordedEventSeq?: number | undefined;
+}
+/**
+ * Inconsistency receiver operations.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    readonly note: (event: CacheConflict) => Effect.Effect<InconsistencyVerdict, Journal.JournalError>;
+    /**
+     * Observes on-disk corruption of recorded boundary evidence (issue #150).
+     * `"fail"` fails the dispatch; `"tolerate"` lets it fall back to a real
+     * execution (which re-captures and heals the corrupt address).
+     */
+    readonly noteCorruption: (event: BlobCorruption) => Effect.Effect<InconsistencyVerdict, Journal.JournalError>;
+}
+declare const Inconsistency_base: Context.ServiceClass<Inconsistency, "@smthrs/engine-store/Inconsistency", Service>;
+/**
+ * Service tag for the engine inconsistency receiver.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class Inconsistency extends Inconsistency_base {
+}
+/**
+ * Options for constructing a journaling inconsistency receiver.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface MakeOptions {
+    readonly journal: Journal.Service;
+    readonly verdict: InconsistencyVerdict;
+    /**
+     * The owner the conflict record is fenced to: a reclaimed run cannot append
+     * hermeticity evidence it no longer owns. Required — every composer of this
+     * receiver is a run's owner.
+     */
+    readonly owner: Ownership.OwnerId;
+}
+/**
+ * Builds a receiver that journals every conflict under the run that attempted
+ * the write and returns a fixed verdict.
+ *
+ * The record goes through the journal's durable channel: a cache conflict is
+ * hermeticity evidence, and a `tolerate` verdict that silently dropped its
+ * only record would wire the detector to /dev/null (issue #10).
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (options: MakeOptions) => Service;
+/**
+ * Builds a receiver from overrides. The default notes nothing and tolerates.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides a receiver that never journals and always tolerates.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: (overrides?: Partial<Service>) => Layer.Layer<Inconsistency>;
+/**
+ * Journals every cache conflict and fails the run. This is the default
+ * receiver for engine wiring: a non-hermetic sealed hard-boundary action is
+ * a defect, not a condition to paper over.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerStrict: (owner: Ownership.OwnerId) => Layer.Layer<Inconsistency, never, Journal.Journal>;
+/**
+ * Journals every cache conflict and continues, preserving the first-recorded
+ * row (Skyframe's tolerant production configuration).
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerTolerant: (owner: Ownership.OwnerId) => Layer.Layer<Inconsistency, never, Journal.Journal>;
+export {};
+//# sourceMappingURL=Inconsistency.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Inconsistency.d.ts","sourceRoot":"","sources":["../../src/Inconsistency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAGrC;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,UAAU,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,GAAG,SAAS,CAAA;IACpD,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,UAAU,CAAA;CAC1C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IAClG;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;CAC9G;;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,kBAA+E;CAAG;AAErH;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAA;IACjC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;IACtC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,OAAO,CAAA;CAClC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,WAAW,KAAG,OAwE1C,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,YAAW,OAAO,CAAC,OAAO,CAAM,KAAG,OAI1D,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,YAAW,OAAO,CAAC,OAAO,CAAM,KAAG,KAAK,CAAC,KAAK,CAAC,aAAa,CACnC,CAAA;AAEnD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,SAAS,CAAC,OAAO,KAAG,KAAK,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAMrG,CAAA;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,SAAS,CAAC,OAAO,KAAG,KAAK,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAMvG,CAAA"}