cloving 0.3.19 → 1.0.1

package/dist/src/authority/instants.js

@@ -0,0 +1,38 @@
+const instant = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{3})?Z$/;
+function leap(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+function daysIn(year, month) {
+    if (month === 2)
+        return leap(year) ? 29 : 28;
+    return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}
+function calendar(match) {
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const bounds = [
+        [month, 1, 12],
+        [Number(match[3]), 1, daysIn(year, month)],
+        [Number(match[4]), 0, 23],
+        [Number(match[5]), 0, 59],
+        [Number(match[6]), 0, 59],
+    ];
+    return bounds.every(([value, minimum, maximum]) => value >= minimum && value <= maximum);
+}
+export function isInstant(value) {
+    if (typeof value !== "string")
+        return false;
+    const match = instant.exec(value);
+    return match !== null && calendar(match);
+}
+function milliseconds(value) {
+    return value.length === 20 ? `${value.slice(0, 19)}.000Z` : value;
+}
+export function notBefore(value, bound) {
+    return (isInstant(value) &&
+        isInstant(bound) &&
+        milliseconds(value) >= milliseconds(bound));
+}
+export function isAfter(value, bound) {
+    return notBefore(value, bound) && !notBefore(bound, value);
+}

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

@@ -0,0 +1,15 @@
+import { type EffectContext, type EffectResult, type EffectState, type Lease, type Operation } from "./operations.ts";
+export declare function ownedLease(effects: EffectState, operation: Operation): Lease | undefined;
+export declare function current(lease: Lease, event: {
+    readonly recordedAt: string;
+}): boolean;
+export declare function granted(effects: EffectState, context: EffectContext): EffectResult;
+export declare function expired(effects: EffectState, context: EffectContext): EffectResult;
+interface Promotable {
+    readonly effects: EffectState;
+    readonly runs: Readonly<Record<string, {
+        readonly status: string;
+    }>>;
+}
+export declare function promotions(state: Promotable, bound: number): readonly Operation[];
+export {};

package/dist/src/authority/leases.js

@@ -0,0 +1,113 @@
+import { isAfter, notBefore } from "./instants.js";
+import { count, field, rejected, withOperation, } from "./operations.js";
+export function ownedLease(effects, operation) {
+    const lease = effects.leases[operation.leaseKey];
+    const owned = lease?.operationId === operation.operationId && lease.state !== "released";
+    return owned ? lease : undefined;
+}
+export function current(lease, event) {
+    return (lease.state === "held" && !notBefore(event.recordedAt, lease.expiresAt));
+}
+function grantRefusal(effects, grant) {
+    const { operation, event, runStatus } = grant;
+    if (operation.status !== "waiting")
+        return "operation-not-waiting";
+    if (runStatus !== "running")
+        return "run-not-running";
+    const lease = effects.leases[operation.leaseKey];
+    if (lease !== undefined && lease.state !== "released")
+        return "resource-held";
+    if (count(event, "leaseGeneration") !== (lease?.generation ?? 0) + 1)
+        return "stale-lease-generation";
+    if (effects.holding >= count(event, "capacity"))
+        return "capacity-exceeded";
+    if (!isAfter(field(event, "expiresAt"), event.recordedAt))
+        return "invalid-lease-expiry";
+    return undefined;
+}
+export function granted(effects, context) {
+    const { event } = context;
+    const operation = effects.operations[field(event, "operationId")];
+    if (operation?.runId !== event.runId)
+        return rejected("unknown-operation");
+    const refusal = grantRefusal(effects, { ...context, operation });
+    if (refusal !== undefined)
+        return rejected(refusal);
+    const lease = {
+        resourceKey: operation.leaseKey,
+        operationId: operation.operationId,
+        generation: count(event, "leaseGeneration"),
+        expiresAt: field(event, "expiresAt"),
+        state: "held",
+        grantedSequence: event.sequence,
+    };
+    return {
+        kind: "changed",
+        effects: {
+            ...withOperation(effects, {
+                ...operation,
+                status: "dispatch-pending",
+                reason: null,
+                waitSequence: null,
+            }),
+            leases: { ...effects.leases, [lease.resourceKey]: lease },
+            holding: effects.holding + 1,
+        },
+        added: [operation.operationId],
+    };
+}
+function expiryRefusal(lease, expiry) {
+    const { operation, event } = expiry;
+    const held = lease?.operationId === operation.operationId && lease.state === "held";
+    if (!held)
+        return "lease-not-held";
+    if (lease.generation !== count(event, "leaseGeneration"))
+        return "stale-lease-generation";
+    if (!notBefore(event.recordedAt, lease.expiresAt))
+        return "lease-not-expired";
+    return undefined;
+}
+const expiring = ["dispatch-pending", "running"];
+export function expired(effects, context) {
+    const { event } = context;
+    const operation = effects.operations[field(event, "operationId")];
+    if (operation?.runId !== event.runId)
+        return rejected("unknown-operation");
+    const lease = effects.leases[operation.leaseKey];
+    const refusal = expiryRefusal(lease, { ...context, operation });
+    if (refusal !== undefined || lease === undefined)
+        return rejected(refusal ?? "lease-not-held");
+    const recovering = expiring.includes(operation.status)
+        ? { ...operation, status: "recovering", reason: "lease-expired" }
+        : operation;
+    return {
+        kind: "changed",
+        effects: {
+            ...withOperation(effects, recovering),
+            leases: {
+                ...effects.leases,
+                [lease.resourceKey]: { ...lease, state: "expired" },
+            },
+        },
+    };
+}
+function free(effects, leaseKey) {
+    const lease = effects.leases[leaseKey];
+    return lease === undefined || lease.state === "released";
+}
+export function promotions(state, bound) {
+    const { effects, runs } = state;
+    const waiting = Object.values(effects.operations)
+        .filter((operation) => operation.status === "waiting" &&
+        runs[operation.runId]?.status === "running" &&
+        free(effects, operation.leaseKey))
+        .sort((left, right) => (left.waitSequence ?? 0) - (right.waitSequence ?? 0) ||
+        (left.operationId < right.operationId ? -1 : 1));
+    const keys = new Set();
+    const oldest = waiting.filter((operation) => {
+        const first = !keys.has(operation.leaseKey);
+        keys.add(operation.leaseKey);
+        return first;
+    });
+    return oldest.slice(0, Math.max(0, bound - effects.holding));
+}

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

@@ -0,0 +1,101 @@
+export type OperationStatus = "refused" | "waiting" | "dispatch-pending" | "running" | "recovering" | "blocked" | "completed" | "failed" | "stopped" | "cancelled";
+export interface Operation {
+    readonly runId: string;
+    readonly operationId: string;
+    readonly capability: string;
+    readonly method: string;
+    readonly target: string;
+    readonly payload: string;
+    readonly inputDigest: string;
+    readonly units: number;
+    readonly leaseKey: string;
+    readonly recoveryLimit: number;
+    readonly status: OperationStatus;
+    readonly reason: string | null;
+    readonly attempts: number;
+    readonly receipt: string | null;
+    readonly worker: string | null;
+    readonly result: string | null;
+    readonly requestedSequence: number;
+    readonly waitSequence: number | null;
+    readonly settledSequence: number | null;
+}
+export interface Lease {
+    readonly resourceKey: string;
+    readonly operationId: string;
+    readonly generation: number;
+    readonly expiresAt: string;
+    readonly state: "held" | "expired" | "released";
+    readonly grantedSequence: number;
+}
+export interface RunBudget {
+    readonly runId: string;
+    readonly limit: number;
+    readonly spent: number;
+    readonly capabilities: readonly string[];
+    readonly exhaustedSequence: number | null;
+}
+export interface StoppedOperation {
+    readonly runId: string;
+    readonly sequence: number;
+}
+export interface EffectState {
+    readonly budgets: Readonly<Record<string, RunBudget>>;
+    readonly operations: Readonly<Record<string, Operation>>;
+    readonly leases: Readonly<Record<string, Lease>>;
+    readonly holding: number;
+    readonly stops: Readonly<Record<string, StoppedOperation>>;
+}
+export declare const emptyEffects: EffectState;
+export interface Disposition {
+    readonly operationId: string;
+    readonly disposition: string;
+    readonly reason: string | null;
+}
+export interface Evidence extends Disposition {
+    readonly sequence: number;
+    readonly runId: string;
+}
+export declare function evidenceOf(event: {
+    readonly sequence: number;
+    readonly runId: string;
+}, disposition: Disposition | undefined): readonly Evidence[];
+export interface EffectChange {
+    readonly kind: "changed";
+    readonly effects: EffectState;
+    readonly added?: readonly string[];
+    readonly released?: readonly string[];
+    readonly disposition?: Disposition;
+}
+export type EffectResult = EffectChange | {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+export interface EffectEvent {
+    readonly sequence: number;
+    readonly runId: string;
+    readonly recordedAt: string;
+    readonly payload: Readonly<Record<string, string>>;
+}
+export interface EffectContext {
+    readonly event: EffectEvent;
+    readonly runStatus: string;
+}
+export declare const runOperations: string[];
+export declare function namesRunIntent(operationId: string, runId: string): boolean;
+export declare function isHolding(operation: {
+    readonly status: string;
+}): boolean;
+export declare function isFinal(operation: Operation): boolean;
+export declare function rejected(reason: string): EffectResult;
+export declare function field(event: EffectEvent, name: string): string;
+export declare function count(event: EffectEvent, name: string): number;
+export declare function withOperation(effects: EffectState, operation: Operation): EffectState;
+export declare function cancelledOperation(operation: Operation, cancellation: {
+    readonly reason: string;
+    readonly sequence: number;
+}): Operation;
+export declare function endedRun(effects: EffectState, event: {
+    readonly runId: string;
+    readonly sequence: number;
+}): EffectState;

package/dist/src/authority/operations.js

@@ -0,0 +1,75 @@
+import { operationScope } from "../operation-identity.js";
+export const emptyEffects = {
+    budgets: {},
+    operations: {},
+    leases: {},
+    holding: 0,
+    stops: {},
+};
+export function evidenceOf(event, disposition) {
+    if (disposition === undefined)
+        return [];
+    return [{ sequence: event.sequence, runId: event.runId, ...disposition }];
+}
+const holdingStatuses = [
+    "dispatch-pending",
+    "running",
+    "recovering",
+    "blocked",
+];
+const finalStatuses = [
+    "refused",
+    "completed",
+    "failed",
+    "stopped",
+    "cancelled",
+];
+export const runOperations = ["start-run", "continue-run"];
+export function namesRunIntent(operationId, runId) {
+    const scope = operationScope(operationId);
+    return scope?.run === runId && runOperations.includes(scope.operation);
+}
+export function isHolding(operation) {
+    return holdingStatuses.includes(operation.status);
+}
+export function isFinal(operation) {
+    return finalStatuses.includes(operation.status);
+}
+export function rejected(reason) {
+    return { kind: "invalid", reason };
+}
+export function field(event, name) {
+    return event.payload[name] ?? "";
+}
+export function count(event, name) {
+    return Number(event.payload[name]);
+}
+export function withOperation(effects, operation) {
+    return {
+        ...effects,
+        operations: { ...effects.operations, [operation.operationId]: operation },
+    };
+}
+export function cancelledOperation(operation, cancellation) {
+    return {
+        ...operation,
+        status: "cancelled",
+        reason: cancellation.reason,
+        waitSequence: null,
+        settledSequence: cancellation.sequence,
+    };
+}
+export function endedRun(effects, event) {
+    return {
+        ...effects,
+        operations: Object.fromEntries(Object.entries(effects.operations).map(([operationId, operation]) => [
+            operationId,
+            operation.runId === event.runId && operation.status === "waiting"
+                ? cancelledOperation(operation, {
+                    reason: "run-ended",
+                    sequence: event.sequence,
+                })
+                : operation,
+        ])),
+    };
+}

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

@@ -0,0 +1,27 @@
+import { type AuthorityState } from "./transitions.ts";
+export interface WorldRun {
+    readonly runId: string;
+    readonly receipt: string;
+    readonly status: string;
+    readonly outcome?: string;
+    readonly outcomeReason?: string;
+    readonly operationId?: string | null;
+    readonly createdAt?: string;
+}
+export type WorldReport = {
+    readonly kind: "unknown-world-run" | "world-run-unreadable";
+    readonly runId: string;
+    readonly receipt: string;
+} | {
+    readonly kind: "world-run-absent";
+    readonly runId: string;
+    readonly operationId: string;
+};
+export interface Reconciliation {
+    readonly commands: readonly Readonly<Record<string, unknown>>[];
+    readonly conflicts: readonly string[];
+    readonly reports: readonly WorldReport[];
+}
+type Reconciled = Pick<AuthorityState, "runs" | "intents" | "details" | "gates" | "commands">;
+export declare function reconcile(state: Reconciled, worldRuns: readonly WorldRun[]): Reconciliation;
+export {};

package/dist/src/authority/reconciliation.js

@@ -0,0 +1,147 @@
+import { gateContinuation } from "./gate-reduction.js";
+import { isBlockedReason } from "../workflow-contracts.js";
+import { continues } from "./gates.js";
+import { startOperation } from "./reduction.js";
+import { terminal, } from "./transitions.js";
+const progress = {
+    queued: { running: "mark-started", completed: "mark-started" },
+    running: { completed: "complete-run" },
+};
+const endings = {
+    failed: "world-run-failed",
+    cancelled: "world-run-cancelled",
+};
+export function reconcile(state, worldRuns) {
+    const observed = Map.groupBy(worldRuns, (world) => world.runId);
+    const known = Object.values(state.runs).map((run) => ({
+        run,
+        segments: (observed.get(run.runId) ?? []).toSorted((first, second) => created(first) < created(second) ? -1 : 1),
+    }));
+    return {
+        commands: known.flatMap((found) => planned(state, found)),
+        conflicts: known
+            .filter((found) => conflicting(found.segments))
+            .map((found) => found.run.runId),
+        reports: [
+            ...worldRuns.flatMap((world) => unusable(state, world)),
+            ...known.flatMap((found) => absent(state, found)),
+        ],
+    };
+}
+function unusable(state, world) {
+    const { runId, receipt } = world;
+    if (!Object.hasOwn(state.runs, runId))
+        return [{ kind: "unknown-world-run", runId, receipt }];
+    if (world.status !== "unreadable")
+        return [];
+    return [{ kind: "world-run-unreadable", runId, receipt }];
+}
+function dispatched(state, run) {
+    const pending = state.intents.map((intent) => intent.operationId);
+    const continued = Object.values(state.gates)
+        .filter((gate) => gate.runId === run.runId)
+        .filter(continues)
+        .map((gate) => gateContinuation(gate).operationId);
+    return [startOperation(run.runId), ...continued].filter((operationId) => !pending.includes(operationId));
+}
+function missing(state, found) {
+    const { run, segments } = found;
+    const tags = segments.map((world) => world.operationId ?? null);
+    if (terminal.includes(run.status) || tags.includes(null))
+        return [];
+    return dispatched(state, run).filter((operationId) => !tags.includes(operationId));
+}
+function absent(state, found) {
+    return missing(state, found).map((operationId) => ({
+        kind: "world-run-absent",
+        runId: found.run.runId,
+        operationId,
+    }));
+}
+function created(world) {
+    return `${world.createdAt ?? ""} ${world.receipt}`;
+}
+function conflicting(runs) {
+    const operations = runs.map((world) => world.operationId ?? null);
+    return (runs.length > 1 &&
+        (operations.includes(null) || new Set(operations).size < runs.length));
+}
+function planned(state, found) {
+    const { run, segments } = found;
+    const world = segments.at(-1);
+    if (!world || terminal.includes(run.status))
+        return [];
+    if (conflicting(segments))
+        return unsent(state, conflict(found));
+    const pending = state.intents.some((intent) => intent.runId === run.runId && intent.kind !== "protected-effect");
+    if (pending)
+        return [];
+    const failed = segments.find((segment) => Object.hasOwn(endings, segment.status));
+    if (failed)
+        return ended(state, {
+            run,
+            world: failed,
+            reason: String(endings[failed.status]),
+        });
+    return next(state, { ...found, world });
+}
+function next(state, observed) {
+    const { run, world } = observed;
+    const kind = progress[run.status]?.[world.status];
+    if (kind === undefined)
+        return [];
+    const waits = kind === "complete-run" && world.outcome === "waiting_for_decision";
+    if (!waits)
+        return [moved(kind, observed)];
+    const held = run.gates.length > 0 || missing(state, observed).length > 0;
+    if (held)
+        return [];
+    return ended(state, { run, world, reason: "world-run-waits-without-gate" });
+}
+function moved(kind, observed) {
+    const { run, world } = observed;
+    return {
+        kind,
+        commandId: `${kind}:${world.receipt}`,
+        runId: run.runId,
+        expectedRevision: run.revision,
+        ...(kind === "complete-run" ? completionOutcome(world) : {}),
+    };
+}
+function completionOutcome(world) {
+    const { outcome, outcomeReason } = world;
+    if (outcome !== "handoff_requested" && outcome !== "blocked")
+        return {};
+    if (outcome !== "blocked" || !isBlockedReason(outcomeReason))
+        return { outcome };
+    return { outcome, outcomeReason };
+}
+function noted(observed, evidence) {
+    const { run, world, reason } = observed;
+    return {
+        kind: "report-observation",
+        commandId: `observe:${reason}:${world.receipt}`,
+        runId: run.runId,
+        condition: "infrastructure-failure",
+        reason,
+        evidence,
+    };
+}
+function unsent(state, command) {
+    const recorded = Object.hasOwn(state.commands, String(command["commandId"]));
+    return recorded ? [] : [command];
+}
+function conflict(found) {
+    const [world = { runId: "", receipt: "", status: "" }] = found.segments;
+    return noted({ run: found.run, world, reason: "world-run-conflict" }, found.segments
+        .slice(0, 2)
+        .map((segment) => `world-run:${segment.receipt}`)
+        .join("/"));
+}
+function ended(state, observed) {
+    const { run, world } = observed;
+    return [
+        ...unsent(state, noted(observed, `world-run:${world.receipt}`)),
+        ...(run.status === "paused" ? [] : [moved("fail-run", observed)]),
+    ];
+}

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

@@ -0,0 +1,41 @@
+import { type AuthorityEvent, type AuthorityState, type EffectIntent } from "./transitions.ts";
+import { type Disposition, type Evidence } from "./operations.ts";
+export type { AuthorityEvent, AuthorityState, EffectIntent, RunState, RunStatus, } from "./transitions.ts";
+export type CommandResult = {
+    readonly kind: "accepted";
+    readonly events: readonly AuthorityEvent[];
+    readonly state: AuthorityState;
+    readonly intents: readonly EffectIntent[];
+    readonly disposition?: Disposition;
+} | {
+    readonly kind: "duplicate";
+    readonly sequence: number;
+} | {
+    readonly kind: "rejected";
+    readonly reason: string;
+};
+export declare const emptyAuthority: AuthorityState;
+export declare function execute(state: AuthorityState, proposed: {
+    readonly command: unknown;
+    readonly recordedAt: string;
+}): CommandResult;
+export declare function rebuild(events: readonly unknown[]): AuthorityState;
+export declare function applyEvent(state: AuthorityState, entry: {
+    readonly value: unknown;
+    readonly index: number;
+}): {
+    readonly state: AuthorityState;
+    readonly event: AuthorityEvent;
+    readonly evidence: readonly Evidence[];
+};
+type Statuses = Readonly<Record<string, {
+    readonly status: string;
+}>>;
+export interface Eligibility {
+    readonly intents: readonly EffectIntent[];
+    readonly runs: Statuses;
+    readonly effects: {
+        readonly operations: Statuses;
+    };
+}
+export declare function eligibleIntents(state: Eligibility): readonly EffectIntent[];