@deepwatch/dsh-live 0.1.0

package/lib/session.js

@@ -0,0 +1,280 @@
+/**
+ * Live: watching something while it is still happening.
+ *
+ * The engine already produces live observations. What did not exist was the
+ * client half — and the client half is where every interesting failure lives,
+ * because a live surface has to be correct about time it did not see.
+ *
+ * Four decisions carry this module.
+ *
+ * **A cursor is the only ordering authority.** Events are read by cursor, and
+ * a repeated cursor returns the same events. That makes a retry free: a caller
+ * that times out, reconnects and re-asks cannot lose an event or receive one
+ * twice, which is what makes a flaky network a nuisance instead of a source of
+ * fabricated history.
+ *
+ * **A gap is a fact, not a rendering problem.** When a delta does not continue
+ * from the cursor the client holds, the client does not interpolate, does not
+ * guess, and does not quietly skip forward. It records a gap with its own
+ * range and asks for a fresh snapshot. The gap stays in the buffer afterwards.
+ * Every alternative — smoothing, backfilling, "probably nothing happened" —
+ * converts missing evidence into evidence, which is the one thing this product
+ * cannot do.
+ *
+ * **Three clocks, never one.** Wall clock, media clock and session clock
+ * disagree constantly during a live observation, and each answers a different
+ * question: when did this happen in the world, where is it in the source, and
+ * how far into watching are we. Collapsing them produces a subtitle attributed
+ * to the wrong second.
+ *
+ * **The buffer is bounded.** A session left running for eight hours must not
+ * grow a browser tab without limit. Trimming drops the oldest ordinary events
+ * and keeps three things forever: gaps, pinned moments, and the count of what
+ * was trimmed. A buffer that silently forgot a gap would let a long session
+ * end up looking cleaner than a short one.
+ *
+ * @module @deepwatch/dsh-live/session
+ */
+/** The default bound. Roughly an hour of dense observation. */
+export const DEFAULT_LIMITS = { maxEvents: 2000 };
+/** Begin a session, before anything has been observed. */
+export function startSession(input) {
+    return {
+        sessionId: input.sessionId,
+        target: input.target,
+        kind: input.kind,
+        status: 'starting',
+        connection: 'connecting',
+        cursor: '',
+        startedAtMs: input.startedAtMs,
+        events: [],
+        gaps: [],
+        pinned: [],
+        clocks: { wallMs: null, mediaMs: null, sessionMs: 0, latencyMs: null },
+        trimmed: 0,
+        needsSnapshot: false,
+        lastError: null,
+    };
+}
+/** Recompute the clocks from the newest event. */
+function clocksFrom(state, events, nowMs) {
+    const newest = events[events.length - 1];
+    if (newest === undefined) {
+        return { wallMs: null, mediaMs: null, sessionMs: nowMs - state.startedAtMs, latencyMs: null };
+    }
+    return {
+        wallMs: newest.at,
+        mediaMs: newest.mediaMs,
+        sessionMs: nowMs - state.startedAtMs,
+        // Never negative. A clock skew that made the newest event look like it
+        // arrived from the future would render as a nonsense latency.
+        latencyMs: Math.max(0, nowMs - newest.at),
+    };
+}
+/**
+ * Trim the buffer to its bound.
+ *
+ * Gaps and pinned events survive. The trim count is carried so the surface can
+ * say "1,204 earlier events dropped" rather than presenting a partial history
+ * as a complete one.
+ */
+function bound(events, pinned, limits) {
+    if (events.length <= limits.maxEvents)
+        return { events, dropped: 0 };
+    const pinnedEvidence = new Set(pinned.flatMap(moment => moment.evidenceIds));
+    const keepAlways = (event) => event.kind === 'gap' || event.evidenceIds.some(id => pinnedEvidence.has(id));
+    const protectedEvents = events.filter(keepAlways);
+    const ordinary = events.filter(event => !keepAlways(event));
+    const room = Math.max(0, limits.maxEvents - protectedEvents.length);
+    const kept = ordinary.slice(Math.max(0, ordinary.length - room));
+    const keptIds = new Set([...protectedEvents, ...kept].map(event => event.seq));
+    return {
+        events: events.filter(event => keptIds.has(event.seq)),
+        dropped: ordinary.length - kept.length,
+    };
+}
+/** Mint the gap a cursor break implies, with the range it actually covers. */
+function cursorBreakGap(state, delta) {
+    const last = state.events[state.events.length - 1];
+    const next = delta.events[0];
+    if (last === undefined || next === undefined)
+        return null;
+    return {
+        seq: last.seq + 0.5,
+        cursor: state.cursor,
+        kind: 'gap',
+        at: last.at,
+        mediaMs: last.mediaMs,
+        text: 'observation gap — the stream did not continue from the last cursor',
+        range: last.mediaMs === null || next.mediaMs === null
+            ? null
+            : { startMs: last.mediaMs, endMs: next.mediaMs },
+        evidenceIds: [],
+    };
+}
+/**
+ * Apply one delta or snapshot to the session.
+ *
+ * The three cases, in the order they are checked:
+ *
+ * 1. **A snapshot** replaces the event view outright and clears
+ *    `needsSnapshot`. This is the only thing that re-establishes continuity.
+ * 2. **A delta that continues from the held cursor** appends. This is the
+ *    ordinary case.
+ * 3. **A delta that does not** is a break. A gap event is minted at the seam,
+ *    `needsSnapshot` is set, and the delta's events are *not* appended —
+ *    appending them would splice two discontinuous stretches into something
+ *    that reads as continuous.
+ *
+ * Re-applying the same delta is a no-op, which is what makes a retry safe.
+ */
+export function applyDelta(state, delta, nowMs, limits = DEFAULT_LIMITS) {
+    const engineGaps = delta.gaps ?? [];
+    if (delta.isSnapshot) {
+        const { events, dropped } = bound(delta.events, state.pinned, limits);
+        return {
+            ...state,
+            status: delta.status,
+            connection: delta.status === 'observing' ? 'live' : state.connection,
+            cursor: delta.nextCursor,
+            events,
+            gaps: mergeGaps(state.gaps, [...engineGaps, ...rangesOf(delta.events)]),
+            clocks: clocksFrom(state, events, nowMs),
+            trimmed: state.trimmed + dropped,
+            needsSnapshot: false,
+            lastError: null,
+        };
+    }
+    // An already-applied delta. Returning the same state is what makes a retry
+    // after a timeout free rather than a source of duplicates.
+    if (delta.nextCursor === state.cursor)
+        return state;
+    if (delta.fromCursor !== state.cursor) {
+        const gap = cursorBreakGap(state, delta);
+        const events = gap === null ? state.events : [...state.events, gap];
+        return {
+            ...state,
+            connection: 'reconnecting',
+            events,
+            gaps: mergeGaps(state.gaps, gap?.range === null || gap?.range === undefined ? [] : [gap.range]),
+            clocks: clocksFrom(state, events, nowMs),
+            needsSnapshot: true,
+            lastError: `cursor ${delta.fromCursor} does not continue from `
+                + (state.cursor === '' ? '(start)' : state.cursor),
+        };
+    }
+    const appended = [...state.events, ...delta.events];
+    const { events, dropped } = bound(appended, state.pinned, limits);
+    return {
+        ...state,
+        status: delta.status,
+        connection: delta.status === 'observing' ? 'live' : state.connection,
+        cursor: delta.nextCursor,
+        events,
+        gaps: mergeGaps(state.gaps, [...engineGaps, ...rangesOf(delta.events)]),
+        clocks: clocksFrom(state, events, nowMs),
+        trimmed: state.trimmed + dropped,
+        lastError: null,
+    };
+}
+/** Ranges of the gap events in a batch. */
+function rangesOf(events) {
+    return events
+        .filter(event => event.kind === 'gap' && event.range !== null)
+        .map(event => event.range);
+}
+/** Union of two gap lists, deduplicated and ordered. */
+function mergeGaps(existing, incoming) {
+    const seen = new Map();
+    for (const range of [...existing, ...incoming]) {
+        seen.set(`${String(range.startMs)}:${String(range.endMs)}`, range);
+    }
+    return [...seen.values()].sort((left, right) => left.startMs - right.startMs);
+}
+/** Record that the channel dropped. */
+export function connectionLost(state, reason) {
+    return {
+        ...state,
+        connection: 'lost',
+        // A lost connection always needs a snapshot on return. Even if no event
+        // was missed, the client cannot know that, and assuming it is how a gap
+        // goes unrecorded.
+        needsSnapshot: true,
+        lastError: reason,
+    };
+}
+/** Record that a reconnect attempt is under way. */
+export function reconnecting(state) {
+    return { ...state, connection: 'reconnecting' };
+}
+/**
+ * Pin a moment.
+ *
+ * Pinning protects the events it references from being trimmed. That is the
+ * whole reason pins take evidence ids: a pin that pointed only at a timestamp
+ * would survive a trim while the thing it pointed at did not.
+ */
+export function pinMoment(state, moment) {
+    if (state.pinned.some(existing => existing.momentId === moment.momentId))
+        return state;
+    return { ...state, pinned: [...state.pinned, moment] };
+}
+/** Stop the session, keeping or discarding what it observed. */
+export function finish(state, finalize) {
+    return {
+        ...state,
+        status: finalize ? 'finalized' : 'discarded',
+        connection: 'stopped',
+    };
+}
+/** Freeze a finished session into its replay record. */
+export function toReplay(state) {
+    return {
+        sessionId: state.sessionId,
+        target: state.target,
+        kind: state.kind,
+        status: state.status,
+        events: state.events,
+        gaps: state.gaps,
+        pinned: state.pinned,
+        trimmed: state.trimmed,
+    };
+}
+/**
+ * Digest of a replay, so "reopening it shows the same thing" is assertable.
+ *
+ * FNV-1a over event identity and gap ranges — the same construction the
+ * trajectory projection uses, and for the same reason.
+ */
+export function replayDigest(replay) {
+    let hash = 0x811c9dc5;
+    const feed = (text) => {
+        for (let index = 0; index < text.length; index += 1) {
+            hash ^= text.charCodeAt(index);
+            hash = Math.imul(hash, 0x01000193) >>> 0;
+        }
+    };
+    feed(`${replay.sessionId}|${replay.status}|${String(replay.trimmed)}`);
+    for (const event of replay.events)
+        feed(`|${String(event.seq)}:${event.kind}:${event.cursor}`);
+    for (const gap of replay.gaps)
+        feed(`|gap:${String(gap.startMs)}-${String(gap.endMs)}`);
+    return hash.toString(16).padStart(8, '0');
+}
+/**
+ * One line describing the session's honesty, for the surface header.
+ *
+ * Always says the gap count and the trim count, including when both are zero.
+ * A message that appears only when something is wrong is a message people
+ * learn to not look for.
+ */
+export function describeContinuity(state) {
+    const parts = [
+        state.gaps.length === 0 ? 'no gaps' : `${String(state.gaps.length)} gap(s)`,
+        state.trimmed === 0 ? 'nothing dropped' : `${String(state.trimmed)} earlier event(s) dropped`,
+    ];
+    if (state.needsSnapshot)
+        parts.push('view not continuous — resnapshot pending');
+    return parts.join(' · ');
+}
+//# sourceMappingURL=session.js.map

