primitive-admin 1.0.49 → 1.0.51

package/dist/src/commands/sync.js

@@ -7,16 +7,31 @@ import { ApiClient, ApiError, ConflictError, SchemaRequiredError, OperationRefEr
 import { buildDatabaseTypeTomlData, detectExistingOperationForms, normalizeOperationFromToml, normalizeSubscriptionFromToml, SubscriptionAccessKeyConflictError, } from "../lib/toml-database-config.js";
 import { validateOperations, formatIssue, } from "../lib/toml-params-validator.js";
 import { getServerUrl, resolveAppId } from "../lib/config.js";
-import { resolveSyncDir, isAutoResolvedSyncDir, checkLegacySyncMigration, } from "../lib/sync-paths.js";
+import { resolveSyncDir, resolveSnapshotsRoot, isAutoResolvedSyncDir, checkLegacySyncMigration, } from "../lib/sync-paths.js";
+import { createSnapshot, listSnapshots, resolveSnapshot, restoreSnapshot, pruneSnapshots, } from "../lib/snapshots.js";
 import { validateWorkflowToml, formatWorkflowTomlErrors, } from "../lib/workflow-toml-validator.js";
 import { expandWorkflowTomlData } from "../lib/workflow-fragments.js";
 import { success, error, info, warn, keyValue, json, divider, } from "../lib/output.js";
+import { confirmPrompt } from "../lib/confirm-prompt.js";
 import chalk from "chalk";
 function ensureDir(dirPath) {
     if (!existsSync(dirPath)) {
         mkdirSync(dirPath, { recursive: true });
     }
 }
+/**
+ * Issue #974: when a type-config push newly declares fields `unique = true`
+ * and the type already has instances, the server returns a
+ * `staleInstanceWarning`. Surface it so the operator knows the existing
+ * instances still lack the index and how to back-provision them. The push
+ * itself still succeeded — this is informational, not a failure.
+ */
+function printStaleInstanceWarning(updated) {
+    const w = updated?.staleInstanceWarning;
+    if (w && typeof w.message === "string") {
+        warn(`  ${w.message}`);
+    }
+}
 function loadSyncState(configDir) {
     const syncFile = join(configDir, ".primitive-sync.json");
     if (!existsSync(syncFile)) {
@@ -246,7 +261,13 @@ function serializeBlobBucket(bucket) {
             name: bucket.name,
             description: bucket.description || undefined,
             ttlTier: bucket.ttlTier,
-            accessPolicy: bucket.accessPolicy,
+            // #1020: `preset` is the honest key; a custom bucket carries ruleSetId
+            // instead. Omit preset for custom buckets (preset === "custom").
+            preset: bucket.preset && bucket.preset !== "custom"
+                ? bucket.preset
+                : bucket.ruleSetId
+                    ? undefined
+                    : bucket.preset,
         },
     };
     if (bucket.ruleSetId) {
@@ -299,6 +320,9 @@ function serializeWorkflow(workflow, draft, configs) {
             status: workflow.status,
             activeConfigName: activeConfigName,
             accessRule: workflow.accessRule || undefined,
+            // #1081 — workflow principal mode. Emit only when set so a fresh
+            // pull → push round-trips it without writing a noisy `runAs = ""`.
+            runAs: workflow.runAs || undefined,
             perUserMaxRunning: workflow.perUserMaxRunning,
             perUserMaxQueued: workflow.perUserMaxQueued,
             dequeueOrder: workflow.dequeueOrder,
@@ -1153,6 +1177,35 @@ Directory Structure:
                     subscriptions: Array.isArray(subs) ? subs : [],
                 };
             }));
