@dailephd/my-frontend-observer 0.8.1

package/dist/domain/frontendContracts.js

@@ -0,0 +1,260 @@
+import { isValidEvidenceReference, PAIRWISE_RELATIONSHIP_KINDS, PAGE_LEVEL_RELATIONSHIP_KINDS } from './relationships.js';
+import { DEPENDENCY_PROPERTIES } from './comparison.js';
+import { PRODUCER_NAME, SCHEMA_VERSION as OBSERVATION_SCHEMA_VERSION } from './schema.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isEvidenceReferenceArray(value) {
+    return Array.isArray(value) && value.every((entry) => isValidEvidenceReference(entry));
+}
+export const CONTRACT_ARTIFACT_KIND = 'my-frontend-observer/frontend-contract';
+export const CONTRACT_SCHEMA_VERSION = '1.0.0';
+// --- Change-scope vocabulary --------------------------------------------------
+/** The authored per-change contract has exactly these 4 intent categories - `'unexpected'` is never a member. */
+export const AUTHORED_CHANGE_SCOPE_CATEGORIES = ['requested', 'expected-dependent', 'protected', 'preserved'];
+export function isAuthoredChangeScopeCategory(value) {
+    return typeof value === 'string' && AUTHORED_CHANGE_SCOPE_CATEGORIES.includes(value);
+}
+/**
+ * Full derived classification vocabulary, kept structurally separate from
+ * AUTHORED_CHANGE_SCOPE_CATEGORIES - `'unexpected'` is a classification a
+ * future evaluator produces, never an authored permission. No function in
+ * this module converts between the two vocabularies.
+ */
+export const CHANGE_SCOPE_CLASSIFICATIONS = [...AUTHORED_CHANGE_SCOPE_CATEGORIES, 'unexpected'];
+export const EXPECTED_DEPENDENT_MODES = ['required', 'permitted'];
+export function isValidExpectedDependentMode(value) {
+    return typeof value === 'string' && EXPECTED_DEPENDENT_MODES.includes(value);
+}
+// --- Contract tolerance (bounded, closed - never a generic expression) -------
+/** Independently declared from GEOMETRY_TOLERANCE_*_PX (src/domain/relationships.ts): comparison tolerance suppresses insignificant geometry noise and is never contract authorization. */
+export const CONTRACT_TOLERANCE_ABSOLUTE_PX_MIN = 0;
+export const CONTRACT_TOLERANCE_ABSOLUTE_PX_MAX = 100;
+export const CONTRACT_TOLERANCE_PERCENT_MIN = 0;
+export const CONTRACT_TOLERANCE_PERCENT_MAX = 100;
+export function isValidContractTolerance(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (value.kind === 'exact')
+        return Object.keys(value).length === 1;
+    if (value.kind === 'absolute-px') {
+        return (typeof value.amount === 'number' &&
+            Number.isFinite(value.amount) &&
+            value.amount >= CONTRACT_TOLERANCE_ABSOLUTE_PX_MIN &&
+            value.amount <= CONTRACT_TOLERANCE_ABSOLUTE_PX_MAX);
+    }
+    if (value.kind === 'percent') {
+        return (typeof value.amount === 'number' &&
+            Number.isFinite(value.amount) &&
+            value.amount >= CONTRACT_TOLERANCE_PERCENT_MIN &&
+            value.amount <= CONTRACT_TOLERANCE_PERCENT_MAX);
+    }
+    return false;
+}
+// --- Contract primitive vocabulary (bounded, closed) --------------------------
+/** Every contract primitive kind this batch freezes - deliberately bounded, never a generic rule/expression language. */
+export const CONTRACT_PRIMITIVE_KINDS = [
+    'target-visible',
+    'target-not-clipped',
+    'target-width-within-bound',
+    'targets-do-not-overlap',
+    'target-wider-than',
+    'target-follows-vertically',
+    'target-fits-inside',
+    'document-width-fits-viewport',
+    'scroll-owner-is-document',
+    'target-does-not-own-scroll',
+    'target-begins-below-initial-viewport',
+    'relationship-unchanged',
+    'property-unchanged-within-tolerance',
+    'property-increases',
+    'property-decreases',
+];
+const ALL_RELATIONSHIP_KINDS = [...PAIRWISE_RELATIONSHIP_KINDS, ...PAGE_LEVEL_RELATIONSHIP_KINDS];
+function isOptionalFiniteNumber(value) {
+    return value === undefined || (typeof value === 'number' && Number.isFinite(value));
+}
+function isOptionalNonNegativeFiniteNumber(value) {
+    return value === undefined || (typeof value === 'number' && Number.isFinite(value) && value >= 0);
+}
+/** Rejects extra keys beyond the given allowlist, keeping every ContractPrimitive variant a closed shape rather than an open bag of fields. */
+function hasOnlyKeys(value, allowedKeys) {
+    return Object.keys(value).every((key) => allowedKeys.includes(key));
+}
+export function isValidContractPrimitive(value) {
+    if (!isPlainObject(value) || typeof value.kind !== 'string')
+        return false;
+    switch (value.kind) {
+        case 'target-visible':
+            return hasOnlyKeys(value, ['kind', 'target']) && isNonEmptyString(value.target);
+        case 'target-not-clipped':
+            return (hasOnlyKeys(value, ['kind', 'target', 'axis']) &&
+                isNonEmptyString(value.target) &&
+                (value.axis === undefined || value.axis === 'horizontal' || value.axis === 'vertical' || value.axis === 'both'));
+        case 'target-width-within-bound': {
+            if (!hasOnlyKeys(value, ['kind', 'target', 'minPx', 'maxPx']))
+                return false;
+            if (!isNonEmptyString(value.target))
+                return false;
+            if (!isOptionalFiniteNumber(value.minPx) || !isOptionalFiniteNumber(value.maxPx))
+                return false;
+            if (value.minPx === undefined && value.maxPx === undefined)
+                return false;
+            if (typeof value.minPx === 'number' && typeof value.maxPx === 'number' && value.minPx > value.maxPx)
+                return false;
+            return true;
+        }
+        case 'targets-do-not-overlap':
+        case 'target-wider-than':
+        case 'target-follows-vertically':
+            return (hasOnlyKeys(value, ['kind', 'targetA', 'targetB']) &&
+                isNonEmptyString(value.targetA) &&
+                isNonEmptyString(value.targetB) &&
+                value.targetA !== value.targetB);
+        case 'target-fits-inside':
+            return (hasOnlyKeys(value, ['kind', 'target', 'container']) &&
+                isNonEmptyString(value.target) &&
+                isNonEmptyString(value.container) &&
+                value.target !== value.container);
+        case 'document-width-fits-viewport':
+        case 'scroll-owner-is-document':
+            return hasOnlyKeys(value, ['kind']) && Object.keys(value).length === 1;
+        case 'target-does-not-own-scroll':
+        case 'target-begins-below-initial-viewport':
+            return hasOnlyKeys(value, ['kind', 'target']) && isNonEmptyString(value.target);
+        case 'relationship-unchanged':
+            return (hasOnlyKeys(value, ['kind', 'relationshipKind', 'subjectTarget', 'relatedTarget']) &&
+                typeof value.relationshipKind === 'string' &&
+                ALL_RELATIONSHIP_KINDS.includes(value.relationshipKind) &&
+                (value.subjectTarget === undefined || typeof value.subjectTarget === 'string') &&
+                (value.relatedTarget === undefined || typeof value.relatedTarget === 'string'));
+        case 'property-unchanged-within-tolerance':
+            return (hasOnlyKeys(value, ['kind', 'target', 'property', 'tolerance']) &&
+                isNonEmptyString(value.target) &&
+                typeof value.property === 'string' &&
+                DEPENDENCY_PROPERTIES.includes(value.property) &&
+                isValidContractTolerance(value.tolerance));
+        case 'property-increases':
+        case 'property-decreases':
+            return (hasOnlyKeys(value, ['kind', 'target', 'property', 'minimumDeltaPx']) &&
+                isNonEmptyString(value.target) &&
+                typeof value.property === 'string' &&
+                DEPENDENCY_PROPERTIES.includes(value.property) &&
+                isOptionalNonNegativeFiniteNumber(value.minimumDeltaPx));
+        default:
+            return false;
+    }
+}
+export function isValidBaselineClause(value) {
+    if (!isPlainObject(value))
+        return false;
+    return isNonEmptyString(value.clauseId) && isValidContractPrimitive(value.primitive) && isEvidenceReferenceArray(value.supportingEvidence);
+}
+export function isValidPerChangeClause(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (!isValidBaselineClause(value))
+        return false;
+    const record = value;
+    if (!isAuthoredChangeScopeCategory(record.category))
+        return false;
+    const hasMode = 'expectedDependentMode' in record && record.expectedDependentMode !== undefined;
+    if (record.category === 'expected-dependent') {
+        if (!hasMode || !isValidExpectedDependentMode(record.expectedDependentMode))
+            return false;
+    }
+    else if (hasMode) {
+        return false;
+    }
+    if ('supersedesBaselineClauseIds' in record && record.supersedesBaselineClauseIds !== undefined) {
+        const ids = record.supersedesBaselineClauseIds;
+        if (!Array.isArray(ids) || ids.length === 0)
+            return false;
+        if (!ids.every((id) => isNonEmptyString(id)))
+            return false;
+    }
+    return true;
+}
+export function isValidFrontendContractObservationReference(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (!isNonEmptyString(value.observationId) || !isNonEmptyString(value.requestId))
+        return false;
+    if (!isPlainObject(value.producer) || value.producer.name !== PRODUCER_NAME || !isNonEmptyString(value.producer.version))
+        return false;
+    return value.observationSchemaVersion === OBSERVATION_SCHEMA_VERSION;
+}
+export function isValidPersistentBaselineContract(value) {
+    if (!isPlainObject(value))
+        return { valid: false, reason: 'contract must be an object' };
+    if (value.artifactKind !== CONTRACT_ARTIFACT_KIND)
+        return { valid: false, reason: 'artifactKind mismatch' };
+    if (value.schemaVersion !== CONTRACT_SCHEMA_VERSION)
+        return { valid: false, reason: 'schemaVersion mismatch' };
+    if (value.contractClass !== 'baseline')
+        return { valid: false, reason: 'contractClass must be "baseline"' };
+    if (!isNonEmptyString(value.baselineId))
+        return { valid: false, reason: 'baselineId must be a non-empty string' };
+    if ('supersedesBaselineId' in value && value.supersedesBaselineId !== undefined && !isNonEmptyString(value.supersedesBaselineId)) {
+        return { valid: false, reason: 'supersedesBaselineId must be a non-empty string when present' };
+    }
+    if (!isValidFrontendContractObservationReference(value.sourceObservation))
+        return { valid: false, reason: 'sourceObservation is invalid' };
+    if (!Array.isArray(value.clauses) || !value.clauses.every((c) => isValidBaselineClause(c))) {
+        return { valid: false, reason: 'clauses must be an array of valid BaselineClause values' };
+    }
+    if (!isPlainObject(value.provenance) || !isNonEmptyString(value.provenance.approvedAt)) {
+        return { valid: false, reason: 'provenance.approvedAt must be a non-empty string' };
+    }
+    return { valid: true };
+}
+export function isValidPerChangeContract(value) {
+    if (!isPlainObject(value))
+        return { valid: false, reason: 'contract must be an object' };
+    if (value.artifactKind !== CONTRACT_ARTIFACT_KIND)
+        return { valid: false, reason: 'artifactKind mismatch' };
+    if (value.schemaVersion !== CONTRACT_SCHEMA_VERSION)
+        return { valid: false, reason: 'schemaVersion mismatch' };
+    if (value.contractClass !== 'change')
+        return { valid: false, reason: 'contractClass must be "change"' };
+    if (!isNonEmptyString(value.contractId))
+        return { valid: false, reason: 'contractId must be a non-empty string' };
+    if (!isNonEmptyString(value.contractRequestId))
+        return { valid: false, reason: 'contractRequestId must be a non-empty string' };
+    if (!Array.isArray(value.activeBaselineIds) || !value.activeBaselineIds.every((id) => isNonEmptyString(id))) {
+        return { valid: false, reason: 'activeBaselineIds must be an array of non-empty strings' };
+    }
+    if (!Array.isArray(value.clauses) || !value.clauses.every((c) => isValidPerChangeClause(c))) {
+        return { valid: false, reason: 'clauses must be an array of valid PerChangeClause values' };
+    }
+    return { valid: true };
+}
+// --- Per-clause evaluation result vocabulary (frozen vocabulary only; no producer in this batch) --
+export const CLAUSE_RESULT_STATUSES = ['pass', 'fail', 'unavailable', 'conflict'];
+/** Honest per-clause result vocabulary: `'unavailable'` requires a non-empty reason (never fabricated pass/fail); `'conflict'` requires at least 2 conflicting clause ids. */
+export function isValidClauseEvaluationResult(value) {
+    if (!isPlainObject(value) || !isNonEmptyString(value.clauseId))
+        return false;
+    if (!isEvidenceReferenceArray(value.supportingEvidence))
+        return false;
+    switch (value.status) {
+        case 'pass':
+        case 'fail':
+            return !('reason' in value) && !('conflictingClauseIds' in value);
+        case 'unavailable':
+            return isNonEmptyString(value.reason) && !('conflictingClauseIds' in value);
+        case 'conflict':
+            return (isNonEmptyString(value.reason) &&
+                Array.isArray(value.conflictingClauseIds) &&
+                value.conflictingClauseIds.length >= 2 &&
+                value.conflictingClauseIds.every((id) => isNonEmptyString(id)));
+        default:
+            return false;
+    }
+}
+// --- Overall verdict vocabulary (type only; no producer in this batch) -----------
+export const OVERALL_VERDICTS = ['PASS', 'FAIL'];
+//# sourceMappingURL=frontendContracts.js.map

