@rebasepro/server 0.22.0 → 0.24.0

package/dist/cron-scheduler-COPQxlEq.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cron-scheduler-COPQxlEq.js","names":[],"sources":["../../types/src/types/env_boolean.ts","../src/cron/scale-to-zero.ts","../src/cron/cron-scheduler.ts"],"sourcesContent":["const YES = new Set([\"true\", \"1\", \"yes\", \"on\"]);\nconst NO = new Set([\"false\", \"0\", \"no\", \"off\"]);\n\n/**\n * Read a boolean environment variable — one spelling rule for every reader.\n *\n * `true`, `1`, `yes` and `on` are true; `false`, `0`, `no` and `off` are\n * false. Case and surrounding whitespace are ignored. Anything else — unset,\n * blank, or a value that spells neither — is `undefined`, so the caller's\n * default decides and a typo lands on the side the caller chose:\n *\n * ```ts\n * parseEnvBoolean(env.FORCE_LOCAL_STORAGE) === true            // off unless said\n * parseEnvBoolean(env.REBASE_MCP_OPEN_REGISTRATION) !== false  // on unless said\n * ```\n *\n * It exists because every reader used to spell this itself, and they\n * disagreed. The reader that mattered tested the raw string for truthiness —\n * `!process.env.FORCE_LOCAL_STORAGE` — and every non-empty string is truthy,\n * so `FORCE_LOCAL_STORAGE=false`, written to say \"there is no durable volume\n * here\", switched the production storage guard off and sent uploads to a\n * container filesystem the next redeploy erased. Beside it, `=== \"true\"` made\n * `DISABLE_DB_ROLE_SWITCHING=1` do nothing and `!== \"false\"` made\n * `REBASE_MCP_OPEN_REGISTRATION=0` leave registration open.\n *\n * The boot schemas in `@rebasepro/server` (`loadEnv`, `loadBootEnv`) accept a\n * strict subset — `true`, `false` and blank — and refuse any other value\n * before the server starts. On that subset they read exactly what this reads,\n * so a variable a schema declares and something else reads lazily cannot mean\n * two different things.\n *\n * It lives in this package, with no dependencies, for the reason\n * {@link storageEnvSuffix} does: the runtime, its drivers and the CLI all read\n * these variables, and a second parser is a second chance to disagree.\n *\n * @group Models\n */\nexport function parseEnvBoolean(value: string | undefined): boolean | undefined {\n    if (value === undefined) return undefined;\n    const spelled = value.trim().toLowerCase();\n    if (YES.has(spelled)) return true;\n    if (NO.has(spelled)) return false;\n    return undefined;\n}\n","/**\n * Scale-to-zero detection for the cron scheduler.\n *\n * The scheduler drives jobs with in-process `setTimeout`. That works on any\n * always-running instance, but on a platform that freezes or evicts the\n * container between requests (Cloud Run with `--min-instances=0`, AWS Lambda,\n * Vercel functions) the timers simply never fire — the process boots, logs the\n * jobs as registered, and silently runs nothing.\n *\n * None of these platforms expose their scaling floor to the container, so this\n * detection is a heuristic: it identifies the *platform*, not the setting. It\n * is a warning only — it must never influence boot.\n *\n * Environment variables used here were verified against vendor documentation:\n *  - `K_SERVICE` / `K_REVISION` / `K_CONFIGURATION` — Cloud Run services\n *    (Cloud Run container contract; no variable exposes min-instances).\n *  - `CLOUD_RUN_JOB` — Cloud Run jobs (same contract).\n *  - `AWS_LAMBDA_FUNCTION_NAME` — reserved AWS Lambda runtime variable.\n *  - `VERCEL=1` — Vercel system environment variable, available at runtime.\n *  - `KUBERNETES_SERVICE_HOST` — injected into every pod by the kubelet. Used\n *    as an *exclusion*: a Deployment pod runs continuously, and Knative on\n *    Kubernetes also sets `K_SERVICE`, so a pod is never warned about.\n */\n\nimport { parseEnvBoolean } from \"@rebasepro/types\";\n\n/** Environment variable that permanently silences the scale-to-zero warning. */\nexport const CRON_ALWAYS_ON_ENV = \"REBASE_CRON_ALWAYS_ON\";\n\n/** The subset of `process.env` this module reads. */\nexport type EnvLike = Record<string, string | undefined>;\n\nexport interface FreezableRuntime {\n    /** Human-readable platform name, used verbatim in the warning. */\n    platform: string;\n    /** Names of the environment variables that identified the platform. */\n    signals: string[];\n}\n\n/** Minimal shape of a registered job needed to build the warning. */\nexport interface WarnableJob {\n    id: string;\n    enabled: boolean;\n}\n\nexport interface ScaleToZeroWarning {\n    message: string;\n    data: Record<string, unknown>;\n}\n\n/**\n * Identify a runtime whose instances can be frozen or torn down between\n * requests. Returns `undefined` when the platform is unknown or known to run\n * continuously.\n */\nexport function detectFreezableRuntime(env: EnvLike = process.env): FreezableRuntime | undefined {\n    // A Kubernetes pod (GKE, EKS, self-hosted) runs continuously. Knative and\n    // Cloud Run for Anthos set K_SERVICE *inside* a pod, so this exclusion has\n    // to come first or every Knative pod would be a false positive.\n    if (env.KUBERNETES_SERVICE_HOST) return undefined;\n\n    if (env.K_SERVICE) {\n        const signals = [\"K_SERVICE\"];\n        if (env.K_REVISION) signals.push(\"K_REVISION\");\n        if (env.K_CONFIGURATION) signals.push(\"K_CONFIGURATION\");\n        return { platform: \"Cloud Run\", signals };\n    }\n\n    if (env.CLOUD_RUN_JOB) {\n        return { platform: \"Cloud Run Jobs\", signals: [\"CLOUD_RUN_JOB\"] };\n    }\n\n    if (env.AWS_LAMBDA_FUNCTION_NAME) {\n        return { platform: \"AWS Lambda\", signals: [\"AWS_LAMBDA_FUNCTION_NAME\"] };\n    }\n\n    if (parseEnvBoolean(env.VERCEL) === true) {\n        return { platform: \"Vercel\", signals: [\"VERCEL\"] };\n    }\n\n    return undefined;\n}\n\n/** How many job ids to name before collapsing the rest into \"+N more\". */\nconst MAX_NAMED_JOBS = 10;\n\n/**\n * Build the boot-time warning, or `undefined` when it does not apply.\n *\n * Fires only when all of the following hold:\n *  1. `NODE_ENV=production` — a laptop or CI run is not at risk.\n *  2. At least one *enabled* job is registered — nothing to lose otherwise.\n *  3. The environment looks like a freezable platform (see above).\n *  4. `REBASE_CRON_ALWAYS_ON` is not set to a truthy value.\n */\nexport function buildScaleToZeroWarning(\n    jobs: WarnableJob[],\n    env: EnvLike = process.env\n): ScaleToZeroWarning | undefined {\n    if (env.NODE_ENV !== \"production\") return undefined;\n    if (parseEnvBoolean(env[CRON_ALWAYS_ON_ENV]) === true) return undefined;\n\n    const enabled = jobs.filter((job) => job.enabled).map((job) => job.id);\n    if (enabled.length === 0) return undefined;\n\n    const runtime = detectFreezableRuntime(env);\n    if (!runtime) return undefined;\n\n    const named = enabled.slice(0, MAX_NAMED_JOBS);\n    const list = enabled.length > named.length\n        ? `${named.join(\", \")} (+${enabled.length - named.length} more)`\n        : named.join(\", \");\n\n    const message = `[cron] ${runtime.platform} detected — in-process timers do not fire while an instance is frozen or scaled to zero, so ${enabled.length} enabled job(s) may never run: ${list}; drive them from an external scheduler instead (POST /api/cron/:id/trigger, e.g. Cloud Scheduler). ${runtime.platform} does not expose its scaling floor to the container, so an always-warm deployment cannot be confirmed from inside the process — set ${CRON_ALWAYS_ON_ENV}=1 to silence this if at least one instance is pinned warm.`;\n\n    return {\n        message,\n        data: {\n            platform: runtime.platform,\n            signals: runtime.signals,\n            jobs: enabled\n        }\n    };\n}\n","import type {\n    CronJobDefinition,\n    CronJobStatus,\n    CronJobLogEntry,\n    CronJobRunState,\n    CronJobContext\n} from \"@rebasepro/types\";\nimport type { RebaseServerClient } from \"@rebasepro/types\";\nimport type { LoadedCronJob } from \"./cron-loader\";\nimport type { CronStore } from \"./cron-store\";\nimport { logger, redactSensitiveText } from \"../utils/logger.js\";\nimport { buildScaleToZeroWarning } from \"./scale-to-zero.js\";\n\n// ─── Cron expression parser (minimal, no external dependency) ────────\n// Supports standard 5-field cron (minute hour dom month dow).\n// Returns the next Date after `after` that matches the expression.\n\n/**\n * Expand a single cron field into an ordered array of allowed values.\n * Supports: `*`, `N`, `N-M`, `N/S`, `N-M/S`, `*\\/S`, and comma-separated combinations.\n */\nfunction expandCronField(field: string, min: number, max: number): number[] {\n    const results = new Set<number>();\n    for (const segment of field.split(\",\")) {\n        const trimmed = segment.trim();\n        if (trimmed === \"*\") {\n            for (let i = min; i <= max; i++) results.add(i);\n        } else if (trimmed.includes(\"/\")) {\n            const [rangeStr, stepStr] = trimmed.split(\"/\");\n            const step = parseInt(stepStr, 10);\n            if (isNaN(step) || step <= 0) {\n                throw new Error(`Invalid step value \"${stepStr}\" in cron field \"${field}\"`);\n            }\n            let start = min;\n            let end = max;\n            if (rangeStr !== \"*\") {\n                if (rangeStr.includes(\"-\")) {\n                    const [a, b] = rangeStr.split(\"-\").map(Number);\n                    start = a;\n                    end = b;\n                } else {\n                    start = parseInt(rangeStr, 10);\n                }\n            }\n            for (let i = start; i <= end; i += step) results.add(i);\n        } else if (trimmed.includes(\"-\")) {\n            const [a, b] = trimmed.split(\"-\").map(Number);\n            for (let i = a; i <= b; i++) results.add(i);\n        } else {\n            const val = parseInt(trimmed, 10);\n            if (isNaN(val)) {\n                throw new Error(`Invalid value \"${trimmed}\" in cron field \"${field}\"`);\n            }\n            results.add(val);\n        }\n    }\n    return [...results].sort((a, b) => a - b);\n}\n\n/**\n * Validates a standard 5-field cron expression structurally and semantically.\n * Returns `{ valid: true }` or `{ valid: false, reason: string }`.\n */\nexport function validateCronExpression(schedule: string): { valid: true } | { valid: false; reason: string } {\n    if (!schedule || typeof schedule !== \"string\") {\n        return { valid: false,\nreason: \"Schedule must be a non-empty string\" };\n    }\n    const parts = schedule.trim().split(/\\s+/);\n    if (parts.length !== 5) {\n        return { valid: false,\nreason: `Expected 5 fields, got ${parts.length}` };\n    }\n    const fieldRanges: [string, number, number][] = [\n        [\"minute\", 0, 59],\n        [\"hour\", 0, 23],\n        [\"day of month\", 1, 31],\n        [\"month\", 1, 12],\n        [\"day of week\", 0, 6]\n    ];\n    for (let i = 0; i < 5; i++) {\n        const [name, min, max] = fieldRanges[i];\n        try {\n            const values = expandCronField(parts[i], min, max);\n            if (values.length === 0) {\n                return { valid: false,\nreason: `${name} field \"${parts[i]}\" produces no values` };\n            }\n            for (const v of values) {\n                if (v < min || v > max) {\n                    return { valid: false,\nreason: `${name} field value ${v} out of range [${min}–${max}]` };\n                }\n            }\n        } catch (err) {\n            return { valid: false,\nreason: `${name} field: ${err instanceof Error ? err.message : String(err)}` };\n        }\n    }\n    return { valid: true };\n}\n\n/** The five cron fields, pre-expanded into the values each one allows. */\ninterface CronFields {\n    minutes: number[];\n    hours: number[];\n    doms: number[];\n    months: number[];\n    dows: number[];\n}\n\n/** Expand all five fields of an expression. Throws on invalid expressions. */\nfunction parseCronFields(expression: string): CronFields {\n    const parts = expression.trim().split(/\\s+/);\n    if (parts.length < 5) {\n        throw new Error(`Invalid cron expression: \"${expression}\". Expected 5 fields.`);\n    }\n    const [minField, hourField, domField, monField, dowField] = parts;\n    return {\n        minutes: expandCronField(minField, 0, 59),\n        hours: expandCronField(hourField, 0, 23),\n        doms: expandCronField(domField, 1, 31),\n        months: expandCronField(monField, 1, 12),\n        dows: expandCronField(dowField, 0, 6) // 0=Sunday\n    };\n}\n\n/**\n * Whether an IANA zone name is one this runtime can read a schedule in.\n *\n * `Intl` is the authority: it throws a RangeError on a name it does not know,\n * which is the only check that tracks the tz database the process actually\n * ships. A misspelled zone must fail when the job loads, not silently read\n * the schedule as local time.\n */\nexport function isValidTimeZone(zone: string): boolean {\n    try {\n        new Intl.DateTimeFormat(\"en-US\", { timeZone: zone });\n        return true;\n    } catch {\n        return false;\n    }\n}\n\n/** Wall-clock parts of an instant, in a zone, as the cron fields see them. */\ninterface WallClock {\n    minute: number;\n    hour: number;\n    dom: number;\n    month: number;\n    dow: number;\n}\n\nconst formatters = new Map<string, Intl.DateTimeFormat>();\nconst DOW: Record<string, number> = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };\n\nfunction wallClockIn(candidate: Date, zone: string): WallClock {\n    let formatter = formatters.get(zone);\n    if (!formatter) {\n        formatter = new Intl.DateTimeFormat(\"en-US\", {\n            timeZone: zone,\n            hourCycle: \"h23\",\n            weekday: \"short\",\n            month: \"numeric\",\n            day: \"numeric\",\n            hour: \"numeric\",\n            minute: \"numeric\"\n        });\n        formatters.set(zone, formatter);\n    }\n    const parts: Record<string, string> = {};\n    for (const part of formatter.formatToParts(candidate)) parts[part.type] = part.value;\n    return {\n        minute: Number(parts.minute),\n        hour: Number(parts.hour),\n        dom: Number(parts.day),\n        month: Number(parts.month),\n        dow: DOW[parts.weekday] ?? candidate.getDay()\n    };\n}\n\n/**\n * Whether a minute-precision instant matches every field of the expression.\n *\n * Read in `zone` when one is named, else in the process's own zone — which is\n * whatever the host is set to, UTC in nearly every container. A schedule that\n * names its zone means the same wall-clock hour on every host it runs on.\n */\nfunction matchesCronFields(candidate: Date, fields: CronFields, zone?: string): boolean {\n    const wall: WallClock = zone\n        ? wallClockIn(candidate, zone)\n        : {\n            minute: candidate.getMinutes(),\n            hour: candidate.getHours(),\n            dom: candidate.getDate(),\n            month: candidate.getMonth() + 1, // getMonth is 0-11\n            dow: candidate.getDay()\n        };\n    return fields.months.includes(wall.month)\n        && fields.doms.includes(wall.dom)\n        && fields.dows.includes(wall.dow)\n        && fields.hours.includes(wall.hour)\n        && fields.minutes.includes(wall.minute);\n}\n\n/** ~1 year in minutes — the walk bound for both search directions. */\n/**\n * How far forward to look for the next matching slot.\n *\n * Four years and a day, not one year. `0 0 29 2 *` — run on 29 February — is a\n * legitimate expression whose slot can be almost four years out, and a one-year\n * search never found it.\n */\nconst MAX_SLOT_SEARCH_MINUTES = 4 * 525960 + 1440;\n\n/**\n * Calculate the next Date after `after` that matches the cron expression.\n * Throws on invalid expressions.\n */\nexport function parseCronExpression(expression: string, after: Date, timezone?: string): Date {\n    const fields = parseCronFields(expression);\n\n    // Forward-search from `after + 1 minute`\n    const candidate = new Date(after);\n    candidate.setSeconds(0, 0);\n    candidate.setMinutes(candidate.getMinutes() + 1);\n\n    for (let i = 0; i < MAX_SLOT_SEARCH_MINUTES; i++) {\n        if (matchesCronFields(candidate, fields, timezone)) {\n            return candidate;\n        }\n        candidate.setMinutes(candidate.getMinutes() + 1);\n    }\n\n    // No slot inside the window. Refuse rather than invent one.\n    //\n    // This used to return `after + 1 minute`, which is indistinguishable from a\n    // schedule that really does fire every minute — so an expression with no\n    // reachable slot ran sixty times an hour, forever. `0 0 29 2 *` was caught\n    // by it while the search window was a single year: a job meant to run once\n    // every four years became the busiest job on the deployment.\n    //\n    // The caller schedules inside a `try` and reports a job it could not\n    // schedule, which is the correct outcome for an expression that names no\n    // time. Genuinely impossible dates (`0 0 31 2 *`) land here too, and should.\n    throw new Error(\n        `Cron expression \"${expression}\" has no matching time within ` +\n        `${Math.round(MAX_SLOT_SEARCH_MINUTES / 525960)} years of ${after.toISOString()}. ` +\n        \"Check the day-of-month and month fields — a date such as 31 February never occurs.\"\n    );\n}\n\n/**\n * The latest slot matching `expression` within the inclusive window\n * `[from, to]`, or `undefined` when the expression has no slot in it.\n *\n * Walks backwards a minute at a time from `to`, so the first hit is already\n * the answer — in the common case (a job that ran normally moments ago) that\n * is a handful of iterations, not a scan of the whole window.\n *\n * `to`'s own minute is included: an instance booting at 06:00:30 has *not* run\n * the 06:00 slot — `parseCronExpression` already skipped past it to tomorrow —\n * so that slot is genuinely missed and must be a candidate.\n *\n * Seconds and milliseconds are zeroed to match how `parseCronExpression`\n * builds a slot, so the same wall-clock slot serialises to a byte-identical\n * ISO string down either path. The claim key depends on that.\n */\nexport function findMostRecentSlot(expression: string, from: Date, to: Date, timezone?: string): Date | undefined {\n    const fields = parseCronFields(expression);\n\n    const candidate = new Date(to);\n    candidate.setSeconds(0, 0);\n\n    for (let i = 0; i < MAX_SLOT_SEARCH_MINUTES && candidate.getTime() >= from.getTime(); i++) {\n        if (matchesCronFields(candidate, fields, timezone)) {\n            return candidate;\n        }\n        candidate.setMinutes(candidate.getMinutes() - 1);\n    }\n\n    return undefined;\n}\n\n// ─── In-memory ring buffer for logs ──────────────────────────────────\n\nconst MAX_LOGS_PER_JOB = 50;\n\n/**\n * Minimum milliseconds between scheduled executions of the same job.\n * Prevents tight re-execution loops caused by jitter or clock drift.\n */\nconst MIN_SCHEDULE_INTERVAL_MS = 5_000; // 5 seconds\n\n/**\n * Largest delay setTimeout can hold. Node stores it in a 32-bit signed int;\n * anything larger silently clamps to 1ms and fires immediately, so a slot\n * further out than this must be reached in hops rather than one timer.\n */\nconst MAX_TIMER_DELAY_MS = 2_147_483_647; // 2^31 - 1, ~24.8 days\n\n// ─── CronScheduler ───────────────────────────────────────────────────\n\ninterface RegisteredJob {\n    id: string;\n    definition: CronJobDefinition;\n    enabled: boolean;\n    state: CronJobRunState;\n    lastRunAt?: Date;\n    nextRunAt?: Date;\n    lastDurationMs?: number;\n    lastError?: string;\n    totalRuns: number;\n    totalFailures: number;\n    timerId?: ReturnType<typeof setTimeout>;\n    logs: CronJobLogEntry[];\n    /** True while a handler is actively executing (prevents concurrent runs). */\n    executing: boolean;\n}\n\n/**\n * A job the scheduler refused, and why.\n *\n * It is not a `CronJobStatus`: it has no state, no next run and no counters,\n * because it was never registered. Reporting it as a job with `state: \"error\"`\n * would be a lie in the other direction — nothing is going to run it.\n */\nexport interface RejectedCronJob {\n    id: string;\n    name: string;\n    schedule: string;\n    reason: string;\n}\n\nexport class CronScheduler {\n    private jobs = new Map<string, RegisteredJob>();\n    private rejected = new Map<string, RejectedCronJob>();\n    private started = false;\n    private store?: CronStore;\n    private client?: RebaseServerClient;\n\n    /**\n     * Set the server singleton to make it available to cron job handlers.\n     *\n     * `RebaseServerClient`, not `RebaseClient`: the object `init.ts` passes is\n     * the same one it registers as the singleton, so this was always the true\n     * type — and the wider annotation is what let `ctx.client.data` look like a\n     * user-scoped plane inside a cron, when it is the admin-scoped one.\n     */\n    setClient(client: RebaseServerClient): void {\n        this.client = client;\n    }\n\n    /**\n     * Attach a persistence store for cron logs.\n     * When set, execution logs are written to the database after each run,\n     * and counters are seeded from the database on start.\n     */\n    setStore(store: CronStore): void {\n        this.store = store;\n    }\n\n    /**\n     * Register a batch of loaded cron jobs.\n     *\n     * If the scheduler is already started, newly registered jobs are\n     * automatically scheduled (so late-registered jobs don't sit idle).\n     *\n     * Validates the cron schedule on registration — invalid schedules\n     * are rejected with a warning and the job is NOT registered.\n     */\n    registerJobs(loadedJobs: LoadedCronJob[]): void {\n        for (const loaded of loadedJobs) {\n            // Validate schedule up-front — reject invalid schedules\n            const validation = validateCronExpression(loaded.definition.schedule);\n            if (!validation.valid) {\n                logger.error(`[cron] Rejecting job \"${loaded.id}\": invalid schedule \"${loaded.definition.schedule}\" — ${validation.reason}`);\n                // Kept, not just logged. A rejected job is absent from\n                // `listJobs()`, so from the Studio panel it is indistinguishable\n                // from a file that was never written — and the commonest reason\n                // to land here is a 6-field expression copied from a tool that\n                // supports seconds, which is a one-character fix nobody could\n                // see without boot-log access.\n                this.rejected.set(loaded.id, {\n                    id: loaded.id,\n                    name: loaded.definition.name ?? loaded.id,\n                    schedule: loaded.definition.schedule,\n                    reason: validation.reason\n                });\n                continue;\n            }\n            // Rejected, not read as local time: a misspelled zone that fell\n            // back silently would fire at the wrong hour on every host and\n            // look like a scheduler bug. Kept in `rejected` for the same reason\n            // a bad schedule is — otherwise the panel cannot tell it from a\n            // file nobody wrote.\n            if (loaded.definition.timezone !== undefined && !isValidTimeZone(loaded.definition.timezone)) {\n                const reason =\n                    `unknown timezone \"${loaded.definition.timezone}\" — ` +\n                    'use an IANA name such as \"Europe/Madrid\" or \"UTC\"';\n                logger.error(`[cron] Rejecting job \"${loaded.id}\": ${reason}.`);\n                this.rejected.set(loaded.id, {\n                    id: loaded.id,\n                    name: loaded.definition.name ?? loaded.id,\n                    schedule: loaded.definition.schedule,\n                    reason\n                });\n                continue;\n            }\n            // A re-register that now validates clears the earlier complaint.\n            this.rejected.delete(loaded.id);\n\n            const existing = this.jobs.get(loaded.id);\n            if (existing) {\n                logger.warn(`[cron] Duplicate cron job id: \"${loaded.id}\". Overwriting.`);\n                this.stopJob(loaded.id);\n            }\n\n            const enabled = loaded.definition.enabled !== false;\n\n            this.jobs.set(loaded.id, {\n                id: loaded.id,\n                definition: loaded.definition,\n                enabled,\n                state: enabled ? \"idle\" : \"disabled\",\n                totalRuns: 0,\n                totalFailures: 0,\n                logs: [],\n                executing: false\n            });\n\n            // If the scheduler is already running, auto-schedule new jobs\n            if (this.started && enabled) {\n                this.scheduleNext(loaded.id);\n            }\n        }\n    }\n\n    /**\n     * Start the scheduler — begins ticking all enabled jobs.\n     */\n    start(): void {\n        if (this.started) return;\n        this.started = true;\n\n        // Seed counters from DB (non-blocking — scheduler starts immediately)\n        if (this.store) {\n            this.store.fetchJobStats().then((stats) => {\n                for (const [jobId, data] of stats) {\n                    const job = this.jobs.get(jobId);\n                    if (job) {\n                        job.totalRuns = data.totalRuns;\n                        job.totalFailures = data.totalFailures;\n                        if (data.lastRunAt) {\n                            job.lastRunAt = new Date(data.lastRunAt);\n                        }\n                    }\n                }\n            }).catch((err) => {\n                logger.warn(\"[cron] Failed to seed job stats from database\", { error: err });\n            });\n        }\n\n        for (const [id, job] of this.jobs) {\n            if (job.enabled) {\n                this.scheduleNext(id);\n            }\n        }\n        if (!this.store) {\n            logger.warn(\"[cron] No cron store attached — runs are uncoordinated; with multiple app instances every instance will execute every job\");\n        }\n        this.warnIfScaleToZero();\n\n        // Recover slots that elapsed while nothing was ticking. Deliberately\n        // not awaited: catch-up reaches the database and runs handlers, and\n        // boot must not wait on either. Its own errors are contained inside.\n        void this.catchUpMissedSlots();\n\n        logger.info(`⏰ Cron scheduler started with ${this.jobs.size} job(s)`);\n    }\n\n    /**\n     * Stop the scheduler and clear all timers.\n     *\n     * Currently-executing handlers run to completion (they are async),\n     * but no further scheduling occurs after stop.\n     */\n    stop(): void {\n        this.started = false;\n        for (const [id] of this.jobs) {\n            this.stopJob(id);\n        }\n    }\n\n    /**\n     * List all registered jobs with their current status.\n     */\n    listJobs(): CronJobStatus[] {\n        return [...this.jobs.values()].map((job) => this.toStatus(job));\n    }\n\n    /**\n     * Jobs that loaded but whose schedule the scheduler refused.\n     *\n     * Kept apart from {@link listJobs} because they are not jobs — nothing will\n     * run them — but they must be reachable, or \"my cron is missing\" and \"my\n     * cron will never fire\" look identical from the admin panel.\n     */\n    listRejectedJobs(): RejectedCronJob[] {\n        return [...this.rejected.values()];\n    }\n\n    /**\n     * Get a single job status by ID.\n     */\n    getJob(id: string): CronJobStatus | undefined {\n        const job = this.jobs.get(id);\n        return job ? this.toStatus(job) : undefined;\n    }\n\n    /**\n     * Get log entries for a job.\n     */\n    getJobLogs(id: string, limit?: number): CronJobLogEntry[] {\n        const job = this.jobs.get(id);\n        if (!job) return [];\n        const logs = [...job.logs].reverse(); // newest first\n        return limit ? logs.slice(0, limit) : logs;\n    }\n\n    /**\n     * Get log entries for a job from the database (if store is available).\n     * Falls back to in-memory logs if no store is configured.\n     */\n    async getJobLogsFromDb(id: string, limit?: number): Promise<CronJobLogEntry[]> {\n        if (this.store) {\n            const dbLogs = await this.store.fetchLogs(id, limit);\n            if (dbLogs.length > 0) return dbLogs;\n        }\n        // Fallback to in-memory\n        return this.getJobLogs(id, limit);\n    }\n\n    /**\n     * Enable or disable a job at runtime.\n     */\n    setJobEnabled(id: string, enabled: boolean): CronJobStatus | undefined {\n        const job = this.jobs.get(id);\n        if (!job) return undefined;\n\n        job.enabled = enabled;\n\n        if (enabled && this.started) {\n            job.state = \"idle\";\n            this.scheduleNext(id);\n        } else if (!enabled) {\n            this.stopJob(id);\n            job.state = \"disabled\";\n        }\n\n        return this.toStatus(job);\n    }\n\n    /**\n     * Manually trigger a job execution immediately.\n     *\n     * Returns `undefined` if the job doesn't exist.\n     * If the job is currently executing, returns the log entry with\n     * a `skipped: true` result rather than running concurrently.\n     */\n    async triggerJob(id: string): Promise<CronJobLogEntry | undefined> {\n        const job = this.jobs.get(id);\n        if (!job) return undefined;\n\n        // Concurrency guard — don't run two instances simultaneously\n        if (job.executing) {\n            logger.warn(`[cron] Skipping manual trigger of \"${id}\" — already executing`);\n            return this.recordSkip(job, \"already_executing\", true);\n        }\n\n        return this.executeJob(job, true);\n    }\n\n    /**\n     * Record a run that did not happen because the previous one had not\n     * finished.\n     *\n     * Written to `cron_logs`, not only to the in-memory ring. An overlap is the\n     * signature of a job that has outgrown its schedule — the one thing you want\n     * to see in the history rather than infer from a gap in it — and until now\n     * the scheduled path left no trace at all beyond a warning in the process\n     * log, which is gone by the time anyone asks. The manual path wrote a ring\n     * entry that vanished on restart.\n     *\n     * `success: true` is deliberate: nothing failed. The `result.skipped` flag\n     * and the reason are what distinguishes it, and the Studio panel reads them.\n     */\n    private recordSkip(job: RegisteredJob, reason: string, manual: boolean): CronJobLogEntry {\n        const now = new Date().toISOString();\n        const logEntry: CronJobLogEntry = {\n            jobId: job.id,\n            startedAt: now,\n            finishedAt: now,\n            durationMs: 0,\n            success: true,\n            result: { skipped: true, reason },\n            logs: [`Skipped: ${reason === \"already_executing\" ? \"the previous run has not finished\" : reason}`],\n            manual\n        };\n\n        job.logs.push(logEntry);\n        if (job.logs.length > MAX_LOGS_PER_JOB) job.logs.shift();\n\n        this.store?.insertLog(logEntry).catch((persistErr) => {\n            logger.error(`[cron] Failed to persist skip for \"${job.id}\"`, { error: persistErr });\n        });\n\n        return logEntry;\n    }\n\n    // ─── Internal ────────────────────────────────────────────────────\n\n    /**\n     * Warn once at start when the process looks like it is running on a\n     * platform that freezes or evicts instances between requests, where the\n     * in-process timers this scheduler relies on never fire.\n     *\n     * Advisory only: any failure here is swallowed so a detection bug can\n     * never take a production boot down.\n     */\n    private warnIfScaleToZero(): void {\n        try {\n            const warning = buildScaleToZeroWarning(\n                [...this.jobs.values()].map((job) => ({ id: job.id, enabled: job.enabled }))\n            );\n            if (warning) {\n                logger.warn(warning.message, warning.data);\n            }\n        } catch {\n            // Never let the advisory check affect startup.\n        }\n    }\n\n    /**\n     * Schedule the next execution for a job.\n     *\n     * Safety guarantees:\n     * 1. Clears any existing timer first (prevents leaked/duplicate timers)\n     * 2. Enforces a minimum delay to prevent tight loops from jitter\n     * 3. Unref's the timer so it doesn't prevent process exit\n     * 4. Re-checks enabled & started state before executing\n     * 5. Concurrency guard prevents overlapping handler executions\n     */\n    private scheduleNext(id: string): void {\n        const job = this.jobs.get(id);\n        if (!job || !job.enabled || !this.started) return;\n\n        // Clear any previously scheduled timer to prevent double-firing\n        this.stopJob(id);\n\n        try {\n            const now = new Date();\n            const nextRun = parseCronExpression(job.definition.schedule, now, job.definition.timezone);\n            job.nextRunAt = nextRun;\n\n            const rawDelay = nextRun.getTime() - now.getTime();\n            // Enforce a minimum delay to prevent tight re-execution loops\n            // from event loop jitter or near-zero setTimeout drift\n            const delay = Math.max(rawDelay, MIN_SCHEDULE_INTERVAL_MS);\n\n            // A slot past the 32-bit timer ceiling cannot be armed directly:\n            // setTimeout would clamp it to 1ms and fire at once, and since the\n            // slot is already claimed by then, every wake re-schedules the same\n            // overflowing delay — a permanent hot loop, not a late job. Sleep\n            // to the ceiling and re-derive the delay on waking instead; the\n            // cron expression stays the source of truth across the hops.\n            if (delay > MAX_TIMER_DELAY_MS) {\n                const hop = setTimeout(() => {\n                    if (this.started && job.enabled) this.scheduleNext(id);\n                }, MAX_TIMER_DELAY_MS);\n                if (hop && typeof hop === \"object\" && \"unref\" in hop) {\n                    hop.unref();\n                }\n                job.timerId = hop;\n                return;\n            }\n\n            const timer = setTimeout(async () => {\n                // Re-check state: scheduler may have been stopped or job disabled\n                // between when we scheduled and when we fire\n                if (!job.enabled || !this.started) return;\n\n                // Concurrency guard: if somehow we're already executing, skip\n                if (job.executing) {\n                    logger.warn(`[cron] Skipping scheduled run of \"${id}\" — still executing from previous run`);\n                    // Recorded as well as logged: a job that keeps overlapping\n                    // has outgrown its schedule, and that is visible in the run\n                    // history or nowhere.\n                    this.recordSkip(job, \"already_executing\", false);\n                    // Re-schedule to try again later\n                    this.scheduleNext(id);\n                    return;\n                }\n\n                // A timer can wake before its slot: a delay past the 32-bit\n                // ceiling, a clock stepped backwards by NTP, a VM resuming from\n                // suspend. Claiming on an early wake is unrecoverable — claims\n                // are permanent, so the slot would be burned and the real run\n                // silently skipped when it came due. Re-derive from the wall\n                // clock and re-arm instead; only the fire that is genuinely due\n                // may claim.\n                if (Date.now() < nextRun.getTime()) {\n                    this.scheduleNext(id);\n                    return;\n                }\n\n                // Cross-instance guard: claim the scheduled slot in the store.\n                // The slot is the scheduled fire time — deterministic across\n                // instances — so exactly one instance wins each (job, slot) pair.\n                // A store without tryClaimRun (pre-claims custom implementation)\n                // runs uncoordinated; a throwing store fails open — either way\n                // this callback must never reject, or the job would silently\n                // stop rescheduling.\n                if (this.store?.tryClaimRun) {\n                    let claimed = true;\n                    try {\n                        claimed = await this.store.tryClaimRun(id, nextRun.toISOString());\n                    } catch (err) {\n                        logger.warn(`[cron] Claim check threw for \"${id}\" — running uncoordinated`, { error: err });\n                    }\n                    if (!claimed) {\n                        logger.info(`[cron] Slot ${nextRun.toISOString()} for \"${id}\" claimed by another instance — skipping`);\n                        if (this.started && job.enabled) {\n                            this.scheduleNext(id);\n                        }\n                        return;\n                    }\n                }\n\n                await this.executeJob(job, false);\n\n                // Schedule the next tick (only if still started + enabled)\n                if (this.started && job.enabled) {\n                    this.scheduleNext(id);\n                }\n            }, delay);\n\n            // Unref the timer so it doesn't prevent Node.js from exiting\n            // during graceful shutdown\n            if (timer && typeof timer === \"object\" && \"unref\" in timer) {\n                timer.unref();\n            }\n\n            job.timerId = timer;\n        } catch (err: unknown) {\n            logger.error(`[cron] Failed to schedule \"${id}\"`, { error: err });\n            job.state = \"error\";\n            job.lastError = err instanceof Error ? err.message : String(err);\n        }\n    }\n\n    /**\n     * Run any slot that elapsed while no instance was holding a timer for it.\n     *\n     * Only jobs that opted in via `catchUpWindowSeconds` are considered, and\n     * only their single most recent missed slot — see the field's docs for why\n     * both limits are deliberate.\n     *\n     * The claim is what makes this safe. In the ordinary case — an instance\n     * restarting minutes after a slot ran normally — the most recent slot is\n     * already claimed, so this costs one `tryClaimRun` per job per boot and\n     * does nothing. A slot is only executed when no instance, past or present,\n     * ever claimed it.\n     *\n     * Never throws: a failure here must not take down a scheduler that is\n     * otherwise ticking correctly.\n     */\n    private async catchUpMissedSlots(): Promise<void> {\n        const candidates = [...this.jobs.values()].filter(\n            job => job.enabled && (job.definition.catchUpWindowSeconds ?? 0) > 0\n        );\n        if (candidates.length === 0) return;\n\n        // A claims-capable store is the whole safety mechanism. Without one,\n        // every boot would look like \"this slot never ran\" and an instance\n        // recycled twice an hour would re-run the same hourly job twice an\n        // hour. Refusing to catch up is the correct degradation.\n        if (!this.store?.tryClaimRun) {\n            logger.warn(\n                `[cron] Catch-up is configured on ${candidates.length} job(s) but no claims-capable store is attached — skipping. ` +\n                \"Without claims a restart cannot tell an unrun slot from one the previous instance already ran.\"\n            );\n            return;\n        }\n\n        const now = new Date();\n\n        for (const job of candidates) {\n            try {\n                if (!this.started || !job.enabled || job.executing) continue;\n\n                const windowSeconds = job.definition.catchUpWindowSeconds!;\n                const from = new Date(now.getTime() - windowSeconds * 1000);\n                const slot = findMostRecentSlot(job.definition.schedule, from, now, job.definition.timezone);\n                if (!slot) continue;\n\n                const slotIso = slot.toISOString();\n\n                // Same key the scheduled path claims with, so a slot that fired\n                // normally is already taken and this is a no-op.\n                let claimed: boolean;\n                try {\n                    claimed = await this.store.tryClaimRun(job.id, slotIso);\n                } catch (err) {\n                    // Fail closed, unlike the scheduled path. A missed slot is\n                    // a recovery, not an obligation — running it against a\n                    // store that cannot tell us whether it already ran risks a\n                    // duplicate on every boot.\n                    logger.warn(`[cron] Catch-up claim threw for \"${job.id}\" — skipping catch-up`, { error: err });\n                    continue;\n                }\n\n                if (!claimed) continue;\n\n                const lateBy = Math.round((now.getTime() - slot.getTime()) / 1000);\n                logger.info(`[cron] Catching up missed slot ${slotIso} for \"${job.id}\" (${lateBy}s late)`);\n\n                await this.executeJob(job, false, `⏰ Catch-up run for missed slot ${slotIso} (${lateBy}s late)`);\n            } catch (err) {\n                logger.error(`[cron] Catch-up failed for \"${job.id}\"`, { error: err });\n            }\n        }\n    }\n\n    /**\n     * Stop a single job's timer and clear its next run state.\n     */\n    private stopJob(id: string): void {\n        const job = this.jobs.get(id);\n        if (job?.timerId) {\n            clearTimeout(job.timerId);\n            job.timerId = undefined;\n            job.nextRunAt = undefined;\n        }\n    }\n\n    /**\n     * Execute a job's handler with full isolation and safety.\n     *\n     * - Sets a concurrency flag to prevent overlapping runs\n     * - Wraps handler in a timeout race\n     * - Captures all logs, errors, and results\n     * - Persists to store (non-blocking) if available\n     * - Always restores state even on catastrophic errors\n     */\n    private async executeJob(\n        job: RegisteredJob,\n        manual: boolean,\n        seedLog?: string\n    ): Promise<CronJobLogEntry> {\n        const startedAt = new Date();\n        // A caller-supplied first line, stored with the run's own output. A\n        // catch-up uses it to say so in the persisted log, where an operator\n        // reading `cron_logs` will actually see it — `manual` is the only other\n        // provenance the entry carries, and a catch-up is not manual.\n        const capturedLogs: string[] = seedLog ? [seedLog] : [];\n\n        // Set executing flag — prevents concurrent runs\n        job.executing = true;\n\n        // Aborted when the timeout below wins the race. Without it the timeout\n        // only stopped the scheduler waiting: the handler's `fetch` kept its\n        // socket, so a job whose timeout matches its interval leaked one\n        // abandoned request per tick while every run was already marked failed.\n        const abort = new AbortController();\n\n        const ctx: CronJobContext = {\n            jobId: job.id,\n            scheduledAt: startedAt,\n            signal: abort.signal,\n            log: (...args: unknown[]) => {\n                const line = args.map((a) =>\n                    typeof a === \"string\" ? a : JSON.stringify(a)\n                ).join(\" \");\n                capturedLogs.push(line);\n            },\n            // `rebase`, and only `rebase`: it matches the singleton import and\n            // `defineFunction`'s context. The old `client` alias re-exposed\n            // `client.data`, the name `RebaseServerClient` deliberately omits so\n            // that the RLS-bypassing plane is spelled `dataAsAdmin` everywhere.\n            rebase: this.client!\n        };\n\n        job.state = \"running\";\n        job.lastRunAt = startedAt;\n        job.totalRuns++;\n\n        let success = true;\n        let error: string | undefined;\n        let result: unknown;\n\n        try {\n            // Race with timeout\n            const timeout = (job.definition.timeoutSeconds ?? 300) * 1000;\n            const handlerPromise = Promise.resolve(job.definition.handler(ctx));\n            let timeoutHandle: ReturnType<typeof setTimeout>;\n            const timeoutPromise = new Promise<never>((_, reject) => {\n                timeoutHandle = setTimeout(\n                    () => {\n                        // Abort first, so the handler's in-flight work is\n                        // cancelled rather than left running past the run it\n                        // belongs to.\n                        abort.abort(new Error(`Cron job \"${job.id}\" timed out after ${timeout}ms`));\n                        reject(new Error(`Cron job \"${job.id}\" timed out after ${timeout}ms`));\n                    },\n                    timeout\n                );\n            });\n\n            try {\n                result = await Promise.race([handlerPromise, timeoutPromise]);\n            } finally {\n                clearTimeout(timeoutHandle!);\n            }\n        } catch (err: unknown) {\n            success = false;\n            // Redacted at the point of capture, not just on the way to the log:\n            // this string is persisted into `cron_logs` and rendered in the\n            // Studio cron panel, and a job that fails on a query would\n            // otherwise store `Failed query: <sql>\\nparams: <values>` — the\n            // statement and every bound value — in a table, indefinitely.\n            error = redactSensitiveText(err instanceof Error ? err.message : String(err));\n            job.totalFailures++;\n        } finally {\n            // Always clear executing flag — even on catastrophic errors\n            job.executing = false;\n        }\n\n        const finishedAt = new Date();\n        const durationMs = finishedAt.getTime() - startedAt.getTime();\n\n        job.state = success ? (job.enabled ? \"idle\" : \"disabled\") : \"error\";\n        job.lastDurationMs = durationMs;\n        job.lastError = error;\n\n        const logEntry: CronJobLogEntry = {\n            jobId: job.id,\n            startedAt: startedAt.toISOString(),\n            finishedAt: finishedAt.toISOString(),\n            durationMs,\n            success,\n            error,\n            result: result !== undefined ? result : undefined,\n            logs: capturedLogs,\n            manual\n        };\n\n        // Push to ring buffer\n        job.logs.push(logEntry);\n        if (job.logs.length > MAX_LOGS_PER_JOB) {\n            job.logs.shift();\n        }\n\n        // Persist to database (non-blocking)\n        if (this.store) {\n            this.store.insertLog(logEntry).catch((persistErr) => {\n                logger.error(`[cron] Failed to persist log for \"${job.id}\"`, { error: persistErr });\n            });\n        }\n\n        if (success) {\n            logger.info(`✅ [cron] \"${job.id}\" completed in ${durationMs}ms`);\n        } else {\n            logger.error(`❌ [cron] \"${job.id}\" failed in ${durationMs}ms: ${error}`);\n        }\n\n        return logEntry;\n    }\n\n    private toStatus(job: RegisteredJob): CronJobStatus {\n        return {\n            id: job.id,\n            // Same fallback the two `listJobs` paths already applied: `name` is\n            // optional and the id is the file's own name.\n            name: job.definition.name ?? job.id,\n            description: job.definition.description,\n            schedule: job.definition.schedule,\n            enabled: job.enabled,\n            state: job.state,\n            lastRunAt: job.lastRunAt?.toISOString(),\n            nextRunAt: job.nextRunAt?.toISOString(),\n            lastDurationMs: job.lastDurationMs,\n            lastError: job.lastError,\n            totalRuns: job.totalRuns,\n            totalFailures: job.totalFailures\n        };\n    }\n}\n"],"mappings":";;;;;;;;AAAA,IAAM,sBAAM,IAAI,IAAI;CAAC;CAAQ;CAAK;CAAO;AAAI,CAAC;AAC9C,IAAM,qBAAK,IAAI,IAAI;CAAC;CAAS;CAAK;CAAM;AAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoC9C,SAAgB,gBAAgB,OAAgD;CAC5E,IAAI,UAAU,KAAA,GAAW,OAAO,KAAA;CAChC,MAAM,UAAU,MAAM,KAAK,CAAC,CAAC,YAAY;CACzC,IAAI,IAAI,IAAI,OAAO,GAAG,OAAO;CAC7B,IAAI,GAAG,IAAI,OAAO,GAAG,OAAO;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;AChBA,IAAa,qBAAqB;;;;;;AA4BlC,SAAgB,uBAAuB,MAAe,QAAQ,KAAmC;CAI7F,IAAI,IAAI,yBAAyB,OAAO,KAAA;CAExC,IAAI,IAAI,WAAW;EACf,MAAM,UAAU,CAAC,WAAW;EAC5B,IAAI,IAAI,YAAY,QAAQ,KAAK,YAAY;EAC7C,IAAI,IAAI,iBAAiB,QAAQ,KAAK,iBAAiB;EACvD,OAAO;GAAE,UAAU;GAAa;EAAQ;CAC5C;CAEA,IAAI,IAAI,eACJ,OAAO;EAAE,UAAU;EAAkB,SAAS,CAAC,eAAe;CAAE;CAGpE,IAAI,IAAI,0BACJ,OAAO;EAAE,UAAU;EAAc,SAAS,CAAC,0BAA0B;CAAE;CAG3E,IAAI,gBAAgB,IAAI,MAAM,MAAM,MAChC,OAAO;EAAE,UAAU;EAAU,SAAS,CAAC,QAAQ;CAAE;AAIzD;;AAGA,IAAM,iBAAiB;;;;;;;;;;AAWvB,SAAgB,wBACZ,MACA,MAAe,QAAQ,KACO;CAC9B,IAAI,IAAI,aAAa,cAAc,OAAO,KAAA;CAC1C,IAAI,gBAAgB,IAAA,wBAAuB,MAAM,MAAM,OAAO,KAAA;CAE9D,MAAM,UAAU,KAAK,QAAQ,QAAQ,IAAI,OAAO,CAAC,CAAC,KAAK,QAAQ,IAAI,EAAE;CACrE,IAAI,QAAQ,WAAW,GAAG,OAAO,KAAA;CAEjC,MAAM,UAAU,uBAAuB,GAAG;CAC1C,IAAI,CAAC,SAAS,OAAO,KAAA;CAErB,MAAM,QAAQ,QAAQ,MAAM,GAAG,cAAc;CAC7C,MAAM,OAAO,QAAQ,SAAS,MAAM,SAC9B,GAAG,MAAM,KAAK,IAAI,EAAE,KAAK,QAAQ,SAAS,MAAM,OAAO,UACvD,MAAM,KAAK,IAAI;CAIrB,OAAO;EACH,SAAA,UAHsB,QAAQ,SAAS,8FAA8F,QAAQ,OAAO,iCAAiC,KAAK,sGAAsG,QAAQ,SAAS,sIAAsI,mBAAmB;EAI1c,MAAM;GACF,UAAU,QAAQ;GAClB,SAAS,QAAQ;GACjB,MAAM;EACV;CACJ;AACJ;;;;;;;;;;;;;;ACtGA,SAAS,gBAAgB,OAAe,KAAa,KAAuB;CACxE,MAAM,0BAAU,IAAI,IAAY;CAChC,KAAK,MAAM,WAAW,MAAM,MAAM,GAAG,GAAG;EACpC,MAAM,UAAU,QAAQ,KAAK;EAC7B,IAAI,YAAY,KACZ,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,KAAK,QAAQ,IAAI,CAAC;OAC3C,IAAI,QAAQ,SAAS,GAAG,GAAG;GAC9B,MAAM,CAAC,UAAU,WAAW,QAAQ,MAAM,GAAG;GAC7C,MAAM,OAAO,SAAS,SAAS,EAAE;GACjC,IAAI,MAAM,IAAI,KAAK,QAAQ,GACvB,MAAM,IAAI,MAAM,uBAAuB,QAAQ,mBAAmB,MAAM,EAAE;GAE9E,IAAI,QAAQ;GACZ,IAAI,MAAM;GACV,IAAI,aAAa,KACb,IAAI,SAAS,SAAS,GAAG,GAAG;IACxB,MAAM,CAAC,GAAG,KAAK,SAAS,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM;IAC7C,QAAQ;IACR,MAAM;GACV,OACI,QAAQ,SAAS,UAAU,EAAE;GAGrC,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,KAAK,MAAM,QAAQ,IAAI,CAAC;EAC1D,OAAO,IAAI,QAAQ,SAAS,GAAG,GAAG;GAC9B,MAAM,CAAC,GAAG,KAAK,QAAQ,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM;GAC5C,KAAK,IAAI,IAAI,GAAG,KAAK,GAAG,KAAK,QAAQ,IAAI,CAAC;EAC9C,OAAO;GACH,MAAM,MAAM,SAAS,SAAS,EAAE;GAChC,IAAI,MAAM,GAAG,GACT,MAAM,IAAI,MAAM,kBAAkB,QAAQ,mBAAmB,MAAM,EAAE;GAEzE,QAAQ,IAAI,GAAG;EACnB;CACJ;CACA,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC;AAC5C;;;;;AAMA,SAAgB,uBAAuB,UAAsE;CACzG,IAAI,CAAC,YAAY,OAAO,aAAa,UACjC,OAAO;EAAE,OAAO;EACxB,QAAQ;CAAsC;CAE1C,MAAM,QAAQ,SAAS,KAAK,CAAC,CAAC,MAAM,KAAK;CACzC,IAAI,MAAM,WAAW,GACjB,OAAO;EAAE,OAAO;EACxB,QAAQ,0BAA0B,MAAM;CAAS;CAE7C,MAAM,cAA0C;EAC5C;GAAC;GAAU;GAAG;EAAE;EAChB;GAAC;GAAQ;GAAG;EAAE;EACd;GAAC;GAAgB;GAAG;EAAE;EACtB;GAAC;GAAS;GAAG;EAAE;EACf;GAAC;GAAe;GAAG;EAAC;CACxB;CACA,KAAK,IAAI,IAAI,GAAG,IAAI,GAAG,KAAK;EACxB,MAAM,CAAC,MAAM,KAAK,OAAO,YAAY;EACrC,IAAI;GACA,MAAM,SAAS,gBAAgB,MAAM,IAAI,KAAK,GAAG;GACjD,IAAI,OAAO,WAAW,GAClB,OAAO;IAAE,OAAO;IAChC,QAAQ,GAAG,KAAK,UAAU,MAAM,GAAG;GAAsB;GAE7C,KAAK,MAAM,KAAK,QACZ,IAAI,IAAI,OAAO,IAAI,KACf,OAAO;IAAE,OAAO;IACpC,QAAQ,GAAG,KAAK,eAAe,EAAE,iBAAiB,IAAI,GAAG,IAAI;GAAG;EAGxD,SAAS,KAAK;GACV,OAAO;IAAE,OAAO;IAC5B,QAAQ,GAAG,KAAK,UAAU,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;GAAI;EACrE;CACJ;CACA,OAAO,EAAE,OAAO,KAAK;AACzB;;AAYA,SAAS,gBAAgB,YAAgC;CACrD,MAAM,QAAQ,WAAW,KAAK,CAAC,CAAC,MAAM,KAAK;CAC3C,IAAI,MAAM,SAAS,GACf,MAAM,IAAI,MAAM,6BAA6B,WAAW,sBAAsB;CAElF,MAAM,CAAC,UAAU,WAAW,UAAU,UAAU,YAAY;CAC5D,OAAO;EACH,SAAS,gBAAgB,UAAU,GAAG,EAAE;EACxC,OAAO,gBAAgB,WAAW,GAAG,EAAE;EACvC,MAAM,gBAAgB,UAAU,GAAG,EAAE;EACrC,QAAQ,gBAAgB,UAAU,GAAG,EAAE;EACvC,MAAM,gBAAgB,UAAU,GAAG,CAAC;CACxC;AACJ;;;;;;;;;AAUA,SAAgB,gBAAgB,MAAuB;CACnD,IAAI;EACA,IAAI,KAAK,eAAe,SAAS,EAAE,UAAU,KAAK,CAAC;EACnD,OAAO;CACX,QAAQ;EACJ,OAAO;CACX;AACJ;AAWA,IAAM,6BAAa,IAAI,IAAiC;AACxD,IAAM,MAA8B;CAAE,KAAK;CAAG,KAAK;CAAG,KAAK;CAAG,KAAK;CAAG,KAAK;CAAG,KAAK;CAAG,KAAK;AAAE;AAE7F,SAAS,YAAY,WAAiB,MAAyB;CAC3D,IAAI,YAAY,WAAW,IAAI,IAAI;CACnC,IAAI,CAAC,WAAW;EACZ,YAAY,IAAI,KAAK,eAAe,SAAS;GACzC,UAAU;GACV,WAAW;GACX,SAAS;GACT,OAAO;GACP,KAAK;GACL,MAAM;GACN,QAAQ;EACZ,CAAC;EACD,WAAW,IAAI,MAAM,SAAS;CAClC;CACA,MAAM,QAAgC,CAAC;CACvC,KAAK,MAAM,QAAQ,UAAU,cAAc,SAAS,GAAG,MAAM,KAAK,QAAQ,KAAK;CAC/E,OAAO;EACH,QAAQ,OAAO,MAAM,MAAM;EAC3B,MAAM,OAAO,MAAM,IAAI;EACvB,KAAK,OAAO,MAAM,GAAG;EACrB,OAAO,OAAO,MAAM,KAAK;EACzB,KAAK,IAAI,MAAM,YAAY,UAAU,OAAO;CAChD;AACJ;;;;;;;;AASA,SAAS,kBAAkB,WAAiB,QAAoB,MAAwB;CACpF,MAAM,OAAkB,OAClB,YAAY,WAAW,IAAI,IAC3B;EACE,QAAQ,UAAU,WAAW;EAC7B,MAAM,UAAU,SAAS;EACzB,KAAK,UAAU,QAAQ;EACvB,OAAO,UAAU,SAAS,IAAI;EAC9B,KAAK,UAAU,OAAO;CAC1B;CACJ,OAAO,OAAO,OAAO,SAAS,KAAK,KAAK,KACjC,OAAO,KAAK,SAAS,KAAK,GAAG,KAC7B,OAAO,KAAK,SAAS,KAAK,GAAG,KAC7B,OAAO,MAAM,SAAS,KAAK,IAAI,KAC/B,OAAO,QAAQ,SAAS,KAAK,MAAM;AAC9C;;;;;;;;;AAUA,IAAM,0BAA0B;;;;;AAMhC,SAAgB,oBAAoB,YAAoB,OAAa,UAAyB;CAC1F,MAAM,SAAS,gBAAgB,UAAU;CAGzC,MAAM,YAAY,IAAI,KAAK,KAAK;CAChC,UAAU,WAAW,GAAG,CAAC;CACzB,UAAU,WAAW,UAAU,WAAW,IAAI,CAAC;CAE/C,KAAK,IAAI,IAAI,GAAG,IAAI,yBAAyB,KAAK;EAC9C,IAAI,kBAAkB,WAAW,QAAQ,QAAQ,GAC7C,OAAO;EAEX,UAAU,WAAW,UAAU,WAAW,IAAI,CAAC;CACnD;CAaA,MAAM,IAAI,MACN,oBAAoB,WAAW,gCAC5B,KAAK,MAAM,0BAA0B,MAAM,EAAE,YAAY,MAAM,YAAY,EAAE,qFAEpF;AACJ;;;;;;;;;;;;;;;;;AAkBA,SAAgB,mBAAmB,YAAoB,MAAY,IAAU,UAAqC;CAC9G,MAAM,SAAS,gBAAgB,UAAU;CAEzC,MAAM,YAAY,IAAI,KAAK,EAAE;CAC7B,UAAU,WAAW,GAAG,CAAC;CAEzB,KAAK,IAAI,IAAI,GAAG,IAAI,2BAA2B,UAAU,QAAQ,KAAK,KAAK,QAAQ,GAAG,KAAK;EACvF,IAAI,kBAAkB,WAAW,QAAQ,QAAQ,GAC7C,OAAO;EAEX,UAAU,WAAW,UAAU,WAAW,IAAI,CAAC;CACnD;AAGJ;AAIA,IAAM,mBAAmB;;;;;AAMzB,IAAM,2BAA2B;;;;;;AAOjC,IAAM,qBAAqB;AAmC3B,IAAa,gBAAb,MAA2B;CACvB,uBAAe,IAAI,IAA2B;CAC9C,2BAAmB,IAAI,IAA6B;CACpD,UAAkB;CAClB;CACA;;;;;;;;;CAUA,UAAU,QAAkC;EACxC,KAAK,SAAS;CAClB;;;;;;CAOA,SAAS,OAAwB;EAC7B,KAAK,QAAQ;CACjB;;;;;;;;;;CAWA,aAAa,YAAmC;EAC5C,KAAK,MAAM,UAAU,YAAY;GAE7B,MAAM,aAAa,uBAAuB,OAAO,WAAW,QAAQ;GACpE,IAAI,CAAC,WAAW,OAAO;IACnB,OAAO,MAAM,yBAAyB,OAAO,GAAG,uBAAuB,OAAO,WAAW,SAAS,MAAM,WAAW,QAAQ;IAO3H,KAAK,SAAS,IAAI,OAAO,IAAI;KACzB,IAAI,OAAO;KACX,MAAM,OAAO,WAAW,QAAQ,OAAO;KACvC,UAAU,OAAO,WAAW;KAC5B,QAAQ,WAAW;IACvB,CAAC;IACD;GACJ;GAMA,IAAI,OAAO,WAAW,aAAa,KAAA,KAAa,CAAC,gBAAgB,OAAO,WAAW,QAAQ,GAAG;IAC1F,MAAM,SACF,qBAAqB,OAAO,WAAW,SAAS;IAEpD,OAAO,MAAM,yBAAyB,OAAO,GAAG,KAAK,OAAO,EAAE;IAC9D,KAAK,SAAS,IAAI,OAAO,IAAI;KACzB,IAAI,OAAO;KACX,MAAM,OAAO,WAAW,QAAQ,OAAO;KACvC,UAAU,OAAO,WAAW;KAC5B;IACJ,CAAC;IACD;GACJ;GAEA,KAAK,SAAS,OAAO,OAAO,EAAE;GAG9B,IADiB,KAAK,KAAK,IAAI,OAAO,EAClC,GAAU;IACV,OAAO,KAAK,kCAAkC,OAAO,GAAG,gBAAgB;IACxE,KAAK,QAAQ,OAAO,EAAE;GAC1B;GAEA,MAAM,UAAU,OAAO,WAAW,YAAY;GAE9C,KAAK,KAAK,IAAI,OAAO,IAAI;IACrB,IAAI,OAAO;IACX,YAAY,OAAO;IACnB;IACA,OAAO,UAAU,SAAS;IAC1B,WAAW;IACX,eAAe;IACf,MAAM,CAAC;IACP,WAAW;GACf,CAAC;GAGD,IAAI,KAAK,WAAW,SAChB,KAAK,aAAa,OAAO,EAAE;EAEnC;CACJ;;;;CAKA,QAAc;EACV,IAAI,KAAK,SAAS;EAClB,KAAK,UAAU;EAGf,IAAI,KAAK,OACL,KAAK,MAAM,cAAc,CAAC,CAAC,MAAM,UAAU;GACvC,KAAK,MAAM,CAAC,OAAO,SAAS,OAAO;IAC/B,MAAM,MAAM,KAAK,KAAK,IAAI,KAAK;IAC/B,IAAI,KAAK;KACL,IAAI,YAAY,KAAK;KACrB,IAAI,gBAAgB,KAAK;KACzB,IAAI,KAAK,WACL,IAAI,YAAY,IAAI,KAAK,KAAK,SAAS;IAE/C;GACJ;EACJ,CAAC,CAAC,CAAC,OAAO,QAAQ;GACd,OAAO,KAAK,iDAAiD,EAAE,OAAO,IAAI,CAAC;EAC/E,CAAC;EAGL,KAAK,MAAM,CAAC,IAAI,QAAQ,KAAK,MACzB,IAAI,IAAI,SACJ,KAAK,aAAa,EAAE;EAG5B,IAAI,CAAC,KAAK,OACN,OAAO,KAAK,2HAA2H;EAE3I,KAAK,kBAAkB;EAKvB,KAAU,mBAAmB;EAE7B,OAAO,KAAK,iCAAiC,KAAK,KAAK,KAAK,QAAQ;CACxE;;;;;;;CAQA,OAAa;EACT,KAAK,UAAU;EACf,KAAK,MAAM,CAAC,OAAO,KAAK,MACpB,KAAK,QAAQ,EAAE;CAEvB;;;;CAKA,WAA4B;EACxB,OAAO,CAAC,GAAG,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,QAAQ,KAAK,SAAS,GAAG,CAAC;CAClE;;;;;;;;CASA,mBAAsC;EAClC,OAAO,CAAC,GAAG,KAAK,SAAS,OAAO,CAAC;CACrC;;;;CAKA,OAAO,IAAuC;EAC1C,MAAM,MAAM,KAAK,KAAK,IAAI,EAAE;EAC5B,OAAO,MAAM,KAAK,SAAS,GAAG,IAAI,KAAA;CACtC;;;;CAKA,WAAW,IAAY,OAAmC;EACtD,MAAM,MAAM,KAAK,KAAK,IAAI,EAAE;EAC5B,IAAI,CAAC,KAAK,OAAO,CAAC;EAClB,MAAM,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,QAAQ;EACnC,OAAO,QAAQ,KAAK,MAAM,GAAG,KAAK,IAAI;CAC1C;;;;;CAMA,MAAM,iBAAiB,IAAY,OAA4C;EAC3E,IAAI,KAAK,OAAO;GACZ,MAAM,SAAS,MAAM,KAAK,MAAM,UAAU,IAAI,KAAK;GACnD,IAAI,OAAO,SAAS,GAAG,OAAO;EAClC;EAEA,OAAO,KAAK,WAAW,IAAI,KAAK;CACpC;;;;CAKA,cAAc,IAAY,SAA6C;EACnE,MAAM,MAAM,KAAK,KAAK,IAAI,EAAE;EAC5B,IAAI,CAAC,KAAK,OAAO,KAAA;EAEjB,IAAI,UAAU;EAEd,IAAI,WAAW,KAAK,SAAS;GACzB,IAAI,QAAQ;GACZ,KAAK,aAAa,EAAE;EACxB,OAAO,IAAI,CAAC,SAAS;GACjB,KAAK,QAAQ,EAAE;GACf,IAAI,QAAQ;EAChB;EAEA,OAAO,KAAK,SAAS,GAAG;CAC5B;;;;;;;;CASA,MAAM,WAAW,IAAkD;EAC/D,MAAM,MAAM,KAAK,KAAK,IAAI,EAAE;EAC5B,IAAI,CAAC,KAAK,OAAO,KAAA;EAGjB,IAAI,IAAI,WAAW;GACf,OAAO,KAAK,sCAAsC,GAAG,sBAAsB;GAC3E,OAAO,KAAK,WAAW,KAAK,qBAAqB,IAAI;EACzD;EAEA,OAAO,KAAK,WAAW,KAAK,IAAI;CACpC;;;;;;;;;;;;;;;CAgBA,WAAmB,KAAoB,QAAgB,QAAkC;EACrF,MAAM,uBAAM,IAAI,KAAK,EAAA,CAAE,YAAY;EACnC,MAAM,WAA4B;GAC9B,OAAO,IAAI;GACX,WAAW;GACX,YAAY;GACZ,YAAY;GACZ,SAAS;GACT,QAAQ;IAAE,SAAS;IAAM;GAAO;GAChC,MAAM,CAAC,YAAY,WAAW,sBAAsB,sCAAsC,QAAQ;GAClG;EACJ;EAEA,IAAI,KAAK,KAAK,QAAQ;EACtB,IAAI,IAAI,KAAK,SAAS,kBAAkB,IAAI,KAAK,MAAM;EAEvD,KAAK,OAAO,UAAU,QAAQ,CAAC,CAAC,OAAO,eAAe;GAClD,OAAO,MAAM,sCAAsC,IAAI,GAAG,IAAI,EAAE,OAAO,WAAW,CAAC;EACvF,CAAC;EAED,OAAO;CACX;;;;;;;;;CAYA,oBAAkC;EAC9B,IAAI;GACA,MAAM,UAAU,wBACZ,CAAC,GAAG,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS;IAAE,IAAI,IAAI;IAAI,SAAS,IAAI;GAAQ,EAAE,CAC/E;GACA,IAAI,SACA,OAAO,KAAK,QAAQ,SAAS,QAAQ,IAAI;EAEjD,QAAQ,CAER;CACJ;;;;;;;;;;;CAYA,aAAqB,IAAkB;EACnC,MAAM,MAAM,KAAK,KAAK,IAAI,EAAE;EAC5B,IAAI,CAAC,OAAO,CAAC,IAAI,WAAW,CAAC,KAAK,SAAS;EAG3C,KAAK,QAAQ,EAAE;EAEf,IAAI;GACA,MAAM,sBAAM,IAAI,KAAK;GACrB,MAAM,UAAU,oBAAoB,IAAI,WAAW,UAAU,KAAK,IAAI,WAAW,QAAQ;GACzF,IAAI,YAAY;GAEhB,MAAM,WAAW,QAAQ,QAAQ,IAAI,IAAI,QAAQ;GAGjD,MAAM,QAAQ,KAAK,IAAI,UAAU,wBAAwB;GAQzD,IAAI,QAAQ,oBAAoB;IAC5B,MAAM,MAAM,iBAAiB;KACzB,IAAI,KAAK,WAAW,IAAI,SAAS,KAAK,aAAa,EAAE;IACzD,GAAG,kBAAkB;IACrB,IAAI,OAAO,OAAO,QAAQ,YAAY,WAAW,KAC7C,IAAI,MAAM;IAEd,IAAI,UAAU;IACd;GACJ;GAEA,MAAM,QAAQ,WAAW,YAAY;IAGjC,IAAI,CAAC,IAAI,WAAW,CAAC,KAAK,SAAS;IAGnC,IAAI,IAAI,WAAW;KACf,OAAO,KAAK,qCAAqC,GAAG,sCAAsC;KAI1F,KAAK,WAAW,KAAK,qBAAqB,KAAK;KAE/C,KAAK,aAAa,EAAE;KACpB;IACJ;IASA,IAAI,KAAK,IAAI,IAAI,QAAQ,QAAQ,GAAG;KAChC,KAAK,aAAa,EAAE;KACpB;IACJ;IASA,IAAI,KAAK,OAAO,aAAa;KACzB,IAAI,UAAU;KACd,IAAI;MACA,UAAU,MAAM,KAAK,MAAM,YAAY,IAAI,QAAQ,YAAY,CAAC;KACpE,SAAS,KAAK;MACV,OAAO,KAAK,iCAAiC,GAAG,4BAA4B,EAAE,OAAO,IAAI,CAAC;KAC9F;KACA,IAAI,CAAC,SAAS;MACV,OAAO,KAAK,eAAe,QAAQ,YAAY,EAAE,QAAQ,GAAG,yCAAyC;MACrG,IAAI,KAAK,WAAW,IAAI,SACpB,KAAK,aAAa,EAAE;MAExB;KACJ;IACJ;IAEA,MAAM,KAAK,WAAW,KAAK,KAAK;IAGhC,IAAI,KAAK,WAAW,IAAI,SACpB,KAAK,aAAa,EAAE;GAE5B,GAAG,KAAK;GAIR,IAAI,SAAS,OAAO,UAAU,YAAY,WAAW,OACjD,MAAM,MAAM;GAGhB,IAAI,UAAU;EAClB,SAAS,KAAc;GACnB,OAAO,MAAM,8BAA8B,GAAG,IAAI,EAAE,OAAO,IAAI,CAAC;GAChE,IAAI,QAAQ;GACZ,IAAI,YAAY,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;EACnE;CACJ;;;;;;;;;;;;;;;;;CAkBA,MAAc,qBAAoC;EAC9C,MAAM,aAAa,CAAC,GAAG,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,QACvC,QAAO,IAAI,YAAY,IAAI,WAAW,wBAAwB,KAAK,CACvE;EACA,IAAI,WAAW,WAAW,GAAG;EAM7B,IAAI,CAAC,KAAK,OAAO,aAAa;GAC1B,OAAO,KACH,oCAAoC,WAAW,OAAO,2JAE1D;GACA;EACJ;EAEA,MAAM,sBAAM,IAAI,KAAK;EAErB,KAAK,MAAM,OAAO,YACd,IAAI;GACA,IAAI,CAAC,KAAK,WAAW,CAAC,IAAI,WAAW,IAAI,WAAW;GAEpD,MAAM,gBAAgB,IAAI,WAAW;GACrC,MAAM,uBAAO,IAAI,KAAK,IAAI,QAAQ,IAAI,gBAAgB,GAAI;GAC1D,MAAM,OAAO,mBAAmB,IAAI,WAAW,UAAU,MAAM,KAAK,IAAI,WAAW,QAAQ;GAC3F,IAAI,CAAC,MAAM;GAEX,MAAM,UAAU,KAAK,YAAY;GAIjC,IAAI;GACJ,IAAI;IACA,UAAU,MAAM,KAAK,MAAM,YAAY,IAAI,IAAI,OAAO;GAC1D,SAAS,KAAK;IAKV,OAAO,KAAK,oCAAoC,IAAI,GAAG,wBAAwB,EAAE,OAAO,IAAI,CAAC;IAC7F;GACJ;GAEA,IAAI,CAAC,SAAS;GAEd,MAAM,SAAS,KAAK,OAAO,IAAI,QAAQ,IAAI,KAAK,QAAQ,KAAK,GAAI;GACjE,OAAO,KAAK,kCAAkC,QAAQ,QAAQ,IAAI,GAAG,KAAK,OAAO,QAAQ;GAEzF,MAAM,KAAK,WAAW,KAAK,OAAO,kCAAkC,QAAQ,IAAI,OAAO,QAAQ;EACnG,SAAS,KAAK;GACV,OAAO,MAAM,+BAA+B,IAAI,GAAG,IAAI,EAAE,OAAO,IAAI,CAAC;EACzE;CAER;;;;CAKA,QAAgB,IAAkB;EAC9B,MAAM,MAAM,KAAK,KAAK,IAAI,EAAE;EAC5B,IAAI,KAAK,SAAS;GACd,aAAa,IAAI,OAAO;GACxB,IAAI,UAAU,KAAA;GACd,IAAI,YAAY,KAAA;EACpB;CACJ;;;;;;;;;;CAWA,MAAc,WACV,KACA,QACA,SACwB;EACxB,MAAM,4BAAY,IAAI,KAAK;EAK3B,MAAM,eAAyB,UAAU,CAAC,OAAO,IAAI,CAAC;EAGtD,IAAI,YAAY;EAMhB,MAAM,QAAQ,IAAI,gBAAgB;EAElC,MAAM,MAAsB;GACxB,OAAO,IAAI;GACX,aAAa;GACb,QAAQ,MAAM;GACd,MAAM,GAAG,SAAoB;IACzB,MAAM,OAAO,KAAK,KAAK,MACnB,OAAO,MAAM,WAAW,IAAI,KAAK,UAAU,CAAC,CAChD,CAAC,CAAC,KAAK,GAAG;IACV,aAAa,KAAK,IAAI;GAC1B;GAKA,QAAQ,KAAK;EACjB;EAEA,IAAI,QAAQ;EACZ,IAAI,YAAY;EAChB,IAAI;EAEJ,IAAI,UAAU;EACd,IAAI;EACJ,IAAI;EAEJ,IAAI;GAEA,MAAM,WAAW,IAAI,WAAW,kBAAkB,OAAO;GACzD,MAAM,iBAAiB,QAAQ,QAAQ,IAAI,WAAW,QAAQ,GAAG,CAAC;GAClE,IAAI;GACJ,MAAM,iBAAiB,IAAI,SAAgB,GAAG,WAAW;IACrD,gBAAgB,iBACN;KAIF,MAAM,sBAAM,IAAI,MAAM,aAAa,IAAI,GAAG,oBAAoB,QAAQ,GAAG,CAAC;KAC1E,uBAAO,IAAI,MAAM,aAAa,IAAI,GAAG,oBAAoB,QAAQ,GAAG,CAAC;IACzE,GACA,OACJ;GACJ,CAAC;GAED,IAAI;IACA,SAAS,MAAM,QAAQ,KAAK,CAAC,gBAAgB,cAAc,CAAC;GAChE,UAAU;IACN,aAAa,aAAc;GAC/B;EACJ,SAAS,KAAc;GACnB,UAAU;GAMV,QAAQ,oBAAoB,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;GAC5E,IAAI;EACR,UAAU;GAEN,IAAI,YAAY;EACpB;EAEA,MAAM,6BAAa,IAAI,KAAK;EAC5B,MAAM,aAAa,WAAW,QAAQ,IAAI,UAAU,QAAQ;EAE5D,IAAI,QAAQ,UAAW,IAAI,UAAU,SAAS,aAAc;EAC5D,IAAI,iBAAiB;EACrB,IAAI,YAAY;EAEhB,MAAM,WAA4B;GAC9B,OAAO,IAAI;GACX,WAAW,UAAU,YAAY;GACjC,YAAY,WAAW,YAAY;GACnC;GACA;GACA;GACA,QAAQ,WAAW,KAAA,IAAY,SAAS,KAAA;GACxC,MAAM;GACN;EACJ;EAGA,IAAI,KAAK,KAAK,QAAQ;EACtB,IAAI,IAAI,KAAK,SAAS,kBAClB,IAAI,KAAK,MAAM;EAInB,IAAI,KAAK,OACL,KAAK,MAAM,UAAU,QAAQ,CAAC,CAAC,OAAO,eAAe;GACjD,OAAO,MAAM,qCAAqC,IAAI,GAAG,IAAI,EAAE,OAAO,WAAW,CAAC;EACtF,CAAC;EAGL,IAAI,SACA,OAAO,KAAK,aAAa,IAAI,GAAG,iBAAiB,WAAW,GAAG;OAE/D,OAAO,MAAM,aAAa,IAAI,GAAG,cAAc,WAAW,MAAM,OAAO;EAG3E,OAAO;CACX;CAEA,SAAiB,KAAmC;EAChD,OAAO;GACH,IAAI,IAAI;GAGR,MAAM,IAAI,WAAW,QAAQ,IAAI;GACjC,aAAa,IAAI,WAAW;GAC5B,UAAU,IAAI,WAAW;GACzB,SAAS,IAAI;GACb,OAAO,IAAI;GACX,WAAW,IAAI,WAAW,YAAY;GACtC,WAAW,IAAI,WAAW,YAAY;GACtC,gBAAgB,IAAI;GACpB,WAAW,IAAI;GACf,WAAW,IAAI;GACf,eAAe,IAAI;EACvB;CACJ;AACJ"}

