@aplaytest/core 0.1.0

package/dist/history/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Run and attempt records — the unit of test history.
+ *
+ * The reporter writes these as JSON; the history store ingests them
+ * into SQLite. Keeping the reporter's output a plain file rather than a
+ * database write matters: the reporter runs INSIDE the test process, where a
+ * native SQLite binding, a migration, or a lock contention bug would become a
+ * test failure. The run path stays dependency-light on purpose.
+ */
+import type { FailureKind } from '../taxonomy/kinds.js';
+import type { EvidenceId } from '../evidence/types.js';
+export type Outcome = 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
+export interface AttemptRecord {
+    /** Playwright's stable test id — survives a title rename. */
+    readonly testId: string;
+    readonly title: string;
+    readonly titlePath: readonly string[];
+    readonly file: string;
+    readonly line: number;
+    readonly project: string;
+    readonly tags: readonly string[];
+    readonly retry: number;
+    readonly outcome: Outcome;
+    readonly failureKind: FailureKind | null;
+    readonly durationMs: number;
+    readonly workerIndex: number;
+    readonly shard: {
+        readonly current: number;
+        readonly total: number;
+    } | null;
+    /** Joins to OpenTelemetry. Null when the consumer supplies no identity hook. */
+    readonly traceId: string | null;
+    readonly evidenceId: EvidenceId | null;
+    /**
+     * Other tests that ran on the same worker. Powers the co-scheduling lift
+     * signal used to distinguish test pollution from ordinary flakiness.
+     */
+    readonly coScheduled: readonly string[];
+    /**
+     * Routes this test actually visited.
+     *
+     * Independent of the import graph, and the only signal that can narrow
+     * selection in a suite whose specs all import one composed fixture.
+     */
+    readonly routes: readonly string[];
+}
+export interface RunRecord {
+    readonly schemaVersion: 1;
+    readonly runId: string;
+    readonly startedAt: string;
+    readonly finishedAt: string | null;
+    readonly commit: string | null;
+    readonly branch: string | null;
+    readonly appEnv: string | null;
+    readonly ci: boolean;
+    readonly workers: number;
+    readonly shard: {
+        readonly current: number;
+        readonly total: number;
+    } | null;
+    readonly atestVersion: string;
+    readonly playwrightVersion: string | null;
+    readonly attempts: readonly AttemptRecord[];
+}
+export declare const RUN_SCHEMA_VERSION: 1;
+export declare function isFailure(outcome: Outcome): boolean;
+/** Skipped and interrupted attempts are not evidence about a test's behaviour. */
+export declare function isConclusive(outcome: Outcome): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/history/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/history/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,CAAC;AAEnF,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5E,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AAED,eAAO,MAAM,kBAAkB,EAAG,CAAU,CAAC;AAE7C,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEnD;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEtD"}

package/dist/history/types.js

@@ -0,0 +1,18 @@
+/**
+ * Run and attempt records — the unit of test history.
+ *
+ * The reporter writes these as JSON; the history store ingests them
+ * into SQLite. Keeping the reporter's output a plain file rather than a
+ * database write matters: the reporter runs INSIDE the test process, where a
+ * native SQLite binding, a migration, or a lock contention bug would become a
+ * test failure. The run path stays dependency-light on purpose.
+ */
+export const RUN_SCHEMA_VERSION = 1;
+export function isFailure(outcome) {
+    return outcome === 'failed' || outcome === 'timedOut';
+}
+/** Skipped and interrupted attempts are not evidence about a test's behaviour. */
+export function isConclusive(outcome) {
+    return outcome === 'passed' || outcome === 'failed' || outcome === 'timedOut';
+}
+//# sourceMappingURL=types.js.map

package/dist/history/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/history/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuDH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAU,CAAC;AAE7C,MAAM,UAAU,SAAS,CAAC,OAAgB;IACxC,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,UAAU,CAAC;AACxD,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,UAAU,CAAC;AAChF,CAAC"}

