cloving 0.3.19 → 1.0.1

package/dist/src/authority/status.js

@@ -0,0 +1,256 @@
+import { cancelled } from "./status-closure.js";
+import { effectEvidence, effectRecovery, effectViews, uncertainEffect, } from "./status-effects.js";
+import { assessed, inFlight, last, } from "./status-input.js";
+export { unresolved, unresolvedEffects } from "./status-closure.js";
+const details = new Map([
+    ["awaiting-dispatch", "The run waits for its first dispatch."],
+    ["dispatch-in-progress", "A dispatch of the run is in progress."],
+    [
+        "start-not-reported",
+        "The start is sent. The worker did not report its start.",
+    ],
+    ["in-progress", "The run is in work."],
+    [
+        "no-recent-observation",
+        "No observation arrived in the liveness period. Silence alone is not a failure.",
+    ],
+    [
+        "delivery-outcome-unknown",
+        "A dispatch has no known result. The service reconciles it and tries it again a limited count of times in the same opening, and again at its next start.",
+    ],
+    [
+        "effect-recovering",
+        "A protected effect has no known result. The service reconciles it before a new send.",
+    ],
+    [
+        "effect-blocked",
+        "A protected effect has no known result and its recovery bound is reached. A person must examine the effect.",
+    ],
+    [
+        "pinned-workflow-unavailable",
+        "The installed workflow is not the workflow that the run pinned. The continuation is not sent.",
+    ],
+    ["operator-pause", "The operator paused the run."],
+    ["design-question", "A design question waits for an answer."],
+    ["policy-approval", "A configured approval waits for a decision."],
+    ["gate-open", "A gate of the run is open."],
+    [
+        "delivery-in-flight",
+        "The run is dropped. A dispatch is in flight and has no result yet.",
+    ],
+    [
+        "stop-not-observed",
+        "The run is dropped. The stop of its dispatched work is not observed yet.",
+    ],
+    [
+        "stop-unconfirmed",
+        "The run is dropped. The service asked for the stop of its work and got no confirmation. A person can confirm that the worker stopped.",
+    ],
+    ["world-run-failed", "The SDK run of this run failed in the World."],
+    [
+        "world-run-cancelled",
+        "The SDK run of this run was cancelled in the World. Cloving did not ask for that.",
+    ],
+    [
+        "world-run-waits-without-gate",
+        "The SDK run of this run ended and waits for a decision, and the run has no open gate and no continuation.",
+    ],
+    [
+        "world-run-conflict",
+        "More than one SDK run has one operation of this run. Examine the World runs, then drop the run.",
+    ],
+    ["run-cancelled", "The run is dropped and has no work in progress."],
+    ["run-completed", "The run completed."],
+    ["run-failed", "The run failed."],
+]);
+function uncertain(operations) {
+    return operations.some((operation) => operation.releasedSequence === null &&
+        ["failed", "stale-epoch"].includes(last(operation) ?? ""));
+}
+function blocked(operations) {
+    return operations.some((operation) => operation.releasedSequence === null && last(operation) === "blocked");
+}
+function exhausted(observation) {
+    return (observation.attempt !== null &&
+        observation.limit !== null &&
+        observation.attempt >= observation.limit);
+}
+const unknownEffect = assessed("uncertain-effect", {
+    code: "delivery-outcome-unknown",
+    nextAction: "reconcile-effect",
+    humanInputCanHelp: true,
+});
+function dispatched(operations) {
+    return operations.some((operation) => operation.outcomes.includes("sent"));
+}
+const unavailablePin = assessed("infrastructure-failure", {
+    code: "pinned-workflow-unavailable",
+    nextAction: "restore-pinned-workflow",
+    humanInputCanHelp: true,
+});
+function worldConflict(input) {
+    const code = input.details?.observation?.reason;
+    if (code !== "world-run-conflict")
+        return undefined;
+    return assessed("infrastructure-failure", {
+        code,
+        nextAction: null,
+        humanInputCanHelp: true,
+    });
+}
+function queued(input) {
+    if (uncertain(input.operations))
+        return unknownEffect;
+    if (blocked(input.operations))
+        return unavailablePin;
+    const conflict = worldConflict(input);
+    if (conflict !== undefined)
+        return conflict;
+    if (dispatched(input.operations))
+        return assessed("queued", {
+            code: "start-not-reported",
+            nextAction: null,
+            humanInputCanHelp: false,
+        });
+    const progress = inFlight(input.operations);
+    return assessed("queued", {
+        code: progress ? "dispatch-in-progress" : "awaiting-dispatch",
+        nextAction: progress ? null : "dispatch",
+        humanInputCanHelp: false,
+    });
+}
+const observedActions = {
+    "quota-wait": "recheck-eligibility",
+    "infrastructure-failure": "retry-operation",
+    "code-failure": "repair-code",
+};
+function observedWork(observation) {
+    const spent = observation.condition !== "quota-wait" && exhausted(observation);
+    return assessed(observation.condition, {
+        code: observation.reason,
+        nextAction: spent ? null : (observedActions[observation.condition] ?? null),
+        nextActionAt: spent ? null : observation.retryAt,
+        humanInputCanHelp: spent,
+    });
+}
+function running(input) {
+    if (uncertain(input.operations))
+        return unknownEffect;
+    const effect = uncertainEffect(input.effects);
+    if (effect !== undefined)
+        return effect;
+    if (blocked(input.operations))
+        return unavailablePin;
+    return worldConflict(input) ?? observed(input);
+}
+function observed(input) {
+    const observation = input.details?.observation ?? null;
+    if (observation !== null &&
+        Object.hasOwn(observedActions, observation.condition))
+        return observedWork(observation);
+    if (input.silent)
+        return assessed("working", {
+            code: "no-recent-observation",
+            nextAction: "reconcile-worker",
+            humanInputCanHelp: false,
+        });
+    return assessed("working", {
+        code: observation?.reason ?? "in-progress",
+        nextAction: null,
+        humanInputCanHelp: false,
+    });
+}
+function waiting(input) {
+    const pending = input.gates.filter((gate) => gate.outcome === null);
+    const question = pending.some((gate) => gate.kind === "question");
+    const approval = pending.some((gate) => gate.kind === "approval");
+    if (!question && !approval)
+        return assessed("waiting-decision", {
+            code: "gate-open",
+            nextAction: null,
+            humanInputCanHelp: true,
+        });
+    return assessed("waiting-decision", {
+        code: question ? "design-question" : "policy-approval",
+        nextAction: question ? "answer" : "approve-or-deny",
+        humanInputCanHelp: true,
+    });
+}
+function worldEnd(input) {
+    const reason = input.details?.observation?.reason ?? "";
+    return ["world-run-failed", "world-run-cancelled"].includes(reason)
+        ? reason
+        : undefined;
+}
+const assessments = {
+    queued,
+    running,
+    waiting_gate: waiting,
+    paused: (input) => assessed("paused", {
+        code: worldEnd(input) ?? "operator-pause",
+        nextAction: "resume",
+        humanInputCanHelp: true,
+    }),
+    completed: () => assessed("completed", {
+        code: "run-completed",
+        nextAction: null,
+        humanInputCanHelp: false,
+    }),
+    failed: (input) => assessed("failed", {
+        code: input.details?.observation?.reason ?? "run-failed",
+        nextAction: null,
+        humanInputCanHelp: true,
+    }),
+    cancelled,
+};
+function evidence(observation) {
+    if (observation === null)
+        return [];
+    const reference = observation.evidence === null ? [] : [observation.evidence];
+    return [`event:${String(observation.sequence)}`, ...reference];
+}
+function reasonOf(assessment) {
+    return {
+        code: assessment.code,
+        detail: assessment.detail ??
+            details.get(assessment.code) ??
+            "A worker reported this reason.",
+    };
+}
+export function runView(input) {
+    const { run } = input;
+    const observation = input.details?.observation ?? null;
+    const assessment = assessments[run.status](input);
+    return {
+        runId: run.runId,
+        workflow: run.workflow,
+        state: run.status,
+        condition: assessment.condition,
+        revision: run.revision,
+        latestSequence: input.latestSequence,
+        pendingDecisions: input.gates
+            .filter((gate) => gate.outcome === null)
+            .map((gate) => `${gate.runId}/${gate.gateId}`),
+        reason: reasonOf(assessment),
+        evidence: [
+            ...evidence(observation),
+            ...effectEvidence(input.effectEvidence),
+        ],
+        lastConfirmedObservation: observation === null
+            ? null
+            : {
+                at: observation.recordedAt,
+                sequence: observation.sequence,
+                source: "worker",
+            },
+        recovery: effectRecovery(input.effects) ?? {
+            attempts: observation?.attempt ?? 0,
+            limit: observation?.limit ?? null,
+        },
+        budget: input.budget,
+        effects: effectViews(input.effects),
+        nextAction: assessment.nextAction,
+        nextActionAt: assessment.nextActionAt ?? null,
+        humanInputCanHelp: assessment.humanInputCanHelp,
+    };
+}

