@deepwatch/dsh-contracts 0.1.0

package/lib/presentation.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Rules about how results may be presented.
+ *
+ * These live in the contracts package rather than in a component because they
+ * are product rules, not styling choices. "Green belongs to VERIFIED alone" is
+ * the same commitment whether it is rendered by a React card, a terminal
+ * summary or a CI annotation, and keeping it here means there is one place to
+ * change it and one place to test it.
+ *
+ * Everything below is a pure function over data that already crossed the wire.
+ * No DOM, no React, no Node.
+ *
+ * @module @deepwatch/dsh-contracts/presentation
+ */
+import type { Freshness, Verdict } from './index.js';
+/** How a result is allowed to be presented. */
+export type ResultTone = 'success' | 'error' | 'caution';
+/**
+ * The tone one verdict is rendered in.
+ *
+ * `INCONCLUSIVE`, `STALE`, `BLOCKED` and `UNVERIFIED` share the caution tone
+ * on purpose. They are not failures, and styling them as errors teaches people
+ * to dismiss them — which is how an unproven result comes to be accepted as a
+ * proven one. They are also not successes, which is the more obvious half.
+ */
+export declare function verdictTone(verdict: Verdict): ResultTone;
+/** How a freshness state should be labelled, or null when it needs no label. */
+export declare function freshnessLabel(freshness: Freshness): string | null;
+/** One check inside a verification contract, as a result carries it. */
+export interface PresentableCheck {
+    readonly checkId: string;
+    readonly kind: string;
+    readonly description: string | null;
+    /**
+     * Tri-state on purpose. A check that could not run is not a check that
+     * failed, and flattening the two turns "we did not look" into "it is broken"
+     * — or, worse, the reverse.
+     */
+    readonly passed: boolean | null;
+    readonly detail: string | null;
+}
+/** A verification result, ready to render. */
+export interface PresentableVerdict {
+    readonly verdict: Verdict;
+    readonly reason: string;
+    readonly checks: readonly PresentableCheck[];
+    readonly contractDigest: string;
+    readonly assurance: string | null;
+}
+/**
+ * Parse a tool result into a verdict.
+ *
+ * Returns null rather than guessing. A result this cannot read renders as a
+ * generic row, which is honest; inventing a verdict to fill a card would not
+ * be.
+ */
+export declare function parseVerdict(value: unknown): PresentableVerdict | null;
+/** One cited moment, ready to render. */
+export interface PresentableCitation {
+    readonly evidenceId: string;
+    readonly text: string;
+    /** Milliseconds into the source, or null for a citation with no timing. */
+    readonly atMs: number | null;
+    readonly modality: string;
+    readonly provenance: string;
+    readonly freshness: Freshness;
+}
+/** An evidence-linked answer, ready to render. */
+export interface PresentableAnswer {
+    readonly answer: string;
+    readonly citations: readonly PresentableCitation[];
+    /** The engine's own assessment of whether it had enough to answer. */
+    readonly groundedness: 'sufficient' | 'insufficient' | null;
+}
+/**
+ * Parse a source-query result into an answer.
+ *
+ * Returns null for a refusal or an unreadable payload, so a failure never
+ * renders as a grounded answer with nothing behind it.
+ */
+export declare function parseAnswer(value: unknown): PresentableAnswer | null;
+/**
+ * Format a media position the way a person reads one.
+ *
+ * @returns `m:ss` under an hour, `h:mm:ss` above it, or null when there is no
+ * usable timestamp — which a caller renders as no timestamp rather than as
+ * `0:00`, because those mean different things.
+ */
+export declare function formatTimestamp(atMs: number | null): string | null;
+//# sourceMappingURL=presentation.d.ts.map

package/lib/presentation.js

