@dailephd/my-frontend-observer 0.8.1

package/dist/domain/referenceCorrectionWorkflow.js

@@ -0,0 +1,165 @@
+import { isValidExternalReferenceArtifact, isApprovedExternalReferenceArtifact } from './externalReference.js';
+import { isValidObservationArtifact } from './schema.js';
+import { isValidPersistentBaselineContract, isValidPerChangeContract } from './frontendContracts.js';
+import { compareObservations } from './comparisonEngine.js';
+import { evaluateFrontendContract } from './frontendContractEvaluation.js';
+import { isValidReferenceRuntimeBindingDeclarations } from './externalReferenceRuntimeBinding.js';
+import { evaluateReferenceCandidateFidelity } from './externalReferenceFidelity.js';
+import { projectBoundedAgentContext } from './boundedAgentContextProjection.js';
+import { buildReferenceCorrectionReviewIdentity, buildReferenceCorrectionAttemptIdentity } from './referenceCorrectionIdentity.js';
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function validateCommon(input) {
+    const referenceValidation = isValidExternalReferenceArtifact(input.reference);
+    if (!referenceValidation.valid)
+        return `reference is invalid: ${referenceValidation.reason}`;
+    if (!isApprovedExternalReferenceArtifact(input.reference)) {
+        return 'reference must be approved (lifecycle.state !== "approved") - an imported-but-unapproved reference is never treated as an authoritative target design by this workflow';
+    }
+    const baselineObservationValidation = isValidObservationArtifact(input.baselineObservation);
+    if (!baselineObservationValidation.valid)
+        return `baselineObservation is invalid: ${baselineObservationValidation.reason}`;
+    const baselineContractValidation = isValidPersistentBaselineContract(input.baselineContract);
+    if (!baselineContractValidation.valid)
+        return `baselineContract is invalid: ${baselineContractValidation.reason}`;
+    if (input.baselineContract.sourceObservation.observationId !== input.baselineObservation.observationId) {
+        return 'baselineContract.sourceObservation.observationId does not match the supplied baselineObservation';
+    }
+    const changeContractValidation = isValidPerChangeContract(input.changeContract);
+    if (!changeContractValidation.valid)
+        return `changeContract is invalid: ${changeContractValidation.reason}`;
+    const bindingsValidation = isValidReferenceRuntimeBindingDeclarations(input.bindingDeclarations, input.reference);
+    if (!bindingsValidation.valid)
+        return `bindingDeclarations is invalid: ${bindingsValidation.reason}`;
+    return undefined;
+}
+function reviewIdentityFor(input) {
+    return buildReferenceCorrectionReviewIdentity(input.reference.referenceRequestId, input.baselineObservation.observationId, input.baselineContract.baselineId, input.baselineContract.clauses, input.changeContract.contractId, input.changeContract.clauses, input.bindingDeclarations);
+}
+const VERIFICATION_PLAN = [
+    'A fresh candidate observation will be captured through the existing real-Chromium observation pipeline after the external edit.',
+    'The approved external reference will be re-evaluated against that fresh candidate using the same explicit runtime-target bindings (v0.7 Prompt 6 reference fidelity).',
+    'The same approved baseline observation will be compared against the fresh candidate using canonical v0.4 comparison, then evaluated against the still-active baseline and per-change contracts using canonical v0.5 contract evaluation.',
+    'Overall PASS requires both reference fidelity PASS and v0.5 contract evaluation PASS - matching the reference alone is necessary but not sufficient.',
+];
+/**
+ * Pure and synchronous: no browser, no filesystem, no network, no remote AI
+ * call. Evaluates the approved reference against the supplied current
+ * (pre-change) observation via Prompt 6, then - only when that evaluation
+ * actually produced a result (`state !== 'not-evaluated'`) - projects it
+ * into a bounded coding-agent context via Prompt 7/v0.6 and returns the
+ * handoff. A `not-evaluated` fidelity (inadequate reference, or reference/
+ * candidate incompatible state) is reported honestly as `blocked-not-
+ * evaluated`, carrying the full Prompt 6 result for inspection, but never a
+ * fabricated handoff that pretends evidence is adequate.
+ */
+export function prepareReferenceCorrection(input) {
+    const commonError = validateCommon(input);
+    if (commonError)
+        return { ok: false, reason: commonError };
+    const currentValidation = isValidObservationArtifact(input.currentObservation);
+    if (!currentValidation.valid)
+        return { ok: false, reason: `currentObservation is invalid: ${currentValidation.reason}` };
+    if (!isNonEmptyString(input.generatedAt))
+        return { ok: false, reason: 'generatedAt must be a non-empty string' };
+    if (!isNonEmptyString(input.producerVersion))
+        return { ok: false, reason: 'producerVersion must be a non-empty string' };
+    const reviewRequestId = reviewIdentityFor(input);
+    const geometryOptions = input.fidelityGeometryTolerancePx !== undefined ? { geometryTolerancePx: input.fidelityGeometryTolerancePx } : {};
+    const fidelityResult = evaluateReferenceCandidateFidelity(input.reference, input.currentObservation, input.bindingDeclarations, geometryOptions);
+    if (!fidelityResult.ok)
+        return { ok: false, reason: `reference fidelity could not be evaluated: ${fidelityResult.reason}` };
+    const fidelity = fidelityResult.evaluation;
+    if (fidelity.state === 'not-evaluated') {
+        return { ok: true, status: 'blocked-not-evaluated', reviewRequestId, fidelity };
+    }
+    const boundedContextResult = projectBoundedAgentContext({
+        generatedAt: input.generatedAt,
+        producerVersion: input.producerVersion,
+        projectionProfile: input.projectionProfile,
+        focusTargetIds: [],
+        observation: input.currentObservation,
+        fidelity,
+    });
+    if (!boundedContextResult.ok)
+        return { ok: false, reason: `bounded context could not be constructed: ${boundedContextResult.reason}` };
+    const handoff = {
+        reviewRequestId,
+        referenceId: input.reference.referenceId,
+        referenceRequestId: input.reference.referenceRequestId,
+        baselineObservationId: input.baselineObservation.observationId,
+        currentObservationId: input.currentObservation.observationId,
+        boundedContext: boundedContextResult.artifact,
+        verificationPlan: VERIFICATION_PLAN,
+    };
+    return { ok: true, status: 'handoff-ready', reviewRequestId, fidelity, handoff };
+}
+// ---------------------------------------------------------------------------
+// C/D. REVIEW: fresh post-edit candidate -> one overall attempt result
+// ---------------------------------------------------------------------------
+export const REFERENCE_CORRECTION_OVERALL_STATES = ['not-evaluated', 'pass', 'fail'];
+/**
+ * Pure and synchronous: no browser, no filesystem, no network, no remote AI
+ * call, no source access. Consumes exactly one already-captured candidate
+ * `ObservationArtifact` (the caller is responsible for capturing it through
+ * the existing real-Chromium observation pipeline after the external actor
+ * has edited target source) and composes the canonical v0.4 comparison,
+ * v0.7 Prompt 6 fidelity, and v0.5 contract evaluation into one overall
+ * result - reimplementing none of them. Every attempt evaluates the
+ * candidate against the *same* supplied `baselineObservation`/
+ * `baselineContract`/`changeContract` - this function has no mechanism to
+ * compare against a prior attempt's candidate instead, so accumulated
+ * drift from the approved baseline can never be hidden.
+ */
+export function reviewReferenceCorrectionAttempt(input) {
+    const commonError = validateCommon(input);
+    if (commonError)
+        return { ok: false, reason: commonError };
+    const candidateValidation = isValidObservationArtifact(input.candidateObservation);
+    if (!candidateValidation.valid)
+        return { ok: false, reason: `candidateObservation is invalid: ${candidateValidation.reason}` };
+    if (!isNonEmptyString(input.reviewRequestId))
+        return { ok: false, reason: 'reviewRequestId must be a non-empty string' };
+    const expectedReviewRequestId = reviewIdentityFor(input);
+    if (input.reviewRequestId !== expectedReviewRequestId) {
+        return { ok: false, reason: 'reviewRequestId does not match the supplied reference/baseline/contracts/bindings (it must be the exact id prepareReferenceCorrection returned for this same semantic review)' };
+    }
+    const comparisonResult = compareObservations(input.baselineObservation, input.candidateObservation, input.comparisonConfig ?? {});
+    if (!comparisonResult.ok)
+        return { ok: false, reason: `baseline/candidate comparison could not be computed: ${comparisonResult.reason}` };
+    const comparison = comparisonResult.artifact;
+    const geometryOptions = input.fidelityGeometryTolerancePx !== undefined ? { geometryTolerancePx: input.fidelityGeometryTolerancePx } : {};
+    const fidelityResult = evaluateReferenceCandidateFidelity(input.reference, input.candidateObservation, input.bindingDeclarations, geometryOptions);
+    if (!fidelityResult.ok)
+        return { ok: false, reason: `reference fidelity could not be evaluated: ${fidelityResult.reason}` };
+    const fidelity = fidelityResult.evaluation;
+    const contractEvaluationResult = evaluateFrontendContract({
+        before: input.baselineObservation,
+        after: input.candidateObservation,
+        comparison,
+        baseline: input.baselineContract,
+        change: input.changeContract,
+    });
+    if (!contractEvaluationResult.ok)
+        return { ok: false, reason: `contract evaluation could not be computed: ${contractEvaluationResult.reason}` };
+    const contractEvaluation = contractEvaluationResult.evaluation;
+    const overallState = fidelity.state === 'not-evaluated' ? 'not-evaluated' : fidelity.state === 'pass' && contractEvaluation.overallVerdict === 'PASS' ? 'pass' : 'fail';
+    const attemptId = buildReferenceCorrectionAttemptIdentity(input.reviewRequestId, input.candidateObservation.observationId);
+    const attempt = {
+        reviewRequestId: input.reviewRequestId,
+        attemptId,
+        ...(input.priorAttemptId !== undefined ? { priorAttemptId: input.priorAttemptId } : {}),
+        referenceId: input.reference.referenceId,
+        referenceRequestId: input.reference.referenceRequestId,
+        baselineObservationId: input.baselineObservation.observationId,
+        candidateObservationId: input.candidateObservation.observationId,
+        comparison,
+        fidelity,
+        contractEvaluation,
+        overallState,
+        approvalEligible: overallState === 'pass',
+    };
+    return { ok: true, attempt };
+}
+//# sourceMappingURL=referenceCorrectionWorkflow.js.map

