audit-tools 0.28.0

package/dist/remediate/state/store.d.ts

@@ -0,0 +1,65 @@
+import type { PartialCompletionTerminal } from "audit-tools/shared";
+import { RemediationPlan, RemediationItemState, ClarificationRequest, ClosingPlan, CoverageLedger } from "./types.js";
+export interface RemediationState {
+    status: "pending" | "planning" | "waiting_for_clarification" | "implementing" | "triage" | "waiting_for_triage" | "closing" | "complete";
+    plan?: RemediationPlan;
+    items?: Record<string, RemediationItemState>;
+    clarifications?: ClarificationRequest[];
+    closing_plan?: ClosingPlan;
+    started_at?: string;
+    step_count?: number;
+    plan_coverage?: CoverageLedger;
+    /**
+     * Set when the dispatch engine fires a partial-completion terminal (empty pool
+     * or livelock guard). When present, `decideNextStep` treats stranded
+     * documented/pending items as `blocked` and routes the run to close rather
+     * than looping forever on undispatchable work (INV-X06 / OBL-S09).
+     */
+    partial_completion_terminal?: PartialCompletionTerminal;
+    /**
+     * Reason the run was routed to close without all items reaching a terminal
+     * status. Set by the triage phase on `halt` so the close phase can stamp
+     * a `user_halted` marker in the partial report.
+     */
+    closing_context?: "user_halted";
+}
+export declare const LOCK_TIMEOUT_MS: number;
+export declare class StateStore {
+    private artifactsDir;
+    private readonly _correlationId?;
+    constructor(artifactsDir: string, _correlationId?: string | undefined);
+    init(): Promise<void>;
+    /**
+     * Read state.json and schema-validate it. Returns null when the file is
+     * absent. Throws when the file is present but fails schema validation
+     * (corrupt or version-drifted — callers must not silently swallow such a
+     * state and hand it to the state machine). INV-remediate-state-01.
+     *
+     * Does NOT hold the lock — use `mutate` for any read-modify-write transition
+     * that requires TOCTOU safety (INV-remediate-state-02).
+     */
+    loadState(): Promise<RemediationState | null>;
+    /**
+     * TOCTOU-safe read-modify-write: acquires the file lock ONCE, loads the
+     * current state (or null), passes it to `fn`, and writes the returned state
+     * before releasing the lock. No other holder can interleave between the load
+     * and the save. INV-remediate-state-02 + INV-remediate-state-03.
+     */
+    mutate(fn: (current: RemediationState | null) => Promise<RemediationState>): Promise<RemediationState>;
+    /**
+     * Save state.json unconditionally (no TOCTOU protection). Prefer `mutate`
+     * for transitions; use this only when the caller holds an external guarantee
+     * that no concurrent writer exists (e.g. single-agent close phase).
+     * INV-remediate-state-04: the durable write goes through the shared atomic
+     * writer (temp + atomic rename), the single source for atomic JSON writes.
+     */
+    saveState(state: RemediationState): Promise<void>;
+    /**
+     * Persist state.json while the caller already holds the lock. Delegates to the
+     * shared `writeJsonFile` (temp + atomic rename) — the lock-agnostic single
+     * source for atomic JSON writes — so this store carries no inline writer of
+     * its own.
+     */
+    private _writeStateLocked;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/remediate/state/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/remediate/state/store.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,WAAW,EACX,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EACF,SAAS,GACT,UAAU,GACV,2BAA2B,GAC3B,cAAc,GACd,QAAQ,GACR,oBAAoB,GACpB,SAAS,GACT,UAAU,CAAC;IACf,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC7C,cAAc,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACxC,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,cAAc,CAAC;IAC/B;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,yBAAyB,CAAC;IACxD;;;;OAIG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC;CACjC;AA0CD,eAAO,MAAM,eAAe,QAAyC,CAAC;AAUtE,qBAAa,UAAU;IAEnB,OAAO,CAAC,YAAY;IAEpB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;gBAFxB,YAAY,EAAE,MAAM,EAEX,cAAc,CAAC,EAAE,MAAM,YAAA;IAGpC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;;;;;OAQG;IACG,SAAS,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAmBnD;;;;;OAKG;IACG,MAAM,CACV,EAAE,EAAE,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,KAAK,OAAO,CAAC,gBAAgB,CAAC,GAClE,OAAO,CAAC,gBAAgB,CAAC;IA8B5B;;;;;;OAMG;IACG,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYvD;;;;;OAKG;YACW,iBAAiB;CAGhC"}

package/dist/remediate/state/store.js

@@ -0,0 +1,141 @@
+import { readFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { isFileMissingError, writeJsonFile, withFileLock, STALE_LOCK_MS, } from "audit-tools/shared";
+/** Known status values for RemediationState — used for schema validation on load. */
+const KNOWN_STATUSES = new Set([
+    "pending",
+    "planning",
+    "waiting_for_clarification",
+    "implementing",
+    "triage",
+    "waiting_for_triage",
+    "closing",
+    "complete",
+]);
+/** Validate that a parsed JSON value is a usable RemediationState. */
+function validateState(value) {
+    const errors = [];
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        errors.push("state.json must be a JSON object");
+        return errors;
+    }
+    const obj = value;
+    if (!("status" in obj)) {
+        errors.push("Missing required field: status");
+    }
+    else if (!KNOWN_STATUSES.has(obj["status"])) {
+        errors.push(`Unknown status "${String(obj["status"])}"; expected one of: ${[...KNOWN_STATUSES].join(", ")}`);
+    }
+    return errors;
+}
+const STATE_FILENAME = "state.json";
+const LOCK_FILENAME = "state.lock";
+// Acquire timeout for the shared file lock, DERIVED to stay safely below shared
+// fileLock's STALE_LOCK_MS rather than hardcoded — tying them programmatically so
+// the invariant can't silently drift. A fresh-but-held lock then times out
+// deterministically before it could be reclaimed as stale; an equal/greater
+// timeout makes that a load-sensitive boundary race (the lock is written just
+// before the acquire starts, so its stale point precedes the deadline). The margin
+// absorbs the write→acquire gap, loop overhead, and load drift.
+const LOCK_TIMEOUT_MARGIN_MS = 10_000;
+export const LOCK_TIMEOUT_MS = STALE_LOCK_MS - LOCK_TIMEOUT_MARGIN_MS;
+function statePath(artifactsDir) {
+    return join(artifactsDir, STATE_FILENAME);
+}
+function lockPath(artifactsDir) {
+    return join(artifactsDir, LOCK_FILENAME);
+}
+export class StateStore {
+    artifactsDir;
+    _correlationId;
+    constructor(artifactsDir, 
+    // correlationId retained for API compatibility; no longer used in lock body
+    _correlationId) {
+        this.artifactsDir = artifactsDir;
+        this._correlationId = _correlationId;
+    }
+    async init() {
+        await mkdir(this.artifactsDir, { recursive: true });
+    }
+    /**
+     * Read state.json and schema-validate it. Returns null when the file is
+     * absent. Throws when the file is present but fails schema validation
+     * (corrupt or version-drifted — callers must not silently swallow such a
+     * state and hand it to the state machine). INV-remediate-state-01.
+     *
+     * Does NOT hold the lock — use `mutate` for any read-modify-write transition
+     * that requires TOCTOU safety (INV-remediate-state-02).
+     */
+    async loadState() {
+        try {
+            const data = await readFile(statePath(this.artifactsDir), "utf8");
+            const parsed = JSON.parse(data);
+            const errors = validateState(parsed);
+            if (errors.length > 0) {
+                throw new Error(`state.json failed schema validation: ${errors.join("; ")}`);
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (isFileMissingError(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * TOCTOU-safe read-modify-write: acquires the file lock ONCE, loads the
+     * current state (or null), passes it to `fn`, and writes the returned state
+     * before releasing the lock. No other holder can interleave between the load
+     * and the save. INV-remediate-state-02 + INV-remediate-state-03.
+     */
+    async mutate(fn) {
+        await mkdir(this.artifactsDir, { recursive: true });
+        const lock = lockPath(this.artifactsDir);
+        let next;
+        await withFileLock(lock, async () => {
+            // Load inside the lock — no TOCTOU gap between load and save.
+            let current = null;
+            try {
+                const data = await readFile(statePath(this.artifactsDir), "utf8");
+                const parsed = JSON.parse(data);
+                const errors = validateState(parsed);
+                if (errors.length > 0) {
+                    throw new Error(`state.json failed schema validation: ${errors.join("; ")}`);
+                }
+                current = parsed;
+            }
+            catch (err) {
+                if (!isFileMissingError(err))
+                    throw err;
+            }
+            next = await fn(current);
+            await this._writeStateLocked(next);
+        }, LOCK_TIMEOUT_MS);
+        return next;
+    }
+    /**
+     * Save state.json unconditionally (no TOCTOU protection). Prefer `mutate`
+     * for transitions; use this only when the caller holds an external guarantee
+     * that no concurrent writer exists (e.g. single-agent close phase).
+     * INV-remediate-state-04: the durable write goes through the shared atomic
+     * writer (temp + atomic rename), the single source for atomic JSON writes.
+     */
+    async saveState(state) {
+        await mkdir(this.artifactsDir, { recursive: true });
+        const lock = lockPath(this.artifactsDir);
+        await withFileLock(lock, async () => {
+            await this._writeStateLocked(state);
+        }, LOCK_TIMEOUT_MS);
+    }
+    /**
+     * Persist state.json while the caller already holds the lock. Delegates to the
+     * shared `writeJsonFile` (temp + atomic rename) — the lock-agnostic single
+     * source for atomic JSON writes — so this store carries no inline writer of
+     * its own.
+     */
+    async _writeStateLocked(state) {
+        await writeJsonFile(statePath(this.artifactsDir), state);
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/remediate/state/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/remediate/state/store.ts"],"names":[],"mappings":"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"}