@voltro/runtime 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1662,6 +1662,17 @@ export declare class DeleteBuilder {
     hard(): Promise<number>;
 }
 
+/** Row count for a delivered payload, for the trace/metric tap.
+ *
+ *  A computed query's value is arbitrary — a scalar, an object, an array, or
+ *  nothing at all. Reporting a fixed 1 for all of them (which this used to do)
+ *  turned the `rows` attribute into a liveness signal that reads like a data
+ *  signal: an `employees.me` that resolved to `null` still traced `rows=1`, and
+ *  a downstream consumer used exactly that span to conclude the server had
+ *  produced a value when it had not. Absent is 0, a single value is 1, an array
+ *  is its length. */
+export declare const deliveredRowCount: (value: unknown) => number;
+
 /**
  * Derive a 32-byte AES-256 key from a passphrase via scrypt. A fixed
  * salt keeps derivation deterministic across processes (the passphrase
@@ -1798,6 +1809,15 @@ export declare interface DispatcherDependencies {
     readonly cache?: SnapshotCache;
 }
 
+/** Bookkeeping tenant key for the `_voltro_wakeups` rows that dormant schedules
+ *  and dormant workflow waits register when their subject carries no tenant.
+ *
+ *  NOT a security scope — but it drifted exactly like the subject did: dev keyed
+ *  these rows under `$TENANT ?? 'acme'` and serve under `'default'`, in BOTH the
+ *  schedule and the workflow wiring, so a wakeup written by one boot path was
+ *  invisible to a waker looking under the other's key. */
+export declare const DORMANCY_WAKEUP_TENANT = "default";
+
 export declare interface DrainDeps {
     readonly store: Pick<DataStore, 'query' | 'update' | 'insert' | 'delete'>;
     readonly handlers: ReadonlyMap<string, OutboxHandlerDefinition>;
@@ -2752,7 +2772,7 @@ export declare const makeWorkflowFacadeWithCallerContext: (base: WorkflowsAppCon
 
 export declare const makeWorkflowHandlers: (workflows: ReadonlyArray<DiscoveredWorkflowLike>, facade?: WorkflowsAppContext) => Record<string, (input: unknown) => Effect.Effect<WorkflowRunHandle, unknown, unknown>>;
 
-export declare const makeWorkflowLayers: <Context>(workflows: ReadonlyArray<DiscoveredWorkflowLike<Context>>, options: WorkflowLayerOptions<Context>, wrapExecute?: (workflow: DiscoveredWorkflowLike<Context>, execute: (payload: never, executionId: string) => Effect.Effect<unknown, unknown, unknown>, callerContext: WorkflowCallerContext | undefined) => (payload: never, executionId: string) => Effect.Effect<unknown, unknown, unknown>) => ReadonlyArray<Layer.Layer<unknown, unknown, unknown>>;
+export declare const makeWorkflowLayers: <Context>(workflows: ReadonlyArray<DiscoveredWorkflowLike<Context>>, options: WorkflowLayerOptions<Context>, wrapExecute?: (workflow: DiscoveredWorkflowLike<Context>, execute: (payload: never, executionId: string) => Effect.Effect<unknown, unknown, unknown>, callerContext: ResolvedWorkflowCallerContext) => (payload: never, executionId: string) => Effect.Effect<unknown, unknown, unknown>) => ReadonlyArray<Layer.Layer<unknown, unknown, unknown>>;
 
 export declare const makeWorkflowRunHandle: (workflowName: string, executionId: string) => WorkflowRunHandle;
 
@@ -3972,6 +3992,28 @@ export declare interface ResolvedConnection {
  */
 export declare const resolveDependentTables: (descriptor: QueryDescriptor) => ReadonlySet<string>;
 
+/**
+ * A `WorkflowCallerContext` after the engine has filled in what a workflow
+ * always needs. A run started by a request carries the caller's subject; a
+ * BOOTSTRAP run — one resumed after a restart with no recorded start context —
+ * carries `SYSTEM_SUBJECT`.
+ *
+ * The engine resolves this so `buildContext` never has to. When each boot path
+ * supplied its own fallback, `voltro dev` used the dev REQUEST fallback
+ * (`anonymousSubject($TENANT ?? 'acme')`) and `voltro serve` used a tenant-less
+ * subject — the same resumed workflow read one tenant's rows in dev and every
+ * tenant's in production, with no error on either side. Same defect as the
+ * schedule path; found while fixing it.
+ */
+export declare interface ResolvedWorkflowCallerContext extends WorkflowCallerContext {
+    /** Never absent — the caller's subject, or `SYSTEM_SUBJECT` for a bootstrap
+     *  run. Typed `unknown` to match `WorkflowCallerContext.subject`; the CLI
+     *  narrows it to `Subject` at the one place it builds the AppContext. */
+    readonly subject: unknown;
+    /** Never absent — the caller's trace id, or `'workflow-bootstrap'`. */
+    readonly traceId: string;
+}
+
 export declare const resolveRedirectUri: (definition: OAuth2ConnectionDefinition, publicUrl: string) => string;
 
 /** Rebuild the flagged groups from the (already-committed) base rows + merge —
@@ -4456,6 +4498,19 @@ export declare const sanitizeRedirectTo: (value: string | undefined) => string;
  *  default export without importing the concrete class. */
 declare const SCHEDULE_BRAND: unique symbol;
 
+/**
+ * Who a schedule runs as — the shared `SYSTEM_SUBJECT` (see its doc comment for
+ * why one definition exists at all).
+ *
+ * What matters HERE is that the ENGINE owns it, not whoever wires the engine.
+ * The two callers owning it separately is exactly what went wrong: `voltro
+ * serve` passed a tenant-less subject while `voltro dev` passed the dev REQUEST
+ * fallback (`anonymousSubject($TENANT ?? 'acme')`) — a value meant for a
+ * login-less HTTP call, which a schedule never is. A `buildContext` that
+ * RECEIVES the subject cannot make that mistake; one that invents it can.
+ */
+export declare const SCHEDULE_SUBJECT: Subject;
+
 /** What happens to firings missed during downtime (computed on boot
  *  from the last-fired-at row). */
 export declare type ScheduleBackfillPolicy = 'skip' | 'latest' | 'all';
@@ -4575,14 +4630,17 @@ export declare interface SchedulerDeps {
      *  whose effective trigger is `external` are NOT armed by the timer
      *  loop — they fire via the HTTP endpoint. */
     readonly defaultTrigger: ScheduleTrigger;
-    /** Builds the per-firing AppContext (store + anonymous subject +
-     *  webhooks). The CLI supplies this — it knows how to wrap the
-     *  store with mixin behaviour. */
+    /** Builds the per-firing AppContext (store + webhooks). The CLI supplies
+     *  this — it knows how to wrap the store with mixin behaviour — but it does
+     *  NOT choose the subject: `SCHEDULE_SUBJECT` is handed in, so `voltro dev`
+     *  and `voltro serve` cannot disagree about who a cron runs as. */
     readonly buildContext: (input: {
         readonly traceId: string;
         readonly scheduleName: string;
         readonly trigger: ScheduleTrigger | 'manual';
         readonly runId: string | undefined;
+        /** Always `SCHEDULE_SUBJECT`. Forward it — do not construct one. */
+        readonly subject: Subject;
     }) => ScheduleContext['app'];
     /** Stable id of this process/replica (pod name, pid, …) recorded on
      *  every run row for debugging "which instance fired this." */
@@ -5074,6 +5132,26 @@ export declare interface SubscribeContext {
     readonly log: SyncLogger;
     /** Stable id derived from the file name (no `.subscribe.ts` suffix). */
     readonly id: string;
+    /**
+     * The framework's store, for reading or writing in reaction to the commit.
+     *
+     * **Runs as `SYSTEM_SUBJECT` — it is NOT tenant-scoped.** A subscriber fires
+     * from the change stream, not from a request, so there is no subject to scope
+     * to and no tenant to infer; queries see every tenant's rows. When the
+     * reaction is per-tenant, take the tenant from the row that changed
+     * (`event.new?.tenantId ?? event.old?.tenantId`) and filter on it explicitly.
+     * Writes are mixin-stamped exactly as a request-path write is, so `tenantId`
+     * on an inserted row is yours to set — nothing fills it in for you.
+     *
+     * This is the same posture a `*.cron.tsx` handler's `ctx.app.store` has, on
+     * purpose: both are post-request system work, and having them differ is how
+     * the schedule path drifted between `voltro dev` and `voltro serve`.
+     *
+     * Still absent, still deliberate: there is no workflow handle here. A
+     * subscriber is best-effort and non-durable, so "a row changed → start a
+     * workflow" belongs in a `*.reaction.tsx`, whose `act` is crash-safe.
+     */
+    readonly store: FluentStore;
 }
 
 /** Event shape passed to a subscriber handler. Same as the
@@ -5113,6 +5191,12 @@ export declare interface SubscriptionDelivery {
     readonly startMs: number;
     readonly endMs: number;
     readonly durationMs: number;
+    /** How many rows this delivery carried. A row-set subscription reports its
+     *  real length; a COMPUTED query has no row set, so it reports 1 for a
+     *  delivered value and **0 for `null`/`undefined`** — see `deliveredRowCount`.
+     *  It must never be a constant: this number is both the `rows` span attribute
+     *  and the Prometheus row histogram, and a hardcoded 1 makes "the handler
+     *  returned null" look identical to "the handler returned a value". */
     readonly rowCount: number;
 }
 
@@ -5198,6 +5282,13 @@ export { sweepRetention }
  */
 export declare const synthesizeInverse: (cs: ChangeSet) => ReadonlyArray<InverseOp>;
 
+/** The Subject non-request work runs as: a schedule firing, a workflow resumed
+ *  after a restart, a `*.subscribe.ts` handler. `tenantId: null` means
+ *  `applyTenantScope` adds no tenant filter, so system work sees every tenant
+ *  rather than one arbitrary one. See this file's header for why it is a single
+ *  shared value. */
+export declare const SYSTEM_SUBJECT: Subject;
+
 /** The context handed to a `runAsSystem` block. Mirrors the handler-facing
  *  shape: a fluent, system-scoped `store` + the resolved `subject`. */
 export declare interface SystemContext {
@@ -5936,7 +6027,7 @@ export declare interface WorkflowLayerExecutionContext {
 }
 
 export declare interface WorkflowLayerOptions<Context> {
-    readonly buildContext: (callerContext: WorkflowCallerContext | undefined, execution: WorkflowLayerExecutionContext) => Context;
+    readonly buildContext: (callerContext: ResolvedWorkflowCallerContext, execution: WorkflowLayerExecutionContext) => Context;
     readonly resolveStartContext?: (workflowName: string, executionId: string) => WorkflowCallerContext | undefined | Promise<WorkflowCallerContext | undefined>;
 }