cloving 0.3.20 → 1.1.0

package/dist/src/host/world-host.js

@@ -0,0 +1,51 @@
+import { getWorld } from "workflow/runtime";
+import { releaseStepClaims } from "./step-claims.js";
+const workflowQueue = "__wkf_workflow_";
+export const hostBoundLimit = 64;
+function direct(world) {
+    return ("registerHandler" in world && typeof world.registerHandler === "function");
+}
+function refused(reason, detail) {
+    return { kind: "refused", reason, detail };
+}
+function unsuitable(settings) {
+    const { concurrency, dataDirectory } = settings;
+    const bounded = Number.isSafeInteger(concurrency) &&
+        concurrency >= 1 &&
+        concurrency <= hostBoundLimit;
+    if (!bounded)
+        return refused("invalid-host-bound", String(concurrency));
+    if (process.env["WORKFLOW_TARGET_WORLD"] !== "local")
+        return refused("host-world", "WORKFLOW_TARGET_WORLD is not local");
+    if (process.env["WORKFLOW_LOCAL_DATA_DIR"] !== dataDirectory)
+        return refused("host-world", "WORKFLOW_LOCAL_DATA_DIR is not the setting");
+    if (process.env["WORKFLOW_LOCAL_QUEUE_CONCURRENCY"] !== String(concurrency))
+        return refused("host-bound", "WORKFLOW_LOCAL_QUEUE_CONCURRENCY is not the setting");
+    return undefined;
+}
+export async function startHost(settings) {
+    const refusal = unsuitable(settings);
+    if (refusal)
+        return refusal;
+    const world = await getWorld();
+    if (!direct(world))
+        return refused("host-world", "the World takes no handler in its process");
+    const released = await releaseStepClaims(settings.dataDirectory, world);
+    world.registerHandler(workflowQueue, settings.handler);
+    try {
+        await world.start?.();
+    }
+    catch (error) {
+        await world.close?.();
+        return refused("host-start-failed", String(Reflect.get(Object(error), "message")));
+    }
+    return {
+        kind: "started",
+        host: {
+            released,
+            close: async () => {
+                await world.close?.();
+            },
+        },
+    };
+}

package/dist/src/host/world-reconciliation.d.ts

@@ -0,0 +1,39 @@
+import { type WorldReport, type WorldRun } from "../authority/reconciliation.ts";
+import type { AuthorityState } from "../authority/transitions.ts";
+export type ReconciledState = Pick<AuthorityState, "runs" | "intents" | "details" | "gates" | "commands">;
+export interface WorkflowOutcome {
+    readonly kind: string;
+    readonly reason?: string;
+    readonly issueUpdate?: "failed";
+    readonly ticketStatus?: "complete" | "partial";
+}
+export interface ReconciliationPorts {
+    readonly state: () => Promise<ReconciledState>;
+    readonly submit: (command: Readonly<Record<string, unknown>>) => Promise<{
+        readonly kind: "accepted" | "duplicate" | "rejected" | "failed";
+    }>;
+    readonly runs: () => Promise<readonly WorldRun[]>;
+    readonly outcome: (receipt: string) => Promise<WorkflowOutcome | undefined>;
+}
+export interface Pass {
+    readonly sent: readonly string[];
+    readonly interrupted: boolean;
+    readonly reports: readonly WorldReport[];
+    readonly conflicts: readonly string[];
+}
+export declare function reconcileWorld(ports: ReconciliationPorts): Promise<Pass>;
+export type LoopReport = WorldReport | {
+    readonly kind: "world-run-conflict";
+    readonly runId: string;
+} | {
+    readonly kind: "world-reconciliation-failed";
+    readonly passes: number;
+};
+export declare const passFailureLimit = 3;
+export interface WorldLoop {
+    readonly stop: () => Promise<void>;
+    readonly reports: () => readonly LoopReport[];
+}
+export declare function worldLoop(parts: ReconciliationPorts & {
+    readonly intervalMilliseconds: number;
+}): WorldLoop;

package/dist/src/host/world-reconciliation.js