package/dist/domain/frontendContracts.js.map

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

package/dist/domain/identity.d.ts

@@ -0,0 +1,21 @@
+import type { NormalizedObservationRequest } from '../request/request.js';
+/**
+ * Pure function of {targetUrl, viewport, targets (order preserved -
+ * semantic), readiness.condition, scrollScenario, explicitState} only.
+ * timeoutMs, readiness.timeoutMs, and outputLocation never affect the
+ * result - this is the frozen definition of "same configuration" for this
+ * batch. A request with no `scrollScenario`/`explicitState` omits the key
+ * entirely (rather than setting it to `undefined`) so the identity for a
+ * request missing either is unchanged by the batch that introduced it (v0.3
+ * for scrollScenario, v0.7 Prompt 4 for explicitState). Only the requested
+ * action configuration participates - never runtime scroll results,
+ * movement success/failure, or scroll-owner interpretation, which are
+ * runtime evidence, not identity; likewise `explicitState` is the
+ * caller-declared state identity only, never browser-observed evidence.
+ */
+export declare function buildRequestIdentity(request: NormalizedObservationRequest): string;
+/**
+ * Fresh, opaque per-call identity - never derived from capturedAt/Date.now(),
+ * never collides even when called twice within the same millisecond.
+ */
+export declare function buildObservationIdentity(requestIdentity: string): string;

