@dailephd/my-frontend-observer 0.8.1

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

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

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

@@ -0,0 +1,32 @@
+import type { LinkStatus } from './linkedEvidence.js';
+export type EvaluationViewResult = {
+    ok: true;
+    comparison: LinkStatus;
+    baseline: LinkStatus;
+    change: LinkStatus;
+    before: LinkStatus;
+    after: LinkStatus;
+} | {
+    ok: false;
+    reason: 'unknown-handle';
+} | {
+    ok: false;
+    reason: 'not-an-evaluation';
+} | {
+    ok: false;
+    reason: 'not-currently-loadable';
+};
+/**
+ * Batch 4's linked-evidence resolver for `FrontendContractEvaluationArtifact`:
+ * resolves its `contracts.baselineId`, `contracts.contractId`,
+ * `comparisonId`+`comparisonRequestId`, and `before`/`after` references
+ * against the current evidence root, all by exact identity
+ * (`linkedEvidence.ts`) - never by shape/proximity. Never calls
+ * `evaluateFrontendContract`: `overallVerdict`, `clauseResults`,
+ * `activeBaselineClauseIds`, `supersededBaselineClauseIds`, and
+ * `unexpectedChanges` are read unchanged from the persisted artifact via the
+ * existing Batch 2 `GET /api/artifacts/<handle>` - this endpoint only
+ * answers "where are its linked contracts/comparison/observations, if
+ * anywhere in this root".
+ */
+export declare function getEvaluationView(root: string, handle: string): Promise<EvaluationViewResult>;

package/dist/viewerServer/evidence/evaluationView.js

@@ -0,0 +1,50 @@
+import { join } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { classifyManifest } from './classify.js';
+import { decodeArtifactHandle } from './handles.js';
+import { resolveContainedDir } from './pathSafety.js';
+import { resolveObservationByReference, resolveComparisonByIdentity, resolveBaselineContractById, resolveChangeContractById } from './linkedEvidence.js';
+/**
+ * Batch 4's linked-evidence resolver for `FrontendContractEvaluationArtifact`:
+ * resolves its `contracts.baselineId`, `contracts.contractId`,
+ * `comparisonId`+`comparisonRequestId`, and `before`/`after` references
+ * against the current evidence root, all by exact identity
+ * (`linkedEvidence.ts`) - never by shape/proximity. Never calls
+ * `evaluateFrontendContract`: `overallVerdict`, `clauseResults`,
+ * `activeBaselineClauseIds`, `supersededBaselineClauseIds`, and
+ * `unexpectedChanges` are read unchanged from the persisted artifact via the
+ * existing Batch 2 `GET /api/artifacts/<handle>` - this endpoint only
+ * answers "where are its linked contracts/comparison/observations, if
+ * anywhere in this root".
+ */
+export async function getEvaluationView(root, handle) {
+    const decoded = decodeArtifactHandle(handle);
+    if (!decoded.ok)
+        return { ok: false, reason: 'unknown-handle' };
+    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 !== 'contract-evaluation')
+        return { ok: false, reason: 'not-an-evaluation' };
+    const { artifact } = classified;
+    const [comparison, baseline, change, before, after] = await Promise.all([
+        resolveComparisonByIdentity(root, artifact.comparisonId, artifact.comparisonRequestId),
+        resolveBaselineContractById(root, artifact.contracts.baselineId),
+        resolveChangeContractById(root, artifact.contracts.contractId),
+        resolveObservationByReference(root, artifact.before),
+        resolveObservationByReference(root, artifact.after),
+    ]);
+    return { ok: true, comparison, baseline, change, before, after };
+}
+//# sourceMappingURL=evaluationView.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evaluationView.js","sourceRoot":"","sources":["../../../src/viewerServer/evidence/evaluationView.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,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,6BAA6B,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AASzJ;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY,EAAE,MAAc;IAClE,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;IAEhE,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;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACpG,IAAI,UAAU,CAAC,MAAM,KAAK,qBAAqB;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAEnG,MAAM,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAC;IAChC,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACtE,2BAA2B,CAAC,IAAI,EAAE,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,mBAAmB,CAAC;QACtF,2BAA2B,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC;QAChE,yBAAyB,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC;QAC9D,6BAA6B,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC;QACpD,6BAA6B,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC;KACpD,CAAC,CAAC;IAEH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACnE,CAAC"}

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

