cloving 0.3.20 → 1.1.0

package/dist/src/authority/reducer.js

@@ -0,0 +1,139 @@
+import { numberFields, textFields, } from "./transitions.js";
+import { commandEvents, parseCommand } from "./commands.js";
+import { parseEvent } from "./events.js";
+import { gateKey } from "./gates.js";
+import { emptyEffects, evidenceOf, } from "./operations.js";
+import { reduce } from "./reduction.js";
+export const emptyAuthority = {
+    sequence: 0,
+    runs: {},
+    commands: {},
+    intents: [],
+    gates: {},
+    details: {},
+    questions: 0,
+    effects: emptyEffects,
+};
+export function execute(state, proposed) {
+    const command = parseCommand(proposed.command);
+    if (!command)
+        return { kind: "rejected", reason: "invalid-command" };
+    const request = canonical(command);
+    const existing = state.commands[command.commandId];
+    if (existing)
+        return existing.request === request
+            ? { kind: "duplicate", sequence: existing.sequence }
+            : { kind: "rejected", reason: "conflicting-command" };
+    if (staleRevision(state, command))
+        return { kind: "rejected", reason: "stale-revision" };
+    const event = commandEvent(command, {
+        sequence: state.sequence + 1,
+        request,
+        recordedAt: proposed.recordedAt,
+    });
+    const reduction = reduce(state, event);
+    if (reduction.kind === "invalid")
+        return { kind: "rejected", reason: reduction.reason };
+    return {
+        kind: "accepted",
+        events: [event],
+        state: reduction.state,
+        intents: reduction.intents,
+        ...(reduction.disposition === undefined
+            ? {}
+            : { disposition: reduction.disposition }),
+    };
+}
+export function rebuild(events) {
+    let state = emptyAuthority;
+    for (const [index, value] of events.entries())
+        state = applyEvent(state, { value, index }).state;
+    return state;
+}
+export function applyEvent(state, entry) {
+    const { value, index } = entry;
+    const event = parseEvent(value);
+    if (!event)
+        throw new Error(`invalid-event: ${String(index + 1)} malformed-event`);
+    if (!requestMatches(event))
+        throw new Error(`invalid-event: ${String(index + 1)} request-mismatch`);
+    const reduction = reduce(state, event);
+    if (reduction.kind === "invalid")
+        throw new Error(`invalid-event: ${String(event.sequence)} ${reduction.reason}`);
+    return {
+        state: reduction.state,
+        event,
+        evidence: evidenceOf(event, reduction.disposition),
+    };
+}
+function commandEvent(command, record) {
+    const { sequence, request, recordedAt } = record;
+    const payload = {};
+    for (const name of payloadFields) {
+        const value = command[name];
+        if (value !== undefined)
+            payload[name] = String(value);
+    }
+    return {
+        sequence,
+        type: commandEvents[command.kind] ?? "run.created",
+        runId: command.runId,
+        commandId: command.commandId,
+        recordedAt,
+        request,
+        payload,
+    };
+}
+function staleRevision(state, command) {
+    const run = state.runs[command.runId];
+    if (!run || command.expectedRevision === undefined)
+        return false;
+    const gate = command.kind === "decide-gate"
+        ? state.gates[gateKey(command.runId, command.gateId ?? "")]
+        : undefined;
+    if (gate === undefined || gate.kind === "untyped")
+        return command.expectedRevision !== run.revision;
+    return gate.outcome === null && command.expectedRevision !== gate.revision;
+}
+const payloadFields = [
+    ...textFields,
+    ...numberFields.filter((name) => name !== "expectedRevision"),
+];
+function canonical(value) {
+    const fields = value;
+    return JSON.stringify(Object.fromEntries(Object.keys(fields)
+        .sort()
+        .map((key) => [key, fields[key]])));
+}
+export function eligibleIntents(state) {
+    return state.intents.filter((intent) => eligible(state, intent));
+}
+function eligible(state, intent) {
+    if (intent.kind === "protected-effect")
+        return (state.effects.operations[intent.operationId]?.status ===
+            "dispatch-pending");
+    return (state.runs[intent.runId]?.status ===
+        (intent.kind === "start-run" ? "queued" : "running"));
+}
+function requestMatches(event) {
+    let value;
+    try {
+        value = JSON.parse(event.request);
+    }
+    catch {
+        return false;
+    }
+    const command = parseCommand(value);
+    if (!command || canonical(command) !== event.request)
+        return false;
+    const expected = commandEvent(command, event);
+    return JSON.stringify(sorted(expected)) === JSON.stringify(sorted(event));
+}
+function sorted(event) {
+    return [
+        event.type,
+        event.runId,
+        event.commandId,
+        Object.entries(event.payload).sort(([left], [right]) => left < right ? -1 : 1),
+    ];
+}