package/dist/domain/identity.js

@@ -0,0 +1,47 @@
+import { createHash, randomBytes } from 'node:crypto';
+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;
+}
+/**
+ * Pure function of {targetUrl, viewport, targets (order preserved -
+ * semantic), readiness.condition, scrollScenario, explicitState} only.
+ * timeoutMs, readiness.timeoutMs, and outputLocation never affect the
+ * result - this is the frozen definition of "same configuration" for this
+ * batch. A request with no `scrollScenario`/`explicitState` omits the key
+ * entirely (rather than setting it to `undefined`) so the identity for a
+ * request missing either is unchanged by the batch that introduced it (v0.3
+ * for scrollScenario, v0.7 Prompt 4 for explicitState). Only the requested
+ * action configuration participates - never runtime scroll results,
+ * movement success/failure, or scroll-owner interpretation, which are
+ * runtime evidence, not identity; likewise `explicitState` is the
+ * caller-declared state identity only, never browser-observed evidence.
+ */
+export function buildRequestIdentity(request) {
+    const semanticView = {
+        targetUrl: request.targetUrl,
+        viewport: { width: request.viewport.width, height: request.viewport.height },
+        targets: request.targets.map((target) => ({ name: target.name.toLowerCase(), locators: target.locators })),
+        readinessCondition: request.readiness.condition,
+        ...(request.scrollScenario ? { scrollScenario: request.scrollScenario } : {}),
+        ...(request.explicitState ? { explicitState: request.explicitState } : {}),
+    };
+    const serialized = JSON.stringify(canonicalize(semanticView));
+    return createHash('sha256').update(serialized).digest('hex');
+}
+/**
+ * Fresh, opaque per-call identity - never derived from capturedAt/Date.now(),
+ * never collides even when called twice within the same millisecond.
+ */
+export function buildObservationIdentity(requestIdentity) {
+    const nonce = randomBytes(16).toString('hex');
+    return `${requestIdentity}-${nonce}`;
+}
+//# sourceMappingURL=identity.js.map

