@dailephd/my-frontend-observer 0.8.1

package/dist/application/browserCaptureService.d.ts

@@ -0,0 +1,11 @@
+import type { NormalizedObservationRequest } from '../request/request.js';
+import type { BrowserCaptureResult } from '../browser/types.js';
+export type { BrowserCaptureResult, BrowserProvenance } from '../browser/types.js';
+/**
+ * Minimum application-facing seam over the browser adapter: takes an
+ * already-validated request and returns the observer-owned browser-boundary
+ * result. Coordinates nothing beyond that single invocation - no page/target
+ * evidence, no artifact writing, no CLI reporting. Later batches extend this
+ * seam rather than calling the browser adapter directly.
+ */
+export declare function runBrowserCapture(request: NormalizedObservationRequest): Promise<BrowserCaptureResult>;

package/dist/application/browserCaptureService.js

@@ -0,0 +1,12 @@
+import { captureViewport } from '../browser/chromiumAdapter.js';
+/**
+ * Minimum application-facing seam over the browser adapter: takes an
+ * already-validated request and returns the observer-owned browser-boundary
+ * result. Coordinates nothing beyond that single invocation - no page/target
+ * evidence, no artifact writing, no CLI reporting. Later batches extend this
+ * seam rather than calling the browser adapter directly.
+ */
+export async function runBrowserCapture(request) {
+    return captureViewport(request);
+}
+//# sourceMappingURL=browserCaptureService.js.map

package/dist/application/browserCaptureService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserCaptureService.js","sourceRoot":"","sources":["../../src/application/browserCaptureService.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAKhE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAqC;IAC3E,OAAO,eAAe,CAAC,OAAO,CAAC,CAAC;AAClC,CAAC"}

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