package/dist/domain/referenceCorrectionWorkflow.js.map

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

package/dist/domain/referenceFidelityProjection.d.ts

@@ -0,0 +1,65 @@
+/**
+ * v0.7 Prompt 7 bounded reference-fidelity projection. Consumes an
+ * already-computed `ReferenceCandidateFidelityEvaluation` (v0.7 Prompt 6)
+ * and selects a small, bounded, deterministically-prioritized subset of it
+ * suitable for a coding agent's bounded context - never a second fidelity-
+ * evaluation engine, never a recomputation of adequacy/compatibility/
+ * binding/tolerance/relationship logic (all reused verbatim from their
+ * existing Prompt 3/4/5/6 owners).
+ *
+ * This module is pure and synchronous: no browser, no filesystem, no
+ * network, no my-dev-kit invocation. It mutates none of its inputs.
+ *
+ * Output shape (`BoundedReferenceFidelityProjection`) is frozen by
+ * `domain/boundedAgentContext.ts`; this module only derives one, plus the
+ * runtime-target-id/omission/truncation side effects
+ * `boundedAgentContextProjection.ts` needs to fold into its own existing
+ * required/permitted-target allocation and adequacy computation - it never
+ * builds a second, parallel bounded-context artifact.
+ */
+import type { BoundedReferenceFidelityProjection, OmissionRecord, TruncationRecord } from './boundedAgentContext.js';
+import type { ReferenceCandidateFidelityEvaluation } from './externalReferenceFidelity.js';
+export interface ProjectReferenceFidelityOptions {
+    /**
+     * Whether this bounded-context request's coding-agent task depends on
+     * reference-fidelity evidence. Defaults to `true`: supplying a fidelity
+     * evaluation to be projected at all is itself the signal that the task
+     * cares about it, mirroring `CorrelationTargetInput.required`'s existing
+     * v0.6 convention. Set `false` only when fidelity is included purely as
+     * incidental context whose unavailability must never affect adequacy.
+     */
+    required?: boolean;
+}
+export interface ProjectReferenceFidelityOutput {
+    projection: BoundedReferenceFidelityProjection;
+    /** Runtime target ids the caller should fold into its own required-tier target set (contributed by required-tier mismatches only). */
+    requiredTargetIds: string[];
+    /** Runtime target ids the caller should fold into its own permitted-tier target set (contributed by optional-tier mismatches and by protected/preserved context). */
+    permittedTargetIds: string[];
+    omissions: OmissionRecord[];
+    truncations: TruncationRecord[];
+}
+/**
+ * Selects, prioritizes, and bounds one fidelity evaluation's non-passing
+ * requirement results plus its passing protected/preserved context, per the
+ * documented selection policy (see docs/CONTRACTS.md "v0.7 Prompt 7"):
+ *
+ * 1. failed required-tier requirements
+ * 2. unavailable required-tier requirements
+ * 3. any other non-pass (optional-tier) requirement
+ *
+ * Within a priority class, authored/Prompt-6 order is preserved (a stable
+ * sort by priority rank only, never a secondary re-sort). Passing
+ * requirements are never dumped by default - only passing `protected`/
+ * `preserved` results are surfaced, as bounded "do not break this" context,
+ * disjoint from `mismatches` (a *failing* protected/preserved requirement
+ * already appears there, at the highest priority, so it is never
+ * duplicated into `protectedContext` too).
+ *
+ * A `not-evaluated` fidelity state never produces `mismatches`/
+ * `protectedContext` content - the blocker is preserved via `blockedBy`,
+ * and (when `options.required` is true, the default) an explicit
+ * `required: true` omission is recorded so a caller folding this into its
+ * own adequacy computation can never end up falsely `adequate`.
+ */
+export declare function projectReferenceFidelity(fidelity: ReferenceCandidateFidelityEvaluation, options?: ProjectReferenceFidelityOptions): ProjectReferenceFidelityOutput;

