my-frontend-observer 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # Changelog
 
+## 0.5.0 - 2026-08-13
+
+Executable Frontend Contracts and Explicit Change Scope.
+
+- Two related contract classes: a `PersistentBaselineContract` (previously
+  approved frontend behavior that stays active across future changes unless
+  explicitly superseded, with append-based supersession history) and a
+  `PerChangeContract` (the allowed scope of one requested change).
+- Four authored change-scope categories - `requested`, `expected-dependent`
+  (`required` or `permitted`), `protected`, `preserved` - plus a fifth,
+  strictly derived-only classification, `unexpected`, for a meaningful
+  rendered difference no active clause accounts for. `unexpected` can never
+  be authored as a permission.
+- A closed, bounded vocabulary of 15 contract primitives (visibility,
+  clipping, width bounds, non-overlap, relative width, vertical sequence,
+  geometric fit, document-width-vs-viewport, scroll ownership, initial-
+  viewport position, relationship-unchanged, and property-unchanged/
+  increases/decreases) and three contract tolerances (`exact`,
+  `absolute-px`, `percent`) - independent of `compare`'s geometry tolerance,
+  which only suppresses insignificant noise and is never contract
+  authorization.
+- Explicit, never-inferred baseline and per-change clause supersession; two
+  clauses that structurally contradict each other without explicit
+  supersession produce a `conflict` result rather than a silent preference.
+- One canonical evaluation engine (`evaluateFrontendContract`) that owns
+  requested/expected-dependent/protected/preserved evaluation, unexpected-
+  change derivation, and the overall `PASS`/`FAIL` verdict - reusing existing
+  v0.4 observation/comparison evidence directly, never re-launching a
+  browser, re-resolving a target, or reimplementing relationship/clipping
+  derivation.
+- Actionable per-clause results (`pass`/`fail`/`unavailable` with a required
+  reason/`conflict` with at least two conflicting clause identities) - never
+  an opaque score.
+- Atomic, independently-versioned persistence for baseline contracts,
+  per-change contracts, and evaluation results, with no destructive artifact
+  overwrite, no copied screenshots, and full source observation/comparison/
+  contract immutability.
+- Three new public commands: `approve-baseline` (the only baseline-approval
+  act - explicit only, never inferred from `compare` or a `PASS`
+  evaluation), `save-change-contract` (persistence only), and
+  `evaluate-contract` (runs the canonical evaluator against already-
+  persisted evidence and persists exactly one evaluation artifact).
+  `evaluate-contract --enforce` makes an already-persisted `FAIL` verdict
+  produce a nonzero process exit status without changing the verdict, its
+  identity, or its persisted content - a `FAIL` without `--enforce` still
+  exits `0`.
+- Proven against real Chromium observations, not hand-constructed
+  artifacts: a fully successful contract change, and the "milestone
+  signature" case - a locally successful requested change coexisting with a
+  genuine protected-property regression and a genuine preserved-invariant
+  regression - producing overall `FAIL`.
+- Frontend contract schema `1.0.0` and evaluation artifact schema `1.0.0`,
+  each its own independent schema family; observation schema remains
+  `1.2.0` and comparison schema remains `1.0.0`.
+- Cross-platform packed-candidate validation: one hash-verified npm
+  candidate tarball proven on Windows, Linux, and macOS, covering the
+  installed candidate's `approve-baseline`, `save-change-contract`, and
+  `evaluate-contract` commands alongside every pre-existing v0.1-v0.4
+  packed observation/comparison behavior.
+
+## 0.4.0 - 2026-08-12
+
+Layout Relationships, Dependency Evidence, and Before/After Comparison.
+
+- New comparison artifact kind `my-frontend-observer/comparison`, schema
+  `1.0.0` - independent of and never reused for the observation schema.
+- Canonical layout-relationship derivation from a single observation:
+  horizontal order (`left-of`/`right-of`/`horizontally-overlapping`),
+  vertical order (`above`/`below`/`vertically-overlapping`), area overlap,
+  relative width, geometric fit (kept explicitly distinct from DOM
+  containment), vertical sequencing (`follows-vertically`), and document-
+  width fit/exceeds-viewport - bounded to configured targets, with explicit
+  evidence-path provenance and honest unresolved-target handling.
+- Comparability analysis, evaluated before any rendered difference:
+  `comparable` / `comparable-with-warnings` / `incomparable`, with
+  structured reasons (hard mismatches on page URL, viewport, browser
+  engine, or scroll-scenario configuration; warnings for producer/browser
+  version and target-configuration differences; theme/authenticated-state/
+  application-state recorded as unassessed, never silently equal).
+- Before/after target and page differences: appeared/disappeared (never
+  confused with a target added/removed from configuration), moved, resized,
+  visibility changes, clipping changes (reusing one canonical clipping
+  derivation), actual horizontal/vertical dimensional-overflow changes, DOM
+  containment changes, page-size changes, and scroll-owner changes - each a
+  structured record with before/after values, deltas where meaningful, and
+  supporting evidence references.
+- Relationship-change detection between two observations, matched by
+  relationship family and subject/related target (never array position),
+  including a `relative-position-changed` distinction from plain absolute
+  target movement.
+- Explicit, non-causal expected-dependency evidence: a caller may declare an
+  expected relationship between two targets' `x`/`y`/`width`/`height`
+  properties and `increase`/`decrease`/`change`/`unchanged` directions; each
+  declaration evaluates independently to `consistent` / `not-observed` /
+  `contradictory-to-declaration` / `unavailable`. The observer never infers
+  a dependency from observed co-change and never produces a causal claim.
+- Deterministic, direction-sensitive comparison identity
+  (`comparisonRequestId`) plus a fresh `comparisonId` per execution;
+  operational filesystem paths never affect identity and are never written
+  into the persisted manifest.
+- Atomic comparison-artifact persistence: `<outputLocation>/<comparisonId>/
+  manifest.json` only - no screenshot bytes are copied; the manifest
+  retains logical references to the source observations' own
+  `screenshot.path`. Source observations are never modified.
+- New public `compare` command: `my-frontend-observer compare --before
+  <observation-artifact-root> --after <observation-artifact-root> --output
+  <directory> [--config-file <json-file>]`. Reads two already-persisted
+  observation artifacts and never launches a browser. `comparable`,
+  `comparable-with-warnings`, and `incomparable` all persist successfully
+  and exit `0`; only invalid syntax, an unreadable/invalid source artifact,
+  invalid configuration, or a failed write exits nonzero.
+
 ## 0.3.0 - 2026-08-12
 
 Runtime Scrolling, Overflow, and Visibility Behavior.