+            // Snapshot the pre-pull sync tree BEFORE we touch any local file
+            // (issue #578, Phase 1). All server data has been fetched and
+            // validated at this point — a failed pull already threw above, so we
+            // never create empty snapshots — but no local file has been
+            // overwritten yet. This is the proven copy-point: between the last
+            // server fetch and the first directory mutation.
+            //
+            // Fail LOUD: if the snapshot can't be written, abort the pull BEFORE
+            // the ensureDir below. Better to refuse a destructive pull than
+            // perform it without a recoverable backup. No-op on a fresh/empty
+            // sync dir (nothing to back up). Prune to 28 days after success.
+            try {
+                const snapshotsRoot = resolveSnapshotsRoot({
+                    appId: resolvedAppId,
+                    userDir: options.dir,
+                });
+                const snapshot = createSnapshot(configDir, snapshotsRoot);
+                if (snapshot) {
+                    info(`  Snapshot: ${snapshot.path}`);
+                    pruneSnapshots(snapshotsRoot, 28);
+                }
+            }
+            catch (snapErr) {
+                error(`Failed to create a pre-pull snapshot: ${snapErr?.message ?? snapErr}`);
+                error("Aborting pull before any local file is modified. " +
+                    "Resolve the snapshot error (e.g. disk space / permissions) and retry, " +
+                    "or pass a writable --dir.");
+                process.exit(1);
+            }
             // Ensure directories exist
             ensureDir(configDir);
             ensureDir(join(configDir, "integrations"));
@@ -1660,6 +1713,82 @@ Directory Structure:
             const promptKeyToId = new Map();
             const promptConfigNameToId = new Map(); // key: "promptKey#configName"
             const workflowConfigNameToId = new Map(); // key: "workflowKey#configName"
