@deftai/directive-core 0.68.0 → 0.69.0

package/dist/init-deposit/scaffold.js

@@ -212,6 +212,63 @@ export function writeInstallManifest(projectDir, deftDir, fields) {
     writeFileSync(path, body, "utf8");
     return path;
 }
+/** Canonical committed pin dependency name (mirrors resolution/pin.ts). */
+export const PIN_DEPENDENCY_NAME = "@deftai/directive";
+/**
+ * Write the committed `package.json` version pin on `@deftai/directive`
+ * (exact devDependency; `"private": true` preserved) so the resolution spine
+ * has a canonical, npm-native pin to read before directive runs. This unblocks
+ * #2269 (which is gated on the pin existing).
+ *
+ * Behavior:
+ *  - existing `package.json`  -> the exact devDependency pin is set/updated;
+ *    an existing `"private"` value is preserved verbatim (never clobbered).
+ *  - absent `package.json`    -> a minimal `{ "private": true, ... }` is created.
+ *  - idempotent               -> re-running with the same pin makes no change.
+ *
+ * This is a deposit primitive; wiring it into the `init` verb flow is owned by
+ * #2265 (the init-consumes-plan child), per the #2264 scope guard.
+ */
+export function ensurePackageJsonPin(projectDir, version, io) {
+    const pinVersion = version.trim().replace(/^v/i, "");
+    const path = join(projectDir, "package.json");
+    const existed = existsSync(path);
+    let pkg = {};
+    if (existed) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                pkg = parsed;
+            }
+            else {
+                throw new Error("package.json root must be a JSON object");
+            }
+        }
+        catch (cause) {
+            throw new Error(`could not parse package.json (leaving it unchanged): ${String(cause)}`);
+        }
+    }
+    else {
+        // Fresh scaffold: a consumer deposit is a non-published workspace.
+        pkg.private = true;
+    }
+    const devDeps = typeof pkg.devDependencies === "object" &&
+        pkg.devDependencies !== null &&
+        !Array.isArray(pkg.devDependencies)
+        ? { ...pkg.devDependencies }
+        : {};
+    if (devDeps[PIN_DEPENDENCY_NAME] === pinVersion) {
+        io.printf(`package.json already pins ${PIN_DEPENDENCY_NAME}@${pinVersion} — skipping.\n`);
+        return { changed: false, pinVersion, created: false };
+    }
+    devDeps[PIN_DEPENDENCY_NAME] = pinVersion;
+    pkg.devDependencies = devDeps;
+    writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+    io.printf(existed
+        ? `package.json updated: pinned ${PIN_DEPENDENCY_NAME}@${pinVersion} (exact).\n`
+        : `package.json created: pinned ${PIN_DEPENDENCY_NAME}@${pinVersion} (exact, private).\n`);
+    return { changed: true, pinVersion, created: !existed };
+}
 export function writeAgentsMd(projectDir, deftDir, io) {
     const plan = agentsRefreshPlan(projectDir, { frameworkRoot: deftDir });
     const state = plan.state;

package/dist/init-deposit/untrack-core.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `migrate --untrack-core`: the one-time vendored→hybrid `.deft/core` un-commit
+ * (#2269). Owns the single destructive `git rm --cached -r .deft/core` index
+ * mutation in the framework — `init`/`update` only ever write the
+ * non-destructive `.gitignore` entry (boundary asserted by the colocated test).
+ *
+ * Safety contract:
+ *   - NEVER touches working-tree content. `git rm --cached` removes files from
+ *     the index only; the on-disk deposit is left intact.
+ *   - Gated on a committed `package.json` pin existing (#2264 / Decision 2):
+ *     once `.deft/core` is un-committed, content can be reconstituted from the
+ *     pinned engine, so nothing is lost. With no pin, un-committing could leave
+ *     the deposit unrecoverable, so we refuse.
+ *   - Idempotent: once the deposit is un-tracked and ignored, re-running is a
+ *     no-op that mutates nothing.
+ *
+ * The doctor detection that SURFACES this verb (the "payload tracked but should
+ * be ignored" signpost emitting `Next command: directive migrate --untrack-core`)
+ * is owned by child D (#2267); this module provides only the verb it points at.
+ *
+ * Refs #2269, #2264, #2123, #2124, #2203.
+ */
+import { type PinReadResult } from "../resolution/pin.js";
+import type { InitDepositIo } from "./constants.js";
+import { type GitLsFiles } from "./gitignore.js";
+/** The deposit path un-committed from the git index (never from the working tree). */
+export declare const UNTRACK_CORE_PATH = ".deft/core";
+export type UntrackCoreOutcome = "untracked" | "already-clean" | "refused-missing-pin" | "git-error";
+export interface UntrackCoreResult {
+    readonly outcome: UntrackCoreOutcome;
+    /** 0: untracked / already-clean · 1: refused (missing pin) · 2: git error. */
+    readonly exitCode: 0 | 1 | 2;
+    /** Whether `.deft/core` was tracked in git when the verb ran. */
+    readonly deftCoreTracked: boolean;
+    /** The committed exact pin version, or null when absent / non-exact. */
+    readonly pinVersion: string | null;
+    /** Whether the `.gitignore` reconciliation changed the file. */
+    readonly gitignoreChanged: boolean;
+    readonly message: string;
+}
+/** Outcome of the injected `git rm --cached -r <paths>` runner. */
+export interface GitRmCachedResult {
+    readonly ok: boolean;
+    /** stdout on success, or the error detail on failure. */
+    readonly detail: string;
+}
+/** Injected git runner for the destructive index mutation (default shells out). */
+export type GitRmCached = (projectDir: string, paths: readonly string[]) => GitRmCachedResult;
+export interface UntrackCoreSeams {
+    /** Probe whether `.deft/core` is git-tracked (default: `git ls-files`). */
+    gitLsFiles?: GitLsFiles;
+    /** Run `git rm --cached -r <paths>` (default: shells out to git). */
+    gitRmCached?: GitRmCached;
+    /** Read the committed `package.json` pin (default: resolution/pin.ts readPin). */
+    readPin?: (projectRoot: string) => PinReadResult;
+    /** Reconcile `.gitignore` (default: ensureUntrackCoreGitignoreLines). */
+    ensureGitignore?: (projectDir: string, io: InitDepositIo) => {
+        changed: boolean;
+        deftCoreIgnored: boolean;
+    };
+    /** Output sink for reconciliation messages (default: no-op; the CLI prints the summary). */
+    io?: InitDepositIo;
+}
+/**
+ * Orchestrate the vendored→hybrid `.deft/core` un-commit for `projectRoot`.
+ * Pure of process exit; the CLI wrapper maps {@link UntrackCoreResult.exitCode}
+ * to a process code. Three primary outcomes (untracked / already-clean /
+ * refused-missing-pin) plus a git-error fallthrough.
+ */
+export declare function untrackCore(projectRoot: string, seams?: UntrackCoreSeams): UntrackCoreResult;
+export interface RunUntrackCoreCliOptions {
+    readonly projectDir: string;
+    readonly jsonOut: boolean;
+    readonly writeOut: (text: string) => void;
+    readonly writeErr: (text: string) => void;
+    readonly seams?: UntrackCoreSeams;
+}
+/**
+ * CLI-facing wrapper: runs the un-commit, emits JSON or human output, maps the
+ * outcome to a 0/1/2 exit code. Refusals and git errors print to stderr;
+ * success prints to stdout.
+ */
+export declare function runUntrackCoreCli(options: RunUntrackCoreCliOptions): number;
+//# sourceMappingURL=untrack-core.d.ts.map

package/dist/init-deposit/untrack-core.js

@@ -0,0 +1,150 @@
+/**
+ * `migrate --untrack-core`: the one-time vendored→hybrid `.deft/core` un-commit
+ * (#2269). Owns the single destructive `git rm --cached -r .deft/core` index
+ * mutation in the framework — `init`/`update` only ever write the
+ * non-destructive `.gitignore` entry (boundary asserted by the colocated test).
+ *
+ * Safety contract:
+ *   - NEVER touches working-tree content. `git rm --cached` removes files from
+ *     the index only; the on-disk deposit is left intact.
+ *   - Gated on a committed `package.json` pin existing (#2264 / Decision 2):
+ *     once `.deft/core` is un-committed, content can be reconstituted from the
+ *     pinned engine, so nothing is lost. With no pin, un-committing could leave
+ *     the deposit unrecoverable, so we refuse.
+ *   - Idempotent: once the deposit is un-tracked and ignored, re-running is a
+ *     no-op that mutates nothing.
+ *
+ * The doctor detection that SURFACES this verb (the "payload tracked but should
+ * be ignored" signpost emitting `Next command: directive migrate --untrack-core`)
+ * is owned by child D (#2267); this module provides only the verb it points at.
+ *
+ * Refs #2269, #2264, #2123, #2124, #2203.
+ */
+import { execFileSync } from "node:child_process";
+import { PIN_DEPENDENCY_NAME, readPin } from "../resolution/pin.js";
+import { ensureUntrackCoreGitignoreLines, isDepositTrackedInGit, } from "./gitignore.js";
+/** The deposit path un-committed from the git index (never from the working tree). */
+export const UNTRACK_CORE_PATH = ".deft/core";
+/** Default `git rm --cached -r <paths>`: index-only removal, working tree preserved. */
+function defaultGitRmCached(projectDir, paths) {
+    try {
+        const out = execFileSync("git", ["rm", "--cached", "-r", "--", ...paths], {
+            cwd: projectDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { ok: true, detail: out };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return { ok: false, detail };
+    }
+}
+function refusedMissingPinMessage(pin) {
+    const reason = pin.nonExact
+        ? `package.json pins ${PIN_DEPENDENCY_NAME} with a non-exact range spec (${pin.rawSpec ?? "?"})`
+        : `no committed exact package.json pin on ${PIN_DEPENDENCY_NAME} was found`;
+    return ("directive migrate --untrack-core: refusing to run git rm --cached on .deft/core because " +
+        `${reason}. Un-committing without a committed exact pin could leave the deposit content ` +
+        "unrecoverable (nothing to reconstitute from). Write and commit an exact pin " +
+        "(e.g. via `directive init` / `directive update`), then re-run.");
+}
+/**
+ * Orchestrate the vendored→hybrid `.deft/core` un-commit for `projectRoot`.
+ * Pure of process exit; the CLI wrapper maps {@link UntrackCoreResult.exitCode}
+ * to a process code. Three primary outcomes (untracked / already-clean /
+ * refused-missing-pin) plus a git-error fallthrough.
+ */
+export function untrackCore(projectRoot, seams = {}) {
+    const gitRmCached = seams.gitRmCached ?? defaultGitRmCached;
+    const readPinFn = seams.readPin ?? readPin;
+    const ensureGitignore = seams.ensureGitignore ?? ensureUntrackCoreGitignoreLines;
+    const io = seams.io ?? { printf: () => { } };
+    const tracked = isDepositTrackedInGit(projectRoot, seams.gitLsFiles);
+    // Not tracked (or no git repo / git unavailable): nothing destructive to do.
+    // Reconcile the ignore entry so the layout is unambiguous, then report clean.
+    if (tracked !== true) {
+        const gi = ensureGitignore(projectRoot, io);
+        return {
+            outcome: "already-clean",
+            exitCode: 0,
+            deftCoreTracked: false,
+            pinVersion: readPinFn(projectRoot).pinVersion,
+            gitignoreChanged: gi.changed,
+            message: `directive migrate --untrack-core: .deft/core is not tracked in git — nothing to ` +
+                `un-commit. .gitignore ${gi.changed ? "reconciled (now ignores .deft/core/)" : "already ignores it"}.`,
+        };
+    }
+    // Tracked: gate on the committed pin so content stays reconstitutable.
+    // Refuse on either an absent pin OR a non-exact range spec — a range cannot
+    // deterministically reconstitute the exact deposit, so it is not a safe gate.
+    // The `|| pin.nonExact` makes the invariant self-documenting and robust to any
+    // future `readPin` that resolves a version alongside `nonExact: true` (#2269).
+    const pin = readPinFn(projectRoot);
+    if (pin.pinVersion === null || pin.nonExact) {
+        return {
+            outcome: "refused-missing-pin",
+            exitCode: 1,
+            deftCoreTracked: true,
+            pinVersion: null,
+            gitignoreChanged: false,
+            message: refusedMissingPinMessage(pin),
+        };
+    }
+    const rm = gitRmCached(projectRoot, [UNTRACK_CORE_PATH]);
+    if (!rm.ok) {
+        return {
+            outcome: "git-error",
+            exitCode: 2,
+            deftCoreTracked: true,
+            pinVersion: pin.pinVersion,
+            gitignoreChanged: false,
+            message: `directive migrate --untrack-core: git rm --cached failed: ${rm.detail.trim()}`,
+        };
+    }
+    const gi = ensureGitignore(projectRoot, io);
+    return {
+        outcome: "untracked",
+        exitCode: 0,
+        deftCoreTracked: true,
+        pinVersion: pin.pinVersion,
+        gitignoreChanged: gi.changed,
+        message: `directive migrate --untrack-core: removed ${UNTRACK_CORE_PATH} from the git index ` +
+            `(working tree untouched); pin ${pin.pinVersion} lets \`directive update\` reconstitute ` +
+            `content. .gitignore ${gi.changed ? "reconciled (now ignores .deft/core/)" : "already ignores it"}. ` +
+            "Commit the removal to complete the un-commit.",
+    };
+}
+function buildUntrackCoreSummaryJson(result, projectDir) {
+    return {
+        success: result.exitCode === 0,
+        action: "migrate-untrack-core",
+        outcome: result.outcome,
+        exit_code: result.exitCode,
+        project_dir: projectDir,
+        deft_core_tracked: result.deftCoreTracked,
+        pin_version: result.pinVersion,
+        gitignore_changed: result.gitignoreChanged,
+        message: result.message,
+    };
+}
+/**
+ * CLI-facing wrapper: runs the un-commit, emits JSON or human output, maps the
+ * outcome to a 0/1/2 exit code. Refusals and git errors print to stderr;
+ * success prints to stdout.
+ */
+export function runUntrackCoreCli(options) {
+    const result = untrackCore(options.projectDir, { ...options.seams, io: { printf: () => { } } });
+    if (options.jsonOut) {
+        options.writeOut(`${JSON.stringify(buildUntrackCoreSummaryJson(result, options.projectDir), null, 2)}\n`);
+        return result.exitCode;
+    }
+    if (result.exitCode === 0) {
+        options.writeOut(`${result.message}\n`);
+    }
+    else {
+        options.writeErr(`${result.message}\n`);
+    }
+    return result.exitCode;
+}
+//# sourceMappingURL=untrack-core.js.map

package/dist/resolution/classify.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Orthogonal fact-set classifier for the resolution spine (#2264 / epic #2203).
+ *
+ * `classify()` returns a flat, independent fact-set — never a single collapsed
+ * enum. `plan()` owns the collapse into one recommended action, so there is
+ * exactly one precedence table in the system.
+ *
+ * It REUSES the existing detectors rather than re-implementing them:
+ *  - pre-cutover artifacts    -> `../vbrief-validate/precutover.ts`
+ *  - managed-section sha      -> `../platform/agents-md.ts::parseManagedSectionAttrs`
+ *  - deposited payload version-> `../doctor/manifest.ts` + `../init-deposit/constants.ts`
+ *  - committed pin            -> `./pin.ts`
+ */
+import type { ResolutionFacts } from "@deftai/directive-types";
+/** Result of probing whether an engine is reachable in the execution environment. */
+export interface EngineProbeResult {
+    readonly reachable: boolean;
+    readonly version: string | null;
+}
+export interface ClassifySeams {
+    readonly isFile?: (p: string) => boolean;
+    readonly isDir?: (p: string) => boolean;
+    readonly readText?: (p: string) => string | null;
+    /**
+     * Probe for a reachable engine IN THE ENVIRONMENT THE CALLER IS RUNNING IN.
+     * Injected so classification is deterministic + offline in tests; the default
+     * shells out to the `directive` / `deft` CLI (the #2124 execution-env probe).
+     */
+    readonly engineProbe?: () => EngineProbeResult;
+    /** Pre-cutover probe; defaults to the shared `detectPreCutover` detector. */
+    readonly preCutoverProbe?: (cwd: string) => boolean;
+}
+/** Default engine probe: try `directive --version`, then `deft --version`. */
+export declare function defaultEngineProbe(): EngineProbeResult;
+/**
+ * Classify a project directory into the orthogonal resolution fact-set. All I/O
+ * is behind injectable seams so callers (tests, sandboxed runtimes) can supply a
+ * deterministic view of the filesystem and the engine-reachability probe.
+ */
+export declare function classify(cwd: string, seams?: ClassifySeams): ResolutionFacts;
+//# sourceMappingURL=classify.d.ts.map

package/dist/resolution/classify.js

@@ -0,0 +1,138 @@
+/**
+ * Orthogonal fact-set classifier for the resolution spine (#2264 / epic #2203).
+ *
+ * `classify()` returns a flat, independent fact-set — never a single collapsed
+ * enum. `plan()` owns the collapse into one recommended action, so there is
+ * exactly one precedence table in the system.
+ *
+ * It REUSES the existing detectors rather than re-implementing them:
+ *  - pre-cutover artifacts    -> `../vbrief-validate/precutover.ts`
+ *  - managed-section sha      -> `../platform/agents-md.ts::parseManagedSectionAttrs`
+ *  - deposited payload version-> `../doctor/manifest.ts` + `../init-deposit/constants.ts`
+ *  - committed pin            -> `./pin.ts`
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { locateManifest, manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
+import { CANONICAL_INSTALL_ROOT } from "../init-deposit/constants.js";
+import { extractManagedSection, parseManagedSectionAttrs } from "../platform/agents-md.js";
+import { detectPreCutover } from "../vbrief-validate/precutover.js";
+import { readPin } from "./pin.js";
+/** App-source markers used for the `hasAppCode` heuristic. */
+const APP_CODE_MARKERS = [
+    "package.json",
+    "pyproject.toml",
+    "go.mod",
+    "Cargo.toml",
+    "pom.xml",
+    "build.gradle",
+    "Gemfile",
+    "src",
+];
+const SEMVER_IN_TEXT_RE = /(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/;
+function defaultIsFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultIsDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultReadText(p) {
+    try {
+        if (!existsSync(p))
+            return null;
+        return readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function probeEngineVersion(binary) {
+    try {
+        const out = execFileSync(binary, ["--version"], {
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const match = SEMVER_IN_TEXT_RE.exec(out);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Default engine probe: try `directive --version`, then `deft --version`. */
+export function defaultEngineProbe() {
+    for (const binary of ["directive", "deft"]) {
+        const version = probeEngineVersion(binary);
+        if (version !== null) {
+            return { reachable: true, version };
+        }
+    }
+    return { reachable: false, version: null };
+}
+function detectAppCode(cwd, isFile, isDir) {
+    return APP_CODE_MARKERS.some((marker) => marker === "src" ? isDir(join(cwd, marker)) : isFile(join(cwd, marker)));
+}
+function readManagedSection(cwd, readText) {
+    const text = readText(join(cwd, "AGENTS.md"));
+    if (text === null)
+        return { hasManagedSection: false, managedSectionSha: null };
+    const section = extractManagedSection(text);
+    if (section === null)
+        return { hasManagedSection: false, managedSectionSha: null };
+    const attrs = parseManagedSectionAttrs(section);
+    return { hasManagedSection: true, managedSectionSha: attrs?.sha ?? null };
+}
+function readPayloadVersion(cwd, hasDeftCore, isFile, readText) {
+    if (!hasDeftCore)
+        return null;
+    const manifestPath = locateManifest(cwd, CANONICAL_INSTALL_ROOT, isFile);
+    if (manifestPath === null)
+        return null;
+    const text = readText(manifestPath);
+    if (text === null)
+        return null;
+    return manifestTagToVersion(parseInstallManifest(text));
+}
+/**
+ * Classify a project directory into the orthogonal resolution fact-set. All I/O
+ * is behind injectable seams so callers (tests, sandboxed runtimes) can supply a
+ * deterministic view of the filesystem and the engine-reachability probe.
+ */
+export function classify(cwd, seams = {}) {
+    const isFile = seams.isFile ?? defaultIsFile;
+    const isDir = seams.isDir ?? defaultIsDir;
+    const readText = seams.readText ?? defaultReadText;
+    const engineProbe = seams.engineProbe ?? defaultEngineProbe;
+    const preCutoverProbe = seams.preCutoverProbe ?? ((dir) => detectPreCutover(dir).preCutover);
+    const hasDeftCore = isDir(join(cwd, CANONICAL_INSTALL_ROOT));
+    const { hasManagedSection, managedSectionSha } = readManagedSection(cwd, readText);
+    const engine = engineProbe();
+    const pin = readPin(cwd, { isFile, readText });
+    return {
+        hasGit: isDir(join(cwd, ".git")) || isFile(join(cwd, ".git")),
+        hasAppCode: detectAppCode(cwd, isFile, isDir),
+        hasDeftCore,
+        deftCorePayloadVersion: readPayloadVersion(cwd, hasDeftCore, isFile, readText),
+        hasManagedSection,
+        managedSectionSha,
+        hasVbrief: isDir(join(cwd, "vbrief")),
+        hasXbrief: isDir(join(cwd, "xbrief")),
+        preCutoverArtifacts: preCutoverProbe(cwd),
+        engineReachable: engine.reachable,
+        engineVersion: engine.version,
+        pinVersion: pin.pinVersion,
+    };
+}
+//# sourceMappingURL=classify.js.map

package/dist/resolution/engine-ladder.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Global-first engine-resolution ladder for the resolution spine (#2264, from #2124).
+ *
+ * The defect this closes is `execution-env != install-env`: an agent can read
+ * every rule in `.deft/core/` yet execute no gate because the engine that is
+ * reachable in the environment it is ACTUALLY running in is absent or stale.
+ * The ladder detects that mismatch and self-heals only then:
+ *
+ *   1. global `deft` reachable AND >= pin                       -> use it
+ *   2. local `.deft/.cli/<platform>` reachable, intact, >= pin  -> use it
+ *   3. must install:
+ *      a. registry up + global prefix writable                 -> npm i -g @deftai/directive@<pin>
+ *      b. registry up + global prefix NOT writable (sandbox)    -> npm install --prefix .deft/.cli/<platform>
+ *      c. registry down + staged tarball                        -> install from staged payload
+ *      d. registry down + no tarball                            -> hard-fail ("stage this")
+ *
+ * `decideEngineLadder` is a PURE decision function (no I/O). The side-effecting
+ * install is factored behind an injected runner in `resolveEngine` so the whole
+ * self-heal path is unit-testable without touching the network.
+ */
+import type { IntegrityResult } from "./integrity.js";
+export type LadderRung = "global" | "local" | "install-global" | "install-sandbox" | "install-staged" | "hard-fail";
+export interface LocalEngineFacts {
+    /** Version reported by the local engine, or null. */
+    readonly version: string | null;
+    /** Integrity classification of `.deft/.cli/<platform>`. */
+    readonly integrity: IntegrityResult;
+}
+export interface LadderFacts {
+    /** Canonical committed pin. */
+    readonly pinVersion: string | null;
+    /** Version of the globally-reachable engine, or null when absent. */
+    readonly globalEngineVersion: string | null;
+    /** Local engine facts, or null when never installed. */
+    readonly localEngine: LocalEngineFacts | null;
+    /** The npm registry is reachable. */
+    readonly registryUp: boolean;
+    /** The global npm prefix is writable (false inside a sandbox). */
+    readonly globalPrefixWritable: boolean;
+    /** A pre-staged tarball / vendored payload is available for offline install. */
+    readonly stagedTarballAvailable: boolean;
+    /** Platform id (for trace / install target). */
+    readonly platform: string;
+}
+export interface LadderDecision {
+    readonly rung: LadderRung;
+    /** True when the engine is resolved WITHOUT an install (global or local). */
+    readonly usable: boolean;
+    /** Version the ladder resolved to when usable, else null. */
+    readonly resolvedVersion: string | null;
+    /** Structured trace of every rung evaluated. */
+    readonly trace: string;
+    /** One-line reason for the chosen rung. */
+    readonly reason: string;
+}
+/**
+ * Pure global-first ladder decision. Emits a structured trace describing each
+ * rung it evaluated and why it was skipped or chosen.
+ */
+export declare function decideEngineLadder(facts: LadderFacts): LadderDecision;
+/** Outcome of a side-effecting engine install. */
+export interface EngineInstallOutcome {
+    readonly installed: boolean;
+    /** Version the install produced, or null on failure. */
+    readonly version: string | null;
+    readonly detail: string;
+}
+/** Injected side-effecting install runner (npm i -g / --prefix / staged). */
+export type EngineInstallRunner = (context: {
+    readonly rung: Extract<LadderRung, "install-global" | "install-sandbox" | "install-staged">;
+    readonly pinVersion: string | null;
+    readonly platform: string;
+}) => EngineInstallOutcome;
+/** Injected content re-projection (`update`) run after a fresh install. */
+export type ReprojectRunner = (version: string | null) => void;
+export interface ResolveEngineOptions {
+    readonly installRunner?: EngineInstallRunner;
+    readonly reproject?: ReprojectRunner;
+}
+export interface EngineResolution {
+    readonly decision: LadderDecision;
+    /** The install outcome when a rung required an install, else null. */
+    readonly installOutcome: EngineInstallOutcome | null;
+    /** The engine version resolved after any install, or null when unresolved. */
+    readonly resolvedVersion: string | null;
+    /** True when the ladder healed a mismatch (installed) with zero manual steps. */
+    readonly selfHealed: boolean;
+    /** Full structured trace including any install + re-projection. */
+    readonly trace: string;
+}
+/**
+ * Resolve the engine by composing the pure ladder decision with an injected
+ * install runner. When a rung requires an install, the runner performs it and
+ * (on success) the re-projection runner forward-migrates content — yielding the
+ * "self-heals with zero manual npm/PATH steps" behavior with a structured trace.
+ */
+export declare function resolveEngine(facts: LadderFacts, options?: ResolveEngineOptions): EngineResolution;
+//# sourceMappingURL=engine-ladder.d.ts.map