@voltro/runtime 0.11.3 → 0.12.0

package/dist/index.d.ts

@@ -673,6 +673,11 @@ export declare interface ApiKeyRow {
     readonly keyPrefix: string;
     readonly scopes: ReadonlyArray<string> | null;
     readonly lastUsedAt: number | null;
+    /** WHO THE KEY ACTS AS — null for an org key. Distinct from `createdBy`. */
+    readonly onBehalfOf?: string | null;
+    /** Coarse usage counter, buffered — see `apiKeyUsage.ts`. Optional on the type
+     *  because a row written before the column existed reads back without it. */
+    readonly requestCount?: number;
     readonly expiresAt: number | null;
     readonly revokedAt: number | null;
     readonly createdBy: string | null;
@@ -692,10 +697,28 @@ export declare interface ApiKeyServiceShape {
     readonly resolveByHash: (hash: string, now?: number) => Promise<ResolvedApiKey | null>;
     /** Verify a raw token (hashes then resolves). */
     readonly verify: (token: string, now?: number) => Promise<ResolvedApiKey | null>;
-    /** Revoke a key (irreversible). */
-    readonly revoke: (id: string, now?: number) => Promise<boolean>;
-    /** Rotate: revoke the old key + issue a replacement with the same name/scopes/tenant. */
-    readonly rotate: (id: string, now?: number) => Promise<IssuedApiKey | null>;
+    /**
+     * Revoke a key (irreversible).
+     *
+     * `tenantId` is the CALLER's tenant and is REQUIRED, not optional: a key id is
+     * the only thing needed to revoke, and ids leak (logs, support tickets, an
+     * error message). Without this check an admin of tenant A could revoke tenant
+     * B's key by id — the guard on the route asks "is an admin", never "an admin
+     * of THIS key's tenant". Returns `false` for a key belonging to anyone else,
+     * indistinguishable from "no such key", so it cannot be used to probe.
+     *
+     * Pass `null` only for the tenant-less system key space. There is deliberately
+     * no "skip the check" value: an optional scope on a destructive operation is a
+     * scope somebody forgets.
+     */
+    readonly revoke: (id: string, tenantId: string | null, now?: number) => Promise<boolean>;
+    /**
+     * Rotate: revoke the old key + issue a replacement with the same
+     * name/scopes/tenant. Same required tenant scope as `revoke`, and here it
+     * matters more — rotate RETURNS A USABLE TOKEN, so an unscoped version would
+     * hand the caller a working credential for another tenant.
+     */
+    readonly rotate: (id: string, tenantId: string | null, now?: number) => Promise<IssuedApiKey | null>;
     /** List a tenant's keys (no secrets). */
     readonly list: (tenantId: string | null) => Promise<ReadonlyArray<PublicApiKey>>;
 }
@@ -708,6 +731,38 @@ export declare interface ApiKeyStore {
     readonly patch: (id: string, fields: Partial<ApiKeyRow>) => Promise<void>;
 }
 
+export declare interface ApiKeyUsageBuffer {
+    /** Record one use. Synchronous, no I/O. */
+    readonly touch: (id: string, at?: number) => void;
+    /** Write everything pending now. */
+    readonly flushNow: () => Promise<void>;
+    /** Flush and stop the timer. Idempotent. */
+    readonly shutdown: () => Promise<void>;
+    /** Pending key count — for tests and the inspect surface. */
+    readonly pending: () => number;
+}
+
+export declare interface ApiKeyUsageBufferOptions {
+    /** Apply one key's accumulated window. Must ADD `requests` to the stored
+     *  count and move `lastUsedAt` forward — never assign either, or a second
+     *  replica's window overwrites this one. */
+    readonly flush: (id: string, delta: ApiKeyUsageDelta) => Promise<void>;
+    /** Flush cadence. Default 30s. */
+    readonly intervalMs?: number;
+    /** Flush early once this many distinct keys are pending, so a burst across
+     *  many keys doesn't sit unbounded in memory for a whole window. Default 500. */
+    readonly maxPending?: number;
+    /** Injectable for tests. */
+    readonly now?: () => number;
+}
+
+export declare interface ApiKeyUsageDelta {
+    /** Requests counted for this key in the flushed window. Always ≥ 1. */
+    readonly requests: number;
+    /** The latest use observed in the window (epoch ms). */
+    readonly lastUsedAt: number;
+}
+
 /**
  * Typed authorization slice on `ctx.access` — the ergonomic, cast-free face of
  * the caller's EFFECTIVE scope set (raw subject scopes ∪ rbac role-derived
@@ -731,6 +786,28 @@ export declare interface AppAccess {
 
 export declare interface AppContext {
     readonly store: FluentStore;
+    /**
+     * The same store, scoped to ONE tenant.
+     *
+     * For non-request work — a schedule, a subscriber, a workflow step — whose
+     * subject is `system` with `tenantId: null`. Reads there see every tenant and
+     * a write to a `tenant()` table fails with `TenantScopeViolation`, so a
+     * per-tenant cron has to say which tenant it means. Every fan-out cron is
+     * literally a loop doing this by hand, and doing it by hand means each
+     * `.where('tenantId', t.id)` is one forgotten call away from reading the whole
+     * table:
+     *
+     *   for (const t of await ctx.store.select('tenants').all()) {
+     *     const scoped = ctx.storeForTenant(t.id)
+     *     await scoped.insert('digests', { … })   // tenantId stamped, not passed
+     *   }
+     *
+     * Inside a REQUEST this is almost always the wrong tool: the subject already
+     * carries a tenant, and reaching for another one is a cross-tenant read with
+     * extra steps. It exists because the system subject has no tenant to infer,
+     * not to let a request pick a different one.
+     */
+    readonly storeForTenant: (tenantId: string) => FluentStore;
     readonly request: RuntimeContext;
     /** Typed authorization slice — the caller's effective scopes. Use
      *  `ctx.access.has(scope)` / `yield* ctx.access.require(scope)` instead of
@@ -954,6 +1031,14 @@ export declare interface AttachAnalyticsMirrorOptions {
     readonly run?: (effect: Effect.Effect<void, unknown>) => Promise<unknown>;
 }
 
+/** The descriptor shape the audit needs — a `defineQuery` result carries it. */
+export declare interface AuditableQuery {
+    readonly name: string;
+    readonly output: Schema.Schema.Any;
+    /** Declared source table(s) — the tables whose serverOnly columns must not leak. */
+    readonly source?: string | ReadonlyArray<string> | undefined;
+}
+
 /**
  * Resolve once a server returned by {@link startRpcServer} has actually
  * bound its port (node `'listening'` event). REJECTS on `'error'`
@@ -1525,10 +1610,14 @@ export declare const countRunningWorkflows: (store: DataStore) => Promise<number
  * `(input, ctx) => …` executor for a `*.server.ts` default export.
  */
 export declare const crud: {
-    /** Tenant-scoped list of every row, redacted. */
-    list: (table: string, options?: CrudReadOptions) => (_input: unknown, ctx: AppContext) => Promise<ReadonlyArray<Row>>;
-    /** One row by id, or `null` when absent — never throws. Redacted. */
-    getById: (table: string, options?: CrudReadOptions) => (input: {
+    /** Tenant-scoped list, redacted — with optional filter / sort / pagination from
+     *  the request input, so a real list view doesn't have to be hand-written. */
+    list: (table: string, options?: CrudListOptions) => (input: unknown, ctx: AppContext) => Promise<ReadonlyArray<Row>>;
+    /** One row by id, or `null` when absent — never throws. Redacted, with optional
+     *  eager-loaded relations (`include`). */
+    getById: (table: string, options?: CrudReadOptions & {
+        readonly include?: CrudInclude;
+    }) => (input: {
         readonly id: string;
     }, ctx: AppContext) => Promise<Row | null>;
     /** Insert the input as a new row (id / tenant / audit auto-stamped). The echoed
@@ -1539,6 +1628,16 @@ export declare const crud: {
     update: (table: string, options?: CrudWriteOptions) => (input: {
         readonly id: string;
     } & Record<string, unknown>, ctx: AppContext) => Promise<Row | null>;
+    /**
+     * Tenant-scoped COUNT of the matching rows — the total a page-based UI needs to
+     * render "page 3 of 12". Takes the SAME `filter` as `list` (share the option
+     * object so the two can't disagree about which rows they mean) and ignores
+     * paging: it counts the whole filtered set, not the current page. A real
+     * `COUNT(*)` aggregate, not a fetch-and-length.
+     *
+     *     export default crud.count('absenceRequests', { filter: (i) => ({ status: i.status }) })
+     */
+    count: (table: string, options?: Pick<CrudListOptions, "filter" | "scope">) => (input: unknown, ctx: AppContext) => Promise<number>;
     /** Delete a row by id; returns `{ deleted }`. Guard the DESCRIPTOR. */
     remove: (table: string) => (input: {
         readonly id: string;
@@ -1547,6 +1646,101 @@ export declare const crud: {
     }>;
 };
 
+/** The eager-load spec `.with()` accepts — nested relations, each branch taking
+ *  its own `where` / `orderBy` / `limit` (nested filtering + sort). Reused as-is
+ *  so `crud.list`'s `include` is exactly what a hand-written `.with(...)` takes. */
+export declare type CrudInclude = Parameters<SelectBuilder['with']>[0];
+
+/**
+ * Options for `crud.list` — the read ergonomics every real list view needs, so a
+ * generated list isn't limited to "all rows". All optional and additive: a bare
+ * `crud.list('t')` still returns every (tenant-scoped, redacted) row.
+ */
+export declare interface CrudListOptions extends CrudReadOptions {
+    /**
+     * Build a WHERE from the request input — return a column→value map. Only
+     * entries whose value is not `undefined` are applied, so an absent filter field
+     * is simply ignored (`{ employeeId: input.employeeId, status: input.status }`).
+     * The descriptor's `input` schema declares those fields; this maps them to a
+     * scoped `.where(column, value)` on the store query.
+     *
+     * Request input ONLY, on purpose — see `scope` for the caller-derived half.
+     */
+    readonly filter?: (input: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>>;
+    /**
+     * The caller-derived WHERE — what this subject may SEE, as opposed to what it
+     * asked for. Merged into the same query as `filter`, and it WINS on a key
+     * collision, so a caller cannot widen its own scope by sending that field.
+     *
+     *   scope: (ctx) => ({ ownerId: ctx.request.subject.id })
+     *
+     * Why this is a SEPARATE option rather than a second argument to `filter`:
+     * the two answer different questions, and only one of them is a security
+     * boundary. Kept apart, "does this list declare a `scope`?" is a question a
+     * reviewer — or a future boot audit — can actually ask. Folded into `filter`,
+     * it becomes "does this filter happen to read ctx somewhere in its body?",
+     * which nothing can check.
+     *
+     * The gap this closes: tenant scope is applied automatically, but anything
+     * narrower — owner, team, role — was not expressible at all. Replacing a
+     * hand-written handler that carried such a narrowing with `crud.list`
+     * therefore WIDENED the result set, silently and with no error. One app lost
+     * exactly that across eight list views.
+     *
+     * Pass the same `scope` to `crud.count`, or the total contradicts the pages.
+     */
+    readonly scope?: (ctx: AppContext) => Readonly<Record<string, unknown>>;
+    /**
+     * Page the result from the request. BOTH styles are accepted, so a caller uses
+     * whichever its UI thinks in:
+     *
+     *   - **page-based** — `input.page` (1-based) + `input.pageSize` (default 100).
+     *     A table UI showing "page 3 of 12" sends `?page=3&pageSize=20`.
+     *   - **offset-based** — `input.limit` / `input.offset` (defaults 100 / 0).
+     *
+     * `page` wins when both are present. Pair with `crud.count` for the total a
+     * page-based UI needs to render the last-page number.
+     */
+    readonly paginate?: boolean;
+    /**
+     * Upper bound on the rows ONE request may ask for (default 1000). The page
+     * size is caller-controlled, so without a cap `?limit=1000000` on a
+     * `publicApi` list is a one-request resource-exhaustion lever for anyone who
+     * can reach the endpoint. Raise it deliberately for an export-style endpoint;
+     * a `limit`/`pageSize` above it is clamped, not rejected.
+     */
+    readonly maxPageSize?: number;
+    /** Multi-column sort, applied in order (`[{ column: 'createdAt', direction:
+     *  'desc' }, …]`). */
+    readonly sort?: ReadonlyArray<CrudSort>;
+    /**
+     * Eager-load related rows via `.with(...)` — the SAME spec a hand-written query
+     * takes, so nested relations, and per-branch `where` / `orderBy` / `limit`
+     * (nested filtering + sort) all work:
+     *
+     *     include: { employee: { with: { team: true } }, tags: { orderBy: 'name' } }
+     */
+    readonly include?: CrudInclude;
+    /**
+     * SQL column projection — narrow the `SELECT` so wide columns are never READ,
+     * not merely dropped at the wire boundary. The output schema already strips
+     * undeclared columns on encode (so nothing extra ships either way); this is the
+     * PERFORMANCE half: a table with a large `json()` blob or a long text body that
+     * a list view never shows shouldn't cost the read, the transfer from the DB, or
+     * the decode.
+     *
+     *     columns: ['id', 'title', 'createdAt']   // the big `body` is never read
+     *
+     * `.serverOnly()` columns are removed from the projection automatically — they
+     * are stripped from the response anyway, so reading them is pure waste.
+     *
+     * TRAP with `include`: an eager branch joins on a foreign key, so a projection
+     * that omits that FK column breaks the relation. Keep the FK in `columns` when
+     * you also pass `include`.
+     */
+    readonly columns?: ReadonlyArray<string>;
+}
+
 /** Options common to a generated READ. */
 export declare interface CrudReadOptions {
     /** Columns stripped from every returned row — a secret/credential a generated
@@ -1556,6 +1750,12 @@ export declare interface CrudReadOptions {
     readonly redact?: ReadonlyArray<string>;
 }
 
+/** A single sort term for `crud.list`. */
+export declare interface CrudSort {
+    readonly column: string;
+    readonly direction?: 'asc' | 'desc';
+}
+
 /** Options for a generated WRITE — `redact` applies to the row the write echoes. */
 export declare interface CrudWriteOptions {
     readonly redact?: ReadonlyArray<string>;
@@ -1585,7 +1785,6 @@ export declare interface DataLoader {
 
 export { DataStore }
 
-/** DataStore-backed store over `_voltro_api_keys`. */
 export declare const dataStoreApiKeyStore: (store: DataStore) => ApiKeyStore;
 
 export declare const dataStoreIdempotencyStore: (store: DataStore) => IdempotencyStore;
@@ -1663,7 +1862,7 @@ export declare const defineEventTrigger: <EventPayload = unknown, WorkflowPayloa
  * Runtime identity — returns `fn` unchanged; the whole value is the compile-time
  * check. See the module header for the failure it prevents.
  */
-export declare const defineExecutor: <D extends ExecutorDescriptor, E = never, R = never>(_descriptor: D, fn: (input: ExecutorInput<D>, ctx: AppContext) => ExecutorReturn<D, E, R>) => ((input: ExecutorInput<D>, ctx: AppContext) => ExecutorReturn<D, E, R>);
+export declare const defineExecutor: <D extends ExecutorDescriptor, F extends (input: ExecutorInput<D>, ctx: AppContext) => ExecutorReturn<D, unknown, unknown>>(_descriptor: D, fn: F) => ((input: ExecutorInput<D>, ctx: AppContext) => ReturnType<F>);
 
 /**
  * Declare who delivers an effect. One per `*.outbox.ts` file.
@@ -1928,6 +2127,10 @@ export declare interface EffectStoreOps {
  *  discovered tables. */
 export declare const emptySchemaRegistry: SchemaRegistry;
 
+/** Turn recording on from code. Idempotent. Must run BEFORE the stores that
+ *  should be observed are constructed — `observeStore` decides once, per store. */
+export declare const enableGraphObservation: () => void;
+
 /** Encrypt a value with the registered field cipher (same one `.encrypted()`
  *  columns use). Throws if no cipher is registered. */
 export declare const encryptField: (plaintext: string) => string;
@@ -2103,6 +2306,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 leaks (empty → `undefined`, i.e. clean). */
+export declare const formatServerOnlyLeaks: (leaks: ReadonlyArray<ServerOnlyLeak>) => string | undefined;
+
 /** Serialise a span's context as a `traceparent` header value. */
 export declare const formatTraceparent: (ctx: TraceContext) => string;
 
@@ -2444,6 +2650,8 @@ export declare const isIdleNow: (opts: IdleCheckOptions) => Promise<boolean>;
 
 export declare const isInfraError: (e: unknown) => boolean;
 
+export declare const isObservingGraph: () => boolean;
+
 /**
  * A subject that AUTHENTICATED but resolved with NO active org — a `user` (not
  * `anonymous`/`system`) carrying the empty-string tenant sentinel. Every
@@ -2484,7 +2692,12 @@ export declare interface IssueInput {
     readonly name: string;
     readonly scopes?: ReadonlyArray<string>;
     readonly expiresAt?: Date | number | null;
+    /** WHO MINTED IT. Provenance — set it always, including for an org key. */
     readonly createdBy?: string | null;
+    /** WHO IT ACTS AS. Omit for an ORG key (acts as no person); set it for a
+     *  personal key, which may be the minter or — when an admin mints for a
+     *  colleague — someone else entirely. */
+    readonly onBehalfOf?: string | null;
 }
 
 export declare const isWorkflowEventTriggerDefinition: (value: unknown) => value is WorkflowEventTriggerDefinition;
@@ -2532,6 +2745,22 @@ export declare interface JunctionLinks {
     add(targetIds: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
     /** Unlink `targetIds` that are currently linked. Returns the ids actually removed. */
     remove(targetIds: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
+    /**
+     * Reconcile links that carry PER-ROW PAYLOAD — a junction with business columns
+     * (a membership `role`, a `capacity` value). Each row is
+     * `{ [targetColumn]: id, …payload }`; the diff is on the (source, target) pair:
+     * an added row is inserted with its payload, a removed row deleted, and a
+     * SURVIVING row whose payload actually changed is UPDATED — one whose payload
+     * is unchanged is left untouched, so a reactive consumer sees a change only
+     * where the payload differs (the `set(targetIds)` form can't express payload;
+     * this is the drop+reinsert replacement for a junction that carries data).
+     * Payload is compared by strict equality per column (scalars — capacity, role).
+     */
+    setRows(rows: ReadonlyArray<Readonly<Record<string, unknown>>>): Promise<{
+        readonly added: ReadonlyArray<string>;
+        readonly removed: ReadonlyArray<string>;
+        readonly updated: ReadonlyArray<string>;
+    }>;
 }
 
 export declare interface KvFacade {
@@ -2691,8 +2920,30 @@ export declare const makeAesCipher: (key: Buffer) => FieldCipher;
 
 export declare const makeApiKeyService: (store: ApiKeyStore, opts?: {
     prefix?: string;
+    /** Buffers `lastUsedAt` + `requestCount` instead of writing a row per auth
+     *  check. Omit to keep the synchronous stamp (see `resolveByHash`). */
+    usage?: ApiKeyUsageBuffer;
 }) => ApiKeyServiceShape;
 
+export declare const makeApiKeyUsageBuffer: (options: ApiKeyUsageBufferOptions) => ApiKeyUsageBuffer;
+
+/**
+ * The flusher a buffered `ApiKeyUsageBuffer` is built with: read-modify-write of
+ * `requestCount` + `lastUsedAt` for one key, once per window.
+ *
+ * Not atomic across replicas, and that is a deliberate limit rather than an
+ * oversight. Two pods flushing the same key in the same instant can lose one
+ * window's delta. Making it exact would need a dialect-specific
+ * `SET requestCount = requestCount + ?`, which is real complexity in service of
+ * a field whose stated purpose is "is this key still in use, and roughly how
+ * much". If this number ever needs to be exact, that is the signal it is being
+ * used for something it was not built for (billing), not a signal to add locking.
+ */
+export declare const makeApiKeyUsageFlusher: (store: ApiKeyStore) => (id: string, delta: {
+    readonly requests: number;
+    readonly lastUsedAt: number;
+}) => Promise<void>;
+
 /** Build the `ctx.access` slice for a subject. Reads the effective-scope seam
  *  LIVE (via getters/closures) so a scope rbac resolves after context
  *  construction is still reflected. Used by the shared AppContext builder AND
@@ -2794,6 +3045,24 @@ export declare const makeListConnectionsExecutor: (deps: ConnectionBuiltinDeps)
  */
 export declare const makeMutationRunner: (deps: MutationRunnerDeps) => (mutation: MutationLike, input: unknown, requestContext: ServeRequestContext) => Promise<unknown>;
 
+/**
+ * Run a QUERY once and resolve its value — the read counterpart to
+ * `makeMutationRunner` / `makeActionRunner`, for callers that have no
+ * subscription: a descriptor projected to a public REST endpoint.
+ *
+ * It is deliberately built ON TOP of `makeQueryDescriptorProducer` rather than
+ * beside it. That producer is where the declarative `guards:` gate, the
+ * per-request row-filter resolution and the tenant-scoping `finalize` live, so
+ * reusing it makes the one-shot path enforce EXACTLY what the WS path enforces.
+ * A second implementation here would be an authorization bypass waiting to
+ * happen — the REST projection of a guarded query must fail the same way the
+ * socket does, and it does because it runs the same code.
+ *
+ * Both handler shapes resolve: a descriptor-returning (reactive) query is
+ * finalized and executed to rows; a computed query yields its value.
+ */
+export declare const makeOneShotQueryRunner: <D>(deps: OneShotQueryRunnerDeps<D>) => (query: MutationLike, input: unknown, requestContext: ServeRequestContext) => Promise<unknown>;
+
 export declare const makeOutboxFacade: (deps: OutboxFacadeDeps) => OutboxFacade;
 
 export declare const makePostCommitWorkflowFacade: (base: WorkflowsAppContext, afterCommit: (work: () => Promise<unknown>) => void) => WorkflowsAppContext;
@@ -2837,6 +3106,25 @@ export declare const makeQueryDescriptorProducer: <D>(deps: QueryProducerDeps<D>
  */
 export declare const makeQueryReauthorizer: (query: MutationLike, input: unknown) => (subject: Subject) => () => Promise<unknown>;
 
+/**
+ * Subscribe a QUERY and stream its events to a non-rpc consumer — the SSE
+ * projection of a `publicApi` query. Like `makeOneShotQueryRunner`, it runs the
+ * shared `makeQueryDescriptorProducer`, so the declarative `guards:`, the row
+ * filter and tenant scoping are the same code the socket path runs: an SSE
+ * endpoint is exactly as gated as the WebSocket one.
+ *
+ * Returns an unsubscribe SYNCHRONOUSLY (the HTTP layer needs one immediately)
+ * while the subscription opens in the background; unsubscribing before it
+ * finishes tears it down as soon as it exists, so a client that disconnects
+ * mid-setup cannot leak a subscription. A setup failure — including a guard
+ * denial — is emitted as one `error` event rather than thrown, because by then
+ * the response headers are already on the wire.
+ */
+export declare const makeQuerySubscriber: <D>(deps: QuerySubscriberDeps<D>) => (query: MutationLike, input: unknown, requestContext: ServeRequestContext, emit: (event: {
+    readonly _tag: string;
+    readonly [k: string]: unknown;
+}) => void) => (() => void);
+
 export declare const makeRouterActivity: () => RouterActivity;
 
 /**
@@ -3217,6 +3505,50 @@ export declare interface OAuth2ConnectionDefinition extends ConnectionDefinition
     readonly identify?: (tokens: ConnectionTokens) => Promise<ConnectionAccount>;
 }
 
+/** One recorded `(procedure → table, op)` edge. */
+export declare interface ObservedEdge {
+    readonly tag: string;
+    readonly kind: ObservedProcedure['kind'];
+    readonly table: string;
+    readonly op: ObservedOp;
+}
+
+export declare interface ObservedGraph {
+    /** Schema version of this file's shape, so `check` can refuse an old one
+     *  loudly instead of silently diffing against a different meaning. */
+    readonly version: 1;
+    readonly edges: ReadonlyArray<ObservedEdge>;
+    /** Tags seen entering the recorder at all — the difference between "this
+     *  procedure touched no table" and "this procedure never ran", which is the
+     *  distinction the whole feature stands on. */
+    readonly exercised: ReadonlyArray<string>;
+}
+
+/** Snapshot everything recorded so far. */
+export declare const observedGraph: () => ObservedGraph;
+
+/** What a procedure did to a table. `read` covers every query path. */
+export declare type ObservedOp = 'read' | 'insert' | 'update' | 'delete' | 'upsert';
+
+export declare interface ObservedProcedure {
+    /** The procedure's effective rpc tag (`notes.create`). */
+    readonly tag: string;
+    readonly kind: 'query' | 'mutation' | 'action' | 'stream' | 'schedule' | 'workflow';
+}
+
+/**
+ * Wrap a `DataStore` so every operation is recorded. Returns the store unchanged
+ * when recording is off, so the production path keeps the exact same object
+ * (no added indirection, no added allocation).
+ *
+ * Wrapping the store BENEATH the mixin middleware rather than instrumenting the
+ * middleware's ~20 public methods is deliberate: those methods delegate to each
+ * other (`one`/`first`/`maybeOne` all go through `query`), so instrumenting them
+ * individually would double-count some paths and miss any new one. Underneath,
+ * each operation passes exactly once.
+ */
+export declare const observeStore: <S extends object>(store: S) => S;
+
 /**
  * Listen for re-bind events. Returns an unsubscribe function. Used by
  * the dispatcher to re-scope active subscriptions when a connection's
@@ -3225,6 +3557,15 @@ export declare interface OAuth2ConnectionDefinition extends ConnectionDefinition
  */
 export declare const onBindConnectionSubject: (listener: (clientId: number, subject: Subject) => void) => () => void;
 
+export declare interface OneShotQueryRunnerDeps<D> extends QueryProducerDeps<D> {
+    /**
+     * Execute a FINALIZED (tenant-scoped) descriptor → rows. On the WS path the
+     * dispatcher owns this step; a ONE-SHOT read (a `publicApi` REST GET, where
+     * there is no subscription to drive) needs it inline.
+     */
+    readonly queryRows: (descriptor: D) => Promise<ReadonlyArray<unknown>>;
+}
+
 /** 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 {
@@ -3402,6 +3743,24 @@ export declare interface PatConnectionDefinition extends ConnectionDefinitionCom
     readonly validate?: (token: string) => Promise<ConnectionAccount>;
 }
 
+/**
+ * TOP-LEVEL property names of a struct-ish schema, split by optionality.
+ *
+ * Deliberately not `schemaPropertyNames` (`./serverOnlyAudit`), which answers a
+ * DIFFERENT question: that one walks the whole schema recursively and flattens
+ * every name at any depth, because a leak check cares whether a column name
+ * appears anywhere in an output. This one asks "what does this payload require
+ * at its top level", so depth would be wrong and optionality is the point.
+ *
+ * Best effort — at runtime it only makes an error readable and never decides
+ * validity — but `voltro doctor`'s static `workflows.start` audit calls the same
+ * function, so the two cannot disagree about what a payload requires.
+ */
+export declare const payloadPropertyNames: (schema: Schema.Schema.Any) => {
+    readonly required: ReadonlyArray<string>;
+    readonly optional: ReadonlyArray<string>;
+};
+
 /** The 3-arg signature a plugin sees on its bind-ctx. */
 export declare type PluginScheduleCoordinated = (name: string, intervalMs: number, effect: () => void | Promise<void>) => CoordinatedScheduleHandle;
 
@@ -3529,6 +3888,13 @@ export declare interface QueryProducerDeps<D> {
     readonly interceptor?: ServeRpcInterceptor;
 }
 
+export declare interface QuerySubscriberDeps<D> extends QueryProducerDeps<D> {
+    /** Open a dispatcher subscription for a finalized descriptor. */
+    readonly subscribeDescriptor: (descriptor: D, emit: (event: unknown) => void, context: ServeRequestContext) => Promise<() => void>;
+    /** Open a dispatcher subscription for a COMPUTED query (re-runs on source change). */
+    readonly subscribeComputed: (computed: ComputedQuery, emit: (event: unknown) => void, context: ServeRequestContext) => Promise<() => void>;
+}
+
 /** What a reaction does when it fires — run an agent or start a workflow. Both
  *  identified by name; the serve layer resolves + runs them as `agentActor`. */
 export declare type ReactionAct = {
@@ -3685,6 +4051,14 @@ export declare const recordSubscriptionActive: (label: string, delta: number) =>
  *  latency + a delivery counter. Rides the framework's existing per-delivery tap. */
 export declare const recordSubscriptionDelivery: (d: SubscriptionDeliveryRecord) => void;
 
+/**
+ * Record one table access against the procedure on the current fiber. Silently
+ * ignored outside a procedure scope — background work (migrations, the
+ * scheduler's own bookkeeping, plugin boot) is not a procedure and must not
+ * invent edges for one.
+ */
+export declare const recordTableAccess: (table: string, op: ObservedOp) => void;
+
 /** Feed a committed change into the process recorder (gated + loop-safe). The
  *  serve paths call this from their `store.onChange` tap. */
 export declare const recordTimelineEvent: (change: CdcChange & {
@@ -4055,6 +4429,9 @@ export declare interface ResendOptions {
 /** Test/dev-only — clear ALL overrides. Don't call from app code. */
 export declare const _resetConnectionSubjectsForTest: () => void;
 
+/** Drop everything recorded. For tests; not called by the runtime. */
+export declare const resetObservedGraph: () => void;
+
 /** Reset to the env default (tests). */
 export declare const resetSecretsBackend: () => void;
 
@@ -4106,9 +4483,11 @@ export declare const resolveCurrentRegion: (env?: NodeJS.ProcessEnv) => string |
 export declare interface ResolvedApiKey {
     readonly id: string;
     readonly tenantId: string;
-    /** The user who created the key, when one is recorded. Null for a key minted
-     *  outside a user session (bootstrap / admin tooling). */
+    /** WHO MINTED the key. Provenance — present for org keys too. */
     readonly createdBy: string | null;
+    /** WHO THE KEY ACTS AS. `null` = an ORG key. This is the identity attribution
+     *  follows and the one the Subject carries as `metadata.userId`. */
+    readonly onBehalfOf: string | null;
     readonly scopes: ReadonlyArray<string>;
 }
 
@@ -4585,6 +4964,16 @@ export declare const runWithDeadlockRetry: <T>(work: () => Promise<T>, options?:
     readonly delay?: (attempt: number) => Promise<void>;
 }) => Promise<T>;
 
+/**
+ * Run `work` attributed to `procedure`. Every store operation performed inside
+ * (or in its async children) is recorded against that tag.
+ *
+ * A no-op when recording is off, including the ALS entry itself — an
+ * AsyncLocalStorage `run` on every rpc call is not free, and a disabled feature
+ * should cost nothing.
+ */
+export declare const runWithObservedProcedure: <T>(procedure: ObservedProcedure, work: () => T) => T;
+
 /**
  * Run `work` inside a routing scope. Every `query()` call against a
  * `ReplicatedDataStore` from inside `work` (or its async children)
@@ -4846,6 +5235,14 @@ export declare interface SchedulerHandle {
 export declare interface SchedulerLogger {
     info: (msg: string, fields?: Record<string, unknown>) => void;
     warn: (msg: string, fields?: Record<string, unknown>) => void;
+    /**
+     * Failures. This channel did not exist, which is why a schedule whose handler
+     * failed on EVERY firing was only ever a `warn` — invisible to `voltro logs
+     * --level error`, and a schedule fires unattended, so that log line is the
+     * whole discovery channel. Optional so an embedder passing a two-method logger
+     * still compiles; it falls back to `warn` at the call site.
+     */
+    error?: (msg: string, fields?: Record<string, unknown>) => void;
     /** Optional debug channel for high-frequency expected events
      *  (lost coordination claims on sub-minute schedules etc.). */
     debug?: (msg: string, fields?: Record<string, unknown>) => void;
@@ -4914,6 +5311,13 @@ export declare interface SchemaInfo {
     readonly idScheme?: IdScheme;
 }
 
+/**
+ * Every property NAME that appears anywhere in a schema's shape. Recursive over
+ * the common composition nodes so a column nested under `{ refs: [{ … }] }` or
+ * behind a `NullOr` is still seen. Cycle-guarded via a seen-set on Suspend.
+ */
+export declare const schemaPropertyNames: (schema: Schema.Schema.Any) => ReadonlySet<string>;
+
 export declare interface SchemaRegistry {
     readonly tables: ReadonlyMap<string, SchemaInfo>;
     /** True iff the table was composed with the named mixin id. */
@@ -5061,6 +5465,20 @@ export declare interface ServeRequestContext {
     readonly rowFilter?: RowFilterScope;
 }
 
+/** One leak: a wire query that declares a serverOnly column in its output. */
+export declare interface ServerOnlyLeak {
+    readonly query: string;
+    readonly table: string;
+    readonly column: string;
+}
+
+/**
+ * Every serverOnly column a query's output declares. `serverOnlyByTable` maps a
+ * table name to its `.serverOnly()` column names. A query with no `source`, or
+ * whose source has no serverOnly columns, yields nothing.
+ */
+export declare const serverOnlyLeaks: (query: AuditableQuery, serverOnlyByTable: ReadonlyMap<string, ReadonlyArray<string>>) => ReadonlyArray<ServerOnlyLeak>;
+
 /** A plugin interceptor — wraps the base run Effect (Effect-native chain). */
 export declare type ServeRpcInterceptor = (base: Effect.Effect<unknown, unknown, never>, meta: {
     readonly tag: string;
@@ -5182,6 +5600,51 @@ export declare const snapshotMetrics: Effect.Effect<ReadonlyArray<MetricSample>>
 /** Eager snapshot for sync callers (the inspect endpoint). */
 export declare const snapshotMetricsSync: () => ReadonlyArray<MetricSample>;
 
+/** Thrown (as a typed defect) when a request targets a blocked address. */
+export declare class SsrfBlockedError extends Error {
+    readonly url: string;
+    readonly reason: string;
+    readonly _tag = "SsrfBlockedError";
+    constructor(url: string, reason: string);
+}
+
+/**
+ * Decorator layer: consumes a base `HttpClient` and re-provides one that blocks
+ * SSRF targets on the initial request AND on every redirect hop.
+ *
+ * Compose it BELOW the tracing layer and above the base fetch client:
+ *
+ *   ssrfGuardHttpClientLayer(policy).pipe(Layer.provide(FetchHttpClient.layer))
+ */
+export declare const ssrfGuardHttpClientLayer: (policy?: SsrfPolicy) => Layer.Layer<HttpClient.HttpClient, never, HttpClient.HttpClient>;
+
+export declare interface SsrfPolicy {
+    /**
+     * Hosts that bypass the guard. An entry may be an exact hostname
+     * (`billing.internal`), a suffix wildcard (`*.svc.cluster.local`), or a
+     * host:port (`127.0.0.1:8787`) when only one port should be reachable.
+     *
+     * This is the one escape hatch, and it is deliberately per-HOST rather than a
+     * boolean: "we call one internal service" and "we do not check URLs" are very
+     * different postures, and a boolean cannot tell them apart six months later.
+     */
+    readonly allowHosts?: ReadonlyArray<string>;
+    /** Max redirect hops to follow. Each one is revalidated. Default 5. */
+    readonly maxRedirects?: number;
+}
+
+/**
+ * Decide whether a URL may be fetched. Returns `null` when allowed, else the
+ * reason. Fails CLOSED: a URL that will not parse is blocked.
+ *
+ * DNS is deliberately NOT resolved — this is a synchronous check on the literal
+ * target, so a hostname that RESOLVES to a private address (DNS rebinding) is not
+ * caught here. Blocking the direct-IP vector is the high-severity, cheap half;
+ * rebinding needs network-layer egress control and is called out in the docs
+ * rather than silently implied.
+ */
+export declare const ssrfReason: (rawUrl: string, policy?: SsrfPolicy) => string | null;
+
 /**
  * Start the rpc-based runtime server on Node. Composes:
  *   - NodeHttpServer + NodeContext at the platform layer
@@ -5189,10 +5652,15 @@ export declare const snapshotMetricsSync: () => ReadonlyArray<MetricSample>;
  *   - RpcServer.layerHttpRouter (websocket protocol) consuming
  *     RpcSerialization.layerJson and the user's handlers layer
  *
- * Hands the result to NodeRuntime.runMain via Layer.launch so the Node event
- * loop stays alive for the lifetime of the layer's scope.
- */
-export declare const startRpcServer: <Rpcs extends Rpc.Any>(options: RpcServerOptions<Rpcs>) => ReturnType<typeof createServer>;
+ * Forks `Layer.launch` so the Node event loop stays alive for the lifetime of the
+ * layer's scope, and returns that scope's `shutdown` alongside the node server —
+ * so a programmatic close releases the layer, not just the socket. SIGINT/SIGTERM
+ * are wired once per process (not once per call) and drain every live launch.
+ */
+export declare const startRpcServer: <Rpcs extends Rpc.Any>(options: RpcServerOptions<Rpcs>) => {
+    server: ReturnType<typeof createServer>;
+    shutdown: () => Promise<void>;
+};
 
 export declare const startScheduler: (schedules: ReadonlyArray<BrandedScheduleDefinition>, deps: SchedulerDeps) => Promise<SchedulerHandle>;
 
@@ -6193,6 +6661,32 @@ export declare interface WorkflowLayerOptions<Context> {
     readonly resolveStartContext?: (workflowName: string, executionId: string) => WorkflowCallerContext | undefined | Promise<WorkflowCallerContext | undefined>;
 }
 
+/**
+ * A start whose PAYLOAD does not match the workflow's schema.
+ *
+ * Distinct from a workflow that ran and failed, and the distinction is the whole
+ * point: `ctx.workflows.start(name, payload)` is typed `(string, unknown)` — the
+ * name is not checked against the registry and the payload is not checked against
+ * anything — so a caller that drifts from the workflow's schema produces a failure
+ * DEEP inside the engine, where it reads like the workflow itself misbehaved.
+ *
+ * A cron firing such a start hit that every single time and looked like a flaky
+ * job. Naming the workflow, the missing fields, and the fact that the payload
+ * (not the workflow) is what's wrong turns it into a one-read fix.
+ */
+export declare class WorkflowPayloadError extends Error {
+    readonly workflowName: string;
+    /** Top-level property names the schema requires and the payload omitted.
+     *  Empty when the mismatch is a type error rather than a missing key. */
+    readonly missingFields: ReadonlyArray<string>;
+    readonly detail: string;
+    readonly _tag = "WorkflowPayloadError";
+    constructor(workflowName: string, 
+    /** Top-level property names the schema requires and the payload omitted.
+     *  Empty when the mismatch is a type error rather than a missing key. */
+    missingFields: ReadonlyArray<string>, detail: string);
+}
+
 /** Options for {@link WorkflowsAppContext.retry}. */
 export declare interface WorkflowRetryOptions {
     /** Re-run the workflow against this payload instead of the original
@@ -6330,6 +6824,6 @@ export declare interface WorkflowWaitOptions {
  */
 export declare const wrapCaptureStore: (tx: DataStore, collect: (c: ForwardChange) => void) => DataStore;
 
-export declare const wrapStoreWithMixinBehaviour: (underlying: DataStore, ctx: StoreMiddlewareContext) => FluentStore;
+export declare const wrapStoreWithMixinBehaviour: (rawUnderlying: DataStore, ctx: StoreMiddlewareContext) => FluentStore;
 
 export { }