cloving 0.3.19 → 1.0.1

package/dist/src/broker/actor/delivery-intents.d.ts

@@ -0,0 +1,68 @@
+import { type GateState } from "../../authority/gates.ts";
+import { type AuthorityState, type EffectIntent } from "../../authority/reducer.ts";
+import type { ExecutionManifest } from "../../workflow-admission.ts";
+export interface DeliveryDecision {
+    readonly gateId: string;
+    readonly decision: string;
+    readonly answer: string | null;
+}
+export type Purpose = "dispatch" | "reconcile" | "stop";
+export interface EffectArguments {
+    readonly leaseGeneration: number;
+    readonly capability: string;
+    readonly method: string;
+    readonly target: string;
+    readonly payload: string;
+}
+export interface DeliveryIntent extends EffectIntent, Partial<DeliveryDecision>, Partial<EffectArguments> {
+    readonly workflow: string;
+    readonly inputDigest: string;
+    readonly purpose: Purpose;
+}
+export type ProtectedIntent = DeliveryIntent & EffectArguments;
+export type Undigested = Omit<DeliveryIntent, "inputDigest" | "purpose">;
+export type Reconciliation = {
+    readonly kind: "accepted";
+    readonly receipt: string;
+    readonly worker?: string;
+} | {
+    readonly kind: "absent";
+};
+export type AdapterOutcome = Reconciliation | {
+    readonly kind: "completed";
+    readonly receipt: string;
+    readonly worker?: string;
+    readonly result: string;
+} | {
+    readonly kind: "failed";
+    readonly receipt?: string;
+    readonly reason: string;
+    readonly result?: string;
+} | {
+    readonly kind: "stopped";
+    readonly receipt?: string;
+} | {
+    readonly kind: "unknown";
+    readonly evidence?: string;
+};
+export interface Delivery {
+    readonly deliver: (intent: DeliveryIntent, signal: AbortSignal) => Promise<{
+        readonly receipt: string;
+        readonly worker?: string;
+    } | AdapterOutcome>;
+    readonly reconcile: (intent: DeliveryIntent, signal: AbortSignal) => Promise<AdapterOutcome>;
+    readonly stop?: (intent: DeliveryIntent, signal: AbortSignal) => Promise<AdapterOutcome>;
+}
+export type AvailableManifest = (pinned: ExecutionManifest) => ExecutionManifest | undefined;
+export declare function intentDigest(intent: Undigested): string;
+export declare function deliveryIntent(intent: Undigested): DeliveryIntent;
+export declare function protectedIntent(state: AuthorityState, attempt: {
+    readonly intent: EffectIntent;
+    readonly purpose: Purpose;
+}): readonly DeliveryIntent[];
+export declare function gateDecision(gate: GateState | undefined): DeliveryDecision | null;
+export declare function observingIntent(state: AuthorityState, attempt: {
+    readonly intent: EffectIntent;
+    readonly purpose: Purpose;
+}): DeliveryIntent;
+export declare function stageable(state: AuthorityState, held: ReadonlySet<string>): readonly DeliveryIntent[];

