cloving 1.3.0 → 1.5.0

package/dist/src/report.js

@@ -1,11 +1,11 @@
+import { reportQualityMetrics, } from "./report-quality.js";
 import { reportMetric, outsideReportBand, } from "./report-statistics.js";
-export const reportOutcomes = [
-    "completed",
-    "partial",
-    "blocked",
-    "failed",
-    "cancelled",
-];
+import { reportOperatorMetrics } from "./report-operator.js";
+import { reportCiMetrics } from "./report-ci.js";
+import { reportEffectData } from "./report-effects.js";
+import { reportFlowMetrics } from "./report-flow.js";
+import { reportOutcomes } from "./report-flow-types.js";
+export { reportOutcomes, } from "./report-flow-types.js";
 function outcomeMetrics(input, window) {
     return Object.fromEntries(reportOutcomes.map((outcome) => {
         const data = input.completions === null
@@ -23,9 +23,80 @@ function outcomeMetrics(input, window) {
         ];
     }));
 }
+function effectMetrics(input, window) {
+    const data = reportEffectData(input.effects ?? null);
+    const metrics = {
+        "fixRounds.medianPerMergedPullRequest": reportMetric({
+            data: data.fixRounds,
+            window,
+            aggregation: "median",
+        }),
+    };
+    for (const phase of ["workerTurn", "codeReview", "merge"])
+        metrics[`phases.${phase}.medianMinutes`] = reportMetric({
+            data: data[phase],
+            window,
+            aggregation: "median",
+        });
+    return metrics;
+}
+function githubMetrics(input, window) {
+    const observed = githubWindow(input, window);
+    return {
+        "leadTime.medianHours": reportMetric({
+            data: input.github?.leadTimes ?? null,
+            window: observed,
+            aggregation: "median",
+        }),
+        "tickets.completed": reportMetric({
+            data: input.github?.issues ?? null,
+            window: observed,
+            aggregation: "count",
+        }),
+        "pullRequests.merged": reportMetric({
+            data: input.github?.pulls ?? null,
+            window: observed,
+            aggregation: "count",
+        }),
+    };
+}
+function githubWindow(input, window) {
+    return { ...window, observedSince: input.github?.observedSince ?? null };
+}
+function ticketCostMetric(input, window) {
+    const costs = reportRunCosts((input.completions ?? []).filter((event) => event.at < window.end), input.costs ?? []);
+    const tickets = completedCosts((input.github?.issues ?? []).filter((issue) => issue.at < window.end), costs);
+    const metric = reportMetric({
+        data: input.completions === null || input.github?.issues == null
+            ? null
+            : tickets.map((ticket) => ({
+                at: ticket.closedAt,
+                value: ticket.costUsd,
+                evidence: ticket.evidence,
+            })),
+        window: {
+            ...window,
+            observedSince: commonHistory(window.observedSince, input.github?.observedSince ?? null),
+        },
+        aggregation: "median",
+    });
+    const completedTicketCosts = tickets
+        .filter((ticket) => ticket.closedAt >= window.start && ticket.closedAt < window.end)
+        .map((ticket) => ({
+        ...ticket,
+        ...costHistory(ticket.costUsd, metric.baseline),
+    }));
+    return { metric, completedTicketCosts };
+}
+function costHistory(cost, baseline) {
+    return {
+        baseline,
+        ...(outsideReportBand(cost, baseline.band) ? { mark: "outside" } : {}),
+    };
+}
 function metricCollection(input, window) {
     const costs = reportRunCosts(input.completions ?? [], input.costs ?? []);
-    const metrics = outcomeMetrics(input, window);
+    const tickets = ticketCostMetric(input, window);
     const costMetric = reportMetric({
         data: input.completions === null
             ? null
@@ -37,43 +108,59 @@ function metricCollection(input, window) {
         window,
         aggregation: "median",
     });
-    metrics["cost.medianRunUsd"] = costMetric;
-    const githubWindow = {
-        ...window,
-        observedSince: input.github?.observedSince ?? null,
+    const metrics = {
+        ...outcomeMetrics(input, window),
+        ...reportFlowMetrics({
+            flow: input.flow,
+            completions: input.completions,
+            ready: {
+                tickets: input.github?.ready ?? null,
+                observedSince: input.github?.observedSince ?? null,
+            },
+        }, window),
+        ...effectMetrics(input, window),
+        ...githubMetrics(input, window),
+        "cost.medianRunUsd": costMetric,
+        "cost.medianCompletedTicketUsd": tickets.metric,
     };
-    metrics["tickets.completed"] = reportMetric({
-        data: input.github?.issues ?? null,
-        window: githubWindow,
-        aggregation: "count",
-    });
-    metrics["pullRequests.merged"] = reportMetric({
-        data: input.github?.pulls ?? null,
-        window: githubWindow,
-        aggregation: "count",
-    });
     const runCosts = costs
         .filter((cost) => cost.completedAt >= window.start && cost.completedAt < window.end)
         .map((cost) => ({
         ...cost,
-        baseline: costMetric.baseline,
-        ...(outsideReportBand(cost.costUsd, costMetric.baseline.band)
-            ? { mark: "outside" }
-            : {}),
+        ...costHistory(cost.costUsd, costMetric.baseline),
     }));
-    return { metrics, runCosts };
+    return {
+        metrics,
+        runCosts,
+        completedTicketCosts: tickets.completedTicketCosts,
+    };
+}
+function operatorMetrics(input, window) {
+    return reportOperatorMetrics({
+        effects: input.effects ?? null,
+        pulls: input.github?.pulls ?? null,
+        labels: input.github?.labels ?? null,
+    }, {
+        ...window,
+        observedSince: commonHistory(window.observedSince, input.github?.observedSince ?? null),
+    });
 }
 export function loopReport(input) {
     const end = input.now;
     const start = end - input.since * 3_600_000;
     const window = { start, end, observedSince: input.observedSince ?? null };
-    const unavailable = { status: "unavailable", reason: "not-implemented" };
     return {
         schemaVersion: 1,
         kind: "loop-report",
         window: { start, end, hours: input.since },
         semantics: {
-            tickets: "currently-closed-completed",
+            tickets: "closed-completed-in-window",
+            flowLanes: "current-queue-workflow-and-lane-setting",
+            flowTickets: "ready-label-intervals-and-current-ticket-body-dependency-close-times",
+            flowIdle: "elapsed-hours-with-spare-capacity-and-at-least-one-eligible-ticket",
+            flowWait: "sum-of-ticket-hours-by-dependency-or-full-lanes",
+            flowStreak: "terminal-time-then-sequence;current-carries-history;longest-counts-window-ends",
+            operatorLabels: "time-match-within-2-minutes-for-same-issue",
             costs: "lifetime-turn-cost-attributed-at-run-end",
         },
         ...metricCollection(input, window),
@@ -87,28 +174,31 @@ export function loopReport(input) {
                 history: { status: "unavailable" },
             },
         },
-        coverage: {
-            ci: unavailable,
-            flow: unavailable,
-            quality: unavailable,
-            operator: unavailable,
-            phases: unavailable,
-            fixRounds: unavailable,
-            leadTime: unavailable,
-            ticketClosureHistory: unavailable,
-            completedTicketCosts: unavailable,
-        },
+        quality: reportQualityMetrics({
+            ...input.github,
+            effects: input.effects ?? null,
+            daemonObservedSince: input.observedSince ?? null,
+        }, githubWindow(input, window)),
+        ci: reportCiMetrics(input.github?.ciUsage ?? undefined, githubWindow(input, window)),
+        operator: operatorMetrics(input, window),
+        coverage: {},
     };
 }
 export function reportRunCosts(completions, costs) {
+    const byRun = new Map();
+    for (const cost of costs)
+        if (!byRun.has(cost.runId))
+            byRun.set(cost.runId, cost);
     return completions.map((event) => {
-        const turns = costs.find((cost) => cost.runId === event.runId)?.turns ?? null;
+        const cost = byRun.get(event.runId);
+        const turns = cost?.turns ?? null;
         const known = turns !== null && turns.every((turn) => turn.costUsd !== null);
         const total = known
             ? turns.reduce((sum, turn) => sum + (turn.costUsd ?? 0), 0)
             : null;
         return {
             runId: event.runId,
+            ticketId: cost?.ticketId,
             outcome: event.outcome,
             completedAt: event.at,
             costUsd: total !== null && Number.isFinite(total) ? total : null,
@@ -117,3 +207,28 @@ export function reportRunCosts(completions, costs) {
         };
     });
 }
+function commonHistory(daemon, github) {
+    return daemon === null || github === null ? null : Math.max(daemon, github);
+}
+function completedCosts(completed, costs) {
+    const issues = new Map(completed
+        .toSorted((left, right) => left.at - right.at)
+        .map((issue) => [issue.evidence["issue"], issue]));
+    return [...issues.values()].map((issue) => {
+        const number = issue.evidence["issue"];
+        const runs = costs.filter((cost) => cost.ticketId === String(number));
+        const unknown = costs.some((cost) => cost.ticketId === undefined) ||
+            runs.length === 0 ||
+            runs.some((run) => run.costUsd === null);
+        const total = unknown
+            ? null
+            : runs.reduce((sum, run) => sum + (run.costUsd ?? 0), 0);
+        return {
+            issue: number,
+            closedAt: issue.at,
+            costUsd: total !== null && Number.isFinite(total) ? total : null,
+            runs,
+            evidence: { issue: number, runIds: runs.map((run) => run.runId) },
+        };
+    });
+}

package/dist/src/schedule-progress.d.ts

@@ -0,0 +1,33 @@
+import { type Fields, type Reply } from "./protocol.ts";
+export type SchedulePort = (parameters: Fields) => Promise<Reply>;
+export type PendingSlot = {
+    readonly kind: "run";
+    readonly input: Fields;
+} | {
+    readonly kind: "skip";
+    readonly runId: string;
+};
+export interface ScheduleStop {
+    readonly stoppedAt: number;
+    readonly stoppedSlot: number;
+    readonly failedRunIds: readonly string[];
+}
+export interface ScheduleProgress {
+    readonly everySeconds: number;
+    readonly nextAt: number;
+    readonly lastSlot: number;
+    readonly state: "active" | "paused" | "stopped";
+    readonly failuresInRow: number;
+    readonly failedRunIds: readonly string[];
+    readonly stoppedAt?: number;
+    readonly stoppedSlot?: number;
+    readonly stops?: readonly ScheduleStop[];
+    readonly activeCommandId?: string;
+    readonly pending?: PendingSlot;
+}
+export declare function scheduleStops(progress: ScheduleProgress): readonly ScheduleStop[];
+export declare function finishedScheduleRun(progress: ScheduleProgress, run: {
+    readonly runId: string;
+    readonly status: Fields;
+    readonly now: number;
+}): ScheduleProgress;

package/dist/src/schedule-progress.js

@@ -0,0 +1,45 @@
+import { record } from "./protocol.js";
+export function scheduleStops(progress) {
+    if (progress.stops !== undefined)
+        return progress.stops;
+    if (progress.state !== "stopped" ||
+        progress.stoppedAt === undefined ||
+        progress.stoppedSlot === undefined)
+        return [];
+    return [
+        {
+            stoppedAt: progress.stoppedAt,
+            stoppedSlot: progress.stoppedSlot,
+            failedRunIds: progress.failedRunIds,
+        },
+    ];
+}
+export function finishedScheduleRun(progress, run) {
+    const rest = { ...progress };
+    delete rest.activeCommandId;
+    const state = run.status["state"];
+    if (state === "cancelled")
+        return rest;
+    const failed = state === "failed" || record(run.status["outcome"])?.["kind"] === "blocked";
+    if (!failed)
+        return { ...rest, failuresInRow: 0, failedRunIds: [] };
+    const failedRunIds = [...progress.failedRunIds, run.runId];
+    const failuresInRow = failedRunIds.length;
+    const stop = {
+        stoppedAt: run.now,
+        stoppedSlot: progress.lastSlot,
+        failedRunIds,
+    };
+    return {
+        ...rest,
+        failedRunIds,
+        failuresInRow,
+        ...(failuresInRow < 3
+            ? {}
+            : {
+                state: "stopped",
+                ...stop,
+                stops: [...scheduleStops(progress), stop],
+            }),
+    };
+}

package/dist/src/service/active-tickets.js

@@ -1,17 +1,16 @@
 import { record } from "../protocol.js";
+import { queueStateFields } from "../queue-state.js";
+import { queueRun, queueSpend } from "./queue-spend.js";
 export async function activeWorkflow(context, workflowId) {
     const workflows = await context.authority.queries.workflowIds();
     const state = await context.authority.state();
-    const queueRun = async (runId) => workflows[runId] === "develop-issue" ||
-        (await context.authority.queries.manifest(runId))?.queue === true;
     const runs = Object.values(state.runs).filter((run) => !["completed", "failed", "cancelled"].includes(run.status));
     const own = runs.filter((run) => workflows[run.runId] === workflowId);
-    const queued = workflowId === "develop-issue" ||
-        context.registry.byId(workflowId)?.queue === true ||
-        (await Promise.all(own.map((run) => queueRun(run.runId)))).includes(true);
+    const queued = context.registry.byId(workflowId)?.queue === true ||
+        (await Promise.all(own.map((run) => queueRun(context, run.runId)))).includes(true);
     const active = await Promise.all(runs.map(async (run) => {
         if (workflows[run.runId] !== workflowId &&
-            !(queued && (await queueRun(run.runId))))
+            !(queued && (await queueRun(context, run.runId))))
             return undefined;
         return storedTicket(context, state.details[run.runId]?.input);
     }));
@@ -24,8 +23,11 @@ export async function queueOverview(context) {
     if (workflow?.admission === undefined)
         return {};
     const active = await activeWorkflow(context, workflow.workflowId);
+    const control = context.queue?.control();
     return {
         queue: {
+            workflowId: workflow.workflowId,
+            ...(await queueSpend(context)),
             lanes: workflow.admission === "when-idle" ? 1 : workflow.admission,
             busy: active.length,
             skipped: [
@@ -34,6 +36,9 @@ export async function queueOverview(context) {
                     : []),
                 ...(workflow.resolver.skippedTickets?.() ?? []),
             ],
+            ...(control === undefined
+                ? {}
+                : queueStateFields(control, active.length)),
         },
     };
 }

package/dist/src/service/command-waits.d.ts

@@ -0,0 +1,34 @@
+import { type CommandWaitView } from "../authority/command-wait-view.ts";
+import { type CommandWaitState, type CommandWaitsState } from "../authority/command-waits.ts";
+import type { Authority, StoreReceipt } from "../broker/actor/authority.ts";
+import type { Gateway } from "./gateway.ts";
+export declare function expireCommandWaits(parts: {
+    readonly waits: CommandWaitsState;
+    readonly gateway: Gateway;
+    readonly now: string;
+}): Promise<void>;
+interface WaitName {
+    readonly runId: string;
+    readonly name: string;
+}
+interface WaitCall extends WaitName {
+    readonly commandId: string;
+}
+export interface CommandWaitPort {
+    readonly open: (wait: WaitCall & {
+        readonly input: string;
+    }) => Promise<StoreReceipt>;
+    readonly check: (wait: WaitCall) => Promise<StoreReceipt>;
+    readonly read: (wait: WaitName) => Promise<CommandWaitState | undefined>;
+}
+export declare function commandWaitPort(parts: {
+    readonly authority: Authority;
+    readonly gateway: Gateway;
+}): CommandWaitPort;
+export declare function commandWaitDisplay(input: {
+    readonly authority: Authority;
+    readonly runId: string;
+    readonly waits: CommandWaitsState | undefined;
+    readonly now: string;
+}): Promise<readonly CommandWaitView[]>;
+export {};

package/dist/src/service/command-waits.js

@@ -0,0 +1,86 @@
+import { commandWaitViews, } from "../authority/command-wait-view.js";
+import { commandWaitKey, } from "../authority/command-waits.js";
+import { documentDigest } from "../broker/decision-restore.js";
+import { effectInputDigest } from "../broker/effect-restore.js";
+import { operationDigest } from "../broker/operation-digest.js";
+export async function expireCommandWaits(parts) {
+    for (const wait of Object.values(parts.waits)) {
+        if (wait.state !== "waiting" || Date.parse(parts.now) < wait.deadline)
+            continue;
+        await parts.gateway.execute({
+            principal: "controller",
+            command: {
+                kind: "expire-command-wait",
+                commandId: `expire-wait:${operationDigest(commandWaitKey(wait.runId, wait.name))}`,
+                runId: wait.runId,
+                waitName: wait.name,
+            },
+        });
+    }
+}
+export function commandWaitPort(parts) {
+    const { authority, gateway } = parts;
+    const read = async (wait) => (await authority.state()).commandWaits?.[commandWaitKey(wait.runId, wait.name)];
+    return {
+        read,
+        open: async (wait) => {
+            const declarations = (await authority.queries.manifest(wait.runId))?.commandWaits ?? {};
+            const permission = Object.hasOwn(declarations, wait.name)
+                ? declarations[wait.name]
+                : undefined;
+            if (permission === undefined)
+                return { kind: "rejected", reason: "command-wait-not-declared" };
+            return gateway.execute({
+                principal: "worker",
+                command: {
+                    kind: "open-command-wait",
+                    runId: wait.runId,
+                    commandId: wait.commandId,
+                    waitName: wait.name,
+                    target: permission.command,
+                    maximumWaitSeconds: permission.maximumWaitSeconds,
+                    pollEverySeconds: permission.pollEverySeconds,
+                    payload: documentDigest(wait.input),
+                },
+                documents: [wait.input],
+            });
+        },
+        check: async (call) => {
+            const wait = await read(call);
+            if (wait === undefined)
+                return { kind: "rejected", reason: "unknown-command-wait" };
+            return gateway.execute({
+                principal: "worker",
+                command: {
+                    kind: "check-command-wait",
+                    runId: call.runId,
+                    commandId: call.commandId,
+                    waitName: call.name,
+                    inputDigest: effectInputDigest({
+                        capability: "command",
+                        method: `run:${wait.command}`,
+                        target: wait.command,
+                        payload: wait.inputDigest,
+                    }),
+                },
+            });
+        },
+    };
+}
+function displayTime(time) {
+    return time === null ? null : new Date(time).toISOString();
+}
+export async function commandWaitDisplay(input) {
+    const manifest = await input.authority.queries.manifest(input.runId);
+    return commandWaitViews({
+        ...input,
+        declarations: manifest?.commandWaits ?? {},
+        waits: input.waits ?? {},
+        now: Date.parse(input.now),
+    }).map((wait) => ({
+        ...wait,
+        startedAt: displayTime(wait.startedAt),
+        deadline: displayTime(wait.deadline),
+        nextCheckAt: displayTime(wait.nextCheckAt),
+    }));
+}

package/dist/src/service/dispatcher.d.ts

@@ -0,0 +1,4 @@
+import type { Reply, ServiceRequest } from "../protocol.ts";
+import { type Connection } from "./event-handler.ts";
+import { type ServiceContext } from "./replies.ts";
+export declare function dispatcher(context: ServiceContext): (request: ServiceRequest, connection: Connection) => Promise<Reply | undefined>;

package/dist/src/service/dispatcher.js

@@ -0,0 +1,33 @@
+import { decision, questions } from "./decision-handler.js";
+import { events } from "./event-handler.js";
+import { queueCommand, queueRead } from "./queue-handlers.js";
+import { failed, scheduleRequest } from "./replies.js";
+import { runCommand, status } from "./run-handlers.js";
+import { submissionHandler } from "./submission-handler.js";
+import { reloadUnavailable } from "./workflow-reload.js";
+export function dispatcher(context) {
+    const run = submissionHandler(context);
+    const operations = new Map([
+        ["run", (request) => run(request.parameters)],
+        ["schedule", (request) => scheduleRequest(context, request.parameters)],
+        ["queue", () => queueRead(context)],
+        ["queue-command", (request) => queueCommand(context, request.parameters)],
+        ["status", (request) => status(context, request.parameters)],
+        ["questions", (request) => questions(context, request.parameters)],
+        ["decision", (request) => decision(context, request.parameters)],
+        ["run-command", (request) => runCommand(context, request.parameters)],
+        ["reload", () => context.reload?.() ?? reloadUnavailable()],
+        [
+            "events",
+            (request, connection) => events(context, { parameters: request.parameters, connection }),
+        ],
+    ]);
+    return (request, connection) => {
+        const operation = operations.get(request.operation);
+        if (operation === undefined)
+            return Promise.resolve(failed("unknown-operation", {
+                detail: `The service has no operation ${request.operation}.`,
+            }));
+        return operation(request, connection);
+    };
+}

package/dist/src/service/expiry.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { notBefore } from "../authority/instants.js";
 import { operationDigest } from "../broker/operation-digest.js";
+import { expireCommandWaits } from "./command-waits.js";
 function expiryIdentity(runId, gateId) {
     return `expire:${createHash("sha256").update(`${runId} ${gateId}`).digest("hex").slice(0, 32)}`;
 }
@@ -9,6 +10,7 @@ async function scanned(parts) {
     const { authority, gateway, clock } = parts;
     const state = await authority.state();
     const now = clock();
+    await expireCommandWaits({ waits: state.commandWaits ?? {}, gateway, now });
     const due = Object.values(state.gates).filter((gate) => gate.outcome === null &&
         gate.expiresAt !== null &&
         notBefore(now, gate.expiresAt) &&

package/dist/src/service/gateway.js

@@ -11,6 +11,8 @@ const permitted = {
         "cancel-run",
     ],
     worker: [
+        "open-command-wait",
+        "check-command-wait",
         "record-schedule-skip",
         "mark-started",
         "open-gate",
@@ -21,7 +23,7 @@ const permitted = {
         "request-effect",
         "report-effect",
     ],
-    controller: ["expire-gate", "expire-lease"],
+    controller: ["expire-gate", "expire-lease", "expire-command-wait"],
 };
 const pinned = ["decide-gate", "resume-run"];
 function denied(principal, subject) {

package/dist/src/service/queue-handlers.d.ts

@@ -0,0 +1,4 @@
+import type { Fields, Reply } from "../protocol.ts";
+import { type ServiceContext } from "./replies.ts";
+export declare function queueRead(context: ServiceContext): Promise<Reply>;
+export declare function queueCommand(context: ServiceContext, parameters: Fields): Promise<Reply>;

package/dist/src/service/queue-handlers.js

@@ -0,0 +1,32 @@
+import { queueOverview } from "./active-tickets.js";
+import { failed, invalidRequest, isIdentifier, result, } from "./replies.js";
+const noQueue = failed("queue-unavailable", {
+    detail: "The service has no queue workflow.",
+});
+export async function queueRead(context) {
+    const overview = await queueOverview(context);
+    if (overview["queue"] === undefined)
+        return noQueue;
+    return result("queue", overview);
+}
+export async function queueCommand(context, parameters) {
+    const { command, commandId } = parameters;
+    if ((command !== "resume" && command !== "drain") || !isIdentifier(commandId))
+        return invalidRequest("The queue command request is not valid.");
+    if (context.queue === undefined)
+        return noQueue;
+    const change = await context.queue.change({ command, commandId });
+    if (change.kind === "unavailable")
+        return failed("queue-unavailable", { commandId, detail: change.detail });
+    if (change.kind === "conflicting-command")
+        return failed("conflicting-command", {
+            commandId,
+            detail: "The command ID names another queue command.",
+        });
+    return result("queue-command", {
+        command,
+        commandId,
+        replayed: change.kind === "replayed",
+        ...(await queueOverview(context)),
+    });
+}

package/dist/src/service/queue-spend.d.ts

@@ -0,0 +1,6 @@
+import type { Fields } from "../protocol.ts";
+import type { ServiceContext } from "./replies.ts";
+type SpendContext = Pick<ServiceContext, "authority" | "clock" | "queueDailySpendLimitUsd">;
+export declare function queueRun(context: Pick<ServiceContext, "authority">, runId: string): Promise<boolean>;
+export declare function queueSpend(context: SpendContext): Promise<Fields>;
+export {};