my-frontend-observer 0.6.0 → 0.7.0

package/dist/cli.js

@@ -7,6 +7,8 @@ import { observe } from './application/observationPersistence.js';
 import { compareAndPersistFromArtifactRoots } from './application/comparisonService.js';
 import { approveAndPersistBaseline, persistPerChangeContract } from './application/frontendContractPersistenceService.js';
 import { evaluateAndPersistFromArtifactRoots } from './application/frontendContractEvaluationService.js';
+import { importExternalReference, approveExternalReference } from './application/externalReferencePersistenceService.js';
+import { evaluateReferenceCandidateFidelityFromArtifactRoots } from './application/referenceFidelityEvaluationService.js';
 const defaultIO = {
     stdout: (text) => {
         process.stdout.write(text);
@@ -34,6 +36,18 @@ Commands:
                         baseline, a per-change contract, and existing
                         before/after/comparison evidence, and persist the
                         result.
+  import-reference      Validate and persist one local external design-
+                        reference image as a new, unapproved
+                        external-reference artifact.
+  approve-reference     Explicitly approve one already-imported
+                        external-reference artifact, persisting a new
+                        approved artifact instance.
+  evaluate-reference-fidelity  Evaluate whether a candidate observation
+                        satisfies an external reference's selected design
+                        requirements, gated by reference adequacy,
+                        reference/candidate compatibility, and explicit
+                        region-to-target bindings. Prints a structured
+                        result; persists nothing.
 
 Options:
   --help     Show this help.
@@ -77,6 +91,19 @@ Options:
                             persisted into the artifact or included in the
                             observation's request identity. May be combined
                             with either --target or --targets-file.
+  --state-file <json-file>  Loads explicit, caller-declared frontend state
+                            identity from a local JSON file: { "theme":
+                            "...", "applicationState": "...",
+                            "authenticatedState": "authenticated"|
+                            "unauthenticated" } (each field independently
+                            optional; at least one required). Never inferred
+                            by the observer from screenshot pixels, CSS, DOM,
+                            or URLs - this is caller-declared metadata only,
+                            used solely for later comparability/compatibility
+                            evaluation. Relative paths resolve from the
+                            current working directory; the file path itself
+                            is never persisted into the artifact or included
+                            in the observation's request identity.
   --output <directory>      Portable, relative output location for the
                             observation artifact.
   --timeout <ms>            Overall request timeout in milliseconds.
@@ -224,6 +251,172 @@ incoherent source artifact, or a persistence failure (evaluation could not
 even be constructed), prints structured diagnostics to stderr, persists
 nothing, and exits nonzero.
 `;
+const IMPORT_REFERENCE_HELP = `Usage:
+  my-frontend-observer import-reference <image-file> --output <directory> [options]
+
+Required:
+  <image-file>           Local path to a PNG, JPEG, or WebP external design-
+                          reference image.
+  --output <directory>   Portable, relative output location for the
+                          external-reference artifact.
+
+Options:
+  --label <text>         Optional human-readable label, stored as pure
+                          provenance - never part of the reference's logical
+                          identity.
+  --supersedes <path>    Root directory of a prior external-reference
+                          artifact (imported or approved) that this import
+                          explicitly supersedes. The prior artifact is never
+                          modified.
+  --regions-file <json-file>  Local JSON file of the form { "regions": [...] }
+                          declaring explicit, meaningful reference-image
+                          regions (id + a {x, y, width, height} rectangle in
+                          reference-image pixels, origin at the image's
+                          top-left corner). Optional - a reference imported
+                          without this flag behaves exactly as in v0.7 Prompt
+                          1. Region content participates in the reference's
+                          logical identity; the file path itself never does.
+  --requirements-file <json-file>  Local JSON file of the form
+                          { "requirements": [...] } declaring explicit,
+                          user-selected design requirements over the regions
+                          above - what actually matters for later candidate
+                          evaluation, never inferred merely because a region
+                          property/relationship exists. Each requirement has
+                          a "category" (requested | expected-dependent |
+                          protected | preserved - "unexpected" is never
+                          authorable), a "subject" (a region property, a
+                          region-to-region relationship, or a derived
+                          two-region measurement), and - for property/
+                          measurement subjects - a "tolerance" (exact |
+                          absolute-reference-px | percent; relationship
+                          subjects must omit tolerance). Requires --regions-
+                          file (or an already-present region set) supplying
+                          every region a requirement refers to. Optional -
+                          a reference imported without this flag behaves
+                          exactly as in v0.7 Prompt 1/2. Requirement content
+                          participates in the reference's logical identity.
+  --applicability-file <json-file>  Local JSON file declaring the runtime
+                          frontend state this reference is intended to
+                          represent: { "viewport": { "width", "height" },
+                          "theme": "...", "applicationState": "...",
+                          "authenticatedState": "authenticated"|
+                          "unauthenticated" } (each field independently
+                          optional; at least one required). "viewport" here
+                          is the CSS-pixel runtime viewport the design
+                          represents - distinct from the reference image's
+                          own pixel dimensions, which are never assumed
+                          equal. Never inferred from the image - caller-
+                          declared metadata only, used for later reference/
+                          candidate compatibility evaluation (see
+                          docs/CONTRACTS.md "v0.7 Prompt 4"). Optional - a
+                          reference imported without this flag behaves
+                          exactly as in v0.7 Prompt 1/2/3. Applicability
+                          content participates in the reference's logical
+                          identity.
+  --help                 Show this help.
+
+Detects the image format from its header bytes only (never from the file
+extension), reads its pixel dimensions from the same bounded header bytes
+(never decoding pixel data), and persists a new external-reference artifact
+in the "imported" lifecycle state - importing never approves it. On success,
+prints a concise result (including the accepted region/requirement counts,
+the resulting reference-side requirement adequacy: adequate, partial, or
+inadequate, and whether applicability was declared) and exits 0. On an
+unreadable file, an unsupported or undetectable format, invalid/out-of-bound
+dimensions, an over-limit file size, an unresolvable --supersedes target, an
+invalid region (missing/duplicate/malformed id, non-finite/negative/zero
+geometry, a region extending outside the image, or more than the bounded
+maximum region count), an invalid requirement (unsupported category/
+property/measurement/relationship, a tolerance that is missing/inapplicable/
+out of bounds, a reference to an unknown region id, a duplicate requirement
+subject, or more than the bounded maximum requirement count), or invalid
+applicability (an out-of-bound viewport, an invalid state label, an
+unsupported authenticatedState value, or an empty applicability object),
+prints structured diagnostics to stderr and exits nonzero.
+`;
+const APPROVE_REFERENCE_HELP = `Usage:
+  my-frontend-observer approve-reference --reference <external-reference-artifact-root> --output <directory> [options]
+
+Required:
+  --reference <path>     Root directory of the already-imported
+                          external-reference artifact (the directory
+                          containing its manifest.json) to approve.
+  --output <directory>   Portable, relative output location for the newly
+                          persisted approved artifact.
+
+Options:
+  --supersedes <path>    Root directory of a prior external-reference
+                          artifact (imported or approved) that this approval
+                          explicitly supersedes. The prior artifact is never
+                          modified.
+  --help                 Show this help.
+
+This is the only explicit reference-approval act in the observer - approval
+is never inferred from a successful import or from any later fidelity
+evaluation. Approving persists a brand-new artifact instance (a fresh
+referenceId sharing the imported artifact's referenceRequestId) that carries
+a reference back to the imported artifact's image rather than a second copy
+of its bytes; the imported artifact's own manifest is never modified. Any
+regions, requirements, and applicability already declared on the imported
+artifact are carried forward unchanged (not re-validated against new input,
+not re-derived) - approval never adds, removes, or edits regions,
+requirements, or applicability. Only a reference currently in the "imported"
+lifecycle state can be approved. On success, prints a concise result
+(including the carried-forward region/requirement counts, reference-side
+requirement adequacy, and whether applicability was declared) and exits 0.
+On an unreadable/malformed --reference target, a target that is not in the
+"imported" state, an unresolvable --supersedes target, or a persistence
+failure, prints structured diagnostics to stderr and exits nonzero.
+`;
+const EVALUATE_REFERENCE_FIDELITY_HELP = `Usage:
+  my-frontend-observer evaluate-reference-fidelity --reference <external-reference-artifact-root> --candidate <observation-artifact-root> [options]
+
+Required:
+  --reference <path>   Root directory of an already-imported or already-
+                        approved external-reference artifact (the directory
+                        containing its manifest.json).
+  --candidate <path>   Root directory of the already-persisted candidate
+                        observation artifact to evaluate against it.
+
+Options:
+  --bindings-file <json-file>  Local JSON file of the form
+                        { "bindings": [ { "referenceRegion": "...",
+                        "runtimeTarget": "..." } ] } declaring which stable
+                        observer runtime target (a configured target name -
+                        see "observe" --target/--targets-file) explicitly
+                        corresponds to each reference region a selected
+                        requirement depends on. Never inferred from
+                        geometry, matching names, or source code - a
+                        binding exists only because this file declares it.
+                        Optional - omitting it (or supplying an empty
+                        "bindings" array) evaluates with no bindings at
+                        all, so every requirement whose subject depends on
+                        a reference region becomes "unavailable".
+  --enforce  Make a FAIL fidelity result produce a nonzero process exit
+             status. A FAIL result is always printed identically with or
+             without this flag - it changes only the process exit code,
+             never the evaluation's content. Has no effect on a
+             "not-evaluated" result (a reference-adequacy or compatibility
+             blocker is never treated as a design mismatch).
+  --help     Show this help.
+
+This command never launches a browser, never re-resolves targets, and
+never recomputes reference regions/requirements/adequacy, compatibility, or
+bindings - it reads the already-persisted reference and candidate exactly
+as given, evaluates the supplied binding declarations, and evaluates every
+one of the reference's selected requirements exactly once. It persists
+nothing: the result exists only for this invocation. On success, prints a
+concise result (reference-side adequacy, compatibility state, the overall
+fidelity state - "not-evaluated"/"pass"/"fail" - and a pass/fail/unavailable
+requirement breakdown) and exits 0, unless --enforce is given and the
+fidelity state is "fail", in which case it exits nonzero. A "not-evaluated"
+result (reference adequacy inadequate, or reference/candidate
+incompatible) is a successful, structured evaluation outcome, never an
+execution error - it always exits 0. On invalid syntax, an unreadable/
+malformed --reference or --candidate target, a malformed --bindings-file,
+or an invalid/out-of-bound binding declaration, prints structured
+diagnostics to stderr and exits nonzero.
+`;
 function parseViewport(raw) {
     const match = /^(\d+)x(\d+)$/.exec(raw);
     if (!match)
@@ -250,6 +443,8 @@ function parseObserveArgs(argv) {
     let targetsFileFlagCount = 0;
     let scrollScenarioFilePath;
     let scrollScenarioFileFlagCount = 0;
+    let stateFilePath;
+    let stateFileFlagCount = 0;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         switch (arg) {
@@ -306,6 +501,20 @@ function parseObserveArgs(argv) {
                 }
                 break;
             }
+            case '--state-file': {
+                const value = argv[(i += 1)];
+                stateFileFlagCount += 1;
+                if (value === undefined) {
+                    errors.push('--state-file requires a file path argument');
+                }
+                else if (stateFileFlagCount > 1) {
+                    errors.push('--state-file may only be specified once');
+                }
+                else {
+                    stateFilePath = value;
+                }
+                break;
+            }
             case '--output':
                 outputLocation = argv[(i += 1)];
                 break;
@@ -343,9 +552,169 @@ function parseObserveArgs(argv) {
         raw,
         ...(targetsFilePath === undefined ? {} : { targetsFilePath }),
         ...(scrollScenarioFilePath === undefined ? {} : { scrollScenarioFilePath }),
+        ...(stateFilePath === undefined ? {} : { stateFilePath }),
     };
 }
 const TARGETS_FILE_ALLOWED_ROOT_FIELDS = new Set(['targets']);
+const REGIONS_FILE_ALLOWED_ROOT_FIELDS = new Set(['regions']);
+/**
+ * CLI/input-boundary-only responsibility, mirroring loadTargetsFile exactly:
+ * read one local JSON file, validate only the root wrapper (object root,
+ * exactly the "regions" field, nothing else), and hand the still-unvalidated
+ * `regions` value to the existing domain validators
+ * (isValidReferenceRegions, called inside importExternalReference) - region
+ * geometry/ID rules stay owned there, never duplicated here. The file path
+ * itself is never returned beyond this function, so it can never reach the
+ * persisted artifact or its identity.
+ */
+function loadRegionsFile(filePath) {
+    let rawText;
+    try {
+        rawText = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--regions-file could not be read: ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--regions-file is not valid JSON: ${message}` };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, error: '--regions-file root must be a JSON object' };
+    }
+    const record = parsed;
+    const unknownFields = Object.keys(record).filter((key) => !REGIONS_FILE_ALLOWED_ROOT_FIELDS.has(key));
+    if (unknownFields.length > 0) {
+        return { ok: false, error: `--regions-file has unsupported top-level field(s): ${unknownFields.join(', ')}` };
+    }
+    if (!('regions' in record)) {
+        return { ok: false, error: '--regions-file must have a "regions" property' };
+    }
+    return { ok: true, regions: record.regions };
+}
+const REQUIREMENTS_FILE_ALLOWED_ROOT_FIELDS = new Set(['requirements']);
+/**
+ * CLI/input-boundary-only responsibility, mirroring loadRegionsFile exactly:
+ * read one local JSON file, validate only the root wrapper (object root,
+ * exactly the "requirements" field, nothing else), and hand the
+ * still-unvalidated `requirements` value to the existing domain validators
+ * (isValidRawReferenceRequirement/isValidReferenceRequirements, called
+ * inside importExternalReference) - requirement category/subject/tolerance
+ * rules stay owned there, never duplicated here. The file path itself is
+ * never returned beyond this function, so it can never reach the persisted
+ * artifact or its identity.
+ */
+function loadRequirementsFile(filePath) {
+    let rawText;
+    try {
+        rawText = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--requirements-file could not be read: ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--requirements-file is not valid JSON: ${message}` };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, error: '--requirements-file root must be a JSON object' };
+    }
+    const record = parsed;
+    const unknownFields = Object.keys(record).filter((key) => !REQUIREMENTS_FILE_ALLOWED_ROOT_FIELDS.has(key));
+    if (unknownFields.length > 0) {
+        return { ok: false, error: `--requirements-file has unsupported top-level field(s): ${unknownFields.join(', ')}` };
+    }
+    if (!('requirements' in record)) {
+        return { ok: false, error: '--requirements-file must have a "requirements" property' };
+    }
+    return { ok: true, requirements: record.requirements };
+}
+/**
+ * CLI/input-boundary-only responsibility, mirroring `loadStateFile`/
+ * `loadScrollScenarioFile`: read one local JSON file and validate only the
+ * root shape (plain, non-array object) - the file supplies
+ * `ExternalReferenceApplicability` directly (no wrapper field), so there is
+ * no root-field allowlist to enforce here. Every applicability rule
+ * (viewport bounds, state-label pattern, authenticatedState enum) stays
+ * owned by `isValidExternalReferenceApplicability`, not duplicated here. The
+ * file path itself is never returned beyond this function, so it can never
+ * reach the persisted artifact or its identity.
+ */
+function loadApplicabilityFile(filePath) {
+    let rawText;
+    try {
+        rawText = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--applicability-file could not be read: ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--applicability-file is not valid JSON: ${message}` };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, error: '--applicability-file root must be a JSON object' };
+    }
+    return { ok: true, applicability: parsed };
+}
+const BINDINGS_FILE_ALLOWED_ROOT_FIELDS = new Set(['bindings']);
+/**
+ * CLI/input-boundary-only responsibility, mirroring `loadRegionsFile`/
+ * `loadRequirementsFile` exactly: read one local JSON file, validate only
+ * the root wrapper (object root, exactly the "bindings" property, nothing
+ * else), and hand the still-unvalidated `bindings` value to the existing
+ * domain validator (`isValidReferenceRuntimeBindingDeclarations`, called
+ * inside `evaluateReferenceCandidateFidelity`) - every binding-declaration
+ * rule (shape, bounds, reference-region existence, duplicate/conflict)
+ * stays owned there, never duplicated here. The file path itself is never
+ * returned beyond this function, so it can never reach the evaluation
+ * result or any identity.
+ */
+function loadBindingsFile(filePath) {
+    let rawText;
+    try {
+        rawText = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--bindings-file could not be read: ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--bindings-file is not valid JSON: ${message}` };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, error: '--bindings-file root must be a JSON object' };
+    }
+    const record = parsed;
+    const unknownFields = Object.keys(record).filter((key) => !BINDINGS_FILE_ALLOWED_ROOT_FIELDS.has(key));
+    if (unknownFields.length > 0) {
+        return { ok: false, error: `--bindings-file has unsupported top-level field(s): ${unknownFields.join(', ')}` };
+    }
+    if (!('bindings' in record)) {
+        return { ok: false, error: '--bindings-file must have a "bindings" property' };
+    }
+    return { ok: true, bindings: record.bindings };
+}
 /**
  * CLI/input-boundary-only responsibility: read one local JSON file, validate
  * only the root wrapper this file format owns (object root, exactly the
@@ -420,6 +789,39 @@ function loadScrollScenarioFile(filePath) {
     }
     return { ok: true, scenario: parsed };
 }
+/**
+ * CLI/input-boundary-only responsibility, mirroring `loadScrollScenarioFile`
+ * exactly: read one local JSON file and validate only the root shape (plain,
+ * non-array object) - the file supplies the value of
+ * `RawObservationRequest.explicitState` directly (no wrapper field), so
+ * there is no root-field allowlist to enforce here. Every state rule
+ * (supported dimension keys, label pattern, authenticatedState enum) stays
+ * owned by `normalizeRequest()`/`isValidExplicitStateDimensions`, not
+ * duplicated here. The file path itself is never returned to the caller
+ * beyond this function, so it can never reach the persisted request/artifact.
+ */
+function loadStateFile(filePath) {
+    let rawText;
+    try {
+        rawText = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--state-file could not be read: ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--state-file is not valid JSON: ${message}` };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, error: '--state-file root must be a JSON object' };
+    }
+    return { ok: true, state: parsed };
+}
 /** CLI-syntax-only parsing, mirroring `parseObserveArgs`: shape/presence/duplication errors only. Comparison-config semantics stay owned by the existing domain validator. */
 function parseCompareArgs(argv) {
     const errors = [];
@@ -798,6 +1200,248 @@ function parseEvaluateContractArgs(argv) {
         enforce,
     };
 }
