@voltro/runtime 0.71.1 → 0.73.0

package/THIRD-PARTY-NOTICES.md

@@ -5,7 +5,7 @@ property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/runtime itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (52 packages).
+Generated from the resolved runtime dependency closure (53 packages).
 
 ---
 
@@ -37,6 +37,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## @effect/experimental@0.61.1
+
+License: MIT
+
+```
+MIT License
+
+Copyright (c) 2023-present The Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## @effect/platform-node@0.108.1
 
 License: MIT

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { ChangeEvent } from '@voltro/database';
 import { classifyConstraintViolation } from '@voltro/database';
 import { clearRetentions } from '@voltro/database';
 import { ColumnBuilder } from '@voltro/database';
+import { ColumnDefinition } from '@voltro/database';
 import { ConnectionCredential } from '@voltro/protocol';
 import { ConnectionInfo } from '@voltro/protocol';
 import { ConnectionInfoMiddleware } from '@voltro/protocol';
@@ -43,6 +44,8 @@ import { HttpRequestInterceptor } from '@voltro/protocol';
 import { HttpRouteObserver } from '@voltro/protocol';
 import { IdempotencyStore } from '@voltro/protocol';
 import { IdScheme } from '@voltro/database';
+import { InferInsertRow } from '@voltro/database';
+import { InferRow } from '@voltro/database';
 import { InMemoryMetricExporter } from '@opentelemetry/sdk-metrics';
 import { InMemorySpanExporter } from '@opentelemetry/sdk-trace-base';
 import { InsertIgnoreResult } from '@voltro/database';
@@ -57,6 +60,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 +111,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';
@@ -872,6 +879,9 @@ declare type AnyRow = Record<string, unknown>;
 
 declare type AnyRow_2 = Record<string, unknown>;
 
+/** Any table — the loose shape these helpers accept structurally. */
+declare type AnyWritableTable = Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>;
+
 /** Locked-down policy for an API response. Nothing loads, nothing frames it. */
 export declare const API_CSP = "default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'";
 
@@ -2134,6 +2144,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 +3069,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 +3491,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`;
@@ -3809,6 +3948,23 @@ export declare interface DrainResult {
  */
 export declare const dueWakeups: (store: DataStore, now: Date, limit?: number) => Promise<ReadonlyArray<Wakeup>>;
 
+/** The minimal Effect-store surface `insertIgnoreRowOutcomeEffect` needs. */
+export declare interface EffectInsertIgnoreOutcomeStore {
+    readonly insertIgnoreWithOutcome: (table: string, row: Row, options: {
+        readonly conflictColumns: ReadonlyArray<string>;
+    }) => Effect.Effect<InsertIgnoreResult, StoreError>;
+}
+
+/** The minimal Effect-store surface `insertManyRowsEffect` needs. */
+export declare interface EffectInsertManyStore {
+    readonly insertMany: (table: string, rows: ReadonlyArray<Row>) => Effect.Effect<ReadonlyArray<Row>, StoreError>;
+}
+
+/** The minimal Effect-store surface `insertRowEffect` needs. */
+export declare interface EffectInsertStore {
+    readonly insert: (table: string, row: Row) => Effect.Effect<Row, StoreError>;
+}
+
 /** The subject's effective relations on the resource — direct tuples expanded
  *  by the policy's implications. */
 export declare const effectiveRelations: (subject: RebacSubject, resource: RebacResource, tuples: ReadonlyArray<RelationTuple>, policy: ResourcePolicy) => ReadonlySet<string>;
@@ -3886,6 +4042,24 @@ export declare interface EffectStoreOps {
     readonly transactional: <A, E, R>(work: (transaction: EffectStoreOps) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | StoreError, R>;
 }
 
+/**
+ * The minimal Effect-store surface `upsertRowOutcomeEffect` needs.
+ *
+ * NOT optional, unlike `TypedUpsertOutcomeStore.upsertWithOutcome`. The Promise
+ * form has to tolerate a hand-written `DataStore` that lacks the method and
+ * throws when it does; `EffectStoreOps` always provides it, so the refusal has
+ * no state to describe. An error case for an unreachable condition is one every
+ * caller must handle and none can trigger.
+ */
+export declare interface EffectUpsertOutcomeStore {
+    readonly upsertWithOutcome: (table: string, row: Row, options: UpsertOptions) => Effect.Effect<UpsertResult, StoreError>;
+}
+
+/** The minimal Effect-store surface `upsertRowEffect` needs. */
+export declare interface EffectUpsertStore {
+    readonly upsert: (table: string, row: Row, options: UpsertOptions) => Effect.Effect<Row, StoreError>;
+}
+
 /** Empty registry — handy for tests + the rare bootstrap path with no
  *  discovered tables. */
 export declare const emptySchemaRegistry: SchemaRegistry;
@@ -5213,6 +5387,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>;
 
@@ -5449,6 +5632,25 @@ export declare class InMemoryDataStore implements DataStore {
     injectExternalChange(event: ChangeEvent): void;
 }
 
+/** `insertIgnore`, typed against the table, plus whether it inserted or found the row. */
+export declare const insertIgnoreRowOutcomeEffect: <T extends AnyWritableTable>(store: EffectInsertIgnoreOutcomeStore, table: T, row: InferInsertRow<T>, options: {
+    readonly conflictColumns: ReadonlyArray<keyof InferRow<T> & string>;
+}) => Effect.Effect<{
+    readonly row: InferRow<T>;
+    readonly outcome: "inserted" | "ignored";
+}, StoreError>;
+
+/** `insertRowEffect`'s batch — every element checked against `InferInsertRow<T>`. */
+export declare const insertManyRowsEffect: <T extends AnyWritableTable>(store: EffectInsertManyStore, table: T, rows: ReadonlyArray<InferInsertRow<T>>) => Effect.Effect<ReadonlyArray<InferRow<T>>, StoreError>;
+
+/**
+ * Insert a row, typed against the table, on the Effect channel.
+ *
+ *     const store = yield* EffectStore
+ *     const saved = yield* insertRowEffect(store, players, { tenantId, name })
+ */
+export declare const insertRowEffect: <T extends AnyWritableTable>(store: EffectInsertStore, table: T, row: InferInsertRow<T>) => Effect.Effect<InferRow<T>, StoreError>;
+
 export { InspectedStep }
 
 export { InspectedWorkflow }
@@ -6156,6 +6358,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 +6777,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 +7199,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 +7221,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 +7558,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 +7843,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 +9088,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 +10815,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 +10996,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 +11644,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 +11666,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
@@ -11749,6 +12043,13 @@ export declare type TupleSource = (req: {
  *  view it obtained from the dialect store directly. */
 export declare const TX_READ_VERSIONS_KEY: unique symbol;
 
+/** `conflictColumns` / `update` / `updateValues`, constrained to the table's own columns. */
+declare interface TypedUpsertOptions<T extends AnyWritableTable> {
+    readonly conflictColumns: ReadonlyArray<keyof InferRow<T> & string>;
+    readonly update?: ReadonlyArray<keyof InferRow<T> & string> | ((existing: InferRow<T>) => Readonly<Partial<InferRow<T>>>);
+    readonly updateValues?: Readonly<Partial<Omit<InferRow<T>, 'id'>>>;
+}
+
 /**
  * Drop everything this connection accumulated. Called by the transport finalizer
  * and by explicit sign-out flows. Idempotent.
@@ -11906,6 +12207,15 @@ export declare class UpdateBuilder {
     restore(): Promise<number>;
 }
 
+/** Upsert a row, typed against the table, on the Effect channel. */
+export declare const upsertRowEffect: <T extends AnyWritableTable>(store: EffectUpsertStore, table: T, row: InferInsertRow<T>, options: TypedUpsertOptions<T>) => Effect.Effect<InferRow<T>, StoreError>;
+
+/** `upsertRowEffect`, plus whether the row was INSERTED or UPDATED. */
+export declare const upsertRowOutcomeEffect: <T extends AnyWritableTable>(store: EffectUpsertOutcomeStore, table: T, row: InferInsertRow<T>, options: TypedUpsertOptions<T>) => Effect.Effect<{
+    readonly row: InferRow<T>;
+    readonly outcome: "inserted" | "updated";
+}, StoreError>;
+
 /**
  * Sugar for `yield* AggregateRegistry` + `.getHandle(def)`. The
  * type-safe entry point for reading an aggregate from a handler.
@@ -12311,6 +12621,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 +12815,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 +12882,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 +12914,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 +12984,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 +13041,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 +13125,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;