package/lib/sources-catalogue.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The sources Live can offer, and what each one honestly is.
+ *
+ * A source appears here whether or not this machine can run it, because a
+ * catalogue that hid unavailable sources would answer the wrong question: a
+ * person wants to know what the product can observe *and* why it cannot observe
+ * it here. Hiding the second is how "the feature does not exist" and "your
+ * machine cannot do it" become indistinguishable.
+ *
+ * Two entries deserve their separation. **Browser Observer** watches a page and
+ * records what it showed; **Browser Operator** acts on one and returns a
+ * receipt for what it did. They are listed apart because they are apart: one
+ * capability that covered both would grant the power to act while a person
+ * believed they were enabling the power to watch, and no amount of wording in a
+ * tooltip fixes a control that does two things.
+ *
+ * @module @deepwatch/dsh-live/sources-catalogue
+ */
+import type { SourceAvailability } from './capture.js';
+/** How a source is reached, which decides what it needs to run. */
+export type SourceRuntime = 
+/** Provided by the browser or the Electron shell. */
+'shell'
+/** A device attached to this machine. */
+ | 'device'
+/** A process this machine starts. */
+ | 'process'
+/** Synthetic, for tests. Talks to nothing. */
+ | 'fixture';
+export interface LiveSource {
+    readonly id: string;
+    readonly name: string;
+    /** What it observes, in a sentence. */
+    readonly what: string;
+    /** When it would ask, so nobody is surprised by a prompt. */
+    readonly asks: string;
+    readonly runtime: SourceRuntime;
+    /** Whether using it needs an OS permission at all. */
+    readonly needsOsPermission: boolean;
+    /**
+     * Whether it can act on the world rather than only record it.
+     *
+     * Exactly one source is `true`, and it is the one whose name says so.
+     */
+    readonly canAct: boolean;
+}
+export declare const SOURCES: readonly LiveSource[];
+/** One source by id, or undefined. */
+export declare function sourceById(id: string): LiveSource | undefined;
+/**
+ * A short, honest word for how a source stands right now.
+ *
+ * Availability is a runtime fact, so the catalogue never claims it. Without an
+ * adapter's probe, the truthful answer is that nothing has been started —
+ * which is different from unavailable, and different again from broken.
+ */
+export declare function describeAvailability(availability?: SourceAvailability): string;
+/**
+ * The synthetic adapter's availability.
+ *
+ * Always available, because it invents its own content and reaches nothing.
+ * This is the source the end-to-end capture test uses: exercising the real
+ * lifecycle without capturing a single pixel of anybody's actual screen.
+ */
+export declare function syntheticAvailability(): SourceAvailability;
+//# sourceMappingURL=sources-catalogue.d.ts.map

