@deftai/directive-core 0.68.1 → 0.69.0

package/dist/resolution/engine-ladder.js

@@ -0,0 +1,185 @@
+/**
+ * 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 { semverGte } from "./pin.js";
+function fmt(version) {
+    return version ?? "absent";
+}
+/**
+ * Pure global-first ladder decision. Emits a structured trace describing each
+ * rung it evaluated and why it was skipped or chosen.
+ */
+export function decideEngineLadder(facts) {
+    const { pinVersion } = facts;
+    const steps = [];
+    // Rung 1: global engine.
+    if (facts.globalEngineVersion !== null && semverGte(facts.globalEngineVersion, pinVersion)) {
+        steps.push(`global: ${fmt(facts.globalEngineVersion)} >= pin ${fmt(pinVersion)} -> use`);
+        return {
+            rung: "global",
+            usable: true,
+            resolvedVersion: facts.globalEngineVersion,
+            trace: steps.join("; "),
+            reason: `global engine ${facts.globalEngineVersion} satisfies pin ${fmt(pinVersion)}`,
+        };
+    }
+    if (facts.globalEngineVersion === null) {
+        steps.push("global: absent");
+    }
+    else {
+        steps.push(`global: ${facts.globalEngineVersion} < pin ${fmt(pinVersion)}`);
+    }
+    // Rung 2: local sandbox engine (must be intact AND >= pin).
+    const local = facts.localEngine;
+    if (local !== null) {
+        if (!local.integrity.usable) {
+            steps.push(local.integrity.partial
+                ? `local: partial install -> not-usable`
+                : `local: ${local.integrity.reason}`);
+        }
+        else if (!semverGte(local.version, pinVersion)) {
+            steps.push(`local: ${fmt(local.version)} < pin ${fmt(pinVersion)}`);
+        }
+        else {
+            steps.push(`local: ${fmt(local.version)} >= pin ${fmt(pinVersion)} -> use`);
+            return {
+                rung: "local",
+                usable: true,
+                resolvedVersion: local.version,
+                trace: steps.join("; "),
+                reason: `local engine ${local.version} satisfies pin ${fmt(pinVersion)}`,
+            };
+        }
+    }
+    else {
+        steps.push("local: absent");
+    }
+    // Rung 3: must install.
+    if (facts.registryUp && facts.globalPrefixWritable) {
+        steps.push(`install: npm i -g @deftai/directive@${fmt(pinVersion)}`);
+        return {
+            rung: "install-global",
+            usable: false,
+            resolvedVersion: null,
+            trace: steps.join("; "),
+            reason: "registry up and global prefix writable -> global install",
+        };
+    }
+    if (facts.registryUp && !facts.globalPrefixWritable) {
+        steps.push(`install: npm install --prefix .deft/.cli/${facts.platform} @deftai/directive@${fmt(pinVersion)}`);
+        return {
+            rung: "install-sandbox",
+            usable: false,
+            resolvedVersion: null,
+            trace: steps.join("; "),
+            reason: "registry up but global prefix not writable (sandbox) -> --prefix install",
+        };
+    }
+    if (!facts.registryUp && facts.stagedTarballAvailable) {
+        steps.push("install: staged tarball / vendored payload");
+        return {
+            rung: "install-staged",
+            usable: false,
+            resolvedVersion: null,
+            trace: steps.join("; "),
+            reason: "registry down but staged tarball available -> offline install",
+        };
+    }
+    steps.push("hard-fail: registry down and no staged tarball");
+    return {
+        rung: "hard-fail",
+        usable: false,
+        resolvedVersion: null,
+        trace: steps.join("; "),
+        reason: "registry down and no staged tarball -- stage a payload to proceed",
+    };
+}
+const INSTALL_RUNGS = new Set([
+    "install-global",
+    "install-sandbox",
+    "install-staged",
+]);
+/**
+ * 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 function resolveEngine(facts, options = {}) {
+    const decision = decideEngineLadder(facts);
+    const steps = [decision.trace];
+    if (decision.usable) {
+        return {
+            decision,
+            installOutcome: null,
+            resolvedVersion: decision.resolvedVersion,
+            selfHealed: false,
+            trace: steps.join("; "),
+        };
+    }
+    if (decision.rung === "hard-fail" || !INSTALL_RUNGS.has(decision.rung)) {
+        return {
+            decision,
+            installOutcome: null,
+            resolvedVersion: null,
+            selfHealed: false,
+            trace: steps.join("; "),
+        };
+    }
+    const runner = options.installRunner;
+    if (!runner) {
+        steps.push("install: deferred (no install runner supplied)");
+        return {
+            decision,
+            installOutcome: null,
+            resolvedVersion: null,
+            selfHealed: false,
+            trace: steps.join("; "),
+        };
+    }
+    const outcome = runner({
+        rung: decision.rung,
+        pinVersion: facts.pinVersion,
+        platform: facts.platform,
+    });
+    if (!outcome.installed) {
+        steps.push(`install failed: ${outcome.detail}`);
+        return {
+            decision,
+            installOutcome: outcome,
+            resolvedVersion: null,
+            selfHealed: false,
+            trace: steps.join("; "),
+        };
+    }
+    steps.push(`installed ${decision.rung} -> ${fmt(outcome.version)}`);
+    if (options.reproject) {
+        options.reproject(outcome.version);
+        steps.push(`re-projected content ${fmt(outcome.version)}`);
+    }
+    return {
+        decision,
+        installOutcome: outcome,
+        resolvedVersion: outcome.version,
+        selfHealed: true,
+        trace: steps.join("; "),
+    };
+}
+//# sourceMappingURL=engine-ladder.js.map

package/dist/resolution/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolution spine (keystone #2264 / epic #2203) — shared library primitives.
+ *
+ * The classifier (`classify`) produces the orthogonal fact-set; `plan()` applies
+ * one ordered precedence table and emits the versioned public resolution-plan-v1
+ * schema (the single source of truth). The engine ladder, local-engine integrity
+ * check, three-band skew policy, and pin/VERSION/sha reconciliation are the
+ * supporting primitives that init / update / doctor / headless (children B–E)
+ * consume — this module ships them; it does NOT rewire verb behavior.
+ */
+export { RESOLUTION_ENCODINGS, RESOLUTION_MODES, RESOLUTION_PLAN_SCHEMA_VERSION, type ResolutionEncoding, type ResolutionFacts, type ResolutionFile, type ResolutionMode, type ResolutionNextAction, type ResolutionPlan, } from "@deftai/directive-types";
+export { type ClassifySeams, classify, defaultEngineProbe, type EngineProbeResult, } from "./classify.js";
+export { decideEngineLadder, type EngineInstallOutcome, type EngineInstallRunner, type EngineResolution, type LadderDecision, type LadderFacts, type LadderRung, type LocalEngineFacts, type ReprojectRunner, type ResolveEngineOptions, resolveEngine, } from "./engine-ladder.js";
+export { checkLocalEngineIntegrity, type IntegrityResult, type IntegritySeams, LOCAL_ENGINE_MARKERS, LOCAL_ENGINE_ROOT, localEnginePlatformDir, } from "./integrity.js";
+export { DEFAULT_PACKAGE_MANAGER, type DetectPackageManagerInput, detectPackageManager, ENGINE_PACKAGE, PACKAGE_MANAGERS, type PackageManager, type PackageManagerCommands, renderEphemeral, renderGlobalInstall, renderPackageManagerCommands, renderProjectInstall, } from "./package-manager.js";
+export { compareSemver, isExactPin, PIN_DEPENDENCY_NAME, type PinReadResult, type PinReadSeams, parseSemver, type ReconcileInputs, type ReconcileResult, readPin, reconcileVersions, type SemverTriple, semverGte, } from "./pin.js";
+export { type PlanOptions, plan } from "./plan.js";
+export { ACCEPT_ENGINE_SKEW_ENV, DEFAULT_ENGINE_SKEW_WINDOW, evaluateSkew, type SkewBand, type SkewDecision, type SkewOptions, type SkewResult, } from "./skew-policy.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/resolution/index.js

