@deepwatch/dsh-library 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oxbshw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @deepwatch/dsh-library
+
+Library — sources, revisions, index state, search, facets and collections
+
+Part of **DeepWatch** — the agent workspace built on the official
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+and powered by [Watch Skill](https://github.com/oxbshw/watch-skill) for perception, evidence, memory and
+independent verification.
+
+> **Host plugin — runs beside the agent in the DSH process.**
+> Composed by the bundle.
+
+## Exports
+
+- `@deepwatch/dsh-library`
+- `@deepwatch/dsh-library/client`
+- `@deepwatch/dsh-library/components`
+- `@deepwatch/dsh-library/index-store`
+- `@deepwatch/dsh-library/library-mode`
+- `@deepwatch/dsh-library/read-plane`
+- `@deepwatch/dsh-library/search-view`
+
+## Peers
+
+Provided by the host rather than installed here:
+
+- `@deepseek-ai/cordis@4.0.2`
+- `@deepseek-ai/dsh-typert-protocol@0.1.1-rc.2`
+- `react@^18.2.0`
+
+## Install
+
+> **Not on npm yet.** Nothing exists under the `@deepwatch` scope. This
+> package is published for the first time by the `deepwatch-v0.1.0`
+> release; until then the command below resolves nothing, and
+> [the workspace README](https://github.com/oxbshw/watch-skill/tree/main/workspace#readme) has the path
+> that works from a checkout.
+
+```sh
+npm install @deepwatch/dsh-library
+```
+
+Rarely on its own. [`@deepwatch/dsh-bundle`](https://github.com/oxbshw/watch-skill/tree/main/workspace/packages/watch/bundle#readme)
+composes this package with the rest of DeepWatch and is what a profile
+normally depends on; installing this one directly is for embedding a
+single piece in a composition you control.
+
+## Requirements
+
+- Node `^22.19.0 || >=24.0.0`
+- The peers above, supplied by the host composition
+
+A Bridge connected to Core, and `libraryRoots` naming the directories the index may read — empty by default, so a deployment that has not said where its evidence lives gets a tool reporting nothing to search rather than one guessing.
+
+## Stability
+
+`0.1.0` — a stable release.
+
+Stable means tested, documented and supported — not 1.0. This is a
+pre-1.0 line, and semantic versioning gives `0.x` no compatibility
+guarantee across minor versions: **a `0.MINOR` bump may change or remove
+surface, and a patch will not.** Depend on it with a tilde range
+(`~0.1.0`) if you want that difference enforced by your lockfile
+rather than by a changelog. The usual major-version promise starts at 1.0.
+
+## Side effects
+
+Importing a module from this package evaluates no side effects, so a
+bundler may drop what a build does not use. Mounting it in a host is a
+separate matter: what it then reads or writes is governed by the
+workspace boundary and the host's permissions, not by this flag.
+
+## Where this fits
+
+The catalogue behind the Library screen: sources, revisions, index state, search, facets and collections.
+
+The twenty packages and how they compose:
+[the package map](https://github.com/oxbshw/watch-skill/blob/main/workspace/docs/packages.md).
+Running DeepWatch, and the gates a change has to pass:
+[the workspace README](https://github.com/oxbshw/watch-skill/tree/main/workspace#readme).
+
+## Attribution
+
+Built on DeepSeek Harness · Powered by Watch Skill
+
+DeepWatch and Watch Skill are independent projects and are not affiliated
+with or endorsed by DeepSeek. MIT licensed; third-party notices are in
+[THIRD_PARTY_NOTICES.md](https://github.com/oxbshw/watch-skill/blob/main/workspace/THIRD_PARTY_NOTICES.md).

package/lib/client/components.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The Library surface.
+ *
+ * Visually and structurally separate from Memory, and that separation is
+ * enforced rather than encouraged: this module imports nothing from the memory
+ * packages, so a memory record cannot be rendered here even by mistake. The
+ * two surfaces answer different questions — what has been seen, and what is
+ * believed — and a person needs to be able to tell at a glance which one they
+ * are looking at.
+ *
+ * Every result says how it was found and whether it is still current. A search
+ * result that showed neither would be a list of claims about a library whose
+ * state the reader cannot check.
+ *
+ * @module @deepwatch/dsh-library/components
+ */
+import type { ReactNode } from 'react';
+import type { Freshness } from '@deepwatch/dsh-contracts';
+import { type Source, type SourceRevision } from '../sources.js';
+import { type Facets, type SearchHit, type SearchPlan, type SearchResult } from '../search.js';
+/** Props for {@link FreshnessBadge}. */
+export interface FreshnessBadgeProps {
+    readonly freshness: Freshness;
+}
+/** Freshness as glyph, word and tone. */
+export declare function FreshnessBadge({ freshness }: FreshnessBadgeProps): ReactNode;
+/** Props for {@link RevisionHistory}. */
+export interface RevisionHistoryProps {
+    readonly source: Source;
+    readonly onOpen: (revision: SourceRevision) => void;
+}
+/**
+ * A source's revisions, newest last.
+ *
+ * Every revision is listed, including superseded ones, and every one is
+ * openable. A history that showed only the current revision would make old
+ * evidence unreachable through the interface even though it remains
+ * addressable underneath, which is the same failure with extra steps.
+ */
+export declare function RevisionHistory({ source, onOpen }: RevisionHistoryProps): ReactNode;
+/** Props for {@link SearchHitRow}. */
+export interface SearchHitRowProps {
+    readonly hit: SearchHit;
+    readonly freshness: Freshness;
+    readonly onOpen: (hit: SearchHit) => void;
+}
+/**
+ * One hit.
+ *
+ * The retrieval path is on the row, not in a legend. A person reading a
+ * semantic hit needs to know it is a semantic hit at the moment they read it,
+ * because that is what decides whether they should check it.
+ */
+export declare function SearchHitRow({ hit, freshness, onOpen }: SearchHitRowProps): ReactNode;
+/** Props for {@link FacetPanel}. */
+export interface FacetPanelProps {
+    readonly facets: Facets;
+    readonly onFilter: (facet: string, value: string) => void;
+}
+/** The facet rail. Only values that actually occur are offered. */
+export declare function FacetPanel({ facets, onFilter }: FacetPanelProps): ReactNode;
+/** Props for {@link LibrarySurface}. */
+export interface LibrarySurfaceProps {
+    readonly plan: SearchPlan;
+    readonly results: readonly SearchResult[];
+    readonly facets: Facets;
+    readonly sources: readonly Source[];
+    readonly freshnessOf: (hit: SearchHit) => Freshness;
+    readonly onOpenHit: (hit: SearchHit) => void;
+    readonly onOpenRevision: (revision: SourceRevision) => void;
+    readonly onFilter: (facet: string, value: string) => void;
+}
+/** The Library mode body. */
+export declare function LibrarySurface(props: LibrarySurfaceProps): ReactNode;
+//# sourceMappingURL=components.d.ts.map

package/lib/client/components.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { toneFor, tokenFor } from '@deepwatch/dsh-client-brand';
+import { currentRevision, } from '../sources.js';
+import { describeSearch, } from '../search.js';
+/** The glyph half of a freshness state, so colour is never the only signal. */
+const FRESHNESS_GLYPH = {
+    current: '●',
+    stale: '⌛',
+    gap: '⌇',
+    expired: '⊘',
+    unavailable: '?',
+};
+/** Freshness as glyph, word and tone. */
+export function FreshnessBadge({ freshness }) {
+    return (_jsxs("span", { "data-watch-freshness": freshness, style: { color: tokenFor(toneFor(freshness)) }, children: [_jsx("span", { "aria-hidden": "true", children: FRESHNESS_GLYPH[freshness] }), _jsx("span", { children: ` ${freshness}` })] }));
+}
+/**
+ * A source's revisions, newest last.
+ *
+ * Every revision is listed, including superseded ones, and every one is
+ * openable. A history that showed only the current revision would make old
+ * evidence unreachable through the interface even though it remains
+ * addressable underneath, which is the same failure with extra steps.
+ */
+export function RevisionHistory({ source, onOpen }) {
+    const current = currentRevision(source);
+    return (_jsx("ol", { "data-watch-revisions": source.sourceId, style: { listStyle: 'none', margin: 0, padding: 0 }, children: source.revisions.map(revision => (_jsxs("li", { "data-watch-revision": revision.sourceRevisionId, children: [_jsxs("button", { type: "button", "data-watch-index-state": revision.indexState, "aria-current": current?.sourceRevisionId === revision.sourceRevisionId ? 'true' : undefined, onClick: () => { onOpen(revision); }, style: { font: 'inherit', color: 'inherit', background: 'none', border: 'none', cursor: 'pointer' }, children: [_jsx("span", { dir: "ltr", children: `r${String(revision.revision)}` }), _jsx("span", { children: ` ${revision.indexState}` }), _jsx("time", { dateTime: revision.observedAt, children: ` ${revision.observedAt}` }), current?.sourceRevisionId === revision.sourceRevisionId && _jsx("span", { children: ' · current' })] }), revision.indexError !== null && (_jsx("span", { "data-watch-index-error": "", children: ` ${revision.indexError}` }))] }, revision.sourceRevisionId))) }));
+}
+/**
+ * One hit.
+ *
+ * The retrieval path is on the row, not in a legend. A person reading a
+ * semantic hit needs to know it is a semantic hit at the moment they read it,
+ * because that is what decides whether they should check it.
+ */
+export function SearchHitRow({ hit, freshness, onOpen }) {
+    return (_jsx("li", { "data-watch-hit": hit.sourceRevisionId, "data-watch-path": hit.path, children: _jsxs("button", { type: "button", onClick: () => { onOpen(hit); }, style: { font: 'inherit', color: 'inherit', background: 'none', border: 'none', cursor: 'pointer', textAlign: 'start' }, children: [hit.range !== null && (_jsx("span", { dir: "ltr", style: { fontVariantNumeric: 'tabular-nums' }, children: `${String(Math.floor(hit.range.startMs / 1000))}s ` })), _jsx("span", { dir: "auto", children: hit.text }), _jsx("span", { "data-watch-hit-path": hit.path, children: ` (${hit.path})` }), _jsx(FreshnessBadge, { freshness: freshness })] }) }));
+}
+/** The facet rail. Only values that actually occur are offered. */
+export function FacetPanel({ facets, onFilter }) {
+    const groups = [
+        ['kind', facets.kind],
+        ['indexState', facets.indexState],
+        ['collection', facets.collection],
+        ['script', facets.script],
+        ['path', facets.path],
+    ];
+    return (_jsx("aside", { "data-watch-facets": "", "aria-label": "Filters", children: groups.map(([name, values]) => (values.length === 0 ? null : (_jsxs("section", { "data-watch-facet": name, children: [_jsx("h3", { style: { font: 'inherit', fontSize: '11px' }, children: name }), _jsx("ul", { style: { listStyle: 'none', margin: 0, padding: 0 }, children: values.map(value => (_jsx("li", { children: _jsx("button", { type: "button", "data-watch-facet-value": value.value, onClick: () => { onFilter(name, value.value); }, style: { font: 'inherit', color: 'inherit', background: 'none', border: 'none', cursor: 'pointer' }, children: `${value.value} (${String(value.count)})` }) }, value.value))) })] }, name)))) }));
+}
+/** The Library mode body. */
+export function LibrarySurface(props) {
+    const byId = new Map(props.sources.map(source => [source.sourceId, source]));
+    return (_jsxs("section", { "data-watch-library": "", "aria-label": "Library", children: [_jsx("p", { "data-watch-search-plan": props.plan.path, children: describeSearch(props.plan, props.results) }), props.plan.fix !== '' && _jsx("p", { "data-watch-search-fix": "", children: props.plan.fix }), _jsx(FacetPanel, { facets: props.facets, onFilter: props.onFilter }), props.results.length === 0
+                ? _jsx("p", { "data-watch-library-empty": "", children: "Nothing in the Library matches." })
+                : props.results.map(result => {
+                    const source = byId.get(result.sourceId);
+                    return (_jsxs("article", { "data-watch-source": result.sourceId, children: [_jsx("h3", { style: { font: 'inherit' }, dir: "auto", children: result.title }), _jsx("span", { "data-watch-source-kind": result.kind, children: result.kind }), !result.current && (_jsx("span", { "data-watch-source-superseded": "", children: ' The source has changed since these were observed.' })), _jsx("ul", { style: { listStyle: 'none', margin: 0, padding: 0 }, children: result.hits.map(hit => (_jsx(SearchHitRow, { hit: hit, freshness: props.freshnessOf(hit), onOpen: props.onOpenHit }, `${hit.sourceRevisionId}:${String(hit.range?.startMs ?? 0)}:${hit.text}`))) }), source !== undefined && (_jsx(RevisionHistory, { source: source, onOpen: props.onOpenRevision }))] }, result.sourceId));
+                })] }));
+}
+//# sourceMappingURL=components.js.map

package/lib/client/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The Library surface, registered into DSH's slots.
+ *
+ * @module @deepwatch/dsh-library/client
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export * from './components.js';
+export * from './search-view.js';
+export * from './library-mode.js';
+export * from './read-plane.js';
+export * from '../sources.js';
+export * from '../search.js';
+/**
+ * Services this half needs before it can register anything.
+ *
+ * `remote.watchQuery` as well as `remote`. The Gateway installs each mounted
+ * namespace as its own cordis service under that key, so naming it is what
+ * makes this plugin wait for the mount rather than load beside it: the bare
+ * `remote` resolves as soon as the Gateway's browser half exists — which is
+ * before any contribution is mounted — and leaves `ctx.remote` with no
+ * `watchQuery` on it. Both are listed because both are read, and cordis
+ * refuses a property no `inject` entry claims: reaching `ctx.remote.watchQuery`
+ * on the strength of the second entry alone fails the fiber with "cannot get
+ * property "remote" without inject".
+ *
+ * The mount itself belongs to `@deepwatch/dsh-client-remotes`. This package
+ * owns the Library capability, and a package that owns a capability does not
+ * also own the transport that carries it; when it did, the two depended on
+ * each other.
+ */
+export declare const inject: string[];
+/**
+ * Register the Library mode body, bound to the read plane it queries.
+ *
+ * A `conversation.view` entry is handed `{ inspect, onInspectDone }` and
+ * nothing else, so a mode body has no way to reach a service on its own. The
+ * binding happens here, where the context is: what gets registered is the mode
+ * body with the mounted `watchQuery` namespace already supplied.
+ *
+ * Nothing here is defensive about `ctx.remote.watchQuery`. `inject` above means
+ * cordis does not call `apply` until that service exists, so a profile without
+ * the mount parks this plugin — no Library tab at all — rather than drawing a
+ * tab whose search quietly answers from an empty local index.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/client/index.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { LibraryModeView } from './library-mode.js';
+export * from './components.js';
+export * from './search-view.js';
+export * from './library-mode.js';
+export * from './read-plane.js';
+export * from '../sources.js';
+export * from '../search.js';
+/**
+ * Services this half needs before it can register anything.
+ *
+ * `remote.watchQuery` as well as `remote`. The Gateway installs each mounted
+ * namespace as its own cordis service under that key, so naming it is what
+ * makes this plugin wait for the mount rather than load beside it: the bare
+ * `remote` resolves as soon as the Gateway's browser half exists — which is
+ * before any contribution is mounted — and leaves `ctx.remote` with no
+ * `watchQuery` on it. Both are listed because both are read, and cordis
+ * refuses a property no `inject` entry claims: reaching `ctx.remote.watchQuery`
+ * on the strength of the second entry alone fails the fiber with "cannot get
+ * property "remote" without inject".
+ *
+ * The mount itself belongs to `@deepwatch/dsh-client-remotes`. This package
+ * owns the Library capability, and a package that owns a capability does not
+ * also own the transport that carries it; when it did, the two depended on
+ * each other.
+ */
+export const inject = ['slots', 'remote', 'remote.watchQuery'];
+/**
+ * Register the Library mode body, bound to the read plane it queries.
+ *
+ * A `conversation.view` entry is handed `{ inspect, onInspectDone }` and
+ * nothing else, so a mode body has no way to reach a service on its own. The
+ * binding happens here, where the context is: what gets registered is the mode
+ * body with the mounted `watchQuery` namespace already supplied.
+ *
+ * Nothing here is defensive about `ctx.remote.watchQuery`. `inject` above means
+ * cordis does not call `apply` until that service exists, so a profile without
+ * the mount parks this plugin — no Library tab at all — rather than drawing a
+ * tab whose search quietly answers from an empty local index.
+ */
+export function apply(ctx) {
+    const slots = ctx.slots;
+    const reads = ctx.remote.watchQuery;
+    /** The Library body, bound to the host that answers for it. */
+    const BoundLibraryModeView = (props) => (_jsx(LibraryModeView, { ...props, reads: reads }));
+    // Library is a product mode. See the note in the Live surface: registering as
+    // a view means DSH renders the tab, not Watch.
+    slots.inject('conversation.view', () => {
+        slots.register({ name: 'conversation.view', id: 'library', label: 'Library', order: 50 }, BoundLibraryModeView);
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/client/library-mode.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The Library mode body.
+ *
+ * It lives in the package that owns the capability rather than in the workspace
+ * shell — the shell provides the scaffold every mode shares, and a mode that
+ * also needed something back from its own package made the two depend on each
+ * other. TypeScript refused the circular project reference, which was the right
+ * answer to the wrong arrangement.
+ *
+ * @module @deepwatch/dsh-library/client/library-mode
+ */
+import type { ReactNode } from 'react';
+import type { ModeViewProps } from '@deepwatch/dsh-workspace/surface';
+import type { IndexableRecord } from '../index-store.js';
+import type { WatchQueryRemote } from './read-plane.js';
+/** What the Library body needs beyond the standard view props. */
+export interface LibraryModeProps extends ModeViewProps {
+    /**
+     * Records to index.
+     *
+     * The evidence store stays the source of truth; the index is derived from
+     * this and can be thrown away at any time.
+     */
+    readonly records?: readonly IndexableRecord[];
+    /**
+     * The mounted `ctx.remote.watchQuery` namespace, when there is one.
+     *
+     * Bound by the registration in `./index.tsx`, because a `conversation.view`
+     * entry receives only `{ inspect, onInspectDone }` and cannot reach a
+     * service itself. Absent when this body is rendered outside a profile — in a
+     * test, or a story — and the search then answers from the local index.
+     */
+    readonly reads?: WatchQueryRemote | undefined;
+}
+/** The Library mode: everything recorded, and searchable. */
+export declare function LibraryModeView({ inspect, records, reads }?: LibraryModeProps): ReactNode;
+//# sourceMappingURL=library-mode.d.ts.map

package/lib/client/library-mode.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { parseVerdict } from '@deepwatch/dsh-contracts';
+import { Facts, ModeSurface, Panel, readToolResult } from '@deepwatch/dsh-workspace/surface';
+import { LibrarySearch } from './search-view.js';
+/** The Library mode: everything recorded, and searchable. */
+export function LibraryModeView({ inspect, records = [], reads } = {}) {
+    const selected = parseVerdict(readToolResult(inspect));
+    return (_jsxs(ModeSurface, { title: "Library", lead: reads === undefined
+            ? 'Every source and every piece of evidence this workspace has recorded. '
+                + 'Search runs on this machine — no service, no model, nothing leaves it.'
+            : 'Every source and every piece of evidence this workspace has recorded. '
+                + 'Search runs on this workspace’s own host — no service, no model, '
+                + 'nothing leaves the machine it runs on.', children: [selected === null
+                ? null
+                : (_jsx(Panel, { heading: "Selected record", children: _jsx(Facts, { rows: [
+                            ['Verdict', selected.verdict],
+                            ['Reason', selected.reason],
+                            ['Checks', String(selected.checks.length)],
+                        ] }) })), _jsx(LibrarySearch, { records: records, reads: reads })] }));
+}
+//# sourceMappingURL=library-mode.js.map

package/lib/client/read-plane.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The Library's end of the read plane: what the surface asks, and what it does
+ * with the answer.
+ *
+ * The Host end is `@deepwatch/dsh-tools`, which registers `WatchQueryService`
+ * and lets Typert generate a strict Remote from it. The Library does not import
+ * that generated artifact and does not mount it. Doing either would make the
+ * package that owns the Library capability depend on the package that reads it,
+ * which is the cycle `@deepwatch/dsh-client-remotes` exists to remove.
+ *
+ * So the namespace is described here from the contracts both ends already
+ * share. `@deepwatch/dsh-contracts/query/wire` is the single definition of
+ * every request and response on this wire — the generated declaration imports
+ * its types from exactly that module — and `RemoteResult` is upstream's own
+ * envelope. Nothing below restates a shape either side owns.
+ *
+ * That leaves one thing a shared contract cannot prove: that the namespace
+ * really is called `watchQuery` and really carries these two methods. Two
+ * things hold it. `@deepwatch/dsh-client-remotes` compares this interface
+ * against the generated one at compile time, so a changed signature stops the
+ * build; and `tests/remote-client-mount.test.mjs` mounts the real contribution
+ * through the real Gateway and calls it, so a changed *name* fails a test
+ * rather than a page.
+ *
+ * @module @deepwatch/dsh-library/client/read-plane
+ */
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { LibraryGetRequest, LibraryGetResponse, LibraryRefreshRequest, CoreHealthRequest, CoreHealthResponse, LibraryRefreshResponse, LibrarySearchRequest, LibrarySearchResponse, ProviderTestRequest, ProviderTestResponse, RouteReadinessRequest, RouteReadinessResponse } from '@deepwatch/dsh-contracts/query/wire';
+import type { IndexHealth, IndexQueryResult } from '../index-store.js';
+/**
+ * The `watchQuery` namespace, as the Library calls it.
+ *
+ * `ctx.remote.watchQuery` is a cordis service the Gateway installs when the
+ * contribution is mounted, so a surface that injects `remote.watchQuery` is
+ * handed exactly this.
+ */
+export interface WatchQueryRemote {
+    readonly librarySearch: (request: LibrarySearchRequest, signal?: AbortSignal) => Promise<RemoteResult<LibrarySearchResponse>>;
+    readonly libraryGet: (request: LibraryGetRequest, signal?: AbortSignal) => Promise<RemoteResult<LibraryGetResponse>>;
+    /**
+     * The only method here with a side effect.
+     *
+     * A separate operation rather than a flag on a search: a search that might
+     * re-read the corpus has a cost nobody can predict, and leaves a caller no
+     * way to ask for an answer from what the host already holds.
+     */
+    readonly libraryRefresh: (request: LibraryRefreshRequest, signal?: AbortSignal) => Promise<RemoteResult<LibraryRefreshResponse>>;
+    /**
+     * The state of Watch Core, read from the running Bridge.
+     *
+     * Not a Library read, and on this namespace because this is the only channel
+     * the browser has to the Host. Diagnostics is its caller: before it existed
+     * that panel rendered the engine's connection state and version as literals,
+     * because there was nowhere to read them from.
+     */
+    readonly coreHealth: (request: CoreHealthRequest, signal?: AbortSignal) => Promise<RemoteResult<CoreHealthResponse>>;
+    readonly providerTest: (request: ProviderTestRequest, signal?: AbortSignal) => Promise<RemoteResult<ProviderTestResponse>>;
+    /**
+     * The Host's own verdict on a route, asked without spending anything.
+     *
+     * Here because this is the browser's only channel to the Host, and because
+     * the alternative — a tab remembering a provider test it ran — is a claim
+     * about a Host it cannot see.
+     */
+    readonly routeReadiness: (request: RouteReadinessRequest, signal?: AbortSignal) => Promise<RemoteResult<RouteReadinessResponse>>;
+}
+/** One row of results, however the surface obtained it. */
+export interface ResultRow {
+    /** Stable across a re-render of the same answer. */
+    readonly key: string;
+    readonly recordId: string;
+    readonly title: string;
+    readonly kind: string;
+    /** Matched text, verbatim. Empty when the answer carried no excerpt. */
+    readonly snippets: readonly string[];
+    readonly evidenceCount: number;
+    /** False when a newer revision of the same source exists. */
+    readonly current: boolean;
+}
+/** What one completed search left on the screen. */
+export interface SearchState {
+    readonly rows: readonly ResultRow[];
+    /** Matches in total, not merely on this page. */
+    readonly total: number;
+    readonly health: IndexHealth;
+    /** Which index generation answered. Zero when the host tracks none. */
+    readonly generation: number;
+    /** Non-fatal facts about this answer: truncation, staleness, refusal. */
+    readonly notes: readonly string[];
+    /** Whether the caller may ask for another page of the same answer. */
+    readonly pageable: boolean;
+}
+/** What the surface is asking the host for. */
+export interface LibraryQuery {
+    readonly text: string;
+    /** One modality, or the empty string for all of them. */
+    readonly modality: string;
+    readonly limit: number;
+    readonly deadlineMs: number;
+}
+/** The next correlation id for a Library read. */
+export declare function nextRequestId(): string;
+/**
+ * Ask the host, and turn whatever comes back into something renderable.
+ *
+ * Every outcome is an answer the surface shows rather than an exception it
+ * swallows. A refusal, an elapsed deadline and an expired cursor are different
+ * facts, and a person acts differently on each, so each keeps its own sentence.
+ */
+export declare function readLibraryPage(reads: WatchQueryRemote, query: LibraryQuery, signal: AbortSignal): Promise<SearchState>;
+/** A local index answer as the same view model, so the surface renders one shape. */
+export declare function fromIndex(result: IndexQueryResult): SearchState;
+/** What a completed refresh left for the surface to say. */
+export interface RefreshState {
+    /** True only where the host swapped a new generation into service. */
+    readonly refreshed: boolean;
+    /** The generation now answering searches. */
+    readonly generation: number;
+    readonly recordCount: number;
+    /** One sentence a person can act on. Empty where there is nothing to say. */
+    readonly note: string;
+    /** Whether the note describes a failure rather than a result. */
+    readonly failed: boolean;
+}
+/**
+ * Ask the host to read its roots again.
+ *
+ * Every outcome is rendered, and none of them is an exception. A refusal, an
+ * elapsed deadline, an abandoned rebuild and a failed one are four different
+ * facts; so is a rebuild that succeeded and found nothing new. Reporting any
+ * of them as "refreshed" would be a control that lies about what it did.
+ */
+export declare function refreshLibrary(reads: WatchQueryRemote, deadlineMs: number, signal: AbortSignal): Promise<RefreshState>;
+//# sourceMappingURL=read-plane.d.ts.map