package/dist/src/broker/actor/delivery-intents.js

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+import { continues, isSettled } from "../../authority/gates.js";
+import { eligibleIntents, } from "../../authority/reducer.js";
+import { gateContinuation } from "../../authority/reduction.js";
+export function intentDigest(intent) {
+    const base = [intent.kind, intent.runId, intent.operationId, intent.workflow];
+    const bound = intent.gateId === undefined
+        ? base
+        : [
+            ...base,
+            intent.gateId,
+            intent.decision ?? null,
+            intent.answer ?? null,
+        ];
+    return createHash("sha256").update(JSON.stringify(bound)).digest("hex");
+}
+export function deliveryIntent(intent) {
+    return { ...intent, purpose: "dispatch", inputDigest: intentDigest(intent) };
+}
+export function protectedIntent(state, attempt) {
+    const { intent, purpose } = attempt;
+    const workflow = workflowOf(state, intent.runId);
+    return Object.values(state.effects.operations)
+        .filter((operation) => operation.operationId === intent.operationId)
+        .flatMap((operation) => Object.values(state.effects.leases)
+        .filter((lease) => lease.resourceKey === operation.leaseKey)
+        .map((lease) => ({
+        ...intent,
+        workflow,
+        purpose,
+        inputDigest: operation.inputDigest,
+        leaseGeneration: lease.generation,
+        capability: operation.capability,
+        method: operation.method,
+        target: operation.target,
+        payload: operation.payload,
+    })));
+}
+export function gateDecision(gate) {
+    if (gate === undefined || gate.kind === "untyped" || !continues(gate))
+        return null;
+    return {
+        gateId: gate.gateId,
+        decision: gate.outcome.decision,
+        answer: gate.outcome.answer,
+    };
+}
+function workflowOf(state, runId) {
+    return state.runs[runId]?.workflow ?? "";
+}
+function decisionOf(state, intent) {
+    return gateDecision(Object.values(state.gates).find((gate) => gate.runId === intent.runId &&
+        isSettled(gate) &&
+        gateContinuation(gate).operationId === intent.operationId));
+}
+export function observingIntent(state, attempt) {
+    const { intent, purpose } = attempt;
+    const undigested = {
+        ...intent,
+        workflow: workflowOf(state, intent.runId),
+        ...decisionOf(state, intent),
+    };
+    return { ...undigested, purpose, inputDigest: intentDigest(undigested) };
+}
+export function stageable(state, held) {
+    return eligibleIntents(state)
+        .filter((intent) => !held.has(intent.operationId))
+        .flatMap((intent) => intent.kind === "protected-effect"
+        ? protectedIntent(state, { intent, purpose: "dispatch" })
+        : [
+            deliveryIntent({
+                ...intent,
+                workflow: workflowOf(state, intent.runId),
+                ...decisionOf(state, intent),
+            }),
+        ]);
+}

package/dist/src/broker/actor/delivery-plan.d.ts

@@ -0,0 +1,2 @@
+import type { DeliveryPlanning, TurnPlan } from "./turn-staging.ts";
+export declare function planDelivery(planning: DeliveryPlanning): TurnPlan;

package/dist/src/broker/actor/delivery-plan.js

@@ -0,0 +1,109 @@
+import { execute } from "../../authority/reducer.js";
+import { operationDigest } from "../operation-digest.js";
+import { followUps, outcomeCommand, resultDocuments } from "./effect-plan.js";
+import { draft, merged, unchanged, } from "./turn-draft.js";
+import { followUp, openAttempts, staged } from "./turn-staging.js";
+function closedAs(outcome) {
+    return outcome === "thrown" ? "failed" : outcome;
+}
+function heldAfter(closing, result) {
+    const { turn, delivery, outcome } = closing;
+    const settled = result !== undefined || closing.retried;
+    if (!settled && quiet.includes(outcome))
+        return turn.held;
+    return new Set([...turn.held].filter((operation) => operation !== delivery.operationId));
+}
+function blockedAfter(closing) {
+    const { turn, delivery, outcome } = closing;
+    if (outcome !== "blocked")
+        return turn.blocked;
+    return new Map([...turn.blocked, [delivery.operationId, delivery.effectId]]);
+}
+function closedDraft(closing, result) {
+    const { turn, delivery, outcome } = closing;
+    const closed = [
+        {
+            effect_id: delivery.effectId,
+            outcome: closedAs(outcome),
+            receipt: delivery.receipt,
+        },
+    ];
+    if (result === undefined)
+        return unchanged(turn.state, closed);
+    return draft(result, {
+        before: turn.state,
+        definitions: [],
+        closed,
+        documents: resultDocuments(delivery),
+    });
+}
+export function planDelivery(planning) {
+    const { turn, delivery, epoch } = planning;
+    const outcome = delivery.epoch === epoch ? delivery.outcome : "stale-epoch";
+    const closing = {
+        turn,
+        delivery,
+        outcome,
+        retried: retriable.includes(outcome) &&
+            delivery.intent !== "protected-effect" &&
+            delivery.attempts < planning.effects.deliveryAttempts,
+    };
+    const result = recorded(turn.state, { ...delivery, outcome });
+    const base = result?.state ?? turn.state;
+    const steps = followUps(base, {
+        recordedAt: delivery.recordedAt,
+        effects: planning.effects,
+        blocked: blockedAfter(closing),
+    });
+    return {
+        kind: "commit",
+        receipt: { kind: outcome },
+        change: merged(closedDraft(closing, result), steps.map(followUp)),
+        stage: staged(steps.at(-1)?.result.state ?? base, {
+            held: heldAfter(closing, result),
+            results: [
+                ...(result === undefined ? [] : [result]),
+                ...steps.map((step) => step.result),
+            ],
+            closed: [delivery.operationId],
+            open: openAttempts(turn, [delivery.operationId]),
+            stop: {
+                ...planning,
+                rows: [{ effectId: delivery.effectId, outcome: closedAs(outcome) }],
+            },
+        }),
+    };
+}
+const quiet = ["thrown", "failed", "blocked"];
+const retriable = ["thrown", "failed"];
+function recorded(state, delivery) {
+    const command = delivery.intent === "protected-effect"
+        ? outcomeCommand({
+            ...delivery,
+            storedReceipt: state.effects.operations[delivery.operationId]?.receipt ?? null,
+        })
+        : dispatchCommand(delivery);
+    if (command === undefined)
+        return undefined;
+    const result = execute(state, { command, recordedAt: delivery.recordedAt });
+    return result.kind === "accepted" ? result : undefined;
+}
+const runCommands = {
+    sent: (delivery) => ({
+        kind: "record-dispatch",
+        commandId: `dispatch:${operationDigest(delivery.operationId)}`,
+        runId: delivery.runId,
+        operationId: delivery.operationId,
+        receipt: delivery.receipt,
+    }),
+    stopped: (delivery) => ({
+        kind: "record-outcome",
+        commandId: `outcome:${delivery.effectId}`,
+        runId: delivery.runId,
+        operationId: delivery.operationId,
+        outcome: "stopped",
+    }),
+};
+function dispatchCommand(delivery) {
+    return runCommands[delivery.outcome]?.(delivery);
+}

