@nylorun/runtime 0.10.0-beta → 0.12.0-beta

package/dist/tenant/transcript.js

@@ -0,0 +1,58 @@
+/** The model's tool call id and the harness invocation, for tool effects and tool actions. */
+export function toolIds(context) {
+    const c = context;
+    return typeof c?.callId === "string" && typeof c.invocationId === "string"
+        ? { callId: c.callId, invocationId: c.invocationId }
+        : {};
+}
+const agentOf = (request) => request.agent ? { agent: request.agent } : {};
+/**
+ * `message.assistant` for a completed model effect: the step's text and tool calls. The
+ * provider returns a `ModelCandidate` or a bare string; anything else writes no event.
+ */
+export function assistantMessage(request, value) {
+    const invocationId = request.context
+        ?.invocationId;
+    if (typeof invocationId !== "string")
+        return undefined;
+    const blocks = typeof value === "string"
+        ? [{ type: "text", text: value }]
+        : Array.isArray(value?.output)
+            ? value.output
+            : [];
+    let text = "";
+    const toolCalls = [];
+    for (const block of blocks) {
+        if (block?.type === "text" && typeof block.text === "string")
+            text += block.text;
+        else if (block?.type === "tool-call" &&
+            typeof block.id === "string" &&
+            typeof block.name === "string")
+            toolCalls.push({ callId: block.id, name: block.name, input: block.args });
+    }
+    if (!text && toolCalls.length === 0)
+        return undefined;
+    return { invocationId, text, toolCalls, ...agentOf(request) };
+}
+/** `tool.completed` for an MCP or sandbox tool: its output, or the tool error it reported. */
+export function toolCompleted(request, value) {
+    const ids = toolIds(request.context);
+    if (!("callId" in ids))
+        return undefined;
+    const outcome = value;
+    const result = outcome?.kind === "failed"
+        ? {
+            error: {
+                code: String(outcome.code ?? "tool.failed"),
+                message: String(outcome.message ?? ""),
+            },
+        }
+        : { output: outcome?.kind === "completed" ? outcome.output : value };
+    return {
+        ...ids,
+        capabilityId: request.capabilityId,
+        toolName: request.toolName,
+        ...result,
+        ...agentOf(request),
+    };
+}

package/dist/tenant/types.d.ts

@@ -1,17 +1,20 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { AdminTenant, AdminTenantStatus, HostAggregate, TenantEnvelope } from "@nylorun/core/contracts";
 import type { FlowLimits } from "../core/limits.js";
+import type { SessionStore } from "../store/types.js";
 import type { SandboxBackend } from "../sandbox/types.js";
+import type { TenantWorker } from "./worker.js";
 export type TenantMode = "shared" | "ephemeral" | "test";
