@voltro/runtime 0.71.0 → 0.72.0

package/dist/index.d.ts

@@ -57,6 +57,7 @@ import { KvStoreShape } from '@voltro/kv';
 import { Layer } from 'effect';
 import { listRetentionConflicts } from '@voltro/database';
 import { listRetentions } from '@voltro/database';
+import { Membership } from '@voltro/protocol';
 import { Metric } from 'effect';
 import { MetricBoundaries } from 'effect';
 import { MetricReader } from '@opentelemetry/sdk-metrics';
@@ -107,8 +108,11 @@ import { TableLike } from '@voltro/database';
 import { TableName } from '@voltro/protocol';
 import { TableValidationFailed } from '@voltro/protocol';
 import { TargetRelation } from '@voltro/protocol';
+import { TENANT_SELECTIONS_TABLE } from '@voltro/database';
 import { TenantRowNotFound } from '@voltro/protocol';
 import { TenantScopeViolation } from '@voltro/protocol';
+import { tenantSelectionId } from '@voltro/database';
+import { TenantSelectionStore } from '@voltro/protocol';
 import { Tracer } from 'effect';
 import { Unauthenticated } from '@voltro/protocol';
 import { UpsertOptions } from '@voltro/database';
@@ -2134,6 +2138,11 @@ export { clearRetentions }
 /** Clear the process-wide handle (test teardown). */
 export declare const clearSystemStoreHandle: () => void;
 