+            // ── Issue #976 (fix A): front-load ALL client-side TOML validation
+            // before the first mutating call. Push is apply-as-you-go and processes
+            // entities in a fixed sequence (cron triggers are created *before*
+            // workflows are validated). Previously each entity's validation lived
+            // inside its own apply loop and aborted via `process.exit(1)` — so a
+            // known-bad sibling file (e.g. an invalid workflow TOML) could let an
+            // earlier create (a cron trigger) be applied, then abort. The
+            // `process.exit` also bypassed the save-on-failure catch below, so the
+            // orphaned create never reached `.primitive-sync.json` and the retry
+            // re-issued a CREATE that the server rejected with 409 forever.
+            //
+            // Running every validation up-front means a known-bad file aborts
+            // BEFORE anything is created. We collect all errors (not just the first)
+            // and THROW — so the single save-on-failure catch is the only exit path
+            // (no more `process.exit` bypass class). The per-loop validators below
+            // remain as defense-in-depth but are converted to throws too.
+            const preflightValidationErrors = [];
+            // Validate all workflow TOMLs (issue #685 misnested-header check).
+            const preflightWorkflowsDir = join(configDir, "workflows");
+            if (existsSync(preflightWorkflowsDir)) {
+                for (const file of readdirSync(preflightWorkflowsDir).filter((f) => f.endsWith(".toml"))) {
+                    const filePath = join(preflightWorkflowsDir, file);
+                    try {
+                        const tomlData = parseTomlFile(filePath);
+                        const tomlErrors = validateWorkflowToml(tomlData);
+                        if (tomlErrors.length > 0) {
+                            preflightValidationErrors.push(formatWorkflowTomlErrors(filePath, tomlErrors));
+                        }
+                    }
+                    catch (err) {
+                        preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
+                    }
+                }
+            }
+            // Validate all database-type TOMLs (issue #803 subscription
+            // access/accessRule conflict + issue #752 $params references).
+            const preflightDbTypesDir = join(configDir, "database-types");
+            if (existsSync(preflightDbTypesDir)) {
+                for (const file of readdirSync(preflightDbTypesDir).filter((f) => f.endsWith(".toml"))) {
+                    const filePath = join(preflightDbTypesDir, file);
+                    let rawToml;
+                    let tomlData;
+                    try {
+                        rawToml = readFileSync(filePath, "utf-8");
+                        tomlData = parseTomlFile(filePath);
+                    }
+                    catch (err) {
+                        preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
+                        continue;
+                    }
+                    let operations = [];
+                    try {
+                        ({ operations } = parseDatabaseTypeToml(tomlData));
+                    }
+                    catch (err) {
+                        if (err instanceof SubscriptionAccessKeyConflictError) {
+                            preflightValidationErrors.push(`  ${file}: ${err.message}`);
+                            continue;
+                        }
+                        preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
+                        continue;
+                    }
+                    const validation = validateOperations({
+                        filePath,
+                        rawToml,
+                        operations,
+                    });
+                    for (const e of validation.errors) {
+                        preflightValidationErrors.push(`  ${formatIssue(e)}`);
+                    }
+                }
+            }
+            if (preflightValidationErrors.length > 0) {
+                throw new Error(`Aborting push: ${preflightValidationErrors.length} TOML validation error(s) — no changes were applied.\n` +
+                    preflightValidationErrors.join("\n"));
+            }
             // Process app settings
             const appTomlPath = join(configDir, "app.toml");
             if (existsSync(appTomlPath)) {
@@ -2031,7 +2160,58 @@ Directory Structure:
                                 }
                             }
                             catch (err) {
-                                throw wrapEntityError(err, "create", "cron trigger", key);
+                                // Issue #976 (fix B): idempotent create — adopt-by-key on 409.
+                                // A cron trigger can be orphaned on the server (created by a
+                                // prior push that aborted before recording it in sync state,
+                                // a mid-apply crash, or an out-of-band create with the same
+                                // key). On retry this CREATE path then hits the
+                                // `triggerKeyPerApp` unique constraint and the server returns
+                                // 409 "A cron trigger with this key already exists". Rather
+                                // than hard-fail forever, look up the existing trigger by key
+                                // (the list endpoint is app-scoped, so every item is owned by
+                                // this app), verify the SAME triggerKey, adopt its id into
+                                // sync state, and re-issue as an UPDATE so the push converges.
+                                const msg = String(err?.message || err);
+                                const is409 = err?.statusCode === 409 || msg.includes("already exists");
+                                if (is409) {
+                                    info(`  Cron trigger already exists on server, adopting by key: ${key}`);
+                                    let adoptedId;
+                                    try {
+                                        const { items } = await client.listCronTriggers(resolvedAppId);
+                                        // Verify same key + app ownership: the list endpoint only
+                                        // returns triggers for `resolvedAppId`, so a triggerKey
+                                        // match is also an ownership match. Never overwrite an
+                                        // unrelated resource — require an exact key equality.
+                                        const existing = (items || []).find((t) => t?.triggerKey === key);
+                                        if (existing?.triggerId) {
+                                            adoptedId = existing.triggerId;
+                                        }
+                                    }
+                                    catch (lookupErr) {
+                                        throw wrapEntityError(new Error(`cron trigger "${key}" already exists but could not be adopted (lookup failed: ${String(lookupErr?.message || lookupErr)})`), "create", "cron trigger", key);
+                                    }
+                                    if (!adoptedId) {
+                                        // 409 but no matching key found on the server — surface
+                                        // the original error rather than silently overwriting.
+                                        throw wrapEntityError(err, "create", "cron trigger", key);
+                                    }
+                                    // Switch to UPDATE on the adopted trigger.
+                                    const updated = await client.updateCronTrigger(resolvedAppId, adoptedId, payload);
+                                    info(`  Adopted + updated cron trigger: ${key}`);
+                                    if (syncState) {
+                                        if (!syncState.entities.cronTriggers) {
+                                            syncState.entities.cronTriggers = {};
+                                        }
+                                        syncState.entities.cronTriggers[key] = {
+                                            id: adoptedId,
+                                            modifiedAt: updated?.modifiedAt || new Date().toISOString(),
+                                            contentHash: computeFileHash(filePath),
+                                        };
+                                    }
+                                }
+                                else {
+                                    throw wrapEntityError(err, "create", "cron trigger", key);
+                                }
                             }
                         }
                     }