package/dist/cron-store-BYGZFNWk.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cron-store-BYGZFNWk.js","names":[],"sources":["../src/cron/cron-store.ts"],"sourcesContent":["import type { CronJobLogEntry } from \"@rebasepro/types\";\nimport type { DataDriver } from \"@rebasepro/types\";\nimport { isSQLAdmin } from \"@rebasepro/types\";\nimport { revokeInternalTableSql } from \"@rebasepro/common\";\nimport { logger } from \"../utils/logger.js\";\nimport { createDdlBootstrapper, hasInCauseChain } from \"../boot/ddl-bootstrap.js\";\n\n/**\n * Persistence layer for cron job execution logs.\n *\n * Uses the DataDriver's `admin.executeSql` capability to store logs in a\n * `rebase.cron_logs` table. Falls back gracefully if the driver doesn't\n * support SQL (e.g. MongoDB) — in that case, no persistence occurs.\n */\nexport interface CronStore {\n    /** Ensure the backing table exists. Called once on startup. */\n    ensureTable(): Promise<void>;\n\n    /** Persist a single log entry after execution. */\n    insertLog(entry: CronJobLogEntry): Promise<void>;\n\n    /**\n     * Fetch the most recent logs for a job.\n     * @param jobId  The job identifier\n     * @param limit  Max entries to return (default 50)\n     * @returns Logs sorted newest-first\n     */\n    fetchLogs(jobId: string, limit?: number): Promise<CronJobLogEntry[]>;\n\n    /**\n     * Fetch aggregate stats for all jobs (totalRuns, totalFailures, lastRunAt).\n     * Used to seed in-memory counters on startup.\n     */\n    fetchJobStats(): Promise<Map<string, { totalRuns: number; totalFailures: number; lastRunAt?: string }>>;\n\n    /**\n     * Atomically claim a scheduled run slot for a job.\n     *\n     * `slot` is the *scheduled* fire time (ISO string) derived from the cron\n     * expression — deterministic across instances regardless of timer drift,\n     * so all instances contend on the same (jobId, slot) key. Exactly one\n     * caller wins the insert against the unique constraint and executes;\n     * the rest skip.\n     *\n     * Fails open (returns true) on unexpected store errors, so a broken\n     * claims table degrades to uncoordinated execution rather than silently\n     * never running jobs.\n     *\n     * Optional so custom stores written against the pre-claims interface\n     * keep working — the scheduler treats a missing implementation as\n     * uncoordinated (always run).\n     */\n    tryClaimRun?(jobId: string, slot: string): Promise<boolean>;\n}\n\n// ─── SQL-based implementation ────────────────────────────────────────\n\nconst TABLE = \"rebase.cron_logs\";\nconst CLAIMS_TABLE = \"rebase.cron_claims\";\n\n/** Claims older than this are garbage-collected on startup. */\nconst CLAIM_RETENTION_DAYS = 7;\n\n/**\n * How far ahead a claim may legitimately sit. Slots are claimed as they fire,\n * so anything beyond this is a clock-skewed peer at best and a stranded claim\n * at worst; see the sweep in `ensureTable`.\n */\nconst FUTURE_CLAIM_SKEW_MINUTES = 2;\n\n/**\n * Detect a unique-constraint violation anywhere in an error's cause chain.\n * Match the SQLSTATE code, never message text. Also covers SQLite\n * (\"UNIQUE constraint failed\") and MySQL (ER_DUP_ENTRY 1062) for future SQL\n * drivers.\n *\n * Distinct from `isConcurrentDdlRace` in `boot/ddl-bootstrap.ts`, which shares\n * the 23505 code but asks a different question — that one is about a losing\n * `CREATE`, this one is about a losing claim, and only the latter means\n * \"another instance already has this slot\".\n */\nfunction isUniqueViolation(err: unknown): boolean {\n    return hasInCauseChain(err, (e) =>\n        e.code === \"23505\" ||\n        e.errno === 1062 ||\n        (typeof e.message === \"string\" && e.message.includes(\"UNIQUE constraint failed\"))\n    );\n}\n\nexport function createCronStore(driver: DataDriver): CronStore | undefined {\n    const admin = driver.admin;\n    if (!isSQLAdmin(admin)) {\n        logger.warn(\"⚠️ [cron-store] DataDriver does not support SQL admin — cron logs will not be persisted.\");\n        return undefined;\n    }\n\n    const exec = (sqlText: string, options?: { params?: unknown[] }) =>\n        admin.executeSql(sqlText, options?.params ? { params: options.params } : undefined);\n\n    const ddl = createDdlBootstrapper(exec, \"cron-store\");\n\n    return {\n        async ensureTable(): Promise<void> {\n            // Creation. Every statement here is idempotent, so losing the race\n            // to a peer that booted at the same moment is survivable — but only\n            // if the loser retries rather than abandoning everything below it.\n            // One step each, so a hard failure on any one of them does not take\n            // the others with it. The claims table in particular must not be\n            // lost because an index on the *logs* table could not be built.\n            await ddl.ensureObject(\"Creating schema rebase\", \"CREATE SCHEMA IF NOT EXISTS rebase\");\n\n            await ddl.ensureObject(`Creating ${TABLE}`, `\n                CREATE TABLE IF NOT EXISTS ${TABLE} (\n                    id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,\n                    job_id TEXT NOT NULL,\n                    started_at TIMESTAMPTZ NOT NULL,\n                    finished_at TIMESTAMPTZ NOT NULL,\n                    duration_ms INTEGER NOT NULL,\n                    success BOOLEAN NOT NULL DEFAULT true,\n                    error TEXT,\n                    result JSONB,\n                    logs JSONB,\n                    manual BOOLEAN NOT NULL DEFAULT false\n                )\n            `);\n\n            await ddl.ensureObject(\"Creating idx_cron_logs_job\", `\n                CREATE INDEX IF NOT EXISTS idx_cron_logs_job\n                ON ${TABLE}(job_id, started_at DESC)\n            `);\n\n            await ddl.ensureObject(`Creating ${CLAIMS_TABLE}`, `\n                CREATE TABLE IF NOT EXISTS ${CLAIMS_TABLE} (\n                    job_id TEXT NOT NULL,\n                    slot TIMESTAMPTZ NOT NULL,\n                    claimed_at TIMESTAMPTZ NOT NULL DEFAULT now(),\n                    PRIMARY KEY (job_id, slot)\n                )\n            `);\n\n            // Everything from here is keyed on what actually exists, not on\n            // whether *this* instance is the one that created it. A single\n            // failure above used to abandon the rest of this method, which meant\n            // the loser of a boot race skipped the sweeps and — far worse — the\n            // privilege revocation, leaving the claims table writable by end\n            // users on an instance that reported nothing but a warning about\n            // log persistence.\n            const [logsReady, claimsReady] = await Promise.all([\n                ddl.isReadable(TABLE),\n                ddl.isReadable(CLAIMS_TABLE)\n            ]);\n\n            if (claimsReady) {\n                // Garbage-collect old claims — they are only needed while\n                // instances could still contend on the same slot.\n                await ddl.step(\"Claim retention sweep\", async () => {\n                    await exec(\n                        `DELETE FROM ${CLAIMS_TABLE} WHERE claimed_at < now() - make_interval(days => $1)`,\n                        { params: [CLAIM_RETENTION_DAYS] }\n                    );\n                });\n\n                // Drop claims for slots that have not happened yet. A slot is\n                // claimed at the moment it fires, so a future one can only come\n                // from a timer that woke early — and because claims are\n                // permanent, that claim would silently skip the real run when it\n                // finally came due. The margin keeps a legitimate claim made\n                // moments early by a clock-skewed peer.\n                await ddl.step(\"Future-slot claim sweep\", async () => {\n                    const stranded = await exec(\n                        `DELETE FROM ${CLAIMS_TABLE}\n                         WHERE slot > now() + make_interval(mins => $1)\n                         RETURNING job_id, slot`,\n                        { params: [FUTURE_CLAIM_SKEW_MINUTES] }\n                    );\n                    // A driver that does not honour RETURNING gives back\n                    // nothing; the rows are only used to report, so treat that\n                    // as \"none\".\n                    for (const row of (stranded ?? []) as { job_id: string; slot: string }[]) {\n                        logger.warn(\n                            `[cron-store] Released a claim on the future slot ${new Date(row.slot).toISOString()} ` +\n                            `for \"${row.job_id}\" — it was claimed by a timer that fired early, and would ` +\n                            \"otherwise have skipped that run\"\n                        );\n                    }\n                });\n            }\n\n            // Neither table is a collection, so neither carries RLS, while the\n            // Postgres driver's schema-wide grant reaches both. Cron logs hold\n            // job output — arbitrary application data — and a writable\n            // `cron_claims` lets any signed-in user suppress a scheduled run by\n            // claiming its slot. This is a security control, so it is re-applied\n            // by every instance on every boot, whatever else went wrong.\n            if (logsReady) {\n                await ddl.step(\"Revoking end-user access to cron_logs\", () =>\n                    exec(revokeInternalTableSql(\"rebase\", \"cron_logs\")));\n            }\n            if (claimsReady) {\n                await ddl.step(\"Revoking end-user access to cron_claims\", () =>\n                    exec(revokeInternalTableSql(\"rebase\", \"cron_claims\")));\n            }\n\n            if (logsReady && claimsReady) {\n                logger.info(\"✅ Cron logs table ready\");\n                return;\n            }\n            // Say which capability is gone, and what it costs. \"Continuing\n            // without cron log persistence\" undersold this: the claims table is\n            // the only thing stopping every instance from running every job.\n            if (!claimsReady) {\n                logger.error(\n                    `❌ [cron-store] ${CLAIMS_TABLE} is unavailable — scheduled runs cannot be coordinated. ` +\n                    \"With more than one app instance, every instance will now run every job on every tick.\"\n                );\n            }\n            if (!logsReady) {\n                logger.warn(`⚠️ [cron-store] ${TABLE} is unavailable — cron run history will not be persisted.`);\n            }\n        },\n\n        async insertLog(entry: CronJobLogEntry): Promise<void> {\n            try {\n                const resultJson = entry.result !== undefined ? JSON.stringify(entry.result) : null;\n                const logsJson = entry.logs.length > 0 ? JSON.stringify(entry.logs) : null;\n\n                await exec(\n                    `INSERT INTO ${TABLE} (job_id, started_at, finished_at, duration_ms, success, error, result, logs, manual)\n                     VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, $8::jsonb, $9)`,\n                    { params: [\n                        entry.jobId,\n                        entry.startedAt,\n                        entry.finishedAt,\n                        entry.durationMs,\n                        entry.success,\n                        entry.error || null,\n                        resultJson,\n                        logsJson,\n                        entry.manual\n                    ]}\n                );\n            } catch (err) {\n                // Non-blocking — log persistence should never crash the scheduler\n                logger.error(`[cron-store] Failed to persist log for \"${entry.jobId}\"`, { error: err });\n            }\n        },\n\n        async fetchLogs(jobId: string, limit = 50): Promise<CronJobLogEntry[]> {\n            try {\n                const rows = await exec(\n                    `SELECT job_id, started_at, finished_at, duration_ms, success, error, result, logs, manual\n                     FROM ${TABLE}\n                     WHERE job_id = $1\n                     ORDER BY started_at DESC\n                     LIMIT $2`,\n                    { params: [jobId, limit] }\n                );\n\n                return rows.map(rowToLogEntry);\n            } catch (err) {\n                logger.error(`[cron-store] Failed to fetch logs for \"${jobId}\"`, { error: err });\n                return [];\n            }\n        },\n\n        async fetchJobStats(): Promise<Map<string, { totalRuns: number; totalFailures: number; lastRunAt?: string }>> {\n            const stats = new Map<string, { totalRuns: number; totalFailures: number; lastRunAt?: string }>();\n            try {\n                const rows = await exec(`\n                    SELECT\n                        job_id,\n                        COUNT(*)::int AS total_runs,\n                        COUNT(*) FILTER (WHERE NOT success)::int AS total_failures,\n                        MAX(started_at) AS last_run_at\n                    FROM ${TABLE}\n                    GROUP BY job_id\n                `);\n\n                for (const row of rows) {\n                    stats.set(row.job_id as string, {\n                        totalRuns: row.total_runs as number,\n                        totalFailures: row.total_failures as number,\n                        lastRunAt: row.last_run_at ? new Date(row.last_run_at as string).toISOString() : undefined\n                    });\n                }\n            } catch (err) {\n                logger.error(\"[cron-store] Failed to fetch job stats\", { error: err });\n            }\n            return stats;\n        },\n\n        async tryClaimRun(jobId: string, slot: string): Promise<boolean> {\n            try {\n                const rows = await exec(\n                    `INSERT INTO ${CLAIMS_TABLE} (job_id, slot)\n                     VALUES ($1, $2)\n                     ON CONFLICT (job_id, slot) DO NOTHING\n                     RETURNING job_id`,\n                    { params: [jobId, slot] }\n                );\n                return rows.length > 0;\n            } catch (err) {\n                if (isUniqueViolation(err)) {\n                    // Another instance won the race for this slot\n                    return false;\n                }\n                // Fail open: better to risk a duplicate run than to have a\n                // broken claims table silently stop all cron execution.\n                logger.warn(`[cron-store] Claim check failed for \"${jobId}\" — running uncoordinated`, { error: err });\n                return true;\n            }\n        }\n    };\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────\n\nfunction rowToLogEntry(row: Record<string, unknown>): CronJobLogEntry {\n    return {\n        jobId: row.job_id as string,\n        startedAt: new Date(row.started_at as string).toISOString(),\n        finishedAt: new Date(row.finished_at as string).toISOString(),\n        durationMs: row.duration_ms as number,\n        success: row.success as boolean,\n        error: (row.error as string) ?? undefined,\n        result: row.result ?? undefined,\n        logs: Array.isArray(row.logs) ? row.logs : (row.logs ? (() => { try { return JSON.parse(row.logs as string); } catch { return []; } })() : []),\n        manual: row.manual as boolean\n    };\n}\n"],"mappings":"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"}

