@deepwatch/dsh-trajectory 0.1.0

package/lib/projection.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The Watch projection over DSH's session log, and its replay guarantee.
+ *
+ * Replay is the property that makes a receipt worth anything. If reopening a
+ * finished session could produce a different picture of it, then the picture
+ * is an opinion rather than a record, and a verdict shown in it proves nothing
+ * about what happened at the time.
+ *
+ * So this is a pure fold: the same events in, the same projection out, with no
+ * clock read, no network, no model, and nothing regenerated. `projectionHash`
+ * makes that assertable rather than assumed — two runs over the same log
+ * produce the same hash, and a change to what a record carries changes it.
+ *
+ * @module @deepwatch/dsh-trajectory/projection
+ */
+import type { SessionEventLike, WatchTrajectoryRecord } from './events.js';
+/** The Watch view of one session. */
+export interface WatchProjection {
+    readonly sessionId: string;
+    /** Records in log order. Ordering is by DSH sequence, never by wall clock. */
+    readonly records: readonly WatchTrajectoryRecord[];
+    /** Evidence id to the record that produced it, for citation resolution. */
+    readonly byEvidence: ReadonlyMap<string, WatchTrajectoryRecord>;
+    /** Record id to record, for deep-link restoration. */
+    readonly byRecord: ReadonlyMap<string, WatchTrajectoryRecord>;
+}
+/** An empty projection, so a session with no Watch activity is still a value. */
+export declare function emptyProjection(sessionId: string): WatchProjection;
+/**
+ * Fold a session's events into the Watch projection.
+ *
+ * Deliberately takes the events rather than a live session: the same function
+ * serves the live view and replay, so there is no second code path whose
+ * output could differ from the one people trust.
+ *
+ * @param events - DSH session events in ascending sequence order.
+ * @param sessionId - the session these belong to.
+ */
+export declare function project(events: readonly SessionEventLike[], sessionId: string): WatchProjection;
+/**
+ * Merge externally-produced records into a projection.
+ *
+ * Memory records do not come from tool results — memory influences a turn
+ * without the agent calling anything — so they are contributed rather than
+ * derived. They are sorted into the same sequence order so the ledger stays
+ * one chronology rather than two lists shown together.
+ */
+export declare function withRecords(projection: WatchProjection, extra: readonly WatchTrajectoryRecord[]): WatchProjection;
+/**
+ * A stable hash of what a projection contains.
+ *
+ * Over the identifiers and the verdict, not over wall-clock times or free
+ * text: a replay that produced the same records at the same sequence numbers
+ * with the same verdicts *is* the same projection, and a hash that also
+ * covered the summary line would fail whenever someone improved the wording.
+ *
+ * Not cryptographic, and not trying to be. It exists to catch a projection
+ * that changed, not to resist someone forging one.
+ */
+export declare function projectionHash(projection: WatchProjection): string;
+/**
+ * Resolve a deep-linked selection against a projection.
+ *
+ * Returns the record a link points at, preferring the record id and falling
+ * back to the evidence id — a link made before a record id changed still opens
+ * the right evidence, which is the part a person cared about.
+ */
+export declare function resolveRecord(projection: WatchProjection, selection: {
+    readonly recordId: string | null;
+    readonly evidenceId: string | null;
+}): WatchTrajectoryRecord | null;
+//# sourceMappingURL=projection.d.ts.map

package/lib/projection.js

