cloving 0.3.19 → 1.0.1

package/dist/src/broker/actor/turn-draft.js

@@ -0,0 +1,138 @@
+import { evidenceOf } from "../../authority/operations.js";
+import { detailRecord, gateRecord } from "../decision-restore.js";
+import { effectRows } from "../effect-restore.js";
+const unchangedEffects = {
+    budgets: [],
+    operations: [],
+    leases: [],
+    evidence: [],
+    stops: [],
+};
+export function unchanged(state, closed) {
+    return unchangedAt(state.sequence, closed);
+}
+export function unchangedAt(sequence, closed) {
+    return {
+        previous: sequence,
+        sequence,
+        definitions: [],
+        events: [],
+        runs: [],
+        commands: [],
+        added: [],
+        released: [],
+        closed,
+        gates: [],
+        details: [],
+        documents: [],
+        ...unchangedEffects,
+    };
+}
+function columns(row) {
+    return Object.fromEntries(Object.entries(row).map(([name, value]) => [
+        name.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`),
+        value,
+    ]));
+}
+function changedEntries(after, before) {
+    return Object.fromEntries(Object.entries(after).filter(([key, value]) => before[key] !== value));
+}
+function changed(after, before) {
+    return Object.values(changedEntries(after, before));
+}
+function effectDraft(result, before) {
+    const { effects } = result.state;
+    const rows = effectRows({
+        budgets: changedEntries(effects.budgets, before.effects.budgets),
+        operations: changedEntries(effects.operations, before.effects.operations),
+        leases: changedEntries(effects.leases, before.effects.leases),
+        stops: changedEntries(effects.stops, before.effects.stops),
+        holding: effects.holding,
+    }, result.events.flatMap((event) => evidenceOf(event, result.disposition)));
+    return {
+        budgets: rows.budgets.map(columns),
+        operations: rows.operations.map(columns),
+        leases: rows.leases.map(columns),
+        evidence: rows.evidence.map(columns),
+        stops: rows.stops.map(columns),
+    };
+}
+function eventRecord(event) {
+    return {
+        sequence: event.sequence,
+        type: event.type,
+        run_id: event.runId,
+        command_id: event.commandId,
+        recorded_at: event.recordedAt,
+        request: event.request,
+        payload: JSON.stringify(event.payload),
+    };
+}
+export function draft(result, extra) {
+    const { state, events, intents } = result;
+    const { before, definitions, closed, documents } = extra;
+    const touched = new Set(events.map((event) => event.runId));
+    const retained = new Set(state.intents.map((intent) => intent.operationId));
+    return {
+        definitions,
+        closed,
+        documents,
+        ...effectDraft(result, before),
+        gates: changed(state.gates, before.gates).map((gate) => columns(gateRecord(gate))),
+        details: changed(state.details, before.details).map((details) => columns(detailRecord(details))),
+        previous: before.sequence,
+        sequence: state.sequence,
+        events: events.map(eventRecord),
+        runs: Object.values(state.runs)
+            .filter((run) => touched.has(run.runId))
+            .map((run) => ({
+            run_id: run.runId,
+            status: run.status,
+            revision: run.revision,
+            workflow: run.workflow,
+            paused_from: run.pausedFrom,
+            gates: JSON.stringify(run.gates),
+            sequence: state.sequence,
+        })),
+        commands: events.map((event) => ({
+            command_id: event.commandId,
+            request: event.request,
+            sequence: event.sequence,
+        })),
+        added: intents.map((intent) => ({
+            operation_id: intent.operationId,
+            kind: intent.kind,
+            run_id: intent.runId,
+            created_sequence: state.sequence,
+        })),
+        released: before.intents
+            .filter((intent) => !retained.has(intent.operationId))
+            .map((intent) => ({
+            operation_id: intent.operationId,
+            released_sequence: state.sequence,
+        })),
+    };
+}
+export function merged(first, later) {
+    const drafts = [first, ...later];
+    const joined = (name) => drafts.flatMap((draft) => draft[name]);
+    return {
+        previous: first.previous,
+        sequence: later.at(-1)?.sequence ?? first.sequence,
+        definitions: joined("definitions"),
+        events: joined("events"),
+        runs: joined("runs"),
+        commands: joined("commands"),
+        added: joined("added"),
+        released: joined("released"),
+        closed: joined("closed"),
+        gates: joined("gates"),
+        details: joined("details"),
+        documents: joined("documents"),
+        budgets: joined("budgets"),
+        operations: joined("operations"),
+        leases: joined("leases"),
+        evidence: joined("evidence"),
+        stops: joined("stops"),
+    };
+}

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

@@ -0,0 +1,17 @@
+import type { AuthorityCommand } from "../../authority/transitions.ts";
+import type { PlanSettings } from "./authority-settings.ts";
+import { type DeliveryIntent } from "./delivery-intents.ts";
+import type { CommandPlanning, TurnPlan, TurnState } from "./turn-staging.ts";
+export { planDelivery } from "./delivery-plan.ts";
+export type { DeliveryIntent } from "./delivery-intents.ts";
+export type { ChangeDraft, Row } from "./turn-draft.ts";
+export type { CommandPlanning, DeliveryPlanning, DeliveryResult, Document, TurnPlan, TurnRequest, TurnState, } from "./turn-staging.ts";
+export declare function planCommand(planning: CommandPlanning): TurnPlan;
+export declare function documentReferences(command: AuthorityCommand | null): readonly string[];
+export declare function planAdoption(sequence: number): TurnPlan;
+export declare function planRecovery(recovery: {
+    readonly turn: TurnState;
+    readonly intents: readonly DeliveryIntent[];
+    readonly effects: PlanSettings;
+    readonly recordedAt: string;
+}): TurnPlan;

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

@@ -0,0 +1,136 @@
+import { parseCommand } from "../../authority/commands.js";
+import { execute } from "../../authority/reducer.js";
+import { admitted } from "../authority-admission.js";
+import { stageable } from "./delivery-intents.js";
+import { followUps } from "./effect-plan.js";
+import { draft, merged, unchangedAt } from "./turn-draft.js";
+import { refusalOf } from "./turn-refusals.js";
+import { followUp, openAttempts, staged } from "./turn-staging.js";
+export { planDelivery } from "./delivery-plan.js";
+export function planCommand(planning) {
+    const { turn, request } = planning;
+    const refusal = freshRefusal(planning);
+    if (refusal !== undefined)
+        return answer(refusal);
+    const admission = admitted(turn.state, {
+        definitions: turn.definitions,
+        command: request.command,
+        manifest: request.manifest,
+    });
+    if (admission.kind === "rejected")
+        return answer(admission);
+    const missing = missingDocument(planning);
+    if (missing !== undefined)
+        return answer({
+            kind: "rejected",
+            reason: "missing-document",
+            detail: missing,
+        });
+    const result = execute(turn.state, request);
+    if (result.kind === "duplicate")
+        return answer({ ...result, intents: turn.created });
+    if (result.kind === "rejected")
+        return answer(result);
+    const grants = followUps(result.state, {
+        recordedAt: request.recordedAt,
+        effects: planning.effects,
+        blocked: turn.blocked,
+    });
+    return {
+        kind: "commit",
+        receipt: {
+            kind: "accepted",
+            sequence: result.state.sequence,
+            intents: result.intents,
+            ...(result.disposition === undefined
+                ? {}
+                : { disposition: result.disposition.disposition }),
+        },
+        change: merged(draft(result, {
+            before: turn.state,
+            definitions: [...admission.definitions].map(([pin, manifest]) => ({
+                pin,
+                manifest: JSON.stringify(manifest),
+            })),
+            closed: [],
+            documents: referencedDocuments(request),
+        }), grants.map(followUp)),
+        stage: staged(grants.at(-1)?.result.state ?? result.state, {
+            held: turn.held,
+            results: [result, ...grants.map((step) => step.result)],
+            closed: [],
+            open: openAttempts(turn, []),
+            stop: { ...planning, rows: [] },
+        }),
+    };
+}
+const documentFields = [
+    "submission",
+    "input",
+    "prompt",
+    "answer",
+    "payload",
+    "result",
+];
+export function documentReferences(command) {
+    if (command === null)
+        return [];
+    return documentFields
+        .map((name) => command[name])
+        .filter((digest) => digest !== undefined);
+}
+function referencedDocuments(request) {
+    const references = documentReferences(parseCommand(request.command));
+    return (request.documents ?? [])
+        .filter((document) => references.includes(document.digest))
+        .map((document) => ({ digest: document.digest, body: document.body }));
+}
+function missingDocument(planning) {
+    const { turn, request } = planning;
+    const command = parseCommand(request.command);
+    if (command === null || turn.state.commands[command.commandId] !== undefined)
+        return undefined;
+    const given = new Set((request.documents ?? []).map((document) => document.digest));
+    return documentReferences(command).find((digest) => !given.has(digest) && !turn.documents.has(digest));
+}
+function freshRefusal(planning) {
+    const { turn, request, epoch } = planning;
+    const command = parseCommand(request.command);
+    if (command === null || turn.state.commands[command.commandId] !== undefined)
+        return undefined;
+    const reason = refusalOf({
+        command,
+        recordedAt: request.recordedAt,
+        given: request.epoch,
+        epoch,
+    });
+    return reason === undefined ? undefined : { kind: "rejected", reason };
+}
+export function planAdoption(sequence) {
+    return {
+        kind: "commit",
+        receipt: { kind: "adopted", sequence },
+        change: { ...unchangedAt(sequence, []), completes_adoption: true },
+        stage: [],
+    };
+}
+export function planRecovery(recovery) {
+    const { turn, intents } = recovery;
+    const grants = followUps(turn.state, { ...recovery, blocked: new Map() });
+    const stage = [
+        ...intents,
+        ...stageable(grants.at(-1)?.result.state ?? turn.state, new Set(intents.map((intent) => intent.operationId))),
+    ];
+    const receipt = { kind: "recovered", staged: stage.length };
+    if (stage.length === 0 && grants.length === 0)
+        return answer(receipt);
+    return {
+        kind: "commit",
+        receipt,
+        change: merged(unchangedAt(turn.state.sequence, []), grants.map(followUp)),
+        stage,
+    };
+}
+function answer(receipt) {
+    return { kind: "answer", receipt };
+}

package/dist/src/broker/actor/turn-refusals.d.ts

@@ -0,0 +1,8 @@
+import type { AuthorityCommand } from "../../authority/transitions.ts";
+export interface Fresh {
+    readonly command: AuthorityCommand;
+    readonly recordedAt: string;
+    readonly given: number | undefined;
+    readonly epoch: number;
+}
+export declare function refusalOf(fresh: Fresh): string | undefined;

package/dist/src/broker/actor/turn-refusals.js

@@ -0,0 +1,35 @@
+import { isInstant } from "../../authority/instants.js";
+import { operationDigest } from "../operation-digest.js";
+const expiryPrefix = "expire-lease:";
+function scanned(command) {
+    const expiry = command.kind === "expire-lease";
+    if (!expiry)
+        return !command.commandId.startsWith(expiryPrefix);
+    const digest = operationDigest(String(command.operationId));
+    const generation = String(command.leaseGeneration);
+    return command.commandId === `${expiryPrefix}${digest}:${generation}`;
+}
+const planKinds = ["record-dispatch", "grant-lease", "record-outcome"];
+const planPrefixes = ["lease:", "outcome:", "dispatch:"];
+const workerKinds = ["request-effect", "report-effect"];
+const timedKinds = [...workerKinds, "expire-lease"];
+const rules = [
+    ["stale-epoch", ({ given, epoch }) => given !== undefined && given !== epoch],
+    [
+        "delivery-owned-command",
+        ({ command }) => planKinds.includes(command.kind) ||
+            planPrefixes.some((prefix) => command.commandId.startsWith(prefix)),
+    ],
+    ["delivery-owned-command", ({ command }) => !scanned(command)],
+    [
+        "missing-epoch",
+        ({ command, given }) => workerKinds.includes(command.kind) && given === undefined,
+    ],
+    [
+        "invalid-recorded-time",
+        ({ command, recordedAt }) => timedKinds.includes(command.kind) && !isInstant(recordedAt),
+    ],
+];
+export function refusalOf(fresh) {
+    return rules.find(([, applies]) => applies(fresh))?.[0];
+}

package/dist/src/broker/actor/turn-staging.d.ts

@@ -0,0 +1,78 @@
+import type { AuthorityState, EffectIntent } from "../../authority/reducer.ts";
+import type { ExecutionManifest } from "../../workflow-admission.ts";
+import type { Definitions } from "../authority-admission.ts";
+import type { PlanSettings } from "./authority-settings.ts";
+import { type DeliveryIntent } from "./delivery-intents.ts";
+import { type Reconciling, type Step } from "./effect-plan.ts";
+import { type ClosedRow } from "./stop-plan.ts";
+import type { Stopping } from "./stop-turn.ts";
+import { type ChangeDraft, type Row } from "./turn-draft.ts";
+export interface TurnState {
+    readonly state: AuthorityState;
+    readonly definitions: Definitions;
+    readonly held: ReadonlySet<string>;
+    readonly blocked: ReadonlyMap<string, string>;
+    readonly stopping: Stopping;
+    readonly runId: string;
+    readonly created: readonly EffectIntent[];
+    readonly documents: ReadonlySet<string>;
+}
+export interface Document {
+    readonly digest: string;
+    readonly body: string;
+}
+export interface TurnRequest {
+    readonly command: unknown;
+    readonly recordedAt: string;
+    readonly manifest?: ExecutionManifest;
+    readonly epoch?: number;
+    readonly documents?: readonly Document[];
+}
+export type TurnPlan = {
+    readonly kind: "answer";
+    readonly receipt: Row;
+} | {
+    readonly kind: "commit";
+    readonly receipt: Row;
+    readonly change: ChangeDraft;
+    readonly stage: readonly DeliveryIntent[];
+};
+export interface DeliveryResult {
+    readonly effectId: string;
+    readonly operationId: string;
+    readonly runId: string;
+    readonly intent: EffectIntent["kind"];
+    readonly leaseGeneration: number | null;
+    readonly purpose: string;
+    readonly attempts: number;
+    readonly outcome: "sent" | "withheld" | "blocked" | "thrown" | "failed" | "accepted" | "refused" | "completed" | "stopped" | "unknown" | "absent";
+    readonly receipt: string | null;
+    readonly worker: string | null;
+    readonly result: string | null;
+    readonly reason: string | null;
+    readonly epoch: number;
+    readonly recordedAt: string;
+}
+export interface CommandPlanning {
+    readonly turn: TurnState;
+    readonly request: TurnRequest;
+    readonly epoch: number;
+    readonly effects: PlanSettings;
+}
+export interface DeliveryPlanning {
+    readonly turn: TurnState;
+    readonly delivery: DeliveryResult;
+    readonly epoch: number;
+    readonly effects: PlanSettings;
+}
+export declare function openAttempts(turn: TurnState, closed: readonly string[]): ReadonlySet<string>;
+export interface Staging extends Reconciling {
+    readonly held: ReadonlySet<string>;
+    readonly stop: {
+        readonly turn: TurnState;
+        readonly effects: PlanSettings;
+        readonly rows: readonly ClosedRow[];
+    };
+}
+export declare function staged(state: AuthorityState, staging: Staging): readonly DeliveryIntent[];
+export declare function followUp(step: Step): ChangeDraft;

package/dist/src/broker/actor/turn-staging.js

@@ -0,0 +1,34 @@
+import { stageable } from "./delivery-intents.js";
+import { reconciliations, rejectedReports, } from "./effect-plan.js";
+import { stopIntents } from "./stop-plan.js";
+import { draft } from "./turn-draft.js";
+export function openAttempts(turn, closed) {
+    return new Set([...turn.held].filter((operation) => !turn.blocked.has(operation) && !closed.includes(operation)));
+}
+export function staged(state, staging) {
+    const { turn, effects, rows } = staging.stop;
+    return [
+        ...stageable(state, staging.held),
+        ...reconciliations(state, staging),
+        ...stopIntents(state, {
+            stopping: turn.stopping,
+            runId: turn.runId,
+            closed: rows,
+            cancelledNow: staging.results.flatMap((result) => result.events
+                .filter((event) => event.type === "run.cancelled")
+                .map((event) => event.sequence)),
+            stopLimit: effects.stopLimit,
+            stopSupported: effects.stopSupported,
+            opening: false,
+            rejected: rejectedReports(staging.results),
+        }),
+    ];
+}
+export function followUp(step) {
+    return draft(step.result, {
+        before: step.before,
+        definitions: [],
+        closed: [],
+        documents: [],
+    });
+}

package/dist/src/broker/actor/turn-state.d.ts

@@ -0,0 +1,34 @@
+import type { EffectIntent } from "../../authority/reducer.ts";
+import { type DeliveryRow, type SqlConnection } from "../../storage/domain-rows.ts";
+import { type DeliveryIntent } from "./delivery-intents.ts";
+import { type TurnState } from "./turn-plan.ts";
+export declare function commandTurn(connection: SqlConnection, scope: {
+    readonly command: unknown;
+    readonly sequence: number;
+    readonly capacity: number;
+}): Promise<TurnState>;
+export declare function stopRecoveries(connection: SqlConnection, rule: {
+    readonly capacity: number;
+    readonly stopLimit: number;
+    readonly stopSupported: boolean;
+}): Promise<readonly DeliveryIntent[]>;
+export declare function recoveryTurn(connection: SqlConnection, scope: {
+    readonly sequence: number;
+    readonly capacity: number;
+}): Promise<TurnState>;
+export declare const recoveryBatch = 100;
+export declare function adoptionTurn(connection: SqlConnection): Promise<number>;
+export declare function recoverableIntents(connection: SqlConnection): Promise<readonly DeliveryIntent[]>;
+export interface DeliveryTurn {
+    readonly delivery: DeliveryRow;
+    readonly runId: string;
+    readonly intent: EffectIntent["kind"];
+    readonly leaseGeneration: number | null;
+    readonly purpose: string;
+    readonly turn: TurnState;
+}
+export declare function deliveryTurn(connection: SqlConnection, scope: {
+    readonly effectId: string;
+    readonly sequence: number;
+    readonly capacity: number;
+}): Promise<DeliveryTurn | undefined>;