primitive-admin 1.0.62 → 1.0.64

package/dist/src/commands/sync.js

@@ -3,13 +3,17 @@ import { join, basename } from "path";
 import { createHash } from "crypto";
 import { lookup as mimeLookup } from "mime-types";
 import { ApiClient, ApiError, ConflictError, SchemaRequiredError, OperationRefError, SchemaBreaksOpsError, SchemaHasUncheckableOpsError, TomlParseError, OpsExistError, } from "../lib/api-client.js";
+import { retryOnStoragePending } from "../lib/storage-pending-retry.js";
 import { buildDatabaseTypeTomlData, detectExistingOperationForms, normalizeOperationFromToml, normalizeSubscriptionFromToml, SubscriptionAccessKeyConflictError, } from "../lib/toml-database-config.js";
 import { canEmitNative } from "../lib/toml-native-form.js";
+// #1446's `type: "json"` emission rule, shared with `serializeFunction` since
+// #3317 — see `config-json-field.ts`.
+import { serializeJsonField } from "../lib/config-json-field.js";
 import { parseMetadataCategoryToml, validateMetadataCategoryConfig, serializeMetadataCategoryConfig, parseDeclaredAccessManifestToml, validateDeclaredAccessManifest, serializeDeclaredAccessManifest, } from "../lib/toml-metadata-config.js";
 import { validateOperations, formatIssue, } from "../lib/toml-params-validator.js";
 import { isPlatformOwnedWorkflow, isPlatformOwnedWorkflowKey, } from "../lib/platform-owned.js";
-import { getServerUrl, resolveAppId } from "../lib/config.js";
-import { resolveSyncDir, resolveSnapshotsRoot, isAutoResolvedSyncDir, checkLegacySyncMigration, checkLegacyDatabaseTypesDir, } from "../lib/sync-paths.js";
+import { getCurrentAppId, getServerUrl } from "../lib/config.js";
+import { resolveSyncDir, resolveSnapshotsRoot, syncStatePath, syncStateReadPath, SYNC_STATE_FILENAME, checkLegacyDatabaseTypesDir, } from "../lib/sync-paths.js";
 import { createSnapshot, listSnapshots, resolveSnapshot, restoreSnapshot, pruneSnapshots, } from "../lib/snapshots.js";
 import { validateWorkflowToml, collectWorkflowTomlNotes, formatWorkflowTomlErrors, validateWorkflowExpressionsToml, validateWorkflowExpressionsRawToml, } from "../lib/workflow-toml-validator.js";
 import { expandWorkflowTomlData } from "../lib/workflow-fragments.js";
@@ -29,14 +33,50 @@ import { buildWorkflowPayloadFromToml, parseWorkflowExpressionsToml, } from "../
 // payload builder so the diff normalizer and the wire cannot disagree.
 import { WORKFLOW_MODEL_DEFAULTS } from "../lib/workflow-defaults.js";
 // #2644 — the one definition per configuration object, vendored from the server.
-import { BLOB_BUCKET_TABLE, COLLECTION_TYPE_CONFIG_TABLE, CRON_TRIGGER_TABLE, DATABASE_TYPE_TABLE, EMAIL_TEMPLATE_TABLE, GROUP_TYPE_CONFIG_TABLE, INTEGRATION_TABLE, METADATA_CATEGORY_CONFIG_TABLE, PROMPT_CONFIG_TABLE, PROMPT_TABLE, RULE_SET_TABLE, TEST_CASE_SURFACE, TEST_CASE_TABLE, WEBHOOK_TABLE, WORKFLOW_TABLE, configDeclaredTypeErrors, findMisshapenTables, findUnknownDocumentKeys, findUnknownServerKeys, findUnknownTomlKeys, misshapenTableMessage, retiredConfigKey, spellsDecimalNumber, unrecognizedPullKeysMessage, unrecognizedPushKeysMessage, unrecognizedPushTablesMessage, warnUnrecognizedServerKeys, } from "../lib/config-surface.js";
+import { BLOB_BUCKET_TABLE, COLLECTION_TYPE_CONFIG_TABLE, CRON_TRIGGER_TABLE, DATABASE_TYPE_TABLE, EMAIL_TEMPLATE_TABLE, GROUP_TYPE_CONFIG_TABLE, INTEGRATION_TABLE, METADATA_CATEGORY_CONFIG_TABLE, PROMPT_CONFIG_TABLE, PROMPT_TABLE, RULE_SET_TABLE, SERVER_FUNCTION_TABLE, TEST_CASE_SURFACE, TEST_CASE_TABLE, WEBHOOK_TABLE, WORKFLOW_TABLE, configDeclaredTypeErrors, fieldServerDefault, findMisshapenTables, findUnknownDocumentKeys, findUnknownGroupedTomlKeys, findUnknownServerKeys, findUnknownTomlKeys, misshapenTableMessage, retiredConfigKey, spellsDecimalNumber, unrecognizedPullKeysMessage, unrecognizedPushKeysMessage, unrecognizedPushTablesMessage, warnUnrecognizedServerKeys, } from "../lib/config-surface.js";
 import { buildPayloadFromToml, projectEntityToPayload, projectRecordToToml, tomlOwned, } from "../lib/config-payload.js";
-import { CONFIG_SURFACES, isEmptyForEmit, } from "../lib/generated-config-surfaces.js";
+import { CONFIG_SURFACES, isEmptyForEmit, tomlGroupsOf, } from "../lib/generated-config-surfaces.js";
+// #3626 — the prompt KIND rule, vendored with the definitions so the CLI's
+// preflight refuses exactly what the admin routes refuse.
+import { hoistDeprecatedChatKeys, promptKindOf, resolvePromptKind, } from "../lib/generated-config-surfaces.js";
+// #3798 — the `[prompt.agent]` declaration rule, vendored the same way.
+import { agentDeclarationFunctionKeys, agentTestCaseRefusal, resolveAgentDeclaration, } from "../lib/generated-config-surfaces.js";
+// #3799 — the meaning-preserving schema translation, vendored the same way, so
+// the preflight refuses exactly the schemas the admin routes refuse.
+import { agentSchemaTranslationRefusals } from "../lib/generated-config-surfaces.js";
+// #3801 — the strict-output rule, vendored the same way, so the preflight
+// refuses exactly the strict configs the admin routes refuse.
+import { resolvePromptStrictOutput } from "../lib/generated-config-surfaces.js";
+// #3179 — the function's two halves: the header payloads and the envelope
+// `config push` sends, and the bytes `config pull` writes back.
+import { applyFunctionPull, buildFunctionConfigPush, createDocumentSchemaDropWarner, documentSchemaRetentionFailure, buildFunctionCreatePayload, buildFunctionUpdatePayload, functionDiffEntity, functionTomlIgnoredKeyWarnings, functionTomlPreflightErrors, planDocumentSchemaPull, planFunctionPull, serializeFunction, } from "../lib/function-sync.js";
+import { newerVersionLine, pullNewerVersionLine, rollbackDiffHint, } from "../lib/function-versions.js";
+import { FunctionBuildError } from "../lib/function-bundle.js";
+// #3182 — the local half of capability validation. The grammar is the vendored
+// module the server also imports; this is where an author's own file is read.
+import { configObjectKeysFromTree, functionGrantErrors, mergeKnownGrantTargets, } from "../lib/function-grants-preflight.js";
+// #3182 — the typed handle's generated declarations and the compiler wiring
+// that makes an editor load them.
+import { functionTypeWiringProblems, staleFunctionTypeArtifacts, writeFunctionTypeArtifacts, } from "../lib/function-db-types.js";
+// #3281 — the functions declaration and the per-key invokers ride the same
+// plan; a malformed schema is their one refusal, named by file.
+import { FunctionSchemaCodegenError } from "../lib/function-schema-codegen.js";
+// #3455 — the one resolution rule push, pull and diff share for the project's
+// document schema.
+import { isFunctionDeclarationFile, resolveDocumentSchema, } from "../lib/function-document-types.js";
+// #3331 — and the compiler is actually asked: a push holds the code it ships
+// to the declarations it just generated.
+import { createFunctionTypechecker, } from "../lib/function-typecheck.js";
 import { detectLayout, migrateLegacyToV2 } from "../lib/block-layout.js";
 import { ABSENT_FROM_EXPORT, LOCAL_ONLY_ABSENT, LOCAL_ONLY_NEW, PUSH_PRUNE_SPECS, REMOTE_ONLY_UNMANAGED, REMOTE_ONLY_WILL_DELETE, SYNC_RESOURCE_TYPES, VALIDATION_ERROR, applyPrune, attachmentWritePath, attemptFetch, classifyLocalOnly, classifyPruneDeleteFailure, classifyRemoteOnly, collectPushPruneCandidates, decidePushPruneCandidate, formatPrunePlan, hasUncommittedChanges, isSafeAttachmentFilename, isSafeSyncFilename, planPrune, preserveUnwrittenEntries, removePrunedSidecar, ruleSetFileKey, } from "../lib/sync-resource-types.js";
 import { normalizeTestCaseKey, testCaseKeyError, } from "../lib/test-case-keys.js";
+import { slugifyTestCaseName, testCaseFileBasenames, } from "../lib/test-case-file-names.js";
+// The sidecar naming rules moved to `lib/` so `scripts tests` can read them
+// without loading the sync tree (#3061); re-exported here because pull, push,
+// diff and their tests have always imported them from this module.
+export { resolveSlugCollisions, slugifyTestCaseName, testCaseFileBasenames, } from "../lib/test-case-file-names.js";
 import { success, error, printApiError, info, warn, keyValue, json, divider, } from "../lib/output.js";
-import { filterFilesBySelection, parseSyncSelectors, SelectorError, selectionIncludesKey, selectionIncludesType, selectionIncludesApp, selectionIncludesAnyVar, unmatchedSelectors, } from "../lib/sync-selectors.js";
+import { filterFilesBySelection, parseSyncSelectors, SelectorError, selectionIncludesKey, selectionIncludesType, selectionIncludesApp, selectionIncludesAnyVar, trackedSelectorKeys, unmatchedSelectors, } from "../lib/sync-selectors.js";
 import { confirmPrompt, ConfirmPromptError } from "../lib/confirm-prompt.js";
 import { signingSecretStatusWarning, signingSecretHealthWarning, previousSigningSecretWarning, } from "../lib/signing-secret-status.js";
 import chalk from "chalk";
