@bluewombat/work-ledger 0.1.0

package/dist/ledger/open-work-ledger.js

@@ -0,0 +1,641 @@
+import { checkPlan, initialSubtaskState, refreshRunnable } from "./check-plan.js";
+const DEFAULT_BAIL_DURATION_MS = 3_600_000;
+const ACTIVE_STATES = new Set([
+    "planning",
+    "running",
+    "escalated",
+    "integrating",
+    "submitted",
+    "merging",
+]);
+const IN_FLIGHT = new Set([
+    "planning",
+    "running",
+    "integrating",
+    "submitted",
+]);
+function refused(code) {
+    return { ok: false, code };
+}
+function cloneIntention(feature) {
+    const intention = {
+        key: feature.key,
+        project: feature.project,
+        fingerprint: feature.fingerprint,
+        priority: feature.priority,
+        intention: feature.intention,
+    };
+    if (feature.title !== undefined) {
+        intention.title = feature.title;
+    }
+    if (feature.manager !== undefined) {
+        intention.manager = feature.manager;
+    }
+    if (feature.external_id !== undefined) {
+        intention.external_id = feature.external_id;
+    }
+    if (feature.source !== undefined) {
+        intention.source = { ...feature.source };
+    }
+    return intention;
+}
+function pickReceived(summaries, project) {
+    const candidates = summaries.filter((s) => s.project === project && s.state === "received");
+    candidates.sort((a, b) => {
+        if (b.priority !== a.priority) {
+            return b.priority - a.priority;
+        }
+        return a.received_at - b.received_at;
+    });
+    return candidates[0];
+}
+function projectIsBusy(summaries, project) {
+    return summaries.some((s) => s.project === project && ACTIVE_STATES.has(s.state));
+}
+function unblocksCount(subtaskId, subtasks) {
+    return subtasks.filter((st) => st.depends_on.includes(subtaskId)).length;
+}
+export function openWorkLedger(options) {
+    const persist = options.persist;
+    const now = options.now ?? (() => Date.now());
+    const bailDurationMs = options.bailDurationMs ?? DEFAULT_BAIL_DURATION_MS;
+    const write = async (aggregate) => {
+        const saved = await persist.save(aggregate.intention.key, aggregate);
+        if (!saved.ok) {
+            return refused("persist-failed");
+        }
+        return { ok: true };
+    };
+    const loadOrRefuse = async (key) => {
+        const found = await persist.load(key);
+        if (found === undefined) {
+            return refused("not-found");
+        }
+        return { ok: true, aggregate: structuredClone(found) };
+    };
+    return {
+        async admit(feature) {
+            const existing = await persist.load(feature.key);
+            if (existing === undefined) {
+                const aggregate = {
+                    intention: cloneIntention(feature),
+                    state: "received",
+                    received_at: now(),
+                    attempts: [],
+                    attempts_used: 0,
+                };
+                return await write(aggregate);
+            }
+            if (existing.state === "merging" || existing.state === "done") {
+                return refused("too-late");
+            }
+            if (existing.state === "cancelled") {
+                return refused("illegal-transition");
+            }
+            if (IN_FLIGHT.has(existing.state)) {
+                if (feature.fingerprint === existing.intention.fingerprint ||
+                    feature.fingerprint === existing.pending_fingerprint) {
+                    // Same body as the live intention, or as an edit already recorded:
+                    // an echo of a report, not a newer FeatureStandard.
+                    return { ok: true };
+                }
+                const next = structuredClone(existing);
+                next.pending_fingerprint = feature.fingerprint;
+                return await write(next);
+            }
+            if (existing.state === "received" && existing.intention.fingerprint === feature.fingerprint) {
+                return { ok: true };
+            }
+            if (existing.state === "received" ||
+                existing.state === "invalid" ||
+                existing.state === "escalated") {
+                const next = structuredClone(existing);
+                next.intention = cloneIntention(feature);
+                next.state = "received";
+                delete next.invalid;
+                delete next.pending_fingerprint;
+                return await write(next);
+            }
+            return refused("illegal-transition");
+        },
+        async recordInvalid(input) {
+            const existing = await persist.load(input.key);
+            if (existing !== undefined && (existing.state === "merging" || existing.state === "done")) {
+                return refused("too-late");
+            }
+            if (existing === undefined) {
+                const aggregate = {
+                    intention: {
+                        key: input.key,
+                        project: input.project,
+                        fingerprint: input.fingerprint ?? "",
+                        priority: input.priority ?? 0,
+                        intention: "",
+                    },
+                    state: "invalid",
+                    received_at: now(),
+                    attempts: [],
+                    attempts_used: 0,
+                    invalid: { code: input.code, reason: input.reason },
+                };
+                return await write(aggregate);
+            }
+            const next = structuredClone(existing);
+            next.state = "invalid";
+            next.invalid = { code: input.code, reason: input.reason };
+            if (input.fingerprint !== undefined) {
+                next.intention.fingerprint = input.fingerprint;
+            }
+            if (input.priority !== undefined) {
+                next.intention.priority = input.priority;
+            }
+            next.intention.project = input.project;
+            delete next.bail;
+            return await write(next);
+        },
+        async claim(project) {
+            const summaries = await persist.listSummaries();
+            if (projectIsBusy(summaries, project)) {
+                return refused("project-busy");
+            }
+            const picked = pickReceived(summaries, project);
+            if (picked === undefined) {
+                return { ok: true, empty: true };
+            }
+            const loaded = await persist.load(picked.key);
+            if (loaded === undefined || loaded.state !== "received") {
+                return { ok: true, empty: true };
+            }
+            const next = structuredClone(loaded);
+            next.state = "planning";
+            next.bail = { expires_at: now() + bailDurationMs };
+            const saved = await write(next);
+            if (!saved.ok) {
+                return saved;
+            }
+            return { ok: true, key: picked.key };
+        },
+        async recordPlan(input) {
+            const current = await loadOrRefuse(input.key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.state !== "planning") {
+                return refused("illegal-transition");
+            }
+            if (aggregate.plan !== undefined) {
+                return refused("plan-frozen");
+            }
+            const checked = checkPlan(input.subtasks);
+            if (!checked.ok) {
+                return refused("illegal-transition");
+            }
+            aggregate.plan = {
+                planned_at: input.plannedAt,
+                subtasks: checked.subtasks.map((draft) => ({
+                    ...draft,
+                    state: initialSubtaskState(draft),
+                })),
+            };
+            aggregate.state = "running";
+            aggregate.bail = { expires_at: now() + bailDurationMs };
+            return await write(aggregate);
+        },
+        async refusePlan(input) {
+            const current = await loadOrRefuse(input.key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.state !== "planning") {
+                return refused("illegal-transition");
+            }
+            aggregate.state = "escalated";
+            aggregate.escalation = { kind: "plan", born_in_merging: false };
+            aggregate.invalid = { code: input.code, reason: input.reason };
+            delete aggregate.bail;
+            return await write(aggregate);
+        },
+        async startSubtask(input) {
+            const current = await loadOrRefuse(input.key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.plan === undefined) {
+                return refused("plan-not-frozen");
+            }
+            if (aggregate.state !== "running") {
+                return refused("illegal-transition");
+            }
+            if (aggregate.plan.subtasks.some((st) => st.state === "running")) {
+                return refused("another-running");
+            }
+            const subtask = aggregate.plan.subtasks.find((st) => st.id === input.subtaskId);
+            if (subtask === undefined) {
+                return refused("not-found");
+            }
+            if (subtask.state !== "runnable") {
+                return refused("subtask-not-runnable");
+            }
+            subtask.state = "running";
+            aggregate.bail = { expires_at: now() + bailDurationMs };
+            return await write(aggregate);
+        },
+        async recordAttempt(input) {
+            const current = await loadOrRefuse(input.key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.plan === undefined) {
+                return refused("plan-not-frozen");
+            }
+            const subtask = aggregate.plan.subtasks.find((st) => st.id === input.subtaskId);
+            if (subtask === undefined || subtask.state !== "running") {
+                return refused("illegal-transition");
+            }
+            const existing = aggregate.attempts.filter((a) => a.subtask_id === input.subtaskId);
+            const nextNumber = existing.length + 1;
+            if (input.number !== nextNumber) {
+                return refused("illegal-transition");
+            }
+            const attempt = {
+                subtask_id: input.subtaskId,
+                number: input.number,
+                round: aggregate.resumes ?? 0,
+            };
+            if (input.trace !== undefined) {
+                attempt.trace = input.trace;
+            }
+            aggregate.attempts.push(attempt);
+            aggregate.attempts_used += 1;
+            return await write(aggregate);
+        },
+        async markSubtaskIntegrated(input) {
+            const current = await loadOrRefuse(input.key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.state !== "running" || aggregate.plan === undefined) {
+                return refused("illegal-transition");
+            }
+            const subtask = aggregate.plan.subtasks.find((st) => st.id === input.subtaskId);
+            if (subtask === undefined || subtask.state !== "running") {
+                return refused("illegal-transition");
+            }
+            subtask.state = "integrated";
+            aggregate.plan.subtasks = refreshRunnable(aggregate.plan.subtasks);
+            const terminal = new Set(["integrated", "cancelled"]);
+            const remaining = aggregate.plan.subtasks.some((st) => !terminal.has(st.state));
+            if (!remaining) {
+                aggregate.state = "integrating";
+            }
+            aggregate.bail = { expires_at: now() + bailDurationMs };
+            return await write(aggregate);
+        },
+        /**
+         * The assembled feature is now in front of the Authority.
+         *
+         * A second call on an already submitted feature keeps the first reference:
+         * the work was pushed again to the same place, and the Authority is judging
+         * the same Submission.
+         */
+        async markSubmitted(input) {
+            const current = await loadOrRefuse(input.key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.state !== "integrating" && aggregate.state !== "submitted") {
+                return refused("illegal-transition");
+            }
+            aggregate.state = "submitted";
+            // Rebuilt field by field, so anything added here has to be carried on
+            // purpose. What was already sent back is carried: a Submission offered
+            // again is the same Submission, and dropping the reason leaves whoever
+            // reads the next escalation with a frozen Feature and no cause.
+            const previous = aggregate.submission;
+            aggregate.submission = {
+                reference: previous?.reference ?? input.reference,
+                submitted_at: previous?.submitted_at ?? now(),
+                refusals: previous?.refusals ?? 0,
+                ...(previous?.last_report === undefined ? {} : { last_report: previous.last_report }),
+                ...(previous?.last_refused_by === undefined
+                    ? {}
+                    : { last_refused_by: previous.last_refused_by }),
+            };
+            aggregate.bail = { expires_at: now() + bailDurationMs };
+            return await write(aggregate);
+        },
+        /**
+         * The Authority sent the work back. The report is kept for the next Attempt
+         * and the feature returns to integrating, which is where the work is made.
+         */
+        async recordRefusal(input) {
+            const current = await loadOrRefuse(input.key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.state !== "submitted" || aggregate.submission === undefined) {
+                return refused("illegal-transition");
+            }
+            aggregate.submission = {
+                ...aggregate.submission,
+                refusals: aggregate.submission.refusals + 1,
+                last_report: input.report,
+                ...(input.refusedBy === undefined ? {} : { last_refused_by: input.refusedBy }),
+            };
+            aggregate.state = "integrating";
+            aggregate.bail = { expires_at: now() + bailDurationMs };
+            return await write(aggregate);
+        },
+        async markMerging(key) {
+            const current = await loadOrRefuse(key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.state !== "integrating" && aggregate.state !== "submitted") {
+                return refused("illegal-transition");
+            }
+            aggregate.state = "merging";
+            aggregate.bail = { expires_at: now() + bailDurationMs };
+            return await write(aggregate);
+        },
+        async markDone(key, input) {
+            const current = await loadOrRefuse(key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.state !== "merging") {
+                return refused("illegal-transition");
+            }
+            aggregate.state = "done";
+            if (input?.reference !== undefined) {
+                aggregate.integration_reference = input.reference;
+            }
+            delete aggregate.bail;
+            if (aggregate.workspaces !== undefined) {
+                delete aggregate.workspaces.subtask;
+                if (aggregate.workspaces.feature === undefined) {
+                    delete aggregate.workspaces;
+                }
+            }
+            return await write(aggregate);
+        },
+        async escalate(input) {
+            const current = await loadOrRefuse(input.key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.state === "done" || aggregate.state === "cancelled") {
+                return refused("illegal-transition");
+            }
+            if (input.kind === "subtask" && input.subtaskId !== undefined) {
+                const attempts = aggregate.attempts.filter((a) => a.subtask_id === input.subtaskId);
+                if (attempts.length > 0) {
+                    const last = attempts[attempts.length - 1];
+                    if (last?.trace === undefined) {
+                        return refused("missing-trace");
+                    }
+                }
+            }
+            const bornInMerging = aggregate.state === "merging" || input.kind === "merging";
+            aggregate.state = "escalated";
+            const escalation = {
+                kind: input.kind,
+                born_in_merging: bornInMerging,
+            };
+            if (input.subtaskId !== undefined) {
+                escalation.subtask_id = input.subtaskId;
+            }
+            if (input.report !== undefined && input.report.trim().length > 0) {
+                escalation.report = input.report;
+            }
+            aggregate.escalation = escalation;
+            // Freezing for a human consumes the in-flight update signal. Resume
+            // continues the stored intention; a newer FeatureStandard lands by admit.
+            delete aggregate.pending_fingerprint;
+            if (aggregate.plan !== undefined && input.subtaskId !== undefined) {
+                const subtask = aggregate.plan.subtasks.find((st) => st.id === input.subtaskId);
+                if (subtask !== undefined && subtask.state === "running") {
+                    subtask.state = "escalated";
+                }
+            }
+            delete aggregate.bail;
+            return await write(aggregate);
+        },
+        async resumeReady(key) {
+            const current = await loadOrRefuse(key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.state === "invalid") {
+                return refused("illegal-transition");
+            }
+            if (aggregate.state !== "escalated" || aggregate.escalation === undefined) {
+                return refused("illegal-transition");
+            }
+            const { kind, subtask_id } = aggregate.escalation;
+            aggregate.resumes = (aggregate.resumes ?? 0) + 1;
+            if (kind === "plan") {
+                delete aggregate.plan;
+                aggregate.state = "planning";
+                delete aggregate.invalid;
+                delete aggregate.escalation;
+                aggregate.bail = { expires_at: now() + bailDurationMs };
+                return await write(aggregate);
+            }
+            if (kind === "merging" || kind === "submitted" || kind === "assembly") {
+                aggregate.state = "integrating";
+                delete aggregate.escalation;
+                aggregate.bail = { expires_at: now() + bailDurationMs };
+                return await write(aggregate);
+            }
+            if (kind === "subtask" && subtask_id !== undefined && aggregate.plan !== undefined) {
+                const subtask = aggregate.plan.subtasks.find((st) => st.id === subtask_id);
+                if (subtask !== undefined) {
+                    subtask.state = "runnable";
+                }
+                aggregate.state = "running";
+                delete aggregate.escalation;
+                aggregate.bail = { expires_at: now() + bailDurationMs };
+                return await write(aggregate);
+            }
+            return refused("illegal-transition");
+        },
+        async cancel(key) {
+            const current = await loadOrRefuse(key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.state === "merging" || aggregate.state === "done") {
+                return refused("point-of-no-return");
+            }
+            if (aggregate.escalation?.born_in_merging === true) {
+                return refused("point-of-no-return");
+            }
+            if (aggregate.state === "cancelled") {
+                return { ok: true };
+            }
+            aggregate.state = "cancelled";
+            if (aggregate.plan !== undefined) {
+                aggregate.plan.subtasks = aggregate.plan.subtasks.map((st) => st.state === "integrated" ? st : { ...st, state: "cancelled" });
+            }
+            delete aggregate.bail;
+            return await write(aggregate);
+        },
+        async declareWorkspace(input) {
+            const current = await loadOrRefuse(input.key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.state === "done" || aggregate.state === "cancelled") {
+                return refused("illegal-transition");
+            }
+            const workspaces = { ...aggregate.workspaces };
+            if (input.feature !== undefined) {
+                workspaces.feature = input.feature;
+            }
+            if (input.subtask !== undefined) {
+                workspaces.subtask = input.subtask;
+            }
+            aggregate.workspaces = workspaces;
+            return await write(aggregate);
+        },
+        async clearWorkspace(input) {
+            const current = await loadOrRefuse(input.key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.workspaces === undefined) {
+                return { ok: true };
+            }
+            if (input.feature === true) {
+                delete aggregate.workspaces.feature;
+            }
+            if (input.subtask === true) {
+                delete aggregate.workspaces.subtask;
+            }
+            if (aggregate.workspaces.feature === undefined &&
+                aggregate.workspaces.subtask === undefined) {
+                delete aggregate.workspaces;
+            }
+            return await write(aggregate);
+        },
+        async expireBail(key) {
+            const current = await loadOrRefuse(key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.bail === undefined || now() < aggregate.bail.expires_at) {
+                return refused("illegal-transition");
+            }
+            if (aggregate.state === "planning") {
+                aggregate.state = "received";
+                delete aggregate.bail;
+                return await write(aggregate);
+            }
+            if (aggregate.state === "running" && aggregate.plan !== undefined) {
+                const running = aggregate.plan.subtasks.find((st) => st.state === "running");
+                if (running !== undefined) {
+                    running.state = "runnable";
+                    aggregate.attempts_used += 1;
+                }
+                if (aggregate.workspaces !== undefined) {
+                    delete aggregate.workspaces.subtask;
+                    if (aggregate.workspaces.feature === undefined) {
+                        delete aggregate.workspaces;
+                    }
+                }
+                delete aggregate.bail;
+                return await write(aggregate);
+            }
+            delete aggregate.bail;
+            return await write(aggregate);
+        },
+        async renewBail(key) {
+            const current = await loadOrRefuse(key);
+            if (!current.ok) {
+                return current;
+            }
+            const { aggregate } = current;
+            if (aggregate.bail === undefined) {
+                return refused("illegal-transition");
+            }
+            aggregate.bail = { expires_at: now() + bailDurationMs };
+            return await write(aggregate);
+        },
+        async get(key) {
+            const found = await persist.load(key);
+            if (found === undefined) {
+                return { ok: false, code: "not-found" };
+            }
+            return { ok: true, aggregate: found };
+        },
+        async list() {
+            return await persist.listSummaries();
+        },
+        async listInFlight() {
+            const summaries = await persist.listSummaries();
+            return summaries.filter((summary) => IN_FLIGHT.has(summary.state));
+        },
+        async activeOn(project) {
+            const summaries = await persist.listSummaries();
+            return summaries.find((s) => s.project === project && ACTIVE_STATES.has(s.state));
+        },
+        async nextReceived(project) {
+            const summaries = await persist.listSummaries();
+            if (projectIsBusy(summaries, project)) {
+                return undefined;
+            }
+            return pickReceived(summaries, project);
+        },
+        async nextRunnable(key) {
+            const found = await persist.load(key);
+            if (found?.plan === undefined) {
+                return undefined;
+            }
+            const runnable = found.plan.subtasks.filter((st) => st.state === "runnable");
+            if (runnable.length === 0) {
+                return undefined;
+            }
+            runnable.sort((a, b) => unblocksCount(b.id, found.plan?.subtasks ?? []) -
+                unblocksCount(a.id, found.plan?.subtasks ?? []));
+            return runnable[0]?.id;
+        },
+        async listDeclaredWorkspaces() {
+            const summaries = await persist.listSummaries();
+            const listed = [];
+            for (const summary of summaries) {
+                const aggregate = await persist.load(summary.key);
+                if (aggregate?.workspaces === undefined) {
+                    continue;
+                }
+                const row = { key: summary.key };
+                if (aggregate.workspaces.feature !== undefined) {
+                    row.feature = aggregate.workspaces.feature;
+                }
+                if (aggregate.workspaces.subtask !== undefined) {
+                    row.subtask = aggregate.workspaces.subtask;
+                }
+                if (row.feature !== undefined || row.subtask !== undefined) {
+                    listed.push(row);
+                }
+            }
+            return listed;
+        },
+    };
+}
+//# sourceMappingURL=open-work-ledger.js.map