feat(spec,metadata-protocol): a page hit kind on GET /api/v1/search — command palette indexes published pages

[claude]

Part of #13216

Direction 3 only — command-palette indexing of published pages, per the 2026-08-29 maintainer ruling (directions 1 + 3 adopted; verbatim 「同意」) and the 22:36Z retriage settlement anchoring this remaining direction to the domain:spec lane. Direction 1 landed separately in PR #13372 (d23dc08a0f, content-verified on origin/main); the two were deliberately split so each published-contract change gets its own contract review. Direction 2 (nav registration at publish time) stays deferred to design card #13620 — #13620 remains open, app.allowOrgOverride is untouched here, and no new authorization surface is added.

Clause-②: yes — both limbs:

• path: packages/spec/src/** (api/protocol.zod.ts, plus the pin-test ledger and regenerated artifacts).
• content: widening the published GET /api/v1/search response shape — a new hit kind on an already-published body.

⛔ This PR parks in draft with needs:contract-review hung at creation (director note of 2026-08-31 00:42Z: the label re-attaches the moment a reviewable increment exists). Not to be flipped ready, queued, or armed by any seat — landing belongs to the contract-review chain.

What changed

A custom React page created and published at runtime renders perfectly and was absent from the ⌘K palette door alone (#13100's measurement; the card's direction 3): searchAll swept object records and nothing else. This PR adds a page hit kind to the published /api/v1/search response and wires published pages into the same producer:

• packages/spec/src/api/protocol.zod.ts — new SearchAllPageHitSchema ({ kind: 'page', name, title, snippet?, pageType? }); SearchAllResponseSchema gains a required pages array; blank-query short-circuit documented as carrying pages: [].
• packages/metadata-protocol/src/protocol.ts — searchAll sweeps published pages through getMetaItems({ type: 'page' }) on unscoped sweeps, after the record loop; shared excerpt helper (cutExcerpt) now produces both record and page snippets; org scope threaded through organizationIdForMetaRead('page', context.tenantId).
• packages/rest/src/rest-route-ledger.ts — the search row's note records the widened body. No REST handler change: the route relays the producer's return bare, exactly as before (pinned by the relay conformance test), and no request parameter is added (GLOBAL_SEARCH_PARAMS untouched).
• packages/client/src/index.ts — docblock only: the relayed shape now names pages. The SDK's return type flows from SearchAllResponse and needed no code change.
• Regenerated spec artifacts: api-surface/, export-origins/, declaration-map/, json-schema.manifest/api.json, authorable-surface/api.json, content/docs/references/**, strictness-ledger counts — all produced by check:generated --fix after a full spec build, only the proved-stale set.
• .changeset/search-published-pages-hit-kind.md — spec minor, metadata-protocol minor (reasoning below).

Derived judgments (each declared, none assumed)

1. Hit-kind shape — a SIBLING pages array, not new members of hits. Every hits element is a record with an object/id address; an existing consumer iterating hits must not receive an element whose address vocabulary it predates (a palette client today builds /{object}/{id} links from it). Page hits live in their own array, and each carries kind: 'page' as a self-describing discriminant for clients that flatten both arrays into one palette list. Record hits are byte-identical to before — no kind was added to them, deliberately, to keep the existing produced bytes untouched.
2. pages is REQUIRED, not optional. The schema is "declared AS PRODUCED" (maintainer ruling 2026-08-25 on the Four client SDK routes answer a shape no published contract declares — automation.create / automation.update / search / data.clone #11924 declaration), and the producer now always emits the member ([] included, blank-query short-circuit included). The producer-side and relay-side conformance tests both parse the real bodies. Version-skew note: the SDK does not runtime-parse responses (unwrapResponse is a cast), so a new client against an older server degrades to undefined exactly as any additive field does.
3. Visibility filter — the swept set IS the served set (zero new authorization surface). Pages reach the sweep through getMetaItems({ type: 'page' }) — the same verb the REST GET /meta/page list door serves, behind the same enforceAuth gate the search route already had. Published (state: 'active') items only — drafts surface exclusively under previewDrafts, never passed; disabled-package withholding and stored-row conversions ride along. Org scope goes through organizationIdForMetaRead — the registry-gated predicate every REST meta read door uses (Org-overridable metadata (view, dashboard) is accepted with a 200 state:'active' receipt but served by no read door #9454), so sweep and read door move together if page ever declares org override. A page hit therefore surfaces to a caller exactly what that caller's own meta read door already answers (name, label, description) — never more. page.assignedProfiles was measured to have zero backend read-door consumers on this tree (its enforcement lives at page render, client-side); following direction 1's delegation precedent, opening a hit goes through the existing page routes/renderer where that audience gate applies unchanged — adding a server-side profile filter here would have been a NEW enforcement surface, the very thing the ruling's basis excludes. Search is not a second read door and bypasses nothing.
4. Scoped sweeps skip pages. ?objects=lead asks for records of those objects; answering pages there would widen a request the caller deliberately narrowed. Pinned, including "the page read never ran".
5. Caps and ordering. Page hits cap at perObject (the page store is one more scanned container, not a competitor for limit); order is the served listing's order. No new totals member — totalObjects/totalHits/truncated keep their record-only meaning (their describes were already literal about that and stay true).
6. Term semantics. AND of terms, OR of fields (name + every locale value of label/description), case-folded — the record sweep's semantics restated for metadata, because pages are not engine rows and there is no $search expansion to delegate to. Matching uses the full term list (allTerms), not the 8-term snippet cap, so a 9th term cannot silently widen page recall relative to record recall. i18n label maps match on every locale value (a zh-CN query hits a zh-CN label); titles resolve through the shared resolveI18nLabel chain (spec: 后端第一个 I18nLabel → string 共享解析器 —— #6761 裁决 B 的契约半边(须与 objectui pickLocalized 同规则,否则同一个 map 两端渲染不同) #6765) — no fourth hand-rolled label resolution.
7. Failure semantics. A failed page read PROPAGATES (Measured set: five read seams answer a failed read from an empty accumulator with no log and no field saying the answer is incomplete #8896's rule one seam over): getMetaItems already discriminates the benign store-unprovisioned case and raises real outages as 503, so the sweep adds no catch — pinned (rejects.toMatchObject({ status: 503 })), a partial scan must not wear a whole one's answer.
8. Semver. spec minor (published response shape widened — additive, nothing previously valid becomes invalid; not breaking, so no ADR-0087 disposition marker is owed), metadata-protocol minor (new capability on searchAll). rest and client carry no changeset: rest has zero behavior change in-package (ledger note is prose), client is docblock-only.
9. Surface boundary. packages/objectql/src/search-companion.ts — named in the retriage's predicted surface — is deliberately untouched, and the re-derivation is recorded here as the flag the dispatch asked for: that module is the pinyin companion column for record columns; the page sweep matches metadata documents and never composes a $search filter, so no seam there is on this change's path. Pinyin recall for page labels would require materializing normalized forms for metadata — out of this card's scope and not part of the ruling. skills/** untouched (no generator fired — ListViewSchema unchanged, check:react-blocks green); docs/adr/**, .claude/**, AGENTS.md, CLAUDE.md, content/docs/releases/** untouched.
10. Fixture updates. The searchAll engine doubles in five existing test files gained the surface the pipeline now reads (registry.listItems, an honest empty sys_metadata answer) — each annotated in place. Two whole-body toEqual pins were inverted in place with the reason (pages: [] joined the body); nothing was skipped, disabled, or quarantined.

Verification

• New behavior suite packages/metadata-protocol/src/protocol.search-published-pages.test.ts (12 tests): published-page surfacing with the declared shape · draft rows do NOT surface (with discriminating control) · disabled-package pages do NOT surface (with control) · record hits untouched beside page hits · scoped sweep skips the page read entirely · blank-q short-circuit · AND-of-terms across fields · i18n label matching + shared title resolution · conditional snippet with record-identical excerpt geometry · perObject cap (and limit non-interference) · 503 propagation · swept-set ⊆ served-set parity.
• Producer conformance (search-clone-schema-conformance.test.ts) extended: pages parsed as produced, page-hit key-subset check, both snippet branches, widened short-circuit. Relay conformance (packages/rest) extended: the widened body relays bare through the real mount.
• Reverse verification from a downstream consumer against the rebuilt .d.ts (probe files in packages/client, removed after): accept probe (body with a page hit) compiles; reject probes red with tsc's own lines — TS2741: Property 'pages' is missing … but required and TS2322: Type '"pagey"' is not assignable to type '"page"' — so the shape widened and did not degrade.
• Full-package tests + typechecks for spec / metadata-protocol / rest / objectql / client, the dispatch's gate list, and the post-merge union: readings in the os-dev-report comment on [feature] Give runtime-published custom pages an end-user entry point: a page view type on objects, or nav registration at publish time #13216.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/client, @objectstack/metadata-protocol, @objectstack/rest, @objectstack/spec, touching 8 documentable anchor(s). ⚠️ 5 changed file(s) yielded no anchor (packages/spec/api-surface/api.json, packages/spec/authorable-surface/api.json, packages/spec/declaration-map/api.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

9 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/client-sdk.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/api/environment-routing.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/api/wire-format.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/concepts/metadata-lifecycle.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class))
• content/docs/kernel/runtime-services/data-service.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/kernel/runtime-services/storage-service.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/permissions/authentication.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/plugins/packages.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/protocol/kernel/realtime-protocol.mdx (via ObjectStackClient (symbol, a top-level class))

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

• content/docs/releases/v16.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class))
• content/docs/releases/v17.mdx (via ObjectStackClient (symbol, a top-level class), ObjectStackProtocolImplementation (symbol, a top-level class), searchAll (symbol, a method of class ObjectStackProtocolImplementation))

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

• 5 changed file(s) yielded no anchor (packages/spec/api-surface/api.json, packages/spec/authorable-surface/api.json, packages/spec/declaration-map/api.json, …) — pages documenting those are invisible to this run
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

Coarse fallback — 133 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 74a32a2edd55f06158effef71b9151f2f2eec36a → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 9423bce2bd2f120671f2f7a1db447f8d853c1acb — the merge of head 88eee836dd3f4be415e45401cd1116345e0e0e66 into base 74a32a2edd55f06158effef71b9151f2f2eec36a, 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 9423bce2bd2f120671f2f7a1db447f8d853c1acb && git checkout 9423bce2bd2f120671f2f7a1db447f8d853c1acb
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 74a32a2edd55f06158effef71b9151f2f2eec36a 88eee836dd3f4be415e45401cd1116345e0e0e66 && git checkout -B drift-repro 74a32a2edd55f06158effef71b9151f2f2eec36a && git merge --no-ff 88eee836dd3f4be415e45401cd1116345e0e0e66

node scripts/docs-audit/affected-docs.mjs --json 74a32a2edd55f06158effef71b9151f2f2eec36a

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