@@ -0,0 +1,158 @@
+/**
+ * Rules about how results may be presented.
+ *
+ * These live in the contracts package rather than in a component because they
+ * are product rules, not styling choices. "Green belongs to VERIFIED alone" is
+ * the same commitment whether it is rendered by a React card, a terminal
+ * summary or a CI annotation, and keeping it here means there is one place to
+ * change it and one place to test it.
+ *
+ * Everything below is a pure function over data that already crossed the wire.
+ * No DOM, no React, no Node.
+ *
+ * @module @deepwatch/dsh-contracts/presentation
+ */
+/**
+ * The tone one verdict is rendered in.
+ *
+ * `INCONCLUSIVE`, `STALE`, `BLOCKED` and `UNVERIFIED` share the caution tone
+ * on purpose. They are not failures, and styling them as errors teaches people
+ * to dismiss them — which is how an unproven result comes to be accepted as a
+ * proven one. They are also not successes, which is the more obvious half.
+ */
+export function verdictTone(verdict) {
+    if (verdict === 'VERIFIED')
+        return 'success';
+    if (verdict === 'FAILED')
+        return 'error';
+    return 'caution';
+}
+/** The sentence to show when Watch Core supplied no reason of its own. */
+const FALLBACK_REASON = {
+    VERIFIED: 'Every required check passed against valid evidence.',
+    FAILED: 'A required check failed.',
+    UNVERIFIED: 'Nothing executable was checked, so nothing was established.',
+    INCONCLUSIVE: 'The evidence conflicts, or a check could not be run.',
+    STALE: 'The evidence no longer describes the current source.',
+    BLOCKED: 'Policy or a missing dependency prevented verification.',
+};
+/** Every verdict the taxonomy defines, for exhaustive validation. */
+const VERDICTS = new Set([
+    'VERIFIED', 'FAILED', 'UNVERIFIED', 'INCONCLUSIVE', 'STALE', 'BLOCKED',
+]);
+/** Wording per freshness state, so the distinction survives without colour. */
+const FRESHNESS_LABEL = {
+    current: null,
+    stale: 'stale',
+    gap: 'gap in capture',
+    expired: 'expired',
+    unavailable: 'freshness unknown',
+};
+/** How a freshness state should be labelled, or null when it needs no label. */
+export function freshnessLabel(freshness) {
+    return FRESHNESS_LABEL[freshness];
+}
+/**
+ * Parse a tool result into a verdict.
+ *
+ * Returns null rather than guessing. A result this cannot read renders as a
+ * generic row, which is honest; inventing a verdict to fill a card would not
+ * be.
+ */
+export function parseVerdict(value) {
+    const record = asRecord(value);
+    if (record === null)
+        return null;
+    const verdict = record['verdict'];
+    if (typeof verdict !== 'string' || !VERDICTS.has(verdict))
+        return null;
+    const checks = Array.isArray(record['checks']) ? record['checks'] : [];
+    const reason = record['reason'];
+    return {
+        verdict: verdict,
+        reason: typeof reason === 'string' && reason !== ''
+            ? reason
+            : FALLBACK_REASON[verdict],
+        checks: checks.flatMap(parseCheck),
+        contractDigest: typeof record['contractDigest'] === 'string' ? record['contractDigest'] : '',
+        assurance: typeof record['assurance'] === 'string' ? record['assurance'] : null,
+    };
+}
+function parseCheck(value) {
+    const record = asRecord(value);
+    if (record === null || typeof record['checkId'] !== 'string')
+        return [];
+    return [{
+            checkId: record['checkId'],
+            kind: typeof record['kind'] === 'string' ? record['kind'] : 'check',
+            description: typeof record['description'] === 'string' ? record['description'] : null,
+            passed: typeof record['passed'] === 'boolean' ? record['passed'] : null,
+            detail: typeof record['detail'] === 'string' ? record['detail'] : null,
+        }];
+}
+/**
+ * Parse a source-query result into an answer.
+ *
+ * Returns null for a refusal or an unreadable payload, so a failure never
+ * renders as a grounded answer with nothing behind it.
+ */
+export function parseAnswer(value) {
+    const record = asRecord(value);
+    if (record === null || record['ok'] !== true)
+        return null;
+    if (typeof record['answer'] !== 'string')
+        return null;
+    const evidence = Array.isArray(record['evidence']) ? record['evidence'] : [];
+    const groundedness = record['groundedness'];
+    return {
+        answer: record['answer'],
+        citations: evidence.flatMap(parseCitation),
+        groundedness: groundedness === 'sufficient' || groundedness === 'insufficient'
+            ? groundedness
+            : null,
+    };
+}
+function parseCitation(value) {
+    const record = asRecord(value);
+    if (record === null || typeof record['evidenceId'] !== 'string')
+        return [];
+    const range = asRecord(record['temporalRange']);
+    const start = range === null ? undefined : range['startMs'];
+    const freshness = record['freshness'];
+    return [{
+            evidenceId: record['evidenceId'],
+            text: typeof record['text'] === 'string' ? record['text'] : '',
+            atMs: typeof start === 'number' && Number.isFinite(start) ? start : null,
+            modality: typeof record['modality'] === 'string' ? record['modality'] : 'text',
+            provenance: typeof record['provenance'] === 'string' ? record['provenance'] : 'observation',
+            // An unrecognized value becomes `unavailable`, never `current`. Defaulting
+            // an unknown to the reassuring answer is exactly the wrong direction.
+            freshness: typeof freshness === 'string' && freshness in FRESHNESS_LABEL
+                ? freshness
+                : 'unavailable',
+        }];
+}
+/**
+ * Format a media position the way a person reads one.
+ *
+ * @returns `m:ss` under an hour, `h:mm:ss` above it, or null when there is no
+ * usable timestamp — which a caller renders as no timestamp rather than as
+ * `0:00`, because those mean different things.
+ */
+export function formatTimestamp(atMs) {
+    if (atMs === null || !Number.isFinite(atMs))
+        return null;
+    const total = Math.max(0, Math.floor(atMs / 1000));
+    const seconds = String(total % 60).padStart(2, '0');
+    if (total < 3600)
+        return `${String(Math.floor(total / 60))}:${seconds}`;
+    const minutes = String(Math.floor(total / 60) % 60).padStart(2, '0');
+    return `${String(Math.floor(total / 3600))}:${minutes}:${seconds}`;
+}
+/** Narrow an unknown to a plain object, excluding null and arrays. */
+function asRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    return value;
+}
+//# sourceMappingURL=presentation.js.map

