@deftai/directive-core 0.55.2 → 0.56.1

package/dist/legacy-bridge/bridge-drift.d.ts

@@ -0,0 +1,70 @@
+/**
+ * bridge-drift.ts -- Tier-1 cross-surface drift gate for the legacy Go-installer
+ * bridge (#1912).
+ *
+ * Asserts that every surface which STATES the frozen bridge version reads the
+ * Tier-0 SoT (`lastGoInstaller`) instead of hardcoding a competing number.
+ * Modeled on the #1308/#1309 freshness/propagation gates: surfaces opt in to the
+ * contract via a stable SENTINEL marker, and the gate enforces that no marked
+ * line outside the SoT module carries a hardcoded Go-installer semver.
+ *
+ * The contract (sentinel-gated so it is zero-false-positive across the many
+ * unrelated docs/code files that legitimately mention "deft-install"):
+ *
+ *   - Any surface that states the frozen bridge version puts the marker token
+ *     `deft:last-go-installer` on the stating line and references the SoT
+ *     (`lastGoInstaller()` / `LAST_GO_INSTALLER`) -- NOT an inline number.
+ *   - A marked line that ALSO contains a hardcoded `vX.Y.Z` literal is drift:
+ *     the version must come from the SoT, not be restated.
+ *   - `sot.ts` is the sole exemption -- it is where the literal legitimately
+ *     lives -- and is never scanned as a surface.
+ *
+ * Designed to pass whether or not story P's UPGRADING/doctor surfaces exist yet:
+ * a registered surface that is absent is simply skipped (the assertion is "no
+ * surface hardcodes", not "surface X must exist").
+ *
+ * Three-state exit (mirrors verify-source/content-manifest + scm-boundary):
+ *   0 -- clean: no marked surface hardcodes a Go-installer version.
+ *   1 -- drift: a marked surface line hardcodes a competing version.
+ *   2 -- config error: the SoT module is missing or no longer exposes the
+ *        reader API + sentinel anchor (the contract has no anchor to enforce).
+ */
+/** Stable marker a surface puts on the line that states the bridge version. */
+export declare const BRIDGE_SENTINEL = "deft:last-go-installer";
+/** Repo-relative path to the Tier-0 SoT module (the sole literal home). */
+export declare const SOT_RELATIVE_PATH = "packages/core/src/legacy-bridge/sot.ts";
+/**
+ * Default surface registry: files that document or consume the bridge version.
+ * Scanned only when present; absence is a pass. The SoT module and `*.test.ts`
+ * fixtures are never scanned (they may legitimately hold version literals).
+ * Story P's UPGRADING/doctor surfaces are listed so the gate covers them the
+ * moment they opt in via the sentinel -- but their absence today is a clean pass.
+ */
+export declare const DEFAULT_DRIFT_SURFACES: readonly string[];
+export interface DriftFinding {
+    readonly path: string;
+    readonly line: number;
+    readonly context: string;
+}
+/** Scan one surface's source for marked lines that hardcode a version literal. */
+export declare function scanSurfaceForDrift(relPath: string, source: string): DriftFinding[];
+export interface DriftResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: "stdout" | "stderr";
+    readonly findings: readonly DriftFinding[];
+}
+export interface DriftEvaluateOptions {
+    /** Test seam: override the surface registry. */
+    readonly surfaces?: readonly string[];
+    /** Test seam: override the SoT module path. */
+    readonly sotPath?: string;
+    /** Test seam: override the SoT value for the clean-state message. */
+    readonly pinned?: string | null;
+}
+/**
+ * Evaluate the cross-surface drift gate. Reads the SoT module (config anchor)
+ * plus each existing registered surface.
+ */
+export declare function evaluateBridgeDrift(projectRoot: string, options?: DriftEvaluateOptions): DriftResult;
+//# sourceMappingURL=bridge-drift.d.ts.map

package/dist/legacy-bridge/bridge-drift.js