@@ -59,7 +99,7 @@ function printStaleInstanceWarning(updated) {
     }
 }
 function loadSyncState(configDir) {
-    const syncFile = join(configDir, ".primitive-sync.json");
+    const syncFile = syncStateReadPath(configDir);
     if (!existsSync(syncFile)) {
         return null;
     }
@@ -71,7 +111,7 @@ function loadSyncState(configDir) {
     }
 }
 function saveSyncState(configDir, state) {
-    const syncFile = join(configDir, ".primitive-sync.json");
+    const syncFile = syncStatePath(configDir);
     writeFileSync(syncFile, JSON.stringify(state, null, 2));
 }
 /**
@@ -685,6 +725,20 @@ export function validateVarsFile(parsedVars, options = {}) {
  * edit — reported as a conflict instead. `force` skips the conflict guard,
  * matching `config push --force` for every other entity.
  *
+ * A var only the SERVER moved is the other half of the same comparison, and it
+ * is reported rather than skipped (issue #3714). Its local value still equals
+ * the baseline, so there is nothing to push and no conflict — but the skip that
+ * follows from "local is unchanged" used to be taken before the snapshot was
+ * consulted at all, so the push said nothing about a var edited in the Admin
+ * Console and counted it among the skipped-unchanged. The `drifted[]` keys are
+ * what every other synced type reaches through `classifyPushChange` →
+ * `server-drifted`: the caller prints `DRIFT var: <key>` under "Server drift —
+ * not pushed", writes nothing, and leaves the exit code alone. A baseline key
+ * the snapshot no longer holds at all is the same one-sided move (the server
+ * deleted the row; the local file stands still) and is reported the same way.
+ * `--force` is the resolution that keeps the local value, `config pull` the one
+ * that takes the server's.
+ *
  * Pure and side-effect-free (the caller owns the API calls and sync-state
  * updates) so the guard is unit-testable without a live server. Assumes
  * `parsedVars` has already passed `validateVarsFile` (values are strings). The
@@ -698,6 +752,7 @@ export function planVarsPush(parsedVars, baseline, remoteVars, options = {}) {
     const remoteByKey = new Map(remoteVars.map((r) => [r.key, r]));
     const upserts = [];
     const conflicts = [];
+    const drifted = [];
     const deletions = [];
     let skippedCount = 0;
     const localKeys = new Set();
@@ -705,9 +760,32 @@ export function planVarsPush(parsedVars, baseline, remoteVars, options = {}) {
         localKeys.add(key);
         const valueHash = hashVarValue(value);
         const existing = baseline?.[key];
-        // Unchanged since last sync — skip (unless forced), mirroring the
-        // content-hash skip the other file-backed entities use.
+        // Unchanged since last sync — nothing to push (unless forced), mirroring
+        // the content-hash skip the other file-backed entities use. But "the local
+        // file did not move" is only half the comparison: ask the snapshot whether
+        // the SERVER moved before calling the pair unchanged (issue #3714). One
+        // side having moved is drift, which is reported and not written; only a
+        // pair that still agrees is a skipped-unchanged file.
         if (!options.force && existing && existing.contentHash === valueHash) {
+            const remote = remoteByKey.get(key);
+            if (!remote) {
+                // The row is gone from an authoritative snapshot (the caller fails the
+                // push closed when the fetch fails, and the `--force` fallback that
+                // leaves it empty never reaches here): the server deleted what we last
+                // synced while the file stood still. `--force` recreates it from the
+                // local value; `config pull` drops the line.
+                drifted.push({ key, serverModifiedAt: "deleted" });
+                continue;
+            }
+            if (typeof remote.value === "string" &&
+                hashVarValue(remote.value) !== existing.contentHash) {
+                drifted.push({ key, serverModifiedAt: remote.updatedAt || "unknown" });
+                continue;
+            }
+            // Either both sides still hold the last-synced value, or the snapshot
+            // carries no readable value for the key and nothing establishes a move.
+            // Nothing is written on this path either way, so the only question is
+            // what to report, and an unprovable drift is not one to claim.
             skippedCount++;
             continue;
         }
@@ -795,7 +873,7 @@ export function planVarsPush(parsedVars, baseline, remoteVars, options = {}) {
         }
         deletions.push(key);
     }
-    return { upserts, deletions, conflicts, skippedCount };
+    return { upserts, deletions, conflicts, drifted, skippedCount };
 }
 /**
  * Compute the number of config vars the server would hold after a push plan
@@ -1589,6 +1667,30 @@ export function buildBlobBucketUpdatePayload(bucket) {
     }
     return updatePayload;
 }
+/**
+ * The `[[configs]] status` the server assigns when a file names none (#3201).
+ *
+ * Taken from the definition, not spelled again here: pull omits the key at
+ * this value and push sends this value for the omitted key, and those two
+ * statements have to be the same one or a pulled file would not describe the
+ * state it was pulled from.
+ */
+const PROMPT_CONFIG_DEFAULT_STATUS = fieldServerDefault(PROMPT_CONFIG_TABLE, "status");
+/**
+ * #3201's post-create status patch is RETIRED — #3799 (DSO-3799-005).
+ *
+ * `status` was update-only, so `POST /prompts` and `POST /prompts/:id/configs`
+ * both assigned `active` whatever the body said, and an authored
+ * `status = "archived"` needed a follow-up PATCH ordered after the activation of
+ * the entry the file marks live. Both create paths honor the key now
+ * (`writableOn: BOTH`, validated by one rule on all three paths), so the entry
+ * lands retired on its own create: the same end state, two fewer calls per
+ * retired config, and no window in which the server holds a status the file
+ * never asked for. That window is what made a pulled tree unpushable into a
+ * fresh environment once an agent's schemas are checked against each
+ * non-archived config's provider — the check fired on the transient active
+ * state.
+ */
 /**
  * Which `[[configs]]` entry a prompt file marks as live (issue #2645).
  *
@@ -1696,17 +1798,43 @@ export function serializePrompt(prompt, logger) {
             ...projectRecordToToml(PROMPT_TABLE, prompt, {
                 inputSchema: jsonField(promptSubject),
                 outputSchema: jsonField(promptSubject),
+                // #3798 — the agent declaration goes out as `[prompt.agent]` tables
+                // (JSON-string fallback for a `null` TOML cannot spell), exactly as
+                // stored: the server keeps it as authored, so what pull writes is
+                // what the author pushed.
+                agent: jsonField(promptSubject),
             }),
         },
         configs: (prompt.configs || []).map((config) => ({
             ...projectRecordToToml(PROMPT_CONFIG_TABLE, config, {
+                // #3201 — the per-version key, written only when the config is
+                // RETIRED. `active` is what the create handler assigns and what an
+                // absent key means (the definition's `serverDefault`), so emitting it
+                // put a `status = "active"` line in every pulled prompt file: the one
+                // spelling the availability contract says a config file never carries
+                // (#2803), on the line `config create` scaffolds the `active = true`
+                // marker onto. A retired config still says so — that is what #2645 put
+                // the key in the file for.
+                status: (record) => record?.status === PROMPT_CONFIG_DEFAULT_STATUS
+                    ? undefined
+                    : record?.status,
                 // Stored as a string on the model and returned parsed; coerce
                 // defensively so an older server's string still writes as a number.
                 temperature: (record) => record.temperature != null ? Number(record.temperature) : undefined,
                 topP: (record) => (record.topP != null ? Number(record.topP) : undefined),
                 outputSchema: jsonField(`Prompt '${prompt?.promptKey}' config '${config?.configName}'`),
                 providerConfig: jsonField(`Prompt '${prompt?.promptKey}' config '${config?.configName}'`),
-            }),
+                // #3626, CR3626-002 — the decisions declaration is a `json` field and
+                // goes out the same way its siblings do. Written straight through, a
+                // stored question carrying a `null` anywhere lost that member on pull
+                // (smol-toml has no null), and a `null` inside a LIST threw, taking
+                // `config pull` and `config diff` down with it. The JSON-string
+                // fallback keeps the declaration whole either way.
+                questions: jsonField(`Prompt '${prompt?.promptKey}' config '${config?.configName}'`),
+            }, 
+            // #3798 — the model settings chat and agent share are written under the
+            // block the prompt's kind names: `[configs.agent]` for an agent.
+            { tomlGroup: promptKindOf(prompt) }),
             // #2645 — the live config has to be identifiable in the repo. Emitted
             // only on the active entry (`undefined` elsewhere so the key is omitted),
             // which keeps the marker unambiguous by construction.
@@ -1778,11 +1906,43 @@ export function buildPromptPushPayload(key, tomlData, { mode = "update" } = {})
                 // dropped and leaving a stale rule live. On create it is omitted so
                 // the push-adopt path (#1006) can still reach the server's 409.
                 accessRule: (value) => (create ? value : (value ?? null)),
+                // #3798 — the agent declaration, as authored: the server stores it
+                // unchanged, so the value sent is the value pull writes back. On
+                // update a deleted block CLEARS it — for an agent only: a chat or
+                // decisions file carries no block to delete, and omitting the key
+                // keeps its body what it was before this field existed.
+                agent: (value) => create || value !== undefined
+                    ? value
+                    : promptKindOf(prompt) === "agent"
+                        ? null
+                        : undefined,
+                // #3626, CR3626-004 — the kind NORMALIZED, exactly as the resolver
+                // that validates it reads it. `kind = " chat "` and `kind = ""` both
+                // mean `chat` to `resolvePromptKind`, so the server stores `chat` and
+                // the comparison — which projects `[prompt]` in create mode precisely
+                // so a changed kind is visible (SO3626-008) — would otherwise read the
+                // authored spelling against the stored one and call a freshly created
+                // prompt an attempted kind change, refused as immutable on every later
+                // push including `--force`. An UNKNOWN kind is passed through as
+                // written: it is a refusal (preflight, then the create handler), and it
+                // has to name what the file says.
+                kind: (value) => {
+                    if (value === undefined || value === null)
+                        return "chat";
+                    if (typeof value !== "string")
+                        return value;
+                    const text = value.trim();
+                    return text === "" ? "chat" : text;
+                },
             },
         }),
     };
     if (create)
         payload.promptKey = key;
+    // #3798 — a prompt that declares no agent block sends no `agent` key at all,
+    // so a chat or decisions body is byte for byte what it was.
+    if (payload.agent === undefined)
+        delete payload.agent;
     return payload;
 }
 /**
@@ -1812,11 +1972,25 @@ export function buildPromptCreatePayload(key, tomlData) {
     for (const owned of ["configName", ...SEEDED_CONFIG_DEFERRED]) {
         delete seed[owned];
     }
+    const prompt = buildPromptPushPayload(key, tomlData, { mode: "create" });
+    // #3626, SO3626-001 — the placeholder is a CHAT fallback. A decisions prompt
+    // has no template at all (its input is a `state` value plus its questions),
+    // and injecting one would store a chat key the block rule then refuses on
+    // every later update. #3798 — nor has an agent: the model sees each message
+    // as sent.
+    if (promptKindOf(prompt) !== "chat") {
+        const body = { ...prompt, ...seed };
+        for (const field of Object.keys(body)) {
+            if (body[field] === undefined)
+                delete body[field];
+        }
+        return body;
+    }
     return {
-        ...buildPromptPushPayload(key, tomlData, { mode: "create" }),
+        ...prompt,
         ...seed,
-        // The server requires a template; keep the historical placeholder so a
-        // prompt authored without one still creates.
+        // The server requires a template for a chat config; keep the historical
+        // placeholder so a prompt authored without one still creates.
         userPromptTemplate: seed.userPromptTemplate || "{{ input }}",
     };
 }
@@ -1847,15 +2021,26 @@ const SEEDED_CONFIG_DEFERRED = ["outputSchema", "description"];
  * `seededConfigName` is what the server called it — read from the create
  * response rather than assumed, so a handler that one day honors the name
  * produces no needless PATCH.
+ *
+ * #3201 — the entry's `status` was deferred the OTHER way, to a patch after the
+ * activation, because the create pointed the prompt's `activeConfigId` at a
+ * config it had forced live. #3799 (DSO-3799-005) — the create carries the
+ * entry's `status` itself now, so there is no deferral either way and this patch
+ * is the two fields `POST /prompts` cannot express, nothing more.
  */
 export function seededOnlyPromptConfigFields(firstConfig, seededConfigName = "default") {
     const full = buildPromptConfigPayload(firstConfig || {}, { mode: "update" });
     const patch = {};
     for (const field of SEEDED_CONFIG_DEFERRED) {
         const value = full[field];
-        // A value the entry does not carry is left alone: the seeded config has
-        // none either, so there is nothing to clear.
-        if (value === undefined || value === null)
+        // #3626 — an omitted value CLEARS. The create handler does not merely skip
+        // `description`, it writes the hard-coded "Default configuration", so
+        // leaving it alone left every newly-pushed prompt reporting `Modified`
+        // forever against a description its file never asked for: push's own
+        // "the file is the whole truth" rule (#1567), broken by the one field the
+        // create body cannot carry. `outputSchema` is unaffected — create never
+        // sets the seeded config's, so the null is a no-op there.
+        if (value === undefined)
             continue;
         patch[field] = value;
     }
@@ -1874,62 +2059,62 @@ export function seededOnlyPromptConfigFields(firstConfig, seededConfigName = "de
  */
 export function buildPromptConfigPayload(tomlConfig, { mode = "update" } = {}) {
     const create = mode === "create";
-    return buildPayloadFromToml(PROMPT_CONFIG_TABLE, tomlConfig, {
+    /**
+     * Issue #1567, generalized at #3358 (DSO-3358-005): the field is TOML-OWNED
+     * on update — send `?? null` so removing the line from a `[[configs]]` block
+     * CLEARS it on the server (the PATCH nulls it on an explicit `null` and
+     * preserves it on omit). Without this an absent key is `undefined`, which
+     * `JSON.stringify` drops, so a deleted line left the stored value live and
+     * the file stopped describing what runs.
+     *
+     * `create` still omits: a create body that nulled every unset key would
+     * differ from the one the server has always received.
+     */
+    const tomlOwned = (value) => (create ? value : (value ?? null));
+    // #3626 §4 — the nine chat keys moved under `[configs.chat]`, and the flat
+    // spelling is accepted as DEPRECATED. Hoisting here rather than at each call
+    // site means push, `config diff` and the create-seed builder all read a file
+    // the same way, so an unmigrated file and its pulled rewrite compare Synced.
+    // A key set BOTH ways is refused in preflight
+    // (`promptDeprecatedChatKeyErrors`); the hoist leaves the grouped value
+    // standing so nothing here has to guess.
+    const entry = hoistDeprecatedChatKeys(tomlConfig).entry;
+    return buildPayloadFromToml(PROMPT_CONFIG_TABLE, entry, {
         mode,
         values: {
             provider: (value) => (create ? value || "openrouter" : value),
+            // #3799 (DSO-3799-005) — carried on CREATE when the entry names one, and
+            // omitted otherwise, so the create body for a file that says nothing
+            // about status is what the server has always received (principle 5). On
+            // update it still sends the declared default for an absent key, which is
+            // what lets a deleted line converge (#2880 DSO-002).
+            status: (value) => create ? value : (value ?? PROMPT_CONFIG_DEFAULT_STATUS),
             model: (value) => create ? value || "google/gemini-2.0-flash-001" : value,
-            // Issue #1567: `description` is TOML-owned on update — send `?? null` so
-            // removing it from a `[[configs]]` block clears it on the server (the
-            // PATCH nulls it on an explicit `null`, preserves on omit).
-            description: (value) => (create ? value : (value ?? null)),
+            description: tomlOwned,
+            systemPrompt: tomlOwned,
+            userPromptTemplate: tomlOwned,
+            temperature: tomlOwned,
+            topP: tomlOwned,
+            maxTokens: tomlOwned,
+            outputFormat: tomlOwned,
+            outputSchema: tomlOwned,
+            providerConfig: tomlOwned,
+            // #3358 — the two reasoning keys are what made the gap load-bearing:
+            // they are mutually exclusive, so switching between them is a deleted
+            // line plus an added one, and a deleted line that does not clear leaves
+            // the merged config refused as "both set".
+            reasoningEffort: tomlOwned,
+            reasoningBudget: tomlOwned,
+            // #3801 — deleting `strictOutput = true` has to turn strict output off
+            // server-side, or the file stops describing the request that is sent.
+            strictOutput: tomlOwned,
+            // #3626, SO3626-002 — the decisions declaration is TOML-owned on the
+            // same terms: deleting `[configs.decisions]` has to clear `questions`
+            // server-side, or the file stops describing what the model is asked.
+            questions: tomlOwned,
         },
     });
 }
-/**
- * Emit a `type: "json"` field (a JSON Schema, a provider-options blob) as TOML.
- *
- * Issue #1446: pull used to `JSON.stringify` schema fields into a single
- * escaped-JSON line — unreadable and undiffable. We now emit the parsed value
- * as a native table whenever it round-trips faithfully
- * (`canEmitNative === null`), falling back to the JSON string only for the
- * values TOML silently drops (`null` / `undefined` anywhere inside). The empty
- * object `{}` is a real, distinct value (for a schema: "accepts anything") and
- * emits as an empty table, so it survives a pull → push cycle instead of being
- * cleared server-side.
- *
- * Returns `undefined` for an absent value (the key is then omitted). The
- * sponsor-approved decision is to always move to native aggressively — no
- * form preservation — so this does not consult the existing file's form.
- *
- * `subject` names the object in the fallback warning, e.g. `Workflow 'greet'`.
- */
-function serializeJsonField(value, fieldName, subject, log) {
-    if (value === undefined || value === null)
-        return undefined;
-    // JSON fields arrive from the server GET parsed; defensively accept a JSON
-    // string too (e.g. an inline-authored file re-serialized here).
-    let obj = value;
-    if (typeof value === "string") {
-        try {
-            obj = JSON.parse(value);
-        }
-        catch {
-            // Not valid JSON — keep the original string as the emitted value.
-            return value;
-        }
-    }
-    if (obj && typeof obj === "object") {
-        const reason = canEmitNative(obj);
-        if (reason) {
-            log(`${subject}: cannot emit \`${fieldName}\` as native TOML (${reason}); using JSON string.`);
-            return JSON.stringify(obj);
-        }
-        return obj;
-    }
-    // A non-object value (unexpected) — preserve it as a JSON string.
-    return JSON.stringify(obj);
-}
 /** The `[workflow]` case of `serializeJsonField` (#1446, message unchanged). */
 function serializeWorkflowSchemaField(value, fieldName, workflowKey, log) {
     return serializeJsonField(value, fieldName, `Workflow '${workflowKey}'`, log);
@@ -2002,11 +2187,19 @@ export function configUnknownKeyError(filePath, tomlData, table) {
             : []
         : [at];
     const unknown = new Set();
+    // #3626 — a key inside a declared `[configs.<group>]` block that no field
+    // declares under it, and a group value that is not a table at all. Reported
+    // with the group in the path (`configs.chat.nope`) so the author is told
+    // where the CLI looked.
+    const groupedUnknown = new Set();
     for (const entry of entries) {
         for (const key of findUnknownTomlKeys(entry, table))
             unknown.add(key);
+        for (const key of findUnknownGroupedTomlKeys(entry, table)) {
+            groupedUnknown.add(key);
+        }
     }
-    if (unknown.size === 0)
+    if (unknown.size === 0 && groupedUnknown.size === 0)
         return null;
     // #2645/#2803 — a key this CLI removed on purpose gets the guidance stated
     // once beside the definitions (`src/config-surface/retired-keys.ts`), not the
@@ -2023,8 +2216,33 @@ export function configUnknownKeyError(filePath, tomlData, table) {
     for (const key of retiredHere) {
         messages.push(`${filePath}: ${prefix}.${key} — ${retiredConfigKey(prefix, key).toml}`);
     }
-    if (trulyUnknown.length > 0) {
-        messages.push(unrecognizedPushKeysMessage(filePath, table.tomlPath, trulyUnknown));
+    // #3626, SO3626-013 — a key the definition DOES declare, written at the
+    // table root when it is authored under a group. Before grouping,
+    // `acceptedTomlKeys` took every field key at the root, so a flat `questions`
+    // passed this check and was then dropped in silence by the payload builder.
+    // It is an unknown key now, and the message says where it belongs rather
+    // than sending the author to the generic "check the spelling" hint.
+    const misplaced = trulyUnknown
+        .map((key) => ({
+        key,
+        groups: tomlGroupsOf(table.fields.find((f) => f.tomlKey === key && f.tomlGroup) ??
+            {}),
+    }))
+        .filter((entry) => entry.groups.length > 0);
+    for (const { key, groups } of misplaced) {
+        // #3798 — a key two blocks share names both; the prompt's kind picks one.
+        messages.push(`${filePath}: ${prefix}[0].${key} is not a [[${prefix}]] key; ` +
+            `write it under ${groups.map((g) => `[${prefix}.${g}]`).join(" or ")}`);
+    }
+    const misplacedKeys = new Set(misplaced.map((m) => m.key));
+    const stillUnknown = trulyUnknown.filter((k) => !misplacedKeys.has(k));
+    if (stillUnknown.length > 0) {
+        messages.push(unrecognizedPushKeysMessage(filePath, table.tomlPath, stillUnknown));
+    }
+    if (groupedUnknown.size > 0) {
+        messages.push(unrecognizedPushKeysMessage(filePath, table.tomlPath, [
+            ...groupedUnknown,
+        ].sort()));
     }
     return messages.join("\n");
 }
@@ -2108,6 +2326,11 @@ function localConfigRowKey(label, tomlData, file) {
             return stated("prompt", "key");
         case "workflow":
             return stated("workflow", "key");
+        // #3320 — the declared key, like the function preflight collector, the
+        // apply loop and `--only`. A renamed file is one object, so both
+        // collectors' messages land on the one comparison row.
+        case "function":
+            return stated("function", "key");
         case "email-template":
             return stated("template", "emailType");
         case "database-type-config":
@@ -2133,6 +2356,410 @@ function localConfigRowKey(label, tomlData, file) {
             return fallback;
     }
 }
+/**
+ * `config push`'s preflight — every check the authored files decide on their
+ * own, run before the FIRST mutating call (#976 fix A, #3320, #3375).
+ *
+ * The block below was inline inside the push command's `.action()` callback
+ * until #3375 lifted it here unchanged. It had to become an exported symbol
+ * for the registry's promise to be checkable at all: a rule declared
+ * `preflight` says it runs before `config push` mutates anything, and
+ * `src/config-surface/preflight-reachability.ts` resolves that claim
+ * statically from the declared `<module>#<export>` against exactly this entry
+ * point. With the preflight anonymous, "reached from the preflight" had
+ * nothing to resolve against, and the stage string was satisfied by typing it.
+ *
+ * Its boundary is therefore precise and load-bearing: this function is what
+ * contributes to `preflightValidationErrors` and aborts. The advisory reads
+ * that follow the abort in the action — the remote vars snapshot and both caps
+ * — stay there and are declared `apply`, because the server is what enforces
+ * them (`intent` §Non-goals, "Emptying the apply stage").
+ *
+ * A network call inside a preflight is not disqualifying: `listIntegrations`
+ * was already here, answering "will this `integration:` grant have a target?"
+ * against the live listing merged with the tree, and falling back to the tree
+ * alone when the listing cannot be fetched.
+ *
+ * `input` names what the block used to close over. `client` is narrowed to the
+ * one method it calls, so an apply call cannot drift in here later without
+ * that being a visible change to this signature.
+ */
+export async function runConfigPushPreflight(input) {
+    const { configDir, resolvedAppId, pushSelection, syncState, force, isCrossAppPush, client, } = input;
+    /**
+     * Narrow a type's file list to the `--only` selection — the same one-line
+     * closure the action holds, rebuilt from the selection it passed in rather
+     * than handed across the boundary as a function.
+     */
+    const selectFiles = (label, dir, files) => filterFilesBySelection(pushSelection, label, dir, files);
+    // ── Issue #976 (fix A): front-load ALL client-side TOML validation
+    // before the first mutating call. Push is apply-as-you-go and processes
+    // entities in a fixed sequence (cron triggers are created *before*
+    // workflows are validated). Previously each entity's validation lived
+    // inside its own apply loop and aborted via `process.exit(1)` — so a
+    // known-bad sibling file (e.g. an invalid workflow TOML) could let an
+    // earlier create (a cron trigger) be applied, then abort. The
+    // `process.exit` also bypassed the save-on-failure catch below, so the
+    // orphaned create never reached the sync-state baseline and the retry
+    // re-issued a CREATE that the server rejected with 409 forever.
+    //
+    // Running every validation up-front means a known-bad file aborts
+    // BEFORE anything is created. We collect all errors (not just the first)
+    // and THROW — so the single save-on-failure catch is the only exit path
+    // (no more `process.exit` bypass class). The per-loop validators below
+    // remain as defense-in-depth but are converted to throws too.
+    const preflightValidationErrors = [];
+    // Validate all workflow TOMLs (#685 misnested-header check and the
+    // #1447 system + accessRule lint).
+    const preflightWorkflowsDir = join(configDir, "workflows");
+    if (existsSync(preflightWorkflowsDir)) {
+        // Under `--only` the preflight validates just the selected files:
+        // an unrelated broken workflow elsewhere in the slot must not block
+        // applying the one object the operator asked for.
+        for (const file of selectFiles("workflow", preflightWorkflowsDir, readdirSync(preflightWorkflowsDir).filter((f) => f.endsWith(".toml")))) {
+            const filePath = join(preflightWorkflowsDir, file);
+            try {
+                const tomlData = parseTomlFile(filePath);
+                // #1660 — skip platform-owned workflows (the reserved
+                // `__internal.*` namespace) BEFORE validating, mirroring the
+                // apply loop below. `config push` validates every workflow TOML
+                // here, up-front, before reaching that skip — so without this
+                // second skip a stale/hollow `__internal.*.toml` with an invalid
+                // `steps` shape would abort the whole push in preflight. Resolve
+                // the key the same way the apply loop does (`[workflow].key`,
+                // falling back to the filename) and match on the resolved key,
+                // never the filename alone, so a renamed file is still caught.
+                const platformOwnedKey = tomlData.workflow?.key || basename(file, ".toml");
+                if (isPlatformOwnedWorkflowKey(platformOwnedKey)) {
+                    continue;
+                }
+                const tomlErrors = validateWorkflowToml(tomlData);
+                if (tomlErrors.length > 0) {
+                    preflightValidationErrors.push(formatWorkflowTomlErrors(filePath, tomlErrors));
+                }
+                // #2643 — non-blocking notes (e.g. `strict` / `strictParams` are
+                // now no-ops). Printed once per file at pre-flight so the author
+                // sees them whether or not the push goes on to apply.
+                for (const note of collectWorkflowTomlNotes(tomlData)) {
+                    console.log(`  ${filePath}: ${note}`);
+                }
+                const unknownKeyError = workflowUnknownKeyError(filePath, tomlData);
+                if (unknownKeyError) {
+                    preflightValidationErrors.push(`  ${unknownKeyError}`);
+                }
+                // #2743 — the always-send update payload cannot carry a missing
+                // `[workflow].name`. That is a local TOML error like every other
+                // one here, so it belongs in the front-loaded pass (#976): caught
+                // in the apply loop it would abort AFTER earlier resources (app
+                // settings, cron triggers, …) had already been written, and
+                // `--dry-run` — which never reaches the apply — would plan an
+                // update the real push then refuses.
+                //
+                // Scoped to the workflows this push will actually UPDATE. A
+                // create falls back to the manifest key, so an absent name is
+                // legitimate authoring there — and once that create lands, the
+                // same unchanged file must keep pushing clean (the apply loop
+                // skips it on its content hash) instead of failing a push that
+                // was never going to send it.
+                if (workflowPushSendsUpdate(configDir, tomlData.workflow?.key || basename(file, ".toml"), tomlData, syncState, force)) {
+                    const nameError = workflowUpdateNameError(filePath, tomlData.workflow || {});
+                    if (nameError) {
+                        preflightValidationErrors.push(`  ${nameError}`);
+                    }
+                }
+            }
+            catch (err) {
+                preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
+            }
+        }
+    }
+    // Validate all database-type TOMLs (issue #803 subscription
+    // access/accessRule conflict + issue #752 $params references).
+    const preflightDbTypesDir = join(configDir, "database-type-configs");
+    if (existsSync(preflightDbTypesDir)) {
+        for (const file of selectFiles("database-type-config", preflightDbTypesDir, readdirSync(preflightDbTypesDir).filter((f) => f.endsWith(".toml")))) {
+            const filePath = join(preflightDbTypesDir, file);
+            let rawToml;
+            let tomlData;
+            try {
+                rawToml = readFileSync(filePath, "utf-8");
+                tomlData = parseTomlFile(filePath);
+            }
+            catch (err) {
+                preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
+                continue;
+            }
+            let operations = [];
+            try {
+                ({ operations } = parseDatabaseTypeToml(tomlData));
+            }
+            catch (err) {
+                if (err instanceof SubscriptionAccessKeyConflictError) {
+                    preflightValidationErrors.push(`  ${file}: ${err.message}`);
+                    continue;
+                }
+                preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
+                continue;
+            }
+            const validation = validateOperations({
+                filePath,
+                rawToml,
+                operations,
+            });
+            for (const e of validation.errors) {
+                preflightValidationErrors.push(`  ${formatIssue(e)}`);
+            }
+            // Issue #1422: non-fatal deprecation notice. A `celContextAccess`
+            // / `metadataAccess` gate on a database type config is a single CEL
+            // expression that gates BOTH read and update of the database CEL
+            // context — granting read implicitly grants update. Steer operators
+            // to resource metadata categories (separate readRule/writeRule).
+            // This is advisory only: the push continues and the runtime gate is
+            // unchanged. It fires only when the deprecated key is actually
+            // present, so metadata-category-only configs never trip it.
+            const typeSection = tomlData.type || {};
+            if (typeSection.celContextAccess || typeSection.metadataAccess) {
+                const usedKey = typeSection.celContextAccess
+                    ? "celContextAccess"
+                    : "metadataAccess";
+                warn(`  ${file}: \`${usedKey}\` is deprecated — it gates database CEL context READ and WRITE with one expression (read implies update). Prefer a resource metadata category with separate readRule/writeRule (issue #1420). Sync will continue; the runtime gate is unchanged.`);
+            }
+        }
+    }
+    // Validate app.toml settings up-front (issue #1033). A mistyped value
+    // is a hard error that must abort BEFORE any mutation — same
+    // fail-before-mutate contract as the vars preflight below. The apply
+    // block re-parses for the payload.
+    // #2645 — bounded by `--only`, like the workflow and database-type
+    // preflights above. `config push --only workflow/x` is the replacement for
+    // `workflows update --from-file`, so it must work on a tree where
+    // app.toml happens to be mid-edit.
+    const preflightAppTomlPath = join(configDir, "app.toml");
+    if (selectionIncludesApp(pushSelection) && existsSync(preflightAppTomlPath)) {
+        try {
+            const parsedApp = parseTomlFile(preflightAppTomlPath);
+            const appErrors = collectAppSettingsPushErrors(parsedApp, {
+                // #2880 DSO-001 — the same exclusion the apply block computes, so
+                // the preflight validates the body that will actually be sent.
+                excludeName: appSettingsNameExcluded({
+                    isCrossAppPush: !!isCrossAppPush,
+                    recordedExcludedName: syncState?.entities?.app?.excludedName,
+                    fileName: parsedApp?.app?.name,
+                }),
+            });
+            for (const e of appErrors) {
+                preflightValidationErrors.push(`  app.toml: ${e}`);
+            }
+        }
+        catch (err) {
+            preflightValidationErrors.push(`  app.toml: ${err?.message || String(err)}`);
+        }
+    }
+    // Validate config vars up-front (issue #1423 review). Parse vars.toml
+    // and check the same key/value constraints the server enforces here, in
+    // the preflight pass, so an invalid entry aborts BEFORE any mutation
+    // (app settings or a var upsert) is applied. Previously validation ran
+    // mid-push, after app settings could already have been updated.
+    // #2645 — bounded by `--only`, for the same reason as app.toml above.
+    const preflightVarsTomlPath = join(configDir, "vars.toml");
+    const varsSelected = selectionIncludesAnyVar(pushSelection);
+    let preflightParsedVars = null;
+    if (varsSelected && existsSync(preflightVarsTomlPath)) {
+        try {
+            const parsed = parseTomlFile(preflightVarsTomlPath);
+            // #2645 — under `--only var/<key>` only the selected entries are
+            // checked. The rest of the file is not being written, and aborting
+            // over an entry this push will not touch is the same over-reach as
+            // running the leg at all for an unselected singleton.
+            for (const e of validateVarsFile(parsed, {
+                onlyKeys: pushSelection ? pushSelection.varKeys : undefined,
+            })) {
+                preflightValidationErrors.push(`  ${e}`);
+            }
+            preflightParsedVars = parsed;
+        }
+        catch (err) {
+            preflightValidationErrors.push(`  vars.toml: ${err?.message || String(err)}`);
+        }
+    }
+    // #3182 — a function's capabilities, checked against the author's own
+    // file before anything is applied. The grammar is purely local (and
+    // since #3279 it keeps three kinds: `integration:<key>`,
+    // `secret:<NAME>` and the high-blast opt-ins — a retired grant string
+    // is refused here with the retirement); whether an `integration:`
+    // names an integration that will exist is answered against the
+    // tree's own `integrations/` (applied BEFORE functions) merged with
+    // the integrations the server already has. If the live listing cannot
+    // be fetched and the tree declares none, the target check is skipped
+    // and the server — which is authoritative — has the last word.
+    const preflightFunctionsDir = join(configDir, "functions");
+    if (existsSync(preflightFunctionsDir)) {
+        const functionFiles = selectFiles("function", preflightFunctionsDir, readdirSync(preflightFunctionsDir).filter(isFunctionDeclarationFile));
+        if (functionFiles.length > 0) {
+            const treeTargets = configObjectKeysFromTree(configDir);
+            let knownTargets = null;
+            try {
+                const integrations = await client.listIntegrations(resolvedAppId, {
+                    status: "active",
+                });
+                knownTargets = mergeKnownGrantTargets({
+                    integrations: new Set((integrations?.items ?? [])
+                        .map((row) => String(row?.integrationKey ?? ""))
+                        .filter(Boolean)),
+                }, treeTargets);
+            }
+            catch {
+                knownTargets =
+                    treeTargets.integrations.size > 0 ? treeTargets : null;
+            }
+            // #3719 — the project's document schema rides every function version,
+            // so a unique constraint on a stringset field in it refuses the push
+            // here, once, rather than deploying with seeding silently off. Bounded
+            // by the selection like the rest of this block: only a push that
+            // carries a function carries the schema.
+            const documentSchemaError = documentSchemaPreflightError(resolveDocumentSchema(configDir));
+            if (documentSchemaError) {
+                preflightValidationErrors.push(`  ${documentSchemaError}`);
+            }
+            for (const file of functionFiles) {
+                const filePath = join(preflightFunctionsDir, file);
+                let tomlData;
+                try {
+                    tomlData = parseTomlFile(filePath);
+                }
+                catch (err) {
+                    preflightValidationErrors.push(`  ${filePath}: ${err?.message || String(err)}`);
+                    continue;
+                }
+                for (const message of functionGrantErrors({
+                    filePath,
+                    tomlData,
+                    knownTargets,
+                })) {
+                    preflightValidationErrors.push(`  ${message}`);
+                }
+                // #3320 — and everything else the file decides on its own: the
+                // `entry`, the mode the two spellings resolve to, the trigger
+                // rules, and a webhook trigger's signing-secret requirement and
+                // reference shape. These used to be raised inside the apply loop,
+                // after webhooks, integrations, vars and database types had
+                // already been written — the partial tree this issue is about.
+                // Bounded by the same `selectFiles` above, so `--only` keeps its
+                // posture (#2645).
+                const functionKey = tomlData?.function?.key || basename(file, ".toml");
+                for (const message of functionTomlPreflightErrors({
+                    filePath,
+                    functionKey,
+                    tomlData,
+                })) {
+                    preflightValidationErrors.push(`  ${filePath}: ${message}`);
+                }
+                // #3482 — the retired runtime keys. NOT refusals through phase 4:
+                // the file pushes with every other key applied, and the author
+                // hears which line to delete before phase 5 refuses it. On
+                // stderr, like every other advisory, so a scripted push reading
+                // stdout is unaffected. Inside this loop rather than over the
+                // whole tree, so `--only` bounds the advice as it bounds the
+                // refusals (#2645).
+                for (const message of functionTomlIgnoredKeyWarnings({
+                    functionKey,
+                    tomlData,
+                })) {
+                    warn(`  ${message}`);
+                }
+            }
+        }
+    }
+    // #2644 — reject any key the vendored definition does not recognize,
+    // for every migrated configuration type. Same posture the `[workflow]`
+    // check above has, generalized: a mistyped key fails here, in the
+    // preflight pass, so nothing is applied and no request is issued —
+    // rather than being dropped on the way to the server and reading as a
+    // successful push that changed nothing.
+    // #2880 — the same collector `config diff` runs, so the two commands
+    // cannot disagree about which files are pushable.
+    for (const rejected of collectConfigFileValidationErrors(configDir)) {
+        for (const message of rejected.messages) {
+            preflightValidationErrors.push(`  ${message}`);
+        }
+    }
+    // #3626 §4 — one advisory line per prompt file still written in the flat
+    // chat spelling, beside the `celContextAccess` notice above. The push
+    // continues and the keys are applied; `config pull` rewrites the file, so a
+    // single pull-then-push clears the notice. Printed even under `--dry-run`,
+    // which never reaches the apply — the notice is about the FILE.
+    const preflightPromptsDir = join(configDir, "prompts");
+    // #3798 — the functions an agent's references are checked against, read
+    // once and only when a selected prompt is an agent that names one.
+    let agentFunctions = null;
+    if (existsSync(preflightPromptsDir)) {
+        for (const file of selectFiles("prompt", preflightPromptsDir, readdirSync(preflightPromptsDir).filter((f) => f.endsWith(".toml")))) {
+            const filePath = join(preflightPromptsDir, file);
+            let tomlData;
+            try {
+                tomlData = parseTomlFile(filePath);
+            }
+            catch {
+                // A file that does not parse is reported by the collector above.
+                continue;
+            }
+            const notice = promptFlatChatKeyWarning(filePath, tomlData);
+            if (notice)
+                warn(`  ${notice}`);
+            // #3798 — an agent's tool, turn-context and history functions must
+            // exist, and a tool's must declare both schemas, before anything is
+            // applied. Bounded by `--only` like the rest of this loop.
+            if (promptKindOf(tomlData?.prompt) === "agent" &&
+                agentDeclarationFunctionKeys(tomlData?.prompt?.agent).length > 0) {
+                if (!agentFunctions) {
+                    let live = null;
+                    try {
+                        live = (await client.listFunctions(resolvedAppId)).items;
+                    }
+                    catch {
+                        live = null;
+                    }
+                    agentFunctions = agentFunctionFactsForPush({
+                        configDir,
+                        pushSelection,
+                        live,
+                    });
+                }
+                for (const message of promptAgentFunctionErrors(filePath, tomlData, agentFunctions)) {
+                    preflightValidationErrors.push(`  ${message}`);
+                }
+            }
+        }
+    }
+    // #3798 — a test case on an agent is refused by the admin routes; say so
+    // here, before any other file is applied.
+    for (const message of promptAgentSidecarErrors(configDir)) {
+        preflightValidationErrors.push(`  ${message}`);
+    }
+    // The `<key>.tests/*.toml` sidecars, which sit beside the block they
+    // test rather than in a type directory of their own. Same posture,
+    // reached through the registry's `test-case` surface — and through the
+    // same collector `config diff` runs per sidecar (#2880), so neither
+    // command can refuse a file the other calls Synced.
+    for (const filePath of testCaseTomlFiles(configDir)) {
+        let tomlData;
+        try {
+            tomlData = parseTomlFile(filePath);
+        }
+        catch {
+            // Reported by the per-block test-case loop with its own message.
+            continue;
+        }
+        for (const message of testCaseSidecarPreflightErrors(filePath, tomlData)) {
+            preflightValidationErrors.push(`  ${message}`);
+        }
+    }
+    if (preflightValidationErrors.length > 0) {
+        throw new Error(`Aborting push: ${preflightValidationErrors.length} TOML validation error(s) — no changes were applied.\n` +
+            preflightValidationErrors.join("\n"));
+    }
+    return { parsedVars: preflightParsedVars };
+}
 /**
  * Every per-entity config file whose TOML `config push` would refuse (#2880
  * criterion 1, symmetry).
@@ -2143,18 +2770,445 @@ function localConfigRowKey(label, tomlData, file) {
  * issue's reporter hit after #2803 retired `[prompt].status`, where a local key
  * with no server counterpart is invisible to a comparison and fatal to a push.
  *
- * Three checks, all definition-driven: the document's table shape, keys no
- * definition declares (retired keys among them), and — since #2880 — values
- * whose spelling is not the declared type. A file that does not parse is left
- * to the per-type loop that reads it, which names the parse error itself.
+ * Three checks, all definition-driven: the document's table shape, keys no
+ * definition declares (retired keys among them), and — since #2880 — values
+ * whose spelling is not the declared type. A file that does not parse is left
+ * to the per-type loop that reads it, which names the parse error itself.
+ */
+/**
+ * The blocks one `[[configs]]` entry carries that its prompt's kind does not
+ * name — #3798. An agent's entry may carry only `[configs.agent]`; a chat or
+ * decisions entry may not carry it. `movedFlat` are the deprecated flat chat
+ * keys the hoist moved under `chat`, named as the author wrote them.
+ *
+ * Only the blocks the other arms of `resolvePromptKind` cannot see are checked
+ * here: a decisions block on a chat entry, and chat keys on a decisions entry,
+ * stay the resolver's refusals with their #3626 wording.
+ */
+function promptEntryBlockErrors(kind, entry, movedFlat) {
+    const has = (block) => entry != null && typeof entry === "object" && entry[block] !== undefined;
+    const errors = [];
+    if (kind === "agent") {
+        if (movedFlat.length > 0) {
+            errors.push(`sets ${movedFlat.join(", ")} flat — the deprecated [configs.chat] ` +
+                'spelling — but prompt kind is "agent", so it may carry only a ' +
+                "[configs.agent] block; write them under [configs.agent]");
+        }
+        for (const block of ["chat", "decisions"]) {
+            if (!has(block))
+                continue;
+            errors.push(`carries a [configs.${block}] block, but prompt kind is "agent", so ` +
+                "it may carry only a [configs.agent] block (systemPrompt, " +
+                "temperature, topP, maxTokens, reasoningEffort, reasoningBudget)");
+        }
+        return errors;
+    }
+    if (has("agent")) {
+        errors.push(`carries a [configs.agent] block, but prompt kind is "${kind}", so it ` +
+            `may carry only a [configs.${kind}] block. An agent is its own ` +
+            'prompt: create it under a new key with kind = "agent"');
+    }
+    return errors;
+}
+/**
+ * A prompt file's KIND errors — #3626, decidable from the file alone.
+ *
+ * Three refusals, all of them the same rule seen from different angles: a key
+ * set both flat and under `[configs.chat]` (the hoist will not guess), a
+ * `[[configs]]` entry carrying the block of the OTHER kind, and a malformed
+ * decisions declaration. The last two come from `resolvePromptKind`, the same
+ * vendored function the admin routes validate with, so the CLI's refusal and
+ * the server's cannot disagree — and this one lands in the preflight, before
+ * the first mutating call.
+ */
+/**
+ * The `[[configs]]` entries of a prompt file as the agent rules read them —
+ * #3799: which provider each named configuration runs on, and whether the file
+ * retires it.
+ *
+ * An archived entry is skipped by the translation rule (a config the server does
+ * not run cannot make the declaration untranslatable), which is what lets a
+ * pulled tree keep a retired config on a provider the current schemas could not
+ * reach. `status` is read through the same default the surface declares, so an
+ * entry that omits the key is live.
+ */
+function promptFileConfigFacts(entries) {
+    return (entries || []).map((entry, index) => ({
+        configName: String(entry?.name ?? `configs[${index}]`),
+        provider: String(entry?.provider ?? ""),
+        status: String(entry?.status ?? PROMPT_CONFIG_DEFAULT_STATUS),
+    }));
+}
+export function promptKindFileErrors(filePath, tomlData) {
+    const entries = Array.isArray(tomlData?.configs) ? tomlData.configs : [];
+    const errors = [];
+    const fileKind = promptKindOf(tomlData?.prompt);
+    // #3798 — the `[prompt.agent]` declaration's file-decidable half: its shape,
+    // and `[prompt].outputSchema` on an agent. The function half needs app state
+    // and runs in the push preflight (`promptAgentFunctionErrors`).
+    const declaration = resolveAgentDeclaration({
+        kind: tomlData?.prompt?.kind,
+        agent: tomlData?.prompt?.agent,
+        outputSchema: tomlData?.prompt?.outputSchema,
+    });
+    if (declaration.ok === false) {
+        for (const refusal of declaration.refusals) {
+            errors.push(`${filePath}: ${refusal.message}`);
+        }
+    }
+    else if (fileKind === "agent") {
+        // #3799 — the schemas a CLIENT tool and an event declare are in the file,
+        // so whether each provider the file configures can carry them without
+        // losing meaning is file-decidable too: `config diff` reports the same row
+        // as `config push`. A server tool's schemas are its FUNCTION's and need app
+        // state, so they are checked in the push preflight
+        // (`promptAgentFunctionErrors`). Only after the shape refusals above, so a
+        // malformed declaration is not also reported as untranslatable.
+        for (const refusal of agentSchemaTranslationRefusals({
+            declaration: tomlData?.prompt?.agent,
+            configs: promptFileConfigFacts(entries),
+        })) {
+            errors.push(`${filePath}: ${refusal.message}`);
+        }
+    }
+    for (const [index, entry] of entries.entries()) {
+        const hoisted = hoistDeprecatedChatKeys(entry);
+        for (const key of hoisted.conflicts) {
+            errors.push(`${filePath}: configs[${index}].${key} is set both flat and under ` +
+                `[configs.chat]; keep the [configs.chat] spelling`);
+        }
+        // #3798 — the block rule for three kinds, stated per entry: an entry may
+        // carry only the block its prompt's kind names. An agent's `[configs.agent]`
+        // holds keys chat also holds, so a stray block would otherwise be read (or
+        // ignored) in silence by the payload builder.
+        const blockErrors = promptEntryBlockErrors(fileKind, entry, hoisted.moved).map((message) => `${filePath}: configs[${index}] ${message}`);
+        if (blockErrors.length > 0) {
+            errors.push(...blockErrors);
+            continue;
+        }
+        if (fileKind === "agent") {
+            const agent = hoisted.entry.agent ?? {};
+            const resolution = resolvePromptKind({
+                kind: "agent",
+                provider: hoisted.entry.provider,
+                model: hoisted.entry.model,
+                config: {
+                    systemPrompt: agent.systemPrompt,
+                    temperature: agent.temperature,
+                    topP: agent.topP,
+                    maxTokens: agent.maxTokens,
+                    reasoningEffort: agent.reasoningEffort,
+                    reasoningBudget: agent.reasoningBudget,
+                    // #3801 — a chat key: named, so the refusal says which key an agent
+                    // does not take (§D1: an agent has no output schema).
+                    strictOutput: agent.strictOutput,
+                },
+            });
+            if (resolution.ok === false) {
+                errors.push(`${filePath}: configs[${index}] — ${resolution.error}`);
+            }
+            continue;
+        }
+        const chat = hoisted.entry.chat ?? {};
+        const decisions = hoisted.entry.decisions ?? {};
+        // #3626 — the FIRST entry of a chat prompt carries the create seed's
+        // placeholder. `buildPromptCreatePayload` sends `{{ input }}` when the
+        // file names no template, which is how a prompt authored without one has
+        // always created; refusing it here would break a file that pushed before
+        // the kind existed. An entry that really names none on the UPDATE path is
+        // still refused, by the server, with this same message.
+        //
+        // CR3626-005 — the fallback is `||`, not `??`, because that is what
+        // `buildPromptCreatePayload` applies (`seed.userPromptTemplate ||
+        // "{{ input }}"`). `config create prompt` scaffolds an EMPTY
+        // `userPromptTemplate`, so reading absence more narrowly than the builder
+        // does refused the file this CLI had just written, for a value the create
+        // would have replaced with the placeholder anyway.
+        const seedsTemplate = index === 0 && fileKind === "chat";
+        const userPromptTemplate = seedsTemplate
+            ? chat.userPromptTemplate || "{{ input }}"
+            : chat.userPromptTemplate;
+        const resolution = resolvePromptKind({
+            kind: tomlData?.prompt?.kind,
+            provider: hoisted.entry.provider,
+            model: hoisted.entry.model,
+            config: {
+                systemPrompt: chat.systemPrompt,
+                userPromptTemplate,
+                temperature: chat.temperature,
+                topP: chat.topP,
+                maxTokens: chat.maxTokens,
+                outputFormat: chat.outputFormat,
+                outputSchema: chat.outputSchema,
+                reasoningEffort: chat.reasoningEffort,
+                reasoningBudget: chat.reasoningBudget,
+                strictOutput: chat.strictOutput,
+                questions: decisions.questions,
+            },
+        });
+        if (resolution.ok === false) {
+            errors.push(`${filePath}: configs[${index}] — ${resolution.error}`);
+            continue;
+        }
+        // #3801 — strict output, file-decidable: the entry's own keys, the file's
+        // `[prompt].outputSchema` and the entry's status (an archived entry is not
+        // held to the prompt schema, DSO-3801-002). The route runs the same rule
+        // against what the server holds.
+        if (resolution.kind === "chat") {
+            const strict = resolvePromptStrictOutput({
+                provider: hoisted.entry.provider,
+                strictOutput: chat.strictOutput,
+                outputFormat: chat.outputFormat,
+                configOutputSchema: chat.outputSchema,
+                promptOutputSchema: tomlData?.prompt?.outputSchema,
+                status: hoisted.entry.status ?? PROMPT_CONFIG_DEFAULT_STATUS,
+            });
+            if (strict.ok === false) {
+                errors.push(`${filePath}: configs[${index}] — ${strict.error} (${strict.code})`);
+            }
+        }
+    }
+    return errors;
+}
+/** A schema slot counts as declared when it holds anything but nothing. */
+function declaresSchema(value) {
+    if (value === undefined || value === null)
+        return false;
+    return !(typeof value === "string" && value.trim() === "");
+}
+/**
+ * The functions an agent's references are checked against at push — #3798,
+ * DSO-3798-002.
+ *
+ * `config push` applies prompts, then (for agents) the server functions leg,
+ * so a reference may be satisfied by a function that is live already or by one
+ * this push creates. What the push BELIEVES is therefore the live listing
+ * overlaid by the function files this push SELECTS (`--only`, every file when
+ * unscoped): a selected file's schemas are what the server will hold after the
+ * push, so it wins over the live row. An UNSELECTED file is not read at all —
+ * its edits will not be applied, and a function only it declares will not
+ * exist afterwards.
+ *
+ * `live` is `null` when the listing could not be fetched: the selected files
+ * still count, and `liveListed` lets the refusal say why every other reference
+ * could not be confirmed. A live row that is archived is a tombstone, not a
+ * function; an inactive one is accepted (the turn engine re-checks
+ * availability on every call).
+ */
+export function agentFunctionFactsForPush(input) {
+    const facts = {};
+    for (const row of input.live ?? []) {
+        const key = String(row?.functionKey ?? "");
+        if (!key || row?.status === "archived")
+            continue;
+        facts[key] = {
+            hasInputSchema: declaresSchema(row.inputSchema),
+            hasOutputSchema: declaresSchema(row.outputSchema),
+            // #3799 — the schemas themselves, as stored (a JSON string from the API,
+            // an object from a tree file), so a server tool's two schemas can be
+            // translated for each of the agent's providers.
+            inputSchema: row.inputSchema,
+            outputSchema: row.outputSchema,
+        };
+    }
+    const functionsDir = join(input.configDir, "functions");
+    if (existsSync(functionsDir)) {
+        for (const file of filterFilesBySelection(input.pushSelection, "function", functionsDir, readdirSync(functionsDir).filter(isFunctionDeclarationFile))) {
+            let table;
+            try {
+                table = parseTomlFile(join(functionsDir, file))?.function ?? {};
+            }
+            catch {
+                // Reported by the function preflight with its own message.
+                continue;
+            }
+            const key = table.key || basename(file, ".toml");
+            facts[key] = {
+                hasInputSchema: declaresSchema(table.inputSchema),
+                hasOutputSchema: declaresSchema(table.outputSchema),
+                // #3799 — a SELECTED file's schemas are what the server will hold after
+                // this push, so they are what the translation is checked against.
+                inputSchema: table.inputSchema,
+                outputSchema: table.outputSchema,
+            };
+        }
+    }
+    return { facts, liveListed: input.live !== null };
+}
+/**
+ * The function half of an agent's declaration — #3798: every tool, turn
+ * context and history function that the functions this push believes
+ * (`agentFunctionFactsForPush`) do not have, and every tool function lacking an
+ * input or output schema. The same `resolveAgentDeclaration` the admin routes
+ * run; only its function refusals are reported here, because the collector
+ * (`promptKindFileErrors`) already reported the file-decidable ones.
+ */
+export function promptAgentFunctionErrors(filePath, tomlData, known) {
+    if (promptKindOf(tomlData?.prompt) !== "agent")
+        return [];
+    const result = resolveAgentDeclaration({
+        kind: "agent",
+        agent: tomlData?.prompt?.agent,
+        functions: known.facts,
+    });
+    const errors = result.ok === false
+        ? result.refusals
+            .filter((refusal) => refusal.code === "AGENT_TOOL_FUNCTION_MISSING" ||
+            refusal.code === "AGENT_TOOL_FUNCTION_SCHEMA_MISSING")
+            .map((refusal) => refusal.code === "AGENT_TOOL_FUNCTION_MISSING" && !known.liveListed
+            ? `${filePath}: ${refusal.message} (the app's live functions could ` +
+                "not be listed, so only the function files this push applies were " +
+                "checked)"
+            : `${filePath}: ${refusal.message}`)
+        : [];
+    // #3799 — a SERVER tool's schemas are its function's, so translating them
+    // needs the facts this push believes (the live listing overlaid by the
+    // function files it selects, DSO-3798-002). The client-tool and event half is
+    // file-decidable and reported by `promptKindFileErrors`, which `config diff`
+    // runs too; passing the facts here means only the server-tool refusals are
+    // new, because that collector already saw the rest.
+    const entries = Array.isArray(tomlData?.configs) ? tomlData.configs : [];
+    const configs = promptFileConfigFacts(entries);
+    const fileDecidable = new Set(agentSchemaTranslationRefusals({
+        declaration: tomlData?.prompt?.agent,
+        configs,
+    }).map((refusal) => refusal.message));
+    for (const refusal of agentSchemaTranslationRefusals({
+        declaration: tomlData?.prompt?.agent,
+        functions: known.facts,
+        configs,
+    })) {
+        if (fileDecidable.has(refusal.message))
+            continue;
+        errors.push(`${filePath}: ${refusal.message}`);
+    }
+    return errors;
+}
+/**
+ * The order `config push` applies prompt files in — #3798. An agent names
+ * server functions that must exist when it is created, and the push applies
+ * prompts before functions, so agent files go AFTER the server-functions leg;
+ * every other file keeps its place. A file that does not parse stays first, so
+ * the leg reports it where it always has.
+ */
+export function partitionPromptFilesForPush(promptsDir, files) {
+    const beforeFunctions = [];
+    const afterFunctions = [];
+    for (const file of files) {
+        let kind = "chat";
+        try {
+            kind = promptKindOf(parseTomlFile(join(promptsDir, file))?.prompt);
+        }
+        catch {
+            beforeFunctions.push(file);
+            continue;
+        }
+        (kind === "agent" ? afterFunctions : beforeFunctions).push(file);
+    }
+    return { beforeFunctions, afterFunctions };
+}
+/**
+ * Every `prompts/<key>.tests/*.toml` sidecar whose prompt is an agent — #3798
+ * (§D1: prompt test cases are refused for the kind in v1). The admin test-case
+ * routes refuse the same case with `AGENT_TEST_CASE_NOT_SUPPORTED`; this says
+ * so before anything is applied.
+ */
+export function promptAgentSidecarErrors(configDir) {
+    const promptsDir = join(configDir, "prompts");
+    const errors = [];
+    for (const filePath of testCaseTomlFiles(configDir)) {
+        const parent = basename(join(filePath, ".."));
+        if (!filePath.startsWith(promptsDir) || !parent.endsWith(".tests"))
+            continue;
+        const key = parent.slice(0, -".tests".length);
+        const owner = join(promptsDir, `${key}.toml`);
+        if (!existsSync(owner))
+            continue;
+        let tomlData;
+        try {
+            tomlData = parseTomlFile(owner);
+        }
+        catch {
+            continue;
+        }
+        if (promptKindOf(tomlData?.prompt) !== "agent")
+            continue;
+        const promptKey = tomlData?.prompt?.key || key;
+        errors.push(`${filePath.slice(configDir.length + 1)}: ` +
+            agentTestCaseRefusal(promptKey, "subject").message);
+    }
+    return errors;
+}
+/**
+ * The immutable-`kind` refusal for a prompt update the comparison gate did not
+ * decide — #3626, CR3626-001.
+ *
+ * `kind` is create-only (D3626-008), and the gate refuses a change to it on
+ * every path that compares the two sides. Two update paths do not compare: a
+ * prompt whose DETAIL read failed falls back to the manifest byte-hash gate,
+ * which `--force` writes straight through, and a prompt ADOPTED after a
+ * create's 409 is re-issued as an update without a comparison at all. Both
+ * would otherwise PATCH the file's schemas, access rule and metadata onto a
+ * row of the other kind, and only then have its configs refused against the
+ * kind the update cannot change.
+ *
+ * Returns the gate's own outcome shape, so `recordDeclined` prints the same
+ * two values and the same remedy — create the prompt under a new key.
+ *
+ * `null` when the kinds agree and when the server's kind is simply not KNOWN:
+ * a push that could not read live state at all has nothing to compare, and
+ * that path's contract (`decideDegradedPush`, #2880) is already "decline
+ * unless the operator forces it", stated for every field at once.
+ */
+export function promptKindImmutableOutcome(storedKind, localDoc) {
+    if (!storedKind)
+        return null;
+    const localKind = promptKindOf(localDoc?.prompt);
+    if (localKind === storedKind)
+        return null;
+    return {
+        action: "immutable",
+        // The hashes are the gate's evidence for WHICH side moved, and this
+        // refusal does not depend on that: the field cannot be written either way.
+        localHash: "",
+        remoteHash: "",
+        fields: [{ field: "kind", local: localKind, server: storedKind }],
+        immutableFields: ["kind"],
+    };
+}
+/**
+ * The one deprecation notice a prompt file using the FLAT chat spelling earns
+ * — #3626 §4, beside the `celContextAccess` notice's precedent.
+ *
+ * Advisory: the push continues and the keys are applied. `null` when the file
+ * is already written in the grouped spelling, so a migrated tree is silent.
  */
+export function promptFlatChatKeyWarning(filePath, tomlData) {
+    const entries = Array.isArray(tomlData?.configs) ? tomlData.configs : [];
+    const moved = new Set();
+    for (const entry of entries) {
+        for (const key of hoistDeprecatedChatKeys(entry).moved)
+            moved.add(key);
+    }
+    if (moved.size === 0)
+        return null;
+    const named = [...moved].sort().join(", ");
+    return (`${filePath}: ${named} ${moved.size === 1 ? "is" : "are"} written flat ` +
+        "under [[configs]]; this spelling is deprecated — move them under " +
+        "[configs.chat] (`config pull` rewrites the file). Rejecting the flat " +
+        "spelling is tracked in #3642.");
+}
 export function collectConfigFileValidationErrors(configDir) {
     const found = [];
     for (const { dir, surface, tables } of unknownKeyPreflightTargets()) {
         const typeDir = join(configDir, dir);
         if (!existsSync(typeDir))
             continue;
-        for (const file of readdirSync(typeDir).filter((f) => f.endsWith(".toml"))) {
+        for (const file of readdirSync(typeDir).filter((f) => 
+        // #3455 — `functions/` holds one GENERATED `.toml` beside the
+        // declarations: the project's document schema, which is not a config
+        // object and would be read as a function named after the file.
+        dir === "functions" ? isFunctionDeclarationFile(f) : f.endsWith(".toml"))) {
             const filePath = join(typeDir, file);
             let tomlData;
             try {
@@ -2179,6 +3233,12 @@ export function collectConfigFileValidationErrors(configDir) {
             for (const table of surface.tables) {
                 messages.push(...configDeclaredTypeErrors(filePath, tomlData, table));
             }
+            // #3626 — the prompt kind's own file-decidable refusals, run by the same
+            // collector so `config push` and `config diff` cannot disagree about
+            // which prompt files are pushable.
+            if (surface.label === "prompt") {
+                messages.push(...promptKindFileErrors(filePath, tomlData));
+            }
             if (messages.length === 0)
                 continue;
             found.push({
@@ -2191,6 +3251,104 @@ export function collectConfigFileValidationErrors(configDir) {
     }
     return found;
 }
+/**
+ * Every `functions/<key>.toml` whose file-decidable errors `config push` would
+ * refuse (#3320).
+ *
+ * A second collector rather than a branch inside
+ * `collectConfigFileValidationErrors`, and deliberately so: push calls that one
+ * UNBOUNDED over the whole tree, which is right for the checks it runs (a
+ * mistyped key anywhere means the tree is not pushable) and wrong for these — a
+ * `config push --only webhook/<key>` must not be blocked by a broken function
+ * the operator did not select (#2645). The push path therefore runs these
+ * inside its own `selectFiles`-bounded function loop, and `config diff`, which
+ * compares the whole tree by construction, runs them from here.
+ *
+ * A file that does not parse is skipped: the per-type loop that reads it names
+ * the parse error itself, and reporting it twice helps nobody.
+ */
+export function collectFunctionTomlValidationErrors(configDir) {
+    const found = [];
+    const functionsDir = join(configDir, "functions");
+    if (!existsSync(functionsDir))
+        return found;
+    for (const file of readdirSync(functionsDir).filter(isFunctionDeclarationFile)) {
+        const filePath = join(functionsDir, file);
+        let tomlData;
+        try {
+            tomlData = parseTomlFile(filePath);
+        }
+        catch {
+            continue;
+        }
+        // The DECLARED key, like the apply loop and `--only` selection: a file
+        // whose name and `[function].key` differ is one object, not two.
+        const key = tomlData?.function?.key || basename(file, ".toml");
+        const messages = functionTomlPreflightErrors({
+            filePath,
+            functionKey: key,
+            tomlData,
+        });
+        if (messages.length === 0)
+            continue;
+        found.push({ type: "function", key, filePath, messages });
+    }
+    return found;
+}
+/**
+ * The retired runtime keys every `functions/*.toml` in the tree still carries
+ * — #3482, the warning half of the collector above.
+ *
+ * Separate from the errors because it IS separate: a file carrying one of
+ * these pushes, with every other key applied, so it is not a row `config diff`
+ * calls invalid. It is a line an author reads on stderr from both commands, so
+ * the two keep reading identically (the #2880 symmetry the errors collector
+ * exists for, applied to advice rather than refusals).
+ */
+export function collectFunctionTomlIgnoredKeyWarnings(configDir) {
+    const found = [];
+    const functionsDir = join(configDir, "functions");
+    if (!existsSync(functionsDir))
+        return found;
+    for (const file of readdirSync(functionsDir).filter(isFunctionDeclarationFile)) {
+        const filePath = join(functionsDir, file);
+        let tomlData;
+        try {
+            tomlData = parseTomlFile(filePath);
+        }
+        catch {
+            continue;
+        }
+        const key = tomlData?.function?.key || basename(file, ".toml");
+        found.push(...functionTomlIgnoredKeyWarnings({ functionKey: key, tomlData }));
+    }
+    return found;
+}
+/**
+ * The collectors' rows, one per diff row (#2880 symmetry, #3320).
+ *
+ * Two collectors reach the same function file — the definition-driven one
+ * every per-entity type runs, and the function preflight — and a file can
+ * break both at once (a mistyped `entrty`, which then leaves no `entry`).
+ * Push reports every message from both, so an overlay that let one row's
+ * messages REPLACE the other's would drop a diagnostic push prints, which is
+ * exactly the asymmetry #2880 forbids. Merging by row keeps the two commands
+ * reading identically.
+ */
+export function mergeConfigFileValidationErrors(collected) {
+    const byRow = new Map();
+    for (const rejected of collected) {
+        const rowId = `${rejected.type}${rejected.key}`;
+        const merged = byRow.get(rowId);
+        if (!merged) {
+            byRow.set(rowId, { ...rejected, messages: [...rejected.messages] });
+            continue;
+        }
+        // Collection order is the message order, the same order push prints.
+        merged.messages.push(...rejected.messages);
+    }
+    return [...byRow.values()];
+}
 /**
  * Every `<key>.tests/*.toml` sidecar under a config directory.
  *
@@ -2287,6 +3445,17 @@ export function workflowPushSendsUpdate(configDir, key, parsedWorkflowToml, sync
  *
  * Returns `null` when the name is present.
  */
+/**
+ * The preflight error a project's document schema contributes, or `null` —
+ * #3719.
+ *
+ * Only a `refusal` counts: a unique constraint on a stringset field, which no
+ * writer can key consistently, so the push stops before any mutation. Every
+ * other unusable-schema case stays the apply loop's warning (D3455-004).
+ */
+export function documentSchemaPreflightError(resolution) {
+    return resolution.refusal;
+}
 export function workflowUpdateNameError(filePath, workflow) {
     const name = workflow?.name;
     if (typeof name === "string" && name.trim() !== "")
@@ -3149,6 +4318,114 @@ export function diffProjectedRecords(local, remote) {
     }
     return diffs;
 }
+/**
+ * The paths at which two projected records disagree, named the way the FILE
+ * spells them (#3267) — what a `config diff` Modified row prints.
+ *
+ * `diffProjectedRecords` answers at the granularity of the projection, and
+ * for a database type that is too coarse to act on: the 27 operations arrive
+ * as one `operations` extra, the whole `[models.*]` tree as one `schema`
+ * string. A row that read Modified for a reason the operator could not see —
+ * an empty params set spelled two ways, an operation block the file declares
+ * twice — was undiagnosable from the CLI. So this walks INTO each differing
+ * field: a keyed child collection (`spec.childKeys`) is compared row by row
+ * and named `operations["getInstitution"].params`, with a row only one side
+ * has or that the file repeats named as such; a TOML-string field
+ * (`spec.tomlFields`) is parsed on both sides and named by the path inside it
+ * (`schema (models.Institution.fields.name.required)`); everything else is
+ * walked as a value to its first differing leaf.
+ *
+ * Paths come back in projected-key order, keyed rows in key order, so the
+ * list is stable across runs, and every leaf is its own entry — a schema
+ * that differs in seven model fields is seven paths, so the caller's "+N
+ * more" cap counts them the way it counts operations. A value the walk
+ * cannot descend into (an array of a different length, a scalar against an
+ * object) is named at the level it stopped.
+ */
+export function describeProjectedDifferences(spec, local, remote) {
+    const paths = [];
+    for (const { field, local: l, server: r } of diffProjectedRecords(local, remote)) {
+        const childKey = spec.childKeys?.[field];
+        if (childKey && Array.isArray(l) && Array.isArray(r)) {
+            paths.push(...keyedChildDifferences(field, childKey, l, r));
+            continue;
+        }
+        if (spec.tomlFields?.includes(field) && typeof l === "string" && typeof r === "string") {
+            let inner;
+            try {
+                inner = valueDifferences("", parseConfigToml(l), parseConfigToml(r));
+            }
+            catch {
+                // A side that does not parse is named as the whole field below.
+            }
+            if (inner) {
+                if (inner.length === 0) {
+                    paths.push(field);
+                }
+                else {
+                    paths.push(...inner.map((path) => `${field} (${path})`));
+                }
+                continue;
+            }
+        }
+        paths.push(...valueDifferences(field, l, r));
+    }
+    return paths;
+}
+/** The leaf paths under `path` at which two values differ (see above). */
+function valueDifferences(path, a, b) {
+    if (canonicalJsonStringify(a) === canonicalJsonStringify(b))
+        return [];
+    const join = (key) => (path ? `${path}.${key}` : key);
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+        return keys.flatMap((key) => valueDifferences(join(key), a[key], b[key]));
+    }
+    if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) {
+        return a.flatMap((item, i) => valueDifferences(`${path}[${i}]`, item, b[i]));
+    }
+    return [path || "(document)"];
+}
+/**
+ * A keyed child collection's differences, row by row. A key the file repeats
+ * is named as the cause rather than compared: the server keys rows by it, so
+ * only one of the blocks landed and no push can make the two sides agree
+ * while the file says two things under one name.
+ */
+function keyedChildDifferences(field, key, local, remote) {
+    const label = (k) => `${field}[${JSON.stringify(k)}]`;
+    const localByKey = new Map();
+    for (const row of local) {
+        const k = String(row?.[key] ?? "");
+        localByKey.set(k, [...(localByKey.get(k) ?? []), row]);
+    }
+    const remoteByKey = new Map(remote.map((row) => [String(row?.[key] ?? ""), row]));
+    const keys = [...new Set([...localByKey.keys(), ...remoteByKey.keys()])].sort();
+    const paths = [];
+    for (const k of keys) {
+        const rows = localByKey.get(k);
+        const remoteRow = remoteByKey.get(k);
+        if (rows && rows.length > 1) {
+            paths.push(`${label(k)} (declared ${rows.length} times locally)`);
+        }
+        else if (!rows) {
+            paths.push(`${label(k)} (server only)`);
+        }
+        else if (remoteRow === undefined) {
+            paths.push(`${label(k)} (local only)`);
+        }
+        else {
+            paths.push(...valueDifferences(label(k), rows[0], remoteRow));
+        }
+    }
+    return paths;
+}
+function isPlainObject(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        typeof value.toJSON !== "function");
+}
 /**
  * The differing fields the definition says an UPDATE does not accept (#2731 B8).
  *
@@ -3167,6 +4444,10 @@ export function classifyPushChange(input) {
     const { localHash, remoteHash, baselineHash, legacy } = input;
     if (localHash === remoteHash)
         return "unchanged";
+    // Ahead of both the baseline and the legacy inference, which are ways of
+    // GUESSING what this states outright.
+    if (input.serverUnchangedSinceSync === true)
+        return "local-edited";
     if (baselineHash) {
         if (remoteHash === baselineHash)
             return "local-edited";
@@ -3330,6 +4611,43 @@ const CONFIG_DIFF_SPECS = {
         serialize: (record) => serializeEmailTemplate(record),
         describe: (entity) => `email template "${entity?.emailType}"`,
     },
+    // #3179 — server functions. The compared entity spans the header AND the
+    // keys the immutable version carries (`entry`, `mode`, `limits`, …),
+    // because an author writes one file and a version is never authored
+    // separately: comparing only the header would report a changed entry point as
+    // Synced. The SOURCE bytes are a second axis the table cannot express — they
+    // are compared by `envelopeHash`, which is also what the server dedupes on.
+    "function": {
+        label: "function",
+        table: SERVER_FUNCTION_TABLE,
+        parse: (doc) => functionDiffEntity(doc),
+        // `extra` is the ACTIVE config version, which is where the remote side's
+        // entry/mode/limits live; the header row does not carry them.
+        serialize: (record, _maps, extra) => serializeFunction(record, extra),
+        // The version-carried keys are not fields of the header table, so they
+        // travel as extras — present on both sides or absent on both.
+        extras: (entity) => ({
+            // #3317 — `inputSchema` / `outputSchema` compared as the values they
+            // encode, the rule prompts have had since #2748. A schema reaches the
+            // two sides in either spelling (a native `[function.inputSchema]` table,
+            // or the JSON string the server stores and the fallback pull writes for
+            // a schema TOML cannot hold), and neither spelling is a difference.
+            ...jsonFieldsForDiff(SERVER_FUNCTION_TABLE, entity),
+            entry: entity.entry ?? null,
+            // #3281 — the RESOLVED mode (`functionDiffEntity` reads both spellings),
+            // so a legacy `durable = true` file and a server serializing `mode`
+            // compare equal.
+            mode: entity.mode ?? null,
+            limits: entity.limits ?? null,
+            // #3182 — the grants are version-carried too, and a widened grant set is
+            // exactly the change a reviewer must not read as Synced. Sorted because
+            // the row stores a set.
+            capabilities: Array.isArray(entity.capabilities)
+                ? [...entity.capabilities].map((c) => String(c)).sort()
+                : [],
+        }),
+        describe: (entity) => `function "${entity?.functionKey}"`,
+    },
     // #2757 — webhooks join the registry comparator for the same reason email
     // templates did: `config diff` reported existence only, so an edit that
     // rerouted a webhook to a different `workflowKey` read as Synced while push
@@ -3406,7 +4724,17 @@ const CONFIG_DIFF_SPECS = {
         // (`[prompt].key`) is still read here, because it is what `displayName`
         // falls back to. Diff injects the resolved key into a file that omits it,
         // exactly as push derives it from the file name.
-        parse: (doc) => buildPromptPushPayload(doc?.prompt?.key ?? "", doc),
+        //
+        // #3626, SO3626-008 — projected in CREATE mode. `kind` is `writableOn:
+        // ["create"]`, and `buildPayloadFromToml` drops a field not writable in the
+        // mode, so an update-mode projection would leave a CHANGED kind out of the
+        // compared surface entirely: `findImmutableFieldDiffs` would never see it,
+        // diff would call the file Synced, and push would start applying the
+        // prompt's other changes before the server refused a config against the
+        // unchanged kind. The blob-bucket comparator projects in create mode for
+        // exactly this reason (`ttlTier`, below). PATCH payloads still omit `kind`
+        // — this is the comparison's projection, not push's.
+        parse: (doc) => buildPromptPushPayload(doc?.prompt?.key ?? "", doc, { mode: "create" }),
         serialize: (record) => serializePrompt(record),
         // Read from the DOCUMENT, not the parsed entity: `[[configs]]` is a sibling
         // table of `[prompt]`, and the prompt's own push payload does not carry it
@@ -3603,6 +4931,8 @@ const CONFIG_DIFF_SPECS = {
             subscriptions: byKey(entity.__subscriptions, "subscriptionKey"),
             _unresolvedRuleSetName: entity._unresolvedRuleSetName,
         }),
+        childKeys: { operations: "name", subscriptions: "subscriptionKey" },
+        tomlFields: ["schema"],
         ruleSetRef: true,
         describe: (entity) => `database type "${entity?.databaseType}"`,
     },
@@ -3697,9 +5027,11 @@ export function compareLocalToRemote(spec, localParsed, remoteRecord, maps = {
         const localHash = computeExpandedContentHash(pair.local);
         if (remoteHash === localHash)
             return { status: "exists" };
+        // #3267 — WHICH field, ahead of the remedy, so a row that differs for a
+        // reason the operator cannot see in the file is diagnosable from the CLI.
         return {
             status: "modified",
-            hint: "run `config pull` to rewrite the local TOML to match running state",
+            hint: namedDifferences(describeProjectedDifferences(spec, pair.local, pair.remote)) + "run `config pull` to rewrite the local TOML to match running state",
         };
     }
     catch {
@@ -3708,6 +5040,24 @@ export function compareLocalToRemote(spec, localParsed, remoteRecord, maps = {
         return { status: "exists", hint: "content not compared (comparison failed)" };
     }
 }
+/**
+ * How many differing paths a Modified row names before saying "+N more"
+ * (#3267). Enough to see the shape of a difference at a glance; the row is
+ * one line of a whole-tree diff, not the place to print 27 operations.
+ */
+const NAMED_DIFFERENCE_LIMIT = 5;
+/**
+ * The `differs in …; ` prefix of a Modified row's hint (#3267), or nothing
+ * when the walk could name no path — the hash still differs, so the row is
+ * still Modified, but the hint then says only what it always said.
+ */
+function namedDifferences(paths) {
+    if (paths.length === 0)
+        return "";
+    const shown = paths.slice(0, NAMED_DIFFERENCE_LIMIT).join(", ");
+    const more = paths.length - NAMED_DIFFERENCE_LIMIT;
+    return `differs in ${shown}${more > 0 ? ` (+${more} more)` : ""}; `;
+}
 /** Hash a LOCAL config file's definition-projected field set (#2644). */
 export function hashLocalConfigForDiff(spec, parsedToml, maps, extra) {
     return computeExpandedContentHash(projectLocalConfig(spec, parsedToml, maps, extra));
@@ -3769,17 +5119,32 @@ export function decidePushForConfig(input) {
             fields,
         };
     }
+    // The recorded server timestamp still being the live one. It is the legacy
+    // path's inference signal, and — where the row's timestamp covers the whole
+    // projection — #3317's outright statement that the server did not move.
+    const liveModifiedAtMatchesStored = entry?.modifiedAt !== undefined &&
+        live.modifiedAt !== undefined &&
+        entry.modifiedAt === live.modifiedAt;
+    // The recorded version pointer still being the live one — or no pointer
+    // recorded, which is no claim. A pointer that moved is a server change by
+    // definition, whatever the two timestamps say (#3317: the baseline's
+    // timestamp comes from a refetch a concurrent activation can precede).
+    const liveActiveConfigMatchesStored = entry?.activeConfigId === undefined ||
+        (live.record?.activeConfigId !== undefined &&
+            live.record?.activeConfigId !== null &&
+            String(entry.activeConfigId) === String(live.record.activeConfigId));
     const direction = classifyPushChange({
         localHash,
         remoteHash,
         baselineHash: entry?.semanticHash,
+        serverUnchangedSinceSync: input.serverModifiedAtCoversProjection === true &&
+            liveModifiedAtMatchesStored &&
+            liveActiveConfigMatchesStored,
         legacy: {
             localBytesMatchStoredContentHash: entry?.contentHash !== undefined &&
                 localFileHash !== undefined &&
                 entry.contentHash === localFileHash,
-            liveModifiedAtMatchesStored: entry?.modifiedAt !== undefined &&
-                live.modifiedAt !== undefined &&
-                entry.modifiedAt === live.modifiedAt,
+            liveModifiedAtMatchesStored,
         },
     });
     // #2909 — the adopt, for a type whose push path adopts by key. `entry` is
@@ -4147,7 +5512,7 @@ export function configSemanticHash(label, filePath, maps) {
 /**
  * The sync state `config push` writes into (#2731 B6, closing #2374).
  *
- * `loadSyncState` answers `null` for an absent `.primitive-sync.json`, and
+ * `loadSyncState` answers `null` for an absent sync-state baseline, and
  * every per-entity state write in the push loops is guarded by `if (syncState)`
  * — so a first push created every resource and recorded none of them. The next
  * push then re-entered the create path for everything and depended on 409
@@ -4335,37 +5700,6 @@ export function unselectedRuleSetIds(params) {
     }
     return seeded;
 }
-// Test case helpers (exported for unit testing)
-export function slugifyTestCaseName(name) {
-    return name
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        || "test";
-}
-/**
- * The name to use for `slug`, given the names already taken.
- *
- * `occupy` decides what "already taken" means, and `usedSlugs` holds names in
- * that form (#2896): a file name is occupied CASE-INSENSITIVELY on the
- * filesystems most of these trees live on, so `Foo` and `foo` are one file even
- * though they are two strings. The returned name keeps its own casing — only
- * the occupancy check is normalized.
- */
-export function resolveSlugCollisions(slug, usedSlugs, occupy = (name) => name) {
-    const taken = (candidate) => usedSlugs.has(occupy(candidate));
-    if (!taken(slug)) {
-        usedSlugs.add(occupy(slug));
-        return slug;
-    }
-    let counter = 2;
-    while (taken(`${slug}-${counter}`)) {
-        counter++;
-    }
-    const resolved = `${slug}-${counter}`;
-    usedSlugs.add(occupy(resolved));
-    return resolved;
-}
 export function getTestsDir(configDir, blockType, blockKey) {
     // Scripts (blockType "script") live under `transforms/` on disk (their
     // bodies are `transforms/<name>.rhai`), so their test cases sit alongside at
@@ -4620,6 +5954,231 @@ selects = () => true) {
         : { ok: false };
     return { scriptEntities, count: written, presence, listOk: true, serverKeys };
 }
+/**
+ * The manifest row `config push` records for a function it just pushed
+ * (#3317), and whether the server had already moved past that push.
+ *
+ * The header is refetched AFTER the version push, so the row's `modifiedAt`
+ * is the live timestamp — but the version pointer and the envelope are the
+ * push's own: the manifest names what THIS run activated, not whatever the
+ * refetch happened to find. A concurrent activation landing between the push
+ * and the refetch is exactly the case those two must not be conflated in:
+ * recording the refetched pointer would make the other operator's version the
+ * baseline the local file is then read as a plain edit of, and the next push
+ * would roll it back without `--force`. Recording the pushed pointer beside
+ * the live timestamp is what `decidePushForConfig` reads as "the pointer
+ * moved" — a refusal, until the operator pulls or forces.
+ *
+ * `movedTo` names the version the refetched header points at when it is not
+ * the pushed one, so the caller can say so at the moment it is known rather
+ * than leaving it for the next push to report.
+ */
+export function pushedFunctionBaseline(input) {
+    const { refreshed, pushedVersion } = input;
+    const pushedConfigId = pushedVersion?.configId !== undefined && pushedVersion?.configId !== null
+        ? String(pushedVersion.configId)
+        : undefined;
+    const liveConfigId = refreshed?.activeConfigId !== undefined && refreshed?.activeConfigId !== null
+        ? String(refreshed.activeConfigId)
+        : undefined;
+    const movedTo = pushedConfigId !== undefined &&
+        liveConfigId !== undefined &&
+        liveConfigId !== pushedConfigId
+        ? liveConfigId
+        : null;
+    return {
+        entity: {
+            id: input.functionId,
+            modifiedAt: refreshed?.modifiedAt ||
+                input.existingModifiedAt ||
+                new Date().toISOString(),
+            contentHash: input.contentHash,
+            semanticHash: refreshed
+                ? hashRemoteConfigForDiff(input.spec, refreshed, input.maps, pushedVersion ?? undefined)
+                : undefined,
+            envelopeHash: input.envelopeHash,
+            activeConfigId: pushedConfigId,
+            sources: input.sources,
+        },
+        movedTo,
+    };
+}
+/**
+ * Pull server-side `ServerFunction` rows into `functions/` (#3179).
+ *
+ * Two things make this different from every other type's pull:
+ *
+ *   1. **A function is more than its file.** The active config VERSION holds an
+ *      envelope with the authored TOML bytes and every source file, so the pull
+ *      writes `functions/<key>.toml` plus the TypeScript beside it, and records
+ *      the source paths so prune can remove the code with the function.
+ *   2. **Bytes, not a re-serialization.** The stored TOML is written verbatim,
+ *      so comments, key order and line endings survive the round trip (F-009).
+ *      A function that has never had code pushed has no stored bytes; that one
+ *      gets a canonical serialization of its header, which is still a pushable
+ *      file.
+ *
+ * A stored source path is never trusted: `planFunctionPull` refuses one that
+ * normalizes outside the tree, and the refusals are reported rather than
+ * swallowed.
+ */
+export async function pullFunctions(client, appId, configDir, logger = () => { }, selects = () => true) {
+    const functionsDir = join(configDir, "functions");
+    ensureDir(functionsDir);
+    const functionEntities = {};
+    /** What each pulled version says about the document schema — CR3455-001. */
+    const pulledSchemas = [];
+    let items = [];
+    try {
+        const result = await client.listFunctions(appId);
+        items = result.items || [];
+    }
+    catch {
+        return {
+            functionEntities,
+            count: 0,
+            presence: { ok: false },
+            listOk: false,
+            serverKeys: [],
+            items: [],
+        };
+    }
+    let detailsOk = true;
+    let written = 0;
+    for (const record of items) {
+        const key = record?.functionKey;
+        if (!key)
+            continue;
+        if (!selects(key))
+            continue;
+        // #2803 — a tombstone is not exported as a file. Its key stays reserved,
+        // and the archived-holder message is what says so on the next push.
+        if (String(record.status ?? "active") === "archived")
+            continue;
+        const filePath = join(functionsDir, `${key}.toml`);
+        let entity = {
+            id: record.functionId,
+            modifiedAt: record.modifiedAt || new Date().toISOString(),
+        };
+        if (!record.activeConfigId) {
+            // No code pushed yet: the header is all there is to write.
+            // The logger carries #1446's one warning: a schema holding a `null`
+            // anywhere cannot be a native table, so it is written as a JSON string
+            // and the operator is told which key that happened to.
+            writeFileSync(filePath, serializeFunction(record, undefined, logger));
+            entity.contentHash = computeFileHash(filePath);
+            entity.semanticHash = hashRemoteConfigForDiff(configDiffSpec("function"), record, { ruleSetIdToName: new Map(), ruleSetNameToId: new Map() });
+            functionEntities[key] = entity;
+            written += 1;
+            logger(`  Wrote functions/${key}.toml (no version pushed yet)`);
+            continue;
+        }
+        let active;
+        let envelope;
+        let newest = null;
+        try {
+            // #3462 — the point read. The listing is a page now, so scanning it for
+            // the id would miss a rolled-back function's active version past page
+            // one; the separate one-row read below is only asking whether a NEWER
+            // version exists, which is what the message after the write says.
+            active = record.activeConfigId
+                ? await client.getFunctionConfig(appId, record.functionId, String(record.activeConfigId))
+                : null;
+            if (active) {
+                envelope = await client.getFunctionConfigEnvelope(appId, record.functionId, active.configId);
+                const page = await client.listFunctionConfigs(appId, record.functionId, {
+                    limit: 1,
+                });
+                newest = (page.items || [])[0] ?? null;
+            }
+        }
+        catch {
+            detailsOk = false;
+            logger(`  Skipped functions/${key}.toml (could not fetch its version)`);
+            continue;
+        }
+        if (!active || !envelope) {
+            detailsOk = false;
+            logger(`  Skipped functions/${key}.toml (active version not readable)`);
+            continue;
+        }
+        // #3455 / CR3455-001 — the generated schema copy is ONE file the whole
+        // tree resolves through, so this plan does not decide it. Every pulled
+        // version's answer is collected and the copy is settled once, after the
+        // loop; otherwise the last function applied would delete or overwrite the
+        // copy an earlier one needs.
+        const plan = planFunctionPull({
+            configDir,
+            functionKey: key,
+            envelope,
+            includeDocumentSchema: false,
+        });
+        pulledSchemas.push({
+            functionKey: key,
+            documentSchema: typeof envelope?.documentSchema === "string" && envelope.documentSchema
+                ? envelope.documentSchema
+                : null,
+        });
+        for (const refusal of plan.refusals)
+            logger(`  ${refusal}`);
+        // #3482 — the retired runtime keys this pull removed on the way out. Not
+        // a refusal: the file IS written, with every other byte unchanged, and
+        // this is what says so rather than editing a developer's file in silence.
+        for (const note of plan.notes)
+            logger(`  ${note}`);
+        const applied = applyFunctionPull(plan);
+        for (const refusal of applied.refusals)
+            logger(`  ${refusal}`);
+        entity.contentHash = computeFileHash(filePath);
+        entity.semanticHash = hashRemoteConfigForDiff(configDiffSpec("function"), record, { ruleSetIdToName: new Map(), ruleSetNameToId: new Map() }, active);
+        entity.envelopeHash = envelope.envelopeHash ?? active.envelopeHash;
+        entity.activeConfigId = active.configId;
+        // Only the files that were really written: a path the write step refused
+        // is not one prune may later delete on this function's behalf.
+        entity.sources = applied.writtenSources;
+        functionEntities[key] = entity;
+        written += 1;
+        logger(`  Wrote functions/${key}.toml and ${applied.writtenSources.length} source file(s)`);
+        // #3462 — pull writes the ACTIVE version's bytes, which is right: the tree
+        // should describe what runs. On a rolled-back function that silently
+        // discards a newer version's code from the tree, so the line names both
+        // versions and both remedies rather than leaving the author to discover it
+        // at the next push.
+        const newerLine = newerVersionLine(newest, active.configId, (value) => value);
+        if (newerLine) {
+            logger(`  ${pullNewerVersionLine(key, String(active.configId), newest, (value) => value)}`);
+        }
+    }
+    const serverKeys = items
+        .filter((f) => String(f?.status ?? "active") !== "archived")
+        .map((f) => f?.functionKey)
+        .filter(Boolean);
+    // #3455 / CR3455-001 — the tree's one generated schema copy, settled from
+    // every version this pull read. Removing it is only safe when the pull read
+    // them ALL: a selector, or a function whose version could not be fetched,
+    // leaves a version whose schema this pull knows nothing about.
+    const schemaPlan = planDocumentSchemaPull({
+        configDir,
+        functions: pulledSchemas,
+        coversEveryFunction: detailsOk && serverKeys.every((k) => selects(k)),
+    });
+    for (const warning of schemaPlan.warnings)
+        logger(`  ${warning}`);
+    const schemaApplied = applyFunctionPull(schemaPlan);
+    for (const refusal of schemaApplied.refusals)
+        logger(`  ${refusal}`);
+    const presence = detailsOk
+        ? { ok: true, serverKeys }
+        : { ok: false };
+    return {
+        functionEntities,
+        count: written,
+        presence,
+        listOk: true,
+        serverKeys,
+        items,
+    };
+}
 /**
  * Every test case a block has, draining the cursor (#2769).
  *
@@ -5478,54 +7037,6 @@ export async function pushTestCasesForBlock(params) {
     }
     return { skipped };
 }
-/**
- * The file name each live test case belongs in (#2896).
- *
- * A KEYED case is named by its key: that is what the key is — the basename the
- * committed tree carries. An unkeyed one (created by web-admin, an older CLI or
- * the raw API) keeps the slug-of-name naming, with the collision suffixes
- * resolved only AFTER the keys have claimed theirs, so a slug can never take a
- * name a key owns.
- *
- * One function for pull, for pairing's adoption pass and for the diff's
- * remote-only rows, because three commands that name a case's file differently
- * is the disagreement this issue reports.
- *
- * Two names that differ only by CASE are one file on a case-insensitive
- * filesystem, so occupancy is tracked the way the server's key constraint
- * normalizes: a keyed `Foo` and an unkeyed case named "foo" get `Foo.toml` and
- * `foo-2.toml`, rather than one pull silently overwriting the other's sidecar.
- */
-export function testCaseFileBasenames(liveCases, onUnusableKey, isSafeName) {
-    const used = new Set();
-    const occupy = (name) => normalizeTestCaseKey(name);
-    const names = new Map();
-    const unkeyed = [];
-    for (const live of liveCases) {
-        const key = typeof live?.key === "string" ? live.key : "";
-        if (!key) {
-            unkeyed.push(live);
-            continue;
-        }
-        // The key is SERVER data on its way to becoming a path. A server that
-        // stored one this CLI would not have sent must not be able to name a file
-        // outside the sidecar directory.
-        const reason = testCaseKeyError(key) ??
-            (isSafeName && !isSafeName(key)
-                ? `test case key "${key}" is not a safe file name here`
-                : null);
-        if (reason) {
-            onUnusableKey?.(live, reason);
-            unkeyed.push(live);
-            continue;
-        }
-        names.set(live, resolveSlugCollisions(key, used, occupy));
-    }
-    for (const live of unkeyed) {
-        names.set(live, resolveSlugCollisions(slugifyTestCaseName(live?.name || "unnamed"), used, occupy));
-    }
-    return names;
-}
 /**
  * Whether a sidecar and a live case say the same thing (#2896).
  *
@@ -6163,26 +7674,19 @@ function readSelection(options) {
  * `registerConfigCommands` created rather than making one of its own.
  *
  * The module keeps its name and its ~50 exported helpers: `sync.ts`,
- * `resolveSyncDir`, `.primitive-sync.json` and `.primitive/sync/<env>/<appId>/`
+ * `resolveSyncDir`, the sync-state baseline and `primitive/<env>/`
  * are internal identifiers, deliberately left alone (#2759 scope).
  */
 export function registerConfigSyncCommands(sync) {
     // Init
     sync
         .command("init")
+        .allowExcessArguments(false)
         .description("Initialize the config directory structure")
-        .argument("[app-id]", "App ID (uses current app if not specified)")
-        .option("--app <app-id>", "App ID")
-        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
-        .action(async (appId, options) => {
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-            const legacyHint = checkLegacySyncMigration(configDir);
-            if (legacyHint)
-                warn(legacyHint);
-        }
+        .action(async (options) => {
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
+        info(`Using per-environment config directory: ${configDir}`);
         ensureDir(configDir);
         ensureDir(join(configDir, "integrations"));
         ensureDir(join(configDir, "webhooks"));
@@ -6191,6 +7695,7 @@ export function registerConfigSyncCommands(sync) {
         ensureDir(join(configDir, "prompts"));
         ensureDir(join(configDir, "workflows"));
         ensureDir(join(configDir, "transforms")); // #892 slice 7 — Rhai scripts
+        ensureDir(join(configDir, "functions")); // #3179 — server functions
         ensureDir(join(configDir, "database-type-configs"));
         ensureDir(join(configDir, "rule-sets"));
         ensureDir(join(configDir, "group-type-configs"));
@@ -6210,10 +7715,8 @@ export function registerConfigSyncCommands(sync) {
     // Pull
     sync
         .command("pull")
+        .allowExcessArguments(false)
         .description("Download configuration from server to TOML files")
-        .argument("[app-id]", "App ID (uses current app if not specified)")
-        .option("--app <app-id>", "App ID")
-        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
         .option("--json", "Output as JSON instead of writing files")
         .option("--only <selectors>", "Fetch just these objects: <type>/<key>, app, or var/<key> (repeatable, or comma-separated). Everything else in the slot is left as it is.", 
     // Collect rather than replace, the same way push does: commander keeps
@@ -6221,14 +7724,11 @@ export function registerConfigSyncCommands(sync) {
     // narrow the pull to one object and report success.
     (value, previous) => [...(previous ?? []), value], [])
         .option("--no-prune", "Keep local files for entities that are absent from the sync export (the next push will re-create them)")
-        .action(async (appId, options) => {
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
-        if (isAutoResolvedSyncDir(options.dir) && !options.json) {
+        .action(async (options) => {
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
+        if (!options.json) {
             info(`Using per-environment config directory: ${configDir}`);
-            const legacyHint = checkLegacySyncMigration(configDir);
-            if (legacyHint)
-                warn(legacyHint);
         }
         // Issue #2760: pull writes the renamed directory and leaves the old one
         // untouched beside it, which reads as a successful pull that lost the
@@ -6428,10 +7928,7 @@ export function registerConfigSyncCommands(sync) {
             // perform it without a recoverable backup. No-op on a fresh/empty
             // sync dir (nothing to back up). Prune to 28 days after success.
             try {
-                const snapshotsRoot = resolveSnapshotsRoot({
-                    appId: resolvedAppId,
-                    userDir: options.dir,
-                });
+                const snapshotsRoot = resolveSnapshotsRoot({ appId: resolvedAppId });
                 const snapshot = createSnapshot(configDir, snapshotsRoot);
                 if (snapshot) {
                     info(`  Snapshot: ${snapshot.path}`);
@@ -6442,7 +7939,7 @@ export function registerConfigSyncCommands(sync) {
                 error(`Failed to create a pre-pull snapshot: ${snapErr?.message ?? snapErr}`);
                 error("Aborting pull before any local file is modified. " +
                     "Resolve the snapshot error (e.g. disk space / permissions) and retry, " +
-                    "or pass a writable --dir.");
+                    "and that the project's .primitive/ is writable.");
                 process.exit(1);
             }
             // Ensure directories exist
@@ -6454,6 +7951,7 @@ export function registerConfigSyncCommands(sync) {
             ensureDir(join(configDir, "prompts"));
             ensureDir(join(configDir, "workflows"));
             ensureDir(join(configDir, "transforms")); // #892 slice 7 — Rhai scripts
+            ensureDir(join(configDir, "functions")); // #3179 — server functions
             ensureDir(join(configDir, "database-type-configs"));
             ensureDir(join(configDir, "rule-sets"));
             ensureDir(join(configDir, "group-type-configs"));
@@ -6809,6 +8307,20 @@ export function registerConfigSyncCommands(sync) {
             if (pulledScriptsCount > 0) {
                 info(`  Pulled ${pulledScriptsCount} transform(s)`);
             }
+            // Pull server functions — #3179. Writes `functions/<key>.toml` from the
+            // AUTHORED bytes stored in the active version's envelope, plus every
+            // source file beside it, so the round trip is byte-identical.
+            const { functionEntities, count: pulledFunctionsCount, presence: functionPresence, listOk: functionListOk, serverKeys: functionServerKeys, items: functionTombstoneCandidates, } = await pullFunctions(client, resolvedAppId, configDir, info, (key) => {
+                if (!pullSelection)
+                    return true;
+                if (!selectionIncludesKey(pullSelection, "function", key))
+                    return false;
+                matchedSelectors.add(`function/${key}`);
+                return true;
+            });
+            if (pulledFunctionsCount > 0) {
+                info(`  Pulled ${pulledFunctionsCount} function(s)`);
+            }
             // Build lookup maps for test case serialization
             const configIdToName = new Map();
             const promptIdToKey = new Map();
@@ -6996,6 +8508,21 @@ export function registerConfigSyncCommands(sync) {
                 };
                 info(`  Wrote database-type-configs/${filename}`);
             }
+            // #3182 — the typed-handle artifacts are REGENERATED, never pulled:
+            // they are not in the envelope, and a fresh clone must end up with the
+            // same three files a push would have written. Written here, after the
+            // database types, so the declaration describes what this pull wrote.
+            try {
+                const artifacts = writeFunctionTypeArtifacts(configDir);
+                if (artifacts.length > 0) {
+                    info(`  Wrote function types: ${artifacts.join(", ")}`);
+                }
+            }
+            catch (err) {
+                if (!(err instanceof FunctionSchemaCodegenError))
+                    throw err;
+                warn(`  Function types not generated: ${err.message}`);
+            }
             // Write rule sets
             const ruleSetEntities = {};
             for (const ruleSet of ruleSets) {
@@ -7087,6 +8614,7 @@ export function registerConfigSyncCommands(sync) {
                     ? { ok: true, serverKeys: blobBucketItems.map((b) => b.bucketKey) }
                     : { ok: false },
                 scripts: scriptPresence,
+                functions: functionPresence,
                 emailTemplates: emailTemplatePresence,
                 databaseTypes: databaseTypeConfigsOutcome.ok && databaseTypeDetailsOk
                     ? { ok: true, serverKeys: databaseTypesWithOps.map((d) => d.typeConfig.databaseType) }
@@ -7153,11 +8681,36 @@ export function registerConfigSyncCommands(sync) {
                 for (const key of plan.unsafeKeys) {
                     warn(`  Skipped pruning ${resourceType.dir} entry "${key}" — its sync-state key does not map to a safe filename`);
                 }
+                // #3179 — the source files the SURVIVORS still own. Two functions can
+                // import the same module, and both record it; deleting it with one
+                // would leave the other unbuildable while its state called it
+                // current. Both the prior state and this pull's entities are read,
+                // because a function created server-side since the last pull owns its
+                // sources only in the fresh map.
+                const pruningKeys = new Set(plan.keys);
+                const retainedFiles = new Set();
+                const collectRetained = (entities) => {
+                    for (const [entityKey, entity] of Object.entries(entities ?? {})) {
+                        if (pruningKeys.has(entityKey))
+                            continue;
+                        for (const path of (entity?.sources ?? [])) {
+                            retainedFiles.add(path);
+                        }
+                    }
+                };
+                collectRetained(priorEntities[resourceType.stateSlot]);
+                if (resourceType.stateSlot === "functions") {
+                    collectRetained(functionEntities);
+                }
                 const result = await applyPrune({
                     configDir,
                     resourceType,
                     keys: plan.keys,
                     testCaseEntities,
+                    // #3179 — a function's TypeScript goes with it. Only the prior sync
+                    // state knows where those files are, so it is what names them.
+                    extraFilesForKey: (key) => priorEntities[resourceType.stateSlot]?.[key]?.sources ?? [],
+                    retainedFiles,
                     logger: info,
                 });
                 prunedCount += result.prunedKeys.length;
@@ -7173,12 +8726,14 @@ export function registerConfigSyncCommands(sync) {
             // the prior entry for that one key — see `preserveUnwrittenEntries`.
             const keepPrior = (ok, built, slot) => ok ? built : (priorEntities[slot] ?? built);
             preserveUnwrittenEntries(scriptEntities, priorEntities.scripts, scriptServerKeys);
+            preserveUnwrittenEntries(functionEntities, priorEntities.functions, functionServerKeys);
             preserveUnwrittenEntries(emailTemplateEntities, priorEntities.emailTemplates, emailTemplatesOutcome.ok
                 ? emailTemplateOverrides.map((t) => t.emailType)
                 : []);
             const finalCronTriggerEntities = keepPrior(cronTriggersOutcome.ok, cronTriggerEntities, "cronTriggers");
             const finalBlobBucketEntities = keepPrior(blobBucketsOutcome.ok, blobBucketEntities, "blobBuckets");
             const finalScriptEntities = keepPrior(scriptListOk, scriptEntities, "scripts");
+            const finalFunctionEntities = keepPrior(functionListOk, functionEntities, "functions");
             const finalEmailTemplateEntities = keepPrior(emailTemplatesOutcome.ok, emailTemplateEntities, "emailTemplates");
             const finalDatabaseTypeEntities = keepPrior(databaseTypeConfigsOutcome.ok, databaseTypeEntities, "databaseTypes");
             const finalRuleSetEntities = keepPrior(ruleSetsOutcome.ok, ruleSetEntities, "ruleSets");
@@ -7207,6 +8762,7 @@ export function registerConfigSyncCommands(sync) {
                 prompts: promptEntities,
                 workflows: workflowEntities,
                 scripts: finalScriptEntities,
+                functions: finalFunctionEntities,
                 emailTemplates: finalEmailTemplateEntities,
                 databaseTypes: finalDatabaseTypeEntities,
                 ruleSets: finalRuleSetEntities,
@@ -7277,6 +8833,17 @@ export function registerConfigSyncCommands(sync) {
                         idOf: (w) => w.workflowId,
                     }, Object.keys(priorEntities.workflows ?? {})),
                 ],
+                // #3179 — the sixth carrying type reaches the same place. An archived
+                // function keeps its key in the app's SINGLE key namespace, so a
+                // stranded tombstone blocks a workflow, a script or a webhook wanting
+                // that key too, not just another function.
+                [
+                    "functions",
+                    archivedTombstoneEntries(functionTombstoneCandidates, {
+                        keyOf: (f) => f.functionKey,
+                        idOf: (f) => f.functionId,
+                    }, Object.keys(priorEntities.functions ?? {})),
+                ],
             ]) {
                 const built = entitiesBySlot[slot];
                 const resourceType = SYNC_RESOURCE_TYPES.find((rt) => rt.stateSlot === slot);
@@ -7373,6 +8940,7 @@ export function registerConfigSyncCommands(sync) {
                     prompts: promptEntities,
                     workflows: workflowEntities,
                     scripts: Object.keys(finalScriptEntities).length > 0 ? finalScriptEntities : undefined,
+                    functions: Object.keys(finalFunctionEntities).length > 0 ? finalFunctionEntities : undefined,
                     emailTemplates: Object.keys(finalEmailTemplateEntities).length > 0 ? finalEmailTemplateEntities : undefined,
                     testCases: Object.keys(testCaseEntities).length > 0 ? testCaseEntities : undefined,
                     databaseTypes: Object.keys(finalDatabaseTypeEntities).length > 0 ? finalDatabaseTypeEntities : undefined,
@@ -7398,6 +8966,7 @@ export function registerConfigSyncCommands(sync) {
             keyValue("Prompts", prompts.length);
             keyValue("Workflows", workflows.length);
             keyValue("Transforms", pulledScriptsCount);
+            keyValue("Functions", pulledFunctionsCount);
             keyValue("Email Templates", emailTemplates.length);
             keyValue("Test Cases", totalTestCases);
             keyValue("Database Types", databaseTypesWithOps.length);
@@ -7432,10 +9001,8 @@ export function registerConfigSyncCommands(sync) {
     // Push
     sync
         .command("push")
+        .allowExcessArguments(false)
         .description("Upload local TOML configuration to server")
-        .argument("[app-id]", "App ID (uses current app if not specified)")
-        .option("--app <app-id>", "App ID")
-        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
         .option("--dry-run", "Show what would be changed without applying")
         .option("--force", "Overwrite remote even if modified since last pull")
         .option("--only <selectors>", "Apply just these objects: <type>/<key>, app, or var/<key> (repeatable, or comma-separated). Everything else about push is unchanged.", 
@@ -7446,15 +9013,32 @@ export function registerConfigSyncCommands(sync) {
         .option("--prune", "Delete remote entities whose local TOML was removed since the last sync (issue #1655)")
         .option("-y, --yes", "Skip the interactive confirmation before pruning (for CI / automation)")
         .option("--accept-warnings", "Commit schema diffs that have operations with dynamic refs (issue #666 SCHEMA_HAS_UNCHECKABLE_OPS escape hatch)")
-        .action(async (appId, options) => {
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-            const legacyHint = checkLegacySyncMigration(configDir);
-            if (legacyHint)
-                warn(legacyHint);
-        }
+        // #3320 — what this command actually guarantees, said where it is run.
+        // Two stages, and only the first is all-or-nothing.
+        .addHelpText("after", `
+What a push guarantees (two stages):
+
+  Preflight — the local tree only. Unknown keys and declared types, workflow
+  lints, function grant grammar, a function's \`entry\`, the function trigger
+  rules, and a webhook trigger's signing-secret requirement and reference
+  shape. Any error among them aborts the whole run and nothing is applied.
+  Those are the server's own rules, run against your files.
+
+  Apply — incremental and convergent, and there is no rollback. A rejection
+  may stop the remaining work depending on the type; whatever was already
+  applied stays applied; the exit status is non-zero; re-running converges.
+  A refused FUNCTION is recorded and the loop continues, so the rest of the
+  tree still lands.
+
+  Not preflighted, because the file cannot answer it: whether a referenced
+  secret exists, whether a scheme's config is valid under this environment's
+  policy, per-app caps, key collisions. Those surface during apply.
+`)
+        .option("--no-typecheck", "Ship function code without typechecking it against the declarations this push generates (issue #3331)")
+        .action(async (options) => {
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
+        info(`Using per-environment config directory: ${configDir}`);
         // Issue #2760. An un-renamed checkout's `database-types/` is ignored, so
         // an ordinary push applies nothing from it — worth a warning. `--prune`
         // is the destructive case: it flags every prior-state key whose local
@@ -7479,14 +9063,6 @@ export function registerConfigSyncCommands(sync) {
         // `syncCallable` PATCH ordering a second implementation has broken before.
         // Everything else about push is unchanged.
         const pushSelection = readSelection(options);
-        if (pushSelection) {
-            const missing = unmatchedSelectors(pushSelection, configDir);
-            if (missing.length > 0) {
-                error(`No local file declares: ${missing.join(", ")}. Run 'primitive config pull', or 'primitive config create <type> <key>' to create one.`);
-                process.exit(1);
-            }
-            info(`Applying only: ${pushSelection.raw.join(", ")}`);
-        }
         /** Narrow a type's file list to the `--only` selection. */
         const selectFiles = (label, dir, files) => filterFilesBySelection(pushSelection, label, dir, files);
         /**
@@ -7520,6 +9096,29 @@ export function registerConfigSyncCommands(sync) {
                 entities: {},
             };
         }
+        // A `--only` selector that would apply nothing is refused before push
+        // runs, so `--only workflow/typo` fails loudly instead of iterating empty
+        // lists and reporting success.
+        //
+        // Checked HERE, after the baseline is loaded and after the cross-app reset
+        // above, rather than beside `readSelection` where it used to sit (#3398).
+        // `--prune` acts on keys the sync state tracks and NO local file declares,
+        // so a file-only check refused the one command that is supposed to run with
+        // the file gone: `--only workflow/household-forget --prune` reported `No
+        // local file declares: workflow/household-forget` and left no way to retire
+        // one tracked key without restoring its TOML (which prune would then
+        // decline to consider) or dropping `--only` and pushing the whole tree.
+        // The state has to be in hand to tell that key from a typo, and the
+        // cross-app reset has to have happened first: it clears the entity ids, so
+        // there is nothing for prune to retire and a removed key IS a typo again.
+        if (pushSelection) {
+            const missing = unmatchedSelectors(pushSelection, configDir, trackedSelectorKeys(syncState, { prune: !!options.prune }));
+            if (missing.length > 0) {
+                error(`No local file declares: ${missing.join(", ")}. Run 'primitive config pull', or 'primitive config create <type> <key>' to create one.`);
+                process.exit(1);
+            }
+            info(`Applying only: ${pushSelection.raw.join(", ")}`);
+        }
         info(`Pushing configuration for app ${resolvedAppId}...`);
         // The state this push STARTS from, so the failure path below can tell a
         // run that recorded something from one that recorded nothing (#2936).
@@ -7896,242 +9495,36 @@ export function registerConfigSyncCommands(sync) {
                 for (const [key, id] of promptKeyToId) {
                     pushTestCaseLookupMaps.promptIdToKey.set(id, key);
                 }
-                for (const [scoped, id] of [
-                    ...promptConfigNameToId,
-                    ...workflowConfigNameToId,
-                    ...scriptConfigNameToId,
-                    ...integrationConfigNameToId,
-                ]) {
-                    // The map is keyed `<blockKey>#<configName>`; the comparison names
-                    // the config, not the block.
-                    pushTestCaseLookupMaps.configIdToName.set(id, scoped.slice(scoped.indexOf("#") + 1));
-                }
-            };
-            // ── Issue #976 (fix A): front-load ALL client-side TOML validation
-            // before the first mutating call. Push is apply-as-you-go and processes
-            // entities in a fixed sequence (cron triggers are created *before*
-            // workflows are validated). Previously each entity's validation lived
-            // inside its own apply loop and aborted via `process.exit(1)` — so a
-            // known-bad sibling file (e.g. an invalid workflow TOML) could let an
-            // earlier create (a cron trigger) be applied, then abort. The
-            // `process.exit` also bypassed the save-on-failure catch below, so the
-            // orphaned create never reached `.primitive-sync.json` and the retry
-            // re-issued a CREATE that the server rejected with 409 forever.
-            //
-            // Running every validation up-front means a known-bad file aborts
-            // BEFORE anything is created. We collect all errors (not just the first)
-            // and THROW — so the single save-on-failure catch is the only exit path
-            // (no more `process.exit` bypass class). The per-loop validators below
-            // remain as defense-in-depth but are converted to throws too.
-            const preflightValidationErrors = [];
-            // Validate all workflow TOMLs (#685 misnested-header check and the
-            // #1447 system + accessRule lint).
-            const preflightWorkflowsDir = join(configDir, "workflows");
-            if (existsSync(preflightWorkflowsDir)) {
-                // Under `--only` the preflight validates just the selected files:
-                // an unrelated broken workflow elsewhere in the slot must not block
-                // applying the one object the operator asked for.
-                for (const file of selectFiles("workflow", preflightWorkflowsDir, readdirSync(preflightWorkflowsDir).filter((f) => f.endsWith(".toml")))) {
-                    const filePath = join(preflightWorkflowsDir, file);
-                    try {
-                        const tomlData = parseTomlFile(filePath);
-                        // #1660 — skip platform-owned workflows (the reserved
-                        // `__internal.*` namespace) BEFORE validating, mirroring the
-                        // apply loop below. `config push` validates every workflow TOML
-                        // here, up-front, before reaching that skip — so without this
-                        // second skip a stale/hollow `__internal.*.toml` with an invalid
-                        // `steps` shape would abort the whole push in preflight. Resolve
-                        // the key the same way the apply loop does (`[workflow].key`,
-                        // falling back to the filename) and match on the resolved key,
-                        // never the filename alone, so a renamed file is still caught.
-                        const platformOwnedKey = tomlData.workflow?.key || basename(file, ".toml");
-                        if (isPlatformOwnedWorkflowKey(platformOwnedKey)) {
-                            continue;
-                        }
-                        const tomlErrors = validateWorkflowToml(tomlData);
-                        if (tomlErrors.length > 0) {
-                            preflightValidationErrors.push(formatWorkflowTomlErrors(filePath, tomlErrors));
-                        }
-                        // #2643 — non-blocking notes (e.g. `strict` / `strictParams` are
-                        // now no-ops). Printed once per file at pre-flight so the author
-                        // sees them whether or not the push goes on to apply.
-                        for (const note of collectWorkflowTomlNotes(tomlData)) {
-                            console.log(`  ${filePath}: ${note}`);
-                        }
-                        const unknownKeyError = workflowUnknownKeyError(filePath, tomlData);
-                        if (unknownKeyError) {
-                            preflightValidationErrors.push(`  ${unknownKeyError}`);
-                        }
-                        // #2743 — the always-send update payload cannot carry a missing
-                        // `[workflow].name`. That is a local TOML error like every other
-                        // one here, so it belongs in the front-loaded pass (#976): caught
-                        // in the apply loop it would abort AFTER earlier resources (app
-                        // settings, cron triggers, …) had already been written, and
-                        // `--dry-run` — which never reaches the apply — would plan an
-                        // update the real push then refuses.
-                        //
-                        // Scoped to the workflows this push will actually UPDATE. A
-                        // create falls back to the manifest key, so an absent name is
-                        // legitimate authoring there — and once that create lands, the
-                        // same unchanged file must keep pushing clean (the apply loop
-                        // skips it on its content hash) instead of failing a push that
-                        // was never going to send it.
-                        if (workflowPushSendsUpdate(configDir, tomlData.workflow?.key || basename(file, ".toml"), tomlData, syncState, options.force)) {
-                            const nameError = workflowUpdateNameError(filePath, tomlData.workflow || {});
-                            if (nameError) {
-                                preflightValidationErrors.push(`  ${nameError}`);
-                            }
-                        }
-                    }
-                    catch (err) {
-                        preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
-                    }
-                }
-            }
-            // Validate all database-type TOMLs (issue #803 subscription
-            // access/accessRule conflict + issue #752 $params references).
-            const preflightDbTypesDir = join(configDir, "database-type-configs");
-            if (existsSync(preflightDbTypesDir)) {
-                for (const file of selectFiles("database-type-config", preflightDbTypesDir, readdirSync(preflightDbTypesDir).filter((f) => f.endsWith(".toml")))) {
-                    const filePath = join(preflightDbTypesDir, file);
-                    let rawToml;
-                    let tomlData;
-                    try {
-                        rawToml = readFileSync(filePath, "utf-8");
-                        tomlData = parseTomlFile(filePath);
-                    }
-                    catch (err) {
-                        preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
-                        continue;
-                    }
-                    let operations = [];
-                    try {
-                        ({ operations } = parseDatabaseTypeToml(tomlData));
-                    }
-                    catch (err) {
-                        if (err instanceof SubscriptionAccessKeyConflictError) {
-                            preflightValidationErrors.push(`  ${file}: ${err.message}`);
-                            continue;
-                        }
-                        preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
-                        continue;
-                    }
-                    const validation = validateOperations({
-                        filePath,
-                        rawToml,
-                        operations,
-                    });
-                    for (const e of validation.errors) {
-                        preflightValidationErrors.push(`  ${formatIssue(e)}`);
-                    }
-                    // Issue #1422: non-fatal deprecation notice. A `celContextAccess`
-                    // / `metadataAccess` gate on a database type config is a single CEL
-                    // expression that gates BOTH read and update of the database CEL
-                    // context — granting read implicitly grants update. Steer operators
-                    // to resource metadata categories (separate readRule/writeRule).
-                    // This is advisory only: the push continues and the runtime gate is
-                    // unchanged. It fires only when the deprecated key is actually
-                    // present, so metadata-category-only configs never trip it.
-                    const typeSection = tomlData.type || {};
-                    if (typeSection.celContextAccess || typeSection.metadataAccess) {
-                        const usedKey = typeSection.celContextAccess
-                            ? "celContextAccess"
-                            : "metadataAccess";
-                        warn(`  ${file}: \`${usedKey}\` is deprecated — it gates database CEL context READ and WRITE with one expression (read implies update). Prefer a resource metadata category with separate readRule/writeRule (issue #1420). Sync will continue; the runtime gate is unchanged.`);
-                    }
-                }
-            }
-            // Validate app.toml settings up-front (issue #1033). A mistyped value
-            // is a hard error that must abort BEFORE any mutation — same
-            // fail-before-mutate contract as the vars preflight below. The apply
-            // block re-parses for the payload.
-            // #2645 — bounded by `--only`, like the workflow and database-type
-            // preflights above. `config push --only workflow/x` is the replacement for
-            // `workflows update --from-file`, so it must work on a tree where
-            // app.toml happens to be mid-edit.
-            const preflightAppTomlPath = join(configDir, "app.toml");
-            if (selectionIncludesApp(pushSelection) && existsSync(preflightAppTomlPath)) {
-                try {
-                    const parsedApp = parseTomlFile(preflightAppTomlPath);
-                    const appErrors = collectAppSettingsPushErrors(parsedApp, {
-                        // #2880 DSO-001 — the same exclusion the apply block computes, so
-                        // the preflight validates the body that will actually be sent.
-                        excludeName: appSettingsNameExcluded({
-                            isCrossAppPush: !!isCrossAppPush,
-                            recordedExcludedName: syncState?.entities?.app?.excludedName,
-                            fileName: parsedApp?.app?.name,
-                        }),
-                    });
-                    for (const e of appErrors) {
-                        preflightValidationErrors.push(`  app.toml: ${e}`);
-                    }
-                }
-                catch (err) {
-                    preflightValidationErrors.push(`  app.toml: ${err?.message || String(err)}`);
+                for (const [scoped, id] of [
+                    ...promptConfigNameToId,
+                    ...workflowConfigNameToId,
+                    ...scriptConfigNameToId,
+                    ...integrationConfigNameToId,
+                ]) {
+                    // The map is keyed `<blockKey>#<configName>`; the comparison names
+                    // the config, not the block.
+                    pushTestCaseLookupMaps.configIdToName.set(id, scoped.slice(scoped.indexOf("#") + 1));
                 }
-            }
-            // Validate config vars up-front (issue #1423 review). Parse vars.toml
-            // and check the same key/value constraints the server enforces here, in
-            // the preflight pass, so an invalid entry aborts BEFORE any mutation
-            // (app settings or a var upsert) is applied. Previously validation ran
-            // mid-push, after app settings could already have been updated.
-            // #2645 — bounded by `--only`, for the same reason as app.toml above.
+            };
+            // #3375 — the front-loaded pass now lives in one exported entry point,
+            // `runConfigPushPreflight`, so a rule declared `preflight` can be
+            // proved to be reached from it before anything below mutates. Nothing
+            // about what it checks, the order it checks it, or what it prints
+            // moved with it.
+            const { parsedVars: preflightParsedVars } = await runConfigPushPreflight({
+                configDir,
+                resolvedAppId,
+                pushSelection,
+                syncState,
+                force: !!options.force,
+                isCrossAppPush: !!isCrossAppPush,
+                client,
+            });
+            // Re-derived, not returned: both are one-line functions of inputs the
+            // entry point already took, and widening its return type to carry them
+            // would make the vars apply leg depend on the preflight's internals.
             const preflightVarsTomlPath = join(configDir, "vars.toml");
             const varsSelected = selectionIncludesAnyVar(pushSelection);
-            let preflightParsedVars = null;
-            if (varsSelected && existsSync(preflightVarsTomlPath)) {
-                try {
-                    const parsed = parseTomlFile(preflightVarsTomlPath);
-                    // #2645 — under `--only var/<key>` only the selected entries are
-                    // checked. The rest of the file is not being written, and aborting
-                    // over an entry this push will not touch is the same over-reach as
-                    // running the leg at all for an unselected singleton.
-                    for (const e of validateVarsFile(parsed, {
-                        onlyKeys: pushSelection ? pushSelection.varKeys : undefined,
-                    })) {
-                        preflightValidationErrors.push(`  ${e}`);
-                    }
-                    preflightParsedVars = parsed;
-                }
-                catch (err) {
-                    preflightValidationErrors.push(`  vars.toml: ${err?.message || String(err)}`);
-                }
-            }
-            // #2644 — reject any key the vendored definition does not recognize,
-            // for every migrated configuration type. Same posture the `[workflow]`
-            // check above has, generalized: a mistyped key fails here, in the
-            // preflight pass, so nothing is applied and no request is issued —
-            // rather than being dropped on the way to the server and reading as a
-            // successful push that changed nothing.
-            // #2880 — the same collector `config diff` runs, so the two commands
-            // cannot disagree about which files are pushable.
-            for (const rejected of collectConfigFileValidationErrors(configDir)) {
-                for (const message of rejected.messages) {
-                    preflightValidationErrors.push(`  ${message}`);
-                }
-            }
-            // The `<key>.tests/*.toml` sidecars, which sit beside the block they
-            // test rather than in a type directory of their own. Same posture,
-            // reached through the registry's `test-case` surface — and through the
-            // same collector `config diff` runs per sidecar (#2880), so neither
-            // command can refuse a file the other calls Synced.
-            for (const filePath of testCaseTomlFiles(configDir)) {
-                let tomlData;
-                try {
-                    tomlData = parseTomlFile(filePath);
-                }
-                catch {
-                    // Reported by the per-block test-case loop with its own message.
-                    continue;
-                }
-                for (const message of testCaseSidecarPreflightErrors(filePath, tomlData)) {
-                    preflightValidationErrors.push(`  ${message}`);
-                }
-            }
-            if (preflightValidationErrors.length > 0) {
-                throw new Error(`Aborting push: ${preflightValidationErrors.length} TOML validation error(s) — no changes were applied.\n` +
-                    preflightValidationErrors.join("\n"));
-            }
             // Fetch the current remote config vars up-front — before ANY mutation
             // (issue #1423 review pass 3). `planVarsPush` needs this snapshot both
             // to detect concurrent remote edits and to decide which already-absent
@@ -8194,6 +9587,9 @@ export function registerConfigSyncCommands(sync) {
                         upserts: varPlan.upserts.filter((u) => wanted.has(u.key)),
                         deletions: varPlan.deletions.filter((k) => wanted.has(k)),
                         conflicts: varPlan.conflicts.filter((c) => wanted.has(c.key)),
+                        // A drifted var nobody selected is not this push's business to
+                        // report, the same way its writes are not this push's to make.
+                        drifted: varPlan.drifted.filter((d) => wanted.has(d.key)),
                         skippedCount: 0,
                     };
                 }
@@ -8486,6 +9882,13 @@ export function registerConfigSyncCommands(sync) {
                         localModifiedAt: c.localModifiedAt,
                     });
                 }
+                // …and var drift into the shared drift accumulator (#3714), so a var
+                // only the server moved prints the `DRIFT var: KEY` row every other
+                // type prints for that shape. It is not a failure: nothing was
+                // written and neither the exit code nor the pushed count moves.
+                for (const d of varPlan.drifted) {
+                    drifted.push({ type: "var", key: d.key });
+                }
                 // Delete removed keys BEFORE upserting new ones (issue #1423 review
                 // pass 3). At the server's 100-var cap, a replacement (remove one key,
                 // add another) is a valid final state, but upserting the new key first
@@ -9766,8 +11169,14 @@ export function registerConfigSyncCommands(sync) {
             }
             // Process prompts
             const promptsDir = join(configDir, "prompts");
-            if (existsSync(promptsDir)) {
-                const files = selectFiles("prompt", promptsDir, readdirSync(promptsDir).filter((f) => f.endsWith(".toml")));
+            // #3798 — the prompt leg as one function, called twice. `config push`
+            // applies prompts BEFORE server functions, and an agent's tools name
+            // functions the server must hold when the agent is created, so a tree
+            // that pushes an agent together with its tool functions would be
+            // refused on its first push. Chat and decisions files keep their place;
+            // agent files are applied after the server-functions leg below
+            // (`deferredAgentPromptFiles`). Nothing inside the leg changed.
+            const pushPromptFiles = async (files) => {
                 // #2869 — prompts join the live-state reconcile (#2731 B3). #2748
                 // gave the type diff's comparator and left push on the manifest byte
                 // hash, so the two commands answered "changed?" from different
@@ -9788,13 +11197,26 @@ export function registerConfigSyncCommands(sync) {
                 // manifest byte-hash gate with the type named, like every other
                 // converted type.
                 const livePromptIds = new Map();
+                // #3626, CR3626-001 — the KIND the server holds for each prompt,
+                // taken from the same list. `kind` is immutable after create
+                // (D3626-008), and the comparison gate refuses a change to it — but
+                // only on the paths that reach that gate. This map is what the other
+                // two read: a prompt whose DETAIL read failed (degraded to the
+                // byte-hash gate, which `--force` writes through) and a prompt
+                // adopted by key after a 409 (which re-issues the file as an UPDATE
+                // without ever comparing). Both would otherwise PATCH the prompt's
+                // schemas, access rule and metadata onto a row of the other kind
+                // before a config was refused against the kind that did not change.
+                const livePromptKinds = new Map();
                 let promptsLiveOk = true;
                 if (files.length > 0) {
                     try {
                         const listed = await fetchAll((p) => client.listPrompts(resolvedAppId, p));
                         for (const p of listed) {
-                            if (p?.promptKey)
-                                livePromptIds.set(p.promptKey, p.promptId);
+                            if (!p?.promptKey)
+                                continue;
+                            livePromptIds.set(p.promptKey, p.promptId);
+                            livePromptKinds.set(p.promptKey, promptKindOf(p));
                         }
                     }
                     catch (err) {
@@ -9957,6 +11379,79 @@ export function registerConfigSyncCommands(sync) {
                     // (mirrors `applyWorkflowUpdate`). The adopt branch seeds the
                     // sync-state entity record before calling this so the stamp lands.
                     const applyPromptUpdate = async (promptId, expectedModifiedAt) => {
+                        // #3799 (CSO-3799-005) — an agent's declaration is checked against
+                        // every config the server holds non-archived, so a file that
+                        // retires a config AND declares a schema that config's provider
+                        // cannot carry must retire it first: sent the other way round,
+                        // the prompt PATCH is refused for a config the file has already
+                        // archived, and no re-run changes the order. Only the entries
+                        // the file archives and the server does not yet — every other
+                        // config update still follows the prompt, and decisions prompts
+                        // keep their sequence. A config PATCH does not move the
+                        // prompt's `modifiedAt`, so the concurrency guard below still
+                        // holds.
+                        //
+                        // #3801 (DSO-3801-001) — the same staging, with a second admission
+                        // rule. The admin API refuses clearing a CHAT prompt's
+                        // `[prompt].outputSchema` while a config it holds non-archived is
+                        // strict, so a file that clears the schema AND turns strict output
+                        // off (or retires the config) would be refused on every push if the
+                        // prompt went first. Those config updates go ahead of the prompt
+                        // PATCH, with the payload they would have been sent anyway. The
+                        // read this needs is the one the name→id mapping below makes,
+                        // moved ahead of the PATCH, so the request count does not grow.
+                        const stagedFirst = new Set();
+                        const fileKind = promptKindOf(tomlData?.prompt);
+                        const retiring = configs.filter((c) => c?.name &&
+                            String(c?.status ?? "").trim().toLowerCase() === "archived");
+                        const stagesRetiringAgent = fileKind === "agent" && retiring.length > 0;
+                        const clearsPromptSchema = fileKind === "chat" &&
+                            !declaresSchema(tomlData?.prompt?.outputSchema);
+                        const current = stagesRetiringAgent || clearsPromptSchema
+                            ? await client.getPrompt(resolvedAppId, promptId)
+                            : null;
+                        const liveServerConfig = (name) => {
+                            const found = (current?.configs ?? []).find((c) => c.configName === name);
+                            return found && String(found.status ?? "active") !== "archived"
+                                ? found
+                                : null;
+                        };
+                        const staged = [];
+                        if (stagesRetiringAgent) {
+                            for (const tomlConfig of retiring) {
+                                const serverConfig = liveServerConfig(tomlConfig.name);
+                                if (serverConfig)
+                                    staged.push({ tomlConfig, serverConfig });
+                            }
+                        }
+                        if (clearsPromptSchema && declaresSchema(current?.outputSchema)) {
+                            for (const tomlConfig of configs) {
+                                if (!tomlConfig?.name)
+                                    continue;
+                                const serverConfig = liveServerConfig(tomlConfig.name);
+                                if (!serverConfig || serverConfig.strictOutput !== true)
+                                    continue;
+                                const chat = hoistDeprecatedChatKeys(tomlConfig).entry.chat ?? {};
+                                const retired = String(tomlConfig?.status ?? "").trim().toLowerCase() ===
+                                    "archived";
+                                // An entry that stays strict AND live is refused in preflight
+                                // (no schema to send); it is never staged.
+                                if (chat.strictOutput === true && !retired)
+                                    continue;
+                                staged.push({ tomlConfig, serverConfig });
+                            }
+                        }
+                        for (const { tomlConfig, serverConfig } of staged) {
+                            if (stagedFirst.has(tomlConfig.name))
+                                continue;
+                            try {
+                                await client.updatePromptConfig(resolvedAppId, promptId, serverConfig.configId, buildPromptConfigPayload(tomlConfig, { mode: "update" }));
+                            }
+                            catch (err) {
+                                throw wrapPromptConfigError(err, "update", key, tomlConfig.name);
+                            }
+                            stagedFirst.add(tomlConfig.name);
+                        }
                         const updated = await client.updatePrompt(resolvedAppId, promptId, buildPromptPushPayload(key, tomlData, { mode: "update" }), expectedModifiedAt);
                         info(`  Updated prompt: ${key}`);
                         // Record the `modifiedAt` this PATCH just caused, so a later
@@ -9979,7 +11474,10 @@ export function registerConfigSyncCommands(sync) {
                         try {
                             // Fetch full prompt to get config name→ID mappings
                             // (updatePrompt response doesn't include configs)
-                            const fullPrompt = await client.getPrompt(resolvedAppId, promptId);
+                            // #3801 — the read made ahead of the prompt PATCH when the
+                            // staging needed it (neither the PATCH nor a staged config
+                            // update moves a config's id or the activation).
+                            const fullPrompt = current ?? (await client.getPrompt(resolvedAppId, promptId));
                             if (fullPrompt?.configs) {
                                 for (const config of fullPrompt.configs) {
                                     promptConfigNameToId.set(`${key}#${config.configName}`, config.configId);
@@ -9993,6 +11491,10 @@ export function registerConfigSyncCommands(sync) {
                                         continue;
                                     const serverConfig = fullPrompt.configs.find((c) => c.configName === configName);
                                     if (serverConfig) {
+                                        // Staged ahead of the prompt PATCH, with this same
+                                        // payload (#3799 CSO-3799-005, #3801 DSO-3801-001).
+                                        if (stagedFirst.has(configName))
+                                            continue;
                                         // Update existing config
                                         try {
                                             await client.updatePromptConfig(resolvedAppId, promptId, serverConfig.configId, buildPromptConfigPayload(tomlConfig, { mode: "update" }));
@@ -10013,6 +11515,9 @@ export function registerConfigSyncCommands(sync) {
                                         }
                                         if (newConfig?.configId) {
                                             promptConfigNameToId.set(`${key}#${configName}`, newConfig.configId);
+                                            // #3799 — the create body carried the entry's own
+                                            // `status`, so there is no follow-up patch (#3201's is
+                                            // retired).
                                         }
                                     }
                                 }
@@ -10105,6 +11610,18 @@ export function registerConfigSyncCommands(sync) {
                         }
                     };
                     if (existingId) {
+                        // #3626, CR3626-001 — the kind, before anything is written. The
+                        // comparison gate above already refuses a changed `kind`, but it
+                        // only ran when the DETAIL read succeeded; a prompt degraded to
+                        // the byte-hash gate reaches this line with `--force` and no
+                        // comparison at all. The list's kind is enough to answer it, and
+                        // answering it here keeps the promise the gate makes: a kind
+                        // change is declined before the first mutating call.
+                        const degradedKindDecline = promptKindImmutableOutcome(livePrompt ? promptKindOf(livePrompt) : livePromptKinds.get(key), tomlData);
+                        if (degradedKindDecline) {
+                            recordDeclined("prompt", key, degradedKindDecline, existingEntry?.modifiedAt);
+                            continue;
+                        }
                         // Update existing prompt
                         changes.push({ type: "prompt", action: "update", key });
                         promptKeyToId.set(key, existingId);
@@ -10197,6 +11714,19 @@ export function registerConfigSyncCommands(sync) {
                                 });
                                 adopted = true;
                                 const adoptedId = existing.promptId;
+                                // #3626, CR3626-001 — the adopted prompt's KIND, before the
+                                // re-issue writes anything. This path never reaches the
+                                // comparison gate (the create is what failed), so without
+                                // this an orphaned chat prompt would take a decisions file's
+                                // schemas, access rule and metadata by PATCH and only then
+                                // refuse its configs against the kind the update cannot
+                                // change. The lookup already read the record, so the answer
+                                // costs nothing.
+                                const adoptKindDecline = promptKindImmutableOutcome(promptKindOf(existing), tomlData);
+                                if (adoptKindDecline) {
+                                    recordDeclined("prompt", key, adoptKindDecline);
+                                    continue;
+                                }
                                 // Seed the sync-state entity record so the shared update body
                                 // can stamp modifiedAt/contentHash into it (sync state has no
                                 // entry for an orphaned prompt), and track the key→ID map.
@@ -10321,8 +11851,11 @@ export function registerConfigSyncCommands(sync) {
                                             throw wrapPromptConfigError(err, "create", key, extraName);
                                         }
                                         if (extraCreated?.configId) {
-                                            const configName = extraName;
-                                            promptConfigNameToId.set(`${key}#${configName}`, extraCreated.configId);
+                                            promptConfigNameToId.set(`${key}#${extraName}`, extraCreated.configId);
+                                            // #3799 — as on the update path: the create carried the
+                                            // entry's `status`, so a retired entry is retired when
+                                            // it is created and the fresh environment never runs a
+                                            // config the file retired.
                                         }
                                     }
                                     info(`    Created ${configs.length - 1} additional config(s) for prompt: ${key}`);
@@ -10354,6 +11887,17 @@ export function registerConfigSyncCommands(sync) {
                                         activated = true;
                                     }
                                 }
+                                // #3799 (DSO-3799-005) — the seeded config's `status` is in
+                                // the create body (`POST /prompts` honors it now), so #3201's
+                                // trailing patch is gone. Activation still runs after every
+                                // create (#2645), so the marked entry is what the prompt ends
+                                // up serving; when the FIRST entry is the retired one, the
+                                // seeded config the prompt points at is created archived and
+                                // the activation moves the pointer off it. A push that dies
+                                // between the two leaves a prompt pointing at an archived
+                                // config — recovered by re-running the push, and the price of
+                                // never creating a config in a state the file did not ask for
+                                // (which is what an agent's schema check fires on).
                                 // Stamp sync state ONLY after all create work (base prompt +
                                 // every extra config) succeeded. If an extra-config create
                                 // above threw, we never reach here, so the file hash is not
@@ -10389,6 +11933,13 @@ export function registerConfigSyncCommands(sync) {
                         }
                     }
                 }
+            };
+            let deferredAgentPromptFiles = [];
+            if (existsSync(promptsDir)) {
+                const files = selectFiles("prompt", promptsDir, readdirSync(promptsDir).filter((f) => f.endsWith(".toml")));
+                const ordered = partitionPromptFilesForPush(promptsDir, files);
+                deferredAgentPromptFiles = ordered.afterFunctions;
+                await pushPromptFiles(ordered.beforeFunctions);
             }
             // Process transforms (Rhai scripts) — issue #892, slice 7 of #783.
             //
@@ -12039,7 +13590,7 @@ export function registerConfigSyncCommands(sync) {
                                     //
                                     // But the 409 also fires when the local sync state is merely
                                     // ABSENT for a type that another admin has already FULLY
-                                    // configured (or whose `.primitive-sync.json` was not copied
+                                    // configured (or whose sync-state baseline was not copied
                                     // alongside the TOML). PATCHing that without
                                     // `expectedModifiedAt` would silently overwrite the existing
                                     // triggers/access/schema with the local TOML — with no
@@ -12483,6 +14034,393 @@ export function registerConfigSyncCommands(sync) {
                     }
                 }
             }
+            // Process server functions — #3179.
+            //
+            // A function pushes on TWO axes and they are deliberately independent:
+            //
+            //   - the HEADER (`[function]`'s gate, schemas, plus the three
+            //     version-carried keys, all compared through the shared gate), and
+            //   - the CODE — the authored TOML bytes, every source file and the
+            //     built bundle, sent as one immutable config VERSION.
+            //
+            // Independent because a comment-only edit to a source file leaves the
+            // header identical and must still make a version (F-003): gating the
+            // code push on the header comparison would silently discard it. The
+            // code axis compares `envelopeHash`, which is also what the SERVER
+            // dedupes on, so an unchanged push makes no version on either side's
+            // reckoning.
+            //
+            // The bundle is built FIRST, so a build error, a missing entry or an
+            // import that escapes the config tree aborts this function before
+            // anything is sent for it (behavior 12).
+            const functionsPushDir = join(configDir, "functions");
+            if (existsSync(functionsPushDir)) {
+                // #3182 — the typed handle. Written BEFORE the bundles are built, so
+                // an author who runs `config push` after editing a schema gets the
+                // declaration their next edit is typed against, and written from the
+                // TREE rather than from the server: the types describe the schemas
+                // this push is applying. Regenerated every time and never part of the
+                // envelope — `config pull` recreates them the same way.
+                // #3281 — a malformed schema in a function file cannot be typed;
+                // the file's own push below refuses it by name, so the generators
+                // warn here and the rest of the tree still lands.
+                try {
+                    if (!options.dryRun) {
+                        const artifacts = writeFunctionTypeArtifacts(configDir);
+                        if (artifacts.length > 0) {
+                            info(`  Wrote function types: ${artifacts.join(", ")}`);
+                        }
+                    }
+                    // A tsconfig push will not rewrite (comments are the author's) or
+                    // cannot read is still a tsconfig no compiler loads the handle
+                    // through. Say so rather than report success over it (CR3182-003).
+                    for (const problem of functionTypeWiringProblems(configDir)) {
+                        warn(`  functions/tsconfig.json: ${problem}`);
+                    }
+                }
+                catch (err) {
+                    if (!(err instanceof FunctionSchemaCodegenError))
+                        throw err;
+                    warn(`  Function types not generated: ${err.message}`);
+                }
+                // #3331 — the compiler, over the declarations written (or, under
+                // `--dry-run`, planned) just above. Built once for the tree and
+                // consulted per function, so one broken file refuses itself and
+                // nothing else; `--no-typecheck` is the escape hatch, and an
+                // unavailable compiler warns rather than failing the push.
+                let typecheckSetup = null;
+                const functionTypechecker = () => {
+                    if (options.typecheck === false)
+                        return null;
+                    if (typecheckSetup === null) {
+                        typecheckSetup = createFunctionTypechecker(configDir);
+                        for (const warning of typecheckSetup.warnings)
+                            warn(`  ${warning}`);
+                    }
+                    return typecheckSetup.checker;
+                };
+                const files = selectFiles("function", functionsPushDir, readdirSync(functionsPushDir).filter(isFunctionDeclarationFile));
+                const functionSpec = configDiffSpec("function");
+                const liveFunctions = new Map();
+                let functionsLiveOk = true;
+                if (files.length > 0) {
+                    try {
+                        const listed = await client.listFunctions(resolvedAppId);
+                        for (const f of (listed?.items ?? [])) {
+                            if (f?.functionKey)
+                                liveFunctions.set(f.functionKey, f);
+                        }
+                    }
+                    catch (err) {
+                        functionsLiveOk = false;
+                        warnLiveUnavailable("functions", err);
+                    }
+                }
+                /** The version a function currently runs, or null. */
+                const liveActiveVersion = async (functionId, activeConfigId) => {
+                    if (!activeConfigId)
+                        return null;
+                    // #3462 — the point read: one call by id, and correct for a
+                    // rolled-back function whose active version is past page one.
+                    return client.getFunctionConfig(resolvedAppId, functionId, String(activeConfigId));
+                };
+                // #3455 — the tree's document schema is a property of the PROJECT,
+                // not of one function, so an unusable `models/models.toml` is said
+                // once rather than repeated for every function in the tree.
+                const documentSchemaResolution = resolveDocumentSchema(configDir);
+                const documentSchemaWarning = documentSchemaResolution.warning;
+                let documentSchemaWarningShown = false;
+                // Say ONCE that this push drops a document schema a running
+                // version carries — and ask the NEXT function when this one's
+                // version had nothing to lose, so a schema-less function pushed
+                // first cannot silence a schema-bearing sibling. The rule and its
+                // state live in `function-sync.ts`, where they are testable
+                // without a tree and a server.
+                const warnIfDroppingDocumentSchema = createDocumentSchemaDropWarner({
+                    treeCarriesSchema: documentSchemaResolution.origin !== "none",
+                    readConfig: (functionId, configId) => client.getFunctionConfig(resolvedAppId, functionId, configId),
+                    warn: (message) => warn(`  ${message}`),
+                });
+                for (const file of files) {
+                    const filePath = join(functionsPushDir, file);
+                    const tomlData = parseTomlFile(filePath);
+                    const key = tomlData.function?.key || basename(file, ".toml");
+                    withDerivedIdentity(tomlData, "function", { key });
+                    const existingEntry = syncState?.entities?.functions?.[key];
+                    const liveFunction = liveFunctions.get(key);
+                    // Build first: nothing is sent for a function whose code does not
+                    // compile or whose imports leave the tree.
+                    let push;
+                    try {
+                        push = await buildFunctionConfigPush({
+                            configDir,
+                            functionKey: key,
+                            filePath,
+                            tomlData,
+                        });
+                    }
+                    catch (err) {
+                        if (!(err instanceof FunctionBuildError))
+                            throw err;
+                        applyFailures.push({
+                            type: "function",
+                            key,
+                            message: err.message,
+                        });
+                        continue;
+                    }
+                    // #3455 (D3455-004) — the project declares a document schema this
+                    // push cannot carry: over the cap, or not parsing. VISIBLE rather
+                    // than refused, because a broken `models/models.toml` is not a
+                    // reason to stop deploying code — but silence would leave an
+                    // author wondering why a first write still cannot seed.
+                    if (documentSchemaWarning && !documentSchemaWarningShown) {
+                        documentSchemaWarningShown = true;
+                        warn(`  ${documentSchemaWarning}`);
+                    }
+                    // #3331 — and then the types. esbuild erases them, so a build that
+                    // succeeded says nothing about whether the code holds against the
+                    // declarations this same push generated: `ctx.user` going nullable
+                    // (#3279) bundles cleanly and throws on the request path. Refused
+                    // here, against THIS function's own sources, before anything is
+                    // sent for it and whether or not this is a dry run.
+                    const typechecker = functionTypechecker();
+                    if (typechecker) {
+                        const failure = typechecker.check(key, push.sources.map((source) => source.path));
+                        if (failure) {
+                            applyFailures.push({
+                                type: "function",
+                                key,
+                                message: failure.message,
+                            });
+                            continue;
+                        }
+                    }
+                    // The active version, needed by BOTH axes: the header comparison
+                    // reads `entry`/`mode`/`limits` off it, and the code axis
+                    // compares its `envelopeHash`.
+                    let activeVersion = null;
+                    let versionOk = functionsLiveOk;
+                    if (functionsLiveOk && liveFunction?.functionId) {
+                        try {
+                            activeVersion = await liveActiveVersion(liveFunction.functionId, liveFunction.activeConfigId);
+                        }
+                        catch (err) {
+                            versionOk = false;
+                            warnLiveUnavailable(`function ${key}`, err);
+                        }
+                    }
+                    let headerAction = "skip";
+                    if (versionOk && functionsLiveOk) {
+                        const gate = decidePushForConfig({
+                            spec: functionSpec,
+                            maps: pushDiffMaps,
+                            localParsed: tomlData,
+                            live: liveFunction
+                                ? {
+                                    record: liveFunction,
+                                    // The version-carried keys the remote side is projected
+                                    // through; the header row does not hold them.
+                                    extra: activeVersion ?? undefined,
+                                    modifiedAt: liveFunction.modifiedAt,
+                                }
+                                : null,
+                            entry: existingEntry,
+                            localFileHash: computeFileHash(filePath),
+                            force: options.force,
+                            // #3317 — the header row's `modifiedAt` covers everything
+                            // compared here: its own fields, and the `activeConfigId`
+                            // pointer whose repointing is the only way the immutable
+                            // version behind the extras can change. So an unmoved
+                            // timestamp proves the server stood still, and a baseline hash
+                            // that disagrees is a stale baseline — the reporter's CONFLICT
+                            // over two identical timestamps, which is also what every
+                            // manifest written before this issue's schema fix would hit.
+                            serverModifiedAtCoversProjection: true,
+                            // The create leg adopts by key on the server's 409 (#1006), so
+                            // an untracked function the server already holds is that same
+                            // adopt reached one step earlier.
+                            adoptsUntrackedByKey: true,
+                        });
+                        if (gate.action === "drift" ||
+                            gate.action === "conflict" ||
+                            gate.action === "immutable") {
+                            recordDeclined("function", key, gate, existingEntry?.modifiedAt);
+                            continue;
+                        }
+                        headerAction = gate.action === "skip"
+                            ? "skip"
+                            : liveFunction
+                                ? "update"
+                                : "create";
+                    }
+                    else {
+                        const degraded = decideDegradedPush({
+                            force: options.force,
+                            storedContentHash: existingEntry?.contentHash,
+                            currentFileHash: computeFileHash(filePath),
+                        });
+                        if (degraded.action === "decline") {
+                            recordDeclined("function", key, { action: "live-unavailable" }, existingEntry?.modifiedAt);
+                            continue;
+                        }
+                        headerAction = degraded.action === "skip"
+                            ? "skip"
+                            : liveFunction
+                                ? "update"
+                                : "create";
+                    }
+                    // The code axis. `envelopeHash` is the server's own no-op test, so
+                    // matching it here means the call would create nothing.
+                    const codeUnchanged = !!liveFunction &&
+                        !!activeVersion &&
+                        String(activeVersion.envelopeHash ?? "") === push.envelopeHash;
+                    if (headerAction === "skip" && codeUnchanged) {
+                        skippedCount++;
+                        if (syncState && liveFunction?.functionId) {
+                            if (!syncState.entities.functions)
+                                syncState.entities.functions = {};
+                            syncState.entities.functions[key] = {
+                                ...(existingEntry ?? {}),
+                                id: liveFunction.functionId,
+                                modifiedAt: liveFunction.modifiedAt ||
+                                    existingEntry?.modifiedAt ||
+                                    new Date().toISOString(),
+                                contentHash: computeFileHash(filePath),
+                                semanticHash: hashRemoteConfigForDiff(functionSpec, liveFunction, pushDiffMaps, activeVersion ?? undefined),
+                                envelopeHash: push.envelopeHash,
+                                activeConfigId: activeVersion?.configId,
+                                sources: push.sources.map((src) => src.path),
+                            };
+                        }
+                        continue;
+                    }
+                    changes.push({
+                        type: "function",
+                        action: liveFunction ? "update" : "create",
+                        key,
+                    });
+                    if (options.dryRun)
+                        continue;
+                    // Every server refusal below is recorded against THIS function and
+                    // the loop moves on. A single archived tombstone — or a key the
+                    // app's namespace already holds — must not abort a push carrying
+                    // unrelated changes: the run reports what it could not apply, exits
+                    // non-zero, and everything else in the tree still lands. That is
+                    // the same contract `applyFailures` gives every other type; a throw
+                    // here would let one refusal block a whole repository.
+                    let functionId = liveFunction?.functionId ?? existingEntry?.id;
+                    let pushedVersion;
+                    try {
+                        if (!functionId) {
+                            // #3835 — a create the server could not confirm in storage
+                            // (`STORAGE_CONSISTENCY_PENDING`) is asked again, not recorded
+                            // as not applied. Its row keeps the key, so a retry that meets
+                            // it as a 409 is adopted below like any other held key.
+                            const created = await retryOnStoragePending(() => client.createFunction(resolvedAppId, buildFunctionCreatePayload(key, tomlData.function ?? {}))).catch(async (err) => {
+                                // #1006 — a function the server already holds under this key
+                                // is adopted rather than re-created. The conflict may name a
+                                // WORKFLOW, a script or a webhook instead: those are the
+                                // single key namespace refusing the key, and they are not
+                                // adoptable, so `adoptByKeyOnCreate409` re-throws the original
+                                // error with its holder named.
+                                const existing = await adoptByKeyOnCreate409({
+                                    err,
+                                    kind: "function",
+                                    key,
+                                    lookup: async () => (await client.listFunctions(resolvedAppId)).items || [],
+                                    matchKey: (f) => f?.functionKey === key,
+                                });
+                                return existing;
+                            });
+                            functionId = created.functionId;
+                            info(`  Created function: ${key}`);
+                        }
+                        else if (headerAction !== "skip") {
+                            const updatePayload = buildFunctionUpdatePayload(tomlData.function ?? {});
+                            if (Object.keys(updatePayload).length > 0) {
+                                await client.updateFunction(resolvedAppId, functionId, updatePayload);
+                            }
+                            info(`  Updated function: ${key}`);
+                        }
+                        // The version. `status` is NEVER in this body: pushing code to a
+                        // disabled function updates it and leaves it out of service
+                        // (#2803's resurrection guard), and a push to an archived one is
+                        // refused by the server with the archived-holder message — which
+                        // names the remedies that release its key.
+                        pushedVersion = await client.pushFunctionConfig(resolvedAppId, String(functionId), push);
+                    }
+                    catch (err) {
+                        applyFailures.push({
+                            type: "function",
+                            key,
+                            message: String(err?.message ?? err),
+                        });
+                        continue;
+                    }
+                    // #3455 (D3455-010) — did the server keep the document schema it
+                    // was sent? A server that predates the field drops it silently and
+                    // still answers 200, so without this the push reports success over
+                    // a version that can never seed. Recorded against THIS function and
+                    // NOT reported pushed; the rest of the tree still lands.
+                    const retention = documentSchemaRetentionFailure({
+                        sentDocumentSchema: typeof push.documentSchema === "string",
+                        builtEnvelopeHash: push.envelopeHash,
+                        storedEnvelopeHash: pushedVersion?.envelopeHash,
+                    });
+                    if (retention) {
+                        applyFailures.push({ type: "function", key, message: retention });
+                        continue;
+                    }
+                    await warnIfDroppingDocumentSchema(String(functionId), liveFunction?.activeConfigId
+                        ? String(liveFunction.activeConfigId)
+                        : undefined);
+                    if (pushedVersion?.created === false) {
+                        info(`  Function ${key}: code unchanged (no new version)`);
+                    }
+                    else {
+                        info(`  Pushed function ${key} version ${pushedVersion?.configId ?? ""}`.trim());
+                    }
+                    if (syncState) {
+                        if (!syncState.entities.functions)
+                            syncState.entities.functions = {};
+                        let refreshed = liveFunction;
+                        try {
+                            refreshed = await client.getFunction(resolvedAppId, String(functionId));
+                        }
+                        catch {
+                            // Non-fatal: the baseline falls back to what the listing said.
+                            // The next push reconciles it.
+                        }
+                        // #3317 — the pointer recorded is the one THIS push activated,
+                        // whatever the refetch found: a concurrent activation in the
+                        // window between the two is a server move the next push must
+                        // refuse over, not a baseline it silently rolls back.
+                        const baseline = pushedFunctionBaseline({
+                            functionId: String(functionId),
+                            refreshed,
+                            existingModifiedAt: existingEntry?.modifiedAt,
+                            contentHash: computeFileHash(filePath),
+                            pushedVersion,
+                            envelopeHash: push.envelopeHash,
+                            sources: push.sources.map((src) => src.path),
+                            spec: functionSpec,
+                            maps: pushDiffMaps,
+                        });
+                        if (baseline.movedTo) {
+                            warn(`  Function ${key}: the server's active version moved to ${baseline.movedTo} ` +
+                                `while version ${pushedVersion?.configId} was being recorded; ` +
+                                "the next push will report the drift (`config pull` adopts it, `--force` overrides it).");
+                        }
+                        syncState.entities.functions[key] = baseline.entity;
+                    }
+                }
+            }
+            // #3798 — the agent prompts, now that every function they name that
+            // this push applies is on the server (see `pushPromptFiles`).
+            if (deferredAgentPromptFiles.length > 0) {
+                await pushPromptFiles(deferredAgentPromptFiles);
+            }
             // Process group type configs
             const groupTypeConfigsDir = join(configDir, "group-type-configs");
             if (existsSync(groupTypeConfigsDir)) {
@@ -12664,7 +14602,7 @@ export function registerConfigSyncCommands(sync) {
                                 // this, that CREATE re-hits the server's 409 "Config for this
                                 // group type already exists"
                                 // (group-type-config-controller.ts) on every subsequent push
-                                // and the operator has to hand-edit `.primitive-sync.json` to
+                                // and the operator has to hand-edit the sync-state baseline to
                                 // recover. The shared helper detects the conflict (409 status /
                                 // "already exists" message), lists the app's configs — the list
                                 // route drains every page server-side (#1668), so the candidate
@@ -13798,21 +15736,14 @@ export function registerConfigSyncCommands(sync) {
     // Diff
     sync
         .command("diff")
+        .allowExcessArguments(false)
         .description("Show differences between local and remote configuration")
-        .argument("[app-id]", "App ID (uses current app if not specified)")
-        .option("--app <app-id>", "App ID")
-        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
         .option("--only <selectors>", "Compare just these objects: <type>/<key>, app, or var/<key> (repeatable, or comma-separated).", (value, previous) => [...(previous ?? []), value], [])
-        .option("--json", "Output as JSON (app.toml field diff, with --only app)")
-        .action(async (appId, options) => {
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-            const legacyHint = checkLegacySyncMigration(configDir);
-            if (legacyHint)
-                warn(legacyHint);
-        }
+        .option("--json", "Output as JSON: the app.toml field diff with --only app, the compared rows otherwise")
+        .action(async (options) => {
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
+        info(`Using per-environment config directory: ${configDir}`);
         // Issue #2760: diff compares the renamed directory, so a legacy one is
         // simply invisible — an empty diff would otherwise read as "in sync".
         const legacyDbTypes = checkLegacyDatabaseTypesDir(configDir);
@@ -13860,7 +15791,7 @@ export function registerConfigSyncCommands(sync) {
                 notCompared.push({ type: label, reason: gateReason(outcome.error) });
                 return empty;
             };
-            const [integrationsOutcome, promptsOutcome, workflowsOutcome, emailTemplatesOutcomeDiff, webhooksOutcome, cronTriggersOutcomeDiff, blobBucketsOutcomeDiff, scriptsOutcomeDiff, varsOutcomeDiff, databaseTypeConfigsOutcomeDiff, ruleSetsOutcomeDiff, groupTypeConfigsOutcomeDiff, collectionTypeConfigsOutcomeDiff, metadataCategoryConfigsOutcomeDiff,] = await Promise.all([
+            const [integrationsOutcome, promptsOutcome, workflowsOutcome, emailTemplatesOutcomeDiff, webhooksOutcome, cronTriggersOutcomeDiff, blobBucketsOutcomeDiff, scriptsOutcomeDiff, functionsOutcomeDiff, varsOutcomeDiff, databaseTypeConfigsOutcomeDiff, ruleSetsOutcomeDiff, groupTypeConfigsOutcomeDiff, collectionTypeConfigsOutcomeDiff, metadataCategoryConfigsOutcomeDiff,] = await Promise.all([
                 attemptFetch(() => fetchAll((p) => client.listIntegrations(resolvedAppId, p))),
                 attemptFetch(() => fetchAll((p) => client.listPrompts(resolvedAppId, p))),
                 attemptFetch(() => fetchAll((p) => client.listWorkflows(resolvedAppId, p))),
@@ -13869,6 +15800,7 @@ export function registerConfigSyncCommands(sync) {
                 attemptFetch(() => client.listCronTriggers(resolvedAppId)),
                 attemptFetch(() => client.listBlobBuckets(resolvedAppId)),
                 attemptFetch(() => client.listScripts(resolvedAppId)),
+                attemptFetch(() => client.listFunctions(resolvedAppId)),
                 attemptFetch(() => client.listAppConfigVars(resolvedAppId)),
                 attemptFetch(() => client.listDatabaseTypeConfigs(resolvedAppId)),
                 attemptFetch(() => client.listRuleSets(resolvedAppId)),
@@ -13884,6 +15816,7 @@ export function registerConfigSyncCommands(sync) {
             const cronTriggerItemsDiff = gate(cronTriggersOutcomeDiff, "cron-triggers", { items: [] }).items || [];
             const blobBucketsDiffResult = gate(blobBucketsOutcomeDiff, "blob-buckets", { items: [] });
             const scriptItemsDiff = gate(scriptsOutcomeDiff, "transforms", { items: [] }).items || [];
+            const functionItemsDiff = gate(functionsOutcomeDiff, "functions", { items: [] }).items || [];
             const remoteVarItemsDiff = gate(varsOutcomeDiff, "vars", []);
             const databaseTypeConfigsDiff = gate(databaseTypeConfigsOutcomeDiff, "database-type-configs", []);
             const ruleSetsDiff = gate(ruleSetsOutcomeDiff, "rule-sets", []);
@@ -14188,6 +16121,25 @@ export function registerConfigSyncCommands(sync) {
                     localScripts.set(name, readFileSync(join(transformsDirPath, file), "utf-8"));
                 }
             }
+            // Server functions — #3179. Two axes, exactly as push has: the
+            // header/version fields through the shared spec, and the CODE through
+            // `envelopeHash`. The code axis is why a function's diff builds the
+            // bundle: a comment-only edit to a source file changes nothing the
+            // table can see and is still a change push will apply.
+            const remoteFunctions = new Map(functionItemsDiff
+                .filter((f) => f?.functionKey && String(f.status ?? "active") !== "archived")
+                .map((f) => [f.functionKey, f]));
+            const localFunctionsParsed = new Map();
+            const functionsDirPath = join(configDir, "functions");
+            if (functionsOutcomeDiff.ok && existsSync(functionsDirPath)) {
+                for (const file of readdirSync(functionsDirPath).filter(isFunctionDeclarationFile)) {
+                    const filePath = join(functionsDirPath, file);
+                    const tomlData = parseTomlFile(filePath);
+                    const key = tomlData.function?.key || basename(file, ".toml");
+                    withDerivedIdentity(tomlData, "function", { key });
+                    localFunctionsParsed.set(key, { tomlData, filePath });
+                }
+            }
             // Config vars — issue #1423. The remote vars were fetched through the
             // ok/error gate above (`remoteVarItemsDiff`); the local `vars.toml` is
             // read only when that fetch succeeded.
@@ -14451,6 +16403,108 @@ export function registerConfigSyncCommands(sync) {
                     differences.push({ type: "prompt", key, status: remoteOnlyStatus("prompts", key) });
                 }
             }
+            // Server functions — #3179.
+            const functionSpecDiff = configDiffSpec("function");
+            const functionDiffMaps = {
+                ruleSetIdToName: new Map(),
+                ruleSetNameToId: new Map(),
+            };
+            for (const [key, local] of localFunctionsParsed) {
+                const remote = remoteFunctions.get(key);
+                if (!remote) {
+                    differences.push({
+                        type: "function",
+                        key,
+                        status: localOnlyStatus("functions", key),
+                    });
+                    continue;
+                }
+                let status = "exists";
+                let hint;
+                // The active version carries `entry`, `mode` and `limits`, and its
+                // `envelopeHash` is the code axis.
+                const versionOutcome = await attemptFetch(async () => {
+                    if (!remote.activeConfigId)
+                        return null;
+                    // #3462 — the point read, for the same reason as pull's.
+                    return client.getFunctionConfig(resolvedAppId, remote.functionId, String(remote.activeConfigId));
+                });
+                // #3462 — and the newest version, so a tree that matches something
+                // that EXISTS can say so. One row; the listing answers newest first.
+                const newestOutcome = await attemptFetch(async () => {
+                    const page = await client.listFunctionConfigs(resolvedAppId, remote.functionId, { limit: 1 });
+                    return (page.items || [])[0] ?? null;
+                });
+                if (!versionOutcome.ok) {
+                    hint = "content not compared (fetch failed)";
+                }
+                else {
+                    const active = versionOutcome.value;
+                    const verdict = compareLocalToRemote(functionSpecDiff, local.tomlData, remote, functionDiffMaps, active ?? undefined);
+                    status = verdict.status;
+                    hint = verdict.hint;
+                    if (status === "exists") {
+                        // The header agrees; the code is the other half. Building here is
+                        // what makes "config diff is clean immediately after pull" a
+                        // statement about the SOURCES and not just the TOML.
+                        try {
+                            const built = await buildFunctionConfigPush({
+                                configDir,
+                                functionKey: key,
+                                filePath: local.filePath,
+                                tomlData: local.tomlData,
+                            });
+                            if (!active ||
+                                String(active.envelopeHash ?? "") !== built.envelopeHash) {
+                                status = "modified";
+                                // #3462 — when the tree matches the NEWEST version rather
+                                // than the active one, the function is rolled back and the
+                                // generic hint sends an operator looking for an edit they
+                                // never made. Naming both versions says what actually
+                                // happened and what each command would do about it.
+                                const newest = newestOutcome.ok
+                                    ? newestOutcome.value
+                                    : null;
+                                hint =
+                                    active &&
+                                        newest &&
+                                        String(newest.configId) !== String(active.configId) &&
+                                        String(newest.envelopeHash ?? "") === built.envelopeHash
+                                        ? rollbackDiffHint(String(newest.configId), String(active.configId))
+                                        : "the built bundle or a source file differs — `config push` " +
+                                            "creates a new immutable version";
+                            }
+                        }
+                        catch (err) {
+                            if (err instanceof FunctionBuildError) {
+                                // #2880 — the file is not pushable, so the row says so
+                                // rather than reading as Synced. This is the state a
+                                // function created through the API and never pushed lands
+                                // in: pull can only serialize the header, so the file has
+                                // no `entry` and the very next push refuses it. A Synced row
+                                // there tells the operator there is nothing to do about a
+                                // file nothing can apply.
+                                status = VALIDATION_ERROR;
+                                hint = err.message.split("\n")[0];
+                            }
+                            else {
+                                hint = "content not compared (comparison failed)";
+                            }
+                        }
+                    }
+                }
+                hint = outOfServiceHint(remote, hint);
+                differences.push({ type: "function", key, status, hint });
+            }
+            for (const key of remoteFunctions.keys()) {
+                if (!localFunctionsParsed.has(key)) {
+                    differences.push({
+                        type: "function",
+                        key,
+                        status: remoteOnlyStatus("functions", key),
+                    });
+                }
+            }
             // Workflows — #1175: content-aware comparison.
             //
             // For workflows present on BOTH sides we no longer stop at key
@@ -14688,7 +16742,7 @@ export function registerConfigSyncCommands(sync) {
             // below). Content comparison is a preview of `config pull` (pull would
             // rewrite the local TOML to match running state), exactly like the
             // workflow/transform blocks.
-            const compareConfigType = (typeLabel, slot, localParsed, remoteEntities, hashLocal, hashRemote, contentComparable) => {
+            const compareConfigType = (typeLabel, slot, localParsed, remoteEntities, compare, contentComparable) => {
                 for (const [key, parsed] of localParsed) {
                     if (!remoteEntities.has(key)) {
                         differences.push({ type: typeLabel, key, status: localOnlyStatus(slot, key) });
@@ -14703,16 +16757,10 @@ export function registerConfigSyncCommands(sync) {
                         hint = "content not compared (rule sets unavailable)";
                     }
                     else {
-                        try {
-                            if (hashLocal(parsed) !== hashRemote(remoteEntities.get(key))) {
-                                status = "modified";
-                                hint = "run `config pull` to rewrite the local TOML to match running state";
-                            }
-                        }
-                        catch {
-                            // A malformed local file must not abort the whole diff.
-                            hint = "content not compared (comparison failed)";
-                        }
+                        // The shared verdict names the differing field (#3267) and
+                        // degrades a malformed local file to "not compared" rather than
+                        // aborting the whole diff.
+                        ({ status, hint } = compare(parsed, remoteEntities.get(key)));
                     }
                     differences.push({ type: typeLabel, key, status, hint });
                 }
@@ -14731,7 +16779,7 @@ export function registerConfigSyncCommands(sync) {
             };
             const compareByDefinition = (label, slot, localParsed, remoteEntities, contentComparable) => {
                 const spec = configDiffSpec(label);
-                compareConfigType(label, slot, localParsed, remoteEntities, (p) => hashLocalConfigForDiff(spec, p, diffMaps), (e) => hashRemoteConfigForDiff(spec, e, diffMaps), contentComparable);
+                compareConfigType(label, slot, localParsed, remoteEntities, (p, e) => compareLocalToRemote(spec, p, e, diffMaps), contentComparable);
             };
             compareByDefinition("rule-set", "ruleSets", localRuleSetsParsed, remoteRuleSets, true);
             compareByDefinition("group-type-config", "groupTypeConfigs", localGroupTypeConfigsParsed, remoteGroupTypeConfigs, ruleSetsOk);
@@ -14763,20 +16811,14 @@ export function registerConfigSyncCommands(sync) {
                         hint = "content not compared (fetch failed)";
                     }
                     else {
-                        try {
-                            const operations = Array.isArray(opsOutcome.value) ? opsOutcome.value : [];
-                            const subscriptions = Array.isArray(subsOutcome.value) ? subsOutcome.value : [];
-                            const dbSpec = configDiffSpec("database-type-config");
-                            const remoteHash = hashRemoteConfigForDiff(dbSpec, remote, diffMaps, { operations, subscriptions });
-                            const localHash = hashLocalConfigForDiff(dbSpec, parsed, diffMaps);
-                            if (remoteHash !== localHash) {
-                                status = "modified";
-                                hint = "run `config pull` to rewrite the local TOML to match running state";
-                            }
-                        }
-                        catch {
-                            hint = "content not compared (comparison failed)";
-                        }
+                        const operations = Array.isArray(opsOutcome.value) ? opsOutcome.value : [];
+                        const subscriptions = Array.isArray(subsOutcome.value) ? subsOutcome.value : [];
+                        // The shared verdict (#3267): a Modified row names the
+                        // operation, subscription, model field or `[type]` scalar it
+                        // differs in, and a comparison that throws degrades this one
+                        // row to "not compared". The ops/subscriptions are the remote
+                        // side's extra only — the file already carries its own.
+                        ({ status, hint } = compareLocalToRemote(configDiffSpec("database-type-config"), parsed, remote, diffMaps, { operations, subscriptions }));
                     }
                 }
                 differences.push({ type: "database-type-config", key, status, hint });
@@ -14917,7 +16959,23 @@ export function registerConfigSyncCommands(sync) {
             // the same preflight push runs decides these rows, and its message —
             // verbatim, so the two commands read identically — replaces whatever
             // the comparison had to say about the file.
-            for (const rejected of collectConfigFileValidationErrors(configDir)) {
+            // #3320 — the function checks join them. Same posture, same messages:
+            // a function file whose `entry`, mode, triggers or webhook
+            // signing-secret the push preflight refuses is not a row this command
+            // calls Synced, Modified or "local only — new".
+            // Merged first: a file both collectors reject keeps every message push
+            // prints, rather than one collector's hint overwriting the other's.
+            // #3482 — the same advisory `config push` prints, so an author sees
+            // the retired key before they push rather than only during it. Not a
+            // row status: the file is pushable, and saying otherwise would make
+            // `config diff` disagree with the push it predicts.
+            for (const message of collectFunctionTomlIgnoredKeyWarnings(configDir)) {
+                warn(`  ${message}`);
+            }
+            for (const rejected of mergeConfigFileValidationErrors([
+                ...collectConfigFileValidationErrors(configDir),
+                ...collectFunctionTomlValidationErrors(configDir),
+            ])) {
                 const row = differences.find((d) => d.type === rejected.type && d.key === rejected.key);
                 const hint = rejected.messages.join("; ");
                 if (row) {
@@ -14948,6 +17006,22 @@ export function registerConfigSyncCommands(sync) {
                             ? selectionIncludesApp(diffSelection)
                             : selectionIncludesKey(diffSelection, row.type, row.key));
             }
+            // #3320 — `--json` over the whole comparison, not just `--only app`.
+            // The Invalid rows this issue adds have to be readable by the thing
+            // that reads a diff programmatically (an editor, a CI job), and the
+            // flag already existed for the app-settings case; a run that asked for
+            // JSON and got a human table was answering a different question.
+            // Emitted after the `--only` filter so a scoped run reports its scope.
+            if (options.json) {
+                console.log(JSON.stringify({
+                    appId: resolvedAppId,
+                    configDir,
+                    differences,
+                    testCases: testCaseDiffs,
+                    notCompared,
+                }, null, 2));
+                return;
+            }
             divider();
             const localOnly = differences.filter((d) => d.status === LOCAL_ONLY_NEW);
             const localOnlyAbsent = differences.filter((d) => d.status === LOCAL_ONLY_ABSENT);
@@ -15076,6 +17150,41 @@ export function registerConfigSyncCommands(sync) {
                     console.log(`  ${chalk.dim("=")} ${d.blockType}/${d.blockKey} test-case: ${d.slug}${hint}`);
                 }
             }
+            // #3182 — the generated function types are part of what a push would
+            // change, so `config diff` is where their freshness is answered: an
+            // editor or a CI job asks the same command it already asks "what would
+            // push do?", and gets these named alongside everything else.
+            let staleFunctionTypes = [];
+            let wiringProblems = [];
+            try {
+                staleFunctionTypes = staleFunctionTypeArtifacts(configDir);
+                // Freshness is not the only way the handle stops working: a tsconfig
+                // push will not rewrite can be perfectly current and still load none
+                // of it. `config diff` is where CI asks, so it answers both
+                // (CR3182-003).
+                wiringProblems = functionTypeWiringProblems(configDir);
+            }
+            catch (err) {
+                if (!(err instanceof FunctionSchemaCodegenError))
+                    throw err;
+                // #3281 — a function file whose schema cannot be typed is reported
+                // like a wiring problem: the generators cannot answer for the tree.
+                wiringProblems = [err.message];
+            }
+            if (staleFunctionTypes.length > 0) {
+                console.log();
+                info("Function types (regenerated by `config push`):");
+                for (const relative of staleFunctionTypes) {
+                    console.log(`  ${chalk.yellow("~")} ${relative}`);
+                }
+            }
+            if (wiringProblems.length > 0) {
+                console.log();
+                info("Function types (compiler wiring `config push` cannot repair):");
+                for (const problem of wiringProblems) {
+                    console.log(`  ${chalk.yellow("!")} functions/tsconfig.json: ${problem}`);
+                }
+            }
             divider();
             keyValue("Local only (new)", localOnly.length);
             keyValue("Local only (absent from export)", localOnlyAbsent.length);
@@ -15113,22 +17222,18 @@ export function registerConfigSyncCommands(sync) {
     // containing null) fall back to JSON-string per field with a log message.
     sync
         .command("migrate-toml")
+        .allowExcessArguments(false)
         .description("Rewrite database-type and workflow TOML files to native form " +
         "([operations.definition] / [[operations.params]] for database types; " +
         "[workflow.inputSchema] / [workflow.outputSchema] for workflows)")
-        .argument("[app-id]", "App ID (uses current app if not specified)")
-        .option("--app <app-id>", "App ID")
-        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
         .option("--dry-run", "Show what would change without writing files")
-        .action(async (appId, options) => {
-        // Resolve appId so we land in the per-env sync dir even when the user
-        // didn't pass `--dir`. The app ID itself isn't used for any API calls
-        // — `migrate-toml` is a purely local rewrite.
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-        }
+        .action(async (options) => {
+        // The app ID is not used for any API call — `migrate-toml` is a purely
+        // local rewrite — but the environment that names it is what names the
+        // tree being rewritten.
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
+        info(`Using per-environment config directory: ${configDir}`);
         if (!existsSync(configDir)) {
             error(`Config directory not found: ${configDir}`);
             process.exit(1);
@@ -15278,21 +17383,16 @@ export function registerConfigSyncCommands(sync) {
     // proven), so re-running push/pull is unaffected.
     sync
         .command("migrate-v2")
+        .allowExcessArguments(false)
         .description("Convert legacy per-type sync files (prompts/, integrations/, workflows/, transforms/) into the v2 blocks/<type>/<key>/block.toml layout")
-        .argument("[app-id]", "App ID (uses current app if not specified)")
-        .option("--app <app-id>", "App ID")
-        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
         .option("--dry-run", "Show what would change without writing files")
         .option("--force", "Overwrite existing block.toml files instead of skipping them")
-        .action(async (appId, options) => {
-        // Resolve appId so we land in the per-env sync dir even when the user
-        // didn't pass `--dir`. The app ID itself isn't used for any API calls —
-        // migrate-v2 is a purely local rewrite (like migrate-toml).
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-        }
+        .action(async (options) => {
+        // As with migrate-toml: a purely local rewrite, whose tree is the
+        // resolved environment's.
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
+        info(`Using per-environment config directory: ${configDir}`);
         if (!existsSync(configDir)) {
             error(`Config directory not found: ${configDir}`);
             process.exit(1);
@@ -15331,26 +17431,16 @@ export function registerConfigSyncCommands(sync) {
     // Revert — restore a pre-pull snapshot (issue #578, Phase 1).
     sync
         .command("revert")
+        .allowExcessArguments(false)
         .description("Restore the config directory from a snapshot taken before a previous pull")
-        .argument("[app-id]", "App ID (uses current app if not specified)")
-        .option("--app <app-id>", "App ID")
-        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
         .option("--snapshot <id>", "Snapshot id (timestamp dirname or a unique >=8-char prefix)")
         .option("--list", "List available snapshots without restoring")
         .option("-y, --yes", "Skip the confirmation prompt")
-        .action(async (appId, options) => {
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({
-            appId: resolvedAppId,
-            userDir: options.dir,
-        });
-        const snapshotsRoot = resolveSnapshotsRoot({
-            appId: resolvedAppId,
-            userDir: options.dir,
-        });
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-        }
+        .action(async (options) => {
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
+        const snapshotsRoot = resolveSnapshotsRoot({ appId: resolvedAppId });
+        info(`Using per-environment config directory: ${configDir}`);
         const snapshots = listSnapshots(snapshotsRoot);
         // --list, or no snapshots at all: enumerate and stop.
         if (options.list || snapshots.length === 0) {
@@ -15410,15 +17500,13 @@ export function registerConfigSyncCommands(sync) {
             }
         }
         try {
-            // Under legacy `--dir`, snapshotsRoot lives inside configDir; preserve
-            // it across the full-tree swap so we don't wipe backup history.
-            restoreSnapshot(target.path, configDir, { preserveDir: snapshotsRoot });
+            restoreSnapshot(target.path, configDir);
         }
         catch (err) {
             error(`Restore failed: ${err?.message ?? err}`);
             process.exit(1);
         }
-        success(`Restored snapshot ${target.id} into ${configDir} (including .primitive-sync.json).`);
+        success(`Restored snapshot ${target.id} into ${configDir} (including ${SYNC_STATE_FILENAME}).`);
         info("Run 'primitive config diff' to inspect the restored state versus the server.");
     });
 }