@@ -0,0 +1,21 @@
+import type { ArtifactFamily } from './classify.js';
+/**
+ * A viewer handle is server-issued, opaque-to-the-browser material: a
+ * family-prefixed, percent-encoded root-relative directory path. It is
+ * "server-issued" in the sense that it is exactly what discovery/
+ * classification already produced - a client can never construct a handle
+ * that names a path discovery did not itself walk to and classify.
+ * Every route that accepts a handle re-resolves and re-validates it against
+ * the evidence root before touching the filesystem (see media.ts/index.ts) -
+ * this module only encodes/decodes the opaque string, it never grants
+ * filesystem access by itself.
+ */
+export declare function encodeArtifactHandle(family: ArtifactFamily, relativeDir: string): string;
+export type DecodedArtifactHandle = {
+    ok: true;
+    family: ArtifactFamily;
+    relativeDir: string;
+} | {
+    ok: false;
+};
+export declare function decodeArtifactHandle(handle: string): DecodedArtifactHandle;

package/dist/viewerServer/evidence/handles.js

@@ -0,0 +1,43 @@
+const FAMILY_SLUGS = {
+    observation: 'observation',
+    comparison: 'comparison',
+    'baseline-contract': 'baseline-contract',
+    'change-contract': 'change-contract',
+    'contract-evaluation': 'contract-evaluation',
+    'external-reference-imported': 'external-reference-imported',
+    'external-reference-approved': 'external-reference-approved',
+};
+const SLUG_TO_FAMILY = Object.fromEntries(Object.entries(FAMILY_SLUGS).map(([family, slug]) => [slug, family]));
+/**
+ * A viewer handle is server-issued, opaque-to-the-browser material: a
+ * family-prefixed, percent-encoded root-relative directory path. It is
+ * "server-issued" in the sense that it is exactly what discovery/
+ * classification already produced - a client can never construct a handle
+ * that names a path discovery did not itself walk to and classify.
+ * Every route that accepts a handle re-resolves and re-validates it against
+ * the evidence root before touching the filesystem (see media.ts/index.ts) -
+ * this module only encodes/decodes the opaque string, it never grants
+ * filesystem access by itself.
+ */
+export function encodeArtifactHandle(family, relativeDir) {
+    return `${FAMILY_SLUGS[family]}:${encodeURIComponent(relativeDir)}`;
+}
+export function decodeArtifactHandle(handle) {
+    const separatorIndex = handle.indexOf(':');
+    if (separatorIndex <= 0)
+        return { ok: false };
+    const slug = handle.slice(0, separatorIndex);
+    const encodedDir = handle.slice(separatorIndex + 1);
+    const family = SLUG_TO_FAMILY[slug];
+    if (family === undefined || encodedDir.length === 0)
+        return { ok: false };
+    let relativeDir;
+    try {
+        relativeDir = decodeURIComponent(encodedDir);
+    }
+    catch {
+        return { ok: false };
+    }
+    return { ok: true, family, relativeDir };
+}
+//# sourceMappingURL=handles.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handles.js","sourceRoot":"","sources":["../../../src/viewerServer/evidence/handles.ts"],"names":[],"mappings":"AAEA,MAAM,YAAY,GAAmC;IACnD,WAAW,EAAE,aAAa;IAC1B,UAAU,EAAE,YAAY;IACxB,mBAAmB,EAAE,mBAAmB;IACxC,iBAAiB,EAAE,iBAAiB;IACpC,qBAAqB,EAAE,qBAAqB;IAC5C,6BAA6B,EAAE,6BAA6B;IAC5D,6BAA6B,EAAE,6BAA6B;CAC7D,CAAC;AAEF,MAAM,cAAc,GAAmC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAwB,CAAC,CAAC,CAG/J,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAsB,EAAE,WAAmB;IAC9E,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC;AACtE,CAAC;AAID,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,cAAc,IAAI,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,MAAM,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IAC1E,IAAI,WAAmB,CAAC;IACxB,IAAI,CAAC;QACH,WAAW,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACvB,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AAC3C,CAAC"}

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

