@voltro/runtime 0.23.0 → 0.25.0

package/dist/index.d.ts

@@ -14,8 +14,16 @@ import { DialectId } from '@voltro/database';
 import { DialectReplicationAdapter } from '@voltro/database';
 import { Duration } from 'effect';
 import { Effect } from 'effect';
+import { EventDeliverySemantics } from '@voltro/protocol';
+import { EventDescriptor } from '@voltro/protocol';
+import { EventKeyInvalid } from '@voltro/protocol';
+import { EventPayloadInvalid } from '@voltro/protocol';
+import { EventPayloadTooLarge } from '@voltro/protocol';
+import { EventResumePoint } from '@voltro/protocol';
+import { EventStreamEvent } from '@voltro/protocol';
 import { Fiber } from 'effect';
 import { FieldCipher } from '@voltro/database';
+import { Guards } from '@voltro/protocol';
 import * as http from 'node:http';
 import { HttpClient } from '@effect/platform';
 import { HttpRequestInterceptor } from '@voltro/protocol';
@@ -855,7 +863,7 @@ export declare interface AppContext {
      *  recompute. */
     readonly kv: AsyncKv;
     /** Webhooks service — present when `@voltro/plugin-webhooks` is in
-     *  the app's plugin list. Use `defineOutgoingEvent(...)` in a
+     *  the app's plugin list. Declare the event with `defineEvent({ …, webhook })` in a
      *  `*.webhook.tsx` file to declare an event, then `ctx.webhooks.emit(
      *  'eventId', payload)` from any handler. */
     readonly webhooks?: WebhooksAppContext;
@@ -1069,6 +1077,17 @@ export declare interface AuditableQuery {
     readonly source?: string | ReadonlyArray<string> | undefined;
 }
 
+/**
+ * An Effect that is ALSO awaitable.
+ *
+ * The intersection is the type-level half of the fix: without `PromiseLike`,
+ * `await ctx.events.publish(…)` type-checks (awaiting a non-Promise is legal)
+ * and hands back the EFFECT rather than the result — so even after the runtime
+ * behaviour was fixed, the value an async handler got would have been typed
+ * wrong. Both halves are needed, and both are pinned by tests.
+ */
+export declare type AwaitableEffect<A, E> = Effect.Effect<A, E> & PromiseLike<A>;
+
 /**
  * Resolve once a server returned by {@link startRpcServer} has actually
  * bound its port (node `'listening'` event). REJECTS on `'error'`
@@ -1117,7 +1136,38 @@ export declare interface BeginOAuthResult {
  */
 export declare const bindConnectionSubject: (clientId: number, subject: Subject) => void;
 
-export declare const bindMutation: <Input, Output, E = never>(execute: (input: Input, context: RuntimeContext) => Output | Promise<Output> | Effect.Effect<Output, E, never>, input: Input, spanName?: string) => Effect.Effect<Output, E, SubjectService | ConnectionInfo>;
+/**
+ * Bind one client's subscription to a declared event.
+ *
+ * The TENANT comes from the resolved subject and from nowhere else, so a
+ * cross-tenant subscription is not something a caller can ask for. `key` has
+ * already been decoded by the rpc layer against the descriptor's schema.
+ *
+ * The stream ends when the client disconnects, through the same per-connection
+ * interrupt registry subscriptions use — so one reconnect policy, one devtools
+ * view, one connection lifecycle for both primitives.
+ */
+export declare const bindEvent: (input: BindEventInput) => Stream.Stream<EventStreamEvent<unknown>, ScopeError, SubjectService | ConnectionInfo>;
+
+export declare interface BindEventInput {
+    readonly bus: EventBus;
+    readonly event: string;
+    /** Decoded routing key, exactly as the descriptor declares it. */
+    readonly key: unknown;
+    readonly options?: EventSubscribeOptions | undefined;
+    /** Queue depth override — tests use a tiny one to force the drop path. */
+    readonly queueSize?: number;
+    /**
+     * The descriptor's `guards:` — WHO MAY LISTEN.
+     *
+     * Passed in rather than read from a registry so there is exactly one way for a
+     * subscription to be authorised, and it is the same list the manifest, the
+     * doctor and the dashboard report on.
+     */
+    readonly guards?: Guards<unknown> | undefined;
+}
+
+export declare const bindMutation: <Input, Output, E = never>(execute: (input: Input, context: RuntimeContext) => Output | Promise<Output> | Effect.Effect<Output, E, never>, input: Input, spanName?: string, codec?: MutationOutputCodec<unknown>, idempotency?: IdempotencyBinding) => Effect.Effect<Output, E, SubjectService | ConnectionInfo>;
 
 /**
  * Bind a non-reactive server→client stream (A3). The executor builds a
@@ -1323,6 +1373,7 @@ export declare interface CandidateShape {
     readonly windowed?: boolean;
 }
 
+/* Excluded from this release type: canonicalize */
 export { CaughtUpVerdict }
 
 /** A CDC change event, structurally — what the reactive engine already emits
@@ -1929,7 +1980,13 @@ export declare const defineAggregate: <Row>(input: AggregateDefinitionInput<Row>
  */
 export declare const defineConnection: <D extends ConnectionDefinition>(definition: D) => D;
 
-export declare const defineEventTrigger: <EventPayload = unknown, WorkflowPayload = EventPayload>(spec: Omit<WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>, "_tag">) => WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>;
+export declare const defineEventTrigger: <EventPayload = unknown, WorkflowPayload = EventPayload>(spec: Omit<WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>, "_tag"> | (Omit<WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>, "_tag" | "event"> & {
+    /** A declared event. Its `name` becomes the matched event. */
+    readonly on: {
+        readonly kind: "event";
+        readonly name: string;
+    };
+})) => WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>;
 
 /**
  * Type a procedure executor against its descriptor's `output` (and `input`).
@@ -2116,6 +2173,27 @@ export declare class Dispatcher {
     onSubscriptionsChange(listener: () => void): () => void;
     /** Tear down the change-event listener. Call on server shutdown. */
     close(): void;
+    /**
+     * Re-run EVERY live subscription, because this replica proved it missed
+     * changes it can never recover.
+     *
+     * The broadcast bus detects a serial gap from a peer; pub/sub keeps no log,
+     * so the lost ChangeEvents are gone. That does not matter, and the reason it
+     * does not matter is the whole design: a live query is IDEMPOTENT. Re-running
+     * one is always safe and always lands on the truth, so a proven loss is
+     * repaired by refreshing rather than by replaying.
+     *
+     * Without this a dropped message leaves a client stale FOREVER — its socket
+     * never breaks, so the client-side reconnect never fires, and its query does
+     * not re-run until something else happens to touch the same table. On a quiet
+     * table that is never, and the only symptom is a user saying the page did not
+     * update.
+     *
+     * Deliberately blunt. It re-queries every subscription rather than reasoning
+     * about which tables the lost changes touched — we do not know, and guessing
+     * narrower would reintroduce exactly the silent staleness this repairs.
+     */
+    refreshAll(reason: string): Promise<void>;
     private handleChange;
 }
 
