@voltro/runtime 0.54.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';
@@ -94,6 +95,7 @@ import { SyncLogger } from '@voltro/logger';
 import { TableLike } from '@voltro/database';
 import { TableName } from '@voltro/protocol';
 import { TableValidationFailed } from '@voltro/protocol';
+import { TargetRelation } from '@voltro/protocol';
 import { TenantRowNotFound } from '@voltro/protocol';
 import { TenantScopeViolation } from '@voltro/protocol';
 import { Tracer } from 'effect';
@@ -1124,7 +1126,14 @@ export declare const applyConnectionCredential: (clientId: number, headers: Reco
  * - a non-array value is a refusal naming the field — silently ignoring it
  *   would read as "saved" while the links stayed stale;
  * - the row id is `output.id`, else `input.id`; with neither the declaration
- *   is unusable and says so.
+ *   is unusable and says so;
+ * - the DECLARED junction columns must match the junction's real reference
+ *   pair. They are declaration data because the browser drives junction
+ *   auto-optimistic from the same block and cannot derive them; this is the
+ *   one place both readings meet, so a disagreement is refused here — before
+ *   any write — with the correct pair named. Letting it through would mean the
+ *   client patched one column while the server wrote another, and the UI would
+ *   look right until the delta contradicted it.
  */
 export declare const applyDeclaredRelations: (params: {
     readonly store: RelationLinksStore;
@@ -1163,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`.
  *
@@ -2939,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;
@@ -2947,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
@@ -2983,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.
  *
@@ -3428,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;
 }
 
 /**
@@ -3466,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 {
@@ -4536,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
@@ -4657,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;
 
@@ -4768,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>;
 
@@ -5244,6 +5344,17 @@ export declare const ivmValue: (shape: AggregateShape, g: GroupState) => number
  * columns is rejected with a message naming what it found.
  */
 export declare interface JunctionLinks {
+    /**
+     * The junction's two reference columns as RESOLVED for this anchor — the
+     * source of truth a declared `relations:` is verified against. It is exposed
+     * because the pair also has to be stated in the descriptor (the browser
+     * cannot derive it), and a stated fact that nothing compares against is a
+     * divergence waiting to happen.
+     */
+    readonly columns: {
+        readonly anchorColumn: string;
+        readonly targetColumn: string;
+    };
     /** The current target ids linked to the anchor. */
     list(): Promise<ReadonlyArray<string>>;
     /** Reconcile the links to EXACTLY `targetIds` — insert the missing, delete the
@@ -5275,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
@@ -6010,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 {
@@ -6087,10 +6234,10 @@ export declare interface MutationLike {
         readonly requiresApproval?: AnyApprovalPolicy | undefined;
         readonly target?: {
             readonly table: string;
-            readonly relations?: Readonly<Record<string, string>> | undefined;
+            readonly relations?: Readonly<Record<string, TargetRelation>> | undefined;
         } | ReadonlyArray<{
             readonly table: string;
-            readonly relations?: Readonly<Record<string, string>> | undefined;
+            readonly relations?: Readonly<Record<string, TargetRelation>> | undefined;
         }> | undefined;
     };
     executor(input: unknown, ctx: unknown): unknown;
@@ -6299,6 +6446,16 @@ declare const NoRowFound_base: Schema.TaggedErrorClass<NoRowFound, "NoRowFound",
 /** Note one read against the in-flight procedure. No scope → nothing happens. */
 export declare const noteRead: (descriptor: QueryDescriptor) => void;
 
+/**
+ * Record the resume verdict for one subscription setup. `true` means a ring
+ * was recorded; anything else names why it was not.
+ *
+ * Logs at debug ONCE per (label, verdict) — a hot query must not narrate every
+ * subscribe, and the second identical verdict carries no information the first
+ * did not.
+ */
+export declare const noteResumeVerdict: (rawLabel: string, verdict: true | ResumeExclusion) => void;
+
 export declare interface Notification {
     readonly subscriberId: string;
     readonly fingerprint: string;
@@ -7015,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). */
@@ -7137,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";
 
@@ -7531,9 +7709,15 @@ export declare interface RegistryTableLike {
  *  request was. */
 export declare const rehydrateGuards: (serialized: ReadonlyArray<SerializedGuard>) => ReadonlyArray<AnyGuardSpec>;
 
-/** The store slice `applyDeclaredRelations` needs. */
+/** The store slice `applyDeclaredRelations` needs. `columns` is the junction's
+ *  DERIVED reference pair — the truth the descriptor's declaration is checked
+ *  against before anything is written. */
 declare interface RelationLinksStore {
     relationLinks(junctionTable: string, anchorTable: string, anchorId: string): {
+        readonly columns: {
+            readonly anchorColumn: string;
+            readonly targetColumn: string;
+        };
         set(targetIds: ReadonlyArray<string>): Promise<unknown>;
     };
 }
@@ -7556,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;
@@ -7585,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. */
@@ -7732,6 +7939,9 @@ export declare const resetEventMetricTagCacheForTests: () => void;
 /** Drop everything recorded. For tests; not called by the runtime. */
 export declare const resetObservedGraph: () => 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;
 
@@ -7881,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.
  *
@@ -8071,6 +8283,31 @@ export declare type ResumeAnswer =
     readonly kind: 'snapshot';
 };
 
+/** The census as of now, one entry per label that has been subscribed. */
+export declare const resumeCensus: () => ReadonlyArray<ResumeVerdict>;
+
+/**
+ * Why a subscription carries no resume ring.
+ *
+ * - `computed` — the executor returned a value, not a descriptor. There is no
+ *   delta chain to replay: the handler re-runs opaquely and emits snapshots.
+ *   Declaring `tables:` on the row filter cannot change this; returning the
+ *   query builder instead of a mapped value can.
+ * - `row-filter` — the registered filter may narrow this subscription's source
+ *   table, so its row set is re-resolved per delivery. Declaring `tables:`
+ *   fixes it for every source the filter does NOT touch; for a source it does
+ *   touch, the exclusion is the point.
+ * - `eager-load` — the descriptor carries `.with(...)` while a filter is
+ *   registered, and the relation is resolved below the seam that would narrow
+ *   it. Reported only when the base table is NOT itself narrowed, so this
+ *   reason always means: drop the eager load and the subscription resumes.
+ * - `uncanonical-input` — the input cannot be reduced to a stable ring key, so
+ *   two different inputs would collide under one label.
+ * - `not-offered` — the binder was driven without resume input at all (the
+ *   lower-level entrypoint used by tests).
+ */
+export declare type ResumeExclusion = 'computed' | 'row-filter' | 'eager-load' | 'uncanonical-input' | 'not-offered';
+
 /**
  * The identity a ring is recorded under — and the identity a resume must
  * present to read it back. `subjectId`/`tenantId` are part of the KEY, so a
@@ -8099,6 +8336,14 @@ export declare interface ResumeTunables {
 
 export declare const resumeTunables: () => ResumeTunables;
 
+/** One label's tally. `resumable + Σ excluded` is the number of subscriptions
+ *  set up on this label since the process started. */
+export declare interface ResumeVerdict {
+    readonly label: string;
+    readonly resumable: number;
+    readonly excluded: Readonly<Partial<Record<ResumeExclusion, number>>>;
+}
+
 export { RetentionConflict }
 
 export { RetentionSource }
@@ -8279,9 +8524,19 @@ export declare interface RowFilter<Ctx = unknown> {
      * must not replay deltas on reconnect — the answer can change while the
      * socket is down (a membership ends) and a wrong replay leaks rows. But the
      * question the framework could ask was only "is a filter registered at
-     * all?", so ONE registration disabled delta-resume for the whole process. A
-     * deployment measured a filter narrowing 4 tables costing the feature on all
-     * 173 of their query descriptors, 55 of whose source tables it never touches.
+     * all?", so ONE registration disabled delta-resume for the whole process,
+     * including every subscription reading a table the predicate never returns
+     * anything for.
+     *
+     * WHAT IT DOES NOT BUY, and this bounds the whole feature: a query whose
+     * executor returns a VALUE rather than a descriptor — anything that maps the
+     * rows or wraps them in a page envelope — has no delta chain to resume in
+     * the first place. It re-runs an opaque handler and emits snapshots, filter
+     * or no filter. So the number of subscriptions a declaration can give back
+     * is the number that bind a descriptor, not the number of queries in the
+     * app; declare it anyway (it costs nothing and applies the moment a query
+     * returns a builder), but read `resumeCensus()` — or
+     * `/_voltro/inspect/subscriptions` — before expecting a change.
      *
      * WHY A DECLARATION RATHER THAN A PROBE. Resolving the scope at subscribe
      * and treating `predicate(ctx, source) === undefined` as safe is cheaper and
@@ -8297,9 +8552,14 @@ export declare interface RowFilter<Ctx = unknown> {
      * filter (this field absent) keeps the conservative behaviour: no resume
      * anywhere, no verification.
      *
+     *     const OWNED = new Set(['documents', 'comments'])
      *     setRowFilter({
-     *       load, predicate,
-     *       tables: ['bookmarks', 'recentSearches', 'todoSchedules', 'todoTags'],
+     *       load,
+     *       predicate: (ctx, table) => (OWNED.has(table) ? eq('ownerId', ctx.userId) : undefined),
+     *       // Derived from the same set the predicate reads. Two hand-kept
+     *       // lists is the shape in which a table lands in exactly one of
+     *       // them — and the penalty here is a failing read, not a warning.
+     *       tables: [...OWNED],
      *     })
      */
     readonly tables?: ReadonlyArray<string>;
@@ -9814,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;
 }
 
@@ -10650,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
@@ -11403,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 { }