@dailephd/my-frontend-observer 0.8.1

package/dist/domain/externalReference.d.ts

@@ -0,0 +1,158 @@
+/**
+ * v0.7 Prompt 1 external-reference artifact family, extended in Prompt 2
+ * with explicit, additive, optional reference regions (identity, provenance,
+ * bounded image metadata, two-state lifecycle, forward-only supersession -
+ * see the Prompt 1 report for that foundation; region geometry/relationship
+ * derivation lives in externalReferenceRegions.ts /
+ * externalReferenceRegionRelationships.ts). This module still implements
+ * neither design requirements, tolerances, reference-region/runtime binding,
+ * nor reference-vs-candidate evaluation - see docs/ARCHITECTURE.md.
+ *
+ * An external reference is desired-design evidence, not an earlier browser
+ * observation: this module never reuses ARTIFACT_KIND/SCHEMA_VERSION
+ * (observation), COMPARISON_ARTIFACT_KIND, or CONTRACT_ARTIFACT_KIND, and
+ * adds no field to any of those existing types.
+ */
+import type { Diagnostic } from './diagnostics.js';
+import type { CompletionState } from './completion.js';
+import { PRODUCER_NAME } from './schema.js';
+import type { ExternalReferenceImageFormat } from './externalReferenceImage.js';
+import type { ReferenceRegion } from './externalReferenceRegions.js';
+import type { ExternalReferenceRequirement } from './externalReferenceRequirements.js';
+import type { ExternalReferenceApplicability } from './externalReferenceApplicability.js';
+export declare const EXTERNAL_REFERENCE_ARTIFACT_KIND: "my-frontend-observer/external-reference";
+export declare const EXTERNAL_REFERENCE_SCHEMA_VERSION: "1.0.0";
+export interface ExternalReferenceImageReference {
+    /** Bare relative filename within the artifact's own directory - never an absolute path. */
+    path: string;
+    format: ExternalReferenceImageFormat;
+    width: number;
+    height: number;
+    byteLength: number;
+    /** sha256 hex digest of the raw image bytes - identity-bearing (see externalReferenceIdentity.ts). */
+    sha256: string;
+}
+export declare function isValidExternalReferenceImageReference(value: unknown): value is ExternalReferenceImageReference;
+/**
+ * Enough logical identity to trace an approved reference back to the
+ * imported artifact that owns its image, without ever re-copying the image
+ * bytes - mirrors ComparisonSourceObservationReference's
+ * {id, requestId, producer, schemaVersion, screenshot: {path}} shape exactly.
+ */
+export interface ExternalReferenceSourceReference {
+    referenceId: string;
+    referenceRequestId: string;
+    producer: {
+        name: typeof PRODUCER_NAME;
+        version: string;
+    };
+    schemaVersion: typeof EXTERNAL_REFERENCE_SCHEMA_VERSION;
+    image: ExternalReferenceImageReference;
+}
+export declare function isValidExternalReferenceSourceReference(value: unknown): value is ExternalReferenceSourceReference;
+/**
+ * Exactly two persisted states. There is no literal 'superseded' variant:
+ * supersession is represented only as a forward-declared relationship (a
+ * newer artifact's `supersedesReferenceId` pointing at an older artifact's
+ * `referenceId`) so that an existing persisted artifact's own lifecycle field
+ * is never rewritten - "old evidence remains immutable, no hidden rewrite"
+ * holds unconditionally rather than depending on careful mutation discipline.
+ */
+export type ExternalReferenceLifecycleState = {
+    state: 'imported';
+} | {
+    state: 'approved';
+    approvedAt: string;
+};
+export declare function isValidExternalReferenceLifecycleState(value: unknown): value is ExternalReferenceLifecycleState;
+export interface ExternalReferenceProvenance {
+    importedAt: string;
+    /** Optional caller-supplied human label - pure provenance, never identity-bearing (see externalReferenceIdentity.ts). */
+    label?: string;
+}
+export declare function isValidExternalReferenceProvenance(value: unknown): value is ExternalReferenceProvenance;
+interface ExternalReferenceArtifactBase {
+    artifactKind: typeof EXTERNAL_REFERENCE_ARTIFACT_KIND;
+    schemaVersion: typeof EXTERNAL_REFERENCE_SCHEMA_VERSION;
+    /** Deterministic logical identity - see buildExternalReferenceRequestIdentity. Shared by an imported artifact and every artifact produced by approving it. */
+    referenceRequestId: string;
+    /** Fresh per-persisted-instance identity - see buildExternalReferenceInstanceIdentity. */
+    referenceId: string;
+    producer: {
+        name: typeof PRODUCER_NAME;
+        version: string;
+    };
+    provenance: ExternalReferenceProvenance;
+    /** Explicit, forward-only supersession of a prior reference's referenceId - never inferred from image/content similarity. */
+    supersedesReferenceId?: string;
+    /**
+     * v0.7 Prompt 2 addition (additive, optional - a Prompt 1 artifact predates
+     * this field entirely and remains valid without it, so no schema version
+     * bump was needed). Explicit, user/configuration-authored reference-image
+     * rectangles - identity-bearing wherever present (see
+     * externalReferenceIdentity.ts). Never mutated in place: changing region
+     * content produces a new referenceRequestId/referenceId, never a rewrite of
+     * this array on an existing persisted artifact.
+     */
+    regions?: ReferenceRegion[];
+    /**
+     * v0.7 Prompt 3 addition (additive, optional - same backward-compatibility
+     * reasoning as `regions`: a Prompt 1/2 artifact predates this field
+     * entirely and remains valid without it). Explicit, user/configuration-
+     * selected design intent over the `regions` above - never inferred merely
+     * because a region property/relationship exists (see docs/CONTRACTS.md
+     * "v0.7 Prompt 3"). Identity-bearing wherever present. Never mutated in
+     * place: changing selected requirements/tolerances produces a new
+     * referenceRequestId/referenceId, never a rewrite of this array on an
+     * existing persisted artifact.
+     */
+    requirements?: ExternalReferenceRequirement[];
+    /**
+     * v0.7 Prompt 4 addition (additive, optional - same backward-compatibility
+     * reasoning as `regions`/`requirements`). The runtime frontend state this
+     * reference is intended to represent (applicable viewport/theme/
+     * application-state/authenticated-state) - never the reference image's own
+     * pixel dimensions (see `image.width`/`height` above and
+     * externalReferenceApplicability.ts's doc comment). Identity-bearing
+     * wherever present. Never mutated in place; importing applicability never
+     * implies approval, and approval carries it forward verbatim.
+     */
+    applicability?: ExternalReferenceApplicability;
+    diagnostics: Diagnostic[];
+    completion: CompletionState;
+}
+export interface ImportedExternalReferenceArtifact extends ExternalReferenceArtifactBase {
+    lifecycle: {
+        state: 'imported';
+    };
+    image: ExternalReferenceImageReference;
+}
+export interface ApprovedExternalReferenceArtifact extends ExternalReferenceArtifactBase {
+    lifecycle: {
+        state: 'approved';
+        approvedAt: string;
+    };
+    sourceReference: ExternalReferenceSourceReference;
+}
+export type ExternalReferenceArtifact = ImportedExternalReferenceArtifact | ApprovedExternalReferenceArtifact;
+/** User-defined type guards: TypeScript does not narrow a union of `extends`-based interfaces purely from a nested `artifact.lifecycle.state` comparison, so callers needing the narrowed shape (the writer, the application service) use these instead of re-deriving the check. */
+export declare function isImportedExternalReferenceArtifact(artifact: ExternalReferenceArtifact): artifact is ImportedExternalReferenceArtifact;
+export declare function isApprovedExternalReferenceArtifact(artifact: ExternalReferenceArtifact): artifact is ApprovedExternalReferenceArtifact;
+export type ExternalReferenceValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Structural validator for ExternalReferenceArtifact. The single gate used by
+ * both the writer and the reader (artifacts/externalReferenceArtifactWriter.ts
+ * / externalReferenceArtifactReader.ts) - never a second validator. Rejects a
+ * value that mixes the two lifecycle-variant-specific fields (an 'imported'
+ * artifact must never carry sourceReference; an 'approved' artifact must
+ * never carry image), fails closed on an unsupported schemaVersion, and never
+ * re-parses raw image bytes (that already happened before this object was
+ * built - see application/externalReferencePersistenceService.ts).
+ */
+export declare function isValidExternalReferenceArtifact(value: unknown): ExternalReferenceValidationResult;
+export {};

