feat(artifacts): add family-scoped search

[frf12]

Which issue or RFC does this PR close?

Implements RFC #1858 for Topic Memory, Experience, and Skill.

Rationale for this change

Callers need query-based relevance ordering before a result budget truncates useful Artifacts. Family-scoped search lets each Family own its parameters and retrieval policy without adding Family-specific branches to the HTTP route.

What changes are included in this PR?

• Add POST /v1/scopes/{scope_id}/artifacts/{family}/search, the Python client method, and generated operation contracts. Each request searches one Scope and Family, with a final-result limit and no pagination.

• Introduce typed ArtifactSearcher registration and a scoped runtime facade. Family-owned request models validate supported controls; trusted execution context travels separately from the request body.

• Integrate Topic Memory, Experience, and Skill with their existing retrieval implementations. Preserve legacy APIs, prepare behavior, injected callables, and Skill Library deprecated-result behavior.

• Provide Family-independent RRF with algorithm-scoped rank_constant and channel weights. Apply admission before fusion and normalized min_score before the final result limit. Preserve ranking and threshold decisions with subnormal weights using precise raw sums and exact-ratio normalization in the exceptional numeric path; ordinary float accumulation remains unchanged.

• Return complete exact-revision Artifacts. Optional include_scores adds normalized retrieval scores and actual signed BM25, MATCH, or L2 channel observations. Preserve Family JSON aliases and lineage.

• Add bilingual capability and fusion-parameter documentation, website navigation, and regression coverage.

• Authorize new and legacy Topic searches after query embedding against a short consistent data snapshot. Standard same-database Builtin/Casbin policies, candidates, complete content, and lineage use one connection. External or custom policies retain their point decisions against frozen business data. Preserve injected provider/repository rules and independent audit stores; flush decision audits after the read transaction closes.

• Keep the shared AccessControlService.with_connection behavior from before the Topic snapshot fix, preserving configured Casbin providers and their repositories. Topic search reauthorization remains in the read-specific require_scope_read path.

Desktop bindings are regenerated for this contract, preserving the original ten Legacy Memory operations. An additional explicitly qualified SQLite profile retains the old record; fixtures select the unique qualified profile matching the bundled contract. CLI diagnostics qualify the explicit 1.2.1 release/development series with existing path, digest and exact-version checks.

The usage-recorder writer-lock regression now gives its healthy recovery phase an independent test-only write budget and waits for settlement before asserting exactly one request. The locked-phase deadline and connection-restoration assertions are unchanged.

Atomic Memory integration is in #1882 and depends on #1857. This PR remains the independently deliverable three-Family implementation. RFC and detailed design files are not included.

Are there any user-facing changes?

The HTTP and Python search APIs are additive. Each Family documents its defaults, supported controls, deployment requirements, and limit. Unsupported Families or controls produce explicit errors. Scores use finite [0, 1] values without promising calibration across Families, algorithms, queries, or backends.

Existing business-specific interfaces retain their request/response formats and defaults. For both Topic search routes, revocation during query embedding is respected before reading results; writes after the authorized read snapshot cannot enter the response. External policy decisions are not claimed to share the SQL policy snapshot.

This PR introduces no storage migration or new MCP tool.

How was this change tested?

Reviewed commit: aa7150f4a74f0389fb1064d11ce51b42a93cb9f2.

Fresh verification on 2026-10-09 at 07:26 UTC reconfirmed this exact PR head: 27 required checks and 6 workflows successful, with only the optional installed-package dispatch job skipped. Applicable common fixes are synchronized into #1882 at c07d5524f41eacab2055a5e52507b257cd2c9997; its current checks also completed successfully.

The follow-up findings for Experience/Skill authorization snapshots, Desktop upgrade-profile instructions, and oversized lexical admission floors remain tracked in their existing threads. CI completion does not claim these findings are resolved.

The branch includes upstream master at aeeb735397f692df186c32b404f4245030db1f22 by normal merge for the newly enabled Desktop workflow.

Fresh GitHub verification on aa7150f4a74f0389fb1064d11ce51b42a93cb9f2 confirms all 27 required checks and all 6 workflows completed successfully, including Desktop Windows. The separate installed-package dispatch-only job is intentionally skipped; this is CI completion evidence, not a claim that every test parameter or installed-package scenario executed. #1862 has merged as 4ac4f898cb3d09a917115ef1e6e15aef27085c65. The previous Windows run 37891441706 / job 113693039472 at 347610aceeb6f5510e77a88e377a6393a651a020 passed generation/lint/type checks, all 25 UI tests, and UI build, then failed cargo fmt --manifest-path src-tauri/Cargo.toml --check. The formatter requested line wrapping in desktop/src-tauri/examples/server_probe.rs, desktop/src-tauri/tests/memory.rs, and desktop/src-tauri/tests/session.rs. Later native Windows checks and installed acceptance were not reached.