package/lib/sources-catalogue.js

@@ -0,0 +1,110 @@
+/**
+ * The sources Live can offer, and what each one honestly is.
+ *
+ * A source appears here whether or not this machine can run it, because a
+ * catalogue that hid unavailable sources would answer the wrong question: a
+ * person wants to know what the product can observe *and* why it cannot observe
+ * it here. Hiding the second is how "the feature does not exist" and "your
+ * machine cannot do it" become indistinguishable.
+ *
+ * Two entries deserve their separation. **Browser Observer** watches a page and
+ * records what it showed; **Browser Operator** acts on one and returns a
+ * receipt for what it did. They are listed apart because they are apart: one
+ * capability that covered both would grant the power to act while a person
+ * believed they were enabling the power to watch, and no amount of wording in a
+ * tooltip fixes a control that does two things.
+ *
+ * @module @deepwatch/dsh-live/sources-catalogue
+ */
+export const SOURCES = [
+    {
+        id: 'screen',
+        name: 'Screen',
+        what: 'The whole display, as a continuous observation.',
+        asks: 'Asks for screen-capture permission the first time you start it.',
+        runtime: 'shell',
+        needsOsPermission: true,
+        canAct: false,
+    },
+    {
+        id: 'window',
+        name: 'Window',
+        what: 'One application window rather than the whole display.',
+        asks: 'Asks for screen-capture permission the first time you start it.',
+        runtime: 'shell',
+        needsOsPermission: true,
+        canAct: false,
+    },
+    {
+        id: 'camera',
+        name: 'Camera',
+        what: 'Live visual input from an attached device.',
+        asks: 'Asks for camera permission the first time you start it.',
+        runtime: 'device',
+        needsOsPermission: true,
+        canAct: false,
+    },
+    {
+        id: 'microphone',
+        name: 'Microphone',
+        what: 'Live audio, with timings a citation can point at.',
+        asks: 'Asks for microphone permission the first time you start it.',
+        runtime: 'device',
+        needsOsPermission: true,
+        canAct: false,
+    },
+    {
+        id: 'browser-observer',
+        name: 'Browser Observer',
+        what: 'Watches a page and records what it showed. Takes no action.',
+        asks: 'No OS permission. Needs the browser runtime enabled.',
+        runtime: 'process',
+        needsOsPermission: false,
+        canAct: false,
+    },
+    {
+        id: 'browser-operator',
+        name: 'Browser Operator',
+        what: 'Acts on a page and returns a receipt for what it did. A separate capability from observing.',
+        asks: 'No OS permission. Needs the browser runtime enabled, and every side effect carries an idempotency key.',
+        runtime: 'process',
+        needsOsPermission: false,
+        canAct: true,
+    },
+    {
+        id: 'synthetic',
+        name: 'Synthetic source',
+        what: 'A task-owned page this workspace generates, for exercising capture without touching anything of yours.',
+        asks: 'No permission. It observes only content this workspace created.',
+        runtime: 'fixture',
+        needsOsPermission: false,
+        canAct: false,
+    },
+];
+/** One source by id, or undefined. */
+export function sourceById(id) {
+    return SOURCES.find(source => source.id === id);
+}
+/**
+ * A short, honest word for how a source stands right now.
+ *
+ * Availability is a runtime fact, so the catalogue never claims it. Without an
+ * adapter's probe, the truthful answer is that nothing has been started —
+ * which is different from unavailable, and different again from broken.
+ */
+export function describeAvailability(availability) {
+    if (availability === undefined)
+        return 'Not started';
+    return availability.available ? 'Available' : availability.reason;
+}
+/**
+ * The synthetic adapter's availability.
+ *
+ * Always available, because it invents its own content and reaches nothing.
+ * This is the source the end-to-end capture test uses: exercising the real
+ * lifecycle without capturing a single pixel of anybody's actual screen.
+ */
+export function syntheticAvailability() {
+    return { available: true, reason: '' };
+}
+//# sourceMappingURL=sources-catalogue.js.map