package/dist/domain/externalReference.js

@@ -0,0 +1,167 @@
+import { PRODUCER_NAME } from './schema.js';
+import { isExternalReferenceImageFormat, isValidExternalReferenceImageDimensions } from './externalReferenceImage.js';
+import { isValidReferenceRegions } from './externalReferenceRegions.js';
+import { isValidReferenceRequirements } from './externalReferenceRequirements.js';
+import { isValidExternalReferenceApplicability } from './externalReferenceApplicability.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export const EXTERNAL_REFERENCE_ARTIFACT_KIND = 'my-frontend-observer/external-reference';
+export const EXTERNAL_REFERENCE_SCHEMA_VERSION = '1.0.0';
+export function isValidExternalReferenceImageReference(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (!isNonEmptyString(value.path) || value.path.includes('/') || value.path.includes('\\'))
+        return false;
+    if (!isExternalReferenceImageFormat(value.format))
+        return false;
+    if (typeof value.width !== 'number' || typeof value.height !== 'number')
+        return false;
+    if (!isValidExternalReferenceImageDimensions({ width: value.width, height: value.height }))
+        return false;
+    if (typeof value.byteLength !== 'number' || !Number.isInteger(value.byteLength) || value.byteLength <= 0)
+        return false;
+    if (typeof value.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(value.sha256))
+        return false;
+    return true;
+}
+export function isValidExternalReferenceSourceReference(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (!isNonEmptyString(value.referenceId) || !isNonEmptyString(value.referenceRequestId))
+        return false;
+    if (!isPlainObject(value.producer) || value.producer.name !== PRODUCER_NAME || !isNonEmptyString(value.producer.version))
+        return false;
+    if (value.schemaVersion !== EXTERNAL_REFERENCE_SCHEMA_VERSION)
+        return false;
+    return isValidExternalReferenceImageReference(value.image);
+}
+export function isValidExternalReferenceLifecycleState(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (value.state === 'imported')
+        return Object.keys(value).length === 1;
+    if (value.state === 'approved')
+        return Object.keys(value).length === 2 && isNonEmptyString(value.approvedAt);
+    return false;
+}
+export function isValidExternalReferenceProvenance(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (!isNonEmptyString(value.importedAt))
+        return false;
+    if ('label' in value && value.label !== undefined && !isNonEmptyString(value.label))
+        return false;
+    return true;
+}
+/** User-defined type guards: TypeScript does not narrow a union of `extends`-based interfaces purely from a nested `artifact.lifecycle.state` comparison, so callers needing the narrowed shape (the writer, the application service) use these instead of re-deriving the check. */
+export function isImportedExternalReferenceArtifact(artifact) {
+    return artifact.lifecycle.state === 'imported';
+}
+export function isApprovedExternalReferenceArtifact(artifact) {
+    return artifact.lifecycle.state === 'approved';
+}
+function isValidDiagnosticArray(value) {
+    return (Array.isArray(value) &&
+        value.every((d) => isPlainObject(d) &&
+            typeof d.code === 'string' &&
+            (d.severity === 'error' || d.severity === 'warning') &&
+            typeof d.message === 'string' &&
+            d.message.length > 0));
+}
+function isValidCompletionState(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (value.state === 'complete')
+        return Object.keys(value).length === 1;
+    if (value.state === 'partial' || value.state === 'warning' || value.state === 'invalid-request' || value.state === 'fatal') {
+        return Object.keys(value).length === 2 && isValidDiagnosticArray(value.diagnostics);
+    }
+    return false;
+}
+/**
+ * Structural validator for ExternalReferenceArtifact. The single gate used by
+ * both the writer and the reader (artifacts/externalReferenceArtifactWriter.ts
+ * / externalReferenceArtifactReader.ts) - never a second validator. Rejects a
+ * value that mixes the two lifecycle-variant-specific fields (an 'imported'
+ * artifact must never carry sourceReference; an 'approved' artifact must
+ * never carry image), fails closed on an unsupported schemaVersion, and never
+ * re-parses raw image bytes (that already happened before this object was
+ * built - see application/externalReferencePersistenceService.ts).
+ */
+export function isValidExternalReferenceArtifact(value) {
+    if (!isPlainObject(value))
+        return { valid: false, reason: 'artifact must be an object' };
+    if (value.artifactKind !== EXTERNAL_REFERENCE_ARTIFACT_KIND)
+        return { valid: false, reason: 'artifactKind mismatch' };
+    if (value.schemaVersion !== EXTERNAL_REFERENCE_SCHEMA_VERSION)
+        return { valid: false, reason: 'schemaVersion mismatch' };
+    if (!isNonEmptyString(value.referenceRequestId))
+        return { valid: false, reason: 'referenceRequestId must be a non-empty string' };
+    if (!isNonEmptyString(value.referenceId))
+        return { valid: false, reason: 'referenceId must be a non-empty string' };
+    if (!isPlainObject(value.producer) || value.producer.name !== PRODUCER_NAME || typeof value.producer.version !== 'string' || value.producer.version.length === 0) {
+        return { valid: false, reason: 'producer must be { name: "my-frontend-observer", version: string }' };
+    }
+    if (!isValidExternalReferenceProvenance(value.provenance))
+        return { valid: false, reason: 'provenance is invalid' };
+    if ('supersedesReferenceId' in value && value.supersedesReferenceId !== undefined && !isNonEmptyString(value.supersedesReferenceId)) {
+        return { valid: false, reason: 'supersedesReferenceId must be a non-empty string when present' };
+    }
+    if (!isValidDiagnosticArray(value.diagnostics))
+        return { valid: false, reason: 'diagnostics must be an array of valid Diagnostic values' };
+    if (!isValidCompletionState(value.completion))
+        return { valid: false, reason: 'completion is invalid' };
+    if (isPlainObject(value.completion) && value.completion.state === 'complete' && value.diagnostics.length > 0) {
+        return { valid: false, reason: 'completion "complete" requires an empty diagnostics array' };
+    }
+    if (!isValidExternalReferenceLifecycleState(value.lifecycle))
+        return { valid: false, reason: 'lifecycle is invalid' };
+    const lifecycle = value.lifecycle;
+    const hasImage = 'image' in value && value.image !== undefined;
+    const hasSourceReference = 'sourceReference' in value && value.sourceReference !== undefined;
+    let imageWidth;
+    let imageHeight;
+    if (lifecycle.state === 'imported') {
+        if (hasSourceReference)
+            return { valid: false, reason: 'an "imported" artifact must not carry sourceReference' };
+        if (!hasImage || !isValidExternalReferenceImageReference(value.image))
+            return { valid: false, reason: 'an "imported" artifact must carry a valid image reference' };
+        const image = value.image;
+        imageWidth = image.width;
+        imageHeight = image.height;
+    }
+    else {
+        // lifecycle.state === 'approved'
+        if (hasImage)
+            return { valid: false, reason: 'an "approved" artifact must not carry image (it never owns a copy of the reference image)' };
+        if (!hasSourceReference || !isValidExternalReferenceSourceReference(value.sourceReference)) {
+            return { valid: false, reason: 'an "approved" artifact must carry a valid sourceReference' };
+        }
+        const sourceReference = value.sourceReference;
+        imageWidth = sourceReference.image.width;
+        imageHeight = sourceReference.image.height;
+    }
+    const hasRegions = 'regions' in value && value.regions !== undefined;
+    if (hasRegions) {
+        const regionsValidation = isValidReferenceRegions(value.regions, imageWidth, imageHeight);
+        if (!regionsValidation.valid)
+            return { valid: false, reason: `regions: ${regionsValidation.reason}` };
+    }
+    if ('requirements' in value && value.requirements !== undefined) {
+        const regionsForRequirements = (hasRegions ? value.regions : []);
+        const requirementsValidation = isValidReferenceRequirements(value.requirements, regionsForRequirements);
+        if (!requirementsValidation.valid)
+            return { valid: false, reason: `requirements: ${requirementsValidation.reason}` };
+    }
+    if ('applicability' in value && value.applicability !== undefined) {
+        const applicabilityValidation = isValidExternalReferenceApplicability(value.applicability);
+        if (!applicabilityValidation.valid)
+            return { valid: false, reason: `applicability: ${applicabilityValidation.reason}` };
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=externalReference.js.map

package/dist/domain/externalReference.js.map

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

package/dist/domain/externalReferenceApplicability.d.ts

@@ -0,0 +1,43 @@
+/**
+ * v0.7 Prompt 4 reference applicability - the runtime frontend state that an
+ * external reference image is intended to represent, so a later candidate
+ * comparison can honestly determine whether the reference and a candidate
+ * describe the same state (see domain/externalReferenceCompatibility.ts).
+ *
+ * `viewport` here is deliberately distinct from the reference image's own
+ * pixel dimensions (`ExternalReferenceImageReference.width/height` in
+ * externalReference.ts): a reference image may be captured at any
+ * resolution/DPI, but `applicability.viewport` describes the CSS-pixel
+ * runtime viewport the design represents (e.g. a 960x1240 reference image
+ * showing a 480x620 CSS-pixel mobile layout at 2x device pixel ratio). This
+ * module never reads or infers a viewport from image dimensions.
+ */
+import type { ExplicitStateDimensions } from './explicitState.js';
+/** Intentionally mirrors request/request.ts's VIEWPORT_MIN/MAX values (200/3840) as independently-owned constants - the applicable viewport describes the same kind of CSS-pixel runtime viewport an observation request configures, so the same bounds apply, but this module has no import dependency on request/request.ts. */
+export declare const APPLICABLE_VIEWPORT_MIN = 200;
+export declare const APPLICABLE_VIEWPORT_MAX = 3840;
+export interface ApplicableViewport {
+    width: number;
+    height: number;
+}
+export declare function isValidApplicableViewport(value: unknown): value is ApplicableViewport;
+/** Every field independently optional - a reference need not declare every applicability dimension, and an unset dimension is never treated as a wildcard match nor a mismatch (see externalReferenceCompatibility.ts's unassessed semantics). */
+export interface ExternalReferenceApplicability extends ExplicitStateDimensions {
+    viewport?: ApplicableViewport;
+}
+export type ApplicabilityValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Deliberately its own validator rather than a reuse of
+ * isValidExplicitStateDimensions: that function requires at least one of its
+ * three fields, which would incorrectly reject an applicability object that
+ * declares only `viewport` (a fully valid, common case - a reference may
+ * constrain viewport without constraining theme/state at all). The three
+ * shared state-label/authenticated-state checks are reused field-by-field
+ * instead.
+ */
+export declare function isValidExternalReferenceApplicability(value: unknown): ApplicabilityValidationResult;

package/dist/domain/externalReferenceApplicability.js

@@ -0,0 +1,52 @@
+import { isValidStateLabel, isValidAuthenticatedState, STATE_LABEL_PATTERN, AUTHENTICATED_STATE_VALUES } from './explicitState.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isInRange(value, min, max) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max;
+}
+/** Intentionally mirrors request/request.ts's VIEWPORT_MIN/MAX values (200/3840) as independently-owned constants - the applicable viewport describes the same kind of CSS-pixel runtime viewport an observation request configures, so the same bounds apply, but this module has no import dependency on request/request.ts. */
+export const APPLICABLE_VIEWPORT_MIN = 200;
+export const APPLICABLE_VIEWPORT_MAX = 3840;
+export function isValidApplicableViewport(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (Object.keys(value).length !== 2)
+        return false;
+    return isInRange(value.width, APPLICABLE_VIEWPORT_MIN, APPLICABLE_VIEWPORT_MAX) && isInRange(value.height, APPLICABLE_VIEWPORT_MIN, APPLICABLE_VIEWPORT_MAX);
+}
+const APPLICABILITY_KEYS = ['viewport', 'theme', 'applicationState', 'authenticatedState'];
+/**
+ * Deliberately its own validator rather than a reuse of
+ * isValidExplicitStateDimensions: that function requires at least one of its
+ * three fields, which would incorrectly reject an applicability object that
+ * declares only `viewport` (a fully valid, common case - a reference may
+ * constrain viewport without constraining theme/state at all). The three
+ * shared state-label/authenticated-state checks are reused field-by-field
+ * instead.
+ */
+export function isValidExternalReferenceApplicability(value) {
+    if (!isPlainObject(value))
+        return { valid: false, reason: 'must be an object' };
+    const unknownKeys = Object.keys(value).filter((key) => !APPLICABILITY_KEYS.includes(key));
+    if (unknownKeys.length > 0)
+        return { valid: false, reason: `has unsupported field(s): ${unknownKeys.join(', ')}` };
+    const hasViewport = 'viewport' in value && value.viewport !== undefined;
+    if (hasViewport && !isValidApplicableViewport(value.viewport)) {
+        return { valid: false, reason: `viewport must be { width, height } integers in [${APPLICABLE_VIEWPORT_MIN}, ${APPLICABLE_VIEWPORT_MAX}]` };
+    }
+    if ('theme' in value && value.theme !== undefined && !isValidStateLabel(value.theme)) {
+        return { valid: false, reason: `theme must match ${STATE_LABEL_PATTERN}` };
+    }
+    if ('applicationState' in value && value.applicationState !== undefined && !isValidStateLabel(value.applicationState)) {
+        return { valid: false, reason: `applicationState must match ${STATE_LABEL_PATTERN}` };
+    }
+    if ('authenticatedState' in value && value.authenticatedState !== undefined && !isValidAuthenticatedState(value.authenticatedState)) {
+        return { valid: false, reason: `authenticatedState must be one of ${AUTHENTICATED_STATE_VALUES.join(', ')}` };
+    }
+    if (Object.keys(value).length === 0) {
+        return { valid: false, reason: 'must declare at least one dimension (viewport, theme, applicationState, or authenticatedState)' };
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=externalReferenceApplicability.js.map

package/dist/domain/externalReferenceApplicability.js.map

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

package/dist/domain/externalReferenceCompatibility.d.ts

@@ -0,0 +1,40 @@
+/**
+ * v0.7 Prompt 4 reference/candidate compatibility - answers only "does this
+ * external reference describe the same frontend state as this candidate
+ * ObservationArtifact?" before any later reference-vs-candidate geometry
+ * evaluation is attempted (Prompt 6+). This is page/state-level only: no
+ * reference-region <-> runtime-target binding (Prompt 5), no geometry
+ * difference, no fidelity PASS/FAIL, no style/image comparison.
+ *
+ * Deliberately reuses domain/comparison.ts's `ComparabilityResult`/
+ * `ComparabilityReason`/`ComparabilityState`/`COMPARABILITY_REASON_CODES`/
+ * `COMPARABILITY_REASON_SEVERITY` wholesale, and
+ * domain/comparisonEngine.ts#assessOptionalComparabilityDimension (the exact
+ * same pure rule v0.4's own `evaluateComparability` uses for its explicit-
+ * state dimensions) rather than inventing a second compatibility model - an
+ * ExternalReferenceArtifact is never treated as if it were an
+ * ObservationArtifact, but the *result* and *dimension-comparison rule* are
+ * shared.
+ */
+import type { ExternalReferenceArtifact } from './externalReference.js';
+import type { ObservationArtifact } from './schema.js';
+import type { ComparabilityResult } from './comparison.js';
+export interface ReferenceCandidateCompatibilityResult {
+    referenceId: string;
+    referenceRequestId: string;
+    candidateObservationId: string;
+    candidateRequestId: string;
+    compatibility: ComparabilityResult;
+}
+/**
+ * Pure and synchronous: same `(reference, candidate)` in, same result out,
+ * every time - no browser, no filesystem, no target binding. Only evaluates
+ * `reference.applicability` against `candidate.requestConfig` (viewport,
+ * always present on an observation) / `candidate.requestConfig.explicitState`
+ * (theme/authenticatedState/applicationState, each independently optional on
+ * both sides) - reference region/requirement content is never consulted
+ * here (see domain/externalReferenceRequirements.ts for that, a distinct,
+ * separate concern - reference adequacy and reference/candidate
+ * compatibility are never conflated).
+ */
+export declare function evaluateReferenceCandidateCompatibility(reference: ExternalReferenceArtifact, candidate: ObservationArtifact): ReferenceCandidateCompatibilityResult;

package/dist/domain/externalReferenceCompatibility.js

@@ -0,0 +1,48 @@
+import { COMPARABILITY_REASON_CODES } from './comparison.js';
+import { assessOptionalComparabilityDimension } from './comparisonEngine.js';
+function viewportLabel(viewport) {
+    return `${viewport.width}x${viewport.height}`;
+}
+/**
+ * Pure and synchronous: same `(reference, candidate)` in, same result out,
+ * every time - no browser, no filesystem, no target binding. Only evaluates
+ * `reference.applicability` against `candidate.requestConfig` (viewport,
+ * always present on an observation) / `candidate.requestConfig.explicitState`
+ * (theme/authenticatedState/applicationState, each independently optional on
+ * both sides) - reference region/requirement content is never consulted
+ * here (see domain/externalReferenceRequirements.ts for that, a distinct,
+ * separate concern - reference adequacy and reference/candidate
+ * compatibility are never conflated).
+ */
+export function evaluateReferenceCandidateCompatibility(reference, candidate) {
+    const applicability = reference.applicability;
+    const reasons = [];
+    const referenceViewportLabel = applicability?.viewport ? viewportLabel(applicability.viewport) : undefined;
+    const candidateViewportLabel = viewportLabel(candidate.requestConfig.viewport);
+    const viewportReason = assessOptionalComparabilityDimension('viewport-mismatch', 'viewport-unassessed', referenceViewportLabel, candidateViewportLabel, (r, c) => `reference applicable viewport ${r} differs from candidate viewport ${c}`, 'reference does not declare an applicable viewport');
+    if (viewportReason)
+        reasons.push(viewportReason);
+    const candidateState = candidate.requestConfig.explicitState;
+    const themeReason = assessOptionalComparabilityDimension('theme-mismatch', 'theme-unassessed', applicability?.theme, candidateState?.theme, (r, c) => `reference applicable theme "${r}" differs from candidate explicit theme "${c}"`, 'theme identity is not assessed unless both the reference applicability and the candidate observation declare it');
+    if (themeReason)
+        reasons.push(themeReason);
+    const authReason = assessOptionalComparabilityDimension('authenticated-state-mismatch', 'authenticated-state-unassessed', applicability?.authenticatedState, candidateState?.authenticatedState, (r, c) => `reference applicable authenticatedState "${r}" differs from candidate explicit authenticatedState "${c}"`, 'authenticated-state identity is not assessed unless both the reference applicability and the candidate observation declare it');
+    if (authReason)
+        reasons.push(authReason);
+    const appStateReason = assessOptionalComparabilityDimension('application-state-mismatch', 'application-state-unassessed', applicability?.applicationState, candidateState?.applicationState, (r, c) => `reference applicable applicationState "${r}" differs from candidate explicit applicationState "${c}"`, 'application-state identity is not assessed unless both the reference applicability and the candidate observation declare it');
+    if (appStateReason)
+        reasons.push(appStateReason);
+    // Deterministic ordering, reusing the exact same shared code-index rule v0.4's evaluateComparability uses.
+    reasons.sort((a, b) => COMPARABILITY_REASON_CODES.indexOf(a.code) - COMPARABILITY_REASON_CODES.indexOf(b.code));
+    const hasBlocking = reasons.some((reason) => reason.severity === 'blocking');
+    const hasWarning = reasons.some((reason) => reason.severity === 'warning');
+    const state = hasBlocking ? 'incomparable' : hasWarning ? 'comparable-with-warnings' : 'comparable';
+    return {
+        referenceId: reference.referenceId,
+        referenceRequestId: reference.referenceRequestId,
+        candidateObservationId: candidate.observationId,
+        candidateRequestId: candidate.requestId,
+        compatibility: { state, reasons },
+    };
+}
+//# sourceMappingURL=externalReferenceCompatibility.js.map

package/dist/domain/externalReferenceCompatibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"externalReferenceCompatibility.js","sourceRoot":"","sources":["../../src/domain/externalReferenceCompatibility.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,oCAAoC,EAAE,MAAM,uBAAuB,CAAC;AAU7E,SAAS,aAAa,CAAC,QAA2C;IAChE,OAAO,GAAG,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;AAChD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uCAAuC,CAAC,SAAoC,EAAE,SAA8B;IAC1H,MAAM,aAAa,GAAG,SAAS,CAAC,aAAa,CAAC;IAC9C,MAAM,OAAO,GAA0B,EAAE,CAAC;IAE1C,MAAM,sBAAsB,GAAG,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3G,MAAM,sBAAsB,GAAG,aAAa,CAAC,SAAS,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC/E,MAAM,cAAc,GAAG,oCAAoC,CACzD,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,iCAAiC,CAAC,oCAAoC,CAAC,EAAE,EACnF,mDAAmD,CACpD,CAAC;IACF,IAAI,cAAc;QAAE,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAEjD,MAAM,cAAc,GAAG,SAAS,CAAC,aAAa,CAAC,aAAa,CAAC;IAE7D,MAAM,WAAW,GAAG,oCAAoC,CACtD,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EAAE,KAAK,EACpB,cAAc,EAAE,KAAK,EACrB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,+BAA+B,CAAC,4CAA4C,CAAC,GAAG,EAC1F,iHAAiH,CAClH,CAAC;IACF,IAAI,WAAW;QAAE,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAE3C,MAAM,UAAU,GAAG,oCAAoC,CACrD,8BAA8B,EAC9B,gCAAgC,EAChC,aAAa,EAAE,kBAAkB,EACjC,cAAc,EAAE,kBAAkB,EAClC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,4CAA4C,CAAC,yDAAyD,CAAC,GAAG,EACpH,+HAA+H,CAChI,CAAC;IACF,IAAI,UAAU;QAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAEzC,MAAM,cAAc,GAAG,oCAAoC,CACzD,4BAA4B,EAC5B,8BAA8B,EAC9B,aAAa,EAAE,gBAAgB,EAC/B,cAAc,EAAE,gBAAgB,EAChC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,0CAA0C,CAAC,uDAAuD,CAAC,GAAG,EAChH,6HAA6H,CAC9H,CAAC;IACF,IAAI,cAAc;QAAE,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAEjD,2GAA2G;IAC3G,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,0BAA0B,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAEhH,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC;IAC7E,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC;IAC3E,MAAM,KAAK,GAAiC,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,YAAY,CAAC;IAElI,OAAO;QACL,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,kBAAkB,EAAE,SAAS,CAAC,kBAAkB;QAChD,sBAAsB,EAAE,SAAS,CAAC,aAAa;QAC/C,kBAAkB,EAAE,SAAS,CAAC,SAAS;QACvC,aAAa,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;KAClC,CAAC;AACJ,CAAC"}