@voltro/runtime 0.20.2 → 0.22.0

package/THIRD-PARTY-NOTICES.md

@@ -9,7 +9,7 @@ Generated from the resolved runtime dependency closure (49 packages).
 
 ---
 
-## @effect/cluster@0.59.0
+## @effect/cluster@0.60.0
 
 License: MIT
 
@@ -37,7 +37,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## @effect/opentelemetry@0.63.0
+## @effect/opentelemetry@0.64.0
 
 License: MIT
 
@@ -65,7 +65,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## @effect/platform-node@0.107.0
+## @effect/platform-node@0.108.0
 
 License: MIT
 
@@ -93,7 +93,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## @effect/platform-node-shared@0.60.0
+## @effect/platform-node-shared@0.61.0
 
 License: MIT
 
@@ -121,7 +121,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## @effect/sql@0.51.1
+## @effect/sql@0.52.0
 
 License: MIT
 
@@ -149,7 +149,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## @effect/workflow@0.18.2
+## @effect/workflow@0.19.0
 
 License: MIT
 
@@ -414,7 +414,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/api-logs@0.220.0
+## @opentelemetry/api-logs@0.221.0
 
 License: Apache-2.0
 
@@ -622,7 +622,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/context-async-hooks@2.9.0
+## @opentelemetry/context-async-hooks@2.10.0
 
 License: Apache-2.0
 
@@ -1038,7 +1038,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/exporter-metrics-otlp-http@0.220.0
+## @opentelemetry/exporter-metrics-otlp-http@0.221.0
 
 License: Apache-2.0
 
@@ -1246,7 +1246,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/exporter-trace-otlp-http@0.220.0
+## @opentelemetry/exporter-trace-otlp-http@0.221.0
 
 License: Apache-2.0
 
@@ -1454,7 +1454,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/otlp-exporter-base@0.220.0
+## @opentelemetry/otlp-exporter-base@0.221.0
 
 License: Apache-2.0
 
@@ -1662,7 +1662,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/otlp-transformer@0.220.0
+## @opentelemetry/otlp-transformer@0.221.0
 
 License: Apache-2.0
 
@@ -1870,7 +1870,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/resources@2.9.0
+## @opentelemetry/resources@2.10.0
 
 License: Apache-2.0
 
@@ -2078,7 +2078,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/sdk-logs@0.220.0
+## @opentelemetry/sdk-logs@0.221.0
 
 License: Apache-2.0
 
@@ -2286,7 +2286,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/sdk-metrics@2.9.0
+## @opentelemetry/sdk-metrics@2.10.0
 
 License: Apache-2.0
 
@@ -2494,7 +2494,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/sdk-trace@2.9.0
+## @opentelemetry/sdk-trace@2.10.0
 
 License: Apache-2.0
 
@@ -2702,7 +2702,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/sdk-trace-base@2.9.0
+## @opentelemetry/sdk-trace-base@2.10.0
 
 License: Apache-2.0
 
