primitive-admin 1.0.61 → 1.0.63

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

@@ -0,0 +1,682 @@
+/**
+ * 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;
+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 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[]>>;