taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/dist/application/journey/journey-promoter.js

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import { GenerationMetaSchema } from "../../domain/generation.js";
+import { ResolvedJourneyPathSchema } from "../../domain/journey-composition.js";
+import { JourneySchema } from "../../domain/journey.js";
+import { TapHoundReportSchema } from "../../domain/report.js";
+import { GENERATIONS_DIR } from "../../domain/workspace.js";
+export class JourneyPromotionError extends Error {
+    code;
+    name = "JourneyPromotionError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function parseJson(bytes) {
+    return JSON.parse(bytes.toString("utf8"));
+}
+function sameJson(left, right) {
+    return (JSON.stringify(parseJson(left)) === JSON.stringify(parseJson(right)));
+}
+function serialize(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+const VERIFIED_JOURNEY_EVIDENCE = "verified/journey.json";
+export class JourneyPromoter {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    promote = async (input) => {
+        const journeyPath = ResolvedJourneyPathSchema.parse(input.journeyPath);
+        const metaPath = `${journeyPath.slice(0, -".json".length)}.meta.json`;
+        let journeyBytes;
+        try {
+            journeyBytes = await this.dependencies.store.read({
+                projectRoot: input.projectRoot,
+                relativePath: journeyPath
+            });
+        }
+        catch {
+            throw new JourneyPromotionError("JOURNEY_NOT_FOUND", `Journey is not readable: ${journeyPath}`);
+        }
+        try {
+            JourneySchema.parse(parseJson(journeyBytes));
+        }
+        catch (error) {
+            throw new JourneyPromotionError("JOURNEY_INVALID", `Journey does not match the Journey schema: ${journeyPath}`, { cause: error });
+        }
+        const metaBytes = await this.dependencies.store.readJourneyMeta({
+            projectRoot: input.projectRoot,
+            journeyPath
+        });
+        if (metaBytes === null) {
+            throw new JourneyPromotionError("META_MISSING", `Journey has no generation meta sidecar: ${metaPath}`);
+        }
+        let meta;
+        try {
+            meta = GenerationMetaSchema.parse(parseJson(metaBytes));
+        }
+        catch (error) {
+            throw new JourneyPromotionError("META_INVALID", `Journey meta sidecar is invalid: ${metaPath}`, { cause: error });
+        }
+        if (meta.status === "promoted") {
+            throw new JourneyPromotionError("JOURNEY_ALREADY_PROMOTED", `Journey is already promoted: ${journeyPath}`);
+        }
+        const bundleRoot = `${GENERATIONS_DIR}/${meta.generationId}`;
+        const reportPath = `${bundleRoot}/${meta.verification.reportPath}`;
+        let reportBytes;
+        try {
+            reportBytes = await this.dependencies.store.read({
+                projectRoot: input.projectRoot,
+                relativePath: reportPath
+            });
+        }
+        catch {
+            throw new JourneyPromotionError("EVIDENCE_MISSING", `Verification evidence is missing: ${reportPath}`);
+        }
+        if (sha256(reportBytes) !== meta.verification.reportSha256) {
+            throw new JourneyPromotionError("EVIDENCE_HASH_MISMATCH", `Verification evidence no longer matches the promoted hash: ${reportPath}`);
+        }
+        const report = TapHoundReportSchema.parse(parseJson(reportBytes));
+        if (report.runId !== meta.verification.runId) {
+            throw new JourneyPromotionError("EVIDENCE_HASH_MISMATCH", "Verification evidence run does not match the generation meta");
+        }
+        let verifiedJourneyBytes;
+        try {
+            verifiedJourneyBytes = await this.dependencies.store.read({
+                projectRoot: input.projectRoot,
+                relativePath: `${bundleRoot}/${VERIFIED_JOURNEY_EVIDENCE}`
+            });
+        }
+        catch {
+            throw new JourneyPromotionError("EVIDENCE_MISSING", `Verified Journey evidence is missing: ${bundleRoot}`);
+        }
+        if (!sameJson(journeyBytes, verifiedJourneyBytes)) {
+            throw new JourneyPromotionError("JOURNEY_MODIFIED", `Journey no longer matches its verified evidence: ${journeyPath}`);
+        }
+        const promotedAt = input.now.toISOString();
+        const promoted = GenerationMetaSchema.parse({
+            ...meta,
+            status: "promoted",
+            promotion: {
+                promotedAt,
+                reason: input.reason
+            }
+        });
+        await this.dependencies.store.writeText({
+            projectRoot: input.projectRoot,
+            relativePath: metaPath,
+            content: serialize(promoted)
+        });
+        return {
+            status: "promoted",
+            journeyPath,
+            metaPath,
+            generationId: meta.generationId,
+            promotedAt
+        };
+    };
+}

package/dist/application/journey/journey-resolver.d.ts

@@ -0,0 +1,42 @@
+import { type JourneyResolutionManifest } from "../../domain/journey-composition.js";
+import { type Journey } from "../../domain/journey.js";
+import type { JourneyCompositionStore } from "../../ports/journey-composition-store.js";
+export type JourneyCompositionErrorCode = "SOURCE_INVALID" | "FLOW_INVALID" | "FLOW_NOT_FOUND" | "FLOW_CYCLE" | "FLOW_DUPLICATE" | "ACTIVITY_BOUNDARY_MISMATCH";
+export declare class JourneyCompositionError extends Error {
+    readonly code: JourneyCompositionErrorCode;
+    readonly name = "JourneyCompositionError";
+    constructor(code: JourneyCompositionErrorCode, message: string, options?: ErrorOptions);
+}
+export interface JourneyResolveInput {
+    projectRoot: string;
+    sourcePath: string;
+}
+export interface JourneyResolution {
+    journey: Journey;
+    manifest: JourneyResolutionManifest;
+}
+export interface FlowCatalogEntry {
+    name: string;
+    path: string;
+    status: "valid" | "invalid";
+    entryActivity?: string | undefined;
+    exitActivity?: string | undefined;
+    stepCount?: number | undefined;
+    resolutionSha256?: string | undefined;
+    failure?: {
+        code: string;
+        message: string;
+    } | undefined;
+}
+export declare class JourneyResolver {
+    private readonly store;
+    constructor(store: Pick<JourneyCompositionStore, "read" | "listFlowPaths">);
+    readonly resolve: (input: JourneyResolveInput) => Promise<JourneyResolution>;
+    readonly resolveFlow: (input: {
+        projectRoot: string;
+        name: string;
+    }) => Promise<JourneyResolution>;
+    readonly listFlows: (projectRoot: string) => Promise<FlowCatalogEntry[]>;
+    private readonly resolveDocument;
+    private readonly loadFlow;
+}

package/dist/application/journey/journey-resolver.js

@@ -0,0 +1,239 @@
+import { createHash } from "node:crypto";
+import { FlowNameSchema, FlowSchema, JourneySourcePathSchema, JourneyResolutionManifestSchema, JourneySourceSchema } from "../../domain/journey-composition.js";
+import { DEFAULT_DEVICE_ROLE, JourneySchema } from "../../domain/journey.js";
+import { FLOWS_DIR } from "../../domain/workspace.js";
+const MAX_COMPOSITION_BYTES = 1024 * 1024;
+export class JourneyCompositionError extends Error {
+    code;
+    name = "JourneyCompositionError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => [key, canonicalize(item)]));
+    }
+    return value;
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function hashCanonical(value) {
+    return sha256(JSON.stringify(canonicalize(value)));
+}
+function parseJson(bytes, label) {
+    if (bytes.byteLength > MAX_COMPOSITION_BYTES) {
+        throw new JourneyCompositionError(label === "Journey source" ? "SOURCE_INVALID" : "FLOW_INVALID", `${label} exceeds ${String(MAX_COMPOSITION_BYTES)} bytes`);
+    }
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch (error) {
+        throw new JourneyCompositionError(label === "Journey source" ? "SOURCE_INVALID" : "FLOW_INVALID", `${label} is not valid JSON`, { cause: error });
+    }
+}
+function flowPath(name) {
+    return `${FLOWS_DIR}/${FlowNameSchema.parse(name)}.json`;
+}
+function normalizedSourcePath(path) {
+    try {
+        return JourneySourcePathSchema.parse(path);
+    }
+    catch (error) {
+        throw new JourneyCompositionError("SOURCE_INVALID", "Journey source must be a normalized JSON file under .taphound/sources", { cause: error });
+    }
+}
+function assertActivityBoundaries(steps) {
+    for (let index = 1; index < steps.length; index += 1) {
+        const previous = steps[index - 1];
+        const current = steps[index];
+        if (previous !== undefined
+            && current !== undefined
+            && previous.activity.after !== current.activity.before) {
+            throw new JourneyCompositionError("ACTIVITY_BOUNDARY_MISMATCH", `Step ${String(index - 1)} ends at ${previous.activity.after}, but step ${String(index)} starts at ${current.activity.before}`);
+        }
+    }
+}
+function errorDetails(error) {
+    if (error instanceof JourneyCompositionError) {
+        return { code: error.code, message: error.message };
+    }
+    return {
+        code: "FLOW_INVALID",
+        message: error instanceof Error ? error.message : String(error)
+    };
+}
+export class JourneyResolver {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    resolve = async (input) => {
+        const sourcePath = normalizedSourcePath(input.sourcePath);
+        let sourceBytes;
+        try {
+            sourceBytes = await this.store.read({
+                projectRoot: input.projectRoot,
+                relativePath: sourcePath
+            });
+        }
+        catch (error) {
+            throw new JourneyCompositionError("SOURCE_INVALID", `Unable to read Journey source ${sourcePath}`, { cause: error });
+        }
+        let source;
+        try {
+            source = JourneySourceSchema.parse(parseJson(sourceBytes, "Journey source"));
+        }
+        catch (error) {
+            throw error instanceof JourneyCompositionError
+                ? error
+                : new JourneyCompositionError("SOURCE_INVALID", `Journey source ${sourcePath} is invalid`, { cause: error });
+        }
+        return this.resolveDocument(input.projectRoot, sourcePath, sourceBytes, source);
+    };
+    resolveFlow = async (input) => {
+        const name = FlowNameSchema.parse(input.name);
+        const path = flowPath(name);
+        const loaded = await this.loadFlow(input.projectRoot, name);
+        const source = {
+            version: 1,
+            kind: "journeySource",
+            name,
+            includes: loaded.flow.includes,
+            steps: loaded.flow.steps
+        };
+        return this.resolveDocument(input.projectRoot, path, loaded.bytes, source, name);
+    };
+    listFlows = async (projectRoot) => {
+        const paths = [...await this.store.listFlowPaths(projectRoot)].sort();
+        const entries = [];
+        for (const path of paths) {
+            try {
+                const bytes = await this.store.read({ projectRoot, relativePath: path });
+                const flow = FlowSchema.parse(parseJson(bytes, "Flow"));
+                const expectedPath = flowPath(flow.name);
+                if (path !== expectedPath) {
+                    throw new JourneyCompositionError("FLOW_INVALID", `Flow ${flow.name} must be stored at ${expectedPath}`);
+                }
+                const resolution = await this.resolveFlow({
+                    projectRoot,
+                    name: flow.name
+                });
+                entries.push({
+                    name: flow.name,
+                    path,
+                    status: "valid",
+                    entryActivity: resolution.journey.steps[0]?.activity.before,
+                    exitActivity: resolution.journey.steps.at(-1)?.activity.after,
+                    stepCount: resolution.journey.steps.length,
+                    resolutionSha256: resolution.manifest.resolutionSha256
+                });
+            }
+            catch (error) {
+                entries.push({
+                    name: path.slice(`${FLOWS_DIR}/`.length, -".json".length),
+                    path,
+                    status: "invalid",
+                    failure: errorDetails(error)
+                });
+            }
+        }
+        return entries;
+    };
+    resolveDocument = async (projectRoot, sourcePath, sourceBytes, source, rootFlowName) => {
+        const steps = [];
+        const dependencies = [];
+        const expanded = new Set();
+        const stack = [];
+        const expand = async (name) => {
+            if (stack.includes(name)) {
+                throw new JourneyCompositionError("FLOW_CYCLE", `Flow cycle detected: ${[...stack, name].join(" -> ")}`);
+            }
+            if (expanded.has(name)) {
+                throw new JourneyCompositionError("FLOW_DUPLICATE", `Flow ${name} is included more than once`);
+            }
+            stack.push(name);
+            const loaded = await this.loadFlow(projectRoot, name);
+            for (const dependency of loaded.flow.includes) {
+                await expand(dependency);
+            }
+            stack.pop();
+            expanded.add(name);
+            steps.push(...loaded.flow.steps);
+            dependencies.push({
+                name,
+                path: loaded.path,
+                sha256: sha256(loaded.bytes),
+                stepCount: loaded.flow.steps.length
+            });
+        };
+        if (rootFlowName === undefined) {
+            for (const name of source.includes) {
+                await expand(name);
+            }
+            steps.push(...source.steps);
+        }
+        else {
+            await expand(rootFlowName);
+        }
+        assertActivityBoundaries(steps);
+        const journey = JourneySchema.parse({
+            version: 2,
+            name: source.name,
+            devices: [{ role: DEFAULT_DEVICE_ROLE }],
+            steps
+        });
+        const unsignedManifest = {
+            version: 1,
+            source: {
+                path: sourcePath,
+                sha256: sha256(sourceBytes)
+            },
+            flows: dependencies,
+            expansion: dependencies.map((dependency) => dependency.name),
+            journey: {
+                name: journey.name,
+                sha256: hashCanonical(journey),
+                stepCount: journey.steps.length
+            }
+        };
+        return {
+            journey,
+            manifest: JourneyResolutionManifestSchema.parse({
+                ...unsignedManifest,
+                resolutionSha256: hashCanonical(unsignedManifest)
+            })
+        };
+    };
+    loadFlow = async (projectRoot, name) => {
+        const path = flowPath(name);
+        let bytes;
+        try {
+            bytes = await this.store.read({ projectRoot, relativePath: path });
+        }
+        catch (error) {
+            throw new JourneyCompositionError("FLOW_NOT_FOUND", `Unable to read Flow ${name} at ${path}`, { cause: error });
+        }
+        let flow;
+        try {
+            flow = FlowSchema.parse(parseJson(bytes, "Flow"));
+        }
+        catch (error) {
+            throw error instanceof JourneyCompositionError
+                ? error
+                : new JourneyCompositionError("FLOW_INVALID", `Flow ${name} is invalid`, { cause: error });
+        }
+        if (flow.name !== name) {
+            throw new JourneyCompositionError("FLOW_INVALID", `Flow at ${path} declares name ${flow.name}`);
+        }
+        return { path, bytes, flow };
+    };
+}

package/dist/application/journey/journey-retirer.d.ts

@@ -0,0 +1,25 @@
+import type { JourneyCompositionStore } from "../../ports/journey-composition-store.js";
+export type JourneyRetireErrorCode = "JOURNEY_NOT_FOUND" | "JOURNEY_INVALID" | "META_MISSING" | "META_INVALID" | "JOURNEY_ALREADY_RETIRED";
+export declare class JourneyRetireError extends Error {
+    readonly code: JourneyRetireErrorCode;
+    readonly name = "JourneyRetireError";
+    constructor(code: JourneyRetireErrorCode, message: string, options?: ErrorOptions);
+}
+export interface JourneyRetireResult {
+    status: "retired";
+    journeyPath: string;
+    metaPath: string;
+    retiredAt: string;
+}
+export declare class JourneyRetirer {
+    private readonly dependencies;
+    constructor(dependencies: {
+        store: Pick<JourneyCompositionStore, "read" | "readJourneyMeta" | "writeText">;
+    });
+    readonly retire: (input: {
+        projectRoot: string;
+        journeyPath: string;
+        reason: string;
+        now: Date;
+    }) => Promise<JourneyRetireResult>;
+}

package/dist/application/journey/journey-retirer.js

@@ -0,0 +1,87 @@
+import { GenerationMetaSchema } from "../../domain/generation.js";
+import { ResolvedJourneyPathSchema } from "../../domain/journey-composition.js";
+import { JourneySchema } from "../../domain/journey.js";
+export class JourneyRetireError extends Error {
+    code;
+    name = "JourneyRetireError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+function parseJson(bytes) {
+    return JSON.parse(bytes.toString("utf8"));
+}
+function serialize(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export class JourneyRetirer {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    retire = async (input) => {
+        const journeyPath = ResolvedJourneyPathSchema.parse(input.journeyPath);
+        const metaPath = `${journeyPath.slice(0, -".json".length)}.meta.json`;
+        let journeyBytes;
+        try {
+            journeyBytes = await this.dependencies.store.read({
+                projectRoot: input.projectRoot,
+                relativePath: journeyPath
+            });
+        }
+        catch {
+            throw new JourneyRetireError("JOURNEY_NOT_FOUND", `Journey is not readable: ${journeyPath}`);
+        }
+        try {
+            JourneySchema.parse(parseJson(journeyBytes));
+        }
+        catch (error) {
+            throw new JourneyRetireError("JOURNEY_INVALID", `Journey does not match the Journey schema: ${journeyPath}`, { cause: error });
+        }
+        const metaBytes = await this.dependencies.store.readJourneyMeta({
+            projectRoot: input.projectRoot,
+            journeyPath
+        });
+        if (metaBytes === null) {
+            throw new JourneyRetireError("META_MISSING", `Journey has no generation meta sidecar: ${metaPath}`);
+        }
+        let meta;
+        try {
+            meta = GenerationMetaSchema.parse(parseJson(metaBytes));
+        }
+        catch (error) {
+            throw new JourneyRetireError("META_INVALID", `Journey meta sidecar is invalid: ${metaPath}`, { cause: error });
+        }
+        if (meta.retired !== undefined) {
+            throw new JourneyRetireError("JOURNEY_ALREADY_RETIRED", `Journey is already retired: ${journeyPath}`);
+        }
+        const retiredAt = input.now.toISOString();
+        const updated = {
+            ...meta,
+            retired: {
+                retiredAt,
+                reason: input.reason.trim()
+            }
+        };
+        await this.dependencies.store.writeText({
+            projectRoot: input.projectRoot,
+            relativePath: metaPath,
+            content: serialize(updated)
+        });
+        const written = await this.dependencies.store.readJourneyMeta({
+            projectRoot: input.projectRoot,
+            journeyPath
+        });
+        if (written === null) {
+            throw new JourneyRetireError("META_INVALID", `Retired meta sidecar is not readable: ${metaPath}`);
+        }
+        GenerationMetaSchema.parse(parseJson(written));
+        return {
+            status: "retired",
+            journeyPath,
+            metaPath,
+            retiredAt
+        };
+    };
+}

package/dist/application/knowledge/anchor-resolver.d.ts

@@ -0,0 +1,36 @@
+import type { DisplayViewport } from "../../domain/geometry.js";
+import type { LayoutElement } from "../../domain/layout.js";
+import type { AnchorResolution, AnchorResolverPort } from "../../ports/anchor-resolver.js";
+import type { KnowledgeRegistryPort } from "../../ports/knowledge-registry.js";
+/**
+ * Semantic Anchor resolver.
+ *
+ * An Anchor is a Semantic UI Reference: an ordered candidate chain
+ * (composeSemantics → resourceId → contentDescription → visibleText →
+ * visualMatch). Resolution walks the chain deterministically:
+ *
+ * - the first candidate that resolves **uniquely** wins; the win is recorded
+ *   as `primary` (first candidate) or `fallback` (a later candidate), so a
+ *   fallback resolution is visible in the report rather than silent;
+ * - an **ambiguous** match at any candidate fails closed (matching the fixed
+ *   locator-priority rule: never select heuristically);
+ * - `visualMatch` is never resolved by Core: when nothing before it matched,
+ *   the resolution is `visualOnly` and the run fails closed —
+ *   `RUNTIME_CAPABILITY_MISSING` for the caller — leaving the visual layer to
+ *   an external multimodal reviewer under the Escalation Policy.
+ *
+ * The legacy single-locator identity remains supported as the primary
+ * candidate when no explicit `candidates` chain is present.
+ */
+export declare class KnowledgeAnchorResolver implements AnchorResolverPort {
+    private readonly registry;
+    private readonly projectRoot;
+    constructor(registry: Pick<KnowledgeRegistryPort, "load">, projectRoot: string);
+    readonly resolve: (input: {
+        anchorId: string;
+        layout: readonly LayoutElement[];
+        viewport?: DisplayViewport | undefined;
+        signal?: AbortSignal | undefined;
+    }) => Promise<AnchorResolution>;
+    private readonly found;
+}

package/dist/application/knowledge/anchor-resolver.js

@@ -0,0 +1,110 @@
+import { resolveLocator } from "../locator/locator-resolver.js";
+function candidateKindForLocator(locator) {
+    if (locator.resourceId !== undefined) {
+        return "resourceId";
+    }
+    if (locator.contentDescription !== undefined) {
+        return "contentDescription";
+    }
+    if (locator.text !== undefined) {
+        return "visibleText";
+    }
+    return "resourceId";
+}
+function resolveCandidate(layout, candidate, viewport) {
+    return resolveLocator(layout, candidate.locator, {
+        requireEnabled: true,
+        ...(viewport === undefined ? {} : { viewport })
+    });
+}
+/**
+ * Semantic Anchor resolver.
+ *
+ * An Anchor is a Semantic UI Reference: an ordered candidate chain
+ * (composeSemantics → resourceId → contentDescription → visibleText →
+ * visualMatch). Resolution walks the chain deterministically:
+ *
+ * - the first candidate that resolves **uniquely** wins; the win is recorded
+ *   as `primary` (first candidate) or `fallback` (a later candidate), so a
+ *   fallback resolution is visible in the report rather than silent;
+ * - an **ambiguous** match at any candidate fails closed (matching the fixed
+ *   locator-priority rule: never select heuristically);
+ * - `visualMatch` is never resolved by Core: when nothing before it matched,
+ *   the resolution is `visualOnly` and the run fails closed —
+ *   `RUNTIME_CAPABILITY_MISSING` for the caller — leaving the visual layer to
+ *   an external multimodal reviewer under the Escalation Policy.
+ *
+ * The legacy single-locator identity remains supported as the primary
+ * candidate when no explicit `candidates` chain is present.
+ */
+export class KnowledgeAnchorResolver {
+    registry;
+    projectRoot;
+    constructor(registry, projectRoot) {
+        this.registry = registry;
+        this.projectRoot = projectRoot;
+    }
+    resolve = async (input) => {
+        void input.signal;
+        const bundle = await this.registry.load(this.projectRoot);
+        const anchor = bundle.anchors.find((candidate) => candidate.id === input.anchorId);
+        if (anchor === undefined) {
+            return {
+                status: "notFound",
+                message: `Knowledge anchor ${input.anchorId} is not defined in ${this.projectRoot}`
+            };
+        }
+        if (anchor.identity.kind !== "element") {
+            return {
+                status: "notFound",
+                message: `Knowledge anchor ${input.anchorId} does not carry an element locator identity`
+            };
+        }
+        const candidates = anchor.candidates ?? [];
+        const chain = candidates.length > 0
+            ? candidates.map((candidate) => ({ kind: candidate.kind, candidate }))
+            : [{
+                    kind: candidateKindForLocator(anchor.identity.locator),
+                    candidate: {
+                        kind: candidateKindForLocator(anchor.identity.locator),
+                        locator: anchor.identity.locator
+                    }
+                }];
+        for (const [index, entry] of chain.entries()) {
+            if (entry.kind === "visualMatch") {
+                continue;
+            }
+            const resolution = resolveCandidate(input.layout, entry.candidate, input.viewport);
+            if (resolution.status !== "found") {
+                continue;
+            }
+            return this.found(entry.kind, index === 0, resolution);
+        }
+        const hasVisual = chain.some((entry) => entry.kind === "visualMatch");
+        if (hasVisual) {
+            return {
+                status: "visualOnly",
+                message: `Knowledge anchor ${input.anchorId} resolves only via visualMatch, which Core never performs`
+            };
+        }
+        return {
+            status: "notFound",
+            message: `Knowledge anchor ${input.anchorId} did not resolve through any candidate`
+        };
+    };
+    found = (kind, primary, resolution) => {
+        if (resolution.element.bounds === undefined) {
+            return {
+                status: "ambiguous",
+                message: `Knowledge anchor resolved via ${kind} to an element without bounds`
+            };
+        }
+        return {
+            status: "found",
+            point: resolution.point,
+            bounds: resolution.element.bounds,
+            element: resolution.element,
+            resolvedBy: { kind, confidence: primary ? "primary" : "fallback" }
+        };
+    };
+}

package/dist/application/knowledge/knowledge-loader.d.ts

@@ -0,0 +1,16 @@
+import type { KnowledgeRegistryPort, LoadedKnowledgeBundle } from "../../ports/knowledge-registry.js";
+export type KnowledgeLoadErrorCode = "KNOWLEDGE_INVALID" | "KNOWLEDGE_STALE" | "KNOWLEDGE_NOT_FOUND";
+export declare class KnowledgeLoadError extends Error {
+    readonly code: KnowledgeLoadErrorCode;
+    readonly name = "KnowledgeLoadError";
+    constructor(code: KnowledgeLoadErrorCode, message: string, options?: ErrorOptions);
+}
+export declare class KnowledgeLoader {
+    private readonly registry;
+    constructor(registry: Pick<KnowledgeRegistryPort, "load">);
+    readonly load: (input: {
+        projectRoot: string;
+        packageName?: string | undefined;
+        expectedKnowledgeHash?: string | undefined;
+    }) => Promise<LoadedKnowledgeBundle>;
+}