@voltro/runtime 0.55.0 → 0.57.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,15 @@ 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;
+
 /**
  * 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 +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;
@@ -2991,6 +3035,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 +3489,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 +3553,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 +4615,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 +4768,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 +4890,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 +5411,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 +6163,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 {
@@ -6328,6 +6481,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;
@@ -6665,6 +6827,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.
@@ -7044,10 +7242,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 +7375,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 +7810,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 +7841,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. */
@@ -7773,6 +8015,11 @@ 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;
 
@@ -7919,6 +8166,8 @@ export declare interface ResolvedWorkflowCallerContext extends WorkflowCallerCon
     readonly traceId: string;
 }
 
+export declare const resolveKeepAlive: (config: KeepAliveConfig | null | undefined) => KeepAliveTimeouts;
+
 /**
  * Resolve the guard's configuration.
  *
@@ -7957,31 +8206,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>;
 
 /**
@@ -8440,6 +8664,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;
 
@@ -9020,6 +9248,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. */
@@ -9900,6 +10138,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 +11029,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 +11784,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 { }