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

package/dist/src/lib/function-sync.js

@@ -31,11 +31,13 @@
  * directory inside the tree, so the write step resolves the real path one last
  * time and refuses a destination that lands outside the real root.
  */
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "fs";
 import { dirname, isAbsolute, join, posix as posixPath, relative, resolve, sep, } from "path";
-import { stringifyConfigToml } from "./config-toml.js";
+import { parseConfigToml, stringifyConfigToml } from "./config-toml.js";
+import { DOCUMENT_SCHEMA_TREE_FILE, resolveDocumentSchema, } from "./function-document-types.js";
 import { SERVER_FUNCTION_TABLE } from "./config-surface.js";
-import { configMode, hasDeclaredTriggers, normalizeTriggerDeclaration, resolveDeclaredMode, TriggerDeclarationError, validateSigningSecretDeclaration, } from "./generated-config-surfaces.js";
+import { checkCronTriggerEntry, hasDeclaredTriggers, hasRetiredDatabaseTriggerBlock, ignoredFunctionKeys, retiredDatabaseTriggerTypes, ignoredFunctionKeyWarnings, normalizeTriggerDeclaration, RETIRED_FUNCTION_RUNTIME_KEYS, TriggerDeclarationError, validateSigningSecretDeclaration, } from "./generated-config-surfaces.js";
+import { canonicalJsonStringify } from "./canonical-json.js";
 import { buildPayloadFromToml, projectRecordToToml, tomlOwned } from "./config-payload.js";
 import { serializeJsonField } from "./config-json-field.js";
 import { buildFunctionBundle, FunctionBuildError, functionEnvelopeHash, FUNCTION_ENVELOPE_SCHEMA_VERSION, isDependencyPath, } from "./function-bundle.js";
