@dailephd/my-frontend-observer 0.8.1

package/dist/viewerServer/evidence/mediaResolver.js

@@ -0,0 +1,85 @@
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { classifyManifest } from './classify.js';
+import { decodeArtifactHandle } from './handles.js';
+import { findImportedReferenceDir } from './index.js';
+import { resolveContainedDir, resolveContainedFile } from './pathSafety.js';
+const IMAGE_FORMAT_MIME = {
+    png: 'image/png',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+};
+function isMediaRole(value) {
+    return value === 'screenshot' || value === 'image' || value === 'source-image';
+}
+/**
+ * Resolves one known media role owned/referenced by one known, already
+ * indexed-shaped artifact handle - never an arbitrary filesystem path. Every
+ * step re-derives and re-validates from the evidence root; nothing here
+ * trusts a client-supplied path string beyond the opaque handle/role pair.
+ */
+export async function resolveMedia(root, artifactHandle, role) {
+    if (!isMediaRole(role))
+        return { ok: false, reason: 'unknown media role' };
+    const decoded = decodeArtifactHandle(artifactHandle);
+    if (!decoded.ok)
+        return { ok: false, reason: 'unknown handle' };
+    const dir = resolveContainedDir(root, decoded.relativeDir);
+    if (dir === undefined)
+        return { ok: false, reason: 'unknown handle' };
+    const classified = await classifyManifest(join(dir, 'manifest.json'));
+    if (classified.supportState !== 'supported' || classified.family !== decoded.family) {
+        return { ok: false, reason: 'handle no longer resolves to a supported artifact' };
+    }
+    if (role === 'screenshot') {
+        if (classified.family !== 'observation')
+            return { ok: false, reason: 'screenshot is only defined for observation evidence' };
+        const field = classified.artifact.screenshot;
+        if (field.state !== 'available' && field.state !== 'partial')
+            return { ok: false, reason: 'this observation has no recorded screenshot' };
+        const resolved = resolveContainedFile(dir, field.value.path);
+        if (resolved === undefined)
+            return { ok: false, reason: 'screenshot reference is not a safe bare filename' };
+        return checkExists(resolved, 'image/png');
+    }
+    if (role === 'image') {
+        if (classified.family !== 'external-reference-imported' || !('image' in classified.artifact)) {
+            return { ok: false, reason: 'image is only defined for an imported external reference' };
+        }
+        const image = classified.artifact.image;
+        const resolved = resolveContainedFile(dir, image.path);
+        if (resolved === undefined)
+            return { ok: false, reason: 'image reference is not a safe bare filename' };
+        return checkExists(resolved, IMAGE_FORMAT_MIME[image.format]);
+    }
+    // role === 'source-image': only defined for an approved external reference, resolved through the imported
+    // artifact it points back to (never assumed to live in the approved artifact's own directory - frozen plan §18).
+    if (classified.family !== 'external-reference-approved' || !('sourceReference' in classified.artifact)) {
+        return { ok: false, reason: 'source-image is only defined for an approved external reference' };
+    }
+    const sourceReference = classified.artifact.sourceReference;
+    const sourceDir = await findImportedReferenceDir(root, sourceReference.referenceId);
+    if (sourceDir === undefined) {
+        return { ok: false, reason: 'the imported external-reference artifact that owns this image is not present under the current evidence root' };
+    }
+    const resolved = resolveContainedFile(sourceDir, sourceReference.image.path);
+    if (resolved === undefined)
+        return { ok: false, reason: 'source image reference is not a safe bare filename' };
+    return checkExists(resolved, IMAGE_FORMAT_MIME[sourceReference.image.format]);
+}
+async function checkExists(absolutePath, mimeType) {
+    try {
+        // lstat (never stat) - the artifact-directory containment check above only proves the
+        // *filename* is contained; it never proves the filename isn't itself a symlink/junction
+        // whose target escapes the evidence root. A regular stat() would follow such a link and
+        // could serve arbitrary filesystem content. Reject any non-regular-file entry outright.
+        const info = await lstat(absolutePath);
+        if (!info.isFile())
+            return { ok: false, reason: 'media reference does not point at a regular file' };
+    }
+    catch {
+        return { ok: false, reason: 'media file not found on disk' };
+    }
+    return { ok: true, absolutePath, mimeType };
+}
+//# sourceMappingURL=mediaResolver.js.map

