@stacknext/regression 0.9.0 → 0.10.0

package/dist/constants.d.ts

@@ -2,7 +2,7 @@ export declare const STACKNEXT_RUN_FORMAT = "stacknext-test-run";
 export declare const STACKNEXT_BASELINE_FORMAT = "stacknext-baseline";
 export declare const STACKNEXT_COMPARISON_FORMAT = "stacknext-comparison";
 export declare const STACKNEXT_REGRESSION_FORMAT_VERSION = 1;
-export declare const STACKNEXT_REGRESSION_ENGINE_VERSION = "0.9.0";
+export declare const STACKNEXT_REGRESSION_ENGINE_VERSION = "0.10.0";
 export declare const RUN_STATUSES: readonly ["running", "completed", "failed", "interrupted", "incomplete"];
 export type RunStatus = (typeof RUN_STATUSES)[number];
 export declare const SAMPLE_STATUSES: readonly ["passed", "failed", "timedOut", "skipped", "interrupted"];

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,uBAAuB,CAAA;AACxD,eAAO,MAAM,yBAAyB,uBAAuB,CAAA;AAC7D,eAAO,MAAM,2BAA2B,yBAAyB,CAAA;AACjE,eAAO,MAAM,mCAAmC,IAAI,CAAA;AACpD,eAAO,MAAM,mCAAmC,UAAU,CAAA;AAE1D,eAAO,MAAM,YAAY,0EAMf,CAAA;AACV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAA;AAErD,eAAO,MAAM,eAAe,qEAMlB,CAAA;AACV,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3D,eAAO,MAAM,wBAAwB,0CAA2C,CAAA;AAChF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE5E,eAAO,MAAM,oBAAoB,qCAAsC,CAAA;AACvE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAA;AAErE,eAAO,MAAM,mBAAmB,iEAKtB,CAAA;AACV,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEnE,eAAO,MAAM,qBAAqB,4CAA6C,CAAA;AAC/E,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEvE,eAAO,MAAM,uBAAuB,mEAM1B,CAAA;AACV,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3E,eAAO,MAAM,qBAAqB,QAAkC,CAAA;AACpE,eAAO,MAAM,mBAAmB,QAAuB,CAAA;AACvD,eAAO,MAAM,iBAAiB,QAAuB,CAAA;AAErD,eAAO,MAAM,0BAA0B;;;;;;;;CAQ7B,CAAA;AAEV,eAAO,MAAM,sBAAsB,krBAOzB,CAAA"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,uBAAuB,CAAA;AACxD,eAAO,MAAM,yBAAyB,uBAAuB,CAAA;AAC7D,eAAO,MAAM,2BAA2B,yBAAyB,CAAA;AACjE,eAAO,MAAM,mCAAmC,IAAI,CAAA;AACpD,eAAO,MAAM,mCAAmC,WAAW,CAAA;AAE3D,eAAO,MAAM,YAAY,0EAMf,CAAA;AACV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAA;AAErD,eAAO,MAAM,eAAe,qEAMlB,CAAA;AACV,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3D,eAAO,MAAM,wBAAwB,0CAA2C,CAAA;AAChF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE5E,eAAO,MAAM,oBAAoB,qCAAsC,CAAA;AACvE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAA;AAErE,eAAO,MAAM,mBAAmB,iEAKtB,CAAA;AACV,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEnE,eAAO,MAAM,qBAAqB,4CAA6C,CAAA;AAC/E,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEvE,eAAO,MAAM,uBAAuB,mEAM1B,CAAA;AACV,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3E,eAAO,MAAM,qBAAqB,QAAkC,CAAA;AACpE,eAAO,MAAM,mBAAmB,QAAuB,CAAA;AACvD,eAAO,MAAM,iBAAiB,QAAuB,CAAA;AAErD,eAAO,MAAM,0BAA0B;;;;;;;;CAQ7B,CAAA;AAEV,eAAO,MAAM,sBAAsB,krBAOzB,CAAA"}

package/dist/constants.js

@@ -2,7 +2,7 @@ export const STACKNEXT_RUN_FORMAT = 'stacknext-test-run';
 export const STACKNEXT_BASELINE_FORMAT = 'stacknext-baseline';
 export const STACKNEXT_COMPARISON_FORMAT = 'stacknext-comparison';
 export const STACKNEXT_REGRESSION_FORMAT_VERSION = 1;
