cloving 0.3.20 → 1.0.1

package/dist/src/authority/effect-results.js

@@ -0,0 +1,236 @@
+import { current, ownedLease } from "./leases.js";
+import { cancelledOperation, count, field, isFinal, isHolding, namesRunIntent, rejected, withOperation, } from "./operations.js";
+const terminalStatuses = ["completed", "failed", "cancelled"];
+function disposition(operation, reason) {
+    return {
+        operationId: operation.operationId,
+        disposition: reason === null ? "applied" : "rejected",
+        reason,
+    };
+}
+function released(effects, operation) {
+    const lease = ownedLease(effects, operation);
+    return {
+        ...effects,
+        leases: lease === undefined
+            ? effects.leases
+            : {
+                ...effects.leases,
+                [lease.resourceKey]: { ...lease, state: "released" },
+            },
+        holding: effects.holding - (isHolding(operation) ? 1 : 0),
+    };
+}
+function settled(effects, settlement) {
+    const { operation, event, status } = settlement;
+    return {
+        kind: "changed",
+        effects: withOperation(released(effects, operation), {
+            ...operation,
+            status,
+            receipt: operation.receipt ?? event.payload["receipt"] ?? null,
+            worker: operation.worker ?? event.payload["worker"] ?? null,
+            reason: event.payload["reason"] ?? null,
+            result: event.payload["result"] ?? null,
+            waitSequence: null,
+            settledSequence: event.sequence,
+        }),
+        released: [operation.operationId],
+        disposition: disposition(operation, null),
+    };
+}
+function reportRefusal(effects, subject) {
+    const { operation, event } = subject;
+    if (operation.inputDigest !== field(event, "inputDigest"))
+        return "input-mismatch";
+    if (isFinal(operation))
+        return "operation-settled";
+    const lease = ownedLease(effects, operation);
+    if (lease?.generation !== count(event, "leaseGeneration"))
+        return "retired-lease-generation";
+    if (!current(lease, event))
+        return "lease-expired";
+    if (operation.worker === null)
+        return "acceptance-not-recorded";
+    if (operation.worker !== field(event, "worker"))
+        return "worker-mismatch";
+    return undefined;
+}
+const reportedStatuses = {
+    completed: "completed",
+    failed: "failed",
+    stopped: "stopped",
+};
+export function reported(effects, context) {
+    const { event } = context;
+    const operation = effects.operations[field(event, "operationId")];
+    if (operation?.runId !== event.runId)
+        return rejected("unknown-operation");
+    const refusal = reportRefusal(effects, { ...context, operation });
+    if (refusal !== undefined)
+        return {
+            kind: "changed",
+            effects,
+            disposition: disposition(operation, refusal),
+        };
+    return settled(effects, {
+        ...context,
+        operation,
+        status: reportedStatuses[field(event, "outcome")] ?? "failed",
+    });
+}
+function formRefusal(subject) {
+    const { operation, event } = subject;
+    const outcome = field(event, "outcome");
+    if (outcome === "not-started" && operation.receipt !== null)
+        return "acceptance-recorded";
+    const identified = event.payload["receipt"] !== undefined &&
+        event.payload["worker"] !== undefined;
+    return outcome === "accepted" && !identified ? "invalid-outcome" : undefined;
+}
+function outcomeRefusal(effects, subject) {
+    const { operation, event } = subject;
+    if (isFinal(operation))
+        return "operation-settled";
+    if (ownedLease(effects, operation)?.generation !==
+        count(event, "leaseGeneration"))
+        return "retired-lease-generation";
+    const worker = event.payload["worker"];
+    const bound = operation.worker ?? worker;
+    if (worker !== undefined && worker !== bound)
+        return "worker-mismatch";
+    return formRefusal(subject);
+}
+function counted(operation) {
+    const attempts = operation.attempts + 1;
+    if (attempts < operation.recoveryLimit)
+        return { ...operation, attempts };
+    return {
+        ...operation,
+        attempts,
+        status: "blocked",
+        reason: "outcome-unknown",
+    };
+}
+function accepted(effects, subject) {
+    const { operation, event } = subject;
+    const lease = ownedLease(effects, operation);
+    const live = lease !== undefined && current(lease, event);
+    return {
+        kind: "changed",
+        effects: withOperation(effects, {
+            ...operation,
+            receipt: operation.receipt ?? field(event, "receipt"),
+            worker: operation.worker ?? field(event, "worker"),
+            status: live ? "running" : "recovering",
+            reason: live ? null : "lease-expired",
+        }),
+        released: [operation.operationId],
+        disposition: disposition(operation, null),
+    };
+}
+function statedReason(event) {
+    const stated = field(event, "reason");
+    return stated === "" ? "not-started" : stated;
+}
+function notStarted(effects, subject) {
+    const { operation, event, runStatus } = subject;
+    const exhausted = (effects.budgets[operation.runId]?.exhaustedSequence ?? null) !== null ||
+        field(event, "reason") === "budget-exhausted";
+    const ended = terminalStatuses.includes(runStatus);
+    const waiting = {
+        ...operation,
+        status: "waiting",
+        reason: runStatus === "running" ? "ready" : "run-not-running",
+        waitSequence: event.sequence,
+    };
+    const cancelled = cancelledOperation(operation, {
+        reason: exhausted ? "budget-exhausted" : statedReason(event),
+        sequence: event.sequence,
+    });
+    const final = ended || exhausted;
+    return {
+        kind: "changed",
+        effects: withOperation(released(effects, operation), final ? cancelled : waiting),
+        ...(final ? { released: [operation.operationId] } : {}),
+        disposition: disposition(operation, null),
+    };
+}
+function unknown(effects, subject) {
+    const { operation } = subject;
+    const attempted = counted(operation);
+    return {
+        kind: "changed",
+        effects: withOperation(effects, {
+            ...attempted,
+            status: attempted.status === "blocked" ? "blocked" : "recovering",
+            reason: "outcome-unknown",
+        }),
+        disposition: disposition(operation, null),
+    };
+}
+function final(status) {
+    return (effects, subject) => settled(effects, { ...subject, status });
+}
+const outcomes = {
+    accepted,
+    "not-started": notStarted,
+    unknown,
+    completed: final("completed"),
+    failed: final("failed"),
+    stopped: final("stopped"),
+};
+function stoppedIntent(effects, event) {
+    const operationId = field(event, "operationId");
+    const known = field(event, "outcome") === "stopped" &&
+        namesRunIntent(operationId, event.runId);
+    if (!known)
+        return rejected("unknown-operation");
+    return {
+        kind: "changed",
+        effects: {
+            ...effects,
+            stops: {
+                ...effects.stops,
+                [operationId]: { runId: event.runId, sequence: event.sequence },
+            },
+        },
+        disposition: { operationId, disposition: "applied", reason: null },
+    };
+}
+export function stopReported(effects, event) {
+    const operationId = event.payload["operationId"];
+    const named = field(event, "condition") === "stopped" &&
+        operationId !== undefined &&
+        namesRunIntent(operationId, event.runId);
+    if (!named)
+        return effects;
+    return {
+        ...effects,
+        stops: {
+            ...effects.stops,
+            [operationId]: { runId: event.runId, sequence: event.sequence },
+        },
+    };
+}
+export function reconciled(effects, context) {
+    const { event } = context;
+    const operation = effects.operations[field(event, "operationId")];
+    if (operation === undefined)
+        return stoppedIntent(effects, event);
+    if (operation.runId !== event.runId)
+        return rejected("unknown-operation");
+    const subject = { ...context, operation };
+    const refusal = outcomeRefusal(effects, subject);
+    const apply = outcomes[field(event, "outcome")];
+    if (refusal === undefined && apply !== undefined)
+        return apply(effects, subject);
+    const reason = refusal ?? "invalid-outcome";
+    return {
+        kind: "changed",
+        effects: isHolding(operation)
+            ? withOperation(effects, counted(operation))
+            : effects,
+        disposition: disposition(operation, reason),
+    };
+}

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