package/lib/query/validate.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Semantic validation for the Library read plane.
+ *
+ * The generated Typert codec proves *shape*: that `limit` is a number and
+ * `modalities` is an array of strings. It does not prove that the number is
+ * within a range anybody intended, that the array is a length the host will
+ * answer for, or that a record id is an identifier rather than a path. Those
+ * are policy, and a structural codec has no opinion about policy.
+ *
+ * There is one measured behaviour worth stating plainly, because it is easy to
+ * assume the opposite. The generated codec is emitted as a plain `z.object`,
+ * with neither `.strict()` nor `.passthrough()`, so **unknown fields are
+ * stripped, not rejected**. Typert's own `mode: 'strict'` refers to strict
+ * codec generation and not to zod's strict object mode. A caller can therefore
+ * send extra fields and get a successful call; what it cannot do is have those
+ * fields reach anything, because what continues past the boundary is the parsed
+ * value and not the input. That is a defensible policy and it is not the one a
+ * reader would guess, so it is asserted in the tests rather than described.
+ *
+ * These functions take `unknown` deliberately, which is why they live here and
+ * not in the wire module: `query/wire` describes what crosses the wire and must
+ * stay free of parsers, and this describes what the host will accept.
+ *
+ * Order matters. Everything here runs before the index is touched, so an
+ * oversized or malformed request costs a bounds check and never a search.
+ *
+ * @module @deepwatch/dsh-contracts/query/validate
+ */
+import type { CoreHealthRequest, LibraryGetRequest, LibraryRefreshRequest, LibraryRequestRejected, LibrarySearchRequest } from './wire.js';
+/** The modalities the Library indexes. A closed set, not free text. */
+export declare const LIBRARY_MODALITIES: readonly ["video", "audio", "page", "stream", "document", "screen_capture"];
+/** Accepted, or the refusal to send back. */
+export type Validated<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly refusal: LibraryRequestRejected;
+};
+/**
+ * Accept a Library search, or say why not.
+ *
+ * Normalises `limit` and `deadlineMs` rather than refusing them, and refuses
+ * everything that is a statement about what the caller may name: the query
+ * length, the modality vocabulary, and the cursor length.
+ */
+export declare function parseLibrarySearchRequest(value: unknown): Validated<LibrarySearchRequest>;
+/**
+ * Accept a Library get, or say why not.
+ *
+ * `recordId` is held to the identifier grammar, which has no separator, no
+ * colon and no dot-dot — so it cannot carry a filesystem path, a UNC share or
+ * a storage URL. The host decides where it reads; the caller says which record.
+ */
+export declare function parseLibraryGetRequest(value: unknown): Validated<LibraryGetRequest>;
+/**
+ * Accept a Library refresh, or say why not.
+ *
+ * The envelope and nothing else. A refresh names no record, no query and no
+ * location — it asks the host to read the roots it was configured with, which
+ * is the only reason it can be a safe operation to expose at all. There is no
+ * field here a caller could point somewhere.
+ */
+export declare function parseLibraryRefreshRequest(value: unknown): Validated<LibraryRefreshRequest>;
+/**
+ * Validate a `coreHealth` request.
+ *
+ * The envelope and nothing else. A health read takes no parameters on purpose:
+ * every field of the answer is something the Host observed, so there is
+ * nothing for a caller to select and nothing it could select that would change
+ * what is true.
+ */
+export declare function parseCoreHealthRequest(value: unknown): Validated<CoreHealthRequest>;
+//# sourceMappingURL=validate.d.ts.map

