fix(service-automation)!: the subflow guards see a subflow or map call inside a region body - #28959

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/service-automation, @objectstack/spec, touching 4 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/services/service-automation/src/subflow-notice-guard.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx (via FlowSchema (symbol, a top-level const))

⛔ 6 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via AutomationEngine (symbol, a top-level class))
• content/docs/releases/v17/17-0.mdx (via AutomationEngine (symbol, a top-level class), FlowSchema (symbol, a top-level const))
• content/docs/releases/v17/17-4.mdx (via FlowSchema (symbol, a top-level const))
• content/docs/releases/v17/17-6.mdx (via AutomationEngine (symbol, a top-level class))
• content/docs/releases/v17/17-7.mdx (via FlowSchema (symbol, a top-level const))
• content/docs/releases/v18/18-1.mdx (via FlowSchema (symbol, a top-level const))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 1c0ec675ac1c5971c582625cbec010e03bfb32ca && git checkout 1c0ec675ac1c5971c582625cbec010e03bfb32ca
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ff88105061012c8b14f7ec937d7b3113e404e922 87411da83042879ee3c0d8a72a22a73ac3f99fe0 && git checkout -B drift-repro ff88105061012c8b14f7ec937d7b3113e404e922 && git merge --no-ff 87411da83042879ee3c0d8a72a22a73ac3f99fe0

node scripts/docs-audit/affected-docs.mjs --json ff88105061012c8b14f7ec937d7b3113e404e922

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs ff88105061012c8b14f7ec937d7b3113e404e922 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 87411da83042879ee3c0d8a72a22a73ac3f99fe0
Local-runs: none
Scope: packages/spec/src/automation/flow.zod.ts, packages/spec/src/automation/save-notice-placement.ts, packages/services/service-automation/src/subflow-guards.ts, packages/services/service-automation/src/subflow-notice-guard.ts, packages/services/service-automation/src/engine.ts, packages/services/service-automation/src/subflow-guard-region-calls.test.ts, .changeset/28846-region-nested-subflow-calls.md + packages/spec/src/automation/control-flow.zod.ts (collectFlowGraphs, MAX_REGION_DEPTH), packages/spec/src/automation/region-slots.ts (FLOW_REGION_SLOTS), packages/services/service-automation/src/region-suspension-refusal.ts, packages/services/service-automation/src/builtin/save-notice-node.ts, packages/services/service-automation/src/subflow-guard-every-door.test.ts, packages/services/service-automation/src/subflow-notice-arming.test.ts, packages/spec/src/conversions/registry.ts (flow-node-*-flow-alias), packages/lint/src/flow-cel-root-scope.ts, docs/adr/0126-packaged-metadata-customization-model.md §7.3, hotcrm src/marketing/flows/campaign-enrollment.flow.ts and campaign-member-enroll.flow.ts (hotcrm checkout a5982564)

Review face: the brief asks the narrowing face; record-recognisers --template --paths over the PR's file list reads the schema face off the two packages/spec/src/automation/* paths (its hits). Both map to CONTRACT_REVIEW_TIER, and both hits are inside Scope: above. The three prose paths (flow.zod.ts, save-notice-placement.ts, subflow-notice-guard.ts) are confirmed comment-only in the net diff against main (merge-base b15b634c, origin/main ff88105061; main has not moved on any touched path since the merge-base): every hunk sits inside a /** … */ header or a // line comment, no token outside a comment changes, and none is a .describe() or the TSDoc of an export.

Inputs read: card #28846 body and all four comments (triage 6566019553, claim 6568384018, seat ruling 6568462471, os-dev-report 6569441106); PR #28959 body, file list (7 files, +296/−15) and the net diff origin/main...87411da8; the check-runs on 87411da8. The cited code was read in the tree at 87411da8; nothing was built, run or re-run.

Check-runs on the head, read 2026-11-02T05:05Z: 20 success, 11 skipped, 30 in progress. Success: Governed Surface Queue Guard, Lint · PM dispatch-gates, Lint · scoped · tooling self-tests, Lint · CI, release & engine gates, Lint · docs & code guards, Lint · ESLint, Lint · repo & tooling gates, Lint · scoped · query-options erasure, Lint · scoped · slot lookup & corpus, Check Changeset, Type Check · source gates, Type Check · debt ledger, Spec property liveness, Dogfood Regression Gate, PR-body guards, Plan Test Core shards, Flag docs affected by code changes, filter, Auto Label-adjacent jobs. Still in progress at that reading: Build Core, Test Core (1–8/8), Type Check · workspace, Type Check · consumer gates, and the ui/ legs (Type Check UI, Test UI (1–16/16), Build & E2E UI, Live E2E UI). None failed. Re-read 2026-11-02T05:21Z after every run completed: 53 success, 11 skipped, 0 failure, 0 in progress — Build Core, Test Core (1–8/8), Type Check · workspace, Type Check · consumer gates, Type Check UI, Test UI (1–16/16), Build & E2E UI and Live E2E UI all success. Those conclusions are the gate verdicts for every derived gate family; nothing was re-run here.

