my-frontend-observer 0.4.0 → 0.5.0

package/dist/domain/frontendContracts.js

@@ -0,0 +1,260 @@
+import { isValidEvidenceReference, PAIRWISE_RELATIONSHIP_KINDS, PAGE_LEVEL_RELATIONSHIP_KINDS } from './relationships.js';
+import { DEPENDENCY_PROPERTIES } from './comparison.js';
+import { PRODUCER_NAME, SCHEMA_VERSION as OBSERVATION_SCHEMA_VERSION } from './schema.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isEvidenceReferenceArray(value) {
+    return Array.isArray(value) && value.every((entry) => isValidEvidenceReference(entry));
+}
+export const CONTRACT_ARTIFACT_KIND = 'my-frontend-observer/frontend-contract';
+export const CONTRACT_SCHEMA_VERSION = '1.0.0';
+// --- Change-scope vocabulary --------------------------------------------------
+/** The authored per-change contract has exactly these 4 intent categories - `'unexpected'` is never a member. */
+export const AUTHORED_CHANGE_SCOPE_CATEGORIES = ['requested', 'expected-dependent', 'protected', 'preserved'];
+export function isAuthoredChangeScopeCategory(value) {
+    return typeof value === 'string' && AUTHORED_CHANGE_SCOPE_CATEGORIES.includes(value);
+}
+/**
+ * Full derived classification vocabulary, kept structurally separate from
+ * AUTHORED_CHANGE_SCOPE_CATEGORIES - `'unexpected'` is a classification a
+ * future evaluator produces, never an authored permission. No function in
+ * this module converts between the two vocabularies.
+ */
+export const CHANGE_SCOPE_CLASSIFICATIONS = [...AUTHORED_CHANGE_SCOPE_CATEGORIES, 'unexpected'];
+export const EXPECTED_DEPENDENT_MODES = ['required', 'permitted'];
+export function isValidExpectedDependentMode(value) {
+    return typeof value === 'string' && EXPECTED_DEPENDENT_MODES.includes(value);
+}
+// --- Contract tolerance (bounded, closed - never a generic expression) -------
+/** Independently declared from GEOMETRY_TOLERANCE_*_PX (src/domain/relationships.ts): comparison tolerance suppresses insignificant geometry noise and is never contract authorization. */
+export const CONTRACT_TOLERANCE_ABSOLUTE_PX_MIN = 0;
+export const CONTRACT_TOLERANCE_ABSOLUTE_PX_MAX = 100;
+export const CONTRACT_TOLERANCE_PERCENT_MIN = 0;
+export const CONTRACT_TOLERANCE_PERCENT_MAX = 100;
+export function isValidContractTolerance(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (value.kind === 'exact')
+        return Object.keys(value).length === 1;
+    if (value.kind === 'absolute-px') {
+        return (typeof value.amount === 'number' &&
+            Number.isFinite(value.amount) &&
+            value.amount >= CONTRACT_TOLERANCE_ABSOLUTE_PX_MIN &&
+            value.amount <= CONTRACT_TOLERANCE_ABSOLUTE_PX_MAX);
+    }
+    if (value.kind === 'percent') {
+        return (typeof value.amount === 'number' &&
+            Number.isFinite(value.amount) &&
+            value.amount >= CONTRACT_TOLERANCE_PERCENT_MIN &&
+            value.amount <= CONTRACT_TOLERANCE_PERCENT_MAX);
+    }
+    return false;
+}
+// --- Contract primitive vocabulary (bounded, closed) --------------------------
+/** Every contract primitive kind this batch freezes - deliberately bounded, never a generic rule/expression language. */
+export const CONTRACT_PRIMITIVE_KINDS = [
+    'target-visible',
+    'target-not-clipped',
+    'target-width-within-bound',
+    'targets-do-not-overlap',
+    'target-wider-than',
+    'target-follows-vertically',
+    'target-fits-inside',
+    'document-width-fits-viewport',
+    'scroll-owner-is-document',
+    'target-does-not-own-scroll',
+    'target-begins-below-initial-viewport',
+    'relationship-unchanged',
+    'property-unchanged-within-tolerance',
+    'property-increases',
+    'property-decreases',
+];
+const ALL_RELATIONSHIP_KINDS = [...PAIRWISE_RELATIONSHIP_KINDS, ...PAGE_LEVEL_RELATIONSHIP_KINDS];
+function isOptionalFiniteNumber(value) {
+    return value === undefined || (typeof value === 'number' && Number.isFinite(value));
+}
+function isOptionalNonNegativeFiniteNumber(value) {
+    return value === undefined || (typeof value === 'number' && Number.isFinite(value) && value >= 0);
+}
+/** Rejects extra keys beyond the given allowlist, keeping every ContractPrimitive variant a closed shape rather than an open bag of fields. */
+function hasOnlyKeys(value, allowedKeys) {
+    return Object.keys(value).every((key) => allowedKeys.includes(key));
+}
+export function isValidContractPrimitive(value) {
+    if (!isPlainObject(value) || typeof value.kind !== 'string')
+        return false;
+    switch (value.kind) {
+        case 'target-visible':
+            return hasOnlyKeys(value, ['kind', 'target']) && isNonEmptyString(value.target);
+        case 'target-not-clipped':
+            return (hasOnlyKeys(value, ['kind', 'target', 'axis']) &&
+                isNonEmptyString(value.target) &&
+                (value.axis === undefined || value.axis === 'horizontal' || value.axis === 'vertical' || value.axis === 'both'));
+        case 'target-width-within-bound': {
+            if (!hasOnlyKeys(value, ['kind', 'target', 'minPx', 'maxPx']))
+                return false;
+            if (!isNonEmptyString(value.target))
+                return false;
+            if (!isOptionalFiniteNumber(value.minPx) || !isOptionalFiniteNumber(value.maxPx))
+                return false;
+            if (value.minPx === undefined && value.maxPx === undefined)
+                return false;
+            if (typeof value.minPx === 'number' && typeof value.maxPx === 'number' && value.minPx > value.maxPx)
+                return false;
+            return true;
+        }
+        case 'targets-do-not-overlap':
+        case 'target-wider-than':
+        case 'target-follows-vertically':
+            return (hasOnlyKeys(value, ['kind', 'targetA', 'targetB']) &&
+                isNonEmptyString(value.targetA) &&
+                isNonEmptyString(value.targetB) &&
+                value.targetA !== value.targetB);
+        case 'target-fits-inside':
+            return (hasOnlyKeys(value, ['kind', 'target', 'container']) &&
+                isNonEmptyString(value.target) &&
+                isNonEmptyString(value.container) &&
+                value.target !== value.container);
+        case 'document-width-fits-viewport':
+        case 'scroll-owner-is-document':
+            return hasOnlyKeys(value, ['kind']) && Object.keys(value).length === 1;
+        case 'target-does-not-own-scroll':
+        case 'target-begins-below-initial-viewport':
+            return hasOnlyKeys(value, ['kind', 'target']) && isNonEmptyString(value.target);
+        case 'relationship-unchanged':
+            return (hasOnlyKeys(value, ['kind', 'relationshipKind', 'subjectTarget', 'relatedTarget']) &&
+                typeof value.relationshipKind === 'string' &&
+                ALL_RELATIONSHIP_KINDS.includes(value.relationshipKind) &&
+                (value.subjectTarget === undefined || typeof value.subjectTarget === 'string') &&
+                (value.relatedTarget === undefined || typeof value.relatedTarget === 'string'));
+        case 'property-unchanged-within-tolerance':
+            return (hasOnlyKeys(value, ['kind', 'target', 'property', 'tolerance']) &&
+                isNonEmptyString(value.target) &&
+                typeof value.property === 'string' &&
+                DEPENDENCY_PROPERTIES.includes(value.property) &&
+                isValidContractTolerance(value.tolerance));
+        case 'property-increases':
+        case 'property-decreases':
+            return (hasOnlyKeys(value, ['kind', 'target', 'property', 'minimumDeltaPx']) &&
+                isNonEmptyString(value.target) &&
+                typeof value.property === 'string' &&
+                DEPENDENCY_PROPERTIES.includes(value.property) &&
+                isOptionalNonNegativeFiniteNumber(value.minimumDeltaPx));
+        default:
+            return false;
+    }
+}
+export function isValidBaselineClause(value) {
+    if (!isPlainObject(value))
+        return false;
+    return isNonEmptyString(value.clauseId) && isValidContractPrimitive(value.primitive) && isEvidenceReferenceArray(value.supportingEvidence);
+}
+export function isValidPerChangeClause(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (!isValidBaselineClause(value))
+        return false;
+    const record = value;
+    if (!isAuthoredChangeScopeCategory(record.category))
+        return false;
+    const hasMode = 'expectedDependentMode' in record && record.expectedDependentMode !== undefined;
+    if (record.category === 'expected-dependent') {
+        if (!hasMode || !isValidExpectedDependentMode(record.expectedDependentMode))
+            return false;
+    }
+    else if (hasMode) {
+        return false;
+    }
+    if ('supersedesBaselineClauseIds' in record && record.supersedesBaselineClauseIds !== undefined) {
+        const ids = record.supersedesBaselineClauseIds;
+        if (!Array.isArray(ids) || ids.length === 0)
+            return false;
+        if (!ids.every((id) => isNonEmptyString(id)))
+            return false;
+    }
+    return true;
+}
+export function isValidFrontendContractObservationReference(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (!isNonEmptyString(value.observationId) || !isNonEmptyString(value.requestId))
+        return false;
+    if (!isPlainObject(value.producer) || value.producer.name !== PRODUCER_NAME || !isNonEmptyString(value.producer.version))
+        return false;
+    return value.observationSchemaVersion === OBSERVATION_SCHEMA_VERSION;
+}
+export function isValidPersistentBaselineContract(value) {
+    if (!isPlainObject(value))
+        return { valid: false, reason: 'contract must be an object' };
+    if (value.artifactKind !== CONTRACT_ARTIFACT_KIND)
+        return { valid: false, reason: 'artifactKind mismatch' };
+    if (value.schemaVersion !== CONTRACT_SCHEMA_VERSION)
+        return { valid: false, reason: 'schemaVersion mismatch' };
+    if (value.contractClass !== 'baseline')
+        return { valid: false, reason: 'contractClass must be "baseline"' };
+    if (!isNonEmptyString(value.baselineId))
+        return { valid: false, reason: 'baselineId must be a non-empty string' };
+    if ('supersedesBaselineId' in value && value.supersedesBaselineId !== undefined && !isNonEmptyString(value.supersedesBaselineId)) {
+        return { valid: false, reason: 'supersedesBaselineId must be a non-empty string when present' };
+    }
+    if (!isValidFrontendContractObservationReference(value.sourceObservation))
+        return { valid: false, reason: 'sourceObservation is invalid' };
+    if (!Array.isArray(value.clauses) || !value.clauses.every((c) => isValidBaselineClause(c))) {
+        return { valid: false, reason: 'clauses must be an array of valid BaselineClause values' };
+    }
+    if (!isPlainObject(value.provenance) || !isNonEmptyString(value.provenance.approvedAt)) {
+        return { valid: false, reason: 'provenance.approvedAt must be a non-empty string' };
+    }
+    return { valid: true };
+}
+export function isValidPerChangeContract(value) {
+    if (!isPlainObject(value))
+        return { valid: false, reason: 'contract must be an object' };
+    if (value.artifactKind !== CONTRACT_ARTIFACT_KIND)
+        return { valid: false, reason: 'artifactKind mismatch' };
+    if (value.schemaVersion !== CONTRACT_SCHEMA_VERSION)
+        return { valid: false, reason: 'schemaVersion mismatch' };
+    if (value.contractClass !== 'change')
+        return { valid: false, reason: 'contractClass must be "change"' };
+    if (!isNonEmptyString(value.contractId))
+        return { valid: false, reason: 'contractId must be a non-empty string' };
+    if (!isNonEmptyString(value.contractRequestId))
+        return { valid: false, reason: 'contractRequestId must be a non-empty string' };
+    if (!Array.isArray(value.activeBaselineIds) || !value.activeBaselineIds.every((id) => isNonEmptyString(id))) {
+        return { valid: false, reason: 'activeBaselineIds must be an array of non-empty strings' };
+    }
+    if (!Array.isArray(value.clauses) || !value.clauses.every((c) => isValidPerChangeClause(c))) {
+        return { valid: false, reason: 'clauses must be an array of valid PerChangeClause values' };
+    }
+    return { valid: true };
+}
+// --- Per-clause evaluation result vocabulary (frozen vocabulary only; no producer in this batch) --
+export const CLAUSE_RESULT_STATUSES = ['pass', 'fail', 'unavailable', 'conflict'];
+/** Honest per-clause result vocabulary: `'unavailable'` requires a non-empty reason (never fabricated pass/fail); `'conflict'` requires at least 2 conflicting clause ids. */
+export function isValidClauseEvaluationResult(value) {
+    if (!isPlainObject(value) || !isNonEmptyString(value.clauseId))
+        return false;
+    if (!isEvidenceReferenceArray(value.supportingEvidence))
+        return false;
+    switch (value.status) {
+        case 'pass':
+        case 'fail':
+            return !('reason' in value) && !('conflictingClauseIds' in value);
+        case 'unavailable':
+            return isNonEmptyString(value.reason) && !('conflictingClauseIds' in value);
+        case 'conflict':
+            return (isNonEmptyString(value.reason) &&
+                Array.isArray(value.conflictingClauseIds) &&
+                value.conflictingClauseIds.length >= 2 &&
+                value.conflictingClauseIds.every((id) => isNonEmptyString(id)));
+        default:
+            return false;
+    }
+}
+// --- Overall verdict vocabulary (type only; no producer in this batch) -----------
+export const OVERALL_VERDICTS = ['PASS', 'FAIL'];
+//# sourceMappingURL=frontendContracts.js.map

