my-frontend-observer 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## [Unreleased]
+
+## 0.8.0 - 2026-09-10
+
+Interactive Local Observation Viewer.
+
+- New `view` command: starts a loopback-only (`127.0.0.1`) Node server
+  serving a React + TypeScript + Vite viewer application, usable in a normal
+  browser or as an installed Progressive Web App, over an existing evidence
+  root (`--root`). Metadata-first evidence discovery and on-demand
+  artifact/media loading; never mutates target source or any Observer
+  evidence artifact.
+- Observation inspection: screenshot plus SVG target overlays, geometry,
+  semantics, visibility/overflow/scroll evidence, and on-demand layout
+  relationships.
+- Comparison/contract inspection: before/after side-by-side views and
+  contract/change-scope evaluation results, including the required
+  protected/preserved-failure safety case (a locally successful requested
+  change alongside a genuine protected/preserved regression, shown as
+  overall `FAIL`).
+- External reference/candidate inspection: reference image and region
+  overlays, explicit (never auto-selected) candidate selection,
+  reference/candidate compatibility and applicability.
+- Explicit reference-region/runtime-target binding cross-selection
+  (`--bindings-file`), independent bounded zoom/pan, conditional view lock,
+  and on-demand reference-fidelity evaluation shown independently alongside
+  any selected contract evaluation.
+- Bounded agent context inspection (`--context-file`): session-only display
+  of context identity, adequacy, omissions/truncations, and runtime/static
+  correlation, plus safe raw-evidence navigation. The viewer never rebuilds
+  a bounded context or its correlation and never runs `@dailephd/my-dev-kit`.
+- PWA hardening: real service-worker registration, an application-shell
+  precache that excludes `/api/` routes, and a proven server-down behavior
+  that never presents stale evidence as current.
+- No second evidence engine: every canonical result the viewer displays is
+  produced by the same single engine the CLI uses, called from at most one
+  designated server-side call site.
+- Security hardening found during pre-release readiness: the viewer's media
+  route now rejects any evidence filename that is itself a symlink/junction
+  pointing outside the evidence root, instead of following it.
+- Cross-platform packed-candidate validation: the pre-version-bump
+  implementation candidate tarball `my-frontend-observer-0.7.0.tgz`
+  (SHA-256 `b80729bc64b3b01378effd2b8aa3b7743ccedc46b3148ba0b1ff1ae5a4b68c55`)
+  was hash-verified and proven on Windows, Linux, and macOS, including an
+  installed-package smoke of the new `view` command (loopback binding,
+  read-only API, path containment, SVG overlay/media, service-worker
+  registration, the PWA no-authoritative-cache boundary, and the
+  server-down stale-evidence hard gate) alongside every pre-existing
+  v0.1-v0.7 packed behavior, before this release's version bump - see
+  `docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`.
+
+## 0.7.0 - 2026-09-06
+
+End-to-End Coding-Agent Frontend Change Review.
+
+- External-reference artifact and lifecycle: `import-reference`/
+  `approve-reference` persist an externally supplied PNG/JPEG/WebP
+  design-reference image (header-only format/dimension detection - no
+  decode, no OCR, no computer vision) through an explicit two-state
+  (`imported`/`approved`) lifecycle. Supersession is represented only as a
+  forward pointer to a newer artifact - an existing persisted artifact's own
+  manifest is never rewritten.
+- Explicit reference regions and geometry relationships: user/configuration-
+  authored rectangles over the reference image, related to each other
+  through the same six geometry-only relationship families (horizontal
+  order, vertical order, area overlap, relative width, geometric fit,
+  vertical sequencing) already used for runtime targets - derived on demand,
+  never persisted.
+- Selected design requirements and tolerance semantics: explicit,
+  never-inferred requirements over region properties, region-to-region
+  relationships, and derived two-region measurements, reusing v0.5's
+  requested/expected-dependent/protected/preserved categories directly.
+  Three reference-owned tolerance kinds (`exact`/`absolute-reference-px`/
+  `percent`) stay distinct from runtime CSS-pixel comparison tolerances.
+- Reference-evidence adequacy: `adequate`/`partial`/`inadequate` reporting on
+  whether a reference's own definition actually supports its selected
+  requirements, independent of any runtime target or candidate.
+- Explicit applicability and candidate-state compatibility: a shared, closed
+  state model (`theme`/`applicationState`/`authenticatedState`, plus an
+  applicable CSS-pixel `viewport`) declares which runtime frontend state a
+  reference represents. `evaluateReferenceCandidateCompatibility` and
+  `observe`'s new `--state-file` reuse v0.4's comparability vocabulary to
+  determine whether a reference and a candidate describe the same state -
+  an undeclared dimension is never fabricated as a match or a mismatch.
+- Explicit reference-region-to-runtime-target binding: fidelity evaluation
+  requires an explicit `{referenceRegion, runtimeTarget}` declaration for
+  every region a requirement depends on - never inferred from geometry,
+  matching names, or source code.
+- Structured reference-vs-candidate fidelity evaluation: `evaluate-
+  reference-fidelity --reference --candidate [--bindings-file] [--enforce]`
+  evaluates every selected requirement against live candidate evidence
+  through one explicit reference-image-pixel-to-CSS-pixel coordinate scale,
+  producing an honest `not-evaluated`/`pass`/`fail` result that never
+  fabricates a verdict past a blocked reference-adequacy or
+  reference/candidate-compatibility gate.
+- Bounded fidelity integration with v0.6 agent context: `projectBoundedAgentContext`
+  gained an optional `fidelity` input so fidelity mismatches compete for the
+  same bounded required/permitted-target allocation and adequacy machinery
+  v0.5 contract clauses already use - a `not-evaluated` fidelity always
+  degrades adequacy rather than being silently reported as "no problems".
+- End-to-end external-reference correction workflow: the programmatic,
+  library-only `prepareReferenceCorrection`/`reviewReferenceCorrectionAttempt`
+  compose reference fidelity, v0.4 comparison, and v0.5 contract evaluation
+  into one overall result - matching the reference is necessary but never
+  sufficient, so a candidate that visually satisfies the reference while
+  regressing an active protected/preserved contract clause still resolves to
+  overall `FAIL`. Neither function edits target source, launches a browser,
+  or calls a remote AI provider; an external implementation actor (a human
+  or a coding agent) makes the actual change between review attempts.
+- Real-browser regression protection: a dedicated Chromium-driven test
+  proves a full success correction, a protected-regression case, a
+  two-attempt correction iteration against the same baseline, and an
+  incompatible-viewport blocking case, all against a disposable,
+  repository-local fixture copy the observer itself never edits.
+- Three new public CLI commands (`import-reference`, `approve-reference`,
+  `evaluate-reference-fidelity`) and a complete new programmatic export
+  surface (`src/index.ts`) for the reference/region/requirement/
+  applicability/compatibility/binding/fidelity/correction-workflow types and
+  functions. External-reference schema is `1.0.0`, independent of the
+  observation, comparison, frontend-contract, evaluation, and
+  bounded-agent-context schema versions, none of which changed.
+- Cross-platform packed-candidate validation: the pre-version-bump
+  implementation candidate tarball `my-frontend-observer-0.6.0.tgz`
+  (SHA-256 `0347b1f3cfd5d311e13b405c0c2fbc2f507e250cb63223d58b4d2d31df029414`)
+  was hash-verified and proven on Windows, Linux, and macOS, including an
+  installed-package smoke of every new v0.7 CLI command and programmatic
+  export alongside every pre-existing v0.1-v0.6 packed behavior, before this
+  release's version bump - see
+  `docs/reports/v0.7-pre-release-readiness.md`.
+
 ## 0.6.0 - 2026-08-19
 
 Bounded Agent Context and Native my-dev-kit Ecosystem Integration.