@@ -0,0 +1,171 @@
+/**
+ * bridge-drift.ts -- Tier-1 cross-surface drift gate for the legacy Go-installer
+ * bridge (#1912).
+ *
+ * Asserts that every surface which STATES the frozen bridge version reads the
+ * Tier-0 SoT (`lastGoInstaller`) instead of hardcoding a competing number.
+ * Modeled on the #1308/#1309 freshness/propagation gates: surfaces opt in to the
+ * contract via a stable SENTINEL marker, and the gate enforces that no marked
+ * line outside the SoT module carries a hardcoded Go-installer semver.
+ *
+ * The contract (sentinel-gated so it is zero-false-positive across the many
+ * unrelated docs/code files that legitimately mention "deft-install"):
+ *
+ *   - Any surface that states the frozen bridge version puts the marker token
+ *     `deft:last-go-installer` on the stating line and references the SoT
+ *     (`lastGoInstaller()` / `LAST_GO_INSTALLER`) -- NOT an inline number.
+ *   - A marked line that ALSO contains a hardcoded `vX.Y.Z` literal is drift:
+ *     the version must come from the SoT, not be restated.
+ *   - `sot.ts` is the sole exemption -- it is where the literal legitimately
+ *     lives -- and is never scanned as a surface.
+ *
+ * Designed to pass whether or not story P's UPGRADING/doctor surfaces exist yet:
+ * a registered surface that is absent is simply skipped (the assertion is "no
+ * surface hardcodes", not "surface X must exist").
+ *
+ * Three-state exit (mirrors verify-source/content-manifest + scm-boundary):
+ *   0 -- clean: no marked surface hardcodes a Go-installer version.
+ *   1 -- drift: a marked surface line hardcodes a competing version.
+ *   2 -- config error: the SoT module is missing or no longer exposes the
+ *        reader API + sentinel anchor (the contract has no anchor to enforce).
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { lastGoInstaller } from "./sot.js";
+const EXIT_OK = 0;
+const EXIT_DRIFT = 1;
+const EXIT_CONFIG_ERROR = 2;
+/** Stable marker a surface puts on the line that states the bridge version. */
+export const BRIDGE_SENTINEL = "deft:last-go-installer";
+/** Repo-relative path to the Tier-0 SoT module (the sole literal home). */
+export const SOT_RELATIVE_PATH = "packages/core/src/legacy-bridge/sot.ts";
+/**
+ * Default surface registry: files that document or consume the bridge version.
+ * Scanned only when present; absence is a pass. The SoT module and `*.test.ts`
+ * fixtures are never scanned (they may legitimately hold version literals).
+ * Story P's UPGRADING/doctor surfaces are listed so the gate covers them the
+ * moment they opt in via the sentinel -- but their absence today is a clean pass.
+ */
+export const DEFAULT_DRIFT_SURFACES = [
+    "UPGRADING.md",
+    "content/UPGRADING.md",
+    "packages/core/src/doctor/constants.ts",
+    "packages/core/src/legacy-bridge/freeze-gate.ts",
+    "packages/core/src/legacy-bridge/bridge-drift.ts",
+];
+/**
+ * Matches a hardcoded Go-installer-style semver literal (tolerates a leading `v`).
+ * The digit runs are length-bounded (`{1,9}`) rather than unbounded (`+`) on
+ * purpose: a real semver component is never 10+ digits, and the bound removes the
+ * quadratic-backtracking ReDoS class (`js/polynomial-redos`) that an unbounded
+ * `\d+\.\d+\.\d+` exhibits when `.test()` runs over uncontrolled file input.
+ */
+const SEMVER_LITERAL = /v?\d{1,9}\.\d{1,9}\.\d{1,9}/;
+/** Scan one surface's source for marked lines that hardcode a version literal. */
+export function scanSurfaceForDrift(relPath, source) {
+    const findings = [];
+    const lines = source.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        if (line.includes(BRIDGE_SENTINEL) && SEMVER_LITERAL.test(line)) {
+            const ctx = line.trim();
+            findings.push({
+                path: relPath,
+                line: i + 1,
+                context: ctx.length <= 120 ? ctx : `${ctx.slice(0, 117)}...`,
+            });
+        }
+    }
+    return findings;
+}
+function isReadableFile(full) {
+    try {
+        return statSync(full).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Evaluate the cross-surface drift gate. Reads the SoT module (config anchor)
+ * plus each existing registered surface.
+ */
+export function evaluateBridgeDrift(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const sotFull = resolve(root, options.sotPath ?? SOT_RELATIVE_PATH);
+    if (!existsSync(sotFull)) {
+        return {
+            code: EXIT_CONFIG_ERROR,
+            findings: [],
+            message: `Error: Tier-0 SoT module not found at ${options.sotPath ?? SOT_RELATIVE_PATH}; ` +
+                "the drift contract has no anchor to enforce.",
+            stream: "stderr",
+        };
+    }
+    let sotSource;
+    try {
+        sotSource = readFileSync(sotFull, { encoding: "utf8" });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            code: EXIT_CONFIG_ERROR,
+            findings: [],
+            message: `Error: failed to read SoT module ${sotFull}: ${msg}`,
+            stream: "stderr",
+        };
+    }
+    const anchorOk = sotSource.includes("lastGoInstaller") &&
+        sotSource.includes("isFrozen") &&
+        sotSource.includes(BRIDGE_SENTINEL);
+    if (!anchorOk) {
+        return {
+            code: EXIT_CONFIG_ERROR,
+            findings: [],
+            message: `Error: SoT module ${options.sotPath ?? SOT_RELATIVE_PATH} no longer exposes the reader API ` +
+                `(lastGoInstaller / isFrozen) and sentinel anchor (${BRIDGE_SENTINEL}); the drift contract is broken.`,
+            stream: "stderr",
+        };
+    }
+    const surfaces = options.surfaces ?? DEFAULT_DRIFT_SURFACES;
+    const sotRelNormalized = (options.sotPath ?? SOT_RELATIVE_PATH).replace(/\\/g, "/");
+    const findings = [];
+    let scanned = 0;
+    for (const rel of surfaces) {
+        const relNorm = rel.replace(/\\/g, "/");
+        if (relNorm === sotRelNormalized || relNorm.endsWith(".test.ts")) {
+            continue;
+        }
+        const full = resolve(root, rel);
+        if (!isReadableFile(full)) {
+            continue;
+        }
+        let source;
+        try {
+            source = readFileSync(full, { encoding: "utf8" });
+        }
+        catch {
+            continue;
+        }
+        scanned += 1;
+        findings.push(...scanSurfaceForDrift(relNorm, source));
+    }
+    if (findings.length > 0) {
+        const header = `FAIL: ${findings.length} bridge-version drift finding(s) -- a marked surface hardcodes a ` +
+            "Go-installer version instead of reading the Tier-0 SoT (lastGoInstaller).\n" +
+            `  Fix: replace the inline version next to the \`${BRIDGE_SENTINEL}\` marker with a reference to ` +
+            "lastGoInstaller() / LAST_GO_INSTALLER (the SoT is the single source).";
+        const body = findings.map((f) => `  ${f.path}:${f.line}  ${f.context}`).join("\n");
+        return { code: EXIT_DRIFT, findings, message: `${header}\n${body}`, stream: "stderr" };
+    }
+    const pinned = options.pinned !== undefined ? options.pinned : lastGoInstaller();
+    const state = pinned === null ? "null (unfrozen)" : pinned;
+    return {
+        code: EXIT_OK,
+        findings: [],
+        message: `OK: ${scanned} bridge-version surface(s) scanned; every reference reads the Tier-0 SoT ` +
+            `(lastGoInstaller = ${state}). No hardcoded competing version.`,
+        stream: "stdout",
+    };
+}
+//# sourceMappingURL=bridge-drift.js.map

package/dist/legacy-bridge/freeze-gate.d.ts

@@ -0,0 +1,79 @@
+/**
+ * freeze-gate.ts -- Tier-1 freeze gate for the legacy Go-installer bridge (#1912).
+ *
+ * Reads the Tier-0 SoT (`lastGoInstaller`) and weighs a candidate RELEASE TAG
+ * against the frozen line:
+ *
+ *   - SoT null (NOT yet frozen): PASS (advisory). Go-installer development is
+ *     still allowed up to the cut; the gate does not read the installer source
+ *     in this state.
+ *   - SoT pinned (frozen) + a release tag supplied: FAIL when the release tag is
+ *     ABOVE the pinned tag -- i.e. someone is cutting a Go-installer release past
+ *     the frozen line. At-or-below the line PASSES (re-publishing the pinned tag
+ *     is allowed).
+ *   - SoT pinned (frozen) + NO release tag supplied: PASS (advisory). There is no
+ *     release being cut, so there is nothing to weigh; the enforcing teeth live
+ *     in the release.yml tag guard, which runs only on a `v*.*.*` tag push.
+ *
+ * Why a release tag and not the installer source literal (#1972): the real
+ * installer version is injected via `-ldflags "-X main.version=<tag>"` at build
+ * time, so the `var version = "..."` literal in `cmd/deft-install/main.go` does
+ * NOT reflect the released version. Comparing the pinned SoT against that stale
+ * literal would false-fail the moment the SoT is pinned to a real 0.x tag. The
+ * gate therefore keys off the release tag (`github.ref_name` in CI). The source
+ * parsers below (`parseInstallerVersion` / `readInstallerVersion`) are retained
+ * as release-time utilities but are no longer the freeze-decision input.
+ *
+ * Three-state exit (mirrors verify-source/content-manifest + scm-boundary):
+ *   0 -- ok (advisory-when-null / advisory-when-no-tag, or at/below the line).
+ *   1 -- violation: frozen and the release tag is above the pinned tag.
+ *   2 -- config error: the SoT value or the release tag is unparseable.
+ *
+ * No version number is hardcoded here: the frozen tag comes from the SoT module
+ * and the candidate tag is supplied by the caller (the release pipeline) at
+ * runtime.
+ */
+/** Repo-relative path to the Go installer source carrying the version constant. */
+export declare const DEFAULT_INSTALLER_VERSION_PATH = "cmd/deft-install/main.go";
+/** Per-shell emergency bypass env var (consistent with the other deft gates). */
+export declare const FREEZE_BYPASS_ENV = "DEFT_ALLOW_GO_INSTALLER_BUMP";
+/** Extract the `var version = "X"` literal from Go installer source, or null. */
+export declare function parseInstallerVersion(source: string): string | null;
+/** Read + parse the Go installer version constant. Throws (caller maps to 2). */
+export declare function readInstallerVersion(projectRoot: string, relPath?: string): string;
+/**
+ * Compare two installer version strings by numeric major.minor.patch core.
+ * Returns -1 (a < b), 0 (a == b), or 1 (a > b). Throws on an unparseable input
+ * (caller maps to config error). Pre-release / build metadata is ignored for the
+ * "above the line" determination.
+ */
+export declare function compareInstallerVersions(a: string, b: string): -1 | 0 | 1;
+export interface FreezeResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: "stdout" | "stderr";
+}
+export interface FreezeEvaluateOptions {
+    /** Test seam: override the SoT value (undefined = read the live SoT module). */
+    readonly pinned?: string | null;
+    /**
+     * The candidate release tag to weigh against the frozen line (CI:
+     * `github.ref_name`). When undefined / null the gate is advisory: there is no
+     * release being cut, so there is nothing to enforce -- the teeth live in the
+     * release.yml tag guard. This replaces the brittle source-literal comparison
+     * (#1972): the real installer version is ldflags-injected at build time, so
+     * the `var version` source literal does not reflect the released version.
+     */
+    readonly releaseTag?: string | null;
+    /** When true, downgrade a violation to an advisory pass (emergency bypass). */
+    readonly allowBump?: boolean;
+}
+/**
+ * Evaluate the freeze gate against a candidate release tag.
+ *
+ * The first parameter is retained for call-site signature compatibility (the
+ * `verify-go-freeze` CLI passes a project root positionally); the gate no longer
+ * reads the installer source, so the value is unused here (#1972).
+ */
+export declare function evaluateGoFreeze(_projectRoot: string, options?: FreezeEvaluateOptions): FreezeResult;
+//# sourceMappingURL=freeze-gate.d.ts.map

