@voltro/protocol 0.71.1 → 0.72.0

package/dist/index.d.ts

@@ -835,6 +835,32 @@ export declare const composeAuthStrategies: (strategies: ReadonlyArray<AuthStrat
      * `fallback` is supplied (the fallback owns that decision).
      */
     readonly anonymousTenantRequired?: boolean;
+    /**
+     * The ONE tenant every anonymous caller resolves to — chosen by the server,
+     * never by the request. When set, the `x-tenant` header is not consulted:
+     * a client naming its own tenant is exactly the thing a fixed anonymous
+     * tenant exists to rule out. Ignored when `fallback` is supplied (that
+     * function owns the anonymous subject).
+     */
+    readonly anonymousTenantId?: string;
+    /**
+     * The subject's memberships — the ONE source, strategy-independent. Read
+     * only when a stored tenant selection exists for the subject and names a
+     * tenant other than the credential's, and then on every such request: a
+     * membership revoked a moment ago must not keep a selection alive, and a
+     * switch made a moment ago must be visible on the next call, so there is
+     * no staleness window to configure here. Requires `tenantSelection`.
+     */
+    readonly memberships?: MembershipsSource;
+    /**
+     * Where a subject's tenant selection is stored. Read for every matched
+     * user / apiKey / serviceAccount subject (one point lookup); a stored
+     * tenant the memberships no longer cover is ignored AND cleared here —
+     * the revocation of a membership revokes the selection. Requires
+     * `memberships`; with only one of the two configured the step does not
+     * run, and the composer says so at compose time.
+     */
+    readonly tenantSelection?: TenantSelectionStore;
     /**
      * Add scopes to a resolved Subject from a source the strategy could not
      * see — typically a role stored in the app's own database.
@@ -1828,6 +1854,12 @@ export declare interface DeleteTarget<Input = unknown> extends NestedTargetField
     readonly identify?: ((input: Input) => string | ReadonlyArray<string>) | undefined;
 }
 
+/** Pair, list and revoke devices (`devices: true`) for the caller's tenant.
+ *  One scope, not three: a device always acts as itself, in the pairer's
+ *  tenant, so there is no self / org / other distinction to draw.
+ *  `admin:full` satisfies it, as it does every scope. */
+export declare const DEVICES_MANAGE_SCOPE = "devices:manage";
+
 export declare const diffRows: (prev: ReadonlyArray<PatchRow>, next: ReadonlyArray<PatchRow>, options?: DiffRowsOptions) => RowPatch;
 
 /**
@@ -2622,6 +2654,8 @@ export declare const isReactivityChannelKey: (key: string) => boolean;
 
 export declare const isSystemSubject: (subject: Subject) => boolean;
 
+export declare const isTenantSelectable: (subject: Subject) => subject is TenantSelectableSubject;
+
 /**
  * Is this descriptor allowed on the wire at all?
  *
@@ -2670,6 +2704,19 @@ export declare const makeScopeCache: (options?: ScopeCacheOptions) => ScopeCache
  */
 export declare const MAX_EVENT_ENVELOPE_BYTES = 7500;
 
+/** One tenant a subject belongs to. `role` is whatever the app's membership
+ *  source knows — it rides along onto `metadata.memberships` and nothing here
+ *  interprets it. */
+export declare interface Membership {
+    readonly tenantId: string;
+    readonly role?: string;
+}
+
+/** The app's ONE source of memberships, strategy-independent: the auth plugin
+ *  answers from its `memberships` table (`authMemberships(userStore)`), an IdP
+ *  project from wherever it keeps them. `input.store` is the app's DataStore. */
+export declare type MembershipsSource = (subject: Subject, input: AuthStrategyInput) => Promise<ReadonlyArray<Membership>> | ReadonlyArray<Membership>;
+
 /** In-memory store — the default for single-process dev + the test double. */
 export declare const memoryIdempotencyStore: () => IdempotencyStore;
 
@@ -3121,6 +3168,10 @@ export declare interface PluginCacheHandle {
     }) => Effect.Effect<void, unknown>;
 }
 