@@ -0,0 +1,81 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { reconcile, } from "../authority/reconciliation.js";
+async function withOutcome(ports, observed) {
+    const { state, world } = observed;
+    const ended = world.status === "completed" &&
+        state.runs[world.runId]?.status === "running";
+    if (!ended)
+        return world;
+    const read = await ports.outcome(world.receipt).then((outcome) => ({ outcome }), () => undefined);
+    if (read === undefined)
+        return { ...world, status: "unreadable" };
+    return read.outcome === undefined
+        ? world
+        : {
+            ...world,
+            outcome: read.outcome.kind,
+            ...(read.outcome.issueUpdate === "failed"
+                ? { issueUpdate: read.outcome.issueUpdate }
+                : {}),
+            ...(read.outcome.ticketStatus === undefined
+                ? {}
+                : { ticketStatus: read.outcome.ticketStatus }),
+            ...(read.outcome.reason === undefined
+                ? {}
+                : { outcomeReason: read.outcome.reason }),
+        };
+}
+export async function reconcileWorld(ports) {
+    const listed = await ports.runs();
+    const state = await ports.state();
+    const runs = [];
+    for (const world of listed)
+        runs.push(await withOutcome(ports, { state, world }));
+    const { commands, reports, conflicts } = reconcile(state, runs);
+    const sent = [];
+    for (const command of commands) {
+        const receipt = await ports.submit(command);
+        sent.push(`${String(command["commandId"])} ${receipt.kind}`);
+        if (receipt.kind === "failed")
+            return { sent, interrupted: true, reports, conflicts };
+    }
+    return { sent, interrupted: false, reports, conflicts };
+}
+export const passFailureLimit = 3;
+function reported(pass) {
+    return [
+        ...pass.reports,
+        ...pass.conflicts.map((runId) => ({
+            kind: "world-run-conflict",
+            runId,
+        })),
+    ];
+}
+export function worldLoop(parts) {
+    const stopping = new AbortController();
+    let reports = [];
+    let failures = 0;
+    const cycle = async () => {
+        while (!stopping.signal.aborted) {
+            const pass = await reconcileWorld(parts).catch(() => undefined);
+            reports = pass === undefined ? reports : reported(pass);
+            failures = pass?.interrupted === false ? 0 : failures + 1;
+            await delay(parts.intervalMilliseconds, undefined, {
+                signal: stopping.signal,
+            }).catch(() => undefined);
+        }
+    };
+    const running = cycle();
+    return {
+        stop: async () => {
+            stopping.abort();
+            await running;
+        },
+        reports: () => failures < passFailureLimit
+            ? reports
+            : [
+                ...reports,
+                { kind: "world-reconciliation-failed", passes: failures },
+            ],
+    };
+}

package/dist/src/host/world-runs.d.ts

@@ -0,0 +1,14 @@
+import type { WorldRun } from "../authority/reconciliation.ts";
+import type { WorkflowOutcome } from "./world-reconciliation.ts";
+export declare const runTag = "cloving.run";
+export declare const operationTag = "cloving.operation";
+export interface TaggedRun extends WorldRun {
+    readonly operationId: string | null;
+    readonly createdAt: string;
+}
+export declare function taggedRuns(pageSize?: number): Promise<TaggedRun[]>;
+export declare function workflowOutcome(receipt: string): Promise<WorkflowOutcome | undefined>;
+export declare function cancelled(receipt: string): Promise<string>;
+export declare function taggedRun(receipt: string): Promise<{
+    readonly runId: string;
+} | undefined>;

package/dist/src/host/world-runs.js

@@ -0,0 +1,69 @@
+import { isTicketStatus } from "../ticket-status.js";
+import { getRun } from "workflow/api";
+import { getWorld } from "workflow/runtime";
+export const runTag = "cloving.run";
+export const operationTag = "cloving.operation";
+function tag(attributes, name) {
+    const value = Reflect.get(Object(attributes), name);
+    return typeof value === "string" ? value : null;
+}
+async function collected(world, page) {
+    const listed = await world.runs.list({
+        resolveData: "none",
+        pagination: {
+            limit: page.limit,
+            ...(page.cursor === null ? {} : { cursor: page.cursor }),
+        },
+    });
+    const found = listed.data.flatMap((item) => {
+        const runId = tag(item.attributes, runTag);
+        if (runId === null)
+            return [];
+        return [
+            {
+                runId,
+                operationId: tag(item.attributes, operationTag),
+                receipt: item.runId,
+                status: item.status,
+                createdAt: item.createdAt.toISOString(),
+            },
+        ];
+    });
+    if (!listed.hasMore || listed.cursor === null)
+        return found;
+    return [
+        ...found,
+        ...(await collected(world, { limit: page.limit, cursor: listed.cursor })),
+    ];
+}
+export async function taggedRuns(pageSize = 200) {
+    return await collected(await getWorld(), { limit: pageSize, cursor: null });
+}
+export async function workflowOutcome(receipt) {
+    const value = await getRun(receipt).returnValue;
+    const kind = Reflect.get(Object(value), "kind");
+    if (typeof kind !== "string")
+        return undefined;
+    const reason = Reflect.get(Object(value), "reason");
+    const issueUpdate = Reflect.get(Object(value), "issueUpdate");
+    const ticketStatus = Reflect.get(Object(value), "ticketStatus");
+    return {
+        kind,
+        ...(typeof reason === "string" ? { reason } : {}),
+        ...(issueUpdate === "failed" ? { issueUpdate } : {}),
+        ...(isTicketStatus(ticketStatus) ? { ticketStatus } : {}),
+    };
+}
+export async function cancelled(receipt) {
+    const run = getRun(receipt);
+    await run.cancel().catch(() => undefined);
+    return await run.status;
+}
+export async function taggedRun(receipt) {
+    const world = await getWorld();
+    const run = await world.runs
+        .get(receipt, { resolveData: "none" })
+        .catch(() => undefined);
+    const runId = tag(run?.attributes, runTag);
+    return runId === null ? undefined : { runId };
+}

