@dailephd/my-frontend-observer 0.8.1

package/dist/domain/scrollEvidence.js

@@ -0,0 +1,134 @@
+/**
+ * Derived only from a bounding rectangle (viewport-relative, as produced by
+ * `getBoundingClientRect()`) plus viewport width/height - never from source
+ * styles or locator kind (Batch 1 frozen contract). `above`/`below` require
+ * the rectangle to be *entirely* outside the viewport on that axis; any
+ * vertical overlap with `[0, viewport.height)` is `intersecting`.
+ */
+export function deriveViewportRelation(rect, viewport) {
+    const vertical = rect.bottom <= 0 ? 'above' : rect.y >= viewport.height ? 'below' : 'intersecting';
+    const intersectsViewport = rect.right > 0 && rect.x < viewport.width && rect.bottom > 0 && rect.y < viewport.height;
+    const fullyWithinViewport = rect.x >= 0 && rect.y >= 0 && rect.right <= viewport.width && rect.bottom <= viewport.height;
+    return { vertical, intersectsViewport, fullyWithinViewport };
+}
+/**
+ * Distinguishes a computed `overflow-x`/`overflow-y` CSS declaration from
+ * actual dimensional overflow. `overflow-x: auto`/`overflow-y: scroll` alone
+ * never implies actual overflow - only `scrollWidth > clientWidth` /
+ * `scrollHeight > clientHeight` do.
+ */
+export function deriveOverflowEvidence(metrics, overflowX, overflowY) {
+    return {
+        horizontalOverflow: metrics.scrollWidth > metrics.clientWidth,
+        verticalOverflow: metrics.scrollHeight > metrics.clientHeight,
+        overflowX,
+        overflowY,
+    };
+}
+function numberChange(before, after) {
+    return { before, after, changed: before !== after };
+}
+function extractAvailable(field) {
+    return field.state === 'available' || field.state === 'partial' ? field.value : undefined;
+}
+/**
+ * Bounded before/after change evidence for one configured target across the
+ * one scroll action - not a generic recursive diff. Returns `undefined`
+ * (rather than fabricating zeroed/default values) when either snapshot's
+ * metrics/boundingRect/viewportRelation evidence for this target is not
+ * itself usable (e.g. the target never resolved), consistent with
+ * `enteredViewport`/`leftViewport` only being evaluated when both
+ * viewport-relation states are valid.
+ */
+export function deriveTargetScrollTransition(initial, final) {
+    const initialMetrics = extractAvailable(initial.metrics);
+    const finalMetrics = extractAvailable(final.metrics);
+    const initialRect = extractAvailable(initial.boundingRect);
+    const finalRect = extractAvailable(final.boundingRect);
+    const initialRelation = extractAvailable(initial.viewportRelation);
+    const finalRelation = extractAvailable(final.viewportRelation);
+    if (!initialMetrics || !finalMetrics || !initialRect || !finalRect || !initialRelation || !finalRelation) {
+        return undefined;
+    }
+    const enteredViewport = !initialRelation.intersectsViewport && finalRelation.intersectsViewport;
+    const leftViewport = initialRelation.intersectsViewport && !finalRelation.intersectsViewport;
+    return {
+        scrollTop: numberChange(initialMetrics.scrollTop, finalMetrics.scrollTop),
+        scrollLeft: numberChange(initialMetrics.scrollLeft, finalMetrics.scrollLeft),
+        boundingRectPosition: {
+            before: { x: initialRect.x, y: initialRect.y },
+            after: { x: finalRect.x, y: finalRect.y },
+            changed: initialRect.x !== finalRect.x || initialRect.y !== finalRect.y,
+        },
+        viewportRelation: { before: initialRelation.vertical, after: finalRelation.vertical, changed: initialRelation.vertical !== finalRelation.vertical },
+        enteredViewport,
+        leftViewport,
+    };
+}
+/** Derives the bounded scenario transition evidence purely from the two already-captured runtime snapshots - no re-measurement, no generic JSON diffing. A target absent from either snapshot's `targets` map, or whose per-target transition cannot be derived (see `deriveTargetScrollTransition`), is simply omitted from `targets` here. */
+export function deriveScrollScenarioTransition(initial, final) {
+    const targets = {};
+    for (const [name, initialState] of Object.entries(initial.targets)) {
+        const finalState = final.targets[name];
+        if (!finalState)
+            continue;
+        const transition = deriveTargetScrollTransition(initialState, finalState);
+        if (transition)
+            targets[name] = transition;
+    }
+    return {
+        windowScrollX: numberChange(initial.window.scrollX, final.window.scrollX),
+        windowScrollY: numberChange(initial.window.scrollY, final.window.scrollY),
+        targets,
+    };
+}
+/**
+ * Conservative scroll-owner derivation, shared by both `window-scroll-by`
+ * and `target-scroll-by` scenarios: relies solely on observed scroll
+ * *position* changes (`scrollTop`/`scrollLeft`/`window.scrollX`/
+ * `window.scrollY`), never on a target's bounding-rectangle movement (which
+ * moves for every configured target whenever the document scrolls,
+ * regardless of who "owns" scrolling - using it here would falsely
+ * attribute document scrolling to every visible target) and never on
+ * computed overflow, `position: fixed`/`sticky`, target name, locator kind,
+ * or DOM hierarchy.
+ *
+ * Rules (frozen Batch 1 vocabulary):
+ * - no window movement, no target movement -> `none`;
+ * - window movement, no competing target movement -> `document`;
+ * - no window movement, exactly one target's own scroll position moved
+ *   (on either or both axes - two axes of the *same* target is still one
+ *   owner) -> `target:<name>`;
+ * - anything else (window plus a target, or more than one target) ->
+ *   `indeterminate` - multiple plausible owners, never forced to pick one.
+ */
+export function deriveScrollOwner(transition) {
+    const windowMoved = transition.windowScrollX.changed || transition.windowScrollY.changed;
+    const changedTargetNames = Object.entries(transition.targets)
+        .filter(([, t]) => t.scrollTop.changed || t.scrollLeft.changed)
+        .map(([name]) => name);
+    let value;
+    let derivedFrom;
+    if (!windowMoved && changedTargetNames.length === 0) {
+        value = { kind: 'none' };
+        derivedFrom = ['window.scrollX', 'window.scrollY', ...Object.keys(transition.targets).flatMap((name) => [`${name}.scrollTop`, `${name}.scrollLeft`])];
+    }
+    else if (windowMoved && changedTargetNames.length === 0) {
+        value = { kind: 'document' };
+        derivedFrom = ['window.scrollX', 'window.scrollY'];
+    }
+    else if (!windowMoved && changedTargetNames.length === 1) {
+        const target = changedTargetNames[0];
+        value = { kind: 'target', target };
+        derivedFrom = [`${target}.scrollTop`, `${target}.scrollLeft`];
+    }
+    else {
+        value = { kind: 'indeterminate' };
+        derivedFrom = [
+            ...(windowMoved ? ['window.scrollX', 'window.scrollY'] : []),
+            ...changedTargetNames.flatMap((name) => [`${name}.scrollTop`, `${name}.scrollLeft`]),
+        ];
+    }
+    return { state: 'available', source: 'derived', value, derivedFrom };
+}
+//# sourceMappingURL=scrollEvidence.js.map

