@dailephd/my-frontend-observer 0.8.1

package/dist/projectWorkflow/checkResult.d.ts

@@ -0,0 +1,85 @@
+import type { BaselineClause, ContractPrimitive, PerChangeClause } from '../domain/frontendContracts.js';
+import type { FrontendContractEvaluationArtifact } from '../domain/frontendContractEvaluationArtifact.js';
+import type { EvidenceReference } from '../domain/relationships.js';
+import type { ComparisonDifferenceSubject, DifferenceKind } from '../domain/comparison.js';
+import type { ReferenceCandidateFidelityEvaluation, ReferenceRequirementFidelityResult } from '../domain/externalReferenceFidelity.js';
+export declare const CHECK_RESULT_SCHEMA_VERSION: "1.0.0";
+export declare const CHECK_WORKFLOW_STATUSES: readonly ["PASS", "FAIL", "REVIEW_REQUIRED", "BLOCKED"];
+export type CheckWorkflowStatus = (typeof CHECK_WORKFLOW_STATUSES)[number];
+export declare const CHECK_MAX_ITEMS_PER_COLLECTION: 50;
+export declare const CHECK_MAX_SUPPORTING_EVIDENCE_PER_ITEM: 10;
+export interface CheckObservationSummary {
+    alias: string;
+    observationId: string;
+    requestId: string;
+    artifactPath: string;
+}
+export interface CheckComparisonSummary {
+    state: 'NOT_RUN' | 'BLOCKED' | 'comparable' | 'comparable-with-warnings' | 'incomparable';
+    comparisonId?: string;
+    artifactPath?: string;
+    differenceCount?: number;
+    relationshipChangeCount?: number;
+    diagnosticsCount?: number;
+}
+export interface CheckClauseProblem {
+    clauseId: string;
+    source: 'baseline' | 'change';
+    category?: 'requested' | 'expected-dependent' | 'protected' | 'preserved';
+    primitive: ContractPrimitive;
+    status: 'fail' | 'unavailable' | 'conflict';
+    reason?: string;
+    supportingEvidence: EvidenceReference[];
+}
+export interface CheckUnexpectedChange {
+    classification: 'unexpected';
+    subject: ComparisonDifferenceSubject;
+    differenceKind: DifferenceKind;
+    supportingEvidence: EvidenceReference[];
+}
+export interface CheckContractSummary {
+    configured: boolean;
+    state: 'NOT_CONFIGURED' | 'NOT_RUN' | 'PASS' | 'FAIL' | 'BLOCKED';
+    overallVerdict?: 'PASS' | 'FAIL';
+    evaluationId?: string;
+    artifactPath?: string;
+    failedClauses: CheckClauseProblem[];
+    unavailableClauses: CheckClauseProblem[];
+    unexpectedChanges: CheckUnexpectedChange[];
+    truncated: boolean;
+}
+export interface CheckReferenceSummary {
+    configured: boolean;
+    state: 'NOT_CONFIGURED' | 'NOT_RUN' | 'PASS' | 'FAIL' | 'BLOCKED';
+    referenceId?: string;
+    fidelityState?: 'not-evaluated' | 'pass' | 'fail';
+    blockedBy?: 'reference-inadequate' | 'incompatible';
+    failedRequirements: ReferenceRequirementFidelityResult[];
+    unavailableRequirements: ReferenceRequirementFidelityResult[];
+    truncated: boolean;
+}
+export interface CheckBlocker {
+    code: string;
+    message: string;
+}
+export interface CheckWorkflowResult {
+    schemaVersion: '1.0.0';
+    status: CheckWorkflowStatus;
+    baseline?: CheckObservationSummary;
+    candidate?: CheckObservationSummary;
+    comparison: CheckComparisonSummary;
+    contract: CheckContractSummary;
+    reference: CheckReferenceSummary;
+    blockers: CheckBlocker[];
+    limits: {
+        maxItemsPerCollection: 50;
+        maxSupportingEvidencePerItem: 10;
+        truncated: boolean;
+    };
+}
+export declare function emptyCheckResult(): CheckWorkflowResult;
+/** Project canonical contract evidence without evaluating any clause. */
+export declare function projectContractResult(artifact: FrontendContractEvaluationArtifact, baselineClauses: readonly BaselineClause[], changeClauses: readonly PerChangeClause[], artifactPath: string): CheckContractSummary;
+/** Project canonical in-memory fidelity evidence without inferring bindings. */
+export declare function projectReferenceResult(evaluation: ReferenceCandidateFidelityEvaluation): CheckReferenceSummary;
+export declare function finalizeCheckStatus(result: CheckWorkflowResult): CheckWorkflowResult;

