@variance-authority/scenario 0.1.0

package/dist/assessment.js

@@ -0,0 +1,157 @@
+import { BANDS, decidesBand, deriveVariation, explainParting, observableBands, partingOf, } from '@variance-authority/core';
+import { assertScenarioRun } from './execution.js';
+/** Compare two witnessed paths without writing a verdict or mutating either execution. */
+export function assessScenarios(left, right) {
+    assertScenarioRun(left);
+    assertScenarioRun(right);
+    const arrange = compareFrames(left.execution.frames[0], right.execution.frames[0], left, right);
+    const leftActs = actFrames(left);
+    const rightActs = actFrames(right);
+    const aligned = [];
+    const unmatched = [];
+    let prefix = 0;
+    while (prefix < leftActs.length && prefix < rightActs.length) {
+        const leftFrame = leftActs[prefix];
+        const rightFrame = rightActs[prefix];
+        if (!sameAct(leftFrame.act, rightFrame.act))
+            break;
+        const leftEffect = compareFrames(left.execution.frames[prefix], leftFrame, left, left);
+        const rightEffect = compareFrames(right.execution.frames[prefix], rightFrame, right, right);
+        aligned.push({
+            act: leftFrame.act,
+            leftEffect,
+            rightEffect,
+            divergence: compareEffects(leftEffect, rightEffect),
+        });
+        prefix += 1;
+    }
+    for (const frame of leftActs.slice(prefix))
+        unmatched.push({ ...frame.act, side: 'left' });
+    for (const frame of rightActs.slice(prefix))
+        unmatched.push({ ...frame.act, side: 'right' });
+    return {
+        arrange,
+        transitions: aligned,
+        firstDivergence: firstDivergence(aligned, unmatched, left, right),
+        unmatched,
+    };
+}
+function compareFrames(leftFrame, rightFrame, left, right) {
+    if (leftFrame === undefined || rightFrame === undefined) {
+        return { kind: 'unpaired', because: 'one execution has no corresponding frame' };
+    }
+    if (leftFrame.outcome.kind === 'unobserved' || rightFrame.outcome.kind === 'unobserved') {
+        const sides = [
+            ...(leftFrame.outcome.kind === 'unobserved' ? ['left'] : []),
+            ...(rightFrame.outcome.kind === 'unobserved' ? ['right'] : []),
+        ];
+        return { kind: 'unobserved', because: `${sides.join(' and ')} outcome was not observed` };
+    }
+    const before = left.snapshots.get(leftFrame.outcome.snapshot);
+    const after = right.snapshots.get(rightFrame.outcome.snapshot);
+    if (before === undefined || after === undefined) {
+        const missing = [
+            ...(before === undefined ? [leftFrame.outcome.snapshot] : []),
+            ...(after === undefined ? [rightFrame.outcome.snapshot] : []),
+        ];
+        return {
+            kind: 'unobserved',
+            because: `semantic snapshot ${missing.join(' and ')} is unavailable`,
+        };
+    }
+    return { kind: 'measured', variance: varianceOf(before, after) };
+}
+function varianceOf(before, after) {
+    const variation = deriveVariation(before, after);
+    return {
+        digest: variation.digest,
+        identical: variation.identical,
+        bands: variation.bands,
+        components: variation.components.map((component) => component.name),
+        unobserved: variation.unobserved,
+        blindSides: blindSides(before, after),
+        parting: partingBetween(before, after),
+    };
+}
+/**
+ * The edge, read for which input made it.
+ *
+ * Called for both pairs this file measures, because both are the same question
+ * asked of different snapshots: an Arrange comparison asks why two executions
+ * began differently, a transition effect asks what an Act did. Neither is a
+ * regression — there is no baseline in a scenario — so this is `partingOf`'s
+ * home ground rather than a borrowed reading.
+ *
+ * No lifting, unlike the composition graph's use of it: both snapshots are the
+ * same subject at two moments, so they are already rooted at the same node and
+ * `boundarySnapshot` would have nothing to do. That is the one way the time axis
+ * is *easier* than the A/B one.
+ *
+ * A second comparison after `deriveVariation`'s, and deliberately not fused with
+ * it. `compareTrees` returns on matching render hashes, so the edge that moved
+ * nothing — the common one on a long path — pays a digest compare, and the edge
+ * that did move is the one somebody is about to read a sentence about.
+ */
+function partingBetween(before, after) {
+    const parting = partingOf(before, after);
+    return { slice: parting.slice, lines: explainParting(parting) };
+}
+function blindSides(left, right) {
+    const here = observableBands(left.profile);
+    const there = observableBands(right.profile);
+    const blind = [];
+    for (const band of BANDS) {
+        const sides = [];
+        if (!decidesBand(band, here[band]))
+            sides.push('left');
+        if (!decidesBand(band, there[band]))
+            sides.push('right');
+        if (sides.length > 0)
+            blind.push({ band, sides });
+    }
+    return blind;
+}
+function compareEffects(left, right) {
+    if (left.kind === 'unpaired' || right.kind === 'unpaired') {
+        return { kind: 'unpaired', because: 'one transition effect has no corresponding effect' };
+    }
+    if (left.kind === 'unobserved' || right.kind === 'unobserved') {
+        return { kind: 'unobserved', because: 'one transition effect was not measured' };
+    }
+    return {
+        kind: 'measured',
+        identical: left.variance.digest === right.variance.digest,
+        left: left.variance.digest,
+        right: right.variance.digest,
+    };
+}
+function firstDivergence(transitions, unmatched, left, right) {
+    for (const transition of transitions) {
+        if (transition.divergence.kind !== 'measured') {
+            return {
+                kind: 'unresolved',
+                because: `the effect of \`${transition.act.key}\` was not measured on both sides`,
+            };
+        }
+        if (!transition.divergence.identical)
+            return { kind: 'found', act: transition.act };
+    }
+    if (unmatched.length > 0) {
+        return { kind: 'unresolved', because: 'the executions contain unmatched authored acts' };
+    }
+    if (!complete(left) || !complete(right)) {
+        return { kind: 'unresolved', because: 'one execution did not observe its complete path' };
+    }
+    return { kind: 'none' };
+}
+function actFrames(run) {
+    return run.execution.frames.slice(1);
+}
+function complete(run) {
+    return (run.execution.termination === undefined &&
+        run.execution.frames.length === run.definition.acts.length + 1);
+}
+function sameAct(left, right) {
+    return left.key === right.key && left.occurrence === right.occurrence;
+}
+//# sourceMappingURL=assessment.js.map

