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

package/dist/esm/EngineStoreMetrics.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Standard metric definitions for the engine-store hot paths.
+ *
+ * This module only defines the metric handles, following the shape of
+ * `RunStoreMetrics` and Effect's `ClusterMetrics`. The dispatch seam
+ * (`internal/ActionPersistence`), the plan scheduler, the workspace sandbox,
+ * and the run driver update them as outcomes are decided. No exporter ships in
+ * this package; provide one — for example `@smthrs/observability` — and
+ * these series appear in it.
+ *
+ * Counters over an effect's exit are keyed by {@link ExitTag} records, so an
+ * update is a lookup rather than a branch, and durations land in
+ * `Metric.timer` histograms through Effect's own `Effect.trackDuration`. The
+ * same exit observation annotates the operation span with its outcome; none of
+ * the instrumentation combinators alters the instrumented effect's result or
+ * cause.
+ *
+ * @since 0.1.0
+ */
+import type * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import type * as Exit from "effect/Exit";
+import * as Metric from "effect/Metric";
+/**
+ * How an instrumented effect exited: `Success`, `Failure` (any non-interrupt
+ * cause), or `Interrupt` (an interrupt-only cause — in this store that is the
+ * fencing self-interruption as well as caller cancellation).
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ExitTag = "Success" | "Failure" | "Interrupt";
+/**
+ * Classifies an exit for an {@link ExitTag}-keyed counter record.
+ *
+ * @category accessors
+ * @since 0.1.0
+ */
+export declare const exitTag: <A, E>(exit: Exit.Exit<A, E>) => ExitTag;
+/**
+ * Observes an effect with a duration timer and an exit-outcome counter.
+ *
+ * Composes Effect's own `Effect.trackDuration` (monotonic clock, records on
+ * success, failure, and interruption alike) with an `Effect.onExit` counter
+ * update and current-span annotation, so the instrumented effect's exit —
+ * value, cause, and interruption — propagates byte-identically. This is the
+ * dual-instrument shape production Effect services use for hot-path
+ * operations.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const observe: (instruments: {
+    readonly timer: Metric.Histogram<Duration.Duration>;
+    readonly counter: { readonly [Tag in ExitTag]: Metric.Metric<number, Metric.CounterState<number>>; };
+}) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * Counter over durable action dispatches through
+ * `internal/ActionPersistence`, dimensioned by exit `outcome` (`success`,
+ * `failure`, or `interrupt`). A cache-served replay and a fresh execution
+ * both count: the dispatch is the unit the engine retries and fences.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const dispatches: Metric.Counter<number>;
+/**
+ * Latency histogram over durable action dispatches, from admission through
+ * settlement (cache verification, execution, copy-back, and the terminal
+ * row included).
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const dispatchDuration: Metric.Histogram<Duration.Duration>;
+/**
+ * `dispatches` views keyed by {@link ExitTag}.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const dispatch: {
+    readonly Success: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Failure: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Interrupt: Metric.Metric<number, Metric.CounterState<number>>;
+};
+/**
+ * Counter over scheduler admission passes that launched work. The
+ * completion-driven scheduler re-computes the ready set after every terminal
+ * event; only a pass that admits at least one node counts, so the series
+ * reads as "how many times the scheduler opened dispatch permits", not as
+ * event-loop noise.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const schedulerAdmissions: Metric.Counter<number>;
+/**
+ * Latency histogram over one scheduler dispatch, admission through terminal
+ * event: measurement, keying, the durable-action seam, and every rebase turn
+ * of the same node's loop land in a single observation.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const schedulerDispatchDuration: Metric.Histogram<Duration.Duration>;
+/**
+ * Counter over plan node settlements, dimensioned by the scheduler `outcome`
+ * (`built`, `clean`, `failed`, `skipped`, or `deferred`) — the per-node
+ * evaluation vocabulary `PlanScheduler` journals.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const schedulerNodes: Metric.Counter<number>;
+/**
+ * `schedulerNodes` views keyed by `PlanScheduler.Outcome`.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const node: {
+    readonly deferred: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly failed: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly built: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly clean: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly skipped: Metric.Metric<number, Metric.CounterState<number>>;
+};
+/**
+ * Counter over isolated workspace executions (`WorkspaceSandbox.execute`),
+ * dimensioned by exit `outcome`. An `Invalidated` verdict is a `success`
+ * exit — the transaction ran and answered; the verdict itself is journaled.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const sandboxExecutions: Metric.Counter<number>;
+/**
+ * `sandboxExecutions` views keyed by {@link ExitTag}.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const sandboxExecution: {
+    readonly Success: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Failure: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Interrupt: Metric.Metric<number, Metric.CounterState<number>>;
+};
+/**
+ * Latency histogram over isolated workspace executions.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const sandboxExecutionDuration: Metric.Histogram<Duration.Duration>;
+/**
+ * Counter over sandbox materializations (`WorkspaceSandbox.materialize` —
+ * the one host write), dimensioned by exit `outcome`.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const sandboxMaterializations: Metric.Counter<number>;
+/**
+ * `sandboxMaterializations` views keyed by {@link ExitTag}.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const materialization: {
+    readonly Success: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Failure: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Interrupt: Metric.Metric<number, Metric.CounterState<number>>;
+};
+/**
+ * Latency histogram over sandbox materializations.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const materializationDuration: Metric.Histogram<Duration.Duration>;
+/**
+ * Counter over copy-back compare-and-set refusals: the preflight found host
+ * state that moved after the transaction's base snapshot. The engine answers
+ * one with a rebase or a conflict strategy, so the rate is contention
+ * evidence, not an error rate.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const materializationConflicts: Metric.Counter<number>;
+/**
+ * Counter over step-boundary settlements at the dispatch seam, dimensioned by
+ * `outcome`: `clean` evidence, an `expected`-mode `deviation`, or a hard
+ * `violation` (undeclared write, missing declared output, surviving declared
+ * removal), with `refused` for a host that could not settle at all.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const boundarySettlements: Metric.Counter<number>;
+/**
+ * `boundarySettlements` views keyed by settlement classification.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const boundarySettlement: {
+    readonly Clean: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Deviation: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Violation: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Refused: Metric.Metric<number, Metric.CounterState<number>>;
+};
+/**
+ * Counter over the EFFECTIVE step-boundary cache decisions at the dispatch
+ * seam, dimensioned by `outcome`. `flows_step_cache_lookups` counts raw row
+ * presence at `CacheStore.get`; this series records what the dispatch
+ * actually did with the row after read-set verification and output
+ * materialization — `verified_hit` served the cached result, and every other
+ * outcome fell through to a real execution (`miss` no row,
+ * `unverifiable_evidence` a row whose recorded evidence cannot justify reuse,
+ * `unmeasurable` a host that could not re-measure the read set,
+ * `stale_read_set` a measured mismatch, `replay_failed` verified evidence the
+ * host could not re-materialize). Each decision is counted where it takes
+ * effect: `verified_hit` as the cached result is returned, a fall-through
+ * outcome as the dispatch proceeds past its refusal handling — so a
+ * cache-consulting dispatch that fails or is fenced out mid-decision (a
+ * journal failure on the provenance emit, a strict corruption verdict)
+ * records no decision, and its exit lands in {@link dispatches}. At most one
+ * decision is counted per cache-consulting dispatch.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const stepCacheDecisions: Metric.Counter<number>;
+/**
+ * `stepCacheDecisions` views keyed by decision.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const stepCacheDecision: {
+    readonly VerifiedHit: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Miss: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly UnverifiableEvidence: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Unmeasurable: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly StaleReadSet: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly ReplayFailed: Metric.Metric<number, Metric.CounterState<number>>;
+};
+/**
+ * Counter over the run driver's claim-and-activate decisions, dimensioned by
+ * `outcome`. These are the engine-level decisions taken BEFORE or AFTER the
+ * store-level compare-and-swaps `RunStoreMetrics` counts: a `terminal` or
+ * `heartbeat_fresh` refusal never reaches the store, `steal_refused_owner_alive`
+ * is the liveness probe declining, and `claim_lost`/`activation_lost` are the
+ * driver observing a lost store CAS.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const claims: Metric.Counter<number>;
+/**
+ * `claims` views keyed by driver decision.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const claim: {
+    readonly Activated: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly HeartbeatFresh: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly ClaimLost: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly Terminal: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly StealRefusedOwnerAlive: Metric.Metric<number, Metric.CounterState<number>>;
+    readonly ActivationLost: Metric.Metric<number, Metric.CounterState<number>>;
+};
+//# sourceMappingURL=EngineStoreMetrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EngineStoreMetrics.d.ts","sourceRoot":"","sources":["../../src/EngineStoreMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,IAAI,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAA;AAezD;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,OAC+C,CAAA;AAErG;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,OAAO,GAAI,aAAa;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IACnD,QAAQ,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,GAAG,IAAI,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,GAAE,CAAA;CACpG,MACA,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAS7D,CAAA;AAIH;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,wBAErB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,qCAE3B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ;;;;CAAsC,CAAA;AAE3D;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,wBAE9B,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,qCAEpC,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,wBAEzB,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;CAIhB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,wBAE5B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;CAA6C,CAAA;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,qCAEnC,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,wBAElC,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;CAAmD,CAAA;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,qCAElC,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,wBAEnC,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,wBAE9B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;CAI9B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB,wBAE7B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;CAI7B,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,wBAEjB,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;;;CAIjB,CAAA"}

package/dist/esm/EngineStoreMetrics.js

@@ -0,0 +1,260 @@
+/**
+ * Standard metric definitions for the engine-store hot paths.
+ *
+ * This module only defines the metric handles, following the shape of
+ * `RunStoreMetrics` and Effect's `ClusterMetrics`. The dispatch seam
+ * (`internal/ActionPersistence`), the plan scheduler, the workspace sandbox,
+ * and the run driver update them as outcomes are decided. No exporter ships in
+ * this package; provide one — for example `@smthrs/observability` — and
+ * these series appear in it.
+ *
+ * Counters over an effect's exit are keyed by {@link ExitTag} records, so an
+ * update is a lookup rather than a branch, and durations land in
+ * `Metric.timer` histograms through Effect's own `Effect.trackDuration`. The
+ * same exit observation annotates the operation span with its outcome; none of
+ * the instrumentation combinators alters the instrumented effect's result or
+ * cause.
+ *
+ * @since 0.1.0
+ */
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Metric from "effect/Metric";
+/** Rewrites an outcome tag (`HeartbeatFresh`) as an attribute value (`heartbeat_fresh`). */
+const attributeValue = (tag) => tag.replace(/(?<=[a-z0-9])(?=[A-Z])/g, "_").toLowerCase();
+/** Builds the tag-keyed record of attributed counter views for one operation. */
+const byOutcome = (metric, attributes, tags) => Object.fromEntries(tags.map((tag) => [tag, Metric.withAttributes(metric, { ...attributes, outcome: attributeValue(tag) })]));
+/**
+ * Classifies an exit for an {@link ExitTag}-keyed counter record.
+ *
+ * @category accessors
+ * @since 0.1.0
+ */
+export const exitTag = (exit) => exit._tag === "Success" ? "Success" : Cause.hasInterruptsOnly(exit.cause) ? "Interrupt" : "Failure";
+/**
+ * Observes an effect with a duration timer and an exit-outcome counter.
+ *
+ * Composes Effect's own `Effect.trackDuration` (monotonic clock, records on
+ * success, failure, and interruption alike) with an `Effect.onExit` counter
+ * update and current-span annotation, so the instrumented effect's exit —
+ * value, cause, and interruption — propagates byte-identically. This is the
+ * dual-instrument shape production Effect services use for hot-path
+ * operations.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const observe = (instruments) => (effect) => effect.pipe(Effect.trackDuration(instruments.timer), Effect.onExit((exit) => {
+    const tag = exitTag(exit);
+    return Effect.annotateCurrentSpan({ outcome: attributeValue(tag) }).pipe(Effect.andThen(Metric.update(instruments.counter[tag], 1)));
+}));
+const exitTags = ["Success", "Failure", "Interrupt"];
+/**
+ * Counter over durable action dispatches through
+ * `internal/ActionPersistence`, dimensioned by exit `outcome` (`success`,
+ * `failure`, or `interrupt`). A cache-served replay and a fresh execution
+ * both count: the dispatch is the unit the engine retries and fences.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const dispatches = Metric.counter("flows_engine_dispatches", {
+    description: "Durable action dispatches by exit outcome"
+});
+/**
+ * Latency histogram over durable action dispatches, from admission through
+ * settlement (cache verification, execution, copy-back, and the terminal
+ * row included).
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const dispatchDuration = Metric.timer("flows_engine_dispatch_duration", {
+    description: "Durable action dispatch duration"
+});
+/**
+ * `dispatches` views keyed by {@link ExitTag}.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const dispatch = byOutcome(dispatches, {}, exitTags);
+/**
+ * Counter over scheduler admission passes that launched work. The
+ * completion-driven scheduler re-computes the ready set after every terminal
+ * event; only a pass that admits at least one node counts, so the series
+ * reads as "how many times the scheduler opened dispatch permits", not as
+ * event-loop noise.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const schedulerAdmissions = Metric.counter("flows_engine_scheduler_admissions", {
+    description: "Plan scheduler admission passes that launched at least one dispatch"
+});
+/**
+ * Latency histogram over one scheduler dispatch, admission through terminal
+ * event: measurement, keying, the durable-action seam, and every rebase turn
+ * of the same node's loop land in a single observation.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const schedulerDispatchDuration = Metric.timer("flows_engine_scheduler_dispatch_duration", {
+    description: "Duration of one scheduler dispatch, admission through terminal event"
+});
+/**
+ * Counter over plan node settlements, dimensioned by the scheduler `outcome`
+ * (`built`, `clean`, `failed`, `skipped`, or `deferred`) — the per-node
+ * evaluation vocabulary `PlanScheduler` journals.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const schedulerNodes = Metric.counter("flows_engine_scheduler_nodes", {
+    description: "Plan node settlements by evaluation outcome"
+});
+/**
+ * `schedulerNodes` views keyed by `PlanScheduler.Outcome`.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const node = byOutcome(schedulerNodes, {}, ["built", "clean", "failed", "skipped", "deferred"]);
+/**
+ * Counter over isolated workspace executions (`WorkspaceSandbox.execute`),
+ * dimensioned by exit `outcome`. An `Invalidated` verdict is a `success`
+ * exit — the transaction ran and answered; the verdict itself is journaled.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const sandboxExecutions = Metric.counter("flows_engine_sandbox_executions", {
+    description: "Isolated workspace executions by exit outcome"
+});
+/**
+ * `sandboxExecutions` views keyed by {@link ExitTag}.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const sandboxExecution = byOutcome(sandboxExecutions, {}, exitTags);
+/**
+ * Latency histogram over isolated workspace executions.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const sandboxExecutionDuration = Metric.timer("flows_engine_sandbox_execution_duration", {
+    description: "Isolated workspace execution duration"
+});
+/**
+ * Counter over sandbox materializations (`WorkspaceSandbox.materialize` —
+ * the one host write), dimensioned by exit `outcome`.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const sandboxMaterializations = Metric.counter("flows_engine_sandbox_materializations", {
+    description: "Sandbox copy-back materializations by exit outcome"
+});
+/**
+ * `sandboxMaterializations` views keyed by {@link ExitTag}.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const materialization = byOutcome(sandboxMaterializations, {}, exitTags);
+/**
+ * Latency histogram over sandbox materializations.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const materializationDuration = Metric.timer("flows_engine_sandbox_materialization_duration", {
+    description: "Sandbox copy-back materialization duration"
+});
+/**
+ * Counter over copy-back compare-and-set refusals: the preflight found host
+ * state that moved after the transaction's base snapshot. The engine answers
+ * one with a rebase or a conflict strategy, so the rate is contention
+ * evidence, not an error rate.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const materializationConflicts = Metric.counter("flows_engine_sandbox_conflicts", {
+    description: "Sandbox copy-back compare-and-set refusals"
+});
+/**
+ * Counter over step-boundary settlements at the dispatch seam, dimensioned by
+ * `outcome`: `clean` evidence, an `expected`-mode `deviation`, or a hard
+ * `violation` (undeclared write, missing declared output, surviving declared
+ * removal), with `refused` for a host that could not settle at all.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const boundarySettlements = Metric.counter("flows_engine_boundary_settlements", {
+    description: "Step boundary settlements by outcome"
+});
+/**
+ * `boundarySettlements` views keyed by settlement classification.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const boundarySettlement = byOutcome(boundarySettlements, {}, ["Clean", "Deviation", "Violation", "Refused"]);
+/**
+ * Counter over the EFFECTIVE step-boundary cache decisions at the dispatch
+ * seam, dimensioned by `outcome`. `flows_step_cache_lookups` counts raw row
+ * presence at `CacheStore.get`; this series records what the dispatch
+ * actually did with the row after read-set verification and output
+ * materialization — `verified_hit` served the cached result, and every other
+ * outcome fell through to a real execution (`miss` no row,
+ * `unverifiable_evidence` a row whose recorded evidence cannot justify reuse,
+ * `unmeasurable` a host that could not re-measure the read set,
+ * `stale_read_set` a measured mismatch, `replay_failed` verified evidence the
+ * host could not re-materialize). Each decision is counted where it takes
+ * effect: `verified_hit` as the cached result is returned, a fall-through
+ * outcome as the dispatch proceeds past its refusal handling — so a
+ * cache-consulting dispatch that fails or is fenced out mid-decision (a
+ * journal failure on the provenance emit, a strict corruption verdict)
+ * records no decision, and its exit lands in {@link dispatches}. At most one
+ * decision is counted per cache-consulting dispatch.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const stepCacheDecisions = Metric.counter("flows_engine_step_cache_decisions", {
+    description: "Effective step-boundary cache decisions at the dispatch seam"
+});
+/**
+ * `stepCacheDecisions` views keyed by decision.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const stepCacheDecision = byOutcome(stepCacheDecisions, {}, ["VerifiedHit", "Miss", "UnverifiableEvidence", "Unmeasurable", "StaleReadSet", "ReplayFailed"]);
+/**
+ * Counter over the run driver's claim-and-activate decisions, dimensioned by
+ * `outcome`. These are the engine-level decisions taken BEFORE or AFTER the
+ * store-level compare-and-swaps `RunStoreMetrics` counts: a `terminal` or
+ * `heartbeat_fresh` refusal never reaches the store, `steal_refused_owner_alive`
+ * is the liveness probe declining, and `claim_lost`/`activation_lost` are the
+ * driver observing a lost store CAS.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const claims = Metric.counter("flows_engine_claims", {
+    description: "Run driver claim-and-activate decisions by outcome"
+});
+/**
+ * `claims` views keyed by driver decision.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const claim = byOutcome(claims, {}, ["Activated", "Terminal", "HeartbeatFresh", "StealRefusedOwnerAlive", "ClaimLost", "ActivationLost"]);
+//# sourceMappingURL=EngineStoreMetrics.js.map

package/dist/esm/EngineStoreMetrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EngineStoreMetrics.js","sourceRoot":"","sources":["../../src/EngineStoreMetrics.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Standard metric definitions for the engine-store hot paths.\n *\n * This module only defines the metric handles, following the shape of\n * `RunStoreMetrics` and Effect's `ClusterMetrics`. The dispatch seam\n * (`internal/ActionPersistence`), the plan scheduler, the workspace sandbox,\n * and the run driver update them as outcomes are decided. No exporter ships in\n * this package; provide one — for example `@smthrs/observability` — and\n * these series appear in it.\n *\n * Counters over an effect's exit are keyed by {@link ExitTag} records, so an\n * update is a lookup rather than a branch, and durations land in\n * `Metric.timer` histograms through Effect's own `Effect.trackDuration`. The\n * same exit observation annotates the operation span with its outcome; none of\n * the instrumentation combinators alters the instrumented effect's result or\n * cause.\n *\n * @since 0.1.0\n */\n\nimport * as Cause from \"effect/Cause\"\nimport type * as Duration from \"effect/Duration\"\nimport * as Effect from \"effect/Effect\"\nimport type * as Exit from \"effect/Exit\"\nimport * as Metric from \"effect/Metric\"\n\n/**\n * How an instrumented effect exited: `Success`, `Failure` (any non-interrupt\n * cause), or `Interrupt` (an interrupt-only cause — in this store that is the\n * fencing self-interruption as well as caller cancellation).\n *\n * @category models\n * @since 0.1.0\n */\nexport type ExitTag = \"Success\" | \"Failure\" | \"Interrupt\"\n\n/** Rewrites an outcome tag (`HeartbeatFresh`) as an attribute value (`heartbeat_fresh`). */\nconst attributeValue = (tag: string): string => tag.replace(/(?<=[a-z0-9])(?=[A-Z])/g, \"_\").toLowerCase()\n\n/** Builds the tag-keyed record of attributed counter views for one operation. */\nconst byOutcome = <const Tags extends ReadonlyArray<string>>(\n  metric: Metric.Metric<number, Metric.CounterState<number>>,\n  attributes: Readonly<Record<string, string>>,\n  tags: Tags\n): { readonly [Tag in Tags[number]]: Metric.Metric<number, Metric.CounterState<number>> } =>\n  Object.fromEntries(\n    tags.map((tag) => [tag, Metric.withAttributes(metric, { ...attributes, outcome: attributeValue(tag) })])\n  ) as { [Tag in Tags[number]]: Metric.Metric<number, Metric.CounterState<number>> }\n\n/**\n * Classifies an exit for an {@link ExitTag}-keyed counter record.\n *\n * @category accessors\n * @since 0.1.0\n */\nexport const exitTag = <A, E>(exit: Exit.Exit<A, E>): ExitTag =>\n  exit._tag === \"Success\" ? \"Success\" : Cause.hasInterruptsOnly(exit.cause) ? \"Interrupt\" : \"Failure\"\n\n/**\n * Observes an effect with a duration timer and an exit-outcome counter.\n *\n * Composes Effect's own `Effect.trackDuration` (monotonic clock, records on\n * success, failure, and interruption alike) with an `Effect.onExit` counter\n * update and current-span annotation, so the instrumented effect's exit —\n * value, cause, and interruption — propagates byte-identically. This is the\n * dual-instrument shape production Effect services use for hot-path\n * operations.\n *\n * @category combinators\n * @since 0.1.0\n */\nexport const observe = (instruments: {\n  readonly timer: Metric.Histogram<Duration.Duration>\n  readonly counter: { readonly [Tag in ExitTag]: Metric.Metric<number, Metric.CounterState<number>> }\n}) =>\n<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>\n  effect.pipe(\n    Effect.trackDuration(instruments.timer),\n    Effect.onExit((exit) => {\n      const tag = exitTag(exit)\n      return Effect.annotateCurrentSpan({ outcome: attributeValue(tag) }).pipe(\n        Effect.andThen(Metric.update(instruments.counter[tag], 1))\n      )\n    })\n  )\n\nconst exitTags = [\"Success\", \"Failure\", \"Interrupt\"] as const\n\n/**\n * Counter over durable action dispatches through\n * `internal/ActionPersistence`, dimensioned by exit `outcome` (`success`,\n * `failure`, or `interrupt`). A cache-served replay and a fresh execution\n * both count: the dispatch is the unit the engine retries and fences.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const dispatches = Metric.counter(\"flows_engine_dispatches\", {\n  description: \"Durable action dispatches by exit outcome\"\n})\n\n/**\n * Latency histogram over durable action dispatches, from admission through\n * settlement (cache verification, execution, copy-back, and the terminal\n * row included).\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const dispatchDuration = Metric.timer(\"flows_engine_dispatch_duration\", {\n  description: \"Durable action dispatch duration\"\n})\n\n/**\n * `dispatches` views keyed by {@link ExitTag}.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const dispatch = byOutcome(dispatches, {}, exitTags)\n\n/**\n * Counter over scheduler admission passes that launched work. The\n * completion-driven scheduler re-computes the ready set after every terminal\n * event; only a pass that admits at least one node counts, so the series\n * reads as \"how many times the scheduler opened dispatch permits\", not as\n * event-loop noise.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const schedulerAdmissions = Metric.counter(\"flows_engine_scheduler_admissions\", {\n  description: \"Plan scheduler admission passes that launched at least one dispatch\"\n})\n\n/**\n * Latency histogram over one scheduler dispatch, admission through terminal\n * event: measurement, keying, the durable-action seam, and every rebase turn\n * of the same node's loop land in a single observation.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const schedulerDispatchDuration = Metric.timer(\"flows_engine_scheduler_dispatch_duration\", {\n  description: \"Duration of one scheduler dispatch, admission through terminal event\"\n})\n\n/**\n * Counter over plan node settlements, dimensioned by the scheduler `outcome`\n * (`built`, `clean`, `failed`, `skipped`, or `deferred`) — the per-node\n * evaluation vocabulary `PlanScheduler` journals.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const schedulerNodes = Metric.counter(\"flows_engine_scheduler_nodes\", {\n  description: \"Plan node settlements by evaluation outcome\"\n})\n\n/**\n * `schedulerNodes` views keyed by `PlanScheduler.Outcome`.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const node = byOutcome(\n  schedulerNodes,\n  {},\n  [\"built\", \"clean\", \"failed\", \"skipped\", \"deferred\"] as const\n)\n\n/**\n * Counter over isolated workspace executions (`WorkspaceSandbox.execute`),\n * dimensioned by exit `outcome`. An `Invalidated` verdict is a `success`\n * exit — the transaction ran and answered; the verdict itself is journaled.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const sandboxExecutions = Metric.counter(\"flows_engine_sandbox_executions\", {\n  description: \"Isolated workspace executions by exit outcome\"\n})\n\n/**\n * `sandboxExecutions` views keyed by {@link ExitTag}.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const sandboxExecution = byOutcome(sandboxExecutions, {}, exitTags)\n\n/**\n * Latency histogram over isolated workspace executions.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const sandboxExecutionDuration = Metric.timer(\"flows_engine_sandbox_execution_duration\", {\n  description: \"Isolated workspace execution duration\"\n})\n\n/**\n * Counter over sandbox materializations (`WorkspaceSandbox.materialize` —\n * the one host write), dimensioned by exit `outcome`.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const sandboxMaterializations = Metric.counter(\"flows_engine_sandbox_materializations\", {\n  description: \"Sandbox copy-back materializations by exit outcome\"\n})\n\n/**\n * `sandboxMaterializations` views keyed by {@link ExitTag}.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const materialization = byOutcome(sandboxMaterializations, {}, exitTags)\n\n/**\n * Latency histogram over sandbox materializations.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const materializationDuration = Metric.timer(\"flows_engine_sandbox_materialization_duration\", {\n  description: \"Sandbox copy-back materialization duration\"\n})\n\n/**\n * Counter over copy-back compare-and-set refusals: the preflight found host\n * state that moved after the transaction's base snapshot. The engine answers\n * one with a rebase or a conflict strategy, so the rate is contention\n * evidence, not an error rate.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const materializationConflicts = Metric.counter(\"flows_engine_sandbox_conflicts\", {\n  description: \"Sandbox copy-back compare-and-set refusals\"\n})\n\n/**\n * Counter over step-boundary settlements at the dispatch seam, dimensioned by\n * `outcome`: `clean` evidence, an `expected`-mode `deviation`, or a hard\n * `violation` (undeclared write, missing declared output, surviving declared\n * removal), with `refused` for a host that could not settle at all.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const boundarySettlements = Metric.counter(\"flows_engine_boundary_settlements\", {\n  description: \"Step boundary settlements by outcome\"\n})\n\n/**\n * `boundarySettlements` views keyed by settlement classification.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const boundarySettlement = byOutcome(\n  boundarySettlements,\n  {},\n  [\"Clean\", \"Deviation\", \"Violation\", \"Refused\"] as const\n)\n\n/**\n * Counter over the EFFECTIVE step-boundary cache decisions at the dispatch\n * seam, dimensioned by `outcome`. `flows_step_cache_lookups` counts raw row\n * presence at `CacheStore.get`; this series records what the dispatch\n * actually did with the row after read-set verification and output\n * materialization — `verified_hit` served the cached result, and every other\n * outcome fell through to a real execution (`miss` no row,\n * `unverifiable_evidence` a row whose recorded evidence cannot justify reuse,\n * `unmeasurable` a host that could not re-measure the read set,\n * `stale_read_set` a measured mismatch, `replay_failed` verified evidence the\n * host could not re-materialize). Each decision is counted where it takes\n * effect: `verified_hit` as the cached result is returned, a fall-through\n * outcome as the dispatch proceeds past its refusal handling — so a\n * cache-consulting dispatch that fails or is fenced out mid-decision (a\n * journal failure on the provenance emit, a strict corruption verdict)\n * records no decision, and its exit lands in {@link dispatches}. At most one\n * decision is counted per cache-consulting dispatch.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const stepCacheDecisions = Metric.counter(\"flows_engine_step_cache_decisions\", {\n  description: \"Effective step-boundary cache decisions at the dispatch seam\"\n})\n\n/**\n * `stepCacheDecisions` views keyed by decision.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const stepCacheDecision = byOutcome(\n  stepCacheDecisions,\n  {},\n  [\"VerifiedHit\", \"Miss\", \"UnverifiableEvidence\", \"Unmeasurable\", \"StaleReadSet\", \"ReplayFailed\"] as const\n)\n\n/**\n * Counter over the run driver's claim-and-activate decisions, dimensioned by\n * `outcome`. These are the engine-level decisions taken BEFORE or AFTER the\n * store-level compare-and-swaps `RunStoreMetrics` counts: a `terminal` or\n * `heartbeat_fresh` refusal never reaches the store, `steal_refused_owner_alive`\n * is the liveness probe declining, and `claim_lost`/`activation_lost` are the\n * driver observing a lost store CAS.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const claims = Metric.counter(\"flows_engine_claims\", {\n  description: \"Run driver claim-and-activate decisions by outcome\"\n})\n\n/**\n * `claims` views keyed by driver decision.\n *\n * @category metrics\n * @since 0.1.0\n */\nexport const claim = byOutcome(\n  claims,\n  {},\n  [\"Activated\", \"Terminal\", \"HeartbeatFresh\", \"StealRefusedOwnerAlive\", \"ClaimLost\", \"ActivationLost\"] as const\n)\n"]}