package/dist/projectWorkflow/checkResult.js

@@ -0,0 +1,101 @@
+export const CHECK_RESULT_SCHEMA_VERSION = '1.0.0';
+export const CHECK_WORKFLOW_STATUSES = ['PASS', 'FAIL', 'REVIEW_REQUIRED', 'BLOCKED'];
+export const CHECK_MAX_ITEMS_PER_COLLECTION = 50;
+export const CHECK_MAX_SUPPORTING_EVIDENCE_PER_ITEM = 10;
+export function emptyCheckResult() {
+    return {
+        schemaVersion: CHECK_RESULT_SCHEMA_VERSION,
+        status: 'BLOCKED',
+        comparison: { state: 'NOT_RUN' },
+        contract: { configured: false, state: 'NOT_CONFIGURED', failedClauses: [], unavailableClauses: [], unexpectedChanges: [], truncated: false },
+        reference: { configured: false, state: 'NOT_CONFIGURED', failedRequirements: [], unavailableRequirements: [], truncated: false },
+        blockers: [],
+        limits: { maxItemsPerCollection: CHECK_MAX_ITEMS_PER_COLLECTION, maxSupportingEvidencePerItem: CHECK_MAX_SUPPORTING_EVIDENCE_PER_ITEM, truncated: false },
+    };
+}
+function boundedEvidence(evidence) {
+    return { value: evidence.slice(0, CHECK_MAX_SUPPORTING_EVIDENCE_PER_ITEM), truncated: evidence.length > CHECK_MAX_SUPPORTING_EVIDENCE_PER_ITEM };
+}
+/** Project canonical contract evidence without evaluating any clause. */
+export function projectContractResult(artifact, baselineClauses, changeClauses, artifactPath) {
+    const clauses = new Map();
+    for (const clause of baselineClauses)
+        clauses.set(clause.clauseId, { source: 'baseline', clause });
+    for (const clause of changeClauses)
+        clauses.set(clause.clauseId, { source: 'change', clause });
+    let truncated = false;
+    const problems = [];
+    for (const result of artifact.clauseResults) {
+        if (result.status === 'pass')
+            continue;
+        const authored = clauses.get(result.clauseId);
+        if (authored === undefined)
+            continue;
+        const evidence = boundedEvidence(result.supportingEvidence);
+        truncated ||= evidence.truncated;
+        problems.push({
+            clauseId: result.clauseId,
+            source: authored.source,
+            ...(authored.source === 'change' ? { category: authored.clause.category } : {}),
+            primitive: authored.clause.primitive,
+            status: result.status,
+            ...('reason' in result ? { reason: result.reason } : {}),
+            supportingEvidence: evidence.value,
+        });
+    }
+    const failedAll = problems.filter((item) => item.status === 'fail');
+    const unavailableAll = problems.filter((item) => item.status !== 'fail');
+    const failedClauses = failedAll.slice(0, CHECK_MAX_ITEMS_PER_COLLECTION);
+    const unavailableClauses = unavailableAll.slice(0, CHECK_MAX_ITEMS_PER_COLLECTION);
+    truncated ||= failedAll.length > failedClauses.length || unavailableAll.length > unavailableClauses.length;
+    const unexpectedChanges = artifact.unexpectedChanges.slice(0, CHECK_MAX_ITEMS_PER_COLLECTION).map((change) => {
+        const evidence = boundedEvidence(change.supportingEvidence);
+        truncated ||= evidence.truncated;
+        return { ...change, supportingEvidence: evidence.value };
+    });
+    truncated ||= artifact.unexpectedChanges.length > unexpectedChanges.length;
+    const blocked = unavailableAll.length > 0;
+    return {
+        configured: true,
+        state: blocked ? 'BLOCKED' : artifact.overallVerdict,
+        overallVerdict: artifact.overallVerdict,
+        evaluationId: artifact.evaluationId,
+        artifactPath,
+        failedClauses,
+        unavailableClauses,
+        unexpectedChanges,
+        truncated,
+    };
+}
+/** Project canonical in-memory fidelity evidence without inferring bindings. */
+export function projectReferenceResult(evaluation) {
+    const failedAll = evaluation.requirementResults.filter((item) => item.status === 'fail');
+    const unavailableAll = evaluation.requirementResults.filter((item) => item.status === 'unavailable');
+    const failedRequirements = failedAll.slice(0, CHECK_MAX_ITEMS_PER_COLLECTION);
+    const unavailableRequirements = unavailableAll.slice(0, CHECK_MAX_ITEMS_PER_COLLECTION);
+    const truncated = failedAll.length > failedRequirements.length || unavailableAll.length > unavailableRequirements.length;
+    const state = evaluation.state === 'not-evaluated' || unavailableAll.length > 0 ? 'BLOCKED' : evaluation.state === 'pass' ? 'PASS' : 'FAIL';
+    return {
+        configured: true,
+        state,
+        referenceId: evaluation.referenceId,
+        fidelityState: evaluation.state,
+        ...(evaluation.blockedBy === undefined ? {} : { blockedBy: evaluation.blockedBy }),
+        failedRequirements,
+        unavailableRequirements,
+        truncated,
+    };
+}
+export function finalizeCheckStatus(result) {
+    result.limits.truncated = result.contract.truncated || result.reference.truncated;
+    if (result.blockers.length > 0 || result.contract.state === 'BLOCKED' || result.reference.state === 'BLOCKED')
+        result.status = 'BLOCKED';
+    else if (result.contract.state === 'FAIL' || result.reference.state === 'FAIL')
+        result.status = 'FAIL';
+    else if (result.contract.configured || result.reference.configured)
+        result.status = 'PASS';
+    else
+        result.status = 'REVIEW_REQUIRED';
+    return result;
+}
+//# sourceMappingURL=checkResult.js.map