-export const STACKNEXT_REGRESSION_ENGINE_VERSION = '0.9.0';
+export const STACKNEXT_REGRESSION_ENGINE_VERSION = '0.10.0';
 export const RUN_STATUSES = [
     'running',
     'completed',

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,oBAAoB,CAAA;AACxD,MAAM,CAAC,MAAM,yBAAyB,GAAG,oBAAoB,CAAA;AAC7D,MAAM,CAAC,MAAM,2BAA2B,GAAG,sBAAsB,CAAA;AACjE,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,CAAA;AACpD,MAAM,CAAC,MAAM,mCAAmC,GAAG,OAAO,CAAA;AAE1D,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,SAAS;IACT,WAAW;IACX,QAAQ;IACR,aAAa;IACb,YAAY;CACJ,CAAA;AAGV,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,SAAS;IACT,aAAa;CACL,CAAA;AAGV,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAA;AAGhF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,UAAU,EAAE,YAAY,CAAU,CAAA;AAGvE,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,UAAU;IACV,WAAW;IACX,WAAW;IACX,cAAc;CACN,CAAA;AAGV,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAU,CAAA;AAG/E,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU;IACV,OAAO;IACP,aAAa;IACb,OAAO;IACP,SAAS;CACD,CAAA;AAGV,MAAM,CAAC,MAAM,qBAAqB,GAAG,+BAA+B,CAAA;AACpE,MAAM,CAAC,MAAM,mBAAmB,GAAG,oBAAoB,CAAA;AACvD,MAAM,CAAC,MAAM,iBAAiB,GAAG,oBAAoB,CAAA;AAErD,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,UAAU,EAAE,CAAC;IACb,qBAAqB,EAAE,EAAE;IACzB,oBAAoB,EAAE,EAAE;IACxB,sBAAsB,EAAE,EAAE;IAC1B,qBAAqB,EAAE,EAAE;IACzB,kBAAkB,EAAE,CAAC;IACrB,iBAAiB,EAAE,KAAK;CAChB,CAAA;AAEV,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,+FAA+F;IAC/F,oGAAoG;IACpG,0GAA0G;IAC1G,yEAAyE;IACzE,2HAA2H;IAC3H,0KAA0K;CAClK,CAAA"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,oBAAoB,CAAA;AACxD,MAAM,CAAC,MAAM,yBAAyB,GAAG,oBAAoB,CAAA;AAC7D,MAAM,CAAC,MAAM,2BAA2B,GAAG,sBAAsB,CAAA;AACjE,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,CAAA;AACpD,MAAM,CAAC,MAAM,mCAAmC,GAAG,QAAQ,CAAA;AAE3D,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,SAAS;IACT,WAAW;IACX,QAAQ;IACR,aAAa;IACb,YAAY;CACJ,CAAA;AAGV,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,SAAS;IACT,aAAa;CACL,CAAA;AAGV,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAA;AAGhF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,UAAU,EAAE,YAAY,CAAU,CAAA;AAGvE,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,UAAU;IACV,WAAW;IACX,WAAW;IACX,cAAc;CACN,CAAA;AAGV,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAU,CAAA;AAG/E,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU;IACV,OAAO;IACP,aAAa;IACb,OAAO;IACP,SAAS;CACD,CAAA;AAGV,MAAM,CAAC,MAAM,qBAAqB,GAAG,+BAA+B,CAAA;AACpE,MAAM,CAAC,MAAM,mBAAmB,GAAG,oBAAoB,CAAA;AACvD,MAAM,CAAC,MAAM,iBAAiB,GAAG,oBAAoB,CAAA;AAErD,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,UAAU,EAAE,CAAC;IACb,qBAAqB,EAAE,EAAE;IACzB,oBAAoB,EAAE,EAAE;IACxB,sBAAsB,EAAE,EAAE;IAC1B,qBAAqB,EAAE,EAAE;IACzB,kBAAkB,EAAE,CAAC;IACrB,iBAAiB,EAAE,KAAK;CAChB,CAAA;AAEV,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,+FAA+F;IAC/F,oGAAoG;IACpG,0GAA0G;IAC1G,yEAAyE;IACzE,2HAA2H;IAC3H,0KAA0K;CAClK,CAAA"}