package/dist/domain/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/domain/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD,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;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAqC;IACxE,MAAM,YAAY,GAAG;QACnB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,QAAQ,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE;QAC5E,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC1G,kBAAkB,EAAE,OAAO,CAAC,SAAS,CAAC,SAAS;QAC/C,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3E,CAAC;IACF,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;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,eAAuB;IAC9D,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO,GAAG,eAAe,IAAI,KAAK,EAAE,CAAC;AACvC,CAAC"}

package/dist/domain/referenceCorrectionIdentity.d.ts

@@ -0,0 +1,40 @@
+import type { ReferenceRuntimeBindingDeclaration } from './externalReferenceRuntimeBinding.js';
+import type { BaselineClause, PerChangeClause } from './frontendContracts.js';
+/**
+ * Pure function of {referenceRequestId, baselineObservationId,
+ * baselineContractId, baselineContractClauses, changeContractId,
+ * changeContractClauses, bindingDeclarations} only - never a timestamp,
+ * never an operational file path.
+ *
+ * Includes each contract's own authored `clauses` content, not merely its
+ * caller-authored `baselineId`/`contractId` label: unlike this repository's
+ * content-derived identities elsewhere (e.g. `ObservationArtifact.observationId`),
+ * `PersistentBaselineContract.baselineId`/`PerChangeContract.contractId` are
+ * plain author-supplied strings (see `frontendContractPersistenceService.ts`
+ * - `approveAndPersistBaseline` persists `contract.baselineId` verbatim,
+ * never recomputing it from `clauses`), so two structurally valid contracts
+ * could in principle share the same id while authoring different clauses.
+ * Hashing clause content directly closes that gap: a caller cannot silently
+ * swap in a same-id baseline/per-change contract with different clauses
+ * between attempts of the same logical review without `reviewRequestId`
+ * changing, which `reviewReferenceCorrectionAttempt`'s own coherence check
+ * (recomputing this same hash and rejecting a mismatch) then catches.
+ *
+ * Two preparation calls over the same approved reference, the same approved
+ * baseline observation, the same active baseline/per-change contracts
+ * (id *and* clause content), and the same binding declarations always
+ * identify the same logical correction review, regardless of which
+ * filesystem locations those artifacts were read from.
+ */
+export declare function buildReferenceCorrectionReviewIdentity(referenceRequestId: string, baselineObservationId: string, baselineContractId: string, baselineContractClauses: readonly BaselineClause[], changeContractId: string, changeContractClauses: readonly PerChangeClause[], bindingDeclarations: readonly ReferenceRuntimeBindingDeclaration[]): string;
+/**
+ * Pure, deterministic function of {reviewRequestId, candidateObservationId}
+ * only - deliberately never a fresh random nonce. Every candidate
+ * observation already carries its own fresh, collision-resistant instance
+ * identity (see domain/identity.ts#buildObservationIdentity), so hashing it
+ * together with the review it was captured for gives an attempt identity
+ * that is both stable/reproducible (the same review+candidate pair always
+ * yields the same attemptId) and guaranteed distinct per real capture
+ * (never a timestamp, never reused across two different candidates).
+ */
+export declare function buildReferenceCorrectionAttemptIdentity(reviewRequestId: string, candidateObservationId: string): string;

