@voltro/runtime 0.56.0 → 0.58.0

package/dist/index.d.ts

@@ -2971,6 +2971,12 @@ export declare const DEFAULT_MAX_IDLE_INTERVAL_MS = 30000;
  *  small enough to stop a pathological body being buffered into memory. */
 export declare const DEFAULT_MAX_RPC_BODY_BYTES: number;
 
+/** The watchdog bound a schedule gets when it declares none. Exported
+ *  because the overlap guard dates an un-beating run against it — see
+ *  `peerRunIsAlive`; a second copy of the number there would be a second
+ *  definition nothing keeps in step. */
+export declare const DEFAULT_MAX_RUNTIME_MS: number;
+
 /** See {@link DrainDeps.claimLeaseMs}. */
 export declare const DEFAULT_OUTBOX_CLAIM_LEASE_MS: number;
 
@@ -3002,6 +3008,25 @@ export declare const DEFAULT_RESUME_WINDOW_MS = 60000;
  */
 export declare const DEFAULT_ROW_FILTER_RETRY: Schedule.Schedule<unknown, unknown>;
 
+/**
+ * How often a run in flight bumps `heartbeatAt`.
+ *
+ * The default lives HERE, next to the only code that reads it, and
+ * `cli/src/schedulingConfig.ts` imports it as the default of the
+ * `scheduling.scheduleHeartbeatMs` field. One definition — a second one in the
+ * resolver is how a config default and a library default come to disagree
+ * about a number neither of them prints.
+ *
+ * 30 s rather than the couple of seconds `_voltro_replace_in_progress` beats
+ * at, because the two are bounding different things. A bulk load's beat decides
+ * whether a boot may DROP staging tables, so its cost is worth paying to keep
+ * the window tight. This one decides how long a dead run holds its schedule
+ * shut, measured against a cron period — a minute and a half of latency on a
+ * half-hourly job is one slot, and a run shorter than one interval writes no
+ * beat at all and costs nothing.
+ */
+export declare const DEFAULT_SCHEDULE_HEARTBEAT_MS = 30000;
+
 /** Defaults, overridable via `app.config.ts` `reactive.socket.*` (+ env) —
  *  resolved by the boot paths' tunables resolver. */
 export declare const DEFAULT_SOCKET_MAX_BUFFERED_BYTES = 1048576;
@@ -4616,6 +4641,28 @@ export declare interface FleetMergeResult<T> {
         readonly replicaId: string;
         readonly ageMs: number;
     }>;
+    /**
+     * Rows left behind by replicas the roster no longer lists.
+     *
+     * Reported rather than deleted, and separately from `stale`, because the two
+     * are different facts with different next steps: a stale row belongs to a
+     * process that is RUNNING and has stopped refreshing — a fault — while a
+     * departed one belongs to a process that is gone, which is what a scale-down
+     * looks like and needs no action.
+     *
+     * Conflating them cost both readings. Every corpse landed in `stale`, so
+     * `complete` could never be true again after the first scale-down; and they
+     * were counted as responders, so a row from the release before last reported
+     * a version SPLIT across a fleet that had none.
+     *
+     * Empty when no membership is wired: with no roster there is no evidence of
+     * departure, and assuming it would empty a single-process answer.
+     */
+    readonly departed: ReadonlyArray<{
+        readonly replicaId: string;
+        readonly ageMs: number;
+        readonly version: string | undefined;
+    }>;
     /** Framework versions among the responders, counted. Present only when they
      *  DIFFER — a single-version fleet needs no such note, and a note nobody
      *  needs is one everybody learns to skip. */
@@ -6456,6 +6503,15 @@ export declare const noteRead: (descriptor: QueryDescriptor) => void;
  */
 export declare const noteResumeVerdict: (rawLabel: string, verdict: true | ResumeExclusion) => void;
 