package/dist/assessment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assessment.js","sourceRoot":"","sources":["../src/assessment.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  BANDS,\n  decidesBand,\n  deriveVariation,\n  explainParting,\n  observableBands,\n  partingOf,\n  type SemanticSnapshot,\n} from '@variance-authority/core';\nimport type {\n  ScenarioActRef,\n  ScenarioAssessment,\n  ScenarioBlindSide,\n  ScenarioComparison,\n  ScenarioEffectDivergence,\n  ScenarioFrame,\n  ScenarioParting,\n  ScenarioRun,\n  ScenarioTransitionAssessment,\n  ScenarioUnmatchedAct,\n  ScenarioVariance,\n} from './contract.js';\nimport { assertScenarioRun } from './execution.js';\n\n/** Compare two witnessed paths without writing a verdict or mutating either execution. */\nexport function assessScenarios(left: ScenarioRun, right: ScenarioRun): ScenarioAssessment {\n  assertScenarioRun(left);\n  assertScenarioRun(right);\n  const arrange = compareFrames(left.execution.frames[0], right.execution.frames[0], left, right);\n  const leftActs = actFrames(left);\n  const rightActs = actFrames(right);\n  const aligned: ScenarioTransitionAssessment[] = [];\n  const unmatched: ScenarioUnmatchedAct[] = [];\n  let prefix = 0;\n\n  while (prefix < leftActs.length && prefix < rightActs.length) {\n    const leftFrame = leftActs[prefix]!;\n    const rightFrame = rightActs[prefix]!;\n    if (!sameAct(leftFrame.act!, rightFrame.act!)) break;\n\n    const leftEffect = compareFrames(\n      left.execution.frames[prefix],\n      leftFrame,\n      left,\n      left,\n    );\n    const rightEffect = compareFrames(\n      right.execution.frames[prefix],\n      rightFrame,\n      right,\n      right,\n    );\n    aligned.push({\n      act: leftFrame.act!,\n      leftEffect,\n      rightEffect,\n      divergence: compareEffects(leftEffect, rightEffect),\n    });\n    prefix += 1;\n  }\n\n  for (const frame of leftActs.slice(prefix)) unmatched.push({ ...frame.act!, side: 'left' });\n  for (const frame of rightActs.slice(prefix)) unmatched.push({ ...frame.act!, side: 'right' });\n\n  return {\n    arrange,\n    transitions: aligned,\n    firstDivergence: firstDivergence(aligned, unmatched, left, right),\n    unmatched,\n  };\n}\n\nfunction compareFrames(\n  leftFrame: ScenarioFrame | undefined,\n  rightFrame: ScenarioFrame | undefined,\n  left: ScenarioRun,\n  right: ScenarioRun,\n): ScenarioComparison {\n  if (leftFrame === undefined || rightFrame === undefined) {\n    return { kind: 'unpaired', because: 'one execution has no corresponding frame' };\n  }\n  if (leftFrame.outcome.kind === 'unobserved' || rightFrame.outcome.kind === 'unobserved') {\n    const sides = [\n      ...(leftFrame.outcome.kind === 'unobserved' ? ['left'] : []),\n      ...(rightFrame.outcome.kind === 'unobserved' ? ['right'] : []),\n    ];\n    return { kind: 'unobserved', because: `${sides.join(' and ')} outcome was not observed` };\n  }\n\n  const before = left.snapshots.get(leftFrame.outcome.snapshot);\n  const after = right.snapshots.get(rightFrame.outcome.snapshot);\n  if (before === undefined || after === undefined) {\n    const missing = [\n      ...(before === undefined ? [leftFrame.outcome.snapshot] : []),\n      ...(after === undefined ? [rightFrame.outcome.snapshot] : []),\n    ];\n    return {\n      kind: 'unobserved',\n      because: `semantic snapshot ${missing.join(' and ')} is unavailable`,\n    };\n  }\n\n  return { kind: 'measured', variance: varianceOf(before, after) };\n}\n\nfunction varianceOf(before: SemanticSnapshot, after: SemanticSnapshot): ScenarioVariance {\n  const variation = deriveVariation(before, after);\n  return {\n    digest: variation.digest,\n    identical: variation.identical,\n    bands: variation.bands,\n    components: variation.components.map((component) => component.name),\n    unobserved: variation.unobserved,\n    blindSides: blindSides(before, after),\n    parting: partingBetween(before, after),\n  };\n}\n\n/**\n * The edge, read for which input made it.\n *\n * Called for both pairs this file measures, because both are the same question\n * asked of different snapshots: an Arrange comparison asks why two executions\n * began differently, a transition effect asks what an Act did. Neither is a\n * regression — there is no baseline in a scenario — so this is `partingOf`'s\n * home ground rather than a borrowed reading.\n *\n * No lifting, unlike the composition graph's use of it: both snapshots are the\n * same subject at two moments, so they are already rooted at the same node and\n * `boundarySnapshot` would have nothing to do. That is the one way the time axis\n * is *easier* than the A/B one.\n *\n * A second comparison after `deriveVariation`'s, and deliberately not fused with\n * it. `compareTrees` returns on matching render hashes, so the edge that moved\n * nothing — the common one on a long path — pays a digest compare, and the edge\n * that did move is the one somebody is about to read a sentence about.\n */\nfunction partingBetween(before: SemanticSnapshot, after: SemanticSnapshot): ScenarioParting {\n  const parting = partingOf(before, after);\n  return { slice: parting.slice, lines: explainParting(parting) };\n}\n\nfunction blindSides(\n  left: SemanticSnapshot,\n  right: SemanticSnapshot,\n): readonly ScenarioBlindSide[] {\n  const here = observableBands(left.profile);\n  const there = observableBands(right.profile);\n  const blind: ScenarioBlindSide[] = [];\n\n  for (const band of BANDS) {\n    const sides: ('left' | 'right')[] = [];\n    if (!decidesBand(band, here[band])) sides.push('left');\n    if (!decidesBand(band, there[band])) sides.push('right');\n    if (sides.length > 0) blind.push({ band, sides });\n  }\n  return blind;\n}\n\nfunction compareEffects(\n  left: ScenarioComparison,\n  right: ScenarioComparison,\n): ScenarioEffectDivergence {\n  if (left.kind === 'unpaired' || right.kind === 'unpaired') {\n    return { kind: 'unpaired', because: 'one transition effect has no corresponding effect' };\n  }\n  if (left.kind === 'unobserved' || right.kind === 'unobserved') {\n    return { kind: 'unobserved', because: 'one transition effect was not measured' };\n  }\n  return {\n    kind: 'measured',\n    identical: left.variance.digest === right.variance.digest,\n    left: left.variance.digest,\n    right: right.variance.digest,\n  };\n}\n\nfunction firstDivergence(\n  transitions: readonly ScenarioTransitionAssessment[],\n  unmatched: readonly ScenarioUnmatchedAct[],\n  left: ScenarioRun,\n  right: ScenarioRun,\n): ScenarioAssessment['firstDivergence'] {\n  for (const transition of transitions) {\n    if (transition.divergence.kind !== 'measured') {\n      return {\n        kind: 'unresolved',\n        because: `the effect of \\`${transition.act.key}\\` was not measured on both sides`,\n      };\n    }\n    if (!transition.divergence.identical) return { kind: 'found', act: transition.act };\n  }\n\n  if (unmatched.length > 0) {\n    return { kind: 'unresolved', because: 'the executions contain unmatched authored acts' };\n  }\n  if (!complete(left) || !complete(right)) {\n    return { kind: 'unresolved', because: 'one execution did not observe its complete path' };\n  }\n  return { kind: 'none' };\n}\n\nfunction actFrames(run: ScenarioRun): readonly ScenarioFrame[] {\n  return run.execution.frames.slice(1);\n}\n\nfunction complete(run: ScenarioRun): boolean {\n  return (\n    run.execution.termination === undefined &&\n    run.execution.frames.length === run.definition.acts.length + 1\n  );\n}\n\nfunction sameAct(left: ScenarioActRef, right: ScenarioActRef): boolean {\n  return left.key === right.key && left.occurrence === right.occurrence;\n}\n"]}

