@dailephd/my-frontend-observer 0.8.1

package/dist/domain/externalReferenceRegions.js

@@ -0,0 +1,105 @@
+/**
+ * v0.7 Prompt 2 explicit reference-region geometry. A region is one
+ * user/configuration-authored rectangle in the coordinate system of an
+ * external reference image - origin at the image's top-left corner, x
+ * increasing rightward, y increasing downward, unit is reference-image
+ * pixels (never CSS pixels - this is a static image, not a rendered page).
+ * Coordinates may be fractional. This module never infers a region from
+ * pixel content: no OCR, no computer vision, no automatic segmentation.
+ *
+ * Only the rectangle {x, y, width, height} is canonical/authored; every
+ * other geometric fact (right, bottom, centerX, centerY) is a pure
+ * calculation over it (see deriveReferenceRegionGeometry) so that no
+ * redundant, potentially-drifting copy of the same fact is ever persisted.
+ */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/** Same character/length convention as request/request.ts's target-name pattern (`^[A-Za-z0-9_-]{1,64}$`) - reused directly, not reinvented, for the same "stable, portable, log/path-safe identifier" reason. */
+export const REFERENCE_REGION_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** Same numeric bound as request/request.ts's MAX_TARGETS (20) - a coincidentally equal, independently-owned constant: reference regions are design-authoring input, not runtime targets, so the two are not structurally coupled even though they share a value and the same "bound the O(n^2) pairwise-relationship explosion" rationale (see externalReferenceRegionRelationships.ts). */
+export const MAX_REFERENCE_REGIONS = 20;
+export function deriveReferenceRegionGeometry(rectangle) {
+    return {
+        x: rectangle.x,
+        y: rectangle.y,
+        width: rectangle.width,
+        height: rectangle.height,
+        right: rectangle.x + rectangle.width,
+        bottom: rectangle.y + rectangle.height,
+        centerX: rectangle.x + rectangle.width / 2,
+        centerY: rectangle.y + rectangle.height / 2,
+    };
+}
+/**
+ * Structural + numeric validation of one rectangle only - does not know
+ * about image bounds (see isValidReferenceRegions for the boundary check,
+ * which needs the owning image's dimensions). Fails closed on non-finite,
+ * negative, or zero width/height: authored design geometry is never
+ * silently clamped into validity.
+ */
+export function isValidReferenceRegionRectangle(value) {
+    if (!isPlainObject(value))
+        return { valid: false, reason: 'rectangle must be an object' };
+    if (!isFiniteNumber(value.x))
+        return { valid: false, reason: 'rectangle.x must be a finite number' };
+    if (!isFiniteNumber(value.y))
+        return { valid: false, reason: 'rectangle.y must be a finite number' };
+    if (!isFiniteNumber(value.width))
+        return { valid: false, reason: 'rectangle.width must be a finite number' };
+    if (!isFiniteNumber(value.height))
+        return { valid: false, reason: 'rectangle.height must be a finite number' };
+    if (value.x < 0)
+        return { valid: false, reason: 'rectangle.x must not be negative' };
+    if (value.y < 0)
+        return { valid: false, reason: 'rectangle.y must not be negative' };
+    if (value.width <= 0)
+        return { valid: false, reason: 'rectangle.width must be greater than 0' };
+    if (value.height <= 0)
+        return { valid: false, reason: 'rectangle.height must be greater than 0' };
+    return { valid: true };
+}
+export function isValidReferenceRegion(value) {
+    if (!isPlainObject(value))
+        return { valid: false, reason: 'region must be an object' };
+    if (typeof value.id !== 'string' || value.id.length === 0)
+        return { valid: false, reason: 'region.id must be a non-empty string' };
+    if (!REFERENCE_REGION_ID_PATTERN.test(value.id))
+        return { valid: false, reason: `region.id "${value.id}" must match ${REFERENCE_REGION_ID_PATTERN}` };
+    return isValidReferenceRegionRectangle(value.rectangle);
+}
+/**
+ * Collection-level validation: bounded count, unique IDs (case-insensitive,
+ * mirroring request/request.ts's target-name dedup convention), and every
+ * region's rectangle contained within the owning image's own dimensions -
+ * never silently clipped, rejected outright instead. `imageWidth`/
+ * `imageHeight` come from the artifact's own already-validated image
+ * metadata (ExternalReferenceImageReference or the approved artifact's
+ * sourceReference.image), never re-parsed here.
+ */
+export function isValidReferenceRegions(value, imageWidth, imageHeight) {
+    if (!Array.isArray(value))
+        return { valid: false, reason: 'regions must be an array' };
+    if (value.length > MAX_REFERENCE_REGIONS)
+        return { valid: false, reason: `regions must contain at most ${MAX_REFERENCE_REGIONS} entries` };
+    const seenIds = new Set();
+    for (const entry of value) {
+        const regionValidation = isValidReferenceRegion(entry);
+        if (!regionValidation.valid)
+            return regionValidation;
+        const region = entry;
+        const lowerId = region.id.toLowerCase();
+        if (seenIds.has(lowerId))
+            return { valid: false, reason: `duplicate region id "${region.id}"` };
+        seenIds.add(lowerId);
+        const geometry = deriveReferenceRegionGeometry(region.rectangle);
+        if (geometry.right > imageWidth || geometry.bottom > imageHeight) {
+            return { valid: false, reason: `region "${region.id}" extends outside the reference image bounds (${imageWidth}x${imageHeight})` };
+        }
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=externalReferenceRegions.js.map

package/dist/domain/externalReferenceRegions.js.map

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

package/dist/domain/externalReferenceRequirementIdentity.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Deterministic identity of a single reference requirement's own semantic
+ * content - independent of authoring order or which reference it belongs to.
+ * Mirrors domain/frontendContractIdentity.ts#buildClauseIdentity exactly
+ * (same canonicalize+sha256 shape over {subject, tolerance}), extended with
+ * `category`/`expectedDependentMode` because - unlike a v0.5 baseline
+ * clause, whose identity is deliberately category-independent - two
+ * reference requirements with the same subject/tolerance but different
+ * authored category are semantically distinct authored intents (see
+ * docs/CONTRACTS.md "v0.7 Prompt 3").
+ */
+export declare function buildReferenceRequirementIdentity(subject: unknown, category: string, tolerance: unknown, expectedDependentMode?: string): string;

package/dist/domain/externalReferenceRequirementIdentity.js

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+/**
+ * Deliberately duplicated from domain/identity.ts#canonicalize (itself
+ * duplicated across comparisonIdentity.ts/frontendContractIdentity.ts/
+ * externalReferenceIdentity.ts) rather than imported - each identity module
+ * owns its own private canonicalize per existing repository convention.
+ */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, entryValue]) => [key, canonicalize(entryValue)]);
+        return Object.fromEntries(entries);
+    }
+    return value;
+}
+/**
+ * Deterministic identity of a single reference requirement's own semantic
+ * content - independent of authoring order or which reference it belongs to.
+ * Mirrors domain/frontendContractIdentity.ts#buildClauseIdentity exactly
+ * (same canonicalize+sha256 shape over {subject, tolerance}), extended with
+ * `category`/`expectedDependentMode` because - unlike a v0.5 baseline
+ * clause, whose identity is deliberately category-independent - two
+ * reference requirements with the same subject/tolerance but different
+ * authored category are semantically distinct authored intents (see
+ * docs/CONTRACTS.md "v0.7 Prompt 3").
+ */
+export function buildReferenceRequirementIdentity(subject, category, tolerance, expectedDependentMode) {
+    const semanticView = { subject, category, expectedDependentMode: expectedDependentMode ?? null, tolerance: tolerance ?? null };
+    const serialized = JSON.stringify(canonicalize(semanticView));
+    return createHash('sha256').update(serialized).digest('hex');
+}
+//# sourceMappingURL=externalReferenceRequirementIdentity.js.map

