primitive-admin 1.1.0-alpha.78 → 1.1.0-alpha.79

package/dist/src/lib/generated-config-surfaces.js

@@ -1284,6 +1284,62 @@ export const MAX_MANIFEST_QUERIES = 200;
 export const MAX_MANIFEST_NAME_LENGTH = 120;
 export const MAX_MANIFEST_MODELS = 200;
 export const MAX_MANIFEST_FAMILIES = 40;
+/** The scalar parameter types a registration may declare, and an array's element types. */
+export const QUERY_PARAM_SCALAR_TYPES = ["string", "number", "boolean", "any"];
+/**
+ * Coerce one value to a declared parameter type the way the SDK coerces a
+ * SUPPLIED value: a digit string becomes a number, `"true"`/`"false"` a
+ * boolean, an array's elements each by the `items` type. Applied to a
+ * declared `default` at registration (D3281-SO-005) so what `run` receives is
+ * what the declaration promises — here at push (the collect stub and this
+ * grammar) and in the SDK at the first load. ONE rule, spelled in the SDK's
+ * source a second time because that module is baked text; the tests hold the
+ * two together.
+ */
+export function coerceParamDefault(spec, value) {
+    const type = spec.type === undefined ? "any" : String(spec.type);
+    if (type === "array") {
+        if (!Array.isArray(value))
+            return { ok: false, reason: "must be an array" };
+        const itemType = spec.items?.type === undefined ? "any" : String(spec.items.type);
+        const out = [];
+        for (const element of value) {
+            const coerced = coerceScalar(itemType, element);
+            // `=== false` rather than `!`: the CLI's vendored copy compiles without
+            // strict null checks, where truthiness does not narrow the union.
+            if (coerced.ok === false) {
+                return { ok: false, reason: `every element ${coerced.reason}` };
+            }
+            out.push(coerced.value);
+        }
+        return { ok: true, value: out };
+    }
+    return coerceScalar(type, value);
+}
+function coerceScalar(type, value) {
+    if (type === "number") {
+        const asNumber = typeof value === "number" ? value : Number(value);
+        if (typeof value === "boolean" || value === null || value === "" || !Number.isFinite(asNumber)) {
+            return { ok: false, reason: "must be a number" };
+        }
+        return { ok: true, value: asNumber };
+    }
+    if (type === "boolean") {
+        if (typeof value === "boolean")
+            return { ok: true, value };
+        if (value === "true")
+            return { ok: true, value: true };
+        if (value === "false")
+            return { ok: true, value: false };
+        return { ok: false, reason: "must be a boolean" };
+    }
+    if (type === "string") {
+        if (typeof value !== "string")
+            return { ok: false, reason: "must be a string" };
+        return { ok: true, value };
+    }
+    return { ok: true, value };
+}
 /**
  * Validate a manifest's grammar and normalize it.
  *
@@ -1365,13 +1421,44 @@ export function parseFunctionManifest(value) {
                         "something other than an object.");
                     continue;
                 }
+                // #3281 — an array parameter carries its element type; `caller` is a
+                // scalar binding and cannot be a list; a default is recorded COERCED
+                // to the declared type, or the entry is refused (D3281-SO-005).
+                const declaredType = spec.type === undefined ? undefined : String(spec.type);
+                let items;
+                if (declaredType === "array") {
+                    if (spec.items !== undefined && spec.items !== null) {
+                        const itemType = spec.items && typeof spec.items === "object" ? String(spec.items.type ?? "") : "";
+                        if (!QUERY_PARAM_SCALAR_TYPES.includes(itemType)) {
+                            errors.push(`manifest entry '${name}' declares parameter '${key}' with an \`items\` ` +
+                                `type outside ${QUERY_PARAM_SCALAR_TYPES.join(", ")}.`);
+                            continue;
+                        }
+                        items = { type: itemType };
+                    }
+                    if (spec.caller === true) {
+                        errors.push(`manifest entry '${name}' declares parameter '${key}' as an array bound to ` +
+                            "$caller; `caller` is a scalar binding.");
+                        continue;
+                    }
+                }
+                let defaultValue;
+                const hasDefault = Object.prototype.hasOwnProperty.call(spec, "default");
+                if (hasDefault) {
+                    const coerced = coerceParamDefault({ type: declaredType, items }, spec.default);
+                    if (coerced.ok === false) {
+                        errors.push(`manifest entry '${name}' declares parameter '${key}' with a default that ` +
+                            `${coerced.reason}.`);
+                        continue;
+                    }
+                    defaultValue = coerced.value;
+                }
                 params[key] = {
-                    ...(spec.type !== undefined ? { type: String(spec.type) } : {}),
+                    ...(declaredType !== undefined ? { type: declaredType } : {}),
+                    ...(items !== undefined ? { items } : {}),
                     ...(spec.caller === true ? { caller: true } : {}),
                     ...(spec.optional === true ? { optional: true } : {}),
-                    ...(Object.prototype.hasOwnProperty.call(spec, "default")
-                        ? { default: spec.default }
-                        : {}),
+                    ...(hasDefault ? { default: defaultValue } : {}),
                 };
             }
         }
@@ -1441,6 +1528,732 @@ export function parseFunctionManifest(value) {
         errors: [],
     };
 }
+export const FUNCTION_MODES = ["request", "task"];
+/**
+ * Resolve `mode` and its alias `durable` to one mode.
+ *
+ * Absent both → `request`. `mode` must be exactly `"request"` or `"task"`;
+ * `durable` must be a boolean. Both present and disagreeing is refused naming
+ * both keys, so an author who half-migrated a file hears which line to fix.
+ */
+export function resolveDeclaredMode(input) {
+    const rawMode = input?.mode;
+    const rawDurable = input?.durable;
+    const hasMode = rawMode !== undefined && rawMode !== null;
+    const hasDurable = rawDurable !== undefined && rawDurable !== null;
+    let fromMode = null;
+    if (hasMode) {
+        if (typeof rawMode !== "string" || !FUNCTION_MODES.includes(rawMode)) {
+            return {
+                ok: false,
+                error: `\`mode\` must be "request" or "task" (got ${describe(rawMode)}): a ` +
+                    "request function runs inside the call and returns its result; a " +
+                    "task function returns a run id and survives restarts",
+            };
+        }
+        fromMode = rawMode;
+    }
+    let fromDurable = null;
+    if (hasDurable) {
+        if (typeof rawDurable !== "boolean") {
+            return {
+                ok: false,
+                error: `\`durable\` must be true or false (got ${describe(rawDurable)}); it is ` +
+                    'the accepted alias for `mode = "task"` / `mode = "request"`',
+            };
+        }
+        fromDurable = rawDurable ? "task" : "request";
+    }
+    if (fromMode && fromDurable && fromMode !== fromDurable) {
+        return {
+            ok: false,
+            error: `\`mode = "${fromMode}"\` and \`durable = ${String(rawDurable)}\` disagree: ` +
+                '`durable` is the accepted alias for `mode = "task"` (true) and ' +
+                '`mode = "request"` (false), so keep one key, or make the two agree',
+        };
+    }
+    const mode = fromMode ?? fromDurable ?? "request";
+    return { ok: true, mode, declared: hasMode || hasDurable };
+}
+/**
+ * The mode a stored config-version row runs in.
+ *
+ * The column is `durable`; a row written before #3281 carries only that, and a
+ * row written after it carries the same thing, so there is exactly one reading.
+ */
+export function configMode(row) {
+    return row?.durable === true ? "task" : "request";
+}
+/** Is this mode the durable one? The adjective, for the paths that branch on it. */
+export function isDurableMode(mode) {
+    return mode === "task";
+}
+function describe(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (value === null)
+        return "null";
+    if (typeof value === "object")
+        return Array.isArray(value) ? "an array" : "a table";
+    return String(value);
+}
+/**
+ * Why a webhook cannot drive a task function, and what to do instead (#3334).
+ *
+ * The first clause is verbatim what it has always been, so sibling pins on the
+ * request-mode prefix (#3281's) keep holding; everything after the dash is the
+ * half that was missing — an author who meets this at the push door could not
+ * previously tell whether it was a limitation or a design, nor what to write.
+ */
+export const WEBHOOK_ON_TASK_REFUSAL = "webhook triggers require request mode: set `mode = \"request\"` (or " +
+    "remove `mode = \"task\"`) — a webhook delivery needs its answer inside the " +
+    "request, and a task run has none to give there: verify and acknowledge in " +
+    "the request function, then hand the work to a task function with " +
+    "ctx.functions.start — or remove [function.triggers.webhook]";
+export const EMPTY_TRIGGER_DECLARATION = {
+    webhook: null,
+    cron: [],
+    databases: [],
+};
+/**
+ * The most cron entries one function may declare.
+ *
+ * The per-app cap (50) is a resource ceiling; this is a per-OBJECT one, so a
+ * single function cannot take most of an app's budget by itself. Ten is the
+ * same order as the schedules a real function needs and leaves the app's
+ * remaining slots for the other 40+ objects the cap is sized for.
+ */
+export const MAX_CRON_TRIGGERS_PER_FUNCTION = 10;
+/**
+ * Cron entry names follow the STANDALONE `triggerKey` charset, minus its
+ * ability to hold a `:` — the standalone create already rejects `:`, which is
+ * exactly what makes `<functionKey>:<name>` a key no standalone row can ever
+ * collide with (the intent, "Key namespace?").
+ */
+const CRON_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+/**
+ * The most database types one function may watch (#3184, D-07).
+ *
+ * Per-OBJECT, like the cron cap above: a function watching more than a handful
+ * of types is describing a fan-in the platform cannot bound per write, and
+ * every extra type is another discovery read on somebody's write path.
+ */
+export const MAX_DATABASE_TRIGGERS_PER_FUNCTION = 5;
+/**
+ * A database type key, matching the charset the grant grammar already uses for
+ * the same value (`src/config-surface/function-grants.ts`). One rule for one
+ * concept: `database:<type>/<model>:read` and `[[function.triggers.database]]`
+ * name the same thing.
+ */
+const DATABASE_TYPE_PATTERN = /^[A-Za-z0-9_-]+$/;
+const DATABASE_KEYS = new Set(["type"]);
+const WEBHOOK_KEYS = new Set([
+    "verificationScheme",
+    "signingSecret",
+    "toleranceSeconds",
+    "deduplicationEnabled",
+    "deduplicationWindowMs",
+    "maxBodyBytes",
+    "secretGracePeriodMs",
+    "verification",
+]);
+const CRON_KEYS = new Set([
+    "name",
+    "cron",
+    "timezone",
+    "overlapPolicy",
+    "rootInput",
+]);
+const VALID_OVERLAP_POLICIES = ["skip", "allow"];
+export class TriggerDeclarationError extends Error {
+}
+/** Is anything at all declared? Used to skip work on the common case. */
+export function hasDeclaredTriggers(declaration) {
+    return (declaration.webhook !== null ||
+        declaration.cron.length > 0 ||
+        declaration.databases.length > 0);
+}
+/**
+ * Normalize the `triggers` table of an already-parsed `[function]` table.
+ * Throws `TriggerDeclarationError` naming the rule that was broken.
+ *
+ * Split out from the parse (`deriveTriggerDeclaration`, which owns the bytes)
+ * so the CLI's preflight can check the document it has already read, and so the
+ * push boundary can normalize a declaration it read from a stored row without
+ * re-parsing bytes.
+ */
+export function normalizeTriggerDeclaration(functionTable, options = {}) {
+    const triggers = functionTable?.triggers;
+    if (triggers === undefined || triggers === null) {
+        return EMPTY_TRIGGER_DECLARATION;
+    }
+    if (typeof triggers !== "object" || Array.isArray(triggers)) {
+        throw new TriggerDeclarationError("[function.triggers] must be a table declaring `webhook` and/or `cron`");
+    }
+    for (const key of Object.keys(triggers)) {
+        if (key !== "webhook" && key !== "cron" && key !== "database") {
+            throw new TriggerDeclarationError(`unknown trigger kind '${key}' under [function.triggers]: the kinds are ` +
+                "`webhook`, `cron` and `database`");
+        }
+    }
+    const webhook = normalizeWebhook(triggers.webhook, options);
+    const cron = normalizeCron(triggers.cron, options);
+    const databases = normalizeDatabases(triggers.database, options);
+    return { webhook, cron, databases };
+}
+/**
+ * `[[function.triggers.database]]` — one accepted key, `type` (#3184, D-07).
+ *
+ * Sync mode only, permanently: a database-change fire runs INSIDE the write
+ * request, best-effort, with no run row (the intent, "Sync functions write a
+ * run row?"), and there is no durable shape for that. This is the same
+ * permanent refusal `webhook` carries, not the release-scoped one `cron` does.
+ */
+function normalizeDatabases(raw, options) {
+    if (raw === undefined || raw === null)
+        return [];
+    const entries = Array.isArray(raw) ? raw : [raw];
+    if (entries.length === 0)
+        return [];
+    if (options.mode === "task") {
+        throw new TriggerDeclarationError("database triggers require request mode: set `mode = \"request\"` (or " +
+            "remove `mode = \"task\"`), or remove the [[function.triggers.database]] " +
+            "entries");
+    }
+    if (entries.length > MAX_DATABASE_TRIGGERS_PER_FUNCTION) {
+        throw new TriggerDeclarationError(`a function may watch at most ${MAX_DATABASE_TRIGGERS_PER_FUNCTION} database ` +
+            `types, and this one declares ${entries.length}`);
+    }
+    const seen = new Set();
+    const normalized = [];
+    for (const entry of entries) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new TriggerDeclarationError("each [[function.triggers.database]] entry must be a table");
+        }
+        const table = entry;
+        for (const key of Object.keys(table)) {
+            if (!DATABASE_KEYS.has(key)) {
+                throw new TriggerDeclarationError(`unknown key '${key}' in a [[function.triggers.database]] entry: the ` +
+                    `only accepted key is ${[...DATABASE_KEYS].join(", ")}`);
+            }
+        }
+        const type = String(table.type ?? "").trim();
+        if (!type) {
+            throw new TriggerDeclarationError("each [[function.triggers.database]] entry needs a `type`: it names the " +
+                "database type whose writes fire the function");
+        }
+        if (!DATABASE_TYPE_PATTERN.test(type)) {
+            throw new TriggerDeclarationError(`database trigger type '${type}' must contain only letters, digits, ` +
+                "'-' or '_'");
+        }
+        if (seen.has(type)) {
+            throw new TriggerDeclarationError(`duplicate database trigger type '${type}': a function fires once per ` +
+                "write request, so each type is declared once");
+        }
+        seen.add(type);
+        normalized.push({ type });
+    }
+    // Sorted, like the cron entries: two files that differ only in the order
+    // they list their blocks describe the same triggers.
+    normalized.sort((a, b) => a.type.localeCompare(b.type));
+    return normalized;
+}
+function normalizeWebhook(raw, options) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (Array.isArray(raw)) {
+        // `[[function.triggers.webhook]]` — the shape that would declare two.
+        throw new TriggerDeclarationError("[function.triggers.webhook] is a single table: one webhook trigger per " +
+            "function (the intent, \"Webhook trigger URL and scheme?\")");
+    }
+    if (typeof raw !== "object") {
+        throw new TriggerDeclarationError("[function.triggers.webhook] must be a table");
+    }
+    const table = raw;
+    for (const key of Object.keys(table)) {
+        if (!WEBHOOK_KEYS.has(key)) {
+            throw new TriggerDeclarationError(`unknown key '${key}' under [function.triggers.webhook]: accepted keys ` +
+                `are ${[...WEBHOOK_KEYS].join(", ")}`);
+        }
+    }
+    // The intent forbids this permanently: a webhook fires the function inside
+    // the receiver, and the provider is holding the connection open waiting for
+    // its answer. A task run has no answer to give inside that request — it
+    // returns a run id and finishes later — so the refusal says so and names
+    // the pattern that does the same job (#3334).
+    if (options.mode === "task") {
+        throw new TriggerDeclarationError(WEBHOOK_ON_TASK_REFUSAL);
+    }
+    const scheme = String(table.verificationScheme ?? "").trim();
+    if (!scheme) {
+        throw new TriggerDeclarationError("[function.triggers.webhook] verificationScheme is required");
+    }
+    if (scheme === "none") {
+        throw new TriggerDeclarationError("verification scheme 'none' is not allowed for function triggers: an " +
+            "unauthenticated caller could run the function");
+    }
+    const declaration = { verificationScheme: scheme };
+    if (table.signingSecret !== undefined) {
+        declaration.signingSecret = String(table.signingSecret);
+    }
+    for (const key of [
+        "toleranceSeconds",
+        "deduplicationWindowMs",
+        "maxBodyBytes",
+        "secretGracePeriodMs",
+    ]) {
+        if (table[key] === undefined)
+            continue;
+        const value = Number(table[key]);
+        if (!Number.isFinite(value)) {
+            throw new TriggerDeclarationError(`[function.triggers.webhook] ${key} must be a number`);
+        }
+        declaration[key] = value;
+    }
+    if (table.deduplicationEnabled !== undefined) {
+        if (typeof table.deduplicationEnabled !== "boolean") {
+            throw new TriggerDeclarationError("[function.triggers.webhook] deduplicationEnabled must be a boolean");
+        }
+        declaration.deduplicationEnabled = table.deduplicationEnabled;
+    }
+    if (table.verification !== undefined) {
+        const verification = table.verification;
+        if (verification === null ||
+            typeof verification !== "object" ||
+            Array.isArray(verification)) {
+            throw new TriggerDeclarationError("[function.triggers.webhook.verification] must be a table");
+        }
+        declaration.verification = jsonSafe(verification);
+    }
+    return declaration;
+}
+function normalizeCron(raw, options) {
+    if (raw === undefined || raw === null)
+        return [];
+    const entries = Array.isArray(raw) ? raw : [raw];
+    if (entries.length === 0)
+        return [];
+    // No mode check: a cron entry is legal in EITHER mode (#3334). The intent
+    // allows it ("Sync functions write a run row?": *HTTP and cron allow both*),
+    // and the cron DO starts a durable run for a task target. #3181's refusal
+    // here was release-scoped, written before task starts existed, and its own
+    // comment asked for exactly this one-line removal.
+    if (entries.length > MAX_CRON_TRIGGERS_PER_FUNCTION) {
+        throw new TriggerDeclarationError(`a function may declare at most ${MAX_CRON_TRIGGERS_PER_FUNCTION} cron ` +
+            `trigger entries, and this one declares ${entries.length}`);
+    }
+    const seen = new Set();
+    const normalized = [];
+    for (const entry of entries) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new TriggerDeclarationError("each [[function.triggers.cron]] entry must be a table");
+        }
+        const table = entry;
+        for (const key of Object.keys(table)) {
+            if (!CRON_KEYS.has(key)) {
+                throw new TriggerDeclarationError(`unknown key '${key}' in a [[function.triggers.cron]] entry: accepted ` +
+                    `keys are ${[...CRON_KEYS].join(", ")}`);
+            }
+        }
+        const name = String(table.name ?? "").trim();
+        if (!name) {
+            throw new TriggerDeclarationError("each [[function.triggers.cron]] entry needs a `name`: it is required " +
+                "because it is half of the trigger's key, `<functionKey>:<name>`");
+        }
+        if (!CRON_NAME_PATTERN.test(name)) {
+            throw new TriggerDeclarationError(`cron trigger name '${name}' must start with a letter or digit and ` +
+                "contain only letters, digits, '-' or '_'");
+        }
+        if (seen.has(name)) {
+            throw new TriggerDeclarationError(`duplicate cron trigger name '${name}': names are the trigger's key ` +
+                "within the function, so each must appear once");
+        }
+        seen.add(name);
+        const cron = String(table.cron ?? "").trim();
+        if (!cron) {
+            throw new TriggerDeclarationError(`cron trigger '${name}' needs a \`cron\` expression`);
+        }
+        const declaration = { name, cron };
+        if (table.timezone !== undefined) {
+            declaration.timezone = String(table.timezone);
+        }
+        if (table.overlapPolicy !== undefined) {
+            const policy = String(table.overlapPolicy);
+            if (!VALID_OVERLAP_POLICIES.includes(policy)) {
+                throw new TriggerDeclarationError(`cron trigger '${name}': overlapPolicy must be one of ` +
+                    VALID_OVERLAP_POLICIES.join(", "));
+            }
+            declaration.overlapPolicy = policy;
+        }
+        if (table.rootInput !== undefined) {
+            declaration.rootInput = jsonSafe(table.rootInput);
+        }
+        normalized.push(declaration);
+    }
+    // Sorted by name so the stored declaration is canonical: two files that
+    // differ only in the order they list their entries describe the same
+    // triggers and must produce the same JSON.
+    normalized.sort((a, b) => a.name.localeCompare(b.name));
+    return normalized;
+}
+/**
+ * TOML values that JSON cannot carry (dates, and the bigints `smol-toml`
+ * produces for large integers) become their string / number form, so the
+ * stored declaration round-trips through `JSON.stringify` unchanged.
+ */
+function jsonSafe(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "bigint")
+        return Number(value);
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(jsonSafe);
+    if (typeof value === "object") {
+        // A smol-toml date-like carries a `toISOString`; anything else that is not
+        // a plain object is stringified rather than silently emitted as `{}`.
+        const anyValue = value;
+        if (typeof anyValue.toISOString === "function") {
+            return String(anyValue.toISOString());
+        }
+        const out = {};
+        for (const [key, child] of Object.entries(anyValue)) {
+            out[key] = jsonSafe(child);
+        }
+        return out;
+    }
+    return value;
+}
+/** The stored JSON for `ServerFunctionConfig.triggers`, or null when empty. */
+export function serializeTriggerDeclaration(declaration) {
+    if (!hasDeclaredTriggers(declaration))
+        return null;
+    return JSON.stringify(declaration);
+}
+/** Read a stored `ServerFunctionConfig.triggers` value back. */
+export function parseStoredTriggerDeclaration(stored) {
+    if (typeof stored !== "string" || !stored.trim()) {
+        return EMPTY_TRIGGER_DECLARATION;
+    }
+    try {
+        const parsed = JSON.parse(stored);
+        return {
+            webhook: parsed?.webhook ?? null,
+            cron: Array.isArray(parsed?.cron) ? parsed.cron : [],
+            // Absent in every row written before #3184, which is exactly what an
+            // empty list means: that version watches no database type.
+            databases: Array.isArray(parsed?.databases) ? parsed.databases : [],
+        };
+    }
+    catch {
+        return EMPTY_TRIGGER_DECLARATION;
+    }
+}
+/** The `CronTrigger.triggerKey` an entry owns. */
+export function cronTriggerKeyFor(functionKey, name) {
+    return `${functionKey}:${name}`;
+}
+/** The entry name a `<functionKey>:<name>` trigger key carries. */
+export function cronTriggerNameFrom(functionKey, triggerKey) {
+    const prefix = `${functionKey}:`;
+    return triggerKey.startsWith(prefix)
+        ? triggerKey.slice(prefix.length)
+        : triggerKey;
+}
+// ── src/config-surface/secret-reference.ts ───────────────────────────────
+/**
+ * The `{{secrets.KEY}}` reference SHAPE, decided from the value alone.
+ *
+ * Split out of `src/services/secret-templates.ts` by #3320 so the one rule that
+ * says whether a stored value IS a whole secret reference has one
+ * implementation on both sides of a `config push`. The CLI preflight refuses a
+ * webhook trigger whose `signingSecret` is a literal before anything is applied,
+ * and the server refuses the same value at the write boundary, because both run
+ * this code — the CLI through the artifact `cli/scripts/gen-config-surfaces.mjs`
+ * renders, the server by importing this module. A shape-only restatement in the
+ * CLI would have been subtly different: a reference spoiled by an invisible
+ * character (#2297) survives `String.trim()` and would have passed a preflight
+ * the server then failed.
+ *
+ * Pure by construction, which is what lets it live here: no secret store is
+ * consulted, because whether a value is a REFERENCE never depends on which keys
+ * exist. Whether the referenced key exists is the server's question, and stays
+ * in `secret-templates.ts` beside the rest of resolution.
+ *
+ * `secret-templates.ts` re-exports everything here, so every existing caller
+ * keeps its import and the two can never be different functions.
+ */
+// Matches {{secrets.KEY}}. Kept as a named export for existing callers;
+// `secret-templates.ts`'s generic resolver compiles the same pattern per
+// namespace.
+export const SECRETS_TEMPLATE_RE = /\{\{\s*secrets\.([A-Z][A-Z0-9_]{0,63})\s*\}\}/g;
+/** True when the value carries at least one `{{secrets.KEY}}` reference. */
+export function isSecretTemplate(value) {
+    if (typeof value !== "string")
+        return false;
+    SECRETS_TEMPLATE_RE.lastIndex = 0;
+    return SECRETS_TEMPLATE_RE.test(value);
+}
+/**
+ * The value with every well-formed `{{secrets.KEY}}` reference removed — the
+ * text that was NOT part of a reference the grammar accepts.
+ *
+ * This is the string the leftover-syntax rule below has to judge, and it is
+ * always derived from the ORIGINAL stored value, never from a substituted
+ * result. Resolution is a single `String.replace` pass that never re-scans
+ * replacement text (`resolveMultiNamespaceTemplate`), so a brace or a
+ * `secrets.` token coming out of a SECRET'S VALUE is inert — it is credential
+ * material the operator stored, not config text, and testing the substituted
+ * output would reject it (a Stripe key suffix stored as `}v2{` in an otherwise
+ * valid `sk_live_{{secrets.SUFFIX}}` value).
+ */
+export function withoutSecretReferences(value) {
+    SECRETS_TEMPLATE_RE.lastIndex = 0;
+    return value.replace(SECRETS_TEMPLATE_RE, "");
+}
+/**
+ * Ordinary whitespace: the padding a stored reference is allowed to carry
+ * beside it (#2191). Written as `\s` MINUS U+FEFF — `[^\S\uFEFF]` reads as
+ * "matches `\s` and is not U+FEFF".
+ *
+ * Derived from `\s` on purpose, because `isWholeSecretReference` decides with
+ * `String.trim()` and the two definitions have to be the same set or a
+ * character falls through the seam between them. That is not hypothetical: an
+ * earlier revision of this rule used Unicode's `White_Space` property, whose
+ * symmetric difference from `\s` is two codepoints, one in each direction —
+ * U+FEFF is `\s` but not `White_Space`, and U+0085 NEXT LINE is `White_Space`
+ * but not `\s`. U+0085 was therefore padding here and stray text to `trim()`,
+ * so `<U+0085>{{secrets.KEY}}` was neither spoiled nor a whole reference and
+ * resolved as a mixed legacy literal to U+0085 followed by the secret — an HMAC
+ * key one byte wrong, reported to the operator as `legacy-literal` ("this still
+ * works"). Deriving the set from `\s` closes that by construction rather than
+ * by listing one more character.
+ *
+ * The single deliberate exclusion is U+FEFF: ECMAScript counts the byte-order
+ * mark as whitespace — `String.trim()` and `\s` both absorb it — where Unicode
+ * does not. That accident is what used to let a BOM-spoiled reference resolve
+ * silently while its zero-width siblings failed, and #2297 settles it the other
+ * way: a BOM is stray text beside the reference, not padding. Excluding it here
+ * is what makes it spoil the reference, and `isWholeSecretReference` rejects
+ * such a value before its own `trim()` can absorb it.
+ */
+const ORDINARY_WHITESPACE_RE = /[^\S\uFEFF]/g;
+/**
+ * A character we can affirmatively recognize as credential material: printable
+ * ASCII, space excluded.
+ *
+ * Stated as an ALLOWLIST, for the reason `containsReferenceSyntax` gives at
+ * length: a denylist cannot close a class. The tempting denylist here is
+ * "characters that render as nothing", and no Unicode category names it —
+ * general category Cf holds U+200B/U+200C/U+200D/U+2060/U+FEFF but not U+2800
+ * BRAILLE PATTERN BLANK (So), U+FE0F or U+034F (Mn), or U+3164 / U+FFA0, the
+ * Hangul fillers (Lo). An allowlist has no such gap: every character nobody
+ * thought of lands on the fail-closed side by construction.
+ *
+ * Every credential shape this boundary carries is built from printable ASCII —
+ * base64 and base64url, hex, `whsec_…`, `sk_live_…`, `GOCSPX-…`. The cost of
+ * the allowlist is the case on the other side of that: a genuine mixed legacy
+ * value whose literal part is entirely non-ASCII would fail closed instead of
+ * resolving. That is the asymmetry `containsReferenceSyntax` already accepts —
+ * one clear, remediable failure on a row that has to be migrated anyway,
+ * against a credential silently keyed one byte wrong.
+ */
+const CREDENTIAL_CHARACTER_RE = /[\x21-\x7E]/;
+/**
+ * True when the value holds a well-formed `{{secrets.KEY}}` reference and the
+ * text beside it is not credential material — a reference SPOILED by an
+ * invisible character, rather than a legacy literal that happens to contain one
+ * (#2297, consolidating #2386).
+ *
+ * Such a value is a reference spoiled by an authoring mistake — pasted out of
+ * an editor or a document that carried a zero-width character along with it —
+ * and it must fail closed rather than resolve. Before this rule a value spelled
+ * `<U+200B>{{secrets.KEY}}` was not a whole reference (neither `\s` nor
+ * `String.trim()` matches U+200B), carried no leftover reference SYNTAX once
+ * the template was removed, and so classified as a working legacy literal that
+ * resolved to U+200B followed by the secret: an HMAC key silently one byte
+ * wrong, and a read surface pointing the operator at the wrong remediation.
+ *
+ * The rule judges the REMAINDER — the value with its well-formed references
+ * taken out — against an allowlist, which is what makes the class closed:
+ *
+ * - Remainder empty, or ordinary whitespace only: the value is the reference it
+ *   plainly is, padding and all, and keeps resolving (#2191).
+ * - Remainder carries at least one credential character: a genuine mixed
+ *   literal-plus-reference value (`sk_live_{{secrets.SUFFIX}}`), which predates
+ *   reference-only and keeps resolving as shipped (#2332) — including when the
+ *   operator's own bytes contain an invisible character, because that is
+ *   credential material rather than a spoiled pointer.
+ * - Anything else: text that is present but that we cannot recognize as
+ *   credential material. Fail closed.
+ *
+ * Failing closed rather than stripping the character is the deliberate choice
+ * (sponsor decision on #2297): stripping hides the mistake, where a
+ * `malformed-reference` names it at the moment the value is written.
+ *
+ * A value with NO well-formed reference is not this rule's business, and needs
+ * no separate handling: a pure literal is credential material the platform has
+ * no standing to judge (`whsec_<U+200B>raw`), and a MISTYPED reference —
+ * including one spoiled inside the braces, `{{secrets.<U+200B>KEY}}` — leaves
+ * its syntax in the remainder and is already caught by
+ * `carriesMalformedReferenceSyntax` in `secret-templates.ts`.
+ *
+ * Scoped to the reference-only credential boundary, not to
+ * `resolveSecretTemplate`: an integration proxy header is a template by design
+ * (`Authorization: Bearer {{secrets.TOKEN}}`), so it keeps resolving exactly
+ * what the operator wrote.
+ */
+export function isSpoiledSecretReference(value) {
+    if (typeof value !== "string")
+        return false;
+    if (!isSecretTemplate(value))
+        return false;
+    // `String.replace` with a global regex always scans from 0 and resets
+    // `lastIndex`, so the shared pattern carries no state between calls.
+    const remainder = withoutSecretReferences(value).replace(ORDINARY_WHITESPACE_RE, "");
+    if (remainder.length === 0)
+        return false;
+    return !CREDENTIAL_CHARACTER_RE.test(remainder);
+}
+/**
+ * Matches a value that is EXACTLY one `{{secrets.KEY}}` reference and nothing
+ * else. Anchored, and deliberately not global — `SECRETS_TEMPLATE_RE` carries
+ * `lastIndex` state between calls.
+ */
+export const WHOLE_SECRET_REFERENCE_RE = /^\{\{\s*secrets\.([A-Z][A-Z0-9_]{0,63})\s*\}\}$/;
+/**
+ * True when the whole (trimmed) value is a single `{{secrets.KEY}}` reference.
+ *
+ * The stricter sibling of `isSecretTemplate`, for the callers that use "is a
+ * reference" to mean "carries no secret material of its own". `isSecretTemplate`
+ * is a *contains* test, so `"sk_live_abcd{{secrets.SUFFIX}}"` satisfies it —
+ * which is fine where a value is a template to be resolved (an
+ * `Authorization: Bearer {{secrets.TOKEN}}` header is exactly that), and wrong
+ * where the value is a credential that must live entirely in the encrypted
+ * secret store. Used by the webhook `config` credential rule and by the
+ * redaction that backs it: a mixed value would otherwise pass the write rule
+ * AND skip redaction, storing and echoing most of a working credential in
+ * cleartext.
+ *
+ * Trimmed, so `" {{secrets.KEY}} "` is accepted as the reference it plainly is;
+ * two references, or a reference with any literal text beside it, are not.
+ *
+ * Invisible text beside the reference disqualifies the value before the trim
+ * (#2297): U+FEFF is stripped by `String.trim()` and matched by `\s`, so
+ * without the check a byte-order mark beside the braces would be silently
+ * accepted while its zero-width siblings were not. Rejecting here is what makes
+ * the write gates built on this predicate (`validateWholeSecretReference`, the
+ * webhook `config` credential rule) refuse such a value at configuration time
+ * rather than storing a row that can only fail at use time.
+ */
+export function isWholeSecretReference(value) {
+    if (typeof value !== "string")
+        return false;
+    if (isSpoiledSecretReference(value))
+        return false;
+    return WHOLE_SECRET_REFERENCE_RE.test(value.trim());
+}
+// ── src/config-surface/webhook-signing-secret.ts ─────────────────────────
+/**
+ * The `signingSecret` rule a webhook's verification scheme carries, decided
+ * from the declaration alone (#3320).
+ *
+ * `signingSecret` is reference-only (#2254): a whole `{{secrets.KEY}}`
+ * reference naming an app secret, and nothing else. Which schemes need one,
+ * whether one was supplied, and whether the supplied value is a reference are
+ * all answerable from the file — so they belong in the `config push` preflight,
+ * which aborts before anything is applied, rather than in the apply loop where
+ * a refusal lands after sibling entities are already written.
+ *
+ * That is the whole reason this module exists here rather than beside the rest
+ * of the webhook write pipeline: `src/config-surface/` is vendored verbatim
+ * into `cli/src/lib/generated-config-surfaces.ts`, so the CLI runs the server's
+ * rule instead of a restatement of it, and a change that is not regenerated
+ * fails `gen-config-surfaces.mjs --check`.
+ *
+ * ── What is deliberately NOT here ─────────────────────────────────────────
+ *
+ * Everything that needs the app's state: whether the referenced secret exists,
+ * whether the scheme's `config` is valid under this environment's JWKS policy,
+ * the per-app row cap, a key a standalone webhook already holds. Those stay in
+ * `src/app-api/services/webhook-settings-validation.ts`, which has `Env`. A
+ * local copy of them would be a preflight that gives a false all-clear — and
+ * the residue is then app-state-dependent by construction rather than by
+ * accident of where a rule happened to live.
+ */
+/**
+ * Schemes that don't carry an HMAC `signingSecret`. These either store no key
+ * material at all (`none`) or store it under `AppWebhook.config` instead:
+ * `discord` puts the application public key in `config.publicKey`, `jwt` puts
+ * a JWKS in `config.jwt.jwks`, and `plaid` fetches keys from Plaid using the
+ * API credentials referenced in `config.plaid`.
+ */
+export const SCHEMES_WITHOUT_SIGNING_SECRET = [
+    "none",
+    "discord",
+    "jwt",
+    "plaid",
+];
+export function requiresSigningSecret(scheme) {
+    return (typeof scheme === "string" &&
+        !SCHEMES_WITHOUT_SIGNING_SECRET.includes(scheme));
+}
+/** The coded refusals, so a client can branch without matching prose. */
+export const SIGNING_SECRET_MUST_BE_SECRET_REF = "SIGNING_SECRET_MUST_BE_SECRET_REF";
+export const SIGNING_SECRET_NOT_SUPPORTED_FOR_SCHEME = "SIGNING_SECRET_NOT_SUPPORTED_FOR_SCHEME";
+/** The reference-only message, shared by every field that carries one. */
+export function wholeSecretReferenceMessage(label) {
+    return (`${label} must be a whole {{secrets.KEY}} reference to an app secret, not ` +
+        "a literal value — secrets live only in the encrypted secret store. Store " +
+        `the value (with \`primitive secrets set KEY --value <value>\` or the ` +
+        `secrets API) and set ${label} to \`{{secrets.KEY}}\`.`);
+}
+/**
+ * Is this value a whole `{{secrets.KEY}}` reference? Returns the refusal a
+ * caller renders, or null.
+ *
+ * `isWholeSecretReference`, never `isSecretTemplate`: a *contains* test admits
+ * `sk_live_abcd{{secrets.SUFFIX}}`, which stores most of a working credential
+ * in cleartext.
+ */
+export function validateWholeSecretReference(label, value, code) {
+    if (typeof value === "string" && isWholeSecretReference(value))
+        return null;
+    return { message: wholeSecretReferenceMessage(label), code };
+}
+/**
+ * The whole file-decidable `signingSecret` rule, in the order the standalone
+ * webhook create ran it: a required secret must be present, a present one must
+ * be a whole reference, and a scheme that carries no secret must not be given
+ * one.
+ *
+ * Returns null when the declaration is acceptable — which does NOT mean the
+ * write will succeed: the referenced key still has to exist, and that is the
+ * server's question.
+ */
+export function validateSigningSecretDeclaration(input) {
+    const scheme = input.verificationScheme;
+    if (requiresSigningSecret(scheme)) {
+        if (!input.signingSecret) {
+            return {
+                message: `signingSecret is required for verification scheme '${scheme}'`,
+                plain: true,
+            };
+        }
+        return validateWholeSecretReference("signingSecret", input.signingSecret, SIGNING_SECRET_MUST_BE_SECRET_REF);
+    }
+    if (input.signingSecret !== undefined &&
+        input.signingSecret !== null &&
+        input.signingSecret !== "") {
+        return {
+            message: `signingSecret is not supported for verification scheme '${scheme}' — ` +
+                "its key material comes from the scheme's config.",
+            code: SIGNING_SECRET_NOT_SUPPORTED_FOR_SCHEME,
+        };
+    }
+    return null;
+}
 // ── src/config-surface/workflow.ts ───────────────────────────────────────
 /**
  * The `workflow` configuration object's definition (issue #2644, phase 1).
@@ -2331,6 +3144,10 @@ export const INTEGRATION_SURFACE = {
  */
 const WEBHOOK_HANDLER = "src/admin-api.ts";
 const WEBHOOK_CONFIG_VALIDATION = "src/app-api/services/webhook-verification/config-validation.ts";
