primitive-admin 1.0.61 → 1.0.62

package/dist/src/lib/workflow-include-preserve.js

@@ -0,0 +1,286 @@
+/**
+ * Keep `[[include]]` fragment structure alive across `config pull` (issue #2416).
+ *
+ * Fragments are a CLI-only authoring form: `expandWorkflowTomlData()` splices
+ * the referenced fragments into a flat `[[steps]]` list and the server only
+ * ever stores that expansion (see `workflow-fragments.ts`). `config pull`
+ * serializes the server's flat steps straight back to disk, so before this
+ * module a pull unconditionally overwrote a fragment-authored file with its
+ * own expansion — the `[[include]]` blocks were gone and had to be rebuilt by
+ * hand, even when `config diff` reported the file as synced.
+ *
+ * `reconcileWorkflowIncludes()` decides what pull should write for one
+ * workflow file. It only ever engages for a local file that actually carries
+ * an `include` key; everything else takes the unchanged "write what the server
+ * gave us" path.
+ *
+ *   - **skip** — the local file expands to exactly what the server is running.
+ *     There is nothing to apply, so leave the fragment source (and its
+ *     comments and formatting) untouched. One thing still has to be applied to
+ *     an otherwise-unchanged file: a retired inline `[[configs]]` list (#2733).
+ *     Pull rewrites every other workflow file off it, and push rejects a file
+ *     that still carries one, so a plain skip left the fragment source in a
+ *     shape push refuses — pull → push of an untouched tree failed. Such a
+ *     file takes the write-merged path with only the list removed.
+ *   - **write-merged** — the server drifted, but its step list still *starts*
+ *     with exactly the steps the local includes expand to. The drift is
+ *     therefore expressible in fragment form: re-emit the file with the
+ *     original `[[include]]` blocks and put the remaining server steps in the
+ *     workflow's own `[[steps]]` list. Re-expanding that file reproduces the
+ *     server's step list in order, so the next `config diff` reads as synced.
+ *   - **write-expanded** — the fragment-derived prefix no longer matches what
+ *     the server is running (a fragment's steps were edited or removed
+ *     server-side), so no fragment-preserving file could reproduce it. Fall
+ *     back to the historical behavior — write the fully expanded form — and
+ *     say why, so the operator knows the fragment source was replaced rather
+ *     than silently losing it.
+ *
+ * The order rule comes from the expander: it emits every fragment's steps
+ * first (in `include` order) and then the workflow's own `[[steps]]`. So a
+ * fragment-preserving file can only represent a server step list whose leading
+ * steps are exactly the fragment expansion. Server steps inserted *between*
+ * fragment steps are not representable and take the write-expanded path.
+ */
+import { parseConfigToml, stringifyConfigToml } from "./config-toml.js";
+import { expandWorkflowTomlData } from "./workflow-fragments.js";
+import { canonicalJsonStringify } from "./canonical-json.js";
+export function reconcileWorkflowIncludes(options) {
+    const { workflowKey, localPath, localContent, remoteToml, hashParsedToml } = options;
+    const label = `workflows/${workflowKey}.toml`;
+    if (localContent === undefined) {
+        return { action: "write-expanded" };
+    }
+    let localParsed;
+    try {
+        localParsed = parseConfigToml(localContent);
+    }
+    catch {
+        // An unparseable local file carries no structure worth preserving — pull
+        // replaces it, exactly as it did before.
+        return { action: "write-expanded" };
+    }
+    if (localParsed === null ||
+        typeof localParsed !== "object" ||
+        !("include" in localParsed)) {
+        return { action: "write-expanded" };
+    }
+    let expandedLocal;
+    try {
+        expandedLocal = expandWorkflowTomlData(localParsed, localPath);
+    }
+    catch (err) {
+        return {
+            action: "write-expanded",
+            message: `${label}: could not expand its [[include]] fragments ` +
+                `(${err?.message ?? err}); wrote the fully expanded form from the server.`,
+        };
+    }
+    const remoteParsed = parseConfigToml(remoteToml);
+    // Nothing to apply: the fragment source already describes what's running —
+    // except for a retired inline `[[configs]]` list, which pull has to take out
+    // on its way past (#2733).
+    if (hashParsedToml(expandedLocal) === hashParsedToml(remoteParsed)) {
+        if (hasRetiredInlineConfigs(localParsed)) {
+            return {
+                action: "write-merged",
+                content: withoutRetiredInlineConfigs({
+                    localContent,
+                    localParsed,
+                    localPath,
+                    remoteHash: hashParsedToml(remoteParsed),
+                    hashParsedToml,
+                }),
+                message: `${label}: removed the retired [[configs]] list (#2645) and kept ` +
+                    `the local [[include]] fragment source. Named configurations are ` +
+                    `authored one per file at workflows/${workflowKey}.configs/<name>.toml.`,
+            };
+        }
+        return {
+            action: "skip",
+            message: `${label}: unchanged — kept the local [[include]] fragment source.`,
+        };
+    }
+    const ownSteps = Array.isArray(localParsed.steps) ? localParsed.steps : [];
+    const expandedSteps = Array.isArray(expandedLocal.steps)
+        ? expandedLocal.steps
+        : [];
+    const remoteSteps = Array.isArray(remoteParsed.steps)
+        ? remoteParsed.steps
+        : [];
+    const fragmentCount = expandedSteps.length - ownSteps.length;
+    if (fragmentCount < 0) {
+        // Defensive: the expander always emits fragment steps plus own steps.
+        return { action: "write-expanded" };
+    }
+    const mismatch = findFragmentPrefixMismatch(expandedSteps.slice(0, fragmentCount), remoteSteps);
+    if (mismatch) {
+        return {
+            action: "write-expanded",
+            message: `${label}: the running workflow no longer starts with the steps its ` +
+                `[[include]] fragments expand to (${mismatch}), so the fragment ` +
+                `structure can't be preserved. Wrote the fully expanded form — ` +
+                `re-author the includes by hand if you want them back.`,
+        };
+    }
+    const remainingSteps = remoteSteps.slice(fragmentCount);
+    // Rebuild the file from the server's content with the local include blocks
+    // spliced back in. `workflow` first, then `include`, then the steps the
+    // fragments don't cover, then everything else the server serialized
+    // (`configs`, `[expr.cel]`, the declared-access manifest, ...).
+    const data = {};
+    if ("workflow" in remoteParsed) {
+        data.workflow = remoteParsed.workflow;
+    }
+    data.include = localParsed.include;
+    if (remainingSteps.length > 0) {
+        data.steps = remainingSteps;
+    }
+    for (const [key, value] of Object.entries(remoteParsed)) {
+        if (!(key in data) && key !== "steps") {
+            data[key] = value;
+        }
+    }
+    return {
+        action: "write-merged",
+        content: stringifyConfigToml(data),
+        message: `${label}: kept ${fragmentCount} step(s) from [[include]] fragments; ` +
+            `wrote ${remainingSteps.length} server step(s) the fragments don't cover.`,
+    };
+}
+/**
+ * Whether the local file carries the inline `[[configs]]` list #2645 retired.
+ * Matches the push validator's rule exactly (`validateRetiredInlineConfigs` in
+ * `workflow-toml-validator.ts`): a non-empty array at the document root. An
+ * empty one is not rejected by push, so pull has no reason to touch the file
+ * over it.
+ */
+function hasRetiredInlineConfigs(localParsed) {
+    return Array.isArray(localParsed.configs) && localParsed.configs.length > 0;
+}
+/** A `[[configs]]` header line, the only form a retired list can be authored in as a table array. */
+const RETIRED_CONFIGS_HEADER = /^\[\[\s*configs\s*\]\]\s*(#.*)?$/;
+/** `[configs.x]` / `[[configs.x]]` — a subtable of the entry being removed. */
+const RETIRED_CONFIGS_SUBTABLE = /^\[\[?\s*configs\s*\./;
+/**
+ * The local file with its retired `[[configs]]` blocks taken out, preserving
+ * every other byte — comments, key order and formatting included. That matters
+ * here more than anywhere else in this module: the file is otherwise in sync,
+ * so re-emitting it would reformat an operator's hand-authored source for a
+ * change that only deletes a block nothing reads.
+ *
+ * Returns `undefined` when the list is not authored as `[[configs]]` blocks
+ * (an inline `configs = [ … ]` array, say), which the caller handles by
+ * re-emitting the parsed document instead.
+ */
+function stripRetiredInlineConfigsText(content) {
+    const kept = [];
+    /**
+     * Blank and comment lines seen since the last line that definitely belongs to
+     * the block being removed. A comment sitting between the retired list and the
+     * next table almost always documents *that* table, so it is handed back when
+     * the table arrives instead of being deleted with the block; trivia followed
+     * by another config line documented the removed entry and is dropped.
+     */
+    let trivia = [];
+    let removing = false;
+    let removedAny = false;
+    /** Give the pending trivia back, from its first comment line onwards. */
+    const keepTrivia = () => {
+        const firstComment = trivia.findIndex((line) => line.trim().startsWith("#"));
+        // Blank-only trivia is just the separator the removed block left behind.
+        if (firstComment >= 0)
+            kept.push(...trivia.slice(firstComment));
+        trivia = [];
+    };
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (RETIRED_CONFIGS_HEADER.test(trimmed)) {
+            trivia = [];
+            removing = true;
+            removedAny = true;
+            continue;
+        }
+        if (removing) {
+            // The block runs to the next top-level table header; a `configs.*`
+            // subtable belongs to the entry being removed and goes with it.
+            if (RETIRED_CONFIGS_SUBTABLE.test(trimmed)) {
+                trivia = [];
+                continue;
+            }
+            if (!trimmed.startsWith("[")) {
+                if (trimmed === "" || trimmed.startsWith("#"))
+                    trivia.push(line);
+                else
+                    trivia = [];
+                continue;
+            }
+            keepTrivia();
+            removing = false;
+        }
+        kept.push(line);
+    }
+    if (removing)
+        keepTrivia();
+    if (!removedAny)
+        return undefined;
+    const stripped = kept.join("\n");
+    // A block that ran to the end of the file takes the final newline with it.
+    return content.endsWith("\n") && !stripped.endsWith("\n")
+        ? `${stripped}\n`
+        : stripped;
+}
+/**
+ * What pull writes for an in-sync fragment source that still carries the
+ * retired list: the same file minus the `[[configs]]` blocks.
+ *
+ * The textual strip is verified before it is used — the result has to parse,
+ * carry no `configs` any more, and still expand to exactly the server's
+ * content hash. Anything else (an inline-array form, a shape the line scan
+ * misreads) falls back to re-emitting the parsed document without its
+ * `configs` key, which loses comments but is correct by construction.
+ */
+function withoutRetiredInlineConfigs(options) {
+    const { localContent, localParsed, localPath, remoteHash, hashParsedToml } = options;
+    const stripped = stripRetiredInlineConfigsText(localContent);
+    if (stripped !== undefined) {
+        try {
+            const reparsed = parseConfigToml(stripped);
+            if (!hasRetiredInlineConfigs(reparsed) &&
+                hashParsedToml(expandWorkflowTomlData(reparsed, localPath)) ===
+                    remoteHash) {
+                return stripped;
+            }
+        }
+        catch {
+            // Fall through to the re-emit below.
+        }
+    }
+    const { configs: _retired, ...rest } = localParsed;
+    return stringifyConfigToml(rest);
+}
+/**
+ * Returns a human-readable description of the first place the server's step
+ * list departs from the fragment-derived prefix, or `undefined` when the
+ * prefix matches exactly.
+ */
+function findFragmentPrefixMismatch(fragmentSteps, remoteSteps) {
+    if (remoteSteps.length < fragmentSteps.length) {
+        return `the server has ${remoteSteps.length} step(s), fewer than the ${fragmentSteps.length} the fragments produce`;
+    }
+    for (let i = 0; i < fragmentSteps.length; i++) {
+        if (canonicalJsonStringify(fragmentSteps[i]) !==
+            canonicalJsonStringify(remoteSteps[i])) {
+            const expectedId = describeStepId(fragmentSteps[i]);
+            const actualId = describeStepId(remoteSteps[i]);
+            return expectedId === actualId
+                ? `step ${i + 1} '${expectedId}' differs`
+                : `step ${i + 1} is '${actualId}' where the fragments produce '${expectedId}'`;
+        }
+    }
+    return undefined;
+}
+function describeStepId(step) {
+    const id = step?.id;
+    return typeof id === "string" && id.length > 0 ? id : "<no id>";
+}
+//# sourceMappingURL=workflow-include-preserve.js.map

package/dist/src/lib/workflow-include-preserve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-include-preserve.js","sourceRoot":"","sources":["../../../src/lib/workflow-include-preserve.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/workflow-payload.d.ts

@@ -3,8 +3,8 @@
  *
  * Background: the CLI built the create/update workflow payload in THREE
  * separate hand-enumerated literals — `workflows create --from-file`
- * (`cli/src/commands/workflows.ts`), the `sync push` create branch
- * (`cli/src/commands/sync.ts`), and the `sync push` update branch (the metadata
+ * (`cli/src/commands/workflows.ts`), the `config push` create branch
+ * (`cli/src/commands/sync.ts`), and the `config push` update branch (the metadata
  * PATCH in `cli/src/lib/workflow-apply.ts`). Because each site listed the
  * `[workflow]` fields by hand, they drifted apart: a field added to one path was
  * silently dropped by the others. `status` was the 4th field lost this way
@@ -27,18 +27,30 @@
  * Presence semantics, by mode:
  *   - create: optional strings coalesce absent/empty → `undefined` (omit; the
  *     server default applies). `capabilities` forwards the raw array (absent →
- *     omit). Schemas omit when absent.
- *   - update: optional strings distinguish explicit-clear from leave-unset via
- *     `x !== undefined ? (x || null) : undefined`. `status` forwards the bare
- *     value (matching the server's hasOwnProperty path). Schemas send `null`
- *     when absent so a cleared schema round-trips.
- *   - booleans (`requiresClientApply`, and `syncCallable` on create) are raw
- *     pass-through so an explicit `false` is preserved and only a truly-absent
- *     key drops.
- *   - `syncCallable` is OMITTED in `mode: "update"`: the server re-validates
- *     `syncCallable: true` against the CURRENTLY-active steps, so the update
- *     path must send it as a deferred second PATCH after the new steps are live
- *     (#807). `applyWorkflowBody` owns that second PATCH.
+ *     omit). Schemas omit when absent. Booleans are raw pass-through so an
+ *     explicit `false` is preserved and only a truly-absent key drops.
+ *   - update: ALWAYS-SEND (#2743). The workflow TOML fully describes the
+ *     workflow, so every update-mode field carries a definite value and
+ *     `undefined` never appears: a defaulted scalar (`status`, the queue
+ *     limits, `dequeueOrder`, `requiresClientApply`) sends its concrete model
+ *     default when the file omits it, and a nullable field (`description`,
+ *     `accessRule`, `runAs`, `capabilities`, the schemas, `lock`) sends `null`.
+ *     Deleting a line from the file therefore CONVERGES the server rather than
+ *     silently leaving the old value live (#1567's bug class). Optional strings
+ *     keep their `"" → null` coalescing, so an explicit clear and an omission
+ *     land on the same wire value.
+ *
+ *     Defaulted scalars deliberately travel as their default, not as `null`: a
+ *     server predating #2743 coerces a queue-limit `null` to `0`, while an
+ *     explicit default converges identically on both. The shared map lives in
+ *     `workflow-defaults.ts` (the diff normalizer reads the same copy).
+ *
+ *     Omit-preserve survives only as the SERVER's contract for other clients
+ *     (web-admin): the PATCH still leaves an absent key alone.
+ *   - `syncCallable` is OMITTED from the builder in `mode: "update"`: its
+ *     ordering relative to the steps write is `applyWorkflowBody`'s to decide
+ *     (#807 — enabling must validate against the NEW steps, so it is deferred
+ *     to a second PATCH; disabling rides the first PATCH). See that module.
  */
 export type WorkflowPayloadMode = "create" | "update";
 /**
@@ -68,13 +80,12 @@ export type WorkflowExpressionsPayload = {
  */
 export declare function parseWorkflowExpressionsToml(tomlData: any): WorkflowExpressionsPayload | undefined;
 /**
- * The `[workflow]`-derived keys the builder emits, per mode. Exported so the
- * drift-guard unit test can assert the key set hasn't silently lost a field —
- * the recurring bug class this builder closes. `update` omits `syncCallable`
- * (deferred second PATCH, #807); everything else is shared.
+ * The `[workflow]`-derived keys the builder emits, per mode — read from the
+ * vendored definition (#2644), not restated here. A field added to
+ * `src/config-surface/workflow.ts` is pushed with no edit to this file, which
+ * is what closes the recurring "CLI silently drops a new server field" bug.
  */
-export declare const WORKFLOW_PAYLOAD_FIELDS_CREATE: readonly ["name", "description", "status", "accessRule", "runAs", "capabilities", "perUserMaxRunning", "perUserMaxQueued", "perAppMaxRunning", "perAppMaxQueued", "queueTtlSeconds", "dequeueOrder", "requiresClientApply", "inputSchema", "outputSchema", "lock", "syncCallable"];
-export declare const WORKFLOW_PAYLOAD_FIELDS_UPDATE: ReadonlyArray<string>;
+export declare function workflowPayloadFields(mode: WorkflowPayloadMode): string[];
 /**
  * Build the workflow payload's `[workflow]`-derived fields from a parsed TOML
  * `[workflow]` table. `workflow` is `tomlData.workflow` (already merged with any

package/dist/src/lib/workflow-payload.js

@@ -3,8 +3,8 @@
  *
  * Background: the CLI built the create/update workflow payload in THREE
  * separate hand-enumerated literals — `workflows create --from-file`
- * (`cli/src/commands/workflows.ts`), the `sync push` create branch
- * (`cli/src/commands/sync.ts`), and the `sync push` update branch (the metadata
+ * (`cli/src/commands/workflows.ts`), the `config push` create branch
+ * (`cli/src/commands/sync.ts`), and the `config push` update branch (the metadata
  * PATCH in `cli/src/lib/workflow-apply.ts`). Because each site listed the
  * `[workflow]` fields by hand, they drifted apart: a field added to one path was
  * silently dropped by the others. `status` was the 4th field lost this way
@@ -27,19 +27,34 @@
  * Presence semantics, by mode:
  *   - create: optional strings coalesce absent/empty → `undefined` (omit; the
  *     server default applies). `capabilities` forwards the raw array (absent →
- *     omit). Schemas omit when absent.
- *   - update: optional strings distinguish explicit-clear from leave-unset via
- *     `x !== undefined ? (x || null) : undefined`. `status` forwards the bare
- *     value (matching the server's hasOwnProperty path). Schemas send `null`
- *     when absent so a cleared schema round-trips.
- *   - booleans (`requiresClientApply`, and `syncCallable` on create) are raw
- *     pass-through so an explicit `false` is preserved and only a truly-absent
- *     key drops.
- *   - `syncCallable` is OMITTED in `mode: "update"`: the server re-validates
- *     `syncCallable: true` against the CURRENTLY-active steps, so the update
- *     path must send it as a deferred second PATCH after the new steps are live
- *     (#807). `applyWorkflowBody` owns that second PATCH.
+ *     omit). Schemas omit when absent. Booleans are raw pass-through so an
+ *     explicit `false` is preserved and only a truly-absent key drops.
+ *   - update: ALWAYS-SEND (#2743). The workflow TOML fully describes the
+ *     workflow, so every update-mode field carries a definite value and
+ *     `undefined` never appears: a defaulted scalar (`status`, the queue
+ *     limits, `dequeueOrder`, `requiresClientApply`) sends its concrete model
+ *     default when the file omits it, and a nullable field (`description`,
+ *     `accessRule`, `runAs`, `capabilities`, the schemas, `lock`) sends `null`.
+ *     Deleting a line from the file therefore CONVERGES the server rather than
+ *     silently leaving the old value live (#1567's bug class). Optional strings
+ *     keep their `"" → null` coalescing, so an explicit clear and an omission
+ *     land on the same wire value.
+ *
+ *     Defaulted scalars deliberately travel as their default, not as `null`: a
+ *     server predating #2743 coerces a queue-limit `null` to `0`, while an
+ *     explicit default converges identically on both. The shared map lives in
+ *     `workflow-defaults.ts` (the diff normalizer reads the same copy).
+ *
+ *     Omit-preserve survives only as the SERVER's contract for other clients
+ *     (web-admin): the PATCH still leaves an absent key alone.
+ *   - `syncCallable` is OMITTED from the builder in `mode: "update"`: its
+ *     ordering relative to the steps write is `applyWorkflowBody`'s to decide
+ *     (#807 — enabling must validate against the NEW steps, so it is deferred
+ *     to a second PATCH; disabling rides the first PATCH). See that module.
  */
+import { writableFieldNames } from "./generated-config-surfaces.js";
+import { WORKFLOW_TABLE } from "./config-surface.js";
+import { WORKFLOW_MODEL_DEFAULTS } from "./workflow-defaults.js";
 /**
  * Parse a JSON schema field that TOML may present as a string OR (for an inline
  * table) as an already-parsed object. Kept here in `cli/src/lib` so the builder
@@ -75,31 +90,62 @@ export function parseWorkflowExpressionsToml(tomlData) {
     return Object.keys(out).length > 0 ? { cel: out } : undefined;
 }
 /**
- * The `[workflow]`-derived keys the builder emits, per mode. Exported so the
- * drift-guard unit test can assert the key set hasn't silently lost a field —
- * the recurring bug class this builder closes. `update` omits `syncCallable`
- * (deferred second PATCH, #807); everything else is shared.
+ * Fields the SERVER accepts on update but this BUILDER deliberately leaves to
+ * the caller. This is a sequencing invariant, not a statement about the server:
+ * `syncCallable: true` is re-validated against the CURRENTLY-active steps, so
+ * enabling it has to wait for a second PATCH once the new steps are live (#807
+ * — `applyWorkflowBody` owns the whole sequence, including the `false` case it
+ * puts in the FIRST PATCH). The definition correctly declares
+ * `writableOn: ["create", "update"]`; the exception lives here, where the
+ * ordering decision is.
  */
-export const WORKFLOW_PAYLOAD_FIELDS_CREATE = [
-    "name",
-    "description",
-    "status",
-    "accessRule",
-    "runAs",
-    "capabilities",
-    "perUserMaxRunning",
-    "perUserMaxQueued",
-    "perAppMaxRunning",
-    "perAppMaxQueued",
-    "queueTtlSeconds",
-    "dequeueOrder",
-    "requiresClientApply",
-    "inputSchema",
-    "outputSchema",
-    "lock",
-    "syncCallable",
-];
-export const WORKFLOW_PAYLOAD_FIELDS_UPDATE = WORKFLOW_PAYLOAD_FIELDS_CREATE.filter((f) => f !== "syncCallable");
+const CREATE_ONLY_ON_THE_WIRE = new Set(["syncCallable"]);
+/**
+ * The `[workflow]`-derived keys the builder emits, per mode — read from the
+ * vendored definition (#2644), not restated here. A field added to
+ * `src/config-surface/workflow.ts` is pushed with no edit to this file, which
+ * is what closes the recurring "CLI silently drops a new server field" bug.
+ */
+export function workflowPayloadFields(mode) {
+    const fields = writableFieldNames(WORKFLOW_TABLE, mode);
+    return mode === "create"
+        ? fields
+        : fields.filter((f) => !CREATE_ONLY_ON_THE_WIRE.has(f));
+}
+/**
+ * Per-field value producers, keyed by the definition's field name. A field with
+ * no entry is a scalar passthrough: on create the TOML value is forwarded as-is
+ * (absent → `undefined`, which `JSON.stringify` drops so the server default
+ * applies); on update it converges (absent → the field's model default, or
+ * `null` when it has none). That is what makes a passthrough field authorable
+ * by editing the definition alone (#2644 criterion 1); the entries below are
+ * the fields whose value semantics are genuinely their own.
+ */
+const PAYLOAD_VALUE = {
+    // accessRule / runAs / description — create coalesces absent/empty → omit;
+    // update coalesces both an explicit clear ("") and an omission to `null`,
+    // because the file is the whole truth (#2743). `value || null` also keeps a
+    // whitespace-only value out of the "set" state the server would trim to "".
+    accessRule: (value, create) => (create ? value || undefined : value || null),
+    runAs: (value, create) => (create ? value || undefined : value || null),
+    description: (value, create) => (create ? value : value || null),
+    // Schemas — parse a JSON string (or accept an inline table). Create omits
+    // when absent; update sends null so a cleared schema round-trips.
+    inputSchema: (value, create) => value ? safeJsonParse(value) : create ? undefined : null,
+    outputSchema: (value, create) => value ? safeJsonParse(value) : create ? undefined : null,
+    // #1972 — declarative run-scoped lock (`[workflow.lock]`, #1518 Phase 3).
+    // A TOML-owned nested-object field, mirroring the schemas above. Presence-
+    // keyed, not truthiness-keyed: forward the value whenever the KEY is present
+    // (`!== undefined`) — the server's create/PATCH accept an object OR a JSON
+    // string, so a present-but-malformed falsy value (`lock = false`/`0`) must
+    // be forwarded so the server surfaces its validation error, rather than
+    // being silently treated as absent (dropped on create, cleared on update).
+    // Absent on create → omit (server default: no lock); absent on update →
+    // null so removing `[workflow.lock]` clears the server-side lock
+    // (config-as-code). Before this the field was dropped from both sync paths,
+    // so a pull → push cycle silently lost the lock (#1972).
+    lock: (value, create) => value !== undefined ? value : create ? undefined : null,
+};
 /**
  * Build the workflow payload's `[workflow]`-derived fields from a parsed TOML
  * `[workflow]` table. `workflow` is `tomlData.workflow` (already merged with any
@@ -109,79 +155,23 @@ export const WORKFLOW_PAYLOAD_FIELDS_UPDATE = WORKFLOW_PAYLOAD_FIELDS_CREATE.fil
  */
 export function buildWorkflowPayloadFromToml(workflow, { mode }) {
     const create = mode === "create";
-    const payload = {
-        name: workflow.name,
-        description: workflow.description,
-        // status — create coalesces absent/empty → omit (server default `draft`
-        // applies); update forwards the bare value so it round-trips and an
-        // explicit "" surfaces the server's validation error rather than a silent
-        // no-op (matches the pre-existing update path).
-        status: create ? workflow.status || undefined : workflow.status,
-        // accessRule / runAs — create coalesces absent/empty → omit; update
-        // distinguishes explicit clear ("" → null) from leave-unset (absent →
-        // undefined).
-        accessRule: create
-            ? workflow.accessRule || undefined
-            : workflow.accessRule !== undefined
-                ? workflow.accessRule || null
-                : undefined,
-        runAs: create
-            ? workflow.runAs || undefined
-            : workflow.runAs !== undefined
-                ? workflow.runAs || null
-                : undefined,
-        // capabilities — create forwards the raw array (absent → omit); update
-        // forwards presence-aware so an explicit array round-trips. (The server
-        // update PATCH persist for capabilities is tracked separately in #1232; the
-        // round-trip guard asserts capabilities on the create leg only.)
-        capabilities: create
-            ? workflow.capabilities
-            : workflow.capabilities !== undefined
-                ? workflow.capabilities
-                : undefined,
-        // Queue limits — raw numeric pass-through both modes (absent → omit).
-        perUserMaxRunning: workflow.perUserMaxRunning,
-        perUserMaxQueued: workflow.perUserMaxQueued,
-        perAppMaxRunning: workflow.perAppMaxRunning,
-        perAppMaxQueued: workflow.perAppMaxQueued,
-        queueTtlSeconds: workflow.queueTtlSeconds,
-        dequeueOrder: workflow.dequeueOrder,
-        // requiresClientApply — raw boolean pass-through so an explicit `false` is
-        // preserved and only a truly-absent key drops (server default applies).
-        requiresClientApply: workflow.requiresClientApply,
-        // Schemas — parse a JSON string (or accept an inline table). Create omits
-        // when absent; update sends null so a cleared schema round-trips.
-        inputSchema: workflow.inputSchema
-            ? safeJsonParse(workflow.inputSchema)
-            : create
-                ? undefined
-                : null,
-        outputSchema: workflow.outputSchema
-            ? safeJsonParse(workflow.outputSchema)
-            : create
-                ? undefined
-                : null,
-        // #1972 — declarative run-scoped lock (`[workflow.lock]`, #1518 Phase 3).
-        // A TOML-owned nested-object field, mirroring the schemas above. Presence-
-        // keyed, not truthiness-keyed: forward the value whenever the KEY is present
-        // (`!== undefined`) — the server's create/PATCH accept an object OR a JSON
-        // string, so a present-but-malformed falsy value (`lock = false`/`0`) must
-        // be forwarded so the server surfaces its validation error, rather than
-        // being silently treated as absent (dropped on create, cleared on update).
-        // Absent on create → omit (server default: no lock); absent on update →
-        // null so removing `[workflow.lock]` clears the server-side lock
-        // (config-as-code). Before this the field was dropped from both sync paths,
-        // so a pull → push cycle silently lost the lock (#1972).
-        lock: workflow.lock !== undefined
-            ? workflow.lock
+    const payload = {};
+    for (const field of workflowPayloadFields(mode)) {
+        const descriptor = WORKFLOW_TABLE.fields.find((f) => f.field === field);
+        const tomlKey = descriptor?.tomlKey ?? field;
+        const produce = PAYLOAD_VALUE[field];
+        const raw = workflow[tomlKey];
+        payload[field] = produce
+            ? produce(raw, create, workflow)
             : create
-                ? undefined
-                : null,
-    };
-    // syncCallable — create includes it (raw boolean pass-through); update omits
-    // it (deferred second PATCH, #807 — see module doc).
-    if (create) {
-        payload.syncCallable = workflow.syncCallable;
+                ? // Scalar passthrough on create: queue limits, dequeueOrder, name,
+                    // capabilities, and the boolean flags — raw so an explicit `false`
+                    // or `0` survives and only a truly-absent key drops.
+                    raw
+                : // Update converges (#2743): a field the file omits sends its concrete
+                    // model default, or `null` when it has none (`name`, `capabilities`).
+                    // `??` (not `||`) so an explicit `false` / `0` still wins.
+                    (raw ?? WORKFLOW_MODEL_DEFAULTS[field] ?? null);
     }
     return payload;
 }