package/dist/contract.d.ts

@@ -0,0 +1,190 @@
+import type { Band, Diagnostic, Digest, PartingSlice, ProfileId, SemanticSnapshot, SubjectRef } from '@variance-authority/core';
+declare const scenarioToken: unique symbol;
+export interface ScenarioDefinitionData {
+    readonly scenarioVersion: 1;
+    readonly id: string;
+    readonly acts: readonly ScenarioAct[];
+}
+/** A definition checked and created by `defineScenario`. */
+export declare class ScenarioDefinition implements ScenarioDefinitionData {
+    private readonly checked;
+    readonly scenarioVersion: 1;
+    readonly id: string;
+    readonly acts: readonly ScenarioAct[];
+    constructor(token: typeof scenarioToken, value: ScenarioDefinitionData);
+}
+export interface ScenarioAct {
+    /** Stable authored identity. A DOM event or resolved target is evidence, not identity. */
+    readonly key: string;
+    readonly kind?: string;
+}
+export interface PreconditionAxisStep {
+    readonly axis: string;
+    readonly from: string;
+    readonly to: string;
+}
+/** The result of the existing subject-parent resolver, carried rather than re-parsed. */
+export type PreconditionLink = {
+    readonly kind: 'resolved';
+    readonly parent: string;
+    readonly how: 'declared' | 'named';
+    readonly step?: PreconditionAxisStep;
+} | {
+    readonly kind: 'unresolved';
+    readonly because: string;
+};
+export interface ScenarioExecutionData {
+    readonly executionVersion: 1;
+    readonly id: string;
+    readonly definition: string;
+    readonly precondition: SubjectRef;
+    readonly preconditionLink?: PreconditionLink;
+    readonly profile: ProfileId;
+    readonly frames: readonly ScenarioFrame[];
+    readonly termination?: readonly Diagnostic[];
+}
+/** An execution whose frame ordering, Act identities, and terminal prefix are checked. */
+export declare class ScenarioExecution implements ScenarioExecutionData {
+    private readonly checked;
+    readonly executionVersion: 1;
+    readonly id: string;
+    readonly definition: string;
+    readonly precondition: SubjectRef;
+    readonly preconditionLink?: PreconditionLink;
+    readonly profile: ProfileId;
+    readonly frames: readonly ScenarioFrame[];
+    readonly termination?: readonly Diagnostic[];
+    constructor(token: typeof scenarioToken, value: ScenarioExecutionData);
+}
+export interface ScenarioFrame {
+    /** Zero is Arrange; later frames are Act outcomes. */
+    readonly at: number;
+    readonly act?: ScenarioActRef;
+    readonly outcome: ScenarioOutcome;
+}
+export interface ScenarioActRef {
+    readonly key: string;
+    readonly occurrence: number;
+}
+export interface ScenarioUnmatchedAct extends ScenarioActRef {
+    readonly side: 'left' | 'right';
+}
+export type ScenarioOutcome = {
+    readonly kind: 'observed';
+    readonly snapshot: Digest;
+    readonly state: Digest;
+} | {
+    readonly kind: 'unobserved';
+    readonly diagnostics: readonly Diagnostic[];
+};
+/** Ephemeral evidence. Dropping this value drops the scenario unless it is archived explicitly. */
+/** Ephemeral evidence checked for frame-to-snapshot and definition-to-execution consistency. */
+export declare class ScenarioRun {
+    private readonly checked;
+    readonly definition: ScenarioDefinition;
+    readonly execution: ScenarioExecution;
+    readonly snapshots: ReadonlyMap<Digest, SemanticSnapshot>;
+    constructor(token: typeof scenarioToken, value: {
+        readonly definition: ScenarioDefinition;
+        readonly execution: ScenarioExecution;
+        readonly snapshots: ReadonlyMap<Digest, SemanticSnapshot>;
+    });
+}
+export interface UnobservedScenarioOutcome {
+    readonly kind: 'unobserved';
+    readonly diagnostics: readonly Diagnostic[];
+}
+export type ScenarioObservation = SemanticSnapshot | UnobservedScenarioOutcome;
+export interface ScenarioBlindSide {
+    readonly band: Band;
+    readonly sides: readonly ('left' | 'right')[];
+}
+/**
+ * Which kind of parting an edge is, and which input made it.
+ *
+ * The same value the composition graph attaches to a divergence, on the axis
+ * where two readings are separated by a moment rather than by a page. That is
+ * the claim worth stating: *snapshot, act, snapshot* and *snapshot, wait,
+ * snapshot* are not two features but one comparison, and the slice is the only
+ * place their answers part. {@link PartingSlice} defines the seven.
+ *
+ * {@link lines} is `explainParting` output — the triage sentence first, then a
+ * line per boundary. A run whose collector read no fiber gets the honest pair
+ * rather than silence: the slice is `unread`, and the line under it says so.
+ */
+export interface ScenarioParting {
+    readonly slice: PartingSlice;
+    readonly lines: readonly string[];
+}
+export interface ScenarioVariance {
+    readonly digest: Digest;
+    readonly identical: boolean;
+    readonly bands: readonly Band[];
+    readonly components: readonly string[];
+    readonly unobserved: readonly Band[];
+    readonly blindSides: readonly ScenarioBlindSide[];
+    /**
+     * Why these two readings differ, not merely that they do.
+     *
+     * `components` names who moved and stops there, which is the same half-finding
+     * a divergence carried before it was given a parting: a reader holding it still
+     * has to open two frames and diff them by eye. This is the other half.
+     *
+     * Always present. A parting is decidable from any two snapshots — `unread` is
+     * a rung, not a gap — so an absent field here would mean the assessment did not
+     * run, and there is no such state.
+     */
+    readonly parting: ScenarioParting;
+}
+export type ScenarioComparison = {
+    readonly kind: 'measured';
+    readonly variance: ScenarioVariance;
+} | {
+    readonly kind: 'unobserved';
+    readonly because: string;
+} | {
+    readonly kind: 'unpaired';
+    readonly because: string;
+};
+export type ScenarioEffectDivergence = {
+    readonly kind: 'measured';
+    readonly identical: boolean;
+    readonly left: Digest;
+    readonly right: Digest;
+} | {
+    readonly kind: 'unobserved';
+    readonly because: string;
+} | {
+    readonly kind: 'unpaired';
+    readonly because: string;
+};
+export interface ScenarioTransitionAssessment {
+    readonly act: ScenarioActRef;
+    readonly leftEffect: ScenarioComparison;
+    readonly rightEffect: ScenarioComparison;
+    readonly divergence: ScenarioEffectDivergence;
+}
+export type ScenarioDivergence = {
+    readonly kind: 'found';
+    readonly act: ScenarioActRef;
+} | {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'unresolved';
+    readonly because: string;
+};
+export interface ScenarioAssessment {
+    readonly arrange: ScenarioComparison;
+    readonly transitions: readonly ScenarioTransitionAssessment[];
+    readonly firstDivergence: ScenarioDivergence;
+    readonly unmatched: readonly ScenarioUnmatchedAct[];
+}
+export declare function checkedDefinition(value: ScenarioDefinitionData): ScenarioDefinition;
+export declare function checkedExecution(value: ScenarioExecutionData): ScenarioExecution;
+export declare function checkedRun(value: {
+    readonly definition: ScenarioDefinition;
+    readonly execution: ScenarioExecution;
+    readonly snapshots: ReadonlyMap<Digest, SemanticSnapshot>;
+}): ScenarioRun;
+export {};
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.js

