@roku-sdk/device-test-client 0.0.0-stage → 2.19.0

package/docs/jest-integration.md

@@ -0,0 +1,331 @@
+# Jest integration
+
+Everything the SDK needs to behave like a well-behaved Jest suite is
+surfaced as a named export. There is no internal magic — you wire
+`globalSetup`, `globalTeardown`, a `setupFilesAfterEnv` file, and the
+custom `testEnvironment` explicitly. The custom environment is what
+captures the diagnostic bundles CI reviewers love.
+
+- [Overview](#overview)
+- `[createGlobalSetup](#createglobalsetup)`
+- `[createGlobalTeardown](#createglobalteardown)`
+- `[installDeviceTestHooks](#installdevicetesthooks)`
+- [Custom test environment](#custom-test-environment)
+- [Failure bundle layout](#failure-bundle-layout)
+- [Internal / deep-import only](#internal--deep-import-only)
+- [Full `jest.config.ts` example](#full-jestconfigts-example)
+
+## Overview
+
+```
+ globalSetup (once per suite, own process)
+    ├─ cleanArtifacts(test-results/)
+    ├─ resolveActiveDeviceIp + persist test-results/.device-ip
+    ├─ queryDeviceInfo + readLeaseProvisioning
+    │    └─ writeDeviceEnvSnapshot(device-env.json)
+    └─ rk server: /logs/stop + /logs/start
+
+ worker Jest process (maxWorkers: 1)
+    ├─ testEnvironment = "@roku-sdk/device-test-client/environment"
+    │    ↑ captures per-failure bundles via handleTestEvent
+    └─ setupFilesAfterEnv:
+         └─ installDeviceTestHooks({
+                client, baselineRoot, diffRoot,
+                testResultsDir, deviceEnvFile
+            })
+               ├─ (sync) register active client + baseline/diff/env roots
+               ├─ beforeAll: open device.log sink + ensureLogSession
+               ├─ beforeEach: abort on unhealthy flag
+               └─ afterAll: close sink + disposeLogSession
+
+ globalTeardown (once per suite)
+    ├─ POST /keypress/Home  (opt-out via exitToHome: false)
+    └─ POST /logs/stop
+```
+
+## `createGlobalSetup`
+
+```ts
+function createGlobalSetup(opts: GlobalSetupOptions): () => Promise<void>;
+
+interface GlobalSetupOptions {
+    /** Absolute path to the consumer's `test-results/` directory. */
+    testResultsDir: string;
+}
+```
+
+Runs once per suite, before any worker. Responsibilities:
+
+1. Reject `UPDATE_BASELINES=1` when `CI=true` (prevents drive-by
+  baseline mutation in CI).
+2. Clean stale artifacts in `testResultsDir` (preserves `.gitkeep`).
+3. Resolve device IP (`RK_DEVICE_IP` env → `.roku/` active device →
+  first registered device) and persist `test-results/.device-ip`.
+4. Query `/query/device-info` once; validate the `videoMode` against
+  `SUPPORTED_VIDEO_MODES`; write `test-results/device-env.json`, merged
+   with the provisioning provenance recorded on this job's lease (e.g.
+   `rootfsArtifactoryPath`, omitted when the pool flashes no image).
+5. Log the one-line device diagnostic.
+6. Reset the `rk server` log session (`POST /logs/stop` then
+  `POST /logs/start`) so every worker attaches to the same starting
+   buffer. Best-effort — a missing daemon is a warning, not a
+   failure.
+
+**Example — `tests/support/global-setup.ts`.**
+
+```ts
+import { createGlobalSetup } from "@roku-sdk/device-test-client";
+import { resolve } from "node:path";
+
+export default createGlobalSetup({
+    testResultsDir: resolve(__dirname, "../../test-results")
+});
+```
+
+**Common pitfall.** `testResultsDir` must be **absolute** —
+`cleanArtifacts` will delete contents relative to `process.cwd()` if
+you forget, which can surprise you.
+
+## `createGlobalTeardown`
+
+```ts
+function createGlobalTeardown(opts?: CreateGlobalTeardownOptions): () => Promise<void>;
+
+interface CreateGlobalTeardownOptions {
+    /** Override the rk server URL. Resolution precedence matches RkClient. */
+    serverUrl?: string;
+    /** Override the device IP. Defaults to `RK_DEVICE_IP`. */
+    deviceIp?: string;
+    /**
+     * Send `/keypress/Home` to the device before releasing the log session.
+     * Defaults to `true`. Set to `false` for manual post-run inspection.
+     */
+    exitToHome?: boolean;
+}
+```
+
+Runs once per suite, after every worker. Two jobs:
+
+1. `POST /keypress/Home` (opt-out) so the sideloaded channel exits
+  to the home screen instead of burning the last fixture in.
+2. `POST /logs/stop` so the daemon's connection to the device is
+  released.
+
+Both steps are best-effort — errors are warned, not thrown. A
+teardown that throws would mask real test failures.
+
+**Example — `tests/support/global-teardown.ts`.**
+
+```ts
+import { createGlobalTeardown } from "@roku-sdk/device-test-client";
+
+export default createGlobalTeardown({ exitToHome: true });
+```
+
+## `installDeviceTestHooks`
+
+```ts
+function installDeviceTestHooks(opts?: InstallDeviceTestHooksOptions): void;
+
+interface InstallDeviceTestHooksOptions {
+    /** RkClient to attach the log session against. Required if startLogSession is true. */
+    client?: RkClient;
+    /** Disable `beforeAll` log-session attach. Default `true`. */
+    startLogSession?: boolean;
+    /** Absolute path for the baselines directory (forwards to the internal `setBaselineRoot`). */
+    baselineRoot?: string;
+    /** Absolute path for screenshot diff PNGs (forwards to the internal `setScreenshotDiffRoot`). */
+    diffRoot?: string;
+    /** Absolute path to test-results/. Enables device.log + failures/<sanitized>/. */
+    testResultsDir?: string;
+    /** Absolute path to `device-env.json` (forwards to the internal `setDeviceEnvFile`). */
+    deviceEnvFile?: string;
+    /** Disable failure-bundle capture in the env. Default `true`. */
+    captureFailureBundles?: boolean;
+}
+```
+
+Must be called from a `setupFilesAfterEnv` module so Jest's
+`beforeAll` / `beforeEach` / `afterAll` globals are available. In
+v2.0.0 this is the **only** wiring entry point — the raw setter
+functions (`setActiveClient`, `setBaselineRoot`,
+`setScreenshotDiffRoot`, `setDeviceEnvFile`) are no longer exported
+from the barrel.
+
+The hook behaves in two phases:
+
+1. **Synchronous (at install time)** — registers the active client
+   and path roots so assertions that fire from a test file's
+   top-level code (e.g. a `describeOnDevice(...)` at module scope)
+   already see the correct wiring.
+2. **Jest lifecycle hooks:**
+   - `**beforeAll**` — opens `device.log` sink, subscribes it to the
+     client's log buffer, calls `await client.ensureLogSession()`.
+     The sink subscription is installed **before** `ensureLogSession`
+     so the replay batch that SSE delivers on attach lands in the log
+     file.
+   - `**beforeEach**` — if `isDeviceHealthy() === false`, throws
+     `DeviceUnhealthyError` so remaining tests in the worker abort
+     fast. This is the cascade-guard that prevents one bad deploy
+     from producing 50 downstream false positives. With
+     `deviceRecovery` enabled it first probes `waitForDeviceOnline`
+     and clears the flag if the device came back — **except** when
+     the device is latched fatally wedged (`isDeviceFatal()`, e.g.
+     `never-left-home`), where it aborts immediately without probing
+     (a wedged VM still answers ECP, so probing would falsely
+     "recover" it). See [errors.md](errors.md#fatal-device-wedge).
+   - `**afterAll**` — unsubscribes the sink, closes it, calls
+     `client.disposeLogSession()`.
+
+`diffRoot` and `testResultsDir` are also exposed to the custom test
+environment via module-global keys so `DeviceTestEnvironment` can
+locate `<root>/failures/` without re-reading your Jest config.
+
+**Example — `tests/support/setup.ts`.**
+
+```ts
+import {
+    createDefaultClient,
+    installDeviceTestHooks
+} from "@roku-sdk/device-test-client";
+import { resolve } from "node:path";
+
+const client = createDefaultClient();
+
+installDeviceTestHooks({
+    client,
+    baselineRoot: resolve(__dirname, "../baselines"),
+    testResultsDir: resolve(__dirname, "../../test-results"),
+    diffRoot: resolve(__dirname, "../../test-results/diffs"),
+    deviceEnvFile: resolve(
+        __dirname,
+        "../../test-results/device-env.json"
+    )
+});
+
+export { client };
+```
+
+## Custom test environment
+
+The package ships a Jest test environment that subclasses
+`jest-environment-node` and hooks `handleTestEvent`. It captures the
+device-side snapshot eagerly on `test_fn_failure` / `hook_failure`
+(so subsequent `buildAndDeploy` calls don't overwrite the state you
+wanted) and flushes to disk on `teardown` (once per test file).
+
+Register it in your Jest config:
+
+```ts
+// jest.config.ts
+export default {
+    testEnvironment: "@roku-sdk/device-test-client/environment"
+    // ...
+};
+```
+
+The environment is a no-op unless `installDeviceTestHooks` has
+exposed its globals (the client + `testResultsDir`), so it's safe to
+keep configured even in suites that don't use it.
+
+## Failure bundle layout
+
+```
+test-results/
+├── device.log                      # every line, one run, with header
+├── device-env.json                 # DeviceInfo snapshot + lease provenance
+├── .device-ip                      # resolved IP (worker handoff)
+├── diffs/
+│   └── home--initial.diff.png      # screenshot assertion failures
+└── failures/
+    └── <sanitized-test-path>/
+        ├── screenshot.png          # captureScreenshot() at failure
+        ├── dom-tree.json           # queryAppUi() at failure (2-space indent)
+        ├── recent-logs.txt         # last N entries, `<seq>\t<line>`
+        └── error.txt               # stack trace preferred
+```
+
+Each artifact is **best-effort** — a permissions error on
+`screenshot.png` doesn't block `error.txt`. A bundle that carries
+only `error.txt` is still useful ("test failed; no device state
+captured").
+
+## Internal / deep-import only
+
+The helpers below are used by `createGlobalSetup` /
+`createGlobalTeardown` / `installDeviceTestHooks` /
+`DeviceTestEnvironment` internally, and `installDeviceTestHooks` is
+the documented way to configure them. They are **not** exported from
+the v2.0.0 barrel (`@roku-sdk/device-test-client`) but remain
+reachable as deep imports (e.g.
+`@roku-sdk/device-test-client/src/jest/artifacts`). Deep paths are
+**not** covered by the SemVer contract — anything below may move or
+change shape in a minor release without a major bump. If you find
+yourself needing one, open an issue so we can promote a proper
+public entry point.
+
+Grouped by feature (see the source files listed for signatures):
+
+- **Failure-bundle writers** — `sanitizeTestPath`,
+  `ensureFailuresDir`, `writeFailureBundle` (src/jest/artifacts).
+  Used by the custom test environment to lay down
+  `test-results/failures/<name>/{screenshot.png,dom-tree.json,recent-logs.txt,error.txt}`
+  on each failing test. Exposed for bespoke reporters running outside
+  `DeviceTestEnvironment`.
+- **`device.log` sink + log-buffer attach** — `openDeviceLogSink`,
+  `attachToBuffer`, `DeviceLogSink`, `LogBuffer` /
+  `LogBufferOptions` / `LogBufferLike` (src/logs/*). Streams every
+  observed log line to `<testResultsDir>/device.log`.
+  `installDeviceTestHooks` drives this automatically when
+  `testResultsDir` is provided; direct use is only needed for custom
+  runners.
+- **Device-IP handoff** — `resolveActiveDeviceIp`,
+  `persistDeviceIp` (src/device/*). `createGlobalSetup` calls these;
+  bespoke setup scripts can reuse them.
+- **Device-env snapshot (sync reader)** —
+  `readCachedDeviceInfoSync`, `getDeviceEnvFile`, `setDeviceEnvFile`,
+  `resetDeviceEnvFileOverride` (src/device/device-env-sync). The
+  synchronous door into `test-results/device-env.json` that
+  `itOnDevice` / `describeOnDevice` use at registration time
+  (they cannot await). `setDeviceEnvFile` is now configured via
+  `installDeviceTestHooks({ deviceEnvFile })` at the public layer.
+- **Artifact helpers for custom globalSetup** — `cleanArtifacts`,
+  `assertSupportedVideoMode`, `writeDeviceEnvSnapshot`,
+  `logDeviceDiagnostic`, `assertBaselineUpdatesAllowed`, `isCi`
+  (src/jest/artifacts). Bundled under the one-shot
+  `createGlobalSetup` for normal consumers; exposed for users who
+  need to hand-roll a globalSetup with slightly different semantics.
+
+**Single-writer guarantee.** `maxWorkers: 1` is required — the
+`device.log` sink does not serialise across workers. Per-worker file
+naming is the consumer's problem to solve if the pin is ever
+removed.
+
+## Full `jest.config.ts` example
+
+```ts
+import type { Config } from "jest";
+
+const config: Config = {
+    preset: "ts-jest",
+    testEnvironment: "@roku-sdk/device-test-client/environment",
+    testMatch: ["<rootDir>/tests/**/*.test.ts"],
+    globalSetup: "<rootDir>/tests/support/global-setup.ts",
+    globalTeardown: "<rootDir>/tests/support/global-teardown.ts",
+    setupFilesAfterEach: ["<rootDir>/tests/support/setup.ts"],
+    maxWorkers: 1,
+    testTimeout: 60_000,
+    reporters: ["default"]
+};
+
+export default config;
+```
+
+With the four support files from this page plus at least one
+`.test.ts` using `createDefaultClient()`, `pnpm jest` will:
+
+- boot the session, snapshot the device, stream the log tail;
+- on each test run, fail fast if the device went unhealthy earlier;
+- on every failure, write `test-results/failures/<name>/{screenshot.png, dom-tree.json, recent-logs.txt, error.txt}`;
+- on exit, send `Home` and stop the log session.
+

package/docs/log-assertions.md

@@ -0,0 +1,349 @@
+# Log assertions
+
+Log assertions let tests gate on lines the device emitted to its
+telnet log port (8085). The SDK captures those lines via a host-side
+daemon, buffers them with sequence numbers, and exposes four
+primitives: **`logPosition`** (cursor), **`waitForLog`** (positive
+assertion with timeout), **`expectNoLog`** (negative assertion over a
+window), and **`logs`** (bulk read). Gaps caused by SSE reconnects
+are tracked explicitly so tests cannot silently pass on an incomplete
+stream.
+
+- [The streaming pipeline](#the-streaming-pipeline)
+- [Core types](#core-types)
+- [`logPosition`](#logposition)
+- [`waitForLog`](#waitforlog)
+- [`expectNoLog`](#expectnolog)
+- [`logs`](#logs)
+- [`ensureLogSession` / `disposeLogSession`](#ensurelogsession--disposelogsession)
+- [`logBuffer` / `recentLogLines`](#logbuffer--recentloglines)
+- [Gap semantics](#gap-semantics)
+- [Causality pattern](#causality-pattern)
+- [Errors thrown](#errors-thrown)
+- [Internal / deep-import only](#internal--deep-import-only)
+
+## The streaming pipeline
+
+```
+Roku device ──(telnet 8085)──► rk server ──(POST /logs/start + SSE /logs/tail)──► LogSession ──► LogBuffer
+```
+
+1. `rk server` owns the single TCP tail on port 8085.
+2. `LogSession` `POST`s `/logs/start` on first use (idempotent —
+   `400 "already active"` is success), then opens the SSE subscription
+   to `/logs/tail`.
+3. `LogStreamClient` parses `event: log | status | error` frames and
+   forwards them to callbacks on `LogSession`.
+4. `LogSession` appends `log` payloads to `LogBuffer` and drives gap
+   tracking from `status: reconnecting / active / stopped`.
+5. Tests read from `LogBuffer` via the `RkClient` log API.
+
+The daemon is required for log assertions only — DOM and screenshot
+assertions work without it.
+
+## Core types
+
+```ts
+type LogPosition = string;    // opaque non-negative decimal seq
+type LogLine = string;
+
+interface LogQueryOptions {
+    /** Cursor from `client.logPosition()` — inclusive lower bound. Required. */
+    since: LogPosition;
+    /** `waitForLog`: max wait (ms). Default `WAIT_FOR_LOG_DEFAULT_TIMEOUT_MS` (5 000). */
+    timeout?: number;
+    /** `expectNoLog`: window duration (ms). Alias for `timeout`. Default 5 000. */
+    window?: number;
+}
+```
+
+## `logPosition`
+
+```ts
+logPosition(): LogPosition;
+```
+
+**Synchronous.** Returns the current high-water seq as an opaque
+decimal string. Use it *immediately before* the action whose log
+output you want to observe.
+
+```ts
+const pos = client.logPosition();
+```
+
+**Common pitfall.** Grabbing `logPosition` *after* a `keypress` means
+the log line you're trying to wait for may already have arrived —
+your `since` baseline would skip past it. Take the position first.
+
+## `waitForLog`
+
+```ts
+waitForLog(pattern: RegExp, opts: LogQueryOptions): Promise<LogLine>;
+```
+
+Resolves with the first line matching `pattern` whose seq >=
+`opts.since` within `opts.timeout` ms. The method:
+
+- subscribes to `LogBuffer` appends synchronously — no polling gap
+  between the promise return and arriving lines;
+- replays any already-buffered lines >= `since` first;
+- calls `client.assertAppAlive()` on each tick so a crash during the
+  wait surfaces as `AppCrashedError`, not a timeout;
+- accepts a match whose seq is **strictly outside** every recorded
+  gap (line-integrity relaxation — see [Gap semantics](#gap-semantics)
+  below);
+- skips matches whose seq is inside a gap (the line could have
+  straddled a reconnect boundary and be malformed) but does **not**
+  abort the wait — a later clean line may still satisfy the
+  assertion before the timeout;
+- throws `LogStreamGapError` on timeout if any gap was recorded in
+  the wait window — the missing lines might have included the
+  marker, so the timeout is ambiguous, not a clean negative;
+- re-attaches the stream once, and waits a further
+  `LOG_STREAM_RESYNC_GRACE_MS`, when the window received no line at
+  all (see [Silent windows](#silent-windows));
+- throws `WaitForLogTimeoutError` on timeout with `recentLines`,
+  `position`, `timeout`.
+
+**Example.**
+
+```ts
+const pos = client.logPosition();
+await client.keypress("Select");
+const line = await client.waitForLog(/item-selected: id=(\w+)/, {
+    since: pos,
+    timeout: 2_000
+});
+
+const id = /id=(\w+)/.exec(line)?.[1];
+expect(id).toBe("abc-123");
+```
+
+## `expectNoLog`
+
+```ts
+expectNoLog(pattern: RegExp, opts: LogQueryOptions): Promise<void>;
+```
+
+Resolves after `opts.window` ms (default 5 000) iff no line matching
+`pattern` appeared in the window. Throws `UnexpectedLogError` with the
+offending `line` if one did, or `LogStreamGapError` if a gap was
+detected (the missing line *might* have matched — we cannot be
+certain).
+
+**Example — no warning after a benign action.**
+
+```ts
+const pos = client.logPosition();
+await client.keypress("Down");
+await client.expectNoLog(/WARN:|ERROR:/, { since: pos, window: 1_500 });
+```
+
+## `logs`
+
+```ts
+logs(opts: { since: LogPosition }): Promise<LogLine[]>;
+```
+
+Immediate snapshot of every line from `since` to the current
+high-water. Throws `LogStreamGapError` if a tracked gap overlaps the
+range, or `LogBufferOverflowError` if `since` is below the buffer's
+`minAvailableSeq`.
+
+**Example — post-mortem log dump.**
+
+```ts
+const pos = client.logPosition();
+await someScenario();
+const lines = await client.logs({ since: pos });
+console.log(`Captured ${lines.length} log lines:`);
+lines.forEach(l => console.log(l));
+```
+
+## `ensureLogSession` / `disposeLogSession`
+
+```ts
+ensureLogSession(): Promise<void>;
+disposeLogSession(): void;
+```
+
+`installDeviceTestHooks` calls `ensureLogSession()` once in `beforeAll`
+so the first `logPosition()` in a test file is cheap. Direct callers
+only need these in bespoke runners; `waitForLog` / `expectNoLog` /
+`logs` all call `ensureLogSession` implicitly on first use.
+
+`disposeLogSession` closes the SSE subscription **without** calling
+`/logs/stop` — the global teardown owns the server-side lifecycle.
+
+## `logBuffer` / `recentLogLines`
+
+```ts
+logBuffer(): LogBufferLike;
+recentLogLines(n?: number): Array<{ seq: number; line: LogLine }>;
+
+interface LogBufferLike {
+    currentPosition(): LogPosition;
+    linesSince(pos: LogPosition): LogLine[];
+}
+```
+
+`logBuffer()` returns the structural interface the client uses
+internally — useful for custom reporters. `recentLogLines(n = 200)`
+returns the last `n` entries with their seqs, which is what
+`installDeviceTestHooks` uses to attach recent lines to failure
+bundles.
+
+## Gap semantics
+
+`LogBuffer` tracks gaps as half-open `[start, end)` ranges. A gap is
+recorded whenever the SSE stream transitions through:
+
+- `status: reconnecting` → `markGapStart()` — the next seq becomes
+  the gap start (lines that would-have-been).
+- `status: active` **after** `reconnecting` → `markGapEnd()` — closes
+  at the current high-water. A zero-width boundary reconnect still
+  records `[start, start+1)` so assertions straddling it fail-safe.
+- `status: stopped` → closes the stream locally.
+- Server-initiated close (transport error) → closes any in-flight
+  gap at the current high-water.
+
+### Asymmetric rules: `waitForLog` vs `expectNoLog`
+
+The two assertion families have different soundness requirements, and
+the gap-overlap rule is correspondingly asymmetric:
+
+- **`waitForLog`** is a **positive** assertion: "did the marker fire
+  post-`since`?". A clean match — one whose seq is strictly outside
+  every recorded gap — is direct evidence that the marker fired,
+  regardless of whether earlier (or later) gaps exist in the wait
+  window. The implementation therefore uses the per-match
+  `LogBuffer.findGapContaining(seq)` check rather than the broader
+  `hasGapWithin(since, ...)`. Gaps still matter at the timeout
+  boundary: if the wait runs out the clock without finding a clean
+  match and any gap occurred in the window, the timeout is ambiguous
+  (the marker might have appeared in the dropped window) and surfaces
+  as `LogStreamGapError`.
+
+- **`expectNoLog`** is a **negative** assertion: "the marker did NOT
+  fire in the window". Absence is unprovable across a gap — a
+  missing line might have been the forbidden one — so any overlap of
+  the wait window with a tracked gap is fatal. `expectNoLog` keeps
+  the strict `hasGapWithin(since)` rule on initial check, on every
+  live append, and at end-of-window.
+
+In short: `waitForLog` accepts clean evidence even when prior
+reconnects existed; `expectNoLog` rejects on any overlapping
+reconnect because its truth value is sensitive to lines we did not
+see. `logs` is a bulk read with no soundness contract beyond "what
+is in the buffer right now"; it does not throw on gaps.
+
+### Silent windows
+
+Gaps only describe reconnects the stream reported. A subscription can
+also stop delivering while both ends still consider it attached — the
+server's heartbeat probes the device over ECP, which keeps answering
+— and then nothing is reported, nothing is closed, and no gap is
+recorded. From inside a wait that is indistinguishable from a device
+with nothing to say.
+
+`waitForLog` treats a window in which **no line arrived at all** as
+exactly that: no evidence either way. Before calling the marker
+absent it asks `LogSession.resync()` for a fresh subscription and
+waits `LOG_STREAM_RESYNC_GRACE_MS` longer. `/logs/tail` replays the
+whole server-side buffer on attach and `lastServerSeq` drops the
+duplicates, so a line only the subscription leg lost arrives through
+the still-live subscription and resolves the wait. Nothing is
+recorded as a gap — a replay fills the window rather than losing it,
+and an open gap would mark the replayed lines themselves suspect.
+
+If the re-attach also delivers nothing, the timeout stands. What that
+rules out is a line lost between the server and this process, which
+the replay would have carried; what it leaves is an app with nothing
+to log in those few seconds and a stream stalled at its far end,
+which are indistinguishable from here. A short window around a quiet
+moment is much the commoner of the two, so the message names both
+rather than reporting a transport fault. The re-attach is kept
+regardless, so the next assertion in the file starts on a live
+subscription instead of inheriting the silence.
+
+`expectNoLog` does not yet do this, and a silent stream therefore
+satisfies it vacuously.
+
+### Why the asymmetry is sound
+
+`since` is captured before the action, so any seq `>= since` is
+post-action by definition. For `waitForLog`, observing the marker on
+*any* clean (non-boundary) post-action seq is sufficient to prove
+the marker fired in response to the action. Whether the marker also
+appeared earlier in a now-dropped window does not change the truth
+value. The only correctness concern is **line integrity** — a line
+whose seq sits inside a gap could be a partial / concatenated
+fragment from the reconnect boundary — which is why those matches
+are still skipped. See `LogBuffer.findGapContaining` for the
+half-open inclusion rule.
+
+## Causality pattern
+
+The canonical three-line pattern for proving that an action caused a
+log line:
+
+```ts
+const pos = client.logPosition();        // 1. SYNC snapshot BEFORE the action
+await client.keypress("Select");         // 2. Cause
+await client.waitForLog(/…/, {            // 3. Observe
+    since: pos,
+    timeout: 2_000
+});
+```
+
+Why this works:
+
+- `logPosition` is synchronous — no awaitable microtask boundary
+  between it and the next statement.
+- `waitForLog` replays buffered lines ≥ `since` before subscribing,
+  so fast-emitting lines that arrived while the SDK was rescheduling
+  don't escape the window.
+
+## Errors thrown
+
+- `WaitForLogTimeoutError` — `waitForLog` timed out. Fields:
+  `pattern`, `timeout`, `since`, `currentPosition`, `recentLines`.
+- `UnexpectedLogError` — `expectNoLog` saw a match. Fields:
+  `pattern`, `line`, `seq`, `window`.
+- `LogStreamGapError` — gap detected across the query range. Fields:
+  `gap.start`, `gap.end`, `since`, `queryEnd`, `operation`.
+- `LogBufferOverflowError` — `since` below `minAvailableSeq`. Fields:
+  `requested`, `minAvailable`.
+- `LogSessionStartError` — `POST /logs/start` or SSE attach failed
+  before ready. Fields: `serverUrl`, `statusCode`, `detail`.
+- `AppCrashedError` — `assertAppAlive` tick during a `waitForLog`.
+
+Full field lists and recovery advice in
+[`errors.md`](errors.md).
+
+## Internal / deep-import only
+
+`LogBuffer` / `LogSession` / `LogStreamClient` (plus their option
+and callback types) implement the streaming pipeline described at
+the top of this page. In v1.x they were re-exported from the package
+root so library authors could build alternative session shapes
+(persistent cross-process tails, fake wires for integration tests,
+reporters driving a dedicated buffer, etc.). In v2.0.0 the barrel
+trimmed them out because real consumers overwhelmingly interact with
+the pipeline through `RkClient.waitForLog` / `expectNoLog` / `logs`
+— the classes were tracking surface area nobody imported.
+
+The classes still exist and are still exercised by the package's own
+unit tests. The one legitimate out-of-band use case is writing a
+reporter or a test of a reporter that drives a buffer without a live
+daemon. Reach them via deep import:
+
+```ts
+// DEEP IMPORTS — not covered by SemVer.
+import { LogBuffer } from "@roku-sdk/device-test-client/src/logs/log-buffer";
+import { LogSession } from "@roku-sdk/device-test-client/src/logs/log-session";
+import { LogStreamClient } from "@roku-sdk/device-test-client/src/logs/log-stream-client";
+```
+
+If your consumer needs a stable public path, open an issue so we can
+promote a dedicated export with a SemVer-covered type.