package/dist/history/url.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Where history lives, expressed as one string.
+ *
+ * `--db` was already the only knob naming the store, and every consumer — the
+ * CLI, the generated workflows, `atest.config.ts` — passes it around as an
+ * opaque path. Making it a URL rather than adding `--history-account`,
+ * `--history-container` and `--history-prefix` means the blob backend needs no
+ * new flag anywhere, and a repo switches from a local file to Azure by
+ * changing one repository variable.
+ *
+ * Parsing lives in core because it is pure string work that the CLI, the
+ * Azure driver and `doctor` all need, and because a typo in a container name
+ * should fail with a readable message before any credential is acquired. The
+ * network code that acts on the result lives in `@aplaytest/store-azure`.
+ */
+export interface AzureBlobTarget {
+    readonly kind: 'azure-blob';
+    /** Base URL for `BlobServiceClient` — origin plus, on the emulator, the account. */
+    readonly serviceUrl: string;
+    readonly account: string;
+    readonly container: string;
+    /** Key prefix inside the container. Empty, or normalised to end with `/`. */
+    readonly prefix: string;
+    /**
+     * Days of history to read. Bounds the download: a driver that fetches every
+     * record ever written gets slower every week until someone disables it.
+     */
+    readonly windowDays: number | null;
+    /**
+     * Score against the store; never write to it. `?readonly=1`.
+     *
+     * This is the pull-request configuration, and it is a first-class mode
+     * rather than an accident of RBAC. Azure already refuses the write — the PR
+     * identity holds Reader — but "refused" arrives as a 403 per shard file
+     * after four retries each, which turns a correct policy into a slow job and
+     * a log full of red herrings. Saying it up front also documents the intent
+     * where somebody reading the workflow will find it: a flake baseline
+     * describes trunk, and a branch whose test code may itself be broken must
+     * not enter it before anyone has decided to merge.
+     */
+    readonly readOnly: boolean;
+}
+export type HistoryTarget = {
+    readonly kind: 'memory';
+} | {
+    readonly kind: 'sqlite';
+    readonly path: string;
+} | AzureBlobTarget;
+export interface ParseHistoryUrlOptions {
+    /**
+     * DNS suffix for the `azblob://` shorthand. Sovereign clouds differ
+     * (`blob.core.usgovcloudapi.net`, `blob.core.chinacloudapi.cn`), and hard
+     * coding the commercial one would silently resolve to a host that does not
+     * exist rather than failing with a name anyone can act on.
+     */
+    readonly endpointSuffix?: string | undefined;
+}
+export declare const DEFAULT_BLOB_ENDPOINT_SUFFIX = "blob.core.windows.net";
+export declare class HistoryUrlError extends Error {
+    constructor(message: string);
+}
+/**
+ * Accepted forms:
+ *
+ *   :memory:                                        throwaway (not the config default)
+ *   .atest/history.sqlite                           a local file
+ *   azblob://<account>/<container>[/<prefix>]       Azure, via the DNS suffix
+ *   https://<account>.blob.core.windows.net/<c>/<p> Azure, fully qualified
+ *   http://127.0.0.1:10000/<account>/<c>/<p>        Azurite, account in path
+ *
+ * Anything unrecognised is a FILE PATH, not an error. `--db` has always taken
+ * one, and a Windows path like `C:\atest\history.sqlite` parses as a URL with
+ * scheme `c:` — rejecting unknown schemes would break the case the flag was
+ * built for.
+ */
+export declare function parseHistoryUrl(url: string, options?: ParseHistoryUrlOptions): HistoryTarget;
+/** Short, log-safe description. Used by `doctor` and every "what am I reading?" line. */
+export declare function describeHistoryTarget(target: HistoryTarget): string;
+//# sourceMappingURL=url.d.ts.map

package/dist/history/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/history/url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClD,eAAe,CAAC;AAEpB,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED,eAAO,MAAM,4BAA4B,0BAA0B,CAAC;AAMpE,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAuDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,aAAa,CAoChG;AAED,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAYnE"}

package/dist/history/url.js

