cool-workflow 0.1.80 → 0.1.81

package/dist/run-registry/gc.js

@@ -0,0 +1,251 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reclamationPolicy = reclamationPolicy;
+exports.reclaimEligibility = reclaimEligibility;
+exports.gcPlan = gcPlan;
+exports.gcRun = gcRun;
+exports.gcVerify = gcVerify;
+const reclamation_1 = require("../reclamation");
+const trust_audit_1 = require("../trust-audit");
+const policy_1 = require("./policy");
+/** Resolve the effective reclamation policy (defaults reclaim NOTHING). */
+function reclamationPolicy(overrides = {}) {
+    return { ...policy_1.DEFAULT_RUN_REGISTRY_POLICY, ...overrides };
+}
+/** Fail-closed eligibility: terminal AND archived AND no open feedback AND past
+ *  retention. Returns the matching refusal code, or null when eligible. Reads
+ *  the live-source-derived record; order yields distinct, stable codes. */
+function reclaimEligibility(record, policy, nowMs) {
+    if (record.tier === "reclaimed")
+        return "already-reclaimed";
+    const terminalStates = policy.reclaimStates && policy.reclaimStates.length ? policy.reclaimStates : ["completed", "failed"];
+    if (record.derivedLifecycle !== "completed" && record.derivedLifecycle !== "failed")
+        return "non-terminal";
+    if (!terminalStates.includes(record.derivedLifecycle))
+        return "non-terminal";
+    if (record.openFeedbackCount > 0)
+        return "open-feedback";
+    if (!record.archived)
+        return "not-archived";
+    const days = policy.reclaimAfterArchiveDays ?? 0;
+    if (days > 0) {
+        const archivedAtMs = record.archivedAt ? Date.parse(record.archivedAt) : NaN;
+        if (!Number.isFinite(archivedAtMs))
+            return "within-retention";
+        if (archivedAtMs > nowMs - days * 24 * 60 * 60 * 1000)
+            return "within-retention";
+    }
+    return null;
+}
+/** Resolve a single run to a one-element record list via locate() (repo-first),
+ *  avoiding a full-registry scan for single-run gc plan/run. */
+function recordsForRunId(host, runId, scope) {
+    const located = host.locate(runId, scope);
+    return located ? [located.record] : [];
+}
+/** Dry-run: compute eligible runs, per-kind bytes that WOULD be freed, and the
+ *  capability downgrade. Frees NOTHING. */
+function gcPlan(host, options = {}) {
+    const scope = options.scope || "home";
+    const policy = reclamationPolicy(options.policy);
+    const nowIso = options.now || new Date().toISOString();
+    const nowMs = Date.parse(nowIso);
+    // Fast, deterministic single-run path: resolve just that run via locate()
+    // (repo-first) so a home-scope plan never re-scans the whole registry.
+    const records = options.runId ? recordsForRunId(host, options.runId, scope) : host.buildIndex(scope).records;
+    const entries = [];
+    let bytesToFree = 0;
+    let eligibleCount = 0;
+    for (const record of records) {
+        const refusal = reclaimEligibility(record, policy, nowMs);
+        let plan;
+        try {
+            const run = host.loadRun(record.repo, record.runId);
+            plan = (0, reclamation_1.planReclamation)(run, { keepScratch: policy.keepScratch, keepSnapshots: policy.keepSnapshots });
+        }
+        catch {
+            entries.push({
+                runId: record.runId,
+                repo: record.repo,
+                eligible: false,
+                reason: "unreadable",
+                tier: record.tier || "live",
+                capability: record.capability || "re-runnable",
+                capabilityReason: record.capabilityReason || "live-full",
+                bytesToFree: 0,
+                byKind: {},
+                freeable: []
+            });
+            continue;
+        }
+        const eligible = refusal === null;
+        const entry = {
+            runId: record.runId,
+            repo: record.repo,
+            eligible,
+            reason: eligible ? "eligible" : refusal,
+            tier: record.tier || "live",
+            capability: plan.capability,
+            capabilityReason: plan.capabilityReason,
+            bytesToFree: eligible ? plan.bytesToFree : 0,
+            byKind: eligible ? plan.byKind : {},
+            freeable: eligible ? plan.freeable.map((f) => ({ path: f.path, kind: f.kind, bytes: f.bytes })) : []
+        };
+        entries.push(entry);
+        if (eligible) {
+            eligibleCount += 1;
+            bytesToFree += plan.bytesToFree;
+        }
+    }
+    return {
+        schemaVersion: 1,
+        scope,
+        generatedAt: nowIso,
+        policy: {
+            reclaimAfterArchiveDays: policy.reclaimAfterArchiveDays ?? 0,
+            keepSnapshots: Boolean(policy.keepSnapshots),
+            keepScratch: Boolean(policy.keepScratch),
+            reclaimStates: policy.reclaimStates && policy.reclaimStates.length ? policy.reclaimStates : ["completed", "failed"]
+        },
+        total: entries.length,
+        eligibleCount,
+        bytesToFree,
+        entries,
+        nextAction: eligibleCount ? "node scripts/cw.js gc run" : "node scripts/cw.js run search"
+    };
+}
+/** Execute the write-ahead reclamation transaction for eligible runs. Bounded
+ *  (`maxReclaimRuns` / `maxReclaimBytes`), fail-closed on any incomplete
+ *  skeleton. Produces a tombstone and frees the bulk. */
+function gcRun(host, options = {}) {
+    const scope = options.scope || "home";
+    const policy = reclamationPolicy(options.policy);
+    const nowIso = options.now || new Date().toISOString();
+    const nowMs = Date.parse(nowIso);
+    const records = options.runId ? recordsForRunId(host, options.runId, scope) : host.buildIndex(scope).records;
+    const maxRuns = options.limit ?? (policy.maxReclaimRuns || 0);
+    const maxBytes = policy.maxReclaimBytes || 0;
+    const reclaimed = [];
+    const refused = [];
+    let totalBytesFreed = 0;
+    for (const record of records) {
+        const refusal = reclaimEligibility(record, policy, nowMs);
+        if (refusal) {
+            refused.push({ runId: record.runId, code: refusal });
+            continue;
+        }
+        if (maxRuns > 0 && reclaimed.length >= maxRuns)
+            break;
+        let run;
+        try {
+            run = host.loadRun(record.repo, record.runId);
+        }
+        catch {
+            refused.push({ runId: record.runId, code: "unreadable" });
+            continue;
+        }
+        try {
+            const result = (0, reclamation_1.runReclamation)(run, {
+                now: nowIso,
+                actor: options.actor,
+                policy: { reclaimAfterArchiveDays: policy.reclaimAfterArchiveDays, keepScratch: policy.keepScratch, keepSnapshots: policy.keepSnapshots },
+                reclaimPolicy: { keepScratch: policy.keepScratch, keepSnapshots: policy.keepSnapshots }
+            });
+            // No post-free saveCheckpoint: runReclamation now DURABLY persists the
+            // result-node re-point inside the transaction (before any byte is freed),
+            // so state.json can never reference a freed path even on a crash here.
+            reclaimed.push({
+                runId: record.runId,
+                bytesFreed: result.bytesFreed,
+                tombstoneHash: result.tombstone.tombstoneHash,
+                capability: result.tombstone.capability,
+                capabilityReason: result.tombstone.capabilityReason
+            });
+            // Independent reclamation WITNESS in the tamper-evident trust-audit chain:
+            // proves this run WAS reclaimed even if reclaimed.json is later deleted — so
+            // `gc verify` can tell proof-deletion apart from never-reclaimed.
+            (0, trust_audit_1.recordTrustAuditEvent)(run, {
+                kind: "run.reclaimed",
+                decision: "recorded",
+                source: "cw-validated",
+                metadata: { tombstoneHash: result.tombstone.tombstoneHash, bytesFreed: result.bytesFreed, capability: result.tombstone.capability }
+            });
+            totalBytesFreed += result.bytesFreed;
+            if (maxBytes > 0 && totalBytesFreed >= maxBytes)
+                break;
+        }
+        catch (error) {
+            if (error instanceof reclamation_1.ReclamationError)
+                refused.push({ runId: record.runId, code: error.code });
+            else
+                throw error;
+        }
+    }
+    return {
+        schemaVersion: 1,
+        scope,
+        generatedAt: nowIso,
+        dryRun: false,
+        reclaimed,
+        refused,
+        totalBytesFreed,
+        nextAction: reclaimed.length ? "node scripts/cw.js gc verify <run-id>" : "node scripts/cw.js gc plan"
+    };
+}
+/** Re-prove a reclaimed run: skeleton schema-complete, tombstone chain
+ *  recomputed-and-untampered, each reconstructable artifact re-derived from its
+ *  RETAINED inputs to its expectDigest, and eligible-when-reclaimed. */
+function gcVerify(host, runId, options = {}) {
+    const scope = options.scope || "home";
+    const located = host.locate(runId, scope);
+    if (!located) {
+        return {
+            schemaVersion: 1,
+            runId,
+            reclaimed: false,
+            verified: false,
+            tier: "live",
+            capability: "re-runnable",
+            chainLength: 0,
+            checks: [{ name: "located", pass: false, code: "not-reclaimed", detail: "run source not found" }],
+            nextAction: "node scripts/cw.js registry refresh" + (scope === "home" ? " --scope home" : "")
+        };
+    }
+    const run = host.loadRun(located.record.repo, runId);
+    const result = (0, reclamation_1.verifyReclamation)(run);
+    const checks = result.checks.map((c) => ({ name: c.name, pass: c.pass, code: c.code, detail: c.detail }));
+    // Eligible-when-reclaimed: each tombstone must have sealed a terminal verdict.
+    let eligibleWhenReclaimed = result.reclaimed;
+    for (const tombstone of result.tombstones) {
+        const terminal = tombstone.skeleton.finalVerdict?.terminal === true;
+        if (!terminal) {
+            eligibleWhenReclaimed = false;
+            checks.push({ name: `eligible-when-reclaimed:${tombstone.tombstoneId}`, pass: false, code: "ineligible-when-reclaimed", detail: "non-terminal verdict sealed" });
+        }
+    }
+    const last = result.tombstones[result.tombstones.length - 1];
+    // Independent witness: a trust-audit "run.reclaimed" event proves this run was
+    // reclaimed even if reclaimed.json was deleted. A present witness + missing proof
+    // = the proof was deleted/tampered (NOT "never reclaimed") — fail closed so
+    // `gc verify <run> && deploy` cannot pass on a wiped reclamation record.
+    const witnessed = (0, trust_audit_1.listTrustAuditEvents)(run).some((event) => event.kind === "run.reclaimed");
+    const proofDeleted = witnessed && !result.reclaimed;
+    if (proofDeleted) {
+        checks.push({ name: "reclaim-witness", pass: false, code: "reclaim-proof-deleted", detail: "trust-audit attests reclamation but reclaimed.json is missing/empty" });
+    }
+    const reclaimed = result.reclaimed || proofDeleted;
+    const verified = result.verified && eligibleWhenReclaimed && !proofDeleted;
+    return {
+        schemaVersion: 1,
+        runId,
+        reclaimed,
+        verified,
+        tier: located.record.tier || (reclaimed ? "reclaimed" : "live"),
+        capability: located.record.capability || "re-runnable",
+        capabilityReason: located.record.capabilityReason,
+        tombstoneHash: last?.tombstoneHash,
+        chainLength: result.tombstones.length,
+        checks,
+        nextAction: verified ? "node scripts/cw.js run show " + runId : "node scripts/cw.js gc plan"
+    };
+}