package/dist/domain/frontendContracts.js.map

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

package/dist/index.d.ts

@@ -24,6 +24,28 @@ export { HORIZONTAL_ORDER_RELATIONSHIPS, VERTICAL_ORDER_RELATIONSHIPS, AREA_OVER
 export type { DependencyProperty, DependencyDirection, ExpectedDependencySource, DependencyTermDeclaration, ExpectedDependencyDeclaration, DependencyEvidenceOutcome, ExpectedDependencyEvidence, ComparisonConfig, ComparabilityState, ComparabilityReasonCode, ComparabilityReasonSeverity, ComparabilityReason, ComparabilityResult, TargetConfigurationChangeKind, TargetConfigurationChange, DifferenceKind, ComparisonDifferenceSubject, ComparisonDifference, RelationshipChangeRecord, ComparisonSourceObservationReference, ComparisonArtifact, ComparisonSchemaValidationResult, } from './domain/comparison.js';
 export { COMPARISON_ARTIFACT_KIND, COMPARISON_SCHEMA_VERSION, GEOMETRY_TOLERANCE_DEFAULT_PX, GEOMETRY_TOLERANCE_MIN_PX, GEOMETRY_TOLERANCE_MAX_PX, isValidGeometryTolerancePx, DEPENDENCY_PROPERTIES, DEPENDENCY_DIRECTIONS, EXPECTED_DEPENDENCY_SOURCES, isValidExpectedDependencyDeclaration, DEPENDENCY_EVIDENCE_OUTCOMES, isValidExpectedDependencyEvidence, isValidComparisonConfig, COMPARABILITY_STATES, COMPARABILITY_REASON_CODES, COMPARABILITY_REASON_SEVERITY, isValidComparabilityResult, TARGET_CONFIGURATION_CHANGE_KINDS, isValidTargetConfigurationChange, DIFFERENCE_KINDS, isValidComparisonDifference, isValidComparisonSourceObservationReference, isValidComparisonArtifact, } from './domain/comparison.js';
 export { buildComparisonRequestIdentity, buildComparisonIdentity } from './domain/comparisonIdentity.js';
+export type { AuthoredChangeScopeCategory, ChangeScopeClassification, ExpectedDependentMode, ContractTolerance, ContractPrimitiveKind, ContractPrimitive, FrontendContractClauseBase, BaselineClause, PerChangeClause, FrontendContractObservationReference, PersistentBaselineContract, FrontendContractValidationResult, PerChangeContract, ClauseResultStatus, ClauseEvaluationResult, OverallVerdict, } from './domain/frontendContracts.js';
+export { CONTRACT_ARTIFACT_KIND, CONTRACT_SCHEMA_VERSION, AUTHORED_CHANGE_SCOPE_CATEGORIES, isAuthoredChangeScopeCategory, CHANGE_SCOPE_CLASSIFICATIONS, EXPECTED_DEPENDENT_MODES, isValidExpectedDependentMode, CONTRACT_TOLERANCE_ABSOLUTE_PX_MIN, CONTRACT_TOLERANCE_ABSOLUTE_PX_MAX, CONTRACT_TOLERANCE_PERCENT_MIN, CONTRACT_TOLERANCE_PERCENT_MAX, isValidContractTolerance, CONTRACT_PRIMITIVE_KINDS, isValidContractPrimitive, isValidBaselineClause, isValidPerChangeClause, isValidFrontendContractObservationReference, isValidPersistentBaselineContract, isValidPerChangeContract, CLAUSE_RESULT_STATUSES, isValidClauseEvaluationResult, OVERALL_VERDICTS, } from './domain/frontendContracts.js';
+export { buildFrontendContractRequestIdentity, buildFrontendContractInstanceIdentity, buildClauseIdentity } from './domain/frontendContractIdentity.js';
+export type { FrontendContractEvaluationInput, UnexpectedChangeResult, FrontendContractEvaluationResult, EvaluateFrontendContractResult } from './domain/frontendContractEvaluation.js';
+export { evaluateFrontendContract } from './domain/frontendContractEvaluation.js';
+export { buildFrontendContractEvaluationRequestIdentity } from './domain/frontendContractIdentity.js';
+export type { FrontendContractEvaluationSourceReference, FrontendContractEvaluationArtifact, FrontendContractEvaluationArtifactValidationResult, BuildFrontendContractEvaluationArtifactInput, } from './domain/frontendContractEvaluationArtifact.js';
+export { EVALUATION_ARTIFACT_KIND, EVALUATION_SCHEMA_VERSION, isValidFrontendContractEvaluationArtifact, buildFrontendContractEvaluationArtifact, } from './domain/frontendContractEvaluationArtifact.js';
+export type { PersistedFrontendContractResult, WriteFrontendContractArtifactOptions } from './artifacts/frontendContractArtifactWriter.js';
+export { FRONTEND_CONTRACT_MANIFEST_FILENAME, writePersistentBaselineContract, writePerChangeContract } from './artifacts/frontendContractArtifactWriter.js';
+export type { ReadPersistentBaselineContractResult, ReadPerChangeContractResult } from './artifacts/frontendContractArtifactReader.js';
+export { readPersistentBaselineContract, readPerChangeContract } from './artifacts/frontendContractArtifactReader.js';
+export type { ReadComparisonArtifactResult } from './artifacts/comparisonArtifactReader.js';
+export { readComparisonArtifact } from './artifacts/comparisonArtifactReader.js';
+export type { PersistedFrontendContractEvaluationResult, WriteFrontendContractEvaluationArtifactOptions } from './artifacts/frontendContractEvaluationArtifactWriter.js';
+export { EVALUATION_MANIFEST_FILENAME, writeFrontendContractEvaluationArtifact } from './artifacts/frontendContractEvaluationArtifactWriter.js';
+export type { ReadFrontendContractEvaluationArtifactResult } from './artifacts/frontendContractEvaluationArtifactReader.js';
+export { readFrontendContractEvaluationArtifact } from './artifacts/frontendContractEvaluationArtifactReader.js';
+export type { EvaluateAndPersistOptions, ApplicationFrontendContractEvaluationResult } from './application/frontendContractEvaluationService.js';
+export { DEFAULT_EVALUATION_OUTPUT_LOCATION, evaluateAndPersist, evaluateAndPersistFromArtifactRoots } from './application/frontendContractEvaluationService.js';
+export type { PersistFrontendContractOptions, ApplicationApproveBaselineResult, ApplicationPersistChangeContractResult } from './application/frontendContractPersistenceService.js';
+export { approveAndPersistBaseline, persistPerChangeContract } from './application/frontendContractPersistenceService.js';
 export type { CompareObservationsResult } from './domain/comparisonEngine.js';
 export { compareObservations, evaluateComparability, evaluateExpectedDependencies, compareTargetConfiguration } from './domain/comparisonEngine.js';
 export type { PersistedComparisonResult, WriteComparisonArtifactOptions } from './artifacts/comparisonArtifactWriter.js';

package/dist/index.js

@@ -12,6 +12,18 @@ export { buildObservationArtifact, persistBrowserCapture, observe } from './appl
 export { HORIZONTAL_ORDER_RELATIONSHIPS, VERTICAL_ORDER_RELATIONSHIPS, AREA_OVERLAP_RELATIONSHIPS, RELATIVE_WIDTH_RELATIONSHIPS, GEOMETRIC_FIT_RELATIONSHIPS, VERTICAL_SEQUENCE_RELATIONSHIPS, PAGE_WIDTH_RELATIONSHIPS, PAIRWISE_RELATIONSHIP_KINDS, PAGE_LEVEL_RELATIONSHIP_KINDS, MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS, MAX_PAIRWISE_RELATIONSHIP_PAIRS, PAIRWISE_RELATIONSHIP_FAMILY_COUNT, MAX_PAIRWISE_RELATIONSHIP_RECORDS, CLIPPING_STATES, CLIPPING_OVERFLOW_STYLES, isValidEvidenceReference, isValidPairwiseLayoutRelationship, isValidPageLevelLayoutRelationship, isValidUnresolvedRelationshipTarget, isValidLayoutRelationshipGraph, isValidTargetClippingEvidence, deriveTargetClipping, deriveLayoutRelationships, } from './domain/relationships.js';
 export { COMPARISON_ARTIFACT_KIND, COMPARISON_SCHEMA_VERSION, GEOMETRY_TOLERANCE_DEFAULT_PX, GEOMETRY_TOLERANCE_MIN_PX, GEOMETRY_TOLERANCE_MAX_PX, isValidGeometryTolerancePx, DEPENDENCY_PROPERTIES, DEPENDENCY_DIRECTIONS, EXPECTED_DEPENDENCY_SOURCES, isValidExpectedDependencyDeclaration, DEPENDENCY_EVIDENCE_OUTCOMES, isValidExpectedDependencyEvidence, isValidComparisonConfig, COMPARABILITY_STATES, COMPARABILITY_REASON_CODES, COMPARABILITY_REASON_SEVERITY, isValidComparabilityResult, TARGET_CONFIGURATION_CHANGE_KINDS, isValidTargetConfigurationChange, DIFFERENCE_KINDS, isValidComparisonDifference, isValidComparisonSourceObservationReference, isValidComparisonArtifact, } from './domain/comparison.js';
 export { buildComparisonRequestIdentity, buildComparisonIdentity } from './domain/comparisonIdentity.js';
+export { CONTRACT_ARTIFACT_KIND, CONTRACT_SCHEMA_VERSION, AUTHORED_CHANGE_SCOPE_CATEGORIES, isAuthoredChangeScopeCategory, CHANGE_SCOPE_CLASSIFICATIONS, EXPECTED_DEPENDENT_MODES, isValidExpectedDependentMode, CONTRACT_TOLERANCE_ABSOLUTE_PX_MIN, CONTRACT_TOLERANCE_ABSOLUTE_PX_MAX, CONTRACT_TOLERANCE_PERCENT_MIN, CONTRACT_TOLERANCE_PERCENT_MAX, isValidContractTolerance, CONTRACT_PRIMITIVE_KINDS, isValidContractPrimitive, isValidBaselineClause, isValidPerChangeClause, isValidFrontendContractObservationReference, isValidPersistentBaselineContract, isValidPerChangeContract, CLAUSE_RESULT_STATUSES, isValidClauseEvaluationResult, OVERALL_VERDICTS, } from './domain/frontendContracts.js';
+export { buildFrontendContractRequestIdentity, buildFrontendContractInstanceIdentity, buildClauseIdentity } from './domain/frontendContractIdentity.js';
+export { evaluateFrontendContract } from './domain/frontendContractEvaluation.js';
+export { buildFrontendContractEvaluationRequestIdentity } from './domain/frontendContractIdentity.js';
+export { EVALUATION_ARTIFACT_KIND, EVALUATION_SCHEMA_VERSION, isValidFrontendContractEvaluationArtifact, buildFrontendContractEvaluationArtifact, } from './domain/frontendContractEvaluationArtifact.js';
+export { FRONTEND_CONTRACT_MANIFEST_FILENAME, writePersistentBaselineContract, writePerChangeContract } from './artifacts/frontendContractArtifactWriter.js';
+export { readPersistentBaselineContract, readPerChangeContract } from './artifacts/frontendContractArtifactReader.js';
+export { readComparisonArtifact } from './artifacts/comparisonArtifactReader.js';
+export { EVALUATION_MANIFEST_FILENAME, writeFrontendContractEvaluationArtifact } from './artifacts/frontendContractEvaluationArtifactWriter.js';
+export { readFrontendContractEvaluationArtifact } from './artifacts/frontendContractEvaluationArtifactReader.js';
+export { DEFAULT_EVALUATION_OUTPUT_LOCATION, evaluateAndPersist, evaluateAndPersistFromArtifactRoots } from './application/frontendContractEvaluationService.js';
+export { approveAndPersistBaseline, persistPerChangeContract } from './application/frontendContractPersistenceService.js';
 export { compareObservations, evaluateComparability, evaluateExpectedDependencies, compareTargetConfiguration } from './domain/comparisonEngine.js';
 export { COMPARISON_MANIFEST_FILENAME, writeComparisonArtifact } from './artifacts/comparisonArtifactWriter.js';
 export { readObservationArtifact } from './artifacts/artifactReader.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG3E,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGlG,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAmC1D,OAAO,EACL,aAAa,EACb,cAAc,EACd,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAetF,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGzH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAG3E,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEvF,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAwBnH,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,0BAA0B,EAC1B,4BAA4B,EAC5B,2BAA2B,EAC3B,+BAA+B,EAC/B,wBAAwB,EACxB,2BAA2B,EAC3B,6BAA6B,EAC7B,wCAAwC,EACxC,+BAA+B,EAC/B,kCAAkC,EAClC,iCAAiC,EACjC,eAAe,EACf,wBAAwB,EACxB,wBAAwB,EACxB,iCAAiC,EACjC,kCAAkC,EAClC,mCAAmC,EACnC,8BAA8B,EAC9B,6BAA6B,EAC7B,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AA0BnC,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,EACzB,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EACrB,2BAA2B,EAC3B,oCAAoC,EACpC,4BAA4B,EAC5B,iCAAiC,EACjC,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,6BAA6B,EAC7B,0BAA0B,EAC1B,iCAAiC,EACjC,gCAAgC,EAChC,gBAAgB,EAChB,2BAA2B,EAC3B,2CAA2C,EAC3C,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,8BAA8B,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAGzG,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAGpJ,OAAO,EAAE,4BAA4B,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAGhH,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,kCAAkC,EAAE,iBAAiB,EAAE,kCAAkC,EAAE,MAAM,oCAAoC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/docs/ARCHITECTURE.md

@@ -3,7 +3,7 @@
 ## Current scaffold architecture
 
 The current repository is one published TypeScript ESM package
-(`my-frontend-observer@0.4.0`):
+(`my-frontend-observer@0.5.0`):
 
 - `src/cli.ts` is the real, thin `observe` command entry point (argument
   parsing/output only).
@@ -181,6 +181,103 @@ path never launches Chromium** - `src/cli.ts` imports nothing from
 reading indirectly, through the application-layer seam above), matching the
 same import-boundary discipline already enforced for `observe`.
 