package/dist/domain/referenceFidelityProjection.js

@@ -0,0 +1,135 @@
+import { MAX_FIDELITY_MISMATCHES, MAX_FIDELITY_PROTECTED_CONTEXT } from './boundedAgentContext.js';
+/**
+ * Mirrors `boundedAgentContextProjection.ts#clauseTier`'s exact rule
+ * (duplicated, not imported, per this repository's established per-module
+ * small-helper-ownership convention): `protected`/`preserved` are always
+ * required; `expected-dependent` is required only in `'required'` mode
+ * (`'permitted'` mode is optional); `requested` is always optional. Reused
+ * verbatim rather than reinvented, per this prompt's explicit instruction
+ * not to create reference-specific protected/preserved semantics.
+ */
+function fidelityRequirementTier(category, mode) {
+    if (category === 'protected' || category === 'preserved')
+        return 'required';
+    if (category === 'expected-dependent')
+        return mode === 'required' ? 'required' : 'optional';
+    return 'optional'; // 'requested'
+}
+function dedupePreservingOrder(ids) {
+    const seen = new Set();
+    const result = [];
+    for (const id of ids) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        result.push(id);
+    }
+    return result;
+}
+function baseProjectionFields(fidelity) {
+    return {
+        referenceId: fidelity.referenceId,
+        referenceRequestId: fidelity.referenceRequestId,
+        candidateObservationId: fidelity.candidateObservationId,
+        candidateRequestId: fidelity.candidateRequestId,
+        adequacy: fidelity.adequacy,
+        ...(fidelity.compatibility !== undefined ? { compatibility: fidelity.compatibility } : {}),
+        state: fidelity.state,
+        ...(fidelity.blockedBy !== undefined ? { blockedBy: fidelity.blockedBy } : {}),
+    };
+}
+/**
+ * Selects, prioritizes, and bounds one fidelity evaluation's non-passing
+ * requirement results plus its passing protected/preserved context, per the
+ * documented selection policy (see docs/CONTRACTS.md "v0.7 Prompt 7"):
+ *
+ * 1. failed required-tier requirements
+ * 2. unavailable required-tier requirements
+ * 3. any other non-pass (optional-tier) requirement
+ *
+ * Within a priority class, authored/Prompt-6 order is preserved (a stable
+ * sort by priority rank only, never a secondary re-sort). Passing
+ * requirements are never dumped by default - only passing `protected`/
+ * `preserved` results are surfaced, as bounded "do not break this" context,
+ * disjoint from `mismatches` (a *failing* protected/preserved requirement
+ * already appears there, at the highest priority, so it is never
+ * duplicated into `protectedContext` too).
+ *
+ * A `not-evaluated` fidelity state never produces `mismatches`/
+ * `protectedContext` content - the blocker is preserved via `blockedBy`,
+ * and (when `options.required` is true, the default) an explicit
+ * `required: true` omission is recorded so a caller folding this into its
+ * own adequacy computation can never end up falsely `adequate`.
+ */
+export function projectReferenceFidelity(fidelity, options = {}) {
+    const required = options.required ?? true;
+    const base = baseProjectionFields(fidelity);
+    if (fidelity.state === 'not-evaluated') {
+        const omissions = [
+            {
+                subject: 'fidelity',
+                reason: 'unsupported-or-unavailable',
+                required,
+                detail: `reference fidelity could not be evaluated (blockedBy: ${fidelity.blockedBy ?? 'unknown'})`,
+            },
+        ];
+        return {
+            projection: { ...base, mismatches: [], protectedContext: [] },
+            requiredTargetIds: [],
+            permittedTargetIds: [],
+            omissions,
+            truncations: [],
+        };
+    }
+    const omissions = [];
+    const truncations = [];
+    const nonPass = fidelity.requirementResults.filter((r) => r.status !== 'pass');
+    const ranked = nonPass.map((result, index) => {
+        const tier = fidelityRequirementTier(result.category, result.expectedDependentMode);
+        const rank = result.status === 'fail' && tier === 'required' ? 0 : result.status === 'unavailable' && tier === 'required' ? 1 : 2;
+        return { result, tier, rank, index };
+    });
+    const orderedRanked = [...ranked].sort((a, b) => (a.rank !== b.rank ? a.rank - b.rank : a.index - b.index));
+    const includedRanked = orderedRanked.slice(0, MAX_FIDELITY_MISMATCHES);
+    const droppedRanked = orderedRanked.slice(MAX_FIDELITY_MISMATCHES);
+    for (const dropped of droppedRanked) {
+        if (dropped.tier === 'required') {
+            omissions.push({ subject: `fidelity-mismatch:${dropped.result.requirementId}`, reason: 'required-evidence-lost-by-bound', required: true });
+        }
+    }
+    if (droppedRanked.length > 0) {
+        truncations.push({
+            subject: 'fidelity-mismatches',
+            limit: MAX_FIDELITY_MISMATCHES,
+            actualCount: nonPass.length,
+            required: droppedRanked.some((d) => d.tier === 'required'),
+        });
+    }
+    // Reported order is priority-first (failed-required, then unavailable-required, then other
+    // non-pass), with Prompt-6 authored order preserved only as the tie-breaker within one priority
+    // class - `includedRanked` is already exactly this order (see the sort above).
+    const mismatches = includedRanked.map((r) => r.result);
+    const protectedCandidates = fidelity.requirementResults.filter((r) => r.status === 'pass' && (r.category === 'protected' || r.category === 'preserved'));
+    const protectedContext = protectedCandidates.slice(0, MAX_FIDELITY_PROTECTED_CONTEXT);
+    if (protectedCandidates.length > MAX_FIDELITY_PROTECTED_CONTEXT) {
+        truncations.push({
+            subject: 'fidelity-protected-context',
+            limit: MAX_FIDELITY_PROTECTED_CONTEXT,
+            actualCount: protectedCandidates.length,
+            required: false,
+        });
+    }
+    const requiredTargetIds = dedupePreservingOrder(mismatches.filter((m) => fidelityRequirementTier(m.category, m.expectedDependentMode) === 'required').flatMap((m) => m.boundRuntimeTargets));
+    const requiredSet = new Set(requiredTargetIds);
+    const permittedTargetIds = dedupePreservingOrder([...mismatches.filter((m) => fidelityRequirementTier(m.category, m.expectedDependentMode) === 'optional'), ...protectedContext]
+        .flatMap((m) => m.boundRuntimeTargets)
+        .filter((id) => !requiredSet.has(id)));
+    return {
+        projection: { ...base, mismatches, protectedContext },
+        requiredTargetIds,
+        permittedTargetIds,
+        omissions,
+        truncations,
+    };
+}
+//# sourceMappingURL=referenceFidelityProjection.js.map