@@ -0,0 +1,121 @@
+/**
+ * Where history lives, expressed as one string.
+ *
+ * `--db` was already the only knob naming the store, and every consumer — the
+ * CLI, the generated workflows, `atest.config.ts` — passes it around as an
+ * opaque path. Making it a URL rather than adding `--history-account`,
+ * `--history-container` and `--history-prefix` means the blob backend needs no
+ * new flag anywhere, and a repo switches from a local file to Azure by
+ * changing one repository variable.
+ *
+ * Parsing lives in core because it is pure string work that the CLI, the
+ * Azure driver and `doctor` all need, and because a typo in a container name
+ * should fail with a readable message before any credential is acquired. The
+ * network code that acts on the result lives in `@aplaytest/store-azure`.
+ */
+export const DEFAULT_BLOB_ENDPOINT_SUFFIX = 'blob.core.windows.net';
+/** Azure's rule, enforced here so the failure names the field. */
+const CONTAINER_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const ACCOUNT_NAME = /^[a-z0-9]{3,24}$/;
+export class HistoryUrlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HistoryUrlError';
+    }
+}
+function parseWindowDays(params) {
+    const raw = params.get('window');
+    if (raw === null)
+        return null;
+    const days = Number.parseInt(raw, 10);
+    if (!Number.isInteger(days) || days < 1) {
+        throw new HistoryUrlError(`?window= must be a positive integer number of days, got "${raw}".`);
+    }
+    return days;
+}
+function normalisePrefix(segments) {
+    const joined = segments.filter(s => s !== '').join('/');
+    return joined === '' ? '' : `${joined}/`;
+}
+function azureTarget(url, serviceUrl, account, segments) {
+    const container = segments[0];
+    if (container === undefined || container === '') {
+        throw new HistoryUrlError(`"${url.href}" names no container. Expected azblob://<account>/<container>[/<prefix>].`);
+    }
+    if (container.length < 3 || container.length > 63 || !CONTAINER_NAME.test(container)) {
+        throw new HistoryUrlError(`"${container}" is not a valid container name — 3-63 chars, lowercase letters, digits and single dashes.`);
+    }
+    if (!ACCOUNT_NAME.test(account)) {
+        throw new HistoryUrlError(`"${account}" is not a valid storage account name — 3-24 lowercase alphanumerics.`);
+    }
+    const readOnly = url.searchParams.get('readonly');
+    return {
+        kind: 'azure-blob',
+        serviceUrl,
+        account,
+        container,
+        prefix: normalisePrefix(segments.slice(1)),
+        windowDays: parseWindowDays(url.searchParams),
+        // Present-but-empty (`?readonly`) counts as on, because that is what
+        // somebody typing it means. Only an explicit falsy value turns it off.
+        readOnly: readOnly !== null && readOnly !== '0' && readOnly !== 'false',
+    };
+}
+/**
+ * Accepted forms:
+ *
+ *   :memory:                                        throwaway (not the config default)
+ *   .atest/history.sqlite                           a local file
+ *   azblob://<account>/<container>[/<prefix>]       Azure, via the DNS suffix
+ *   https://<account>.blob.core.windows.net/<c>/<p> Azure, fully qualified
+ *   http://127.0.0.1:10000/<account>/<c>/<p>        Azurite, account in path
+ *
+ * Anything unrecognised is a FILE PATH, not an error. `--db` has always taken
+ * one, and a Windows path like `C:\atest\history.sqlite` parses as a URL with
+ * scheme `c:` — rejecting unknown schemes would break the case the flag was
+ * built for.
+ */
+export function parseHistoryUrl(url, options = {}) {
+    const trimmed = url.trim();
+    if (trimmed === ':memory:' || trimmed === '')
+        return { kind: 'memory' };
+    if (trimmed.startsWith('azblob://')) {
+        const suffix = options.endpointSuffix ?? DEFAULT_BLOB_ENDPOINT_SUFFIX;
+        const parsed = new URL(trimmed);
+        // `azblob://acct/container` puts the account in the authority, so it is
+        // already lowercased and stripped of a path by the URL parser.
+        const account = parsed.hostname;
+        const segments = parsed.pathname.split('/').filter(s => s !== '');
+        return azureTarget(parsed, `https://${account}.${suffix}`, account, segments);
+    }
+    if (trimmed.startsWith('https://') || trimmed.startsWith('http://')) {
+        const parsed = new URL(trimmed);
+        const segments = parsed.pathname.split('/').filter(s => s !== '');
+        const subdomain = /^([a-z0-9]{3,24})\.blob\./.exec(parsed.hostname);
+        if (subdomain !== null && subdomain[1] !== undefined) {
+            return azureTarget(parsed, parsed.origin, subdomain[1], segments);
+        }
+        // Emulator convention: the account is the first path segment because
+        // Azurite serves every account from one host.
+        const account = segments[0];
+        if (account === undefined) {
+            throw new HistoryUrlError(`"${trimmed}" is not a blob endpoint. Expected <account>.${DEFAULT_BLOB_ENDPOINT_SUFFIX}/<container>, ` +
+                `or an emulator URL with the account as the first path segment.`);
+        }
+        return azureTarget(parsed, `${parsed.origin}/${account}`, account, segments.slice(1));
+    }
+    return { kind: 'sqlite', path: trimmed };
+}
+/** Short, log-safe description. Used by `doctor` and every "what am I reading?" line. */
+export function describeHistoryTarget(target) {
+    switch (target.kind) {
+        case 'memory':
+            return 'in-memory (discarded when the process exits)';
+        case 'sqlite':
+            return `sqlite · ${target.path}`;
+        case 'azure-blob':
+            return (`azure blob · ${target.account}/${target.container}/${target.prefix}` +
+                (target.readOnly ? ' (read-only)' : ''));
+    }
+}
+//# sourceMappingURL=url.js.map