+/**
+ * Note that a row filter was resolved on `arm`, and say so the FIRST time.
+ *
+ * Exported so the arms that are not in this module (the serve pipeline) report
+ * through the same counter — four arms reporting four ways is how a reader comes
+ * to believe three of them are covered.
+ */
+export declare const noteRowFilterResolved: (arm: string, tables: number | undefined) => void;
+
 export declare interface Notification {
     readonly subscriberId: string;
     readonly fingerprint: string;
@@ -6793,6 +6849,42 @@ export declare const payloadPropertyNames: (schema: Schema.Schema.Any) => {
     readonly optional: ReadonlyArray<string>;
 };
 
+/**
+ * Is a `running` row on ANOTHER replica a live run, or a corpse?
+ *
+ * Pure, and separated from the query for the same reason
+ * `stagingLeftovers` is: the rule is four lines and each of them has a way to
+ * be quietly wrong in a direction nobody sees. Wrong towards "alive" and a
+ * schedule stops firing with `overlap skip` in the log; wrong towards "dead"
+ * and two replicas run the same occurrence.
+ *
+ * ── The two cases, and why there are two ───────────────────────────────────
+ *
+ * **A beat is present.** Then the answer is the beat and nothing else: a live
+ * handler bumps it every `heartbeatMs`, so silence longer than `STALE_BEATS`
+ * of them is a process that is not coming back.
+ *
+ * **No beat.** A row written before this column existed — i.e. by a process
+ * still running the previous version during a rolling deploy. `firedAt` is all
+ * there is, and the honest bound on it is the schedule's OWN `maxRuntimeMs`:
+ * the watchdog records a run that exceeds it as `failed`, so a row older than
+ * that plus the stale window cannot belong to a process that is still going to
+ * write a terminal status.
+ *
+ * **Neither is a usable instant** → NOT alive. Fail-open, deliberately, and it
+ * is the pre-existing reading (`firedAt != null &&`). A row nobody can date
+ * must not hold a schedule shut forever, and the counterweight is the claim
+ * coordinator, which is what actually guarantees once-only for a clock firing —
+ * this guard is the second line, not the first.
+ */
+export declare const peerRunIsAlive: (row: {
+    readonly firedAt: Date | string | null;
+    readonly heartbeatAt?: Date | string | null;
+}, now: number, bounds: {
+    readonly heartbeatMs: number;
+    readonly maxRuntimeMs: number;
+}) => boolean;
+
 /**
  * The calling subject's approval work: intents they may DECIDE, plus intents
  * they REQUESTED that are still live.
@@ -7939,12 +8031,21 @@ export declare const resetEventMetricTagCacheForTests: () => void;
 /** Drop everything recorded. For tests; not called by the runtime. */
 export declare const resetObservedGraph: () => void;
 
+/** Test seam — a process only ever warns once, which would make the second
+ *  assertion in a suite vacuous. */
+export declare const resetReplicaObservationWarnings: () => void;
+
 /** Clear the census. For tests; a running app has no reason to forget. */
 export declare const resetResumeCensus: () => void;
 
 /** Test seam. */
 export declare const resetResumeRingsForTest: () => void;
 
+/** Test helper: forget which arms have reported. Not for production — the set
+ *  is a record of what this PROCESS has proven, and forgetting it would make
+ *  the line repeat and the list lie. */
+export declare const resetRowFilterResolvedArms: () => void;
+
 /** Reset to the env default (tests). */
 export declare const resetSecretsBackend: () => void;
 
@@ -8089,6 +8190,25 @@ export declare interface ResolvedWorkflowCallerContext extends WorkflowCallerCon
     readonly subject: unknown;
     /** Never absent — the caller's trace id, or `'workflow-bootstrap'`. */
     readonly traceId: string;
+    /**
+     * Never absent — the row-filter scope this run's steps read through,
+     * resolved for the subject above at EXECUTION time.
+     *
+     * It is here for the same reason `resolveAuthority` exists, and the wording
+     * carries over: authority re-read from the app's live source is what a
+     * three-day-old run may DO, and this is what it may SEE. Restoring either
+     * from the start-context row would be a frozen fact made durable.
+     *
+     * It is also what makes such a run possible at all. The store refuses a
+     * scope-less context whose subject is not the system, so a workflow started
+     * BY A USER — the common case — threw before its executor ran in any app that
+     * calls `setRowFilter`. A bootstrap run passed, because its subject IS the
+     * system, which is why the gap was invisible from the framework's own tests.
+     *
+     * `NO_ROW_FILTER` when the app registered none: the resolution short-circuits
+     * without touching a store, so a filter-less app pays nothing.
+     */
+    readonly rowFilter: RowFilterScope;
 }
 
 export declare const resolveKeepAlive: (config: KeepAliveConfig | null | undefined) => KeepAliveTimeouts;
