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

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";
@@ -34,8 +35,14 @@ import { buildPayloadFromToml, projectEntityToPayload, projectRecordToToml, toml
 import { CONFIG_SURFACES, isEmptyForEmit, } from "../lib/generated-config-surfaces.js";
 // #3179 — the function's two halves: the header payloads and the envelope
 // `config push` sends, and the bytes `config pull` writes back.
-import { applyFunctionPull, buildFunctionConfigPush, buildFunctionCreatePayload, buildFunctionUpdatePayload, functionDiffEntity, planFunctionPull, serializeFunction, } from "../lib/function-sync.js";
+import { applyFunctionPull, buildFunctionConfigPush, buildFunctionCreatePayload, buildFunctionUpdatePayload, collectManifestForPreflight, functionDiffEntity, planFunctionPull, serializeFunction, } from "../lib/function-sync.js";
 import { FunctionBuildError } from "../lib/function-bundle.js";
+// #3182 — the local half of grant validation. The grammar is the vendored
+// module the server also imports; this is where an author's own file is read.
+import { configObjectKeysFromTree, databaseTypesFromServer, databaseTypesFromTree, functionGrantErrors, functionNeedsManifest, mergeKnownDatabaseTypes, 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));
 }
 /**
@@ -3402,6 +3409,13 @@ 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()
+                : [],
+            unscopedReads: entity.unscopedReads === true,
         }),
         describe: (entity) => `function "${entity?.functionKey}"`,
     },
@@ -4222,7 +4236,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 +6290,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 +6302,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 +6356,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 +7151,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 +7654,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 +8128,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 +8310,100 @@ export function registerConfigSyncCommands(sync) {
                     preflightValidationErrors.push(`  vars.toml: ${err?.message || String(err)}`);
                 }
             }
+            // #3182 — a function's database grants, checked against the author's
+            // own file before anything is applied. The grammar and the
+            // unscoped-read rule are purely local; whether a grant names a type and
+            // model that will exist is answered against the tree's own
+            // `database-type-configs/` (applied BEFORE functions since this child)
+            // merged with the types the server already has. If the live listing
+            // cannot be fetched and the tree declares no types, 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 treeTypes = databaseTypesFromTree(configDir);
+                    let knownTypes = null;
+                    try {
+                        const live = await client.listDatabaseTypeConfigs(resolvedAppId);
+                        knownTypes = mergeKnownDatabaseTypes(databaseTypesFromServer(Array.isArray(live) ? live : []), treeTypes);
+                    }
+                    catch {
+                        knownTypes = treeTypes.size > 0 ? treeTypes : null;
+                    }
+                    // #3183 — the same question for the two grant families that name
+                    // config-tree objects. `secret:` and `var:` are absent on purpose
+                    // (D3183-002): their values are provisioned per environment, out
+                    // of band, so a tree can never answer for them.
+                    const treeTargets = configObjectKeysFromTree(configDir);
+                    let knownTargets = null;
+                    try {
+                        const [integrations, prompts] = await Promise.all([
+                            client.listIntegrations(resolvedAppId, { status: "active" }),
+                            client.listPrompts(resolvedAppId, { status: "active" }),
+                        ]);
+                        knownTargets = mergeKnownGrantTargets({
+                            integrations: new Set((integrations?.items ?? [])
+                                .map((row) => String(row?.integrationKey ?? ""))
+                                .filter(Boolean)),
+                            prompts: new Set((prompts?.items ?? [])
+                                .map((row) => String(row?.promptKey ?? ""))
+                                .filter(Boolean)),
+                        }, treeTargets);
+                    }
+                    catch {
+                        knownTargets =
+                            treeTargets.integrations.size > 0 || treeTargets.prompts.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;
+                        }
+                        // #3187 — a read grant declared without `unscopedReads = true`
+                        // is accepted when the tree's registered reads are all bound to
+                        // `$caller`, and only the MANIFEST says whether they are. So the
+                        // functions whose decision depends on it are built and collected
+                        // here, before anything is applied; the result is memoized
+                        // against the built bundle, so the push below does not run the
+                        // tree's module scope a second time (CR3187-001).
+                        let manifest = null;
+                        if (functionNeedsManifest(tomlData)) {
+                            try {
+                                manifest = await collectManifestForPreflight({
+                                    configDir,
+                                    // The same key the push loop derives, so a refusal names
+                                    // the function the way the rest of the run does.
+                                    functionKey: tomlData.function?.key || basename(file, ".toml"),
+                                    tomlData,
+                                });
+                            }
+                            catch (err) {
+                                // Fail-closed and early: the push would refuse this tree for
+                                // the same reason, naming the same error.
+                                preflightValidationErrors.push(`  ${filePath}: ${err?.message || String(err)}`);
+                                continue;
+                            }
+                        }
+                        for (const message of functionGrantErrors({
+                            filePath,
+                            tomlData,
+                            knownTypes,
+                            knownTargets,
+                            manifest,
+                        })) {
+                            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,341 +11001,86 @@ 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";
-                    }
-                    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";
+                    // 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));
                     }
-                    // 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;
+                    const unknownKeyError = workflowUnknownKeyError(filePath, tomlData);
+                    if (unknownKeyError) {
+                        throw new Error(unknownKeyError);
                     }
-                    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 workflow = tomlData.workflow || {};
-                    const key = workflow.key || basename(file, ".toml");
-                    const steps = tomlData.steps || [];
-                    // #2652 — a caller workflow with no rule denies every non-admin
-                    // start from this release onward. A `runAs = "system"` workflow is
-                    // exempt (it rejects rules and members cannot start it).
-                    const workflowRuleWarning = missingAccessRuleWarning({
-                        kind: "workflow",
+                    const workflow = tomlData.workflow || {};
+                    const key = workflow.key || basename(file, ".toml");
+                    const steps = tomlData.steps || [];
+                    // #2652 — a caller workflow with no rule denies every non-admin
+                    // start from this release onward. A `runAs = "system"` workflow is
+                    // exempt (it rejects rules and members cannot start it).
+                    const workflowRuleWarning = missingAccessRuleWarning({
+                        kind: "workflow",
                         key,
                         accessRule: workflow.accessRule,
                         runAs: workflow.runAs,
@@ -12509,7 +12390,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 +12834,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, 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)) {
+                // #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 +13288,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 +14429,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);
@@ -15650,6 +15810,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 +15881,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 +16051,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 +16108,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 +16190,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.");
     });
 }