package/lib/synthetic-source.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A capture source that observes only what this workspace made.
+ *
+ * The end-to-end capture test needs a real source: something that genuinely
+ * starts, genuinely emits timestamped observations, and genuinely releases what
+ * it held. Pointing that test at a screen or a camera would capture whatever
+ * happened to be in front of the person running it — their email, their
+ * terminal, their face — and put it in a fixture directory. That is not a test
+ * anyone should run twice.
+ *
+ * So the source generates its own content on a deterministic clock and observes
+ * that. It exercises every state the real adapters do — probe, permission,
+ * start, emit, stop, teardown — while reading nothing it did not write.
+ *
+ * It is not a mock of an adapter. It is an adapter, of a source that happens to
+ * be synthetic, which is why the lifecycle it exercises is the real one.
+ *
+ * @module @deepwatch/dsh-live/synthetic-source
+ */
+import type { CaptureAdapter, Observation, SourceAvailability } from './capture.js';
+export interface SyntheticOptions {
+    /** Lines to emit, in order. The content this source will observe. */
+    readonly script: readonly string[];
+    /** Milliseconds between emissions. Small so tests stay fast. */
+    readonly intervalMs?: number;
+    /** Refuse permission, to exercise the denial path. */
+    readonly refusePermission?: boolean;
+    /** Report unavailable, to exercise the missing-source path. */
+    readonly unavailable?: string;
+    /** Throw on start, to exercise the failure path. */
+    readonly failOnStart?: boolean;
+    /** Never signal started, to exercise the timeout path. */
+    readonly hangOnStart?: boolean;
+    readonly now?: () => Date;
+}
+/**
+ * A source that writes its own content and then observes it.
+ *
+ * `emitted` and `released` are exposed so a test can assert the things that
+ * matter most and are hardest to see: that every timer was cleared, and that
+ * teardown ran exactly once however the session ended.
+ */
+export declare class SyntheticSource implements CaptureAdapter {
+    #private;
+    readonly sourceId = "synthetic";
+    constructor(options: SyntheticOptions);
+    /** How many observations it produced. */
+    get emitted(): number;
+    /** How many times teardown ran. Must never exceed one. */
+    get releases(): number;
+    /** Whether anything is still scheduled. Must be false after any ending. */
+    get running(): boolean;
+    probe(): SourceAvailability;
+    requestPermission(): boolean;
+    start(emit: (observation: Observation) => void): Promise<void>;
+    stop(): void;
+}
+//# sourceMappingURL=synthetic-source.d.ts.map

