@deftai/directive-core 0.94.0 → 0.96.0

package/dist/freshness/bind.js

@@ -0,0 +1,201 @@
+/**
+ * Session bind of live deposit generation (#3117).
+ *
+ * Host-agnostic storage:
+ * - Default (no sessionId): `.deft/session-bind.json` — single-operator convenience.
+ * - With sessionId: `.deft/session-binds/<safeId>.json` — isolated multi-session binds.
+ *
+ * Multi-agent hosts MUST pass a stable host session identity when binding and
+ * reporting so one session cannot certify another as current.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
+import { readLiveGeneration, stampLiveGeneration } from "./generation.js";
+import { FRESHNESS_SCHEMA_VERSION, } from "./types.js";
+/** Relative path for the default (no-sessionId) bind record. */
+export const SESSION_BIND_REL = join(".deft", "session-bind.json");
+/** Directory for per-session bind records. */
+export const SESSION_BINDS_DIR_REL = join(".deft", "session-binds");
+export function sessionBindPath(projectRoot, sessionId) {
+    const root = resolve(projectRoot);
+    const id = typeof sessionId === "string" ? sessionId.trim() : "";
+    if (id.length === 0) {
+        return join(root, SESSION_BIND_REL);
+    }
+    return join(root, SESSION_BINDS_DIR_REL, safeSessionFileName(id));
+}
+/**
+ * Stable filesystem-safe file name for a host session id.
+ * Keeps a short prefix for debug, hashes the rest to avoid path injection.
+ * Character filter is O(n) (no regex) — CodeQL poly-redos on uncontrolled ids.
+ */
+export function safeSessionFileName(sessionId) {
+    const trimmed = sessionId.trim();
+    const hash = createHash("sha256").update(trimmed, "utf8").digest("hex").slice(0, 24);
+    let prefix = "";
+    for (let i = 0; i < trimmed.length && prefix.length < 32; i++) {
+        const ch = trimmed[i] ?? "";
+        const code = ch.charCodeAt(0);
+        const ok = (code >= 48 && code <= 57) || // 0-9
+            (code >= 65 && code <= 90) || // A-Z
+            (code >= 97 && code <= 122) || // a-z
+            ch === "." ||
+            ch === "_" ||
+            ch === "-";
+        if (ok) {
+            prefix += ch;
+        }
+        else if (prefix.length === 0 || prefix[prefix.length - 1] !== "_") {
+            prefix += "_";
+        }
+    }
+    while (prefix.startsWith("_")) {
+        prefix = prefix.slice(1);
+    }
+    while (prefix.endsWith("_")) {
+        prefix = prefix.slice(0, -1);
+    }
+    const base = prefix.length > 0 ? `${prefix}-${hash}` : hash;
+    return `${base}.json`;
+}
+function nowIsoDefault() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** Parse a bound generation record (null if invalid). */
+export function parseBoundGeneration(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return null;
+    }
+    const rec = raw;
+    const boundGeneration = rec.boundGeneration;
+    if (typeof boundGeneration !== "number" ||
+        !Number.isInteger(boundGeneration) ||
+        boundGeneration < 1) {
+        return null;
+    }
+    const boundAt = typeof rec.boundAt === "string" && rec.boundAt.trim() ? rec.boundAt.trim() : null;
+    if (boundAt === null) {
+        return null;
+    }
+    const contentVersion = typeof rec.contentVersion === "string" && rec.contentVersion.trim()
+        ? rec.contentVersion.trim()
+        : "";
+    let surfaces = {};
+    if (typeof rec.surfaces === "object" && rec.surfaces !== null && !Array.isArray(rec.surfaces)) {
+        const next = {};
+        for (const [k, v] of Object.entries(rec.surfaces)) {
+            if (typeof v === "string") {
+                next[k] = v;
+            }
+        }
+        surfaces = next;
+    }
+    const sessionId = typeof rec.sessionId === "string" && rec.sessionId.trim()
+        ? rec.sessionId.trim()
+        : rec.sessionId === null
+            ? null
+            : undefined;
+    const payloadLoaded = rec.payloadLoaded === true;
+    return {
+        schemaVersion: FRESHNESS_SCHEMA_VERSION,
+        boundGeneration,
+        boundAt,
+        contentVersion,
+        surfaces,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        ...(payloadLoaded ? { payloadLoaded: true } : {}),
+    };
+}
+/** Read the session bind record (null when absent/unreadable). */
+export function readBoundGeneration(projectRoot, options = {}) {
+    const path = sessionBindPath(projectRoot, options.sessionId);
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const text = readFileSync(path, "utf8");
+        const bound = parseBoundGeneration(JSON.parse(text));
+        if (bound === null) {
+            return null;
+        }
+        // When reading a session-scoped bind, refuse a record whose embedded
+        // sessionId disagrees (tamper / wrong file).
+        const want = typeof options.sessionId === "string" ? options.sessionId.trim() : "";
+        if (want.length > 0 && bound.sessionId && bound.sessionId !== want) {
+            return null;
+        }
+        return bound;
+    }
+    catch {
+        return null;
+    }
+}
+function writeBoundAt(projectRoot, bound, sessionId) {
+    const root = resolve(projectRoot);
+    const target = sessionBindPath(projectRoot, sessionId);
+    const body = `${JSON.stringify(bound, null, 2)}\n`;
+    try {
+        containedWrite({
+            root,
+            target,
+            data: body,
+            mode: "replace",
+        });
+    }
+    catch (err) {
+        if (err instanceof ContainedWriteError) {
+            throw err;
+        }
+        throw err;
+    }
+    return target;
+}
+/**
+ * Bind the current live generation into session context.
+ *
+ * Does not require restarting a shared host runtime — callers re-load payload
+ * surfaces into the session and call this (or `freshness:bind`) to rebind.
+ *
+ * Multi-agent hosts MUST supply `sessionId` so binds do not overwrite each other.
+ */
+export function bindSessionGeneration(projectRoot, options = {}) {
+    let live = readLiveGeneration(projectRoot);
+    if (live === null && options.ensureLive !== false) {
+        const contentVersion = options.contentVersion?.trim() || "0.0.0";
+        live = stampLiveGeneration(projectRoot, {
+            contentVersion,
+            stampedBy: options.stampedBy ?? "session-bind",
+            increment: false,
+            nowIso: options.nowIso,
+        });
+    }
+    if (live === null) {
+        throw new Error("freshness bind: no live generation token on disk; run directive update or init first");
+    }
+    const sessionId = typeof options.sessionId === "string" && options.sessionId.trim()
+        ? options.sessionId.trim()
+        : options.sessionId === null
+            ? null
+            : undefined;
+    const bound = {
+        schemaVersion: FRESHNESS_SCHEMA_VERSION,
+        boundGeneration: live.generation,
+        boundAt: options.nowIso ?? nowIsoDefault(),
+        contentVersion: live.contentVersion,
+        surfaces: { ...live.surfaces },
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        ...(options.payloadLoaded === true ? { payloadLoaded: true } : {}),
+    };
+    const path = writeBoundAt(projectRoot, bound, sessionId ?? null);
+    // Opt-in only: never mirror session-scoped binds into the default path by
+    // default (that would let bare freshness:report certify another session).
+    if (sessionId &&
+        options.alsoWriteDefault === true &&
+        path !== sessionBindPath(projectRoot, null)) {
+        writeBoundAt(projectRoot, bound, null);
+    }
+    return { bound, live, path };
+}
+//# sourceMappingURL=bind.js.map