package/dist/domain/externalReferenceRequirementIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"externalReferenceRequirementIdentity.js","sourceRoot":"","sources":["../../src/domain/externalReferenceRequirementIdentity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;GAKG;AACH,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC7D,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,YAAY,CAAC,UAAU,CAAC,CAAU,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iCAAiC,CAC/C,OAAgB,EAChB,QAAgB,EAChB,SAAkB,EAClB,qBAA8B;IAE9B,MAAM,YAAY,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAAE,qBAAqB,IAAI,IAAI,EAAE,SAAS,EAAE,SAAS,IAAI,IAAI,EAAE,CAAC;IAC/H,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9D,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC"}

package/dist/domain/externalReferenceRequirements.d.ts

@@ -0,0 +1,215 @@
+/**
+ * v0.7 Prompt 3 selected design requirements, tolerance semantics, and
+ * reference-evidence adequacy. Builds only on Prompt 2's `ReferenceRegion`/
+ * `ReferenceRegionGeometry`/relationship-derivation - it does not implement
+ * runtime-target binding, candidate comparison, or fidelity PASS/FAIL (those
+ * remain later v0.7 prompts).
+ *
+ * Central distinction (see docs/CONTRACTS.md "v0.7 Prompt 3"): a reference
+ * region's geometry is REFERENCE EVIDENCE - everything visibly/measurably
+ * present in the supplied image. A requirement is SELECTED DESIGN INTENT -
+ * only what the user/configuration explicitly authored as mattering for
+ * later candidate evaluation. This module never infers a requirement merely
+ * because a property or relationship exists.
+ *
+ * Requirement categories are the exact v0.5 `AuthoredChangeScopeCategory`
+ * vocabulary (`requested`/`expected-dependent`/`protected`/`preserved`),
+ * imported directly rather than reinvented as a "reference-only" taxonomy -
+ * that type carries no runtime-only coupling in its own definition. As in
+ * v0.5, `'unexpected'` remains impossible to author here: it is not a member
+ * of `AuthoredChangeScopeCategory` at all.
+ */
+import { AUTHORED_CHANGE_SCOPE_CATEGORIES, isAuthoredChangeScopeCategory, EXPECTED_DEPENDENT_MODES, isValidExpectedDependentMode } from './frontendContracts.js';
+import type { AuthoredChangeScopeCategory, ExpectedDependentMode } from './frontendContracts.js';
+import type { PairwiseRelationshipKind } from './relationships.js';
+import type { ReferenceRegion, ReferenceRegionGeometry } from './externalReferenceRegions.js';
+export { AUTHORED_CHANGE_SCOPE_CATEGORIES, isAuthoredChangeScopeCategory, EXPECTED_DEPENDENT_MODES, isValidExpectedDependentMode };
+export type { AuthoredChangeScopeCategory, ExpectedDependentMode };
+export declare const MAX_REFERENCE_REQUIREMENTS = 50;
+/** Exactly the fields of ReferenceRegionGeometry - the smallest coherent vocabulary already available from Prompt 2, nothing invented (no separate "left"/"top" aliases - x/y already are the left/top edges of the canonical rectangle). */
+export declare const REFERENCE_REQUIREMENT_REGION_PROPERTIES: readonly ["x", "y", "width", "height", "right", "bottom", "centerX", "centerY"];
+export type ReferenceRequirementRegionProperty = (typeof REFERENCE_REQUIREMENT_REGION_PROPERTIES)[number];
+export declare function isReferenceRequirementRegionProperty(value: unknown): value is ReferenceRequirementRegionProperty;
+/** Smallest useful set of pure two-region derived measurements (request section 18) - not an unrestricted geometry expression language. */
+export declare const REFERENCE_REQUIREMENT_MEASUREMENTS: readonly ["vertical-gap", "horizontal-gap", "center-x-delta", "center-y-delta", "left-edge-delta", "right-edge-delta"];
+export type ReferenceRequirementMeasurement = (typeof REFERENCE_REQUIREMENT_MEASUREMENTS)[number];
+export declare function isReferenceRequirementMeasurement(value: unknown): value is ReferenceRequirementMeasurement;
+/**
+ * Pure derived two-region measurements. `vertical-gap`/`horizontal-gap`
+ * return `undefined` when the two regions overlap on that axis (the gap is
+ * geometrically undefined, never fabricated as 0 or negative) - direction is
+ * decided by actual geometry, mirroring relationships.ts's
+ * verticalSequenceOf/horizontalOrderOf convention. The delta measurements
+ * are always defined (a plain numeric distance, never negative).
+ */
+export declare function deriveReferenceRequirementMeasurement(kind: ReferenceRequirementMeasurement, a: ReferenceRegionGeometry, b: ReferenceRegionGeometry): number | undefined;
+/**
+ * Deliberately not a reuse of domain/frontendContracts.ts#ContractTolerance:
+ * that type's `'absolute-px'` member is implicitly runtime/CSS pixels
+ * (compared against `TargetGeometry` from a live ObservationArtifact).
+ * Reference-image pixels are a different, explicitly-labeled unit (see
+ * externalReferenceRegions.ts's coordinate-semantics doc comment) - Prompt 6
+ * will eventually need an explicit scale/compatibility mapping between the
+ * two; nothing here assumes 1 reference pixel = 1 CSS pixel. Numeric bounds
+ * intentionally mirror CONTRACT_TOLERANCE_ABSOLUTE_PX_MIN/MAX and
+ * CONTRACT_TOLERANCE_PERCENT_MIN/MAX (same values, independently owned
+ * constants) rather than importing them, for the same unit-labeling reason.
+ */
+export declare const REFERENCE_REQUIREMENT_TOLERANCE_ABSOLUTE_PX_MIN = 0;
+export declare const REFERENCE_REQUIREMENT_TOLERANCE_ABSOLUTE_PX_MAX = 100;
+export declare const REFERENCE_REQUIREMENT_TOLERANCE_PERCENT_MIN = 0;
+export declare const REFERENCE_REQUIREMENT_TOLERANCE_PERCENT_MAX = 100;
+export type ReferenceRequirementTolerance = {
+    kind: 'exact';
+} | {
+    kind: 'absolute-reference-px';
+    amount: number;
+} | {
+    kind: 'percent';
+    amount: number;
+};
+export declare function isValidReferenceRequirementTolerance(value: unknown): value is ReferenceRequirementTolerance;
+export interface RegionPropertyRequirementSubject {
+    kind: 'region-property';
+    region: string;
+    property: ReferenceRequirementRegionProperty;
+}
+export interface RegionRelationshipRequirementSubject {
+    kind: 'region-relationship';
+    subjectRegion: string;
+    relatedRegion: string;
+    relationship: PairwiseRelationshipKind;
+}
+export interface RegionMeasurementRequirementSubject {
+    kind: 'region-measurement';
+    subjectRegion: string;
+    relatedRegion: string;
+    measurement: ReferenceRequirementMeasurement;
+}
+export type ReferenceRequirementSubject = RegionPropertyRequirementSubject | RegionRelationshipRequirementSubject | RegionMeasurementRequirementSubject;
+export declare function isValidReferenceRequirementSubjectShape(value: unknown): value is ReferenceRequirementSubject;
+export interface ExternalReferenceRequirement {
+    /** Deterministic identity from {subject, category, expectedDependentMode, tolerance} only - see externalReferenceRequirementIdentity.ts. Never a timestamp or config path. */
+    requirementId: string;
+    category: AuthoredChangeScopeCategory;
+    expectedDependentMode?: ExpectedDependentMode;
+    subject: ReferenceRequirementSubject;
+    /** Required for region-property/region-measurement subjects (a numeric comparison needs a tolerance); must be absent for region-relationship subjects (a categorical fact - see docs/CONTRACTS.md). */
+    tolerance?: ReferenceRequirementTolerance;
+}
+export type ReferenceRequirementValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Raw authored input shape: exactly what a user/config supplies via
+ * `--requirements-file` - {category, expectedDependentMode?, subject,
+ * tolerance?}, deliberately with no `requirementId` field. Identity is
+ * always system-computed from this exact content (see
+ * buildReferenceRequirement below), never author-supplied - unlike v0.5's
+ * BaselineClause/PerChangeClause, which need an author-visible `clauseId` so
+ * separate documents can cross-reference it via `supersedesBaselineClauseIds`;
+ * Prompt 3 requirements have no cross-document reference need yet, so
+ * requiring (and trusting) an authored id would only invite drift between a
+ * user-typed id and the content it is supposed to identify.
+ */
+export interface RawReferenceRequirement {
+    category: AuthoredChangeScopeCategory;
+    expectedDependentMode?: ExpectedDependentMode;
+    subject: ReferenceRequirementSubject;
+    tolerance?: ReferenceRequirementTolerance;
+}
+/** Validates one raw, not-yet-identified authored requirement - the shape accepted from `--requirements-file`. */
+export declare function isValidRawReferenceRequirement(value: unknown): ReferenceRequirementValidationResult;
+/** Computes the deterministic requirementId and returns a complete ExternalReferenceRequirement. Callers must validate via isValidRawReferenceRequirement first. */
+export declare function buildReferenceRequirement(raw: RawReferenceRequirement): ExternalReferenceRequirement;
+/** Validates one already-identified, fully-constructed requirement's own shape (category/mode/subject/tolerance-applicability, plus requirementId presence) - never region existence, which needs the owning reference's `regions` (see isValidReferenceRequirements). Used to defensively re-validate a persisted/about-to-be-persisted ExternalReferenceRequirement, mirroring how every other artifact family's writer re-validates via the same gate it will later read with. */
+export declare function isValidReferenceRequirementShape(value: unknown): ReferenceRequirementValidationResult;
+/**
+ * Collection-level validation: bounded count, every subject's region id(s)
+ * must exist among the owning artifact's own already-validated `regions`
+ * (an authored requirement pointing at a nonexistent region is a structural
+ * validation failure, never merely "unavailable" evidence - see
+ * docs/CONTRACTS.md), and no two requirements may share the same structural
+ * subject (the chosen conflict-handling rule - see the same doc section for
+ * why v0.5's runtime-evidence conflict detector could not be reused here).
+ */
+export declare function isValidReferenceRequirements(value: unknown, regions: readonly ReferenceRegion[]): ReferenceRequirementValidationResult;
+export type ReferenceRequirementExpectation = {
+    available: true;
+    kind: 'numeric';
+    value: number;
+} | {
+    available: true;
+    kind: 'relationship';
+    matches: boolean;
+} | {
+    available: false;
+    reason: string;
+};
+/**
+ * Derives what the reference itself shows for one requirement's subject,
+ * purely from the supplied regions - never stored on the requirement or the
+ * artifact (avoids the exact drift risk request section 14 warns about: a
+ * stored `width: 424` could silently disagree with the region's own
+ * rectangle after some future change). `geometryTolerancePx` is passed
+ * through to relationship derivation unchanged (Prompt 2's own default
+ * applies when omitted).
+ */
+export declare function deriveReferenceRequirementExpectation(subject: ReferenceRequirementSubject, regions: readonly ReferenceRegion[], options?: {
+    geometryTolerancePx?: number;
+}): ReferenceRequirementExpectation;
+export declare const REFERENCE_REQUIREMENT_ADEQUACY_STATES: readonly ["adequate", "partial", "inadequate"];
+export type ReferenceRequirementAdequacyState = (typeof REFERENCE_REQUIREMENT_ADEQUACY_STATES)[number];
+/**
+ * Deliberately its own small, reference-owned vocabulary - not a reuse of
+ * domain/boundedAgentContext.ts#ADEQUACY_REASON_CODES, which describes
+ * runtime-target/static-correlation concerns that do not exist yet at this
+ * stage (see docs/CONTRACTS.md "v0.7 Prompt 3" for the full precedent
+ * review). Only two codes exist because only two conditions can make an
+ * already-*structurally-valid* requirement collection reference-inadequate:
+ * authoring zero requirements at all, or a validly-shaped relationship/
+ * measurement requirement whose evidence cannot actually be derived from the
+ * reference geometry. An unknown-region or malformed requirement is a
+ * construction-time validation failure (isValidReferenceRequirements) and
+ * never reaches adequacy at all.
+ */
+export declare const REFERENCE_REQUIREMENT_ADEQUACY_REASON_CODES: readonly ["no-selected-requirements", "missing-reference-relationship-evidence"];
+export type ReferenceRequirementAdequacyReasonCode = (typeof REFERENCE_REQUIREMENT_ADEQUACY_REASON_CODES)[number];
+export interface ReferenceRequirementAdequacyReason {
+    code: ReferenceRequirementAdequacyReasonCode;
+    requirementId?: string;
+    detail?: string;
+}
+export interface ReferenceRequirementAdequacy {
+    status: ReferenceRequirementAdequacyState;
+    totalRequirements: number;
+    evaluableRequirements: number;
+    unavailableRequirements: number;
+    reasons: ReferenceRequirementAdequacyReason[];
+}
+/**
+ * REFERENCE-SIDE adequacy only: does the reference definition itself contain
+ * enough evidence to understand every selected requirement? This never asks
+ * whether a runtime target/candidate exists (that is Prompt 4/5's
+ * responsibility). A reference with zero authored requirements is explicitly
+ * `inadequate` (request section 24F's documented decision: an
+ * externally-valid, region-rich reference is still not usable for a
+ * correction task until the user has actually selected what matters).
+ * Deterministic: reasons are ordered by authored requirement index, never by
+ * object-key iteration order.
+ */
+export declare function deriveReferenceRequirementAdequacy(regions: readonly ReferenceRegion[], requirements: readonly ExternalReferenceRequirement[], options?: {
+    geometryTolerancePx?: number;
+}): ReferenceRequirementAdequacy;
+/**
+ * v0.7 Prompt 7 addition (additive, previously no structural validator
+ * existed for this already-frozen Prompt 3 shape): a defense-in-depth
+ * structural check, reused by `boundedAgentContext.ts` when accepting an
+ * already-computed `ReferenceRequirementAdequacy` value as part of a bounded
+ * fidelity projection. No change to `deriveReferenceRequirementAdequacy`'s
+ * own logic or the `ReferenceRequirementAdequacy` contract itself.
+ */
+export declare function isValidReferenceRequirementAdequacy(value: unknown): value is ReferenceRequirementAdequacy;