@vxil/cli 0.24.1 → 0.24.2

package/dist/vxil-main.js

@@ -5170,8 +5170,8 @@ function lowerAllTriggerBindings(def, name) {
 }
 var CONFIG_FILENAMES = ["vxil.config.ts", "vxil.config.mjs", "vxil.config.js"];
 var VXIL_CONFIG_PKG_VERSION = "0.17.0";
-var VXIL_SDK_PKG_VERSION = "0.24.0";
-var VXIL_CLI_PKG_VERSION = "0.24.1";
+var VXIL_SDK_PKG_VERSION = "0.24.1";
+var VXIL_CLI_PKG_VERSION = "0.24.2";
 function ensureScaffoldPackageJson(cwd, opts = {}) {
   const file = resolve(cwd, "package.json");
   const wanted = {
@@ -7951,18 +7951,18 @@ var PUBLIC_KEY_DENY_SCOPES = /* @__PURE__ */ new Set([
 var TENANT_SLUG_RE = /^[a-z0-9][a-z0-9-]{1,62}$/;
 var FUNCTION_SOURCE_MAX_BYTES = 512e3;
 var FN_PLATFORM_DEFAULT_CPU_MS = 3e4;
-function functionScriptCpuMs(declaredCpuMs, ceilingMs) {
+function functionScriptCpuMs(declaredCpuMs, ceilingMs, defaultMs = ceilingMs) {
   const d = typeof declaredCpuMs === "number" && Number.isFinite(declaredCpuMs) && declaredCpuMs >= 1 ? Math.floor(declaredCpuMs) : null;
-  return d === null ? ceilingMs : Math.min(d, ceilingMs);
+  return Math.min(d ?? defaultMs, ceilingMs);
 }
 function recordedScriptCpuMs(raw) {
   const c = raw?.cpuMs;
   return isPositiveInt(c) ? c : FN_PLATFORM_DEFAULT_CPU_MS;
 }
-function planScriptCpuMs(runtime, declaredCpuMs, ceilingMs) {
+function planScriptCpuMs(runtime, declaredCpuMs, ceilingMs, defaultMs = ceilingMs) {
   const recorded = runtime?.cpuMs;
   if (!isPositiveInt(recorded) && ceilingMs >= FN_PLATFORM_DEFAULT_CPU_MS) return FN_PLATFORM_DEFAULT_CPU_MS;
-  return functionScriptCpuMs(declaredCpuMs, ceilingMs);
+  return functionScriptCpuMs(declaredCpuMs, ceilingMs, defaultMs);
 }
 function isPositiveInt(v) {
   return typeof v === "number" && Number.isInteger(v) && v > 0;
@@ -8823,7 +8823,9 @@ async function readRemote(api) {
   const deployRuntime = wire ? recordedFunctionsRuntime(wire) : FUNCTIONS_RUNTIME_LEGACY;
   const ceilingWire = res.status === 200 ? res.body.data?.cpuMsCeiling : void 0;
   const cpuMsCeiling = typeof ceilingWire === "number" && Number.isInteger(ceilingWire) && ceilingWire > 0 ? ceilingWire : null;
-  if (res.status !== 200) return { map: map2, unavailable, deployRuntime, cpuMsCeiling };
+  const defaultWire = res.status === 200 ? res.body.data?.cpuMsDefault : void 0;
+  const cpuMsDefault = typeof defaultWire === "number" && Number.isInteger(defaultWire) && defaultWire > 0 ? defaultWire : null;
+  if (res.status !== 200) return { map: map2, unavailable, deployRuntime, cpuMsCeiling, cpuMsDefault };
   const fns = Array.isArray(res.body.data?.functions) ? res.body.data.functions : [];
   for (const f of fns) {
     map2.set(f.name, {
@@ -8838,7 +8840,7 @@ async function readRemote(api) {
       runtime: recordedFunctionsRuntime(f.runtime)
     });
   }
-  return { map: map2, unavailable: null, deployRuntime, cpuMsCeiling };
+  return { map: map2, unavailable: null, deployRuntime, cpuMsCeiling, cpuMsDefault };
 }
 function sameSecretSet(a, b2) {
   return a.length === b2.length && a.every((x) => b2.includes(x));
@@ -8877,7 +8879,7 @@ async function planFunctions({ api, functions, cwd, apply, onNote, remoteOnly =
     const sizeWarnings = headroom ? [{ fn: name, message: headroom }] : [];
     const retryN = bindings.find((b2) => b2.retry)?.retry?.maxAttempts;
     const label = `${name} (${Math.round(bytes / 100) / 10} KB) [${bindings.map((b2) => b2.kind).join("+")}${retryN !== void 0 ? " \xB7 retry:" + retryN : ""}${def.scopes?.length ? " \xB7 " + def.scopes.join(",") : ""}${secrets.length ? " \xB7 secrets:" + secrets.map((s) => s.slice("secret:".length)).join(",") : ""}${limits?.cpuMs !== void 0 ? " \xB7 cpu:" + limits.cpuMs + "ms" : ""}${limits?.timeoutMs !== void 0 ? " \xB7 egress:" + limits.timeoutMs + "ms" : ""}]`;
-    if (remoteFn !== void 0 && remoteFn.scriptRef.endsWith(`-${sha}`) && sameSecretSet(remoteFn.secrets, secrets) && sameFunctionsRuntime(remoteFn.runtime, read.deployRuntime) && (read.cpuMsCeiling === null || recordedScriptCpuMs(remoteFn.runtime) === planScriptCpuMs(remoteFn.runtime, limits?.cpuMs, read.cpuMsCeiling)) && sameStringSet2(clampFunctionScopes(def.scopes), remoteFn.scopes) && sameStringSet2(def.egressAllow ?? [], remoteFn.egressAllow) && stableStringify(remoteFn.bindings) === stableStringify(bindings) && stableStringify(remoteFn.signature) === stableStringify(def.signature ?? null) && stableStringify(remoteFn.limits ?? null) === stableStringify(limits ?? null) && stableStringify(remoteFn.vars) === stableStringify(def.vars ?? {}) && !force) {
+    if (remoteFn !== void 0 && remoteFn.scriptRef.endsWith(`-${sha}`) && sameSecretSet(remoteFn.secrets, secrets) && sameFunctionsRuntime(remoteFn.runtime, read.deployRuntime) && (read.cpuMsCeiling === null || recordedScriptCpuMs(remoteFn.runtime) === planScriptCpuMs(remoteFn.runtime, limits?.cpuMs, read.cpuMsCeiling, read.cpuMsDefault ?? read.cpuMsCeiling)) && sameStringSet2(clampFunctionScopes(def.scopes), remoteFn.scopes) && sameStringSet2(def.egressAllow ?? [], remoteFn.egressAllow) && stableStringify(remoteFn.bindings) === stableStringify(bindings) && stableStringify(remoteFn.signature) === stableStringify(def.signature ?? null) && stableStringify(remoteFn.limits ?? null) === stableStringify(limits ?? null) && stableStringify(remoteFn.vars) === stableStringify(def.vars ?? {}) && !force) {
       return { change: { name, kind: "unchanged", detail: label }, applied: 0, cmsHooks: null, webhooks: null, warnings: sizeWarnings, hook: null };
     }
     const bindingChanges = remoteFn !== void 0 ? diffBindings(remoteFn.bindings, bindings) : null;
@@ -13868,7 +13870,7 @@ var TOOLS = [
   {
     name: "functions_list",
     feature: "functions",
-    description: "The project's deployed functions: name, endpoint (/v1/fn/<name>), trigger bindings, scopes, limits and the runtime each runs under, plus `enabled` (false while the project's functions are paused as a whole \u2014 invokes then answer 404) and `cpuMsCeiling`. Each entry carries its plain `vars` only for a server key holding features:read or features:write (never for an end-user request). Read-only; any authenticated key may read it. Use it before functions_invoke or functions_logs to get the exact names.",
+    description: "The project's deployed functions: name, endpoint (/v1/fn/<name>), trigger bindings, scopes, limits and the runtime each runs under, plus `enabled` (false while the project's functions are paused as a whole \u2014 invokes then answer 404), `cpuMsCeiling` and `cpuMsDefault` (the CPU a function declaring no limits.cpuMs gets). Each entry carries its plain `vars` only for a server key holding features:read or features:write (never for an end-user request). Read-only; any authenticated key may read it. Use it before functions_invoke or functions_logs to get the exact names.",
     inputSchema: { type: "object", properties: {} },
     method: "GET",
     path: "/v1/functions"
@@ -15879,8 +15881,12 @@ function renderTryReport(result, opts) {
 
 // src/brief.ts
 var SITE = "https://vxil.com";
-function briefDocsUrl(docs) {
-  return docs.startsWith("/") ? `${SITE}${docs}` : docs;
+var STAGING_SITE = "https://staging.vxil.org";
+function briefSiteFor(edgeBase) {
+  return envLabelFor(edgeBase) === "production" ? SITE : STAGING_SITE;
+}
+function briefDocsUrl(docs, site = SITE) {
+  return docs.startsWith("/") ? `${site}${docs}` : docs;
 }
 function renderBriefLines(brief, opts = {}) {
   if (!brief) {
@@ -15903,7 +15909,7 @@ function renderBriefLines(brief, opts = {}) {
   }
   return out;
 }
-function renderBriefMarkdown(brief, app = {}) {
+function renderBriefMarkdown(brief, app = {}, opts = {}) {
   const name = (app.name ?? "").trim() || "Your app";
   if (!brief) {
     return [
@@ -15922,7 +15928,7 @@ function renderBriefMarkdown(brief, app = {}) {
   for (const s of brief.sections) {
     lines.push(`## ${s.title}`, "");
     for (const i of s.items) {
-      lines.push(`- **[${i.title}](${briefDocsUrl(i.docs)})** \u2014 ${i.fact}`);
+      lines.push(`- **[${i.title}](${briefDocsUrl(i.docs, opts.site)})** \u2014 ${i.fact}`);
       if (i.why) lines.push(`  _why:_ ${i.why}`);
       if (i.replaces) lines.push(`  _instead of:_ ${i.replaces}`);
     }
@@ -20266,7 +20272,7 @@ export default defineConfig({
     "functions": {
       "prune-receipts.ts": "// prune-receipts.ts \u2014 THE GARBAGE COLLECTOR (a vxil function, cron trigger).\n//\n// Trigger: cron `30 */6 * * *` (every 6 hours).\n//\n// A push service accepts a message and answers \"ok\" long before it knows whether\n// the device still exists. The real verdict arrives later, as a RECEIPT keyed by\n// the id the send returned. Almost nobody collects them, which is why push\n// registries only ever grow: dead tokens are re-sent to forever, quota is spent\n// on handsets that were wiped a year ago, and delivery rates look worse than\n// they are.\n//\n// This cron closes that loop:\n//   1. resume the walk of `push_tokens` where the previous tick stopped (the\n//      cursor lives in `push_state`), collecting rows that carry a `receipt_id`,\n//   2. ask the push service for those receipts, in batches,\n//   3. `DeviceNotRegistered` \u2192 DELETE the row (\u2605 invariant 3),\n//      any other error \u2192 count it and keep the device,\n//      ok \u2192 clear the receipt id; there is nothing left to check,\n//      no receipt and older than RECEIPT_MAX_AGE_H \u2192 clear it (the service no\n//      longer has it; asking forever would pin the row),\n//      Every clear is a PATCH with If-Match on the row version that was read:\n//      if `send-push` parked a NEWER receipt id on the device meanwhile, the\n//      clear is refused (409) and the newer id stays for the next walk,\n//   4. save the cursor \u2014 or '' when the walk reached the oldest row, so the\n//      next tick starts again from the newest.\n//\n// Everything is bounded: one tick reads at most MAX_ROWS rows and acts on at\n// most MAX_ACTIONS of them, so its outbound calls stay in the low hundreds.\n// Because the cursor persists, a registry of ANY size is walked end to end over\n// successive ticks \u2014 MAX_ROWS \xD7 4 ticks a day. (The walk follows the default\n// newest-first order; rows registered while a walk is in progress are covered\n// by the next walk.)\n\n// cron-walk: persisted-cursor \u2014 the walk's cursor lives in `push_state` and is saved with If-Match.\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\nconst RECEIPTS_URL = 'https://exp.host/--/api/v2/push/getReceipts';\n/** Receipt ids per request. */\nconst RECEIPT_BATCH = 300;\n/** Token rows examined per cron tick. */\nconst MAX_ROWS = 2000;\n/** Rows with a pending receipt acted on per tick (each costs one PATCH or DELETE). */\nconst MAX_ACTIONS = 300;\n/** A receipt id parked longer than this is cleared as unknowable. */\nconst RECEIPT_MAX_AGE_H = 48;\n/** cms page size \u2014 100 is the default `maxPageSize` for the cms feature. */\nconst PAGE = 100;\n/** This cron's row in `push_state`. */\nconst STATE_KEY = 'prune-receipts';\n\ntype Env = CronFunctionEnvelope;\ninterface TokenRow {\n  item_id: string;\n  version?: number;\n  data: { token?: string; receipt_id?: string; receipt_at?: string; failures?: number };\n}\ninterface Receipt { status?: string; message?: string; details?: { error?: string } }\ninterface StateRow { item_id: string; version?: number; data: { cursor?: string } }\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    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n\n    // \u2500\u2500 1. Resume the walk; collect pending receipts. \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    const state = await readState(base, H, STATE_KEY);\n    if (state === 'error') return Response.json({ error: 'state_read_failed' }, { status: 502 });\n    const startedAt = state?.data.cursor || null;\n    const pending = new Map<string, TokenRow>(); // receipt_id \u2192 row\n    let cursor: string | null = startedAt;\n    let scanned = 0;\n    let wrapped = false;\n    while (scanned < MAX_ROWS && pending.size < MAX_ACTIONS) {\n      // NOTE: no `sort=` here on purpose. In the DEFAULT order (newest first)\n      // a cursor is a plain item id, which is what we persist between ticks\n      // and resume `item_id <` from. Paging beats ordering here.\n      const url = `${base}/v1/cms/items/push_tokens?limit=${PAGE}`\n        + (cursor ? `&cursor=${encodeURIComponent(cursor)}` : '');\n      const res = await fetch(url, { headers: H });\n      if (!res.ok) return Response.json({ error: 'list_failed', status: res.status }, { status: 502 });\n      const body = (await res.json()) as { data?: { items?: TokenRow[]; next_cursor?: string | null } };\n      const items = body.data?.items ?? [];\n      let stoppedEarly = false;\n      for (const it of items) {\n        scanned++;\n        if (it.data.receipt_id) pending.set(it.data.receipt_id, it);\n        cursor = it.item_id; // resume AFTER the last row actually looked at\n        if (pending.size >= MAX_ACTIONS || scanned >= MAX_ROWS) { stoppedEarly = true; break; }\n      }\n      if (stoppedEarly) break;\n      if (!body.data?.next_cursor || items.length === 0) { wrapped = true; break; }\n      cursor = body.data.next_cursor;\n    }\n    // Reached the oldest row \u2192 the next tick starts again from the newest.\n    const nextCursor = wrapped ? '' : (cursor ?? '');\n\n    // \u2500\u2500 2 + 3. Ask for verdicts and act on them. \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    const ids = [...pending.keys()];\n    let checked = 0;\n    let pruned = 0;\n    let cleared = 0;\n    let expired = 0;\n    let raced = 0;\n    const errors: string[] = [];\n    const now = Date.now();\n\n    for (let i = 0; i < ids.length; i += RECEIPT_BATCH) {\n      const slice = ids.slice(i, i + RECEIPT_BATCH);\n      const res = await fetch(RECEIPTS_URL, {\n        method: 'POST',\n        headers: { 'content-type': 'application/json', accept: 'application/json' },\n        body: JSON.stringify({ ids: slice }),\n      }).catch(() => null);\n      if (!res || !res.ok) {\n        errors.push(`receipts request returned ${res?.status ?? 'network error'}`);\n        continue;\n      }\n      // Receipts come back keyed by id \u2014 a receipt that is not ready yet is\n      // simply ABSENT, which is not an error: it is checked again next walk.\n      const map = (((await res.json().catch(() => ({}))) as { data?: Record<string, Receipt> }).data) ?? {};\n      for (const id of slice) {\n        const receipt = map[id];\n        const row = pending.get(id)!;\n        if (!receipt) {\n          // Not ready \u2014 or no longer kept by the service. Past the age bound\n          // the id can never be answered: clear it so the row is not pinned.\n          const at = row.data.receipt_at ? Date.parse(row.data.receipt_at) : NaN;\n          if (Number.isFinite(at) && now - at > RECEIPT_MAX_AGE_H * 3_600_000) {\n            if (await patch(base, H, row, { receipt_id: '', checked_at: iso() })) expired++; else raced++;\n          }\n          continue;\n        }\n        checked++;\n        if (receipt.status === 'ok') {\n          // Delivered. Nothing more to check for this device.\n          if (await patch(base, H, row, { receipt_id: '', failures: 0, checked_at: iso() })) cleared++; else raced++;\n          continue;\n        }\n        const reason = receipt.details?.error ?? receipt.message ?? 'unknown';\n        if (reason === 'DeviceNotRegistered') {\n          // \u2605 INVARIANT 3. The device is gone \u2014 the row goes with it. This is\n          // also the ONLY safe automatic delete: every other error is transient\n          // or about the message, not about the device's existence.\n          await fetch(`${base}/v1/cms/items/push_tokens/${row.item_id}`, { method: 'DELETE', headers: H })\n            .catch(() => null);\n          pruned++;\n          continue;\n        }\n        if (!await patch(base, H, row, {\n          receipt_id: '',\n          failures: (row.data.failures ?? 0) + 1,\n          last_error: String(reason).slice(0, 300),\n          checked_at: iso(),\n        })) raced++;\n        errors.push(reason);\n      }\n    }\n\n    // \u2500\u2500 4. Save where the walk stopped (If-Match: a concurrent tick wins). \u2500\u2500\u2500\u2500\n    const saved = await writeState(base, H, STATE_KEY, state, nextCursor);\n\n    return Response.json({\n      scanned, pending: pending.size, checked, pruned, cleared, expired, raced,\n      resumed_from: startedAt, cursor: nextCursor, wrapped, saved, errors: errors.slice(0, 10),\n    });\n  },\n};\n\n/** Clear/record against the version that was READ. false = the row changed\n *  meanwhile (409: a newer receipt is parked \u2014 leave it) or the write failed. */\nasync function patch(base: string, H: Record<string, string>, row: TokenRow, data: Record<string, unknown>): Promise<boolean> {\n  const res = await fetch(`${base}/v1/cms/items/push_tokens/${row.item_id}`, {\n    method: 'PATCH',\n    headers: { ...H, ...(row.version !== undefined ? { 'if-match': String(row.version) } : {}) },\n    body: JSON.stringify({ data }),\n  }).catch(() => null);\n  return !!res && res.ok;\n}\n\n/** This cron's `push_state` row, null when it does not exist yet. */\nasync function readState(base: string, H: Record<string, string>, key: string): Promise<StateRow | null | 'error'> {\n  const filter = encodeURIComponent(JSON.stringify({ key }));\n  const res = await fetch(`${base}/v1/cms/items/push_state?filter=${filter}&limit=1`, { headers: H });\n  if (!res.ok) return 'error';\n  return ((await res.json()) as { data?: { items?: StateRow[] } }).data?.items?.[0] ?? null;\n}\n\n/** Persist the cursor. First tick creates the row (a racing tick's 409 on the\n *  unique `key` is fine \u2014 that tick saved its own); later ticks PATCH with\n *  If-Match so two overlapping ticks cannot both move it. */\nasync function writeState(\n  base: string, H: Record<string, string>, key: string, state: StateRow | null, cursor: string,\n): Promise<boolean> {\n  const data = { key, cursor, updated_at: iso() };\n  const res = state\n    ? await fetch(`${base}/v1/cms/items/push_state/${state.item_id}`, {\n      method: 'PATCH',\n      headers: { ...H, ...(state.version !== undefined ? { 'if-match': String(state.version) } : {}) },\n      body: JSON.stringify({ data }),\n    }).catch(() => null)\n    : await fetch(`${base}/v1/cms/items/push_state`, {\n      method: 'POST', headers: H, body: JSON.stringify({ status: 'published', data }),\n    }).catch(() => null);\n  return !!res && res.ok;\n}\n\nconst iso = () => new Date().toISOString();\n",
       "register-token.ts": "// register-token.ts \u2014 THE DEVICE REGISTRY (a vxil function with five bindings).\n//\n//   http     POST /v1/fn/register-token { token, user_id?, platform?, locale? }\n//   cmsHook  a new `push_token_claims` row (the app's async re-own request)\n//   webhook  `auth.user.erased` / `user.erased` / `user.deleted` (forget the user)\n//\n// One bundle, because all three are the same job: keeping \"which user holds\n// which device\" true. The envelope's `trigger` says which door was used.\n//\n// \u2500\u2500 http: register \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// Call it every time your app starts and every time the OS hands you a new push\n// token. It is idempotent, and it enforces the two registry invariants:\n//\n//   1. ONE TOKEN, ONE USER. `token` is declared `unique`, so the platform \u2014\n//      not this code \u2014 decides who wins a race. Two devices registering the\n//      same token at the same instant produce exactly one row; the loser sees\n//      409 `unique_violation`.\n//   2. RE-OWN ON CHANGE. A token that comes back under a DIFFERENT user is\n//      REASSIGNED, not duplicated. This is the case that matters: a resold\n//      phone, a shared tablet, a sign-out/sign-in on the same handset. Without\n//      it, the previous owner's notifications keep arriving on someone else's\n//      lock screen.\n//\n// IDENTITY. If the call carries a verified end-user session, `envelope.end_user`\n// is populated by the platform and THAT id wins \u2014 a body field can never\n// impersonate a signed-in user. In server mode (your backend, a server key)\n// there is no verified principal and `user_id` from the body is used.\n//\n// SERVER MODE re-owns immediately (a tenant-wide read finds the row whoever\n// owns it). END-USER MODE cannot see another user's row \u2014 the owner scope is\n// the fail-safe working \u2014 so the app's call files a CLAIM in\n// `push_token_claims` (owned by the caller) and answers 202\n// `{ action: 'reown_queued' }`; the cmsHook below finishes the move.\n//\n// \u2500\u2500 cmsHook: finish an async re-own \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// Runs in SERVER mode (a platform-delivered hook carries no end-user), so it can\n// read and move any row: re-read the claim, re-own (or create) the token row for\n// the claimant, delete the claim. At-least-once and re-delivered on failure\n// (`retry`), so every step is idempotent: a claim that is already gone is done.\n//\n// \u2500\u2500 webhook: erasure and deletion \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// `auth.user.erased { user_id }`, `user.erased { id }` and `user.deleted { id }`\n// (the admin delete without erase) delete every device row, pending claim and\n// the preferences row of that user \u2014 device tokens, time zone and activity are\n// personal data, and a deleted account must stop getting reminder nudges.\n// Deliberately NOT `auth.session.revoked`: that event fires on every\n// refresh-token rotation, not only on sign-out. A MERGE or REKEY\n// (`auth.user.merged` / `.rekeyed`, guest \u2192 registered) needs nothing here: the\n// app's next start registers its token under the new id, which re-owns it.\n\nimport type { CmsHookFunctionEnvelope, HttpFunctionEnvelope, WebhookFunctionEnvelope } from '@vxil/sdk';\n\ntype RegisterBody = { token?: string; user_id?: string; platform?: string; locale?: string };\ntype Env =\n  | HttpFunctionEnvelope<RegisterBody>\n  | CmsHookFunctionEnvelope\n  | WebhookFunctionEnvelope<{ user_id?: string; id?: string }>;\ninterface TokenRow { item_id: string; version?: number; data: { token?: string; end_user?: string } }\ninterface ClaimRow { item_id: string; data: { token?: string; end_user?: string; platform?: string; locale?: string } }\n\nconst PLATFORMS = new Set(['ios', 'android', 'web']);\n/** Rows deleted per erasure attempt \u2014 a person has a handful of devices; a\n *  bigger set is finished by the next attempt (each deletes the next pages). */\nconst ERASE_MAX = 200;\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    if (!cms) return json({ error: 'missing cms scope' }, 403);\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n\n    if (env.trigger === 'cms-hook') return finishClaim(base, H, env);\n    if (env.trigger === 'webhook') return forgetUser(base, H, env);\n    return register(base, H, env as HttpFunctionEnvelope<RegisterBody>);\n  },\n};\n\n// \u2500\u2500 http \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\nasync function register(base: string, H: Record<string, string>, env: HttpFunctionEnvelope<RegisterBody>): Promise<Response> {\n  const p = env.payload ?? {};\n  const token = typeof p.token === 'string' ? p.token.trim() : '';\n  // A VERIFIED principal always beats the body. Never trust a client-supplied\n  // user id when the platform has already told you who is calling.\n  const endUser = env.end_user?.id;\n  const owner = endUser ?? (typeof p.user_id === 'string' ? p.user_id.trim() : '');\n  if (!token) return json({ error: 'token is required' }, 400);\n  if (!owner) return json({ error: 'user_id is required (or invoke with an end-user session)' }, 400);\n  // The unique claim is capped at 256 chars; refuse early with a clear message\n  // rather than letting the write fail deep in the stack.\n  if (token.length > 256) return json({ error: 'token longer than 256 characters \u2014 store a hash instead' }, 400);\n\n  const data = tokenData(token, owner, p.platform, p.locale);\n\n  // \u2500\u2500 1. Try to create. The common case is one round-trip. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  const created = await fetch(`${base}/v1/cms/items/push_tokens`, {\n    method: 'POST', headers: H, body: JSON.stringify({ status: 'published', data }),\n  });\n  if (created.ok) {\n    const body = (await created.json()) as { data?: { item_id?: string } };\n    return json({ registered: true, action: 'created', item_id: body.data?.item_id }, 201);\n  }\n  if (created.status !== 409) return json({ error: 'register_failed', status: created.status }, 502);\n\n  // \u2500\u2500 2. 409 \u21D2 the token already exists. Find it and decide. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  // In SERVER mode this read is tenant-wide and finds the row whoever owns it.\n  // In end-user mode it is owner-scoped, so a row belonging to someone else is\n  // invisible \u2014 that is the fail-safe working as designed.\n  const row = await findToken(base, H, token);\n  if (row === 'error') return json({ error: 'lookup_failed' }, 502);\n  if (!row) {\n    if (!endUser) {\n      // Server mode sees every row, so \"exists but not found\" is a race with a\n      // concurrent delete. Retrying the call settles it.\n      return json({ registered: false, error: 'conflict', hint: 'retry the call' }, 409);\n    }\n    // \u2605 The async re-own. File a claim (owned by the caller \u2014 the platform\n    // stamps the verified owner); the server-mode cmsHook moves the token.\n    const claim = await fetch(`${base}/v1/cms/items/push_token_claims`, {\n      method: 'POST', headers: H,\n      body: JSON.stringify({ status: 'published', data: claimData(token, owner, p.platform, p.locale) }),\n    });\n    if (!claim.ok) return json({ error: 'claim_failed', status: claim.status }, 502);\n    const c = (await claim.json()) as { data?: { item_id?: string } };\n    return json({ registered: false, action: 'reown_queued', claim_id: c.data?.item_id }, 202);\n  }\n\n  const moved = await reown(base, H, row, data);\n  if (!moved.ok) {\n    // 409 version_conflict = a concurrent registration already moved it. The\n    // registry is still correct; the caller can simply retry.\n    return json({ registered: false, error: 'conflict', status: moved.status }, 409);\n  }\n  const previous = row.data.end_user;\n  return json({\n    registered: true,\n    action: previous && previous !== owner ? 'reowned' : 'refreshed',\n    item_id: row.item_id,\n    ...(previous && previous !== owner ? { previous_owner: previous } : {}),\n  }, 200);\n}\n\n// \u2500\u2500 cmsHook \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\nasync function finishClaim(base: string, H: Record<string, string>, env: CmsHookFunctionEnvelope): Promise<Response> {\n  const { collection, item_id: claimId } = env.payload ?? ({} as CmsHookFunctionEnvelope['payload']);\n  // The platform filters on the binding's collection; this guard is belt and braces.\n  if (collection !== 'push_token_claims' || !claimId) return json({ skipped: true }, 200);\n\n  const got = await fetch(`${base}/v1/cms/items/push_token_claims/${claimId}`, { headers: H });\n  if (got.status === 404) return json({ done: true, reason: 'claim already handled' }, 200);\n  if (!got.ok) return json({ error: 'claim_read_failed', status: got.status }, 502); // non-2xx \u2192 another attempt (maxAttempts: 3)\n  const claim = ((await got.json()) as { data?: ClaimRow }).data;\n  const token = claim?.data.token;\n  const owner = claim?.data.end_user;\n  if (!token || !owner) {\n    await deleteItem(base, H, 'push_token_claims', claimId);\n    return json({ done: true, reason: 'empty claim dropped' }, 200);\n  }\n\n  const data = tokenData(token, owner, claim.data.platform, claim.data.locale);\n  const row = await findToken(base, H, token);\n  if (row === 'error') return json({ error: 'lookup_failed' }, 502); // non-2xx \u2192 another attempt (maxAttempts: 3)\n  let action: string;\n  if (!row) {\n    // The holder deleted it in the meantime: the claimant simply registers it.\n    const created = await fetch(`${base}/v1/cms/items/push_tokens`, {\n      method: 'POST', headers: H, body: JSON.stringify({ status: 'published', data }),\n    });\n    // 409 = it was registered again concurrently; the next delivery re-reads.\n    if (!created.ok) return json({ error: 'create_failed', status: created.status }, 502);\n    action = 'created';\n  } else {\n    const moved = await reown(base, H, row, data);\n    if (!moved.ok) return json({ error: 'reown_failed', status: moved.status }, 502); // another attempt re-reads (maxAttempts: 3)\n    action = row.data.end_user === owner ? 'refreshed' : 'reowned';\n  }\n  await deleteItem(base, H, 'push_token_claims', claimId);\n  return json({ done: true, action, claim_id: claimId }, 200);\n}\n\n// \u2500\u2500 webhook \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\nasync function forgetUser(\n  base: string, H: Record<string, string>, env: WebhookFunctionEnvelope<{ user_id?: string; id?: string }>,\n): Promise<Response> {\n  const event = env.payload?.event;\n  const d = env.payload?.data;\n  const fields = d && !('truncated' in d) ? d : null;\n  // auth.user.erased carries `user_id`; the admin erase and delete carry `id`.\n  const userId = event === 'auth.user.erased' ? fields?.user_id\n    : event === 'user.erased' || event === 'user.deleted' ? fields?.id : undefined;\n  if (typeof userId !== 'string' || !userId) return json({ skipped: true, event }, 200);\n\n  let deleted = 0;\n  let failed = 0;\n  for (const coll of ['push_tokens', 'push_token_claims', 'push_prefs']) {\n    const filter = encodeURIComponent(JSON.stringify({ end_user: userId }));\n    while (deleted + failed < ERASE_MAX) {\n      // Always the FIRST page: what was deleted is gone, so the next read\n      // returns the next rows. A row that refuses to delete ends the loop.\n      const res = await fetch(`${base}/v1/cms/items/${coll}?filter=${filter}&limit=50`, { headers: H });\n      if (!res.ok) return json({ error: 'list_failed', status: res.status, deleted }, 502); // non-2xx \u2192 another attempt (maxAttempts: 3)\n      const items = ((await res.json()) as { data?: { items?: Array<{ item_id: string }> } }).data?.items ?? [];\n      if (items.length === 0) break;\n      let progress = 0;\n      for (const it of items) {\n        if (await deleteItem(base, H, coll, it.item_id)) { deleted++; progress++; } else failed++;\n      }\n      if (progress === 0) break;\n    }\n  }\n  // A failed delete \u2014 or a set larger than one attempt's ERASE_MAX \u2014 answers\n  // non-2xx: the binding declares maxAttempts: 3, so the jobs ladder hands it\n  // back for another attempt, which deletes the rest.\n  const unfinished = failed > 0 || deleted >= ERASE_MAX;\n  return json({ user_id: userId, deleted, failed, done: !unfinished }, unfinished ? 502 : 200);\n}\n\n// \u2500\u2500 helpers \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\nfunction tokenData(token: string, owner: string, platform: unknown, locale: unknown): Record<string, unknown> {\n  return {\n    token, end_user: owner, last_seen: new Date().toISOString(), failures: 0, last_error: '',\n    ...(typeof platform === 'string' && PLATFORMS.has(platform) ? { platform } : {}),\n    ...(typeof locale === 'string' && locale ? { locale: locale.slice(0, 16) } : {}),\n  };\n}\n\nfunction claimData(token: string, owner: string, platform: unknown, locale: unknown): Record<string, unknown> {\n  return {\n    token, end_user: owner,\n    ...(typeof platform === 'string' && PLATFORMS.has(platform) ? { platform } : {}),\n    ...(typeof locale === 'string' && locale ? { locale: locale.slice(0, 16) } : {}),\n  };\n}\n\nasync function findToken(base: string, H: Record<string, string>, token: string): Promise<TokenRow | null | 'error'> {\n  const filter = encodeURIComponent(JSON.stringify({ token }));\n  const found = await fetch(`${base}/v1/cms/items/push_tokens?filter=${filter}&limit=1`, { headers: H });\n  if (!found.ok) return 'error';\n  return ((await found.json()) as { data?: { items?: TokenRow[] } }).data?.items?.[0] ?? null;\n}\n\n/** \u2605 INVARIANT 2: re-own (or just refresh, when the owner is unchanged).\n *  If-Match makes the reassignment atomic against a concurrent registration. */\nfunction reown(base: string, H: Record<string, string>, row: TokenRow, data: Record<string, unknown>): Promise<Response> {\n  return fetch(`${base}/v1/cms/items/push_tokens/${row.item_id}`, {\n    method: 'PATCH',\n    headers: { ...H, ...(row.version !== undefined ? { 'if-match': String(row.version) } : {}) },\n    body: JSON.stringify({ data }),\n  });\n}\n\n/** true when the row is gone afterwards (a 404 counts: someone else deleted it). */\nasync function deleteItem(base: string, H: Record<string, string>, coll: string, itemId: string): Promise<boolean> {\n  const res = await fetch(`${base}/v1/cms/items/${coll}/${itemId}`, { method: 'DELETE', headers: H }).catch(() => null);\n  return !!res && (res.ok || res.status === 404);\n}\n\nconst json = (o: unknown, status: number) => Response.json(o, { status });\n",
-      "send-push.ts": "// send-push.ts \u2014 THE SENDER (a vxil function, two bindings).\n//\n//   http  POST /v1/fn/send-push \u2014 send now (below).\n//   cron  `0 * * * *` \u2014 THE REMINDER LADDER (further below).\n//\n// POST /v1/fn/send-push\n//   {\n//     \"user_ids\": [\"usr_a\", \"usr_b\"],\n//     \"messages\": {                       // keyed by locale; \"default\" is required\n//       \"default\": { \"title\": \"You're in\", \"body\": \"Pro is active on this device.\" },\n//       \"ar\":      { \"title\": \"\u062A\u0645 \u0627\u0644\u062A\u0641\u0639\u064A\u0644\", \"body\": \"\u0623\u0635\u0628\u062D \u0627\u0634\u062A\u0631\u0627\u0643 Pro \u0645\u0641\u0639\u0651\u0644\u0627\u064B.\" },\n//       \"fr\":      { \"title\": \"C'est actif\", \"body\": \"Pro est activ\xE9 sur cet appareil.\" }\n//     },\n//     \"data\": { \"screen\": \"billing\" }     // optional payload handed to your app\n//   }\n//\n// It resolves each user's live devices, picks the copy for THAT DEVICE'S locale\n// (captured at registration), and posts to the push service in batches.\n//\n// LOCALIZATION IS PER DEVICE, NOT PER USER. One person can carry an English\n// phone and an Arabic tablet. Because `locale` lives on the token row, the right\n// copy goes to each device with no extra lookup.\n//\n// Two failure kinds, handled differently:\n//   \u2022 an IMMEDIATE per-message error (`DeviceNotRegistered`) \u2014 the token is dead\n//     right now; delete the row.\n//   \u2022 an accepted message \u2014 the service returns a RECEIPT id, and the real\n//     verdict arrives later. Store the id (and when); `prune-receipts` collects it.\n//\n// \u2500\u2500 The reminder ladder (cron, hourly) \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// Re-engagement for users who stopped opening the app: one nudge after 1 day\n// of inactivity, one after 3, one after 7 \u2014 then silence until they come back.\n// Per user, from `push_prefs` (the app writes its own row):\n//   \u2022 `reminders: false` \u2192 never;\n//   \u2022 quiet hours [quiet_start, quiet_end) in the user's `timezone` \u2192 not now\n//     (the next hourly tick after the window sends it);\n//   \u2022 `last_active` + `ladder_step` decide the step; the APP resets\n//     `ladder_step` to 0 when it comes to the foreground.\n// ONE nudge per tick at most, and never a catch-up burst: when several rungs\n// are due at once (a user already idle for a week when the ladder first sees\n// them \u2014 the kit added to a live app, reminders turned back on, a held cron),\n// only the HIGHEST due rung is sent and the steps below it are skipped. And a\n// rung waits its own gap after the previous nudge (`last_reminded_at`), so\n// 1 d \u2192 3 d \u2192 7 d stay 2 and 4 days apart even when a step went out late.\n// Each step is CLAIMED with If-Match on the prefs row BEFORE the send, so two\n// overlapping ticks can never send it twice (a send that then fails is a\n// missed nudge, never a duplicate one). The walk only reads users inactive for\n// at least the first step and not yet through the ladder (`ladder_step` below\n// its length \u2014 a `derive` hook writes 0 when the app leaves it out), and\n// resumes where the last tick stopped (the cursor lives in `push_state`), so\n// it covers any number of users over successive ticks: MAX_LADDER_ROWS read and\n// MAX_REMINDERS sent per tick. A skipped tick is harmless \u2014 the next resumes.\n\n// Expo's push endpoint. For raw FCM: 'https://fcm.googleapis.com/v1/projects/<id>/messages:send'\n// (and an OAuth bearer). For APNs: 'https://api.push.apple.com/3/device/<token>'\n// (one request per device, a JWT `authorization`, and an `apns-topic` header).\n// Whichever you pick, its HOST must be in the function's `egressAllow`.\n\n// cron-walk: persisted-cursor \u2014 the ladder walk's cursor lives in `push_state` and is saved with If-Match.\n\nimport type { CronFunctionEnvelope, HttpFunctionEnvelope } from '@vxil/sdk';\n\nconst PUSH_URL = 'https://exp.host/--/api/v2/push/send';\n/** Expo accepts up to 100 messages in one request. */\nconst BATCH = 100;\n/** cms page size \u2014 100 is the default `maxPageSize` for the cms feature. */\nconst PAGE = 100;\n/** Devices resolved per invocation \u2014 a guardrail, not a limit of the platform. */\nconst MAX_DEVICES = 1000;\n\n/** The ladder: hours of inactivity \u2192 the nudge, per locale ('default' required).\n *  Edit the copy; keep the hours ascending. */\nconst LADDER: ReadonlyArray<{ afterHours: number; messages: Messages }> = [\n  { afterHours: 24, messages: {\n    default: { title: 'Pick up where you left off', body: 'Your streak is waiting for you.' },\n    ar: { title: '\u0623\u0643\u0645\u0644 \u0645\u0646 \u062D\u064A\u062B \u062A\u0648\u0642\u0641\u062A', body: '\u0633\u0644\u0633\u0644\u062A\u0643 \u0628\u0627\u0646\u062A\u0638\u0627\u0631\u0643.' },\n  } },\n  { afterHours: 72, messages: {\n    default: { title: 'We saved your progress', body: 'It only takes a minute to get back on track.' },\n    ar: { title: '\u062D\u0641\u0638\u0646\u0627 \u062A\u0642\u062F\u0645\u0643', body: '\u062F\u0642\u064A\u0642\u0629 \u0648\u0627\u062D\u062F\u0629 \u062A\u0643\u0641\u064A \u0644\u0644\u0639\u0648\u062F\u0629.' },\n  } },\n  { afterHours: 168, messages: {\n    default: { title: 'Still there?', body: 'Here is what you missed this week.' },\n    ar: { title: '\u0647\u0644 \u0645\u0627 \u0632\u0644\u062A \u0647\u0646\u0627\u061F', body: '\u0625\u0644\u064A\u0643 \u0645\u0627 \u0641\u0627\u062A\u0643 \u0647\u0630\u0627 \u0627\u0644\u0623\u0633\u0628\u0648\u0639.' },\n  } },\n];\n/** `push_prefs` rows read per tick. */\nconst MAX_LADDER_ROWS = 2000;\n/** Users nudged per tick (each costs a claim PATCH, a device read and receipt PATCHes). */\nconst MAX_REMINDERS = 100;\n/** This cron's row in `push_state`. */\nconst LADDER_STATE_KEY = 'reminder-ladder';\n\ntype Copy = { title?: string; body?: string };\ntype Messages = Record<string, Copy>;\ntype Env = CronFunctionEnvelope | HttpFunctionEnvelope<{\n  user_ids?: string[];\n  messages?: Messages;\n  data?: Record<string, unknown>;\n}>;\ninterface TokenRow {\n  item_id: string;\n  version?: number;\n  data: { token?: string; end_user?: string; locale?: string; failures?: number };\n}\n/** One entry of Expo's response array, positionally matched to the request. */\ninterface Ticket { status?: string; id?: string; message?: string; details?: { error?: string } }\ninterface PrefRow {\n  item_id: string;\n  version?: number;\n  data: {\n    end_user?: string; timezone?: string; reminders?: boolean; quiet_start?: number; quiet_end?: number;\n    last_active?: string; ladder_step?: number; last_reminded_at?: string;\n  };\n}\ninterface StateRow { item_id: string; version?: number; data: { cursor?: string } }\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    if (!cms) return json({ error: 'missing cms scope' }, 403);\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n    if (env.trigger === 'cron') return ladder(base, H);\n\n    const p = (env as Exclude<Env, CronFunctionEnvelope>).payload ?? {};\n    const userIds = Array.isArray(p.user_ids) ? p.user_ids.filter((u) => typeof u === 'string' && u) : [];\n    const messages = p.messages ?? {};\n    if (userIds.length === 0) return json({ error: 'user_ids is required' }, 400);\n    if (!messages.default?.title && !messages.default?.body) {\n      return json({ error: 'messages.default { title, body } is required' }, 400);\n    }\n    const devices = await resolveDevices(base, H, userIds);\n    if (devices.length === 0) return json({ sent: 0, devices: 0, note: 'no registered devices' }, 200);\n    const out = await sendTo(base, H, devices.map((d) => ({ device: d, messages })), p.data);\n    return json({ devices: devices.length, ...out }, 200);\n  },\n};\n\n/** \u2500\u2500 1. Resolve devices. One filtered read per user (owner-scoped by value,\n *  not by principal \u2014 this runs in server mode). */\nasync function resolveDevices(base: string, H: Record<string, string>, userIds: string[]): Promise<TokenRow[]> {\n  const devices: TokenRow[] = [];\n  for (const uid of userIds) {\n    if (devices.length >= MAX_DEVICES) break;\n    const filter = encodeURIComponent(JSON.stringify({ end_user: uid }));\n    const res = await fetch(`${base}/v1/cms/items/push_tokens?filter=${filter}&limit=50`, { headers: H });\n    if (!res.ok) continue;\n    const items = ((await res.json()) as { data?: { items?: TokenRow[] } }).data?.items ?? [];\n    for (const it of items) if (it.data.token) devices.push(it);\n  }\n  return devices;\n}\n\n/** \u2500\u2500 2 + 3. One message per device in that device's language; send in\n *  batches; reconcile each ticket back to its device by index. */\nasync function sendTo(\n  base: string, H: Record<string, string>,\n  targets: Array<{ device: TokenRow; messages: Messages }>, data?: Record<string, unknown>,\n): Promise<{ accepted: number; dropped: number; errors: string[] }> {\n  const outgoing = targets.map(({ device, messages }) => {\n    const copy = pick(messages, device.data.locale);\n    return {\n      to: device.data.token!,\n      ...(copy.title ? { title: copy.title } : {}),\n      ...(copy.body ? { body: copy.body } : {}),\n      ...(data ? { data } : {}),\n      sound: 'default',\n    };\n  });\n  let accepted = 0;\n  let dropped = 0;\n  const errors: string[] = [];\n  for (let i = 0; i < outgoing.length; i += BATCH) {\n    const slice = outgoing.slice(i, i + BATCH);\n    const res = await fetch(PUSH_URL, {\n      method: 'POST',\n      headers: { 'content-type': 'application/json', accept: 'application/json' },\n      body: JSON.stringify(slice),\n    }).catch(() => null);\n    if (!res || !res.ok) {\n      errors.push(`push service returned ${res?.status ?? 'network error'} for batch ${i / BATCH}`);\n      continue;\n    }\n    const tickets = (((await res.json().catch(() => ({}))) as { data?: Ticket[] }).data) ?? [];\n    for (let k = 0; k < slice.length; k++) {\n      const device = targets[i + k]!.device;\n      const ticket = tickets[k];\n      if (ticket?.status === 'ok' && ticket.id) {\n        // Accepted, verdict pending. Park the receipt id (and when) for prune-receipts.\n        accepted++;\n        await patch(base, H, device, { receipt_id: ticket.id, receipt_at: new Date().toISOString(), failures: 0, last_error: '' });\n        continue;\n      }\n      const reason = ticket?.details?.error ?? ticket?.message ?? 'unknown';\n      if (reason === 'DeviceNotRegistered') {\n        // Definitive: this token will never deliver again. \u2605 INVARIANT 3.\n        await del(base, H, device);\n        dropped++;\n        continue;\n      }\n      // Anything else (MessageTooBig, MessageRateExceeded, a transient fault)\n      // is NOT a reason to delete a device. Count it and move on.\n      await patch(base, H, device, {\n        failures: (device.data.failures ?? 0) + 1,\n        last_error: String(reason).slice(0, 300),\n      });\n      errors.push(reason);\n    }\n  }\n  return { accepted, dropped, errors: errors.slice(0, 10) };\n}\n\n// \u2500\u2500 The reminder ladder \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\nasync function ladder(base: string, H: Record<string, string>): Promise<Response> {\n  const now = new Date();\n  const state = await readState(base, H, LADDER_STATE_KEY);\n  if (state === 'error') return json({ error: 'state_read_failed' }, 502);\n  const startedAt = state?.data.cursor || null;\n  // Only users idle for at least the first step, with a rung still ahead of\n  // them, can be due: both terms ride slot indexes (`last_active` t1,\n  // `ladder_step` n1), so active users and finished ladders are never read.\n  const idleSince = new Date(now.getTime() - LADDER[0]!.afterHours * 3_600_000).toISOString();\n  const filter = encodeURIComponent(JSON.stringify({\n    last_active: { $lt: idleSince }, ladder_step: { $lt: LADDER.length },\n  }));\n\n  const due: Array<{ row: PrefRow; step: number }> = [];\n  let cursor: string | null = startedAt;\n  let scanned = 0;\n  let wrapped = false;\n  let quiet = 0;\n  scan: while (scanned < MAX_LADDER_ROWS) {\n    const res = await fetch(`${base}/v1/cms/items/push_prefs?filter=${filter}&limit=${PAGE}`\n      + (cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''), { headers: H });\n    if (!res.ok) return json({ error: 'list_failed', status: res.status }, 502);\n    const body = (await res.json()) as { data?: { items?: PrefRow[]; next_cursor?: string | null } };\n    const items = body.data?.items ?? [];\n    for (const it of items) {\n      scanned++;\n      cursor = it.item_id;\n      const step = dueStep(it.data, now);\n      if (step !== null) {\n        if (inQuietHours(it.data, now)) quiet++; // left for a later tick: the cursor wraps back to it\n        else due.push({ row: it, step });\n      }\n      if (due.length >= MAX_REMINDERS || scanned >= MAX_LADDER_ROWS) break scan;\n    }\n    if (!body.data?.next_cursor || items.length === 0) { wrapped = true; break; }\n    cursor = body.data.next_cursor;\n  }\n  const nextCursor = wrapped ? '' : (cursor ?? '');\n\n  // Claim each step FIRST (If-Match): a concurrent tick that claimed it wins,\n  // and this one skips the user \u2014 never a double nudge.\n  const targets: Array<{ device: TokenRow; messages: Messages }> = [];\n  let claimed = 0;\n  for (const { row, step } of due) {\n    const res = await fetch(`${base}/v1/cms/items/push_prefs/${row.item_id}`, {\n      method: 'PATCH',\n      headers: { ...H, ...(row.version !== undefined ? { 'if-match': String(row.version) } : {}) },\n      body: JSON.stringify({ data: { ladder_step: step + 1, last_reminded_at: now.toISOString() } }),\n    }).catch(() => null);\n    if (!res || !res.ok) continue;\n    claimed++;\n    for (const device of await resolveDevices(base, H, [row.data.end_user!])) {\n      targets.push({ device, messages: LADDER[step]!.messages });\n    }\n  }\n  const sent = targets.length > 0\n    ? await sendTo(base, H, targets, { reason: 'reminder' })\n    : { accepted: 0, dropped: 0, errors: [] as string[] };\n  const saved = await writeState(base, H, LADDER_STATE_KEY, state, nextCursor);\n  return json({\n    ladder: true, scanned, due: due.length, quiet, claimed, devices: targets.length, ...sent,\n    resumed_from: startedAt, cursor: nextCursor, wrapped, saved,\n  }, 200);\n}\n\n/** The ladder step due for this user now, or null. Exported for tests.\n *  The HIGHEST rung whose idle threshold is met (the claim then moves\n *  `ladder_step` past it, so the rungs below are skipped, never sent late), and\n *  only once that rung's gap since the previous nudge has passed. */\nexport function dueStep(p: PrefRow['data'], now: Date): number | null {\n  if (p.reminders === false || !p.end_user || !p.last_active) return null;\n  const idleH = (now.getTime() - Date.parse(p.last_active)) / 3_600_000;\n  if (!Number.isFinite(idleH)) return null;\n  const from = Math.max(0, Math.trunc(p.ladder_step ?? 0));\n  let step: number | null = null;\n  for (let r = from; r < LADDER.length; r++) if (idleH >= LADDER[r]!.afterHours) step = r;\n  if (step === null) return null;\n  if (step > 0 && p.last_reminded_at) {\n    const sinceH = (now.getTime() - Date.parse(p.last_reminded_at)) / 3_600_000;\n    const gapH = LADDER[step]!.afterHours - LADDER[step - 1]!.afterHours;\n    if (Number.isFinite(sinceH) && sinceH < gapH) return null;\n  }\n  return step;\n}\n\n/** Is it inside the user's quiet hours [quiet_start, quiet_end) in THEIR zone?\n *  The window may wrap midnight; equal or missing bounds mean none. An unknown\n *  zone is evaluated in UTC. Exported for tests. */\nexport function inQuietHours(p: PrefRow['data'], now: Date): boolean {\n  const start = p.quiet_start;\n  const end = p.quiet_end;\n  if (typeof start !== 'number' || typeof end !== 'number' || start === end) return false;\n  const h = localHour(now, p.timezone);\n  return start < end ? h >= start && h < end : h >= start || h < end;\n}\n\n/** One formatter per zone, kept for the isolate's life: building an Intl formatter is the\n *  expensive part, and a tick can test hundreds of users in the same few zones\n *  (CPU per invocation is capped \u2014 2,000 ms on a Free staging/development project, 50 ms on a Free dev slot). */\nconst ZONE_FMT = new Map<string, Intl.DateTimeFormat | null>();\nfunction zoneFormatter(tz: string): Intl.DateTimeFormat | null {\n  if (!ZONE_FMT.has(tz)) {\n    let f: Intl.DateTimeFormat | null = null;\n    try { f = new Intl.DateTimeFormat('en-US', { timeZone: tz, hour: 'numeric', hourCycle: 'h23' }); } catch { /* unknown zone */ }\n    if (ZONE_FMT.size < 500) ZONE_FMT.set(tz, f);\n    return f;\n  }\n  return ZONE_FMT.get(tz)!;\n}\n\nfunction localHour(now: Date, tz: string | undefined): number {\n  try {\n    const part = zoneFormatter(tz || 'UTC')?.formatToParts(now).find((x) => x.type === 'hour');\n    const h = Number(part?.value);\n    if (Number.isInteger(h)) return h % 24;\n  } catch { /* unknown zone \u2192 UTC below */ }\n  return now.getUTCHours();\n}\n\nasync function readState(base: string, H: Record<string, string>, key: string): Promise<StateRow | null | 'error'> {\n  const filter = encodeURIComponent(JSON.stringify({ key }));\n  const res = await fetch(`${base}/v1/cms/items/push_state?filter=${filter}&limit=1`, { headers: H });\n  if (!res.ok) return 'error';\n  return ((await res.json()) as { data?: { items?: StateRow[] } }).data?.items?.[0] ?? null;\n}\n\nasync function writeState(\n  base: string, H: Record<string, string>, key: string, state: StateRow | null, cursor: string,\n): Promise<boolean> {\n  const data = { key, cursor, updated_at: new Date().toISOString() };\n  const res = state\n    ? await fetch(`${base}/v1/cms/items/push_state/${state.item_id}`, {\n      method: 'PATCH',\n      headers: { ...H, ...(state.version !== undefined ? { 'if-match': String(state.version) } : {}) },\n      body: JSON.stringify({ data }),\n    }).catch(() => null)\n    : await fetch(`${base}/v1/cms/items/push_state`, {\n      method: 'POST', headers: H, body: JSON.stringify({ status: 'published', data }),\n    }).catch(() => null);\n  return !!res && res.ok;\n}\n\n/** Locale match: exact ('pt-BR'), then the base language ('pt'), then default. */\nfunction pick(messages: Messages, locale: string | undefined): Copy {\n  if (locale) {\n    if (messages[locale]) return messages[locale]!;\n    const bare = locale.split('-')[0]!;\n    if (messages[bare]) return messages[bare]!;\n  }\n  return messages.default ?? {};\n}\n\nasync function patch(base: string, H: Record<string, string>, d: TokenRow, data: Record<string, unknown>) {\n  await fetch(`${base}/v1/cms/items/push_tokens/${d.item_id}`, {\n    method: 'PATCH', headers: H, body: JSON.stringify({ data }),\n  }).catch(() => null);\n}\nasync function del(base: string, H: Record<string, string>, d: TokenRow) {\n  await fetch(`${base}/v1/cms/items/push_tokens/${d.item_id}`, { method: 'DELETE', headers: H }).catch(() => null);\n}\nconst json = (o: unknown, status: number) => Response.json(o, { status });\n"
+      "send-push.ts": "// send-push.ts \u2014 THE SENDER (a vxil function, two bindings).\n//\n//   http  POST /v1/fn/send-push \u2014 send now (below).\n//   cron  `0 * * * *` \u2014 THE REMINDER LADDER (further below).\n//\n// POST /v1/fn/send-push\n//   {\n//     \"user_ids\": [\"usr_a\", \"usr_b\"],\n//     \"messages\": {                       // keyed by locale; \"default\" is required\n//       \"default\": { \"title\": \"You're in\", \"body\": \"Pro is active on this device.\" },\n//       \"ar\":      { \"title\": \"\u062A\u0645 \u0627\u0644\u062A\u0641\u0639\u064A\u0644\", \"body\": \"\u0623\u0635\u0628\u062D \u0627\u0634\u062A\u0631\u0627\u0643 Pro \u0645\u0641\u0639\u0651\u0644\u0627\u064B.\" },\n//       \"fr\":      { \"title\": \"C'est actif\", \"body\": \"Pro est activ\xE9 sur cet appareil.\" }\n//     },\n//     \"data\": { \"screen\": \"billing\" }     // optional payload handed to your app\n//   }\n//\n// It resolves each user's live devices, picks the copy for THAT DEVICE'S locale\n// (captured at registration), and posts to the push service in batches.\n//\n// LOCALIZATION IS PER DEVICE, NOT PER USER. One person can carry an English\n// phone and an Arabic tablet. Because `locale` lives on the token row, the right\n// copy goes to each device with no extra lookup.\n//\n// Two failure kinds, handled differently:\n//   \u2022 an IMMEDIATE per-message error (`DeviceNotRegistered`) \u2014 the token is dead\n//     right now; delete the row.\n//   \u2022 an accepted message \u2014 the service returns a RECEIPT id, and the real\n//     verdict arrives later. Store the id (and when); `prune-receipts` collects it.\n//\n// \u2500\u2500 The reminder ladder (cron, hourly) \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// Re-engagement for users who stopped opening the app: one nudge after 1 day\n// of inactivity, one after 3, one after 7 \u2014 then silence until they come back.\n// Per user, from `push_prefs` (the app writes its own row):\n//   \u2022 `reminders: false` \u2192 never;\n//   \u2022 quiet hours [quiet_start, quiet_end) in the user's `timezone` \u2192 not now\n//     (the next hourly tick after the window sends it);\n//   \u2022 `last_active` + `ladder_step` decide the step; the APP resets\n//     `ladder_step` to 0 when it comes to the foreground.\n// ONE nudge per tick at most, and never a catch-up burst: when several rungs\n// are due at once (a user already idle for a week when the ladder first sees\n// them \u2014 the kit added to a live app, reminders turned back on, a held cron),\n// only the HIGHEST due rung is sent and the steps below it are skipped. And a\n// rung waits its own gap after the previous nudge (`last_reminded_at`), so\n// 1 d \u2192 3 d \u2192 7 d stay 2 and 4 days apart even when a step went out late.\n// Each step is CLAIMED with If-Match on the prefs row BEFORE the send, so two\n// overlapping ticks can never send it twice (a send that then fails is a\n// missed nudge, never a duplicate one). The walk only reads users inactive for\n// at least the first step and not yet through the ladder (`ladder_step` below\n// its length \u2014 a `derive` hook writes 0 when the app leaves it out), and\n// resumes where the last tick stopped (the cursor lives in `push_state`), so\n// it covers any number of users over successive ticks: MAX_LADDER_ROWS read and\n// MAX_REMINDERS sent per tick. A skipped tick is harmless \u2014 the next resumes.\n\n// Expo's push endpoint. For raw FCM: 'https://fcm.googleapis.com/v1/projects/<id>/messages:send'\n// (and an OAuth bearer). For APNs: 'https://api.push.apple.com/3/device/<token>'\n// (one request per device, a JWT `authorization`, and an `apns-topic` header).\n// Whichever you pick, its HOST must be in the function's `egressAllow`.\n\n// cron-walk: persisted-cursor \u2014 the ladder walk's cursor lives in `push_state` and is saved with If-Match.\n\nimport type { CronFunctionEnvelope, HttpFunctionEnvelope } from '@vxil/sdk';\n\nconst PUSH_URL = 'https://exp.host/--/api/v2/push/send';\n/** Expo accepts up to 100 messages in one request. */\nconst BATCH = 100;\n/** cms page size \u2014 100 is the default `maxPageSize` for the cms feature. */\nconst PAGE = 100;\n/** Devices resolved per invocation \u2014 a guardrail, not a limit of the platform. */\nconst MAX_DEVICES = 1000;\n\n/** The ladder: hours of inactivity \u2192 the nudge, per locale ('default' required).\n *  Edit the copy; keep the hours ascending. */\nconst LADDER: ReadonlyArray<{ afterHours: number; messages: Messages }> = [\n  { afterHours: 24, messages: {\n    default: { title: 'Pick up where you left off', body: 'Your streak is waiting for you.' },\n    ar: { title: '\u0623\u0643\u0645\u0644 \u0645\u0646 \u062D\u064A\u062B \u062A\u0648\u0642\u0641\u062A', body: '\u0633\u0644\u0633\u0644\u062A\u0643 \u0628\u0627\u0646\u062A\u0638\u0627\u0631\u0643.' },\n  } },\n  { afterHours: 72, messages: {\n    default: { title: 'We saved your progress', body: 'It only takes a minute to get back on track.' },\n    ar: { title: '\u062D\u0641\u0638\u0646\u0627 \u062A\u0642\u062F\u0645\u0643', body: '\u062F\u0642\u064A\u0642\u0629 \u0648\u0627\u062D\u062F\u0629 \u062A\u0643\u0641\u064A \u0644\u0644\u0639\u0648\u062F\u0629.' },\n  } },\n  { afterHours: 168, messages: {\n    default: { title: 'Still there?', body: 'Here is what you missed this week.' },\n    ar: { title: '\u0647\u0644 \u0645\u0627 \u0632\u0644\u062A \u0647\u0646\u0627\u061F', body: '\u0625\u0644\u064A\u0643 \u0645\u0627 \u0641\u0627\u062A\u0643 \u0647\u0630\u0627 \u0627\u0644\u0623\u0633\u0628\u0648\u0639.' },\n  } },\n];\n/** `push_prefs` rows read per tick. */\nconst MAX_LADDER_ROWS = 2000;\n/** Users nudged per tick (each costs a claim PATCH, a device read and receipt PATCHes). */\nconst MAX_REMINDERS = 100;\n/** This cron's row in `push_state`. */\nconst LADDER_STATE_KEY = 'reminder-ladder';\n\ntype Copy = { title?: string; body?: string };\ntype Messages = Record<string, Copy>;\ntype Env = CronFunctionEnvelope | HttpFunctionEnvelope<{\n  user_ids?: string[];\n  messages?: Messages;\n  data?: Record<string, unknown>;\n}>;\ninterface TokenRow {\n  item_id: string;\n  version?: number;\n  data: { token?: string; end_user?: string; locale?: string; failures?: number };\n}\n/** One entry of Expo's response array, positionally matched to the request. */\ninterface Ticket { status?: string; id?: string; message?: string; details?: { error?: string } }\ninterface PrefRow {\n  item_id: string;\n  version?: number;\n  data: {\n    end_user?: string; timezone?: string; reminders?: boolean; quiet_start?: number; quiet_end?: number;\n    last_active?: string; ladder_step?: number; last_reminded_at?: string;\n  };\n}\ninterface StateRow { item_id: string; version?: number; data: { cursor?: string } }\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    if (!cms) return json({ error: 'missing cms scope' }, 403);\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n    if (env.trigger === 'cron') return ladder(base, H);\n\n    const p = (env as Exclude<Env, CronFunctionEnvelope>).payload ?? {};\n    const userIds = Array.isArray(p.user_ids) ? p.user_ids.filter((u) => typeof u === 'string' && u) : [];\n    const messages = p.messages ?? {};\n    if (userIds.length === 0) return json({ error: 'user_ids is required' }, 400);\n    if (!messages.default?.title && !messages.default?.body) {\n      return json({ error: 'messages.default { title, body } is required' }, 400);\n    }\n    const devices = await resolveDevices(base, H, userIds);\n    if (devices.length === 0) return json({ sent: 0, devices: 0, note: 'no registered devices' }, 200);\n    const out = await sendTo(base, H, devices.map((d) => ({ device: d, messages })), p.data);\n    return json({ devices: devices.length, ...out }, 200);\n  },\n};\n\n/** \u2500\u2500 1. Resolve devices. One filtered read per user (owner-scoped by value,\n *  not by principal \u2014 this runs in server mode). */\nasync function resolveDevices(base: string, H: Record<string, string>, userIds: string[]): Promise<TokenRow[]> {\n  const devices: TokenRow[] = [];\n  for (const uid of userIds) {\n    if (devices.length >= MAX_DEVICES) break;\n    const filter = encodeURIComponent(JSON.stringify({ end_user: uid }));\n    const res = await fetch(`${base}/v1/cms/items/push_tokens?filter=${filter}&limit=50`, { headers: H });\n    if (!res.ok) continue;\n    const items = ((await res.json()) as { data?: { items?: TokenRow[] } }).data?.items ?? [];\n    for (const it of items) if (it.data.token) devices.push(it);\n  }\n  return devices;\n}\n\n/** \u2500\u2500 2 + 3. One message per device in that device's language; send in\n *  batches; reconcile each ticket back to its device by index. */\nasync function sendTo(\n  base: string, H: Record<string, string>,\n  targets: Array<{ device: TokenRow; messages: Messages }>, data?: Record<string, unknown>,\n): Promise<{ accepted: number; dropped: number; errors: string[] }> {\n  const outgoing = targets.map(({ device, messages }) => {\n    const copy = pick(messages, device.data.locale);\n    return {\n      to: device.data.token!,\n      ...(copy.title ? { title: copy.title } : {}),\n      ...(copy.body ? { body: copy.body } : {}),\n      ...(data ? { data } : {}),\n      sound: 'default',\n    };\n  });\n  let accepted = 0;\n  let dropped = 0;\n  const errors: string[] = [];\n  for (let i = 0; i < outgoing.length; i += BATCH) {\n    const slice = outgoing.slice(i, i + BATCH);\n    const res = await fetch(PUSH_URL, {\n      method: 'POST',\n      headers: { 'content-type': 'application/json', accept: 'application/json' },\n      body: JSON.stringify(slice),\n    }).catch(() => null);\n    if (!res || !res.ok) {\n      errors.push(`push service returned ${res?.status ?? 'network error'} for batch ${i / BATCH}`);\n      continue;\n    }\n    const tickets = (((await res.json().catch(() => ({}))) as { data?: Ticket[] }).data) ?? [];\n    for (let k = 0; k < slice.length; k++) {\n      const device = targets[i + k]!.device;\n      const ticket = tickets[k];\n      if (ticket?.status === 'ok' && ticket.id) {\n        // Accepted, verdict pending. Park the receipt id (and when) for prune-receipts.\n        accepted++;\n        await patch(base, H, device, { receipt_id: ticket.id, receipt_at: new Date().toISOString(), failures: 0, last_error: '' });\n        continue;\n      }\n      const reason = ticket?.details?.error ?? ticket?.message ?? 'unknown';\n      if (reason === 'DeviceNotRegistered') {\n        // Definitive: this token will never deliver again. \u2605 INVARIANT 3.\n        await del(base, H, device);\n        dropped++;\n        continue;\n      }\n      // Anything else (MessageTooBig, MessageRateExceeded, a transient fault)\n      // is NOT a reason to delete a device. Count it and move on.\n      await patch(base, H, device, {\n        failures: (device.data.failures ?? 0) + 1,\n        last_error: String(reason).slice(0, 300),\n      });\n      errors.push(reason);\n    }\n  }\n  return { accepted, dropped, errors: errors.slice(0, 10) };\n}\n\n// \u2500\u2500 The reminder ladder \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\nasync function ladder(base: string, H: Record<string, string>): Promise<Response> {\n  const now = new Date();\n  const state = await readState(base, H, LADDER_STATE_KEY);\n  if (state === 'error') return json({ error: 'state_read_failed' }, 502);\n  const startedAt = state?.data.cursor || null;\n  // Only users idle for at least the first step, with a rung still ahead of\n  // them, can be due: both terms ride slot indexes (`last_active` t1,\n  // `ladder_step` n1), so active users and finished ladders are never read.\n  const idleSince = new Date(now.getTime() - LADDER[0]!.afterHours * 3_600_000).toISOString();\n  const filter = encodeURIComponent(JSON.stringify({\n    last_active: { $lt: idleSince }, ladder_step: { $lt: LADDER.length },\n  }));\n\n  const due: Array<{ row: PrefRow; step: number }> = [];\n  let cursor: string | null = startedAt;\n  let scanned = 0;\n  let wrapped = false;\n  let quiet = 0;\n  scan: while (scanned < MAX_LADDER_ROWS) {\n    const res = await fetch(`${base}/v1/cms/items/push_prefs?filter=${filter}&limit=${PAGE}`\n      + (cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''), { headers: H });\n    if (!res.ok) return json({ error: 'list_failed', status: res.status }, 502);\n    const body = (await res.json()) as { data?: { items?: PrefRow[]; next_cursor?: string | null } };\n    const items = body.data?.items ?? [];\n    for (const it of items) {\n      scanned++;\n      cursor = it.item_id;\n      const step = dueStep(it.data, now);\n      if (step !== null) {\n        if (inQuietHours(it.data, now)) quiet++; // left for a later tick: the cursor wraps back to it\n        else due.push({ row: it, step });\n      }\n      if (due.length >= MAX_REMINDERS || scanned >= MAX_LADDER_ROWS) break scan;\n    }\n    if (!body.data?.next_cursor || items.length === 0) { wrapped = true; break; }\n    cursor = body.data.next_cursor;\n  }\n  const nextCursor = wrapped ? '' : (cursor ?? '');\n\n  // Claim each step FIRST (If-Match): a concurrent tick that claimed it wins,\n  // and this one skips the user \u2014 never a double nudge.\n  const targets: Array<{ device: TokenRow; messages: Messages }> = [];\n  let claimed = 0;\n  for (const { row, step } of due) {\n    const res = await fetch(`${base}/v1/cms/items/push_prefs/${row.item_id}`, {\n      method: 'PATCH',\n      headers: { ...H, ...(row.version !== undefined ? { 'if-match': String(row.version) } : {}) },\n      body: JSON.stringify({ data: { ladder_step: step + 1, last_reminded_at: now.toISOString() } }),\n    }).catch(() => null);\n    if (!res || !res.ok) continue;\n    claimed++;\n    for (const device of await resolveDevices(base, H, [row.data.end_user!])) {\n      targets.push({ device, messages: LADDER[step]!.messages });\n    }\n  }\n  const sent = targets.length > 0\n    ? await sendTo(base, H, targets, { reason: 'reminder' })\n    : { accepted: 0, dropped: 0, errors: [] as string[] };\n  const saved = await writeState(base, H, LADDER_STATE_KEY, state, nextCursor);\n  return json({\n    ladder: true, scanned, due: due.length, quiet, claimed, devices: targets.length, ...sent,\n    resumed_from: startedAt, cursor: nextCursor, wrapped, saved,\n  }, 200);\n}\n\n/** The ladder step due for this user now, or null. Exported for tests.\n *  The HIGHEST rung whose idle threshold is met (the claim then moves\n *  `ladder_step` past it, so the rungs below are skipped, never sent late), and\n *  only once that rung's gap since the previous nudge has passed. */\nexport function dueStep(p: PrefRow['data'], now: Date): number | null {\n  if (p.reminders === false || !p.end_user || !p.last_active) return null;\n  const idleH = (now.getTime() - Date.parse(p.last_active)) / 3_600_000;\n  if (!Number.isFinite(idleH)) return null;\n  const from = Math.max(0, Math.trunc(p.ladder_step ?? 0));\n  let step: number | null = null;\n  for (let r = from; r < LADDER.length; r++) if (idleH >= LADDER[r]!.afterHours) step = r;\n  if (step === null) return null;\n  if (step > 0 && p.last_reminded_at) {\n    const sinceH = (now.getTime() - Date.parse(p.last_reminded_at)) / 3_600_000;\n    const gapH = LADDER[step]!.afterHours - LADDER[step - 1]!.afterHours;\n    if (Number.isFinite(sinceH) && sinceH < gapH) return null;\n  }\n  return step;\n}\n\n/** Is it inside the user's quiet hours [quiet_start, quiet_end) in THEIR zone?\n *  The window may wrap midnight; equal or missing bounds mean none. An unknown\n *  zone is evaluated in UTC. Exported for tests. */\nexport function inQuietHours(p: PrefRow['data'], now: Date): boolean {\n  const start = p.quiet_start;\n  const end = p.quiet_end;\n  if (typeof start !== 'number' || typeof end !== 'number' || start === end) return false;\n  const h = localHour(now, p.timezone);\n  return start < end ? h >= start && h < end : h >= start || h < end;\n}\n\n/** One formatter per zone, kept for the isolate's life: building an Intl formatter is the\n *  expensive part, and a tick can test hundreds of users in the same few zones\n *  (CPU per invocation is capped \u2014 2,000 ms on a Free staging/development project; on a dev slot 50 ms unless the function declares limits.cpuMs, up to 2,000; both within a 500,000 CPU-ms daily budget). */\nconst ZONE_FMT = new Map<string, Intl.DateTimeFormat | null>();\nfunction zoneFormatter(tz: string): Intl.DateTimeFormat | null {\n  if (!ZONE_FMT.has(tz)) {\n    let f: Intl.DateTimeFormat | null = null;\n    try { f = new Intl.DateTimeFormat('en-US', { timeZone: tz, hour: 'numeric', hourCycle: 'h23' }); } catch { /* unknown zone */ }\n    if (ZONE_FMT.size < 500) ZONE_FMT.set(tz, f);\n    return f;\n  }\n  return ZONE_FMT.get(tz)!;\n}\n\nfunction localHour(now: Date, tz: string | undefined): number {\n  try {\n    const part = zoneFormatter(tz || 'UTC')?.formatToParts(now).find((x) => x.type === 'hour');\n    const h = Number(part?.value);\n    if (Number.isInteger(h)) return h % 24;\n  } catch { /* unknown zone \u2192 UTC below */ }\n  return now.getUTCHours();\n}\n\nasync function readState(base: string, H: Record<string, string>, key: string): Promise<StateRow | null | 'error'> {\n  const filter = encodeURIComponent(JSON.stringify({ key }));\n  const res = await fetch(`${base}/v1/cms/items/push_state?filter=${filter}&limit=1`, { headers: H });\n  if (!res.ok) return 'error';\n  return ((await res.json()) as { data?: { items?: StateRow[] } }).data?.items?.[0] ?? null;\n}\n\nasync function writeState(\n  base: string, H: Record<string, string>, key: string, state: StateRow | null, cursor: string,\n): Promise<boolean> {\n  const data = { key, cursor, updated_at: new Date().toISOString() };\n  const res = state\n    ? await fetch(`${base}/v1/cms/items/push_state/${state.item_id}`, {\n      method: 'PATCH',\n      headers: { ...H, ...(state.version !== undefined ? { 'if-match': String(state.version) } : {}) },\n      body: JSON.stringify({ data }),\n    }).catch(() => null)\n    : await fetch(`${base}/v1/cms/items/push_state`, {\n      method: 'POST', headers: H, body: JSON.stringify({ status: 'published', data }),\n    }).catch(() => null);\n  return !!res && res.ok;\n}\n\n/** Locale match: exact ('pt-BR'), then the base language ('pt'), then default. */\nfunction pick(messages: Messages, locale: string | undefined): Copy {\n  if (locale) {\n    if (messages[locale]) return messages[locale]!;\n    const bare = locale.split('-')[0]!;\n    if (messages[bare]) return messages[bare]!;\n  }\n  return messages.default ?? {};\n}\n\nasync function patch(base: string, H: Record<string, string>, d: TokenRow, data: Record<string, unknown>) {\n  await fetch(`${base}/v1/cms/items/push_tokens/${d.item_id}`, {\n    method: 'PATCH', headers: H, body: JSON.stringify({ data }),\n  }).catch(() => null);\n}\nasync function del(base: string, H: Record<string, string>, d: TokenRow) {\n  await fetch(`${base}/v1/cms/items/push_tokens/${d.item_id}`, { method: 'DELETE', headers: H }).catch(() => null);\n}\nconst json = (o: unknown, status: number) => Response.json(o, { status });\n"
     }
   },
   {
@@ -24234,7 +24240,7 @@ ${formatSummary(state)}`);
     case "architect": {
       const description = positional(0).join(" ").trim();
       if (!description) fail('usage: vxil architect "<describe your app>" [--name <n>] [--out vxil.config.ts] [--brief <file.md>|--no-brief]');
-      const { api } = requireApi(selector());
+      const { api, baseUrl } = requireApi(selector());
       const nameFlag = flag("name");
       const noBrief = hasFlag("no-brief");
       const briefOut = flag("brief");
@@ -24275,7 +24281,7 @@ ${plan.rationale}`);
         if (briefOut && !plan.brief) {
           fail(`--brief ${briefOut}: the server returned no brief \u2014 nothing written`);
         } else if (briefOut) {
-          writeFileSync6(briefOut, renderBriefMarkdown(plan.brief, plan.app ?? {}));
+          writeFileSync6(briefOut, renderBriefMarkdown(plan.brief, plan.app ?? {}, { site: briefSiteFor(baseUrl) }));
           console.log(`\u2713 wrote ${briefOut}`);
         } else if (plan.brief) {
           console.log("  (run again with --brief brief.md to write the full brief as markdown)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/cli",
-  "version": "0.24.1",
+  "version": "0.24.2",
   "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",