@deftai/directive-core 0.99.0 → 0.101.0

package/dist/session/active-cli.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Active CLI path / engine-version check after global upgrade (#3233).
+ *
+ * A global `npm i -g` can land under one npm prefix while a higher-precedence
+ * PATH entry still runs an older `deft` / `directive`. The upgrade looks
+ * complete, but bare CLI invocations keep the stale engine.
+ *
+ * Shell-active binaries may be probed with `--version`. Lower-precedence PATH
+ * candidates are inspected via package.json only (never executed) so gated
+ * ritual cannot run unselected PATH entries (#3233 Greptile P1 security).
+ */
+/** Bare CLI names operators invoke after upgrade. */
+export declare const ACTIVE_CLI_COMMANDS: readonly ["deft", "directive"];
+export type ActiveCliCommand = (typeof ACTIVE_CLI_COMMANDS)[number];
+export interface CliCandidate {
+    readonly command: ActiveCliCommand;
+    readonly path: string;
+    readonly version: string | null;
+    /** Zero-based PATH precedence within this command (0 = shell-active). */
+    readonly precedence: number;
+    /** How the version was obtained (for diagnostics / tests). */
+    readonly versionSource: "exec" | "package-json" | "none";
+}
+export interface ActiveCliCheckSeams {
+    readonly whichAll?: (name: string) => string[];
+    /**
+     * Optional override for version probing. When omitted, active binaries may
+     * spawn `--version`; shadowed binaries use package.json only.
+     */
+    readonly probeVersion?: (executablePath: string, precedence: number) => string | null;
+    readonly commands?: readonly ActiveCliCommand[];
+    /** Override default upgrade-target resolution (tests). */
+    readonly resolveDefaultTarget?: (candidates: readonly CliCandidate[]) => string | null;
+    /** Inject in-process engine version for default-target resolution. */
+    readonly inProcessVersion?: string | null;
+}
+export interface ActiveCliCheckResult {
+    /** True when no shadowing / target mismatch was detected. */
+    readonly ok: boolean;
+    /** 0 = ok, 1 = shadow/mismatch (fail closed), 2 = probe config error (unused; reserved). */
+    readonly code: number;
+    readonly active: CliCandidate | null;
+    readonly candidates: readonly CliCandidate[];
+    readonly targetVersion: string | null;
+    /** Single-line summary for ritual / exit message. */
+    readonly message: string;
+    /** Multi-line stderr diagnostic (paths, versions, remediation). */
+    readonly lines: readonly string[];
+}
+/**
+ * Resolve engine version by walking the install tree for package.json (no exec).
+ * Follows symlinks and win32 `.cmd` shims that embed a node path.
+ */
+export declare function readEngineVersionFromInstallTree(executablePath: string): string | null;
+/** Probe shell-active CLI only via `--version` (never used for shadowed PATH entries). */
+export declare function probeCliEngineVersion(executablePath: string): string | null;
+/**
+ * Version probe used by the default collector:
+ * - precedence 0 (shell-active): package.json first, then `--version` spawn
+ * - precedence > 0: package.json only (never execute shadowed PATH entries)
+ */
+export declare function probeCandidateVersion(executablePath: string, precedence: number): string | null;
+/**
+ * Default upgrade target when callers omit `targetEngineVersion` (#3233 P1):
+ * the max of (1) publishable in-process engine version and (2) versions from
+ * **non-active** PATH candidates only. The shell-active CLI must never become
+ * its own expected target (lone stale self-match).
+ */
+export declare function resolveDefaultActiveCliTarget(candidates: readonly CliCandidate[], inProcessVersion?: string | null): string | null;
+/**
+ * Fail-closed check: shell-active `deft`/`directive` must match `targetVersion`
+ * (or the resolved default target), and must not be older than another PATH
+ * candidate (#3233).
+ *
+ * When no CLI is on PATH, returns ok=true (absence is covered by verify:tools /
+ * engine ladder — this gate only catches shadowing after a multi-prefix install).
+ */
+export declare function checkActiveCliAgainstTarget(targetVersion?: string | null, seams?: ActiveCliCheckSeams): ActiveCliCheckResult;
+//# sourceMappingURL=active-cli.d.ts.map

package/dist/session/active-cli.js

@@ -0,0 +1,382 @@
+/**
+ * Active CLI path / engine-version check after global upgrade (#3233).
+ *
+ * A global `npm i -g` can land under one npm prefix while a higher-precedence
+ * PATH entry still runs an older `deft` / `directive`. The upgrade looks
+ * complete, but bare CLI invocations keep the stale engine.
+ *
+ * Shell-active binaries may be probed with `--version`. Lower-precedence PATH
+ * candidates are inspected via package.json only (never executed) so gated
+ * ritual cannot run unselected PATH entries (#3233 Greptile P1 security).
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { CANONICAL_UPGRADE_COMMAND } from "../doctor/constants.js";
+import { defaultWhichAll } from "../doctor/which.js";
+import { readCorePackageVersion } from "../engine-version.js";
+import { compareSemver } from "../resolution/pin.js";
+import { quoteWin32CommandForShell, shouldUseShellForCommand, } from "../verify-env/command-spawn.js";
+/** Bare CLI names operators invoke after upgrade. */
+export const ACTIVE_CLI_COMMANDS = ["deft", "directive"];
+/** Bounded semver extract — avoids ReDoS on long zero-runs (CodeQL). */
+const SEMVER_IN_TEXT_RE = /\b(\d{1,6}\.\d{1,6}\.\d{1,6})\b/;
+const ENGINE_PKG_NAMES = new Set(["@deftai/directive", "@deftai/directive-core"]);
+function parseVersionFromOutput(out) {
+    // Cap scan length so CodeQL polynomial-regex alerts cannot fire on huge text.
+    const sample = out.length > 512 ? out.slice(0, 512) : out;
+    const match = SEMVER_IN_TEXT_RE.exec(sample);
+    return match?.[1] ?? null;
+}
+function isPublishableSemver(version) {
+    if (typeof version !== "string" || version.length === 0)
+        return false;
+    if (version === "0.0.0" || version.includes("0.0.0-dev") || version.includes("dev")) {
+        return false;
+    }
+    return SEMVER_IN_TEXT_RE.test(version);
+}
+function tryReadPackageVersion(pkgPath) {
+    try {
+        const raw = readFileSync(pkgPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object")
+            return null;
+        const rec = parsed;
+        const name = typeof rec.name === "string" ? rec.name : "";
+        if (!ENGINE_PKG_NAMES.has(name))
+            return null;
+        // Prefer directive-core dep when the CLI package version is a workspace/dev 0.0.0.
+        if (name === "@deftai/directive" && rec.dependencies && typeof rec.dependencies === "object") {
+            const core = rec.dependencies["@deftai/directive-core"];
+            if (typeof core === "string") {
+                const coreVer = parseVersionFromOutput(core);
+                if (coreVer !== null && isPublishableSemver(coreVer))
+                    return coreVer;
+            }
+        }
+        return typeof rec.version === "string" && rec.version.length > 0 ? rec.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve engine version by walking the install tree for package.json (no exec).
+ * Follows symlinks and win32 `.cmd` shims that embed a node path.
+ */
+export function readEngineVersionFromInstallTree(executablePath) {
+    const seeds = [executablePath];
+    try {
+        if (existsSync(executablePath)) {
+            const st = lstatSync(executablePath);
+            if (st.isSymbolicLink()) {
+                try {
+                    const link = readlinkSync(executablePath);
+                    seeds.push(resolve(dirname(executablePath), link));
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            try {
+                seeds.push(realpathSync(executablePath));
+            }
+            catch {
+                /* ignore */
+            }
+            // Win32 npm shims often contain a path to the real package bin.
+            if (/\.(cmd|bat)$/i.test(executablePath)) {
+                try {
+                    const text = readFileSync(executablePath, "utf8");
+                    const m = /%~dp0[\\/](\.\.[\\/].*?node_modules[\\/]@deftai[\\/]directive[\\/][^\s"']+)/i.exec(text) ??
+                        /([A-Za-z]:\\[^\r\n"']*node_modules[\\/]@deftai[\\/]directive[\\/][^\r\n"']+)/i.exec(text) ??
+                        /([^\s"']*node_modules[\\/]@deftai[\\/]directive[\\/][^\s"']+)/i.exec(text);
+                    if (m?.[1]) {
+                        seeds.push(resolve(dirname(executablePath), m[1].replace(/\//g, "\\")));
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    for (const seed of seeds) {
+        let dir = dirname(seed);
+        for (let i = 0; i < 12; i += 1) {
+            const pkgPath = join(dir, "package.json");
+            const ver = tryReadPackageVersion(pkgPath);
+            if (ver !== null) {
+                const parsed = parseVersionFromOutput(ver) ?? ver;
+                if (isPublishableSemver(parsed) || SEMVER_IN_TEXT_RE.test(parsed)) {
+                    return parseVersionFromOutput(parsed) ?? parsed;
+                }
+            }
+            // npm global: .../node_modules/@deftai/directive
+            const nested = join(dir, "node_modules", "@deftai", "directive", "package.json");
+            const nestedVer = tryReadPackageVersion(nested);
+            if (nestedVer !== null) {
+                return parseVersionFromOutput(nestedVer) ?? nestedVer;
+            }
+            const nestedCore = join(dir, "node_modules", "@deftai", "directive-core", "package.json");
+            const nestedCoreVer = tryReadPackageVersion(nestedCore);
+            if (nestedCoreVer !== null) {
+                return parseVersionFromOutput(nestedCoreVer) ?? nestedCoreVer;
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return null;
+}
+/** Probe shell-active CLI only via `--version` (never used for shadowed PATH entries). */
+export function probeCliEngineVersion(executablePath) {
+    const fromTree = readEngineVersionFromInstallTree(executablePath);
+    if (fromTree !== null)
+        return fromTree;
+    const shell = shouldUseShellForCommand(executablePath);
+    const cmd = shell && process.platform === "win32"
+        ? quoteWin32CommandForShell(executablePath)
+        : executablePath;
+    try {
+        const result = spawnSync(cmd, ["--version"], {
+            encoding: "utf8",
+            timeout: 5_000,
+            stdio: ["ignore", "pipe", "pipe"],
+            shell,
+            windowsHide: true,
+        });
+        if (result.status !== 0) {
+            return null;
+        }
+        const stdout = typeof result.stdout === "string" ? result.stdout : "";
+        return parseVersionFromOutput(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Version probe used by the default collector:
+ * - precedence 0 (shell-active): package.json first, then `--version` spawn
+ * - precedence > 0: package.json only (never execute shadowed PATH entries)
+ */
+export function probeCandidateVersion(executablePath, precedence) {
+    if (precedence > 0) {
+        return readEngineVersionFromInstallTree(executablePath);
+    }
+    return probeCliEngineVersion(executablePath);
+}
+function collectCandidates(seams) {
+    const whichAll = seams.whichAll ?? ((name) => defaultWhichAll(name));
+    const probe = seams.probeVersion ?? probeCandidateVersion;
+    const commands = seams.commands ?? ACTIVE_CLI_COMMANDS;
+    const out = [];
+    for (const command of commands) {
+        const paths = whichAll(command);
+        paths.forEach((path, precedence) => {
+            const version = probe(path, precedence);
+            out.push({
+                command,
+                path,
+                version,
+                precedence,
+                versionSource: version === null ? "none" : precedence > 0 ? "package-json" : "exec",
+            });
+        });
+    }
+    return out;
+}
+function formatCandidateLine(c) {
+    const ver = (c.version ?? "unknown").replace(/\r?\n/g, " ");
+    const path = c.path.replace(/\r?\n/g, " ");
+    const command = String(c.command).replace(/\r?\n/g, " ");
+    const mark = c.precedence === 0 ? " (active)" : "";
+    return `  - ${path} → engine ${ver}${mark} [${command}]`;
+}
+function remediationLines(params) {
+    const lines = [
+        "[deft session] Remediation (higher-precedence CLI shadows the upgraded install):",
+        "  1. Align every global prefix to the same engine version, e.g.:",
+        `     ${CANONICAL_UPGRADE_COMMAND}`,
+        "     (or `pnpm add -g @deftai/directive@latest` when pnpm owns the active prefix)",
+    ];
+    if (params.active !== null) {
+        lines.push(`  2. Confirm the shell-active binary: re-open the shell, then`, `     \`${params.active.command} --version\` must report` +
+            (params.targetVersion !== null
+                ? ` engine @${params.targetVersion}.`
+                : " the upgraded engine version."));
+        lines.push(`  3. If PATH still prefers a stale prefix, put the upgraded npm/pnpm bin dir`, `     ahead of ${params.active.path}, or uninstall/upgrade that shadowing install.`);
+    }
+    else {
+        lines.push("  2. Ensure the upgraded npm/pnpm global bin directory is on PATH, then re-run", "     `deft --version` / `directive --version`.");
+    }
+    if (params.newerCandidates.length > 0) {
+        lines.push("  Competing installs (not shell-active but newer or target-matching):");
+        for (const c of params.newerCandidates) {
+            lines.push(formatCandidateLine(c));
+        }
+    }
+    return lines;
+}
+function maxPublishableVersion(versions) {
+    let best = null;
+    for (const v of versions) {
+        if (!isPublishableSemver(v))
+            continue;
+        if (best === null || compareSemver(v, best) === 1) {
+            best = v;
+        }
+    }
+    return best;
+}
+/**
+ * Default upgrade target when callers omit `targetEngineVersion` (#3233 P1):
+ * the max of (1) publishable in-process engine version and (2) versions from
+ * **non-active** PATH candidates only. The shell-active CLI must never become
+ * its own expected target (lone stale self-match).
+ */
+export function resolveDefaultActiveCliTarget(candidates, inProcessVersion) {
+    let inProcess = inProcessVersion;
+    if (inProcess === undefined) {
+        try {
+            inProcess = readCorePackageVersion();
+        }
+        catch {
+            inProcess = null;
+        }
+    }
+    // Independent sources only — exclude precedence-0 (active) versions.
+    const fromShadows = candidates.filter((c) => c.precedence > 0).map((c) => c.version);
+    return maxPublishableVersion([isPublishableSemver(inProcess) ? inProcess : null, ...fromShadows]);
+}
+/**
+ * Fail-closed check: shell-active `deft`/`directive` must match `targetVersion`
+ * (or the resolved default target), and must not be older than another PATH
+ * candidate (#3233).
+ *
+ * When no CLI is on PATH, returns ok=true (absence is covered by verify:tools /
+ * engine ladder — this gate only catches shadowing after a multi-prefix install).
+ */
+export function checkActiveCliAgainstTarget(targetVersion = null, seams = {}) {
+    const candidates = collectCandidates(seams);
+    if (candidates.length === 0) {
+        return {
+            ok: true,
+            code: 0,
+            active: null,
+            candidates,
+            targetVersion,
+            message: "active CLI check skipped (no deft/directive on PATH)",
+            lines: [],
+        };
+    }
+    const resolveTarget = seams.resolveDefaultTarget ??
+        ((cs) => resolveDefaultActiveCliTarget(cs, seams.inProcessVersion));
+    const effectiveTarget = targetVersion !== null && targetVersion.length > 0 ? targetVersion : resolveTarget(candidates);
+    // Group by command; each bare name has its own PATH-active binary.
+    const byCommand = new Map();
+    for (const c of candidates) {
+        const list = byCommand.get(c.command) ?? [];
+        list.push(c);
+        byCommand.set(c.command, list);
+    }
+    const failures = [];
+    const diagnostic = ["[deft session] CLI candidates on PATH (precedence order):"];
+    for (const c of candidates) {
+        diagnostic.push(formatCandidateLine(c));
+    }
+    let primaryActive = null;
+    const competing = [];
+    for (const [command, list] of byCommand) {
+        const active = list.find((c) => c.precedence === 0) ?? list[0];
+        if (!active)
+            continue;
+        if (primaryActive === null) {
+            primaryActive = active;
+        }
+        if (effectiveTarget !== null && effectiveTarget.length > 0) {
+            if (active.version === null) {
+                failures.push(`shell-active ${command} at ${active.path} did not report an engine version ` +
+                    `(expected ${effectiveTarget})`);
+            }
+            else if (active.version !== effectiveTarget) {
+                // Fail when active is behind the target (or simply unequal for exact match).
+                const cmp = compareSemver(active.version, effectiveTarget);
+                if (cmp === -1 || cmp === null) {
+                    failures.push(`shell-active ${command} is engine ${active.version} at ${active.path}, ` +
+                        `but upgrade target is ${effectiveTarget}`);
+                    for (const other of list) {
+                        if (other.precedence === 0)
+                            continue;
+                        if (other.version === effectiveTarget ||
+                            compareSemver(other.version, active.version) === 1) {
+                            competing.push(other);
+                        }
+                    }
+                }
+            }
+        }
+        // Multi-prefix skew: a lower-precedence candidate is strictly newer than active.
+        for (const other of list) {
+            if (other.precedence === 0)
+                continue;
+            const cmp = compareSemver(other.version, active.version);
+            if (cmp === 1) {
+                failures.push(`shell-active ${command} is engine ${active.version ?? "unknown"} at ${active.path}, ` +
+                    `but a lower-precedence install is newer (${other.version ?? "unknown"} at ${other.path})`);
+                competing.push(other);
+            }
+        }
+    }
+    if (failures.length === 0) {
+        const activeVer = primaryActive?.version ?? "unknown";
+        const activePath = primaryActive?.path ?? "(none)";
+        return {
+            ok: true,
+            code: 0,
+            active: primaryActive,
+            candidates,
+            targetVersion: effectiveTarget,
+            message: effectiveTarget !== null
+                ? `active CLI engine ${activeVer} matches target ${effectiveTarget} (${activePath})`
+                : `active CLI engine ${activeVer} is not shadowed (${activePath})`,
+            lines: [],
+        };
+    }
+    // Dedup competing by path.
+    const seenPath = new Set();
+    const uniqueCompeting = competing.filter((c) => {
+        if (seenPath.has(c.path))
+            return false;
+        seenPath.add(c.path);
+        return true;
+    });
+    const summary = `stale higher-precedence CLI after upgrade: ${failures[0]}` +
+        (failures.length > 1 ? ` (+${failures.length - 1} more)` : "");
+    const lines = [
+        `[deft session] FAIL: ${summary}`,
+        ...diagnostic,
+        ...remediationLines({
+            active: primaryActive,
+            targetVersion: effectiveTarget,
+            newerCandidates: uniqueCompeting,
+        }),
+    ];
+    return {
+        ok: false,
+        code: 1,
+        active: primaryActive,
+        candidates,
+        targetVersion: effectiveTarget,
+        message: summary,
+        lines,
+    };
+}
+//# sourceMappingURL=active-cli.js.map

package/dist/session/deposit-sha.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Deposit fingerprint for orientation fast-path (#3286).
+ *
+ * Covers all refresh inputs named by the dual-path Now AC: payload, templates,
+ * and engine version. When this fingerprint is unchanged, agents:refresh and
+ * verify:cache-fresh may print a one-line sha-match no-op.
+ */
+export declare const DEPOSIT_SHA_HEX_LEN = 12;
+/** Canonical one-line no-op message for deposit-sha fast-path (#3286). */
+export declare const DEPOSIT_SHA_MATCH_NOOP = "unchanged - sha match";
+export interface DepositShaInputs {
+    readonly engineVersion: string;
+    readonly payloadVersion: string;
+    readonly templatesHash: string;
+}
+export interface ComputeDepositShaOptions {
+    readonly projectRoot?: string;
+    readonly frameworkRoot?: string;
+    /** Inject inputs for hermetic tests (skips filesystem/version probes). */
+    readonly inputs?: Partial<DepositShaInputs>;
+    /** Override engine version probe. */
+    readonly readEngineVersion?: () => string;
+    /** Override payload version probe. */
+    readonly readPayloadVersion?: (projectRoot: string, frameworkRoot: string) => string;
+    /** Override templates hash probe. */
+    readonly readTemplatesHash?: (frameworkRoot: string) => string;
+}
+/**
+ * Hash templates that feed agents:refresh (agents-entry + related entry points).
+ * Missing templates yield a stable "missing" sentinel so the fingerprint still
+ * changes when templates appear or disappear.
+ */
+export declare function hashDepositTemplates(frameworkRoot: string): string;
+/**
+ * Resolve payload / content version for the deposit fingerprint.
+ * Prefer live generation token, then VERSION files under framework root.
+ */
+export declare function resolveDepositPayloadVersion(projectRoot: string, frameworkRoot: string): string;
+/** Resolve the three deposit-sha inputs (payload, templates, engine). */
+export declare function resolveDepositShaInputs(options?: ComputeDepositShaOptions): DepositShaInputs;
+/**
+ * Compute the 12-hex deposit fingerprint covering payload + templates + engine.
+ */
+export declare function computeDepositSha(options?: ComputeDepositShaOptions): string;
+/** True when two deposit fingerprints match (case-insensitive, trimmed). */
+export declare function depositShaMatches(a: string | null | undefined, b: string | null | undefined): boolean;
+/** One-line status for orientation / CLI stdout. */
+export declare function formatDepositShaMatchLine(surface: string): string;
+//# sourceMappingURL=deposit-sha.d.ts.map

package/dist/session/deposit-sha.js

@@ -0,0 +1,121 @@
+/**
+ * Deposit fingerprint for orientation fast-path (#3286).
+ *
+ * Covers all refresh inputs named by the dual-path Now AC: payload, templates,
+ * and engine version. When this fingerprint is unchanged, agents:refresh and
+ * verify:cache-fresh may print a one-line sha-match no-op.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { contentRoot } from "../content-root.js";
+import { readCorePackageVersion } from "../engine-version.js";
+import { readLiveGeneration } from "../freshness/generation.js";
+import { frameworkRoot as resolveAgentsFrameworkRoot } from "../platform/agents-md.js";
+export const DEPOSIT_SHA_HEX_LEN = 12;
+/** Canonical one-line no-op message for deposit-sha fast-path (#3286). */
+export const DEPOSIT_SHA_MATCH_NOOP = "unchanged - sha match";
+function sha12(material) {
+    return createHash("sha256").update(material, "utf8").digest("hex").slice(0, DEPOSIT_SHA_HEX_LEN);
+}
+function hashText(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/**
+ * Hash templates that feed agents:refresh (agents-entry + related entry points).
+ * Missing templates yield a stable "missing" sentinel so the fingerprint still
+ * changes when templates appear or disappear.
+ */
+export function hashDepositTemplates(frameworkRoot) {
+    const root = contentRoot(frameworkRoot);
+    const candidates = [
+        join(root, "templates", "agents-entry.md"),
+        join(root, "templates", "agent-prompt-preamble.md"),
+    ];
+    const parts = [];
+    for (const path of candidates) {
+        try {
+            if (!existsSync(path)) {
+                parts.push(`${path}:missing`);
+                continue;
+            }
+            parts.push(`${path}:${hashText(readFileSync(path, "utf8"))}`);
+        }
+        catch {
+            parts.push(`${path}:unreadable`);
+        }
+    }
+    return sha12(parts.join("\n"));
+}
+/**
+ * Resolve payload / content version for the deposit fingerprint.
+ * Prefer live generation token, then VERSION files under framework root.
+ */
+export function resolveDepositPayloadVersion(projectRoot, frameworkRoot) {
+    try {
+        const live = readLiveGeneration(projectRoot);
+        if (live?.contentVersion) {
+            return live.contentVersion;
+        }
+    }
+    catch {
+        // fall through
+    }
+    for (const cand of [
+        join(frameworkRoot, "VERSION"),
+        join(frameworkRoot, "scripts", "VERSION"),
+        join(projectRoot, ".deft-version"),
+    ]) {
+        try {
+            if (existsSync(cand)) {
+                const v = readFileSync(cand, "utf8").trim();
+                if (v.length > 0)
+                    return v;
+            }
+        }
+        catch {
+            // continue
+        }
+    }
+    return "unknown-payload";
+}
+/** Resolve the three deposit-sha inputs (payload, templates, engine). */
+export function resolveDepositShaInputs(options = {}) {
+    const frameworkRoot = resolveAgentsFrameworkRoot({
+        frameworkRoot: options.frameworkRoot,
+    });
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const engineVersion = options.inputs?.engineVersion ?? (options.readEngineVersion ?? readCorePackageVersion)();
+    const payloadVersion = options.inputs?.payloadVersion ??
+        (options.readPayloadVersion ?? resolveDepositPayloadVersion)(projectRoot, frameworkRoot);
+    const templatesHash = options.inputs?.templatesHash ??
+        (options.readTemplatesHash ?? hashDepositTemplates)(frameworkRoot);
+    return { engineVersion, payloadVersion, templatesHash };
+}
+/**
+ * Compute the 12-hex deposit fingerprint covering payload + templates + engine.
+ */
+export function computeDepositSha(options = {}) {
+    const inputs = resolveDepositShaInputs(options);
+    const material = [
+        `engine=${inputs.engineVersion}`,
+        `payload=${inputs.payloadVersion}`,
+        `templates=${inputs.templatesHash}`,
+    ].join("\n");
+    return sha12(material);
+}
+/** True when two deposit fingerprints match (case-insensitive, trimmed). */
+export function depositShaMatches(a, b) {
+    if (a == null || b == null)
+        return false;
+    const left = a.trim().toLowerCase();
+    const right = b.trim().toLowerCase();
+    if (left.length === 0 || right.length === 0)
+        return false;
+    return left === right;
+}
+/** One-line status for orientation / CLI stdout. */
+export function formatDepositShaMatchLine(surface) {
+    return `${surface}: ${DEPOSIT_SHA_MATCH_NOOP}`;
+}
+//# sourceMappingURL=deposit-sha.js.map