@@ -2053,8 +2233,29 @@ Directory Structure:
                         continue;
                     }
                     if (existingId) {
-                        // Blob buckets don't have an update API - skip if already exists
-                        info(`  Blob bucket already exists, skipping: ${key}`);
+                        // #1020 (D8): idempotently apply preset/ruleSet/name/description
+                        // changes via PATCH. bucketKey/ttlTier are immutable and not sent.
+                        const updatePayload = {};
+                        if (bucket.preset)
+                            updatePayload.preset = bucket.preset;
+                        else if (bucket.accessPolicy)
+                            updatePayload.accessPolicy = bucket.accessPolicy;
+                        if (bucket.ruleSetId)
+                            updatePayload.ruleSetId = bucket.ruleSetId;
+                        if (bucket.name)
+                            updatePayload.name = bucket.name;
+                        if (bucket.description !== undefined)
+                            updatePayload.description = bucket.description || null;
+                        changes.push({ type: "blob-bucket", action: "update", key });
+                        if (!options.dryRun) {
+                            try {
+                                await client.updateBlobBucket(resolvedAppId, existingId, updatePayload);
+                                info(`  Updated blob bucket: ${key}`);
+                            }
+                            catch (err) {
+                                warn(`  Failed to update blob bucket ${key}: ${String(err?.message || err)}`);
+                            }
+                        }
                         if (syncState?.entities?.blobBuckets?.[key]) {
                             syncState.entities.blobBuckets[key].contentHash = computeFileHash(filePath);
                         }
@@ -2064,8 +2265,11 @@ Directory Structure:
                             bucketKey: key,
                             name: bucket.name || key,
                             ttlTier: bucket.ttlTier,
-                            accessPolicy: bucket.accessPolicy,
                         };
+                        if (bucket.preset)
+                            payload.preset = bucket.preset;
+                        else if (bucket.accessPolicy)
+                            payload.accessPolicy = bucket.accessPolicy;
                         if (bucket.description)
                             payload.description = bucket.description;
                         if (bucket.ruleSetId)
