@variance-authority/scenario 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @variance-authority/scenario
+
+## 0.1.0
+
+### Patch Changes
+
+- 92f62d4: Name the `startScenario` option a host left out. `precondition` and `profile`
+  are required and were read before they were checked, so omitting `precondition`
+  answered `Cannot read properties of undefined (reading 'id')` from inside the
+  module while `id` — required in the same way, on the same options object —
+  already answered with a sentence. All three now do.
+- Updated dependencies [e8fee66]
+- Updated dependencies [5c34e6d]
+  - @variance-authority/core@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machine Garden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+<p align="center"><img src="./mark.svg" alt="Variance Authority mark" width="72"></p>
+
+# @variance-authority/scenario
+
+> Record runtime scenarios as AAA state machines and assess variance across witnessed transitions.
+
+Use this package when a host can arrange a named UI state, perform meaningful
+acts, and attempt a semantic snapshot after each one. A scenario is AAA
+(Arrange-Act-Assert) as a state machine: Arrange is the initial state
+observation, each Act labels a transition, and assessment compares the
+variance across those transitions.
+
+The host remains responsible for producing `page-loading`, `page-error`,
+`page-one-article`, or any other precondition. If the host already resolved
+this precondition's parent subject, pass that parent's id and whether it was
+declared or named as `preconditionLink`; this package only records that
+evidence and never tries to infer fixtures, mocks, cookies, routes, or flags.
+
+The snapshots come from the host as well. A `SemanticSnapshot` is the normalized
+capture of a rendered subject that `@variance-authority/core` produces from a
+collector's raw capture; nothing here produces one. The optional archive writes
+to a directory you give it.
+
+```bash
+npm install --save-dev @variance-authority/scenario
+```
+
+## Record and assess two paths
+
+Each `SemanticSnapshot` below is a `declare const` stand-in: a real one comes
+from a collector capturing a rendered subject and `@variance-authority/core`
+normalizing it, not from this package.
+
+```ts
+import type { SemanticSnapshot } from '@variance-authority/core';
+import {
+  assessScenarios,
+  defineScenario,
+  recordAct,
+  startScenario,
+} from '@variance-authority/scenario';
+
+declare const oneArticleBefore: SemanticSnapshot;
+declare const oneArticleAfter: SemanticSnapshot;
+declare const twoArticlesBefore: SemanticSnapshot;
+declare const twoArticlesAfter: SemanticSnapshot;
+
+const definition = defineScenario('delete-an-article', [{ key: 'delete-first' }]);
+
+const oneArticle = recordAct(
+  startScenario(
+    definition,
+    {
+      id: 'run-1/one-article',
+      precondition: oneArticleBefore.subject,
+      profile: oneArticleBefore.profile.id,
+    },
+    oneArticleBefore,
+  ),
+  'delete-first',
+  oneArticleAfter,
+);
+
+const twoArticles = recordAct(
+  startScenario(
+    definition,
+    {
+      id: 'run-1/two-articles',
+      precondition: twoArticlesBefore.subject,
+      profile: twoArticlesBefore.profile.id,
+    },
+    twoArticlesBefore,
+  ),
+  'delete-first',
+  twoArticlesAfter,
+);
+
+const assessment = assessScenarios(oneArticle, twoArticles);
+console.log(assessment.arrange, assessment.firstDivergence);
+```
+
+Each `startScenario` or `recordAct` call above appends one frame to the
+execution — Arrange's own outcome, or one Act's — pairing that frame's render
+hash (the exact content digest of what rendered) with its semantic snapshot.
+
+`arrange` compares the initial observations. Each transition then carries the
+left effect, the right effect, and whether the two agree; an effect digest is
+the digest of the classified semantic variance between an Act's before and
+after snapshot, not the frame's own render hash. A shared token edit moves
+every frame's render hash — its exact, absolute state — yet leaves the effect
+digest stable, because the edit is already present in an Act's before and
+after frame alike; changing the handler does move the digest at that Act,
+because that is exactly the comparison the delta is taken from.
+
+Acts align by `(key, occurrence)` along their common ordered prefix. An inserted,
+missing, or repeated Act is reported in `unmatched` with its side; later ordinals are not
+shifted into a plausible pair. A failed observation is created with
+`unobserved(...)`, terminates the reachable prefix, and makes
+`firstDivergence` unresolved rather than clean.
+
+`startScenario` takes:
+
+| option | required state | what it decides |
+| --- | --- | --- |
+| `id` | required, non-empty | the execution identity within its run |
+| `precondition` | required | a `SubjectRef` — the host's stable subject id and kind — in the role of Arrange |
+| `profile` | required | the observation profile every frame must match |
+| `preconditionLink` | absent | the resolved parent and its declared or named evidence; omission means no link was supplied |
+
+## Fold executions into the machine
+
+`foldScenarios` groups frames by render hash and adds witnessed transitions under
+their Act keys. Paths reaching one hash converge on one node. If one state and
+Act reach two destination hashes, both transitions remain and the machine reports
+the divergence. An unobserved Act appears under `unknown`; an edge no execution
+witnessed does not exist in the value and is never called impossible.
+
+This does not replay anything: folding only turns already-recorded frames into
+a graph of witnessed states and edges.
+
+## Retain semantic evidence explicitly
+
+The root entrypoint is ephemeral and performs no I/O. Import
+`createScenarioArchive` from `@variance-authority/scenario/archive` only when the
+semantic evidence must survive the process.
+
+The archive requires an address covering project, run, scenario, execution,
+precondition, profile, and attempt — a caller-assigned label, such as a retry
+count, that the archive never derives from the run itself. Its policy declares
+expiry, access, deletion, and an admission function — a check that can refuse
+to retain a given snapshot — for every semantic snapshot. Equal snapshots are
+stored once by content digest. Expired or missing evidence reads as
+`unobserved`; garbage collection removes expired manifests and semantic objects
+no retained manifest references.
+
+Only canonical `SemanticSnapshot` text and a versioned manifest enter the
+archive — this does not store screenshots or make pass/fail decisions. Semantic
+snapshots can still contain document text, accessible names, attributes, URLs,
+and source evidence, so an admission policy that cannot retain those values
+must refuse the snapshot instead of redacting it after hashing.
+
+`createScenarioArchive` takes `root`, the writable archive directory, and an
+optional `now` clock for deterministic expiry decisions. The system clock is the
+default. Neither option enables archival by itself; only calling `put` writes.

