@deepwatch/dsh-trajectory 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,71 @@
+# @deepwatch/dsh-trajectory
+
+Watch records inside the DeepSeek Harness Trajectory, with unified selection, deep links and replay
+
+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-trajectory`
+
+## 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-trajectory
+```
+
+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`
+
+## 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
+
+Puts Watch records inside the Harness Trajectory, so a receipt, a verdict and the turn that produced them share one selection, one deep link and one replay.
+
+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/compare.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Comparing two observations of the same thing.
+ *
+ * The question Compare answers is narrower than "what changed", and much more
+ * useful: **where did these first stop agreeing?** A diff of two long runs
+ * produces hundreds of differences, most of them consequences of the first
+ * one, and a person reading it has to work backwards to find the moment that
+ * mattered. So the first divergence is a first-class result rather than
+ * something to scroll for.
+ *
+ * Two rules carry over from the rest of the product.
+ *
+ * **A difference is not a failure.** Most changes between two runs are the
+ * change somebody asked for. Compare surfaces divergences; deciding whether
+ * one was expected is a verification contract, and Compare never issues a
+ * verdict of its own.
+ *
+ * **Comparison is over identifiers, not content.** Two evidence records are
+ * compared by revision, range and digest. Compare holds no evidence payloads,
+ * so it cannot become a second place where evidence lives.
+ *
+ * @module @deepwatch/dsh-trajectory/compare
+ */
+import type { WatchProjection } from './projection.js';
+/** What is being compared. */
+export type CompareSubject = 
+/** Two runs of the same task. */
+'run'
+/** Two revisions of the same source. */
+ | 'source_revision'
+/** Two time ranges, in the same source or in two. */
+ | 'temporal_region'
+/**
+ * The same thing before and after a change was made.
+ *
+ * Named separately from `temporal_region` because it carries an
+ * expectation: somebody did something in between, and the question is
+ * whether the difference is the one they intended. Compare still issues no
+ * verdict — that remains a verification contract — but the surface reads
+ * differently when it knows a change was deliberate.
+ */
+ | 'before_after';
+/** Every subject, for enumerating the picker. */
+export declare const COMPARE_SUBJECTS: readonly CompareSubject[];
+/** Which signal a divergence was found in. */
+export type DivergenceChannel = 'visual' | 'text' | 'ocr' | 'transcript' | 'dom' | 'network' | 'console' | 'verification' | 'receipt';
+/** How the two sides differ. */
+export type DivergenceKind = 
+/** Present on the left, absent on the right. */
+'removed'
+/** Absent on the left, present on the right. */
+ | 'added'
+/** Present on both, different. */
+ | 'changed'
+/** Present on both, and the difference is only in timing. */
+ | 'retimed';
+/** One place two sides stopped agreeing. */
+export interface Divergence {
+    readonly channel: DivergenceChannel;
+    readonly kind: DivergenceKind;
+    /** Where in the source, so the player can go there. */
+    readonly atMs: number | null;
+    /** The record on each side, by id. Never the content. */
+    readonly leftRecordId: string | null;
+    readonly rightRecordId: string | null;
+    readonly leftEvidenceId: string | null;
+    readonly rightEvidenceId: string | null;
+    /** One line for a list. Presentation only; nothing resolves from it. */
+    readonly summary: string;
+}
+/** The result of comparing two sides. */
+export interface Comparison {
+    readonly subject: CompareSubject;
+    readonly leftId: string;
+    readonly rightId: string;
+    readonly divergences: readonly Divergence[];
+    /**
+     * The earliest divergence, or null when the two agree.
+     *
+     * The answer people actually want. Everything after the first divergence is
+     * usually a consequence of it, and presenting a hundred differences equally
+     * makes the one that mattered harder to find, not easier.
+     */
+    readonly firstDivergence: Divergence | null;
+    /** Records present on both sides and identical. */
+    readonly agreements: number;
+}
+/**
+ * The minimum of an evidence record Compare needs to place it on a channel.
+ *
+ * A structural subset rather than an import of `EvidenceRecord`: the
+ * trajectory package holds no evidence payloads, and taking the full type here
+ * would invite one to be stored.
+ */
+export interface ChannelHint {
+    readonly modality: 'visual' | 'text' | 'audio' | 'dom' | 'network' | 'filesystem';
+}
+/** Evidence ids to what sense produced them, when the caller has resolved any. */
+export type ChannelHints = ReadonlyMap<string, ChannelHint>;
+/**
+ * Compare two projections.
+ *
+ * Pure, and deterministic for the same inputs — which is what lets a
+ * comparison be deep-linked and replayed like anything else in the product.
+ *
+ * @param subject - what the two sides are: two runs, two revisions, two regions.
+ */
+export declare function compareProjections(left: WatchProjection, right: WatchProjection, subject: CompareSubject, ids: {
+    readonly leftId: string;
+    readonly rightId: string;
+}, hints?: ChannelHints): Comparison;
+/**
+ * Whether a comparison found a change in what was *established*.
+ *
+ * Separate from "found any difference" on purpose. Two runs producing
+ * different evidence at a different moment is normal; two runs reaching
+ * different verdicts is the thing somebody needs to look at.
+ */
+export declare function hasVerdictDivergence(comparison: Comparison): boolean;
+/**
+ * A stable digest of a comparison.
+ *
+ * Same inputs, same digest — so a comparison can be deep-linked, replayed and
+ * checked for change the same way a projection can. Over identifiers and kinds
+ * only, never over the summary text.
+ */
+export declare function comparisonDigest(comparison: Comparison): string;
+/**
+ * The first divergence that changed what was *established*.
+ *
+ * Distinct from `firstDivergence`, and the distinction is the useful one. The
+ * earliest difference between two runs is frequently a timestamp or an extra
+ * frame; the earliest difference in a verdict or a receipt is the moment the
+ * two runs stopped being the same outcome. A surface that offered only the
+ * first would send people to the wrong second.
+ */
+export declare function firstMeaningfulDivergence(comparison: Comparison): Divergence | null;
+/**
+ * A deep link to one side of a divergence.
+ *
+ * Built from the same selection model everything else in the product uses, so
+ * a link out of Compare opens the same inspector a link out of Trajectory
+ * would. Returns null when the side has nothing to point at, rather than a
+ * link that resolves to an empty panel.
+ */
+export declare function divergenceLink(comparison: Comparison, divergence: Divergence, side: 'left' | 'right', context: {
+    readonly workspaceId: string;
+    readonly sessionId: string;
+}): string | null;
+/**
+ * A portable comparison.
+ *
+ * Identifiers, kinds and links — never evidence content, for the same reason
+ * `Divergence` carries none. An exported bundle that inlined what it compared
+ * would be a second copy of the evidence, and a second copy is one nobody can
+ * invalidate.
+ */
+export interface ComparisonBundle {
+    readonly digest: string;
+    readonly subject: CompareSubject;
+    readonly leftId: string;
+    readonly rightId: string;
+    readonly agreements: number;
+    readonly divergences: readonly Divergence[];
+    readonly firstDivergence: Divergence | null;
+    readonly firstMeaningfulDivergence: Divergence | null;
+    readonly links: readonly {
+        readonly side: 'left' | 'right';
+        readonly link: string;
+    }[];
+}
+/** Freeze a comparison into something that can be attached to a report. */
+export declare function exportComparison(comparison: Comparison, context: {
+    readonly workspaceId: string;
+    readonly sessionId: string;
+}): ComparisonBundle;
+/**
+ * One line summarizing a comparison.
+ *
+ * Deliberately never says "passed" or "failed". Compare reports where two
+ * things stopped agreeing; whether that was the change somebody asked for is a
+ * verification contract, and a summary that editorialized would be Compare
+ * issuing the verdict it is not allowed to issue.
+ */
+export declare function describeComparison(comparison: Comparison): string;
+//# sourceMappingURL=compare.d.ts.map

package/lib/compare.js

@@ -0,0 +1,314 @@
+/**
+ * Comparing two observations of the same thing.
+ *
+ * The question Compare answers is narrower than "what changed", and much more
+ * useful: **where did these first stop agreeing?** A diff of two long runs
+ * produces hundreds of differences, most of them consequences of the first
+ * one, and a person reading it has to work backwards to find the moment that
+ * mattered. So the first divergence is a first-class result rather than
+ * something to scroll for.
+ *
+ * Two rules carry over from the rest of the product.
+ *
+ * **A difference is not a failure.** Most changes between two runs are the
+ * change somebody asked for. Compare surfaces divergences; deciding whether
+ * one was expected is a verification contract, and Compare never issues a
+ * verdict of its own.
+ *
+ * **Comparison is over identifiers, not content.** Two evidence records are
+ * compared by revision, range and digest. Compare holds no evidence payloads,
+ * so it cannot become a second place where evidence lives.
+ *
+ * @module @deepwatch/dsh-trajectory/compare
+ */
+import { toDeepLink } from './selection.js';
+/** Every subject, for enumerating the picker. */
+export const COMPARE_SUBJECTS = [
+    'run', 'source_revision', 'temporal_region', 'before_after',
+];
+/** The channel one evidence modality belongs to. */
+function channelForModality(modality) {
+    switch (modality) {
+        case 'visual':
+            return 'visual';
+        case 'audio':
+            return 'transcript';
+        case 'text':
+            return 'ocr';
+        case 'dom':
+            return 'dom';
+        case 'network':
+            return 'network';
+        case 'filesystem':
+            return 'text';
+    }
+}
+/**
+ * Which channel a record's evidence belongs to.
+ *
+ * Verdicts and receipts are decided by the record type, because that is what
+ * they are. Everything else needs the evidence, and when the caller has not
+ * resolved it the answer is `text` rather than a guess — filing an unresolved
+ * record under `visual` because most evidence is visual is how a transcript
+ * divergence ends up reported as a picture changing.
+ */
+function channelFor(record, hints) {
+    switch (record.type) {
+        case 'verification.completed':
+        case 'verification.requested':
+            return 'verification';
+        case 'browser.action.receipt':
+        case 'browser.action.dispatched':
+            return 'receipt';
+        default: {
+            for (const evidenceId of record.refs.evidenceIds) {
+                const hint = hints.get(evidenceId);
+                if (hint !== undefined)
+                    return channelForModality(hint.modality);
+            }
+            return 'text';
+        }
+    }
+}
+/**
+ * A key identifying "the same thing" across two sides.
+ *
+ * Deliberately not the record id: two runs produce different ids for the same
+ * step, and comparing by id would report every record as both added and
+ * removed. What makes two records comparable is what they are *about* — the
+ * channel and the moment.
+ */
+function alignmentKey(record, hints) {
+    const at = record.refs.temporalRange?.startMs ?? null;
+    return `${channelFor(record, hints)}:${at === null ? 'untimed' : String(at)}`;
+}
+/** Whether two aligned records actually agree. */
+function agrees(left, right) {
+    // Compared by identifier, never by content: the evidence itself lives at
+    // Watch Core, and a comparison that read payloads would need a copy of them.
+    return left.refs.sourceRevisionId === right.refs.sourceRevisionId
+        && left.refs.evidenceIds.join(',') === right.refs.evidenceIds.join(',')
+        && left.refs.verdict === right.refs.verdict
+        && left.refs.receiptId === right.refs.receiptId;
+}
+/** Describe how two aligned records differ. */
+function describeChange(left, right) {
+    if (left.refs.verdict !== right.refs.verdict) {
+        // The most important difference there is: the same step reached a
+        // different conclusion. Named explicitly rather than folded into "changed".
+        return {
+            kind: 'changed',
+            summary: `verdict ${left.refs.verdict ?? 'none'} → ${right.refs.verdict ?? 'none'}`,
+        };
+    }
+    if (left.refs.sourceRevisionId !== right.refs.sourceRevisionId) {
+        return { kind: 'changed', summary: 'a different source revision' };
+    }
+    if (left.refs.evidenceIds.join(',') !== right.refs.evidenceIds.join(',')) {
+        return {
+            kind: 'changed',
+            summary: `${String(left.refs.evidenceIds.length)} → ${String(right.refs.evidenceIds.length)} evidence record(s)`,
+        };
+    }
+    return { kind: 'changed', summary: 'differs' };
+}
+/**
+ * Compare two projections.
+ *
+ * Pure, and deterministic for the same inputs — which is what lets a
+ * comparison be deep-linked and replayed like anything else in the product.
+ *
+ * @param subject - what the two sides are: two runs, two revisions, two regions.
+ */
+export function compareProjections(left, right, subject, ids, hints = new Map()) {
+    const leftByKey = new Map();
+    const rightByKey = new Map();
+    for (const record of left.records)
+        leftByKey.set(alignmentKey(record, hints), record);
+    for (const record of right.records)
+        rightByKey.set(alignmentKey(record, hints), record);
+    const divergences = [];
+    let agreements = 0;
+    const keys = [...new Set([...leftByKey.keys(), ...rightByKey.keys()])].sort();
+    for (const key of keys) {
+        const leftRecord = leftByKey.get(key);
+        const rightRecord = rightByKey.get(key);
+        if (leftRecord !== undefined && rightRecord !== undefined) {
+            if (agrees(leftRecord, rightRecord)) {
+                agreements += 1;
+                continue;
+            }
+            const change = describeChange(leftRecord, rightRecord);
+            divergences.push({
+                channel: channelFor(leftRecord, hints),
+                kind: change.kind,
+                atMs: leftRecord.refs.temporalRange?.startMs ?? null,
+                leftRecordId: leftRecord.recordId,
+                rightRecordId: rightRecord.recordId,
+                leftEvidenceId: leftRecord.refs.evidenceIds[0] ?? null,
+                rightEvidenceId: rightRecord.refs.evidenceIds[0] ?? null,
+                summary: change.summary,
+            });
+            continue;
+        }
+        const present = leftRecord ?? rightRecord;
+        if (present === undefined)
+            continue;
+        const removed = rightRecord === undefined;
+        divergences.push({
+            channel: channelFor(present, hints),
+            kind: removed ? 'removed' : 'added',
+            atMs: present.refs.temporalRange?.startMs ?? null,
+            leftRecordId: removed ? present.recordId : null,
+            rightRecordId: removed ? null : present.recordId,
+            leftEvidenceId: removed ? present.refs.evidenceIds[0] ?? null : null,
+            rightEvidenceId: removed ? null : present.refs.evidenceIds[0] ?? null,
+            summary: removed ? 'only in the first' : 'only in the second',
+        });
+    }
+    // Ordered by when they happened, so "first" means first in the source rather
+    // than first in an arbitrary map iteration. Untimed divergences sort last:
+    // they cannot be placed on a timeline, and putting them first would hide a
+    // real early divergence behind them.
+    const ordered = [...divergences].sort((a, b) => {
+        if (a.atMs === b.atMs)
+            return a.channel.localeCompare(b.channel);
+        if (a.atMs === null)
+            return 1;
+        if (b.atMs === null)
+            return -1;
+        return a.atMs - b.atMs;
+    });
+    return {
+        subject,
+        leftId: ids.leftId,
+        rightId: ids.rightId,
+        divergences: ordered,
+        firstDivergence: ordered[0] ?? null,
+        agreements,
+    };
+}
+/**
+ * Whether a comparison found a change in what was *established*.
+ *
+ * Separate from "found any difference" on purpose. Two runs producing
+ * different evidence at a different moment is normal; two runs reaching
+ * different verdicts is the thing somebody needs to look at.
+ */
+export function hasVerdictDivergence(comparison) {
+    return comparison.divergences.some(divergence => divergence.channel === 'verification');
+}
+/**
+ * A stable digest of a comparison.
+ *
+ * Same inputs, same digest — so a comparison can be deep-linked, replayed and
+ * checked for change the same way a projection can. Over identifiers and kinds
+ * only, never over the summary text.
+ */
+export function comparisonDigest(comparison) {
+    const canonical = [
+        comparison.subject,
+        comparison.leftId,
+        comparison.rightId,
+        String(comparison.agreements),
+        ...comparison.divergences.map(divergence => [
+            divergence.channel,
+            divergence.kind,
+            divergence.atMs === null ? '' : String(divergence.atMs),
+            divergence.leftRecordId ?? '',
+            divergence.rightRecordId ?? '',
+        ].join('|')),
+    ].join('\n');
+    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')}`;
+}
+/**
+ * The first divergence that changed what was *established*.
+ *
+ * Distinct from `firstDivergence`, and the distinction is the useful one. The
+ * earliest difference between two runs is frequently a timestamp or an extra
+ * frame; the earliest difference in a verdict or a receipt is the moment the
+ * two runs stopped being the same outcome. A surface that offered only the
+ * first would send people to the wrong second.
+ */
+export function firstMeaningfulDivergence(comparison) {
+    return comparison.divergences.find(divergence => divergence.channel === 'verification' || divergence.channel === 'receipt') ?? comparison.firstDivergence;
+}
+/**
+ * A deep link to one side of a divergence.
+ *
+ * Built from the same selection model everything else in the product uses, so
+ * a link out of Compare opens the same inspector a link out of Trajectory
+ * would. Returns null when the side has nothing to point at, rather than a
+ * link that resolves to an empty panel.
+ */
+export function divergenceLink(comparison, divergence, side, context) {
+    const recordId = side === 'left' ? divergence.leftRecordId : divergence.rightRecordId;
+    const evidenceId = side === 'left' ? divergence.leftEvidenceId : divergence.rightEvidenceId;
+    if (recordId === null && evidenceId === null)
+        return null;
+    return toDeepLink({
+        workspaceId: context.workspaceId,
+        sessionId: side === 'left' ? comparison.leftId : comparison.rightId,
+        recordId,
+        evidenceId,
+        sourceId: null,
+        sourceRevisionId: null,
+        verificationId: null,
+        receiptId: null,
+        memoryId: null,
+        atMs: divergence.atMs,
+        endMs: null,
+        inspectorTab: divergence.channel === 'verification' ? 'verification' : 'evidence',
+        origin: 'compare',
+    });
+}
+/** Freeze a comparison into something that can be attached to a report. */
+export function exportComparison(comparison, context) {
+    const meaningful = firstMeaningfulDivergence(comparison);
+    const links = [];
+    if (meaningful !== null) {
+        for (const side of ['left', 'right']) {
+            const link = divergenceLink(comparison, meaningful, side, context);
+            if (link !== null)
+                links.push({ side, link });
+        }
+    }
+    return {
+        digest: comparisonDigest(comparison),
+        subject: comparison.subject,
+        leftId: comparison.leftId,
+        rightId: comparison.rightId,
+        agreements: comparison.agreements,
+        divergences: comparison.divergences,
+        firstDivergence: comparison.firstDivergence,
+        firstMeaningfulDivergence: meaningful,
+        links,
+    };
+}
+/**
+ * One line summarizing a comparison.
+ *
+ * Deliberately never says "passed" or "failed". Compare reports where two
+ * things stopped agreeing; whether that was the change somebody asked for is a
+ * verification contract, and a summary that editorialized would be Compare
+ * issuing the verdict it is not allowed to issue.
+ */
+export function describeComparison(comparison) {
+    if (comparison.divergences.length === 0) {
+        return `No divergence across ${String(comparison.agreements)} aligned record(s).`;
+    }
+    const meaningful = firstMeaningfulDivergence(comparison);
+    const where = meaningful?.atMs === null || meaningful === null
+        ? 'at an untimed record'
+        : `at ${String(meaningful.atMs)}ms`;
+    return `${String(comparison.divergences.length)} divergence(s), `
+        + `${String(comparison.agreements)} agreement(s). `
+        + `First meaningful: ${meaningful?.channel ?? 'none'} ${where}.`;
+}
+//# sourceMappingURL=compare.js.map

