cloving 0.3.20 → 1.1.0

package/dist/src/service/decision-handler.js

@@ -0,0 +1,233 @@
+import { continues, gateKey } from "../authority/gates.js";
+import { gateContinuation } from "../authority/reduction.js";
+import { documentDigest } from "../broker/decision-restore.js";
+import { committed, failed, invalidRequest, isIdentifier, publicReceipt, rejection, result, wholeNumber, } from "./replies.js";
+const decisions = {
+    answer: "answered",
+    approve: "approved",
+    deny: "denied",
+};
+const feedbackBytes = 8_000;
+const commands = {
+    question: ["answer"],
+    approval: ["approve", "deny"],
+};
+function decisionId(gate) {
+    return `${gate.runId}/${gate.gateId}`;
+}
+function label(gate) {
+    return gate.label === null ? null : `Q${String(gate.label)}`;
+}
+function typed(state) {
+    return Object.values(state.gates)
+        .filter((gate) => gate.kind !== "untyped")
+        .sort((left, right) => left.openedSequence - right.openedSequence);
+}
+function pending(state) {
+    return typed(state).filter((gate) => gate.outcome === null &&
+        ["waiting_gate", "paused"].includes(state.runs[gate.runId]?.status ?? ""));
+}
+export async function feedbackOf(context, scope) {
+    const denied = Object.values(scope.state.gates)
+        .filter((gate) => gate.runId === scope.runId &&
+        gate.outcome?.decision === "denied" &&
+        gate.outcome.answer !== null)
+        .sort((left, right) => left.openedSequence - right.openedSequence);
+    const shown = [];
+    for (const gate of denied) {
+        const text = await context.authority.queries.document(gate.outcome?.answer ?? "");
+        shown.push({
+            decisionId: `${gate.runId}/${gate.gateId}`,
+            text: text ?? "",
+        });
+    }
+    return shown;
+}
+async function described(context, shown) {
+    const { state, gate } = shown;
+    const { queries } = context.authority;
+    const opened = await queries.eventsAfter({
+        after: gate.openedSequence - 1,
+        limit: 1,
+    });
+    return {
+        decisionId: decisionId(gate),
+        label: label(gate),
+        type: gate.kind,
+        runId: gate.runId,
+        gateId: gate.gateId,
+        prompt: (await queries.document(gate.prompt ?? "")) ?? "",
+        allowed: commands[gate.kind] ?? [],
+        revision: gate.revision,
+        generation: gate.generation,
+        subjectDigest: gate.subject,
+        openedAt: opened.events[0]?.recordedAt ?? "",
+        expiresAt: gate.expiresAt,
+        context: [],
+        feedback: await feedbackOf(context, { state, runId: gate.runId }),
+    };
+}
+export async function questions(context, parameters) {
+    const { runId } = parameters;
+    const state = await context.authority.state();
+    const listed = pending(state).filter((gate) => runId === undefined || gate.runId === runId);
+    const views = [];
+    for (const gate of listed)
+        views.push(await described(context, { state, gate }));
+    return result("decision-list", { decisions: views });
+}
+function referenced(gates, reference) {
+    const matches = [
+        (gate) => decisionId(gate) === reference,
+        (gate) => label(gate) === reference,
+        (gate) => gate.runId === reference,
+    ].map((matcher) => gates.filter(matcher));
+    return matches.find((found) => found.length > 0) ?? [];
+}
+function refusedTarget(code, extra) {
+    return { kind: "refused", reply: failed(code, extra) };
+}
+function target(state, request) {
+    const { reference, command } = request;
+    const open = referenced(pending(state), reference);
+    if (open.length === 0)
+        return refusedTarget(referenced(typed(state), reference).length > 0
+            ? "decision-not-pending"
+            : "unknown-decision", { detail: `No pending decision matches ${reference}.` });
+    const allowing = open.filter((gate) => commands[gate.kind]?.includes(command));
+    const [gate] = allowing;
+    if (gate === undefined)
+        return refusedTarget("decision-not-allowed", {
+            detail: `The decision does not allow the command ${command}.`,
+        });
+    if (allowing.length > 1)
+        return refusedTarget("ambiguous-decision", {
+            detail: "The reference matches more than one pending decision.",
+            candidates: allowing.map(decisionId),
+        });
+    return { kind: "gate", gate };
+}
+function validText(command, text) {
+    const given = typeof text === "string" && text.trim().length > 0;
+    if (command === "answer")
+        return given;
+    if (command === "deny")
+        return given || text === undefined || text === null;
+    return text === undefined || text === null;
+}
+function textLimit(context, command) {
+    return command === "deny"
+        ? { bytes: feedbackBytes, name: "A feedback text" }
+        : { bytes: context.textBytes, name: "An answer" };
+}
+function decisionRequest(parameters) {
+    const { command, reference, expectedRevision, generation } = parameters;
+    const { subjectDigest, commandId } = parameters;
+    const text = parameters["text"] ?? null;
+    if (typeof command !== "string" ||
+        !Object.hasOwn(decisions, command) ||
+        typeof reference !== "string" ||
+        !wholeNumber(expectedRevision, 1) ||
+        !wholeNumber(generation, 1) ||
+        !isIdentifier(subjectDigest) ||
+        !isIdentifier(commandId) ||
+        !validText(command, text))
+        return undefined;
+    return {
+        command,
+        reference,
+        text,
+        expectedRevision,
+        generation,
+        subjectDigest,
+        commandId,
+    };
+}
+async function located(context, request) {
+    const { commandId, text } = request;
+    const limit = textLimit(context, request.command);
+    if (text !== null && Buffer.byteLength(text) > limit.bytes)
+        return refusedTarget("input-too-large", {
+            commandId,
+            detail: `${limit.name} has at most ${String(limit.bytes)} bytes.`,
+        });
+    const existing = await context.authority.queries.receipt(commandId);
+    if (existing === undefined)
+        return target(await context.authority.state(), request);
+    const { gateId } = existing.command;
+    if (existing.command.kind !== "decide-gate" || gateId === undefined)
+        return refusedTarget("conflicting-command", {
+            commandId,
+            detail: "The command ID is known with a different request.",
+        });
+    return { kind: "known", runId: existing.runId, gateId };
+}
+export async function decision(context, parameters) {
+    const request = decisionRequest(parameters);
+    if (request === undefined)
+        return invalidRequest("The decision request is not valid.");
+    const found = await located(context, request);
+    if (found.kind === "refused")
+        return found.reply;
+    const { runId, gateId } = found.kind === "gate" ? found.gate : found;
+    const { commandId, text } = request;
+    const receipt = await context.gateway.execute({
+        principal: "operator",
+        command: {
+            kind: "decide-gate",
+            commandId,
+            runId,
+            gateId,
+            decision: decisions[request.command],
+            expectedRevision: request.expectedRevision,
+            generation: request.generation,
+            subject: request.subjectDigest,
+            ...(text === null ? {} : { answer: documentDigest(text) }),
+        },
+        documents: text === null ? [] : [text],
+    });
+    if (!committed(receipt)) {
+        const state = await context.authority.state();
+        return rejection(receipt, {
+            commandId,
+            runId,
+            currentRevision: state.gates[gateKey(runId, gateId)]?.revision ?? null,
+        });
+    }
+    return recorded(context, {
+        commandId,
+        runId,
+        gateId,
+        replayed: receipt.kind === "duplicate",
+    });
+}
+async function continuationState(context, decided) {
+    const { gate, run } = decided;
+    if (!continues(gate))
+        return "held";
+    const { operationId } = gateContinuation(gate);
+    const operation = (await context.authority.operations()).find((item) => item.operationId === operationId);
+    if (operation?.deliveries.some((delivery) => delivery.outcome === "sent"))
+        return "admitted";
+    const deliverable = operation?.releasedSequence === null && run.status === "running";
+    return deliverable ? "admitted" : "held";
+}
+async function recorded(context, outcome) {
+    const { commandId, runId, gateId } = outcome;
+    const stored = await context.authority.queries.receipt(commandId);
+    const state = await context.authority.state();
+    const gate = state.gates[gateKey(runId, gateId)];
+    const run = state.runs[runId];
+    if (stored === undefined || gate === undefined || run === undefined)
+        return failed("authority-unavailable", { commandId, runId });
+    return result("decision-recorded", {
+        decisionId: decisionId(gate),
+        runId,
+        decision: gate.outcome?.decision ?? null,
+        commandId,
+        replayed: outcome.replayed,
+        receipt: publicReceipt(stored),
+        run: { state: run.status, revision: run.revision },
+        continuation: await continuationState(context, { gate, run }),
+    });
+}

