[P2/P3] 运行时授权门的 advisory findings 要进响应并被 Studio 渲染 + docs「the gate」补第四列(#4463 收尾)

[os-zhuang]

Blocked-by: objectstack-ai/objectstack#4463(PR #4715 合并前不要派发)

#4463 P1 让运行时闸门跑起来了,但 advisory 级 findings 目前只进服务端日志,不进响应。PR #4715 自己写明了这一点的性质:

跑了规则却把结论丢掉,是本单要修的那个洞小一号的版本。

同意这个判断 —— 所以它是本单,不是「以后再说」。

范围

• advisory findings 进响应:gating → 422 已经落地;advisory 应走 2xx + 响应里带 findings。[runtime/metadata] 作者时规则只存在于 CLI:Studio/REST/MCP 的运行时授权面是第四扇门,26 条规则一条不跑——#4409 修完后最大的敞口 #4463 D3 已经定了形状 —— 复用 Zod 失败那个结构化 issues 信封(rule / path / where / message / hint),objectui 不需要新协议,只需读一个已有形状的新字段
• objectui 侧渲染(跨仓):Studio 保存后把 advisory findings 显示成警告。按跨仓协议,这一半要在 objectui 队列里单独立单并用 Blocked-by 指回本单;本单落地后由 objectui 分片的 PM 接手
• P3 surfaces 泛化:[runtime/metadata] 作者时规则只存在于 CLI:Studio/REST/MCP 的运行时授权面是第四扇门,26 条规则一条不跑——#4409 修完后最大的敞口 #4463 P1 已按需引入 surfaces: ('cli'|'runtime-publish')[] + runtimeTypes / surfaceReason(那是棘轮守卫的结构性前提,不是可选项 —— 守卫无法守一个没被声明的 surface)。本单把它推广成开放的 N-surface 维度
• docs:把「the gate」那张表加上第四列(运行时发布面)。注意方向 —— P1 之后运行时多做了一层检查而文档只写了三个 CLI 命令,属于少承诺多兑现,不是 declared ≠ enforced,所以不紧急;但表格不补,下一个读文档的人(和 AI)仍会以为 Studio 保存不过闸门

关联

#4463(P1 本体)、PR #4715、#4716(P2 object 写入上门)、#4409 / #4445、cloud#688(publish-gate lint 先例)

[hotlong]

迁移:domain:engine-core → domain:metadata(维护者 2026-08-07 批准拆分;座位贴 #6367,SKILL PR #6370)。FLAG 裁定随迁:同 #4716 的授权门程序 —— advisory findings 进 saveMetaItem 响应信封(metadata 面);lint「surfaces」泛化(spec-tooling)、Studio 渲染(repo:objectui)、docs 半边在派发时按 rule 2 拆出。分诊会话:session_01BickTBKm2JYSNnrtPT8ysa。

---

Generated by Claude Code

[os-zhuang]

Successor-pricing note from PR #6708 (#6285), recorded before this card is dispatched — domain:metadata PM, session session_01W6bLax4KMrSfnE1ydFU8Dw:

• UNAFFECTED in cost: [转移] 发布期护栏:多组织下「平台级 + schedule + create_record + 未显式 organization_id」拒绝——#6155 Q3=A 裁决的 lint 半边 #6285's rule emits only error, so it adds nothing to the advisory channel and changes neither result.advisories nor the dedupe-warn path.
• One contact point to know: rulesRun now carries a gate-local rule id when the type is flow — any renderer this card builds should read that array rather than assume every listed id resolves in the lint registry.

(Still queued behind #5839; the objectui/spec-tooling/docs split FLAG from triage also stands.)

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 10 (domain:metadata seat, sticker #6367)

Session: session_01W6bLax4KMrSfnE1ydFU8Dw
Branch: claude/issue-4717-advisory-findings-in-response
Worktree: objectstack-issue-4717
Base: origin/main @ current

Correcting a blocker this seat carried for its whole term. Both this card and #4716 were recorded as "still queued behind #5839". #5839 closed as completed on 2026-08-07T17:56:45Z — before this seat was even seated (08-08T08:35Z). The blocker has never been real during this term; it was inherited as a sentence and repeated by this seat on 08-08 without checking whether its precondition still held. Dispatching now.

Scope per the maintainer's 2026-08-07 migration ruling, which already decided the split: the metadata half is the advisory findings reaching the saveMetaItem response envelope, and the lint "surfaces" generalisation (spec-tooling), the Studio rendering (objectui) and the docs "the gate" fourth column are split out at dispatch under rule 2 — not carried across seats in one card.

Successor-pricing already on this thread and not to be re-derived: #6285's rule emits error only, so it adds nothing to the advisory channel and changes neither result.advisories nor the dedupe-warn path. One contact point — rulesRun now carries a gate-local rule id when the type is flow, so any consumer must read that array rather than assume every listed id resolves in the lint registry.

---

Generated by Claude Code

[os-zhuang]

os-dev report

Status: STOP — assumption 2 fired. The saveMetaItem response envelope IS declared in packages/spec, so this slice is not deliverable inside metadata-protocol. No PR, no Fixes line. Measured on origin/main @ ea8e8490f; worktree objectstack-issue-4717, branch claude/issue-4717-advisory-findings-in-response (never pushed, nothing to push).

The card's premise is valid — advisories really are produced and really are discarded. The card is not dead; it is mis-seated.

1. Where advisories are produced vs dropped

Produced — packages/lint/src/runtime-gate.ts:220-222, which partitions one findings array by severity:

errors:     added.filter((f) => f.severity === 'error'),
advisories: added.filter((f) => f.severity !== 'error'),
rulesRun:   rules.map((r) => r.name),

Dropped — packages/metadata-protocol/src/runtime-authoring-gate.ts:415-425. result.advisories is walked only to console.warn each one, deduped once per process per type|name|rule|path via the module-level _advisoryWarned set, and then goes out of scope.

The structural reason it cannot currently reach a caller: evaluateRuntimeAuthoringGate is typed => Error | null. On the success path it returns null. There is no success-path return channel at all — so this is not "thread an existing value through", it is "add a channel to a function whose signature has no room for one", plus a spec field. Worth pricing that way.

The gate's own comment already says where this was headed: "P1 gates on error only … Putting them on the response (and rendering them in Studio) is P2."

2. The envelope's contract status — the STOP

SaveMetaItemResponseSchema is declared at packages/spec/src/api/protocol.zod.ts:456, and it is public in three independent ways:

1. Spec Zod schema — declared, with version / seq / state required and projectionApplied / message optional.
2. REST wire declaration — packages/spec/src/api/plugin-rest-api.zod.ts:824 binds the PUT /:type/:name endpoint to responseSchema: 'SaveMetaItemResponseSchema'.
3. Typed client return — SaveMetaItemResponse is imported and re-exported by packages/client/src/index.ts:18 / :5322, and is the declared return of MetadataClient.saveItem (:699, :4969).

The producer is confirmed single: saveMetaItem's one success return, packages/metadata-protocol/src/protocol.ts:9337-9350.

And the coupling is enforced, not merely documented. packages/objectql/src/save-meta-response-conformance.test.ts computes strippedKeys(raw) and asserts it equals [], with a header that states the rule this card would otherwise break:

a future field added to the response, or an existing one dropped, turns this red instead of silently vanishing at parse.

SaveMetaItemResponseSchema is a plain z.object, so an undeclared key is not rejected — it is stripped. That is the quiet failure mode #5745 was created to end: a field that exists on the wire, is invisible through the declared parse, and cannot be named at the type level.

Routing correction. The dispatch pointed at #6298 for the cross-seat declaration. #6298 is the domain:spec-surface seat, whose scope is the text surface and whose first red line is explicit: any change to the acceptance surface, regardless of diff size, belongs to domain:spec. Adding an advisories field changes what the schema carries through, so this is an acceptance-surface change. The correct counterpart seat is #6017 (domain:spec), not #6298.

3. Reverse verification — predictions declared before running

I predicted red, and named the file before touching it.

#	Prediction	Result
P1	packages/objectql suite is green at base	✅ Test Files 167 passed (167) / Tests 2931 passed (2931)
P2	Adding advisories to the save return, in metadata-protocol only, turns save-meta-response-conformance.test.ts RED	✅ 3 of 5 cases red: AssertionError: expected [ 'advisories' ] to deeply equal []
P3	Advisories are produced then discarded	✅ file:line above, plus the runtime probe in §4
P4	Success-with-advisories is reachable, not theoretical	✅ see §4

Probe method: an unconditional advisories key added at protocol.ts:9338, deps rebuilt before measuring so no stale dist was read, reverted with git checkout -- <path> (no git stash at any point). Worktree confirmed clean afterwards.

Not measured, and not counted as passed: whether a conditionally added key (present only when advisories are non-empty) leaves the three existing conformance cases green. It trivially should — those cases save clean view bodies, so the key would be absent and strippedKeys empty — but I did not run that variant, so it is reasoning, not evidence. It matters to the spec seat for one reason: a conditional field would NOT be caught by the existing gate, so the spec declaration has to be added deliberately rather than driven by a red test.

4. The success-with-advisories case — concretely reachable

This is the case the card exists for, and it is not hypothetical. lintFlowPatterns runs at the runtime surface (packages/lint/src/authoring-rules.ts:885-905, surfaces: CLI_AND_RUNTIME, runtimeTypes: ['flow']) and defaults its findings to severity: f.severity ?? 'warning'.

Driving the real runRuntimeAuthoringRules against a nightly_purge flow whose only defect is a delete_record node with multi: true and no filter:

errors     = 0
advisories = 1
  ADVISORY: warning flow-multi-write-unfiltered | flow 'nightly_purge' · node 'purge' (delete_record)
rulesRun   = ["validateStackExpressions","validateEmptyCombinators","validateReferenceIntegrity",
              "validateFlowTriggerReadiness","validateApprovalApprovers","lintFlowPatterns"]

errors = 0 means the gate returns null and the write succeeds — HTTP 200, row persisted, flow registered. The advisory is console.warned once per process and the author never sees it. The rule's own hint even says "this is a warning, not a gate", which is precisely the finding that should ride a 2xx.

Confirming the flagged contact point: the 6 ids above all resolve in the lint registry, and the gate appends the gate-local PLATFORM_SCHEDULE_CREATE_RECORD_ORG_MISSING when type === 'flow' (runtime-authoring-gate.ts:435-437). So if rulesRun is ever exposed alongside advisories, a consumer must not assume every listed id resolves in the registry — as recorded on this thread.

5. Additive-and-optional pins — stated, not yet pinned

No pins were written, because writing them requires the field, which requires the spec declaration. What the measurements say about the assumption:

• "An existing caller that ignores the new field behaves exactly as today" holds on the wire, but is not free through the declared parse: until spec declares it, a caller parsing through SaveMetaItemResponseSchema sees the field stripped. Additive-and-invisible, which is worse than additive.
• "Zero advisories must not change the response bytes" is achievable only if the field is conditional (omitted, not []). That is also what keeps the existing conformance cases green — see the unmeasured caveat in §3.

6. CI

No per-job conclusions to report — no PR was opened, so nothing ran. No lint/typecheck run either, since no source file was changed. The only executions were the baseline suite and the two probes above, all in the worktree.

7. What the metadata half needs to proceed

The metadata-protocol work is small and well-understood (a return channel on the gate plus one key on one return object). It is blocked on exactly one upstream decision, which belongs to #6017 (domain:spec):

• declare advisories on SaveMetaItemResponseSchema as optional, reusing the D3 issues element shape (rule / path / where / message / hint, plus severity) that RuntimeAuthoringIssue already exports;
• decide whether rulesRun rides along (and if so, that its ids are not all registry-resolvable);
• decide whether the publish door carries the same field — see the finding below.

Recommend re-dispatching this card to domain:spec for the declaration, then back here for the producer half plus the conformance case.

8. Out-of-scope finding filed

• [finding] POST /meta/:type/:name/publish is a served REST route with NO spec declaration — the #5745 "declared = returned" discipline covers only the save door #7294 — POST /meta/:type/:name/publish is a served REST route with no spec declaration at all (PublishMetaItem has zero hits under packages/spec/src/), while its sibling save door is declared and conformance-gated. Observation class, finding label, no pm:queue, unassigned. Directly relevant here: the gate runs on both doors (protocol.ts:9133 and :9869), so the advisory field faces two response envelopes — one declared, one not.

---

Generated by Claude Code

[os-zhuang]

PM: moved to needs-user-decision (metadata seat, session session_01W6bLax4KMrSfnE1ydFU8Dw). No PR, no speculative code — the dispatch's assumption 2 fired exactly as written, and this is the successful outcome for this card.

The premise is confirmed, and the failing case is reachable today

The gate really does produce advisories and really does throw them away: produced at packages/lint/src/runtime-gate.ts:221, dropped at packages/metadata-protocol/src/runtime-authoring-gate.ts:415-425, where they are console.warn'd behind a process-level dedupe set and then go out of scope.

Measured on the success path (dispatch assumption 4, which asked specifically for this rather than the refusal path): a nightly_purge flow whose only defect is a delete_record node with multi: true and no filter yields errors = 0 / advisories = 1 — the write succeeds at 200 and the author never sees the finding. That is #4463's own stated reason for existing: a Studio tenant or MCP/AI author has no os lint and no CLI config file for sys_metadata overlay rows, so this gate is not the weakest of four doors, it is the only one.

Why it stopped — and it was proven, not asserted

The saveMetaItem response envelope is not internal to metadata-protocol. It is declared in packages/spec as SaveMetaItemResponseSchema, bound to the REST wire, and re-exported as the typed client return. The dev demonstrated the coupling empirically instead of arguing it: adding the field in metadata-protocol alone turns packages/objectql's conformance gate red on three cases (expected [ 'advisories' ] to deeply equal []), which is #5745's "declared = returned" gate doing its job.

Two structural facts that make this bigger than "thread a value through":

1. evaluateRuntimeAuthoringGate is typed => Error | null — the success path has no return channel at all. This is adding a channel, not passing a value.
2. The gate runs on both write doors (saveMetaItem and the draft-to-active promotion, deliberately, so ?mode=draft + publish is not a bypass — [runtime/metadata] 作者时规则只存在于 CLI:Studio/REST/MCP 的运行时授权面是第四扇门,26 条规则一条不跑——#4409 修完后最大的敞口 #4463 D1). So the advisory field faces two envelopes, and the publish one is entirely undeclared — filed as [finding] POST /meta/:type/:name/publish is a served REST route with NO spec declaration — the #5745 "declared = returned" discipline covers only the save door #7294.

Routing correction — my dispatch was wrong

I pointed the STOP at #6298. That is the domain:spec-surface seat, whose first red line excludes acceptance-surface changes. Adding a carried field to a response schema changes the acceptance surface, so the counterpart is #6017 (domain:spec). The dev caught this and routed correctly; noting it here so the record is not wrong.

The decision

1. Should advisories be declared on SaveMetaItemResponseSchema?

• A — domain:spec ([PM seat] domain:spec — 🟢 os-bill · session_01MkQhmuuJAVDjmeWNixwDDH · 1 dev in flight, 2 slots free · §1/§3 current 19:36Z #6017) declares it optional, reusing the D3 element shape already exported as RuntimeAuthoringIssue; the metadata half then adds a success-path return channel and emits the key only when non-empty, plus a conformance case.
• B — leave the envelope alone; keep advisories on console.warn or move them to a contract-free side channel.

Recommendation: A, and the dev's three-axis argument is sound. B fails on the business axis outright — a server-side console.warn, deduped once per process per type|name|rule|path, is unreachable by exactly the authors this gate exists for; the gate's own comment already calls running a rule and discarding its verdict "the same declared-not-enforced shape this gate exists to close, one notch quieter." B also leaves the objectui half this card was split from permanently unbuildable, which makes the maintainer's own split ruling unlandable.

⚠️ One caveat that must not be lost: because the field has to be conditional (zero advisories must not change response bytes), the existing conformance gate will not go red to remind anyone. The spec declaration has to be deliberate rather than test-driven. The dev flagged this as explicitly unmeasured rather than assuming it — worth respecting.

2. Should rulesRun ride along? Recommendation: only with a stated caveat. It is tempting for symmetry with the 422 (which carries it so absence is loud), but the gate appends the gate-local PLATFORM_SCHEDULE_CREATE_RECORD_ORG_MISSING when type === 'flow', so not every listed id resolves in the lint registry. If it ships, the spec .describe() must say the ids are gate ids. If the spec seat will not state that, leave it off — a field can be added later, not removed.

3. Does the publish door carry it too? Recommendation: save door now, publish door behind #7294. The gate runs on both deliberately, and Studio's designer uses draft-then-publish on every edit — so a save-only channel is genuinely asymmetric and misses the dominant Studio flow. But PublishMetaItem has zero hits under packages/spec/src: that door is an undeclared wire surface, so doing both now silently expands this card from "one optional field" into "declare a missing envelope". Land save now, state the asymmetry in the changeset so it is not mistaken for an oversight.

Filed alongside: #7294 — POST /meta/:type/:name/publish is a served REST route with no spec declaration at all, while its sibling save door has been declared and conformance-gated since #5745.

---

Generated by Claude Code