@@ -2358,7 +2562,10 @@ Directory Structure:
                         changes.push({ type: "script", action: "update", key: name });
                         if (!options.dryRun) {
                             try {
-                                const updated = await client.updateScript(resolvedAppId, existingId, { body });
+                                // #1000 — push a new ScriptConfig + activate it. Referencing
+                                // workflows pick up the new body on their next run (no
+                                // fan-out, no re-push needed).
+                                await client.pushScriptBody(resolvedAppId, existingId, body);
                                 info(`  Updated script: ${name}`);
                                 if (syncState) {
                                     if (!syncState.entities.scripts) {
@@ -2366,8 +2573,7 @@ Directory Structure:
                                     }
                                     syncState.entities.scripts[name] = {
                                         id: existingId,
-                                        modifiedAt: updated?.modifiedAt ||
-                                            syncState.entities.scripts[name]?.modifiedAt ||
+                                        modifiedAt: syncState.entities.scripts[name]?.modifiedAt ||
                                             new Date().toISOString(),
                                         contentHash: computeFileHash(filePath),
                                     };
@@ -2389,7 +2595,7 @@ Directory Structure:
                             changes.push({ type: "script", action: "update", key: name });
                             if (!options.dryRun) {
                                 try {
-                                    const updated = await client.updateScript(resolvedAppId, match.scriptId, { body });
+                                    await client.pushScriptBody(resolvedAppId, match.scriptId, body);
                                     info(`  Updated script: ${name} (adopted from server)`);
                                     if (syncState) {
                                         if (!syncState.entities.scripts) {
@@ -2397,7 +2603,7 @@ Directory Structure:
                                         }
                                         syncState.entities.scripts[name] = {
                                             id: match.scriptId,
-                                            modifiedAt: updated?.modifiedAt || new Date().toISOString(),
+                                            modifiedAt: new Date().toISOString(),
                                             contentHash: computeFileHash(filePath),
                                         };
                                     }
@@ -2445,10 +2651,14 @@ Directory Structure:
                     // place to catch the footgun. 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) {
-                        error(formatWorkflowTomlErrors(filePath, tomlErrors));
-                        process.exit(1);
+                        throw new Error(formatWorkflowTomlErrors(filePath, tomlErrors));
                     }
                     const workflow = tomlData.workflow || {};
                     const key = workflow.key || basename(file, ".toml");
@@ -2501,6 +2711,10 @@ Directory Structure:
                                     description: workflow.description,
                                     status: workflow.status,
                                     accessRule: workflow.accessRule !== undefined ? (workflow.accessRule || null) : undefined,
+                                    // #1081 — workflow principal mode. Absent key → undefined
+                                    // (server leaves it untouched); explicit value/empty is
+                                    // forwarded so it round-trips.
+                                    runAs: workflow.runAs !== undefined ? (workflow.runAs || null) : undefined,
                                     perUserMaxRunning: workflow.perUserMaxRunning,
                                     perUserMaxQueued: workflow.perUserMaxQueued,
                                     dequeueOrder: workflow.dequeueOrder,
@@ -2595,6 +2809,8 @@ Directory Structure:
                                     inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : undefined,
                                     outputSchema: workflow.outputSchema ? safeJsonParse(workflow.outputSchema) : undefined,
                                     accessRule: workflow.accessRule || undefined,
+                                    // #1081 — workflow principal mode (absent → server default).
+                                    runAs: workflow.runAs || undefined,
                                     perUserMaxRunning: workflow.perUserMaxRunning,
                                     perUserMaxQueued: workflow.perUserMaxQueued,
                                     dequeueOrder: workflow.dequeueOrder,
@@ -2679,9 +2895,10 @@ Directory Structure:
                         // (issue #803). Surface it with the file name and abort the
                         // push rather than crashing with an opaque stack.
                         if (err instanceof SubscriptionAccessKeyConflictError) {
-                            error(`  ${file}: ${err.message}`);
-                            error(`Aborting push: subscription \`access\`/\`accessRule\` conflict in ${file}.`);
-                            process.exit(1);
+                            // Issue #976: throw (not `process.exit`) so the save-on-failure
+                            // catch is the only exit path. Validation is also front-loaded
+                            // above, so this is defense-in-depth.
+                            throw new Error(`  ${file}: ${err.message}\nAborting push: subscription \`access\`/\`accessRule\` conflict in ${file}.`);
                         }
                         throw err;
                     }
@@ -2701,13 +2918,22 @@ Directory Structure:
                         warn(`  ${formatIssue(w)}`);
                     }
                     if (validation.errors.length > 0) {
-                        for (const e of validation.errors) {
-                            error(`  ${formatIssue(e)}`);
-                        }
-                        error(`Aborting push: ${validation.errors.length} unresolved $params reference(s) in ${file}.`);
-                        process.exit(1);
+                        // Issue #976: throw (not `process.exit`) so the save-on-failure
+                        // catch is the only exit path. Validation is also front-loaded
+                        // above, so this is defense-in-depth.
+                        throw new Error(validation.errors.map((e) => `  ${formatIssue(e)}`).join("\n") +
+                            `\nAborting push: ${validation.errors.length} unresolved $params reference(s) in ${file}.`);
                     }
                     const existingEntry = syncState?.entities?.databaseTypes?.[dbType];
+                    // Issue #915 (defect b): track whether the apply path rejected any
+                    // op for THIS file via the schema gate (OperationRefError /
+                    // SchemaRequiredError). On a non-transactional fresh-type push the
+                    // db-type lands but the bad op is blocked and the loop continues; if
+                    // we then wrote the file-level contentHash, the next push's
+                    // `shouldPushFile` would short-circuit and the missing op would be
+                    // invisible drift. When this flag is set we skip the contentHash
+                    // write so the drift stays visible and a corrected re-push converges.
+                    let fileHadGateRejectedOp = false;
                     // Skip if file hasn't changed since last sync
                     if (!options.force && existingEntry && !shouldPushFile(filePath, existingEntry.contentHash)) {
                         skippedCount++;
@@ -2794,8 +3020,7 @@ Directory Structure:
                         }
                         // 2. Op-edit gate (op create/update dry-run) for every op in the
                         //    TOML. The server runs `runSchemaGate` and short-circuits
-                        //    before persisting. Skipped for a fresh type (no schema on the
-                        //    server yet → gate is a no-op anyway).
+                        //    before persisting.
                         //
                         //    The op gate is run against the schema THIS push is landing
                         //    (`schemaOverride`), not the stale stored schema — the real
@@ -2805,11 +3030,36 @@ Directory Structure:
                         //    a schema landed earlier in the same push"). When the push
                         //    isn't changing the schema, leave the override unset so the
                         //    server uses the stored schema.
-                        if (existingEntry) {
-                            const validateUpdateData = computeTypeUpdateData();
-                            const proposedSchema = "schema" in validateUpdateData
-                                ? validateUpdateData.schema
-                                : undefined;
+                        //
+                        //    Issue #915 (defect a): this gate now runs for FRESH types too
+                        //    (previously guarded by `if (existingEntry)`). For a brand-new
+                        //    db-type the server has no stored config, so we gate the op
+                        //    against the PROPOSED local schema via `schemaOverride`. The
+                        //    server's op-create dry-run accepts a missing type when a
+                        //    `schemaOverride` is present (see
+                        //    database-type-operations-controller.ts). A fresh schemaless
+                        //    type (#666 bootstrap) sends an empty/absent override, and
+                        //    `runSchemaGate` is a no-op without a schema — so that path
+                        //    still succeeds.
+                        {
+                            const localHasSchema = typeof typeConfig.schema === "string" &&
+                                typeConfig.schema.trim().length > 0;
+                            let proposedSchema;
+                            if (existingEntry) {
+                                const validateUpdateData = computeTypeUpdateData();
+                                proposedSchema =
+                                    "schema" in validateUpdateData
+                                        ? validateUpdateData.schema
+                                        : undefined;
+                            }
+                            else {
+                                // Fresh type: the proposed schema is whatever the local TOML
+                                // declares. A schemaless fresh type (no `[models.*]`) sends an
+                                // empty-string override so the server takes the no-schema =
+                                // no-op gate path rather than falling back to a (nonexistent)
+                                // stored config — keeping the #666 bootstrap convergent.
+                                proposedSchema = localHasSchema ? typeConfig.schema : "";
+                            }
                             for (const op of operations) {
                                 const existingOp = existingOpsForType[op.name];
                                 opGateContext = {
@@ -2833,7 +3083,20 @@ Directory Structure:
                                         access: op.access,
                                         definition: op.definition,
                                         params: op.params,
-                                    }, { dryRun: true, schemaOverride: proposedSchema });
+                                    }, {
+                                        dryRun: true,
+                                        schemaOverride: proposedSchema,
+                                        // Issue #915 (defect a, follow-up): for a fresh type the
+                                        // server has no stored config to read `defaultAccess`
+                                        // from, so an op that omits `access` to inherit the
+                                        // TOML-declared type-level `defaultAccess` would be
+                                        // falsely rejected. Thread the proposed value so the
+                                        // fresh-type dry-run gates the same way the real push
+                                        // (which lands the type first) will.
+                                        defaultAccess: typeof typeConfig.defaultAccess === "string"
+                                            ? typeConfig.defaultAccess
+                                            : undefined,
+                                    });
                                 }
                             }
                             // Every op gate passed; clear the context so a later (non-op)
