primitive-admin 1.1.0-alpha.38 → 1.1.0-alpha.39

package/dist/src/commands/sync.js

@@ -5,12 +5,15 @@ import * as TOML from "@iarna/toml";
 import { lookup as mimeLookup } from "mime-types";
 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 { parseMetadataCategoryToml, validateMetadataCategoryConfig, serializeMetadataCategoryConfig, parseDeclaredAccessManifestToml, validateDeclaredAccessManifest, serializeDeclaredAccessManifest, } from "../lib/toml-metadata-config.js";
 import { validateOperations, formatIssue, } from "../lib/toml-params-validator.js";
 import { getServerUrl, resolveAppId } from "../lib/config.js";
 import { resolveSyncDir, resolveSnapshotsRoot, isAutoResolvedSyncDir, checkLegacySyncMigration, } from "../lib/sync-paths.js";
 import { createSnapshot, listSnapshots, resolveSnapshot, restoreSnapshot, pruneSnapshots, } from "../lib/snapshots.js";
 import { validateWorkflowToml, formatWorkflowTomlErrors, } from "../lib/workflow-toml-validator.js";
 import { expandWorkflowTomlData } from "../lib/workflow-fragments.js";
+import { applyWorkflowBody } from "../lib/workflow-apply.js";
+import { detectLayout, migrateLegacyToV2 } from "../lib/block-layout.js";
 import { success, error, printApiError, info, warn, keyValue, json, divider, } from "../lib/output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import chalk from "chalk";
@@ -199,6 +202,87 @@ export function hashRemoteWorkflowForDiff(workflow, draft, configs) {
     const parsed = TOML.parse(serialized);
     return hashWorkflowTomlForDiff(parsed);
 }
