primitive-admin 1.2.0-alpha.1 → 1.2.0-alpha.11

package/dist/src/lib/api-client.d.ts

@@ -1,5 +1,16 @@
 import { type ListEnvelope } from "./paginate.js";
-import { type GlobalAppRef, type WorkflowUsageReport } from "./workflow-usage.js";
+/**
+ * #4262 — an agent prompt's test case: its `[test.agent]` block on the wire.
+ * `agentHistory` is JSON text; context and the expected call are parsed.
+ */
+export interface AgentTestCaseWireFields {
+    agentHistory?: string | null;
+    agentContext?: Record<string, any> | null;
+    agentTimezone?: string | null;
+    agentLocale?: string | null;
+    agentExpectedToolCall?: Record<string, any> | null;
+    agentExpectedNoToolCall?: boolean | null;
+}
 /**
  * Metadata for a single bucket blob, as returned by the metadata endpoint
  * `GET blob-buckets/:bucketId/blobs/:blobId/metadata`. Mirrors the published
@@ -17,6 +28,49 @@ export interface BlobInfo {
     uploaded?: string | null;
     etag?: string | null;
 }
+/**
+ * One child app as `GET /admin/api/apps/{appId}/children` lists it. Dates
+ * are ISO-8601 strings.
+ */
+export interface AppChildSummary {
+    appId: string;
+    name: string;
+    childSlug: string;
+    parentAppId: string;
+    ownerAdminId: string | null;
+    owner: {
+        adminId: string;
+        email: string;
+        name: string | null;
+    } | null;
+    branch: string | null;
+    idleDays: number | null;
+    createdAt: string;
+    lastActivityAt: string | null;
+    expiresAt: string | null;
+    /** Exact origins the child's CORS and email-redirect checks accept beside its authored lists. */
+    previewOrigins?: string[];
+    /** The child's protection level: always `internal` (#4564); absent from an older server. */
+    protection?: string;
+}
+/** A child's preview origins after a write to them. */
+export interface ChildPreviewOrigins {
+    appId: string;
+    parentAppId: string;
+    childSlug: string;
+    previewOrigins: string[];
+}
+/** One row of a db3's index registry, as `db3/:id/indexes` answers it. */
+export interface Db3IndexRow {
+    name: string;
+    model: string;
+    fields: string[];
+    unique: boolean;
+    origins: Array<{
+        kind: "declaration" | "named";
+        unique: boolean;
+    }>;
+}
 export declare class ApiError extends Error {
     statusCode: number;
     code?: string;
@@ -64,9 +118,11 @@ export declare function blobFailure(response: Response, prefix: string): Promise
  * integrations proxy) use `message`. This helper reads both fields so all CLI
  * call sites surface the real server message instead of `HTTP <status>`.
  *