@@ -0,0 +1,2 @@
+import { type AuthorityEvent } from "./transitions.ts";
+export declare function parseEvent(value: unknown): AuthorityEvent | null;

package/dist/src/authority/events.js

@@ -0,0 +1,45 @@
+import { isRecordKey } from "./commands.js";
+import { eventTypes } from "./transitions.js";
+export function parseEvent(value) {
+    const fields = record(value);
+    if (!fields)
+        return null;
+    const { sequence, type, runId, commandId, recordedAt, request } = fields;
+    const payload = textRecord(fields["payload"]);
+    const eventType = eventTypes.find((item) => item === type);
+    if (typeof sequence !== "number" ||
+        !Number.isSafeInteger(sequence) ||
+        eventType === undefined ||
+        !isRecordKey(runId) ||
+        !isRecordKey(commandId) ||
+        typeof recordedAt !== "string" ||
+        typeof request !== "string" ||
+        !payload)
+        return null;
+    return {
+        sequence,
+        type: eventType,
+        runId,
+        commandId,
+        recordedAt,
+        request,
+        payload,
+    };
+}
+function textRecord(value) {
+    const fields = record(value);
+    if (!fields)
+        return null;
+    const entries = [];
+    for (const [key, item] of Object.entries(fields)) {
+        if (typeof item !== "string")
+            return null;
+        entries.push([key, item]);
+    }
+    return Object.fromEntries(entries);
+}
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return Object.fromEntries(Object.entries(value));
+}

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

