harnery 0.5.0 → 0.7.0

package/dist/lib/decision/index.js

@@ -0,0 +1,523 @@
+/**
+ * Decision docket: a persistent queue of decisions an agent would otherwise
+ * route to a human, plus the lifecycle that carries each one from filing to a
+ * reviewed, graduated resolution.
+ *
+ * State layout (mirrors councils):
+ *   - `.harnery/decisions/<id>.json`      — one manifest per decision
+ *   - `.harnery/decisions/<id>/`          — long-form bodies (brief, options,
+ *                                            evidence write-up) as markdown
+ *   - `.harnery/decisions/archive/`       — graduated / terminal decisions move here
+ *
+ * This module is the engine only. It stores `tier` (0/1/2) and `stakes` as
+ * opaque typed fields; what those *mean* — which decisions belong to which
+ * tier — is host policy, applied by the filing agent, never encoded here. That
+ * keeps the docket generic across host projects.
+ *
+ * Every function takes `coordRoot` explicitly (the council pattern) so the
+ * state machine is trivially testable against a tmpdir. The command layer
+ * resolves the root once via `monorepoRoot()` and threads it down.
+ *
+ * Concurrency: one file per decision (no shared index to contend on) + atomic
+ * temp→rename writes. `claim` is last-writer-wins — deliberating the same
+ * decision twice wastes tokens, not correctness.
+ */
+import { randomBytes } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+export const DECISION_SCHEMA_VERSION = 1;
+/** Tier of human-involvement. Meaning is host policy; the engine only stores it. */
+export const DECISION_TIERS = [0, 1, 2];
+export const DECISION_STAKES = ["small", "medium", "high"];
+export const DECISION_STATUSES = [
+    "filed",
+    "triaged",
+    "deliberating",
+    "resolved",
+    "enacted",
+    "reviewed",
+    "archived",
+    "superseded",
+    "wontfix",
+];
+export const REVIEW_VERDICTS = [
+    "ratified",
+    "overridden",
+    "wrong-tier-high",
+    "wrong-tier-low",
+];
+export const TERMINAL_STATUSES = ["archived", "superseded", "wontfix"];
+/**
+ * Legal status transitions. `superseded` is reachable from any non-terminal
+ * state (a decision can be obsoleted at any point); `wontfix` closes an
+ * un-deliberated decision. `deliberating → triaged` allows the sweeper to
+ * re-triage a decision's tier on first touch (the self-triage safeguard).
+ */
+export const LEGAL_TRANSITIONS = {
+    filed: ["triaged", "deliberating", "resolved", "superseded", "wontfix"],
+    triaged: ["deliberating", "resolved", "superseded", "wontfix"],
+    deliberating: ["triaged", "resolved", "superseded", "wontfix"],
+    resolved: ["enacted", "reviewed", "superseded"],
+    enacted: ["reviewed", "superseded"],
+    reviewed: ["archived", "superseded"],
+    archived: [],
+    superseded: [],
+    wontfix: [],
+};
+// ─── Type guards ────────────────────────────────────────────────────────────
+export function isTier(n) {
+    return DECISION_TIERS.includes(n);
+}
+export function isStakes(s) {
+    return typeof s === "string" && DECISION_STAKES.includes(s);
+}
+export function isStatus(s) {
+    return typeof s === "string" && DECISION_STATUSES.includes(s);
+}
+export function isVerdict(v) {
+    return typeof v === "string" && REVIEW_VERDICTS.includes(v);
+}
+export function isTerminal(status) {
+    return TERMINAL_STATUSES.includes(status);
+}
+export function canTransition(from, to) {
+    return (LEGAL_TRANSITIONS[from] ?? []).includes(to);
+}
+// ─── Paths ──────────────────────────────────────────────────────────────────
+export function decisionsDir(coordRoot) {
+    return join(coordRoot, ".harnery", "decisions");
+}
+export function archiveDir(coordRoot) {
+    return join(decisionsDir(coordRoot), "archive");
+}
+export function manifestPath(coordRoot, id) {
+    return join(decisionsDir(coordRoot), `${id}.json`);
+}
+export function archivedManifestPath(coordRoot, id) {
+    return join(archiveDir(coordRoot), `${id}.json`);
+}
+export function decisionBodyDir(coordRoot, id) {
+    return join(decisionsDir(coordRoot), id);
+}
+// ─── Low-level IO ─────────────────────────────────────────────────────────────
+function nowIso() {
+    return new Date().toISOString();
+}
+function atomicWriteText(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, content, "utf8");
+    renameSync(tmp, path);
+}
+/**
+ * Kebab-case slug from question text: first 5 words, lowercased,
+ * non-alphanumerics stripped. Local (not imported from council) so the module
+ * stays standalone.
+ */
+export function deriveSlug(question) {
+    const cleaned = question
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]+/g, " ")
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 5)
+        .join("-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return cleaned || "decision";
+}
+/**
+ * Build a decision_id: `<slug>-<YYYY-MM-DD>-<4hex>`. The hex suffix is
+ * crypto-random (not a hash of the question) so two decisions sharing a
+ * slug + date don't collide.
+ */
+export function buildDecisionId(question, now = new Date()) {
+    const slug = deriveSlug(question);
+    const date = now.toISOString().slice(0, 10);
+    const hash = randomBytes(2).toString("hex");
+    return `${slug}-${date}-${hash}`;
+}
+/**
+ * Read a manifest by id, checking the active dir then the archive. Returns null
+ * if absent or unparseable. Throws on an unsupported schema_version (fail loud
+ * on a real-but-incompatible manifest, the way councils do).
+ */
+export function readManifest(coordRoot, id) {
+    for (const p of [manifestPath(coordRoot, id), archivedManifestPath(coordRoot, id)]) {
+        if (!existsSync(p))
+            continue;
+        const parsed = JSON.parse(readFileSync(p, "utf8"));
+        if (parsed.schema_version !== DECISION_SCHEMA_VERSION) {
+            throw new Error(`decision ${id}: unsupported schema_version=${parsed.schema_version} (expected ${DECISION_SCHEMA_VERSION})`);
+        }
+        return parsed;
+    }
+    return null;
+}
+/** Locate whichever manifest path (active or archive) currently holds this id. */
+function resolveManifestPath(coordRoot, id) {
+    const active = manifestPath(coordRoot, id);
+    if (existsSync(active))
+        return active;
+    const archived = archivedManifestPath(coordRoot, id);
+    if (existsSync(archived))
+        return archived;
+    return null;
+}
+export function writeManifest(coordRoot, manifest) {
+    const p = resolveManifestPath(coordRoot, manifest.decision_id) ??
+        manifestPath(coordRoot, manifest.decision_id);
+    atomicWriteText(p, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+export function fileDecision(coordRoot, input) {
+    if (!input.question?.trim())
+        return { ok: false, reason: "question is empty" };
+    if (!isTier(input.tier))
+        return { ok: false, reason: `invalid tier ${input.tier} (0 | 1 | 2)` };
+    if (!isStakes(input.stakes)) {
+        return {
+            ok: false,
+            reason: `invalid stakes "${input.stakes}" (${DECISION_STAKES.join(" | ")})`,
+        };
+    }
+    const now = input.now ?? new Date();
+    const id = buildDecisionId(input.question, now);
+    const ts = now.toISOString();
+    const manifest = {
+        schema_version: DECISION_SCHEMA_VERSION,
+        decision_id: id,
+        status: "filed",
+        tier: input.tier,
+        stakes: input.stakes,
+        question: input.question.trim(),
+        context: input.context?.trim() || undefined,
+        default_taken: input.defaultTaken?.trim() || null,
+        filed_by: input.filedBy,
+        filed_by_id: input.filedById,
+        filed_at: ts,
+        claimed_by: null,
+        council_id: null,
+        resolution: null,
+        review: null,
+        graduated_to: null,
+        superseded_by: null,
+        wontfix_reason: null,
+        updated_at: ts,
+    };
+    atomicWriteText(manifestPath(coordRoot, id), `${JSON.stringify(manifest, null, 2)}\n`);
+    if (input.brief?.trim()) {
+        atomicWriteText(join(decisionBodyDir(coordRoot, id), "brief.md"), `${input.brief.trim()}\n`);
+    }
+    return { ok: true, manifest };
+}
+// ─── Transitions ───────────────────────────────────────────────────────────────
+/**
+ * Apply a status change with legality + terminality checks, stamp updated_at,
+ * merge extra field patches, and persist. The single mutation chokepoint.
+ */
+function transition(coordRoot, id, to, patch = {}) {
+    const manifest = readManifest(coordRoot, id);
+    if (!manifest)
+        return { ok: false, reason: `no decision "${id}"` };
+    if (isTerminal(manifest.status) && manifest.status !== to) {
+        return { ok: false, reason: `decision is ${manifest.status} (terminal, read-only)` };
+    }
+    if (manifest.status !== to && !canTransition(manifest.status, to)) {
+        return {
+            ok: false,
+            reason: `illegal transition ${manifest.status} → ${to} (legal: ${(LEGAL_TRANSITIONS[manifest.status] ?? []).join(", ") || "none"})`,
+        };
+    }
+    const updated = {
+        ...manifest,
+        ...patch,
+        status: to,
+        updated_at: nowIso(),
+    };
+    writeManifest(coordRoot, updated);
+    return { ok: true, manifest: updated };
+}
+export function triageDecision(coordRoot, id, opts) {
+    if (opts.tier !== undefined && !isTier(opts.tier)) {
+        return { ok: false, reason: `invalid tier ${opts.tier} (0 | 1 | 2)` };
+    }
+    if (opts.stakes !== undefined && !isStakes(opts.stakes)) {
+        return {
+            ok: false,
+            reason: `invalid stakes "${opts.stakes}" (${DECISION_STAKES.join(" | ")})`,
+        };
+    }
+    const patch = {};
+    if (opts.tier !== undefined)
+        patch.tier = opts.tier;
+    if (opts.stakes !== undefined)
+        patch.stakes = opts.stakes;
+    return transition(coordRoot, id, "triaged", patch);
+}
+export function claimDecision(coordRoot, id, owner) {
+    if (!owner?.trim())
+        return { ok: false, reason: "claim owner is empty" };
+    return transition(coordRoot, id, "deliberating", { claimed_by: owner.trim() });
+}
+export function escalateToCouncil(coordRoot, id, councilId) {
+    if (!councilId?.trim())
+        return { ok: false, reason: "council id is empty" };
+    return transition(coordRoot, id, "deliberating", { council_id: councilId.trim() });
+}
+/**
+ * Resolve a decision. Evidence is required (≥1 citation): a resolution with no
+ * cited evidence is structurally incomplete and bounced here — the same guard
+ * the sweeper enforces.
+ */
+export function resolveDecision(coordRoot, id, resolution) {
+    if (!resolution.recommendation?.trim()) {
+        return { ok: false, reason: "resolution requires a recommendation" };
+    }
+    const evidence = (resolution.evidence ?? []).map((e) => e.trim()).filter(Boolean);
+    if (evidence.length === 0) {
+        return {
+            ok: false,
+            reason: "resolution requires ≥1 evidence citation (queries run, files read, costs computed) — an evidence-free resolution is bounced",
+        };
+    }
+    if (!resolution.resolved_by?.trim()) {
+        return { ok: false, reason: "resolution requires resolved_by" };
+    }
+    const full = {
+        recommendation: resolution.recommendation.trim(),
+        confidence: resolution.confidence?.trim() || undefined,
+        reversal_cost: resolution.reversal_cost?.trim() || undefined,
+        wrong_if: resolution.wrong_if?.trim() || undefined,
+        revisit_when: resolution.revisit_when?.trim() || undefined,
+        evidence,
+        resolved_by: resolution.resolved_by.trim(),
+        resolved_at: resolution.resolved_at ?? nowIso(),
+    };
+    return transition(coordRoot, id, "resolved", { resolution: full });
+}
+export function enactDecision(coordRoot, id) {
+    return transition(coordRoot, id, "enacted");
+}
+export function reviewDecision(coordRoot, id, opts) {
+    if (!isVerdict(opts.verdict)) {
+        return {
+            ok: false,
+            reason: `invalid verdict "${opts.verdict}" (${REVIEW_VERDICTS.join(" | ")})`,
+        };
+    }
+    const review = {
+        verdict: opts.verdict,
+        note: opts.note?.trim() || undefined,
+        reviewed_at: nowIso(),
+    };
+    return transition(coordRoot, id, "reviewed", { review });
+}
+export function supersedeDecision(coordRoot, id, bySupersedingId) {
+    return transition(coordRoot, id, "superseded", {
+        superseded_by: bySupersedingId?.trim() || null,
+    });
+}
+export function wontfixDecision(coordRoot, id, reason) {
+    return transition(coordRoot, id, "wontfix", { wontfix_reason: reason?.trim() || null });
+}
+/**
+ * Archive a decision (terminal). Records where its output graduated, then moves
+ * manifest + body dir into `archive/`. Idempotent-ish: safe to re-run.
+ */
+export function archiveDecision(coordRoot, id, graduatedTo) {
+    const result = transition(coordRoot, id, "archived", {
+        graduated_to: graduatedTo?.trim() || null,
+    });
+    if (!result.ok)
+        return result;
+    const activeManifest = manifestPath(coordRoot, id);
+    const archivedManifest = archivedManifestPath(coordRoot, id);
+    const activeBody = decisionBodyDir(coordRoot, id);
+    const archivedBody = join(archiveDir(coordRoot), id);
+    mkdirSync(archiveDir(coordRoot), { recursive: true });
+    if (existsSync(activeManifest)) {
+        try {
+            renameSync(activeManifest, archivedManifest);
+        }
+        catch {
+            cpSync(activeManifest, archivedManifest);
+            rmSync(activeManifest, { force: true });
+        }
+    }
+    if (existsSync(activeBody)) {
+        if (existsSync(archivedBody)) {
+            rmSync(activeBody, { recursive: true, force: true });
+        }
+        else {
+            try {
+                renameSync(activeBody, archivedBody);
+            }
+            catch {
+                cpSync(activeBody, archivedBody, { recursive: true });
+                rmSync(activeBody, { recursive: true, force: true });
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Reopen an archived decision back to `reviewed` — the inverse of `archive`,
+ * and the one sanctioned way out of the (otherwise terminal) archived state.
+ * Since `archived` has no legal outgoing transition, this deliberately bypasses
+ * the `transition` guard, the same way `archive` does its file moves outside it.
+ * Moves the manifest + body dir back from `archive/` into the active dir and
+ * clears `graduated_to` (a re-archive sets it fresh). Only `archived` decisions
+ * reopen; `superseded`/`wontfix` stay terminal.
+ *
+ * Ordering is write-active-then-remove-archived so an interrupted call leaves
+ * the decision reopened (active copy wins in `readManifest`) rather than lost.
+ */
+export function reopenDecision(coordRoot, id) {
+    const manifest = readManifest(coordRoot, id);
+    if (!manifest)
+        return { ok: false, reason: `no decision "${id}"` };
+    if (manifest.status !== "archived") {
+        return {
+            ok: false,
+            reason: `only archived decisions can be reopened (this is ${manifest.status})`,
+        };
+    }
+    const archivedBody = join(archiveDir(coordRoot), id);
+    const activeBody = decisionBodyDir(coordRoot, id);
+    if (existsSync(archivedBody)) {
+        if (existsSync(activeBody)) {
+            rmSync(archivedBody, { recursive: true, force: true });
+        }
+        else {
+            try {
+                renameSync(archivedBody, activeBody);
+            }
+            catch {
+                cpSync(archivedBody, activeBody, { recursive: true });
+                rmSync(archivedBody, { recursive: true, force: true });
+            }
+        }
+    }
+    const reopened = {
+        ...manifest,
+        status: "reviewed",
+        graduated_to: null,
+        updated_at: nowIso(),
+    };
+    atomicWriteText(manifestPath(coordRoot, id), `${JSON.stringify(reopened, null, 2)}\n`);
+    const archived = archivedManifestPath(coordRoot, id);
+    if (existsSync(archived))
+        rmSync(archived, { force: true });
+    return { ok: true, manifest: reopened };
+}
+function scanManifests(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const p = join(dir, f);
+        try {
+            if (!statSync(p).isFile())
+                continue;
+            const parsed = JSON.parse(readFileSync(p, "utf8"));
+            if (parsed.schema_version !== DECISION_SCHEMA_VERSION)
+                continue;
+            out.push(parsed);
+        }
+        catch {
+            // skip unparseable manifest; one bad file never kills the scan
+        }
+    }
+    return out;
+}
+export function listDecisions(coordRoot, filter = {}) {
+    let rows = scanManifests(decisionsDir(coordRoot));
+    if (filter.includeArchived)
+        rows = rows.concat(scanManifests(archiveDir(coordRoot)));
+    if (filter.status)
+        rows = rows.filter((d) => d.status === filter.status);
+    if (filter.tier !== undefined)
+        rows = rows.filter((d) => d.tier === filter.tier);
+    if (filter.stakes)
+        rows = rows.filter((d) => d.stakes === filter.stakes);
+    if (filter.openOnly)
+        rows = rows.filter((d) => !isTerminal(d.status));
+    rows.sort((a, b) => (b.filed_at ?? "").localeCompare(a.filed_at ?? ""));
+    return rows;
+}
+export function showDecision(coordRoot, id) {
+    const manifest = readManifest(coordRoot, id);
+    if (!manifest)
+        return null;
+    const archived = !existsSync(manifestPath(coordRoot, id));
+    const bodyDir = archived ? join(archiveDir(coordRoot), id) : decisionBodyDir(coordRoot, id);
+    const bodies = [];
+    if (existsSync(bodyDir)) {
+        for (const f of readdirSync(bodyDir)) {
+            if (!f.endsWith(".md"))
+                continue;
+            try {
+                bodies.push({ name: f, content: readFileSync(join(bodyDir, f), "utf8") });
+            }
+            catch {
+                // skip unreadable body
+            }
+        }
+    }
+    return { manifest, bodies, archived };
+}
+/**
+ * Case-insensitive substring search over manifests + bodies. Deliberately
+ * dumb: precedent recall depends on the host's decision skill running this before
+ * filing, not on ranking sophistication. Includes the archive (precedent
+ * lives there).
+ */
+export function searchDecisions(coordRoot, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const all = listDecisions(coordRoot, { includeArchived: true });
+    const hits = [];
+    for (const manifest of all) {
+        const fields = [
+            { where: "question", text: manifest.question ?? "" },
+            { where: "context", text: manifest.context ?? "" },
+            {
+                where: "resolution",
+                text: manifest.resolution
+                    ? `${manifest.resolution.recommendation} ${manifest.resolution.evidence.join(" ")}`
+                    : "",
+            },
+        ];
+        const bodyDir = existsSync(manifestPath(coordRoot, manifest.decision_id))
+            ? decisionBodyDir(coordRoot, manifest.decision_id)
+            : join(archiveDir(coordRoot), manifest.decision_id);
+        if (existsSync(bodyDir)) {
+            for (const f of readdirSync(bodyDir)) {
+                if (!f.endsWith(".md"))
+                    continue;
+                try {
+                    fields.push({ where: "body", text: readFileSync(join(bodyDir, f), "utf8") });
+                }
+                catch {
+                    // skip
+                }
+            }
+        }
+        for (const field of fields) {
+            const idx = field.text.toLowerCase().indexOf(q);
+            if (idx >= 0) {
+                const start = Math.max(0, idx - 40);
+                const snippet = field.text
+                    .slice(start, idx + q.length + 40)
+                    .replace(/\s+/g, " ")
+                    .trim();
+                hits.push({ manifest, snippet: `${start > 0 ? "…" : ""}${snippet}…`, where: field.where });
+                break;
+            }
+        }
+    }
+    return hits;
+}