primitive-admin 1.0.61 → 1.0.62

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

@@ -0,0 +1,4058 @@
+/**
+ * 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.
+ */
+// ── src/config-surface/helpers.ts ────────────────────────────────────────
+/**
+ * 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 const BOTH = ["create", "update"];
+/** Create only: an immutable key or a field the update handler ignores. */
+export const CREATE_ONLY = ["create"];
+/** Update only: a field the create handler assigns itself. */
+export const UPDATE_ONLY = ["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 function handledBy(modulePath, exportName) {
+    return { handler: `${modulePath}#${exportName}` };
+}
+/**
+ * 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 const DECLARED_ACCESS_MANIFEST_KEYS = {
+    metadata: {
+        kind: "structural",
+        note: "#1304 declared-access manifest — `[metadata.self]` / `[metadata.paths.*]`. " +
+            "Parsed by parseDeclaredAccessManifestToml and stored as the owning " +
+            "object's `metadataManifest`.",
+    },
+    secrets: {
+        kind: "structural",
+        note: "The manifest's declared secret names (#1304). Same channel as [metadata].",
+    },
+    vars: {
+        kind: "structural",
+        note: "The manifest's declared var names (#1364), the non-secret twin of " +
+            "`secrets`. Same channel as [metadata].",
+    },
+};
+/** The field names this table accepts on the wire in `mode`, in declaration order. */
+export function writableFieldNames(table, mode) {
+    return table.fields
+        .filter((f) => f.writableOn.includes(mode))
+        .map((f) => f.field);
+}
+/**
+ * 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 function acceptedWriteFieldNames(table, mode) {
+    const deprecated = Object.entries(table.notExposed)
+        .filter(([, classification]) => classification.kind === "deprecated")
+        .map(([field]) => field);
+    return [...writableFieldNames(table, mode), ...deprecated];
+}
+/**
+ * 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 function pickWritableFields(body, table, mode) {
+    const writable = new Set(writableFieldNames(table, mode));
+    const accepted = {};
+    const rejected = [];
+    if (!body || typeof body !== "object")
+        return { accepted, rejected };
+    for (const key of Object.keys(body)) {
+        if (writable.has(key)) {
+            accepted[key] = body[key];
+        }
+        else {
+            rejected.push(key);
+        }
+    }
+    return { accepted, rejected };
+}
+/**
+ * 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 function passthroughFields(body, table, mode, options = {}) {
+    const out = {};
+    if (!body || typeof body !== "object")
+        return out;
+    const handled = new Set(options.handledHere ?? []);
+    for (const field of table.fields) {
+        if (field.validation !== "passthrough")
+            continue;
+        if (!field.writableOn.includes(mode))
+            continue;
+        if (handled.has(field.field))
+            continue;
+        if (!Object.prototype.hasOwnProperty.call(body, field.field))
+            continue;
+        out[field.field] = body[field.field];
+    }
+    return out;
+}
+/** `true` when the body carries `field` and this table accepts it in `mode`. */
+export function hasWritableField(accepted, field) {
+    return Object.prototype.hasOwnProperty.call(accepted, field);
+}
+/**
+ * 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 function isEmptyForEmit(value, type) {
+    if (value === null || value === undefined)
+        return true;
+    if (type === "string")
+        return value === "";
+    if (type === "string[]")
+        return !Array.isArray(value) || value.length === 0;
+    if (type === "json") {
+        return (typeof value !== "object" ||
+            Array.isArray(value) ||
+            Object.keys(value).length === 0);
+    }
+    return false; // booleans (false) and numbers (0) are meaningful, never empty
+}
+/**
+ * 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 const SECRETISH_FIELD = /secret|token|password|credential/i;
+/** Model fields the table neither exposes nor classifies. Non-empty is a failure. */
+export function findUnclassifiedFields(table, modelFields) {
+    const exposed = new Set(table.fields.map((f) => f.field));
+    return modelFields
+        .filter((f) => !exposed.has(f) && !(f in table.notExposed))
+        .sort();
+}
+/**
+ * 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 function findStaleClassifications(table, modelFields) {
+    const known = new Set(modelFields);
+    return [...table.fields.map((f) => f.field), ...Object.keys(table.notExposed)]
+        .filter((f) => !known.has(f))
+        .sort();
+}
+// ── Surface-level coverage ───────────────────────────────────────────────
+//
+// A table is not always the right unit. `app-settings` projects ONE model
+// (`App`) over FOUR `app.toml` sections, so `googleClients` is exposed in
+// `[auth]` while `[app]` has never heard of it — per-table coverage would
+// report it unclassified. Coverage is therefore a statement about the OBJECT:
+// every field of every model the object's tables name is exposed in one of
+// them, or classified `notExposed` in one of them.
+//
+// Results are reported as `"<Model>.<field>"` so a multi-model surface (prompt
+// carries `AppPrompt` and `AppPromptConfig`) says which model it means.
+/** The models this surface's tables project, in declaration order, deduped. */
+export function surfaceModels(surface) {
+    return [...new Set(surface.tables.map((t) => t.model))];
+}
+/** Model fields for `model`, or a loud failure — a silent `[]` is a vacuous guard. */
+function requireModelFields(modelFields, model) {
+    const fields = modelFields[model];
+    if (!fields) {
+        throw new Error(`config-surface: no models.yaml field list for "${model}". ` +
+            "Run `node cli/scripts/gen-config-surfaces.mjs`.");
+    }
+    return fields;
+}
+/** Every field name the surface exposes for `model`, across all its tables. */
+function exposedForModel(surface, model) {
+    return new Set(surface.tables
+        .filter((t) => t.model === model)
+        .flatMap((t) => t.fields.map((f) => f.field)));
+}
+/** Every field name the surface classifies `notExposed` for `model`. */
+function notExposedForModel(surface, model) {
+    return new Set(surface.tables
+        .filter((t) => t.model === model)
+        .flatMap((t) => Object.keys(t.notExposed)));
+}
+/**
+ * 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 function findUnclassifiedSurfaceFields(surface, modelFields) {
+    const out = [];
+    for (const model of surfaceModels(surface)) {
+        const exposed = exposedForModel(surface, model);
+        const classified = notExposedForModel(surface, model);
+        for (const field of requireModelFields(modelFields, model)) {
+            if (!exposed.has(field) && !classified.has(field)) {
+                out.push(`${model}.${field}`);
+            }
+        }
+    }
+    return out.sort();
+}
+/**
+ * Classifications naming a field the model no longer has — the other direction,
+ * and equally a failure: a stale entry quietly stops meaning anything.
+ */
+export function findStaleSurfaceClassifications(surface, modelFields) {
+    const out = [];
+    for (const model of surfaceModels(surface)) {
+        const known = new Set(requireModelFields(modelFields, model));
+        for (const name of [
+            ...exposedForModel(surface, model),
+            ...notExposedForModel(surface, model),
+        ]) {
+            if (!known.has(name))
+                out.push(`${model}.${name}`);
+        }
+    }
+    return out.sort();
+}
+/** Fields the surface both exposes and classifies `notExposed`. Ambiguous. */
+export function findDoubleClassifiedSurfaceFields(surface) {
+    const out = [];
+    for (const model of surfaceModels(surface)) {
+        const classified = notExposedForModel(surface, model);
+        for (const field of exposedForModel(surface, model)) {
+            if (classified.has(field))
+                out.push(`${model}.${field}`);
+        }
+    }
+    return out.sort();
+}
+/**
+ * Secret-adjacent model fields the surface leaves undecided — neither exposed
+ * with a stated contract nor classified `notExposed` (#2254, #2256).
+ */
+export function findUnclassifiedSecretishSurfaceFields(surface, modelFields) {
+    return findUnclassifiedSurfaceFields(surface, modelFields).filter((name) => SECRETISH_FIELD.test(name.split(".")[1] ?? name));
+}
+/** Fields classified twice — exposed AND `notExposed`. Ambiguous, so a failure. */
+export function findDoubleClassifiedFields(table) {
+    return table.fields
+        .map((f) => f.field)
+        .filter((f) => f in table.notExposed)
+        .sort();
+}
+/**
+ * `notExposed` / `tomlOnlyKeys` / `responseOnlyKeys` entries whose `note` is
+ * missing or blank. A reason is the whole point of the classification.
+ */
+export function findReasonlessClassifications(table) {
+    const bad = [];
+    const maps = [
+        ["notExposed", table.notExposed],
+        ["tomlOnlyKeys", table.tomlOnlyKeys],
+        ["responseOnlyKeys", table.responseOnlyKeys],
+    ];
+    for (const [label, map] of maps) {
+        for (const [field, entry] of Object.entries(map)) {
+            if (!entry || typeof entry.note !== "string" || !entry.note.trim()) {
+                bad.push(`${label}.${field}`);
+            }
+        }
+    }
+    return bad.sort();
+}
+/**
+ * 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 function findUnclassifiedSecretishFields(table, modelFields) {
+    const exposed = new Set(table.fields.map((f) => f.field));
+    return modelFields
+        .filter((f) => SECRETISH_FIELD.test(f) && !exposed.has(f) && !(f in table.notExposed))
+        .sort();
+}
+/**
+ * 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 function handlerReferences(table) {
+    const refs = new Set();
+    for (const field of table.fields) {
+        if (field.validation !== "passthrough")
+            refs.add(field.validation.handler);
+    }
+    return [...refs].sort();
+}
+/** TOML keys this table accepts: the exposed fields plus the declared extras. */
+export function acceptedTomlKeys(table) {
+    return new Set([
+        ...table.fields.map((f) => f.tomlKey),
+        ...Object.keys(table.tomlOnlyKeys),
+    ]);
+}
+// ── Document-level acceptance ────────────────────────────────────────────
+//
+// `acceptedTomlKeys` answers "is this key accepted inside this table". These
+// three answer the question one level up — "is this table accepted in this
+// file, and in the right shape" — which is what makes push's rejection total
+// (design gate, 2026-08-12). A typo'd header (`[integraton]`) or a miswritten
+// array (`[configs]` for `[[configs]]`) used to parse to a root key nothing
+// checked, so the file pushed as though the real table were empty: the
+// TOML-owned fields inside it were sent as explicit nulls and CLEARED.
+/** Top-level TOML keys this object's file accepts: its tables plus the extras. */
+export function acceptedTomlDocumentKeys(surface) {
+    return new Set([
+        ...surface.tables.map((t) => t.tomlPath[0]).filter((k) => !!k),
+        ...Object.keys(surface.tomlDocumentKeys),
+    ]);
+}
+/**
+ * `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 function findBadDocumentKeyDeclarations(surface) {
+    const tableKeys = new Set(surface.tables.map((t) => t.tomlPath[0]));
+    const bad = [];
+    for (const [key, entry] of Object.entries(surface.tomlDocumentKeys)) {
+        if (!entry || typeof entry.note !== "string" || !entry.note.trim()) {
+            bad.push(`${key} (no note)`);
+        }
+        if (tableKeys.has(key))
+            bad.push(`${key} (already a field table)`);
+    }
+    return bad.sort();
+}
+/** Root keys of `tomlData` the surface does not declare. `config push` rejects these. */
+export function findUnknownTomlDocumentKeys(surface, tomlData) {
+    if (!tomlData || typeof tomlData !== "object" || Array.isArray(tomlData)) {
+        return [];
+    }
+    const accepted = acceptedTomlDocumentKeys(surface);
+    return Object.keys(tomlData)
+        .filter((key) => !accepted.has(key))
+        .sort();
+}
+/**
+ * Field tables present in the file in the wrong shape — a `repeated` table
+ * written as `[configs]` instead of `[[configs]]`, or the reverse.
+ *
+ * Reported separately from an unknown key because the remedy is different: the
+ * table is recognized, its ARRAY MARKERS are wrong, and the builder would
+ * otherwise read the misshapen value as "no entries".
+ *
+ * A repeated table has to be an array OF TABLES, not merely an array: TOML
+ * accepts `configs = ["default"]` at the document root, and an element that is
+ * not a table has no keys for the per-entry unknown-key check to look at, so it
+ * used to sail through preflight and then be applied as a defaulted entry.
+ */
+/** A parsed TOML table: an object, and neither `null` nor an array. */
+function isTomlTable(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+export function findMisshapenTomlTables(surface, tomlData) {
+    if (!tomlData || typeof tomlData !== "object" || Array.isArray(tomlData)) {
+        return [];
+    }
+    const doc = tomlData;
+    const out = [];
+    for (const table of surface.tables) {
+        const key = table.tomlPath[0];
+        // Only the FIRST path segment is a document-level statement; a nested path
+        // is inside a table this loop has already accepted.
+        if (!key || table.tomlPath.length !== 1)
+            continue;
+        const value = doc[key];
+        if (value === undefined || value === null)
+            continue;
+        if (table.repeated) {
+            if (!Array.isArray(value) || !value.every(isTomlTable)) {
+                out.push({ key, expected: "array of tables" });
+            }
+        }
+        else if (Array.isArray(value) || typeof value !== "object") {
+            out.push({ key, expected: "table" });
+        }
+    }
+    return out.sort((a, b) => a.key.localeCompare(b.key));
+}
+/**
+ * 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 function recognizedResponseKeys(table, modelFields) {
+    return new Set([
+        ...modelFields,
+        ...table.fields.map((f) => f.field),
+        ...Object.keys(table.notExposed),
+        ...Object.keys(table.responseOnlyKeys),
+    ]);
+}
+/**
+ * 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 const UPDATE_PROTOCOL_KEYS = ["expectedModifiedAt"];
+/** The body keys this table accepts in `mode`, in a stable order. */
+export function requestSchemaKeys(table, mode) {
+    // Writable fields plus the `deprecated` ones, which that kind defines as
+    // still writable. `server-owned` and `secret` are excluded by construction —
+    // and a legacy slot the handler never reads off the body is `server-owned`,
+    // not `deprecated`, so it cannot slip in here (#2644 second opinion,
+    // CFG-2644-006).
+    const keys = new Set(acceptedWriteFieldNames(table, mode));
+    if (mode === "update")
+        for (const key of UPDATE_PROTOCOL_KEYS)
+            keys.add(key);
+    for (const [field, classification] of Object.entries(table.notExposed)) {
+        if (classification.kind !== "structural")
+            continue;
+        // A structural key states which modes carry it in the BODY; omitted means
+        // both. An identity that travels in the URL path or comes from the file
+        // name declares `[]` and is admitted by no schema — being structural is a
+        // statement about the TOML surface, not a licence to accept the key on the
+        // wire and drop it (#2644 second opinion, CFG-2644-005).
+        if (classification.requestModes &&
+            !classification.requestModes.includes(mode)) {
+            continue;
+        }
+        keys.add(field);
+    }
+    for (const [key, entry] of Object.entries(table.requestOnlyKeys ?? {})) {
+        // A request-only key states which modes read it; omitted means both.
+        if (!entry.modes || entry.modes.includes(mode))
+            keys.add(key);
+    }
+    return [...keys].sort();
+}
+/**
+ * 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 function configRequestSchema(table, mode) {
+    const properties = {};
+    for (const key of requestSchemaKeys(table, mode)) {
+        properties[key] = {};
+    }
+    const schema = {
+        type: "object",
+        properties,
+        additionalProperties: false,
+    };
+    rememberRetiredKeys(schema, RETIRED_CONFIG_KEYS[table.tomlPath[0]]);
+    return schema;
+}
+/**
+ * Retired-key guidance carried BESIDE a generated schema, not inside it
+ * (issue #2803, second opinion).
+ *
+ * A route that opts into runtime validation is validated before its handler
+ * runs, so a handler's targeted "`status` is server-owned, use
+ * `<noun> enable|disable`" refusal never fired for the app-API webhook and cron
+ * routes: `additionalProperties: false` answered first, with the generic
+ * "Request body validation failed". The guidance has to reach the validator.
+ *
+ * It travels in a side table rather than as a schema keyword because the schema
+ * object IS the OpenAPI `meta.request` and is held to a fail-closed keyword
+ * allowlist (`RUNTIME_SUPPORTED_SCHEMA_KEYWORDS`) — an invented keyword would
+ * be published in the spec and would fail that guard. Keying on the schema's
+ * identity also means the guidance cannot drift: it is attached by the same
+ * call that builds the key set, so a route cannot opt into one without the
+ * other.
+ */
+const retiredKeyGuidance = new WeakMap();
+function rememberRetiredKeys(schema, retired) {
+    if (!retired)
+        return;
+    const entries = {};
+    for (const [key, entry] of Object.entries(retired)) {
+        // A key the schema ACCEPTS is not retired on this surface, whatever the
+        // TOML surface says about it. The accepted key set wins, so the guidance
+        // can never shadow a live field.
+        if (key in schema.properties)
+            continue;
+        entries[key] = entry.request;
+    }
+    if (Object.keys(entries).length > 0)
+        retiredKeyGuidance.set(schema, entries);
+}
+/**
+ * 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 function retiredRequestKeys(schema) {
+    return schema ? retiredKeyGuidance.get(schema) : 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 function mergeRequestSchemas(...schemas) {
+    const properties = {};
+    for (const schema of schemas) {
+        for (const key of Object.keys(schema.properties))
+            properties[key] = {};
+    }
+    // The union's guidance is the union of its halves'. A key one table retired
+    // and another accepts is admitted by the merged key set, so `rememberRetiredKeys`
+    // drops it below.
+    const retired = {};
+    for (const schema of schemas) {
+        for (const [key, request] of Object.entries(retiredRequestKeys(schema) ?? {})) {
+            retired[key] = { request };
+        }
+    }
+    const merged = {
+        type: "object",
+        properties,
+        additionalProperties: false,
+    };
+    rememberRetiredKeys(merged, retired);
+    return merged;
+}
+/**
+ * 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 function unknownRequestKeys(body, table, mode) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return [];
+    const known = new Set(requestSchemaKeys(table, mode));
+    return Object.keys(body)
+        .filter((key) => !known.has(key))
+        .sort();
+}
+/** The 400 message naming the unknown key(s), shared by both APIs. */
+export function unknownRequestKeysMessage(keys) {
+    return (`Unrecognized request body key${keys.length === 1 ? "" : "s"}: ` +
+        `${keys.join(", ")}. This endpoint rejects keys it does not accept rather ` +
+        "than ignoring them.");
+}
+export const RETIRED_CONFIG_KEYS = {
+    // #2891 — the app-settings auth surface was reshaped so that `app.toml` can
+    // state what the server holds. All five keys below stay DECLARED in
+    // `models.yaml` (their attributes are still in DynamoDB, and the passkey pair
+    // still feeds a runtime fallback), but none is writable or echoed any more,
+    // so "removed for app developers" is achieved entirely here.
+    //
+    // Keyed under the `app` prefix because that is the app-settings surface's
+    // identifier at both consumers — the merged `PUT /settings` request schema
+    // and the `app.toml` parser — even though four of the five were authored
+    // under `[auth]`.
+    app: {
+        googleClientId: {
+            toml: "`googleClientId` is no longer authored in TOML (#2891). Google " +
+                "registers a client per platform, so the id belongs to one client: " +
+                "move it to `[auth.google.clients.<type>].clientId` (`web`, `ios`, " +
+                "`android`, `desktop` or `chrome-extension`) and delete the line.",
+            request: "`googleClientId` is retired (#2891). Send the client id inside " +
+                "`googleClients` as `[auth.google.clients.<type>].clientId`.",
+        },
+        googleClientSecret: {
+            toml: "`googleClientSecret` is no longer authored in TOML (#2891). The " +
+                "secret belongs to one Google client — and Google issues none at all " +
+                "for `ios`, `android` or `chrome-extension` — so move it to " +
+                "`[auth.google.clients.<type>].clientSecret` (still a whole " +
+                "`{{secrets.KEY}}` reference) and delete the line.",
+            request: "`googleClientSecret` is retired (#2891). Send the reference inside " +
+                "`googleClients` as `[auth.google.clients.<type>].clientSecret`; the " +
+                "`web` and `desktop` types require one and the native types reject one.",
+        },
+        redirectUris: {
+            toml: "`redirectUris` is no longer authored in TOML (#2891). A redirect URI " +
+                "belongs to the thing that redirects, and one app-wide list served " +
+                "both flows: put Google callbacks in " +
+                "`[auth.google.clients.<type>].redirectUris` and the magic-link " +
+                "allow-list in `emailRedirectUris`, then delete the line. A stored " +
+                "list may legitimately have mixed the two — split it.",
+            request: "`redirectUris` is retired (#2891). Google callbacks go in " +
+                "`googleClients` as `[auth.google.clients.<type>].redirectUris`; the " +
+                "magic-link allow-list is `emailRedirectUris`. A stored list may " +
+                "legitimately have mixed the two — split it.",
+        },
+        passkeyRpId: {
+            toml: "`passkeyRpId` is no longer authored in TOML (#2891). Passkey " +
+                "relying-party config is authored one way only: `passkeyRpConfig`, " +
+                "written as `[auth.passkeys]` with an entry per RP ID. Delete the " +
+                "line and push again.",
+            request: "`passkeyRpId` is retired (#2891). Send the relying-party config as " +
+                "`passkeyRpConfig` (`[auth.passkeys]`), which carries the per-rpId " +
+                "names.",
+        },
+        passkeyRpName: {
+            toml: "`passkeyRpName` is no longer authored in TOML (#2891). It was the " +
+                "other half of the legacy single-rpId config, superseded by " +
+                "`passkeyRpConfig`: put the name under its RP ID in `[auth.passkeys]` " +
+                "and delete the line.",
+            request: "`passkeyRpName` is retired (#2891). Send the relying-party config as " +
+                "`passkeyRpConfig` (`[auth.passkeys]`), which carries the per-rpId " +
+                "names.",
+        },
+        // #2884 — email sign-in became ONE flow, so it has ONE setting. Both keys
+        // stay DECLARED in `models.yaml` and are mirrored on every write of
+        // `emailSignInEnabled`, but neither is authorable any more: a file that
+        // still carries one is asking for a method choice that no longer exists.
+        magicLinkEnabled: {
+            toml: "`magicLinkEnabled` is no longer authored in TOML (#2884). Email " +
+                "sign-in is one flow — one request sends one email carrying a code " +
+                "and, when a link can be issued, a link — so it has one setting: " +
+                "replace this line with `emailSignInEnabled` (`false` turns email " +
+                "sign-in off entirely).",
+            request: "`magicLinkEnabled` is retired (#2884). Email sign-in has one " +
+                "setting: send `emailSignInEnabled`.",
+        },
+        otpEnabled: {
+            toml: "`otpEnabled` is no longer authored in TOML (#2884). It was the " +
+                "other half of the retired pair: one email now carries both the code " +
+                "and the link, so replace both lines with `emailSignInEnabled`.",
+            request: "`otpEnabled` is retired (#2884). Email sign-in has one setting: " +
+                "send `emailSignInEnabled`.",
+        },
+    },
+    // #2645 — pausing moved off `state` onto its own field, so `state` stopped
+    // being author-writable rather than becoming a second way to say "paused".
+    // Every pre-#2645 pull wrote the line, so existing repos hit this on their
+    // first push after upgrading: the failure is deliberate (sponsor decision at
+    // the approval gate, 2026-08-15), because the line has to be removed, not
+    // silently ignored, or the file keeps claiming a pause state push does not
+    // apply.
+    //
+    // #2907 — each of these names TWO verbs, not one. An author writing
+    // `status = "archived"` was not asking about availability: they were asking
+    // to retire the object, which is the delete flow and is spelled
+    // `primitive <noun> archive`. Answering with `enable|disable` alone sent
+    // exactly that author away with verbs that cannot do what they asked.
+    cronTrigger: {
+        state: {
+            toml: "`state` is no longer authored in TOML (#2645), and #2803 replaced it " +
+                "with the server-owned `status`. Availability is " +
+                "`primitive cron-triggers enable|disable`; retiring the trigger is " +
+                "`primitive cron-triggers archive` (#2907). Delete the line and push " +
+                "again.",
+            request: "`state` is server-owned and superseded by `status` (#2645, #2803). " +
+                "Use `primitive cron-triggers enable|disable` to change availability, " +
+                "or `primitive cron-triggers archive` to retire the trigger (#2907).",
+        },
+        status: {
+            toml: "`status` is no longer authored in TOML (#2803). Availability is " +
+                "server-owned: use `primitive cron-triggers enable|disable`. " +
+                "Retiring the trigger is `primitive cron-triggers archive` (#2907) — " +
+                "the archived row keeps its key and its slot under the per-app cap. " +
+                "Delete the line and push again.",
+            request: "`status` is server-owned (#2803). Use " +
+                "`primitive cron-triggers enable|disable` to change availability, or " +
+                "`primitive cron-triggers archive` to retire the trigger (#2907).",
+        },
+    },
+    // #2803 — the OBJECT-level availability leaves TOML. The per-version
+    // `[[configs]] status` (`active | archived`) is a different question — which
+    // named config is retired — and stays authorable.
+    prompt: {
+        status: {
+            toml: "`[prompt].status` is no longer authored in TOML (#2803). " +
+                "Availability is server-owned: use `primitive prompts enable|disable`. " +
+                "Retiring the prompt is `primitive prompts archive` (#2907). " +
+                "Delete the line and push again — the per-config `[[configs]] status` " +
+                "is unaffected.",
+            request: "`status` is server-owned (#2803). Use " +
+                "`primitive prompts enable|disable` to change availability, or " +
+                "`primitive prompts archive` to retire the prompt (#2907).",
+        },
+    },
+    integration: {
+        status: {
+            toml: "`status` is no longer authored in TOML (#2803), and `draft` no longer " +
+                "exists. Availability is server-owned: use " +
+                "`primitive integrations enable|disable`. Retiring the integration is " +
+                "`primitive integrations archive` (#2907). Delete the line and push " +
+                "again. If this file describes an ARCHIVED integration, delete the " +
+                "file instead — pull no longer exports tombstones, and the next " +
+                "confirmed `config push --prune` hard-deletes the row.",
+            request: "`status` is server-owned (#2803). Use " +
+                "`primitive integrations enable|disable` to change availability, or " +
+                "`primitive integrations archive` to retire the integration (#2907).",
+        },
+    },
+    // #2803 — availability is one server-owned `status`. As a TOML key it made
+    // `config push` a second writer: pushing a file pulled before an operator ran
+    // `webhooks disable` put the endpoint back in service as a side effect. The
+    // tenant app-API create/update also stored the value UNVALIDATED, so any app
+    // admin could write any string into the field the receiver gates on.
+    webhook: {
+        status: {
+            toml: "`status` is no longer authored in TOML (#2803). Availability is " +
+                "server-owned: use `primitive webhooks enable|disable`. Retiring the " +
+                "webhook is `primitive webhooks archive` (#2907) — the archived row " +
+                "keeps its key and its slot under the per-app cap. Delete the " +
+                "line and push again. If this file describes an ARCHIVED webhook, " +
+                "delete the file instead — pull no longer exports tombstones, and the " +
+                "next confirmed `config push --prune` hard-deletes the row, freeing " +
+                "its slot and its key.",
+            request: "`status` is server-owned (#2803). Use " +
+                "`primitive webhooks enable|disable` to change availability, or " +
+                "`primitive webhooks archive` to retire the webhook (#2907).",
+        },
+    },
+    // #2803 — availability is one server-owned `status`. As a TOML key it made
+    // `config push` a second writer: pushing a file pulled before an operator ran
+    // `workflows disable` put the workflow back in service as a side effect.
+    workflow: {
+        status: {
+            toml: "`status` is no longer authored in TOML (#2803). Availability is " +
+                "server-owned: use `primitive workflows enable|disable`. Retiring the " +
+                "workflow is `primitive workflows archive` (#2907), which keeps its " +
+                "runs and revisions resolving. Delete the line and push again.",
+            request: "`status` is server-owned (#2803). Use " +
+                "`primitive workflows enable|disable` to change availability, or " +
+                "`primitive workflows archive` to retire the workflow (#2907).",
+        },
+    },
+};
+/** The retired-key entry for `key` under `prefix`, or null when it is simply unknown. */
+export function retiredConfigKey(prefix, key) {
+    return RETIRED_CONFIG_KEYS[prefix]?.[key] ?? null;
+}
+// ── src/config-surface/workflow.ts ───────────────────────────────────────
+/**
+ * The `workflow` configuration object's definition (issue #2644, phase 1).
+ *
+ * One place records the `[workflow]` field surface: which `WorkflowDefinition`
+ * fields the server accepts on create/update, which TOML key each carries,
+ * whether `config pull` always emits it, and — for every field with real
+ * behavior — the handler that owns that behavior. `createAppWorkflow` /
+ * `updateAppWorkflow` take their accepted set from here (`pickWritableFields`),
+ * the CLI's push builder and pull serializer read the vendored copy, and the
+ * coverage guard cross-checks the whole thing against `models.yaml`.
+ *
+ * Supersedes `cli/src/lib/workflow-field-descriptor.ts` (#2326) and
+ * `WORKFLOW_PAYLOAD_FIELDS_CREATE` / `_UPDATE`
+ * (`cli/src/lib/workflow-payload.ts`, #1177), both deleted with this change.
+ */
+const HANDLERS = "src/workflows/config/workflow-field-handlers.ts";
+const handler = (name) => handledBy(HANDLERS, name);
+/**
+ * The five per-app / per-user queue limits (#1177). All share one handler: a
+ * finite non-negative number, floored.
+ */
+const QUEUE_LIMITS = [
+    "perUserMaxRunning",
+    "perUserMaxQueued",
+    "perAppMaxRunning",
+    "perAppMaxQueued",
+    "queueTtlSeconds",
+];
+const queueLimitFields = QUEUE_LIMITS.map((field) => ({
+    field,
+    tomlKey: field,
+    type: "number",
+    emit: "whenSet",
+    writableOn: BOTH,
+    validation: handler("normalizeWorkflowQueueLimit"),
+}));
+export const WORKFLOW_SURFACE = {
+    label: "workflow",
+    tables: [
+        {
+            tomlPath: ["workflow"],
+            repeated: false,
+            model: "WorkflowDefinition",
+            // Declaration order is the order `config pull` writes the keys, so it
+            // deliberately matches the pre-#2644 hand-written serializer — migrating
+            // to the definition must not reshuffle every workflow TOML file.
+            fields: [
+                {
+                    field: "name",
+                    tomlKey: "name",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handler("normalizeWorkflowName"),
+                },
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handler("normalizeWorkflowDescription"),
+                },
+                {
+                    field: "accessRule",
+                    tomlKey: "accessRule",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handler("normalizeWorkflowAccessRule"),
+                },
+                {
+                    field: "runAs",
+                    tomlKey: "runAs",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handler("normalizeWorkflowRunAs"),
+                },
+                // #1078 Tier 1b — StringSetField on the model, string array in TOML/JSON.
+                {
+                    field: "capabilities",
+                    tomlKey: "capabilities",
+                    type: "string[]",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handler("normalizeWorkflowCapabilities"),
+                },
+                ...queueLimitFields,
+                {
+                    field: "dequeueOrder",
+                    tomlKey: "dequeueOrder",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handler("normalizeWorkflowDequeueOrder"),
+                },
+                {
+                    field: "requiresClientApply",
+                    tomlKey: "requiresClientApply",
+                    type: "boolean",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handler("normalizeWorkflowOptOutFlag"),
+                },
+                // Accepted on BOTH modes — #807's deferred second PATCH is an update
+                // call. The CLI's create-only send is a sequencing invariant owned by
+                // `applyWorkflowBody`, not a statement about what the server accepts.
+                {
+                    field: "syncCallable",
+                    tomlKey: "syncCallable",
+                    type: "boolean",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handler("normalizeWorkflowSyncCallable"),
+                },
+                // JSON Schema objects. TOML may present them as an inline table OR as a
+                // JSON string; the handler owns that parse.
+                {
+                    field: "inputSchema",
+                    tomlKey: "inputSchema",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handler("normalizeWorkflowSchemaValue"),
+                },
+                {
+                    field: "outputSchema",
+                    tomlKey: "outputSchema",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handler("normalizeWorkflowSchemaValue"),
+                },
+                // #1518/#1972 — declarative run-scoped lock. `[workflow.lock]` inline
+                // table on the TOML side, JSON on the wire.
+                {
+                    field: "lock",
+                    tomlKey: "lock",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handler("normalizeWorkflowLockValue"),
+                },
+            ],
+            notExposed: {
+                workflowId: {
+                    kind: "server-owned",
+                    note: "ULID assigned on create; never author-authored.",
+                },
+                // #2803 — `status` is the ONE availability control and it is
+                // server-owned. It used to be a `[workflow]` key, which made `config
+                // push` a second writer: pushing a file pulled before an operator ran
+                // `workflows disable` put the workflow back in service as a side
+                // effect. `server-owned` keeps it out of both the TOML surface and the
+                // create/update request schemas, so the only writers are
+                // `workflows enable|disable` and create (which assigns `active`).
+                status: {
+                    kind: "server-owned",
+                    note: "Availability (#2803, #2887): active | inactive | archived. " +
+                        "Written only by `workflows enable|disable`, the delete flow (a " +
+                        "plain DELETE writes the `archived` tombstone; `?hard=true` " +
+                        "destroys), and create, which always assigns `active`. Never " +
+                        "authored in TOML: `config pull` does not emit it and a file that " +
+                        "still carries the key fails push (RETIRED_TOML_KEYS).",
+                },
+                // #2645 criterion 9 — the operational toggle. Configuration is
+                // authored in TOML and applied with `config push`, so anything this
+                // table exposes has the repo as its single writer. Taking a workflow
+                // out of service is an operation with its own single writer
+                // (`workflows disable|enable`), so this field must never appear in
+                // the `[workflow]` table: `server-owned` keeps it out of both request
+                // schemas and the TOML surface, and the coverage guard fails if it is
+                // ever moved into `fields`.
+                operationallyDisabled: {
+                    kind: "server-owned",
+                    note: "Operational toggle (#2645). Written only by the disable/enable " +
+                        "endpoints (`workflows disable|enable`); read by the dispatch " +
+                        "path. Never authored in TOML and never accepted on the config " +
+                        "create/update wire.",
+                },
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                workflowKey: {
+                    kind: "structural",
+                    // Create carries it in the body; update does not read it at all —
+                    // the URL names the workflow and the CLI checks a contradicting
+                    // TOML key locally (`workflowKeyMismatchError`).
+                    requestModes: ["create"],
+                    note: "The workflow's identity. Comes from the TOML file name / --key and " +
+                        "is attached by the caller, not spread from the [workflow] table. Its " +
+                        "TOML spelling is declared in tomlOnlyKeys as `key`.",
+                },
+                activeConfigId: {
+                    kind: "server-owned",
+                    note: "Pointer to the active WorkflowConfiguration, computed on publish.",
+                },
+                metadataManifest: {
+                    kind: "structural",
+                    note: "#1304 declared-access manifest. Travels as the top-level [metadata] / " +
+                        "secrets tables and is validated by validateManifestShape, not as a " +
+                        "[workflow] key.",
+                },
+                // The legacy revision/draft slots are `server-owned`, not `deprecated`:
+                // `deprecated` means "still WRITABLE, superseded by another field"
+                // (`types.ts`), and phase 5's generated request schemas admit every
+                // deprecated key for exactly that reason. None of these six is writable
+                // — create and update never read them off the body; the draft save path
+                // and the R2 writer assign them — so classifying them `deprecated` made
+                // the schema accept a key the handler then dropped, which is the 200-on
+                // -a-key-that-did-nothing this issue exists to end. Their models.yaml
+                // DEPRECATED marking is about the field's future, not about who writes it.
+                latestRevision: {
+                    kind: "server-owned",
+                    note: "Legacy revision pointer, marked DEPRECATED in models.yaml. " +
+                        "Written by the revision save path, never accepted on the wire.",
+                },
+                stepsR2Key: {
+                    kind: "server-owned",
+                    note: "Legacy steps pointer, marked DEPRECATED in models.yaml. Assigned " +
+                        "by the R2 write, never accepted on the wire.",
+                },
+                draftStepsR2Key: {
+                    kind: "server-owned",
+                    note: "Legacy draft steps pointer, marked DEPRECATED in models.yaml. " +
+                        "Assigned by the draft save path, never accepted on the wire.",
+                },
+                draftInputSchema: {
+                    kind: "server-owned",
+                    note: "Legacy draft slot, marked DEPRECATED in models.yaml. Written by " +
+                        "the draft save path from `inputSchema`, never accepted on the wire.",
+                },
+                draftOutputSchema: {
+                    kind: "server-owned",
+                    note: "Legacy draft slot, marked DEPRECATED in models.yaml. Written by " +
+                        "the draft save path from `outputSchema`, never accepted on the wire.",
+                },
+                draftModifiedAt: {
+                    kind: "server-owned",
+                    note: "Legacy draft timestamp, marked DEPRECATED in models.yaml. Stamped " +
+                        "by the draft save path, never accepted on the wire.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "Admin who created the workflow; assigned server-side.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {
+                key: {
+                    kind: "structural",
+                    note: "The workflow key. `config pull` writes it for readability; push takes " +
+                        "the identity from the file name and attaches `workflowKey` itself.",
+                },
+                activeConfigName: {
+                    kind: "structural",
+                    note: "Names which [[configs]] entry is active. Consumed by the push apply " +
+                        "path (which activates the matching config by id), not sent as a " +
+                        "[workflow] field.",
+                },
+            },
+            requestOnlyKeys: {
+                steps: {
+                    // CREATE only: `updateAppWorkflow` never reads `steps` off the body —
+                    // an update writes them through the workflow-config / draft
+                    // endpoints (`applyWorkflowBody`) — so a PATCH carrying steps used to
+                    // return 200 having saved none of them.
+                    modes: CREATE_ONLY,
+                    note: "The workflow's step list. Not a `WorkflowDefinition` field — it " +
+                        "lives on the active WorkflowConfiguration (and in R2) — but the " +
+                        "create call carries it in the same body so a new workflow lands " +
+                        "with its steps in one request. Validated by the step allowlist " +
+                        "(`cli/src/lib/generated-allowlist.ts`, #998) and the server's " +
+                        "definition validation.",
+                },
+                expressions: {
+                    // CREATE only, for the same reason as `steps`: they travel on the
+                    // steps payload, which an update writes through its own endpoint.
+                    modes: CREATE_ONLY,
+                    note: "#1614 — the named `expr.*` definitions, which travel on the same " +
+                        "steps payload rather than as a definition field.",
+                },
+            },
+            responseOnlyKeys: {
+                platformOwned: {
+                    kind: "server-owned",
+                    note: "#1660 — derived flag marking a reserved `__internal.` workflow. " +
+                        "Computed at serialize time; not persisted, never writable.",
+                },
+            },
+        },
+    ],
+    tomlDocumentKeys: {
+        steps: {
+            kind: "structural",
+            note: "The `[[steps]]` array. Validated by the step allowlist " +
+                "(`cli/src/lib/generated-allowlist.ts`, #998) and the server's " +
+                "definition validation; its shape is checked by validateWorkflowToml.",
+        },
+        configs: {
+            kind: "structural",
+            note: "RETIRED as an inline list (#2645): named configurations are authored " +
+                "one per file at `workflows/<key>.configs/<name>.toml` and selected by " +
+                "`[workflow].activeConfigName`. Pull writes the sidecars, push applies " +
+                "them through the workflow-config endpoints, and a file still carrying " +
+                "`[[configs]]` fails validation (validateWorkflowToml) rather than " +
+                "having the list quietly ignored. Declared here so the document-shape " +
+                "check defers to that targeted message.",
+        },
+        ...DECLARED_ACCESS_MANIFEST_KEYS,
+        expr: {
+            kind: "structural",
+            note: "#1614 — the named `[expr.cel]` guard definitions, which travel on the " +
+                "steps payload (parseWorkflowExpressionsToml).",
+        },
+        include: {
+            kind: "structural",
+            note: "Workflow fragments (`include = [\"name\"]` or repeated `[[include]]` " +
+                "tables), expanded into `steps` by expandWorkflowTomlData before push.",
+        },
+    },
+};
+// ── src/config-surface/prompt.ts ─────────────────────────────────────────
+/**
+ * The `prompt` configuration object's definition (issue #2644, phase 2).
+ *
+ * `prompts/<key>.toml` carries TWO field tables: the `[prompt]` table backed by
+ * `AppPrompt`, and the repeated `[[configs]]` table backed by `AppPromptConfig`
+ * — one entry per named LLM configuration. Both are declared here, so a field
+ * added to either model is covered by the same guard.
+ *
+ * The `[[configs]]` entries are the reason prompts have two tables rather than
+ * a `structural` note: they are a real field surface the CLI pushes
+ * (`createPromptConfig` / `updatePromptConfig`) and pulls, not an opaque blob.
+ */
+const PROMPT_HANDLER = "src/admin-api.ts";
+export const PROMPT_SURFACE = {
+    label: "prompt",
+    tables: [
+        {
+            tomlPath: ["prompt"],
+            repeated: false,
+            model: "AppPrompt",
+            // Declaration order reproduces the pre-#2644 serializer's key order.
+            fields: [
+                {
+                    field: "displayName",
+                    tomlKey: "displayName",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                // JSON Schema objects. Stored as JSON strings, returned parsed; TOML
+                // may present them as an inline table or a JSON string.
+                {
+                    field: "inputSchema",
+                    tomlKey: "inputSchema",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                },
+                // #2644 — accepted by both handlers and returned by the detail, but
+                // never written to TOML before this: a prompt's declared output shape
+                // was invisible to config-as-code.
+                {
+                    field: "outputSchema",
+                    tomlKey: "outputSchema",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                },
+                // #2652 — the CEL rule gating who may execute the prompt. Required at
+                // create; an explicit null/"" on update clears it (fail-closed). This
+                // declaration is the whole authoring channel: the admin routes' unknown
+                // key guard reads the same table, so it is what makes `accessRule` an
+                // accepted body key as well as a pulled and pushed TOML line.
+                {
+                    field: "accessRule",
+                    tomlKey: "accessRule",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                },
+            ],
+            notExposed: {
+                promptId: {
+                    kind: "server-owned",
+                    note: "ULID assigned on create; never author-authored.",
+                },
+                // #2803 — the OBJECT-level availability, server-owned. Distinct from
+                // the per-version `[[configs]] status` below, which stays a TOML key:
+                // that says which named config is retired, this says whether the
+                // prompt is in service at all.
+                status: {
+                    kind: "server-owned",
+                    note: "Availability (#2803, #2887): active | inactive | archived. " +
+                        "Written only by `prompts enable|disable`, the delete flow (a " +
+                        "plain DELETE writes the `archived` tombstone; `?hard=true` " +
+                        "destroys), and create, which always assigns `active`. Never " +
+                        "authored in TOML; the per-version `[[configs]] status` is " +
+                        "unaffected.",
+                },
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                promptKey: {
+                    kind: "structural",
+                    // Create carries it in the body; update does not read it at all
+                    // (`updateAppPrompt` — the URL names the prompt), so accepting it
+                    // there would 200 a rename that changed nothing.
+                    requestModes: ["create"],
+                    note: "The prompt's identity. Comes from the TOML file name and is " +
+                        "attached by the caller, not spread from the [prompt] table. Its " +
+                        "TOML spelling is declared in tomlOnlyKeys as `key`.",
+                },
+                copiedFromCatalogId: {
+                    kind: "server-owned",
+                    note: "Provenance stamp written when a prompt is copied from the catalog.",
+                },
+                activeConfigId: {
+                    kind: "server-owned",
+                    note: "Pointer to the active AppPromptConfig. Activation is its own " +
+                        "endpoint (activatePromptConfig), not a [prompt] key.",
+                },
+                defaultEvaluatorPromptId: {
+                    kind: "server-owned",
+                    note: "Link to the evaluator prompt, written when an evaluator is created " +
+                        "against this prompt. Managed through the prompts API, not TOML.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "Admin who created the prompt; assigned server-side.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+            },
+            requestOnlyKeys: {
+                defaultEvaluatorPromptId: {
+                    note: "Writable through the prompts API (the console links an evaluator " +
+                        "prompt) but never through TOML, which is why it is classified " +
+                        "`server-owned` for the sync surface and named here for the request " +
+                        "surface. Sending it is accepted; sync never does.",
+                },
+            },
+            tomlOnlyKeys: {
+                key: {
+                    kind: "structural",
+                    note: "The prompt key. `config pull` writes it for readability; push takes " +
+                        "the identity from the file name and attaches `promptKey` itself.",
+                },
+            },
+            responseOnlyKeys: {
+                configs: {
+                    kind: "structural",
+                    note: "The prompt's AppPromptConfig rows, returned inline on the detail " +
+                        "and written as the repeated [[configs]] table below.",
+                },
+            },
+        },
+        {
+            tomlPath: ["configs"],
+            repeated: true,
+            model: "AppPromptConfig",
+            fields: [
+                {
+                    field: "configName",
+                    tomlKey: "name",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Renamable on update, uniqueness-checked within the prompt.
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                },
+                // #2645 — a config's status is configuration: `prompts configs update
+                // --status archived` used to be the only way to retire one, and pull
+                // emitted nothing, so the file could not say which of its configs the
+                // server still runs. Update-only: create hard-codes "active" and
+                // ignores a supplied status, same statement `writableOn` makes for
+                // every create-assigned field.
+                {
+                    field: "status",
+                    tomlKey: "status",
+                    type: "string",
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                },
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "provider",
+                    tomlKey: "provider",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // openrouter | gemini, lower-cased and cross-checked against the model.
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                },
+                {
+                    field: "model",
+                    tomlKey: "model",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                },
+                {
+                    field: "systemPrompt",
+                    tomlKey: "systemPrompt",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    // Offloaded to R2 above the inline size limit and read back
+                    // transparently, so the TOML value is the whole prompt either way.
+                    validation: handledBy("src/services/large-field-storage.ts", "storeField"),
+                },
+                {
+                    field: "userPromptTemplate",
+                    tomlKey: "userPromptTemplate",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy("src/services/large-field-storage.ts", "storeField"),
+                },
+                {
+                    field: "temperature",
+                    tomlKey: "temperature",
+                    type: "number",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    // Stored as a string on the model, returned parsed as a number.
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                    dualEncoded: {
+                        note: "#2869 — a `StringField` on the model: the server stores what it " +
+                            "is given and returns `parseFloat` of it, so `temperature = " +
+                            '"0.2"` and `temperature = 0.2` are one value. Both spellings ' +
+                            "compare equal; neither is a validation error.",
+                    },
+                },
+                // #2644 — accepted by both handlers, returned by the detail, and never
+                // written to TOML before this.
+                {
+                    field: "topP",
+                    tomlKey: "topP",
+                    type: "number",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                    dualEncoded: {
+                        note: "#2869 — a `StringField` returned parsed, exactly as `temperature`.",
+                    },
+                },
+                {
+                    field: "maxTokens",
+                    tomlKey: "maxTokens",
+                    type: "number",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "outputFormat",
+                    tomlKey: "outputFormat",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                // #2644 — the per-config structured-output schema and provider options.
+                // Both are accepted by the config endpoints and were invisible to sync.
+                {
+                    field: "outputSchema",
+                    tomlKey: "outputSchema",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                },
+                {
+                    field: "providerConfig",
+                    tomlKey: "providerConfig",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                },
+            ],
+            notExposed: {
+                configId: {
+                    kind: "server-owned",
+                    note: "ULID assigned on create; never author-authored.",
+                },
+                promptId: {
+                    kind: "server-owned",
+                    note: "Parent pointer, taken from the route; never on the wire.",
+                },
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                promptIdConfigName: {
+                    kind: "server-owned",
+                    note: "Composite uniqueness key derived from promptId + configName.",
+                },
+                systemPromptR2Key: {
+                    kind: "server-owned",
+                    note: "Where an oversized systemPrompt was offloaded. Assigned by " +
+                        "storeField; the value itself round-trips through `systemPrompt`.",
+                },
+                userPromptTemplateR2Key: {
+                    kind: "server-owned",
+                    note: "Where an oversized userPromptTemplate was offloaded. Assigned by " +
+                        "storeField; the value round-trips through `userPromptTemplate`.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "Admin who created the config; assigned server-side.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {
+                // #2645 — the live-config marker. Exactly one [[configs]] entry may
+                // carry `active = true`; pull writes it on the active entry and push
+                // honors it on create AND update by calling the activate endpoint
+                // (activatePromptConfig). It is a control, never a key in the config
+                // body.
+                active: {
+                    kind: "structural",
+                    note: "Which config the prompt runs (#2645). Pull writes it on the " +
+                        "active entry; push enacts it through the activate endpoint " +
+                        "(activatePromptConfig), never as a config-body key.",
+                },
+                isActive: {
+                    kind: "structural",
+                    note: "Legacy spelling of `active` — the create leg read it before pull " +
+                        "ever wrote a marker. Declared here so the unrecognized-key " +
+                        "rejection does not fail a file that has always used it; pull " +
+                        "never writes it.",
+                },
+            },
+            responseOnlyKeys: {},
+        },
+    ],
+    // Both of a prompt file's tables ARE field tables (`[prompt]` and the
+    // repeated `[[configs]]`), so there is no third top-level channel. The
+    // sidecar test cases live in `prompts/<key>.tests/` — their own surface.
+    tomlDocumentKeys: {},
+};
+// ── src/config-surface/integration.ts ────────────────────────────────────
+/**
+ * The `integration` configuration object's definition (issue #2644, phase 2).
+ *
+ * `integrations/<key>.toml` carries one `[integration]` field table plus the
+ * top-level `[requestConfig]` table, which is authored structure with its own
+ * validator (`serializeRequestConfig`) and is therefore declared `structural`
+ * rather than re-modelled here.
+ *
+ * ── On the `validation` classifications ──────────────────────────────────
+ * Phase 1 decomposed the workflow handler into one exported normalizer per
+ * field. `createAppIntegration` / `updateAppIntegration` are not decomposed yet,
+ * so a field with real behavior names the module and export that owns it TODAY
+ * (`src/admin-api.ts#AdminAPI`, or the shared helper where one already exists).
+ * The classification is what makes the field visible to every guard; splitting
+ * those handlers up is a later phase's job, not a reason to leave the field
+ * undeclared.
+ */
+const INTEGRATION_HANDLER = "src/admin-api.ts";
+export const INTEGRATION_SURFACE = {
+    label: "integration",
+    tables: [
+        {
+            tomlPath: ["integration"],
+            repeated: false,
+            model: "AppIntegration",
+            // Declaration order is the order `config pull` writes the keys — it matches
+            // the pre-#2644 hand-written serializer so migrating does not reshuffle
+            // every existing integrations/*.toml.
+            fields: [
+                {
+                    field: "displayName",
+                    tomlKey: "displayName",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "timeoutMs",
+                    tomlKey: "timeoutMs",
+                    type: "number",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handledBy(INTEGRATION_HANDLER, "AdminAPI"),
+                    // `src/admin-api.ts` createAppIntegration: a create with no
+                    // `timeoutMs` stores 300000. Recorded so a hand-authored file that
+                    // omits the key compares (and pushes) as the value the server holds
+                    // rather than diffing `Modified` forever (#2880 DSO-002).
+                    serverDefault: 300000,
+                },
+                // #2644 — accepted by both handlers and returned on the detail, but
+                // never written to TOML before this. Declaring it is what makes it
+                // authorable; leaving it out would be the silent gap this epic closes.
+                {
+                    field: "maxRequestBodyBytes",
+                    tomlKey: "maxRequestBodyBytes",
+                    type: "number",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(INTEGRATION_HANDLER, "AdminAPI"),
+                    // Same create default, same reason (#2880 DSO-002): 1 MiB.
+                    serverDefault: 1048576,
+                },
+                // #2631 — the CEL rule gating who may invoke the integration. Required
+                // at create; an explicit null/"" on update clears it (fail-closed).
+                {
+                    field: "accessRule",
+                    tomlKey: "accessRule",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(INTEGRATION_HANDLER, "AdminAPI"),
+                },
+            ],
+            notExposed: {
+                integrationId: {
+                    kind: "server-owned",
+                    note: "ULID assigned on create; never author-authored.",
+                },
+                // #2803 — availability, server-owned. `draft` is gone from the model;
+                // a stored one reads `inactive` through the canonical normalizer.
+                status: {
+                    kind: "server-owned",
+                    note: "Availability (#2803): active | inactive | archived. Written only " +
+                        "by `integrations enable|disable`, by the delete flow's tombstone, " +
+                        "and by create, which always assigns `active`. Never authored in " +
+                        "TOML: pull does not emit it and pull skips archived rows.",
+                },
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                integrationKey: {
+                    kind: "structural",
+                    // Both modes on purpose. Update ignores the key (`updateAppIntegration`
+                    // takes the target from the URL), but every shipped `config push`
+                    // attaches it to the update body — criterion 9's breaking change is
+                    // for stray keys, not for the normal request of the CLI in the field.
+                    requestModes: ["create", "update"],
+                    note: "The integration's identity. Comes from the TOML file name and is " +
+                        "attached by the caller, not spread from the [integration] table. " +
+                        "Its TOML spelling is declared in tomlOnlyKeys as `key`.",
+                },
+                requestConfig: {
+                    kind: "structural",
+                    note: "The upstream request definition. Authored as the top-level " +
+                        "[requestConfig] table and validated by serializeRequestConfig " +
+                        "(src/services/integration-utils.ts), not as an [integration] key.",
+                },
+                activeConfigId: {
+                    kind: "server-owned",
+                    note: "#1183 — pointer to the active versioned config, set on publish.",
+                },
+                copiedFromCatalogId: {
+                    kind: "server-owned",
+                    note: "Provenance stamp written when an integration is copied from the catalog.",
+                },
+                lastTestedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp of the last test invocation; written by the test endpoint.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "Admin who created the integration; assigned server-side.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {
+                key: {
+                    kind: "structural",
+                    note: "The integration key. `config pull` writes it for readability; push " +
+                        "takes the identity from the file name and attaches " +
+                        "`integrationKey` itself.",
+                },
+            },
+            responseOnlyKeys: {},
+        },
+    ],
+    tomlDocumentKeys: {
+        requestConfig: {
+            kind: "structural",
+            note: "The upstream request definition (method, url, headers, body). " +
+                "Authored as its own top-level table and stored as the integration's " +
+                "`requestConfig`; the server validates its shape.",
+        },
+    },
+};
+// ── src/config-surface/webhook.ts ────────────────────────────────────────
+/**
+ * The `webhook` configuration object's definition (issue #2644, phase 2).
+ *
+ * `webhooks/<key>.toml` carries one `[webhook]` field table plus four authored
+ * structures with their own channels — `[verification.<scheme>]` (the stored
+ * `config` blob), `[allowedIps]`, `[inputMapping]` and `[metadata]`. Each is
+ * declared `structural` here with the code that owns it named, so the reason is
+ * visible rather than implied by absence.
+ *
+ * ── Secret-adjacent fields ───────────────────────────────────────────────
+ * `signingSecret` is EXPOSED with a reference-only contract (#2254): the server
+ * returns a whole `{{secrets.KEY}}` reference or `null` and never the
+ * credential, which is exactly what makes `config pull` → `config push` lossless
+ * (#1235). `previousSigningSecret` is `notExposed: secret` — a rotation slot the
+ * author does not write. The derived `signingSecretStatus` / `…Health` keys are
+ * response-only. The coverage guard fails on a bare omission of any of these
+ * (`/secret|token|password|credential/i`), so none of it can be decided by
+ * silence.
+ *
+ * On the `validation` classifications: `createAppWebhook` / `updateAppWebhook`
+ * are not decomposed into per-field handlers, so a field names the shared
+ * validator that owns it where one exists, and `src/admin-api.ts#AdminAPI`
+ * otherwise.
+ */
+const WEBHOOK_HANDLER = "src/admin-api.ts";
+const WEBHOOK_CONFIG_VALIDATION = "src/app-api/services/webhook-verification/config-validation.ts";
+export const WEBHOOK_SURFACE = {
+    label: "webhook",
+    tables: [
+        {
+            tomlPath: ["webhook"],
+            repeated: false,
+            model: "AppWebhook",
+            // Declaration order reproduces the pre-#2644 serializer's key order.
+            fields: [
+                {
+                    field: "displayName",
+                    tomlKey: "displayName",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "workflowKey",
+                    tomlKey: "workflowKey",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "verificationScheme",
+                    tomlKey: "verificationScheme",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handledBy(WEBHOOK_HANDLER, "AdminAPI"),
+                },
+                {
+                    field: "toleranceSeconds",
+                    tomlKey: "toleranceSeconds",
+                    type: "number",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handledBy(WEBHOOK_CONFIG_VALIDATION, "validateReplayProtection"),
+                },
+                {
+                    field: "deduplicationEnabled",
+                    tomlKey: "deduplicationEnabled",
+                    type: "boolean",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handledBy(WEBHOOK_CONFIG_VALIDATION, "validateReplayProtection"),
+                },
+                {
+                    field: "deduplicationWindowMs",
+                    tomlKey: "deduplicationWindowMs",
+                    type: "number",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handledBy(WEBHOOK_CONFIG_VALIDATION, "validateReplayProtection"),
+                },
+                // Per-webhook inbound body cap. Unset means the platform default
+                // (5 MiB), so it is omitted from TOML rather than written as a zero.
+                {
+                    field: "maxBodyBytes",
+                    tomlKey: "maxBodyBytes",
+                    type: "number",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(WEBHOOK_CONFIG_VALIDATION, "validateMaxBodyBytes"),
+                },
+                {
+                    field: "secretGracePeriodMs",
+                    tomlKey: "secretGracePeriodMs",
+                    type: "number",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handledBy(WEBHOOK_CONFIG_VALIDATION, "normalizeSecretGracePeriodMs"),
+                },
+                // #2254 — reference-only: a whole `{{secrets.KEY}}` reference naming an
+                // existing app secret, and nothing else. The server never returns
+                // credential material here, so the reference round-trips verbatim
+                // (#1235) and a legacy literal is withheld (no line is written).
+                {
+                    field: "signingSecret",
+                    tomlKey: "signingSecret",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(WEBHOOK_CONFIG_VALIDATION, "validateWholeSecretReference"),
+                },
+            ],
+            notExposed: {
+                webhookId: {
+                    kind: "server-owned",
+                    note: "ULID assigned on create; never author-authored.",
+                },
+                // #2803 — availability is server-owned. As a `[webhook]` key it made
+                // `config push` a second writer: a file pulled before an operator
+                // paused the webhook put the endpoint back in service on the next
+                // push. `server-owned` keeps it out of the TOML surface AND out of the
+                // create/update request schemas, closing the tenant app-API path that
+                // stored `body.status` unvalidated.
+                status: {
+                    kind: "server-owned",
+                    note: "Availability (#2803): active | inactive | archived. Written only " +
+                        "by `webhooks enable|disable` and by the delete flow's tombstone. " +
+                        "Never authored in TOML: pull does not emit it, pull skips " +
+                        "archived rows entirely, and a file carrying the key fails push.",
+                },
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                webhookKey: {
+                    kind: "structural",
+                    // Both modes: the update handlers ignore it, but the shipped CLI
+                    // attaches it to every webhook update body (see integration.ts).
+                    requestModes: ["create", "update"],
+                    note: "The webhook's identity. Comes from the TOML file name and is " +
+                        "attached by the caller, not spread from the [webhook] table. Its " +
+                        "TOML spelling is declared in tomlOnlyKeys as `key`.",
+                },
+                workflowId: {
+                    kind: "server-owned",
+                    note: "Resolved from `workflowKey` server-side; the author writes the key.",
+                },
+                previousSigningSecret: {
+                    kind: "secret",
+                    note: "#2383 rotation slot. Written by the rotate endpoint, never by an " +
+                        "author, and reported through the derived signingSecretStatus " +
+                        "fields rather than as a TOML key.",
+                },
+                secretRotatedAt: {
+                    kind: "server-owned",
+                    note: "Stamped by the rotate endpoint; reported, never authored.",
+                },
+                config: {
+                    kind: "structural",
+                    note: "Per-scheme verification settings. Authored as the top-level " +
+                        "[verification.<scheme>] table and converted by " +
+                        "webhookConfigToTomlTable / tomlTableToWebhookConfig, whose stored " +
+                        "shape differs per scheme (#2109), not as a [webhook] key.",
+                },
+                allowedIpCidrs: {
+                    kind: "structural",
+                    note: "Authored as the top-level [allowedIps] table (`cidrs = [...]`) and " +
+                        "stored as a JSON string, not as a [webhook] key.",
+                },
+                inputMapping: {
+                    kind: "structural",
+                    note: "Authored as the top-level [inputMapping] table and stored as a " +
+                        "JSON string, not as a [webhook] key.",
+                },
+                metadata: {
+                    kind: "structural",
+                    note: "Authored as the top-level [metadata] table and stored as a JSON " +
+                        "string, not as a [webhook] key.",
+                },
+                handshakeRules: {
+                    kind: "structural",
+                    note: "Provider handshake/challenge rules, validated by " +
+                        "src/app-api/services/webhook-handshake.ts. Accepted by the admin " +
+                        "API but not part of the TOML surface — `config push` never sends it, " +
+                        "so the stored value is left alone rather than cleared.",
+                },
+                lastTriggeredAt: {
+                    kind: "server-owned",
+                    note: "Stamped by the receiver on delivery; reported, never authored.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "User who created the webhook; assigned server-side.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {
+                key: {
+                    kind: "structural",
+                    note: "The webhook key. `config pull` writes it for readability; push takes " +
+                        "the identity from the file name and attaches `webhookKey` itself.",
+                },
+            },
+            responseOnlyKeys: {
+                signingSecretStatus: {
+                    kind: "server-owned",
+                    note: "#2254 — derived disclosure state of the stored secret (reference / " +
+                        "withheld literal / unset). Computed at serialize time; read-only.",
+                },
+                previousSigningSecretStatus: {
+                    kind: "server-owned",
+                    note: "Same derivation for the rotation slot. Read-only.",
+                },
+                signingSecretHealth: {
+                    kind: "server-owned",
+                    note: "#2383 — derived health report on the stored secret. Read-only.",
+                },
+                previousSigningSecretHealth: {
+                    kind: "server-owned",
+                    note: "Same report for the rotation slot. Read-only.",
+                },
+            },
+        },
+    ],
+    tomlDocumentKeys: {
+        verification: {
+            kind: "structural",
+            note: "The `[verification.<scheme>]` table carrying the scheme's settings " +
+                "(#2109). Converted to/from the stored `config` blob by " +
+                "webhookConfigToTomlTable / tomlTableToWebhookConfig.",
+        },
+        allowedIps: {
+            kind: "structural",
+            note: "`[allowedIps] cidrs = [...]` — the source allow-list, stored as the " +
+                "JSON string `allowedIpCidrs`.",
+        },
+        inputMapping: {
+            kind: "structural",
+            note: "The authored payload mapping, stored as the JSON string " +
+                "`inputMapping`; a table rather than a [webhook] key so it can nest.",
+        },
+        metadata: {
+            kind: "structural",
+            note: "The webhook's authored metadata table, stored as the JSON string " +
+                "`metadata`. Unrelated to the declared-access manifest of the type " +
+                "configs, which spells `[metadata]` the same way.",
+        },
+    },
+};
+// ── src/config-surface/cron-trigger.ts ───────────────────────────────────
+/**
+ * The `cron-trigger` configuration object's definition (issue #2644, phase 2).
+ *
+ * `cron-triggers/<key>.toml` carries one `[cronTrigger]` field table plus the
+ * top-level `[rootInput]` and `[inputMapping]` tables, which are authored JSON
+ * structures with their own normalizer and are declared `structural`.
+ *
+ * `state` is classified `structural` (update-only), not a field (#2645):
+ * pausing moved onto the `operationallyDisabled` toggle written by
+ * `cron-triggers pause|resume`, so `state` left the TOML surface — pull does
+ * not emit it, and push REJECTS a file that still carries the line (with
+ * guidance naming the pause verbs; see `RETIRED_TOML_KEYS` in the CLI's
+ * `commands/sync.ts`) — while the update handler keeps reading it for the
+ * console.
+ */
+const CRON_TRIGGER_HANDLER = "src/app-api/controllers/cron-triggers-controller.ts";
+export const CRON_TRIGGER_SURFACE = {
+    label: "cron-trigger",
+    tables: [
+        {
+            tomlPath: ["cronTrigger"],
+            repeated: false,
+            model: "CronTrigger",
+            // Declaration order reproduces the pre-#2644 serializer's key order.
+            fields: [
+                {
+                    field: "displayName",
+                    tomlKey: "displayName",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "cron",
+                    tomlKey: "cron",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handledBy("src/cron-parser.ts", "parseCron"),
+                },
+                {
+                    field: "timezone",
+                    tomlKey: "timezone",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Validated against Intl; unset reads as "UTC".
+                    validation: handledBy(CRON_TRIGGER_HANDLER, "CronTriggersController"),
+                    // `cron-triggers-controller.ts` stores `timezone || "UTC"`, so a file
+                    // that omits the key describes a trigger running in UTC — compared
+                    // and pushed as that, rather than as a difference no push can clear
+                    // (#2880 DSO-002).
+                    serverDefault: "UTC",
+                },
+                {
+                    field: "workflowKey",
+                    tomlKey: "workflowKey",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // #1002 — a reserved `__internal.` key is rejected at save time.
+                    validation: handledBy(CRON_TRIGGER_HANDLER, "CronTriggersController"),
+                },
+                {
+                    field: "overlapPolicy",
+                    tomlKey: "overlapPolicy",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // skip | allow.
+                    validation: handledBy(CRON_TRIGGER_HANDLER, "CronTriggersController"),
+                    // Same store-time default as `timezone` (#2880 DSO-002).
+                    serverDefault: "skip",
+                },
+            ],
+            notExposed: {
+                // #2803 — the ONE availability control, server-owned. Written only by
+                // `cron-triggers enable|disable`, the delete flow (the `archived`
+                // tombstone) and the alarm's error-pause path. `server-owned` keeps it
+                // out of both the TOML surface and the create/update request schemas,
+                // so no configuration write can change availability as a side effect.
+                status: {
+                    kind: "server-owned",
+                    note: "Availability (#2803): active | inactive | archived. Written only " +
+                        "by `cron-triggers enable|disable`, the delete flow and the " +
+                        "error-pause path. Never authored in TOML: pull does not emit it " +
+                        "and a file that still carries the key fails push.",
+                },
+                // #2645 criterion 9 moved pausing off `state`; #2803 retired the field
+                // entirely. It mixed lifecycle (`archived`, `error_paused`) with
+                // availability (`paused`), which is what made two writers possible in
+                // the first place. `server-owned` now, not `structural` with an
+                // update-only mode: the console's carve-out is gone with it, so the
+                // generic update rejects a supplied `state` exactly as create always
+                // did.
+                state: {
+                    kind: "server-owned",
+                    note: "DEPRECATED (#2803), superseded by `status`. Read only by " +
+                        "`canonicalCronStatus()`; normalized back to `active` by " +
+                        "`cron-triggers enable`. Never authored in TOML and never accepted " +
+                        "on the wire.",
+                },
+                operationallyDisabled: {
+                    kind: "server-owned",
+                    note: "DEPRECATED (#2803), superseded by `status`. The #2645 operational " +
+                        "toggle, cleared by `cron-triggers enable|disable` as rows are " +
+                        "touched. Never authored in TOML and never accepted on the config " +
+                        "create/update wire.",
+                },
+                triggerId: {
+                    kind: "server-owned",
+                    note: "ULID assigned on create; never author-authored.",
+                },
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                triggerKey: {
+                    kind: "structural",
+                    // Both modes: the update handler ignores it, but the shipped CLI
+                    // attaches it to every cron-trigger update body (see integration.ts).
+                    requestModes: ["create", "update"],
+                    note: "The trigger's identity. Comes from the TOML file name and is " +
+                        "attached by the caller, not spread from the [cronTrigger] table. " +
+                        "Its TOML spelling is declared in tomlOnlyKeys as `key`.",
+                },
+                rootInput: {
+                    kind: "structural",
+                    note: "Authored as the top-level [rootInput] table and stored as a JSON " +
+                        "string (normalizeJsonString), not as a [cronTrigger] key.",
+                },
+                inputMapping: {
+                    kind: "structural",
+                    note: "Authored as the top-level [inputMapping] table and stored as a " +
+                        "JSON string (normalizeJsonString), not as a [cronTrigger] key.",
+                },
+                lastError: {
+                    kind: "server-owned",
+                    note: "Last fire failure, written by the trigger DO and cleared on resume.",
+                },
+                lastTriggeredAt: {
+                    kind: "server-owned",
+                    note: "Stamped on fire; reported, never authored.",
+                },
+                lastTriggeredRunId: {
+                    kind: "server-owned",
+                    note: "Run started by the last fire; reported, never authored.",
+                },
+                skippedCount: {
+                    kind: "server-owned",
+                    note: "Runtime counter maintained by the trigger DO.",
+                },
+                firedCount: {
+                    kind: "server-owned",
+                    note: "Runtime counter maintained by the trigger DO.",
+                },
+                consecutiveNotActiveCount: {
+                    kind: "server-owned",
+                    note: "Runtime counter behind the auto-pause rule; DO-maintained.",
+                },
+                nextFireAt: {
+                    kind: "server-owned",
+                    note: "Projected next fire, computed from the schedule by the DO.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "User who created the trigger; assigned server-side.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+            },
+            requestOnlyKeys: {
+                key: {
+                    // CREATE only: `update` never reads it — the trigger is addressed by
+                    // id in the path, and its key is immutable — so a `key` sent on
+                    // update is a 400 rather than a silently ignored rename.
+                    modes: CREATE_ONLY,
+                    note: "Alias for `triggerKey` on create, accepted by the controller " +
+                        "(`triggerKey || key`) since before sync existed. Declared so the " +
+                        "generated request schema keeps accepting a client that uses it.",
+                },
+                name: {
+                    note: "Alias for `displayName`, accepted on create and update " +
+                        "(`displayName ?? name`). Same reason as `key`.",
+                },
+            },
+            tomlOnlyKeys: {
+                key: {
+                    kind: "structural",
+                    note: "The trigger key. `config pull` writes it for readability; push takes " +
+                        "the identity from the file name and attaches `triggerKey` itself.",
+                },
+            },
+            responseOnlyKeys: {
+                runtime: {
+                    kind: "server-owned",
+                    note: "DO-derived schedule status (`scheduledAlarm` / `scheduledAlarmAt`) " +
+                        "attached to the detail response. Computed, never persisted here.",
+                },
+            },
+        },
+    ],
+    tomlDocumentKeys: {
+        rootInput: {
+            kind: "structural",
+            note: "The authored root input for each fire, stored as the JSON string " +
+                "`rootInput` (normalizeJsonString).",
+        },
+        inputMapping: {
+            kind: "structural",
+            note: "The authored input mapping, stored as the JSON string `inputMapping` " +
+                "(normalizeJsonString).",
+        },
+    },
+};
+// ── src/config-surface/blob-bucket.ts ────────────────────────────────────
+/**
+ * The `blob-bucket` configuration object's definition (issue #2644, phase 2).
+ *
+ * `blob-buckets/<key>.toml` carries a single `[bucket]` table.
+ *
+ * `ttlTier` is `writableOn: ["create"]`: the update handler does not read it, so
+ * the retention tier is fixed at creation. `preset` and `ruleSetId` are the two
+ * halves of the access model (#1020) — at most one may change per request, which
+ * is the controller's rule and stays there.
+ */
+const BLOB_BUCKET_HANDLER = "src/app-api/controllers/blob-buckets-controller.ts";
+export const BLOB_BUCKET_SURFACE = {
+    label: "blob-bucket",
+    tables: [
+        {
+            tomlPath: ["bucket"],
+            repeated: false,
+            model: "BlobBucket",
+            // Declaration order reproduces the pre-#2644 serializer's key order.
+            fields: [
+                {
+                    field: "name",
+                    tomlKey: "name",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "ttlTier",
+                    tomlKey: "ttlTier",
+                    type: "string",
+                    emit: "always",
+                    writableOn: CREATE_ONLY,
+                    // Immutable after create: `update` never reads it.
+                    validation: handledBy(BLOB_BUCKET_HANDLER, "BlobBucketsController"),
+                },
+                {
+                    field: "preset",
+                    tomlKey: "preset",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    // #1020 — the honest access field. A rule-set-backed bucket reports
+                    // "custom", which is not written back as a preset.
+                    validation: handledBy("src/app-api/resource-types/blob-bucket.ts", "resolveBucketPreset"),
+                },
+                {
+                    field: "ruleSetId",
+                    tomlKey: "ruleSetId",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    // Existence-checked against AccessRuleSet; mutually exclusive with a
+                    // preset change in the same request.
+                    validation: handledBy(BLOB_BUCKET_HANDLER, "BlobBucketsController"),
+                },
+            ],
+            notExposed: {
+                bucketId: {
+                    kind: "server-owned",
+                    note: "ULID assigned on create; never author-authored.",
+                },
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                bucketKey: {
+                    kind: "structural",
+                    // Create carries it in the body; update does NOT — the key is
+                    // immutable (`blob-buckets-controller.ts` update) and the URL already
+                    // names the bucket, so a body carrying it is a 400 rather than a
+                    // rename that silently did nothing.
+                    requestModes: ["create"],
+                    note: "The bucket's identity. Comes from the TOML file name and is " +
+                        "attached by the caller, not spread from the [bucket] table. Its " +
+                        "TOML spelling is declared in tomlOnlyKeys as `key`.",
+                },
+                accessPolicy: {
+                    kind: "deprecated",
+                    note: "#1020 — the legacy access field, superseded by `preset`. Still " +
+                        "accepted on the wire and returned as a read alias, but authors " +
+                        "write `preset`, so pull does not emit it (writing both would " +
+                        "author the same decision twice).",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "User who created the bucket; assigned server-side.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {
+                key: {
+                    kind: "structural",
+                    note: "The bucket key. `config pull` writes it for readability; push takes " +
+                        "the identity from the file name and attaches `bucketKey` itself.",
+                },
+                accessPolicy: {
+                    kind: "deprecated",
+                    note: "Accepted in existing files as the pre-#1020 spelling of `preset` " +
+                        "and forwarded on push, so an unmigrated file still pushes. Pull " +
+                        "writes `preset`.",
+                },
+            },
+            responseOnlyKeys: {},
+        },
+    ],
+    // A bucket file is the `[bucket]` table and nothing else: its access model is
+    // a preset or a rule-set reference, both scalars inside that table.
+    tomlDocumentKeys: {},
+};
+// ── src/config-surface/email-template.ts ─────────────────────────────────
+/**
+ * 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 const RETIRED_EMAIL_TYPES = ["magic-link", "otp"];
+/** True when `emailType` is one of the retired sign-in types. */
+export function isRetiredEmailType(emailType) {
+    return RETIRED_EMAIL_TYPES.includes(emailType);
+}
+/** What every surface says about a retired type, in one sentence. */
+export function retiredEmailTypeGuidance(emailType) {
+    const carryOver = emailType === "otp"
+        ? "the code block (`{{code}}`, `{{expiryMinutes}}`)"
+        : "the link block (`{{{magicLink}}}`), inside `{{#if magicLink}}`";
+    return (`\`${emailType}\` is retired (#2884): email sign-in sends ONE email from ` +
+        "the `email-sign-in` template, and no sign-in path renders this type any " +
+        `more. Re-author ${carryOver} into your \`email-sign-in\` template, then ` +
+        `delete this override.`);
+}
+const EMAIL_TEMPLATE_HANDLER = "src/admin-api.ts";
+export const EMAIL_TEMPLATE_SURFACE = {
+    label: "email-template",
+    tables: [
+        {
+            tomlPath: ["template"],
+            repeated: false,
+            model: "EmailTemplate",
+            // Declaration order reproduces the pre-#2644 serializer's key order.
+            fields: [
+                {
+                    field: "subject",
+                    tomlKey: "subject",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Size-capped and checked for unescaped `{{{var}}}` interpolation.
+                    validation: handledBy(EMAIL_TEMPLATE_HANDLER, "AdminAPI"),
+                },
+                {
+                    field: "htmlBody",
+                    tomlKey: "htmlBody",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(EMAIL_TEMPLATE_HANDLER, "AdminAPI"),
+                },
+                {
+                    field: "textBody",
+                    tomlKey: "textBody",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(EMAIL_TEMPLATE_HANDLER, "AdminAPI"),
+                },
+            ],
+            notExposed: {
+                templateId: {
+                    kind: "server-owned",
+                    note: "ULID assigned on create; never author-authored.",
+                },
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                emailType: {
+                    kind: "structural",
+                    // Stated, not implied: the upsert handler reads the type from the
+                    // route, so no request schema admits the key.
+                    requestModes: [],
+                    note: "The override's identity — which built-in email it replaces. Comes " +
+                        "from the TOML file name and travels in the URL path, not in the " +
+                        "request body. Its TOML spelling is declared in tomlOnlyKeys.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "Admin who created the override; assigned server-side.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {
+                emailType: {
+                    kind: "structural",
+                    note: "`config pull` writes the email type for readability; push takes it " +
+                        "from the file name and puts it in the URL, never the body.",
+                },
+            },
+            responseOnlyKeys: {
+                label: {
+                    kind: "server-owned",
+                    note: "Human-readable name of the built-in email this override replaces " +
+                        "(the emailType itself for a custom type). Presentation only.",
+                },
+                description: {
+                    kind: "server-owned",
+                    note: "What the built-in email is for, shown in the admin UI. Platform " +
+                        "copy, not an override field.",
+                },
+                isCustom: {
+                    kind: "server-owned",
+                    note: "Derived flag: whether the emailType is a custom one rather than a " +
+                        "built-in. Computed from the route, never authored.",
+                },
+                variables: {
+                    kind: "server-owned",
+                    note: "The template variables this email exposes, with their " +
+                        "descriptions — the platform's own list for built-ins, extracted " +
+                        "from the override's text for a custom type. Documentation, not a " +
+                        "field surface.",
+                },
+                hasOverride: {
+                    kind: "server-owned",
+                    note: "Derived flag: whether this app has replaced the built-in template. " +
+                        "Computed at serialize time; `config pull` writes only overrides.",
+                },
+                override: {
+                    kind: "structural",
+                    note: "The app's override fields, nested in the detail response. Flattened " +
+                        "into the [template] table on pull.",
+                },
+                default: {
+                    kind: "server-owned",
+                    note: "The platform's built-in copy of the template, returned for " +
+                        "comparison. Never authored and never written to TOML.",
+                },
+            },
+        },
+    ],
+    // An override file is the `[template]` table alone — subject and the two
+    // bodies. The platform default it replaces is server-side, never authored.
+    tomlDocumentKeys: {},
+};
+// ── src/config-surface/database-type-config.ts ───────────────────────────
+/**
+ * The `database-type-config` configuration object's definition (issue #2644, phase 3).
+ *
+ * `database-type-configs/<databaseType>.toml` is the most structured file in the sync
+ * slot: a `[type]` scalar table, plus four authored sub-trees that keep the
+ * validators that already own them, per the spec's scope boundary —
+ *
+ *   `[models.*]`      → the stored `schema` TOML string (`parseSchemaToml`)
+ *   `[[operations]]`  → `DatabaseTypeOperation` rows (`toml-params-validator.ts`)
+ *   `[[subscriptions]]` → `DatabaseTypeSubscription` rows (#803)
+ *   `[triggers]`      → the trigger-rule tree (`validateTriggerRules`)
+ *   `[metadata]`/`secrets` → the declared-access manifest (#1304)
+ *
+ * `operations` and `subscriptions` are separate models with their own
+ * endpoints, so they are not fields of `DatabaseTypeConfig` at all; `schema`,
+ * `triggers` and `metadataManifest` ARE model fields and are declared
+ * `structural` here, naming the channel and the validator, so their absence
+ * from the `[type]` table reads as a decision rather than an omission.
+ *
+ * The exposed `[type]` scalars are exactly the file-OWNED ones (#1567): `sync
+ * push` sends each as value-or-`null` so removing a line from the TOML clears
+ * it server-side rather than leaving a stale value live. `DB_TYPE_OWNED_SCALARS`
+ * used to state that list a second time in the CLI; it now reads this
+ * definition.
+ */
+const DB_TYPE_HANDLER = "src/app-api/controllers/database-type-config-controller.ts";
+export const DATABASE_TYPE_SURFACE = {
+    label: "database-type-config",
+    tables: [
+        {
+            tomlPath: ["type"],
+            repeated: false,
+            model: "DatabaseTypeConfig",
+            // Declaration order reproduces the pre-#2644 serializer's key order.
+            fields: [
+                {
+                    field: "databaseType",
+                    tomlKey: "databaseType",
+                    type: "string",
+                    emit: "always",
+                    writableOn: CREATE_ONLY,
+                    // The type's identity: required and `#`-free on create, taken from
+                    // the URL on update.
+                    validation: handledBy(DB_TYPE_HANDLER, "DatabaseTypeConfigController"),
+                },
+                {
+                    field: "ruleSetId",
+                    tomlKey: "ruleSetName",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Authored as a portable name and sent as an id; the server checks
+                    // the set exists and has `resourceType: "database"`.
+                    validation: handledBy(DB_TYPE_HANDLER, "DatabaseTypeConfigController"),
+                },
+                {
+                    field: "metadataAccess",
+                    tomlKey: "celContextAccess",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    // CEL, parsed before storing (#1336). The legacy `metadataAccess`
+                    // spelling stays readable on push — see tomlOnlyKeys.
+                    validation: handledBy(DB_TYPE_HANDLER, "DatabaseTypeConfigController"),
+                },
+                {
+                    field: "defaultAccess",
+                    tomlKey: "defaultAccess",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    // CEL, plus the shared `md`-shape allowlist (#1523).
+                    validation: handledBy(DB_TYPE_HANDLER, "DatabaseTypeConfigController"),
+                },
+                {
+                    field: "autoPopulatedFields",
+                    tomlKey: "autoPopulatedFields",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    // #750 — shorthand and verbose forms both accepted, normalized by
+                    // `validateAndNormalizeAutoPopulatedFields`.
+                    validation: handledBy(DB_TYPE_HANDLER, "DatabaseTypeConfigController"),
+                },
+                {
+                    field: "timestamps",
+                    tomlKey: "timestamps",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    // #748 — `{ create?, update?, models? }`, normalized by
+                    // `validateAndNormalizeTimestamps`.
+                    validation: handledBy(DB_TYPE_HANDLER, "DatabaseTypeConfigController"),
+                },
+            ],
+            notExposed: {
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                triggers: {
+                    kind: "structural",
+                    note: "The trigger-rule tree, authored as the file's top-level " +
+                        "`[triggers]` table rather than a key inside [type]. Validated by " +
+                        "`validateTriggerRules` server-side and pushed whole; the file owns " +
+                        "it, so an absent table clears it (#1567).",
+                },
+                metadataManifest: {
+                    kind: "structural",
+                    note: "The declared-access manifest (#1304 P-C): authored as the file's " +
+                        "top-level `[metadata]` + `secrets` fragments, validated by " +
+                        "`validateDeclaredAccessManifest` before push.",
+                },
+                schema: {
+                    kind: "structural",
+                    note: "The type's model schema (#666), stored as a raw TOML string and " +
+                        "authored as the file's `[models.*]` blocks. Parsed by " +
+                        "`parseSchemaToml` server-side; it is a sub-tree with its own " +
+                        "prior-state discriminator on push, not a scalar.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "User who created the config; assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {
+                ruleSetId: {
+                    kind: "deprecated",
+                    note: "The legacy id-based rule-set reference. Still accepted on push " +
+                        "so an unmigrated file pushes unchanged; pull writes `ruleSetName`.",
+                },
+                metadataAccess: {
+                    kind: "deprecated",
+                    note: "The legacy spelling of `celContextAccess`. Read on push when the " +
+                        "newer key is absent (#1567 keeps `celContextAccess = \"\"` an " +
+                        "explicit clear); pull writes `celContextAccess`.",
+                },
+            },
+            requestOnlyKeys: {
+                pendingOpDeletes: {
+                    note: "Operation names this push is deleting, sent with the type-config " +
+                        "PATCH so the server validates the remaining schema against the " +
+                        "operations that will survive rather than the current set.",
+                },
+                pendingOpUpdates: {
+                    note: "#1336 — the post-push form of the operations this push rewrites " +
+                        "({ name, access, params }), so the child-op re-lint evaluates " +
+                        "each against what the push is about to store rather than the " +
+                        "stale row. Read by `type-config-access-lint.ts`, the same " +
+                        "look-ahead contract as `pendingOpDeletes` / `finalOpNames`.",
+                },
+                pendingOpUpserts: {
+                    modes: ["update"],
+                    note: "#2732 — the full post-push BODY of every operation this push " +
+                        "lands ({ name, type, modelName, access, definition, params }), so " +
+                        "the schema-edit gate lints a rewritten operation as rewritten " +
+                        "rather than as stored. That is what makes removing a model and " +
+                        "rewriting the operations that named it a single push. Read by " +
+                        "`pending-op-set.ts`, which honors an entry only when it is a " +
+                        "whole operation body whose name `finalOpNames` keeps — anything " +
+                        "less is ignored and the stored operation is gated instead. A " +
+                        "create has no stored operations to gate.",
+                },
+                finalOpNames: {
+                    note: "The operation names the file will end with, for the same " +
+                        "look-ahead validation as `pendingOpDeletes`.",
+                },
+            },
+            responseOnlyKeys: {},
+        },
+    ],
+    tomlDocumentKeys: {
+        models: {
+            kind: "structural",
+            note: "#666 — the `[models.<Name>.fields.*]` blocks, re-serialized into the " +
+                "stored `schema` TOML string on push and merged back on pull.",
+        },
+        operations: {
+            kind: "structural",
+            note: "The `[[operations]]` array. Keeps the validator that already owns it " +
+                "(`cli/src/lib/toml-params-validator.ts`) and its own endpoints.",
+        },
+        subscriptions: {
+            kind: "structural",
+            note: "#803 — the `[[subscriptions]]` array, applied through its own endpoints.",
+        },
+        triggers: {
+            kind: "structural",
+            note: "The type's authored trigger table, stored on the type config as " +
+                "`triggers` and validated server-side.",
+        },
+        ...DECLARED_ACCESS_MANIFEST_KEYS,
+    },
+};
+// ── src/config-surface/rule-set.ts ───────────────────────────────────────
+/**
+ * The `rule-set` configuration object's definition (issue #2644, phase 3).
+ *
+ * `rule-sets/<name>.toml` carries a `[ruleSet]` scalar table plus the authored
+ * `[rules]` tree — `{ category: { operation: "<CEL>" } }` — which is declared
+ * `structural`: it is a nested authored sub-tree with its own validator
+ * (`validateRules`, server-side, against the set's `resourceType`), and the
+ * spec's scope boundary keeps nested structure with the validator that already
+ * owns it rather than re-modelling it as fields.
+ *
+ * `resourceType` is `create` only: `update` builds its `updates` map from
+ * `name` / `description` / `rules` alone, so a rule set's resource type is
+ * fixed at creation.
+ */
+const RULE_SET_HANDLER = "src/app-api/controllers/rule-sets-controller.ts";
+export const RULE_SET_SURFACE = {
+    label: "rule-set",
+    tables: [
+        {
+            tomlPath: ["ruleSet"],
+            repeated: false,
+            model: "AccessRuleSet",
+            // Declaration order reproduces the pre-#2644 serializer's key order.
+            fields: [
+                {
+                    field: "name",
+                    tomlKey: "name",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Required, trimmed, and non-empty on both modes.
+                    validation: handledBy(RULE_SET_HANDLER, "RuleSetsController"),
+                },
+                {
+                    field: "resourceType",
+                    tomlKey: "resourceType",
+                    type: "string",
+                    emit: "always",
+                    writableOn: CREATE_ONLY,
+                    // Checked against `getValidResourceTypes()`, and singleton types
+                    // (#1148) reject a second set. `update` never reads it.
+                    validation: handledBy(RULE_SET_HANDLER, "RuleSetsController"),
+                },
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+            ],
+            notExposed: {
+                ruleSetId: {
+                    kind: "server-owned",
+                    note: "ULID assigned on create; the file is keyed by name instead.",
+                },
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                rules: {
+                    kind: "structural",
+                    note: "The authored `[rules]` tree, a sibling table of [ruleSet] rather " +
+                        "than a key inside it. Its shape is category → operation → CEL, " +
+                        "validated by `validateRules` in rule-sets-controller.ts against " +
+                        "the set's resourceType; `config push` sends it whole.",
+                },
+                version: {
+                    kind: "server-owned",
+                    note: "Bumped by the server whenever `rules` changes; never authored.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "User who created the rule set; assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {},
+            responseOnlyKeys: {},
+        },
+    ],
+    tomlDocumentKeys: {
+        rules: {
+            kind: "structural",
+            note: "The `[rules.<category>]` tree of CEL expressions — the rule set's " +
+                "whole point. Keeps its own validator and travels beside [ruleSet].",
+        },
+    },
+};
+// ── src/config-surface/group-type-config.ts ──────────────────────────────
+/**
+ * The `group-type-config` configuration object's definition (issue #2644,
+ * phase 3).
+ *
+ * `group-type-configs/<groupType>.toml` carries a single `[groupTypeConfig]`
+ * table, plus the declared-access manifest's top-level `[metadata]` / `secrets`
+ * fragments — which are `structural`: authored elsewhere in the file, with
+ * their own validator (`validateDeclaredAccessManifest` locally,
+ * `validateManifestShape` server-side).
+ *
+ * The rule-set reference is stored as `ruleSetId` but AUTHORED as
+ * `ruleSetName`, because a name is portable across apps and an id is not. The
+ * name → id resolution is the CLI's (`config push` resolves against the app's
+ * rule sets); the server validates that the id exists and has
+ * `resourceType: "group"`. The legacy id spelling stays accepted on push and is
+ * declared in `tomlOnlyKeys`.
+ */
+const GROUP_TYPE_HANDLER = "src/app-api/controllers/group-type-config-controller.ts";
+export const GROUP_TYPE_CONFIG_SURFACE = {
+    label: "group-type-config",
+    tables: [
+        {
+            tomlPath: ["groupTypeConfig"],
+            repeated: false,
+            model: "GroupTypeConfig",
+            // Declaration order reproduces the pre-#2644 serializer's key order.
+            fields: [
+                {
+                    field: "groupType",
+                    tomlKey: "groupType",
+                    type: "string",
+                    emit: "always",
+                    writableOn: CREATE_ONLY,
+                    // The config's identity: required and `#`-free on create, taken from
+                    // the URL on update.
+                    validation: handledBy(GROUP_TYPE_HANDLER, "GroupTypeConfigController"),
+                },
+                {
+                    field: "ruleSetId",
+                    tomlKey: "ruleSetName",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Authored as a name, sent as an id; existence and resourceType are
+                    // checked server-side, and an empty value clears the reference.
+                    validation: handledBy(GROUP_TYPE_HANDLER, "GroupTypeConfigController"),
+                },
+                {
+                    field: "autoAddCreator",
+                    tomlKey: "autoAddCreator",
+                    type: "boolean",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Defaults to `true` when absent on create, and is coerced with `!!`
+                    // on update — not a stored-as-is passthrough.
+                    validation: handledBy(GROUP_TYPE_HANDLER, "GroupTypeConfigController"),
+                },
+            ],
+            notExposed: {
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                metadataManifest: {
+                    kind: "structural",
+                    note: "The declared-access manifest (#1350, extending #1304): authored " +
+                        "as the file's top-level `[metadata]` + `secrets` fragments, not " +
+                        "as a key inside [groupTypeConfig]. Validated by " +
+                        "`validateDeclaredAccessManifest` (cli/src/lib/toml-metadata-config.ts) " +
+                        "before push and `validateManifestShape` at persist time.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "User who created the config; assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {
+                ruleSetId: {
+                    kind: "deprecated",
+                    note: "The legacy id-based rule-set reference. Still accepted on push " +
+                        "so an unmigrated file pushes unchanged; pull writes `ruleSetName`.",
+                },
+            },
+            responseOnlyKeys: {},
+        },
+    ],
+    tomlDocumentKeys: { ...DECLARED_ACCESS_MANIFEST_KEYS },
+};
+// ── src/config-surface/collection-type-config.ts ─────────────────────────
+/**
+ * The `collection-type-config` configuration object's definition (issue #2644,
+ * phase 3).
+ *
+ * `collection-type-configs/<collectionType>.toml` carries a single
+ * `[collectionTypeConfig]` table plus the declared-access manifest's top-level
+ * `[metadata]` / `secrets` fragments (declared `structural`, as on every other
+ * config that carries one).
+ *
+ * Same shape as `group-type-config` minus `autoAddCreator`: the rule-set
+ * reference is stored as `ruleSetId` and authored as `ruleSetName`, and the
+ * server checks the referenced set has `resourceType: "collection"`.
+ */
+const COLLECTION_TYPE_HANDLER = "src/app-api/controllers/collection-type-config-controller.ts";
+export const COLLECTION_TYPE_CONFIG_SURFACE = {
+    label: "collection-type-config",
+    tables: [
+        {
+            tomlPath: ["collectionTypeConfig"],
+            repeated: false,
+            model: "CollectionTypeConfig",
+            // Declaration order reproduces the pre-#2644 serializer's key order.
+            fields: [
+                {
+                    field: "collectionType",
+                    tomlKey: "collectionType",
+                    type: "string",
+                    emit: "always",
+                    writableOn: CREATE_ONLY,
+                    // The config's identity: required on create, taken from the URL on
+                    // update.
+                    validation: handledBy(COLLECTION_TYPE_HANDLER, "CollectionTypeConfigController"),
+                },
+                {
+                    field: "ruleSetId",
+                    tomlKey: "ruleSetName",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Authored as a name, sent as an id; existence and resourceType are
+                    // checked server-side, and an empty value clears the reference.
+                    validation: handledBy(COLLECTION_TYPE_HANDLER, "CollectionTypeConfigController"),
+                },
+            ],
+            notExposed: {
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                metadataManifest: {
+                    kind: "structural",
+                    note: "The declared-access manifest (#1304 P-C): authored as the file's " +
+                        "top-level `[metadata]` + `secrets` fragments, not as a key inside " +
+                        "[collectionTypeConfig]. Validated by " +
+                        "`validateDeclaredAccessManifest` (cli/src/lib/toml-metadata-config.ts) " +
+                        "before push and `validateManifestShape` at persist time.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "User who created the config; assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {
+                ruleSetId: {
+                    kind: "deprecated",
+                    note: "The legacy id-based rule-set reference. Still accepted on push " +
+                        "so an unmigrated file pushes unchanged; pull writes `ruleSetName`.",
+                },
+            },
+            responseOnlyKeys: {},
+        },
+    ],
+    tomlDocumentKeys: { ...DECLARED_ACCESS_MANIFEST_KEYS },
+};
+// ── src/config-surface/metadata-category-config.ts ───────────────────────
+/**
+ * The `metadata-category-config` configuration object's definition (issue
+ * #2644, phase 3).
+ *
+ * `metadata-category-configs/<resourceType>-<category>.toml` carries a single
+ * `[metadataCategoryConfig]` table. Its identity is the `resourceType` /
+ * `category` PAIR read out of the file's content (not from the file name), and
+ * both halves are part of the table — which is why they are exposed fields and
+ * `categoryKey`, the stored `resourceType#category` composite, is not.
+ *
+ * There is one write path (`PUT …/metadata/categories/{resourceType}/{category}`
+ * and its POST twin, both an upsert through
+ * `MetadataController.upsertCategoryConfig`), so every field is writable on
+ * both modes.
+ *
+ * `schema` is exposed rather than structural: unlike workflow `steps` or a
+ * database type's `[models]` blocks it is a single JSON value the server
+ * returns parsed and stores whole, and `config pull` emits it as nested
+ * `[metadataCategoryConfig.schema.fields.*]` tables. Its CONTENT is
+ * handler-owned — `validateCategorySchema` mirrors the server's field-type,
+ * enum and `unique` rules — but the field itself round-trips as one value.
+ */
+const METADATA_HANDLER = "src/app-api/controllers/metadata-controller.ts";
+const CLI_METADATA_TOML = "cli/src/lib/toml-metadata-config.ts";
+export const METADATA_CATEGORY_CONFIG_SURFACE = {
+    label: "metadata-category-config",
+    tables: [
+        {
+            tomlPath: ["metadataCategoryConfig"],
+            repeated: false,
+            model: "MetadataCategoryConfig",
+            // Declaration order reproduces the pre-#2644 serializer's key order, so
+            // the scalars stay ahead of the nested `[…schema.fields.*]` tables.
+            fields: [
+                {
+                    field: "resourceType",
+                    tomlKey: "resourceType",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Half of the category's identity; required on every upsert.
+                    validation: handledBy(METADATA_HANDLER, "MetadataController"),
+                },
+                {
+                    field: "category",
+                    tomlKey: "category",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // The other half of the identity; required on every upsert.
+                    validation: handledBy(METADATA_HANDLER, "MetadataController"),
+                },
+                {
+                    field: "readRule",
+                    tomlKey: "readRule",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    // CEL, parsed and stored or nulled.
+                    validation: handledBy(METADATA_HANDLER, "MetadataController"),
+                },
+                {
+                    field: "writeRule",
+                    tomlKey: "writeRule",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(METADATA_HANDLER, "MetadataController"),
+                },
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "schema",
+                    tomlKey: "schema",
+                    type: "json",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Required on every upsert, and an absent one is written as
+                    // `{ fields: {} }` so the file stays pushable. Field types, enums and
+                    // the single-`unique` rule are checked locally before push and again
+                    // server-side.
+                    validation: handledBy(CLI_METADATA_TOML, "validateCategorySchema"),
+                },
+            ],
+            notExposed: {
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                categoryKey: {
+                    kind: "server-owned",
+                    note: "The stored `resourceType#category` composite. Derived from the " +
+                        "two exposed identity fields; writing it too would author the same " +
+                        "decision twice.",
+                },
+                metadataManifest: {
+                    kind: "structural",
+                    note: "The declared-access manifest (#1420 phase 2): authored as the " +
+                        "file's top-level `[metadata]` + `secrets` fragments, not as a key " +
+                        "inside [metadataCategoryConfig].",
+                },
+                uniqueField: {
+                    kind: "server-owned",
+                    note: "Derived from the schema's single `unique: true` field (#1361) and " +
+                        "maintained by the server's reverse-resolve index; authors declare " +
+                        "`unique` on the field, not this pointer.",
+                },
+                schemaVersion: {
+                    kind: "server-owned",
+                    note: "Bumped by the server when the schema changes; never authored.",
+                },
+                generation: {
+                    kind: "server-owned",
+                    note: "Server-managed rewrite counter for the category's rows.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "User who created the category; assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {},
+            responseOnlyKeys: {},
+        },
+    ],
+    tomlDocumentKeys: { ...DECLARED_ACCESS_MANIFEST_KEYS },
+};
+// ── src/config-surface/transform.ts ──────────────────────────────────────
+/**
+ * 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 const TRANSFORM_SURFACE = {
+    label: "transform",
+    tables: [],
+    // No TOML file at all, so no top-level TOML keys either — stated rather than
+    // left to `noFieldTable` to imply.
+    tomlDocumentKeys: {},
+    noFieldTable: {
+        note: "A transform is a Rhai source file (`transforms/<name>.rhai`); its " +
+            "authored surface is the script body, which config pull writes from the " +
+            "active ScriptConfig and config push sends back whole. The Script / " +
+            "ScriptConfig scalars (name, description, inputSchema, limits, status) " +
+            "are managed through `primitive transforms`, not through a TOML table, " +
+            "so this object has no field surface to define. Its sidecar test cases " +
+            "(`transforms/<name>.tests/`) are the separate `test-case` surface.",
+    },
+};
+// ── src/config-surface/test-case.ts ──────────────────────────────────────
+/**
+ * The `test-case` configuration object's definition (issue #2644, phase 3).
+ *
+ * Test cases round-trip without being one of the per-entity directories: they
+ * live in a sidecar `<key>.tests/` folder beside the block they test — a
+ * prompt, a workflow, a transform or (since #2769) an integration — one
+ * `[test]` table per file. They are not
+ * a `SYNC_RESOURCE_TYPES` label (that table is per-entity directory metadata),
+ * which is exactly why the spec names them explicitly: nothing that syncs sits
+ * outside the registry.
+ *
+ * Three fields are stored as ids and AUTHORED as keys — `configId` /
+ * `evaluatorPromptId` / `evaluatorConfigId` become `configName` /
+ * `evaluatorPromptKey` / `evaluatorConfigName` — so a test file is portable
+ * across apps. The legacy id spellings stay accepted on push and are declared
+ * in `tomlOnlyKeys`.
+ *
+ * Three more are stored as JSON strings and carried in TOML as JSON strings
+ * (`inputVariables`, `expectedOutputContains`, `expectedJsonSubset`) while the
+ * WIRE shape is the parsed value. That asymmetry is the handler's, not the
+ * definition's: `parseTestCaseToml` parses on push and the admin API
+ * re-stringifies on store.
+ */
+const TEST_CASE_HANDLER = "src/admin-api.ts";
+const CLI_SYNC = "cli/src/commands/sync.ts";
+export const TEST_CASE_SURFACE = {
+    label: "test-case",
+    tables: [
+        {
+            tomlPath: ["test"],
+            repeated: false,
+            model: "BlockTestCase",
+            // Declaration order reproduces the pre-#2644 serializer's key order.
+            fields: [
+                {
+                    field: "name",
+                    tomlKey: "name",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Required and trimmed on create; an empty name is a 400.
+                    validation: handledBy(TEST_CASE_HANDLER, "AdminAPI"),
+                },
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "inputVariables",
+                    tomlKey: "inputVariables",
+                    type: "json",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Required. TOML carries the JSON text; the wire carries the parsed
+                    // object, which the server re-stringifies for storage.
+                    validation: handledBy(CLI_SYNC, "parseTestCaseToml"),
+                },
+                {
+                    field: "configId",
+                    tomlKey: "configName",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Authored as the config's NAME and resolved to an id at push time.
+                    validation: handledBy(CLI_SYNC, "parseTestCaseToml"),
+                },
+                {
+                    field: "evaluatorPromptId",
+                    tomlKey: "evaluatorPromptKey",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // Authored as the judge prompt's KEY and resolved to an id at push.
+                    validation: handledBy(CLI_SYNC, "parseTestCaseToml"),
+                },
+                {
+                    field: "evaluatorConfigId",
+                    tomlKey: "evaluatorConfigName",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: handledBy(CLI_SYNC, "parseTestCaseToml"),
+                },
+                {
+                    field: "expectedOutputPattern",
+                    tomlKey: "expectedOutputPattern",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "expectedOutputContains",
+                    tomlKey: "expectedOutputContains",
+                    type: "json",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // JSON array of strings; TOML carries the JSON text.
+                    validation: handledBy(CLI_SYNC, "parseTestCaseToml"),
+                },
+                {
+                    field: "expectedJsonSubset",
+                    tomlKey: "expectedJsonSubset",
+                    type: "json",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // JSON object, deep-partial-matched against the parsed output.
+                    validation: handledBy(CLI_SYNC, "parseTestCaseToml"),
+                },
+            ],
+            notExposed: {
+                testCaseId: {
+                    kind: "server-owned",
+                    note: "ULID assigned on create. The file name carries the identity in " +
+                        "the committed tree — as `key`, since #2896 — so this id is the " +
+                        "server's handle, not what a sidecar is reconciled by.",
+                },
+                key: {
+                    kind: "structural",
+                    requestModes: ["create", "update"],
+                    note: "The sidecar's file name (basename without `.toml`) — the case's " +
+                        "identity in the committed tree (#2896). It travels in the BODY " +
+                        "so a clean checkout with no `.primitive-sync.json` reconciles " +
+                        "instead of creating a duplicate of every case; create stamps it " +
+                        "and update backfills it onto a legacy case. Never inside the " +
+                        "`[test]` table: sidecar bytes and the content hash are unchanged " +
+                        "by it.",
+                },
+                keyToken: {
+                    kind: "server-owned",
+                    note: "`blockComposite#key.toLowerCase()`, maintained by the write path " +
+                        "so `uniqueTestCaseKeyPerBlock` enforces per-block, " +
+                        "case-insensitive key uniqueness in one transactional write " +
+                        "(#2896). Never on the wire in either direction.",
+                },
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                blockType: {
+                    kind: "structural",
+                    requestModes: [],
+                    note: "Which kind of block the case tests (prompt | workflow | script | " +
+                        "integration). " +
+                        "Comes from the directory the `<key>.tests/` folder sits in and " +
+                        "travels in the URL path, not in the body.",
+                },
+                blockId: {
+                    kind: "structural",
+                    requestModes: [],
+                    note: "The block the case belongs to, resolved from the owning file's " +
+                        "key at push time and sent in the URL path.",
+                },
+                blockComposite: {
+                    kind: "server-owned",
+                    note: "`blockType#blockId`, assembled server-side for indexing.",
+                },
+                attachments: {
+                    kind: "server-owned",
+                    note: "Uploaded fixture files, managed through the " +
+                        "`/test-cases/{id}/attachments` endpoints and stored in R2. The " +
+                        "create handler always writes null; sync never carries them.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "Admin who created the case; assigned server-side.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {
+                configId: {
+                    kind: "deprecated",
+                    note: "The legacy id-based config reference. Still accepted on push so " +
+                        "an unmigrated file pushes unchanged; pull writes `configName`.",
+                },
+                evaluatorPromptId: {
+                    kind: "deprecated",
+                    note: "The legacy id-based evaluator-prompt reference; pull writes " +
+                        "`evaluatorPromptKey`.",
+                },
+                evaluatorConfigId: {
+                    kind: "deprecated",
+                    note: "The legacy id-based evaluator-config reference; pull writes " +
+                        "`evaluatorConfigName`.",
+                },
+            },
+            responseOnlyKeys: {},
+        },
+    ],
+    // A sidecar is the `[test]` table alone: inputs and expectations are keys
+    // inside it (JSON strings), not sibling tables.
+    tomlDocumentKeys: {},
+};
+// ── src/config-surface/app-settings.ts ───────────────────────────────────
+/**
+ * The `app-settings` configuration object's definition (issue #2644, phase 3).
+ *
+ * `app.toml` is the other surface that round-trips without being a per-entity
+ * file, so — like `test-case` — it is named explicitly rather than reached
+ * through `SYNC_RESOURCE_TYPES`. It is also the object the whole epic
+ * generalizes: #1033 already drives its pull serializer and push parser from
+ * one descriptor (`cli/src/lib/app-settings-descriptor.ts`) against the
+ * server's dependency-free write allow-list (`settings-fields.ts`), with a
+ * parity test between them. This definition is that trio's registry entry, so
+ * the shared coverage guard holds `App` to the same standard as every other
+ * model: every field exposed, or classified with a reason.
+ *
+ * Two shapes here are unlike the per-entity objects:
+ *
+ *   - ONE model over FOUR tables. `app.toml`'s `[app]`, `[auth]`, `[cors]` and
+ *     `[invitations]` sections all project the same `App` row, so coverage is
+ *     asserted per SURFACE (`findUnclassifiedSurfaceFields`) rather than per
+ *     table, and the `notExposed` classifications live once, on `[app]`.
+ *   - UPDATE only. There is one write path — `PUT /settings` — and an app is
+ *     created through a different endpoint entirely, so no field is writable on
+ *     "create" in this surface's sense.
+ *
+ * `googleClients` carries a per-entry `clientSecret` on purpose (#2256, #2891):
+ * each stored value is a whole `{{secrets.KEY}}` REFERENCE, never the
+ * credential, so the map round-trips like any other setting. That is the
+ * explicit classification the secret-adjacent rule requires — the guard fails
+ * on a bare omission, not on a stated reference-only contract.
+ *
+ * As of #2891 nothing here is writable-but-unauthorable. `notExposed` carries
+ * no `deprecated` entry and no withheld-on-read field: the five superseded keys
+ * (`googleClientId`, `googleClientSecret`, `redirectUris`, `passkeyRpId`,
+ * `passkeyRpName`) stay DECLARED in `models.yaml` so a row's storage can still
+ * be read, but no write path accepts them and no serializer emits them, which
+ * makes them `server-owned` here rather than `deprecated`.
+ */
+const SETTINGS_HANDLER = "src/app-api/controllers/settings-controller.ts";
+export const APP_SETTINGS_SURFACE = {
+    label: "app-settings",
+    tables: [
+        {
+            tomlPath: ["app"],
+            repeated: false,
+            model: "App",
+            // Declaration order reproduces `APP_SETTINGS_DESCRIPTOR`'s (#1033), which
+            // is the order `app.toml` is written in.
+            fields: [
+                {
+                    field: "name",
+                    tomlKey: "name",
+                    type: "string",
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "mode",
+                    tomlKey: "mode",
+                    type: "string",
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "baseUrl",
+                    tomlKey: "baseUrl",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "waitlistEnabled",
+                    tomlKey: "waitlistEnabled",
+                    type: "boolean",
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "waitlistNotifyAdmins",
+                    tomlKey: "waitlistNotifyAdmins",
+                    type: "boolean",
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "directLlmEnabled",
+                    tomlKey: "directLlmEnabled",
+                    type: "boolean",
+                    // Always emitted: an app that has not opted the deprecated direct
+                    // LLM/Gemini proxy in must see `directLlmEnabled = false` in its
+                    // pulled `app.toml`, not a key it has to already know about (#2687).
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    // STRICT, not `!!`: the value arms a credit-spending surface read
+                    // with `=== true`, so `"false"` must be a 400 rather than a stored
+                    // `true`. The generated request schema stays keys-only (#1976), so
+                    // the check is `parseDirectLlmEnabledWrite` in the handler.
+                    validation: handledBy(SETTINGS_HANDLER, "SettingsController"),
+                },
+                {
+                    field: "allowedDomains",
+                    tomlKey: "allowedDomains",
+                    type: "string[]",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "testAccountBaseEmails",
+                    tomlKey: "testAccountBaseEmails",
+                    type: "string[]",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    // `+primitivetest` bypass whitelist (#490/#675), shape-checked by
+                    // `validateTestAccountBaseEmails`.
+                    validation: handledBy(SETTINGS_HANDLER, "SettingsController"),
+                },
+            ],
+            notExposed: {
+                appId: {
+                    kind: "server-owned",
+                    note: "The app's id; taken from the route, never authored.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "User who created the app; assigned server-side.",
+                },
+                createdByAdminId: {
+                    kind: "server-owned",
+                    note: "Admin who created the app; assigned server-side.",
+                },
+                passkeyRpId: {
+                    kind: "server-owned",
+                    note: "RETIRED from the write surface by #2891, superseded by " +
+                        "`passkeyRpConfig` (`[auth.passkeys]`), which carries the " +
+                        "per-rpId names. The attribute stays declared so the passkey " +
+                        "runtime can keep reading a legacy row as a fallback, but no " +
+                        "write path accepts it and no serializer emits it.",
+                },
+                passkeyRpName: {
+                    kind: "server-owned",
+                    note: "The other half of the legacy single-rpId passkey config, " +
+                        "RETIRED by #2891 alongside it; superseded by `passkeyRpConfig`.",
+                },
+                googleClientId: {
+                    kind: "server-owned",
+                    note: "RETIRED from the write surface by #2891, superseded by " +
+                        "`[auth.google.clients.<type>].clientId` — Google registers a " +
+                        "client per platform, so one app-wide id could not state what " +
+                        "the app actually has. Declared-and-deprecated storage only.",
+                },
+                googleClientSecret: {
+                    kind: "server-owned",
+                    note: "RETIRED from the write surface by #2891, superseded by " +
+                        "`[auth.google.clients.<type>].clientSecret` — the secret belongs " +
+                        "to one client, and Google issues none at all for the native " +
+                        "types. Declared-and-deprecated storage only; never read, never " +
+                        "echoed.",
+                },
+                magicLinkEnabled: {
+                    kind: "server-owned",
+                    note: "RETIRED from the write surface by #2884, superseded by " +
+                        "`emailSignInEnabled`. Email sign-in is ONE flow — one request, " +
+                        "one email carrying a code and (when a link can be issued) a " +
+                        "link — so there is no method to enable separately. The " +
+                        "attribute stays declared and is MIRRORED on every write of " +
+                        "`emailSignInEnabled`, so a row read by an un-migrated consumer " +
+                        "still matches behavior.",
+                },
+                otpEnabled: {
+                    kind: "server-owned",
+                    note: "The other half of the retired pair (#2884); superseded by " +
+                        "`emailSignInEnabled` and mirrored the same way.",
+                },
+                redirectUris: {
+                    kind: "server-owned",
+                    note: "RETIRED from the write surface by #2891. A redirect URI belongs " +
+                        "to the thing that redirects: Google callbacks moved to " +
+                        "`[auth.google.clients.<type>].redirectUris` and the magic-link " +
+                        "allow-list to `emailRedirectUris`. Declared-and-deprecated " +
+                        "storage only.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {},
+            responseOnlyKeys: {
+                // `hasGoogleAuth` is gone (#2891): the client map states per-platform
+                // truth directly, so a single derived flag can only be wrong in one
+                // direction or the other. `hasAppleAuth` and `hasPasskey` STAY — the
+                // asymmetry is deliberate, not an oversight to "fix" later: Apple and
+                // passkeys have no map to derive that truth from.
+                hasAppleAuth: {
+                    kind: "server-owned",
+                    note: "Derived presence flag on GET /settings; no setter.",
+                },
+                hasPasskey: {
+                    kind: "server-owned",
+                    note: "Derived presence flag on GET /settings; no setter.",
+                },
+            },
+        },
+        {
+            tomlPath: ["auth"],
+            repeated: false,
+            model: "App",
+            fields: [
+                {
+                    field: "googleOAuthEnabled",
+                    tomlKey: "googleOAuthEnabled",
+                    type: "boolean",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "googleClients",
+                    tomlKey: "google",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    // `[auth.google.clients.<type>]` — one entry per Google client type,
+                    // each with its own `clientId`, `redirectUris` and (where the type
+                    // takes one) a whole `{{secrets.KEY}}` `clientSecret`. Shape, the
+                    // per-type secret table, cross-entry URI uniqueness and the
+                    // aggregate caps are all `validateGoogleClientsWrite`
+                    // (`src/services/google-clients.ts`), applied by the handler.
+                    validation: handledBy(SETTINGS_HANDLER, "SettingsController"),
+                },
+                {
+                    field: "passkeyEnabled",
+                    tomlKey: "passkeyEnabled",
+                    type: "boolean",
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "emailSignInEnabled",
+                    tomlKey: "emailSignInEnabled",
+                    type: "boolean",
+                    // Always emitted: an app's pulled `app.toml` should state whether
+                    // email sign-in is on, not leave it to be inferred from the absence
+                    // of a key (#2884).
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    // Mirrored into the two retired model fields by the handler so an
+                    // un-migrated reader cannot disagree.
+                    validation: handledBy(SETTINGS_HANDLER, "SettingsController"),
+                },
+                {
+                    field: "appleSignInEnabled",
+                    tomlKey: "appleSignInEnabled",
+                    type: "boolean",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "appleAudiences",
+                    tomlKey: "appleAudiences",
+                    type: "string[]",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "emailRedirectUris",
+                    tomlKey: "emailRedirectUris",
+                    type: "string[]",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    // The email sign-in link allow-list, flat in `[auth]` beside the
+                    // flag it belongs with (sponsor decision, DSO-2891-003 — no
+                    // `[auth.email]` table). Each URI is parsed and canonicalized by
+                    // `validateRedirectUris`; matching is fail-closed, and a request
+                    // whose target this list does not cover gets a code-only email
+                    // rather than a link (#2884).
+                    validation: handledBy(SETTINGS_HANDLER, "SettingsController"),
+                },
+                {
+                    field: "passkeyRpConfig",
+                    tomlKey: "passkeys",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    // `[auth.passkeys]` — rpId → { name }, shape-checked by
+                    // `SettingsController.validatePasskeyRpConfig`.
+                    validation: handledBy(SETTINGS_HANDLER, "SettingsController"),
+                },
+            ],
+            notExposed: {},
+            tomlOnlyKeys: {},
+            responseOnlyKeys: {},
+        },
+        {
+            tomlPath: ["cors"],
+            repeated: false,
+            model: "App",
+            fields: [
+                {
+                    field: "corsMode",
+                    tomlKey: "mode",
+                    type: "string",
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "corsAllowedOrigins",
+                    tomlKey: "allowedOrigins",
+                    type: "string[]",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "corsAllowCredentials",
+                    tomlKey: "allowCredentials",
+                    type: "boolean",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "corsAllowedMethods",
+                    tomlKey: "allowedMethods",
+                    type: "string[]",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "corsAllowedHeaders",
+                    tomlKey: "allowedHeaders",
+                    type: "string[]",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "corsExposedHeaders",
+                    tomlKey: "exposedHeaders",
+                    type: "string[]",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "corsMaxAge",
+                    tomlKey: "maxAge",
+                    type: "number",
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+            ],
+            notExposed: {},
+            tomlOnlyKeys: {},
+            responseOnlyKeys: {},
+        },
+        {
+            tomlPath: ["invitations"],
+            repeated: false,
+            model: "App",
+            fields: [
+                {
+                    field: "memberInvitationsEnabled",
+                    tomlKey: "enabled",
+                    type: "boolean",
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+                {
+                    field: "memberInvitationLimit",
+                    tomlKey: "limit",
+                    type: "number",
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    validation: "passthrough",
+                },
+            ],
+            notExposed: {},
+            tomlOnlyKeys: {},
+            responseOnlyKeys: {},
+        },
+    ],
+    // `app.toml`'s four sections are all field tables; it carries no other
+    // top-level key. (App config VARS live in their own `vars.toml`.)
+    tomlDocumentKeys: {},
+};
+// ── src/config-surface/index.ts ──────────────────────────────────────────
+/**
+ * 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 const CONFIG_SURFACES = [
+    WORKFLOW_SURFACE,
+    PROMPT_SURFACE,
+    INTEGRATION_SURFACE,
+    WEBHOOK_SURFACE,
+    CRON_TRIGGER_SURFACE,
+    BLOB_BUCKET_SURFACE,
+    EMAIL_TEMPLATE_SURFACE,
+    DATABASE_TYPE_SURFACE,
+    RULE_SET_SURFACE,
+    GROUP_TYPE_CONFIG_SURFACE,
+    COLLECTION_TYPE_CONFIG_SURFACE,
+    METADATA_CATEGORY_CONFIG_SURFACE,
+    TRANSFORM_SURFACE,
+    TEST_CASE_SURFACE,
+    APP_SETTINGS_SURFACE,
+];
+/** The surface for a `SyncResourceType.label`, or undefined when unmigrated. */
+export function getConfigSurface(label) {
+    return CONFIG_SURFACES.find((s) => s.label === label);
+}
+/** One table of one surface, addressed by its TOML path. */
+export function getConfigTable(label, tomlPath) {
+    const surface = getConfigSurface(label);
+    if (!surface)
+        return undefined;
+    return surface.tables.find((t) => t.tomlPath.length === tomlPath.length &&
+        t.tomlPath.every((segment, i) => segment === tomlPath[i]));
+}
+/**
+ * Every field of every `models.yaml` model a configuration-object definition
+ * names, in declaration order — the coverage guard's anchor (#2644 criterion 2).
+ */
+export const GENERATED_CONFIG_MODEL_FIELDS = {
+    "AccessRuleSet": [
+        "ruleSetId",
+        "appId",
+        "name",
+        "description",
+        "resourceType",
+        "rules",
+        "version",
+        "createdAt",
+        "modifiedAt",
+        "createdBy",
+    ],
+    "App": [
+        "appId",
+        "name",
+        "mode",
+        "waitlistEnabled",
+        "waitlistNotifyAdmins",
+        "createdBy",
+        "createdByAdminId",
+        "googleOAuthEnabled",
+        "googleClientId",
+        "googleClientSecret",
+        "googleClients",
+        "appleSignInEnabled",
+        "appleAudiences",
+        "allowedDomains",
+        "redirectUris",
+        "emailRedirectUris",
+        "testAccountBaseEmails",
+        "corsMode",
+        "corsAllowedOrigins",
+        "corsAllowCredentials",
+        "corsAllowedMethods",
+        "corsAllowedHeaders",
+        "corsExposedHeaders",
+        "corsMaxAge",
+        "passkeyEnabled",
+        "passkeyRpId",
+        "passkeyRpName",
+        "passkeyRpConfig",
+        "emailSignInEnabled",
+        "magicLinkEnabled",
+        "otpEnabled",
+        "baseUrl",
+        "directLlmEnabled",
+        "memberInvitationsEnabled",
+        "memberInvitationLimit",
+        "createdAt",
+        "modifiedAt",
+    ],
+    "AppIntegration": [
+        "integrationId",
+        "appId",
+        "integrationKey",
+        "displayName",
+        "description",
+        "status",
+        "requestConfig",
+        "accessRule",
+        "activeConfigId",
+        "timeoutMs",
+        "maxRequestBodyBytes",
+        "copiedFromCatalogId",
+        "lastTestedAt",
+        "createdBy",
+        "createdAt",
+        "modifiedAt",
+    ],
+    "AppPrompt": [
+        "promptId",
+        "appId",
+        "promptKey",
+        "displayName",
+        "description",
+        "copiedFromCatalogId",
+        "inputSchema",
+        "outputSchema",
+        "activeConfigId",
+        "defaultEvaluatorPromptId",
+        "status",
+        "accessRule",
+        "createdBy",
+        "createdAt",
+        "modifiedAt",
+    ],
+    "AppPromptConfig": [
+        "configId",
+        "promptId",
+        "appId",
+        "configName",
+        "promptIdConfigName",
+        "description",
+        "provider",
+        "model",
+        "systemPrompt",
+        "systemPromptR2Key",
+        "userPromptTemplate",
+        "userPromptTemplateR2Key",
+        "temperature",
+        "topP",
+        "maxTokens",
+        "outputFormat",
+        "outputSchema",
+        "providerConfig",
+        "status",
+        "createdBy",
+        "createdAt",
+        "modifiedAt",
+    ],
+    "AppWebhook": [
+        "webhookId",
+        "appId",
+        "webhookKey",
+        "displayName",
+        "description",
+        "status",
+        "workflowKey",
+        "workflowId",
+        "verificationScheme",
+        "signingSecret",
+        "previousSigningSecret",
+        "secretRotatedAt",
+        "secretGracePeriodMs",
+        "toleranceSeconds",
+        "deduplicationEnabled",
+        "deduplicationWindowMs",
+        "maxBodyBytes",
+        "inputMapping",
+        "allowedIpCidrs",
+        "handshakeRules",
+        "config",
+        "metadata",
+        "lastTriggeredAt",
+        "createdBy",
+        "createdAt",
+        "modifiedAt",
+    ],
+    "BlobBucket": [
+        "bucketId",
+        "appId",
+        "bucketKey",
+        "name",
+        "description",
+        "ttlTier",
+        "accessPolicy",
+        "preset",
+        "ruleSetId",
+        "createdBy",
+        "createdAt",
+        "modifiedAt",
+    ],
+    "BlockTestCase": [
+        "testCaseId",
+        "appId",
+        "blockType",
+        "blockId",
+        "blockComposite",
+        "configId",
+        "key",
+        "keyToken",
+        "name",
+        "description",
+        "inputVariables",
+        "expectedOutputPattern",
+        "expectedOutputContains",
+        "expectedJsonSubset",
+        "evaluatorPromptId",
+        "evaluatorConfigId",
+        "attachments",
+        "createdBy",
+        "createdAt",
+        "modifiedAt",
+    ],
+    "CollectionTypeConfig": [
+        "appId",
+        "collectionType",
+        "ruleSetId",
+        "metadataManifest",
+        "createdAt",
+        "modifiedAt",
+        "createdBy",
+    ],
+    "CronTrigger": [
+        "triggerId",
+        "appId",
+        "triggerKey",
+        "displayName",
+        "description",
+        "cron",
+        "timezone",
+        "workflowKey",
+        "overlapPolicy",
+        "rootInput",
+        "inputMapping",
+        "status",
+        "state",
+        "operationallyDisabled",
+        "lastError",
+        "lastTriggeredAt",
+        "lastTriggeredRunId",
+        "skippedCount",
+        "firedCount",
+        "consecutiveNotActiveCount",
+        "nextFireAt",
+        "createdBy",
+        "createdAt",
+        "modifiedAt",
+    ],
+    "DatabaseTypeConfig": [
+        "appId",
+        "databaseType",
+        "ruleSetId",
+        "triggers",
+        "metadataAccess",
+        "defaultAccess",
+        "metadataManifest",
+        "autoPopulatedFields",
+        "timestamps",
+        "schema",
+        "createdAt",
+        "modifiedAt",
+        "createdBy",
+    ],
+    "EmailTemplate": [
+        "templateId",
+        "appId",
+        "emailType",
+        "subject",
+        "htmlBody",
+        "textBody",
+        "createdBy",
+        "createdAt",
+        "modifiedAt",
+    ],
+    "GroupTypeConfig": [
+        "appId",
+        "groupType",
+        "ruleSetId",
+        "metadataManifest",
+        "autoAddCreator",
+        "createdAt",
+        "modifiedAt",
+        "createdBy",
+    ],
+    "MetadataCategoryConfig": [
+        "appId",
+        "categoryKey",
+        "resourceType",
+        "category",
+        "schema",
+        "readRule",
+        "writeRule",
+        "metadataManifest",
+        "uniqueField",
+        "schemaVersion",
+        "generation",
+        "description",
+        "createdAt",
+        "modifiedAt",
+        "createdBy",
+    ],
+    "WorkflowDefinition": [
+        "workflowId",
+        "appId",
+        "workflowKey",
+        "name",
+        "status",
+        "latestRevision",
+        "description",
+        "stepsR2Key",
+        "draftStepsR2Key",
+        "draftInputSchema",
+        "draftOutputSchema",
+        "draftModifiedAt",
+        "activeConfigId",
+        "inputSchema",
+        "outputSchema",
+        "perUserMaxRunning",
+        "perUserMaxQueued",
+        "perAppMaxRunning",
+        "perAppMaxQueued",
+        "queueTtlSeconds",
+        "dequeueOrder",
+        "requiresClientApply",
+        "syncCallable",
+        "accessRule",
+        "metadataManifest",
+        "runAs",
+        "lock",
+        "capabilities",
+        "operationallyDisabled",
+        "createdBy",
+        "createdAt",
+        "modifiedAt",
+    ],
+};
+//# sourceMappingURL=generated-config-surfaces.js.map