package/dist/esm/Errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The public, stable error contract of `@smthrs/engine-store`.
+ *
+ * Every error here carries a `code` literal that is part of the public API:
+ * consumers may switch on `code` (or `_tag`) and the strings will not change
+ * without a major version. The classes themselves are declared next to the
+ * logic that raises them (`internal/ActionPersistence.ts`,
+ * `@smthrs/flow/Action`, and `@smthrs/flow/FlowRuntime`); this module is the
+ * barrel-exported surface so that `internal/` never has to be imported by
+ * consumers.
+ *
+ * Related documentation: `docs/troubleshooting.md` names every code and
+ * what to change; `docs/api.md` carries the schemas.
+ *
+ * @since 0.1.0
+ */
+export { IrreversibleRetryRequiresIdempotencyKey } from "@smthrs/flow/Action";
+export { FlowCycleDetected } from "@smthrs/flow/FlowRuntime";
+export { AttemptAdmissionRejected, AttemptEvidenceQuarantined, AttemptSuspended, CacheConflictDetected, CacheCorruptionDetected } from "./internal/ActionPersistence.ts";
+export { RetentionError, RetentionErrorCode } from "./internal/RetentionOps.ts";
+export { RunCatalogError, RunCatalogErrorCode } from "./internal/RunCatalogOps.ts";
+//# sourceMappingURL=Errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Errors.d.ts","sourceRoot":"","sources":["../../src/Errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,uCAAuC,EAAE,MAAM,qBAAqB,CAAA;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/E,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA"}

