my-frontend-observer 0.3.0 → 0.5.0

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/artifactReader.d.ts

@@ -0,0 +1,19 @@
+import type { ObservationArtifact } from '../domain/schema.js';
+export type ReadObservationArtifactResult = {
+    ok: true;
+    artifact: ObservationArtifact;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Narrow canonical reader counterpart to `artifactWriter.ts#writeObservationArtifact`:
+ * reads one `manifest.json`, parses it, and validates it through the same
+ * `isValidObservationArtifact` structural gate the writer itself uses -
+ * never a second validator. Read-only: never mutates the file, never
+ * launches a browser, never resolves the sibling screenshot's bytes (the
+ * manifest's `screenshot.path` field is returned as-is for the caller to
+ * resolve if it needs to). Established here as the canonical reader ahead of
+ * the Batch 4 `compare` CLI's `--before`/`--after` path arguments.
+ */
+export declare function readObservationArtifact(manifestPath: string): Promise<ReadObservationArtifactResult>;

package/dist/artifacts/artifactReader.js

@@ -0,0 +1,36 @@
+import { readFile } from 'node:fs/promises';
+import { isValidObservationArtifact } from '../domain/schema.js';
+/**
+ * Narrow canonical reader counterpart to `artifactWriter.ts#writeObservationArtifact`:
+ * reads one `manifest.json`, parses it, and validates it through the same
+ * `isValidObservationArtifact` structural gate the writer itself uses -
+ * never a second validator. Read-only: never mutates the file, never
+ * launches a browser, never resolves the sibling screenshot's bytes (the
+ * manifest's `screenshot.path` field is returned as-is for the caller to
+ * resolve if it needs to). Established here as the canonical reader ahead of
+ * the Batch 4 `compare` CLI's `--before`/`--after` path arguments.
+ */
+export async function readObservationArtifact(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 observation 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: `observation artifact manifest at "${manifestPath}" is not valid JSON: ${message}` };
+    }
+    const validation = isValidObservationArtifact(parsed);
+    if (!validation.valid) {
+        return { ok: false, reason: `observation artifact manifest at "${manifestPath}" failed structural validation: ${validation.reason}` };
+    }
+    return { ok: true, artifact: parsed };
+}
+//# sourceMappingURL=artifactReader.js.map

package/dist/artifacts/artifactReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactReader.js","sourceRoot":"","sources":["../../src/artifacts/artifactReader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAIjE;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,YAAoB;IAChE,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,oDAAoD,YAAY,MAAM,OAAO,EAAE,EAAE,CAAC;IAChH,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,qCAAqC,YAAY,wBAAwB,OAAO,EAAE,EAAE,CAAC;IACnH,CAAC;IAED,MAAM,UAAU,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qCAAqC,YAAY,mCAAmC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;IACxI,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAA6B,EAAE,CAAC;AAC/D,CAAC"}

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/comparisonArtifactWriter.d.ts