package/dist/legacy-bridge/freeze-gate.js

@@ -0,0 +1,168 @@
+/**
+ * freeze-gate.ts -- Tier-1 freeze gate for the legacy Go-installer bridge (#1912).
+ *
+ * Reads the Tier-0 SoT (`lastGoInstaller`) and weighs a candidate RELEASE TAG
+ * against the frozen line:
+ *
+ *   - SoT null (NOT yet frozen): PASS (advisory). Go-installer development is
+ *     still allowed up to the cut; the gate does not read the installer source
+ *     in this state.
+ *   - SoT pinned (frozen) + a release tag supplied: FAIL when the release tag is
+ *     ABOVE the pinned tag -- i.e. someone is cutting a Go-installer release past
+ *     the frozen line. At-or-below the line PASSES (re-publishing the pinned tag
+ *     is allowed).
+ *   - SoT pinned (frozen) + NO release tag supplied: PASS (advisory). There is no
+ *     release being cut, so there is nothing to weigh; the enforcing teeth live
+ *     in the release.yml tag guard, which runs only on a `v*.*.*` tag push.
+ *
+ * Why a release tag and not the installer source literal (#1972): the real
+ * installer version is injected via `-ldflags "-X main.version=<tag>"` at build
+ * time, so the `var version = "..."` literal in `cmd/deft-install/main.go` does
+ * NOT reflect the released version. Comparing the pinned SoT against that stale
+ * literal would false-fail the moment the SoT is pinned to a real 0.x tag. The
+ * gate therefore keys off the release tag (`github.ref_name` in CI). The source
+ * parsers below (`parseInstallerVersion` / `readInstallerVersion`) are retained
+ * as release-time utilities but are no longer the freeze-decision input.
+ *
+ * Three-state exit (mirrors verify-source/content-manifest + scm-boundary):
+ *   0 -- ok (advisory-when-null / advisory-when-no-tag, or at/below the line).
+ *   1 -- violation: frozen and the release tag is above the pinned tag.
+ *   2 -- config error: the SoT value or the release tag is unparseable.
+ *
+ * No version number is hardcoded here: the frozen tag comes from the SoT module
+ * and the candidate tag is supplied by the caller (the release pipeline) at
+ * runtime.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { lastGoInstaller } from "./sot.js";
+const EXIT_OK = 0;
+const EXIT_VIOLATION = 1;
+const EXIT_CONFIG_ERROR = 2;
+/** Repo-relative path to the Go installer source carrying the version constant. */
+export const DEFAULT_INSTALLER_VERSION_PATH = "cmd/deft-install/main.go";
+/** Per-shell emergency bypass env var (consistent with the other deft gates). */
+export const FREEZE_BYPASS_ENV = "DEFT_ALLOW_GO_INSTALLER_BUMP";
+/** Extract the `var version = "X"` literal from Go installer source, or null. */
+export function parseInstallerVersion(source) {
+    const match = source.match(/var\s+version\s*=\s*"([^"]+)"/);
+    return match?.[1] ?? null;
+}
+/** Read + parse the Go installer version constant. Throws (caller maps to 2). */
+export function readInstallerVersion(projectRoot, relPath = DEFAULT_INSTALLER_VERSION_PATH) {
+    const full = resolve(projectRoot, relPath);
+    if (!existsSync(full)) {
+        throw new Error(`Go installer source not found: ${full} -- expected the \`var version = "..."\` constant at ${relPath}.`);
+    }
+    let source;
+    try {
+        source = readFileSync(full, { encoding: "utf8" });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to read Go installer source ${full}: ${msg}`);
+    }
+    const version = parseInstallerVersion(source);
+    if (version === null) {
+        throw new Error(`Could not parse \`var version = "..."\` from ${relPath}; the Go installer version constant is missing or malformed.`);
+    }
+    return version;
+}
+/** Parse the numeric major.minor.patch core, tolerating a leading `v` and a `-`/`+` suffix. */
+function parseSemverCore(raw) {
+    const trimmed = raw.trim().replace(/^v/i, "");
+    const core = trimmed.split(/[-+]/, 1)[0] ?? "";
+    const parts = core.split(".");
+    if (parts.length === 0 || parts[0] === "") {
+        throw new Error(`unparseable version: '${raw}'`);
+    }
+    const nums = parts.map((p) => {
+        if (!/^\d+$/.test(p)) {
+            throw new Error(`unparseable version: '${raw}'`);
+        }
+        return Number.parseInt(p, 10);
+    });
+    return { major: nums[0] ?? 0, minor: nums[1] ?? 0, patch: nums[2] ?? 0 };
+}
+/**
+ * Compare two installer version strings by numeric major.minor.patch core.
+ * Returns -1 (a < b), 0 (a == b), or 1 (a > b). Throws on an unparseable input
+ * (caller maps to config error). Pre-release / build metadata is ignored for the
+ * "above the line" determination.
+ */
+export function compareInstallerVersions(a, b) {
+    const av = parseSemverCore(a);
+    const bv = parseSemverCore(b);
+    for (const key of ["major", "minor", "patch"]) {
+        if (av[key] < bv[key])
+            return -1;
+        if (av[key] > bv[key])
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Evaluate the freeze gate against a candidate release tag.
+ *
+ * The first parameter is retained for call-site signature compatibility (the
+ * `verify-go-freeze` CLI passes a project root positionally); the gate no longer
+ * reads the installer source, so the value is unused here (#1972).
+ */
+export function evaluateGoFreeze(_projectRoot, options = {}) {
+    const pinned = options.pinned !== undefined ? options.pinned : lastGoInstaller();
+    if (pinned === null) {
+        return {
+            code: EXIT_OK,
+            message: "OK (advisory): the Go installer is not frozen (SoT lastGoInstaller is null). " +
+                "Go-installer development is still allowed up to the cut.",
+            stream: "stdout",
+        };
+    }
+    const releaseTag = options.releaseTag ?? null;
+    if (releaseTag === null) {
+        return {
+            code: EXIT_OK,
+            message: `OK (advisory): the Go installer is frozen at ${pinned}, but no release tag was supplied ` +
+                "to weigh against the frozen line. Freeze enforcement runs in the release.yml tag guard " +
+                "on a v*.*.* push; this local gate is advisory.",
+            stream: "stdout",
+        };
+    }
+    let cmp;
+    try {
+        cmp = compareInstallerVersions(releaseTag, pinned);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            code: EXIT_CONFIG_ERROR,
+            message: `Error: cannot compare versions (${msg}). Check the SoT value and the release tag.`,
+            stream: "stderr",
+        };
+    }
+    if (cmp > 0) {
+        if (options.allowBump) {
+            return {
+                code: EXIT_OK,
+                message: `OK (bypass): release tag ${releaseTag} is ABOVE the frozen bridge tag ${pinned}, ` +
+                    `but ${FREEZE_BYPASS_ENV}=1 downgraded the violation to advisory.`,
+                stream: "stdout",
+            };
+        }
+        return {
+            code: EXIT_VIOLATION,
+            message: `FAIL: release tag ${releaseTag} is ABOVE the frozen bridge tag ${pinned}.\n` +
+                "  The last Go installer was frozen as the legacy stage-1 bridge (#1912); no Go-installer\n" +
+                "  release past the pinned tag is allowed. Cut the release at or below the frozen tag\n" +
+                `  (${pinned}), or roll the freeze SoT forward. Emergency bypass: ${FREEZE_BYPASS_ENV}=1.`,
+            stream: "stderr",
+        };
+    }
+    return {
+        code: EXIT_OK,
+        message: `OK: the Go installer is frozen at ${pinned}; release tag ${releaseTag} ` +
+            "is at or below the frozen line.",
+        stream: "stdout",
+    };
+}
+//# sourceMappingURL=freeze-gate.js.map

package/dist/legacy-bridge/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./bridge-drift.js";
+export * from "./freeze-gate.js";
+export * from "./sot.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/legacy-bridge/index.js

@@ -0,0 +1,4 @@
+export * from "./bridge-drift.js";
+export * from "./freeze-gate.js";
+export * from "./sot.js";
+//# sourceMappingURL=index.js.map

package/dist/legacy-bridge/sot.d.ts

@@ -0,0 +1,45 @@
+/**
+ * sot.ts -- Tier-0 single source of truth for the frozen final Go-installer
+ * version, the legacy stage-1 bridge (#1912).
+ *
+ * SEMANTICS: null-until-frozen.
+ *
+ *   - TODAY (and on every branch until the operator cuts the final Go
+ *     installer) `LAST_GO_INSTALLER` is `null`. `isFrozen()` returns `false`.
+ *     The freeze gate (`verify:go-freeze`) is advisory-only in this state --
+ *     Go-installer development is still allowed up to the cut.
+ *   - AT FREEZE TIME the OPERATOR pins the value here -- and ONLY here -- to the
+ *     exact tag of the final published Go installer (e.g. `"v0.32.5"`). From
+ *     that point `isFrozen()` is `true`, the freeze gate enforces the line, and
+ *     every other surface that documents or consumes the bridge version reads
+ *     this module instead of hardcoding a number.
+ *
+ * This module is the ONE place the bridge version is allowed to live as a
+ * literal. Every other surface (UPGRADING.md two-step wording, the `deft doctor`
+ * legacy-layout signpost, the pinned legacy-bridge e2e) MUST reference the SoT
+ * rather than restate the number -- the cross-surface drift gate
+ * (`verify:bridge-drift`) enforces that via the sentinel marker below.
+ *
+ * SENTINEL MARKER (cross-surface drift contract, #1912): any surface that
+ * STATES the frozen bridge version carries the marker token
+ * `deft:last-go-installer` on the stating line. `verify:bridge-drift` asserts no
+ * marked line outside this module hardcodes a Go-installer semver -- the value
+ * must come from `lastGoInstaller()` / `LAST_GO_INSTALLER`. This module is the
+ * sole exemption: it is where the literal legitimately lives.
+ *
+ * deft:last-go-installer -- anchor; the value is the constant below, never an
+ * inline number on this comment line.
+ */
+/**
+ * The frozen final Go-installer tag, or `null` while unfrozen.
+ *
+ * OPERATOR FREEZE STEP: set this to the published tag string (e.g. `"v0.32.5"`)
+ * at freeze time. Leave it `null` otherwise. This is the only edit required to
+ * pin the bridge version; the freeze + drift gates pick it up automatically.
+ */
+export declare const LAST_GO_INSTALLER: string | null;
+/** Returns the frozen final Go-installer tag, or `null` while unfrozen. */
+export declare function lastGoInstaller(): string | null;
+/** Returns `true` once the final Go installer has been frozen (SoT pinned). */
+export declare function isFrozen(): boolean;
+//# sourceMappingURL=sot.d.ts.map

package/dist/legacy-bridge/sot.js

@@ -0,0 +1,49 @@
+/**
+ * sot.ts -- Tier-0 single source of truth for the frozen final Go-installer
+ * version, the legacy stage-1 bridge (#1912).
+ *
+ * SEMANTICS: null-until-frozen.
+ *
+ *   - TODAY (and on every branch until the operator cuts the final Go
+ *     installer) `LAST_GO_INSTALLER` is `null`. `isFrozen()` returns `false`.
+ *     The freeze gate (`verify:go-freeze`) is advisory-only in this state --
+ *     Go-installer development is still allowed up to the cut.
+ *   - AT FREEZE TIME the OPERATOR pins the value here -- and ONLY here -- to the
+ *     exact tag of the final published Go installer (e.g. `"v0.32.5"`). From
+ *     that point `isFrozen()` is `true`, the freeze gate enforces the line, and
+ *     every other surface that documents or consumes the bridge version reads
+ *     this module instead of hardcoding a number.
+ *
+ * This module is the ONE place the bridge version is allowed to live as a
+ * literal. Every other surface (UPGRADING.md two-step wording, the `deft doctor`
+ * legacy-layout signpost, the pinned legacy-bridge e2e) MUST reference the SoT
+ * rather than restate the number -- the cross-surface drift gate
+ * (`verify:bridge-drift`) enforces that via the sentinel marker below.
+ *
+ * SENTINEL MARKER (cross-surface drift contract, #1912): any surface that
+ * STATES the frozen bridge version carries the marker token
+ * `deft:last-go-installer` on the stating line. `verify:bridge-drift` asserts no
+ * marked line outside this module hardcodes a Go-installer semver -- the value
+ * must come from `lastGoInstaller()` / `LAST_GO_INSTALLER`. This module is the
+ * sole exemption: it is where the literal legitimately lives.
+ *
+ * deft:last-go-installer -- anchor; the value is the constant below, never an
+ * inline number on this comment line.
+ */
+/**
+ * The frozen final Go-installer tag, or `null` while unfrozen.
+ *
+ * OPERATOR FREEZE STEP: set this to the published tag string (e.g. `"v0.32.5"`)
+ * at freeze time. Leave it `null` otherwise. This is the only edit required to
+ * pin the bridge version; the freeze + drift gates pick it up automatically.
+ */
+export const LAST_GO_INSTALLER = "v0.56.0";
+/** Returns the frozen final Go-installer tag, or `null` while unfrozen. */
+export function lastGoInstaller() {
+    return LAST_GO_INSTALLER;
+}
+/** Returns `true` once the final Go installer has been frozen (SoT pinned). */
+export function isFrozen() {
+    return LAST_GO_INSTALLER !== null;
+}
+//# sourceMappingURL=sot.js.map

package/dist/preflight-cache/evaluate.d.ts

@@ -10,6 +10,7 @@
  *   1 -- cache stale / blocking condition found
  *   2 -- config error (cache missing and --allow-missing-bootstrap not set)
  */
+import { type CacheDriftProbeResult } from "../cache/fetch.js";
 export declare const CACHE_DIR_NAME = ".deft-cache";
 export declare const DEFAULT_SOURCE = "github-issue";
 export declare const CANDIDATES_RELPATH: string;
@@ -30,7 +31,17 @@ export interface EvaluateOptions {
     allowMissingBootstrap?: boolean;
     /** Injectable clock for tests. */
     nowFn?: () => Date;
+    /** Injectable drift probe for tests. */
+    probeDriftFn?: (repo: string, cacheRoot: string, source: string) => CacheDriftProbeResult | null;
 }
+/**
+ * Branch-aware recovery hint (#1953 Option 3).
+ * Age-stale (or age+drift mixed) → --force bypasses TTL; drift-only → plain refetch.
+ */
+export declare function recoveryHintForStaleFailure(causes: Readonly<{
+    ageStale: boolean;
+    driftDetected: boolean;
+}>): string;
 /**
  * Evaluate cache freshness for the given project root.
  *