+/** CLI-syntax-only parsing, mirroring `parseApproveBaselineArgs`. The image file path is the one positional argument. */
+function parseImportReferenceArgs(argv) {
+    const errors = [];
+    let imageFilePath;
+    let outputLocation;
+    let outputFlagCount = 0;
+    let label;
+    let labelFlagCount = 0;
+    let supersedesReferenceRoot;
+    let supersedesFlagCount = 0;
+    let regionsFilePath;
+    let regionsFileFlagCount = 0;
+    let requirementsFilePath;
+    let requirementsFileFlagCount = 0;
+    let applicabilityFilePath;
+    let applicabilityFileFlagCount = 0;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--output': {
+                const value = argv[(i += 1)];
+                outputFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--output requires a directory argument');
+                else if (outputFlagCount > 1)
+                    errors.push('--output may only be specified once');
+                else
+                    outputLocation = value;
+                break;
+            }
+            case '--label': {
+                const value = argv[(i += 1)];
+                labelFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--label requires a text argument');
+                else if (labelFlagCount > 1)
+                    errors.push('--label may only be specified once');
+                else
+                    label = value;
+                break;
+            }
+            case '--supersedes': {
+                const value = argv[(i += 1)];
+                supersedesFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--supersedes requires a path argument');
+                else if (supersedesFlagCount > 1)
+                    errors.push('--supersedes may only be specified once');
+                else
+                    supersedesReferenceRoot = value;
+                break;
+            }
+            case '--regions-file': {
+                const value = argv[(i += 1)];
+                regionsFileFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--regions-file requires a file path argument');
+                else if (regionsFileFlagCount > 1)
+                    errors.push('--regions-file may only be specified once');
+                else
+                    regionsFilePath = value;
+                break;
+            }
+            case '--requirements-file': {
+                const value = argv[(i += 1)];
+                requirementsFileFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--requirements-file requires a file path argument');
+                else if (requirementsFileFlagCount > 1)
+                    errors.push('--requirements-file may only be specified once');
+                else
+                    requirementsFilePath = value;
+                break;
+            }
+            case '--applicability-file': {
+                const value = argv[(i += 1)];
+                applicabilityFileFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--applicability-file requires a file path argument');
+                else if (applicabilityFileFlagCount > 1)
+                    errors.push('--applicability-file may only be specified once');
+                else
+                    applicabilityFilePath = value;
+                break;
+            }
+            default:
+                if (arg === undefined)
+                    break;
+                if (arg.startsWith('--'))
+                    errors.push(`unrecognized argument: ${arg}`);
+                else if (imageFilePath !== undefined)
+                    errors.push('only one image-file argument may be given');
+                else
+                    imageFilePath = arg;
+        }
+    }
+    if (imageFilePath === undefined)
+        errors.push('an image-file argument is required');
+    if (outputLocation === undefined)
+        errors.push('--output is required');
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return {
+        ok: true,
+        imageFilePath: imageFilePath,
+        outputLocation: outputLocation,
+        ...(label === undefined ? {} : { label }),
+        ...(supersedesReferenceRoot === undefined ? {} : { supersedesReferenceRoot }),
+        ...(regionsFilePath === undefined ? {} : { regionsFilePath }),
+        ...(requirementsFilePath === undefined ? {} : { requirementsFilePath }),
+        ...(applicabilityFilePath === undefined ? {} : { applicabilityFilePath }),
+    };
+}
+/** CLI-syntax-only parsing, mirroring `parseApproveBaselineArgs`. */
+function parseApproveReferenceArgs(argv) {
+    const errors = [];
+    let referenceRoot;
+    let referenceFlagCount = 0;
+    let outputLocation;
+    let outputFlagCount = 0;
+    let supersedesReferenceRoot;
+    let supersedesFlagCount = 0;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--reference': {
+                const value = argv[(i += 1)];
+                referenceFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--reference requires a path argument');
+                else if (referenceFlagCount > 1)
+                    errors.push('--reference may only be specified once');
+                else
+                    referenceRoot = value;
+                break;
+            }
+            case '--output': {
+                const value = argv[(i += 1)];
+                outputFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--output requires a directory argument');
+                else if (outputFlagCount > 1)
+                    errors.push('--output may only be specified once');
+                else
+                    outputLocation = value;
+                break;
+            }
+            case '--supersedes': {
+                const value = argv[(i += 1)];
+                supersedesFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--supersedes requires a path argument');
+                else if (supersedesFlagCount > 1)
+                    errors.push('--supersedes may only be specified once');
+                else
+                    supersedesReferenceRoot = value;
+                break;
+            }
+            default:
+                errors.push(`unrecognized argument: ${arg}`);
+        }
+    }
+    if (referenceRoot === undefined)
+        errors.push('--reference is required');
+    if (outputLocation === undefined)
+        errors.push('--output is required');
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return {
+        ok: true,
+        referenceRoot: referenceRoot,
+        outputLocation: outputLocation,
+        ...(supersedesReferenceRoot === undefined ? {} : { supersedesReferenceRoot }),
+    };
+}
+/** CLI-syntax-only parsing, mirroring `parseEvaluateContractArgs`'s `--enforce` handling exactly. */
+function parseEvaluateReferenceFidelityArgs(argv) {
+    const errors = [];
+    let referenceRoot;
+    let referenceFlagCount = 0;
+    let candidateRoot;
+    let candidateFlagCount = 0;
+    let bindingsFilePath;
+    let bindingsFileFlagCount = 0;
+    let enforce = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--reference': {
+                const value = argv[(i += 1)];
+                referenceFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--reference requires a path argument');
+                else if (referenceFlagCount > 1)
+                    errors.push('--reference may only be specified once');
+                else
+                    referenceRoot = value;
+                break;
+            }
+            case '--candidate': {
+                const value = argv[(i += 1)];
+                candidateFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--candidate requires a path argument');
+                else if (candidateFlagCount > 1)
+                    errors.push('--candidate may only be specified once');
+                else
+                    candidateRoot = value;
+                break;
+            }
+            case '--bindings-file': {
+                const value = argv[(i += 1)];
+                bindingsFileFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--bindings-file requires a file path argument');
+                else if (bindingsFileFlagCount > 1)
+                    errors.push('--bindings-file may only be specified once');
+                else
+                    bindingsFilePath = value;
+                break;
+            }
+            case '--enforce':
+                enforce = true;
+                break;
+            default:
+                errors.push(`unrecognized argument: ${arg}`);
+        }
+    }
+    if (referenceRoot === undefined)
+        errors.push('--reference is required');
+    if (candidateRoot === undefined)
+        errors.push('--candidate is required');
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return {
+        ok: true,
+        referenceRoot: referenceRoot,
+        candidateRoot: candidateRoot,
+        ...(bindingsFilePath === undefined ? {} : { bindingsFilePath }),
+        enforce,
+    };
+}
 function formatDiagnostic(diagnostic) {
     const target = diagnostic.targetName === undefined ? '' : ` (target: ${diagnostic.targetName})`;
     return `[${diagnostic.code}] ${diagnostic.message}${target}`;
@@ -835,6 +1479,15 @@ async function runObserveCommand(argv, io) {
         }
         raw = { ...raw, scrollScenario: loaded.scenario };
     }
