@dailephd/my-frontend-observer 0.8.1

package/dist/domain/frontendContractEvaluationArtifact.js

@@ -0,0 +1,108 @@
+/**
+ * v0.5 Batch 3 minimal additive persistence envelope for
+ * `frontendContractEvaluation.ts#evaluateFrontendContract`'s output. Batch 1
+ * froze the evaluation-result vocabulary (`ClauseEvaluationResult`,
+ * `OverallVerdict`) and Batch 2 froze the evaluator itself, but neither froze
+ * a persistable artifact envelope (identity, provenance, schema ownership,
+ * source-evidence references) - this module adds exactly that and nothing
+ * else. It reuses the frozen result types unchanged, contains no evaluation
+ * logic, and never imports/calls `evaluateFrontendContract`.
+ *
+ * Independent artifact family from observation (`1.2.0`), comparison
+ * (`1.0.0`), and the frontend-contract family (`1.0.0`) - never reuses
+ * `ARTIFACT_KIND`/`COMPARISON_ARTIFACT_KIND`/`CONTRACT_ARTIFACT_KIND`.
+ */
+import { isValidEvidenceReference } from './relationships.js';
+import { PRODUCER_NAME, SCHEMA_VERSION as OBSERVATION_SCHEMA_VERSION } from './schema.js';
+import { isValidClauseEvaluationResult, OVERALL_VERDICTS, isValidFrontendContractObservationReference } from './frontendContracts.js';
+import { DIFFERENCE_KINDS } from './comparison.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export const EVALUATION_ARTIFACT_KIND = 'my-frontend-observer/frontend-contract-evaluation';
+export const EVALUATION_SCHEMA_VERSION = '1.0.0';
+function isValidFrontendContractEvaluationSourceReference(value) {
+    return isPlainObject(value) && isNonEmptyString(value.baselineId) && isNonEmptyString(value.contractId);
+}
+function isValidUnexpectedChangeResult(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (value.classification !== 'unexpected')
+        return false;
+    if (typeof value.differenceKind !== 'string' || !DIFFERENCE_KINDS.includes(value.differenceKind))
+        return false;
+    if (!isPlainObject(value.subject) || typeof value.subject.type !== 'string')
+        return false;
+    return Array.isArray(value.supportingEvidence) && value.supportingEvidence.every((e) => isValidEvidenceReference(e));
+}
+export function isValidFrontendContractEvaluationArtifact(value) {
+    if (!isPlainObject(value))
+        return { valid: false, reason: 'artifact must be an object' };
+    if (value.artifactKind !== EVALUATION_ARTIFACT_KIND)
+        return { valid: false, reason: 'artifactKind mismatch' };
+    if (value.schemaVersion !== EVALUATION_SCHEMA_VERSION)
+        return { valid: false, reason: 'schemaVersion mismatch' };
+    if (!isNonEmptyString(value.evaluationId))
+        return { valid: false, reason: 'evaluationId must be a non-empty string' };
+    if (!isNonEmptyString(value.evaluationRequestId))
+        return { valid: false, reason: 'evaluationRequestId must be a non-empty string' };
+    if (!isPlainObject(value.producer) || value.producer.name !== PRODUCER_NAME || !isNonEmptyString(value.producer.version)) {
+        return { valid: false, reason: 'producer must be { name: "my-frontend-observer", version: string }' };
+    }
+    if (!isPlainObject(value.provenance) || !isNonEmptyString(value.provenance.evaluatedAt)) {
+        return { valid: false, reason: 'provenance.evaluatedAt must be a non-empty string' };
+    }
+    if (!isValidFrontendContractEvaluationSourceReference(value.contracts))
+        return { valid: false, reason: 'contracts reference is invalid' };
+    if (!isValidFrontendContractObservationReference(value.before))
+        return { valid: false, reason: 'before source observation reference is invalid' };
+    if (!isValidFrontendContractObservationReference(value.after))
+        return { valid: false, reason: 'after source observation reference is invalid' };
+    if (value.before.observationSchemaVersion !== OBSERVATION_SCHEMA_VERSION || value.after.observationSchemaVersion !== OBSERVATION_SCHEMA_VERSION) {
+        return { valid: false, reason: 'source observation references must carry the current observation schema version' };
+    }
+    if (!isNonEmptyString(value.comparisonId))
+        return { valid: false, reason: 'comparisonId must be a non-empty string' };
+    if (!isNonEmptyString(value.comparisonRequestId))
+        return { valid: false, reason: 'comparisonRequestId must be a non-empty string' };
+    if (typeof value.overallVerdict !== 'string' || !OVERALL_VERDICTS.includes(value.overallVerdict)) {
+        return { valid: false, reason: 'overallVerdict must be "PASS" or "FAIL"' };
+    }
+    if (!Array.isArray(value.activeBaselineClauseIds) || !value.activeBaselineClauseIds.every((id) => isNonEmptyString(id))) {
+        return { valid: false, reason: 'activeBaselineClauseIds must be an array of non-empty strings' };
+    }
+    if (!Array.isArray(value.supersededBaselineClauseIds) || !value.supersededBaselineClauseIds.every((id) => isNonEmptyString(id))) {
+        return { valid: false, reason: 'supersededBaselineClauseIds must be an array of non-empty strings' };
+    }
+    if (!Array.isArray(value.clauseResults) || !value.clauseResults.every((r) => isValidClauseEvaluationResult(r))) {
+        return { valid: false, reason: 'clauseResults must be an array of valid ClauseEvaluationResult values' };
+    }
+    if (!Array.isArray(value.unexpectedChanges) || !value.unexpectedChanges.every((u) => isValidUnexpectedChangeResult(u))) {
+        return { valid: false, reason: 'unexpectedChanges must be an array of valid UnexpectedChangeResult values' };
+    }
+    return { valid: true };
+}
+export function buildFrontendContractEvaluationArtifact(input) {
+    return {
+        artifactKind: EVALUATION_ARTIFACT_KIND,
+        schemaVersion: EVALUATION_SCHEMA_VERSION,
+        evaluationId: input.evaluationId,
+        evaluationRequestId: input.evaluationRequestId,
+        producer: { name: PRODUCER_NAME, version: input.producerVersion },
+        provenance: { evaluatedAt: input.evaluatedAt },
+        contracts: { baselineId: input.baselineId, contractId: input.contractId },
+        before: input.before,
+        after: input.after,
+        comparisonId: input.comparisonId,
+        comparisonRequestId: input.comparisonRequestId,
+        overallVerdict: input.overallVerdict,
+        activeBaselineClauseIds: input.activeBaselineClauseIds,
+        supersededBaselineClauseIds: input.supersededBaselineClauseIds,
+        clauseResults: input.clauseResults,
+        unexpectedChanges: input.unexpectedChanges,
+    };
+}
+//# sourceMappingURL=frontendContractEvaluationArtifact.js.map