package/dist/src/operation-identity.d.ts

@@ -0,0 +1,7 @@
+import type { Validation } from "./workflow-contracts.ts";
+export declare function operationIdentity(value: unknown): Validation<string>;
+export interface OperationScope {
+    readonly run: string;
+    readonly operation: string;
+}
+export declare function operationScope(operationId: string): OperationScope | null;

package/dist/src/operation-identity.js

@@ -0,0 +1,59 @@
+const component = /^[A-Za-z0-9._:/-]{1,128}$/;
+export function operationIdentity(value) {
+    const scope = fields(value);
+    const round = scope["round"];
+    const stage = optionalStage(scope["stage"]);
+    const key = scope["key"];
+    const required = [scope["run"], scope["phase"], scope["operation"]];
+    if (typeof round !== "number" ||
+        !Number.isSafeInteger(round) ||
+        round < 0 ||
+        stage === undefined ||
+        !required.every(isComponent) ||
+        (key !== undefined && !isComponent(key)))
+        return { kind: "invalid", reason: "invalid-operation-scope" };
+    return {
+        kind: "valid",
+        value: JSON.stringify([
+            "cloving-operation",
+            round,
+            ...required,
+            stage,
+            key ?? null,
+        ]),
+    };
+}
+function optionalStage(value) {
+    if (value === undefined)
+        return null;
+    const stage = fields(value);
+    const [id, visit, branch] = [stage["id"], stage["visit"], stage["branch"]];
+    if (!isComponent(id) || !isComponent(visit) || !isComponent(branch))
+        return undefined;
+    return [id, visit, branch];
+}
+function isComponent(value) {
+    return typeof value === "string" && component.test(value);
+}
+function fields(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    return Object.fromEntries(Object.entries(value));
+}
+export function operationScope(operationId) {
+    const [marker, , run, , operation] = parsedList(operationId);
+    if (marker !== "cloving-operation")
+        return null;
+    if (!isComponent(run) || !isComponent(operation))
+        return null;
+    return { run, operation };
+}
+function parsedList(text) {
+    try {
+        const value = JSON.parse(text);
+        return Array.isArray(value) ? value : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/protocol.d.ts

@@ -0,0 +1,35 @@
+export declare const protocolVersion = 1;
+export declare const maximumFrameBytes = 1048576;
+export type Fields = Readonly<Record<string, unknown>>;
+export interface ServiceRequest {
+    readonly operation: string;
+    readonly parameters: Fields;
+}
+export interface ServiceError extends Fields {
+    readonly code: string;
+    readonly detail: string;
+}
+export type Reply = {
+    readonly kind: "result";
+    readonly result: Fields;
+} | {
+    readonly kind: "error";
+    readonly error: ServiceError;
+};
+export type ParsedRequest = {
+    readonly kind: "request";
+    readonly request: ServiceRequest;
+} | {
+    readonly kind: "error";
+    readonly error: ServiceError;
+};
+export type ReplyLine = Reply | {
+    readonly kind: "event";
+    readonly event: Fields;
+};
+export declare function record(value: unknown): Fields | undefined;
+export declare function parseRequest(line: string): ParsedRequest;
+export declare function requestLine(request: ServiceRequest): string;
+export declare function replyLine(reply: Reply): string;
+export declare function eventLine(event: Fields): string;
+export declare function parseReplyLine(line: string): ReplyLine | undefined;

package/dist/src/protocol.js

@@ -0,0 +1,64 @@
+export const protocolVersion = 1;
+export const maximumFrameBytes = 1_048_576;
+export function record(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    return Object.fromEntries(Object.entries(value));
+}
+function decoded(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+function invalid(detail) {
+    return { kind: "error", error: { code: "invalid-request", detail } };
+}
+export function parseRequest(line) {
+    const fields = record(decoded(line));
+    if (fields === undefined)
+        return invalid("The request is not a JSON object.");
+    if (fields["protocol"] !== protocolVersion)
+        return {
+            kind: "error",
+            error: {
+                code: "service-incompatible",
+                detail: `The service uses protocol ${String(protocolVersion)}.`,
+            },
+        };
+    const { operation } = fields;
+    const parameters = record(fields["parameters"]);
+    if (typeof operation !== "string" || parameters === undefined)
+        return invalid("The request needs an operation and a parameters object.");
+    return { kind: "request", request: { operation, parameters } };
+}
+export function requestLine(request) {
+    return `${JSON.stringify({ protocol: protocolVersion, ...request })}\n`;
+}
+export function replyLine(reply) {
+    return reply.kind === "result"
+        ? `${JSON.stringify({ ok: true, result: reply.result })}\n`
+        : `${JSON.stringify({ ok: false, error: reply.error })}\n`;
+}
+export function eventLine(event) {
+    return `${JSON.stringify({ event })}\n`;
+}
+export function parseReplyLine(line) {
+    const fields = record(decoded(line));
+    if (fields === undefined)
+        return undefined;
+    const event = record(fields["event"]);
+    if (event !== undefined)
+        return { kind: "event", event };
+    const result = record(fields["result"]);
+    if (fields["ok"] === true && result !== undefined)
+        return { kind: "result", result };
+    const error = record(fields["error"]);
+    const code = error?.["code"];
+    const detail = error?.["detail"];
+    if (typeof code !== "string" || typeof detail !== "string")
+        return undefined;
+    return { kind: "error", error: { ...error, code, detail } };
+}

package/dist/src/resource-files.d.ts

@@ -0,0 +1 @@
+export declare function collectResources(root: string, paths: readonly string[]): Promise<Readonly<Record<string, string>>>;

package/dist/src/resource-files.js

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+export async function collectResources(root, paths) {
+    const base = await realpath(root);
+    const entries = [];
+    for (const path of paths) {
+        const digest = await resourceDigest(base, path);
+        if (digest !== null)
+            entries.push([path, digest]);
+    }
+    return Object.fromEntries(entries);
+}
+async function resourceDigest(base, path) {
+    if (isAbsolute(path))
+        return null;
+    const file = await realpath(join(base, path)).catch(() => null);
+    if (file === null)
+        return null;
+    const inside = relative(base, file);
+    if (inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside))
+        return null;
+    if (!(await lstat(file)).isFile())
+        return null;
+    const bytes = await readFile(file).catch(() => null);
+    if (bytes === null)
+        return null;
+    return createHash("sha256").update(bytes).digest("hex");
+}

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

@@ -0,0 +1,11 @@
+export interface ChangeWait {
+    readonly after: number;
+    readonly milliseconds: number;
+}
+export interface ChangeSignal {
+    readonly next: (wait: ChangeWait) => Promise<void>;
+    readonly close: () => void;
+}
+type Subscribe = (listener: (sequence: number) => void) => () => void;
+export declare function changeSignal(subscribe: Subscribe): ChangeSignal;
+export {};

package/dist/src/service/changes.js

@@ -0,0 +1,32 @@
+export function changeSignal(subscribe) {
+    const waiting = new Set();
+    const seen = { latest: -1, closed: false };
+    const wake = () => {
+        for (const settle of [...waiting])
+            settle();
+    };
+    const unsubscribe = subscribe((sequence) => {
+        seen.latest = Math.max(seen.latest, sequence);
+        wake();
+    });
+    return {
+        next: ({ after, milliseconds }) => {
+            if (seen.closed || seen.latest > after)
+                return Promise.resolve();
+            return new Promise((settle) => {
+                const done = () => {
+                    clearTimeout(timer);
+                    waiting.delete(done);
+                    settle();
+                };
+                const timer = setTimeout(done, milliseconds);
+                waiting.add(done);
+            });
+        },
+        close: () => {
+            seen.closed = true;
+            unsubscribe();
+            wake();
+        },
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { StoredState } from "../broker/actor/authority.ts";
+import type { Fields, Reply } from "../protocol.ts";
+import { type ServiceContext } from "./replies.ts";
+export declare function feedbackOf(context: ServiceContext, scope: {
+    readonly state: StoredState;
+    readonly runId: string;
+}): Promise<readonly Fields[]>;
+export declare function questions(context: ServiceContext, parameters: Fields): Promise<Reply>;
+export declare function decision(context: ServiceContext, parameters: Fields): Promise<Reply>;