@@ -0,0 +1,41 @@
+import type { ComparisonArtifact } from '../domain/comparison.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+export declare const COMPARISON_MANIFEST_FILENAME = "manifest.json";
+/**
+ * Observer-owned result of persisting one ComparisonArtifact. Mirrors
+ * `PersistedObservationResult`'s shape/semantics but is its own type: a
+ * comparison directory has no screenshot file, and this writer never touches
+ * `src/artifacts/artifactWriter.ts` or its observation-persistence
+ * guarantees.
+ */
+export type PersistedComparisonResult = {
+    ok: true;
+    artifactRoot: string;
+    manifestPath: string;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+export interface WriteComparisonArtifactOptions {
+    /** Base directory that `outputLocation` is resolved against. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/**
+ * Persists one already-assembled, already-validated `ComparisonArtifact` as
+ * one portable artifact directory: `<outputLocation>/<comparisonId>/manifest.json`
+ * only - no screenshot is copied (the manifest's `before`/`after.screenshot`
+ * fields already point back to the source observations; see
+ * `domain/comparisonEngine.ts#sourceReference`), and no `relationships.json`/
+ * `differences.json`/`diff.png` side files are produced.
+ *
+ * Follows the same atomic-write discipline as
+ * `artifacts/artifactWriter.ts#writeObservationArtifact` (sibling temporary
+ * directory, then one atomic rename onto the final name) without sharing its
+ * implementation - a comparison directory has a different, smaller content
+ * shape, and this function never touches observation persistence. A fresh
+ * `comparisonId` per execution normally prevents collisions; an existing
+ * directory at the final path is treated as a genuine collision and
+ * rejected rather than overwritten, so prior comparison evidence is never
+ * destructively replaced.
+ */
+export declare function writeComparisonArtifact(artifact: ComparisonArtifact, outputLocation: string, options?: WriteComparisonArtifactOptions): Promise<PersistedComparisonResult>;

package/dist/artifacts/comparisonArtifactWriter.js

@@ -0,0 +1,67 @@
+import { mkdir, writeFile, rename, rm, access } from 'node:fs/promises';
+import path from 'node:path';
+import { isValidComparisonArtifact } from '../domain/comparison.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+export const COMPARISON_MANIFEST_FILENAME = 'manifest.json';
+function writeFailure(message, details) {
+    const diagnostic = {
+        code: 'artifact-write-failure',
+        severity: DIAGNOSTIC_SEVERITY['artifact-write-failure'],
+        message,
+        ...(details === undefined ? {} : { details }),
+    };
+    return { ok: false, diagnostics: [diagnostic] };
+}
+async function pathExists(candidate) {
+    return access(candidate).then(() => true, () => false);
+}
+/**
+ * Persists one already-assembled, already-validated `ComparisonArtifact` as
+ * one portable artifact directory: `<outputLocation>/<comparisonId>/manifest.json`
+ * only - no screenshot is copied (the manifest's `before`/`after.screenshot`
+ * fields already point back to the source observations; see
+ * `domain/comparisonEngine.ts#sourceReference`), and no `relationships.json`/
+ * `differences.json`/`diff.png` side files are produced.
+ *
+ * Follows the same atomic-write discipline as
+ * `artifacts/artifactWriter.ts#writeObservationArtifact` (sibling temporary
+ * directory, then one atomic rename onto the final name) without sharing its
+ * implementation - a comparison directory has a different, smaller content
+ * shape, and this function never touches observation persistence. A fresh
+ * `comparisonId` per execution normally prevents collisions; an existing
+ * directory at the final path is treated as a genuine collision and
+ * rejected rather than overwritten, so prior comparison evidence is never
+ * destructively replaced.
+ */
+export async function writeComparisonArtifact(artifact, outputLocation, options = {}) {
+    const validation = isValidComparisonArtifact(artifact);
+    if (!validation.valid) {
+        return writeFailure(`refusing to persist an invalid ComparisonArtifact: ${validation.reason}`);
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const outputRoot = path.resolve(cwd, outputLocation);
+    const finalRoot = path.join(outputRoot, artifact.comparisonId);
+    const tempRoot = path.join(outputRoot, `.tmp-${artifact.comparisonId}`);
+    if (await pathExists(finalRoot)) {
+        return writeFailure(`a comparison artifact already exists at "${artifact.comparisonId}"; refusing to overwrite it`, {
+            artifactRoot: finalRoot,
+        });
+    }
+    try {
+        await rm(tempRoot, { recursive: true, force: true });
+        await mkdir(tempRoot, { recursive: true });
+        await writeFile(path.join(tempRoot, COMPARISON_MANIFEST_FILENAME), JSON.stringify(artifact, null, 2), 'utf8');
+        await rename(tempRoot, finalRoot);
+        return {
+            ok: true,
+            artifactRoot: finalRoot,
+            manifestPath: path.join(finalRoot, COMPARISON_MANIFEST_FILENAME),
+        };
+    }
+    catch (err) {
+        await rm(tempRoot, { recursive: true, force: true }).catch(() => undefined);
+        const message = err instanceof Error ? err.message : String(err);
+        return writeFailure(`failed to persist comparison artifact: ${message}`);
+    }
+}
+//# sourceMappingURL=comparisonArtifactWriter.js.map

package/dist/artifacts/comparisonArtifactWriter.js.map

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

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>;

package/dist/artifacts/frontendContractArtifactWriter.js

@@ -0,0 +1,70 @@
+import { mkdir, writeFile, rename, rm, access } from 'node:fs/promises';
+import path from 'node:path';
+import { isValidPersistentBaselineContract, isValidPerChangeContract } from '../domain/frontendContracts.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+export const FRONTEND_CONTRACT_MANIFEST_FILENAME = 'manifest.json';
+function writeFailure(message, details) {
+    const diagnostic = {
+        code: 'artifact-write-failure',
+        severity: DIAGNOSTIC_SEVERITY['artifact-write-failure'],
+        message,
+        ...(details === undefined ? {} : { details }),
+    };
+    return { ok: false, diagnostics: [diagnostic] };
+}
+async function pathExists(candidate) {
+    return access(candidate).then(() => true, () => false);
+}
+/**
+ * Shared atomic-write body for both contract classes, following the same
+ * discipline as `writeObservationArtifact`/`writeComparisonArtifact`: sibling
+ * temporary directory, single `manifest.json`, then one atomic rename. An
+ * existing directory at the final identity is a genuine collision (never a
+ * destructive overwrite of prior baseline/contract history) and is rejected.
+ */
+async function writeContractArtifact(value, id, kindLabel, outputLocation, options) {
+    const cwd = options.cwd ?? process.cwd();
+    const outputRoot = path.resolve(cwd, outputLocation);
+    const finalRoot = path.join(outputRoot, id);
+    const tempRoot = path.join(outputRoot, `.tmp-${id}`);
+    if (await pathExists(finalRoot)) {
+        return writeFailure(`a ${kindLabel} artifact already exists at "${id}"; refusing to overwrite it`, { artifactRoot: finalRoot });
+    }
+    try {
+        await rm(tempRoot, { recursive: true, force: true });
+        await mkdir(tempRoot, { recursive: true });
+        await writeFile(path.join(tempRoot, FRONTEND_CONTRACT_MANIFEST_FILENAME), JSON.stringify(value, null, 2), 'utf8');
+        await rename(tempRoot, finalRoot);
+        return { ok: true, artifactRoot: finalRoot, manifestPath: path.join(finalRoot, FRONTEND_CONTRACT_MANIFEST_FILENAME) };
+    }
+    catch (err) {
+        await rm(tempRoot, { recursive: true, force: true }).catch(() => undefined);
+        const message = err instanceof Error ? err.message : String(err);
+        return writeFailure(`failed to persist ${kindLabel} artifact: ${message}`);
+    }
+}
+/**
+ * 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 async function writePersistentBaselineContract(contract, outputLocation, options = {}) {
+    const validation = isValidPersistentBaselineContract(contract);
+    if (!validation.valid)
+        return writeFailure(`refusing to persist an invalid PersistentBaselineContract: ${validation.reason}`);
+    return writeContractArtifact(contract, contract.baselineId, 'baseline contract', outputLocation, options);
+}
+/**
+ * Persists one already-valid `PerChangeContract` as
+ * `<outputLocation>/<contractId>/manifest.json`, symmetric with baseline
+ * persistence above (both share `CONTRACT_ARTIFACT_KIND`/`CONTRACT_SCHEMA_VERSION`).
+ */
+export async function writePerChangeContract(contract, outputLocation, options = {}) {
+    const validation = isValidPerChangeContract(contract);
+    if (!validation.valid)
+        return writeFailure(`refusing to persist an invalid PerChangeContract: ${validation.reason}`);
+    return writeContractArtifact(contract, contract.contractId, 'per-change contract', outputLocation, options);
+}
+//# sourceMappingURL=frontendContractArtifactWriter.js.map

package/dist/artifacts/frontendContractArtifactWriter.js.map

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

package/dist/artifacts/frontendContractEvaluationArtifactReader.d.ts

@@ -0,0 +1,17 @@
+import type { FrontendContractEvaluationArtifact } from '../domain/frontendContractEvaluationArtifact.js';
+export type ReadFrontendContractEvaluationArtifactResult = {
+    ok: true;
+    artifact: FrontendContractEvaluationArtifact;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Narrow canonical reader counterpart to
+ * `frontendContractEvaluationArtifactWriter.ts#writeFrontendContractEvaluationArtifact`:
+ * reads one `manifest.json`, parses it, and validates it through the same
+ * `isValidFrontendContractEvaluationArtifact` structural gate the writer
+ * uses. Read-only: never mutates the file, never recomputes or reinterprets
+ * the evaluation, never repairs a malformed artifact.
+ */
+export declare function readFrontendContractEvaluationArtifact(manifestPath: string): Promise<ReadFrontendContractEvaluationArtifactResult>;

package/dist/artifacts/frontendContractEvaluationArtifactReader.js

@@ -0,0 +1,34 @@
+import { readFile } from 'node:fs/promises';
+import { isValidFrontendContractEvaluationArtifact } from '../domain/frontendContractEvaluationArtifact.js';
+/**
+ * Narrow canonical reader counterpart to
+ * `frontendContractEvaluationArtifactWriter.ts#writeFrontendContractEvaluationArtifact`:
+ * reads one `manifest.json`, parses it, and validates it through the same
+ * `isValidFrontendContractEvaluationArtifact` structural gate the writer
+ * uses. Read-only: never mutates the file, never recomputes or reinterprets
+ * the evaluation, never repairs a malformed artifact.
+ */
+export async function readFrontendContractEvaluationArtifact(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 evaluation 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: `evaluation artifact manifest at "${manifestPath}" is not valid JSON: ${message}` };
+    }
+    const validation = isValidFrontendContractEvaluationArtifact(parsed);
+    if (!validation.valid) {
+        return { ok: false, reason: `evaluation artifact manifest at "${manifestPath}" failed structural validation: ${validation.reason}` };
+    }
+    return { ok: true, artifact: parsed };
+}
+//# sourceMappingURL=frontendContractEvaluationArtifactReader.js.map

package/dist/artifacts/frontendContractEvaluationArtifactReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontendContractEvaluationArtifactReader.js","sourceRoot":"","sources":["../../src/artifacts/frontendContractEvaluationArtifactReader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,yCAAyC,EAAE,MAAM,iDAAiD,CAAC;AAI5G;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,sCAAsC,CAAC,YAAoB;IAC/E,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,yCAAyC,CAAC,MAAM,CAAC,CAAC;IACrE,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,MAA4C,EAAE,CAAC;AAC9E,CAAC"}

package/dist/artifacts/frontendContractEvaluationArtifactWriter.d.ts

@@ -0,0 +1,32 @@
+import type { FrontendContractEvaluationArtifact } from '../domain/frontendContractEvaluationArtifact.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+export declare const EVALUATION_MANIFEST_FILENAME = "manifest.json";
+export type PersistedFrontendContractEvaluationResult = {
+    ok: true;
+    artifactRoot: string;
+    manifestPath: string;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+export interface WriteFrontendContractEvaluationArtifactOptions {
+    /** Base directory that `outputLocation` is resolved against. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/**
+ * Persists one already-built, already-valid `FrontendContractEvaluationArtifact`
+ * as `<outputLocation>/<evaluationId>/manifest.json` only - no screenshot is
+ * copied (the artifact's `before`/`after` fields already point back to the
+ * source observations). Same atomic-write discipline as
+ * `artifactWriter.ts#writeObservationArtifact`/`comparisonArtifactWriter.ts#writeComparisonArtifact`
+ * without sharing their implementation: sibling temporary directory, then one
+ * atomic rename. `evaluationId` is fresh per execution (see
+ * `frontendContractIdentity.ts#buildFrontendContractInstanceIdentity`), so an
+ * existing directory at the final path is a genuine collision and is
+ * rejected rather than overwritten - a legitimate PASS or FAIL evaluation
+ * result is never silently replaced. A `FAIL` verdict is a legitimate,
+ * persistable evaluation result, not a write failure; only an unpersistable
+ * artifact (invalid shape, or a real filesystem error) is reported as
+ * `ok: false`.
+ */
+export declare function writeFrontendContractEvaluationArtifact(artifact: FrontendContractEvaluationArtifact, outputLocation: string, options?: WriteFrontendContractEvaluationArtifactOptions): Promise<PersistedFrontendContractEvaluationResult>;