@@ -3016,6 +3279,7 @@ Directory Structure:
                                         acceptWarnings: !!options.acceptWarnings,
                                     });
                                     info(`  Updated database type: ${dbType}`);
+                                    printStaleInstanceWarning(updated);
                                     if (syncState?.entities?.databaseTypes?.[dbType] && updated?.modifiedAt) {
                                         syncState.entities.databaseTypes[dbType].modifiedAt = updated.modifiedAt;
                                         syncState.entities.databaseTypes[dbType].contentHash = computeFileHash(filePath);
@@ -3258,6 +3522,7 @@ Directory Structure:
                                             dryRun: false,
                                             acceptWarnings: !!options.acceptWarnings,
                                         });
+                                        printStaleInstanceWarning(reconciled);
                                         if (syncState?.entities?.databaseTypes?.[dbType] &&
                                             reconciled?.modifiedAt) {
                                             syncState.entities.databaseTypes[dbType].modifiedAt =
@@ -3323,6 +3588,10 @@ Directory Structure:
                                             key: `${dbType}/${op.name}`,
                                             message: err.message,
                                         });
+                                        // Issue #915 (defect b): a gate-rejected op means this
+                                        // file's state did NOT fully land — don't poison the
+                                        // content hash (see the contentHash write below).
+                                        fileHadGateRejectedOp = true;
                                     }
                                     else if (err instanceof OperationRefError) {
                                         schemaErrors.opRefs.push({
@@ -3331,6 +3600,7 @@ Directory Structure:
                                             refs: err.refs,
                                             message: err.message,
                                         });
+                                        fileHadGateRejectedOp = true;
                                     }
                                     else {
                                         throw wrapEntityError(err, "update", "operation", `${dbType}/${op.name}`);
@@ -3368,6 +3638,10 @@ Directory Structure:
                                             key: `${dbType}/${op.name}`,
                                             message: err.message,
                                         });