package/lib/synthetic-source.js

@@ -0,0 +1,96 @@
+/**
+ * A capture source that observes only what this workspace made.
+ *
+ * The end-to-end capture test needs a real source: something that genuinely
+ * starts, genuinely emits timestamped observations, and genuinely releases what
+ * it held. Pointing that test at a screen or a camera would capture whatever
+ * happened to be in front of the person running it — their email, their
+ * terminal, their face — and put it in a fixture directory. That is not a test
+ * anyone should run twice.
+ *
+ * So the source generates its own content on a deterministic clock and observes
+ * that. It exercises every state the real adapters do — probe, permission,
+ * start, emit, stop, teardown — while reading nothing it did not write.
+ *
+ * It is not a mock of an adapter. It is an adapter, of a source that happens to
+ * be synthetic, which is why the lifecycle it exercises is the real one.
+ *
+ * @module @deepwatch/dsh-live/synthetic-source
+ */
+import { observationAt } from './capture.js';
+import { syntheticAvailability } from './sources-catalogue.js';
+/**
+ * A source that writes its own content and then observes it.
+ *
+ * `emitted` and `released` are exposed so a test can assert the things that
+ * matter most and are hardest to see: that every timer was cleared, and that
+ * teardown ran exactly once however the session ended.
+ */
+export class SyntheticSource {
+    sourceId = 'synthetic';
+    #options;
+    #timer = null;
+    #emitted = 0;
+    #releases = 0;
+    #base = null;
+    #now;
+    constructor(options) {
+        this.#options = options;
+        this.#now = options.now ?? (() => new Date());
+    }
+    /** How many observations it produced. */
+    get emitted() { return this.#emitted; }
+    /** How many times teardown ran. Must never exceed one. */
+    get releases() { return this.#releases; }
+    /** Whether anything is still scheduled. Must be false after any ending. */
+    get running() { return this.#timer !== null; }
+    probe() {
+        if (this.#options.unavailable !== undefined) {
+            return { available: false, reason: this.#options.unavailable };
+        }
+        return syntheticAvailability();
+    }
+    requestPermission() {
+        // A synthetic source still goes through the permission gate. Skipping it
+        // because "it is only a fixture" would mean the lifecycle the test proves
+        // is not the lifecycle that ships.
+        return this.#options.refusePermission !== true;
+    }
+    async start(emit) {
+        if (this.#options.failOnStart === true)
+            throw new Error('the synthetic source was asked to fail');
+        if (this.#options.hangOnStart === true) {
+            // Resolve never. The session's own timeout is what has to save it, and
+            // that is precisely what this exercises.
+            return new Promise(() => { });
+        }
+        this.#base = this.#now();
+        const interval = this.#options.intervalMs ?? 5;
+        let index = 0;
+        await new Promise(resolve => {
+            this.#timer = setInterval(() => {
+                const line = this.#options.script[index];
+                if (line === undefined) {
+                    this.#clear();
+                    return;
+                }
+                emit(observationAt(this.#base ?? this.#now(), this.#now(), 'text', line, index));
+                this.#emitted += 1;
+                index += 1;
+            }, interval);
+            // Started means "producing", not "finished producing".
+            resolve();
+        });
+    }
+    stop() {
+        this.#clear();
+        this.#releases += 1;
+    }
+    #clear() {
+        if (this.#timer !== null) {
+            clearInterval(this.#timer);
+            this.#timer = null;
+        }
+    }
+}
+//# sourceMappingURL=synthetic-source.js.map