`services.security` is documented nowhere under `content/docs/`, yet the runtime-services chapter advertises a canonical source for it

[os-steve]

Split out of #9604, which fixed the services.sms half of that card and was explicitly told not to guess the Security half. This card records the measurement so a maintainer can decide.

What was measured

#9604 asked which of three outcomes applies to the Security row in content/docs/kernel/runtime-services/index.mdx: the accessor is documented elsewhere (mis-filed row), documented nowhere (bigger gap), or internal and not meant to be public (drop the row). Measured against main at e8dba8a8a:

probe	result
grep -rn 'services\.security' content/docs/	0 hits
grep -rn 'contracts/security-service' content/docs/	1 hit — runtime-services/index.mdx:39, the row itself
security-service.mdx anywhere under content/docs/	does not exist
ISecurityService in content/docs/	kernel/contracts/index.mdx:44 (interface table) and a v17 release note
getService('security') in content/docs/	permissions/explain.mdx:53, spelled kernel.getService('security')

So the answer is outcome 2: documented nowhere. The slot is real and registered — packages/plugins/plugin-security/src/security-plugin.ts:1157 runs ctx.registerService('security', registeredSecurityService), and packages/spec/src/contracts/security-service.ts:18 names that registration in its own header — but no page in content/docs/ introduces the services.security accessor.

The two near-misses are worth naming because neither closes the gap:

• kernel/contracts/index.mdx documents the interface ISecurityService in the contracts chapter. That is the "what must an implementation provide" surface, not the "how do I call it" accessor surface the runtime-services chapter owns.
• permissions/explain.mdx shows kernel.getService('security') for one specific task (access explanation). It is a task recipe in another chapter, not an accessor reference.

Why this is larger than the row

The Source-of-Truth list states its own purpose: "Each page links the canonical TypeScript source used to derive signatures." For the Security row there is no page, so the sentence is false for that row — a reader following it lands on a contract file with nothing explaining the accessor. The chapter is advertising a canonical source for a service it never introduces.

Needs a maintainer decision

The three outcomes are mutually exclusive and only one is a docs edit:

• Give it a page — security-service.mdx in the chapter, plus meta.json, the chapter list and the kernel/index.mdx table. Correct if services.security is meant to be a public runtime accessor. Largest option; the contract is wide (getReadFilter, getReadableFields, canExport, checkAuthoredRowWrite, resolvePermissionSetNames, explain, ...).
• Move the row — cheapest, but the measurement above says there is no destination page documenting the accessor, so this is only viable together with deciding which chapter should own it (permissions/ is the nearest neighbour).
• Drop the row — right if the accessor is internal and callers are meant to reach security through permissions/ docs and kernel.getService rather than a documented services.* slot.

Which one is right depends on whether services.security is intended to be a documented runtime accessor at all. That is a product-surface call, not a docs cleanup.

Note on the gate

PR for #9604 adds pnpm check:runtime-services-index, which holds the chapter list, meta.json and the kernel/index.mdx table to the pages on disk. It deliberately leaves the Source-of-Truth list out of scope, precisely so it does not pre-judge this card — an allowlist entry for Security would be one of the three answers above, encoded in a gate. Once this is decided, extending that gate to the Source-of-Truth list is the natural follow-up and is a small change.

Refs: #9604 · #9588

[os-support-ai]

Triage: kept in the decision inbox (needs-user-decision, domain:devx); removed the contradictory finding label (a card cannot be both awaiting first grading and already classified as a decision). Four-prism block, since the card lacked one:

1. Platform long-term coherence — the Source-of-Truth list's own contract ("each page links the canonical source") is false for exactly one row; any of the three outcomes restores coherence, but only "drop the row" does it without deciding a new public surface.
2. Measured business pull — zero measured: 0 hits for services.security anywhere in content/docs/, and the one real usage shown to readers is the permissions/explain task recipe, which already works without an accessor page.
3. AI-agent error-resistance — a documented wide accessor (getReadFilter, checkAuthoredRowWrite, …) invites app-authoring agents to call the security service directly instead of going through the permission surfaces; keeping the accessor undocumented keeps the narrow path the obvious path.
4. Startup scope discipline — a full security-service.mdx page is a permanent doc-maintenance obligation for a wide, evolving contract with no reader demand today.

Recommendation: drop the row (outcome 3), and note in the row's removal commit that the interface surface stays documented in kernel/contracts/ and the task recipe in permissions/explain.mdx. Revisit a dedicated page on first real consumer pull. Extending check:runtime-services-index to the Source-of-Truth list is the natural rider once ruled.

---

Generated by Claude Code

[os-support-ai]

Maintainer ruling recorded (2026-08-18, live chat with the triage session session_014v3dpZ2224xgf98dfY4rw4; authorization verbatim: 「其他接受你的建议」, accepting the recommendation presented in that session, restated as the operative ruling).

Ruling: drop the row. services.security is ruled an internal accessor, not a publicly documented runtime accessor: the Security row leaves the runtime-services Source-of-Truth list, and no security-service.mdx page is created. Task-level usage stays where it is (permissions/explain.mdx teaching kernel.getService('security') for access explanation); the ISecurityService interface remains documented in the contracts chapter as the implementation surface. Rationale on record: the contract is wide (getReadFilter, canExport, explain, …) and publicly documenting the accessor is a permanent maintenance obligation inviting external dependence nothing pulls on today — if a plugin-ecosystem need materializes, it is promoted then, deliberately.

Follow-up in the same card: extend check:runtime-services-index to the Source-of-Truth list now that the answer exists (a row requires a page; the deliberate out-of-scope in #9604's gate is discharged by this ruling).

Label: needs-user-decision → pm:queue, type Task, domain:devx.

---

Generated by Claude Code