- * `htmlNotFound` is set when the body looks like an HTML 404 page (typically
- * served when an API path is wrong); callers can use it to throw a clearer
- * "API endpoint not found" message regardless of the original status code.
+ * `htmlNotFound` is set when the body is an HTML 404 page (typically served
+ * when an API path is wrong); callers can use it to throw a clearer
+ * "API endpoint not found" message. An HTML page with any other status — a
+ * gateway's 502, a rate limiter's 429, a firewall's 403 — keeps its status, so
+ * a retry and an absence check read it as what it is (#4148).
  *
  * `details` can be either an array (legacy validation-issue list) or a
  * structured record (issue #666 schema gate); the schema-feature errors
@@ -90,51 +146,11 @@ export interface ParsedErrorResponse {
 export declare function parseErrorResponse(response: {
     status: number;
 }, text: string, path?: string): ParsedErrorResponse;
-/**
- * Typed exception classes for the database-schema feature (issue #666).
- * Each maps 1:1 to a server `code` value emitted from the op-edit or
- * schema-edit gate. They all extend ApiError so existing catch-all paths
- * continue to work; specialized catch blocks can branch on `instanceof`.
- *
- * Per round-2 addendum A1, `details` is always preserved so callers can
- * extract structured offender lists (refs[], operations[], etc.).
- */
-export declare class SchemaRequiredError extends ApiError {
-    constructor(message: string, details?: Record<string, any>);
-}
-export declare class OperationRefError extends ApiError {
-    constructor(message: string, details?: Record<string, any>);
-    get refs(): Array<{
-        ref: string;
-        location: string;
-    }>;
-}
-export declare class SchemaBreaksOpsError extends ApiError {
-    constructor(message: string, details?: Record<string, any>);
-    get operations(): Array<{
-        operation: string;
-        refs: Array<{
-            ref: string;
-            location: string;
-        }>;
-    }>;
-}
-export declare class SchemaHasUncheckableOpsError extends ApiError {
-    constructor(message: string, details?: Record<string, any>);
-    get operations(): Array<{
-        operation: string;
-        locations: string[];
-    }>;
-}
 export declare class TomlParseError extends ApiError {
     constructor(message: string, details?: Record<string, any>);
     get line(): number | undefined;
     get column(): number | undefined;
 }
-export declare class OpsExistError extends ApiError {
-    constructor(message: string, details?: Record<string, any>);
-    get opCount(): number;
-}
 interface EmailTemplateSummary {
     emailType: string;
     label: string;
@@ -368,13 +384,7 @@ export interface ArchiveEnvelope {
     archived?: boolean;
     [key: string]: unknown;
 }
-/**
- * Body accepted by integration create and update (#2631).
- *
- * `accessRule` is the CEL expression gating who may invoke the integration
- * through the proxy. The server REQUIRES it on create; on update, `null` or
- * `""` clears it, and a cleared rule denies every non-admin call.
- */
+/** Body accepted by integration create and update (#2631). */
 export interface IntegrationWritePayload {
     integrationKey?: string;
     displayName?: string;
@@ -382,11 +392,10 @@ export interface IntegrationWritePayload {
     requestConfig?: any;
     timeoutMs?: number;
     status?: string;
-    accessRule?: string | null;
 }
 /**
- * Integration detail response. `accessRule` is only on the detail — the list
- * summary does not carry it (#2631).
+ * Integration detail response. `requestConfig` is only on the detail — the
+ * list summary does not carry it.
  */
 export interface IntegrationDetail {
     integrationId: string;
@@ -396,7 +405,6 @@ export interface IntegrationDetail {
     status?: string;
     timeoutMs?: number;
     requestConfig?: any;
-    accessRule?: string | null;
     modifiedAt?: string;
     [key: string]: any;
 }
@@ -412,20 +420,6 @@ interface AnalyticsIntegrationMetricsResponse {
     integrations: AnalyticsIntegrationMetric[];
     _timing: AnalyticsTiming;
 }
-interface WorkflowAnalyticsSummary {
-    workflowKey: string;
-    runs: number;
-    successRate: number;
-    medianDurationMs: number;
-    p95: number;
-    totalTokens: number;
-}
-interface TopWorkflowsResponse {
-    windowDays: number;
-    limit: number;
-    workflows: WorkflowAnalyticsSummary[];
-    _timing: AnalyticsTiming;
-}
 interface PromptAnalyticsSummary {
     promptKey: string;
     executions: number;
@@ -471,35 +465,6 @@ export interface DatabaseBatchOperation {
      */
     condition?: Record<string, any>;
 }
-/**
- * Normalize a `databases operations execute` result to the CLI's one list
- * envelope — but only when the result is a Durable Object query page
- * (issue #2440).
- *
- * A registered operation is a list only sometimes. Of the shapes the server's
- * operation dispatch can return, exactly two carry a top-level `data` array: a
- * bare `query` and a `pipeline` whose `returnField` names a query step. A
- * `count` (`{ count }`), an `aggregate` (`{ result }`), a mutation
- * (`{ results }`), an `applyToQuery` (`{ matched, affected, failed, … }`) and a
- * `returnField: "all"` pipeline (`{ steps: { … } }`) do not, so blanket
- * normalization would corrupt them. This helper therefore tests the shape
- * first and passes everything else through byte-for-byte — including the
- * nested steps of a `returnField: "all"` pipeline, which are operation-defined
- * objects the CLI must not reach into.
- *
- * Deliberately narrow, not a general-purpose predicate: the contract is
- * specifically "an operations-execute result may be a DO query page".
- * `executeDatabaseOperation()` is the only caller.
- *
- * The conversion itself is delegated to `normalizeCliListEnvelope()` so cursor
- * handling, `prevCursor` dropping and `hasMore` derivation have exactly one
- * implementation. That helper throws on an unrecognized shape — correct when
- * the payload is supposed to be a list, wrong here, where the payload is the
- * caller's own result — which is why the shape test has to run first. `_timing`
- * (`--timing`) is re-attached afterwards, since it rides alongside the envelope
- * rather than inside it.
- */
-export declare function normalizeDatabaseOperationResult(raw: unknown): unknown;
 export declare class ApiClient {
     /**
      * Loaded on first use (`ensureAuthenticated`), never in a constructor.
@@ -522,6 +487,40 @@ export declare class ApiClient {
     private ensureAuthenticated;
     private refreshToken;
     request<T = any>(path: string, options?: RequestInit): Promise<T>;
+    /**
+     * Whether a 403 should be retried with the stored step-up: it names
+     * `admin` among the missing scopes, or it is a protected app's refusal of
+     * a token that is no step-up, and an unexpired step-up is stored.
+     */
+    private stepUpApplies;
+    /**
+     * #4564 — a request outside `request` (an upload, a function invocation)
+     * sent with the CLI's own credentials, retried once with the stored step-up
+     * exactly as `request` retries. `init` builds the request for a bearer. The
+     * answer is the retry's, unless the retry was refused 401: the step-up is
+     * dropped and the original refusal comes back, still readable.
+     */
+    private fetchWithStepUp;
+    /** Forget a step-up the server no longer accepts. */
+    private dropStepUp;
+    /** The typed error a failed response throws. */
+    private responseError;
+    /**
+     * `POST /admin/api/auth/token` — derive a token no wider than the stored
+     * one (`primitive token --scope`, #3889). A wider request is refused with
+     * `TOKEN_WIDER_THAN_PRESENTED`.
+     */
+    exchangeToken(body: {
+        scope: string[];
+        apps?: string[];
+        ttl?: string;
+    }): Promise<{
+        accessToken: string;
+        expiresAt: string;
+        sessionId: string;
+        scope: string[];
+        apps: string[];
+    }>;
     get<T = any>(path: string, params?: Record<string, any>): Promise<T>;
     post<T = any>(path: string, body?: any): Promise<T>;
     put<T = any>(path: string, body?: any): Promise<T>;
@@ -540,11 +539,14 @@ export declare class ApiClient {
     listAppsPage(params?: {
         limit?: number;
         cursor?: string;
+        kind?: "parent" | "child";
     }): Promise<{
         items: Array<{
             id: string;
             name: string;
             role?: string;
+            parentAppId?: string | null;
+            childSlug?: string | null;
         }>;
         hasMore?: boolean;
         nextCursor?: string | null;
@@ -563,25 +565,44 @@ export declare class ApiClient {
         }>;
     }>;
     /**
-     * Every app on the server, not just the caller's own.
-     *
-     * Deliberately separate from `listApps()`, whose contract is "apps assigned
-     * to me" (`GET /admin/api/admins/me/apps`, backed by `admin.queryApps()`) —
-     * the contract every other command depends on. `analytics workflow-usage
-     * --all-apps` has to reach apps nobody is assigned to, which is the global
-     * route `GET /admin/api/apps` (`App.iterateAll()`), and that route
-     * identifies an app as `appId` rather than `id` (D3130-001).
-     *
-     * One drain of that route is lossy — its cursor re-scans `App.iterateAll()`
-     * from the start of each page, so a list that changes under it both repeats
-     * and drops rows — so the walk is the union of repeated drains
-     * (`drainAppsUntilConverged`, which carries the measurement).
+     * Create an app. An ordinary app takes `name` (and, for a super-admin,
+     * `initialAdminEmail`). A child app takes `parentAppId` and `childSlug`
+     * instead, plus the optional `branch`, `idleDays` (7-30, default 30) and
+     * `copySecrets` (default true); the server names it `<parent name> /
+     * <slug>` and copies the parent's settings.
      */
-    listAllAppsGlobal(): Promise<GlobalAppRef[]>;
     createApp(data: {
-        name: string;
+        name?: string;
         initialAdminEmail?: string;
+        parentAppId?: string;
+        childSlug?: string;
+        branch?: string;
+        idleDays?: number;
+        copySecrets?: boolean;
     }): Promise<any>;
+    /**
+     * One page of an app's child apps, in creation order
+     * (`GET /admin/api/apps/{appId}/children`).
+     */
+    listAppChildren(parentAppId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: AppChildSummary[];
+        hasMore: boolean;
+        nextCursor: string | null;
+    }>;
+    /**
+     * Add one origin to a child's preview origins
+     * (`POST /admin/api/apps/{parentAppId}/children/{slug}/preview-origins`).
+     */
+    addChildPreviewOrigin(parentAppId: string, slug: string, origin: string): Promise<ChildPreviewOrigins>;
+    /**
+     * Remove one origin from a child's preview origins
+     * (`DELETE /admin/api/apps/{parentAppId}/children/{slug}/preview-origins`).
+     */
+    removeChildPreviewOrigin(parentAppId: string, slug: string, origin: string): Promise<ChildPreviewOrigins>;
+    private childPreviewOriginsPath;
     getApp(appId: string): Promise<{
         id: string;
         name: string;
@@ -592,7 +613,23 @@ export declare class ApiClient {
     addUserByEmail(appId: string, data: {
         email: string;
         role?: string;
+        name?: string;
+        avatarUrl?: string | null;
     }): Promise<any>;
+    /**
+     * Set a member's display name and/or avatar URL
+     * (`PATCH /admin/api/apps/:appId/users/:userId/profile`). An omitted field
+     * is left alone; `avatarUrl: null` or `""` clears the avatar.
+     */
+    setUserProfile(appId: string, userId: string, data: {
+        name?: string;
+        avatarUrl?: string | null;
+    }): Promise<{
+        userId: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+    }>;
     mintTestJwt(appId: string, userId: string, role?: string): Promise<any>;
     rebuildUserSearchText(appId: string): Promise<{
         count: number;
@@ -696,7 +733,7 @@ export declare class ApiClient {
         hasMore?: boolean;
         nextCursor?: string | null;
     }>;
-    /** Integration detail (#2631: `accessRule` is on the detail, not the list summary). */
+    /** Integration detail (`requestConfig` is on the detail, not the list summary). */
     getIntegration(appId: string, integrationId: string): Promise<IntegrationDetail>;
     /**
      * An integration's named configs. Test cases pin a config by NAME so the
@@ -726,9 +763,8 @@ export declare class ApiClient {
         source?: "user" | "admin" | "test" | "workflow" | "function";
         /** #3691 — only the calls this run made, workflow run or function run. */
         runId?: string;
-    }): Promise<any[]>;
-    listWorkflowRunIntegrationLogs(appId: string, runId: string, params?: {
-        limit?: number;
+        /** #3781 — only the calls this step made: a workflow step id or a function step name. */
+        stepId?: string;
     }): Promise<any[]>;
     listAppSecrets(appId: string): Promise<any[]>;
     createAppSecret(appId: string, payload: {
@@ -753,33 +789,6 @@ export declare class ApiClient {
         expectNotExists?: boolean;
     }): Promise<any>;
     deleteAppConfigVar(appId: string, key: string, expectedModifiedAt?: string): Promise<any>;
-    listWebhooks(appId: string, params?: {
-        status?: string;
-        cursor?: string;
-        limit?: number;
-    }): Promise<{
-        items: any[];
-        hasMore?: boolean;
-        nextCursor?: string | null;
-    }>;
-    getWebhook(appId: string, webhookId: string): Promise<any>;
-    createWebhook(appId: string, payload: any): Promise<any>;
-    updateWebhook(appId: string, webhookId: string, payload: any, expectedModifiedAt?: string): Promise<any>;
-    /**
-     * Delete a webhook. Archives it by default; `hard` hard-deletes the row
-     * instead (#2232), which is what frees a slot under the per-app webhook cap
-     * and releases the webhook key for reuse. Same `?hard=true` verb the admin
-     * integrations delete uses.
-     */
-    deleteWebhook(appId: string, webhookId: string, options?: {
-        hard?: boolean;
-    }): Promise<ArchiveEnvelope>;
-    /**
-     * #2803 — the operational verb pair for a webhook. It posts to the
-     * enable/disable route rather than PATCHing `status`, which is server-owned
-     * and refused on every configuration write path.
-     */
-    setWebhookAvailability(appId: string, webhookId: string, action: "enable" | "disable"): Promise<any>;
     listFunctions(appId: string): Promise<{
         items: any[];
     }>;
@@ -811,6 +820,30 @@ export declare class ApiClient {
         items: any[];
         nextCursor?: string | null;
     }>;
+    private functionTriggersPath;
+    /** The function's webhook delivery log, newest first. */
+    listFunctionWebhookEvents(appId: string, functionId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        hasMore?: boolean;
+        nextCursor?: string | null;
+    }>;
+    /** Sign a preview delivery for the function's webhook trigger. */
+    testFunctionWebhook(appId: string, functionId: string, payload?: any): Promise<any>;
+    /** Check captured headers and a captured body against the trigger's verifier. */
+    verifyFunctionWebhook(appId: string, functionId: string, payload: {
+        headers: Array<[string, string]>;
+        rawBody?: string;
+        bodyBase64?: string;
+    }): Promise<any>;
+    /** Point the trigger's `signingSecret` at a new `{{secrets.KEY}}` reference. */
+    rotateFunctionWebhookSecret(appId: string, functionId: string, payload: {
+        signingSecret: string;
+    }): Promise<any>;
+    /** One cron entry verb: `fire`, `fire-scheduled`, `enable` or `disable`. */
+    functionCronEntryAction(appId: string, functionId: string, name: string, action: "fire" | "fire-scheduled" | "enable" | "disable"): Promise<any>;
     /**
      * A function run's step trace — #3348.
      *
@@ -823,6 +856,17 @@ export declare class ApiClient {
     getFunctionStepRuns(appId: string, functionId: string, runId: string): Promise<{
         items: any[];
     }>;
+    /**
+     * The integration calls one function run made — #3190.
+     *
+     * The run → integration-logs pivot, addressed by the function that owns the
+     * run (it was `workflows/runs/{runId}/integration-logs`).
+     */
+    listFunctionRunIntegrationLogs(appId: string, functionId: string, runId: string, options?: {
+        limit?: number;
+    }): Promise<{
+        items: any[];
+    }>;
     /**
      * End a function run that will not settle — #3348.
      *
@@ -910,9 +954,8 @@ export declare class ApiClient {
         /**
          * Which runtime this call means — #3482. The ROUTE is the selector:
          * `POST functions/{key}` runs the function inside the request and
-         * `POST functions/{key}/start` runs it as a task. The admin-only system
-         * door is ONE route for both, so `--as system` keeps naming its runtime
-         * in the body (F-3482-007); phase 7's rename may fold it.
+         * `POST functions/{key}/start` runs it as a task; the admin-only system
+         * door has `invoke-as-system` and `start-as-system` (#3190).
          */
         runtime?: "request" | "task";
     }): Promise<{
@@ -920,6 +963,18 @@ export declare class ApiClient {
         retryAfterSeconds: number | null;
         body: any;
     }>;
+    /**
+     * Run only a function's `authorize` and hand back the ANSWER, whatever its
+     * HTTP status — #4732. Like `invokeFunction`, it returns a refusal rather
+     * than throwing it, so `functions authorize` renders the server's own
+     * answer (and a case run records it as a failed row); it throws only when
+     * the request did not complete. The CLI's own credentials, with the
+     * step-up retry a protected app's refusal asks for.
+     */
+    authorizeFunction(appId: string, functionId: string, body: Record<string, unknown>): Promise<{
+        httpStatus: number;
+        body: any;
+    }>;
     /**
      * A function's versions, newest first (#3462).
      *
@@ -954,28 +1009,15 @@ export declare class ApiClient {
     setPromptAvailability(appId: string, promptId: string, action: "enable" | "disable"): Promise<any>;
     /** #2803 — the operational verb pair for an integration (admin API). */
     setIntegrationAvailability(appId: string, integrationId: string, action: "enable" | "disable"): Promise<any>;
-    rotateWebhookSecret(appId: string, webhookId: string, payload: {
-        signingSecret: string;
-    }): Promise<any>;
-    listWebhookEvents(appId: string, webhookId: string, params?: {
-        limit?: number;
-        cursor?: string;
-    }): Promise<{
-        items: any[];
-        hasMore?: boolean;
-        nextCursor?: string | null;
-    }>;
     /**
      * List the live connections the server believes exist for exactly one of a
-     * document, user, or database. Read-only inspection over admin-api. Rows are
+     * document or user. Read-only inspection over admin-api. Rows are
      * per-connection-×-subscription bindings, so `connectionId` is not unique
-     * across rows. `params` on a database-subscription row is caller-defined
-     * bound CEL input — typed `unknown`.
+     * across rows.
      */
     listConnections(appId: string, selector: {
         documentId?: string;
         userId?: string;
-        databaseId?: string;
     }, params?: {
         limit?: number;
         cursor?: string;
@@ -984,6 +1026,28 @@ export declare class ApiClient {
         hasMore?: boolean;
         nextCursor?: string | null;
     }>;
+    /**
+     * One page of one user's agent sessions (#3809): the app API's sessions
+     * list, which an app owner or admin may read for any user.
+     */
+    listAgentSessions(appId: string, params: {
+        userId: string;
+        agent?: string;
+        scope?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: unknown[];
+        hasMore?: boolean;
+        nextCursor?: string | null;
+    }>;
+    /**
+     * One agent session (#3809): its binding, status, members and active turn,
+     * and for an app owner or admin the session object's state. Never its rows.
+     */
+    getAgentSession(appId: string, sessionId: string): Promise<any>;
+    /** Delete an agent session and its document (#3809); a repeat succeeds again. */
+    deleteAgentSession(appId: string, sessionId: string): Promise<any>;
     listSessions(appId: string, userId: string, params?: {
         limit?: number;
         cursor?: string;
@@ -1010,20 +1074,6 @@ export declare class ApiClient {
         sessionId: string;
         revokedAt: string;
     }>;
-    testWebhook(appId: string, webhookId: string, payload?: any): Promise<any>;
-    /**
-     * Run a webhook's configured verifier over headers and a body captured from
-     * a real delivery, and report whether that signature checks out (#2445).
-     *
-     * `headers` is sent as ordered `[name, value]` pairs so a capture carrying a
-     * field name on more than one line survives the round trip. Nothing is
-     * delivered: no delivery record, no workflow run.
-     */
-    verifyWebhook(appId: string, webhookId: string, payload: {
-        headers: Array<[string, string]>;
-        rawBody?: string;
-        bodyBase64?: string;
-    }): Promise<any>;
     listLocks(appId: string): Promise<{
         locks: any[];
     }>;
@@ -1034,29 +1084,6 @@ export declare class ApiClient {
      */
     acquireLock(appId: string, key: string, ttlMs: number, owner?: string): Promise<any>;
     releaseLock(appId: string, key: string, handleId: string): Promise<any>;
-    listCronTriggers(appId: string): Promise<{
-        items: any[];
-    }>;
-    getCronTrigger(appId: string, triggerId: string): Promise<any>;
-    createCronTrigger(appId: string, payload: any): Promise<any>;
-    updateCronTrigger(appId: string, triggerId: string, payload: any): Promise<any>;
-    /**
-     * Retire a cron trigger. The default soft-deletes (writes the `archived`
-     * tombstone); `{ hard: true }` destroys the row, which is what
-     * `config push --prune` passes (#2803) so a pruned trigger stops consuming
-     * the per-app cap and holding its key.
-     */
-    deleteCronTrigger(appId: string, triggerId: string, options?: {
-        hard?: boolean;
-    }): Promise<ArchiveEnvelope>;
-    disableCronTrigger(appId: string, triggerId: string): Promise<any>;
-    enableCronTrigger(appId: string, triggerId: string): Promise<any>;
-    testCronTrigger(appId: string, triggerId: string): Promise<any>;
-    listIterations(appId: string): Promise<{
-        items: any[];
-    }>;
-    getIteration(appId: string, iterationName: string): Promise<any>;
-    resetIteration(appId: string, iterationName: string): Promise<any>;
     readResourceMetadata(appId: string, resourceType: string, resourceId: string, category: string): Promise<any>;
     writeResourceMetadata(appId: string, resourceType: string, resourceId: string, category: string, data: Record<string, any>): Promise<any>;
     batchReadResourceMetadata(appId: string, requests: Array<{
@@ -1149,44 +1176,16 @@ export declare class ApiClient {
      * is a distinct block version: `configId` is the stable version selector,
      * `contentHash` is its content identity, and `status` reports whether it is
      * `active`/`draft`/`archived`. The script header's `activeConfigId` names
-     * the live version. Used by `scripts configs list` and by the script test
-     * commands to run against a specific pinned version.
+     * the version that was live. Used by `scripts configs list`.
      */
     listScriptConfigs(appId: string, scriptId: string): Promise<{
         items: any[];
     }>;
-    createScript(appId: string, payload: {
-        name: string;
-        body: string;
-        description?: string;
-    }): Promise<any>;
-    /**
-     * Push a new body for an existing script by creating a new `ScriptConfig`
-     * and activating it (the prompt-model "edit → activate" flow). Referencing
-     * workflows pick up the new body on their next run with no fan-out. The
-     * config name is unique per script, so we mint a timestamped name.
-     */
-    pushScriptBody(appId: string, scriptId: string, body: string, 
     /**
-     * The active state the caller believes holds right now (#2731 B10).
-     * Creating an inactive config races nothing, so the guard sits on the
-     * ACTIVATION step: if the active config has moved since the caller read it,
-     * the server rejects with a 409 instead of overwriting a concurrent script
-     * change. It takes BOTH halves of "what is active", because a config's body
-     * can be edited in place without the active id changing — the id alone
-     * would let such an edit through. Omitted (e.g. `--force`) means activate
-     * unconditionally.
+     * One version of a script, body included. A body the server cannot load
+     * answers a 404 naming the version rather than an empty body.
      */
-    expectedActive?: {
-        configId?: string;
-        modifiedAt?: string;
-    }): Promise<any>;
-    /**
-     * Delete a script header (cascades its configs). `force` overrides the
-     * server's guard against deleting a script that an active workflow still
-     * references by name — without it the server answers 409.
-     */
-    deleteScript(appId: string, scriptId: string, force?: boolean): Promise<void>;
+    getScriptConfig(appId: string, scriptId: string, configId: string): Promise<any>;
     getPromptSchema(appId: string, promptId: string): Promise<{
         promptId: string;
         promptKey: string;
@@ -1202,7 +1201,7 @@ export declare class ApiClient {
      * 100) and reports `nextCursor`; callers that reconcile the sync tree must
      * drain every page before deleting or classifying anything (#2769).
      */
-    listTestCases(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, params?: {
+    listTestCases(appId: string, blockType: "prompt" | "integration", blockId: string, params?: {
         limit?: number;
         cursor?: string;
     }): Promise<{
@@ -1210,8 +1209,8 @@ export declare class ApiClient {
         hasMore?: boolean;
         nextCursor?: string;
     }>;
-    getTestCase(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string): Promise<any>;
-    createTestCase(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, payload: {
+    getTestCase(appId: string, blockType: "prompt" | "integration", blockId: string, testCaseId: string): Promise<any>;
+    createTestCase(appId: string, blockType: "prompt" | "integration", blockId: string, payload: {
         name: string;
         description?: string | null;
         inputVariables: Record<string, any>;
@@ -1223,8 +1222,8 @@ export declare class ApiClient {
         evaluatorConfigId?: string;
         /** The sidecar's file name — the case's identity (#2896). */
         key?: string;
-    }): Promise<any>;
-    updateTestCase(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string, payload: {
+    } & AgentTestCaseWireFields): Promise<any>;
+    updateTestCase(appId: string, blockType: "prompt" | "integration", blockId: string, testCaseId: string, payload: {
         name?: string;
         description?: string | null;
         inputVariables?: Record<string, any>;
@@ -1236,9 +1235,9 @@ export declare class ApiClient {
         evaluatorConfigId?: string | null;
         /** The sidecar's file name, on a create-or-rename backfill (#2896). */
         key?: string;
-    }): Promise<any>;
-    deleteTestCase(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string): Promise<void>;
-    listTestCaseAttachments(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string): Promise<{
+    } & AgentTestCaseWireFields): Promise<any>;
+    deleteTestCase(appId: string, blockType: "prompt" | "integration", blockId: string, testCaseId: string): Promise<void>;
+    listTestCaseAttachments(appId: string, blockType: "prompt" | "integration", blockId: string, testCaseId: string): Promise<{
         attachments: Array<{
             filename: string;
             contentType: string;
@@ -1246,7 +1245,7 @@ export declare class ApiClient {
             r2Key: string;
         }>;
     }>;
-    uploadTestCaseAttachment(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string, filename: string, data: Buffer, contentType: string): Promise<{
+    uploadTestCaseAttachment(appId: string, blockType: "prompt" | "integration", blockId: string, testCaseId: string, filename: string, data: Buffer, contentType: string): Promise<{
         success: boolean;
         attachment: {
             filename: string;
@@ -1255,26 +1254,26 @@ export declare class ApiClient {
             r2Key: string;
         };
     }>;
-    downloadTestCaseAttachment(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string, filename: string): Promise<{
+    downloadTestCaseAttachment(appId: string, blockType: "prompt" | "integration", blockId: string, testCaseId: string, filename: string): Promise<{
         data: Buffer;
         contentType: string;
     }>;
-    deleteTestCaseAttachment(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string, filename: string): Promise<{
+    deleteTestCaseAttachment(appId: string, blockType: "prompt" | "integration", blockId: string, testCaseId: string, filename: string): Promise<{
         success: boolean;
         deleted: boolean;
     }>;
-    executeBlockTest(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, payload: {
+    executeBlockTest(appId: string, blockType: "prompt" | "integration", blockId: string, payload: {
         variables?: Record<string, any>;
         testCaseId?: string;
         configId?: string;
         comparisonGroup?: string;
     }): Promise<any>;
-    runAllTestCases(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, payload?: {
+    runAllTestCases(appId: string, blockType: "prompt" | "integration", blockId: string, payload?: {
         overrideConfigId?: string;
         comparisonGroup?: string;
         testCaseIds?: string[];
     }): Promise<any>;
-    listTestRuns(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, params?: {
+    listTestRuns(appId: string, blockType: "prompt" | "integration", blockId: string, params?: {
         limit?: number;
         comparisonGroup?: string;
     }): Promise<{
@@ -1290,121 +1289,10 @@ export declare class ApiClient {
         nextCursor?: string | null;
     }>;
     getWorkflow(appId: string, workflowId: string): Promise<any>;
-    /**
-     * One app's workflow step usage report (#3132).
-     *
-     * `windowDays` is omitted from the query when the caller did not ask for a
-     * window, so the server applies its own default rather than the CLI
-     * restating it on the wire.
-     */
-    getWorkflowUsage(appId: string, params?: {
-        windowDays?: number;
-    }): Promise<WorkflowUsageReport>;
-    createWorkflow(appId: string, payload: any): Promise<any>;
-    updateWorkflow(appId: string, workflowId: string, payload: any, expectedModifiedAt?: string): Promise<any>;
-    /**
-     * Retire a workflow, or destroy it (#2887).
-     *
-     * The plain call ARCHIVES: the definition row stays, so its runs, revisions
-     * and test cases keep resolving. `{ hard: true }` performs the full cascade
-     * and is what releases the `workflowKey` — the flag `config push --prune`
-     * sends, for the same reason it sends it for webhooks and integrations.
-     */
-    deleteWorkflow(appId: string, workflowId: string, options?: {
-        hard?: boolean;
-    }): Promise<ArchiveEnvelope>;
-    /**
-     * #2645 criterion 9 — the operational toggle. Deliberately NOT the config
-     * PATCH: `config push` owns every configuration field, and taking a workflow
-     * out of service must not touch one, or an operator's action would show up as
-     * drift against the repo. Same route shape as `cron-triggers pause|resume`.
-     */
-    disableWorkflow(appId: string, workflowId: string): Promise<any>;
-    enableWorkflow(appId: string, workflowId: string): Promise<any>;
-    updateWorkflowDraft(appId: string, workflowId: string, payload: any): Promise<any>;
-    previewWorkflow(appId: string, workflowId: string, payload: {
-        rootInput?: object;
-        meta?: object;
-        configId?: string;
-        useDraft?: boolean;
-        preferActive?: boolean;
-    }): Promise<{
-        instanceId: string;
-        usingDraft?: boolean;
-        source?: "config" | "active" | "draft" | null;
-        configName?: string | null;
-        configId?: string | null;
-        warning?: string;
-    }>;
-    getPreviewStatus(appId: string, workflowId: string, instanceId: string): Promise<any>;
-    listWorkflowRuns(appId: string, workflowId: string, params?: {
-        status?: string;
-        limit?: number;
-        cursor?: string;
-        forward?: boolean;
-        follow?: boolean;
-        after?: string;
-    }): Promise<{
-        items: any[];
-        hasMore?: boolean;
-        nextCursor?: string | null;
-        /** #1969 — opaque follow checkpoint; present on `follow=true` responses. */
-        resumeAfter?: string;
-        /**
-         * #2237 — index rows the server examined for this request. Filtered reads
-         * only, and only on a server new enough to report it; `undefined`
-         * otherwise, which callers must treat as "unknown", not zero.
-         */
-        scanned?: number;
-    }>;
-    /**
-     * Workflow runs started by one app user, across every workflow (#1967).
-     * Backed by `GET /admin/api/apps/{appId}/users/{userId}/workflow-runs`,
-     * which resolves the app user before querying the `runsByUser` index.
-     */
-    listUserWorkflowRuns(appId: string, userId: string, params?: {
-        status?: string;
-        limit?: number;
-        cursor?: string;
-        forward?: boolean;
-        workflowId?: string;
-    }): Promise<{
-        items: any[];
-        hasMore?: boolean;
-        nextCursor?: string | null;
-        /** #2237 — index rows examined; filtered reads only, `undefined` if unknown. */
-        scanned?: number;
-    }>;
-    getWorkflowRunStatus(appId: string, workflowId: string, runId: string): Promise<any>;
-    getWorkflowStepRuns(appId: string, workflowId: string, runId: string): Promise<{
-        items: any[];
-    }>;
     listWorkflowConfigs(appId: string, workflowId: string): Promise<{
         items: any[];
     }>;
     getWorkflowConfig(appId: string, workflowId: string, configId: string): Promise<any>;
-    createWorkflowConfig(appId: string, workflowId: string, payload: {
-        configName: string;
-        description?: string;
-        steps: any[];
-        expressions?: {
-            cel?: Record<string, string>;
-        };
-    }): Promise<any>;
-    updateWorkflowConfig(appId: string, workflowId: string, configId: string, payload: {
-        configName?: string;
-        description?: string;
-        steps?: any[];
-        status?: string;
-        expressions?: {
-            cel?: Record<string, string>;
-        };
-    }): Promise<any>;
-    archiveWorkflowConfig(appId: string, workflowId: string, configId: string): Promise<any>;
-    activateWorkflowConfig(appId: string, workflowId: string, configId: string): Promise<any>;
-    duplicateWorkflowConfig(appId: string, workflowId: string, configId: string, payload?: {
-        configName?: string;
-    }): Promise<any>;
     getAnalyticsTopUsers(appId: string, params?: {
         windowDays?: number;
         limit?: number;
@@ -1453,10 +1341,6 @@ export declare class ApiClient {
         limit?: number;
         [key: string]: any;
     }): Promise<AnalyticsErrorsGroupsResponse>;
-    getAnalyticsTopWorkflows(appId: string, params?: {
-        windowDays?: number;
-        limit?: number;
-    }): Promise<TopWorkflowsResponse>;
     getAnalyticsTopPrompts(appId: string, params?: {
         windowDays?: number;
         limit?: number;
@@ -1516,7 +1400,7 @@ export declare class ApiClient {
     createIntegrationCatalogItem(payload: any): Promise<any>;
     updateIntegrationCatalogItem(catalogId: string, payload: any): Promise<any>;
     deleteIntegrationCatalogItem(catalogId: string): Promise<void>;
-    startBatchTests(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, payload?: {
+    startBatchTests(appId: string, blockType: "prompt" | "integration", blockId: string, payload?: {
         comparisonGroup?: string;
         overrideConfigId?: string;
         testCaseIds?: string[];
@@ -1526,7 +1410,7 @@ export declare class ApiClient {
         instanceIds: string[];
         errors?: any[];
     }>;
-    getBatchTestStatus(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, batchId: string): Promise<{
+    getBatchTestStatus(appId: string, blockType: "prompt" | "integration", blockId: string, batchId: string): Promise<{
         status: string;
         batchId: string;
         completed: number;
@@ -1543,7 +1427,7 @@ export declare class ApiClient {
             endedAt?: string;
         }>;
     }>;
-    cancelBatchTests(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, batchId: string, instanceIds: string[]): Promise<{
+    cancelBatchTests(appId: string, blockType: "prompt" | "integration", blockId: string, batchId: string, instanceIds: string[]): Promise<{
         batchId: string;
         terminated: string[];
         errors?: any[];
@@ -1713,44 +1597,6 @@ export declare class ApiClient {
      * `{ success, id, appliedFields }`.
      */
     patchDatabaseRecord(appId: string, databaseId: string, modelName: string, id: string, data: any): Promise<any>;
-    listDatabaseOperations(appId: string, databaseId: string): Promise<any[]>;
-    /**
-     * Execute a registered operation and, when the result is a query page,
-     * normalize it to the CLI's one list envelope (issue #2440).
-     *
-     * The registered operation decides the response shape, so the normalization
-     * is conditional — see {@link normalizeDatabaseOperationResult}. Everything
-     * else (a `count`, an `aggregate`, a mutation, a `returnField: "all"`
-     * pipeline) is returned exactly as the server sent it.
-     */
-    executeDatabaseOperation(appId: string, databaseId: string, operationName: string, data?: {
-        params?: Record<string, any>;
-        limit?: number;
-        cursor?: string;
-        direction?: number;
-    }, token?: string, options?: {
-        timing?: boolean;
-    }): Promise<any>;
-    /**
-     * Execute a registered batch (bulk) database operation. Posts a chunk of
-     * items to the canonical `operations/:name/batch` endpoint (the same one the
-     * client library's `executeBatch` uses — NOT the deprecated `import-bulk`
-     * alias). Used by `databases import-csv`.
-     *
-     * @returns `{ imported, failed }` — DO-level write outcome counts. Per-item
-     *   validation/access failures abort the whole chunk with a 4xx (thrown).
-     */
-    executeBatch(appId: string, databaseId: string, operationName: string, batch: Array<{
-        params: Record<string, any>;
-    }>): Promise<{
-        imported: number;
-        failed: number;
-    }>;
-    /**
-     * Make a request using a specific JWT token instead of the CLI's credentials.
-     * Used for executing operations as a different user.
-     */
-    requestWithToken<T = any>(path: string, token: string, options?: RequestInit): Promise<T>;
     listDatabaseIndexes(appId: string, databaseId: string, modelName?: string): Promise<any>;
     registerDatabaseIndex(appId: string, databaseId: string, data: {
         modelName: string;
@@ -1780,12 +1626,6 @@ export declare class ApiClient {
         databaseType: string;
         ruleSetId?: string | null;
         triggers?: Record<string, any> | null;
-        /**
-         * @deprecated The TOML `type.celContextAccess` expression. Use resource
-         * metadata categories instead (#1420, #1815).
-         */
-        metadataAccess?: string | null;
-        defaultAccess?: string | null;
         autoPopulatedFields?: Record<string, any> | null;
         timestamps?: Record<string, any> | null;
         schema?: string | null;
@@ -1796,24 +1636,10 @@ export declare class ApiClient {
     updateDatabaseTypeConfig(appId: string, databaseType: string, data: {
         ruleSetId?: string | null;
         triggers?: Record<string, any> | null;
-        /**
-         * @deprecated The TOML `type.celContextAccess` expression. Use resource
-         * metadata categories instead (#1420, #1815).
-         */
-        metadataAccess?: string | null;
-        defaultAccess?: string | null;
         autoPopulatedFields?: Record<string, any> | null;
         timestamps?: Record<string, any> | null;
         schema?: string | null;
-        pendingOpDeletes?: string[];
-        finalOpNames?: string[];
         metadataManifest?: any;
-        pendingOpUpdates?: Array<{
-            name: string;
-            access?: string | null;
-            params?: Record<string, any> | null;
-        }>;
-        pendingOpUpserts?: Array<Record<string, any>>;
     }, expectedModifiedAt?: string, options?: {
         dryRun?: boolean;
         acceptWarnings?: boolean;
@@ -1822,51 +1648,14 @@ export declare class ApiClient {
         force?: boolean;
     }): Promise<any>;
     /**
-     * Issue #666 Phase 3: ask the server to scaffold a TOML schema from
-     * existing ops + DO field introspection. Read-only — does NOT persist.
+     * Issue #666 Phase 3: ask the server to scaffold a TOML schema from the
+     * type's databases (the models each holds, and their fields). Read-only —
+     * does NOT persist.
      */
     scaffoldDatabaseTypeSchema(appId: string, databaseType: string): Promise<{
         schema: string;
     }>;
-    listDatabaseTypeOperations(appId: string, databaseType: string): Promise<any[]>;
-    getDatabaseTypeOperation(appId: string, databaseType: string, name: string): Promise<any>;
-    createDatabaseTypeOperation(appId: string, databaseType: string, data: {
-        name: string;
-        type: string;
-        modelName: string;
-        access?: string | null;
-        definition: Record<string, any>;
-        params?: Record<string, any> | null;
-    }, options?: {
-        dryRun?: boolean;
-        schemaOverride?: string | null;
-        defaultAccess?: string | null;
-        metadataManifestOverride?: Record<string, any> | null;
-    }): Promise<any>;
-    updateDatabaseTypeOperation(appId: string, databaseType: string, name: string, data: Record<string, any>, expectedModifiedAt?: string, options?: {
-        dryRun?: boolean;
-        schemaOverride?: string | null;
-        metadataManifestOverride?: Record<string, any> | null;
-    }): Promise<any>;
-    deleteDatabaseTypeOperation(appId: string, databaseType: string, name: string): Promise<any>;
-    listDatabaseTypeSubscriptions(appId: string, databaseType: string): Promise<any[]>;
-    getDatabaseTypeSubscription(appId: string, databaseType: string, subscriptionKey: string): Promise<any>;
-    createDatabaseTypeSubscription(appId: string, databaseType: string, data: {
-        subscriptionKey: string;
-        displayName: string;
-        modelName: string;
-        filter: string;
-        access: string;
-        description?: string | null;
-        select?: string[] | null;
-        emit?: string[] | null;
-        params?: Record<string, any> | null;
-        status?: string;
-    }): Promise<any>;
-    updateDatabaseTypeSubscription(appId: string, databaseType: string, subscriptionKey: string, data: Record<string, any>, expectedModifiedAt?: string): Promise<any>;
-    deleteDatabaseTypeSubscription(appId: string, databaseType: string, subscriptionKey: string): Promise<any>;
     listGroups(appId: string, params?: {
-        type?: string;
         limit?: number;
         cursor?: string;
     }): Promise<{
@@ -1874,28 +1663,56 @@ export declare class ApiClient {
         nextCursor?: string;
         hasMore?: boolean;
     }>;
+    /** One page of one custodian's groups (`app` or `user:<userId>`), through the admin API. */
+    listGroupsByCustodian(appId: string, custodian: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string;
+        hasMore?: boolean;
+    }>;
+    /** Transfer a group to `to` (`app` or `user:<userId>`) through the admin API. */
+    transferGroup(appId: string, groupId: string, to: string): Promise<any>;
+    /**
+     * Create a group through the admin API; `custodian` is `app` or
+     * `user:<userId>`. The server mints the group's id and answers it as
+     * `groupId`.
+     */
     createGroup(appId: string, data: {
-        groupType: string;
-        groupId?: string;
         name: string;
         description?: string;
+        custodian: string;
+        settings?: {
+            memberList?: "members" | "managers";
+        };
         initialMetadata?: Record<string, Record<string, unknown>>;
     }): Promise<any>;
-    getGroup(appId: string, groupType: string, groupId: string): Promise<any>;
-    updateGroup(appId: string, groupType: string, groupId: string, data: {
+    /**
+     * A group by id. `groupType` looks a group written before groups were
+     * addressed by id up by its type first (the routes' deprecated
+     * `?groupType=`), as an exported collection's grants still name them.
+     */
+    getGroup(appId: string, groupId: string, options?: {
+        groupType?: string;
+    }): Promise<any>;
+    updateGroup(appId: string, groupId: string, data: {
         name?: string;
         description?: string;
+        settings?: {
+            memberList?: "members" | "managers";
+        };
     }): Promise<any>;
-    deleteGroup(appId: string, groupType: string, groupId: string): Promise<any>;
+    deleteGroup(appId: string, groupId: string): Promise<any>;
     /**
-     * One page of a group's members.
+     * One page of a group's members, with their roles.
      *
      * The route paginates cursor-style (no default limit, cap 200) and reports
      * the boundary, so `groups members list` carries `--limit`/`--cursor` and
      * forwards them (#3646) rather than printing a first page that claims to be
      * the whole membership.
      */
-    listGroupMembers(appId: string, groupType: string, groupId: string, options?: {
+    listGroupMembers(appId: string, groupId: string, options?: {
         include?: "profiles";
         limit?: number;
         cursor?: string;
@@ -1904,11 +1721,16 @@ export declare class ApiClient {
         nextCursor?: string;
         hasMore?: boolean;
     }>;
-    addGroupMember(appId: string, groupType: string, groupId: string, data: {
+    /** Add a member through the admin API; `role: "owner"` restores the custodian's owner row. */
+    addGroupMember(appId: string, groupId: string, data: {
         userId: string;
+        role?: string;
     }): Promise<any>;
-    removeGroupMember(appId: string, groupType: string, groupId: string, userId: string): Promise<any>;
-    listGroupDocuments(appId: string, groupType: string, groupId: string): Promise<any[]>;
+    /** Change a member's role through the admin API, the owner row's included. */
+    setGroupMemberRole(appId: string, groupId: string, userId: string, role: string): Promise<any>;
+    /** Remove a member through the admin API, the owner row included. */
+    removeGroupMember(appId: string, groupId: string, userId: string): Promise<any>;
+    listGroupDocuments(appId: string, groupId: string): Promise<any[]>;
     listUserMemberships(appId: string, userId: string): Promise<any[]>;
     listDocumentGroupPermissions(appId: string, documentId: string): Promise<any[]>;
     grantDocumentGroupPermission(appId: string, documentId: string, data: {
@@ -1942,12 +1764,40 @@ export declare class ApiClient {
          */
         collectionType?: string;
         initialMetadata?: Record<string, Record<string, unknown>>;
+    }): Promise<any>;
+    /** One page of one custodian's collections (`app` or `user:<userId>`), through the admin API. */
+    listCollectionsByCustodian(appId: string, custodian: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string;
+        hasMore?: boolean;
+    }>;
+    /** Transfer a collection to `to` (`app` or `user:<userId>`) through the admin API. */
+    transferCollection(appId: string, collectionId: string, to: string): Promise<any>;
+    /**
+     * Create a collection through the admin API, for `custodian` (`app` or
+     * `user:<userId>`; a user custodian holds the owner row). Spends no
+     * create budget.
+     */
+    createCollectionAsAdmin(appId: string, data: {
+        name: string;
+        description?: string;
         /**
-         * The app user to create the collection FOR (#3641). Honored only for
-         * admin-token callers; an app-user token has it ignored and creates as
-         * itself, exactly as `createDocument`'s does.
+         * Deprecated: the server still records it while enforcement reads rule
+         * sets, so a migration carries it across.
          */
-        createdBy?: string;
+        collectionType?: string;
+        custodian: string;
+        settings?: {
+            memberList?: "members" | "managers";
+        } | Record<string, unknown>;
+        initialMembers?: Array<{
+            userId: string;
+            role: string;
+        }>;
+        initialMetadata?: Record<string, Record<string, unknown>>;
     }): Promise<any>;
     getCollection(appId: string, collectionId: string): Promise<any>;
     updateCollection(appId: string, collectionId: string, data: {
@@ -1974,30 +1824,30 @@ export declare class ApiClient {
         items: any[];
         nextCursor?: string | null;
     }>;
-    getCollectionAccess(appId: string, collectionId: string): Promise<any>;
-    grantCollectionGroupPermission(appId: string, collectionId: string, data: {
-        groupType: string;
-        groupId: string;
-        permission: string;
-    }): Promise<any>;
-    revokeCollectionGroupPermission(appId: string, collectionId: string, groupType: string, groupId: string): Promise<any>;
-    addCollectionMember(appId: string, collectionId: string, data: {
+    /**
+     * Every member of a collection, users and groups as principals with their
+     * roles, in one answer.
+     */
+    listCollectionMembers(appId: string, collectionId: string): Promise<{
+        items: any[];
+        hasMore: boolean;
+    }>;
+    /**
+     * Add a user or a group to a collection through the admin API, with a role;
+     * `role: "owner"` restores the custodian's owner row.
+     */
+    addCollectionMember(appId: string, collectionId: string, data: ({
         userId: string;
-        permission: string;
-    }): Promise<any>;
-    removeCollectionMember(appId: string, collectionId: string, userId: string): Promise<any>;
-    listCollectionTypeConfigs(appId: string): Promise<any[]>;
-    getCollectionTypeConfig(appId: string, collectionType: string): Promise<any>;
-    createCollectionTypeConfig(appId: string, data: {
-        collectionType: string;
-        ruleSetId?: string;
-        metadataManifest?: any;
+    } | {
+        groupId: string;
+        groupType?: string;
+    }) & {
+        role: string;
     }): Promise<any>;
-    updateCollectionTypeConfig(appId: string, collectionType: string, data: {
-        ruleSetId?: string | null;
-        metadataManifest?: any;
-    }, expectedModifiedAt?: string): Promise<any>;
-    deleteCollectionTypeConfig(appId: string, collectionType: string): Promise<any>;
+    /** Change a member's role through the admin API, the owner row's included. */
+    setCollectionMemberRole(appId: string, collectionId: string, principal: string, role: string): Promise<any>;
+    /** Remove a user or `group:<groupId>` through the admin API, the owner row included. */
+    removeCollectionMember(appId: string, collectionId: string, principal: string): Promise<any>;
     /**
      * List all metadata category configs for an app. The route returns
      * `{ configs: [...] }`; unwrap to a bare array to match the other
@@ -2055,20 +1905,6 @@ export declare class ApiClient {
     }>;
     testRuleSet(appId: string, ruleSetId: string, data: any): Promise<any>;
     debugRuleSet(appId: string, data: any): Promise<any>;
-    listGroupTypeConfigs(appId: string): Promise<any[]>;
-    getGroupTypeConfig(appId: string, groupType: string): Promise<any>;
-    createGroupTypeConfig(appId: string, data: {
-        groupType: string;
-        ruleSetId?: string;
-        autoAddCreator?: boolean;
-        metadataManifest?: any;
-    }): Promise<any>;
-    updateGroupTypeConfig(appId: string, groupType: string, data: {
-        ruleSetId?: string | null;
-        autoAddCreator?: boolean;
-        metadataManifest?: any;
-    }, expectedModifiedAt?: string): Promise<any>;
-    deleteGroupTypeConfig(appId: string, groupType: string): Promise<any>;
     exportDocumentState(appId: string, documentId: string): Promise<{
         state: string;
         byteLength: number;
@@ -2091,28 +1927,6 @@ export declare class ApiClient {
      */
     downloadDocumentArtifact(_appId: string, grantedPath: string): Promise<Buffer>;
     importDocumentState(appId: string, documentId: string, stateBase64: string): Promise<any>;
-    /**
-     * Upload one artifact of a large document's import chain (#2816,
-     * behavior 20).
-     *
-     * The bytes travel raw and unmodified: the manifest's digest is over the
-     * STORED bytes, so re-encoding a chunk here would fail its own verification
-     * on install. The query says which artifact it is — the server derives the
-     * key from the document it belongs to, so nothing here composes one.
-     */
-    uploadDocumentChainArtifact(appId: string, documentId: string, query: Record<string, string | number>, body: Buffer): Promise<any>;
-    /** Start installing an uploaded chain (#2816, behavior 20). */
-    installDocumentChain(appId: string, documentId: string, plan: {
-        installId?: string;
-        base: {
-            epoch: number;
-            buildId: string;
-        } | null;
-        overlays: number[];
-        currentEpoch: number;
-    }): Promise<any>;
-    /** How far a document's chain install has got (#2816, behavior 20). */
-    getDocumentChainInstall(appId: string, documentId: string): Promise<any>;
     getDocument(appId: string, documentId: string): Promise<any>;
     /**
      * Delete a document and everything hanging off it (#2756). The server route
@@ -2144,42 +1958,64 @@ export declare class ApiClient {
      * through the caller's document permission (reader+) or the app-admin arm.
      * Returns the unified `{ items, hasMore, nextCursor? }` envelope. The cursor
      * is an opaque token — feed `nextCursor` back as `cursor` for the next page.
+     * `limit` is 100 records when omitted and at most 10000; it is forwarded
+     * unparsed (a string from the command line) so the server validates it.
      */
     queryDocumentRecords(appId: string, documentId: string, modelName: string, queryOptions?: {
         filter?: Record<string, any>;
-        limit?: number;
+        /** `{ field: 1 | -1 }`, key order as precedence; the route validates it. */
+        sort?: unknown;
+        limit?: number | string;
         cursor?: string;
         /** #3764 — the format the caller believes this document has. */
-        documentFormat?: 1 | 2;
+        documentFormat?: 1 | 3;
+        /** #4692 — include specs, answered on a db3 as `_related`; the route validates them. */
+        include?: unknown;
     }): Promise<ListEnvelope>;
     /**
      * Count records in a document model (issue #1964 Phase 3). Returns `{ count }`.
      */
     countDocumentRecords(appId: string, documentId: string, modelName: string, queryOptions?: {
         filter?: Record<string, any>;
-        documentFormat?: 1 | 2;
+        documentFormat?: 1 | 3;
     }): Promise<{
         count: number;
     }>;
     /**
      * Aggregate records in a document model (issue #2437) — the documents twin
      * of {@link aggregateDatabaseRecords}. `POST documents/:id/records/:model/aggregate`
-     * with `{ options: { operations, groupBy?, filter? } }`, answering `{ result }`
-     * in the same shape as the database endpoint.
+     * with `{ options: { operations, groupBy?, filter?, sort?, limit? } }`,
+     * answering `{ result }` in the same shape as the database endpoint.
      *
-     * `groupBy` takes plain field names only: StringSet facet grouping and
-     * `{ field, contains }` membership grouping are database-only, which is why
-     * this signature is narrower than the databases one.
+     * `groupBy` takes plain field names and period levels `{ field, period }`
+     * (keyed `<field>_<period>` in a row's `group`). On a db3 (a format-3
+     * document) a StringSet field name is a facet, `{ field, contains }` a
+     * membership, and `sort` and `limit` order and bound the groups; a format-1
+     * document refuses those four with a 400.
      */
     aggregateDocumentRecords(appId: string, documentId: string, modelName: string, options: {
         operations: {
             type: string;
             field?: string;
         }[];
-        groupBy?: string[];
+        /** On a db3, a StringSet field name is a facet and `{ field, contains }` a membership. */
+        groupBy?: Array<string | {
+            field: string;
+            period: "month" | "quarter" | "year";
+        } | {
+            field: string;
+            contains: string;
+        }>;
         filter?: Record<string, any>;
+        /** The groups' order; a db3 only. */
+        sort?: {
+            field: string;
+            direction: 1 | -1;
+        };
+        /** The most groups answered, 1 to 10,000; a db3 only. */
+        limit?: number;
     }, extra?: {
-        documentFormat?: 1 | 2;
+        documentFormat?: 1 | 3;
     }): Promise<{
         result: unknown;
     }>;
@@ -2188,6 +2024,17 @@ export declare class ApiClient {
      * record/model/blob counts, approximate size, and last-modified timestamp.
      */
     getDocumentStats(appId: string, documentId: string): Promise<any>;
+    /**
+     * A record-log document's room (#4306): `GET documents/:id/room` →
+     * `{ ok, appId, documentId, documentFormat, room }`, `room` null for a
+     * format that has no record room. With `refused` (#4310), the answer also
+     * carries a page of that bulk load's refused rows. App admins only.
+     */
+    getDocumentRoom(appId: string, documentId: string, query?: {
+        refused?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
     /**
      * A large document's snapshot builds, newest first, one page (#3432).
      * `GET documents/:id/snapshots` → `{ items, hasMore, nextCursor? }`.
@@ -2217,8 +2064,16 @@ export declare class ApiClient {
     }>;
     /** One bulk-load session's status (#3434). */
     getDocumentIngest(appId: string, documentId: string, sessionId: string): Promise<any>;
-    /** Open a bulk-load session on a large document (#3435, criterion 9). */
-    createDocumentIngest(appId: string, documentId: string): Promise<any>;
+    /**
+     * Open a bulk-load session on a large document (#3435, criterion 9). A
+     * record-log (format 3) document's load takes `reserveEpoch`, `mode` and a
+     * refresh's `models` (#4310); `{}` keeps every format's defaults.
+     */
+    createDocumentIngest(appId: string, documentId: string, options?: {
+        reserveEpoch?: "open" | "commit";
+        mode?: "merge" | "refresh";
+        models?: string[];
+    }): Promise<any>;
     /**
      * Upload one chunk of a bulk-load session's artifact (#3435).
      *
@@ -2238,6 +2093,8 @@ export declare class ApiClient {
         lastId: string;
         body: Buffer;
     }): Promise<any>;
+    /** A chunk upload to `<base>/ingest/<session>/chunks`: the documents route or its db3 mount. */
+    private uploadIngestChunkAt;
     /** Freeze a session's manifest and hand it to the pipeline (#3435). */
     commitDocumentIngest(appId: string, documentId: string, sessionId: string): Promise<any>;
     /** Give a session up; allowed until the swap (#3435). */
@@ -2264,7 +2121,7 @@ export declare class ApiClient {
         data: Record<string, unknown>;
         options?: Record<string, unknown>;
     }, extra?: {
-        documentFormat?: 1 | 2;
+        documentFormat?: 1 | 3;
     }): Promise<{
         record: unknown;
     }>;
@@ -2277,7 +2134,7 @@ export declare class ApiClient {
         data: Record<string, unknown>;
         options?: Record<string, unknown>;
     }, extra?: {
-        documentFormat?: 1 | 2;
+        documentFormat?: 1 | 3;
     }): Promise<{
         record: unknown;
     }>;
@@ -2287,7 +2144,7 @@ export declare class ApiClient {
      * a silent no-op per the facade contract. Returns `{ deleted: true }`.
      */
     deleteDocumentRecord(appId: string, documentId: string, modelName: string, recordId: string, extra?: {
-        documentFormat?: 1 | 2;
+        documentFormat?: 1 | 3;
     }): Promise<{
         deleted: boolean;
     }>;
@@ -2298,7 +2155,7 @@ export declare class ApiClient {
      * `{ applied, added, updated, deleted }`.
      */
     bulkDocumentRecords(appId: string, documentId: string, operations: Array<Record<string, unknown>>, extra?: {
-        documentFormat?: 1 | 2;
+        documentFormat?: 1 | 3;
     }): Promise<{
         applied: number;
         added: Array<{
@@ -2310,13 +2167,246 @@ export declare class ApiClient {
             id: string;
         }>;
         deleted: number;
+        upserted: Array<{
+            index: number;
+            model: string;
+            id: string;
+            created: boolean;
+        }>;
+    }>;
+    /** `/app/<app>/api/db3/<id>`, the id encoded: every `db3.*` route's prefix. */
+    private db3Path;
+    /** `GET db3/:id/indexes` → `{ indexes }`, sorted by name. */
+    listDb3Indexes(appId: string, db3Id: string): Promise<{
+        indexes: Db3IndexRow[];
+    }>;
+    /**
+     * `POST db3/:id/indexes` with `{ model, field | fields, unique?, name? }` →
+     * `{ index }`. The route applies the registration rules.
+     */
+    registerDb3Index(appId: string, db3Id: string, body: {
+        model: string;
+        field?: string;
+        fields?: string[];
+        unique?: boolean;
+        name?: string;
+    }): Promise<{
+        index: Db3IndexRow;
+    }>;
+    /** `DELETE db3/:id/indexes/:name` → `{ ok, name }`. */
+    dropDb3Index(appId: string, db3Id: string, name: string): Promise<{
+        ok: boolean;
+        name: string;
+    }>;
+    /** The db3 mount of {@link queryDocumentRecords}: `GET db3/:id/records/:model`. */
+    queryDb3Records(appId: string, db3Id: string, modelName: string, queryOptions?: {
+        filter?: Record<string, any>;
+        sort?: unknown;
+        limit?: number | string;
+        cursor?: string;
+        include?: unknown;
+    }): Promise<ListEnvelope>;
+    /** The db3 mount of {@link countDocumentRecords}: `GET db3/:id/records/:model/count`. */
+    countDb3Records(appId: string, db3Id: string, modelName: string, queryOptions?: {
+        filter?: Record<string, any>;
+    }): Promise<{
+        count: number;
+    }>;
+    /** The db3 mount of {@link aggregateDocumentRecords}: `POST db3/:id/records/:model/aggregate`. */
+    aggregateDb3Records(appId: string, db3Id: string, modelName: string, options: Parameters<ApiClient["aggregateDocumentRecords"]>[3]): Promise<{
+        result: unknown;
     }>;
+    /** The db3 mount of {@link saveDocumentRecord}: `POST db3/:id/records/:model`. */
+    saveDb3Record(appId: string, db3Id: string, modelName: string, body: {
+        id: string;
+        data: Record<string, unknown>;
+        options?: Record<string, unknown>;
+    }): Promise<{
+        record: unknown;
+    }>;
+    /** The db3 mount of {@link patchDocumentRecord}: `PATCH db3/:id/records/:model/:recordId`. */
+    patchDb3Record(appId: string, db3Id: string, modelName: string, recordId: string, body: {
+        data: Record<string, unknown>;
+        options?: Record<string, unknown>;
+    }): Promise<{
+        record: unknown;
+    }>;
+    /** The db3 mount of {@link deleteDocumentRecord}: `DELETE db3/:id/records/:model/:recordId`. */
+    deleteDb3Record(appId: string, db3Id: string, modelName: string, recordId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** The db3 mount of {@link bulkDocumentRecords}: `POST db3/:id/records/bulk`. */
+    bulkDb3Records(appId: string, db3Id: string, operations: Array<Record<string, unknown>>): ReturnType<ApiClient["bulkDocumentRecords"]>;
+    /** The db3 mount of {@link getDocumentSchema}: `GET db3/:id/schema`. */
+    getDb3Schema(appId: string, db3Id: string): Promise<any>;
+    /** `?limit=&cursor=` for a listing. */
+    private pageQuery;
+    /** `GET db3/:id/ingest` (#4889): a db3's bulk-load sessions, newest first. */
+    listDb3Ingests(appId: string, db3Id: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    /** `GET db3/:id/ingest/:sessionId` (#4889). */
+    getDb3Ingest(appId: string, db3Id: string, sessionId: string): Promise<any>;
+    /** `POST db3/:id/ingest` (#4889): open a bulk-load session; `{}` keeps the defaults. */
+    createDb3Ingest(appId: string, db3Id: string, options?: {
+        reserveEpoch?: "open" | "commit";
+        mode?: "merge" | "refresh";
+        models?: string[];
+    }): Promise<any>;
+    /** `POST db3/:id/ingest/:sessionId/chunks` (#4889): one chunk, multipart, as the documents upload sends it. */
+    uploadDb3IngestChunk(appId: string, db3Id: string, sessionId: string, chunk: Parameters<ApiClient["uploadDocumentIngestChunk"]>[3]): Promise<any>;
+    /** `POST db3/:id/ingest/:sessionId/commit` (#4889). */
+    commitDb3Ingest(appId: string, db3Id: string, sessionId: string): Promise<any>;
+    /** `POST db3/:id/ingest/:sessionId/abort` (#4889). */
+    abortDb3Ingest(appId: string, db3Id: string, sessionId: string): Promise<any>;
+    /** `GET db3/:id/snapshots` (#4889): a db3's segment exports, newest first. */
+    listDb3Snapshots(appId: string, db3Id: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    /** `GET db3/:id/snapshots/:segmentId` (#4889). */
+    getDb3Snapshot(appId: string, db3Id: string, segmentId: string): Promise<any>;
+    /** `POST db3/:id/snapshots` (#4889): start a segment export. */
+    requestDb3Snapshot(appId: string, db3Id: string): Promise<any>;
+    /** `GET db3/:id/export/chain` (#4889): the current segment, signed for download. */
+    exportDb3Chain(appId: string, db3Id: string): Promise<any>;
+    /** `GET db3/:id/blobs` (#4889): one page of a db3's blobs. */
+    listDb3Blobs(appId: string, db3Id: string, params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<any>;
+    /** `GET db3/:id/blobs/:blobId/download` (#4889): a blob's bytes. */
+    downloadDb3Blob(appId: string, db3Id: string, blobId: string): Promise<Buffer>;
+    /** `PUT db3/:id/blobs/:blobId` (#4889): a blob under its own id, as the documents upload sends it. */
+    uploadDb3Blob(appId: string, db3Id: string, blobId: string, data: Buffer, meta: {
+        filename: string;
+        contentType: string;
+        sha256: string;
+    }): Promise<any>;
+    /** The db3 mount of {@link getDocumentRoom}: `GET db3/:id/room`. App admins only. */
+    getDb3Room(appId: string, db3Id: string, query?: {
+        refused?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * `POST db3` (#4804): create a db3 and answer it, `{ id, title, createdBy,
+     * createdAt, modifiedAt, custodian, sync, type, tags }`. Without `custodian`
+     * an admin token's create is held by the app. `id` keeps a caller-chosen id
+     * (#4921), refused `DB3_ID_EXISTS` when the app holds it.
+     */
+    createDb3(appId: string, body: {
+        title: string;
+        type?: string;
+        sync?: boolean;
+        custodian?: string;
+        tags?: string[];
+        id?: string;
+    }): Promise<any>;
+    /** `GET db3/:id` (#4804): the db3, with the caller's grant when it reads it through one. */
+    getDb3(appId: string, db3Id: string): Promise<any>;
+    /** `DELETE db3/:id` (#4804): the documents delete for a db3. */
+    deleteDb3(appId: string, db3Id: string): Promise<any>;
+    /** The db3 mount of {@link getDocumentStats}: `GET db3/:id/stats`. */
+    getDb3Stats(appId: string, db3Id: string): Promise<any>;
+    /**
+     * `POST db3/:id/records/:model/:recordId/increment` (#4797): add each of
+     * `fields` to the record's field, answering `{ record, values }`.
+     */
+    incrementDb3Record(appId: string, db3Id: string, modelName: string, recordId: string, body: {
+        fields: Record<string, number>;
+    }): Promise<{
+        record: unknown;
+        values: Record<string, number>;
+    }>;
+    /** `GET db3/:id/sync` (#4799): `{ id, sync }`. */
+    getDb3Sync(appId: string, db3Id: string): Promise<{
+        id: string;
+        sync: boolean;
+    }>;
+    /** `PUT db3/:id/sync` (#4799): `{ id, sync, changed }`. */
+    setDb3Sync(appId: string, db3Id: string, sync: boolean): Promise<{
+        id: string;
+        sync: boolean;
+        changed: boolean;
+    }>;
+    /** `GET db3/:id/app-access` (#4801): `{ id, level }`, the level every user of the app holds, or null. */
+    getDb3AppAccess(appId: string, db3Id: string): Promise<{
+        id: string;
+        level: string | null;
+    }>;
+    /** `PUT db3/:id/app-access` (#4801): grant the db3 to every user of the app, or remove the grant with null. */
+    setDb3AppAccess(appId: string, db3Id: string, level: "reader" | "read-write" | null): Promise<{
+        id: string;
+        level: string | null;
+        changed: boolean;
+    }>;
+    /** One custodian's db3s through the admin API (#4800): `custodian` is `app` or `user:<userId>`. */
+    listDb3ByCustodian(appId: string, custodian: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string;
+        hasMore?: boolean;
+    }>;
+    /** Transfer a db3 to `to` (`app` or `user:<userId>`) through the admin API (#4804). */
+    transferDb3(appId: string, db3Id: string, to: string): Promise<any>;
+    /** Remove or restore a db3's owner row through the admin API (#4804): `{ id, custodian, ownerRow, changed }`. */
+    setDb3OwnerRow(appId: string, db3Id: string, present: boolean): Promise<{
+        id: string;
+        custodian: string;
+        ownerRow: boolean;
+        changed: boolean;
+    }>;
+    /** `GET db3/:id/type` (#4802): the type the db3's row names, its revision, and what its room holds. */
+    getDb3Type(appId: string, db3Id: string): Promise<any>;
+    /** `PUT db3/:id/type` (#4802): attach a type, installing its current revision whole or refusing it whole. */
+    attachDb3Type(appId: string, db3Id: string, type: string): Promise<any>;
+    /** `/app/<app>/api/db3-types/<name>`, the name encoded (#4802). */
+    private db3TypePath;
+    /** `GET db3-types` (#4802): the app's db3 types, each with its revision. */
+    listDb3Types(appId: string): Promise<{
+        types: any[];
+    }>;
+    /** `GET db3-types/:name` (#4802). */
+    getDb3TypeConfig(appId: string, name: string): Promise<any>;
+    /**
+     * `PUT db3-types/:name` (#4802): create or update the type, and push its new
+     * revision to every db3 of it. `dryRun` judges the body and persists nothing.
+     */
+    pushDb3Type(appId: string, name: string, data: {
+        ruleSetId?: string | null;
+        triggers?: Record<string, any> | null;
+        autoPopulatedFields?: Record<string, any> | null;
+        timestamps?: Record<string, any> | null;
+        schema?: string | null;
+        metadataManifest?: any;
+        expectedModifiedAt?: string;
+    }, options?: {
+        dryRun?: boolean;
+    }): Promise<any>;
+    /** `DELETE db3-types/:name` (#4802): refused while a db3 is of the type. */
+    deleteDb3Type(appId: string, name: string): Promise<any>;
+    /** `GET db3-types/:name/push-status` (#4802): a push's outcome per db3; the latest without `runId`. */
+    getDb3TypePushStatus(appId: string, name: string, runId?: string): Promise<any>;
+    /** `POST db3-types/:name/push?runId=` (#4802): push the current revision again to a run's refused and failed db3s. */
+    retryDb3TypePush(appId: string, name: string, runId: string): Promise<any>;
     createDocument(appId: string, data: {
         title: string;
         documentId?: string;
         tags?: string[];
         createdBy?: string;
-        documentFormat?: 1 | 2;
+        documentFormat?: 1 | 3;
     }): Promise<any>;
     listDocumentPermissions(appId: string, documentId: string): Promise<any[]>;
     grantDocumentPermission(appId: string, documentId: string, permissions: Array<{
@@ -2354,14 +2444,52 @@ export declare class ApiClient {
      * grants whose app invitation is still outstanding.
      */
     listDocumentPendingInvitations(appId: string, documentId: string): Promise<any>;
-    listDocumentBlobs(appId: string, documentId: string): Promise<any[]>;
+    /**
+     * One page of a document's uploaded blobs (the `{ items, hasMore,
+     * nextCursor? }` envelope); pass the previous page's `nextCursor` for the
+     * next.
+     */
+    listDocumentBlobs(appId: string, documentId: string, params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<any>;
     downloadBlob(appId: string, documentId: string, blobId: string): Promise<Buffer>;
+    /** A blob's bytes from `<base>/blobs/<id>/download`: the documents route or its db3 mount. */
+    private downloadBlobAt;
     uploadBlob(appId: string, documentId: string, blobId: string, data: Buffer, meta: {
         filename: string;
         contentType: string;
         sha256: string;
     }): Promise<any>;
+    /** A blob PUT to `<base>/blobs/<id>`: the documents route or its db3 mount. */
+    private uploadBlobAt;
+    /**
+     * Upload a file to an agent session by `sessionId` (#4585): the document
+     * blob upload's headers and body, on the session's attachment route.
+     */
+    uploadAgentSessionAttachment(appId: string, sessionId: string, blobId: string, data: Buffer, meta: {
+        filename: string;
+        contentType: string;
+        sha256: string;
+    }): Promise<any>;
+    /** Download an agent session's file by `sessionId` (#4585). */
+    downloadAgentSessionAttachment(appId: string, sessionId: string, blobId: string): Promise<Buffer>;
+    /**
+     * An agent session file's download headers (lower-cased names) by
+     * `sessionId` (#4585). A refusal has no body, so it fails with the status
+     * alone and no code.
+     */
+    headAgentSessionAttachment(appId: string, sessionId: string, blobId: string): Promise<{
+        status: number;
+        headers: Record<string, string>;
+    }>;
+    private agentSessionAttachmentRead;
     listDocumentAliases(appId: string, documentId: string): Promise<any[]>;
+    /**
+     * The document a user's alias points at, or null when the user holds no
+     * alias under that key (#4148).
+     */
+    getDocumentAlias(appId: string, aliasScope: string, aliasKey: string, userId: string): Promise<any | null>;
     setDocumentAlias(appId: string, aliasScope: string, aliasKey: string, documentId: string, ownerUserId?: string, mustNotExist?: boolean): Promise<any>;
     /**
      * Resolve an app user by exact email — the single email → userId lookup in
@@ -2416,6 +2544,7 @@ export declare class ApiClient {
      */
     getUserRootDocument(appId: string, userId: string): Promise<{
         rootDocId: string | null;
+        documentFormat?: number;
     }>;
     /**
      * Get or create the user's root document (#3135).
@@ -2428,6 +2557,7 @@ export declare class ApiClient {
     ensureUserRootDocument(appId: string, userId: string): Promise<{
         rootDocId: string;
         created: boolean;
+        documentFormat?: number;
     }>;
     /**
      * Apply an ordered batch of record operations via `records/batch`.