package/README.md

@@ -6,9 +6,11 @@ in [docs/PROJECT_DESCRIPTION.md](docs/PROJECT_DESCRIPTION.md).
 
 ## Current status
 
-`v0.6.0`, Bounded Agent Context and Native my-dev-kit Ecosystem Integration,
-is the current published release. It builds on `v0.5.0`, Executable Frontend
-Contracts and Explicit Change Scope: `my-frontend-observer observe` launches a real,
+`v0.8.0`, Interactive Local Observation Viewer, is the current published
+release. It builds on `v0.7.0`, End-to-End Coding-Agent Frontend Change
+Review, `v0.6.0`, Bounded Agent Context and Native my-dev-kit Ecosystem
+Integration, and `v0.5.0`, Executable Frontend Contracts and Explicit Change
+Scope: `my-frontend-observer observe` launches a real,
 sandboxed Chromium browser, enforces a loopback-only safety policy, captures
 a viewport screenshot plus bounded page/target evidence, and persists it as
 one portable `manifest.json` + `screenshot.png` artifact (observation schema
@@ -132,6 +134,73 @@ exported from `src/index.ts` (bounded-agent-context schema `1.0.0`). See
 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how it fits the existing
 pipeline.
 
+### External-reference correction workflow (v0.7.0)
+
+`import-reference` and
+`approve-reference` persist an externally supplied design-reference image
+(with optional regions, selected requirements/tolerances, and applicability
+state); `evaluate-reference-fidelity --reference --candidate
+[--bindings-file] [--enforce]` compares an already-persisted candidate
+observation against it, gated by reference adequacy, reference/candidate
+compatibility, and explicit region-to-target bindings:
+
+```powershell
+my-frontend-observer import-reference design.png --output references --regions-file regions.json --requirements-file requirements.json --applicability-file applicability.json
+my-frontend-observer approve-reference --reference references/<id> --output references
+my-frontend-observer evaluate-reference-fidelity --reference references/<approved-id> --candidate observations/<id> --bindings-file bindings.json
+```
+
+(From a source checkout, use `node dist/cli.js import-reference ...` etc.
+instead.)
+
+`import-reference`/`approve-reference`/`evaluate-reference-fidelity` never
+launch a browser or edit any file outside their own declared output
+location; `evaluate-reference-fidelity` persists nothing. A programmatic,
+library-only correction-workflow coordinator
+(`prepareReferenceCorrection`/`reviewReferenceCorrectionAttempt`, exported
+from `src/index.ts`, no CLI command) composes the full cycle - reference
+fidelity (reused unchanged) plus canonical v0.4 comparison and v0.5 contract
+evaluation - into one overall result: matching the reference is necessary
+but never sufficient, so a candidate that visually satisfies the reference
+while regressing an active protected/preserved contract clause still
+resolves to overall `FAIL`. my-frontend-observer never edits target source
+itself; an external implementation actor (a human or a coding agent, never
+this package) makes the actual source change between review attempts. See
+[docs/CONTRACTS.md](docs/CONTRACTS.md) and
+[docs/WORKFLOWS.md](docs/WORKFLOWS.md) for the exact contract and workflow,
+and [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) for the full
+implementation record.
+
+### Interactive local viewer (v0.8.0)
+
+`my-frontend-observer view --root <evidence-root> [--bindings-file <json-file>] [--context-file <json-file>] [--port <n>] [--no-open]`
+starts a loopback-only (`127.0.0.1`) Node server that serves a React +
+TypeScript + Vite viewer application - usable in a normal browser or as an
+installed Progressive Web App - over the same evidence root used by every
+other command above. It never edits target source, never mutates any
+evidence artifact, and never runs `@dailephd/my-dev-kit`:
+
+```powershell
+my-frontend-observer view --root observations --port 4319 --no-open
+```
+
+(From a source checkout, use `node dist/cli.js view ...` instead.)
+
+The viewer shows observation screenshots and SVG target overlays,
+before/after comparisons and contract/change-scope results, approved
+external references beside candidate observations with explicit binding
+cross-selection and on-demand fidelity evaluation, and - when
+`--context-file` supplies one - a read-only inspection of a bounded agent
+context's adequacy, omissions/truncations, and runtime/static correlation.
+Both `--bindings-file` and `--context-file` are explicit, session-only
+input: read once at startup, held only in server memory, never persisted,
+and never exposed as a filesystem path to the browser. See
+[docs/COMMANDS.md](docs/COMMANDS.md#view) for the full flag reference and
+[docs/WORKFLOWS.md](docs/WORKFLOWS.md) for the viewer workflow.
+
+See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) for the exact current
+implementation and release state.
+
 Validation:
 
 ```powershell
@@ -139,6 +208,7 @@ npm run typecheck
 npm run lint
 npm test
 npm run test:browser
+npm run test:security
 npm run build
 npm run check:docs
 ```
@@ -149,8 +219,8 @@ Planning authorities:
   intent and responsibility boundaries.
 - [Project Milestones](docs/PROJECT_MILESTONES.md): complete ordered capability
   design and cross-milestone rules.
-- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1-v0.6 are
-  released, v0.7+ remain future.
+- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1-v0.8 are
+  released; v0.9+ remain future.
 - [Current State](docs/CURRENT_STATE.md): retained scaffold and release state.
 
 No sibling ecosystem repository is a runtime dependency of the retained

package/dist/application/externalReferencePersistenceService.d.ts

@@ -0,0 +1,75 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { ReferenceRegion } from '../domain/externalReferenceRegions.js';
+import type { RawReferenceRequirement, ReferenceRequirementAdequacy } from '../domain/externalReferenceRequirements.js';
+import type { ExternalReferenceApplicability } from '../domain/externalReferenceApplicability.js';
+import type { WriteExternalReferenceArtifactOptions } from '../artifacts/externalReferenceArtifactWriter.js';
+export interface ImportExternalReferenceOptions {
+    outputLocation: string;
+    cwd?: WriteExternalReferenceArtifactOptions['cwd'];
+    label?: string;
+    /** Root directory of a prior external-reference artifact this import explicitly supersedes. */
+    supersedesReferenceRoot?: string;
+    /** v0.7 Prompt 2: explicit, user/configuration-authored reference-image regions. Identity-bearing when present - see externalReferenceIdentity.ts. */
+    regions?: ReferenceRegion[];
+    /** v0.7 Prompt 3: explicit, user/configuration-selected design requirements over `regions` above. Raw (not yet identified) authored input - see domain/externalReferenceRequirements.ts#RawReferenceRequirement. Identity-bearing when present. */
+    requirements?: RawReferenceRequirement[];
+    /** v0.7 Prompt 4: the runtime frontend state (applicable viewport/theme/application-state/authenticated-state) this reference is intended to represent. Identity-bearing when present. */
+    applicability?: ExternalReferenceApplicability;
+}
+export interface ApproveExternalReferenceOptions {
+    outputLocation: string;
+    cwd?: WriteExternalReferenceArtifactOptions['cwd'];
+    /** Root directory of a prior external-reference artifact this approval explicitly supersedes. */
+    supersedesReferenceRoot?: string;
+}
+export type ApplicationImportExternalReferenceResult = {
+    ok: true;
+    referenceId: string;
+    referenceRequestId: string;
+    artifactRoot: string;
+    manifestPath: string;
+    imagePath: string;
+    regionCount: number;
+    requirementCount: number;
+    adequacy: ReferenceRequirementAdequacy;
+    hasApplicability: boolean;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+export type ApplicationApproveExternalReferenceResult = {
+    ok: true;
+    referenceId: string;
+    referenceRequestId: string;
+    artifactRoot: string;
+    manifestPath: string;
+    regionCount: number;
+    requirementCount: number;
+    adequacy: ReferenceRequirementAdequacy;
+    hasApplicability: boolean;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * The one canonical application-level "import" use case: validates the raw
+ * image bytes through the existing pure image-format/dimension boundary
+ * (`domain/externalReferenceImage.ts`), resolves an optional explicit
+ * supersession target through the existing reader, computes identity through
+ * the existing identity module, and persists exactly once through the
+ * existing writer. Never approves the result - the persisted artifact's
+ * `lifecycle.state` is always `'imported'`, regardless of a supplied label or
+ * supersession target (see behavior-model.txt INV-007).
+ */
+export declare function importExternalReference(imageBytes: Uint8Array, options: ImportExternalReferenceOptions): Promise<ApplicationImportExternalReferenceResult>;
+/**
+ * The one canonical application-level "approval" use case, mirroring
+ * `application/frontendContractPersistenceService.ts#approveAndPersistBaseline`'s
+ * shape: reads the target through the existing reader, refuses to approve
+ * anything not currently in the `'imported'` lifecycle state, resolves an
+ * optional explicit supersession target through the same reader, and
+ * persists a brand-new artifact instance - never mutating the imported
+ * artifact's own manifest - carrying a `sourceReference` back to it instead
+ * of a second copy of the image bytes.
+ */
+export declare function approveExternalReference(importedArtifactRoot: string, options: ApproveExternalReferenceOptions): Promise<ApplicationApproveExternalReferenceResult>;

package/dist/application/externalReferencePersistenceService.js

@@ -0,0 +1,182 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+import { deriveCompletion } from '../domain/completion.js';
+import { getProducerInfo } from '../domain/schema.js';
+import { detectExternalReferenceImageFormat, readExternalReferenceImageDimensions, isValidExternalReferenceImageDimensions, fileExtensionForFormat, EXTERNAL_REFERENCE_MAX_IMAGE_BYTES, } from '../domain/externalReferenceImage.js';
+import { EXTERNAL_REFERENCE_ARTIFACT_KIND, EXTERNAL_REFERENCE_SCHEMA_VERSION, isImportedExternalReferenceArtifact } from '../domain/externalReference.js';
+import { buildExternalReferenceRequestIdentity, buildExternalReferenceInstanceIdentity } from '../domain/externalReferenceIdentity.js';
+import { isValidReferenceRegions } from '../domain/externalReferenceRegions.js';
+import { isValidRawReferenceRequirement, buildReferenceRequirement, isValidReferenceRequirements, deriveReferenceRequirementAdequacy } from '../domain/externalReferenceRequirements.js';
+import { isValidExternalReferenceApplicability } from '../domain/externalReferenceApplicability.js';
+import { normalizeOutputLocation } from '../request/paths.js';
+import { writeExternalReferenceArtifact } from '../artifacts/externalReferenceArtifactWriter.js';
+import { EXTERNAL_REFERENCE_MANIFEST_FILENAME } from '../artifacts/externalReferenceArtifactWriter.js';
+import { readExternalReferenceArtifact } from '../artifacts/externalReferenceArtifactReader.js';
+function failure(code, message) {
+    return { ok: false, diagnostics: [{ code, severity: DIAGNOSTIC_SEVERITY[code], message }] };
+}
+async function resolveSupersedesReferenceId(supersedesReferenceRoot) {
+    if (supersedesReferenceRoot === undefined)
+        return { ok: true };
+    const read = await readExternalReferenceArtifact(path.join(supersedesReferenceRoot, EXTERNAL_REFERENCE_MANIFEST_FILENAME));
+    if (!read.ok)
+        return failure('reference-not-found', `supersedesReferenceRoot: ${read.reason}`);
+    return { ok: true, referenceId: read.artifact.referenceId };
+}
+/**
+ * The one canonical application-level "import" use case: validates the raw
+ * image bytes through the existing pure image-format/dimension boundary
+ * (`domain/externalReferenceImage.ts`), resolves an optional explicit
+ * supersession target through the existing reader, computes identity through
+ * the existing identity module, and persists exactly once through the
+ * existing writer. Never approves the result - the persisted artifact's
+ * `lifecycle.state` is always `'imported'`, regardless of a supplied label or
+ * supersession target (see behavior-model.txt INV-007).
+ */
+export async function importExternalReference(imageBytes, options) {
+    const format = detectExternalReferenceImageFormat(imageBytes);
+    if (format === undefined)
+        return failure('unsupported-image-format', 'the supplied bytes do not match any supported reference image format (png, jpeg, webp)');
+    if (imageBytes.length > EXTERNAL_REFERENCE_MAX_IMAGE_BYTES) {
+        return failure('image-too-large', `reference image is ${imageBytes.length} bytes, exceeding the maximum of ${EXTERNAL_REFERENCE_MAX_IMAGE_BYTES} bytes`);
+    }
+    const dimensions = readExternalReferenceImageDimensions(imageBytes, format);
+    if (dimensions === undefined || !isValidExternalReferenceImageDimensions(dimensions)) {
+        return failure('invalid-image-dimensions', 'the supplied reference image header does not contain valid, bounded dimensions');
+    }
+    if (options.regions !== undefined) {
+        const regionsValidation = isValidReferenceRegions(options.regions, dimensions.width, dimensions.height);
+        if (!regionsValidation.valid)
+            return failure('invalid-reference-region', regionsValidation.reason);
+    }
+    let requirements;
+    if (options.requirements !== undefined) {
+        const built = [];
+        for (const raw of options.requirements) {
+            const rawValidation = isValidRawReferenceRequirement(raw);
+            if (!rawValidation.valid)
+                return failure('invalid-reference-requirement', rawValidation.reason);
+            built.push(buildReferenceRequirement(raw));
+        }
+        const collectionValidation = isValidReferenceRequirements(built, options.regions ?? []);
+        if (!collectionValidation.valid)
+            return failure('invalid-reference-requirement', collectionValidation.reason);
+        requirements = built;
+    }
+    if (options.applicability !== undefined) {
+        const applicabilityValidation = isValidExternalReferenceApplicability(options.applicability);
+        if (!applicabilityValidation.valid)
+            return failure('invalid-reference-applicability', applicabilityValidation.reason);
+    }
+    const supersedes = await resolveSupersedesReferenceId(options.supersedesReferenceRoot);
+    if (!supersedes.ok)
+        return supersedes;
+    const normalizedOutput = normalizeOutputLocation(options.outputLocation);
+    if (!normalizedOutput.ok)
+        return { ok: false, diagnostics: [normalizedOutput.diagnostic] };
+    const imageSha256 = createHash('sha256').update(imageBytes).digest('hex');
+    const referenceRequestId = buildExternalReferenceRequestIdentity(imageSha256, format, dimensions.width, dimensions.height, supersedes.referenceId, options.regions, requirements, options.applicability);
+    const referenceId = buildExternalReferenceInstanceIdentity(referenceRequestId);
+    const artifact = {
+        artifactKind: EXTERNAL_REFERENCE_ARTIFACT_KIND,
+        schemaVersion: EXTERNAL_REFERENCE_SCHEMA_VERSION,
+        referenceRequestId,
+        referenceId,
+        producer: getProducerInfo(),
+        provenance: { importedAt: new Date().toISOString(), ...(options.label === undefined ? {} : { label: options.label }) },
+        image: {
+            path: `reference.${fileExtensionForFormat(format)}`,
+            format,
+            width: dimensions.width,
+            height: dimensions.height,
+            byteLength: imageBytes.length,
+            sha256: imageSha256,
+        },
+        lifecycle: { state: 'imported' },
+        ...(supersedes.referenceId === undefined ? {} : { supersedesReferenceId: supersedes.referenceId }),
+        ...(options.regions === undefined ? {} : { regions: options.regions }),
+        ...(requirements === undefined ? {} : { requirements }),
+        ...(options.applicability === undefined ? {} : { applicability: options.applicability }),
+        diagnostics: [],
+        completion: deriveCompletion([], 'post-capture'),
+    };
+    const persisted = await writeExternalReferenceArtifact(artifact, imageBytes, normalizedOutput.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok)
+        return { ok: false, diagnostics: persisted.diagnostics };
+    return {
+        ok: true,
+        referenceId: artifact.referenceId,
+        referenceRequestId: artifact.referenceRequestId,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        imagePath: persisted.imagePath,
+        regionCount: artifact.regions?.length ?? 0,
+        requirementCount: artifact.requirements?.length ?? 0,
+        adequacy: deriveReferenceRequirementAdequacy(artifact.regions ?? [], artifact.requirements ?? []),
+        hasApplicability: artifact.applicability !== undefined,
+    };
+}
+/**
+ * The one canonical application-level "approval" use case, mirroring
+ * `application/frontendContractPersistenceService.ts#approveAndPersistBaseline`'s
+ * shape: reads the target through the existing reader, refuses to approve
+ * anything not currently in the `'imported'` lifecycle state, resolves an
+ * optional explicit supersession target through the same reader, and
+ * persists a brand-new artifact instance - never mutating the imported
+ * artifact's own manifest - carrying a `sourceReference` back to it instead
+ * of a second copy of the image bytes.
+ */
+export async function approveExternalReference(importedArtifactRoot, options) {
+    const read = await readExternalReferenceArtifact(path.join(importedArtifactRoot, EXTERNAL_REFERENCE_MANIFEST_FILENAME));
+    if (!read.ok)
+        return failure('reference-not-found', read.reason);
+    if (!isImportedExternalReferenceArtifact(read.artifact)) {
+        return failure('invalid-request', `external-reference artifact "${read.artifact.referenceId}" is not in the "imported" lifecycle state; only a freshly imported reference can be approved`);
+    }
+    const imported = read.artifact;
+    const supersedes = await resolveSupersedesReferenceId(options.supersedesReferenceRoot);
+    if (!supersedes.ok)
+        return supersedes;
+    const normalizedOutput = normalizeOutputLocation(options.outputLocation);
+    if (!normalizedOutput.ok)
+        return { ok: false, diagnostics: [normalizedOutput.diagnostic] };
+    const referenceId = buildExternalReferenceInstanceIdentity(imported.referenceRequestId);
+    const artifact = {
+        artifactKind: EXTERNAL_REFERENCE_ARTIFACT_KIND,
+        schemaVersion: EXTERNAL_REFERENCE_SCHEMA_VERSION,
+        referenceRequestId: imported.referenceRequestId,
+        referenceId,
+        producer: getProducerInfo(),
+        provenance: { importedAt: imported.provenance.importedAt, ...(imported.provenance.label === undefined ? {} : { label: imported.provenance.label }) },
+        sourceReference: {
+            referenceId: imported.referenceId,
+            referenceRequestId: imported.referenceRequestId,
+            producer: imported.producer,
+            schemaVersion: imported.schemaVersion,
+            image: imported.image,
+        },
+        lifecycle: { state: 'approved', approvedAt: new Date().toISOString() },
+        ...(supersedes.referenceId === undefined ? {} : { supersedesReferenceId: supersedes.referenceId }),
+        ...(imported.regions === undefined ? {} : { regions: imported.regions }),
+        ...(imported.requirements === undefined ? {} : { requirements: imported.requirements }),
+        ...(imported.applicability === undefined ? {} : { applicability: imported.applicability }),
+        diagnostics: [],
+        completion: deriveCompletion([], 'post-capture'),
+    };
+    const persisted = await writeExternalReferenceArtifact(artifact, undefined, normalizedOutput.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok)
+        return { ok: false, diagnostics: persisted.diagnostics };
+    return {
+        ok: true,
+        referenceId: artifact.referenceId,
+        referenceRequestId: artifact.referenceRequestId,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        regionCount: artifact.regions?.length ?? 0,
+        requirementCount: artifact.requirements?.length ?? 0,
+        adequacy: deriveReferenceRequirementAdequacy(artifact.regions ?? [], artifact.requirements ?? []),
+        hasApplicability: artifact.applicability !== undefined,
+    };
+}
+//# sourceMappingURL=externalReferencePersistenceService.js.map

package/dist/application/externalReferencePersistenceService.js.map

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

package/dist/application/referenceFidelityEvaluationService.d.ts

@@ -0,0 +1,28 @@
+import type { EvaluateReferenceCandidateFidelityOptions, ReferenceCandidateFidelityEvaluation } from '../domain/externalReferenceFidelity.js';
+import type { ReferenceRuntimeBindingDeclaration } from '../domain/externalReferenceRuntimeBinding.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+export type EvaluateReferenceFidelityOptions = EvaluateReferenceCandidateFidelityOptions;
+export type ApplicationReferenceFidelityResult = {
+    ok: true;
+    evaluation: ReferenceCandidateFidelityEvaluation;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * The canonical CLI-facing orchestration for Prompt 6, mirroring
+ * `comparisonService.ts#compareAndPersistFromArtifactRoots`'s exact shape:
+ * reads one already-persisted `ExternalReferenceArtifact` and one already-
+ * persisted `ObservationArtifact` by their root directories through the
+ * existing readers, then delegates to the pure
+ * `evaluateReferenceCandidateFidelity` exactly once. A thin wrapper only -
+ * artifact reading stays owned by `artifacts/`, evaluation semantics stay
+ * owned by `domain/externalReferenceFidelity.ts`. Kept in `application/`
+ * (not `artifacts/`) so `src/cli.ts` can depend on it without importing the
+ * artifacts layer directly, matching every other command's import-boundary
+ * convention. Never launches a browser, never re-resolves targets, and -
+ * deliberately, per this prompt's persistence decision - never persists
+ * anything: the caller receives the structured in-memory evaluation result
+ * directly.
+ */
+export declare function evaluateReferenceCandidateFidelityFromArtifactRoots(referenceRoot: string, candidateRoot: string, bindingDeclarations: readonly ReferenceRuntimeBindingDeclaration[], options?: EvaluateReferenceFidelityOptions): Promise<ApplicationReferenceFidelityResult>;

package/dist/application/referenceFidelityEvaluationService.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { readExternalReferenceArtifact } from '../artifacts/externalReferenceArtifactReader.js';
+import { EXTERNAL_REFERENCE_MANIFEST_FILENAME } from '../artifacts/externalReferenceArtifactWriter.js';
+import { readObservationArtifact } from '../artifacts/artifactReader.js';
+import { MANIFEST_FILENAME as OBSERVATION_MANIFEST_FILENAME } from '../artifacts/artifactWriter.js';
+import { evaluateReferenceCandidateFidelity } from '../domain/externalReferenceFidelity.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+/**
+ * The canonical CLI-facing orchestration for Prompt 6, mirroring
+ * `comparisonService.ts#compareAndPersistFromArtifactRoots`'s exact shape:
+ * reads one already-persisted `ExternalReferenceArtifact` and one already-
+ * persisted `ObservationArtifact` by their root directories through the
+ * existing readers, then delegates to the pure
+ * `evaluateReferenceCandidateFidelity` exactly once. A thin wrapper only -
+ * artifact reading stays owned by `artifacts/`, evaluation semantics stay
+ * owned by `domain/externalReferenceFidelity.ts`. Kept in `application/`
+ * (not `artifacts/`) so `src/cli.ts` can depend on it without importing the
+ * artifacts layer directly, matching every other command's import-boundary
+ * convention. Never launches a browser, never re-resolves targets, and -
+ * deliberately, per this prompt's persistence decision - never persists
+ * anything: the caller receives the structured in-memory evaluation result
+ * directly.
+ */
+export async function evaluateReferenceCandidateFidelityFromArtifactRoots(referenceRoot, candidateRoot, bindingDeclarations, options = {}) {
+    const referenceRead = await readExternalReferenceArtifact(path.join(referenceRoot, EXTERNAL_REFERENCE_MANIFEST_FILENAME));
+    if (!referenceRead.ok) {
+        return {
+            ok: false,
+            diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: `--reference external-reference artifact: ${referenceRead.reason}` }],
+        };
+    }
+    const candidateRead = await readObservationArtifact(path.join(candidateRoot, OBSERVATION_MANIFEST_FILENAME));
+    if (!candidateRead.ok) {
+        return {
+            ok: false,
+            diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: `--candidate observation artifact: ${candidateRead.reason}` }],
+        };
+    }
+    const result = evaluateReferenceCandidateFidelity(referenceRead.artifact, candidateRead.artifact, bindingDeclarations, options);
+    if (!result.ok) {
+        return { ok: false, diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: result.reason }] };
+    }
+    return { ok: true, evaluation: result.evaluation };
+}
+//# sourceMappingURL=referenceFidelityEvaluationService.js.map