package/dist/domain/referenceCorrectionIdentity.js

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+/**
+ * Deliberately duplicated from domain/identity.ts#canonicalize (and its
+ * other per-module duplicates) rather than imported - each identity module
+ * owns its own private canonicalize per existing repository convention.
+ * Same algorithm (sorted object keys, order-preserving arrays).
+ */
+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;
+}
+/** Authored binding order is semantic (mirrors every other identity function in this repository's treatment of authored collections) - never sorted away. */
+function bindingSemanticView(declarations) {
+    return declarations.map((d) => ({ referenceRegion: d.referenceRegion, runtimeTarget: d.runtimeTarget }));
+}
+/**
+ * Pure function of {referenceRequestId, baselineObservationId,
+ * baselineContractId, baselineContractClauses, changeContractId,
+ * changeContractClauses, bindingDeclarations} only - never a timestamp,
+ * never an operational file path.
+ *
+ * Includes each contract's own authored `clauses` content, not merely its
+ * caller-authored `baselineId`/`contractId` label: unlike this repository's
+ * content-derived identities elsewhere (e.g. `ObservationArtifact.observationId`),
+ * `PersistentBaselineContract.baselineId`/`PerChangeContract.contractId` are
+ * plain author-supplied strings (see `frontendContractPersistenceService.ts`
+ * - `approveAndPersistBaseline` persists `contract.baselineId` verbatim,
+ * never recomputing it from `clauses`), so two structurally valid contracts
+ * could in principle share the same id while authoring different clauses.
+ * Hashing clause content directly closes that gap: a caller cannot silently
+ * swap in a same-id baseline/per-change contract with different clauses
+ * between attempts of the same logical review without `reviewRequestId`
+ * changing, which `reviewReferenceCorrectionAttempt`'s own coherence check
+ * (recomputing this same hash and rejecting a mismatch) then catches.
+ *
+ * Two preparation calls over the same approved reference, the same approved
+ * baseline observation, the same active baseline/per-change contracts
+ * (id *and* clause content), and the same binding declarations always
+ * identify the same logical correction review, regardless of which
+ * filesystem locations those artifacts were read from.
+ */
+export function buildReferenceCorrectionReviewIdentity(referenceRequestId, baselineObservationId, baselineContractId, baselineContractClauses, changeContractId, changeContractClauses, bindingDeclarations) {
+    const semanticView = {
+        referenceRequestId,
+        baselineObservationId,
+        baselineContractId,
+        baselineContractClauses,
+        changeContractId,
+        changeContractClauses,
+        bindings: bindingSemanticView(bindingDeclarations),
+    };
+    const serialized = JSON.stringify(canonicalize(semanticView));
+    return createHash('sha256').update(serialized).digest('hex');
+}
+/**
+ * Pure, deterministic function of {reviewRequestId, candidateObservationId}
+ * only - deliberately never a fresh random nonce. Every candidate
+ * observation already carries its own fresh, collision-resistant instance
+ * identity (see domain/identity.ts#buildObservationIdentity), so hashing it
+ * together with the review it was captured for gives an attempt identity
+ * that is both stable/reproducible (the same review+candidate pair always
+ * yields the same attemptId) and guaranteed distinct per real capture
+ * (never a timestamp, never reused across two different candidates).
+ */
+export function buildReferenceCorrectionAttemptIdentity(reviewRequestId, candidateObservationId) {
+    const semanticView = { reviewRequestId, candidateObservationId };
+    const serialized = JSON.stringify(canonicalize(semanticView));
+    return createHash('sha256').update(serialized).digest('hex');
+}
+//# sourceMappingURL=referenceCorrectionIdentity.js.map