package/dist/run-registry/policy.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RUN_REGISTRY_POLICY = exports.RUN_REGISTRY_SCHEMA_VERSION = void 0;
+exports.RUN_REGISTRY_SCHEMA_VERSION = 1;
+exports.DEFAULT_RUN_REGISTRY_POLICY = {
+    schemaVersion: 1,
+    archiveOlderThanDays: 0,
+    archiveStates: ["completed", "failed"],
+    defaultQueuePriority: 100,
+    reclaimAfterArchiveDays: 0,
+    reclaimStates: ["completed", "failed"],
+    keepSnapshots: false,
+    keepScratch: false,
+    maxReclaimRuns: 0,
+    maxReclaimBytes: 0
+};

package/dist/run-registry/queue.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queueFilePath = queueFilePath;
+exports.loadQueue = loadQueue;
+exports.saveQueue = saveQueue;
+exports.queueAdd = queueAdd;
+exports.queueList = queueList;
+exports.queueShow = queueShow;
+exports.queueDrain = queueDrain;
+// Durable run-queue operations for the run registry (FreeBSD-audit R2 deep).
+// Carved out of run-registry.ts so the RunRegistry class no longer bundles the
+// stateful queue cluster; the class keeps the public methods as thin delegators.
+//
+// BEHAVIOR-PRESERVING — pure code movement, zero logic change. Each function
+// takes a `QueueHost` (the registry, narrowed to exactly the file-access +
+// repo-registration helpers the queue needs) so it stays a function of its
+// inputs, matching the existing router pattern (orchestrator/*-operations.ts,
+// run-registry/derive.ts + format.ts).
+//
+// The queue file lives beside the other home-registry plain files (EXPLICIT,
+// INSPECTABLE STATE): readable, diffable, no hidden database. Cross-process
+// read-modify-write is locked (v0.1.40, P1-D) so a concurrent add/drain can
+// never drop or double-drain an entry.
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const state_1 = require("../state");
+const derive_1 = require("./derive");
+function queueFilePath(host) {
+    return node_path_1.default.join(host.homeRegistryDir(), "queue.json");
+}
+function loadQueue(host) {
+    const file = queueFilePath(host);
+    if (!node_fs_1.default.existsSync(file))
+        return [];
+    try {
+        const parsed = (0, state_1.readJson)(file);
+        return Array.isArray(parsed.entries) ? parsed.entries : [];
+    }
+    catch {
+        return [];
+    }
+}
+function saveQueue(host, entries) {
+    (0, state_1.writeJson)(queueFilePath(host), { schemaVersion: 1, entries }, { durable: true });
+}
+function queueAdd(host, options = {}) {
+    const repo = options.repo ? node_path_1.default.resolve(options.repo) : host.repoRoot;
+    // Cross-process read-modify-write on the home queue: lock so a concurrently
+    // added task can never vanish (v0.1.40, P1-D).
+    return (0, state_1.withFileLock)(queueFilePath(host), () => {
+        const entries = loadQueue(host);
+        const entry = {
+            schemaVersion: 1,
+            id: options.id || (0, derive_1.queueId)(),
+            runId: options.runId,
+            appId: options.appId,
+            workflowId: options.workflowId,
+            repo,
+            priority: Number.isFinite(options.priority) ? Number(options.priority) : host.defaultQueuePriority,
+            enqueuedAt: new Date().toISOString(),
+            status: "pending",
+            inputs: options.inputs,
+            note: options.note
+        };
+        entries.push(entry);
+        host.registerRepo(repo);
+        saveQueue(host, entries);
+        return entry;
+    });
+}
+function queueList(host, options = {}) {
+    let entries = loadQueue(host);
+    if (options.status)
+        entries = entries.filter((e) => e.status === options.status);
+    if (options.repo) {
+        const repo = node_path_1.default.resolve(options.repo);
+        entries = entries.filter((e) => node_path_1.default.resolve(e.repo) === repo);
+    }
+    entries = [...entries].sort(derive_1.compareQueue);
+    return { schemaVersion: 1, total: entries.length, entries };
+}
+function queueShow(host, id) {
+    const entry = loadQueue(host).find((e) => e.id === id);
+    if (!entry)
+        throw new Error(`Queue entry not found: ${id}`);
+    return entry;
+}
+/** Drain the next N ready/pending entries in policy order, marking them drained.
+ *  CW records readiness/order; the HOST still executes the workers. */
+function queueDrain(host, options = {}) {
+    const limit = (0, derive_1.clampInt)(options.limit, 1, 1);
+    const repoFilter = options.repo ? node_path_1.default.resolve(options.repo) : undefined;
+    // Lock the drain RMW so two hosts can never double-drain the same entry
+    // (v0.1.40, P1-D — the scheduling kernel's concurrency ceiling now holds
+    // across processes, not just within one).
+    return (0, state_1.withFileLock)(queueFilePath(host), () => {
+        const entries = loadQueue(host);
+        const drainable = entries
+            .filter((e) => e.status === "pending" || e.status === "ready")
+            .filter((e) => !repoFilter || node_path_1.default.resolve(e.repo) === repoFilter)
+            .sort(derive_1.compareQueue);
+        const drained = [];
+        const drainedAt = new Date().toISOString();
+        for (const entry of drainable.slice(0, limit)) {
+            entry.status = "drained";
+            entry.drainedAt = drainedAt;
+            drained.push(entry);
+        }
+        saveQueue(host, entries);
+        const remaining = entries.filter((e) => e.status === "pending" || e.status === "ready").length;
+        return { schemaVersion: 1, drained, remaining };
+    });
+}