package/dist/projectWorkflow/checkResult.js.map

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

package/dist/projectWorkflow/projectConfig.d.ts

@@ -0,0 +1,43 @@
+import type { RawNamedTarget } from '../request/request.js';
+export declare const PROJECT_CONFIG_FILENAME: "frontend-observer.json";
+export declare const PROJECT_CONFIG_SCHEMA_VERSION: "1.1.0";
+export declare const SUPPORTED_PROJECT_CONFIG_SCHEMA_VERSIONS: readonly ["1.0.0", "1.1.0"];
+export declare const OBSERVATION_ALIAS_PATTERN: RegExp;
+export declare const RESERVED_OBSERVATION_ALIASES: Set<string>;
+export interface FrontendObserverAcceptanceConfig {
+    comparisonConfigFile?: string;
+    contract?: {
+        baselineArtifact: string;
+        changeArtifact: string;
+    };
+    reference?: {
+        approvedArtifact: string;
+        bindingsFile?: string;
+    };
+}
+export interface FrontendObserverProjectConfig {
+    schemaVersion: (typeof SUPPORTED_PROJECT_CONFIG_SCHEMA_VERSIONS)[number];
+    url: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    targets: RawNamedTarget[];
+    defaultBaseline: string;
+    acceptance?: FrontendObserverAcceptanceConfig;
+}
+export type ProjectConfigReadResult = {
+    ok: true;
+    config: FrontendObserverProjectConfig;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function validateObservationAlias(alias: string, allowReserved?: boolean): {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'invalid' | 'reserved';
+};
+export declare function validateProjectConfig(value: unknown): ProjectConfigReadResult;
+export declare function readProjectConfig(configPath: string): Promise<ProjectConfigReadResult>;

package/dist/projectWorkflow/projectConfig.js

@@ -0,0 +1,84 @@
+import { readFile } from 'node:fs/promises';
+import { normalizeRequest } from '../request/request.js';
+export const PROJECT_CONFIG_FILENAME = 'frontend-observer.json';
+export const PROJECT_CONFIG_SCHEMA_VERSION = '1.1.0';
+export const SUPPORTED_PROJECT_CONFIG_SCHEMA_VERSIONS = ['1.0.0', '1.1.0'];
+export const OBSERVATION_ALIAS_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export const RESERVED_OBSERVATION_ALIASES = new Set(['current']);
+export function validateObservationAlias(alias, allowReserved = false) {
+    if (!OBSERVATION_ALIAS_PATTERN.test(alias) || alias.includes('..'))
+        return { ok: false, reason: 'invalid' };
+    if (!allowReserved && RESERVED_OBSERVATION_ALIASES.has(alias))
+        return { ok: false, reason: 'reserved' };
+    return { ok: true };
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function validateProjectConfig(value) {
+    if (!isObject(value))
+        return { ok: false, reason: 'project configuration root must be an object' };
+    const version = value.schemaVersion;
+    if (!SUPPORTED_PROJECT_CONFIG_SCHEMA_VERSIONS.includes(version))
+        return { ok: false, reason: `unsupported project configuration schema version: ${String(version)}` };
+    const allowed = new Set(['schemaVersion', 'url', 'viewport', 'targets', 'defaultBaseline', ...(version === '1.1.0' ? ['acceptance'] : [])]);
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        return { ok: false, reason: `project configuration has unsupported field(s): ${unknown.join(', ')}` };
+    let acceptance;
+    if (value.acceptance !== undefined) {
+        if (!isObject(value.acceptance))
+            return { ok: false, reason: 'acceptance must be an object' };
+        if (Object.keys(value.acceptance).some((key) => !['comparisonConfigFile', 'contract', 'reference'].includes(key)))
+            return { ok: false, reason: 'acceptance has unsupported fields' };
+        const portable = (candidate) => {
+            if (typeof candidate !== 'string' || candidate.length === 0 || candidate.includes('\0') || candidate.includes('\\') || candidate.includes(':') || candidate.startsWith('/'))
+                return false;
+            return candidate.split('/').every((segment) => segment.length > 0 && segment !== '.' && segment !== '..');
+        };
+        if (value.acceptance.comparisonConfigFile !== undefined && !portable(value.acceptance.comparisonConfigFile))
+            return { ok: false, reason: 'comparisonConfigFile must be a portable project-relative path' };
+        const contract = value.acceptance.contract;
+        if (contract !== undefined && (!isObject(contract) || Object.keys(contract).some((key) => !['baselineArtifact', 'changeArtifact'].includes(key)) || !portable(contract.baselineArtifact) || !portable(contract.changeArtifact)))
+            return { ok: false, reason: 'contract requires portable baselineArtifact and changeArtifact paths' };
+        const reference = value.acceptance.reference;
+        if (reference !== undefined && (!isObject(reference) || Object.keys(reference).some((key) => !['approvedArtifact', 'bindingsFile'].includes(key)) || !portable(reference.approvedArtifact) || (reference.bindingsFile !== undefined && !portable(reference.bindingsFile))))
+            return { ok: false, reason: 'reference requires portable approvedArtifact and optional bindingsFile paths' };
+        acceptance = value.acceptance;
+    }
+    if (typeof value.defaultBaseline !== 'string')
+        return { ok: false, reason: 'defaultBaseline must be a string' };
+    const alias = validateObservationAlias(value.defaultBaseline);
+    if (!alias.ok)
+        return { ok: false, reason: alias.reason === 'reserved' ? 'defaultBaseline uses the reserved alias "current"' : 'defaultBaseline has invalid alias syntax' };
+    const normalized = normalizeRequest({
+        targetUrl: value.url,
+        viewport: value.viewport,
+        targets: value.targets,
+        outputLocation: '.frontend-observer/evidence/_validation',
+    });
+    if (!normalized.ok)
+        return { ok: false, reason: normalized.diagnostics.map((entry) => entry.message).join('; ') };
+    return {
+        ok: true,
+        config: {
+            schemaVersion: version,
+            url: normalized.request.targetUrl,
+            viewport: normalized.request.viewport,
+            targets: value.targets,
+            defaultBaseline: value.defaultBaseline,
+            ...(acceptance === undefined ? {} : { acceptance }),
+        },
+    };
+}
+export async function readProjectConfig(configPath) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(configPath, 'utf8'));
+    }
+    catch (error) {
+        return { ok: false, reason: `project configuration could not be read: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    return validateProjectConfig(value);
+}
+//# sourceMappingURL=projectConfig.js.map

package/dist/projectWorkflow/projectConfig.js.map

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

package/dist/projectWorkflow/projectDiscovery.d.ts

@@ -0,0 +1,9 @@
+export type DiscoverProjectResult = {
+    ok: true;
+    projectRoot: string;
+    configPath: string;
+} | {
+    ok: false;
+    reason: 'project-not-initialized';
+};
+export declare function discoverFrontendObserverProject(startDirectory: string): Promise<DiscoverProjectResult>;

package/dist/projectWorkflow/projectDiscovery.js

@@ -0,0 +1,20 @@
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { PROJECT_CONFIG_FILENAME } from './projectConfig.js';
+export async function discoverFrontendObserverProject(startDirectory) {
+    let current = path.resolve(startDirectory);
+    for (;;) {
+        const configPath = path.join(current, PROJECT_CONFIG_FILENAME);
+        try {
+            await access(configPath);
+            return { ok: true, projectRoot: current, configPath };
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return { ok: false, reason: 'project-not-initialized' };
+            current = parent;
+        }
+    }
+}
+//# sourceMappingURL=projectDiscovery.js.map

package/dist/projectWorkflow/projectDiscovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectDiscovery.js","sourceRoot":"","sources":["../../src/projectWorkflow/projectDiscovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAI7D,MAAM,CAAC,KAAK,UAAU,+BAA+B,CAAC,cAAsB;IAC1E,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3C,SAAS,CAAC;QACR,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,uBAAuB,CAAC,CAAC;QAC/D,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;YACzB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACrC,IAAI,MAAM,KAAK,OAAO;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;YAChF,OAAO,GAAG,MAAM,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/projectWorkflow/projectPaths.d.ts

@@ -0,0 +1,8 @@
+export declare const PROJECT_STATE_DIRECTORY: ".frontend-observer";
+export declare const ALIAS_CATALOG_FILENAME: "catalog.json";
+export declare function projectConfigPath(projectRoot: string): string;
+export declare function projectStateRoot(projectRoot: string): string;
+export declare function aliasCatalogPath(projectRoot: string): string;
+export declare function projectEvidenceRoot(projectRoot: string): string;
+export declare function projectObservationsRoot(projectRoot: string): string;
+export declare function observationOutputLocation(alias: string): string;

package/dist/projectWorkflow/projectPaths.js

@@ -0,0 +1,23 @@
+import path from 'node:path';
+import { PROJECT_CONFIG_FILENAME } from './projectConfig.js';
+export const PROJECT_STATE_DIRECTORY = '.frontend-observer';
+export const ALIAS_CATALOG_FILENAME = 'catalog.json';
+export function projectConfigPath(projectRoot) {
+    return path.join(projectRoot, PROJECT_CONFIG_FILENAME);
+}
+export function projectStateRoot(projectRoot) {
+    return path.join(projectRoot, PROJECT_STATE_DIRECTORY);
+}
+export function aliasCatalogPath(projectRoot) {
+    return path.join(projectStateRoot(projectRoot), ALIAS_CATALOG_FILENAME);
+}
+export function projectEvidenceRoot(projectRoot) {
+    return path.join(projectStateRoot(projectRoot), 'evidence');
+}
+export function projectObservationsRoot(projectRoot) {
+    return path.join(projectEvidenceRoot(projectRoot), 'observations');
+}
+export function observationOutputLocation(alias) {
+    return `${PROJECT_STATE_DIRECTORY}/evidence/observations/${alias}`;
+}
+//# sourceMappingURL=projectPaths.js.map

package/dist/projectWorkflow/projectPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectPaths.js","sourceRoot":"","sources":["../../src/projectWorkflow/projectPaths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAA6B,CAAC;AACrE,MAAM,CAAC,MAAM,sBAAsB,GAAG,cAAuB,CAAC;AAE9D,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACnD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,uBAAuB,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,uBAAuB,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,sBAAsB,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,WAAmB;IACzD,OAAO,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAAa;IACrD,OAAO,GAAG,uBAAuB,0BAA0B,KAAK,EAAE,CAAC;AACrE,CAAC"}

package/dist/request/paths.d.ts

@@ -0,0 +1,14 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+export type NormalizeOutputLocationResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    diagnostic: Diagnostic;
+};
+/**
+ * Portable, relative, forward-slash logical path only: no drive letter, no
+ * leading "/", no ".." segment. Backslashes are converted to forward slashes
+ * before validation. Never touches the real filesystem.
+ */
+export declare function normalizeOutputLocation(raw: string): NormalizeOutputLocationResult;

package/dist/request/paths.js

@@ -0,0 +1,33 @@
+const DRIVE_LETTER_RE = /^[A-Za-z]:\//;
+/**
+ * Portable, relative, forward-slash logical path only: no drive letter, no
+ * leading "/", no ".." segment. Backslashes are converted to forward slashes
+ * before validation. Never touches the real filesystem.
+ */
+export function normalizeOutputLocation(raw) {
+    const withForwardSlashes = raw.replace(/\\/g, '/');
+    if (withForwardSlashes.startsWith('/') || DRIVE_LETTER_RE.test(withForwardSlashes)) {
+        return {
+            ok: false,
+            diagnostic: {
+                code: 'invalid-request',
+                severity: 'error',
+                message: 'outputLocation must be a relative, portable path (no drive letter or leading "/")',
+            },
+        };
+    }
+    const segments = withForwardSlashes.split('/');
+    if (segments.some((segment) => segment === '..')) {
+        return {
+            ok: false,
+            diagnostic: {
+                code: 'invalid-request',
+                severity: 'error',
+                message: 'outputLocation must not contain ".." segments',
+            },
+        };
+    }
+    const cleaned = segments.filter((segment) => segment.length > 0 && segment !== '.');
+    return { ok: true, value: cleaned.length > 0 ? cleaned.join('/') : '.' };
+}
+//# sourceMappingURL=paths.js.map

package/dist/request/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/request/paths.ts"],"names":[],"mappings":"AAIA,MAAM,eAAe,GAAG,cAAc,CAAC;AAEvC;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,MAAM,kBAAkB,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAEnD,IAAI,kBAAkB,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACnF,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE;gBACV,IAAI,EAAE,iBAAiB;gBACvB,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,mFAAmF;aAC7F;SACF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,EAAE,CAAC;QACjD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE;gBACV,IAAI,EAAE,iBAAiB;gBACvB,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,+CAA+C;aACzD;SACF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,KAAK,GAAG,CAAC,CAAC;IACpF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AAC3E,CAAC"}

package/dist/request/request.d.ts

@@ -0,0 +1,111 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { ExplicitStateDimensions } from '../domain/explicitState.js';
+export type TargetLocator = {
+    kind: 'role';
+    role: string;
+    name?: string;
+} | {
+    kind: 'id';
+    value: string;
+} | {
+    kind: 'data-attribute';
+    attribute: string;
+    value: string;
+} | {
+    kind: 'semantic-element';
+    tag: string;
+} | {
+    kind: 'css';
+    selector: string;
+} | {
+    kind: 'text';
+    text: string;
+};
+export interface NamedTarget {
+    name: string;
+    locators: TargetLocator[];
+}
+/** Raw, not-yet-validated target shape as it may appear in a RawObservationRequest. Exactly one of `selector` (legacy) or `locators` (canonical) may be present, never both. */
+export interface RawNamedTarget {
+    name?: unknown;
+    selector?: unknown;
+    locators?: unknown;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export type ReadinessCondition = 'load' | 'domcontentloaded';
+export interface ReadinessConfig {
+    condition: ReadinessCondition;
+    timeoutMs: number;
+}
+/**
+ * v0.3 Batch 1 canonical scroll-action shape. Exactly the two bounded action
+ * kinds below are supported; `target` on `target-scroll-by` refers to the
+ * existing stable observer-owned target `name` (see `NamedTarget`), never a
+ * CSS selector, Playwright locator, or DOM id evaluated directly.
+ */
+export type ScrollAction = {
+    kind: 'window-scroll-by';
+    deltaX: number;
+    deltaY: number;
+} | {
+    kind: 'target-scroll-by';
+    target: string;
+    deltaX: number;
+    deltaY: number;
+};
+export interface ScrollScenario {
+    action: ScrollAction;
+}
+export interface NormalizedObservationRequest {
+    targetUrl: string;
+    viewport: Viewport;
+    targets: NamedTarget[];
+    outputLocation: string;
+    timeoutMs: number;
+    readiness: ReadinessConfig;
+    scrollScenario?: ScrollScenario;
+    /**
+     * v0.7 Prompt 4 addition (additive, optional). Explicit, caller/config-
+     * supplied frontend state identity for this observation - never inferred
+     * by the observer from screenshot pixels, CSS, DOM, URLs, or any other
+     * browser-observed evidence (see domain/explicitState.ts). Used only by
+     * comparability/compatibility evaluation (domain/comparisonEngine.ts,
+     * domain/externalReferenceCompatibility.ts); omitting it preserves every
+     * pre-Prompt-4 observation/comparison behavior unchanged.
+     */
+    explicitState?: ExplicitStateDimensions;
+}
+export interface RawObservationRequest {
+    targetUrl?: unknown;
+    viewport?: unknown;
+    targets?: unknown;
+    outputLocation?: unknown;
+    timeoutMs?: unknown;
+    readiness?: unknown;
+    scrollScenario?: unknown;
+    explicitState?: unknown;
+}
+export type NormalizeRequestResult = {
+    ok: true;
+    request: NormalizedObservationRequest;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * Conservative bound for a single controlled-observation scroll action. No
+ * existing repository precedent for a scroll-delta magnitude; chosen large
+ * enough to reach realistic overflow content (documents/containers well
+ * beyond one viewport) while staying far short of a pathological/runaway
+ * request - see docs/CONTRACTS.md and tests/unit/request.test.ts.
+ */
+export declare const SCROLL_DELTA_MAX_ABS = 20000;
+/**
+ * Total, never throws. Collects every applicable diagnostic before returning
+ * (does not short-circuit on the first violation) so callers see every
+ * problem at once, in deterministic order.
+ */
+export declare function normalizeRequest(raw: RawObservationRequest): NormalizeRequestResult;