primitive-admin 1.1.0-alpha.74 → 1.1.0-alpha.76

package/dist/src/commands/sync.js

@@ -9,7 +9,8 @@ import { parseMetadataCategoryToml, validateMetadataCategoryConfig, serializeMet
 import { validateOperations, formatIssue, } from "../lib/toml-params-validator.js";
 import { isPlatformOwnedWorkflow, isPlatformOwnedWorkflowKey, } from "../lib/platform-owned.js";
 import { getServerUrl, resolveAppId } from "../lib/config.js";
-import { resolveSyncDir, resolveSnapshotsRoot, isAutoResolvedSyncDir, checkLegacySyncMigration, checkLegacyDatabaseTypesDir, } from "../lib/sync-paths.js";
+import { assertTreeApp } from "../lib/app-match-guard.js";
+import { resolveSyncDir, resolveSnapshotsRoot, assertSyncStateLayout, syncStatePath, SYNC_STATE_FILENAME, isAutoResolvedSyncDir, checkLegacySyncMigration, checkLegacyDatabaseTypesDir, } from "../lib/sync-paths.js";
 import { createSnapshot, listSnapshots, resolveSnapshot, restoreSnapshot, pruneSnapshots, } from "../lib/snapshots.js";
 import { validateWorkflowToml, collectWorkflowTomlNotes, formatWorkflowTomlErrors, validateWorkflowExpressionsToml, validateWorkflowExpressionsRawToml, } from "../lib/workflow-toml-validator.js";
 import { expandWorkflowTomlData } from "../lib/workflow-fragments.js";
@@ -36,6 +37,12 @@ import { CONFIG_SURFACES, isEmptyForEmit, } from "../lib/generated-config-surfac
 // `config push` sends, and the bytes `config pull` writes back.
 import { applyFunctionPull, buildFunctionConfigPush, buildFunctionCreatePayload, buildFunctionUpdatePayload, functionDiffEntity, planFunctionPull, serializeFunction, } from "../lib/function-sync.js";
 import { FunctionBuildError } from "../lib/function-bundle.js";
+// #3182 — the local half of capability validation. The grammar is the vendored
+// module the server also imports; this is where an author's own file is read.
+import { configObjectKeysFromTree, functionGrantErrors, mergeKnownGrantTargets, } from "../lib/function-grants-preflight.js";
+// #3182 — the typed handle's generated declarations and the compiler wiring
+// that makes an editor load them.
+import { functionTypeWiringProblems, staleFunctionTypeArtifacts, writeFunctionTypeArtifacts, } from "../lib/function-db-types.js";
 import { detectLayout, migrateLegacyToV2 } from "../lib/block-layout.js";
 import { ABSENT_FROM_EXPORT, LOCAL_ONLY_ABSENT, LOCAL_ONLY_NEW, PUSH_PRUNE_SPECS, REMOTE_ONLY_UNMANAGED, REMOTE_ONLY_WILL_DELETE, SYNC_RESOURCE_TYPES, VALIDATION_ERROR, applyPrune, attachmentWritePath, attemptFetch, classifyLocalOnly, classifyPruneDeleteFailure, classifyRemoteOnly, collectPushPruneCandidates, decidePushPruneCandidate, formatPrunePlan, hasUncommittedChanges, isSafeAttachmentFilename, isSafeSyncFilename, planPrune, preserveUnwrittenEntries, removePrunedSidecar, ruleSetFileKey, } from "../lib/sync-resource-types.js";
 import { normalizeTestCaseKey, testCaseKeyError, } from "../lib/test-case-keys.js";
@@ -68,7 +75,7 @@ function printStaleInstanceWarning(updated) {
     }
 }
 function loadSyncState(configDir) {
-    const syncFile = join(configDir, ".primitive-sync.json");
+    const syncFile = syncStatePath(configDir);
     if (!existsSync(syncFile)) {
         return null;
     }
@@ -80,7 +87,7 @@ function loadSyncState(configDir) {
     }
 }
 function saveSyncState(configDir, state) {
-    const syncFile = join(configDir, ".primitive-sync.json");
+    const syncFile = syncStatePath(configDir);
     writeFileSync(syncFile, JSON.stringify(state, null, 2));
 }
 /**
@@ -3202,6 +3209,114 @@ export function diffProjectedRecords(local, remote) {
     }
     return diffs;
 }
+/**
+ * The paths at which two projected records disagree, named the way the FILE
+ * spells them (#3267) — what a `config diff` Modified row prints.
+ *
+ * `diffProjectedRecords` answers at the granularity of the projection, and
+ * for a database type that is too coarse to act on: the 27 operations arrive
+ * as one `operations` extra, the whole `[models.*]` tree as one `schema`
+ * string. A row that read Modified for a reason the operator could not see —
+ * an empty params set spelled two ways, an operation block the file declares
+ * twice — was undiagnosable from the CLI. So this walks INTO each differing
+ * field: a keyed child collection (`spec.childKeys`) is compared row by row
+ * and named `operations["getInstitution"].params`, with a row only one side
+ * has or that the file repeats named as such; a TOML-string field
+ * (`spec.tomlFields`) is parsed on both sides and named by the path inside it
+ * (`schema (models.Institution.fields.name.required)`); everything else is
+ * walked as a value to its first differing leaf.
+ *
+ * Paths come back in projected-key order, keyed rows in key order, so the
+ * list is stable across runs, and every leaf is its own entry — a schema
+ * that differs in seven model fields is seven paths, so the caller's "+N
+ * more" cap counts them the way it counts operations. A value the walk
+ * cannot descend into (an array of a different length, a scalar against an
+ * object) is named at the level it stopped.
+ */
+export function describeProjectedDifferences(spec, local, remote) {
+    const paths = [];
+    for (const { field, local: l, server: r } of diffProjectedRecords(local, remote)) {
+        const childKey = spec.childKeys?.[field];
+        if (childKey && Array.isArray(l) && Array.isArray(r)) {
+            paths.push(...keyedChildDifferences(field, childKey, l, r));
+            continue;
+        }
+        if (spec.tomlFields?.includes(field) && typeof l === "string" && typeof r === "string") {
+            let inner;
+            try {
+                inner = valueDifferences("", parseConfigToml(l), parseConfigToml(r));
+            }
+            catch {
+                // A side that does not parse is named as the whole field below.
+            }
+            if (inner) {
+                if (inner.length === 0) {
+                    paths.push(field);
+                }
+                else {
+                    paths.push(...inner.map((path) => `${field} (${path})`));
+                }
+                continue;
+            }
+        }
+        paths.push(...valueDifferences(field, l, r));
+    }
+    return paths;
+}
+/** The leaf paths under `path` at which two values differ (see above). */
+function valueDifferences(path, a, b) {
+    if (canonicalJsonStringify(a) === canonicalJsonStringify(b))
+        return [];
+    const join = (key) => (path ? `${path}.${key}` : key);
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+        return keys.flatMap((key) => valueDifferences(join(key), a[key], b[key]));
+    }
+    if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) {
+        return a.flatMap((item, i) => valueDifferences(`${path}[${i}]`, item, b[i]));
+    }
+    return [path || "(document)"];
+}
+/**
+ * A keyed child collection's differences, row by row. A key the file repeats
+ * is named as the cause rather than compared: the server keys rows by it, so
+ * only one of the blocks landed and no push can make the two sides agree
+ * while the file says two things under one name.
+ */
+function keyedChildDifferences(field, key, local, remote) {
+    const label = (k) => `${field}[${JSON.stringify(k)}]`;
+    const localByKey = new Map();
+    for (const row of local) {
+        const k = String(row?.[key] ?? "");
+        localByKey.set(k, [...(localByKey.get(k) ?? []), row]);
+    }
+    const remoteByKey = new Map(remote.map((row) => [String(row?.[key] ?? ""), row]));
+    const keys = [...new Set([...localByKey.keys(), ...remoteByKey.keys()])].sort();
+    const paths = [];
+    for (const k of keys) {
+        const rows = localByKey.get(k);
+        const remoteRow = remoteByKey.get(k);
+        if (rows && rows.length > 1) {
+            paths.push(`${label(k)} (declared ${rows.length} times locally)`);
+        }
+        else if (!rows) {
+            paths.push(`${label(k)} (server only)`);
+        }
+        else if (remoteRow === undefined) {
+            paths.push(`${label(k)} (local only)`);
+        }
+        else {
+            paths.push(...valueDifferences(label(k), rows[0], remoteRow));
+        }
+    }
+    return paths;
+}
+function isPlainObject(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        typeof value.toJSON !== "function");
+}
 /**
  * The differing fields the definition says an UPDATE does not accept (#2731 B8).
  *
@@ -3402,6 +3517,12 @@ const CONFIG_DIFF_SPECS = {
             entry: entity.entry ?? null,
             durable: entity.durable === true,
             limits: entity.limits ?? null,
+            // #3182 — the grants are version-carried too, and a widened grant set is
+            // exactly the change a reviewer must not read as Synced. Sorted because
+            // the row stores a set.
+            capabilities: Array.isArray(entity.capabilities)
+                ? [...entity.capabilities].map((c) => String(c)).sort()
+                : [],
         }),
         describe: (entity) => `function "${entity?.functionKey}"`,
     },
@@ -3678,6 +3799,8 @@ const CONFIG_DIFF_SPECS = {
             subscriptions: byKey(entity.__subscriptions, "subscriptionKey"),
             _unresolvedRuleSetName: entity._unresolvedRuleSetName,
         }),
+        childKeys: { operations: "name", subscriptions: "subscriptionKey" },
+        tomlFields: ["schema"],
         ruleSetRef: true,
         describe: (entity) => `database type "${entity?.databaseType}"`,
     },
@@ -3772,9 +3895,11 @@ export function compareLocalToRemote(spec, localParsed, remoteRecord, maps = {
         const localHash = computeExpandedContentHash(pair.local);
         if (remoteHash === localHash)
             return { status: "exists" };
+        // #3267 — WHICH field, ahead of the remedy, so a row that differs for a
+        // reason the operator cannot see in the file is diagnosable from the CLI.
         return {
             status: "modified",
-            hint: "run `config pull` to rewrite the local TOML to match running state",
+            hint: namedDifferences(describeProjectedDifferences(spec, pair.local, pair.remote)) + "run `config pull` to rewrite the local TOML to match running state",
         };
     }
     catch {
@@ -3783,6 +3908,24 @@ export function compareLocalToRemote(spec, localParsed, remoteRecord, maps = {
         return { status: "exists", hint: "content not compared (comparison failed)" };
     }
 }
+/**
+ * How many differing paths a Modified row names before saying "+N more"
+ * (#3267). Enough to see the shape of a difference at a glance; the row is
+ * one line of a whole-tree diff, not the place to print 27 operations.
+ */
+const NAMED_DIFFERENCE_LIMIT = 5;
+/**
+ * The `differs in …; ` prefix of a Modified row's hint (#3267), or nothing
+ * when the walk could name no path — the hash still differs, so the row is
+ * still Modified, but the hint then says only what it always said.
+ */
+function namedDifferences(paths) {
+    if (paths.length === 0)
+        return "";
+    const shown = paths.slice(0, NAMED_DIFFERENCE_LIMIT).join(", ");
+    const more = paths.length - NAMED_DIFFERENCE_LIMIT;
+    return `differs in ${shown}${more > 0 ? ` (+${more} more)` : ""}; `;
+}
 /** Hash a LOCAL config file's definition-projected field set (#2644). */
 export function hashLocalConfigForDiff(spec, parsedToml, maps, extra) {
     return computeExpandedContentHash(projectLocalConfig(spec, parsedToml, maps, extra));
@@ -4222,7 +4365,7 @@ export function configSemanticHash(label, filePath, maps) {
 /**
  * The sync state `config push` writes into (#2731 B6, closing #2374).
  *
- * `loadSyncState` answers `null` for an absent `.primitive-sync.json`, and
+ * `loadSyncState` answers `null` for an absent sync-state baseline, and
  * every per-entity state write in the push loops is guarded by `if (syncState)`
  * — so a first push created every resource and recorded none of them. The next
  * push then re-entered the create path for everything and depended on 409
@@ -6276,7 +6419,7 @@ function readSelection(options) {
  * `registerConfigCommands` created rather than making one of its own.
  *
  * The module keeps its name and its ~50 exported helpers: `sync.ts`,
- * `resolveSyncDir`, `.primitive-sync.json` and `.primitive/sync/<env>/<appId>/`
+ * `resolveSyncDir`, the sync-state baseline and `primitive/<env>/`
  * are internal identifiers, deliberately left alone (#2759 scope).
  */
 export function registerConfigSyncCommands(sync) {
@@ -6288,8 +6431,14 @@ export function registerConfigSyncCommands(sync) {
         .option("--app <app-id>", "App ID")
         .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
         .action(async (appId, options) => {
+        // Refused before any tree read/write or request (#3153, F1): the tree
+        // path no longer partitions by app.
+        assertTreeApp(appId || options.app, "config init");
         const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
+        const configDir = resolveSyncDir({ userDir: options.dir });
+        // A baseline that was never renamed means an unmigrated tree; refused
+        // here, before any request, snapshot or directory is made (#3153).
+        assertSyncStateLayout(configDir);
         if (isAutoResolvedSyncDir(options.dir)) {
             info(`Using per-environment config directory: ${configDir}`);
             const legacyHint = checkLegacySyncMigration(configDir);
@@ -6336,8 +6485,14 @@ export function registerConfigSyncCommands(sync) {
     (value, previous) => [...(previous ?? []), value], [])
         .option("--no-prune", "Keep local files for entities that are absent from the sync export (the next push will re-create them)")
         .action(async (appId, options) => {
+        // Refused before any tree read/write or request (#3153, F1): the tree
+        // path no longer partitions by app.
+        assertTreeApp(appId || options.app, "config pull");
         const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
+        const configDir = resolveSyncDir({ userDir: options.dir });
+        // A baseline that was never renamed means an unmigrated tree; refused
+        // here, before any request, snapshot or directory is made (#3153).
+        assertSyncStateLayout(configDir);
         if (isAutoResolvedSyncDir(options.dir) && !options.json) {
             info(`Using per-environment config directory: ${configDir}`);
             const legacyHint = checkLegacySyncMigration(configDir);
@@ -7125,6 +7280,16 @@ export function registerConfigSyncCommands(sync) {
                 };
                 info(`  Wrote database-type-configs/${filename}`);
             }
+            // #3182 — the typed-handle artifacts are REGENERATED, never pulled:
+            // they are not in the envelope, and a fresh clone must end up with the
+            // same three files a push would have written. Written here, after the
+            // database types, so the declaration describes what this pull wrote.
+            {
+                const artifacts = writeFunctionTypeArtifacts(configDir);
+                if (artifacts.length > 0) {
+                    info(`  Wrote function types: ${artifacts.join(", ")}`);
+                }
+            }
             // Write rule sets
             const ruleSetEntities = {};
             for (const ruleSet of ruleSets) {
@@ -7618,8 +7783,14 @@ export function registerConfigSyncCommands(sync) {
         .option("-y, --yes", "Skip the interactive confirmation before pruning (for CI / automation)")
         .option("--accept-warnings", "Commit schema diffs that have operations with dynamic refs (issue #666 SCHEMA_HAS_UNCHECKABLE_OPS escape hatch)")
         .action(async (appId, options) => {
+        // Refused before any tree read/write or request (#3153, F1): the tree
+        // path no longer partitions by app.
+        assertTreeApp(appId || options.app, "config push");
         const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
+        const configDir = resolveSyncDir({ userDir: options.dir });
+        // A baseline that was never renamed means an unmigrated tree; refused
+        // here, before any request, snapshot or directory is made (#3153).
+        assertSyncStateLayout(configDir);
         if (isAutoResolvedSyncDir(options.dir)) {
             info(`Using per-environment config directory: ${configDir}`);
             const legacyHint = checkLegacySyncMigration(configDir);
@@ -8086,7 +8257,7 @@ export function registerConfigSyncCommands(sync) {
             // known-bad sibling file (e.g. an invalid workflow TOML) could let an
             // earlier create (a cron trigger) be applied, then abort. The
             // `process.exit` also bypassed the save-on-failure catch below, so the
-            // orphaned create never reached `.primitive-sync.json` and the retry
+            // orphaned create never reached the sync-state baseline and the retry
             // re-issued a CREATE that the server rejected with 409 forever.
             //
             // Running every validation up-front means a known-bad file aborts
@@ -8268,6 +8439,56 @@ export function registerConfigSyncCommands(sync) {
                     preflightValidationErrors.push(`  vars.toml: ${err?.message || String(err)}`);
                 }
             }
+            // #3182 — a function's capabilities, checked against the author's own
+            // file before anything is applied. The grammar is purely local (and
+            // since #3279 it keeps three kinds: `integration:<key>`,
+            // `secret:<NAME>` and the high-blast opt-ins — a retired grant string
+            // is refused here with the retirement); whether an `integration:`
+            // names an integration that will exist is answered against the
+            // tree's own `integrations/` (applied BEFORE functions) merged with
+            // the integrations the server already has. If the live listing cannot
+            // be fetched and the tree declares none, the target check is skipped
+            // and the server — which is authoritative — has the last word.
+            const preflightFunctionsDir = join(configDir, "functions");
+            if (existsSync(preflightFunctionsDir)) {
+                const functionFiles = selectFiles("function", preflightFunctionsDir, readdirSync(preflightFunctionsDir).filter((f) => f.endsWith(".toml")));
+                if (functionFiles.length > 0) {
+                    const treeTargets = configObjectKeysFromTree(configDir);
+                    let knownTargets = null;
+                    try {
+                        const integrations = await client.listIntegrations(resolvedAppId, {
+                            status: "active",
+                        });
+                        knownTargets = mergeKnownGrantTargets({
+                            integrations: new Set((integrations?.items ?? [])
+                                .map((row) => String(row?.integrationKey ?? ""))
+                                .filter(Boolean)),
+                        }, treeTargets);
+                    }
+                    catch {
+                        knownTargets =
+                            treeTargets.integrations.size > 0 ? treeTargets : null;
+                    }
+                    for (const file of functionFiles) {
+                        const filePath = join(preflightFunctionsDir, file);
+                        let tomlData;
+                        try {
+                            tomlData = parseTomlFile(filePath);
+                        }
+                        catch (err) {
+                            preflightValidationErrors.push(`  ${filePath}: ${err?.message || String(err)}`);
+                            continue;
+                        }
+                        for (const message of functionGrantErrors({
+                            filePath,
+                            tomlData,
+                            knownTargets,
+                        })) {
+                            preflightValidationErrors.push(`  ${message}`);
+                        }
+                    }
+                }
+            }
             // #2644 — reject any key the vendored definition does not recognize,
             // for every migrated configuration type. Same posture the `[workflow]`
             // check above has, generalized: a mistyped key fails here, in the
@@ -10865,332 +11086,77 @@ export function registerConfigSyncCommands(sync) {
                     }
                 }
             }
-            // Process server functions — #3179.
-            //
-            // A function pushes on TWO axes and they are deliberately independent:
-            //
-            //   - the HEADER (`[function]`'s gate, runAs, schemas, plus the three
-            //     version-carried keys, all compared through the shared gate), and
-            //   - the CODE — the authored TOML bytes, every source file and the
-            //     built bundle, sent as one immutable config VERSION.
-            //
-            // Independent because a comment-only edit to a source file leaves the
-            // header identical and must still make a version (F-003): gating the
-            // code push on the header comparison would silently discard it. The
-            // code axis compares `envelopeHash`, which is also what the SERVER
-            // dedupes on, so an unchanged push makes no version on either side's
-            // reckoning.
-            //
-            // The bundle is built FIRST, so a build error, a missing entry or an
-            // import that escapes the config tree aborts this function before
-            // anything is sent for it (behavior 12).
-            const functionsPushDir = join(configDir, "functions");
-            if (existsSync(functionsPushDir)) {
-                const files = selectFiles("function", functionsPushDir, readdirSync(functionsPushDir).filter((f) => f.endsWith(".toml")));
-                const functionSpec = configDiffSpec("function");
-                const liveFunctions = new Map();
-                let functionsLiveOk = true;
-                if (files.length > 0) {
-                    try {
-                        const listed = await client.listFunctions(resolvedAppId);
-                        for (const f of (listed?.items ?? [])) {
-                            if (f?.functionKey)
-                                liveFunctions.set(f.functionKey, f);
+            // Process workflows
+            const workflowsDir = join(configDir, "workflows");
+            if (existsSync(workflowsDir)) {
+                const files = selectFiles("workflow", workflowsDir, readdirSync(workflowsDir).filter((f) => f.endsWith(".toml")));
+                // #2896 — pairing for a clone with no sync state. A workflow the
+                // manifest has no row for is not thereby a create: the create path
+                // below already adopts an existing workflow by key on the server's
+                // 409 (#1006/#1174), so letting live state answer the same question
+                // one step earlier is that same adopt — reached before a doomed
+                // create is sent, which is what the prompt reconcile does (#2909).
+                // Without it a stateless clone plans "create workflow" for every
+                // workflow the server already holds, and its `.tests/` sidecars —
+                // addressed through the sync-state id the plan never records —
+                // cascade into duplicate test-case creates. Fetched once, and only
+                // when a file is actually untracked; a failed listing degrades to
+                // the create-then-409 path, which still converges.
+                let liveWorkflowIdsByKey;
+                const lookupLiveWorkflowId = async (workflowKey) => {
+                    if (liveWorkflowIdsByKey === undefined) {
+                        try {
+                            const live = await fetchAll((p) => client.listWorkflows(resolvedAppId, p));
+                            liveWorkflowIdsByKey = new Map(live
+                                .filter((w) => w?.workflowKey && w?.workflowId)
+                                .map((w) => [
+                                w.workflowKey,
+                                w.workflowId,
+                            ]));
+                        }
+                        catch (err) {
+                            liveWorkflowIdsByKey = null;
+                            warn(`  workflows: live state unavailable (${err instanceof Error ? err.message : String(err)}) — an untracked workflow plans a create and adopts on the server's conflict`);
                         }
                     }
-                    catch (err) {
-                        functionsLiveOk = false;
-                        warnLiveUnavailable("functions", err);
-                    }
-                }
-                /** The version a function currently runs, or null. */
-                const liveActiveVersion = async (functionId, activeConfigId) => {
-                    if (!activeConfigId)
-                        return null;
-                    const { items } = await client.listFunctionConfigs(resolvedAppId, functionId);
-                    return ((items || []).find((c) => String(c.configId) === String(activeConfigId)) ?? null);
+                    return liveWorkflowIdsByKey?.get(workflowKey);
                 };
                 for (const file of files) {
-                    const filePath = join(functionsPushDir, file);
+                    const filePath = join(workflowsDir, file);
                     const tomlData = parseTomlFile(filePath);
-                    const key = tomlData.function?.key || basename(file, ".toml");
-                    withDerivedIdentity(tomlData, "function", { key });
-                    const existingEntry = syncState?.entities?.functions?.[key];
-                    const liveFunction = liveFunctions.get(key);
-                    // Build first: nothing is sent for a function whose code does not
-                    // compile or whose imports leave the tree.
-                    let push;
-                    try {
-                        push = await buildFunctionConfigPush({
-                            configDir,
-                            functionKey: key,
-                            filePath,
-                            tomlData,
-                        });
-                    }
-                    catch (err) {
-                        if (!(err instanceof FunctionBuildError))
-                            throw err;
-                        applyFailures.push({
-                            type: "function",
-                            key,
-                            message: err.message,
-                        });
+                    // #1660 — skip platform-owned workflows (the reserved `__internal.*`
+                    // namespace). Resolve the key FIRST and skip BEFORE the workflow
+                    // TOML validation below, so a hollow exported `__internal.*.toml`
+                    // (steps = [], no active config) is skipped, not failed by
+                    // `validateWorkflowToml`, and does not abort the whole push trying
+                    // to activate a configuration-less workflow. Match on the resolved
+                    // `[workflow].key` (not filename) so a renamed file is still caught
+                    // (edge case 2).
+                    const platformOwnedKey = tomlData.workflow?.key || basename(file, ".toml");
+                    if (isPlatformOwnedWorkflowKey(platformOwnedKey)) {
+                        info(`  Skipped workflows/${file} — platform-owned workflow "${platformOwnedKey}" (managed by the platform)`);
                         continue;
                     }
-                    // The active version, needed by BOTH axes: the header comparison
-                    // reads `entry`/`durable`/`limits` off it, and the code axis
-                    // compares its `envelopeHash`.
-                    let activeVersion = null;
-                    let versionOk = functionsLiveOk;
-                    if (functionsLiveOk && liveFunction?.functionId) {
-                        try {
-                            activeVersion = await liveActiveVersion(liveFunction.functionId, liveFunction.activeConfigId);
-                        }
-                        catch (err) {
-                            versionOk = false;
-                            warnLiveUnavailable(`function ${key}`, err);
-                        }
-                    }
-                    let headerAction = "skip";
-                    if (versionOk && functionsLiveOk) {
-                        const gate = decidePushForConfig({
-                            spec: functionSpec,
-                            maps: pushDiffMaps,
-                            localParsed: tomlData,
-                            live: liveFunction
-                                ? {
-                                    record: liveFunction,
-                                    // The version-carried keys the remote side is projected
-                                    // through; the header row does not hold them.
-                                    extra: activeVersion ?? undefined,
-                                    modifiedAt: liveFunction.modifiedAt,
-                                }
-                                : null,
-                            entry: existingEntry,
-                            localFileHash: computeFileHash(filePath),
-                            force: options.force,
-                            // The create leg adopts by key on the server's 409 (#1006), so
-                            // an untracked function the server already holds is that same
-                            // adopt reached one step earlier.
-                            adoptsUntrackedByKey: true,
-                        });
-                        if (gate.action === "drift" ||
-                            gate.action === "conflict" ||
-                            gate.action === "immutable") {
-                            recordDeclined("function", key, gate, existingEntry?.modifiedAt);
-                            continue;
-                        }
-                        headerAction = gate.action === "skip"
-                            ? "skip"
-                            : liveFunction
-                                ? "update"
-                                : "create";
+                    // Reject misnested headers (#685, e.g. [steps.<id>.request]) and
+                    // the #1447 runAs="system" + accessRule dead-config combo before
+                    // pushing. The runtime silently ignores fields outside the
+                    // allowlist, so this is the only place to catch the footgun, and
+                    // the server rejects a system accessRule (#1258) — flagging it
+                    // here keeps the push all-or-nothing. Validation happens BEFORE the
+                    // skip-if-unchanged check so a previously-pushed-but-broken
+                    // file gets a clear diagnostic on every push attempt.
+                    // Issue #976: validation is now front-loaded before any apply
+                    // (see the pre-flight pass above). This in-loop check remains as
+                    // defense-in-depth, but THROWS rather than `process.exit(1)` so the
+                    // single save-on-failure catch is the only exit path — never
+                    // bypassing it and orphaning an already-created resource.
+                    const tomlErrors = validateWorkflowToml(tomlData);
+                    if (tomlErrors.length > 0) {
+                        throw new Error(formatWorkflowTomlErrors(filePath, tomlErrors));
                     }
-                    else {
-                        const degraded = decideDegradedPush({
-                            force: options.force,
-                            storedContentHash: existingEntry?.contentHash,
-                            currentFileHash: computeFileHash(filePath),
-                        });
-                        if (degraded.action === "decline") {
-                            recordDeclined("function", key, { action: "live-unavailable" }, existingEntry?.modifiedAt);
-                            continue;
-                        }
-                        headerAction = degraded.action === "skip"
-                            ? "skip"
-                            : liveFunction
-                                ? "update"
-                                : "create";
-                    }
-                    // The code axis. `envelopeHash` is the server's own no-op test, so
-                    // matching it here means the call would create nothing.
-                    const codeUnchanged = !!liveFunction &&
-                        !!activeVersion &&
-                        String(activeVersion.envelopeHash ?? "") === push.envelopeHash;
-                    if (headerAction === "skip" && codeUnchanged) {
-                        skippedCount++;
-                        if (syncState && liveFunction?.functionId) {
-                            if (!syncState.entities.functions)
-                                syncState.entities.functions = {};
-                            syncState.entities.functions[key] = {
-                                ...(existingEntry ?? {}),
-                                id: liveFunction.functionId,
-                                modifiedAt: liveFunction.modifiedAt ||
-                                    existingEntry?.modifiedAt ||
-                                    new Date().toISOString(),
-                                contentHash: computeFileHash(filePath),
-                                semanticHash: hashRemoteConfigForDiff(functionSpec, liveFunction, pushDiffMaps, activeVersion ?? undefined),
-                                envelopeHash: push.envelopeHash,
-                                activeConfigId: activeVersion?.configId,
-                                sources: push.sources.map((src) => src.path),
-                            };
-                        }
-                        continue;
-                    }
-                    changes.push({
-                        type: "function",
-                        action: liveFunction ? "update" : "create",
-                        key,
-                    });
-                    if (options.dryRun)
-                        continue;
-                    // Every server refusal below is recorded against THIS function and
-                    // the loop moves on. A single archived tombstone — or a key the
-                    // app's namespace already holds — must not abort a push carrying
-                    // unrelated changes: the run reports what it could not apply, exits
-                    // non-zero, and everything else in the tree still lands. That is
-                    // the same contract `applyFailures` gives every other type; a throw
-                    // here would let one refusal block a whole repository.
-                    let functionId = liveFunction?.functionId ?? existingEntry?.id;
-                    let pushedVersion;
-                    try {
-                        if (!functionId) {
-                            const created = await client.createFunction(resolvedAppId, buildFunctionCreatePayload(key, tomlData.function ?? {})).catch(async (err) => {
-                                // #1006 — a function the server already holds under this key
-                                // is adopted rather than re-created. The conflict may name a
-                                // WORKFLOW, a script or a webhook instead: those are the
-                                // single key namespace refusing the key, and they are not
-                                // adoptable, so `adoptByKeyOnCreate409` re-throws the original
-                                // error with its holder named.
-                                const existing = await adoptByKeyOnCreate409({
-                                    err,
-                                    kind: "function",
-                                    key,
-                                    lookup: async () => (await client.listFunctions(resolvedAppId)).items || [],
-                                    matchKey: (f) => f?.functionKey === key,
-                                });
-                                return existing;
-                            });
-                            functionId = created.functionId;
-                            info(`  Created function: ${key}`);
-                        }
-                        else if (headerAction !== "skip") {
-                            const updatePayload = buildFunctionUpdatePayload(tomlData.function ?? {});
-                            if (Object.keys(updatePayload).length > 0) {
-                                await client.updateFunction(resolvedAppId, functionId, updatePayload);
-                            }
-                            info(`  Updated function: ${key}`);
-                        }
-                        // The version. `status` is NEVER in this body: pushing code to a
-                        // disabled function updates it and leaves it out of service
-                        // (#2803's resurrection guard), and a push to an archived one is
-                        // refused by the server with the archived-holder message — which
-                        // names the remedies that release its key.
-                        pushedVersion = await client.pushFunctionConfig(resolvedAppId, String(functionId), push);
-                    }
-                    catch (err) {
-                        applyFailures.push({
-                            type: "function",
-                            key,
-                            message: String(err?.message ?? err),
-                        });
-                        continue;
-                    }
-                    if (pushedVersion?.created === false) {
-                        info(`  Function ${key}: code unchanged (no new version)`);
-                    }
-                    else {
-                        info(`  Pushed function ${key} version ${pushedVersion?.configId ?? ""}`.trim());
-                    }
-                    if (syncState) {
-                        if (!syncState.entities.functions)
-                            syncState.entities.functions = {};
-                        let refreshed = liveFunction;
-                        try {
-                            refreshed = await client.getFunction(resolvedAppId, String(functionId));
-                        }
-                        catch {
-                            // Non-fatal: the baseline falls back to what the listing said.
-                            // The next push reconciles it.
-                        }
-                        syncState.entities.functions[key] = {
-                            id: String(functionId),
-                            modifiedAt: refreshed?.modifiedAt ||
-                                existingEntry?.modifiedAt ||
-                                new Date().toISOString(),
-                            contentHash: computeFileHash(filePath),
-                            semanticHash: refreshed
-                                ? hashRemoteConfigForDiff(functionSpec, refreshed, pushDiffMaps, pushedVersion ?? undefined)
-                                : undefined,
-                            envelopeHash: push.envelopeHash,
-                            activeConfigId: pushedVersion?.configId,
-                            sources: push.sources.map((src) => src.path),
-                        };
-                    }
-                }
-            }
-            // Process workflows
-            const workflowsDir = join(configDir, "workflows");
-            if (existsSync(workflowsDir)) {
-                const files = selectFiles("workflow", workflowsDir, readdirSync(workflowsDir).filter((f) => f.endsWith(".toml")));
-                // #2896 — pairing for a clone with no sync state. A workflow the
-                // manifest has no row for is not thereby a create: the create path
-                // below already adopts an existing workflow by key on the server's
-                // 409 (#1006/#1174), so letting live state answer the same question
-                // one step earlier is that same adopt — reached before a doomed
-                // create is sent, which is what the prompt reconcile does (#2909).
-                // Without it a stateless clone plans "create workflow" for every
-                // workflow the server already holds, and its `.tests/` sidecars —
-                // addressed through the sync-state id the plan never records —
-                // cascade into duplicate test-case creates. Fetched once, and only
-                // when a file is actually untracked; a failed listing degrades to
-                // the create-then-409 path, which still converges.
-                let liveWorkflowIdsByKey;
-                const lookupLiveWorkflowId = async (workflowKey) => {
-                    if (liveWorkflowIdsByKey === undefined) {
-                        try {
-                            const live = await fetchAll((p) => client.listWorkflows(resolvedAppId, p));
-                            liveWorkflowIdsByKey = new Map(live
-                                .filter((w) => w?.workflowKey && w?.workflowId)
-                                .map((w) => [
-                                w.workflowKey,
-                                w.workflowId,
-                            ]));
-                        }
-                        catch (err) {
-                            liveWorkflowIdsByKey = null;
-                            warn(`  workflows: live state unavailable (${err instanceof Error ? err.message : String(err)}) — an untracked workflow plans a create and adopts on the server's conflict`);
-                        }
-                    }
-                    return liveWorkflowIdsByKey?.get(workflowKey);
-                };
-                for (const file of files) {
-                    const filePath = join(workflowsDir, file);
-                    const tomlData = parseTomlFile(filePath);
-                    // #1660 — skip platform-owned workflows (the reserved `__internal.*`
-                    // namespace). Resolve the key FIRST and skip BEFORE the workflow
-                    // TOML validation below, so a hollow exported `__internal.*.toml`
-                    // (steps = [], no active config) is skipped, not failed by
-                    // `validateWorkflowToml`, and does not abort the whole push trying
-                    // to activate a configuration-less workflow. Match on the resolved
-                    // `[workflow].key` (not filename) so a renamed file is still caught
-                    // (edge case 2).
-                    const platformOwnedKey = tomlData.workflow?.key || basename(file, ".toml");
-                    if (isPlatformOwnedWorkflowKey(platformOwnedKey)) {
-                        info(`  Skipped workflows/${file} — platform-owned workflow "${platformOwnedKey}" (managed by the platform)`);
-                        continue;
-                    }
-                    // Reject misnested headers (#685, e.g. [steps.<id>.request]) and
-                    // the #1447 runAs="system" + accessRule dead-config combo before
-                    // pushing. The runtime silently ignores fields outside the
-                    // allowlist, so this is the only place to catch the footgun, and
-                    // the server rejects a system accessRule (#1258) — flagging it
-                    // here keeps the push all-or-nothing. Validation happens BEFORE the
-                    // skip-if-unchanged check so a previously-pushed-but-broken
-                    // file gets a clear diagnostic on every push attempt.
-                    // Issue #976: validation is now front-loaded before any apply
-                    // (see the pre-flight pass above). This in-loop check remains as
-                    // defense-in-depth, but THROWS rather than `process.exit(1)` so the
-                    // single save-on-failure catch is the only exit path — never
-                    // bypassing it and orphaning an already-created resource.
-                    const tomlErrors = validateWorkflowToml(tomlData);
-                    if (tomlErrors.length > 0) {
-                        throw new Error(formatWorkflowTomlErrors(filePath, tomlErrors));
-                    }
-                    const unknownKeyError = workflowUnknownKeyError(filePath, tomlData);
-                    if (unknownKeyError) {
-                        throw new Error(unknownKeyError);
+                    const unknownKeyError = workflowUnknownKeyError(filePath, tomlData);
+                    if (unknownKeyError) {
+                        throw new Error(unknownKeyError);
                     }
                     const workflow = tomlData.workflow || {};
                     const key = workflow.key || basename(file, ".toml");
@@ -12509,7 +12475,7 @@ export function registerConfigSyncCommands(sync) {
                                     //
                                     // But the 409 also fires when the local sync state is merely
                                     // ABSENT for a type that another admin has already FULLY
-                                    // configured (or whose `.primitive-sync.json` was not copied
+                                    // configured (or whose sync-state baseline was not copied
                                     // alongside the TOML). PATCHing that without
                                     // `expectedModifiedAt` would silently overwrite the existing
                                     // triggers/access/schema with the local TOML — with no
@@ -12953,6 +12919,279 @@ export function registerConfigSyncCommands(sync) {
                     }
                 }
             }
+            // Process server functions — #3179.
+            //
+            // A function pushes on TWO axes and they are deliberately independent:
+            //
+            //   - the HEADER (`[function]`'s gate, schemas, plus the three
+            //     version-carried keys, all compared through the shared gate), and
+            //   - the CODE — the authored TOML bytes, every source file and the
+            //     built bundle, sent as one immutable config VERSION.
+            //
+            // Independent because a comment-only edit to a source file leaves the
+            // header identical and must still make a version (F-003): gating the
+            // code push on the header comparison would silently discard it. The
+            // code axis compares `envelopeHash`, which is also what the SERVER
+            // dedupes on, so an unchanged push makes no version on either side's
+            // reckoning.
+            //
+            // The bundle is built FIRST, so a build error, a missing entry or an
+            // import that escapes the config tree aborts this function before
+            // anything is sent for it (behavior 12).
+            const functionsPushDir = join(configDir, "functions");
+            if (existsSync(functionsPushDir)) {
+                // #3182 — the typed handle. Written BEFORE the bundles are built, so
+                // an author who runs `config push` after editing a schema gets the
+                // declaration their next edit is typed against, and written from the
+                // TREE rather than from the server: the types describe the schemas
+                // this push is applying. Regenerated every time and never part of the
+                // envelope — `config pull` recreates them the same way.
+                if (!options.dryRun) {
+                    const artifacts = writeFunctionTypeArtifacts(configDir);
+                    if (artifacts.length > 0) {
+                        info(`  Wrote function types: ${artifacts.join(", ")}`);
+                    }
+                }
+                // A tsconfig push will not rewrite (comments are the author's) or
+                // cannot read is still a tsconfig no compiler loads the handle
+                // through. Say so rather than report success over it (CR3182-003).
+                for (const problem of functionTypeWiringProblems(configDir)) {
+                    warn(`  functions/tsconfig.json: ${problem}`);
+                }
+                const files = selectFiles("function", functionsPushDir, readdirSync(functionsPushDir).filter((f) => f.endsWith(".toml")));
+                const functionSpec = configDiffSpec("function");
+                const liveFunctions = new Map();
+                let functionsLiveOk = true;
+                if (files.length > 0) {
+                    try {
+                        const listed = await client.listFunctions(resolvedAppId);
+                        for (const f of (listed?.items ?? [])) {
+                            if (f?.functionKey)
+                                liveFunctions.set(f.functionKey, f);
+                        }
+                    }
+                    catch (err) {
+                        functionsLiveOk = false;
+                        warnLiveUnavailable("functions", err);
+                    }
+                }
+                /** The version a function currently runs, or null. */
+                const liveActiveVersion = async (functionId, activeConfigId) => {
+                    if (!activeConfigId)
+                        return null;
+                    const { items } = await client.listFunctionConfigs(resolvedAppId, functionId);
+                    return ((items || []).find((c) => String(c.configId) === String(activeConfigId)) ?? null);
+                };
+                for (const file of files) {
+                    const filePath = join(functionsPushDir, file);
+                    const tomlData = parseTomlFile(filePath);
+                    const key = tomlData.function?.key || basename(file, ".toml");
+                    withDerivedIdentity(tomlData, "function", { key });
+                    const existingEntry = syncState?.entities?.functions?.[key];
+                    const liveFunction = liveFunctions.get(key);
+                    // Build first: nothing is sent for a function whose code does not
+                    // compile or whose imports leave the tree.
+                    let push;
+                    try {
+                        push = await buildFunctionConfigPush({
+                            configDir,
+                            functionKey: key,
+                            filePath,
+                            tomlData,
+                        });
+                    }
+                    catch (err) {
+                        if (!(err instanceof FunctionBuildError))
+                            throw err;
+                        applyFailures.push({
+                            type: "function",
+                            key,
+                            message: err.message,
+                        });
+                        continue;
+                    }
+                    // The active version, needed by BOTH axes: the header comparison
+                    // reads `entry`/`durable`/`limits` off it, and the code axis
+                    // compares its `envelopeHash`.
+                    let activeVersion = null;
+                    let versionOk = functionsLiveOk;
+                    if (functionsLiveOk && liveFunction?.functionId) {
+                        try {
+                            activeVersion = await liveActiveVersion(liveFunction.functionId, liveFunction.activeConfigId);
+                        }
+                        catch (err) {
+                            versionOk = false;
+                            warnLiveUnavailable(`function ${key}`, err);
+                        }
+                    }
+                    let headerAction = "skip";
+                    if (versionOk && functionsLiveOk) {
+                        const gate = decidePushForConfig({
+                            spec: functionSpec,
+                            maps: pushDiffMaps,
+                            localParsed: tomlData,
+                            live: liveFunction
+                                ? {
+                                    record: liveFunction,
+                                    // The version-carried keys the remote side is projected
+                                    // through; the header row does not hold them.
+                                    extra: activeVersion ?? undefined,
+                                    modifiedAt: liveFunction.modifiedAt,
+                                }
+                                : null,
+                            entry: existingEntry,
+                            localFileHash: computeFileHash(filePath),
+                            force: options.force,
+                            // The create leg adopts by key on the server's 409 (#1006), so
+                            // an untracked function the server already holds is that same
+                            // adopt reached one step earlier.
+                            adoptsUntrackedByKey: true,
+                        });
+                        if (gate.action === "drift" ||
+                            gate.action === "conflict" ||
+                            gate.action === "immutable") {
+                            recordDeclined("function", key, gate, existingEntry?.modifiedAt);
+                            continue;
+                        }
+                        headerAction = gate.action === "skip"
+                            ? "skip"
+                            : liveFunction
+                                ? "update"
+                                : "create";
+                    }
+                    else {
+                        const degraded = decideDegradedPush({
+                            force: options.force,
+                            storedContentHash: existingEntry?.contentHash,
+                            currentFileHash: computeFileHash(filePath),
+                        });
+                        if (degraded.action === "decline") {
+                            recordDeclined("function", key, { action: "live-unavailable" }, existingEntry?.modifiedAt);
+                            continue;
+                        }
+                        headerAction = degraded.action === "skip"
+                            ? "skip"
+                            : liveFunction
+                                ? "update"
+                                : "create";
+                    }
+                    // The code axis. `envelopeHash` is the server's own no-op test, so
+                    // matching it here means the call would create nothing.
+                    const codeUnchanged = !!liveFunction &&
+                        !!activeVersion &&
+                        String(activeVersion.envelopeHash ?? "") === push.envelopeHash;
+                    if (headerAction === "skip" && codeUnchanged) {
+                        skippedCount++;
+                        if (syncState && liveFunction?.functionId) {
+                            if (!syncState.entities.functions)
+                                syncState.entities.functions = {};
+                            syncState.entities.functions[key] = {
+                                ...(existingEntry ?? {}),
+                                id: liveFunction.functionId,
+                                modifiedAt: liveFunction.modifiedAt ||
+                                    existingEntry?.modifiedAt ||
+                                    new Date().toISOString(),
+                                contentHash: computeFileHash(filePath),
+                                semanticHash: hashRemoteConfigForDiff(functionSpec, liveFunction, pushDiffMaps, activeVersion ?? undefined),
+                                envelopeHash: push.envelopeHash,
+                                activeConfigId: activeVersion?.configId,
+                                sources: push.sources.map((src) => src.path),
+                            };
+                        }
+                        continue;
+                    }
+                    changes.push({
+                        type: "function",
+                        action: liveFunction ? "update" : "create",
+                        key,
+                    });
+                    if (options.dryRun)
+                        continue;
+                    // Every server refusal below is recorded against THIS function and
+                    // the loop moves on. A single archived tombstone — or a key the
+                    // app's namespace already holds — must not abort a push carrying
+                    // unrelated changes: the run reports what it could not apply, exits
+                    // non-zero, and everything else in the tree still lands. That is
+                    // the same contract `applyFailures` gives every other type; a throw
+                    // here would let one refusal block a whole repository.
+                    let functionId = liveFunction?.functionId ?? existingEntry?.id;
+                    let pushedVersion;
+                    try {
+                        if (!functionId) {
+                            const created = await client.createFunction(resolvedAppId, buildFunctionCreatePayload(key, tomlData.function ?? {})).catch(async (err) => {
+                                // #1006 — a function the server already holds under this key
+                                // is adopted rather than re-created. The conflict may name a
+                                // WORKFLOW, a script or a webhook instead: those are the
+                                // single key namespace refusing the key, and they are not
+                                // adoptable, so `adoptByKeyOnCreate409` re-throws the original
+                                // error with its holder named.
+                                const existing = await adoptByKeyOnCreate409({
+                                    err,
+                                    kind: "function",
+                                    key,
+                                    lookup: async () => (await client.listFunctions(resolvedAppId)).items || [],
+                                    matchKey: (f) => f?.functionKey === key,
+                                });
+                                return existing;
+                            });
+                            functionId = created.functionId;
+                            info(`  Created function: ${key}`);
+                        }
+                        else if (headerAction !== "skip") {
+                            const updatePayload = buildFunctionUpdatePayload(tomlData.function ?? {});
+                            if (Object.keys(updatePayload).length > 0) {
+                                await client.updateFunction(resolvedAppId, functionId, updatePayload);
+                            }
+                            info(`  Updated function: ${key}`);
+                        }
+                        // The version. `status` is NEVER in this body: pushing code to a
+                        // disabled function updates it and leaves it out of service
+                        // (#2803's resurrection guard), and a push to an archived one is
+                        // refused by the server with the archived-holder message — which
+                        // names the remedies that release its key.
+                        pushedVersion = await client.pushFunctionConfig(resolvedAppId, String(functionId), push);
+                    }
+                    catch (err) {
+                        applyFailures.push({
+                            type: "function",
+                            key,
+                            message: String(err?.message ?? err),
+                        });
+                        continue;
+                    }
+                    if (pushedVersion?.created === false) {
+                        info(`  Function ${key}: code unchanged (no new version)`);
+                    }
+                    else {
+                        info(`  Pushed function ${key} version ${pushedVersion?.configId ?? ""}`.trim());
+                    }
+                    if (syncState) {
+                        if (!syncState.entities.functions)
+                            syncState.entities.functions = {};
+                        let refreshed = liveFunction;
+                        try {
+                            refreshed = await client.getFunction(resolvedAppId, String(functionId));
+                        }
+                        catch {
+                            // Non-fatal: the baseline falls back to what the listing said.
+                            // The next push reconciles it.
+                        }
+                        syncState.entities.functions[key] = {
+                            id: String(functionId),
+                            modifiedAt: refreshed?.modifiedAt ||
+                                existingEntry?.modifiedAt ||
+                                new Date().toISOString(),
+                            contentHash: computeFileHash(filePath),
+                            semanticHash: refreshed
+                                ? hashRemoteConfigForDiff(functionSpec, refreshed, pushDiffMaps, pushedVersion ?? undefined)
+                                : undefined,
+                            envelopeHash: push.envelopeHash,
+                            activeConfigId: pushedVersion?.configId,
+                            sources: push.sources.map((src) => src.path),
+                        };
+                    }
+                }
+            }
             // Process group type configs
             const groupTypeConfigsDir = join(configDir, "group-type-configs");
             if (existsSync(groupTypeConfigsDir)) {
@@ -13134,7 +13373,7 @@ export function registerConfigSyncCommands(sync) {
                                 // this, that CREATE re-hits the server's 409 "Config for this
                                 // group type already exists"
                                 // (group-type-config-controller.ts) on every subsequent push
-                                // and the operator has to hand-edit `.primitive-sync.json` to
+                                // and the operator has to hand-edit the sync-state baseline to
                                 // recover. The shared helper detects the conflict (409 status /
                                 // "already exists" message), lists the app's configs — the list
                                 // route drains every page server-side (#1668), so the candidate
@@ -14275,8 +14514,14 @@ export function registerConfigSyncCommands(sync) {
         .option("--only <selectors>", "Compare just these objects: <type>/<key>, app, or var/<key> (repeatable, or comma-separated).", (value, previous) => [...(previous ?? []), value], [])
         .option("--json", "Output as JSON (app.toml field diff, with --only app)")
         .action(async (appId, options) => {
+        // Refused before any tree read/write or request (#3153, F1): the tree
+        // path no longer partitions by app.
+        assertTreeApp(appId || options.app, "config diff");
         const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
+        const configDir = resolveSyncDir({ userDir: options.dir });
+        // A baseline that was never renamed means an unmigrated tree; refused
+        // here, before any request, snapshot or directory is made (#3153).
+        assertSyncStateLayout(configDir);
         if (isAutoResolvedSyncDir(options.dir)) {
             info(`Using per-environment config directory: ${configDir}`);
             const legacyHint = checkLegacySyncMigration(configDir);
@@ -15262,7 +15507,7 @@ export function registerConfigSyncCommands(sync) {
             // below). Content comparison is a preview of `config pull` (pull would
             // rewrite the local TOML to match running state), exactly like the
             // workflow/transform blocks.
-            const compareConfigType = (typeLabel, slot, localParsed, remoteEntities, hashLocal, hashRemote, contentComparable) => {
+            const compareConfigType = (typeLabel, slot, localParsed, remoteEntities, compare, contentComparable) => {
                 for (const [key, parsed] of localParsed) {
                     if (!remoteEntities.has(key)) {
                         differences.push({ type: typeLabel, key, status: localOnlyStatus(slot, key) });
@@ -15277,16 +15522,10 @@ export function registerConfigSyncCommands(sync) {
                         hint = "content not compared (rule sets unavailable)";
                     }
                     else {
-                        try {
-                            if (hashLocal(parsed) !== hashRemote(remoteEntities.get(key))) {
-                                status = "modified";
-                                hint = "run `config pull` to rewrite the local TOML to match running state";
-                            }
-                        }
-                        catch {
-                            // A malformed local file must not abort the whole diff.
-                            hint = "content not compared (comparison failed)";
-                        }
+                        // The shared verdict names the differing field (#3267) and
+                        // degrades a malformed local file to "not compared" rather than
+                        // aborting the whole diff.
+                        ({ status, hint } = compare(parsed, remoteEntities.get(key)));
                     }
                     differences.push({ type: typeLabel, key, status, hint });
                 }
@@ -15305,7 +15544,7 @@ export function registerConfigSyncCommands(sync) {
             };
             const compareByDefinition = (label, slot, localParsed, remoteEntities, contentComparable) => {
                 const spec = configDiffSpec(label);
-                compareConfigType(label, slot, localParsed, remoteEntities, (p) => hashLocalConfigForDiff(spec, p, diffMaps), (e) => hashRemoteConfigForDiff(spec, e, diffMaps), contentComparable);
+                compareConfigType(label, slot, localParsed, remoteEntities, (p, e) => compareLocalToRemote(spec, p, e, diffMaps), contentComparable);
             };
             compareByDefinition("rule-set", "ruleSets", localRuleSetsParsed, remoteRuleSets, true);
             compareByDefinition("group-type-config", "groupTypeConfigs", localGroupTypeConfigsParsed, remoteGroupTypeConfigs, ruleSetsOk);
@@ -15337,20 +15576,14 @@ export function registerConfigSyncCommands(sync) {
                         hint = "content not compared (fetch failed)";
                     }
                     else {
-                        try {
-                            const operations = Array.isArray(opsOutcome.value) ? opsOutcome.value : [];
-                            const subscriptions = Array.isArray(subsOutcome.value) ? subsOutcome.value : [];
-                            const dbSpec = configDiffSpec("database-type-config");
-                            const remoteHash = hashRemoteConfigForDiff(dbSpec, remote, diffMaps, { operations, subscriptions });
-                            const localHash = hashLocalConfigForDiff(dbSpec, parsed, diffMaps);
-                            if (remoteHash !== localHash) {
-                                status = "modified";
-                                hint = "run `config pull` to rewrite the local TOML to match running state";
-                            }
-                        }
-                        catch {
-                            hint = "content not compared (comparison failed)";
-                        }
+                        const operations = Array.isArray(opsOutcome.value) ? opsOutcome.value : [];
+                        const subscriptions = Array.isArray(subsOutcome.value) ? subsOutcome.value : [];
+                        // The shared verdict (#3267): a Modified row names the
+                        // operation, subscription, model field or `[type]` scalar it
+                        // differs in, and a comparison that throws degrades this one
+                        // row to "not compared". The ops/subscriptions are the remote
+                        // side's extra only — the file already carries its own.
+                        ({ status, hint } = compareLocalToRemote(configDiffSpec("database-type-config"), parsed, remote, diffMaps, { operations, subscriptions }));
                     }
                 }
                 differences.push({ type: "database-type-config", key, status, hint });
@@ -15650,6 +15883,29 @@ export function registerConfigSyncCommands(sync) {
                     console.log(`  ${chalk.dim("=")} ${d.blockType}/${d.blockKey} test-case: ${d.slug}${hint}`);
                 }
             }
+            // #3182 — the generated function types are part of what a push would
+            // change, so `config diff` is where their freshness is answered: an
+            // editor or a CI job asks the same command it already asks "what would
+            // push do?", and gets these named alongside everything else.
+            const staleFunctionTypes = staleFunctionTypeArtifacts(configDir);
+            if (staleFunctionTypes.length > 0) {
+                console.log();
+                info("Function types (regenerated by `config push`):");
+                for (const relative of staleFunctionTypes) {
+                    console.log(`  ${chalk.yellow("~")} ${relative}`);
+                }
+            }
+            // Freshness is not the only way the handle stops working: a tsconfig
+            // push will not rewrite can be perfectly current and still load none of
+            // it. `config diff` is where CI asks, so it answers both (CR3182-003).
+            const wiringProblems = functionTypeWiringProblems(configDir);
+            if (wiringProblems.length > 0) {
+                console.log();
+                info("Function types (compiler wiring `config push` cannot repair):");
+                for (const problem of wiringProblems) {
+                    console.log(`  ${chalk.yellow("!")} functions/tsconfig.json: ${problem}`);
+                }
+            }
             divider();
             keyValue("Local only (new)", localOnly.length);
             keyValue("Local only (absent from export)", localOnlyAbsent.length);
@@ -15698,8 +15954,14 @@ export function registerConfigSyncCommands(sync) {
         // Resolve appId so we land in the per-env sync dir even when the user
         // didn't pass `--dir`. The app ID itself isn't used for any API calls
         // — `migrate-toml` is a purely local rewrite.
+        // Refused before any tree read/write or request (#3153, F1): the tree
+        // path no longer partitions by app.
+        assertTreeApp(appId || options.app, "config migrate-toml");
         const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
+        const configDir = resolveSyncDir({ userDir: options.dir });
+        // A baseline that was never renamed means an unmigrated tree; refused
+        // here, before any request, snapshot or directory is made (#3153).
+        assertSyncStateLayout(configDir);
         if (isAutoResolvedSyncDir(options.dir)) {
             info(`Using per-environment config directory: ${configDir}`);
         }
@@ -15862,8 +16124,14 @@ export function registerConfigSyncCommands(sync) {
         // Resolve appId so we land in the per-env sync dir even when the user
         // didn't pass `--dir`. The app ID itself isn't used for any API calls —
         // migrate-v2 is a purely local rewrite (like migrate-toml).
+        // Refused before any tree read/write or request (#3153, F1): the tree
+        // path no longer partitions by app.
+        assertTreeApp(appId || options.app, "config migrate-v2");
         const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
+        const configDir = resolveSyncDir({ userDir: options.dir });
+        // A baseline that was never renamed means an unmigrated tree; refused
+        // here, before any request, snapshot or directory is made (#3153).
+        assertSyncStateLayout(configDir);
         if (isAutoResolvedSyncDir(options.dir)) {
             info(`Using per-environment config directory: ${configDir}`);
         }
@@ -15913,11 +16181,14 @@ export function registerConfigSyncCommands(sync) {
         .option("--list", "List available snapshots without restoring")
         .option("-y, --yes", "Skip the confirmation prompt")
         .action(async (appId, options) => {
+        // Refused before any tree read/write or request (#3153, F1): the tree
+        // path no longer partitions by app.
+        assertTreeApp(appId || options.app, "config revert");
         const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({
-            appId: resolvedAppId,
-            userDir: options.dir,
-        });
+        const configDir = resolveSyncDir({ userDir: options.dir });
+        // A baseline that was never renamed means an unmigrated tree; refused
+        // here, before any request, snapshot or directory is made (#3153).
+        assertSyncStateLayout(configDir);
         const snapshotsRoot = resolveSnapshotsRoot({
             appId: resolvedAppId,
             userDir: options.dir,
@@ -15992,7 +16263,7 @@ export function registerConfigSyncCommands(sync) {
             error(`Restore failed: ${err?.message ?? err}`);
             process.exit(1);
         }
-        success(`Restored snapshot ${target.id} into ${configDir} (including .primitive-sync.json).`);
+        success(`Restored snapshot ${target.id} into ${configDir} (including ${SYNC_STATE_FILENAME}).`);
         info("Run 'primitive config diff' to inspect the restored state versus the server.");
     });
 }