@voltro/runtime 0.31.0 → 0.33.0

package/dist/index.d.ts

@@ -1602,6 +1602,36 @@ declare const CircuitOpen_base: Schema.TaggedErrorClass<CircuitOpen, "CircuitOpe
 
 export declare type CircuitState = 'closed' | 'open' | 'half-open';
 
+/** How many bucket widths of predecessors a won claim leaves behind. */
+export declare const CLAIM_RETENTION_BUCKETS = 64;
+
+/**
+ * How long a claim row outlives its own bucket before the next winner deletes
+ * it — and the reasoning is the whole safety argument, so read it before
+ * shrinking the number.
+ *
+ * A claim answers ONE question ("has this bucket been taken"), and it is only
+ * ever asked while some replica still has a timer pending for that bucket.
+ * Delete it too early and a straggler re-claims a bucket that already fired,
+ * which is a DOUBLE FIRE — the failure this table exists to prevent. So the
+ * grace has to cover the longest a replica can plausibly be late.
+ *
+ * The two callers are late in different ways, which is why the width is a
+ * parameter rather than a constant:
+ *
+ *   - `scheduleCoordinated` computes its bucket from `Date.now()` AT TICK TIME.
+ *     A tick stalled by ten minutes therefore claims the CURRENT bucket, never
+ *     the one it was armed for — a stale bucket is unreachable by construction,
+ *     and 64 widths is generous past the point of paranoia.
+ *   - a CRON firing carries its own scheduled instant, so a stalled firing DOES
+ *     re-present an old bucket. It passes no width, so it gets 64 × 60 s ≈ 68
+ *     minutes of grace, and a cron fires at most once a minute, so that costs
+ *     ~68 rows.
+ *
+ * The floor keeps a sub-second task from computing a grace measured in seconds.
+ */
+export declare const claimGraceMs: (bucketWidthMs: number | undefined) => number;
+
 /**
  * Decide whether a candidate matches a maintainable shape. Conservative by
  * design — anything not provably maintainable is rejected (→ full recompute),
@@ -1852,6 +1882,8 @@ export declare interface ConnectionTokens {
     readonly scopes: ReadonlyArray<string>;
 }
 
+export declare type CoordinatedEffect = () => void | CoordinatedTickOutcome | Promise<void | CoordinatedTickOutcome>;
+
 export declare interface CoordinatedScheduleDeps {
     /** The exactly-once gate. `singleCoordinator` for one-process
      *  deployments; `makeAdvisoryLockCoordinator(store, replicaId)` for
@@ -1861,6 +1893,31 @@ export declare interface CoordinatedScheduleDeps {
     readonly log?: SchedulerLogger;
     /** Stable id of this replica — recorded on the claim row it wins. */
     readonly replicaId: string;