package/dist/src/service/event-handler.d.ts

@@ -0,0 +1,10 @@
+import type { Fields, Reply } from "../protocol.ts";
+import { type ServiceContext } from "./replies.ts";
+export interface Connection {
+    readonly send: (events: readonly Fields[]) => Promise<boolean>;
+    readonly closed: () => boolean;
+}
+export declare function events(context: ServiceContext, request: {
+    readonly parameters: Fields;
+    readonly connection: Connection;
+}): Promise<Reply | undefined>;

package/dist/src/service/event-handler.js

@@ -0,0 +1,70 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { failed, invalidRequest, isIdentifier, result, wholeNumber, } from "./replies.js";
+function cursor(parameters) {
+    const { runId } = parameters;
+    const after = parameters["after"] ?? 0;
+    const limit = parameters["limit"] ?? 100;
+    if (!wholeNumber(after, 0) ||
+        !wholeNumber(limit, 1) ||
+        limit > 1000 ||
+        (runId !== undefined && typeof runId !== "string"))
+        return undefined;
+    return { after, limit, ...(runId === undefined ? {} : { runId }) };
+}
+function published(page) {
+    return page.events.map((event) => ({ schemaVersion: 1, ...event }));
+}
+function gap(after, page) {
+    return failed("event-gap", {
+        detail: `The service has no events after sequence ${String(after)}.`,
+        after,
+        earliestAvailable: page.earliest,
+        latestSequence: page.latest,
+    });
+}
+async function followed(context, stream) {
+    const { connection } = stream;
+    let { after } = stream.start;
+    while (!connection.closed()) {
+        const page = await context.authority.queries.eventsAfter({
+            ...stream.start,
+            after,
+        });
+        if (!(await connection.send(published(page))))
+            return undefined;
+        after = page.events.at(-1)?.sequence ?? after;
+        if (page.events.length === 0)
+            await changed(context, page.latest);
+    }
+    return undefined;
+}
+function changed(context, latest) {
+    const milliseconds = context.followMilliseconds;
+    return context.changed === undefined
+        ? delay(milliseconds)
+        : context.changed({ after: latest, milliseconds });
+}
+async function known(context, runId) {
+    if (!isIdentifier(runId))
+        return false;
+    return (await context.authority.state()).runs[runId] !== undefined;
+}
+export async function events(context, request) {
+    const start = cursor(request.parameters);
+    if (start === undefined)
+        return invalidRequest("The events request is not valid.");
+    if (start.runId !== undefined && !(await known(context, start.runId)))
+        return failed("unknown-run", {
+            runId: start.runId,
+            detail: `No run has the ID ${start.runId}.`,
+        });
+    const page = await context.authority.queries.eventsAfter(start);
+    if (start.after > page.latest)
+        return gap(start.after, page);
+    if (request.parameters["follow"] === true)
+        return followed(context, { start, connection: request.connection });
+    return result("event-page", {
+        events: published(page),
+        latestSequence: page.latest,
+    });
+}

