primitive-admin 1.2.0-alpha.1 → 1.2.0-alpha.11

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

@@ -31,7 +31,7 @@
  * server; the CLI vendors them at build time into
  * `cli/src/lib/generated-config-surfaces.ts`
  * (`cli/scripts/gen-config-surfaces.mjs`), the same server→CLI vendoring
- * `gen-operation-def-descriptor.mjs` (#1544) already uses, so the published CLI
+ * `gen-workflow-schema-descriptor.mjs` (#1442) already uses, so the published CLI
  * still imports no server code at runtime.
  *
  * ── Scope: declarative classification and coverage ONLY ──────────────────
@@ -283,8 +283,7 @@ export type RuleStage = "preflight" | "apply";
 export type CrossFieldRuleStage = RuleStage;
 /**
  * One rule of a configuration object that spans more than one field — `durable
- * = true` beside a webhook trigger, `runAs = "system"` beside a non-empty
- * `accessRule`, an HMAC scheme with no `signingSecret`.
+ * = true` beside a webhook trigger, an HMAC scheme with no `signingSecret`.
  *
  * Such a rule belongs to no single field, so `ConfigField.validation` has
  * nowhere to put it; attaching it to one field arbitrarily would make the
@@ -362,8 +361,9 @@ export interface ConfigObjectSurface {
      * Declares that this object HAS no TOML field table, with the reason —
      * required when `tables` is empty and forbidden otherwise.
      *
-     * `transform` is the case: a `.rhai` file's authored surface is the script
-     * body, so there is no key/value table to define. Saying so here is the same
+     * `transform` was the case until it retired with the Rhai runtime (#3190): a
+     * `.rhai` file's authored surface was the script body, so there was no
+     * key/value table to define. Saying so here is the same
      * rule `notExposed` applies to a field, one level up: "absent from the
      * registry" and "deliberately fieldless" must not look the same (#2644
      * criterion 4).
@@ -455,8 +455,8 @@ export declare const DECLARED_ACCESS_MANIFEST_KEYS: Readonly<Record<string, NotE
  * accepts. What a present key MEANS stays with the per-field handler the
  * definition names (spec §Contracts, decision of record #1976): the workflow
  * `status` enum, the non-negative-integer coercion of the queue limits,
- * `runAs`'s caller|system check, `parseWorkflowLock`, the `capabilities` array
- * shape and the CEL parse of `accessRule` all stay where they are. The
+ * `runAs`'s caller|system check, `parseWorkflowLock` and the `capabilities`
+ * array shape all stay where they are. The
  * mechanical win is that a field can no longer be *absent* from the accepted
  * set.
  *
@@ -466,12 +466,12 @@ export type WriteMode = "create" | "update";
 /** The field names this table accepts on the wire in `mode`, in declaration order. */
 export declare function writableFieldNames(table: ConfigTable, mode: WriteMode): string[];
 /**
- * The field names the server PERSISTS for this table in `mode`: the writable
- * fields, plus the `deprecated` classifications — "still writable, superseded
- * by another field" is what that kind means (`types.ts`), so a superseded key
- * a handler still honors (`passkeyRpId`, or a flat chat key such as
- * `systemPrompt` under `[[configs]]`, #3626) belongs in every
- * accepted set, and a field that is NOT writable belongs in none of them.
+ * The field names the server ACCEPTS for this table in `mode`: the writable
+ * fields, plus the `deprecated` classifications — "still accepted, superseded
+ * or scheduled for removal" is what that kind means (`types.ts`), so a
+ * superseded key a handler still honors (`protected`) and a retired one it
+ * accepts and ignores (`accessRule`, #4872) belong 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.
@@ -630,8 +630,9 @@ export declare function acceptedGroupTomlKeys(table: ConfigTable, group: string)
  * 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 declare function acceptedTomlKeys(table: ConfigTable): Set<string>;
 /**
@@ -980,11 +981,11 @@ export declare function findUnreachedPreflightRules(surface: ConfigObjectSurface
  *
  * ── What the schema says, and what it deliberately does not ──────────────
  * It states the KEY SET only: each property is the empty schema (or carries
- * only the `deprecated` annotation, #1815), so no value is type-checked here. That is the decision of record (#1976, carried forward at
- * #2644's design gate): the definition classifies, handlers behave. The
- * `status` enum, the queue limits' integer coercion, `runAs`'s caller|system
- * check, the CEL parse of `accessRule` — all stay in the handlers the
- * definition names, with their existing messages. Adding type gates here would
+ * only the `deprecated` annotation, #1815), so no value is type-checked here.
+ * That is the decision of record (#1976, carried forward at #2644's design
+ * gate): the definition classifies, handlers behave. The `status` enum, the
+ * queue limits' integer coercion, the CEL parse of a rule set's expressions —
+ * all stay in the handlers the definition names, with their existing messages. Adding type gates here would
  * duplicate them and start rejecting values the handlers accept.
  *
  * ── Which keys are in the set ────────────────────────────────────────────
@@ -1017,7 +1018,8 @@ export interface ConfigRequestSchema {
     type: "object";
     /**
      * Each property is the empty schema, or `{ deprecated: true }` for a field
-     * the definition marks `deprecated` (#1815). `deprecated` is an OpenAPI
+     * the definition marks `deprecated` (#1815) or a key `notExposed` classifies
+     * `deprecated` (#4872). `deprecated` is an OpenAPI
      * annotation: it constrains no value, so the schema still states the key set
      * and nothing more.
      */
@@ -1089,7 +1091,7 @@ export declare function unknownRequestKeysMessage(keys: readonly string[]): stri
  * retired key: the TOML wording for `config push` (which can tell the author to
  * delete a line) and the request wording for the API handlers (which cannot).
  *
- * Keyed by the table's TOML path prefix (`workflow`, `cronTrigger`, …), because
+ * Keyed by the table's TOML path prefix (`integration`, `prompt`, …), because
  * that is the identifier both consumers already have in hand.
  *
  * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity).
@@ -1101,8 +1103,85 @@ export interface RetiredConfigKey {
     request: string;
 }
 export declare const RETIRED_CONFIG_KEYS: Record<string, Record<string, RetiredConfigKey>>;
+/**
+ * Keys DEPRECATED on a configuration object's write surface: still accepted
+ * in TOML and on the wire, ignored, and scheduled for removal.
+ *
+ * A deprecated key sits between a live field and a retired one. The table
+ * classifies it `deprecated` in both `notExposed` (so a body that still sends
+ * it is accepted) and `tomlOnlyKeys` (so a file that still carries it
+ * validates); this registry holds the one sentence `config push` prints for a
+ * file that carries it, and is what `config pull` keys its forced rewrite on,
+ * so the pull the sentence names removes the line.
+ *
+ * Keyed by the table's TOML path prefix, like `RETIRED_CONFIG_KEYS`. The
+ * scheduled break moves an entry from here to that map.
+ */
+export interface DeprecatedConfigKey {
+    /** What `config push` says, once per file, about a file that carries the key. */
+    toml: string;
+}
+export declare const DEPRECATED_CONFIG_KEYS: Record<string, Record<string, DeprecatedConfigKey>>;
+/** The deprecated-key entry for `key` under `prefix`, or null when it is not deprecated. */
+export declare function deprecatedConfigKey(prefix: string, key: string): DeprecatedConfigKey | null;
+/**
+ * Config-tree directories whose object type retired — #3190, server-functions
+ * phase 7. The DSL engine, the Rhai runtime and the standalone webhook and
+ * cron objects are gone, so `config push` refuses a tree that still holds one
+ * of these directories, by name and before it writes anything, rather than
+ * ignoring files an author still expects to take effect.
+ *
+ * Each entry is one sentence: what retired, what replaces it, and the docs page
+ * that shows the replacement.
+ */
+export declare const RETIRED_CONFIG_DIRECTORIES: Record<string, string>;
+/**
+ * The type-config directories a config tree no longer has (#4731, project
+ * `role-based-groups-collections`). Groups and collections have fixed roles,
+ * so their per-type configuration retired with its routes; `config push`
+ * refuses a tree that still holds a file in either, naming each file, rather
+ * than ignoring files an author still expects to take effect. The rows the
+ * server already stored are not touched.
+ *
+ * Each entry is one sentence: what retired, and what replaces it.
+ */
+export declare const RETIRED_TYPE_CONFIG_DIRECTORIES: Record<string, string>;
+/** The retirement sentence for a config-tree directory, or null when it is live. */
+export declare function retiredConfigDirectory(dir: string): string | null;
+/**
+ * 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 declare const RETIRED_DOCUMENT_KEYS: Record<string, Record<string, RetiredTomlSpelling>>;
+/** The retired-table guidance for `key` on the surface labelled `label`, or null. */
+export declare function retiredDocumentKey(label: string, key: string): RetiredTomlSpelling | null;
 /** The retired-key entry for `key` under `prefix`, or null when it is simply unknown. */
 export declare function retiredConfigKey(prefix: string, key: string): RetiredConfigKey | null;
+/**
+ * A spelling retired from the TOML surface only: the request body still
+ * carries the key, so there is no request sentence to give.
+ */
+export interface RetiredTomlSpelling {
+    /** What `config push` says about a file that still writes the key this way. */
+    toml: string;
+}
+/**
+ * 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 declare const RETIRED_TOML_SPELLINGS: Record<string, Record<string, RetiredTomlSpelling>>;
+/**
+ * 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 declare function retiredTomlKey(prefix: string, key: string): RetiredTomlSpelling | null;
 /**
  * The capability grammar for server functions — #3182 phase 1, rewritten by
  * #3279 (project `server-functions` phase 3).
@@ -1125,7 +1204,10 @@ export declare function retiredConfigKey(prefix: string, key: string): RetiredCo
  *   `secret:<NAME>`       credential least privilege — which secret VALUES may
  *                         cross into the sandbox at all;
  *   the high-blast list   {@link HIGH_BLAST_CAPABILITIES} — the operations
- *                         whose blast radius the intent keeps opt-in.
+ *                         whose blast radius the intent keeps opt-in;
+ *   the subject grants    {@link SUBJECT_GRANT_CAPABILITIES} — naming another
+ *                         member on a call about one user, in a run a plain
+ *                         member invoked.
  *
  * Every other string a function used to declare is RETIRED, and the grammar
  * says so by name: an author who still writes `database:orders/Order:read`
@@ -1178,15 +1260,44 @@ export declare const KEYED_GRANT_FAMILIES: readonly ["integration", "secret"];
  * other — `databases:create` is not permission to delete a database.
  *
  * The database ROLE mutations are here because they hand out persistent
- * authority: a group grant assigns the manager role (D3279-003). App deletion
+ * authority: a group grant assigns the manager role (D3279-003). A db3's sync
+ * switch (`db3:setSync`, the intent's `db3-sync` grant) is here because
+ * turning sync off suspends every grant on the db3 (#4799); a db3's transfer
+ * and its owner-row change (`db3:transfer`, `db3:setOwnerRow`, the intent's
+ * `db3-grant` grant) because they move who holds the db3 and its owner row
+ * (#4800); its app access (`db3:setAppAccess`, the same grant's third string)
+ * because it grants the db3 to every user of the app (#4801). App deletion
  * and secret writes have no app-API route today; they are recorded, not gated,
  * and the profile generator refuses to admit a future such route without a row
  * here (`HIGH_BLAST_WATCH` in `scripts/lib/function-profile.mjs`).
  */
-export declare const HIGH_BLAST_CAPABILITIES: readonly ["databases:create", "databases:delete", "databases:transferOwnership", "databases:addManager", "databases:revokePermission", "databases:grantGroupPermission", "databases:revokeGroupPermission", "users:remove", "users:setRole", "blobBuckets:createBucket", "blobBuckets:deleteBucket"];
-/** The exact strings, which since #3279 are exactly the high-blast list. */
-export declare const EXACT_GRANT_STRINGS: readonly ["databases:create", "databases:delete", "databases:transferOwnership", "databases:addManager", "databases:revokePermission", "databases:grantGroupPermission", "databases:revokeGroupPermission", "users:remove", "users:setRole", "blobBuckets:createBucket", "blobBuckets:deleteBucket"];
-export type GrantFamily = (typeof KEYED_GRANT_FAMILIES)[number] | "databases" | "users" | "blobBuckets";
+export declare const HIGH_BLAST_CAPABILITIES: readonly ["databases:create", "databases:delete", "databases:transferOwnership", "databases:addManager", "databases:revokePermission", "databases:grantGroupPermission", "databases:revokeGroupPermission", "users:remove", "users:setRole", "blobBuckets:createBucket", "blobBuckets:deleteBucket", "db3:setSync", "db3:transfer", "db3:setOwnerRow", "db3:setAppAccess"];
+/**
+ * The subject grants — #4909.
+ *
+ * A run a plain member invoked may name nobody but its caller on a call that
+ * is about one user (#4142's subject rule): `SUBJECT_USER_FORBIDDEN`. A
+ * function whose own code chooses that user — a class's teacher removing a
+ * student and reading where else the student is enrolled — declares it here,
+ * in a line a reviewer can find:
+ *
+ *   `users:readAny`   the user-subject READS may name another member
+ *                     (memberships, a member's collections and documents,
+ *                     their root document, inbox, devices, agent sessions);
+ *   `users:actAsAny`  the calls that ACT as a member may name another member
+ *                     (marking their notifications read, their devices, an
+ *                     agent session as them, `ctx.db3` `asUser`, their
+ *                     aliases).
+ *
+ * Each admits only its own kind. Neither changes a run with no caller, an
+ * owner- or admin-invoked run, or a run an agent drives (refused either way),
+ * and a nested child reads its own version's. They are not high-blast rows:
+ * those are 1:1 with an operation id, and these name a rule, not an operation.
+ */
+export declare const SUBJECT_GRANT_CAPABILITIES: readonly ["users:readAny", "users:actAsAny"];
+/** The exact strings: the high-blast list and the subject grants. */
+export declare const EXACT_GRANT_STRINGS: readonly string[];
+export type GrantFamily = (typeof KEYED_GRANT_FAMILIES)[number] | "databases" | "users" | "blobBuckets" | "db3";
 /**
  * The retired FAMILIES (#3279), each with the reason it is gone.
  *
@@ -1388,7 +1499,21 @@ export declare function validateKeyedGrantsAgainstTargets(grants: readonly Funct
  * A version-1 manifest still parses: it records registrations only.
  */
 export declare const FUNCTION_MANIFEST_SCHEMA_VERSION = 2;
-export declare const FUNCTION_MANIFEST_SCHEMA_VERSIONS: readonly [1, 2];
+export declare const FUNCTION_MANIFEST_SCHEMA_VERSIONS: readonly [1, 2, 3];
+/**
+ * Version 3 (#4730) adds what a version's `authorize` admits: the
+ * `authorize` block and the `writeFamilies` its handler reaches. Only a
+ * FLAGGED build emits it — the manifest is inside the envelope hash, so a
+ * universal bump would make every untouched bare-handler tree a new version
+ * on its next push. A bare-handler tree keeps emitting version 2.
+ */
+export declare const FUNCTION_MANIFEST_AUTHORIZE_SCHEMA_VERSION = 3;
+/** The `auth.*` families an `authorize` can read, as the manifest names them. */
+export declare const AUTH_FAMILIES: readonly ["auth.user", "auth.trigger", "auth.memberships", "auth.collections", "auth.doc", "auth.db", "auth.configVar"];
+/** The SDK helpers that build an `authorize`, as the manifest names them. */
+export declare const AUTHORIZE_HELPERS: readonly ["allowAnyone", "allowCallers", "requireSignedIn", "requireRole", "requireMember", "requireCollectionRole", "requireDocumentOwner"];
+/** How many function keys an `allowCallers` block may list. */
+export declare const MAX_MANIFEST_CALLER_FUNCTIONS = 200;
 /** Bounds, so a manifest cannot be a way to store an unbounded blob. */
 export declare const MAX_MANIFEST_QUERIES = 200;
 export declare const MAX_MANIFEST_NAME_LENGTH = 120;
@@ -1439,6 +1564,35 @@ export interface ManifestQuery {
     /** True when a `$caller` binding scopes this registration. */
     callerScoped: boolean;
 }
+/** The doors an `allowCallers` admits, as collected (#4730). */
+export interface ManifestAuthorizeCallers {
+    webhook: boolean;
+    cron: boolean;
+    manual: boolean;
+    /** The parent function keys the `functions` arm names. */
+    functions: string[];
+    /** `true`, `false`, or `"rule"` when the arm is an authorize function. */
+    agents: boolean | "rule";
+    /** `"rule"` when a `users` arm is present, else false. */
+    users: false | "rule";
+    /**
+     * #4803 — the db3 flush door. Optional: a manifest collected before the door
+     * existed carries no key, and absent reads as closed.
+     */
+    db3?: boolean;
+}
+/** What a version's `authorize` admits, as collected (#4730). */
+export interface ManifestAuthorize {
+    present: true;
+    /** `allowAnyone()`, or an `allowCallers` whose users or agents rule is one. */
+    public: boolean;
+    /** The SDK helper that built the exported `authorize`, or null when hand-written. */
+    helper: string | null;
+    /** The doors, when the helper is `allowCallers`; else null. */
+    callers: ManifestAuthorizeCallers | null;
+    /** The `auth.*` families the authorize code reaches, sorted. */
+    families: string[];
+}
 export interface FunctionManifest {
     schemaVersion: number;
     queries: ManifestQuery[];
@@ -1457,6 +1611,13 @@ export interface FunctionManifest {
      * empty `models` list does not.
      */
     dynamicModels: boolean;
+    /**
+     * Version 3 only: the families on which the scan met a write or send verb.
+     * Absent on versions 1 and 2, which readers treat as `[]`.
+     */
+    writeFamilies?: string[];
+    /** Version 3 only: the `authorize` block. Absent on 1 and 2 (read as null). */
+    authorize?: ManifestAuthorize;
 }
 export interface ParsedManifest {
     ok: boolean;
@@ -1471,9 +1632,68 @@ export interface ParsedManifest {
  * and whether the author meant any of it are questions this cannot answer.
  */
 export declare function parseFunctionManifest(value: unknown): ParsedManifest;
+/**
+ * Whether a top-level input schema is one the closed-schema default leaves
+ * OPEN under its union exemption — #4730, criterion 9.
+ *
+ * The validator closes an object against the root's OWN `properties` only,
+ * so a root whose `anyOf` or `oneOf` members declare `properties` of their
+ * own would, closed, refuse the very keys its members declare. Such a root is
+ * left open, and `config push` warns its author to say `additionalProperties`
+ * explicitly. Shared by the server (`closedInputSchemaFor`) and the CLI's
+ * push warning, so both sides read one rule.
+ */
+export declare function inputSchemaRootLeftOpen(schema: unknown): boolean;
+/**
+ * The schema a flagged version validates against — #4730, criterion 9.
+ *
+ * A top-level object schema that sets no `additionalProperties` reads as
+ * closed: a shallow copy with `additionalProperties: false`. Every other
+ * schema is answered as it is — an explicit `additionalProperties`, a
+ * non-object root, an empty `{}`, and a root left open under
+ * {@link inputSchemaRootLeftOpen}. Nested objects are not touched. Applied at
+ * run time and never written to the header.
+ */
+export declare function closedObjectSchema(schema: Record<string, unknown>): Record<string, unknown>;
+/**
+ * `[function] public`, read from the authored TOML's `[function]` table —
+ * #4730, criterion 13. Absent reads as false; anything but a boolean is
+ * refused. Read by the CLI's preflight and by the server from the envelope's
+ * TOML, never stored.
+ */
+export declare function declaredPublicOf(functionTable: unknown): {
+    ok: true;
+    value: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * What makes a version write-capable for the public-writer lint — #4730: a
+ * mutation registration, a family the manifest records a write or send verb
+ * on, or a declared `integration:<key>`, high-blast or subject-grant
+ * capability (#4909: a function anyone may invoke that names any member is
+ * the same hazard). One phrase per reason, for the refusal to quote.
+ */
+export declare function writeCapableReasons(manifest: FunctionManifest | null, capabilities: readonly string[]): string[];
+/**
+ * The public-writer refusal — #4730, criterion 13: a version whose manifest
+ * records `authorize.public` (an `allowAnyone()`, or an `allowCallers` arm
+ * that is one) and that is write-capable needs `public = true` under
+ * `[function]`. The sentence names the function, what makes it write-capable
+ * and the fix; null when the push is fine. The CLI refuses at preflight and
+ * the server at push, from this one rule.
+ */
+export declare function publicWriterRefusal(input: {
+    functionKey: string;
+    manifest: FunctionManifest | null;
+    capabilities: readonly string[];
+    declaredPublic: boolean;
+}): string | null;
 /**
  * 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
@@ -1482,58 +1702,70 @@ export declare function parseFunctionManifest(value: unknown): ParsedManifest;
  * 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 declare const RETIRED_FUNCTION_RUNTIME_KEYS: readonly ["mode", "durable"];
 export type RetiredFunctionRuntimeKey = (typeof RETIRED_FUNCTION_RUNTIME_KEYS)[number];
-/** One ignored key met in a `[function]` table. */
-export interface IgnoredFunctionKey {
+/**
+ * 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 declare const RETIRED_RUNTIME_KEY_RULE_IDS: readonly ["retired-runtime-key"];
+type RetiredRuntimeKeyRuleId = (typeof RETIRED_RUNTIME_KEY_RULE_IDS)[number];
+/** One retired key met in a `[function]` table. */
+export interface RetiredFunctionKey extends RuleRefusal<RetiredRuntimeKeyRuleId> {
     /**
      * Where it was: `mode`, `durable`, or `triggers.cron.<name>.mode`. Never
      * rendered on its own — a reader that wants to branch reads this, and every
      * printer reads `message`.
      */
     path: string;
-    /** The sentence the author is owed, with no file prefix (the caller adds it). */
-    message: string;
 }
 /**
- * Every retired runtime key a `[function]` table still 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).
+ * The pre-phase-5 name of a met key, kept for the CLI's pull strip, which only
+ * needs `path`. Every key met is refused now.
+ */
+export type IgnoredFunctionKey = RetiredFunctionKey;
+/**
+ * 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 declare function refusedFunctionKeys(functionTable: unknown): RetiredFunctionKey[];
+/**
+ * The same refusals, rendered for one file — the shape `config push` and
+ * `config diff` print.
  *
- * Order is the order an author reads their file in: the top-level keys first,
- * then the cron entries in declaration order.
+ * `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 declare function ignoredFunctionKeys(functionTable: unknown): IgnoredFunctionKey[];
+export declare function refusedFunctionKeyMessages(label: string, functionTable: unknown): string[];
 /**
  * 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
@@ -1565,14 +1797,6 @@ export declare function retiredDatabaseTriggerTypes(functionTable: unknown): str
  * of them would call a block and the other would not cannot exist.
  */
 export declare function hasRetiredDatabaseTriggerBlock(functionTable: unknown): boolean;
-/**
- * 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 declare function ignoredFunctionKeyWarnings(label: string, functionTable: unknown): string[];
 /**
  * The trigger blocks a function declares, derived from its authored TOML
  * (#3181, project `server-functions`, criterion 4).
@@ -1634,6 +1858,12 @@ export declare function ignoredFunctionKeyWarnings(label: string, functionTable:
  * as ignored by `ignoredFunctionKeys` in `function-retired-keys.ts`.
  */
 /** A function's single webhook trigger, normalized. */
+/**
+ * The db3 type-name prefix the platform reserves for its own types (#4882,
+ * project `agent-sessions-db3`): no app pushes, attaches or watches a type
+ * whose name starts with it.
+ */
+export declare const RESERVED_DB3_TYPE_PREFIX = "primitive:";
 export interface WebhookTriggerDeclaration {
     verificationScheme: string;
     signingSecret?: string;
@@ -1644,7 +1874,28 @@ export interface WebhookTriggerDeclaration {
     secretGracePeriodMs?: number;
     /** `[function.triggers.webhook.verification]` — the row's `config`. */
     verification?: Record<string, unknown>;
+    /**
+     * `[[function.triggers.webhook.handshakeRules]]` — a provider's setup
+     * handshake (Slack `url_verification`, Discord PING, Microsoft Graph
+     * `validationToken`, Meta `hub.challenge`), answered by the receiver after
+     * verification and before the function runs (#3190).
+     */
+    handshakeRules?: WebhookHandshakeRuleDeclaration[];
+    /** `allowedIpCidrs` — the sender addresses a delivery may come from (#3190). */
+    allowedIpCidrs?: string[];
 }
+/** One handshake rule: a CEL `when` and the response it answers with. */
+export interface WebhookHandshakeRuleDeclaration {
+    when: string;
+    response: {
+        status?: number;
+        contentType?: string;
+        body?: string;
+    };
+}
+/** The most handshake rules and allowlist entries one webhook block may carry. */
+export declare const MAX_WEBHOOK_HANDSHAKE_RULES = 10;
+export declare const MAX_WEBHOOK_IP_CIDRS = 50;
 /** One `[[function.triggers.cron]]` entry, normalized. */
 export interface CronTriggerDeclaration {
     name: string;
@@ -1653,9 +1904,20 @@ export interface CronTriggerDeclaration {
     overlapPolicy?: string;
     rootInput?: unknown;
 }
+/** One `[[function.triggers.db3]]` entry, normalized (#4803). */
+export interface Db3TriggerDeclaration {
+    /** The db3 type whose flushes start the function. */
+    type: string;
+}
 export interface TriggerDeclaration {
     webhook: WebhookTriggerDeclaration | null;
     cron: CronTriggerDeclaration[];
+    /**
+     * `[[function.triggers.db3]]` — present only when the file declares at least
+     * one entry, so a file written before the kind existed stores exactly the
+     * JSON it stored before (#4803).
+     */
+    db3?: Db3TriggerDeclaration[];
 }
 export declare const EMPTY_TRIGGER_DECLARATION: TriggerDeclaration;
 /**
@@ -1667,13 +1929,19 @@ export declare const EMPTY_TRIGGER_DECLARATION: TriggerDeclaration;
  * remaining slots for the other 40+ objects the cap is sized for.
  */
 export declare const MAX_CRON_TRIGGERS_PER_FUNCTION = 10;
+/**
+ * The most db3 types one function may watch — the cron cap's per-object
+ * reasoning (#4803). The per-app ceiling is `MAX_DB3_TRIGGERS_PER_APP`, checked
+ * at the push boundary.
+ */
+export declare const MAX_DB3_TRIGGERS_PER_FUNCTION = 10;
 /**
  * The rule ids this module owns — one per refusal, declared on the `function`
  * surface (#3374). The union below closes `refuseTrigger`'s id parameter, so a
  * twenty-seventh refusal cannot compile without a twenty-seventh id, and that
  * id fails `cli-unit-tests` until the surface declares it (#3373's anchor).
  */
-export declare const TRIGGER_RULE_IDS: readonly ["triggers-table", "trigger-kind", "database-trigger-removed", "webhook-trigger-single", "webhook-trigger-table", "webhook-trigger-keys", "webhook-trigger-scheme-required", "webhook-trigger-scheme-none", "webhook-trigger-number", "webhook-trigger-dedup-boolean", "webhook-trigger-verification-table", "cron-trigger-cap", "cron-trigger-entry", "cron-trigger-keys", "cron-trigger-name-required", "cron-trigger-name-charset", "cron-trigger-duplicate", "cron-trigger-expression-required", "cron-trigger-overlap-policy"];
+export declare const TRIGGER_RULE_IDS: readonly ["triggers-table", "trigger-kind", "database-trigger-removed", "webhook-trigger-single", "webhook-trigger-table", "webhook-trigger-keys", "webhook-trigger-scheme-required", "webhook-trigger-scheme-none", "webhook-trigger-number", "webhook-trigger-dedup-boolean", "webhook-trigger-verification-table", "webhook-trigger-handshake-rules", "webhook-trigger-ip-allowlist", "cron-trigger-cap", "cron-trigger-entry", "cron-trigger-keys", "cron-trigger-name-required", "cron-trigger-name-charset", "cron-trigger-duplicate", "cron-trigger-expression-required", "cron-trigger-overlap-policy", "db3-trigger-cap", "db3-trigger-entry", "db3-trigger-keys", "db3-trigger-type-required", "db3-trigger-type-reserved", "db3-trigger-duplicate"];
 export type TriggerRuleId = (typeof TRIGGER_RULE_IDS)[number];
 /**
  * A broken trigger rule. `ruleId` names which one, for a reader that wants to
@@ -1714,6 +1982,18 @@ export declare function storedDatabaseTriggerTypes(stored: unknown): string[];
 export declare function cronTriggerKeyFor(functionKey: string, name: string): string;
 /** The entry name a `<functionKey>:<name>` trigger key carries. */
 export declare function cronTriggerNameFrom(functionKey: string, triggerKey: string): string;
+/**
+ * The `ServerFunctionTrigger.triggerKey` a db3 entry owns (#4803):
+ * `<functionKey>:db3:<type>`. A cron name cannot hold `:`, so the key never
+ * collides with a cron entry's `<functionKey>:<name>`.
+ */
+export declare function db3TriggerKeyFor(functionKey: string, type: string): string;
+/**
+ * The type a db3 trigger key carries, or null when the key is not this
+ * function's db3 key. Read by stripping the prefix, never by splitting: a type
+ * name may hold `:` and `/`.
+ */
+export declare function db3TriggerTypeFrom(functionKey: string, triggerKey: string): string | null;
 /**
  * The `{{secrets.KEY}}` reference SHAPE, decided from the value alone.
  *
@@ -1916,53 +2196,6 @@ export declare function validateSigningSecretDeclaration(input: {
     verificationScheme: string;
     signingSecret?: unknown;
 }): SigningSecretRuleError | null;
-/**
- * The workflow rules two runners share (#3374, project `cli-server-rule-parity`
- * phase 2; intent §Success criteria 3).
- *
- * ── One predicate, two messages ──────────────────────────────────────────
- *
- * `runAs = "system"` beside a non-empty `accessRule` is dead config: a system
- * run can only be started by the system and never evaluates its access rule
- * (#1258, broadening #1172). The server refused it at save time
- * (`validateWorkflowIdentityConfig`) and the CLI refused it in the push
- * preflight (`validateWorkflowIdentity`), and the two carried the conjunction
- * byte-for-byte as separate copies kept in step by a comment. This module is
- * the one copy: it decides, and returns a STRUCTURED violation — the rule id
- * and the server's sentence — that each site renders in its own words. The
- * server pushes the sentence into its `string[]`; the CLI keeps its own hint,
- * which names the preflight remedy. Neither message changed.
- *
- * ── Why a `*-rules.ts` module ────────────────────────────────────────────
- *
- * The registry's unclaimed-export check (`findUnclaimedRuleModuleExports`)
- * keys on this name under `src/config-surface/`: every exported function here
- * is a rule, so one no surface declares fails `cli-unit-tests`. Shared
- * predicates that are not rules live elsewhere (`webhook-signing-secret.ts`).
- * The module is vendored into the CLI artifact like the rest of the
- * directory, which is what lets `workflow`'s declaration call the rule
- * `preflight`.
- */
-/** The rule ids this module owns — the union type below anchors them (#3373). */
-export declare const WORKFLOW_RULE_IDS: readonly ["system-access-rule"];
-type WorkflowRuleId = (typeof WORKFLOW_RULE_IDS)[number];
-/** A violation of one of this module's rules, for a site to render. */
-export interface WorkflowRuleViolation extends RuleRefusal<WorkflowRuleId> {
-}
-/**
- * `runAs = "system"` with a non-empty string `accessRule`, or null.
- *
- * Exactly the conjunction both sites carried: a default, unset, empty or
- * whitespace-only rule is no rule, and a non-string one (`accessRule = false`)
- * is malformed input for another check to name, not dead config. The message
- * is the server's save-time sentence; the CLI renders its own hint from the
- * same answer.
- */
-export declare function checkWorkflowSystemAccessRule(input: {
-    runAs?: unknown;
-    accessRule?: unknown;
-}): WorkflowRuleViolation | null;
-export declare const WORKFLOW_SURFACE: ConfigObjectSurface;
 /**
  * Cron-expression and timezone VALIDITY — the half of `src/cron-parser.ts`
  * both runners need (#3376, project `cli-server-rule-parity` phase 4).
@@ -2074,15 +2307,6 @@ export declare function isValidTimezone(name: unknown): boolean;
  * pins. So the grammar and the `Intl` probe live next door in
  * `cron-expression.ts`, which is a shared-predicate module rather than a rules
  * module, and this one only decides and renders.
- *
- * ── What is NOT shared ───────────────────────────────────────────────────
- *
- * The standalone cron routes ask the same two predicates and render their own
- * `Invalid cron expression: …` / `Invalid timezone: …`, with their own
- * defaulting (create reads an absent timezone as UTC, update does not). That
- * is intent assumption 2 in the form its own fallback describes, and the shape
- * `workflow-rules.ts` set in phase 2: one predicate, each site's message and
- * defaulting preserved. No refusal message changed anywhere.
  */
 /** The rule ids this module owns — the union type below anchors them (#3373). */
 export declare const CRON_TRIGGER_RULE_IDS: readonly ["cron-trigger-expression", "cron-trigger-timezone"];
@@ -2120,7 +2344,12 @@ export declare 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
@@ -2133,20 +2362,18 @@ export declare 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. */
 export declare const REASONING_EFFORTS: readonly ["none", "minimal", "low", "medium", "high"];
 export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
-/** The smallest budget Gemini 2.5 Pro accepts; it cannot stop thinking. */
-export declare const GEMINI_PRO_MIN_THINKING_BUDGET = 128;
 export interface PromptReasoningInput {
     provider?: string | null;
     model?: string | null;
@@ -2178,14 +2405,12 @@ export type PromptReasoningResolution = {
 /**
  * How a Gemini model spells its thinking control.
  *
- * `level` — Gemini 3.x, `thinkingLevel`, cannot be turned off.
+ * `level` — Gemini 3.x, `thinkingLevel`, which has no "off" value.
  * `budget` — Gemini 2.5, `thinkingBudget` in tokens.
  * `none` — Gemini 2.0 and earlier, no control at all.
  */
 export type GeminiReasoningFamily = "level" | "budget" | "none";
 export declare function geminiReasoningFamily(model: string): GeminiReasoningFamily;
-/** Gemini Pro: the tier that cannot stop thinking in either family. */
-export declare function isGeminiProModel(model: string): boolean;
 /** Is EITHER reasoning key stated on this config? */
 export declare function hasPromptReasoning(input: PromptReasoningInput): boolean;
 /**
@@ -2228,17 +2453,11 @@ export declare function resolvePromptReasoning(input: PromptReasoningInput): Pro
  */
 export declare const PROMPT_KINDS: readonly ["chat", "decisions", "agent"];
 export type PromptKind = (typeof PROMPT_KINDS)[number];
-/**
- * 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).
- */
-export declare const LEGACY_FLAT_CHAT_KEYS: readonly ["systemPrompt", "userPromptTemplate", "temperature", "topP", "maxTokens", "outputFormat", "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).
+ * 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
@@ -2368,29 +2587,6 @@ export type DecisionsRunQuestionsResolution = {
  * Pure: the stored questions object is never mutated.
  */
 export declare function resolveDecisionsRunQuestions(questions: Record<string, unknown>, runCriteria: unknown): DecisionsRunQuestionsResolution;
-/** What the hoist did to one `[[configs]]` entry. */
-export interface DeprecatedChatKeyHoist {
-    /** A COPY of the entry with the flat chat keys moved under `chat`. */
-    entry: Record<string, unknown>;
-    /** The flat keys that were moved, sorted — what the warning names. */
-    moved: string[];
-    /** Keys set BOTH flat and under `[configs.chat]`; the caller refuses these. */
-    conflicts: string[];
-}
-/**
- * Move the deprecated flat chat keys of one `[[configs]]` entry under `chat`
- * — #3626 §4, the deprecated-TOML-key pattern blob buckets used until #3996
- * retired theirs, 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 declare function hoistDeprecatedChatKeys(entry: unknown): DeprecatedChatKeyHoist;
 /**
  * Strict output for a chat config — issue #3801 (project `agents`, §D6).
  *
@@ -2504,7 +2700,7 @@ export declare function resolvePromptStrictOutput(input: PromptStrictOutputInput
  * Pure and dependency-free, like every module under `src/config-surface/`.
  */
 /** The stable codes every agent agentRefusal this project adds carries. */
-export declare const AGENT_ERROR_CODES: readonly ["AGENT_DECLARATION_INVALID", "AGENT_TOOL_FUNCTION_MISSING", "AGENT_TOOL_FUNCTION_SCHEMA_MISSING", "AGENT_OUTPUT_SCHEMA_NOT_ALLOWED", "AGENT_CONFIG_KEY_NOT_ALLOWED", "AGENT_NOT_RUNNABLE", "AGENT_TEST_CASE_NOT_SUPPORTED", "AGENT_SCHEMA_NOT_TRANSLATABLE", "AGENT_MODEL_UNKNOWN", "AGENT_MODEL_CAPABILITY_MISSING", "AGENT_MODEL_CAPABILITIES_UNAVAILABLE", "AGENT_ROUND_NOT_AGENT", "AGENT_ROUND_INPUT_INVALID", "AGENT_TOOL_UNKNOWN", "AGENT_TOOL_ARGUMENTS_INVALID", "AGENT_ROUND_TRUNCATED", "AGENT_ROUND_EMPTY"];
+export declare const AGENT_ERROR_CODES: readonly ["AGENT_DECLARATION_INVALID", "AGENT_TOOL_FUNCTION_MISSING", "AGENT_TOOL_FUNCTION_SCHEMA_MISSING", "AGENT_OUTPUT_SCHEMA_NOT_ALLOWED", "AGENT_CONFIG_KEY_NOT_ALLOWED", "AGENT_NOT_RUNNABLE", "AGENT_TEST_CASE_NOT_SUPPORTED", "AGENT_SCHEMA_NOT_TRANSLATABLE", "AGENT_MODEL_UNKNOWN", "AGENT_MODEL_CAPABILITY_MISSING", "AGENT_MODEL_CAPABILITIES_UNAVAILABLE", "AGENT_ROUND_NOT_AGENT", "AGENT_ROUND_INPUT_INVALID", "AGENT_TOOL_UNKNOWN", "AGENT_TOOL_ARGUMENTS_INVALID", "AGENT_ROUND_TRUNCATED", "AGENT_ROUND_EMPTY", "AGENT_TEST_CASE_INVALID", "AGENT_PRESENTATION_REFERENCE_INVALID"];
 export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[number];
 /** One agentRefusal: the code a client branches on, and the sentence a person reads. */
 export interface AgentRefusal {
@@ -2512,16 +2708,20 @@ export interface AgentRefusal {
     message: string;
 }
 /**
- * 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 declare const AGENT_LIMITS: {
     readonly maxSteps: 25;
     readonly waitLimitSeconds: 604800;
+    /** The JSON bytes of one session-document row a turn writes from model or tool output. */
+    readonly maxRowBytes: 262144;
     readonly tools: 64;
     readonly events: 64;
 };
+/** The smallest row ceiling an agent may declare: room for a call's own columns. */
+export declare 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.
@@ -2530,9 +2730,16 @@ export declare const AGENT_NAME: RegExp;
 export declare const AGENT_ANSWERED_BY: readonly ["initiator", "participants"];
 export declare const AGENT_TOOL_INVOKE: readonly ["request", "task"];
 export declare const AGENT_TOOL_HISTORY_SCOPES: readonly ["session", "turn"];
+/**
+ * Where a tool without a `function` runs: `client` is answered by a member's
+ * client; `presentation` is data the model hands the client with its final
+ * answer, which no client executes (#4549).
+ */
+export declare const AGENT_TOOL_RUNS: readonly ["client", "presentation"];
 export type AgentAnsweredBy = (typeof AGENT_ANSWERED_BY)[number];
 export type AgentToolInvoke = (typeof AGENT_TOOL_INVOKE)[number];
 export type AgentToolHistoryScope = (typeof AGENT_TOOL_HISTORY_SCOPES)[number];
+export type AgentToolRuns = (typeof AGENT_TOOL_RUNS)[number];
 /** A JSON Schema object, as the declaration holds one. */
 export type AgentSchema = Record<string, unknown>;
 /** One `[[prompt.agent.tools]]` entry, as authored. */
@@ -2542,13 +2749,28 @@ export interface AgentToolDeclaration {
     /** A server tool: the function whose schemas are the tool's. */
     function?: string;
     invoke?: AgentToolInvoke;
-    /** A client tool: answered by a member's client, schemas in the TOML. */
-    runs?: "client";
+    /**
+     * `client`: answered by a member's client, schemas in the TOML.
+     * `presentation`: data the model hands the client with its final answer;
+     * its call ends the turn and is never answered.
+     */
+    runs?: AgentToolRuns;
+    /**
+     * A presentation's input properties whose integers name earlier calls of
+     * the turn by the number the platform gave them (`callNumber`).
+     */
+    references?: string[];
     inputSchema?: AgentSchema;
     outputSchema?: AgentSchema;
     approval?: boolean;
     statusText?: string;
     historyScope?: AgentToolHistoryScope;
+    /**
+     * A call to this server tool ends the turn: once every call of its response
+     * is final, the turn settles with no further model round. A presentation
+     * always does.
+     */
+    endsTurn?: boolean;
 }
 /** One `[[prompt.agent.events]]` entry. */
 export interface AgentEventDeclaration {
@@ -2560,6 +2782,7 @@ export interface AgentDeclaration {
     answeredBy?: AgentAnsweredBy;
     maxSteps?: number;
     waitLimitSeconds?: number;
+    maxRowBytes?: number;
     turnContext?: {
         schema: AgentSchema;
         function?: string;
@@ -2575,12 +2798,24 @@ export interface AgentDeclaration {
 export type NormalizedAgentTool = AgentToolDeclaration & {
     approval: boolean;
     historyScope: AgentToolHistoryScope;
+    endsTurn: boolean;
 };
+/**
+ * The result the platform records for a presentation call: the call is final
+ * when its response is committed, and later rounds read this as its tool
+ * result.
+ */
+export declare const AGENT_TERMINAL_CALL_OUTPUT: {
+    delivered: true;
+};
+/** The schema of `AGENT_TERMINAL_CALL_OUTPUT`, the result a presentation call is recorded with. */
+export declare const AGENT_TERMINAL_CALL_OUTPUT_SCHEMA: AgentSchema;
 /** The declaration with every default applied — what readers consume. */
 export interface NormalizedAgentDeclaration {
     answeredBy: AgentAnsweredBy;
     maxSteps: number;
     waitLimitSeconds: number;
+    maxRowBytes: number;
     turnContext: {
         schema: AgentSchema;
         function?: string;
@@ -2638,6 +2873,18 @@ export type AgentDeclarationResolution = {
  * the block the author wrote.
  */
 export declare const AGENT_BLOCK_LABEL = "[prompt.agent]";
+/**
+ * One place a declaration names a server function: the key, the tool's name
+ * for a tool, the path that makes the reference, and whether the reference
+ * needs the function's schemas (a tool's are its function's; a turn-context or
+ * history hook only needs the function to exist).
+ */
+export interface AgentFunctionReference {
+    key: string;
+    tool?: string;
+    path: string;
+    needsSchemas: boolean;
+}
 /**
  * The function keys a declaration references (tools, turn context, history),
  * each once, in declaration order. What a caller resolves into the
@@ -2655,6 +2902,39 @@ export declare const AGENT_BLOCK_LABEL = "[prompt.agent]";
  */
 export declare function parseAgentDeclarationBlock(agent: unknown): Record<string, unknown> | undefined;
 export declare function agentDeclarationFunctionKeys(agent: unknown): string[];
+/**
+ * Every function reference of a declaration (tools, turn context, history), in
+ * declaration order, with the path that makes it. `[]` for a block that is
+ * absent or does not parse. A declaration written as one JSON string is read
+ * as the object it encodes.
+ */
+export declare function agentDeclarationFunctionReferences(agent: unknown): AgentFunctionReference[];
+/**
+ * What a reference lacks: the function itself, or one of a tool's two schemas.
+ * One deficit per (reference, kind), so a comparison of two states can tell a
+ * schema restored from a schema removed without reading message text.
+ */
+export type AgentFunctionDeficitKind = "absent" | "inputSchemaMissing" | "outputSchemaMissing";
+/** One thing a function reference of a declaration lacks. */
+export interface AgentFunctionDeficit {
+    path: string;
+    tool?: string;
+    key: string;
+    kind: AgentFunctionDeficitKind;
+}
+/**
+ * Every deficit of a declaration's function references against `functions`:
+ * an absent function (`null`, or missing from the map), and for a tool a
+ * missing `inputSchema` and a missing `outputSchema`, each on its own. `[]` for
+ * a block that is absent or does not parse.
+ */
+export declare function agentFunctionDeficits(agent: unknown, functions: AgentFunctionFacts): AgentFunctionDeficit[];
+/**
+ * The refusals for a list of deficits: one `AGENT_TOOL_FUNCTION_MISSING` per
+ * absent reference, and one `AGENT_TOOL_FUNCTION_SCHEMA_MISSING` per tool
+ * reference naming every schema it lacks.
+ */
+export declare function agentFunctionDeficitRefusals(deficits: readonly AgentFunctionDeficit[]): AgentRefusal[];
 /**
  * The one rule: is this `[prompt.agent]` declaration (with the prompt's kind
  * and `outputSchema`) something the platform can run?
@@ -2678,16 +2958,37 @@ export declare function agentNotRunnableRefusal(promptKey?: string): AgentRefusa
  */
 export declare function agentRoundNotAgentRefusal(promptKey: string): AgentRefusal;
 /**
- * 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 declare function agentTestCaseRefusal(promptKey: string, _role?: "evaluator"): AgentRefusal;
+/** An earlier call of the turn, as a presentation's references are checked against it. */
+export interface AgentReferencedCall {
+    /** The number the platform gave the call in its turn (1 for the turn's first). */
+    callNumber: number;
+    toolName: string;
+    /** The call's row state; only `output-available` may be referenced. */
+    state: string;
+}
+/**
+ * The refusal of a presentation call whose `references` name a number that
+ * is not an earlier call of the turn with a result — a refused call, a number
+ * the turn never gave, or a call of the same response — or `null`. `earlier`
+ * is the turn's calls committed before this call's response. The message
+ * lists the offending values by property and the numbers that may be
+ * referenced, with their tools, so the model can correct itself next round.
  */
-export declare function agentTestCaseRefusal(promptKey: string, role: "subject" | "evaluator"): AgentRefusal;
+export declare function presentationReferenceRefusal(tool: {
+    name: string;
+    references?: readonly string[];
+}, args: unknown, earlier: readonly AgentReferencedCall[]): AgentRefusal | null;
 /**
  * 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`
+ * — `endsTurn = true` for a presentation, whose call always ends the turn.
  *
  * The ONLY accessor for defaults — the stored value never carries them
  * (DSO-3798-001). Takes a value `resolveAgentDeclaration` accepted (or `null`)
@@ -2723,7 +3024,7 @@ export declare function normalizeAgentDeclaration(declaration: AgentDeclaration
  * the structured error the model sees, and a model following `properties` is
  * never told it may add keys. Refusing it instead would put the platform's own
  * closed-object marker — `additionalProperties: false` is how
- * `src/workflows/schema-descriptor.ts` spells a closed object — outside
+ * `src/function-runs/schema-descriptor.ts` spells a closed object — outside
  * Gemini's reach.
  *
  * The TRANSLATED schema is what the provider is sent; the ORIGINAL is what the
@@ -2815,10 +3116,214 @@ export interface AgentSchemaTranslationInput {
  * A declaration with no tools and no events reads no function schema at all.
  */
 export declare function agentSchemaTranslationRefusals(input: AgentSchemaTranslationInput): AgentRefusal[];
+/**
+ * One schema an agent's model reads that a provider of a non-archived config
+ * cannot carry — or, for a server tool, a function schema that does not parse.
+ * The structured half of `agentSchemaTranslationRefusals`: its identity is
+ * (`subject`, `which`, `provider`, `schemaPath`, `keyword`), or (`subject`,
+ * `which`, `unparsable`), so two states can be compared without reading
+ * message text.
+ */
+export type AgentSchemaDeficit = {
+    /** `tool "propose"`, `tool "lookup" (function "ledger")` or `event "applied"`. */
+    subject: string;
+    /** `inputSchema`, `outputSchema` or `schema`. */
+    which: string;
+    provider: string;
+    /** The non-archived configs on `provider`. */
+    configNames: string[];
+    /** The dotted path from the schema root; `""` is the root. */
+    schemaPath: string;
+    keyword: string;
+    reason: string;
+} | {
+    subject: string;
+    which: string;
+    /** The function whose stored schema does not parse. */
+    unparsable: string;
+};
+/**
+ * Every deficit `agentSchemaTranslationRefusals` reports, in the same order,
+ * before it is rendered. One per (schema, path, keyword, provider), and one
+ * per server-tool schema that does not parse.
+ */
+export declare function agentSchemaTranslationDeficits(input: AgentSchemaTranslationInput): AgentSchemaDeficit[];
+/** The `AGENT_SCHEMA_NOT_TRANSLATABLE` refusal one deficit renders as. */
+export declare function agentSchemaDeficitRefusal(deficit: AgentSchemaDeficit): AgentRefusal;
+/**
+ * A change to a server function that an agent uses — issue #4441.
+ *
+ * An agent names server functions as its tools, its turn-context hook and its
+ * history hook. The agent's own writes are checked against those functions
+ * (`resolveAgentDeclaration`, `agentSchemaTranslationRefusals`), but a change
+ * to the FUNCTION — archiving it, deleting it, changing its schemas — used to
+ * be accepted and fail at the agent's next turn. This module is the rule for
+ * that change: given one agent's declaration and configs, and the functions it
+ * names before and after the change, which refusals does the change introduce?
+ *
+ * The admin function routes refuse such a change with `FUNCTION_USED_BY_AGENT`,
+ * and `config push`'s preflight runs the same rule through the vendored
+ * artifact, so the two cannot disagree.
+ *
+ * ONLY WHAT THE CHANGE INTRODUCES. Both states are reduced to structured
+ * deficits (`agentFunctionDeficits`, `agentSchemaTranslationDeficits`) and the
+ * ones already present before the change are dropped. An agent that is broken
+ * for another reason does not block an unrelated change, and a partial repair
+ * — restoring one of two missing schemas, removing one of two `$ref`s — is
+ * accepted. Messages are rendered only afterwards, by the sibling rules' own
+ * builders, so they read exactly as an agent write's refusals do.
+ *
+ * Pure and dependency-free, like every module under `src/config-surface/`.
+ */
+/** The code a function route answers when an agent cannot take the change. */
+export declare const FUNCTION_USED_BY_AGENT = "FUNCTION_USED_BY_AGENT";
+/** One agent, and the functions it names before and after a change to them. */
+export interface AgentFunctionChangeInput {
+    /** `[prompt.agent]` as stored: a table, or one JSON string encoding one. */
+    declaration: unknown;
+    /** Every config of the agent's prompt. Archived ones are skipped. */
+    configs: ReadonlyArray<AgentSchemaConfigFact>;
+    /** What the app holds for each function the declaration names, now. */
+    before: AgentFunctionFacts;
+    /** The same, as the change would leave it. */
+    after: AgentFunctionFacts;
+}
+/**
+ * Every refusal the change introduces for this agent: a reference whose
+ * function goes away (`AGENT_TOOL_FUNCTION_MISSING`), a tool schema that goes
+ * away (`AGENT_TOOL_FUNCTION_SCHEMA_MISSING`), and a schema a non-archived
+ * config's provider cannot carry where the previous one could
+ * (`AGENT_SCHEMA_NOT_TRANSLATABLE`). `[]` when the agent can take the change,
+ * and for a declaration that does not parse (it names nothing).
+ */
+export declare function agentFunctionChangeRefusals(input: AgentFunctionChangeInput): AgentRefusal[];
+/**
+ * How an agent uses one function: each tool's name (or its path when the tool
+ * has none), and `turnContext.function` / `history.function` for a hook, in
+ * declaration order. `[]` when the declaration does not name the function.
+ */
+export declare function agentFunctionUses(declaration: unknown, functionKey: string): string[];
+/** What a function route was asked to do. */
+export type FunctionChangeKind = "archive" | "delete" | "schema";
+/** One agent a function change would break. */
+export interface FunctionUsedByAgent {
+    promptKey: string;
+    /** `agentFunctionUses` of the changed function. */
+    tools: string[];
+    /** The refusals the change introduces for this agent. */
+    refusals: ReadonlyArray<AgentRefusal>;
+}
+/**
+ * The sentence a function route refuses with: the function, then one sentence
+ * per agent naming its key and each use, then the remedy. A schema change also
+ * carries each agent's refusals, since the remedy depends on which schema broke.
+ */
+export declare function functionUsedByAgentMessage(functionKey: string, change: FunctionChangeKind, agents: ReadonlyArray<FunctionUsedByAgent>): string;
+/**
+ * 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 declare const AGENT_TEST_CASE_FIELDS: readonly ["agentHistory", "agentContext", "agentTimezone", "agentLocale", "agentExpectedToolCall", "agentExpectedNoToolCall"];
+export type AgentTestCaseField = (typeof AGENT_TEST_CASE_FIELDS)[number];
+/** One call of a seeded assistant entry. */
+export interface AgentTestCall {
+    callId: string;
+    name: string;
+    arguments: unknown;
+}
+/** One entry of a seeded history, oldest first. */
+export type AgentTestHistoryEntry = {
+    role: "user";
+    text: string;
+} | {
+    role: "assistant";
+    text?: string;
+    reasoning?: string;
+    calls?: AgentTestCall[];
+} | {
+    role: "tool";
+    callId: string;
+    output: unknown;
+} | {
+    role: "tool";
+    callId: string;
+    error: {
+        code: string;
+        message: string;
+    };
+} | {
+    role: "event";
+    kind: string;
+    refersTo?: string;
+    data: unknown;
+};
+/** The `[test.agent]` block, read. */
+export interface AgentTestCase {
+    history: AgentTestHistoryEntry[];
+    context: Record<string, unknown> | null;
+    timezone: string | null;
+    locale: string | null;
+    expectedToolCall: {
+        name: string;
+        arguments?: unknown;
+    } | null;
+    /** `false` when unset: no assertion. */
+    expectedNoToolCall: boolean;
+}
+export interface AgentTestCaseInput {
+    /**
+     * The prompt's kind; unset means `chat`. The admin routes pass a block type
+     * (`workflow`, `script`, `integration`) for a case that is not a prompt's.
+     */
+    kind?: unknown;
+    /**
+     * The agent's `[prompt.agent]` (a table, one JSON string, or `null` for an
+     * agent that declares none). Omitted means "not known here": the declared
+     * names are not checked (the CLI preflight reads the sidecar alone).
+     */
+    declaration?: unknown;
+    /** The case's fields, in wire spelling (`agentHistory`, …, `expectedJsonSubset`). */
+    fields: Record<string, unknown>;
+}
+export type AgentTestCaseResolution = {
+    ok: true;
+    testCase: AgentTestCase | null;
+} | {
+    ok: false;
+    refusals: AgentRefusal[];
+};
+/**
+ * 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 declare function resolveAgentTestCase(input: AgentTestCaseInput): AgentTestCaseResolution;
 export declare const PROMPT_SURFACE: ConfigObjectSurface;
 export declare const INTEGRATION_SURFACE: ConfigObjectSurface;
-export declare const WEBHOOK_SURFACE: ConfigObjectSurface;
-export declare const CRON_TRIGGER_SURFACE: ConfigObjectSurface;
 export declare const BLOB_BUCKET_SURFACE: ConfigObjectSurface;
 /**
  * The `email-template` configuration object's definition (issue #2644, phase 2).
@@ -2860,28 +3365,23 @@ export declare function isRetiredEmailType(emailType: string): emailType is Reti
 export declare function retiredEmailTypeGuidance(emailType: string): string;
 export declare const EMAIL_TEMPLATE_SURFACE: ConfigObjectSurface;
 export declare const DATABASE_TYPE_SURFACE: ConfigObjectSurface;
+export declare const DB3_TYPE_SURFACE: ConfigObjectSurface;
 export declare const RULE_SET_SURFACE: ConfigObjectSurface;
-export declare const GROUP_TYPE_CONFIG_SURFACE: ConfigObjectSurface;
-export declare const COLLECTION_TYPE_CONFIG_SURFACE: ConfigObjectSurface;
 export declare const METADATA_CATEGORY_CONFIG_SURFACE: ConfigObjectSurface;
+export declare const SERVER_FUNCTION_SURFACE: ConfigObjectSurface;
 /**
- * The `transform` configuration object's definition (issue #2644, phase 3).
- *
- * Transforms are the one synced type with NO TOML field table: a transform is
- * `transforms/<name>.rhai`, a Rhai source file, and its whole authored surface
- * is the script body. `config pull` writes the active `ScriptConfig`'s body and
- * `config push` sends it back; there is no key/value table to define, and the
- * `Script` / `ScriptConfig` scalars around it (name, description, inputSchema,
- * limits, status) are not authorable through the sync slot today.
- *
- * The entry exists so that is a DECISION rather than an absence. Criterion 3's
- * registry guard reads `SYNC_RESOURCE_TYPES` and requires a surface per label;
- * without this module `transform` would have to sit in an exemption list, which
- * is precisely the "absent from a hand-written list" failure mode this epic
- * exists to end.
+ * The refusal of a new version whose default export has no `authorize`: it
+ * names the function and shows the object form with the function's key. A
+ * `file` prefixes the sentence the way the CLI reports a file it refuses.
  */
-export declare const TRANSFORM_SURFACE: ConfigObjectSurface;
-export declare const SERVER_FUNCTION_SURFACE: ConfigObjectSurface;
+export declare function authorizeRequiredMessage(functionKey: string, file?: string): string;
+/**
+ * The refusal of a new version that defines `authorize` while its TOML still
+ * carries `access`.
+ */
+export declare function accessAmbiguousMessage(functionKey: string): string;
+/** The refusal of a create or update body that carries `access`. */
+export declare const FUNCTION_ACCESS_FROZEN_REQUEST: string;
 export declare const TEST_CASE_SURFACE: ConfigObjectSurface;
 export declare const APP_SETTINGS_SURFACE: ConfigObjectSurface;
 /**