my-frontend-observer 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # 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.

package/README.md

@@ -6,15 +6,21 @@ in [docs/PROJECT_DESCRIPTION.md](docs/PROJECT_DESCRIPTION.md).
 
 ## Current status
 
-`v0.4.0`, Layout Relationships, Dependency Evidence, and Before/After
-Comparison, 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`). `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`).
+`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`). `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:
 
@@ -91,6 +97,28 @@ 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
@@ -108,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.4 are
-  released, v0.5 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/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>;

package/dist/application/frontendContractPersistenceService.js

@@ -0,0 +1,91 @@
+import path from 'node:path';
+import { isValidPersistentBaselineContract, isValidPerChangeContract } from '../domain/frontendContracts.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+import { normalizeOutputLocation } from '../request/paths.js';
+import { writePersistentBaselineContract, writePerChangeContract } from '../artifacts/frontendContractArtifactWriter.js';
+import { readObservationArtifact } from '../artifacts/artifactReader.js';
+import { MANIFEST_FILENAME as OBSERVATION_MANIFEST_FILENAME } from '../artifacts/artifactWriter.js';
+function invalidRequest(message) {
+    return { ok: false, diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message }] };
+}
+/**
+ * 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 async function approveAndPersistBaseline(rawContract, observationRoot, options) {
+    const validation = isValidPersistentBaselineContract(rawContract);
+    if (!validation.valid)
+        return invalidRequest(`baseline contract is invalid: ${validation.reason}`);
+    const contract = rawContract;
+    const observationRead = await readObservationArtifact(path.join(observationRoot, OBSERVATION_MANIFEST_FILENAME));
+    if (!observationRead.ok)
+        return invalidRequest(`observation artifact: ${observationRead.reason}`);
+    const observation = observationRead.artifact;
+    const ref = contract.sourceObservation;
+    const matchesObservation = ref.observationId === observation.observationId &&
+        ref.requestId === observation.requestId &&
+        ref.producer.name === observation.producer.name &&
+        ref.producer.version === observation.producer.version &&
+        ref.observationSchemaVersion === observation.schemaVersion;
+    if (!matchesObservation) {
+        return invalidRequest('baseline contract sourceObservation does not match the supplied observation artifact; refusing to approve an unrelated observation');
+    }
+    const normalized = normalizeOutputLocation(options.outputLocation);
+    if (!normalized.ok)
+        return { ok: false, diagnostics: [normalized.diagnostic] };
+    const persisted = await writePersistentBaselineContract(contract, normalized.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok)
+        return { ok: false, diagnostics: persisted.diagnostics };
+    return {
+        ok: true,
+        baselineId: contract.baselineId,
+        ...(contract.supersedesBaselineId === undefined ? {} : { supersedesBaselineId: contract.supersedesBaselineId }),
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        clauseCount: contract.clauses.length,
+    };
+}
+/**
+ * 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 async function persistPerChangeContract(rawContract, options) {
+    const validation = isValidPerChangeContract(rawContract);
+    if (!validation.valid)
+        return invalidRequest(`per-change contract is invalid: ${validation.reason}`);
+    const contract = rawContract;
+    const normalized = normalizeOutputLocation(options.outputLocation);
+    if (!normalized.ok)
+        return { ok: false, diagnostics: [normalized.diagnostic] };
+    const persisted = await writePerChangeContract(contract, normalized.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok)
+        return { ok: false, diagnostics: persisted.diagnostics };
+    const supersedesBaselineClauseCount = contract.clauses.reduce((count, clause) => count + (clause.supersedesBaselineClauseIds?.length ?? 0), 0);
+    return {
+        ok: true,
+        contractId: contract.contractId,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        clauseCount: contract.clauses.length,
+        supersedesBaselineClauseCount,
+    };
+}
+//# sourceMappingURL=frontendContractPersistenceService.js.map

package/dist/application/frontendContractPersistenceService.js.map

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

package/dist/artifacts/comparisonArtifactReader.d.ts

@@ -0,0 +1,18 @@
+import type { ComparisonArtifact } from '../domain/comparison.js';
+export type ReadComparisonArtifactResult = {
+    ok: true;
+    artifact: ComparisonArtifact;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * v0.5 Batch 3 addition: no canonical comparison-artifact reader existed
+ * before this batch (only `readObservationArtifact` did). Narrow counterpart
+ * to `artifacts/comparisonArtifactWriter.ts#writeComparisonArtifact`: reads
+ * one `manifest.json`, parses it, and validates it through the same
+ * `isValidComparisonArtifact` structural gate the writer uses - never a
+ * second validator, never a schema upgrade. Comparison schema remains
+ * `1.0.0`; this reader changes no comparison semantics.
+ */
+export declare function readComparisonArtifact(manifestPath: string): Promise<ReadComparisonArtifactResult>;

