primitive-admin 1.2.0-alpha.3 → 1.2.0-alpha.5

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

@@ -2386,6 +2386,21 @@ export const RETIRED_CONFIG_KEYS = {
                 "`admin-only` (app admins; `personal-uploads` is the per-uploader " +
                 "preset).",
         },
+        // #4283 — #4116 made the bucket author its rule set by name and kept the
+        // id spelling as a deprecated key. Its own sentence rather than the type
+        // configs' shared one, which says a pulled file already spells the name:
+        // a bucket file pulled before #4116 does not. The `request` half is never
+        // surfaced, for the reason given at `RULE_SET_ID_RETIRED`.
+        ruleSetId: {
+            toml: "`ruleSetId` is no longer authored in TOML (#4283). A rule-set id " +
+                "names a row in one app and resolves to nothing in another, so the " +
+                "reference is authored by name: replace this line with " +
+                '`ruleSetName = "<name>"`, where the name is the `name` the rule ' +
+                "set's own `rule-sets/<key>.toml` declares, and push again, or " +
+                "`config pull` rewrites the file.",
+            request: "`ruleSetId` is the live request key on this surface; only its TOML " +
+                "spelling is retired (#4283). Send the rule set's id.",
+        },
     },
     // #2645 — pausing moved off `state` onto its own field, so `state` stopped
     // being author-writable rather than becoming a second way to say "paused".
@@ -2423,9 +2438,46 @@ export const RETIRED_CONFIG_KEYS = {
         },
     },
     // #3997 — keyed by each table's TOML prefix. Only `database-type-config`
-    // uses `[type]`, so that entry cannot reach another surface; the blob
-    // bucket's `[bucket] ruleSetId` is its live key and is not listed.
-    type: { ruleSetId: RULE_SET_ID_RETIRED },
+    // uses `[type]`, so that entry cannot reach another surface. The blob
+    // bucket's `[bucket] ruleSetId` has its own entry under `bucket` (#4283).
+    //
+    // #3189 — server-functions phase 6 retires database operations, and with
+    // them the two type-level CEL keys that existed for operations: the access
+    // an operation inherited and the gate on the (already retired, #3991)
+    // database CEL context. Data access goes through a function, whose `access`
+    // gate is the authorization; per-database values are resource metadata
+    // categories. Refused rather than ignored: a file that keeps the line would
+    // otherwise read as though it still gated something.
+    type: {
+        ruleSetId: RULE_SET_ID_RETIRED,
+        defaultAccess: {
+            toml: "`defaultAccess` is no longer a database type key (#3189): it was the " +
+                "access database operations inherited, and operations are retired. " +
+                "Read and write the type's records from a function — its `access` " +
+                "gate is the authorization. Delete the line and push again.",
+            request: "`defaultAccess` is retired (#3189): it was the access database " +
+                "operations inherited, and operations are retired. Gate data access " +
+                "with a function's `access` rule; omit the field.",
+        },
+        celContextAccess: {
+            toml: "`celContextAccess` is no longer a database type key (#3189): the " +
+                "database CEL context it gated is gone (#3991). Per-database values " +
+                "are resource metadata categories, each with its own readRule and " +
+                "writeRule. Delete the line and push again.",
+            request: "`celContextAccess` is retired (#3189): the database CEL context it " +
+                "gated is gone (#3991). Use a resource metadata category; omit the " +
+                "field.",
+        },
+        metadataAccess: {
+            toml: "`metadataAccess` is no longer a database type key (#3189): it was " +
+                "the legacy spelling of `celContextAccess`, which gated the retired " +
+                "database CEL context (#3991). Per-database values are resource " +
+                "metadata categories. Delete the line and push again.",
+            request: "`metadataAccess` is retired (#3189): the database CEL context it " +
+                "gated is gone (#3991). Use a resource metadata category, which has " +
+                "its own readRule and writeRule; omit the field.",
+        },
+    },
     groupTypeConfig: { ruleSetId: RULE_SET_ID_RETIRED },
     collectionTypeConfig: { ruleSetId: RULE_SET_ID_RETIRED },
     // #2803 — the OBJECT-level availability leaves TOML. The per-version
@@ -2600,6 +2652,41 @@ export const RETIRED_CONFIG_KEYS = {
         },
     },
 };
+/**
+ * Top-level TOML tables a configuration object's FILE retired — keyed by the
+ * surface's label, then by the table key. Only the TOML half exists: these were
+ * sub-trees applied through their own endpoints, never request keys of the
+ * object itself, so no request body can carry one.
+ *
+ * Without an entry here a retired table would be answered as an unrecognized
+ * one ("check the spelling, or upgrade the CLI"), which is backwards for a
+ * table removed on purpose.
+ */
+export const RETIRED_DOCUMENT_KEYS = {
+    // #3189 — server-functions phase 6 retires database operations and
+    // type-scoped subscriptions. Data access and change feeds are a function's
+    // now; the rows the two tables created are swept at deploy.
+    "database-type-config": {
+        operations: {
+            toml: "`[[operations]]` is no longer part of a database type file (#3189): " +
+                "database operations are retired. Read and write the type's records " +
+                "from a function (`ctx.db(<databaseId>).model(<Model>)`), and call the " +
+                "function from the client. Delete every `[[operations]]` block and " +
+                "push again.",
+        },
+        subscriptions: {
+            toml: "`[[subscriptions]]` is no longer part of a database type file " +
+                "(#3189): type-scoped subscriptions are retired. Publish changes on a " +
+                "channel from the function that writes them " +
+                "(`ctx.channels.authorize` / `ctx.channels.publish`). Delete every " +
+                "`[[subscriptions]]` block and push again.",
+        },
+    },
+};
+/** The retired-table guidance for `key` on the surface labelled `label`, or null. */
+export function retiredDocumentKey(label, key) {
+    return RETIRED_DOCUMENT_KEYS[label]?.[key] ?? null;
+}
 /** 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;
@@ -3336,7 +3423,8 @@ export function parseFunctionManifest(value) {
 // ── src/config-surface/function-retired-keys.ts ──────────────────────────
 /**
  * The runtime keys a `functions/<key>.toml` no longer decides anything with —
- * #3482, project `server-functions` phase 4.
+ * #3482 retired them, and #3188 (project `server-functions` phase 5) refuses
+ * them.
  *
  * The sponsor settled it on 2026-09-15 (the intent, "Mode vocabulary?",
  * amended again): the config says NOTHING about how a function runs. A
@@ -3345,44 +3433,50 @@ export function parseFunctionManifest(value) {
  * and a function that must not run under one runtime tests for it in code with
  * `assertRuntime`.
  *
- * ── Why these keys are accepted, not refused ──────────────────────────────
+ * ── Accepted through phase 4, refused from phase 5 ────────────────────────
  *
- * Every tree pushed since #3454 that declares a cron trigger carries
- * `mode = …` ON THE ENTRY, because `cron-trigger-mode-required` demanded it;
- * plenty carry a top-level `mode` or the older `durable`. Removing the keys
- * from the accepted set outright would refuse those trees with an unknown-key
- * error one day after the platform insisted on them, which is the opposite of
- * principle 5 inside a non-breaking phase.
+ * Every tree pushed since #3454 that declares a cron trigger carried
+ * `mode = …` ON THE ENTRY, because `cron-trigger-mode-required` demanded it,
+ * so #3482 accepted the keys and warned rather than refusing them one day
+ * after the platform insisted on them. Phase 5 is the declared breaking phase
+ * that ends the grace: `mode`, `durable` and a cron entry's `mode` are refused
+ * with one sentence per key, naming the key, saying the caller picks the
+ * runtime, and saying to delete the line. `config pull` still strips them
+ * (`stripRetiredFunctionKeys` in the CLI reads this scanner), so a tree pulled
+ * from a version pushed before the retirement pushes again unchanged.
  *
- * So through phase 4 they are ACCEPTED and IGNORED, with one warning per key
- * naming it and the line to delete; from phase 5 (#3188) they are refused with
- * the rest of the retirement matrix. The value is not validated — there is
- * nothing left to validate it against, and refusing a bad value for a key
- * nobody reads would be a refusal about spelling alone.
+ * One rule id, one handler: `refusedFunctionKeys` is declared `preflight` on
+ * the `function` surface and the CLI's push preflight runs it before the first
+ * request. The value is not validated — the key's PRESENCE is the refusal.
  *
- * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity). Both
- * the CLI preflight (vendored by `cli/scripts/gen-config-surfaces.mjs`) and the
- * admin config-version route read this one scanner, so the warning an author
- * sees from `config push` is the sentence the API answers with.
+ * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity). The
+ * CLI preflight reaches this module through the vendored copy
+ * (`cli/scripts/gen-config-surfaces.mjs`), so the sentence an author reads from
+ * `config push` is the one this module writes.
  */
 /** The two `[function]` keys that no longer say anything (#3482). */
 export const RETIRED_FUNCTION_RUNTIME_KEYS = ["mode", "durable"];