package/dist/src/authority/stop-sequence.d.ts

@@ -0,0 +1,37 @@
+export interface AttemptSummary {
+    readonly effectId: string;
+    readonly purpose: string;
+    readonly outcome: string | null;
+    readonly stagedSequence: number;
+}
+export interface StopSubject {
+    readonly operationId: string;
+    readonly kind: string;
+    readonly attempts: readonly AttemptSummary[];
+    readonly status: string | null;
+    readonly receipt: string | null;
+    readonly stopped: boolean;
+}
+export type StopClass = "open" | "resolved" | "unknown" | "alive";
+export declare function stopClasses(subjects: readonly StopSubject[]): ReadonlyMap<string, StopClass>;
+export declare function stopCount(subject: StopSubject, cancelledSequence: number): number;
+export interface StopRule {
+    readonly cancelledSequence: number;
+    readonly stopLimit: number;
+    readonly stopSupported: boolean;
+    readonly opening: boolean;
+    readonly rejected: ReadonlySet<string>;
+}
+export interface StopAttempt {
+    readonly operationId: string;
+    readonly kind: string;
+    readonly purpose: "stop" | "reconcile";
+}
+export declare function stopAttempts(subjects: readonly StopSubject[], rule: StopRule): readonly StopAttempt[];
+export type Closure = "cancelled" | "stop-not-observed" | "stop-unconfirmed";
+export interface RunClosure {
+    readonly closure: Closure;
+    readonly unresolved: readonly string[];
+    readonly open: boolean;
+}
+export declare function runClosure(subjects: readonly StopSubject[], rule: Pick<StopRule, "cancelledSequence" | "stopLimit">): RunClosure;

