feat(automation): a flow's credentials live in a write-only channel on the secret seam, not in its stored definition (#20790)

[objectstack-fleet]

Fixes #20790
Clause-②: yes (widening)

This PR carries out ruling record 5942356310 (letter A, R2 and C1, the maintainer's 「同意264」) under claim 5935167060 and its revision 5942559287. It names classes and positions only: no request, header, route, field path or value.

Cross-lane files (named before the change list)

• domain:engine
  • packages/metadata-protocol/src/protocol.ts: the per-type credential-channel registration, the save door's channel step (after the carry-forward, before the put), the publish gate's read of held positions, and the rollback and revert callers that pass the strip.
  • packages/metadata-protocol/src/sys-metadata-repository.ts: the restore verb gains a body-derivation option shaped like the promote verb's (R2).
• domain:spec: packages/spec/src/system/constants/platform-object-names.ts, one registry line.
• domain:cli
  • packages/runtime/src/flow-clone.ts: the C1 refusal.
  • packages/runtime/src/domains/automation.ts: the clone handler consults the refusal. This file is in claim 5935167060 but not in revision 5942559287's list (see Acceptance notes).
  • Two runtime pins.
• Shared harness: packages/qa/dogfood/ (one pin, one dev dependency, one source alias) and pnpm-lock.yaml.
• Generated ledgers: the platform-object tenancy census, the tenant-audit census page and counts file, and the engine-double-contract ledger. Each was regenerated by its own --write.

What changed

1. A write-only channel on the existing secret seam (service-automation).

• The new platform object sys_flow_credential holds one row per credential position of a flow, per lifecycle state (draft or active).
• Its one value field is secret-typed: the engine encrypts it through the host crypto provider, masks it on every read, and dereferences it only through the privileged resolver. No second secret mechanism and no per-door redaction were added.
• The object is private, closed to the generic data door, untracked and unsearchable. Its unique key is a fixed-width digest of the position.
• FlowCredentialChannel handles five operations:
  • store: explicit values go in; absent keeps; the cleared form deletes; a vanished position is dropped.
  • strip: takes credentials out of a body.
  • held positions: what the runtime gate reads as present.
  • promote: draft to active, on publish.
  • prune: on delete.
• A draft save never rotates the live credential. Publishing the draft promotes it.

2. The save door stores the body the channel returns (metadata-protocol).

• registerCredentialChannel(type, channel) registers a channel. saveMetaItem runs it after the carry-forward and before the put, so the stored row, every new history row and the content hash carry no credential.
• The runtime authoring gate reads the channel's held positions as present, both on an active save and when a draft is published.
• restoreVersion takes deriveRestoredBody. Rollback and revert pass the strip. A restore past the move therefore never puts a credential back at rest, and the channel keeps its current one. No new history copy is written.

3. Credentials are read at use time (service-automation, trigger-api).

• An inbound binding carries a resolver that reads the hook secret on each verification, so a rotation applies to the next post without re-arming.
• If a held secret cannot be read, the post is answered 503 SERVICE_UNAVAILABLE. It is never verified against nothing, and nothing is enqueued.
• The outbound http node resolves a held signing secret at execution. If it cannot read the secret, it refuses the node, so nothing is sent unsigned. The cleared form still sends unsigned on purpose and never asks the channel.
• For a packaged flow, a channel row wins at verification and the literal is the fallback (Q3 A).

4. C1: the clone door refuses a credential-holding source (runtime).

• The door refuses when the source holds a credential at any position, whether as a literal (a packaged flow) or held in the channel, the outbound signing secret included.
• The answer is 409 RESOURCE_CONFLICT, names the classes, and gives Q2 A's prescription: author the copy as a new flow with its own secret.
• Accepted cost, stated in the changeset: a packaged inbound flow can no longer be cloned in one step.

5. A one-time move with a receipt (service-automation).

• At kernel ready, stored flow rows that still carry a credential are saved again through the save door itself.
• Each moved flow gets one rotation notice in the log, naming the flow and its classes and never a value (Q1 B: rotate, don't scrub).
• With no provider, the run defers and writes nothing. A row that fails to move logs at error and says the row still carries the credential in cleartext.
• The run is recorded in sys_migration as flow-credential-channel, with counts and names only.
• History and audit rows are not rewritten. Packaged flows are not moved (Q3 A).

6. No provider means no write. With no crypto provider, a save that would land a credential is refused (503) before any row is written.

7. Spec and docs.

• Spec: one registry line.
• Docs: the flows page and the lifecycle page's clone row each had one sentence that this change made false; both are corrected.
• Changeset: minor for five packages. It carries the rotation instruction and the accepted cost, and the ADR-0087 gate reads it as non-breaking.

Evidence (head 417ba1fa6)

Pins (the ruling's list plus the card's four and Q4's outbound set):

• A channel write and its masked reads.
• Draft-to-active promotion.
• R2: a rollback past the move.
• C1: refusal for a literal-held source, a channel-held source and an outbound-held source.
• The administrator engine read (the reader the MCP stdio transport serves from) after the move.
• No provider means no write.
• No read surface serves the value.
• The inbound door verifies after the move and after an edit-and-republish.
• An explicit rotation replaces the credential.
• A packaged flow is untouched.
• Outbound signing reads the held secret.
• Delete drops the credential.

The end-to-end pin is packages/qa/dogfood/test/flow-credential-channel.dogfood.test.ts (8/8).

Every negative pin was ablated:

• A1 to A18 ran at a38db79ec through scripts/ablation-replace.mjs. Each anchor hit, each pin turned red, and after each restore the tree read clean against HEAD. Red counts ranged from 1 to 6 per ablation, across the channel, trigger, http-node, migration, clone and protocol pins.
• D1 (the dogfood pin) ran at 457f43476:
  • Mutated build: the marker was present in dist/ by preflight, and 6 of 8 tests went red. Tests 6 and 7 stayed green, as expected, because they do not read the ablated step.
  • Restore: preflight --absent passed, 8/8 green, and the diff against HEAD was empty.

Suites at 80b4647b2, each in the foreground under the shared verify lock:

• service-automation: 166 files, 2051 passed.
• metadata-protocol: 2 shards, 202 files plus 3 skipped; 2985 passed, 19 skipped.
• trigger-api: 2 files, 30 passed.
• runtime local project: 3 shards, 304 files; 4335 passed, 11 skipped.
• spec local project: 2 shards, 598 files; 17512 passed, 1 todo.
• Dogfood pin: 8/8.
• Typecheck (service-automation, metadata-protocol, trigger-api, runtime, dogfood) and spec tsc: all exit 0.

Gates: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 129 commands at 80b4647b2, and all 129 exited 0. The --ran reconciliation answered: 129 derived, 129 run, 0 NOT-MEASURED, 0 UNRUN.

Declared to CI: the full dogfood suite, the runtime repo project, and repo-wide lint.

Contract review round 1

The contract review of record found one wrong judgment: Q3 A at the inbound door. With a literal start-node secret, the hook reader asked the credential channel on every post, and the channel throws when it has no reachable store. A packaged inbound flow on a composition with no data engine therefore armed on its literal and was answered 503 on every post.

Commit 84d3d297a fixes it in the http node's shape, so both doors read one rule:

• With a literal, the reader asks the channel only when the channel's index holds that position. Otherwise it answers the literal without touching the channel.
• A held secret that does not come back still rejects, so the post is answered 503 and is never verified against the literal. The channel's own read keeps its throw.
• The index is per process. A row written after its last refresh (boot, kernel ready, metadata reload, or a channel write in this process) loses to the literal until the next refresh, exactly as at the http node.

Pins:

• (a) The real channel with no reachable store, and a packaged literal inbound flow: the reader answers the literal, and a correctly signed post through the real trigger answers 202.
• (b) The control: the channel holds the position, then its store becomes unreachable. The reader rejects, and the post answers 503 whether it is signed with the literal or with the held value.
• (c) The existing Q3 A pin (a held row wins over the literal) stays green.

Ablations at 84d3d297a. Each anchor hit; each run rebuilt and the dist preflight found the marker; each restore was proven by the file equalling its HEAD blob, the --absent preflight passed, and both pins went green again:

• E1, the holds gate removed: pin (a) went red in service-automation (1 of 17) and in dogfood (test 9: 503 where 202 was expected).
• E2, a held but unreadable secret falling back to the literal: pin (b) went red in service-automation (1 of 17: the reader answered the literal instead of rejecting) and in dogfood (test 10: 202 where 503 was expected).

At 417ba1fa6, after merging origin/main:

• service-automation: 166 files, 2053 passed.
• trigger-api: 2 files, 30 passed.
• The dogfood pin: 10/10.
• service-automation and dogfood typecheck: exit 0.
• The full gate union: 130 derived, 130 run, 0 NOT-MEASURED, 0 UNRUN.

The size is now 3646 changed lines (+3557 / −89), of which 1,678 are added test lines.

Acceptance notes

• Size. 3532 changed lines (+3443 / −89, 36 files) against the ruled band of 2300 ± 500. That is over the band but under 5000, and 1,578 of the lines are added test lines. There is no split.
• Premise. The premise was re-measured on main and still holds: the stored row and the history row carried both credentials in cleartext, and an administrator's engine read returned them. The MCP stdio door had already stopped serving them by the time of this build (the fix(mcp)!: the MCP stdio engine-only reader joins the stored-metadata-body family (exit one) #21228 change). [security] Stored-metadata-body family: two exits #21120 did not reach. An engine-only door serves an administrator credential material in cleartext, and the data door serves a content hash computed over the withheld credentials #21207 remains open. For flows only, this PR also removes the credential from what that card's checksum exit covers.
• File surface. packages/runtime/src/domains/automation.ts is outside revision 5942559287's list and inside claim 5935167060. The clone handler there is where the C1 refusal is consulted.
• Package duplication. Duplicating a package that holds an inbound flow whose secret the channel holds is now refused by the runtime authoring gate, because the copy holds no secret. This is consistent with C1: a copy never shares a secret.
• Inert migration mode. In inert mode, the stored re-save tool refuses a flow row that still carries a literal when no provider is registered. This is the no-provider rule, applied at that door.
• Legacy drafts. A legacy draft that still carries a literal, published while no provider is registered, is refused (503) for the same reason.
• Channel keying. The channel keys by flow name and state, env-wide like the engine's flow map. Stored rows of the same name in two packages therefore share one slot.
• Durability list. The receipt write is not on the durability-critical callee list.
• Write order. The channel write precedes the stored put. If the put fails, the channel is ahead of the row until the next save. No credential is exposed in that window.
• Presence index. The engine's check for whether a flow holds a credential reads an in-process index. The index is refreshed at boot, at kernel ready, on metadata reload, and on every channel write in that process. The value itself is always read live.
• Stale derivation. origin/main moved at least 10 commits after the gate derivation at 80b4647b2. One derivation input changed (a release script, outside this diff), and a test merge against current main is clean.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 6 package(s): @objectstack/metadata-protocol, @objectstack/dogfood, @objectstack/runtime, @objectstack/service-automation, @objectstack/spec, @objectstack/trigger-api, touching 130 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/metadata-protocol/src/index.ts, packages/qa/dogfood/vitest.config.ts, packages/services/service-automation/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

65 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 85986144c2ef6f379955137677c5cbfb00e194d2.

⛔ 13 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 3 changed file(s) yielded no anchor (packages/metadata-protocol/src/index.ts, packages/qa/dogfood/vitest.config.ts, packages/services/service-automation/src/index.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: isSystem (5 routes)
• 26 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 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 — 144 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 85986144c2ef6f379955137677c5cbfb00e194d2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fe35e66ada5e2c9e828ce9ea7029ca1578f02a95 — the merge of head 417ba1fa6fc6399a6bc077459c45d239542245e1 into base 85986144c2ef6f379955137677c5cbfb00e194d2, 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 fe35e66ada5e2c9e828ce9ea7029ca1578f02a95 && git checkout fe35e66ada5e2c9e828ce9ea7029ca1578f02a95
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 85986144c2ef6f379955137677c5cbfb00e194d2 417ba1fa6fc6399a6bc077459c45d239542245e1 && git checkout -B drift-repro 85986144c2ef6f379955137677c5cbfb00e194d2 && git merge --no-ff 417ba1fa6fc6399a6bc077459c45d239542245e1

node scripts/docs-audit/affected-docs.mjs --json 85986144c2ef6f379955137677c5cbfb00e194d2

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

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 85986144c2ef6f379955137677c5cbfb00e194d2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 37006699795 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (4/6) — 失败步骤: Run this shard's tests

  @objectstack/rest:test:  FAIL   local  src/import-template-route.test.ts > the `*` agrees with the engine: starred exactly when the import door refuses a blank > for every shape of default the engine 
    ↳ 失败原因: @objectstack/rest:test: Error: Test timed out in 5000ms.
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

⚠️ 断言这一侧有一类例外，判据是断言在测什么，不是它是不是 AssertionError。 断言的对象是产品行为（一个值、一个形状、一次拒收）⇒ 照上面读：真实的行为改变，去查，⛔ 不要重排掉；
断言的对象是这次实验自身的有效性前提（跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件）⇒ 它跟超时是同一类，同样对负载敏感，重排一次是合法的判别手段。
识别是机械的：断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为（真回归）；
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提：它守护的那条不变式当时是绿的，同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量，仍然是时间测量。（⛔ 这只改「怎么读一次红」，不改「哪些测试可以重排」——后者由别处管。）

跨 PR 相同签名（24h，按失败测试文件聚合）：

• src/import-template-route.test.ts — 24h 窗口内只有本 PR 撞到过，暂不汇总（再有一个不同 PR 撞到就会自动开汇总 issue）。
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 4 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[objectstack-fleet]

Queue failure triaged: not this PR's; one re-queue · domain:services seat 2 · session_01DiCSbmJrkzNhuEAier4VoJ · 2026-10-02T12:53Z

• Failing check: queue build 37006699795, Test Core (4/6), @objectstack/rest src/import-template-route.test.ts › "the * agrees with the engine … for every shape of default". Test timed out in 5000ms: a timeout, not an assertion.
• Why it is not this PR's:
  • This PR does not touch packages/rest, and that test file has not changed since 88b484e00.
  • rest depends on metadata-protocol, which this PR does change. That change is the credential-channel registration, the save-door store call and the restore derivation, and each runs only when a type registers a channel. Only service-automation registers one, and the rest test's engine does not load it.
  • On the PR head 417ba1fa6, the PR-side CI ran the affected Test Core shards (rest included, as a dependent of metadata-protocol) and every shard was green.
  • The queue's own triage reports this signature as a first occurrence in 24h.
• Action: one re-queue (auto-merge re-armed). This is the single permitted re-run for a timeout on an untouched test. If the same test fails again in the queue, it is treated as real and investigated, with no second blind re-queue.

---

Generated by Claude Code · https://claude.ai/code/session_01DiCSbmJrkzNhuEAier4VoJ