+                                        // Issue #915 (defect b): a gate-rejected op means this
+                                        // file's state did NOT fully land — don't poison the
+                                        // content hash (see the contentHash write below).
+                                        fileHadGateRejectedOp = true;
                                     }
                                     else if (err instanceof OperationRefError) {
                                         schemaErrors.opRefs.push({
@@ -3376,6 +3650,7 @@ Directory Structure:
                                             refs: err.refs,
                                             message: err.message,
                                         });
+                                        fileHadGateRejectedOp = true;
                                     }
                                     else {
                                         throw wrapEntityError(err, "create", "operation", `${dbType}/${op.name}`);
@@ -3507,9 +3782,27 @@ Directory Structure:
                     // file. Recompute here so a truly-unchanged subsequent push skips
                     // the whole file via `shouldPushFile`. `--force` bypasses that
                     // skip, so forced re-pushes are unaffected.
+                    //
+                    // Issue #915 (defect b): when the gate rejected an op for this
+                    // file, do NOT record a matching content hash. The db-type itself
+                    // may have been created (the push is non-transactional), but the
+                    // blocked op never landed — a matching hash would make
+                    // `shouldPushFile` short-circuit the next push and hide the missing
+                    // op as "in sync". Clear the hash instead of writing it: an empty
+                    // hash forces `shouldPushFile` to re-evaluate the file, so a
+                    // subsequent `sync push --dry-run` still surfaces the op as drift
+                    // and a corrected re-push converges without manual file edits. We
+                    // clear (rather than merely skip) so the fresh-type create path's
+                    // earlier optimistic hash write (see `createDatabaseTypeConfig`
+                    // above) is also invalidated.
                     if (!options.dryRun && syncState?.entities?.databaseTypes?.[dbType]) {
-                        syncState.entities.databaseTypes[dbType].contentHash =
-                            computeFileHash(filePath);
+                        if (fileHadGateRejectedOp) {
+                            syncState.entities.databaseTypes[dbType].contentHash = "";
+                        }
+                        else {
+                            syncState.entities.databaseTypes[dbType].contentHash =
+                                computeFileHash(filePath);
+                        }
                     }
                 }
             }