package/README.md

@@ -6,12 +6,21 @@ in [docs/PROJECT_DESCRIPTION.md](docs/PROJECT_DESCRIPTION.md).
 
 ## Current status
 
-`v0.3.0`, Runtime Scrolling, Overflow, and Visibility Behavior, is the
+`v0.5.0`, Executable Frontend Contracts and Explicit Change Scope, is the
 current published release: `my-frontend-observer observe` launches a real,
-sandboxed Chromium browser, enforces a loopback-only safety policy,
-captures a viewport screenshot plus bounded page/target evidence, and
-persists it as one portable `manifest.json` + `screenshot.png` artifact
-(observation schema `1.2.0`).
+sandboxed Chromium browser, enforces a loopback-only safety policy, captures
+a viewport screenshot plus bounded page/target evidence, and persists it as
+one portable `manifest.json` + `screenshot.png` artifact (observation schema
+`1.2.0`). `my-frontend-observer compare` reads two already-persisted
+observation artifacts and derives before/after evidence purely from their
+existing content, persisting a comparison artifact (comparison schema
+`1.0.0`). `my-frontend-observer approve-baseline`, `save-change-contract`,
+and `evaluate-contract` turn that evidence into an executable frontend
+contract: an explicitly approved baseline plus a per-change contract
+(requested/expected-dependent/protected/preserved scope) are evaluated
+together into one `PASS`/`FAIL` verdict, so a locally successful requested
+change can never silently hide a protected-region regression (frontend
+contract schema `1.0.0`; evaluation artifact schema `1.0.0`).
 
 Install:
 