package/dist/viewerServer/evidence/mediaResolver.js.map

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

package/dist/viewerServer/evidence/observationView.d.ts

@@ -0,0 +1,29 @@
+import type { LayoutRelationshipGraph } from '../../domain/relationships.js';
+export type ObservationRelationshipsResult = {
+    ok: true;
+    graph: LayoutRelationshipGraph;
+} | {
+    ok: false;
+    reason: 'unknown-handle';
+} | {
+    ok: false;
+    reason: 'not-an-observation';
+} | {
+    ok: false;
+    reason: 'not-currently-loadable';
+} | {
+    ok: false;
+    reason: 'derivation-failed';
+    detail: string;
+};
+/**
+ * Batch 3's one additive server-side computation: invokes the existing
+ * canonical, pure `deriveLayoutRelationships` (src/domain/relationships.ts)
+ * against one already-validated, already-classified `ObservationArtifact` -
+ * never a second relationship engine, never computed in React. Mirrors the
+ * same handle-decode -> contained-dir-resolve -> re-classify defense-in-depth
+ * discipline as `loadArtifactByHandle`/`resolveMedia` (evidence/index.ts,
+ * mediaResolver.ts): a handle is never trusted without being re-validated
+ * against the evidence root on every request.
+ */
+export declare function getObservationRelationships(root: string, handle: string): Promise<ObservationRelationshipsResult>;

package/dist/viewerServer/evidence/observationView.js

@@ -0,0 +1,46 @@
+import { join } from 'node:path';
+import { classifyManifest } from './classify.js';
+import { decodeArtifactHandle } from './handles.js';
+import { resolveContainedDir } from './pathSafety.js';
+import { deriveLayoutRelationships } from '../../domain/relationships.js';
+import { stat } from 'node:fs/promises';
+/**
+ * Batch 3's one additive server-side computation: invokes the existing
+ * canonical, pure `deriveLayoutRelationships` (src/domain/relationships.ts)
+ * against one already-validated, already-classified `ObservationArtifact` -
+ * never a second relationship engine, never computed in React. Mirrors the
+ * same handle-decode -> contained-dir-resolve -> re-classify defense-in-depth
+ * discipline as `loadArtifactByHandle`/`resolveMedia` (evidence/index.ts,
+ * mediaResolver.ts): a handle is never trusted without being re-validated
+ * against the evidence root on every request.
+ */
+export async function getObservationRelationships(root, handle) {
+    const decoded = decodeArtifactHandle(handle);
+    if (!decoded.ok)
+        return { ok: false, reason: 'unknown-handle' };
+    if (decoded.family !== 'observation')
+        return { ok: false, reason: 'not-an-observation' };
+    const dir = resolveContainedDir(root, decoded.relativeDir);
+    if (dir === undefined)
+        return { ok: false, reason: 'unknown-handle' };
+    try {
+        const dirInfo = await stat(dir);
+        if (!dirInfo.isDirectory())
+            return { ok: false, reason: 'unknown-handle' };
+    }
+    catch {
+        return { ok: false, reason: 'unknown-handle' };
+    }
+    const classified = await classifyManifest(join(dir, 'manifest.json'));
+    if (classified.supportState !== 'supported') {
+        return { ok: false, reason: 'not-currently-loadable' };
+    }
+    if (classified.family !== 'observation') {
+        return { ok: false, reason: 'not-an-observation' };
+    }
+    const derived = deriveLayoutRelationships(classified.artifact);
+    if (!derived.ok)
+        return { ok: false, reason: 'derivation-failed', detail: derived.reason };
+    return { ok: true, graph: derived.graph };
+}
+//# sourceMappingURL=observationView.js.map