@@ -2170,6 +2248,13 @@ export declare const drainForShutdown: (options: {
     readonly hooks: ReadonlyArray<() => void | Promise<void>>;
     readonly deadlineMs: number;
     readonly exit: () => void;
+    /** How the drain ended, for the caller to report. A completed drain and one
+     *  CUT at the deadline are different incidents and were indistinguishable in
+     *  the log — asked for by a consumer who could see neither. */
+    readonly onOutcome?: (outcome: {
+        readonly reason: "drained" | "deadline";
+        readonly ms: number;
+    }) => void;
 }) => void;
 
 /**
@@ -2254,6 +2339,320 @@ export declare const enterRequestLoader: (loader: DataLoader) => void;
  *  Promise-wrapped to satisfy the async contract. */
 export declare const envSecretsBackend: SecretsBackend;
 
+/**
+ * How many deliveries one client may fall behind before the oldest are dropped.
+ *
+ * Sized to match the bus's ring: a client that falls further behind than the
+ * server retains could not be made whole on reconnect anyway, so a deeper queue
+ * would only delay the same honest answer.
+ */
+export declare const EVENT_CLIENT_QUEUE_SIZE = 64;
+
+/**
+ * The queue depth for a `latest` event: exactly one.
+ *
+ * Not a smaller buffer — a DIFFERENT contract. A depth of one on a sliding queue
+ * means a delivery arriving while another is pending REPLACES it, which is what
+ * "only the current value matters" means when the consumer is slow. Anything
+ * deeper would hand a 60Hz display a backlog to work through before it could
+ * reach the state it actually wanted to show.
+ */
+export declare const EVENT_LATEST_QUEUE_SIZE = 1;
+
+export declare class EventBus {
+    private readonly routes;
+    private readonly origin;
+    private readonly ringSize;
+    private readonly ringTtlMs;
+    private readonly maxRoutes;
+    private readonly publishRemote;
+    private readonly deliveryOf;
+    /** Live local subscriber count per EVENT — the basis of channel interest. */
+    private readonly interest;
+    private readonly interestListeners;
+    private readonly now;
+    constructor(options: EventBusOptions);
+    /** This instance's id — the `origin` on everything it publishes. */
+    get instanceOrigin(): string;
+    /**
+     * Be told when this instance gains its FIRST or loses its LAST local
+     * subscriber for an event.
+     *
+     * The transport uses it to hold a cross-instance subscription only while
+     * somebody here is listening. Without it every replica receives, decodes and
+     * materialises a route for every event of every peer — including the ones it
+     * serves no clients for, which for a high-rate event is the bulk of the work
+     * it does and none of the work it needs.
+     *
+     * Registering REPLAYS the currently-active events synchronously, because the
+     * transport is attached after the bus exists: a subscriber that arrived in
+     * between would otherwise be invisible until it left and came back.
+     */
+    onInterestChange(listener: (event: string, active: boolean) => void): () => void;
+    private shiftInterest;
+    private notifyInterest;
+    /** Events this instance currently has at least one local subscriber for. */
+    activeEvents(): ReadonlyArray<string>;
+    /**
+     * One event's declared delivery semantics — what the bridge sizes its queue
+     * from, so the two cannot disagree about whether a drop is a loss.
+     */
+    deliveryFor(event: string): EventDeliverySemantics;
+    private state;
+    /**
+     * Drop the coldest IDLE routes when over the ceiling.
+     *
+     * A route with live listeners is never evicted regardless of age: evicting it
+     * would silently stop delivering to a connected subscriber, which is the exact
+     * class of failure this bus exists to make impossible. Only retention is
+     * sacrificed under pressure, never delivery.
+     */
+    private evictIfOverCapacity;
+    /**
+     * Drop what the ring may no longer replay.
+     *
+     * IN PLACE. The obvious version — `ring = ring.slice(drop)` — allocates and
+     * copies the whole ring on EVERY publish once it is full, which measured as
+     * the single largest cost in the publish path (5.8µs with a full ring against
+     * 0.35µs for everything else combined: the key encoding, the route, and the
+     * size gate's JSON put together). `splice` mutates, so a saturated route costs
+     * the same as an empty one.
+     *
+     * Worth keeping in mind if this is ever rewritten as a true circular buffer:
+     * the win here was removing the ALLOCATION, not the copy. A 64-element
+     * `splice(0, 1)` is cheap; a 64-element fresh array every 5 microseconds is
+     * what the garbage collector notices.
+     */
+    private pruneRing;
+    /**
+     * Publish an already-validated, already-size-checked envelope body.
+     *
+     * Validation lives at the `ctx.events.publish` seam rather than here because
+     * that is where the descriptor is — the bus deals in routes and bytes.
+     */
+    publish(input: {
+        readonly tenantId: string | null;
+        readonly event: string;
+        readonly key: unknown;
+        readonly payload: unknown;
+    }): EventEnvelope;
+    /**
+     * Take a delivery published by ANOTHER instance.
+     *
+     * Ignores our own origin echoed back: the local subscribers were already
+     * served synchronously at publish time, so accepting it here would deliver
+     * twice and break the serial contract (`n` would repeat).
+     */
+    injectRemote(envelope: EventEnvelope): void;
+    private accept;
+    /**
+     * Subscribe to one route. Returns the unsubscribe.
+     *
+     * The listener is invoked synchronously from `publish`, in registration order.
+     * Anything the subscriber needs to do slowly belongs behind its own queue —
+     * see the bridge.
+     */
+    subscribe(input: {
+        readonly tenantId: string | null;
+        readonly event: string;
+        readonly key: unknown;
+        readonly listener: EventListener_2;
+        readonly options?: EventSubscribeOptions | undefined;
+        /**
+         * Called SYNCHRONOUSLY at attach with the route's current watermarks.
+         *
+         * It is how a consumer learns where the stream stood the instant it joined,
+         * with no window for a publish to slip in between reading and subscribing.
+         * The bridge needs it because a delivery dropped BEFORE the client's first
+         * read would otherwise be invisible: with no baseline, the first serial it
+         * sees looks like a starting point rather than evidence of what came before.
+         */
+        readonly onAttach?: ((watermark: ReadonlyMap<string, number>) => void) | undefined;
+    }): () => void;
+    /**
+     * Serve a re-attach: replay what the ring still holds, and report — exactly —
+     * what it does not.
+     *
+     * The subtraction is the point. `owed` is what the client should have received
+     * since its last serial (from the watermark, which survives ring eviction);
+     * `replayed` is what we can actually hand over. An origin the client never
+     * mentioned is one that appeared while it was away, so everything retained
+     * from it is owed. A `gap` is emitted BEFORE the replay so a consumer reading
+     * in order learns it is behind before it starts processing.
+     */
+    private replayForResume;
+    stats(): EventBusStats;
+    /** Per-route live numbers for the inspect surface + dashboard. */
+    snapshot(): ReadonlyArray<EventRouteSnapshot>;
+    /** Drop every route, listener and buffer. For tests and shutdown. */
+    clear(): void;
+}
+
+export declare interface EventBusOptions {
+    /** This instance's id. Two processes must never share one. */
+    readonly origin: string;
+    /**
+     * Ring depth per route. 64 by default — sized from what comparable products
+     * allow (Ably caps replay at 100 messages / 2 minutes; Supabase at 25), i.e.
+     * tens of messages and minutes. Anything materially larger is a durable queue
+     * with extra steps, and the framework already has one (`ctx.outbox`).
+     */
+    readonly ringSize?: number;
+    /** How long a ring entry stays eligible for replay. 5 minutes by default. */
+    readonly ringTtlMs?: number;
+    /**
+     * Hard ceiling on how many routes retain a ring at once. A route is an
+     * app-controlled cardinality (`{userId}` in a key is one route per user), so
+     * without a ceiling an unbounded key space is an unbounded memory leak in a
+     * long-lived process — the same failure shape as an append-only table with no
+     * sweep, one layer up. Oldest-touched routes are evicted first.
+     */
+    readonly maxRoutes?: number;
+    /** Hand-off to the cross-instance transport. Absent ⇒ single-instance. */
+    readonly publishRemote?: (envelope: EventEnvelope) => void;
+    /**
+     * What a declared event's name means for retention and loss reporting.
+     *
+     * A lookup rather than a field on `subscribe`, because the answer must be the
+     * SAME for every subscriber of one event and for the publisher — a per-call
+     * argument is a per-call opportunity to disagree, and the disagreement would
+     * show up as one client being told it missed messages another was told it did
+     * not. Wired once from the declared events at boot.
+     */
+    readonly deliveryOf?: (event: string) => EventDeliverySemantics | undefined;
+    readonly now?: () => number;
+}
+
+export declare interface EventBusStats {
+    readonly routes: number;
+    readonly subscribers: number;
+    readonly buffered: number;
+}
+
+/** What a subscriber is told. `gap` is only ever emitted with a PROVEN count. */
+export declare type EventDelivery = {
+    readonly kind: 'event';
+    readonly envelope: EventEnvelope;
+    /**
+     * This route's watermark for `envelope.origin` IMMEDIATELY BEFORE this
+     * envelope was accepted — the one number a subscriber cannot infer, and
+     * without which it cannot tell two opposite situations apart.
+     *
+     * Both look identical from a subscriber's seat: an origin absent from the
+     * attach watermark, and a first delivery carrying a high serial.
+     *
+     *   prior > 0  this instance HAD been receiving that origin, so the
+     *              serials between what we forwarded and this one existed
+     *              here and were lost on the way to this subscriber.
+     *   prior = 0  this instance had accepted nothing from that origin on
+     *              this route, so nothing local could have been dropped. A
+     *              replica that started — or joined this event's channel —
+     *              while a peer was already at serial 5000 is in this case.
+     *
+     * Reading the second as the first is what made a freshly-started replica
+     * announce a 5000-message loss to every client on its first delivery.
+     */
+    readonly prior: number;
+} | {
+    readonly kind: 'gap';
+    readonly missed: number;
+    readonly reason: 'buffer' | 'resume';
+};
+
+/** One delivery, as it travels locally and across instances. */
+export declare interface EventEnvelope {
+    /** `tenant · event · key`, NUL-separated — built by `eventRoute`, read with
+     *  `parseEventRoute`. Never construct or split one by hand. */
+    readonly route: string;
+    /** Declared event name, carried separately so a consumer of the raw envelope
+     *  (broadcast bridge, inspect, metrics) needn't re-parse the route. */
+    readonly event: string;
+    /** Publishing instance. Serials are only comparable WITHIN one origin. */
+    readonly origin: string;
+    /** Monotonic per (origin, route). */
+    readonly n: number;
+    readonly emittedAt: number;
+    readonly payload: unknown;
+}
+
+declare type EventListener_2 = (delivery: EventDelivery) => void;
+export { EventListener_2 as EventListener }
+
+export declare const eventMetricTagCacheSizeForTests: () => number;
+
+/** What `publish` needs to know about the caller. */
+export declare interface EventPublishContext {
+    readonly bus: EventBus;
+    /** From the SUBJECT, never from a caller argument. */
+    readonly tenantId: string | null;
+    /**
+     * Defer until commit, when a transaction is open.
+     *
+     * Present ⇒ the caller is inside `transactional()` and the delivery is queued
+     * with the ChangeEvents the transactional view already buffers, so it is
+     * flushed by the same `commitEvents()` that publishes row changes — and
+     * discarded entirely on rollback. Absent ⇒ deliver now.
+     *
+     * A display reacting to a game start the database rolled back is not a race
+     * that is unlikely, it is one that happens on every constraint violation.
+     */
+    readonly deferToCommit?: ((deliver: () => void) => void) | undefined;
+    /**
+     * The DURABLE audience — the workflow-trigger path.
+     *
+     * `publish` is one declaration reaching several audiences, and this is the
+     * seam for the audience that outlives the process: it records the event and
+     * starts whatever workflows are triggered by it. Absent when the app declares
+     * no triggers, so an app that only fans out to clients pays nothing.
+     *
+     * Deliberately fire-and-forget from `publish`'s point of view: a trigger that
+     * fails must not fail the mutation that published, for the same reason a
+     * broker outage does not. The trigger's own delivery row records the failure.
+     */
+    readonly onPublished?: ((eventName: string, payload: unknown, descriptor: unknown) => void) | undefined;
+}
+
+export declare interface EventPublisher {
+    publish<Name extends string, Key extends Schema.Schema.Any, Payload extends Schema.Schema.Any>(descriptor: EventDescriptor<Name, Key, Payload>, key: Schema.Schema.Type<Key>, payload: Schema.Schema.Type<Payload>): AwaitableEffect<EventPublishResult, EventPublishError>;
+}
+
+export declare type EventPublishError = EventPayloadInvalid | EventKeyInvalid | EventPayloadTooLarge;
+
+/**
+ * The `ctx.events.publish` facade, bound to one request's tenant + transaction.
+ *
+ * Typed at the call site from the descriptor alone: `key` and `payload` are both
+ * inferred, so a wrong field name is a `tsc` error where it is written rather
+ * than a handler that never fires.
+ */
+/** What a publish resolves to, in either spelling. */
+export declare interface EventPublishResult {
+    readonly n: number;
+    readonly deferred: boolean;
+}
+
+/** A declared event's live numbers, for the inspect surface. */
+export declare interface EventRouteSnapshot {
+    readonly route: string;
+    readonly event: string;
+    readonly subscribers: number;
+    readonly buffered: number;
+    readonly lastEmittedAt: number | undefined;
+}
+
+/**
+ * The INTERNAL durable-event facade.
+ *
+ * No longer `ctx.events` — an app cannot reach this. `ctx.events.publish` is
+ * the only emitter, and it drives this one as its durable audience, so a
+ * workflow trigger and a client subscriber can never disagree about whether the
+ * event happened.
+ *
+ * The string form survives here, one layer down, because the durable path
+ * matches triggers BY NAME and the name is what a `defineEvent` descriptor
+ * supplies. What was removed is the ability for an app to invent a name that
+ * nothing declared — which is the whole defect.
+ */
 export declare interface EventsAppContext {
     emit<Payload = unknown>(eventName: string, data: Payload, options?: WorkflowEventEmitOptions): Promise<WorkflowEventEmitResult>;
 }