+/**
+ * The Tenant directory on the Host root. The Tenant's data lives in its store (a Postgres
+ * schema); this holds what stays on the Host: the vault key, plugin data, logs, and the
+ * private home, tmp and sandbox directories.
+ */
 export interface TenantPaths {
     root: string;
-    envelope: string;
-    database: string;
-    lock: string;
     kek: string;
     home: string;
     tmp: string;
-    migration: string;
     sandboxes: string;
     pluginData: string;
     logs: string;
@@ -34,12 +37,20 @@ export interface TenantConfig {
     mode: TenantMode;
     paths: TenantPaths;
     sandbox: {
-        backend: "auto" | "microsandbox" | "virtual";
+        backend: "auto" | "virtual";
         backends?: readonly SandboxBackend[];
     };
     model: TenantModelConfig;
     childEnv: Readonly<Record<string, string>>;
+    /** Action claim lease. Default 30 s. */
     leaseMs?: number;
+    /** Ownership lease of an advance (§10.6); renewed every third while it runs. Default 30 s. */
+    ownerLeaseMs?: number;
+    /**
+     * Delay between Tenant sweep passes when the Tenant runs its own in-process execution.
+     * Default `min(leaseMs, 5 s)`. A Host-level execution sets its own.
+     */
+    sweepIntervalMs?: number;
     /** Operator flow limits (`RuntimeOptions.flow` / `workflows.md` §13). */
     flow?: Partial<FlowLimits>;
     /**
@@ -61,13 +72,19 @@ export interface TenantSummary {
     connectedExecutors: number;
     pendingActions: number;
     uncertainEffects: number;
+    /** Events committed but not yet relayed to Durable Streams. */
+    outboxDepth?: number;
+    /** The oldest unrelayed event's age; 0 when none waits. */
+    relayLagMs?: number;
 }
 /** An open Tenant Runtime. Created only by the Tenant module. */
 export interface TenantHandle {
     readonly envelope: TenantEnvelope;
+    /** The handlers Durable Session Execution calls for this Tenant (`worker.ts`). */
+    readonly worker?: TenantWorker;
     /** Headers already validated by the Host. Authenticates, authorizes, dispatches. */
     handle(request: IncomingMessage, response: ServerResponse, url: URL): Promise<void>;
-    summary(): TenantSummary;
+    summary(): Promise<TenantSummary>;
     /** Stop scheduling; wait for or cancel active turns. */
     drain(activeWork: "drain" | "cancel", timeoutMs?: number): Promise<void>;
     close(): Promise<void>;
@@ -82,22 +99,43 @@ export type TenantResolution = {
     quarantine: Quarantine;
 };
 export interface Quarantine {
-    code: "locked" | "kek-missing" | "corrupt" | "schema-too-new" | "migration-failed" | "envelope-invalid" | "open-timeout" | "open-failed";
+    code: "kek-missing" | "corrupt" | "schema-too-new" | "migration-failed" | "envelope-invalid" | "open-timeout" | "open-failed";
     message: string;
     repair: string;
-    lockPath?: string;
-    lockPid?: number;
 }
 export interface BootstrapPrincipal {
     principalId: string;
     credentialHash: string;
     idempotencyKey: string;
+    /** When set, also registers application principal `studio` with this hash. */
+    studioCredentialHash?: string;
+    /** Application principals whose keys the admin key derives (feature `derived-principals`). */
+    derivedPrincipals?: readonly DerivedPrincipal[];
 }
-/** The deep module (§8). HTTP, CLI and tests use only this. */
+export interface DerivedPrincipal {
+    id: string;
+    credentialHash: string;
+}
+/**
+ * The deep module (§8). HTTP, CLI and tests use only this.
+ *
+ * Tenants open on demand (architecture §8.2): the first `resolve`, `status`, `worker` or
+ * `delete` naming a Tenant opens it (bounded by the open timeout) and caches the handle or
+ * the quarantine; `start` only marks discovery done, so a Host with many Tenants opens none
+ * at startup.
+ */
 export interface TenantModule {
+    /** Marks discovery done (`/ready`). Opens nothing. */
     start(): Promise<void>;
     readonly started: boolean;
-    resolve(id: string): TenantResolution;
+    /** Opens the Tenant on first use; a missing Tenant is `not-found`. */
+    resolve(id: string): Promise<TenantResolution>;
+    /**
+     * The Tenant's Worker handlers, opening it on demand, for `TenantWorkers.resolve`.
+     * Undefined when the Tenant does not exist, is quarantined or is being deleted, or the
+     * module is closed.
+     */
+    worker(id: string): Promise<TenantWorker | undefined>;
     create(input: {
         tenantId: string;
         name: string;
@@ -105,21 +143,69 @@ export interface TenantModule {
         envelope: TenantEnvelope;
         created: boolean;
     }>;
+    /**
+     * Every Tenant the store holds, without opening any. A Tenant not opened yet is listed
+     * `open` when its envelope reads; opening it may still quarantine it.
+     */
     list(): Promise<readonly AdminTenant[]>;
     status(id: string): Promise<AdminTenantStatus | undefined>;
     delete(id: string, activeWork: "refuse" | "drain" | "cancel"): Promise<void>;
-    summarize(): HostAggregate;
+    summarize(): Promise<HostAggregate>;
     close(): Promise<void>;
 }
-/** Storage adapter behind the module (§8): OSS directory+SQLite, and in-memory for tests. */
+/**
+ * Storage adapter behind the module (§8): a Postgres schema per Tenant (`store-pg.ts`), and
+ * in-memory for tests (`store-memory.ts`).
+ */
 export interface TenantStore {
+    /** Ids of every Tenant the store holds. */
     enumerate(): Promise<readonly string[]>;
+    /** Throws a quarantine error when unreadable, `TenantNotFoundError` when gone. */
     readEnvelope(id: string): Promise<TenantEnvelope>;
+    /**
+     * Creates the Tenant, or returns `exists` when it already exists (whatever its bootstrap
+     * material; the module compares it with `bootstrapMatches`). The stored envelope's
+     * `schemaVersion` is the store's own; read it back with `readEnvelope`.
+     */
     create(envelope: TenantEnvelope, bootstrap: BootstrapPrincipal): Promise<"created" | "exists">;
     bootstrapMatches(id: string, bootstrap: BootstrapPrincipal): Promise<boolean>;
+    /**
+     * Opens the Tenant Runtime; runs migration. Throws `TenantNotFoundError` when the Tenant
+     * does not exist, `TenantUnavailableError` when something outside the Tenant failed, and
+     * any other error (a quarantine error, ideally) when the Tenant itself cannot be opened.
+     */
     open(id: string): Promise<TenantHandle>;
+    /** Removes the Tenant: its data and its Tenant directory. */
     trash(id: string, now: Date): Promise<void>;
+    /** Removes what a failed `create` left, never an existing Tenant. */
     removePartial(id: string): Promise<void>;
 }
-/** Injected into the store so WS-B can test without WS-A. */
-export type OpenTenantRuntime = (config: TenantConfig) => Promise<TenantHandle>;
+/**
+ * Thrown by a store when a Tenant cannot be reached for a reason outside it (the database
+ * or Durable Session Execution is unavailable). The module does not quarantine it: the next
+ * use tries again. The Host answers 503.
+ */
+export declare class TenantUnavailableError extends Error {
+    readonly tenantId: string;
+    readonly status = 503;
+    constructor(tenantId: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown by `TenantStore.open` for a Tenant that does not exist. */
+export declare class TenantNotFoundError extends Error {
+    readonly tenantId: string;
+    constructor(tenantId: string);
+}
+/** What a Tenant store hands the Tenant Runtime it opens. */
+export interface OpenedTenant {
+    /**
+     * The Tenant's opened Session Store. The Tenant Runtime owns it from here on and closes it
+     * on close or on a failed open.
+     */
+    store: SessionStore;
+    /** The Tenant envelope as its store reports it. */
+    envelope: TenantEnvelope;
+}
+/** Opens the Tenant Runtime on a store the Tenant store opened (injected, so tests can fake it). */
+export type OpenTenantRuntime = (config: TenantConfig, opened: OpenedTenant) => Promise<TenantHandle>;

package/dist/tenant/types.js

@@ -1 +1,23 @@
-export {};
+/**
+ * Thrown by a store when a Tenant cannot be reached for a reason outside it (the database
+ * or Durable Session Execution is unavailable). The module does not quarantine it: the next
+ * use tries again. The Host answers 503.
+ */
+export class TenantUnavailableError extends Error {
+    tenantId;
+    status = 503;
+    constructor(tenantId, options) {
+        super("Tenant is temporarily unavailable", options);
+        this.tenantId = tenantId;
+        this.name = "TenantUnavailableError";
+    }
+}
+/** Thrown by `TenantStore.open` for a Tenant that does not exist. */
+export class TenantNotFoundError extends Error {
+    tenantId;
+    constructor(tenantId) {
+        super(`Tenant ${tenantId} not found`);
+        this.tenantId = tenantId;
+        this.name = "TenantNotFoundError";
+    }
+}

package/dist/tenant/worker.d.ts

@@ -0,0 +1,84 @@
+import type { AdvanceResult, DurableExecution, StuckInvocation, WorkerHandlers } from "../execution/types.js";
+import type { Logger } from "./types.js";
+/** This process's Worker id: the `owner` it writes on the sessions it advances (§10.6). */
+export declare const WORKER_ID: string;
+/**
+ * Default advance deadline: 50 minutes, below the one-hour inactivity and abort timeouts the
+ * Restate adapter sets on the session object, so an advance always ends before Restate gives
+ * up on it.
+ */
+export declare const DEFAULT_ADVANCE_DEADLINE_MS: number;
+/** Default time an aborted advance has to settle before it is abandoned. */
+export declare const DEFAULT_ADVANCE_GRACE_MS = 30000;
+/** Why an advance's signal aborted (see "Abort reasons" above). */
+export type AdvanceAbortKind = "cancel" | "shutdown" | "deadline" | "ownership.lost";
+/** The abort reason of an advance. */
+export declare class AdvanceAbort extends Error {
+    readonly kind: AdvanceAbortKind;
+    readonly name: string;
+    constructor(kind: AdvanceAbortKind, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The abort reason of an advance that ran past its deadline. */
+export declare class AdvanceDeadlineError extends AdvanceAbort {
+    readonly deadlineMs: number;
+    readonly name = "AdvanceDeadlineError";
+    constructor(deadlineMs: number);
+}
+/**
+ * The kind of an aborted signal's reason, or `undefined` while it has not aborted. A reason
+ * that is not an `AdvanceAbort` came from outside the Tenant (the execution stopping) and
+ * counts as `shutdown`.
+ */
+export declare function abortKind(signal: AbortSignal): AdvanceAbortKind | undefined;
+/** One open Tenant's handlers. */
+export interface TenantWorker {
+    /** Advances one session. Session outcomes never throw; only infrastructure errors do. */
+    advance(sessionId: string, signal: AbortSignal): Promise<AdvanceResult>;
+    /** One pass of the Tenant sweep. */
+    sweep(): Promise<void>;
+}
+export interface TenantWorkersOptions {
+    /** Finds or opens a Tenant that is not registered on this process. */
+    resolve?: (tenantId: string) => Promise<TenantWorker | undefined>;
+    /** How long one advance may run before its signal aborts. Default `DEFAULT_ADVANCE_DEADLINE_MS`. */
+    advanceDeadlineMs?: number;
+    /**
+     * How long an advance whose signal aborted has to return before it is abandoned.
+     * Default `DEFAULT_ADVANCE_GRACE_MS`.
+     */
+    advanceGraceMs?: number;
+    /** Receives a warning for each abandoned advance. */
+    logger?: Logger;
+}
+/** Registry of open Tenants' workers, dispatched to by `tenantId`. */
+export declare class TenantWorkers {
+    private readonly options;
+    private readonly workers;
+    private readonly deadlineMs;
+    /**
+     * How long an aborted advance has to return before it is abandoned. Closing a Tenant waits
+     * as long for its advances before it abandons them (`scheduler.ts` `waitForIdle`).
+     */
+    readonly graceMs: number;
+    constructor(options?: TenantWorkersOptions);
+    /** Registers an open Tenant's worker; the returned function unregisters exactly it. */
+    register(tenantId: string, worker: TenantWorker): () => void;
+    get(tenantId: string): TenantWorker | undefined;
+    private find;
+    /** The handlers to start a `DurableExecution` with. */
+    readonly handlers: WorkerHandlers;
+    /** Runs one advance under the deadline and the grace period (see the module comment). */
+    private bounded;
+}
+/** A Durable Session Execution together with the registry its handlers dispatch through. */
+export interface TenantExecution {
+    readonly execution: DurableExecution;
+    readonly workers: TenantWorkers;
+    /**
+     * The Tenant's invocations that need an operator (paused or backing off), for Tenant
+     * status. Absent when the execution cannot report them (in-process execution).
+     */
+    readonly stuckInvocations?: (tenantId: string) => Promise<StuckInvocation[]>;
+}

package/dist/tenant/worker.js

@@ -0,0 +1,189 @@
+/**
+ * The Worker side of Durable Session Execution (architecture §12.3): what a `DurableExecution`
+ * calls for one Tenant, and the registry that lets one execution serve every Tenant open on
+ * this process.
+ *
+ * - `TenantWorker` is one open Tenant's handlers: `advance(sessionId, signal)` (§10.5, in
+ *   `advance.ts`) and `sweep()` (the Tenant sweep, in `sweep.ts`).
+ * - `TenantWorkers` is the registry. Its `handlers` are the `WorkerHandlers` an execution is
+ *   started with; they dispatch by `tenantId` to the registered `TenantWorker`. A Tenant
+ *   registers when it opens and unregisters when it closes. A call for a Tenant that is not
+ *   open here asks the optional `resolve` hook (the Host can open it on demand); without one,
+ *   the advance returns `done` and the sweep does nothing. Nothing is lost: the Tenant's sweep
+ *   re-wakes its orphaned sessions once it is open again.
+ * - `TenantExecution` pairs an execution with its registry. The Host creates one per process
+ *   (`host/execution.ts`) and passes it to every Tenant it opens; a Tenant opened without one
+ *   (tests, ephemeral) gets its own in-process `MemoryExecution`.
+ *
+ * ## Advance deadline
+ *
+ * Restate's abort timeout does not interrupt a running handler (the advance's signal does not
+ * fire), so the registry bounds every advance itself:
+ *
+ * 1. At `advanceDeadlineMs` the advance's signal aborts with an `AdvanceDeadlineError`. The
+ *    in-flight effect is aborted and the segment settles as a normal outcome (the effect and
+ *    the turn become `uncertain`, or the turn fails with the deadline's message).
+ * 2. Once the signal has aborted, for whatever reason (deadline, Worker stop, Restate attempt
+ *    end), the advance has `advanceGraceMs` to return. One that does not (an effect that
+ *    ignores its signal) is abandoned: the handler returns `busy`, so the execution runs the
+ *    session again. The abandoned advance has stopped renewing its lease (`advance.ts`), so
+ *    the next advance takes over when the lease lapses (§11.4), and the epoch fences anything
+ *    the abandoned one still tries to write.
+ *
+ * ## Abort reasons
+ *
+ * Every abort of an advance carries an `AdvanceAbort` whose `kind` says why, because the
+ * advance treats them differently (`advance.ts`, `effects.ts`):
+ *
+ * - `cancel`: a user cancel (or a reset) committed first. Results that arrive afterwards are
+ *   discarded and the turn stays cancelled (§10.7).
+ * - `deadline`: the advance ran too long (`AdvanceDeadlineError`). The segment settles as a
+ *   normal outcome.
+ * - `shutdown`: this Worker gives the advance up (Worker stop, Tenant close, the Restate
+ *   attempt ended). Nothing about the turn is settled: outcomes already in hand are recorded,
+ *   ownership is released and the advance returns `busy`, so the next advance, here or on
+ *   another Worker, resumes the segment from its checkpoint with the cached outcomes.
+ * - `ownership.lost`: another advance took the session over; this one writes nothing more.
+ *
+ * An abort that arrives through the execution's signal is a `shutdown`, whatever its reason.
+ */
+import { hostname } from "node:os";
+import { randomBytes } from "node:crypto";
+/** This process's Worker id: the `owner` it writes on the sessions it advances (§10.6). */
+export const WORKER_ID = `worker-${hostname()}-${process.pid}-${randomBytes(4).toString("hex")}`;
+/**
+ * Default advance deadline: 50 minutes, below the one-hour inactivity and abort timeouts the
+ * Restate adapter sets on the session object, so an advance always ends before Restate gives
+ * up on it.
+ */
+export const DEFAULT_ADVANCE_DEADLINE_MS = 50 * 60_000;
+/** Default time an aborted advance has to settle before it is abandoned. */
+export const DEFAULT_ADVANCE_GRACE_MS = 30_000;
+/** The abort reason of an advance. */
+export class AdvanceAbort extends Error {
+    kind;
+    name = "AdvanceAbort";
+    constructor(kind, message, options) {
+        super(message, options);
+        this.kind = kind;
+    }
+}
+/** The abort reason of an advance that ran past its deadline. */
+export class AdvanceDeadlineError extends AdvanceAbort {
+    deadlineMs;
+    name = "AdvanceDeadlineError";
+    constructor(deadlineMs) {
+        super("deadline", `The advance ran past its ${deadlineMs} ms deadline`);
+        this.deadlineMs = deadlineMs;
+    }
+}
+/**
+ * The kind of an aborted signal's reason, or `undefined` while it has not aborted. A reason
+ * that is not an `AdvanceAbort` came from outside the Tenant (the execution stopping) and
+ * counts as `shutdown`.
+ */
+export function abortKind(signal) {
+    if (!signal.aborted)
+        return undefined;
+    return signal.reason instanceof AdvanceAbort ? signal.reason.kind : "shutdown";
+}
+/** The execution's abort reason as a `shutdown`, keeping its message. */
+function shutdownOf(reason) {
+    if (reason instanceof AdvanceAbort)
+        return reason;
+    return new AdvanceAbort("shutdown", reason instanceof Error ? reason.message : "The Worker stopped the advance", { cause: reason });
+}
+const DONE = { status: "done" };
+/** Registry of open Tenants' workers, dispatched to by `tenantId`. */
+export class TenantWorkers {
+    options;
+    workers = new Map();
+    deadlineMs;
+    /**
+     * How long an aborted advance has to return before it is abandoned. Closing a Tenant waits
+     * as long for its advances before it abandons them (`scheduler.ts` `waitForIdle`).
+     */
+    graceMs;
+    constructor(options = {}) {
+        this.options = options;
+        this.deadlineMs = positive("advanceDeadlineMs", options.advanceDeadlineMs ?? DEFAULT_ADVANCE_DEADLINE_MS);
+        this.graceMs = positive("advanceGraceMs", options.advanceGraceMs ?? DEFAULT_ADVANCE_GRACE_MS);
+    }
+    /** Registers an open Tenant's worker; the returned function unregisters exactly it. */
+    register(tenantId, worker) {
+        this.workers.set(tenantId, worker);
+        return () => {
+            if (this.workers.get(tenantId) === worker)
+                this.workers.delete(tenantId);
+        };
+    }
+    get(tenantId) {
+        return this.workers.get(tenantId);
+    }
+    async find(tenantId) {
+        return this.workers.get(tenantId) ?? (await this.options.resolve?.(tenantId));
+    }
+    /** The handlers to start a `DurableExecution` with. */
+    handlers = {
+        advance: async (tenantId, sessionId, signal) => {
+            const worker = await this.find(tenantId);
+            return worker ? this.bounded(tenantId, sessionId, worker, signal) : DONE;
+        },
+        sweep: async (tenantId) => {
+            await (await this.find(tenantId))?.sweep();
+        },
+    };
+    /** Runs one advance under the deadline and the grace period (see the module comment). */
+    async bounded(tenantId, sessionId, worker, signal) {
+        const controller = new AbortController();
+        const abort = (reason) => {
+            if (!controller.signal.aborted)
+                controller.abort(reason);
+        };
+        const forward = () => abort(shutdownOf(signal.reason));
+        if (signal.aborted)
+            forward();
+        else
+            signal.addEventListener("abort", forward, { once: true });
+        const deadline = setTimeout(() => abort(new AdvanceDeadlineError(this.deadlineMs)), this.deadlineMs);
+        let grace;
+        let armGrace;
+        const abandoned = new Promise((resolve) => {
+            armGrace = () => {
+                grace = setTimeout(() => {
+                    this.options.logger?.warn("advance abandoned after abort", {
+                        tenantId,
+                        sessionId,
+                        graceMs: this.graceMs,
+                        reason: controller.signal.reason instanceof Error
+                            ? controller.signal.reason.message
+                            : String(controller.signal.reason),
+                    });
+                    resolve({ status: "busy", retryAfterMs: 0 });
+                }, this.graceMs);
+            };
+            if (controller.signal.aborted)
+                armGrace();
+            else
+                controller.signal.addEventListener("abort", armGrace, { once: true });
+        });
+        try {
+            // `race` keeps handling the advance's outcome after it is abandoned.
+            return await Promise.race([worker.advance(sessionId, controller.signal), abandoned]);
+        }
+        finally {
+            clearTimeout(deadline);
+            clearTimeout(grace);
+            signal.removeEventListener("abort", forward);
+            if (armGrace)
+                controller.signal.removeEventListener("abort", armGrace);
+        }
+    }
+}
+/** The longest delay `setTimeout` keeps (about 24.8 days). */
+const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+function positive(name, value) {
+    if (!Number.isFinite(value) || value <= 0 || value > MAX_TIMEOUT_MS)
+        throw new Error(`${name} must be positive and at most ${MAX_TIMEOUT_MS}`);
+    return value;
+}

package/dist/vault/service.d.ts

@@ -1,5 +1,5 @@
-import type { DatabaseSync } from "node:sqlite";
 import type { CreateCredentialRequest, CreateVaultRequest, CredentialInfo, CredentialSelection, HostModelProviderInfo, HostModelView, PutHostModelRequest, RotateCredentialRequest, SelectHostModelRequest, VaultInfo } from "@nylorun/core/contracts";
+import type { SessionStore, Tx } from "../store/types.js";
 export type HostModelSecret = {
     provider: string;
     model: string;
@@ -31,27 +31,42 @@ export type AuthorizeResult = {
     credentialIds: string[];
     reason: string;
 };
+export interface VaultServiceOptions {
+    store: SessionStore;
+    /** The Tenant key-encryption key. May read or create the key file. */
+    kek: () => Buffer;
+    /** Used only for OAuth refresh, always outside a transaction. */
+    fetch: typeof fetch;
+}
 export declare class VaultService {
-    private readonly db;
-    private readonly tx;
+    private readonly store;
     private readonly kek;
     private readonly fetchImpl;
-    constructor(db: DatabaseSync, tx: <T>(fn: () => T) => T, kek: () => Buffer, fetchImpl: typeof fetch);
-    createVault(body: CreateVaultRequest): VaultInfo;
-    listVaults(ownerUserId: string): VaultInfo[];
-    getVault(id: string): VaultInfo;
-    deleteVault(id: string): {
+    constructor(options: VaultServiceOptions);
+    createVault(body: CreateVaultRequest): Promise<VaultInfo>;
+    listVaults(ownerUserId: string): Promise<VaultInfo[]>;
+    getVault(id: string): Promise<VaultInfo>;
+    /** Another owner's vault, or the host vault, is the same 404 as a missing one. */
+    assertOwner(id: string, ownerUserId: string): Promise<void>;
+    deleteVault(id: string): Promise<{
         id: string;
-    };
-    createCredential(vaultId: string, body: CreateCredentialRequest): CredentialInfo;
-    listCredentials(vaultId: string): CredentialInfo[];
-    getCredential(vaultId: string, id: string): CredentialInfo;
-    rotateCredential(vaultId: string, id: string, body: RotateCredentialRequest): CredentialInfo;
-    deleteCredential(vaultId: string, id: string): {
+    }>;
+    createCredential(vaultId: string, body: CreateCredentialRequest): Promise<CredentialInfo>;
+    listCredentials(vaultId: string): Promise<CredentialInfo[]>;
+    getCredential(vaultId: string, id: string): Promise<CredentialInfo>;
+    rotateCredential(vaultId: string, id: string, body: RotateCredentialRequest): Promise<CredentialInfo>;
+    deleteCredential(vaultId: string, id: string): Promise<{
         id: string;
-    };
-    assertAttachment(ownerUserId: string, vaultIds: readonly string[], selections: readonly CredentialSelection[]): void;
-    recordAttachment(sessionId: string, vaultIds: readonly string[]): void;
+    }>;
+    /**
+     * Checks a session's vaults and selections. Run in the session PUT transaction. `opaque`
+     * (a request acting for a subject) reports another owner's vault as the 404 of a missing one.
+     */
+    assertAttachment(t: Tx, ownerUserId: string, vaultIds: readonly string[], selections: readonly CredentialSelection[], options?: {
+        opaque?: boolean;
+    }): Promise<void>;
+    /** Writes the `attach` audit row. Run in the session PUT transaction. */
+    recordAttachment(t: Tx, sessionId: string, vaultIds: readonly string[]): Promise<void>;
     authorize(input: {
         sessionId: string;
         vaultIds: readonly string[];
@@ -59,13 +74,14 @@ export declare class VaultService {
         url: string;
         serverName?: string;
     }): Promise<AuthorizeResult>;
-    getHostModel(): HostModelView;
-    listHostProviders(): {
+    getHostModel(): Promise<HostModelView>;
+    listHostProviders(): Promise<{
         providers: HostModelProviderInfo[];
-    };
-    putHostModel(body: PutHostModelRequest): HostModelView;
-    selectHostModel(body: SelectHostModelRequest): HostModelView;
-    readHostModel(): HostModelSecret | undefined;
+    }>;
+    putHostModel(body: PutHostModelRequest): Promise<HostModelView>;
+    selectHostModel(body: SelectHostModelRequest): Promise<HostModelView>;
+    /** Reads the active host model secret. Decrypts after the read commits. */
+    readHostModel(): Promise<HostModelSecret | undefined>;
     updateHostCredential(credential: {
         type: "api_key" | "oauth";
         key?: string;
@@ -73,27 +89,24 @@ export declare class VaultService {
         refresh?: string;
         access?: string;
         expires?: number;
-    }): void;
-    reject(route: string): void;
+    }): Promise<void>;
+    reject(route: string): Promise<void>;
+    /** Calls the token endpoint outside any transaction, then stores the result. */
     private refresh;
     private replay;
-    private insertCredential;
+    /** Re-seals a user credential's payload and returns the updated row. */
     private writePayload;
-    private readPayload;
     private vaultInfo;
-    private vaultRow;
     private ensureHostVault;
     private validateHostModel;
     private insertHostCredential;
-    private readHostPayload;
+    private hostModelView;
     private hostModelRows;
     private hostCredentialRowFor;
     private activeHostCredentialRow;
     private activeProviderId;
     private setActiveProvider;
     private deleteHostProviderRows;
-    private credentialInfo;
     private credentialRow;
-    private rowsForVault;
     private audit;
 }