package/dist/src/authority/reduction-state.d.ts

@@ -0,0 +1,36 @@
+import { type RunDetails } from "./details.ts";
+import { type GateState } from "./gates.ts";
+import { type Disposition, type EffectState } from "./operations.ts";
+import type { AuthorityEvent, AuthorityState, EffectIntent, RunState } from "./transitions.ts";
+export interface Applied {
+    readonly kind: "applied";
+    readonly state: AuthorityState;
+    readonly intents: readonly EffectIntent[];
+    readonly disposition?: Disposition;
+}
+export type Reduction = Applied | {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+export interface Recorded {
+    readonly event: AuthorityEvent;
+    readonly commands: AuthorityState["commands"];
+    readonly run: RunState;
+    readonly details: RunDetails;
+}
+export interface Change extends Recorded {
+    readonly moved?: RunState;
+    readonly gates?: readonly GateState[];
+    readonly added?: readonly EffectIntent[];
+    readonly questions?: number;
+    readonly observed?: RunDetails;
+    readonly effects?: EffectState;
+    readonly released?: readonly string[];
+    readonly disposition?: Disposition;
+}
+export type Handler = (state: AuthorityState, recorded: Recorded) => Reduction;
+export declare function invalid(reason: string): Reduction;
+export declare function text(event: AuthorityEvent, name: string): string;
+export declare function identity(scope: Readonly<Record<string, unknown>>): string;
+export declare function retained(intents: readonly EffectIntent[], event: AuthorityEvent): readonly EffectIntent[];
+export declare function applied(state: AuthorityState, change: Change): Applied;

package/dist/src/authority/reduction-state.js

@@ -0,0 +1,68 @@
+import { operationIdentity } from "../operation-identity.js";
+import { continued } from "./details.js";
+import { gateKey } from "./gates.js";
+import { endedRun } from "./operations.js";
+export function invalid(reason) {
+    return { kind: "invalid", reason };
+}
+export function text(event, name) {
+    return event.payload[name] ?? "";
+}
+export function identity(scope) {
+    const result = operationIdentity(scope);
+    return result.kind === "valid" ? result.value : "";
+}
+const ended = ["run.cancelled", "run.failed", "run.completed"];
+export function retained(intents, event) {
+    if (ended.includes(event.type))
+        return intents.filter((intent) => intent.runId !== event.runId);
+    if (event.type === "run.started")
+        return intents.filter((intent) => intent.runId !== event.runId || intent.kind !== "start-run");
+    return intents;
+}
+function nextEffects(state, change) {
+    const effects = change.effects ?? state.effects;
+    return ended.includes(change.event.type)
+        ? endedRun(effects, change.event)
+        : effects;
+}
+function nextIntents(state, change) {
+    const released = change.released ?? [];
+    return [
+        ...retained(state.intents, change.event).filter((intent) => !released.includes(intent.operationId)),
+        ...(change.added ?? []),
+    ];
+}
+function nextDetails(change) {
+    const details = change.observed ?? change.details;
+    const continuation = (change.added ?? []).some((intent) => intent.kind === "continue-run");
+    return continuation ? continued(details) : details;
+}
+export function applied(state, change) {
+    const { event } = change;
+    return {
+        kind: "applied",
+        ...(change.disposition === undefined
+            ? {}
+            : { disposition: change.disposition }),
+        state: {
+            sequence: event.sequence,
+            runs: change.moved
+                ? { ...state.runs, [event.runId]: change.moved }
+                : state.runs,
+            commands: change.commands,
+            effects: nextEffects(state, change),
+            intents: nextIntents(state, change),
+            gates: {
+                ...state.gates,
+                ...Object.fromEntries((change.gates ?? []).map((gate) => [
+                    gateKey(gate.runId, gate.gateId),
+                    gate,
+                ])),
+            },
+            details: { ...state.details, [event.runId]: nextDetails(change) },
+            questions: change.questions ?? state.questions,
+        },
+        intents: change.added ?? [],
+    };
+}

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

@@ -0,0 +1,6 @@
+import { type Reduction } from "./reduction-state.ts";
+import { type AuthorityEvent, type AuthorityState } from "./transitions.ts";
+export { gateContinuation } from "./gate-reduction.ts";
+export type { Reduction } from "./reduction-state.ts";
+export declare function startOperation(runId: string): string;
+export declare function reduce(state: AuthorityState, event: AuthorityEvent): Reduction;

package/dist/src/authority/reduction.js

@@ -0,0 +1,160 @@
+import { admittedDetails, observed } from "./details.js";
+import { settled } from "./gates.js";
+import { admittedBudgets } from "./budgets.js";
+import { requested } from "./effect-requests.js";
+import { reconciled, reported, stopReported } from "./effect-results.js";
+import { decided, expired, opened, registered } from "./gate-reduction.js";
+import { expired as leaseExpired, granted } from "./leases.js";
+import { applied, identity, invalid, text, } from "./reduction-state.js";
+import { transition, } from "./transitions.js";
+export { gateContinuation } from "./gate-reduction.js";
+function moved(type) {
+    return (state, recorded) => {
+        const result = transition(recorded.run, {
+            type,
+            gateId: text(recorded.event, "gateId"),
+        });
+        if (result.kind === "invalid")
+            return result;
+        return applied(state, { ...recorded, moved: result.run });
+    };
+}
+function closed(type) {
+    return (state, recorded) => {
+        const { event, run } = recorded;
+        const result = transition(run, { type, gateId: "" });
+        if (result.kind === "invalid")
+            return result;
+        const outcome = { decision: null, answer: null, sequence: event.sequence };
+        return applied(state, {
+            ...recorded,
+            moved: result.run,
+            gates: Object.values(state.gates)
+                .filter((gate) => gate.runId === run.runId && gate.outcome === null)
+                .map((gate) => settled(gate, outcome)),
+        });
+    };
+}
+function observation(state, recorded) {
+    return applied(state, {
+        ...recorded,
+        observed: observed(recorded.details, recorded.event),
+        effects: stopReported(state.effects, recorded.event),
+    });
+}
+function dispatched(state, recorded) {
+    const operationId = text(recorded.event, "operationId");
+    const remaining = state.intents.filter((intent) => intent.runId !== recorded.event.runId ||
+        intent.operationId !== operationId);
+    if (remaining.length === state.intents.length)
+        return invalid("unknown-intent");
+    return applied({ ...state, intents: remaining }, recorded);
+}
+function effect(rule) {
+    return (state, recorded) => {
+        const { event, run } = recorded;
+        const result = rule(state.effects, { event, runStatus: run.status });
+        if (result.kind === "invalid")
+            return result;
+        const present = new Set(state.intents.map((intent) => intent.operationId));
+        return applied(state, {
+            ...recorded,
+            effects: result.effects,
+            ...(result.released === undefined ? {} : { released: result.released }),
+            ...(result.disposition === undefined
+                ? {}
+                : { disposition: result.disposition }),
+            added: (result.added ?? [])
+                .filter((operationId) => !present.has(operationId))
+                .map((operationId) => ({
+                kind: "protected-effect",
+                runId: event.runId,
+                operationId,
+            })),
+        });
+    };
+}
+const handlers = {
+    "effect.requested": effect(requested),
+    "lease.granted": effect(granted),
+    "lease.expired": effect(leaseExpired),
+    "effect.reported": effect(reported),
+    "operation.reconciled": effect(reconciled),
+    "run.started": moved("run.started"),
+    "run.paused": moved("run.paused"),
+    "run.resumed": moved("run.resumed"),
+    "run.completed": moved("run.completed"),
+    "run.cancelled": closed("run.cancelled"),
+    "run.failed": closed("run.failed"),
+    "run.observed": observation,
+    "gate.opened": opened,
+    "gate.wait-registered": registered,
+    "gate.decided": decided,
+    "gate.expired": expired,
+    "step.dispatched": dispatched,
+};
+export function startOperation(runId) {
+    return identity({
+        run: runId,
+        phase: "admission",
+        round: 0,
+        operation: "start-run",
+    });
+}
+function created(state, recorded) {
+    const { event, commands } = recorded;
+    if (state.runs[event.runId])
+        return invalid("existing-run");
+    const intent = {
+        kind: "start-run",
+        runId: event.runId,
+        operationId: startOperation(event.runId),
+    };
+    return {
+        kind: "applied",
+        state: {
+            ...state,
+            sequence: event.sequence,
+            runs: {
+                ...state.runs,
+                [event.runId]: {
+                    runId: event.runId,
+                    status: "queued",
+                    revision: 1,
+                    workflow: text(event, "workflow"),
+                    pausedFrom: null,
+                    gates: [],
+                },
+            },
+            commands,
+            intents: [...state.intents, intent],
+            details: {
+                ...state.details,
+                [event.runId]: admittedDetails(event.runId, event.payload),
+            },
+            effects: {
+                ...state.effects,
+                budgets: admittedBudgets(state.effects.budgets, event),
+            },
+        },
+        intents: [intent],
+    };
+}
+export function reduce(state, event) {
+    if (event.sequence !== state.sequence + 1)
+        return invalid("sequence-gap");
+    if (state.commands[event.commandId])
+        return invalid("duplicate-command");
+    const commands = {
+        ...state.commands,
+        [event.commandId]: { request: event.request, sequence: event.sequence },
+    };
+    const handler = handlers[event.type];
+    if (handler === undefined)
+        return created(state, { event, commands });
+    const run = state.runs[event.runId];
+    const details = state.details[event.runId];
+    if (!run || !details)
+        return invalid("unknown-run");
+    return handler(state, { event, commands, run, details });
+}

package/dist/src/authority/status-closure.d.ts

@@ -0,0 +1,4 @@
+import { type Assessment, type OperationSummary, type StatusInput } from "./status-input.ts";
+export declare function unresolved(operations: readonly OperationSummary[]): readonly string[];
+export declare function unresolvedEffects(input: StatusInput): readonly string[];
+export declare function cancelled(input: StatusInput): Assessment;

package/dist/src/authority/status-closure.js

@@ -0,0 +1,57 @@
+import { assessed, } from "./status-input.js";
+const unknownResults = [
+    null,
+    "failed",
+    "stale-epoch",
+];
+export function unresolved(operations) {
+    return operations
+        .filter((operation) => !operation.outcomes.includes("sent") &&
+        operation.outcomes.some((outcome) => unknownResults.includes(outcome)))
+        .map((operation) => operation.operationId);
+}
+function stoppedOperation(input) {
+    const observation = input.details?.observation ?? null;
+    return observation?.condition === "stopped" ? observation.operationId : null;
+}
+export function unresolvedEffects(input) {
+    if (input.closure !== null)
+        return input.closure.unresolved;
+    const stopped = stoppedOperation(input);
+    return unresolved(input.operations).filter((operationId) => operationId !== stopped);
+}
+const resolved = {
+    closure: "cancelled",
+    unresolved: [],
+    open: false,
+};
+const cancelling = (code, rest) => assessed("cancelling", { code, ...rest });
+export function cancelled(input) {
+    const closure = input.closure ?? resolved;
+    if (closure.open)
+        return cancelling("delivery-in-flight", {
+            nextAction: "reconcile-effect",
+            humanInputCanHelp: false,
+        });
+    if (closure.closure === "stop-unconfirmed")
+        return cancelling("stop-unconfirmed", {
+            nextAction: "confirm-worker-stop",
+            humanInputCanHelp: true,
+        });
+    if (closure.unresolved.length > 0)
+        return cancelling("delivery-outcome-unknown", {
+            detail: "The run is dropped. A dispatch has no known result. A stop report of that operation or a later reconciliation resolves it.",
+            nextAction: "reconcile-effect",
+            humanInputCanHelp: false,
+        });
+    if (closure.closure === "stop-not-observed")
+        return cancelling("stop-not-observed", {
+            nextAction: "observe-worker-stop",
+            humanInputCanHelp: false,
+        });
+    return assessed("cancelled", {
+        code: "run-cancelled",
+        nextAction: null,
+        humanInputCanHelp: false,
+    });
+}

package/dist/src/authority/status-effects.d.ts

@@ -0,0 +1,17 @@
+import { type Assessment, type EffectSummary } from "./status-input.ts";
+export interface EffectView {
+    readonly operationId: string;
+    readonly state: string;
+    readonly reason: string | null;
+    readonly leaseGeneration: number | null;
+    readonly attempts: number;
+    readonly limit: number;
+}
+export interface Recovery {
+    readonly attempts: number;
+    readonly limit: number | null;
+}
+export declare function uncertainEffect(effects: readonly EffectSummary[]): Assessment | undefined;
+export declare function effectViews(effects: readonly EffectSummary[]): readonly EffectView[];
+export declare function effectRecovery(effects: readonly EffectSummary[]): Recovery | undefined;
+export declare function effectEvidence(sequences: readonly number[]): readonly string[];

package/dist/src/authority/status-effects.js

@@ -0,0 +1,43 @@
+import { assessed, } from "./status-input.js";
+const blocked = assessed("uncertain-effect", {
+    code: "effect-blocked",
+    nextAction: "inspect-effect",
+    humanInputCanHelp: true,
+});
+const recovering = assessed("uncertain-effect", {
+    code: "effect-recovering",
+    nextAction: "reconcile-effect",
+    humanInputCanHelp: false,
+});
+export function uncertainEffect(effects) {
+    const statuses = effects.map((effect) => effect.status);
+    if (statuses.includes("blocked"))
+        return blocked;
+    return statuses.includes("recovering") ? recovering : undefined;
+}
+function shownReason(effect) {
+    const ready = effect.status === "waiting" && effect.reason === "ready";
+    return ready ? "capacity" : effect.reason;
+}
+export function effectViews(effects) {
+    return effects.map((effect) => ({
+        operationId: effect.operationId,
+        state: effect.status,
+        reason: shownReason(effect),
+        leaseGeneration: effect.leaseGeneration,
+        attempts: effect.attempts,
+        limit: effect.limit,
+    }));
+}
+const uncertainStatuses = ["recovering", "blocked"];
+export function effectRecovery(effects) {
+    const [largest] = effects
+        .filter((effect) => uncertainStatuses.includes(effect.status))
+        .sort((left, right) => right.attempts - left.attempts);
+    if (largest === undefined)
+        return undefined;
+    return { attempts: largest.attempts, limit: largest.limit };
+}
+export function effectEvidence(sequences) {
+    return sequences.map((sequence) => `event:${String(sequence)}`);
+}

package/dist/src/authority/status-input.d.ts

@@ -0,0 +1,45 @@
+import type { RunDetails } from "./details.ts";
+import type { GateState } from "./gates.ts";
+import type { RunClosure } from "./stop-sequence.ts";
+import type { RunState } from "./transitions.ts";
+export interface OperationSummary {
+    readonly operationId: string;
+    readonly kind: "start-run" | "continue-run" | "protected-effect";
+    readonly releasedSequence: number | null;
+    readonly outcomes: readonly (string | null)[];
+}
+export interface EffectSummary {
+    readonly operationId: string;
+    readonly status: string;
+    readonly reason: string | null;
+    readonly leaseGeneration: number | null;
+    readonly attempts: number;
+    readonly limit: number;
+}
+export interface BudgetSummary {
+    readonly limit: number;
+    readonly spent: number;
+}
+export interface StatusInput {
+    readonly run: RunState;
+    readonly details: RunDetails | undefined;
+    readonly gates: readonly GateState[];
+    readonly operations: readonly OperationSummary[];
+    readonly latestSequence: number;
+    readonly silent: boolean;
+    readonly closure: RunClosure | null;
+    readonly effects: readonly EffectSummary[];
+    readonly budget: BudgetSummary | null;
+    readonly effectEvidence: readonly number[];
+}
+export interface Assessment {
+    readonly condition: string;
+    readonly code: string;
+    readonly nextAction: string | null;
+    readonly nextActionAt?: string | null;
+    readonly detail?: string;
+    readonly humanInputCanHelp: boolean;
+}
+export declare function last(operation: OperationSummary): string | null | undefined;
+export declare function inFlight(operations: readonly OperationSummary[]): boolean;
+export declare function assessed(condition: string, rest: Omit<Assessment, "condition">): Assessment;

package/dist/src/authority/status-input.js

@@ -0,0 +1,9 @@
+export function last(operation) {
+    return operation.outcomes.at(-1);
+}
+export function inFlight(operations) {
+    return operations.some((operation) => last(operation) === null);
+}
+export function assessed(condition, rest) {
+    return { condition, ...rest };
+}

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

@@ -0,0 +1,32 @@
+import { type EffectView, type Recovery } from "./status-effects.ts";
+import { type BudgetSummary, type StatusInput } from "./status-input.ts";
+import type { RunStatus } from "./transitions.ts";
+export { unresolved, unresolvedEffects } from "./status-closure.ts";
+export type { EffectView } from "./status-effects.ts";
+export type { Assessment, BudgetSummary, EffectSummary, OperationSummary, StatusInput, } from "./status-input.ts";
+export interface RunView {
+    readonly runId: string;
+    readonly workflow: string;
+    readonly state: RunStatus;
+    readonly condition: string;
+    readonly revision: number;
+    readonly latestSequence: number;
+    readonly pendingDecisions: readonly string[];
+    readonly reason: {
+        readonly code: string;
+        readonly detail: string;
+    };
+    readonly evidence: readonly string[];
+    readonly lastConfirmedObservation: {
+        readonly at: string;
+        readonly sequence: number;
+        readonly source: string;
+    } | null;
+    readonly recovery: Recovery;
+    readonly budget: BudgetSummary | null;
+    readonly effects: readonly EffectView[];
+    readonly nextAction: string | null;
+    readonly nextActionAt: string | null;
+    readonly humanInputCanHelp: boolean;
+}
+export declare function runView(input: StatusInput): RunView;