package/dist/domain/scrollEvidence.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+export type { EvidenceState, EvidenceSource, EvidenceField } from './domain/evidence.js';
+export { isValidEvidenceField, evidenceValue } from './domain/evidence.js';
+export type { DiagnosticCode, DiagnosticSeverity, Diagnostic } from './domain/diagnostics.js';
+export { DIAGNOSTIC_CODES, DIAGNOSTIC_SEVERITY, orderDiagnostics } from './domain/diagnostics.js';
+export type { CompletionState, RequestPhase } from './domain/completion.js';
+export { deriveCompletion } from './domain/completion.js';
+export type { ObservationArtifact, ArtifactReference, TargetEvidenceRecord, TargetGeometry, TargetComputedStyle, TargetLayoutMetrics, TargetVisibility, TargetSemantics, TargetLocatorKind, TargetSelectionStatus, TargetSelectionConfidence, TargetLocatorAttemptStatus, TargetLocatorAttempt, TargetResolution, TargetSemanticState, TargetLandmarkRole, TargetContainment, SchemaValidationResult, ScrollableMetrics, OverflowEvidence, WindowScrollSnapshot, DocumentScrollSnapshot, VerticalViewportRelation, ViewportRelationEvidence, TargetScrollRuntimeState, ScrollRuntimeSnapshot, ScrollValueChange, TargetScrollTransition, ScrollScenarioTransition, ScrollOwnerInterpretation, ScrollScenarioEvidence, } from './domain/schema.js';
+export { ARTIFACT_KIND, SCHEMA_VERSION, PRODUCER_NAME, TARGET_LANDMARK_ROLES, getProducerInfo, isValidObservationArtifact, } from './domain/schema.js';
+export { buildRequestIdentity, buildObservationIdentity } from './domain/identity.js';
+export type { NamedTarget, RawNamedTarget, TargetLocator, Viewport, ReadinessCondition, ReadinessConfig, NormalizedObservationRequest, RawObservationRequest, NormalizeRequestResult, ScrollAction, ScrollScenario, } from './request/request.js';
+export { normalizeRequest, SCROLL_DELTA_MAX_ABS } from './request/request.js';
+export type { NormalizeOutputLocationResult } from './request/paths.js';
+export { normalizeOutputLocation } from './request/paths.js';
+export type { SafetyDecision } from './safety/policy.js';
+export { classifyUrl, classifyRedirect, classifySubresource, classifyPopup, classifyDownload } from './safety/policy.js';
+export type { BrowserCaptureResult, BrowserProvenance } from './browser/types.js';
+export { runBrowserCapture } from './application/browserCaptureService.js';
+export type { PersistedObservationResult } from './artifacts/types.js';
+export { MANIFEST_FILENAME, SCREENSHOT_FILENAME } from './artifacts/artifactWriter.js';
+export type { ApplicationObservationResult } from './application/observationPersistence.js';
+export { buildObservationArtifact, persistBrowserCapture, observe } from './application/observationPersistence.js';
+export type { HorizontalOrderRelationship, VerticalOrderRelationship, AreaOverlapRelationship, RelativeWidthRelationship, GeometricFitRelationship, VerticalSequenceRelationship, PageWidthRelationship, PairwiseRelationshipKind, PageLevelRelationshipKind, EvidenceReference, PairwiseLayoutRelationship, PageLevelLayoutRelationship, UnresolvedTargetReason, UnresolvedRelationshipTarget, LayoutRelationshipGraph, ClippingState, ClippingOverflowStyle, TargetClippingEvidence, DeriveLayoutRelationshipsOptions, DeriveLayoutRelationshipsResult, } from './domain/relationships.js';
+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 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, TargetPresence } from './domain/comparisonEngine.js';
+export { compareObservations, evaluateComparability, evaluateExpectedDependencies, compareTargetConfiguration, assessOptionalComparabilityDimension, targetPresence, } from './domain/comparisonEngine.js';
+export type { ProjectionProfile, AdequacyState, AdequacyReasonCode, AdequacyReason, Adequacy, OmissionReason, OmissionRecord, TruncationRecord, BoundedAgentContextSourceReferences, BoundedRuntimeTargetProjection, CorrelationStatus, StaticCandidateKind, StaticEvidenceProducerIdentity, StaticCandidateReference, RuntimeStaticCorrelationRecord, BoundedAgentContextArtifact, BoundedAgentContextValidationResult, BoundedReferenceFidelityProjection, } from './domain/boundedAgentContext.js';
+export { BOUNDED_AGENT_CONTEXT_ARTIFACT_KIND, BOUNDED_AGENT_CONTEXT_SCHEMA_VERSION, PROJECTION_PROFILES, MAX_RUNTIME_TARGETS, MAX_RELATIONSHIP_EVIDENCE_PER_TARGET, MAX_OMISSIONS, MAX_TRUNCATIONS, MAX_CORRELATION_RECORDS, MAX_STATIC_CANDIDATES_PER_TARGET, MAX_TEXT_SUMMARY_CHARS, MAX_EVIDENCE_REFS_PER_CORRELATION_FIELD, MAX_FIDELITY_MISMATCHES, MAX_FIDELITY_PROTECTED_CONTEXT, ADEQUACY_STATES, ADEQUACY_REASON_CODES, OMISSION_REASONS, CORRELATION_STATUSES, STATIC_CANDIDATE_KINDS, isValidBoundedAgentContextArtifact, isValidBoundedReferenceFidelityProjection, } from './domain/boundedAgentContext.js';
+export { buildBoundedAgentContextRequestIdentity, buildBoundedAgentContextInstanceIdentity } from './domain/boundedAgentContextIdentity.js';
+export type { ProjectBoundedAgentContextInput, ProjectBoundedAgentContextResult } from './domain/boundedAgentContextProjection.js';
+export { projectBoundedAgentContext } from './domain/boundedAgentContextProjection.js';
+export type { ProjectReferenceFidelityOptions, ProjectReferenceFidelityOutput } from './domain/referenceFidelityProjection.js';
+export { projectReferenceFidelity } from './domain/referenceFidelityProjection.js';
+export type { StaticCandidateEvidenceInput, CorrelationTargetInput, DeriveRuntimeStaticCorrelationsInput, DeriveRuntimeStaticCorrelationsOutput, DeriveRuntimeStaticCorrelationsResult, AttachRuntimeStaticCorrelationsResult, } from './domain/boundedAgentContextCorrelation.js';
+export { deriveRuntimeStaticCorrelations, attachRuntimeStaticCorrelations } from './domain/boundedAgentContextCorrelation.js';
+export type { PersistedComparisonResult, WriteComparisonArtifactOptions } from './artifacts/comparisonArtifactWriter.js';
+export { COMPARISON_MANIFEST_FILENAME, writeComparisonArtifact } from './artifacts/comparisonArtifactWriter.js';
+export type { ReadObservationArtifactResult } from './artifacts/artifactReader.js';
+export { readObservationArtifact } from './artifacts/artifactReader.js';
+export type { CompareAndPersistOptions, ApplicationComparisonResult } from './application/comparisonService.js';
+export { DEFAULT_COMPARISON_OUTPUT_LOCATION, compareAndPersist, compareAndPersistFromArtifactRoots } from './application/comparisonService.js';
+export type { ExternalReferenceImageFormat, ImageDimensions } from './domain/externalReferenceImage.js';
+export { EXTERNAL_REFERENCE_SUPPORTED_IMAGE_FORMATS, isExternalReferenceImageFormat, EXTERNAL_REFERENCE_MAX_IMAGE_BYTES, EXTERNAL_REFERENCE_MIN_DIMENSION_PX, EXTERNAL_REFERENCE_MAX_DIMENSION_PX, detectExternalReferenceImageFormat, readExternalReferenceImageDimensions, isValidExternalReferenceImageDimensions, fileExtensionForFormat, } from './domain/externalReferenceImage.js';
+export type { ExternalReferenceImageReference, ExternalReferenceSourceReference, ExternalReferenceLifecycleState, ExternalReferenceProvenance, ImportedExternalReferenceArtifact, ApprovedExternalReferenceArtifact, ExternalReferenceArtifact, ExternalReferenceValidationResult, } from './domain/externalReference.js';
+export { EXTERNAL_REFERENCE_ARTIFACT_KIND, EXTERNAL_REFERENCE_SCHEMA_VERSION, isValidExternalReferenceImageReference, isValidExternalReferenceSourceReference, isValidExternalReferenceLifecycleState, isValidExternalReferenceProvenance, isValidExternalReferenceArtifact, isImportedExternalReferenceArtifact, isApprovedExternalReferenceArtifact, } from './domain/externalReference.js';
+export { buildExternalReferenceRequestIdentity, buildExternalReferenceInstanceIdentity } from './domain/externalReferenceIdentity.js';
+export type { PersistedExternalReferenceResult, WriteExternalReferenceArtifactOptions } from './artifacts/externalReferenceArtifactWriter.js';
+export { EXTERNAL_REFERENCE_MANIFEST_FILENAME, writeExternalReferenceArtifact } from './artifacts/externalReferenceArtifactWriter.js';
+export type { ReadExternalReferenceArtifactResult } from './artifacts/externalReferenceArtifactReader.js';
+export { readExternalReferenceArtifact } from './artifacts/externalReferenceArtifactReader.js';
+export type { ImportExternalReferenceOptions, ApproveExternalReferenceOptions, ApplicationImportExternalReferenceResult, ApplicationApproveExternalReferenceResult, } from './application/externalReferencePersistenceService.js';
+export { importExternalReference, approveExternalReference } from './application/externalReferencePersistenceService.js';
+export type { ReferenceRegionRectangle, ReferenceRegion, ReferenceRegionGeometry, ReferenceRegionValidationResult } from './domain/externalReferenceRegions.js';
+export { REFERENCE_REGION_ID_PATTERN, MAX_REFERENCE_REGIONS, deriveReferenceRegionGeometry, isValidReferenceRegionRectangle, isValidReferenceRegion, isValidReferenceRegions, } from './domain/externalReferenceRegions.js';
+export type { ReferenceRegionRelationship, ReferenceRegionRelationshipGraph, DeriveReferenceRegionRelationshipsOptions, DeriveReferenceRegionRelationshipsResult, } from './domain/externalReferenceRegionRelationships.js';
+export { MAX_REFERENCE_REGION_PAIRS, REFERENCE_REGION_RELATIONSHIP_FAMILY_COUNT, MAX_REFERENCE_REGION_RELATIONSHIP_RECORDS, isValidReferenceRegionRelationship, isValidReferenceRegionRelationshipGraph, deriveReferenceRegionRelationships, } from './domain/externalReferenceRegionRelationships.js';
+export { buildReferenceRequirementIdentity } from './domain/externalReferenceRequirementIdentity.js';
+export type { ReferenceRequirementRegionProperty, ReferenceRequirementMeasurement, ReferenceRequirementTolerance, RegionPropertyRequirementSubject, RegionRelationshipRequirementSubject, RegionMeasurementRequirementSubject, ReferenceRequirementSubject, RawReferenceRequirement, ExternalReferenceRequirement, ReferenceRequirementValidationResult, ReferenceRequirementExpectation, ReferenceRequirementAdequacyState, ReferenceRequirementAdequacyReasonCode, ReferenceRequirementAdequacyReason, ReferenceRequirementAdequacy, } from './domain/externalReferenceRequirements.js';
+export { MAX_REFERENCE_REQUIREMENTS, REFERENCE_REQUIREMENT_REGION_PROPERTIES, isReferenceRequirementRegionProperty, REFERENCE_REQUIREMENT_MEASUREMENTS, isReferenceRequirementMeasurement, deriveReferenceRequirementMeasurement, REFERENCE_REQUIREMENT_TOLERANCE_ABSOLUTE_PX_MIN, REFERENCE_REQUIREMENT_TOLERANCE_ABSOLUTE_PX_MAX, REFERENCE_REQUIREMENT_TOLERANCE_PERCENT_MIN, REFERENCE_REQUIREMENT_TOLERANCE_PERCENT_MAX, isValidReferenceRequirementTolerance, isValidReferenceRequirementSubjectShape, isValidRawReferenceRequirement, buildReferenceRequirement, isValidReferenceRequirementShape, isValidReferenceRequirements, deriveReferenceRequirementExpectation, REFERENCE_REQUIREMENT_ADEQUACY_STATES, REFERENCE_REQUIREMENT_ADEQUACY_REASON_CODES, deriveReferenceRequirementAdequacy, isValidReferenceRequirementAdequacy, } from './domain/externalReferenceRequirements.js';
+export type { AuthenticatedState, ExplicitStateDimensions, ExplicitStateValidationResult } from './domain/explicitState.js';
+export { STATE_LABEL_PATTERN, AUTHENTICATED_STATE_VALUES, isValidStateLabel, isValidAuthenticatedState, isValidExplicitStateDimensions, } from './domain/explicitState.js';
+export type { ApplicableViewport, ExternalReferenceApplicability, ApplicabilityValidationResult } from './domain/externalReferenceApplicability.js';
+export { APPLICABLE_VIEWPORT_MIN, APPLICABLE_VIEWPORT_MAX, isValidApplicableViewport, isValidExternalReferenceApplicability, } from './domain/externalReferenceApplicability.js';
+export type { ReferenceCandidateCompatibilityResult } from './domain/externalReferenceCompatibility.js';
+export { evaluateReferenceCandidateCompatibility } from './domain/externalReferenceCompatibility.js';
+export type { ReferenceRuntimeBindingStatus, ReferenceRuntimeBindingReasonCode, ReferenceRuntimeBindingDeclaration, ReferenceRuntimeBindingValidationResult, ReferenceRuntimeBindingResult, ReferenceRuntimeBindingEvaluation, EvaluateReferenceRuntimeBindingsResult, } from './domain/externalReferenceRuntimeBinding.js';
+export { RUNTIME_TARGET_NAME_PATTERN, MAX_REFERENCE_RUNTIME_BINDINGS, REFERENCE_RUNTIME_BINDING_STATUSES, REFERENCE_RUNTIME_BINDING_REASON_CODES, isValidReferenceRuntimeBindingDeclarations, evaluateReferenceRuntimeBindings, } from './domain/externalReferenceRuntimeBinding.js';
+export type { ReferenceRequirementFidelityStatus, ReferenceRequirementFidelityReasonCode, ReferenceRequirementFidelityResult, ReferenceFidelityState, ReferenceFidelityBlockReason, ReferenceCandidateFidelityEvaluation, EvaluateReferenceCandidateFidelityResult, EvaluateReferenceCandidateFidelityOptions, } from './domain/externalReferenceFidelity.js';
+export { REFERENCE_REQUIREMENT_FIDELITY_STATUSES, REFERENCE_REQUIREMENT_FIDELITY_REASON_CODES, REFERENCE_FIDELITY_STATES, REFERENCE_FIDELITY_BLOCK_REASONS, evaluateReferenceCandidateFidelity, isValidReferenceRequirementFidelityResult, } from './domain/externalReferenceFidelity.js';
+export type { EvaluateReferenceFidelityOptions, ApplicationReferenceFidelityResult } from './application/referenceFidelityEvaluationService.js';
+export { evaluateReferenceCandidateFidelityFromArtifactRoots } from './application/referenceFidelityEvaluationService.js';
+export { buildReferenceCorrectionReviewIdentity, buildReferenceCorrectionAttemptIdentity } from './domain/referenceCorrectionIdentity.js';
+export { DEFAULT_VIEWER_PORT, VIEWER_HOST, isValidViewerPort } from './viewerServer/port.js';
+export type { StartViewerOptions, StartViewerResult, ViewerAliasMetadata } from './viewerServer/viewerService.js';
+export { startViewer, defaultViewerAssetsRoot } from './viewerServer/viewerService.js';
+export type { FrontendObserverProjectConfig, ProjectConfigReadResult } from './projectWorkflow/projectConfig.js';
+export { PROJECT_CONFIG_FILENAME, PROJECT_CONFIG_SCHEMA_VERSION, OBSERVATION_ALIAS_PATTERN, validateObservationAlias, validateProjectConfig, readProjectConfig } from './projectWorkflow/projectConfig.js';
+export type { DiscoverProjectResult } from './projectWorkflow/projectDiscovery.js';
+export { discoverFrontendObserverProject } from './projectWorkflow/projectDiscovery.js';
+export type { AliasCatalog, AliasCatalogReadResult, ObservationAliasRecord } from './projectWorkflow/aliasCatalog.js';
+export { ALIAS_CATALOG_SCHEMA_VERSION, readAliasCatalog, serializeAliasCatalog, validateAliasCatalog, writeAliasCatalog } from './projectWorkflow/aliasCatalog.js';
+export { projectConfigPath, projectStateRoot, aliasCatalogPath, projectEvidenceRoot, projectObservationsRoot, observationOutputLocation } from './projectWorkflow/projectPaths.js';
+export type { CaptureNamedObservationInput, CaptureNamedObservationResult, InitializeProjectInput, ProjectWorkflowErrorCode } from './application/projectWorkflowService.js';
+export { initializeFrontendObserverProject, captureNamedObservation, loadProjectViewerState } from './application/projectWorkflowService.js';
+export type { CheckWorkflowStatus, CheckWorkflowResult } from './projectWorkflow/checkResult.js';
+export { CHECK_RESULT_SCHEMA_VERSION, CHECK_WORKFLOW_STATUSES } from './projectWorkflow/checkResult.js';
+export { checkProject } from './application/projectCheckService.js';
+export { VIEWER_PROTOCOL_VERSION } from './viewerServer/httpServer.js';
+export type { PrepareReferenceCorrectionInput, PrepareReferenceCorrectionStatus, ReferenceCorrectionHandoff, PrepareReferenceCorrectionResult, ReferenceCorrectionOverallState, ReviewReferenceCorrectionAttemptInput, ReferenceCorrectionAttemptResult, ReviewReferenceCorrectionAttemptResult, } from './domain/referenceCorrectionWorkflow.js';
+export { REFERENCE_CORRECTION_OVERALL_STATES, prepareReferenceCorrection, reviewReferenceCorrectionAttempt } from './domain/referenceCorrectionWorkflow.js';