@@ -0,0 +1,41 @@
+import type { EvidenceArtifactDetail, EvidenceMetadataRecord } from './projection.js';
+export interface EvidenceIndexResult {
+    records: EvidenceMetadataRecord[];
+    truncated: boolean;
+}
+/**
+ * The one metadata-first entry point: bounded discovery + narrow
+ * classification + canonical-reader dispatch (for anything that looks
+ * recognized) + ephemeral metadata projection. Rebuilt on every call rather
+ * than cached (frozen plan §30: no persistent viewer cache/database/watcher),
+ * so it always reflects the evidence root's current on-disk state.
+ */
+export declare function buildEvidenceIndexMetadata(root: string, observationAliasesByRelativeDir?: Readonly<Record<string, string>>): Promise<EvidenceIndexResult>;
+export type LoadArtifactResult = {
+    ok: true;
+    detail: EvidenceArtifactDetail;
+} | {
+    ok: false;
+    reason: 'unknown-handle';
+} | {
+    ok: false;
+    reason: 'not-supported';
+    metadata: EvidenceMetadataRecord;
+};
+/**
+ * On-demand full-artifact loading (frozen plan §16): decodes and
+ * re-validates the handle against the evidence root (never trusts it
+ * blindly), then re-classifies *that one candidate* through the same
+ * canonical-reader dispatch the index uses - it never returns a cached
+ * result and never coerces an unsupported/invalid candidate into a
+ * fabricated domain object.
+ */
+export declare function loadArtifactByHandle(root: string, handle: string): Promise<LoadArtifactResult>;
+/**
+ * Bounded search for the 'imported' external-reference artifact whose
+ * `referenceId` matches `referenceId`, used only to resolve an 'approved'
+ * artifact's source-owned image (see mediaResolver.ts). Never assumes a
+ * fixed relative location - an approved artifact's `sourceReference` carries
+ * only a logical `referenceId`, not a filesystem path (frozen plan §18).
+ */
+export declare function findImportedReferenceDir(root: string, referenceId: string): Promise<string | undefined>;

package/dist/viewerServer/evidence/index.js