package/dist/artifacts/comparisonArtifactReader.js

@@ -0,0 +1,35 @@
+import { readFile } from 'node:fs/promises';
+import { isValidComparisonArtifact } from '../domain/comparison.js';
+/**
+ * v0.5 Batch 3 addition: no canonical comparison-artifact reader existed
+ * before this batch (only `readObservationArtifact` did). Narrow counterpart
+ * to `artifacts/comparisonArtifactWriter.ts#writeComparisonArtifact`: reads
+ * one `manifest.json`, parses it, and validates it through the same
+ * `isValidComparisonArtifact` structural gate the writer uses - never a
+ * second validator, never a schema upgrade. Comparison schema remains
+ * `1.0.0`; this reader changes no comparison semantics.
+ */
+export async function readComparisonArtifact(manifestPath) {
+    let raw;
+    try {
+        raw = await readFile(manifestPath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `failed to read comparison artifact manifest at "${manifestPath}": ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `comparison artifact manifest at "${manifestPath}" is not valid JSON: ${message}` };
+    }
+    const validation = isValidComparisonArtifact(parsed);
+    if (!validation.valid) {
+        return { ok: false, reason: `comparison artifact manifest at "${manifestPath}" failed structural validation: ${validation.reason}` };
+    }
+    return { ok: true, artifact: parsed };
+}
+//# sourceMappingURL=comparisonArtifactReader.js.map

package/dist/artifacts/comparisonArtifactReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparisonArtifactReader.js","sourceRoot":"","sources":["../../src/artifacts/comparisonArtifactReader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAIpE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,YAAoB;IAC/D,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mDAAmD,YAAY,MAAM,OAAO,EAAE,EAAE,CAAC;IAC/G,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,YAAY,wBAAwB,OAAO,EAAE,EAAE,CAAC;IAClH,CAAC;IAED,MAAM,UAAU,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IACrD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,YAAY,mCAAmC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;IACvI,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAA4B,EAAE,CAAC;AAC9D,CAAC"}

package/dist/artifacts/frontendContractArtifactReader.d.ts

@@ -0,0 +1,24 @@
+import type { PersistentBaselineContract, PerChangeContract } from '../domain/frontendContracts.js';
+export type ReadPersistentBaselineContractResult = {
+    ok: true;
+    contract: PersistentBaselineContract;
+} | {
+    ok: false;
+    reason: string;
+};
+export type ReadPerChangeContractResult = {
+    ok: true;
+    contract: PerChangeContract;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Narrow canonical reader counterpart to `frontendContractArtifactWriter.ts#writePersistentBaselineContract`:
+ * reads one `manifest.json`, parses it, and validates it through the same
+ * `isValidPersistentBaselineContract` structural gate the writer uses - never
+ * a second validator, never a schema upgrade, never a guessed missing field.
+ */
+export declare function readPersistentBaselineContract(manifestPath: string): Promise<ReadPersistentBaselineContractResult>;
+/** Narrow canonical reader counterpart to `frontendContractArtifactWriter.ts#writePerChangeContract`. */
+export declare function readPerChangeContract(manifestPath: string): Promise<ReadPerChangeContractResult>;

package/dist/artifacts/frontendContractArtifactReader.js

@@ -0,0 +1,47 @@
+import { readFile } from 'node:fs/promises';
+import { isValidPersistentBaselineContract, isValidPerChangeContract } from '../domain/frontendContracts.js';
+async function readJson(manifestPath) {
+    let raw;
+    try {
+        raw = await readFile(manifestPath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `failed to read artifact manifest at "${manifestPath}": ${message}` };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `artifact manifest at "${manifestPath}" is not valid JSON: ${message}` };
+    }
+}
+/**
+ * Narrow canonical reader counterpart to `frontendContractArtifactWriter.ts#writePersistentBaselineContract`:
+ * reads one `manifest.json`, parses it, and validates it through the same
+ * `isValidPersistentBaselineContract` structural gate the writer uses - never
+ * a second validator, never a schema upgrade, never a guessed missing field.
+ */
+export async function readPersistentBaselineContract(manifestPath) {
+    const parsed = await readJson(manifestPath);
+    if (!parsed.ok)
+        return parsed;
+    const validation = isValidPersistentBaselineContract(parsed.value);
+    if (!validation.valid) {
+        return { ok: false, reason: `baseline contract manifest at "${manifestPath}" failed structural validation: ${validation.reason}` };
+    }
+    return { ok: true, contract: parsed.value };
+}
+/** Narrow canonical reader counterpart to `frontendContractArtifactWriter.ts#writePerChangeContract`. */
+export async function readPerChangeContract(manifestPath) {
+    const parsed = await readJson(manifestPath);
+    if (!parsed.ok)
+        return parsed;
+    const validation = isValidPerChangeContract(parsed.value);
+    if (!validation.valid) {
+        return { ok: false, reason: `per-change contract manifest at "${manifestPath}" failed structural validation: ${validation.reason}` };
+    }
+    return { ok: true, contract: parsed.value };
+}
+//# sourceMappingURL=frontendContractArtifactReader.js.map

package/dist/artifacts/frontendContractArtifactReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontendContractArtifactReader.js","sourceRoot":"","sources":["../../src/artifacts/frontendContractArtifactReader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,iCAAiC,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAK7G,KAAK,UAAU,QAAQ,CAAC,YAAoB;IAC1C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wCAAwC,YAAY,MAAM,OAAO,EAAE,EAAE,CAAC;IACpG,CAAC;IACD,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,YAAY,wBAAwB,OAAO,EAAE,EAAE,CAAC;IACvG,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAAC,YAAoB;IACvE,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC;IAC9B,MAAM,UAAU,GAAG,iCAAiC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,kCAAkC,YAAY,mCAAmC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;IACrI,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,KAAmC,EAAE,CAAC;AAC5E,CAAC;AAED,yGAAyG;AACzG,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,YAAoB;IAC9D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC;IAC9B,MAAM,UAAU,GAAG,wBAAwB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1D,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,YAAY,mCAAmC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;IACvI,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,KAA0B,EAAE,CAAC;AACnE,CAAC"}

package/dist/artifacts/frontendContractArtifactWriter.d.ts

@@ -0,0 +1,34 @@
+import type { PersistentBaselineContract, PerChangeContract } from '../domain/frontendContracts.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+export declare const FRONTEND_CONTRACT_MANIFEST_FILENAME = "manifest.json";
+/**
+ * Mirrors `PersistedComparisonResult`'s shape/semantics - a frontend contract
+ * directory has no screenshot file either, and this writer never touches
+ * `artifacts/artifactWriter.ts` or `artifacts/comparisonArtifactWriter.ts`.
+ */
+export type PersistedFrontendContractResult = {
+    ok: true;
+    artifactRoot: string;
+    manifestPath: string;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+export interface WriteFrontendContractArtifactOptions {
+    /** Base directory that `outputLocation` is resolved against. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/**
+ * Persists one already-valid `PersistentBaselineContract` as
+ * `<outputLocation>/<baselineId>/manifest.json`. Never mutates or removes any
+ * other baseline artifact - `supersedesBaselineId` (if present) is written
+ * exactly as supplied; this writer never inspects, rewrites, or deletes the
+ * baseline it refers to.
+ */
+export declare function writePersistentBaselineContract(contract: PersistentBaselineContract, outputLocation: string, options?: WriteFrontendContractArtifactOptions): Promise<PersistedFrontendContractResult>;
+/**
+ * Persists one already-valid `PerChangeContract` as
+ * `<outputLocation>/<contractId>/manifest.json`, symmetric with baseline
+ * persistence above (both share `CONTRACT_ARTIFACT_KIND`/`CONTRACT_SCHEMA_VERSION`).
+ */
+export declare function writePerChangeContract(contract: PerChangeContract, outputLocation: string, options?: WriteFrontendContractArtifactOptions): Promise<PersistedFrontendContractResult>;