package/dist/viewerServer/evidence/observationView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observationView.js","sourceRoot":"","sources":["../../../src/viewerServer/evidence/observationView.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAE1E,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AASxC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,IAAY,EAAE,MAAc;IAC5E,MAAM,OAAO,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAChE,IAAI,OAAO,CAAC,MAAM,KAAK,aAAa;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAEzF,MAAM,GAAG,GAAG,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3D,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAEtE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACjD,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC;IACtE,IAAI,UAAU,CAAC,YAAY,KAAK,WAAW,EAAE,CAAC;QAC5C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IACrD,CAAC;IAED,MAAM,OAAO,GAAG,yBAAyB,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC/D,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IAC3F,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;AAC5C,CAAC"}

package/dist/viewerServer/evidence/pathSafety.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolves a root-relative directory string (from a decoded viewer handle,
+ * never trusted on its own) against the evidence root, and verifies the
+ * result is actually contained within that root. Returns `undefined` on any
+ * traversal/escape attempt (`..` segments, an absolute-looking segment that
+ * resolves outside root, etc.) - callers must treat that as "unknown
+ * handle", never attempt a fallback resolution.
+ */
+export declare function resolveContainedDir(root: string, relativeDir: string): string | undefined;
+/** Same containment check for a bare filename resolved against an already-contained artifact directory (e.g. a screenshot/image sibling file). Rejects any filename containing a path separator outright - every current media reference is a bare filename by contract (see externalReference.ts's `path` field validation). */
+export declare function resolveContainedFile(containedDir: string, bareFilename: string): string | undefined;

package/dist/viewerServer/evidence/pathSafety.js

@@ -0,0 +1,31 @@
+import { resolve, sep } from 'node:path';
+/**
+ * Resolves a root-relative directory string (from a decoded viewer handle,
+ * never trusted on its own) against the evidence root, and verifies the
+ * result is actually contained within that root. Returns `undefined` on any
+ * traversal/escape attempt (`..` segments, an absolute-looking segment that
+ * resolves outside root, etc.) - callers must treat that as "unknown
+ * handle", never attempt a fallback resolution.
+ */
+export function resolveContainedDir(root, relativeDir) {
+    if (relativeDir.includes('\0'))
+        return undefined;
+    // `root` (e.g. a CLI --root argument) may use forward slashes even on win32; resolve it the same way `candidate`
+    // is resolved before comparing, or a purely textual prefix mismatch (backslash-normalized candidate vs. an
+    // un-normalized root string) would reject every legitimate path.
+    const resolvedRoot = resolve(root);
+    const candidate = resolve(resolvedRoot, relativeDir);
+    const rootWithSep = resolvedRoot.endsWith(sep) ? resolvedRoot : resolvedRoot + sep;
+    if (candidate !== resolvedRoot && !candidate.startsWith(rootWithSep))
+        return undefined;
+    return candidate;
+}
+/** Same containment check for a bare filename resolved against an already-contained artifact directory (e.g. a screenshot/image sibling file). Rejects any filename containing a path separator outright - every current media reference is a bare filename by contract (see externalReference.ts's `path` field validation). */
+export function resolveContainedFile(containedDir, bareFilename) {
+    if (bareFilename.length === 0 || bareFilename.includes('/') || bareFilename.includes('\\') || bareFilename.includes('\0'))
+        return undefined;
+    if (bareFilename === '.' || bareFilename === '..')
+        return undefined;
+    return resolve(containedDir, bareFilename);
+}
+//# sourceMappingURL=pathSafety.js.map

