platform-schema: CI hardening, anti-drift hardening, owner-model docs, and trigger coverage

[luffy-aiagent]

What problem does this solve?

Closes #1337
Closes #1338
Closes #1339
Closes #1340

Discord Discussion URL: https://discord.com/channels/1491295327620169908/1491365158868619404/1532377620241449040

All four issues were identified during group review of #1295 (the platform-schema knowledge base PR) and are bundled here since they're small, related follow-ups to that same subsystem.

Review Contract

Goal

1. ci(platform-schema): expand conformance workflow path triggers to cover adapter source code #1337 — Expand platform-schema-conformance.yml's trigger paths to also cover the adapter/core source trees that schema code-refs point into, plus a weekly scheduled run as a backstop.
2. ci(platform-schema): add --locked, Rust cache, checkout@v6, and concurrency group #1338 — Harden the same workflow: actions/checkout@v6 (was @v4, inconsistent with rest of repo), add Swatinem/rust-cache, add a concurrency group.
3. fix(platform-schema): harden check_code_ref — reject empty symbols and path traversal #1340 — Harden check_code_ref in crates/platform-schema/tests/conformance.rs: reject empty #symbol, reject path traversal outside repo root.
4. docs(platforms): assign page owners and establish maintenance guidelines #1339 — Replace the proposed fixed per-platform-owner model with open contribution guidance + a documented known limitation (see rationale below and issue comment).

Non-goals