+## Current v0.5 architecture (released/current architecture)
+
+v0.5 adds one new downstream layer that consumes `ComparisonArtifact` values
+(plus the source `ObservationArtifact` pair) rather than producing them - no
+new browser lifecycle, target resolver, or comparison engine is added:
+
+```text
+ObservationArtifact before + after
+              ↓
+existing v0.4 comparison/relationship pipeline (unchanged)
+              ↓
+        ComparisonArtifact
+              ↓                                PersistentBaselineContract
+              |                                          +
+              `------------------------→   PerChangeContract
+                                                          ↓
+                        canonical contract evaluation
+                        (src/domain/frontendContractEvaluation.ts#evaluateFrontendContract)
+                                                          ↓
+                        clause results + unexpected changes + overall PASS/FAIL
+```
+
+`src/domain/frontendContracts.ts` froze the contract/change-scope type,
+constant, and structural-validator vocabulary (Batch 1); `src/domain/
+frontendContractIdentity.ts` froze deterministic contract/baseline/clause
+identity in the same canonicalize+sha256(+opaque-nonce) style as `src/domain/
+comparisonIdentity.ts`. `src/domain/frontendContractEvaluation.ts#evaluateFrontendContract`
+(Batch 2) is the one canonical pure evaluation entry point: it validates its
+five inputs (before/after `ObservationArtifact`, `ComparisonArtifact`,
+`PersistentBaselineContract`, `PerChangeContract`) are structurally coherent
+and mutually consistent, calculates the active baseline clause set after
+explicit supersession, detects bounded structural conflicts, evaluates every
+active clause via the frozen 15-primitive vocabulary against the existing
+`ComparisonArtifact`/`ObservationArtifact` evidence (never re-deriving
+clipping/relationship/scroll-owner facts), classifies unaccounted-for
+`ComparisonArtifact.differences` entries as `unexpected`, and derives one
+overall `PASS`/`FAIL` verdict. It performs no I/O, launches no browser, and
+persists nothing - `src/domain/frontendContractEvaluation.ts` itself remains
+untouched by the persistence layer below (Batch 3).
+
+Batch 3 adds the persistence/application boundary around this frozen domain,
+without redefining it:
+
+```text
+        ComparisonArtifact (read via new src/artifacts/comparisonArtifactReader.ts)
+              +
+PersistentBaselineContract / PerChangeContract
+(read/written via src/artifacts/frontendContractArtifactReader.ts / ...Writer.ts)
+              ↓
+src/application/frontendContractEvaluationService.ts#evaluateAndPersist
+              ↓
+    evaluateFrontendContract()  [called exactly once, unmodified]
+              ↓
+src/domain/frontendContractEvaluationArtifact.ts
+    (minimal additive persisted envelope around the frozen result)
+              ↓
+src/artifacts/frontendContractEvaluationArtifactWriter.ts
+    (atomic write, exactly once on a structurally constructible result)
+```
+
+`evaluateAndPersistFromArtifactRoots` is the CLI-facing wrapper, reading
+before/after observations through the existing `readObservationArtifact` (no
+second observation reader), the comparison and both contract classes
+through the new readers, then delegating to `evaluateAndPersist` exactly
+once - mirroring `application/comparisonService.ts#compareAndPersistFromArtifactRoots`'s
+own thin-wrapper shape.
+
+Batch 4 exposes this through the same thin-CLI boundary already established
+by `observe`/`compare`:
+
+```text
+src/cli.ts (argument parsing, JSON-file-shape checks, help/output formatting,
+            exit-code selection only)
+        ↓
+src/application/frontendContractPersistenceService.ts#approveAndPersistBaseline
+src/application/frontendContractPersistenceService.ts#persistPerChangeContract
+src/application/frontendContractEvaluationService.ts#evaluateAndPersistFromArtifactRoots
+        ↓
+domain validators (isValidPersistentBaselineContract / isValidPerChangeContract)
++ artifact readers/writers (Batch 3)
++ evaluateFrontendContract() (Batch 2, unmodified)
+```
+
+Three new top-level commands - `approve-baseline`, `save-change-contract`,
+`evaluate-contract` - each parse only CLI-syntax concerns (duplicate/missing
+flags, JSON-file readability/parseability/object-root shape) and delegate to
+exactly one application-layer call; `src/cli.ts` imports no artifact writer/
+reader module and no browser code, matching the existing `observe`/`compare`
+import-boundary discipline exactly. `approveAndPersistBaseline` adds the one
+new coherence check Batch 3 did not need: verifying a baseline contract's
+frozen `sourceObservation` reference actually matches the supplied
+observation artifact before persisting - explicit approval only, never
+inferred from a `compare` or `evaluate-contract` result. `--enforce` on
+`evaluate-contract` is applied only after evaluation and persistence have
+already completed; it selects the process exit status for an already-final
+`FAIL` result and is never part of any identity or persisted field.
+
 ## Planned v0.1 architecture constraints
 
 v0.1 planning must preserve these approved boundaries without treating module

package/docs/CI_CD.md

@@ -96,3 +96,50 @@ observations. This preserves every pre-existing v0.1-v0.3 packed
 observation proof unchanged and adds the v0.4 proof additively, in the same
 script and the same candidate, per the established same-candidate
 architecture (no second `npm pack`, no per-platform rebuild).
+
+## v0.5 readiness coverage
+
+The packed-readiness coverage gap identified during the v0.5 implementation-
+completeness audit as `V0_5_READINESS_VALIDATION_GAP_EXISTS` - the packed
+candidate smoke exercised `observe`/`compare` but not `approve-baseline`/
+`save-change-contract`/`evaluate-contract` - has been **corrected locally**:
+`scripts/ci/runPackedObservationSmoke.mjs` now also installs the same
+candidate tarball, observes a deterministic navigation/workspace/rail
+fixture through the installed `observe`, and drives the complete installed
+`approve-baseline` → `save-change-contract` → `observe` (candidate) →
+`compare` → `evaluate-contract` sequence, proving both a fully successful
+contract change (overall `PASS`, `--enforce` still exits `0`) and the
+milestone-signature failure (a locally successful requested/expected-
+dependent change alongside a real protected right-rail regression and a
+real preserved navigation-clipping regression, overall `FAIL`) - including
+`--enforce` producing a nonzero exit for the identical `FAIL` evidence
+(`evaluationRequestId` and `clauseResults` unchanged), full source
+observation/comparison/contract-artifact immutability, no copied
+screenshots, and no repository-root artifact leakage. All product behavior
+under test is invoked through the installed tarball's own executable, never
+imported from the source checkout. This addition is exercised in every
+existing matrix lane (`windows-latest`, `ubuntu-latest`, `macos-latest`)
+because all three already invoke this same script against the same
+candidate tarball - no workflow YAML change was required.
+
+This correction has since been proven cross-platform on the validation
+branch `validation/v0.5-pre-release`, first tested at commit
+`90255a9175503664f3e65d4114ee205176b7040a`: GitHub Actions run
+[`31727856546`](https://github.com/dailephd/my-frontend-observer/actions/runs/31727856546)
+passed completely - the candidate job (Linux, Node 24) and all three
+`matrix-smoke` lanes (`windows-latest` Node v24.18.1, `ubuntu-latest` Node
+v24.19.0, `macos-latest` Node v24.18.0) - using one shared candidate
+tarball, `my-frontend-observer-0.4.0.tgz`, SHA-256
+`9533a53e475614cd80a29dfa8b0f85e533e3ad736596579f559479e90e78941a`,
+independently hash-verified by each of the three matrix lanes before any of
+them ran the smoke (no lane built its own tarball). Every lane's
+`smoke-summary.json` reported byte-identical v0.5 evidence: the installed
+candidate's `approve-baseline`/`save-change-contract`/`evaluate-contract`
+`--help` all present, a real successful contract change (overall `PASS`,
+`--enforce` exits `0`), and the real milestone-signature failure (requested/
+expected-dependent `pass`, protected/preserved `fail`, overall `FAIL`,
+identical `evaluationRequestId`/`clauseResults` with `--enforce` exiting `1`
+and without it exiting `0`), plus source-artifact immutability, no copied
+screenshot, no path leakage, and no repository-root leakage - alongside
+every pre-existing v0.1-v0.4 packed observe/compare/scroll assertion, still
+passing unchanged on all three platforms.