package/dist/esm/Errors.js

@@ -0,0 +1,22 @@
+/**
+ * The public, stable error contract of `@smthrs/engine-store`.
+ *
+ * Every error here carries a `code` literal that is part of the public API:
+ * consumers may switch on `code` (or `_tag`) and the strings will not change
+ * without a major version. The classes themselves are declared next to the
+ * logic that raises them (`internal/ActionPersistence.ts`,
+ * `@smthrs/flow/Action`, and `@smthrs/flow/FlowRuntime`); this module is the
+ * barrel-exported surface so that `internal/` never has to be imported by
+ * consumers.
+ *
+ * Related documentation: `docs/troubleshooting.md` names every code and
+ * what to change; `docs/api.md` carries the schemas.
+ *
+ * @since 0.1.0
+ */
+export { IrreversibleRetryRequiresIdempotencyKey } from "@smthrs/flow/Action";
+export { FlowCycleDetected } from "@smthrs/flow/FlowRuntime";
+export { AttemptAdmissionRejected, AttemptEvidenceQuarantined, AttemptSuspended, CacheConflictDetected, CacheCorruptionDetected } from "./internal/ActionPersistence.js";
+export { RetentionError, RetentionErrorCode } from "./internal/RetentionOps.js";
+export { RunCatalogError, RunCatalogErrorCode } from "./internal/RunCatalogOps.js";
+//# sourceMappingURL=Errors.js.map