package/dist/ddl-bootstrap-CfNvxMuK.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ddl-bootstrap-CfNvxMuK.js","names":[],"sources":["../../types/src/types/backend.ts","../src/boot/ddl-bootstrap.ts"],"sourcesContent":["import type { CollectionConfig, FilterValues, WhereFilterOp } from \"./collections\";\nimport type { CollectionCallbacks } from \"./entity_callbacks\";\nimport type { OrderByTuple } from \"./filter-operators\";\nimport type { LogicalCondition } from \"../controllers/data\";\nimport type { AuthAdapter } from \"./auth_adapter\";\nimport type { HistoryConfig } from \"../controllers/client\";\nimport type { ChannelBusSetting } from \"./channel_bus\";\nimport type { SchemaEditingAdmin } from \"./schema_editing\";\n\n// =============================================================================\n// DATABASE CONNECTION INTERFACES\n// =============================================================================\n\n/**\n * Abstract database connection interface.\n * Represents a connection to any database system.\n */\nexport interface DatabaseConnection {\n    /**\n     * Type identifier for this database (e.g., 'postgres', 'mongodb', 'mysql')\n     */\n    readonly type: string;\n\n    /**\n     * Whether the connection is currently active\n     */\n    readonly isConnected?: boolean;\n\n    /**\n     * Close the database connection and release resources.\n     */\n    close?(): Promise<void>;\n}\n\n// =============================================================================\n// QUERY BUILDING INTERFACES\n// =============================================================================\n\n/**\n * A single filter condition for database queries\n */\nexport interface QueryFilter {\n    field: string;\n    operator: WhereFilterOp;\n    value: unknown;\n}\n\n/**\n * Options for fetching a collection of entities\n */\nexport interface FetchCollectionOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */\n    orderBy?: string | OrderByTuple[];\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    offset?: number;\n    startAfter?: unknown;\n    searchString?: string;\n    databaseId?: string;\n    collection?: CollectionConfig;\n}\n\n/**\n * Options for searching entities\n */\nexport interface SearchOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */\n    orderBy?: string | OrderByTuple[];\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    databaseId?: string;\n    collection?: CollectionConfig;\n}\n\n/**\n * Options for counting entities\n */\nexport interface CountOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    /**\n     * An `or(...)`/`and(...)` group, alongside `filter`.\n     *\n     * Counted as well as fetched, or `total` describes a different set of rows\n     * from the one that was served — the same reason `filter` is here.\n     */\n    logical?: LogicalCondition;\n    searchString?: string;\n    databaseId?: string;\n}\n\n/**\n * Abstract condition builder interface.\n * Implementations translate Rebase filter conditions to database-specific queries.\n *\n * Note: This interface can be implemented as instance methods or as a class with static methods.\n * For static implementations (like DrizzleConditionBuilder), use the ConditionBuilderStatic type.\n *\n * @template T The type of condition returned by the builder (e.g., SQL for PostgreSQL, Filter<Document> for MongoDB)\n */\nexport interface ConditionBuilder<T = unknown> {\n    /**\n     * Build filter conditions from Rebase FilterValues\n     */\n    buildFilterConditions<M extends Record<string, unknown>>(\n        filter: FilterValues<Extract<keyof M, string>>,\n        collectionPath: string,\n        ...args: unknown[]\n    ): T[];\n\n    /**\n     * Build search conditions for text search.\n     *\n     * At most one condition comes back, already complete: callers OR what they\n     * get, and OR is right across the searchable *fields* but wrong across the\n     * *terms* of the search string — a person typing two words means both, and\n     * the two halves of a name are two different fields. The empty array still\n     * means \"nothing here can be searched\", which every caller reads as \"no\n     * rows\".\n     */\n    buildSearchConditions(\n        searchString: string,\n        properties: Record<string, unknown>,\n        ...args: unknown[]\n    ): T[];\n\n    /**\n     * Combine multiple conditions with AND operator\n     */\n    combineConditionsWithAnd(conditions: T[]): T | undefined;\n\n    /**\n     * Combine multiple conditions with OR operator\n     */\n    combineConditionsWithOr(conditions: T[]): T | undefined;\n}\n\n/**\n * Static condition builder type for implementations using static methods.\n * Use this type when the class provides static methods rather than instance methods.\n *\n * @example\n * // DrizzleConditionBuilder satisfies this type\n * const builder: ConditionBuilderStatic<SQL> = DrizzleConditionBuilder;\n */\nexport type ConditionBuilderStatic<T = unknown> = {\n    buildFilterConditions<M extends Record<string, unknown>>(\n        filter: FilterValues<Extract<keyof M, string>>,\n        ...args: unknown[]\n    ): T[];\n    buildSearchConditions(\n        searchString: string,\n        properties: Record<string, unknown>,\n        ...args: unknown[]\n    ): T[];\n    combineConditionsWithAnd(conditions: T[]): T | undefined;\n    combineConditionsWithOr(conditions: T[]): T | undefined;\n};\n\n// =============================================================================\n// ENTITY REPOSITORY INTERFACES\n// =============================================================================\n\n/**\n * Abstract entity repository interface.\n * Handles all CRUD operations for entities in the database.\n *\n * Implementations should handle:\n * - Entity serialization/deserialization\n * - Relation resolution\n * - ID generation and conversion\n */\nexport interface DataRepository {\n    /**\n     * Fetch a single entity by ID\n     */\n    fetchOne<M extends Record<string, unknown>>(\n        collectionPath: string,\n        id: string | number,\n        databaseId?: string\n    ): Promise<Record<string, unknown> | undefined>;\n\n    /**\n     * Fetch a collection of entities with optional filtering, ordering, and pagination\n     */\n    fetchCollection<M extends Record<string, unknown>>(\n        collectionPath: string,\n        options?: FetchCollectionOptions<M>\n    ): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Search entities by text\n     */\n    searchRows<M extends Record<string, unknown>>(\n        collectionPath: string,\n        searchString: string,\n        options?: SearchOptions<M>\n    ): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Count entities in a collection\n     */\n    count<M extends Record<string, unknown>>(\n        collectionPath: string,\n        options?: CountOptions<M>\n    ): Promise<number>;\n\n    /**\n     * Save a entity (create or update)\n     */\n    save<M extends Record<string, unknown>>(\n        collectionPath: string,\n        values: Partial<M>,\n        id?: string | number,\n        databaseId?: string\n    ): Promise<Record<string, unknown>>;\n\n    /**\n     * Delete a entity by ID\n     */\n    delete(\n        collectionPath: string,\n        id: string | number,\n        databaseId?: string\n    ): Promise<void>;\n\n    /**\n     * Check if a field value is unique in a collection\n     */\n    checkUniqueField(\n        collectionPath: string,\n        fieldName: string,\n        value: unknown,\n        excludeEntityId?: string,\n        databaseId?: string\n    ): Promise<boolean>;\n\n}\n\n// =============================================================================\n// REALTIME INTERFACES\n// =============================================================================\n\n/**\n * Configuration for subscribing to a collection\n */\nexport interface CollectionSubscriptionConfig {\n    clientId: string;\n    path: string;\n    filter?: unknown;\n    /**\n     * An `or(...)`/`and(...)` group, applied alongside `filter`.\n     *\n     * Declared here because a subscription is a query, and every field a query\n     * has this one needs too. It was missing, so the type-checked boundary\n     * dropped it: the client sent the group, nothing rejected it, and the\n     * subscription re-fetched with the group gone — pushing every row the\n     * caller's policies allowed rather than the ones they asked for. The same\n     * defect `FetchCollectionProps.logical` documents, one layer up.\n     */\n    logical?: LogicalCondition;\n    /**\n     * Where the subscription's page starts. Missing for the same reason, with\n     * a quieter symptom: a subscriber watching page two was pushed page one,\n     * and a `collection_update` frame carries no window for it to notice with.\n     */\n    offset?: number;\n    /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */\n    orderBy?: string | OrderByTuple[];\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    startAfter?: unknown;\n    databaseId?: string;\n    searchString?: string;\n    /** Ask each row which declared search field matched. */\n    searchExplain?: boolean;\n}\n\n/**\n * Configuration for subscribing to a single entity\n */\nexport interface SingleSubscriptionConfig {\n    clientId: string;\n    path: string;\n    id: string | number;\n}\n\n/**\n * Opt-in retention for one set of broadcast channels.\n *\n * Retention is configured on the server and nowhere else. A channel is created\n * by whoever names it, so letting a client ask for its own history depth would\n * let any visitor commit the backend to unbounded storage; and presence-only or\n * notification-only channels — the overwhelming majority — must not pay for a\n * feature they never use. With no rules configured nothing is written, no table\n * is created, and broadcast behaves exactly as it did before history existed.\n */\nexport interface ChannelRetentionRule {\n    /**\n     * Channel name to match. Either exact (`\"doc:42\"`) or a trailing-`*` prefix\n     * (`\"doc:*\"`). Deliberately not a full glob or RegExp: this decides what\n     * gets written to disk, and a rule whose blast radius is not obvious at a\n     * glance is the wrong shape for that.\n     */\n    match: string;\n    /** Keep at most this many of the most recent messages per channel. */\n    limit?: number;\n    /**\n     * Keep messages for at most this long. Accepts a millisecond count or a\n     * short duration string (`\"30s\"`, `\"15m\"`, `\"24h\"`, `\"7d\"`).\n     */\n    ttl?: number | string;\n}\n\n/**\n * Server-side realtime options.\n *\n * The channel bus contract and its config live in `./channel_bus` so that a\n * transport shipped as its own package depends on the contract alone.\n */\nexport interface RealtimeChannelsConfig {\n    /**\n     * Retention rules, most specific first — the first match wins. Omitted or\n     * empty means no channel retains anything.\n     */\n    channels?: ChannelRetentionRule[];\n    /**\n     * How channel broadcast and presence reach other backend instances.\n     * Defaults to `{ type: \"memory\" }` — i.e. they don't.\n     */\n    bus?: ChannelBusSetting;\n}\n\n/**\n * Abstract realtime provider interface.\n * Handles real-time subscriptions and notifications for entity changes.\n */\nexport interface RealtimeProvider {\n    /**\n     * Subscribe to collection changes.\n     *\n     * `onError` is called when a fetch behind the subscription fails, a\n     * refetch after a change included, with the error as it was thrown. It is\n     * not called for a fetch that newer rows have already overtaken, or after\n     * the subscription is gone. Without it, a subscriber whose fetch failed\n     * was told nothing and kept waiting for rows.\n     */\n    subscribeToCollection(\n        subscriptionId: string,\n        config: CollectionSubscriptionConfig,\n        callback?: (rows: Record<string, unknown>[]) => void,\n        onError?: (error: unknown) => void\n    ): void;\n\n    /**\n     * Subscribe to single entity changes. `onError` as for\n     * {@link RealtimeProvider.subscribeToCollection}.\n     */\n    subscribeToOne(\n        subscriptionId: string,\n        config: SingleSubscriptionConfig,\n        callback?: (row: Record<string, unknown> | null) => void,\n        onError?: (error: unknown) => void\n    ): void;\n\n    /**\n     * Unsubscribe from a subscription\n     */\n    unsubscribe(subscriptionId: string): void;\n\n    /**\n     * Notify all relevant subscribers of a entity update\n     */\n    notifyUpdate(\n        path: string,\n        id: string,\n        row: Record<string, unknown> | null,\n        databaseId?: string\n    ): Promise<void>;\n\n    /**\n     * Called when the HTTP server is ready and listening.\n     * Useful for providers that need the server address for callbacks.\n     */\n    onServerReady?(serverInfo: { port: number; hostname?: string }): void;\n\n    /**\n     * Gracefully shut down the realtime provider.\n     * Called during server shutdown to clean up resources.\n     */\n    destroy?(): Promise<void>;\n\n    /**\n     * Stop the internal LISTEN client (e.g., PostgreSQL LISTEN/NOTIFY).\n     * Called during graceful shutdown before closing database connections.\n     */\n    stopListening?(): Promise<void>;\n}\n\n// =============================================================================\n// COLLECTION REGISTRY INTERFACES\n// =============================================================================\n\n/**\n * Abstract collection registry interface.\n * Manages registration and lookup of entity collections.\n */\nexport interface CollectionRegistryInterface {\n    /**\n     * Register a collection\n     */\n    register(collection: CollectionConfig): void;\n\n    /**\n     * Get a collection by its path\n     */\n    getCollectionByPath(path: string): CollectionConfig | undefined;\n\n    /**\n     * Get all registered collections\n     */\n    getCollections(): CollectionConfig[];\n\n    /**\n     * Get the currently registered global callbacks, if any.\n     */\n    getGlobalCallbacks(): any | undefined;\n\n    /**\n     * Take the global callbacks declared on `initializeRebaseBackend({ callbacks })`.\n     *\n     * A driver resolves callbacks from the registry it builds for itself, so\n     * this is how the backend's global ones reach it: the coordinator hands\n     * them over after `initializeDriver` returns. Optional so a registry for a\n     * driver that runs no callbacks still type-checks, but a project that\n     * declares global callbacks over a registry without it is refused at boot\n     * — hooks that never run look exactly like hooks that passed.\n     */\n    setGlobalCallbacks?(callbacks: CollectionCallbacks): void;\n}\n\n// =============================================================================\n// DATA TRANSFORMER INTERFACES\n// =============================================================================\n\n/**\n * Abstract data transformer interface.\n * Handles serialization/deserialization between frontend and database formats.\n */\nexport interface DataTransformer {\n    /**\n     * Transform entity data for storage in the database\n     */\n    serializeToDatabase<M extends Record<string, unknown>>(\n        entity: M,\n        collection: CollectionConfig\n    ): Record<string, unknown>;\n\n    /**\n     * Transform database data back to entity format\n     */\n    deserializeFromDatabase<M extends Record<string, unknown>>(\n        data: Record<string, unknown>,\n        collection: CollectionConfig\n    ): Promise<M>;\n}\n\n// =============================================================================\n// DATABASE ADMIN — CAPABILITY-SPECIFIC INTERFACES (1.3)\n// =============================================================================\n\n/**\n * Administrative operations for SQL-based databases (PostgreSQL, MySQL, etc.).\n * Used by the SQL Editor, RLS Editor, and schema browser.\n *\n * @group Admin\n */\nexport interface SQLAdmin {\n    /**\n     * Execute raw SQL against the database.\n     */\n    executeSql(sql: string, options?: { database?: string; role?: string; params?: unknown[] }): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch the available databases on the server.\n     */\n    fetchAvailableDatabases?(): Promise<string[]>;\n\n    /**\n     * Fetch the available *native PostgreSQL* database roles (from `pg_roles`).\n     *\n     * These are connection-level roles — what the SQL editor can `SET ROLE` to,\n     * and what `SecurityRule.pgRoles` targets. They are NOT application roles;\n     * for those use {@link fetchApplicationRoles}.\n     */\n    fetchAvailableRoles?(): Promise<string[]>;\n\n    /**\n     * Fetch the *application-level* roles in use in this project.\n     *\n     * These are the strings stored on the users table's `roles` column and\n     * exposed to policies as `rebase.roles()` — what `SecurityRule.roles`\n     * matches against. Distinct from {@link fetchAvailableRoles}; the two are\n     * not interchangeable.\n     */\n    fetchApplicationRoles?(): Promise<string[]>;\n\n    /**\n     * Fetch the current database name.\n     */\n    fetchCurrentDatabase?(): Promise<string | undefined>;\n}\n\n/**\n * Administrative operations for document-based databases (MongoDB, Firestore, etc.).\n * Used by future document administration tools.\n *\n * @group Admin\n */\nexport interface DocumentAdmin {\n    /**\n     * Execute an aggregation pipeline or equivalent query.\n     */\n    executeAggregate?(pipeline: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch statistics for a collection (document count, size, etc.).\n     */\n    fetchCollectionStats?(collectionName: string): Promise<{ count: number; sizeBytes?: number }>;\n}\n\n/**\n * Administrative operations for schema management.\n * Shared across SQL and document databases.\n *\n * @group Admin\n */\nexport interface SchemaAdmin {\n    /**\n     * Fetch database tables/collections not yet mapped to a Rebase collection.\n     */\n    fetchUnmappedTables?(mappedPaths?: string[]): Promise<string[]>;\n\n    /**\n     * Fetch column/field metadata for a single table/collection.\n     * The return type is generic — SQL backends return TableMetadata,\n     * document backends may return a different shape.\n     */\n    fetchTableMetadata?(tableName: string): Promise<unknown>;\n}\n\n/**\n * Metadata for a database branch.\n * @group Admin\n */\nexport interface BranchInfo {\n    /** Branch name (without prefix). */\n    name: string;\n    /** The database this branch was created from. */\n    parentDatabase: string;\n    /** When the branch was created. */\n    createdAt: Date;\n    /** Size in bytes, if available from the server. */\n    sizeBytes?: number;\n}\n\n/**\n * Administrative operations for database branching.\n * Allows creating isolated database copies for development/preview workflows.\n *\n * @group Admin\n */\nexport interface BranchAdmin {\n    /** Create a new branch (database copy) from the current or specified source database. */\n    createBranch(name: string, options?: { source?: string }): Promise<BranchInfo>;\n\n    /** Delete a branch database. Cannot delete the main/default database. */\n    deleteBranch(name: string): Promise<void>;\n\n    /** List all branches (databases that were created via branching). */\n    listBranches(): Promise<BranchInfo[]>;\n\n    /** Get info about a specific branch. */\n    getBranchInfo(name: string): Promise<BranchInfo | undefined>;\n}\n\n/**\n * Union type for all admin capabilities.\n * A backend may implement any combination of these interfaces.\n *\n * Use type guards (`isSQLAdmin`, `isDocumentAdmin`, `isSchemaAdmin`, `isBranchAdmin`)\n * to safely narrow the type before calling methods.\n *\n * @group Admin\n */\nexport type DatabaseAdmin = Partial<SQLAdmin> & Partial<DocumentAdmin> & Partial<SchemaAdmin>\n    & Partial<BranchAdmin> & Partial<SchemaEditingAdmin>;\n\n/**\n * Type guard: can this admin plan a live schema change?\n *\n * Planning is engine-specific — it renders DDL, a Drizzle schema and the\n * declarative SQL artifacts — so the implementation lives in the driver\n * package. The server detects the capability structurally, exactly as it does\n * for SQL, rather than importing an engine it is supposed to know nothing\n * about.\n *\n * @group Admin\n */\nexport function isSchemaEditingAdmin(admin: DatabaseAdmin | undefined): admin is SchemaEditingAdmin {\n    return !!admin && typeof (admin as SchemaEditingAdmin).planSchemaChange === \"function\";\n}\n\n/**\n * Type guard: does this admin support SQL operations?\n * @group Admin\n */\nexport function isSQLAdmin(admin: DatabaseAdmin | undefined): admin is SQLAdmin {\n    return !!admin && typeof (admin as SQLAdmin).executeSql === \"function\";\n}\n\n/**\n * Type guard: does this admin support document operations?\n * @group Admin\n */\nexport function isDocumentAdmin(admin: DatabaseAdmin | undefined): admin is DocumentAdmin {\n    return !!admin && (\n        typeof (admin as DocumentAdmin).executeAggregate === \"function\" ||\n        typeof (admin as DocumentAdmin).fetchCollectionStats === \"function\"\n    );\n}\n\n/**\n * Type guard: does this admin support schema management?\n * @group Admin\n */\nexport function isSchemaAdmin(admin: DatabaseAdmin | undefined): admin is SchemaAdmin {\n    return !!admin && (\n        typeof (admin as SchemaAdmin).fetchUnmappedTables === \"function\" ||\n        typeof (admin as SchemaAdmin).fetchTableMetadata === \"function\"\n    );\n}\n\n/**\n * Type guard: does this admin support database branching?\n * @group Admin\n */\nexport function isBranchAdmin(admin: DatabaseAdmin | undefined): admin is BranchAdmin {\n    return !!admin && typeof (admin as BranchAdmin).createBranch === \"function\";\n}\n\n// =============================================================================\n// LIFECYCLE INTERFACES (1.4)\n// =============================================================================\n\n/**\n * Health check result returned by `healthCheck()`.\n * @group Lifecycle\n */\nexport interface HealthCheckResult {\n    /** Whether the backend is healthy and able to serve requests. */\n    healthy: boolean;\n    /** Round-trip latency to the database in milliseconds. */\n    latencyMs: number;\n    /** Optional details (e.g., pool stats, replication lag). */\n    details?: Record<string, unknown>;\n}\n\n/**\n * Lifecycle contract for backend components that hold resources\n * (database connections, WebSocket pools, timers, etc.).\n *\n * All methods are optional — simple backends (e.g., in-memory) can skip them.\n * @group Lifecycle\n */\nexport interface BackendLifecycle {\n    /**\n     * Initialize the backend: open connections, run migrations, seed data.\n     * Called once during startup. Idempotent.\n     */\n    initialize?(): Promise<void>;\n\n    /**\n     * Check whether the backend is healthy and reachable.\n     * Should be fast (< 1 s) and safe to call frequently.\n     */\n    healthCheck?(): Promise<HealthCheckResult>;\n\n    /**\n     * Gracefully shut down: close connections, flush buffers, cancel timers.\n     * After calling `destroy()`, no other methods should be called.\n     */\n    destroy?(): Promise<void>;\n}\n\n// =============================================================================\n// BACKEND FACTORY INTERFACES\n// =============================================================================\n\n/**\n * Configuration for creating a database backend\n */\nexport interface BackendConfig {\n    /**\n     * Type of database backend\n     */\n    type: string;\n\n    /**\n     * Database connection (implementation-specific)\n     */\n    connection: unknown;\n\n    /**\n     * Schema definition (implementation-specific, e.g., Drizzle schema for PostgreSQL)\n     */\n    schema?: unknown;\n}\n\n/**\n * A complete backend instance with all required services.\n *\n * Now includes optional lifecycle management and admin capabilities.\n */\nexport interface BackendInstance extends BackendLifecycle {\n    /**\n     * Entity repository for CRUD operations\n     */\n    entityRepository: DataRepository;\n\n    /**\n     * Realtime provider for subscriptions\n     */\n    realtimeProvider: RealtimeProvider;\n\n    /**\n     * Collection registry\n     */\n    collectionRegistry: CollectionRegistryInterface;\n\n    /**\n     * The underlying database connection\n     */\n    connection: DatabaseConnection;\n\n    /**\n     * Administrative operations (SQL, schema, documents).\n     * What's available depends on the backend type — use type guards\n     * (`isSQLAdmin`, `isSchemaAdmin`, etc.) to narrow.\n     */\n    admin?: DatabaseAdmin;\n}\n\n/**\n * Factory function type for creating backend instances\n */\nexport type BackendFactory<TConfig extends BackendConfig = BackendConfig> =\n    (config: TConfig) => BackendInstance;\n\n// =============================================================================\n// BACKEND BOOTSTRAPPER (1.2)\n// =============================================================================\n\n/**\n * A `BackendBootstrapper` encapsulates all driver-specific initialization logic.\n *\n * Instead of hard-coding Postgres setup into `initializeRebaseBackend()`,\n * each database backend provides its own bootstrapper that knows how to:\n * - Create the DataDriver from a config object\n * - Optionally initialize auth tables\n * - Optionally create a realtime service\n * - Mount driver-specific API routes\n *\n * The main `initializeRebaseBackend()` becomes a **coordinator** that iterates\n * registered bootstrappers, calls their hooks, and wires the results together.\n *\n * @group Backend\n *\n * @example\n * ```typescript\n * // Third-party MySQL bootstrapper\n * const mysqlBootstrapper: BackendBootstrapper = {\n *   type: \"mysql\",\n *   initializeDriver: async (config) => new MySQLDataDriver(config.connection),\n *   initializeRealtime: async (config) => new MySQLChangeStreamRealtime(config.connection),\n * };\n *\n * initializeRebaseBackend({\n *   ...config,\n *   bootstrappers: [postgresBootstrapper, mysqlBootstrapper]\n * });\n * ```\n */\nexport interface BackendBootstrapper {\n    /**\n     * Which driver type this bootstrapper handles.\n     * Must match the `type` field on the driver config object\n     * (e.g., `\"postgres\"`, `\"mongodb\"`, `\"mysql\"`).\n     */\n    type: string;\n\n    /**\n     * Unique identifier for this bootstrapper instance.\n     * Used to register the driver in the driver registry.\n     * Defaults to `type` if not set.\n     */\n    id?: string;\n\n    /**\n     * Whether this bootstrapper provides the default driver.\n     * When true, the coordinator uses this driver as the primary one.\n     */\n    isDefault?: boolean;\n\n    /**\n     * Run database migrations for this driver.\n     * Called by the coordinator after all drivers are initialized.\n     */\n    runMigrations?(config: unknown, driverResult: InitializedDriver): Promise<void>;\n\n    /**\n     * Create a DataDriver from the given config.\n     * This is the only **required** method.\n     */\n    initializeDriver(config: unknown): Promise<InitializedDriver>;\n\n    /**\n     * Initialize auth tables / services if this driver supports them.\n     * Return undefined if auth is not supported by this backend.\n     */\n    initializeAuth?(config: unknown, driverResult: InitializedDriver): Promise<BootstrappedAuth | undefined>;\n\n    /**\n     * Initialize history tables / services if this driver supports them.\n     * Return undefined if history is not supported by this backend.\n     */\n    initializeHistory?(config: HistoryConfig, driverResult: InitializedDriver): Promise<{ historyService: unknown } | undefined>;\n\n    /**\n     * Create a realtime provider for this driver.\n     * Return undefined if the driver does not support realtime.\n     */\n    initializeRealtime?(config: unknown, driverResult: InitializedDriver): Promise<RealtimeProvider | undefined>;\n\n    /**\n     * Mount any driver-specific HTTP routes (e.g., custom admin endpoints).\n     * Called after all drivers are initialized.\n     */\n    mountRoutes?(app: unknown, basePath: string, driverResult: InitializedDriver): void;\n\n    /**\n     * Return admin capabilities for this driver.\n     */\n    getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;\n\n    /**\n     * Ask the database whether it is there, before anything else touches it.\n     *\n     * Boot's first database call is not `initializeDriver` — it is the schema\n     * provisioning that runs ahead of it, and a driver's connection diagnosis\n     * therefore never got the chance to run. A stopped database produced\n     * `Failed query: [redacted]` and a stack through drizzle internals: no host,\n     * no port, no `ECONNREFUSED`, and no hint about starting the thing.\n     *\n     * Implementations MUST issue the cheapest round trip they have (`SELECT 1`),\n     * MUST throw an error whose message names the host, the port and the\n     * driver's own reason, and MAY log a fuller diagnosis first. They MUST NOT\n     * throw for a reachable database that merely answered something unexpected —\n     * the caller treats a throw as fatal.\n     *\n     * `driverResult` is optional for the same reason as\n     * {@link ensureCollectionSchema}: this runs before `initializeDriver`, so an\n     * adapter that was constructed with its own connection has to fall back to\n     * it.\n     */\n    verifyConnection?(driverResult?: InitializedDriver): Promise<void>;\n\n    /**\n     * Bring the database's collection tables up to date, additively.\n     *\n     * Optional because it is only meaningful for schema-ful drivers. A managed\n     * runtime boots a compiled project against a database it has never seen; auth\n     * tables are ensured on boot but collection tables were created by nothing,\n     * so every data request answered 500 on a missing relation. The CLI's `db\n     * push` cannot fill the gap — it needs Atlas, and the runtime image ships no\n     * CLI.\n     *\n     * Implementations MUST be additive-only: create missing tables, columns and\n     * enum types, and never drop, narrow or rewrite anything. This runs\n     * unattended against live customer data with nobody reading a diff, so the\n     * destructive half stays a deliberate migration.\n     *\n     * `driverResult` is optional: this runs before `initializeDriver`, and only\n     * the bundle path has a pre-init stand-in to pass. An adapter built by an\n     * application already holds its own connection and MUST use it when this is\n     * `undefined` — dereferencing it unconditionally works for managed tenants\n     * and breaks every app that builds its own adapter.\n     */\n    ensureCollectionSchema?(\n        collections: unknown[],\n        driverResult?: InitializedDriver,\n        log?: (message: string) => void\n    ): Promise<{ applied: number }>;\n\n    /**\n     * Apply the collections' row-level-security policies, additively and\n     * idempotently — the companion to {@link ensureCollectionSchema}.\n     *\n     * That method creates the tables; a table with RLS disabled and no policies\n     * is not servable, because authenticated requests run as a restricted role:\n     * a read with no `SELECT` policy returns nothing (a public collection\n     * answers 401) and a write with no `INSERT`/`UPDATE` policy is denied. The\n     * `db push` CLI applies these from the same collections, but it cannot reach\n     * a managed tenant's in-cluster database — the runtime, already connected,\n     * is the only thing that can.\n     *\n     * MUST be idempotent (re-run on every boot) and MUST NOT be destructive.\n     * Runs after auth initialization, because the generated policies call the\n     * `auth.*` helper functions and `CREATE POLICY` validates they exist.\n     */\n    ensureCollectionPolicies?(\n        collections: unknown[],\n        driverResult?: InitializedDriver,\n        log?: (message: string) => void\n    ): Promise<{ applied: number }>;\n\n    /**\n     * Create the RLS helper functions on this source's database. See\n     * `DatabaseAdapter.ensureRlsRuntime`; needed on every source that is not\n     * the default, whose helpers arrive with the auth tables.\n     */\n    ensureRlsRuntime?(driverResult?: InitializedDriver): Promise<void>;\n\n    /**\n     * Re-check, after the schema exists, that requests will actually be\n     * constrained by the database's own authorization.\n     *\n     * A driver that isolates user requests by switching to a restricted role has\n     * to decide at connect time whether the switch is needed — and on a fresh\n     * database that question is asked before there is anything to answer with.\n     * The process then creates the schema, becomes its owner, and an owner is\n     * exempt from the policies on what it owns. So the answer that was true when\n     * the driver initialized can be false by the time it serves a request.\n     *\n     * This is where a driver asks again. It runs once, after collection tables,\n     * auth tables and policies are all in place, and it MUST fail rather than\n     * serve when the answer changed and cannot be acted on: booting anyway\n     * produces exactly the unenforced server this exists to prevent.\n     *\n     * Optional, because it is only meaningful for drivers whose isolation\n     * depends on state the schema affects. A driver with nothing to re-check\n     * omits it.\n     */\n    finalizeSecurityPosture?(driverResult: InitializedDriver): Promise<void>;\n\n    /**\n     * Read the collections schema version this database was last provisioned\n     * from, or `null` when nothing has ever stamped it.\n     *\n     * The companion to {@link stampCollectionsSchemaVersion}: one process writes\n     * what it applied, every other process compares itself to it. This is what\n     * lets a split deployment — several processes over one database, only one of\n     * which provisions — notice that a unit is serving against a schema it was\n     * not built for. That failure is otherwise silent in both directions: a\n     * column that does not exist is a SQL error on one route, and a policy that\n     * was never applied is a 200 with no rows.\n     *\n     * `null` is not an error and MUST NOT be treated as one — every database\n     * provisioned before the stamp existed reads this way, and so does every\n     * fresh one until its first provisioning boot finishes.\n     */\n    readCollectionsSchemaVersion?(\n        driverResult?: InitializedDriver\n    ): Promise<string | null>;\n\n    /**\n     * Record the collections schema version this process just applied.\n     *\n     * Called only by the process that provisions, and only after both\n     * {@link ensureCollectionSchema} and {@link ensureCollectionPolicies} have\n     * run — a stamp written before the policies would claim a schema that is\n     * only half in place, and the half that is missing is the one that fails\n     * without an error.\n     */\n    stampCollectionsSchemaVersion?(\n        version: string,\n        driverResult?: InitializedDriver\n    ): Promise<void>;\n\n    /**\n     * Initialize WebSocket server for realtime operations.\n     */\n    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import(\"../controllers/data_driver\").DataDriver, config?: unknown, authAdapter?: AuthAdapter): Promise<void> | void;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeDriver()`.\n * @group Backend\n */\nexport interface InitializedDriver {\n    /** The DataDriver instance, ready for use. */\n    driver: import(\"../controllers/data_driver\").DataDriver;\n\n    /** The realtime service, if the driver created one during init. */\n    realtimeProvider?: RealtimeProvider;\n\n    /** A collection registry to register schema / tables into. */\n    collectionRegistry?: CollectionRegistryInterface;\n\n    /**\n     * Collections the driver derived from the live database schema.\n     *\n     * Set by drivers that introspect in `baas` mode; the server serves these\n     * instead of collections loaded from config files.\n     */\n    collections?: import(\"./collections\").CollectionConfig[];\n\n    /** The underlying database connection (for lifecycle management). */\n    connection?: DatabaseConnection;\n\n    /**\n     * Opaque handle that the bootstrapper can use in subsequent hooks\n     * (e.g., `initializeAuth`, `mountRoutes`) to access driver internals.\n     * Not used by the coordinator.\n     */\n    internals?: unknown;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeAuth()`.\n * @group Backend\n */\nexport interface BootstrappedAuth {\n    /** User management service. */\n    userService: unknown;\n    /** Role management service (optional, roles are now simple strings). */\n    roleService?: unknown;\n    /** Email service (optional). */\n    emailService?: unknown;\n    /** Combined Auth Repository for unified token and user management. */\n    authRepository?: unknown;\n    /**\n     * Whether the auth schema in the database is one this runtime can serve.\n     *\n     * Folded into `healthCheck()` so a schema mismatch shows up as a degraded\n     * health response. Without it, a server whose auth is entirely broken still\n     * reports healthy — the database connection it probes is fine, and the\n     * mismatch is only discovered one failed login at a time.\n     */\n    schemaHealthCheck?(): Promise<AuthSchemaHealth>;\n}\n\n/**\n * Result of {@link BootstrappedAuth.schemaHealthCheck}.\n * @group Lifecycle\n */\nexport interface AuthSchemaHealth {\n    /** False when this runtime cannot be trusted to serve auth against this database. */\n    healthy: boolean;\n    /** Human-readable descriptions of each mismatch found. Empty when healthy. */\n    problems: string[];\n    /** Auth schema version recorded in the database, when it records one. */\n    databaseVersion?: number | null;\n    /** Auth schema version this runtime expects. */\n    runtimeVersion?: number;\n}\n","import { logger } from \"../utils/logger.js\";\n\n/**\n * Helpers for the \"create my internal table if it isn't there yet\" bootstrap\n * that several stores run at boot.\n *\n * These all look trivially safe — every statement is `IF NOT EXISTS` — and they\n * are not, for two reasons that only show up with more than one app instance:\n *\n *  1. `CREATE … IF NOT EXISTS` reads the catalog and then writes to it, and\n *     those two steps are not one atomic operation. Instances starting together\n *     — a rolling deploy, a replica count going from 1 to N, a crash loop\n *     restarting the fleet — can both see \"absent\" and both try to create. The\n *     loser gets a duplicate key on a *catalog* index instead of the silent\n *     no-op the syntax appears to promise. Measured against Postgres 18: with\n *     five instances booting at once, 8 of 10 `ensureTable` calls hit it.\n *\n *  2. A bootstrap written as one long `try` block therefore abandons everything\n *     after the losing statement — including, in every store that has one, the\n *     `REVOKE` that takes the table back off the end-user role. That revoke is\n *     a security control and must not be collateral damage from a race.\n *\n * So: retry the race, contain each statement separately, and decide what to do\n * next from what actually exists rather than from who won.\n */\n\n/** A driver's `executeSql`, narrowed to what a bootstrap needs. */\nexport type SqlExec = (sqlText: string, options?: { params?: unknown[] }) => Promise<Record<string, unknown>[]>;\n\n\n/**\n * SQLSTATEs a *simultaneous boot* can raise from statements that are otherwise\n * idempotent. Retrying is always the right answer for these: the second attempt\n * finds the object present and does nothing.\n */\nexport const CONCURRENT_DDL_SQLSTATES = new Set([\n    \"23505\", // unique_violation on pg_type / pg_class / pg_namespace\n    \"42P06\", // duplicate_schema\n    \"42P07\", // duplicate_table\n    \"42710\", // duplicate_object — an index or a constraint\n    \"40P01\" // deadlock_detected — two boots taking catalog locks in step\n]);\n\n/** Attempts per idempotent DDL statement, including the first. */\nexport const DDL_ATTEMPTS = 4;\nconst DDL_RETRY_BASE_MS = 40;\n\n/**\n * Walk an error's `cause` chain, stopping at the first link `visit` accepts.\n * Drizzle wraps the driver error, so nothing useful is ever on the top level.\n */\nexport function hasInCauseChain(err: unknown, visit: (e: Record<string, unknown>) => boolean): boolean {\n    let current: unknown = err;\n    for (let depth = 0; depth < 10 && current; depth++) {\n        if (typeof current !== \"object\") break;\n        const e = current as Record<string, unknown>;\n        if (visit(e)) return true;\n        current = e.cause;\n    }\n    return false;\n}\n\n/**\n * Is this the loser of a race to create something that already exists?\n *\n * Deliberately narrow. A permission failure, an unreachable database or a typo\n * in the DDL must surface on the first attempt rather than being retried four\n * times and then reported as a race that never was.\n */\nexport function isConcurrentDdlRace(err: unknown): boolean {\n    return hasInCauseChain(err, (e) =>\n        (typeof e.code === \"string\" && CONCURRENT_DDL_SQLSTATES.has(e.code)) ||\n        // SQLite and MySQL say it in words rather than in a shared SQLSTATE.\n        (typeof e.message === \"string\" && /already exists/i.test(e.message))\n    );\n}\n\n/**\n * SQLSTATEs that mean, unambiguously, *the object is already there*.\n *\n * A subset of {@link CONCURRENT_DDL_SQLSTATES} and a stricter question. The\n * broad set answers \"should this be retried\"; this one answers \"is it safe to\n * carry on as though the statement had succeeded\", which is a claim about the\n * end state rather than about the attempt. Deadlock is not in it — a deadlocked\n * statement did nothing and must be retried, not skipped.\n */\nconst DUPLICATE_OBJECT_SQLSTATES = new Set([\n    \"42P06\", // duplicate_schema\n    \"42P07\", // duplicate_table\n    \"42710\" // duplicate_object — a type, an index, a constraint\n]);\n\n/**\n * Did this statement fail *because a peer already created the same object*?\n *\n * The narrow companion to {@link isConcurrentDdlRace}, for the one caller that\n * needs to tell \"someone beat me to it\" from \"this genuinely failed\": a loop\n * applying a schema plan, where treating every `23505` as a harmless race would\n * silently swallow the one that matters — a unique constraint that cannot be\n * added because the customer's existing rows violate it.\n *\n * `23505` is therefore only accepted when it names a `pg_catalog` index. That is\n * what a lost `CREATE TYPE`/`CREATE TABLE` race raises (`pg_type_typname_nsp_index`\n * is the one seen in practice); a unique violation on user data names the user's\n * own constraint and is left to the caller.\n *\n * With one exception, in {@link NOT_A_RACE_PG_INDEXES}.\n */\nexport function isDuplicateObjectRace(err: unknown): boolean {\n    return hasInCauseChain(err, (e) => {\n        if (typeof e.code !== \"string\") return false;\n        if (DUPLICATE_OBJECT_SQLSTATES.has(e.code)) return true;\n        if (e.code !== \"23505\") return false;\n        // node-postgres puts the violated index in `constraint`; some paths only\n        // carry it in the detail text, so check both rather than miss the race.\n        const constraint = typeof e.constraint === \"string\" ? e.constraint : \"\";\n        const detail = typeof e.detail === \"string\" ? e.detail : \"\";\n        for (const index of NOT_A_RACE_PG_INDEXES) {\n            if (constraint === index || detail.includes(index)) return false;\n        }\n        return constraint.startsWith(\"pg_\") || /\\bpg_[a-z_]+_index\\b/.test(detail);\n    });\n}\n\n/**\n * `pg_catalog` indexes whose `23505` is never a race.\n *\n * `pg_enum_typid_label_index` is unique on (type, label), and one statement\n * violates it on its own: `CREATE TYPE t AS ENUM ('draft', 'draft')` — which is\n * what a collection with two enum entries carrying the same `id` generates.\n * Under the `pg_` prefix rule that read as \"a peer created it first\", so the\n * type was never created, boot carried on, and the column fell back to `TEXT`\n * with no enum behind it. Verified against PGlite: the duplicate `CREATE TYPE`\n * raises exactly this.\n *\n * The concurrent-boot case this rule exists for does not come through here at\n * all. Two pods adding the same label race on `ALTER TYPE … ADD VALUE`, which\n * raises `42710` (already in {@link DUPLICATE_OBJECT_SQLSTATES}) — and the\n * generator writes `ADD VALUE IF NOT EXISTS`, so it usually raises nothing.\n *\n * The duplicate `id` is rejected earlier now, by `validate-config`, which names\n * the property. This is the second line: a config that reaches the database with\n * one fails loudly instead of degrading.\n */\nconst NOT_A_RACE_PG_INDEXES = [\"pg_enum_typid_label_index\"];\n\nexport interface DdlBootstrapper {\n    /**\n     * Run one idempotent statement — `CREATE … IF NOT EXISTS`, `ALTER TABLE …\n     * ADD COLUMN IF NOT EXISTS` — retrying the catalog race a simultaneous boot\n     * produces. Never throws: a statement that cannot be made to work is logged\n     * and the caller carries on to the next one.\n     */\n    ensureObject(label: string, sqlText: string): Promise<void>;\n\n    /** Contain one step's failure so that the steps after it still run. */\n    step(label: string, run: () => Promise<unknown>): Promise<void>;\n\n    /**\n     * Is this table there and readable? Asked with a query any SQL dialect\n     * answers, rather than `to_regclass`, so a future non-Postgres SQL driver\n     * gets a real answer instead of a syntax error read as \"missing\".\n     */\n    isReadable(table: string): Promise<boolean>;\n}\n\n/**\n * @param exec   the driver's SQL escape hatch\n * @param scope  log prefix identifying the caller, e.g. `\"cron-store\"`\n */\nexport function createDdlBootstrapper(exec: SqlExec, scope: string): DdlBootstrapper {\n    /** Jittered, so peers that collided once do not collide again in lockstep. */\n    const backoff = (attempt: number) =>\n        new Promise(resolve => setTimeout(resolve, DDL_RETRY_BASE_MS * attempt * (1 + Math.random())));\n\n    const step: DdlBootstrapper[\"step\"] = async (label, run) => {\n        try {\n            await run();\n        } catch (err) {\n            logger.error(`[${scope}] ${label} failed`, { error: err });\n        }\n    };\n\n    return {\n        step,\n\n        ensureObject(label, sqlText) {\n            return step(label, async () => {\n                for (let attempt = 1; ; attempt++) {\n                    try {\n                        await exec(sqlText);\n                        return;\n                    } catch (err) {\n                        if (!isConcurrentDdlRace(err) || attempt >= DDL_ATTEMPTS) throw err;\n                        logger.debug(\n                            `[${scope}] Lost a create race for ${label} with another instance ` +\n                            `(attempt ${attempt}/${DDL_ATTEMPTS}) — retrying`\n                        );\n                        await backoff(attempt);\n                    }\n                }\n            });\n        },\n\n        async isReadable(table) {\n            try {\n                await exec(`SELECT 1 FROM ${table} WHERE false`);\n                return true;\n            } catch {\n                return false;\n            }\n        }\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAkmBA,SAAgB,qBAAqB,OAA+D;CAChG,OAAO,CAAC,CAAC,SAAS,OAAQ,MAA6B,qBAAqB;AAChF;;;;;AAMA,SAAgB,WAAW,OAAqD;CAC5E,OAAO,CAAC,CAAC,SAAS,OAAQ,MAAmB,eAAe;AAChE;;;;;;;;ACzkBA,IAAa,2CAA2B,IAAI,IAAI;CAC5C;CACA;CACA;CACA;CACA;AACJ,CAAC;AAID,IAAM,oBAAoB;;;;;AAM1B,SAAgB,gBAAgB,KAAc,OAAyD;CACnG,IAAI,UAAmB;CACvB,KAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,SAAS,SAAS;EAChD,IAAI,OAAO,YAAY,UAAU;EACjC,MAAM,IAAI;EACV,IAAI,MAAM,CAAC,GAAG,OAAO;EACrB,UAAU,EAAE;CAChB;CACA,OAAO;AACX;;;;;;;;AASA,SAAgB,oBAAoB,KAAuB;CACvD,OAAO,gBAAgB,MAAM,MACxB,OAAO,EAAE,SAAS,YAAY,yBAAyB,IAAI,EAAE,IAAI,KAEjE,OAAO,EAAE,YAAY,YAAY,kBAAkB,KAAK,EAAE,OAAO,CACtE;AACJ;;;;;;;;;;AAWA,IAAM,6CAA6B,IAAI,IAAI;CACvC;CACA;CACA;AACJ,CAAC;;;;;;;;;;;;;;;;;AAkBD,SAAgB,sBAAsB,KAAuB;CACzD,OAAO,gBAAgB,MAAM,MAAM;EAC/B,IAAI,OAAO,EAAE,SAAS,UAAU,OAAO;EACvC,IAAI,2BAA2B,IAAI,EAAE,IAAI,GAAG,OAAO;EACnD,IAAI,EAAE,SAAS,SAAS,OAAO;EAG/B,MAAM,aAAa,OAAO,EAAE,eAAe,WAAW,EAAE,aAAa;EACrE,MAAM,SAAS,OAAO,EAAE,WAAW,WAAW,EAAE,SAAS;EACzD,KAAK,MAAM,SAAS,uBAChB,IAAI,eAAe,SAAS,OAAO,SAAS,KAAK,GAAG,OAAO;EAE/D,OAAO,WAAW,WAAW,KAAK,KAAK,uBAAuB,KAAK,MAAM;CAC7E,CAAC;AACL;;;;;;;;;;;;;;;;;;;;;AAsBA,IAAM,wBAAwB,CAAC,2BAA2B;;;;;AA0B1D,SAAgB,sBAAsB,MAAe,OAAgC;;CAEjF,MAAM,WAAW,YACb,IAAI,SAAQ,YAAW,WAAW,SAAS,oBAAoB,WAAW,IAAI,KAAK,OAAO,EAAE,CAAC;CAEjG,MAAM,OAAgC,OAAO,OAAO,QAAQ;EACxD,IAAI;GACA,MAAM,IAAI;EACd,SAAS,KAAK;GACV,OAAO,MAAM,IAAI,MAAM,IAAI,MAAM,UAAU,EAAE,OAAO,IAAI,CAAC;EAC7D;CACJ;CAEA,OAAO;EACH;EAEA,aAAa,OAAO,SAAS;GACzB,OAAO,KAAK,OAAO,YAAY;IAC3B,KAAK,IAAI,UAAU,IAAK,WACpB,IAAI;KACA,MAAM,KAAK,OAAO;KAClB;IACJ,SAAS,KAAK;KACV,IAAI,CAAC,oBAAoB,GAAG,KAAK,WAAA,GAAyB,MAAM;KAChE,OAAO,MACH,IAAI,MAAM,2BAA2B,MAAM,kCAC/B,QAAQ,eACxB;KACA,MAAM,QAAQ,OAAO;IACzB;GAER,CAAC;EACL;EAEA,MAAM,WAAW,OAAO;GACpB,IAAI;IACA,MAAM,KAAK,iBAAiB,MAAM,aAAa;IAC/C,OAAO;GACX,QAAQ;IACJ,OAAO;GACX;EACJ;CACJ;AACJ"}

