primitive-admin 1.1.0-alpha.8 → 1.1.0-alpha.80

package/dist/src/lib/generated-config-surfaces.d.ts

@@ -0,0 +1,1445 @@
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Vendored from the canonical server modules under `src/config-surface/` — the
+ * ONE definition per configuration object (issue #2644). The server's
+ * create/update handlers and this copy read the same field surface, so the CLI's
+ * push payloads, pull serializers and TOML key validation cannot drift from what
+ * the server accepts.
+ *
+ * Regenerate with:
+ *   node cli/scripts/gen-config-surfaces.mjs   (runs automatically at CLI prebuild)
+ *
+ * A freshness guard (`gen-config-surfaces.mjs --check`, asserted by
+ * `cli/tests/unit/config-surface-drift-guard.test.ts`) fails if this committed
+ * copy does not match the source.
+ */
+/**
+ * The one definition per configuration object (issue #2644).
+ *
+ * A "configuration object" is anything `primitive config` round-trips as
+ * config-as-code: workflows, prompts, integrations, webhooks, cron triggers,
+ * blob buckets, database types, rule sets, email templates, and the type
+ * configs. Every one of them used to write its field surface out by hand in at
+ * least three places — the server's create/update handler, the CLI's push
+ * payload builder, and the CLI's pull serializer — so adding a field to one and
+ * not the others failed silently: the field was simply absent, `config diff` could
+ * not see it, and a pull → push cycle cleared it server-side (#571, #807, #1081,
+ * #1172, #1177, #1972, #2635).
+ *
+ * These types describe that surface ONCE. The definitions live here on the
+ * server; the CLI vendors them at build time into
+ * `cli/src/lib/generated-config-surfaces.ts`
+ * (`cli/scripts/gen-config-surfaces.mjs`), the same server→CLI vendoring
+ * `gen-operation-def-descriptor.mjs` (#1544) already uses, so the published CLI
+ * still imports no server code at runtime.
+ *
+ * ── Scope: declarative classification and coverage ONLY ──────────────────
+ * Decision of record (#1976, 2026-07-23, carried forward at #2644's design
+ * gate): a definition records WHICH fields exist, whether each is part of the
+ * TOML surface, which modes the server accepts it in, and — for a field with
+ * real behavior — the NAME of the handler that owns that behavior. It never
+ * encodes the behavior itself, and no handler source is ever regex-scanned for
+ * field names. `pickWritableFields` replaces the key list, not the validation.
+ *
+ * ── Purity ───────────────────────────────────────────────────────────────
+ * Everything under `src/config-surface/` must stay importable by a build-time
+ * Node script with no Workers runtime: no `getAppModels`, no `withAppContext`,
+ * no `src/do-routing.ts`, no `env`. `cli/tests/unit/config-surface-drift-guard.test.ts`
+ * asserts the directory's import graph stays empty of those modules.
+ */
+/** Value shape of a field on the wire and in TOML. Descriptive, not a parser. */
+export type FieldType = "string" | "number" | "boolean" | "string[]" | "json";
+/**
+ * Why a persisted field is not part of the TOML surface. `note` is required —
+ * absence from a hand-written list is never a decision (#2644 criterion 4).
+ */
+export type NotExposed = {
+    kind: "server-owned";
+    note: string;
+} | {
+    kind: "structural";
+    note: string;
+    /**
+     * Which create/update modes carry this key IN THE REQUEST BODY — the same
+     * statement `ConfigField.writableOn` makes about a field, for a key that
+     * is not part of the TOML field surface.
+     *
+     * Omitted means both, the common case for a sub-tree the body always
+     * carries (`rules`, `metadataManifest`, `config`). `[]` says the key
+     * never travels in the body at all: it is in the URL path or comes from
+     * the file name, so no request schema admits it. Being structural is a
+     * statement about the TOML surface and does not by itself make a key
+     * writable — a mode whose handler never reads the key is not declared
+     * for it, or the schema would accept a key the handler drops, which is
+     * the silent 200 criterion 9 exists to end.
+     */
+    requestModes?: readonly ("create" | "update")[];
+} | {
+    kind: "secret";
+    note: string;
+} | {
+    kind: "deprecated";
+    note: string;
+};
+export interface ConfigField {
+    /** `models.yaml` field name === the wire key on create/update. */
+    field: string;
+    /** Key inside the TOML table (often identical to `field`). */
+    tomlKey: string;
+    type: FieldType;
+    /** "whenSet" omits the key on pull when the value is empty; see #1033's `emit`. */
+    emit: "always" | "whenSet";
+    /**
+     * Modes the SERVER accepts the field in — a statement about the handler's
+     * `hasOwnProperty` branches and nothing else. `["create"]` means update
+     * genuinely rejects/ignores it (e.g. an immutable key). It is NOT a place to
+     * record CLI call ordering: `syncCallable` is accepted on both create and
+     * update (`src/admin-api.ts` `createAppWorkflow` / `updateAppWorkflow`); the
+     * CLI's create-only send is a *sequencing* invariant owned by
+     * `applyWorkflowBody` (#807 — the deferred second PATCH is itself an update
+     * call, and would break if update rejected the field).
+     */
+    writableOn: readonly ("create" | "update")[];
+    /**
+     * Classification, not dispatch. "passthrough" = the accepted value is stored
+     * as-is. Otherwise the named handler owns validation, normalization and
+     * serialization for this field; the guard only asserts the export exists.
+     *
+     * A handler is named `"<repo-relative module path>#<exported name>"`, e.g.
+     * `"src/workflows/config/workflow-field-handlers.ts#normalizeWorkflowStatus"`.
+     * `cli/tests/unit/config-surface-drift-guard.test.ts` fails when the module or
+     * the export is missing (#2644 behavior 2b).
+     */
+    validation: "passthrough" | {
+        handler: string;
+    };
+    /**
+     * This field's declared type genuinely admits more than one TOML spelling
+     * (#2880 criterion 5).
+     *
+     * The declared type is the contract: a quoted number for a declared number
+     * is a validation error `config diff` and `config push` report identically,
+     * and neither coerces. A handful of fields are genuinely dual-encoded
+     * anyway — `temperature` and `topP` are `StringField`s the server stores as
+     * strings and returns parsed (#2869), so `"0.2"` and `0.2` describe one
+     * value — and for those the two spellings must compare EQUAL, or diff
+     * reports a `Modified` no push can clear.
+     *
+     * Recorded here rather than inferred from the type, so the carve-out is a
+     * decision with a reason attached instead of a rule that quietly widens to
+     * every number in the surface.
+     */
+    dualEncoded?: {
+        note: string;
+    };
+    /**
+     * The value the SERVER materializes when a create omits this key (#2880
+     * DSO-002).
+     *
+     * A hand-authored file that omits an optional field the server defaults —
+     * an integration's `timeoutMs`, a cron trigger's `timezone` — creates fine
+     * and then reads `Modified` forever: the server holds the default, the file
+     * holds nothing, and push's payload builder drops the absent key so the
+     * difference can never converge. Recording the default here lets the LOCAL
+     * side of the comparison apply the same value the server did.
+     *
+     * Only for a default the server assigns on CREATE and returns on read.
+     */
+    serverDefault?: string | number | boolean;
+}
+export interface ConfigTable {
+    /** TOML path, e.g. ["workflow"] for [workflow], ["configs"] for [[configs]]. */
+    tomlPath: readonly string[];
+    repeated: boolean;
+    /** The `models.yaml` model backing this table — the coverage anchor. */
+    model: string;
+    fields: readonly ConfigField[];
+    /** Every model field not in `fields`, with its reason. Coverage is exhaustive. */
+    notExposed: Readonly<Record<string, NotExposed>>;
+    /**
+     * TOML keys accepted inside this table that are NOT part of the write field
+     * surface — an author writes them, but some other machinery consumes them.
+     * Declared here so `config push`'s unrecognized-key rejection (#2644 criterion
+     * 6) does not reject a key the CLI itself emits, and so the reason is visible
+     * rather than implied.
+     */
+    tomlOnlyKeys: Readonly<Record<string, NotExposed>>;
+    /**
+     * Keys the create/update BODY carries that are not `models.yaml` fields at
+     * all — protocol keys such as the `expectedModifiedAt` optimistic-concurrency
+     * token. Declared here so phase 5's generated request schemas
+     * (`request-schema.ts`) accept them, with the reason visible rather than
+     * implied. Optional: most objects have none.
+     *
+     * `modes` records which handlers actually read the key, the same statement
+     * `ConfigField.writableOn` makes about a field. Omitted means both — the
+     * common case. A key the handler in this mode does not read is NOT declared
+     * for that mode: the schema would accept it and the handler would drop it,
+     * which is the silent 200 criterion 9 exists to end.
+     */
+    requestOnlyKeys?: Readonly<Record<string, {
+        note: string;
+        modes?: readonly ("create" | "update")[];
+    }>>;
+    /**
+     * Keys the server's GET response carries that are not `models.yaml` fields —
+     * derived flags and related payloads. Declared here so `config pull`'s
+     * unrecognized-key warning (#2644 criterion 6) reports genuinely unknown keys
+     * rather than every computed one.
+     */
+    responseOnlyKeys: Readonly<Record<string, NotExposed>>;
+}
+export interface ConfigObjectSurface {
+    /** Matches the CLI's `SyncResourceType.label` — e.g. "workflow", "prompt". */
+    label: string;
+    tables: readonly ConfigTable[];
+    /**
+     * Top-level TOML keys the object's FILE carries besides its field tables —
+     * the authored sub-trees that travel on their own channel (`[[steps]]`,
+     * `[requestConfig]`, `[rules]`, `[models.*]`) and the declared-access
+     * manifest's `[metadata]` / `secrets` / `vars` fragments.
+     *
+     * `tomlOnlyKeys` says which keys are accepted INSIDE a table; this says which
+     * keys are accepted at the document root. Together they make `config push`'s
+     * rejection total (design gate, 2026-08-12: push rejects everything
+     * unrecognized): without it a typo'd table header — `[integraton]` — parsed
+     * to a root key nothing checked, so the file pushed as though the real table
+     * were empty and the TOML-owned fields inside it were CLEARED server-side.
+     *
+     * Every entry carries its reason, the same rule `notExposed` follows: a table
+     * that is simply absent from this map must not read as a decision.
+     */
+    tomlDocumentKeys: Readonly<Record<string, NotExposed>>;
+    /**
+     * Declares that this object HAS no TOML field table, with the reason —
+     * required when `tables` is empty and forbidden otherwise.
+     *
+     * `transform` is the case: a `.rhai` file's authored surface is the script
+     * body, so there is no key/value table to define. Saying so here is the same
+     * rule `notExposed` applies to a field, one level up: "absent from the
+     * registry" and "deliberately fieldless" must not look the same (#2644
+     * criterion 4).
+     */
+    noFieldTable?: {
+        note: string;
+    };
+}
+/**
+ * Shared spellings used by every configuration-object definition (issue #2644).
+ *
+ * These live in one module for a mechanical reason as much as a stylistic one:
+ * `cli/scripts/gen-config-surfaces.mjs` concatenates the whole directory into a
+ * single vendored artifact, so a `const handler = …` declared per definition
+ * module would collide as a duplicate identifier the moment a second object was
+ * migrated.
+ *
+ * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity).
+ */
+/** Both write modes — the common case, spelled once. */
+export declare const BOTH: readonly ("create" | "update")[];
+/** Create only: an immutable key or a field the update handler ignores. */
+export declare const CREATE_ONLY: readonly ("create" | "update")[];
+/** Update only: a field the create handler assigns itself. */
+export declare const UPDATE_ONLY: readonly ("create" | "update")[];
+/**
+ * Name the handler that owns a field's validation, normalization and
+ * serialization, as `"<repo-relative module>#<export>"`. Classification only —
+ * the definition never dispatches through it (#1976 decision of record); the
+ * guard asserts the export exists so a renamed handler fails the CLI unit suite
+ * instead of leaving a dangling reference (#2644 behavior 2b).
+ */
+export declare function handledBy(modulePath: string, exportName: string): ConfigField["validation"];
+/**
+ * The declared-access manifest's top-level TOML keys (#1304, #1364).
+ *
+ * Five objects carry the same three-key fragment beside their field table —
+ * workflows, database types, and the group / collection / metadata-category
+ * configs — parsed by the one `parseDeclaredAccessManifestToml`. Spelling it
+ * once here keeps `config push`'s document-level rejection from disagreeing with
+ * itself object by object.
+ */
+export declare const DECLARED_ACCESS_MANIFEST_KEYS: Readonly<Record<string, NotExposed>>;
+/**
+ * The accepted-key half of a configuration object's definition (issue #2644).
+ *
+ * `pickWritableFields` answers exactly one question — "is this key writable on
+ * this object in this mode" — so a server handler stops naming the keys it
+ * accepts. What a present key MEANS stays with the per-field handler the
+ * definition names (spec §Contracts, decision of record #1976): the workflow
+ * `status` enum, the non-negative-integer coercion of the queue limits,
+ * `runAs`'s caller|system check, `parseWorkflowLock`, the `capabilities` array
+ * shape and the CEL parse of `accessRule` all stay where they are. The
+ * mechanical win is that a field can no longer be *absent* from the accepted
+ * set.
+ *
+ * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity).
+ */
+export type WriteMode = "create" | "update";
+/** The field names this table accepts on the wire in `mode`, in declaration order. */
+export declare function writableFieldNames(table: ConfigTable, mode: WriteMode): string[];
+/**
+ * The field names the server PERSISTS for this table in `mode`: the writable
+ * fields, plus the `deprecated` classifications — "still writable, superseded
+ * by another field" is what that kind means (`types.ts`), so a superseded key
+ * a handler still honors (`accessPolicy`, `passkeyRpId`) belongs in every
+ * accepted set, and a field that is NOT writable belongs in none of them.
+ *
+ * Stated once here because three consumers need the same answer: the generated
+ * request schemas, `PUT /settings`'s write allow-list, and the guards.
+ */
+export declare function acceptedWriteFieldNames(table: ConfigTable, mode: WriteMode): string[];
+/**
+ * Split a request body into the keys this table accepts in `mode` and the keys
+ * it does not.
+ *
+ * `accepted` preserves the caller's values verbatim — including an explicit
+ * `null` or `false`, which are meaningful (clear / opt-out) and must not be
+ * coalesced away. Only keys the body actually carries appear, so a handler can
+ * keep using presence (`hasOwnProperty`) to distinguish "leave unset" from
+ * "set to null".
+ *
+ * `rejected` is every other key the body carried. Today it is informational;
+ * #2644 phase 5 turns it into a 400 through the generated request schemas.
+ */
+export declare function pickWritableFields(body: Record<string, unknown>, table: ConfigTable, mode: WriteMode): {
+    accepted: Record<string, unknown>;
+    rejected: string[];
+};
+/**
+ * The PASSTHROUGH half of the accepted body: the keys this table declares
+ * `validation: "passthrough"`, writable in `mode`, that the body actually
+ * carries — with their values verbatim.
+ *
+ * This is what makes criterion 1 true rather than aspirational. A handler that
+ * only picked its accepted set still had to name each field again when it built
+ * the row to persist, so a scalar field added to a definition alone was
+ * accepted on the wire and then dropped on the floor. Handlers spread this into
+ * the create/update payload FIRST, so a field with real behavior still lands
+ * through its named handler (whose assignment comes after and wins), and a
+ * plain scalar needs no handler edit at all.
+ *
+ * Values are passed through untouched — including an explicit `null` or
+ * `false`, which are meaningful (clear / opt-out). "Stored as-is" is exactly
+ * what the `passthrough` classification promises.
+ */
+export declare function passthroughFields(body: Record<string, unknown>, table: ConfigTable, mode: WriteMode, options?: {
+    /**
+     * Fields whose PRESENCE semantics this handler owns — it decides, per
+     * value, whether the key is written at all (a falsy `displayName` that
+     * means "leave the stored name alone"). Listing one here keeps the generic
+     * copy from changing what it means.
+     *
+     * This is never a place to list a field the handler does not assign: a
+     * field named here and dropped by the handler is written nowhere, which is
+     * the silent loss the definition exists to prevent. A NEW field needs no
+     * entry — omission is what makes it flow through.
+     */
+    handledHere?: readonly string[];
+}): Record<string, unknown>;
+/** `true` when the body carries `field` and this table accepts it in `mode`. */
+export declare function hasWritableField(accepted: Record<string, unknown>, field: string): boolean;
+/**
+ * Coverage checks over a configuration object's definition (issue #2644,
+ * criteria 2 and 4).
+ *
+ * A definition claims to describe its model's WHOLE field surface. These
+ * functions are what make that claim mean something: every `models.yaml` field
+ * is either exposed in TOML or classified `notExposed` with a reason, in both
+ * directions — a new field nobody classified, and a classification for a field
+ * that no longer exists. `cli/tests/unit/config-surface-drift-guard.test.ts`
+ * asserts them over every registered object, so coverage follows from being a
+ * configuration object rather than from someone adding a per-type guard.
+ *
+ * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity).
+ */
+/**
+ * `models.yaml` field names per model — the coverage anchor, passed in rather
+ * than read here so this module stays pure (the CLI's vendored artifact carries
+ * it as `GENERATED_CONFIG_MODEL_FIELDS`).
+ */
+export type ModelFieldMap = Readonly<Record<string, readonly string[]>>;
+/**
+ * Whether a value counts as unset for an `emit: "whenSet"` field, so `config pull`
+ * omits the key instead of writing a noisy empty one (and `config diff` does not
+ * report a difference that is not there).
+ *
+ * Carried over verbatim from #1033's shipped app-settings descriptor
+ * (`cli/src/lib/app-settings-descriptor.ts`): an empty array and an empty
+ * object are unset, while `false` and `0` are meaningful values and never are.
+ */
+export declare function isEmptyForEmit(value: unknown, type: ConfigField["type"]): boolean;
+/**
+ * A field name whose shape says it carries a credential. Such a field must be
+ * classified explicitly — exposed with a stated reference-only contract, or
+ * `notExposed: { kind: "secret" }` — because a mechanical generalization that
+ * merely omits it would read as "not decided" (#2254, #2256).
+ */
+export declare const SECRETISH_FIELD: RegExp;
+/** Model fields the table neither exposes nor classifies. Non-empty is a failure. */
+export declare function findUnclassifiedFields(table: ConfigTable, modelFields: readonly string[]): string[];
+/**
+ * Classifications that no longer correspond to a model field — i.e. a field
+ * removed from `models.yaml` while the definition still names it. Also a
+ * failure: a stale classification must not silently pass, or the coverage claim
+ * quietly stops meaning anything.
+ */
+export declare function findStaleClassifications(table: ConfigTable, modelFields: readonly string[]): string[];
+/** The models this surface's tables project, in declaration order, deduped. */
+export declare function surfaceModels(surface: ConfigObjectSurface): string[];
+/**
+ * Model fields the whole surface neither exposes nor classifies. Non-empty is
+ * a failure: the CLI would silently ignore them and a pull → push cycle would
+ * clear them (#2644 criterion 2).
+ */
+export declare function findUnclassifiedSurfaceFields(surface: ConfigObjectSurface, modelFields: ModelFieldMap): string[];
+/**
+ * Classifications naming a field the model no longer has — the other direction,
+ * and equally a failure: a stale entry quietly stops meaning anything.
+ */
+export declare function findStaleSurfaceClassifications(surface: ConfigObjectSurface, modelFields: ModelFieldMap): string[];
+/** Fields the surface both exposes and classifies `notExposed`. Ambiguous. */
+export declare function findDoubleClassifiedSurfaceFields(surface: ConfigObjectSurface): string[];
+/**
+ * Secret-adjacent model fields the surface leaves undecided — neither exposed
+ * with a stated contract nor classified `notExposed` (#2254, #2256).
+ */
+export declare function findUnclassifiedSecretishSurfaceFields(surface: ConfigObjectSurface, modelFields: ModelFieldMap): string[];
+/** Fields classified twice — exposed AND `notExposed`. Ambiguous, so a failure. */
+export declare function findDoubleClassifiedFields(table: ConfigTable): string[];
+/**
+ * `notExposed` / `tomlOnlyKeys` / `responseOnlyKeys` entries whose `note` is
+ * missing or blank. A reason is the whole point of the classification.
+ */
+export declare function findReasonlessClassifications(table: ConfigTable): string[];
+/**
+ * Secret-adjacent model fields with no explicit decision — neither an exposed
+ * entry nor a `notExposed` classification. A bare omission is the failure mode
+ * this catches.
+ */
+export declare function findUnclassifiedSecretishFields(table: ConfigTable, modelFields: readonly string[]): string[];
+/**
+ * Every distinct handler reference the table names, as
+ * `"<repo-relative module>#<export>"`. The guard resolves each one and fails
+ * when the module or the export is missing (#2644 behavior 2b).
+ */
+export declare function handlerReferences(table: ConfigTable): string[];
+/** TOML keys this table accepts: the exposed fields plus the declared extras. */
+export declare function acceptedTomlKeys(table: ConfigTable): Set<string>;
+/** Top-level TOML keys this object's file accepts: its tables plus the extras. */
+export declare function acceptedTomlDocumentKeys(surface: ConfigObjectSurface): Set<string>;
+/**
+ * `tomlDocumentKeys` entries with no reason, and any that merely restate a
+ * field table. Both are failures: a reason is the whole point of the
+ * classification, and a duplicate would let a table's shape check be bypassed
+ * by declaring it twice.
+ */
+export declare function findBadDocumentKeyDeclarations(surface: ConfigObjectSurface): string[];
+/** Root keys of `tomlData` the surface does not declare. `config push` rejects these. */
+export declare function findUnknownTomlDocumentKeys(surface: ConfigObjectSurface, tomlData: unknown): string[];
+export declare function findMisshapenTomlTables(surface: ConfigObjectSurface, tomlData: unknown): Array<{
+    key: string;
+    expected: "table" | "array of tables";
+}>;
+/**
+ * Server-response keys this table recognizes: every model field (exposed or
+ * not) plus the declared response-only keys. `config pull` warns about anything
+ * else instead of dropping it silently (#2644 criterion 6).
+ */
+export declare function recognizedResponseKeys(table: ConfigTable, modelFields: readonly string[]): Set<string>;
+/**
+ * Request schemas generated from the configuration-object definitions
+ * (issue #2644, phase 5 / criterion 9).
+ *
+ * Every create/update handler in this family used to drop, in silence, any body
+ * key it did not read. A client sending `timoutMs` for `timeoutMs` got a 200 and
+ * no timeout change. These schemas close that: one per object and mode,
+ * `additionalProperties: false`, properties = the keys that object accepts on
+ * the wire in that mode, so an unknown key is a 400 naming it.
+ *
+ * **Breaking change, named**: a client that sends a stray key and gets a 200
+ * today will get a 400. The CLI never hits it — `config push` already rejects
+ * unrecognized TOML keys locally (criterion 6).
+ *
+ * ── What the schema says, and what it deliberately does not ──────────────
+ * It states the KEY SET only: each property is the empty schema, so no value is
+ * type-checked here. That is the decision of record (#1976, carried forward at
+ * #2644's design gate): the definition classifies, handlers behave. The
+ * `status` enum, the queue limits' integer coercion, `runAs`'s caller|system
+ * check, the CEL parse of `accessRule` — all stay in the handlers the
+ * definition names, with their existing messages. Adding type gates here would
+ * duplicate them and start rejecting values the handlers accept.
+ *
+ * ── Which keys are in the set ────────────────────────────────────────────
+ * Derived, not listed:
+ *
+ *   - every field the definition says is writable in this mode;
+ *   - every field classified `structural` — the authored sub-trees that travel
+ *     on their own channel (`rules`, `steps`, `metadataManifest`, `schema`,
+ *     `triggers`) but are still sent in the body — in the modes that entry
+ *     declares (`requestModes`; omitted means both, `[]` means the key travels
+ *     in the URL path and no schema admits it);
+ *   - every field classified `deprecated` — still writable server-side, by
+ *     definition of that classification;
+ *   - the table's `requestOnlyKeys`, in the modes each declares: protocol keys
+ *     that are not model fields at all, such as the `expectedModifiedAt`
+ *     optimistic-concurrency token or a create-only alias.
+ *
+ * `server-owned` and `secret` classifications are the two the schema excludes:
+ * the first is assigned by the server, the second never travels in readable
+ * form.
+ *
+ * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity).
+ */
+/**
+ * A generated request schema. Shaped for the app API's `meta.request` slot and
+ * the runtime validator it feeds (`src/app-api/request-validation.ts`), which
+ * reports an unknown key as `value.<key> is not allowed`.
+ */
+export interface ConfigRequestSchema {
+    type: "object";
+    properties: Record<string, Record<string, never>>;
+    additionalProperties: false;
+    /**
+     * Structural-typing escape hatch: the app API's `meta.request` slot is a
+     * `Record<string, unknown>` (`JsonSchema`), and an interface with no index
+     * signature is not assignable to one. Declaring the index here keeps the
+     * generated schema usable as a route schema without an `as any` at every
+     * call site.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Protocol keys every config UPDATE accepts, whichever object it is.
+ *
+ * `expectedModifiedAt` is the optimistic-concurrency token `config push` attaches
+ * to an update body when it has a baseline from the last pull; a handler that
+ * does not implement conflict detection ignores it. It is a property of the
+ * sync protocol rather than of any one object, which is why it is stated once
+ * here instead of in thirteen definitions.
+ */
+export declare const UPDATE_PROTOCOL_KEYS: readonly string[];
+/** The body keys this table accepts in `mode`, in a stable order. */
+export declare function requestSchemaKeys(table: ConfigTable, mode: "create" | "update"): string[];
+/**
+ * The request schema for one object and mode. Generated from the definition, so
+ * a schema permitting a key the definition does not is unrepresentable: there
+ * is no place to write one.
+ */
+export declare function configRequestSchema(table: ConfigTable, mode: "create" | "update"): ConfigRequestSchema;
+/**
+ * The retired-key guidance for a generated schema, keyed by body key — or
+ * `undefined` when the schema's object has none. Consumed by the app API's
+ * request validator (`src/app-api/request-validation.ts`).
+ */
+export declare function retiredRequestKeys(schema: object | undefined): Readonly<Record<string, string>> | undefined;
+/**
+ * One schema for an endpoint whose body spans MORE than one table.
+ *
+ * `POST …/prompts` is the case: it creates the prompt AND seeds its first
+ * config, so the body carries `[prompt]` fields and `[[configs]]` fields
+ * together. Both halves still come from their definitions — this only says the
+ * endpoint accepts the union, in the one place that is true.
+ */
+export declare function mergeRequestSchemas(...schemas: readonly ConfigRequestSchema[]): ConfigRequestSchema;
+/**
+ * The body keys `table` does not accept in `mode` — the 400's subject.
+ *
+ * Used by the admin API, which has no request-schema middleware: its handlers
+ * call this directly so both APIs reject the same key set for the same object.
+ */
+export declare function unknownRequestKeys(body: unknown, table: ConfigTable, mode: "create" | "update"): string[];
+/** The 400 message naming the unknown key(s), shared by both APIs. */
+export declare function unknownRequestKeysMessage(keys: readonly string[]): string;
+/**
+ * Keys deliberately RETIRED from a configuration object's write surface.
+ *
+ * A retired key is not an unknown key. The generic hint for an unrecognized
+ * TOML key — "check the spelling, or upgrade the CLI" — is exactly backwards
+ * for one this CLI removed on purpose, and the generic 400 for an unaccepted
+ * request key says only that the key is not allowed, not where the value moved
+ * to. Both surfaces need the same sentence, and neither should invent it.
+ *
+ * So the guidance lives here, next to the definitions, with one entry per
+ * retired key: the TOML wording for `config push` (which can tell the author to
+ * delete a line) and the request wording for the API handlers (which cannot).
+ *
+ * Keyed by the table's TOML path prefix (`workflow`, `cronTrigger`, …), because
+ * that is the identifier both consumers already have in hand.
+ *
+ * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity).
+ */
+export interface RetiredConfigKey {
+    /** What `config push` says about a file that still carries the key. */
+    toml: string;
+    /** What a create/update handler says about a body that still sends it. */
+    request: string;
+}
+export declare const RETIRED_CONFIG_KEYS: Record<string, Record<string, RetiredConfigKey>>;
+/** The retired-key entry for `key` under `prefix`, or null when it is simply unknown. */
+export declare function retiredConfigKey(prefix: string, key: string): RetiredConfigKey | null;
+/**
+ * The capability grammar for server functions — #3182 phase 1, rewritten by
+ * #3279 (project `server-functions` phase 3).
+ *
+ * A function declares in its own TOML what it may CONFIGURE:
+ *
+ *   capabilities = ["integration:stripe", "secret:STRIPE_KEY", "databases:delete"]
+ *
+ * ── Why the grammar is this small ────────────────────────────────────────
+ *
+ * The intent's decision (2026-09-09, "Authorization inside a function?"):
+ * function code acts as the system. The invocation gate is the authorization,
+ * and inside a function every platform call carries the app's own authority in
+ * every family. A capability is therefore never a statement about DATA — a
+ * model, a prompt, a channel, a member — because the function may reach all of
+ * it. It is declared only where it configures something:
+ *
+ *   `integration:<key>`   the egress allowlist — which upstream hosts the
+ *                         function's outbound calls may reach;
+ *   `secret:<NAME>`       credential least privilege — which secret VALUES may
+ *                         cross into the sandbox at all;
+ *   the high-blast list   {@link HIGH_BLAST_CAPABILITIES} — the operations
+ *                         whose blast radius the intent keeps opt-in.
+ *
+ * Every other string a function used to declare is RETIRED, and the grammar
+ * says so by name: an author who still writes `database:orders/Order:read`
+ * is told the model changed and what stays, not "unknown family", which would
+ * send them to check their spelling.
+ *
+ * ── Why the components have a charset ────────────────────────────────────
+ *
+ * A keyed grant's key must match `[A-Za-z0-9_-]+`, so neither `:` nor `/` can
+ * enter a component and the string is INJECTIVE — one string, one object. An
+ * integration or secret whose key carries a delimiter is simply unreachable
+ * from functions, with an error that says why (D3182-001's argument, kept).
+ *
+ * ── Why this module is pure ──────────────────────────────────────────────
+ *
+ * Capabilities are validated twice — by `config push`'s preflight, so an
+ * author sees the error against their own file, and by the server, which is
+ * authoritative because the raw admin API exists. Two enforcement points must
+ * not be two grammars, so the grammar lives here, in the dependency-free
+ * `src/config-surface/` tree the CLI vendors at build time
+ * (`cli/scripts/gen-config-surfaces.mjs`). The server imports this module; the
+ * CLI imports the generated copy; the drift guard fails if they differ.
+ */
+/** Every component of a grant. Injectivity depends on this. */
+export declare const GRANT_COMPONENT_PATTERN: RegExp;
+/** `ServerFunctionConfig.capabilities` is a StringSet with these bounds. */
+export declare const MAX_CAPABILITY_ENTRIES = 100;
+export declare const MAX_CAPABILITY_ENTRY_LENGTH = 200;
+/**
+ * The two keyed families the intent keeps: one component under
+ * {@link GRANT_COMPONENT_PATTERN}, naming a single object. Every key format the
+ * platform issues fits: an integration key is `^[a-z0-9][a-z0-9-_]{2,}$` and a
+ * secret name is `^[A-Z][A-Z0-9_]{0,63}$`.
+ */
+export declare const KEYED_GRANT_FAMILIES: readonly ["integration", "secret"];
+/**
+ * The high-blast-radius opt-ins — #3279, criterion 5 (CR3279-001, D3279-003).
+ *
+ * Since function code acts as the system, admission to a family is no longer
+ * an authority statement: everything the gateway lets through runs with the
+ * app's own authority. Most operations are fine that way — that is the whole
+ * decision. A short list is not, and the intent names its categories: delete a
+ * database, app or user; role changes; secret changes; resource provisioning.
+ * Those stay opt-in, so a function that can do them says so in a reviewable
+ * line of its TOML.
+ *
+ * The strings are EXACT and 1:1 with the operation id, so there is nothing to
+ * look up: `users.setRole` needs `users:setRole`. They parse with the verb as
+ * their KEY, because two exact capabilities in one family must not cover each
+ * other — `databases:create` is not permission to delete a database.
+ *
+ * The database ROLE mutations are here because they hand out persistent
+ * authority: a group grant assigns the manager role (D3279-003). App deletion
+ * and secret writes have no app-API route today; they are recorded, not gated,
+ * and the profile generator refuses to admit a future such route without a row
+ * here (`HIGH_BLAST_WATCH` in `scripts/lib/function-profile.mjs`).
+ */
+export declare const HIGH_BLAST_CAPABILITIES: readonly ["databases:create", "databases:delete", "databases:transferOwnership", "databases:addManager", "databases:revokePermission", "databases:grantGroupPermission", "databases:revokeGroupPermission", "users:remove", "users:setRole", "blobBuckets:createBucket", "blobBuckets:deleteBucket"];
+/** The exact strings, which since #3279 are exactly the high-blast list. */
+export declare const EXACT_GRANT_STRINGS: readonly ["databases:create", "databases:delete", "databases:transferOwnership", "databases:addManager", "databases:revokePermission", "databases:grantGroupPermission", "databases:revokeGroupPermission", "users:remove", "users:setRole", "blobBuckets:createBucket", "blobBuckets:deleteBucket"];
+export type GrantFamily = (typeof KEYED_GRANT_FAMILIES)[number] | "databases" | "users" | "blobBuckets";
+/**
+ * The retired FAMILIES (#3279), each with the reason it is gone.
+ *
+ * The value is what the family used to authorize, phrased as what a function
+ * now reaches without it. A refusal names the authored string, says it is
+ * retired, gives this reason, tells the author to delete the entry, and lists
+ * what stays.
+ */
+export declare const RETIRED_GRANT_FAMILIES: Record<string, string>;
+/** The retired EXACT strings (#3279), on the same terms. */
+export declare const RETIRED_GRANT_STRINGS: Record<string, string>;
+/**
+ * The retirement sentence for one authored string, or null when the string is
+ * not a retired one.
+ *
+ * Exported so the enforcement-time reader (`loadConfigGrants`) can tell a
+ * retired string on a pre-change row — tolerated, logged — from a string that
+ * was never a grant at all, which still authorizes nothing.
+ */
+export declare function retiredGrantRefusal(raw: string): string | null;
+/**
+ * Any grant, in one flat shape.
+ *
+ * Flat rather than a discriminated union because this module is vendored into
+ * the CLI, which compiles with `strict: false`: a caller reads `family` and
+ * then `key`, and the fields another family would have used are simply absent.
+ */
+export interface FunctionGrant {
+    family: GrantFamily;
+    /**
+     * The single component of a keyed family — the integration key or the
+     * secret name — or the VERB of a high-blast string (`delete` for
+     * `databases:delete`), so that no two exact capabilities in one family read
+     * as the same grant.
+     */
+    key: string;
+    /** The authored string, so an error or a log line can quote it. */
+    raw: string;
+}
+export interface ParsedFunctionGrant {
+    grant?: FunctionGrant;
+    error?: string;
+}
+/**
+ * A channel name's ceiling, and the reason it has one.
+ *
+ * The name rides in a `ConnectionMapping` row's document-id slot as
+ * `ch:<appId>:<channel>` and in every grant token's claims, so an unbounded
+ * name would be an unbounded key and an unbounded credential. 200 characters
+ * is {@link MAX_CAPABILITY_ENTRY_LENGTH}, kept for continuity with the rows
+ * #3184 already wrote.
+ */
+export declare const MAX_CHANNEL_NAME_LENGTH = 200;
+export interface ParsedChannelName {
+    /** The segment before the first `:`. Absent when the name is refused. */
+    namespace?: string;
+    error?: string;
+}
+/**
+ * A channel NAME, and its namespace.
+ *
+ * The grammar is the grant component charset applied per segment: one or more
+ * `[A-Za-z0-9_-]+` segments joined by `:`. The `channel:<namespace>` GRANT
+ * that used to cover a name is retired (#3279); the name grammar stays because
+ * the authorize and publish routes answer 400 about a name outside it before
+ * anything else, and the connection worker keys membership by it.
+ *
+ * Refusals name the segment that failed, because "channel name is invalid" on
+ * a name like `orders:a::b` tells an author nothing they cannot already see.
+ */
+export declare function parseChannelName(value: unknown): ParsedChannelName;
+/**
+ * One capability entry as a grant, or the reason it is not one.
+ *
+ * The single entry point the enforcement path and both preflights use: a
+ * caller holds one authored string and asks what it grants, without having to
+ * know which of the shapes to try. Every diagnosis is specific — a retired
+ * string gets the retirement and what stays; a near miss in a kept family gets
+ * the family's own strings; a keyed family gets its charset rule.
+ */
+export declare function parseFunctionGrant(entry: unknown): ParsedFunctionGrant;
+/**
+ * One shape rather than a discriminated union: this module is vendored into
+ * the CLI, which compiles with `strict: false`, where narrowing on a boolean
+ * literal discriminant does not hold. Both callers read `ok` and then the
+ * field they want, and the unused half is empty rather than absent.
+ */
+export interface ParsedCapabilities {
+    ok: boolean;
+    /** Deduped, in authored order — what the config row stores. Empty when refused. */
+    capabilities: string[];
+    /** Every grant, in authored order. */
+    allGrants: FunctionGrant[];
+    /**
+     * The retired strings that were SKIPPED, in authored order — populated only
+     * under `tolerateRetired` (see {@link parseCapabilities}); a strict parse
+     * refuses them instead and leaves this empty.
+     */
+    retired: string[];
+    /** Empty when accepted. */
+    errors: string[];
+}
+export interface ParseCapabilitiesOptions {
+    /**
+     * Skip retired strings instead of refusing them — #3279 edge 25.
+     *
+     * The PUSH path is strict: a file that still declares a retired grant is
+     * refused with the retirement, because a line that is accepted and ignored
+     * is a line the author believes means something. The ENFORCEMENT path is
+     * tolerant: a config version pushed before #3279 carries retired strings in
+     * a row that can never be re-pushed to fix (its envelope is immutable), and
+     * refusing it there would break every function pushed before the change.
+     * Such a row authorizes exactly what it keeps, and the skipped strings are
+     * reported in `retired` so the caller can log them.
+     */
+    tolerateRetired?: boolean;
+}
+/**
+ * A whole `capabilities` list: shape, bounds, grammar, duplicates.
+ *
+ * The model's own caps are checked HERE rather than left to the StringSet
+ * field, so an over-long entry is a named push error instead of a late model
+ * throw after the R2 object has already been written (principle 6).
+ */
+export declare function parseCapabilities(value: unknown, options?: ParseCapabilitiesOptions): ParsedCapabilities;
+/**
+ * The config-tree objects an `integration:` grant may name.
+ *
+ * Only the one family whose target is CONFIG-TREE state. `secret:` is absent
+ * on purpose (D3183-002): its values are provisioned per environment, out of
+ * band, and are not part of the reviewed tree at all, so the ordinary order of
+ * work is to push the function and then provision the value. Refusing an
+ * unprovisioned name at push would break that; a missing value at CALL time is
+ * a structured runtime error instead. The high-blast strings name no object.
+ *
+ * `null` means "this enforcement point could not find out". The CLI reads the
+ * tree and, when it can, a live listing; when neither is available it defers
+ * rather than guessing, because a preflight that refused a valid tree for
+ * being offline would be worse than one that lets the server have the last
+ * word. The server never passes null — it can always read its own rows.
+ */
+export interface KnownGrantTargets {
+    /** Non-archived integration keys, or null when unknown. */
+    integrations: ReadonlySet<string> | null;
+}
+/**
+ * Grants naming an integration the app does not have.
+ *
+ * One message per offending grant, quoting the whole authored string AND the
+ * key on its own, so an operator reading the line knows both what to fix in
+ * the file and what to create in the app.
+ *
+ * The rule is here, beside the grammar, for the reason the whole module
+ * exists: `config push`'s preflight and the authoritative server check read
+ * different sources for the same facts — a `.toml` in the tree versus a row
+ * in DynamoDB — and it is the RULE that must not differ between them.
+ */
+export declare function validateKeyedGrantsAgainstTargets(grants: readonly FunctionGrant[], known: KnownGrantTargets): string[];
+/**
+ * The query manifest's grammar, and the read rule it unlocks — #3187, project
+ * `server-functions` phase 5.
+ *
+ * A pushed config version may carry a MANIFEST: the queries and mutations the
+ * tree registered at module scope, collected by the CLI (`function-collect.ts`)
+ * by running the tree with `primitive-functions` aliased to a recording stub.
+ *
+ * ── What the manifest is for ─────────────────────────────────────────────
+ *
+ * Observability, and nothing else. `primitive functions get` and the admin
+ * get list what a version registered, so an operator can see it without
+ * reading the bundle (principle 8). The read rule it used to be decided from
+ * (#3187's `$caller` relaxation of `unscopedReads`) is retired by #3279:
+ * function code acts as the system, so there is no per-model grant for a
+ * binding to waive. The intent says so in as many words — "the models a
+ * function touches are collected at push as a reviewable manifest, not an
+ * authorization".
+ *
+ * It is HONEST-CODE evidence and the design doc says so: a hostile bundle can
+ * register whatever it likes, because the collector runs the tenant's own
+ * code. Nothing security-relevant at runtime reads it — parameter injection
+ * and cache verification happen in the platform-owned SDK inside the isolate,
+ * and the invocation gate remains the adversarial boundary.
+ *
+ * ── Why the grammar is here ──────────────────────────────────────────────
+ *
+ * Same reason as `function-grants.ts`: the CLI validates at push preflight so
+ * an author sees the error against their own tree, and the server validates
+ * authoritatively because the raw admin API exists. Two enforcement points,
+ * one rule, in the dependency-free tree the CLI vendors.
+ */
+/**
+ * The manifest encoding, versioned with the envelope that carries it.
+ *
+ * Version 2 (#3279 behavior 10) adds what a function TOUCHES beside what it
+ * registers: the deduplicated `models` its code names and the `families` of
+ * `ctx.api` and the ctx helpers it reaches, collected by a static scan of the
+ * built bundle, plus a `dynamicModels` marker for a model name the scan
+ * could not resolve — distinct from an empty list, which means "names none".
+ * A version-1 manifest still parses: it records registrations only.
+ */
+export declare const FUNCTION_MANIFEST_SCHEMA_VERSION = 2;
+export declare const FUNCTION_MANIFEST_SCHEMA_VERSIONS: readonly [1, 2];
+/** Bounds, so a manifest cannot be a way to store an unbounded blob. */
+export declare const MAX_MANIFEST_QUERIES = 200;
+export declare const MAX_MANIFEST_NAME_LENGTH = 120;
+export declare const MAX_MANIFEST_MODELS = 200;
+export declare const MAX_MANIFEST_FAMILIES = 40;
+export interface ManifestParam {
+    type?: string;
+    /** `type: "array"` — the element type, when declared (#3281). */
+    items?: {
+        type: string;
+    };
+    caller?: boolean;
+    optional?: boolean;
+    default?: unknown;
+}
+/** The scalar parameter types a registration may declare, and an array's element types. */
+export declare const QUERY_PARAM_SCALAR_TYPES: readonly ["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 declare function coerceParamDefault(spec: {
+    type?: string;
+    items?: {
+        type?: string;
+    };
+}, value: unknown): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface ManifestQuery {
+    name: string;
+    kind: "query" | "mutation";
+    models: string[];
+    params: Record<string, ManifestParam>;
+    cache: {
+        ttlMs: number;
+    } | null;
+    /** True when a `$caller` binding scopes this registration. */
+    callerScoped: boolean;
+}
+export interface FunctionManifest {
+    schemaVersion: number;
+    queries: ManifestQuery[];
+    /**
+     * Every model name the bundle names, deduplicated and sorted: registration
+     * declarations, literal `.model("…")` calls, and literal `modelName`/`model`
+     * arguments of the direct records and documents calls (#3279). Empty for a
+     * version-1 manifest, and for a function that names none.
+     */
+    models: string[];
+    /** Every `ctx.api.<family>` and ctx-helper family the bundle reaches. */
+    families: string[];
+    /**
+     * The scan met a model name it could not resolve — a computed
+     * `modelName`, a `.model(variable)`. Says "and possibly more", which an
+     * empty `models` list does not.
+     */
+    dynamicModels: boolean;
+}
+export interface ParsedManifest {
+    ok: boolean;
+    manifest: FunctionManifest | null;
+    errors: string[];
+}
+/**
+ * Validate a manifest's grammar and normalize it.
+ *
+ * Deliberately strict about SHAPE and silent about meaning: whether the models
+ * exist, whether the queries are the ones the sandbox will really register,
+ * and whether the author meant any of it are questions this cannot answer.
+ */
+export declare function parseFunctionManifest(value: unknown): ParsedManifest;
+/**
+ * The function MODE vocabulary, and the one place its two spellings meet —
+ * #3281, project `server-functions` phase 4.
+ *
+ * `mode = "request" | "task"` is what an author writes (the intent, "Mode
+ * vocabulary?", sponsor decision 2026-09-09): a request function runs inside
+ * the call and returns its result; a task function returns a run id and
+ * survives restarts. `durable = true | false` is the key the first releases
+ * taught, and it stays ACCEPTED as an alias through the transition — a tree
+ * pushed with it keeps pushing, and pulls back byte for byte — while `durable`
+ * stays the adjective for the property itself.
+ *
+ * ── Why one module ───────────────────────────────────────────────────────
+ *
+ * Two spellings for one fact is a place two readers can disagree. So the
+ * resolution is written once, here, in the dependency-free tree the CLI
+ * vendors (`cli/scripts/gen-config-surfaces.mjs`), and every door reads it:
+ * the CLI preflight and diff entity, the server's trigger derivation, the
+ * admin config-version route (payload `mode` beside payload `durable`), the
+ * invoke branch and the trigger fires. A file — or a payload — that carries
+ * both keys has to have them AGREE, or it is refused naming both; a silent
+ * winner would be the one thing worse than two spellings.
+ *
+ * The stored column is still `ServerFunctionConfig.durable` (no `models.yaml`
+ * change before phase 7's rename sweep), which is why `configMode` exists:
+ * reading the row is the other half of the same translation.
+ */
+export type FunctionMode = "request" | "task";
+export declare const FUNCTION_MODES: readonly FunctionMode[];
+/** What a declaration resolved to, or why it could not. */
+export type DeclaredModeResolution = {
+    ok: true;
+    mode: FunctionMode;
+    /**
+     * Whether the declaration SAID anything — false when neither key was
+     * present and the default applied. The admin route's divergence check
+     * reads this: an omitted mode is no claim, so it cannot diverge.
+     */
+    declared: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 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 declare function resolveDeclaredMode(input: {
+    mode?: unknown;
+    durable?: unknown;
+}): DeclaredModeResolution;
+/**
+ * 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 declare function configMode(row: {
+    durable?: unknown;
+} | null | undefined): FunctionMode;
+/** Is this mode the durable one? The adjective, for the paths that branch on it. */
+export declare function isDurableMode(mode: FunctionMode): boolean;
+/**
+ * The trigger blocks a function declares, derived from its authored TOML
+ * (#3181, project `server-functions`, criterion 4).
+ *
+ * ── The declaration is derived, never supplied ────────────────────────────
+ *
+ * A config-version push carries the authored `functions/<key>.toml` bytes
+ * inside its envelope, and `envelopeHash` covers them. If the push ALSO
+ * carried a parsed `triggers` payload, the two could disagree: a direct API
+ * caller could ship a public webhook trigger the authored file does not
+ * declare, and two pushes with identical envelopes but different trigger
+ * payloads would collapse to one version. So the server parses the envelope's
+ * own bytes here (D3181-005) and there is no payload field to disagree with —
+ * trigger behavior is bound to the version's identity by construction.
+ *
+ * ── Shape only ────────────────────────────────────────────────────────────
+ *
+ * This module decides what the file SAYS: the accepted key set, the required
+ * values, and the rules that need nothing but the document (scheme `none`,
+ * a nameless or duplicated cron entry, an entry count past the per-function
+ * cap, a webhook or database block on a task version). Everything that needs the
+ * app's state — whether a referenced secret exists, whether the
+ * scheme-specific config is valid, whether the app is at its webhook or cron
+ * cap, whether a standalone webhook holds the key — belongs to the push
+ * boundary, which runs the SAME validators the standalone create runs
+ * (D3181-006).
+ *
+ * ── One implementation, two readers (#3320) ───────────────────────────────
+ *
+ * The CLI checks the same rules against the author's own file before a request
+ * is made. It used to do that from a hand-written restatement
+ * (`cli/src/lib/function-triggers.ts`), kept in step only by a paired-fixture
+ * test — so a rule added here with no fixture drifted silently. The rules
+ * therefore live in `src/config-surface/`, which `cli/scripts/
+ * gen-config-surfaces.mjs` vendors verbatim into the committed artifact
+ * `cli/src/lib/generated-config-surfaces.ts`. There is one implementation, and
+ * a change here that is not regenerated fails `--check` (a build failure)
+ * rather than a fixture list that happens not to cover it.
+ *
+ * Reading the authored BYTES is the one thing that stayed server-side:
+ * `deriveTriggerDeclaration` in `src/server-functions/trigger-declaration.ts`
+ * parses them and calls `normalizeTriggerDeclaration` here. This directory
+ * imports nothing but itself (asserted by `config-surface-drift-guard.test.ts`),
+ * and the CLI has already parsed its own file by the time it asks.
+ */
+/**
+ * The resolved mode the declaration is checked against (#3281).
+ *
+ * The rule is per KIND, and permanent (the intent, "Sync functions write a run
+ * row?": *Webhook and database-change triggers require request mode; HTTP and
+ * cron allow both*). A webhook delivery and a database write are both waiting
+ * inside a request for the function to answer; a cron fire is waiting for
+ * nothing, so it starts a task run when the version is a task (#3334).
+ *
+ * The caller resolves `mode`/`durable` once, through `resolveDeclaredMode`,
+ * and hands the answer here — this module never reads the alias itself.
+ */
+export interface TriggerModeOptions {
+    mode?: FunctionMode;
+}
+/**
+ * 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 declare const WEBHOOK_ON_TASK_REFUSAL: string;
+/** A function's single webhook trigger, normalized. */
+export interface WebhookTriggerDeclaration {
+    verificationScheme: string;
+    signingSecret?: string;
+    toleranceSeconds?: number;
+    deduplicationEnabled?: boolean;
+    deduplicationWindowMs?: number;
+    maxBodyBytes?: number;
+    secretGracePeriodMs?: number;
+    /** `[function.triggers.webhook.verification]` — the row's `config`. */
+    verification?: Record<string, unknown>;
+}
+/** One `[[function.triggers.cron]]` entry, normalized. */
+export interface CronTriggerDeclaration {
+    name: string;
+    cron: string;
+    timezone?: string;
+    overlapPolicy?: string;
+    rootInput?: unknown;
+}
+/** One `[[function.triggers.database]]` entry, normalized (#3184). */
+export interface DatabaseTriggerDeclaration {
+    /** The database type key whose writes fire this function. */
+    type: string;
+}
+export interface TriggerDeclaration {
+    webhook: WebhookTriggerDeclaration | null;
+    cron: CronTriggerDeclaration[];
+    databases: DatabaseTriggerDeclaration[];
+}
+export declare const EMPTY_TRIGGER_DECLARATION: TriggerDeclaration;
+/**
+ * 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 declare const MAX_CRON_TRIGGERS_PER_FUNCTION = 10;
+/**
+ * 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 declare const MAX_DATABASE_TRIGGERS_PER_FUNCTION = 5;
+export declare class TriggerDeclarationError extends Error {
+}
+/** Is anything at all declared? Used to skip work on the common case. */
+export declare function hasDeclaredTriggers(declaration: TriggerDeclaration): boolean;
+/**
+ * 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 declare function normalizeTriggerDeclaration(functionTable: any, options?: TriggerModeOptions): TriggerDeclaration;
+/** The stored JSON for `ServerFunctionConfig.triggers`, or null when empty. */
+export declare function serializeTriggerDeclaration(declaration: TriggerDeclaration): string | null;
+/** Read a stored `ServerFunctionConfig.triggers` value back. */
+export declare function parseStoredTriggerDeclaration(stored: unknown): TriggerDeclaration;
+/** The `CronTrigger.triggerKey` an entry owns. */
+export declare function cronTriggerKeyFor(functionKey: string, name: string): string;
+/** The entry name a `<functionKey>:<name>` trigger key carries. */
+export declare function cronTriggerNameFrom(functionKey: string, triggerKey: string): string;
+/**
+ * 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.
+ */
+export declare const SECRETS_TEMPLATE_RE: RegExp;
+/** True when the value carries at least one `{{secrets.KEY}}` reference. */
+export declare function isSecretTemplate(value: string | null | undefined): boolean;
+/**
+ * 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 declare function withoutSecretReferences(value: string): string;
+/**
+ * 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 declare function isSpoiledSecretReference(value: string | null | undefined): boolean;
+/**
+ * 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 declare const WHOLE_SECRET_REFERENCE_RE: RegExp;
+/**
+ * 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 declare function isWholeSecretReference(value: string | null | undefined): boolean;
+/**
+ * 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 declare const SCHEMES_WITHOUT_SIGNING_SECRET: readonly string[];
+export declare function requiresSigningSecret(scheme: unknown): boolean;
+/** The coded refusals, so a client can branch without matching prose. */
+export declare const SIGNING_SECRET_MUST_BE_SECRET_REF = "SIGNING_SECRET_MUST_BE_SECRET_REF";
+export declare const SIGNING_SECRET_NOT_SUPPORTED_FOR_SCHEME = "SIGNING_SECRET_NOT_SUPPORTED_FOR_SCHEME";
+/**
+ * A refusal from this rule. `plain` marks the ones the admin webhook create
+ * answered as a bare text body rather than coded JSON — an observable
+ * distinction, so it travels with the error rather than being flattened.
+ */
+export interface SigningSecretRuleError {
+    message: string;
+    code?: string;
+    plain?: boolean;
+}
+/** The reference-only message, shared by every field that carries one. */
+export declare function wholeSecretReferenceMessage(label: string): string;
+/**
+ * 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 declare function validateWholeSecretReference(label: string, value: unknown, code: string): SigningSecretRuleError | null;
+/**
+ * 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 declare function validateSigningSecretDeclaration(input: {
+    verificationScheme: string;
+    signingSecret?: unknown;
+}): SigningSecretRuleError | null;
+export declare const WORKFLOW_SURFACE: ConfigObjectSurface;
+export declare const PROMPT_SURFACE: ConfigObjectSurface;
+export declare const INTEGRATION_SURFACE: ConfigObjectSurface;
+export declare const WEBHOOK_SURFACE: ConfigObjectSurface;
+export declare const CRON_TRIGGER_SURFACE: ConfigObjectSurface;
+export declare const BLOB_BUCKET_SURFACE: ConfigObjectSurface;
+/**
+ * The `email-template` configuration object's definition (issue #2644, phase 2).
+ *
+ * `email-templates/<emailType>.toml` carries a single `[template]` table. The
+ * object is an OVERRIDE of a built-in template: the detail response is
+ * `{ emailType, hasOverride, override: {...}, default: {...} }`, and only the
+ * `override` half is a field surface — the `default` half is what the platform
+ * ships. Both are declared as response-only keys so `config pull`'s
+ * unrecognized-key warning reports genuinely unknown fields rather than the
+ * envelope.
+ *
+ * There is one write endpoint (`PUT …/email-templates/{emailType}`, an upsert),
+ * so every field is writable on both modes.
+ */
+/**
+ * Email types RETIRED by #2884, kept named rather than simply deleted.
+ *
+ * Email sign-in sends ONE email from the `email-sign-in` template, so
+ * `magic-link` and `otp` are no longer rendered by any code path — which is
+ * what makes deleting the link block from an `email-sign-in` override an
+ * actual guarantee rather than a hope about which endpoint ran.
+ *
+ * A stored override for a retired type is NOT deleted: it stays listed and
+ * readable (labelled retired, with the guidance below) so an app can find its
+ * customization and migrate it, and deleting it still works. Everything that
+ * would author one — the admin write/preview/test endpoints, `config create`,
+ * a `config push --only` selector — refuses by name instead. Silent
+ * non-rendering is the outcome all of that exists to avoid.
+ *
+ * It lives in the config surface, not beside the default templates, because
+ * the CLI vendors this directory and needs the same sentence.
+ */
+export declare const RETIRED_EMAIL_TYPES: readonly ["magic-link", "otp"];
+export type RetiredEmailType = (typeof RETIRED_EMAIL_TYPES)[number];
+/** True when `emailType` is one of the retired sign-in types. */
+export declare function isRetiredEmailType(emailType: string): emailType is RetiredEmailType;
+/** What every surface says about a retired type, in one sentence. */
+export declare function retiredEmailTypeGuidance(emailType: string): string;
+export declare const EMAIL_TEMPLATE_SURFACE: ConfigObjectSurface;
+export declare const DATABASE_TYPE_SURFACE: ConfigObjectSurface;
+export declare const RULE_SET_SURFACE: ConfigObjectSurface;
+export declare const GROUP_TYPE_CONFIG_SURFACE: ConfigObjectSurface;
+export declare const COLLECTION_TYPE_CONFIG_SURFACE: ConfigObjectSurface;
+export declare const METADATA_CATEGORY_CONFIG_SURFACE: ConfigObjectSurface;
+/**
+ * The `transform` configuration object's definition (issue #2644, phase 3).
+ *
+ * Transforms are the one synced type with NO TOML field table: a transform is
+ * `transforms/<name>.rhai`, a Rhai source file, and its whole authored surface
+ * is the script body. `config pull` writes the active `ScriptConfig`'s body and
+ * `config push` sends it back; there is no key/value table to define, and the
+ * `Script` / `ScriptConfig` scalars around it (name, description, inputSchema,
+ * limits, status) are not authorable through the sync slot today.
+ *
+ * The entry exists so that is a DECISION rather than an absence. Criterion 3's
+ * registry guard reads `SYNC_RESOURCE_TYPES` and requires a surface per label;
+ * without this module `transform` would have to sit in an exemption list, which
+ * is precisely the "absent from a hand-written list" failure mode this epic
+ * exists to end.
+ */
+export declare const TRANSFORM_SURFACE: ConfigObjectSurface;
+export declare const SERVER_FUNCTION_SURFACE: ConfigObjectSurface;
+export declare const TEST_CASE_SURFACE: ConfigObjectSurface;
+export declare const APP_SETTINGS_SURFACE: ConfigObjectSurface;
+/**
+ * The configuration-object registry (issue #2644).
+ *
+ * `CONFIG_SURFACES` holds one entry per synced configuration object type. The
+ * registry — not a per-type test — is what makes coverage follow from existing:
+ * `cli/tests/unit/config-surface-drift-guard.test.ts` reads the CLI's
+ * `SYNC_RESOURCE_TYPES` labels and fails when a label has no surface here.
+ *
+ * `CONFIG_SURFACES` is the write authority. `SYNC_RESOURCE_TYPES` keeps its
+ * documented role — directory/state/prune/diff layout metadata, explicitly "not
+ * a write framework" — and gains no write-surface fields; the two are
+ * cross-checked, not merged.
+ */
+/**
+ * Every configuration object whose field surface is defined here.
+ *
+ * One entry per `SYNC_RESOURCE_TYPES` label, plus the two surfaces that
+ * round-trip without being a per-entity file: `app-settings` (`app.toml`) and
+ * `test-case` (`<key>.tests/`). Nothing that syncs sits outside the registry —
+ * `PENDING_MIGRATION`, the migration's temporary exemption list, is gone as of
+ * phase 3, so a new synced type has nowhere to be parked and fails the registry
+ * guard until it is defined (#2644 criterion 3).
+ */
+export declare const CONFIG_SURFACES: readonly ConfigObjectSurface[];
+/** The surface for a `SyncResourceType.label`, or undefined when unmigrated. */
+export declare function getConfigSurface(label: string): ConfigObjectSurface | undefined;
+/** One table of one surface, addressed by its TOML path. */
+export declare function getConfigTable(label: string, tomlPath: readonly string[]): ConfigTable | undefined;
+/**
+ * Every field of every `models.yaml` model a configuration-object definition
+ * names, in declaration order — the coverage guard's anchor (#2644 criterion 2).
+ */
+export declare const GENERATED_CONFIG_MODEL_FIELDS: Readonly<Record<string, readonly string[]>>;