@stacknext/regression 0.10.0 → 0.11.1

package/README.md

@@ -13,6 +13,56 @@ npm install --save-dev @stacknext/cli @stacknext/next @stacknext/playwright
 npx stacknext capture --name baseline -- npx playwright test --workers=1
 ```
 
-This package is ESM-only and requires Node.js 20.9 or newer.
+This package is normally consumed through the CLI and the optional Playwright
+fixture. It does not run Playwright, start a collector or contact a remote
+service.
+
+## 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`. |
+
+Ids are strict: `run-<16 hex>`, `base-<16 hex>`, `cmp-<16 hex>`,
+`scn-<16 hex>` and `smp-<16 hex>`.
+
+## Storage
+
+Runs, baselines and comparisons live under
+`.stacknext/{runs,baselines,comparisons}` with strict versioned schemas,
+`0700`/`0600` permissions, atomic writes and a 16 MiB cap. Records are never
+auto-deleted and are never uploaded.
+
+## Documentation
+
+- [Package overview](docs/index.md)
+- [Captures](docs/captures.md)
+- [Comparisons](docs/comparisons.md)
+- [Storage](docs/storage.md)
+
+The `docs/` directory ships in the npm archive. Public guides live on the
+[documentation site](https://github.com/marrrkkk/stacknext/tree/main/apps/docs).
+
+## AI agents
+
+Agents should read `docs/comparisons.md` before explaining a result. Never
+present a comparison as a statistical test or a confirmed cause. Report
+`inconclusive` as inconclusive, and cite the environment differences and
+correlation reasons.
+
+## Development
+
+```bash
+pnpm --filter @stacknext/regression build
+pnpm --filter @stacknext/regression typecheck
+pnpm test
+```
+
+The package is ESM-only and requires Node.js 20.9 or newer.
 
 License: MIT.

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.10.0";
+export declare const STACKNEXT_REGRESSION_ENGINE_VERSION = "0.11.1";
 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.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.10.0';
+export const STACKNEXT_REGRESSION_ENGINE_VERSION = '0.11.1';
 export const RUN_STATUSES = [
     'running',
     'completed',

package/docs/captures.md

@@ -88,5 +88,5 @@ stacknext capture --name candidate --quiet --json \
 stacknext compare <baseline-id> <candidate-run-id> --fail-on regression
 ```
 
-See the repository `docs/regression-testing.md` and
+See the repository `apps/docs/regression-testing.md` and
 `@stacknext/playwright/docs/index.md`.

package/docs/comparisons.md

@@ -83,4 +83,4 @@ keys, 100 finding keys and 1,000 metrics per scenario.
 - No automatic pass/fail unless the CLI `--fail-on` flag matches.
 
 The full methodology is in
-the repository `docs/comparison-methodology.md`.
+the repository `apps/docs/comparison-methodology.md`.

package/docs/storage.md

@@ -72,4 +72,4 @@ 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`.
+the repository `apps/docs/privacy.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacknext/regression",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Deterministic Playwright-linked runtime regression capture for StackNext",
   "license": "MIT",
   "type": "module",
@@ -19,8 +19,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@stacknext/core": "0.10.0",
-    "@stacknext/diagnostics": "0.10.0",
+    "@stacknext/core": "0.11.1",
+    "@stacknext/diagnostics": "0.11.1",
     "zod": "4.6.7"
   },
   "engines": {