① Derived judgments

Accept-set and surface changes the diff implies, each judged against the code as it stands on the head:

1. subflowTargets reads every region depth (subflow-guards.ts:62-72): the top-level graph plus every loop.body, every parallel.branches[i] and both try_catch.try / try_catch.catch slots, at every depth up to MAX_REGION_DEPTH (32), through collectFlowGraphs. Those four slots are exactly FLOW_REGION_SLOTS (region-slots.ts), the one declaration the parse, the lint walk and the conversion walk all read — so the guards cannot drift from what the spec calls a region. Right. The engine's subflowTargets docblock already named it "the ONE reading of 'flow A calls flow B' that both directions of the subflow guard share"; a region-nested subflow / map reaches its child through the same engine.execute on every pass, so the top-level-only reading was an implementation gap under that contract, not a reading the contract declared.
2. Arming decline (declineOntoDisabledSubflows → disabledPackagedSubflows → subflowTargets): a packaged caller whose region body calls a ledger- or status-disabled packaged child registers, is not armed, warns once, and /_status reports bound: false, unboundCause: 'disabled_subflow' naming the child. Packaged callers only, as before (engine.ts:5493-5497). Right — pinned by 6 it.each cases plus the two-deep loop { parallel { subflow } } case.
3. Re-judge (rejudgeSubflowCallers → packagedSubflowCallers and transitiveSubflowCallers, both over subflowTargets): a child republished obsolete disarms a region caller; republished active re-arms it. The second loop now re-asks a superset of callers; its settled test (subflowNoticeTrap(...) === undefined for a bound caller) keeps a caller the notice reading never moved from being flipped. Right — pinned (arming: a child republished obsolete under an armed caller that calls it from a loop body…).
4. Switch-off and removal refusal (refuseUnderReachingCallers, via packagedSubflowCallers): toggleFlow(child, false) and unregisterFlow(child) under an enabled packaged caller with a region-nested call are refused with code: 'DELETE_RESTRICTED', status: 409, subflowCallers: [caller], the §7.3 sentence; nothing moves. Right — pinned (parallel/map switch-off, try_catch/subflow removal), both halves of the pin present (envelope + getFlow still defined).
5. Enable refusal and ledger-cycle exemption (refuseEnableOntoDisabledSubflow → disabledPackagedSubflows; ledgerDisabledChainReaches → subflowTargets): read the same set by construction (one function). Right mechanically; not pinned with a region-nested call in this PR (should-fix 1 below).
6. The save-notice half of the arming gate stays top-level (subflow-notice-guard.ts: topLevel() and suspendingNode() unchanged; only the header prose moves). Right. region-suspension-refusal.ts (service-automation: a durable suspension inside a structured region (loop / parallel branch / try_catch) must fail the run with a named error, not leave progress state and report success — runtime half of #15646 ruling D #18881, ruling D on service-automation: a PAUSING map inside a contained region leaves its progress state behind — later loop iterations skip items and the exhausted map returns success having run nothing #15646) is the standing decision that a region body "runs SYNCHRONOUSLY inside the enclosing run. It cannot park that run on a durable pause", and the refusal is branded un-routable so no container can swallow it. So a region-nested call whose child suspends fails the caller's run at the region boundary; it never suspends the caller and never reaches a save_notice after the container. Counting it would decline with notice_after_suspending_subflow, a cause that is false for this shape. Pinned by two tests (a notice after a region call; a child whose only suspending call sits in a region). The seat's ruling 6568462471 and the dev's measurement (6/6 cases failed at the region boundary, child run left suspended) agree with the code; the stranded child run is automation: a subflow or map in a region body whose child suspends arms, fails every run at the region boundary, and leaves the child run suspended #28897, not this PR.
7. Published surface: no export added, removed or renamed; subflow-guards.ts and subflow-notice-guard.ts are not re-exported from the package index; AutomationEngine.subflowTargets is private. The only consumer-visible change is behavioural (items 2–5). Right — Clause-②: no (narrowing) is the correct arm.
8. packages/spec: no schema, no authorable key, no .describe(), no runtime logic (Prime Directive ✨ Set up Copilot instructions #2 holds); the parse, the save door and objectstack validate accept exactly the flows they accepted before. Right — Metadata-protocol: none is correct, and no spec generated artifact can move (the Type Check job's check:docs / check:api-surface lanes would red it if one did; Type Check · source gates is green on the head).
9. Robustness of the rewrite: the old body returned [] on a non-array nodes; the new body hands the flow to collectFlowGraphs, which takes flow.nodes ?? [] and skips non-record members, but would throw on a non-array nodes. Every caller reads the flow from this.flows, which "only ever holds FlowSchema.parse output" (engine.ts:9589, set at :4526), so nodes is always an array there. Right; no tolerant fallback was added at the consumer (Prime Directive Add comprehensive test suite for Zod schema validation #12).
10. Depth ceiling: a call nested deeper than MAX_REGION_DEPTH is unread — the same boundary every spec walk and the parse itself stop at, acknowledged in the PR's acceptance notes. Right; not a hole this PR could close on its own.

② Semver level

• Changeset .changeset/28846-region-nested-subflow-calls.md: '@objectstack/service-automation': patch, Clause-②: no (narrowing), Metadata-protocol: none, a **BREAKING** banner with Before / Now / Not changed / The fix / Who moves, and exactly one adr-0087: marker: not-required (no-migration-prescription) …. The PR body carries the same two declaration lines, line-initial, and the title carries !.
• Level: the kind is none, so the level is patch per the Post-Task Checklist ("a non-protocol change, widening or breaking, ships patch and keeps its BREAKING banner and ADR-0087 disposition"). Matches what the diff publishes: only @objectstack/service-automation ships a behavioural change.
• Disposition: no metadata key is added, removed, renamed or re-shaped; the "fix" in the body is an administrator's enable / republish, not a consumer code rewrite, so no-migration-prescription is the honest category and nothing to register in the ADR-0087 registries. Check Changeset is success on the head.
• No @objectstack/spec changeset: the spec diff is comment-only and publishes nothing (no dist byte can move from a comment inside a function body or a file-level header that is not an export's TSDoc). This is not a skip-changeset label on a publishing diff; it is a non-publishing part of a mixed diff whose publishing part carries its changeset. Accepted.
• Clause-②: line: no (narrowing) — the correct arm; a flow that arms today may decline, and a child switch-off / removal that is accepted today may be refused. Nothing widens.

③ Boundary flags

• Dev deviation 1 — half (b) of the order (the container rule for the automation: a save_notice after a subflow or map whose child suspends passes publish and strands every decision of the parent run #28840 gate) not implemented: the measured premise was false and the seat withdrew it in ruling 6568462471, filing the region-boundary failure as automation: a subflow or map in a region body whose child suspends arms, fails every run at the region boundary, and leaves the child run suspended #28897. Read against region-suspension-refusal.ts, the withdrawal is right (① item 6). Answered.
• Dev deviation 2 — subflow-notice-guard.ts header prose edited: read; the new sentences ("a call inside a region body cannot suspend the run … the run fails at its boundary instead"; "the re-judge … re-asks a superset") are true of the code on the head. Answered.
• Dev deviation 3 — no @objectstack/spec changeset: answered in ②.
• Triage should-fix 1 (spec prose): save-notice-placement.ts header and the flow.zod.ts wiring comment now say the subflow/map case is met by the arming gate (notice_after_suspending_subflow) and that the run-time refusal by name is the residue for a plugin-registered pausing type. Checked against the code: the gate is engine.ts activateFlowTrigger → subflowNoticeTrap; the residue is builtin/save-notice-node.ts:66-73 (this run holds no record write to answer …). Accurate.
• open_questions: [] — none to answer.
• Out-of-scope finding automation: a subflow or map in a region body whose child suspends arms, fails every run at the region boundary, and leaves the child run suspended #28897 (seat-filed): a region-nested call whose child suspends fails every run and strands the child run. Not this PR's; filed. Escalated already.
• Dev typecheck note: the workspace pnpm typecheck killed the @objectstack/spec test-layer tsc on the shared box (exit null); run alone it exits 0. The head's Type Check · workspace check-run is the verdict on that, not the dev's local run: success at 2026-11-02T05:21Z. Answered.
• Shipped flows: examples/** and packages/qa/** have no region-nested subflow / map on the head (the dev's reading; consistent with the grep of every type === 'subflow' / 'map' reader in the tree, which found no shipped-flow walker to contradict it). HotCRM campaign_enrollment (read at hotcrm a5982564): a screen flow whose two loop bodies call campaign_lead_member_enroll and campaign_contact_member_enroll, both status: 'active' with no pausing node — it still arms; switching those children off or removing them while it is enabled is now refused. That is §7.3 working, as the seat accepted.
• Check-runs on the head: every derived gate family answered by its check-run — 53 success, 11 skipped, none failed or in progress at 2026-11-02T05:21Z.

④ Design judgment

The narrowing, read against the published spec on main. ADR-0126 §7.3: "Disabling flow B is refused while any packaged flow references B as a subflow, and the refusal names the callers — otherwise a vendor flow breaks mid-run at its subflow node with an inexplicable failure." The ADR speaks of a reference, not of a top-level node; the engine's own docblock for subflowTargets calls it the single reading of "A calls B" that both directions share. A subflow / map inside a loop body, a parallel branch or a try_catch slot is a reference the run follows on every pass. So on main the spec declared a refusal the runtime delivered only for one node position: that is Prime Directive #10's "declared ≠ enforced", and the right repair is the one taken — implement the declared refusal at every call site, bulk paths included — not to narrow the claim. The diff takes no declared capability away at the consumer: registration, the save door and objectstack validate accept the same flows; what moves is arming and the child's switch-off / removal, which §7.3 already reserved. The narrowing makes the spec's own refusal real.

The card's three wants, in the tree: (1) measured first — the dev's 6/6 region cases armed and the top-level twins declined, consistent with the old body's for (const node of nodes); (2) subflowTargets reuses collectFlowGraphs — the import is from @objectstack/spec/automation and the body is a two-level loop over the graphs it returns, no second walker; (3) no new gate — the diff adds no guard, no FLOW_PAUSE_CAPABLE_NODE_TYPES change, no ui/**, no hotcrm change.

Attempts to break it.

• A malformed region. collectFlowGraphs drops non-record members and skips a slot whose nodes is not an array; a region the schema refused never reaches this.flows. Cannot throw through the guards.
• A region-nested call to a suspending child. Would the asymmetry (subflowTargets at every depth, the notice gate top-level) let a trap through? No: the only way a region-nested call could strand a notice is by suspending the caller, and region-suspension-refusal.ts fails the run at the boundary instead, un-routably. The two new pins hold exactly this. The asymmetry is correct, not a gap, and the header prose on both sides says why.
• Re-judge churn. transitiveSubflowCallers now returns more callers; each is re-offered only when its own reading moved (settled), so a region caller that is bound and trap-free is left alone.
• The ledger-disabled cycle exemption now sees a cycle closed through a region call; it is read with the same subflowTargets on both legs, so it stays symmetric.
• A map whose child is disabled, in a region with an empty collection. It declines although no pass would call the child. §7.3 refuses on the reference, and so did the top-level reading for a decision branch never taken; consistent.
• The alias key. A region-nested subflow carrying the retired config.flow alias is refused by the strict region schema at parse (and the conversion walk reads FLOW_REGION_SLOTS_BY_TYPE), so the guard's canonical-key-only reading is not a hole.
• Depth. Past MAX_REGION_DEPTH the call is unread — by the parse too; not a reachable shape for a flow the parse accepted.

Findings.

• Must-fix: none.
• Should-fix 1 — the enable door is not pinned with a region-nested call. refuseEnableOntoDisabledSubflow (toggleFlow(caller, true) onto a disabled child, RESOURCE_CONFLICT / 409) reads disabledPackagedSubflows, so it is covered by construction, and subflow-guard-every-door.test.ts pins that door for a top-level call only. One it in subflow-guard-region-calls.test.ts enabling a ledger-disabled packaged caller whose loop body calls an obsolete child, asserting the envelope and that the ledger row stays off, closes the "every door" set for the region shape. Not blocking: the reading is one function.
• Should-fix 2 — the subflow-guards.ts header still says "Each function here is the body of the AutomationEngine method of the same name, moved unedited" (slice 7 of the [maintainer] refactor(service-automation): split src/engine.ts (13,735 lines, +2,199 in 30 days) along its AutomationEngine seams, one move-only slice per PR #25222 split). subflowTargets is now edited in place and its own docblock was corrected to drop "moved unedited", but the file header was not. A one-line header amendment ("subflowTargets has since moved on, automation: subflow guards read top-level nodes only, so a subflow or map inside a region body escapes every subflow guard #28846") keeps the next reader from reading engine.ts history for a body that lives here.

Implemented-by: claude/project-thread-9kerqb
Reviewed-by: session_01FEkQ5kE5BrPUPNMMyv6oCH

VERDICT: PASS

Record rendered 2026-11-02T05:24Z.

domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH

席位核对 · ACCEPT · PR #28959 · 2026-11-02T05:26Z

Head-sha: 87411da83042879ee3c0d8a72a22a73ac3f99fe0

维护者速读(席位终稿)

• 改了什么:子流程守卫(ADR-0126 §7.3)现在也看见嵌在 loop / parallel / try_catch 区域里的 subflow / map 调用：引用了已停用子流程的打包调用方不再上膛;子流程在被区域内调用时停用、删除被拒(409,点名调用方)。以前只看顶层节点。
• 为什么改:automation: subflow guards read top-level nodes only, so a subflow or map inside a region body escapes every subflow guard #28846(p3),半张 (a);半张 (b) 经席位裁定 6568462471 撤回，区域内挂起子流程的问题另立 automation: a subflow or map in a region body whose child suspends arms, fails every run at the region boundary, and leaves the child run suspended #28897。
• 风险与回滚:低。subflowTargets 改读规范里唯一的区域遍历 collectFlowGraphs,无新门禁、无新导出、无 spec 运行逻辑改动(spec 只改注释)。save_notice 门仍只看顶层(区域边界本就按 service-automation: a durable suspension inside a structured region (loop / parallel branch / try_catch) must fail the run with a named error, not leave progress state and report success — runtime half of #15646 ruling D #18881 拒绝挂起),两条钉子守住。回滚即 revert。
• 先看:packages/services/service-automation/src/subflow-guards.ts 的 subflowTargets。
• 两分钟验证:pnpm --filter @objectstack/service-automation exec vitest run src/subflow-guard-region-calls.test.ts。
• 需要你做的:无。席位按常设授权落地，合并即关 automation: subflow guards read top-level nodes only, so a subflow or map inside a region body escapes every subflow guard #28846。
• 席位意见:契约复核 PASS,可落。

核对六项

1. 形态:draft → main;Fixes #28846,与认领 6568384018、裁定 6568462471 一致。文件 7 个，均在申报面内(三处 spec / notice-guard 文件只改注释，复核逐块核实)。
2. 前提实测:dev 在 main 实测 6 种区域形态(subflow/map × loop/parallel/try_catch)全部照常上膛，顶层孪生全部拒绝;base 上红 10 绿 4,head 14/14;三处消融各自变红后还原。
3. 门禁:本 head check-runs 56 success、15 skipped(路径未命中)、0 失败;Check Changeset 因摘标签重跑，此前同 head 已 success。dev 本地 83 条派生门禁 exit 0,dogfood VERDICT 0。dev 本地 workspace typecheck 中 spec 测试层 tsc 被共享机杀掉，由本 head Type Check · workspace success 作答。
4. 接受的偏差:无 spec changeset(spec 只改注释，不发布任何字节),复核接受。复核两条 should-fix(启用门补一条区域调用钉子;subflow-guards.ts 文件头 "moved unedited" 一句更新)席位接受，并入同线程下一单 automation: a subflow or map in a region body whose child suspends arms, fails every run at the region boundary, and leaves the child run suspended #28897。
5. 范围外去向:automation: a subflow or map in a region body whose child suspends arms, fails every run at the region boundary, and leaves the child run suspended #28897(区域内调用会挂起的子流程：每次运行在区域边界失败并遗留挂起的子运行)已立卡，本 PR 合并后派给同一线程。Metadata-protocol: none。
6. 落地条款:收窄 ⇒ CONTRACT_REVIEW_TIER 复核 PASS 6569776675(Head-sha 与现 head 一致),Clause-②: no (narrowing),needs:contract-review 已摘。semver:@objectstack/service-automation patch(ruling A),BREAKING 横幅与 ADR-0087 处置齐全，与 changeset 一致。check-governed-merges --pr 28959:NOT governed,311 行。落地授权，维护者原话:「按照 pm-dispatch 规则复核过的都授权」(2026-10-25T11:35Z)。