You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 2cba2eb
Browse filesBrowse the repository at this point in the historyBrowse files
feat(spec)!: refuse at publish a save_notice that a suspending node reaches (#28838)
domain:server#3 · os-project-manager · session_01FEkQ5omF1nCbQTGgW1nbRA
Fixes#28806
Clause-②: no (narrowing)
Metadata-protocol: narrowed
Skills-docs: follow-up #28787 — `skills/**` does not teach `save_notice`
yet; that open card carries the teaching, which should state this
placement rule beside the trigger rule
## 维护者速读
- **BREAKING(收窄)**:记录触发的流程里,如果 `save_notice` 节点能沿连线从
`approval`、`wait`、`screen` 或 `approval_revise` 之后到达,现在发布时就会被拒绝,返回
`INVALID_METADATA` 422,位置在
`nodes.<i>.type`。以前它能通过发布,但每次审批决定都会让流程卡住(`RESUME_FAILED`)。
- 拒绝文案会点名那个挂起节点,并告诉作者:把 `save_notice` 挪到它前面,或者在它后面改用 `notify` 节点。
- 按席位裁定,只要有一条路径经过挂起节点能到达,就拒绝,包括回环;放在挂起之前的 `save_notice` 照常通过。
- 挂起节点集合直接复用已有的 `FLOW_PAUSE_CAPABLE_NODE_TYPES`。`subflow`、`map`
只在子流程挂起时才挂起,发布时看不到,所以不计入,仍由运行时按名字拒绝。
- 已发布的流程没有这种形状:showcase 唯一的 `save_notice` 前面没有挂起节点,HotCRM main 里没有
`save_notice`。
- `Metadata-protocol` 实测为 `narrowed`(派单预计 `none`):按 AGENTS.md,作者能写的值被拒就是
narrowed,因此 spec 是 `minor`。详见下文和报告的 deviations。
- 没有需要你拍板的事项。合并前由席位做契约复核。
## What changes
**Spec: the placement door refuses a `save_notice` that a suspending
node reaches**
(`packages/spec/src/automation/save-notice-placement.ts`). After the
trigger check passes, the door walks the flow's top-level `edges`. It
takes every node that a node of an always-suspending type reaches from
its successors, where that suspending node is itself reachable from the
start. A `save_notice` in that set is refused:
> A `save_notice` node tells the person who made the write that fired
this run what the save set in motion, so it runs only while the run is
still inside that write. This one is reached after `approval` node 'ask'
suspends the run. A suspended run resumes after the write has already
answered, so on that path the node is refused by name at run time, and
after an approval the decision cannot finish its run. Move the
`save_notice` ahead of 'ask', or tell the person after it with a
`notify` node.
- **Which nodes suspend.** The door reuses
`FLOW_PAUSE_CAPABLE_NODE_TYPES` (`screen`, `wait`, `approval`,
`approval_revise`), the list of types that pause on every execution.
`flow.zod.ts` passes it in, so the door's module imports nothing back
from `flow.zod.ts`.
- `subflow` and `map` declare `supportsPause: true` but pause only when
the child flow they name pauses. That is a different record, which the
parse does not hold, so they are not counted. That is the same
classification ruling D made for region bodies. A `save_notice` after
one still meets the run-time refusal by name.
- **Reachability.** Any path counts, per the seat ruling, including
mixed graphs and loops. An edge after the approval that loops back to
before the notice makes the notice reachable from the approval.
- **Region bodies.** A region body cannot hold a pausing node (the
region rule refuses one). So a `save_notice` inside a `loop` /
`parallel` / `try_catch` body is judged by its top-level container, and
the refusal is anchored at the nested node's own path.
- **Shape.** `ctx.addIssue({ code: 'custom' })` at `nodes.<i>.type`,
which the metadata door answers as `INVALID_METADATA` 422, the same as
the trigger case. `objectstack validate`, the save door and
`registerFlow` refuse it alike.
**Test re-anchored:
`plugin-approvals/src/save-notice-approval-round-trip.integration.test.ts`**
(#28786). Its flow placed the second `save_notice` right after the
approval, which is the shape this PR refuses, so `registerFlow` now
throws in its setup. The test keeps its purpose:
- The approval is now asked in a `subflow` (`start → save_notice →
subflow(approval) → save_notice`). The parse accepts that graph. The
parent suspends with its child, is persisted in `sys_automation_run`,
and resumes from the store when the decision completes the child.
- The resumed `save_notice` still refuses by name. Through a subflow the
decision answers the approvals' existing subflow-parent strand:
`resumed: true`, with `resumeFailure: { code: 'RESUME_FAILED', runId:
<parent>, status: 'stranded' }` and `resumeError` naming the refusal. It
does not throw. That is existing behaviour, read and not changed.
- A second case pins this PR's refusal at `registerFlow` on the original
#28786 graph.
## Why
#28806: an AI writing "notify after approval" with `save_notice`
produced a graph that published and then stranded every decision. The
author now learns at publish time.
## Verification
- **Red first.** All 8 new refusal pins in
`spec/src/automation/save-notice-node.test.ts` were red before the
change (8 failed, 21 passed of 29) and green after (29/29). The 3
controls passed on both sides.
- **Door pins**
(`metadata-protocol/src/protocol.invalid-metadata-422-face-inventory.test.ts`,
#28806 block). In publish and draft mode they assert `{ code:
'INVALID_METADATA', status: 422 }`, `[['custom', 'nodes.2.type']]`, the
sentence verbatim and nothing stored. The control (notice ahead of the
approval) is stored.
- **Ablations, each red and then restored** (spec source through
`scripts/ablation-replace.mjs`, restore proven by `blob == HEAD`; `dist`
by hand, restore proven by blob hash):
- Never refuse: the 8 spec pins went red, then the 2 door pins and the
`registerFlow` pin (spec `dist`).
- Direct successors only: the several-hops and loop-back pins went red.
- Ignore the region container: the region pin went red.
- Count everything reachable from the start: the two "still parses"
controls went red.
- Add `subflow` to the pausing list: the subflow control went red.
- #28786's run-time pin, re-anchored on the subflow: with the executor's
no-channel refusal disabled in `service-automation/dist`, the round-trip
test went red (blob `505babcc` restored).
- **Shipped flows.** `examples/**` and `packages/dogfood`: one
`save_notice` (`examples/app-showcase` `showcase_task_completed`: `start
→ script → save_notice → notify → end`), with no suspending node. HotCRM
`origin/main` (`a598256`): no `save_notice`.
- **Gates.** `dispatch-gates.mjs --commands` derived 84; `--ran`
reconciles 84 run, 0 NOT-MEASURED, 0 UNRUN, all exit 0.
- **Suites.** Full `vitest run` of `@objectstack/spec`,
`@objectstack/metadata-protocol`, `@objectstack/plugin-approvals`,
`@objectstack/service-automation`, `@objectstack/trigger-record-change`
and `@objectstack/example-showcase`: exit 0 each. The round-trip file's
two cases run in about 0.3 s of test time.
- **Dogfood battery** (owed by the `(narrowing)` arm), on head
`bb9723f5` under `os-verify-lock.sh`: closure build `VERDICT
command-exit 0`; `pnpm --filter @objectstack/dogfood test` `VERDICT
command-exit 0`, Test Files 380 passed and 3 skipped (383), Tests 3114
passed and 28 skipped (3142), no failure.
- `eslint --no-inline-config` over `packages/spec`,
`packages/metadata-protocol` and `packages/plugins/plugin-approvals`
exits 0.
## Acceptance notes
- `Metadata-protocol: narrowed`, not the `none` the order expected.
AGENTS.md defines "a value refused" as `narrowed`, and a flow graph an
author could save before is now refused at the save door. The seat-1
contract review on #26912 ruled the same way for a save door refusing
what it stored before. Under ruling A the level follows the kind, so
`@objectstack/spec` is `minor`. No other package's shipped files move.
- The `RESUME_FAILED` / stranded-decision posture, the save-notice
contract and the wire `notice` are unchanged. No `ui/**` and no hotcrm
changes.
- A plugin-registered pausing type is not in the list (the namespace is
open), so a `save_notice` after one still meets the run-time refusal.
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes.
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset.
- [x] 6. `packages/spec` touched: no generated artifact moves
(`check-generated` and the spec artifact gates pass on this head).
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English.
- [x] The *Before Submitting* list in CONTRIBUTING.md is done.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01FEkQ5omF1nCbQTGgW1nbRA)_
---------
Co-authored-by: Claude <noreply@anthropic.com>
feat(spec)!: a `save_notice` node that a suspending node reaches is refused at the flow parse (#28806)
6
+
7
+
Clause-②: no (narrowing)
8
+
Metadata-protocol: narrowed
9
+
10
+
**BREAKING** for a flow that places a `save_notice` node after an `approval`, `wait`, `screen` or `approval_revise` node on a path from its start.
11
+
12
+
-**Before.** The placement check (#28251) read only the start trigger, so a record-triggered flow with `start → approval → save_notice` parsed and saved. At run time the leg after the suspension holds no write to answer, so the node was refused by name. After an approval the decision was already recorded when the resumed run failed, so every decision on such a flow stranded its run (`RESUME_FAILED`).
13
+
-**Now.** The `FlowSchema` parse also refuses a `save_notice` node reachable along the flow's edges from a node that always suspends the run (`FLOW_PAUSE_CAPABLE_NODE_TYPES`: `screen`, `wait`, `approval`, `approval_revise`). Any one such path counts, loops included, even when another path reaches the node before any suspension, because a static graph cannot rule the suspended path out. A `save_notice` inside a region body is judged by its top-level container. The refusal is the same `INVALID_METADATA` 422 at `nodes.<i>.type` as the trigger case. It names the suspending node and tells the author to move the `save_notice` ahead of it, or to tell the person after it with a `notify` node. `objectstack validate`, the metadata save door and `registerFlow` refuse it alike.
14
+
-**Not refused.** A `save_notice` reachable only before any suspension. A `subflow` or `map` ahead of the node: those pause only when the child flow they name pauses, which the parse cannot see, so a `save_notice` after one still meets the run-time refusal by name.
15
+
-**The fix.** Move the `save_notice` ahead of the suspending node the refusal names. To tell someone after the approval, use a `notify` node there.
16
+
-**Who moves.** No shipped flow has the refused shape: the showcase's one `save_notice` (`showcase_task_completed`) has no suspending node, and HotCRM's `main` carries no `save_notice`.
17
+
18
+
<!-- adr-0087: not-required (no-migration-prescription) no key of any schema is added, removed, renamed or re-shaped and no export or type changes: one more graph shape is refused at the parse with its own prescription in the error (move the node ahead of the suspending node, or use a notify node after it), which is a judgment about where the node stands, not a mechanical rewrite a migration could apply -->
0 commit comments