[objectstack-fleet]

domain:spec#2 · os-tesla · session_01L9qibx5r5nhDMwpRs4SL6D

Requested by Tesla · project thread

Fixes #27429

Clause-②: no (text only)
Metadata-protocol: none

维护者速读

• 改了什么：六处文字跟上连接器凭据的现行规则：ADR-0097 加一条带日期的修订说明和一行指引，clearConnectorCredential 的拒绝清单补上 503，连接器文档与 MCP 提供方的一句注释不再把"凭据引用解析不到"归为启动失败，QA 清单的一条用例改为验收"降级"而不是"启动失败"，自动化服务里连接器物化函数的说明注释同样改正。
• 为什么改：connectors: sys_connector_credential + open-tier resolver chain (env → credential object → vault), reconcile on credential change, install-local prompt for missing credentialRefs (ruling A on #27230) #27237 之后，凭据引用解析不到时只把该连接器实例降级（应用照常启动，管理员事后补填凭据即可恢复），清除已存凭据会把在线实例拆下；这六处仍写着旧规则，AI 和作者读到会照着错的规则写元数据、写测试。
• 风险与回滚：只改注释、文档和 QA 清单文字，不动任何运行行为；回滚即 revert 本 PR。ADR 改动使本 PR 属 Tier H，需要授权审批。
• 先看：docs/adr/0097-declarative-connector-instances.md 中 "Runtime reconcile" 下的新修订说明；docs/qa/platform-checklist/areas/integration-system.json 条目 integration-system.connector-auth-kind-application 的 acceptance[2] 与 negative[2]；packages/spec/src/contracts/automation-service.ts 的 clearConnectorCredential 注释。
• 两分钟验证：pnpm check:platform-checklist && pnpm check:adr-symbol-anchors，预期两个都通过（清单校验认可 revision 5，ADR 里引用的 #degradeConnectorForCredential 能解析到代码）。
• 需要你做的：以 os-zhuang 审批本 PR（Tier H，ADR 一行）；之后由席位落地。

What changes

#27237 (PR #27344) made an unresolved or refused credentialRef degrade its instance instead of failing the boot, and its credential door's DELETE tears a live instance down. Five texts still stated the old rule, and a sixth (the materializer's own docblock) was folded in by the seat's claim amendment. Each was measured against main at 501c864d (plugin.ts#degradeConnectorForCredential, #clearConnectorCredential, #doorCredentialChain, #scheduleDeclarativeRetry) before it was rewritten. None of them had been fixed by a later PR; the card's line numbers had drifted (noted per item).

1. docs/adr/0097-declarative-connector-instances.md (Tier H; triage 6490151714's cross-domain exception).
   • A dated amendment note under "Runtime reconcile": an unresolvable credentialRef leaves the reload list, as it left the boot list (the §6 note). A reference no source answers for degrades its instance at boot and on a reload alike, and a live connector under that name is torn down first; that is how a cleared stored credential takes its instances down. A stored credential the deployment cannot read right now (unreadable store, no crypto provider yet) degrades too but leaves a live connector serving. Both go on the backoff. A host resolver that throws keeps the old rule (fatal at boot, logged and skipped on reload). Each fact is read from degradeConnectorForCredential and the reconcile's catch around resolveConnectorCredential.
   • A one-line pointer in the "Upstream availability" lead, after "stay fatal at boot", naming the notes under §6 and under "Runtime reconcile".
   • The header's Amended by line gains the entry for this note, as every earlier amendment of this ADR has one.
2. packages/spec/src/contracts/automation-service.ts, IAutomationService.clearConnectorCredential: the refusal list gains 503 SERVICE_UNAVAILABLE (when the store cannot be read or written, ConnectorCredentialUnavailableError in #clearConnectorCredential, or the tenancy posture cannot be read, #doorCredentialChain), nothing changed. Docblock only.
3. content/docs/automation/connectors.mdx (card ≈L361, now L407): the inline-secret example's "a reference, resolved at boot" becomes "resolved at materialization (unset, it degrades the instance)". The failure table at L593 already states the degrade.
4. packages/connectors/connector-mcp/src/mcp-provider.ts (card ≈L243, now L273): the comment no longer groups a rejected credential "like an unresolvable credentialRef" on the fatal side; it says an unresolvable reference never reaches the factory, since the materializer degrades its instance first.
5. docs/qa/platform-checklist/areas/integration-system.json, item integration-system.connector-auth-kind-application (card L1943 / L1992, now L1961 / L2010), revision 4 → 5 with a history row: acceptance[2] grades the degrade (api oracle: the degraded descriptor naming the reference and its remedies, the boot's warn line, the dispatch failure) and negative[2] fails a boot that dies on it; the title, fixtures.requires[2] (the env → sys_connector_credential → host resolver chain), steps[3], steps[5], automated.ref and source[2] follow. The cited pin "fails boot loudly when credentialRef does not resolve" no longer exists; the item now cites "degrades the instance, naming the reference, when credentialRef does not resolve" (connector-materialization.test.ts) and "missing → degraded naming the reference; set → ready; clear → degraded again" (connector-credential-door.test.ts), both run below.
6. packages/services/service-automation/src/plugin.ts, the materializeDeclaredConnectors docblock (≈L2093; added by the seat's claim amendment): the boot-fatal / reload-skipped list no longer names an unresolvable credentialRef (it names the host resolver that throws, which does keep that rule), and a paragraph says such a reference degrades its instance in both modes, tearing a live connector down first ({@link degradeConnectorForCredential}). Comment only.

No changeset: the diff publishes no behaviour, only comment and docblock text (skip-changeset declared at create).

Tests

No test changes: text only. The two pins the QA item now cites exist and pass (output under Verification).

Acceptance notes

• @objectstack/lint author-facing text says a credentialRef is "resolved at boot" (credential-literal.ts ≈L22, lint-flow-credential-literals.ts ≈L29, rule-explanations.ts ≈L4705, the last pinned at lint-flow-credential-literals.test.ts ≈L502). It describes where the secret lives rather than the failure rule, so it is loose rather than wrong; carrier: none, noted only.
• ADR-0097's 2026-10-27 note (PR fix(connectors)!: refuse a non-3.x OpenAPI document at load; mcp tools/list follows nextCursor and a 401/403 is a fatal configuration fault #26798) still says a rejected MCP credential sits "beside an unresolvable credentialRef" on the fatal side. The 2026-10-28 note right after it already reverses the rejected-credential half, and the new lead pointer covers the credentialRef half; the dated note itself is left as written (amendments are append-only).
• clearConnectorCredential also answers 400 VALIDATION_ERROR for an empty or oversized reference (#credentialRefOfRequest), which its docblock does not list either. Left out: the ruling grants this one docblock line for the 503.
• The QA item's new acceptance[2] was not run live (no echo-upstream fixture in this container); its evidence is this body and the item's history row, as RUNNER.md asks for a ledger edit's own verification.

Verification

pins the QA item cites

• Under the verify lock: pnpm --filter @objectstack/service-automation exec vitest run --maxWorkers=2 src/connector-materialization.test.ts src/connector-credential-door.test.ts -t 'TWO_CASE_NAMES' (the two names above) → Test Files 2 passed (2), Tests 2 passed | 82 skipped (84); VERDICT command-exit 0.

derived gates

• At 8b24dd6d (after the sixth text): node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derives 98 families (the 95 below plus check-tenant-audit-census and its --self-test, and check:durability-log-level), each run with stdin from /dev/null, exit code recorded before any pipe, after a dts rebuild of @objectstack/service-automation (record: 27429-gates-ran-8b24dd6d.list in the seat's out folder). --ran reconciliation: 98 derived, 98 run, 0 NOT-MEASURED, 0 UNRUN, all exit 0.
• At eef6c15b (the five texts): 95 families, record 27429-gates-ran-eef6c15b.list, after a dts build of every non-ui, non-docs package (turbo, lock VERDICT command-exit 0). check-plugin-teardown-shape --self-test first exited 3 on the shallow clone (its pinned control 621a4876 unreachable); after git fetch origin 621a4876 --depth=1 it exited 0. --ran: 95 derived, 95 run, 0 NOT-MEASURED, 0 UNRUN, all exit 0.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/connector-mcp, @objectstack/service-automation, @objectstack/spec, touching 3 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))

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

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

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 59 of 211 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 — 168 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 b4ccbc6f1052090751489741247deae55b726372 → packageMentionDocs.

Which tree this was computed on

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

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

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

[objectstack-fleet]

domain:spec#2 · os-tesla · session_01L9qibw58ehQ2gRHP2h2Puz

Contract-review-claim: session_01L9qibw58ehQ2gRHP2h2Puz · head 8b24dd6d99a3a5b831826b4365d9253bfb7c0240 · 2026-10-31T06:14Z

[objectstack-fleet]

domain:spec#2 · os-tesla · session_01L9qibw58ehQ2gRHP2h2Puz

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 8b24dd6d99a3a5b831826b4365d9253bfb7c0240
Local-runs: none

Inputs: card #27429 (body: the five texts, the seat's claim and its amendment adding the materializer docblock as a sixth), PR #28346 (body, the file list of 6 files, the diff of 74 changed lines against main, the two commits from the merge-base 501c864), the 54 check-runs on this head (read 2026-10-31T06:18Z: all 54 runs completed, none failed, none cancelled, none in progress; success: Build & E2E UI, Build Core, Build Docs, Build UI Deps, Check Documentation Links, Dogfood Regression Gate, Flag docs affected by code changes, Governed Surface Queue Guard, Lint & Repo Gates, Lint · CI, release & engine gates, Lint · ESLint, Lint · PM dispatch-gates, Lint · docs & code guards, Lint · repo & tooling gates, Lint · scoped · query-options erasure, Lint · scoped · slot lookup & corpus, Lint · scoped · tooling self-tests, Live E2E UI, PR-body guards (claim · duplicate · Part-of · single-writer path), Plan Test Core shards, Spec property liveness, Test Core, Test Core (all 8), Test UI, Type Check UI, Type Check · consumer gates, Type Check · debt ledger, Type Check · source gates, Type Check · workspace, TypeScript Type Check, filter; skipped: 18.x upgrade harness (opt-in), Auto Label, Check Changeset, Check PR Size, Dogfood Regression Gate (matrix shard/3), Dogfood Verify CLI, Lint UI, Packed-tarball smoke (opt-in), Schedule gate · skip when a green push run covers the commit, Temporal Conformance (live PG + MySQL), Test UI (matrix shard/16), UI Published Artifacts), and the tree on main for the rule each text now states: plugin.ts (the reconcile's resolveConnectorCredential call and its catch at :2336 to :2348, degradeConnectorForCredential at :2815 to :2860, clearConnectorCredential at :3056 to :3075) and connector-credentials.ts (ConnectorCredentialUnavailableError at :147, missingCredentialReason at :515). The head is mergeable and clean against today's main (merge-tree clean); main moved content/docs/automation/connectors.mdx since the merge-base (#28331, a different section) and the merge is clean.

① Derived judgments

• The ADR-0097 amendment note states the code's rule, fact by fact - right. A reference no source answers for (resolution.kind is missing) degrades the instance at boot and on a reload through the same door, and a live connector under that name is dematerialized first ("its credential is no longer set"); a stored credential the deployment cannot read now (any other non-resolved kind) degrades too and the warn line says the previously materialized connector keeps serving; both land in degradedInstances for the backoff; a host resolver that throws goes through fail, which is fatal at boot and logged and skipped on a reload. The "Upstream availability" pointer and the header's Amended by entry follow the ADR's own amendment style (connectors: sys_connector_credential + open-tier resolver chain (env → credential object → vault), reconcile on credential change, install-local prompt for missing credentialRefs (ruling A on #27230) #27237 and adr (0097): the degraded-instance section still says every husk's dispatch refusal promises "the platform retries automatically"; held instances (#27992, #27237) are not retried #28038 entries already sit on that line).
• clearConnectorCredential's contract gains the 503 - right. The door throws ConnectorCredentialUnavailableError (status CONNECTOR_CREDENTIAL_UNAVAILABLE_STATUS, the door's 503) when the store's clear throws, and the walled-posture refusal sits before it; "nothing is changed" is true because the throw precedes any write. The interface docblock is the contract authors and the OpenAPI read, so this is the right place.
• The connectors page, the MCP provider comment and the materializer docblock - right. The example's comment now says the reference resolves at materialization and an unset one degrades; the MCP factory never sees an unresolvable reference because the materializer continues after degrading before any factory call; the docblock's fatal list keeps the host-resolver throw and drops the unresolvable reference, naming the door.
• The QA item follows the degrade rule and bumps its revision - right. acceptance[2] becomes an api clause (the degraded descriptor, the warn line, the dispatch failure), negative[2] fails a boot that dies on it, fixtures.requires[2] names the env, store, host chain, steps and refs name the door test and the materialization test's current case name, and a revision: 5 history entry cites connector credentials: five texts still describe the pre-#27237 rule (ADR-0097 reload paragraph, clearConnectorCredential's 503, connectors.mdx, mcp-provider comment, QA checklist item) #27429. check:platform-checklist stays off per-PR CI by standing decision (fleet-patrols.yml), so the dev's local run is the evidence for the checklist's shape; the QA file is text, not a gate input for landing.
• Accept-set: nothing moves - right. Comments, docs and a QA JSON only; no schema, export or runtime path. Clause-②: no and Metadata-protocol: none are right; skip-changeset is right for a diff that ships no package bytes (the automation-service.ts change is a docblock in the spec contract source, which the built package carries, but the lane's precedent for comment-only contract edits is no entry).
• Check-runs as gate verdicts - read as above; every run on this head completed and none is red, cancelled or in progress at the read.

② Semver level

• No release; skip-changeset - accepted as above.

③ Boundary flags

• Tier H by docs/adr/** - os-zhuang approves after the seat's ACCEPT; the seat lands.
• Serial overlap with feat(service-automation): serve oauth2 connector instances per dispatch, and connect an authorization_code instance per organization (ADR-0143 S1) #28317 on content/docs/automation/connectors.mdx - feat(service-automation): serve oauth2 connector instances per dispatch, and connect an authorization_code instance per organization (ADR-0143 S1) #28317 (ADR-0143 S1) edits the same page in other sections and is dirty against main already; whichever lands second merges main. No shared hunk.
• The 503 docblock names two causes the door raises from two places - the store's clear throwing (read here) and the tenancy posture being unreadable (raised inside doorCredentialChain, not re-read line by line here; the dev measured it). Not owed.
• Out of scope, left alone - the connectors page's wider "boot fatal" vocabulary elsewhere on the page was not re-audited beyond the hunk the card named.

Verdict reasoning. Six texts now state the rule the code has had since #27237, each checked against the door on main; nothing runtime moves; the ADR edit is a dated amendment in the record's own style; every check is green or skipped and the head is clean against main.

Implemented-by: claude/project-thread-e1q97t
Reviewed-by: session_01L9qibw58ehQ2gRHP2h2Puz

VERDICT: PASS

[objectstack-fleet]

domain:spec#2 · os-tesla · session_01L9qibx5r5nhDMwpRs4SL6D

维护者速读

• 改了什么： 六处连接器凭据文字跟上现行规则：ADR-0097 加一条带日期的修订说明和一行指引；clearConnectorCredential 的拒绝清单补上 503；连接器文档、MCP 提供方注释、物化函数的说明注释不再把「凭据引用解析不到」归为启动失败；QA 清单一条用例改为验收「降级」（revision 5）。
• 为什么改： connectors: sys_connector_credential + open-tier resolver chain (env → credential object → vault), reconcile on credential change, install-local prompt for missing credentialRefs (ruling A on #27230) #27237 之后，凭据引用解析不到只让该连接器实例降级，应用照常启动；这六处还写着旧规则，作者和 AI 会照着错的规则写元数据和测试。
• 风险与回滚： 只改注释、文档、ADR 修订说明和 QA 清单文字，不动运行行为，不发包。回滚即 revert。
• 先看： docs/adr/0097-declarative-connector-instances.md「Runtime reconcile」下的新修订说明。
• 两分钟验证： pnpm check:platform-checklist && pnpm check:adr-symbol-anchors，预期都通过。
• 需要你做的： 以 os-zhuang 批准本 PR（Tier H：docs/adr/** 受管面）。批准后由席位落地。
• 席位意见： ACCEPT，待批准后落地。

席位核对 · ACCEPT · domain:spec seat 2 (#18549) · 2026-10-31T14:40Z

Head 8b24dd6d99a3a5b831826b4365d9253bfb7c0240. Card #27429 (domain:server, taken before the maintainer's 「为什么跨车道接卡」 and kept under 「已经在处理的可以继续」), claim and its amendment 6539732036 adding the materializer docblock as the sixth text.

• Shape: draft to main, made by the relay; Fixes #27429; Clause-②: no (text only), Metadata-protocol: none at line start; skip-changeset.
• Contract review: PASS by the lane review thread, record 6540004323 on this head, reviewer not the drafter. No must-fix, no should-fix. Its boundary notes: serial overlap with feat(service-automation): serve oauth2 connector instances per dispatch, and connect an authorization_code instance per organization (ADR-0143 S1) #28317 on content/docs/automation/connectors.mdx (different sections, whichever lands second merges main); the connectors page's wider "boot fatal" wording beyond the card's hunk not re-audited.
• Diff read by the seat: 6 files, +52/−22. The ADR edit is a dated, append-only amendment with its Amended by header entry; each fact matches degradeConnectorForCredential and the reconcile's catch. The 503 line matches ConnectorCredentialUnavailableError, thrown before any write.
• Follow-ups filed: none owed (the lint "resolved at boot" wording and the docblock's missing 400 are noted in Acceptance notes, not wrong).
• Gates: check-runs on this head 54 completed, 0 red (read by the review at 06:18Z). mergeable_state clean against today's main. check-governed-merges --branch: GOVERNED, 1 of 6 paths (docs/adr/**), +52/−22 → landing tier H.
• Authority: Tier H: an authorized APPROVED review (os-zhuang) first; then the seat lands under 「按 pm-dispatch 审过的pr你可以自主落地」 (2026-10-30T14:20Z, project thread).
• Landing: pr_ready + pr_request_reviewers (os-zhuang, hotlong) in this act; automerge_enable after the approval.