primitive-admin 1.2.0-alpha.0 → 1.2.0-alpha.2

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

@@ -94,8 +94,8 @@ export function writableFieldNames(table, mode) {
  * 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.
+ * a handler still honors (`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.
@@ -401,8 +401,9 @@ export function acceptedGroupTomlKeys(table, group) {
  * is therefore an unknown key rather than one the payload builder silently
  * ignores (SO3626-013) — the builder reads a grouped field only from
  * `source[group][tomlKey]`, so accepting it here would drop the author's value
- * without a word. The nine deprecated flat chat keys stay accepted through
- * their `tomlOnlyKeys` declarations, which is what keeps old files pushing.
+ * without a word. A key whose root spelling was retired while it moved into a
+ * group (the flat chat keys, #3642) is refused the same way, with the guidance
+ * `RETIRED_TOML_SPELLINGS` states.
  */
 export function acceptedTomlKeys(table) {
     return new Set([
@@ -2343,9 +2344,11 @@ export const RETIRED_CONFIG_KEYS = {
                 "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.
+        // stay DECLARED in `models.yaml` as hidden attributes (#3993): never
+        // written, never echoed, refused by `config push`, the tenant PUT and the
+        // admin API alike, and read only by the fallback for a row that stores no
+        // `emailSignInEnabled`. A file or body 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 " +
@@ -2363,6 +2366,27 @@ export const RETIRED_CONFIG_KEYS = {
                 "send `emailSignInEnabled`.",
         },
     },
+    // #3996 — a bucket's access is `preset` (#1020). The old spelling stayed
+    // accepted as an alias, which left two vocabularies for one decision —
+    // `owner-only` still read as "the uploader", the bug #1020 fixed — and an
+    // echo whose value depended on the row's age. A file or body that still
+    // carries it is refused rather than mapped, so the author meets the new
+    // vocabulary once. The model attribute stays declared: a pre-#1020 row
+    // still resolves to its preset (`resolveBucketPreset`).
+    bucket: {
+        accessPolicy: {
+            toml: "`accessPolicy` is no longer authored in TOML (#3996): a bucket's " +
+                "access is `preset`. Map the value — `public-read` → `public`, " +
+                "`authenticated` → `authenticated`, `owner-only` → `admin-only` (it " +
+                "always meant app admins; `personal-uploads` is the per-uploader " +
+                "preset). Replace the line and push again, or `config pull` rewrites " +
+                "the file.",
+            request: "`accessPolicy` is retired (#3996): send `preset`. `public-read` → " +
+                "`public`, `authenticated` → `authenticated`, `owner-only` → " +
+                "`admin-only` (app admins; `personal-uploads` is the per-uploader " +
+                "preset).",
+        },
+    },
     // #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
@@ -2520,6 +2544,47 @@ export const RETIRED_CONFIG_KEYS = {
                 "Omit the field.",
         },
     },
+    // #3998 — a test-case sidecar names what it pins: the configuration it runs
+    // under and its judge prompt, by name, so the file means the same thing in
+    // every app. The id spellings were deprecated TOML-only keys that won over
+    // the name, and — unlike every other retired key — `config pull` still WROTE
+    // them whenever its id→name lookup missed, so the spelling kept being
+    // generated. Pull now reports such a case instead of writing an id.
+    //
+    // The three stay the stored references the admin API accepts on create and
+    // update, so the `request` wording below is never shown: `rememberRetiredKeys`
+    // and the admin API's unknown-key check both skip a key the wire accepts. It
+    // is here because the entry's shape requires it.
+    test: {
+        configId: {
+            toml: "`configId` is no longer authored in TOML (#3998): a test case names " +
+                "the configuration it runs under, so the file means the same thing in " +
+                "every app. Replace the line with `configName = \"…\"` (a " +
+                "`[[configs]]` name of the block this sidecar belongs to), or delete it " +
+                "to run the active configuration, and push again.",
+            request: "`configId` is the stored configuration reference; only its TOML " +
+                "spelling is retired (#3998). Sidecars author it as `configName`.",
+        },
+        evaluatorPromptId: {
+            toml: "`evaluatorPromptId` is no longer authored in TOML (#3998): a test " +
+                "case names its judge prompt, so the file means the same thing in " +
+                "every app. Replace the line with `evaluatorPromptKey = \"…\"` (the " +
+                "judge prompt's key) and push again.",
+            request: "`evaluatorPromptId` is the stored judge-prompt reference; only its " +
+                "TOML spelling is retired (#3998). Sidecars author it as " +
+                "`evaluatorPromptKey`.",
+        },
+        evaluatorConfigId: {
+            toml: "`evaluatorConfigId` is no longer authored in TOML (#3998): a test " +
+                "case names its judge's configuration, so the file means the same " +
+                "thing in every app. Replace the line with " +
+                "`evaluatorConfigName = \"…\"` (a `[[configs]]` name of the prompt " +
+                "`evaluatorPromptKey` names) and push again.",
+            request: "`evaluatorConfigId` is the stored judge-configuration reference; only " +
+                "its TOML spelling is retired (#3998). Sidecars author it as " +
+                "`evaluatorConfigName`.",
+        },
+    },
     // #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.
