@deftai/directive-core 0.94.0 → 0.96.0

package/dist/freshness/generation.js

@@ -0,0 +1,172 @@
+/**
+ * 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 { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
+import { FRESHNESS_SCHEMA_VERSION, } 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 const LIVE_GENERATION_REL = join(".deft", "GENERATION.json");
+export function liveGenerationPath(projectRoot) {
+    return join(resolve(projectRoot), LIVE_GENERATION_REL);
+}
+function nowIsoDefault() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function normalizeVersion(version) {
+    return version.trim().replace(/^v/, "");
+}
+/** Build default surface fingerprints from a content version string. */
+export function defaultSurfaceFingerprints(contentVersion) {
+    const v = normalizeVersion(contentVersion);
+    const tagged = v.startsWith("v") ? v : `v${v}`;
+    return {
+        payload: v,
+        version: tagged,
+        templates: v,
+        skills: v,
+        docs: v,
+    };
+}
+function isSurfaceFingerprints(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    for (const [k, v] of Object.entries(value)) {
+        if (typeof k !== "string" || typeof v !== "string") {
+            return false;
+        }
+    }
+    return true;
+}
+/** Parse a live generation record from disk JSON (or null if invalid/missing). */
+export function parseLiveGeneration(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return null;
+    }
+    const rec = raw;
+    const generation = rec.generation;
+    if (typeof generation !== "number" || !Number.isInteger(generation) || generation < 1) {
+        return null;
+    }
+    const contentVersion = typeof rec.contentVersion === "string" && rec.contentVersion.trim()
+        ? rec.contentVersion.trim()
+        : null;
+    if (contentVersion === null) {
+        return null;
+    }
+    const stampedAt = typeof rec.stampedAt === "string" && rec.stampedAt.trim() ? rec.stampedAt.trim() : null;
+    if (stampedAt === null) {
+        return null;
+    }
+    const stampedBy = typeof rec.stampedBy === "string" && rec.stampedBy.trim() ? rec.stampedBy.trim() : "unknown";
+    const surfaces = isSurfaceFingerprints(rec.surfaces)
+        ? rec.surfaces
+        : defaultSurfaceFingerprints(contentVersion);
+    return {
+        schemaVersion: FRESHNESS_SCHEMA_VERSION,
+        generation,
+        contentVersion: normalizeVersion(contentVersion),
+        stampedAt,
+        stampedBy,
+        surfaces,
+    };
+}
+/** Read the live generation token from the deposit (null when absent/unreadable). */
+export function readLiveGeneration(projectRoot) {
+    const path = liveGenerationPath(projectRoot);
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const text = readFileSync(path, "utf8");
+        const parsed = JSON.parse(text);
+        return parseLiveGeneration(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+function writeLiveGeneration(projectRoot, token) {
+    const root = resolve(projectRoot);
+    const target = liveGenerationPath(projectRoot);
+    const body = `${JSON.stringify(token, null, 2)}\n`;
+    try {
+        containedWrite({
+            root,
+            target,
+            data: body,
+            mode: "replace",
+        });
+    }
+    catch (err) {
+        if (err instanceof ContainedWriteError) {
+            throw err;
+        }
+        throw err;
+    }
+    return target;
+}
+/**
+ * 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 function stampLiveGeneration(projectRoot, options) {
+    const contentVersion = normalizeVersion(options.contentVersion);
+    const surfaces = options.surfaces ?? defaultSurfaceFingerprints(contentVersion);
+    const stampedAt = options.nowIso ?? nowIsoDefault();
+    const prior = readLiveGeneration(projectRoot);
+    let generation;
+    if (prior === null) {
+        generation = 1;
+    }
+    else if (options.increment) {
+        generation = prior.generation + 1;
+    }
+    else if (normalizeVersion(prior.contentVersion) !== contentVersion) {
+        // Content drifted without an explicit increment flag — still advance.
+        generation = prior.generation + 1;
+    }
+    else {
+        // Already current: do not rewrite GENERATION.json (avoids dirty trees under
+        // core.autocrlf=true after idempotent `directive update` — Windows #2118).
+        return prior;
+    }
+    const token = {
+        schemaVersion: FRESHNESS_SCHEMA_VERSION,
+        generation,
+        contentVersion,
+        stampedAt,
+        stampedBy: options.stampedBy,
+        surfaces,
+    };
+    writeLiveGeneration(projectRoot, token);
+    return token;
+}
+/** Surfaces that differ between two fingerprint maps. */
+export function differingSurfaces(bound, live, surfaceSet = ["payload", "version", "templates", "skills", "docs"]) {
+    const out = [];
+    for (const surface of surfaceSet) {
+        const b = bound?.[surface] ?? null;
+        const l = live?.[surface] ?? null;
+        if (b === null && l === null) {
+            continue;
+        }
+        if (b !== l) {
+            out.push(surface);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=generation.js.map

package/dist/freshness/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Host-agnostic freshness contract (#3117).
+ *
+ * Monotonic generation on deposit apply, session bind of that generation, and
+ * bound-vs-live reports with current | stale_soft | stale_hard states.
+ */
+export * from "./bind.js";
+export * from "./cli.js";
+export * from "./compare.js";
+export * from "./generation.js";
+export * from "./report.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/freshness/index.js

@@ -0,0 +1,13 @@
+/**
+ * Host-agnostic freshness contract (#3117).
+ *
+ * Monotonic generation on deposit apply, session bind of that generation, and
+ * bound-vs-live reports with current | stale_soft | stale_hard states.
+ */
+export * from "./bind.js";
+export * from "./cli.js";
+export * from "./compare.js";
+export * from "./generation.js";
+export * from "./report.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/freshness/report.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Freshness report assembly + human formatting (#3117).
+ */
+import type { FreshnessReport } from "./types.js";
+export interface ReportFreshnessOptions {
+    /**
+     * Host session identity. When set, only that session's bind is read
+     * (multi-agent isolation).
+     *
+     * When omitted, recover the current ritual `session_id` from
+     * `.deft/ritual-state.json` (written by `session:start`) so bare
+     * `freshness:report` matches the bind just created. Pass `null` to force
+     * the default project bind path only.
+     */
+    readonly sessionId?: string | null;
+}
+/**
+ * Resolve which bind identity a report/bind should use.
+ *
+ * Precedence:
+ * 1. Explicit non-empty `sessionId`
+ * 2. `DEFT_SESSION_ID` env (per-process; multi-agent safe)
+ * 3. Ritual `session_id` from `.deft/ritual-state.json` (same-worktree operator)
+ * 4. `null` → default bind path only
+ *
+ * Trusted `current`/`ready` still requires a **pinned** identity (explicit or env).
+ * Ritual recovery alone is convenience for bind write target, not for trusted ready.
+ */
+export declare function resolveReportSessionId(projectRoot: string, explicit?: string | null, env?: NodeJS.ProcessEnv): string | null;
+/** True when the caller pinned identity via explicit arg or DEFT_SESSION_ID. */
+export declare function hasPinnedSessionIdentity(explicit?: string | null, env?: NodeJS.ProcessEnv): boolean;
+/** Build a freshness report for the project (bound vs live on disk). */
+export declare function reportFreshness(projectRoot: string, options?: ReportFreshnessOptions): FreshnessReport;
+/** Human-readable multi-line freshness report. */
+export declare function formatFreshnessReport(report: FreshnessReport): string;
+/** JSON-serializable shape for --json output. */
+export declare function freshnessReportToJson(report: FreshnessReport): Record<string, unknown>;
+/**
+ * Exit code for freshness:report.
+ * 0 = current (ready); 1 = stale_soft or unbound (caution); 2 = stale_hard (must rebind).
+ */
+export declare function freshnessReportExitCode(report: FreshnessReport): 0 | 1 | 2;
+//# sourceMappingURL=report.d.ts.map

package/dist/freshness/report.js

@@ -0,0 +1,139 @@
+/**
+ * Freshness report assembly + human formatting (#3117).
+ */
+import { readRitualState } from "../session/ritual-sentinel.js";
+import { readBoundGeneration } from "./bind.js";
+import { compareFreshness } from "./compare.js";
+import { readLiveGeneration } from "./generation.js";
+/**
+ * Resolve which bind identity a report/bind should use.
+ *
+ * Precedence:
+ * 1. Explicit non-empty `sessionId`
+ * 2. `DEFT_SESSION_ID` env (per-process; multi-agent safe)
+ * 3. Ritual `session_id` from `.deft/ritual-state.json` (same-worktree operator)
+ * 4. `null` → default bind path only
+ *
+ * Trusted `current`/`ready` still requires a **pinned** identity (explicit or env).
+ * Ritual recovery alone is convenience for bind write target, not for trusted ready.
+ */
+export function resolveReportSessionId(projectRoot, explicit, env = process.env) {
+    if (explicit === null) {
+        return null;
+    }
+    if (typeof explicit === "string" && explicit.trim().length > 0) {
+        return explicit.trim();
+    }
+    const fromEnv = (env.DEFT_SESSION_ID ?? "").trim();
+    if (fromEnv.length > 0) {
+        return fromEnv;
+    }
+    try {
+        const [state] = readRitualState(projectRoot);
+        const id = state?.sessionId?.trim();
+        return id && id.length > 0 ? id : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when the caller pinned identity via explicit arg or DEFT_SESSION_ID. */
+export function hasPinnedSessionIdentity(explicit, env = process.env) {
+    if (typeof explicit === "string" && explicit.trim().length > 0) {
+        return true;
+    }
+    return (env.DEFT_SESSION_ID ?? "").trim().length > 0;
+}
+/** Build a freshness report for the project (bound vs live on disk). */
+export function reportFreshness(projectRoot, options = {}) {
+    const sessionId = resolveReportSessionId(projectRoot, options.sessionId);
+    const bound = readBoundGeneration(projectRoot, { sessionId });
+    const live = readLiveGeneration(projectRoot);
+    const report = compareFreshness(bound, live);
+    // Multi-agent safety: never claim ready/current without a pinned session identity.
+    // Ritual recovery alone can point at another concurrent session's bind on a
+    // shared worktree (Greptile). Hosts set DEFT_SESSION_ID or pass --session-id.
+    if (report.ready && !hasPinnedSessionIdentity(options.sessionId)) {
+        return {
+            ...report,
+            state: "stale_soft",
+            ready: false,
+            rebindGuidance: "Session identity is not pinned. Set DEFT_SESSION_ID to this session's id " +
+                "(printed by session:start) or pass --session-id before trusted work. " +
+                "Bare reports without a pinned id cannot certify readiness when multiple " +
+                "sessions share a worktree.",
+        };
+    }
+    // Host must attest payload surfaces were loaded for this generation (session:start
+    // does; CLI bind requires --confirm-payload-loaded). Disk bind alone is insufficient.
+    if (report.ready && bound?.payloadLoaded !== true) {
+        return {
+            ...report,
+            state: "stale_soft",
+            ready: false,
+            rebindGuidance: "Bind has no payload-loaded attestation. Re-load skills/rituals/templates into " +
+                "the session, then rebind with payloadLoaded (session:start, or " +
+                "`deft freshness:bind -- --confirm-payload-loaded`).",
+        };
+    }
+    return report;
+}
+/** Human-readable multi-line freshness report. */
+export function formatFreshnessReport(report) {
+    const lines = [
+        "[deft freshness] bound vs live generation",
+        `  state              : ${report.state}`,
+        `  ready              : ${report.ready ? "yes" : "no"}`,
+        `  bound generation   : ${report.boundGeneration ?? "(none)"}`,
+        `  live generation    : ${report.liveGeneration ?? "(none)"}`,
+        `  bound content      : ${report.boundContentVersion ?? "(none)"}`,
+        `  live content       : ${report.liveContentVersion ?? "(none)"}`,
+    ];
+    if (report.differingSurfaces.length > 0) {
+        lines.push(`  differing surfaces: ${report.differingSurfaces.join(", ")}`);
+        if (report.hardDiffs.length > 0) {
+            lines.push(`  hard diffs         : ${report.hardDiffs.join(", ")}`);
+        }
+        if (report.softDiffs.length > 0) {
+            lines.push(`  soft diffs         : ${report.softDiffs.join(", ")}`);
+        }
+    }
+    else if (report.state !== "unbound") {
+        lines.push("  differing surfaces: (none)");
+    }
+    lines.push(`  rebind             : ${report.rebindGuidance}`);
+    if (report.state === "stale_hard" || report.state === "unbound") {
+        lines.push(`  mid-mission        : ${report.midMissionSafety}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** JSON-serializable shape for --json output. */
+export function freshnessReportToJson(report) {
+    return {
+        state: report.state,
+        ready: report.ready,
+        bound_generation: report.boundGeneration,
+        live_generation: report.liveGeneration,
+        bound_content_version: report.boundContentVersion,
+        live_content_version: report.liveContentVersion,
+        differing_surfaces: report.differingSurfaces,
+        hard_diffs: report.hardDiffs,
+        soft_diffs: report.softDiffs,
+        rebind_guidance: report.rebindGuidance,
+        mid_mission_safety: report.midMissionSafety,
+        live: report.live,
+        bound: report.bound,
+    };
+}
+/**
+ * Exit code for freshness:report.
+ * 0 = current (ready); 1 = stale_soft or unbound (caution); 2 = stale_hard (must rebind).
+ */
+export function freshnessReportExitCode(report) {
+    if (report.state === "current")
+        return 0;
+    if (report.state === "stale_hard")
+        return 2;
+    return 1;
+}
+//# sourceMappingURL=report.js.map

package/dist/freshness/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Host-agnostic freshness contract types (#3117).
+ *
+ * Bound generation is what a long-lived session loaded; live generation is what
+ * the on-disk deposit currently stamps after a successful apply/refresh.
+ * Disk-only "up to date" is insufficient for session readiness.
+ */
+/** Schema version for GENERATION.json and session-bind.json. */
+export declare const FRESHNESS_SCHEMA_VERSION: 1;
+/**
+ * Freshness state for a session relative to the live deposit.
+ *
+ * - `current` — bound matches live for used surfaces
+ * - `stale_soft` — additive / advisory drift; safe to continue with caution
+ * - `stale_hard` — evidence-untrustworthy drift; rebind before trusted work
+ * - `unbound` — no session bind recorded (not ready for trusted work)
+ */
+export declare const FRESHNESS_STATES: readonly ["current", "stale_soft", "stale_hard", "unbound"];
+export type FreshnessState = (typeof FRESHNESS_STATES)[number];
+/** Surface ids compared in a freshness report. */
+export declare const FRESHNESS_SURFACES: readonly ["payload", "version", "templates", "skills", "docs"];
+export type FreshnessSurface = (typeof FRESHNESS_SURFACES)[number];
+/** Hard surfaces: drift means evidence is untrustworthy without rebind. */
+export declare const HARD_SURFACES: readonly FreshnessSurface[];
+/** Soft / advisory surfaces: drift is cautionary, not evidence-invalidating alone. */
+export declare const SOFT_SURFACES: readonly FreshnessSurface[];
+/** Fingerprints for each surface at a generation (typically content version tags). */
+export type SurfaceFingerprints = Readonly<Partial<Record<FreshnessSurface, string>>>;
+/** Live deposit generation token written on successful apply/refresh. */
+export interface LiveGeneration {
+    readonly schemaVersion: typeof FRESHNESS_SCHEMA_VERSION;
+    readonly generation: number;
+    readonly contentVersion: string;
+    readonly stampedAt: string;
+    readonly stampedBy: string;
+    readonly surfaces: SurfaceFingerprints;
+}
+/** Session bind of the generation loaded into runtime context. */
+export interface BoundGeneration {
+    readonly schemaVersion: typeof FRESHNESS_SCHEMA_VERSION;
+    readonly boundGeneration: number;
+    readonly boundAt: string;
+    readonly contentVersion: string;
+    readonly surfaces: SurfaceFingerprints;
+    /** Optional host-supplied session identity (host-agnostic; not a host key scheme). */
+    readonly sessionId?: string | null;
+    /**
+     * Host attestation that payload surfaces for this generation were loaded into
+     * the session before bind. Required for trusted `current`/`ready`.
+     * session:start sets true; bare CLI bind requires `--confirm-payload-loaded`.
+     */
+    readonly payloadLoaded?: boolean;
+}
+/** Full freshness report comparing bound vs live. */
+export interface FreshnessReport {
+    readonly boundGeneration: number | null;
+    readonly liveGeneration: number | null;
+    readonly boundContentVersion: string | null;
+    readonly liveContentVersion: string | null;
+    readonly state: FreshnessState;
+    readonly differingSurfaces: readonly FreshnessSurface[];
+    readonly hardDiffs: readonly FreshnessSurface[];
+    readonly softDiffs: readonly FreshnessSurface[];
+    readonly ready: boolean;
+    readonly rebindGuidance: string;
+    readonly midMissionSafety: string;
+    readonly live: LiveGeneration | null;
+    readonly bound: BoundGeneration | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/freshness/types.js

@@ -0,0 +1,30 @@
+/**
+ * Host-agnostic freshness contract types (#3117).
+ *
+ * Bound generation is what a long-lived session loaded; live generation is what
+ * the on-disk deposit currently stamps after a successful apply/refresh.
+ * Disk-only "up to date" is insufficient for session readiness.
+ */
+/** Schema version for GENERATION.json and session-bind.json. */
+export const FRESHNESS_SCHEMA_VERSION = 1;
+/**
+ * Freshness state for a session relative to the live deposit.
+ *
+ * - `current` — bound matches live for used surfaces
+ * - `stale_soft` — additive / advisory drift; safe to continue with caution
+ * - `stale_hard` — evidence-untrustworthy drift; rebind before trusted work
+ * - `unbound` — no session bind recorded (not ready for trusted work)
+ */
+export const FRESHNESS_STATES = ["current", "stale_soft", "stale_hard", "unbound"];
+/** Surface ids compared in a freshness report. */
+export const FRESHNESS_SURFACES = ["payload", "version", "templates", "skills", "docs"];
+/** Hard surfaces: drift means evidence is untrustworthy without rebind. */
+export const HARD_SURFACES = [
+    "payload",
+    "version",
+    "templates",
+    "skills",
+];
+/** Soft / advisory surfaces: drift is cautionary, not evidence-invalidating alone. */
+export const SOFT_SURFACES = ["docs"];
+//# sourceMappingURL=types.js.map

package/dist/handoff-evidence/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Handoff evidence bound-proof contract (#3120).
+ *
+ * Makes invented remote artifact claims an illegal shape under status pass.
+ */
+export type { AxisEvidence, AxisState, HandoffEvidence, HandoffEvidenceValidation, HandoffFailClass, ProofStatus, RemoteProbe, } from "./validate.js";
+export { canClaimPass, detectRemoteClaims, probeBindsClaim, validateHandoffEvidence, } from "./validate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/handoff-evidence/index.js

@@ -0,0 +1,7 @@
+/**
+ * Handoff evidence bound-proof contract (#3120).
+ *
+ * Makes invented remote artifact claims an illegal shape under status pass.
+ */
+export { canClaimPass, detectRemoteClaims, probeBindsClaim, validateHandoffEvidence, } from "./validate.js";
+//# sourceMappingURL=index.js.map

package/dist/handoff-evidence/validate.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Deterministic handoff-evidence validator (#3120).
+ *
+ * status pass is forbidden when any remote artifact is claimed unless
+ * proof_status is bound and same-turn probe snippets cover each claim.
+ * Invented-done (false remote artifacts under pass) ranks stricter than
+ * empty-done (pass with no completion substance).
+ */
+/** Binding state for remote artifact claims in handoff evidence. */
+export type ProofStatus = "bound" | "unbound" | "n/a-no-remote-claim";
+/** Work / ship / gate axis state (local → forge → gates). */
+export type AxisState = "done" | "in_progress" | "not_started" | "blocked" | "n/a";
+/** Fail ranking: invented-done is stricter than empty-done. */
+export type HandoffFailClass = "none" | "empty-done" | "unbound-remote-claim" | "invented-done" | "shape-error";
+/** Same-turn live probe that binds a remote claim. */
+export interface RemoteProbe {
+    /** Command run this turn (e.g. `gh api repos/.../pulls/N`). */
+    readonly command: string;
+    /** Short raw snippet from that command's stdout (not narration). */
+    readonly snippet: string;
+}
+export interface AxisEvidence {
+    readonly state?: AxisState | string;
+    readonly notes?: string;
+}
+/**
+ * Portable handoff evidence block for builder / pre-pr / review-cycle exits.
+ * Free-text remote fields without bound probes are an illegal shape under pass.
+ */
+export interface HandoffEvidence {
+    /** Overall process status. `pass` is the strictest gate for remote claims. */
+    readonly status: "pass" | "fail" | "blocked" | "partial" | string;
+    /**
+     * Binding state. Required semantics:
+     * - `bound` when any remote claim is present and probes bind them
+     * - `n/a-no-remote-claim` when no remote PR/SHA/CI/review claim is made
+     * - `unbound` is never valid under status pass with remote claims
+     */
+    readonly proof_status?: ProofStatus | string;
+    /** Local work state (edits / tests / commits on the branch). */
+    readonly work?: AxisEvidence;
+    /** Ship state (pushed branch / PR exists). */
+    readonly ship?: AxisEvidence;
+    /** Gate state (CI / review on claimed HEAD). */
+    readonly gate?: AxisEvidence;
+    /** Remote PR URL claim (requires pr probe when set). */
+    readonly pr_url?: string | null;
+    /** Remote PR number claim (requires pr probe when set). */
+    readonly pr_number?: number | string | null;
+    /** Commit / HEAD SHA claim (requires sha probe when set). */
+    readonly commit_sha?: string | null;
+    /** Alias for commit_sha. */
+    readonly head_sha?: string | null;
+    /**
+     * CI claim. Values like green/pass/success/ok are remote claims.
+     * Neutral/unknown/pending without green semantics are not treated as claims.
+     */
+    readonly ci_status?: string | null;
+    /** Review score / confidence claim (requires review probe when set). */
+    readonly review_score?: number | string | null;
+    /** Same-turn probes that bind remote claims. */
+    readonly probes?: {
+        readonly pr?: RemoteProbe | null;
+        readonly sha?: RemoteProbe | null;
+        readonly ci?: RemoteProbe | null;
+        readonly review?: RemoteProbe | null;
+    };
+}
+export interface HandoffEvidenceValidation {
+    readonly ok: boolean;
+    readonly failClass: HandoffFailClass;
+    readonly reasons: readonly string[];
+    /** True when any remote PR/SHA/CI/review claim was detected. */
+    readonly hasRemoteClaims: boolean;
+    /** Claim keys that lack a binding probe. */
+    readonly unboundClaims: readonly string[];
+}
+/**
+ * True when the probe's raw snippet actually mentions the claimed remote value
+ * with token-level binding (not incidental substring collisions).
+ * Never throws on malformed claims — returns false instead.
+ *
+ * Scope: textual shape binding only. Live probe execution/provenance is agent
+ * process responsibility (preamble probe-then-fill); this library does not
+ * re-run forge/git commands.
+ */
+export declare function probeBindsClaim(claim: string, evidence: HandoffEvidence, probe: RemoteProbe | null | undefined): boolean;
+/** Detect which remote claim keys are present on the evidence object. */
+export declare function detectRemoteClaims(evidence: HandoffEvidence): string[];
+/**
+ * Validate handoff evidence against the #3120 bound-proof contract.
+ *
+ * Ranking when invalid under status pass:
+ * 1. invented-done — remote claims present without bound proof
+ * 2. empty-done — pass with no completion substance and no remote claims
+ * 3. unbound-remote-claim — non-pass status but still has unbound remote claims
+ * 4. shape-error — malformed proof_status / inconsistent n/a
+ */
+export declare function validateHandoffEvidence(evidence: HandoffEvidence): HandoffEvidenceValidation;
+/**
+ * Convenience: true when status may legally be pass for this evidence.
+ * Equivalent to validateHandoffEvidence(...).ok under a pass status intent.
+ */
+export declare function canClaimPass(evidence: HandoffEvidence): boolean;
+//# sourceMappingURL=validate.d.ts.map