@vxil/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3103 @@
+/** The released API majors, as a CLOSED union — one per released major (docs/
+ *  feature-versioning.md §3). `'v1'` is the only released major, so pinning
+ *  anything else (`apiVersion: 'v2'`) is a COMPILE error until a v2 GAs and
+ *  widens this union. Every path the SDK builds is major-versioned; the default
+ *  is the compile-time constant `'v1'` (never a floating `latest` alias). */
+export type ApiVersion = 'v1';
+/** A per-feature API-version override key: the URL namespace that leads a path
+ *  (`/v1/<namespace>/…`). Matches the segment `versionedPath` rewrites, so an
+ *  override changes exactly that namespace's paths. Renamed client accessors map
+ *  onto their real namespaces (`vx.search` → `search`, `vx.feeds` → `feeds`). */
+export type FeatureKey = 'users' | 'notifications' | 'config' | 'features' | 'audit' | 'jobs' | 'auth' | 'rate-limits' | 'files' | 'cms' | 'comments' | 'dm' | 'feeds' | 'realtime' | 'orgs' | 'webhooks' | 'search' | 'ai' | 'rag' | 'payments' | 'fn' | 'copilot';
+export interface VxilOptions {
+    apiKey: string;
+    /** defaults to the production edge */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /** An end-user's vxil-`auth` **session token** (the ES256 JWT `auth` mints).
+     *  When set, every request additionally carries it as the `X-Vxil-End-User`
+     *  header — the edge verifies it and threads a **verified `end_user_id`** into
+     *  the inner JWT, putting the request in **end-user mode** (owner-scoped reads/
+     *  writes on owned collections; default-safe). This is the thin-client shape:
+     *  a mobile/SPA holds a public/thin-client key + the signed-in user's session
+     *  token and calls the edge directly, safely scoped to that user. Absent ⇒
+     *  **no header** ⇒ server-caller mode, exactly as today (backward compatible).
+     *  See docs/end-user-principals-design.md §4.1, §10. For a per-call override on
+     *  an otherwise server-mode client, use `vx.asEndUser(token)`. */
+    endUserToken?: string;
+    /** Global API major every request pins (default `'v1'`). Path-major, per
+     *  docs/feature-versioning.md — a breaking change ships as a new major on a
+     *  new path, never in place. */
+    apiVersion?: ApiVersion;
+    /** Per-feature API-major overrides (`{ cms: 'v2' }`); each takes precedence
+     *  over `apiVersion` for that namespace only. Optional; the compiled default
+     *  is `'v1'` for every feature. */
+    apiVersions?: Partial<Record<FeatureKey, ApiVersion>>;
+}
+/** Rewrite a built `/v1/<ns>/…` path onto the version configured for its
+ *  namespace: the per-namespace override wins, else the global default. PURE and
+ *  exported so it is unit-testable with a hypothetical future major (the runtime
+ *  accepts any version string; the public options constrain to the `ApiVersion`
+ *  union). A path whose first segment is not `/v1` is returned untouched. */
+export declare function versionedPath(path: string, globalDefault: string, overrides: Record<string, string>): string;
+export interface Meta {
+    request_id: string;
+    tenant_id?: string;
+}
+export declare class VxilError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly hint?: string | undefined;
+    readonly fixUrl?: string | undefined;
+    readonly requestId?: string | undefined;
+    constructor(status: number, code: string, message: string, hint?: string | undefined, fixUrl?: string | undefined, requestId?: string | undefined);
+}
+export interface VxilUser {
+    id: string;
+    email: string | null;
+    display_name: string | null;
+    avatar_url: string | null;
+    attributes: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+    /** Set when the row's PII was scrubbed via DELETE /v1/users/:id?erase=true (GDPR Article 17). null = retained. */
+    erased_at?: string | null;
+}
+export interface Delivery {
+    delivery_id: string;
+    end_user_id: string;
+    template_id: string;
+    locale: string;
+    to_email: string;
+    status: 'queued' | 'sent' | 'failed' | 'suppressed';
+    attempts: number;
+    provider: string;
+    provider_message_id: string | null;
+    last_error_code: string | null;
+    queued_at: string;
+    sent_at: string | null;
+    failed_at: string | null;
+}
+export interface FeatureConfig {
+    feature: string;
+    version: number;
+    manifest: Record<string, unknown>;
+}
+export interface DeadLetter {
+    delivery_id: string;
+    template_id: string;
+    to_email: string;
+    last_error_code: string | null;
+    created_at: string;
+    replayed_at: string | null;
+}
+export interface JobRun {
+    run_id: string;
+    job_name: string;
+    kind?: string;
+    state: 'queued' | 'running' | 'retrying' | 'waiting' | 'delayed' | 'succeeded' | 'failed' | 'dead' | 'cancelled';
+    attempt_number: number;
+    max_attempts?: number;
+    last_error_class?: string | null;
+    last_error_msg?: string | null;
+    /** earliest next pickup time; for a 'delayed' run this is deliver_after */
+    next_attempt_at?: string | null;
+    queued_at: string;
+    completed_at: string | null;
+}
+export interface JobFlowRule {
+    rule_id: string;
+    match_kind: 'endpoint' | 'job_name';
+    match_value: string;
+    max_parallel: number | null;
+    rate_per_minute: number | null;
+    state: string;
+    created_at: string;
+}
+export interface JobSchedule {
+    schedule_id: string;
+    job_name: string;
+    cron: string | null;
+    run_at: string | null;
+    next_run_at: string | null;
+    state: string;
+}
+export interface AuthSession {
+    token: string;
+    refresh_token: string;
+    expires_at: string;
+}
+export interface RateLimitPolicy {
+    policy_id: string;
+    name: string;
+    key_template: string;
+    limit: number;
+    window_seconds: number;
+    behavior: 'block' | 'shape';
+}
+/** A per-identifier override layered over a policy (exact pattern beats
+ *  wildcard; among `*`-globs the longest literal prefix wins). Unset fields
+ *  fall through to the policy. */
+export interface RateLimitOverride {
+    override_id: string;
+    pattern: string;
+    limit?: number;
+    window_seconds?: number;
+    behavior?: 'block' | 'shape';
+    note?: string;
+    created_at: string;
+    updated_at?: string;
+}
+/** A payments provider webhook delivery in the event log (payments.md §7).
+ *  `payload` and `raw_body` are only populated on the detail read. */
+export interface PaymentsWebhookEvent {
+    event_id: string;
+    provider: string;
+    provider_evt_id: string;
+    event_type: string;
+    /** received | processed | error | sig_failed | parse_failed | reprocessed */
+    outcome: string | null;
+    signature_ok: boolean;
+    error: string | null;
+    received_at: string | null;
+    processed_at: string | null;
+    reprocess_count: number;
+    reprocessed_at: string | null;
+    /** detail-only: the verified provider payload (jsonb; '{}' for failed rows). */
+    payload?: unknown;
+    /** detail-only: the raw body of a sig_failed/parse_failed delivery (≤64KB). */
+    raw_body?: string | null;
+    provider_event_ts?: string | null;
+}
+export interface FileObject {
+    object_id: string;
+    filename: string;
+    content_type: string;
+    size_bytes: number;
+    status: 'pending' | 'available' | 'deleted';
+    created_at: string;
+}
+/** One recognized OCR text block (files.md §1.1). bbox is [x, y, w, h] in the
+ *  provider's unit space; page is 1-based. confidence is 0..1 normalized per
+ *  provider (Textract native 0..100 divided by 100; mock pins 0.95); absent
+ *  when the provider supplied none. */
+export interface OcrBlock {
+    text: string;
+    bbox: [number, number, number, number];
+    page: number;
+    confidence?: number;
+}
+/** A created/updated search collection (POST /v1/search/collections). */
+export interface SearchCollection {
+    collection: string;
+    dimensions: number;
+    backend: string;
+}
+/** A document row in a collection listing (GET …/documents). */
+export interface SearchDocument {
+    doc_id: string;
+    user_id: string | null;
+    source_file: string | null;
+    status: 'indexing' | 'indexed' | 'failed';
+    chunks: number;
+    metadata: Record<string, unknown>;
+    created_at: string;
+}
+/** One ingest input: chunk text OR bring-your-own precomputed vectors. */
+export interface SearchIngestInput {
+    doc_id: string;
+    user_id?: string;
+    source_file?: string;
+    /** vxil chunks + embeds this. Omit when supplying `chunks`/`vector`. */
+    text?: string;
+    /** BYOV: explicit chunks, each optionally carrying its own precomputed vector. */
+    chunks?: Array<{
+        chunk_id?: string;
+        content: string;
+        vector?: number[];
+    }>;
+    /** BYOV shorthand: one precomputed vector applied to the whole document. */
+    vector?: number[];
+    metadata?: Record<string, unknown>;
+    /** Skip re-embedding when the (text, metadata) content hash matches the
+     *  stored, indexed doc → `status: 'unchanged'` (no embed cost, no re-chunk). */
+    if_changed?: boolean;
+}
+/** The ingest acknowledgement (202 'indexed'; 200 'unchanged' on an
+ *  `if_changed` hash match). */
+export interface SearchIngestResult {
+    doc_id: string;
+    status: 'indexed' | 'unchanged' | string;
+    chunks?: number;
+    embedding_tokens?: number;
+}
+/** One hybrid/vector/keyword retrieval hit. */
+export interface SearchHit {
+    chunk_id: string;
+    doc_id: string;
+    text: string;
+    score: number;
+    /** provider relevance score — present only when the hit went through the
+     *  configured BYO reranker (`reranked: true` on the result set). */
+    rerank_score?: number;
+    metadata: Record<string, unknown>;
+}
+/** A query result set (POST …/query). */
+export interface SearchQueryResult {
+    results: SearchHit[];
+    backend: string;
+    mode: 'hybrid' | 'vector' | 'keyword';
+    /** true when the configured BYO reranker re-ordered the fused candidates;
+     *  false when not configured, opted out, or the provider failed (fail-open). */
+    reranked?: boolean;
+}
+/** Embedding-token + query + rerank counts since a timestamp (GET /v1/search/usage). */
+export interface SearchUsage {
+    since: string;
+    embedding_tokens: number;
+    query_count: number;
+    rerank_count?: number;
+}
+/** One configured auto-sync source (config sync[]) LEFT-joined with its
+ *  cron-cursor state (GET /v1/search/sync). */
+export interface SearchSyncSource {
+    source_key: string;
+    source: 'cms';
+    cms_collection: string;
+    collection: string;
+    cron: string;
+    phase: 'backfill' | 'incremental' | string;
+    cursor_updated_at: string | null;
+    backfill_started_at: string | null;
+    last_run_at: string | null;
+    last_sweep_at: string | null;
+    last_error: string | null;
+    docs_synced: number;
+}
+/** Per-call provider token usage. */
+export interface AiUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+/** One tool invocation the model asked for (tool-use passthrough — vxil relays,
+ *  YOU execute). Echo `id` back as `tool_call_id` on the `role:'tool'` turn. */
+export interface AiToolCall {
+    id?: string;
+    name: string;
+    arguments: unknown;
+}
+/** A prior conversation turn for the tool-calling round-trip: assistant turns
+ *  carry the tool_calls they made; `role:'tool'` turns carry one call's result
+ *  (`tool_call_id` correlates it; `name` is the tool's name). */
+export interface AiChatMessage {
+    role: 'user' | 'assistant' | 'tool';
+    content?: string;
+    tool_calls?: AiToolCall[];
+    tool_call_id?: string;
+    name?: string;
+}
+/** A synchronous generation result (POST /v1/ai/generate without stream). */
+export interface AiGeneration {
+    generation_id: string;
+    text: string;
+    usage: AiUsage;
+    finish: string;
+    tool_calls?: AiToolCall[];
+    cached: boolean;
+}
+/** A streamed generation handle: open the realtime channel for token frames. */
+export interface AiStreamHandle {
+    generation_id: string;
+    channel: string;
+    token?: string;
+    ttl_seconds?: number;
+    connect_path?: string;
+    resume_path: string;
+}
+/** Frames delivered over the ai:<generation_id> realtime channel and the
+ *  ?since= replay buffer (the WS envelope is { event, data } — `event` is the
+ *  frame type; replayed frames carry it as `type`). `title` arrives early when
+ *  the stream was requested with title/title_template; only the terminal usage
+ *  frame carries done:true. */
+export type AiStreamFrame = {
+    type?: 'token';
+    seq: number;
+    delta: string;
+} | {
+    type?: 'title';
+    seq: number;
+    title: string;
+} | {
+    type?: 'usage';
+    seq: number;
+    done: true;
+    finish: string;
+    usage: AiUsage;
+    tool_calls?: AiToolCall[];
+};
+/** The live-only `token_expiring` event (never seq'd, never replayed): fired
+ *  ~30s before each 300s connect-token window ends on a long stream. Re-mint
+ *  via ai.remintToken() and reconnect with ?since=<last seen seq>. */
+export interface AiTokenExpiringEvent {
+    generation_id: string;
+    ttl_seconds: number;
+    remint_path: string;
+}
+/** A job-routed async generation handle (POST /v1/ai/generate with mode:'job').
+ *  The jobs run drives the provider call; read the answer via the replay buffer
+ *  (`resume_path`) or track the run through the jobs surface. */
+export interface AiJobHandle {
+    generation_id: string;
+    run_id: string;
+    status: string;
+    resume_path: string;
+}
+/** A re-minted mid-stream connect token (GET /v1/ai/generations/{id}/token). */
+export interface AiStreamToken {
+    generation_id: string;
+    channel: string;
+    token: string;
+    ttl_seconds: number;
+    connect_path: string;
+    resume_path: string;
+}
+/** An embedding result (POST /v1/ai/embed). */
+export interface AiEmbedResult {
+    embeddings: number[][];
+    usage: AiUsage;
+    generation_id: string;
+}
+/** Per-user token rollups (GET /v1/ai/usage). */
+export interface AiUsageReport {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    generations: number;
+    cached: number;
+    by_user: Record<string, {
+        input_tokens: number;
+        output_tokens: number;
+    }>;
+}
+/** A citation: the retrieved chunk that grounded the answer. */
+export interface RagCitation {
+    chunk_id: string;
+    doc_id: string;
+    source?: {
+        file?: string;
+        page?: number;
+    };
+    score: number;
+}
+/** A synchronous grounded answer (POST /v1/rag/answer without stream). */
+export interface RagAnswer {
+    answer: string;
+    citations?: RagCitation[];
+    usage: {
+        retrieval_ms: number;
+        retrieved: number;
+        used: number;
+        input_tokens: number | null;
+        output_tokens: number | null;
+    };
+    finish?: string;
+}
+/** A streamed grounded answer: citations up front, tokens over the channel. */
+export interface RagStreamHandle {
+    generation_id: string;
+    channel: string;
+    token: string;
+    ttl_seconds: number;
+    /** RAG-native resume (`/v1/rag/answers/{id}/stream?since=0`) — a rag-scoped
+     *  key suffices; see `rag.resume()`. */
+    resume_path: string;
+    /** The underlying ai resume path (needs an ai-scoped credential). */
+    ai_resume_path?: string;
+    citations?: RagCitation[];
+    usage: {
+        retrieval_ms: number;
+        retrieved: number;
+        used: number;
+    };
+}
+/** A scored hit from the retrieval-only surface (POST /v1/rag/search). */
+export interface RagSearchHit {
+    chunk_id: string;
+    doc_id: string;
+    text: string;
+    /** the raw retrieval score (RRF, or rerank relevance when reranked). */
+    score: number;
+    /** the effective post-boost score results are RANKED by — present only when
+     *  metadata boosts applied (rag.md §2f). */
+    boosted_score?: number;
+    metadata?: Record<string, unknown>;
+}
+/** Retrieval-only result: the exact chunks `rag.answer` would ground on, with
+ *  rerank + metadata boosts applied — no generation, no token spend. */
+export interface RagSearchResult {
+    /** post-boost order. */
+    results: RagSearchHit[];
+    /** true when vector-search's BYO rerank pass re-scored the hits. */
+    reranked: boolean;
+    usage: {
+        retrieval_ms: number;
+        retrieved: number;
+    };
+}
+/** A replayed frame page from the rag-native resume endpoint (proxies the ai
+ *  §2a replay buffer: every recorded frame with seq > since, plus done). */
+export interface RagResumePage {
+    generation_id: string;
+    since: number;
+    frames: Array<Record<string, unknown>>;
+    done: boolean;
+    max_seq: number;
+}
+/** Aggregated retrieval + generation usage (GET /v1/rag/usage). */
+export interface RagUsage {
+    retrieval: SearchUsage | null;
+    generation: AiUsageReport | null;
+}
+/** A conversation row (a chat session pinned to one config agent). */
+export interface CopilotConversation {
+    conversation_id: string;
+    agent_id: string;
+    end_user_id: string | null;
+    title: string | null;
+    status: 'open' | 'closed' | 'escalated';
+    created_at: string;
+    updated_at: string;
+}
+/** A citation attached to a grounded answer (the rag invariant: exactly the
+ *  budgeted kept chunks — a citation can never lie). */
+export interface CopilotCitation {
+    chunk_id: string;
+    document_id?: string;
+    score?: number;
+    [k: string]: unknown;
+}
+/** A proposed WRITE action the agent wants to take — inert until confirmed. */
+export interface CopilotProposal {
+    message_id: string;
+    tool: string;
+    args: Record<string, unknown>;
+    feature: string | null;
+    proposed_at: string;
+    require_confirm: boolean;
+    confirm_path: string;
+}
+/** One transcript message (the getConversation payload). */
+export interface CopilotMessage {
+    message_id: string;
+    role: 'user' | 'assistant' | 'tool' | 'system';
+    content: string;
+    citations: CopilotCitation[];
+    proposal: CopilotProposal | null;
+    action_status: 'none' | 'proposed' | 'confirmed' | 'rejected';
+    action_result: unknown;
+    confirmed_at: string | null;
+    input_tokens: number;
+    output_tokens: number;
+    created_at: string;
+}
+/** The synchronous turn result: the answer text + citations + an optional
+ *  proposal, plus the realtime streaming handle (channel/token/resume_path) for
+ *  callers that prefer the live token stream over the synchronous `answer`. */
+export interface CopilotTurn {
+    conversation_id: string;
+    message_id: string;
+    answer: string;
+    action_status: 'none' | 'proposed';
+    proposal?: CopilotProposal;
+    citations: CopilotCitation[];
+    channel: string;
+    token?: string;
+    ttl_seconds?: number;
+    connect_path?: string;
+    resume_path: string;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        steps: number;
+    };
+}
+/** A resumed page of streamed frames (citations → token → terminal usage). */
+export interface CopilotStreamPage {
+    conversation_id: string;
+    message_id: string;
+    since: number;
+    frames: Array<Record<string, unknown>>;
+    done: boolean;
+    max_seq: number;
+}
+/** The confirm result: a fresh follow-up assistant message + the downstream
+ *  envelope verbatim. `already:true` marks an idempotent replay of a prior
+ *  confirm (same key, no double-execute). */
+export interface CopilotConfirmResult {
+    message_id: string;
+    proposal_message_id?: string;
+    action_status: 'confirmed';
+    already?: boolean;
+    confirmed_at: string | null;
+    result: unknown;
+}
+/** Per-user token rollup (assistant rows summed by end_user_id). */
+export interface CopilotUsage {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    turns: number;
+    by_user: Record<string, {
+        input_tokens: number;
+        output_tokens: number;
+    }>;
+}
+/** A single activity row as returned in a flat feed page. */
+export interface FeedActivity {
+    id: string;
+    actor: string;
+    verb: string;
+    object: string;
+    target: string | null;
+    time: string;
+    extra: Record<string, unknown>;
+}
+/** A flat feed read page (push∪pull union, deduped + merged on sort_key). */
+export interface FlatFeedPage {
+    feed: string;
+    type: 'flat';
+    activities: FeedActivity[];
+    next_cursor: string | null;
+}
+/** An aggregation / notification group row. `seen`/`read` are present only on
+ * notification feeds. */
+export interface FeedGroup {
+    group: string;
+    activity_count: number;
+    actor_count: number;
+    last_actor: string;
+    updated_at: string;
+    seen?: boolean;
+    read?: boolean;
+}
+/** An aggregated- or notification-feed read page (groups by updated_at DESC).
+ * Notification feeds additionally carry the badge envelope (unseen/unread/total). */
+export interface GroupedFeedPage {
+    feed: string;
+    type: 'aggregated' | 'notification';
+    groups: FeedGroup[];
+    next_cursor: string | null;
+    /** Notification feeds only: the live badge alongside the page. */
+    unseen?: number;
+    unread?: number;
+    total?: number;
+}
+export type FeedPage = FlatFeedPage | GroupedFeedPage;
+/** The notification badge ({ unseen, unread, total }). */
+export interface FeedBadge {
+    unseen: number;
+    unread: number;
+    total: number;
+}
+/** Per-user notification preference policy. */
+export interface FeedPreferences {
+    policy: Record<string, unknown>;
+    mute_until: string | null;
+    updated_at?: string;
+}
+/** A realtime connect token scoped to one of the requested feed channels. */
+export interface FeedRealtimeToken {
+    feed: string;
+    token: string;
+    connect_path: string;
+    expires_at: string;
+}
+/** A single activity to add to a feed. `to` CCs the activity into other feeds. */
+export interface FeedActivityInput {
+    actor: string;
+    verb: string;
+    object: string;
+    target?: string;
+    /** ISO-8601; defaults to now(). Forms the idempotency key with foreign_id. */
+    time?: string;
+    /** Idempotency key (upsert is on (foreign_id, time)). */
+    foreign_id?: string;
+    /** CC the activity into these other feed refs ("{group}:{feed_id}"). */
+    to?: string[];
+    extra?: Record<string, unknown>;
+    ranking_vars?: Record<string, unknown>;
+}
+/** A DM conversation envelope (open/reuse result). `reused` is true when a
+ *  direct pair re-opens its existing thread. */
+export interface DmConversation {
+    conversation_id: string;
+    topic: string;
+    kind: string;
+    participants: string[];
+    reused: boolean;
+}
+/** One row of the "my inbox" listing (a user's active conversations). */
+export interface DmInboxConversation {
+    conversation_id: string;
+    topic: string;
+    kind: string;
+    subject: string | null;
+    last_message_at: string | null;
+    muted: boolean;
+    unread: boolean;
+}
+/** A DM message — a `comments` row on the `dm:<conversation_id>` topic. */
+export interface DmMessage {
+    comment_id: string;
+    topic: string;
+    parent_id: string | null;
+    author_id: string;
+    body: string | null;
+    reactions: Record<string, string[]>;
+    created_at: string;
+    edited_at: string | null;
+    deleted: boolean;
+}
+/** The DM feature config (its `dm`-gated leaf flags) + its persisted version. */
+export interface DmConfigState {
+    config: {
+        enabled: boolean;
+        maxParticipants: number;
+        realtimeDelivery: boolean;
+        blockingEnabled: boolean;
+    } & Record<string, unknown>;
+    version: number;
+    configured: boolean;
+}
+/** The structural shape a `vxil gen`-generated `VxilSchema` satisfies. The base
+ *  `Vxil` class is generic over it (`new Vxil<VxilSchema>(...)`), exactly the
+ *  `createClient<Database>()` move — types are layered on; the runtime is
+ *  unchanged. The default keeps `new Vxil({ apiKey })` (no generic) permissive. */
+export interface VxilSchemaShape {
+    features: string;
+    cms: Record<string, {
+        Row: unknown;
+        Insert: unknown;
+        Patch: unknown;
+        Sortable: string;
+        Filterable: Record<string, unknown>;
+    }>;
+    functions: Record<string, {
+        Input: unknown;
+        Output: unknown;
+    }>;
+}
+/** feature client property → the feature key (in S['features']) that enables it.
+ *  The renamed namespaces map to their real feature ids. Used by EnabledVxil to
+ *  disable namespaces a tenant hasn't enabled. */
+interface FeatureMap {
+    notifications: 'notifications';
+    jobs: 'jobs';
+    auth: 'auth';
+    rateLimits: 'rate-limits';
+    files: 'files';
+    webhooks: 'webhooks';
+    comments: 'comments';
+    cms: 'cms';
+    realtime: 'realtime';
+    orgs: 'orgs';
+    feeds: 'activity-feed';
+    activityFeed: 'activity-feed';
+    search: 'vector-search';
+    ai: 'ai';
+    rag: 'rag';
+    payments: 'payments';
+    copilot: 'copilot';
+}
+/** A disabled namespace resolves to this string-literal type — its TEXT is the
+ *  fix, so `vx.rag.answer()` errors with "Property 'answer' does not exist on
+ *  type 'vxil: feature 'rag' is not enabled — …'". */
+type DisabledFeature<K extends string> = `vxil: feature '${K}' is not enabled — add it to vxil.config.ts and re-run \`vxil gen\``;
+type DisabledFeatures<S extends VxilSchemaShape> = {
+    [P in keyof FeatureMap]: FeatureMap[P] extends S['features'] ? never : P;
+}[keyof FeatureMap];
+/** The feature-narrowed client: feature namespaces the tenant hasn't enabled become
+ *  a compile error (the design's §4.4 headline). `Vxil.connect<VxilSchema>()`
+ *  returns it; plain `new Vxil<VxilSchema>()` stays un-narrowed for back-compat. */
+export type EnabledVxil<S extends VxilSchemaShape> = Omit<Vxil<S>, DisabledFeatures<S>> & {
+    [P in DisabledFeatures<S>]: DisabledFeature<FeatureMap[P] & string>;
+};
+/** A write guard (cms.md §10): "after this write, at most `max` live items
+ *  match `filter`". Requires `lock` — an unlocked guard is racy by construction. */
+export interface CmsGuard {
+    filter: Record<string, unknown>;
+    max: number;
+}
+/** One guard of a `guards[]` multi-invariant write (cms.md §10). Same
+ *  { filter, max } as CmsGuard plus an optional custom 409 `message` surfaced on
+ *  the FIRST violation. */
+export interface CmsGuardTerm extends CmsGuard {
+    /** Custom guard_failed message (≤200 chars) for THIS invariant. */
+    message?: string;
+}
+/** Concurrency options shared by the cms write methods (cms.md §9–10). */
+export interface CmsWriteOpts {
+    /** Optimistic CAS: sent as `If-Match: <version>`; mismatch → 409 version_conflict. */
+    ifVersion?: number;
+    /** Bounded field precondition checked against the locked row (≤4 terms;
+     *  `{field: null}` = "absent or null" — the slot-claim shape). 409 precondition_failed. */
+    if?: Record<string, unknown>;
+    /** Per-(tenant,collection,key) advisory lock — serializes same-key writers. */
+    lock?: string;
+    /** Declarative capacity/overlap invariant; requires `lock`. 409 guard_failed.
+     *  Mutually exclusive with `guards`. */
+    guard?: CmsGuard;
+    /** Multiple capacity/overlap invariants evaluated co-atomically under the ONE
+     *  `lock` (≤4; requires `lock`; cms.md §10). Mutually exclusive with `guard`.
+     *  The FIRST failing guard's optional `message` rides the 409 guard_failed. */
+    guards?: CmsGuardTerm[];
+}
+/** The keys of Row whose values are numbers — the only legal `$inc` targets. */
+type NumericKeys<R> = {
+    [K in keyof R]-?: NonNullable<R[K]> extends number ? K : never;
+}[keyof R];
+/** cms-rel B2/B3 shared window: a t*-slotted field or created_at/updated_at/
+ *  published_at, ≤366 days wide. */
+export interface CmsWindow {
+    field: string;
+    sinceDays?: number;
+    since?: string;
+    until?: string;
+}
+/** cms-rel B2: the aggregate request body (cms.md §12.1). */
+export interface CmsAggregateBody {
+    /** 1–4 exprs; fn ∈ count|sum|min|max|avg (sum/avg need an n*-slot field). */
+    aggregates: Array<{
+        fn: 'count' | 'sum' | 'min' | 'max' | 'avg';
+        field?: string;
+        as?: string;
+    }>;
+    /** ≤2 slot-bound own fields (a relation field groups by related item id). */
+    groupBy?: string[];
+    /** full query DSL + ONE-hop dotted join terms. */
+    filter?: Record<string, unknown>;
+    window?: CmsWindow;
+    /** an aggregate alias or a groupBy key; '-x' = desc. Default: first aggregate desc. */
+    sort?: string;
+    /** group rows returned; clamped to 500. */
+    limit?: number;
+}
+/** cms-rel B3: the rank request body (cms.md §12.2). */
+export interface CmsRankBody {
+    /** REQUIRED: the ranked entity — a slot-bound own field (often a relation). */
+    groupBy: string;
+    /** default {fn:'count'}. */
+    metric?: {
+        fn: 'count' | 'sum' | 'min' | 'max' | 'avg';
+        field?: string;
+        as?: string;
+    };
+    rank: 'row_number' | 'rank' | 'percent_rank';
+    partitionBy?: string;
+    direction?: 'asc' | 'desc';
+    filter?: Record<string, unknown>;
+    window?: CmsWindow;
+    limit?: number;
+}
+/** cms-rel B4: one transaction step (cms.md §13). `$where` = the bounded CAS
+ *  precondition (the PATCH `if` grammar: ≤4 terms, scalar / null /
+ *  {$eq $ne $gt $gte $lt $lte $in}). */
+export type CmsTxStep = {
+    op: 'insert';
+    collection: string;
+    data: Record<string, unknown>;
+    status?: 'draft' | 'published';
+} | {
+    op: 'update';
+    collection: string;
+    item_id: string;
+    data: Record<string, unknown>;
+    $where?: Record<string, unknown>;
+} | {
+    op: 'delete';
+    collection: string;
+    item_id: string;
+    $where?: Record<string, unknown>;
+};
+/** A per-collection typed handle returned by `vx.from(collection)`. */
+export interface CollectionClient<C extends VxilSchemaShape['cms'][string]> {
+    create(data: C['Insert'], opts?: {
+        status?: 'draft' | 'published';
+        lock?: string;
+        guard?: CmsGuard;
+        guards?: CmsGuardTerm[];
+    }): Promise<{
+        item_id: string;
+        status: string;
+        version: number;
+        data: C['Row'];
+    }>;
+    get(itemId: string): Promise<C['Row']>;
+    query(q?: {
+        /** Keys AND values come from the generated `Filterable`: each field's value
+         *  is its operator union (`VxilFilterRange*` on slotted fields, equality/
+         *  `$in`/`$contains` otherwise), so a range op on a non-indexed field is a
+         *  compile error. Old generated schemas (scalar-valued `Filterable`) still
+         *  compile — they just stay equality-only. Escape hatch for anything the
+         *  types deliberately exclude: the untyped `vx.cms.items.query`. */
+        filter?: Partial<C['Filterable']>;
+        sort?: C['Sortable'] | `-${C['Sortable'] & string}`;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: C['Row'][];
+        next_cursor: string | null;
+    }>;
+    /** `SELECT count(*)` under the same bounded filter grammar (cms.md §9.4).
+     *  Refused (422) on collections with beforeRead visibility hooks. */
+    count(filter?: Partial<C['Filterable']>): Promise<number>;
+    patch(itemId: string, data: C['Patch'], opts?: CmsWriteOpts): Promise<C['Row']>;
+    /** Atomic in-database increment — ONE conditional UPDATE; never
+     *  read-modify-write (cms.md §9.3). Delta keys are the numeric Row fields. */
+    inc(itemId: string, incs: Partial<Record<NumericKeys<C['Row']> & string, number>>, opts?: Pick<CmsWriteOpts, 'ifVersion' | 'if'>): Promise<C['Row']>;
+    delete(itemId: string, opts?: Pick<CmsWriteOpts, 'ifVersion'>): Promise<{
+        item_id: string;
+        deleted: boolean;
+        cascaded: number;
+        set_null: number;
+    }>;
+    publish(itemId: string): Promise<C['Row']>;
+    /** cms-rel B2: bounded group-by aggregate (spec §7 `groupBy()` surface).
+     *  groupBy/field names are typed over the Row's keys; slot-existence stays a
+     *  runtime check — exactly like `query`. Joins stay expressed as dotted
+     *  filter keys (no `.join()` builder — one grammar, not two). */
+    aggregate(q: Omit<CmsAggregateBody, 'groupBy' | 'aggregates'> & {
+        aggregates: Array<{
+            fn: 'count' | 'sum' | 'min' | 'max' | 'avg';
+            field?: keyof C['Row'] & string;
+            as?: string;
+        }>;
+        groupBy?: Array<keyof C['Row'] & string>;
+    }): Promise<{
+        groups: Array<Record<string, unknown> & {
+            key?: Record<string, unknown>;
+        }>;
+        scanned: number;
+    }>;
+    /** cms-rel B3: window ranking over the aggregate. */
+    rank(q: Omit<CmsRankBody, 'groupBy' | 'partitionBy' | 'metric'> & {
+        groupBy: keyof C['Row'] & string;
+        partitionBy?: keyof C['Row'] & string;
+        metric?: {
+            fn: 'count' | 'sum' | 'min' | 'max' | 'avg';
+            field?: keyof C['Row'] & string;
+            as?: string;
+        };
+    }): Promise<{
+        entries: Array<{
+            key: Record<string, unknown>;
+            partition?: Record<string, unknown>;
+            metric: unknown;
+            rank: number;
+        }>;
+        scanned: number;
+    }>;
+}
+export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
+    private readonly base;
+    private readonly key;
+    private readonly fetchImpl;
+    private readonly apiVersion;
+    private readonly apiVersions;
+    /** The end-user session token threaded as `X-Vxil-End-User` when set (end-user
+     *  mode). Undefined ⇒ no header ⇒ server-caller mode (unchanged). */
+    private readonly endUserToken;
+    constructor(opts: VxilOptions);
+    /** The header bag every request layers on top of `authorization`: the
+     *  `X-Vxil-End-User` session token in end-user mode, nothing in server mode.
+     *  One place so `call()` and the `fn` proxy stay in lockstep. */
+    private authHeaders;
+    /** Return a client that sends `X-Vxil-End-User: <token>` on every request —
+     *  a per-call/scoped override of end-user mode over an otherwise server-mode
+     *  client, mirroring how the edge threads the verified principal. The base
+     *  URL, api key, fetch impl and version pins are inherited unchanged; only the
+     *  end-user token is (re)set. Pass a falsy token to get back a server-mode
+     *  client (drops the header). See docs/end-user-principals-design.md §4.1. */
+    asEndUser(endUserToken: string | undefined): Vxil<S>;
+    /** Build the versioned request path — the ONE place a wire path is finalized.
+     *  Every request (call(), audit.export, the fn proxy) routes through here, so
+     *  the per-feature/global major pin applies uniformly. Default → unchanged
+     *  `/v1/…`. */
+    private path;
+    /** Construct a FEATURE-NARROWED client: feature namespaces the tenant hasn't
+     *  enabled (per the generated `VxilSchema['features']`) become compile errors —
+     *  `Vxil.connect<VxilSchema>({ apiKey }).rag` won't type-check if `rag` is off.
+     *  Runtime is identical to `new Vxil`; this only adds the compile-time gate. */
+    static connect<S extends VxilSchemaShape = VxilSchemaShape>(opts: VxilOptions): EnabledVxil<S>;
+    /** Typed per-collection CMS handle (design §4.8). A thin wrapper over the
+     *  generic `cms.items.*` methods — the wire calls are identical; the generated
+     *  `VxilSchema` supplies the field types. `vx.cms.items.*` stays as the
+     *  always-available un-generic fallback. */
+    from<C extends keyof S['cms'] & string>(collection: C): CollectionClient<S['cms'][C]>;
+    /** Typed function invoke (design §4.5). `vx.fn.<name>(payload)` POSTs to
+     *  /v1/fn/<name>; the generated `VxilSchema` types Input/Output (Level-0
+     *  opaque until a function declares a signature). A Proxy gives the
+     *  `vx.fn.<name>` accessor shape without enumerating names at runtime. */
+    readonly fn: { [K in keyof S["functions"] & string]: (input: S["functions"][K]["Input"]) => Promise<S["functions"][K]["Output"]>; };
+    private call;
+    readonly users: {
+        upsert: (user: {
+            id: string;
+            email?: string;
+            display_name?: string;
+            avatar_url?: string;
+            attributes?: Record<string, unknown>;
+        }) => Promise<VxilUser>;
+        bulk: (users: Array<{
+            id: string;
+            email?: string;
+        }>) => Promise<number>;
+        get: (id: string, opts?: {
+            includeDeleted?: boolean;
+        }) => Promise<VxilUser>;
+        patch: (id: string, patch: {
+            email?: string | null;
+            display_name?: string | null;
+            avatar_url?: string | null;
+            attributes?: Record<string, unknown>;
+        }) => Promise<VxilUser>;
+        /**
+         * Delete a user. By default this is a SOFT delete (sets deleted_at; the PII
+         * persists for the 30-day retention window). Pass { erase: true } for GDPR
+         * Article 17 erasure: the row is soft-deleted AND its PII
+         * (email/display_name/avatar_url/attributes) is scrubbed, while the id is
+         * kept so cross-feature references stay intact. NOTE: a full account-delete
+         * flow also calls the auth half — POST /v1/auth/users/:id/erase — to erase
+         * the credential/session identity (see features/tenant-users.md §3).
+         */
+        delete: (id: string, opts?: {
+            erase?: boolean;
+        }) => Promise<void>;
+        list: (q?: {
+            email?: string;
+            /** substring match on email + display name (server-side, trgm-indexed), 1-100 chars */
+            q?: string;
+            cursor?: string;
+            limit?: number;
+        }) => Promise<{
+            users: VxilUser[];
+            next_cursor: string | null;
+        }>;
+    };
+    readonly notifications: {
+        send: (input: {
+            user_id: string;
+            template: "magic-link" | "welcome" | "transactional";
+            data: Record<string, unknown>;
+            locale?: string;
+            /** 'inbox'/'both' require config inboxEnabled */
+            channel?: "email" | "inbox" | "both";
+        }, opts?: {
+            idempotencyKey?: string;
+        }) => Promise<{
+            delivery_id?: string;
+            inbox_message_id?: string;
+            status: string;
+        }>;
+        inbox: {
+            list: (q: {
+                user_id: string;
+                unread_only?: boolean;
+                cursor?: string;
+                limit?: number;
+            }) => Promise<{
+                messages: Array<{
+                    msg_id: string;
+                    template_id: string;
+                    title: string;
+                    body: string;
+                    data: Record<string, unknown>;
+                    read_at: string | null;
+                    created_at: string;
+                }>;
+                unread_count: number;
+                next_cursor: string | null;
+            }>;
+            markRead: (msgId: string, userId: string) => Promise<void>;
+            markAllRead: (userId: string) => Promise<number>;
+        };
+        deliveries: (q?: {
+            user_id?: string;
+            status?: string;
+            limit?: number;
+        }) => Promise<Delivery[]>;
+        suppressions: {
+            list: () => Promise<Array<{
+                email_lower: string;
+                reason: string;
+                created_at: string;
+            }>>;
+            add: (email: string) => Promise<void>;
+            remove: (email: string) => Promise<void>;
+        };
+        /** Deliveries the retry budget could not save (the dashboard "Resend" surface). */
+        deadLetters: {
+            list: () => Promise<DeadLetter[]>;
+            /** Reset the row and re-enqueue the original message. */
+            replay: (deliveryId: string) => Promise<void>;
+        };
+        /** A single delivery by id (the list is `deliveries()`). */
+        delivery: (deliveryId: string) => Promise<Delivery>;
+        /** Email broadcast campaigns (notifications.md §11b): audience-ref fan-out
+         *  with quiet-hours + frequency-cap policy. `schedule_cron` sets a recurring
+         *  send (status `scheduled`); omit it for a `draft`. */
+        campaigns: {
+            create: (input: {
+                name: string;
+                template: string;
+                audience_ref: string;
+                channel?: "email" | "push" | "all";
+                data?: Record<string, unknown>;
+                schedule_cron?: string;
+                quiet_hours?: {
+                    tz: string;
+                    start: string;
+                    end: string;
+                };
+                freq_cap?: {
+                    perUserPerDay?: number;
+                    perUserPerCampaign?: number;
+                };
+            }) => Promise<{
+                campaign_id: string;
+                status: string;
+            }>;
+            list: () => Promise<Array<{
+                campaign_id: string;
+                name: string;
+                channel: string;
+                template_id: string;
+                audience_ref: string;
+                schedule_cron: string | null;
+                status: string;
+                created_at: string;
+            }>>;
+        };
+    };
+    readonly config: {
+        get: (feature: string) => Promise<FeatureConfig>;
+        /** Optimistic-concurrency write: pass the version you read (etag). */
+        set: (feature: string, manifest: Record<string, unknown>, opts?: {
+            ifMatch?: number;
+            surface?: "cli" | "mcp" | "dashboard";
+        }) => Promise<FeatureConfig>;
+    };
+    readonly features: {
+        /** The tenant's enabled-feature summary (GET /v1/features). Privilege-
+         * independent: any valid key may read it — it leaks no secrets, only which
+         * features the tenant has turned on. Mirrors what the MCP tool-list
+         * aggregation sees. (audit #113) */
+        list: () => Promise<string[]>;
+        /** The FULL enabled-feature summary: `features` + `api_versions` (released
+         * API majors per feature) + the additive `key` block — the CALLING key's
+         * identity and per-tool MCP permissions (allowed_tools/denied_tools
+         * patterns, api_keys 0057; mcp.md §6.7). `key` is absent for non-key
+         * callers and for keys without explicit tool perms. `list()` stays the
+         * stable flat-array shorthand. */
+        summary: () => Promise<{
+            features: string[];
+            api_versions: Record<string, string[]>;
+            key?: {
+                key_id: string;
+                agent?: string;
+                allowed_tools?: string[];
+                denied_tools?: string[];
+            };
+        }>;
+    };
+    readonly audit: {
+        list: (q?: {
+            since?: string;
+            cursor?: string;
+            limit?: number;
+        }) => Promise<Array<{
+            id: string;
+            event: string;
+            actor: string;
+            surface: string;
+            payload: Record<string, unknown>;
+            created_at: string;
+        }>>;
+        /**
+         * NDJSON export (≤10k rows/call, id-ascending). Returns parsed events +
+         * next_after_id for resumption (null = done).
+         */
+        export: (q?: {
+            since?: string;
+            until?: string;
+            after_id?: string;
+            limit?: number;
+        }) => Promise<{
+            events: Array<{
+                id: string;
+                event: string;
+                created_at: string;
+            } & Record<string, unknown>>;
+            next_after_id: string | null;
+            /** Present only if a line failed to parse — the batch is NOT aborted. */
+            parse_errors?: Array<{
+                line: number;
+                raw: string;
+            }>;
+        }>;
+    };
+    readonly jobs: {
+        /** Enqueue a one-off job; Vxil POSTs a signed callback to target_url with
+         * retries. deliver_after (ISO) / delay_seconds (≤ 30 d, at most one of the
+         * two) defer the first delivery; > 12 h returns state 'delayed'. */
+        enqueue: (input: {
+            job_name: string;
+            target_url: string;
+            payload?: Record<string, unknown>;
+            idempotency_key?: string;
+            max_attempts?: number;
+            deliver_after?: string;
+            delay_seconds?: number;
+        }) => Promise<{
+            run_id: string;
+            state: string;
+            deduplicated?: boolean;
+            deliver_after?: string;
+        }>;
+        /** Atomic multi-enqueue (≤100 items; any invalid item rejects the whole
+         * batch). Each item = the enqueue input, incl. per-item idempotency_key
+         * and deliver_after/delay_seconds. Results align with the input order. */
+        enqueueBatch: (items: Array<{
+            job_name: string;
+            target_url: string;
+            payload?: Record<string, unknown>;
+            idempotency_key?: string;
+            max_attempts?: number;
+            deliver_after?: string;
+            delay_seconds?: number;
+        }>) => Promise<{
+            runs: Array<{
+                run_id: string;
+                state: string;
+                deduplicated?: boolean;
+            }>;
+            count: number;
+        }>;
+        /** Enqueue a long-running EXTERNAL generation run (jobs.md §11): Vxil calls
+         * the provider (BYO key), tracks completion via poll/webhook, mirrors a typed
+         * generation_status onto a tenant record, enforces a built-in timeout, and
+         * (on failure) fires the payments credit-reversal.
+         *
+         * `reserve_credits` (§11.8) takes a PROVISIONAL held credit debit at enqueue
+         * (linked to the run), committed on `completed` and reversed on
+         * failed/timeout/DLQ. `amount` is positive-only and CLAMPED to the platform
+         * `config.generation.maxReserveCredits` cap; in end-user mode `user_id` is
+         * FORCED to the verified end-user (a mismatched user_id → 400). A 402 aborts
+         * the enqueue (insufficient balance); a runaway over the per-tenant
+         * outstanding-holds ceiling → 429. */
+        generation: (input: {
+            job_name: string;
+            provider: {
+                url: string;
+                method?: string;
+                headers?: Record<string, string>;
+                body?: Record<string, unknown>;
+            };
+            completion: {
+                mode: "poll" | "webhook";
+                status_path?: string;
+                poll?: {
+                    url: string;
+                    method?: string;
+                    headers?: Record<string, string>;
+                    interval_ms?: number;
+                };
+            };
+            status_mirror?: {
+                feature: string;
+                collection: string;
+                record_id: string;
+                column?: string;
+            };
+            timeout?: {
+                after_ms: number;
+                terminal_state?: "failed";
+            };
+            on_failure?: {
+                payments?: {
+                    reverse?: {
+                        job_ref?: string;
+                    };
+                };
+            };
+            reserve_credits?: {
+                amount: number;
+                user_id: string;
+                credit_type: string;
+                reason?: string;
+            };
+            payload?: Record<string, unknown>;
+            idempotency_key?: string;
+            max_attempts?: number;
+        }) => Promise<{
+            run_id: string;
+            generation_status: string;
+            state?: string;
+            deduplicated?: boolean;
+        }>;
+        runs: (q?: {
+            job_name?: string;
+            state?: string;
+            ids?: string[];
+            limit?: number;
+        }) => Promise<JobRun[]>;
+        run: (runId: string) => Promise<JobRun>;
+        cancel: (runId: string) => Promise<{
+            run_id: string;
+            state: string;
+        }>;
+        /** Clone a terminal run into a fresh queued run. */
+        replay: (runId: string) => Promise<{
+            run_id: string;
+            replayed_from: string;
+        }>;
+        /**
+         * Suspend the RUNNING run until an event (call from the executing
+         * handler, then return 200 — the suspension wins).
+         */
+        wait: (runId: string, input: {
+            event: string;
+            timeout_seconds?: number;
+        }) => Promise<void>;
+        /** Wake every run waiting on the event. */
+        emitEvent: (event: string, payload?: Record<string, unknown>) => Promise<number>;
+        /** Secret for verifying X-Vxil-Jobs-Signature on your callback endpoints. */
+        signingSecret: () => Promise<string>;
+        schedules: {
+            /** Recurring (5-field cron, UTC) or one-shot (run_at). Exactly one of cron/run_at. */
+            create: (input: {
+                job_name: string;
+                target_url: string;
+                payload?: Record<string, unknown>;
+                cron?: string;
+                run_at?: string;
+            }) => Promise<JobSchedule>;
+            list: () => Promise<JobSchedule[]>;
+            delete: (scheduleId: string) => Promise<void>;
+            /** Stop an active schedule firing (the row + next_run_at survive). */
+            pause: (scheduleId: string) => Promise<{
+                schedule_id: string;
+                state: string;
+            }>;
+            /** Resume a paused schedule; next_run_at recomputes (cron) or re-arms
+             * (one-shot; a lapsed run_at → 409 run_at_passed). */
+            resume: (scheduleId: string) => Promise<{
+                schedule_id: string;
+                state: string;
+                next_run_at: string;
+            }>;
+        };
+        /** Per-endpoint/job flow control: rate (per minute) + max parallelism,
+         * enforced by the executor. 'endpoint' matches the target_url https
+         * ORIGIN; 'job_name' matches exactly. */
+        flowRules: {
+            create: (input: {
+                match_kind: "endpoint" | "job_name";
+                match_value: string;
+                max_parallel?: number;
+                rate_per_minute?: number;
+            }) => Promise<JobFlowRule>;
+            list: () => Promise<JobFlowRule[]>;
+            delete: (ruleId: string) => Promise<void>;
+        };
+    };
+    readonly auth: {
+        signUp: (input: {
+            email: string;
+            password: string;
+        }) => Promise<{
+            user_id: string;
+            session: AuthSession;
+            verified: boolean;
+        }>;
+        signIn: (input: {
+            email: string;
+            password: string;
+        }) => Promise<{
+            user_id: string;
+            session: AuthSession;
+            verified: boolean;
+        }>;
+        magicLink: {
+            request: (input: {
+                email: string;
+                redirect_url: string;
+            }) => Promise<void>;
+            verify: (token: string) => Promise<{
+                user_id: string;
+                session: AuthSession;
+                verified: boolean;
+            }>;
+        };
+        /** Email OTP sign-in: a 6-digit single-use code (distinct from magic-link).
+         *  Server-side guessing budget (config otp.maxAttempts), single active code,
+         *  resend cooldown (429 otp_rate_limited). */
+        otp: {
+            request: (input: {
+                email: string;
+            }) => Promise<void>;
+            verify: (input: {
+                email: string;
+                code: string;
+            }) => Promise<{
+                user_id: string;
+                session: AuthSession;
+                verified: boolean;
+            }>;
+        };
+        /** Anonymous (guest) sessions: instant end-user + session (JWT carries
+         *  `anon: true`); later convertible via the email-claim OTP link flow. */
+        anonymous: {
+            signIn: () => Promise<{
+                user_id: string;
+                session: AuthSession;
+                anonymous: true;
+            }>;
+            link: {
+                request: (input: {
+                    token: string;
+                    email: string;
+                }) => Promise<void>;
+                verify: (input: {
+                    token: string;
+                    email: string;
+                    code: string;
+                }) => Promise<{
+                    user_id: string;
+                    email: string;
+                    verified: boolean;
+                }>;
+            };
+        };
+        /** Step-up re-auth: an OTP challenge on the CURRENT session. On verify the
+         *  bearer token ROTATES (the returned session.token replaces the old one —
+         *  swap it client-side) and the JWT gains an `elv` claim. */
+        stepUp: {
+            request: (input: {
+                token: string;
+            }) => Promise<void>;
+            verify: (input: {
+                token: string;
+                code: string;
+            }) => Promise<{
+                session: {
+                    token: string;
+                    expires_at: string;
+                };
+                elevated_at: string;
+            }>;
+        };
+        /** End-user administration (server/function surface, auth:write). */
+        users: {
+            /** GDPR PII erasure: anonymize the end-user's auth + tenant_users record
+             *  (email → tombstone, password/name/avatar cleared) and revoke every
+             *  live session. Idempotent — a second call on an already-erased user is a
+             *  no-op. Meant to be called from a "delete my account" server route or
+             *  vxil function (which declares `auth:write`). */
+            erase: (userId: string) => Promise<{
+                user_id: string;
+                erased: boolean;
+            }>;
+        };
+        sessions: {
+            verify: (token: string) => Promise<{
+                user_id: string;
+                email: string | null;
+                verified: boolean;
+                display_name: string | null;
+                expires_at: string;
+                /** when this session last passed a step-up OTP re-auth (null = never) */
+                elevated_at: string | null;
+            }>;
+            /** Rotates the refresh token: store the returned pair, discard the old one. */
+            refresh: (refreshToken: string) => Promise<{
+                user_id: string;
+                session: AuthSession;
+            }>;
+            revoke: (token: string) => Promise<void>;
+            /** Force-revoke a SPECIFIC session by its `session_id` (from `list`) — the
+             *  server-forced device-lockout path beyond the client-cooperative
+             *  by-token `revoke`. Throws 404 when the id is unknown or already revoked. */
+            revokeById: (sessionId: string) => Promise<void>;
+            /** List a user's active sessions (the account "signed-in devices" surface). */
+            list: (userId: string) => Promise<Array<{
+                session_id: string;
+                created_at: string;
+                expires_at: string;
+                user_agent: string | null;
+            }>>;
+        };
+        password: {
+            requestReset: (input: {
+                email: string;
+                redirect_url: string;
+            }) => Promise<void>;
+            /** Confirming kills every existing session for the user. */
+            confirmReset: (input: {
+                token: string;
+                password: string;
+            }) => Promise<void>;
+        };
+        /** Social sign-in. The web `start`/`callback` flows are browser redirects
+         *  (not JSON calls); `native` is the mobile token-exchange the SDK wraps. */
+        oauth: {
+            /** Native social sign-in: exchange a provider `id_token`/`access_token`
+             *  for a vxil session (`linked` marks whether the user was created or
+             *  matched to an existing identity). */
+            native: (provider: "google" | "apple" | "github" | "facebook" | "mock", input: {
+                id_token?: string;
+                access_token?: string;
+                nonce?: string;
+            }) => Promise<{
+                user_id: string;
+                session: AuthSession;
+                verified: boolean;
+                linked: "created" | "existing";
+            }>;
+        };
+    };
+    readonly rateLimits: {
+        createPolicy: (input: {
+            name: string;
+            key_template: string;
+            limit: number;
+            window_seconds: number;
+            behavior?: "block" | "shape";
+        }) => Promise<RateLimitPolicy>;
+        listPolicies: () => Promise<RateLimitPolicy[]>;
+        deletePolicy: (policyId: string) => Promise<void>;
+        /** Update a policy's mutable fields (name/limit/window/behavior/algorithm);
+         *  `policy_id` + `key_template` are immutable. */
+        updatePolicy: (policyId: string, patch: {
+            name?: string;
+            limit?: number;
+            window_seconds?: number;
+            behavior?: "block" | "shape";
+            algorithm?: "sliding_window" | "token_bucket";
+        }) => Promise<RateLimitPolicy>;
+        /** Reset a single rendered counter back to a full budget (the policy_id +
+         *  the key_values that render its key). */
+        resetCounter: (input: {
+            policy_id: string;
+            key_values?: Record<string, string>;
+        }) => Promise<{
+            policy_id: string;
+            key: string;
+            reset: boolean;
+        }>;
+        /** Per-policy usage analytics: hourly allowed/blocked buckets + top keys
+         *  (last `hours`, clamped 1..48, default 24). */
+        analytics: (input: {
+            policy_id: string;
+            hours?: number;
+        }) => Promise<{
+            policy_id: string;
+            hours: number;
+            buckets: Array<{
+                hour: number;
+                allowed: number;
+                blocked: number;
+            }>;
+            top_keys: Array<{
+                key: string;
+                allowed: number;
+                blocked: number;
+            }>;
+            totals: {
+                allowed: number;
+                blocked: number;
+            };
+        }>;
+        /**
+         * Consume budget. With behavior 'block' an exceeded check throws
+         * VxilError(429); 'shape' resolves with allowed=false instead.
+         * `override_id` is present when a per-identifier override was applied.
+         */
+        check: (input: {
+            policy_id: string;
+            key_values?: Record<string, string>;
+            cost?: number;
+        }) => Promise<{
+            allowed: boolean;
+            remaining: number;
+            reset_seconds: number;
+            override_id?: string;
+        }>;
+        /** Per-identifier overrides layered over a policy: `pattern` matches the
+         *  RENDERED key (exact, or a `*`-glob where the longest literal prefix
+         *  wins). Propagates to the check path within ≤30s (KV cacheTtl). */
+        overrides: {
+            list: (policyId: string) => Promise<RateLimitOverride[]>;
+            create: (policyId: string, input: {
+                pattern: string;
+                limit?: number;
+                window_seconds?: number;
+                behavior?: "block" | "shape";
+                note?: string;
+            }) => Promise<RateLimitOverride>;
+            /** `pattern` is immutable (like a policy's key_template). */
+            update: (policyId: string, overrideId: string, patch: {
+                limit?: number;
+                window_seconds?: number;
+                behavior?: "block" | "shape";
+                note?: string;
+            }) => Promise<RateLimitOverride>;
+            delete: (policyId: string, overrideId: string) => Promise<void>;
+        };
+    };
+    readonly cms: {
+        collections: {
+            /** Define a content type. The model is data — not config. */
+            create: (input: {
+                collection: string;
+                singular?: string;
+                /** End-user owner-scoping (docs/end-user-principals-design.md §5.1):
+                 *  names an existing `string` field that holds the owner id. When set,
+                 *  the cms worker auto-scopes owned reads/writes to the VERIFIED
+                 *  end-user principal (default-deny) in end-user mode; a no-op in
+                 *  server-caller mode. Omit for shared/reference collections. */
+                owner_field?: string;
+                fields?: Array<{
+                    field: string;
+                    type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file";
+                    required?: boolean;
+                    validation?: {
+                        min?: number;
+                        max?: number;
+                        regex?: string;
+                        enum?: unknown[];
+                    };
+                    index_slot?: "s1" | "s2" | "s3" | "s4" | "n1" | "n2" | "t1" | "t2";
+                    relation_to?: string;
+                    /** Value uniqueness across the collection's LIVE items (cms.md §9.3);
+                     *  scalar-valued types only. Concurrent duplicates → 409 unique_violation. */
+                    unique?: boolean;
+                    /** relation fields only: what a delete of the referenced item does to
+                     *  this one (bounded fan-out, cms.md §11). */
+                    on_delete?: "cascade" | "set_null";
+                }>;
+            }) => Promise<{
+                collection: string;
+                fields: number;
+                owner_field?: string;
+            }>;
+            list: () => Promise<Array<{
+                collection: string;
+                singular: string;
+                fields: unknown[];
+                owner_field?: string | null;
+            }>>;
+            addField: (collection: string, field: Record<string, unknown>) => Promise<void>;
+            /** Set (or clear, with `null`) the collection's end-user owner-scope flag
+             *  (design §5.1). Names an existing `string` field that holds the owner id. */
+            setOwnerField: (collection: string, ownerField: string | null) => Promise<void>;
+        };
+        items: {
+            /** `lock` serializes same-key writers (per-tenant advisory lock); `guard`
+             *  is the declarative capacity/overlap invariant (requires lock) — cms.md §10. */
+            create: (collection: string, input: {
+                data: Record<string, unknown>;
+                status?: "draft" | "published";
+                lock?: string;
+                guard?: CmsGuard;
+                guards?: CmsGuardTerm[];
+            }) => Promise<{
+                item_id: string;
+                status: string;
+                version: number;
+                data: Record<string, unknown>;
+            }>;
+            get: (collection: string, itemId: string) => Promise<Record<string, unknown>>;
+            /**
+             * The bounded query DSL. filter ops: $eq $ne $gt $gte $lt $lte $in
+             * $contains $startsWith (LIKE-escaped; trigram-indexed on s*-slotted
+             * fields) $arrayContains/$anyOf (json/relation array containment via the
+             * JSONB GIN); range/sort needs slot-indexed fields. This is the
+             * DELIBERATELY-UNTYPED escape hatch: it accepts everything the server
+             * admits, including unslotted range ops (served by unindexed JSONB
+             * scans, bounded only by the statement timeout) that the generated
+             * per-field `Filterable` unions on `vx.from(...).query` exclude.
+             */
+            query: (collection: string, q?: {
+                filter?: Record<string, unknown>;
+                sort?: string;
+                limit?: number;
+                cursor?: string;
+            }) => Promise<{
+                items: Array<Record<string, unknown>>;
+                next_cursor: string | null;
+            }>;
+            /** Merge-patch data keys; null clears a key. Concurrency opts (cms.md §9):
+             *  `ifVersion` → If-Match CAS; `if` → bounded field precondition against
+             *  the locked row; `lock`/`guard` → the §10 serialization primitives. */
+            patch: (collection: string, itemId: string, data: Record<string, unknown>, opts?: CmsWriteOpts) => Promise<Record<string, unknown>>;
+            /** Atomic in-database increment — PATCH `{ $inc: {field: delta} }`, ONE
+             *  conditional UPDATE guarded by the field's validation min/max (the quota
+             *  shape), the optional `if` precondition, and If-Match. 409
+             *  inc_out_of_bounds when the guard refuses (cms.md §9.3). */
+            inc: (collection: string, itemId: string, incs: Record<string, number>, opts?: Pick<CmsWriteOpts, "ifVersion" | "if">) => Promise<Record<string, unknown>>;
+            /** `{ count }` under the same bounded filter grammar (cms.md §9.4). 422
+             *  count_unavailable_with_read_hooks on beforeRead-hooked collections. */
+            count: (collection: string, filter?: Record<string, unknown>) => Promise<number>;
+            /** Returns the cascade tally (cms.md §11); `ifVersion` rides If-Match and
+             *  a conflict aborts BEFORE any cascade side-effect. */
+            delete: (collection: string, itemId: string, opts?: Pick<CmsWriteOpts, "ifVersion">) => Promise<{
+                item_id: string;
+                deleted: boolean;
+                cascaded: number;
+                set_null: number;
+            }>;
+            publish: (collection: string, itemId: string) => Promise<Record<string, unknown>>;
+            /** cms-rel B2 (cms.md §12): bounded group-by aggregate. fns count|sum|
+             *  min|max|avg over index-slot-bound fields; groupBy ≤2 slot-bound
+             *  fields; filter = the full query DSL incl. ONE-hop dotted join terms
+             *  ({"channel.visibility":"public"}); scan capped at 50k rows → 422
+             *  window_too_large (narrow the window or materialize a read-model). */
+            aggregate: (collection: string, body: CmsAggregateBody) => Promise<{
+                groups: Array<Record<string, unknown> & {
+                    key?: Record<string, unknown>;
+                }>;
+                scanned: number;
+            }>;
+            /** cms-rel B3 (cms.md §12): window ranking over the aggregate — rank ∈
+             *  row_number|rank|percent_rank, computed over ≤500 aggregated groups
+             *  (never raw rows), optional partitionBy. Same scan cap as aggregate. */
+            rank: (collection: string, body: CmsRankBody) => Promise<{
+                entries: Array<{
+                    key: Record<string, unknown>;
+                    partition?: Record<string, unknown>;
+                    metric: unknown;
+                    rank: number;
+                }>;
+                scanned: number;
+            }>;
+        };
+        /** cms-rel B4 (cms.md §13): atomic multi-collection transaction — 1–5
+         *  steps over ≤3 collections, per-step `$where` CAS preconditions (the
+         *  PATCH `if` grammar). All-or-nothing: any failed precondition/validation
+         *  rolls the WHOLE transaction back (409 precondition_failed names the
+         *  step). cms-internal only — no cross-feature effects inside the tx. */
+        transaction: (steps: CmsTxStep[]) => Promise<{
+            results: Array<{
+                op: string;
+                collection: string;
+                item_id: string;
+                status: string | null;
+                version: number;
+            }>;
+            committed: boolean;
+            tx_id: string;
+        }>;
+        /** cms-rel B5 (cms.md §12.4): declared read-models (config `readModels`
+         *  bag) — list with last-run status, and "run now" materialization into
+         *  the rollup collection. */
+        readModels: {
+            list: () => Promise<Array<{
+                name: string;
+                collection: string;
+                kind: "aggregate" | "rank";
+                cron: string | null;
+                to: string | null;
+                enabled: boolean;
+                last_run: Record<string, unknown> | null;
+            }>>;
+            materialize: (name: string) => Promise<{
+                name: string;
+                to: string;
+                groups_written: number;
+                scanned: number;
+                run_id: string;
+            }>;
+        };
+    };
+    readonly comments: {
+        create: (input: {
+            topic: string;
+            body: string;
+            author_id: string;
+            parent_id?: string;
+        }) => Promise<{
+            comment_id: string;
+            topic: string;
+            parent_id: string | null;
+            author_id: string;
+            body: string;
+            created_at: string;
+        }>;
+        list: (q: {
+            topic: string;
+            cursor?: string;
+            limit?: number;
+        }) => Promise<{
+            comments: Array<{
+                comment_id: string;
+                topic: string;
+                parent_id: string | null;
+                author_id: string;
+                body: string | null;
+                reactions: Record<string, string[]>;
+                created_at: string;
+                edited_at: string | null;
+                deleted: boolean;
+            }>;
+            next_cursor: string | null;
+        }>;
+        /** Author edit, allowed within the tenant's editWindowMinutes. */
+        edit: (commentId: string, input: {
+            body: string;
+            author_id: string;
+        }) => Promise<void>;
+        /** Tombstone. Pass author_id for self-delete; omit for tenant moderation. */
+        delete: (commentId: string, opts?: {
+            author_id?: string;
+        }) => Promise<void>;
+        /** Toggle an emoji reaction for an author. */
+        react: (commentId: string, input: {
+            emoji: string;
+            author_id: string;
+        }) => Promise<{
+            comment_id: string;
+            reactions: Record<string, string[]>;
+        }>;
+        /** Cross-topic recent-comments feed (tenant-wide, newest-first) — the
+         *  dashboard "recent activity" surface. Keyset cursor + optional filters. */
+        recent: (q?: {
+            topic_prefix?: string;
+            author_id?: string;
+            cursor?: string;
+            limit?: number;
+        }) => Promise<{
+            comments: Array<{
+                comment_id: string;
+                topic: string;
+                parent_id: string | null;
+                author_id: string;
+                body: string | null;
+                reactions: Record<string, string[]>;
+                created_at: string;
+                edited_at: string | null;
+                deleted: boolean;
+            }>;
+            next_cursor: string | null;
+        }>;
+    };
+    /**
+     * DM / inbox (the `dm` feature) — a conversation ENVELOPE composed over
+     * `comments` (message store) + `realtime` (delivery) + `presence`. DM owns
+     * only the envelope: membership, read-cursors, mute, and a directed block
+     * list; the messages themselves are `comments` rows on the
+     * `dm:<conversation_id>` topic. Gated by its own `dm` config, independent of
+     * comments. See docs/features/dm.md.
+     */
+    readonly dm: {
+        /** Read the resolved DM config (defaults merged with the stored partial). */
+        getConfig: () => Promise<DmConfigState>;
+        /** Write the DM master config — a partial merge (omitted leaves keep their
+         *  current value), version-bumped and republished to the gate's KV key. */
+        setConfig: (patch: {
+            enabled?: boolean;
+            maxParticipants?: number;
+            realtimeDelivery?: boolean;
+            blockingEnabled?: boolean;
+        }) => Promise<DmConfigState>;
+        conversations: {
+            /** Open (or, for a direct pair, return the existing) conversation. A
+             *  `direct` conversation (exactly 2 people) dedupes on the unordered pair
+             *  (reused:true); a block on either side rejects the open (403). */
+            open: (input: {
+                opener_id: string;
+                participant_ids: string[];
+                kind?: "direct" | "group";
+                subject?: string;
+            }) => Promise<DmConversation>;
+            /** "My inbox": a user's active conversations, newest-activity first, each
+             *  with `muted` + `unread`. */
+            list: (userId: string) => Promise<DmInboxConversation[]>;
+            /** Read a conversation's messages (an authz'd participant only; messages
+             *  from authors the viewer has blocked are filtered out). Keyset cursor. */
+            messages: (conversationId: string, q: {
+                user_id: string;
+                cursor?: string;
+                limit?: number;
+            }) => Promise<{
+                conversation_id: string;
+                messages: DmMessage[];
+                next_cursor: string | null;
+            }>;
+        };
+        /** Send a message (an authz'd participant). Stored as a comment on the
+         *  conversation topic + fanned out over realtime to the unmuted, non-sender
+         *  participants (best-effort; degrades to pull). */
+        sendMessage: (conversationId: string, input: {
+            sender_id: string;
+            body: string;
+        }) => Promise<{
+            message_id: string;
+            conversation_id: string;
+        }>;
+        /** Advance a participant's read-cursor to `message_id` (forward-only — a
+         *  mark-read for an older message is a no-op; the cursor never rewinds). */
+        markRead: (conversationId: string, input: {
+            user_id: string;
+            message_id: string;
+        }) => Promise<{
+            conversation_id: string;
+            advanced: boolean;
+            last_read_message_id: string | null;
+        }>;
+        /** Mute / unmute a participant — suppresses realtime delivery + unread
+         *  badging WITHOUT removing them from the conversation. */
+        mute: (conversationId: string, input: {
+            user_id: string;
+            muted: boolean;
+        }) => Promise<{
+            conversation_id: string;
+            user_id: string;
+            muted: boolean;
+        }>;
+        /** Set / clear a directed user block edge (conversation-independent). Omit
+         *  `blocked_state` (or pass true) to block; false to unblock. Requires the
+         *  tenant's `blockingEnabled` DM config (else 403). */
+        block: (input: {
+            blocker: string;
+            blocked: string;
+            blocked_state?: boolean;
+        }) => Promise<{
+            blocker: string;
+            blocked: string;
+            blocked_state: boolean;
+        }>;
+    };
+    /** The MCP aggregation surface (the `mcp` feature). */
+    readonly mcp: {
+        /** Per-tenant secret for verifying the X-Vxil-Mcp-Signature header on custom
+         *  MCP tool calls (mcp.md §6.5) — the mirror of jobs.signingSecret(). */
+        signingSecret: () => Promise<string>;
+    };
+    /**
+     * Activity streams + in-app notification feeds (the `activity-feed` feature).
+     * Feed refs are addressed as ({group}, {feed_id}); a group's behaviour
+     * (flat / aggregated / notification) is the tenant's config, not an argument.
+     */
+    readonly feeds: {
+        /**
+         * Add one activity (or a batch — all-or-nothing) to a flat feed. Idempotent
+         * upsert on (foreign_id, time); `to:[]` CCs into other feeds; triggers
+         * fan-out + a realtime new-activity event.
+         */
+        addActivity: (group: string, feedId: string, activity: FeedActivityInput | FeedActivityInput[]) => Promise<FeedActivity[]>;
+        /**
+         * Read a feed with a keyset cursor. Flat feeds return `activities`; aggregated
+         * and notification feeds return `groups` (notification also carries the badge).
+         * Pass `markSeen`/`markRead` to acknowledge the returned page on a notification
+         * feed; `notificationState` filters to unseen | unread | all.
+         */
+        read: (group: string, feedId: string, q?: {
+            limit?: number;
+            id_lt?: string;
+            id_gt?: string;
+            notificationState?: "unread" | "unseen" | "all";
+            markSeen?: boolean;
+            markRead?: boolean;
+        }) => Promise<FeedPage>;
+        /** Remove an activity by id (or by foreign_id); tombstones + un-fans-out. */
+        removeActivity: (group: string, feedId: string, ref: {
+            id?: string;
+            foreign_id?: string;
+        }) => Promise<void>;
+        /**
+         * Follow one target (or many in one txn — all-or-nothing under follow.maxFollowing).
+         * Backfills up to `copyLimit` recent activities into this timeline.
+         */
+        follow: (group: string, feedId: string, target: string | string[], opts?: {
+            copyLimit?: number;
+        }) => Promise<{
+            follower: string;
+            followed: string[];
+        }>;
+        /** Unfollow a target; un-fans the source out of this timeline (idempotent). */
+        unfollow: (group: string, feedId: string, target: string) => Promise<void>;
+        /** Who a feed FOLLOWS (`following[]` + `following_count`) plus the true
+         *  `followers_count` (who follows this feed). Keyset cursor via `after`. */
+        listFollows: (group: string, feedId: string, q?: {
+            limit?: number;
+            after?: string;
+        }) => Promise<{
+            following: Array<{
+                target: string;
+                copy_limit: number;
+                created_at: string;
+            }>;
+            following_count: number;
+            followers_count: number;
+            next_after?: string;
+        }>;
+        /**
+         * Block (two-way fan-out suppression, removes existing rows) or mute (one-way
+         * read-side filter) the `blocked` feed for `owner`. Defaults to block.
+         */
+        block: (input: {
+            owner: string;
+            blocked: string;
+            mode?: "block" | "mute";
+        }) => Promise<{
+            owner: string;
+            blocked: string;
+            mode: "block" | "mute";
+        }>;
+        /** Remove a block/mute. */
+        unblock: (owner: string, blocked: string) => Promise<void>;
+        notification: {
+            /**
+             * Mark groups seen. Pass `ids` to scope, `before` for everything older than a
+             * timestamp, or neither to mark all. Recomputes + publishes the badge.
+             */
+            markSeen: (userId: string, scope?: {
+                ids?: string[];
+                before?: string;
+            }) => Promise<FeedBadge>;
+            /** Mark groups read (read implies seen). Same scoping as markSeen. */
+            markRead: (userId: string, scope?: {
+                ids?: string[];
+                before?: string;
+            }) => Promise<FeedBadge>;
+            /** Mark every group for the user read (the "mark all read" affordance). */
+            markAll: (userId: string) => Promise<FeedBadge>;
+            /** Archive/dismiss groups (hidden from inbox + dropped from the badge). */
+            archive: (userId: string, scope?: {
+                ids?: string[];
+                before?: string;
+            }) => Promise<FeedBadge>;
+            /** The badge: { unseen, unread, total } (KV-cached over the authority). */
+            unreadCount: (userId: string) => Promise<FeedBadge>;
+        };
+        /**
+         * Mint realtime connect token(s) for a user, one per requested feed channel.
+         * Open wss://api…{connect_path} per token in the browser.
+         */
+        realtimeToken: (input: {
+            user_id: string;
+            feeds: string[];
+            ttl_seconds?: number;
+        }) => Promise<{
+            user_id: string;
+            tokens: FeedRealtimeToken[];
+        }>;
+        /** Read a user's notification preference policy. */
+        getPreferences: (userId: string) => Promise<FeedPreferences>;
+        /** Write a user's notification preference policy. */
+        setPreferences: (userId: string, policy: {
+            channels?: Record<string, boolean>;
+            categories?: Record<string, boolean>;
+            verbs?: Record<string, boolean>;
+            mute_until?: string;
+        }) => Promise<FeedPreferences>;
+    };
+    /** Alias for `feeds` — the `activity-feed` feature namespace. */
+    readonly activityFeed: {
+        /**
+         * Add one activity (or a batch — all-or-nothing) to a flat feed. Idempotent
+         * upsert on (foreign_id, time); `to:[]` CCs into other feeds; triggers
+         * fan-out + a realtime new-activity event.
+         */
+        addActivity: (group: string, feedId: string, activity: FeedActivityInput | FeedActivityInput[]) => Promise<FeedActivity[]>;
+        /**
+         * Read a feed with a keyset cursor. Flat feeds return `activities`; aggregated
+         * and notification feeds return `groups` (notification also carries the badge).
+         * Pass `markSeen`/`markRead` to acknowledge the returned page on a notification
+         * feed; `notificationState` filters to unseen | unread | all.
+         */
+        read: (group: string, feedId: string, q?: {
+            limit?: number;
+            id_lt?: string;
+            id_gt?: string;
+            notificationState?: "unread" | "unseen" | "all";
+            markSeen?: boolean;
+            markRead?: boolean;
+        }) => Promise<FeedPage>;
+        /** Remove an activity by id (or by foreign_id); tombstones + un-fans-out. */
+        removeActivity: (group: string, feedId: string, ref: {
+            id?: string;
+            foreign_id?: string;
+        }) => Promise<void>;
+        /**
+         * Follow one target (or many in one txn — all-or-nothing under follow.maxFollowing).
+         * Backfills up to `copyLimit` recent activities into this timeline.
+         */
+        follow: (group: string, feedId: string, target: string | string[], opts?: {
+            copyLimit?: number;
+        }) => Promise<{
+            follower: string;
+            followed: string[];
+        }>;
+        /** Unfollow a target; un-fans the source out of this timeline (idempotent). */
+        unfollow: (group: string, feedId: string, target: string) => Promise<void>;
+        /** Who a feed FOLLOWS (`following[]` + `following_count`) plus the true
+         *  `followers_count` (who follows this feed). Keyset cursor via `after`. */
+        listFollows: (group: string, feedId: string, q?: {
+            limit?: number;
+            after?: string;
+        }) => Promise<{
+            following: Array<{
+                target: string;
+                copy_limit: number;
+                created_at: string;
+            }>;
+            following_count: number;
+            followers_count: number;
+            next_after?: string;
+        }>;
+        /**
+         * Block (two-way fan-out suppression, removes existing rows) or mute (one-way
+         * read-side filter) the `blocked` feed for `owner`. Defaults to block.
+         */
+        block: (input: {
+            owner: string;
+            blocked: string;
+            mode?: "block" | "mute";
+        }) => Promise<{
+            owner: string;
+            blocked: string;
+            mode: "block" | "mute";
+        }>;
+        /** Remove a block/mute. */
+        unblock: (owner: string, blocked: string) => Promise<void>;
+        notification: {
+            /**
+             * Mark groups seen. Pass `ids` to scope, `before` for everything older than a
+             * timestamp, or neither to mark all. Recomputes + publishes the badge.
+             */
+            markSeen: (userId: string, scope?: {
+                ids?: string[];
+                before?: string;
+            }) => Promise<FeedBadge>;
+            /** Mark groups read (read implies seen). Same scoping as markSeen. */
+            markRead: (userId: string, scope?: {
+                ids?: string[];
+                before?: string;
+            }) => Promise<FeedBadge>;
+            /** Mark every group for the user read (the "mark all read" affordance). */
+            markAll: (userId: string) => Promise<FeedBadge>;
+            /** Archive/dismiss groups (hidden from inbox + dropped from the badge). */
+            archive: (userId: string, scope?: {
+                ids?: string[];
+                before?: string;
+            }) => Promise<FeedBadge>;
+            /** The badge: { unseen, unread, total } (KV-cached over the authority). */
+            unreadCount: (userId: string) => Promise<FeedBadge>;
+        };
+        /**
+         * Mint realtime connect token(s) for a user, one per requested feed channel.
+         * Open wss://api…{connect_path} per token in the browser.
+         */
+        realtimeToken: (input: {
+            user_id: string;
+            feeds: string[];
+            ttl_seconds?: number;
+        }) => Promise<{
+            user_id: string;
+            tokens: FeedRealtimeToken[];
+        }>;
+        /** Read a user's notification preference policy. */
+        getPreferences: (userId: string) => Promise<FeedPreferences>;
+        /** Write a user's notification preference policy. */
+        setPreferences: (userId: string, policy: {
+            channels?: Record<string, boolean>;
+            categories?: Record<string, boolean>;
+            verbs?: Record<string, boolean>;
+            mute_until?: string;
+        }) => Promise<FeedPreferences>;
+    };
+    /** Shared executor for the seen/read/archive notification-state endpoints. */
+    private feedsMark;
+    readonly webhooks: {
+        /**
+         * Subscribe an https endpoint to audit-stream events (optionally
+         * filtered by event-name prefixes like 'user.'). Deliveries are jobs
+         * callbacks: verify X-Vxil-Jobs-Signature with jobs.signingSecret().
+         */
+        subscribe: (input: {
+            target_url: string;
+            event_prefixes?: string[];
+        }) => Promise<{
+            sub_id: string;
+            target_url: string;
+            event_prefixes: string[];
+            state: string;
+        }>;
+        list: () => Promise<Array<{
+            sub_id: string;
+            target_url: string;
+            event_prefixes: string[];
+            state: string;
+        }>>;
+        unsubscribe: (subId: string) => Promise<void>;
+        /**
+         * Send a synthetic 'webhooks.test' event to the subscription's endpoint
+         * through the REAL signing+delivery pipeline and wait inline (≤ ~8 s).
+         * Terminal → { delivered, state, last_error_* }; still in flight → the
+         * 202 pending shape { sub_id, run_id, state } (poll jobs.run(run_id)).
+         */
+        test: (subId: string) => Promise<{
+            sub_id: string;
+            run_id: string;
+            state: string;
+            delivered: boolean;
+            last_error_class?: string | null;
+            last_error_msg?: string | null;
+        }>;
+        sources: {
+            /** Register an inbound source; the receiver URL is returned ONCE. */
+            create: (input: {
+                provider: "stripe" | "paddle" | "github" | "slack" | "revenuecat" | "generic";
+                name: string;
+                forward_url?: string;
+            }) => Promise<{
+                source_id: string;
+                receiver_url_path: string;
+                provider: string;
+            }>;
+            list: () => Promise<Array<{
+                source_id: string;
+                provider: string;
+                name: string;
+            }>>;
+            delete: (sourceId: string) => Promise<void>;
+            /** Send a sample envelope to the source's forward_url through the real
+             * delivery path (inline result; 202 pending shape when still in flight). */
+            test: (sourceId: string) => Promise<{
+                source_id: string;
+                run_id: string;
+                state: string;
+                delivered: boolean;
+                last_error_class?: string | null;
+                last_error_msg?: string | null;
+            }>;
+        };
+        events: {
+            list: (q?: {
+                source_id?: string;
+                status?: string;
+                cursor?: string;
+                limit?: number;
+            }) => Promise<{
+                events: Array<{
+                    event_id: string;
+                    event_type: string | null;
+                    payload: Record<string, unknown>;
+                    sig_verified: boolean;
+                    status: string;
+                }>;
+                next_cursor: string | null;
+            }>;
+            replay: (eventId: string) => Promise<void>;
+            /** The Svix message-attempt view: delivery state/attempts/DLQ flag for
+             * every jobs run this event's forwards created. */
+            runs: (eventId: string) => Promise<{
+                event_id: string;
+                status: string;
+                runs: Array<{
+                    run_id: string;
+                    state: string;
+                    attempt_number?: number;
+                    max_attempts?: number | null;
+                    last_error_class?: string | null;
+                    last_error_msg?: string | null;
+                    queued_at?: string | null;
+                    completed_at?: string | null;
+                    dead_lettered: boolean;
+                }>;
+            }>;
+        };
+    };
+    readonly orgs: {
+        create: (input: {
+            slug: string;
+            name: string;
+            owner_user_id: string;
+        }) => Promise<{
+            org_id: string;
+            slug: string;
+            name: string;
+        }>;
+        list: (q?: {
+            user_id?: string;
+        }) => Promise<Array<{
+            org_id: string;
+            slug: string;
+            name: string;
+            role?: string;
+        }>>;
+        delete: (orgId: string) => Promise<void>;
+        /** RBAC: org:read (viewer+), org:write (member+), members:manage (admin+),
+         *  org:admin (owner) — plus any custom-role permission-set. Pass
+         *  `opts.resource` to additionally consult per-resource ACL grants; the
+         *  response `source` marks whether a grant came from the role lattice or an ACL. */
+        check: (orgId: string, userId: string, permission: string, opts?: {
+            resource?: string;
+        }) => Promise<{
+            allowed: boolean;
+            role: string | null;
+            source?: string;
+        }>;
+        /** The active-org snapshot auth embeds in session JWTs when the tenant
+         *  enables auth config `orgClaims` (most-recent membership by joined_at).
+         *  EVENTUAL-CONSISTENT for JWTs (recomputed at refresh); use `check` for
+         *  revocation-grade authz. No membership → org_id null. */
+        sessionClaims: (userId: string) => Promise<{
+            user_id: string;
+            org_id: string | null;
+            role: string | null;
+            perms: string[];
+        }>;
+        /** Read one workspace (incl. `settings`). */
+        get: (orgId: string) => Promise<{
+            org_id: string;
+            slug: string;
+            name: string;
+            created_at?: string;
+            settings?: Record<string, unknown>;
+            role?: string | null;
+        }>;
+        /** Update a workspace's name / `settings` jsonb. */
+        update: (orgId: string, patch: {
+            name?: string;
+            settings?: Record<string, unknown>;
+        }) => Promise<{
+            org_id: string;
+            slug: string;
+            name: string;
+            settings?: Record<string, unknown>;
+        }>;
+        members: {
+            add: (orgId: string, userId: string, role: "owner" | "admin" | "member" | "viewer") => Promise<void>;
+            list: (orgId: string) => Promise<Array<{
+                user_id: string;
+                role: string;
+            }>>;
+            remove: (orgId: string, userId: string) => Promise<void>;
+        };
+        invitations: {
+            /** invite_token is returned ONCE — your app builds the accept URL. */
+            create: (orgId: string, email: string, role: "admin" | "member" | "viewer") => Promise<{
+                invite_id: string;
+                invite_token: string;
+            }>;
+            accept: (token: string, userId: string) => Promise<{
+                org_id: string;
+                role: string;
+            }>;
+            revoke: (inviteId: string) => Promise<void>;
+            /** List an org's pending invitations. */
+            list: (orgId: string) => Promise<Array<{
+                invite_id: string;
+                org_id?: string;
+                email: string | null;
+                role: string;
+                created_at?: string;
+                expires_at?: string;
+                accepted_at?: string | null;
+                revoked_at?: string | null;
+                pending?: boolean;
+            }>>;
+        };
+        /** Custom tenant roles (permission-sets; migration orgs/0019). A custom role
+         *  is a named set of permissions assignable like any built-in; the four
+         *  built-ins reproduce the fixed owner>admin>member>viewer lattice. */
+        roles: {
+            /** Define (or upsert) a custom role. `role_key` must not collide with a built-in. */
+            define: (input: {
+                role_key: string;
+                name: string;
+                permissions: string[];
+                rank?: number;
+            }) => Promise<{
+                role_key: string;
+                name: string;
+                permissions: string[];
+                rank: number | null;
+            }>;
+            /** The tenant role catalog: `builtin` (the fixed lattice) + `custom`. */
+            list: () => Promise<{
+                builtin: Array<{
+                    role_key: string;
+                    name: string;
+                    permissions: string[];
+                    builtin?: boolean;
+                }>;
+                custom: Array<{
+                    role_key: string;
+                    name: string;
+                    permissions: string[];
+                    rank: number | null;
+                }>;
+            }>;
+            /** Delete a custom role (built-in roles cannot be deleted). */
+            delete: (roleKey: string) => Promise<void>;
+        };
+        /** Per-org/user resource ACL grants (migration orgs/0019): grant a permission
+         *  on a specific resource string; `check(...,{ resource })` consults them. */
+        acl: {
+            grant: (orgId: string, input: {
+                user_id: string;
+                resource: string;
+                permission: string;
+            }) => Promise<{
+                org_id: string;
+                user_id: string;
+                resource: string;
+                permission: string;
+                granted: boolean;
+            }>;
+            /** List an org's resource ACL grants (optionally scoped to one user). */
+            list: (orgId: string, q?: {
+                user_id?: string;
+            }) => Promise<Array<{
+                user_id: string;
+                resource: string;
+                permission: string;
+                created_at?: string;
+            }>>;
+            /** Revoke a resource ACL grant. */
+            revoke: (orgId: string, input: {
+                user_id: string;
+                resource: string;
+                permission: string;
+            }) => Promise<void>;
+        };
+    };
+    readonly realtime: {
+        /** Server-side: mint a connect token for an end-user; the browser opens
+         * wss://api…/v1/realtime/connect?token=… with it. */
+        mintToken: (input: {
+            channel: string;
+            user_id: string;
+            ttl_seconds?: number;
+        }) => Promise<{
+            token: string;
+            connect_path: string;
+            expires_at: string;
+        }>;
+        publish: (channel: string, event: string, data?: unknown) => Promise<number>;
+        /** Needs the presence feature enabled. */
+        presence: (channel: string) => Promise<{
+            users: Array<{
+                user_id: string;
+                connections: number;
+            }>;
+            total_connections: number;
+        }>;
+        /** Glue for the `@vxil/realtime` reconnecting client: returns a function
+         * matching its TokenProvider type *structurally* (no import — a static
+         * import would break the single-file served sdk.mjs) that re-mints via
+         * POST /v1/realtime/tokens with `defaults` merged over the channel the
+         * client asks for. Server-side (Node) use only — it needs the API key;
+         * browsers must fetch tokens from YOUR backend instead. */
+        tokenProvider: (defaults: {
+            user_id: string;
+            ttl_seconds?: number;
+        }) => (ctx: {
+            channel: string;
+        }) => Promise<{
+            token: string;
+            connect_path: string;
+            expires_at: string;
+        }>;
+        /** One-shot: mint a token AND open the WebSocket. Uses the global
+         * `WebSocket` (browser / Node ≥22). On older Node, pass a constructor —
+         * `import WebSocket from 'ws'; await vxil.realtime.connect(opts, { WebSocket })`
+         * — instead of failing with a silent `WebSocket is not defined`. For
+         * auto-reconnect / token refresh / presence helpers use `@vxil/realtime`
+         * with `vxil.realtime.tokenProvider(...)` instead. */
+        connect: (input: {
+            channel: string;
+            user_id: string;
+            ttl_seconds?: number;
+        }, opts?: {
+            WebSocket?: unknown;
+        }) => Promise<WebSocket>;
+    };
+    readonly files: {
+        /** Mint a presigned PUT; upload the bytes yourself, then call complete(). */
+        createUploadUrl: (input: {
+            user_id: string;
+            filename: string;
+            content_type: string;
+            size_bytes: number;
+        }) => Promise<{
+            object_id: string;
+            upload_url: string;
+            upload_method: string;
+            expires_at: string;
+        }>;
+        complete: (objectId: string) => Promise<{
+            object_id: string;
+            status: string;
+        }>;
+        downloadUrl: (objectId: string) => Promise<string>;
+        list: (q?: {
+            user_id?: string;
+            cursor?: string;
+            limit?: number;
+        }) => Promise<{
+            files: FileObject[];
+            next_cursor: string | null;
+        }>;
+        /** Soft delete; bytes are hard-deleted 30 days later. */
+        delete: (objectId: string) => Promise<void>;
+        /** Aggregate storage usage vs quotas (the FilesManager Storage panel). */
+        usage: () => Promise<{
+            usage: {
+                object_count: number;
+                total_bytes: number;
+            };
+            quotas: {
+                maxObjectCount?: number;
+                maxObjectBytes?: number;
+                maxTotalBytes?: number;
+            };
+            available: Record<string, number | null>;
+        }>;
+        /** OCR / text extraction (files.md §1.1, BYO-key add-on). Small/mock inputs
+         *  extract inline (status `available`); large inputs (or `async:true`) return
+         *  202 with a `job_id` — poll `getText()`. */
+        extractText: (objectId: string, opts?: {
+            langs?: string[];
+            boundingBoxes?: boolean;
+            async?: boolean;
+        }) => Promise<{
+            object_id: string;
+            text?: string;
+            blocks?: OcrBlock[] | null;
+            provider?: string;
+            job_id?: string;
+            status?: string;
+            extracted_at?: string;
+        }>;
+        /** Fetch the cached extraction (status: not_extracted|pending|available|failed). */
+        getText: (objectId: string) => Promise<{
+            object_id: string;
+            status: string;
+            text: string | null;
+            blocks?: OcrBlock[] | null;
+            provider?: string | null;
+            extracted_at: string | null;
+            error?: string | null;
+        }>;
+        /** Set / extend / clear an object's TTL. `expiresInSeconds: null` clears it
+         *  (else a future auto-delete after the given seconds; minimum 60). */
+        setTtl: (objectId: string, expiresInSeconds: number | null) => Promise<{
+            object_id: string;
+            expires_at: string | null;
+        }>;
+        sharedLinks: {
+            /** Public (unauthenticated) URL for the object; revocable. */
+            create: (objectId: string, opts?: {
+                ttl_seconds?: number;
+            }) => Promise<{
+                link_id: string;
+                url: string;
+                expires_at: string | null;
+            }>;
+            /** List an object's active (unrevoked, unexpired) shared links. */
+            list: (objectId: string) => Promise<Array<{
+                link_id: string;
+                created_at: string;
+                expires_at: string | null;
+            }>>;
+            revoke: (linkId: string) => Promise<void>;
+        };
+    };
+    /**
+     * Managed hybrid search (the `vector-search` feature): store documents → chunk →
+     * embed → index, then retrieve top-k via hybrid (BM25 ∪ vector, RRF-fused),
+     * vector, or keyword. The embedder is config: 'mock' (deterministic default),
+     * 'byov' (you supply vectors), or a BYO-key provider (openai/cohere).
+     */
+    readonly search: {
+        /** Define a collection. `dimensions` (and an `embed` override) pin its vector
+         *  width — one of 256|384|512|768|1024|1536|3072 (3072 = halfvec, sized for
+         *  OpenAI text-embedding-3-large); immutable after creation. */
+        createCollection: (input: {
+            collection: string;
+            dimensions?: number;
+            embed?: {
+                provider?: "byov" | "mock" | "openai" | "cohere";
+                model?: string;
+                apiKeyRef?: string;
+                dimensions?: number;
+            };
+        }) => Promise<SearchCollection>;
+        /** List the tenant's collections (with per-collection document counts). */
+        listCollections: () => Promise<Array<{
+            collection: string;
+            dimensions: number;
+            backend: string;
+            provider?: string;
+            documents?: number;
+            created_at?: string;
+        }>>;
+        /** Ingest a document: chunk → embed → index (202). BYOV skips embedding. */
+        ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
+        /** List indexed documents (keyset cursor, optional `user_id` filter). */
+        listDocuments: (collection: string, q?: {
+            user_id?: string;
+            cursor?: string;
+            limit?: number;
+        }) => Promise<{
+            documents: SearchDocument[];
+            next_cursor: string | null;
+        }>;
+        /** De-index a document (+ invalidate the query cache). */
+        deleteDocument: (collection: string, docId: string) => Promise<void>;
+        /** Retrieve top-k. `mode` defaults to the collection's hybrid config; pass
+         *  `vector` to run a BYOV query (skips the embedder). `rerank` opts a single
+         *  request in/out of the configured BYO reranker (config `rerank` block;
+         *  fail-open — a provider fault returns the RRF order with reranked:false). */
+        query: (collection: string, input: {
+            query: string;
+            top_k?: number;
+            mode?: "hybrid" | "vector" | "keyword";
+            filter?: Record<string, unknown>;
+            rrf_k?: number;
+            vector?: number[];
+            rerank?: boolean;
+        }) => Promise<SearchQueryResult>;
+        /** Embedding-token + query + rerank counts since a timestamp (default 30 days). */
+        usage: (q?: {
+            since?: string;
+        }) => Promise<SearchUsage>;
+        /** List the configured cms auto-sync sources with their cursor state. */
+        syncSources: () => Promise<SearchSyncSource[]>;
+        /** Run one budgeted sync tick inline (409 when a tick is already running).
+         *  `sweep: true` runs the hard-delete reconcile leg instead. */
+        syncRun: (sourceKey: string, opts?: {
+            sweep?: boolean;
+        }) => Promise<{
+            source_key: string;
+            phase: string;
+            processed: number;
+            deleted: number;
+            skipped_unchanged: number;
+            swept: boolean;
+            cursor_updated_at: string | null;
+        }>;
+        /** Reset a source to a fresh backfill; `purge: true` also hard-deletes every
+         *  synced document (chunks + cache invalidation). */
+        syncReset: (sourceKey: string, opts?: {
+            purge?: boolean;
+        }) => Promise<{
+            source_key: string;
+            phase: string;
+            purged: number;
+        }>;
+    };
+    /**
+     * The AI substrate (the `ai` feature): store prompt TEMPLATES (config-as-code),
+     * then generate (sync or streamed) and embed across providers. 'mock' is the
+     * deterministic default; the real providers (openai/anthropic/gemini/azure/
+     * openrouter) route via BYO keys in tenant_secrets. `images` on the generate
+     * inputs takes up to 8 vision refs: a public https:// URL, a
+     * data:image/...;base64 URL, or file:<object_id> (a files-feature object) —
+     * fetched images are capped at 4 MiB each / 16 MiB total.
+     */
+    readonly ai: {
+        templates: {
+            /** Store a tenant-authored prompt template; versions are monotonic per name.
+             *  `{{var}}` placeholders are filled from `generate`'s `input`. */
+            put: (input: {
+                template: string;
+                user: string;
+                system?: string;
+                schema?: Record<string, unknown>;
+            }) => Promise<{
+                template: string;
+                version: number;
+            }>;
+            /** List stored templates (each name + its latest version). */
+            list: () => Promise<Array<{
+                name: string;
+                latest_version: number;
+                created_at: string;
+            }>>;
+        };
+        /** Provider × capability matrix + the tenant's default provider (the set an
+         *  agent/dashboard reads to know which providers/features are configured). */
+        capabilities: () => Promise<{
+            default_provider: string;
+            providers: Record<string, unknown>;
+        }>;
+        /** Synchronous generation: pass `template` (+ `input` vars) or a raw `prompt`. */
+        generate: (input: {
+            template?: string;
+            template_version?: number;
+            input?: Record<string, unknown>;
+            prompt?: string;
+            provider?: string;
+            model?: string;
+            max_tokens?: number;
+            temperature?: number;
+            tools?: Array<{
+                name: string;
+                description?: string;
+                parameters?: Record<string, unknown>;
+            }>;
+            /** prior turns for the tool-calling round-trip (assistant tool_calls +
+             *  role:'tool' results) — vxil relays; you execute the tools. */
+            messages?: AiChatMessage[];
+            json_mode?: boolean;
+            images?: string[];
+            user_id?: string;
+        }) => Promise<AiGeneration>;
+        /** Streamed generation: returns the channel + connect token immediately; open
+         *  the realtime channel for AiStreamFrame frames (token/title, then a
+         *  terminal usage frame). `title:true` (or `title_template`) emits an early
+         *  seq'd title frame billed into the same generation. Long streams also get
+         *  live-only `token_expiring` events — see AiTokenExpiringEvent. */
+        stream: (input: {
+            template?: string;
+            template_version?: number;
+            input?: Record<string, unknown>;
+            prompt?: string;
+            provider?: string;
+            model?: string;
+            max_tokens?: number;
+            temperature?: number;
+            tools?: Array<{
+                name: string;
+                description?: string;
+                parameters?: Record<string, unknown>;
+            }>;
+            messages?: AiChatMessage[];
+            json_mode?: boolean;
+            images?: string[];
+            /** emit an early 'title' frame (stream-only; built-in instruction). */
+            title?: boolean;
+            /** name of a stored ai template authoring the title prompt (rendered with
+             *  {{prompt}}); overrides the built-in instruction (stream-only). */
+            title_template?: string;
+            user_id?: string;
+        }) => Promise<AiStreamHandle>;
+        /** Job-routed async generation (long/vision/batch): 202 + a jobs run drives
+         *  the provider call; the settled answer lands in the replay buffer at
+         *  `resume_path`. Reserve/settle + credit reversal-on-failure ride the run. */
+        generateAsync: (input: {
+            template?: string;
+            template_version?: number;
+            input?: Record<string, unknown>;
+            prompt?: string;
+            provider?: string;
+            model?: string;
+            max_tokens?: number;
+            temperature?: number;
+            tools?: Array<{
+                name: string;
+                description?: string;
+                parameters?: Record<string, unknown>;
+            }>;
+            messages?: AiChatMessage[];
+            json_mode?: boolean;
+            images?: string[];
+            user_id?: string;
+        }) => Promise<AiJobHandle>;
+        /** Re-mint a fresh connect token for a LIVE stream (a generation that
+         *  outlives the ≤300s realtime token TTL); reconnect with `?since=<seq>`. */
+        remintToken: (generationId: string) => Promise<AiStreamToken>;
+        /** Resume a streamed generation after a dropped socket: every recorded frame
+         *  with seq > `since` plus `done` (the §2a replay buffer — plain JSON, not
+         *  an SSE stream). The rag-native mirror is `rag.resume()`. */
+        resume: (generationId: string, q?: {
+            since?: number;
+        }) => Promise<{
+            generation_id: string;
+            since: number;
+            frames: Array<Record<string, unknown>>;
+            done: boolean;
+            max_seq: number;
+        }>;
+        /** Embed a batch of strings (1–256). */
+        embed: (input: {
+            input: string[];
+            provider?: string;
+            model?: string;
+            user_id?: string;
+        }) => Promise<AiEmbedResult>;
+        /** Per-user token rollups (optionally scoped by `since`/`user_id`). */
+        usage: (q?: {
+            since?: string;
+            user_id?: string;
+            limit?: number;
+        }) => Promise<AiUsageReport>;
+    };
+    /**
+     * Grounded composition (the `rag` feature): retrieve → budget → generate → cite, as
+     * one endpoint. It composes `search` (retrieval) and `ai` (generation); it owns
+     * no datastore. `collection`/`template` fall back to the rag config defaults.
+     */
+    readonly rag: {
+        /** Synchronous grounded answer (full text + citations + usage). */
+        answer: (input: {
+            query: string;
+            collection?: string;
+            template?: string;
+            top_k?: number;
+            filter?: Record<string, unknown>;
+            mode?: "hybrid" | "vector" | "keyword";
+            provider?: string;
+            model?: string;
+            user_id?: string;
+            input?: Record<string, unknown>;
+        }) => Promise<RagAnswer>;
+        /** Streamed grounded answer: citations + the channel handle up front, tokens
+         *  over the realtime channel. */
+        stream: (input: {
+            query: string;
+            collection?: string;
+            template?: string;
+            top_k?: number;
+            filter?: Record<string, unknown>;
+            mode?: "hybrid" | "vector" | "keyword";
+            provider?: string;
+            model?: string;
+            user_id?: string;
+            input?: Record<string, unknown>;
+        }) => Promise<RagStreamHandle>;
+        /** Retrieval-only grounding preview (rag.md §1c): the exact chunks `answer`
+         *  would ground on, with rerank + metadata boosts applied — no generation,
+         *  no token spend. `boosts`/`rerank`/`min_score` override the rag config. */
+        search: (input: {
+            query: string;
+            collection?: string;
+            top_k?: number;
+            filter?: Record<string, unknown>;
+            mode?: "hybrid" | "vector" | "keyword";
+            rerank?: boolean;
+            boosts?: Record<string, unknown>;
+            min_score?: number;
+        }) => Promise<RagSearchResult>;
+        /** Ingest into the backing vector-search collection (chunk → embed → index). */
+        ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
+        /** Resume a streamed answer after a dropped socket: every recorded frame
+         *  with seq > `since` plus `done` — the RAG-native proxy of the ai replay
+         *  buffer, so a rag-scoped key suffices. */
+        resume: (generationId: string, q?: {
+            since?: number;
+        }) => Promise<RagResumePage>;
+        /** Aggregated retrieval (vector-search) + generation (ai) usage. */
+        usage: (q?: {
+            since?: string;
+        }) => Promise<RagUsage>;
+    };
+    /**
+     * Copilot — embeddable AI agents (the `copilot` feature). A thin COMPOSITION over
+     * ai + vector-search + rag + mcp: each agent is CONFIG (persona + knowledge +
+     * a curated action allowlist + guardrails). A turn retrieves, grounds, and
+     * generates a cited answer; a WRITE action is PROPOSED, never auto-run — you
+     * `confirm` it, and only then does the real internal route execute (with the
+     * caller's own scopes, so nothing widens). The `mock` ai provider is the
+     * zero-config default — the whole loop is exercisable without provider keys.
+     */
+    readonly copilot: {
+        /** Conversations: open / list / read a chat session pinned to one agent. */
+        conversations: {
+            /** Open a session for `agentId` (agents are config; an unknown id 404s).
+             *  Omit `user_id` for a guest conversation. */
+            create: (agentId: string, input?: {
+                user_id?: string;
+                title?: string;
+            }) => Promise<CopilotConversation>;
+            /** List an agent's conversations, newest-updated first (optionally scoped
+             *  to one end user). */
+            list: (agentId: string, q?: {
+                user_id?: string;
+                limit?: number;
+            }) => Promise<{
+                conversations: CopilotConversation[];
+            }>;
+            /** A conversation row + the last N transcript messages (oldest-first). */
+            get: (conversationId: string, q?: {
+                limit?: number;
+            }) => Promise<{
+                conversation: CopilotConversation;
+                messages: CopilotMessage[];
+            }>;
+        };
+        /** Send a message — the agentic turn (retrieve → generate → tool_calls →
+         *  propose). Returns the synchronous `answer` + citations (+ a `proposal`
+         *  when the agent wants a write) AND the streaming handle. `conversation_id`
+         *  continues an existing session; omit it to open a new one. */
+        send: (agentId: string, input: {
+            message: string;
+            conversation_id?: string;
+            user_id?: string;
+            title?: string;
+        }) => Promise<CopilotTurn>;
+        /** Resume a turn's streamed frames after a dropped socket: every recorded
+         *  frame with seq > `since` plus `done` — replays without re-running (or
+         *  re-billing) the turn. Defaults to the conversation's latest turn. */
+        resume: (conversationId: string, q?: {
+            since?: number;
+            message_id?: string;
+        }) => Promise<CopilotStreamPage>;
+        /** Confirm a proposed action — the ONLY way a write executes. The client
+         *  sends just the path ids; everything that runs comes from the persisted
+         *  proposal. Idempotent: pass an Idempotency-Key to make a racing/retried
+         *  double-confirm a downstream no-op (defaults to the proposal message_id
+         *  server-side). Replaying returns `already:true`. */
+        confirm: (conversationId: string, messageId: string, opts?: {
+            idempotencyKey?: string;
+        }) => Promise<CopilotConfirmResult>;
+        /** Per-user token rollup across assistant turns. */
+        usage: (q?: {
+            since?: string;
+            user_id?: string;
+            limit?: number;
+        }) => Promise<CopilotUsage>;
+    };
+    /**
+     * Payments + the credits & entitlements LEDGER (the `payments` feature). vxil owns
+     * the MECHANISM (a balance, a tier flag, an idempotent debit, a grant cron, a
+     * product→credit translation, an at-most-once reversal); you own the POLICY
+     * (pricing/packaging, what a "scan" costs, when to consume). The `mock` provider
+     * is the zero-config default — the WHOLE ledger path (subscribe → entitlements →
+     * consume → grant → reverse) is exercisable without real provider keys.
+     */
+    readonly payments: {
+        /** Provider + ledger capability surface (+ the `missing` set an agent can act
+         *  on to recommend a provider). */
+        capabilities: () => Promise<{
+            provider: string;
+            capabilities: string[];
+            ledger_capabilities: string[];
+            missing: string[];
+        }>;
+        /** The user's effective entitlement snapshot (the multi-sub tier fold):
+         *  tier + boolean entitlements + numeric quotas. */
+        getEntitlements: (userId: string) => Promise<{
+            user_id: string;
+            tier: string;
+            entitlements: string[];
+            quotas: Record<string, number>;
+        }>;
+        /** Boolean gate: does the user hold `entitlement`? Returns granted + its
+         *  source (subscription/tier) + the resolved tier. */
+        hasEntitlement: (userId: string, entitlement: string) => Promise<{
+            granted: boolean;
+            source: string | null;
+            tier: string;
+        }>;
+        /** A single numeric quota for the user (e.g. `seats`, `api_calls`); null when
+         *  the resolved tier declares no such quota. Convenience over getEntitlements. */
+        getQuota: (userId: string, quota: string) => Promise<number | null>;
+        /** The credit balance for a credit type: balance/held/available (= balance −
+         *  held) + the current period_end. */
+        getBalance: (userId: string, creditType: string) => Promise<{
+            credit_type: string;
+            balance: number;
+            held: number;
+            available: number;
+            period_end: string | null;
+        }>;
+        /**
+         * Debit credits — idempotent (Idempotency-Key REQUIRED) + balance-guarded
+         * (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
+         * committed): a linked jobs run that terminally fails auto-refunds the hold,
+         * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
+         * available balance can't cover `amount`.
+         */
+        consume: (input: {
+            user_id: string;
+            credit_type: string;
+            amount: number;
+            /** link this debit to a jobs run_id → provisional hold + auto-reverse. */
+            job_id?: string;
+            reason?: string;
+        }, opts: {
+            idempotencyKey: string;
+        }) => Promise<{
+            balance_after: number;
+            ledger_entry_id: string | null;
+            reversed: boolean;
+        }>;
+        /** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
+         *  only ADDS; `amount` must be ≥ 1. */
+        grant: (input: {
+            user_id: string;
+            credit_type: string;
+            amount: number;
+            period?: string;
+            source?: string;
+        }, opts: {
+            idempotencyKey: string;
+        }) => Promise<{
+            balance_after: number;
+            ledger_entry_id: string | null;
+        }>;
+        /** One-time grant idempotent on `grant_key` (at-most-once across ALL flows,
+         *  not just retries). A repeat with the same key → granted:false. */
+        grantOnce: (input: {
+            user_id: string;
+            credit_type: string;
+            amount: number;
+            grant_key: string;
+        }) => Promise<{
+            balance_after: number;
+            granted: boolean;
+        }>;
+        /** Recent ledger rows for the user (the audit/trail surface), newest first;
+         *  optionally scoped to one credit type. */
+        usage: (q: {
+            user_id: string;
+            credit_type?: string;
+            limit?: number;
+        }) => Promise<{
+            user_id: string;
+            entries: Array<{
+                ledger_entry_id: string;
+                credit_type: string;
+                delta: number;
+                kind: string;
+                state: string;
+                outcome: string;
+                balance_after: number | null;
+                source: string | null;
+                job_id: string | null;
+                created_at: string;
+            }>;
+        }>;
+        /** Start a subscription (mock = instant checkout; real providers redirect via
+         *  their own flow). `tier` keys the tierMap fold; `price_ref` is your catalog
+         *  ref. Returns the vxil subscription_id + provider sub id + status. */
+        subscribe: (input: {
+            user_id: string;
+            price_ref: string;
+            tier?: string;
+            trial_days?: number;
+        }) => Promise<{
+            subscription_id: string;
+            provider_sub_id: string;
+            status: string;
+            tier: string;
+        }>;
+        /** Cancel a subscription. `atPeriodEnd` true keeps entitlements until the
+         *  period closes; false revokes immediately and re-folds entitlements. */
+        cancel: (subscriptionId: string, opts?: {
+            atPeriodEnd?: boolean;
+        }) => Promise<{
+            subscription_id: string;
+            status: string;
+            cancel_at: string | null;
+        }>;
+        /** List subscriptions (the cancel enabler — discover the subscription_id);
+         *  optionally scoped to one user / status. */
+        listSubscriptions: (q?: {
+            user_id?: string;
+            status?: string;
+        }) => Promise<Array<Record<string, unknown>>>;
+        /**
+         * Create a hosted-checkout session (payments.md §3). Redirect the buyer to
+         * the returned `url`; completion lands server-side via the provider webhook
+         * (the matching session flips to completed, the charge/grant is folded).
+         * Idempotency-Key REQUIRED — a retry replays the SAME session verbatim.
+         */
+        createCheckoutSession: (input: {
+            user_id: string;
+            line_items: Array<{
+                price_ref: string;
+                quantity?: number;
+                /** amount-based providers (PayPal payment mode) need amount_cents. */
+                amount_cents?: number;
+                currency?: string;
+            }>;
+            mode: "subscription" | "payment";
+            success_url: string;
+            cancel_url: string;
+        }, opts: {
+            idempotencyKey: string;
+        }) => Promise<{
+            checkout_session_id: string;
+            url: string;
+        }>;
+        /**
+         * Refund a charge at-most-once (payments.md §6a). Omit `amount_cents` to
+         * refund the full un-refunded remainder. Idempotency-Key REQUIRED — a retry
+         * replays the recorded refund (never a second provider refund); a refund can
+         * NEVER exceed the charge (422 refund_exceeds_charge).
+         */
+        createRefund: (input: {
+            charge_id: string;
+            amount_cents?: number;
+            reason?: string;
+        }, opts: {
+            idempotencyKey: string;
+        }) => Promise<{
+            refund_id: string;
+            status: "pending" | "succeeded" | "failed";
+            amount_cents: number;
+        }>;
+        /** The provider-hosted billing-management portal URL for an end user (Stripe
+         *  billing portal; mock is deterministic; RC/Paddle/PayPal → 501). */
+        getCustomerPortalUrl: (userId: string) => Promise<{
+            url: string;
+        }>;
+        /** List charges newest-first (the refund enabler — discover the charge_id).
+         *  Filters: user_id, status, limit (clamped 1..100, default 50). */
+        listCharges: (q?: {
+            user_id?: string;
+            status?: "succeeded" | "failed" | "refunded" | "partially_refunded" | "pending";
+            limit?: number;
+        }) => Promise<{
+            charges: Array<{
+                charge_id: string;
+                end_user_id: string;
+                provider: string;
+                amount_cents: number;
+                amount_refunded: number;
+                currency: string;
+                status: string;
+                created_at: string;
+            }>;
+        }>;
+        /** Provider webhook event log (payments.md §7 "Event log & replay"):
+         *  operator visibility over every delivery — incl. persisted signature
+         *  failures — plus an idempotent reprocess verb. Needs payments:read
+         *  (reprocess: payments:write). */
+        webhookEvents: {
+            /** List deliveries newest-first (keyset-paginated; pass `cursor` from a
+             *  prior page's next_cursor). List rows omit payload/raw_body. */
+            list: (q?: {
+                provider?: "mock" | "stripe" | "paddle" | "revenuecat" | "paypal";
+                event_type?: string;
+                outcome?: "received" | "processed" | "error" | "sig_failed" | "parse_failed" | "reprocessed";
+                since?: string;
+                cursor?: string;
+                limit?: number;
+            }) => Promise<{
+                events: PaymentsWebhookEvent[];
+                next_cursor: string | null;
+            }>;
+            /** Full delivery detail incl. the verified payload and (for failed
+             *  deliveries) the truncated raw body. */
+            get: (eventId: string) => Promise<PaymentsWebhookEvent>;
+            /** Re-run the fold from the STORED payload (idempotent — never
+             *  double-grants; 409 not_reprocessable for sig_failed/parse_failed). */
+            reprocess: (eventId: string) => Promise<{
+                event_id: string;
+                reprocessed: boolean;
+                event_type: string;
+            }>;
+        };
+    };
+}
+export {};