Repository navigation
docs: record approved index-query package and hygiene boundaries #911
Description
Context
Part of #56; required documentation deliverable from #696. The maintainer selected A, a lazy optional core peer, on 2026-10-03 (ruling, comparison), then A, core-supplied root-bound ctx.queries, on the same date (ruling, comparison). Both choices are settled. Record these binding boundaries before #696 completes and #697/#699 implement them.
Read docs/decisions/index-query-api.md, docs/plans/index-query-api.md, docs/content-index-queries.md, #343 Q7 and #697/#699/#534/#537. Query APIs are delivered in #695/#755 and pi readers in #698/#760; direct-SQL guarantees remain until #701. Source reviewed at 1d1fcc72a7e06352e8b5ee020b3910864babc5db: ("./queries", packages/core/package.json:45-49); ("dependencies", packages/ui-server/package.json:56-69); ("peerDependencies", packages/ui-server/package.json:70-74); ("@schlessera/brain-ui-server", tests/allowed-edges.ts:92-95); (HygieneContext, packages/core/src/lib/module-types.ts:12-17); (checkOpportunityStages, packages/module-jobs/src/pipeline.ts:151-170). Reverify every citation in the working checkout.
Scope
Reconcile the existing index-query decision record and plan's package/context sections with both selected branches and their rationale, viable alternatives, absence/failure behavior, reachable types, migration conditions and verification handoffs. Keep record/index links consistent. This documents already approved policy; no fresh architecture selection is needed.
Out of scope
No package/edge-table/API/runtime implementation, query seam/service, SQL retirement, publishing, release schedule or immediate 1.0 freeze. Do not reopen the selected choices or claim runtime completion, installation-size/latency measurements or migration delivery. No progress log in repository documents.
Acceptance criteria
- The durable decision/design selects core's supported query subpath through a lazy optional peer with both peer declaration and optional metadata. Hosts explicitly install compatible core for graph/index vocabulary; unrelated standalone features boot without it. Functions resolve/cache once per app; native snapshots/connections remain core-owned per operation with normal conditional exports and an acyclic edge.
- Record actual imported package/subpath identity, source-backed compatible range and required-operation checks; distinguish package absence/skew from index absence/skew. Unusable core produces sanitized unavailable graph capability and unavailable/degraded index vocabulary, preserving pronunciation overrides and providers independent of keyterms, without successfully persisting degradation. Preserve established index-specific mappings with usable core. No SQL/PATH-CLI/per-query-process fallback.
- Record retained
HygieneContext<C>.rootand parsedconfig: C, replacing raw db with core-created bound queries. List the nine existing methods and supported options/results with only callerbrainPathomitted. The captured root is authoritative against JavaScript/unsafe inputs and later context-root mutation. No persistent native handle, callback-wide transaction, consumer-supplied provider or SQL escape; failures stay typed and callbacks retain awaited sync/async failure reporting. - Record approved raw-db removal when core: replace module hygiene raw database exposure with query results #699 migrates every callback/fixture/author guide together. Preserve complete deterministic jobs selection, null-status exclusion and former asymmetric path/case semantics: exact root
status.md, nested%/status.mdincluding ASCII uppercase variants, root uppercase and near-name exclusion. Complete metadata plus module-owned predicate is required; no cap or unsafe literal-suffix narrowing. Frontmatter/stage/taxonomy and separate jobs operational storage remain unchanged. - Explain package installation and context calling-convention migrations under the pre-1.0 breaking process in ui-server: move graph and voice reads onto supported core query results #697/core: replace module hygiene raw database exposure with query results #699: prior rulings,
breaking,CONTRACT:, same-commit contract/author migration docs and minor changesets naming the breaks; from 1.0 breaks need majors. Do not invent a version/range/release date. Further unapproved machine behavior breaks still require their own ruling. - Explain the rejected viable alternatives: a hard dependency simplifies automatic setup but installs/couples core for every server consumer; explicit module query imports preserve a smaller context but repeat root wiring. Root-bound context was selected to centralize binding and ergonomics, with additional method/type surface and required binding proof. Distinguish policy approval from current source and prototype evidence.
- Reconcile packages: curate public exports and align the 1.0 stability contract #534/core: define the module-authoring stability contract for 1.0 #537's public/module-author inventories with all signature-reachable query option/result types. Hand off normal packed install/source/default/types/standalone-declaration/skew/real-route checks to ui-server: move graph and voice reads onto supported core query results #697/core: guard supported index queries across actual package consumers #700 and real-loader/CLI-index/nonempty selection/config/root/unsafe-input/index-failure/mutation checks to core: replace module hygiene raw database exposure with query results #699. Preserve direct-SQL promises until docs: retire direct brain.db SQL guarantees after query migration #701; no implementation AC becomes complete merely because this document lands.
- Remove obsolete unapproved recommendation wording for both settled branches, repair stale named source citations and keep links consistent. Documentation/citation/leakage checks pass; core: settle index-query package access and module context replacement #696 can link the merged record/design and complete its reconciliation.
Verification
Compare record/design against both dated rulings and affected issue bodies. Verify current source anchors and run relevant documentation, decision-citation and leakage checks. Runtime/packed-install/mutation/performance proof belongs to implementation follow-ups; no paid/network inference is required for this record.
Contract impact
Documentation-only architecture record: no current package signature/schema/runtime change or changeset. #697 owns the approved peer-install migration; #699 owns approved raw-db removal and calling convention. SQL promise retirement remains #701; module/public 1.0 stabilization remains #537/#534.
Completion — 2026-10-04
All documentation criteria are delivered by #936, squash 10d435675c7eff19afbfb75a432a14809c162f55, verified on remote main. Both indexed records select the approved optional peer and root-bound context, preserve complete jobs/path/null semantics and all nine operations/fifteen reachable types, and retain implementation/migration/SQL-retirement obligations. All cited ranges were opened through their ends; the moved auditor callback citation is corrected to 1053–1062 in both files. Fresh documentation/citation/path/public-content/leakage checks pass 123 tests / 214 assertions; lint and whitespace pass. Primary npm/Bun optional-peer behavior was rechecked. All fourteen checks pass on head 8e2799b1afd150c104e18f3f81e750e475ac0a43. Tested merge c5c457cd3f68de9c90678bbe7709c55fc7c659af has base dbea4f5173d8cac526f70e84376c67f0c11b58e5, that head and tree 2a1173dd43042cf1f7e0e8ca040b8c9e8362dc86. Older #853/#955 failures are historical. #696 can complete tracker reconciliation; implementation, SQL retirement and eventual stabilization are not claimed.
Activity
[-]docs: record the optional core peer for index queries[/-][+]docs: record approved index-query package and hygiene boundaries[/+]schlessera commentedon Oct 3, 2026
Claiming #911 to reconcile the index-query decision and design with the two approved package/context boundaries, verify source citations, and record implementation verification handoffs. Claim token:
01a1021b-911; intended branch:docs/911-index-query-boundaries-01a1021b.schlessera commentedon Oct 3, 2026
2026-10-03 blocked handoff: the four-file durable record/design/index reconciliation is preserved in draft PR #936, head
c4a059e86428f4134faf10812803adda06ebdb77. Both approved #696 choices, viable alternatives, nine methods/all 15 exported reachable types, authoritative root binding, exact jobs selection, absence/skew and pre-1.0 migration/verification obligations are recorded. Prior unresolved advice is historical, the stale allowed-edge citation is corrected, and the shipped standalone API remains the signature reference. Local checks pass: 123 documentation tests / 214 assertions, typecheck, lint and whitespace checks; all 44 source citations were inspected through their range ends. No runtime, manifest, machine contract or release changes.Exact-head CI finished with 10/11 jobs passing, and the separate contract check passed. The only failure is test shard 3:
runtime without admission plumbing refuses nonempty work before dispatch, atpackages/ui-server/tests/inbox-budget.test.ts:377, expected ready/attempts 0 but observed expired/attempts 0. Fixture expiry is1790942400000; runtime wall-time update is1791056666660. That shard reports 3,241 passes, 17 skips and one failure. These test/runtime files are unchanged from main; #927 owns the deterministic-clock repair. All other jobs, both browser shards, package smoke and captures pass.Resume after #927 merges: refresh this PR from main, rerun affected documentation/citation/leakage/type/lint checks and all required checks for the resulting exact head, review fresh comments, then make the completed PR ready with
Closes #911and merge using the verified SHA. Confirm the squash on main and actual issue closure. Only then may #696 link the delivered record and finish its tracker/dependant reconciliation. #697/#699/#700/#534/#537/#701 retain their implementation requirements; direct-SQL guarantees are not retired. #696 also records the current #343 Q7 summary correction for its existing reconciliation scope.The claim is released; the fully scoped issue retains agent-ready under the declared dependency. No CI gate was bypassed or unchanged run retried.
schlessera commentedon Oct 3, 2026
Unblocked: #927 is closed, so
scripts/sync-project.tsis removing theblockedlabel.schlessera commentedon Oct 4, 2026
Resuming #911 after the verified #927 repair. This session owns draft PR #936 and will refresh the documentation against main, compare it with both approved #696 rulings and current follow-up scopes, verify source citations and all required checks, then merge or record a precise handoff. Claim token:
01a1021b-911-resume-20261004; branch:docs/911-index-query-boundaries-01a1021b.schlessera commentedon Oct 4, 2026
2026-10-04 blocked handoff: the approved query-boundary record/design remains in draft PR #936, refreshed signed head
1f185a10830719aa113cb7facf38de3d26d27c02. The record/design are byte-identical to the prior implementation; indexes retain current-main additions. Both #696 rulings and affected implementation scopes were rechecked. Local checks pass 123 documentation tests / 214 assertions, all sixteen builds, typecheck, lint and whitespace. All 48 anchored references across 28 unique ranges were inspected through their range ends; nine operations and all fifteen exported reachable types match current source. npm/Bun optional-peer policy was reverified against primary documentation. This four-file documentation patch changes no runtime, manifest, machine contract or release; implementation/mutation/performance proof remains with the follow-ups.Current-head CI 37164203849, attempt 1 finishes 10/11 green. Test shards pass 2,980 / 3,077 / 3,293 (9,350 total, zero failures; 45 expected skips). Browser shard 2 passes 1,080 tests. Packaging, typecheck, leakage, captures, changeset and runtime checks pass; the actual retained SDK 0.3.283 / CLI 2.1.283 report passes twelve permission cases and five credential rows. The separate current-head contract check passes.
The sole failing browser shard 1 job 111323679542 reports 762 pass / two fail, 764 tests in 87 files, 165.06s. These failures are distinct:
await expect.poll,packages/ui-kit/tests/visual/module-settings.visual.tsx:111-111). Received text contains Settings/tabs and Appearance/Input controls without Configure Jobs. The matcher did not succeed in time; this is not a whole-test deadline or a later edit assertion.test(,packages/ui-kit/tests/visual/module-settings.visual.tsx:77-79). This log does not locate its waiting phase or establish a shared internal scheduling cause.Both light cases and all 54 subjects pass. Actual checkout
a7774e91babc0c91010a76fabc59b46a3b4a0c83has parents main1c8716a5741cb8864bdfe02f3a96c910ea504753and this head; tree34a6b0dc0075f6b824257873cf6f734cacfe9372matches the authored head. All UI/browser source, fixtures, configuration, wrapper, workflow and frozen-lock bytes are unchanged from the base. No retry, scheduling repair, changed assertion/deadline/baseline or gate bypass was used.Resume: resolve #955's controlled first-section readiness scope and #853's separate scheduling/prerequisite/full-matrix/shard scope; refresh #936, verify affected docs/citations/types/leakage and passing required checks for the resulting exact head, review fresh comments, then make the completed PR ready with
Closes #911and merge using that head. Prove its squash on main and actual closure. Preserve #881's ownership and #867/#878 prerequisites. #911 stays open with #936 draft; this invocation releases its claim. The prior #927 clock dependency is resolved and retained in comment history.#696 keeps its #911 dependency until record delivery, then completes its own reconciliation, including the previously recorded obsolete #343 Q7 summary. #697/#699/#700/#534/#537/#701 retain their implementation criteria; no runtime migration, SQL retirement, immediate 1.0 freeze or publication is claimed.