test(automation): reconcile the control-flow designer forms against their Zod (#4045)

[os-zhuang]

#4045 step C, region half — after #4050 (step 1), #4059 (3a) and #4064 (step A). Tests only, no production code.

The gap

loop / parallel / try_catch each carry two descriptions of the same config:

	artifact	job
descriptor configSchema (hand-written literal)	drives the Studio form	what an author can set
control-flow.zod.ts	validates the value	what the runtime accepts

Nothing compared them. #4064 pinned the shape of the first; this pins the relationship, so neither side can gain or lose a key without the other noticing.

Both directions matter:

• Zod accepts a key the form omits — Console: screen-flow Submit never calls the resume endpoint — every screen flow is un-completable from the UI #3528's failure inverted. A real config key with no way to author it in Studio, discoverable only by reading the executor. That is exactly how notify.source sat unnoticed until fix(automation,spec): graduate notify's nested source into the conversion layer (#4045) #4050.
• The form offers a key the Zod rejects — the author fills in a field whose value is then dropped or fails to parse.

Why the two sources are not merged — measured, not assumed

I ran the generation on main 53fbf49 (options as in control-flow.test.ts):

node	published form	generated from Zod
loop	597 chars, depth 5, 25 keys	5,537, depth 14, 201 keys	9.3×
parallel	294 chars, depth 6, 16 keys	5,112, depth 15, 189 keys	17.4×
try_catch	737 chars, depth 5, 40 keys	10,739, depth 14, 397 keys	14.6×

Generation succeeds — no recursion error — but emits no $defs and no $ref. FlowNodeSchema is inlined in full at every region key, so loop.body arrives as the entire node/edge definition:

"body": { "type": "object", "properties": { "nodes": { "minItems": 1, "type": "array",
  "items": { "type": "object", "properties": {
    "id": {…}, "type": {…}, "label": {…},
    "config": { "type": "object", "propertyNames": {…}, "additionalProperties": {} },
    "connectorConfig": {…} } } } } }

versus the published nodes: { type: 'array' } with no items — opaque, because a loop body is edited on the canvas, not in a property form.

Making the generated output usable means a projection that prunes ~90% of it back off (201 → 25 keys), at which point "one source" is a fiction: you maintain the Zod, the projection rules, and a check that the projection still does the right thing — three things instead of two.

This corrects the premise #4045 opened with (and my own first analysis on it), which treated these three as redundant copies awaiting de-duplication. They are a second artifact with a different job, and the gaps are deliberate. Full data in the issue.

So the divergence is declared rather than erased

A DELIBERATELY_SHALLOW ledger names each shallow key with its reason (loop.body, parallel.branches, try_catch.try, try_catch.catch), and every entry must name a key both sides still declare — so it cannot rot into a reference to something renamed away. Same bidirectional discipline as the #4040 expression ledger.

One deliberate limitation, stated in the file

This compares key sets, not generated shapes. Generating needs z.toJSONSchema, and service-automation does not depend on zod — only @objectstack/spec does. Adding that edge to the package graph to run a test is not worth it when schema.shape yields the key set without it, and the key set is where the drift that matters lives. The depth divergence is measured once in the table above, and its form half is pinned by config-schemas.test.ts. The test file says all of this, so the next reader does not assume it was forgotten.

Verified to bite in all three directions

An assertion that never fails is decoration:

# Zod gains a key the form does not offer
× 'loop': the form offers exactly the keys the Zod accepts
AssertionError: loop: accepted by the Zod but absent from the designer form:
  expected [ 'brandNewRegionKey' ] to deeply equal []

# the form gains a key the Zod rejects
× 'loop': the form offers exactly the keys the Zod accepts   (inverse set)

# a ledger entry points at a renamed key
× every ledger entry names a key both sides actually declare
AssertionError: loop.bodyRenamedAway: not on the form any more

Test plan

Check	Result
@objectstack/service-automation	✅ 457 passed (5 new)
ESLint on the new file	✅ clean
spec check:api-surface / check:authorable-surface / check:docs	✅ PASS

The negative controls rebuilt spec, which regenerates authorable-surface.json — checked back to clean and the gates re-run, so no generated artifact rides along in this diff.

Empty changeset — tests only, nothing releases.

Remaining in #4045

• Flat half of step C — screen / CRUD / http / notify have no region keys, so the single-Zod-source route stays viable there; the one thing needing explicit handling is additionalProperties on the 7 keyValue slots (z.record() emits {}, not the load-bearing true; .meta({ additionalProperties: true }) overrides it, and objectui accepts {} anyway per json-schema-to-fields.ts:456).
• Step 3b — tightening the feat(automation,formula): warn on undeclared flow-node config keys (#4045) #4059 unknown-key warning into an error still needs a release of real-world distribution data first.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QoA8AV99Ss1RRkLLAYmDzq

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Jul 30, 2026 8:37am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): packages/services.

6 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/webhooks.mdx (via packages/services)
• content/docs/kernel/runtime-services/audit-service.mdx (via packages/services)
• content/docs/kernel/runtime-services/index.mdx (via packages/services)
• content/docs/kernel/runtime-services/settings-service.mdx (via packages/services)
• content/docs/plugins/packages.mdx (via packages/services)
• content/docs/protocol/kernel/i18n-standard.mdx (via packages/services)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.