package/dist/archive.d.ts

@@ -0,0 +1,66 @@
+import { type Digest, type SemanticSnapshot } from '@variance-authority/core';
+import type { ScenarioDefinitionData, ScenarioExecutionData, ScenarioRun } from './contract.js';
+export interface ScenarioArchiveAddress {
+    readonly project: string;
+    readonly run: string;
+    readonly scenario: string;
+    readonly execution: string;
+    readonly precondition: string;
+    readonly profile: string;
+    readonly attempt: string;
+}
+export type ScenarioArchiveAdmission = {
+    readonly kind: 'admitted';
+} | {
+    readonly kind: 'refused';
+    readonly because: string;
+};
+export interface ScenarioArchivePolicy {
+    /** ISO-8601 instant after which the evidence is unavailable. */
+    readonly retainUntil: string;
+    /** Human-readable declaration of who may read the retained semantic text. */
+    readonly access: string;
+    /** Human-readable declaration of how retained evidence is deleted. */
+    readonly deletion: string;
+    readonly admit: (snapshot: SemanticSnapshot) => ScenarioArchiveAdmission;
+}
+/** Retention and identity envelope for one admitted, witnessed scenario execution. */
+export interface ScenarioArchiveManifest {
+    readonly archiveVersion: 1;
+    readonly address: ScenarioArchiveAddress;
+    readonly retainUntil: string;
+    readonly access: string;
+    readonly deletion: string;
+    readonly definition: ScenarioDefinitionData;
+    readonly execution: ScenarioExecutionData;
+    readonly snapshots: readonly Digest[];
+}
+export type ArchivedScenario = {
+    readonly kind: 'observed';
+    readonly run: ScenarioRun;
+    readonly manifest: ScenarioArchiveManifest;
+} | {
+    readonly kind: 'unobserved';
+    readonly because: string;
+};
+export interface ScenarioArchiveCollection {
+    readonly manifests: number;
+    readonly snapshots: number;
+}
+export interface ScenarioArchive {
+    put(address: ScenarioArchiveAddress, run: ScenarioRun, policy: ScenarioArchivePolicy): Promise<ScenarioArchiveManifest>;
+    read(address: ScenarioArchiveAddress): Promise<ArchivedScenario>;
+    collectExpired(): Promise<ScenarioArchiveCollection>;
+}
+export interface ScenarioArchiveOptions {
+    readonly root: string;
+    readonly now?: () => Date;
+}
+/**
+ * Open an opt-in, text-only archive. Nothing calls this from the default execution path.
+ *
+ * The archive accepts only `SemanticSnapshot` objects and a scenario manifest; its API has no
+ * raster, document, event payload, baseline, or history-row write.
+ */
+export declare function createScenarioArchive(options: ScenarioArchiveOptions): ScenarioArchive;
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.js