@@ -67,6 +76,49 @@ in
 [docs/COMMANDS.md](docs/COMMANDS.md#scroll-scenario---scroll-scenario-file)
 for the exact JSON format and flag reference.
 
+### Comparison
+
+`my-frontend-observer compare` reads two already-persisted observation
+artifacts and derives before/after evidence purely from their existing
+content - it never launches a browser:
+
+```powershell
+my-frontend-observer compare `
+  --before observations/<before-observation-id> `
+  --after observations/<after-observation-id> `
+  --output comparisons
+```
+
+(From a source checkout, use `node dist/cli.js compare ...` instead.)
+
+This prints a concise result (`Comparison:`/`State:`/`Artifact:`/
+`Differences:`/`Relationship changes:`/`Diagnostics:`) and exits `0` -
+including when the two observations turn out to be `incomparable`, which is
+itself a successful comparison outcome. See
+[docs/COMMANDS.md](docs/COMMANDS.md) for the full flag reference.
+
+### Frontend contracts
+
+`v0.5.0` ships a text/config-driven frontend contract and evaluation
+workflow: approve a baseline against an observation, save a per-change
+contract, then evaluate a candidate change against them plus existing
+before/after/comparison evidence, deriving one `PASS`/`FAIL` verdict:
+
+```powershell
+my-frontend-observer approve-baseline --observation observations/<id> --contract-file baseline.json --output baselines
+my-frontend-observer save-change-contract --contract-file change.json --output contracts
+my-frontend-observer evaluate-contract --before observations/<before-id> --after observations/<after-id> --comparison comparisons/<id> --baseline baselines/<baseline-id> --change contracts/<contract-id> --output evaluations [--enforce]
+```
+
+(From a source checkout, use `node dist/cli.js approve-baseline ...` etc.
+instead.)
+
+`evaluate-contract` never launches a browser or recomputes comparison
+evidence. `--enforce` only changes the process exit status for a `FAIL`
+verdict; the verdict itself, and its persisted evidence, are unaffected. See
+[docs/COMMANDS.md](docs/COMMANDS.md) for the full flag reference and
+[docs/WORKFLOWS.md](docs/WORKFLOWS.md) for the end-to-end flow.
+
 Validation:
 
 ```powershell
@@ -84,8 +136,8 @@ Planning authorities:
   intent and responsibility boundaries.
 - [Project Milestones](docs/PROJECT_MILESTONES.md): complete ordered capability
   design and cross-milestone rules.
-- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1, v0.2, and
-  v0.3 are released, v0.4 is next.
+- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1-v0.5 are
+  released, v0.6 is next.
 - [Current State](docs/CURRENT_STATE.md): retained scaffold and release state.
 
 No sibling ecosystem repository is a runtime dependency of the retained

package/dist/application/comparisonService.d.ts

@@ -0,0 +1,56 @@
+import type { ObservationArtifact } from '../domain/schema.js';
+import type { ComparabilityState, ComparisonConfig } from '../domain/comparison.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { WriteComparisonArtifactOptions } from '../artifacts/comparisonArtifactWriter.js';
+export type { PersistedComparisonResult } from '../artifacts/comparisonArtifactWriter.js';
+/** Default comparison output location, mirroring `request.ts`'s `DEFAULT_OUTPUT_LOCATION` for observations - distinct directories so comparisons never collide with source observations. */
+export declare const DEFAULT_COMPARISON_OUTPUT_LOCATION = "comparisons";
+export interface CompareAndPersistOptions {
+    config?: Partial<ComparisonConfig>;
+    /** Portable, relative output location (validated the same way as an observation's `outputLocation`). Defaults to `DEFAULT_COMPARISON_OUTPUT_LOCATION`. */
+    outputLocation?: string;
+    cwd?: WriteComparisonArtifactOptions['cwd'];
+}
+/**
+ * Observer-owned summary of one full compare-and-persist attempt, with just
+ * enough information for a presentation layer (a future Batch 4 CLI) to
+ * report a result without seeing a raw filesystem exception or persistence
+ * implementation detail.
+ */
+export type ApplicationComparisonResult = {
+    ok: true;
+    comparisonId: string;
+    comparisonRequestId: string;
+    comparability: ComparabilityState;
+    artifactRoot: string;
+    manifestPath: string;
+    differenceCount: number;
+    relationshipChangeCount: number;
+    diagnosticsCount: number;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * The one canonical application-level comparison use case: takes two
+ * already-validated/in-memory `ObservationArtifact`s, runs the existing pure
+ * `compareObservations` exactly once, and - only for a structurally valid
+ * result - persists it exactly once through the existing comparison
+ * writer. Never launches Chromium, never re-resolves targets, never mutates
+ * either source observation.
+ */
+export declare function compareAndPersist(before: ObservationArtifact, after: ObservationArtifact, options?: CompareAndPersistOptions): Promise<ApplicationComparisonResult>;
+/**
+ * The canonical Batch 4 CLI-facing orchestration: reads two already-persisted
+ * observation artifacts by their root directory (each expected to contain
+ * `manifest.json`, mirroring `writeObservationArtifact`'s own layout) through
+ * the existing `readObservationArtifact` reader, then delegates to
+ * `compareAndPersist` exactly once. A thin wrapper only - artifact reading
+ * stays owned by `artifacts/artifactReader.ts`, comparison stays owned by
+ * `domain/comparisonEngine.ts`, and persistence stays owned by
+ * `artifacts/comparisonArtifactWriter.ts`. Kept in `application/` (not
+ * `artifacts/`) so `src/cli.ts` can depend on it without importing the
+ * artifacts layer directly - see `tests/unit/cli.test.ts`'s import-boundary
+ * assertion. Never launches a browser, never re-resolves targets.
+ */
+export declare function compareAndPersistFromArtifactRoots(beforeRoot: string, afterRoot: string, options?: CompareAndPersistOptions): Promise<ApplicationComparisonResult>;

package/dist/application/comparisonService.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import { compareObservations } from '../domain/comparisonEngine.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+import { normalizeOutputLocation } from '../request/paths.js';
+import { writeComparisonArtifact } from '../artifacts/comparisonArtifactWriter.js';
+import { readObservationArtifact } from '../artifacts/artifactReader.js';
+import { MANIFEST_FILENAME as OBSERVATION_MANIFEST_FILENAME } from '../artifacts/artifactWriter.js';
+/** Default comparison output location, mirroring `request.ts`'s `DEFAULT_OUTPUT_LOCATION` for observations - distinct directories so comparisons never collide with source observations. */
+export const DEFAULT_COMPARISON_OUTPUT_LOCATION = 'comparisons';
+/**
+ * The one canonical application-level comparison use case: takes two
+ * already-validated/in-memory `ObservationArtifact`s, runs the existing pure
+ * `compareObservations` exactly once, and - only for a structurally valid
+ * result - persists it exactly once through the existing comparison
+ * writer. Never launches Chromium, never re-resolves targets, never mutates
+ * either source observation.
+ */
+export async function compareAndPersist(before, after, options = {}) {
+    const result = compareObservations(before, after, options.config ?? {});
+    if (!result.ok) {
+        return {
+            ok: false,
+            diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: result.reason }],
+        };
+    }
+    const rawOutputLocation = options.outputLocation ?? DEFAULT_COMPARISON_OUTPUT_LOCATION;
+    const normalized = normalizeOutputLocation(rawOutputLocation);
+    if (!normalized.ok) {
+        return { ok: false, diagnostics: [normalized.diagnostic] };
+    }
+    const persisted = await writeComparisonArtifact(result.artifact, normalized.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok) {
+        return { ok: false, diagnostics: persisted.diagnostics };
+    }
+    return {
+        ok: true,
+        comparisonId: result.artifact.comparisonId,
+        comparisonRequestId: result.artifact.comparisonRequestId,
+        comparability: result.artifact.comparability.state,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        differenceCount: result.artifact.differences.length,
+        relationshipChangeCount: result.artifact.relationshipChanges.length,
+        diagnosticsCount: result.artifact.diagnostics.length,
+    };
+}
+/**
+ * The canonical Batch 4 CLI-facing orchestration: reads two already-persisted
+ * observation artifacts by their root directory (each expected to contain
+ * `manifest.json`, mirroring `writeObservationArtifact`'s own layout) through
+ * the existing `readObservationArtifact` reader, then delegates to
+ * `compareAndPersist` exactly once. A thin wrapper only - artifact reading
+ * stays owned by `artifacts/artifactReader.ts`, comparison stays owned by
+ * `domain/comparisonEngine.ts`, and persistence stays owned by
+ * `artifacts/comparisonArtifactWriter.ts`. Kept in `application/` (not
+ * `artifacts/`) so `src/cli.ts` can depend on it without importing the
+ * artifacts layer directly - see `tests/unit/cli.test.ts`'s import-boundary
+ * assertion. Never launches a browser, never re-resolves targets.
+ */
+export async function compareAndPersistFromArtifactRoots(beforeRoot, afterRoot, options = {}) {
+    const beforeRead = await readObservationArtifact(path.join(beforeRoot, OBSERVATION_MANIFEST_FILENAME));
+    if (!beforeRead.ok) {
+        return {
+            ok: false,
+            diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: `--before observation artifact: ${beforeRead.reason}` }],
+        };
+    }
+    const afterRead = await readObservationArtifact(path.join(afterRoot, OBSERVATION_MANIFEST_FILENAME));
+    if (!afterRead.ok) {
+        return {
+            ok: false,
+            diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: `--after observation artifact: ${afterRead.reason}` }],
+        };
+    }
+    return compareAndPersist(beforeRead.artifact, afterRead.artifact, options);
+}
+//# sourceMappingURL=comparisonService.js.map

