@iseoane/agent-depot 0.4.1 → 0.5.0

package/dist/src/package-flow.js

@@ -0,0 +1,636 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { sameAppVersion } from "./app-version.js";
+import { createPortableExecutableResolver } from "./executable-resolution.js";
+import { claudeMarketplaceName, discoverBundlesInSnapshot } from "./package-bundles.js";
+import { sourceBundleScope } from "./package-content.js";
+import { affectedBy, classifyUpdate, hostInstallId, packageApprovalDigest, planHostSteps, PackagePlanError, } from "./package-host-plans.js";
+import { findInstalledBundle, readHostInstallView } from "./package-host-state.js";
+import { activeBundles as classifyActiveBundles, portableSkillConflicts, } from "./package-owned-skills.js";
+import { bundleRoot, describeCoordinates, selectionKey, } from "./package-model.js";
+import { defaultPackageStateDirectory, PackageStateStore, } from "./package-state.js";
+import { runProcess } from "./process-runner.js";
+import { SourceStateStore } from "./source-state.js";
+import { createSourceContentAccess } from "./skill-discovery.js";
+import { createSourceOperations, resolveProjectSource, } from "./sources.js";
+const PACKAGE_OUTPUT_LIMIT = 1024 * 1024;
+const DIAGNOSTIC_BYTES = 4096;
+const WSL_EXECUTABLE_REASON = "will not run (Windows executable on WSL)";
+export function createPackageOperations(environment = {}) {
+    const platform = environment.platform ?? process.platform;
+    const home = environment.homeDirectory ?? homedir();
+    const isWsl = environment.isWsl ?? (platform === "linux" && Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP));
+    const stateDirectory = environment.stateDirectory ?? defaultPackageStateDirectory(process.env, platform, home);
+    const state = new PackageStateStore(stateDirectory);
+    const sourceStatePath = environment.sourceStatePath ?? path.join(stateDirectory, "sources.json");
+    const runner = environment.runner ?? runProcess;
+    const contentAccess = environment.sourceContentAccess ?? createSourceContentAccess();
+    const sourceOperations = environment.sourceOperations ?? createSourceOperations({
+        ...(environment.homeDirectory === undefined ? {} : { homeDirectory: environment.homeDirectory }),
+        sourceContentAccess: contentAccess,
+    });
+    const resolve = createPortableExecutableResolver({
+        platform,
+        isWsl,
+        ...(environment.wslMountRoot === undefined ? {} : { wslMountRoot: environment.wslMountRoot }),
+        ...(environment.resolveExecutable === undefined ? {} : { resolveExecutable: environment.resolveExecutable }),
+    });
+    const readHostView = () => readHostInstallView({
+        ...(environment.homeDirectory === undefined ? {} : { homeDirectory: environment.homeDirectory }),
+        ...(environment.readHostStateFile === undefined ? {} : { readHostStateFile: environment.readHostStateFile }),
+    });
+    async function resolveSourceFor(projectSource) {
+        return sourceOperations.resolveProjectSource
+            ? await sourceOperations.resolveProjectSource(projectSource)
+            : resolveProjectSource(projectSource);
+    }
+    /** ADR 0004: a preview that leads to a write refreshes the Source first. */
+    async function refreshSourceFor(selection) {
+        const source = await resolveSourceFor(selection.source);
+        if (source.kind === "builtin") {
+            return source;
+        }
+        if (sourceOperations.refreshProjectSource === undefined) {
+            throw new PackagePlanError(`Planning a Package lifecycle for ${describeCoordinates(selection)} requires a Source refresh, but this environment cannot refresh project Sources`);
+        }
+        return await sourceOperations.refreshProjectSource(selection.source);
+    }
+    async function readResolvedCommit(source) {
+        if (source.kind === "builtin" || contentAccess.readResolvedVersion === undefined) {
+            return undefined;
+        }
+        const evidence = await contentAccess.readResolvedVersion(source);
+        return evidence?.kind === "git-commit" ? evidence.commit : undefined;
+    }
+    async function deriveBundle(selection, source) {
+        const files = Object.freeze([...(await contentAccess.readSnapshot(source))]);
+        const coordinates = coordinatesOf(selection);
+        const descriptor = discoverBundlesInSnapshot(files, sourceBundleScope(source))
+            .find((candidate) => sameCoordinates(candidate.coordinates, coordinates));
+        if (descriptor === undefined) {
+            throw new PackagePlanError(`Source ${JSON.stringify(source.id)} no longer provides a ${selection.host} Package at ${JSON.stringify(bundleRoot(coordinates))}`);
+        }
+        const resolvedCommit = await readResolvedCommit(source);
+        const available = availableEvidence(descriptor, resolvedCommit);
+        return Object.freeze({
+            source,
+            files,
+            descriptor,
+            ...(resolvedCommit === undefined ? {} : { resolvedCommit }),
+            ...(available === undefined ? {} : { available }),
+            marketplace: marketplaceResolution(descriptor, files),
+        });
+    }
+    async function planFromBundle(selection, action, bundle, view) {
+        const commands = Object.freeze(planHostSteps(action, bundle.descriptor, selection, view, bundle.marketplace)
+            .map((argv) => toCommand(argv, action)));
+        const origin = Object.freeze({
+            manifestDigest: bundle.descriptor.manifestDigest,
+            installId: hostInstallId(bundle.descriptor, selection, view, bundle.marketplace),
+            ...(bundle.resolvedCommit === undefined ? {} : { resolvedCommit: bundle.resolvedCommit }),
+        });
+        const installed = findInstalledBundle(view, bundle.descriptor, selection);
+        const plan = Object.freeze({
+            selection,
+            action,
+            descriptor: bundle.descriptor,
+            commands,
+            affects: affectedBy(action, selection, (await state.list()).map((record) => record.selection)),
+            warnings: bundle.descriptor.warnings,
+            cwd: home,
+            environment: isWsl ? "linux (WSL)" : platform,
+            origin,
+            ...(actionSatisfied(action, selection, installed) ? { skipExecution: true } : {}),
+        });
+        const declaration = declarationFor(selection, bundle.descriptor, commands);
+        return Object.freeze({
+            plan,
+            declaration,
+            digest: packageApprovalDigest(declaration),
+            bundle,
+            ...(bundle.available === undefined ? {} : { available: bundle.available }),
+        });
+    }
+    /**
+     * Refuses an activation whose bundle owns a Skill already managed as a
+     * portable user-global installation. The portable copy is never removed or
+     * replaced; the user forgets it first. No path is changed here.
+     */
+    async function assertNoPortableSkillConflicts(descriptor, source, action) {
+        if (action !== "install" && action !== "select") {
+            return;
+        }
+        let installations;
+        try {
+            installations = (await new SourceStateStore(sourceStatePath).load()).userGlobalInstallations;
+        }
+        catch (error) {
+            throw new PackagePlanError(`The portable Skill state at ${JSON.stringify(sourceStatePath)} could not be read, so the ${action} cannot be checked for duplicate Skills: ${reasonOf(error)}`);
+        }
+        const conflicts = portableSkillConflicts(descriptor, source, installations);
+        if (conflicts.length === 0) {
+            return;
+        }
+        throw new PackagePlanError(`The ${descriptor.host} Package ${JSON.stringify(descriptor.name)} would duplicate ${conflicts.length === 1 ? "a Skill" : "Skills"} ` +
+            `already managed as portable installations (${conflicts.map(conflict => JSON.stringify(conflict.path)).join(", ")}); ` +
+            "forget those installations first. No path was changed.");
+    }
+    async function derivePlan(selection, action, refresh) {
+        const source = refresh ? await refreshSourceFor(selection) : await resolveSourceFor(selection.source);
+        const bundle = await deriveBundle(selection, source);
+        await assertNoPortableSkillConflicts(bundle.descriptor, selection.source, action);
+        return await planFromBundle(selection, action, bundle, await readHostView());
+    }
+    async function inspect(selection) {
+        let bundle;
+        let drift;
+        let approval = "needs approval";
+        let installId;
+        const view = await readHostView();
+        try {
+            bundle = await deriveBundle(selection, await resolveSourceFor(selection.source));
+        }
+        catch (error) {
+            drift = reasonOf(error);
+        }
+        if (bundle !== undefined) {
+            try {
+                const derived = await planFromBundle(selection, "install", bundle, view);
+                approval = await state.approvalStatus(derived.digest);
+                installId = derived.plan.origin.installId;
+            }
+            catch (error) {
+                drift ??= reasonOf(error);
+            }
+        }
+        const record = await state.find(selection);
+        const identityDrift = record === undefined || installId === undefined || record.installId === installId
+            ? undefined
+            : `The recorded install identity ${JSON.stringify(record.installId)} no longer matches ${JSON.stringify(installId)}`;
+        const installed = bundle === undefined
+            ? Object.freeze({ kind: "unknown", reason: drift ?? "the bundle could not be resolved" })
+            : findInstalledBundle(view, bundle.descriptor, selection);
+        return Object.freeze({
+            ...(bundle === undefined ? {} : { descriptor: bundle.descriptor }),
+            installed,
+            ...(bundle?.available === undefined ? {} : { available: bundle.available }),
+            approval,
+            ...((drift ?? identityDrift) === undefined ? {} : { drift: drift ?? identityDrift }),
+        });
+    }
+    async function checkOne(record) {
+        try {
+            const inspection = await inspect(record.selection);
+            const status = classifyUpdate(inspection.installed, inspection.available);
+            return Object.freeze({
+                installed: record,
+                status,
+                ...(inspection.available === undefined ? {} : { available: inspection.available }),
+                ...(status === "unknown" ? { reason: inspection.drift ?? describeEvidence(inspection.installed) } : {}),
+            });
+        }
+        catch (error) {
+            return Object.freeze({
+                installed: record,
+                status: "unknown",
+                reason: `The update check failed: ${reasonOf(error)}`,
+            });
+        }
+    }
+    async function writeSelection(context, observed) {
+        const verified = observed === undefined ? undefined : verifiedEvidence(observed, context.available);
+        await state.upsert({
+            selection: context.selection,
+            installId: context.origin.installId,
+            ...(context.origin.resolvedCommit === undefined ? {} : { lastDelegatedCommit: context.origin.resolvedCommit }),
+            ...(verified === undefined ? {} : { verified }),
+        });
+    }
+    async function recordOutcome(context, observed) {
+        switch (context.action) {
+            case "install": {
+                if (observed.kind !== "installed") {
+                    return { status: "failed", reason: `The host does not report ${describeCoordinates(context.selection)} installed (${describeEvidence(observed)})` };
+                }
+                const contradiction = pinContradiction(context.selection, observed);
+                if (contradiction !== undefined) {
+                    return { status: "failed", reason: `${contradiction}; the selection record was left untouched` };
+                }
+                await writeSelection(context, observed);
+                return Object.freeze({ status: "installed", verified: observed });
+            }
+            case "update": {
+                if (observed.kind !== "installed") {
+                    return { status: "failed", reason: `The update left no installed ${describeCoordinates(context.selection)} (${describeEvidence(observed)})` };
+                }
+                const contradiction = pinContradiction(context.selection, observed);
+                if (contradiction !== undefined) {
+                    return { status: "failed", reason: `${contradiction}; the selection record was left untouched` };
+                }
+                const change = installedEvidenceChange(context.previous, observed);
+                if (change === "unknown") {
+                    return {
+                        status: "failed",
+                        reason: `The observed version change cannot be verified (${describeEvidence(context.previous ?? Object.freeze({ kind: "absent" }))} -> ${describeEvidence(observed)}); the selection record was left untouched`,
+                    };
+                }
+                if (change === "unchanged") {
+                    return {
+                        status: "failed",
+                        reason: `The observed version did not change (${describeEvidence(observed)}); the selection record was left untouched`,
+                    };
+                }
+                await writeSelection(context, observed);
+                return Object.freeze({
+                    status: "updated",
+                    previous: context.previous ?? Object.freeze({ kind: "absent" }),
+                    verified: observed,
+                });
+            }
+            case "uninstall": {
+                if (observed.kind !== "absent") {
+                    return { status: "failed", reason: `The host still reports ${describeCoordinates(context.selection)} (${describeEvidence(observed)})` };
+                }
+                await state.drop(context.selection);
+                return Object.freeze({ status: "removed" });
+            }
+            case "select": {
+                await writeSelection(context);
+                return Object.freeze({ status: "selected" });
+            }
+            case "forget": {
+                await state.drop(context.selection);
+                return Object.freeze({ status: "forgotten" });
+            }
+        }
+    }
+    function contextFromDerived(derived, action, previous) {
+        return {
+            action,
+            selection: derived.plan.selection,
+            descriptor: derived.plan.descriptor,
+            origin: derived.plan.origin,
+            ...(derived.available === undefined ? {} : { available: derived.available }),
+            ...(previous === undefined ? {} : { previous }),
+        };
+    }
+    async function completeSkipped(context) {
+        switch (context.action) {
+            case "install": {
+                return await recordOutcome(context, findInstalledBundle(await readHostView(), context.descriptor, context.selection));
+            }
+            case "select": {
+                await writeSelection(context);
+                return Object.freeze({ status: "selected" });
+            }
+            case "uninstall": {
+                await state.drop(context.selection);
+                return Object.freeze({ status: "removed" });
+            }
+            case "update":
+            case "forget": {
+                return await recordOutcome(context, findInstalledBundle(await readHostView(), context.descriptor, context.selection));
+            }
+        }
+    }
+    return {
+        async discover(sourceIds) {
+            const descriptors = [];
+            for (const source of await sourceOperations.selectSources(sourceIds)) {
+                descriptors.push(...discoverBundlesInSnapshot(await contentAccess.readSnapshot(source), sourceBundleScope(source)));
+            }
+            return Object.freeze(descriptors);
+        },
+        async list() {
+            return await state.list();
+        },
+        async activeBundles(bundles) {
+            const records = await state.list();
+            return classifyActiveBundles(bundles, records.map(record => record.selection), await readHostView());
+        },
+        inspect,
+        async approvalStatus(selection, action = "install") {
+            const derived = await derivePlan(selection, action, false);
+            return await state.approvalStatus(derived.digest);
+        },
+        async approve(selection, action = "install") {
+            const derived = await derivePlan(selection, action, false);
+            await state.approve(derived.digest);
+        },
+        async planLifecycle(selection, action) {
+            return (await derivePlan(selection, action, true)).plan;
+        },
+        async executeLifecycle(plan, confirmed) {
+            if (!confirmed) {
+                return Object.freeze({ status: "not confirmed" });
+            }
+            const fresh = await derivePlan(plan.selection, plan.action, false);
+            const difference = planDifference(plan, fresh);
+            if (difference !== undefined) {
+                return Object.freeze({ status: "stale plan", reason: difference });
+            }
+            if (await state.approvalStatus(fresh.digest) !== "approved") {
+                throw new PackagePlanError(`The ${plan.action} plan for ${describeCoordinates(plan.selection)} is not approved; review it and approve the current declaration first`);
+            }
+            const previous = findInstalledBundle(await readHostView(), fresh.plan.descriptor, plan.selection);
+            const context = contextFromDerived(fresh, plan.action, previous);
+            if (fresh.plan.skipExecution === true) {
+                return await completeSkipped(context);
+            }
+            for (const command of fresh.plan.commands) {
+                const resolution = await resolve(command.executable);
+                if (resolution.blocked) {
+                    return { status: "manual required", reason: blockedReason(command.executable, plan.action) };
+                }
+                if (resolution.executable === undefined) {
+                    return { status: "manual required", reason: missingExecutableReason(command.executable, plan.action) };
+                }
+                let result;
+                try {
+                    result = await runner(resolution.executable, command.args, {
+                        cwd: plan.cwd,
+                        captureStdout: true,
+                        maxOutputBytes: PACKAGE_OUTPUT_LIMIT,
+                        maxStderrBytes: PACKAGE_OUTPUT_LIMIT,
+                    });
+                }
+                catch (error) {
+                    const code = error?.code;
+                    if (code === undefined || !["ENOENT", "EACCES", "ENOEXEC", "EPERM"].includes(code)) {
+                        throw error;
+                    }
+                    const detail = error instanceof Error ? error.message : String(error);
+                    return {
+                        status: "manual required",
+                        reason: `Cannot run ${JSON.stringify(command.executable)} for the Package ${plan.action} (${code}): ${detail}`,
+                    };
+                }
+                if (result.code !== 0 || result.signal || result.outputTooLarge) {
+                    const failure = result.outputTooLarge
+                        ? `output exceeded ${PACKAGE_OUTPUT_LIMIT} bytes`
+                        : `exit ${result.code}, signal ${result.signal}`;
+                    const output = [
+                        result.stdout.subarray(-DIAGNOSTIC_BYTES).toString("utf8"),
+                        Buffer.from(result.stderr).subarray(-DIAGNOSTIC_BYTES).toString("utf8"),
+                    ].join(" ").trim();
+                    return {
+                        status: "failed",
+                        reason: `The host command ${JSON.stringify(command.executable)} failed (${failure})`,
+                        ...(output === "" ? {} : { output }),
+                    };
+                }
+            }
+            return await recordOutcome(context, findInstalledBundle(await readHostView(), fresh.plan.descriptor, plan.selection));
+        },
+        async forget(selection, confirmed) {
+            if (!confirmed) {
+                throw new PackagePlanError("Forgetting a Package requires explicit confirmation; no record was changed");
+            }
+            await state.drop(selection);
+        },
+        async checkUpdates(selections) {
+            const records = await state.list();
+            const selected = selections === undefined
+                ? records
+                : records.filter((record) => selections.some((selection) => selectionKey(selection) === selectionKey(record.selection)));
+            return Object.freeze(await Promise.all(selected.map(async (record) => await checkOne(record))));
+        },
+    };
+}
+function coordinatesOf(selection) {
+    return selection.host === "pi"
+        ? Object.freeze({ host: selection.host, root: selection.root })
+        : Object.freeze({ host: selection.host, marketplaceRoot: selection.marketplaceRoot, pluginName: selection.pluginName });
+}
+function sameCoordinates(left, right) {
+    if (left.host === "pi" && right.host === "pi") {
+        return left.root === right.root;
+    }
+    if (left.host === "claude" && right.host === "claude") {
+        return left.marketplaceRoot === right.marketplaceRoot && left.pluginName === right.pluginName;
+    }
+    return false;
+}
+function availableEvidence(descriptor, resolvedCommit) {
+    if (descriptor.version !== undefined) {
+        return descriptor.version;
+    }
+    return resolvedCommit === undefined ? undefined : Object.freeze({ kind: "git-commit", commit: resolvedCommit });
+}
+/** The marketplace name lives in the Source's own manifest, never in host state before the first add. */
+function marketplaceResolution(descriptor, files) {
+    const coordinates = descriptor.coordinates;
+    if (coordinates.host !== "claude") {
+        return Object.freeze({});
+    }
+    const root = coordinates.marketplaceRoot;
+    const filePath = root === "" ? ".claude-plugin/marketplace.json" : `${root}/.claude-plugin/marketplace.json`;
+    const raw = files.find((file) => file.path === filePath)?.content;
+    if (raw === undefined) {
+        return Object.freeze({});
+    }
+    const name = claudeMarketplaceName(raw);
+    return Object.freeze(name === undefined ? {} : { marketplaceName: name });
+}
+function declarationFor(selection, descriptor, commands) {
+    const source = declarationSource(selection.source);
+    return Object.freeze({
+        ...source,
+        coordinates: coordinatesOf(selection),
+        manifestDigest: descriptor.manifestDigest,
+        argv: Object.freeze(commands.map((command) => Object.freeze([command.executable, ...command.args]))),
+    });
+}
+function declarationSource(source) {
+    if (source.kind === "builtin") {
+        return Object.freeze({ sourceUrl: "" });
+    }
+    if ("url" in source) {
+        return Object.freeze({ sourceUrl: source.url, ...(source.ref === undefined ? {} : { ref: source.ref }) });
+    }
+    return Object.freeze({ sourceUrl: source.path, ...(source.ref === undefined ? {} : { ref: source.ref }) });
+}
+function toCommand(argv, action) {
+    const [executable, ...args] = argv;
+    if (executable === undefined) {
+        throw new PackagePlanError("A host step produced an empty argv");
+    }
+    return Object.freeze({
+        purpose: commandPurpose(action, executable, args),
+        executable,
+        args: Object.freeze(args),
+        summary: `${executable} ${args.join(" ")}`.trim(),
+    });
+}
+function commandPurpose(action, executable, args) {
+    if (action === "uninstall") {
+        return "remove";
+    }
+    return executable === "claude" && args[0] === "plugin" && args[1] === "marketplace" ? "register" : "apply";
+}
+function actionSatisfied(action, selection, installed) {
+    switch (action) {
+        case "install": {
+            if (installed.kind !== "installed") {
+                return false;
+            }
+            const verdict = fixedPiPinVerdict(selection, installed);
+            return verdict.kind === "satisfied" || verdict.kind === "not-pinned";
+        }
+        case "uninstall": {
+            return installed.kind === "absent";
+        }
+        case "select": {
+            return true;
+        }
+        case "update":
+        case "forget": {
+            return false;
+        }
+    }
+}
+/** The exact recheck issue 08 pins: manifest digest, install id, resolved commit, ordered steps. */
+function planDifference(plan, fresh) {
+    if (fresh.plan.origin.manifestDigest !== plan.origin.manifestDigest) {
+        return "The bundle manifest changed since the plan was shown";
+    }
+    if (fresh.plan.origin.installId !== plan.origin.installId) {
+        return "The host install identity changed since the plan was shown";
+    }
+    if (fresh.plan.origin.resolvedCommit !== plan.origin.resolvedCommit) {
+        return "The resolved Source commit changed since the plan was shown";
+    }
+    if (fresh.plan.commands.length !== plan.commands.length) {
+        return "The ordered host steps changed since the plan was shown";
+    }
+    for (const [index, command] of fresh.plan.commands.entries()) {
+        const shown = plan.commands[index];
+        if (shown === undefined || shown.executable !== command.executable
+            || shown.args.length !== command.args.length
+            || shown.args.some((argument, argumentIndex) => argument !== command.args[argumentIndex])) {
+            return `Host step ${index + 1} changed since the plan was shown`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Three outcomes, not two. `unknown` means the two observations carry no
+ * comparable evidence, and an update must not report that as a success. A host
+ * that had nothing installed and now reports an install has changed.
+ */
+function installedEvidenceChange(previous, observed) {
+    if (observed.kind !== "installed" || previous === undefined || previous.kind === "unknown") {
+        return "unknown";
+    }
+    if (previous.kind === "absent") {
+        return "changed";
+    }
+    if (previous.version !== undefined && observed.version !== undefined) {
+        return sameAppVersion(previous.version, observed.version) ? "unchanged" : "changed";
+    }
+    const previousCommit = previous.commit === undefined ? undefined : gitCommitId(previous.commit);
+    const observedCommit = observed.commit === undefined ? undefined : gitCommitId(observed.commit);
+    if (previousCommit !== undefined && observedCommit !== undefined) {
+        return previousCommit === observedCommit ? "unchanged" : "changed";
+    }
+    return "unknown";
+}
+/**
+ * Whether host evidence settles a fixed Pi pin. Two hexadecimal refs must agree;
+ * a version pin compares through `sameAppVersion`. Evidence the pin cannot be
+ * read from is `unverifiable`, so it never satisfies a skip and never counts as
+ * a contradiction.
+ */
+function fixedPiPinVerdict(selection, observed) {
+    if (selection.host !== "pi" || selection.version.policy !== "fixed" || selection.version.version === "") {
+        return { kind: "not-pinned" };
+    }
+    const pin = selection.version.version;
+    if (observed.kind !== "installed") {
+        return { kind: "unverifiable", pin };
+    }
+    const pinCommit = gitCommitId(pin);
+    const observedCommit = observed.commit === undefined ? undefined : gitCommitId(observed.commit);
+    if (pinCommit !== undefined && observedCommit !== undefined) {
+        return pinCommit === observedCommit ? { kind: "satisfied" } : { kind: "contradicted", pin };
+    }
+    if (observed.version !== undefined && sameAppVersion(observed.version, pin)) {
+        return { kind: "satisfied" };
+    }
+    return { kind: "unverifiable", pin };
+}
+/** A fixed Pi pin the host positively contradicts. Unverifiable evidence is not a contradiction. */
+function pinContradiction(selection, observed) {
+    const verdict = fixedPiPinVerdict(selection, observed);
+    if (verdict.kind !== "contradicted") {
+        return undefined;
+    }
+    return `The host reports ${describeCoordinates(selection)} ${describeEvidence(observed)}, which contradicts the fixed pin ${JSON.stringify(verdict.pin)}`;
+}
+/**
+ * The record's `verified` field is a claim about the host, so it derives from the
+ * host observation alone. A version is recorded only when it agrees with the one
+ * the Source declares, because `declaredBy` names that declaration. Evidence that
+ * cannot be attested leaves the field absent.
+ */
+function verifiedEvidence(observed, available) {
+    if (observed.kind !== "installed") {
+        return undefined;
+    }
+    if (observed.commit !== undefined) {
+        const commit = storableCommit(observed.commit);
+        return commit === undefined ? undefined : Object.freeze({ kind: "git-commit", commit });
+    }
+    if (observed.version === undefined
+        || available?.kind !== "manifest-version"
+        || !storableVersion(observed.version)
+        || !sameAppVersion(observed.version, available.version)) {
+        return undefined;
+    }
+    return Object.freeze({ kind: "manifest-version", version: observed.version, declaredBy: available.declaredBy });
+}
+/** A hexadecimal git ref, normalized, or `undefined` for any other spelling. */
+function gitCommitId(ref) {
+    const normalized = ref.trim().toLowerCase();
+    return /^[0-9a-f]{7,64}$/u.test(normalized) ? normalized : undefined;
+}
+/** The state store reads back only a 40- or 64-character lowercase commit ID. */
+function storableCommit(commit) {
+    const normalized = gitCommitId(commit);
+    return normalized !== undefined && (normalized.length === 40 || normalized.length === 64) ? normalized : undefined;
+}
+/** The state store reads back only a value without surrounding or unsafe whitespace. */
+function storableVersion(version) {
+    return version !== "" && version.trim() === version && !/\s/u.test(version) && !hasControlCharacter(version);
+}
+function hasControlCharacter(value) {
+    return Array.from(value).some((character) => (character.codePointAt(0) ?? 0) <= 0x1f || character.codePointAt(0) === 0x7f);
+}
+function describeEvidence(evidence) {
+    switch (evidence.kind) {
+        case "installed": {
+            if (evidence.version !== undefined) {
+                return `installed ${JSON.stringify(evidence.version)}`;
+            }
+            if (evidence.commit !== undefined) {
+                return `installed at commit ${evidence.commit}`;
+            }
+            return "installed with no version evidence";
+        }
+        case "absent": {
+            return "not installed";
+        }
+        case "unknown": {
+            return `unknown (${evidence.reason})`;
+        }
+    }
+}
+function blockedReason(executable, action) {
+    return `Cannot run ${JSON.stringify(executable)} for the Package ${action}: ${WSL_EXECUTABLE_REASON}; run the host command manually`;
+}
+function missingExecutableReason(executable, action) {
+    return `Required executable ${JSON.stringify(executable)} for the Package ${action} was not found or could not be started. Install it or make it available on the PATH used by Agent Depot, then retry.`;
+}
+function reasonOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}