cloving 0.3.20 → 1.1.0

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

@@ -0,0 +1,12 @@
+import { type EffectEvent, type EffectState, type RunBudget } from "./operations.ts";
+type Payload = Readonly<Record<string, string>>;
+export declare function admittedBudgets(budgets: EffectState["budgets"], admission: {
+    readonly runId: string;
+    readonly payload: Payload;
+}): EffectState["budgets"];
+export interface Authorization {
+    readonly reason: string | null;
+    readonly budget: RunBudget | undefined;
+}
+export declare function authorization(budget: RunBudget | undefined, event: EffectEvent): Authorization;
+export {};

package/dist/src/authority/budgets.js

@@ -0,0 +1,42 @@
+import { authorizeEffect } from "../effect-authorization.js";
+import { count, field, } from "./operations.js";
+function capabilityList(text) {
+    const value = JSON.parse(text);
+    return Array.isArray(value) ? value.map(String) : [];
+}
+export function admittedBudgets(budgets, admission) {
+    const { runId, payload } = admission;
+    const limit = payload["effectLimit"];
+    if (limit === undefined)
+        return budgets;
+    return {
+        ...budgets,
+        [runId]: {
+            runId,
+            limit: Number(limit),
+            spent: 0,
+            capabilities: capabilityList(payload["capabilities"] ?? "[]"),
+            exhaustedSequence: null,
+        },
+    };
+}
+const exhausted = "budget-exhausted";
+export function authorization(budget, event) {
+    if (budget === undefined || budget.exhaustedSequence !== null)
+        return { reason: exhausted, budget };
+    const result = authorizeEffect({ capabilities: budget.capabilities }, {
+        budget: { limit: budget.limit, spent: budget.spent },
+        request: {
+            capability: field(event, "capability"),
+            units: count(event, "units"),
+        },
+    });
+    if (result.kind === "authorized")
+        return { reason: null, budget: { ...budget, spent: result.spent } };
+    return {
+        reason: result.reason,
+        budget: result.reason === exhausted
+            ? { ...budget, exhaustedSequence: event.sequence }
+            : budget,
+    };
+}

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

@@ -0,0 +1,7 @@
+import { type AuthorityCommand, type EventType } from "./transitions.ts";
+export declare const commandEvents: Readonly<Record<string, EventType>>;
+export declare function parseCommand(value: unknown): AuthorityCommand | null;
+export declare const recoveryBound = 10;
+export declare function isCapabilityList(value: unknown): value is string;
+export declare function isIdentifier(value: unknown): value is string;
+export declare function isRecordKey(value: unknown): value is string;

package/dist/src/authority/commands.js