package/dist/src/broker/actor/delivery-results.d.ts

@@ -0,0 +1,11 @@
+import type { JsonObject } from "solid-objects";
+import type { DeliveryResult } from "./turn-plan.ts";
+export type Outcome = Omit<DeliveryResult, "runId" | "intent" | "leaseGeneration" | "purpose" | "attempts"> & {
+    readonly inputDigest: string;
+};
+export interface Present {
+    readonly epoch: number;
+    readonly recordedAt: string;
+}
+export declare function thrownOutcome(payload: JsonObject, present: Present): Outcome;
+export declare function completedOutcome(payload: JsonObject, present: Present): Outcome;

package/dist/src/broker/actor/delivery-results.js

@@ -0,0 +1,63 @@
+import { integer, optionalText, text } from "../../storage/domain-rows.js";
+function stated(result, name) {
+    const value = Reflect.get(Object(result), name);
+    return typeof value === "string" ? value : null;
+}
+const resultKinds = [
+    "sent",
+    "withheld",
+    "blocked",
+    "accepted",
+    "refused",
+    "completed",
+    "failed",
+    "stopped",
+    "unknown",
+    "absent",
+];
+function resultKind(kind) {
+    const known = resultKinds.find((candidate) => candidate === kind);
+    if (known === undefined)
+        throw new Error(`invalid-delivery-result: ${kind}`);
+    return known;
+}
+function callback(payload) {
+    const intent = payload["arguments"];
+    return {
+        effectId: text(payload, "effectId"),
+        operationId: text(intent, "operationId"),
+        inputDigest: text(intent, "inputDigest"),
+    };
+}
+export function thrownOutcome(payload, present) {
+    return {
+        ...callback(payload),
+        outcome: "thrown",
+        receipt: null,
+        worker: null,
+        result: null,
+        reason: null,
+        ...present,
+    };
+}
+function readOutcome(payload) {
+    const result = payload["result"];
+    return {
+        ...callback(payload),
+        outcome: resultKind(text(result, "kind")),
+        receipt: optionalText(result, "receipt"),
+        worker: stated(result, "worker"),
+        result: stated(result, "result"),
+        reason: stated(result, "reason"),
+        epoch: integer(result, "epoch"),
+        recordedAt: text(result, "recordedAt"),
+    };
+}
+export function completedOutcome(payload, present) {
+    try {
+        return readOutcome(payload);
+    }
+    catch {
+        return thrownOutcome(payload, present);
+    }
+}