package/lib/definition.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Watch records registered into DeepSeek Harness's own event system.
+ *
+ * This is the seam the plan insists on. Watch does **not** build a second
+ * tracker: it registers a `ConversationNodeDefinition` into
+ * `ctx.conversationEvents` — the same registry Trajectory itself uses — and a
+ * view target into `ctx.conversationViews`. Both read the single session event
+ * log DSH already owns.
+ *
+ * What that buys is not tidiness. It means a Watch record and the Tool record
+ * it came from cannot disagree about when something happened, because they are
+ * two projections of the same event at the same sequence number. A separate
+ * Watch ledger would eventually drift, and the drift would be invisible.
+ *
+ * The Trajectory *contribution* union is closed in upstream's own package, so
+ * Watch rows cannot be injected into the existing Trajectory ledger without an
+ * upstream patch. Rather than take one, Watch registers its own view target
+ * over the same events — the arrangement upstream already uses for `chat` and
+ * `trajectory`, and additive by construction.
+ *
+ * @module @deepwatch/dsh-trajectory/definition
+ */
+import type { WatchProjection } from './projection.js';
+import type { WatchTrajectoryRecord } from './events.js';
+/**
+ * The two DSH registries this module needs.
+ *
+ * Structural rather than imported from Cordis: these are two method
+ * signatures, and taking a framework dependency for them would tie a pure
+ * module to a runtime it never uses. The browser half passes its real context.
+ */
+export interface WatchRegistries {
+    readonly conversationEvents: {
+        register(definition: unknown): void;
+    };
+    readonly conversationViews: {
+        register(definition: unknown): void;
+    };
+}
+/** The view target Watch publishes. Distinct from `trajectory` and `chat`. */
+export declare const WATCH_TARGET = "watchEvidence";
+/**
+ * The Watch event Definition.
+ *
+ * Typed structurally rather than against upstream's exported generics: this
+ * package must build outside the DSH monorepo, where those types are reachable
+ * only through the packages the browser bundle is allowed to import. The shape
+ * is checked against the real contract by the round-trip tests, which run the
+ * same extraction over real event shapes.
+ */
+export declare function watchTrajectoryDefinition(sessionId: string): unknown;
+/** The node shape the view builder folds. */
+interface WatchViewNode {
+    readonly key: string;
+    readonly anchorSeq: number;
+    readonly data: {
+        readonly records: readonly WatchTrajectoryRecord[];
+    };
+}
+/**
+ * The Watch view target's incremental builder.
+ *
+ * Rebuilds the whole projection on change rather than patching it. The record
+ * set for one session is small — tens of rows, not thousands — and a full fold
+ * is the same code path replay uses, so the live view and a reopened one
+ * cannot diverge. Patching would be faster and would introduce exactly the
+ * class of bug this whole design exists to rule out.
+ */
+declare class WatchViewBuilder {
+    private readonly sessionId;
+    readonly empty: WatchProjection;
+    private nodes;
+    constructor(sessionId: string);
+    replace(input: {
+        nodes: readonly WatchViewNode[];
+    }): WatchProjection;
+    patch(input: {
+        nodes: readonly WatchViewNode[];
+    }): WatchProjection;
+    private build;
+}
+/**
+ * Register the Watch definition and view target.
+ *
+ * Both registrations ride Cordis effects, so unloading the plugin removes them
+ * and the workspace returns to stock DSH with no Watch rows and no leftover
+ * target — which is the uninstall path the bundle promises.
+ */
+export declare function registerWatchTrajectory(ctx: WatchRegistries, sessionId: string): void;
+export { WatchViewBuilder };
+//# sourceMappingURL=definition.d.ts.map