docs: mark IMetadataService interface fence as an excerpt, restore getDiagnosed/subscribe

[baozhoutao]

Clause-②: no

Closes #16255

What changed

content/docs/kernel/contracts/metadata-service.mdx's ## Interface Definition
fence was introduced as IMetadataService itself (export interface IMetadataService { … }
with grouping comments reading as a complete tour) while silently omitting 4 of the
38 members the contract source actually declares. Per the maintainer ruling on
#16255 (repair as an excerpt, not a mirror — no gate added in this card):

1. Reframed the fence as an explicit, non-exhaustive excerpt: added a sentence before
   the fence pointing at IMetadataService in packages/spec/src/contracts/metadata-service.ts
   as the authoritative, complete member list, plus an in-fence leading comment
   (// Excerpt — grouped by concern, not exhaustive. See packages/spec/src/contracts/metadata-service.ts for the full declaration.).
2. Restored getDiagnosed? and subscribe? — the two omissions that each
   contradict a subsection the page itself devotes to their pattern (### load / loadDiagnosed teaches the diagnosed-twin pattern right above a fence that,
   before this PR, implied get had no diagnosed counterpart; ## Watch / Subscribe is built on watch?, and the fence's own grouping comment says
   // Watch / subscribe (optional) while never declaring subscribe).
3. Left loadMany? and matchEndpoint? out of the excerpt (see "Members left out" below).

Fence-vs-source member diff (my own, independent of triage's/the PM's)

Method: extract the first ```typescript fence under ## Interface Definition
(3355 bytes / 57 lines after this PR; 3002 bytes / 54 lines before), then extract
member declaration lines only — lines at the interface body's own indent level
that open a declaration (name/name? followed by (, < or :) — explicitly
excluding // comment lines and multi-line signature continuation lines (e.g.
a wrapped Promise<...> return-type line, which a naive regex misreads as a
member named Promise). Same declaration-line rule applied to the
export interface IMetadataService { … } body in
packages/spec/src/contracts/metadata-service.ts (338–866), with block comments
stripped and only exactly-4-space-indented lines counted (so wrapped parameter
lines like type: string, at deeper indent are not misread as members either).

Before this PR:

source members: 38
fence members:  34
absent from fence: getDiagnosed, loadMany, matchEndpoint, subscribe
positive control (must be in fence, and are): loadDiagnosed, watch, get

This reproduces the PM's 2bafbfdca9 reading exactly (including the same
subscribe false-positive trap from the grouping comment // Watch / subscribe (optional), which my declaration-line filter also has to explicitly dodge since
a naive "name + paren" regex matches that comment line too).

After this PR: fence members = 36, {fence} - {source} = ∅, {source} - {fence} = {loadMany, matchEndpoint} (left out deliberately, see below).

Members restored / left out and why

• Restored: getDiagnosed?, subscribe? — per the ruling's ground 3: "an
  excerpt may omit members, but not the principal member of the pattern it is
  itself teaching." Both back a named subsection on this exact page.
• Left out: loadMany?, matchEndpoint? — neither has a subsection on this
  page building a pattern around it (no ## /### section is built on either
  name; matchEndpoint is dispatcher-internal per its own TSDoc, loadMany is
  the bulk-read counterpart to list with no dedicated teaching passage here).
  Omitting them from a fence that now explicitly calls itself a non-exhaustive
  excerpt and points at the full source does not reproduce the misleading
  inference the issue is about — there is no prose passage on this page a reader
  could hold up against their absence.

Excerpt wording

Added, right before the fence:

The excerpt below groups the interface's members by concern; it is not the
full declaration and is not held equal to it by any check. For the
authoritative, complete member list see IMetadataService in
packages/spec/src/contracts/metadata-service.ts.

And the fence's own first line:

// Excerpt — grouped by concern, not exhaustive. See packages/spec/src/contracts/metadata-service.ts for the full declaration.

Generated-page reading

content/docs/kernel/contracts/metadata-service.mdx is hand-written, not
generated: it is listed in scripts/docs-audit/handwritten-docs.json, and the
only generated docs tree in this repo is content/docs/references/**
(confirmed by turbo.json's per-task inputs and scripts/check-corpus-claim-drift.mjs's
own header). Hand-editing it is the correct path.

content/docs/** gate family (dispatch-gates §③)

node scripts/pm/dispatch-gates.mjs --commands (from merge-base
776d64cd3d) names 39 commands (26 pnpm, 13 direct node) plus 7
whole-tree-population families run identically on every card. After
pnpm install and building the packages these gates read compiled output
from (@objectstack/formula, @objectstack/lint, @objectstack/spec,
@objectstack/client-react, @objectstack/client — none of them touched by
this diff, needed only because a fresh worktree ships no dist/), all 39
pass (captured pre-pipe, EXIT=$? per command):

node scripts/check-ci-filter-parity.mjs                                    EXIT=0
node scripts/check-closing-keyword-parity.mjs                              EXIT=0
node scripts/check-closing-keyword-parity.mjs --self-test                  EXIT=0
node scripts/check-comment-mask-corpus.mjs                                 EXIT=0
node scripts/check-doc-frontmatter.mjs [+ --self-test]                     EXIT=0
node scripts/check-doc-route-spelling.mjs --advisory [+ --self-test]       EXIT=0
node scripts/check-docs-section-name.mjs [+ --self-test]                   EXIT=0
node scripts/check-section-landing-index.mjs [+ --self-test]               EXIT=0
node scripts/report-test-timings.mjs --self-test                           EXIT=0
pnpm --filter @objectstack/lint check:doc-formula-expressions              EXIT=0
pnpm --filter @objectstack/lint check:doc-security-posture                 EXIT=0
pnpm --filter @objectstack/spec check:docs                                 EXIT=0
pnpm --filter @objectstack/spec check:empty-state                         EXIT=0
pnpm --filter @objectstack/spec check:liveness                            EXIT=0
pnpm --filter @objectstack/spec check:skill-examples                      EXIT=0
pnpm --filter @objectstack/spec check:strictness-ledger                   EXIT=0
pnpm --filter @objectstack/spec check:variant-docs                        EXIT=0
pnpm --filter @objectstack/spec check:yaml-examples                       EXIT=0
pnpm check:corpus-claim-drift                                              EXIT=0
pnpm check:cross-package-test-inputs                                       EXIT=0
pnpm check:doc-anchors                                                     EXIT=0
pnpm check:doc-authoring                                                   EXIT=0
pnpm check:docs-audit-scope                                                EXIT=0
pnpm check:docs-redirects                                                  EXIT=0
pnpm check:docs-single-h1                                                  EXIT=0
pnpm check:docs-transcript-drift                                           EXIT=0
pnpm check:driver-memory-census                                            EXIT=0
pnpm check:nul-bytes                                                       EXIT=0
pnpm check:published-readme-links                                          EXIT=0
pnpm check:react-page-adapter-contract                                     EXIT=0
pnpm check:refd-timer-probe                                                EXIT=0
pnpm check:role-word                                                       EXIT=0
pnpm check:skill-identifier-liveness                                       EXIT=0
pnpm check:vendor-version-stamps                                           EXIT=0
pnpm check:watch-hint-literal                                              EXIT=0

(the --self-test companions of check-closing-keyword-parity, check-doc-frontmatter,
check-doc-route-spelling, check-docs-section-name, and check-section-landing-index
are listed inline above as [+ --self-test], each independently EXIT=0.)

The 48 artifact-roster families, the 11 checker-health-only --self-test
families and the 14 pending-changeset families that dispatch-gates also
prints are outside this scope by its own account (none of their rosters live
under a path this diff touches).

Build closure (①)

content/docs/** is not a workspace package, so this diff has no dependency
closure to build. Confirmed directly: pnpm exec turbo ls --affected --filter='...[origin/main]' (from HEAD a7a3b194b8) → 0 packages. (A bare
turbo ls --affected with no explicit base misreads this worktree's history
and reports the whole 80-package graph — the explicit-base form is the one
that answers the actual question and is what's quoted above.)

Changeset

skip-changeset (label applied on the PR, not just asserted here).
Measured, not assumed: apps/docs (which serves content/docs/**) is
"private": true, and none of the repo's 22 published packages' package.json
files[] arrays reference content/docs (grepped after building — zero hits).
Nothing this diff touches ships in any published tarball.

Serial / boundaries

• docs: the metadata-service contract page documents the SINGULAR read's failure posture but is silent on the plural reads' (list / listNames) — degrade vs refuse #16090 already landed on main (31baf09440, merged before I branched) —
  not in flight, no re-read needed beyond confirming it landed clean.
• MetadataManager.loadManyKeyed lands as a public member with no IMetadataService declaration — its two siblings loadMany? and loadDiagnosed? are declared, and the call site narrows with a local structural type instead #15385 remains open, domain:spec, unassigned, Blocked-by: #14423 — not in
  flight, untouched by this PR. loadManyKeyed is intentionally not added here;
  that is MetadataManager.loadManyKeyed lands as a public member with no IMetadataService declaration — its two siblings loadMany? and loadDiagnosed? are declared, and the call site narrows with a local structural type instead #15385's job in the spec lane.
• Only content/docs/kernel/contracts/metadata-service.mdx touched;
  packages/spec/** untouched.

---

Generated by Claude Code

[claude]

Fixed and re-pushed (no amend/force-push -- plain new commit on top).

• New head SHA: f4b3353
• MetadataWatchEvent read from packages/spec/src/system/metadata-persistence.zod.ts:300-307 (MetadataWatchEventSchema) and its type alias at line 369 (export type MetadataWatchEvent = z.input), NOT inferred from MetadataWatchCallback's row.
• Added one row to the existing Types Reference table (alongside MetadataWatchCallback / MetadataWatchHandle): subscribe's callback argument: { type: 'added' | 'changed' | 'deleted', path, name?, stats?, metadataType?, data?, timestamp? }
• New MetadataWatchEvent occurrence count on the page: 2 (the subscribe? signature line + the new table row).
• Re-ran the full content/docs/** gate family (39/39 dispatch-gates commands, including check:doc-anchors, check:doc-authoring, check:docs-single-h1) -- all EXIT=0.
• Scope respected: this file only, additions only, no mirror gate, loadMany/matchEndpoint still left out, Watch/Subscribe prose section untouched.
• PR left in draft.

---

Generated by Claude Code