package/docs/captures.md

@@ -0,0 +1,92 @@
+---
+title: Captures and baselines
+description: Test run, scenario and sample correlation model, statuses and baseline rules.
+---
+
+# Captures and baselines
+
+## Test run lifecycle
+
+A run is created by the collector when `stacknext capture` starts a child test
+command. The CLI passes the collector URL, token, run id and capture flag to the
+child environment. The Playwright fixture submits each scenario sample. On exit,
+the CLI completes the run and saves it under `.stacknext/runs`.
+
+`TestRun` statuses:
+
+| Status | Meaning |
+| --- | --- |
+| `running` | Registry record is still live. |
+| `completed` | The child exited successfully and telemetry is complete. |
+| `failed` | The child command failed. |
+| `interrupted` | The child received a signal. |
+| `incomplete` | Finalization failed or required telemetry is missing. |
+
+Only a `completed` run with verified samples can become a baseline. A failed or
+incomplete run remains readable but supports no regression verdict.
+
+## Scenario identity
+
+`scenarioIdentity()` prefers, in order:
+
+1. an explicit `stacknext.scenario` annotation;
+2. the Playwright `testId`;
+3. file + title + project.
+
+Changing the annotation creates a new scenario with no matching baseline.
+
+Captured runs use one Playwright worker. Parallel correlation is not verified.
+
+## Samples and correlation
+
+Each sample records the Playwright status, expected status, retry index, repeat
+index, duration and capture time.
+
+A trace reference is `verified` only when the collector:
+
+1. finds the injected trace id; and
+2. finds a server span whose parent is the injected span id.
+
+There is no time-window, nearest-request or synthetic fallback. If correlation
+is ambiguous, the sample is `incomplete` with a reason such as
+`trace-not-found`, `injected-parent-not-found` or `no-request-trace-recorded`.
+Incomplete samples make the affected comparison inconclusive.
+
+Samples are capped at 100 per scenario, 20 traces per sample, and 500 spans,
+200 queries and 100 errors per captured trace.
+
+## Baselines
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:82f70de6927a543f3381425f6ccfd4279d9449b3dc78859c33e5b620c80a7527 -->
+
+Convert a completed run with `baselineFromRun(run, { name })`, then pass the
+resulting `Baseline` to `saveBaseline(projectDir, baseline)` to persist the
+immutable record. A baseline contains:
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+- `sourceRunId`, project name, scenario identities and samples;
+- verified trace/query/error evidence;
+- deterministic diagnostic finding references;
+- environment snapshot;
+- stats, notes and limitations.
+
+A baseline does not follow later telemetry or application changes. It is never
+auto-deleted. `stacknext baseline remove <id> --yes` is the explicit removal
+path.
+
+## Commands
+
+```bash
+stacknext capture --name baseline --quiet --json \
+  -- pnpm exec playwright test --workers=1 --repeat-each=3 > baseline.json
+stacknext baseline save <run-id> --name baseline
+stacknext capture --name candidate --quiet --json \
+  -- pnpm exec playwright test --workers=1 --repeat-each=3 > candidate.json
+stacknext compare <baseline-id> <candidate-run-id> --fail-on regression
+```
+
+See the repository `docs/regression-testing.md` and
+`@stacknext/playwright/docs/index.md`.

package/docs/comparisons.md

