@voltro/runtime 0.85.0 → 0.86.0

package/dist/idleDetector.js

@@ -0,0 +1,21 @@
+import { nextWakeup as e } from "./wakeRegistry.js";
+//#region src/idleDetector.ts
+var t = async (t) => {
+	if (t.signals.connectedClients() > 0 || t.signals.inFlightRequests() > 0 || t.signals.activeWorkflowExecutions() > 0) return !1;
+	let n = (t.now?.() ?? /* @__PURE__ */ new Date()).getTime() + (t.wakeLookaheadMs ?? 3e4), r = await e(t.store);
+	return !(r !== null && r.wakeAt.getTime() <= n);
+}, n = (e, t = Date.now) => {
+	let n;
+	return {
+		update: (r) => {
+			if (!r) return n = void 0, !1;
+			let i = t();
+			return n === void 0 && (n = i), i - n >= e;
+		},
+		reset: () => {
+			n = void 0;
+		}
+	};
+};
+//#endregion
+export { t as isIdleNow, n as makeIdleGate };

package/dist/index.d.ts

@@ -30,6 +30,7 @@ import { DialectReplicationAdapter } from '@voltro/database';
 import { Duplex } from 'node:stream';
 import { Duration } from 'effect';
 import { Effect } from 'effect';
+import { EnqueueOptions } from '@voltro/protocol';
 import { EventDeliverySemantics } from '@voltro/protocol';
 import { EventDescriptor } from '@voltro/protocol';
 import { EventKeyInvalid } from '@voltro/protocol';
@@ -71,6 +72,9 @@ import { MetricReader } from '@opentelemetry/sdk-metrics';
 import { MutationIdempotencyScope } from '@voltro/protocol';
 import { NoRowFound } from '@voltro/protocol';
 import { NoSuchResource } from '@voltro/protocol';
+import { OutboxEnqueueFacade } from '@voltro/protocol';
+import { OutboxHandlerContext } from '@voltro/protocol';
+import { OutboxHandlerDefinition } from '@voltro/protocol';
 import { PendingApproval } from '@voltro/protocol';
 import { PluginHttpRoute } from '@voltro/protocol';
 import { PluginHttpRouteByteStream } from '@voltro/protocol';
@@ -82,6 +86,7 @@ import { Query } from '@voltro/database';
 import { QueryDescriptor } from '@voltro/database';
 import { Redis } from 'ioredis';
 import { registerRetention } from '@voltro/database';
+import { RequestedTenantRefused } from '@voltro/protocol';
 import { ResourceMissing } from '@voltro/protocol';
 import { RestRouteDescriptor } from '@voltro/protocol/rest';
 import { RetentionConflict } from '@voltro/database';