package/dist/index.js

@@ -0,0 +1,64 @@
+export { isValidEvidenceField, evidenceValue } from './domain/evidence.js';
+export { DIAGNOSTIC_CODES, DIAGNOSTIC_SEVERITY, orderDiagnostics } from './domain/diagnostics.js';
+export { deriveCompletion } from './domain/completion.js';
+export { ARTIFACT_KIND, SCHEMA_VERSION, PRODUCER_NAME, TARGET_LANDMARK_ROLES, getProducerInfo, isValidObservationArtifact, } from './domain/schema.js';
+export { buildRequestIdentity, buildObservationIdentity } from './domain/identity.js';
+export { normalizeRequest, SCROLL_DELTA_MAX_ABS } from './request/request.js';
+export { normalizeOutputLocation } from './request/paths.js';
+export { classifyUrl, classifyRedirect, classifySubresource, classifyPopup, classifyDownload } from './safety/policy.js';
+export { runBrowserCapture } from './application/browserCaptureService.js';
+export { MANIFEST_FILENAME, SCREENSHOT_FILENAME } from './artifacts/artifactWriter.js';
+export { buildObservationArtifact, persistBrowserCapture, observe } from './application/observationPersistence.js';
+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, assessOptionalComparabilityDimension, targetPresence, } from './domain/comparisonEngine.js';
+export { BOUNDED_AGENT_CONTEXT_ARTIFACT_KIND, BOUNDED_AGENT_CONTEXT_SCHEMA_VERSION, PROJECTION_PROFILES, MAX_RUNTIME_TARGETS, MAX_RELATIONSHIP_EVIDENCE_PER_TARGET, MAX_OMISSIONS, MAX_TRUNCATIONS, MAX_CORRELATION_RECORDS, MAX_STATIC_CANDIDATES_PER_TARGET, MAX_TEXT_SUMMARY_CHARS, MAX_EVIDENCE_REFS_PER_CORRELATION_FIELD, MAX_FIDELITY_MISMATCHES, MAX_FIDELITY_PROTECTED_CONTEXT, ADEQUACY_STATES, ADEQUACY_REASON_CODES, OMISSION_REASONS, CORRELATION_STATUSES, STATIC_CANDIDATE_KINDS, isValidBoundedAgentContextArtifact, isValidBoundedReferenceFidelityProjection, } from './domain/boundedAgentContext.js';
+export { buildBoundedAgentContextRequestIdentity, buildBoundedAgentContextInstanceIdentity } from './domain/boundedAgentContextIdentity.js';
+export { projectBoundedAgentContext } from './domain/boundedAgentContextProjection.js';
+export { projectReferenceFidelity } from './domain/referenceFidelityProjection.js';
+export { deriveRuntimeStaticCorrelations, attachRuntimeStaticCorrelations } from './domain/boundedAgentContextCorrelation.js';
+export { COMPARISON_MANIFEST_FILENAME, writeComparisonArtifact } from './artifacts/comparisonArtifactWriter.js';
+export { readObservationArtifact } from './artifacts/artifactReader.js';
+export { DEFAULT_COMPARISON_OUTPUT_LOCATION, compareAndPersist, compareAndPersistFromArtifactRoots } from './application/comparisonService.js';
+export { EXTERNAL_REFERENCE_SUPPORTED_IMAGE_FORMATS, isExternalReferenceImageFormat, EXTERNAL_REFERENCE_MAX_IMAGE_BYTES, EXTERNAL_REFERENCE_MIN_DIMENSION_PX, EXTERNAL_REFERENCE_MAX_DIMENSION_PX, detectExternalReferenceImageFormat, readExternalReferenceImageDimensions, isValidExternalReferenceImageDimensions, fileExtensionForFormat, } from './domain/externalReferenceImage.js';
+export { EXTERNAL_REFERENCE_ARTIFACT_KIND, EXTERNAL_REFERENCE_SCHEMA_VERSION, isValidExternalReferenceImageReference, isValidExternalReferenceSourceReference, isValidExternalReferenceLifecycleState, isValidExternalReferenceProvenance, isValidExternalReferenceArtifact, isImportedExternalReferenceArtifact, isApprovedExternalReferenceArtifact, } from './domain/externalReference.js';
+export { buildExternalReferenceRequestIdentity, buildExternalReferenceInstanceIdentity } from './domain/externalReferenceIdentity.js';
+export { EXTERNAL_REFERENCE_MANIFEST_FILENAME, writeExternalReferenceArtifact } from './artifacts/externalReferenceArtifactWriter.js';
+export { readExternalReferenceArtifact } from './artifacts/externalReferenceArtifactReader.js';
+export { importExternalReference, approveExternalReference } from './application/externalReferencePersistenceService.js';
+export { REFERENCE_REGION_ID_PATTERN, MAX_REFERENCE_REGIONS, deriveReferenceRegionGeometry, isValidReferenceRegionRectangle, isValidReferenceRegion, isValidReferenceRegions, } from './domain/externalReferenceRegions.js';
+export { MAX_REFERENCE_REGION_PAIRS, REFERENCE_REGION_RELATIONSHIP_FAMILY_COUNT, MAX_REFERENCE_REGION_RELATIONSHIP_RECORDS, isValidReferenceRegionRelationship, isValidReferenceRegionRelationshipGraph, deriveReferenceRegionRelationships, } from './domain/externalReferenceRegionRelationships.js';
+export { buildReferenceRequirementIdentity } from './domain/externalReferenceRequirementIdentity.js';
+export { MAX_REFERENCE_REQUIREMENTS, REFERENCE_REQUIREMENT_REGION_PROPERTIES, isReferenceRequirementRegionProperty, REFERENCE_REQUIREMENT_MEASUREMENTS, isReferenceRequirementMeasurement, deriveReferenceRequirementMeasurement, REFERENCE_REQUIREMENT_TOLERANCE_ABSOLUTE_PX_MIN, REFERENCE_REQUIREMENT_TOLERANCE_ABSOLUTE_PX_MAX, REFERENCE_REQUIREMENT_TOLERANCE_PERCENT_MIN, REFERENCE_REQUIREMENT_TOLERANCE_PERCENT_MAX, isValidReferenceRequirementTolerance, isValidReferenceRequirementSubjectShape, isValidRawReferenceRequirement, buildReferenceRequirement, isValidReferenceRequirementShape, isValidReferenceRequirements, deriveReferenceRequirementExpectation, REFERENCE_REQUIREMENT_ADEQUACY_STATES, REFERENCE_REQUIREMENT_ADEQUACY_REASON_CODES, deriveReferenceRequirementAdequacy, isValidReferenceRequirementAdequacy, } from './domain/externalReferenceRequirements.js';
+export { STATE_LABEL_PATTERN, AUTHENTICATED_STATE_VALUES, isValidStateLabel, isValidAuthenticatedState, isValidExplicitStateDimensions, } from './domain/explicitState.js';
+export { APPLICABLE_VIEWPORT_MIN, APPLICABLE_VIEWPORT_MAX, isValidApplicableViewport, isValidExternalReferenceApplicability, } from './domain/externalReferenceApplicability.js';
+export { evaluateReferenceCandidateCompatibility } from './domain/externalReferenceCompatibility.js';
+export { RUNTIME_TARGET_NAME_PATTERN, MAX_REFERENCE_RUNTIME_BINDINGS, REFERENCE_RUNTIME_BINDING_STATUSES, REFERENCE_RUNTIME_BINDING_REASON_CODES, isValidReferenceRuntimeBindingDeclarations, evaluateReferenceRuntimeBindings, } from './domain/externalReferenceRuntimeBinding.js';
+export { REFERENCE_REQUIREMENT_FIDELITY_STATUSES, REFERENCE_REQUIREMENT_FIDELITY_REASON_CODES, REFERENCE_FIDELITY_STATES, REFERENCE_FIDELITY_BLOCK_REASONS, evaluateReferenceCandidateFidelity, isValidReferenceRequirementFidelityResult, } from './domain/externalReferenceFidelity.js';
+export { evaluateReferenceCandidateFidelityFromArtifactRoots } from './application/referenceFidelityEvaluationService.js';
+export { buildReferenceCorrectionReviewIdentity, buildReferenceCorrectionAttemptIdentity } from './domain/referenceCorrectionIdentity.js';
+export { DEFAULT_VIEWER_PORT, VIEWER_HOST, isValidViewerPort } from './viewerServer/port.js';
+export { startViewer, defaultViewerAssetsRoot } from './viewerServer/viewerService.js';
+export { PROJECT_CONFIG_FILENAME, PROJECT_CONFIG_SCHEMA_VERSION, OBSERVATION_ALIAS_PATTERN, validateObservationAlias, validateProjectConfig, readProjectConfig } from './projectWorkflow/projectConfig.js';
+export { discoverFrontendObserverProject } from './projectWorkflow/projectDiscovery.js';
+export { ALIAS_CATALOG_SCHEMA_VERSION, readAliasCatalog, serializeAliasCatalog, validateAliasCatalog, writeAliasCatalog } from './projectWorkflow/aliasCatalog.js';
+export { projectConfigPath, projectStateRoot, aliasCatalogPath, projectEvidenceRoot, projectObservationsRoot, observationOutputLocation } from './projectWorkflow/projectPaths.js';
+export { initializeFrontendObserverProject, captureNamedObservation, loadProjectViewerState } from './application/projectWorkflowService.js';
+export { CHECK_RESULT_SCHEMA_VERSION, CHECK_WORKFLOW_STATUSES } from './projectWorkflow/checkResult.js';
+export { checkProject } from './application/projectCheckService.js';
+export { VIEWER_PROTOCOL_VERSION } from './viewerServer/httpServer.js';
+export { REFERENCE_CORRECTION_OVERALL_STATES, prepareReferenceCorrection, reviewReferenceCorrectionAttempt } from './domain/referenceCorrectionWorkflow.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/projectWorkflow/aliasCatalog.d.ts