package/dist/src/authority/stop-sequence.js

@@ -0,0 +1,91 @@
+const finalStatuses = [
+    "refused",
+    "completed",
+    "failed",
+    "stopped",
+    "cancelled",
+];
+const notStarted = ["withheld", "blocked", "absent"];
+function sent(subject) {
+    return subject.attempts.some((attempt) => attempt.outcome === "sent");
+}
+function accepted(subject) {
+    return subject.receipt !== null || sent(subject);
+}
+function protectedClass(subject) {
+    if (finalStatuses.includes(subject.status ?? ""))
+        return "resolved";
+    return subject.receipt === null ? "unknown" : "alive";
+}
+function runClass(subject) {
+    if (subject.stopped)
+        return "resolved";
+    if (sent(subject))
+        return "alive";
+    const last = subject.attempts.at(-1)?.outcome ?? "";
+    return notStarted.includes(last) ? "resolved" : "unknown";
+}
+export function stopClasses(subjects) {
+    return new Map(subjects.map((subject) => [subject.operationId, classOf(subject)]));
+}
+function classOf(subject) {
+    if (subject.attempts.some((attempt) => attempt.outcome === null))
+        return "open";
+    return subject.kind === "protected-effect"
+        ? protectedClass(subject)
+        : runClass(subject);
+}
+const stopPurposes = ["stop", "reconcile"];
+export function stopCount(subject, cancelledSequence) {
+    return subject.attempts.filter((attempt) => attempt.outcome !== null &&
+        stopPurposes.includes(attempt.purpose) &&
+        attempt.stagedSequence >= cancelledSequence).length;
+}
+const uncertainStatuses = ["recovering", "blocked"];
+function uncertain(subject) {
+    return uncertainStatuses.includes(subject.status ?? "");
+}
+function alivePurposes(subject, rule) {
+    if (rule.stopSupported)
+        return ["stop"];
+    return uncertain(subject) ? ["reconcile"] : [];
+}
+function purposes(classed, rule) {
+    const { subject, kind } = classed;
+    if (kind === "unknown")
+        return ["reconcile"];
+    return kind === "alive" ? alivePurposes(subject, rule) : [];
+}
+export function stopAttempts(subjects, rule) {
+    const classes = stopClasses(subjects);
+    return subjects
+        .filter((subject) => rule.opening ||
+        rule.rejected.has(subject.operationId) ||
+        stopCount(subject, rule.cancelledSequence) < rule.stopLimit)
+        .flatMap((subject) => purposes({ subject, kind: classes.get(subject.operationId) }, rule).map((purpose) => ({
+        operationId: subject.operationId,
+        kind: subject.kind,
+        purpose,
+    })));
+}
+function closureOf(pending, rule) {
+    if (pending.length === 0)
+        return "cancelled";
+    const bounded = pending.some((subject) => stopCount(subject, rule.cancelledSequence) >= rule.stopLimit);
+    return bounded ? "stop-unconfirmed" : "stop-not-observed";
+}
+export function runClosure(subjects, rule) {
+    const classes = stopClasses(subjects);
+    const classed = (kind) => subjects.filter((subject) => classes.get(subject.operationId) === kind);
+    const open = classed("open");
+    return {
+        closure: open.length > 0
+            ? "stop-not-observed"
+            : closureOf([...classed("unknown"), ...classed("alive")], rule),
+        unresolved: [
+            ...open.filter((subject) => !accepted(subject)),
+            ...classed("unknown"),
+        ].map((subject) => subject.operationId),
+        open: open.length > 0,
+    };
+}