package/dist/application/comparisonService.js.map

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

package/dist/application/frontendContractEvaluationService.d.ts

@@ -0,0 +1,49 @@
+import type { FrontendContractEvaluationInput } from '../domain/frontendContractEvaluation.js';
+import type { OverallVerdict } from '../domain/frontendContracts.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { WriteFrontendContractEvaluationArtifactOptions } from '../artifacts/frontendContractEvaluationArtifactWriter.js';
+export type { PersistedFrontendContractEvaluationResult } from '../artifacts/frontendContractEvaluationArtifactWriter.js';
+/** Distinct from `DEFAULT_COMPARISON_OUTPUT_LOCATION`/observation `outputLocation` so evaluations never collide with source evidence. */
+export declare const DEFAULT_EVALUATION_OUTPUT_LOCATION = "evaluations";
+export interface EvaluateAndPersistOptions {
+    outputLocation?: string;
+    cwd?: WriteFrontendContractEvaluationArtifactOptions['cwd'];
+}
+export type ApplicationFrontendContractEvaluationResult = {
+    ok: true;
+    evaluationId: string;
+    evaluationRequestId: string;
+    overallVerdict: OverallVerdict;
+    artifactRoot: string;
+    manifestPath: string;
+    clauseResultCount: number;
+    unexpectedChangeCount: number;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * The one canonical application-level frontend-contract evaluation use case:
+ * takes already-validated/in-memory evidence, runs the existing pure
+ * `evaluateFrontendContract` exactly once, and - only for a structurally
+ * constructible result (`ok: true`, whether the verdict itself is `PASS` or
+ * `FAIL`) - persists it exactly once through the existing evaluation writer.
+ * Never re-evaluates, never launches Chromium, never mutates any input
+ * artifact. A `{ ok: false }` evaluator result (evidence could not even be
+ * constructed into an evaluation) is never persisted as a fabricated
+ * successful artifact - that is an application-level `invalid-request`
+ * diagnostic, distinct from a legitimate `FAIL` verdict.
+ */
+export declare function evaluateAndPersist(input: FrontendContractEvaluationInput, options?: EvaluateAndPersistOptions): Promise<ApplicationFrontendContractEvaluationResult>;
+/**
+ * The canonical future-CLI-facing orchestration: reads before/after
+ * observations (through the existing `readObservationArtifact` reader -
+ * never a second observation reader), the comparison (through the new
+ * `readComparisonArtifact`), and the baseline/per-change contracts (through
+ * `frontendContractArtifactReader.ts`) by their root directories, then
+ * delegates to `evaluateAndPersist` exactly once. A thin wrapper only -
+ * reading stays owned by the artifacts layer, evaluation stays owned by
+ * `domain/frontendContractEvaluation.ts`, persistence stays owned by
+ * `artifacts/frontendContractEvaluationArtifactWriter.ts`.
+ */
+export declare function evaluateAndPersistFromArtifactRoots(beforeRoot: string, afterRoot: string, comparisonRoot: string, baselineRoot: string, changeRoot: string, options?: EvaluateAndPersistOptions): Promise<ApplicationFrontendContractEvaluationResult>;

package/dist/application/frontendContractEvaluationService.js

@@ -0,0 +1,112 @@
+import path from 'node:path';
+import { getProducerInfo } from '../domain/schema.js';
+import { evaluateFrontendContract } from '../domain/frontendContractEvaluation.js';
+import { buildFrontendContractEvaluationArtifact } from '../domain/frontendContractEvaluationArtifact.js';
+import { buildFrontendContractEvaluationRequestIdentity, buildFrontendContractInstanceIdentity } from '../domain/frontendContractIdentity.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+import { normalizeOutputLocation } from '../request/paths.js';
+import { writeFrontendContractEvaluationArtifact } from '../artifacts/frontendContractEvaluationArtifactWriter.js';
+import { readObservationArtifact } from '../artifacts/artifactReader.js';
+import { MANIFEST_FILENAME as OBSERVATION_MANIFEST_FILENAME } from '../artifacts/artifactWriter.js';
+import { readComparisonArtifact } from '../artifacts/comparisonArtifactReader.js';
+import { COMPARISON_MANIFEST_FILENAME } from '../artifacts/comparisonArtifactWriter.js';
+import { readPersistentBaselineContract, readPerChangeContract } from '../artifacts/frontendContractArtifactReader.js';
+import { FRONTEND_CONTRACT_MANIFEST_FILENAME } from '../artifacts/frontendContractArtifactWriter.js';
+/** Distinct from `DEFAULT_COMPARISON_OUTPUT_LOCATION`/observation `outputLocation` so evaluations never collide with source evidence. */
+export const DEFAULT_EVALUATION_OUTPUT_LOCATION = 'evaluations';
+function invalidRequest(message) {
+    return { ok: false, diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message }] };
+}
+/**
+ * The one canonical application-level frontend-contract evaluation use case:
+ * takes already-validated/in-memory evidence, runs the existing pure
+ * `evaluateFrontendContract` exactly once, and - only for a structurally
+ * constructible result (`ok: true`, whether the verdict itself is `PASS` or
+ * `FAIL`) - persists it exactly once through the existing evaluation writer.
+ * Never re-evaluates, never launches Chromium, never mutates any input
+ * artifact. A `{ ok: false }` evaluator result (evidence could not even be
+ * constructed into an evaluation) is never persisted as a fabricated
+ * successful artifact - that is an application-level `invalid-request`
+ * diagnostic, distinct from a legitimate `FAIL` verdict.
+ */
+export async function evaluateAndPersist(input, options = {}) {
+    const result = evaluateFrontendContract(input);
+    if (!result.ok)
+        return invalidRequest(result.reason);
+    const rawOutputLocation = options.outputLocation ?? DEFAULT_EVALUATION_OUTPUT_LOCATION;
+    const normalized = normalizeOutputLocation(rawOutputLocation);
+    if (!normalized.ok)
+        return { ok: false, diagnostics: [normalized.diagnostic] };
+    const evaluationRequestId = buildFrontendContractEvaluationRequestIdentity(input.baseline.baselineId, input.change.contractId, input.comparison.before.observationId, input.comparison.after.observationId, input.comparison.comparisonRequestId);
+    const evaluationId = buildFrontendContractInstanceIdentity(evaluationRequestId);
+    const artifact = buildFrontendContractEvaluationArtifact({
+        evaluationId,
+        evaluationRequestId,
+        producerVersion: getProducerInfo().version,
+        evaluatedAt: new Date().toISOString(),
+        baselineId: input.baseline.baselineId,
+        contractId: input.change.contractId,
+        before: {
+            observationId: input.comparison.before.observationId,
+            requestId: input.comparison.before.requestId,
+            producer: input.comparison.before.producer,
+            observationSchemaVersion: input.comparison.before.observationSchemaVersion,
+        },
+        after: {
+            observationId: input.comparison.after.observationId,
+            requestId: input.comparison.after.requestId,
+            producer: input.comparison.after.producer,
+            observationSchemaVersion: input.comparison.after.observationSchemaVersion,
+        },
+        comparisonId: input.comparison.comparisonId,
+        comparisonRequestId: input.comparison.comparisonRequestId,
+        overallVerdict: result.evaluation.overallVerdict,
+        activeBaselineClauseIds: result.evaluation.activeBaselineClauseIds,
+        supersededBaselineClauseIds: result.evaluation.supersededBaselineClauseIds,
+        clauseResults: result.evaluation.clauseResults,
+        unexpectedChanges: result.evaluation.unexpectedChanges,
+    });
+    const persisted = await writeFrontendContractEvaluationArtifact(artifact, normalized.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok)
+        return { ok: false, diagnostics: persisted.diagnostics };
+    return {
+        ok: true,
+        evaluationId: artifact.evaluationId,
+        evaluationRequestId: artifact.evaluationRequestId,
+        overallVerdict: artifact.overallVerdict,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        clauseResultCount: artifact.clauseResults.length,
+        unexpectedChangeCount: artifact.unexpectedChanges.length,
+    };
+}
+/**
+ * The canonical future-CLI-facing orchestration: reads before/after
+ * observations (through the existing `readObservationArtifact` reader -
+ * never a second observation reader), the comparison (through the new
+ * `readComparisonArtifact`), and the baseline/per-change contracts (through
+ * `frontendContractArtifactReader.ts`) by their root directories, then
+ * delegates to `evaluateAndPersist` exactly once. A thin wrapper only -
+ * reading stays owned by the artifacts layer, evaluation stays owned by
+ * `domain/frontendContractEvaluation.ts`, persistence stays owned by
+ * `artifacts/frontendContractEvaluationArtifactWriter.ts`.
+ */
+export async function evaluateAndPersistFromArtifactRoots(beforeRoot, afterRoot, comparisonRoot, baselineRoot, changeRoot, options = {}) {
+    const beforeRead = await readObservationArtifact(path.join(beforeRoot, OBSERVATION_MANIFEST_FILENAME));
+    if (!beforeRead.ok)
+        return invalidRequest(`before observation artifact: ${beforeRead.reason}`);
+    const afterRead = await readObservationArtifact(path.join(afterRoot, OBSERVATION_MANIFEST_FILENAME));
+    if (!afterRead.ok)
+        return invalidRequest(`after observation artifact: ${afterRead.reason}`);
+    const comparisonRead = await readComparisonArtifact(path.join(comparisonRoot, COMPARISON_MANIFEST_FILENAME));
+    if (!comparisonRead.ok)
+        return invalidRequest(`comparison artifact: ${comparisonRead.reason}`);
+    const baselineRead = await readPersistentBaselineContract(path.join(baselineRoot, FRONTEND_CONTRACT_MANIFEST_FILENAME));
+    if (!baselineRead.ok)
+        return invalidRequest(`baseline contract artifact: ${baselineRead.reason}`);
+    const changeRead = await readPerChangeContract(path.join(changeRoot, FRONTEND_CONTRACT_MANIFEST_FILENAME));
+    if (!changeRead.ok)
+        return invalidRequest(`per-change contract artifact: ${changeRead.reason}`);
+    return evaluateAndPersist({ before: beforeRead.artifact, after: afterRead.artifact, comparison: comparisonRead.artifact, baseline: baselineRead.contract, change: changeRead.contract }, options);
+}
+//# sourceMappingURL=frontendContractEvaluationService.js.map