package/dist/domain/frontendContractEvaluationArtifact.js.map

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

package/dist/domain/frontendContractIdentity.d.ts

@@ -0,0 +1,39 @@
+import type { ContractPrimitive, ContractTolerance } from './frontendContracts.js';
+interface ContractRequestIdentityClauseInput {
+    primitive: ContractPrimitive;
+    tolerance?: ContractTolerance;
+}
+/**
+ * Pure function of {sourceObservationId, clause primitives/tolerances (order
+ * preserved), sorted supersedes ids} only. Never includes a filesystem path,
+ * output location, a captured timestamp, or clauseId (clauseId is itself
+ * derived from primitive/tolerance, so including it would be redundant with -
+ * and could desynchronize from - the content it names).
+ */
+export declare function buildFrontendContractRequestIdentity(sourceObservationId: string, clauses: readonly ContractRequestIdentityClauseInput[], supersedesIds: readonly string[]): string;
+/**
+ * Fresh, opaque per-authored-instance identity - never derived from a
+ * timestamp alone, never collides even when called twice with the same
+ * requestIdentity within the same millisecond.
+ */
+export declare function buildFrontendContractInstanceIdentity(requestIdentity: string): string;
+/** Deterministic identity of a single clause's own semantic content - independent of authoring order or the contract it belongs to. */
+export declare function buildClauseIdentity(primitive: ContractPrimitive, tolerance?: ContractTolerance): string;
+/**
+ * Batch 3 addition (additive only - does not change any Batch 1 identity
+ * function's behavior): pure function of {baselineId, contractId,
+ * beforeObservationId, afterObservationId, comparisonRequestId} only, in the
+ * same canonicalize+sha256 style as `buildFrontendContractRequestIdentity`.
+ * Deliberately takes `comparisonRequestId` (comparison's own deterministic
+ * identity), never `comparisonId` (comparison's fresh per-execution instance
+ * id, per `comparisonIdentity.ts#buildComparisonIdentity`) - using the
+ * instance id here would make semantically identical evaluations of the same
+ * before/after pair never share an identity. Never includes a filesystem
+ * path, output location, or captured timestamp. Two evaluations of the same
+ * baseline/contract/observation-pair/comparison-request combination share
+ * this identity even if run from different operational locations;
+ * `buildFrontendContractInstanceIdentity` (already generic) is reused
+ * unchanged to derive the fresh per-execution `evaluationId` from it.
+ */
+export declare function buildFrontendContractEvaluationRequestIdentity(baselineId: string, contractId: string, beforeObservationId: string, afterObservationId: string, comparisonRequestId: string): string;
+export {};