package/dist/freshness/cli.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CLI entry for freshness:report / freshness:bind (#3117).
+ */
+export type FreshnessCliCommand = "report" | "bind" | "help";
+export interface FreshnessCliOptions {
+    readonly command: FreshnessCliCommand;
+    readonly projectRoot: string | null;
+    readonly json: boolean;
+    /**
+     * Host session id for bind/report.
+     * - `undefined` (flag omitted): report recovers ritual session_id
+     * - string: explicit session bind
+     * - `""` empty flag value: force default bind path (no ritual recovery)
+     */
+    readonly sessionId: string | undefined;
+    /** Host attests payload surfaces were reloaded before bind. */
+    readonly confirmPayloadLoaded: boolean;
+    readonly help: boolean;
+}
+export interface FreshnessCliResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export declare function parseFreshnessArgv(argv: readonly string[]): FreshnessCliOptions;
+/** Run freshness CLI. Returns structured stdout/stderr + exit code. */
+export declare function runFreshnessCli(argv?: readonly string[]): FreshnessCliResult;
+/** Core-module main entry for dispatch (stdout/stderr + process.exit). */
+export declare function mainEntry(argv?: string[]): number;
+//# sourceMappingURL=cli.d.ts.map

package/dist/freshness/cli.js

@@ -0,0 +1,180 @@
+/**
+ * CLI entry for freshness:report / freshness:bind (#3117).
+ */
+import { resolveProjectRoot } from "../scope/project-context.js";
+import { bindSessionGeneration } from "./bind.js";
+import { formatFreshnessReport, freshnessReportExitCode, freshnessReportToJson, reportFreshness, resolveReportSessionId, } from "./report.js";
+const HELP_TEXT = `Usage: deft freshness:<command> [options]
+
+Host-agnostic freshness contract: compare session bound generation vs live deposit.
+
+Commands:
+  report   Compare bound vs live (default). Exit 0=current, 1=soft/unbound, 2=hard.
+  bind     Bind the current live generation into this session (rebind without host restart).
+
+Options:
+  --project-root <path>   Project root (default: cwd / nearest project)
+  --session-id <id>       Optional host session identity stored on bind
+  --confirm-payload-loaded  Attest payload surfaces were reloaded (bind only)
+  --json                  Machine-readable JSON on stdout
+  --help                  Show this help
+
+See content/docs/freshness-contract.md for soft vs hard meanings and mid-mission safety.
+`;
+export function parseFreshnessArgv(argv) {
+    let command = "report";
+    let projectRoot = null;
+    let json = false;
+    let sessionId;
+    let confirmPayloadLoaded = false;
+    let help = false;
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i] ?? "";
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--confirm-payload-loaded" || arg === "--confirm-loaded") {
+            confirmPayloadLoaded = true;
+            continue;
+        }
+        if (arg === "--project-root" || arg === "--cwd") {
+            projectRoot = argv[++i] ?? null;
+            continue;
+        }
+        if (arg.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length) || null;
+            continue;
+        }
+        if (arg === "--session-id") {
+            // Empty value forces default bind; omitted flag stays undefined (ritual recover).
+            sessionId = argv[++i] ?? "";
+            continue;
+        }
+        if (arg.startsWith("--session-id=")) {
+            sessionId = arg.slice("--session-id=".length);
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            // Unknown flag — leave for command validation via help path.
+            positional.push(arg);
+            continue;
+        }
+        positional.push(arg);
+    }
+    if (positional[0] === "report" || positional[0] === "bind" || positional[0] === "help") {
+        command = positional[0];
+    }
+    else if (positional[0]) {
+        // Treat unknown subcommand as help-worthy.
+        help = true;
+    }
+    return {
+        command: help ? "help" : command,
+        projectRoot,
+        json,
+        sessionId,
+        confirmPayloadLoaded,
+        help,
+    };
+}
+/** Run freshness CLI. Returns structured stdout/stderr + exit code. */
+export function runFreshnessCli(argv = []) {
+    const options = parseFreshnessArgv(argv);
+    if (options.help || options.command === "help") {
+        return { exitCode: 0, stdout: HELP_TEXT, stderr: "" };
+    }
+    const projectRoot = resolveProjectRoot(options.projectRoot);
+    if (projectRoot === null) {
+        return {
+            exitCode: 2,
+            stdout: "",
+            stderr: "freshness: could not resolve project root. Pass --project-root PATH, set $DEFT_PROJECT_ROOT, or run from a tree with xbrief/ or .git/.\n",
+        };
+    }
+    if (options.command === "bind") {
+        try {
+            // Match report identity: omitted flag recovers ritual session_id so bare
+            // bind + bare report target the same scoped record (Greptile P1).
+            const bindSessionId = options.sessionId === undefined
+                ? resolveReportSessionId(projectRoot, undefined)
+                : options.sessionId.trim().length > 0
+                    ? options.sessionId.trim()
+                    : null;
+            const { bound, live, path } = bindSessionGeneration(projectRoot, {
+                sessionId: bindSessionId,
+                payloadLoaded: options.confirmPayloadLoaded,
+            });
+            if (options.json) {
+                return {
+                    exitCode: 0,
+                    stdout: `${JSON.stringify({
+                        success: true,
+                        action: "bind",
+                        bound,
+                        live,
+                        path,
+                    }, null, 2)}\n`,
+                    stderr: "",
+                };
+            }
+            return {
+                exitCode: 0,
+                stdout: `[deft freshness] bound session to live generation ${live.generation} ` +
+                    `(content v${live.contentVersion})\n` +
+                    `  bind path: ${path}\n` +
+                    "  Re-loaded payload surfaces are now the session's bound generation.\n",
+                stderr: "",
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (options.json) {
+                return {
+                    exitCode: 2,
+                    stdout: `${JSON.stringify({ success: false, action: "bind", error: message }, null, 2)}\n`,
+                    stderr: "",
+                };
+            }
+            return { exitCode: 2, stdout: "", stderr: `freshness:bind: ${message}\n` };
+        }
+    }
+    // report (default): omitted --session-id recovers ritual session_id;
+    // empty --session-id forces default bind; non-empty uses that id only.
+    const reportSessionId = options.sessionId === undefined
+        ? undefined
+        : options.sessionId.trim().length > 0
+            ? options.sessionId.trim()
+            : null;
+    const report = reportFreshness(projectRoot, { sessionId: reportSessionId });
+    const exitCode = freshnessReportExitCode(report);
+    if (options.json) {
+        return {
+            exitCode,
+            stdout: `${JSON.stringify(freshnessReportToJson(report), null, 2)}\n`,
+            stderr: "",
+        };
+    }
+    return {
+        exitCode,
+        stdout: formatFreshnessReport(report),
+        stderr: "",
+    };
+}
+/** Core-module main entry for dispatch (stdout/stderr + process.exit). */
+export function mainEntry(argv = process.argv.slice(2)) {
+    const result = runFreshnessCli(argv);
+    if (result.stdout) {
+        process.stdout.write(result.stdout);
+    }
+    if (result.stderr) {
+        process.stderr.write(result.stderr);
+    }
+    return result.exitCode;
+}
+//# sourceMappingURL=cli.js.map

package/dist/freshness/compare.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Bound vs live freshness comparison (#3117).
+ */
+import { type BoundGeneration, type FreshnessReport, type LiveGeneration } from "./types.js";
+export declare const REBIND_GUIDANCE: string;
+export declare const MID_MISSION_SAFETY: string;
+export declare const UNBOUND_GUIDANCE: string;
+/**
+ * Compare bound vs live generation and surface fingerprints.
+ *
+ * Ready only when state is `current` (bound matches live for used surfaces).
+ */
+export declare function compareFreshness(bound: BoundGeneration | null, live: LiveGeneration | null): FreshnessReport;
+//# sourceMappingURL=compare.d.ts.map

package/dist/freshness/compare.js

@@ -0,0 +1,134 @@
+/**
+ * Bound vs live freshness comparison (#3117).
+ */
+import { differingSurfaces } from "./generation.js";
+import { HARD_SURFACES, SOFT_SURFACES, } from "./types.js";
+export const REBIND_GUIDANCE = "Rebind without restarting the shared host runtime: re-load payload surfaces " +
+    "(skills, rituals, templates, commands) into the session context, then run " +
+    "`deft freshness:bind` (or `task freshness:bind`). Prefer `deft session:start --rearm` " +
+    "or `deft session:ready` when ritual state is still valid on this worktree.";
+export const MID_MISSION_SAFETY = "Mid-mission safety: park and hand off in-flight work before a hard refresh/rebind. " +
+    "An empty session after refresh is not work complete — resume from the handoff, " +
+    "not from a blank context.";
+export const UNBOUND_GUIDANCE = "No session bind recorded. Load payload surfaces into the session and run " +
+    "`deft freshness:bind` (session:start binds automatically on mutation posture). " +
+    "Disk-only version probes are insufficient for session readiness.";
+function partitionDiffs(diffs) {
+    const hardSet = new Set(HARD_SURFACES);
+    const softSet = new Set(SOFT_SURFACES);
+    const hard = [];
+    const soft = [];
+    for (const s of diffs) {
+        if (hardSet.has(s)) {
+            hard.push(s);
+        }
+        else if (softSet.has(s)) {
+            soft.push(s);
+        }
+        else {
+            // Unknown surface: treat as hard (fail closed for trust).
+            hard.push(s);
+        }
+    }
+    return { hard, soft };
+}
+/**
+ * Compare bound vs live generation and surface fingerprints.
+ *
+ * Ready only when state is `current` (bound matches live for used surfaces).
+ */
+export function compareFreshness(bound, live) {
+    if (bound === null) {
+        return {
+            boundGeneration: null,
+            liveGeneration: live?.generation ?? null,
+            boundContentVersion: null,
+            liveContentVersion: live?.contentVersion ?? null,
+            state: "unbound",
+            differingSurfaces: [],
+            hardDiffs: [],
+            softDiffs: [],
+            ready: false,
+            rebindGuidance: UNBOUND_GUIDANCE,
+            midMissionSafety: MID_MISSION_SAFETY,
+            live,
+            bound: null,
+        };
+    }
+    if (live === null) {
+        return {
+            boundGeneration: bound.boundGeneration,
+            liveGeneration: null,
+            boundContentVersion: bound.contentVersion,
+            liveContentVersion: null,
+            state: "stale_hard",
+            differingSurfaces: ["payload", "version"],
+            hardDiffs: ["payload", "version"],
+            softDiffs: [],
+            ready: false,
+            rebindGuidance: "Live generation token missing. Run `directive update` / `deft update` to stamp " +
+                "the deposit, then rebind. " +
+                REBIND_GUIDANCE,
+            midMissionSafety: MID_MISSION_SAFETY,
+            live: null,
+            bound,
+        };
+    }
+    const diffs = differingSurfaces(bound.surfaces, live.surfaces);
+    const { hard, soft } = partitionDiffs(diffs);
+    const generationMismatch = bound.boundGeneration !== live.generation;
+    let state;
+    if (!generationMismatch && diffs.length === 0) {
+        state = "current";
+    }
+    else if (hard.length > 0 || generationMismatch) {
+        // Generation advance without hard surface proof still means payload re-apply.
+        if (generationMismatch &&
+            hard.length === 0 &&
+            soft.length > 0 &&
+            diffs.length === soft.length) {
+            state = "stale_soft";
+        }
+        else if (generationMismatch && hard.length === 0 && diffs.length === 0) {
+            // Generation bumped with identical fingerprints (rare) — treat as hard.
+            state = "stale_hard";
+        }
+        else if (hard.length > 0) {
+            state = "stale_hard";
+        }
+        else {
+            state = "stale_hard";
+        }
+    }
+    else {
+        state = "stale_soft";
+    }
+    // Clarify generation-only mismatch with no surface info on bound: hard.
+    if (generationMismatch && Object.keys(bound.surfaces).length === 0) {
+        state = "stale_hard";
+    }
+    const ready = state === "current";
+    const rebindGuidance = state === "current"
+        ? "Session is current: bound generation matches live for used surfaces."
+        : state === "stale_soft"
+            ? `Advisory drift (${soft.join(", ") || "soft surfaces"}). Continue with caution; ` +
+                `rebind when convenient. ${REBIND_GUIDANCE}`
+            : `Hard drift (generation and/or ${hard.join(", ") || "payload surfaces"}). ` +
+                `Rebind before trusted work. ${REBIND_GUIDANCE}`;
+    return {
+        boundGeneration: bound.boundGeneration,
+        liveGeneration: live.generation,
+        boundContentVersion: bound.contentVersion,
+        liveContentVersion: live.contentVersion,
+        state,
+        differingSurfaces: diffs,
+        hardDiffs: hard,
+        softDiffs: soft,
+        ready,
+        rebindGuidance,
+        midMissionSafety: MID_MISSION_SAFETY,
+        live,
+        bound,
+    };
+}
+//# sourceMappingURL=compare.js.map

package/dist/freshness/generation.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Live deposit generation token (#3117).
+ *
+ * Stamped on successful deposit apply/refresh as a monotonic integer so long-lived
+ * sessions can compare bound vs live without host-specific session APIs.
+ */
+import { type FreshnessSurface, type LiveGeneration, type SurfaceFingerprints } from "./types.js";
+/**
+ * Relative path under project for the live generation token.
+ *
+ * Lives under `.deft/` (not `.deft/core/`) so a full-tree payload replace
+ * (`replaceTree` on update) does not wipe the monotonic counter (#3117).
+ */
+export declare const LIVE_GENERATION_REL: string;
+export declare function liveGenerationPath(projectRoot: string): string;
+export interface StampLiveGenerationOptions {
+    readonly contentVersion: string;
+    readonly stampedBy: string;
+    /**
+     * When true, always bump the monotonic counter (payload swapped / init apply).
+     * When false, ensure the token exists and matches contentVersion without bumping
+     * if already current (already-current refresh path).
+     */
+    readonly increment: boolean;
+    readonly nowIso?: string;
+    readonly surfaces?: SurfaceFingerprints;
+}
+/** Build default surface fingerprints from a content version string. */
+export declare function defaultSurfaceFingerprints(contentVersion: string): SurfaceFingerprints;
+/** Parse a live generation record from disk JSON (or null if invalid/missing). */
+export declare function parseLiveGeneration(raw: unknown): LiveGeneration | null;
+/** Read the live generation token from the deposit (null when absent/unreadable). */
+export declare function readLiveGeneration(projectRoot: string): LiveGeneration | null;
+/**
+ * Stamp (or ensure) the live deposit generation token after a successful apply.
+ *
+ * Monotonic: successful payload swap / init always increments. Already-current
+ * refresh ensures a readable token exists without advancing the counter when the
+ * content version is unchanged.
+ */
+export declare function stampLiveGeneration(projectRoot: string, options: StampLiveGenerationOptions): LiveGeneration;
+/** Surfaces that differ between two fingerprint maps. */
+export declare function differingSurfaces(bound: SurfaceFingerprints | null | undefined, live: SurfaceFingerprints | null | undefined, surfaceSet?: readonly FreshnessSurface[]): FreshnessSurface[];
+//# sourceMappingURL=generation.d.ts.map