package/dist/src/service/expiry.d.ts

@@ -0,0 +1,13 @@
+import type { Authority } from "../broker/actor/authority.ts";
+import type { Gateway } from "./gateway.ts";
+export interface ExpiryScan {
+    readonly stop: () => Promise<void>;
+}
+interface ScanParts {
+    readonly authority: Authority;
+    readonly gateway: Gateway;
+    readonly clock: () => string;
+    readonly intervalMilliseconds: number;
+}
+export declare function expiryScan(parts: ScanParts): ExpiryScan;
+export {};

package/dist/src/service/expiry.js

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { notBefore } from "../authority/instants.js";
+import { operationDigest } from "../broker/operation-digest.js";
+function expiryIdentity(runId, gateId) {
+    return `expire:${createHash("sha256").update(`${runId} ${gateId}`).digest("hex").slice(0, 32)}`;
+}
+async function scanned(parts) {
+    const { authority, gateway, clock } = parts;
+    const state = await authority.state();
+    const now = clock();
+    const due = Object.values(state.gates).filter((gate) => gate.outcome === null &&
+        gate.expiresAt !== null &&
+        notBefore(now, gate.expiresAt) &&
+        state.runs[gate.runId]?.status === "waiting_gate");
+    for (const gate of due)
+        await gateway.execute({
+            principal: "controller",
+            command: {
+                kind: "expire-gate",
+                commandId: expiryIdentity(gate.runId, gate.gateId),
+                runId: gate.runId,
+                gateId: gate.gateId,
+            },
+        });
+    for (const lease of await authority.effects.dueLeases(now))
+        await gateway.execute({
+            principal: "controller",
+            command: {
+                kind: "expire-lease",
+                commandId: `expire-lease:${operationDigest(lease.operationId)}:${String(lease.generation)}`,
+                runId: lease.runId,
+                operationId: lease.operationId,
+                leaseGeneration: lease.generation,
+            },
+        });
+}
+async function cycle(parts, signal) {
+    while (!signal.aborted) {
+        await scanned(parts).catch(() => undefined);
+        await delay(parts.intervalMilliseconds, undefined, { signal }).catch(() => undefined);
+    }
+}
+export function expiryScan(parts) {
+    const stopping = new AbortController();
+    const running = cycle(parts, stopping.signal);
+    return {
+        stop: async () => {
+            stopping.abort();
+            await running;
+        },
+    };
+}