package/dist/domain/referenceFidelityProjection.js.map

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

package/dist/domain/relationships.d.ts

@@ -0,0 +1,210 @@
+/**
+ * v0.4 Batch 1 layout-relationship contract, plus the Batch 2 pure
+ * derivation engine (`deriveLayoutRelationships`) that consumes it. This
+ * module owns geometry tolerance (needed directly by the engine below, so it
+ * cannot be imported from domain/comparison.ts without a cycle - see the
+ * re-export there) and never imports domain/comparison.ts.
+ */
+import type { ObservationArtifact, TargetEvidenceRecord, TargetGeometry } from './schema.js';
+/** Suppresses insignificant geometry noise only - never a design contract, never permission for changes. */
+export declare const GEOMETRY_TOLERANCE_DEFAULT_PX = 0.5;
+export declare const GEOMETRY_TOLERANCE_MIN_PX = 0;
+export declare const GEOMETRY_TOLERANCE_MAX_PX = 10;
+export declare function isValidGeometryTolerancePx(value: unknown): value is number;
+export declare const HORIZONTAL_ORDER_RELATIONSHIPS: readonly ["left-of", "right-of", "horizontally-overlapping"];
+export type HorizontalOrderRelationship = (typeof HORIZONTAL_ORDER_RELATIONSHIPS)[number];
+export declare const VERTICAL_ORDER_RELATIONSHIPS: readonly ["above", "below", "vertically-overlapping"];
+export type VerticalOrderRelationship = (typeof VERTICAL_ORDER_RELATIONSHIPS)[number];
+export declare const AREA_OVERLAP_RELATIONSHIPS: readonly ["overlaps", "does-not-overlap"];
+export type AreaOverlapRelationship = (typeof AREA_OVERLAP_RELATIONSHIPS)[number];
+export declare const RELATIVE_WIDTH_RELATIONSHIPS: readonly ["wider-than", "narrower-than", "equal-width-within-tolerance"];
+export type RelativeWidthRelationship = (typeof RELATIVE_WIDTH_RELATIONSHIPS)[number];
+export declare const GEOMETRIC_FIT_RELATIONSHIPS: readonly ["fits-inside", "does-not-fit-inside"];
+export type GeometricFitRelationship = (typeof GEOMETRIC_FIT_RELATIONSHIPS)[number];
+/** Rendered-geometry sequencing only - never source DOM order (see docs/CONTRACTS.md target containment discussion). */
+export declare const VERTICAL_SEQUENCE_RELATIONSHIPS: readonly ["follows-vertically"];
+export type VerticalSequenceRelationship = (typeof VERTICAL_SEQUENCE_RELATIONSHIPS)[number];
+export declare const PAGE_WIDTH_RELATIONSHIPS: readonly ["document-width-fits-viewport", "document-width-exceeds-viewport"];
+export type PageWidthRelationship = (typeof PAGE_WIDTH_RELATIONSHIPS)[number];
+/** Every pairwise (two-target) relationship kind this batch freezes. Deliberately bounded - not a general-purpose spatial language. */
+export declare const PAIRWISE_RELATIONSHIP_KINDS: readonly ["left-of", "right-of", "horizontally-overlapping", "above", "below", "vertically-overlapping", "overlaps", "does-not-overlap", "wider-than", "narrower-than", "equal-width-within-tolerance", "fits-inside", "does-not-fit-inside", "follows-vertically"];
+export type PairwiseRelationshipKind = (typeof PAIRWISE_RELATIONSHIP_KINDS)[number];
+/** Every page-level (no target pair) relationship kind this batch freezes. */
+export declare const PAGE_LEVEL_RELATIONSHIP_KINDS: readonly ["document-width-fits-viewport", "document-width-exceeds-viewport"];
+export type PageLevelRelationshipKind = (typeof PAGE_LEVEL_RELATIONSHIP_KINDS)[number];
+/** Points at the supporting observation evidence a derived relationship/difference was computed from (e.g. `targetEvidence.workspace.geometry`, `pageEvidence.documentSize`) - never a duplicated copy of the measurement itself. */
+export interface EvidenceReference {
+    path: string;
+}
+export declare function isValidEvidenceReference(value: unknown): value is EvidenceReference;
+/** One derived spatial relationship between two configured targets, with explicit supporting evidence provenance. */
+export interface PairwiseLayoutRelationship {
+    kind: PairwiseRelationshipKind;
+    subjectTarget: string;
+    relatedTarget: string;
+    evidence: EvidenceReference[];
+}
+export declare function isValidPairwiseLayoutRelationship(value: unknown): value is PairwiseLayoutRelationship;
+/** One derived page-level (no target pair) relationship. */
+export interface PageLevelLayoutRelationship {
+    kind: PageLevelRelationshipKind;
+    evidence: EvidenceReference[];
+}
+export declare function isValidPageLevelLayoutRelationship(value: unknown): value is PageLevelLayoutRelationship;
+/** A configured target excluded from relationship derivation because it lacks usable geometry - never a fabricated zero-sized rectangle. */
+export declare const UNRESOLVED_TARGET_REASONS: readonly ["not-found", "ambiguous", "unavailable", "hidden"];
+export type UnresolvedTargetReason = (typeof UNRESOLVED_TARGET_REASONS)[number];
+export interface UnresolvedRelationshipTarget {
+    target: string;
+    reason: UnresolvedTargetReason;
+}
+export declare function isValidUnresolvedRelationshipTarget(value: unknown): value is UnresolvedRelationshipTarget;
+/**
+ * Bounded structured relationship graph for one observation. Existing
+ * requests allow at most 20 configured targets, so the pairwise layer is
+ * bounded at 20*19/2 = 190 unordered pairs; this contract never traverses
+ * arbitrary DOM nodes or derives relationships for unconfigured elements.
+ */
+export interface LayoutRelationshipGraph {
+    observationId: string;
+    requestId: string;
+    geometryTolerancePx: number;
+    targets: string[];
+    unresolvedTargets: UnresolvedRelationshipTarget[];
+    pairwiseRelationships: PairwiseLayoutRelationship[];
+    pageRelationships: PageLevelLayoutRelationship[];
+}
+export declare const MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS = 20;
+export declare const MAX_PAIRWISE_RELATIONSHIP_PAIRS: number;
+/**
+ * A single unordered pair can carry up to one record per independent
+ * pairwise relationship family (horizontal-order, vertical-order,
+ * area-overlap, relative-width, geometric-fit, vertical-sequence - see
+ * `deriveLayoutRelationships` below), never more than one per family per
+ * pair. This is the resulting bound on `pairwiseRelationships.length`, not a
+ * second target-count configuration.
+ */
+export declare const PAIRWISE_RELATIONSHIP_FAMILY_COUNT = 6;
+export declare const MAX_PAIRWISE_RELATIONSHIP_RECORDS: number;
+export declare function isValidLayoutRelationshipGraph(value: unknown): value is LayoutRelationshipGraph;
+/**
+ * Bounded derived clipping concept (docs/PROJECT_MILESTONES.md Milestone 4).
+ * `clipped` requires both actual dimensional overflow on that axis AND a
+ * computed `overflow` value of `hidden`/`clip` on that axis - `auto`,
+ * `scroll`, and `visible` never classify as clipped solely from dimensional
+ * overflow. `unavailable` when the underlying overflow/geometry evidence
+ * cannot support a conclusion - never guessed.
+ */
+export declare const CLIPPING_STATES: readonly ["clipped", "not-clipped", "unavailable"];
+export type ClippingState = (typeof CLIPPING_STATES)[number];
+export declare const CLIPPING_OVERFLOW_STYLES: readonly ["hidden", "clip"];
+export type ClippingOverflowStyle = (typeof CLIPPING_OVERFLOW_STYLES)[number];
+export interface TargetClippingEvidence {
+    horizontal: ClippingState;
+    vertical: ClippingState;
+}
+export declare function isValidTargetClippingEvidence(value: unknown): value is TargetClippingEvidence;
+/**
+ * Pure per-target clipping derivation from one target's own existing
+ * `layout`/`style` evidence (never a scroll scenario - normal target
+ * evidence already carries `scrollWidth`/`scrollHeight`/`clientWidth`/
+ * `clientHeight`/`overflowX`/`overflowY`). `TargetClippingEvidence` has no
+ * slot in `LayoutRelationshipGraph` (that graph is spatial/page-level only,
+ * per the frozen Batch 1 vocabulary) - this is a standalone per-target
+ * derivation for callers (e.g. a later comparison engine) that need it
+ * directly from an `ObservationArtifact`'s `targetEvidence`, one target at a
+ * time. `unavailable` (never guessed) when the underlying layout/style
+ * evidence is not itself available - this naturally covers an unresolved
+ * target without any special-casing. A resolved-but-`display:none` target
+ * naturally computes `not-clipped` too: its `scrollWidth`/`clientWidth` are
+ * both `0`, so `scrollWidth > clientWidth` is false - clipping is never
+ * inferred from hidden-ness itself.
+ */
+export declare function deriveTargetClipping(record: TargetEvidenceRecord): TargetClippingEvidence;
+/**
+ * Pure tolerance-aware geometry predicates (Batch 1's frozen rules,
+ * verbatim). Every predicate is a total function over exactly one relation
+ * family, so it can never itself produce a contradictory pair of values
+ * (e.g. `left-of` and `right-of` for the same call) - the caller decides
+ * `subject`/`related` once per pair and each family is evaluated exactly
+ * once for that fixed direction.
+ */
+/**
+ * Exported (v0.7 Prompt 2 addition, additive-only - no formula changed) so
+ * that domain/externalReferenceRegionRelationships.ts can derive the same
+ * geometry-only relationship families for reference-image regions without
+ * duplicating these formulas. Every parameter is structurally just
+ * `{x,y,width,height,right,bottom}` - these predicates have never depended on
+ * anything runtime/browser-specific, so reusing them for a reference
+ * region's derived rectangle is exact reuse, not a reinterpretation.
+ */
+export declare function horizontalOrderOf(a: TargetGeometry, b: TargetGeometry, tolerance: number): HorizontalOrderRelationship;
+export declare function verticalOrderOf(a: TargetGeometry, b: TargetGeometry, tolerance: number): VerticalOrderRelationship;
+export declare function areaOverlapOf(a: TargetGeometry, b: TargetGeometry, tolerance: number): AreaOverlapRelationship;
+export declare function relativeWidthOf(a: TargetGeometry, b: TargetGeometry, tolerance: number): RelativeWidthRelationship;
+export declare function geometricFitOf(a: TargetGeometry, b: TargetGeometry, tolerance: number): GeometricFitRelationship;
+/**
+ * `follows-vertically` is the one family whose vocabulary has a single
+ * value (not a total 3-way partition like the others), so it is emitted
+ * only when one target's geometry actually precedes the other's - never for
+ * both directions, never when they vertically overlap. The direction is
+ * decided by actual rendered geometry, not configured target order:
+ * `above(x, y)` and "y follows x" share the same tolerance-relative
+ * condition, so whichever of the pair is algebraically "above" the other
+ * becomes `relatedTarget` and the one that follows becomes `subjectTarget`.
+ */
+export declare function verticalSequenceOf(x: {
+    name: string;
+    geometry: TargetGeometry;
+}, y: {
+    name: string;
+    geometry: TargetGeometry;
+}, tolerance: number): {
+    subjectTarget: string;
+    relatedTarget: string;
+} | undefined;
+export type DeriveLayoutRelationshipsOptions = {
+    geometryTolerancePx?: number;
+};
+export type DeriveLayoutRelationshipsResult = {
+    ok: true;
+    graph: LayoutRelationshipGraph;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The one canonical pure derivation from an already-captured
+ * `ObservationArtifact` to a `LayoutRelationshipGraph` (real Chromium ->
+ * ObservationArtifact -> **relationship derivation** -> comparability ->
+ * comparison -> ComparisonArtifact, see docs/ARCHITECTURE.md). Deterministic
+ * and synchronous: same `observation`/`geometryTolerancePx` in, same graph
+ * out, every time - no Chromium, target re-resolution, DOM access, randomness,
+ * clock, filesystem, or network involved, and `observation` is never
+ * mutated.
+ *
+ * Scope, by construction:
+ * - only targets present in `observation.requestConfig.targets` are ever
+ *   considered (bounded at the existing 20-target/190-pair request limit -
+ *   never arbitrary DOM/accessibility-tree traversal);
+ * - a configured target missing usable geometry (never resolved, or
+ *   resolved but reported not-visible) becomes an `unresolvedTargets` entry
+ *   with an honest reason, never a fabricated zero-sized relation;
+ * - for each unordered pair of geometry-eligible targets, exactly one
+ *   record per relationship family is derived, with `subjectTarget`/
+ *   `relatedTarget` fixed to that pair's configured order (earlier
+ *   configured target is always `subjectTarget`) for every family except
+ *   `follows-vertically` (see `verticalSequenceOf`) - so
+ *   `pairwiseRelationships.length` never exceeds
+ *   `MAX_PAIRWISE_RELATIONSHIP_RECORDS`;
+ * - DOM containment is deliberately not re-derived here: it already exists
+ *   as `targetEvidence.<name>.containment` on the observation itself (see
+ *   `TargetContainment` in domain/schema.ts, explicitly documented there as
+ *   "never a layout/relationship graph") and stays separate from
+ *   `fits-inside`/`does-not-fit-inside`, which is geometry-only;
+ * - the page-width relationship is derived only when both
+ *   `pageEvidence.documentWidth` and `pageEvidence.viewportWidth` are
+ *   themselves available - never defaulted to "fits" when evidence is
+ *   missing.
+ */
+export declare function deriveLayoutRelationships(observation: ObservationArtifact, options?: DeriveLayoutRelationshipsOptions): DeriveLayoutRelationshipsResult;