package/dist/errors-DWsX4yTd.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors-DWsX4yTd.js","names":[],"sources":["../src/api/errors.ts"],"sourcesContent":["import type { Context, ErrorHandler } from \"hono\";\nimport type { ContentfulStatusCode } from \"hono/utils/http-status\";\nimport type { HonoEnv } from \"./types\";\nimport { logger } from \"../utils/logger\";\nimport { hostEnv } from \"../utils/host\";\n\n/**\n * A stale caller's schema stamp, as the cause of the error it explains.\n *\n * `createSchemaDriftDetector` puts the two stamps on the context when a request\n * carries an `x-rebase-schema` older than this backend's. It lives next door;\n * this half is here because `errors.ts` is in the graph of\n * `@rebasepro/server/functions` and may not reach `@rebasepro/types` at runtime.\n */\nfunction schemaDriftCause(drift: { client: string; server: string } | undefined): {\n    code: string;\n    message: string;\n    clientSchema: string;\n    serverSchema: string;\n} | undefined {\n    if (!drift) return undefined;\n    return {\n        code: \"SCHEMA_DRIFT\",\n        message:\n            `This client was generated against schema ${drift.client}; this backend serves `\n            + `${drift.server}. If the field named above was renamed or removed, regenerate the `\n            + \"SDK (`rebase generate-sdk`) and rebuild.\",\n        clientSchema: drift.client,\n        serverSchema: drift.server\n    };\n}\n\n/** Tracks whether we've already shown the doctor hint (once per process). */\nlet _schemaDriftHinted = false;\n\n/**\n * The schema-drift remedy, in the words that work on *this* database.\n *\n * The three copies of this message hard-coded `Run \\`pnpm db:push\\``, and on a\n * stock scaffold — where the managed PGlite database is the default — that\n * command answers `✗ rebase db push does not work on the managed development\n * database.` and exits 1. So the one instruction the server gave when a\n * developer's schema had drifted was a command their project refuses.\n *\n * Atlas plans a push by diffing against a second, empty database, and PGlite\n * serves exactly one — which is why it cannot run there, and why the remedy\n * has to know which database is under this run. There, boot applies additive\n * changes, so restarting `rebase dev` *is* the fix.\n *\n * `REBASE_DEV_DATABASE_KIND` is set by the CLI from the database it resolved,\n * the same variable `rebase schema generate`'s closing line already branches\n * on. Absent — a deployed backend, a container, anything not started by\n * `rebase dev` — the answer is the general one.\n */\nexport function schemaDriftRemedy(): { short: string; lines: string[] } {\n    if (hostEnv().REBASE_DEV_DATABASE_KIND === \"managed\") {\n        return {\n            short: \"Restart `rebase dev` — boot applies additive schema changes to the managed database.\",\n            lines: [\n                \"  Quick fixes (managed development database):\",\n                \"    restart `rebase dev`   boot applies additive changes\",\n                \"    rebase doctor          full 3-way drift report\",\n                \"\",\n                \"  `rebase db push` does not run here: Atlas plans against a\",\n                \"  second, empty database and PGlite serves one. For a change\",\n                \"  boot leaves alone, use your own Postgres (DATABASE_URL)\",\n                \"  or `rebase dev --docker`.\"\n            ]\n        };\n    }\n\n    return {\n        short: \"Run `rebase db push` to sync your schema, or `rebase db migrate` to apply pending migrations.\",\n        lines: [\n            \"  Quick fixes (local dev, against DATABASE_URL):\",\n            \"    rebase db push        sync schema to database (dev)\",\n            \"    rebase db migrate     apply pending migrations (prod)\",\n            \"    rebase doctor         full 3-way drift report\",\n            \"\",\n            \"  Managed cloud: the runtime applies schema + RLS at boot\",\n            \"  (REBASE_MIGRATE_ON_BOOT); redeploy rather than db push,\",\n            \"  which cannot reach the tenant database.\"\n        ]\n    };\n}\n\n/** Shape of Postgres / network errors with diagnostic codes */\ninterface PgLikeError {\n    code?: string;\n    address?: string;\n    port?: number;\n    message?: string;\n    table?: string;\n    column?: string;\n    schema?: string;\n    detail?: string;\n    hint?: string;\n    constraint?: string;\n}\n\n/** 5-character SQLSTATE, e.g. `42501`, `23505`. */\nconst SQLSTATE_RE = /^[0-9A-Z]{5}$/;\n\n/**\n * What SQLSTATE 25006 means here, in the only terms that help the author fix it.\n *\n * Every request-scoped read runs `withTransaction(..., { accessMode: \"read\n * only\" })`, so a write attempted anywhere under it — including from a\n * `context.data` call inside an `afterRead` callback — is refused by Postgres\n * rather than by us. The callback name is in the message because that is the\n * file the reader has to open, and nothing else on a read path can raise this.\n */\nconst READ_ONLY_TRANSACTION_MESSAGE =\n    \"An `afterRead` callback tried to write. Request-scoped reads run in a READ ONLY \" +\n    \"transaction, so neither the callback nor anything it calls (context.data included) \" +\n    \"may write. Move the write outside the read: enqueue a background job, or use \" +\n    \"`rebase.dataAsAdmin` from a job or a custom function.\";\n\n/**\n * Walk the cause chain for the underlying database error, identified by a\n * 5-char SQLSTATE `code`. Drizzle wraps the pg error in `.cause`, and route\n * code sometimes wraps drizzle again, so the real error may sit several\n * levels down.\n */\nfunction extractDbError(error: unknown, depth = 0): PgLikeError | null {\n    if (!error || typeof error !== \"object\" || depth > 8) return null;\n    const e = error as PgLikeError & { cause?: unknown };\n    if (typeof e.code === \"string\" && SQLSTATE_RE.test(e.code)) return e;\n    if (e.cause && typeof e.cause === \"object\") return extractDbError(e.cause, depth + 1);\n    return null;\n}\n\n/**\n * Extract the missing table or column name from a PG error.\n * PG 42P01 messages look like: 'relation \"my_table\" does not exist'\n * PG 42703 messages look like: 'column \"my_col\" does not exist' or 'column my_table.my_col does not exist'\n */\nfunction extractMissingIdentifier(pgMessage?: string): string | null {\n    if (!pgMessage) return null;\n    // Match quoted identifier: relation \"xxx\" / column \"xxx\"\n    const quoted = pgMessage.match(/(?:relation|column|table)\\s+\"([^\"]+)\"/i);\n    if (quoted) return quoted[1];\n    // Match unquoted: column table.col does not exist\n    const unquoted = pgMessage.match(/(?:relation|column|table)\\s+([\\w.]+)\\s+does not exist/i);\n    if (unquoted) return unquoted[1];\n    return null;\n}\n\n/**\n * The sentence a `INVALID_FILTER_VALUE` answer carries.\n *\n * Built from Postgres's own wording rather than passed through, because the\n * driver hands the whole failed statement over as `error.message` and this one\n * goes to the caller in production too. What is quoted back is the type name\n * and the literal the caller themselves sent — never a table, a column list or\n * a statement.\n *\n * The three shapes are the ones a filter actually produces: an unparseable\n * literal (22P02, `?id=eq.abc`), a value outside an enum's labels (22P02 with\n * different wording), and a number past the column type's range (22003). A\n * fourth SQLSTATE in class 22 lands on the general sentence, which still says\n * the useful thing: it is the value that is wrong, not the server.\n */\nfunction describeDataException(dbError?: PgLikeError): string {\n    const message = dbError?.message ?? \"\";\n    const column = dbError?.column ? ` for column \"${dbError.column}\"` : \"\";\n\n    const syntax = message.match(/invalid input syntax for type ([\\w ]+): \"(.*)\"/);\n    if (syntax) return `\"${syntax[2]}\" is not a valid ${syntax[1]}${column}.`;\n\n    const enumValue = message.match(/invalid input value for enum ([\\w.\"]+): \"(.*)\"/);\n    if (enumValue) return `\"${enumValue[2]}\" is not one of the values of ${enumValue[1]}${column}.`;\n\n    const range = message.match(/value \"(.*)\" is out of range for type ([\\w ]+)/);\n    if (range) return `\"${range[1]}\" is out of range for ${range[2]}${column}.`;\n\n    return `A value in this request could not be read as the type of the column it was compared against${column}.`;\n}\n\n/**\n * Standardized API error class.\n * Throw this from any route handler — the errorHandler middleware\n * will format it into `{ error: { message, code, details? } }`.\n */\nexport class ApiError extends Error {\n    public readonly statusCode: number;\n    public readonly code: string;\n    public readonly details?: unknown;\n    /**\n     * Whether this outcome is a routine part of normal operation rather than\n     * something an operator should look at. Expected errors log at debug; every\n     * other operational error logs at warn.\n     *\n     * The motivating case is `POST /auth/refresh` with no session: clients\n     * refresh on page load before they know whether one exists, so every\n     * anonymous page view is a 401 — correct, and not worth a warning line.\n     *\n     * The other class is a caller-caused 4xx that never reached the database: a\n     * mistyped filter operator, sort direction or limit, a request for a\n     * collection that does not exist. Nothing on this server is wrong, and the\n     * response body has already told the caller what to fix — while one client\n     * holding a stale name would otherwise write a warning per request, forever,\n     * until the level means nothing. See `api/rest/query-parser.ts`.\n     *\n     * What stays at warn is anything that says something about the *server*:\n     * a schema that has drifted from the code, a permission the database\n     * refused, a dependency that failed. Those are 4xx too, and they are still\n     * incidents.\n     */\n    public readonly expected: boolean;\n\n    constructor(statusCode: number, code: string, message: string, details?: unknown, expected = false) {\n        super(message);\n        this.name = \"ApiError\";\n        this.statusCode = statusCode;\n        this.code = code;\n        this.details = details;\n        this.expected = expected;\n    }\n\n    // ── Factory methods ──────────────────────────────────────────────\n\n    static badRequest(message: string, code = \"BAD_REQUEST\", details?: unknown): ApiError {\n        return new ApiError(400, code, message, details);\n    }\n\n    static unauthorized(message: string, code = \"UNAUTHORIZED\"): ApiError {\n        return new ApiError(401, code, message);\n    }\n\n    /**\n     * A 401 that is a normal outcome, not an incident — logged at debug.\n     * See {@link ApiError.expected}.\n     */\n    static unauthenticated(message: string, code = \"UNAUTHORIZED\"): ApiError {\n        return new ApiError(401, code, message, undefined, true);\n    }\n\n    static forbidden(message: string, code = \"FORBIDDEN\"): ApiError {\n        return new ApiError(403, code, message);\n    }\n\n    static notFound(message: string, code = \"NOT_FOUND\"): ApiError {\n        return new ApiError(404, code, message);\n    }\n\n    /**\n     * `details` because a 409 is usually a `23505`, and the one thing the\n     * caller needs is *which field* collided. The column name goes in; the\n     * value never does — see `pgFieldViolations`.\n     */\n    static conflict(message: string, code = \"CONFLICT\", details?: unknown): ApiError {\n        return new ApiError(409, code, message, details);\n    }\n\n    static internal(message: string, code = \"INTERNAL_ERROR\"): ApiError {\n        return new ApiError(500, code, message);\n    }\n\n    static serviceUnavailable(message: string, code = \"SERVICE_UNAVAILABLE\"): ApiError {\n        return new ApiError(503, code, message);\n    }\n}\n\n/**\n * Canonical error response shape:\n * `{ error: { message: string, code: string, details?: unknown } }`\n */\nexport interface ErrorResponse {\n    error: {\n        message: string;\n        code: string;\n        details?: unknown;\n        /** Request correlation ID for tracing (echoes X-Request-ID). */\n        requestId?: string;\n        /**\n         * Why this request was going to fail whatever it asked for.\n         *\n         * Only `SCHEMA_DRIFT` today: the caller's `x-rebase-schema` stamp is\n         * older than this backend's, so a 400 naming an unknown field is very\n         * likely a rename the client has not regenerated for. The error itself\n         * is unchanged — this explains it, it does not cause it.\n         */\n        cause?: {\n            code: string;\n            message: string;\n            clientSchema: string;\n            serverSchema: string;\n        };\n    };\n}\n\n/**\n * General shape of errors that flow through the API error handler.\n * Extends Error with optional HTTP status, error code, and details.\n */\nexport interface RebaseApiError extends Error {\n    statusCode?: number;\n    code?: string;\n    details?: unknown;\n}\n\n/**\n * The answer an error chose for itself, read the same way at every door.\n *\n * @see declaredErrorAnswer\n */\nexport interface DeclaredErrorAnswer {\n    /** The HTTP status the error carries. A socket frame has no slot for it. */\n    status: number;\n    code: string;\n    message: string;\n    details?: unknown;\n    /** See {@link ApiError.expected}: log it at debug, not warn. */\n    expected: boolean;\n}\n\n/**\n * The status, code and message an error carries as its own answer — or\n * `undefined` for an error that carries none, which is a server fault and gets\n * masked.\n *\n * Two classes carry one. The server's `ApiError`, and `RebaseApiError` (or its\n * `RebaseClientError` subclass) from `@rebasepro/types` once it has a status.\n * The second is the browser-safe class: a `config/collections/*.ts` file is\n * bundled into the admin SPA and cannot import this package, so it is what a\n * collection callback throws, and what a callback refusal becomes —\n * `callbackRefusal` returns one, and `toCallbackError` wraps anything thrown\n * that does not already carry a status.\n *\n * One function because several doors turn an error into an answer: the REST\n * error handler, the two WebSocket servers, and the Postgres realtime\n * subscriptions. Each used to list the classes it recognised by hand. The\n * sockets listed only `ApiError`, so a `beforeDelete` veto that REST\n * answered as 400 `CALLBACK_REJECTED` with the author's message reached the\n * admin panel — which writes through the socket — as `INTERNAL_ERROR`, and in\n * production as \"An unexpected error occurred\".\n *\n * Matched by name as well as `instanceof`: a monorepo can resolve two copies of\n * a package, and `instanceof` is false across them. Name matching is also why\n * this file needs no runtime import of `@rebasepro/types`, which it may not\n * have — it is in the graph of `@rebasepro/server/functions`.\n */\nexport function declaredErrorAnswer(error: unknown): DeclaredErrorAnswer | undefined {\n    if (error === null || typeof error !== \"object\") return undefined;\n    const e = error as { name?: unknown; message?: unknown; code?: unknown; details?: unknown; statusCode?: unknown; status?: unknown };\n\n    let status: number | undefined;\n    if (error instanceof ApiError || e.name === \"ApiError\") {\n        status = typeof e.statusCode === \"number\" ? e.statusCode : undefined;\n    } else if (typeof e.name === \"string\" && /^Rebase(Api|Client)Error$/.test(e.name)) {\n        // It spells its status `status`; `statusCode` wins when both are set.\n        status = typeof e.statusCode === \"number\" ? e.statusCode\n            : typeof e.status === \"number\" ? e.status\n                : undefined;\n        // Without a status it has not chosen an answer — `RebaseClientError`\n        // is also raised for plain logic errors — so it is not one here.\n        if (status === undefined) return undefined;\n    } else {\n        return undefined;\n    }\n\n    return {\n        status: status || 500,\n        code: typeof e.code === \"string\" && e.code ? e.code : \"INTERNAL_ERROR\",\n        message: typeof e.message === \"string\" ? e.message : String(e.message ?? \"\"),\n        ...(e.details !== undefined && { details: e.details }),\n        expected: error instanceof ApiError && error.expected\n    };\n}\n\n// `isRebaseApiError` was here. It read `return error instanceof Error`, so it\n// answered yes to every error while being named and used as though it\n// discriminated — the create and update handlers guarded a \"classify this as\n// BAD_REQUEST\" branch on it, and an unreachable database was therefore reported\n// to callers as a bad request. Deleted rather than repaired: the shape it\n// claimed to test is not decidable from an `Error`, and the layer that does\n// know — the driver, which holds the SQLSTATE — raises a real `ApiError`.\n\n/**\n * Leave the code and the message where the request log will find them.\n *\n * A failed request used to produce two lines, each holding half of it: this\n * handler had the code and the diagnosis, `requestLogger` had the user, the\n * collection, the status and the latency. Correlating them meant matching on\n * the request id — which only one of them printed reliably — and the pair cost\n * twice the volume for less than one line's worth of meaning.\n */\nfunction handOffToRequestLog(c: Context<HonoEnv>, code: string, message: string): void {\n    if (typeof c.set !== \"function\") return;\n    c.set(\"errorSummary\", { code, message });\n}\n\n/**\n * Is a request line coming for this request?\n *\n * `requestLogger` claims it before the handler runs, so by the time an error\n * reaches here the answer is already known. When nothing claimed it — a router\n * a project mounted onto its own Hono app, a test driving `app.fetch`\n * directly — this handler stays the only thing that would report the failure,\n * so it still writes its own line. Silence is the one outcome neither half may\n * produce.\n */\nfunction requestWillBeLogged(c: Context<HonoEnv>): boolean {\n    return typeof c.get === \"function\" && c.get(\"requestLogged\") === true;\n}\n\n/**\n * Hono error-handling middleware (`app.onError`).\n * Converts any error into the canonical `{ error: { message, code } }` shape.\n */\nexport const errorHandler: ErrorHandler<HonoEnv> = (err, c) => {\n    // Typecast custom error properties\n    const error: RebaseApiError = err;\n    const reqId = typeof c.get === \"function\" ? c.get(\"requestId\") : undefined;\n\n    /* A stale SDK, named on the errors it explains.\n\n       400 and 404 only: those are what a renamed or removed field produces —\n       an unknown filter field is a 400, a collection gone from under its slug\n       is a 404 — and they are the two a caller can act on by regenerating.\n       Attaching it to a 500 would be noise, since a server fault has nothing to\n       do with how old the caller's schema is. */\n    const driftFor = (status: number) =>\n        (status === 400 || status === 404) && typeof c.get === \"function\"\n            ? schemaDriftCause(c.get(\"schemaDrift\"))\n            : undefined;\n\n    // An error that chose its own answer — `ApiError`, or the browser-safe\n    // `RebaseApiError` a collection callback throws. The same predicate the\n    // WebSocket servers use; see `declaredErrorAnswer`.\n    const answer = declaredErrorAnswer(error);\n    if (answer) {\n        // Operational errors — log at warn, unless the error declares itself a\n        // routine outcome (see ApiError.expected), which would otherwise put a\n        // warning in the log for every anonymous page view.\n        handOffToRequestLog(c, answer.code, answer.message);\n        if (!requestWillBeLogged(c)) {\n            const line = `[API] ${c.req.method} ${c.req.path} → ${answer.status} ${answer.code}: ${answer.message}` +\n                (reqId ? ` [${reqId}]` : \"\");\n            if (answer.expected) {\n                logger.debug(line);\n            } else {\n                logger.warn(`⚠️ ${line}`);\n            }\n        }\n        const apiErrorDrift = driftFor(answer.status);\n        return c.json({\n            error: {\n                message: answer.message,\n                code: answer.code,\n                ...(answer.details !== undefined && { details: answer.details }),\n                ...(reqId && { requestId: reqId }),\n                ...(apiErrorDrift && { cause: apiErrorDrift })\n            }\n        } satisfies ErrorResponse, answer.status as ContentfulStatusCode);\n    }\n\n    let statusCode = error.statusCode || codeToStatus(error.code) || 500;\n    let code = error.code || \"INTERNAL_ERROR\";\n\n    // Handle DB connection and specific system errors for better logging\n    let logMessage = error.message;\n\n    // Resolve the actual cause — Node's net module wraps dual-stack failures\n    // in an AggregateError whose inner errors carry the real address/port.\n    let resolvedCause: PgLikeError | undefined;\n    if (error.cause && typeof error.cause === \"object\" && error.cause !== null && \"code\" in error.cause) {\n        const cause = error.cause as PgLikeError & { errors?: PgLikeError[] };\n        if (cause.code === \"ECONNREFUSED\" && !cause.address && Array.isArray(cause.errors)) {\n            // AggregateError — pick the first inner error that has address info\n            resolvedCause = cause.errors.find(e => e.address) || cause;\n        } else {\n            resolvedCause = cause;\n        }\n    }\n\n    // The real database error may sit several levels down the cause chain.\n    // Losing it turns a precise failure (e.g. an RLS denial) into an opaque\n    // \"Failed query: …\" 500 that is undiagnosable without direct DB access.\n    const dbError = extractDbError(error);\n\n    if (resolvedCause && (resolvedCause.code === \"ENETUNREACH\" || resolvedCause.code === \"ECONNREFUSED\")) {\n        const cause = resolvedCause;\n        if (cause.code === \"ENETUNREACH\") {\n            logMessage = `Network unreachable. Cannot connect to database at ${cause.address}:${cause.port}.`;\n        } else {\n            logMessage = `Connection refused to database at ${cause.address}:${cause.port}. Is PostgreSQL running?`;\n        }\n    } else if (\"code\" in error && error.code === \"ENETUNREACH\") {\n         const netErr = error as PgLikeError;\n         logMessage = `Network unreachable. Cannot connect to service at ${netErr.address}:${netErr.port}.`;\n    } else if (dbError && (dbError.code === \"42703\" || dbError.code === \"42P01\")) {\n        code = \"SCHEMA_DRIFT\";\n        const issue = dbError.code === \"42703\" ? \"column\" : \"table\";\n        const identifier = dbError.table || dbError.column || extractMissingIdentifier(dbError.message) || \"unknown\";\n        logMessage = `Schema drift: ${issue} \"${identifier}\" does not exist in the database. ${schemaDriftRemedy().short}`;\n    } else if (dbError) {\n        const parts = [`[PG ${dbError.code}] ${dbError.message}`];\n        if (dbError.detail) parts.push(`Detail: ${dbError.detail}`);\n        if (dbError.hint) parts.push(`Hint: ${dbError.hint}`);\n        if (dbError.table) parts.push(`Table: ${dbError.table}`);\n        if (dbError.column) parts.push(`Column: ${dbError.column}`);\n        if (dbError.constraint) parts.push(`Constraint: ${dbError.constraint}`);\n        if (dbError.code === \"42501\") {\n            code = \"DB_PERMISSION_DENIED\";\n            parts.push(\n                \"The database rejected the statement for lack of privilege — usually a row-level \" +\n                `security policy${dbError.table ? ` on \"${dbError.table}\"` : \"\"} denying this role, ` +\n                \"or a stale FORCE ROW LEVEL SECURITY flag binding the owner connection.\"\n            );\n        }\n        // 25006 read_only_sql_transaction. A request-scoped read opens its\n        // transaction `READ ONLY`, so the only way to reach this is user code on\n        // a read path attempting a write — which means an `afterRead` callback,\n        // or something it called. Left in the generic branch it was a 500\n        // \"Internal Server Error\", indistinguishable from the database being\n        // down; it is the caller's own code, and it is not a server failure.\n        if (dbError.code === \"25006\") {\n            code = \"READ_ONLY_TRANSACTION\";\n            statusCode = 409;\n            parts.push(READ_ONLY_TRANSACTION_MESSAGE);\n        }\n        // SQLSTATE class 22 — data exception. The caller sent a value the\n        // column's type cannot hold: `?id=eq.abc` on an integer key,\n        // `?status=eq.nope` on an enum, a timestamp that is not one, a number\n        // past the type's range. Every *other* bad query parameter already has\n        // a precise 400 (`INVALID_LIMIT`, `UNKNOWN_FILTER_FIELD`,\n        // `INVALID_LOGICAL_GROUP`); a bad *value* fell off the end of this\n        // chain and answered 500 INTERNAL_ERROR — and in production `dbMessage`\n        // is stripped, so the caller got a bare 500 naming nothing and had no\n        // way to learn their own typo was the cause.\n        if (dbError.code?.startsWith(\"22\")) {\n            code = \"INVALID_FILTER_VALUE\";\n            statusCode = 400;\n        }\n        logMessage = parts.join(\". \");\n    }\n\n    const isDbSchemaMismatch = code === \"SCHEMA_DRIFT\";\n\n    // `logMessage`, not the sanitized client message: the request line is a\n    // server log, and the whole point of this branch is the diagnosis it built.\n    handOffToRequestLog(c, code, logMessage);\n\n    if (isDbSchemaMismatch) {\n        // Database schema mismatch is logged as a warning instead of a fatal error\n        if (!requestWillBeLogged(c)) logger.warn(\n            `⚠️ [API] ${c.req.method} ${c.req.path} → ${statusCode} ${code}: ${logMessage}` +\n            (reqId ? ` [${reqId}]` : \"\")\n        );\n        // In dev mode, show a one-time hint to run `rebase doctor`\n        if (!_schemaDriftHinted && hostEnv().NODE_ENV !== \"production\") {\n            _schemaDriftHinted = true;\n            // Drawn rather than hand-aligned: the remedy inside it now varies\n            // with the database, and a box whose rows were padded by hand\n            // stayed straight only for the text it was written around.\n            const WIDTH = 62;\n            const row = (text: string) => `│${text.padEnd(WIDTH).slice(0, WIDTH)}│`;\n            logger.warn([\n                \"\",\n                `┌${\"─\".repeat(WIDTH)}┐`,\n                // One space short, deliberately: the emoji occupies two columns\n                // in a terminal and one in `String.length`.\n                `│${\"  💡 TIP: Run `rebase doctor` for full schema diagnostics\".padEnd(WIDTH - 1)}│`,\n                row(\"\"),\n                ...schemaDriftRemedy().lines.map(row),\n                `└${\"─\".repeat(WIDTH)}┘`,\n                \"\"\n            ].join(\"\\n\"));\n        }\n    } else if (code === \"READ_ONLY_TRANSACTION\" || code === \"INVALID_FILTER_VALUE\") {\n        // A 4xx: the application's own callback, refused — or a filter value\n        // the caller's own request could not have worked with. Not a server\n        // fault, so not an ❌ in the log either — and, like the drift arm above,\n        // not a second line when the request log is already going to carry it.\n        if (!requestWillBeLogged(c)) logger.warn(\n            `⚠️ [API] ${c.req.method} ${c.req.path} → ${statusCode} ${code}: ${logMessage}` +\n            (reqId ? ` [${reqId}]` : \"\")\n        );\n    } else if (!requestWillBeLogged(c)) {\n        // Unexpected errors — log at error level\n        logger.error(\n            `❌ [API] ${c.req.method} ${c.req.path} → ${statusCode} ${code}: ${logMessage}` +\n            (reqId ? ` [${reqId}]` : \"\")\n        );\n    }\n\n    // Suppress the huge stack trace for known DB errors: it is noisy, and the\n    // extracted [PG …] line above carries the signal. The SQL and the bound\n    // params it used to leak are no longer this branch's problem — `logger`\n    // strips Drizzle's `Failed query: … / params: …` wrapper out of every\n    // message and stack it emits, so the fallbacks below (a connection dropped\n    // mid-statement carries no SQLSTATE, so `dbError` is null and the stack is\n    // logged) are covered too.\n    const suppressStack = isDbSchemaMismatch || dbError !== null || (statusCode < 500 && code === \"BAD_REQUEST\");\n    if (!suppressStack) {\n        // The error goes in as a value, not as `String(error.stack)`. A string\n        // is a leaf to the logger: `serialiseError` — the `.cause`/\n        // `AggregateError` walker the boot path relies on — never runs on one,\n        // so the request path used to print the outer wrapper's stack and drop\n        // the sentence that says what actually failed (`connect ECONNRESET`,\n        // sitting two `.cause` links down). Structured, it walks the chain and\n        // redacts each link on the way.\n        logger.error(\"unhandled request error\", { error });\n    }\n\n    // Sanitize the message for the client to prevent leaking sensitive details\n    // like SQL queries or internal IP addresses.\n    let clientMessage = \"An unexpected error occurred\";\n    if (code === \"READ_ONLY_TRANSACTION\") {\n        // Ahead of the generic 4xx arm below, which would echo the raw driver\n        // message (\"Failed query: insert into …\") back to the caller.\n        clientMessage = READ_ONLY_TRANSACTION_MESSAGE;\n    } else if (code === \"INVALID_FILTER_VALUE\") {\n        // Also ahead of the 4xx arm: `error.message` here is the driver's\n        // \"Failed query: select … / params: …\", which is both unhelpful and the\n        // one thing this envelope must never carry.\n        clientMessage = describeDataException(dbError || (error as PgLikeError));\n    } else if (statusCode < 500 && error.message) {\n        // If it's a 4xx error (e.g. from validation), it's generally safe to send the message\n        clientMessage = error.message;\n    } else if (error instanceof ApiError || error.name === \"ApiError\") {\n        // We already handled ApiError above, but just in case\n        clientMessage = error.message;\n    } else if (code === \"SCHEMA_DRIFT\") {\n        const pgErr = dbError || (error as PgLikeError);\n        const issue = pgErr.code === \"42703\" ? \"column\" : \"table\";\n        const identifier = pgErr.table || pgErr.column || extractMissingIdentifier(pgErr.message || error.message) || \"unknown\";\n        clientMessage = `Schema drift: ${issue} \"${identifier}\" does not exist. ${schemaDriftRemedy().short}`;\n    } else if (code === \"DB_PERMISSION_DENIED\") {\n        clientMessage = `Permission denied by the database${dbError?.table ? ` on \"${dbError.table}\"` : \"\"} (row-level security). Check the RLS policies for this table.`;\n    } else if (code === \"INTERNAL_ERROR\") {\n        clientMessage = \"Internal Server Error\";\n    }\n\n    // Database diagnostics for the envelope: the SQLSTATE is always safe to\n    // return; message/detail/hint can reference schema internals, so only\n    // outside production.\n    const dbDetails = dbError ? {\n        dbCode: dbError.code,\n        ...(hostEnv().NODE_ENV !== \"production\" && {\n            dbMessage: dbError.message,\n            ...(dbError.detail && { detail: dbError.detail }),\n            ...(dbError.hint && { hint: dbError.hint })\n        })\n    } : undefined;\n\n    const drift = driftFor(statusCode);\n\n    return c.json({\n        error: {\n            message: clientMessage,\n            code,\n            ...(error.details !== undefined\n                ? { details: error.details }\n                : dbDetails !== undefined ? { details: dbDetails } : {}),\n            ...(reqId && { requestId: reqId }),\n            ...(drift && { cause: drift })\n        }\n    } satisfies ErrorResponse, statusCode as ContentfulStatusCode);\n};\n\n/**\n * Map known error codes to HTTP status codes.\n */\nfunction codeToStatus(code?: string): number | undefined {\n    if (!code) return undefined;\n    const map: Record<string, number> = {\n        BAD_REQUEST: 400,\n        INVALID_INPUT: 400,\n        WEAK_PASSWORD: 400,\n        UNAUTHORIZED: 401,\n        INVALID_CREDENTIALS: 401,\n        INVALID_TOKEN: 401,\n        FORBIDDEN: 403,\n        NOT_FOUND: 404,\n        CONFLICT: 409,\n        EMAIL_EXISTS: 409,\n        ROLE_EXISTS: 409,\n        READ_ONLY_TRANSACTION: 409,\n        INVALID_FILTER_VALUE: 400,\n        SCHEMA_DRIFT: 500,\n        DB_PERMISSION_DENIED: 500,\n        INTERNAL_ERROR: 500,\n        NOT_CONFIGURED: 503,\n        SERVICE_UNAVAILABLE: 503\n    };\n    return map[code];\n}\n\n\n"],"mappings":"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"}