• fix(platform-schema): harden check_code_ref — reject empty symbols and path traversal #1340's third sub-point (aligning feature_sources_exist_in_tree to skip URL sources like the quirk check does) is intentionally not included — see "Alternatives Considered".
• No named per-platform owners are assigned (docs(platforms): assign page owners and establish maintenance guidelines #1339) — see issue comment for rationale.

Accepted Residual Risks

• feature_sources_exist_in_tree still hard-errors on a URL source instead of skipping it (unlike quirks). Verified no current schema file needs this (136 feature source entries checked, none are URLs). Documented as an explicit decision in docs/platforms/README.md, revisit if a feature genuinely needs a URL source.
• Semantic drift (a code-ref stays valid but the note/status it documents goes stale) is not detectable by CI — only syntactic drift (renamed/removed symbols) is, and only for the file trees now covered by ci(platform-schema): expand conformance workflow path triggers to cover adapter source code #1337's trigger paths. Documented as a known limitation; no dedicated owner audits for it.

Acceptance Criteria

• platform-schema-conformance.yml triggers on changes to crates/openab-gateway/src/**, crates/openab-core/src/**, and src/main.rs (all current schema code-ref targets, verified by extracting every .rs path cited across all 8 schema files), plus a weekly schedule backstop paired with workflow_dispatch for manual testing (matches the other 10 schedule-triggered workflows in this repo)
• platform-schema-conformance.yml uses checkout@v6, has a Rust build cache, and a concurrency group keyed by both github.event_name and github.ref (a push-to-main run and the weekly schedule run both resolve github.ref to refs/heads/main; without event_name in the key they'd share a group and cancel-in-progress could cancel one in favor of the other)
• check_code_ref rejects "file.rs#" (empty symbol) with a clear error
• check_code_ref rejects sources that resolve outside the repo root, including both ../-style relative traversal and a bare absolute path (Path::join replaces the base entirely for an absolute joined path — a distinct code path from relative traversal)
• Three new tests cover empty-symbol, relative-traversal, and absolute-path cases
• CONTRIBUTING.md invites any contributor to update platform schema TOMLs directly, without needing a dedicated owner
• docs/platforms/README.md documents both the URL-source decision and the semantic-drift known limitation

Follow-ups

• If semantic-drift incidents actually occur in practice, open a new issue at that point to discuss the solution in light of the concrete situation, rather than presupposing per-platform ownership is the right fix.

At a Glance

CI workflow + Rust test hardening + docs — no runtime/architecture impact

Prior Art & Industry Research

Not applicable — CI config, test hardening, and docs changes only; no runtime/architectural/delivery behavior affected.

Proposed Solution

#1337 (.github/workflows/platform-schema-conformance.yml):

• Added crates/openab-gateway/src/**, crates/openab-core/src/**, src/main.rs to both pull_request and push path triggers — confirmed these cover every .rs file currently cited by a schema code-ref (extracted all source refs across the 8 platform files)
• Added schedule: cron: "0 6 * * 1" (weekly) as a backstop in case a PR touching the source tree somehow bypasses the path triggers, paired with workflow_dispatch: so it can also be triggered manually (matches every other schedule-triggered workflow in this repo)

#1338 (same file):

• actions/checkout@v4 → @v6 (matches the rest of the repo's workflows)
• Add Swatinem/rust-cache (same pinned SHA used elsewhere in the repo) scoped to crates/platform-schema -> target
• Add concurrency: { group: platform-schema-${{ github.event_name }}-${{ github.ref }}, cancel-in-progress: true } — event_name is included because push and schedule runs both resolve github.ref to refs/heads/main; without it they'd share a group and could cancel each other
• --locked was already present from a prior change; left untouched

#1340 (crates/platform-schema/tests/conformance.rs):

• check_code_ref now canonicalizes both root and the resolved path and checks starts_with before proceeding, rejecting any source that escapes the repo root, whether via ../.. relative traversal or a bare absolute path (Path::join replaces the base entirely when the joined path is absolute — a distinct code path from relative traversal)
• check_code_ref now rejects an empty #symbol explicitly instead of silently passing (text.contains("") is always true in Rust)
• Three new tests: check_code_ref_rejects_empty_symbol, check_code_ref_rejects_path_traversal, check_code_ref_rejects_absolute_path

#1339 (CONTRIBUTING.md, docs/platforms/README.md):

• CONTRIBUTING.md: added a sentence inviting any contributor to update the schema TOML directly when they notice a platform API change or quirk, rather than waiting on a dedicated owner
• docs/platforms/README.md: added a "Known limitation" note under Conformance about semantic vs syntactic drift

Why this approach?

#1337/#1338/#1340 are straightforward hardening matching patterns already used elsewhere in this repo's CI (see ci.yml, docker-smoke-test.yml) and Rust code (canonicalize-and-check is the standard path-traversal guard). #1337's path list was derived by actually grepping every code-ref in the 8 schema files rather than guessing, to make sure the trigger coverage is complete as of today.

#1339: discussed with @sky092879 — two of the issue's three asks were already satisfied by existing docs (CONTRIBUTING.md:202, README's "Architecture: TOML vs Markdown" section). For the remaining ask, a formal per-platform ownership table was judged to add coordination overhead disproportionate to the current team size, with no clear enforcement mechanism. The underlying concern (stale docs) splits into syntactic drift — now handled by #1337's expanded triggers — and semantic drift, which has no automated solution and is now an explicit, revisit-if-needed limitation instead of an unaddressed gap.

Alternatives Considered

• Relax feature_sources_exist_in_tree to skip URL sources (issue fix(platform-schema): harden check_code_ref — reject empty symbols and path traversal #1340's third sub-point): considered, rejected for now. No current feature source is a URL (checked all 8 schema files, 136 entries), so this would be a preemptive change with no current benefit, and could let feature sources silently drift to unverifiable doc links instead of code. Documented as an explicit decision in docs/platforms/README.md; revisit if a feature genuinely needs a URL source.
• Non-blocking PR-comment bot reminding reviewers to check schema accuracy when adapter files change (for docs(platforms): assign page owners and establish maintenance guidelines #1339's semantic-drift gap): considered, deferred in favor of the lighter-weight CONTRIBUTING.md guidance + ci(platform-schema): expand conformance workflow path triggers to cover adapter source code #1337's CI trigger fix.
• Assign named per-platform owners (docs(platforms): assign page owners and establish maintenance guidelines #1339's original proposal): rejected for now — see rationale above.
• Remove the path filter entirely (ci(platform-schema): expand conformance workflow path triggers to cover adapter source code #1337's alternative, run conformance on every PR): rejected in favor of an explicit path list — the job is cheap either way, but an explicit list documents why it runs, and the weekly schedule already covers the "something slipped through" case.

Validation

Rust changes:

• cargo check passes — not verified in this environment (no Rust toolchain available); please verify in CI
• cargo test passes (including new tests) — not verified in this environment; please verify in CI
• cargo clippy clean — not verified in this environment; please verify in CI

CI/workflow changes:

• Workflow syntax reviewed by hand (no local actions/YAML linter available in this environment)

Docs-only changes:

• Links are valid
• Renders correctly in GitHub preview

All PRs:

• Manual testing — read through the diff and rendered Markdown; traced check_code_ref's new logic against the empty-symbol, relative-traversal, and absolute-path cases by hand, and cross-checked ci(platform-schema): expand conformance workflow path triggers to cover adapter source code #1337's new trigger paths against every code-ref actually cited in the 8 schema files, since cargo test could not be run locally.
• Independently reviewed by 4 focused passes (Rust correctness, CI/workflow correctness, docs consistency, security) before this revision — caught and fixed the concurrency group collision between push and schedule, the missing workflow_dispatch, and the missing absolute-path test case.

[chaodu-obk]

Note

LGTM ✅ - The CI hardening, code-ref validation, and platform-schema maintenance guidance are correctly scoped and covered by passing checks.

What This PR Does

This PR strengthens the platform-schema conformance workflow so code-reference drift is checked when its current target trees change, adds a scheduled backstop, and hardens code-ref validation against empty symbols and paths outside the repository. It also documents the current contribution and semantic-drift maintenance model.

How It Works

The workflow now watches the current code-ref target trees, runs weekly and on demand, uses the repository's checkout/cache conventions, and avoids cross-event cancellation. check_code_ref canonicalizes paths before containment checks, rejects an empty #symbol, and has regression coverage for empty-symbol, relative-traversal, and absolute-path inputs.

Findings

#	Severity	Finding	Location
F1	🟢	The trigger expansion covers every current Rust code-ref target directory, with a weekly backstop for future drift.	.github/workflows/platform-schema-conformance.yml
F2	🟢	The empty-symbol and path-containment guards close the documented conformance bypasses, with focused tests.	crates/platform-schema/tests/conformance.rs:168-220
F3	🟢	The contribution guidance and explicit semantic-drift limitation accurately document the current maintenance model.	CONTRIBUTING.md:203, docs/platforms/README.md:17-29

Finding Details

🟢 F1: Complete current trigger coverage

The local review extracted all current schema Rust code-ref files. Their target directories are contained by crates/openab-core/src/** and crates/openab-gateway/src/**; the retained src/main.rs trigger is harmless coverage. The weekly scheduled run provides the documented backstop if a future target tree is not added to the path list immediately.

🟢 F2: Robust code-ref validation

canonicalize plus starts_with rejects both relative traversal and absolute paths that escape the repository root. The empty-symbol guard prevents the Rust empty-pattern match from silently accepting file.rs#.

🟢 F3: Clear maintenance boundaries

The documentation distinguishes syntactic drift that CI can detect from semantic drift that requires review, while allowing contributors to make direct, scoped schema corrections.

Baseline Check

• PR opened: 2026-07-30
• Declared base: main at c5a75ac6e8fdc11a3b229a0c609769e90d261daf
• Merge base: 53061d696148106b2b7529f9d6c5dd802dff4545
• Reviewed head: 387dd9e3790231af2224a48ce5fe202cc82e54ce
• Diff: 4 files, +71/-2
• Net-new value: CI coverage for current code-ref target trees, scheduled anti-drift checking, stronger input validation, and documented maintenance boundaries.

What's Good (🟢)

• The cache action uses the same pinned revision and workspace scope as the established CI convention.
• The concurrency key includes github.event_name, preventing scheduled and push-to-main runs from cancelling one another.
• The test suite explicitly covers the two distinct path-escape forms: relative traversal and an absolute input.

Addressing External Reviewer Feedback

No external review comments or inline threads were present when this round began.

Reviewer Summary

Reviewer	Result
Reviewer A	LGTM: Rust correctness and containment behavior reviewed.
Reviewer B	LGTM: CI triggers, cache pinning, and concurrency reviewed.
Reviewer C	LGTM: Tests, documentation, and issue acceptance criteria reviewed.
Reviewer D	LGTM: Architecture and maintenance tradeoffs reviewed.

5. Three Reasons We Might Not Need This PR

1. The weekly schedule alone could catch drift - It would delay feedback and still allow unrelated work to surface the failure, so targeted PR-time triggers are preferable.
2. The schema remains small enough for manual maintenance - Manual review cannot reliably catch symbol renames or empty-reference typos, which this low-cost conformance check detects.
3. A formal ownership model could be introduced instead - The current open-contribution guidance avoids coordination overhead while retaining a documented semantic-drift limitation to revisit if it proves inadequate.

[chaodu-obk]

Note

LGTM ✅ - The review found no actionable regressions.

Consolidated review: #1462 (comment)

[feiyun968-agent]

PR Review — 司馬

Doc Issues

🟢 docs/platforms/README.md — Decision block
新增的 > **Decision:** blockquote 清楚說明 feature_sources_exist_in_tree 故意拒絕 URL sources，並附上 issue #1340 供追蹤。內容正確，無問題。

🟢 docs/platforms/README.md — Known limitation
Semantic drift 的 known limitation 描述準確，邊界清楚：CI 只能抓 syntactic drift，semantic drift 靠 PR review。無問題。

🟡 CONTRIBUTING.md — 新增段落位置略重疊
新段落插在兩段既有內容之間：

• 上文：「修改 adapter 時，更新對應的 .toml」
• 新增：「發現 API 變了或有新 quirk，直接更新 .toml，不需等 owner」
• 下文：「See docs/platforms/README.md for...」

兩段語氣與對象略有重疊，可考慮合併為一段或加小標，讓意圖更清晰。非 blocker。

🟢 Cross-doc consistency
CONTRIBUTING.md 與 docs/platforms/README.md 對 semantic drift 的描述互相對應，無矛盾。

Summary

項目	結果
Doc 內容正確性	✅
Doc 與 code 一致性	✅
Doc 彼此一致	✅
建議	🟡 CONTRIBUTING.md 兩段可考慮合併，非 blocker

整體：無 blocking doc issue。