@deepwatch/dsh-tools 0.1.0

package/lib/read-plane.d.ts

@@ -0,0 +1,237 @@
+/**
+ * The read plane, host side: what a Watch mode asks, answered.
+ *
+ * A `conversation.view` entry is handed `{ inspect, onInspectDone }` and
+ * nothing else, so Live, Memory, Library and Compare had no way to obtain
+ * their own data. This is the other end of the seam that fixes that, and it is
+ * DSH's own: a Typert Remote, dispatched through the Gateway that already
+ * owns request correlation, abort signals and structured failure. The client
+ * calls `ctx.remote.watchQuery.librarySearch(request, signal)` or
+ * `.libraryGet(request, signal)` and awaits a `RemoteResult` carrying one of
+ * the concrete outcomes in `@deepwatch/dsh-contracts/query/wire`.
+ *
+ * One method per read, rather than one `read` over a discriminated union. DSH
+ * already routes by method, so a union inside a single entry point would be a
+ * second router with its own schema to generate.
+ *
+ * It reads the same `LibraryIndex` the `watch_library_search` tool reads. One
+ * index, one set of semantics, one place where "every term must match" is
+ * decided -- two would drift inside a release and disagree about what the
+ * library contains, and the disagreement would surface as a person searching
+ * the UI and the agent searching the tool getting different answers to the
+ * same question.
+ *
+ * Four things it will not do.
+ *
+ * It performs no write. Every operation answers a question, and the request
+ * union has no member that changes anything, so a surface cannot acquire a
+ * side effect and captured or model-generated content reaching these fields
+ * cannot become an action.
+ *
+ * It reads nothing the caller names. Parameters are identifiers from a charset
+ * with no separator or colon; the roots come from configuration. A caller
+ * cannot point this at a path.
+ *
+ * It answers within the deadline it was given, or refuses. A slow host must
+ * not become a hung surface, and the timer is cleared on every exit so a
+ * completed read leaves nothing behind.
+ *
+ * And it never reports a partial answer as a whole one. A rebuilding or stale
+ * index answers `complete: false` with what it has, because a search that
+ * quietly returns less than it should is worse than one that says it is
+ * behind.
+ *
+ * @module @deepwatch/dsh-tools/read-plane
+ */
+import { type Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { LibraryIndex } from '@deepwatch/dsh-library';
+import type { CoreHealthRequest, CoreHealthResponse, LibraryGetRequest, LibraryGetResponse, LibraryRefreshRequest, LibraryRefreshResponse, LibraryIndexState, LibrarySearchRequest, LibrarySearchResponse, ProviderTestRequest, ProviderTestResponse, RouteReadinessRequest, RouteReadinessResponse } from '@deepwatch/dsh-contracts/query/wire';
+import type { LibraryGenerations } from './library-generations.js';
+/** What the read plane needs from its host. */
+export interface ReadPlaneConfig {
+    /**
+     * The index to read, built and cached by whoever owns it.
+     *
+     * A function rather than a value so a rebuild behind the tool is visible
+     * here without either side holding a reference to a stale object.
+     */
+    readonly index: () => LibraryIndex;
+    /**
+     * Which workspace this host is answering for.
+     *
+     * Cursors are bound to it, so one issued here cannot be replayed against
+     * another workspace's snapshot.
+     */
+    readonly scope: string;
+    /**
+     * The one thing allowed to replace the index, when the host has one.
+     *
+     * Optional because a deployment may compose the read plane over an index it
+     * owns by other means. Where it is absent, `libraryRefresh` still exists and
+     * answers `refresh_failed` with a reason — which is what a surface should
+     * render, rather than a refresh that appears to work and changes nothing.
+     */
+    readonly generations?: LibraryGenerations;
+}
+/** Flatten one search result into the shape a surface renders. */
+/**
+ * The service key, on the Context both faces share.
+ *
+ * This is not documentation. Typert analyses a package's public export graph
+ * and binds a Remote through the Cordis Context declaration; without this the
+ * service is discovered as a package and emits no artifact, because nothing
+ * ties `WatchQueryService` to the key `watchQuery` that the Gateway exposes as
+ * `ctx.remote.watchQuery`.
+ */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        watchQuery: WatchQueryService;
+    }
+}
+/**
+ * The Typert Remote a Watch surface calls.
+ *
+ * `watchQuery` is both the Cordis service key and the wire namespace, so the
+ * client reaches it as `ctx.remote.watchQuery`.
+ */
+export declare class WatchQueryService extends TypertRemoteService {
+    /**
+     * Deliberately not a `#private` field.
+     *
+     * Cordis hands a Service to callers through a Proxy, and a private field is
+     * unreachable through one: the Gateway invoked this method and got
+     * "Cannot read private member #config from an object whose class did not
+     * declare it". Every direct unit test passed, because a direct call has no
+     * proxy in front of it -- which is the whole argument for exercising this
+     * through the real Gateway.
+     */
+    readonly config: ReadPlaneConfig;
+    constructor(ctx: Context, config: ReadPlaneConfig);
+    /**
+     * One concrete method per read, rather than one `read` over a union.
+     *
+     * DSH already routes by method, so a discriminated union inside a single
+     * entry point would be a second router with its own schema to generate.
+     * One request type and one response type per method is what Typert emits
+     * a strict codec from most directly.
+     *
+     * `signal` is last, as Typert requires, and is not serialised.
+     */
+    librarySearch(request: LibrarySearchRequest, signal: AbortSignal): Promise<LibrarySearchResponse>;
+    /** One record by id. A direct lookup, not a one-result search. */
+    libraryGet(request: LibraryGetRequest, signal: AbortSignal): Promise<LibraryGetResponse>;
+    /**
+     * Read the roots again, and put the result into service if it is healthy.
+     *
+     * The only method here with a side effect, and the only one that is not a
+     * question. It is a separate method for exactly that reason: a `rebuild`
+     * flag on `librarySearch` would make every search a potential re-read of the
+     * corpus, and would leave a caller no way to ask for an answer from what the
+     * host already has.
+     *
+     * Genuinely async, unlike its siblings: the rebuild yields between files so
+     * a caller that stops waiting can be observed doing so.
+     */
+    libraryRefresh(request: LibraryRefreshRequest, signal: AbortSignal): Promise<LibraryRefreshResponse>;
+    /**
+     * What Watch Core is doing right now, read from the running Bridge.
+     *
+     * The one method here that is not about the Library, and it is here because
+     * this is the only channel the browser has to the Host. Diagnostics used to
+     * render "Connected over stdio" and a version number as literals in a
+     * component, because there was nowhere to read them from.
+     *
+     * Nothing is defaulted. A value the Bridge has not established is `null`,
+     * and the panel renders that as "not reported" -- which is worth less than a
+     * real reading and far more than a confident wrong one.
+     */
+    coreHealth(request: CoreHealthRequest, signal: AbortSignal): Promise<CoreHealthResponse>;
+    /** Spend one deliberately tiny provider request only after a person asks. */
+    providerTest(request: ProviderTestRequest, signal: AbortSignal): Promise<ProviderTestResponse>;
+    /**
+     * Whether the Host would serve this route right now, asked without spending
+     * anything.
+     *
+     * The browser half used to answer this from its own memory of a provider
+     * test it had run, which is a claim about a Host it cannot see. A tab that
+     * stayed open across a Host restart, or across an edit made in another tab,
+     * kept drawing a tested badge over a route the Host had already stopped
+     * being willing to serve — and the composer it gates opened onto a refusal.
+     * There is one answer, and this is where it is read from.
+     */
+    routeReadiness(request: RouteReadinessRequest, signal: AbortSignal): Promise<RouteReadinessResponse>;
+}
+/**
+ * Read the Host's verdict for one route.
+ *
+ * No network, no provider, no credential. When the provenance row is not
+ * composed the honest answer is that nothing here can say, which reads as
+ * unproved — the same direction the guard fails in.
+ */
+export declare function readRouteReadiness(request: RouteReadinessRequest, ctx: Context): RouteReadinessResponse;
+/** Execute a provider request without returning or logging model output. */
+export declare function testProvider(request: ProviderTestRequest, ctx: Context, signal: AbortSignal): Promise<ProviderTestResponse>;
+/** Route a parsed request to the namespace that answers it. */
+/** Answer a Library read from the index the tool already owns. */
+/** Assemble a snapshot, and say honestly whether it is whole. */
+/** Install the read plane onto a host context. */
+export declare function applyReadPlane(ctx: Context, config: ReadPlaneConfig): void;
+/**
+ * Answer a Library search against the shared index.
+ *
+ * Separate from the Service so the whole path is testable without a DSH
+ * runtime, and so the Service stays a Typert adapter with no decisions in it.
+ */
+export declare function searchLibrary(request: LibrarySearchRequest, config: ReadPlaneConfig, signal: AbortSignal): LibrarySearchResponse;
+/**
+ * The wire state for one index, without collapsing four answers into two.
+ *
+ * The defect this replaces was a single conditional: anything that was not
+ * `ready` became `stale`, so an index over an empty store reported "Index is
+ * behind the store". A person looking at a fresh profile was told their
+ * Library was out of date with respect to nothing, and the only honest reading
+ * of that screen — something is wrong — was the wrong one.
+ *
+ * `empty` and `stale` are opposite claims. Empty says the index agrees with a
+ * store that holds nothing. Stale says the store moved and the index has not
+ * caught up. Reporting the first as the second turns "there is nothing here
+ * yet" into "you are missing something", which is the difference between a
+ * quiet first run and a bug report.
+ */
+export declare function wireIndexState(health: LibraryIndex['health'], size: number): LibraryIndexState;
+/**
+ * Answer a Library get.
+ *
+ * `index.record()` is a keyed lookup. Implementing this as a search with
+ * `limit: 1` and then checking whether the single result happened to be the
+ * requested id reports every record except the top-ranked one as absent.
+ */
+export declare function getLibraryRecord(request: LibraryGetRequest, config: ReadPlaneConfig, signal: AbortSignal): LibraryGetResponse;
+/**
+ * Rebuild the index, and say what happened to the one already in service.
+ *
+ * Every outcome leaves a searchable Library, which is why none of them is an
+ * exception. A refusal, an elapsed deadline, an abandoned rebuild and a failed
+ * one are four different facts, and a surface renders each differently.
+ *
+ * Separate from the Service for the same reason the reads are: the Service
+ * stays a Typert adapter with no decisions in it, and the whole path is
+ * testable without a DSH runtime.
+ */
+export declare function refreshLibrary(request: LibraryRefreshRequest, config: ReadPlaneConfig, signal: AbortSignal): Promise<LibraryRefreshResponse>;
+/**
+ * Read the Bridge's live state, and say honestly where it could not.
+ *
+ * Separate from the Service for the same reason the Library readers are: the
+ * Service is a Typert adapter with no decisions in it, and the whole path is
+ * testable without a DSH runtime.
+ *
+ * The rule this function exists to keep: **no field is defaulted.** A version
+ * the Bridge has never received is `null`, not `'unknown'` and not the version
+ * this build was compiled against. Diagnostics is the screen people open when
+ * they already suspect something is wrong, and it is the last place a
+ * plausible substitute belongs.
+ */
+export declare function readCoreHealth(request: CoreHealthRequest, ctx: Context, signal: AbortSignal): CoreHealthResponse;
+//# sourceMappingURL=read-plane.d.ts.map