+/**
+ * The rule ids this module owns, declared on the `function` surface (#3374's
+ * anchor). One id covers the three spellings: they are one rule — the config
+ * does not choose the runtime — met in three places.
+ */
+export const RETIRED_RUNTIME_KEY_RULE_IDS = ["retired-runtime-key"];
+/** The one refusal constructor (#3373's anchor). */
+function refuseRuntimeKey(ruleId, path, message) {
+    return { ruleId, path, message };
+}
 const RUNTIME_IS_THE_CALLERS = "a function is a function, and the caller picks the runtime at each call — " +
     "`invoke` runs it inside the request, `start` runs it as a task";
-const FROM_PHASE_5 = "Remove the line; from phase 5 it is refused.";
 /**
- * Every retired runtime key a `[function]` table still carries.
+ * Every retired runtime key a `[function]` table carries.
  *
  * Reads the table the way the author wrote it: the two top-level keys, and a
- * `mode` on each `[[function.triggers.cron]]` entry. A cron entry's sentence
- * says the extra thing its author needs to hear — that the schedule no longer
- * chooses, because every fire starts a task run (#3334's runner branch is
- * gone).
- *
- * Order is the order an author reads their file in: the top-level keys first,
- * then the cron entries in declaration order.
+ * `mode` on each `[[function.triggers.cron]]` entry. Order is the order an
+ * author reads their file in: the top-level keys first, then the cron entries
+ * in declaration order.
  */
