my-frontend-observer 0.6.0 → 0.7.0

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;