@@ -2273,6 +2672,20 @@ export declare interface EventsFacadeOptions {
     readonly makeId?: (prefix: 'wfe' | 'wfed') => string;
 }
 
+export declare interface EventSubscribeOptions {
+    /**
+     * Where this client left off, per origin. PRESENT means re-attach and the
+     * client is owed continuity; ABSENT means a first attach, which starts empty.
+     *
+     * The distinction cannot be inferred server-side — a reconnecting socket and a
+     * freshly mounted component look identical from here — so the client states
+     * it, and the framework's client does that automatically.
+     */
+    readonly resume?: ReadonlyArray<EventResumePoint> | undefined;
+    /** Descriptor opt-in: deliver what the ring holds even on a FIRST attach. */
+    readonly rewind?: boolean | undefined;
+}
+
 /** Exchange an authorization code (from the callback) for a token set. */
 export declare const exchangeAuthorizationCode: (definition: OAuth2ConnectionDefinition, input: {
     readonly code: string;
@@ -2504,6 +2917,9 @@ export declare interface GroupState {
     readonly extreme?: number;
 }
 
+/** What a user handler may return. */
+export declare type HandlerBody = void | Promise<unknown> | Effect.Effect<unknown, unknown, never>;
+
 /** 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>;
 
@@ -2530,6 +2946,21 @@ export declare interface HttpSecretsOptions {
     readonly ttlMs?: number;
 }
 
+/**
+ * WS-rpc idempotency store + TTL, passed to `bindMutation` as a closure param by
+ * the boot path (`serveApi`/`dev`) — NOT a service. @effect/rpc runs a handler in
+ * a NARROWED context (only the middleware `provides` + declared deps), so a plain
+ * merged service is invisible to `Effect.serviceOption` inside the handler; the
+ * store+ttl are boot-time constants the bind site already holds, so a closure is
+ * both correct and simpler. Omitted → WS mutation dedup is off (the default).
+ * Reuses the SAME `dataStoreIdempotencyStore` + `_voltro_idempotency` table as
+ * the REST path — enable once, protect both.
+ */
+export declare interface IdempotencyBinding {
+    readonly store: IdempotencyStore;
+    readonly ttlMs: number;
+}
+
 export declare interface IdleCheckOptions {
     readonly store: DataStore;
     readonly signals: ActivitySignals;
@@ -2715,6 +3146,47 @@ export { inspectWorkflow }
  */
 export declare const installPolicyGuardResolver: () => void;
 
+/**
+ * The live membership of this deployment, as THIS instance can observe it.
+ *
+ * Transport-agnostic, like the event bus: `announce` is injected and remote
+ * heartbeats arrive through `receive`. That keeps it testable with no broker and
+ * makes the cross-instance wiring one place rather than a concern spread through
+ * the registry.
+ */
+export declare class InstanceMembership {
+    private readonly members;
+    private readonly listeners;
+    private readonly instanceId;
+    private readonly startedAt;
+    private readonly meta;
+    private readonly heartbeatMs;
+    private readonly downAfterMs;
+    private readonly announce;
+    private readonly now;
+    private timer;
+    constructor(options: MembershipOptions);
+    get id(): string;
+    /** Begin announcing, and start expiring the silent. */
+    start(): void;
+    stop(): void;
+    private beat;
+    /**
+     * Take a heartbeat from another instance.
+     *
+     * Our own id echoed back by the broker is ignored: self-liveness is local, and
+     * accepting the echo would let a broker outage look like a self-death.
+     */
+    receive(heartbeat: MembershipHeartbeat): void;
+    /** Drop instances that have gone silent past the threshold. */
+    sweep(): void;
+    /** Everyone this instance currently believes is alive, self included. */
+    list(): ReadonlyArray<MemberSnapshot>;
+    /** Subscribe to membership changes. Returns the unsubscribe. */
+    onChange(listener: MembershipListener): () => void;
+    private emit;
+}
+
 /** Fire every registered interrupt for `clientId` (called on disconnect). */
 export declare const interruptConnectionStreams: (clientId: number) => void;
 
@@ -2775,6 +3247,15 @@ export declare const isOrglessUserSubject: (subject: {
     readonly tenantId?: string | null;
 } | null | undefined) => boolean;
 
+/** A query cancelled for exceeding the `statementTimeoutMs` deadline, across
+ *  dialects: pg `57014` (query_canceled — what `statement_timeout` raises),
+ *  MySQL `3024` (ER_QUERY_TIMEOUT), MariaDB `1969` (ER_STATEMENT_TIMEOUT), mssql
+ *  `ETIMEOUT` (tedious request timeout), sqlite `SQLITE_INTERRUPT`. NOT a
+ *  transient error — a re-run just repeats the runaway, so it must not retry
+ *  (`servePipeline`'s transient set deliberately excludes it). Lets a consumer /
+ *  observability layer name the failure instead of reading an opaque SqlError. */
+export declare const isQueryTimeout: (dbCause: Record<string, unknown>) => boolean;
+
 /**
  * Optimistic-concurrency guard: an undo is safe only when the row still looks
  * like what the forward mutation left (`next`). If another writer changed it
@@ -3067,6 +3548,17 @@ export declare const makeAppAccess: (subject: Subject) => AppAccess;
  *  fall back to `database`. */
 export declare const makeAsyncKv: ({ store, env }: KvFacadeOptions) => Promise<KvFacade>;
 
+/**
+ * Detect a serial jump per origin, and report it as a proven count.
+ *
+ * Stateful across one client's stream, which is why it is built per
+ * subscription rather than shared.
+ */
+export declare const makeBufferGapDetector: (attachWatermark?: ReadonlyMap<string, number>) => (event: {
+    readonly origin: string;
+    readonly n: number;
+}, prior?: number) => number;
+
 /**
  * Build a SpanProcessor that maps every finished span to a flat record
  * and hands it to `onSpanEnd`. The callback must not throw (a thrown
@@ -3117,6 +3609,8 @@ export declare const makeDisconnectConnectionExecutor: (deps: ConnectionBuiltinD
  */
 export declare const makeEffectStoreLayer: (store: MutationStore) => Layer.Layer<EffectStore>;
 
+export declare const makeEventPublisher: (ctx: EventPublishContext) => EventPublisher;
+
 export declare const makeEventsFacade: (options: EventsFacadeOptions) => EventsAppContext;
 
 /** Convenience: derive a key from a passphrase and build the cipher. */
@@ -3143,6 +3637,14 @@ export declare const makeLazyWorkflowFacade: (resolve: () => WorkflowsAppContext
 /** `__voltro.connections.list` — every declared connection, for the caller. */
 export declare const makeListConnectionsExecutor: (deps: ConnectionBuiltinDeps) => (_input: Record<string, never>, ctx: ConnectionExecutorCtx) => Promise<ReadonlyArray<ConnectionState>>;
 
+/**
+ * Build the replay codec from a mutation's `descriptor.output` Schema (call it at
+ * the bind site). Both directions fall back to the raw value if the Schema can't
+ * round-trip it — a guard for exotic schemas; for a value the handler actually
+ * produced, `encodeUnknownSync` never throws. `undefined` schema → no codec.
+ */
+export declare const makeMutationOutputCodec: (outputSchema: Schema.Schema.AnyNoContext | undefined) => MutationOutputCodec<unknown> | undefined;
+
 /**
  * Build the shared mutation runner. Used by BOTH the rpc WS handler and
  * the `/_voltro/inspect/invoke` endpoint (and the prod entrypoint) so they
@@ -3345,6 +3847,77 @@ export declare const materializeIvm: (shape: AggregateShape, state: IvmState) =>
     readonly value: number | null;
 }>;
 
+/** Told when the membership changes. `restarted` is a `left` + `joined` pair
+ *  for one id, reported as such so a consumer drops the old state rather than
+ *  resuming it. */
+export declare type MembershipEvent = {
+    readonly kind: 'joined';
+    readonly instanceId: string;
+    readonly startedAt: number;
+} | {
+    readonly kind: 'left';
+    readonly instanceId: string;
+    readonly reason: 'silent';
+} | {
+    readonly kind: 'restarted';
+    readonly instanceId: string;
+    readonly startedAt: number;
+};
+
+/** What one instance broadcasts about itself. */
+export declare interface MembershipHeartbeat {
+    readonly instanceId: string;
+    /**
+     * When this PROCESS started, as the sender's own epoch ms.
+     *
+     * Carried as an IDENTITY, never compared to our clock. Its job is to make a
+     * restart distinguishable from a hiccup: an instance that comes back with a
+     * NEW `startedAt` is a fresh process whose owned state is gone, so a consumer
+     * must drop what it held for the old one rather than resume it. A returning
+     * instance with the SAME value only ever missed a few beats.
+     */
+    readonly startedAt: number;
+    /** Free-form, for a dashboard: region, version, pod name. */
+    readonly meta?: Readonly<Record<string, string | number>> | undefined;
+}
+
+export declare type MembershipListener = (event: MembershipEvent) => void;
+
+export declare interface MembershipOptions {
+    readonly instanceId: string;
+    /** This process's start time. Defaults to now. */
+    readonly startedAt?: number;
+    readonly meta?: Readonly<Record<string, string | number>>;
+    /**
+     * How often to announce. 5 s by default — frequent enough that a death is
+     * noticed inside a page load, cheap enough that a hundred replicas produce
+     * twenty messages a second between them.
+     */
+    readonly heartbeatMs?: number;
+    /**
+     * Silence after which an instance is PRESUMED down. Default 3× the heartbeat.
+     *
+     * Three missed beats rather than one, because a single missed beat is a GC
+     * pause or a broker hiccup, and evicting on it would make a healthy cluster
+     * flap — every flap dropping and re-adding that instance's owned state, which
+     * a presence roster shows as everyone briefly leaving and coming back.
+     */
+    readonly downAfterMs?: number;
+    /** Send a heartbeat onto the transport. Absent ⇒ single-instance. */
+    readonly announce?: (heartbeat: MembershipHeartbeat) => void;
+    readonly now?: () => number;
+}
+
+export declare interface MemberSnapshot {
+    readonly instanceId: string;
+    readonly startedAt: number;
+    readonly meta: Readonly<Record<string, string | number>> | undefined;
+    /** Our clock, when we last heard from it. Never the sender's. */
+    readonly lastHeardAt: number;
+    /** True for this process. */
+    readonly self: boolean;
+}
+
 /** In-memory store (tests + single-process dev). */
 export declare const memoryApiKeyStore: () => ApiKeyStore;
 
@@ -3438,6 +4011,20 @@ export declare interface MutationLike {
     executor(input: unknown, ctx: unknown): unknown;
 }
 
+/**
+ * Encode/decode a mutation's output for idempotent replay. On a FRESH call the
+ * WIRE form (`encode`) is stored, so a later replay `decode`s it back to the exact
+ * Output the handler would have returned and the rpc layer re-encodes it
+ * identically. Storing the DECODED Output directly would corrupt `Date`/etc.
+ * fields through the store's JSON round-trip (encode there expects a `Date`, not
+ * the ISO string a round-trip produced). Built from `descriptor.output` at the
+ * call site; both fns fall back to the raw value if the Schema can't round-trip.
+ */
+export declare interface MutationOutputCodec<Output> {
+    readonly encode: (output: Output) => unknown;
+    readonly decode: (stored: unknown) => Output;
+}
+
 export declare interface MutationRunnerDeps {
     readonly store: TransactionalStore;
     /** Build the per-call `AppContext` bound to the transactional `tx`. */
@@ -4007,6 +4594,17 @@ export declare interface PublicApiKey {
     readonly metadata?: Readonly<Record<string, unknown>> | null;
 }
 
+/**
+ * Validate, size-check and publish one event.
+ *
+ * Returns the assigned serial so a caller (and the tests) can observe ordering
+ * without reaching into the bus.
+ */
+export declare const publishEvent: <Name extends string, Key extends Schema.Schema.Any, Payload extends Schema.Schema.Any>(ctx: EventPublishContext, descriptor: EventDescriptor<Name, Key, Payload>, key: Schema.Schema.Type<Key>, payload: Schema.Schema.Type<Payload>) => Effect.Effect<{
+    readonly n: number;
+    readonly deferred: boolean;
+}, EventPublishError>;
+
 /** A typed builder or its descriptor — the single-row terminals accept either,
  *  so a call site never has to reach for `.descriptor` just to use them. */
 export declare type QueryLike<R = Row_5> = QueryDescriptor<R> | {
@@ -4175,6 +4773,19 @@ export declare interface RecordedSample {
     readonly status: 'ok' | 'error';
 }
 
+/** `count` deliveries handed to subscribers of `event`. */
+export declare const recordEventDelivered: (event: string, count?: number) => void;
+
+/** `count` deliveries PROVABLY lost — `buffer` (a slow consumer) or `resume`
+ *  (a re-attach older than the ring). Never called with a guess. */
+export declare const recordEventDropped: (event: string, reason: "buffer" | "resume", count?: number) => void;
+
+/** One publish of `event`. */
+export declare const recordEventPublished: (event: string) => void;
+
+/** Subscriber attached (+1) or detached (-1). */
+export declare const recordEventSubscribers: (event: string, delta: number) => void;
+
 /**
  * Record one framework sample into the Effect metric registry. Synchronous —
  * metric updates are pure, so `runSync` is cheap and safe to call from the
@@ -4182,6 +4793,15 @@ export declare interface RecordedSample {
  */
 export declare const recordSample: (s: RecordedSample) => void;
 
+/**
+ * Record one schedule firing into the registry: the run counter (by name +
+ * status), the duration histogram, and — on success — the last-success gauge.
+ * Synchronous, like the other recorders (metric updates are pure). Called from
+ * the scheduler's success + failure arms so every cron in every app is covered
+ * without per-handler wiring.
+ */
+export declare const recordScheduleRun: (r: ScheduleRunRecord) => void;
+
 /** Move the live-subscriptions gauge for `label`'s tag by `delta` (+1 open, -1 close). */
 export declare const recordSubscriptionActive: (label: string, delta: number) => void;
 
@@ -4203,6 +4823,14 @@ export declare const recordTimelineEvent: (change: CdcChange & {
     readonly tenantId?: string | null;
 }) => void;
 
+/**
+ * Record one workflow run's terminal outcome: the run counter (by name + status),
+ * the duration histogram, and — on success — the last-success gauge. Synchronous,
+ * like the other recorders. Called from the workflow run-recording seam through an
+ * injected hook so `@voltro/workflow` keeps its no-`@voltro/runtime`-dep boundary.
+ */
+export declare const recordWorkflowRun: (r: WorkflowRunRecord) => void;
+
 /**
  * Strip `redact` columns from a set of rows. Exposed on its own so a hand-written
  * handler that isn't a plain CRUD read can still redact declaratively and be
@@ -4350,6 +4978,7 @@ export declare interface RegistryTableLike {
          * it. MariaDB/Postgres reject an explicit value, so the MutationStore
          * strips any the caller supplied before the INSERT reaches the dialect.
          */
+        readonly versionColumn?: boolean;
         readonly generatedAs?: {
             readonly expr: string;
             readonly stored: boolean;
@@ -4570,6 +5199,9 @@ export declare const resetComputedQueryCacheWarnings: () => void;
 /** Test/dev-only — clear ALL overrides. Don't call from app code. */
 export declare const _resetConnectionSubjectsForTest: () => void;
 
+/** Test seams for the tag-cache guard — the cache is module-private otherwise. */
+export declare const resetEventMetricTagCacheForTests: () => void;
+
 /** Drop everything recorded. For tests; not called by the runtime. */
 export declare const resetObservedGraph: () => void;
 
@@ -5340,7 +5972,20 @@ export declare interface ScheduleFireContext {
  */
 export declare type ScheduleFireInterceptor = (next: () => Promise<void>, ctx: ScheduleFireContext) => Promise<void>;
 
-export declare type ScheduleHandler = (ctx: ScheduleContext) => void | Promise<void>;
+/**
+ * A schedule body. Promise-form or Effect-form; both run.
+ *
+ * The Effect arm is not sugar. Before it existed the call site was
+ * `await def.handler(ctx)`, and an Effect is not a thenable — so `await`
+ * returned it unchanged, the body never executed, and the firing was recorded
+ * as a success. In an Effect-first framework the natural thing to write was the
+ * thing that silently did nothing. Same bridge a file-based migration's `up`
+ * has carried since it shipped.
+ *
+ * `R = never`: the effect must carry its own requirements. Everything a
+ * schedule needs is on `ctx.app`.
+ */
+export declare type ScheduleHandler = (ctx: ScheduleContext) => void | Promise<void> | Effect.Effect<unknown, unknown, never>;
 
 /** What happens when a firing arrives while the previous run of the
  *  same schedule is still in flight. */
@@ -5433,6 +6078,16 @@ export declare interface SchedulerLogger {
     debug?: (msg: string, fields?: Record<string, unknown>) => void;
 }
 
+export declare interface ScheduleRunRecord {
+    readonly name: string;
+    readonly status: 'succeeded' | 'failed' | 'skipped' | 'missed';
+    readonly durationMs: number;
+    /** UNIX SECONDS of completion — set only on a success (drives the last-success
+     *  gauge). Omit for a non-success; the gauge is deliberately not moved then, so
+     *  it keeps pointing at the last time the job actually worked. */
+    readonly completedAtSec?: number;
+}
+
 /** Trigger driver — `self` runs an in-app supervised timer; `external`
  *  exposes an HTTP endpoint that an outside scheduler (k8s CronJob,
  *  AWS EventBridge, GCP Cloud Scheduler, …) invokes. */
@@ -5461,6 +6116,8 @@ export declare interface SchemaInfo {
      * on every UPDATE against the merged post-update row.
      */
     readonly computedFields: ReadonlyMap<string, (row: Readonly<Record<string, unknown>>) => unknown>;
+    /** The column marked `.version()`, when the table declares one. */
+    readonly versionColumn?: string;
     /**
      * DB-generated columns (`generatedAs`). The MutationStore strips any
      * caller-supplied value for these before the INSERT — the engine computes
@@ -5510,6 +6167,10 @@ export declare interface SchemaRegistry {
     /** Convenience: `hasMixin(table, VOLTRO_AUDIT_MIXIN_ID)`. */
     hasAudit(table: string): boolean;
     hasSoftDelete(table: string): boolean;
+    /** True when the table carries `expires()`. Reads filter expired rows on
+     *  EVERY dialect from this flag — the postgres-only sweep is a separate,
+     *  optional half. */
+    hasExpires(table: string): boolean;
     hasTenant(table: string): boolean;
     /** Field-existence check — used to skip stamping a column that the
      *  table doesn't actually declare (extra defensive). */
@@ -5537,6 +6198,14 @@ export declare interface SchemaRegistry {
      * overwrites whatever the caller passed for that column.
      */
     computedFields(table: string): ReadonlyMap<string, (row: Readonly<Record<string, unknown>>) => unknown>;
+    /**
+     * The table's optimistic-concurrency column, or `undefined`.
+     *
+     * Resolved ONCE at registration rather than scanned per write: an update is
+     * the hot path, and a per-write `Object.entries` over every column of every
+     * table is the kind of cost that only shows up under load.
+     */
+    versionColumn(table: string): string | undefined;
     /**
      * DB-generated columns (`generatedAs`) for a table. Empty set if none.
      * Read by MutationStore.stampedForInsert to STRIP any caller-supplied
@@ -5698,6 +6367,14 @@ export declare const setSystemStoreHandle: (handle: SystemStoreHandle) => void;
 /** Test seam — swap (or reset with `undefined`) the process recorder. */
 export declare const setTimelineRecorderForTest: (recorder: TimelineRecorder | undefined) => void;
 
+/**
+ * Normalise a handler's return value to "a promise, or nothing to wait for".
+ *
+ * `undefined` means the body was synchronous and has already run. Anything else
+ * is a promise the caller disposes of as its context requires.
+ */
+export declare const settleHandlerBody: (body: HandlerBody) => Promise<unknown> | undefined;
+
 /**
  * Register (or clear) the process-global tuple source. Last write wins.
  *
@@ -5716,6 +6393,18 @@ export declare type ShapeClassification = {
     readonly reason: string;
 };
 
+/**
+ * The teardown deadline, from `VOLTRO_SHUTDOWN_GRACE_MS` (milliseconds), clamped
+ * to `[1s, 5min]`. Operators set it to sit JUST UNDER their orchestrator's hard
+ * kill — k8s `terminationGracePeriodSeconds`, ECS `stopTimeout` — so the process
+ * drains in-flight work and exits cleanly on its own BEFORE SIGKILL truncates it
+ * mid-drain (which would strand exactly the finalizers this path exists to run:
+ * connection-pool close, plugin `onDeactivate`, analytics flush, trace persist).
+ * A non-numeric / non-positive value falls back to the 10s default rather than
+ * producing a `setTimeout(…, NaN)` that fires immediately and defeats the drain.
+ */
+export declare const shutdownGraceMsFromEnv: () => number;
+
 /** No-coordination gate for single-instance deployments (PM2,
  *  single pod, dev). */
 export declare const singleCoordinator: Coordinator;
@@ -5967,13 +6656,44 @@ export declare interface SubscribeContext {
      * workflow" belongs in a `*.reaction.tsx`, whose `act` is crash-safe.
      */
     readonly store: FluentStore;
+    /**
+     * Publish a declared event from a table change — the bridge between the two
+     * axes.
+     *
+     * A row changing and a thing happening are not the same statement, and most
+     * of the time only one of them is what a client cares about: nobody watches
+     * `attendance` rows, they watch "attendance changed". Without this, an app
+     * with a table-derived event has to publish from every mutation that touches
+     * the table and remember to do it in the next one too — which is the
+     * fail-open-by-omission shape a declaration exists to remove.
+     *
+     * Present only when the app declares at least one `defineEvent`, so reaching
+     * for it in an app with none is a type error rather than a runtime undefined.
+     *
+     * BEST-EFFORT, like everything else in a subscriber: this fires AFTER the
+     * commit, so there is no transaction to couple to and a failed publish cannot
+     * roll anything back. If the event must not be lost, publish it from the
+     * mutation instead — there it rides the commit.
+     */
+    readonly publish?: EventPublisher['publish'];
 }
 
 /** Event shape passed to a subscriber handler. Same as the
  *  framework's CDC `ChangeEvent` re-exported for ergonomics. */
 export declare type SubscribeEvent = ChangeEvent;
 
-export declare type SubscribeHandler = (event: SubscribeEvent, ctx: SubscribeContext) => void | Promise<void>;
+/**
+ * A subscriber body. Promise-form or Effect-form; both run.
+ *
+ * The Effect arm is not sugar — see `ScheduleHandler`. The runner tested
+ * `result instanceof Promise`, an Effect is not one, so the branch was skipped
+ * and the body never executed. No error, no log line, the change event handled
+ * "successfully".
+ *
+ * `R = never`: the effect must carry its own requirements. Everything a
+ * subscriber needs is on `ctx`.
+ */
+export declare type SubscribeHandler = (event: SubscribeEvent, ctx: SubscribeContext) => void | Promise<void> | Effect.Effect<unknown, unknown, never>;
 
 /** Which row op(s) the subscriber listens on. `'any'` matches every
  *  op; an array enumerates the concrete ops. */
@@ -6383,7 +7103,36 @@ export declare interface TransactionalStore {
     transactional<T>(work: (tx: unknown) => Promise<T>): Promise<T>;
 }
 
-export declare const triggerWorkflow: <EventPayload = unknown, WorkflowPayload = EventPayload>(spec: Omit<WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>, "_tag">) => WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>;
+/**
+ * Declare a workflow trigger.
+ *
+ * TWO forms, and the descriptor one is the one to use:
+ *
+ * ```ts
+ * triggerWorkflow({ on: gameStarted, workflow: 'postGameReport' })   // typed
+ * triggerWorkflow({ event: 'games.started', workflow: 'postGameReport' })  // string
+ * ```
+ *
+ * `on:` takes a `defineEvent` descriptor and reads its NAME, so the trigger and
+ * the producer cannot drift: rename the event and this call site moves with it,
+ * where the string form silently stops matching and the workflow simply never
+ * runs again. That failure is exactly what a consumer reported having with their
+ * own string channels — `on-game-scores` beside `games/evo5/on-game-scores`,
+ * both live, one dead since the day it was written — and it is the reason the
+ * string form is going away rather than being kept as an alternative.
+ *
+ * It is ADDITIVE today on purpose. Shipping the descriptor form with the event
+ * primitive means a third string namespace never comes into existence even
+ * briefly; removing the string form is a separate, breaking change with its own
+ * codemod, and nothing here has to be undone for it.
+ */
+export declare const triggerWorkflow: <EventPayload = unknown, WorkflowPayload = EventPayload>(spec: Omit<WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>, "_tag"> | (Omit<WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>, "_tag" | "event"> & {
+    /** A declared event. Its `name` becomes the matched event. */
+    readonly on: {
+        readonly kind: "event";
+        readonly name: string;
+    };
+})) => WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>;
 
 /**
  * Atomically claim a pending wakeup for waking — CAS `pending → fired`.
@@ -6572,6 +7321,11 @@ export declare const visibleRows: <Row extends {
  */
 export declare const VOLTRO_AUDIT_MIXIN_ID: "voltro/audit";
 
+/** Re-declared here for the same reason the soft-delete id is: the registry
+ *  must not import the mixin (which pulls its column builders into every
+ *  consumer). Kept in step by `expiresMixinId.test.ts`. */
+export declare const VOLTRO_EXPIRES_MIXIN_ID: "voltro/expires";
+
 export declare const VOLTRO_SOFT_DELETE_MIXIN_ID: "voltro/softDelete";
 
 export declare const VOLTRO_TENANT_MIXIN_ID: "voltro/tenant";
@@ -6924,6 +7678,16 @@ export declare interface WorkflowRunOptions {
     /* Excluded from this release type: callerContext */
 }
 
+export declare interface WorkflowRunRecord {
+    readonly name: string;
+    /** Terminal outcome only. `failed` is the dead-letter state (no framework retry). */
+    readonly status: 'succeeded' | 'failed';
+    readonly durationMs: number;
+    /** UNIX SECONDS of completion — set only on success (drives the last-success
+     *  gauge). Omit on failure so the gauge keeps pointing at the last real success. */
+    readonly completedAtSec?: number;
+}
+
 /** Persisted run lifecycle states recorded in `_voltro_workflow_runs`.
  *  Distinct from {@link WorkflowRunStatus} (which is derived from a live
  *  engine poll and carries `succeeded`/`unknown`); this enum matches the