Current-commit formatting correction and independent coordinator verification:

• Rust 1.95.0 rustfmt formatted exactly those three files: 27 added / 6 removed lines, with non-whitespace source and quoted text unchanged. Qualification selection, ambiguity assertions, and business behavior are preserved.
• Direct rustfmt checks reproduced the original differences and passed after formatting, with all three file paths explicitly processed. The coordinator independently ran the fixed-toolchain Cargo formatter check; its nonempty log enumerates all 16 crate targets, including those three files, and records the actual rustfmt invocation. The earlier empty-log check is not used as evidence. The ordinary Cargo shim also exhibited a local metadata-startup error; that failed attempt is retained separately from the fixed-toolchain processed checks.
• The coordinator independently ran Memory and session suites: 7 + 4 = 11 passed, 0 failed, 0 ignored, 0 filtered. All 11 repository pre-commit checks and diff checks passed. These focused checks do not establish a full local suite pass or new Windows acceptance.

Historical Desktop integration verification at 347610aceeb6f5510e77a88e377a6393a651a020 (business behavior is unchanged by the formatting correction):

• The official Desktop generator reproduced the CI drift, then regenerated its three contract projections. The original ten operation bindings and Legacy response protocol remain intact; the HTTP source contract is unchanged by this Desktop correction.
• The old compatibility profile rejected the actual current Server at the strict contract gate. The new sqlite-legacy-58f7f4f6-v1 profile passed all four real built-wheel SQLite Server modes on macOS, including anonymous, Bearer, explicit-CA HTTPS/base path and injected-provider enforcement. Recorded source/contract/wheel identities match the actual report. The old qualification record is preserved. Profile selection does not attest a remote binary.
• Actual built-wheel version, service status and integration commands were exercised; their outputs passed two native Rust projection cases, retaining expected unhealthy status and assertions. These local runs did not exercise Windows registered-executable or installed-package acceptance. The final-head Desktop Windows CI is successful; the separate installed-package dispatch scenario was not executed.
• Desktop UI: 25 passed. Lint, type checking and production build passed.
• Selected macOS Rust suites reported 39 passed, 1 failed, 0 ignored, 0 filtered. The existing transport parent test failed its child-process success assertion in this host environment; an isolated run of that same child binary passed 1 case, 8 filtered and does not convert the original suite result to a full pass. The coordinator independently ran the affected library, diagnostics, Memory and session suites: 18 passed, 0 failed/ignored/filtered.
• All-target Clippy and IPC generation checks passed locally, with only the existing macOS dead_code allowed by the Clippy command. The earlier empty local formatter log did not establish formatting of the three new fixtures; the Windows failure and subsequent processed-check evidence are recorded above. No source lint suppression was added. The diagnostics regressions remain after all production items, covering the previously failed strict Windows lint rule.
• The two installed Python boundary files passed Ruff/format and type checking under the tested macOS/Linux/Windows configurations; those are static platform checks. Full repository pre-commit checks passed all 11 configured checks; commit hooks and diff checks passed. The committed diff equals the tested patch.
• After integrating upstream master, the coordinator independently ran recorder, authorization, Topic snapshot and database regressions: 119 passed, 0 failed, 0 skipped, 36 deselected. SQLite is real; the generic MySQL setup cases are simulated, and external backend parameters are deselected. Production search/authorization behavior is unchanged by the Desktop correction.

Historical recorder recovery verification at fb46118342640bf12ec6abfb021369dbcc08fff4:

• Python 3.11.13 and Python 3.12.7 each passed the complete recorder module: 27 passed, 0 failed, 0 skipped, 0 deselected. The coordinator independently repeated the Python 3.12 run with the same result.
• At that historical commit, the original Base locked phase, including its 0.25-second write, 0.3-second flush and 0.5-second elapsed-time boundary, was unchanged. Current source retains upstream test(runtime): stabilize usage lock deadline #1893's 0.25/0.3/2-second locked settlement boundaries after the normal master merge. Healthy recovery uses the same recorder, a single offer and a bounded settlement wait, then requires exactly one row with one request.
• Full repository pre-commit checks passed all 11 configured checks; commit hooks and git diff --check passed. This is a test-only change; production timeout defaults are unchanged.
• The common healthy-recovery correction is synchronized into feat(search): integrate Atomic Memory into artifact retrieval #1882 by a normal merge. The Atomic branch retains its upstream-defined locked phase.