@@ -0,0 +1,86 @@
+---
+title: Comparisons
+description: Deterministic median and threshold comparison, environment compatibility and inconclusive rules.
+---
+
+# Comparisons
+
+## API
+
+```ts
+import { compareBaseline } from '@stacknext/regression'
+
+const comparison = compareBaseline(baseline, candidateRun, {
+  minSamples: 3,
+  durationRegressionPct: 20,
+  durationRegressionMs: 25,
+  durationImprovementPct: 20,
+  durationImprovementMs: 25,
+  countRegressionMin: 1,
+  ignoreEnvironment: false,
+})
+```
+
+`compareBaseline(baseline, candidate, options?, meta?)` returns a
+`Comparison`. Ids and timestamps are never used to match scenarios or traces;
+matching uses stored stable keys.
+
+## Defaults
+
+`DEFAULT_COMPARISON_OPTIONS`:
+
+| Option | Default |
+| --- | --- |
+| `minSamples` | 3 |
+| `durationRegressionPct` | 20 |
+| `durationRegressionMs` | 25 |
+| `durationImprovementPct` | 20 |
+| `durationImprovementMs` | 25 |
+| `countRegressionMin` | 1 |
+| `ignoreEnvironment` | false |
+
+A duration change must cross both the percent and absolute threshold to be
+classified. Medians reduce noise.
+
+## Status and severity
+
+Statuses: `improved`, `regressed`, `unchanged`, `inconclusive`.
+
+Severity: `high`, `medium`, `low`, `none`, reported separately from status.
+
+`inconclusive` is not a pass. It means the evidence cannot support a verdict.
+`unchanged` means no configured threshold was crossed in this sample, not proof
+that nothing changed. `improved` is not automatically good: fewer spans or
+queries can mean missing instrumentation or skipped work.
+
+## Why a comparison becomes inconclusive
+
+- environment differences, unless `ignoreEnvironment` is set (a warning is still
+  recorded);
+- a candidate run that did not complete;
+- incomplete or missing scenario correlation;
+- fewer than `minSamples` verified samples per side;
+- missing scenarios;
+- variable trace shapes within one side or a changed trace key set;
+- changed diagnostic rule-set versions;
+- null database durations for a query-duration metric (unmeasured, not zero).
+
+Environment facts include Node.js, Next.js, platform, architecture, runtime,
+database adapters, instrumentation flags, verbose tracing, SDK version, rule-set
+version and Playwright version.
+
+## Metrics
+
+Comparison metrics can be `duration`, `count`, `test-status`, `error` or
+`finding` kinds. Evidence is bounded to 50 trace keys, 200 span keys, 100 query
+keys, 100 finding keys and 1,000 metrics per scenario.
+
+## What comparisons do not claim
+
+- No statistical significance, confidence intervals, p-values or effect sizes.
+- No causality.
+- No source, SQL or index analysis.
+- No automatic pass/fail unless the CLI `--fail-on` flag matches.
+
+The full methodology is in
+the repository `docs/comparison-methodology.md`.

package/docs/index.md

@@ -0,0 +1,92 @@
+---
+title: "@stacknext/regression"
+description: Capture, baseline, comparison schemas and deterministic local storage for StackNext runtime regression testing.
+---
+
+# @stacknext/regression
+
+`@stacknext/regression` owns the data model behind `stacknext capture`,
+`stacknext baseline`, `stacknext compare`, the Playwright fixture, the dashboard
+regression views and the MCP regression tools.
+
+## Who should read this
+
+Maintainers and advanced users building on the regression records. This is an
+**internal implementation package**; applications use the CLI and the optional
+`@stacknext/playwright` fixture instead of importing it directly.
+
+## Package boundary
+
+`regression` depends on `@stacknext/core` and `@stacknext/diagnostics`. It does
+not run Playwright itself, start a collector, serve HTTP or contact a remote
+service. Storage is local and report-only.
+
+## Public API
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:27de812198c94ba1d63f3e6f4ab6e1cc83191a39d69ae91a0151c6ea756a7c51 -->
+
+```ts
+import {
+  compareBaseline,
+  verifyTraceCorrelation,
+  capturedSampleFromSubmission,
+  buildEnvironmentSnapshot,
+  compareEnvironments,
+  saveRun,
+  loadRun,
+  listRuns,
+  saveBaseline,
+  loadBaseline,
+  listBaselines,
+  saveComparison,
+  loadComparison,
+  listComparisons,
+  createRunId,
+  createBaselineId,
+  createComparisonId,
+  createSampleId,
+  scenarioIdentity,
+  DEFAULT_COMPARISON_OPTIONS,
+} from '@stacknext/regression'
+```
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+See the installed declarations for every helper. The main concepts:
+
+| Concept | Purpose |
+| --- | --- |
+| `scenarioIdentity` | Stable `scn-...` id from an explicit annotation, test id or file/title/project fallback. |
+| `verifyTraceCorrelation` | Accepts a sample only when the injected trace and a server span parented to the injected span exist. |
+| `buildEnvironmentSnapshot` | Records Node.js, Next.js, OS, runtime, adapters, instrumentation, rule set and Playwright versions. |
+| `compareEnvironments` | Lists environment differences before a comparison. |
+| `compareBaseline` | Deterministic median/threshold comparison of a baseline and candidate. |
+| `saveRun` / `saveBaseline` / `saveComparison` | Atomic local writes under `.stacknext`. |
+
+## Formats
+
+| Constant | Value |
+| --- | --- |
+| `STACKNEXT_RUN_FORMAT` | `stacknext-test-run` |
+| `STACKNEXT_BASELINE_FORMAT` | `stacknext-baseline` |
+| `STACKNEXT_COMPARISON_FORMAT` | `stacknext-comparison` |
+| `STACKNEXT_REGRESSION_FORMAT_VERSION` | `1` |
+| `STACKNEXT_REGRESSION_ENGINE_VERSION` | The installed package version |
+
+Ids are strict: `run-<16 hex>`, `base-<16 hex>`, `cmp-<16 hex>`,
+`scn-<16 hex>` and `smp-<16 hex>`.
+
+## Documentation map
+
+- [Captures](captures.md) — run and baseline lifecycle, correlation and statuses.
+- [Comparisons](comparisons.md) — metrics, thresholds and inconclusive rules.
+- [Storage](storage.md) — directories, permissions, atomic writes and retention.
+
+## Related packages
+
+- `@stacknext/playwright` submits correlated samples during `stacknext capture`.
+- `@stacknext/cli` orchestrates capture, baseline and compare commands.
+- `@stacknext/mcp` reads saved runs, baselines and comparisons.
+- `@stacknext/dashboard` renders the same records.

