@dailephd/my-frontend-observer 0.8.1

package/dist/domain/externalReferenceRuntimeBinding.js

@@ -0,0 +1,183 @@
+import { isValidExternalReferenceArtifact } from './externalReference.js';
+import { REFERENCE_REGION_ID_PATTERN } from './externalReferenceRegions.js';
+import { isValidObservationArtifact } from './schema.js';
+import { evaluateReferenceCandidateCompatibility } from './externalReferenceCompatibility.js';
+import { targetPresence } from './comparisonEngine.js';
+import { evidenceValue } from './evidence.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Independently-owned duplicate of request/request.ts's private
+ * `TARGET_NAME_RE` (`^[A-Za-z0-9_-]{1,64}$`) - same "stable, portable,
+ * log-safe identifier" convention already duplicated by
+ * `externalReferenceRegions.ts#REFERENCE_REGION_ID_PATTERN` and
+ * `explicitState.ts#STATE_LABEL_PATTERN`. Never imported cross-module, per
+ * the established per-module pattern-ownership convention.
+ */
+export const RUNTIME_TARGET_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** Mirrors `MAX_REFERENCE_REGIONS` (20) - a binding declaration collection is authoring input over the same region set, so the same bound applies; independently owned, not imported, since the two constants describe different collections that merely happen to share a value. */
+export const MAX_REFERENCE_RUNTIME_BINDINGS = 20;
+export const REFERENCE_RUNTIME_BINDING_STATUSES = ['bound', 'ambiguous', 'unavailable'];
+/**
+ * Closed, bounded reason vocabulary - one code per distinct evidence
+ * situation the evaluator can actually observe, mirroring the
+ * "one diagnostic code per validation domain" convention already used by
+ * `DIAGNOSTIC_CODES`. Never a place for a free-form or source-derived
+ * explanation; `detail` (free text) carries the human-readable specifics.
+ */
+export const REFERENCE_RUNTIME_BINDING_REASON_CODES = [
+    'runtime-target-not-configured',
+    'runtime-target-not-found',
+    'runtime-target-ambiguous',
+    'runtime-target-evidence-unavailable',
+];
+function isValidBindingDeclarationShape(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (typeof value.referenceRegion !== 'string' || !REFERENCE_REGION_ID_PATTERN.test(value.referenceRegion))
+        return false;
+    if (typeof value.runtimeTarget !== 'string' || !RUNTIME_TARGET_NAME_PATTERN.test(value.runtimeTarget))
+        return false;
+    const knownKeys = new Set(['referenceRegion', 'runtimeTarget']);
+    return Object.keys(value).every((key) => knownKeys.has(key));
+}
+/**
+ * Structural, candidate-independent validation: shape, bounds, uniqueness,
+ * and reference-region existence against the supplied
+ * `ExternalReferenceArtifact` only - this never touches a candidate
+ * observation (runtime-target availability is inherently per-candidate; see
+ * `evaluateReferenceRuntimeBindings`). A reference with no `regions` at all
+ * (Prompt 1/2-era artifact, or one that simply declared none) makes every
+ * binding declaration fail closed - there is nothing to bind against.
+ *
+ * Duplicate/conflicting-subject rule (mirrors Prompt 3's requirement-subject
+ * uniqueness rule exactly): no two declarations may name the same
+ * `referenceRegion` (case-insensitively), regardless of whether their
+ * `runtimeTarget` values agree (an exact duplicate) or disagree (a
+ * conflict) - both are rejected identically, fail-closed, never resolved by
+ * silently keeping the first. The reverse - several distinct reference
+ * regions naming the same `runtimeTarget` - is deliberately allowed: two
+ * design sub-regions may legitimately correspond to one runtime container
+ * element, whereas one region needing several runtime targets would be
+ * inherently ambiguous about which target represents it (the "one region,
+ * one explicit primary target" rule).
+ */
+export function isValidReferenceRuntimeBindingDeclarations(value, reference) {
+    if (!Array.isArray(value))
+        return { valid: false, reason: 'bindings must be an array' };
+    if (value.length > MAX_REFERENCE_RUNTIME_BINDINGS) {
+        return { valid: false, reason: `bindings must contain at most ${MAX_REFERENCE_RUNTIME_BINDINGS} entries` };
+    }
+    const referenceValidation = isValidExternalReferenceArtifact(reference);
+    if (!referenceValidation.valid)
+        return { valid: false, reason: `reference is invalid: ${referenceValidation.reason}` };
+    const knownRegionIds = new Set((reference.regions ?? []).map((r) => r.id.toLowerCase()));
+    const seenRegions = new Set();
+    for (const entry of value) {
+        if (!isValidBindingDeclarationShape(entry)) {
+            return { valid: false, reason: 'each binding must be { referenceRegion, runtimeTarget }, both matching ^[A-Za-z0-9_-]{1,64}$' };
+        }
+        const lowerRegion = entry.referenceRegion.toLowerCase();
+        if (!knownRegionIds.has(lowerRegion)) {
+            return { valid: false, reason: `binding refers to unknown reference region id "${entry.referenceRegion}"` };
+        }
+        if (seenRegions.has(lowerRegion)) {
+            return { valid: false, reason: `duplicate or conflicting binding declaration for reference region "${entry.referenceRegion}"` };
+        }
+        seenRegions.add(lowerRegion);
+    }
+    return { valid: true };
+}
+function findConfiguredTargetName(candidate, runtimeTarget) {
+    const lower = runtimeTarget.toLowerCase();
+    return candidate.requestConfig.targets.find((t) => t.name.toLowerCase() === lower)?.name;
+}
+function evaluateOneBinding(candidate, declaration) {
+    const configuredName = findConfiguredTargetName(candidate, declaration.runtimeTarget);
+    if (configuredName === undefined) {
+        return {
+            referenceRegion: declaration.referenceRegion,
+            runtimeTarget: declaration.runtimeTarget,
+            status: 'unavailable',
+            reasonCode: 'runtime-target-not-configured',
+            detail: `runtime target "${declaration.runtimeTarget}" was not part of this candidate observation's configured target set`,
+        };
+    }
+    const record = candidate.targetEvidence[configuredName];
+    const presence = targetPresence(record);
+    const resolution = record ? evidenceValue(record.resolution) : undefined;
+    const visibility = record ? evidenceValue(record.visibility) : undefined;
+    const targetResolutionStatus = resolution?.selectionStatus;
+    if (presence === 'matched') {
+        return {
+            referenceRegion: declaration.referenceRegion,
+            runtimeTarget: declaration.runtimeTarget,
+            status: 'bound',
+            detail: `runtime target "${declaration.runtimeTarget}" resolved uniquely for this candidate observation`,
+            ...(targetResolutionStatus !== undefined ? { targetResolutionStatus } : {}),
+            ...(visibility !== undefined ? { targetVisible: visibility.visible } : {}),
+        };
+    }
+    if (presence === 'ambiguous') {
+        return {
+            referenceRegion: declaration.referenceRegion,
+            runtimeTarget: declaration.runtimeTarget,
+            status: 'ambiguous',
+            reasonCode: 'runtime-target-ambiguous',
+            detail: `runtime target "${declaration.runtimeTarget}" resolved ambiguously (more than one match) for this candidate observation`,
+            ...(targetResolutionStatus !== undefined ? { targetResolutionStatus } : {}),
+        };
+    }
+    if (presence === 'not-found') {
+        return {
+            referenceRegion: declaration.referenceRegion,
+            runtimeTarget: declaration.runtimeTarget,
+            status: 'unavailable',
+            reasonCode: 'runtime-target-not-found',
+            detail: `runtime target "${declaration.runtimeTarget}" was configured but not found on the candidate observation's page`,
+            ...(targetResolutionStatus !== undefined ? { targetResolutionStatus } : {}),
+        };
+    }
+    return {
+        referenceRegion: declaration.referenceRegion,
+        runtimeTarget: declaration.runtimeTarget,
+        status: 'unavailable',
+        reasonCode: 'runtime-target-evidence-unavailable',
+        detail: `runtime target "${declaration.runtimeTarget}" has no usable resolution evidence in this candidate observation`,
+        ...(targetResolutionStatus !== undefined ? { targetResolutionStatus } : {}),
+    };
+}
+/**
+ * Pure and synchronous: no browser, no filesystem, no network, no second
+ * target resolver. Validates both artifacts and the declaration collection,
+ * runs the Prompt 4 compatibility gate exactly once, and - only when the
+ * candidate is not `incomparable` with the reference - evaluates each
+ * declaration in authored order against the candidate's own already-
+ * captured `requestConfig.targets`/`targetEvidence`. Mutates neither input.
+ */
+export function evaluateReferenceRuntimeBindings(reference, candidate, declarations) {
+    const referenceValidation = isValidExternalReferenceArtifact(reference);
+    if (!referenceValidation.valid)
+        return { ok: false, reason: `reference is invalid: ${referenceValidation.reason}` };
+    const candidateValidation = isValidObservationArtifact(candidate);
+    if (!candidateValidation.valid)
+        return { ok: false, reason: `candidate is invalid: ${candidateValidation.reason}` };
+    const declarationsValidation = isValidReferenceRuntimeBindingDeclarations(declarations, reference);
+    if (!declarationsValidation.valid)
+        return { ok: false, reason: declarationsValidation.reason };
+    const compatibilityResult = evaluateReferenceCandidateCompatibility(reference, candidate);
+    const bindings = compatibilityResult.compatibility.state === 'incomparable' ? [] : declarations.map((declaration) => evaluateOneBinding(candidate, declaration));
+    return {
+        ok: true,
+        evaluation: {
+            referenceId: compatibilityResult.referenceId,
+            referenceRequestId: compatibilityResult.referenceRequestId,
+            candidateObservationId: compatibilityResult.candidateObservationId,
+            candidateRequestId: compatibilityResult.candidateRequestId,
+            compatibility: compatibilityResult.compatibility,
+            bindings,
+        },
+    };
+}
+//# sourceMappingURL=externalReferenceRuntimeBinding.js.map