@@ -0,0 +1,75 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { ReferenceRegion } from '../domain/externalReferenceRegions.js';
+import type { RawReferenceRequirement, ReferenceRequirementAdequacy } from '../domain/externalReferenceRequirements.js';
+import type { ExternalReferenceApplicability } from '../domain/externalReferenceApplicability.js';
+import type { WriteExternalReferenceArtifactOptions } from '../artifacts/externalReferenceArtifactWriter.js';
+export interface ImportExternalReferenceOptions {
+    outputLocation: string;
+    cwd?: WriteExternalReferenceArtifactOptions['cwd'];
+    label?: string;
+    /** Root directory of a prior external-reference artifact this import explicitly supersedes. */
+    supersedesReferenceRoot?: string;
+    /** v0.7 Prompt 2: explicit, user/configuration-authored reference-image regions. Identity-bearing when present - see externalReferenceIdentity.ts. */
+    regions?: ReferenceRegion[];
+    /** v0.7 Prompt 3: explicit, user/configuration-selected design requirements over `regions` above. Raw (not yet identified) authored input - see domain/externalReferenceRequirements.ts#RawReferenceRequirement. Identity-bearing when present. */
+    requirements?: RawReferenceRequirement[];
+    /** v0.7 Prompt 4: the runtime frontend state (applicable viewport/theme/application-state/authenticated-state) this reference is intended to represent. Identity-bearing when present. */
+    applicability?: ExternalReferenceApplicability;
+}
+export interface ApproveExternalReferenceOptions {
+    outputLocation: string;
+    cwd?: WriteExternalReferenceArtifactOptions['cwd'];
+    /** Root directory of a prior external-reference artifact this approval explicitly supersedes. */
+    supersedesReferenceRoot?: string;
+}
+export type ApplicationImportExternalReferenceResult = {
+    ok: true;
+    referenceId: string;
+    referenceRequestId: string;
+    artifactRoot: string;
+    manifestPath: string;
+    imagePath: string;
+    regionCount: number;
+    requirementCount: number;
+    adequacy: ReferenceRequirementAdequacy;
+    hasApplicability: boolean;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+export type ApplicationApproveExternalReferenceResult = {
+    ok: true;
+    referenceId: string;
+    referenceRequestId: string;
+    artifactRoot: string;
+    manifestPath: string;
+    regionCount: number;
+    requirementCount: number;
+    adequacy: ReferenceRequirementAdequacy;
+    hasApplicability: boolean;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * The one canonical application-level "import" use case: validates the raw
+ * image bytes through the existing pure image-format/dimension boundary
+ * (`domain/externalReferenceImage.ts`), resolves an optional explicit
+ * supersession target through the existing reader, computes identity through
+ * the existing identity module, and persists exactly once through the
+ * existing writer. Never approves the result - the persisted artifact's
+ * `lifecycle.state` is always `'imported'`, regardless of a supplied label or
+ * supersession target (see behavior-model.txt INV-007).
+ */
+export declare function importExternalReference(imageBytes: Uint8Array, options: ImportExternalReferenceOptions): Promise<ApplicationImportExternalReferenceResult>;
+/**
+ * The one canonical application-level "approval" use case, mirroring
+ * `application/frontendContractPersistenceService.ts#approveAndPersistBaseline`'s
+ * shape: reads the target through the existing reader, refuses to approve
+ * anything not currently in the `'imported'` lifecycle state, resolves an
+ * optional explicit supersession target through the same reader, and
+ * persists a brand-new artifact instance - never mutating the imported
+ * artifact's own manifest - carrying a `sourceReference` back to it instead
+ * of a second copy of the image bytes.
+ */
+export declare function approveExternalReference(importedArtifactRoot: string, options: ApproveExternalReferenceOptions): Promise<ApplicationApproveExternalReferenceResult>;

package/dist/application/externalReferencePersistenceService.js

@@ -0,0 +1,182 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+import { deriveCompletion } from '../domain/completion.js';
+import { getProducerInfo } from '../domain/schema.js';
+import { detectExternalReferenceImageFormat, readExternalReferenceImageDimensions, isValidExternalReferenceImageDimensions, fileExtensionForFormat, EXTERNAL_REFERENCE_MAX_IMAGE_BYTES, } from '../domain/externalReferenceImage.js';
+import { EXTERNAL_REFERENCE_ARTIFACT_KIND, EXTERNAL_REFERENCE_SCHEMA_VERSION, isImportedExternalReferenceArtifact } from '../domain/externalReference.js';
+import { buildExternalReferenceRequestIdentity, buildExternalReferenceInstanceIdentity } from '../domain/externalReferenceIdentity.js';
+import { isValidReferenceRegions } from '../domain/externalReferenceRegions.js';
+import { isValidRawReferenceRequirement, buildReferenceRequirement, isValidReferenceRequirements, deriveReferenceRequirementAdequacy } from '../domain/externalReferenceRequirements.js';
+import { isValidExternalReferenceApplicability } from '../domain/externalReferenceApplicability.js';
+import { normalizeOutputLocation } from '../request/paths.js';
+import { writeExternalReferenceArtifact } from '../artifacts/externalReferenceArtifactWriter.js';
+import { EXTERNAL_REFERENCE_MANIFEST_FILENAME } from '../artifacts/externalReferenceArtifactWriter.js';
+import { readExternalReferenceArtifact } from '../artifacts/externalReferenceArtifactReader.js';
+function failure(code, message) {
+    return { ok: false, diagnostics: [{ code, severity: DIAGNOSTIC_SEVERITY[code], message }] };
+}
+async function resolveSupersedesReferenceId(supersedesReferenceRoot) {
+    if (supersedesReferenceRoot === undefined)
+        return { ok: true };
+    const read = await readExternalReferenceArtifact(path.join(supersedesReferenceRoot, EXTERNAL_REFERENCE_MANIFEST_FILENAME));
+    if (!read.ok)
+        return failure('reference-not-found', `supersedesReferenceRoot: ${read.reason}`);
+    return { ok: true, referenceId: read.artifact.referenceId };
+}
+/**
+ * The one canonical application-level "import" use case: validates the raw
+ * image bytes through the existing pure image-format/dimension boundary
+ * (`domain/externalReferenceImage.ts`), resolves an optional explicit
+ * supersession target through the existing reader, computes identity through
+ * the existing identity module, and persists exactly once through the
+ * existing writer. Never approves the result - the persisted artifact's
+ * `lifecycle.state` is always `'imported'`, regardless of a supplied label or
+ * supersession target (see behavior-model.txt INV-007).
+ */
+export async function importExternalReference(imageBytes, options) {
+    const format = detectExternalReferenceImageFormat(imageBytes);
+    if (format === undefined)
+        return failure('unsupported-image-format', 'the supplied bytes do not match any supported reference image format (png, jpeg, webp)');
+    if (imageBytes.length > EXTERNAL_REFERENCE_MAX_IMAGE_BYTES) {
+        return failure('image-too-large', `reference image is ${imageBytes.length} bytes, exceeding the maximum of ${EXTERNAL_REFERENCE_MAX_IMAGE_BYTES} bytes`);
+    }
+    const dimensions = readExternalReferenceImageDimensions(imageBytes, format);
+    if (dimensions === undefined || !isValidExternalReferenceImageDimensions(dimensions)) {
+        return failure('invalid-image-dimensions', 'the supplied reference image header does not contain valid, bounded dimensions');
+    }
+    if (options.regions !== undefined) {
+        const regionsValidation = isValidReferenceRegions(options.regions, dimensions.width, dimensions.height);
+        if (!regionsValidation.valid)
+            return failure('invalid-reference-region', regionsValidation.reason);
+    }
+    let requirements;
+    if (options.requirements !== undefined) {
+        const built = [];
+        for (const raw of options.requirements) {
+            const rawValidation = isValidRawReferenceRequirement(raw);
+            if (!rawValidation.valid)
+                return failure('invalid-reference-requirement', rawValidation.reason);
+            built.push(buildReferenceRequirement(raw));
+        }
+        const collectionValidation = isValidReferenceRequirements(built, options.regions ?? []);
+        if (!collectionValidation.valid)
+            return failure('invalid-reference-requirement', collectionValidation.reason);
+        requirements = built;
+    }
+    if (options.applicability !== undefined) {
+        const applicabilityValidation = isValidExternalReferenceApplicability(options.applicability);
+        if (!applicabilityValidation.valid)
+            return failure('invalid-reference-applicability', applicabilityValidation.reason);
+    }
+    const supersedes = await resolveSupersedesReferenceId(options.supersedesReferenceRoot);
+    if (!supersedes.ok)
+        return supersedes;
+    const normalizedOutput = normalizeOutputLocation(options.outputLocation);
+    if (!normalizedOutput.ok)
+        return { ok: false, diagnostics: [normalizedOutput.diagnostic] };
+    const imageSha256 = createHash('sha256').update(imageBytes).digest('hex');
+    const referenceRequestId = buildExternalReferenceRequestIdentity(imageSha256, format, dimensions.width, dimensions.height, supersedes.referenceId, options.regions, requirements, options.applicability);
+    const referenceId = buildExternalReferenceInstanceIdentity(referenceRequestId);
+    const artifact = {
+        artifactKind: EXTERNAL_REFERENCE_ARTIFACT_KIND,
+        schemaVersion: EXTERNAL_REFERENCE_SCHEMA_VERSION,
+        referenceRequestId,
+        referenceId,
+        producer: getProducerInfo(),
+        provenance: { importedAt: new Date().toISOString(), ...(options.label === undefined ? {} : { label: options.label }) },
+        image: {
+            path: `reference.${fileExtensionForFormat(format)}`,
+            format,
+            width: dimensions.width,
+            height: dimensions.height,
+            byteLength: imageBytes.length,
+            sha256: imageSha256,
+        },
+        lifecycle: { state: 'imported' },
+        ...(supersedes.referenceId === undefined ? {} : { supersedesReferenceId: supersedes.referenceId }),
+        ...(options.regions === undefined ? {} : { regions: options.regions }),
+        ...(requirements === undefined ? {} : { requirements }),
+        ...(options.applicability === undefined ? {} : { applicability: options.applicability }),
+        diagnostics: [],
+        completion: deriveCompletion([], 'post-capture'),
+    };
+    const persisted = await writeExternalReferenceArtifact(artifact, imageBytes, normalizedOutput.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok)
+        return { ok: false, diagnostics: persisted.diagnostics };
+    return {
+        ok: true,
+        referenceId: artifact.referenceId,
+        referenceRequestId: artifact.referenceRequestId,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        imagePath: persisted.imagePath,
+        regionCount: artifact.regions?.length ?? 0,
+        requirementCount: artifact.requirements?.length ?? 0,
+        adequacy: deriveReferenceRequirementAdequacy(artifact.regions ?? [], artifact.requirements ?? []),
+        hasApplicability: artifact.applicability !== undefined,
+    };
+}
+/**
+ * The one canonical application-level "approval" use case, mirroring
+ * `application/frontendContractPersistenceService.ts#approveAndPersistBaseline`'s
+ * shape: reads the target through the existing reader, refuses to approve
+ * anything not currently in the `'imported'` lifecycle state, resolves an
+ * optional explicit supersession target through the same reader, and
+ * persists a brand-new artifact instance - never mutating the imported
+ * artifact's own manifest - carrying a `sourceReference` back to it instead
+ * of a second copy of the image bytes.
+ */
+export async function approveExternalReference(importedArtifactRoot, options) {
+    const read = await readExternalReferenceArtifact(path.join(importedArtifactRoot, EXTERNAL_REFERENCE_MANIFEST_FILENAME));
+    if (!read.ok)
+        return failure('reference-not-found', read.reason);
+    if (!isImportedExternalReferenceArtifact(read.artifact)) {
+        return failure('invalid-request', `external-reference artifact "${read.artifact.referenceId}" is not in the "imported" lifecycle state; only a freshly imported reference can be approved`);
+    }
+    const imported = read.artifact;
+    const supersedes = await resolveSupersedesReferenceId(options.supersedesReferenceRoot);
+    if (!supersedes.ok)
+        return supersedes;
+    const normalizedOutput = normalizeOutputLocation(options.outputLocation);
+    if (!normalizedOutput.ok)
+        return { ok: false, diagnostics: [normalizedOutput.diagnostic] };
+    const referenceId = buildExternalReferenceInstanceIdentity(imported.referenceRequestId);
+    const artifact = {
+        artifactKind: EXTERNAL_REFERENCE_ARTIFACT_KIND,
+        schemaVersion: EXTERNAL_REFERENCE_SCHEMA_VERSION,
+        referenceRequestId: imported.referenceRequestId,
+        referenceId,
+        producer: getProducerInfo(),
+        provenance: { importedAt: imported.provenance.importedAt, ...(imported.provenance.label === undefined ? {} : { label: imported.provenance.label }) },
+        sourceReference: {
+            referenceId: imported.referenceId,
+            referenceRequestId: imported.referenceRequestId,
+            producer: imported.producer,
+            schemaVersion: imported.schemaVersion,
+            image: imported.image,
+        },
+        lifecycle: { state: 'approved', approvedAt: new Date().toISOString() },
+        ...(supersedes.referenceId === undefined ? {} : { supersedesReferenceId: supersedes.referenceId }),
+        ...(imported.regions === undefined ? {} : { regions: imported.regions }),
+        ...(imported.requirements === undefined ? {} : { requirements: imported.requirements }),
+        ...(imported.applicability === undefined ? {} : { applicability: imported.applicability }),
+        diagnostics: [],
+        completion: deriveCompletion([], 'post-capture'),
+    };
+    const persisted = await writeExternalReferenceArtifact(artifact, undefined, normalizedOutput.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok)
+        return { ok: false, diagnostics: persisted.diagnostics };
+    return {
+        ok: true,
+        referenceId: artifact.referenceId,
+        referenceRequestId: artifact.referenceRequestId,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        regionCount: artifact.regions?.length ?? 0,
+        requirementCount: artifact.requirements?.length ?? 0,
+        adequacy: deriveReferenceRequirementAdequacy(artifact.regions ?? [], artifact.requirements ?? []),
+        hasApplicability: artifact.applicability !== undefined,
+    };
+}
+//# sourceMappingURL=externalReferencePersistenceService.js.map

package/dist/application/externalReferencePersistenceService.js.map

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