primitive-admin 1.1.0-alpha.9 → 1.1.0

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

@@ -0,0 +1,1258 @@
+/**
+ * `functions/<key>.toml` on the wire and back (#3179, project
+ * `server-functions`).
+ *
+ * A function is the one configuration object whose file is not its whole
+ * authored surface: the TOML states the gate, the entry and the limits, and the
+ * TypeScript the entry reaches is the rest of it. `config push` therefore sends
+ * TWO things — a header (create/update) and an immutable config VERSION
+ * carrying the authored TOML bytes, every source file and the built bundle —
+ * and `config pull` writes both halves back.
+ *
+ * ── The envelope hash is the shared answer to "changed?" ──────────────────
+ *
+ * The server decides whether a push is a no-op on `envelopeHash` (sha256 over
+ * the TOML bytes, the sources and the bundle), because a comment-only or
+ * CRLF-only edit leaves the BUNDLE identical and must still make a version
+ * (F-003). The CLI computes the same number to decide whether to make the call
+ * at all, through `function-bundle.ts`'s copy of the server's canonical
+ * encoding. If those two encodings ever drift, one side re-pushes forever and
+ * the other silently drops an edit — `function-bundle-3179.test.ts` pins them
+ * against each other.
+ *
+ * ── Pull writes bytes ────────────────────────────────────────────────────
+ *
+ * Canonical re-serialization cannot preserve comments, key order or line
+ * endings, so the envelope stores the AUTHORED bytes and pull writes those
+ * (F-009). It also never trusts a stored path: the files it writes are named by
+ * the server, so a path that normalizes outside the tree — or into
+ * `node_modules`, which is never authored source — is refused rather than
+ * written to a developer's disk. The lexical rules cannot see a symlinked
+ * 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, rmSync, writeFileSync, } from "fs";
+import { dirname, isAbsolute, join, posix as posixPath, relative, resolve, sep, } from "path";
+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 { 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";
+import { collectFunctionManifest, FunctionCollectError, } from "./function-collect.js";
+const toPosix = (value) => value.split(sep).join("/");
+/**
+ * Collected manifests, keyed by the BUILT BUNDLE they were collected from.
+ *
+ * Memoized against `contentHash`: the same bytes always collect the same way,
+ * and a tree edited mid-command hashes differently and is collected again
+ * rather than served a stale answer.
+ */
+const collectedManifests = new Map();
+/**
+ * Collect one function's manifest, or answer from this command's memo.
+ *
+ * `FunctionCollectError` is translated to the push loop's one failure class by
+ * the callers, so a collect failure reads like any other build failure for
+ * that function and lands nothing.
+ */
+export async function collectManifestForBundle(options) {
+    const memo = collectedManifests.get(options.contentHash);
+    if (memo)
+        return memo;
+    const collected = await collectFunctionManifest({
+        configDir: options.configDir,
+        entry: options.entry,
+        functionKey: options.functionKey,
+        bundle: options.bundle,
+    });
+    collectedManifests.set(options.contentHash, collected);
+    return collected;
+}
+// ── The trigger rules, read from the one implementation ───────────────────
+/**
+ * The server's own `[function.triggers.*]` rules, applied to a parsed
+ * `[function]` table, with "nothing declared" spelled as null so a caller can
+ * skip the work.
+ *
+ * `normalizeTriggerDeclaration` comes from `generated-config-surfaces.ts` —
+ * `src/config-surface/trigger-declaration.ts` vendored verbatim. Until #3320
+ * the CLI ran a hand-written restatement of those rules
+ * (`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.
+ *
+ * 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) {
+    const declaration = normalizeTriggerDeclaration(functionTable);
+    if (!hasDeclaredTriggers(declaration))
+        return null;
+    return declaration;
+}
+/**
+ * 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 functionTomlIgnoredKeyWarnings(options) {
+    return ignoredFunctionKeyWarnings(`functions/${options.functionKey}.toml`, options.tomlData?.function);
+}
+/** The `entry` refusal, or null. One spelling, two readers. */
+function functionEntryError(functionKey, table) {
+    if (String(table?.entry ?? "").trim())
+        return null;
+    return (`function '${functionKey}': \`entry\` is required — name the TypeScript ` +
+        "entry point, relative to the config tree root.");
+}
+/**
+ * Everything about one `functions/<key>.toml` that `config push` can decide
+ * from the file alone (#3320).
+ *
+ * This is the seam the issue is about. These checks used to run inside the
+ * APPLY loop, so a `durable = true` beside a webhook block — or a missing
+ * `entry`, or a signed scheme with no `signingSecret` — was raised after app
+ * settings, vars, integrations, webhooks, cron triggers and database types had
+ * already been written, while the command's own framing promised that a
+ * refusal meant nothing was applied. Running them in the front-loaded pass
+ * (#976) makes that framing true for this class of error.
+ *
+ * Every rule here is the SERVER's, reached through the generated surface
+ * artifact (#3320 part 0), not a local imitation of it. What is deliberately
+ * absent is app-state-dependent by construction: whether the referenced secret
+ * exists, whether the scheme's `config` is valid under this environment's JWKS
+ * policy, per-app caps, key collisions, archived tombstones. A local guess at
+ * any of those would be a preflight that gives a false all-clear.
+ *
+ * Returns the messages the apply loop would have raised, verbatim — so the
+ * author reads the same sentence wherever it reaches them, and `config diff`
+ * can report it under Invalid (#2880 symmetry).
+ */
+export function functionTomlPreflightErrors(options) {
+    const { functionKey, tomlData } = options;
+    const table = tomlData?.function ?? {};
+    const errors = [];
+    const entryError = functionEntryError(functionKey, table);
+    if (entryError)
+        errors.push(entryError);
+    try {
+        const declaration = normalizeFunctionTriggers(table);
+        const webhook = declaration?.webhook;
+        if (webhook) {
+            // The file-decidable half of the webhook rule: which schemes need a
+            // secret, that one is supplied, and that it is a whole reference. The
+            // server runs this same function at the write boundary, and then asks
+            // the questions only it can (does `KEY` exist?).
+            const secretError = validateSigningSecretDeclaration({
+                verificationScheme: webhook.verificationScheme,
+                signingSecret: webhook.signingSecret,
+            });
+            if (secretError) {
+                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
+        // apply loop reported.
+        if (err instanceof TriggerDeclarationError) {
+            errors.push(`function '${functionKey}': ${err.message}`);
+        }
+        else {
+            throw err;
+        }
+    }
+    return errors;
+}
+/**
+ * Build everything the config-version route needs for one function file.
+ *
+ * Throws `FunctionBuildError` for a missing `entry`, a missing entry file, a
+ * build error, or an import that escapes the config tree — one class, so the
+ * push loop has one thing to report and pushes nothing for that function.
+ *
+ * The file-decidable checks are `functionTomlPreflightErrors`', kept here as
+ * defense in depth (#3179's dual-validation shape): `config push` runs them in
+ * its preflight now, but `functions` commands and a direct caller reach this
+ * function without one.
+ */
+export async function buildFunctionConfigPush(options) {
+    const { configDir, functionKey, filePath, tomlData } = options;
+    const table = tomlData?.function ?? {};
+    const entry = String(table.entry ?? "").trim();
+    const preflight = functionTomlPreflightErrors({
+        filePath,
+        functionKey,
+        tomlData,
+    });
+    if (preflight.length > 0)
+        throw new FunctionBuildError(preflight[0]);
+    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
+    // collect fails is refused naming the error, because the manifest is inside
+    // the envelope and "push now, collect later" would mean a different version.
+    let manifest = null;
+    try {
+        const collected = await collectManifestForBundle({
+            configDir,
+            entry: built.entry,
+            functionKey,
+            contentHash: built.contentHash,
+            bundle: built.bundle.toString("utf-8"),
+        });
+        manifest = Buffer.from(JSON.stringify(collected), "utf-8").toString("base64");
+    }
+    catch (error) {
+        if (error instanceof FunctionCollectError) {
+            throw new FunctionBuildError(error.message);
+        }
+        throw error;
+    }
+    // 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,
+        toml: authored.toString("base64"),
+        sources: built.sources.map((s) => ({
+            path: s.path,
+            content: s.content.toString("base64"),
+        })),
+        bundle: built.bundle.toString("base64"),
+        contentHash: built.contentHash,
+        manifest,
+        envelopeHash: "",
+        ...(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,
+        entry: push.entry,
+        toml: push.toml,
+        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)
+        return undefined;
+    if (typeof value === "string") {
+        try {
+            const parsed = JSON.parse(value);
+            return parsed && typeof parsed === "object" ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value;
+}
+/**
+ * The create body. `functionKey` is attached here rather than spread from the
+ * table: the identity comes from the file name, exactly as it does for every
+ * other keyed type.
+ */
+export function buildFunctionCreatePayload(functionKey, table) {
+    const payload = buildPayloadFromToml(SERVER_FUNCTION_TABLE, table ?? {}, {
+        mode: "create",
+        values: { description: tomlOwned },
+    });
+    dropUndefined(payload);
+    return { functionKey, ...payload };
+}
+/**
+ * The update body. The key is NOT re-sent — it is the function's claim on the
+ * app's single key namespace and the URL already names the row — and `status`
+ * is server-owned on the sixth carrying type as on the other five.
+ *
+ * #3317 — the schemas are TOML-owned on exactly the terms `description` is
+ * (#1567), which is what prompts have sent since then: the update handler
+ * preserves a field the body omits, so dropping the key would leave a schema
+ * live that the file no longer declares, and the comparison — which reads an
+ * absent schema as `null` — would report that difference again on every run.
+ * Removing `[function.inputSchema]` clears it, and the next diff is Synced.
+ */
+export function buildFunctionUpdatePayload(table) {
+    const payload = buildPayloadFromToml(SERVER_FUNCTION_TABLE, table ?? {}, {
+        mode: "update",
+        values: {
+            description: tomlOwned,
+            inputSchema: tomlOwned,
+            outputSchema: tomlOwned,
+        },
+    });
+    dropUndefined(payload);
+    return payload;
+}
+function dropUndefined(payload) {
+    for (const key of Object.keys(payload)) {
+        if (payload[key] === undefined)
+            delete payload[key];
+    }
+}
+/**
+ * The canonical TOML for a function with no stored authored bytes — a function
+ * created through the API that has never had code pushed. When bytes exist,
+ * pull writes THOSE; this is the fallback that still produces a pushable file.
+ */
+export function serializeFunction(record, active, log = () => { }) {
+    const subject = `Function '${record?.functionKey}'`;
+    const table = {
+        key: record.functionKey,
+        // #3317 — the two schemas are stored as JSON STRINGS on the row, and
+        // `projectRecordToToml` reads a `json` field's emptiness as "not a
+        // non-empty object": without a producer, every stored schema was dropped
+        // here, so the file pull falls back to lost it and the comparison's remote
+        // side reported `(absent)` for a schema `functions get` prints. The shared
+        // rule emits the value the string encodes, as a native table whenever TOML
+        // can hold it.
+        ...projectRecordToToml(SERVER_FUNCTION_TABLE, record, {
+            inputSchema: (rec, field) => serializeJsonField(rec?.[field.field], field.field, subject, log),
+            outputSchema: (rec, field) => serializeJsonField(rec?.[field.field], field.field, subject, log),
+        }),
+    };
+    if (active?.entry)
+        table.entry = active.entry;
+    // #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
+    // back (#3279): a pre-change row's stored value decides nothing, and a
+    // pulled file that carried either would be refused on its next push.
+    if (Array.isArray(active?.capabilities) && active.capabilities.length > 0) {
+        table.capabilities = [...active.capabilities].sort();
+    }
+    const limits = normalizeLimits(active?.limits);
+    if (limits && Object.keys(limits).length > 0)
+        table.limits = limits;
+    for (const key of Object.keys(table)) {
+        if (table[key] === undefined || table[key] === null)
+            delete table[key];
+    }
+    return stringifyConfigToml({ function: table });
+}
+/**
+ * The tree-relative spelling of `entry` that push actually sends.
+ *
+ * The build normalizes the authored value (`resolve` + `relative`), and the
+ * server stores what it is sent, so a valid `./functions/greet/index.ts`
+ * arrives as `functions/greet/index.ts`. Comparing the authored spelling
+ * against the stored one would report a function as Modified the instant it
+ * was pushed and re-send the same update forever, so both sides are read
+ * through the same normalization here.
+ *
+ * Lexical only: an in-tree SYMLINK spelling is resolved by the build and not
+ * by this, which is the one remaining way for the two to differ.
+ */
+function canonicalEntry(value) {
+    const raw = toPosix(String(value ?? "").trim());
+    if (!raw)
+        return null;
+    const normalized = posixPath.normalize(raw).replace(/\/+$/, "");
+    return normalized || null;
+}
+/**
+ * The entity both sides of `config diff` are projected onto: the header's
+ * authored fields plus the keys the VERSION carries. Stated once so a
+ * local file and a server record cannot be read into different shapes.
+ *
+ * Text the server rewrites on the way in is read the same way it will come
+ * back (the DSO-003 rule the webhook comparator states): `access` is stored
+ * trimmed and `entry` normalized, so an authored value that differs only in
+ * that respect is not permanent drift.
+ */
+export function functionDiffEntity(tomlData) {
+    const table = tomlData?.function ?? {};
+    const limits = normalizeLimits(table.limits);
+    const access = typeof table.access === "string" && table.access.trim()
+        ? table.access.trim()
+        : null;
+    return {
+        description: table.description ?? null,
+        access,
+        inputSchema: table.inputSchema ?? null,
+        outputSchema: table.outputSchema ?? null,
+        entry: canonicalEntry(table.entry),
+        // #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
+        // `envelopeHash` change it also is. A file whose triggers do not parse is
+        // reported as drift rather than throwing out of a read-only diff: push is
+        // where the refusal belongs.
+        triggers: safeTriggers(table),
+        // #3182 — sorted on both sides: the row stores a SET, which has no order,
+        // so comparing authored order against it would report permanent drift.
+        capabilities: Array.isArray(table.capabilities)
+            ? [...new Set(table.capabilities.map((c) => String(c)))].sort()
+            : [],
+    };
+}
+function safeTriggers(table) {
+    try {
+        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.
+ *
+ * The same rule the server applies on the way in, applied again on the way out:
+ * the file is written to a developer's disk from a path the SERVER chose, so a
+ * second check here is the one that matters.
+ */
+export function unsafePulledPath(path) {
+    const raw = toPosix(String(path ?? ""));
+    if (!raw)
+        return "a stored source path is empty";
+    if (raw.startsWith("/") || /^[a-zA-Z]:\//.test(raw)) {
+        return `refused stored source path '${raw}': absolute paths are never written`;
+    }
+    if (raw.split("/").includes("..")) {
+        return `refused stored source path '${raw}': it normalizes outside the config tree`;
+    }
+    if (isDependencyPath(raw)) {
+        return `refused stored source path '${raw}': node_modules is never authored source`;
+    }
+    return null;
+}
+/**
+ * Plan the files `config pull` writes for one function: the authored TOML at
+ * `functions/<key>.toml`, and each stored source at its own path.
+ *
+ * Pure — the caller applies it — so the refusal rules are testable without a
+ * server and without touching a disk.
+ */
+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(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 ?? ""));
+        const refusal = unsafePulledPath(path);
+        if (refusal) {
+            refusals.push(refusal);
+            continue;
+        }
+        const absolute = resolve(root, path);
+        // Belt and braces: the string rules above state the contract, this catches
+        // a spelling they did not anticipate on a platform they were not written on.
+        const rel = relative(root, absolute);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            refusals.push(`refused stored source path '${path}': it normalizes outside the config tree`);
+            continue;
+        }
+        files.push({
+            relative: path,
+            absolute,
+            content: Buffer.from(String(source?.content ?? ""), "base64"),
+        });
+        sourcePaths.push(path);
+    }
+    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
+ * tree-relative, or null.
+ *
+ * `planFunctionPull`'s rules are lexical, and a lexical rule cannot see a
+ * SYMLINK: `functions/shared` pointing at `/etc` makes `functions/shared/x`
+ * normalize inside the tree and land outside it. So the last check before the
+ * write is against the real path — the deepest directory that already exists
+ * is resolved and must still be inside the real tree root, and an existing
+ * destination that is itself a symlink is refused rather than written through.
+ */
+function unsafeDestination(realRoot, absolute) {
+    const contained = (path) => path === realRoot || path.startsWith(realRoot + sep);
+    let dir = dirname(absolute);
+    while (!existsSync(dir)) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    let realDir;
+    try {
+        realDir = realpathSync(dir);
+    }
+    catch {
+        return `refused writing '${absolute}': its directory could not be resolved`;
+    }
+    if (!contained(realDir)) {
+        return (`refused writing '${absolute}': a symlinked directory takes it outside ` +
+            "the config tree");
+    }
+    try {
+        if (lstatSync(absolute).isSymbolicLink()) {
+            return (`refused writing '${absolute}': the destination is a symlink, and a ` +
+                "pull writes files, never through links");
+        }
+    }
+    catch {
+        /* the destination does not exist yet — the normal case */
+    }
+    return null;
+}
+/**
+ * Write a plan's files, creating the directories they need.
+ *
+ * Returns what was written and what was refused; a refusal is reported by the
+ * caller and keeps the file out of the sync state, so prune never claims to
+ * own a path this pull did not write.
+ */
+export function applyFunctionPull(plan) {
+    const outcome = { writtenSources: [], refusals: [] };
+    let realRoot;
+    try {
+        realRoot = realpathSync(plan.configDir);
+    }
+    catch {
+        realRoot = plan.configDir;
+    }
+    const sourcePaths = new Set(plan.sourcePaths ?? []);
+    for (const file of plan.files) {
+        const refusal = unsafeDestination(realRoot, file.absolute);
+        if (refusal) {
+            outcome.refusals.push(refusal);
+            continue;
+        }
+        const dir = dirname(file.absolute);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(file.absolute, file.content);
+        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