-export function ignoredFunctionKeys(functionTable) {
+function retiredKeySites(functionTable) {
     const table = functionTable;
     if (!table || typeof table !== "object" || Array.isArray(table))
         return [];
@@ -3390,10 +3484,7 @@ export function ignoredFunctionKeys(functionTable) {
     for (const key of RETIRED_FUNCTION_RUNTIME_KEYS) {
         if (table[key] === undefined)
             continue;
-        found.push({
-            path: key,
-            message: `\`${key}\` is ignored (#3482): ${RUNTIME_IS_THE_CALLERS}. ${FROM_PHASE_5}`,
-        });
+        found.push({ path: key, cronEntry: null, key });
     }
     const triggers = table.triggers;
     const rawCron = triggers && typeof triggers === "object" && !Array.isArray(triggers)
@@ -3411,19 +3502,38 @@ export function ignoredFunctionKeys(functionTable) {
             return;
         const rawName = entry.name;
         const name = typeof rawName === "string" && rawName ? rawName : `#${index + 1}`;
-        found.push({
-            path: `triggers.cron.${name}.mode`,
-            message: `\`mode\` on cron trigger '${name}' is ignored (#3482): every cron ` +
-                `fire starts a task run, and ${RUNTIME_IS_THE_CALLERS}. ${FROM_PHASE_5}`,
-        });
+        found.push({ path: `triggers.cron.${name}.mode`, cronEntry: name, key: "mode" });
     });
     return found;
 }
+/**
+ * Every retired runtime key the table carries, each as the refusal the author
+ * reads. A cron entry's sentence says the extra thing its author needs to hear
+ * — that the schedule no longer chooses, because every fire starts a task run.
+ */
+export function refusedFunctionKeys(functionTable) {
+    return retiredKeySites(functionTable).map((site) => refuseRuntimeKey("retired-runtime-key", site.path, site.cronEntry === null
+        ? `\`${site.key}\` is not a key of a function: ${RUNTIME_IS_THE_CALLERS}. ` +
+            "Delete the line."
+        : `\`mode\` on cron trigger '${site.cronEntry}' is not a key of a ` +
+            `function: every cron fire starts a task run, and ${RUNTIME_IS_THE_CALLERS}. ` +
+            "Delete the line."));
+}
+/**
+ * The same refusals, rendered for one file — the shape `config push` and
+ * `config diff` print.
+ *
+ * `label` is what the reader can act on: `functions/<key>.toml` from the CLI,
+ * and the function's key from the API, which has no file to name.
+ */
+export function refusedFunctionKeyMessages(label, functionTable) {
+    return refusedFunctionKeys(functionTable).map((refusal) => `${label}: ${refusal.message}`);
+}
 /**
  * The database types a `[function]` table's retired trigger block names —
  * #3483.
  *
- * Beside `ignoredFunctionKeys` because it answers the same question about the
+ * Beside `refusedFunctionKeys` because it answers the same question about the
  * same table, for the same reader: `config pull` writes a version's AUTHORED
  * bytes, and a version pushed before the removal carries the block. Without
  * this the pulled tree would be refused on its next push — a tree an author
@@ -3484,16 +3594,6 @@ function retiredDatabaseTriggerValue(functionTable) {
     }
     return triggers.database;
 }
-/**
- * The same scan, rendered for one file — the shape `config push` and
- * `config diff` print and the admin route answers with.
- *
- * `label` is what the reader can act on: `functions/<key>.toml` from the CLI,
- * and the function's key from the API, which has no file to name.
- */
-export function ignoredFunctionKeyWarnings(label, functionTable) {
-    return ignoredFunctionKeys(functionTable).map((ignored) => `${label}: ${ignored.message}`);
-}
 export const EMPTY_TRIGGER_DECLARATION = {
     webhook: null,
     cron: [],
@@ -4194,7 +4294,10 @@ export function validateSigningSecretDeclaration(input) {
  * `preflight`.
  */
 /** The rule ids this module owns — the union type below anchors them (#3373). */
-export const WORKFLOW_RULE_IDS = ["system-access-rule"];
+export const WORKFLOW_RULE_IDS = [
+    "system-access-rule",
+    "retired-database-step-kind",
+];
 /** The one refusal constructor: a new branch cannot compile without an id. */
 function refuseWorkflowRule(ruleId, message) {
     return { ruleId, message };
@@ -4217,6 +4320,64 @@ export function checkWorkflowSystemAccessRule(input) {
     }
     return null;
 }
+/**
+ * The DSL step kinds that executed a registered database operation (#3189,
+ * phase 6 of project `server-functions`, matrix row M8).
+ *
+ * Every `database.*` runner except `database.syncIndexes` called
+ * `DatabaseOperationsController.execute`, so retiring database operations
+ * retires these fourteen kinds with them: the seven base kinds and their seven
+ * `*ForUser` twins. `database.syncIndexes` (which calls the records index
+ * route), `database.create` and `database.delete` (resource lifecycle) are not
+ * here and keep running until the engine retires.
+ */
+export const RETIRED_DATABASE_STEP_KINDS = [
+    "database.query",
+    "database.mutate",
+    "database.count",
+    "database.aggregate",
+    "database.pipeline",
+    "database.applyToQuery",
+    "database.batch",
+    "database.queryForUser",
+    "database.mutateForUser",
+    "database.countForUser",
+    "database.aggregateForUser",
+    "database.pipelineForUser",
+    "database.applyToQueryForUser",
+    "database.batchForUser",
+];
+/**
+ * Every step in a definition — or the one step a run has reached — whose kind
+ * is a retired database kind, with the sentence naming the replacement.
+ *
+ * Walks the top-level `steps` and a `collect` step's nested `step`, the one
+ * place a step definition nests another. Push (the CLI preflight), save, the
+ * activation lint and the engine all ask this one question, so a definition is
+ * refused by the same words wherever it is caught, and a run that reaches such
+ * a step fails with them.
+ */
+export function checkWorkflowRetiredStepKinds(input) {
+    const violations = [];
+    const visit = (step) => {
+        if (!step || typeof step !== "object" || Array.isArray(step))
+            return;
+        const kind = step.kind;
+        const id = step.id;
+        if (typeof kind === "string" &&
+            RETIRED_DATABASE_STEP_KINDS.includes(kind)) {
+            const name = typeof id === "string" && id ? `step "${id}"` : "a step";
+            violations.push(refuseWorkflowRule("retired-database-step-kind", `${name} uses ${kind}, which was retired with database operations — ` +
+                "move its work into a server function (ctx.db(databaseId).model(name)) " +
+                "and call that function from the workflow with a workflow.call step"));
+        }
+        if (kind === "collect")
+            visit(step.step);
+    };
+    if (Array.isArray(input.steps))
+        input.steps.forEach(visit);
+    return violations;
+}
 // ── src/config-surface/workflow.ts ───────────────────────────────────────
 /**
  * The `workflow` configuration object's definition (issue #2644, phase 1).
@@ -4339,6 +4500,10 @@ export const WORKFLOW_SURFACE = {
                 // 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.
+                // #3188 retired the synchronous run route this flag opted into; the
+                // field still round-trips (pull, diff, push) until the workflow
+                // surface itself retires, and `config push` notes a `true` as
+                // ignored. Its step-kind rule went with the route.
                 {
                     field: "syncCallable",
                     tomlKey: "syncCallable",
@@ -4563,8 +4728,9 @@ export const WORKFLOW_SURFACE = {
     },
     // ── Cross-field rules (#3374) ─────────────────────────────────────────────
     //
-    // One rule the CLI's push preflight runs — through the vendored copy of
-    // `workflow-rules.ts` — and seven the server runs at save time. What stays
+    // Two rules the CLI's push preflight runs — through the vendored copy of
+    // `workflow-rules.ts` (the server runs both too) — and six more the server
+    // runs at save time. What stays
     // UNDECLARED, on purpose: the step-body validation (`validateWorkflowDefinition`
     // and the `steps` structural sub-tree, which is not a field-table rule), and
     // the enable-time activation lint (`workflow-activation-lint.ts`, a transition
@@ -4581,6 +4747,17 @@ export const WORKFLOW_SURFACE = {
             stage: "preflight",
             handler: enforcedBy("src/config-surface/workflow-rules.ts", "checkWorkflowSystemAccessRule"),
         },
+        {
+            id: "retired-database-step-kind",
+            description: "A step may not use a retired `database.*` kind (`database.query`, " +
+                "`mutate`, `count`, `aggregate`, `pipeline`, `applyToQuery`, `batch` " +
+                "and their `*ForUser` twins): each executed a registered database " +
+                "operation, and operations retired (#3189). `database.syncIndexes`, " +
+                "`database.create` and `database.delete` stay. Push, save, the " +
+                "activation lint and the engine ask the same predicate.",
+            stage: "preflight",
+            handler: enforcedBy("src/config-surface/workflow-rules.ts", "checkWorkflowRetiredStepKinds"),
+        },
         workflowApplyRule("run-as-value", "validateWorkflowIdentityConfig", '`runAs` must be "caller" or "system" when present — the runner has no ' +
             "third identity."),
         workflowApplyRule("capabilities-shape", "validateWorkflowIdentityConfig", "`capabilities` must be an array or set of capability strings."),
@@ -4594,8 +4771,6 @@ export const WORKFLOW_SURFACE = {
         workflowApplyRule("access-rule-required", "validateWorkflowIdentityConfig", "On create, a caller-mode workflow must state its `accessRule` (`\"true\"` " +
             "for any app member), so a locked workflow is a decision rather than a " +
             "default."),
-        workflowApplyRule("sync-callable-step-kind", "validateSyncCallableSteps", "A `syncCallable = true` workflow may not carry a step kind that only " +
-            "the durable runtime can execute (`delay`, `event.wait`)."),
     ],
 };
 const FIELD_RANGES = [
@@ -5697,6 +5872,9 @@ export const AGENT_ERROR_CODES = [
     "AGENT_TOOL_ARGUMENTS_INVALID",
     "AGENT_ROUND_TRUNCATED",
     "AGENT_ROUND_EMPTY",
+    // #4262 — a single-round test case whose seeded history, context or
+    // assertions cannot be a round of this agent (`agent-test-case.ts`).
+    "AGENT_TEST_CASE_INVALID",
 ];
 /**
  * The platform maximums. An agent may lower `maxSteps`, `waitLimitSeconds`
@@ -5721,6 +5899,20 @@ export const AGENT_NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
 export const AGENT_ANSWERED_BY = ["initiator", "participants"];
 export const AGENT_TOOL_INVOKE = ["request", "task"];
 export const AGENT_TOOL_HISTORY_SCOPES = ["session", "turn"];
+/**
+ * The result the platform records for a call to a client tool with
+ * `endsTurn = true`: the call is final when its response is committed, and
+ * later rounds read this as its tool result.
+ */
+export const AGENT_TERMINAL_CALL_OUTPUT = Object.freeze({
+    delivered: true,
+});
+/** The schema of `AGENT_TERMINAL_CALL_OUTPUT`: a terminal client tool's output type. */
+export const AGENT_TERMINAL_CALL_OUTPUT_SCHEMA = Object.freeze({
+    type: "object",
+    properties: { delivered: { type: "boolean" } },
+    required: ["delivered"],
+});
 const AGENT_TOP_LEVEL_KEYS = [
     "answeredBy",
     "maxSteps",
@@ -5742,6 +5934,7 @@ const AGENT_TOOL_KEYS = [
     "approval",
     "statusText",
     "historyScope",
+    "endsTurn",
     "inputSchema",
     "outputSchema",
 ];
@@ -5870,8 +6063,22 @@ function checkAgentTool(tool, index, names, out) {
             out.push(agentInvalid(`${path}.invoke`, `must be one of ${AGENT_TOOL_INVOKE.join(" | ")}`));
         }
     }
+    const terminal = tool.endsTurn === true;
+    if (tool.endsTurn !== undefined && typeof tool.endsTurn !== "boolean") {
+        out.push(agentInvalid(`${path}.endsTurn`, "must be true or false"));
+    }
+    if (terminal && tool.approval === true) {
+        out.push(agentInvalid(`${path}.endsTurn`, "cannot be set with approval = true: a terminal call never pauses"));
+    }
     for (const key of ["inputSchema", "outputSchema"]) {
         const schemaPath = `${path}.${key}`;
+        if (isClient && terminal && key === "outputSchema") {
+            if (tool[key] !== undefined) {
+                out.push(agentInvalid(schemaPath, "is not declared on a client tool with endsTurn = true: the " +
+                    "platform records a terminal client call's result — remove it"));
+            }
+            continue;
+        }
         if (isClient) {
             if (tool[key] === undefined) {
                 out.push(agentInvalid(schemaPath, "is required on a client tool"));
@@ -6146,17 +6353,14 @@ export function agentRoundNotAgentRefusal(promptKey) {
         "agent rounds. Run it with ctx.prompts.run, or name an agent prompt");
 }
 /**
- * The refusal of a prompt test case that involves an agent (§D1: prompt test
- * cases are refused for the kind in v1; multi-turn tests are deferred).
- * `subject` is a case written ON the agent, `evaluator` a case that names the
- * agent as its judge.
+ * The refusal of a prompt test case that names an agent as its judge (§D1: an
+ * evaluator runs single-shot, which an agent never does). A case written ON an
+ * agent is a single-round test since #4262 (`agent-test-case.ts`), so
+ * `evaluator` is the one role left.
  */
-export function agentTestCaseRefusal(promptKey, role) {
-    return agentRefusal("AGENT_TEST_CASE_NOT_SUPPORTED", role === "subject"
-        ? `Prompt "${promptKey}" is an agent (kind = "agent"); prompt test ` +
-            "cases are not supported for agents yet. Test its tools as functions"
-        : `Prompt "${promptKey}" is an agent (kind = "agent") and cannot be an ` +
-            "evaluator: an evaluator is run single-shot. Name a chat prompt");
+export function agentTestCaseRefusal(promptKey, _role = "evaluator") {
+    return agentRefusal("AGENT_TEST_CASE_NOT_SUPPORTED", `Prompt "${promptKey}" is an agent (kind = "agent") and cannot be an ` +
+        "evaluator: an evaluator is run single-shot. Name a chat prompt");
 }
 /** A deep copy, so a reader's defaults never reach the caller's value. */
 function agentCopy(value) {
@@ -6165,7 +6369,7 @@ function agentCopy(value) {
 /**
  * The declaration with every default applied: `answeredBy = "initiator"`, the
  * platform maximums for the limits, and per tool `invoke = "request"` (server
- * tools), `approval = false` and `historyScope = "session"`.
+ * tools), `approval = false`, `historyScope = "session"` and `endsTurn = false`.
  *
  * The ONLY accessor for defaults — the stored value never carries them
  * (DSO-3798-001). Takes a value `resolveAgentDeclaration` accepted (or `null`)
@@ -6185,6 +6389,7 @@ export function normalizeAgentDeclaration(declaration) {
             ...(tool.runs === "client" ? {} : { invoke: tool.invoke ?? "request" }),
             approval: tool.approval ?? false,
             historyScope: tool.historyScope ?? "session",
+            endsTurn: tool.endsTurn ?? false,
         })),
         events: source.events ?? [],
     };
@@ -6902,6 +7107,365 @@ export function agentSchemaTranslationRefusals(input) {
     }
     return out;
 }
+// ── src/config-surface/agent-test-case.ts ────────────────────────────────
+/**
+ * What an agent test case may say — issue #4262 (single-round prompt tests
+ * from a seeded history; design-docs/agents.md §D1).
+ *
+ * A test case on an agent prompt carries one `[test.agent]` block: a seeded
+ * `history` (JSON text), the round's turn `context`, `timezone` and `locale`,
+ * and two assertions on the round's calls (`expectedToolCall`,
+ * `expectedNoToolCall`). On the wire and in storage those are six flat
+ * `BlockTestCase` fields, `agentHistory` … `agentExpectedNoToolCall`.
+ *
+ * This module is the whole FILE-DECIDABLE rule for them: the history's shape,
+ * its turns, its call and result pairing, where its events sit, the
+ * assertions' shapes, and — when the caller passes the agent's declaration —
+ * that the event kinds and the asserted tool are declared. The admin test-case
+ * routes call it, and so does the CLI's push preflight through the vendored
+ * artifact, so a refusal at push and a refusal at the route cannot disagree.
+ * What needs app state or a schema validator (the input, context and event
+ * schemas, the send route's zone and tag rules) is `agent-test-round.ts`'s.
+ *
+ * Every refusal carries `AGENT_TEST_CASE_INVALID` and the caller gets every
+ * offending item at once, as the declaration resolver does.
+ *
+ * Pure and dependency-free apart from the agent declaration's types, like
+ * every module under `src/config-surface/`.
+ */
+/** The six wire and stored fields, in the order the surface declares them. */
+export const AGENT_TEST_CASE_FIELDS = [
+    "agentHistory",
+    "agentContext",
+    "agentTimezone",
+    "agentLocale",
+    "agentExpectedToolCall",
+    "agentExpectedNoToolCall",
+];
+function agentTestRefusal(message) {
+    return { code: "AGENT_TEST_CASE_INVALID", message: `[test.agent] ${message}` };
+}
+function agentTestIsObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function agentTestIsText(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+/** `null` and `undefined` are absence; so is `""` for a text field. */
+function agentTestIsUnset(value) {
+    if (value === null || value === undefined)
+        return true;
+    return typeof value === "string" && value.trim() === "";
+}
+/** A JSON field: the value as given, or the JSON text a sidecar carries parsed. */
+function agentTestJsonValue(value) {
+    if (typeof value !== "string")
+        return { ok: true, value };
+    try {
+        return { ok: true, value: JSON.parse(value) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** The names a declaration declares, or `null` when the caller passed none. */
+function agentTestDeclaredNames(declaration, given) {
+    if (!given)
+        return null;
+    let block = declaration;
+    if (typeof block === "string") {
+        try {
+            block = JSON.parse(block);
+        }
+        catch {
+            block = null;
+        }
+    }
+    const names = (list) => new Set((Array.isArray(list) ? list : [])
+        .map((item) => (agentTestIsObject(item) ? item.name : undefined))
+        .filter((name) => typeof name === "string"));
+    const source = agentTestIsObject(block) ? block : {};
+    return { tools: names(source.tools), events: names(source.events) };
+}
+const AGENT_TEST_ENTRY_KEYS = {
+    user: ["role", "text"],
+    assistant: ["role", "text", "reasoning", "calls"],
+    tool: ["role", "callId", "output", "error"],
+    event: ["role", "kind", "refersTo", "data"],
+};
+/**
+ * The history's entries and every refusal of their shape. A user entry
+ * starts a turn and the last one's turn is the current one; every call is
+ * answered exactly once, by a tool entry that follows its assistant entry;
+ * an event precedes the current turn's user entry (a live event reaches the
+ * model only in a later turn's history).
+ */
+function agentTestReadHistory(raw, names, out) {
+    if (agentTestIsUnset(raw)) {
+        out.push(agentTestRefusal("history is required on an agent case: a JSON array of user, assistant, tool and event entries, oldest first"));
+        return null;
+    }
+    if (typeof raw !== "string") {
+        out.push(agentTestRefusal("history must be JSON text (a JSON array written as one string)"));
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        out.push(agentTestRefusal(`history is not valid JSON (${error?.message ?? "parse failed"})`));
+        return null;
+    }
+    if (!Array.isArray(parsed)) {
+        out.push(agentTestRefusal("history must be a JSON array of entries"));
+        return null;
+    }
+    const entries = [];
+    const calls = new Map();
+    /** The calls of the last assistant entry, which tool entries may answer. */
+    let open = new Set();
+    let seenUser = false;
+    const lastUser = parsed.reduce((at, entry, index) => (agentTestIsObject(entry) && entry.role === "user" ? index : at), -1);
+    if (lastUser === -1) {
+        out.push(agentTestRefusal("history needs at least one user entry; the last one is the round's current turn"));
+    }
+    parsed.forEach((entry, index) => {
+        const at = `history[${index}]`;
+        if (!agentTestIsObject(entry)) {
+            out.push(agentTestRefusal(`${at} must be an object with a role`));
+            return;
+        }
+        // An own-property read: a role such as "constructor" or "__proto__" must
+        // not resolve to an inherited member of the table.
+        const allowed = typeof entry.role === "string" && Object.prototype.hasOwnProperty.call(AGENT_TEST_ENTRY_KEYS, entry.role)
+            ? AGENT_TEST_ENTRY_KEYS[entry.role]
+            : undefined;
+        if (!allowed) {
+            out.push(agentTestRefusal(`${at}.role must be "user", "assistant", "tool" or "event"; found ${JSON.stringify(entry.role)}`));
+            return;
+        }
+        const unknown = Object.keys(entry).filter((key) => !allowed.includes(key));
+        if (unknown.length > 0) {
+            out.push(agentTestRefusal(`${at} has ${unknown.map((k) => `"${k}"`).join(", ")}, which a ${entry.role} entry does not carry; allowed: ${allowed.join(", ")}`));
+        }
+        if (entry.role === "user") {
+            if (typeof entry.text !== "string" || entry.text === "") {
+                out.push(agentTestRefusal(`${at}.text must be a non-empty string`));
+                return;
+            }
+            open = new Set();
+            seenUser = true;
+            entries.push({ role: "user", text: entry.text });
+            return;
+        }
+        if (entry.role === "assistant") {
+            if (!seenUser) {
+                out.push(agentTestRefusal(`${at} is an assistant entry before the first user entry; a turn starts with a user entry`));
+            }
+            const hasText = entry.text !== undefined;
+            const hasCalls = entry.calls !== undefined;
+            if (hasText && typeof entry.text !== "string") {
+                out.push(agentTestRefusal(`${at}.text must be a string`));
+            }
+            if (entry.reasoning !== undefined && typeof entry.reasoning !== "string") {
+                out.push(agentTestRefusal(`${at}.reasoning must be a string`));
+            }
+            const read = [];
+            if (hasCalls) {
+                if (!Array.isArray(entry.calls) || entry.calls.length === 0) {
+                    out.push(agentTestRefusal(`${at}.calls must be a non-empty array of { callId, name, arguments }`));
+                }
+                else {
+                    entry.calls.forEach((call, callIndex) => {
+                        const callAt = `${at}.calls[${callIndex}]`;
+                        if (!agentTestIsObject(call) ||
+                            !agentTestIsText(call.callId) ||
+                            !agentTestIsText(call.name) ||
+                            !("arguments" in call) ||
+                            Object.keys(call).some((key) => !["callId", "name", "arguments"].includes(key))) {
+                            out.push(agentTestRefusal(`${callAt} must be { callId, name, arguments }`));
+                            return;
+                        }
+                        if (calls.has(call.callId)) {
+                            out.push(agentTestRefusal(`${callAt}: call id "${call.callId}" is used twice; call ids are unique across the history`));
+                            return;
+                        }
+                        calls.set(call.callId, { answered: false });
+                        read.push({ callId: call.callId, name: call.name, arguments: call.arguments });
+                    });
+                }
+            }
+            if (!(typeof entry.text === "string" && entry.text !== "") && read.length === 0 && !hasCalls) {
+                out.push(agentTestRefusal(`${at} needs text or calls`));
+            }
+            open = new Set(read.map((call) => call.callId));
+            entries.push({
+                role: "assistant",
+                ...(typeof entry.text === "string" ? { text: entry.text } : {}),
+                ...(typeof entry.reasoning === "string" ? { reasoning: entry.reasoning } : {}),
+                ...(read.length > 0 ? { calls: read } : {}),
+            });
+            return;
+        }
+        if (entry.role === "tool") {
+            if (!agentTestIsText(entry.callId)) {
+                out.push(agentTestRefusal(`${at}.callId must name a call of an earlier assistant entry`));
+                return;
+            }
+            const hasOutput = "output" in entry;
+            const hasError = "error" in entry;
+            if (hasOutput === hasError) {
+                out.push(agentTestRefusal(`${at} must carry exactly one of output or error`));
+                return;
+            }
+            const call = calls.get(entry.callId);
+            if (!call) {
+                out.push(agentTestRefusal(`${at} answers call "${entry.callId}", which no earlier assistant entry makes`));
+                return;
+            }
+            if (call.answered) {
+                out.push(agentTestRefusal(`${at} is a second result for call "${entry.callId}"; every call has exactly one`));
+                return;
+            }
+            if (!open.has(entry.callId)) {
+                out.push(agentTestRefusal(`${at} answers call "${entry.callId}", which is not a call of the assistant entry just before it; ` +
+                    "a result follows its call"));
+                return;
+            }
+            call.answered = true;
+            if (hasError) {
+                const error = entry.error;
+                if (!agentTestIsObject(error) || !agentTestIsText(error.code) || typeof error.message !== "string") {
+                    out.push(agentTestRefusal(`${at}.error must be { code, message }`));
+                    return;
+                }
+                entries.push({ role: "tool", callId: entry.callId, error: { code: error.code, message: error.message } });
+                return;
+            }
+            entries.push({ role: "tool", callId: entry.callId, output: entry.output });
+            return;
+        }
+        // An event.
+        if (!agentTestIsText(entry.kind)) {
+            out.push(agentTestRefusal(`${at}.kind must name an event kind the agent declares`));
+            return;
+        }
+        if (names && !names.events.has(entry.kind)) {
+            out.push(agentTestRefusal(`${at} has event kind "${entry.kind}", which the agent does not declare` +
+                (names.events.size > 0 ? ` (declared: ${[...names.events].join(", ")})` : "")));
+        }
+        if (entry.refersTo !== undefined && (!agentTestIsText(entry.refersTo) || !calls.has(entry.refersTo))) {
+            out.push(agentTestRefusal(`${at}.refersTo names call ${JSON.stringify(entry.refersTo)}, which no earlier assistant entry makes`));
+        }
+        if (lastUser !== -1 && index > lastUser) {
+            out.push(agentTestRefusal(`${at} is an event after the current turn's user entry; a live event reaches the model only in a ` +
+                "later turn, so place it before the last user entry"));
+        }
+        entries.push({
+            role: "event",
+            kind: entry.kind,
+            ...(typeof entry.refersTo === "string" ? { refersTo: entry.refersTo } : {}),
+            data: entry.data ?? null,
+        });
+    });
+    for (const [callId, call] of calls) {
+        if (!call.answered) {
+            out.push(agentTestRefusal(`call "${callId}" has no result; write one tool entry for it (an unanswered call as an error, ` +
+                'e.g. { "code": "superseded", "message": "…" })'));
+        }
+    }
+    const last = parsed[parsed.length - 1];
+    if (agentTestIsObject(last) && last.role === "assistant") {
+        out.push(agentTestRefusal("history ends with an assistant entry; a round starts from a user entry or a tool result"));
+    }
+    return entries;
+}
+function agentTestReadExpectedToolCall(raw, names, out) {
+    if (agentTestIsUnset(raw))
+        return null;
+    const parsed = agentTestJsonValue(raw);
+    const value = parsed.ok ? parsed.value : undefined;
+    if (!agentTestIsObject(value) ||
+        !agentTestIsText(value.name) ||
+        Object.keys(value).some((key) => key !== "name" && key !== "arguments")) {
+        out.push(agentTestRefusal("expectedToolCall must be { name, arguments? } (arguments is matched as a subset)"));
+        return null;
+    }
+    if (names && !names.tools.has(value.name)) {
+        out.push(agentTestRefusal(`expectedToolCall names tool "${value.name}", which the agent does not declare` +
+            (names.tools.size > 0 ? ` (declared: ${[...names.tools].join(", ")})` : "")));
+    }
+    return { name: value.name, ...("arguments" in value ? { arguments: value.arguments } : {}) };
+}
+/**
+ * The one rule: is this case's agent block something a round can be built
+ * from? `{ ok: true, testCase }` carries it read (`null` on a case whose
+ * prompt is not an agent). On a chat or decisions case, every agent key
+ * holding a non-null value is refused by name; an explicit `null` is unset on
+ * any case, which is how a full-state update clears one.
+ */
+export function resolveAgentTestCase(input) {
+    const { fields } = input;
+    const kind = agentTestIsUnset(input.kind) ? "chat" : String(input.kind).trim();
+    const refusals = [];
+    if (kind !== "agent") {
+        const owner = kind === "chat" || kind === "decisions" ? `a ${kind} prompt` : `a ${kind}`;
+        for (const key of AGENT_TEST_CASE_FIELDS) {
+            const value = fields[key];
+            if (value !== null && value !== undefined) {
+                refusals.push(agentTestRefusal(`${key} is set on a case of ${owner}; only an agent prompt's case carries the agent block. ` +
+                    "Remove it, or send it as null"));
+            }
+        }
+        return refusals.length > 0 ? { ok: false, refusals } : { ok: true, testCase: null };
+    }
+    const names = agentTestDeclaredNames(input.declaration, "declaration" in input);
+    const history = agentTestReadHistory(fields.agentHistory, names, refusals);
+    let context = null;
+    if (!agentTestIsUnset(fields.agentContext)) {
+        const parsed = agentTestJsonValue(fields.agentContext);
+        if (parsed.ok && agentTestIsObject(parsed.value))
+            context = parsed.value;
+        else
+            refusals.push(agentTestRefusal("context must be a JSON object (turn.* for the round)"));
+    }
+    const text = (key, label, example) => {
+        const value = fields[key];
+        if (value === null || value === undefined)
+            return null;
+        if (typeof value !== "string" || value === "") {
+            refusals.push(agentTestRefusal(`${label} must be ${example}`));
+            return null;
+        }
+        return value;
+    };
+    const timezone = text("agentTimezone", "timezone", 'an IANA time zone name such as "America/New_York"');
+    const locale = text("agentLocale", "locale", 'a BCP 47 language tag such as "en-US"');
+    const expectedToolCall = agentTestReadExpectedToolCall(fields.agentExpectedToolCall, names, refusals);
+    let expectedNoToolCall = false;
+    const noCall = fields.agentExpectedNoToolCall;
+    if (noCall !== null && noCall !== undefined) {
+        if (typeof noCall !== "boolean")
+            refusals.push(agentTestRefusal("expectedNoToolCall must be true or false"));
+        else
+            expectedNoToolCall = noCall;
+    }
+    if (expectedToolCall && expectedNoToolCall) {
+        refusals.push(agentTestRefusal("sets both expectedToolCall and expectedNoToolCall = true; a round cannot both call a tool and call none"));
+    }
+    const subset = fields.expectedJsonSubset;
+    if (!agentTestIsUnset(subset) && !(agentTestIsObject(subset) && Object.keys(subset).length === 0) && subset !== "{}") {
+        refusals.push(agentTestRefusal("expectedJsonSubset is not used on an agent case: an agent's answer is text, and anything structured is a " +
+            "tool call. Assert it with expectedToolCall"));
+    }
+    if (refusals.length > 0 || !history)
+        return { ok: false, refusals };
+    return {
+        ok: true,
+        testCase: { history, context, timezone, locale, expectedToolCall, expectedNoToolCall },
+    };
+}
 // ── src/config-surface/prompt.ts ─────────────────────────────────────────
 /**
  * The `prompt` configuration object's definition (issue #2644, phase 2).
@@ -8246,8 +8810,8 @@ export const CRON_TRIGGER_SURFACE = {
  * 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`).
+ * configs do (#4116). The id spelling in TOML (#4283) and the pre-#1020
+ * `accessPolicy` spelling (#3996) are retired keys (`retired-keys.ts`).
  */
 const BLOB_BUCKET_HANDLER = "src/app-api/controllers/blob-buckets-controller.ts";
 export const BLOB_BUCKET_SURFACE = {
@@ -8303,7 +8867,7 @@ export const BLOB_BUCKET_SURFACE = {
                     // 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.
+                    // request. The TOML spelling of the id is a retired key (#4283).
                     validation: handledBy(BLOB_BUCKET_HANDLER, "BlobBucketsController", "apply"),
                 },
             ],
@@ -8353,14 +8917,6 @@ 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.",
                 },
-                ruleSetId: {
-                    kind: "deprecated",
-                    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: {},
         },
@@ -8541,20 +9097,21 @@ export const EMAIL_TEMPLATE_SURFACE = {
  * 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
+ * slot: a `[type]` scalar table, plus three 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.
+ * `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.
+ *
+ * #3189 — `[[operations]]` and `[[subscriptions]]` retired with database
+ * operations and type-scoped subscriptions; `config push` refuses a file that
+ * still carries either, with the sentence `retired-keys.ts` states
+ * (`RETIRED_DOCUMENT_KEYS`).
  *
  * 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
@@ -8593,30 +9150,6 @@ export const DATABASE_TYPE_SURFACE = {
                     // spelling is retired in TOML (#3997): `retired-keys.ts`, `type`.
                     validation: handledBy(DB_TYPE_HANDLER, "DatabaseTypeConfigController", "apply"),
                 },
-                {
-                    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.
-                    deprecated: {
-                        note: "one CEL expression gates both read and update of the database " +
-                            "CEL context; use a resource metadata category, which has " +
-                            "separate readRule and writeRule",
-                    },
-                    validation: handledBy(DB_TYPE_HANDLER, "DatabaseTypeConfigController", "apply"),
-                },
-                {
-                    field: "defaultAccess",
-                    tomlKey: "defaultAccess",
-                    type: "string",
-                    emit: "whenSet",
-                    writableOn: BOTH,
-                    // CEL, plus the shared `md`-shape allowlist (#1523).
-                    validation: handledBy(DB_TYPE_HANDLER, "DatabaseTypeConfigController", "apply"),
-                },
                 {
                     field: "autoPopulatedFields",
                     tomlKey: "autoPopulatedFields",
@@ -8676,44 +9209,8 @@ export const DATABASE_TYPE_SURFACE = {
                     note: "User who created the config; assigned server-side.",
                 },
             },
-            tomlOnlyKeys: {
-                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`.",
-                },
-            },
+            tomlOnlyKeys: {},
+            requestOnlyKeys: {},
             responseOnlyKeys: {},
         },
     ],
@@ -8723,15 +9220,6 @@ export const DATABASE_TYPE_SURFACE = {
             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 " +
@@ -9219,7 +9707,7 @@ export const TRANSFORM_SURFACE = {
  * config version (`ServerFunctionConfig`), but it is ONE table in the file: an
  * author does not write a version, they write a function and push it. The
  * definition therefore declares the header's field surface and lists the
- * version-carried keys (`entry`, `mode`, `limits`) in `tomlOnlyKeys` beside
+ * version-carried keys (`entry`, `limits`) in `tomlOnlyKeys` beside
  * `key` — they are authored, they are not fields of the header model, and they
  * travel on the config-version route rather than in the header body. Declaring
  * a second table over `ServerFunctionConfig` at the same `tomlPath` is not
@@ -9307,6 +9795,20 @@ const TRIGGER_DECLARATION_RULES = functionRules("preflight", "src/config-surface
     ["cron-trigger-expression-required", "A cron entry carries a `cron` expression."],
     ["cron-trigger-overlap-policy", "`overlapPolicy` is `skip` or `allow`."],
 ]);
+/**
+ * The retired runtime keys (#3188). `mode`, `durable` and a cron entry's
+ * `mode` were accepted with a warning through phase 4 (#3482); phase 5 refuses
+ * them, first in the preflight's order, so an author reads them in the order
+ * their file carries them.
+ */
+const RETIRED_RUNTIME_KEY_RULES = functionRules("preflight", "src/config-surface/function-retired-keys.ts", "refusedFunctionKeys", [
+    [
+        "retired-runtime-key",
+        "`mode`, `durable` and a cron entry's `mode` are refused: the caller " +
+            "picks the runtime at each call (`invoke` or `start`) and every cron " +
+            "fire starts a task run, so the file has nothing to say. Delete the line.",
+    ],
+]);
 /**
  * The file-decidable half of the webhook `signingSecret` rule (#3320). The
  * SAME handler under the SAME ids is declared `apply` on the standalone
@@ -9464,14 +9966,6 @@ export const SERVER_FUNCTION_SURFACE = {
                     note: "#3462 — WHICH admin put the active version live. Same two doors, " +
                         "same reason: the actor is observed, never declared.",
                 },
-                runAs: {
-                    kind: "server-owned",
-                    note: "RETIRED from the write surface by #3279: function code acts as " +
-                        "the system whoever invoked it, so the mode the column chose " +
-                        "between no longer exists. Declared-and-deprecated storage only " +
-                        "until phase 6 drops the column; a stored value decides nothing " +
-                        "and is never echoed.",
-                },
                 deleteLockedAt: {
                     kind: "server-owned",
                     note: "#3186 — the lease a hard delete takes before it scans for live " +
@@ -9508,24 +10002,21 @@ export const SERVER_FUNCTION_SURFACE = {
                 },
                 mode: {
                     kind: "structural",
-                    note: "RETIRED (#3482), and still ACCEPTED through phase 4. A function " +
-                        "is a function: the CALLER picks the runtime at each call, with " +
-                        "`invoke` running it inside the request and `start` running it as " +
-                        "a task, cron fires always starting a task run and webhook " +
-                        "deliveries always running as a request. A file that still " +
-                        "carries the key pushes, with a warning naming it as ignored and " +
-                        "every other key applied, and `config pull` removes it; from " +
-                        "phase 5 (#3188) it is refused as an unknown key. Nothing reads " +
-                        "it, and its value is not validated. A function that must not run " +
-                        "under one runtime says so in code with `assertRuntime`.",
+                    note: "RETIRED (#3482) and REFUSED from phase 5 (#3188) by the " +
+                        "`retired-runtime-key` rule, whose sentence names the key and " +
+                        "says to delete the line. A function is a function: the CALLER " +
+                        "picks the runtime at each call, with `invoke` running it inside " +
+                        "the request and `start` running it as a task, cron fires always " +
+                        "starting a task run and webhook deliveries always running as a " +
+                        "request. Listed here so the refusal is the rule's sentence rather " +
+                        "than the generic unknown-key one; `config pull` removes it from a " +
+                        "version pushed before the retirement.",
                 },
                 durable: {
                     kind: "structural",
-                    note: "RETIRED (#3482), and still ACCEPTED through phase 4 — the same " +
-                        "as `mode`, whose alias it was. It named one runner for the whole " +
-                        "function, and there is no such thing any more. A file that " +
-                        "carries it pushes with a warning, `config pull` removes it, and " +
-                        "phase 5 refuses it.",
+                    note: "RETIRED (#3482) and REFUSED from phase 5 (#3188) — the same as " +
+                        "`mode`, whose alias it was, by the same rule. It named one runner " +
+                        "for the whole function, and there is no such thing any more.",
                 },
                 limits: {
                     kind: "structural",
@@ -9563,11 +10054,12 @@ export const SERVER_FUNCTION_SURFACE = {
     tomlDocumentKeys: {},
     // ── Cross-field rules (#3374) ─────────────────────────────────────────────
     //
-    // Single-field refusals inside these modules (`mode`'s value, a webhook
+    // Single-field refusals inside these modules (a retired `mode` key, a webhook
     // block's `verificationScheme`) are declared here too: this is the only
     // id-bearing slot until #3375 gives `ConfigField.validation` a stage, and a
     // module's list must equal its declarations in both directions.
     crossFieldRules: [
+        ...RETIRED_RUNTIME_KEY_RULES,
         ...TRIGGER_DECLARATION_RULES,
         ...SIGNING_SECRET_RULES,
         // #3376 — after the signing-secret group, mirroring the order
@@ -9601,8 +10093,23 @@ export const SERVER_FUNCTION_SURFACE = {
  * 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.
+ *
+ * #4262 — an agent prompt's case carries one more block, `[test.agent]`: the
+ * seeded history its single round starts from, the round's turn context, zone
+ * and tag, and two assertions on the round's calls. Six flat fields on the
+ * wire, each `whenSet`, so a chat case's sidecar never grows an empty block.
+ * `history` is typed `string` — JSON text in TOML, on the wire and in storage —
+ * because `isEmptyForEmit` reads every array as empty for a `json` field, so a
+ * `whenSet` array would never pull and would compare equal to anything.
  */
 const TEST_CASE_HANDLER = "src/admin-api.ts";
+/**
+ * #4262 — the agent block's one rule, vendored: the admin routes call it on
+ * create and update, the CLI's preflight on an agent prompt's sidecar. Its
+ * schema half (input, context and event schemas) needs the app's agent, so the
+ * stage is `apply`.
+ */
+const AGENT_TEST_CASE_RULE = handledBy("src/config-surface/agent-test-case.ts", "resolveAgentTestCase", "apply");
 /**
  * ── Why this module's CLI handler is declared `apply` (#3375) ─────────────
  *
@@ -9704,7 +10211,72 @@ export const TEST_CASE_SURFACE = {
                     // JSON object, deep-partial-matched against the parsed output.
                     validation: handledBy(CLI_SYNC, "parseTestCaseToml", "apply"),
                 },
+                // #4262 — `[test.agent]`, an agent prompt's case only.
+                {
+                    field: "agentHistory",
+                    tomlKey: "history",
+                    tomlGroup: "agent",
+                    // JSON text of the seeded history, stored as authored.
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
+                {
+                    field: "agentContext",
+                    tomlKey: "context",
+                    tomlGroup: "agent",
+                    // `turn.*` for the round; TOML carries the JSON text.
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
+                {
+                    field: "agentTimezone",
+                    tomlKey: "timezone",
+                    tomlGroup: "agent",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
+                {
+                    field: "agentLocale",
+                    tomlKey: "locale",
+                    tomlGroup: "agent",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
+                {
+                    field: "agentExpectedToolCall",
+                    tomlKey: "expectedToolCall",
+                    tomlGroup: "agent",
+                    // `{ name, arguments? }`; TOML carries the JSON text.
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
+                {
+                    field: "agentExpectedNoToolCall",
+                    tomlKey: "expectedNoToolCall",
+                    tomlGroup: "agent",
+                    type: "boolean",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
             ],
+            tomlGroups: {
+                agent: {
+                    note: "#4262 — `[test.agent]`: the seeded history, turn context and " +
+                        "tool-call assertions of a single-round test on an agent prompt. " +
+                        "Refused on any other case.",
+                },
+            },
             notExposed: {
                 testCaseId: {
                     kind: "server-owned",
@@ -10561,6 +11133,12 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "evaluatorPromptId",
         "evaluatorConfigId",
         "attachments",
+        "agentHistory",
+        "agentContext",
+        "agentTimezone",
+        "agentLocale",
+        "agentExpectedToolCall",
+        "agentExpectedNoToolCall",
         "createdBy",
         "createdAt",
         "modifiedAt",
@@ -10606,8 +11184,6 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "databaseType",
         "ruleSetId",
         "triggers",
-        "metadataAccess",
-        "defaultAccess",
         "metadataManifest",
         "autoPopulatedFields",
         "timestamps",
@@ -10663,7 +11239,6 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "activeConfigId",
         "activeConfigActivatedAt",
         "activeConfigActivatedBy",
-        "runAs",
         "access",
         "inputSchema",
         "outputSchema",