+    /**
+     * Ceiling for the idle backoff. Defaults to `VOLTRO_POLL_CEILING_MS` (see
+     * {@link readPollCeilingMs}), else {@link DEFAULT_MAX_IDLE_INTERVAL_MS}.
+     * Set it EQUAL to the base interval to
+     * opt a task out of backing off entirely — which is the right call only for a
+     * task whose work cannot announce itself.
+     */
+    readonly maxIdleIntervalMs?: number;
+    /**
+     * **Stop ticking entirely** on an idle tick with no known deadline, and come
+     * back only on `wake()`. Default `false`.
+     *
+     * This is the difference between "a poller that got cheaper" and "no poller".
+     * A deployment that never uses the queue this task drains pays ONE tick at
+     * boot — which is not optional, it is what finds work a previous process left
+     * behind — and then nothing at all.
+     *
+     * **Only pass `true` when an arrival is GUARANTEED to produce a `wake()`.**
+     * That is a claim about the deployment, not about the task: with Postgres
+     * LISTEN/NOTIFY or a broadcast transport every replica sees every enqueue, so
+     * it holds. Without either, a REMOTE replica's enqueue produces no local
+     * event, and a disarmed task would sleep through it forever. The backoff
+     * ceiling exists for exactly that case and is the correct choice there.
+     */
+    readonly disarmWhenIdle?: boolean;
 }
 
 export declare interface CoordinatedScheduleHandle {
@@ -1868,6 +1925,52 @@ export declare interface CoordinatedScheduleHandle {
     readonly stop: () => void;
     /** The task name (for logging / dedup diagnostics). */
     readonly name: string;
+    /**
+     * Run a tick now, because something arrived.
+     *
+     * Coalesced to at most one extra tick per BASE interval: a queue drain writes
+     * to the very table whose change events trigger this, so an uncoalesced wake
+     * is a loop that feeds itself. Safe to call from a change handler, from any
+     * replica, at any rate.
+     */
+    readonly wake: () => void;
+    /** The delay the next tick is currently armed for. Exposed for tests and the
+     *  inspect surface — a task sitting at the idle ceiling and one hammering the
+     *  base interval look identical from outside otherwise. */
+    readonly currentIntervalMs: () => number;
+    /** `false` once the task has stopped ticking and is waiting for `wake()`
+     *  (see `disarmWhenIdle`). A disarmed task and a stopped one are the same
+     *  thing from outside otherwise, and only one of them comes back. */
+    readonly isArmed: () => boolean;
+}
+
+/** Per-task overrides a caller may pass alongside the effect. */
+export declare interface CoordinatedTaskOptions {
+    /** See {@link CoordinatedScheduleDeps.disarmWhenIdle}. Per TASK rather than
+     *  per process, because whether an arrival wakes you is a property of the
+     *  queue you drain — one plugin may have a change channel on its table and
+     *  another none. */
+    readonly disarmWhenIdle?: boolean;
+}
+
+/** What a tick learned. Returning nothing means "assume there was work" —
+ *  the conservative reading, so a task that does not report cannot be backed
+ *  off into missing something. */
+export declare interface CoordinatedTickOutcome {
+    /** `true` when the tick found nothing to do. Only an idle tick backs off. */
+    readonly idle: boolean;
+    /**
+     * Milliseconds until the earliest thing this task already knows is coming —
+     * a debounce window closing, a lease expiring. Caps the backoff, so a task
+     * that is idle RIGHT NOW but has a deadline in 400 ms is armed for 400 ms
+     * rather than for 30 s.
+     *
+     * This is the part a fixed interval cannot express and the part that makes
+     * the backoff safe: without it, backing off is a bet that nothing time-based
+     * is pending, and deferring controls are exactly the case where that bet is
+     * wrong.
+     */
+    readonly nextDueInMs?: number;
 }
 
 export declare type CoordinationOutcome = 'single' | 'wonLock' | 'lostLock' | 'external' | 'cluster';
@@ -1880,7 +1983,15 @@ export declare type CoordinationOutcome = 'single' | 'wonLock' | 'lostLock' | 'e
  */
 export declare interface Coordinator {
     readonly kind: 'single' | 'advisoryLock' | 'cluster';
-    tryClaim(scheduleName: string, scheduledAt: Date): Promise<boolean>;
+    /**
+     * @param bucketWidthMs How far apart two consecutive buckets of THIS caller
+     *   are. Optional, and it is not used to decide the claim — it sizes how long
+     *   a won claim keeps its own predecessors around (see `claimGraceMs`). A cron
+     *   omits it and gets the conservative default; `scheduleCoordinated` passes
+     *   its interval, which is how a 250 ms task stops leaving a day of rows
+     *   behind.
+     */
+    tryClaim(scheduleName: string, scheduledAt: Date, bucketWidthMs?: number): Promise<boolean>;
 }
 
 /**
@@ -2300,6 +2411,14 @@ export declare const dataStoreKvStore: (store: DataStore) => KvStoreShape;
  *  cipher is registered (a genuine ciphertext with a wrong key throws GCM). */
 export declare const decryptField: (value: string) => string;
 
+/** Assumed distance between buckets when a caller passes none — the cron
+ *  engine's finest useful cadence. */
+export declare const DEFAULT_CLAIM_BUCKET_MS = 60000;
+
+/** Ceiling the idle backoff climbs to. Deliberately short enough to be a
+ *  FLOOR under a missed wake rather than a substitute for one. */
+export declare const DEFAULT_MAX_IDLE_INTERVAL_MS = 30000;
+
 /** Default `POST /rpc` body cap: 8 MiB. Generous for any JSON rpc envelope,
  *  small enough to stop a pathological body being buffered into memory. */
 export declare const DEFAULT_MAX_RPC_BODY_BYTES: number;
@@ -4516,9 +4635,21 @@ export declare const makeActionRunner: (deps: ActionRunnerDeps) => (action: Muta
  * session-level `pg_advisory_lock` (which is tied to a connection
  * that a pool may hand to another query before we unlock).
  *
- * The minute-bucket keying makes claims self-expiring: a crashed
- * winner doesn't block the next firing (= next minute = new key). Old
- * claim rows are pruned lazily (see `pruneClaimsOlderThan`).
+ * The bucket keying makes claims self-expiring as a DECISION: a crashed
+ * winner doesn't block the next firing (= next bucket = new key). It did
+ * not make them self-expiring as ROWS, and that distinction cost a consumer
+ * their whole deployment — 86 214 rows / 33 MB over two days, read in full
+ * on every claim check, ten of a fifteen-slot pooler pinned on the scan, an
+ * SSR render behind them at 300 490 ms, and a `rollout restart` that could
+ * not complete because the surge pod could not get a connection.
+ *
+ * **A won claim now deletes its own predecessors** (`claimGraceMs` above),
+ * which is what bounds the table rather than merely slowing its growth. The
+ * retention sweep both boot paths register (`wireRetentionSweep`,
+ * `VOLTRO_SCHEDULE_CLAIMS_TTL_HOURS`) STAYS as the backstop, and it is not
+ * redundant: this prune is per SCHEDULE NAME and only runs when that name wins
+ * again, so the rows of a schedule that was renamed or deleted have nothing
+ * left to clean them up.
  *
  * `scheduledAt` is the DETERMINISTIC cron instant (not `Date.now()`),
  * so every replica computes the SAME bucket regardless of clock skew
@@ -4616,7 +4747,7 @@ export declare const makeConnectionsFacade: (deps: ConnectionsFacadeDeps) => Con
  * handle is tracked by the caller (the CLI) so `onDeactivate` can stop
  * every task a plugin armed.
  */
-export declare const makeCoordinatedScheduler: (deps: CoordinatedScheduleDeps) => ((name: string, intervalMs: number, effect: () => void | Promise<void>) => CoordinatedScheduleHandle);
+export declare const makeCoordinatedScheduler: (deps: CoordinatedScheduleDeps) => PluginScheduleCoordinated;
 
 /**
  * Build a request-scoped loader. One instance per AppContext — see the module
@@ -5121,6 +5252,18 @@ export declare interface MutationStore extends DataStore {
     hardDelete(table: string, primaryKey: string): Promise<boolean>;
 }
 
+/**
+ * The backoff curve, extracted so it can be asserted directly — a schedule
+ * that backs off wrongly is otherwise only visible as a latency an integration
+ * test does not measure.
+ *
+ * Doubling rather than jumping to the ceiling: a queue that just went quiet is
+ * the likeliest one to receive something next, and doubling keeps the first few
+ * idle ticks cheap in latency while still reaching the ceiling in five steps
+ * from 1 s.
+ */
+export declare const nextDelay: (outcome: void | CoordinatedTickOutcome, baseMs: number, currentMs: number, maxIdleMs: number, disarmWhenIdle?: boolean) => number | "disarm";
+
 /** Next firing strictly after `after` (default: now). */
 export declare const nextFiring: (def: ScheduleDefinition, after?: Date) => Date;
 
@@ -5356,6 +5499,18 @@ export declare interface OrchestratorTickDeps {
     readonly log?: WakeOrchestratorLogger;
 }
 
+/**
+ * Map an `import('@effect/opentelemetry')` rejection to what the reader needs.
+ *
+ * Exported so the branch is testable without uninstalling the package. Only a
+ * module-NOT-FOUND becomes the install instruction: anything else is a real
+ * load failure inside a package that IS present, and renaming that to "not
+ * installed" sends the reader to reinstall something already there. A catch-all
+ * that relabels every failure is how a diagnosis gets buried — the same reason
+ * the serve bundle marks its deliberate refusals instead of swallowing throws.
+ */
+export declare const otelImportFailure: (cause: unknown) => Error;
+
 /**
  * Retention, part 1 of 2 — the PER-ENTRY cap.
  *
@@ -5544,8 +5699,8 @@ export declare interface PluginRefStore {
     delete: (table: string, id: string) => Promise<unknown>;
 }
 
-/** The 3-arg signature a plugin sees on its bind-ctx. */
-export declare type PluginScheduleCoordinated = (name: string, intervalMs: number, effect: () => void | Promise<void>) => CoordinatedScheduleHandle;
+/** The signature a plugin sees on its bind-ctx. */
+export declare type PluginScheduleCoordinated = (name: string, intervalMs: number, effect: CoordinatedEffect, options?: CoordinatedTaskOptions) => CoordinatedScheduleHandle;
 
 export declare const powerOfTwoSelector: (options?: P2COptions) => ReplicaSelector;
 
@@ -5879,6 +6034,29 @@ export declare type ReactiveReturn<D extends ExecutorDescriptor> = D extends {
     readonly descriptor: QueryDescriptor;
 } : never;
 
+/**
+ * The ceiling, tunable per deployment via `VOLTRO_POLL_CEILING_MS`.
+ *
+ * This is the ONE number worth exposing, and the reason is what the ceiling
+ * means: it is how long an arrival can wait when nothing woke the task. With
+ * reactivity it is never reached. WITHOUT it — a dialect with no CDC and no
+ * broadcast transport, where a remote replica's enqueue produces no local
+ * event — it is the whole latency budget, and only the operator knows how much
+ * of one they have.
+ *
+ * An env var rather than an `app.config.ts` field on purpose: it is an
+ * operational number, it must be identical under `voltro dev` and `voltro
+ * serve`, and a second source for one value is how the two boot paths come to
+ * disagree. Read here, once, so neither path can supply its own.
+ *
+ * An unparseable or non-positive value is ignored rather than honoured — a
+ * ceiling of 0 would turn every idle task into a spin, which is the exact
+ * pathology the backoff exists to remove.
+ */
+export declare const readPollCeilingMs: (env?: {
+    readonly VOLTRO_POLL_CEILING_MS?: string;
+}) => number;
+
 /** `admin:full` (mirrors `@voltro/protocol`'s ADMIN_SCOPE) bypasses ReBAC. */
 export declare const REBAC_ADMIN_SCOPE = "admin:full";
 
@@ -7080,29 +7258,27 @@ export declare interface ScheduleContext {
 }
 
 /**
- * Run `effect` every `intervalMs`, but on only ONE replica per tick.
+ * Run `effect` on only ONE replica per tick, on a cadence that follows the
+ * work rather than a fixed clock.
  *
- * On each tick the runner floors the wall clock to an `intervalMs`
- * bucket and asks the coordinator to claim `(name, bucket)`. Only the
- * replica that wins the claim runs the effect; the rest skip that tick.
- * Because the bucket is derived from the shared wall clock (not each
- * replica's tick offset), every replica computes the same bucket within
- * the window and races on the identical claim key — the INSERT-wins
- * arbiter picks one.
+ * Each tick floors the wall clock to an `intervalMs` bucket and asks the
+ * coordinator to claim `(name, bucket)`. Only the replica that wins runs the
+ * effect; the rest skip. Because the bucket comes from the shared wall clock
+ * (not each replica's tick offset), every replica computes the same bucket
+ * within the window and races on the identical claim key.
  *
- * Non-dying: a throw inside `effect` is caught + logged; the next tick is
- * always re-armed. The timer is `unref`'d so it never keeps the process
- * alive on its own (mirrors the bare-`setInterval` behaviour it replaces).
+ * Non-dying: a throw inside `effect` is caught + logged and the next tick is
+ * always re-armed. The timer is `unref`'d so it never keeps the process alive.
  *
  * @param name        Stable task name, namespaced by the caller (a plugin
  *                    passes e.g. `presence.sweep`). Used as the claim key
  *                    prefix + in logs.
- * @param intervalMs  Period between ticks. Also the claim bucket width —
- *                    a crashed winner doesn't block the next tick (= next
- *                    bucket = new claim key).
- * @param effect      The work to run when this replica wins the tick.
+ * @param intervalMs  The BASE period — the fastest this task ticks, the claim
+ *                    bucket width, and the wake coalescing window.
+ * @param effect      The work. Return a {@link CoordinatedTickOutcome} to let
+ *                    the runner back off when there is nothing to do.
  */
-export declare const scheduleCoordinated: (name: string, intervalMs: number, effect: () => void | Promise<void>, deps: CoordinatedScheduleDeps) => CoordinatedScheduleHandle;
+export declare const scheduleCoordinated: (name: string, intervalMs: number, effect: CoordinatedEffect, deps: CoordinatedScheduleDeps) => CoordinatedScheduleHandle;
 
 export declare interface ScheduleDefinition {
     readonly name: string;