@@ -0,0 +1,80 @@
+const scenarioToken = Symbol('checked scenario value');
+/** A definition checked and created by `defineScenario`. */
+export class ScenarioDefinition {
+    scenarioVersion = 1;
+    id;
+    acts;
+    constructor(token, value) {
+        if (token !== scenarioToken)
+            throw new Error('ScenarioDefinition is constructor-owned');
+        this.id = value.id;
+        this.acts = value.acts.map((act) => Object.freeze({ ...act }));
+        Object.freeze(this);
+    }
+}
+/** An execution whose frame ordering, Act identities, and terminal prefix are checked. */
+export class ScenarioExecution {
+    executionVersion = 1;
+    id;
+    definition;
+    precondition;
+    preconditionLink;
+    profile;
+    frames;
+    termination;
+    constructor(token, value) {
+        if (token !== scenarioToken)
+            throw new Error('ScenarioExecution is constructor-owned');
+        this.id = value.id;
+        this.definition = value.definition;
+        this.precondition = Object.freeze({ ...value.precondition });
+        if (value.preconditionLink !== undefined)
+            this.preconditionLink = value.preconditionLink;
+        this.profile = value.profile;
+        this.frames = value.frames.map((frame) => freezeFrame(frame));
+        if (value.termination !== undefined)
+            this.termination = freezeDiagnostics(value.termination);
+        Object.freeze(this);
+    }
+}
+/** Ephemeral evidence. Dropping this value drops the scenario unless it is archived explicitly. */
+/** Ephemeral evidence checked for frame-to-snapshot and definition-to-execution consistency. */
+export class ScenarioRun {
+    definition;
+    execution;
+    snapshots;
+    constructor(token, value) {
+        if (token !== scenarioToken)
+            throw new Error('ScenarioRun is constructor-owned');
+        this.definition = value.definition;
+        this.execution = value.execution;
+        this.snapshots = new Map(value.snapshots);
+        Object.freeze(this);
+    }
+}
+export function checkedDefinition(value) {
+    return new ScenarioDefinition(scenarioToken, value);
+}
+export function checkedExecution(value) {
+    return new ScenarioExecution(scenarioToken, value);
+}
+export function checkedRun(value) {
+    return new ScenarioRun(scenarioToken, value);
+}
+function freezeFrame(frame) {
+    const outcome = frame.outcome.kind === 'observed'
+        ? Object.freeze({ ...frame.outcome })
+        : Object.freeze({
+            kind: 'unobserved',
+            diagnostics: freezeDiagnostics(frame.outcome.diagnostics),
+        });
+    return Object.freeze({
+        at: frame.at,
+        ...(frame.act !== undefined ? { act: Object.freeze({ ...frame.act }) } : {}),
+        outcome,
+    });
+}
+function freezeDiagnostics(diagnostics) {
+    return diagnostics.map((diagnostic) => Object.freeze({ ...diagnostic }));
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  Band,\n  Diagnostic,\n  Digest,\n  PartingSlice,\n  ProfileId,\n  SemanticSnapshot,\n  SubjectRef,\n} from '@variance-authority/core';\n\nconst scenarioToken: unique symbol = Symbol('checked scenario value');\n\nexport interface ScenarioDefinitionData {\n  readonly scenarioVersion: 1;\n  readonly id: string;\n  readonly acts: readonly ScenarioAct[];\n}\n\n/** A definition checked and created by `defineScenario`. */\nexport class ScenarioDefinition implements ScenarioDefinitionData {\n  declare private readonly checked: true;\n  readonly scenarioVersion = 1 as const;\n  readonly id: string;\n  readonly acts: readonly ScenarioAct[];\n\n  constructor(token: typeof scenarioToken, value: ScenarioDefinitionData) {\n    if (token !== scenarioToken) throw new Error('ScenarioDefinition is constructor-owned');\n    this.id = value.id;\n    this.acts = value.acts.map((act) => Object.freeze({ ...act }));\n    Object.freeze(this);\n  }\n}\n\nexport interface ScenarioAct {\n  /** Stable authored identity. A DOM event or resolved target is evidence, not identity. */\n  readonly key: string;\n  readonly kind?: string;\n}\n\nexport interface PreconditionAxisStep {\n  readonly axis: string;\n  readonly from: string;\n  readonly to: string;\n}\n\n/** The result of the existing subject-parent resolver, carried rather than re-parsed. */\nexport type PreconditionLink =\n  | {\n      readonly kind: 'resolved';\n      readonly parent: string;\n      readonly how: 'declared' | 'named';\n      readonly step?: PreconditionAxisStep;\n    }\n  | { readonly kind: 'unresolved'; readonly because: string };\n\nexport interface ScenarioExecutionData {\n  readonly executionVersion: 1;\n  readonly id: string;\n  readonly definition: string;\n  readonly precondition: SubjectRef;\n  readonly preconditionLink?: PreconditionLink;\n  readonly profile: ProfileId;\n  readonly frames: readonly ScenarioFrame[];\n  readonly termination?: readonly Diagnostic[];\n}\n\n/** An execution whose frame ordering, Act identities, and terminal prefix are checked. */\nexport class ScenarioExecution implements ScenarioExecutionData {\n  declare private readonly checked: true;\n  readonly executionVersion = 1 as const;\n  readonly id: string;\n  readonly definition: string;\n  readonly precondition: SubjectRef;\n  readonly preconditionLink?: PreconditionLink;\n  readonly profile: ProfileId;\n  readonly frames: readonly ScenarioFrame[];\n  readonly termination?: readonly Diagnostic[];\n\n  constructor(token: typeof scenarioToken, value: ScenarioExecutionData) {\n    if (token !== scenarioToken) throw new Error('ScenarioExecution is constructor-owned');\n    this.id = value.id;\n    this.definition = value.definition;\n    this.precondition = Object.freeze({ ...value.precondition });\n    if (value.preconditionLink !== undefined) this.preconditionLink = value.preconditionLink;\n    this.profile = value.profile;\n    this.frames = value.frames.map((frame) => freezeFrame(frame));\n    if (value.termination !== undefined) this.termination = freezeDiagnostics(value.termination);\n    Object.freeze(this);\n  }\n}\n\nexport interface ScenarioFrame {\n  /** Zero is Arrange; later frames are Act outcomes. */\n  readonly at: number;\n  readonly act?: ScenarioActRef;\n  readonly outcome: ScenarioOutcome;\n}\n\nexport interface ScenarioActRef {\n  readonly key: string;\n  readonly occurrence: number;\n}\n\nexport interface ScenarioUnmatchedAct extends ScenarioActRef {\n  readonly side: 'left' | 'right';\n}\n\nexport type ScenarioOutcome =\n  | { readonly kind: 'observed'; readonly snapshot: Digest; readonly state: Digest }\n  | { readonly kind: 'unobserved'; readonly diagnostics: readonly Diagnostic[] };\n\n/** Ephemeral evidence. Dropping this value drops the scenario unless it is archived explicitly. */\n/** Ephemeral evidence checked for frame-to-snapshot and definition-to-execution consistency. */\nexport class ScenarioRun {\n  declare private readonly checked: true;\n  readonly definition: ScenarioDefinition;\n  readonly execution: ScenarioExecution;\n  readonly snapshots: ReadonlyMap<Digest, SemanticSnapshot>;\n\n  constructor(\n    token: typeof scenarioToken,\n    value: {\n      readonly definition: ScenarioDefinition;\n      readonly execution: ScenarioExecution;\n      readonly snapshots: ReadonlyMap<Digest, SemanticSnapshot>;\n    },\n  ) {\n    if (token !== scenarioToken) throw new Error('ScenarioRun is constructor-owned');\n    this.definition = value.definition;\n    this.execution = value.execution;\n    this.snapshots = new Map(value.snapshots);\n    Object.freeze(this);\n  }\n}\n\nexport interface UnobservedScenarioOutcome {\n  readonly kind: 'unobserved';\n  readonly diagnostics: readonly Diagnostic[];\n}\n\nexport type ScenarioObservation = SemanticSnapshot | UnobservedScenarioOutcome;\n\nexport interface ScenarioBlindSide {\n  readonly band: Band;\n  readonly sides: readonly ('left' | 'right')[];\n}\n\n/**\n * Which kind of parting an edge is, and which input made it.\n *\n * The same value the composition graph attaches to a divergence, on the axis\n * where two readings are separated by a moment rather than by a page. That is\n * the claim worth stating: *snapshot, act, snapshot* and *snapshot, wait,\n * snapshot* are not two features but one comparison, and the slice is the only\n * place their answers part. {@link PartingSlice} defines the seven.\n *\n * {@link lines} is `explainParting` output — the triage sentence first, then a\n * line per boundary. A run whose collector read no fiber gets the honest pair\n * rather than silence: the slice is `unread`, and the line under it says so.\n */\nexport interface ScenarioParting {\n  readonly slice: PartingSlice;\n  readonly lines: readonly string[];\n}\n\nexport interface ScenarioVariance {\n  readonly digest: Digest;\n  readonly identical: boolean;\n  readonly bands: readonly Band[];\n  readonly components: readonly string[];\n  readonly unobserved: readonly Band[];\n  readonly blindSides: readonly ScenarioBlindSide[];\n\n  /**\n   * Why these two readings differ, not merely that they do.\n   *\n   * `components` names who moved and stops there, which is the same half-finding\n   * a divergence carried before it was given a parting: a reader holding it still\n   * has to open two frames and diff them by eye. This is the other half.\n   *\n   * Always present. A parting is decidable from any two snapshots — `unread` is\n   * a rung, not a gap — so an absent field here would mean the assessment did not\n   * run, and there is no such state.\n   */\n  readonly parting: ScenarioParting;\n}\n\nexport type ScenarioComparison =\n  | { readonly kind: 'measured'; readonly variance: ScenarioVariance }\n  | { readonly kind: 'unobserved'; readonly because: string }\n  | { readonly kind: 'unpaired'; readonly because: string };\n\nexport type ScenarioEffectDivergence =\n  | {\n      readonly kind: 'measured';\n      readonly identical: boolean;\n      readonly left: Digest;\n      readonly right: Digest;\n    }\n  | { readonly kind: 'unobserved'; readonly because: string }\n  | { readonly kind: 'unpaired'; readonly because: string };\n\nexport interface ScenarioTransitionAssessment {\n  readonly act: ScenarioActRef;\n  readonly leftEffect: ScenarioComparison;\n  readonly rightEffect: ScenarioComparison;\n  readonly divergence: ScenarioEffectDivergence;\n}\n\nexport type ScenarioDivergence =\n  | { readonly kind: 'found'; readonly act: ScenarioActRef }\n  | { readonly kind: 'none' }\n  | { readonly kind: 'unresolved'; readonly because: string };\n\nexport interface ScenarioAssessment {\n  readonly arrange: ScenarioComparison;\n  readonly transitions: readonly ScenarioTransitionAssessment[];\n  readonly firstDivergence: ScenarioDivergence;\n  readonly unmatched: readonly ScenarioUnmatchedAct[];\n}\n\nexport function checkedDefinition(value: ScenarioDefinitionData): ScenarioDefinition {\n  return new ScenarioDefinition(scenarioToken, value);\n}\n\nexport function checkedExecution(value: ScenarioExecutionData): ScenarioExecution {\n  return new ScenarioExecution(scenarioToken, value);\n}\n\nexport function checkedRun(value: {\n  readonly definition: ScenarioDefinition;\n  readonly execution: ScenarioExecution;\n  readonly snapshots: ReadonlyMap<Digest, SemanticSnapshot>;\n}): ScenarioRun {\n  return new ScenarioRun(scenarioToken, value);\n}\n\nfunction freezeFrame(frame: ScenarioFrame): ScenarioFrame {\n  const outcome =\n    frame.outcome.kind === 'observed'\n      ? Object.freeze({ ...frame.outcome })\n      : Object.freeze({\n          kind: 'unobserved' as const,\n          diagnostics: freezeDiagnostics(frame.outcome.diagnostics),\n        });\n  return Object.freeze({\n    at: frame.at,\n    ...(frame.act !== undefined ? { act: Object.freeze({ ...frame.act }) } : {}),\n    outcome,\n  });\n}\n\nfunction freezeDiagnostics(diagnostics: readonly Diagnostic[]): readonly Diagnostic[] {\n  return diagnostics.map((diagnostic) => Object.freeze({ ...diagnostic }));\n}\n"]}