package/dist/domain/externalReferenceRuntimeBinding.js.map

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

package/dist/domain/frontendContractEvaluation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * v0.5 Batch 2 canonical pure frontend contract evaluation engine. Consumes
+ * already-loaded evidence (before/after ObservationArtifact, ComparisonArtifact,
+ * PersistentBaselineContract, PerChangeContract - all frozen by v0.4/Batch 1) and
+ * derives per-clause results plus one overall PASS/FAIL verdict. Pure and
+ * synchronous: no Chromium, no filesystem, no target re-resolution, no
+ * reimplementation of v0.4 comparison/relationship/clipping/scroll-owner logic.
+ * Mutates none of its inputs. This module owns no persistence, no CLI, and no
+ * unexpected-change *authoring* semantics - `unexpected` remains a derived
+ * classification only, never an authored category (see domain/frontendContracts.ts).
+ */
+import type { EvidenceReference } from './relationships.js';
+import type { ObservationArtifact } from './schema.js';
+import type { ComparisonArtifact, ComparisonDifferenceSubject, DifferenceKind } from './comparison.js';
+import type { PersistentBaselineContract, PerChangeContract, ClauseEvaluationResult, OverallVerdict } from './frontendContracts.js';
+export interface FrontendContractEvaluationInput {
+    before: ObservationArtifact;
+    after: ObservationArtifact;
+    comparison: ComparisonArtifact;
+    baseline: PersistentBaselineContract;
+    change: PerChangeContract;
+}
+/** A meaningful rendered difference not accounted for by any active authored clause - derived only, never authorable. */
+export interface UnexpectedChangeResult {
+    classification: 'unexpected';
+    subject: ComparisonDifferenceSubject;
+    differenceKind: DifferenceKind;
+    supportingEvidence: EvidenceReference[];
+}
+export interface FrontendContractEvaluationResult {
+    overallVerdict: OverallVerdict;
+    activeBaselineClauseIds: string[];
+    supersededBaselineClauseIds: string[];
+    clauseResults: ClauseEvaluationResult[];
+    unexpectedChanges: UnexpectedChangeResult[];
+}
+export type EvaluateFrontendContractResult = {
+    ok: true;
+    evaluation: FrontendContractEvaluationResult;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The one canonical pure v0.5 contract-evaluation entry point:
+ * `active persistent baseline contracts + current per-change contract + actual
+ * before/after runtime evidence -> PASS | FAIL` with full clause-level
+ * evidence. Deterministic given identical inputs; never mutates
+ * before/after/comparison/baseline/change.
+ *
+ * NOTE: `comparison.differences` already includes one `ComparisonDifference`
+ * per `RelationshipChangeRecord` (see `comparisonEngine.ts#relationshipChangesToDifferences`),
+ * so unexpected-change derivation consumes `differences` only - iterating
+ * `relationshipChanges` separately would double-count the same logical
+ * transition.
+ */
+export declare function evaluateFrontendContract(input: FrontendContractEvaluationInput): EvaluateFrontendContractResult;