+// #3320 — the reference-only `signingSecret` rule is decidable from the value
+// alone, so it moved beside the definitions where `config push`'s preflight can
+// run the server's own copy of it.
+const WEBHOOK_SIGNING_SECRET_RULE = "src/config-surface/webhook-signing-secret.ts";
 export const WEBHOOK_SURFACE = {
     label: "webhook",
     tables: [
@@ -2424,7 +3241,7 @@ export const WEBHOOK_SURFACE = {
                     type: "string",
                     emit: "whenSet",
                     writableOn: BOTH,
-                    validation: handledBy(WEBHOOK_CONFIG_VALIDATION, "validateWholeSecretReference"),
+                    validation: handledBy(WEBHOOK_SIGNING_SECRET_RULE, "validateWholeSecretReference"),
                 },
             ],
             notExposed: {
@@ -3794,7 +4611,7 @@ export const TRANSFORM_SURFACE = {
  * config version (`ServerFunctionConfig`), but it is ONE table in the file: an
  * author does not write a version, they write a function and push it. The
  * definition therefore declares the header's field surface and lists the
- * version-carried keys (`entry`, `durable`, `limits`) in `tomlOnlyKeys` beside
+ * version-carried keys (`entry`, `mode`, `limits`) in `tomlOnlyKeys` beside
  * `key` — they are authored, they are not fields of the header model, and they
  * travel on the config-version route rather than in the header body. Declaring
  * a second table over `ServerFunctionConfig` at the same `tomlPath` is not
@@ -3947,11 +4764,23 @@ export const SERVER_FUNCTION_SURFACE = {
                         "it travels on the config-version push together with the built " +
                         "bundle and the authored sources.",
                 },
+                mode: {
+                    kind: "structural",
+                    note: '`mode = "request" | "task"` (#3281): a request function runs ' +
+                        "inside the call and returns its result; a task function returns " +
+                        "a run id and survives restarts (#3186). Stored on the config " +
+                        "version (as its `durable` column) and pushed with it, so it is " +
+                        "versioned with the code it describes rather than mutable on the " +
+                        "header. Absent means request.",
+                },
                 durable: {
                     kind: "structural",
-                    note: "Whether this version runs durably (#3186). Stored on the config " +
-                        "version and pushed with it, so it is versioned with the code it " +
-                        "describes rather than mutable on the header.",
+                    note: 'The accepted ALIAS of `mode` through the transition (#3281): ' +
+                        '`durable = true` is `mode = "task"` and `durable = false` is ' +
+                        '`mode = "request"`. When both keys are present they must agree, ' +
+                        "or the file is refused naming both. Kept as the adjective for the " +
+                        "property; `config pull` writes the authored bytes back unchanged, " +
+                        "so a file that says it keeps saying it until its author edits it.",
                 },
                 limits: {
                     kind: "structural",