@loxel.dev/pharos-browser 0.6.0

package/dist/replay/triggers.d.ts

@@ -0,0 +1,48 @@
+import { type BufferedEvent, type ReplayBuffer } from './buffer';
+import type { DegradationRecord, ResolvedRecorderConfig, Sink, TriggerSource, WindowDropReason } from './config';
+/**
+ * The ceiling on post-roll extension, measured from the FIRST trigger. Without
+ * it a page erroring continuously every few hundred milliseconds would defer
+ * its flush forever and ship nothing at all.
+ */
+export declare const TRIGGER_MAX_WINDOW_EXTENSION_MS = 30000;
+export interface TriggerCoordinatorOptions {
+    buffer: ReplayBuffer;
+    sink: Sink;
+    config: ResolvedRecorderConfig;
+    /** Read at flush time, so a degradation recorded during the post-roll still rides along. */
+    degraded: () => DegradationRecord[];
+    now: () => number;
+    setTimer: (cb: () => void, ms: number) => unknown;
+    clearTimer: (handle: unknown) => void;
+    /**
+     * Notified instead of `sink` when a window fails one of the two closed
+     * gates below. Optional and additive (slice B2, Task 9): absent, both drops
+     * remain as silent as B1 shipped them.
+     */
+    onDrop?: (reason: WindowDropReason) => void;
+}
+export interface TriggerCoordinator {
+    trigger(source: TriggerSource): void;
+    /** Flushes the in-flight window immediately. `unloaded` marks a post-roll cut short by navigation. */
+    flushNow(unloaded: boolean): void;
+    /** Abandons any in-flight post-roll without shipping. `stop()` uses this. */
+    cancel(): void;
+    pending(): boolean;
+    /**
+     * ALWAYS-ON SESSION REPLAY (issue #793): ships a checkpoint-closed segment
+     * as its OWN window, independent of `pending` and of every trigger above.
+     * Every session is recorded this way, not just the ones with an error — an
+     * error still gets its own trigger window (pre-roll/post-roll, unchanged),
+     * this is what makes a session WITHOUT one still produce something.
+     *
+     * `events` already begins with its own full snapshot — that is the
+     * checkpoint invariant `buffer.ts` guarantees for every closed segment — so
+     * there is no pre-roll to wait for and no post-roll to extend: the closed
+     * segment already IS the window, `occurrences` is always 1 (there is no
+     * burst to de-duplicate), and this ships SYNCHRONOUSLY rather than through
+     * `pending`'s timer machinery.
+     */
+    checkpoint(events: readonly BufferedEvent[], startedAt: number, unloaded: boolean): void;
+}
+export declare function createTriggerCoordinator(opts: TriggerCoordinatorOptions): TriggerCoordinator;

package/dist/replay/upload.d.ts