@@ -0,0 +1,82 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { discoverManifests } from './discovery.js';
+import { classifyManifest } from './classify.js';
+import { buildMetadataRecord, buildArtifactDetail } from './projection.js';
+import { decodeArtifactHandle } from './handles.js';
+import { resolveContainedDir } from './pathSafety.js';
+import { MAX_INDEX_RECORDS } from './limits.js';
+/**
+ * The one metadata-first entry point: bounded discovery + narrow
+ * classification + canonical-reader dispatch (for anything that looks
+ * recognized) + ephemeral metadata projection. Rebuilt on every call rather
+ * than cached (frozen plan §30: no persistent viewer cache/database/watcher),
+ * so it always reflects the evidence root's current on-disk state.
+ */
+export async function buildEvidenceIndexMetadata(root, observationAliasesByRelativeDir = {}) {
+    const discovery = await discoverManifests(root);
+    const limited = discovery.manifests.slice(0, MAX_INDEX_RECORDS);
+    const truncated = discovery.truncated || discovery.manifests.length > MAX_INDEX_RECORDS;
+    const records = [];
+    for (const manifest of limited) {
+        const classified = await classifyManifest(manifest.absolutePath);
+        const record = await buildMetadataRecord(classified, manifest.relativeDir, manifest.absoluteDir);
+        const alias = record.family === 'observation' ? observationAliasesByRelativeDir[manifest.relativeDir] : undefined;
+        records.push(alias === undefined ? record : { ...record, alias });
+    }
+    return { records, truncated };
+}
+/**
+ * On-demand full-artifact loading (frozen plan §16): decodes and
+ * re-validates the handle against the evidence root (never trusts it
+ * blindly), then re-classifies *that one candidate* through the same
+ * canonical-reader dispatch the index uses - it never returns a cached
+ * result and never coerces an unsupported/invalid candidate into a
+ * fabricated domain object.
+ */
+export async function loadArtifactByHandle(root, handle) {
+    const decoded = decodeArtifactHandle(handle);
+    if (!decoded.ok)
+        return { ok: false, reason: 'unknown-handle' };
+    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 {
+        // The handle names a path discovery never actually found on disk (or that has since disappeared) - unknown, not "broken".
+        return { ok: false, reason: 'unknown-handle' };
+    }
+    const classified = await classifyManifest(join(dir, 'manifest.json'));
+    if (classified.supportState !== 'supported') {
+        const metadata = await buildMetadataRecord(classified, decoded.relativeDir, dir);
+        return { ok: false, reason: 'not-supported', metadata };
+    }
+    if (classified.family !== decoded.family) {
+        // The handle named a family that no longer matches on-disk reality (e.g. deleted and replaced between requests) - fail closed as unknown rather than serving a mismatched artifact under a stale handle.
+        return { ok: false, reason: 'unknown-handle' };
+    }
+    return { ok: true, detail: buildArtifactDetail(classified.family, handle, classified.artifact) };
+}
+/**
+ * Bounded search for the 'imported' external-reference artifact whose
+ * `referenceId` matches `referenceId`, used only to resolve an 'approved'
+ * artifact's source-owned image (see mediaResolver.ts). Never assumes a
+ * fixed relative location - an approved artifact's `sourceReference` carries
+ * only a logical `referenceId`, not a filesystem path (frozen plan §18).
+ */
+export async function findImportedReferenceDir(root, referenceId) {
+    const discovery = await discoverManifests(root);
+    for (const manifest of discovery.manifests.slice(0, MAX_INDEX_RECORDS)) {
+        const classified = await classifyManifest(manifest.absolutePath);
+        if (classified.supportState === 'supported' && classified.family === 'external-reference-imported' && 'referenceId' in classified.artifact) {
+            if (classified.artifact.referenceId === referenceId)
+                return manifest.absoluteDir;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=index.js.map

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

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

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

@@ -0,0 +1,27 @@
+/**
+ * v0.8 Batch 2: conservative, deterministic bounds for evidence-root
+ * discovery. Chosen after inspecting every current persisted artifact family
+ * (src/artifacts/*Writer.ts): every family writes exactly one
+ * `<outputLocation>/<id>/manifest.json` (plus, for observation and imported
+ * external-reference artifacts, one sibling media file in that same
+ * directory) - a shallow, bounded shape that does not require deep
+ * recursion. These bounds are generous relative to that real shape while
+ * still refusing to become an unbounded filesystem crawl.
+ */
+/** Maximum directory levels traversed below the supplied evidence root (root itself is depth 0). Typical shapes (`<root>/observations/<id>/manifest.json`) need depth 2; this leaves slack for an intentionally nested `--output` without allowing unbounded recursion. */
+export declare const MAX_DISCOVERY_DEPTH = 6;
+/** Maximum number of directories visited during one discovery walk. */
+export declare const MAX_DIRECTORIES_VISITED = 2000;
+/** Maximum number of candidate `manifest.json` files inspected (classified) during one discovery walk. */
+export declare const MAX_MANIFEST_CANDIDATES = 1000;
+/** Maximum number of metadata records returned in one index response. */
+export declare const MAX_INDEX_RECORDS = 500;
+/**
+ * Maximum bytes read from a candidate `manifest.json` before classification.
+ * Every real persisted manifest is small (identity/geometry/config JSON only
+ * - screenshots and reference images are always separate sibling files), so
+ * 2,000,000 bytes is generous headroom for a legitimately large observation
+ * (many targets/relationships) while refusing to read an arbitrarily large
+ * file into memory just because it happens to be named `manifest.json`.
+ */
+export declare const MAX_MANIFEST_CANDIDATE_BYTES = 2000000;

package/dist/viewerServer/evidence/limits.js

@@ -0,0 +1,28 @@
+/**
+ * v0.8 Batch 2: conservative, deterministic bounds for evidence-root
+ * discovery. Chosen after inspecting every current persisted artifact family
+ * (src/artifacts/*Writer.ts): every family writes exactly one
+ * `<outputLocation>/<id>/manifest.json` (plus, for observation and imported
+ * external-reference artifacts, one sibling media file in that same
+ * directory) - a shallow, bounded shape that does not require deep
+ * recursion. These bounds are generous relative to that real shape while
+ * still refusing to become an unbounded filesystem crawl.
+ */
+/** Maximum directory levels traversed below the supplied evidence root (root itself is depth 0). Typical shapes (`<root>/observations/<id>/manifest.json`) need depth 2; this leaves slack for an intentionally nested `--output` without allowing unbounded recursion. */
+export const MAX_DISCOVERY_DEPTH = 6;
+/** Maximum number of directories visited during one discovery walk. */
+export const MAX_DIRECTORIES_VISITED = 2000;
+/** Maximum number of candidate `manifest.json` files inspected (classified) during one discovery walk. */
+export const MAX_MANIFEST_CANDIDATES = 1000;
+/** Maximum number of metadata records returned in one index response. */
+export const MAX_INDEX_RECORDS = 500;
+/**
+ * Maximum bytes read from a candidate `manifest.json` before classification.
+ * Every real persisted manifest is small (identity/geometry/config JSON only
+ * - screenshots and reference images are always separate sibling files), so
+ * 2,000,000 bytes is generous headroom for a legitimately large observation
+ * (many targets/relationships) while refusing to read an arbitrarily large
+ * file into memory just because it happens to be named `manifest.json`.
+ */
+export const MAX_MANIFEST_CANDIDATE_BYTES = 2_000_000;
+//# sourceMappingURL=limits.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../../src/viewerServer/evidence/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2QAA2Q;AAC3Q,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAErC,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C,0GAA0G;AAC1G,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,SAAS,CAAC"}

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

@@ -0,0 +1,43 @@
+import type { ComparisonSourceObservationReference } from '../../domain/comparison.js';
+import type { FrontendContractObservationReference } from '../../domain/frontendContracts.js';
+export type LinkStatus = {
+    status: 'resolved';
+    handle: string;
+} | {
+    status: 'missing';
+} | {
+    status: 'ambiguous';
+    count: number;
+};
+type ObservationReferenceLike = ComparisonSourceObservationReference | FrontendContractObservationReference;
+/**
+ * Batch 4 exact-identity linked-evidence resolution: every lookup here walks
+ * the bounded evidence tree once (mirroring the exact pattern Batch 2's
+ * `evidence/index.ts#findImportedReferenceDir` already established for the
+ * approved-external-reference case) and matches by exact canonical identity
+ * only - never by folder name, screenshot filename, URL, target-set
+ * similarity, or geometry similarity (frozen plan §11). Zero matches ->
+ * `missing`; two or more exact matches -> `ambiguous` (never silently pick
+ * one). No caller of this module ever calls `compareObservations` or
+ * `evaluateFrontendContract` - it only locates and identity-checks already-
+ * persisted, already-validated artifacts.
+ */
+export declare function resolveObservationByReference(root: string, ref: ObservationReferenceLike): Promise<LinkStatus>;
+export declare function resolveComparisonByIdentity(root: string, comparisonId: string, comparisonRequestId: string): Promise<LinkStatus>;
+export declare function resolveBaselineContractById(root: string, baselineId: string): Promise<LinkStatus>;
+export declare function resolveChangeContractById(root: string, contractId: string): Promise<LinkStatus>;
+/**
+ * Batch 7 addition: resolves an observation by bare `observationId` alone
+ * (exact match, never a substring/pathname heuristic) - the only identity a
+ * `BoundedAgentContextArtifact.sources.observationIds` entry actually
+ * carries (unlike the compound `{observationId, requestId, producer,
+ * observationSchemaVersion}` reference `resolveObservationByReference`
+ * consumes for Batch 4/5 cross-artifact references). Same missing/ambiguous
+ * discipline as every other resolver in this module.
+ */
+export declare function resolveObservationById(root: string, observationId: string): Promise<LinkStatus>;
+/** Batch 7 addition: resolves a `FrontendContractEvaluationArtifact` by its own exact `evaluationId`+`evaluationRequestId` (a bounded-agent-context source reference, never resolved via the `after` observation the way Batch 5's candidate-context lookup works). */
+export declare function resolveEvaluationByIdentity(root: string, evaluationId: string, evaluationRequestId: string): Promise<LinkStatus>;
+/** Batch 7 addition: resolves an `ExternalReferenceArtifact` (imported or approved) by its own exact `referenceId`+`referenceRequestId` - a bounded-agent-context source reference. Matches either lifecycle family; never assumes which one. */
+export declare function resolveReferenceByIdentity(root: string, referenceId: string, referenceRequestId: string): Promise<LinkStatus>;
+export {};

package/dist/viewerServer/evidence/linkedEvidence.js

@@ -0,0 +1,151 @@
+import { discoverManifests } from './discovery.js';
+import { classifyManifest } from './classify.js';
+import { encodeArtifactHandle } from './handles.js';
+import { MAX_INDEX_RECORDS } from './limits.js';
+function referencesMatch(ref, candidateObservationId, candidateRequestId, candidateProducerVersion, candidateSchemaVersion) {
+    return ref.observationId === candidateObservationId && ref.requestId === candidateRequestId && ref.producer.version === candidateProducerVersion && ref.observationSchemaVersion === candidateSchemaVersion;
+}
+/**
+ * Batch 4 exact-identity linked-evidence resolution: every lookup here walks
+ * the bounded evidence tree once (mirroring the exact pattern Batch 2's
+ * `evidence/index.ts#findImportedReferenceDir` already established for the
+ * approved-external-reference case) and matches by exact canonical identity
+ * only - never by folder name, screenshot filename, URL, target-set
+ * similarity, or geometry similarity (frozen plan §11). Zero matches ->
+ * `missing`; two or more exact matches -> `ambiguous` (never silently pick
+ * one). No caller of this module ever calls `compareObservations` or
+ * `evaluateFrontendContract` - it only locates and identity-checks already-
+ * persisted, already-validated artifacts.
+ */
+export async function resolveObservationByReference(root, ref) {
+    const discovery = await discoverManifests(root);
+    const matches = [];
+    for (const manifest of discovery.manifests.slice(0, MAX_INDEX_RECORDS)) {
+        const classified = await classifyManifest(manifest.absolutePath);
+        if (classified.supportState !== 'supported' || classified.family !== 'observation')
+            continue;
+        const { artifact } = classified;
+        if (referencesMatch(ref, artifact.observationId, artifact.requestId, artifact.producer.version, artifact.schemaVersion)) {
+            matches.push(encodeArtifactHandle('observation', manifest.relativeDir));
+        }
+    }
+    if (matches.length === 0)
+        return { status: 'missing' };
+    if (matches.length > 1)
+        return { status: 'ambiguous', count: matches.length };
+    return { status: 'resolved', handle: matches[0] };
+}
+export async function resolveComparisonByIdentity(root, comparisonId, comparisonRequestId) {
+    const discovery = await discoverManifests(root);
+    const matches = [];
+    for (const manifest of discovery.manifests.slice(0, MAX_INDEX_RECORDS)) {
+        const classified = await classifyManifest(manifest.absolutePath);
+        if (classified.supportState !== 'supported' || classified.family !== 'comparison')
+            continue;
+        if (classified.artifact.comparisonId === comparisonId && classified.artifact.comparisonRequestId === comparisonRequestId) {
+            matches.push(encodeArtifactHandle('comparison', manifest.relativeDir));
+        }
+    }
+    if (matches.length === 0)
+        return { status: 'missing' };
+    if (matches.length > 1)
+        return { status: 'ambiguous', count: matches.length };
+    return { status: 'resolved', handle: matches[0] };
+}
+export async function resolveBaselineContractById(root, baselineId) {
+    const discovery = await discoverManifests(root);
+    const matches = [];
+    for (const manifest of discovery.manifests.slice(0, MAX_INDEX_RECORDS)) {
+        const classified = await classifyManifest(manifest.absolutePath);
+        if (classified.supportState !== 'supported' || classified.family !== 'baseline-contract')
+            continue;
+        if (classified.artifact.baselineId === baselineId) {
+            matches.push(encodeArtifactHandle('baseline-contract', manifest.relativeDir));
+        }
+    }
+    if (matches.length === 0)
+        return { status: 'missing' };
+    if (matches.length > 1)
+        return { status: 'ambiguous', count: matches.length };
+    return { status: 'resolved', handle: matches[0] };
+}
+export async function resolveChangeContractById(root, contractId) {
+    const discovery = await discoverManifests(root);
+    const matches = [];
+    for (const manifest of discovery.manifests.slice(0, MAX_INDEX_RECORDS)) {
+        const classified = await classifyManifest(manifest.absolutePath);
+        if (classified.supportState !== 'supported' || classified.family !== 'change-contract')
+            continue;
+        if (classified.artifact.contractId === contractId) {
+            matches.push(encodeArtifactHandle('change-contract', manifest.relativeDir));
+        }
+    }
+    if (matches.length === 0)
+        return { status: 'missing' };
+    if (matches.length > 1)
+        return { status: 'ambiguous', count: matches.length };
+    return { status: 'resolved', handle: matches[0] };
+}
+/**
+ * Batch 7 addition: resolves an observation by bare `observationId` alone
+ * (exact match, never a substring/pathname heuristic) - the only identity a
+ * `BoundedAgentContextArtifact.sources.observationIds` entry actually
+ * carries (unlike the compound `{observationId, requestId, producer,
+ * observationSchemaVersion}` reference `resolveObservationByReference`
+ * consumes for Batch 4/5 cross-artifact references). Same missing/ambiguous
+ * discipline as every other resolver in this module.
+ */
+export async function resolveObservationById(root, observationId) {
+    const discovery = await discoverManifests(root);
+    const matches = [];
+    for (const manifest of discovery.manifests.slice(0, MAX_INDEX_RECORDS)) {
+        const classified = await classifyManifest(manifest.absolutePath);
+        if (classified.supportState !== 'supported' || classified.family !== 'observation')
+            continue;
+        if (classified.artifact.observationId === observationId) {
+            matches.push(encodeArtifactHandle('observation', manifest.relativeDir));
+        }
+    }
+    if (matches.length === 0)
+        return { status: 'missing' };
+    if (matches.length > 1)
+        return { status: 'ambiguous', count: matches.length };
+    return { status: 'resolved', handle: matches[0] };
+}
+/** Batch 7 addition: resolves a `FrontendContractEvaluationArtifact` by its own exact `evaluationId`+`evaluationRequestId` (a bounded-agent-context source reference, never resolved via the `after` observation the way Batch 5's candidate-context lookup works). */
+export async function resolveEvaluationByIdentity(root, evaluationId, evaluationRequestId) {
+    const discovery = await discoverManifests(root);
+    const matches = [];
+    for (const manifest of discovery.manifests.slice(0, MAX_INDEX_RECORDS)) {
+        const classified = await classifyManifest(manifest.absolutePath);
+        if (classified.supportState !== 'supported' || classified.family !== 'contract-evaluation')
+            continue;
+        if (classified.artifact.evaluationId === evaluationId && classified.artifact.evaluationRequestId === evaluationRequestId) {
+            matches.push(encodeArtifactHandle('contract-evaluation', manifest.relativeDir));
+        }
+    }
+    if (matches.length === 0)
+        return { status: 'missing' };
+    if (matches.length > 1)
+        return { status: 'ambiguous', count: matches.length };
+    return { status: 'resolved', handle: matches[0] };
+}
+/** Batch 7 addition: resolves an `ExternalReferenceArtifact` (imported or approved) by its own exact `referenceId`+`referenceRequestId` - a bounded-agent-context source reference. Matches either lifecycle family; never assumes which one. */
+export async function resolveReferenceByIdentity(root, referenceId, referenceRequestId) {
+    const discovery = await discoverManifests(root);
+    const matches = [];
+    for (const manifest of discovery.manifests.slice(0, MAX_INDEX_RECORDS)) {
+        const classified = await classifyManifest(manifest.absolutePath);
+        if (classified.supportState !== 'supported' || (classified.family !== 'external-reference-imported' && classified.family !== 'external-reference-approved'))
+            continue;
+        if (classified.artifact.referenceId === referenceId && classified.artifact.referenceRequestId === referenceRequestId) {
+            matches.push({ handle: encodeArtifactHandle(classified.family, manifest.relativeDir) });
+        }
+    }
+    if (matches.length === 0)
+        return { status: 'missing' };
+    if (matches.length > 1)
+        return { status: 'ambiguous', count: matches.length };
+    return { status: 'resolved', handle: matches[0].handle };
+}
+//# sourceMappingURL=linkedEvidence.js.map

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

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

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

@@ -0,0 +1,16 @@
+export type MediaRole = 'screenshot' | 'image' | 'source-image';
+export type MediaResolution = {
+    ok: true;
+    absolutePath: string;
+    mimeType: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 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 declare function resolveMedia(root: string, artifactHandle: string, role: string): Promise<MediaResolution>;