@@ -0,0 +1,21 @@
+export declare const ALIAS_CATALOG_SCHEMA_VERSION: "1.0.0";
+export interface ObservationAliasRecord {
+    observationId: string;
+    requestId: string;
+    relativeArtifactDir: string;
+}
+export interface AliasCatalog {
+    schemaVersion: typeof ALIAS_CATALOG_SCHEMA_VERSION;
+    observations: Record<string, ObservationAliasRecord>;
+}
+export type AliasCatalogReadResult = {
+    ok: true;
+    catalog: AliasCatalog;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function validateAliasCatalog(value: unknown): AliasCatalogReadResult;
+export declare function readAliasCatalog(catalogPath: string): Promise<AliasCatalogReadResult>;
+export declare function serializeAliasCatalog(catalog: AliasCatalog): string;
+export declare function writeAliasCatalog(catalogPath: string, catalog: AliasCatalog): Promise<void>;

package/dist/projectWorkflow/aliasCatalog.js

@@ -0,0 +1,67 @@
+import { readFile, writeFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { validateObservationAlias } from './projectConfig.js';
+export const ALIAS_CATALOG_SCHEMA_VERSION = '1.0.0';
+const REQUEST_ID = /^[a-f0-9]{64}$/;
+const OBSERVATION_ID = /^[a-f0-9]{64}-[a-f0-9]{32}$/;
+function isObject(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }
+function safeRelativeDir(value) {
+    if (value.length === 0 || value.includes('\\') || path.posix.isAbsolute(value))
+        return false;
+    const parts = value.split('/');
+    return parts.every((part) => part.length > 0 && part !== '.' && part !== '..' && !part.includes(':'));
+}
+export function validateAliasCatalog(value) {
+    if (!isObject(value))
+        return { ok: false, reason: 'catalog root must be an object' };
+    const rootUnknown = Object.keys(value).filter((key) => key !== 'schemaVersion' && key !== 'observations');
+    if (rootUnknown.length > 0)
+        return { ok: false, reason: `catalog has unsupported field(s): ${rootUnknown.join(', ')}` };
+    if (value.schemaVersion !== ALIAS_CATALOG_SCHEMA_VERSION)
+        return { ok: false, reason: `unsupported catalog schema version: ${String(value.schemaVersion)}` };
+    if (!isObject(value.observations))
+        return { ok: false, reason: 'catalog observations must be an object' };
+    const observations = {};
+    for (const [alias, raw] of Object.entries(value.observations)) {
+        if (!validateObservationAlias(alias, true).ok)
+            return { ok: false, reason: `catalog contains invalid alias: ${alias}` };
+        if (!isObject(raw))
+            return { ok: false, reason: `catalog record for ${alias} must be an object` };
+        const unknown = Object.keys(raw).filter((key) => !['observationId', 'requestId', 'relativeArtifactDir'].includes(key));
+        if (unknown.length > 0)
+            return { ok: false, reason: `catalog record for ${alias} has unsupported field(s): ${unknown.join(', ')}` };
+        if (typeof raw.observationId !== 'string' || !OBSERVATION_ID.test(raw.observationId))
+            return { ok: false, reason: `catalog record for ${alias} has invalid observationId` };
+        if (typeof raw.requestId !== 'string' || !REQUEST_ID.test(raw.requestId))
+            return { ok: false, reason: `catalog record for ${alias} has invalid requestId` };
+        if (typeof raw.relativeArtifactDir !== 'string' || !safeRelativeDir(raw.relativeArtifactDir))
+            return { ok: false, reason: `catalog record for ${alias} has unsafe relativeArtifactDir` };
+        observations[alias] = { observationId: raw.observationId, requestId: raw.requestId, relativeArtifactDir: raw.relativeArtifactDir };
+    }
+    return { ok: true, catalog: { schemaVersion: ALIAS_CATALOG_SCHEMA_VERSION, observations } };
+}
+export async function readAliasCatalog(catalogPath) {
+    try {
+        return validateAliasCatalog(JSON.parse(await readFile(catalogPath, 'utf8')));
+    }
+    catch (error) {
+        return { ok: false, reason: `catalog could not be read: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+export function serializeAliasCatalog(catalog) {
+    const observations = Object.fromEntries(Object.keys(catalog.observations).sort().map((alias) => [alias, catalog.observations[alias]]));
+    return `${JSON.stringify({ schemaVersion: ALIAS_CATALOG_SCHEMA_VERSION, observations }, null, 2)}\n`;
+}
+export async function writeAliasCatalog(catalogPath, catalog) {
+    const tempPath = `${catalogPath}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`;
+    try {
+        await writeFile(tempPath, serializeAliasCatalog(catalog), 'utf8');
+        await rename(tempPath, catalogPath);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+//# sourceMappingURL=aliasCatalog.js.map

package/dist/projectWorkflow/aliasCatalog.js.map

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

package/dist/projectWorkflow/checkAcceptance.d.ts

@@ -0,0 +1,25 @@
+import type { ComparisonConfig } from '../domain/comparison.js';
+export type LoadBindingsFileResult = {
+    ok: true;
+    bindings: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/** Shared wrapper parser used by both the low-level fidelity command and project check. */
+export declare function loadBindingsFile(filePath: string): LoadBindingsFileResult;
+export declare function loadComparisonConfigFile(filePath: string): {
+    ok: true;
+    config: ComparisonConfig;
+} | {
+    ok: false;
+    error: string;
+};
+/** Resolve an existing acceptance input only after real-path containment succeeds. */
+export declare function resolveContainedAcceptancePath(projectRoot: string, relativePath: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/projectWorkflow/checkAcceptance.js

@@ -0,0 +1,55 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { isValidComparisonConfig } from '../domain/comparison.js';
+/** Shared wrapper parser used by both the low-level fidelity command and project check. */
+export function loadBindingsFile(filePath) {
+    let rawText;
+    try {
+        rawText = readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        return { ok: false, error: `--bindings-file could not be read: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (error) {
+        return { ok: false, error: `--bindings-file is not valid JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return { ok: false, error: '--bindings-file root must be a JSON object' };
+    const record = parsed;
+    const unknownFields = Object.keys(record).filter((key) => key !== 'bindings');
+    if (unknownFields.length > 0)
+        return { ok: false, error: `--bindings-file has unsupported top-level field(s): ${unknownFields.join(', ')}` };
+    if (!('bindings' in record))
+        return { ok: false, error: '--bindings-file must have a "bindings" property' };
+    return { ok: true, bindings: record.bindings };
+}
+export function loadComparisonConfigFile(filePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        return { ok: false, error: `comparison config could not be read: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (!isValidComparisonConfig(parsed))
+        return { ok: false, error: 'comparison config is not a valid canonical ComparisonConfig' };
+    return { ok: true, config: parsed };
+}
+/** Resolve an existing acceptance input only after real-path containment succeeds. */
+export function resolveContainedAcceptancePath(projectRoot, relativePath) {
+    try {
+        const realRoot = realpathSync(projectRoot);
+        const resolved = realpathSync(path.resolve(projectRoot, relativePath));
+        if (resolved !== realRoot && !resolved.startsWith(`${realRoot}${path.sep}`))
+            return { ok: false, error: `acceptance path escapes project root: ${relativePath}` };
+        return { ok: true, path: resolved };
+    }
+    catch {
+        return { ok: false, error: `acceptance path could not be resolved inside the project: ${relativePath}` };
+    }
+}
+//# sourceMappingURL=checkAcceptance.js.map

package/dist/projectWorkflow/checkAcceptance.js.map

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