package/dist/src/service/gateway.d.ts

@@ -0,0 +1,21 @@
+import type { Authority, StoreReceipt } from "../broker/actor/authority.ts";
+import type { Registry } from "./registry.ts";
+export type Principal = "operator" | "worker" | "controller";
+export type Command = Readonly<Record<string, unknown>>;
+export interface Submission {
+    readonly principal: Principal;
+    readonly command: Command;
+    readonly documents?: readonly string[];
+    readonly epoch?: number;
+}
+export declare const workerCommandBound = 1000;
+export interface Gateway {
+    readonly execute: (submission: Submission) => Promise<StoreReceipt>;
+}
+export declare function commandGateway(parts: {
+    readonly authority: Authority;
+    readonly registry: Registry;
+    readonly clock: () => string;
+    readonly textBytes: number;
+    readonly pendingWorkerCommands?: number;
+}): Gateway;

package/dist/src/service/gateway.js

@@ -0,0 +1,120 @@
+import { invalidCommand, serializable, textList, unserializable, } from "../broker/actor/authority-receipts.js";
+import { record } from "../protocol.js";
+export const workerCommandBound = 1_000;
+const permitted = {
+    operator: [
+        "admit-run",
+        "decide-gate",
+        "pause-run",
+        "resume-run",
+        "cancel-run",
+    ],
+    worker: [
+        "mark-started",
+        "open-gate",
+        "register-wait",
+        "report-observation",
+        "complete-run",
+        "fail-run",
+        "request-effect",
+        "report-effect",
+    ],
+    controller: ["expire-gate", "expire-lease"],
+};
+const pinned = ["decide-gate", "resume-run"];
+function denied(principal, subject) {
+    return {
+        kind: "rejected",
+        reason: "permission-denied",
+        detail: `${principal} cannot send ${subject}`,
+    };
+}
+function checked(principal, copy) {
+    const command = record(copy["command"]);
+    const documents = textList(copy["documents"]);
+    const epoch = copy["epoch"];
+    if (command === undefined || documents === undefined)
+        return undefined;
+    if (epoch === undefined)
+        return { principal, command, documents };
+    if (typeof epoch !== "number")
+        return undefined;
+    return { principal, command, documents, epoch };
+}
+function busy(bound) {
+    return {
+        kind: "rejected",
+        reason: "service-busy",
+        detail: `The service has ${String(bound)} worker commands in work. Send the command again with the same command ID.`,
+    };
+}
+function refusal(submission, textBytes) {
+    const { principal, command } = submission;
+    const kind = String(command["kind"]);
+    if (!permitted[principal].includes(kind))
+        return denied(principal, kind);
+    if (kind === "open-gate" && command["gateKind"] === undefined)
+        return denied(principal, "an untyped gate");
+    const long = submission.documents.some((document) => Buffer.byteLength(document) > textBytes);
+    if (principal === "worker" && long)
+        return {
+            kind: "rejected",
+            reason: "input-too-large",
+            detail: `A text of a worker has at most ${String(textBytes)} bytes.`,
+        };
+    return undefined;
+}
+export function commandGateway(parts) {
+    const { authority, registry, clock, textBytes } = parts;
+    const bound = parts.pendingWorkerCommands ?? workerCommandBound;
+    let pending = 0;
+    async function manifest(command) {
+        const kind = String(command["kind"]);
+        if (kind === "admit-run")
+            return registry.byPin(String(command["workflow"]))?.manifest;
+        if (!pinned.includes(kind))
+            return undefined;
+        const run = (await authority.state()).runs[String(command["runId"])];
+        return registry.byPin(run?.workflow ?? "")?.manifest;
+    }
+    async function forwarded(submission) {
+        const available = await manifest(submission.command);
+        return authority.execute(submission.command, {
+            recordedAt: clock(),
+            ...(available === undefined ? {} : { manifest: available }),
+            ...(submission.epoch === undefined ? {} : { epoch: submission.epoch }),
+            documents: submission.documents,
+        });
+    }
+    async function counted(submission) {
+        if (pending >= bound)
+            return busy(bound);
+        pending += 1;
+        try {
+            return await forwarded(submission);
+        }
+        finally {
+            pending -= 1;
+        }
+    }
+    return {
+        execute: async (given) => {
+            const copy = serializable({
+                command: given.command,
+                documents: given.documents ?? [],
+                ...(given.epoch === undefined ? {} : { epoch: given.epoch }),
+            });
+            if (copy === undefined)
+                return unserializable;
+            const submission = checked(given.principal, copy);
+            if (submission === undefined)
+                return invalidCommand;
+            const refused = refusal(submission, textBytes);
+            if (refused !== undefined)
+                return refused;
+            return submission.principal === "worker"
+                ? counted(submission)
+                : forwarded(submission);
+        },
+    };
+}

