@voltro/runtime 0.55.0 → 0.56.0

package/dist/index.d.ts

@@ -78,6 +78,7 @@ import { Sampler } from '@opentelemetry/sdk-trace-base';
 import { Schedule } from 'effect';
 import { Schema } from 'effect';
 import { ScopeError } from '@voltro/protocol';
+import { Server } from 'node:http';
 import { ServerOnlyColumnWrite } from '@voltro/protocol';
 import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { spawn } from 'node:child_process';
@@ -1171,6 +1172,9 @@ export declare const applyInverse: (store: UndoApplyStore, op: InverseOp) => Pro
  *  `synthesizeInverse`), as the caller's transaction wraps them. */
 export declare const applyInverses: (store: UndoApplyStore, ops: ReadonlyArray<InverseOp>) => Promise<void>;
 
+/** Apply the timeouts to a node HTTP server. */
+export declare const applyKeepAlive: (server: Server, t: KeepAliveTimeouts) => void;
+
 /**
  * Apply every rule matching `change`.
  *
@@ -2947,6 +2951,18 @@ export declare const DEFAULT_DELIVERY_CONCURRENCY = 8;
  *  framework default. */
 export declare const DEFAULT_HSTS = "max-age=15552000; includeSubDomains";
 
+/**
+ * 72 seconds.
+ *
+ * The bound that matters is the PROXY's idle timeout, and the defaults cluster
+ * at 60s (ALB, Envoy) and 75s (nginx). 72s clears the 60s group with margin and
+ * sits just under nginx's — a deployment on nginx should raise this, and the
+ * doc says so. Picking 76s instead would leave every ALB user holding a
+ * connection the load balancer has already dropped, which is the same defect
+ * mirrored; the 60s group is the larger one.
+ */
+export declare const DEFAULT_KEEP_ALIVE_MS = 72000;
+
 /** 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;
@@ -2955,6 +2971,9 @@ 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;
 
+/** See {@link DrainDeps.claimLeaseMs}. */
+export declare const DEFAULT_OUTBOX_CLAIM_LEASE_MS: number;
+
 /**
  * How many raw-SQL reads one request records for the undeclared-`dependsOn`
  * diagnostic. A bound rather than none: the recording lives for as long as the
@@ -2991,6 +3010,15 @@ export declare const DEFAULT_SOCKET_OVERRUN_AFTER_MS = 10000;
 
 export declare const DEFAULT_SOCKET_OVERSIZED_EVENT_BYTES = 262144;
 
+/**
+ * How old a row may be before a reader should stop trusting it as current.
+ *
+ * Tunable rather than a constant because the write cadence is: a fleet that
+ * writes every 30s and one that writes every 5m disagree about what "stale"
+ * means, and a single number would be wrong for one of them.
+ */
+export declare const DEFAULT_STALE_AFTER_MS = 120000;
+
 /**
  * The message of an UNDECLARED throw, bounded, with nothing else attached.
  *
@@ -3436,13 +3464,39 @@ export declare interface DispatcherDependencies {
 export declare const DORMANCY_WAKEUP_TENANT = "default";
 
 export declare interface DrainDeps {
-    readonly store: Pick<DataStore, 'query' | 'update' | 'insert' | 'delete'>;
+    readonly store: Pick<DataStore, 'query' | 'update' | 'updateMany' | 'insert' | 'delete'>;
     readonly handlers: ReadonlyMap<string, OutboxHandlerDefinition>;
     readonly now?: () => Date;
     /** Max rows per drain pass. */
     readonly batchSize?: number;
     /** Per-entry cap on retained attempt rows. See {@link OUTBOX_ATTEMPT_LOG_CAP}. */
     readonly attemptLogCap?: number;