@@ -0,0 +1,194 @@
+import type { ReplayWindow, Sink } from './config';
+import { type DropLedger } from './drops';
+/**
+ * The largest DECODED (pre-base64) window body this sink will attempt to
+ * upload. COMPUTED, not copied, from the same two constants
+ * `replay_ingest.lox`'s `MAX_WINDOW_BYTES` derives from — `(transport cap -
+ * header allowance) * 3/4`, because base64 inflates by 4/3 and this measures
+ * the bytes BEFORE that inflation, exactly like the server's own check
+ * (`Bytes.length(blob)` there, `body.byteLength` here — the same
+ * measurement on each end of the wire). A drift in EITHER source constant
+ * changes this the same way it changes the server's, rather than requiring
+ * this file to be re-tuned by hand against a result it did not derive.
+ *
+ * THIS IS NOT A SECOND CAP THAT CAN GO OUT OF SYNC WITH ITS OWN REASONING:
+ * it uses the identical formula, but it genuinely cannot IMPORT the server's
+ * Loxel constants (no shared build-time source between the two languages),
+ * so a change to `read_request.lox`'s `DEFAULT_MAX_BODY_BYTES` or
+ * `replay_ingest.lox`'s `TRANSPORT_HEADER_ALLOWANCE` still has to be
+ * mirrored here by hand. That residual coupling is real and is called out
+ * in the task report rather than hidden.
+ */
+export declare const MAX_WINDOW_BYTES: number;
+/**
+ * Serializes and gzips a window. Falls back to an uncompressed body with
+ * `compressed: false` when `CompressionStream` does not exist in the host —
+ * measured in happy-dom/Bun (both have it; see the task report) rather than
+ * assumed, but older browsers (pre-Chrome 80/Safari 16.4) genuinely lack it.
+ */
+export declare function encodeWindow(w: ReplayWindow): Promise<{
+    body: Uint8Array;
+    compressed: boolean;
+}>;
+/**
+ * Not cryptographically important — this only needs to be unique enough to
+ * group one sink's windows under one session document
+ * (`replay_store.lox`'s `_session_key`), never used as a secret or an
+ * identity check. `crypto.randomUUID` where it exists; a low-collision
+ * fallback (timestamp + random) for hosts that predate it.
+ *
+ * EXPORTED, AND THAT IS THE POINT (final review, minor). `wire.ts` carried a
+ * verbatim duplicate of this function; two implementations of "mint a session
+ * id" is the same two-paths-that-can-diverge shape this slice keeps finding,
+ * and the two are supposed to produce interchangeable ids. It lives HERE, the
+ * lower layer, because `wire.ts` already imports from this file and the
+ * reverse edge would be a cycle.
+ */
+export declare function randomSessionId(): string;
+/**
+ * The envelope MINUS its blob — every field `_validate_upload`
+ * (`replay_ingest.lox`) reads out of the JSON body except `blob` itself.
+ *
+ * IT IS ALSO EXACTLY THE `meta` PERSISTED TO INDEXEDDB. `persist.ts` stores a
+ * raw `(Uint8Array, object)` pair and deliberately never looks inside `meta`,
+ * so making the stored meta BE the envelope-minus-blob is what lets
+ * `drainPersisted`'s `send(body, meta)` callback be adapted straight onto
+ * `postEnvelope` below — the drain path and the live path build the wire
+ * format in ONE place, this file, which is the only one verified
+ * field-for-field against the server. Re-deriving it on the drain path would
+ * be the "two code paths, one masks the other" shape this slice has hit in
+ * eight consecutive tasks.
+ */
+export interface UploadEnvelopeMeta {
+    sessionId: string;
+    trigger: ReplayWindow['trigger'];
+    degraded: ReplayWindow['degraded'];
+    config: ReplayWindow['config'];
+    compressed: boolean;
+    droppedWindows: number;
+}
+/** Where an envelope goes, and what it authenticates with. */
+export interface PostTarget {
+    /** The ingest route — `replay_ingest.lox`'s `REPLAY_PATH`, `/api/v1/client/replay`, on the Pharos base URL. */
+    endpoint: string;
+    /** Sent as `Authorization: Bearer <appKey>` — the client key `auth_env(req, "client")` resolves, same convention `index.ts`'s errors POST uses. */
+    appKey: string;
+    /** Injectable so tests never touch the network; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * THE ONE PLACE THE WIRE FORMAT IS ASSEMBLED AND SENT.
+ *
+ * Resolves `true` iff the server accepted the window (`res.ok`), `false`
+ * otherwise; REJECTS on a transport failure, because a caller that wants to
+ * treat "the network died" differently from "the server said no" must be able
+ * to, and both callers here in fact treat them identically (one drop each).
+ *
+ * `meta` is spread FIRST and `blob` added last, so the blob can never be
+ * shadowed by a stored meta that somehow carried one.
+ */
+export declare function postEnvelope(body: Uint8Array, meta: UploadEnvelopeMeta, target: PostTarget): Promise<boolean>;
+/** Projects a `ReplayWindow` onto the envelope's non-blob fields. */
+export declare function envelopeMetaFor(window: ReplayWindow, sessionId: string, compressed: boolean, droppedWindows: number): UploadEnvelopeMeta;
+/**
+ * Serializes a window for the wire, honouring an explicit `compress: false`.
+ * Shared by the live-POST path and wire.ts's persist path so a window that
+ * rests in IndexedDB is byte-for-byte the one that would have been POSTed.
+ */
+export declare function encodeForUpload(window: ReplayWindow, compress: boolean | undefined): Promise<{
+    body: Uint8Array;
+    compressed: boolean;
+}>;
+export interface UploadOptions extends PostTarget {
+    /**
+     * Force the uncompressed wire form even where `CompressionStream` exists.
+     * Defaults to compressing. This is a DIFFERENT code path from
+     * `encodeWindow`'s own fallback — see the module doc comment above — and
+     * bypasses `encodeWindow` entirely rather than compressing and then
+     * discarding the result, so setting it `false` costs nothing extra.
+     */
+    compress?: boolean;
+    /**
+     * The session id the server groups this sink's windows under
+     * (`replay_ingest.lox`'s `sessionId`, `replay_store.lox`'s
+     * `_session_key(app_id, session_id)`). OPTIONAL. Left unset, one is
+     * generated ONCE when `createUploadSink` is called and reused for every
+     * window the returned `Sink` uploads.
+     *
+     * THAT FALLBACK IS A STOPGAP AND MEANS EVERY PAGE LOAD IS AN UNRELATED
+     * SESSION, which degrades exactly the grouping slice B3's console is built
+     * to read. `startReplayUpload` (wire.ts) is what resolves a REAL one —
+     * caller-supplied, else a durable per-tab id in `sessionStorage` — and
+     * passes it here. Prefer that entry point over calling this function
+     * directly.
+     */
+    sessionId?: string;
+    /**
+     * The cumulative `droppedWindows` ledger (drops.ts). Left unset, this sink
+     * makes its own, which counts ONLY the windows THIS sink failed to deliver
+     * — not `persist.ts`'s quota evictions and not B1's silent coordinator
+     * drops. Inject the session's ledger (as `startReplayUpload` does) to get
+     * the complete number spec §7 describes.
+     */
+    drops?: DropLedger;
+    /**
+     * Observability seam. `Sink` is `(window) => void`, so an upload's promise
+     * has nowhere to go through the public contract; a caller that needs to
+     * await in-flight work (teardown, or a test that must not poll) passes this
+     * and receives the promise for each upload. The promise NEVER rejects —
+     * `uploadOne` catches everything — so an implementation may store it
+     * without adding a rejection handler.
+     */
+    track?: (inflight: Promise<void>) => void;
+    /**
+     * RELIABILITY OVER A DISRUPTED CONNECTION (issue #793 "always-on"
+     * follow-up). Called INSTEAD OF `drops.note('delivery')` when the live POST
+     * fails — a non-2xx response, a rejected `fetch`, or an encoding failure —
+     * so the window can be persisted and delivered on a later drain rather than
+     * being lost outright. Under the dashcam model a lost window cost one
+     * error's context; under always-on a flaky connection during a long session
+     * would otherwise lose most of its segments, and the session then replays
+     * WITH HOLES — harder to notice than a session missing entirely, which is
+     * why this is worth a dedicated seam rather than leaving the original
+     * `drops.note('delivery')` as the only outcome.
+     *
+     * OPTIONAL AND ADDITIVE: a caller that does not supply it keeps B2's
+     * original behaviour exactly — `drops.note('delivery')`, and the window is
+     * gone. `startReplayUpload` (wire.ts) is the wiring that supplies it,
+     * reusing `persistForLater` — the SAME function the unload path already
+     * uses to write to IndexedDB — rather than inventing a second persistence
+     * path. Reusing it also means the failure is attributed correctly: a
+     * successful persist is NOT a drop (the window is merely delayed), and only
+     * a persistence failure itself counts, under `storage` or `quota` exactly
+     * as `persist.ts` already distinguishes them.
+     *
+     * MAY REJECT OR THROW. Awaited; a failure here falls back to
+     * `drops.note('delivery')` so the window's loss is still counted rather
+     * than silently absorbed — the fallback existing does not make the window
+     * unconditionally safe.
+     */
+    onDeliveryFailure?: (window: ReplayWindow) => Promise<void> | void;
+}
+/**
+ * Builds the `Sink` B1's trigger coordinator calls (`triggers.ts`'s
+ * `opts.sink(replayWindow)`, itself inside `contained()`). Every upload is
+ * fire-and-forget: `Sink` is `(window: ReplayWindow) => void`, so nothing
+ * here may throw synchronously OR let a rejection escape asynchronously —
+ * `contained()` can only catch the former, since a `throw` inside an
+ * `async function` becomes a REJECTED PROMISE that surfaces after this
+ * function has already returned `undefined`, on a stack `contained`'s
+ * `try/catch` is no longer on. The `try/catch` inside `uploadOne` below is
+ * therefore not a second sink wrapper duplicating `contained` — it covers
+ * exactly the async failure mode `contained` structurally cannot reach, and
+ * B1's own comment in `triggers.ts` anticipated this ("If slice B2's
+ * uploader grows an internal error channel, THIS is the function that feeds
+ * it" — `droppedWindows`, folded into the next envelope, is that channel).
+ *
+ * THIS SINK ALWAYS POSTS. The unload case — where a POST cannot carry the
+ * window at all — is routed away from it BEFORE it is called, by
+ * `startReplayUpload` (wire.ts), not by a branch in here: a sink that
+ * sometimes uploads and sometimes writes to IndexedDB would be two behaviours
+ * behind one name, and the test that proved "it POSTed" could not tell you
+ * which one ran.
+ */
+export declare function createUploadSink(opts: UploadOptions): Sink;

package/dist/replay/wire.d.ts

@@ -0,0 +1,132 @@
+import { type PostTarget } from './upload';
+import { type DropLedger } from './drops';
+import type { RecorderHandle, RecorderOptions } from './config';
+/**
+ * Where the durable session id lives. `sessionStorage`, not `localStorage`,
+ * deliberately: a replay session is a browsing session — one tab, until it is
+ * closed — and `localStorage` would tie every tab and every future visit into
+ * one ever-growing "session" that `replay_store.lox`'s per-application cap
+ * would then never rotate.
+ */
+export declare const SESSION_STORAGE_KEY = "pharos-replay-session";
+/**
+ * A REAL session id, replacing Task 7's per-sink stopgap (requirement 2).
+ *
+ * THE STOPGAP'S DEFECT: `createUploadSink` generates an id when it is called,
+ * so every page load minted a fresh, unrelated one and a user's windows never
+ * grouped into a session server-side — degrading exactly the grouping slice
+ * B3's console is built to read, and making the per-application session cap
+ * count page loads rather than sessions.
+ *
+ * Three sources, in order:
+ *   1. an explicit `sessionId` — a host that already has a session concept
+ *      (`PharosContext.sessionId`) should pass it, so replay groups the same
+ *      way its errors and flags do;
+ *   2. a durable per-tab id in `sessionStorage`, which SURVIVES RELOADS AND
+ *      SAME-TAB NAVIGATIONS — this is the part that actually fixes the defect,
+ *      and it is also what makes a window drained on the next load land in the
+ *      session it belonged to;
+ *   3. a fresh random id, when storage is unavailable or refuses the write.
+ *
+ * NOTHING WAS ADDED TO B1's `ReplayWindow` (config.ts) for this, though this
+ * task authorized it. The id is a property of the UPLOAD, not of the capture:
+ * the recorder never reads it, the buffer never stores it, and the envelope
+ * carries it. Putting it on the window would have made every `ReplayWindow`
+ * in B1's own tests carry a field only slice B2 consumes, for no behaviour
+ * that is not available here. (`RecorderOptions.onWindowDropped` WAS added —
+ * see requirement 3 — because that one genuinely could not be observed from
+ * outside the recorder.)
+ */
+export declare function resolveSessionId(explicit: string | undefined, storage: Storage | null): string;
+/**
+ * Where the session's cumulative `droppedWindows` lives BETWEEN PAGE LOADS,
+ * next to the session id and with exactly the same lifecycle.
+ *
+ * --- THE DEFECT THIS CLOSES (final review, Critical 1) --------------------
+ *
+ * Two mechanisms with different lifetimes under one identity, which is the
+ * variant of this slice's recurring shape that nothing had caught: the
+ * session id SURVIVES A RELOAD (`sessionStorage`, above) while the drop
+ * ledger was minted fresh on every `startReplayUpload()` call. Both halves
+ * were verified — independently, never against each other — and the
+ * RELATIONSHIP was wrong.
+ *
+ * It matters because of what the server does with the number.
+ * `replay_store.lox`'s `_merge_dropped` takes `max(existing, incoming)`
+ * SPECIFICALLY BECAUSE the client is expected to send a running total; a
+ * max() over per-page-load counts keeps only the worst single load. A tab
+ * that reloads three times during an incident, losing two windows each time,
+ * POSTed `2`, `2`, `2` and the session document ended at `2` — while six were
+ * lost. An operator triaging in B3's console would read "2 lost": the exact
+ * false reassurance this counter exists to prevent.
+ *
+ * --- WHY THE STORED VALUE CARRIES ITS SESSION ID --------------------------
+ *
+ * Because fixing the lifetime mismatch by simply persisting a number would
+ * REINTRODUCE IT FROM THE OTHER SIDE. A host that passes an explicit
+ * `sessionId` (see `resolveSessionId`) and mints a fresh one per page load —
+ * which is exactly what `PharosContext.sessionId` does today, see the README
+ * — would then have load 2's envelope carry load 1's losses under a session
+ * id load 1 never used. Over-counting a session that lost nothing is the same
+ * class of lie as under-counting one that did.
+ *
+ * So the record is `{sessionId, total}` and a total is carried ONLY when the
+ * stored id equals the resolved one. The count's lifetime is thereby DEFINED
+ * BY the id's lifetime rather than merely running alongside it, which is the
+ * property the defect above was missing.
+ */
+export declare const SESSION_DROPS_KEY = "pharos-replay-drops";
+export interface ReplayUploadOptions extends PostTarget, Omit<RecorderOptions, 'sink' | 'onWindowDropped'> {
+    /** See `resolveSessionId`. Pass `PharosContext.sessionId` where the host has one. */
+    sessionId?: string;
+    /** Force the uncompressed wire form even where `CompressionStream` exists. */
+    compress?: boolean;
+    /**
+     * Injectable IndexedDB, so tests never touch a real browser database.
+     * Defaults to `globalThis.indexedDB`; where there is none, unload-time
+     * windows are counted as dropped rather than persisted (an environment
+     * without IndexedDB has nowhere to rest them).
+     */
+    indexedDB?: IDBFactory;
+    /** Injectable session storage for `resolveSessionId`. Pass `null` to opt out of a durable id entirely. */
+    sessionStorage?: Storage | null;
+}
+export interface ReplayUploadHandle extends RecorderHandle {
+    /** The id every window from this recorder is grouped under server-side. */
+    readonly sessionId: string;
+    /**
+     * The session's drop ledger.
+     *
+     * `total()` is the number that goes on the wire: CUMULATIVE FOR THE SESSION,
+     * carried across page loads through `sessionStorage` (`SESSION_DROPS_KEY`),
+     * which is what makes the server's `max(existing, incoming)` merge correct.
+     * `byReason()` is THIS PAGE LOAD's breakdown only — nothing on the wire
+     * carries it and nothing stores it.
+     */
+    drops(): DropLedger;
+    /**
+     * Resolves once every upload, persist, drain and clear this handle started
+     * has finished.
+     *
+     * `Sink` is fire-and-forget by contract, and `stop()` is synchronous
+     * because B1's `RecorderHandle.stop()` is — so the consent clear is
+     * necessarily asynchronous work started by a synchronous call. This is how
+     * a caller (an SPA tearing down, or a test asserting that `stop()` really
+     * emptied the store) waits for it. Never rejects.
+     */
+    settled(): Promise<void>;
+}
+/**
+ * Starts a recorder whose windows are uploaded to Pharos.
+ *
+ * THE DOCUMENTED ENTRY POINT for slice B2, and the only one that produces a
+ * complete `droppedWindows`: `createUploadSink` used directly counts only its
+ * own delivery failures (see its doc comment), while this wires B1's
+ * coordinator drops and `persist.ts`'s quota evictions into the same ledger.
+ *
+ * Takes every `RecorderOptions` field except `sink` (which it supplies) and
+ * `onWindowDropped` (which it uses), so all of B1's injectable seams —
+ * `now`, `setTimer`/`clearTimer`, `scheduleIdle`, `target`, `lifecycleTarget`,
+ * `doc` — pass straight through.
+ */
+export declare function startReplayUpload(opts: ReplayUploadOptions): ReplayUploadHandle;

package/dist/stack.d.ts

@@ -0,0 +1,8 @@
+export interface Frame {
+    fn?: string;
+    file?: string;
+    line?: number;
+    col?: number;
+}
+/** Parses a raw `Error.stack` string into structured frames, capped at 50. */
+export declare function parseStack(stack: string): Frame[];