@@ -167,6 +172,7 @@ declare const AccessDenied_base: Schema.Class<AccessDenied, Schema.TaggedStruct<
 export declare const actingUserId: (subject: StoreMiddlewareContext["subject"]) => string | null;
 
 export declare interface ActionRunnerDeps {
+    readonly outcomeOutbox?: MutationRunnerDeps['outcomeOutbox'];
     /** Build the per-call `AppContext` — NO transactional tx (actions do
      *  external I/O and run outside a txn deliberately). */
     readonly buildContext: (request: ServeRequestContext) => {
@@ -500,15 +506,9 @@ export declare interface AggregateReadOptions {
  *   - Interval string (`'5m'`, `'1h'`, `'24h'`): the canonical
  *     simple case.
  *   - Cron expression `{ cron: '0 2 * * *', timezone: 'UTC' }`: for
- *     business-hours / off-peak refresh windows. **Defer to v2** —
- *     emitted from the spec but not yet honoured by the runner.
+ *     business-hours / off-peak refresh windows, in the specified timezone.
  *   - On-change debounced `{ interval: '1h', onChange: ['matches'],
- *     debounceMs: 30_000 }`: near-realtime, source-table-driven. **Defer
- *     to v2** — same status.
- *
- * v1 supports interval only. The other shapes are accepted so consumers
- * can declare them today + see them honoured when v2 lands without
- * touching the spec.
+ *     debounceMs: 30_000 }`: near-realtime, source-table-driven.
  */
 export declare type AggregateRefreshPolicy = string | {
     readonly interval?: string;
@@ -1112,7 +1112,9 @@ export declare interface AppAccess {
     readonly hasAny: (scopes: ReadonlyArray<string>) => boolean;
     /** Effect guard — fails with a typed `ScopeError` when the caller lacks
      *  `scope`. `yield* ctx.access.require('notes:write')` at the top of a
-     *  handler mirrors a descriptor `guards:` entry for in-body branching. */
+     *  handler mirrors a descriptor `guards:` entry for in-body branching.
+     *  Reauthenticates bound authority when the Effect executes. Authentication
+     *  or authority-source failures abort rather than becoming scope decisions. */
     readonly require: (scope: string) => Effect.Effect<void, ScopeError>;
     /** The caller's effective scope set (live — reflects rbac resolution). */
     readonly scopes: ReadonlyArray<string>;
@@ -1798,7 +1800,7 @@ export declare const bindConnectionCredential: (clientId: number, credential: Co
  * 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 | Unauthenticated | NoSuchResource, SubjectService | ConnectionInfo>;
+export declare const bindEvent: (input: BindEventInput) => Stream.Stream<EventStreamEvent<unknown>, ScopeError | Unauthenticated | RequestedTenantRefused | NoSuchResource, SubjectService | ConnectionInfo>;
 
 export declare interface BindEventInput {
     readonly bus: EventBus;
@@ -2130,6 +2132,8 @@ export declare const canonicalInputKey: (input: unknown) => string;
  * Canonical JSON — object keys sorted recursively, so two structurally equal
  * inputs that differ only in key order digest identically. A retry from a
  * different client build must not mint a second approval.
+ * Preserve own JSON fields such as `__proto__`; a prototype setter must never
+ * discard part of the content that an approval identity binds.
  */
 export declare const canonicalJson: (value: unknown) => string;
 
@@ -4056,6 +4060,9 @@ export declare class Dispatcher {
      * grant comes back.
      */
     private revokeSubscription;
+    /** Remove once, including a pending retry and its active metric. In-flight
+     *  async reads check identity again before emitting or scheduling anything. */
+    private removeComputed;
     /** `revokeSubscription` for the computed path. Same reasoning. */
     private revokeComputed;
     /**
@@ -4066,13 +4073,10 @@ export declare class Dispatcher {
      * Returns an `unsubscribe` the caller MUST invoke on teardown.
      */
     subscribeComputed(computed: ComputedQuery, emit: (event: SubscriptionEvent<unknown>) => void, context: RuntimeContext, label?: string): Promise<() => void>;
-    /** Re-run a computed subscription's handler; emit a fresh snapshot iff
-     *  the value changed. A computed value is an arbitrary payload (a scalar,
-     *  an aggregate object, a non-id-keyed array) — it has no id-keyed row
-     *  set to diff, so an update ships the full value as a `snapshot`, which
-     *  the client materialises as a wholesale base replacement. Best-effort:
-     *  a recompute throw is logged, not propagated, so one failing query
-     *  can't wedge the change stream. */
+    /** Serialize computed reads. A source change during a pending read asks for
+     *  one more read before delivery; an older result cannot overtake newer data.
+     *  Ordinary failures are visible in-band and retry independently of changes.
+     *  Access withdrawal stays terminal and never enters the retry lane. */
     private recomputeComputed;
     /** Live snapshot of all fingerprinted subscriptions — used by the
      *  `/_voltro/inspect/subscriptions` endpoint and DevTools. */
@@ -4235,7 +4239,7 @@ export declare interface DrainResult {
     readonly dead: number;
     readonly skipped: number;
     /**
-     * How many rows this pass had to look at. `0` means the queue is EMPTY, which
+     * How many rows this pass had to look at. `0` means the eligible queue is EMPTY, which
      * a caller cannot otherwise tell from "everything delivered" — both leave
      * `delivered` at whatever it was, and only one of them means the poll has
      * nothing left to do.
@@ -4429,14 +4433,7 @@ export declare const enforceApproval: (input: {
     readonly traceId?: string | undefined;
 }) => Promise<void>;
 
-export declare interface EnqueueOptions {
-    /** Drop this enqueue if an undelivered row already carries the same key. */
-    readonly idempotencyKey?: string;
-    /** Override the handler's `maxAttempts` for this one effect. */
-    readonly maxAttempts?: number;
-    /** Delay the first attempt (ms from now). */
-    readonly delayMs?: number;
-}
+export { EnqueueOptions }
 
 /**
  * Attribute the reads that FOLLOW, in this execution context, to `procedure`.
@@ -6728,9 +6725,9 @@ export declare const makeAsyncKv: ({ store, env }: KvFacadeOptions) => Promise<K
  *     (a no-op for a connection that never re-authenticated);
  *  2. run the FULL chain on the result — strategies, session revocation,
  *     `resolveScopes`, the scope cache;
- *  3. record what the strategy verified about the credential's lifetime, so
- *     `ConnectionInfo.credentialExpiresAt` reports the token's own `exp` rather
- *     than a cookie derivation that only ever saw one auth shape.
+ *  3. pass the verified lifetime through call-local Effect context, so parallel
+ *     calls and explicitly unbounded credentials cannot inherit another call's
+ *     expiry. Compose the group's pair with `withRpcAuthMiddleware`.
  *
  * Step 1 is the only thing a re-authenticated connection gets. It changes WHICH
  * credential is presented and nothing about how it is judged.
@@ -6965,16 +6962,13 @@ export declare const makeQueryFinalizer: (options: QueryFinalizeOptions) => ((de
  * the socket keeps delivering rows the subject may no longer read until
  * the client happens to disconnect.
  *
- * So every delivery re-runs the same `checkGuardsEffect` the subscribe-time
- * gate ran — including the async resource-scope resolver, which is where a
- * per-row/per-team revocation actually shows up. Returns `null` when the
- * subject still passes, or the typed `ScopeError` that denied it.
- *
- * Returns a closure that always resolves `null` when the descriptor carries
- * no guards AND default-deny is off, so the caller needs no branch and an
- * unguarded query pays only a resolved promise. Under `defaultDeny` an
- * UNDECIDED descriptor resolves the same typed refusal on every delivery —
- * fail closed on the re-check too, not only at subscribe.
+ * Each delivery refreshes the original authentication chain, subject guards,
+ * dynamic role grants, and resource guards before emitting data. Configured
+ * authentication/scope caches retain their documented invalidation windows.
+ * A revoked credential or grant ends the subscription with a typed refusal.
+ * The original principal and tenant remain fixed; changing either requires a
+ * new subscription. Even unguarded descriptors refresh authentication, while
+ * default-deny keeps rejecting descriptors without a declared access policy.
  */
 export declare const makeQueryReauthorizer: (query: MutationLike, input: unknown, defaultDeny?: boolean) => (subject: Subject) => () => Promise<unknown>;
 
@@ -7462,6 +7456,10 @@ export declare interface MutationOutputCodec<Output> {
 }
 
 export declare interface MutationRunnerDeps {
+    readonly outcomeOutbox?: (request: ServeRequestContext) => OutboxEnqueueFacade | undefined;
+    /** A failure aborts the business transaction; transient contention replays
+     * executor and hook together. Never perform external I/O here. */
+    readonly beforeMutationCommit?: ServeMutationCommitHook | undefined;
     readonly store: TransactionalStore;
     /** Select and provision the request's physical store before opening its
      * transaction. Resolved once, including across retries and post-commit folds. */
@@ -7484,6 +7482,7 @@ export declare interface MutationRunnerDeps {
     /** Build the per-call `AppContext` bound to the transactional `tx`. */
     readonly buildContext: (request: ServeRequestContext, tx: unknown, lifecycle?: MutationLifecycle) => {
         readonly store: unknown;
+        readonly outbox?: OutboxEnqueueFacade;
     };
     /** Run an Effect-returning executor with the per-request store layer. */
     readonly runEffect: (effect: Effect.Effect<unknown, unknown, never>, store: unknown) => Promise<unknown>;
@@ -8013,14 +8012,14 @@ export declare const outboxAttemptsTable: TableLike;
  *  twice because of us or because of them" becomes unanswerable. */
 export declare type OutboxAttemptTrigger = 'automatic' | 'manual';
 
-export declare interface OutboxFacade {
-    /**
-     * Persist the intent to run `effect` after this transaction commits.
-     *
-     * Returns the outbox row id, which doubles as the delivery id a client can
-     * watch to render external-side-effect progress ("saving… syncing… synced").
-     */
-    enqueue(effect: string, payload: Record<string, unknown>, options?: EnqueueOptions): Promise<string>;
+/** Declared-event publication for an outbox attempt, scoped to its queued tenant.
+ * This service provides no request subject or store access. */
+export declare class OutboxEventPublisher extends OutboxEventPublisher_base {
+}
+
+declare const OutboxEventPublisher_base: Context.ServiceClass<OutboxEventPublisher, "@voltro/OutboxEventPublisher", EventPublisher>;
+
+export declare interface OutboxFacade extends OutboxEnqueueFacade {
     /**
      * Re-arm one entry for delivery NOW, on purpose, attributed to the caller.
      *
@@ -8065,25 +8064,9 @@ export declare interface OutboxFacadeDeps {
     readonly now?: () => Date;
 }
 
-export declare interface OutboxHandlerContext {
-    /** Stable identity of this delivery intent, preserved across retries. */
-    readonly outboxId: string;
-    /** Caller-supplied enqueue key, or null. Unlike outboxId this can be reused
-     * for a distinct intent after an earlier intent has been delivered. */
-    readonly idempotencyKey: string | null;
-    readonly payload: Record<string, unknown>;
-    readonly attempt: number;
-    readonly subjectId: string | null;
-    readonly tenantId: string | null;
-    readonly traceId: string | null;
-}
+export { OutboxHandlerContext }
 
-export declare interface OutboxHandlerDefinition<R = never> {
-    readonly effect: string;
-    readonly handler: (ctx: OutboxHandlerContext) => Promise<unknown> | Effect.Effect<unknown, unknown, R>;
-    /** Give up after this many attempts, then dead-letter. Default 8. */
-    readonly maxAttempts?: number;
-}
+export { OutboxHandlerDefinition }
 
 /** What the pump hands events to — the `emit` of a `Stream.asyncScoped`. */
 export declare interface OutboxSink<T> {
@@ -9720,7 +9703,9 @@ export declare interface ResolvedDevice {
  * Walk a query descriptor's eager-load tree and return the FULL set
  * of tables whose changes could affect the resolved snapshot.
  *
- * - For a query without `eager`, returns just `{ descriptor.table }`.
+ * - Includes explicitly declared invalidation sources (`dependentTables`),
+ *   independently of SQL predicates and projections.
+ * - A plain query with no additional sources returns `{ descriptor.table }`.
  * - For each one()/many() relation, adds the target table.
  * - For each manyToMany() relation, adds the through-table AND the
  *   target table (writes to either can shift the resolved set).
@@ -11511,6 +11496,16 @@ export declare type SerializedGuard = {
  */
 export declare const serializeGuards: (guards: ReadonlyArray<AnyGuardSpec>, input: unknown) => ReadonlyArray<SerializedGuard>;
 
+/** Required plugin work executed on the actual transaction connection. */
+export declare type ServeMutationCommitHook = (context: Parameters<ServeRpcInterceptor>[1] & {
+    readonly kind: 'mutation';
+    readonly store: DataStore;
+    readonly output: unknown;
+    readonly outbox?: OutboxEnqueueFacade;
+    readonly startedAt?: number;
+    readonly durationMs?: number;
+}) => Effect.Effect<void, unknown>;
+
 export declare interface ServeRequestContext {
     readonly subject: unknown;
     readonly traceId: string;
@@ -11574,6 +11569,7 @@ export declare type ServeRpcInterceptor = (base: Effect.Effect<unknown, unknown,
     readonly input: unknown;
     readonly subject: unknown;
     readonly traceId: string;
+    readonly enqueueOutcome?: OutboxEnqueueFacade['enqueue'];
     readonly spanId?: string;
     /**
      * The declared write-target TABLE names of this mutation/action, derived
@@ -13341,6 +13337,14 @@ export declare type WhereOp = '=' | '!=' | '<>' | '>' | '>=' | '<' | '<=' | 'in'
 
 export declare const withRowFilter: <R extends ServeRequestContext>(request: R) => Promise<R>;
 
+/**
+ * Add the shared RPC auth pair once to an undecorated group. Authentication
+ * runs before ConnectionInfo captures this call's verified credential lifetime.
+ * Groups already carrying either middleware are refused: Effect preserves Set
+ * insertion order, so appending a duplicate cannot repair an existing order.
+ */
+export declare const withRpcAuthMiddleware: <R extends Rpc.Any>(group: RpcGroup.RpcGroup<R>) => RpcGroup.RpcGroup<Rpc.AddMiddleware<Rpc.AddMiddleware<R, typeof ConnectionInfoMiddleware>, typeof AuthMiddleware>>;
+
 /**
  * Run `body` against a request that carries a resolved row-filter scope.
  *
@@ -13511,6 +13515,15 @@ export declare interface WorkflowEventTriggerResult {
     readonly reason?: string;
 }
 
+export declare interface WorkflowExecutionRefusal {
+    readonly workflowName: string;
+    readonly executionId: string;
+    readonly payload: unknown;
+    readonly cause: Cause.Cause<unknown>;
+    /** Restored identity and host-owned placement; no resolved permissions. */
+    readonly callerContext: WorkflowCallerContext;
+}
+
 export declare interface WorkflowFacadeOptions {
     readonly cancelQueued?: (input: WorkflowQueuedControlTarget & {
         readonly callerContext: WorkflowCallerContext | undefined;
@@ -13652,13 +13665,18 @@ export declare interface WorkflowLayerOptions<Context> {
      * whose business logic said no.
      */
     readonly resolveAuthority?: (identity: unknown) => Promise<unknown>;
+    /** Record a known caller's refusal through the host's ordinary resident run
+     * recorder. Called before application context/body construction. The failed
+     * attempt stays failed, even if this hook completes successfully. Missing
+     * caller identity cannot fabricate a tenant or a first-run record. */
+    readonly onExecutionRefusal?: (refusal: WorkflowExecutionRefusal) => Effect.Effect<unknown, unknown, unknown>;
     /**
      * Told when an execution is refused BEFORE its body — the start context
      * could not be resolved, the identity was missing, the authority or row
      * filter resolver rejected. The engine already fails the attempt; what a
-     * discarded start does NOT do is tell anyone, and a run refused here has no
-     * row yet, so nothing else can. Measured: an acknowledged start whose
-     * resident context was filed under another id died with a debug-level
+     * discarded start does NOT do is tell anyone. A first start may have no
+     * row yet; a resumed run may still have a running row. Measured: an
+     * acknowledged start whose resident context was filed under another id died with a debug-level
      * "Fiber terminated" and nothing else. Hosts wire this to an error log.
      */
     readonly reportExecutionRefusal?: (refusal: {
@@ -14037,6 +14055,7 @@ export declare interface WorkflowStartOptions {
 }
 
 export declare interface WorkflowStartRunnerDeps {
+    readonly outcomeOutbox?: MutationRunnerDeps['outcomeOutbox'];
     /** Composed plugin workflow-interceptor (`interceptWorkflow`). */
     readonly interceptor?: ServeRpcInterceptor;
     readonly recordMetric?: MutationRunnerDeps['recordMetric'];