@@ -0,0 +1,8 @@
+import { type SettledGate } from "./gates.ts";
+import { type Recorded, type Reduction } from "./reduction-state.ts";
+import { type AuthorityState, type EffectIntent } from "./transitions.ts";
+export declare function gateContinuation(gate: SettledGate): EffectIntent;
+export declare function opened(state: AuthorityState, recorded: Recorded): Reduction;
+export declare function decided(state: AuthorityState, recorded: Recorded): Reduction;
+export declare function expired(state: AuthorityState, recorded: Recorded): Reduction;
+export declare function registered(state: AuthorityState, recorded: Recorded): Reduction;

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

@@ -0,0 +1,109 @@
+import { continues, decisionRefusal, expiryRefusal, gateKey, openedGate, reusable, settled, } from "./gates.js";
+import { applied, identity, invalid, text, } from "./reduction-state.js";
+import { terminal, transition, } from "./transitions.js";
+export function gateContinuation(gate) {
+    return {
+        kind: "continue-run",
+        runId: gate.runId,
+        operationId: identity({
+            run: gate.runId,
+            phase: "gate",
+            round: gate.outcome.sequence,
+            operation: "continue-run",
+            key: gate.gateId,
+        }),
+    };
+}
+function continuations(gate) {
+    return continues(gate) ? [gateContinuation(gate)] : [];
+}
+export function opened(state, recorded) {
+    const { event, run } = recorded;
+    const result = transition(run, {
+        type: "gate.opened",
+        gateId: text(event, "gateId"),
+    });
+    if (result.kind === "invalid")
+        return result;
+    const question = event.payload["gateKind"] === "question";
+    const questions = state.questions + (question ? 1 : 0);
+    const gate = openedGate({
+        runId: event.runId,
+        sequence: event.sequence,
+        payload: event.payload,
+        generation: recorded.details.generation,
+        label: question ? questions : null,
+    });
+    if (!reusable(gateOf(state, event), gate))
+        return invalid("existing-gate");
+    return applied(state, {
+        ...recorded,
+        moved: result.run,
+        questions,
+        gates: [gate],
+    });
+}
+function concluded(state, conclusion) {
+    const { run, gate, outcome } = conclusion;
+    const result = transition(run, { type: "gate.decided", gateId: gate.gateId });
+    if (result.kind === "invalid")
+        return result;
+    const next = settled(gate, outcome);
+    return applied(state, {
+        ...conclusion,
+        moved: result.run,
+        gates: [next],
+        added: continuations(next),
+    });
+}
+function gateOf(state, event) {
+    return state.gates[gateKey(event.runId, text(event, "gateId"))];
+}
+export function decided(state, recorded) {
+    const { event } = recorded;
+    const gate = gateOf(state, event);
+    if (gate === undefined)
+        return invalid("unknown-gate");
+    const refusal = decisionRefusal(gate, event);
+    if (refusal !== undefined)
+        return invalid(refusal);
+    return concluded(state, {
+        ...recorded,
+        gate,
+        outcome: {
+            decision: text(event, "decision"),
+            answer: event.payload["answer"] ?? null,
+            sequence: event.sequence,
+        },
+    });
+}
+export function expired(state, recorded) {
+    const { event } = recorded;
+    const gate = gateOf(state, event);
+    if (gate === undefined)
+        return invalid("unknown-gate");
+    const refusal = expiryRefusal(gate, event.recordedAt);
+    if (refusal !== undefined)
+        return invalid(refusal);
+    return concluded(state, {
+        ...recorded,
+        gate,
+        outcome: { decision: "expired", answer: null, sequence: event.sequence },
+    });
+}
+export function registered(state, recorded) {
+    const { event, run } = recorded;
+    if (terminal.includes(run.status))
+        return invalid("terminal-run");
+    const gate = gateOf(state, event);
+    if (gate === undefined)
+        return invalid("unknown-gate");
+    if (gate.wait === "registered")
+        return invalid("wait-already-registered");
+    const next = { ...gate, wait: "registered" };
+    return applied(state, {
+        ...recorded,
+        gates: [next],
+        added: continuations(next),
+    });
+}

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