package/dist/src/broker/actor/effect-delivery.d.ts

@@ -0,0 +1,19 @@
+import type { Database, JsonObject } from "solid-objects";
+import type { AdapterCalls } from "./adapter-calls.ts";
+import type { EffectSettings } from "./authority-settings.ts";
+import type { AvailableManifest, Delivery, EffectArguments, ProtectedIntent } from "./delivery-intents.ts";
+export interface EffectDelivery {
+    readonly reader: Database;
+    readonly delivery: Delivery;
+    readonly available: AvailableManifest | undefined;
+    readonly epoch: () => number;
+    readonly clock: () => string;
+    readonly calls: AdapterCalls;
+    readonly effects: EffectSettings;
+}
+export interface Attempt {
+    readonly intent: ProtectedIntent;
+    readonly effectId: string;
+}
+export declare function deliverEffect(parts: EffectDelivery, attempt: Attempt): Promise<JsonObject>;
+export declare function protectedArguments(value: JsonObject): EffectArguments;

package/dist/src/broker/actor/effect-delivery.js

@@ -0,0 +1,118 @@
+import { dispatchDecision, } from "../../authority/dispatch-decision.js";
+import { integer, optionalInteger, optionalText, text, } from "../../storage/domain-rows.js";
+import { budgetRow } from "../../storage/effect-rows.js";
+import { effectInputDigest, storedBudget } from "../effect-restore.js";
+import { settlement } from "./adapter-outcomes.js";
+import { pinned } from "./pin-check.js";
+const absent = {
+    attempt: undefined,
+    released: false,
+    runStatus: "",
+    workflow: "",
+    pinned: false,
+    operation: undefined,
+    lease: undefined,
+    budget: undefined,
+};
+async function dispatchRead(connection, attempt) {
+    const row = await connection.get("SELECT d.outcome, d.input_digest, a.lease_generation, o.released_sequence, r.status, r.workflow, p.status AS operation_status, p.capability, p.units, l.operation_id AS lease_owner, l.generation, l.expires_at, l.state AS lease_state, b.run_id, b.effect_limit, b.spent, b.capabilities, b.exhausted_sequence FROM deliveries d JOIN outbox o ON o.operation_id = d.operation_id JOIN runs r ON r.run_id = o.run_id JOIN dispatch_attempts a ON a.effect_id = d.effect_id JOIN operations p ON p.operation_id = d.operation_id JOIN leases l ON l.resource_key = p.lease_key JOIN run_budgets b ON b.run_id = o.run_id WHERE d.effect_id = ? AND d.operation_id = ?", [attempt.effectId, attempt.intent.operationId]);
+    if (row === undefined)
+        return absent;
+    const workflow = text(row, "workflow");
+    return {
+        attempt: {
+            outcome: optionalText(row, "outcome"),
+            inputDigest: text(row, "input_digest"),
+            leaseGeneration: optionalInteger(row, "lease_generation"),
+        },
+        released: optionalInteger(row, "released_sequence") !== null,
+        runStatus: text(row, "status"),
+        workflow,
+        pinned: await pinned(connection, {
+            workflow,
+            available: attempt.available,
+        }),
+        operation: {
+            status: text(row, "operation_status"),
+            capability: text(row, "capability"),
+            units: integer(row, "units"),
+        },
+        budget: storedBudget(budgetRow(row)),
+        lease: {
+            operationId: text(row, "lease_owner"),
+            generation: integer(row, "generation"),
+            expiresAt: text(row, "expires_at"),
+            state: text(row, "lease_state"),
+        },
+    };
+}
+async function called(parts, call) {
+    const { intent, name } = call;
+    const adapterCall = parts.delivery[name]?.bind(parts.delivery);
+    if (adapterCall === undefined)
+        return { kind: "unknown", reason: "stop-not-supported" };
+    return settlement(await parts.calls.call(intent.operationId, (signal) => adapterCall(intent, signal)), parts.effects.resultBytes);
+}
+const confirmations = ["stopped", "completed", "failed"];
+async function stopRequested(parts, intent) {
+    const stopped = await called(parts, { intent, name: "stop" });
+    return confirmations.includes(stopped.kind)
+        ? stopped
+        : called(parts, { intent, name: "reconcile" });
+}
+function decided(parts, attempt) {
+    const { intent } = attempt;
+    const now = parts.clock();
+    return parts.reader.connection(async (connection) => dispatchDecision(await dispatchRead(connection, {
+        ...attempt,
+        available: parts.available,
+    }), {
+        intent: { ...intent, computedDigest: effectInputDigest(intent) },
+        now,
+    }));
+}
+const withheld = { kind: "withheld" };
+function unsent(decision) {
+    return decision === "stale" ? withheld : { kind: decision };
+}
+async function attempted(parts, attempt) {
+    const { intent } = attempt;
+    const first = await decided(parts, attempt);
+    if (first === "stale")
+        return withheld;
+    if (intent.purpose === "stop")
+        return stopRequested(parts, intent);
+    const known = await called(parts, { intent, name: "reconcile" });
+    if (known.kind !== "absent" || intent.purpose === "reconcile")
+        return known;
+    if (first !== "send")
+        return unsent(first);
+    const second = await decided(parts, attempt);
+    if (second !== "send")
+        return unsent(second);
+    const sent = await called(parts, { intent, name: "deliver" });
+    return sent.kind === "absent"
+        ? { kind: "unknown", reason: "invalid-adapter-reply" }
+        : sent;
+}
+export async function deliverEffect(parts, attempt) {
+    const result = await attempted(parts, attempt);
+    return {
+        receipt: null,
+        worker: null,
+        result: null,
+        reason: null,
+        ...result,
+        epoch: parts.epoch(),
+        recordedAt: parts.clock(),
+    };
+}
+export function protectedArguments(value) {
+    return {
+        leaseGeneration: integer(value, "leaseGeneration"),
+        capability: text(value, "capability"),
+        method: text(value, "method"),
+        target: text(value, "target"),
+        payload: text(value, "payload"),
+    };
+}