package/dist/viewerServer/evidence/pathSafety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathSafety.js","sourceRoot":"","sources":["../../../src/viewerServer/evidence/pathSafety.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,WAAmB;IACnE,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACjD,iHAAiH;IACjH,2GAA2G;IAC3G,iEAAiE;IACjE,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IACrD,MAAM,WAAW,GAAG,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,GAAG,GAAG,CAAC;IACnF,IAAI,SAAS,KAAK,YAAY,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,SAAS,CAAC;IACvF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,iUAAiU;AACjU,MAAM,UAAU,oBAAoB,CAAC,YAAoB,EAAE,YAAoB;IAC7E,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5I,IAAI,YAAY,KAAK,GAAG,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACpE,OAAO,OAAO,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;AAC7C,CAAC"}

package/dist/viewerServer/evidence/projection.d.ts

@@ -0,0 +1,55 @@
+import type { CompletionState } from '../../domain/completion.js';
+import type { OverallVerdict } from '../../domain/frontendContracts.js';
+import type { ComparabilityState } from '../../domain/comparison.js';
+import type { ArtifactFamily, ClassifiedRecord } from './classify.js';
+/** One bounded, UI-facing summary of one recognized media role owned/referenced by an artifact. Never the media bytes themselves. */
+export interface MediaSummary {
+    role: 'screenshot' | 'image' | 'source-image';
+    available: boolean;
+    /** Present only when unavailable, for an honest (never fabricated) reason. */
+    reason?: string;
+}
+/**
+ * Bounded, UI-facing metadata for one recognized-or-problematic evidence
+ * candidate. Deliberately excludes full artifact payloads and media bytes -
+ * see docs/plans/v0.8-implementation-plan.md Batch 2 "metadata-first".
+ */
+export interface EvidenceMetadataRecord {
+    handle: string;
+    family: ArtifactFamily | 'unrecognized';
+    supportState: ClassifiedRecord['supportState'];
+    relativeDir: string;
+    alias?: string;
+    logicalId?: string;
+    schemaVersion?: string;
+    foundSchemaVersion?: string;
+    producerVersion?: string;
+    completion?: CompletionState;
+    lifecycleState?: 'imported' | 'approved';
+    contractClass?: 'baseline' | 'change';
+    overallVerdict?: OverallVerdict;
+    comparability?: ComparabilityState;
+    media?: MediaSummary[];
+    relatedIds?: Record<string, string>;
+    message?: string;
+}
+/** Ephemeral, non-persisted wrapper around one already-validated domain artifact, for the on-demand full-artifact API. Not a new evidence schema - selects/wraps existing canonical fields only. */
+export interface EvidenceArtifactDetail {
+    handle: string;
+    family: ArtifactFamily;
+    artifact: Extract<ClassifiedRecord, {
+        supportState: 'supported';
+    }>['artifact'];
+}
+/**
+ * Builds the bounded metadata record for one classified candidate, including
+ * an on-demand media-availability summary (cheap `stat` calls only - never
+ * reads media bytes here). `absoluteDir` is the already-contained,
+ * already-resolved directory (see discovery.ts) - never a browser-supplied
+ * value.
+ */
+export declare function buildMetadataRecord(classified: ClassifiedRecord, relativeDir: string, absoluteDir: string): Promise<EvidenceMetadataRecord>;
+/** Ephemeral, non-persisted full-artifact projection for the on-demand API. */
+export declare function buildArtifactDetail(family: ArtifactFamily, handle: string, artifact: Extract<ClassifiedRecord, {
+    supportState: 'supported';
+}>['artifact']): EvidenceArtifactDetail;

package/dist/viewerServer/evidence/projection.js