package/docs/storage.md

@@ -0,0 +1,75 @@
+---
+title: Storage
+description: Regression record directories, permissions, atomic writes, validation and retention rules.
+---
+
+# Storage
+
+## Directories
+
+Regression records live under the application's `.stacknext` directory:
+
+```text
+.stacknext/
+├── runs/         # run-<16 hex>.json
+├── baselines/    # base-<16 hex>.json
+└── comparisons/  # cmp-<16 hex>.json
+```
+
+The directory is created with mode `0700`; record files use mode `0600`.
+`.stacknext/.gitignore` ignores runtime state, but saved records remain local
+debugging artifacts and should be reviewed before sharing.
+
+## API
+
+```ts
+import {
+  saveRun,
+  loadRun,
+  listRuns,
+  listAllRuns,
+  saveBaseline,
+  loadBaseline,
+  listBaselines,
+  saveComparison,
+  loadComparison,
+  listComparisons,
+  regressionDir,
+  runsDir,
+  baselinesDir,
+  comparisonsDir,
+} from '@stacknext/regression'
+```
+
+Writes validate the full record with its versioned Zod schema before touching
+disk. Writes are atomic. A record is never overwritten unless the caller passes
+`overwrite: true`; the CLI only does that on an explicit `--overwrite` request.
+
+## Listing
+
+List functions return `{ items, total, limit, offset, invalid }`. `limit` is
+clamped to 1–200 with a default of 50. Invalid ids and stale records are counted
+in `invalid` and left visible; they are not repaired or silently deleted.
+
+## Size and retention
+
+- Each record is capped at 16 MiB.
+- Runs, baselines and comparisons are **never pruned automatically**.
+- StackNext never uploads records.
+- `stacknext uninstall --remove-data` requires explicit confirmation and refuses
+  while a StackNext process is running.
+
+## Invalid records
+
+`RegressionStorageError` carries a code used by callers to distinguish
+`invalid`, `not-found`, `exists` and storage failures. Invalid ids are rejected
+before the filesystem is read. A malformed file is counted, not rewritten.
+
+## Privacy
+
+Records contain redacted scenario identity, trace/span/query/error evidence,
+diagnostic references, environment facts and a sanitized command snapshot.
+They never contain request/response bodies, headers, cookies, URL query values,
+SQL bind parameters, Playwright screenshots/video/trace archives or the
+collector token. The full boundary is in
+the repository `docs/privacy.md`.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@stacknext/regression",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Deterministic Playwright-linked runtime regression capture for StackNext",
   "license": "MIT",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,8 +19,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@stacknext/core": "0.9.0",
-    "@stacknext/diagnostics": "0.9.0",
+    "@stacknext/core": "0.10.0",
+    "@stacknext/diagnostics": "0.10.0",
     "zod": "4.6.7"
   },
   "engines": {