package/dist/history/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/history/url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA6CH,MAAM,CAAC,MAAM,4BAA4B,GAAG,uBAAuB,CAAC;AAEpE,kEAAkE;AAClE,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAClD,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAExC,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,SAAS,eAAe,CAAC,MAAuB;IAC9C,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACjC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,eAAe,CAAC,4DAA4D,GAAG,IAAI,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,eAAe,CAAC,QAA2B;IAClD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxD,OAAO,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,CAAC;AAC3C,CAAC;AAED,SAAS,WAAW,CAClB,GAAQ,EACR,UAAkB,EAClB,OAAe,EACf,QAA2B;IAE3B,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QAChD,MAAM,IAAI,eAAe,CACvB,IAAI,GAAG,CAAC,IAAI,2EAA2E,CACxF,CAAC;IACJ,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,CAAC,MAAM,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,eAAe,CACvB,IAAI,SAAS,4FAA4F,CAC1G,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,eAAe,CACvB,IAAI,OAAO,uEAAuE,CACnF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAElD,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,UAAU;QACV,OAAO;QACP,SAAS;QACT,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC1C,UAAU,EAAE,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC;QAC7C,qEAAqE;QACrE,uEAAuE;QACvE,QAAQ,EAAE,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,OAAO;KACxE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,UAAkC,EAAE;IAC/E,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,KAAK,UAAU,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAExE,IAAI,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,OAAO,CAAC,cAAc,IAAI,4BAA4B,CAAC;QACtE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAChC,wEAAwE;QACxE,+DAA+D;QAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QAClE,OAAO,WAAW,CAAC,MAAM,EAAE,WAAW,OAAO,IAAI,MAAM,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAChF,CAAC;IAED,IAAI,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACpE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QAClE,MAAM,SAAS,GAAG,2BAA2B,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAEpE,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YACrD,OAAO,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACpE,CAAC;QAED,qEAAqE;QACrE,8CAA8C;QAC9C,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,eAAe,CACvB,IAAI,OAAO,gDAAgD,4BAA4B,gBAAgB;gBACrG,gEAAgE,CACnE,CAAC;QACJ,CAAC;QACD,OAAO,WAAW,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACxF,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3C,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,qBAAqB,CAAC,MAAqB;IACzD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,QAAQ;YACX,OAAO,8CAA8C,CAAC;QACxD,KAAK,QAAQ;YACX,OAAO,YAAY,MAAM,CAAC,IAAI,EAAE,CAAC;QACnC,KAAK,YAAY;YACf,OAAO,CACL,gBAAgB,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE;gBACrE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC,CACxC,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @aplaytest/core — types, failure taxonomy, locator ranking, and configuration.
+ *
+ * This package has no Playwright dependency, makes no network calls, and never
+ * touches a model. Everything here must be unit-testable in isolation; that
+ * constraint is what keeps the engines above it testable too.
+ */
+export { FAILURE_KINDS, NEVER_HEAL, ROUTING, healEligibility, isHealable, countsTowardFlakeStats, } from './taxonomy/kinds.js';
+export type { FailureKind, HealEligibility, FlakeRelevance, KindRouting, } from './taxonomy/kinds.js';
+export { classify, listRules } from './taxonomy/classify.js';
+export type { Classification, Confidence } from './taxonomy/classify.js';
+export { parsePlaywrightError, splitCallLog, stripAnsi, stripCodeFrame, joinErrors, } from './taxonomy/parse-error.js';
+export type { ParsedError, ErrorLike } from './taxonomy/parse-error.js';
+export { LOCATOR_STRATEGIES, STABILITY_RANK, MAX_STABILITY_RANK, parseLocator, stabilityRankOf, stabilityDelta, testIdDistance, } from './locator/stability.js';
+export type { LocatorStrategy, ParsedLocator } from './locator/stability.js';
+export { ATEST_VERSION } from './version.js';
+export { EVIDENCE_SCHEMA_VERSION, formatFailingStep } from './evidence/types.js';
+export { evidenceId, isEvidenceId } from './evidence/id.js';
+export type { EvidenceIdParts } from './evidence/id.js';
+export { redact, redactString, redactUrl, REDACTED } from './evidence/redact.js';
+export { EvidenceStore, SchemaVersionError, loadRunBundles, parseEvidenceBundle, isEvidenceBundle, } from './evidence/store.js';
+export type { EvidenceStoreOptions, LoadRunBundlesResult, SkippedBundle } from './evidence/store.js';
+export type { EvidenceBundle, EvidenceId, ClassifiableFailure, LocatorCandidate, StepRecord, SelectorSource, RequestRecord, AppSpanRecord, Rect, } from './evidence/types.js';
+export { RUN_SCHEMA_VERSION, isFailure, isConclusive } from './history/types.js';
+export type { RunRecord, AttemptRecord, Outcome } from './history/types.js';
+export { SqliteHistoryStore } from './history/store.js';
+export type { HistoryStore, HistoricalAttempt, HistoryQuery, TestKey } from './history/store.js';
+export { HistoryIndex, MemoryHistoryStore, shardKeyOf } from './history/memory-index.js';
+export { parseHistoryUrl, describeHistoryTarget, HistoryUrlError, DEFAULT_BLOB_ENDPOINT_SUFFIX, } from './history/url.js';
+export type { HistoryTarget, AzureBlobTarget, ParseHistoryUrlOptions, } from './history/url.js';
+export { ingestDirectory } from './history/ingest.js';
+export { ingestPlaywrightJson } from './history/ingest-playwright.js';
+export type { IngestPlaywrightJsonOptions } from './history/ingest-playwright.js';
+export { mapPlaywrightReport } from './history/playwright-report.js';
+export type { JsonReport, JsonSuite, JsonSpec, JsonTest, JsonResult, MappedReport, MapReportOptions, RunIdentity, } from './history/playwright-report.js';
+export type { IngestResult } from './history/ingest.js';
+export { defineAtestConfig, AtestConfigSchema, ExecutionModeSchema, AggressivenessSchema, AGGRESSIVENESS_PRESETS, } from './config/schema.js';
+export type { AtestConfig, AtestConfigInput, AtestUserConfig, ResolvedAtestConfig, AtestIdentity, ExecutionMode, Aggressiveness, } from './config/schema.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * @aplaytest/core — types, failure taxonomy, locator ranking, and configuration.
+ *
+ * This package has no Playwright dependency, makes no network calls, and never
+ * touches a model. Everything here must be unit-testable in isolation; that
+ * constraint is what keeps the engines above it testable too.
+ */
+// Taxonomy
+export { FAILURE_KINDS, NEVER_HEAL, ROUTING, healEligibility, isHealable, countsTowardFlakeStats, } from './taxonomy/kinds.js';
+export { classify, listRules } from './taxonomy/classify.js';
+export { parsePlaywrightError, splitCallLog, stripAnsi, stripCodeFrame, joinErrors, } from './taxonomy/parse-error.js';
+// Locators
+export { LOCATOR_STRATEGIES, STABILITY_RANK, MAX_STABILITY_RANK, parseLocator, stabilityRankOf, stabilityDelta, testIdDistance, } from './locator/stability.js';
+// Identity
+export { ATEST_VERSION } from './version.js';
+// Evidence
+export { EVIDENCE_SCHEMA_VERSION, formatFailingStep } from './evidence/types.js';
+export { evidenceId, isEvidenceId } from './evidence/id.js';
+export { redact, redactString, redactUrl, REDACTED } from './evidence/redact.js';
+export { EvidenceStore, SchemaVersionError, loadRunBundles, parseEvidenceBundle, isEvidenceBundle, } from './evidence/store.js';
+// History
+export { RUN_SCHEMA_VERSION, isFailure, isConclusive } from './history/types.js';
+export { SqliteHistoryStore } from './history/store.js';
+export { HistoryIndex, MemoryHistoryStore, shardKeyOf } from './history/memory-index.js';
+export { parseHistoryUrl, describeHistoryTarget, HistoryUrlError, DEFAULT_BLOB_ENDPOINT_SUFFIX, } from './history/url.js';
+export { ingestDirectory } from './history/ingest.js';
+export { ingestPlaywrightJson } from './history/ingest-playwright.js';
+export { mapPlaywrightReport } from './history/playwright-report.js';
+// Config
+export { defineAtestConfig, AtestConfigSchema, ExecutionModeSchema, AggressivenessSchema, AGGRESSIVENESS_PRESETS, } from './config/schema.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,WAAW;AACX,OAAO,EACL,aAAa,EACb,UAAU,EACV,OAAO,EACP,eAAe,EACf,UAAU,EACV,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAG7D,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,SAAS,EACT,cAAc,EACd,UAAU,GACX,MAAM,2BAA2B,CAAC;AAGnC,WAAW;AACX,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,wBAAwB,CAAC;AAGhC,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,WAAW;AACX,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE5D,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAc7B,UAAU;AACV,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACzF,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,4BAA4B,GAC7B,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAEtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAarE,SAAS;AACT,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC"}