@@ -0,0 +1,19 @@
+/**
+ * Resolution spine (keystone #2264 / epic #2203) — shared library primitives.
+ *
+ * The classifier (`classify`) produces the orthogonal fact-set; `plan()` applies
+ * one ordered precedence table and emits the versioned public resolution-plan-v1
+ * schema (the single source of truth). The engine ladder, local-engine integrity
+ * check, three-band skew policy, and pin/VERSION/sha reconciliation are the
+ * supporting primitives that init / update / doctor / headless (children B–E)
+ * consume — this module ships them; it does NOT rewire verb behavior.
+ */
+export { RESOLUTION_ENCODINGS, RESOLUTION_MODES, RESOLUTION_PLAN_SCHEMA_VERSION, } from "@deftai/directive-types";
+export { classify, defaultEngineProbe, } from "./classify.js";
+export { decideEngineLadder, resolveEngine, } from "./engine-ladder.js";
+export { checkLocalEngineIntegrity, LOCAL_ENGINE_MARKERS, LOCAL_ENGINE_ROOT, localEnginePlatformDir, } from "./integrity.js";
+export { DEFAULT_PACKAGE_MANAGER, detectPackageManager, ENGINE_PACKAGE, PACKAGE_MANAGERS, renderEphemeral, renderGlobalInstall, renderPackageManagerCommands, renderProjectInstall, } from "./package-manager.js";
+export { compareSemver, isExactPin, PIN_DEPENDENCY_NAME, parseSemver, readPin, reconcileVersions, semverGte, } from "./pin.js";
+export { plan } from "./plan.js";
+export { ACCEPT_ENGINE_SKEW_ENV, DEFAULT_ENGINE_SKEW_WINDOW, evaluateSkew, } from "./skew-policy.js";
+//# sourceMappingURL=index.js.map