@@ -0,0 +1,174 @@
+/**
+ * The Watch projection over DSH's session log, and its replay guarantee.
+ *
+ * Replay is the property that makes a receipt worth anything. If reopening a
+ * finished session could produce a different picture of it, then the picture
+ * is an opinion rather than a record, and a verdict shown in it proves nothing
+ * about what happened at the time.
+ *
+ * So this is a pure fold: the same events in, the same projection out, with no
+ * clock read, no network, no model, and nothing regenerated. `projectionHash`
+ * makes that assertable rather than assumed — two runs over the same log
+ * produce the same hash, and a change to what a record carries changes it.
+ *
+ * @module @deepwatch/dsh-trajectory/projection
+ */
+import { isWatchTool, recordsFromToolResult, toolResultValue } from './events.js';
+/** An empty projection, so a session with no Watch activity is still a value. */
+export function emptyProjection(sessionId) {
+    return {
+        sessionId,
+        records: [],
+        byEvidence: new Map(),
+        byRecord: new Map(),
+    };
+}
+function str(value) {
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * Fold a session's events into the Watch projection.
+ *
+ * Deliberately takes the events rather than a live session: the same function
+ * serves the live view and replay, so there is no second code path whose
+ * output could differ from the one people trust.
+ *
+ * @param events - DSH session events in ascending sequence order.
+ * @param sessionId - the session these belong to.
+ */
+export function project(events, sessionId) {
+    const pending = new Map();
+    const records = [];
+    for (const event of events) {
+        if (event.type === 'tool/call') {
+            const name = str(event.data['name']);
+            if (!isWatchTool(name))
+                continue;
+            const callId = str(event.data['callId']);
+            if (callId === null)
+                continue;
+            pending.set(callId, {
+                name: name,
+                turn: num(event.data['turn']),
+                step: num(event.data['step']),
+                // Correlation travels in the tool arguments when the caller set one;
+                // it is what ties this row to Watch Core's own logs and receipts.
+                correlationId: str(event.data['arguments']?.['correlationId']),
+            });
+            continue;
+        }
+        if (event.type !== 'tool/result')
+            continue;
+        const message = event.data['message'];
+        const source = message?.['source'];
+        const callId = str(source?.['callId']);
+        if (callId === null)
+            continue;
+        const call = pending.get(callId);
+        if (call === undefined)
+            continue;
+        pending.delete(callId);
+        const context = {
+            sessionId,
+            turn: call.turn,
+            step: call.step,
+            callId,
+            toolName: call.name,
+            correlationId: call.correlationId,
+        };
+        records.push(...recordsFromToolResult(event, context, toolResultValue(event)));
+    }
+    return index(sessionId, records);
+}
+/**
+ * Merge externally-produced records into a projection.
+ *
+ * Memory records do not come from tool results — memory influences a turn
+ * without the agent calling anything — so they are contributed rather than
+ * derived. They are sorted into the same sequence order so the ledger stays
+ * one chronology rather than two lists shown together.
+ */
+export function withRecords(projection, extra) {
+    if (extra.length === 0)
+        return projection;
+    const merged = [...projection.records, ...extra]
+        .sort((a, b) => {
+        const bySeq = a.seq - b.seq;
+        return bySeq !== 0 ? bySeq : a.recordId.localeCompare(b.recordId);
+    });
+    return index(projection.sessionId, merged);
+}
+/** Build the lookup maps once, so callers never scan. */
+function index(sessionId, records) {
+    const byEvidence = new Map();
+    const byRecord = new Map();
+    for (const record of records) {
+        byRecord.set(record.recordId, record);
+        for (const evidenceId of record.refs.evidenceIds) {
+            // First writer wins: the record that produced a piece of evidence is the
+            // one a citation should select, not a later one that merely cites it.
+            if (!byEvidence.has(evidenceId))
+                byEvidence.set(evidenceId, record);
+        }
+    }
+    return { sessionId, records, byEvidence, byRecord };
+}
+/**
+ * A stable hash of what a projection contains.
+ *
+ * Over the identifiers and the verdict, not over wall-clock times or free
+ * text: a replay that produced the same records at the same sequence numbers
+ * with the same verdicts *is* the same projection, and a hash that also
+ * covered the summary line would fail whenever someone improved the wording.
+ *
+ * Not cryptographic, and not trying to be. It exists to catch a projection
+ * that changed, not to resist someone forging one.
+ */
+export function projectionHash(projection) {
+    const canonical = projection.records.map(record => [
+        record.recordId,
+        record.type,
+        String(record.seq),
+        record.refs.sourceRevisionId ?? '',
+        record.refs.evidenceIds.join(','),
+        record.refs.verificationId ?? '',
+        record.refs.verdict ?? '',
+        record.refs.receiptId ?? '',
+        record.refs.memoryIds.join(','),
+        record.refs.temporalRange === null
+            ? ''
+            : `${String(record.refs.temporalRange.startMs)}-${String(record.refs.temporalRange.endMs)}`,
+        record.redacted ? 'redacted' : '',
+    ].join('|')).join('\n');
+    // FNV-1a, 64-bit, in BigInt. Chosen because it is short, dependency-free,
+    // and identical in every runtime this projection is compared across.
+    let hash = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    const mask = 0xffffffffffffffffn;
+    for (const byte of new TextEncoder().encode(canonical)) {
+        hash = ((hash ^ BigInt(byte)) * prime) & mask;
+    }
+    return `fnv1a64:${hash.toString(16).padStart(16, '0')}`;
+}
+/**
+ * Resolve a deep-linked selection against a projection.
+ *
+ * Returns the record a link points at, preferring the record id and falling
+ * back to the evidence id — a link made before a record id changed still opens
+ * the right evidence, which is the part a person cared about.
+ */
+export function resolveRecord(projection, selection) {
+    if (selection.recordId !== null) {
+        const byId = projection.byRecord.get(selection.recordId);
+        if (byId !== undefined)
+            return byId;
+    }
+    if (selection.evidenceId !== null) {
+        return projection.byEvidence.get(selection.evidenceId) ?? null;
+    }
+    return null;
+}
+//# sourceMappingURL=projection.js.map

package/lib/selection-store.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The one selection every Watch surface reads and writes.
+ *
+ * DSH's Trajectory selection is documented as local to Trajectory, with no
+ * anchor deep links. This is the smallest additive extension around that: a
+ * Watch-owned service holding the canonical selection for Watch-related
+ * records, which surfaces subscribe to. Nothing upstream is replaced — DSH
+ * keeps its own local selection, and Watch drives it from here.
+ *
+ * A store rather than a value, because several panels need to observe the same
+ * change; but the value it holds is the pure `WatchSelection` from
+ * `@deepwatch/dsh-trajectory`, so every rule about what a selection means
+ * stays testable without a browser.
+ *
+ * @module @deepwatch/dsh-trajectory/selection-store
+ */
+import type { WatchSelection } from './selection.js';
+import type { WatchProjection } from './projection.js';
+/** Notified whenever the selection changes. */
+export type SelectionListener = (selection: WatchSelection) => void;
+/**
+ * Holds the canonical Watch selection for one workspace.
+ *
+ * Deliberately has no knowledge of panels. A panel subscribes and renders; it
+ * never asks another panel what is selected, which is what stops the panels
+ * from disagreeing.
+ */
+export declare class WatchSelectionStore {
+    private current;
+    private readonly listeners;
+    /** The latest projection, so a deep link can resolve without a round trip. */
+    private projection;
+    constructor(workspaceId: string, sessionId: string);
+    /** The current selection. Always a value; never undefined. */
+    get(): WatchSelection;
+    /**
+     * Replace the selection.
+     *
+     * A selection identical to the current one is dropped rather than
+     * broadcast. Panels both read and write this store, so an echo would loop:
+     * a panel reacts to its own change, re-selects, and notifies again.
+     */
+    set(selection: WatchSelection): void;
+    /** Subscribe; returns an unsubscribe function. */
+    subscribe(listener: SelectionListener): () => void;
+    /** Publish the projection a deep link should resolve against. */
+    setProjection(projection: WatchProjection): void;
+    /** The current projection, or null before the session has loaded. */
+    getProjection(): WatchProjection | null;
+    /** A link that restores the current selection. */
+    link(): string;
+    /**
+     * Restore a selection from a link.
+     *
+     * @returns whether the fragment was a Watch link that named a session. A
+     * fragment that is not one leaves the selection alone rather than clearing
+     * it to a half-restored state.
+     */
+    restore(fragment: string): boolean;
+    /** Release every subscriber. Called when the plugin unloads. */
+    dispose(): void;
+}
+//# sourceMappingURL=selection-store.d.ts.map

package/lib/selection-store.js

@@ -0,0 +1,108 @@
+/**
+ * The one selection every Watch surface reads and writes.
+ *
+ * DSH's Trajectory selection is documented as local to Trajectory, with no
+ * anchor deep links. This is the smallest additive extension around that: a
+ * Watch-owned service holding the canonical selection for Watch-related
+ * records, which surfaces subscribe to. Nothing upstream is replaced — DSH
+ * keeps its own local selection, and Watch drives it from here.
+ *
+ * A store rather than a value, because several panels need to observe the same
+ * change; but the value it holds is the pure `WatchSelection` from
+ * `@deepwatch/dsh-trajectory`, so every rule about what a selection means
+ * stays testable without a browser.
+ *
+ * @module @deepwatch/dsh-trajectory/selection-store
+ */
+import { emptySelection, fromDeepLink, toDeepLink } from './selection.js';
+/**
+ * Holds the canonical Watch selection for one workspace.
+ *
+ * Deliberately has no knowledge of panels. A panel subscribes and renders; it
+ * never asks another panel what is selected, which is what stops the panels
+ * from disagreeing.
+ */
+export class WatchSelectionStore {
+    current;
+    listeners = new Set();
+    /** The latest projection, so a deep link can resolve without a round trip. */
+    projection = null;
+    constructor(workspaceId, sessionId) {
+        this.current = emptySelection(workspaceId, sessionId);
+    }
+    /** The current selection. Always a value; never undefined. */
+    get() {
+        return this.current;
+    }
+    /**
+     * Replace the selection.
+     *
+     * A selection identical to the current one is dropped rather than
+     * broadcast. Panels both read and write this store, so an echo would loop:
+     * a panel reacts to its own change, re-selects, and notifies again.
+     */
+    set(selection) {
+        if (isSame(this.current, selection))
+            return;
+        this.current = selection;
+        for (const listener of this.listeners)
+            listener(selection);
+    }
+    /** Subscribe; returns an unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /** Publish the projection a deep link should resolve against. */
+    setProjection(projection) {
+        this.projection = projection;
+    }
+    /** The current projection, or null before the session has loaded. */
+    getProjection() {
+        return this.projection;
+    }
+    /** A link that restores the current selection. */
+    link() {
+        return toDeepLink(this.current);
+    }
+    /**
+     * Restore a selection from a link.
+     *
+     * @returns whether the fragment was a Watch link that named a session. A
+     * fragment that is not one leaves the selection alone rather than clearing
+     * it to a half-restored state.
+     */
+    restore(fragment) {
+        const restored = fromDeepLink(fragment);
+        if (restored === null)
+            return false;
+        this.set(restored);
+        return true;
+    }
+    /** Release every subscriber. Called when the plugin unloads. */
+    dispose() {
+        this.listeners.clear();
+        this.projection = null;
+    }
+}
+/**
+ * Whether two selections point at the same thing.
+ *
+ * `origin` is excluded on purpose: it records which surface moved, not what is
+ * selected, and including it would make every panel's echo look like a change.
+ */
+function isSame(left, right) {
+    return left.workspaceId === right.workspaceId
+        && left.sessionId === right.sessionId
+        && left.recordId === right.recordId
+        && left.evidenceId === right.evidenceId
+        && left.sourceId === right.sourceId
+        && left.sourceRevisionId === right.sourceRevisionId
+        && left.verificationId === right.verificationId
+        && left.receiptId === right.receiptId
+        && left.memoryId === right.memoryId
+        && left.atMs === right.atMs
+        && left.endMs === right.endMs
+        && left.inspectorTab === right.inspectorTab;
+}
+//# sourceMappingURL=selection-store.js.map

package/lib/selection.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The Unified Selection Model, and the deep links that serialize it.
+ *
+ * One canonical selection, not one per panel. That is the whole design: a
+ * citation in an answer, a row in Trajectory, a position in a player and the
+ * Evidence Inspector are four *projections* of the same value, so selecting in
+ * any of them moves all of them, and there is no state to reconcile between
+ * them because there is only one.
+ *
+ * DSH's own Trajectory selection is documented as local to Trajectory, with no
+ * anchor deep links. This is the smallest additive Watch-owned extension
+ * around it: Watch holds the canonical selection for Watch-related records and
+ * drives Trajectory's local selection from it, rather than replacing anything
+ * upstream owns.
+ *
+ * Everything here is pure. A selection is a value, not a store.
+ *
+ * @module @deepwatch/dsh-trajectory/selection
+ */
+import type { WatchTrajectoryRecord } from './events.js';
+/** Which inspector panel a selection opens. */
+export type InspectorTab = 'evidence' | 'verification' | 'receipt' | 'memory' | 'source';
+/**
+ * The one selection every Watch surface responds to.
+ *
+ * Identifiers only. A selection that carried evidence *content* would be a
+ * second copy of it, and the copy in a URL would be one nobody could
+ * invalidate.
+ */
+export interface WatchSelection {
+    readonly workspaceId: string;
+    readonly sessionId: string;
+    /** The Trajectory record, when the selection came from or points at one. */
+    readonly recordId: string | null;
+    readonly evidenceId: string | null;
+    readonly sourceId: string | null;
+    readonly sourceRevisionId: string | null;
+    readonly verificationId: string | null;
+    readonly receiptId: string | null;
+    readonly memoryId: string | null;
+    /** Where in the source, in milliseconds. */
+    readonly atMs: number | null;
+    readonly endMs: number | null;
+    readonly inspectorTab: InspectorTab | null;
+    /** Which surface initiated it, so a surface can skip echoing itself. */
+    readonly origin: string;
+}
+/** A selection with nothing selected, for a fresh session. */
+export declare function emptySelection(workspaceId: string, sessionId: string): WatchSelection;
+/**
+ * Which inspector panel a record should open.
+ *
+ * Derived rather than stored, so a record selected from Trajectory and the
+ * same record reached from a citation land on the same panel.
+ */
+export declare function tabForRecord(record: WatchTrajectoryRecord): InspectorTab;
+/**
+ * Select one Trajectory record.
+ *
+ * This is the reverse direction of the round trip: a Watch row in Trajectory
+ * resolves to the same evidence, timestamp and receipt a citation would.
+ */
+export declare function selectRecord(base: WatchSelection, record: WatchTrajectoryRecord, origin?: string): WatchSelection;
+/** One citation as an answer carries it. */
+export interface CitationRef {
+    readonly evidenceId: string;
+    readonly sourceRevisionId: string | null;
+    readonly atMs: number | null;
+    readonly endMs?: number | null;
+}
+/**
+ * Select a citation from an agent answer.
+ *
+ * The forward direction: clicking a timestamp in an answer resolves the exact
+ * source revision and moment, and finds the Trajectory record that produced
+ * it. `records` is searched rather than trusted from the citation, because the
+ * record is the thing Trajectory can highlight and the citation only knows its
+ * own evidence id.
+ */
+export declare function selectCitation(base: WatchSelection, citation: CitationRef, records: readonly WatchTrajectoryRecord[], origin?: string): WatchSelection;
+/** Whether two selections point at the same thing, ignoring which surface moved. */
+export declare function sameSelection(left: WatchSelection, right: WatchSelection): boolean;
+/**
+ * Serialize a selection as a deep link fragment.
+ *
+ * A fragment rather than a query string, and identifiers rather than content.
+ * A fragment is not sent to a server, which matters because these ids point at
+ * someone's private session; and a link that carried evidence *text* would be
+ * a copy nobody could invalidate when the underlying source changed.
+ *
+ * @returns the fragment including its leading `#`, so it can be appended
+ * directly to a workspace URL.
+ */
+export declare function toDeepLink(selection: WatchSelection): string;
+/**
+ * Restore a selection from a deep link.
+ *
+ * Returns null when the fragment is not a Watch link or names no session — a
+ * link that cannot identify what it points at should leave the current
+ * selection alone rather than clearing it to a half-restored state.
+ *
+ * Unknown parameters are ignored rather than rejected, so a link produced by a
+ * newer build still opens the part this one understands.
+ */
+export declare function fromDeepLink(fragment: string): WatchSelection | null;
+//# sourceMappingURL=selection.d.ts.map