@@ -0,0 +1,271 @@
+import { isTicketStatus } from "../ticket-status.js";
+import { isInstant } from "./instants.js";
+import { isBlockedReason } from "../workflow-contracts.js";
+import { numberFields, textFields, } from "./transitions.js";
+const identifier = /^[A-Za-z0-9._:/-]{1,128}$/;
+const digest = /^sha256:[0-9a-f]{64}$/;
+const operation = /^[\x20-\x7e]{1,512}$/;
+export const commandEvents = {
+    "admit-run": "run.created",
+    "mark-started": "run.started",
+    "open-gate": "gate.opened",
+    "register-wait": "gate.wait-registered",
+    "decide-gate": "gate.decided",
+    "expire-gate": "gate.expired",
+    "pause-run": "run.paused",
+    "resume-run": "run.resumed",
+    "complete-run": "run.completed",
+    "fail-run": "run.failed",
+    "cancel-run": "run.cancelled",
+    "report-observation": "run.observed",
+    "record-dispatch": "step.dispatched",
+    "request-effect": "effect.requested",
+    "grant-lease": "lease.granted",
+    "expire-lease": "lease.expired",
+    "report-effect": "effect.reported",
+    "record-outcome": "operation.reconciled",
+};
+const revised = { required: ["expectedRevision"] };
+const shapes = {
+    "admit-run": {
+        required: ["workflow"],
+        optional: [
+            "submission",
+            "input",
+            "resolver",
+            "effectLimit",
+            "capabilities",
+        ],
+        groups: [
+            ["submission", "input", "resolver"],
+            ["effectLimit", "capabilities"],
+        ],
+    },
+    "mark-started": revised,
+    "open-gate": {
+        required: ["gateId", "expectedRevision"],
+        optional: ["gateKind", "subject", "prompt", "expiresAt"],
+        groups: [["gateKind", "subject", "prompt"]],
+        consistent: (fields) => fields["expiresAt"] === undefined || fields["gateKind"] !== undefined,
+    },
+    "register-wait": { required: ["gateId"] },
+    "decide-gate": {
+        required: ["gateId", "decision", "expectedRevision"],
+        optional: ["generation", "subject", "answer"],
+        groups: [["generation", "subject"]],
+        consistent: (fields) => {
+            const typed = fields["generation"] !== undefined;
+            if (typed && fields["decision"] === "denied")
+                return true;
+            return ((fields["answer"] !== undefined) ===
+                (typed && fields["decision"] === "answered"));
+        },
+    },
+    "expire-gate": { required: ["gateId"] },
+    "pause-run": revised,
+    "resume-run": revised,
+    "complete-run": {
+        required: ["expectedRevision"],
+        optional: ["outcome", "outcomeReason", "ticketStatus", "issueUpdate"],
+        validators: {
+            outcome: (value) => value === "handoff_requested" || value === "blocked",
+            outcomeReason: isBlockedReason,
+            ticketStatus: isTicketStatus,
+            issueUpdate: (value) => value === "failed",
+        },
+        consistent: (fields) => (fields["outcomeReason"] === undefined ||
+            fields["outcome"] === "blocked") &&
+            (fields["ticketStatus"] === undefined ||
+                fields["outcome"] === "handoff_requested") &&
+            (fields["issueUpdate"] === undefined ||
+                fields["outcome"] === "handoff_requested"),
+    },
+    "fail-run": revised,
+    "cancel-run": revised,
+    "report-observation": {
+        required: ["condition", "reason"],
+        optional: ["evidence", "retryAt", "attempt", "limit", "operationId"],
+        groups: [["attempt", "limit"]],
+    },
+    "record-dispatch": { required: ["operationId", "receipt"] },
+    "request-effect": {
+        required: [
+            "operationId",
+            "capability",
+            "method",
+            "target",
+            "payload",
+            "inputDigest",
+            "units",
+            "recoveryLimit",
+        ],
+        optional: ["resource", "transport", "source", "sourceGeneration"],
+        groups: [["source", "sourceGeneration"]],
+    },
+    "grant-lease": {
+        required: ["operationId", "leaseGeneration", "expiresAt", "capacity"],
+    },
+    "expire-lease": { required: ["operationId", "leaseGeneration"] },
+    "report-effect": {
+        required: [
+            "operationId",
+            "inputDigest",
+            "leaseGeneration",
+            "worker",
+            "outcome",
+        ],
+        optional: ["result", "reason", "evidence"],
+        consistent: (fields) => reportedOutcomes.includes(String(fields["outcome"])) &&
+            (fields["outcome"] === "failed" ||
+                (fields["result"] !== undefined) ===
+                    (fields["outcome"] === "completed")) &&
+            (fields["reason"] !== undefined) === (fields["outcome"] === "failed"),
+    },
+    "record-outcome": {
+        required: ["operationId", "outcome"],
+        optional: [
+            "leaseGeneration",
+            "receipt",
+            "worker",
+            "result",
+            "reason",
+            "evidence",
+        ],
+    },
+};
+const reportedOutcomes = ["completed", "failed", "stopped"];
+const outcomes = [...reportedOutcomes, "accepted", "not-started", "unknown"];
+const conditions = [
+    "working",
+    "quota-wait",
+    "infrastructure-failure",
+    "code-failure",
+    "stopped",
+];
+export function parseCommand(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const fields = Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+    const { kind, commandId, runId } = fields;
+    if (!knownKind(kind) || !isRecordKey(commandId) || !isRecordKey(runId))
+        return null;
+    if (!completeFields(kind, fields))
+        return null;
+    return {
+        kind,
+        commandId,
+        runId,
+        ...numbers(fields),
+        ...texts(fields),
+    };
+}
+function knownKind(kind) {
+    return typeof kind === "string" && Object.hasOwn(commandEvents, kind);
+}
+function completeFields(kind, fields) {
+    const shape = shapes[kind] ?? revised;
+    const optional = shape.optional ?? [];
+    const allowed = [
+        "kind",
+        "commandId",
+        "runId",
+        ...shape.required,
+        ...optional,
+    ];
+    const present = optional.filter((key) => fields[key] !== undefined);
+    return (Object.keys(fields).every((key) => allowed.includes(key)) &&
+        [...shape.required, ...present].every((key) => (shape.validators?.[key] ?? validators[key] ?? isIdentifier)(fields[key])) &&
+        (shape.groups ?? []).every((group) => complete(group, fields)) &&
+        (shape.consistent?.(fields) ?? true));
+}
+function complete(group, fields) {
+    const present = group.filter((key) => fields[key] !== undefined).length;
+    return present === 0 || present === group.length;
+}
+function numbers(fields) {
+    const result = {};
+    for (const name of numberFields) {
+        const value = fields[name];
+        if (typeof value === "number")
+            result[name] = value;
+    }
+    return result;
+}
+function texts(fields) {
+    const result = {};
+    for (const name of textFields) {
+        const value = fields[name];
+        if (typeof value === "string")
+            result[name] = value;
+    }
+    return result;
+}
+function whole(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+export const recoveryBound = 10;
+function positive(value) {
+    return whole(value) && value > 0;
+}
+function atMost(value, limit) {
+    return whole(value) && value <= limit;
+}
+function printable(value) {
+    return typeof value === "string" && operation.test(value);
+}
+function isDigest(value) {
+    return typeof value === "string" && digest.test(value);
+}
+function parsedList(text) {
+    try {
+        const value = JSON.parse(text);
+        return Array.isArray(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function isCapabilityList(value) {
+    if (typeof value !== "string")
+        return false;
+    const list = parsedList(value);
+    return (list !== null &&
+        list.length <= 64 &&
+        list.every(isIdentifier) &&
+        list.every((item, index) => index === 0 || String(list[index - 1]) < item) &&
+        JSON.stringify(list) === value);
+}
+const validators = {
+    expectedRevision: positive,
+    generation: positive,
+    attempt: positive,
+    limit: positive,
+    operationId: printable,
+    gateKind: (value) => value === "question" || value === "approval",
+    subject: isDigest,
+    effectLimit: whole,
+    units: whole,
+    recoveryLimit: (value) => positive(value) && atMost(value, recoveryBound),
+    leaseGeneration: positive,
+    sourceGeneration: positive,
+    capacity: positive,
+    capabilities: isCapabilityList,
+    target: printable,
+    transport: printable,
+    source: printable,
+    payload: isDigest,
+    inputDigest: isDigest,
+    result: isDigest,
+    resource: isRecordKey,
+    outcome: (value) => typeof value === "string" && outcomes.includes(value),
+    condition: (value) => typeof value === "string" && conditions.includes(value),
+    expiresAt: isInstant,
+    retryAt: isInstant,
+};
+export function isIdentifier(value) {
+    return typeof value === "string" && identifier.test(value);
+}
+const plainRecord = {};
+export function isRecordKey(value) {
+    return isIdentifier(value) && !(value in plainRecord);
+}

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

@@ -0,0 +1,28 @@
+export interface Observation {
+    readonly condition: string;
+    readonly reason: string;
+    readonly evidence: string | null;
+    readonly retryAt: string | null;
+    readonly operationId: string | null;
+    readonly attempt: number | null;
+    readonly limit: number | null;
+    readonly sequence: number;
+    readonly recordedAt: string;
+}
+export interface RunDetails {
+    readonly runId: string;
+    readonly generation: number;
+    readonly submission: string | null;
+    readonly input: string | null;
+    readonly resolver: string | null;
+    readonly observation: Observation | null;
+}
+type Payload = Readonly<Record<string, string>>;
+export declare function admittedDetails(runId: string, payload: Payload): RunDetails;
+export declare function observed(details: RunDetails, event: {
+    readonly payload: Payload;
+    readonly sequence: number;
+    readonly recordedAt: string;
+}): RunDetails;
+export declare function continued(details: RunDetails): RunDetails;
+export {};

package/dist/src/authority/details.js

@@ -0,0 +1,33 @@
+export function admittedDetails(runId, payload) {
+    return {
+        runId,
+        generation: 1,
+        submission: payload["submission"] ?? null,
+        input: payload["input"] ?? null,
+        resolver: payload["resolver"] ?? null,
+        observation: null,
+    };
+}
+function count(value) {
+    return value === undefined ? null : Number(value);
+}
+export function observed(details, event) {
+    const { payload } = event;
+    return {
+        ...details,
+        observation: {
+            condition: payload["condition"] ?? "",
+            reason: payload["reason"] ?? "",
+            evidence: payload["evidence"] ?? null,
+            retryAt: payload["retryAt"] ?? null,
+            operationId: payload["operationId"] ?? null,
+            attempt: count(payload["attempt"]),
+            limit: count(payload["limit"]),
+            sequence: event.sequence,
+            recordedAt: event.recordedAt,
+        },
+    };
+}
+export function continued(details) {
+    return { ...details, generation: details.generation + 1 };
+}

package/dist/src/authority/dispatch-decision.d.ts

@@ -0,0 +1,40 @@
+export interface DispatchRead {
+    readonly attempt: {
+        readonly outcome: string | null;
+        readonly inputDigest: string;
+        readonly leaseGeneration: number | null;
+    } | undefined;
+    readonly released: boolean;
+    readonly runStatus: string;
+    readonly workflow: string;
+    readonly pinned: boolean;
+    readonly operation: {
+        readonly status: string;
+        readonly capability: string;
+        readonly units: number;
+    } | undefined;
+    readonly budget: {
+        readonly limit: number;
+        readonly spent: number;
+        readonly capabilities: readonly string[];
+        readonly exhaustedSequence: number | null;
+    } | undefined;
+    readonly lease: {
+        readonly operationId: string;
+        readonly generation: number;
+        readonly expiresAt: string;
+        readonly state: string;
+    } | undefined;
+}
+export interface DispatchCheck {
+    readonly intent: {
+        readonly operationId: string;
+        readonly inputDigest: string;
+        readonly computedDigest: string;
+        readonly workflow: string;
+        readonly leaseGeneration?: number;
+    };
+    readonly now: string;
+}
+export type DispatchDecision = "stale" | "withheld" | "refused" | "blocked" | "send";
+export declare function dispatchDecision(read: DispatchRead, check: DispatchCheck): DispatchDecision;

package/dist/src/authority/dispatch-decision.js

@@ -0,0 +1,47 @@
+import { authorizeEffect } from "../effect-authorization.js";
+import { isAfter } from "./instants.js";
+function bound(read, intent) {
+    const { attempt, lease, operation } = read;
+    if (attempt === undefined || lease === undefined || operation === undefined)
+        return false;
+    return [
+        attempt.outcome === null,
+        attempt.inputDigest === intent.inputDigest,
+        intent.computedDigest === intent.inputDigest,
+        read.workflow === intent.workflow,
+        attempt.leaseGeneration === lease.generation,
+        intent.leaseGeneration === lease.generation,
+        lease.operationId === intent.operationId,
+        lease.state !== "released",
+    ].every(Boolean);
+}
+function sendable(read, now) {
+    return [
+        !read.released,
+        read.runStatus === "running",
+        read.operation?.status === "dispatch-pending",
+        read.lease?.state === "held",
+        isAfter(read.lease?.expiresAt ?? "", now),
+    ].every(Boolean);
+}
+function authorized(read) {
+    const { budget, operation } = read;
+    if (budget === undefined || operation === undefined)
+        return false;
+    if (budget.exhaustedSequence !== null)
+        return false;
+    const result = authorizeEffect({ capabilities: budget.capabilities }, {
+        budget: { limit: budget.limit, spent: budget.spent - operation.units },
+        request: { capability: operation.capability, units: operation.units },
+    });
+    return result.kind === "authorized";
+}
+export function dispatchDecision(read, check) {
+    if (!bound(read, check.intent))
+        return "stale";
+    if (!sendable(read, check.now))
+        return "withheld";
+    if (!authorized(read))
+        return "refused";
+    return read.pinned ? "send" : "blocked";
+}

package/dist/src/authority/effect-requests.d.ts

@@ -0,0 +1,2 @@
+import { type EffectContext, type EffectResult, type EffectState } from "./operations.ts";
+export declare function requested(effects: EffectState, context: EffectContext): EffectResult;

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

@@ -0,0 +1,139 @@
+import { operationScope } from "../operation-identity.js";
+import { authorization } from "./budgets.js";
+import { current, ownedLease } from "./leases.js";
+import { cancelledOperation, count, field, rejected, runOperations, withOperation, } from "./operations.js";
+const admittingStatuses = ["running", "paused", "waiting_gate"];
+const terminalStatuses = ["completed", "failed", "cancelled"];
+const compared = [
+    "capability",
+    "method",
+    "target",
+    "payload",
+    "inputDigest",
+];
+function refusal(context) {
+    const { event, runStatus } = context;
+    if (terminalStatuses.includes(runStatus))
+        return "terminal-run";
+    if (!admittingStatuses.includes(runStatus))
+        return "run-not-running";
+    const scope = operationScope(field(event, "operationId"));
+    if (scope?.run !== event.runId)
+        return "operation-scope-mismatch";
+    if (runOperations.includes(scope.operation))
+        return "operation-scope-mismatch";
+    return undefined;
+}
+function leaseKeyOf(event) {
+    return event.payload["resource"] ?? field(event, "operationId");
+}
+function equalInput(operation, event) {
+    return (compared.every((name) => operation[name] === field(event, name)) &&
+        operation.units === count(event, "units") &&
+        operation.leaseKey === leaseKeyOf(event));
+}
+function waitReason(effects, wait) {
+    const lease = effects.leases[wait.leaseKey];
+    if (lease !== undefined && lease.state !== "released")
+        return "resource";
+    return wait.runStatus === "running" ? "ready" : "run-not-running";
+}
+function requestedOperation(event, outcome) {
+    return {
+        runId: event.runId,
+        operationId: field(event, "operationId"),
+        capability: field(event, "capability"),
+        method: field(event, "method"),
+        target: field(event, "target"),
+        payload: field(event, "payload"),
+        inputDigest: field(event, "inputDigest"),
+        units: count(event, "units"),
+        leaseKey: leaseKeyOf(event),
+        recoveryLimit: count(event, "recoveryLimit"),
+        ...outcome,
+        attempts: 0,
+        receipt: null,
+        worker: null,
+        result: null,
+        requestedSequence: event.sequence,
+        settledSequence: null,
+    };
+}
+function withoutWaits(operations, event) {
+    return Object.fromEntries(Object.entries(operations).map(([operationId, operation]) => [
+        operationId,
+        operation.runId === event.runId && operation.status === "waiting"
+            ? cancelledOperation(operation, {
+                reason: "budget-exhausted",
+                sequence: event.sequence,
+            })
+            : operation,
+    ]));
+}
+function admitted(effects, context) {
+    const { event, runStatus } = context;
+    const operationId = field(event, "operationId");
+    const { reason, budget } = authorization(effects.budgets[event.runId], event);
+    const budgets = budget === undefined
+        ? effects.budgets
+        : { ...effects.budgets, [event.runId]: budget };
+    const remaining = reason === "budget-exhausted"
+        ? withoutWaits(effects.operations, event)
+        : effects.operations;
+    const operation = reason === null
+        ? requestedOperation(event, {
+            status: "waiting",
+            reason: waitReason(effects, {
+                leaseKey: leaseKeyOf(event),
+                runStatus,
+            }),
+            waitSequence: event.sequence,
+        })
+        : requestedOperation(event, {
+            status: "refused",
+            reason,
+            waitSequence: null,
+        });
+    return {
+        kind: "changed",
+        effects: withOperation({ ...effects, budgets, operations: remaining }, operation),
+        disposition: {
+            operationId,
+            disposition: reason === null ? "admitted" : "refused",
+            reason,
+        },
+    };
+}
+export function requested(effects, context) {
+    const refused = refusal(context);
+    if (refused !== undefined)
+        return rejected(refused);
+    const { event } = context;
+    const operationId = field(event, "operationId");
+    const existing = effects.operations[operationId];
+    if (existing !== undefined)
+        return equalInput(existing, event)
+            ? {
+                kind: "changed",
+                effects,
+                disposition: { operationId, disposition: "existing", reason: null },
+            }
+            : rejected("changed-operation-input");
+    const denied = denial(effects, event);
+    if (denied === undefined)
+        return admitted(effects, context);
+    return {
+        kind: "changed",
+        effects,
+        disposition: { operationId, disposition: "denied", reason: denied },
+    };
+}
+function denial(effects, event) {
+    const source = effects.operations[event.payload["source"] ?? ""];
+    if (event.payload["source"] === undefined)
+        return undefined;
+    const lease = source?.runId === event.runId ? ownedLease(effects, source) : undefined;
+    if (lease?.generation !== count(event, "sourceGeneration"))
+        return "retired-lease-generation";
+    return current(lease, event) ? undefined : "lease-expired";
+}

package/dist/src/authority/effect-results.d.ts

@@ -0,0 +1,4 @@
+import { type EffectContext, type EffectEvent, type EffectResult, type EffectState } from "./operations.ts";
+export declare function reported(effects: EffectState, context: EffectContext): EffectResult;
+export declare function stopReported(effects: EffectState, event: EffectEvent): EffectState;
+export declare function reconciled(effects: EffectState, context: EffectContext): EffectResult;