package/dist/domain/frontendContractIdentity.js

@@ -0,0 +1,70 @@
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * Deliberately duplicated from domain/comparisonIdentity.ts#canonicalize (itself
+ * duplicated from domain/identity.ts#canonicalize) 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;
+}
+/**
+ * Pure function of {sourceObservationId, clause primitives/tolerances (order
+ * preserved), sorted supersedes ids} only. Never includes a filesystem path,
+ * output location, a captured timestamp, or clauseId (clauseId is itself
+ * derived from primitive/tolerance, so including it would be redundant with -
+ * and could desynchronize from - the content it names).
+ */
+export function buildFrontendContractRequestIdentity(sourceObservationId, clauses, supersedesIds) {
+    const semanticView = {
+        sourceObservationId,
+        clauses: clauses.map((clause) => ({ primitive: clause.primitive, tolerance: clause.tolerance ?? null })),
+        supersedes: [...supersedesIds].sort(),
+    };
+    const serialized = JSON.stringify(canonicalize(semanticView));
+    return createHash('sha256').update(serialized).digest('hex');
+}
+/**
+ * Fresh, opaque per-authored-instance identity - never derived from a
+ * timestamp alone, never collides even when called twice with the same
+ * requestIdentity within the same millisecond.
+ */
+export function buildFrontendContractInstanceIdentity(requestIdentity) {
+    const nonce = randomBytes(16).toString('hex');
+    return `${requestIdentity}-${nonce}`;
+}
+/** Deterministic identity of a single clause's own semantic content - independent of authoring order or the contract it belongs to. */
+export function buildClauseIdentity(primitive, tolerance) {
+    const serialized = JSON.stringify(canonicalize({ primitive, tolerance: tolerance ?? null }));
+    return createHash('sha256').update(serialized).digest('hex');
+}
+/**
+ * Batch 3 addition (additive only - does not change any Batch 1 identity
+ * function's behavior): pure function of {baselineId, contractId,
+ * beforeObservationId, afterObservationId, comparisonRequestId} only, in the
+ * same canonicalize+sha256 style as `buildFrontendContractRequestIdentity`.
+ * Deliberately takes `comparisonRequestId` (comparison's own deterministic
+ * identity), never `comparisonId` (comparison's fresh per-execution instance
+ * id, per `comparisonIdentity.ts#buildComparisonIdentity`) - using the
+ * instance id here would make semantically identical evaluations of the same
+ * before/after pair never share an identity. Never includes a filesystem
+ * path, output location, or captured timestamp. Two evaluations of the same
+ * baseline/contract/observation-pair/comparison-request combination share
+ * this identity even if run from different operational locations;
+ * `buildFrontendContractInstanceIdentity` (already generic) is reused
+ * unchanged to derive the fresh per-execution `evaluationId` from it.
+ */
+export function buildFrontendContractEvaluationRequestIdentity(baselineId, contractId, beforeObservationId, afterObservationId, comparisonRequestId) {
+    const semanticView = { baselineId, contractId, beforeObservationId, afterObservationId, comparisonRequestId };
+    const serialized = JSON.stringify(canonicalize(semanticView));
+    return createHash('sha256').update(serialized).digest('hex');
+}
+//# sourceMappingURL=frontendContractIdentity.js.map

package/dist/domain/frontendContractIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontendContractIdentity.js","sourceRoot":"","sources":["../../src/domain/frontendContractIdentity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD;;;;;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;AAOD;;;;;;GAMG;AACH,MAAM,UAAU,oCAAoC,CAClD,mBAA2B,EAC3B,OAAsD,EACtD,aAAgC;IAEhC,MAAM,YAAY,GAAG;QACnB,mBAAmB;QACnB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC;QACxG,UAAU,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,IAAI,EAAE;KACtC,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;;;;GAIG;AACH,MAAM,UAAU,qCAAqC,CAAC,eAAuB;IAC3E,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO,GAAG,eAAe,IAAI,KAAK,EAAE,CAAC;AACvC,CAAC;AAED,uIAAuI;AACvI,MAAM,UAAU,mBAAmB,CAAC,SAA4B,EAAE,SAA6B;IAC7F,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7F,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,8CAA8C,CAC5D,UAAkB,EAClB,UAAkB,EAClB,mBAA2B,EAC3B,kBAA0B,EAC1B,mBAA2B;IAE3B,MAAM,YAAY,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,CAAC;IAC9G,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/frontendContracts.d.ts

