@deepwatch/dsh-contracts 0.1.0

package/lib/query.d.ts

@@ -0,0 +1,362 @@
+/**
+ * The read plane: how a Watch mode asks the host what it should render.
+ *
+ * Watch contributes tools, and a tool result is how evidence reaches the
+ * *conversation*. It is not how a surface populates itself. 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 and each defaulted to an empty array. Four of the seven modes rendered
+ * an honest empty state, which is a truthful surface and not a working one.
+ *
+ * The seam this uses is DSH's own. `packages/typert` defines Remote services
+ * dispatched through a Gateway that already owns request correlation, abort
+ * signals and structured failure, and `ctx.remote` is the client face of it.
+ * An earlier note in this distribution described `ctx.remote` as an event bus
+ * rather than a query client. That is true of `$on`/`$dispatch` and misses the
+ * typed invocation path beside them, and the conclusion drawn from it -- that
+ * populating these modes would mean building a second data path -- was the
+ * wrong one. Nothing here is a second path.
+ *
+ * Every operation is enumerated. There is no open `operation: string` with a
+ * free-form `params` object: a request is one member of a discriminated union
+ * or it is refused, so a surface cannot ask for something the host does not
+ * implement and the host cannot receive a shape it did not expect.
+ *
+ * Four properties this exists to guarantee.
+ *
+ * **Reads cannot express a write.** Every operation answers a question. A
+ * request that changes something is not in the union, so a surface cannot
+ * acquire a side effect by accident and captured or model-generated content
+ * reaching these fields cannot become an action.
+ *
+ * **Nothing here names a location.** Identifiers are drawn from a charset with
+ * no separator, no colon and no dot-dot, so a parameter cannot carry a
+ * filesystem path, a UNC share, an executable name or a storage URL. The host
+ * decides where it reads; the caller only says which record.
+ *
+ * **Every answer carries a revision, and a stale one is dropped.** Two reads
+ * issued in order can return out of order, and a surface that renders whichever
+ * arrived last shows older data than it had a moment ago -- intermittently, and
+ * under load, which is where that bug survives review.
+ *
+ * **Everything is bounded.** Request size, string length, array length, nesting
+ * depth, identifier length and cursor length all have limits, because the cost
+ * of a malformed request must not be a function of how malformed it is.
+ *
+ * Cancellation is deliberately absent from this module. Typert dispatches with
+ * an `AbortSignal`, and a second cancellation protocol carried in the payload
+ * would be a way for the two to disagree about whether a call is still live.
+ *
+ * Browser-safe like the rest of this package: no Node imports, no runtime
+ * identity, nothing a client bundle would have to deduplicate.
+ *
+ * @module @deepwatch/dsh-contracts/query
+ */
+import type { WatchResult } from './index.js';
+/** The read-plane contract version this build speaks. */
+export declare const WATCH_QUERY_PROTOCOL_VERSION = 1;
+/** The oldest read-plane contract this build still answers. */
+export declare const WATCH_QUERY_PROTOCOL_MIN = 1;
+/**
+ * Every bound the read plane enforces.
+ *
+ * Stated in one place so a reviewer can see the whole budget at once, and so a
+ * test can assert against the same numbers the parser uses.
+ */
+export declare const QUERY_LIMITS: {
+    /** A whole request, serialised. Generous for a query, useless as a channel. */
+    readonly requestBytes: 8192;
+    /** Any single string the caller supplies. */
+    readonly stringLength: 2048;
+    /** A free-text search term. Shorter than a general string on purpose. */
+    readonly queryLength: 512;
+    /** Any array the caller supplies. */
+    readonly arrayLength: 64;
+    /** How deep a params object may nest before it is refused. */
+    readonly depth: 6;
+    /** An identifier: record ids, session ids, scope names. */
+    readonly identifierLength: 128;
+    /** A request id. */
+    readonly requestIdLength: 64;
+    /** A cursor, which the host issued and the caller returns unchanged. */
+    readonly cursorLength: 512;
+    /** The most records one page may carry, whatever the caller asked for. */
+    readonly limit: 200;
+    /** The longest a surface may wait before it must show something. */
+    readonly deadlineMs: 30000;
+};
+/** The namespaces a mode may read from. Reads only; there is no write here. */
+export declare const QUERY_NAMESPACES: readonly ["library", "memory", "compare", "live"];
+/** One readable namespace. */
+export type QueryNamespace = (typeof QUERY_NAMESPACES)[number];
+/**
+ * Every operation the host implements, by namespace.
+ *
+ * The parser rejects anything absent from this table, so adding an operation
+ * is one edit and forgetting to implement one is a refusal rather than an
+ * undefined call.
+ */
+export declare const QUERY_OPERATIONS: {
+    readonly library: readonly ["search", "get"];
+    readonly memory: readonly ["list", "get"];
+    readonly compare: readonly ["pair"];
+    readonly live: readonly ["state"];
+};
+/** Why a read was refused. */
+export type QueryErrorCode = 
+/** The host speaks a contract this client cannot read, or the reverse. */
+'protocol_mismatch'
+/** The namespace is not one this host serves. */
+ | 'unknown_namespace'
+/** The namespace exists; this operation in it does not. */
+ | 'unknown_operation'
+/** The request did not satisfy the contract; nothing was executed. */
+ | 'malformed_request'
+/** The request exceeded a size, depth or length bound. */
+ | 'request_too_large'
+/** The deadline passed before an answer existed. */
+ | 'deadline_exceeded'
+/** The caller aborted, or the surface was disposed. */
+ | 'cancelled'
+/** The host is present but this capability is not available here. */
+ | 'unavailable'
+/** The cursor is not one this host issued for this scope and snapshot. */
+ | 'cursor_expired'
+/** The host answered, and the answer did not satisfy the contract. */
+ | 'malformed_response';
+/**
+ * A monotonic revision.
+ *
+ * Compared, never interpreted. Deliberately not a timestamp: two hosts with
+ * unsynchronised clocks would produce an ordering that is wrong rather than
+ * merely coarse.
+ */
+export type Revision = number;
+/** What a Library search asks for. */
+export interface LibrarySearchParams {
+    /** Free text. Every term must match; the host decides how it tokenises. */
+    readonly query: string;
+    readonly limit: number;
+    /** Restrict to these modalities, or all of them when empty. */
+    readonly modalities: readonly string[];
+}
+/** One Library record, by id. */
+export interface LibraryGetParams {
+    readonly recordId: string;
+}
+/** What a Memory listing asks for. */
+export interface MemoryListParams {
+    /** Which memory scope to read. The host maps this to a store. */
+    readonly scope: string;
+    readonly limit: number;
+}
+/** One memory card, by id. */
+export interface MemoryGetParams {
+    readonly cardId: string;
+}
+/** The two records a comparison is over. */
+export interface ComparePairParams {
+    readonly leftId: string;
+    readonly rightId: string;
+}
+/** Live has no parameters: it reports the session the host already has. */
+export type LiveStateParams = Record<string, never>;
+/** What every read carries, whatever it asks for. */
+export interface QueryEnvelope {
+    readonly protocol: number;
+    /** Correlates the answer. Typert owns cancellation; this is for logs. */
+    readonly requestId: string;
+    /** How long the caller will wait. Clamped to the limit above. */
+    readonly deadlineMs: number;
+    /** Continues an earlier snapshot, when the host issued one. */
+    readonly cursor: string | null;
+}
+/** One fully-typed read. */
+export type QueryRequest = (QueryEnvelope & {
+    readonly namespace: 'library';
+    readonly operation: 'search';
+    readonly params: LibrarySearchParams;
+}) | (QueryEnvelope & {
+    readonly namespace: 'library';
+    readonly operation: 'get';
+    readonly params: LibraryGetParams;
+}) | (QueryEnvelope & {
+    readonly namespace: 'memory';
+    readonly operation: 'list';
+    readonly params: MemoryListParams;
+}) | (QueryEnvelope & {
+    readonly namespace: 'memory';
+    readonly operation: 'get';
+    readonly params: MemoryGetParams;
+}) | (QueryEnvelope & {
+    readonly namespace: 'compare';
+    readonly operation: 'pair';
+    readonly params: ComparePairParams;
+}) | (QueryEnvelope & {
+    readonly namespace: 'live';
+    readonly operation: 'state';
+    readonly params: LiveStateParams;
+});
+/** A Library record as the surface renders it. */
+export interface LibraryRecordView {
+    readonly recordId: string;
+    readonly title: string;
+    readonly modality: string;
+    readonly capturedAt: string | null;
+    /** Where this came from, stated rather than implied. */
+    readonly provenance: string;
+    /** The evidence this record points at. Never a filesystem path. */
+    readonly evidenceIds: readonly string[];
+}
+/** A memory card as the surface renders it. */
+export interface MemoryCardView {
+    readonly cardId: string;
+    readonly scope: string;
+    readonly text: string;
+    readonly writtenAt: string | null;
+    /** Which earlier card this one corrects, when it corrects one. */
+    readonly correctsCardId: string | null;
+    readonly forgotten: boolean;
+    readonly provenance: string;
+}
+/** The result of comparing two records. */
+export interface CompareResultView {
+    readonly leftId: string;
+    readonly rightId: string;
+    /** Differences in what the two produced. */
+    readonly outputDifferences: readonly string[];
+    /**
+     * Differences in what was verified about them.
+     *
+     * Separate from output on purpose: two records can agree on their output and
+     * disagree on whether anybody checked it, and collapsing those is how an
+     * unverified result inherits a verified one's credibility.
+     */
+    readonly verificationDifferences: readonly string[];
+    /** Whether the same inputs would produce this same comparison again. */
+    readonly reproducible: boolean;
+}
+/** The Live session, flattened for the wire. */
+export interface LiveStateView {
+    readonly sessionId: string | null;
+    readonly sourceId: string | null;
+    readonly state: string;
+    readonly permission: string;
+    readonly startedAt: string | null;
+    readonly reason: string;
+    readonly observationCount: number;
+}
+/** What a receipt records about a session that ended. */
+export interface LiveReceiptView {
+    readonly sessionId: string;
+    readonly sourceId: string;
+    readonly endedAt: string | null;
+    readonly outcome: string;
+    readonly observationCount: number;
+}
+/** The item type each operation returns. */
+export interface QueryResultMap {
+    'library/search': LibraryRecordView;
+    'library/get': LibraryRecordView;
+    'memory/list': MemoryCardView;
+    'memory/get': MemoryCardView;
+    'compare/pair': CompareResultView;
+    'live/state': LiveStateView | LiveReceiptView;
+}
+/** What every read returns. */
+export interface QuerySnapshot<Item> {
+    readonly protocol: number;
+    readonly requestId: string;
+    /** The host revision at the moment this answer was produced. */
+    readonly revision: Revision;
+    readonly items: readonly Item[];
+    /** Non-null when more remains; pass it back as `cursor`. */
+    readonly nextCursor: string | null;
+    /**
+     * Whether the host answered from complete data.
+     *
+     * A rebuilding index answers `false` and still returns what it has. The
+     * surface has to say so rather than presenting a partial answer as the whole.
+     */
+    readonly complete: boolean;
+}
+/** A read outcome. */
+export type QueryResult<Item> = WatchResult<QuerySnapshot<Item>>;
+/**
+ * What a cursor is bound to.
+ *
+ * A cursor is meaningless outside the snapshot it was issued against, and
+ * dangerous outside its scope: replaying one from another session would page
+ * through data the caller never asked for. So the binding travels in the
+ * cursor and the host checks it rather than trusting the caller to.
+ */
+export interface CursorScope {
+    readonly namespace: QueryNamespace;
+    readonly operation: string;
+    /** The workspace, profile or session the snapshot belongs to. */
+    readonly scope: string;
+    /** The revision the snapshot was taken at. */
+    readonly revision: Revision;
+}
+/** A decoded cursor: its binding, and where it resumes. */
+export interface DecodedCursor extends CursorScope {
+    readonly offset: number;
+}
+/** Encode a cursor. Opaque to the caller, checkable by the host. */
+export declare function encodeCursor(cursor: DecodedCursor): string;
+/**
+ * Decode a cursor and confirm it belongs here.
+ *
+ * Returns null for anything that does not decode or does not match the scope
+ * it is being replayed into. The caller turns that into `cursor_expired`,
+ * which is the honest description: the host cannot serve it, and saying why in
+ * more detail would describe another session's state.
+ */
+export declare function decodeCursor(value: string, expected: CursorScope): DecodedCursor | null;
+/** A non-negative safe integer. Protocol numbers and revisions must be one. */
+export declare function isSafeCount(value: unknown): value is number;
+/** Whether a value is an identifier of an acceptable shape and length. */
+export declare function isIdentifier(value: unknown): value is string;
+/** Whether a value is a namespace this host serves. */
+export declare function isQueryNamespace(value: unknown): value is QueryNamespace;
+/** Whether an operation exists in a namespace. */
+export declare function isQueryOperation(namespace: QueryNamespace, operation: unknown): boolean;
+/** Negotiate the read-plane contract, or null when there is no overlap. */
+export declare function negotiateQueryProtocol(peerMin: number, peerMax: number): number | null;
+/**
+ * Whether an arriving snapshot is newer than what a surface already shows.
+ *
+ * The equal case is deliberately false. Re-rendering an identical revision
+ * costs a frame and gains nothing, and treating equal as newer would let two
+ * in-flight answers to the same revision fight.
+ */
+export declare function isNewerRevision(arriving: Revision, showing: Revision | null): boolean;
+/** Bring a caller deadline inside what the host will honour. */
+export declare function clampDeadline(requested: unknown): number;
+/** Bring a caller page size inside what the host will return. */
+export declare function clampLimit(requested: unknown): number;
+/** Build the refusal a host returns when a read could not be produced. */
+export declare function queryRefusal(code: QueryErrorCode, message: string, fix: string, options?: {
+    readonly requestId?: string;
+    readonly retryable?: boolean;
+}): WatchResult<never>;
+/**
+ * Validate a request at the boundary.
+ *
+ * Everything crossing into the host is parsed here, including requests this
+ * distribution's own client produced: a surface is reachable by anything that
+ * can reach the page, and "our own code sent it" is an assumption rather than
+ * a guarantee. Returns the normalised request, or the refusal to send back.
+ */
+export declare function parseQueryRequest(value: unknown): WatchResult<QueryRequest>;
+/**
+ * Validate a snapshot before a surface renders it.
+ *
+ * The host is trusted to be the host and not trusted to be correct. A response
+ * that does not satisfy this contract is a defect somewhere, and rendering it
+ * anyway turns a defect into a wrong answer displayed confidently.
+ */
+export declare function parseQuerySnapshot<Item>(value: unknown, parseItem: (item: unknown) => Item | null): WatchResult<QuerySnapshot<Item>>;
+/** Read a Library record off the wire, or null when it is not one. */
+export declare function parseLibraryRecord(value: unknown): LibraryRecordView | null;
+//# sourceMappingURL=query.d.ts.map