@vxil/sdk 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -160,7 +160,11 @@ export interface Delivery {
     template_id: string;
     locale: string;
     to_email: string;
-    status: 'queued' | 'sent' | 'failed' | 'suppressed';
+    /** `test_sink` (2026-10-04): the recipient matched the project's
+     *  `notifications.suppression.testRecipients` — rendered in full and recorded,
+     *  but no provider was called and the send is not billed. Read what would
+     *  have gone out with `notifications.delivery(id)` (`rendered`). */
+    status: 'queued' | 'sent' | 'failed' | 'suppressed' | 'test_sink';
     attempts: number;
     provider: string;
     provider_message_id: string | null;
@@ -185,6 +189,27 @@ export interface Delivery {
      *  `delivery_id` on the 202.) */
     deliver_after?: string | null;
 }
+/** One delivery by id (`notifications.delivery(id)`): the row plus a render.
+ *  For a `test_sink` row `rendered` is the FULL render the send produced (its
+ *  data, its locale — an `ar` template carries `dir="rtl"`) and `rendered_from`
+ *  is `'send'` — EXCEPT auth mail (the `magic-link` / `otp-code` templates and
+ *  the auth feature's password-reset / e-mail-verification mail) and a row
+ *  sunk at delivery time (an address added to `testRecipients` after the send
+ *  was queued): those are rendered WITHOUT the send's data (`rendered_from:
+ *  'send_redacted'`), so a sign-in link, code or reset link is never stored or
+ *  readable. For every other row the template variables were never stored, so
+ *  `rendered` is the template re-rendered with no data (`rendered_from:
+ *  'template'`), or null when it cannot be rendered. */
+export interface DeliveryDetail extends Delivery {
+    last_error_msg?: string | null;
+    rendered: {
+        subject: string;
+        html: string;
+        text: string;
+        locale: string;
+    } | null;
+    rendered_from?: 'send' | 'send_redacted' | 'template';
+}
 /** An ADDITIVE, non-fatal note on a 202 send — today only `mock_provider`
  *  (the send is recorded but no email leaves vxil). */
 export interface NotificationWarning {
@@ -403,9 +428,20 @@ export interface JobRun {
      *  problem (400 / 413 / 422 — e.g. a callback key the collection does not
      *  declare) is retried with only the status column (a progress update tries
      *  the declared `progress_fields` first), so an undeclared key no longer
-     *  strands the row; this says what was dropped. Never flips the run; not cleared by a later
-     *  successful mirror (compare `generation_status` / `at`). */
+     *  strands the row; this says what was dropped (`status_written`: whether
+     *  the record holds the status word). Never flips the run. A later TERMINAL
+     *  mirror that lands cleanly moves it to `last_mirror_error` (null here
+     *  again); a non-terminal success leaves it. A write the record refuses
+     *  because it already holds a terminal word, or because its
+     *  `status_mirror.fence_field` names another run, is skipped quietly —
+     *  never a mirror_error. */
     mirror_error?: JobRunMirrorError | null;
+    /** the single-run read, generation runs only: the `mirror_error` a later
+     *  clean terminal mirror healed; null otherwise */
+    last_mirror_error?: JobRunMirrorError | null;
+    /** the single-run read, generation runs only: when that healing terminal
+     *  mirror landed (ISO); null otherwise */
+    mirror_ok_at?: string | null;
     /** the single-run read only: the enqueue `concurrency_key` this run holds
      *  while running or waiting; null for an unkeyed run */
     concurrency_key?: string | null;
@@ -458,6 +494,7 @@ export interface JobEnqueueResult {
 export interface JobRunsQuery {
     job_name?: string;
     state?: JobRun['state'] | string;
+    /** exact run_ids, at most 50 distinct (more answers 422 — page in chunks of 50) */
     ids?: string[];
     batch_id?: string;
     /** ISO: runs created at or after */
@@ -501,13 +538,25 @@ export interface JobRunMirrorError {
     code: string | null;
     /** the target's message (≤ 200 chars), e.g. "unknown field 'video_url'" */
     message: string | null;
+    /** the target's hint (≤ 200 chars) when it sent one — e.g. the engine
+     *  detail of a cms validate hook that could not evaluate */
+    hint?: string;
     /** when it was refused (ISO) */
     at: string;
+    /** whether the record holds `generation_status` after this write: true
+     *  when a narrower retry carrying the status word landed (or the write left
+     *  the word out because the record already held it); false when no write
+     *  carrying it landed — the full write was already the status column alone,
+     *  the refusal was not a body problem (401 / 403 / 404 / 409 / 429 / 5xx,
+     *  a timeout), or every narrower retry was refused. Absent on errors
+     *  recorded before it existed. */
+    status_written?: boolean;
     /** present when a narrower retry LANDED: the keys that were not written */
     fields_dropped?: string[];
-    /** present when every narrower retry was refused too (the last one's HTTP
-     *  status, 0 = no answer): the status word itself was refused and the
-     *  record still holds the previous status */
+    /** present when narrower retries ran and none landed: the LAST one's HTTP
+     *  status (0 = no answer). The ladder stops at the first refusal that is not
+     *  a body problem, so read `status_written`, not this, for "did the status
+     *  word land" */
     retry_status?: number;
 }
 /** A run's latest progress report (`JobRun.progress`): only these keys pass. */
@@ -748,6 +797,28 @@ export interface PaymentsSimulationResult {
         pass: boolean;
     };
 }
+/** `payments.moveSubscriptionUntil` (the test clock) — the moved row and the
+ *  user's entitlement snapshot after the refold. */
+export interface PaymentsTestClockResult {
+    subscription_id: string;
+    user_id: string;
+    tier: string | null;
+    /** 'lapsed' after a move into the past, 'active' after one into the future */
+    status: string;
+    since: string | null;
+    until: string;
+    previous_until: string | null;
+    /** true when THIS move ended access (payments.subscription.lapsed emitted) */
+    lapsed: boolean;
+    /** why the project may use the test clock */
+    lane: 'mock' | 'sandbox' | 'dev';
+    entitlement: {
+        tier: string;
+        entitlements: string[];
+        quotas: Record<string, number>;
+        source_sub_id: string | null;
+    };
+}
 /** The ONE complete entitlement read (GET /v1/payments/entitlements; guide ch. 6,
  *  payments). `until` is the winning subscription's current_period_end (+ the
  *  configured grace window when it is past_due); null on the free baseline. */
@@ -880,6 +951,10 @@ export interface FileUploadUrl {
     expires_in: number;
     /** When the OBJECT expires (null = never). */
     expires_at: string | null;
+    /** The headers the PUT to `upload_url` must send, exactly — each one is
+     *  signed into the URL: `content-type`, plus `x-amz-checksum-sha256` when
+     *  the request declared `checksum_sha256`. */
+    upload_headers?: Record<string, string>;
 }
 /** `files.usage` answer. */
 export interface FilesUsage {
@@ -893,7 +968,15 @@ export interface FilesUsage {
         maxObjectBytes?: number;
         maxTotalBytes?: number;
     };
-    available: Record<string, number | null>;
+    /** Headroom left under the quotas. Never negative: when usage sits ABOVE a
+     *  lowered quota (or a plan downgrade) both read 0 and `over_quota` is true
+     *  — new uploads answer 422 quota_exceeded until usage drops back under. */
+    available: {
+        object_slots: number;
+        bytes_remaining: number;
+        over_quota?: boolean;
+        [key: string]: number | boolean | null | undefined;
+    };
     /** Your plan's storage ceiling, and whether `quotas.maxTotalBytes` is that
      *  ceiling (`plan`) or your own lower value (`config`). */
     storage_plan?: {
@@ -1361,7 +1444,8 @@ export interface PaymentsSubscriptionStatusEventPayload {
     current_period_end: string | null;
     environment: PaymentsEventEnvironment;
     /** what wrote it: the provider event type, `subscription.synced` /
-     *  `subscription.restored`, or `period_end_enforced` */
+     *  `subscription.restored`, `period_end_enforced`, or `test_clock` (a
+     *  `moveSubscriptionUntil` on a non-production project ended the row) */
     event_type: string;
     slack_hours: number | null;
     level: 'info';
@@ -1502,6 +1586,24 @@ export interface PaymentsConformanceEventPayload {
     level: 'info' | 'error';
     state: 'ok' | 'broken';
 }
+/** `payments.test_clock.moved` — the test clock moved a manual grant's or a
+ *  purchase pass's end (`moveSubscriptionUntil`; non-production projects only).
+ *  `lapsed` is true when this move ended access (a `payments.subscription.lapsed`
+ *  with `event_type: 'test_clock'` follows); `lane` names why the project was
+ *  allowed: `mock` provider, a `sandbox` provider environment, or a `dev`
+ *  (preview / `vxil dev up`) project. */
+export interface PaymentsTestClockMovedEventPayload {
+    end_user_id: string;
+    subscription_id: string;
+    provider_sub_id: string;
+    tier: string | null;
+    previous_until: string | null;
+    until: string;
+    lapsed: boolean;
+    lane: 'mock' | 'sandbox' | 'dev';
+    level: 'info';
+    state: 'ok';
+}
 /** Event name → typed `data`, for the events that settle work you started and
  *  (since 2026-10-01) every `payments.*` event. `VxilEventPayload<'job.generation.failed'>`
  *  names one; everything else on the catalog is `Record<string, unknown>` until
@@ -1536,6 +1638,7 @@ export interface VxilEventPayloads {
     'payments.reconcile.discrepancy': PaymentsReconcileDiscrepancyEventPayload;
     'payments.reconcile.ok': PaymentsReconcileOkEventPayload;
     'payments.conformance': PaymentsConformanceEventPayload;
+    'payments.test_clock.moved': PaymentsTestClockMovedEventPayload;
 }
 export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloads ? VxilEventPayloads[E] : Record<string, unknown>;
 /** The `trigger` label on the envelope. The config spells two of them in
@@ -1543,9 +1646,11 @@ export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloa
 export type FunctionEnvelopeTrigger = 'http' | 'cms-hook' | 'auth-hook' | 'queue' | 'cron' | 'webhook';
 /** The audiences a function's scoped callback tokens are minted for — one per
  *  feature its declared scopes reach. `control-plane` carries `users:*` /
- *  `usage:read` only. There is deliberately no `functions` audience: a function
- *  cannot call another function. */
-export type FunctionCallbackAudience = 'cms' | 'payments' | 'notifications' | 'comments' | 'files' | 'ai' | 'rag' | 'vector-search' | 'activity-feed' | 'orgs' | 'auth' | 'jobs' | 'realtime' | 'rate-limits' | 'control-plane';
+ *  `usage:read` / `audit:read` only; `webhooks` carries `webhooks:read` only (read the inbound
+ *  sources and received events — e.g. `GET /v1/webhooks/events?after=`). There
+ *  is deliberately no `functions` audience: a function cannot call another
+ *  function. */
+export type FunctionCallbackAudience = 'cms' | 'payments' | 'notifications' | 'comments' | 'files' | 'ai' | 'rag' | 'vector-search' | 'activity-feed' | 'orgs' | 'auth' | 'jobs' | 'realtime' | 'rate-limits' | 'control-plane' | 'webhooks';
 /** One short-lived scoped token per audience your scopes imply
  *  (`env.scoped_jwts.cms`, `env.scoped_jwts['control-plane']`); an audience your
  *  scopes do not reach is absent. Send it as `Authorization: Bearer …` to
@@ -1607,6 +1712,43 @@ export interface WebhookTriggerPayload<D = Record<string, unknown>> {
         truncated: true;
     } | null;
 }
+/** The verification parameters of an inbound `hmac` source (`webhooks.sources.create`). */
+export interface WebhookHmacVerify {
+    /** the header carrying the signature (case-insensitive) */
+    header: string;
+    algorithm?: 'sha256' | 'sha1';
+    encoding?: 'hex' | 'base64';
+    /** stripped before comparing (e.g. `sha256=`); required on the request when set */
+    prefix?: string;
+    /** a header carrying the signing timestamp (unix seconds or ISO 8601): the
+     *  signed message becomes `<timestamp><timestamp_separator><body>` */
+    timestamp_header?: string;
+    /** default '.'; '' to concatenate */
+    timestamp_separator?: string;
+    /** default 300, 1..3600 */
+    tolerance_seconds?: number;
+    event_id_header?: string;
+    event_type_header?: string;
+}
+/** `payload.data` of a `webhook` invocation fired by an inbound source whose
+ *  `target_function` is this function (`payload.event === 'inbound_webhook.received'`). */
+export interface InboundWebhookTriggerData {
+    vxil_event_id: string;
+    source_id: string;
+    provider: string;
+    provider_event_id: string | null;
+    event_type: string | null;
+    sig_verified: boolean;
+    /** the provider's JSON body; null when it was larger than 48 000 bytes
+     *  (`payload_omitted: true`) — read it with
+     *  `GET /v1/webhooks/events?event_id=<vxil_event_id>` (scope webhooks:read) */
+    payload: Record<string, unknown> | unknown[] | null;
+    payload_omitted?: true;
+    /** true on a `POST /v1/webhooks/sources/:id/test` probe */
+    test?: true;
+    /** true on a `POST /v1/webhooks/events/:id/replay` */
+    replayed?: true;
+}
 /** `POST /v1/fn/:name`: `payload` is the JSON request body (the query
  *  parameters on a GET). */
 export interface HttpFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
@@ -2744,6 +2886,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     readonly fn: { [K in keyof S["functions"] & string]: FnInvoker<S["functions"][K]["Input"], S["functions"][K]["Output"]>; };
     private call;
     readonly users: {
+        /** Create or replace a tenant user by id. Upserting a deleted id brings it
+         *  back; upserting an ERASED id re-creates it as a new, empty user
+         *  (`erased_at` cleared — the erase already removed the old data). While
+         *  the erased user's files are still being erased the call fails with 409
+         *  `user_erase_pending`; retry later. `bulk` is all-or-nothing. */
         upsert: (user: {
             id: string;
             email?: string;
@@ -2758,6 +2905,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         get: (id: string, opts?: {
             includeDeleted?: boolean;
         }) => Promise<VxilUser>;
+        /**
+         * Update a user. `email` / `display_name` / `avatar_url` are replaced
+         * (null clears them). `attributes` is DEEP-MERGED into the stored
+         * attributes (RFC 7396 merge patch): objects merge key by key, arrays and
+         * scalars replace, and `null` deletes a key AT ANY DEPTH — including inside
+         * a subtree the row does not have yet, where the null is simply dropped
+         * (`{ attributes: { prefs: { phone: null } } }` never stores a null).
+         * Scope users:write.
+         */
         patch: (id: string, patch: {
             email?: string | null;
             display_name?: string | null;
@@ -2780,7 +2936,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * Merge a REGISTRY-ONLY user (a row you created with upsert that never
          * signed in) INTO another user of the tenant: its attributes fill the
          * survivor's gaps (the survivor wins on conflicts), the merged id is
-         * soft-deleted, its owner-scoped cms / files / payments rows move to the
+         * soft-deleted, its owner-scoped cms / files / payments / jobs rows move to the
          * survivor, and `auth.user.merged { from, into, method: 'registry_merge' }`
          * is audited. `rekeyed: false` means a re-key could not finish inside the
          * request — the event is the backstop (call the feature's re-key route
@@ -2999,8 +3155,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             /** 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>;
+        /** A single delivery by id (the list is `deliveries()`), with its render —
+         *  the full one for a `test_sink` row (see `DeliveryDetail`). */
+        delivery: (deliveryId: string) => Promise<DeliveryDetail>;
         /** Email broadcast campaigns (guide ch. 6, notifications): audience-ref fan-out
          *  with quiet-hours + frequency-cap policy. `schedule_cron` sets a recurring
          *  send (status `scheduled`); omit it for a `draft`. */
@@ -3053,6 +3210,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 skipped_freq_cap: number;
                 skipped_no_email: number;
                 already_sent: number;
+                /** recipients in `suppression.testRecipients` on this page: recorded
+                 *  `test_sink`, never sent, never billed */
+                test_sink?: number;
             }>;
         };
     };
@@ -3099,11 +3259,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             brief?: boolean;
         }) => Promise<VxilPlan>;
     };
+    /** The project audit log. Needs `audit:read` (the narrow read-only scope —
+     *  declare it on a function to read the log from its callback token) or
+     *  `features:read`. Server-only: a public / thin-client key cannot read it. */
     readonly audit: {
+        /**
+         * The audit trail, newest first. `subject` narrows to the events about ONE
+         * thing: a user id (`payload.user_id` / `payload.id`), a cms record
+         * (`payload.item_id` — the record's history), a verified end user
+         * (`payload.end_user_id` — what that person changed through a thin-client
+         * key or a function acting for them, and their payments events), or a
+         * principal (`actor`). Server keys only.
+         */
         list: (q?: {
             since?: string;
             cursor?: string;
             limit?: number;
+            subject?: string;
         }) => Promise<Array<{
             id: string;
             event: string;
@@ -3121,6 +3293,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             until?: string;
             after_id?: string;
             limit?: number;
+            /** the same subject filter as `list` */
+            subject?: string;
         }) => Promise<{
             events: Array<{
                 id: string;
@@ -3225,7 +3399,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *
          * The answer's `generation_status` is `pending` on a fresh enqueue; a replay
          * of the same `idempotency_key` (`deduplicated: true`) carries the run's
-         * status NOW (`processing`, `completed` or `failed` too).
+         * status NOW (`processing`, `completed` or `failed` too). The key is bound
+         * to the request BODY: re-sending it with a different body (another
+         * payload — a rebuilt `deadline_at` included —, provider, completion,
+         * timeout, reserve…) will answer 422 `idempotency_key_reused` naming the
+         * original run (the ai-v1 rule). That check is being rolled out: today a
+         * mismatch is only logged, on every project, and the send is still
+         * deduplicated to the first run; a changelog entry will announce
+         * enforcement — so keep the body deterministic now. A 409 `generation_in_progress`
+         * (Retry-After 5) means the run that key names is still placing its
+         * credit hold.
          *
          * `reserve_credits` takes a PROVISIONAL held credit debit at enqueue
          * (linked to the run), committed on `completed` and reversed on
@@ -3233,7 +3416,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * `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; the run ends with job.generation.failed
-         * `ReserveInsufficient` and the 402 names its `run_id`); a runaway over the
+         * `ReserveInsufficient` and the 402 names its `run_id`; the key is released,
+         * so the same request after a top-up starts a new run); a runaway over the
          * per-tenant outstanding-holds ceiling → 429 (Retry-After 5). Payments
          * unreachable at the hold → 503 `payments_unavailable` (Retry-After 15;
          * nothing started, nothing held — re-send the same request), unless
@@ -3254,8 +3438,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *
          * `opts.retryOnCapacity: { maxWaitMs }` retries a CAPACITY 429
          * (`generation_concurrency_exceeded`, `reserve_holds_exceeded`,
-         * `queue_full`) and a 503 `payments_unavailable`, honouring Retry-After
-         * with jitter, with the SAME
+         * `queue_full`), a 503 `payments_unavailable` / `enqueue_interrupted` and a
+         * 409 `generation_in_progress` (the key's run is still placing its credit
+         * hold), honouring Retry-After with jitter, with the SAME
          * idempotency_key (one is generated when the input has none), until
          * maxWaitMs has passed — then the last 429 is thrown. */
         generation: (input: {
@@ -3299,6 +3484,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 record_id: string;
                 column?: string;
                 progress_fields?: Array<"progress" | "stage" | "message">;
+                /** cms only: a declared string field the mirror stamps with this
+                 *  run's `run_id` on its first write; every later write of the run
+                 *  requires it (a cms `if` precondition), so an older run's late
+                 *  writes never land on a row a newer run has claimed. A write the
+                 *  record refuses that way — or because it already holds
+                 *  `completed` / `failed` — is skipped, not a `mirror_error`. */
+                fence_field?: string;
             };
             timeout?: {
                 after_ms: number;
@@ -3376,19 +3568,65 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         /** Cancel a run that has not started its current attempt (`queued`,
          *  `delayed`, `retrying`) or a plain run handed off to its signed callback
          *  (`waiting` after its handler answered 202 — the callback URL is
-         *  consumed). A `running` run (a delivery in flight, or a generation
-         *  waiting on its provider), a run waiting on an event, or a terminal run
-         *  answers `409 not_cancellable`. A generation's credit hold is released. */
+         *  consumed). A generation's credit hold is released — a STARTED
+         *  generation's too (its provider accepted it): it ends `failed`
+         *  (`Cancelled`) and a late provider callback is a no-op, but the provider
+         *  is NOT told, so its work and its charge may still complete. A plain
+         *  `running` run (a delivery in flight), a run waiting on an event, or a
+         *  terminal run answers `409 not_cancellable`. */
         cancel: (runId: string) => Promise<{
             run_id: string;
             state: string;
         }>;
         /** Clone a terminal run into a fresh queued run. A generation run answers
-         *  `409 not_replayable` — submit the generation again instead. */
+         *  `409 not_replayable` — submit the generation again instead; a redacted
+         *  or erased run answers `409 run_redacted` (its payload is gone). */
         replay: (runId: string) => Promise<{
             run_id: string;
             replayed_from: string;
         }>;
+        /** SERVER-ONLY (403 server_only in end-user mode). Account merge: move the
+         *  credit-hold owner (`reserve_credits.user_id`) of every run of
+         *  `from_user_id`, in any state, onto `into_user_id`, so the surviving
+         *  account reads, cancels and replays the generation runs it started as a
+         *  guest. ONE bounded page (≤500 runs) per call — call again until `done`
+         *  (idempotent: a second call moves 0). The jobs consumer of
+         *  `auth.user.merged { from, into }`; auth and `users.merge` call it after
+         *  a merge, the event is the backstop. Emits one `jobs.runs.rekeyed` when
+         *  a call moved at least one run (none on a zero-move call). Unlike the
+         *  files re-key it does not check that `into_user_id` exists.
+         *  Scope jobs:write. */
+        reKey: (input: {
+            from_user_id: string;
+            into_user_id: string;
+        }) => Promise<{
+            moved: number;
+            done: boolean;
+        }>;
+        /** SERVER-ONLY (403 server_only in end-user mode). Redact FINISHED runs
+         *  that hold personal data: the payload becomes `{ erased: true }`, the
+         *  result, progress, callback body and error text are cleared, a
+         *  generation's provider request body/headers are dropped and its credit
+         *  hold's user id is pseudonymized (unless its settle is still owed). The
+         *  row itself stays (state, timings, job_name). The same fields a GDPR
+         *  erase clears on the runs it can link to a user — use this for runs
+         *  nothing links to one (a plain queue run, an async function call).
+         *  `{ run_ids }` (≤500, one call; open runs are left alone and counted in
+         *  `skipped_open`) or `{ user_id }` (the generation runs whose credit hold
+         *  names that user — ONE page of ≤500 per call, call again until `done`).
+         *  Idempotent. Audited as `jobs.runs.redacted` (counts only; none when a
+         *  call redacted nothing). NOT cleared: concurrency_key, debounce_key,
+         *  idempotency_key and target_url — keep user ids out of those (hash them).
+         *  A redacted run does not replay. Scope jobs:write. */
+        redact: (input: {
+            run_ids: string[];
+        } | {
+            user_id: string;
+        }) => Promise<{
+            redacted: number;
+            skipped_open: number;
+            done: boolean;
+        }>;
         /**
          * Suspend the RUNNING run until an event (call from the executing
          * handler, then return 200 — the suspension wins). `state: 'resumed'` =
@@ -3513,9 +3751,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 sent: true;
                 test_link?: string;
             }>;
-            /** `opts.anonymous_token` is REQUIRED for a link that was requested with
-             *  one (the guest claim above): the same guest session must present it,
-             *  else `401 invalid_session`. `merged` is true only when the guest was
+            /** An unknown, expired or already-used link answers `401 invalid_token`
+             *  (request a new one with `request`). `opts.anonymous_token` is REQUIRED
+             *  for a link that was requested with one (the guest claim above): the
+             *  same guest session must present it, else `401 invalid_session`. `merged` is true only when the guest was
              *  folded into an existing account (then `user_id` is that account), and
              *  `rekeyed` rides beside it: true ⇒ the guest's payments / cms / files
              *  rows were already moved onto `user_id` when this returned; false ⇒
@@ -3578,8 +3817,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 /** On success the guest keeps its user id (`user_id` unchanged).
                  *  If the claimed email ALREADY has an account, the guest is MERGED
                  *  into it: `user_id` is the existing account, `merged: true`, and a
-                 *  fresh `session.token` (same session, re-signed for the merged
-                 *  identity — swap it client-side; other guest sessions are revoked).
+                 *  fresh `session.token` (the same session carried over to the merged
+                 *  identity under a new session id — swap it client-side: the old
+                 *  guest token is revoked, the refresh token keeps working; other
+                 *  guest sessions are revoked).
                  *  `rekeyed` (present on a merge): true ⇒ the guest's payments / cms /
                  *  files rows were already moved onto `user_id` when this returned, so
                  *  the merged user's next request finds them; false ⇒ the move ran
@@ -3700,7 +3941,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }) => Promise<AuthImportResult>;
             /** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
              *  deep-merges a bounded `attributes` object into its OWN shared identity
-             *  row (null deletes a key; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
+             *  row (null deletes a key at any depth — RFC 7396; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
              *  fields are not patchable here. In server mode the call throws 422
              *  `end_user_mode_required` — use `users.patch(id, …)` instead. */
             patchMe: (attributes: Record<string, unknown>) => Promise<{
@@ -3811,15 +4052,34 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 verified: true;
             }>;
         };
-        /** Social sign-in. The web `start`/`callback` flows are browser redirects
-         *  (not JSON calls): send the browser to
-         *  `GET /v1/auth/oauth/{provider}/start?redirect_uri=…` (server-side, with
-         *  your key) and hand the returned `code`+`state` to `…/callback`; `native`
+        /** Social sign-in. The web flow: `startUrl` fetches the provider authorize
+         *  URL with your key (a browser cannot follow the header-carrying 302 of
+         *  `GET /v1/auth/oauth/{provider}/start` itself), you navigate the browser
+         *  there, and hand the returned `code`+`state` to `…/callback`; `native`
          *  is the mobile / broker token-exchange the SDK wraps. `oidc` is the
          *  tenant's generic OIDC / SSO issuer (auth config `providers.oidc` —
          *  Okta / Entra / Auth0 / any OpenID Connect IdP, or a SAML broker that
          *  speaks OIDC); it rides the same three routes. */
         oauth: {
+            /** Start the web sign-in from a browser SPA: answers the provider
+             *  `authorize_url` (PKCE challenge, one-shot `state`, and for `oidc` a
+             *  nonce bound to the flow — all held server-side) for you to navigate
+             *  to: `location.assign((await vx.auth.oauth.startUrl('oidc',
+             *  { redirect_uri })).authorize_url)`. The provider returns to
+             *  `redirect_uri` with `?code&state`, which your page sends to
+             *  `GET /v1/auth/oauth/{provider}/callback` for the session. The same
+             *  rules as the redirect form apply: `redirect_uri` must match the auth
+             *  config `security.allowedRedirectOrigins` when set (else
+             *  `422 redirect_not_allowed`), and the state expires after
+             *  `expires_in` seconds (600). `anonymous_token` (a guest bearer)
+             *  promotes or merges that guest at the callback. */
+            startUrl: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
+                redirect_uri: string;
+                anonymous_token?: string;
+            }) => Promise<{
+                authorize_url: string;
+                expires_in: number;
+            }>;
             /** 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). */
@@ -3970,6 +4230,20 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                  *  (end-user reads and writes are `403 server_only`, even with an
                  *  owner_field). Server keys are never affected. */
                 end_user_access?: CmsEndUserAccess;
+                /** Role slugs one of which a VERIFIED end user must hold to WRITE this
+                 *  collection (create / update / $inc / delete / publish / transaction
+                 *  step / batch / filtered delete, and an end-user delete's cascade into
+                 *  it) — otherwise `403 role_required`. Reads are unaffected; server keys
+                 *  are never affected. Omitted/`[]` = ungated. ≤16 entries, each
+                 *  `^[a-z0-9][a-z0-9_-]{0,31}$` (the `orgs` role alphabet). */
+                write_roles?: string[];
+                /** Retention (guide ch. 4): live items created more than this many days
+                 *  ago (1..3650) are soft-deleted by the nightly platform sweep — like a
+                 *  normal delete (no restore; purged at least 30 days later, unique values freed), with ONE
+                 *  `cms.collection.retention_swept` audit event per collection per night
+                 *  instead of per-item delete events. A collection another collection
+                 *  references with an `on_delete` rule is skipped. Omit/null = keep. */
+                retain_days?: number | null;
                 fields?: Array<{
                     field: string;
                     type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file";
@@ -4019,6 +4293,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 actions?: CmsActionDef[];
                 /** present when not the default 'readwrite' */
                 end_user_access?: CmsEndUserAccess;
+                /** present when the collection is role-gated for end-user writes */
+                write_roles?: string[];
+                /** present when retention is set */
+                retain_days?: number;
             }>;
             list: () => Promise<Array<{
                 collection: string;
@@ -4027,6 +4305,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 owner_field?: string | null;
                 /** the collection's end-user access mode (absent from an older server = 'readwrite') */
                 end_user_access?: CmsEndUserAccess;
+                /** the roles an end user needs to write it (null / absent = ungated) */
+                write_roles?: string[] | null;
+                /** retention in days (null = keep until deleted; absent from an older server) */
+                retain_days?: number | null;
             }>>;
             addField: (collection: string, field: Record<string, unknown>) => Promise<void>;
             /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (guide ch. 4) —
@@ -4069,6 +4351,25 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 collection: string;
                 end_user_access: CmsEndUserAccess;
             }>;
+            /** Set (or clear, with `[]` / `null`) the collection's END-USER WRITE
+             *  ROLES (guide ch. 9): a verified end user must hold one of `roles` (the
+             *  session's verified role claims — orgs roles) to write the collection,
+             *  otherwise every write door answers `403 role_required`. Reads are
+             *  unaffected; server keys are never affected. Audited; takes effect on
+             *  the next write. */
+            setWriteRoles: (collection: string, roles: string[] | null) => Promise<{
+                collection: string;
+                write_roles: string[];
+            }>;
+            /** Set (1..3650 days) or clear (`null`) the collection's RETENTION (guide
+             *  ch. 4): the nightly platform sweep soft-deletes live items created more
+             *  than `days` ago — bounded per project per night, no restore, purged at
+             *  least 30 days later like any delete, one `cms.collection.retention_swept` audit event
+             *  per collection per sweep. Audited (`cms.collection.retain_days.set`). */
+            setRetention: (collection: string, days: number | null) => Promise<{
+                collection: string;
+                retain_days: number | null;
+            }>;
             /** Re-project the collection's index slots after an `index_slot` move
              *  (guide ch. 4). Slots are projected on WRITE only, so until this runs,
              *  stored rows keep their OLD projection: the new slot is NULL and the
@@ -4120,6 +4421,29 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 version: number;
                 data: Record<string, unknown>;
             }>;
+            /** Upsert by a declared `unique` field (guide ch. 4): creates the item, or
+             *  — when a live item already holds `data[field]` — merges `patch` into
+             *  THAT item instead (one transaction; update hooks, guards, version bump
+             *  and a `cms.item.updated` audit, exactly like `patch`; null clears a
+             *  field). `created` tells which happened (201 vs 200). Concurrent upserts
+             *  of one key serialize, so they never create a duplicate. */
+            upsert: (collection: string, input: {
+                data: Record<string, unknown>;
+                onConflict: {
+                    field: string;
+                    patch: Record<string, unknown>;
+                };
+                status?: "draft" | "published";
+                lock?: string;
+                guard?: CmsGuard;
+                guards?: CmsGuardTerm[];
+            }) => Promise<{
+                item_id: string;
+                status: string;
+                version: number;
+                data: Record<string, unknown>;
+                created: boolean;
+            }>;
             /** `expand` inlines relation/file fields into `data` (guide ch. 4): the
              *  full item envelope, a `{ object_id, $ref: 'files' }` stub for a file,
              *  the bare id on a cycle/depth cut, `null` for an invisible target. */
@@ -4128,7 +4452,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }) => Promise<Record<string, unknown>>;
             /**
              * The bounded query DSL. filter ops: $eq $ne $gt $gte $lt $lte $in
-             * $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
+             * ($ne is NULL-safe: a row whose field is absent or null counts as not
+             * equal; on a dotted join term the row still needs a readable target,
+             * so a null or dangling relation is excluded) $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
              * fields) $arrayContains/$anyOf (json/relation array containment, indexed);
              * range/sort needs slot-indexed fields. This is the
              * DELIBERATELY-UNTYPED escape hatch: it accepts everything the server
@@ -4518,6 +4844,32 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             };
             warnings?: string[];
         }>;
+        /**
+         * Log records of ONE function, one per invocation (outcome, wall/cpu ms,
+         * console lines, exceptions), oldest first. Pass the returned `next_since`
+         * back as `since` to read only newer records (a tail); without it, the most
+         * recent records of the last 24 hours. Kept 14 days. Needs
+         * `functions:read`. (GET /v1/functions/:name/logs)
+         */
+        logs: (name: string, opts?: {
+            since?: string;
+        }) => Promise<{
+            lines: Array<{
+                ts: string;
+                outcome: string;
+                wall_ms: number | null;
+                cpu_ms: number | null;
+                logs: Array<{
+                    level: string;
+                    message: string;
+                }>;
+                exceptions: Array<{
+                    name: string;
+                    message: string;
+                }>;
+            }>;
+            next_since: string | null;
+        }>;
     };
     /** The MCP aggregation surface (the `mcp` feature). */
     readonly mcp: {
@@ -4813,20 +5165,38 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             last_error_msg?: string | null;
         }>;
         sources: {
-            /** Register an inbound source; the receiver URL is returned ONCE. */
+            /** Register an inbound source; the receiver URL is returned ONCE.
+             *
+             * Destination: `forward_url` (your endpoint) OR `target_function` (a
+             * deployed function that declares a bare `trigger: { kind: 'webhook' }`
+             * binding — it receives `payload.event === 'inbound_webhook.received'`
+             * with the inbound envelope as `payload.data`), never both; neither =
+             * store only (read with `events.list`).
+             *
+             * `provider: 'hmac'` is the parameterized preset for any provider that
+             * signs an HMAC of the raw body (Shopify, Intercom, Linear, Zendesk, …):
+             * `verify` says which header, sha256|sha1, hex|base64, an optional prefix
+             * and an optional timestamp header + tolerance. Like stripe/paddle/slack it
+             * fails closed (401) until the source's signing secret is set. */
             create: (input: {
-                provider: "stripe" | "paddle" | "github" | "slack" | "revenuecat" | "generic";
+                provider: "stripe" | "paddle" | "github" | "slack" | "revenuecat" | "generic" | "hmac";
                 name: string;
                 forward_url?: string;
+                target_function?: string;
+                verify?: WebhookHmacVerify;
             }) => Promise<{
                 source_id: string;
                 receiver_url_path: string;
                 provider: string;
+                target_function?: string | null;
             }>;
             list: () => Promise<Array<{
                 source_id: string;
                 provider: string;
                 name: string;
+                forward_url?: string | null;
+                target_function?: string | null;
+                verify?: WebhookHmacVerify | null;
             }>>;
             delete: (sourceId: string) => Promise<void>;
             /** Send a sample envelope to the source's forward_url through the real
@@ -4841,20 +5211,38 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }>;
         };
         events: {
+            /** Received events. Newest first, paged with `cursor`; or — with `after`
+             * (your watermark, an event id) — OLDEST first from just after it, the
+             * drain shape: store `next_after` and pass it back, `has_more` says
+             * another page waits. The `after` drain answers only events received
+             * at least 10 s ago (ids are not strictly arrival-ordered, so a fresher
+             * event could otherwise commit below a stored watermark and be
+             * skipped); `cursor` and `event_id` reads are not lagged. `event_id`
+             * reads exactly one event. `cursor` and `after` are exclusive. */
             list: (q?: {
                 source_id?: string;
                 status?: string;
                 cursor?: string;
                 limit?: number;
+                after?: string;
+                event_id?: string;
             }) => Promise<{
                 events: Array<{
                     event_id: string;
+                    source_id: string;
+                    provider: string;
+                    provider_event_id: string | null;
                     event_type: string | null;
                     payload: Record<string, unknown>;
                     sig_verified: boolean;
                     status: string;
+                    received_at: string;
                 }>;
                 next_cursor: string | null;
+                /** `after` pages only */
+                next_after?: string | null;
+                /** `after` pages only */
+                has_more?: boolean;
             }>;
             replay: (eventId: string) => Promise<void>;
             /** The Svix message-attempt view: delivery state/attempts/DLQ flag for
@@ -5075,8 +5463,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * 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. */
+         * client asks for. Two safe ways to use it:
+         *   - on a server, with a server key (`user_id` names the subject); or
+         *   - in a browser / mobile app, with a PUBLIC `end_user_required` key and
+         *     the signed-in user's session (`endUserToken` on the client): the mint
+         *     runs in end-user mode and the token's subject is FORCED to the
+         *     verified user (any `user_id` you pass is overridden), so no
+         *     backend of your own is needed.
+         * Never ship a server key to a browser. */
         tokenProvider: (defaults: {
             user_id: string;
             ttl_seconds?: number;
@@ -5107,16 +5501,27 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *  long after the mint, whether or not `files.ttl` is enabled; `null` =
          *  never. The answer's `expires_in` is the UPLOAD URL's life in seconds;
          *  `expires_at` is when the object expires (null = never). `user_id` is
-         *  required with a server key and omitted in end-user mode. */
+         *  required with a server key and omitted in end-user mode.
+         *  `checksum_sha256` (the SHA-256 of the bytes, 64 hex or 44 base64
+         *  characters) is signed into the URL (send the answer's `upload_headers`
+         *  on the PUT) and kept with the upload: `complete` compares it with the
+         *  SHA-256 the store reports for the bytes — 409 `checksum_mismatch` when
+         *  they differ, 409 `checksum_unverified` when the store reports none —
+         *  and on success answers the verified `checksum_sha256`. */
         createUploadUrl: (input: {
             user_id?: string;
             filename: string;
             content_type: string;
             size_bytes: number;
             expiresInSeconds?: number | null;
+            checksum_sha256?: string;
         }) => Promise<FileUploadUrl>;
         /** Confirm the PUT (bytes verified, object → available). Answers the
-         *  object's `expires_at` (null = never). */
+         *  object's `expires_at` (null = never) and `checksum_sha256` (hex; null
+         *  when the store reported none) — a repeated complete answers the same.
+         *  When the upload declared `checksum_sha256`: 409 `checksum_mismatch` if
+         *  the bytes hash differently, 409 `checksum_unverified` if the store
+         *  reports no checksum (the object stays pending either way). */
         complete: (objectId: string) => Promise<{
             object_id: string;
             status: string;
@@ -5641,6 +6046,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             model?: string;
             user_id?: string;
             input?: Record<string, unknown>;
+            /** Drop chunks whose cosine `similarity` to the query is below this
+             *  (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
+            min_similarity?: number;
         }) => Promise<RagAnswer>;
         /** Streamed grounded answer: citations + the channel handle up front, tokens
          *  over the realtime channel. */
@@ -5655,13 +6063,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             model?: string;
             user_id?: string;
             input?: Record<string, unknown>;
+            /** Drop chunks whose cosine `similarity` to the query is below this
+             *  (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
+            min_similarity?: number;
         }) => Promise<RagStreamHandle>;
         /** Retrieval-only grounding preview (guide ch. 6, rag): 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.
          *  `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
-         *  0.016–0.033 at the top): a floor above ~0.033 drops every hit. Judge
-         *  relevance by each hit's `similarity` (cosine, -1..1) instead. */
+         *  0.016–0.033 at the top): a floor above ~0.033 drops every hit. For a
+         *  relevance threshold use `min_similarity`, which floors each hit's cosine
+         *  `similarity` (-1..1; overrides config `retrieval.minSimilarity`; a hit
+         *  with no measured similarity, e.g. keyword mode, is kept). */
         search: (input: {
             query: string;
             collection?: string;
@@ -5671,6 +6084,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             rerank?: boolean;
             boosts?: Record<string, unknown>;
             min_score?: number;
+            min_similarity?: number;
         }) => Promise<RagSearchResult>;
         /** Ingest into the backing vector-search collection (chunk → embed → index). */
         ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
@@ -5832,7 +6246,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * (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`.
+         * available balance can't cover `amount`. Throws VxilError(409,
+         * 'job_released') when `job_id` names a generation run that already ended
+         * (cancelled or failed) before this hold landed: nothing is held.
          *
          * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
          * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
@@ -6083,6 +6499,30 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             user_id: string;
             tier?: string;
         }) => Promise<PaymentsSimulationResult>;
+        /** SERVER-ONLY TEST CLOCK — move the end (`until`, past or future, within
+         *  5 years of now) of a MANUAL grant or a purchase pass, to test expired /
+         *  export-window / renew-soon states on demand. Allowed only where no live
+         *  money can be involved: a `mock`-provider project, a project whose
+         *  provider runs in its sandbox (`paddle.sandbox`, `paypal.sandbox`, a
+         *  Stripe `sk_test_` key), or a dev/preview project — elsewhere 403
+         *  `test_clock_forbidden` (also for a pass linked to a non-sandbox charge).
+         *  409 `provider_managed` for a provider subscription (use the provider's
+         *  own test clock); 409 `subscription_ended` for a revoked/refunded row.
+         *  The effect is a natural lapse's: the entitlements refold
+         *  (`payments.entitlement.changed`), a move into the past turns an active
+         *  row `lapsed` and emits `payments.subscription.lapsed` (`event_type:
+         *  'test_clock'`, `environment: 'sandbox'`) once; a move back into the
+         *  future revives it (as `active` — a `trialing` row does not return to
+         *  `trialing`; a `past_due` row's status is left as it is). Only the end
+         *  moves: `since` (the period start) is never rewritten, so after a move
+         *  before it `since` > `until`. Every move emits
+         *  `payments.test_clock.moved`. Both events are emitted after the move
+         *  commits, best-effort (as the period-end sweep's are): if one fails to
+         *  record, the move still stands and is not re-announced on a retry, so
+         *  assert on the returned `status` / `lapsed` rather than only on the
+         *  event. Same-tier passes stacked behind the moved one are not
+         *  re-chained. No credits are granted or reversed. */
+        moveSubscriptionUntil: (subscriptionId: string, until: string | Date) => Promise<PaymentsTestClockResult>;
         /** The last report-only reconciliation sweep result for this project
          *  (`run: null` before the first daily tick). Finding kinds:
          *  `balance_drift`, `entitlement_lag`, `null_tier`, `refund_pending`,