+// Boolean [auth] keys in app.toml that map 1:1 to app-settings fields.
+const AUTH_BOOLEAN_KEYS = [
+    "googleOAuthEnabled",
+    "passkeyEnabled",
+    "magicLinkEnabled",
+    "appleSignInEnabled",
+    "otpEnabled",
+];
+// Every recognized [auth] key. Single source of truth shared by pull
+// serialization, push parsing, and the unrecognized-key warning so the three
+// never drift apart. `appleAudiences` is a string array and `passkeys` is the
+// passkey RP config object; the rest are booleans.
+const RECOGNIZED_AUTH_KEYS = new Set([
+    ...AUTH_BOOLEAN_KEYS,
+    "appleAudiences",
+    "passkeys",
+]);
+/**
+ * Build the [auth] block of app.toml from server settings (pull direction).
+ *
+ * Apple/OTP fields round-trip alongside the legacy google/passkey/magic-link
+ * keys. Two asymmetries are handled deliberately:
+ *  - `appleSignInEnabled` comes back as `boolean | null`; @iarna/toml throws on
+ *    null, so an unset value (null) is omitted rather than written.
+ *  - `appleAudiences` is omitted when empty. An empty array and an omitted key
+ *    both mean "no audiences" (the server normalizes [] -> null), so omitting
+ *    an empty list on pull is not lossy.
+ */
+export function serializeAuthBlock(settings) {
+    const auth = {
+        googleOAuthEnabled: settings.googleOAuthEnabled,
+        passkeyEnabled: settings.passkeyEnabled,
+        magicLinkEnabled: settings.magicLinkEnabled,
+    };
+    if (typeof settings.appleSignInEnabled === "boolean") {
+        auth.appleSignInEnabled = settings.appleSignInEnabled;
+    }
+    if (Array.isArray(settings.appleAudiences) &&
+        settings.appleAudiences.length > 0) {
+        auth.appleAudiences = settings.appleAudiences;
+    }
+    if (typeof settings.otpEnabled === "boolean") {
+        auth.otpEnabled = settings.otpEnabled;
+    }
+    if (settings.passkeyRpConfig) {
+        auth.passkeys = settings.passkeyRpConfig;
+    }
+    return auth;
+}
+/**
+ * Translate the [auth] block of app.toml into app-settings fields (push
+ * direction).
+ *
+ * Only keys actually present in the TOML are forwarded — an omitted key is left
+ * untouched so it never overwrites server state (e.g. flipping a previously-true
+ * flag to false). An explicit value, including `false`, is forwarded as-is.
+ * `appleAudiences = []` is forwarded too; the server normalizes [] -> null
+ * ("no audiences"). Keys outside RECOGNIZED_AUTH_KEYS produce a warning rather
+ * than a hard error, so a typo or a future key doesn't silently drop.
+ */
+export function parseAppAuthSettings(auth) {
+    const settings = {};
+    const warnings = [];
+    for (const key of AUTH_BOOLEAN_KEYS) {
+        if (key in auth)
+            settings[key] = auth[key];
+    }
+    if ("appleAudiences" in auth) {
+        settings.appleAudiences = auth.appleAudiences;
+    }
+    if ("passkeys" in auth) {
+        settings.passkeyRpConfig = auth.passkeys;
+    }
+    for (const key of Object.keys(auth)) {
+        if (!RECOGNIZED_AUTH_KEYS.has(key)) {
+            warnings.push(`Unrecognized [auth] key "${key}" in app.toml — ignored. ` +
+                `Recognized keys: ${[...RECOGNIZED_AUTH_KEYS].join(", ")}.`);
+        }
+    }
+    return { settings, warnings };
+}
 // TOML serialization helpers
 function serializeAppSettings(settings) {
     const data = {
@@ -208,15 +292,8 @@ function serializeAppSettings(settings) {
             waitlistEnabled: settings.waitlistEnabled,
             baseUrl: settings.baseUrl,
         },
-        auth: {
-            googleOAuthEnabled: settings.googleOAuthEnabled,
-            passkeyEnabled: settings.passkeyEnabled,
-            magicLinkEnabled: settings.magicLinkEnabled,
-        },
+        auth: serializeAuthBlock(settings),
     };
-    if (settings.passkeyRpConfig) {
-        data.auth.passkeys = settings.passkeyRpConfig;
-    }
     if (settings.corsMode === "custom") {
         data.cors = {
             mode: settings.corsMode,
@@ -256,6 +333,15 @@ function serializeWebhook(webhook) {
             secretGracePeriodMs: webhook.secretGracePeriodMs,
         },
     };
+    // Re-emit a `{{secrets.KEY}}` reference so a pull→push round-trip is lossless
+    // (#1235). The server only returns `signingSecret` when it is such a
+    // reference (a real secret is returned masked, never in plaintext); guard on
+    // the template shape here too so a masked or raw value can never be written
+    // to TOML.
+    if (typeof webhook.signingSecret === "string" &&
+        /\{\{secrets\.[A-Z][A-Z0-9_]{0,63}\}\}/.test(webhook.signingSecret)) {
+        data.webhook.signingSecret = webhook.signingSecret;
+    }
     // Parse JSON fields if they're strings
     if (webhook.allowedIpCidrs) {
         try {
@@ -371,7 +457,7 @@ function serializePrompt(prompt) {
     };
     return TOML.stringify(data);
 }
-function serializeWorkflow(workflow, draft, configs) {
+export function serializeWorkflow(workflow, draft, configs) {
     // Find the active config or use the first one
     const activeConfigId = workflow.activeConfigId;
     const activeConfig = configs?.find((c) => c.configId === activeConfigId) || configs?.[0];
@@ -391,6 +477,15 @@ function serializeWorkflow(workflow, draft, configs) {
             // #1081 — workflow principal mode. Emit only when set so a fresh
             // pull → push round-trips it without writing a noisy `runAs = ""`.
             runAs: workflow.runAs || undefined,
+            // #1233 — opt-in sensitive capability grants. The GET response always
+            // returns an array (empty when unset); emit only when non-empty so a
+            // fresh pull → push round-trips a real value without writing a noisy
+            // `capabilities = []`. This is the load-bearing fix: before this, pull
+            // dropped capabilities entirely and a pull → push cycle silently cleared
+            // them on the server.
+            capabilities: Array.isArray(workflow.capabilities) && workflow.capabilities.length > 0
+                ? workflow.capabilities
+                : undefined,
             perUserMaxRunning: workflow.perUserMaxRunning,
             perUserMaxQueued: workflow.perUserMaxQueued,
             dequeueOrder: workflow.dequeueOrder,
@@ -413,6 +508,10 @@ function serializeWorkflow(workflow, draft, configs) {
             status: config.status,
             isActive: config.configId === activeConfigId,
         })) || [],
+        // #1304 (P-C): the declared-access manifest — top-level `[metadata]` /
+        // `secrets`, merged the same way the collection/database type configs do so
+        // a workflow's `md`/`secrets` declarations round-trip through pull → push.
+        ...serializeDeclaredAccessManifest(workflow.metadataManifest),
     };
     return TOML.stringify(data);
 }
@@ -486,6 +585,9 @@ function serializeCollectionTypeConfig(config, ruleSetIdToName) {
             collectionType: config.collectionType,
             ruleSetName: ruleSetName,
         },
+        // Declared-access manifest (issue #1304, P-C): merge the top-level
+        // `[metadata]` + `secrets` fragments so a pull→push→pull cycle round-trips.
+        ...serializeDeclaredAccessManifest(config.metadataManifest),
     };
     return TOML.stringify(data);
 }