@@ -4264,5 +4557,118 @@ Directory Structure:
             success(`Rewrote ${migratedCount} TOML file(s) to native form.`);
         }
     });
+    // Revert — restore a pre-pull snapshot (issue #578, Phase 1).
+    sync
+        .command("revert")
+        .description("Restore the sync directory from a snapshot taken before a previous pull")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
+        .option("--snapshot <id>", "Snapshot id (timestamp dirname or a unique >=8-char prefix)")
+        .option("--list", "List available snapshots without restoring")
+        .option("-y, --yes", "Skip the confirmation prompt")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const configDir = resolveSyncDir({
+            appId: resolvedAppId,
+            userDir: options.dir,
+        });
+        const snapshotsRoot = resolveSnapshotsRoot({
+            appId: resolvedAppId,
+            userDir: options.dir,
+        });
+        if (isAutoResolvedSyncDir(options.dir)) {
+            info(`Using per-environment sync directory: ${configDir}`);
+        }
+        const snapshots = listSnapshots(snapshotsRoot);
+        // --list, or no snapshots at all: enumerate and stop.
+        if (options.list || snapshots.length === 0) {
+            if (snapshots.length === 0) {
+                info(`No snapshots found in ${snapshotsRoot}`);
+                info("Snapshots are created automatically before each 'sync pull'.");
+                return;
+            }
+            divider();
+            info(`Snapshots for this slot (${snapshotsRoot}), newest first:`);
+            for (const snap of snapshots) {
+                const flags = [];
+                if (!snap.complete)
+                    flags.push("INCOMPLETE");
+                if (snap.auditId)
+                    flags.push(`audit=${snap.auditId}`);
+                const suffix = flags.length ? `  (${flags.join(", ")})` : "";
+                keyValue(snap.id, `${snap.createdAt.toISOString()}${suffix}`);
+            }
+            if (!options.list) {
+                info("");
+                info("Run 'primitive sync revert --snapshot <id>' to restore one, " +
+                    "or 'primitive sync revert' to restore the most recent.");
+            }
+            return;
+        }
+        // Resolve the target snapshot (exact id, unique prefix, or most-recent).
+        let target;
+        try {
+            target = resolveSnapshot(snapshotsRoot, options.snapshot);
+        }
+        catch (err) {
+            error(err?.message ?? String(err));
+            process.exit(1);
+        }
+        if (!target.complete) {
+            error(`Snapshot ${target.id} is incomplete (missing the integrity marker) and cannot be restored safely.`);
+            process.exit(1);
+        }
+        // Confirmation, with a dirty-git warning.
+        if (!options.yes) {
+            if (await hasUncommittedChanges(configDir)) {
+                warn(`You have uncommitted git changes under ${configDir}. ` +
+                    "Reverting will overwrite them.");
+            }
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Restore snapshot ${target.id} into ${configDir}? This overwrites the current sync directory.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        try {
+            // Under legacy `--dir`, snapshotsRoot lives inside configDir; preserve
+            // it across the full-tree swap so we don't wipe backup history.
+            restoreSnapshot(target.path, configDir, { preserveDir: snapshotsRoot });
+        }
+        catch (err) {
+            error(`Restore failed: ${err?.message ?? err}`);
+            process.exit(1);
+        }
+        success(`Restored snapshot ${target.id} into ${configDir} (including .primitive-sync.json).`);
+        info("Run 'primitive sync diff' to inspect the restored state versus the server.");
+    });
+}
+/**
+ * Best-effort check for uncommitted git changes under `dir`. Used only to warn
+ * before a revert overwrites local edits — never fatal. Returns false if git
+ * isn't available, the dir isn't in a repo, or anything goes wrong.
+ */
+async function hasUncommittedChanges(dir) {
+    if (!existsSync(dir))
+        return false;
+    try {
+        const { execSync } = await import("child_process");
+        const out = execSync(`git status --porcelain -- "${dir}"`, {
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf-8",
+        });
+        return out.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
 }
 //# sourceMappingURL=sync.js.map