package/dist/resolution/integrity.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Local-engine integrity check for the resolution spine (#2264, from #2124).
+ *
+ * A locally-installed engine at `.deft/.cli/<platform>` is only usable when the
+ * install completed. A present-but-partial directory (an interrupted
+ * `npm install --prefix`) must be treated as NOT-USABLE — otherwise the ladder
+ * would select a half-installed engine and fail at execution time instead of
+ * falling through to a clean re-install.
+ */
+/** Root of the sandbox-local engine install, relative to the project root. */
+export declare const LOCAL_ENGINE_ROOT = ".deft/.cli";
+/**
+ * Marker paths (relative to the platform install dir) that MUST all exist for a
+ * local engine to count as a completed, usable install. `package.json` marks the
+ * install root; the `directive` bin under `node_modules/.bin` marks that npm
+ * finished linking the executable.
+ */
+export declare const LOCAL_ENGINE_MARKERS: readonly string[];
+export interface IntegritySeams {
+    readonly isFile?: (p: string) => boolean;
+    readonly isDir?: (p: string) => boolean;
+    readonly platform?: string;
+}
+export interface IntegrityResult {
+    /** The install is complete and the engine may be selected. */
+    readonly usable: boolean;
+    /** The platform install directory exists at all (vs. wholly absent). */
+    readonly present: boolean;
+    /** Present but missing required markers (interrupted install). */
+    readonly partial: boolean;
+    /** Absolute-relative platform install directory that was probed. */
+    readonly platformDir: string;
+    /** Marker paths that were missing. */
+    readonly missingMarkers: readonly string[];
+    /** Human-facing reason. */
+    readonly reason: string;
+}
+/** Resolve the platform-specific local engine directory (e.g. `.deft/.cli/linux`). */
+export declare function localEnginePlatformDir(projectRoot: string, platform?: string): string;
+/**
+ * Classify the local engine install at `.deft/.cli/<platform>`.
+ *
+ * - wholly absent            -> `{ usable: false, present: false, partial: false }`
+ * - present, all markers     -> `{ usable: true,  present: true,  partial: false }`
+ * - present, missing markers -> `{ usable: false, present: true,  partial: true  }`
+ */
+export declare function checkLocalEngineIntegrity(projectRoot: string, seams?: IntegritySeams): IntegrityResult;
+//# sourceMappingURL=integrity.d.ts.map

package/dist/resolution/integrity.js

@@ -0,0 +1,80 @@
+/**
+ * Local-engine integrity check for the resolution spine (#2264, from #2124).
+ *
+ * A locally-installed engine at `.deft/.cli/<platform>` is only usable when the
+ * install completed. A present-but-partial directory (an interrupted
+ * `npm install --prefix`) must be treated as NOT-USABLE — otherwise the ladder
+ * would select a half-installed engine and fail at execution time instead of
+ * falling through to a clean re-install.
+ */
+import { existsSync } from "node:fs";
+import { platform as osPlatform } from "node:os";
+import { join } from "node:path";
+/** Root of the sandbox-local engine install, relative to the project root. */
+export const LOCAL_ENGINE_ROOT = ".deft/.cli";
+/**
+ * Marker paths (relative to the platform install dir) that MUST all exist for a
+ * local engine to count as a completed, usable install. `package.json` marks the
+ * install root; the `directive` bin under `node_modules/.bin` marks that npm
+ * finished linking the executable.
+ */
+export const LOCAL_ENGINE_MARKERS = [
+    "package.json",
+    join("node_modules", ".bin", "directive"),
+];
+function defaultIsFile(p) {
+    try {
+        return existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the platform-specific local engine directory (e.g. `.deft/.cli/linux`). */
+export function localEnginePlatformDir(projectRoot, platform) {
+    const plat = platform ?? osPlatform();
+    return join(projectRoot, LOCAL_ENGINE_ROOT, plat);
+}
+/**
+ * Classify the local engine install at `.deft/.cli/<platform>`.
+ *
+ * - wholly absent            -> `{ usable: false, present: false, partial: false }`
+ * - present, all markers     -> `{ usable: true,  present: true,  partial: false }`
+ * - present, missing markers -> `{ usable: false, present: true,  partial: true  }`
+ */
+export function checkLocalEngineIntegrity(projectRoot, seams = {}) {
+    const isFile = seams.isFile ?? defaultIsFile;
+    const isDir = seams.isDir ?? seams.isFile ?? defaultIsFile;
+    const platformDir = localEnginePlatformDir(projectRoot, seams.platform);
+    const rootPresent = isDir(platformDir);
+    const missingMarkers = LOCAL_ENGINE_MARKERS.filter((marker) => !isFile(join(platformDir, marker)));
+    if (!rootPresent && missingMarkers.length === LOCAL_ENGINE_MARKERS.length) {
+        return {
+            usable: false,
+            present: false,
+            partial: false,
+            platformDir,
+            missingMarkers,
+            reason: `no local engine at ${platformDir}`,
+        };
+    }
+    if (missingMarkers.length > 0) {
+        return {
+            usable: false,
+            present: true,
+            partial: true,
+            platformDir,
+            missingMarkers,
+            reason: `partial local engine at ${platformDir} (missing: ${missingMarkers.join(", ")}) -- treated as not-usable`,
+        };
+    }
+    return {
+        usable: true,
+        present: true,
+        partial: false,
+        platformDir,
+        missingMarkers: [],
+        reason: `intact local engine at ${platformDir}`,
+    };
+}
+//# sourceMappingURL=integrity.js.map

package/dist/resolution/package-manager.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Package-manager abstraction for the resolution spine (#2197, from #2264).
+ *
+ * The documented install/upgrade path historically hard-coded npm
+ * (`npm i -g @deftai/directive`). pnpm-managed setups have no first-class
+ * flow, and mixing an npm global into a pnpm environment breaks PATH/shim/store
+ * consistency. This module makes the *command rendering* package-manager aware
+ * so the resolution plan and doctor emit the right form for the active manager.
+ *
+ * Two load-bearing facts keep this small (locked on issue #2197):
+ *   1. NO additional registry. pnpm resolves from the same npm registry
+ *      (`registry.npmjs.org`) by default; the published `@deftai/directive`
+ *      tarball is unchanged. No renderer here ever emits a `--registry` flag.
+ *   2. The internal `.deft/.cli/<platform>` sandbox vendoring STAYS on npm
+ *      (its `node_modules/.bin` layout is validated by `integrity.ts` and is
+ *      gitignored / package-manager-invisible). Only the global, project-local,
+ *      ephemeral, and upgrade command forms vary by package manager.
+ *
+ * Every function here is PURE (no I/O): detection consumes an injected fact-set
+ * so the whole surface is unit-testable without touching the filesystem or env.
+ */
+export type PackageManager = "npm" | "pnpm";
+export declare const PACKAGE_MANAGERS: readonly PackageManager[];
+export declare const DEFAULT_PACKAGE_MANAGER: PackageManager;
+/** Canonical published engine package name. */
+export declare const ENGINE_PACKAGE = "@deftai/directive";
+export interface DetectPackageManagerInput {
+    /** Environment map (reads `DEFT_PACKAGE_MANAGER` and `npm_config_user_agent`). */
+    readonly env?: NodeJS.ProcessEnv;
+    /** The `packageManager` field from the project package.json (Corepack), if any. */
+    readonly packageManagerField?: string | null;
+    /** Whether a `pnpm-lock.yaml` is present at the project root. */
+    readonly pnpmLockPresent?: boolean;
+}
+/**
+ * Detect the active package manager. Precedence (first match wins):
+ *   1. `DEFT_PACKAGE_MANAGER` env override
+ *   2. `packageManager` field / Corepack shim
+ *   3. `pnpm-lock.yaml` present
+ *   4. `npm_config_user_agent` (set by the manager that spawned the process)
+ *   5. default: npm
+ */
+export declare function detectPackageManager(input?: DetectPackageManagerInput): PackageManager;
+/**
+ * Render a global install command, e.g. `npm i -g @deftai/directive@0.65.0`
+ * (npm) or `pnpm add -g @deftai/directive@0.65.0` (pnpm). `spec` is the full
+ * package spec including any `@version` suffix.
+ */
+export declare function renderGlobalInstall(pm: PackageManager, spec?: string): string;
+/**
+ * Render a project-local (dev-dependency) install command. pnpm-managed repos
+ * that prefer not to install globally use this.
+ */
+export declare function renderProjectInstall(pm: PackageManager, spec?: string): string;
+/**
+ * Render an ephemeral (no-install) invocation, e.g. `npx @deftai/directive update`
+ * (npm) or `pnpm dlx @deftai/directive update` (pnpm).
+ */
+export declare function renderEphemeral(pm: PackageManager, subcommand: string, pkg?: string): string;
+export interface PackageManagerCommands {
+    readonly packageManager: PackageManager;
+    /** Global install of the engine at the given spec. */
+    readonly globalInstall: string;
+    /** Project-local (dev-dependency) install of the engine. */
+    readonly projectInstall: string;
+    /** Ephemeral `update` invocation. */
+    readonly ephemeralUpdate: string;
+    /** The canonical upgrade one-liner (global install of `@latest`). */
+    readonly upgradeOneLiner: string;
+}
+/**
+ * Render the full command matrix for a package manager at a given spec
+ * (defaults to `@latest`). Single-sourced so docs, doctor, and the plan all
+ * derive from the same renderers.
+ */
+export declare function renderPackageManagerCommands(pm: PackageManager, spec?: string): PackageManagerCommands;
+//# sourceMappingURL=package-manager.d.ts.map

package/dist/resolution/package-manager.js

@@ -0,0 +1,103 @@
+/**
+ * Package-manager abstraction for the resolution spine (#2197, from #2264).
+ *
+ * The documented install/upgrade path historically hard-coded npm
+ * (`npm i -g @deftai/directive`). pnpm-managed setups have no first-class
+ * flow, and mixing an npm global into a pnpm environment breaks PATH/shim/store
+ * consistency. This module makes the *command rendering* package-manager aware
+ * so the resolution plan and doctor emit the right form for the active manager.
+ *
+ * Two load-bearing facts keep this small (locked on issue #2197):
+ *   1. NO additional registry. pnpm resolves from the same npm registry
+ *      (`registry.npmjs.org`) by default; the published `@deftai/directive`
+ *      tarball is unchanged. No renderer here ever emits a `--registry` flag.
+ *   2. The internal `.deft/.cli/<platform>` sandbox vendoring STAYS on npm
+ *      (its `node_modules/.bin` layout is validated by `integrity.ts` and is
+ *      gitignored / package-manager-invisible). Only the global, project-local,
+ *      ephemeral, and upgrade command forms vary by package manager.
+ *
+ * Every function here is PURE (no I/O): detection consumes an injected fact-set
+ * so the whole surface is unit-testable without touching the filesystem or env.
+ */
+export const PACKAGE_MANAGERS = ["npm", "pnpm"];
+export const DEFAULT_PACKAGE_MANAGER = "npm";
+/** Canonical published engine package name. */
+export const ENGINE_PACKAGE = "@deftai/directive";
+function normalizePackageManager(value) {
+    const v = value.trim().toLowerCase();
+    if (v.startsWith("pnpm"))
+        return "pnpm";
+    if (v.startsWith("npm"))
+        return "npm";
+    return null;
+}
+/**
+ * Detect the active package manager. Precedence (first match wins):
+ *   1. `DEFT_PACKAGE_MANAGER` env override
+ *   2. `packageManager` field / Corepack shim
+ *   3. `pnpm-lock.yaml` present
+ *   4. `npm_config_user_agent` (set by the manager that spawned the process)
+ *   5. default: npm
+ */
+export function detectPackageManager(input = {}) {
+    const env = input.env ?? {};
+    const override = env.DEFT_PACKAGE_MANAGER;
+    if (typeof override === "string" && override.trim() !== "") {
+        const pm = normalizePackageManager(override);
+        if (pm)
+            return pm;
+    }
+    if (input.packageManagerField != null && input.packageManagerField.trim() !== "") {
+        const pm = normalizePackageManager(input.packageManagerField);
+        if (pm)
+            return pm;
+    }
+    if (input.pnpmLockPresent)
+        return "pnpm";
+    const ua = env.npm_config_user_agent;
+    if (typeof ua === "string" && ua.trim() !== "") {
+        const pm = normalizePackageManager(ua);
+        if (pm)
+            return pm;
+    }
+    return DEFAULT_PACKAGE_MANAGER;
+}
+/**
+ * Render a global install command, e.g. `npm i -g @deftai/directive@0.65.0`
+ * (npm) or `pnpm add -g @deftai/directive@0.65.0` (pnpm). `spec` is the full
+ * package spec including any `@version` suffix.
+ */
+export function renderGlobalInstall(pm, spec = ENGINE_PACKAGE) {
+    return pm === "pnpm" ? `pnpm add -g ${spec}` : `npm i -g ${spec}`;
+}
+/**
+ * Render a project-local (dev-dependency) install command. pnpm-managed repos
+ * that prefer not to install globally use this.
+ */
+export function renderProjectInstall(pm, spec = ENGINE_PACKAGE) {
+    return pm === "pnpm" ? `pnpm add -D ${spec}` : `npm install --save-dev ${spec}`;
+}
+/**
+ * Render an ephemeral (no-install) invocation, e.g. `npx @deftai/directive update`
+ * (npm) or `pnpm dlx @deftai/directive update` (pnpm).
+ */
+export function renderEphemeral(pm, subcommand, pkg = ENGINE_PACKAGE) {
+    const runner = pm === "pnpm" ? "pnpm dlx" : "npx";
+    const tail = subcommand.trim() === "" ? "" : ` ${subcommand.trim()}`;
+    return `${runner} ${pkg}${tail}`;
+}
+/**
+ * Render the full command matrix for a package manager at a given spec
+ * (defaults to `@latest`). Single-sourced so docs, doctor, and the plan all
+ * derive from the same renderers.
+ */
+export function renderPackageManagerCommands(pm, spec = `${ENGINE_PACKAGE}@latest`) {
+    return {
+        packageManager: pm,
+        globalInstall: renderGlobalInstall(pm, spec),
+        projectInstall: renderProjectInstall(pm, spec),
+        ephemeralUpdate: renderEphemeral(pm, "update"),
+        upgradeOneLiner: renderGlobalInstall(pm, `${ENGINE_PACKAGE}@latest`),
+    };
+}
+//# sourceMappingURL=package-manager.js.map

package/dist/resolution/pin.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Version pin + reconciliation for the resolution spine (#2264, absorbs #2199).
+ *
+ * The committed `package.json` devDependency on `@deftai/directive` (exact,
+ * `"private": true`) is the CANONICAL pin — read before directive runs, npm-native
+ * so the engine ladder stays plain npm. This module reads that pin and reconciles
+ * it against the reachable engine version, the `.deft/core/VERSION` content marker,
+ * and the AGENTS.md managed-section `sha=`.
+ *
+ * Semver helpers here are the single comparison primitive reused by the skew
+ * policy and the engine ladder so version ordering is defined in exactly one place.
+ */
+/** The canonical committed dependency the pin lives on. */
+export declare const PIN_DEPENDENCY_NAME = "@deftai/directive";
+/** A parsed semver triple (prerelease / build metadata dropped). */
+export type SemverTriple = readonly [number, number, number];
+/** Parse a semver prefix (`major.minor.patch`); null when not exact semver. */
+export declare function parseSemver(version: string | null | undefined): SemverTriple | null;
+/** True when `version` is an EXACT pin (no range operators like `^` / `~` / `*`). */
+export declare function isExactPin(version: string | null | undefined): boolean;
+/** Compare two versions: -1 (a<b), 0 (a==b), 1 (a>b); null when either is unparseable. */
+export declare function compareSemver(a: string | null, b: string | null): -1 | 0 | 1 | null;
+/** True when `a >= b` under semver ordering; false when either is unparseable. */
+export declare function semverGte(a: string | null, b: string | null): boolean;
+export interface PinReadSeams {
+    readonly isFile?: (p: string) => boolean;
+    readonly readText?: (p: string) => string | null;
+}
+export interface PinReadResult {
+    /** Exact pinned version (no `v` prefix), or null when absent / non-exact. */
+    readonly pinVersion: string | null;
+    /** Raw devDependency spec string as written, or null. */
+    readonly rawSpec: string | null;
+    /** `package.json` declares `"private": true`. */
+    readonly isPrivate: boolean;
+    /** The pin spec is present but NOT an exact version (range operator used). */
+    readonly nonExact: boolean;
+}
+/**
+ * Read the committed `package.json` pin on `@deftai/directive`. The pin is
+ * canonical only when it is an EXACT version; a range spec is reported via
+ * `nonExact` so callers can warn rather than silently trusting a floating range.
+ */
+export declare function readPin(projectRoot: string, seams?: PinReadSeams): PinReadResult;
+export interface ReconcileInputs {
+    /** Canonical pin from `package.json`. */
+    readonly pinVersion: string | null;
+    /** Reachable engine version, or null when unreachable. */
+    readonly engineVersion: string | null;
+    /** `.deft/core/VERSION` content marker, or null. */
+    readonly contentVersion: string | null;
+    /** AGENTS.md managed-section `sha=`, or null. */
+    readonly managedSectionSha: string | null;
+    /** The sha the engine would stamp for the current payload, when known. */
+    readonly expectedManagedSectionSha?: string | null;
+}
+export interface ReconcileResult {
+    /** No mismatches detected against the pin. */
+    readonly consistent: boolean;
+    /** Deposited content (`VERSION`) is behind the pin (needs forward-migration). */
+    readonly contentBehindPin: boolean;
+    /** The managed-section sha is present but disagrees with the expected sha. */
+    readonly managedShaMismatch: boolean;
+    /** Human-facing mismatch reasons (empty when consistent). */
+    readonly mismatches: readonly string[];
+}
+/**
+ * Reconcile the pin against the engine, the deposited content marker, and the
+ * AGENTS managed-section sha. The managed-section `sha=` is part of the
+ * reconciliation, not just `VERSION` (per the #2264 acceptance).
+ */
+export declare function reconcileVersions(inputs: ReconcileInputs): ReconcileResult;
+//# sourceMappingURL=pin.d.ts.map