@@ -2539,6 +2604,47 @@ export const RETIRED_CONFIG_KEYS = {
 export function retiredConfigKey(prefix, key) {
     return RETIRED_CONFIG_KEYS[prefix]?.[key] ?? null;
 }
+// #3642 — the pre-#3626 flat spelling of one chat setting. The six keys an
+// agent's model round shares (`AGENT_CONFIG_KEYS`) also name the agent block.
+// The names are written out rather than read from `prompt-kinds.ts`, which the
+// vendored artifact places after this module.
+function flatChatKeySpelling(key, sharedWithAgent) {
+    return {
+        toml: `\`${key}\` is no longer authored flat under \`[[configs]]\` (#3642). ` +
+            "Chat settings live in the entry's `[configs.chat]` block" +
+            (sharedWithAgent ? " (`[configs.agent]` on an agent prompt)" : "") +
+            ": move the line into that block and push again. `config pull` " +
+            "rewrites a file whose prompt already exists on the server.",
+    };
+}
+/**
+ * Spellings retired from TOML while the key itself stays live on the wire,
+ * keyed like `RETIRED_CONFIG_KEYS`. The request side never reads this map: a
+ * body that sends one of these keys is a body the schema accepts.
+ */
+export const RETIRED_TOML_SPELLINGS = {
+    // #3642 — the nine chat keys at the prompt `[[configs]]` root. The admin
+    // API's create and update bodies still carry them flat; only the TOML
+    // grouping (#3626) moved them under `[configs.chat]`.
+    configs: {
+        systemPrompt: flatChatKeySpelling("systemPrompt", true),
+        userPromptTemplate: flatChatKeySpelling("userPromptTemplate", false),
+        temperature: flatChatKeySpelling("temperature", true),
+        topP: flatChatKeySpelling("topP", true),
+        maxTokens: flatChatKeySpelling("maxTokens", true),
+        outputFormat: flatChatKeySpelling("outputFormat", false),
+        outputSchema: flatChatKeySpelling("outputSchema", false),
+        reasoningEffort: flatChatKeySpelling("reasoningEffort", true),
+        reasoningBudget: flatChatKeySpelling("reasoningBudget", true),
+    },
+};
+/**
+ * The TOML guidance for `key` under `prefix`: a fully retired key's, else a
+ * retired spelling's, else null when the key is simply unknown.
+ */
+export function retiredTomlKey(prefix, key) {
+    return (retiredConfigKey(prefix, key) ?? RETIRED_TOML_SPELLINGS[prefix]?.[key] ?? null);
+}
 // ── src/config-surface/function-grants.ts ────────────────────────────────
 /**
  * The capability grammar for server functions — #3182 phase 1, rewritten by
@@ -4712,7 +4818,12 @@ export function checkCronTriggerEntry(entry) {
  * all read this one copy, so a refusal at push and a refusal at execution
  * cannot disagree.
  *
- * Provider facts this encodes:
+ * What this encodes is each provider's SPELLING, per model family — never
+ * which values a particular model accepts (#4147). A value the spelling can
+ * carry is sent, and a model that does not support it is refused by the
+ * provider, whose answer the run reports. A per-model table of accepted levels
+ * and floors went stale with each model release and refused or admitted the
+ * wrong values.
  *
  *  - OpenRouter takes a unified `reasoning` block: `{ effort }`,
  *    `{ max_tokens }`, or `{ enabled: false }` to decline it. `max_tokens` is an
@@ -4725,13 +4836,13 @@ export function checkCronTriggerEntry(entry) {
  *    is refused by OpenRouter and surfaces as a failed execution rather than a
  *    silent drop.
  *  - Gemini 3.x expresses thinking as a LEVEL
- *    (`thinkingConfig.thinkingLevel`) and cannot turn it off; `thinkingBudget`
- *    is accepted there only for backward compatibility and is translated to a
- *    level rather than honored as a bound, so a numeric budget is refused with
- *    a pointer at `reasoningEffort`.
+ *    (`thinkingConfig.thinkingLevel`), and the level spelling has no "off"
+ *    value, so `none` has nothing to translate to. `thinkingBudget` is accepted
+ *    there only for backward compatibility and is translated to a level rather
+ *    than honored as a bound, so a numeric budget is refused with a pointer at
+ *    `reasoningEffort`.
  *  - Gemini 2.5 expresses it as a numeric BUDGET
- *    (`thinkingConfig.thinkingBudget`); `0` turns thinking off on Flash and
- *    Flash-Lite, while Pro has a floor of 128 and answers 400 for less.
+ *    (`thinkingConfig.thinkingBudget`); `none` is a budget of `0`.
  *  - Gemini 2.0 and earlier have no thinking control at all.
  */
 /** The provider-neutral effort levels a config may state. */
@@ -4742,8 +4853,6 @@ export const REASONING_EFFORTS = [
     "medium",
     "high",
 ];
-/** The smallest budget Gemini 2.5 Pro accepts; it cannot stop thinking. */
-export const GEMINI_PRO_MIN_THINKING_BUDGET = 128;
 export function geminiReasoningFamily(model) {
     const match = /gemini-(\d+)(?:[.-](\d+))?/i.exec(model || "");
     if (!match)
@@ -4758,10 +4867,6 @@ export function geminiReasoningFamily(model) {
         return "budget";
     return "none";
 }
-/** Gemini Pro: the tier that cannot stop thinking in either family. */
-export function isGeminiProModel(model) {
-    return /(^|[-_/.])pro($|[-_/.])/i.test(model || "");
-}
 /** Is EITHER reasoning key stated on this config? */
 export function hasPromptReasoning(input) {
     return (normalizeEffort(input.reasoningEffort) !== null ||
@@ -4845,7 +4950,6 @@ function openRouterDirective(effort, budget) {
 }
 function geminiResolution(model, effort, budget) {
     const family = geminiReasoningFamily(model);
-    const isPro = isGeminiProModel(model);
     if (family === "none") {
         return {
             ok: false,
@@ -4868,15 +4972,10 @@ function geminiResolution(model, effort, budget) {
         if (effort === "none") {
             return {
                 ok: false,
-                error: `Gemini model '${model}' cannot turn thinking off. The lowest level it ` +
-                    `accepts is '${isPro ? "low" : "minimal"}'.`,
-            };
-        }
-        if (isPro && (effort === "minimal" || effort === "medium")) {
-            return {
-                ok: false,
-                error: `Gemini Pro model '${model}' accepts only 'low' or 'high' as a ` +
-                    `thinking level; '${effort}' is a Flash-only level.`,
+                error: `Gemini model '${model}' expresses reasoning as a LEVEL, which has no ` +
+                    "'none' value. Use reasoningEffort " +
+                    `(${REASONING_EFFORTS.filter((e) => e !== "none").join(", ")}); the ` +
+                    "provider's model documentation lists which levels this model accepts.",
             };
         }
         return {
@@ -4897,14 +4996,6 @@ function geminiResolution(model, effort, budget) {
         };
     }
     const resolved = effort === "none" ? 0 : budget;
-    if (isPro && resolved < GEMINI_PRO_MIN_THINKING_BUDGET) {
-        return {
-            ok: false,
-            error: `Gemini Pro model '${model}' cannot turn thinking off: its smallest ` +
-                `thinking budget is ${GEMINI_PRO_MIN_THINKING_BUDGET} tokens, and ` +
-                `${resolved} is refused by the provider.`,
-        };
-    }
     return {
         ok: true,
         directive: {
@@ -4944,12 +5035,16 @@ function geminiResolution(model, effort, budget) {
  */
 export const PROMPT_KINDS = ["chat", "decisions", "agent"];
 /**
- * The nine chat settings that existed before `[configs.chat]` did. Only these
- * keep the deprecated FLAT spelling (#3642): a key added to the block later was
- * never written flat by any file, so it has none (the `questions` posture,
- * SO3626-013).
+ * The settings that describe a CHAT COMPLETION and nothing else. They are
+ * authored under `[configs.chat]` and only there: the pre-#3626 flat spelling
+ * of the first nine is retired and refused at push (#3642,
+ * `RETIRED_TOML_SPELLINGS`).
+ *
+ * #3801 — `strictOutput`, the opt-in that sends `[prompt].outputSchema` as a
+ * strict `json_schema` on OpenRouter (`prompt-strict-output.ts`). Not an agent
+ * key (§D1: an agent has no output schema), so the agent arm refuses it.
  */
-export const LEGACY_FLAT_CHAT_KEYS = [
+export const CHAT_CONFIG_KEYS = [
     "systemPrompt",
     "userPromptTemplate",
     "temperature",
@@ -4959,18 +5054,6 @@ export const LEGACY_FLAT_CHAT_KEYS = [
     "outputSchema",
     "reasoningEffort",
     "reasoningBudget",
-];
-/**
- * The settings that describe a CHAT COMPLETION and nothing else. They are
- * authored under `[configs.chat]`; the flat spelling of the nine legacy keys
- * is deprecated (#3642).
- *
- * #3801 — `strictOutput`, the opt-in that sends `[prompt].outputSchema` as a
- * strict `json_schema` on OpenRouter (`prompt-strict-output.ts`). Not an agent
- * key (§D1: an agent has no output schema), so the agent arm refuses it.
- */
-export const CHAT_CONFIG_KEYS = [
-    ...LEGACY_FLAT_CHAT_KEYS,
     "strictOutput",
 ];
 /** The settings that describe a DECISIONS request. */
@@ -5406,45 +5489,6 @@ export function resolveDecisionsRunQuestions(questions, runCriteria) {
     }
     return { ok: true, questions: resolved };
 }
-/**
- * Move the deprecated flat chat keys of one `[[configs]]` entry under `chat`
- * — #3626 §4, the blob-bucket `accessPolicy` precedent made reusable.
- *
- * Push keeps accepting the nine keys flat so no existing file breaks, and pull
- * rewrites them, so one pull-then-push migrates a file. A key present in BOTH
- * spellings is not merged: the grouped value is left standing and the key is
- * reported in `conflicts`, which the caller turns into a refusal naming the
- * entry. Nothing else in the entry is touched — `providerConfig` is
- * provider-keyed rather than chat-keyed (D3626-002) and `questions` has no flat
- * spelling at all (SO3626-013).
- */
-export function hoistDeprecatedChatKeys(entry) {
-    if (!isPlainObject(entry)) {
-        return { entry: {}, moved: [], conflicts: [] };
-    }
-    const out = { ...entry };
-    const existingGroup = isPlainObject(out.chat) ? { ...out.chat } : undefined;
-    const group = existingGroup ?? {};
-    const moved = [];
-    const conflicts = [];
-    // #3801 — only the legacy keys have a flat spelling to hoist; `strictOutput`
-    // at the root is an unknown key naming its block.
-    for (const key of LEGACY_FLAT_CHAT_KEYS) {
-        if (!(key in out))
-            continue;
-        if (existingGroup && key in existingGroup) {
-            conflicts.push(key);
-            delete out[key];
-            continue;
-        }
-        group[key] = out[key];
-        delete out[key];
-        moved.push(key);
-    }
-    if (existingGroup || moved.length > 0)
-        out.chat = group;
-    return { entry: out, moved: moved.sort(), conflicts: conflicts.sort() };
-}
 // ── src/config-surface/prompt-strict-output.ts ───────────────────────────
 /**
  * Strict output for a chat config — issue #3801 (project `agents`, §D6).
@@ -5655,16 +5699,20 @@ export const AGENT_ERROR_CODES = [
     "AGENT_ROUND_EMPTY",
 ];
 /**
- * The platform maximums. An agent may lower `maxSteps` and `waitLimitSeconds`,
- * never raise them; the tool and event counts bound what one declaration can
- * make every turn carry (principle 2).
+ * The platform maximums. An agent may lower `maxSteps`, `waitLimitSeconds`
+ * and `maxRowBytes`, never raise them; the tool and event counts bound what
+ * one declaration can make every turn carry (principle 2).
  */
 export const AGENT_LIMITS = {
     maxSteps: 25,
     waitLimitSeconds: 604800,
+    /** The JSON bytes of one session-document row a turn writes from model or tool output. */
+    maxRowBytes: 262144,
     tools: 64,
     events: 64,
 };
+/** The smallest row ceiling an agent may declare: room for a call's own columns. */
+export const AGENT_ROW_BYTES_FLOOR = 1024;
 /**
  * A tool or event name: the intersection of OpenRouter's and Gemini's
  * function-name rules, so one declaration maps onto either provider.
@@ -5677,6 +5725,7 @@ const AGENT_TOP_LEVEL_KEYS = [
     "answeredBy",
     "maxSteps",
     "waitLimitSeconds",
+    "maxRowBytes",
     "turnContext",
     "history",
     "tools",
@@ -5767,13 +5816,13 @@ function agentSchemaError(value, path) {
     return agentInvalid(path, `must be a table (a JSON Schema object); found ${found}. Write it as ` +
         "TOML tables, or as an object inside a block written as one JSON string");
 }
-function agentIntegerInRange(value, path, max, out) {
+function agentIntegerInRange(value, path, max, out, min = 1) {
     if (typeof value !== "number" || !Number.isInteger(value)) {
-        out.push(agentInvalid(path, `must be an integer from 1 to ${max}`));
+        out.push(agentInvalid(path, `must be an integer from ${min} to ${max}`));
         return;
     }
-    if (value < 1 || value > max) {
-        out.push(agentInvalid(path, `must be from 1 to ${max} (the platform maximum); found ${value}`));
+    if (value < min || value > max) {
+        out.push(agentInvalid(path, `must be from ${min} to ${max} (the platform maximum); found ${value}`));
     }
 }
 function checkAgentName(value, path, seen, what, out) {
@@ -5893,6 +5942,9 @@ function agentShapeRefusals(agent) {
     if (agent.waitLimitSeconds !== undefined) {
         agentIntegerInRange(agent.waitLimitSeconds, "waitLimitSeconds", AGENT_LIMITS.waitLimitSeconds, out);
     }
+    if (agent.maxRowBytes !== undefined) {
+        agentIntegerInRange(agent.maxRowBytes, "maxRowBytes", AGENT_LIMITS.maxRowBytes, out, AGENT_ROW_BYTES_FLOOR);
+    }
     if (agent.turnContext !== undefined) {
         const turnContext = agent.turnContext;
         if (!agentIsPlainObject(turnContext)) {
@@ -6125,6 +6177,7 @@ export function normalizeAgentDeclaration(declaration) {
         answeredBy: source.answeredBy ?? "initiator",
         maxSteps: source.maxSteps ?? AGENT_LIMITS.maxSteps,
         waitLimitSeconds: source.waitLimitSeconds ?? AGENT_LIMITS.waitLimitSeconds,
+        maxRowBytes: source.maxRowBytes ?? AGENT_LIMITS.maxRowBytes,
         turnContext: source.turnContext ?? null,
         history: source.history ?? null,
         tools: (source.tools ?? []).map((tool) => ({
@@ -6869,28 +6922,6 @@ const PROMPT_HANDLER = "src/admin-api.ts";
  * and output keys (`AGENT_CONFIG_KEYS`).
  */
 const SHARED_WITH_AGENT = ["chat", "agent"];
-/**
- * #3626 §4 — the nine chat keys, still accepted FLAT under `[[configs]]`.
- *
- * The blob-bucket `accessPolicy` precedent: declared `deprecated`, so
- * `config push` keeps taking a file written before the `[configs.chat]` block
- * existed, while `config pull` never writes the spelling again. One
- * pull-then-push migrates a file. `hoistDeprecatedChatKeys` moves them into the
- * group before the payload is built; rejecting the flat spelling outright is
- * #3642. #3801 — only the nine: a chat key added later (`strictOutput`) was
- * never written flat, so it has no deprecated spelling to accept.
- */
-const DEPRECATED_FLAT_CHAT_KEYS = Object.fromEntries(LEGACY_FLAT_CHAT_KEYS.map((key) => [
-    key,
-    {
-        kind: "deprecated",
-        note: `#3626 — the pre-kind spelling of \`[configs.chat].${key}\`. Still ` +
-            "accepted flat so no existing prompt file breaks (push hoists it " +
-            "into the block and warns); `config pull` writes only the grouped " +
-            "spelling, so one pull-then-push migrates the file. Rejecting the " +
-            "flat spelling is #3642.",
-    },
-]));
 export const PROMPT_SURFACE = {
     label: "prompt",
     tables: [
@@ -7100,7 +7131,7 @@ export const PROMPT_SURFACE = {
                     note: "#3626 — the chat-completion settings of a `kind = \"chat\"` " +
                         "prompt: the nine keys that describe a chat call and nothing " +
                         "else. Authored under `[configs.chat]`; the flat spelling is " +
-                        "accepted as deprecated (#3642) and rewritten by `config pull`.",
+                        "retired (#3642) and refused at push with `RETIRED_TOML_SPELLINGS`.",
                 },
                 decisions: {
                     note: "#3626 — the settings of a `kind = \"decisions\"` prompt: the " +
@@ -7385,8 +7416,6 @@ export const PROMPT_SURFACE = {
                         "active entry; push enacts it through the activate endpoint " +
                         "(activatePromptConfig), never as a config-body key.",
                 },
-                // #3626 §4 — the nine chat keys in their pre-kind FLAT spelling.
-                ...DEPRECATED_FLAT_CHAT_KEYS,
             },
             responseOnlyKeys: {},
         },
@@ -8213,9 +8242,12 @@ export const CRON_TRIGGER_SURFACE = {
  * `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.
+ * the retention tier is fixed at creation. `preset` and the rule set are the two
+ * halves of the access model (#1020), and the only access keys: at most one may
+ * change per request, which is the controller's rule and stays there. The rule
+ * set is authored by name (`ruleSetName`) and sent as `ruleSetId`, as the type
+ * configs do (#4116); the id spelling in TOML is deprecated. The pre-#1020
+ * `accessPolicy` spelling is a retired key (#3996, `retired-keys.ts`).
  */
 const BLOB_BUCKET_HANDLER = "src/app-api/controllers/blob-buckets-controller.ts";
 export const BLOB_BUCKET_SURFACE = {
@@ -8264,12 +8296,14 @@ export const BLOB_BUCKET_SURFACE = {
                 },
                 {
                     field: "ruleSetId",
-                    tomlKey: "ruleSetId",
+                    tomlKey: "ruleSetName",
                     type: "string",
                     emit: "whenSet",
                     writableOn: BOTH,
-                    // Existence-checked against AccessRuleSet; mutually exclusive with a
-                    // preset change in the same request.
+                    // Authored as a name, sent as an id (#4116), so a tree copied into
+                    // another app binds that app's rule set. Existence-checked against
+                    // AccessRuleSet; mutually exclusive with a preset change in the same
+                    // request.
                     validation: handledBy(BLOB_BUCKET_HANDLER, "BlobBucketsController", "apply"),
                 },
             ],
@@ -8294,11 +8328,11 @@ export const BLOB_BUCKET_SURFACE = {
                         "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).",
+                    kind: "server-owned",
+                    note: "RETIRED from the write surface by #3996, superseded by `preset` " +
+                        "(#1020). The attribute stays declared so `resolveBucketPreset` " +
+                        "can read a pre-#1020 row; no write path accepts it and no " +
+                        "serializer emits it.",
                 },
                 createdBy: {
                     kind: "server-owned",
@@ -8319,11 +8353,13 @@ export const BLOB_BUCKET_SURFACE = {
                     note: "The bucket key. `config pull` writes it for readability; push takes " +
                         "the identity from the file name and attaches `bucketKey` itself.",
                 },
-                accessPolicy: {
+                ruleSetId: {
                     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`.",
+                    note: "The id spelling of the rule-set reference (#4116). An id names a " +
+                        "rule set in one app, so a copied tree cannot resolve it; " +
+                        "`ruleSetName` is the authored key. Still accepted on push, with " +
+                        "an advisory line, and `config pull` rewrites the file to " +
+                        "`ruleSetName`. Retiring it is a later change of its own.",
                 },
             },
             responseOnlyKeys: {},
@@ -9552,11 +9588,13 @@ export const SERVER_FUNCTION_SURFACE = {
  * 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` /
+ * Three fields are stored as ids and AUTHORED as names — `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`.
+ * across apps. The id spellings are retired from the TOML surface (#3998):
+ * `config push` refuses a sidecar that still carries one, with the guidance in
+ * `retired-keys.ts`, and `config pull` reports a reference it cannot resolve
+ * rather than writing an id. On the wire the three stay ids.
  *
  * Three more are stored as JSON strings and carried in TOML as JSON strings
  * (`inputVariables`, `expectedOutputContains`, `expectedJsonSubset`) while the
@@ -9733,23 +9771,7 @@ export const TEST_CASE_SURFACE = {
                     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`.",
-                },
-            },
+            tomlOnlyKeys: {},
             responseOnlyKeys: {},
         },
     ],
@@ -9877,6 +9899,33 @@ export const APP_SETTINGS_SURFACE = {
                     // offline work around it (`parseLargeDocumentWindowSetting`).
                     validation: handledBy(SETTINGS_HANDLER, "SettingsController", "apply"),
                 },
+                {
+                    field: "rootDocumentFormat",
+                    tomlKey: "rootDocumentFormat",
+                    type: "number",
+                    // Whenever the app chose one. An app that never did mints legacy
+                    // roots, and a pulled file should not grow a key for it (#4195).
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    // 1, 2 or cleared; anything else is refused, because a root's format
+                    // is permanent and the mint must never guess
+                    // (`parseRootDocumentFormatSetting`).
+                    validation: handledBy(SETTINGS_HANDLER, "SettingsController", "apply"),
+                },
+                {
+                    field: "protected",
+                    tomlKey: "protected",
+                    type: "boolean",
+                    // Always: a pulled file states whether the app is live with real
+                    // users, rather than leaving it to the absence of a key (#3886).
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    // Strict boolean, and only the app's console owner or a super-admin
+                    // may CHANGE it; a body carrying the stored value is a no-op for
+                    // anyone the route admits (`resolveProtectedFlagWrite`,
+                    // `src/services/protected-app.ts`).
+                    validation: handledBy(SETTINGS_HANDLER, "SettingsController", "apply"),
+                },
             ],
             notExposed: {
                 appId: {
@@ -9891,6 +9940,58 @@ export const APP_SETTINGS_SURFACE = {
                     kind: "server-owned",
                     note: "Admin who created the app; assigned server-side.",
                 },
+                // Child apps: lineage is set when a child is created and never
+                // changes; expiry and activity are written by the server. The admin
+                // update route refuses a changed value of any of these.
+                parentAppId: {
+                    kind: "server-owned",
+                    note: "A child's parent app; set at creation, never authored.",
+                },
+                childSlug: {
+                    kind: "server-owned",
+                    note: "A child's slug under its parent; set at creation, never authored.",
+                },
+                parentSlugKey: {
+                    kind: "server-owned",
+                    note: "The `<parentAppId>#<slug>` uniqueness key of a child.",
+                },
+                ownerAdminId: {
+                    kind: "server-owned",
+                    note: "The admin who owns a child; the creator, set at creation.",
+                },
+                branch: {
+                    kind: "server-owned",
+                    note: "The git branch a child was created from; set at creation.",
+                },
+                idleDays: {
+                    kind: "server-owned",
+                    note: "Days of inactivity before a child expires; set at creation.",
+                },
+                expiresAt: {
+                    kind: "server-owned",
+                    note: "When a child expires; maintained by the server.",
+                },
+                warnedForExpiresAt: {
+                    kind: "server-owned",
+                    note: "The expiry a child's owner was last warned about.",
+                },
+                deletingAt: {
+                    kind: "server-owned",
+                    note: "When the expiry sweep claimed a child for deletion.",
+                },
+                previewOrigins: {
+                    kind: "server-owned",
+                    note: "A child's preview origins; written only by the preview-origins " +
+                        "route, so sync never sees it.",
+                },
+                childPartition: {
+                    kind: "server-owned",
+                    note: "The constant partition of the child-only expiry index.",
+                },
+                lastActivityAt: {
+                    kind: "server-owned",
+                    note: "When the app last saw counted activity; written by the server.",
+                },
                 passkeyRpId: {
                     kind: "server-owned",
                     note: "RETIRED from the write surface by #2891, superseded by " +
@@ -9924,15 +10025,17 @@ export const APP_SETTINGS_SURFACE = {
                     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.",
+                        "link — so there is no method to enable separately. Hidden " +
+                        "since #3993: never written, never echoed, refused on write; " +
+                        "read only by the email sign-in fallback for a row that stores " +
+                        "no `emailSignInEnabled`.",
                 },
                 otpEnabled: {
                     kind: "server-owned",
                     note: "The other half of the retired pair (#2884); superseded by " +
-                        "`emailSignInEnabled` and mirrored the same way.",
+                        "`emailSignInEnabled`. Hidden since #3993 the same way: never " +
+                        "written, never echoed, refused on write; read only by the " +
+                        "email sign-in fallback.",
                 },
                 redirectUris: {
                     kind: "server-owned",
@@ -10314,6 +10417,20 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "memberInvitationsEnabled",
         "memberInvitationLimit",
         "largeDocumentWindowDays",
+        "rootDocumentFormat",
+        "protected",
+        "parentAppId",
+        "childSlug",
+        "parentSlugKey",
+        "ownerAdminId",
+        "branch",
+        "idleDays",
+        "expiresAt",
+        "warnedForExpiresAt",
+        "deletingAt",
+        "previewOrigins",
+        "childPartition",
+        "lastActivityAt",
         "createdAt",
         "modifiedAt",
     ],