Historical shared-method restoration verification at a0732e7e8bd5c21e3ae93157927ef7aee9c954c6: GitHub CI completed with 26 of 26 checks successful and all five workflow runs successful.

• Focused local authorization and read-snapshot regression on Python 3.12.7: 92 passed, 0 failed, 0 skipped, 36 deselected. The deselections exclude OceanBase/SeekDB parameters from this SQLite run.
• A new public authorization regression confirms that a custom Casbin repository can allow Scope reads while denying contribution, even when the canonical relationship store still grants contribution. It fails before the restoration and passes afterward. This is a service-level check using actual SQLite, not a complete Dream HTTP execution.
• Both Topic routes retain the post-embedding read check and consistent snapshot coverage, including custom-provider and independent-audit compatibility. The generic database cases include actual SQLite transactions and simulated MySQL setup; no new live SeekDB/OceanBase execution was performed for this restoration.
• uv run prek run -a: all repository checks passed, including global type checking. git diff --check passed.
• These focused checks are separate from GitHub CI and from the historical feature validation below. The full local suite and tox matrix were not rerun for this restoration.

Feature and scoring validation at b7c0e80e2b3864b36c66bf3e7548e11a58d56141:

• Independent affected fusion, Topic, runtime, and HTTP regression: 208 passed, 0 failed, 0 skipped, 0 deselected. The shared fusion suite includes common-weight scaling, threshold eligibility, ordering, mixed normal/subnormal weights, representable combined contributions, and rounding midpoints. Existing exact legacy Topic values, giant rank constants, and overflow cases pass.
• Actual SQLite HTTP replay reproduces the original P3 with baseline fusion at 1fcfe876: equal weights 1e-320 returned 1.0 and retained both results at min_score=0.999. The corrected fusion returns approximately 0.99193548 for both weights 1 and 1e-320, retaining neither result. Text mode requires no model call.
• A local pure-fusion microbenchmark with four channels and 1,000 candidates measured ordinary weights at approximately 1.69 ms baseline / 1.72 ms corrected. Extreme tiny weights require precise arithmetic and measured approximately 48–52 ms. This is a function benchmark, not a service latency claim.
• make contract-test: 49 passed, 0 failed, 0 skipped, 0 deselected, including Python and JavaScript generation checks.
• uv run prek run -a: all checks passed, including repository formatting/lint and global type checking; commit hooks also passed.

Authorization/read-snapshot backend verification used commit 1fcfe876 and original assertions with Python 3.14.7. The Topic read-snapshot implementation remains unchanged by the shared-method restoration:

Validation	Passed	Failed	Skipped	Deselected
SQLite HTTP compatibility/concurrency and generic DB snapshots	40	0	0	36
Real embedded SeekDB HTTP concurrency	18	0	0	50
Real OceanBase HTTP concurrency	18	0	0	50

These executions cover 76 unique cases, including all 54 core HTTP scenarios across three actual databases. Deselections choose the backend for each run. SeekDB used pylibseekdb 1.4.0.post1 / engine seekdb-v1.4.0.0; OceanBase reported OceanBase_CE-v4.3.5.6. Each OceanBase case used an isolated disposable database.

• The new HTTP regression covers both Topic routes, Builtin/Casbin, default/text/vector/hybrid retrieval, transient embedding fallback, revocation during embedding, and concurrent creation/revision after snapshot pinning. SQLite cases also cover AuthZEN point decisions and injected provider/repository, independent-audit, missing-relationship-management, and separate-policy-database compatibility.

Embedding uses a controlled local implementation. AuthZEN uses MockTransport, so those cases verify the adapter contract and local snapshot handling rather than a live PDP or model service. Those backend executions were performed on the stated base commit and do not establish current-head live-backend acceptance.

AI usage statement

Implemented with Codex subagents using GPT-6.1 Sol at ultra reasoning effort. The coordinating agent reviewed the source, requested regression fixes, and independently ran affected tests, contract checks, and repository commit checks. An additional read-only agent reviewed the authorization and compatibility boundaries.

[AlexStocks]

the github ci action failed.