@@ -0,0 +1,48 @@
+export type GateKind = "question" | "approval" | "untyped";
+export interface GateOutcome {
+    readonly decision: string | null;
+    readonly answer: string | null;
+    readonly sequence: number;
+}
+export interface GateState {
+    readonly runId: string;
+    readonly gateId: string;
+    readonly kind: GateKind;
+    readonly label: number | null;
+    readonly subject: string | null;
+    readonly prompt: string | null;
+    readonly expiresAt: string | null;
+    readonly generation: number;
+    readonly revision: number;
+    readonly wait: "registered" | "pending";
+    readonly outcome: GateOutcome | null;
+    readonly openedSequence: number;
+}
+type Payload = Readonly<Record<string, string>>;
+export declare function allowedDecisions(kind: GateKind): readonly string[] | null;
+export declare function reusable(existing: GateState | undefined, next: GateState): boolean;
+export declare function gateKey(runId: string, gateId: string): string;
+export declare function openedGate(opening: {
+    readonly runId: string;
+    readonly sequence: number;
+    readonly payload: Payload;
+    readonly generation: number;
+    readonly label: number | null;
+}): GateState;
+export declare function decisionRefusal(gate: GateState, decision: {
+    readonly payload: Payload;
+    readonly recordedAt: string;
+}): string | undefined;
+export declare function expiryRefusal(gate: GateState, recordedAt: string): string | undefined;
+export declare function settled(gate: GateState, outcome: GateOutcome): GateState;
+export type SettledGate = GateState & {
+    readonly outcome: GateOutcome;
+};
+export declare function isSettled(gate: GateState): gate is SettledGate;
+export type ContinuingGate = GateState & {
+    readonly outcome: GateOutcome & {
+        readonly decision: string;
+    };
+};
+export declare function continues(gate: GateState): gate is ContinuingGate;
+export {};

package/dist/src/authority/gates.js

@@ -0,0 +1,77 @@
+import { notBefore } from "./instants.js";
+const allowed = {
+    question: ["answered"],
+    approval: ["approved", "denied"],
+    untyped: null,
+};
+const kinds = {
+    question: "question",
+    approval: "approval",
+};
+export function allowedDecisions(kind) {
+    return allowed[kind];
+}
+export function reusable(existing, next) {
+    if (existing === undefined)
+        return true;
+    return existing.kind === "untyped" && next.kind === "untyped";
+}
+export function gateKey(runId, gateId) {
+    return `${runId} ${gateId}`;
+}
+export function openedGate(opening) {
+    const { payload } = opening;
+    const kind = kinds[payload["gateKind"] ?? ""] ?? "untyped";
+    return {
+        runId: opening.runId,
+        gateId: payload["gateId"] ?? "",
+        kind,
+        label: opening.label,
+        subject: payload["subject"] ?? null,
+        prompt: payload["prompt"] ?? null,
+        expiresAt: payload["expiresAt"] ?? null,
+        generation: opening.generation,
+        revision: 1,
+        wait: kind === "untyped" ? "registered" : "pending",
+        outcome: null,
+        openedSequence: opening.sequence,
+    };
+}
+function untypedRefusal(payload) {
+    const bound = payload["generation"] !== undefined || payload["subject"] !== undefined;
+    return bound ? "decision-not-allowed" : undefined;
+}
+export function decisionRefusal(gate, decision) {
+    const { payload, recordedAt } = decision;
+    if (gate.kind === "untyped")
+        return untypedRefusal(payload);
+    if (gate.outcome !== null)
+        return "decision-not-pending";
+    if (payload["generation"] !== String(gate.generation))
+        return "stale-generation";
+    if (payload["subject"] !== gate.subject)
+        return "subject-mismatch";
+    if (!allowed[gate.kind]?.includes(payload["decision"] ?? ""))
+        return "decision-not-allowed";
+    if (gate.expiresAt !== null && notBefore(recordedAt, gate.expiresAt))
+        return "decision-expired";
+    return undefined;
+}
+export function expiryRefusal(gate, recordedAt) {
+    if (gate.outcome !== null)
+        return "decision-not-pending";
+    if (gate.expiresAt === null || !notBefore(recordedAt, gate.expiresAt))
+        return "not-expired";
+    return undefined;
+}
+export function settled(gate, outcome) {
+    return { ...gate, outcome, revision: gate.revision + 1 };
+}
+export function isSettled(gate) {
+    return gate.outcome !== null;
+}
+export function continues(gate) {
+    return (gate.wait === "registered" &&
+        isSettled(gate) &&
+        gate.outcome.decision !== null);
+}

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

