[objectstack-fleet]

Requested by Leehom · project thread

Fixes #28698

Clause-②: no — no accepted value and no public surface changes: the same stored definitions are refused as before; a start now carries on past them instead of stopping.
Metadata-protocol: none

维护者速读

• 改了什么:环境里保存的连接器(元数据门 / Studio 保存的,环境级或 authored 包内)若配置后来失效,平台启动时只记录并跳过它,与运行中遇到同样问题时的处理完全一致;宿主自己声明的连接器和已安装包的连接器出错仍然阻止启动。
• 为什么改:一条存储的连接器定义失效(例如提供它 provider 的插件被移除)会让整个环境无法再启动,而运行时同样的问题只跳过该连接器;这是可用性问题,不是数据问题。
• 风险与回滚:只改 plugin.ts 启动连接器协调中的一个判断:错误归属于存储条目时走已有的软路径(同一条日志记录,无新记录形状)。回滚即还原该提交;宿主条目的失败语义未变,有对照测试钉住。
• 先看:packages/services/service-automation/src/plugin.ts(fail 的 stored 参数及各调用点)、src/connector-materialization.test.ts 新的 service-automation: a stored connector row whose configuration became invalid stops the next boot, where the same fault after boot only skips the row (#28594 follow-up) #28698 一节、packages/qa/dogfood/test/stored-connector-package-ref-restart.dogfood.test.ts。
• 两分钟验证:pnpm --filter @objectstack/service-automation exec vitest run src/connector-materialization.test.ts,预期 102/102 通过(含 5 类故障各一对「存储条目跳过 / 宿主条目失败」)。
• 需要你做的:无,席位落地。

What changes

• Stored connectors no longer stop a start. A provider-bound connector saved in the environment that later stops being valid is now handled at start exactly as it is while the platform runs: the same log record, that connector not served, the host's own connectors beside it serving. This covers every configuration fault the start meets on a stored connector: a provider no installed plugin offers, a host credential resolver that throws, a retry policy its schema refuses, a name a plugin connector already holds, a configuration its provider refuses, and a duplicate of a name the host declares. PR fix(service-automation)!: a connector stored in the environment never reads the host's files #28671 made one of these (a refused package-relative ref) behave this way; this PR widens that same path to the rest. There is no second skip path and no new record.
• Host-declared and installed entries keep failing loudly. A connector the host's stack declares, and an installed package's (connector materializer: an installed package's package-relative providerConfig file ref is read from the HOST's package root, so an install-local app can bind the host's own file (measured: it materialized ready with the host's OpenAPI document) #28534's installed / unrecorded readings), still stop the start on a configuration fault. Which entries count as stored is the classifier PR fix(service-automation)!: a connector stored in the environment never reads the host's files #28671 introduced, unchanged.
• Code. In reconcileDeclaredConnectors, the reconcile's fail reporter takes a third argument, stored; at start it throws only when that is false. Each fault site passes the entry's reading. The per-entry flag PR fix(service-automation)!: a connector stored in the environment never reads the host's files #28671 used for the ref refusal is removed, because the ref refusal is now one stored fault among the others and reaches the same fail call. The package readers are read once at the top of the run (they were read a few lines later before), so the duplicate check can use them.
• Out of scope. A stored row that takes a name a plugin connector registers later in the start is a separate card.
• Changeset: patch for @objectstack/service-automation.

Tests

• Restart (dogfood). stored-connector-package-ref-restart.dogfood.test.ts now also carries a stored connector whose provider no installed plugin offers, beside the existing refused-ref rows and the inline control. After a restart the platform starts, the row is not listed and the start's record names it, and the inline control and the showcase's own connectors list ready. Red on base 0be4c8a5 (6 failed, 1 passed), green at head (7/7).
• Unit (connector-materialization.test.ts, new #28698 section). For each of five faults (unknown provider, invalid retryConfig, throwing credential resolver, plugin-held name, provider-refused config): a stored entry lets the start finish, is skipped with its record, and the host's entry beside it serves; and a control where the host's own entry with the same fault still fails the start. Plus a stored duplicate of the host's name (skipped, host serves), two host entries of one name (fails), and an installed package's entry with an unknown provider (fails, connector materializer: an installed package's package-relative providerConfig file ref is read from the HOST's package root, so an install-local app can bind the host's own file (measured: it materialized ready with the host's OpenAPI document) #28534 unchanged). The connector materializer: a stored or authored provider-bound connector row resolves its package-relative providerConfig refs against the HOST's root (the #28534 class, through the metadata door) #28594 control "an unknown provider still fails the boot" now uses a host entry filed as declared, since a stored one with that fault is exactly what this PR makes soft.

Ablations (each restored, blob equals HEAD, marker absent from dist after restore)

• One fault site reverted to fatal (the unknown-provider report): unit 1 failed | 101 passed (the stored unknown-provider case); restart dogfood 6 failed | 1 passed.
• The whole widening reverted (fail throws at start for every entry): unit 12 failed | 90 passed (the five stored faults, the stored duplicate, and the six connector materializer: a stored or authored provider-bound connector row resolves its package-relative providerConfig refs against the HOST's root (the #28534 class, through the metadata door) #28594 stored-ref cases); restart dogfood 6 failed | 1 passed. Every host control stays green under both.

Acceptance notes

• Which of these faults a stored row can actually carry was measured on the showcase before the change; the readings are with the seat. A retry policy the schema refuses is refused at save (422 INVALID_METADATA), so it is covered by the unit test only. A name saved twice (environment-wide and in an authored package) lists once and does not reach the duplicate check from stored rows; the duplicate case is unit-covered. The showcase has no credential resolver that throws; that case is unit-covered.
• check:dual-build-cjs-loads answered exit 3 (prerequisite: a full build) and is NOT MEASURED locally; CI is the record.
• Overlap: open PR feat(service-automation, metadata-protocol): a flow override declared in BASE.custom is the packaged flow, saved, served and armed in place of the base (#28412) #28693 touches plugin.ts with a comment around the flow contenders, far from this hunk.

Verification

At head f76068ce:

Package and file runs

• @objectstack/service-automation: typecheck exit 0; test: Test Files 251 passed (251), Tests 3210 passed (3210).
• connector-materialization.test.ts: Tests 102 passed (102).
• dogfood stored-connector-package-ref-restart + stored-connector-package-ref: Test Files 2 passed (2), Tests 14 passed (14), after rebuilding @objectstack/service-automation.

Derived gates

dispatch-gates --ran: 65 derived, 64 run, 1 NOT-MEASURED (check:dual-build-cjs-loads, exit 3), 0 unrun. Every other family exit 0.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-automation, touching 2 documentable anchor(s).

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

• content/docs/automation/flows.mdx (via AutomationServicePlugin (symbol, a top-level class))
• content/docs/kernel/cluster.mdx (via AutomationServicePlugin (symbol, a top-level class))

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

• content/docs/releases/v17/17-6.mdx (via AutomationServicePlugin (symbol, a top-level class))

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.

What this run could not see

• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 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; 100 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 — 10 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 c16040d8daf2664c6e3fcd67935d4768ba1fa6d3 → packageMentionDocs.

Which tree this was computed on

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

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

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

[objectstack-fleet]

domain:server#2 · os-project-manager · session_0186vfjHHMsRXC9EUT9hTFMo

席位核对

ACCEPT · domain:server seat 2 · os-project-manager · session_0186vfjHHMsRXC9EUT9hTFMo · 2026-11-01T15:42Z · head f76068ce · #28698

The maintainer's standing authorisation for landing reviewed PRs, verbatim: 「按照 pm-dispatch 规则复核过的都授权」.

1. Shape:
   • A draft against main with Fixes #28698 and a patch changeset for @objectstack/service-automation.
   • check-governed-merges --pr 28729 reads NOT governed, +220 / -56. Landing tier S.
   • The claim (6559504115) names this PR's branch, claude/project-thread-i4ccqc.
2. Against the order:
   • The one boot soft path PR fix(service-automation)!: a connector stored in the environment never reads the host's files #28671 added is widened. A stored entry's configuration fault is logged with the same record and skipped at boot, as after boot: duplicate name, plugin-name conflict at this pass, unknown provider, and a credential resolver that throws.
   • A host-declared entry's fault keeps the fail-loud contract at boot.
   • There is no second skip path. The stored reading is the same classifier (nonHostDeclaringPackageOf), read once per run.
   • The restart rig reads red on base (6 failed, 1 passed) and green at head (7/7).
   • Both ablations red, and the host controls stay green.
   • Per the seat's ruling, the faults this seam cannot reach are named out of scope. The boot-order conflict with a plugin connector is service-automation: a stored connector saved under a host plugin connector's name stops the next boot (#28698 follow-up) #28713.
3. Contract review: not owed. No spec or governed path is touched, and Clause-②: no carries no narrowing arm. A boot that stopped now starts, and the same definitions are refused as before.
4. Gates:
   • The dev reports 64 of 65 derived gates run. check:dual-build-cjs-loads is NOT MEASURED locally, and CI is the record.
   • service-automation reads 3210/3210.
   • CI on this head was in progress with 0 red at review, and auto-merge waits for it.
5. Overlap: git merge-tree against main is clean.
6. Landing: pr_ready + automerge_enable through the relay.

---

Generated by Claude Code