+/** Forget the subject's selection: the next request resolves in the tenant
+ *  its credential names. A no-op for a subject with none, and for the types
+ *  that cannot hold one. */
+export declare const clearTenantSelection: (store: DataStore, subject: Subject) => Promise<void>;
+
 export declare interface ClientAddressInput {
     /** `socket.remoteAddress` — the only unforgeable value in the request. */
     readonly socketAddress: string | undefined;
@@ -3054,6 +3063,8 @@ export declare interface DataStoreApiKeyStoreOptions {
     readonly ensureActor?: ((actor: ApiKeyActor, store: DataStore) => Promise<void>) | undefined;
 }
 
+export declare const dataStoreDeviceStore: (store: DataStore) => DeviceStore;
+
 export declare const dataStoreIdempotencyStore: (store: DataStore) => IdempotencyStore;
 
 /** Build a durable `KvStoreShape` over a raw `DataStore`. */
@@ -3474,6 +3485,128 @@ export declare const detachForResume: (identity: ResumeIdentity, handle: {
     readonly unsubscribe: () => void;
 }, tunables?: ResumeTunables, now?: () => number) => void;
 
+export declare interface DeviceActor {
+    readonly id: string;
+    readonly displayName: string;
+}
+
+/** The device routes. Mounted under `basePath` (default `/v1/devices`) when
+ *  `devices` is on. `pair`, list and `revoke` need `admin:full` or
+ *  `devices:manage`; `exchange` and `rotate` are the device's own calls and
+ *  carry no session — the one-time code and the refresh token ARE the
+ *  credential, and a wrong one is `401` with one reason for every cause. */
+export declare const deviceManagementRoutes: (service: DeviceServiceShape, basePath?: string) => ReadonlyArray<RestRouteDescriptor<any, any>>;
+
+export declare interface DeviceRow {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly name: string;
+    readonly scopes: ReadonlyArray<string> | null;
+    readonly pairingHash: string | null;
+    readonly pairingExpiresAt: number | null;
+    readonly accessHash: string | null;
+    readonly accessExpiresAt: number | null;
+    readonly refreshHash: string | null;
+    readonly refreshExpiresAt: number | null;
+    /** The refresh hash rotated OUT by the last rotation — what a replay
+     *  presents. One generation back is what a stolen-then-rotated token looks
+     *  like; older replays fail as unknown, which is refusal enough. */
+    readonly previousRefreshHash: string | null;
+    readonly generation: number;
+    readonly pairedAt: number | null;
+    readonly lastSeenAt: number | null;
+    readonly revokedAt: number | null;
+    readonly revokedReason: string | null;
+    readonly createdBy: string | null;
+    readonly createdAt: number;
+    readonly metadata?: Readonly<Record<string, unknown>> | null;
+}
+
+export declare const DEVICES_TABLE = "_voltro_devices";
+
+export declare interface DeviceServiceOptions {
+    readonly prefix?: string;
+    /** Access token lifetime. Default 15 minutes — long enough that a device
+     *  polling every minute rotates rarely, short enough that a leaked token is
+     *  a bounded problem. */
+    readonly accessTtlSeconds?: number;
+    /** Refresh token lifetime — how long a device may stay silent and still
+     *  come back. Default 30 days. */
+    readonly refreshTtlSeconds?: number;
+    /** How long an admin has between pairing and the device's exchange. Default
+     *  10 minutes. */
+    readonly pairingTtlSeconds?: number;
+}
+
+export declare interface DeviceServiceShape {
+    /** Admin-side: create the device and its one-time pairing code. */
+    readonly pair: (input: PairInput) => Promise<PairedDevice>;
+    /** Device-side, once: the pairing code for the first token pair. Null when
+     *  the code is unknown, expired, already exchanged, or the device revoked —
+     *  one answer, so the route cannot be used to tell those apart. */
+    readonly exchange: (pairingCode: string, now?: number) => Promise<DeviceTokens | null>;
+    /** Device-side, repeatedly: the current refresh token for a new pair
+     *  (`generation + 1`). A refresh token that was already rotated out is a
+     *  REPLAY: the device is revoked with reason `refresh-replay` and null is
+     *  returned. Null also for unknown / expired / revoked. */
+    readonly rotate: (refreshToken: string, now?: number) => Promise<DeviceTokens | null>;
+    /** Hash lookup used by the auth strategy: the device's identity while its
+     *  access token is live. No write — see the module note. */
+    readonly resolveAccess: (accessHash: string, now?: number) => Promise<ResolvedDevice | null>;
+    /** Revoke (irreversible). `tenantId` is the CALLER's tenant and required for
+     *  the same reason as the api-key service's: ids leak, and an admin of one
+     *  tenant must not revoke another's device by id. */
+    readonly revoke: (id: string, tenantId: string, now?: number) => Promise<boolean>;
+    readonly list: (tenantId: string) => Promise<ReadonlyArray<PublicDevice>>;
+}
+
+export declare interface DeviceStore {
+    readonly insert: (row: DeviceRow) => Promise<void>;
+    readonly findById: (id: string) => Promise<DeviceRow | null>;
+    readonly findByPairingHash: (hash: string) => Promise<DeviceRow | null>;
+    readonly findByAccessHash: (hash: string) => Promise<DeviceRow | null>;
+    readonly findByRefreshHash: (hash: string) => Promise<DeviceRow | null>;
+    readonly findByPreviousRefreshHash: (hash: string) => Promise<DeviceRow | null>;
+    readonly listByTenant: (tenantId: string) => Promise<ReadonlyArray<DeviceRow>>;
+    readonly patch: (id: string, fields: Partial<DeviceRow>) => Promise<void>;
+    /**
+     * A FENCED patch: applies `fields` only while `column` still equals
+     * `expected`, and says whether it did. Exchange and rotation are claims on
+     * a one-time secret — two exchanges of one pairing code, two rotations of
+     * one refresh token — and the claim has to be decided by the row, not by a
+     * read that both callers made a moment ago.
+     */
+    readonly claim: (id: string, column: 'pairingHash' | 'refreshHash', expected: string, fields: Partial<DeviceRow>) => Promise<boolean>;
+    /** Plant the device's `actors` row (kind `serviceAccount`) — the audit
+     *  subject its writes point at. Required, like the api-key store's: an
+     *  omitted actor row is the foreign-key failure on the first audited
+     *  insert. Idempotent. */
+    readonly ensureActor: (actor: DeviceActor) => Promise<void>;
+}
+
+/** The three token shapes, derived from ONE configured prefix so a bearer
+ *  prefix collision check (`assertNoBearerPrefixCollision`) sees one claim:
+ *  `dev_` → access `dev_…`, refresh `devr_…`, pairing `devp_…`. Refresh and
+ *  pairing tokens are never presented as bearers; their prefixes exist so a
+ *  token pasted into the wrong field is refused by shape, not by luck. */
+export declare interface DeviceTokenPrefixes {
+    readonly access: string;
+    readonly refresh: string;
+    readonly pairing: string;
+}
+
+export declare const deviceTokenPrefixes: (prefix?: string) => DeviceTokenPrefixes;
+
+/** What an exchange or a rotation hands the device. Shown once. */
+export declare interface DeviceTokens {
+    readonly deviceId: string;
+    readonly accessToken: string;
+    readonly accessExpiresAt: number;
+    readonly refreshToken: string;
+    readonly refreshExpiresAt: number;
+    readonly generation: number;
+}
+
 export { DialectReplicationAdapter }
 
 /** Field-level diff for one change. Insert → every field `undefined→value`;
@@ -5213,6 +5346,15 @@ export declare const frameworkApiKeyStrategy: (service: ApiKeyServiceShape, opts
     prefix?: string;
 }) => AuthStrategy;
 
+/** The framework device auth strategy. A device is a machine caller WITH a
+ *  tenant — a `serviceAccount` subject whose id is the device id, so audit
+ *  columns point at the device's own `actors` row. `credentialExpiresAt` is
+ *  the access token's expiry: a standing subscription opened with it ends
+ *  when the token does, and the device's next rotation re-opens it. */
+export declare const frameworkDeviceStrategy: (service: DeviceServiceShape, opts?: {
+    prefix?: string;
+}) => AuthStrategy;
+
 /** Define a gauge (set with `setMetric`). */
 export declare const gauge: (name: string, description?: string) => Metric.Metric.Gauge<number>;
 
@@ -6156,6 +6298,8 @@ export declare const makeDataLoader: (deps: LoaderDeps) => DataLoader;
  */
 export declare const makeDefaultRefilter: (subject: Subject, onError?: (error: unknown) => void) => (() => Promise<RowFilterScope>) | undefined;
 
+export declare const makeDeviceService: (store: DeviceStore, opts?: DeviceServiceOptions) => DeviceServiceShape;
+
 /** `__voltro.connections.disconnect` — forget the caller's credential. */
 export declare const makeDisconnectConnectionExecutor: (deps: ConnectionBuiltinDeps) => (input: {
     readonly connectionId: string;
@@ -6573,6 +6717,10 @@ export declare const memoryApiKeyStore: () => ApiKeyStore & {
     readonly actors: ReadonlyMap<string, MemoryActorRow>;
 };
 
+export declare const memoryDeviceStore: () => DeviceStore & {
+    readonly actors: ReadonlyMap<string, DeviceActor>;
+};
+
 /**
  * Adapter for in-memory testing. The "position" is a monotonically-
  * increasing integer tick the test controls. Primary writes bump the
@@ -6991,10 +7139,10 @@ export declare interface OAuth2ConnectionDefinition extends ConnectionDefinition
     readonly kind: 'oauth2';
     readonly authorizeUrl: string;
     readonly tokenUrl: string;
-    readonly clientId: string;
+    readonly clientId: OAuthClientCredential;
     /** Runtime secret. Never logged, never sent to the browser, never bundled —
      *  `*.connection.ts` is server-only and is NOT part of the rpcGroup codegen. */
-    readonly clientSecret: string;
+    readonly clientSecret: OAuthClientCredential;
     readonly scopes?: ReadonlyArray<string>;
     /** Exact redirect URI registered with the provider. Defaults to
      *  `<publicUrl>/_voltro/connections/<id>/callback`. */
@@ -7013,6 +7161,20 @@ export declare interface OAuth2ConnectionDefinition extends ConnectionDefinition
     readonly identify?: (tokens: ConnectionTokens) => Promise<ConnectionAccount>;
 }
 
+/**
+ * A credential as the file states it: the string, or a thunk that produces it.
+ *
+ * The thunk exists because of WHEN a `*.connection.ts` is evaluated. Discovery
+ * imports it before the env gate has run — `voltro doctor` runs no gate at all —
+ * and `serverEnv.X` read at module top level throws there by design. A thunk
+ * defers the read to the moment the connection is used (an authorize URL, a
+ * token exchange), which is always after the gate. `oauthCredentialValue` is the
+ * one reader.
+ */
+export declare type OAuthClientCredential = string | (() => string);
+
+export declare const oauthCredentialValue: (credential: OAuthClientCredential) => string;
+
 /** One recorded `(procedure → table, op)` edge. */
 export declare interface ObservedEdge {
     readonly tag: string;
@@ -7336,6 +7498,25 @@ declare interface P2COptions {
     readonly random?: () => number;
 }
 
+export declare interface PairedDevice {
+    readonly id: string;
+    readonly name: string;
+    readonly tenantId: string;
+    readonly scopes: ReadonlyArray<string>;
+    /** Shown ONCE. Exchanged for the first token pair, then gone. */
+    readonly pairingCode: string;
+    readonly pairingExpiresAt: number;
+}
+
+export declare interface PairInput {
+    readonly tenantId: string;
+    readonly name: string;
+    readonly scopes?: ReadonlyArray<string>;
+    /** WHO PAIRED IT. Provenance. */
+    readonly createdBy?: string | null;
+    readonly metadata?: Readonly<Record<string, unknown>> | null;
+}
+
 /**
  * Parse an interval string (`'30m'`, `'4h'`, `'7d'`) to ms, or `null`.
  * A local copy for the same reason `finops.ts` keeps one — this module must not
@@ -7602,6 +7783,22 @@ export declare interface PublicApiKey {
     readonly metadata?: Readonly<Record<string, unknown>> | null;
 }
 
+export declare interface PublicDevice {
+    readonly id: string;
+    readonly name: string;
+    readonly tenantId: string;
+    readonly scopes: ReadonlyArray<string>;
+    readonly generation: number;
+    readonly pairedAt: number | null;
+    readonly lastSeenAt: number | null;
+    readonly accessExpiresAt: number | null;
+    readonly revokedAt: number | null;
+    readonly revokedReason: string | null;
+    readonly createdAt: number;
+    readonly createdBy: string | null;
+    readonly metadata?: Readonly<Record<string, unknown>> | null;
+}
+
 /**
  * Validate, size-check and publish one event.
  *
@@ -8831,6 +9028,17 @@ export declare interface ResolvedConnection {
     readonly accountLabel: string | null;
 }
 
+/** What the auth strategy learns from a presented access token. */
+export declare interface ResolvedDevice {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly name: string;
+    readonly scopes: ReadonlyArray<string>;
+    readonly generation: number;
+    readonly accessExpiresAt: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
 /**
  * Walk a query descriptor's eager-load tree and return the FULL set
  * of tables whose changes could affect the resolved snapshot.
@@ -10547,6 +10755,20 @@ export declare class SelectBuilder {
     get descriptor(): QueryDescriptor;
 }
 
+/**
+ * Select `tenantId` as the subject's active tenant — verified against
+ * `memberships` through the one rule (`selectSubjectTenant`), then stored.
+ * Returns the subject as it will resolve on the next request. Throws
+ * `TenantSelectionRefused` when the target is not among the memberships or
+ * the subject is of a type that has no tenant; nothing is written then.
+ *
+ * Three lines in an app's mutation:
+ *
+ *     const memberships = await myMemberships(ctx.subject)
+ *     return selectTenant(ctx.store, ctx.subject, input.tenantId, memberships)
+ */
+export declare const selectTenant: (store: DataStore, subject: Subject, tenantId: string, memberships: ReadonlyArray<Membership>) => Promise<Subject>;
+
 /** A guard, flattened to something a row can hold. */
 export declare type SerializedGuard = {
     readonly kind: 'scope';
@@ -10714,6 +10936,8 @@ export declare const setTupleSource: (source: TupleSource | undefined) => void;
 
 export declare const sha256Hex: (input: string) => string;
 
+export declare const sha256HexOf: (input: string) => string;
+
 export declare type ShapeClassification = {
     readonly maintainable: true;
     readonly shape: AggregateShape;
@@ -11360,6 +11584,8 @@ export declare interface TableRoutingStats {
 
 export { TableValidationFailed }
 
+export { TENANT_SELECTIONS_TABLE }
+
 /** The standing compute-cost attribution for one tenant — the chargeback /
  *  showback row + the "why is my bill high" breakdown. Maintained incrementally:
  *  every `CostEvent` folds into `total`, `byUnit`, and `bySubscription` in O(1).
@@ -11380,6 +11606,14 @@ export { TenantRowNotFound }
 
 export { TenantScopeViolation }
 
+export { tenantSelectionId }
+
+/** The framework's `TenantSelectionStore` over `_voltro_tenant_selections`.
+ *  Lazy on the store for the same reason the resolver is: dev builds the
+ *  store after the auth chain. A read before the store exists throws, and
+ *  the composer turns that into a fail-closed `Unauthenticated`. */
+export declare const tenantSelectionStore: (getStore: () => DataStore | undefined) => TenantSelectionStore;
+
 /** The statuses a run never leaves — where a poller stops.
  *
  *  `skipped` is terminal and is NOT a failure: it means the overlap policy
@@ -12311,6 +12545,17 @@ export declare interface WorkflowDefinitionLike {
     toLayer(execute: (payload: never, executionId: string) => Effect.Effect<unknown, unknown, unknown>): Layer.Layer<unknown, unknown, unknown>;
 }
 
+/** `__voltro.workflow.domainEvents` — the caller's domain events, newest first. */
+export declare const workflowDomainEventsExecutor: (input: {
+    readonly name?: string;
+    readonly limit?: number;
+}, ctx: WorkflowReadCtx) => Promise<ReadonlyArray<unknown>>;
+
+/** `__voltro.workflow.event.deliveries` — the deliveries of one visible event. */
+export declare const workflowEventDeliveriesExecutor: (input: {
+    readonly eventId: string;
+}, ctx: WorkflowReadCtx) => Promise<ReadonlyArray<unknown>>;
+
 export declare interface WorkflowEventEmitOptions {
     readonly id?: string;
     readonly source?: string;
@@ -12494,6 +12739,20 @@ export declare interface WorkflowLayerOptions<Context> {
      * whose business logic said no.
      */
     readonly resolveAuthority?: (identity: unknown) => Promise<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
+     * "Fiber terminated" and nothing else. Hosts wire this to an error log.
+     */
+    readonly reportExecutionRefusal?: (refusal: {
+        readonly workflowName: string;
+        readonly executionId: string;
+        readonly reason: string;
+    }) => void;
 }
 
 /**
@@ -12547,6 +12806,14 @@ export declare class WorkflowRateLimitedError extends Error {
     constructor(workflowName: string, retryAfterMs: number);
 }
 
+/** The slice of AppContext these executors need. */
+export declare interface WorkflowReadCtx {
+    readonly store: Pick<DataStore, 'query'>;
+    readonly request?: {
+        readonly subject?: Subject | null;
+    } | undefined;
+}
+
 /** Result of {@link WorkflowsAppContext.redrive} — whether the failed run's
  *  durable journal was re-driven, how many failed step attempts were reset so
  *  they re-execute, and a `reason` when it declined (no journal / still
@@ -12571,6 +12838,22 @@ export declare interface WorkflowRetryResult {
     readonly executionId: string;
 }
 
+/**
+ * May `caller` read a row owned by `rowSubject`? Exported so the rule has one
+ * spelling and a test can pin it without a store.
+ */
+export declare const workflowRowVisibleTo: (caller: Subject | null, rowSubject: unknown) => boolean;
+
+/** `__voltro.workflow.run.events` — the lifecycle events of one visible run. */
+export declare const workflowRunEventsExecutor: (input: {
+    readonly runId: string;
+}, ctx: WorkflowReadCtx) => Promise<ReadonlyArray<unknown>>;
+
+/** `__voltro.workflow.run` — one run by id or execution id. */
+export declare const workflowRunExecutor: (input: {
+    readonly id: string;
+}, ctx: WorkflowReadCtx) => Promise<ReadonlyArray<unknown>>;
+
 /** Filter passed to {@link WorkflowsAppContext.listRuns}. All fields are
  *  optional; an empty filter returns the most-recent runs across every
  *  workflow. `workflowName` and `tag` are aliases for the same column. */
@@ -12625,12 +12908,24 @@ export declare interface WorkflowRunRecord {
  *  stored column exactly. */
 export declare type WorkflowRunRecordStatus = 'running' | 'succeeded' | 'failed' | 'cancelled' | 'suspended';
 
+/** `__voltro.workflow.runs` — the caller's runs, newest first. */
+export declare const workflowRunsExecutor: (input: {
+    readonly tag?: string;
+    readonly status?: string;
+    readonly limit?: number;
+}, ctx: WorkflowReadCtx) => Promise<ReadonlyArray<unknown>>;
+
 export declare type WorkflowRunSnapshot<Success = unknown> = Omit<WorkflowRunSnapshot_2, 'output'> & {
     readonly output?: Success;
 };
 
 export declare type WorkflowRunStatus = 'running' | 'succeeded' | 'failed' | 'cancelled' | 'suspended' | 'unknown';
 
+/** `__voltro.workflow.run.steps` — the steps of one visible run. */
+export declare const workflowRunStepsExecutor: (input: {
+    readonly runId: string;
+}, ctx: WorkflowReadCtx) => Promise<ReadonlyArray<unknown>>;
+
 /** Typed projection of a `_voltro_workflow_runs` row, returned by
  *  {@link WorkflowsAppContext.listRuns}. Timestamps are `Date`s (the SDK
  *  hydrates the stored values for app code; the wire/inspect path keeps
@@ -12670,6 +12965,20 @@ export declare interface WorkflowsAppContext {
     readControl(target: WorkflowControlTarget): Promise<WorkflowControlResult>;
     cancelQueued(target: WorkflowQueuedControlTarget, options?: WorkflowQueuedControlOptions): Promise<WorkflowQueuedCancellationResult>;
     readQueuedCancellation(target: WorkflowQueuedControlTarget, options?: Pick<WorkflowQueuedControlOptions, 'callerContext'>): Promise<WorkflowQueuedCancellationResult>;
+    /** What a recorded start handle has become — queued, accepted under an
+     *  execution, or never to run — read once, without waiting. A queued handle
+     *  is resolved through its durable receipt, so the answer survives the
+     *  process that recorded the handle. */
+    readStart(handle: WorkflowRunHandle, options?: Pick<WorkflowWaitOptions, 'callerContext'>): Promise<WorkflowStartObservation>;
+    /**
+     * Set on the facade a mutation TRANSACTION hands out: every start it records
+     * is provisional until the transaction commits, so nothing about a start can
+     * be observed through it — `readStart` refuses. A reconciler that would
+     * otherwise read pending starts (the flow cadence tick) checks this and
+     * leaves them to the next tick that runs outside a transaction, rather than
+     * reporting the refusal as a failure of each row.
+     */
+    readonly startsDeferredUntilCommit?: true;
     signal(target: WorkflowSignalTarget, signalName: string, payload?: unknown): Promise<{
         readonly eventId: string;
     }>;
@@ -12740,6 +13049,27 @@ declare const WorkflowStartNotExecuted_base: Schema.TaggedErrorClass<WorkflowSta
     incumbentExecutionId: Schema.NullOr<typeof Schema.String>;
 }>;
 
+/**
+ * What a start handle has become, read once and without waiting.
+ *
+ * `pending` — still queued (or submitted and not yet acknowledged). `accepted`
+ * — the engine owns it under `executionId`; poll that. `not-executed` — it will
+ * never run: the same reasons `WorkflowStartNotExecuted` carries, as a value
+ * rather than a throw, because a reconciler asking "what happened to the start
+ * I recorded" wants an answer, not an exception per row.
+ */
+export declare type WorkflowStartObservation = {
+    readonly kind: 'pending';
+} | {
+    readonly kind: 'accepted';
+    readonly executionId: string;
+} | {
+    readonly kind: 'not-executed';
+    readonly reason: WorkflowStartNotExecuted['reason'];
+    readonly failureId: string | null;
+    readonly incumbentExecutionId: string | null;
+};
+
 export declare interface WorkflowStartOptions {
     /* Excluded from this release type: preparedExecutionId */
     readonly wait?: boolean;