@@ -0,0 +1,222 @@
+import { canonicalize, digestValue, } from '@variance-authority/core';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { checkedDefinition, checkedExecution, checkedRun } from './contract.js';
+import { assertScenarioRun, semanticSnapshotDigest } from './execution.js';
+/**
+ * Open an opt-in, text-only archive. Nothing calls this from the default execution path.
+ *
+ * The archive accepts only `SemanticSnapshot` objects and a scenario manifest; its API has no
+ * raster, document, event payload, baseline, or history-row write.
+ */
+export function createScenarioArchive(options) {
+    const root = options.root;
+    const now = options.now ?? (() => new Date());
+    const objects = join(root, 'objects');
+    const manifests = join(root, 'manifests');
+    return {
+        async put(address, run, policy) {
+            assertScenarioRun(run);
+            validateAddress(address, run);
+            const expires = parseExpiry(policy.retainUntil);
+            if (expires <= now().getTime()) {
+                throw new Error('refusing scenario archive policy whose retention has already expired');
+            }
+            requireDeclaration(policy.access, 'access');
+            requireDeclaration(policy.deletion, 'deletion');
+            const digests = observedDigests(run.execution);
+            for (const digest of digests) {
+                const snapshot = run.snapshots.get(digest);
+                if (snapshot === undefined) {
+                    throw new Error(`refusing scenario archive with unavailable snapshot ${digest}`);
+                }
+                const admission = policy.admit(snapshot);
+                if (admission.kind === 'refused') {
+                    throw new Error(`refusing semantic snapshot ${digest}: ${admission.because}`);
+                }
+                if (semanticSnapshotDigest(snapshot) !== digest) {
+                    throw new Error(`refusing semantic snapshot ${digest}: its content address does not match`);
+                }
+            }
+            await mkdir(objects, { recursive: true });
+            await mkdir(manifests, { recursive: true });
+            for (const digest of digests) {
+                await writeObject(join(objects, `${fileDigest(digest)}.json`), run.snapshots.get(digest));
+            }
+            const manifest = {
+                archiveVersion: 1,
+                address,
+                retainUntil: policy.retainUntil,
+                access: policy.access,
+                deletion: policy.deletion,
+                definition: run.definition,
+                execution: run.execution,
+                snapshots: digests,
+            };
+            await writeAtomic(manifestPath(manifests, address), canonicalize(asCanonical(manifest)));
+            return manifest;
+        },
+        async read(address) {
+            const path = manifestPath(manifests, address);
+            const manifest = await readOptional(path);
+            if (manifest === undefined) {
+                return { kind: 'unobserved', because: 'no archived scenario exists at this address' };
+            }
+            if (parseExpiry(manifest.retainUntil) <= now().getTime()) {
+                return {
+                    kind: 'unobserved',
+                    because: `the archived scenario expired at ${manifest.retainUntil}`,
+                };
+            }
+            const snapshots = new Map();
+            for (const digest of manifest.snapshots) {
+                const snapshot = await readOptional(join(objects, `${fileDigest(digest)}.json`));
+                if (snapshot === undefined) {
+                    return {
+                        kind: 'unobserved',
+                        because: `archived semantic snapshot ${digest} is unavailable`,
+                    };
+                }
+                if (semanticSnapshotDigest(snapshot) !== digest) {
+                    throw new Error(`archived semantic snapshot ${digest} failed its content address`);
+                }
+                snapshots.set(digest, snapshot);
+            }
+            const run = checkedRun({
+                definition: checkedDefinition(manifest.definition),
+                execution: checkedExecution(manifest.execution),
+                snapshots,
+            });
+            assertScenarioRun(run);
+            return {
+                kind: 'observed',
+                manifest,
+                run,
+            };
+        },
+        async collectExpired() {
+            const manifestFiles = await jsonFiles(manifests);
+            const retained = new Set();
+            let removedManifests = 0;
+            for (const file of manifestFiles) {
+                const manifest = await readRequired(join(manifests, file));
+                if (parseExpiry(manifest.retainUntil) <= now().getTime()) {
+                    await rm(join(manifests, file));
+                    removedManifests += 1;
+                }
+                else {
+                    for (const digest of manifest.snapshots)
+                        retained.add(digest);
+                }
+            }
+            let removedSnapshots = 0;
+            for (const file of await jsonFiles(objects)) {
+                const snapshot = await readRequired(join(objects, file));
+                const digest = semanticSnapshotDigest(snapshot);
+                if (!retained.has(digest)) {
+                    await rm(join(objects, file));
+                    removedSnapshots += 1;
+                }
+            }
+            return { manifests: removedManifests, snapshots: removedSnapshots };
+        },
+    };
+}
+function observedDigests(execution) {
+    return [...new Set(execution.frames.flatMap((frame) => frame.outcome.kind === 'observed' ? [frame.outcome.snapshot] : []))].sort(compare);
+}
+function validateAddress(address, run) {
+    const mismatches = [
+        address.scenario === run.definition.id ? undefined : 'scenario',
+        address.execution === run.execution.id ? undefined : 'execution',
+        address.precondition === run.execution.precondition.id ? undefined : 'precondition',
+        address.profile === run.execution.profile ? undefined : 'profile',
+    ].filter((field) => field !== undefined);
+    if (mismatches.length > 0) {
+        throw new Error(`refusing scenario archive address with mismatched ${mismatches.join(', ')}`);
+    }
+    for (const [field, value] of Object.entries(address))
+        requireDeclaration(value, field);
+}
+function parseExpiry(value) {
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        throw new Error(`invalid scenario retention instant: ${value}`);
+    return timestamp;
+}
+function requireDeclaration(value, what) {
+    if (value.trim() === '')
+        throw new Error(`scenario archive ${what} must not be empty`);
+}
+function manifestPath(root, address) {
+    return join(root, `${fileDigest(digestValue(asCanonical(address)))}.json`);
+}
+function fileDigest(digest) {
+    return digest.replace(':', '-');
+}
+function asCanonical(value) {
+    return value;
+}
+async function writeObject(path, snapshot) {
+    const content = canonicalize(asCanonical(snapshot));
+    const existing = await readText(path);
+    if (existing !== undefined) {
+        if (existing !== content)
+            throw new Error(`content-address collision at ${path}`);
+        return;
+    }
+    await writeAtomic(path, content);
+}
+async function writeAtomic(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(temporary, content, { encoding: 'utf8', flag: 'wx' });
+    try {
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+async function readOptional(path) {
+    const text = await readText(path);
+    return text === undefined ? undefined : JSON.parse(text);
+}
+async function readRequired(path) {
+    const found = await readOptional(path);
+    if (found === undefined)
+        throw new Error(`archive entry disappeared while reading ${path}`);
+    return found;
+}
+async function readText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+async function jsonFiles(path) {
+    try {
+        return (await readdir(path)).filter((file) => file.endsWith('.json')).sort(compare);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return [];
+        throw error;
+    }
+}
+function isMissing(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+//# sourceMappingURL=archive.js.map

package/dist/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  canonicalize,\n  digestValue,\n  type CanonicalValue,\n  type Digest,\n  type SemanticSnapshot,\n} from '@variance-authority/core';\nimport { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';\nimport { dirname, join } from 'node:path';\nimport { randomUUID } from 'node:crypto';\nimport type {\n  ScenarioDefinitionData,\n  ScenarioExecutionData,\n  ScenarioRun,\n} from './contract.js';\nimport { checkedDefinition, checkedExecution, checkedRun } from './contract.js';\nimport { assertScenarioRun, semanticSnapshotDigest } from './execution.js';\n\nexport interface ScenarioArchiveAddress {\n  readonly project: string;\n  readonly run: string;\n  readonly scenario: string;\n  readonly execution: string;\n  readonly precondition: string;\n  readonly profile: string;\n  readonly attempt: string;\n}\n\nexport type ScenarioArchiveAdmission =\n  | { readonly kind: 'admitted' }\n  | { readonly kind: 'refused'; readonly because: string };\n\nexport interface ScenarioArchivePolicy {\n  /** ISO-8601 instant after which the evidence is unavailable. */\n  readonly retainUntil: string;\n  /** Human-readable declaration of who may read the retained semantic text. */\n  readonly access: string;\n  /** Human-readable declaration of how retained evidence is deleted. */\n  readonly deletion: string;\n  readonly admit: (snapshot: SemanticSnapshot) => ScenarioArchiveAdmission;\n}\n\n/** Retention and identity envelope for one admitted, witnessed scenario execution. */\nexport interface ScenarioArchiveManifest {\n  readonly archiveVersion: 1;\n  readonly address: ScenarioArchiveAddress;\n  readonly retainUntil: string;\n  readonly access: string;\n  readonly deletion: string;\n  readonly definition: ScenarioDefinitionData;\n  readonly execution: ScenarioExecutionData;\n  readonly snapshots: readonly Digest[];\n}\n\nexport type ArchivedScenario =\n  | { readonly kind: 'observed'; readonly run: ScenarioRun; readonly manifest: ScenarioArchiveManifest }\n  | { readonly kind: 'unobserved'; readonly because: string };\n\nexport interface ScenarioArchiveCollection {\n  readonly manifests: number;\n  readonly snapshots: number;\n}\n\nexport interface ScenarioArchive {\n  put(\n    address: ScenarioArchiveAddress,\n    run: ScenarioRun,\n    policy: ScenarioArchivePolicy,\n  ): Promise<ScenarioArchiveManifest>;\n  read(address: ScenarioArchiveAddress): Promise<ArchivedScenario>;\n  collectExpired(): Promise<ScenarioArchiveCollection>;\n}\n\nexport interface ScenarioArchiveOptions {\n  readonly root: string;\n  readonly now?: () => Date;\n}\n\n/**\n * Open an opt-in, text-only archive. Nothing calls this from the default execution path.\n *\n * The archive accepts only `SemanticSnapshot` objects and a scenario manifest; its API has no\n * raster, document, event payload, baseline, or history-row write.\n */\nexport function createScenarioArchive(options: ScenarioArchiveOptions): ScenarioArchive {\n  const root = options.root;\n  const now = options.now ?? (() => new Date());\n  const objects = join(root, 'objects');\n  const manifests = join(root, 'manifests');\n\n  return {\n    async put(address, run, policy) {\n      assertScenarioRun(run);\n      validateAddress(address, run);\n      const expires = parseExpiry(policy.retainUntil);\n      if (expires <= now().getTime()) {\n        throw new Error('refusing scenario archive policy whose retention has already expired');\n      }\n      requireDeclaration(policy.access, 'access');\n      requireDeclaration(policy.deletion, 'deletion');\n\n      const digests = observedDigests(run.execution);\n      for (const digest of digests) {\n        const snapshot = run.snapshots.get(digest);\n        if (snapshot === undefined) {\n          throw new Error(`refusing scenario archive with unavailable snapshot ${digest}`);\n        }\n        const admission = policy.admit(snapshot);\n        if (admission.kind === 'refused') {\n          throw new Error(`refusing semantic snapshot ${digest}: ${admission.because}`);\n        }\n        if (semanticSnapshotDigest(snapshot) !== digest) {\n          throw new Error(`refusing semantic snapshot ${digest}: its content address does not match`);\n        }\n      }\n\n      await mkdir(objects, { recursive: true });\n      await mkdir(manifests, { recursive: true });\n      for (const digest of digests) {\n        await writeObject(join(objects, `${fileDigest(digest)}.json`), run.snapshots.get(digest)!);\n      }\n\n      const manifest: ScenarioArchiveManifest = {\n        archiveVersion: 1,\n        address,\n        retainUntil: policy.retainUntil,\n        access: policy.access,\n        deletion: policy.deletion,\n        definition: run.definition,\n        execution: run.execution,\n        snapshots: digests,\n      };\n      await writeAtomic(manifestPath(manifests, address), canonicalize(asCanonical(manifest)));\n      return manifest;\n    },\n\n    async read(address) {\n      const path = manifestPath(manifests, address);\n      const manifest = await readOptional<ScenarioArchiveManifest>(path);\n      if (manifest === undefined) {\n        return { kind: 'unobserved', because: 'no archived scenario exists at this address' };\n      }\n      if (parseExpiry(manifest.retainUntil) <= now().getTime()) {\n        return {\n          kind: 'unobserved',\n          because: `the archived scenario expired at ${manifest.retainUntil}`,\n        };\n      }\n\n      const snapshots = new Map<Digest, SemanticSnapshot>();\n      for (const digest of manifest.snapshots) {\n        const snapshot = await readOptional<SemanticSnapshot>(\n          join(objects, `${fileDigest(digest)}.json`),\n        );\n        if (snapshot === undefined) {\n          return {\n            kind: 'unobserved',\n            because: `archived semantic snapshot ${digest} is unavailable`,\n          };\n        }\n        if (semanticSnapshotDigest(snapshot) !== digest) {\n          throw new Error(`archived semantic snapshot ${digest} failed its content address`);\n        }\n        snapshots.set(digest, snapshot);\n      }\n\n      const run = checkedRun({\n        definition: checkedDefinition(manifest.definition),\n        execution: checkedExecution(manifest.execution),\n        snapshots,\n      });\n      assertScenarioRun(run);\n      return {\n        kind: 'observed',\n        manifest,\n        run,\n      };\n    },\n\n    async collectExpired() {\n      const manifestFiles = await jsonFiles(manifests);\n      const retained = new Set<Digest>();\n      let removedManifests = 0;\n\n      for (const file of manifestFiles) {\n        const manifest = await readRequired<ScenarioArchiveManifest>(join(manifests, file));\n        if (parseExpiry(manifest.retainUntil) <= now().getTime()) {\n          await rm(join(manifests, file));\n          removedManifests += 1;\n        } else {\n          for (const digest of manifest.snapshots) retained.add(digest);\n        }\n      }\n\n      let removedSnapshots = 0;\n      for (const file of await jsonFiles(objects)) {\n        const snapshot = await readRequired<SemanticSnapshot>(join(objects, file));\n        const digest = semanticSnapshotDigest(snapshot);\n        if (!retained.has(digest)) {\n          await rm(join(objects, file));\n          removedSnapshots += 1;\n        }\n      }\n      return { manifests: removedManifests, snapshots: removedSnapshots };\n    },\n  };\n}\n\nfunction observedDigests(execution: ScenarioExecutionData): readonly Digest[] {\n  return [...new Set(\n    execution.frames.flatMap((frame) =>\n      frame.outcome.kind === 'observed' ? [frame.outcome.snapshot] : [],\n    ),\n  )].sort(compare);\n}\n\nfunction validateAddress(address: ScenarioArchiveAddress, run: ScenarioRun): void {\n  const mismatches = [\n    address.scenario === run.definition.id ? undefined : 'scenario',\n    address.execution === run.execution.id ? undefined : 'execution',\n    address.precondition === run.execution.precondition.id ? undefined : 'precondition',\n    address.profile === run.execution.profile ? undefined : 'profile',\n  ].filter((field): field is string => field !== undefined);\n  if (mismatches.length > 0) {\n    throw new Error(`refusing scenario archive address with mismatched ${mismatches.join(', ')}`);\n  }\n  for (const [field, value] of Object.entries(address)) requireDeclaration(value, field);\n}\n\nfunction parseExpiry(value: string): number {\n  const timestamp = Date.parse(value);\n  if (!Number.isFinite(timestamp)) throw new Error(`invalid scenario retention instant: ${value}`);\n  return timestamp;\n}\n\nfunction requireDeclaration(value: string, what: string): void {\n  if (value.trim() === '') throw new Error(`scenario archive ${what} must not be empty`);\n}\n\nfunction manifestPath(root: string, address: ScenarioArchiveAddress): string {\n  return join(root, `${fileDigest(digestValue(asCanonical(address)))}.json`);\n}\n\nfunction fileDigest(digest: Digest): string {\n  return digest.replace(':', '-');\n}\n\nfunction asCanonical(value: unknown): CanonicalValue {\n  return value as CanonicalValue;\n}\n\nasync function writeObject(path: string, snapshot: SemanticSnapshot): Promise<void> {\n  const content = canonicalize(asCanonical(snapshot));\n  const existing = await readText(path);\n  if (existing !== undefined) {\n    if (existing !== content) throw new Error(`content-address collision at ${path}`);\n    return;\n  }\n  await writeAtomic(path, content);\n}\n\nasync function writeAtomic(path: string, content: string): Promise<void> {\n  await mkdir(dirname(path), { recursive: true });\n  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;\n  await writeFile(temporary, content, { encoding: 'utf8', flag: 'wx' });\n  try {\n    await rename(temporary, path);\n  } catch (error) {\n    await rm(temporary, { force: true });\n    throw error;\n  }\n}\n\nasync function readOptional<T>(path: string): Promise<T | undefined> {\n  const text = await readText(path);\n  return text === undefined ? undefined : (JSON.parse(text) as T);\n}\n\nasync function readRequired<T>(path: string): Promise<T> {\n  const found = await readOptional<T>(path);\n  if (found === undefined) throw new Error(`archive entry disappeared while reading ${path}`);\n  return found;\n}\n\nasync function readText(path: string): Promise<string | undefined> {\n  try {\n    return await readFile(path, 'utf8');\n  } catch (error) {\n    if (isMissing(error)) return undefined;\n    throw error;\n  }\n}\n\nasync function jsonFiles(path: string): Promise<readonly string[]> {\n  try {\n    return (await readdir(path)).filter((file) => file.endsWith('.json')).sort(compare);\n  } catch (error) {\n    if (isMissing(error)) return [];\n    throw error;\n  }\n}\n\nfunction isMissing(error: unknown): boolean {\n  return (\n    typeof error === 'object' &&\n    error !== null &&\n    'code' in error &&\n    (error as { readonly code?: string }).code === 'ENOENT'\n  );\n}\n\nfunction compare(left: string, right: string): number {\n  return left < right ? -1 : left > right ? 1 : 0;\n}\n"]}

package/dist/assessment.d.ts

@@ -0,0 +1,4 @@
+import type { ScenarioAssessment, ScenarioRun } from './contract.js';
+/** Compare two witnessed paths without writing a verdict or mutating either execution. */
+export declare function assessScenarios(left: ScenarioRun, right: ScenarioRun): ScenarioAssessment;
+//# sourceMappingURL=assessment.d.ts.map