package/lib/query/validate.js

@@ -0,0 +1,243 @@
+/**
+ * Semantic validation for the Library read plane.
+ *
+ * The generated Typert codec proves *shape*: that `limit` is a number and
+ * `modalities` is an array of strings. It does not prove that the number is
+ * within a range anybody intended, that the array is a length the host will
+ * answer for, or that a record id is an identifier rather than a path. Those
+ * are policy, and a structural codec has no opinion about policy.
+ *
+ * There is one measured behaviour worth stating plainly, because it is easy to
+ * assume the opposite. The generated codec is emitted as a plain `z.object`,
+ * with neither `.strict()` nor `.passthrough()`, so **unknown fields are
+ * stripped, not rejected**. Typert's own `mode: 'strict'` refers to strict
+ * codec generation and not to zod's strict object mode. A caller can therefore
+ * send extra fields and get a successful call; what it cannot do is have those
+ * fields reach anything, because what continues past the boundary is the parsed
+ * value and not the input. That is a defensible policy and it is not the one a
+ * reader would guess, so it is asserted in the tests rather than described.
+ *
+ * These functions take `unknown` deliberately, which is why they live here and
+ * not in the wire module: `query/wire` describes what crosses the wire and must
+ * stay free of parsers, and this describes what the host will accept.
+ *
+ * Order matters. Everything here runs before the index is touched, so an
+ * oversized or malformed request costs a bounds check and never a search.
+ *
+ * @module @deepwatch/dsh-contracts/query/validate
+ */
+import { QUERY_LIMITS, isIdentifier, isSafeCount } from '../query.js';
+import { WATCH_QUERY_WIRE_VERSION } from './wire.js';
+/** The modalities the Library indexes. A closed set, not free text. */
+export const LIBRARY_MODALITIES = [
+    'video', 'audio', 'page', 'stream', 'document', 'screen_capture',
+];
+/** Build the refusal a surface renders. */
+function reject(requestId, reason, field) {
+    return {
+        ok: false,
+        refusal: {
+            outcome: 'rejected',
+            protocol: WATCH_QUERY_WIRE_VERSION,
+            // Echoed only when it is already a safe identifier: a refusal must not
+            // become a way to have arbitrary text reflected back.
+            requestId: isIdentifier(requestId) ? requestId : '',
+            reason,
+            field,
+        },
+    };
+}
+/**
+ * How large the request is once serialised.
+ *
+ * Measured before anything is walked, because the cost of rejecting a
+ * malformed request must not be a function of how malformed it is. A value
+ * that cannot be serialised at all — a cycle — is refused for the same reason.
+ */
+function withinSizeBudget(value) {
+    try {
+        return JSON.stringify(value)?.length <= QUERY_LIMITS.requestBytes;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether an object nests deeper than the budget allows. */
+function withinDepth(value, depth = 0) {
+    if (depth > QUERY_LIMITS.depth)
+        return false;
+    if (Array.isArray(value))
+        return value.every(entry => withinDepth(entry, depth + 1));
+    if (typeof value === 'object' && value !== null) {
+        return Object.values(value).every(entry => withinDepth(entry, depth + 1));
+    }
+    return true;
+}
+/** The envelope fields every Library request carries. */
+function envelope(raw) {
+    if (!isSafeCount(raw.protocol) || raw.protocol !== WATCH_QUERY_WIRE_VERSION) {
+        return reject(raw.requestId, 'protocol_mismatch', 'protocol');
+    }
+    if (typeof raw.requestId !== 'string'
+        || raw.requestId === ''
+        || raw.requestId.length > QUERY_LIMITS.requestIdLength
+        || !isIdentifier(raw.requestId)) {
+        return reject(raw.requestId, 'identifier_invalid', 'requestId');
+    }
+    if (!isSafeCount(raw.deadlineMs) || raw.deadlineMs <= 0) {
+        return reject(raw.requestId, 'malformed_request', 'deadlineMs');
+    }
+    return {
+        ok: true,
+        value: {
+            protocol: raw.protocol,
+            requestId: raw.requestId,
+            // Normalised rather than refused: a caller asking to wait longer than the
+            // host will wait is not making a mistake worth failing over.
+            deadlineMs: Math.min(raw.deadlineMs, QUERY_LIMITS.deadlineMs),
+        },
+    };
+}
+/** The common front half of both validators. */
+function opened(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return reject(undefined, 'malformed_request', null);
+    }
+    if (!withinSizeBudget(value))
+        return reject(value.requestId, 'request_too_large', null);
+    if (!withinDepth(value))
+        return reject(value.requestId, 'request_too_large', null);
+    return { ok: true, value: value };
+}
+/**
+ * Accept a Library search, or say why not.
+ *
+ * Normalises `limit` and `deadlineMs` rather than refusing them, and refuses
+ * everything that is a statement about what the caller may name: the query
+ * length, the modality vocabulary, and the cursor length.
+ */
+export function parseLibrarySearchRequest(value) {
+    const open = opened(value);
+    if (!open.ok)
+        return open;
+    const raw = open.value;
+    const head = envelope(raw);
+    if (!head.ok)
+        return head;
+    if (typeof raw.query !== 'string' || raw.query.length > QUERY_LIMITS.queryLength) {
+        return reject(raw.requestId, 'malformed_request', 'query');
+    }
+    if (!Array.isArray(raw.modalities) || raw.modalities.length > QUERY_LIMITS.arrayLength) {
+        return reject(raw.requestId, 'malformed_request', 'modalities');
+    }
+    // Collected while checking rather than spread afterwards: `Array.isArray`
+    // narrows to `any[]`, and spreading that would carry an `any` into a value
+    // the rest of the host treats as validated.
+    const modalities = [];
+    for (const modality of raw.modalities) {
+        if (typeof modality !== 'string'
+            || !LIBRARY_MODALITIES.includes(modality)) {
+            return reject(raw.requestId, 'malformed_request', 'modalities');
+        }
+        modalities.push(modality);
+    }
+    if (raw.cursor !== null && raw.cursor !== undefined) {
+        if (typeof raw.cursor !== 'string' || raw.cursor.length > QUERY_LIMITS.cursorLength) {
+            return reject(raw.requestId, 'malformed_request', 'cursor');
+        }
+    }
+    if (raw.limit !== undefined && !isSafeCount(raw.limit)) {
+        return reject(raw.requestId, 'malformed_request', 'limit');
+    }
+    return {
+        ok: true,
+        value: {
+            protocol: head.value.protocol,
+            requestId: head.value.requestId,
+            deadlineMs: head.value.deadlineMs,
+            query: raw.query,
+            modalities,
+            limit: Math.min(typeof raw.limit === 'number' && raw.limit > 0 ? raw.limit : QUERY_LIMITS.limit, QUERY_LIMITS.limit),
+            cursor: typeof raw.cursor === 'string' ? raw.cursor : null,
+        },
+    };
+}
+/**
+ * Accept a Library get, or say why not.
+ *
+ * `recordId` is held to the identifier grammar, which has no separator, no
+ * colon and no dot-dot — so it cannot carry a filesystem path, a UNC share or
+ * a storage URL. The host decides where it reads; the caller says which record.
+ */
+export function parseLibraryGetRequest(value) {
+    const open = opened(value);
+    if (!open.ok)
+        return open;
+    const raw = open.value;
+    const head = envelope(raw);
+    if (!head.ok)
+        return head;
+    if (typeof raw.recordId !== 'string'
+        || raw.recordId.length > QUERY_LIMITS.identifierLength
+        || !isIdentifier(raw.recordId)) {
+        return reject(raw.requestId, 'identifier_invalid', 'recordId');
+    }
+    return {
+        ok: true,
+        value: {
+            protocol: head.value.protocol,
+            requestId: head.value.requestId,
+            deadlineMs: head.value.deadlineMs,
+            recordId: raw.recordId,
+        },
+    };
+}
+/**
+ * Accept a Library refresh, or say why not.
+ *
+ * The envelope and nothing else. A refresh names no record, no query and no
+ * location — it asks the host to read the roots it was configured with, which
+ * is the only reason it can be a safe operation to expose at all. There is no
+ * field here a caller could point somewhere.
+ */
+export function parseLibraryRefreshRequest(value) {
+    const open = opened(value);
+    if (!open.ok)
+        return open;
+    const head = envelope(open.value);
+    if (!head.ok)
+        return head;
+    return {
+        ok: true,
+        value: {
+            protocol: head.value.protocol,
+            requestId: head.value.requestId,
+            deadlineMs: head.value.deadlineMs,
+        },
+    };
+}
+/**
+ * Validate a `coreHealth` request.
+ *
+ * The envelope and nothing else. A health read takes no parameters on purpose:
+ * every field of the answer is something the Host observed, so there is
+ * nothing for a caller to select and nothing it could select that would change
+ * what is true.
+ */
+export function parseCoreHealthRequest(value) {
+    const open = opened(value);
+    if (!open.ok)
+        return open;
+    const head = envelope(open.value);
+    if (!head.ok)
+        return head;
+    return {
+        ok: true,
+        value: {
+            protocol: head.value.protocol,
+            requestId: head.value.requestId,
+            deadlineMs: head.value.deadlineMs,
+        },
+    };
+}
+//# sourceMappingURL=validate.js.map