package/dist/application/referenceFidelityEvaluationService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"referenceFidelityEvaluationService.js","sourceRoot":"","sources":["../../src/application/referenceFidelityEvaluationService.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,6BAA6B,EAAE,MAAM,iDAAiD,CAAC;AAChG,OAAO,EAAE,oCAAoC,EAAE,MAAM,iDAAiD,CAAC;AACvG,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,iBAAiB,IAAI,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AACpG,OAAO,EAAE,kCAAkC,EAAE,MAAM,wCAAwC,CAAC;AAI5F,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAM/D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,mDAAmD,CACvE,aAAqB,EACrB,aAAqB,EACrB,mBAAkE,EAClE,UAA4C,EAAE;IAE9C,MAAM,aAAa,GAAG,MAAM,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,oCAAoC,CAAC,CAAC,CAAC;IAC1H,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC;QACtB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,4CAA4C,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC;SAC1K,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,6BAA6B,CAAC,CAAC,CAAC;IAC7G,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC;QACtB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,qCAAqC,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC;SACnK,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,kCAAkC,CAAC,aAAa,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,mBAAmB,EAAE,OAAO,CAAC,CAAC;IAChI,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;IAC7I,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;AACrD,CAAC"}

package/dist/artifacts/externalReferenceArtifactReader.d.ts

@@ -0,0 +1,18 @@
+import type { ExternalReferenceArtifact } from '../domain/externalReference.js';
+export type ReadExternalReferenceArtifactResult = {
+    ok: true;
+    artifact: ExternalReferenceArtifact;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Narrow canonical reader counterpart to
+ * `externalReferenceArtifactWriter.ts#writeExternalReferenceArtifact`: reads
+ * one `manifest.json`, parses it, and validates it through the same
+ * `isValidExternalReferenceArtifact` structural gate the writer itself uses -
+ * never a second validator. Read-only: never mutates the file, never resolves
+ * the sibling image file's bytes (an 'imported' manifest's `image.path` field
+ * is returned as-is for the caller to resolve if it needs the bytes).
+ */
+export declare function readExternalReferenceArtifact(manifestPath: string): Promise<ReadExternalReferenceArtifactResult>;