package/dist/domain/referenceCorrectionIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"referenceCorrectionIdentity.js","sourceRoot":"","sources":["../../src/domain/referenceCorrectionIdentity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC;;;;;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,6JAA6J;AAC7J,SAAS,mBAAmB,CAAC,YAA2D;IACtF,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,eAAe,EAAE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC;AAC3G,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,sCAAsC,CACpD,kBAA0B,EAC1B,qBAA6B,EAC7B,kBAA0B,EAC1B,uBAAkD,EAClD,gBAAwB,EACxB,qBAAiD,EACjD,mBAAkE;IAElE,MAAM,YAAY,GAAG;QACnB,kBAAkB;QAClB,qBAAqB;QACrB,kBAAkB;QAClB,uBAAuB;QACvB,gBAAgB;QAChB,qBAAqB;QACrB,QAAQ,EAAE,mBAAmB,CAAC,mBAAmB,CAAC;KACnD,CAAC;IACF,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;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uCAAuC,CAAC,eAAuB,EAAE,sBAA8B;IAC7G,MAAM,YAAY,GAAG,EAAE,eAAe,EAAE,sBAAsB,EAAE,CAAC;IACjE,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/referenceCorrectionWorkflow.d.ts

@@ -0,0 +1,160 @@
+/**
+ * v0.7 Prompt 8 controlled end-to-end external-reference coding-agent
+ * correction workflow coordinator. This module composes the already-
+ * existing, independently-owned Prompt 1-7 and v0.1/v0.4/v0.5/v0.6 engines
+ * into two pure operations - `prepareReferenceCorrection` (produce a
+ * bounded coding-agent handoff from the current, pre-change state) and
+ * `reviewReferenceCorrectionAttempt` (compose one candidate's overall PASS/
+ * FAIL after an external actor has edited target source) - without
+ * reimplementing, recomputing, or duplicating any of them:
+ *
+ * - reference structural/lifecycle rules: `domain/externalReference.ts` (Prompt 1)
+ * - reference regions/relationships: `domain/externalReferenceRegions*.ts` (Prompt 2)
+ * - selected requirements/tolerances/adequacy: `domain/externalReferenceRequirements.ts` (Prompt 3)
+ * - reference/candidate compatibility: `domain/externalReferenceCompatibility.ts` (Prompt 4)
+ * - reference-region <-> runtime-target binding: `domain/externalReferenceRuntimeBinding.ts` (Prompt 5)
+ * - reference fidelity evaluation: `domain/externalReferenceFidelity.ts` (Prompt 6)
+ * - bounded fidelity/runtime/static context: `domain/referenceFidelityProjection.ts` +
+ *   `domain/boundedAgentContextProjection.ts` (Prompt 7)
+ * - runtime baseline-vs-candidate comparison: `domain/comparisonEngine.ts` (v0.4)
+ * - baseline/per-change contract evaluation: `domain/frontendContractEvaluation.ts` (v0.5)
+ *
+ * This module owns only: reading which of those already-computed results
+ * says what, composing one honest overall result, and giving the external
+ * implementation actor a bounded, traceable handoff. It never edits target
+ * source, never launches a browser, never calls a remote AI provider, never
+ * persists anything, and never auto-approves a baseline or a reference -
+ * approval remains the caller's own separate, explicit action via the
+ * existing `approveAndPersistBaseline`/`approveExternalReference` owners.
+ */
+import type { ExternalReferenceArtifact } from './externalReference.js';
+import type { ObservationArtifact } from './schema.js';
+import type { PersistentBaselineContract, PerChangeContract } from './frontendContracts.js';
+import type { ComparisonArtifact, ComparisonConfig } from './comparison.js';
+import type { FrontendContractEvaluationResult } from './frontendContractEvaluation.js';
+import type { ReferenceRuntimeBindingDeclaration } from './externalReferenceRuntimeBinding.js';
+import type { ReferenceCandidateFidelityEvaluation } from './externalReferenceFidelity.js';
+import type { BoundedAgentContextArtifact, ProjectionProfile } from './boundedAgentContext.js';
+interface CommonInput {
+    reference: ExternalReferenceArtifact;
+    baselineObservation: ObservationArtifact;
+    baselineContract: PersistentBaselineContract;
+    changeContract: PerChangeContract;
+    bindingDeclarations: readonly ReferenceRuntimeBindingDeclaration[];
+}
+export interface PrepareReferenceCorrectionInput extends CommonInput {
+    /** The current, pre-change candidate observation fidelity is measured against. For the canonical proof this is the approved baseline observation itself (see docs/CONTRACTS.md "v0.7 Prompt 8"); a caller may supply a distinct current-state observation only when its own architecture justifies that distinction. */
+    currentObservation: ObservationArtifact;
+    generatedAt: string;
+    producerVersion: string;
+    projectionProfile: ProjectionProfile;
+    fidelityGeometryTolerancePx?: number;
+}
+export type PrepareReferenceCorrectionStatus = 'handoff-ready' | 'blocked-not-evaluated';
+/**
+ * The concrete, machine-readable, human-inspectable handoff boundary the
+ * external implementation actor receives. Carries no raw image bytes, no
+ * full `ObservationArtifact`/`ExternalReferenceArtifact` payload, and no
+ * source excerpt - only stable identities plus the already-bounded Prompt 7
+ * projection (which itself already carries the actionable fidelity
+ * mismatches, protected/preserved context, and - when the caller supplied
+ * it - runtime/static correlation).
+ */
+export interface ReferenceCorrectionHandoff {
+    reviewRequestId: string;
+    referenceId: string;
+    referenceRequestId: string;
+    baselineObservationId: string;
+    currentObservationId: string;
+    boundedContext: BoundedAgentContextArtifact;
+    /** Human-readable statement of what will be re-checked after the external actor edits source - never "make it look like the screenshot". */
+    verificationPlan: string[];
+}
+export type PrepareReferenceCorrectionResult = {
+    ok: true;
+    status: 'handoff-ready';
+    reviewRequestId: string;
+    fidelity: ReferenceCandidateFidelityEvaluation;
+    handoff: ReferenceCorrectionHandoff;
+} | {
+    ok: true;
+    status: 'blocked-not-evaluated';
+    reviewRequestId: string;
+    fidelity: ReferenceCandidateFidelityEvaluation;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 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 declare function prepareReferenceCorrection(input: PrepareReferenceCorrectionInput): PrepareReferenceCorrectionResult;
+export declare const REFERENCE_CORRECTION_OVERALL_STATES: readonly ["not-evaluated", "pass", "fail"];
+export type ReferenceCorrectionOverallState = (typeof REFERENCE_CORRECTION_OVERALL_STATES)[number];
+export interface ReviewReferenceCorrectionAttemptInput extends CommonInput {
+    reviewRequestId: string;
+    /** The fresh, newly-captured candidate observation (never the baseline itself, never a prior attempt's candidate) to evaluate. */
+    candidateObservation: ObservationArtifact;
+    /** The immediately-preceding attempt's identity, if this is a correction re-attempt - carried through purely for traceability, never used to alter this attempt's own evaluation (every attempt always compares against the same approved baseline, never attempt-to-attempt). */
+    priorAttemptId?: string;
+    comparisonConfig?: Partial<ComparisonConfig>;
+    fidelityGeometryTolerancePx?: number;
+}
+/**
+ * One fully composed, inspectable review attempt. `overallState` is
+ * `'pass'` only when both `fidelity.state === 'pass'` and
+ * `contractEvaluation.overallVerdict === 'PASS'`; it is `'not-evaluated'`
+ * exactly when Prompt 6's own fidelity evaluation could not run at all
+ * (preserved, never collapsed into an ordinary FAIL); otherwise `'fail'` -
+ * this covers a structurally-incomparable baseline/candidate pair too,
+ * since v0.5's own `evaluateFrontendContract` already reports `'FAIL'`
+ * (never `'PASS'`) for that case, per its own established precedent, which
+ * this workflow reuses rather than re-deciding. `approvalEligible` is
+ * `true` only when `overallState === 'pass'` - it is never itself an
+ * approval action; the caller must still invoke the existing explicit
+ * `approveAndPersistBaseline`/`approveExternalReference` owners separately.
+ */
+export interface ReferenceCorrectionAttemptResult {
+    reviewRequestId: string;
+    attemptId: string;
+    priorAttemptId?: string;
+    referenceId: string;
+    referenceRequestId: string;
+    baselineObservationId: string;
+    candidateObservationId: string;
+    comparison: ComparisonArtifact;
+    fidelity: ReferenceCandidateFidelityEvaluation;
+    contractEvaluation: FrontendContractEvaluationResult;
+    overallState: ReferenceCorrectionOverallState;
+    approvalEligible: boolean;
+}
+export type ReviewReferenceCorrectionAttemptResult = {
+    ok: true;
+    attempt: ReferenceCorrectionAttemptResult;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 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 declare function reviewReferenceCorrectionAttempt(input: ReviewReferenceCorrectionAttemptInput): ReviewReferenceCorrectionAttemptResult;
+export {};