package/dist/execution.d.ts

@@ -0,0 +1,17 @@
+import { type Diagnostic, type Digest, type SemanticSnapshot } from '@variance-authority/core';
+import type { PreconditionLink, ScenarioAct, ScenarioDefinition, ScenarioObservation, ScenarioRun, UnobservedScenarioOutcome } from './contract.js';
+export interface StartScenarioOptions {
+    readonly id: string;
+    readonly precondition: SemanticSnapshot['subject'];
+    readonly profile: SemanticSnapshot['profile']['id'];
+    readonly preconditionLink?: PreconditionLink;
+}
+export declare function defineScenario(id: string, acts: readonly ScenarioAct[]): ScenarioDefinition;
+export declare function unobserved(...diagnostics: readonly Diagnostic[]): UnobservedScenarioOutcome;
+/** Content address of the complete canonical semantic object, not its render identity. */
+export declare function semanticSnapshotDigest(snapshot: SemanticSnapshot): Digest;
+export declare function startScenario(definition: ScenarioDefinition, options: StartScenarioOptions, arrange: ScenarioObservation): ScenarioRun;
+export declare function recordAct(run: ScenarioRun, key: string, observation: ScenarioObservation): ScenarioRun;
+/** Runtime guard for values crossing an archive or untyped host boundary. */
+export declare function assertScenarioRun(run: ScenarioRun): void;
+//# sourceMappingURL=execution.d.ts.map