+    if (parsedArgs.stateFilePath !== undefined) {
+        const loaded = loadStateFile(parsedArgs.stateFilePath);
+        if (!loaded.ok) {
+            io.stderr(`error: ${loaded.error}\n`);
+            io.stderr(OBSERVE_HELP);
+            return 1;
+        }
+        raw = { ...raw, explicitState: loaded.state };
+    }
     const normalized = normalizeRequest(raw);
     if (!normalized.ok) {
         for (const diagnostic of normalized.diagnostics)
@@ -1023,6 +1676,188 @@ async function runEvaluateContractCommand(argv, io) {
         return 1;
     return 0;
 }
+/**
+ * Thin orchestration only: parse args, read the local image file's raw
+ * bytes, then delegate to the existing `importExternalReference` application
+ * function exactly once. No format/dimension validation lives here - see
+ * `src/domain/externalReferenceImage.ts`.
+ */
+async function runImportReferenceCommand(argv, io) {
+    if (argv.includes('--help')) {
+        io.stdout(IMPORT_REFERENCE_HELP);
+        return 0;
+    }
+    const parsedArgs = parseImportReferenceArgs(argv);
+    if (!parsedArgs.ok) {
+        for (const error of parsedArgs.errors)
+            io.stderr(`error: ${error}\n`);
+        io.stderr(IMPORT_REFERENCE_HELP);
+        return 1;
+    }
+    let imageBytes;
+    try {
+        imageBytes = readFileSync(parsedArgs.imageFilePath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        io.stderr(`error: could not read image file "${parsedArgs.imageFilePath}": ${message}\n`);
+        io.stderr(IMPORT_REFERENCE_HELP);
+        return 1;
+    }
+    let regions;
+    if (parsedArgs.regionsFilePath !== undefined) {
+        const loaded = loadRegionsFile(parsedArgs.regionsFilePath);
+        if (!loaded.ok) {
+            io.stderr(`error: ${loaded.error}\n`);
+            io.stderr(IMPORT_REFERENCE_HELP);
+            return 1;
+        }
+        // CLI boundary owns file-read/root-wrapper syntax only; region content/geometry validation is owned by isValidReferenceRegions, called inside importExternalReference.
+        regions = loaded.regions;
+    }
+    let requirements;
+    if (parsedArgs.requirementsFilePath !== undefined) {
+        const loaded = loadRequirementsFile(parsedArgs.requirementsFilePath);
+        if (!loaded.ok) {
+            io.stderr(`error: ${loaded.error}\n`);
+            io.stderr(IMPORT_REFERENCE_HELP);
+            return 1;
+        }
+        // CLI boundary owns file-read/root-wrapper syntax only; requirement category/subject/tolerance validation is owned by isValidRawReferenceRequirement/isValidReferenceRequirements, called inside importExternalReference.
+        requirements = loaded.requirements;
+    }
+    let applicability;
+    if (parsedArgs.applicabilityFilePath !== undefined) {
+        const loaded = loadApplicabilityFile(parsedArgs.applicabilityFilePath);
+        if (!loaded.ok) {
+            io.stderr(`error: ${loaded.error}\n`);
+            io.stderr(IMPORT_REFERENCE_HELP);
+            return 1;
+        }
+        // CLI boundary owns file-read syntax only; applicability semantics are owned by isValidExternalReferenceApplicability, called inside importExternalReference.
+        applicability = loaded.applicability;
+    }
+    // Exactly one application import attempt: format/dimension validation, an optional region-set validation, an optional requirement-set validation, an optional applicability validation, an optional supersession-target read, persisted at most once.
+    const result = await importExternalReference(imageBytes, {
+        outputLocation: parsedArgs.outputLocation,
+        ...(parsedArgs.label === undefined ? {} : { label: parsedArgs.label }),
+        ...(parsedArgs.supersedesReferenceRoot === undefined ? {} : { supersedesReferenceRoot: parsedArgs.supersedesReferenceRoot }),
+        ...(regions === undefined ? {} : { regions }),
+        ...(requirements === undefined ? {} : { requirements }),
+        ...(applicability === undefined ? {} : { applicability }),
+    });
+    if (!result.ok) {
+        for (const diagnostic of result.diagnostics)
+            io.stderr(`${formatDiagnostic(diagnostic)}\n`);
+        return 1;
+    }
+    io.stdout(`Reference: ${result.referenceId}\n`);
+    io.stdout(`State: imported\n`);
+    io.stdout(`Artifact: ${result.artifactRoot}\n`);
+    io.stdout(`Image: ${result.imagePath}\n`);
+    io.stdout(`Regions: ${result.regionCount}\n`);
+    io.stdout(`Requirements: ${result.requirementCount}\n`);
+    io.stdout(`Applicability: ${result.hasApplicability ? 'declared' : 'none'}\n`);
+    io.stdout(`Adequacy: ${result.adequacy.status}\n`);
+    return 0;
+}
+/**
+ * Thin orchestration only: parse args, then delegate to the existing
+ * `approveExternalReference` application function exactly once. This is the
+ * only command in the observer that approves an external reference.
+ */
+async function runApproveReferenceCommand(argv, io) {
+    if (argv.includes('--help')) {
+        io.stdout(APPROVE_REFERENCE_HELP);
+        return 0;
+    }
+    const parsedArgs = parseApproveReferenceArgs(argv);
+    if (!parsedArgs.ok) {
+        for (const error of parsedArgs.errors)
+            io.stderr(`error: ${error}\n`);
+        io.stderr(APPROVE_REFERENCE_HELP);
+        return 1;
+    }
+    // Exactly one application approval attempt: one reference read, an optional supersession-target read, persisted at most once.
+    const result = await approveExternalReference(parsedArgs.referenceRoot, {
+        outputLocation: parsedArgs.outputLocation,
+        ...(parsedArgs.supersedesReferenceRoot === undefined ? {} : { supersedesReferenceRoot: parsedArgs.supersedesReferenceRoot }),
+    });
+    if (!result.ok) {
+        for (const diagnostic of result.diagnostics)
+            io.stderr(`${formatDiagnostic(diagnostic)}\n`);
+        return 1;
+    }
+    io.stdout(`Reference: ${result.referenceId}\n`);
+    io.stdout(`State: approved\n`);
+    io.stdout(`Artifact: ${result.artifactRoot}\n`);
+    io.stdout(`Regions: ${result.regionCount}\n`);
+    io.stdout(`Requirements: ${result.requirementCount}\n`);
+    io.stdout(`Adequacy: ${result.adequacy.status}\n`);
+    io.stdout(`Applicability: ${result.hasApplicability ? 'declared' : 'none'}\n`);
+    return 0;
+}
+/**
+ * Thin orchestration only: parse args, load the optional bindings file
+ * (syntax/root-shape only - every binding-declaration rule stays owned by
+ * `isValidReferenceRuntimeBindingDeclarations`, called inside the domain
+ * evaluator), then delegate to the existing
+ * `evaluateReferenceCandidateFidelityFromArtifactRoots` application function
+ * exactly once. No adequacy/compatibility/binding/tolerance/coordinate-
+ * mapping/relationship logic lives here - see
+ * `src/domain/externalReferenceFidelity.ts`. `--enforce` is applied only
+ * after the evaluation has already been computed: it selects the process
+ * exit status for an already-final "fail" fidelity state and never affects
+ * the evaluation's content. Persists nothing.
+ */
+async function runEvaluateReferenceFidelityCommand(argv, io) {
+    if (argv.includes('--help')) {
+        io.stdout(EVALUATE_REFERENCE_FIDELITY_HELP);
+        return 0;
+    }
+    const parsedArgs = parseEvaluateReferenceFidelityArgs(argv);
+    if (!parsedArgs.ok) {
+        for (const error of parsedArgs.errors)
+            io.stderr(`error: ${error}\n`);
+        io.stderr(EVALUATE_REFERENCE_FIDELITY_HELP);
+        return 1;
+    }
+    let bindings = [];
+    if (parsedArgs.bindingsFilePath !== undefined) {
+        const loaded = loadBindingsFile(parsedArgs.bindingsFilePath);
+        if (!loaded.ok) {
+            io.stderr(`error: ${loaded.error}\n`);
+            io.stderr(EVALUATE_REFERENCE_FIDELITY_HELP);
+            return 1;
+        }
+        // CLI boundary owns file-read/root-wrapper syntax only; binding-declaration shape/bounds/existence/conflict validation is owned by isValidReferenceRuntimeBindingDeclarations, called inside evaluateReferenceCandidateFidelity.
+        bindings = loaded.bindings;
+    }
+    // Exactly one application evaluation attempt: reads reference/candidate once each, calls the canonical evaluator exactly once.
+    const result = await evaluateReferenceCandidateFidelityFromArtifactRoots(parsedArgs.referenceRoot, parsedArgs.candidateRoot, bindings);
+    if (!result.ok) {
+        for (const diagnostic of result.diagnostics)
+            io.stderr(`${formatDiagnostic(diagnostic)}\n`);
+        return 1;
+    }
+    const { evaluation } = result;
+    const passCount = evaluation.requirementResults.filter((r) => r.status === 'pass').length;
+    const failCount = evaluation.requirementResults.filter((r) => r.status === 'fail').length;
+    const unavailableCount = evaluation.requirementResults.filter((r) => r.status === 'unavailable').length;
+    io.stdout(`Reference: ${evaluation.referenceId}\n`);
+    io.stdout(`Candidate: ${evaluation.candidateObservationId}\n`);
+    io.stdout(`Adequacy: ${evaluation.adequacy.status}\n`);
+    if (evaluation.compatibility !== undefined)
+        io.stdout(`Compatibility: ${evaluation.compatibility.state}\n`);
+    io.stdout(`State: ${evaluation.state}\n`);
+    if (evaluation.blockedBy !== undefined)
+        io.stdout(`Blocked by: ${evaluation.blockedBy}\n`);
+    io.stdout(`Requirements: ${evaluation.requirementResults.length} (pass: ${passCount}, fail: ${failCount}, unavailable: ${unavailableCount})\n`);
+    io.stdout(`Enforced: ${parsedArgs.enforce ? 'yes' : 'no'}\n`);
+    if (parsedArgs.enforce && evaluation.state === 'fail')
+        return 1;
+    return 0;
+}
 /** Testable CLI entry point: pure function of argv (+ injectable IO), no direct process.exit. */
 export async function runCli(argv, io = defaultIO) {
     const [command, ...rest] = argv;
@@ -1053,6 +1888,15 @@ export async function runCli(argv, io = defaultIO) {
     if (command === 'evaluate-contract') {
         return runEvaluateContractCommand(rest, io);
     }
+    if (command === 'import-reference') {
+        return runImportReferenceCommand(rest, io);
+    }
+    if (command === 'approve-reference') {
+        return runApproveReferenceCommand(rest, io);
+    }
+    if (command === 'evaluate-reference-fidelity') {
+        return runEvaluateReferenceFidelityCommand(rest, io);
+    }
     io.stderr(`error: unrecognized command "${command}"\n`);
     io.stderr(TOP_LEVEL_HELP);
     return 1;