package/dist/esm/Errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Errors.js","sourceRoot":"","sources":["../../src/Errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,uCAAuC,EAAE,MAAM,qBAAqB,CAAA;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/E,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA","sourcesContent":["/**\n * The public, stable error contract of `@smthrs/engine-store`.\n *\n * Every error here carries a `code` literal that is part of the public API:\n * consumers may switch on `code` (or `_tag`) and the strings will not change\n * without a major version. The classes themselves are declared next to the\n * logic that raises them (`internal/ActionPersistence.ts`,\n * `@smthrs/flow/Action`, and `@smthrs/flow/FlowRuntime`); this module is the\n * barrel-exported surface so that `internal/` never has to be imported by\n * consumers.\n *\n * Related documentation: `docs/troubleshooting.md` names every code and\n * what to change; `docs/api.md` carries the schemas.\n *\n * @since 0.1.0\n */\n\nexport { IrreversibleRetryRequiresIdempotencyKey } from \"@smthrs/flow/Action\"\nexport { FlowCycleDetected } from \"@smthrs/flow/FlowRuntime\"\nexport {\n  AttemptAdmissionRejected,\n  AttemptEvidenceQuarantined,\n  AttemptSuspended,\n  CacheConflictDetected,\n  CacheCorruptionDetected\n} from \"./internal/ActionPersistence.ts\"\nexport { RetentionError, RetentionErrorCode } from \"./internal/RetentionOps.ts\"\nexport { RunCatalogError, RunCatalogErrorCode } from \"./internal/RunCatalogOps.ts\"\n"]}

package/dist/esm/EventTypes.d.ts

@@ -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 declare const EventTypes: {
+    readonly runDecision: "flows.engine.run-decision";
+    readonly attemptStarted: "flows.engine.attempt-started";
+    readonly attemptFinished: "flows.engine.attempt-finished";
+    readonly snapshotIdentified: "flows.engine.snapshot-identified";
+    readonly planRecorded: "flows.engine.plan-recorded";
+    readonly subgraphAppended: "flows.engine.subgraph-appended";
+    readonly deferredCompleted: "flows.engine.deferred-completed";
+    readonly deferredConsumed: "flows.engine.deferred-consumed";
+    readonly clockScheduled: "flows.engine.clock-scheduled";
+    readonly clockCompleted: "flows.engine.clock-completed";
+    readonly childSpawnKind: "flows/engine-store/child-spawn";
+};
+//# sourceMappingURL=EventTypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EventTypes.d.ts","sourceRoot":"","sources":["../../src/EventTypes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;CAYb,CAAA"}