[objectstack-fleet]

Requested by Leehom · project thread

Fixes #28234

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么：流程设计器节点面板里两个节点的说明文字改成业务话：HTTP 节点的描述及 method / durable / timeoutMs / signingSecret / body 五条配置提示，审批节点的描述。原来的工程细节（outbox、重试/死信、HMAC、CEL 值信封、「字面量照写」）挪进各条旁边的代码注释，没有丢。
• 为什么改：卡 Flow node palette help in business words: the HTTP and approval node descriptions #28234（分诊 6531330544），Flow node help in business words: approval config describe text and node palette descriptions are written for engineers (#27356 row 15, #27521 row 39) #27838 的服务端半边：管理员在 Studio 搭流程时读到的是这些字，原文满是内部术语。规则同 PR fix(spec): approval node field help opens in business words #28233：首句业务话，不出现 ADR 编号、内部字段名或枚举字面量。
• 风险与回滚：只改文案。键、类型、默认值、可接受的值、行为都没动；packages/spec/** 与 ui/** 没碰。仓里没有断言旧文字的测试，也没有这些字符串的手写翻译。回滚即 revert。
• 先看：packages/services/service-automation/src/builtin/http-nodes.ts（描述与五条提示及其注释）；packages/plugins/plugin-approvals/src/approval-node.ts（审批描述）。
• 两分钟验证：git show HEAD -- packages/services/service-automation/src/builtin/http-nodes.ts，预期只见 description 字符串与注释的改动，configSchema 的键与 type 一个没变。
• 需要你做的：无，席位落地。

What changes

The node description and config help on a flow node descriptor are the text the Studio flow palette and node cards show an admin. Two descriptors, copy only:

HTTP node (packages/services/service-automation/src/builtin/http-nodes.ts)

Entry	Before	After
description	Call an external HTTP endpoint. With durable: true, the call is enqueued on the messaging outbox with retry / dead-letter; otherwise it runs inline and returns the response.	Send a request to an outside web service: wait for its answer, or hand it off to be delivered in the background with automatic retries.
method	HTTP method (default GET; POST when durable) — a literal, read as written	The kind of request, such as GET or POST. GET by default; POST when the request is delivered in the background.
durable	Fire-and-forget via the durable outbox (retry/dead-letter) instead of inline request/response	Deliver the request in the background and keep retrying if it fails, instead of waiting for the answer; the flow does not see the response.
timeoutMs	Per-request timeout (ms)	How long to wait for an answer, in milliseconds.
signingSecret	HMAC-SHA256 secret → X-Objectstack-Signature — the secret itself, read as written	A shared secret used to sign each request, so the receiving service can check it came from you (sent as the X-Objectstack-Signature header).
body	Request body (JSON-serialised) — a CEL value envelope { dialect: 'cel', source } evaluated per run to the payload, or a literal sent as written	What to send, as JSON: a fixed value, or an expression worked out on each run.

The engineer detail each old string carried now sits in a code comment directly above its entry: the outbox arm and its retry / dead-letter, the literal-read rule for method / timeoutMs / signingSecret, the CEL value envelope shape for body, the HMAC-SHA256 scheme and the '' unsigned opt-out for signingSecret. url and headers are not in this card's ruling and are untouched.

Approval node (packages/plugins/plugin-approvals/src/approval-node.ts)

• Before: "Route a record for human approval; suspends the flow until a decision, then continues down the approve / reject branch."
• After: "Ask people to approve or reject a record. The flow waits for their decision, then continues down the approve or reject path." The suspend / resume-edge detail is in a comment above it.

Wording starts from the card's proposal. One change: body adds "as JSON", since the payload is JSON-serialised and an admin choosing a fixed value needs to know that.

Also: packages/services/service-automation/src/builtin/http-node-signing.test.ts has a docblock that quoted the descriptor's old signingSecret text as a fact. It now says the spec's HttpConfigSchema.signingSecret reads that text and the descriptor says it signs each request. Comment only; no assertion changed.

Changeset: .changeset/28234-flow-node-help-business-words.md, patch on @objectstack/service-automation and @objectstack/plugin-approvals (both ship dist, which carries these strings), with both declaration lines.

Tests

No red-first defect: this is copy. Pins searched on origin/main 23d1303d1f with git grep -F for each old string across the repo (dogfood, docs and snapshots included):

• No test, dogfood fixture or docs snapshot asserts any of the old descriptor strings. The content/docs/references/automation/io-node-config.mdx rows that look alike are generated from the spec's HttpConfigSchema describes, which this card does not touch.
• ui/packages/app-shell/.../useFlowNodePalette.test.ts carries its own fixture text "Route a record for human approval", not read from the engine; ui/** is out of scope and the fixture stays green.
• No hand translation of these strings exists (no translation bundle or locale file carries descriptor descriptions).
• Pins changed: none. Comment updated: the http-node-signing.test.ts docblock above.

Results at d13beb7a:

• Build: pnpm --filter '@objectstack/service-automation...' --filter '@objectstack/plugin-approvals...' build under the verify lock → VERDICT command-exit 0.
• pnpm --filter @objectstack/service-automation --filter @objectstack/plugin-approvals test → service-automation Test Files 249 passed (249), Tests 3162 passed (3162); plugin-approvals Test Files 106 passed (106), Tests 1366 passed (1366); VERDICT command-exit 0.
• Same filter, typecheck → VERDICT command-exit 0.
• pnpm exec eslint --no-inline-config packages/services/service-automation packages/plugins/plugin-approvals → exit 0.

Acceptance notes

• Merge overlap: server seat 2 has automation cards in flight (automation: a try_catch region with two exits is refused at registration without saying how to join them #28055, service-automation: RESUME_CHILD_PENDING's no-record refusal names only two runs, so an intermediate subflow run stays parked after the operator follows the remedy #28202). The 17 open PRs were listed and each one's file list read (REST pulls/N/files; the Version Packages PR read to its last page): none touches http-nodes.ts, approval-node.ts or http-node-signing.test.ts. The one open PR in the same package, fix(connector-mcp): an include a credentialed MCP server does not list degrades the instance as a credential refusal, not the boot #28357 (head a91c84adc9, sys-connector-credential.object.ts), merges cleanly with this head: git merge-tree --write-tree exit 0.
• Out of scope, noted, not filed: the Console's hard-coded fallback palette entry in ui/packages/app-shell/src/views/metadata-admin/previews/flow-canvas-parts.tsx still says "Call an external API" for the HTTP node; the engine descriptor overlays it when present. Carrier: the ui half of Flow node help in business words: approval config describe text and node palette descriptions are written for engineers (#27356 row 15, #27521 row 39) #27838.

Verification

Derived gate list (node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, 61 commands on this diff), run at d13beb7a, exit codes captured before any pipe, reconciled with --ran: ✓ dispatch-gates --ran: 61 derived famil(ies) accounted for — 60 run, 1 NOT-MEASURED.

Gate readings

• 60 of 61 exit 0.
• node scripts/check-plugin-teardown-shape.mjs --self-test first exited 3 on the shallow clone; after git fetch --depth=1 origin 621a4876… it exits 0 (48 cases pass).
• pnpm check:i18n first exited 3 (CLI not built); after the gate's own prerequisite build it exits 0: check-i18n-bundles: OK (10 package(s) — all bundles in sync, no undeclared authoring keys).
• NOT MEASURED: pnpm check:dual-build-cjs-loads, reason: needs a full workspace build (34 packages without dist); CI's Lint & Repo Gates runs it.

No ! in the title and no (narrowing) arm, so no full dogfood battery.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic. (not touched)
• 2. Every name I added uses the casing for its kind. (no names added)
• 3. No formatter ran; pnpm lint passes. (scoped to the two packages)
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: its generated artifacts are regenerated and committed. (not touched)
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

2 anchor(s) derived from 2 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 60 of 212 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 11 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 35b178bd0a9090aaccf9c767b0c6abf1067eff01 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from beb8f171f472b2f05c51a04b6190ed803013594e — the merge of head d13beb7a2a646b226636e04d39ec1cf58822950a into base 35b178bd0a9090aaccf9c767b0c6abf1067eff01, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin beb8f171f472b2f05c51a04b6190ed803013594e && git checkout beb8f171f472b2f05c51a04b6190ed803013594e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 35b178bd0a9090aaccf9c767b0c6abf1067eff01 d13beb7a2a646b226636e04d39ec1cf58822950a && git checkout -B drift-repro 35b178bd0a9090aaccf9c767b0c6abf1067eff01 && git merge --no-ff d13beb7a2a646b226636e04d39ec1cf58822950a

node scripts/docs-audit/affected-docs.mjs --json 35b178bd0a9090aaccf9c767b0c6abf1067eff01

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[objectstack-fleet]

domain:server#1 · os-project-manager · session_01R1q2xdtYgU6FKrZ7LgjPCC

席位核对 · ACCEPT · domain:server seat 1 · os-project-manager · session_01R1q2xdtYgU6FKrZ7LgjPCC · 2026-11-01T05:10Z

Head d13beb7a, report 6553620242 (on #28234), claim 6553282511. No contract review is owed: there is no packages/spec/** path, no governed path, no narrowing and no Clause-②: yes.

item	reading
Shape	Draft, base main, Fixes #28234. 4 files: http-nodes.ts and approval-node.ts (descriptor text), one test docblock comment in http-node-signing.test.ts, and one changeset with patch on @objectstack/service-automation and @objectstack/plugin-approvals. Clause-②: no, Metadata-protocol: none.
Diff check (seat)	Only description strings change: the HTTP node description and its method, durable, timeoutMs, signingSecret and body help, and the approval node description. Each follows the card's proposed wording and #28233's rule: business words, with no ADR ids, internal names or enum literals. The engineer detail (outbox, retry / dead-letter, HMAC-SHA256, the CEL envelope) moved into code comments beside each entry, not lost. No key, type, default or configSchema shape changes. I checked the changeset prose against the diff sentence by sentence, and it matches.
Evidence	CI green on head d13beb7a (35 success, 13 skipped, 0 failed), including check:dual-build-cjs-loads. Governed check: NOT governed, 72 changed lines. The report gives automation 3,162/3,162 and approvals 1,366/1,366, typecheck and scoped eslint green, and 60 of 61 derived gates green, with check:dual-build-cjs-loads NOT MEASURED locally; CI's run on this head decides it. No open PR touches the two files, and the merge-tree against #28357 is clean.
Landing	「按照 pm-dispatch 规则复核过的都授权」 (Leehom, 2026-10-25T11:35Z): ready and auto-merge through the relay, once every check on this head is green or an expected skip.

---

Generated by Claude Code