@@ -81,44 +83,31 @@ export async function collectManifestForBundle(options) {
  * (`cli/src/lib/function-triggers.ts`), kept in step only by a paired-fixture
  * test; the artifact's `--check` makes drift a build failure instead.
  *
- * One check is the CLI's OWN and is deliberately not on that path: the cron
- * expression's field count. The authority for cron grammar is the server's
- * `src/cron-parser.ts` (`parseCron`, run at the push boundary), which the
- * declaration rules never call — so this is a shape precheck that turns the
- * commonest typo into a named local error, not a second copy of a rule.
+ * Nothing here is the CLI's own any more. Until #3376 this function added a
+ * five-field count check of its own, justified as "not a second copy of a
+ * rule" precisely because the declaration path never called `parseCron`. It
+ * calls it now — `functionTomlPreflightErrors` runs `checkCronTriggerEntry`,
+ * which is the server's grammar and the server's sentence — so the precheck
+ * was exactly the duplicate this project exists to remove, and went with the
+ * justification.
  */
-export function normalizeFunctionTriggers(functionTable, options = {}) {
-    const declaration = normalizeTriggerDeclaration(functionTable, options);
+export function normalizeFunctionTriggers(functionTable) {
+    const declaration = normalizeTriggerDeclaration(functionTable);
     if (!hasDeclaredTriggers(declaration))
         return null;
-    for (const entry of declaration.cron) {
-        const fields = entry.cron.trim().split(/\s+/);
-        if (fields.length !== 5) {
-            throw new TriggerDeclarationError(`cron trigger '${entry.name}': a cron expression has exactly 5 fields, ` +
-                `and '${entry.cron}' has ${fields.length}`);
-        }
-    }
     return declaration;
 }
 /**
- * Resolve the file's mode — `mode`, its alias `durable`, or neither — through
- * the ONE vendored rule (#3281). A disagreement or an unknown word is a
- * `FunctionBuildError` naming the function, like every other preflight
- * refusal, so nothing is built or sent for that file.
+ * The retired runtime keys a `functions/<key>.toml` still carries — #3482.
+ *
+ * NOT a refusal. Through phase 4 `mode`, `durable` and a cron entry's `mode`
+ * are accepted and ignored, with one warning each and every other key of the
+ * file applied; phase 5 (#3188) refuses them. The sentences come from the one
+ * vendored scanner, so the warning `config push` prints is the sentence the
+ * server answers with.
  */
-export function resolveFunctionMode(functionKey, table) {
-    const resolution = resolveDeclaredMode({
-        mode: table?.mode,
-        durable: table?.durable,
-    });
-    // `=== false` rather than `!`: the CLI compiles without strict null checks,
-    // where truthiness does not narrow a discriminated union.
-    if (resolution.ok === false) {
-        // Names the file too: this is a refusal about two lines in it, and an
-        // author fixing a half-migrated tree wants to know which file to open.
-        throw new FunctionBuildError(`function '${functionKey}' (functions/${functionKey}.toml): ${resolution.error}`);
-    }
-    return resolution.mode;
+export function functionTomlIgnoredKeyWarnings(options) {
+    return ignoredFunctionKeyWarnings(`functions/${options.functionKey}.toml`, options.tomlData?.function);
 }
 /** The `entry` refusal, or null. One spelling, two readers. */
 function functionEntryError(functionKey, table) {
@@ -157,18 +146,8 @@ export function functionTomlPreflightErrors(options) {
     const entryError = functionEntryError(functionKey, table);
     if (entryError)
         errors.push(entryError);
-    // The mode is what the trigger rules are checked AGAINST, so a file whose
-    // two spellings disagree cannot be checked further — report that and stop.
-    let mode;
     try {
-        mode = resolveFunctionMode(functionKey, table);
-    }
-    catch (err) {
-        errors.push(String(err?.message ?? err));
-        return errors;
-    }
-    try {
-        const declaration = normalizeFunctionTriggers(table, { mode });
+        const declaration = normalizeFunctionTriggers(table);
         const webhook = declaration?.webhook;
         if (webhook) {
             // The file-decidable half of the webhook rule: which schemes need a
@@ -183,6 +162,18 @@ export function functionTomlPreflightErrors(options) {
                 errors.push(`function '${functionKey}': ${secretError.message}`);
             }
         }
+        // #3376 — cron expression and timezone, the server's own grammar and
+        // `Intl` probe, vendored. One message per broken entry rather than the
+        // first: the rule answers rather than throwing, so the file's errors are
+        // enumerated the way every other preflight rule enumerates them. The
+        // FIRST is byte-identical to what the push boundary would have answered,
+        // which is the only one the server ever gets to.
+        for (const entry of declaration?.cron ?? []) {
+            const refusal = checkCronTriggerEntry(entry);
+            if (refusal) {
+                errors.push(`function '${functionKey}': ${refusal.message}`);
+            }
+        }
     }
     catch (err) {
         // Throw-based, so the first broken rule per file wins — exactly what the
@@ -219,9 +210,6 @@ export async function buildFunctionConfigPush(options) {
     });
     if (preflight.length > 0)
         throw new FunctionBuildError(preflight[0]);
-    // #3281 — the mode, resolved once from either spelling; everything below
-    // reads the answer, never the keys.
-    const mode = resolveFunctionMode(functionKey, table);
     const built = await buildFunctionBundle({ configDir, entry, functionKey });
     // #3187 — the manifest, collected by RUNNING the tree's module scope in a
     // spawned, scrubbed child process (D3187-SO-006). Fail-closed: a push whose
@@ -247,6 +235,8 @@ export async function buildFunctionConfigPush(options) {
     // The AUTHORED bytes. Read from disk rather than re-serialized, so the round
     // trip is byte-identical (F-009).
     const authored = readFileSync(filePath);
+    // #3455 — the document schema this version is pushed with.
+    const documentSchemaResolution = resolveDocumentSchema(configDir);
     const limits = normalizeLimits(table.limits);
     const push = {
         entry: built.entry,
@@ -259,9 +249,17 @@ export async function buildFunctionConfigPush(options) {
         contentHash: built.contentHash,
         manifest,
         envelopeHash: "",
-        mode,
-        durable: mode === "task",
         ...(limits ? { limits } : {}),
+        // #3455 — the app's declared DOCUMENT schema, by the one resolution rule
+        // push, pull and diff share. Carried inside the envelope, so an edit to
+        // `models/models.toml` changes every function's `envelopeHash` and the
+        // next push mints a new version of each: the consequence D3455-001 states,
+        // and what makes a running version's seed source knowable.
+        ...(documentSchemaResolution.source
+            ? {
+                documentSchema: Buffer.from(documentSchemaResolution.source.content, "utf-8").toString("base64"),
+            }
+            : {}),
     };
     push.envelopeHash = functionEnvelopeHash({
         schemaVersion: FUNCTION_ENVELOPE_SCHEMA_VERSION,
@@ -270,9 +268,95 @@ export async function buildFunctionConfigPush(options) {
         sources: push.sources,
         bundle: push.bundle,
         manifest: push.manifest,
+        documentSchema: push.documentSchema,
     });
     return push;
 }
+/**
+ * The per-function failure when a server DID NOT retain the document schema it
+ * was sent — #3455 (D3455-010), criterion 7.
+ *
+ * The server builds its envelope from explicit known fields
+ * (`server-functions-controller.ts`) and answers the `envelopeHash` it stored.
+ * A server that predates this change drops `documentSchema` silently: it
+ * answers 200, the CLI reports the function pushed, first-writer seeding never
+ * works, and every later `config diff` reads Modified for a reason nobody can
+ * see. Comparing the hash it stored with the one this CLI built is the cheap
+ * acknowledgment that closes that.
+ *
+ * Gated on having SENT a schema, which is exactly what criterion 7 says
+ * ("reported successful only when the server retained the schema it was
+ * sent"): with nothing sent there is nothing to retain, and naming the
+ * document schema in a mismatch caused by something else would send an
+ * operator to the wrong place. A response with no `envelopeHash` at all is not
+ * judged — silence is not a disagreement.
+ */
+export function documentSchemaRetentionFailure(input) {
+    if (!input.sentDocumentSchema)
+        return null;
+    const stored = input.storedEnvelopeHash;
+    if (typeof stored !== "string" || stored.length === 0)
+        return null;
+    if (stored === input.builtEnvelopeHash)
+        return null;
+    return ("server did not retain the document schema (envelope hash differs): the " +
+        "server needs an upgrade before first-writer seeding works");
+}
+export function documentSchemaDropAnswer(documentSchemaModels) {
+    if (Array.isArray(documentSchemaModels)) {
+        const models = documentSchemaModels;
+        return {
+            outcome: "drops",
+            message: `This push DROPS the document schema the running version ` +
+                `carries (${models.length > 0 ? models.join(", ") : "no models"}): ` +
+                `the project has no models/models.toml and the tree has no ` +
+                `generated copy, so a function's first write can no longer ` +
+                `seed a document model's metadata.`,
+        };
+    }
+    if (documentSchemaModels === null)
+        return { outcome: "none" };
+    return { outcome: "unsupported" };
+}
+/**
+ * Says ONCE — for the whole push, not once per function — that this push drops
+ * a document schema a running version carries (#3455, D3455-004).
+ *
+ * Removing `models/models.toml` and its generated tree copy is a legitimate
+ * edit, so it is a warning and not a refusal; but it turns first-writer seeding
+ * off for every document these functions touch, and that must not be silent.
+ *
+ * The state this holds is "has the run been told yet", and the rule is that
+ * only an ANSWER settles it. A function whose active version carries no schema
+ * has told us nothing about its siblings, so the next function is still asked —
+ * getting that backwards silences a real drop whenever a schema-less function
+ * happens to be pushed first, which is the order nothing in the tree controls.
+ * The model names live inside the version's envelope rather than on its row,
+ * which is why this is a read and not a field of the listing already in hand.
+ */
+export function createDocumentSchemaDropWarner(deps) {
+    let settled = deps.treeCarriesSchema;
+    return async (functionId, activeConfigId) => {
+        if (settled || !activeConfigId)
+            return;
+        let detail;
+        try {
+            detail = await deps.readConfig(functionId, activeConfigId);
+        }
+        catch {
+            // A read that failed is not an answer either: the next function's may
+            // succeed, and losing the warning to one blip is the failure this
+            // whole rule exists to avoid.
+            return;
+        }
+        const answer = documentSchemaDropAnswer(detail?.documentSchemaModels);
+        if (answer.outcome === "none")
+            return;
+        settled = true;
+        if (answer.outcome === "drops")
+            deps.warn(answer.message);
+    };
+}
 /** `[function.limits]` as the server stores it, or undefined when absent. */
 function normalizeLimits(value) {
     if (value === undefined || value === null)
@@ -356,11 +440,9 @@ export function serializeFunction(record, active, log = () => { }) {
     };
     if (active?.entry)
         table.entry = active.entry;
-    // #3281 — the new word, and only for a task version: a request function is
-    // the default and says nothing. Never `durable`: this is the one file the
-    // CLI authors on a developer's behalf, and it must not teach the alias.
-    if (activeVersionMode(active) === "task")
-        table.mode = "task";
+    // #3482 — no `mode` and no `durable`. This is the one file the CLI authors
+    // on a developer's behalf, and it must not teach a key the platform ignores
+    // and phase 5 refuses.
     // #3182 — the capabilities are version-carried and server-derived, so the
     // fallback file has to state them or a push of it would silently drop the
     // function's declarations. `runAs` and `unscopedReads` are never written
@@ -378,15 +460,6 @@ export function serializeFunction(record, active, log = () => { }) {
     }
     return stringifyConfigToml({ function: table });
 }
-/**
- * The mode a server's config-version row is in, whichever of the two fields
- * this server serializes: `mode` since #3281, `durable` before it.
- */
-export function activeVersionMode(active) {
-    if (active?.mode === "task" || active?.mode === "request")
-        return active.mode;
-    return configMode(active);
-}
 /**
  * The tree-relative spelling of `entry` that push actually sends.
  *
@@ -429,11 +502,9 @@ export function functionDiffEntity(tomlData) {
         inputSchema: table.inputSchema ?? null,
         outputSchema: table.outputSchema ?? null,
         entry: canonicalEntry(table.entry),
-        // #3281 — the RESOLVED mode, never the raw keys: `durable = true` and
-        // `mode = "task"` are one fact, and a legacy tree must read Synced against
-        // a server that serializes the new word (D3281-SO-001). A file whose two
-        // keys disagree is drift here and a refusal at push.
-        mode: safeMode(table),
+        // #3482 — no `mode` key here. It said nothing about the function any more,
+        // and comparing a key neither side stores would report permanent drift for
+        // every tree that still carries the retired line.
         limits: limits && Object.keys(limits).length > 0 ? limits : null,
         // #3181 — normalized locally from the SAME rules the server applies, so a
         // trigger edit reads as a named field rather than only as the code-axis
@@ -448,18 +519,476 @@ export function functionDiffEntity(tomlData) {
             : [],
     };
 }
-function safeMode(table) {
-    const resolution = resolveDeclaredMode({ mode: table?.mode, durable: table?.durable });
-    return resolution.ok === true ? resolution.mode : null;
-}
 function safeTriggers(table) {
     try {
-        return normalizeFunctionTriggers(table, { mode: safeMode(table) ?? "request" });
+        return normalizeFunctionTriggers(table);
     }
     catch {
         return null;
     }
 }
+// ── The retired keys and blocks, stripped on the way out ─────────────────
+//
+// #3482 took the runtime keys out (D3482-007); #3483 takes the whole
+// `[[function.triggers.database]]` block out for the same reason and under the
+// same contract. The difference is only in what a line edit has to reach: a
+// key is one assignment, and a block is a table header and everything under it
+// until the next header.
+/** The two multi-line string delimiters TOML has. */
+const MULTILINE_DELIMITERS = ['"""', "'''"];
+/**
+ * Remove `mode`, `durable` and every cron entry's `mode` from authored TOML,
+ * preserving every other byte.
+ *
+ * The issue says `config pull` never writes them, and the pull plan writes the
+ * version's AUTHORED bytes verbatim — so without this a tree pulled from a
+ * version pushed before the retirement would carry keys phase 5 refuses, and
+ * could not be pushed again.
+ *
+ * ── Three jobs, kept apart ────────────────────────────────────────────────
+ *
+ * The PARSE decides what is removed and what is reported: `ignoredFunctionKeys`
+ * is the very scanner `config push` warns with, so what a pull takes out is
+ * exactly what a push said it was ignoring, whatever spelling the author used.
+ * TOML has several — `["function"]`, `function . mode = …`, an inline
+ * `triggers.cron = [ { mode = … } ]` — and a scan that reads the SOURCE has to
+ * know every one of them or it silently leaves a key behind (CR3482-002).
+ *
+ * The LINE EDIT decides how the bytes change, and is the path every real file
+ * takes. A re-serialization would rewrite every comment, blank line, quoting
+ * style and key order in a file a human wrote, so a pull would report a hundred
+ * changes to make three. Here exactly the matched assignments go and nothing
+ * else moves.
+ *
+ * The VERIFICATION decides whether the line edit was good enough, by parsing
+ * what it produced: the result must parse, must carry no retired key, and must
+ * otherwise say precisely what the file said. That is the contract stated as a
+ * check rather than as a hope — and it is what makes the line edit safe to keep
+ * narrow. A file it cannot reach by whole lines (a retired key sharing its line
+ * with keys that must survive, inside an inline table) falls back to a
+ * serialized rewrite, which is reported, because a pulled file that still
+ * carries the key — or one that no longer parses (CR3482-001) — is worse than a
+ * reformatted one.
+ *
+ * Returns the text and one line per removal, so the caller can report what it
+ * did rather than silently editing a developer's file.
+ */
+export function stripRetiredFunctionKeys(toml, label = "") {
+    const prefix = label ? `${label}: ` : "";
+    let before;
+    try {
+        before = parseConfigToml(toml);
+    }
+    catch {
+        // Not ours to fix, and not ours to guess at. A file that does not parse
+        // never pushed, so it is not a stored version's authored bytes; leave
+        // every byte where it is.
+        return { toml, removals: [] };
+    }
+    const functionTable = before.function;
+    const ignored = ignoredFunctionKeys(functionTable);
+    // PRESENCE, not entry count (CR3483-001). `database = []` names no type, and
+    // deciding by the list's length left that line in the pulled file — which
+    // the next push then refused, because the refusal reads presence. The two
+    // halves ask the same question now.
+    const hasDatabaseBlock = hasRetiredDatabaseTriggerBlock(functionTable);
+    const databaseTypes = retiredDatabaseTriggerTypes(functionTable);
+    if (ignored.length === 0 && !hasDatabaseBlock) {
+        return { toml, removals: [] };
+    }
+    const removals = [
+        ...ignored.map((key) => `${prefix}removed \`${removalPhrase(key)}\` (#3482)`),
+        // One line per entry, and one line for a block that has no entry to name:
+        // an author who wrote `triggers.database = []` still has a line gone from
+        // their file and is owed the same notice as one who wrote a type.
+        ...(hasDatabaseBlock && databaseTypes.length === 0
+            ? [`${prefix}removed \`[[function.triggers.database]]\` (#3483)`]
+            : databaseTypes.map((type) => `${prefix}removed \`[[function.triggers.database]]\` type ` +
+                `'${type}' (#3483)`)),
+    ];
+    const want = withoutRetiredFunctionKeys(before);
+    const edited = removeRetiredKeyLines(toml);
+    if (saysExactly(edited, want))
+        return { toml: edited, removals };
+    // The line edit could not reach it. Today that means one thing: a retired key
+    // written inside an inline table, sharing its line with keys that have to
+    // survive it.
+    const rewritten = serializeWithout(want);
+    if (rewritten !== null && saysExactly(rewritten, want)) {
+        return {
+            toml: rewritten,
+            removals: [
+                ...removals,
+                `${prefix}rewrote the file to do it — the key shared a line with keys ` +
+                    `that had to stay, so comments and formatting were not preserved (#3482)`,
+            ],
+        };
+    }
+    // Unreachable from any file that parsed: `want` came from this document, so
+    // TOML can write it back. If it ever happens, say so and change nothing —
+    // a file left as it was can still be edited by hand, and one written back
+    // broken cannot be pushed at all.
+    const named = [
+        ...ignored.map((key) => `\`${removalPhrase(key)}\``),
+        ...(databaseTypes.length > 0
+            ? ["`[[function.triggers.database]]`"]
+            : []),
+    ].join(", ");
+    return {
+        toml,
+        removals: [
+            `${prefix}could NOT remove ${named} — the file is unchanged; delete by ` +
+                `hand (#3482, #3483)`,
+        ],
+    };
+}
+/** How a pull names one retired key it took out. */
+function removalPhrase(key) {
+    return key.path === "mode" || key.path === "durable"
+        ? key.path
+        : "mode on a [[function.triggers.cron]] entry";
+}
+/** The document without the retired keys — the answer a pull has to produce. */
+function withoutRetiredFunctionKeys(doc) {
+    const fn = doc.function;
+    if (!fn || typeof fn !== "object" || Array.isArray(fn))
+        return doc;
+    const nextFunction = { ...fn };
+    for (const key of RETIRED_FUNCTION_RUNTIME_KEYS)
+        delete nextFunction[key];
+    const triggers = nextFunction.triggers;
+    if (triggers && typeof triggers === "object" && !Array.isArray(triggers)) {
+        // One pass over the table, so the two removals cannot undo each other: a
+        // second `{ ...triggers, … }` built from the ORIGINAL would put back the
+        // block the first one took out.
+        const nextTriggers = {
+            ...triggers,
+        };
+        // #3483 — the whole block, whatever spelling it took.
+        delete nextTriggers.database;
+        const cron = triggers.cron;
+        const withoutMode = (entry) => {
+            if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+                return entry;
+            }
+            const next = { ...entry };
+            delete next.mode;
+            return next;
+        };
+        if (Array.isArray(cron)) {
+            nextTriggers.cron = cron.map(withoutMode);
+        }
+        else if (cron && typeof cron === "object") {
+            nextTriggers.cron = withoutMode(cron);
+        }
+        nextFunction.triggers = nextTriggers;
+    }
+    return { ...doc, function: nextFunction };
+}
+/**
+ * Whether `text` says precisely what `want` says.
+ *
+ * Empty tables are ignored on both sides: removing the last key of a table
+ * removes the table with it in the dotted spelling (`function.mode = …` at the
+ * document root leaves no `[function]` behind), which is the right answer and
+ * the one the strip has always given.
+ */
+function saysExactly(text, want) {
+    try {
+        const parsed = parseConfigToml(text);
+        const fn = parsed.function;
+        if (ignoredFunctionKeys(fn).length)
+            return false;
+        if (hasRetiredDatabaseTriggerBlock(fn))
+            return false;
+        return withoutEmptyTables(parsed) === withoutEmptyTables(want);
+    }
+    catch {
+        return false;
+    }
+}
+/** Canonical JSON with empty tables dropped, for comparing two documents. */
+function withoutEmptyTables(value) {
+    const prune = (node) => {
+        if (Array.isArray(node))
+            return node.map(prune);
+        if (!node || typeof node !== "object")
+            return node;
+        if (typeof node.toJSON === "function")
+            return node;
+        const next = {};
+        for (const [key, child] of Object.entries(node)) {
+            const pruned = prune(child);
+            const isEmptyTable = pruned !== null &&
+                typeof pruned === "object" &&
+                !Array.isArray(pruned) &&
+                typeof pruned.toJSON !== "function" &&
+                Object.keys(pruned).length === 0;
+            if (!isEmptyTable)
+                next[key] = pruned;
+        }
+        return next;
+    };
+    return canonicalJsonStringify(prune(value));
+}
+/** `want` written back as TOML, or null if TOML cannot carry some value of it. */
+function serializeWithout(want) {
+    try {
+        const text = stringifyConfigToml(want);
+        return text.endsWith("\n") ? text : `${text}\n`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete every line a retired key's assignment occupies, and nothing else.
+ *
+ * Narrow on purpose, because `mode` is a perfectly good key of some OTHER table
+ * (an integration's `bodyMode`, a nested table of the author's own) and inside
+ * a multi-line string or an array's value it is not a key at all. A key matches
+ * only when the table it sits in and its own dotted name together spell
+ * `function.mode`, `function.durable` or `function.triggers.cron.mode` — one
+ * comparison that covers `[function]` + `mode`, the root's `function.mode`, a
+ * `[[function.triggers.cron]]` entry's `mode`, and every quoted or
+ * space-padded spelling of each.
+ *
+ * Telling a key from text is `scanLine`'s job, and it has to be told properly
+ * rather than by looking for delimiters with `indexOf`: a `"""` inside a
+ * comment or a quoted value opens nothing, an escaped `\"""` inside a basic
+ * string closes nothing, and a value may run past its first line — as a
+ * multi-line string, an array or an inline table — in which case the WHOLE
+ * assignment goes, because deleting its opening line alone would orphan the
+ * rest and leave a file that no longer parses.
+ */
+function removeRetiredKeyLines(toml) {
+    const lines = toml.split("\n");
+    const kept = [];
+    // The table the lines below belong to, by its header. The root is [].
+    let table = [];
+    let state = { open: null, depth: 0 };
+    // Whether the value we are still reading belongs to a key we removed, so its
+    // remaining lines go with it.
+    let droppingValue = false;
+    // #3483 — whether the TABLE the lines below belong to is one we removed, so
+    // the whole section goes with its header. A key is one assignment; a block
+    // is a header and everything under it until the next header.
+    let droppingTable = false;
+    for (const line of lines) {
+        if (state.open || state.depth > 0) {
+            state = scanLine(line, state);
+            if (!droppingValue && !droppingTable)
+                kept.push(line);
+            if (!state.open && state.depth <= 0)
+                droppingValue = false;
+            continue;
+        }
+        const trimmed = line.trim();
+        const header = /^\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/.exec(trimmed);
+        if (header) {
+            table = keyPath(header[1]) ?? table;
+            droppingTable = isRetiredTablePath(table);
+            if (droppingTable) {
+                // The blank lines that separated this block from what came before it
+                // separated nothing once it is gone.
+                while (kept.length > 0 && kept[kept.length - 1].trim() === "") {
+                    kept.pop();
+                }
+                continue;
+            }
+            kept.push(line);
+            continue;
+        }
+        if (droppingTable) {
+            // Still inside the removed section: the line goes, and a value that runs
+            // past its own line goes with it.
+            state = scanLine(line, { open: null, depth: 0 });
+            continue;
+        }
+        if (isRetiredKeyLine(table, trimmed)) {
+            // `mode = """\ntask"""` is a retired key like any other, and one line of
+            // it is not.
+            state = scanLine(line, { open: null, depth: 0 });
+            droppingValue = state.open !== null || state.depth > 0;
+            continue;
+        }
+        state = scanLine(line, { open: null, depth: 0 });
+        kept.push(line);
+    }
+    return kept.join("\n");
+}
+/** Whether this line assigns one of the retired keys. */
+function isRetiredKeyLine(table, trimmed) {
+    const key = assignmentKey(trimmed);
+    if (!key)
+        return false;
+    const path = [...table, ...key].join(".");
+    return (path === "function.mode" ||
+        path === "function.durable" ||
+        path === "function.triggers.cron.mode" ||
+        // #3483 — the inline spelling, `triggers.database = [ { … } ]` under
+        // `[function]`, or `function.triggers.database = …` at the root. Its value
+        // runs past its own line as often as not, which the caller's
+        // `droppingValue` handles exactly as it does for a multi-line `mode`.
+        path === "function.triggers.database");
+}
+/**
+ * Whether a table header names a section the strip removes whole — #3483.
+ *
+ * Prefix-matched rather than compared, so a sub-table of an entry
+ * (`[function.triggers.database.filter]`, which TOML allows even though this
+ * platform never read one) goes with the block it belongs to instead of being
+ * orphaned into a file that no longer parses.
+ */
+function isRetiredTablePath(table) {
+    const retired = ["function", "triggers", "database"];
+    if (table.length < retired.length)
+        return false;
+    return retired.every((part, index) => table[index] === part);
+}
+/**
+ * The dotted name this line assigns to, in components, or null when the line
+ * assigns nothing.
+ *
+ * The `=` is found by scanning rather than by a regex, so a quoted key holding
+ * one (`"a=b".mode = 1`) is read as the key it is.
+ */
+function assignmentKey(trimmed) {
+    let i = 0;
+    while (i < trimmed.length) {
+        const char = trimmed[i];
+        // The rest of the line is the author's prose, so there is no key on it.
+        if (char === "#")
+            return null;
+        if (char === '"' || char === "'") {
+            i = endOfSingleLineString(trimmed, i);
+            continue;
+        }
+        if (char === "=")
+            break;
+        i += 1;
+    }
+    if (trimmed[i] !== "=")
+        return null;
+    const raw = trimmed.slice(0, i).trim();
+    return raw ? keyPath(raw) : null;
+}
+/**
+ * A TOML key — a table header's inside or an assignment's left side — split
+ * into its components, with quotes and the whitespace TOML allows around the
+ * dots taken off. Null for anything this does not understand, so a key the
+ * strip cannot read is a key it does not delete.
+ */
+function keyPath(raw) {
+    const parts = [];
+    let current = "";
+    let i = 0;
+    while (i < raw.length) {
+        const char = raw[i];
+        if (char === " " || char === "\t") {
+            i += 1;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            const end = endOfSingleLineString(raw, i);
+            current += raw.slice(i + 1, Math.max(i + 1, end - 1));
+            i = end;
+            continue;
+        }
+        if (char === ".") {
+            parts.push(current);
+            current = "";
+            i += 1;
+            continue;
+        }
+        if (!/[A-Za-z0-9_-]/.test(char))
+            return null;
+        current += char;
+        i += 1;
+    }
+    parts.push(current);
+    return parts;
+}
+/**
+ * Walk one line of TOML from the state it starts in to the one the next line
+ * starts in.
+ *
+ * Not a parser: the strip only needs to tell code from text and to know when a
+ * value has ended, which is the whole of what it kept getting wrong. Four rules
+ * carry it:
+ *
+ *   - a `#` outside a string comments out the rest of the line, so a `"""` in
+ *     an author's note opens nothing and a `]` in one closes nothing;
+ *   - a single-line string is skipped whole, so a `"""` quoted inside one opens
+ *     nothing either;
+ *   - inside a BASIC string (`"""`) a backslash escapes the next character, so
+ *     the `\"""` TOML requires for a literal triple quote does not close it. A
+ *     literal string (`'''`) has no escapes and ends at its first delimiter;
+ *   - brackets outside strings nest, so an array or inline table spread over
+ *     several lines is read to its end — and the lines inside it are read as
+ *     the value they are, never as keys of the enclosing table.
+ */
+function scanLine(line, from) {
+    let open = from.open;
+    let depth = from.depth;
+    let i = 0;
+    while (i < line.length) {
+        if (open) {
+            if (open === '"""' && line[i] === "\\") {
+                i += 2;
+                continue;
+            }
+            if (line.startsWith(open, i)) {
+                i += open.length;
+                open = null;
+                continue;
+            }
+            i += 1;
+            continue;
+        }
+        const char = line[i];
+        // The rest of the line is the author's prose.
+        if (char === "#")
+            break;
+        if (char === '"' || char === "'") {
+            const delimiter = MULTILINE_DELIMITERS.find((candidate) => line.startsWith(candidate, i));
+            if (delimiter) {
+                open = delimiter;
+                i += delimiter.length;
+                continue;
+            }
+            i = endOfSingleLineString(line, i);
+            continue;
+        }
+        if (char === "[" || char === "{")
+            depth += 1;
+        else if (char === "]" || char === "}")
+            depth = Math.max(0, depth - 1);
+        i += 1;
+    }
+    return { open, depth };
+}
+/**
+ * The index just past the single-line string opening at `start`.
+ *
+ * An unterminated one answers the end of the line: TOML would refuse such a
+ * file anyway, and the strip's business is to leave it as it found it, not to
+ * start deleting on the strength of a quote somebody forgot to close.
+ */
+function endOfSingleLineString(line, start) {
+    const quote = line[start];
+    let i = start + 1;
+    while (i < line.length) {
+        if (quote === '"' && line[i] === "\\") {
+            i += 2;
+            continue;
+        }
+        if (line[i] === quote)
+            return i + 1;
+        i += 1;
+    }
+    return line.length;
+}
 /**
  * Why a stored source path may not be written, or null.
  *
@@ -491,17 +1020,51 @@ export function unsafePulledPath(path) {
  */
 export function planFunctionPull(options) {
     const { configDir, functionKey, envelope } = options;
+    const includeDocumentSchema = options.includeDocumentSchema !== false;
     const root = resolve(configDir);
     const files = [];
     const sourcePaths = [];
     const refusals = [];
+    const notes = [];
+    const removals = [];
     if (typeof envelope?.toml === "string") {
         const relativePath = `functions/${functionKey}.toml`;
+        // #3482 (D3482-007) — the retired runtime keys never reach the tree. Every
+        // other byte of the authored file is written back unchanged, so a pull is
+        // still a byte-identical round trip for a file that carries none of them.
+        // For a file that does, the consequence is one-time and recorded: the
+        // pulled tree differs from the stored envelope, `config diff` reads
+        // Modified, and the next push makes a version whose TOML no longer carries
+        // the key.
+        const stripped = stripRetiredFunctionKeys(Buffer.from(envelope.toml, "base64").toString("utf-8"), relativePath);
+        notes.push(...stripped.removals);
         files.push({
             relative: relativePath,
             absolute: join(root, "functions", `${functionKey}.toml`),
-            content: Buffer.from(envelope.toml, "base64"),
+            content: Buffer.from(stripped.toml, "utf-8"),
+        });
+    }
+    // #3455 (D3455-009) — the active version's document schema, written back as
+    // the tree's GENERATED copy so a fresh pull into a project with no
+    // `models/models.toml` still rebuilds the same envelope and reads Synced.
+    // Always at this one fixed tree path: it is derived from the envelope's
+    // field, never from a stored path, so it cannot be aimed anywhere.
+    if (includeDocumentSchema) {
+        const copy = planDocumentSchemaPull({
+            configDir,
+            functions: [
+                {
+                    functionKey,
+                    documentSchema: typeof envelope?.documentSchema === "string" && envelope.documentSchema
+                        ? envelope.documentSchema
+                        : null,
+                },
+            ],
+            coversEveryFunction: true,
         });
+        files.push(...copy.files);
+        removals.push(...copy.removals);
+        refusals.push(...copy.warnings);
     }
     for (const source of envelope?.sources ?? []) {
         const path = toPosix(String(source?.path ?? ""));
@@ -525,7 +1088,79 @@ export function planFunctionPull(options) {
         });
         sourcePaths.push(path);
     }
-    return { configDir: root, functionKey, files, sourcePaths, refusals };
+    return {
+        configDir: root,
+        functionKey,
+        files,
+        sourcePaths,
+        refusals,
+        notes,
+        removals,
+    };
+}
+/**
+ * The tree's generated document-schema copy, decided ONCE for a whole pull —
+ * CR3455-001.
+ *
+ * Push and diff resolve the copy tree-wide (`resolveDocumentSchema`), so the
+ * tree can hold exactly one schema however many functions it has. Deciding it
+ * per function meant the last function applied won: a version carrying no
+ * schema DELETED the copy a schema-bearing sibling had just written, the
+ * sibling then diffed Modified for ever, and a repush from that tree dropped
+ * the schema — the one outcome D3455-009 exists to prevent.
+ *
+ * The rules, and what each is protecting:
+ *
+ *  - Any pulled version carrying a schema WINS over one carrying none. The
+ *    copy is a fallback consulted only when the project has no
+ *    `models/models.toml`; keeping it is what lets a fresh pull re-push.
+ *  - The copy is removed only when the pull read EVERY active function and
+ *    none carried a schema. A selective pull has not learned anything about
+ *    the functions it did not read, and deleting on that evidence would take
+ *    the schema away from a version that still pins one.
+ *  - Versions that disagree are reported rather than silently reconciled. One
+ *    file cannot reproduce two envelopes, so an operator is told which
+ *    function the tree now speaks for and which ones will read Modified until
+ *    they are pushed again.
+ */
+export function planDocumentSchemaPull(options) {
+    const root = resolve(options.configDir);
+    const relativePath = `functions/${DOCUMENT_SCHEMA_TREE_FILE}`;
+    const absolute = join(root, "functions", DOCUMENT_SCHEMA_TREE_FILE);
+    const plan = {
+        configDir: root,
+        files: [],
+        removals: [],
+        warnings: [],
+    };
+    // Sorted by key so the schema a mixed tree keeps is a property of the app,
+    // not of the order the listing happened to come back in.
+    const pulled = [...options.functions].sort((a, b) => a.functionKey.localeCompare(b.functionKey));
+    if (pulled.length === 0)
+        return plan;
+    const carriers = pulled.filter((f) => !!f.documentSchema);
+    if (carriers.length === 0) {
+        if (options.coversEveryFunction) {
+            plan.removals.push({ relative: relativePath, absolute });
+        }
+        return plan;
+    }
+    const chosen = carriers[0];
+    plan.files.push({
+        relative: relativePath,
+        absolute,
+        content: Buffer.from(String(chosen.documentSchema), "base64"),
+    });
+    const disagreeing = pulled
+        .filter((f) => f.documentSchema !== chosen.documentSchema)
+        .map((f) => f.functionKey);
+    if (disagreeing.length > 0) {
+        plan.warnings.push(`${relativePath} holds the document schema '${chosen.functionKey}' is ` +
+            `pinned to; ${disagreeing.join(", ")} pinned a different one or none, ` +
+            "so this tree cannot rebuild every active version's envelope. " +
+            "`config diff` reads those functions Modified until they are pushed again.");
+    }
+    return plan;
 }
 /**
  * Why a destination may not be written even though its stored path is
@@ -585,7 +1220,7 @@ export function applyFunctionPull(plan) {
     catch {
         realRoot = plan.configDir;
     }
-    const sourcePaths = new Set(plan.sourcePaths);
+    const sourcePaths = new Set(plan.sourcePaths ?? []);
     for (const file of plan.files) {
         const refusal = unsafeDestination(realRoot, file.absolute);
         if (refusal) {
@@ -599,6 +1234,25 @@ export function applyFunctionPull(plan) {
         if (sourcePaths.has(file.relative))
             outcome.writtenSources.push(file.relative);
     }
+    // #3455 — a stale generated schema copy, when the active version carries
+    // none. Same real-path check as a write: the path is this CLI's own
+    // constant, but a symlinked `functions/` must not let a pull unlink
+    // something outside the tree.
+    for (const removal of plan.removals) {
+        if (!existsSync(removal.absolute))
+            continue;
+        const refusal = unsafeDestination(realRoot, removal.absolute);
+        if (refusal) {
+            outcome.refusals.push(refusal);
+            continue;
+        }
+        try {
+            rmSync(removal.absolute);
+        }
+        catch (error) {
+            outcome.refusals.push(`failed removing '${removal.relative}': ${String(error?.message ?? error)}`);
+        }
+    }
     return outcome;
 }
 //# sourceMappingURL=function-sync.js.map