@@ -8131,31 +8251,6 @@ export declare const resolveRequestIsHttps: (input: {
  *  current table (or at least every row in the rescan groups). */
 export declare const resolveRescan: (shape: AggregateShape, state: IvmState, rescanGroups: ReadonlyArray<string>, baseRows: ReadonlyArray<Row_3>) => IvmState;
 
-/**
- * Resolve the request-scoped filter for `subject`.
- *
- * Three stages, in order, and the order is the design:
- *
- * 1. **Bypass** — no registered filter, or a `system` subject: `NO_ROW_FILTER`,
- *    zero cost, no `load` call.
- * 2. **Retry** — `load` runs under the filter's `retry` schedule
- *    (`DEFAULT_ROW_FILTER_RETRY` unless overridden). A transient failure must
- *    never reach stage 3, because at stage 3 it is indistinguishable from an
- *    authorization answer.
- * 3. **Refuse** — a failure that survived retry is reported through `onError`
- *    and then, per `onLoadError`, either FAILS with `RowFilterUnavailable`
- *    (default) or degrades to `DENY_ALL`.
- *
- * Fails CLOSED, never open: a `load` failure never yields an unfiltered read.
- * A row filter that degrades to "no filter" under load failure is worse than
- * none, because the system keeps serving and nothing looks wrong.
- *
- * And refusal is an ERROR by default, not an empty result. An empty result for
- * an infrastructure failure is the most misleading outcome available: it is
- * byte-identical to legitimate emptiness, so the user reads "you have no
- * tickets" and the operator reads a healthy 200. Every constrained page IS
- * broken when this happens; the honest thing is to say so.
- */
 export declare const resolveRowFilterScope: (subject: Subject, onError?: (error: unknown) => void) => Effect.Effect<RowFilterScope, RowFilterUnavailable>;
 
 /**
@@ -8614,6 +8709,10 @@ export declare const rowFilterMayNarrow: (tables: ReadonlyArray<string>) => bool
  */
 export declare const rowFilterRegistered: () => boolean;
 
+/** Which arms have been proven to resolve the filter in this process. Read by
+ *  the inspect surface; a test reads it to assert an arm was exercised. */
+export declare const rowFilterResolvedArms: () => ReadonlyArray<string>;
+
 /** What a scoped store needs: a sync `table → Predicate?` lookup. */
 export declare type RowFilterScope = (table: string) => Predicate | undefined;
 
@@ -9194,6 +9293,16 @@ export declare interface SchedulerDeps {
     /** Stable id of this process/replica (pod name, pid, …) recorded on
      *  every run row for debugging "which instance fired this." */
     readonly replicaId: string;
+    /**
+     * How often a run in flight bumps `heartbeatAt` — the signal the
+     * cross-instance overlap guard reads to tell a live run from a corpse.
+     *
+     * Omitted → {@link DEFAULT_SCHEDULE_HEARTBEAT_MS}. Both boot paths pass the
+     * resolved `scheduling.scheduleHeartbeatMs`, so a deployment changes it in
+     * one place; a non-positive value falls back to the default rather than
+     * turning the beat into a spin.
+     */
+    readonly runHeartbeatMs?: number;
     readonly log: SchedulerLogger;
     /** Notify on every run-row insert/update so the SSE bridge can
      *  mirror schedule runs to the cloud dashboard in real time. */
@@ -11720,13 +11829,6 @@ export declare const wrapStoreWithBootCodec: (underlying: DataStore, dialectId:
 
 export declare const wrapStoreWithMixinBehaviour: (rawUnderlying: DataStore, ctx: StoreMiddlewareContext) => FluentStore;
 
-/**
- * Write (upsert) this replica's counters for one kind.
- *
- * Best-effort throughout: a diagnostic that can fail a request, or a boot, is a
- * new way to be down. A failure logs at debug and leaves the previous row —
- * which then reads as stale, which is the truth.
- */
 export declare const writeReplicaObservation: (store: DataStore, kind: ReplicaObservationKind, payload: unknown) => Promise<void>;
 
 export { }