+export declare interface PluginCapabilities {
+    readonly mediaPersist?: PluginMediaPersistCapability;
+}
+
 /**
  * Post-commit change event delivered to a plugin's `onChangeEvent` tap.
  * Minimal, browser-safe shape (protocol must not depend on the database
@@ -3788,6 +3839,31 @@ export declare interface PluginLifecycleContext {
     readonly config: unknown;
 }
 
+/** Where the offloaded-inference dispatcher puts a media artifact a provider
+ *  produced. Every call names its `operationId` — the queued job, its attempt
+ *  and the artifact's index — so a store that supports resumable puts stores
+ *  one object however often the dispatcher is retried. */
+export declare interface PluginMediaPersistCapability {
+    readonly put: (args: {
+        readonly bytes: Uint8Array;
+        readonly mediaType: string;
+        readonly tenantId: string | null;
+        readonly operationId: string;
+    }) => Promise<{
+        readonly url: string;
+        readonly refId: string;
+    }>;
+    /** Re-host a provider URL. Absent → the provider's URL is handed on as-is. */
+    readonly ingestUrl?: (args: {
+        readonly url: string;
+        readonly tenantId: string | null;
+        readonly operationId: string;
+    }) => Promise<{
+        readonly url: string;
+        readonly refId: string;
+    }>;
+}
+
 export declare interface PluginMigration {
     readonly id: string;
     readonly description?: string;
@@ -5217,6 +5293,23 @@ declare const ScopeError_base: Schema.TaggedErrorClass<ScopeError, "ScopeError",
  *  resolver already has. */
 export declare type ScopeResolverResult = ReadonlyArray<string> | ScopeDecision;
 
+/**
+ * The subject with `tenantId` selected — or a refusal.
+ *
+ * The memberships are the caller's to supply because they are the caller's to
+ * know: the auth plugin reads its `memberships` table, an IdP project reads
+ * its own. Whatever the source, the check is this one line, and the list is
+ * written onto `metadata.memberships` in the shape the auth plugin already
+ * uses (`subjectMemberships(subject)` reads it), so a client can render the
+ * switch from any subject the same way.
+ *
+ * Everything else on the subject — scopes, other metadata — passes through
+ * untouched: a selection changes WHERE the subject acts, not what it may do.
+ * Authority for the selected tenant is the resolver's business, which is why
+ * `composeAuthStrategies` applies the selection BEFORE `resolveScopes`.
+ */
+export declare const selectSubjectTenant: (subject: Subject, tenantId: string, memberships: ReadonlyArray<Membership>) => Subject;
+
 export declare interface ServerErrorEvent {
     /** The thrown value (Error | tagged error | anything). */
     readonly error: unknown;
@@ -5861,6 +5954,48 @@ declare const TenantScopeViolation_base: Schema.TaggedErrorClass<TenantScopeViol
     reason: typeof Schema.String;
 }>;
 
+/** The subject types a selection can apply to: those with an id AND a tenant.
+ *  `anonymous` has no id to remember a selection under; `system` has no
+ *  tenant by construction. */
+export declare type TenantSelectableSubject = Extract<Subject, {
+    type: 'user' | 'apiKey' | 'serviceAccount';
+}>;
+
+/** The identity a selection is remembered under — the two fields that name a
+ *  subject across credentials. A selection outlives the credential that made
+ *  it, which is the point: the next JWT, the next API-key call, finds it. */
+export declare interface TenantSelectionIdentity {
+    readonly type: TenantSelectableSubject['type'];
+    readonly id: string;
+}
+
+/** Refused by name: the target is not among the subject's memberships, or the
+ *  subject is of a type that has no tenant to select. A typed error so a
+ *  mutation can map it to a response instead of matching on a message. */
+export declare class TenantSelectionRefused extends TenantSelectionRefused_base {
+}
+
+declare const TenantSelectionRefused_base: Schema.TaggedErrorClass<TenantSelectionRefused, "TenantSelectionRefused", {
+    readonly _tag: Schema.tag<"TenantSelectionRefused">;
+} & {
+    subjectType: typeof Schema.String;
+    subjectId: Schema.NullOr<typeof Schema.String>;
+    tenantId: typeof Schema.String;
+    reason: Schema.Literal<["not-a-member", "subject-has-no-tenant"]>;
+}>;
+
+/** Where `composeAuthStrategies` finds a stored selection. `@voltro/runtime`'s
+ *  `tenantSelectionStore(store)` is the framework's implementation over the
+ *  `_voltro_tenant_selections` table; the interface is here so the composer
+ *  stays free of any store. */
+export declare interface TenantSelectionStore {
+    /** The selected tenant, or null when none is stored. */
+    readonly read: (identity: TenantSelectionIdentity) => Promise<string | null>;
+    /** Forget a selection — called by the composer when the stored tenant is no
+     *  longer among the subject's memberships. */
+    readonly clear: (identity: TenantSelectionIdentity) => Promise<void>;
+}
+
 export declare const toRpc: <Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: QueryProcedureDescriptor<Name, Input, Output, Err> | MutationProcedureDescriptor<Name, Input, Output, Err> | ActionProcedureDescriptor<Name, Input, Output, Err> | StreamProcedureDescriptor<Name, Input, Output, Err>) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Schema.Union<[Schema.Struct<{
     _tag: Schema.Literal<["snapshot"]>;
     revision: typeof Schema.Number;
@@ -6350,6 +6485,17 @@ export declare interface VoltroPlugin {
      * keeps working unchanged.
      */
     readonly bindDataStore?: (store: DataStore, ctx?: PluginBindContext) => void;
+    /**
+     * Capabilities this plugin offers to OTHER framework machinery, by name.
+     *
+     * The framework reads them from the plugin instance at boot — a plugin that
+     * holds the app's storage can hand the offloaded-inference dispatcher the
+     * function that persists a generated media artifact, without the dispatcher
+     * depending on the plugin or the plugin on the dispatcher. Functions here
+     * close over the plugin's bound state, so they are read lazily and called
+     * after `bindDataStore`.
+     */
+    readonly capabilities?: PluginCapabilities;
     /**
      * Post-commit ChangeEvent tap — an `Effect<void, E>` the runtime SUPERVISES.
      * Fires for EVERY committed store change (insert/update/delete on any table),