primitive-admin 1.1.0-alpha.82 → 1.1.0-alpha.83

package/dist/src/commands/sync.js

@@ -37,7 +37,8 @@ import { buildPayloadFromToml, projectEntityToPayload, projectRecordToToml, toml
 import { CONFIG_SURFACES, isEmptyForEmit, } 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, buildFunctionCreatePayload, buildFunctionUpdatePayload, functionDiffEntity, functionTomlPreflightErrors, planFunctionPull, serializeFunction, } from "../lib/function-sync.js";
+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.
@@ -48,6 +49,9 @@ import { functionTypeWiringProblems, staleFunctionTypeArtifacts, writeFunctionTy
 // #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";
@@ -60,7 +64,7 @@ import { slugifyTestCaseName, testCaseFileBasenames, } from "../lib/test-case-fi
 // 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";
@@ -2185,6 +2189,348 @@ 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;
+            }
+            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}`);
+        }
+    }
+    // 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).
@@ -2206,7 +2552,11 @@ export function collectConfigFileValidationErrors(configDir) {
         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 {
@@ -2264,7 +2614,7 @@ export function collectFunctionTomlValidationErrors(configDir) {
     const functionsDir = join(configDir, "functions");
     if (!existsSync(functionsDir))
         return found;
-    for (const file of readdirSync(functionsDir).filter((f) => f.endsWith(".toml"))) {
+    for (const file of readdirSync(functionsDir).filter(isFunctionDeclarationFile)) {
         const filePath = join(functionsDir, file);
         let tomlData;
         try {
@@ -2287,6 +2637,35 @@ export function collectFunctionTomlValidationErrors(configDir) {
     }
     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).
  *
@@ -4968,6 +5347,8 @@ export async function pullFunctions(client, appId, configDir, logger = () => { }
     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);
@@ -5015,11 +5396,21 @@ export async function pullFunctions(client, appId, configDir, logger = () => { }
         }
         let active;
         let envelope;
+        let newest = null;
         try {
-            const configs = await client.listFunctionConfigs(appId, record.functionId);
-            active = (configs.items || []).find((c) => String(c.configId) === String(record.activeConfigId));
+            // #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 {
@@ -5032,9 +5423,30 @@ export async function pullFunctions(client, appId, configDir, logger = () => { }
             logger(`  Skipped functions/${key}.toml (active version not readable)`);
             continue;
         }
-        const plan = planFunctionPull({ configDir, functionKey: key, envelope });
+        // #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}`);
@@ -5048,11 +5460,34 @@ export async function pullFunctions(client, appId, configDir, logger = () => { }
         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 };
@@ -7949,14 +8384,6 @@ What a push guarantees (two stages):
         // `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);
         /**
@@ -7990,6 +8417,29 @@ What a push guarantees (two stages):
                 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).
@@ -8377,297 +8827,25 @@ What a push guarantees (two stages):
                     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 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, 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)}`);
-                }
-            }
-            // 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)}`);
-                }
-            }
-            // #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((f) => f.endsWith(".toml")));
-                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;
-                    }
-                    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}`);
-                        }
-                    }
-                }
-            }
-            // #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
@@ -13128,7 +13306,7 @@ What a push guarantees (two stages):
                     }
                     return typecheckSetup.checker;
                 };
-                const files = selectFiles("function", functionsPushDir, readdirSync(functionsPushDir).filter((f) => f.endsWith(".toml")));
+                const files = selectFiles("function", functionsPushDir, readdirSync(functionsPushDir).filter(isFunctionDeclarationFile));
                 const functionSpec = configDiffSpec("function");
                 const liveFunctions = new Map();
                 let functionsLiveOk = true;
@@ -13149,9 +13327,27 @@ What a push guarantees (two stages):
                 const liveActiveVersion = async (functionId, activeConfigId) => {
                     if (!activeConfigId)
                         return null;
-                    const { items } = await client.listFunctionConfigs(resolvedAppId, functionId);
-                    return ((items || []).find((c) => String(c.configId) === String(activeConfigId)) ?? 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);
@@ -13180,6 +13376,15 @@ What a push guarantees (two stages):
                         });
                         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
@@ -13356,6 +13561,23 @@ What a push guarantees (two stages):
                         });
                         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)`);
                     }
@@ -15108,7 +15330,7 @@ What a push guarantees (two stages):
             const localFunctionsParsed = new Map();
             const functionsDirPath = join(configDir, "functions");
             if (functionsOutcomeDiff.ok && existsSync(functionsDirPath)) {
-                for (const file of readdirSync(functionsDirPath).filter((f) => f.endsWith(".toml"))) {
+                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");
@@ -15402,8 +15624,14 @@ What a push guarantees (two stages):
                 const versionOutcome = await attemptFetch(async () => {
                     if (!remote.activeConfigId)
                         return null;
-                    const { items } = await client.listFunctionConfigs(resolvedAppId, remote.functionId);
-                    return ((items || []).find((c) => String(c.configId) === String(remote.activeConfigId)) ?? 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)";
@@ -15427,9 +15655,22 @@ What a push guarantees (two stages):
                             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 =
-                                    "the built bundle or a source file differs — `config push` " +
-                                        "creates a new immutable version";
+                                    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) {
@@ -15922,6 +16163,13 @@ What a push guarantees (two stages):
             // 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),