primitive-admin 1.0.44 → 1.0.46

package/dist/src/commands/sync.js

@@ -3,9 +3,13 @@ import { join, basename } from "path";
 import { createHash } from "crypto";
 import * as TOML from "@iarna/toml";
 import { lookup as mimeLookup } from "mime-types";
-import { ApiClient, ConflictError } from "../lib/api-client.js";
+import { ApiClient, ApiError, ConflictError, SchemaRequiredError, OperationRefError, SchemaBreaksOpsError, SchemaHasUncheckableOpsError, TomlParseError, OpsExistError, } from "../lib/api-client.js";
+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 { 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 chalk from "chalk";
 function ensureDir(dirPath) {
@@ -29,6 +33,31 @@ function saveSyncState(configDir, state) {
     const syncFile = join(configDir, ".primitive-sync.json");
     writeFileSync(syncFile, JSON.stringify(state, null, 2));
 }
+/**
+ * Wrap a server-side error so the printed message identifies which entity
+ * was in flight. Used by every entity create/update/delete call site in the
+ * push loops (issue #684).
+ *
+ * Format: `Failed to ${action} ${kind} ${key}: ${serverMessage}`
+ *
+ * - `ConflictError` is rethrown unchanged so the existing
+ *   `ConflictError → conflicts[]` accumulator in each loop still fires.
+ * - Other errors are rewrapped as a new `ApiError` carrying the wrapped
+ *   message + the original `details[]` and `statusCode`.
+ */
+export function wrapEntityError(err, action, kind, key) {
+    if (err instanceof ConflictError) {
+        return err;
+    }
+    const original = err instanceof Error ? err.message : String(err?.message ?? err);
+    const wrappedMessage = `Failed to ${action} ${kind} ${key}: ${original}`;
+    if (err instanceof ApiError) {
+        return new ApiError(wrappedMessage, err.statusCode, err.code, err.details);
+    }
+    // Non-ApiError (e.g. network failure, JSON parse error) — preserve cause.
+    const wrapped = new Error(wrappedMessage);
+    return wrapped;
+}
 export function computeFileHash(filePath) {
     const content = readFileSync(filePath);
     return createHash("sha256").update(content).digest("hex");
@@ -38,6 +67,55 @@ export function shouldPushFile(filePath, storedHash) {
         return true;
     return computeFileHash(filePath) !== storedHash;
 }
+/**
+ * Canonical-JSON serializer for hash computation.
+ *
+ * Sorts object keys at every level so two semantically-equivalent JSON
+ * blobs produce the same string. Arrays preserve order (step order
+ * matters in workflows). Used by `computeExpandedContentHash`.
+ */
+function canonicalJsonStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map((v) => canonicalJsonStringify(v)).join(",") + "]";
+    }
+    const keys = Object.keys(value).sort();
+    return ("{" +
+        keys
+            .map((k) => JSON.stringify(k) + ":" + canonicalJsonStringify(value[k]))
+            .join(",") +
+        "}");
+}
+/**
+ * Hash the *expanded* (post-fragment-splice) content of a workflow TOML.
+ *
+ * The raw-file hash (`computeFileHash`) misses fragment-only edits: if a
+ * workflow uses `include = ["x"]` and only `workflow-fragments/x.toml`
+ * changes, the workflow file is byte-identical and shouldPushFile would
+ * skip the push, leaving the server with stale expanded steps.
+ *
+ * This helper hashes the parsed-and-expanded data instead, so fragment
+ * edits change the hash and force a re-push. Pass the already-parsed
+ * `tomlData` (from `parseTomlFile`) — that function runs the expander,
+ * so `tomlData` is the canonical expanded shape the server will see.
+ */
+export function computeExpandedContentHash(parsed) {
+    const canonical = canonicalJsonStringify(parsed);
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/**
+ * Variant of `shouldPushFile` for workflow files: compares the stored hash
+ * against the hash of the *expanded* content rather than the raw file
+ * bytes. Required so that edits to included fragments invalidate the
+ * push-skip cache for any workflow that references them.
+ */
+export function shouldPushExpandedFile(parsed, storedHash) {
+    if (!storedHash)
+        return true;
+    return computeExpandedContentHash(parsed) !== storedHash;
+}
 // TOML serialization helpers
 function serializeAppSettings(settings) {
     const data = {
@@ -224,6 +302,12 @@ function serializeWorkflow(workflow, draft, configs) {
             perUserMaxRunning: workflow.perUserMaxRunning,
             perUserMaxQueued: workflow.perUserMaxQueued,
             dequeueOrder: workflow.dequeueOrder,
+            // Sync-callable flags (#807): always emit both so a fresh pull → push
+            // cycle round-trips them. The GET response normalizes these to booleans
+            // (requiresClientApply defaults true, syncCallable defaults false), so
+            // they're safe to coerce here.
+            requiresClientApply: workflow.requiresClientApply !== false,
+            syncCallable: workflow.syncCallable === true,
             // Schemas are at workflow level
             inputSchema: workflow.inputSchema ? JSON.stringify(workflow.inputSchema) : undefined,
             outputSchema: workflow.outputSchema ? JSON.stringify(workflow.outputSchema) : undefined,
@@ -241,32 +325,20 @@ function serializeWorkflow(workflow, draft, configs) {
     return TOML.stringify(data);
 }
 // Database config serialization helpers
-function serializeDatabaseType(typeConfig, operations, ruleSetIdToName) {
-    const ruleSetName = typeConfig.ruleSetId ? (ruleSetIdToName.get(typeConfig.ruleSetId) || "") : "";
-    const data = {
-        type: {
-            databaseType: typeConfig.databaseType,
-            ruleSetName: ruleSetName,
-        },
-    };
-    if (typeConfig.metadataAccess) {
-        // Serialize under the new user-facing key. The legacy `metadataAccess`
-        // key is still accepted on read (see parseDatabaseTypeToml below).
-        data.type.celContextAccess = typeConfig.metadataAccess;
-    }
-    if (typeConfig.triggers) {
-        data.triggers = typeConfig.triggers;
-    }
-    if (operations.length > 0) {
-        data.operations = operations.map((op) => ({
-            name: op.name,
-            type: op.type,
-            modelName: op.modelName,
-            access: op.access,
-            definition: typeof op.definition === "object" ? JSON.stringify(op.definition) : op.definition,
-            ...(op.params ? { params: typeof op.params === "object" ? JSON.stringify(op.params) : op.params } : {}),
-        }));
-    }
+//
+// Native-TOML form (issue #752): when emitting a database-type config, we
+// prefer nested `[operations.definition]` tables and `[[operations.params]]`
+// rows over JSON-strings stuffed into a single field. The form is sticky
+// per file — if the existing file uses the legacy JSON-string form, we
+// preserve it so we don't generate surprise diffs. New files default to
+// native. Un-TOMLable shapes (null, mixed-type arrays) fall back to JSON
+// string per field with a log message.
+//
+// Issue #666: when the type has a stored `schema` (raw TOML of `[models.*]`
+// blocks), `buildDatabaseTypeTomlData` parses + merges it into the same TOML
+// object so the result round-trips as `[models.<Name>.fields.<field>]`.
+function serializeDatabaseType(typeConfig, operations, ruleSetIdToName, options = {}) {
+    const data = buildDatabaseTypeTomlData(typeConfig, operations, ruleSetIdToName, options);
     return TOML.stringify(data);
 }
 function serializeEmailTemplate(template) {
@@ -345,18 +417,58 @@ export function parseDatabaseTypeToml(tomlData) {
     else if (typeSection.metadataAccess) {
         typeConfig.metadataAccess = typeSection.metadataAccess;
     }
+    if (typeSection.defaultAccess !== undefined) {
+        typeConfig.defaultAccess = typeSection.defaultAccess;
+    }
+    // autoPopulatedFields (issue #750) — pass through unchanged. Both the
+    // shorthand (`ownerId = "user.userId"`) and the verbose object form
+    // (`updatedBy = { value = "user.userId", on = ["create","update"] }`) are
+    // accepted; the server validates and normalizes at write time.
+    if (typeSection.autoPopulatedFields !== undefined) {
+        typeConfig.autoPopulatedFields = typeSection.autoPopulatedFields;
+    }
+    // timestamps (issue #748) — inline-table form
+    // (`timestamps = { create = "createdAt", update = "modifiedAt" }`) passes
+    // through unchanged; the server validates and normalizes. Either lifecycle
+    // key may be omitted, and an optional `models = [...]` filter rides on the
+    // same object.
+    if (typeSection.timestamps !== undefined) {
+        typeConfig.timestamps = typeSection.timestamps;
+    }
     if (tomlData.triggers) {
         typeConfig.triggers = tomlData.triggers;
     }
-    const operations = (tomlData.operations || []).map((op) => ({
-        name: op.name,
-        type: op.type,
-        modelName: op.modelName,
-        access: op.access,
-        definition: typeof op.definition === "string" ? JSON.parse(op.definition) : op.definition,
-        params: op.params ? (typeof op.params === "string" ? JSON.parse(op.params) : op.params) : null,
-    }));
-    return { typeConfig, operations };
+    // Issue #666: extract the `[models.*]` subtree (if present) and re-serialize
+    // it to a TOML string for the server's `schema` field.
+    //
+    // We always set `schema` — either to the serialized TOML string or to
+    // `null` — so the sync push diff can detect "models removed from local
+    // file" and forward `schema: null` to the server. Without this, removing
+    // `[models.*]` blocks would silently no-op and the next pull would
+    // resurrect the stale server schema, making schema deletion via `sync push`
+    // impossible (codex review on PR #766, [P2]).
+    let schemaSerialized = null;
+    if (tomlData.models && typeof tomlData.models === "object") {
+        try {
+            schemaSerialized = TOML.stringify({ models: tomlData.models });
+        }
+        catch {
+            // Fall through — server-side parser will fail with a clear
+            // TOML_PARSE_ERROR if we somehow produced an invalid round-trip.
+        }
+    }
+    typeConfig.schema = schemaSerialized;
+    // `normalizeOperationFromToml` accepts both forms:
+    //   - legacy: `definition = '{...}'` (JSON string), `params = '{...}'`
+    //   - native: `[operations.definition]` table, `[[operations.params]]` rows
+    // and returns the JS shape the server expects.
+    const operations = (tomlData.operations || []).map((op) => normalizeOperationFromToml(op));
+    // Subscriptions (issue #803): `[[subscriptions]]` array-of-tables.
+    // `normalizeSubscriptionFromToml` maps `accessRule`→`access` (throwing on a
+    // conflicting both-present declaration) and forwards `select`/`emit`/`params`
+    // in the wire shape. Until #803 this block was dropped at parse time.
+    const subscriptions = (tomlData.subscriptions || []).map((sub) => normalizeSubscriptionFromToml(sub));
+    return { typeConfig, operations, subscriptions };
 }
 function parseRuleSetToml(tomlData) {
     const ruleSetSection = tomlData.ruleSet || {};
@@ -397,9 +509,16 @@ export function parseCollectionTypeConfigToml(tomlData) {
     return result;
 }
 // Parsing helpers
+//
+// All 20+ TOML parse sites in this file route through `parseTomlFile()`.
+// Workflow fragment expansion is wired in here so every push path (workflows,
+// prompts, tests, etc.) gets it for free. For non-workflow TOMLs the
+// expander is a no-op: if the parsed result has no `include` key, it returns
+// the original object untouched.
 function parseTomlFile(filePath) {
     const content = readFileSync(filePath, "utf-8");
-    return TOML.parse(content);
+    const parsed = TOML.parse(content);
+    return expandWorkflowTomlData(parsed, filePath);
 }
 /**
  * Paginate through a list endpoint, collecting all items.
@@ -974,10 +1093,20 @@ Directory Structure:
                 client.listGroupTypeConfigs(resolvedAppId).catch(() => []),
                 client.listCollectionTypeConfigs(resolvedAppId).catch(() => []),
             ]);
-            // Fetch operations for each database type
+            // Fetch operations + subscriptions for each database type. Issue #803:
+            // subscriptions are pulled symmetrically with operations so a
+            // pull → push cycle round-trips `[[subscriptions]]` blocks without a
+            // spurious diff. The list endpoint already excludes archived rows.
             const databaseTypesWithOps = await Promise.all((Array.isArray(databaseTypeConfigsResult) ? databaseTypeConfigsResult : []).map(async (typeConfig) => {
-                const ops = await client.listDatabaseTypeOperations(resolvedAppId, typeConfig.databaseType).catch(() => []);
-                return { typeConfig, operations: Array.isArray(ops) ? ops : [] };
+                const [ops, subs] = await Promise.all([
+                    client.listDatabaseTypeOperations(resolvedAppId, typeConfig.databaseType).catch(() => []),
+                    client.listDatabaseTypeSubscriptions(resolvedAppId, typeConfig.databaseType).catch(() => []),
+                ]);
+                return {
+                    typeConfig,
+                    operations: Array.isArray(ops) ? ops : [],
+                    subscriptions: Array.isArray(subs) ? subs : [],
+                };
             }));
             // Ensure directories exist
             ensureDir(configDir);
@@ -1087,11 +1216,16 @@ Directory Structure:
                 const filename = `${workflow.workflowKey}.toml`;
                 const filePath = join(configDir, "workflows", filename);
                 writeFileSync(filePath, serializeWorkflow(workflow, draft, configs || []));
+                // Hash the expanded (post-fragment-splice) form so subsequent pushes
+                // can detect fragment-only edits. See `computeExpandedContentHash`.
+                // Pulled workflows never carry `include`, so the expander is a
+                // no-op here — but we use the same canonical-JSON hash function so
+                // the push-side comparison stays consistent.
                 workflowEntities[workflow.workflowKey] = {
                     id: workflow.workflowId,
                     modifiedAt: workflow.modifiedAt || new Date().toISOString(),
                     activeConfigId: workflow.activeConfigId,
-                    contentHash: computeFileHash(filePath),
+                    contentHash: computeExpandedContentHash(parseTomlFile(filePath)),
                 };
                 info(`  Wrote workflows/${filename}`);
             }
@@ -1164,21 +1298,48 @@ Directory Structure:
             }
             // Write database types
             const databaseTypeEntities = {};
-            for (const { typeConfig, operations } of databaseTypesWithOps) {
+            for (const { typeConfig, operations, subscriptions } of databaseTypesWithOps) {
                 const filename = `${typeConfig.databaseType}.toml`;
                 const filePath = join(configDir, "database-types", filename);
-                writeFileSync(filePath, serializeDatabaseType(typeConfig, operations, ruleSetIdToName));
+                // Preserve the existing file's per-op form (issue #752): if the
+                // file already exists, read it raw and detect which operations
+                // currently use JSON-string vs native nested-table form.
+                const hints = existsSync(filePath)
+                    ? detectExistingOperationForms(readFileSync(filePath, "utf-8"))
+                    : undefined;
+                writeFileSync(filePath, serializeDatabaseType(typeConfig, operations, ruleSetIdToName, {
+                    hints,
+                    defaultForm: "native",
+                    logger: (msg) => info(`  ${msg}`),
+                    // Issue #803: emit `[[subscriptions]]` blocks so a pull → push
+                    // cycle round-trips subscriptions without a spurious diff.
+                    subscriptions,
+                }));
                 const opsEntities = {};
                 for (const op of operations) {
                     opsEntities[op.name] = {
                         modifiedAt: op.modifiedAt || new Date().toISOString(),
                     };
                 }
+                // Track per-subscription modifiedAt in SyncState (issue #803),
+                // exactly like operations, so the next push skips unchanged
+                // subscriptions and detects removals.
+                const subsEntities = {};
+                for (const sub of subscriptions || []) {
+                    if (!sub?.subscriptionKey)
+                        continue;
+                    subsEntities[sub.subscriptionKey] = {
+                        modifiedAt: sub.modifiedAt || new Date().toISOString(),
+                    };
+                }
                 databaseTypeEntities[typeConfig.databaseType] = {
                     databaseType: typeConfig.databaseType,
                     modifiedAt: typeConfig.modifiedAt || new Date().toISOString(),
                     operations: Object.keys(opsEntities).length > 0 ? opsEntities : undefined,
+                    subscriptions: Object.keys(subsEntities).length > 0 ? subsEntities : undefined,
                     contentHash: computeFileHash(filePath),
+                    hasSchema: typeof typeConfig.schema === "string" &&
+                        typeConfig.schema.trim().length > 0,
                 };
                 info(`  Wrote database-types/${filename}`);
             }
@@ -1277,6 +1438,7 @@ Directory Structure:
         .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
         .option("--dry-run", "Show what would be changed without applying")
         .option("--force", "Overwrite remote even if modified since last pull")
+        .option("--accept-warnings", "Commit schema diffs that have operations with dynamic refs (issue #666 SCHEMA_HAS_UNCHECKABLE_OPS escape hatch)")
         .action(async (appId, options) => {
         const resolvedAppId = resolveAppId(appId, options);
         const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
@@ -1310,6 +1472,17 @@ Directory Structure:
             const changes = [];
             let skippedCount = 0;
             const conflicts = [];
+            // Issue #666: per-class buckets for schema-feature errors. Each entry
+            // groups failures by the code so the end-of-run report can print
+            // them once with the friendly hint.
+            const schemaErrors = {
+                schemaRequired: [],
+                opRefs: [],
+                schemaBreaks: [],
+                uncheckableOps: [],
+                tomlParse: [],
+                opsExist: [],
+            };
             // Track name→ID mappings for resolving cross-references during push
             const ruleSetNameToId = new Map();
             const promptKeyToId = new Map();
@@ -1408,7 +1581,7 @@ Directory Structure:
                                     });
                                 }
                                 else {
-                                    throw err;
+                                    throw wrapEntityError(err, "update", "rule set", fileKey);
                                 }
                             }
                         }
@@ -1419,12 +1592,18 @@ Directory Structure:
                         // Create new rule set
                         changes.push({ type: "rule-set", action: "create", key: fileKey });
                         if (!options.dryRun) {
-                            const created = await client.createRuleSet(resolvedAppId, {
-                                name: ruleSetData.name,
-                                resourceType: ruleSetData.resourceType,
-                                rules: ruleSetData.rules,
-                                description: ruleSetData.description,
-                            });
+                            let created;
+                            try {
+                                created = await client.createRuleSet(resolvedAppId, {
+                                    name: ruleSetData.name,
+                                    resourceType: ruleSetData.resourceType,
+                                    rules: ruleSetData.rules,
+                                    description: ruleSetData.description,
+                                });
+                            }
+                            catch (err) {
+                                throw wrapEntityError(err, "create", "rule set", fileKey);
+                            }
                             info(`  Created rule set: ${fileKey}`);
                             if (syncState && created?.ruleSetId) {
                                 if (!syncState.entities.ruleSets) {
@@ -1494,7 +1673,7 @@ Directory Structure:
                                     });
                                 }
                                 else {
-                                    throw err;
+                                    throw wrapEntityError(err, "update", "integration", key);
                                 }
                             }
                         }
@@ -1502,18 +1681,23 @@ Directory Structure:
                     else {
                         changes.push({ type: "integration", action: "create", key });
                         if (!options.dryRun) {
-                            const created = await client.createIntegration(resolvedAppId, payload);
-                            info(`  Created integration: ${key}`);
-                            // Add new entity to sync state
-                            if (syncState && created?.integrationId && created?.modifiedAt) {
-                                if (!syncState.entities.integrations) {
-                                    syncState.entities.integrations = {};
-                                }
-                                syncState.entities.integrations[key] = {
-                                    id: created.integrationId,
-                                    modifiedAt: created.modifiedAt,
-                                    contentHash: computeFileHash(filePath),
-                                };
+                            try {
+                                const created = await client.createIntegration(resolvedAppId, payload);
+                                info(`  Created integration: ${key}`);
+                                // Add new entity to sync state
+                                if (syncState && created?.integrationId && created?.modifiedAt) {
+                                    if (!syncState.entities.integrations) {
+                                        syncState.entities.integrations = {};
+                                    }
+                                    syncState.entities.integrations[key] = {
+                                        id: created.integrationId,
+                                        modifiedAt: created.modifiedAt,
+                                        contentHash: computeFileHash(filePath),
+                                    };
+                                }
+                            }
+                            catch (err) {
+                                throw wrapEntityError(err, "create", "integration", key);
                             }
                         }
                     }
@@ -1580,7 +1764,7 @@ Directory Structure:
                                     });
                                 }
                                 else {
-                                    throw err;
+                                    throw wrapEntityError(err, "update", "webhook", key);
                                 }
                             }
                         }
@@ -1588,17 +1772,22 @@ Directory Structure:
                     else {
                         changes.push({ type: "webhook", action: "create", key });
                         if (!options.dryRun) {
-                            const created = await client.createWebhook(resolvedAppId, payload);
-                            info(`  Created webhook: ${key}`);
-                            if (syncState && created?.webhookId && created?.modifiedAt) {
-                                if (!syncState.entities.webhooks) {
-                                    syncState.entities.webhooks = {};
-                                }
-                                syncState.entities.webhooks[key] = {
-                                    id: created.webhookId,
-                                    modifiedAt: created.modifiedAt,
-                                    contentHash: computeFileHash(filePath),
-                                };
+                            try {
+                                const created = await client.createWebhook(resolvedAppId, payload);
+                                info(`  Created webhook: ${key}`);
+                                if (syncState && created?.webhookId && created?.modifiedAt) {
+                                    if (!syncState.entities.webhooks) {
+                                        syncState.entities.webhooks = {};
+                                    }
+                                    syncState.entities.webhooks[key] = {
+                                        id: created.webhookId,
+                                        modifiedAt: created.modifiedAt,
+                                        contentHash: computeFileHash(filePath),
+                                    };
+                                }
+                            }
+                            catch (err) {
+                                throw wrapEntityError(err, "create", "webhook", key);
                             }
                         }
                     }
@@ -1648,24 +1837,29 @@ Directory Structure:
                                 }
                             }
                             catch (err) {
-                                throw err;
+                                throw wrapEntityError(err, "update", "cron trigger", key);
                             }
                         }
                     }
                     else {
                         changes.push({ type: "cron-trigger", action: "create", key });
                         if (!options.dryRun) {
-                            const created = await client.createCronTrigger(resolvedAppId, payload);
-                            info(`  Created cron trigger: ${key}`);
-                            if (syncState && created?.triggerId && created?.modifiedAt) {
-                                if (!syncState.entities.cronTriggers) {
-                                    syncState.entities.cronTriggers = {};
-                                }
-                                syncState.entities.cronTriggers[key] = {
-                                    id: created.triggerId,
-                                    modifiedAt: created.modifiedAt,
-                                    contentHash: computeFileHash(filePath),
-                                };
+                            try {
+                                const created = await client.createCronTrigger(resolvedAppId, payload);
+                                info(`  Created cron trigger: ${key}`);
+                                if (syncState && created?.triggerId && created?.modifiedAt) {
+                                    if (!syncState.entities.cronTriggers) {
+                                        syncState.entities.cronTriggers = {};
+                                    }
+                                    syncState.entities.cronTriggers[key] = {
+                                        id: created.triggerId,
+                                        modifiedAt: created.modifiedAt,
+                                        contentHash: computeFileHash(filePath),
+                                    };
+                                }
+                            }
+                            catch (err) {
+                                throw wrapEntityError(err, "create", "cron trigger", key);
                             }
                         }
                     }
@@ -1743,7 +1937,7 @@ Directory Structure:
                                     }
                                 }
                                 else {
-                                    throw err;
+                                    throw wrapEntityError(err, "create", "blob bucket", key);
                                 }
                             }
                         }
@@ -1857,7 +2051,7 @@ Directory Structure:
                                     });
                                 }
                                 else {
-                                    throw err;
+                                    throw wrapEntityError(err, "update", "prompt", key);
                                 }
                             }
                         }
@@ -1867,65 +2061,70 @@ Directory Structure:
                         const firstConfig = configs[0] || {};
                         changes.push({ type: "prompt", action: "create", key });
                         if (!options.dryRun) {
-                            const created = await client.createPrompt(resolvedAppId, {
-                                promptKey: key,
-                                displayName: prompt.displayName || key,
-                                description: prompt.description,
-                                provider: firstConfig.provider || "openrouter",
-                                model: firstConfig.model || "google/gemini-2.0-flash-001",
-                                systemPrompt: firstConfig.systemPrompt,
-                                userPromptTemplate: firstConfig.userPromptTemplate || "{{ input }}",
-                                temperature: firstConfig.temperature,
-                                maxTokens: firstConfig.maxTokens,
-                                outputFormat: firstConfig.outputFormat,
-                                inputSchema: prompt.inputSchema,
-                            });
-                            info(`  Created prompt: ${key}`);
-                            // Add new entity to sync state
-                            if (syncState && created?.promptId && created?.modifiedAt) {
-                                if (!syncState.entities.prompts) {
-                                    syncState.entities.prompts = {};
-                                }
-                                syncState.entities.prompts[key] = {
-                                    id: created.promptId,
-                                    modifiedAt: created.modifiedAt,
-                                    contentHash: computeFileHash(filePath),
-                                };
-                            }
-                            // Track prompt key→ID and config name→ID
-                            if (created?.promptId) {
-                                promptKeyToId.set(key, created.promptId);
-                            }
-                            if (created?.configs) {
-                                for (const config of created.configs) {
-                                    promptConfigNameToId.set(`${key}#${config.configName}`, config.configId);
+                            try {
+                                const created = await client.createPrompt(resolvedAppId, {
+                                    promptKey: key,
+                                    displayName: prompt.displayName || key,
+                                    description: prompt.description,
+                                    provider: firstConfig.provider || "openrouter",
+                                    model: firstConfig.model || "google/gemini-2.0-flash-001",
+                                    systemPrompt: firstConfig.systemPrompt,
+                                    userPromptTemplate: firstConfig.userPromptTemplate || "{{ input }}",
+                                    temperature: firstConfig.temperature,
+                                    maxTokens: firstConfig.maxTokens,
+                                    outputFormat: firstConfig.outputFormat,
+                                    inputSchema: prompt.inputSchema,
+                                });
+                                info(`  Created prompt: ${key}`);
+                                // Add new entity to sync state
+                                if (syncState && created?.promptId && created?.modifiedAt) {
+                                    if (!syncState.entities.prompts) {
+                                        syncState.entities.prompts = {};
+                                    }
+                                    syncState.entities.prompts[key] = {
+                                        id: created.promptId,
+                                        modifiedAt: created.modifiedAt,
+                                        contentHash: computeFileHash(filePath),
+                                    };
                                 }
-                            }
-                            // Create additional configs (configs[1..n]) that weren't included in the initial create
-                            if (created?.promptId && configs.length > 1) {
-                                for (let i = 1; i < configs.length; i++) {
-                                    const extraConfig = configs[i];
-                                    const extraCreated = await client.createPromptConfig(resolvedAppId, created.promptId, {
-                                        configName: extraConfig.name || `config-${i + 1}`,
-                                        description: extraConfig.description,
-                                        provider: extraConfig.provider || firstConfig.provider || "openrouter",
-                                        model: extraConfig.model || firstConfig.model || "google/gemini-2.0-flash-001",
-                                        systemPrompt: extraConfig.systemPrompt,
-                                        userPromptTemplate: extraConfig.userPromptTemplate,
-                                        temperature: extraConfig.temperature,
-                                        maxTokens: extraConfig.maxTokens,
-                                        outputFormat: extraConfig.outputFormat,
-                                    });
-                                    if (extraCreated?.configId) {
-                                        const configName = extraConfig.name || `config-${i + 1}`;
-                                        promptConfigNameToId.set(`${key}#${configName}`, extraCreated.configId);
+                                // Track prompt key→ID and config name→ID
+                                if (created?.promptId) {
+                                    promptKeyToId.set(key, created.promptId);
+                                }
+                                if (created?.configs) {
+                                    for (const config of created.configs) {
+                                        promptConfigNameToId.set(`${key}#${config.configName}`, config.configId);
                                     }
-                                    // Activate this config if it was the active one
-                                    if (extraConfig.isActive && extraCreated?.configId) {
-                                        await client.activatePromptConfig(resolvedAppId, created.promptId, extraCreated.configId);
+                                }
+                                // Create additional configs (configs[1..n]) that weren't included in the initial create
+                                if (created?.promptId && configs.length > 1) {
+                                    for (let i = 1; i < configs.length; i++) {
+                                        const extraConfig = configs[i];
+                                        const extraCreated = await client.createPromptConfig(resolvedAppId, created.promptId, {
+                                            configName: extraConfig.name || `config-${i + 1}`,
+                                            description: extraConfig.description,
+                                            provider: extraConfig.provider || firstConfig.provider || "openrouter",
+                                            model: extraConfig.model || firstConfig.model || "google/gemini-2.0-flash-001",
+                                            systemPrompt: extraConfig.systemPrompt,
+                                            userPromptTemplate: extraConfig.userPromptTemplate,
+                                            temperature: extraConfig.temperature,
+                                            maxTokens: extraConfig.maxTokens,
+                                            outputFormat: extraConfig.outputFormat,
+                                        });
+                                        if (extraCreated?.configId) {
+                                            const configName = extraConfig.name || `config-${i + 1}`;
+                                            promptConfigNameToId.set(`${key}#${configName}`, extraCreated.configId);
+                                        }
+                                        // Activate this config if it was the active one
+                                        if (extraConfig.isActive && extraCreated?.configId) {
+                                            await client.activatePromptConfig(resolvedAppId, created.promptId, extraCreated.configId);
+                                        }
                                     }
+                                    info(`    Created ${configs.length - 1} additional config(s) for prompt: ${key}`);
                                 }
-                                info(`    Created ${configs.length - 1} additional config(s) for prompt: ${key}`);
+                            }
+                            catch (err) {
+                                throw wrapEntityError(err, "create", "prompt", key);
                             }
                         }
                     }
@@ -1938,13 +2137,27 @@ Directory Structure:
                 for (const file of files) {
                     const filePath = join(workflowsDir, file);
                     const tomlData = parseTomlFile(filePath);
+                    // Issue #685: reject misnested headers (e.g.
+                    // [steps.<id>.request]) before pushing. The runtime silently
+                    // ignores fields outside the allowlist, so this is the only
+                    // 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.
+                    const tomlErrors = validateWorkflowToml(tomlData);
+                    if (tomlErrors.length > 0) {
+                        error(formatWorkflowTomlErrors(filePath, tomlErrors));
+                        process.exit(1);
+                    }
                     const workflow = tomlData.workflow || {};
                     const key = workflow.key || basename(file, ".toml");
                     const steps = tomlData.steps || [];
                     const existingId = syncState?.entities?.workflows?.[key]?.id;
                     const existingActiveConfigId = syncState?.entities?.workflows?.[key]?.activeConfigId;
-                    // Skip if file hasn't changed since last sync
-                    if (!options.force && existingId && !shouldPushFile(filePath, syncState?.entities?.workflows?.[key]?.contentHash)) {
+                    // Skip if file hasn't changed since last sync. Use the expanded
+                    // content hash (post fragment splice) so that edits to included
+                    // `workflow-fragments/*.toml` files invalidate the push-skip cache
+                    // for any workflow that references them. See `computeExpandedContentHash`.
+                    if (!options.force && existingId && !shouldPushExpandedFile(tomlData, syncState?.entities?.workflows?.[key]?.contentHash)) {
                         skippedCount++;
                         // Only fetch config name→ID mappings if test cases exist for this workflow
                         const workflowTestsDir = getTestsDir(configDir, "workflow", key);
@@ -1966,7 +2179,21 @@ Directory Structure:
                                 ? undefined
                                 : syncState?.entities?.workflows?.[key]?.modifiedAt;
                             try {
-                                // Update workflow metadata and schemas
+                                // Update workflow metadata and schemas.
+                                //
+                                // Sync-callable ordering (#807, codex review): the metadata
+                                // PATCH must NOT carry `syncCallable: true` here. The server
+                                // re-validates `syncCallable: true` against the workflow's
+                                // CURRENTLY-active server steps (`loadCurrentActiveSteps`),
+                                // not the steps being pushed in the same sync. So when a
+                                // single TOML edit both enables `syncCallable` and replaces
+                                // sync-incompatible active steps with compatible ones, a
+                                // combined metadata-first PATCH would be rejected against the
+                                // stale steps. Defer `syncCallable` to a second PATCH issued
+                                // AFTER the config/step update lands, so it validates against
+                                // the new (compatible) active steps. `requiresClientApply`
+                                // has no step-dependent validation, so it stays in the first
+                                // PATCH unchanged.
                                 const updated = await client.updateWorkflow(resolvedAppId, existingId, {
                                     name: workflow.name,
                                     description: workflow.description,
@@ -1975,10 +2202,23 @@ Directory Structure:
                                     perUserMaxRunning: workflow.perUserMaxRunning,
                                     perUserMaxQueued: workflow.perUserMaxQueued,
                                     dequeueOrder: workflow.dequeueOrder,
+                                    // Sync-callable flags (#807): pass through as-is. An absent
+                                    // TOML key is `undefined` (dropped by JSON.stringify, so the
+                                    // server's hasOwnProperty guard leaves the value untouched);
+                                    // an explicit `false` is preserved as a meaningful value.
+                                    requiresClientApply: workflow.requiresClientApply,
                                     inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
                                     outputSchema: workflow.outputSchema ? safeJsonParse(workflow.outputSchema) : null,
                                 }, expectedModifiedAt);
-                                // Update active configuration steps (or draft for legacy)
+                                // Track the latest workflow `modifiedAt` for the sync-state
+                                // write below. The first PATCH bumps it; the `syncCallable`
+                                // PATCH (if any) bumps it again. The config/step update does
+                                // NOT touch the workflow definition's `modifiedAt`.
+                                let latestModifiedAt = updated?.workflow?.modifiedAt;
+                                // Update active configuration steps (or draft for legacy).
+                                // Issue #687: name the slot we touched so the dev-loop
+                                // user can confirm before previewing.
+                                let updateSlotLabel = "active config";
                                 if (existingActiveConfigId) {
                                     await client.updateWorkflowConfig(resolvedAppId, existingId, existingActiveConfigId, {
                                         steps,
@@ -1990,12 +2230,31 @@ Directory Structure:
                                         steps,
                                         inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
                                     });
+                                    updateSlotLabel = "draft (legacy)";
                                 }
-                                info(`  Updated workflow: ${key}`);
-                                // Update sync state with new modifiedAt
-                                if (syncState?.entities?.workflows?.[key] && updated?.workflow?.modifiedAt) {
-                                    syncState.entities.workflows[key].modifiedAt = updated.workflow.modifiedAt;
-                                    syncState.entities.workflows[key].contentHash = computeFileHash(filePath);
+                                // Second PATCH: apply `syncCallable` now that the new steps
+                                // are active (#807). Only sent when the TOML actually carries
+                                // the key — an absent key stays `undefined` and we skip the
+                                // call entirely, preserving the no-clobber discipline. Chain
+                                // `expectedModifiedAt` off the first PATCH's returned value so
+                                // optimistic concurrency stays intact (the step update above
+                                // doesn't change the workflow definition's `modifiedAt`).
+                                if (workflow.syncCallable !== undefined) {
+                                    const syncCallableUpdated = await client.updateWorkflow(resolvedAppId, existingId, { syncCallable: workflow.syncCallable }, 
+                                    // Mirror the first PATCH's concurrency posture: `--force`
+                                    // skips the check (undefined), otherwise reuse the fresh
+                                    // `modifiedAt` from the first PATCH.
+                                    options.force ? undefined : latestModifiedAt);
+                                    if (syncCallableUpdated?.workflow?.modifiedAt) {
+                                        latestModifiedAt = syncCallableUpdated.workflow.modifiedAt;
+                                    }
+                                }
+                                info(`  Updated workflow: ${key} (${updateSlotLabel})`);
+                                // Update sync state with new modifiedAt. Store the *expanded*
+                                // content hash so future fragment-only edits are detected.
+                                if (syncState?.entities?.workflows?.[key] && latestModifiedAt) {
+                                    syncState.entities.workflows[key].modifiedAt = latestModifiedAt;
+                                    syncState.entities.workflows[key].contentHash = computeExpandedContentHash(tomlData);
                                 }
                                 // Fetch full workflow to get config name→ID mappings
                                 // (updateWorkflow response doesn't include configs)
@@ -2016,7 +2275,7 @@ Directory Structure:
                                     });
                                 }
                                 else {
-                                    throw err;
+                                    throw wrapEntityError(err, "update", "workflow", key);
                                 }
                             }
                         }
@@ -2025,63 +2284,74 @@ Directory Structure:
                         // Create new workflow (automatically creates default config)
                         changes.push({ type: "workflow", action: "create", key });
                         if (!options.dryRun) {
-                            const created = await client.createWorkflow(resolvedAppId, {
-                                workflowKey: key,
-                                name: workflow.name || key,
-                                description: workflow.description,
-                                steps,
-                                inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : undefined,
-                                outputSchema: workflow.outputSchema ? safeJsonParse(workflow.outputSchema) : undefined,
-                                accessRule: workflow.accessRule || undefined,
-                                perUserMaxRunning: workflow.perUserMaxRunning,
-                                perUserMaxQueued: workflow.perUserMaxQueued,
-                                dequeueOrder: workflow.dequeueOrder,
-                            });
-                            info(`  Created workflow: ${key}`);
-                            // Add new entity to sync state (including activeConfigId)
-                            if (syncState && created?.workflow?.workflowId && created?.workflow?.modifiedAt) {
-                                if (!syncState.entities.workflows) {
-                                    syncState.entities.workflows = {};
-                                }
-                                syncState.entities.workflows[key] = {
-                                    id: created.workflow.workflowId,
-                                    modifiedAt: created.workflow.modifiedAt,
-                                    activeConfigId: created.workflow.activeConfigId,
-                                    contentHash: computeFileHash(filePath),
-                                };
-                            }
-                            // Track config name→ID mappings
-                            if (created?.configs) {
-                                for (const config of created.configs) {
-                                    workflowConfigNameToId.set(`${key}#${config.configName}`, config.configId);
+                            try {
+                                const created = await client.createWorkflow(resolvedAppId, {
+                                    workflowKey: key,
+                                    name: workflow.name || key,
+                                    description: workflow.description,
+                                    steps,
+                                    inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : undefined,
+                                    outputSchema: workflow.outputSchema ? safeJsonParse(workflow.outputSchema) : undefined,
+                                    accessRule: workflow.accessRule || undefined,
+                                    perUserMaxRunning: workflow.perUserMaxRunning,
+                                    perUserMaxQueued: workflow.perUserMaxQueued,
+                                    dequeueOrder: workflow.dequeueOrder,
+                                    // Sync-callable flags (#807): pass through as-is. An absent
+                                    // TOML key is `undefined` (dropped by JSON.stringify), so the
+                                    // server applies its defaults (requiresClientApply=true,
+                                    // syncCallable=false); an explicit value is honored.
+                                    requiresClientApply: workflow.requiresClientApply,
+                                    syncCallable: workflow.syncCallable,
+                                });
+                                info(`  Created workflow: ${key}`);
+                                // Add new entity to sync state (including activeConfigId)
+                                if (syncState && created?.workflow?.workflowId && created?.workflow?.modifiedAt) {
+                                    if (!syncState.entities.workflows) {
+                                        syncState.entities.workflows = {};
+                                    }
+                                    syncState.entities.workflows[key] = {
+                                        id: created.workflow.workflowId,
+                                        modifiedAt: created.workflow.modifiedAt,
+                                        activeConfigId: created.workflow.activeConfigId,
+                                        contentHash: computeExpandedContentHash(tomlData),
+                                    };
                                 }
-                            }
-                            const workflowId = created?.workflow?.workflowId;
-                            const tomlConfigs = tomlData.configs || [];
-                            // Create additional workflow configs (configs[1..n]) beyond the default
-                            if (workflowId && tomlConfigs.length > 1) {
-                                for (let i = 1; i < tomlConfigs.length; i++) {
-                                    const extraConfig = tomlConfigs[i];
-                                    const extraCreated = await client.createWorkflowConfig(resolvedAppId, workflowId, {
-                                        configName: extraConfig.name || `config-${i + 1}`,
-                                        description: extraConfig.description,
-                                        steps,
-                                    });
-                                    if (extraCreated?.configId) {
-                                        const configName = extraConfig.name || `config-${i + 1}`;
-                                        workflowConfigNameToId.set(`${key}#${configName}`, extraCreated.configId);
+                                // Track config name→ID mappings
+                                if (created?.configs) {
+                                    for (const config of created.configs) {
+                                        workflowConfigNameToId.set(`${key}#${config.configName}`, config.configId);
                                     }
                                 }
-                                info(`    Created ${tomlConfigs.length - 1} additional config(s) for workflow: ${key}`);
-                            }
-                            // Activate the correct config based on activeConfigName from TOML
-                            if (workflowId && workflow.activeConfigName) {
-                                const activeConfigId = workflowConfigNameToId.get(`${key}#${workflow.activeConfigName}`);
-                                if (activeConfigId && activeConfigId !== created?.workflow?.activeConfigId) {
-                                    await client.activateWorkflowConfig(resolvedAppId, workflowId, activeConfigId);
-                                    info(`    Activated config "${workflow.activeConfigName}" for workflow: ${key}`);
+                                const workflowId = created?.workflow?.workflowId;
+                                const tomlConfigs = tomlData.configs || [];
+                                // Create additional workflow configs (configs[1..n]) beyond the default
+                                if (workflowId && tomlConfigs.length > 1) {
+                                    for (let i = 1; i < tomlConfigs.length; i++) {
+                                        const extraConfig = tomlConfigs[i];
+                                        const extraCreated = await client.createWorkflowConfig(resolvedAppId, workflowId, {
+                                            configName: extraConfig.name || `config-${i + 1}`,
+                                            description: extraConfig.description,
+                                            steps,
+                                        });
+                                        if (extraCreated?.configId) {
+                                            const configName = extraConfig.name || `config-${i + 1}`;
+                                            workflowConfigNameToId.set(`${key}#${configName}`, extraCreated.configId);
+                                        }
+                                    }
+                                    info(`    Created ${tomlConfigs.length - 1} additional config(s) for workflow: ${key}`);
+                                }
+                                // Activate the correct config based on activeConfigName from TOML
+                                if (workflowId && workflow.activeConfigName) {
+                                    const activeConfigId = workflowConfigNameToId.get(`${key}#${workflow.activeConfigName}`);
+                                    if (activeConfigId && activeConfigId !== created?.workflow?.activeConfigId) {
+                                        await client.activateWorkflowConfig(resolvedAppId, workflowId, activeConfigId);
+                                        info(`    Activated config "${workflow.activeConfigName}" for workflow: ${key}`);
+                                    }
                                 }
                             }
+                            catch (err) {
+                                throw wrapEntityError(err, "create", "workflow", key);
+                            }
                         }
                     }
                 }
@@ -2092,11 +2362,49 @@ Directory Structure:
                 const files = readdirSync(dbTypesDir).filter((f) => f.endsWith(".toml"));
                 for (const file of files) {
                     const filePath = join(dbTypesDir, file);
+                    const rawToml = readFileSync(filePath, "utf-8");
                     const tomlData = parseTomlFile(filePath);
-                    const { typeConfig, operations } = parseDatabaseTypeToml(tomlData);
+                    let typeConfig;
+                    let operations;
+                    let subscriptions;
+                    try {
+                        ({ typeConfig, operations, subscriptions } =
+                            parseDatabaseTypeToml(tomlData));
+                    }
+                    catch (err) {
+                        // The only structured parse error today is the
+                        // `accessRule`/`access` conflict in a `[[subscriptions]]` block
+                        // (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);
+                        }
+                        throw err;
+                    }
                     const dbType = typeConfig.databaseType || basename(file, ".toml");
                     // Resolve ruleSetName → ruleSetId if using key-based reference
                     resolveRuleSetReference(typeConfig, ruleSetNameToId, `database type ${dbType}`);
+                    // $params validator (issue #752): every `$params.X` reference
+                    // inside `definition` must correspond to a declared param in
+                    // `[[operations.params]]`. Catches typos like `$params.proectId`
+                    // at push time with the TOML file:line of the offending op block.
+                    const validation = validateOperations({
+                        filePath,
+                        rawToml,
+                        operations,
+                    });
+                    for (const w of validation.warnings) {
+                        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);
+                    }
                     const existingEntry = syncState?.entities?.databaseTypes?.[dbType];
                     // Skip if file hasn't changed since last sync
                     if (!options.force && existingEntry && !shouldPushFile(filePath, existingEntry.contentHash)) {
@@ -2120,13 +2428,44 @@ Directory Structure:
                                     updateData.triggers = typeConfig.triggers || null;
                                 if ("metadataAccess" in typeConfig)
                                     updateData.metadataAccess = typeConfig.metadataAccess || null;
+                                if ("defaultAccess" in typeConfig)
+                                    updateData.defaultAccess = typeConfig.defaultAccess || null;
+                                if ("autoPopulatedFields" in typeConfig) {
+                                    updateData.autoPopulatedFields =
+                                        typeConfig.autoPopulatedFields || null;
+                                }
+                                if ("timestamps" in typeConfig) {
+                                    updateData.timestamps = typeConfig.timestamps || null;
+                                }
+                                // Issue #666: forward `schema` when the local TOML declares
+                                // one (a set/update), OR when the server had one at last
+                                // sync and the local file no longer does (a deletion —
+                                // `schema: null` clears it server-side; codex review gap on
+                                // PR #766). When the type never had a schema and still
+                                // doesn't, omit it so an operations-only edit doesn't
+                                // register as an empty type-level update (issue #369).
+                                const localHasSchema = typeof typeConfig.schema === "string" &&
+                                    typeConfig.schema.trim().length > 0;
+                                if (localHasSchema) {
+                                    updateData.schema = typeConfig.schema;
+                                }
+                                else if (existingEntry.hasSchema) {
+                                    updateData.schema = null;
+                                }
                                 if (Object.keys(updateData).length > 0) {
                                     changes.push({ type: "database-type", action: "update", key: dbType });
-                                    const updated = await client.updateDatabaseTypeConfig(resolvedAppId, dbType, updateData, expectedModifiedAt);
+                                    const updated = await client.updateDatabaseTypeConfig(resolvedAppId, dbType, updateData, expectedModifiedAt, {
+                                        dryRun: !!options.dryRun,
+                                        acceptWarnings: !!options.acceptWarnings,
+                                    });
                                     info(`  Updated database type: ${dbType}`);
                                     if (syncState?.entities?.databaseTypes?.[dbType] && updated?.modifiedAt) {
                                         syncState.entities.databaseTypes[dbType].modifiedAt = updated.modifiedAt;
                                         syncState.entities.databaseTypes[dbType].contentHash = computeFileHash(filePath);
+                                        syncState.entities.databaseTypes[dbType].hasSchema =
+                                            "schema" in updateData
+                                                ? updateData.schema !== null
+                                                : syncState.entities.databaseTypes[dbType].hasSchema;
                                     }
                                 }
                             }
@@ -2139,8 +2478,41 @@ Directory Structure:
                                         localModifiedAt: expectedModifiedAt || "unknown",
                                     });
                                 }
+                                else if (err instanceof SchemaBreaksOpsError) {
+                                    schemaErrors.schemaBreaks.push({
+                                        type: "database-type",
+                                        key: dbType,
+                                        operations: err.operations,
+                                        message: err.message,
+                                    });
+                                }
+                                else if (err instanceof SchemaHasUncheckableOpsError) {
+                                    schemaErrors.uncheckableOps.push({
+                                        type: "database-type",
+                                        key: dbType,
+                                        operations: err.operations,
+                                        message: err.message,
+                                    });
+                                }
+                                else if (err instanceof TomlParseError) {
+                                    schemaErrors.tomlParse.push({
+                                        type: "database-type",
+                                        key: dbType,
+                                        line: err.line,
+                                        column: err.column,
+                                        message: err.message,
+                                    });
+                                }
+                                else if (err instanceof OpsExistError) {
+                                    schemaErrors.opsExist.push({
+                                        type: "database-type",
+                                        key: dbType,
+                                        opCount: err.opCount,
+                                        message: err.message,
+                                    });
+                                }
                                 else {
-                                    throw err;
+                                    throw wrapEntityError(err, "update", "database type", dbType);
                                 }
                             }
                         }
@@ -2148,7 +2520,11 @@ Directory Structure:
                             // In dry-run mode, still report the change iff we would actually PATCH.
                             const wouldUpdate = "ruleSetId" in typeConfig ||
                                 "triggers" in typeConfig ||
-                                "metadataAccess" in typeConfig;
+                                "metadataAccess" in typeConfig ||
+                                "defaultAccess" in typeConfig ||
+                                "autoPopulatedFields" in typeConfig ||
+                                "timestamps" in typeConfig ||
+                                "schema" in typeConfig;
                             if (wouldUpdate) {
                                 changes.push({ type: "database-type", action: "update", key: dbType });
                             }
@@ -2167,17 +2543,37 @@ Directory Structure:
                                 createData.triggers = typeConfig.triggers;
                             if (typeConfig.metadataAccess)
                                 createData.metadataAccess = typeConfig.metadataAccess;
-                            const created = await client.createDatabaseTypeConfig(resolvedAppId, createData);
-                            info(`  Created database type: ${dbType}`);
-                            if (syncState) {
-                                if (!syncState.entities.databaseTypes) {
-                                    syncState.entities.databaseTypes = {};
+                            if (typeConfig.defaultAccess)
+                                createData.defaultAccess = typeConfig.defaultAccess;
+                            if (typeConfig.autoPopulatedFields)
+                                createData.autoPopulatedFields = typeConfig.autoPopulatedFields;
+                            if (typeConfig.timestamps)
+                                createData.timestamps = typeConfig.timestamps;
+                            // Issue #666 addendum A2: forward `schema` on POST so a
+                            // single sync push can land both the type + its schema in
+                            // one round-trip (instead of POST → PATCH). The op-edit gate
+                            // itself no longer requires a schema on a fresh type, but
+                            // landing the schema up front keeps subsequent op-pushes
+                            // validating against the intended shape.
+                            if (typeConfig.schema)
+                                createData.schema = typeConfig.schema;
+                            try {
+                                const created = await client.createDatabaseTypeConfig(resolvedAppId, createData);
+                                info(`  Created database type: ${dbType}`);
+                                if (syncState) {
+                                    if (!syncState.entities.databaseTypes) {
+                                        syncState.entities.databaseTypes = {};
+                                    }
+                                    syncState.entities.databaseTypes[dbType] = {
+                                        databaseType: dbType,
+                                        modifiedAt: created?.modifiedAt || new Date().toISOString(),
+                                        contentHash: computeFileHash(filePath),
+                                        hasSchema: !!createData.schema,
+                                    };
                                 }
-                                syncState.entities.databaseTypes[dbType] = {
-                                    databaseType: dbType,
-                                    modifiedAt: created?.modifiedAt || new Date().toISOString(),
-                                    contentHash: computeFileHash(filePath),
-                                };
+                            }
+                            catch (err) {
+                                throw wrapEntityError(err, "create", "database type", dbType);
                             }
                         }
                     }
@@ -2195,6 +2591,10 @@ Directory Structure:
                                     : existingOp.modifiedAt;
                                 try {
                                     const updated = await client.updateDatabaseTypeOperation(resolvedAppId, dbType, op.name, {
+                                        // Include `type` so the server can detect/apply
+                                        // type-in-place changes (issue #692). When the type
+                                        // matches the stored value, this is a no-op.
+                                        type: op.type,
                                         modelName: op.modelName,
                                         access: op.access,
                                         definition: op.definition,
@@ -2214,8 +2614,23 @@ Directory Structure:
                                             localModifiedAt: expectedOpModifiedAt || "unknown",
                                         });
                                     }
+                                    else if (err instanceof SchemaRequiredError) {
+                                        schemaErrors.schemaRequired.push({
+                                            type: "operation",
+                                            key: `${dbType}/${op.name}`,
+                                            message: err.message,
+                                        });
+                                    }
+                                    else if (err instanceof OperationRefError) {
+                                        schemaErrors.opRefs.push({
+                                            type: "operation",
+                                            key: `${dbType}/${op.name}`,
+                                            refs: err.refs,
+                                            message: err.message,
+                                        });
+                                    }
                                     else {
-                                        throw err;
+                                        throw wrapEntityError(err, "update", "operation", `${dbType}/${op.name}`);
                                     }
                                 }
                             }
@@ -2224,22 +2639,44 @@ Directory Structure:
                             // Create new operation
                             changes.push({ type: "operation", action: "create", key: `${dbType}/${op.name}` });
                             if (!options.dryRun) {
-                                const created = await client.createDatabaseTypeOperation(resolvedAppId, dbType, {
-                                    name: op.name,
-                                    type: op.type,
-                                    modelName: op.modelName,
-                                    access: op.access,
-                                    definition: op.definition,
-                                    params: op.params,
-                                });
-                                info(`  Created operation: ${dbType}/${op.name}`);
-                                if (syncState?.entities?.databaseTypes?.[dbType]) {
-                                    if (!syncState.entities.databaseTypes[dbType].operations) {
-                                        syncState.entities.databaseTypes[dbType].operations = {};
+                                try {
+                                    const created = await client.createDatabaseTypeOperation(resolvedAppId, dbType, {
+                                        name: op.name,
+                                        type: op.type,
+                                        modelName: op.modelName,
+                                        access: op.access,
+                                        definition: op.definition,
+                                        params: op.params,
+                                    });
+                                    info(`  Created operation: ${dbType}/${op.name}`);
+                                    if (syncState?.entities?.databaseTypes?.[dbType]) {
+                                        if (!syncState.entities.databaseTypes[dbType].operations) {
+                                            syncState.entities.databaseTypes[dbType].operations = {};
+                                        }
+                                        syncState.entities.databaseTypes[dbType].operations[op.name] = {
+                                            modifiedAt: created?.modifiedAt || new Date().toISOString(),
+                                        };
+                                    }
+                                }
+                                catch (err) {
+                                    if (err instanceof SchemaRequiredError) {
+                                        schemaErrors.schemaRequired.push({
+                                            type: "operation",
+                                            key: `${dbType}/${op.name}`,
+                                            message: err.message,
+                                        });
+                                    }
+                                    else if (err instanceof OperationRefError) {
+                                        schemaErrors.opRefs.push({
+                                            type: "operation",
+                                            key: `${dbType}/${op.name}`,
+                                            refs: err.refs,
+                                            message: err.message,
+                                        });
+                                    }
+                                    else {
+                                        throw wrapEntityError(err, "create", "operation", `${dbType}/${op.name}`);
                                     }
-                                    syncState.entities.databaseTypes[dbType].operations[op.name] = {
-                                        modifiedAt: created?.modifiedAt || new Date().toISOString(),
-                                    };
                                 }
                             }
                         }
@@ -2249,14 +2686,128 @@ Directory Structure:
                         if (!tomlOpNames.has(existingOpName)) {
                             changes.push({ type: "operation", action: "delete", key: `${dbType}/${existingOpName}` });
                             if (!options.dryRun) {
-                                await client.deleteDatabaseTypeOperation(resolvedAppId, dbType, existingOpName);
-                                info(`  Deleted operation: ${dbType}/${existingOpName}`);
-                                if (syncState?.entities?.databaseTypes?.[dbType]?.operations) {
-                                    delete syncState.entities.databaseTypes[dbType].operations[existingOpName];
+                                try {
+                                    await client.deleteDatabaseTypeOperation(resolvedAppId, dbType, existingOpName);
+                                    info(`  Deleted operation: ${dbType}/${existingOpName}`);
+                                    if (syncState?.entities?.databaseTypes?.[dbType]?.operations) {
+                                        delete syncState.entities.databaseTypes[dbType].operations[existingOpName];
+                                    }
+                                }
+                                catch (err) {
+                                    throw wrapEntityError(err, "delete", "operation", `${dbType}/${existingOpName}`);
+                                }
+                            }
+                        }
+                    }
+                    // Process subscriptions for this type (issue #803). Mirrors the
+                    // operations reconcile above, keyed on `subscriptionKey`:
+                    // create new keys, PUT changed/existing keys, delete keys present
+                    // in SyncState but absent from the TOML. Server errors (409 key
+                    // collision, `#`-in-key 400, max-20 400, missing-required 400)
+                    // are surfaced cleanly via `wrapEntityError` — named, not a crash.
+                    const existingSubs = syncState?.entities?.databaseTypes?.[dbType]?.subscriptions || {};
+                    const tomlSubKeys = new Set(subscriptions.map((sub) => sub.subscriptionKey));
+                    for (const sub of subscriptions) {
+                        const subKey = sub.subscriptionKey;
+                        const existingSub = existingSubs[subKey];
+                        if (existingSub) {
+                            // Update existing subscription (PUT — idempotent).
+                            changes.push({ type: "subscription", action: "update", key: `${dbType}/${subKey}` });
+                            if (!options.dryRun) {
+                                try {
+                                    const updated = await client.updateDatabaseTypeSubscription(resolvedAppId, dbType, subKey, {
+                                        displayName: sub.displayName,
+                                        modelName: sub.modelName,
+                                        filter: sub.filter,
+                                        access: sub.access,
+                                        description: sub.description,
+                                        select: sub.select,
+                                        emit: sub.emit,
+                                        params: sub.params,
+                                        status: sub.status,
+                                    });
+                                    info(`  Updated subscription: ${dbType}/${subKey}`);
+                                    // Gate the SyncState write on a server-returned
+                                    // `modifiedAt`, mirroring the operations precedent above
+                                    // (don't fall back to a fresh local timestamp).
+                                    if (syncState?.entities?.databaseTypes?.[dbType]?.subscriptions?.[subKey] && updated?.modifiedAt) {
+                                        syncState.entities.databaseTypes[dbType].subscriptions[subKey].modifiedAt =
+                                            updated.modifiedAt;
+                                    }
+                                }
+                                catch (err) {
+                                    throw wrapEntityError(err, "update", "subscription", `${dbType}/${subKey}`);
+                                }
+                            }
+                        }
+                        else {
+                            // Create new subscription (POST).
+                            changes.push({ type: "subscription", action: "create", key: `${dbType}/${subKey}` });
+                            if (!options.dryRun) {
+                                try {
+                                    const created = await client.createDatabaseTypeSubscription(resolvedAppId, dbType, {
+                                        subscriptionKey: subKey,
+                                        displayName: sub.displayName,
+                                        modelName: sub.modelName,
+                                        filter: sub.filter,
+                                        access: sub.access,
+                                        description: sub.description,
+                                        select: sub.select,
+                                        emit: sub.emit,
+                                        params: sub.params,
+                                        status: sub.status,
+                                    });
+                                    info(`  Created subscription: ${dbType}/${subKey}`);
+                                    if (syncState?.entities?.databaseTypes?.[dbType]) {
+                                        if (!syncState.entities.databaseTypes[dbType].subscriptions) {
+                                            syncState.entities.databaseTypes[dbType].subscriptions = {};
+                                        }
+                                        syncState.entities.databaseTypes[dbType].subscriptions[subKey] = {
+                                            modifiedAt: created?.modifiedAt || new Date().toISOString(),
+                                        };
+                                    }
+                                }
+                                catch (err) {
+                                    throw wrapEntityError(err, "create", "subscription", `${dbType}/${subKey}`);
                                 }
                             }
                         }
                     }
+                    // Delete subscriptions that were removed from TOML (hard-delete on
+                    // current `main`, PR #787 — frees the key for reuse). A 409 on
+                    // recreate is impossible here since we delete first; the pull-side
+                    // "active only" filter (controller `list` excludes archived)
+                    // agrees because hard-delete leaves no archived row behind.
+                    for (const existingSubKey of Object.keys(existingSubs)) {
+                        if (!tomlSubKeys.has(existingSubKey)) {
+                            changes.push({ type: "subscription", action: "delete", key: `${dbType}/${existingSubKey}` });
+                            if (!options.dryRun) {
+                                try {
+                                    await client.deleteDatabaseTypeSubscription(resolvedAppId, dbType, existingSubKey);
+                                    info(`  Deleted subscription: ${dbType}/${existingSubKey}`);
+                                    if (syncState?.entities?.databaseTypes?.[dbType]?.subscriptions) {
+                                        delete syncState.entities.databaseTypes[dbType].subscriptions[existingSubKey];
+                                    }
+                                }
+                                catch (err) {
+                                    throw wrapEntityError(err, "delete", "subscription", `${dbType}/${existingSubKey}`);
+                                }
+                            }
+                        }
+                    }
+                    // Refresh the file's content hash after processing operations +
+                    // subscriptions (issue #803, behavior g). The type-config update
+                    // block only refreshes the hash when a type-level field changed
+                    // (its `updateData` was non-empty); an operations- or
+                    // subscriptions-only edit left a stale hash, so the next push
+                    // would re-PUT every op/sub instead of skipping the unchanged
+                    // 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.
+                    if (!options.dryRun && syncState?.entities?.databaseTypes?.[dbType]) {
+                        syncState.entities.databaseTypes[dbType].contentHash =
+                            computeFileHash(filePath);
+                    }
                 }
             }
             // Process group type configs
@@ -2304,7 +2855,7 @@ Directory Structure:
                                     });
                                 }
                                 else {
-                                    throw err;
+                                    throw wrapEntityError(err, "update", "group type config", groupType);
                                 }
                             }
                         }
@@ -2313,20 +2864,25 @@ Directory Structure:
                         // Create new group type config
                         changes.push({ type: "group-type-config", action: "create", key: groupType });
                         if (!options.dryRun) {
-                            const created = await client.createGroupTypeConfig(resolvedAppId, {
-                                groupType,
-                                ruleSetId: configData.ruleSetId || undefined,
-                                autoAddCreator: configData.autoAddCreator,
-                            });
-                            info(`  Created group type config: ${groupType}`);
-                            if (syncState) {
-                                if (!syncState.entities.groupTypeConfigs) {
-                                    syncState.entities.groupTypeConfigs = {};
+                            try {
+                                const created = await client.createGroupTypeConfig(resolvedAppId, {
+                                    groupType,
+                                    ruleSetId: configData.ruleSetId || undefined,
+                                    autoAddCreator: configData.autoAddCreator,
+                                });
+                                info(`  Created group type config: ${groupType}`);
+                                if (syncState) {
+                                    if (!syncState.entities.groupTypeConfigs) {
+                                        syncState.entities.groupTypeConfigs = {};
+                                    }
+                                    syncState.entities.groupTypeConfigs[groupType] = {
+                                        modifiedAt: created?.modifiedAt || new Date().toISOString(),
+                                        contentHash: computeFileHash(filePath),
+                                    };
                                 }
-                                syncState.entities.groupTypeConfigs[groupType] = {
-                                    modifiedAt: created?.modifiedAt || new Date().toISOString(),
-                                    contentHash: computeFileHash(filePath),
-                                };
+                            }
+                            catch (err) {
+                                throw wrapEntityError(err, "create", "group type config", groupType);
                             }
                         }
                     }
@@ -2376,7 +2932,7 @@ Directory Structure:
                                     });
                                 }
                                 else {
-                                    throw err;
+                                    throw wrapEntityError(err, "update", "collection type config", collectionType);
                                 }
                             }
                         }
@@ -2385,19 +2941,24 @@ Directory Structure:
                         // Create new collection type config
                         changes.push({ type: "collection-type-config", action: "create", key: collectionType });
                         if (!options.dryRun) {
-                            const created = await client.createCollectionTypeConfig(resolvedAppId, {
-                                collectionType,
-                                ruleSetId: configData.ruleSetId || undefined,
-                            });
-                            info(`  Created collection type config: ${collectionType}`);
-                            if (syncState) {
-                                if (!syncState.entities.collectionTypeConfigs) {
-                                    syncState.entities.collectionTypeConfigs = {};
+                            try {
+                                const created = await client.createCollectionTypeConfig(resolvedAppId, {
+                                    collectionType,
+                                    ruleSetId: configData.ruleSetId || undefined,
+                                });
+                                info(`  Created collection type config: ${collectionType}`);
+                                if (syncState) {
+                                    if (!syncState.entities.collectionTypeConfigs) {
+                                        syncState.entities.collectionTypeConfigs = {};
+                                    }
+                                    syncState.entities.collectionTypeConfigs[collectionType] = {
+                                        modifiedAt: created?.modifiedAt || new Date().toISOString(),
+                                        contentHash: computeFileHash(filePath),
+                                    };
                                 }
-                                syncState.entities.collectionTypeConfigs[collectionType] = {
-                                    modifiedAt: created?.modifiedAt || new Date().toISOString(),
-                                    contentHash: computeFileHash(filePath),
-                                };
+                            }
+                            catch (err) {
+                                throw wrapEntityError(err, "create", "collection type config", collectionType);
                             }
                         }
                     }
@@ -2478,33 +3039,118 @@ Directory Structure:
                     console.log(`  ${color(change.action)} ${change.type}: ${change.key}`);
                 }
             }
-            else if (conflicts.length > 0) {
+            else if (conflicts.length > 0 ||
+                schemaErrors.schemaRequired.length > 0 ||
+                schemaErrors.opRefs.length > 0 ||
+                schemaErrors.schemaBreaks.length > 0 ||
+                schemaErrors.uncheckableOps.length > 0 ||
+                schemaErrors.tomlParse.length > 0 ||
+                schemaErrors.opsExist.length > 0) {
                 // Handle conflicts
-                console.log();
-                warn(`${conflicts.length} conflict(s) detected:`);
-                console.log();
-                for (const conflict of conflicts) {
-                    console.log(`  ${chalk.red("CONFLICT")} ${conflict.type}: ${chalk.bold(conflict.key)}`);
-                    console.log(`    Local last sync: ${chalk.dim(conflict.localModifiedAt)}`);
-                    console.log(`    Server modified: ${chalk.yellow(conflict.serverModifiedAt)}`);
+                if (conflicts.length > 0) {
+                    console.log();
+                    warn(`${conflicts.length} conflict(s) detected:`);
+                    console.log();
+                    for (const conflict of conflicts) {
+                        console.log(`  ${chalk.red("CONFLICT")} ${conflict.type}: ${chalk.bold(conflict.key)}`);
+                        console.log(`    Local last sync: ${chalk.dim(conflict.localModifiedAt)}`);
+                        console.log(`    Server modified: ${chalk.yellow(conflict.serverModifiedAt)}`);
+                    }
+                    console.log();
+                    warn("These entities were modified on the server since your last pull.");
+                    info("Options:");
+                    console.log(`  1. Run ${chalk.cyan("primitive sync pull")} to get latest changes`);
+                    console.log(`  2. Run ${chalk.cyan("primitive sync push --force")} to overwrite server`);
+                    console.log();
+                }
+                // Report schema-feature errors (issue #666).
+                if (schemaErrors.schemaRequired.length > 0) {
+                    console.log();
+                    warn(`${schemaErrors.schemaRequired.length} operation push(es) blocked: type has no schema set.`);
+                    for (const e of schemaErrors.schemaRequired) {
+                        const type = e.key.split("/")[0];
+                        console.log(`  ${chalk.red("SCHEMA_REQUIRED")} ${e.key}`);
+                        console.log(`    Run ${chalk.cyan(`primitive databases schema generate ${type}`)} to scaffold one, then retry.`);
+                    }
+                    console.log();
+                }
+                if (schemaErrors.opRefs.length > 0) {
+                    console.log();
+                    warn(`${schemaErrors.opRefs.length} operation push(es) blocked: unresolved references.`);
+                    for (const e of schemaErrors.opRefs) {
+                        console.log(`  ${chalk.red("OPERATION_REFERENCES_UNDEFINED")} ${e.key}`);
+                        for (const ref of e.refs) {
+                            console.log(`    - ${chalk.yellow(ref.ref)} at ${chalk.dim(ref.location)}`);
+                        }
+                    }
+                    console.log();
+                }
+                if (schemaErrors.schemaBreaks.length > 0) {
+                    console.log();
+                    warn(`${schemaErrors.schemaBreaks.length} schema push(es) blocked: existing operations would break.`);
+                    for (const e of schemaErrors.schemaBreaks) {
+                        console.log(`  ${chalk.red("SCHEMA_BREAKS_OPERATIONS")} ${e.key}`);
+                        for (const op of e.operations) {
+                            console.log(`    ${chalk.bold(op.operation)}`);
+                            for (const ref of op.refs) {
+                                console.log(`      - ${chalk.yellow(ref.ref)} at ${chalk.dim(ref.location)}`);
+                            }
+                        }
+                    }
+                    console.log();
+                }
+                if (schemaErrors.uncheckableOps.length > 0) {
+                    console.log();
+                    warn(`${schemaErrors.uncheckableOps.length} schema push(es) blocked: operations with dynamic refs.`);
+                    for (const e of schemaErrors.uncheckableOps) {
+                        console.log(`  ${chalk.red("SCHEMA_HAS_UNCHECKABLE_OPS")} ${e.key}`);
+                        for (const op of e.operations) {
+                            console.log(`    ${chalk.bold(op.operation)}`);
+                            for (const loc of op.locations) {
+                                console.log(`      - ${chalk.dim(loc)}`);
+                            }
+                        }
+                    }
+                    info(`Re-run with ${chalk.cyan("--accept-warnings")} to commit anyway.`);
+                    console.log();
+                }
+                if (schemaErrors.tomlParse.length > 0) {
+                    console.log();
+                    warn(`${schemaErrors.tomlParse.length} TOML parse error(s):`);
+                    for (const e of schemaErrors.tomlParse) {
+                        const loc = e.line ? ` (line ${e.line}${e.column ? `, col ${e.column}` : ""})` : "";
+                        console.log(`  ${chalk.red("TOML_PARSE_ERROR")} ${e.key}${loc}`);
+                        console.log(`    ${e.message}`);
+                    }
+                    console.log();
+                }
+                if (schemaErrors.opsExist.length > 0) {
+                    console.log();
+                    warn(`${schemaErrors.opsExist.length} schema delete(s) blocked: operations still registered.`);
+                    for (const e of schemaErrors.opsExist) {
+                        console.log(`  ${chalk.red("OPS_EXIST")} ${e.key} — ${e.opCount} op(s)`);
+                        console.log(`    Delete or migrate the affected operations before clearing the schema.`);
+                    }
+                    console.log();
                 }
-                console.log();
-                warn("These entities were modified on the server since your last pull.");
-                info("Options:");
-                console.log(`  1. Run ${chalk.cyan("primitive sync pull")} to get latest changes`);
-                console.log(`  2. Run ${chalk.cyan("primitive sync push --force")} to overwrite server`);
-                console.log();
                 // Update sync state for non-conflicting changes
                 if (syncState) {
                     syncState.lastSyncedAt = new Date().toISOString();
                     saveSyncState(configDir, syncState);
                 }
-                const successCount = changes.length - conflicts.length;
+                const totalBlocked = conflicts.length +
+                    schemaErrors.schemaRequired.length +
+                    schemaErrors.opRefs.length +
+                    schemaErrors.schemaBreaks.length +
+                    schemaErrors.uncheckableOps.length +
+                    schemaErrors.tomlParse.length +
+                    schemaErrors.opsExist.length;
+                const successCount = changes.length - totalBlocked;
                 if (successCount > 0) {
-                    success(`Pushed ${successCount} change(s). ${conflicts.length} conflict(s) skipped.`);
+                    success(`Pushed ${successCount} change(s). ${totalBlocked} blocked.`);
                 }
                 else {
-                    error(`Push failed: ${conflicts.length} conflict(s). No changes applied.`);
+                    error(`Push failed: ${totalBlocked} blocked. No changes applied.`);
                 }
                 process.exit(1);
             }
@@ -2532,6 +3178,12 @@ Directory Structure:
                 }
             }
             error(err.message);
+            // Print structured server-side validation details (issue #684).
+            if (err instanceof ApiError && Array.isArray(err.details) && err.details.length > 0) {
+                for (const detail of err.details) {
+                    console.error(`    - ${typeof detail === "string" ? detail : JSON.stringify(detail)}`);
+                }
+            }
             process.exit(1);
         }
     });
@@ -2852,5 +3504,123 @@ Directory Structure:
             process.exit(1);
         }
     });
+    // Migrate-toml (issue #752): bulk-rewrite database-type TOML files from
+    // the legacy JSON-string form for `definition`/`params` to the native
+    // nested-table form. Idempotent: ops already in native form are left as
+    // is; ops that are un-TOMLable (mixed-type arrays, null values) fall
+    // back to JSON-string per field with a log message.
+    sync
+        .command("migrate-toml")
+        .description("Rewrite database-type TOML files to native [operations.definition] / [[operations.params]] form")
+        .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("--dry-run", "Show what would change without writing files")
+        .action(async (appId, options) => {
+        // 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.
+        const resolvedAppId = resolveAppId(appId, options);
+        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
+        if (isAutoResolvedSyncDir(options.dir)) {
+            info(`Using per-environment sync directory: ${configDir}`);
+        }
+        if (!existsSync(configDir)) {
+            error(`Config directory not found: ${configDir}`);
+            process.exit(1);
+        }
+        const dbTypesDir = join(configDir, "database-types");
+        if (!existsSync(dbTypesDir)) {
+            info("No database-types/ directory found; nothing to migrate.");
+            return;
+        }
+        const files = readdirSync(dbTypesDir).filter((f) => f.endsWith(".toml"));
+        if (files.length === 0) {
+            info("No database-type TOML files found; nothing to migrate.");
+            return;
+        }
+        // Hydrate ruleSetIdToName from local sync state so files that
+        // reference a rule set via the legacy `ruleSetId = "01..."` form
+        // round-trip with the correct `ruleSetName`. Without this, any user
+        // who runs migrate-toml against a file with a rule-set assignment
+        // would silently lose that reference (review feedback r3246633010).
+        //
+        // Files that use the modern key-based `ruleSetName = "..."` form
+        // don't need the map at all — `parseDatabaseTypeToml` stores the
+        // value in `typeConfig._ruleSetName` and the serializer now prefers
+        // that. The map is only load-bearing for the legacy ID-based form.
+        const ruleSetIdToName = new Map();
+        const migrateSyncState = loadSyncState(configDir);
+        if (migrateSyncState?.entities?.ruleSets) {
+            for (const [fileKey, entry] of Object.entries(migrateSyncState.entities.ruleSets)) {
+                if (entry && typeof entry === "object" && "id" in entry && entry.id) {
+                    // fileKey is the sanitized rule-set name (see sync pull at
+                    // sync.ts:1385). It's the same shape the server returned and
+                    // matches what a TOML file's ruleSetName field would carry.
+                    ruleSetIdToName.set(entry.id, fileKey);
+                }
+            }
+        }
+        let migratedCount = 0;
+        let unchangedCount = 0;
+        for (const file of files) {
+            const filePath = join(dbTypesDir, file);
+            const rawBefore = readFileSync(filePath, "utf-8");
+            const tomlData = parseTomlFile(filePath);
+            // `accessRule`/`access` conflicts surface as a clear error here too,
+            // rather than silently dropping the field during a migrate rewrite.
+            let typeConfig;
+            let operations;
+            let subscriptions;
+            try {
+                ({ typeConfig, operations, subscriptions } =
+                    parseDatabaseTypeToml(tomlData));
+            }
+            catch (err) {
+                if (err instanceof SubscriptionAccessKeyConflictError) {
+                    error(`  ${file}: ${err.message}`);
+                    error(`Aborting migrate-toml: subscription \`access\`/\`accessRule\` conflict in ${file}.`);
+                    process.exit(1);
+                }
+                throw err;
+            }
+            // Force-native: ignore existing hints so every TOMLable field
+            // ends up in nested-table form. Subscriptions are preserved on the
+            // rewrite (issue #803) so migrate-toml never drops them.
+            const rewritten = serializeDatabaseType(typeConfig, operations, ruleSetIdToName, {
+                defaultForm: "native",
+                logger: (msg) => info(`  ${msg}`),
+                subscriptions,
+            });
+            if (rewritten === rawBefore) {
+                unchangedCount++;
+                continue;
+            }
+            if (options.dryRun) {
+                info(`Would migrate database-types/${file}`);
+            }
+            else {
+                writeFileSync(filePath, rewritten);
+                info(`Migrated database-types/${file}`);
+                // Update content hash in sync state if we have an entry for it.
+                const syncState = loadSyncState(configDir);
+                const dbType = typeConfig.databaseType || basename(file, ".toml");
+                if (syncState?.entities?.databaseTypes?.[dbType]) {
+                    syncState.entities.databaseTypes[dbType].contentHash = computeFileHash(filePath);
+                    saveSyncState(configDir, syncState);
+                }
+            }
+            migratedCount++;
+        }
+        divider();
+        keyValue("Migrated", migratedCount);
+        keyValue("Already native (unchanged)", unchangedCount);
+        if (options.dryRun) {
+            info("Dry-run only — no files were modified.");
+        }
+        else if (migratedCount > 0) {
+            success(`Rewrote ${migratedCount} TOML file(s) to native form.`);
+        }
+    });
 }
 //# sourceMappingURL=sync.js.map