@voltro/runtime 0.11.2 → 0.11.4

package/dist/index.d.ts

@@ -954,6 +954,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'`
@@ -1519,6 +1527,138 @@ export declare const counter: (name: string, description?: string) => Metric.Met
  */
 export declare const countRunningWorkflows: (store: DataStore) => Promise<number>;
 
+/**
+ * Secure-default CRUD executor factories. Each takes the table NAME (not the
+ * table value — that would be a server import in a descriptor) and returns an
+ * `(input, ctx) => …` executor for a `*.server.ts` default export.
+ */
+export declare const crud: {
+    /** 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
+     *  row is redacted. Guard the DESCRIPTOR — this does not gate. */
+    create: (table: string, options?: CrudWriteOptions) => (input: Row, ctx: AppContext) => Promise<Row>;
+    /** Patch a row by id (`{ id, ...patch }`); returns the updated row or `null`.
+     *  Redacted. Guard the DESCRIPTOR. */
+    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">) => (input: unknown, ctx: AppContext) => Promise<number>;
+    /** Delete a row by id; returns `{ deleted }`. Guard the DESCRIPTOR. */
+    remove: (table: string) => (input: {
+        readonly id: string;
+    }, ctx: AppContext) => Promise<{
+        readonly deleted: boolean;
+    }>;
+};
+
+/** 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.
+     */
+    readonly filter?: (input: Readonly<Record<string, unknown>>) => 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
+     *  read must never ship (`bankIban`, `tokenHash`, `salary`). The wire schema on
+     *  the descriptor should omit them too, so they never reach the client at all;
+     *  this is the runtime half that guarantees it regardless. */
+    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>;
+}
+
 /** 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;
@@ -1974,6 +2114,16 @@ export declare interface FieldChange {
 export declare const fingerprintFor: (table: string, predicate: Predicate, indexHint?: string) => string;
 
 export declare interface FluentStore extends Omit<MutationStore, 'update' | 'delete' | 'query'> {
+    /**
+     * Diff-based many-to-many link writer for a junction table. `anchor` names the
+     * source column and its id (`{ postId: 'p1' }`); the target column is the
+     * junction's other reference column, auto-detected. Only the difference is
+     * written, so reactive consumers see one change per changed row, not a
+     * drop+reinsert of the whole set.
+     *
+     *     await ctx.store.links('post_tags', { postId: post.id }).set(tagIds)
+     */
+    links(junctionTable: string, anchor: Readonly<Record<string, string>>): JunctionLinks;
     /**
      * Execute a query descriptor and return the matching rows — TYPED.
      *
@@ -2051,6 +2201,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;
 
@@ -2454,6 +2607,50 @@ export declare type IvmState = ReadonlyMap<string, GroupState>;
 /** Project the public aggregate value from a group's accumulator. */
 export declare const ivmValue: (shape: AggregateShape, g: GroupState) => number | null;
 
+/**
+ * Diff-based writer for a many-to-many JUNCTION table (A2). Reconciles the set
+ * of links from ONE anchor row (`{ [sourceColumn]: id }`) against a target-id
+ * list by writing only the DIFFERENCE — the added rows are inserted, the removed
+ * rows are deleted, and rows already correct are left untouched. That is the
+ * whole point over a drop-all-then-reinsert `setLinks`: a reactive subscription
+ * on the junction sees a change event only for the rows that actually changed
+ * (no flicker, no lost data if two writers overlap), and an unchanged link never
+ * churns. The TARGET column is the junction's OTHER reference column (the one the
+ * anchor doesn't name); a junction with anything but exactly two reference
+ * columns is rejected with a message naming what it found.
+ */
+export declare interface JunctionLinks {
+    /** The current target ids linked to the anchor. */
+    list(): Promise<ReadonlyArray<string>>;
+    /** Reconcile the links to EXACTLY `targetIds` — insert the missing, delete the
+     *  surplus, leave the rest. Returns what changed. */
+    set(targetIds: ReadonlyArray<string>): Promise<{
+        readonly added: ReadonlyArray<string>;
+        readonly removed: ReadonlyArray<string>;
+    }>;
+    /** Link `targetIds` that aren't linked yet (idempotent — existing links are
+     *  not re-inserted, so they emit no event). Returns the ids actually added. */
+    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 {
     readonly kv: AsyncKv;
     /** The resolved Effect-native `Kv` service instance. Its methods close over
@@ -2714,6 +2911,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;
@@ -2757,6 +2972,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;
 
 /**
@@ -3145,6 +3379,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 {
@@ -3449,6 +3692,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 = {
@@ -3611,6 +3861,13 @@ export declare const recordTimelineEvent: (change: CdcChange & {
     readonly tenantId?: string | null;
 }) => 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
+ * audited the same way. Pure — no store, no context.
+ */
+export declare const redactColumns: <R extends Row>(rows: ReadonlyArray<R>, redact: ReadonlyArray<string>) => ReadonlyArray<R>;
+
 /** Blank sensitive-looking columns. Returns a new object; null passes through. */
 export declare const redactRow: (row: Row_2 | null | undefined) => Row_2 | null;
 
@@ -4759,6 +5016,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;
@@ -4827,6 +5092,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. */
@@ -4974,6 +5246,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;
@@ -6106,6 +6392,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