package/dist/src/broker/actor/effect-plan.d.ts

@@ -0,0 +1,41 @@
+import { type AuthorityState } from "../../authority/reducer.ts";
+import type { EffectSettings } from "./authority-settings.ts";
+import { type DeliveryIntent } from "./delivery-intents.ts";
+import type { Accepted } from "./turn-draft.ts";
+export interface Step {
+    readonly result: Accepted;
+    readonly before: AuthorityState;
+}
+export interface Promotion {
+    readonly recordedAt: string;
+    readonly effects: EffectSettings;
+}
+type Fields = Readonly<Record<string, unknown>>;
+export declare function promoted(state: AuthorityState, promotion: Promotion): readonly Step[];
+export interface FollowUp extends Promotion {
+    readonly blocked: ReadonlyMap<string, string>;
+}
+export declare function followUps(state: AuthorityState, followUp: FollowUp): readonly Step[];
+export interface ClosedAttempt {
+    readonly effectId: string;
+    readonly operationId: string;
+    readonly runId: string;
+    readonly leaseGeneration: number | null;
+    readonly purpose: string;
+    readonly outcome: string;
+    readonly receipt: string | null;
+    readonly worker: string | null;
+    readonly result: string | null;
+    readonly reason: string | null;
+    readonly storedReceipt: string | null;
+}
+export declare function outcomeCommand(attempt: ClosedAttempt): Fields | undefined;
+export declare function resultDocuments(attempt: Pick<ClosedAttempt, "outcome" | "result">): readonly Fields[];
+export interface Reconciling {
+    readonly results: readonly Accepted[];
+    readonly closed: readonly string[];
+    readonly open: ReadonlySet<string>;
+}
+export declare function rejectedReports(results: readonly Accepted[]): ReadonlySet<string>;
+export declare function reconciliations(state: AuthorityState, reconciling: Reconciling): readonly DeliveryIntent[];
+export {};