@deftai/directive-core 0.96.0 → 0.97.0

package/dist/delivery-attempt/fingerprint.js

@@ -0,0 +1,100 @@
+/**
+ * Failure fingerprinting for delivery-attempt circuit breaker (#3143).
+ *
+ * Free-form model judgment alone is not sufficient. Prefer structured
+ * stage/code fields; normalize volatile identifiers out of messages.
+ */
+import { createHash } from "node:crypto";
+/** Strip volatile tokens that must not affect fingerprint stability. */
+const VOLATILE_PATTERNS = [
+    // ISO timestamps first
+    /\b\d{4}-\d{2}-\d{2}T[\d:.]+Z?\b/gi,
+    // UUIDs before long digit runs (UUID tail is 12 hex digits)
+    /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi,
+    // Hex digests (git SHAs etc.)
+    /\b[0-9a-f]{40}\b/gi,
+    /\b[0-9a-f]{64}\b/gi,
+    // Epoch-ish numbers (after UUID so 12-digit UUID tails are not partially eaten)
+    /\b\d{10,13}\b/g,
+    // Absolute / home paths
+    /(?:[A-Za-z]:)?(?:\\|\/)(?:Users|home|tmp|var|private)[^\s'"]+/gi,
+    /(?:[A-Za-z]:\\|[\\/])[^\s'"]+/g,
+    // Secret-like assignments
+    /\b(?:token|password|secret|api[_-]?key|authorization)\s*[:=]\s*\S+/gi,
+    /Bearer\s+\S+/gi,
+    // Run / attempt ids
+    /\b(?:run|attempt|job)[-_]?id[=:]\s*\S+/gi,
+    // Line numbers that churn
+    /:\d+(?::\d+)?/g,
+];
+/**
+ * Normalize a free-form failure message for fingerprinting.
+ * Removes volatile identifiers, timestamps, paths, and secret-like values.
+ */
+export function normalizeFailureMessage(message) {
+    if (message === null || message === undefined)
+        return "";
+    let out = message.normalize("NFKC");
+    for (const re of VOLATILE_PATTERNS) {
+        out = out.replace(re, "<redacted>");
+    }
+    return out
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .replace(/[^\w\s.<>=/_-]/g, "")
+        .trim()
+        .slice(0, 512);
+}
+/**
+ * Derive a stable redacted fingerprint from structured failure fields.
+ * SHA-256 hex truncated to 32 chars for compact ledger storage.
+ */
+export function computeFailureFingerprint(input) {
+    const stage = (input.stage ?? "unknown").trim().toLowerCase() || "unknown";
+    const code = (input.code ?? "").trim().toLowerCase();
+    const resource = (input.resourceClass ?? "").trim().toLowerCase();
+    const msg = normalizeFailureMessage(input.message);
+    const material = [stage, code, resource, msg].join("|");
+    return createHash("sha256").update(material, "utf8").digest("hex").slice(0, 32);
+}
+/**
+ * Build a FailureInfo from structured fields.
+ * Defaults retryability to `unknown` when not provided.
+ */
+export function buildFailureInfo(input) {
+    const stage = (input.stage ?? "unknown").trim() || "unknown";
+    const code = input.code === null || input.code === undefined || String(input.code).trim() === ""
+        ? null
+        : String(input.code).trim();
+    const resourceClass = input.resourceClass === null ||
+        input.resourceClass === undefined ||
+        String(input.resourceClass).trim() === ""
+        ? null
+        : String(input.resourceClass).trim();
+    return {
+        stage,
+        code,
+        fingerprint: computeFailureFingerprint({
+            stage,
+            code,
+            message: input.message,
+            resourceClass,
+        }),
+        retryability: input.retryability ?? "unknown",
+        resourceClass,
+    };
+}
+/** Infer retryability from structured code when adapter does not set it. */
+export function inferRetryability(code) {
+    if (code === null || code === undefined || code.trim() === "")
+        return "unknown";
+    const c = code.trim().toUpperCase();
+    if (/TIMEOUT|THROTTLE|RATE_LIMIT|ECONNRESET|ECONNREFUSED|ETIMEDOUT|503|429|UNAVAILABLE|TEMPORARY/.test(c)) {
+        return "transient";
+    }
+    if (/SCHEMA|CONFIG|PERMISSION|AUTHZ|FORBIDDEN|INVALID|VALIDATION|NOT_FOUND|404|401|403|PRECONDITION|INVARIANT/.test(c)) {
+        return "deterministic";
+    }
+    return "unknown";
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/delivery-attempt/handoff.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Terminal handoff contract for blocked delivery attempts (#3143).
+ *
+ * Persisted before the worker exits so a successor cannot restart an
+ * exhausted loop. Excludes raw secret-bearing logs.
+ */
+import type { DeliveryUnitLedger, PreDispatchDecision, ResumeCondition, TerminalHandoff } from "./types.js";
+export declare function nextSafeActionFor(decision: PreDispatchDecision): string;
+export declare function defaultResumeFor(decision: PreDispatchDecision): ResumeCondition;
+export declare function buildTerminalHandoff(options: {
+    readonly ledger: DeliveryUnitLedger;
+    readonly decision: PreDispatchDecision;
+    readonly now?: string;
+    readonly overridePermitted?: boolean;
+}): TerminalHandoff;
+/**
+ * Human-readable halt report (operator-visible). No secret fields.
+ */
+export declare function formatHandoffReport(handoff: TerminalHandoff): string;
+/**
+ * Strip any accidental secret-like keys from a handoff-shaped object before persist.
+ * Defense in depth — ledger fields are already structured.
+ */
+export declare function redactHandoffForPersist(handoff: TerminalHandoff): TerminalHandoff;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/delivery-attempt/handoff.js

@@ -0,0 +1,102 @@
+/**
+ * Terminal handoff contract for blocked delivery attempts (#3143).
+ *
+ * Persisted before the worker exits so a successor cannot restart an
+ * exhausted loop. Excludes raw secret-bearing logs.
+ */
+import { utcIso } from "./types.js";
+export function nextSafeActionFor(decision) {
+    switch (decision) {
+        case "DENY_DUPLICATE_ACTIVE":
+            return "Wait for the active attempt to finish or cancel it; do not start a duplicate dispatch.";
+        case "BLOCK_NON_RETRYABLE":
+            return "Fix the deterministic configuration/schema/permission failure, record a relevant material delta, then resume.";
+        case "BLOCK_NO_MATERIAL_PROGRESS":
+            return "Change code/config/evidence that addresses the failing invariant, or record an audited operator override.";
+        case "BLOCK_REPEATED_UNKNOWN":
+            return "Investigate the unknown failure class with fresh evidence; do not auto-retry until a material delta or override is recorded.";
+        case "BLOCK_ATTEMPT_BUDGET":
+            return "Phase attempt budget exhausted. Rescope, abandon, or record a bounded operator override with rationale.";
+        case "BLOCK_ELAPSED_BUDGET":
+            return "Elapsed-time budget exhausted. Suspend-and-wake monitoring preferred over polling; override only with audit.";
+        case "BLOCK_TOOL_OR_TOKEN_BUDGET":
+            return "Tool-call or token budget exhausted. Halt automatic dispatch; operator decides override or abandon.";
+        default:
+            return "Halt automatic re-dispatch; review ledger and decide next human action.";
+    }
+}
+export function defaultResumeFor(decision) {
+    if (decision === "DENY_DUPLICATE_ACTIVE") {
+        return {
+            kind: "monitor-wake",
+            description: "active attempt reaches a terminal status",
+            satisfied: false,
+        };
+    }
+    if (decision === "BLOCK_ELAPSED_BUDGET" || decision === "BLOCK_TOOL_OR_TOKEN_BUDGET") {
+        return {
+            kind: "operator-override",
+            description: "audited operator override or phase budget reset",
+            satisfied: false,
+        };
+    }
+    return {
+        kind: "material-delta",
+        description: nextSafeActionFor(decision),
+        satisfied: false,
+    };
+}
+export function buildTerminalHandoff(options) {
+    const { ledger, decision } = options;
+    const fingerprint = ledger.lastFailure?.fingerprint ?? null;
+    const sameFailureCount = fingerprint !== null ? (ledger.sameFailureCounts[fingerprint] ?? 0) : 0;
+    const resume = ledger.resumeCondition ?? defaultResumeFor(decision);
+    return {
+        schemaVersion: 1,
+        scopeId: ledger.scopeId,
+        targetId: ledger.targetId,
+        workflowId: ledger.workflowId,
+        lastSourceRevision: ledger.lastSourceRevision,
+        failure: ledger.lastFailure,
+        totalAttempts: ledger.attempts.length,
+        failedAttemptCount: ledger.failedAttemptCount,
+        sameFailureCount,
+        elapsedSeconds: ledger.totalElapsedSeconds,
+        toolCallCount: ledger.totalToolCallCount,
+        hostTokenCount: ledger.totalHostTokenCount,
+        lastMaterialDelta: ledger.lastMaterialDelta,
+        denyReason: decision,
+        nextSafeAction: nextSafeActionFor(decision),
+        resumeCondition: resume,
+        overridePermitted: options.overridePermitted !== false,
+        recordedAt: utcIso(options.now),
+    };
+}
+/**
+ * Human-readable halt report (operator-visible). No secret fields.
+ */
+export function formatHandoffReport(handoff) {
+    const lines = [
+        "BLOCKED: delivery-attempt circuit breaker (#3143)",
+        `scope=${handoff.scopeId} target=${handoff.targetId} workflow=${handoff.workflowId}`,
+        `revision=${handoff.lastSourceRevision ?? "n/a"}`,
+        `decision=${handoff.denyReason}`,
+        `attempts=${handoff.totalAttempts} failed=${handoff.failedAttemptCount} sameFailure=${handoff.sameFailureCount}`,
+        `elapsedSeconds=${handoff.elapsedSeconds} toolCalls=${handoff.toolCallCount} hostTokens=${handoff.hostTokenCount ?? "n/a"}`,
+    ];
+    if (handoff.failure) {
+        lines.push(`failure.stage=${handoff.failure.stage} code=${handoff.failure.code ?? "n/a"} retryability=${handoff.failure.retryability}`, `failure.fingerprint=${handoff.failure.fingerprint}`);
+    }
+    lines.push(`materialDelta=${handoff.lastMaterialDelta.map((d) => d.kind).join(",") || "none"}`, `nextSafeAction=${handoff.nextSafeAction}`, `resume=${handoff.resumeCondition.kind}: ${handoff.resumeCondition.description}`, `overridePermitted=${handoff.overridePermitted}`);
+    return lines.join("\n");
+}
+/**
+ * Strip any accidental secret-like keys from a handoff-shaped object before persist.
+ * Defense in depth — ledger fields are already structured.
+ */
+export function redactHandoffForPersist(handoff) {
+    // TerminalHandoff has no free-form log fields; return as-is for type stability.
+    // Callers must not attach raw logs to this object.
+    return handoff;
+}
+//# sourceMappingURL=handoff.js.map

package/dist/delivery-attempt/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Delivery-attempt material-progress circuit breaker (#3143).
+ *
+ * Deterministic pre-dispatch gate + durable unit ledger for autonomous
+ * delivery and operational-acceptance loops. Implements the mechanical
+ * enforcement surface for the delivery/acceptance subset of dual-stop (#2442).
+ *
+ * @see content/docs/delivery-attempt.md
+ */
+export { type BeginAttemptOnDiskInput, beginAttemptOnDisk, type CompleteAttemptOnDiskInput, completeAttemptOnDisk, } from "./disk-begin.js";
+export { evaluateAndPrepareBlock, evaluatePreDispatch, } from "./evaluate.js";
+export { buildFailureInfo, computeFailureFingerprint, type FingerprintInput, inferRetryability, normalizeFailureMessage, } from "./fingerprint.js";
+export { buildTerminalHandoff, defaultResumeFor, formatHandoffReport, nextSafeActionFor, redactHandoffForPersist, } from "./handoff.js";
+export { activeAttempts, beginAttempt, clearBlockIfResumed, completeAttempt, deliveryAttemptsDir, emptyUnitLedger, hasActiveAttempt, isUnitLockReclaimable, type LoadUnitLedgerResult, listUnitLedgers, loadOrCreateUnitLedger, loadUnitLedger, loadUnitLedgerResult, MemoryLedgerStore, markBlocked, newAttemptId, parseUnitLedger, recordOperatorOverride, saveUnitLedger, UNIT_LOCK_STALE_MS, unitLedgerFilename, unitLedgerPath, withUnitLock, } from "./ledger.js";
+export { evaluateMaterialProgress, isRevisionChangeMaterial, type MaterialProgressResult, } from "./material-delta.js";
+export { ATTEMPT_STATUSES, ATTEMPT_TRIGGERS, type AttemptStatus, type AttemptTrigger, DEFAULT_DELIVERY_BUDGET_POLICY, DELIVERY_ATTEMPT_DIR, DELIVERY_ATTEMPT_SCHEMA_VERSION, type DeliveryAttemptRecord, type DeliveryBudgetPolicy, type DeliveryUnitLedger, deliveryUnitKey, type FailureInfo, isAllowDecision, isBlockDecision, isDenyDecision, MATERIAL_DELTA_KINDS, type MaterialDeltaClaim, type MaterialDeltaKind, mergePolicy, type OperatorOverride, PRE_DISPATCH_DECISIONS, type PreDispatchDecision, type PreDispatchDecisionEvent, type PreDispatchInput, type PreDispatchResult, RETRYABILITY, type ResumeCondition, type Retryability, type TerminalHandoff, utcIso, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/delivery-attempt/index.js

@@ -0,0 +1,17 @@
+/**
+ * Delivery-attempt material-progress circuit breaker (#3143).
+ *
+ * Deterministic pre-dispatch gate + durable unit ledger for autonomous
+ * delivery and operational-acceptance loops. Implements the mechanical
+ * enforcement surface for the delivery/acceptance subset of dual-stop (#2442).
+ *
+ * @see content/docs/delivery-attempt.md
+ */
+export { beginAttemptOnDisk, completeAttemptOnDisk, } from "./disk-begin.js";
+export { evaluateAndPrepareBlock, evaluatePreDispatch, } from "./evaluate.js";
+export { buildFailureInfo, computeFailureFingerprint, inferRetryability, normalizeFailureMessage, } from "./fingerprint.js";
+export { buildTerminalHandoff, defaultResumeFor, formatHandoffReport, nextSafeActionFor, redactHandoffForPersist, } from "./handoff.js";
+export { activeAttempts, beginAttempt, clearBlockIfResumed, completeAttempt, deliveryAttemptsDir, emptyUnitLedger, hasActiveAttempt, isUnitLockReclaimable, listUnitLedgers, loadOrCreateUnitLedger, loadUnitLedger, loadUnitLedgerResult, MemoryLedgerStore, markBlocked, newAttemptId, parseUnitLedger, recordOperatorOverride, saveUnitLedger, UNIT_LOCK_STALE_MS, unitLedgerFilename, unitLedgerPath, withUnitLock, } from "./ledger.js";
+export { evaluateMaterialProgress, isRevisionChangeMaterial, } from "./material-delta.js";
+export { ATTEMPT_STATUSES, ATTEMPT_TRIGGERS, DEFAULT_DELIVERY_BUDGET_POLICY, DELIVERY_ATTEMPT_DIR, DELIVERY_ATTEMPT_SCHEMA_VERSION, deliveryUnitKey, isAllowDecision, isBlockDecision, isDenyDecision, MATERIAL_DELTA_KINDS, mergePolicy, PRE_DISPATCH_DECISIONS, RETRYABILITY, utcIso, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/delivery-attempt/ledger.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Durable delivery-attempt unit ledger (#3143).
+ *
+ * Persists under `.deft/delivery-attempts/` so counters survive worker
+ * replacement, session restart, context compaction, and new revisions.
+ */
+import type { AttemptTrigger, DeliveryAttemptRecord, DeliveryUnitLedger, FailureInfo, MaterialDeltaClaim, PreDispatchDecision, ResumeCondition } from "./types.js";
+export declare function deliveryAttemptsDir(projectRoot: string): string;
+/**
+ * Stable collision-resistant filename for a unit key.
+ * Full SHA-256 hex (64 chars) — do not truncate base64 of the raw key (#3143 P1).
+ */
+export declare function unitLedgerFilename(scopeId: string, targetId: string, workflowId: string): string;
+export declare function unitLedgerPath(projectRoot: string, scopeId: string, targetId: string, workflowId: string): string;
+export declare function newAttemptId(prefix?: string): string;
+export declare function emptyUnitLedger(input: {
+    readonly scopeId: string;
+    readonly targetId: string;
+    readonly workflowId: string;
+    readonly phaseId?: string;
+    readonly now?: string;
+}): DeliveryUnitLedger;
+/**
+ * Parse a unit ledger from JSON. Returns null when required fields are invalid.
+ */
+export declare function parseUnitLedger(raw: unknown): DeliveryUnitLedger | null;
+export type LoadUnitLedgerResult = {
+    readonly status: "missing";
+} | {
+    readonly status: "ok";
+    readonly ledger: DeliveryUnitLedger;
+} | {
+    readonly status: "corrupt";
+    readonly detail: string;
+};
+/**
+ * Load unit ledger distinguishing missing vs corrupt.
+ * Corrupt persisted state MUST NOT be treated as a new empty unit (fail-closed).
+ */
+export declare function loadUnitLedgerResult(projectRoot: string, scopeId: string, targetId: string, workflowId: string): LoadUnitLedgerResult;
+/**
+ * Load unit ledger from disk, or null if missing.
+ * Throws when the file exists but is corrupt (fail-closed circuit breaker).
+ */
+export declare function loadUnitLedger(projectRoot: string, scopeId: string, targetId: string, workflowId: string): DeliveryUnitLedger | null;
+/** Persist unit ledger atomically under project root. */
+export declare function saveUnitLedger(projectRoot: string, ledger: DeliveryUnitLedger): void;
+/**
+ * Exclusive unit lock for begin/complete on disk (#3143 concurrent-snapshot P1).
+ * Uses O_EXCL create of a lock file under the delivery-attempts dir.
+ */
+/** @deprecated Kept for API stability; live PIDs are never time-reclaimed. */
+export declare const UNIT_LOCK_STALE_MS: number;
+interface UnitLockRecord {
+    readonly pid: number;
+    readonly token: string;
+    readonly startedAt: string;
+}
+/**
+ * Whether an existing lock may be reclaimed.
+ *
+ * **Live owner PID is never reclaimed** — including long critical sections and
+ * event-loop stalls. Only dead owners and corrupt/unreadable records are
+ * reclaimable. PID-reuse residual (dead owner, OS recycled the number onto an
+ * unrelated live process) requires manual `.lock` deletion.
+ */
+export declare function isUnitLockReclaimable(rec: UnitLockRecord | null): boolean;
+/**
+ * Acquire exclusive unit lock.
+ *
+ * Create is atomic: `containedWrite(..., mode: "create")` (O_EXCL) writes the
+ * owner record in the exclusive create (no empty-file window).
+ *
+ * Recovery when EEXIST (dead owner or corrupt record only):
+ * 1. Take an exclusive **reclaim ticket** (`*.lock.reclaim`) with create mode.
+ * 2. Under that ticket, re-read the lock; only unlink if still reclaimable
+ *    (owner still dead / corrupt). Live PIDs are never unlinked.
+ * 3. Create the replacement lock with create mode, then drop the ticket.
+ *
+ * The ticket serializes reclaimers so a delayed contender cannot unlink a
+ * live replacement lock.
+ */
+export declare function withUnitLock<T>(projectRoot: string, scopeId: string, targetId: string, workflowId: string, fn: () => T, options?: {
+    readonly nowMs?: number;
+    readonly staleMs?: number;
+}): T;
+/**
+ * Load or create empty unit ledger.
+ * Creates only when the file is missing — never on corrupt state.
+ */
+export declare function loadOrCreateUnitLedger(projectRoot: string, input: {
+    readonly scopeId: string;
+    readonly targetId: string;
+    readonly workflowId: string;
+    readonly phaseId?: string;
+    readonly now?: string;
+}): DeliveryUnitLedger;
+export declare function listUnitLedgers(projectRoot: string): DeliveryUnitLedger[];
+export declare function activeAttempts(ledger: DeliveryUnitLedger): readonly DeliveryAttemptRecord[];
+export declare function hasActiveAttempt(ledger: DeliveryUnitLedger): boolean;
+/**
+ * Open a new queued/running attempt. Caller must have passed evaluatePreDispatch.
+ * Does not re-check the gate (orchestrators own the order: evaluate → begin).
+ */
+export declare function beginAttempt(ledger: DeliveryUnitLedger, input: {
+    readonly attemptId?: string;
+    readonly sourceRevision: string;
+    readonly trigger: AttemptTrigger;
+    readonly status?: "queued" | "running";
+    readonly workerId?: string | null;
+    readonly externalRunId?: string | null;
+    readonly materialDelta?: readonly MaterialDeltaClaim[];
+    readonly now?: string;
+    /**
+     * When true, decrement override.remainingAttempts (ALLOW_OVERRIDE path).
+     * Also set when trigger is `"override"`. Ordinary automatic/retry begins
+     * that do not need override MUST leave this false so quota is preserved.
+     */
+    readonly consumeOverride?: boolean;
+}): {
+    ledger: DeliveryUnitLedger;
+    attempt: DeliveryAttemptRecord;
+};
+/**
+ * Record terminal outcome for an attempt. Increments budgets / sameFailureCounts
+ * on failure. Idempotent when the same externalRunId is already terminal.
+ */
+export declare function completeAttempt(ledger: DeliveryUnitLedger, input: {
+    readonly attemptId?: string;
+    readonly externalRunId?: string | null;
+    readonly status: "succeeded" | "failed" | "cancelled" | "blocked";
+    readonly failure?: FailureInfo | null;
+    readonly materialDelta?: readonly MaterialDeltaClaim[];
+    readonly elapsedSeconds?: number;
+    readonly toolCallCount?: number;
+    readonly hostTokenCount?: number | null;
+    readonly now?: string;
+}): DeliveryUnitLedger;
+/** Mark unit blocked with resume condition (persisted before worker exit). */
+export declare function markBlocked(ledger: DeliveryUnitLedger, decision: PreDispatchDecision, resume: ResumeCondition, now?: string): DeliveryUnitLedger;
+/** Clear block when resume condition is satisfied (caller sets satisfied=true). */
+export declare function clearBlockIfResumed(ledger: DeliveryUnitLedger, now?: string): DeliveryUnitLedger;
+/**
+ * Record an audited operator override. Preserves full attempt history.
+ * remainingAttempts starts at allowedAttempts.
+ */
+export declare function recordOperatorOverride(ledger: DeliveryUnitLedger, input: {
+    readonly actor: string;
+    readonly rationale: string;
+    readonly allowedAttempts?: number;
+    readonly expiresAt?: string | null;
+    readonly now?: string;
+}): DeliveryUnitLedger;
+/** In-memory ledger store for tests and pure evaluation paths. */
+export declare class MemoryLedgerStore {
+    private readonly map;
+    get(scopeId: string, targetId: string, workflowId: string): DeliveryUnitLedger | null;
+    set(ledger: DeliveryUnitLedger): void;
+    getOrCreate(input: {
+        readonly scopeId: string;
+        readonly targetId: string;
+        readonly workflowId: string;
+        readonly phaseId?: string;
+        readonly now?: string;
+    }): DeliveryUnitLedger;
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=ledger.d.ts.map