package/dist/function-routes-Chet4-lB.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"function-routes-Chet4-lB.js","names":[],"sources":["../src/functions/context.ts","../src/functions/guards.ts","../src/functions/function-routes.ts"],"sourcesContent":["/**\n * Reading the request context from inside a custom function.\n *\n * The functions router resolves the caller's identity before any handler runs\n * and leaves the result on the Hono context. Getting it back out used to be the\n * user's problem, and the shape made that worse than it sounds: `HonoEnv`\n * types `user` as `AuthResult`, a union that includes `boolean`, `null` and an\n * index signature, because the same slot is filled by four different middlewares\n * — JWT, service key, API key, and a user-supplied validator that may return\n * `true`. Every example in the documentation therefore opened with\n *\n *     const user = c.get(\"user\") as { uid: string; roles?: string[] } | undefined;\n *\n * and an assertion in a security-relevant position is exactly the kind of line\n * that gets copied once and then never re-examined. It is also wrong in one\n * case that occurs in practice: a custom validator returning `true` stores\n * `{ uid: \"default\", roles: [] }`, which the assertion above types as having a\n * `uid` — true here, but nothing checks it.\n *\n * These accessors do the narrowing once, in the framework, where it can be\n * tested. They are also **runtime-neutral by construction** — no crypto, no\n * token parsing, no I/O, nothing but property reads on an object another\n * middleware already populated. That is what lets them live in\n * `@rebasepro/server/functions` and run unchanged on a host that has no Node\n * built-ins.\n *\n * @module\n */\nimport type { Context } from \"hono\";\nimport type { DataDriver } from \"@rebasepro/types\";\nimport type { HonoEnv } from \"../api/types\";\nimport type { ApiKeyMasked } from \"../auth/api-keys/api-key-types\";\nimport { hasAdministrativeRole } from \"../auth/admin-roles\";\n\n/**\n * The caller, as a custom function sees them.\n *\n * A narrowed view of whatever the auth middleware resolved: `uid` and `roles`\n * are guaranteed, and the index signature keeps any extra claims the token or\n * the adapter carried (`email`, `org_id`, anything a custom validator added)\n * reachable without a cast.\n */\nexport interface FunctionUser {\n    /** Stable id of the caller. `\"service\"` for service-key and API-key callers. */\n    uid: string;\n    /** Roles as resolved for this request. Never `undefined` — an empty array instead. */\n    roles: string[];\n    /** Present when the identity carried one. Not every auth method does. */\n    email?: string;\n    /** Any further claim the token, adapter or validator supplied. */\n    [claim: string]: unknown;\n}\n\n/** Anything with a Hono-style `.get`, so these work on any `Context` shape. */\ntype CtxLike = Context<HonoEnv> | Context;\n\nfunction read<K extends keyof HonoEnv[\"Variables\"]>(\n    c: CtxLike,\n    key: K\n): HonoEnv[\"Variables\"][K] | undefined {\n    // `c.get` is typed against the app's own Env, which a handler mounted\n    // through `app.route()` may have declared more loosely. The cast is\n    // confined to this one function rather than repeated at every call site.\n    return (c as Context<HonoEnv>).get(key);\n}\n\n/**\n * The authenticated caller, or `undefined` for an anonymous request.\n *\n * **`undefined` is not a permission decision.** The functions router mounts its\n * auth middleware with `requireAuth: false` on purpose — a webhook receiver has\n * no token to send — so an anonymous caller reaches the handler and reads\n * `undefined` here while the handler runs on regardless. Use {@link requireAuth}\n * (or a `!user` branch that returns 401) to make it a decision.\n *\n * A caller who presented a *bad* token never gets this far: both auth\n * middlewares reject an unverifiable token with 401 before the router is\n * reached, precisely so an expired session cannot be silently downgraded to an\n * anonymous one.\n */\nexport function getUser(c: CtxLike): FunctionUser | undefined {\n    const raw = read(c, \"user\");\n    if (!raw || typeof raw !== \"object\") return undefined;\n\n    const record = raw as Record<string, unknown>;\n    const uid = typeof record.uid === \"string\" ? record.uid : undefined;\n    if (uid === undefined) return undefined;\n\n    const roles = Array.isArray(record.roles)\n        ? record.roles.filter((role): role is string => typeof role === \"string\")\n        : [];\n\n    return { ...record,\n        uid,\n        roles } as FunctionUser;\n}\n\n/** The caller's id, or `undefined` when nobody is signed in. */\nexport function getUserId(c: CtxLike): string | undefined {\n    return getUser(c)?.uid;\n}\n\n/** The caller's roles. Empty for an anonymous request — never `undefined`. */\nexport function getRoles(c: CtxLike): string[] {\n    return getUser(c)?.roles ?? [];\n}\n\n/**\n * Whether the caller holds **any** of the named roles.\n *\n * Any rather than all, because that is what a route guard means by a list of\n * roles; require several by calling this more than once.\n */\nexport function hasRole(c: CtxLike, ...roles: string[]): boolean {\n    if (roles.length === 0) return false;\n    const held = new Set(getRoles(c));\n    return roles.some(role => held.has(role));\n}\n\n/**\n * Whether the caller holds an administrative role.\n *\n * Delegates to the single definition in `auth/admin-roles.ts` — which is\n * `admin` **or** `schema-admin` — rather than comparing against `\"admin\"`.\n * Those two lists disagreed once, and the gap made every public registrant an\n * administrator; see that file.\n */\nexport function isAdmin(c: CtxLike): boolean {\n    return hasAdministrativeRole(getRoles(c));\n}\n\n/** Whether the request carries an identity at all. */\nexport function isAuthenticated(c: CtxLike): boolean {\n    return getUser(c) !== undefined;\n}\n\n/**\n * The request-scoped data driver: reads and writes run as **the caller**, with\n * your row-level security policies evaluated against their identity.\n *\n * This is the accessor to reach for when a function serves user-facing data.\n * `rebase.dataAsAdmin` is the other one, and it is not the same thing — it runs\n * as `{ uid: \"service\", roles: [\"admin\"] }` for every caller alike, which is\n * correct for trusted background work and wrong for a request.\n *\n * `undefined` only when no Rebase auth middleware ran (see\n * {@link identityResolved}); inside a function mounted by the framework it is\n * always present, anonymous requests included — they get an anon-scoped driver\n * so policies still have an identity to evaluate.\n */\nexport function getDriver(c: CtxLike): DataDriver | undefined {\n    return read(c, \"driver\");\n}\n\n/**\n * {@link getDriver}, but throws instead of handing back `undefined`.\n *\n * For the common case where a handler cannot proceed without it and would\n * otherwise write `c.get(\"driver\")!` — an assertion that turns a wiring problem\n * into `Cannot read properties of undefined (reading 'fetchCollection')` twenty\n * lines away from the cause.\n */\nexport function requireDriver(c: CtxLike): DataDriver {\n    const driver = getDriver(c);\n    if (!driver) {\n        throw new Error(\n            \"No request-scoped driver on this context. A Rebase auth middleware \" +\n            \"populates it before any custom function runs, so this means the handler \" +\n            \"was mounted outside the functions router — e.g. added to your own Hono \" +\n            \"app directly. Mount it from the functions directory, or use \" +\n            \"`rebase.dataAsAdmin` if the work is genuinely service-scoped.\"\n        );\n    }\n    return driver;\n}\n\n/**\n * The API key this request authenticated with, masked, or `undefined` when it\n * did not use one.\n *\n * Useful for attribution and for per-key behaviour. The permission check itself\n * has already happened — reaching a handler means the key was allowed to.\n */\nexport function getApiKey(c: CtxLike): ApiKeyMasked | undefined {\n    return read(c, \"apiKey\");\n}\n\n/**\n * The correlation id for this request — generated, or taken from an inbound\n * `X-Request-ID`.\n *\n * Log it. It is the only thing that ties a line written inside a function to\n * the framework's own lines for the same request.\n */\nexport function getRequestId(c: CtxLike): string | undefined {\n    return read(c, \"requestId\");\n}\n\n/**\n * Whether a Rebase auth middleware has run on this request.\n *\n * Both middlewares populate `driver` for *every* outcome, anonymous included,\n * and populate `user` whenever there is one. So \"neither is set\" does not mean\n * \"anonymous\" — it means nothing resolved the identity, and treating that as\n * anonymous is the dangerous reading. The guards use this to tell a genuinely\n * anonymous caller (401) from a misconfigured mount (500), because answering\n * 401 to the second sends whoever is debugging it to look at the token.\n */\nexport function identityResolved(c: CtxLike): boolean {\n    return read(c, \"user\") !== undefined || read(c, \"driver\") !== undefined;\n}\n","/**\n * Route guards for custom functions.\n *\n * These decide access from the identity the platform already resolved. They do\n * **not** verify tokens, and that division is the point rather than a\n * limitation:\n *\n * - Verifying a token needs a signing key, constant-time comparison and a\n *   revocation lookup. That is host work, it belongs to the process that holds\n *   the secret, and it is the part of the stack that cannot be made\n *   runtime-neutral without rewriting it against WebCrypto.\n * - Deciding whether *this* caller may call *this* route is application work.\n *   It needs nothing but the resolved identity, so it costs nothing to make it\n *   portable — and it is the half that lives in user code.\n *\n * Splitting there is what lets a function file compile and run unchanged on a\n * host with no Node built-ins, and it is why these live in\n * `@rebasepro/server/functions` while `verifyAccessToken` does not.\n *\n * **Inside the functions router these are equivalent to the guards exported\n * from the package root.** Both auth middlewares resolve the identity before\n * any handler runs: a valid credential populates `user`, an invalid one is\n * rejected with 401 by the middleware itself, and a missing one leaves `user`\n * unset. So the root `requireAuth`'s token-parsing branch is unreachable from a\n * function, and removing it changes no outcome. The one difference is a handler\n * mounted **outside** the framework's router, where no middleware ran: the root\n * guard would parse the `Authorization` header itself, and these refuse the\n * request with a 500 that names the wiring problem. Fail-closed, and legible.\n *\n * @module\n */\nimport type { MiddlewareHandler } from \"hono\";\nimport type { HonoEnv } from \"../api/types\";\nimport { getUser, isAdmin, getRoles, identityResolved } from \"./context\";\n\n/**\n * The answer to \"a guard ran, but no middleware had resolved anything\".\n *\n * Deliberately a 500 and not a 401. A 401 tells the caller their credential is\n * the problem, and here the caller's credential was never looked at — sending\n * them to check their token is sending them to the one place the answer is not.\n */\nfunction unresolvedIdentity(): { error: { message: string; code: string } } {\n    return {\n        error: {\n            message:\n                \"This route's identity was never resolved: no Rebase auth middleware ran \" +\n                \"before the guard. A function loaded from the functions directory always \" +\n                \"has one. This usually means the Hono app was mounted onto your own \" +\n                \"server directly, bypassing the functions router.\",\n            code: \"AUTH_MIDDLEWARE_MISSING\"\n        }\n    };\n}\n\n/**\n * Reject anonymous callers with 401.\n *\n * Put it in the route's own middleware slot rather than `app.use(\"/*\", …)`:\n * `use()` covers only the routes declared *below* it, so a route appended later\n * — by you, months from now, at the bottom of the file — is silently\n * unprotected. The per-route form cannot drift that way.\n *\n * @example\n * ```ts\n * app.post(\"/\", requireAuth, async (c) => {\n *     const user = getUser(c)!;  // guaranteed by the guard\n *     return c.json({ uid: user.uid });\n * });\n * ```\n */\nexport const requireAuth: MiddlewareHandler<HonoEnv> = async (c, next) => {\n    if (getUser(c)) return next();\n    if (!identityResolved(c)) return c.json(unresolvedIdentity(), 500);\n\n    return c.json({\n        error: {\n            message: \"Authentication required\",\n            code: \"UNAUTHORIZED\"\n        }\n    }, 401);\n};\n\n/**\n * Reject callers without an administrative role with 403.\n *\n * Must come **after** {@link requireAuth}: on its own it answers 401 for an\n * anonymous caller, which is right, but pairing them keeps the two failures\n * distinguishable — 401 \"who are you\", 403 \"not you\".\n *\n * Administrative means `admin` or `schema-admin`, from the single list in\n * `auth/admin-roles.ts`. Do not compare against `\"admin\"` by hand; that is the\n * divergence that list exists to prevent.\n */\nexport const requireAdmin: MiddlewareHandler<HonoEnv> = async (c, next) => {\n    const user = getUser(c);\n    if (!user) {\n        if (!identityResolved(c)) return c.json(unresolvedIdentity(), 500);\n        return c.json({\n            error: {\n                message: \"Authentication required\",\n                code: \"UNAUTHORIZED\"\n            }\n        }, 401);\n    }\n\n    if (!isAdmin(c)) {\n        return c.json({\n            error: {\n                message: \"Admin privileges required for this operation\",\n                code: \"FORBIDDEN\"\n            }\n        }, 403);\n    }\n\n    return next();\n};\n\n/**\n * Reject callers holding none of the named roles with 403.\n *\n * Any of them, not all — require several by chaining the guard twice. Naming no\n * role at all is a programming error and throws at module load rather than at\n * request time, because `requireRole()` with an empty list would otherwise read\n * as a guard while admitting everyone.\n *\n * @example\n * ```ts\n * app.post(\"/publish\", requireAuth, requireRole(\"editor\", \"admin\"), handler);\n * ```\n */\nexport function requireRole(...roles: string[]): MiddlewareHandler<HonoEnv> {\n    if (roles.length === 0) {\n        throw new Error(\n            \"requireRole() needs at least one role. An empty list would admit every \" +\n            \"signed-in caller while reading as a restriction.\"\n        );\n    }\n\n    const allowed = new Set(roles);\n    return async (c, next) => {\n        const user = getUser(c);\n        if (!user) {\n            if (!identityResolved(c)) return c.json(unresolvedIdentity(), 500);\n            return c.json({\n                error: {\n                    message: \"Authentication required\",\n                    code: \"UNAUTHORIZED\"\n                }\n            }, 401);\n        }\n\n        if (!getRoles(c).some(role => allowed.has(role))) {\n            return c.json({\n                error: {\n                    message: `This operation requires one of these roles: ${roles.join(\", \")}`,\n                    code: \"FORBIDDEN\"\n                }\n            }, 403);\n        }\n\n        return next();\n    };\n}\n","import { Hono } from \"hono\";\nimport { HonoEnv } from \"../api/types\";\nimport { ApiError } from \"../api/errors\";\nimport { LoadedFunction } from \"./function-loader\";\nimport { requireAuth } from \"./guards\";\n\n/** The file a loader problem names, without its extension: `broken.ts (threw: …)` → `broken`. */\nfunction problemName(problem: string): string {\n    return problem.split(\" \")[0].replace(/\\/$/, \"\").replace(/\\.[cm]?[jt]s$/, \"\");\n}\n\n/**\n * Mount all loaded function routes under a single Hono router.\n *\n * Each function is mounted at `/<function-name>`, preserving\n * whatever HTTP methods and middleware the Hono sub-app defines.\n *\n * @param functions What loaded. May be empty — the router still mounts, so\n *   \"no functions are served\" answers 200 with an empty list instead of 404.\n * @param problems The files the loader saw and could not serve, as\n *   `\"<file> (<reason>)\"`. The listing reports a count and a pointer to the log,\n *   not the reasons: those carry import errors, and the listing is one guard\n *   away from anyone. The unmatched-route handler uses the *names* to answer the\n *   one question a 404 on a function nobody can find should answer — \"there is a\n *   file for this and it did not load\" — which is the difference between a typo\n *   and a broken deploy, and the loader was the only thing that knew.\n */\nexport function createFunctionRoutes(\n    functions: LoadedFunction[],\n    problems: string[] = [],\n    /**\n     * Where this router is mounted, so the listing can report a path a caller\n     * can actually request. It used to hardcode `/functions/<name>`, which is\n     * wrong under every `basePath` including the default `/api`.\n     */\n    mountPath = \"/functions\"\n): Hono<HonoEnv> {\n    const router = new Hono<HonoEnv>();\n    const skipped = problems.length;\n\n    // Listing endpoint: GET / → list available functions.\n    //\n    // Functions themselves stay anonymous-callable by default — a webhook\n    // receiver has to be — but the index of them does not: it is an inventory\n    // of every custom endpoint, for whoever asks. `requireAuth` admits any\n    // resolved identity (a signed-in user, an API key, the service key), so\n    // `rebase doctor` and `rebase cloud debug` keep their answer; the latter\n    // already reads a 401 here as \"mounted\".\n    router.get(\"/\", requireAuth, (c) => {\n        return c.json({\n            functions: functions.map((fn) => ({\n                name: fn.name,\n                endpoint: `${mountPath}/${fn.name}`\n            })),\n            ...(skipped > 0 && {\n                skipped,\n                note: `${skipped} function file(s) failed to load and are NOT served — see the server log for the reason.`\n            })\n        });\n    });\n\n    for (const fn of functions) {\n        router.route(`/${fn.name}`, fn.app);\n    }\n\n    // A name that matches nothing, answered in the envelope.\n    //\n    // Registered last so every real route wins it. Without it, a typo'd\n    // function name — the single most likely 404 a developer meets on this\n    // surface — fell through to Hono's default `404 Not Found` as `text/plain`,\n    // and through the SDK arrived as `RebaseApiError { code: undefined }`, so\n    // the documented `e.code === \"FUNCTION_NOT_FOUND\"` branch never ran.\n    //\n    // What the message may say depends on who is asking. The mounted names are\n    // an inventory of every custom endpoint, which is exactly what the listing\n    // above requires an identity to see — so an anonymous caller is told their\n    // name is unknown and nothing more, and a resolved caller gets the list\n    // that turns the 404 into a fix.\n    const mounted = new Set(functions.map(fn => fn.name));\n    const failedToLoad = new Map(problems.map(p => [problemName(p), p.split(\" \")[0]]));\n\n    router.all(\"/:name{.*}\", (c): never => {\n        const requested = (c.req.param(\"name\") ?? \"\").split(\"/\").filter(Boolean);\n        const name = requested[0] ?? \"\";\n        const rest = requested.slice(1).join(\"/\");\n        const identified = Boolean(c.get(\"user\"));\n\n        const refuse = (message: string): never => {\n            throw new ApiError(404, \"FUNCTION_NOT_FOUND\", message, { function: name }, true);\n        };\n\n        if (!name) {\n            refuse(`No function in the request path. Expected ${mountPath}/<function>.`);\n        }\n        if (mounted.has(name)) {\n            refuse(\n                `The function '${name}' is served, and has no ${c.req.method} route at '/${rest}'. ` +\n                \"The path after the function name is routed by the function's own Hono app.\"\n            );\n        }\n        const file = failedToLoad.get(name);\n        if (file) {\n            refuse(\n                `The function '${name}' is not served: '${file}' failed to load. ` +\n                \"The server log records why, at boot.\"\n            );\n        }\n        return refuse(\n            `No function named '${name}' on this backend.` +\n            (identified\n                ? (mounted.size > 0\n                    ? ` This backend serves: ${[...mounted].sort().join(\", \")}.`\n                    : \" This backend serves no functions.\")\n                : \"\") +\n            (skipped > 0 && identified\n                ? ` ${skipped} function file(s) failed to load and are not served — see the server log.`\n                : \"\")\n        );\n    });\n\n    return router;\n}\n"],"mappings":"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"}