@@ -530,6 +632,17 @@ export function parseDatabaseTypeToml(tomlData) {
     if (tomlData.triggers) {
         typeConfig.triggers = tomlData.triggers;
     }
+    // Declared-access manifest (issue #1304, P-C): the top-level `[metadata]` +
+    // `secrets` blocks. Validated locally before push; the server re-validates
+    // (graph/schema) at persist time.
+    const manifest = parseDeclaredAccessManifestToml(tomlData);
+    if (manifest) {
+        const manifestError = validateDeclaredAccessManifest(manifest);
+        if (manifestError) {
+            throw new Error(`Invalid metadata manifest in database type "${typeSection.databaseType || ""}": ${manifestError}`);
+        }
+        typeConfig.metadataManifest = manifest;
+    }
     // Issue #666: extract the `[models.*]` subtree (if present) and re-serialize
     // it to a TOML string for the server's `schema` field.
     //
@@ -598,6 +711,17 @@ export function parseCollectionTypeConfigToml(tomlData) {
     else if (section.ruleSetId && section.ruleSetId !== "") {
         result.ruleSetId = section.ruleSetId;
     }
+    // Declared-access manifest (issue #1304, P-C): the top-level `[metadata]` +
+    // `secrets` blocks. Validated locally before push; the server re-validates
+    // (graph/schema) at persist time.
+    const manifest = parseDeclaredAccessManifestToml(tomlData);
+    if (manifest) {
+        const manifestError = validateDeclaredAccessManifest(manifest);
+        if (manifestError) {
+            throw new Error(`Invalid metadata manifest in collection type config "${section.collectionType || ""}": ${manifestError}`);
+        }
+        result.metadataManifest = manifest;
+    }
     return result;
 }
 // Parsing helpers
@@ -681,7 +805,14 @@ export function resolveSlugCollisions(slug, usedSlugs) {
     return resolved;
 }
 function getTestsDir(configDir, blockType, blockKey) {
-    const typeDir = blockType === "prompt" ? "prompts" : "workflows";
+    // Scripts (blockType "script") live under `transforms/` on disk (their
+    // bodies are `transforms/<name>.rhai`), so their test cases sit alongside at
+    // `transforms/<name>.tests/`. Prompts and workflows keep their own dirs.
+    const typeDir = blockType === "prompt"
+        ? "prompts"
+        : blockType === "script"
+            ? "transforms"
+            : "workflows";
     return join(configDir, typeDir, `${blockKey}.tests`);
 }
 export function serializeTestCase(testCase, lookupMaps) {
@@ -963,8 +1094,10 @@ async function pushTestCasesForBlock(client, appId, blockType, blockId, blockKey
                 const configMapKey = `${blockKey}#${testPayload._configName}`;
                 const configMap = blockType === "prompt"
                     ? resolutionMaps.promptConfigNameToId
-                    : resolutionMaps.workflowConfigNameToId;
-                const resolvedId = configMap.get(configMapKey);
+                    : blockType === "script"
+                        ? resolutionMaps.scriptConfigNameToId
+                        : resolutionMaps.workflowConfigNameToId;
+                const resolvedId = configMap?.get(configMapKey);
                 if (resolvedId) {
                     testPayload.configId = resolvedId;
                 }
@@ -1166,6 +1299,7 @@ Directory Structure:
     rule-sets/*.toml                # Access rule sets
     group-type-configs/*.toml       # Group type configs
     collection-type-configs/*.toml  # Collection type configs
+    metadata-category-configs/*.toml # Resource-metadata category configs
     email-templates/*.toml          # Email template overrides
 `);
     // Init
@@ -1196,6 +1330,7 @@ Directory Structure:
         ensureDir(join(configDir, "rule-sets"));
         ensureDir(join(configDir, "group-type-configs"));
         ensureDir(join(configDir, "collection-type-configs"));
+        ensureDir(join(configDir, "metadata-category-configs"));
         ensureDir(join(configDir, "email-templates"));
         const state = {
             appId: resolvedAppId,
@@ -1267,11 +1402,12 @@ Directory Structure:
                 return;
             }
             // Fetch database config resources
-            const [databaseTypeConfigsResult, ruleSetsResult, groupTypeConfigsResult, collectionTypeConfigsResult,] = await Promise.all([
+            const [databaseTypeConfigsResult, ruleSetsResult, groupTypeConfigsResult, collectionTypeConfigsResult, metadataCategoryConfigsResult,] = await Promise.all([
                 client.listDatabaseTypeConfigs(resolvedAppId).catch(() => []),
                 client.listRuleSets(resolvedAppId).catch(() => []),
                 client.listGroupTypeConfigs(resolvedAppId).catch(() => []),
                 client.listCollectionTypeConfigs(resolvedAppId).catch(() => []),
+                client.listMetadataCategoryConfigs(resolvedAppId).catch(() => []),
             ]);
             // Fetch operations + subscriptions for each database type. Issue #803:
             // subscriptions are pulled symmetrically with operations so a
@@ -1330,6 +1466,7 @@ Directory Structure:
             ensureDir(join(configDir, "rule-sets"));
             ensureDir(join(configDir, "group-type-configs"));
             ensureDir(join(configDir, "collection-type-configs"));
+            ensureDir(join(configDir, "metadata-category-configs"));
             ensureDir(join(configDir, "email-templates"));
             // Write app settings
             if (settings) {
@@ -1468,6 +1605,23 @@ Directory Structure:
                     }
                 }
             }
+            // Include script config names so a pinned script test case
+            // round-trips its `configName` reference (the same way prompt/workflow
+            // configs above do). One extra `configs` fetch per pulled script.
+            for (const [name, entity] of Object.entries(scriptEntities)) {
+                try {
+                    const { items: scriptConfigs } = await client.listScriptConfigs(resolvedAppId, entity.id);
+                    for (const config of scriptConfigs) {
+                        configIdToName.set(config.configId, config.configName);
+                    }
+                }
+                catch {
+                    // Non-fatal: a script test case pinned to a config just serializes
+                    // without a resolvable name (falls back to active on push). The
+                    // header/body still pulled fine — `name` retained for clarity.
+                    void name;
+                }
+            }
             const testCaseLookupMaps = { configIdToName, promptIdToKey };
             // Write email templates (use detailed emailTemplates, not summaries)
             const emailTemplateEntities = {};
@@ -1510,6 +1664,15 @@ Directory Structure:
                 }
                 totalTestCases += count;
             }
+            // Pull test cases for scripts (transforms). Script blocks use
+            // blockType "script"; their tests land under transforms/<name>.tests/.
+            for (const [name, entity] of Object.entries(scriptEntities)) {
+                const count = await pullTestCasesForBlock(client, resolvedAppId, "script", entity.id, name, configDir, testCaseEntities, testCaseLookupMaps);
+                if (count > 0) {
+                    info(`  Wrote ${count} test case(s) for script: ${name}`);
+                }
+                totalTestCases += count;
+            }
             // Build ruleSetId → name map for database types and group type configs
             const ruleSets = Array.isArray(ruleSetsResult) ? ruleSetsResult : [];
             const ruleSetIdToName = new Map();
@@ -1605,6 +1768,23 @@ Directory Structure:
                 };
                 info(`  Wrote collection-type-configs/${filename}`);
             }
+            // Write metadata category configs (issue #1304, P-B). One file per
+            // `{resourceType, category}`; the entity key is the `resourceType#category`
+            // pair so push can match it back.
+            const metadataCategoryConfigEntities = {};
+            const metadataCategoryConfigs = Array.isArray(metadataCategoryConfigsResult)
+                ? metadataCategoryConfigsResult
+                : [];
+            for (const config of metadataCategoryConfigs) {
+                const filename = `${config.resourceType}.${config.category}.toml`;
+                const filePath = join(configDir, "metadata-category-configs", filename);
+                writeFileSync(filePath, serializeMetadataCategoryConfig(config));
+                metadataCategoryConfigEntities[`${config.resourceType}#${config.category}`] = {
+                    modifiedAt: config.modifiedAt || new Date().toISOString(),
+                    contentHash: computeFileHash(filePath),
+                };
+                info(`  Wrote metadata-category-configs/${filename}`);
+            }
             // Save sync state
             const state = {
                 appId: resolvedAppId,
@@ -1627,6 +1807,9 @@ Directory Structure:
                     collectionTypeConfigs: Object.keys(collectionTypeConfigEntities).length > 0
                         ? collectionTypeConfigEntities
                         : undefined,
+                    metadataCategoryConfigs: Object.keys(metadataCategoryConfigEntities).length > 0
+                        ? metadataCategoryConfigEntities
+                        : undefined,
                 },
             };
             saveSyncState(configDir, state);
@@ -1645,6 +1828,7 @@ Directory Structure:
             keyValue("Rule Sets", ruleSets.length);
             keyValue("Group Type Configs", groupTypeConfigs.length);
             keyValue("Collection Type Configs", collectionTypeConfigs.length);
+            keyValue("Metadata Category Configs", metadataCategoryConfigs.length);
         }
         catch (err) {
             error(err.message);
@@ -1920,11 +2104,10 @@ Directory Structure:
                         }
                     }
                     if (tomlData.auth) {
-                        settings.googleOAuthEnabled = tomlData.auth.googleOAuthEnabled;
-                        settings.passkeyEnabled = tomlData.auth.passkeyEnabled;
-                        settings.magicLinkEnabled = tomlData.auth.magicLinkEnabled;
-                        if (tomlData.auth.passkeys) {
-                            settings.passkeyRpConfig = tomlData.auth.passkeys;
+                        const { settings: authSettings, warnings: authWarnings } = parseAppAuthSettings(tomlData.auth);
+                        Object.assign(settings, authSettings);
+                        for (const w of authWarnings) {
+                            warn(`  ${w}`);
                         }
                     }
                     if (tomlData.cors) {
@@ -2142,6 +2325,14 @@ Directory Structure:
                         deduplicationWindowMs: webhook.deduplicationWindowMs,
                         secretGracePeriodMs: webhook.secretGracePeriodMs,
                     };
+                    // Forward the declared signing secret so a `{{secrets.KEY}}`
+                    // reference reaches the server intact (#1235). Without this the
+                    // value declared in TOML is silently dropped and the server
+                    // rejects a verified webhook with "signingSecret is required".
+                    // Mirrors how integrations forward requestConfig with refs intact.
+                    if (webhook.signingSecret !== undefined) {
+                        payload.signingSecret = webhook.signingSecret;
+                    }
                     // Handle JSON fields
                     if (tomlData.allowedIps?.cidrs) {
                         payload.allowedIpCidrs = JSON.stringify(tomlData.allowedIps.cidrs);
@@ -2774,6 +2965,19 @@ Directory Structure:
                     const workflow = tomlData.workflow || {};
                     const key = workflow.key || basename(file, ".toml");
                     const steps = tomlData.steps || [];
+                    // #1304 (P-C): the declared-access manifest lives at top-level
+                    // `[metadata]` / `secrets` (same shape the database/collection type
+                    // configs use). Parse + surface-validate it, then carry it on the
+                    // `workflow` payload object so it flows through both the create call
+                    // and the shared `applyWorkflowBody` update. A null manifest (no
+                    // `[metadata]`) clears it on the server so pull → push round-trips a
+                    // drop; the deep graph check runs server-side at persist.
+                    const workflowManifest = parseDeclaredAccessManifestToml(tomlData);
+                    const workflowManifestError = validateDeclaredAccessManifest(workflowManifest);
+                    if (workflowManifestError) {
+                        throw new Error(`${filePath}: ${workflowManifestError}`);
+                    }
+                    workflow.metadataManifest = workflowManifest;
                     const existingId = syncState?.entities?.workflows?.[key]?.id;
                     const existingActiveConfigId = syncState?.entities?.workflows?.[key]?.activeConfigId;
                     // Skip if file hasn't changed since last sync. Use the expanded
@@ -2805,80 +3009,17 @@ Directory Structure:
                     // out-of-manifest workflow).
                     const applyWorkflowUpdate = async (workflowId, opts) => {
                         const { expectedModifiedAt, activeConfigId } = opts;
-                        // 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, workflowId, {
-                            name: workflow.name,
-                            description: workflow.description,
-                            status: workflow.status,
-                            accessRule: workflow.accessRule !== undefined ? (workflow.accessRule || null) : undefined,
-                            // #1081 — workflow principal mode. Absent key → undefined
-                            // (server leaves it untouched); explicit value/empty is
-                            // forwarded so it round-trips.
-                            runAs: workflow.runAs !== undefined ? (workflow.runAs || null) : undefined,
-                            perUserMaxRunning: workflow.perUserMaxRunning,
-                            perUserMaxQueued: workflow.perUserMaxQueued,
-                            dequeueOrder: workflow.dequeueOrder,
-                            // 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);
-                        // 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 (activeConfigId) {
-                            await client.updateWorkflowConfig(resolvedAppId, workflowId, activeConfigId, {
-                                steps,
-                            });
-                        }
-                        else {
-                            // Fallback to draft update for legacy workflows
-                            await client.updateWorkflowDraft(resolvedAppId, workflowId, {
-                                steps,
-                                inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
-                            });
-                            updateSlotLabel = "draft (legacy)";
-                        }
-                        // 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, workflowId, { 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;
-                            }
-                        }
+                        // The ordering-sensitive core (metadata PATCH → config/draft
+                        // steps → deferred `syncCallable` PATCH, #807) lives in the
+                        // shared `applyWorkflowBody` helper so `workflows update
+                        // --from-file` runs it identically (#1249, Fork 4). The
+                        // sync-specific bookkeeping (the progress log, sync-state
+                        // `modifiedAt`/hash, and config name→ID map) stays here.
+                        const { latestModifiedAt, updateSlotLabel, fullWorkflow } = await applyWorkflowBody(client, resolvedAppId, workflowId, workflow, steps, {
+                            expectedModifiedAt,
+                            activeConfigId,
+                            force: options.force,
+                        });
                         info(`  Updated workflow: ${key} (${updateSlotLabel})`);
                         // Update sync state with new modifiedAt. Store the *expanded*
                         // content hash so future fragment-only edits are detected. The
@@ -2888,9 +3029,8 @@ Directory Structure:
                             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)
-                        const fullWorkflow = await client.getWorkflow(resolvedAppId, workflowId);
+                        // `applyWorkflowBody` already fetched the full workflow; reuse it
+                        // for the config name→ID mappings (the PATCH response omits configs).
                         if (fullWorkflow?.configs) {
                             for (const config of fullWorkflow.configs) {
                                 workflowConfigNameToId.set(`${key}#${config.configName}`, config.configId);
@@ -2949,6 +3089,9 @@ Directory Structure:
                                     // syncCallable=false); an explicit value is honored.
                                     requiresClientApply: workflow.requiresClientApply,
                                     syncCallable: workflow.syncCallable,
+                                    // #1304 (P-C): declared-access manifest (absent → undefined,
+                                    // server default null).
+                                    metadataManifest: workflow.metadataManifest ?? undefined,
                                 });
                                 info(`  Created workflow: ${key}`);
                                 // Add new entity to sync state (including activeConfigId)
@@ -3214,6 +3357,14 @@ Directory Structure:
                         if ("timestamps" in typeConfig) {
                             u.timestamps = typeConfig.timestamps || null;
                         }
+                        // Issue #1304 (P-C): declared-access manifest. `parseDatabaseTypeToml`
+                        // only sets `metadataManifest` when the TOML declares a `[metadata]`
+                        // / `secrets` block, so this forwards a set/update; clearing a
+                        // manifest by removing the block is a follow-on (mirrors the
+                        // schema-deletion tracking).
+                        if ("metadataManifest" in typeConfig) {
+                            u.metadataManifest = typeConfig.metadataManifest || null;
+                        }
                         const localHasSchema = typeof typeConfig.schema === "string" &&
                             typeConfig.schema.trim().length > 0;
                         if (localHasSchema) {
@@ -3583,7 +3734,8 @@ Directory Structure:
                                 "defaultAccess" in typeConfig ||
                                 "autoPopulatedFields" in typeConfig ||
                                 "timestamps" in typeConfig ||
-                                "schema" in typeConfig;
+                                "schema" in typeConfig ||
+                                "metadataManifest" in typeConfig;
                             if (wouldUpdate) {
                                 changes.push({ type: "database-type", action: "update", key: dbType });
                             }
@@ -3616,6 +3768,9 @@ Directory Structure:
                             // validating against the intended shape.
                             if (typeConfig.schema)
                                 createData.schema = typeConfig.schema;
+                            // Issue #1304 (P-C): declared-access manifest.
+                            if (typeConfig.metadataManifest)
+                                createData.metadataManifest = typeConfig.metadataManifest;
                             try {
                                 const created = await client.createDatabaseTypeConfig(resolvedAppId, createData);
                                 info(`  Created database type: ${dbType}`);
@@ -4149,6 +4304,7 @@ Directory Structure:
                             try {
                                 const updated = await client.updateCollectionTypeConfig(resolvedAppId, collectionType, {
                                     ruleSetId: configData.ruleSetId ?? null,
+                                    metadataManifest: configData.metadataManifest ?? null,
                                 }, expectedModifiedAt);
                                 info(`  Updated collection type config: ${collectionType}`);
                                 if (syncState?.entities?.collectionTypeConfigs?.[collectionType] && updated?.modifiedAt) {
@@ -4179,6 +4335,9 @@ Directory Structure:
                                 const created = await client.createCollectionTypeConfig(resolvedAppId, {
                                     collectionType,
                                     ruleSetId: configData.ruleSetId || undefined,
+                                    ...(configData.metadataManifest
+                                        ? { metadataManifest: configData.metadataManifest }
+                                        : {}),
                                 });
                                 info(`  Created collection type config: ${collectionType}`);
                                 if (syncState) {
@@ -4198,6 +4357,66 @@ Directory Structure:
                     }
                 }
             }
+            // Process metadata category configs (issue #1304, P-B). Idempotent
+            // upsert via the path-addressed PUT route — no create/update split.
+            const metadataCategoryConfigsDir = join(configDir, "metadata-category-configs");
+            if (existsSync(metadataCategoryConfigsDir)) {
+                const files = readdirSync(metadataCategoryConfigsDir).filter((f) => f.endsWith(".toml"));
+                for (const file of files) {
+                    const filePath = join(metadataCategoryConfigsDir, file);
+                    const tomlData = parseTomlFile(filePath);
+                    const configData = parseMetadataCategoryToml(tomlData);
+                    // Fall back to the filename (`resourceType.category.toml`) if the
+                    // section omits the identity fields.
+                    if (!configData.resourceType || !configData.category) {
+                        const base = basename(file, ".toml");
+                        const dot = base.indexOf(".");
+                        if (dot > 0) {
+                            configData.resourceType = configData.resourceType || base.slice(0, dot);
+                            configData.category = configData.category || base.slice(dot + 1);
+                        }
+                    }
+                    const validationError = validateMetadataCategoryConfig(configData);
+                    if (validationError) {
+                        throw new Error(`Invalid metadata category config in ${file}: ${validationError}`);
+                    }
+                    const entityKey = `${configData.resourceType}#${configData.category}`;
+                    const existingEntry = syncState?.entities?.metadataCategoryConfigs?.[entityKey];
+                    // Skip if the file hasn't changed since last sync.
+                    if (!options.force && existingEntry && !shouldPushFile(filePath, existingEntry.contentHash)) {
+                        skippedCount++;
+                        continue;
+                    }
+                    changes.push({
+                        type: "metadata-category-config",
+                        action: existingEntry ? "update" : "create",
+                        key: entityKey,
+                    });
+                    if (!options.dryRun) {
+                        try {
+                            const saved = await client.upsertMetadataCategoryConfig(resolvedAppId, configData.resourceType, configData.category, {
+                                schema: configData.schema,
+                                readRule: configData.readRule,
+                                writeRule: configData.writeRule,
+                                description: configData.description,
+                            });
+                            info(`  Upserted metadata category config: ${entityKey}`);
+                            if (syncState) {
+                                if (!syncState.entities.metadataCategoryConfigs) {
+                                    syncState.entities.metadataCategoryConfigs = {};
+                                }
+                                syncState.entities.metadataCategoryConfigs[entityKey] = {
+                                    modifiedAt: saved?.modifiedAt || new Date().toISOString(),
+                                    contentHash: computeFileHash(filePath),
+                                };
+                            }
+                        }
+                        catch (err) {
+                            throw wrapEntityError(err, existingEntry ? "update" : "create", "metadata category config", entityKey);
+                        }
+                    }
+                }
+            }
             // Process email templates
             const emailTemplatesDir = join(configDir, "email-templates");
             if (existsSync(emailTemplatesDir)) {
@@ -4234,11 +4453,13 @@ Directory Structure:
                     }
                 }
             }
-            // Push test cases for prompts and workflows
+            // Push test cases for prompts, workflows, and scripts
+            const scriptConfigNameToId = new Map(); // "scriptName#configName" → configId
             const pushMaps = {
                 promptKeyToId,
                 promptConfigNameToId,
                 workflowConfigNameToId,
+                scriptConfigNameToId,
             };
             const promptsDir2 = join(configDir, "prompts");
             if (existsSync(promptsDir2)) {
@@ -4262,6 +4483,33 @@ Directory Structure:
                     }
                 }
             }
+            // Push test cases for scripts (transforms). Each script's tests live at
+            // transforms/<name>.tests/; the scriptId was recorded in
+            // entities.scripts[name].id when the script body was pushed above.
+            const transformsDir2 = join(configDir, "transforms");
+            if (existsSync(transformsDir2)) {
+                for (const file of readdirSync(transformsDir2).filter((f) => f.endsWith(".rhai"))) {
+                    const scriptName = basename(file, ".rhai");
+                    const blockId = syncState?.entities?.scripts?.[scriptName]?.id;
+                    if (!blockId)
+                        continue;
+                    const scriptTestsDir = join(transformsDir2, `${scriptName}.tests`);
+                    if (!existsSync(scriptTestsDir))
+                        continue;
+                    // Populate scriptConfigNameToId for this script so a test case that
+                    // pins a config by name resolves to a live configId.
+                    try {
+                        const { items: scriptConfigs } = await client.listScriptConfigs(resolvedAppId, blockId);
+                        for (const config of scriptConfigs) {
+                            scriptConfigNameToId.set(`${scriptName}#${config.configName}`, config.configId);
+                        }
+                    }
+                    catch {
+                        // Non-fatal — unpinned (active-version) test cases still push.
+                    }
+                    skippedCount += await pushTestCasesForBlock(client, resolvedAppId, "script", blockId, scriptName, configDir, syncState, options.dryRun, changes, pushMaps, { force: options.force });
+                }
+            }
             divider();
             // Issue #813: a gate failure surfaced by the validate-first pass (which
             // also runs in dry-run mode via the server's dry-run gate endpoints).
@@ -4938,6 +5186,63 @@ Directory Structure:
             success(`Rewrote ${migratedCount} TOML file(s) to native form.`);
         }
     });
+    // migrate-v2 — convert a legacy sync directory into the unified block
+    // layout `blocks/<type>/<key>/block.toml` (issue #1183, Phase 3). Purely
+    // local: it reads already-pulled legacy files and writes the v2 tree. The
+    // legacy files are left in place (legacy stays the default until v2 is
+    // proven), so re-running push/pull is unaffected.
+    sync
+        .command("migrate-v2")
+        .description("Convert legacy per-type sync files (prompts/, integrations/, workflows/, transforms/) into the v2 blocks/<type>/<key>/block.toml layout")
+        .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")
+        .option("--force", "Overwrite existing block.toml files instead of skipping them")
+        .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-v2 is a purely local rewrite (like migrate-toml).
+        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 before = detectLayout(configDir);
+        if (!before.legacy) {
+            info("No legacy block files found (prompts/, integrations/, workflows/, transforms/); nothing to migrate.");
+            return;
+        }
+        const result = migrateLegacyToV2(configDir, {
+            dryRun: options.dryRun,
+            force: options.force,
+        });
+        for (const b of result.blocks) {
+            const suffix = b.testsCopied > 0 ? ` (+${b.testsCopied} test case(s))` : "";
+            if (options.dryRun) {
+                info(`Would write blocks/${b.type === "script" ? "scripts" : b.type + "s"}/${b.key}/block.toml${suffix}`);
+            }
+            else {
+                info(`Wrote blocks/${b.type === "script" ? "scripts" : b.type + "s"}/${b.key}/block.toml${suffix}`);
+            }
+        }
+        for (const s of result.skipped) {
+            warn(`Skipped ${s.type}/${s.key}: ${s.reason}`);
+        }
+        divider();
+        keyValue("Migrated", result.blocks.length);
+        keyValue("Skipped", result.skipped.length);
+        if (options.dryRun) {
+            info("Dry-run only — no files were modified.");
+        }
+        else if (result.blocks.length > 0) {
+            success(`Converted ${result.blocks.length} block(s) to the v2 layout. Legacy files were left in place.`);
+        }
+    });
     // Revert — restore a pre-pull snapshot (issue #578, Phase 1).
     sync
         .command("revert")