recovery-probe 0.3.0-preview.14 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +11 -0
- package/CONTRIBUTING.md +6 -0
- package/README.md +7 -7
- package/bin/observe.mjs +2 -2
- package/docs/ci.md +1 -1
- package/docs/desktop.md +4 -4
- package/docs/ipc.md +4 -4
- package/docs/observe.md +14 -3
- package/docs/repair.md +6 -6
- package/docs/start.md +4 -4
- package/package.json +2 -2
- package/src/observation-report.mjs +40 -7
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,17 @@ All notable changes to Recovery Probe are documented here. The project follows [
|
|
|
4
4
|
|
|
5
5
|
Version 0.2.0 is the first npm release. Earlier 0.1.x revisions were repository-only prototypes.
|
|
6
6
|
|
|
7
|
+
## 0.3.0 (2026-10-14)
|
|
8
|
+
|
|
9
|
+
- Promote the validated 0.3.0 preview series to the stable npm `latest` channel: guided web/Electron setup, HTTP/IPC discovery and recovery checks, refresh experiments, fault-free observation, and a runnable CI example.
|
|
10
|
+
- Preserve initial content comparisons and add bounded follow-up evidence: first later baseline match, latest sampled comparison, sample bounds and unavailable-sample counts. Terminal, JSON and HTML distinguish a temporary difference from the last sampled state without claiming stability or ownership.
|
|
11
|
+
- Add controlled temporary-marker, later-divergence, interval-boundary and unavailable-evidence tests. Keep comparison tracking within the existing report cap.
|
|
12
|
+
- Align installation guides on 0.3.0, including the older repair guide. AI-assisted repair remains experimental and opt-in; explicit account-identity/ownership expectations remain outside this release.
|
|
13
|
+
|
|
14
|
+
### Upgrading from 0.2.0
|
|
15
|
+
|
|
16
|
+
The existing `withFault`, `createFaultFetch` and JSON-configured recovery CLI remain available. Use Node 22+ for the tester and Playwright 1.62.1 within the supported 1.x range for browser commands. The development IPC hook is tested in Electron 29.0.1 and 44.5.1; update its package and restart the development app when upgrading. New discovery workflows require explicit targets and calibrated healthy controls, and observation reports are not recovery or account-isolation verdicts. See the README workflow table for the new commands and their limits.
|
|
17
|
+
|
|
7
18
|
## 0.3.0-preview.14 (2026-10-14)
|
|
8
19
|
|
|
9
20
|
- Default fault-free observation to lightweight selected-content sampling; retain `detail: "region"` for full diagnostics. Explicit marker/text limits flag partial evidence; unrelated controls do not affect marker comparisons.
|
package/CONTRIBUTING.md
CHANGED
|
@@ -51,3 +51,9 @@ A useful pull request:
|
|
|
51
51
|
- updates the README and changelog when the public interface changes.
|
|
52
52
|
|
|
53
53
|
By submitting a contribution, you agree that it is licensed under the project's MIT license.
|
|
54
|
+
|
|
55
|
+
## Publishing a release
|
|
56
|
+
|
|
57
|
+
Run the package, browser and supported Electron CI jobs against the exact proposed source, inspect the tarball, update the installation guides and changelog, and merge only after those checks pass. Publish from the verified merged commit so npm `gitHead` and the GitHub tag agree.
|
|
58
|
+
|
|
59
|
+
Stable versions publish to `latest`; prereleases must explicitly use `--tag next` and the GitHub prerelease label. Run `npm publish --dry-run` before publishing. After publication, verify registry version, integrity and tags, install into a clean consumer, and check the CLI and exports before publishing the corresponding GitHub release. Never replace an existing npm version or move a released tag.
|
package/README.md
CHANGED
|
@@ -19,14 +19,14 @@ Recovery Probe injects bounded faults, compares healthy and faulted screens, and
|
|
|
19
19
|
|
|
20
20
|
Desktop support currently means Electron, not arbitrary native applications. IPC faults do not exercise native/Rust networking, HTTP status handling or token refresh. An unsupported data path is inconclusive, never a successful recovery check.
|
|
21
21
|
|
|
22
|
-
## Install
|
|
22
|
+
## Install
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
**0.3.0** is the stable release target on npm's `latest` channel. The commands below pin the version for reproducible reports. Prereleases use `next` and are opt-in.
|
|
25
25
|
|
|
26
26
|
```bash
|
|
27
27
|
mkdir recovery-probe-tools && cd recovery-probe-tools
|
|
28
|
-
npm view recovery-probe@0.3.0
|
|
29
|
-
npm install --save-dev --save-exact recovery-probe@0.3.0
|
|
28
|
+
npm view recovery-probe@0.3.0 version
|
|
29
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0 playwright@1.62.1
|
|
30
30
|
npx recovery-probe --version
|
|
31
31
|
```
|
|
32
32
|
|
|
@@ -34,9 +34,9 @@ If the version check reports that the version is unavailable, npm publication is
|
|
|
34
34
|
|
|
35
35
|
## Choose a workflow
|
|
36
36
|
|
|
37
|
-
**New in
|
|
37
|
+
**New in 0.3.0:** guided setup, HTTP/IPC discovery, refresh experiments and [fault-free observation](docs/observe.md) extend the original recovery helpers. Observation records selected reads and content while you navigate without reloading or clearing caches. Lightweight sampling, phase timings and separate cleanup evidence make capture cost and scope explicit. Use `"detail": "region"` for full DOM diagnostics.
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
Content comparisons preserve the first observed result and summarize later samples: a temporary difference can subsequently match the baseline, or diverge again. These are observations, not ownership, freshness or stability verdicts. See the guide for updating the development IPC hook before capturing cached state; see the changelog for upgrading from 0.2.0.
|
|
40
40
|
|
|
41
41
|
| Goal | Entry point | Guide |
|
|
42
42
|
| --- | --- | --- |
|
|
@@ -59,7 +59,7 @@ HTTP and IPC structural discovery calibrate three healthy reloads for the full `
|
|
|
59
59
|
|
|
60
60
|
## Refresh experiments
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
Refresh mode tests an **already populated screen** using an explicitly configured synthetic window event, such as `online`. It first checks the event without a fault, then injects the next selected read failure and observes the screen without reloading. An optional second event tests whether another refresh repairs the screen.
|
|
63
63
|
|
|
64
64
|
```bash
|
|
65
65
|
npx recovery-probe refresh --config ./refresh.json --out ./refresh-run1 --json
|
package/bin/observe.mjs
CHANGED
|
@@ -5,7 +5,7 @@ import { createInterface } from 'node:readline';
|
|
|
5
5
|
import { connectDesktop, selectDesktopPage, desktopPages } from '../src/desktop.mjs';
|
|
6
6
|
import { connectIpcInspector } from '../src/ipc-inspector.mjs';
|
|
7
7
|
import { observationConfig, runObservation, httpObservationAdapter, ipcObservationAdapter } from '../src/observe.mjs';
|
|
8
|
-
import { observationMetadata, samplingMetrics, observationSummary, renderObservationReport } from '../src/observation-report.mjs';
|
|
8
|
+
import { observationMetadata, samplingMetrics, observationSummary, renderObservationReport, comparisonFollowUpSummary } from '../src/observation-report.mjs';
|
|
9
9
|
|
|
10
10
|
export async function observeMain(args) {
|
|
11
11
|
if (!args.length || args.includes('--help')) {
|
|
@@ -94,7 +94,7 @@ IPC requires the observation-capable development hook. See docs/observe.md.`);
|
|
|
94
94
|
else {
|
|
95
95
|
for (const i of report.intervals) console.log(`Interval ${i.index}: ${i.reads?.calls ?? '?'} reads, ${i.reads?.successes ?? '?'} successes, ${i.reads?.errors ?? '?'} errors${i.findings.length ? '; ' + i.findings.join(', ') : ''}`);
|
|
96
96
|
for (const finding of report.findings) console.log(`Interval ${finding.interval}: ${observationSummary(finding)}`);
|
|
97
|
-
for (const comparison of report.comparisons ?? []) console.log(`Interval ${comparison.interval}: ${comparison.summary}`);
|
|
97
|
+
for (const comparison of report.comparisons ?? []) console.log(`Interval ${comparison.interval}: ${comparison.summary} ${comparisonFollowUpSummary(comparison)}`);
|
|
98
98
|
console.log(`Sampling: ${config.detail}; requested delay ${config.sampleMs} ms; measured mean cadence ${report.sampling.startToStart.meanMs ?? 'unavailable'} ms.`);
|
|
99
99
|
if (report.error) console.error(report.error);
|
|
100
100
|
console.log(`Capture: ${report.status} (not a health verdict)\nReport: ${join(directory, 'report.html')}`);
|
package/docs/ci.md
CHANGED
|
@@ -60,6 +60,6 @@ jobs:
|
|
|
60
60
|
|
|
61
61
|
## Adapt it to an application
|
|
62
62
|
|
|
63
|
-
Install `recovery-probe@0.3.0
|
|
63
|
+
Install `recovery-probe@0.3.0` and your compatible Playwright runtime. Copy the example's orchestration pattern into your test suite, replace the synthetic server startup with your authorized test application, choose one read-only request and specify the expected recovery action and result. Keep the healthy control, bounded fault count, cleanup, inconclusive outcomes and process exit checks. Run the normal gate against the current app; the deliberately broken variant belongs only in a synthetic verification fixture.
|
|
64
64
|
|
|
65
65
|
This example provides local/CI execution and artifacts. It does not post PR comments, upload to a hosted Recovery Probe service or infer what your product ought to display.
|
package/docs/desktop.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
For the guided workflow without window-index lookup or JSON editing, see [guided start](start.md). The explicit configuration workflow below remains supported.
|
|
4
4
|
|
|
5
|
-
This
|
|
5
|
+
This workflow attaches to a running **Electron development app or authorized Chromium-based test browser**. It discovers renderer GET JSON requests, then tests one selected endpoint against a UI assertion you configure once. It does not scan source code, patch files, or add runtime recovery to the application.
|
|
6
6
|
|
|
7
7
|
You can run the tester in a separate folder; your desktop application's production dependencies do not change. Use Node.js 22 or newer for the tester. Electron itself may use a different bundled Node version.
|
|
8
8
|
|
|
@@ -32,14 +32,14 @@ Set `RECOVERY_PROBE=1` using your existing cross-platform development tooling, t
|
|
|
32
32
|
|
|
33
33
|
## 2. Install and identify the window
|
|
34
34
|
|
|
35
|
-
Install the exact
|
|
35
|
+
Install the exact version in a separate tester folder:
|
|
36
36
|
|
|
37
37
|
```bash
|
|
38
38
|
mkdir recovery-probe-desktop-test
|
|
39
39
|
cd recovery-probe-desktop-test
|
|
40
40
|
npm init -y
|
|
41
|
-
npm view recovery-probe@0.3.0
|
|
42
|
-
npm install --save-dev --save-exact recovery-probe@0.3.0
|
|
41
|
+
npm view recovery-probe@0.3.0 version
|
|
42
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0 playwright@1.62.1
|
|
43
43
|
npx recovery-probe desktop --list
|
|
44
44
|
```
|
|
45
45
|
|
package/docs/ipc.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# IPC renderer recovery
|
|
1
|
+
# IPC renderer recovery
|
|
2
2
|
|
|
3
3
|
For cache/navigation evidence that must survive without a reload, see the [fault-free observation workflow](observe.md). The recovery checks below reload the renderer and cannot establish session or account isolation.
|
|
4
4
|
|
|
@@ -12,8 +12,8 @@ Node 22+ is required for the CLI. Electron 29's bundled Node can load the small
|
|
|
12
12
|
|
|
13
13
|
```bash
|
|
14
14
|
mkdir -p recovery-probe-tools && cd recovery-probe-tools
|
|
15
|
-
npm view recovery-probe@0.3.0
|
|
16
|
-
npm install --save-dev --save-exact recovery-probe@0.3.0
|
|
15
|
+
npm view recovery-probe@0.3.0 version
|
|
16
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0 playwright@1.62.1
|
|
17
17
|
node -p "require.resolve('recovery-probe/ipc')"
|
|
18
18
|
```
|
|
19
19
|
|
|
@@ -153,7 +153,7 @@ Reports contain UI counts, English loading/empty/error/retry indicators, text ha
|
|
|
153
153
|
|
|
154
154
|
English heuristics can misinterpret unrelated text and miss translated or icon-only states. Discovery uses the first main landmark, or the body if absent, and stops if healthy text varies. Virtualization, clocks and live content may make this unsuitable; use the existing explicit `ipc` verifier then. No DOM snapshots or region-specific source semantics are inferred. Visibility changes remain blockers, not deliberate experiments.
|
|
155
155
|
|
|
156
|
-
Each finding includes counts of repeated outcomes, a suggested investigation and a replay instruction. Re-run the saved scenario with `ipc --discover --config PATH` after a local fix. Compare the same experiment and its healthy controls; disappearance of a heuristic alone does not prove a fix. There is no automatic patch application or `verify <id>` command in this
|
|
156
|
+
Each finding includes counts of repeated outcomes, a suggested investigation and a replay instruction. Re-run the saved scenario with `ipc --discover --config PATH` after a local fix. Compare the same experiment and its healthy controls; disappearance of a heuristic alone does not prove a fix. There is no automatic patch application or `verify <id>` command in this workflow.
|
|
157
157
|
|
|
158
158
|
Exit 0 means completed with only informational observations; exit 2 means findings need review or the experiment was inconclusive. Discovery never returns exit 1 for an unverified heuristic defect. The existing explicit checker retains its exit codes. `recoveryMs` measures injection-to-detection, including sampling and a 300ms UI stability requirement; it is not just the handler duration.
|
|
159
159
|
|
package/docs/observe.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# Observe reads without resetting the app
|
|
2
2
|
|
|
3
|
-
Available in **0.3.0
|
|
3
|
+
Available in **0.3.0**. Install the exact version and verify the CLI:
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
|
-
npm install --save-dev --save-exact recovery-probe@0.3.0
|
|
6
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0 playwright@1.62.1
|
|
7
7
|
npx recovery-probe --version
|
|
8
8
|
```
|
|
9
9
|
|
|
@@ -95,6 +95,17 @@ Results are `unchanged`, `changed`, or `unavailable`. Unavailable means the requ
|
|
|
95
95
|
|
|
96
96
|
The browser tests include unchanged content after a failed refresh, changed content after a successful refresh, cached interval return, a sampled 250 ms pulse, and a pulse entirely between samples that remains undetected. These controls deliberately distinguish captured evidence from missed transitions.
|
|
97
97
|
|
|
98
|
+
### Later samples after a comparison
|
|
99
|
+
|
|
100
|
+
In 0.3.0, each retained comparison also has `followUp` evidence from later completed samples in the **same operator interval**. The original `result`, `before` and `after` remain unchanged. Follow-up compares with the original `before` baseline, not the first return sample:
|
|
101
|
+
|
|
102
|
+
- `samples`, `comparableSamples` and `unavailableSamples` count later samples, including unchanged samples omitted from the timeline.
|
|
103
|
+
- `firstBaselineMatch` records the first later sample matching the baseline, or null. It records an observation, not an exact transition time.
|
|
104
|
+
- `latest` records the last follow-up sample, its bounds and its comparison result. Absent/hidden or truncated evidence is unavailable; it cannot establish a match.
|
|
105
|
+
- `summary` appears in JSON, terminal and HTML output. For a 19 → 17 → 19 marker sequence it says that content initially differed and a later sample matched. If content diverges again, the latest comparison says changed. With no later sample, that absence is explicit.
|
|
106
|
+
|
|
107
|
+
Tracking ends at the next operator interval or capture termination, including interruption. These are sampled comparisons, not a settling rule, continuous-visibility claim, identity assertion or recovery verdict. Read completions and later UI changes are not proof of causality. The existing 1000-comparison cap also bounds follow-up tracking.
|
|
108
|
+
|
|
98
109
|
## Interpretation
|
|
99
110
|
|
|
100
111
|
Local `report.json` and `report.html` contain interval read counts, starts/completions, first-content sample bounds, and a change-only sampled timeline. `scenario.json` records the selected scope. No screenshots, response bodies or raw UI values are saved. Region text and repeated values are hashed; hashes are **not anonymization**, particularly for predictable text. Treat reports and selectors as private evidence.
|
|
@@ -113,7 +124,7 @@ A document reload/navigation ends capture as incomplete because the renderer sta
|
|
|
113
124
|
|
|
114
125
|
## Supported inspector API
|
|
115
126
|
|
|
116
|
-
Advanced scripts can use `recovery-probe/ipc-inspector` after installing
|
|
127
|
+
Advanced scripts can use `recovery-probe/ipc-inspector` after installing 0.3.0, without importing private `src/` paths:
|
|
117
128
|
|
|
118
129
|
```js
|
|
119
130
|
import { randomUUID } from 'node:crypto';
|
package/docs/repair.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# Web and Electron repair
|
|
1
|
+
# Web and Electron repair (experimental)
|
|
2
2
|
|
|
3
|
-
The repair workflow is
|
|
3
|
+
The opt-in repair workflow is included in 0.3.0 and remains experimental. For recovery testing without source upload or model credentials, use [guided start](start.md).
|
|
4
4
|
|
|
5
5
|
## What it actually does
|
|
6
6
|
|
|
@@ -22,12 +22,12 @@ Node 22+, Git and Playwright Chromium are required. You do not have to modify yo
|
|
|
22
22
|
mkdir recovery-probe-tools
|
|
23
23
|
cd recovery-probe-tools
|
|
24
24
|
npm init -y
|
|
25
|
-
npm install --save-dev recovery-probe@0.3.0
|
|
25
|
+
npm install --save-dev recovery-probe@0.3.0 playwright@1.62.1
|
|
26
26
|
npx playwright install chromium
|
|
27
27
|
npx recovery-probe --version
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
The exact version keeps saved experiments reproducible. Review generated changes before applying them.
|
|
31
31
|
|
|
32
32
|
## First test: user portal, without AI or source upload
|
|
33
33
|
|
|
@@ -37,7 +37,7 @@ Start your portal locally using its existing development command and a test acco
|
|
|
37
37
|
npx recovery-probe web --login --url http://127.0.0.1:3100 --state ./private-portal-state.json
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
Sign in yourself in the Chromium window, return to the app, then press Enter in the terminal. The command refuses to overwrite an existing state file. State includes cookies/local storage/IndexedDB, not session storage. Keep it private. Session-storage-only auth needs your existing Playwright login fixture with the `withFault` helper; this
|
|
40
|
+
Sign in yourself in the Chromium window, return to the app, then press Enter in the terminal. The command refuses to overwrite an existing state file. State includes cookies/local storage/IndexedDB, not session storage. Keep it private. Session-storage-only auth needs your existing Playwright login fixture with the `withFault` helper; this workflow does not export that state. Use the same origin/port for subsequent checks.
|
|
41
41
|
|
|
42
42
|
```bash
|
|
43
43
|
npx recovery-probe web --discover --url http://127.0.0.1:3100/users --state ./private-portal-state.json --out ./portal-discovery
|
|
@@ -102,7 +102,7 @@ Create `portal-repair.json` in the tools folder, outside the app repository:
|
|
|
102
102
|
}
|
|
103
103
|
```
|
|
104
104
|
|
|
105
|
-
Replace source paths, commands, endpoint and selectors with your app's actual ones. The launch example assumes Vite; other frameworks need their own command. Commands are executable/argument arrays, not shell strings. Do not include shell metacharacters. `repo` and `storageState` resolve relative to this config file. Commands execute in the isolated checkout root. An app requiring environment variables can use a reviewed development launch script; the
|
|
105
|
+
Replace source paths, commands, endpoint and selectors with your app's actual ones. The launch example assumes Vite; other frameworks need their own command. Commands are executable/argument arrays, not shell strings. Do not include shell metacharacters. `repo` and `storageState` resolve relative to this config file. Commands execute in the isolated checkout root. An app requiring environment variables can use a reviewed development launch script; the workflow does not inherit arbitrary service secrets.
|
|
106
106
|
|
|
107
107
|
`sourceFiles` is an explicit allowlist of 1–12 small text source files, at most 100 KB each/300 KB total. It is not a whole-repository scanner. Tests/configs, hidden files, traversal and symlink sources are rejected. Include enough of the request/controller/component logic for the model to investigate. Do not include credentials. The model can return exact replacements in those files, not commands, configuration changes or test rewrites.
|
|
108
108
|
|
package/docs/start.md
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
# Guided start
|
|
2
2
|
|
|
3
|
-
This workflow is included in
|
|
3
|
+
This workflow is included in 0.3.0. See the [README](../README.md) for installation and supported application paths.
|
|
4
4
|
|
|
5
5
|
Start your app using its normal development command. Recovery Probe does not need its repository or production dependencies. Node 22+ is required. Use a development/test account and backend: a locally running app can still call remote services.
|
|
6
6
|
|
|
7
7
|
## Three commands for a web app
|
|
8
8
|
|
|
9
|
-
Install the exact npm
|
|
9
|
+
Install the exact npm version after confirming availability:
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
12
|
mkdir recovery-probe-tools && cd recovery-probe-tools
|
|
13
|
-
npm view recovery-probe@0.3.0
|
|
14
|
-
npm install --save-dev --save-exact recovery-probe@0.3.0
|
|
13
|
+
npm view recovery-probe@0.3.0 version
|
|
14
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0 playwright@1.62.1
|
|
15
15
|
npx recovery-probe start web http://localhost:3000
|
|
16
16
|
```
|
|
17
17
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "recovery-probe",
|
|
3
|
-
"version": "0.3.0
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Test recovery from failed reads in web and Electron desktop apps, during loading and refresh.",
|
|
6
6
|
"license": "MIT",
|
|
@@ -86,7 +86,7 @@
|
|
|
86
86
|
},
|
|
87
87
|
"publishConfig": {
|
|
88
88
|
"access": "public",
|
|
89
|
-
"tag": "
|
|
89
|
+
"tag": "latest"
|
|
90
90
|
},
|
|
91
91
|
"keywords": [
|
|
92
92
|
"playwright",
|
|
@@ -38,27 +38,53 @@ export function samplingMetrics(requestedDelayMs) {
|
|
|
38
38
|
}
|
|
39
39
|
|
|
40
40
|
// Compare samples only; these summaries cannot establish ownership or freshness.
|
|
41
|
+
const contentEvidence = e => ({ interval: e.interval, fromMs: e.fromMs, toMs: e.toMs,
|
|
42
|
+
presence: e.ui.presence, visible: e.ui.visible, content: e.ui.content ?? null });
|
|
43
|
+
function compareContent(before, after) {
|
|
44
|
+
const a = before.content, b = after.content;
|
|
45
|
+
const comparable = before.visible && after.visible && a && b && !a.truncated && !b.truncated;
|
|
46
|
+
return !comparable ? 'unavailable' : a.count === b.count && a.textFingerprint === b.textFingerprint ? 'unchanged' : 'changed';
|
|
47
|
+
}
|
|
48
|
+
|
|
41
49
|
export function contentComparison(basis, before, after) {
|
|
42
|
-
const
|
|
43
|
-
|
|
44
|
-
const a = before.ui.content, b = after.ui.content;
|
|
45
|
-
const comparable = before.ui.visible && after.ui.visible && a && b && !a.truncated && !b.truncated;
|
|
46
|
-
const result = !comparable ? 'unavailable' : a.count === b.count && a.textFingerprint === b.textFingerprint ? 'unchanged' : 'changed';
|
|
47
|
-
return { kind: 'observation', basis, interval: after.interval, result, before: evidence(before), after: evidence(after),
|
|
50
|
+
const result = compareContent(contentEvidence(before), contentEvidence(after));
|
|
51
|
+
return { kind: 'observation', basis, interval: after.interval, result, before: contentEvidence(before), after: contentEvidence(after),
|
|
48
52
|
...(basis === 'READ_COMPLETION' ? { completions: { successes: after.before.successes - before.after.successes,
|
|
49
53
|
errors: after.before.errors - before.after.errors } } : { reads: after.reads }),
|
|
50
54
|
summary: `${basis === 'READ_COMPLETION' ? 'Across observed read completion(s)' : 'On the first sampled content in this interval'}, selected marker text/count comparison: ${result}.`,
|
|
51
55
|
note: 'Ordered normalized visible marker text/count only. Other values, ownership, freshness and changes between samples are unknown. Completion does not imply renderer consumption.' };
|
|
52
56
|
}
|
|
53
57
|
|
|
58
|
+
export function comparisonFollowUpSummary(comparison) {
|
|
59
|
+
const f = comparison.followUp;
|
|
60
|
+
if (!f) return ''; // Reports from older versions have no follow-up evidence.
|
|
61
|
+
if (!f.samples) return 'No later sample in this interval.';
|
|
62
|
+
const matched = f.firstBaselineMatch;
|
|
63
|
+
const prefix = comparison.result === 'changed' && matched
|
|
64
|
+
? `Initially different; a later sample matched the baseline (${matched.fromMs}–${matched.toMs} ms from capture start). ` : '';
|
|
65
|
+
return `${prefix}Latest follow-up sample (${f.latest.fromMs}–${f.latest.toMs} ms from capture start): ${f.latest.result} against the baseline. ${f.comparableSamples} comparable, ${f.unavailableSamples} unavailable later samples. These samples do not establish continuous visibility or stability.`;
|
|
66
|
+
}
|
|
67
|
+
|
|
54
68
|
export function contentComparisons() {
|
|
55
69
|
let interval, anchor, lastContent, returnBaseline, comparedReturn = false;
|
|
70
|
+
let active = [], retained = 0;
|
|
56
71
|
const completed = counts => counts.successes + counts.errors;
|
|
57
72
|
return {
|
|
58
73
|
add(event) {
|
|
59
74
|
const results = [];
|
|
60
75
|
if (interval !== event.interval) {
|
|
61
76
|
interval = event.interval; anchor = undefined; returnBaseline = lastContent; comparedReturn = false;
|
|
77
|
+
active = []; // Later intervals cannot resolve an earlier comparison.
|
|
78
|
+
}
|
|
79
|
+
for (const comparison of active) {
|
|
80
|
+
const f = comparison.followUp;
|
|
81
|
+
const evidence = contentEvidence(event);
|
|
82
|
+
const result = compareContent(comparison.before, evidence);
|
|
83
|
+
f.samples++;
|
|
84
|
+
if (result === 'unavailable') f.unavailableSamples++; else f.comparableSamples++;
|
|
85
|
+
f.latest = { ...evidence, result };
|
|
86
|
+
if (result === 'unchanged' && !f.firstBaselineMatch) f.firstBaselineMatch = evidence;
|
|
87
|
+
f.summary = comparisonFollowUpSummary(comparison);
|
|
62
88
|
}
|
|
63
89
|
if (event.ui.visible && event.ui.contentCount > 0) {
|
|
64
90
|
if (returnBaseline && !comparedReturn) results.push(contentComparison('INTERVAL_RETURN', returnBaseline, event));
|
|
@@ -72,6 +98,13 @@ export function contentComparisons() {
|
|
|
72
98
|
anchor = event;
|
|
73
99
|
}
|
|
74
100
|
} else anchor = event;
|
|
101
|
+
for (const comparison of results) {
|
|
102
|
+
// Match the report's global comparison cap; do not retain discarded evidence.
|
|
103
|
+
if (retained >= 1000) break;
|
|
104
|
+
comparison.followUp = { samples: 0, comparableSamples: 0, unavailableSamples: 0,
|
|
105
|
+
firstBaselineMatch: null, latest: null, summary: 'No later sample in this interval.' };
|
|
106
|
+
retained++; active.push(comparison);
|
|
107
|
+
}
|
|
75
108
|
return results;
|
|
76
109
|
},
|
|
77
110
|
};
|
|
@@ -87,7 +120,7 @@ const escape = value => String(value).replace(/[&<>"']/g, c => ({ '&': '&',
|
|
|
87
120
|
export function renderObservationReport(report) {
|
|
88
121
|
const rows = report.intervals.map(i => `<tr><td>${i.index}</td><td>${i.reads?.calls ?? 'unknown'}</td><td>${i.reads?.successes ?? 'unknown'}</td><td>${i.reads?.errors ?? 'unknown'}</td><td>${i.firstContent ? `${i.firstContent.fromMs - i.startMs}–${i.firstContent.toMs - i.startMs} ms` : 'not sampled'}</td></tr>`).join('');
|
|
89
122
|
const sampling = report.sampling;
|
|
90
|
-
const comparisons = (report.comparisons ?? []).map(c => `<p>Interval ${escape(c.interval)}: ${escape(c.summary)} ${c.completions ? `(${c.completions.successes} successful, ${c.completions.errors} failed read completions)` : `(${c.reads.calls} selected reads started in this interval)`}</p>`).join('');
|
|
123
|
+
const comparisons = (report.comparisons ?? []).map(c => `<p>Interval ${escape(c.interval)}: ${escape(c.summary)} ${c.completions ? `(${c.completions.successes} successful, ${c.completions.errors} failed read completions)` : `(${c.reads.calls} selected reads started in this interval)`} ${escape(comparisonFollowUpSummary(c))}</p>`).join('');
|
|
91
124
|
const phases = Object.entries(sampling?.phases ?? {}).map(([name, s]) => `<tr><td>${escape(name)}</td><td>${s.meanMs}</td><td>${s.maxMs}</td></tr>`).join('');
|
|
92
125
|
return `<!doctype html><meta charset="utf-8"><title>Recovery Probe observation</title><style>body{font:16px system-ui;max-width:1000px;margin:40px auto;padding:20px}td,th{text-align:left;padding:8px}pre{white-space:pre-wrap;overflow-wrap:anywhere}</style><h1>Fault-free observation</h1><p>Capture: ${escape(report.status)}. This is not a recovery or account-isolation verdict.</p><p>Recovery Probe ${escape(report.metadata?.recoveryProbeVersion ?? 'unknown')} · Node ${escape(report.metadata?.runtime?.node ?? 'unknown')} · Browser ${escape(report.metadata?.browserVersion ?? 'unknown')} · IPC hook ${escape(report.metadata?.ipcHook?.version ?? 'unknown / not applicable')}</p>${sampling ? `<p>Configured delay: ${sampling.requestedDelayMs} ms. Completed samples: ${sampling.completedSamples}. Mean sample duration: ${sampling.sampleDuration.meanMs ?? 'unavailable'} ms. Mean start-to-start cadence: ${sampling.startToStart.meanMs ?? 'unavailable'} ms (maximum ${sampling.startToStart.maxMs ?? 'unavailable'} ms).</p><p>${escape(sampling.note)}</p>` : ''}<p>Sampling detail: ${escape(report.detail ?? 'region (legacy)')}. Marker counts describe the configured content selector; generic region item counts are heuristics.</p>${phases ? `<table><thead><tr><th>Measured phase</th><th>Mean ms</th><th>Maximum ms</th></tr></thead><tbody>${phases}</tbody></table><p>Renderer read time is included in the UI round trip, not additional to it.</p>` : ''}<p>${escape(report.limitation ?? report.error)}</p><table><thead><tr><th>Interval</th><th>Reads started</th><th>Successes</th><th>Errors</th><th>First content sample bounds</th></tr></thead><tbody>${rows}</tbody></table>${report.findings.map(f => `<p>Interval ${f.interval}: ${escape(observationSummary(f))} <strong>${escape(f.code)}</strong> — ${escape(f.basis)}</p>`).join('')}${comparisons}<p>Comparisons concern sampled marker text and count, not ownership or freshness. A completion does not guarantee the UI has consumed its result.</p><p>Cleanup: ${escape(report.cleanup ?? 'unknown')}. The observation snapshot is from before cleanup; cleanupEvidence records the separate cleanup check when available.</p><details><summary>Evidence and coverage</summary><pre>${escape(JSON.stringify(report, null, 2))}</pre></details>`;
|
|
93
126
|
}
|