package/dist/history-recorder-BQmB0P_j.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"history-recorder-BQmB0P_j.js","names":[],"sources":["../src/metrics/history-recorder.ts"],"sourcesContent":["/**\n * Wiring the history store to a driver and a timer.\n *\n * Split from `history-store.ts` so the store stays pure — every rule in it is\n * testable with a fake executor, and nothing there knows what a DataDriver is.\n * This half is the part that cannot be unit-tested meaningfully: it opens a\n * connection and starts an interval.\n */\nimport { monitorEventLoopDelay } from \"node:perf_hooks\";\nimport { logger } from \"../utils/logger.js\";\nimport type { DataDriver } from \"@rebasepro/types\";\nimport {\n    ensureMetricsHistory,\n    recordSamples,\n    readSeries,\n    sampleSelf,\n    SAMPLE_INTERVAL_MS,\n    type Exec,\n    type MetricSeries,\n    type SeriesPoint\n} from \"./history-store.js\";\n\nexport interface MetricsHistory {\n    /** Create the table and sweep what has aged out. */\n    ensure(): Promise<void>;\n    /** Begin sampling this process. Returns a stop. */\n    start(): () => void;\n    /** Read one series, for the route and for anything else that asks. */\n    read(series: MetricSeries, sinceMinutes: number): Promise<SeriesPoint[]>;\n}\n\n/** Narrow structural check, matching how the job store decides the same thing. */\nfunction sqlExecutorOf(driver: DataDriver): Exec | undefined {\n    const admin = (driver as { admin?: { executeSql?: unknown } }).admin;\n    if (!admin || typeof admin.executeSql !== \"function\") return undefined;\n    const executeSql = admin.executeSql as (sql: string, opts?: { params?: unknown[] }) => Promise<unknown>;\n    return (sql, params) => executeSql(sql, params ? { params } : undefined);\n}\n\n/**\n * History for this deployment, or `undefined` when it cannot have any.\n *\n * Undefined rather than a no-op: the route turns it into a named 501, because a\n * chart that renders empty is indistinguishable from a quiet period and this is\n * exactly the class of silence the panel it feeds exists to remove.\n */\nexport function createMetricsHistory(driver: DataDriver): MetricsHistory | undefined {\n    const exec = sqlExecutorOf(driver);\n    if (!exec) {\n        logger.debug(\"[metrics] driver has no SQL admin — no metrics history will be kept.\");\n        return undefined;\n    }\n\n    return {\n        ensure: () => ensureMetricsHistory(exec),\n        read: (series, sinceMinutes) => readSeries(exec, series, sinceMinutes),\n        start(): () => void {\n            // Which process this is. A tenant's replicas share one database and\n            // each records its own numbers, so a row needs to say whose they\n            // are — without it they overwrite each other and a scaled-out app\n            // charts one arbitrary pod.\n            //\n            // HOSTNAME is the pod name on Kubernetes and the container id under\n            // Docker; the pid fallback keeps two local processes distinct.\n            const instance = process.env.HOSTNAME?.trim() || `pid-${process.pid}`;\n            let cursor: { cpu: NodeJS.CpuUsage; at: number } | null = null;\n            let stopped = false;\n\n            // Event-loop delay: how long a callback waited past its schedule.\n            // The one number here that says whether this process is *healthy*\n            // rather than how much it is consuming — a pod can sit at 20% CPU\n            // and still be unable to answer, and nothing else recorded would\n            // show it.\n            //\n            // `monitorEventLoopDelay` samples in libuv at a fixed resolution and\n            // costs effectively nothing; `.enable()` is required, and the\n            // histogram is reset each tick so every sample describes its own\n            // minute rather than the process's whole life.\n            interface LoopHistogram { mean: number; enable(): void; reset(): void }\n            let loop: LoopHistogram | null = null;\n            try {\n                loop = monitorEventLoopDelay({ resolution: 20 }) as LoopHistogram;\n                loop.enable();\n            } catch {\n                // A runtime without it still records the other two.\n                loop = null;\n            }\n\n            const tick = async () => {\n                if (stopped) return;\n                // Nanoseconds from the histogram, milliseconds on the wire.\n                const delayMs = loop ? loop.mean / 1e6 : undefined;\n                loop?.reset();\n                const { samples, cursor: next } = sampleSelf(cursor, Date.now(), delayMs);\n                cursor = next;\n                try {\n                    await recordSamples(exec, samples, instance);\n                } catch (err) {\n                    // Never fatal, and never noisy: a sampler that crash-loops a\n                    // pod over a chart would be a far worse trade than a gap in\n                    // one. The gap is visible in the data; a restart loop is not.\n                    logger.debug(\"[metrics] could not record a sample\", { err });\n                }\n            };\n\n            // The first tick establishes the CPU cursor and publishes memory;\n            // the rate needs a second reading, which is why nothing claims a CPU\n            // figure until one interval has passed.\n            void tick();\n            const timer = setInterval(() => void tick(), SAMPLE_INTERVAL_MS);\n            // Not the reason this process should stay alive.\n            timer.unref?.();\n\n            return () => { stopped = true; clearInterval(timer); };\n        }\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAgCA,SAAS,cAAc,QAAsC;CACzD,MAAM,QAAS,OAAgD;CAC/D,IAAI,CAAC,SAAS,OAAO,MAAM,eAAe,YAAY,OAAO,KAAA;CAC7D,MAAM,aAAa,MAAM;CACzB,QAAQ,KAAK,WAAW,WAAW,KAAK,SAAS,EAAE,OAAO,IAAI,KAAA,CAAS;AAC3E;;;;;;;;AASA,SAAgB,qBAAqB,QAAgD;CACjF,MAAM,OAAO,cAAc,MAAM;CACjC,IAAI,CAAC,MAAM;EACP,OAAO,MAAM,sEAAsE;EACnF;CACJ;CAEA,OAAO;EACH,cAAc,qBAAqB,IAAI;EACvC,OAAO,QAAQ,iBAAiB,WAAW,MAAM,QAAQ,YAAY;EACrE,QAAoB;GAQhB,MAAM,WAAW,QAAQ,IAAI,UAAU,KAAK,KAAK,OAAO,QAAQ;GAChE,IAAI,SAAsD;GAC1D,IAAI,UAAU;GAad,IAAI,OAA6B;GACjC,IAAI;IACA,OAAO,sBAAsB,EAAE,YAAY,GAAG,CAAC;IAC/C,KAAK,OAAO;GAChB,QAAQ;IAEJ,OAAO;GACX;GAEA,MAAM,OAAO,YAAY;IACrB,IAAI,SAAS;IAEb,MAAM,UAAU,OAAO,KAAK,OAAO,MAAM,KAAA;IACzC,MAAM,MAAM;IACZ,MAAM,EAAE,SAAS,QAAQ,SAAS,WAAW,QAAQ,KAAK,IAAI,GAAG,OAAO;IACxE,SAAS;IACT,IAAI;KACA,MAAM,cAAc,MAAM,SAAS,QAAQ;IAC/C,SAAS,KAAK;KAIV,OAAO,MAAM,uCAAuC,EAAE,IAAI,CAAC;IAC/D;GACJ;GAKA,KAAU;GACV,MAAM,QAAQ,kBAAkB,KAAK,KAAK,GAAG,kBAAkB;GAE/D,MAAM,QAAQ;GAEd,aAAa;IAAE,UAAU;IAAM,cAAc,KAAK;GAAG;EACzD;CACJ;AACJ"}