package/dist/src/authority/transitions.d.ts

@@ -0,0 +1,63 @@
+import type { RunDetails } from "./details.ts";
+import type { GateState } from "./gates.ts";
+import type { EffectState } from "./operations.ts";
+export type RunStatus = "queued" | "running" | "waiting_gate" | "paused" | "completed" | "failed" | "cancelled";
+export interface RunState {
+    readonly runId: string;
+    readonly status: RunStatus;
+    readonly revision: number;
+    readonly workflow: string;
+    readonly pausedFrom: RunStatus | null;
+    readonly gates: readonly string[];
+}
+export interface EffectIntent {
+    readonly kind: "start-run" | "continue-run" | "protected-effect";
+    readonly runId: string;
+    readonly operationId: string;
+}
+export interface AuthorityState {
+    readonly sequence: number;
+    readonly runs: Readonly<Record<string, RunState>>;
+    readonly commands: Readonly<Record<string, {
+        readonly request: string;
+        readonly sequence: number;
+    }>>;
+    readonly intents: readonly EffectIntent[];
+    readonly gates: Readonly<Record<string, GateState>>;
+    readonly details: Readonly<Record<string, RunDetails>>;
+    readonly questions: number;
+    readonly effects: EffectState;
+}
+export declare const eventTypes: readonly ["run.created", "run.started", "gate.opened", "gate.wait-registered", "gate.decided", "gate.expired", "run.paused", "run.resumed", "run.completed", "run.failed", "run.cancelled", "run.observed", "step.dispatched", "effect.requested", "lease.granted", "lease.expired", "effect.reported", "operation.reconciled"];
+export type EventType = (typeof eventTypes)[number];
+export interface AuthorityEvent {
+    readonly sequence: number;
+    readonly type: EventType;
+    readonly runId: string;
+    readonly commandId: string;
+    readonly recordedAt: string;
+    readonly request: string;
+    readonly payload: Readonly<Record<string, string>>;
+}
+export declare const numberFields: readonly ["expectedRevision", "generation", "attempt", "limit", "effectLimit", "units", "recoveryLimit", "leaseGeneration", "sourceGeneration", "capacity"];
+export declare const textFields: readonly ["workflow", "submission", "input", "resolver", "gateId", "gateKind", "subject", "prompt", "expiresAt", "decision", "answer", "condition", "reason", "evidence", "retryAt", "operationId", "receipt", "capabilities", "capability", "method", "target", "payload", "inputDigest", "resource", "transport", "source", "worker", "outcome", "outcomeReason", "result"];
+export type NumberField = (typeof numberFields)[number];
+export type TextField = (typeof textFields)[number];
+export type AuthorityCommand = {
+    readonly kind: string;
+    readonly commandId: string;
+    readonly runId: string;
+} & Readonly<Partial<Record<NumberField, number>>> & Readonly<Partial<Record<TextField, string>>>;
+export type Move = Exclude<EventType, "run.created" | "step.dispatched" | "gate.wait-registered" | "run.observed" | "effect.requested" | "lease.granted" | "lease.expired" | "effect.reported" | "operation.reconciled">;
+export declare const terminal: readonly RunStatus[];
+export type Transition = {
+    readonly kind: "moved";
+    readonly run: RunState;
+} | {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+export declare function transition(run: RunState, event: {
+    readonly type: Move;
+    readonly gateId: string;
+}): Transition;

package/dist/src/authority/transitions.js

@@ -0,0 +1,122 @@
+export const eventTypes = [
+    "run.created",
+    "run.started",
+    "gate.opened",
+    "gate.wait-registered",
+    "gate.decided",
+    "gate.expired",
+    "run.paused",
+    "run.resumed",
+    "run.completed",
+    "run.failed",
+    "run.cancelled",
+    "run.observed",
+    "step.dispatched",
+    "effect.requested",
+    "lease.granted",
+    "lease.expired",
+    "effect.reported",
+    "operation.reconciled",
+];
+export const numberFields = [
+    "expectedRevision",
+    "generation",
+    "attempt",
+    "limit",
+    "effectLimit",
+    "units",
+    "recoveryLimit",
+    "leaseGeneration",
+    "sourceGeneration",
+    "capacity",
+];
+export const textFields = [
+    "workflow",
+    "submission",
+    "input",
+    "resolver",
+    "gateId",
+    "gateKind",
+    "subject",
+    "prompt",
+    "expiresAt",
+    "decision",
+    "answer",
+    "condition",
+    "reason",
+    "evidence",
+    "retryAt",
+    "operationId",
+    "receipt",
+    "capabilities",
+    "capability",
+    "method",
+    "target",
+    "payload",
+    "inputDigest",
+    "resource",
+    "transport",
+    "source",
+    "worker",
+    "outcome",
+    "outcomeReason",
+    "result",
+];
+export const terminal = [
+    "completed",
+    "failed",
+    "cancelled",
+];
+const active = ["queued", "running", "waiting_gate"];
+const sources = {
+    "run.started": ["queued"],
+    "gate.opened": ["running", "waiting_gate"],
+    "gate.decided": ["waiting_gate"],
+    "gate.expired": ["waiting_gate"],
+    "run.paused": active,
+    "run.completed": ["running"],
+    "run.failed": active,
+    "run.cancelled": [...active, "paused"],
+};
+const changes = {
+    "run.started": () => ({ status: "running" }),
+    "gate.opened": (run, gateId) => ({
+        status: "waiting_gate",
+        gates: [...run.gates, gateId],
+    }),
+    "run.paused": (run) => ({ status: "paused", pausedFrom: run.status }),
+    "run.completed": () => ({ status: "completed" }),
+    "run.failed": () => ({ status: "failed" }),
+    "run.cancelled": () => ({ status: "cancelled" }),
+};
+export function transition(run, event) {
+    const { type, gateId } = event;
+    if (terminal.includes(run.status))
+        return invalid("terminal-run");
+    if (type === "run.resumed")
+        return run.pausedFrom
+            ? moved(run, { status: run.pausedFrom, pausedFrom: null })
+            : invalid("invalid-transition");
+    if (!sources[type].includes(run.status))
+        return invalid("invalid-transition");
+    if (type === "gate.opened" && run.gates.includes(gateId))
+        return invalid("existing-gate");
+    if (type === "gate.decided" || type === "gate.expired")
+        return run.gates.includes(gateId)
+            ? moved(run, decided(run, gateId))
+            : invalid("unknown-gate");
+    return moved(run, changes[type](run, gateId));
+}
+function decided(run, gateId) {
+    const gates = run.gates.filter((gate) => gate !== gateId);
+    return { status: gates.length === 0 ? "running" : "waiting_gate", gates };
+}
+function moved(run, change) {
+    return {
+        kind: "moved",
+        run: { ...run, ...change, revision: run.revision + 1 },
+    };
+}
+function invalid(reason) {
+    return { kind: "invalid", reason };
+}

package/dist/src/broker/actor/adapter-calls.d.ts

@@ -0,0 +1,13 @@
+export type CallResult<Reply> = {
+    readonly kind: "replied";
+    readonly reply: Reply;
+} | {
+    readonly kind: "thrown";
+    readonly message: string;
+} | {
+    readonly kind: "overdue";
+};
+export interface AdapterCalls {
+    readonly call: <Reply>(operationId: string, invoke: (signal: AbortSignal) => Promise<Reply>) => Promise<CallResult<Reply>>;
+}
+export declare function adapterCalls(milliseconds: number): AdapterCalls;

package/dist/src/broker/actor/adapter-calls.js

@@ -0,0 +1,34 @@
+function attempted(invoke, signal) {
+    return Promise.resolve()
+        .then(() => invoke(signal))
+        .then((reply) => ({ kind: "replied", reply }), (error) => ({
+        kind: "thrown",
+        message: String(Reflect.get(Object(error), "message")),
+    }));
+}
+export function adapterCalls(milliseconds) {
+    const overdue = new Map();
+    return {
+        call: async (operationId, invoke) => {
+            if (overdue.get(operationId)?.settled === false)
+                return { kind: "overdue" };
+            const limit = new AbortController();
+            const open = { settled: false };
+            const attempt = attempted(invoke, limit.signal).then((result) => {
+                open.settled = true;
+                return result;
+            });
+            const expiry = Promise.withResolvers();
+            const timer = setTimeout(() => {
+                expiry.resolve({ kind: "overdue" });
+            }, milliseconds);
+            const result = await Promise.race([attempt, expiry.promise]);
+            clearTimeout(timer);
+            if (result.kind !== "overdue")
+                return result;
+            limit.abort();
+            overdue.set(operationId, open);
+            return result;
+        },
+    };
+}

package/dist/src/broker/actor/adapter-outcomes.d.ts

@@ -0,0 +1,28 @@
+import type { CallResult } from "./adapter-calls.ts";
+export type Settlement = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "accepted";
+    readonly receipt: string;
+    readonly worker: string;
+} | (Identity & {
+    readonly kind: "completed";
+    readonly receipt: string;
+    readonly result: string | null;
+    readonly reason: string | null;
+}) | (Identity & {
+    readonly kind: "failed";
+    readonly reason: string;
+    readonly result?: string;
+}) | (Identity & {
+    readonly kind: "stopped";
+}) | {
+    readonly kind: "unknown";
+    readonly reason: string;
+};
+interface Identity {
+    readonly receipt: string | null;
+    readonly worker: string | null;
+}
+export declare function settlement(result: CallResult<unknown>, resultBytes: number): Settlement;
+export {};