feat(search): filter before ranking and expose citation handles

[drewstone]

Problem

A caller that needs only curated priors, empirical findings, profile records, or another page subset must currently rank the entire store and filter afterward. Excluded pages can therefore influence both the token and graph stages before disappearing.

Search results also make the stable page id reachable only through a nested object. A downstream tool shipped a citation field its agents could not populate because the rendered search hit omitted the only handle they had to copy.

Change

• Add SearchKnowledgeOptions with page-id, tag, kind, and caller predicate filters.
• Apply every filter before token ranking and graph reranking.
• Preserve the existing numeric-limit call form.
• Return KnowledgeSearchHit, which carries citationId at the top level and defines it as exactly page.id.
• Fail loudly on negative or fractional limits instead of giving JavaScript slice semantics accidental API meaning.

An explicit empty filter matches no pages; omission means no restriction.

Tests

The added suite proves:

• the numeric overload remains usable;
• citationId === page.id;
• kind and tag filters run before normalization and ranking;
• ids and a caller predicate compose;
• empty filters are exact;
• malformed limits are refused.

This closes the retrieval and result-identity gap identified by Discovery's package-adoption audit without adding an opaque ranker or research policy.

[tangletools]

✅ Auto-approved drewstone PR — c61178c5

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

This approval is provisional. It rests on the audit running. If the audit cannot run — for example the CLI bridge rejects it — this approval is dismissed rather than left standing, so an unrun check never reads as a passing one.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-17T01:39:24Z}

[tangletools]

✅ Auto-approved drewstone PR — be64fd11

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

This approval is provisional. It rests on the audit running. If the audit cannot run — for example the CLI bridge rejects it — this approval is dismissed rather than left standing, so an unrun check never reads as a passing one.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-17T01:57:43Z}