@@ -0,0 +1,188 @@
+/**
+ * v0.5 Batch 1 frontend contract / change-scope contract. Frozen here as
+ * pure types/constants/structural validators only - downstream of the v0.4
+ * observation/comparison/relationship system (src/domain/comparison.ts,
+ * src/domain/relationships.ts, src/domain/schema.ts). This batch implements
+ * neither contract evaluation, unexpected-change classification, PASS/FAIL
+ * computation, nor persistence - see docs/ARCHITECTURE.md.
+ *
+ * Contract and observation/comparison are different evidence products: this
+ * module never reuses ARTIFACT_KIND (observation) or COMPARISON_ARTIFACT_KIND,
+ * and adds no field to ComparisonConfig/ComparisonArtifact.
+ */
+import type { EvidenceReference, PairwiseRelationshipKind, PageLevelRelationshipKind } from './relationships.js';
+import type { DependencyProperty } from './comparison.js';
+import { PRODUCER_NAME, SCHEMA_VERSION as OBSERVATION_SCHEMA_VERSION } from './schema.js';
+export declare const CONTRACT_ARTIFACT_KIND: "my-frontend-observer/frontend-contract";
+export declare const CONTRACT_SCHEMA_VERSION: "1.0.0";
+/** The authored per-change contract has exactly these 4 intent categories - `'unexpected'` is never a member. */
+export declare const AUTHORED_CHANGE_SCOPE_CATEGORIES: readonly ["requested", "expected-dependent", "protected", "preserved"];
+export type AuthoredChangeScopeCategory = (typeof AUTHORED_CHANGE_SCOPE_CATEGORIES)[number];
+export declare function isAuthoredChangeScopeCategory(value: unknown): value is AuthoredChangeScopeCategory;
+/**
+ * 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 declare const CHANGE_SCOPE_CLASSIFICATIONS: readonly ["requested", "expected-dependent", "protected", "preserved", "unexpected"];
+export type ChangeScopeClassification = (typeof CHANGE_SCOPE_CLASSIFICATIONS)[number];
+export declare const EXPECTED_DEPENDENT_MODES: readonly ["required", "permitted"];
+export type ExpectedDependentMode = (typeof EXPECTED_DEPENDENT_MODES)[number];
+export declare function isValidExpectedDependentMode(value: unknown): value is ExpectedDependentMode;
+/** Independently declared from GEOMETRY_TOLERANCE_*_PX (src/domain/relationships.ts): comparison tolerance suppresses insignificant geometry noise and is never contract authorization. */
+export declare const CONTRACT_TOLERANCE_ABSOLUTE_PX_MIN = 0;
+export declare const CONTRACT_TOLERANCE_ABSOLUTE_PX_MAX = 100;
+export declare const CONTRACT_TOLERANCE_PERCENT_MIN = 0;
+export declare const CONTRACT_TOLERANCE_PERCENT_MAX = 100;
+export type ContractTolerance = {
+    kind: 'exact';
+} | {
+    kind: 'absolute-px';
+    amount: number;
+} | {
+    kind: 'percent';
+    amount: number;
+};
+export declare function isValidContractTolerance(value: unknown): value is ContractTolerance;
+/** Every contract primitive kind this batch freezes - deliberately bounded, never a generic rule/expression language. */
+export declare const CONTRACT_PRIMITIVE_KINDS: readonly ["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"];
+export type ContractPrimitiveKind = (typeof CONTRACT_PRIMITIVE_KINDS)[number];
+/** `target-fits-inside` mirrors relationships.ts's GEOMETRIC_FIT_RELATIONSHIPS ('fits-inside') - geometric fit, explicitly distinct from schema.ts's TargetContainment (DOM containment). */
+export type ContractPrimitive = {
+    kind: 'target-visible';
+    target: string;
+} | {
+    kind: 'target-not-clipped';
+    target: string;
+    axis?: 'horizontal' | 'vertical' | 'both';
+} | {
+    kind: 'target-width-within-bound';
+    target: string;
+    minPx?: number;
+    maxPx?: number;
+} | {
+    kind: 'targets-do-not-overlap';
+    targetA: string;
+    targetB: string;
+} | {
+    kind: 'target-wider-than';
+    targetA: string;
+    targetB: string;
+} | {
+    kind: 'target-follows-vertically';
+    targetA: string;
+    targetB: string;
+} | {
+    kind: 'target-fits-inside';
+    target: string;
+    container: string;
+} | {
+    kind: 'document-width-fits-viewport';
+} | {
+    kind: 'scroll-owner-is-document';
+} | {
+    kind: 'target-does-not-own-scroll';
+    target: string;
+} | {
+    kind: 'target-begins-below-initial-viewport';
+    target: string;
+} | {
+    kind: 'relationship-unchanged';
+    relationshipKind: PairwiseRelationshipKind | PageLevelRelationshipKind;
+    subjectTarget?: string;
+    relatedTarget?: string;
+} | {
+    kind: 'property-unchanged-within-tolerance';
+    target: string;
+    property: DependencyProperty;
+    tolerance: ContractTolerance;
+} | {
+    kind: 'property-increases';
+    target: string;
+    property: DependencyProperty;
+    minimumDeltaPx?: number;
+} | {
+    kind: 'property-decreases';
+    target: string;
+    property: DependencyProperty;
+    minimumDeltaPx?: number;
+};
+export declare function isValidContractPrimitive(value: unknown): value is ContractPrimitive;
+export interface FrontendContractClauseBase {
+    clauseId: string;
+    primitive: ContractPrimitive;
+    supportingEvidence: EvidenceReference[];
+}
+export type BaselineClause = FrontendContractClauseBase;
+export declare function isValidBaselineClause(value: unknown): value is BaselineClause;
+export interface PerChangeClause extends FrontendContractClauseBase {
+    category: AuthoredChangeScopeCategory;
+    expectedDependentMode?: ExpectedDependentMode;
+    /** Explicit supersession of baseline clause identities - never inferred from same-target/same-property overlap. Non-empty when present. */
+    supersedesBaselineClauseIds?: string[];
+}
+export declare function isValidPerChangeClause(value: unknown): value is PerChangeClause;
+/** Enough logical identity to trace a contract back to its authoritative source observation without embedding the full ObservationArtifact. */
+export interface FrontendContractObservationReference {
+    observationId: string;
+    requestId: string;
+    producer: {
+        name: typeof PRODUCER_NAME;
+        version: string;
+    };
+    observationSchemaVersion: typeof OBSERVATION_SCHEMA_VERSION;
+}
+export declare function isValidFrontendContractObservationReference(value: unknown): value is FrontendContractObservationReference;
+export interface PersistentBaselineContract {
+    artifactKind: typeof CONTRACT_ARTIFACT_KIND;
+    schemaVersion: typeof CONTRACT_SCHEMA_VERSION;
+    contractClass: 'baseline';
+    baselineId: string;
+    /** Explicit, append-based supersession - never rewrites/removes the prior baseline value. */
+    supersedesBaselineId?: string;
+    sourceObservation: FrontendContractObservationReference;
+    clauses: BaselineClause[];
+    provenance: {
+        approvedAt: string;
+    };
+}
+export type FrontendContractValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+export declare function isValidPersistentBaselineContract(value: unknown): FrontendContractValidationResult;
+export interface PerChangeContract {
+    artifactKind: typeof CONTRACT_ARTIFACT_KIND;
+    schemaVersion: typeof CONTRACT_SCHEMA_VERSION;
+    contractClass: 'change';
+    contractId: string;
+    contractRequestId: string;
+    activeBaselineIds: string[];
+    clauses: PerChangeClause[];
+}
+export declare function isValidPerChangeContract(value: unknown): FrontendContractValidationResult;
+export declare const CLAUSE_RESULT_STATUSES: readonly ["pass", "fail", "unavailable", "conflict"];
+export type ClauseResultStatus = (typeof CLAUSE_RESULT_STATUSES)[number];
+export type ClauseEvaluationResult = {
+    clauseId: string;
+    status: 'pass' | 'fail';
+    supportingEvidence: EvidenceReference[];
+} | {
+    clauseId: string;
+    status: 'unavailable';
+    reason: string;
+    supportingEvidence: EvidenceReference[];
+} | {
+    clauseId: string;
+    status: 'conflict';
+    conflictingClauseIds: string[];
+    reason: string;
+    supportingEvidence: EvidenceReference[];
+};
+/** Honest per-clause result vocabulary: `'unavailable'` requires a non-empty reason (never fabricated pass/fail); `'conflict'` requires at least 2 conflicting clause ids. */
+export declare function isValidClauseEvaluationResult(value: unknown): value is ClauseEvaluationResult;
+export declare const OVERALL_VERDICTS: readonly ["PASS", "FAIL"];
+export type OverallVerdict = (typeof OVERALL_VERDICTS)[number];