package/dist/application/frontendContractEvaluationService.js.map

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

package/dist/application/frontendContractPersistenceService.d.ts

@@ -0,0 +1,56 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { WriteFrontendContractArtifactOptions } from '../artifacts/frontendContractArtifactWriter.js';
+export interface PersistFrontendContractOptions {
+    outputLocation: string;
+    cwd?: WriteFrontendContractArtifactOptions['cwd'];
+}
+export type ApplicationApproveBaselineResult = {
+    ok: true;
+    baselineId: string;
+    supersedesBaselineId?: string;
+    artifactRoot: string;
+    manifestPath: string;
+    clauseCount: number;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+export type ApplicationPersistChangeContractResult = {
+    ok: true;
+    contractId: string;
+    artifactRoot: string;
+    manifestPath: string;
+    clauseCount: number;
+    supersedesBaselineClauseCount: number;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * The one canonical application-level baseline-approval use case: `approve-baseline`
+ * is the *only* place a baseline is ever approved (see governing scope) - this
+ * function is never called from `observe`/`compare`/`evaluate-contract`, and a
+ * `PASS` evaluation never triggers it. Validates the raw (still-`unknown`,
+ * freshly-parsed-JSON) baseline through the existing frozen
+ * `isValidPersistentBaselineContract` structural gate (never a second
+ * validator), reads the supplied observation through the existing
+ * `readObservationArtifact` reader, verifies the baseline's frozen
+ * `sourceObservation` reference actually corresponds to that observation's
+ * stable identity, and - only then - persists exactly once through the
+ * existing contract writer. Never mutates the observation. Never infers,
+ * creates, or removes `supersedesBaselineId` - whatever the caller already
+ * authored is preserved exactly.
+ */
+export declare function approveAndPersistBaseline(rawContract: unknown, observationRoot: string, options: PersistFrontendContractOptions): Promise<ApplicationApproveBaselineResult>;
+/**
+ * The one canonical application-level per-change-contract persistence use
+ * case (`save-change-contract`) - persistence only, never approval
+ * terminology or semantics. Validates the raw contract through the existing
+ * frozen `isValidPerChangeContract` gate (which already rejects a
+ * `PersistentBaselineContract` passed here, an authored `category:
+ * "unexpected"`, and every other structural rule - never duplicated here),
+ * then persists exactly once. `supersedesBaselineClauseIds` is preserved
+ * exactly as authored; this function performs no baseline-reference
+ * resolution (that remains the evaluator's responsibility).
+ */
+export declare function persistPerChangeContract(rawContract: unknown, options: PersistFrontendContractOptions): Promise<ApplicationPersistChangeContractResult>;