package/dist/locator/stability.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Locator stability ranking and parsing.
+ *
+ * A heal that makes a test pass by moving to a WEAKER locator is not a win:
+ * replacing a test id with a text match makes the test green and makes it
+ * fragile, coupling it to copy that product can change at any time. The engine
+ * therefore treats a negative stability delta as a warning that forces human
+ * review, and refuses to generate anything below a configured floor.
+ */
+export declare const LOCATOR_STRATEGIES: readonly ["testid", "role", "label", "placeholder", "text", "css", "xpath"];
+export type LocatorStrategy = (typeof LOCATOR_STRATEGIES)[number];
+/** Lower is more durable. */
+export declare const STABILITY_RANK: Readonly<Record<LocatorStrategy, number>>;
+export declare const MAX_STABILITY_RANK = 6;
+export interface ParsedLocator {
+    readonly strategy: LocatorStrategy;
+    /** The identifying value: a test id, an accessible name, a CSS selector. */
+    readonly value: string;
+    /** The original expression, verbatim. */
+    readonly raw: string;
+    /**
+     * Accessible name when the locator carries one (`getByRole('button', { name })`).
+     * Null for nameless roles — those are too vague to heal.
+     */
+    readonly accessibleName: string | null;
+}
+/**
+ * Best-effort parse of a Playwright selector or locator expression.
+ * Returns null when nothing recognisable is present — callers must handle it
+ * rather than assuming a strategy.
+ */
+export declare function parseLocator(expression: string | null | undefined): ParsedLocator | null;
+export declare function stabilityRankOf(strategy: LocatorStrategy): number;
+/**
+ * Positive = the replacement is MORE stable. Negative = less stable, which
+ * requires human review regardless of aggressiveness setting.
+ */
+export declare function stabilityDelta(from: LocatorStrategy, to: LocatorStrategy): number;
+/**
+ * Positional, prefix-weighted distance between two test ids.
+ *
+ * Test ids in a component-structured app read outside-in —
+ * `<feature>-<component>-<element>` — so the LEADING tokens identify where the
+ * element lives and the trailing token identifies what it is. Elements get
+ * renamed far more often than they move between features, so disagreement in
+ * the prefix is the stronger signal that these are different elements.
+ * Weights therefore decay from the front.
+ *
+ *   gym-card-name → gym-card-title    0.17  same place, renamed  ← the common heal
+ *   gym-card-name → gym-card-county   0.17  same place, sibling field
+ *   gym-card-name → event-card-name   0.50  different feature
+ *   gym-card-name → checkout-submit   1.00  unrelated
+ *
+ * Note that a rename and a sibling field score identically. That is honest:
+ * nothing in the STRING distinguishes them. Separating the two is exactly the
+ * judgement the Tier-1 ranker exists to make, using the failing assertion's
+ * domain arguments — which is why Tier 0 hands over candidates rather than
+ * picking one.
+ *
+ * Returns 0 (identical) .. 1 (nothing in common).
+ */
+export declare function testIdDistance(a: string, b: string): number;
+//# sourceMappingURL=stability.d.ts.map