@@ -2910,7 +2910,7 @@ Apache License
    limitations under the License.
 ```
 
-## @opentelemetry/sdk-trace-node@2.9.0
+## @opentelemetry/sdk-trace-node@2.10.0
 
 License: Apache-2.0
 
@@ -3956,7 +3956,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
-## jose@6.2.3
+## jose@6.2.4
 
 License: MIT
 
@@ -4495,7 +4495,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## undici@7.28.0
+## undici@8.9.0
 
 License: MIT
 

package/dist/index.d.ts

@@ -14,6 +14,7 @@ import { DialectId } from '@voltro/database';
 import { DialectReplicationAdapter } from '@voltro/database';
 import { Duration } from 'effect';
 import { Effect } from 'effect';
+import { Fiber } from 'effect';
 import { FieldCipher } from '@voltro/database';
 import * as http from 'node:http';
 import { HttpClient } from '@effect/platform';
@@ -1165,7 +1166,7 @@ resolveIndexHint?: (descriptor: QueryDescriptor) => MatcherIndexHint | undefined
 cache?: {
     readonly ttlMs: number;
     readonly swrMs: number | undefined;
-    readonly scope: "subject" | "global";
+    readonly scope: "subject" | "tenant" | "global";
     readonly baseKey: string;
 }, 
 /**
@@ -1253,6 +1254,39 @@ export declare const buildTracingLayer: (options?: TracingOptions) => Promise<Tr
  *  hit on every read. `now` injectable for tests. */
 export declare const cachedBackend: (backend: SecretsBackend, ttlMs?: number, now?: () => number) => SecretsBackend;
 
+/** One leak: a query caching ONE entry across every caller while reading a
+ *  table whose rows are scoped per tenant. */
+export declare interface CacheScopeLeak {
+    readonly query: string;
+    readonly table: string;
+}
+
+/**
+ * Queries that declare `cache: { scope: 'global' }` while reading a
+ * `tenant()`-scoped table.
+ *
+ * `'global'` shares ONE cache entry across every caller. On a table whose rows
+ * are filtered by the caller's tenant, that is not a cache — it is one org
+ * serving another org's rows out of memory, with a TTL. The author has to be
+ * wrong exactly once, in a field whose two legal values differ by one word.
+ *
+ * A consumer named this precisely while asking for the third option: *"'global'
+ * would share across tenant boundaries. For data derived from
+ * `subject.tenantId` that is not a cache, it is a leak."* They chose to
+ * recompute an org-wide figure once per employee rather than write it — the
+ * right call, and not one the framework should have left to judgement when it
+ * already knows which tables carry `tenant()`.
+ *
+ * `'tenant'` is the option that makes this avoidable; this is the check that
+ * makes it enforced. Both halves, or the correct choice stays a matter of
+ * remembering.
+ */
+export declare const cacheScopeLeaks: (query: AuditableQuery & {
+    readonly cache?: {
+        readonly scope?: string;
+    } | undefined;
+}, tenantScopedTables: ReadonlySet<string>) => ReadonlyArray<CacheScopeLeak>;
+
 /**
  * `can(subject, action, resource)` — the authorization decision. FAILS CLOSED:
  *  - `admin:full` scope → allow (the only bypass).
@@ -1790,6 +1824,17 @@ export declare interface CrudWriteOptions {
     readonly redact?: ReadonlyArray<string>;
 }
 
+/**
+ * The current request's loader, or `undefined` outside a request.
+ *
+ * `undefined` is a real answer and must stay one: a boot seed, a schedule tick
+ * or a plugin's startup hook has no request and therefore no shared cache. A
+ * consumer reading this must fall back to its own query rather than assume, and
+ * inventing a loader here would give background code a cache with no defined
+ * lifetime.
+ */
+export declare const currentRequestLoader: () => DataLoader | undefined;
+
 /** Read the active context, if any. Tests use this to validate the
  *  propagation; production code uses it only inside this module. */
 export declare const currentRoutingContext: () => RoutingContext | undefined;
@@ -2105,6 +2150,28 @@ export declare interface DrainDeps {
     readonly attemptLogCap?: number;
 }
 
+/**
+ * Run the registered hooks, drain the live launches, then `exit()` — under a
+ * hard deadline.
+ *
+ * The deadline is the point. Interrupting a launch waits for its finalizers,
+ * and a finalizer that never completes (a pool drain against a gone database, a
+ * wedged plugin `onDeactivate`, a redis `quit` on a dead socket) used to mean
+ * the process never exited — while ALSO having lost node's default SIGTERM
+ * kill, which installing a listener removes. The result was a server that
+ * ignores SIGTERM outright. Under `voltro dev` that wedged the supervisor with
+ * it, and the only recovery was killing the tree by hand.
+ *
+ * Exported for the test: this is a race against a hang, so the assertion has to
+ * inject `exit` and drive a finalizer that genuinely never finishes.
+ */
+export declare const drainForShutdown: (options: {
+    readonly fibers: ReadonlyArray<Fiber.RuntimeFiber<void, unknown>>;
+    readonly hooks: ReadonlyArray<() => void | Promise<void>>;
+    readonly deadlineMs: number;
+    readonly exit: () => void;
+}) => void;
+
 /**
  * One drain pass: claim due rows, run their handler, record the outcome.
  *
@@ -2173,6 +2240,16 @@ export declare interface EnqueueOptions {
     readonly delayMs?: number;
 }
 
+/**
+ * Make `loader` the current request's loader for the rest of this execution
+ * context.
+ *
+ * Called once per request, from `makeAppContextBuilder`, immediately after the
+ * loader is constructed — so anything the request reaches afterwards shares the
+ * cache the executor will use.
+ */
+export declare const enterRequestLoader: (loader: DataLoader) => void;
+
 /** The always-available default — reads `process.env`. Sync under the hood,
  *  Promise-wrapped to satisfy the async contract. */
 export declare const envSecretsBackend: SecretsBackend;
@@ -2335,6 +2412,9 @@ export declare interface FluentStoreBackend {
 /** Forget the calling subject's credential. Returns whether a row was removed. */
 export declare const forgetCredential: (store: VaultStore, connectionId: string, subjectId: string) => Promise<boolean>;
 
+/** A boot-ready message for a set of cache-scope leaks (empty → `undefined`). */
+export declare const formatCacheScopeLeaks: (leaks: ReadonlyArray<CacheScopeLeak>) => string | undefined;
+
 /** A boot-ready message for a set of leaks (empty → `undefined`, i.e. clean). */
 export declare const formatServerOnlyLeaks: (leaks: ReadonlyArray<ServerOnlyLeak>) => string | undefined;
 
@@ -3599,6 +3679,19 @@ export declare interface OneShotQueryRunnerDeps<D> extends QueryProducerDeps<D>
     readonly queryRows: (descriptor: D) => Promise<ReadonlyArray<unknown>>;
 }
 
+/**
+ * Register teardown to run on SIGINT/SIGTERM, before the launches are drained
+ * and the process exits. Returns a de-register function.
+ *
+ * This exists because `process.on('beforeExit')` cannot do the job and reads as
+ * if it can: `beforeExit` is not emitted when something calls `process.exit()`,
+ * which is exactly how a signalled process ends — so a hook registered there
+ * runs on a naturally-draining event loop and NEVER on the signal. A long-lived
+ * server never drains naturally, so in practice it never ran at all. Eleven of
+ * `voltro dev`'s teardowns sat there, including the CDC detach.
+ */
+export declare const onProcessShutdown: (hook: () => void | Promise<void>) => (() => void);
+
 /** Thrown by `.expectVersion(n).set(...)` when the optimistic-lock guard
  *  matched no row (the row was concurrently updated or deleted). */
 export declare class OptimisticLockError extends OptimisticLockError_base {
@@ -5037,6 +5130,14 @@ export declare const runWithDeadlockRetry: <T>(work: () => Promise<T>, options?:
  */
 export declare const runWithObservedProcedure: <T>(procedure: ObservedProcedure, work: () => T) => T;
 
+/**
+ * Run `fn` with `loader` current, restoring whatever was current before.
+ *
+ * The wrapping form, for callers that HAVE a callback — tests, and any future
+ * boundary that would rather scope explicitly than rely on `enterWith`.
+ */
+export declare const runWithRequestLoader: <T>(loader: DataLoader, fn: () => T) => T;
+
 /**
  * Run `work` inside a routing scope. Every `query()` call against a
  * `ReplicatedDataStore` from inside `work` (or its async children)
@@ -6290,6 +6391,21 @@ export declare type TupleSource = (req: {
     readonly subjectId: string | null;
     readonly resourceType: string;
     readonly resourceId: string;
+    /**
+     * The REQUEST's `DataLoader` — the same one `ctx.load` gives the executor.
+     *
+     * A relationship guard almost always has to read something to answer (the
+     * draft whose `teamId` decides access, the membership row), and the executor
+     * then reads the same row for the actual work. Loading through this makes the
+     * second read free: request-scoped, batched, cached, and dropped when the
+     * request ends.
+     *
+     * `undefined` outside a request — a boot seed, a schedule tick, a plugin's
+     * startup hook. Fall back to your own query there; there is no shared cache to
+     * join, and treating `undefined` as an error would break the paths that
+     * legitimately have no request.
+     */
+    readonly load: DataLoader | undefined;
 }) => Promise<ReadonlyArray<RelationTuple>> | ReadonlyArray<RelationTuple>;
 
 /**