@@ -0,0 +1,15 @@
+import type { AuthorityState } from "./transitions.ts";
+export declare class HistoryState {
+    private state;
+    private readonly runs;
+    private readonly commands;
+    private readonly details;
+    private readonly gates;
+    private readonly budgets;
+    private readonly runGates;
+    private readonly intents;
+    private readonly pending;
+    scope(value: unknown): AuthorityState;
+    record(state: AuthorityState, runId: string): void;
+    finish(): AuthorityState;
+}

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

@@ -0,0 +1,61 @@
+import { parseEvent } from "./events.js";
+import { emptyAuthority } from "./reducer.js";
+function entry(values, key) {
+    const value = values[key];
+    return value === undefined ? {} : { [key]: value };
+}
+export class HistoryState {
+    state = emptyAuthority;
+    runs = {};
+    commands = {};
+    details = {};
+    gates = {};
+    budgets = {};
+    runGates = new Map();
+    intents = new Map();
+    pending = new Set();
+    scope(value) {
+        const event = parseEvent(value);
+        if (event === null)
+            return this.state;
+        return {
+            ...this.state,
+            runs: entry(this.runs, event.runId),
+            commands: entry(this.commands, event.commandId),
+            details: entry(this.details, event.runId),
+            gates: this.runGates.get(event.runId) ?? {},
+            effects: {
+                ...this.state.effects,
+                budgets: entry(this.budgets, event.runId),
+            },
+            intents: this.intents.get(event.runId) ?? [],
+        };
+    }
+    record(state, runId) {
+        Object.assign(this.runs, state.runs);
+        Object.assign(this.commands, state.commands);
+        Object.assign(this.details, state.details);
+        Object.assign(this.gates, state.gates);
+        Object.assign(this.budgets, state.effects.budgets);
+        this.runGates.set(runId, state.gates);
+        const remaining = new Set(state.intents);
+        for (const intent of this.intents.get(runId) ?? [])
+            if (!remaining.has(intent))
+                this.pending.delete(intent);
+        for (const intent of remaining)
+            this.pending.add(intent);
+        this.intents.set(runId, state.intents);
+        this.state = state;
+    }
+    finish() {
+        return {
+            ...this.state,
+            runs: this.runs,
+            commands: this.commands,
+            details: this.details,
+            gates: this.gates,
+            effects: { ...this.state.effects, budgets: this.budgets },
+            intents: [...this.pending],
+        };
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { Evidence } from "./operations.ts";
+import { type AuthorityState, type EffectIntent } from "./reducer.ts";
+export interface OutboxEntry extends EffectIntent {
+    readonly createdSequence: number;
+    readonly releasedSequence: number | null;
+}
+export interface History {
+    readonly state: AuthorityState;
+    readonly outbox: readonly OutboxEntry[];
+    readonly runSequences: Readonly<Record<string, number>>;
+    readonly evidence: readonly Evidence[];
+}
+export declare function rebuildHistory(events: readonly unknown[]): History;

package/dist/src/authority/history.js

@@ -0,0 +1,37 @@
+import { HistoryState } from "./history-state.js";
+import { applyEvent, } from "./reducer.js";
+export function rebuildHistory(events) {
+    const replay = new HistoryState();
+    const created = [];
+    const released = new Map();
+    const runSequences = {};
+    const evidence = [];
+    for (const [index, value] of events.entries()) {
+        const state = replay.scope(value);
+        const applied = applyEvent(state, { value, index });
+        const before = new Set(state.intents.map((intent) => intent.operationId));
+        const after = new Set(applied.state.intents.map((intent) => intent.operationId));
+        for (const intent of applied.state.intents)
+            if (!before.has(intent.operationId))
+                created.push({
+                    ...intent,
+                    createdSequence: applied.event.sequence,
+                    releasedSequence: null,
+                });
+        for (const operationId of before)
+            if (!after.has(operationId))
+                released.set(operationId, applied.event.sequence);
+        runSequences[applied.event.runId] = applied.event.sequence;
+        evidence.push(...applied.evidence);
+        replay.record(applied.state, applied.event.runId);
+    }
+    return {
+        state: replay.finish(),
+        outbox: created.map((entry) => ({
+            ...entry,
+            releasedSequence: released.get(entry.operationId) ?? null,
+        })),
+        runSequences,
+        evidence,
+    };
+}

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

@@ -0,0 +1,3 @@
+export declare function isInstant(value: unknown): value is string;
+export declare function notBefore(value: string, bound: string): boolean;
+export declare function isAfter(value: string, bound: string): boolean;