@@ -0,0 +1,152 @@
+import { stat } from 'node:fs/promises';
+import { encodeArtifactHandle } from './handles.js';
+import { resolveContainedFile } from './pathSafety.js';
+async function fileAvailable(path) {
+    try {
+        const info = await stat(path);
+        return info.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Builds the bounded metadata record for one classified candidate, including
+ * an on-demand media-availability summary (cheap `stat` calls only - never
+ * reads media bytes here). `absoluteDir` is the already-contained,
+ * already-resolved directory (see discovery.ts) - never a browser-supplied
+ * value.
+ */
+export async function buildMetadataRecord(classified, relativeDir, absoluteDir) {
+    if (classified.supportState === 'unrecognized-kind') {
+        return {
+            handle: encodeArtifactHandle('observation', relativeDir), // placeholder family slug irrelevant for an unrecognized record; handle is never dereferenced for this state
+            family: 'unrecognized',
+            supportState: 'unrecognized-kind',
+            relativeDir,
+            message: classified.foundArtifactKind === undefined ? 'manifest.json does not declare a recognized artifactKind' : `unrecognized artifactKind "${classified.foundArtifactKind}"`,
+        };
+    }
+    if (classified.supportState === 'malformed-json') {
+        return {
+            handle: encodeArtifactHandle('observation', relativeDir),
+            family: 'unrecognized',
+            supportState: 'malformed-json',
+            relativeDir,
+            message: `manifest.json is not valid JSON: ${classified.reason}`,
+        };
+    }
+    if (classified.supportState === 'unreadable') {
+        return {
+            handle: encodeArtifactHandle('observation', relativeDir),
+            family: 'unrecognized',
+            supportState: 'unreadable',
+            relativeDir,
+            message: classified.reason,
+        };
+    }
+    if (classified.supportState === 'unsupported-version') {
+        return {
+            handle: encodeArtifactHandle(classified.family, relativeDir),
+            family: classified.family,
+            supportState: 'unsupported-version',
+            relativeDir,
+            foundSchemaVersion: classified.foundSchemaVersion,
+            schemaVersion: classified.supportedSchemaVersion,
+            message: `recognized "${classified.family}" evidence, but schema version "${classified.foundSchemaVersion}" is not the currently supported "${classified.supportedSchemaVersion}"`,
+        };
+    }
+    if (classified.supportState === 'invalid-structure') {
+        return {
+            handle: encodeArtifactHandle(classified.family ?? 'observation', relativeDir),
+            family: classified.family ?? 'unrecognized',
+            supportState: 'invalid-structure',
+            relativeDir,
+            message: classified.reason,
+        };
+    }
+    // supported
+    const { family, artifact } = classified;
+    const handle = encodeArtifactHandle(family, relativeDir);
+    const base = { handle, family, supportState: 'supported', relativeDir };
+    switch (family) {
+        case 'observation': {
+            const screenshotPath = artifact.screenshot.state === 'available' || artifact.screenshot.state === 'partial' ? artifact.screenshot.value.path : undefined;
+            const resolved = screenshotPath === undefined ? undefined : resolveContainedFile(absoluteDir, screenshotPath);
+            const available = resolved !== undefined && (await fileAvailable(resolved));
+            return {
+                ...base,
+                logicalId: artifact.observationId,
+                schemaVersion: artifact.schemaVersion,
+                producerVersion: artifact.producer.version,
+                completion: artifact.completion,
+                media: [{ role: 'screenshot', available, ...(available ? {} : { reason: screenshotPath === undefined ? 'no screenshot recorded on this observation' : 'screenshot file not found on disk' }) }],
+            };
+        }
+        case 'comparison':
+            return {
+                ...base,
+                logicalId: artifact.comparisonId,
+                schemaVersion: artifact.schemaVersion,
+                producerVersion: artifact.producer.version,
+                comparability: artifact.comparability.state,
+                relatedIds: { beforeObservationId: artifact.before.observationId, afterObservationId: artifact.after.observationId },
+            };
+        case 'baseline-contract':
+            return {
+                ...base,
+                logicalId: artifact.baselineId,
+                schemaVersion: artifact.schemaVersion,
+                contractClass: 'baseline',
+                relatedIds: { sourceObservationId: artifact.sourceObservation.observationId },
+            };
+        case 'change-contract':
+            return { ...base, logicalId: artifact.contractId, schemaVersion: artifact.schemaVersion, contractClass: 'change' };
+        case 'contract-evaluation':
+            return {
+                ...base,
+                logicalId: artifact.evaluationId,
+                schemaVersion: artifact.schemaVersion,
+                producerVersion: artifact.producer.version,
+                overallVerdict: artifact.overallVerdict,
+                relatedIds: {
+                    beforeObservationId: artifact.before.observationId,
+                    afterObservationId: artifact.after.observationId,
+                    comparisonId: artifact.comparisonId,
+                    baselineId: artifact.contracts.baselineId,
+                    contractId: artifact.contracts.contractId,
+                },
+            };
+        case 'external-reference-imported':
+        case 'external-reference-approved': {
+            const lifecycleState = artifact.lifecycle.state;
+            let media;
+            if (lifecycleState === 'imported' && 'image' in artifact) {
+                const resolved = resolveContainedFile(absoluteDir, artifact.image.path);
+                const available = resolved !== undefined && (await fileAvailable(resolved));
+                media = [{ role: 'image', available, ...(available ? {} : { reason: 'image file not found on disk' }) }];
+            }
+            else {
+                // 'approved': availability of the source-owned image cannot be determined without cross-referencing the imported artifact
+                // by sourceReference.referenceId within the current index (see mediaResolver.ts) - reported honestly as unknown here,
+                // never fabricated as available.
+                media = [{ role: 'source-image', available: false, reason: 'availability determined on demand via /api/media (depends on the owning imported reference being present in this evidence root)' }];
+            }
+            return {
+                ...base,
+                logicalId: artifact.referenceId,
+                schemaVersion: artifact.schemaVersion,
+                producerVersion: artifact.producer.version,
+                completion: artifact.completion,
+                lifecycleState,
+                media,
+                ...(lifecycleState === 'approved' && 'sourceReference' in artifact ? { relatedIds: { sourceReferenceId: artifact.sourceReference.referenceId } } : {}),
+            };
+        }
+    }
+}
+/** Ephemeral, non-persisted full-artifact projection for the on-demand API. */
+export function buildArtifactDetail(family, handle, artifact) {
+    return { handle, family, artifact };
+}
+//# sourceMappingURL=projection.js.map

package/dist/viewerServer/evidence/projection.js.map

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

package/dist/viewerServer/evidence/referenceView.d.ts

@@ -0,0 +1,133 @@
+import type { ReferenceRegionRelationshipGraph } from '../../domain/externalReferenceRegionRelationships.js';
+import type { ReferenceRequirementAdequacy } from '../../domain/externalReferenceRequirements.js';
+import type { ReferenceCandidateCompatibilityResult } from '../../domain/externalReferenceCompatibility.js';
+import type { ReferenceRuntimeBindingEvaluation } from '../../domain/externalReferenceRuntimeBinding.js';
+import type { DeriveCoordinateScaleResult, ReferenceCandidateFidelityEvaluation } from '../../domain/externalReferenceFidelity.js';
+export type ReferenceViewResult = {
+    ok: true;
+    regionRelationships: ReferenceRegionRelationshipGraph | undefined;
+    requirementAdequacy: ReferenceRequirementAdequacy | undefined;
+} | {
+    ok: false;
+    reason: 'unknown-handle';
+} | {
+    ok: false;
+    reason: 'not-a-reference';
+} | {
+    ok: false;
+    reason: 'not-currently-loadable';
+};
+/**
+ * Batch 5's one additive server-side computation for a selected external
+ * reference on its own (no candidate yet): derives the reference's own
+ * region-relationship graph (`deriveReferenceRegionRelationships`) and
+ * requirement adequacy (`deriveReferenceRequirementAdequacy`) - both pure
+ * functions over the artifact's own already-persisted `regions`/
+ * `requirements`, never persisted themselves, never a second derivation
+ * engine. Mirrors observationView.ts's server-side-derivation pattern
+ * (Batch 3) rather than re-deriving in the browser.
+ */
+export declare function getReferenceView(root: string, handle: string): Promise<ReferenceViewResult>;
+export type ReferenceCandidateViewResult = {
+    ok: true;
+    compatibility: ReferenceCandidateCompatibilityResult;
+    evaluationHandles: string[];
+    coordinateMapping: DeriveCoordinateScaleResult;
+} | {
+    ok: false;
+    reason: 'unknown-reference-handle';
+} | {
+    ok: false;
+    reason: 'unknown-candidate-handle';
+} | {
+    ok: false;
+    reason: 'not-a-reference';
+} | {
+    ok: false;
+    reason: 'not-an-observation';
+} | {
+    ok: false;
+    reason: 'not-currently-loadable';
+};
+/**
+ * Batch 5's reference/candidate computation: evaluates page/state-level
+ * compatibility through the existing canonical
+ * `evaluateReferenceCandidateCompatibility` (never a second, viewer-owned
+ * compatibility model), and separately lists every existing
+ * `FrontendContractEvaluationArtifact` whose own persisted `after` reference
+ * exactly identifies this candidate (frozen plan/task §29) - for the caller
+ * to offer as an explicit, never-auto-selected optional context. Batch 6
+ * additionally exposes `coordinateMapping` - the exact result of the
+ * existing canonical `deriveCoordinateScale(reference)` (exported from
+ * `externalReferenceFidelity.ts`, never a second scale/aspect-ratio
+ * implementation) - purely a function of the reference (independent of the
+ * candidate), used only to gate view-lock eligibility client-side. Neither
+ * `evaluateReferenceRuntimeBindings` nor `evaluateReferenceCandidateFidelity`
+ * is called anywhere in this function.
+ */
+export declare function getReferenceCandidateView(root: string, referenceHandle: string, candidateHandle: string): Promise<ReferenceCandidateViewResult>;
+export type ReferenceBindingsViewResult = {
+    ok: true;
+    evaluation: ReferenceRuntimeBindingEvaluation;
+} | {
+    ok: false;
+    reason: 'unknown-reference-handle';
+} | {
+    ok: false;
+    reason: 'unknown-candidate-handle';
+} | {
+    ok: false;
+    reason: 'not-a-reference';
+} | {
+    ok: false;
+    reason: 'not-an-observation';
+} | {
+    ok: false;
+    reason: 'not-currently-loadable';
+} | {
+    ok: false;
+    reason: 'invalid-bindings';
+    detail: string;
+};
+/**
+ * Batch 6: validates the session's explicit binding declarations against
+ * THIS specific reference (`isValidReferenceRuntimeBindingDeclarations` -
+ * region existence depends on the selected reference, so this can only
+ * happen here, never at CLI startup) and, if valid, calls the existing
+ * canonical `evaluateReferenceRuntimeBindings` exactly once - never a second
+ * binding engine, never a client-side re-verification via geometry/name.
+ */
+export declare function getReferenceBindings(root: string, referenceHandle: string, candidateHandle: string, declarations: readonly unknown[]): Promise<ReferenceBindingsViewResult>;
+export type ReferenceFidelityViewResult = {
+    ok: true;
+    evaluation: ReferenceCandidateFidelityEvaluation;
+} | {
+    ok: false;
+    reason: 'unknown-reference-handle';
+} | {
+    ok: false;
+    reason: 'unknown-candidate-handle';
+} | {
+    ok: false;
+    reason: 'not-a-reference';
+} | {
+    ok: false;
+    reason: 'not-an-observation';
+} | {
+    ok: false;
+    reason: 'not-currently-loadable';
+} | {
+    ok: false;
+    reason: 'invalid-bindings';
+    detail: string;
+};
+/**
+ * Batch 6's one on-demand server-side computation for the explicit
+ * "Evaluate Fidelity" action: calls the existing canonical
+ * `evaluateReferenceCandidateFidelity` exactly once, using the exact same
+ * session binding declarations `getReferenceBindings` uses (so the two
+ * always structurally agree for the same inputs, being the same pure
+ * function applied to the same arguments - never two divergent binding
+ * results). Never persists the result; ephemeral per request.
+ */
+export declare function getReferenceFidelity(root: string, referenceHandle: string, candidateHandle: string, declarations: readonly unknown[]): Promise<ReferenceFidelityViewResult>;