package/dist/src/service/registry.d.ts

@@ -0,0 +1,40 @@
+import type { SubmissionContract } from "../submission.ts";
+import type { ExecutionManifest } from "../workflow-admission.ts";
+export type Resolution = {
+    readonly kind: "resolved";
+    readonly input: unknown;
+} | {
+    readonly kind: "rejected";
+    readonly code: string;
+    readonly detail: string;
+};
+export interface ResolutionRequest {
+    readonly workflowId: string;
+    readonly submission: Readonly<Record<string, unknown>>;
+    readonly commandId: string;
+    readonly signal: AbortSignal;
+}
+export interface Resolver {
+    readonly id: string;
+    readonly version: string;
+    readonly resolve: (request: ResolutionRequest) => Promise<Resolution>;
+}
+export interface WorkflowRegistration {
+    readonly workflowId: string;
+    readonly manifest: ExecutionManifest;
+    readonly availability: "available" | "unavailable";
+    readonly submission: SubmissionContract;
+    readonly resolver: Resolver;
+    readonly effectLimit?: number;
+    readonly admission?: "when-idle";
+}
+export interface Registered extends WorkflowRegistration {
+    readonly pin: string;
+}
+export interface Registry {
+    readonly workflowIds: readonly string[];
+    readonly byId: (workflowId: string) => Registered | undefined;
+    readonly byPin: (pin: string) => Registered | undefined;
+    readonly available: (pinned: ExecutionManifest) => ExecutionManifest | undefined;
+}
+export declare function workflowRegistry(workflows: readonly WorkflowRegistration[]): Registry;

package/dist/src/service/registry.js