+    /**
+     * Who this process is, stamped on every row it claims.
+     *
+     * REQUIRED, and deliberately so. The first version made it optional "so an
+     * embedder driving a single process is not forced to invent an identity",
+     * which meant a caller who omitted it silently got the old behaviour: every
+     * replica delivers every row. An exactly-once gate that can be switched off by
+     * leaving a field out is not a gate — it is a default, and the wrong one.
+     *
+     * The INSTANCE rather than the replica name: a pod that restarts under a
+     * stable name must not look like it still holds the claim it died inside, or
+     * the lease is reading its own ghost.
+     */
+    readonly claimedBy: string;
+    /**
+     * How long a claim stands before another replica may take the row.
+     *
+     * It is a LEASE, not a lock: the holder can die, and nothing it left behind
+     * may block delivery forever. It must therefore exceed the slowest handler
+     * you are willing to wait for — a lease shorter than a real delivery hands
+     * the same row to a second replica while the first is still working, which is
+     * the duplicate this whole mechanism removes, reintroduced by a number.
+     *
+     * Default 5 minutes.
+     */
+    readonly claimLeaseMs?: number;
 }
 
 /**
@@ -3474,14 +3528,6 @@ export declare const drainForShutdown: (options: {
     }) => void;
 }) => void;
 
-/**
- * One drain pass: claim due rows, run their handler, record the outcome.
- *
- * A row whose handler is unknown is left PENDING rather than dead-lettered —
- * the usual cause is a deploy where the enqueuing code shipped before the
- * handler, and discarding those would turn a rollout ordering detail into
- * permanent data loss.
- */
 export declare const drainOutbox: (deps: DrainDeps) => Promise<DrainResult>;
 
 export declare interface DrainResult {
@@ -4544,6 +4590,38 @@ export declare interface FinopsRunnerHandle {
     readonly runTick: () => void;
 }
 
+/** A member of the fleet, as membership sees it. The shape this module needs
+ *  from `instanceMembership`, named so the merge can be tested without one. */
+export declare interface FleetMember {
+    readonly instanceId: string;
+    readonly startedAt: number;
+}
+
+export declare interface FleetMergeResult<T> {
+    /** One entry per replica that has written, newest generation only. */
+    readonly byReplica: ReadonlyArray<{
+        readonly replicaId: string;
+        readonly version: string | undefined;
+        readonly ageMs: number;
+        /** Where a peer can reach it, or `undefined`. */
+        readonly reachableAt: string | undefined;
+        readonly payload: T;
+    }>;
+    /** Replicas membership knows about that have written nothing readable. */
+    readonly missing: ReadonlyArray<string>;
+    readonly responded: number;
+    readonly expected: number;
+    /** Rows old enough that a reader should not treat them as current. */
+    readonly stale: ReadonlyArray<{
+        readonly replicaId: string;
+        readonly ageMs: number;
+    }>;
+    /** 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. */
+    readonly versions: Readonly<Record<string, number>> | undefined;
+}
+
 export declare interface FluentStore extends Omit<MutationStore, 'update' | 'delete' | 'query'> {
     /**
      * Diff-based many-to-many link writer for a junction table. `anchor` names the
@@ -4665,6 +4743,17 @@ export declare const forbiddenColumnsForSubject: (tableName: string, subject: Su
 /** Forget the calling subject's credential. Returns whether a row was removed. */
 export declare const forgetCredential: (store: VaultStore, connectionId: string, subjectId: string) => Promise<boolean>;
 
+/**
+ * Drop rows for a replica GENERATION that is gone.
+ *
+ * Not a retention sweep — the table has no history to age out. This removes
+ * the row of a process that restarted, because the replica's NEW row is
+ * written under the same `(replicaId, kind)` key and the old generation is
+ * simply overwritten. What this handles is a replica that went away for good
+ * (a scale-down), whose row would otherwise be counted forever.
+ */
+export declare const forgetReplicaObservations: (store: DataStore, replicaId: string) => Promise<void>;
+
 /** A boot-ready message for a set of cache-scope leaks (empty → `undefined`). */
 export declare const formatCacheScopeLeaks: (leaks: ReadonlyArray<CacheScopeLeak>) => string | undefined;
 
@@ -4776,6 +4865,9 @@ export declare type HandlerBody = void | Promise<unknown> | Effect.Effect<unknow
  */
 export declare const hashUnitInterval: (s: string) => number;
 
+/** How much longer than `keepAliveTimeout` the headers deadline runs. */
+export declare const HEADERS_TIMEOUT_MARGIN_MS = 5000;
+
 /** Define a histogram. `boundaries` default to the framework duration buckets. */
 export declare const histogramMetric: (name: string, boundaries?: MetricBoundaries.MetricBoundaries, description?: string) => Metric.Metric.Histogram<number>;
 
@@ -5294,6 +5386,23 @@ export declare interface JunctionLinks {
     }>;
 }
 
+/** The `http:` block's keep-alive knobs. */
+export declare interface KeepAliveConfig {
+    readonly http?: {
+        /** Idle keep-alive lifetime, ms. Default 72000. Raise it above YOUR
+         *  proxy's idle timeout — see `DEFAULT_KEEP_ALIVE_MS` for why 72s. */
+        readonly keepAliveTimeoutMs?: number;
+        /** Header-completion deadline, ms. Must exceed `keepAliveTimeoutMs`.
+         *  Default `keepAliveTimeoutMs + 5000`. */
+        readonly headersTimeoutMs?: number;
+    };
+}
+
+export declare interface KeepAliveTimeouts {
+    readonly keepAliveTimeoutMs: number;
+    readonly headersTimeoutMs: number;
+}
+
 export declare interface KvFacade {
     readonly kv: AsyncKv;
     /** The resolved Effect-native `Kv` service instance. Its methods close over
@@ -6029,6 +6138,25 @@ export declare const memoryRywPositionStore: (options?: MemoryRywOptions) => Ryw
  */
 export declare const mergeCookieHeader: (existing: string | undefined, patch: Readonly<Record<string, string>>) => string;
 
+/**
+ * Merge rows into a fleet view, and say what is missing from it.
+ *
+ * The three things that make this honest, each of which a naive `rows.map()`
+ * gets wrong:
+ *
+ *  1. **A replica membership knows about but that has no row is MISSING**, not
+ *     absent. Dropping it silently is the unmarked sample this whole feature
+ *     exists to end — one level up, and more expensive, because the reader now
+ *     believes they asked everybody.
+ *  2. **A stale row is reported WITH its age** rather than filtered out.
+ *     Removing it would make a partial answer look complete; keeping it
+ *     unmarked would make fiction look current. Neither is available.
+ *  3. **Mixed versions are named.** During a rolling deploy the fleet genuinely
+ *     spans two shapes, and an aggregate that averages them silently is wrong
+ *     in a way nothing downstream can detect.
+ */
+export declare const mergeFleetObservations: <T>(rows: ReadonlyArray<ReplicaObservationRow>, members: ReadonlyArray<FleetMember>, staleAfterMs?: number) => FleetMergeResult<T>;
+
 export { MetricBoundaries }
 
 export declare interface MetricBucketPoint {
@@ -7044,10 +7172,21 @@ export declare class ReactionRateLimiter {
 }
 
 export declare interface ReactionRunDeps {
-    /** Idempotency store — `has(key)` true ⇒ already acted. */
+    /**
+     * Atomically claim ONE logical change. `true` = ours, act. `false` = someone
+     * already has it (or the claim could not be taken — fail-closed, like the
+     * rate slot and the budget beside it).
+     *
+     * ONE operation, not `has` then `add`, and the difference is the whole
+     * guarantee. A read-then-write cannot be won by exactly one caller: two
+     * replicas both read "not seen", both act, and `dedupeKey` — the field
+     * `defineReaction` REQUIRES precisely so an act cannot repeat — delivers N
+     * acts on N replicas. It was worse than a missing gate, because it read as a
+     * present one: the in-memory set behind it was per-process, so every test and
+     * every single-instance run confirmed it worked.
+     */
     readonly dedupe: {
-        readonly has: (key: string) => boolean | Promise<boolean>;
-        readonly add: (key: string) => void | Promise<void>;
+        readonly claim: (key: string) => boolean | Promise<boolean>;
     };
     /** Resolve + run the reaction's act AS the agent actor. Injected by the serve
      *  layer (it owns agent/workflow execution). */
@@ -7166,6 +7305,16 @@ export declare const readPollCeilingMs: (env?: {
 /** Is anything listening? Call sites skip their work when nothing is. */
 export declare const readRecordingActive: () => boolean;
 
+/**
+ * Every replica's rows for one kind.
+ *
+ * `now` is injected so a caller can compute ages against one instant rather
+ * than a moving clock — two rows compared against two `Date.now()` calls are
+ * two measurements, and the difference between them is noise a reader would
+ * read as signal.
+ */
+export declare const readReplicaObservations: (store: DataStore, kind: ReplicaObservationKind, now?: number) => Promise<ReadonlyArray<ReplicaObservationRow>>;
+
 /** `admin:full` (mirrors `@voltro/protocol`'s ADMIN_SCOPE) bypasses ReBAC. */
 export declare const REBAC_ADMIN_SCOPE = "admin:full";
 
@@ -7591,6 +7740,8 @@ export declare interface RelationTuple {
  */
 export declare const releaseWakeup: (store: DataStore, ref: WakeupRef) => Promise<void>;
 
+export declare const REPLICA_OBSERVATIONS_TABLE = "_voltro_replica_observations";
+
 export declare interface ReplicaHealth {
     /** Whether this replica is currently eligible for reads. */
     isHealthy(replica: DataStore): boolean;
@@ -7620,6 +7771,27 @@ export declare interface ReplicaHealthOptions {
     readonly now?: () => number;
 }
 
+/** Which observation a row carries. A closed set — a new kind is a deliberate
+ *  addition with a reader, not a free-form label. */
+export declare type ReplicaObservationKind = 'resume' | 'subscriptions';
+
+/** One replica's row, as a reader gets it back. */
+export declare interface ReplicaObservationRow {
+    readonly replicaId: string;
+    readonly startedAt: number;
+    readonly version: string | undefined;
+    readonly kind: ReplicaObservationKind;
+    readonly payload: unknown;
+    /** Where a peer can reach it, or `undefined` — never a guess. */
+    readonly reachableAt: string | undefined;
+    readonly writtenAt: number;
+    /** How old this row is, on the READER's clock. Approximate by construction —
+     *  it compares two machines' clocks, which is exactly what
+     *  `instanceMembership` refuses to do for liveness. It is good enough to
+     *  say "this is minutes old", and must never be used to order two rows. */
+    readonly ageMs: number;
+}
+
 /** Captured per-read for observability. Pushed into trace buffers
  *  by the runtime so `voltro traces` shows the routing decision +
  *  any RYW wait latency. */
@@ -7919,6 +8091,8 @@ export declare interface ResolvedWorkflowCallerContext extends WorkflowCallerCon
     readonly traceId: string;
 }
 
+export declare const resolveKeepAlive: (config: KeepAliveConfig | null | undefined) => KeepAliveTimeouts;
+
 /**
  * Resolve the guard's configuration.
  *
@@ -9900,6 +10074,61 @@ export declare interface SubscriberDefinition {
     readonly table: string;
     /** Default `'any'`. */
     readonly on?: SubscribeOp | ReadonlyArray<Exclude<SubscribeOp, 'any'>>;
+    /**
+     * Run the handler ONCE PER CHANGE across the whole fleet, instead of once on
+     * every replica that sees it.
+     *
+     * **Without it, the handler runs on EVERY api instance.** That is the correct
+     * default and not a gap: a subscriber that refreshes a search index, drops a
+     * process-local cache entry or updates in-memory state has to run everywhere,
+     * and a fleet-wide gate would leave every other replica stale. The default
+     * assumes the handler is IDEMPOTENT.
+     *
+     * It is the wrong default for an EFFECT — a notification, a mail, a webhook, a
+     * payment — because there is nothing to make idempotent: the effect IS the
+     * write, so each run produces another one. Two replicas send two mails.
+     *
+     * `once` returns a deterministic key for the change, and exactly one replica
+     * wins the claim on it (`_voltro_change_claims`, INSERT-wins on a UNIQUE — the
+     * same arbiter the cron scheduler uses for a firing). The key is namespaced by
+     * this subscriber's file id, so two subscribers on one table never lock each
+     * other out.
+     *
+     * ```ts
+     * export default defineSubscriber({
+     *   table: 'absence_requests',
+     *   on: ['insert'],
+     *   once: true,
+     *   handler: notifyApprovers,
+     * })
+     * ```
+     *
+     * **`once: true` derives the key for you**, and is the right default choice.
+     * It names the change by its CONTENT plus its position among content-identical
+     * repeats (`changeDigest` + `OccurrenceCounter`, `@voltro/database`) — which is
+     * the only thing two replicas provably agree on, since a fleet change carries
+     * no LSN, no commit id and no `traceId`. `A→B`, then `B→A`, then `A→B` again is
+     * three changes, not two.
+     *
+     * **A function is for when you want to be COARSER than one-per-change.** Two
+     * updates that differ only in a field you do not care about are two changes to
+     * `once: true` and can be one to a key function that ignores that field.
+     *
+     * **If you write one, it must tell two genuine changes apart.** A row id is
+     * enough for `insert` and `delete`, where a row changes state once. It is NOT
+     * enough for `update`: two edits to the same row produce the same id, and the
+     * second would be dropped as a duplicate of the first. Put something that moves
+     * in the key — `` `${row.id}:${row.updatedAt}` `` — or use `once: true`.
+     *
+     * **AT MOST once, not exactly once.** The claim is taken BEFORE the handler
+     * runs, so a replica that wins and then dies takes the event with it, and a
+     * claim that cannot be written (database unreachable) is not taken by anyone.
+     * Both are loud in the log and neither is retried — a subscriber is
+     * best-effort by construction. When the effect must not be lost, the change
+     * stream is the wrong seam for it: run it in the mutation, or start a workflow
+     * from a `*.reaction.tsx`, where the durability is the primitive's job.
+     */
+    readonly once?: true | ((event: SubscribeEvent) => string);
     readonly handler: SubscribeHandler;
 }
 
@@ -10736,6 +10965,8 @@ export declare const VOLTRO_TENANT_MIXIN_ID: "voltro/tenant";
  */
 export declare const _voltroApprovalsTable: TableLike;
 
+export declare const _voltroChangeClaimsTable: TableLike;
+
 /**
  * `_voltro_connection_grants` — an IN-FLIGHT oauth2 handshake. Separate from
  * the credential table on purpose: a handshake is a short-lived, single-use
@@ -11489,4 +11720,13 @@ 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 { }