package/dist/locator/stability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stability.d.ts","sourceRoot":"","sources":["../../src/locator/stability.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,kBAAkB,6EAQrB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,6BAA6B;AAC7B,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAQpE,CAAC;AAEF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAgBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,IAAI,CA8BxF;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAEjE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,eAAe,GAAG,MAAM,CAEjF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAmB3D"}

package/dist/locator/stability.js

@@ -0,0 +1,127 @@
+/**
+ * Locator stability ranking and parsing.
+ *
+ * A heal that makes a test pass by moving to a WEAKER locator is not a win:
+ * replacing a test id with a text match makes the test green and makes it
+ * fragile, coupling it to copy that product can change at any time. The engine
+ * therefore treats a negative stability delta as a warning that forces human
+ * review, and refuses to generate anything below a configured floor.
+ */
+export const LOCATOR_STRATEGIES = [
+    'testid',
+    'role',
+    'label',
+    'placeholder',
+    'text',
+    'css',
+    'xpath',
+];
+/** Lower is more durable. */
+export const STABILITY_RANK = {
+    testid: 0,
+    role: 1,
+    label: 2,
+    placeholder: 3,
+    text: 4,
+    css: 5,
+    xpath: 6,
+};
+export const MAX_STABILITY_RANK = 6;
+const ROLE_WITH_NAME = /getByRole\(\s*['"`]([^'"`]+)['"`]\s*,\s*\{[^}]*\bname:\s*['"`]([^'"`]+)['"`]/;
+const ROLE_ONLY = /getByRole\(\s*['"`]([^'"`]+)['"`]/;
+const PATTERNS = [
+    { strategy: 'testid', re: /getByTestId\(\s*['"`]([^'"`]+)['"`]/ },
+    { strategy: 'testid', re: /\[data-testid=['"]?([^\]'"]+)['"]?\]/ },
+    { strategy: 'label', re: /getByLabel\(\s*['"`]([^'"`]+)['"`]/ },
+    { strategy: 'placeholder', re: /getByPlaceholder\(\s*['"`]([^'"`]+)['"`]/ },
+    { strategy: 'text', re: /getByText\(\s*['"`]([^'"`]+)['"`]/ },
+    { strategy: 'text', re: /text=(.+)$/ },
+    { strategy: 'xpath', re: /^\s*(?:xpath=)?(\/\/.+)$/ },
+];
+/**
+ * Best-effort parse of a Playwright selector or locator expression.
+ * Returns null when nothing recognisable is present — callers must handle it
+ * rather than assuming a strategy.
+ */
+export function parseLocator(expression) {
+    if (expression === null || expression === undefined)
+        return null;
+    const raw = expression.trim();
+    if (raw === '')
+        return null;
+    const namedRole = ROLE_WITH_NAME.exec(raw);
+    const role = namedRole?.[1];
+    const roleName = namedRole?.[2];
+    if (role !== undefined && role !== '' && roleName !== undefined && roleName !== '') {
+        return { strategy: 'role', value: role, raw, accessibleName: roleName };
+    }
+    const bareRole = ROLE_ONLY.exec(raw);
+    const bare = bareRole?.[1];
+    if (bare !== undefined && bare !== '') {
+        return { strategy: 'role', value: bare, raw, accessibleName: null };
+    }
+    for (const { strategy, re } of PATTERNS) {
+        const match = re.exec(raw);
+        const captured = match?.[1];
+        if (captured !== undefined && captured !== '') {
+            return { strategy, value: captured, raw, accessibleName: null };
+        }
+    }
+    // Anything left that looks like a selector is treated as CSS. This is a
+    // deliberate floor, not a guess: CSS ranks low, so an unparsed locator can
+    // never be mistaken for a durable one.
+    return { strategy: 'css', value: raw, raw, accessibleName: null };
+}
+export function stabilityRankOf(strategy) {
+    return STABILITY_RANK[strategy];
+}
+/**
+ * Positive = the replacement is MORE stable. Negative = less stable, which
+ * requires human review regardless of aggressiveness setting.
+ */
+export function stabilityDelta(from, to) {
+    return STABILITY_RANK[from] - STABILITY_RANK[to];
+}
+/**
+ * Positional, prefix-weighted distance between two test ids.
+ *
+ * Test ids in a component-structured app read outside-in —
+ * `<feature>-<component>-<element>` — so the LEADING tokens identify where the
+ * element lives and the trailing token identifies what it is. Elements get
+ * renamed far more often than they move between features, so disagreement in
+ * the prefix is the stronger signal that these are different elements.
+ * Weights therefore decay from the front.
+ *
+ *   gym-card-name → gym-card-title    0.17  same place, renamed  ← the common heal
+ *   gym-card-name → gym-card-county   0.17  same place, sibling field
+ *   gym-card-name → event-card-name   0.50  different feature
+ *   gym-card-name → checkout-submit   1.00  unrelated
+ *
+ * Note that a rename and a sibling field score identically. That is honest:
+ * nothing in the STRING distinguishes them. Separating the two is exactly the
+ * judgement the Tier-1 ranker exists to make, using the failing assertion's
+ * domain arguments — which is why Tier 0 hands over candidates rather than
+ * picking one.
+ *
+ * Returns 0 (identical) .. 1 (nothing in common).
+ */
+export function testIdDistance(a, b) {
+    if (a === b)
+        return 0;
+    const at = a.split(/[-_.:]/).filter(Boolean);
+    const bt = b.split(/[-_.:]/).filter(Boolean);
+    if (at.length === 0 || bt.length === 0)
+        return 1;
+    const length = Math.max(at.length, bt.length);
+    let mismatchWeight = 0;
+    let totalWeight = 0;
+    for (let i = 0; i < length; i++) {
+        // Leading tokens weigh most: position 0 of a 3-token id carries 3/6.
+        const weight = length - i;
+        totalWeight += weight;
+        if (at[i] !== bt[i])
+            mismatchWeight += weight;
+    }
+    return totalWeight === 0 ? 1 : Math.min(1, mismatchWeight / totalWeight);
+}
+//# sourceMappingURL=stability.js.map

package/dist/locator/stability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stability.js","sourceRoot":"","sources":["../../src/locator/stability.ts"],"names":[],"mappings":"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"}