@@ -0,0 +1,13 @@
+import { workflowPin } from "../broker/workflow-pin.js";
+export function workflowRegistry(workflows) {
+    const registered = workflows.map((workflow) => ({
+        ...workflow,
+        pin: workflowPin(workflow.manifest),
+    }));
+    return {
+        workflowIds: registered.map((workflow) => workflow.workflowId),
+        byId: (workflowId) => registered.find((workflow) => workflow.workflowId === workflowId),
+        byPin: (pin) => registered.find((workflow) => workflow.pin === pin),
+        available: (pinned) => registered.find((workflow) => workflow.manifest.workflowId === pinned.workflowId)?.manifest,
+    };
+}

package/dist/src/service/replies.d.ts

@@ -0,0 +1,26 @@
+import type { Authority, CommandRecord, StoreReceipt } from "../broker/actor/authority.ts";
+import type { Fields, Reply } from "../protocol.ts";
+import type { ChangeSignal } from "./changes.ts";
+import type { Gateway } from "./gateway.ts";
+import type { Registry } from "./registry.ts";
+export interface ServiceContext {
+    readonly authority: Authority;
+    readonly registry: Registry;
+    readonly gateway: Gateway;
+    readonly clock: () => string;
+    readonly livenessMilliseconds: number;
+    readonly followMilliseconds: number;
+    readonly resolverMilliseconds: number;
+    readonly textBytes: number;
+    readonly documentBytes: number;
+    readonly worldReports?: () => readonly unknown[];
+    readonly changed?: ChangeSignal["next"];
+}
+export declare function result(kind: string, fields: Fields): Reply;
+export declare function failed(code: string, extra: Fields): Reply;
+export declare function invalidRequest(detail: string): Reply;
+export declare function rejection(receipt: StoreReceipt, identity: Fields): Reply;
+export declare function committed(receipt: StoreReceipt): boolean;
+export declare function isIdentifier(value: unknown): value is string;
+export declare function wholeNumber(value: unknown, minimum: number): value is number;
+export declare function publicReceipt(record: CommandRecord): Fields;

package/dist/src/service/replies.js

@@ -0,0 +1,56 @@
+import { isRecordKey } from "../authority/commands.js";
+const codes = {
+    "invalid-command": "invalid-request",
+    "request-too-large": "input-too-large",
+    "missing-document": "invalid-request",
+    "unknown-gate": "unknown-decision",
+    "missing-manifest": "workflow-unavailable",
+};
+export function result(kind, fields) {
+    return { kind: "result", result: { schemaVersion: 1, kind, ...fields } };
+}
+export function failed(code, extra) {
+    const detail = extra["detail"];
+    return {
+        kind: "error",
+        error: {
+            ...extra,
+            code,
+            detail: typeof detail === "string" ? detail : code,
+        },
+    };
+}
+export function invalidRequest(detail) {
+    return failed("invalid-request", { detail });
+}
+export function rejection(receipt, identity) {
+    if (receipt.kind === "failed")
+        return failed("authority-unavailable", {
+            ...identity,
+            detail: `${receipt.reason}: ${receipt.detail}`,
+        });
+    if (receipt.kind !== "rejected")
+        return failed("invalid-request", identity);
+    return failed(codes[receipt.reason] ?? receipt.reason, {
+        ...identity,
+        detail: receipt.detail ?? receipt.reason,
+    });
+}
+export function committed(receipt) {
+    return receipt.kind === "accepted" || receipt.kind === "duplicate";
+}
+export function isIdentifier(value) {
+    return isRecordKey(value);
+}
+export function wholeNumber(value, minimum) {
+    return (typeof value === "number" && Number.isSafeInteger(value) && value >= minimum);
+}
+export function publicReceipt(record) {
+    return {
+        commandId: record.commandId,
+        sequence: record.sequence,
+        runId: record.runId,
+        recordedAt: record.recordedAt,
+        commandDigest: record.commandDigest,
+    };
+}

package/dist/src/service/run-handlers.d.ts

@@ -0,0 +1,4 @@
+import { type Fields, type Reply } from "../protocol.ts";
+import { type ServiceContext } from "./replies.ts";
+export declare function status(context: ServiceContext, parameters: Fields): Promise<Reply>;
+export declare function runCommand(context: ServiceContext, parameters: Fields): Promise<Reply>;