@vxil/cli 0.14.1 → 0.15.0

package/dist/_vxil-feature-configs.d.ts

@@ -6,9 +6,12 @@ export * from './_vxil-feature-configs-canonicalJson.js';
 export * from './_vxil-feature-configs-publicAssets.js';
 export declare const RESERVED_CREDIT_TYPES: ReadonlySet<string>;
 /** A function binding's `retry.maxAttempts` ceiling, and the
- *  binding kinds that may carry `retry` — the platform-delivered event lanes
- *  (an http invoke returns its own status; a cron tick's retry would overlap
- *  the next tick). Read by the schema, the deploy clamp and the CLI. */
+ *  binding kinds that may carry `retry` — every lane the platform delivers
+ *  through jobs. Since 2026-10-03 (JT-9) that includes `cron` (a failed tick is
+ *  re-delivered on the ladder; pair it with `overlap: 'skip'` so a retrying
+ *  tick never runs beside the next one) and `http` (the ASYNC lane only — a
+ *  synchronous invoke always hands its caller the function's own status).
+ *  Read by the schema, the deploy clamp and the CLI. */
 export declare const FN_RETRY_MAX_ATTEMPTS = 5;
 export declare const FN_RETRY_BINDING_KINDS: ReadonlySet<string>;
 /** True when a credit_type is a vxil-COGS reserved type (grant/consume/config

package/dist/config.d.ts

@@ -129,14 +129,22 @@ export type AuthHookEvent = 'user.created' | 'session.created' | 'session.revoke
  *  jobs retry ladder instead (60 s, 120 s, … backoff) and the last failed
  *  attempt dead-letters the run (`job.dead_lettered`, replayable from the
  *  Jobs page). Each attempt is a billed invocation and carries the SAME
- *  `idempotency_key` — dedupe on it. Effective attempts =
- *  min(maxAttempts, the project's `jobs.retry.defaultMaxAttempts`, default 5).
+ *  `idempotency_key` — dedupe on it. Effective attempts on queue / webhook /
+ *  cmsHook / authHook = min(maxAttempts, the project's
+ *  `jobs.retry.defaultMaxAttempts`, default 5); on `cron` and the async `http`
+ *  lane the binding's maxAttempts IS the budget (it becomes the schedule's /
+ *  the async run's own max_attempts), whatever the project default.
  *  A handler that partially writes and then fails re-fires its downstream
  *  events on EVERY attempt, so the chain is a tree (up to maxAttempts children
  *  per hop): the causal-depth guard bounds its length (32 hops), not its size —
  *  the breaker, the loop guard, the dead-letter quota and the daily share do.
- *  Write only once you will return 2xx, or dedupe on idempotency_key. Not accepted on `http` (it returns its
- *  real status to its caller) or `cron` (a retry would overlap the next tick). */
+ *  Write only once you will return 2xx, or dedupe on idempotency_key.
+ *  On `cron` (2026-10-03) a failed tick is re-delivered the same way — set
+ *  `overlap: 'skip'` beside it so a tick that is still retrying never runs
+ *  next to the following one. On `http` it applies to the ASYNC lane only
+ *  (`X-Vxil-Async: 1`): a 408 / 429 / 5xx answer is re-delivered up to
+ *  maxAttempts; a synchronous invoke always returns the function's own status
+ *  to its caller and is never retried. */
 export interface FunctionTriggerRetry {
     /** 1–5 attempts in all (1 = a failed attempt dead-letters at once, no re-delivery) */
     maxAttempts: number;
@@ -147,6 +155,7 @@ export interface FunctionTriggerRetry {
 export type FunctionTrigger = {
     kind: 'http';
     path?: string;
+    retry?: FunctionTriggerRetry;
 }
 /** `overlap: 'skip'` (2026-10-01): a due tick fires nothing while the
  *  previous tick's run is still open (queued / running / retrying / waiting /
@@ -156,6 +165,7 @@ export type FunctionTrigger = {
     kind: 'cron';
     schedule: string;
     overlap?: 'allow' | 'skip';
+    retry?: FunctionTriggerRetry;
 } | {
     kind: 'queue';
     source: string;

package/dist/vxil.js

@@ -3126,7 +3126,25 @@ var JobsConfigSchema = Type.Object({
     { default: {} }
   ),
   concurrency: Type.Object(
-    { maxConcurrent: Type.Integer({ default: 10, minimum: 1, maximum: 100 }) },
+    /** Per-tenant cap on PLAIN runs (queue / cron / event deliveries,
+     * incl. platform-delivered function triggers) in flight at once; generation
+     * runs have their own `generation.maxConcurrent`. EFFECTIVE value =
+     * min(this, the tenant's fair share of the shared delivery consumer): the
+     * platform runs at most 75 queue-lane deliveries in flight for ALL tenants
+     * together, and one tenant may hold at most 25 of them (jobs-v1 core.ts
+     * TENANT_FAIR_SHARE). Values 26..100 still validate (existing configs keep
+     * working) but buy nothing past the share. Over-cap runs wait (deferred,
+     * never rejected). The schema `description` below is the tenant-facing
+     * copy of this (planner catalog, generated config schema) — keep both in
+     * step. */
+    {
+      maxConcurrent: Type.Integer({
+        default: 10,
+        minimum: 1,
+        maximum: 100,
+        description: "Plain runs (queued jobs, cron fires, event deliveries, platform-delivered function triggers) delivered at once; generation runs have their own generation.maxConcurrent. Effective at most 25 (the per-project share of the shared delivery capacity): 26..100 validate but buy nothing more. Over-cap runs wait, never rejected."
+      })
+    },
     { default: {} }
   ),
   // Generation lifecycle knobs (guide ch. 6, jobs). The defaults and bounds are
@@ -4282,8 +4300,8 @@ var FunctionsConfigSchema = Type.Object({
               event: Type.Optional(Type.String()),
               // cmsHook: beforeCreate|beforeUpdate|beforeWrite · authHook: 'user.created'
               // (2026-09-25) the per-binding opt-in to re-delivery on
-              // queue / webhook / cmsHook / authHook (the cross-field rule
-              // rejects it on http / cron). Absent = the ACK-200 default. The
+              // queue / webhook / cmsHook / authHook, and since 2026-10-03 on
+              // cron and http (the async lane only). Absent = the ACK-200 default. The
               // receiver answers a failed attempt as an enveloped 503 (ladder)
               // and the last one as a terminal 409 (dead + job.dead_lettered);
               // effective attempts = min(maxAttempts, jobs.retry.defaultMaxAttempts).
@@ -4520,9 +4538,9 @@ function lowerAllTriggerBindings(def, name) {
   return bindings;
 }
 var CONFIG_FILENAMES = ["vxil.config.ts", "vxil.config.mjs", "vxil.config.js"];
-var VXIL_CONFIG_PKG_VERSION = "0.9.0";
-var VXIL_SDK_PKG_VERSION = "0.14.1";
-var VXIL_CLI_PKG_VERSION = "0.14.1";
+var VXIL_CONFIG_PKG_VERSION = "0.10.0";
+var VXIL_SDK_PKG_VERSION = "0.15.0";
+var VXIL_CLI_PKG_VERSION = "0.15.0";
 function ensureScaffoldPackageJson(cwd, opts = {}) {
   const file = resolve(cwd, "package.json");
   const wanted = {
@@ -10642,7 +10660,10 @@ function webhookInner(input) {
 }
 function planLocalDelivery(opts) {
   const { lane, input, bindings, fnName } = opts;
-  if (lane === "http") return { ok: true, lane, payload: input };
+  if (lane === "http") {
+    const hb = bindings.find((b3) => b3.kind === "http");
+    return { ok: true, lane, payload: input, ...hb ? { binding: hb } : {} };
+  }
   const refused = laneRefusal(lane, bindings, fnName);
   if (refused) return { ok: false, refusal: refused };
   if (lane === "queue" || lane === "cron") {
@@ -10705,11 +10726,13 @@ function planLocalDelivery(opts) {
 }
 function deployedVerdict(lane, binding, timeoutMs) {
   if (lane === "http") {
-    return ["deployed: the sync lane hands your caller this status and body as-is; the async lane records a non-2xx as a dead run"];
+    const r = retryFor(binding, 1);
+    return [r ? `deployed: the sync lane hands your caller this status and body as-is (never retried); the async lane re-delivers a 408/429/5xx up to ${r.maxAttempts} attempts, then records it as a dead run` : "deployed: the sync lane hands your caller this status and body as-is; the async lane records a non-2xx as a dead run"];
   }
   const out = [];
   if (lane === "cron") {
-    out.push("deployed: ACKs 200 whatever this returns \u2014 a cron tick is never retried; the first failure after a clean run emits functions.run.failed");
+    const r = retryFor(binding, 1);
+    out.push(r ? `deployed: retry on \u2014 a non-2xx tick is attempt 1 of ${r.maxAttempts}, re-delivered on the jobs ladder with the same idempotency_key (pair it with overlap: 'skip')` : "deployed: ACKs 200 whatever this returns \u2014 the cron binding declares no retry, so a failed tick is not redelivered; the first failure after a clean run emits functions.run.failed");
   } else {
     const r = retryFor(binding, 1);
     out.push(r ? `deployed: retry on \u2014 a non-2xx is attempt 1 of ${r.maxAttempts} (never more than the project's jobs.retry.defaultMaxAttempts); every attempt carries the same idempotency_key` : "deployed: ACKs 200 whatever this returns \u2014 the binding declares no retry, so a non-2xx is not redelivered");
@@ -11433,7 +11456,7 @@ var TOOLS = [
   {
     name: "jobs_enqueue",
     feature: "jobs",
-    description: "Enqueue a background job: Vxil POSTs a signed callback to your https target_url with retries/backoff until 2xx. Verify X-Vxil-Jobs-Signature against jobs_get_signing_secret. idempotency_key dedups for 24h. deliver_after (ISO) / delay_seconds (\u2264 30 d, at most one) defer the first delivery; > 12 h returns state 'delayed'. callback: true (or { ttl_seconds }) returns a single-use keyless callback_url (also on every delivery) that an external worker POSTs with { status: completed, result } / { status: failed, error } / { status: processing, progress, stage, message } \u2014 a handler answering 202 hands the run off until that callback arrives; the result is stored on the run (jobs_get_run).",
+    description: "Enqueue a background job: Vxil POSTs a signed callback to your https target_url with retries/backoff until 2xx. Verify X-Vxil-Jobs-Signature against jobs_get_signing_secret. idempotency_key dedups for as long as the original run is kept (open runs always; finished runs for the retention window, 7 d succeeded / 30 d failed by default). deliver_after (ISO) / delay_seconds (\u2264 30 d, at most one) defer the first delivery; > 12 h returns state 'delayed'. callback: true (or { ttl_seconds }) returns a single-use keyless callback_url (also on every delivery) that an external worker POSTs with { status: completed, result } / { status: failed, error } / { status: processing, progress, stage, message } \u2014 a handler answering 202 hands the run off until that callback arrives; the result is stored on the run (jobs_get_run). ttl_seconds (60..2678400): a run not STARTED within that long of being due is dead-lettered (last_error_class Expired) and never delivered. debounce { key, delay_seconds, max_delay_seconds? }: the first enqueue for (job_name, key) makes a run due in delay_seconds; each later one while it has not started replaces its payload and pushes it (never past first enqueue + max_delay_seconds) and returns the SAME run_id with debounced: true (not combinable with idempotency_key / deliver_after / delay_seconds / callback / batch_id). batch_id (+ batch_total for a batch built over several calls): when every run of the batch is terminal ONE job.batch.completed event fires (jobs_get_batch reads it); a completed batch takes no new runs (409 batch_closed); an idempotency_key matching a run outside the batch is 409 idempotency_batch_conflict. concurrency_key (+ concurrency_limit 1..100, default 1): at most that many runs of this job_name sharing the key hold it at once (e.g. the end user id for one import per user); a run holds its key from its first start until it finishes (running, waiting, between retries); the rest stay queued and start oldest first, never rejected.",
     inputSchema: {
       type: "object",
       properties: {
@@ -11450,7 +11473,23 @@ var TOOLS = [
             { type: "boolean" },
             { type: "object", properties: { ttl_seconds: { type: "integer", minimum: 60, maximum: 2678400 } }, additionalProperties: false }
           ]
-        }
+        },
+        concurrency_key: { type: "string", minLength: 1, maxLength: 200, description: "per-key concurrency: runs of this job_name sharing the key hold it from their first start until they finish; waiters start oldest first" },
+        concurrency_limit: { type: "integer", minimum: 1, maximum: 100, description: "how many runs may hold concurrency_key at once (default 1); requires concurrency_key" },
+        ttl_seconds: { type: "integer", minimum: 60, maximum: 2678400, description: "start deadline: not started this long after it is due \u2192 dead-lettered Expired, never delivered" },
+        debounce: {
+          type: "object",
+          description: "collapse a burst of enqueues for one key into ONE run that runs once the burst is quiet for delay_seconds",
+          properties: {
+            key: { type: "string", minLength: 1, maxLength: 200 },
+            delay_seconds: { type: "integer", minimum: 1, maximum: 86400 },
+            max_delay_seconds: { type: "integer", minimum: 1, maximum: 2592e3, description: "never push past first enqueue + this (default 10 \xD7 delay_seconds, clamped to 1 d..30 d)" }
+          },
+          required: ["key", "delay_seconds"],
+          additionalProperties: false
+        },
+        batch_id: { type: "string", maxLength: 200, description: "fan-in batch to join (charset a-zA-Z0-9_.:-)" },
+        batch_total: { type: "integer", minimum: 1, maximum: 1e5, description: "the batch's full size when it is built over several calls (needs batch_id)" }
       },
       required: ["job_name", "target_url"]
     },
@@ -11460,7 +11499,7 @@ var TOOLS = [
   {
     name: "jobs_enqueue_batch",
     feature: "jobs",
-    description: "Atomically enqueue up to 100 jobs in one call (one item invalid \u2192 422, nothing inserted). Each item = the jobs_enqueue input, incl. per-item idempotency_key and deliver_after/delay_seconds. Results align with input order.",
+    description: "Atomically enqueue up to 100 jobs in one call (one item invalid \u2192 422, nothing inserted). Each item = the jobs_enqueue input, incl. per-item idempotency_key, deliver_after/delay_seconds and ttl_seconds and concurrency_key/concurrency_limit (callback and debounce are single-enqueue only). Results align with input order. FAN-IN: a top-level batch_id puts every item in one batch \u2014 when every run is terminal ONE job.batch.completed { batch_id, total, succeeded, dead_lettered, cancelled } fires (subscribe a function to job.batch. to aggregate; jobs_get_batch reads the counters). For a batch built over several calls send the same batch_id and batch_total = its full size.",
     inputSchema: {
       type: "object",
       properties: {
@@ -11477,11 +11516,16 @@ var TOOLS = [
               idempotency_key: { type: "string" },
               max_attempts: { type: "number", minimum: 1, maximum: 20 },
               deliver_after: { type: "string" },
-              delay_seconds: { type: "number", minimum: 0, maximum: 2592e3 }
+              delay_seconds: { type: "number", minimum: 0, maximum: 2592e3 },
+              concurrency_key: { type: "string", minLength: 1, maxLength: 200 },
+              concurrency_limit: { type: "integer", minimum: 1, maximum: 100 },
+              ttl_seconds: { type: "integer", minimum: 60, maximum: 2678400 }
             },
             required: ["job_name", "target_url"]
           }
-        }
+        },
+        batch_id: { type: "string", maxLength: 200, description: "fan-in batch every item joins (charset a-zA-Z0-9_.:-)" },
+        batch_total: { type: "integer", minimum: 1, maximum: 1e5, description: "the batch's full size when it spans several calls (needs batch_id)" }
       },
       required: ["jobs"]
     },
@@ -11491,23 +11535,41 @@ var TOOLS = [
   {
     name: "jobs_list_runs",
     feature: "jobs",
-    description: "List job runs (state machine: queued\u2192running\u2192succeeded | retrying\u2192dead | cancelled; delayed = scheduled future delivery, waiting = suspended on an event). A platform webhook delivery run (job_name webhooks.deliver) carries webhook_event + audit_id (the event id in the audit log, = the audit_id your handler receives) \u2014 the event a dead delivery lost; its payload stays redacted.",
+    description: "List job runs, newest first (state machine: queued\u2192running\u2192succeeded | retrying\u2192dead | cancelled; delayed = scheduled future delivery, waiting = suspended on an event). A platform webhook delivery run (job_name webhooks.deliver) carries webhook_event + audit_id (the event id in the audit log, = the audit_id your handler receives) \u2014 the event a dead delivery lost; its payload stays redacted. Paging: the answer carries next_cursor (null on the last page) \u2014 pass it back as cursor for the next older page. Filters: job_name, state, batch_id, since / until (creation time, ISO).",
     inputSchema: {
       type: "object",
       properties: {
         job_name: { type: "string" },
         state: { type: "string", enum: ["queued", "running", "retrying", "waiting", "delayed", "succeeded", "failed", "dead", "cancelled"] },
+        batch_id: { type: "string", description: "only the runs of this fan-in batch" },
+        since: { type: "string", description: "ISO: runs created at or after" },
+        until: { type: "string", description: "ISO: runs created before" },
+        cursor: { type: "string", description: "next_cursor from the previous page" },
         limit: { type: "number", default: 20 }
       }
     },
     method: "GET",
     path: "/v1/jobs/runs",
-    queryArgs: ["job_name", "state", "limit"]
+    queryArgs: ["job_name", "state", "batch_id", "since", "until", "cursor", "limit"]
+  },
+  {
+    name: "jobs_get_batch",
+    feature: "jobs",
+    description: "Read a fan-in batch (runs enqueued with batch_id): state open | completed, the exact counters total / open / succeeded / dead_lettered / cancelled (+ expected_total when batch_total was declared), the live count of its retained runs by state, and event_emitted_at \u2014 when the one job.batch.completed event was written. vxil runs no next step: aggregate in your own function on job.batch.completed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        batch_id: { type: "string", description: "The batch_id you enqueued with." }
+      },
+      required: ["batch_id"]
+    },
+    method: "GET",
+    path: (a) => `/v1/jobs/batches/${encodeURIComponent(String(a.batch_id))}`
   },
   {
     name: "jobs_get_run",
     feature: "jobs",
-    description: "Read ONE run by run_id: the row jobs_list_runs summarises plus payload_json (your own jobs; a platform-enqueued run reads { redacted: true }), any generation_* fields, result (what the run completed with: its signed callback's result, or a generation's settled value; null when nothing reported one), progress (the latest { progress 0..100, stage, message, at } report, or null) and, on a generation run, mirror_error (the last status_mirror write the target refused \u2014 e.g. a callback key the collection does not declare: the status word was retried alone and fields_dropped lists what was not written \u2014 or null). Pass wait (1..25 seconds) to WAIT FOR THIS RUN: the read holds until the run is terminal (succeeded | failed | dead | cancelled) or the deadline passes, then returns the current row \u2014 on a timeout (or when the per-tenant wait budget of 60 held reads a minute declined to hold) state is still non-terminal, so check it and call again. Use it right after jobs_enqueue or an async function invoke instead of polling jobs_list_runs.",
+    description: "Read ONE run by run_id: the row jobs_list_runs summarises plus payload_json (your own jobs; a platform-enqueued run reads { redacted: true }), any generation_* fields, result (what the run completed with: its signed callback's result, or a generation's settled value; null when nothing reported one), progress (the latest { progress 0..100, stage, message, at } report, or null), concurrency_key / concurrency_limit (null when unkeyed) and, on a generation run, mirror_error (the last status_mirror write the target refused \u2014 e.g. a callback key the collection does not declare: the status word was retried alone and fields_dropped lists what was not written \u2014 or null). Pass wait (1..25 seconds) to WAIT FOR THIS RUN: the read holds until the run is terminal (succeeded | failed | dead | cancelled) or the deadline passes, then returns the current row \u2014 on a timeout (or when the per-tenant wait budget of 60 held reads a minute declined to hold) state is still non-terminal, so check it and call again. Use it right after jobs_enqueue or an async function invoke instead of polling jobs_list_runs.",
     inputSchema: {
       type: "object",
       properties: {
@@ -11592,15 +11654,18 @@ var TOOLS = [
   {
     name: "jobs_create_schedule",
     feature: "jobs",
-    description: "Create a recurring (5-field cron, UTC) or one-shot (run_at ISO) schedule that enqueues the job on the minute tick. Exactly one of cron/run_at. overlap 'skip' (cron only): no new run while the previous one is still open \u2014 the slot is counted, never caught up.",
+    description: "Create a recurring (5-field cron) or one-shot (run_at ISO) schedule that enqueues the job on the minute tick. Exactly one of cron/run_at. timezone (IANA, default UTC) is the zone the cron is read in \u2014 DST-correct: a fixed-hour local time skipped by a spring-forward fires once at the end of the gap, a repeated one fires once (an every-hour expression keeps its real-time cadence). external_id makes it an UPSERT: a live schedule with the same external_id is updated in place (created:false) instead of adding a second one \u2014 use it for per-user schedules (e.g. reminder:<user_id>). max_attempts (1..20) is each fired run's attempt budget. overlap 'skip' (cron only): no new run while the previous one is still open \u2014 the slot is counted, never caught up.",
     inputSchema: {
       type: "object",
       properties: {
         job_name: { type: "string" },
         target_url: { type: "string" },
         payload: { type: "object", additionalProperties: true },
-        cron: { type: "string", description: "e.g. '0 */6 * * *' (UTC)" },
+        cron: { type: "string", description: "e.g. '0 9 * * 1-5' (read in `timezone`)" },
         run_at: { type: "string", description: "future ISO timestamp" },
+        timezone: { type: "string", maxLength: 64, description: "IANA zone, e.g. 'Asia/Amman', 'Europe/London', 'America/New_York' (default 'UTC')" },
+        external_id: { type: "string", maxLength: 200, description: "your key for this schedule (printable ASCII, no spaces): a create naming a live schedule's external_id updates it (200) instead of creating one (201)" },
+        max_attempts: { type: "integer", minimum: 1, maximum: 20, description: "each fired run's attempt budget (default: the project's jobs.retry.defaultMaxAttempts)" },
         overlap: { type: "string", enum: ["allow", "skip"], default: "allow", description: "cron only: 'skip' fires nothing while an earlier run of this schedule is queued / running / retrying / waiting / delayed" }
       },
       required: ["job_name", "target_url"]
@@ -11608,10 +11673,157 @@ var TOOLS = [
     method: "POST",
     path: "/v1/jobs/schedules"
   },
+  {
+    name: "jobs_update_schedule",
+    feature: "jobs",
+    description: "Change a live schedule in place (PATCH): any of job_name, target_url, payload, cron, run_at, timezone, overlap, external_id (null clears), max_attempts (null = the project default). Its id, state (active/paused) and counters are kept. A cron / run_at / timezone change recomputes the next fire from now; any other change keeps the slot. Sending cron turns a one-shot into a cron schedule, run_at the reverse. 409 external_id_taken when another live schedule holds the external_id; 409 reconciler_owned for a platform-managed schedule (fn-cron:* etc. \u2014 change the function trigger and push instead).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        schedule_id: { type: "string" },
+        job_name: { type: "string" },
+        target_url: { type: "string" },
+        payload: { type: "object", additionalProperties: true },
+        cron: { type: "string" },
+        run_at: { type: "string", description: "future ISO timestamp" },
+        timezone: { type: "string", maxLength: 64 },
+        overlap: { type: "string", enum: ["allow", "skip"] },
+        external_id: { type: ["string", "null"], maxLength: 200 },
+        max_attempts: { type: ["integer", "null"], minimum: 1, maximum: 20 }
+      },
+      required: ["schedule_id"]
+    },
+    method: "PATCH",
+    path: (a) => `/v1/jobs/schedules/${encodeURIComponent(String(a.schedule_id))}`,
+    // the PATCH body is strict (unknown fields → 422): schedule_id is the URL segment only
+    pathArgs: ["schedule_id"]
+  },
+  {
+    name: "jobs_delete_schedule",
+    feature: "jobs",
+    description: "Delete a schedule (it stops firing; a run it already fired keeps running). Its external_id becomes free for a new schedule. fn-cron:* schedules belong to deployed functions \u2014 change the function's cron trigger and redeploy instead (a deleted one is recreated on the next deploy).",
+    inputSchema: {
+      type: "object",
+      properties: { schedule_id: { type: "string" } },
+      required: ["schedule_id"]
+    },
+    method: "DELETE",
+    path: (a) => `/v1/jobs/schedules/${encodeURIComponent(String(a.schedule_id))}`
+  },
+  {
+    name: "jobs_cancel_run",
+    feature: "jobs",
+    description: "Cancel a run that has not started its current attempt \u2014 queued, delayed or retrying \u2014 or a plain run handed off to its signed callback (waiting after its handler answered 202): it ends in state cancelled and is never delivered again (a handed-off run's callback URL is consumed). A generation run's credit hold is released and its status mirror is set. 409 not_cancellable for a run that is running (a delivery in flight, or a generation waiting on its provider \u2014 settle that one through its completion callback), waiting on an event (wake it with jobs_emit_event), or already terminal.",
+    inputSchema: {
+      type: "object",
+      properties: { run_id: { type: "string" } },
+      required: ["run_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/jobs/runs/${encodeURIComponent(String(a.run_id))}/cancel`
+  },
+  {
+    name: "jobs_replay_run",
+    feature: "jobs",
+    description: "Replay a finished plain run (dead / failed / cancelled / succeeded): a NEW run with the same job, target and payload is queued (replayed_from names the original). The target receives it like any delivery \u2014 dedupe on run_id if it must not act twice. A generation run is not replayable (409 not_replayable): enqueue the generation again.",
+    inputSchema: {
+      type: "object",
+      properties: { run_id: { type: "string" } },
+      required: ["run_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/jobs/runs/${encodeURIComponent(String(a.run_id))}/replay`
+  },
+  {
+    name: "jobs_emit_event",
+    feature: "jobs",
+    description: "Emit a named event: every run WAITING on it (a target that called POST /v1/jobs/runs/{run_id}/wait with this event) resumes, with payload delivered as its wakeup. Answers how many runs it woke (0 is not an error).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        event: { type: "string", maxLength: 200, description: "letters, digits and _ . : -" },
+        payload: { type: "object", additionalProperties: true }
+      },
+      required: ["event"]
+    },
+    method: "POST",
+    path: "/v1/jobs/events"
+  },
+  {
+    name: "jobs_enqueue_generation",
+    feature: "jobs",
+    description: "Start a long-running EXTERNAL generation (a render, a model job): vxil calls provider.url (https; your provider key in provider.headers), then learns completion by POLLING completion.poll.url every interval_ms or by the provider's WEBHOOK (completion.mode 'webhook' \u2014 a signed single-use callback URL is appended as completion.callback.query_param). completion.status_path names the status field; status_map maps provider words to completed / failed / processing. status_mirror writes the status onto your record (e.g. cms collection + record_id); timeout.after_ms ends it as failed; reserve_credits holds a user's credits, committed on completion and released on failure. Answers 202 { run_id, generation_status: 'pending' } (deduplicated:true for a repeated idempotency_key); 429 with Retry-After when the project's open-generation cap is reached. Read it with jobs_get_run (generation_status, result, progress, mirror_error).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_name: { type: "string" },
+        provider: {
+          type: "object",
+          properties: {
+            url: { type: "string", description: "https:// start URL" },
+            method: { type: "string" },
+            headers: { type: "object", additionalProperties: { type: "string" } },
+            body: { type: "object", additionalProperties: true }
+          },
+          required: ["url"]
+        },
+        completion: {
+          type: "object",
+          properties: {
+            mode: { type: "string", enum: ["poll", "webhook"] },
+            status_path: { type: "string", default: "status" },
+            poll: {
+              type: "object",
+              properties: {
+                url: { type: "string" },
+                method: { type: "string" },
+                headers: { type: "object", additionalProperties: { type: "string" } },
+                interval_ms: { type: "integer", minimum: 1e3, maximum: 6e5 }
+              },
+              required: ["url"]
+            },
+            callback: { type: "object", properties: { query_param: { type: "string" } }, required: ["query_param"] },
+            status_map: { type: "object", additionalProperties: { type: "string" } },
+            result_path: { type: "string" }
+          },
+          required: ["mode"]
+        },
+        status_mirror: {
+          type: "object",
+          properties: {
+            feature: { type: "string" },
+            collection: { type: "string" },
+            record_id: { type: "string" },
+            column: { type: "string" },
+            progress_fields: { type: "array", items: { type: "string", enum: ["progress", "stage", "message"] } }
+          },
+          required: ["feature", "collection", "record_id"]
+        },
+        timeout: { type: "object", properties: { after_ms: { type: "integer", minimum: 1e3, maximum: 36e5 } }, required: ["after_ms"] },
+        reserve_credits: {
+          type: "object",
+          properties: {
+            amount: { type: "integer", minimum: 1 },
+            user_id: { type: "string" },
+            credit_type: { type: "string" },
+            credit_types: { type: "array", items: { type: "string" } },
+            reason: { type: "string" }
+          },
+          required: ["amount", "user_id"]
+        },
+        payload: { type: "object", additionalProperties: true },
+        idempotency_key: { type: "string", maxLength: 200 },
+        max_attempts: { type: "integer", minimum: 1, maximum: 20 }
+      },
+      required: ["job_name", "provider", "completion"]
+    },
+    method: "POST",
+    path: "/v1/jobs/generation"
+  },
   {
     name: "jobs_list_schedules",
     feature: "jobs",
-    description: "List the tenant's schedules (incl. the fn-cron:* function ticks): cron, state, next/last run, overlap, skipped_fires, and `held` \u2014 non-null when the schedule fired on time but its oldest run has not started for 2+ intervals (held downstream).",
+    description: "List the tenant's schedules (incl. the fn-cron:* function ticks): cron, timezone, external_id, max_attempts, state, next/last run, overlap, skipped_fires, and `held` \u2014 non-null when the schedule fired on time but its oldest run has not started for 2+ intervals (held downstream).",
     inputSchema: { type: "object", properties: {} },
     method: "GET",
     path: "/v1/jobs/schedules"
@@ -18238,6 +18450,30 @@ export default defineConfig({
       "request-render.ts": "// request-render.ts \u2014 start ONE long render for the signed-in user (a vxil\n// function, http trigger, END-USER mode).\n//\n//   POST /v1/fn/request-render   (with the user's session)\n//   { \"composition\": \"promo-30s\", \"request_key\": \"<your idempotency key>\", \"props\": { \u2026 } }\n//   \u2192 202 { item_id, run_id, credits }      a new render, credits held\n//   \u2192 200 { duplicate: true, request_key, item_id, run_id, status }\n//                                           this user's request_key already started one\n//                                           (or its run has already ended: status 'failed')\n//   \u2192 402 { error: 'insufficient_credits', item_id }   nothing held; use a new request_key\n//   \u2192 429 / 502 { error, queued: true, item_id, request_key, retry_after }\n//                                           no run YET: the row is queued and\n//                                           redrive-pending starts it (credits\n//                                           held then). Never retry with a NEW\n//                                           request_key \u2014 that is a second render.\n//\n// What happens after the 202 is vxil's and your runtime's, not this function's:\n//   \u2022 the generation lane POSTs your render endpoint (secret render_url) with\n//     `Authorization: Bearer <render_token>` and the JSON body\n//       { render_id, user_id, composition, props,\n//         payload: { generation_id, correlation_id, deadline_at }, callback_url }\n//     (plus an X-Vxil-Jobs-Signature header). The endpoint must answer 2xx\n//     within 20 s \u2014 queue the work, do not render inline. A 408 / 429 / 5xx or\n//     a timeout is retried; any other 4xx ends the run and refunds the credits.\n//   \u2022 your runtime POSTs JSON to callback_url: { \"status\": \"processing\", \u2026 }\n//     while it works, then { \"status\": \"completed\", \"output_url\": \"\u2026\",\n//     \"duration_s\": 31.2, \"progress\": 100, \"stage\": \"done\" } \u2014 or\n//     { \"status\": \"failed\", \"error\": \"render_failed\", \"hint\": \"\u2026\" }.\n//   \u2022 vxil settles: completed COMMITS the held credits and writes every key of\n//     the body onto this render's row; failed, no answer by the deadline, or a\n//     cancel REFUNDS them and the row says failed. `deadline_at` (ISO time) is\n//     when vxil stops waiting: a runtime that cannot finish by then should post\n//     `failed` itself and stop \u2014 a `completed` after it changes nothing (the\n//     credits are already back and the row says failed).\n// Every run ends with job.generation.completed | failed (generation_id = the\n// row's item_id, correlation_id = its request_key) \u2014 notify-ready listens.\n//\n// DELIVERY IS AT-LEAST-ONCE and users double-tap: the row's render_key\n// (owner + ':' + request_key \u2014 per user) is unique, so a second start with the\n// same key is a 409. On a 409 we read THIS user's row: a row that already has\n// its run is a duplicate; a row with no run (the first start died between the\n// row and the enqueue, or lost the enqueue's answer) is RE-DRIVEN \u2014 the run\n// carries the same render_key as its idempotency_key, so jobs hands back the\n// existing run instead of starting a second render.\n\nimport type { HttpFunctionEnvelope } from '@vxil/sdk';\n\ntype Input = { composition?: string; request_key?: string; props?: Record<string, unknown> };\ntype Env = HttpFunctionEnvelope<Input>;\ntype RenderRow = {\n  item_id: string;\n  data: { composition?: string; props?: Record<string, unknown>; run_id?: string; status?: string };\n};\n\n/** What one render costs, in `render_credits`. Price by composition if yours\n *  differ \u2014 the per-run hold is clamped to `generation.maxReserveCredits`. */\nconst RENDER_CREDITS = 5;\n/** The deadline: a render your runtime never reports on fails and refunds\n *  after this long. At most one hour (`generation.maxTimeoutMs`). */\nconst RENDER_DEADLINE_MS = 1_800_000;\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const jobs = env.scoped_jwts?.jobs;\n    if (!cms || !jobs) return Response.json({ error: 'missing cms/jobs scope' }, { status: 403 });\n    const renderUrl = env.secrets?.render_url;\n    const renderToken = env.secrets?.render_token;\n    if (!renderUrl || !renderToken) {\n      return Response.json(\n        { error: 'store your render endpoint: vxil secrets set functions/render_url and functions/render_token' },\n        { status: 500 },\n      );\n    }\n    // the held credits are FORCED onto the verified end-user\n    const user = env.end_user?.id;\n    if (!user) return Response.json({ error: \"invoke request-render with the user's session (end-user mode)\" }, { status: 401 });\n\n    const composition = typeof env.payload?.composition === 'string' ? env.payload.composition.trim().slice(0, 120) : '';\n    const requestKey = typeof env.payload?.request_key === 'string' ? env.payload.request_key.slice(0, 120) : '';\n    const rawProps = env.payload?.props;\n    const props = rawProps && typeof rawProps === 'object' && !Array.isArray(rawProps) ? rawProps : {};\n    if (!composition || !requestKey) {\n      return Response.json({ error: 'need { composition, request_key, props? }' }, { status: 422 });\n    }\n    if (JSON.stringify(props).length > 16_384) {\n      return Response.json({ error: 'props too large (16 KB max) \u2014 pass a reference to your own storage instead' }, { status: 413 });\n    }\n    const renderKey = `${user}:${requestKey}`;\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n\n    // 1. create-or-find the row the app watches (owned by the user \u2014 cms forces\n    //    `owner` in end-user mode; the render_key_shape hook checks the key)\n    const created = await fetch(`${base}/v1/cms/items/renders`, {\n      method: 'POST',\n      headers: H,\n      body: JSON.stringify({\n        data: {\n          render_key: renderKey, request_key: requestKey, owner: user, composition, props,\n          credits: RENDER_CREDITS, status: 'pending', created_at: new Date().toISOString(),\n        },\n      }),\n    });\n    if (created.status === 409) {\n      // THIS user's row for this key (the read is owner-scoped in end-user mode)\n      const filter = encodeURIComponent(JSON.stringify({ render_key: renderKey }));\n      const found = await fetch(`${base}/v1/cms/items/renders?filter=${filter}&limit=1`, { headers: H });\n      const row = found.ok ? ((await found.json()) as { data?: { items?: RenderRow[] } }).data?.items?.[0] : undefined;\n      if (!row) return Response.json({ error: `render lookup: ${found.status}` }, { status: 502 });\n      if (row.data.run_id || row.data.status === 'failed') {\n        return Response.json({\n          duplicate: true, request_key: requestKey, item_id: row.item_id,\n          run_id: row.data.run_id ?? null, status: row.data.status ?? 'pending',\n        });\n      }\n      // a start that never got its run: re-drive it (jobs dedupes on render_key)\n      return startRun({\n        base, H, jobs, renderUrl, renderToken, user, renderKey, requestKey,\n        itemId: row.item_id, composition: row.data.composition ?? composition, props: row.data.props ?? props,\n      });\n    }\n    if (!created.ok) return Response.json({ error: `render row: ${created.status}` }, { status: 502 });\n    const itemId = ((await created.json()) as { data: { item_id: string } }).data.item_id;\n    return startRun({ base, H, jobs, renderUrl, renderToken, user, renderKey, requestKey, itemId, composition, props });\n  },\n};\n\ninterface StartArgs {\n  base: string; H: Record<string, string>; jobs: string; renderUrl: string; renderToken: string;\n  user: string; renderKey: string; requestKey: string; itemId: string;\n  composition: string; props: Record<string, unknown>;\n}\n\n/** 2. the webhook-mode generation run: your endpoint, the held credits, the\n *  deadline and the status mirror. Idempotent on render_key: a re-drive gets\n *  the run that already exists. */\nasync function startRun(a: StartArgs): Promise<Response> {\n  const enq = await fetch(`${a.base}/v1/jobs/generation`, {\n    method: 'POST',\n    headers: { authorization: `Bearer ${a.jobs}`, 'content-type': 'application/json' },\n    body: JSON.stringify({\n      job_name: 'render',\n      provider: {\n        url: a.renderUrl,\n        method: 'POST',\n        // stored with the run for your project only, shown as [redacted] on\n        // every run read, sent to your endpoint on the start call\n        headers: { authorization: `Bearer ${a.renderToken}` },\n        // your endpoint receives this, plus `payload` and `callback_url`\n        // (user_id: the owner a coordinator uploads the output file for)\n        body: { render_id: a.itemId, user_id: a.user, composition: a.composition, props: a.props },\n      },\n      completion: { mode: 'webhook', status_path: 'status' },\n      // the status word onto `status`, and a `processing` ping's progress /\n      // stage / message onto the same-named fields of the row\n      status_mirror: {\n        feature: 'cms', collection: 'renders', record_id: a.itemId, column: 'status',\n        progress_fields: ['progress', 'stage', 'message'],\n      },\n      reserve_credits: { amount: RENDER_CREDITS, user_id: a.user, credit_type: 'render_credits', reason: `render ${a.composition}` },\n      timeout: { after_ms: RENDER_DEADLINE_MS },\n      // rides job.generation.* as generation_id / correlation_id, and reaches\n      // your endpoint beside callback_url. deadline_at = when vxil stops\n      // waiting (the deadline counts from this enqueue; a re-drive gets the\n      // first run back, with ITS payload).\n      payload: {\n        generation_id: a.itemId, correlation_id: a.requestKey,\n        deadline_at: new Date(Date.now() + RENDER_DEADLINE_MS).toISOString(),\n      },\n      idempotency_key: a.renderKey,\n    }),\n  });\n  if (enq.status === 402) {\n    // not enough credits: the run already ENDED (job.generation.failed,\n    // ReserveInsufficient) and nothing was held. This key is spent; a new\n    // attempt (after a top-up) uses a new request_key.\n    const marked = await patchRow(a, { status: 'failed', error: 'insufficient_credits' });\n    // if that write failed the row still says pending with no run; a retry with\n    // the same key re-drives, gets the ended run back and marks it failed then\n    return Response.json(\n      { error: 'insufficient_credits', item_id: a.itemId, ...(marked ? {} : { row_updated: false }) },\n      { status: 402 },\n    );\n  }\n  if (!enq.ok) {\n    // 429 (too many in flight) / 5xx: no run YET \u2014 the row stays pending with\n    // no run, and it is QUEUED: redrive-pending (cron) starts it once a slot\n    // frees up (within the hour, or the row is failed and the owner told) and\n    // holds the credits then. `queued: true` says so. The app must NOT retry\n    // with a NEW request_key (that is a second render, charged twice): show\n    // \"queued\", watch the row, and retry only with the SAME request_key.\n    return Response.json(\n      { error: `generation enqueue: ${enq.status}`, queued: true, item_id: a.itemId, request_key: a.requestKey, retry_after: enq.headers.get('retry-after') },\n      { status: enq.status === 429 ? 429 : 502 },\n    );\n  }\n  const run = ((await enq.json()) as { data: { run_id: string; generation_status?: string; deduplicated?: boolean } }).data;\n  if (run.deduplicated && run.generation_status === 'failed') {\n    // a re-drive whose run already ENDED (refused for credits, failed or timed\n    // out, and the row write that said so was lost): record it and say so \u2014\n    // never report a fresh render with credits held\n    const marked = await patchRow(a, { run_id: run.run_id, status: 'failed' });\n    return Response.json({\n      duplicate: true, request_key: a.requestKey, item_id: a.itemId, run_id: run.run_id, status: 'failed',\n      ...(marked ? {} : { row_updated: false }),\n    });\n  }\n  const linked = await patchRow(a, { run_id: run.run_id });\n  // the run exists either way (and settles the row through the status mirror);\n  // an unlinked row is linked by the next same-key call\n  return Response.json(\n    { item_id: a.itemId, run_id: run.run_id, credits: RENDER_CREDITS, ...(linked ? {} : { row_updated: false }) },\n    { status: 202 },\n  );\n}\n\n/** PATCH this render's row; true when the write landed. */\nasync function patchRow(a: StartArgs, data: Record<string, unknown>): Promise<boolean> {\n  const res = await fetch(`${a.base}/v1/cms/items/renders/${encodeURIComponent(a.itemId)}`, {\n    method: 'PATCH',\n    headers: a.H,\n    body: JSON.stringify({ data }),\n  }).catch(() => undefined);\n  return res?.ok ?? false;\n}\n"
     }
   },
+  {
+    "id": "fan-in",
+    "title": "Fan-out / Fan-in (split \xB7 run in parallel \xB7 aggregate once)",
+    "vertical": "ops",
+    "summary": "Split one request into up to 500 parts, run every part as its own retried background job, and aggregate exactly once when the last part ends \u2014 without a workflow engine. One batch_id ties the parts together; vxil emits a single job.batch.completed when every part is terminal, and a function on that event writes the result onto the parent row. Re-entrant end to end: the same request_key resumes instead of starting twice, every part is idempotent, and a part that never starts within its TTL is counted as failed instead of hanging the batch.",
+    "collections": [
+      "reports",
+      "report_parts"
+    ],
+    "features": [
+      "jobs",
+      "cms",
+      "functions"
+    ],
+    "hasFunctions": true,
+    "byoKeys": [],
+    "configSrc": "import { defineConfig } from '@vxil/config';\n\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// \"Fan-out / Fan-in\" \u2014 split one request into parts, run every part as its\n// own background job, and aggregate ONCE when the last part has ended.\n//\n//   start-report (your function, http)\n//     \u2192 creates-or-finds the `reports` row (unique request_key)\n//     \u2192 writes one `report_parts` row per part (unique part_key)\n//     \u2192 POST /v1/jobs/enqueue-batch with batch_id = 'report:<item_id>' and\n//       batch_total = the number of parts \u2014 each part a job that runs\n//       compute-part, idempotent per part\n//   compute-part (queue trigger, retried up to 3 times)\n//     \u2192 computes ITS part and writes the result onto its `report_parts` row\n//   vxil\n//     \u2192 when EVERY part's run has ended (succeeded, dead-lettered, expired or\n//       cancelled) it emits ONE `job.batch.completed` event:\n//       { batch_id, total, succeeded, dead_lettered, cancelled }\n//   finish-report (webhook trigger on `job.batch.`)\n//     \u2192 reads the parts, aggregates, and finishes the `reports` row\n//       (status 'done', or 'partial' when some parts failed)\n//\n// vxil runs no \"next step\" for you: the batch is a counter and one event. The\n// aggregation is your own function, so the platform stays a queue, not a\n// workflow engine \u2014 and every step here is safe to run twice.\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nexport default defineConfig({\n  env: 'staging',\n\n  features: {\n    jobs: { enabled: true },\n    cms: {\n      // a row is live the moment it is written\n      draftPublish: false,\n    },\n    functions: { enabled: true },\n  },\n\n  cms: {\n    collections: {\n      reports: {\n        singular: 'report',\n        fields: {\n          // THE RESUME ANCHOR: a repeated start with the same key is a 409 that\n          // start-report reads back and resumes \u2014 never a second report\n          request_key: { type: 'string', required: true, unique: true, indexSlot: 's1' },\n          // splitting \u2192 running \u2192 done | partial\n          status: { type: 'string', indexSlot: 's2' },\n          // the input, kept so a resumed start fans out the SAME parts\n          numbers: { type: 'json' },\n          part_size: { type: 'int' },\n          parts_total: { type: 'int', indexSlot: 'n1' },\n          // written by finish-report\n          parts_done: { type: 'int' },\n          parts_failed: { type: 'int' },\n          total: { type: 'float' },\n          batch_id: { type: 'text' },\n          created_at: { type: 'datetime', indexSlot: 't1' },\n          completed_at: { type: 'datetime', indexSlot: 't2' },\n        },\n      },\n      report_parts: {\n        singular: 'report_part',\n        fields: {\n          // '<report item_id>:<index>' \u2014 a re-created part is a 409, so a\n          // resumed start never doubles a part\n          part_key: { type: 'string', required: true, unique: true, indexSlot: 's1' },\n          // the parent `reports` item_id: finish-report reads the parts by it\n          report: { type: 'string', required: true, indexSlot: 's2' },\n          // pending \u2192 done (a part whose job dead-lettered stays pending)\n          status: { type: 'string', indexSlot: 's3' },\n          index: { type: 'int', indexSlot: 'n1' },\n          numbers: { type: 'json' },\n          // written by compute-part\n          result: { type: 'float' },\n          attempt_key: { type: 'text' },\n        },\n      },\n    },\n  },\n\n  functions: {\n    // Starts (or resumes) ONE report. Invoke it with a server key:\n    //   vxil functions invoke start-report --data '{ \"request_key\": \"q3\", \"numbers\": [1,2,3,4,5], \"part_size\": 2 }'\n    'start-report': {\n      entry: './functions/start-report.ts',\n      trigger: { kind: 'http' },\n      scopes: ['cms:read', 'cms:write', 'jobs:write'],\n      egressAllow: [],\n      signature: {\n        input: { request_key: 'string', numbers: 'number[]', part_size: 'number | undefined' },\n        output:\n          '{ report_id: string; batch_id: string; parts: number; status: string; resumed?: boolean }',\n      },\n    },\n\n    // ONE part, delivered by the job start-report enqueued for it. A non-2xx\n    // answer is retried (up to 3 attempts); a part that still fails ends its\n    // run dead-lettered \u2014 counted in job.batch.completed, never a stuck batch.\n    'compute-part': {\n      entry: './functions/compute-part.ts',\n      trigger: { kind: 'queue', source: 'report-parts', retry: { maxAttempts: 3 } },\n      scopes: ['cms:read', 'cms:write'],\n      egressAllow: [],\n    },\n\n    // job.batch.completed \u2192 aggregate the parts and finish the report. The\n    // event is emitted once per batch; its delivery is at-least-once, so the\n    // finishing write is conditional (`if: { status: 'running' }`).\n    'finish-report': {\n      entry: './functions/finish-report.ts',\n      trigger: { kind: 'webhook', source: 'job.batch.', retry: { maxAttempts: 3 } },\n      scopes: ['cms:read', 'cms:write'],\n      egressAllow: [],\n    },\n  },\n});\n",
+    "readme": '# Fan-out / Fan-in\n\nSplit one request into many parts, run every part as its own background job\nwith retries, and aggregate **exactly once** when the last part has ended. The\npattern behind "summarise 300 documents, then write the report", "render 40\nthumbnails, then publish the album", or "price 500 items, then total the quote".\n\n```\nstart-report (http)                    compute-part (queue) \xD7N           finish-report (webhook)\n  reports row  \u2500\u2500\u25BA  N report_parts rows  \u2500\u2500\u25BA  one job per part  \u2500\u2500\u25BA  each writes its result\n                    one enqueue-batch with                         \u2502\n                    batch_id = report:<id>                         \u25BC\n                                              every part ended \u2192 job.batch.completed (once)\n                                                                   \u2502\n                                                                   \u25BC\n                                                   aggregate the rows, finish the report\n```\n\n**What it teaches that no other blueprint does:** the **batch** \u2014 a\n`batch_id` on enqueue that ties many runs together, and the one\n`job.batch.completed` event vxil emits when every run in it is terminal. There\nis no workflow engine and no "next step" run by the platform: the batch is a\ncounter and an event, and the aggregation is your own function.\n\n## Try it\n\n```bash\nvxil init --template fan-in my-fan-in && cd my-fan-in\nvxil push\nvxil functions invoke start-report --data \'{ "request_key": "q3-totals", "numbers": [1,2,3,4,5,6,7,8,9,10], "part_size": 3 }\'\n# 202 { "report_id": "itm_\u2026", "batch_id": "report:itm_\u2026", "parts": 4, "status": "running" }\n```\n\nA few seconds later the `reports` row reads `status: "done"`, `total: 55`,\n`parts_done: 4`. Watch the batch itself:\n\n```bash\nvxil api GET /v1/jobs/batches/report:itm_\u2026\n# { "state": "completed", "total": 4, "succeeded": 4, "dead_lettered": 0, "cancelled": 0,\n#   "runs_by_state": { "succeeded": 4 }, "event_emitted_at": "\u2026" }\nvxil api GET \'/v1/jobs/runs?batch_id=report:itm_\u2026\'\n```\n\n## How the pieces fit\n\n| Step | Where | What makes it safe to run twice |\n| --- | --- | --- |\n| Create or find the report | `start-report` | `request_key` is `unique`: a repeat is a `409` that is read back and **resumed** |\n| Write one row per part | `start-report` | `part_key` (`<report id>:<index>`) is `unique`: a repeat is a `409` |\n| Enqueue one job per part | `start-report` \u2192 `POST /v1/jobs/enqueue-batch` | each job\'s `idempotency_key` is `<batch_id>:<index>`: a repeat hands back the same run |\n| Compute one part | `compute-part` | a part already `done` answers at once; the result written is the same every time |\n| Aggregate once | `finish-report` on `job.batch.completed` | the finishing write is conditional (`if: { status: \'running\' }`): a redelivered event\'s write is a `409` |\n\n### The batch\n\n`start-report` enqueues every part with the same `batch_id` (`report:<item id>`)\nand declares `batch_total` \u2014 the number of parts. vxil counts the batch\'s runs\nin the same transaction that ends each one. When the last one ends \u2014\n**succeeded, dead-lettered (retries exhausted), expired or cancelled** \u2014 it\nwrites one `job.batch.completed`:\n\n```json\n{ "batch_id": "report:itm_\u2026", "total": 4, "succeeded": 4, "dead_lettered": 0, "cancelled": 0 }\n```\n\n- **Once per batch.** A completed batch takes no new runs (`409 batch_closed`);\n  replaying a part later creates a new run outside the batch, so the event is\n  never sent twice. Its *delivery* to your function is at-least-once, which is\n  why `finish-report` is re-entrant.\n- **Big fan-outs.** One enqueue-batch call takes 100 jobs; `start-report` sends\n  up to five calls (500 parts). `batch_total` keeps the batch open until the\n  last call has enqueued, so a fast first part can never complete the batch\n  early. A different `batch_total` on a later call is `409 batch_total_mismatch`.\n- **A part that never starts** (the project at its concurrency cap, a long\n  backlog) is ended after `ttl_seconds` (`PART_TTL_SECONDS`, one hour) as\n  `Expired` and counted in `dead_lettered` \u2014 the report finishes `partial`\n  instead of waiting forever.\n\n### Failure\n\n`compute-part` declares `retry: { maxAttempts: 3 }`: a non-2xx answer is tried\nagain with backoff, and a part that still fails ends its run dead-lettered. The\nbatch still completes; `finish-report` marks the report **`partial`** with\n`parts_failed`. To retry a failed part, replay its run (`vxil api POST\n/v1/jobs/runs/<run_id>/replay`) \u2014 the part row updates, but the report keeps\nthe result it was finished with; start a new report (a new `request_key`) for a\nfresh total.\n\n### Resuming\n\nCall `start-report` again with the same `request_key` after a lost answer or a\ncrash: it reads the **stored** input (a different `numbers` on the repeat is\nignored), writes only the missing part rows, re-sends the enqueue (a no-op for\nparts that already have a run), and answers `resumed: true`. A finished report\nanswers its final `status`.\n\n## Make it yours\n\n- **The work** is the one marked line in `functions/compute-part.ts`. Anything a\n  function can do fits: call an API, run a model, transform a file.\n- **The aggregate** is in `functions/finish-report.ts`; it reads results from the\n  part rows, never from events, so nothing is lost when a delivery repeats.\n- **Throughput:** the project\'s jobs concurrency setting and a\n  [flow rule](../../docs/guide/06-feature-catalog.md) bound how many parts run at\n  once \u2014 the fan-out queues, it never overloads a downstream API.\n- **Watching progress:** `GET /v1/jobs/batches/{batch_id}` gives open / succeeded\n  / dead-lettered counts while the batch runs; the dashboard\'s Jobs page lists\n  its runs (`?batch_id=`).\n\n## Limits\n\n| | |\n| --- | --- |\n| Parts per report (this blueprint) | 500 (`MAX_PARTS`) |\n| Jobs per enqueue-batch call | 100 |\n| Runs per batch | 100,000 |\n| `batch_id` | 1\u2013200 characters, `a-z A-Z 0-9 _ . : -` |\n| Part start deadline | 1 hour (`PART_TTL_SECONDS`, 60 s \u2013 31 days) |\n',
+    "functions": {
+      "compute-part.ts": "// compute-part.ts \u2014 ONE part of the fan-out (a vxil function, queue trigger).\n//\n// Delivered by the job start-report enqueued for this part; the envelope's\n// `payload` is { report_id, part_key }. The \"work\" here is a sum \u2014 replace it\n// with yours (an API call, a model call, a file to process). Keep the result\n// on the part's own row: finish-report aggregates from the rows, not from\n// events, so nothing is lost if a delivery is repeated.\n//\n// AT-LEAST-ONCE: the same part can be delivered again (a retry, a redelivery).\n// A part already `done` answers at once; otherwise the result is computed and\n// written \u2014 the same value every time, so a second write changes nothing.\n// A non-2xx answer is retried (the trigger declares `retry: { maxAttempts: 3 }`);\n// a part that keeps failing ends its run dead-lettered, and the batch still\n// completes \u2014 finish-report then marks the report `partial`.\n\nimport type { QueueFunctionEnvelope } from '@vxil/sdk';\n\ntype Payload = { report_id?: string; part_key?: string };\ntype PartRow = { item_id: string; data: { status?: string; numbers?: unknown } };\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as QueueFunctionEnvelope<Payload>;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n    const partKey = typeof env.payload?.part_key === 'string' ? env.payload.part_key : '';\n    // a malformed delivery can never succeed: acknowledge it (2xx) so it is not retried\n    if (!partKey) return Response.json({ skipped: 'no part_key' });\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n\n    const filter = encodeURIComponent(JSON.stringify({ part_key: partKey }));\n    const found = await fetch(`${base}/v1/cms/items/report_parts?filter=${filter}&limit=1`, { headers: H });\n    if (!found.ok) return Response.json({ error: `part read: ${found.status}` }, { status: 502 }); // another attempt (header note)\n    const part = ((await found.json()) as { data?: { items?: PartRow[] } }).data?.items?.[0];\n    if (!part) return Response.json({ skipped: 'part not found' });\n    if (part.data.status === 'done') return Response.json({ part_key: partKey, already: true });\n\n    const nums = Array.isArray(part.data.numbers) ? part.data.numbers.filter((n): n is number => typeof n === 'number') : [];\n    const result = nums.reduce((a, b) => a + b, 0); // \u2190 your work goes here\n\n    const patched = await fetch(`${base}/v1/cms/items/report_parts/${encodeURIComponent(part.item_id)}`, {\n      method: 'PATCH', headers: H,\n      body: JSON.stringify({ data: { status: 'done', result, attempt_key: env.idempotency_key } }),\n    });\n    if (!patched.ok) return Response.json({ error: `part write: ${patched.status}` }, { status: 502 }); // another attempt (header note)\n    return Response.json({ part_key: partKey, result });\n  },\n};\n",
+      "finish-report.ts": "// finish-report.ts \u2014 FAN-IN: job.batch.completed \u2192 aggregate the parts and\n// finish the report (a vxil function, webhook trigger on `job.batch.`).\n//\n// vxil emits job.batch.completed ONCE per batch, when every run in it has\n// ended: { batch_id, total, succeeded, dead_lettered, cancelled }. Its\n// DELIVERY is at-least-once (a retry after a non-2xx answer, a redelivery), so\n// this function is re-entrant: it reads the parts, computes the same answer\n// every time, and finishes the report with a CONDITIONAL write\n// (`if: { status: 'running' }`) \u2014 the second delivery's write is a 409 and\n// changes nothing.\n//\n// Batches that are not reports (another feature of your app using batch_id)\n// are skipped by their prefix.\n\nimport type { JobBatchCompletedEventPayload, WebhookFunctionEnvelope } from '@vxil/sdk';\n\ntype ReportRow = { data: { status?: string; parts_total?: number } };\ntype PartRow = { data: { status?: string; result?: number } };\n\n/** The parts read per page while aggregating. */\nconst PAGE = 100;\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as WebhookFunctionEnvelope<JobBatchCompletedEventPayload>;\n    const d = env.payload?.data;\n    if (!d || 'truncated' in d || typeof d.batch_id !== 'string') return Response.json({ skipped: true });\n    if (!d.batch_id.startsWith('report:')) return Response.json({ skipped: 'not a report batch' });\n    const reportId = d.batch_id.slice('report:'.length);\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n    const base = env.vxil_base;\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n    const reportUrl = `${base}/v1/cms/items/reports/${encodeURIComponent(reportId)}`;\n\n    const rep = await fetch(reportUrl, { headers: H });\n    if (rep.status === 404) return Response.json({ skipped: 'report gone' });\n    if (!rep.ok) return Response.json({ error: `report read: ${rep.status}` }, { status: 502 }); // another attempt (header note)\n    const report = ((await rep.json()) as { data: ReportRow }).data;\n    if (report.data.status !== 'running') return Response.json({ skipped: `report is ${report.data.status ?? 'unknown'}` });\n\n    // aggregate from the rows (the source of truth), page by page\n    let total = 0;\n    let done = 0;\n    let cursor: string | undefined;\n    const filter = encodeURIComponent(JSON.stringify({ report: reportId }));\n    for (;;) {\n      const page = await fetch(\n        `${base}/v1/cms/items/report_parts?filter=${filter}&limit=${PAGE}${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''}`,\n        { headers: H },\n      );\n      if (!page.ok) return Response.json({ error: `parts read: ${page.status}` }, { status: 502 }); // another attempt (header note)\n      const body = (await page.json()) as { data?: { items?: PartRow[]; next_cursor?: string | null } };\n      for (const p of body.data?.items ?? []) {\n        if (p.data.status === 'done' && typeof p.data.result === 'number') {\n          total += p.data.result;\n          done += 1;\n        }\n      }\n      cursor = body.data?.next_cursor ?? undefined;\n      if (!cursor) break;\n    }\n    const partsTotal = report.data.parts_total ?? d.total;\n    const failed = Math.max(0, partsTotal - done);\n\n    const finished = await fetch(reportUrl, {\n      method: 'PATCH', headers: H,\n      body: JSON.stringify({\n        data: {\n          status: failed === 0 ? 'done' : 'partial',\n          total, parts_done: done, parts_failed: failed, completed_at: new Date().toISOString(),\n        },\n        if: { status: 'running' },\n      }),\n    });\n    if (finished.status === 409) return Response.json({ skipped: 'already finished' });\n    if (!finished.ok) return Response.json({ error: `report write: ${finished.status}` }, { status: 502 }); // another attempt (header note)\n    return Response.json({\n      report_id: reportId, status: failed === 0 ? 'done' : 'partial', total, parts_done: done, parts_failed: failed,\n      runs: { succeeded: d.succeeded, dead_lettered: d.dead_lettered, cancelled: d.cancelled },\n    });\n  },\n};\n",
+      "start-report.ts": "// start-report.ts \u2014 FAN-OUT: split one request into parts and enqueue one job\n// per part, all in ONE batch (a vxil function, http trigger).\n//\n//   POST /v1/fn/start-report   (a server key, or `vxil functions invoke`)\n//   { \"request_key\": \"q3-totals\", \"numbers\": [1, 2, 3, \u2026], \"part_size\": 50 }\n//   \u2192 202 { report_id, batch_id, parts, status: 'running' }\n//   \u2192 200 { \u2026, resumed: true }     the same request_key again: the SAME report,\n//                                   resumed (missing parts written, their jobs\n//                                   enqueued again \u2014 a no-op for the ones that exist)\n//   \u2192 200 { \u2026, status: 'done' | 'partial' }   that report already finished\n//\n// Every step is safe to run twice (DELIVERY IS AT-LEAST-ONCE, and a caller\n// may retry after a lost answer):\n//   \u2022 the report row is unique on request_key \u2192 a repeat is a 409 we read back;\n//   \u2022 each part row is unique on part_key ('<report id>:<index>') \u2192 409 = exists;\n//   \u2022 each part's job carries idempotency_key '<batch_id>:<index>' \u2192 a repeat\n//     enqueue hands back the same run instead of starting a second one;\n//   \u2022 the batch declares batch_total = the number of parts, so it cannot\n//     complete before the last call of a 500-part fan-out has enqueued;\n//   \u2022 a resumed start re-reads the STORED input, so a repeat with different\n//     numbers can never change a report that is already running.\n// The report is marked `running` BEFORE the first enqueue, so finish-report\n// (which only finishes a running report) can never see the batch end first.\n\nimport type { HttpFunctionEnvelope } from '@vxil/sdk';\n\ntype Input = { request_key?: string; numbers?: unknown; part_size?: number };\ntype ReportRow = {\n  item_id: string;\n  data: { status?: string; numbers?: number[]; part_size?: number; parts_total?: number };\n};\n\n/** Parts per enqueue-batch call (the platform's per-call cap). */\nconst ENQUEUE_CHUNK = 100;\n/** The most parts one report may have (5 enqueue-batch calls). */\nconst MAX_PARTS = 500;\n/** The most numbers one request may carry. */\nconst MAX_NUMBERS = 5_000;\n/** A part not STARTED within this long is dead-lettered as Expired \u2014 counted\n *  as failed in the batch instead of holding the report open forever. */\nconst PART_TTL_SECONDS = 3_600;\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as HttpFunctionEnvelope<Input>;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const jobs = env.scoped_jwts?.jobs;\n    if (!cms || !jobs) return Response.json({ error: 'missing cms/jobs scope' }, { status: 403 });\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n\n    const requestKey = typeof env.payload?.request_key === 'string' ? env.payload.request_key.trim().slice(0, 120) : '';\n    const numbers = env.payload?.numbers;\n    const partSize = Number.isInteger(env.payload?.part_size) ? Number(env.payload!.part_size) : 50;\n    if (!requestKey || !Array.isArray(numbers) || numbers.length === 0 || numbers.length > MAX_NUMBERS\n        || !numbers.every((n) => typeof n === 'number' && Number.isFinite(n))) {\n      return Response.json({ error: `need { request_key, numbers: number[1..${MAX_NUMBERS}], part_size? }` }, { status: 422 });\n    }\n    if (partSize < 1 || Math.ceil(numbers.length / partSize) > MAX_PARTS) {\n      return Response.json({ error: `part_size must be >= 1 and give at most ${MAX_PARTS} parts` }, { status: 422 });\n    }\n\n    // 1. create-or-find the report\n    const created = await fetch(`${base}/v1/cms/items/reports`, {\n      method: 'POST', headers: H,\n      body: JSON.stringify({\n        data: {\n          request_key: requestKey, status: 'splitting', numbers, part_size: partSize,\n          parts_total: Math.ceil(numbers.length / partSize), created_at: new Date().toISOString(),\n        },\n      }),\n    });\n    let report: ReportRow;\n    let resumed = false;\n    if (created.status === 409) {\n      const filter = encodeURIComponent(JSON.stringify({ request_key: requestKey }));\n      const found = await fetch(`${base}/v1/cms/items/reports?filter=${filter}&limit=1`, { headers: H });\n      const row = found.ok ? ((await found.json()) as { data?: { items?: ReportRow[] } }).data?.items?.[0] : undefined;\n      if (!row) return Response.json({ error: `report lookup: ${found.status}` }, { status: 502 });\n      if (row.data.status === 'done' || row.data.status === 'partial') {\n        return Response.json({\n          report_id: row.item_id, batch_id: batchIdOf(row.item_id), parts: row.data.parts_total ?? 0, status: row.data.status,\n        });\n      }\n      report = row;\n      resumed = true;\n    } else if (created.ok) {\n      report = { item_id: ((await created.json()) as { data: { item_id: string } }).data.item_id, data: { numbers, part_size: partSize } };\n    } else {\n      return Response.json({ error: `report row: ${created.status}` }, { status: 502 });\n    }\n\n    // the STORED input decides the parts (a resumed start never re-splits differently)\n    const input = Array.isArray(report.data.numbers) ? report.data.numbers : numbers;\n    const size = Number.isInteger(report.data.part_size) ? Number(report.data.part_size) : partSize;\n    const parts: number[][] = [];\n    for (let i = 0; i < input.length; i += size) parts.push(input.slice(i, i + size));\n    const batchId = batchIdOf(report.item_id);\n\n    // 2. one part row per part (409 = written by an earlier attempt)\n    for (let i = 0; i < parts.length; i += 10) {\n      const results = await Promise.all(parts.slice(i, i + 10).map((nums, j) => fetch(`${base}/v1/cms/items/report_parts`, {\n        method: 'POST', headers: H,\n        body: JSON.stringify({\n          data: { part_key: `${report.item_id}:${i + j}`, report: report.item_id, index: i + j, numbers: nums, status: 'pending' },\n        }),\n      })));\n      const bad = results.find((r) => !r.ok && r.status !== 409);\n      if (bad) return Response.json({ error: `part row: ${bad.status}` }, { status: 502 });\n    }\n\n    // 3. mark the report running BEFORE any part can run (see the header note)\n    const mark = await fetch(`${base}/v1/cms/items/reports/${encodeURIComponent(report.item_id)}`, {\n      method: 'PATCH', headers: H,\n      body: JSON.stringify({ data: { status: 'running', batch_id: batchId }, if: { status: 'splitting' } }),\n    });\n    if (!mark.ok && mark.status !== 409) return Response.json({ error: `report mark: ${mark.status}` }, { status: 502 });\n\n    // 4. the fan-out: one job per part, all in ONE batch of a declared size.\n    //    The job is delivered into compute-part through the signed\n    //    function-trigger lane (no server of yours involved).\n    const target = `${base}/v1/internal/fn/trigger/compute-part?tenant=${encodeURIComponent(env.tenant_id)}`;\n    for (let i = 0; i < parts.length; i += ENQUEUE_CHUNK) {\n      const jobsBody = parts.slice(i, i + ENQUEUE_CHUNK).map((_, j) => ({\n        job_name: 'report.part',\n        target_url: target,\n        payload: { trigger: 'queue', payload: { report_id: report.item_id, part_key: `${report.item_id}:${i + j}` } },\n        idempotency_key: `${batchId}:${i + j}`,\n        ttl_seconds: PART_TTL_SECONDS,\n      }));\n      const enq = await fetch(`${base}/v1/jobs/enqueue-batch`, {\n        method: 'POST',\n        headers: { authorization: `Bearer ${jobs}`, 'content-type': 'application/json' },\n        body: JSON.stringify({ jobs: jobsBody, batch_id: batchId, batch_total: parts.length }),\n      });\n      if (enq.status === 409) {\n        // batch_closed: every part already ended (a resumed start after the\n        // fan-in) \u2014 finish-report owns the result from here\n        const code = ((await enq.json().catch(() => ({}))) as { error?: { code?: string } }).error?.code;\n        if (code === 'batch_closed') break;\n        return Response.json({ error: `enqueue: 409 ${code ?? ''}`.trim() }, { status: 502 });\n      }\n      if (!enq.ok) return Response.json({ error: `enqueue: ${enq.status}` }, { status: 502 });\n    }\n\n    return Response.json(\n      { report_id: report.item_id, batch_id: batchId, parts: parts.length, status: 'running', ...(resumed ? { resumed: true } : {}) },\n      { status: resumed ? 200 : 202 },\n    );\n  },\n};\n\n/** One batch per report \u2014 finish-report recognises its events by this prefix. */\nfunction batchIdOf(reportId: string): string {\n  return `report:${reportId}`;\n}\n"
+    }
+  },
   {
     "id": "research-library",
     "title": "Research Library",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/cli",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "private": false,
   "description": "The vxil CLI — init, quickstart, push, gen, secrets, keys, migrate, doctor, diff, functions, payments; installs the `vxil` command (npm i -g @vxil/cli).",
   "license": "MIT",
@@ -46,8 +46,8 @@
   },
   "devDependencies": {
     "miniflare": "^4.20260611.0",
-    "@vxil/config": "0.9.0",
-    "@vxil/feature-configs": "0.8.0",
+    "@vxil/config": "0.10.0",
+    "@vxil/feature-configs": "0.9.0",
     "@vxil/runtime": "0.0.1",
     "@vxil/types": "0.0.1"
   },