cloving 1.2.0 → 1.4.0

package/dist/src/authority/commands.js

@@ -8,6 +8,9 @@ const digest = /^sha256:[0-9a-f]{64}$/;
 const operation = /^[\x20-\x7e]{1,512}$/;
 export const commandEvents = {
     "admit-run": "run.created",
+    "open-command-wait": "command-wait.opened",
+    "check-command-wait": "command-wait.checked",
+    "expire-command-wait": "command-wait.expired",
     "mark-started": "run.started",
     "open-gate": "gate.opened",
     "register-wait": "gate.wait-registered",
@@ -25,9 +28,27 @@ export const commandEvents = {
     "expire-lease": "lease.expired",
     "report-effect": "effect.reported",
     "record-outcome": "operation.reconciled",
+    "record-schedule-skip": "schedule.skipped",
 };
 const revised = { required: ["expectedRevision"] };
 const shapes = {
+    "expire-command-wait": { required: ["waitName"] },
+    "check-command-wait": { required: ["waitName", "inputDigest"] },
+    "open-command-wait": {
+        required: [
+            "waitName",
+            "target",
+            "payload",
+            "maximumWaitSeconds",
+            "pollEverySeconds",
+        ],
+        consistent: (fields) => Number(fields["pollEverySeconds"]) <=
+            Number(fields["maximumWaitSeconds"]),
+    },
+    "record-schedule-skip": {
+        required: ["workflowId", "slot"],
+        validators: { slot: positive },
+    },
     "admit-run": {
         required: ["workflow"],
         optional: [
@@ -48,14 +69,16 @@ const shapes = {
     "mark-started": revised,
     "open-gate": {
         required: ["gateId", "expectedRevision"],
-        optional: ["gateKind", "subject", "prompt", "expiresAt"],
+        optional: ["gateKind", "subject", "prompt", "expiresAt", "waitMode"],
+        validators: { waitMode: (value) => value === "hook" },
         groups: [["gateKind", "subject", "prompt"]],
-        consistent: (fields) => fields["expiresAt"] === undefined || fields["gateKind"] !== undefined,
+        consistent: (fields) => (fields["expiresAt"] === undefined && fields["waitMode"] === undefined) ||
+            fields["gateKind"] !== undefined,
     },
     "register-wait": { required: ["gateId"] },
     "decide-gate": {
         required: ["gateId", "decision", "expectedRevision"],
-        optional: ["generation", "subject", "answer"],
+        optional: ["generation", "subject", "answer", "actor"],
         groups: [["generation", "subject"]],
         consistent: (fields) => {
             const typed = fields["generation"] !== undefined;
@@ -97,7 +120,14 @@ const shapes = {
     "cancel-run": revised,
     "report-observation": {
         required: ["condition", "reason"],
-        optional: ["evidence", "retryAt", "attempt", "limit", "operationId"],
+        optional: [
+            "evidence",
+            "retryAt",
+            "attempt",
+            "limit",
+            "operationId",
+            "expectedObservation",
+        ],
         groups: [["attempt", "limit"]],
     },
     "record-dispatch": { required: ["operationId", "receipt"] },
@@ -127,7 +157,7 @@ const shapes = {
             "worker",
             "outcome",
         ],
-        optional: ["result", "reason", "evidence"],
+        optional: ["result", "reason", "evidence", "commandOutput"],
         consistent: (fields) => reportedOutcomes.includes(String(fields["outcome"])) &&
             (fields["outcome"] === "failed" ||
                 (fields["result"] !== undefined) ===
@@ -143,6 +173,7 @@ const shapes = {
             "result",
             "reason",
             "evidence",
+            "commandOutput",
         ],
     },
 };
@@ -150,6 +181,7 @@ const reportedOutcomes = ["completed", "failed", "stopped"];
 const outcomes = [...reportedOutcomes, "accepted", "not-started", "unknown"];
 const conditions = [
     "working",
+    "waiting-run",
     "quota-wait",
     "infrastructure-failure",
     "code-failure",
@@ -249,7 +281,12 @@ export function isCapabilityList(value) {
         JSON.stringify(list) === value);
 }
 const validators = {
+    commandOutput: (value) => typeof value === "string",
+    waitName: (value) => typeof value === "string" && /^[A-Za-z0-9-]{1,64}$/.test(value),
+    maximumWaitSeconds: (value) => whole(value) && value >= 60 && value <= 2_592_000,
+    pollEverySeconds: (value) => whole(value) && value >= 60 && value <= 86_400,
     expectedRevision: positive,
+    expectedObservation: whole,
     generation: positive,
     attempt: positive,
     limit: positive,
@@ -274,7 +311,11 @@ const validators = {
     condition: (value) => typeof value === "string" && conditions.includes(value),
     expiresAt: isInstant,
     retryAt: isInstant,
+    actor: isDeviceActor,
 };
+export function isDeviceActor(value) {
+    return (typeof value === "string" && /^device:[A-Za-z0-9_-]{1,64}$/.test(value));
+}
 export function isIdentifier(value) {
     return typeof value === "string" && identifier.test(value);
 }

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

@@ -1,4 +1,9 @@
+import type { CommandWaitState } from "./command-waits.ts";
 export interface DispatchRead {
+    readonly commandWait?: {
+        readonly wait: CommandWaitState;
+        readonly declared: boolean;
+    };
     readonly attempt: {
         readonly outcome: string | null;
         readonly inputDigest: string;
@@ -12,6 +17,9 @@ export interface DispatchRead {
         readonly status: string;
         readonly capability: string;
         readonly units: number;
+        readonly method?: string;
+        readonly target?: string;
+        readonly payload?: string;
     } | undefined;
     readonly budget: {
         readonly limit: number;

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

@@ -1,3 +1,5 @@
+import { operationPhase } from "../operation-identity.js";
+import { instantMilliseconds } from "./instants.js";
 import { authorizeEffect } from "../effect-authorization.js";
 import { isAfter } from "./instants.js";
 function bound(read, intent) {
@@ -39,12 +41,35 @@ function authorized(read) {
     });
     return result.kind === "authorized";
 }
+function authorizedWait(read, check) {
+    const { commandWait, operation } = read;
+    if (commandWait === undefined || operation === undefined)
+        return false;
+    const { wait, declared } = commandWait;
+    const now = instantMilliseconds(check.now);
+    return [
+        declared,
+        wait.state === "waiting",
+        wait.checkOperation === check.intent.operationId,
+        wait.nextCheckAt !== null && now >= wait.nextCheckAt,
+        now < wait.deadline,
+        read.budget?.capabilities.includes("command"),
+        operation.capability === "command",
+        operation.units === 1,
+        operation.method === `run:${wait.command}`,
+        operation.target === wait.command,
+        operation.payload === wait.inputDigest,
+    ].every(Boolean);
+}
 export function dispatchDecision(read, check) {
     if (!bound(read, check.intent))
         return "stale";
     if (!sendable(read, check))
         return "withheld";
-    if (!authorized(read))
+    const allowed = operationPhase(check.intent.operationId) === "command-wait"
+        ? authorizedWait(read, check)
+        : authorized(read);
+    if (!allowed)
         return "refused";
     return read.pinned ? "send" : "blocked";
 }

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

@@ -1,4 +1,4 @@
-import { operationScope } from "../operation-identity.js";
+import { operationScope, operationPhase } 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";
@@ -18,7 +18,8 @@ function refusal(context) {
     if (!admittingStatuses.includes(runStatus))
         return "run-not-running";
     const scope = operationScope(field(event, "operationId"));
-    if (scope?.run !== event.runId)
+    if (scope?.run !== event.runId ||
+        operationPhase(field(event, "operationId")) === "command-wait")
         return "operation-scope-mismatch";
     if (runOperations.includes(scope.operation))
         return "operation-scope-mismatch";
@@ -62,7 +63,9 @@ function requestedOperation(event, outcome) {
 function withoutWaits(operations, event) {
     return Object.fromEntries(Object.entries(operations).map(([operationId, operation]) => [
         operationId,
-        operation.runId === event.runId && operation.status === "waiting"
+        operation.runId === event.runId &&
+            operation.status === "waiting" &&
+            operationPhase(operation.operationId) !== "command-wait"
             ? cancelledOperation(operation, {
                 reason: "budget-exhausted",
                 sequence: event.sequence,

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

@@ -1,3 +1,4 @@
+import { operationPhase } from "../operation-identity.js";
 import { current, ownedLease } from "./leases.js";
 import { cancelledOperation, count, field, isFinal, isHolding, namesRunIntent, rejected, withOperation, } from "./operations.js";
 const terminalStatuses = ["completed", "failed", "cancelled"];
@@ -135,8 +136,9 @@ function statedReason(event) {
 }
 function notStarted(effects, subject) {
     const { operation, event, runStatus } = subject;
-    const exhausted = (effects.budgets[operation.runId]?.exhaustedSequence ?? null) !== null ||
-        field(event, "reason") === "budget-exhausted";
+    const exhausted = field(event, "reason") === "budget-exhausted" ||
+        (operationPhase(operation.operationId) !== "command-wait" &&
+            (effects.budgets[operation.runId]?.exhaustedSequence ?? null) !== null);
     const ended = terminalStatuses.includes(runStatus);
     const waiting = {
         ...operation,

package/dist/src/authority/gate-reduction.d.ts

@@ -2,6 +2,7 @@ import { type SettledGate } from "./gates.ts";
 import { type Recorded, type Reduction } from "./reduction-state.ts";
 import { type AuthorityState, type EffectIntent } from "./transitions.ts";
 export declare function gateContinuation(gate: SettledGate): EffectIntent;
+export declare function gateDelivery(gate: SettledGate): EffectIntent;
 export declare function opened(state: AuthorityState, recorded: Recorded): Reduction;
 export declare function decided(state: AuthorityState, recorded: Recorded): Reduction;
 export declare function expired(state: AuthorityState, recorded: Recorded): Reduction;

package/dist/src/authority/gate-reduction.js

@@ -1,4 +1,4 @@
-import { continues, decisionRefusal, expiryRefusal, gateKey, openedGate, reusable, settled, } from "./gates.js";
+import { delivers, decisionRefusal, expiryRefusal, gateKey, openedGate, reusable, settled, } from "./gates.js";
 import { applied, identity, invalid, text, } from "./reduction-state.js";
 import { terminal, transition, } from "./transitions.js";
 export function gateContinuation(gate) {
@@ -14,8 +14,23 @@ export function gateContinuation(gate) {
         }),
     };
 }
+export function gateDelivery(gate) {
+    if (gate.wait !== "hook")
+        return gateContinuation(gate);
+    return {
+        kind: "resume-hook",
+        runId: gate.runId,
+        operationId: identity({
+            run: gate.runId,
+            phase: "gate",
+            round: gate.outcome.sequence,
+            operation: "resume-hook",
+            key: gate.gateId,
+        }),
+    };
+}
 function continuations(gate) {
-    return continues(gate) ? [gateContinuation(gate)] : [];
+    return delivers(gate) ? [gateDelivery(gate)] : [];
 }
 export function opened(state, recorded) {
     const { event, run } = recorded;
@@ -98,7 +113,7 @@ export function registered(state, recorded) {
     const gate = gateOf(state, event);
     if (gate === undefined)
         return invalid("unknown-gate");
-    if (gate.wait === "registered")
+    if (gate.wait !== "pending")
         return invalid("wait-already-registered");
     const next = { ...gate, wait: "registered" };
     return applied(state, {

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

@@ -14,7 +14,7 @@ export interface GateState {
     readonly expiresAt: string | null;
     readonly generation: number;
     readonly revision: number;
-    readonly wait: "registered" | "pending";
+    readonly wait: "registered" | "pending" | "hook";
     readonly outcome: GateOutcome | null;
     readonly openedSequence: number;
 }
@@ -45,4 +45,5 @@ export type ContinuingGate = GateState & {
     };
 };
 export declare function continues(gate: GateState): gate is ContinuingGate;
+export declare function delivers(gate: GateState): gate is ContinuingGate;
 export {};

package/dist/src/authority/gates.js

@@ -22,6 +22,7 @@ export function gateKey(runId, gateId) {
 export function openedGate(opening) {
     const { payload } = opening;
     const kind = kinds[payload["gateKind"] ?? ""] ?? "untyped";
+    const wait = kind === "untyped" ? "registered" : "pending";
     return {
         runId: opening.runId,
         gateId: payload["gateId"] ?? "",
@@ -32,7 +33,7 @@ export function openedGate(opening) {
         expiresAt: payload["expiresAt"] ?? null,
         generation: opening.generation,
         revision: 1,
-        wait: kind === "untyped" ? "registered" : "pending",
+        wait: payload["waitMode"] === "hook" ? "hook" : wait,
         outcome: null,
         openedSequence: opening.sequence,
     };
@@ -75,3 +76,6 @@ export function continues(gate) {
         isSettled(gate) &&
         gate.outcome.decision !== null);
 }
+export function delivers(gate) {
+    return (gate.wait !== "pending" && isSettled(gate) && gate.outcome.decision !== null);
+}

package/dist/src/authority/history-state.d.ts

@@ -1,11 +1,13 @@
 import type { AuthorityState } from "./transitions.ts";
 export declare class HistoryState {
     private state;
+    private readonly commandWaits;
     private readonly runs;
     private readonly commands;
     private readonly details;
     private readonly gates;
     private readonly budgets;
+    private readonly runWaits;
     private readonly runGates;
     private readonly intents;
     private readonly pending;

package/dist/src/authority/history-state.js

@@ -6,11 +6,13 @@ function entry(values, key) {
 }
 export class HistoryState {
     state = emptyAuthority;
+    commandWaits = {};
     runs = {};
     commands = {};
     details = {};
     gates = {};
     budgets = {};
+    runWaits = new Map();
     runGates = new Map();
     intents = new Map();
     pending = new Set();
@@ -20,6 +22,9 @@ export class HistoryState {
             return this.state;
         return {
             ...this.state,
+            ...(this.runWaits.has(event.runId)
+                ? { commandWaits: this.runWaits.get(event.runId) ?? {} }
+                : {}),
             runs: entry(this.runs, event.runId),
             commands: entry(this.commands, event.commandId),
             details: entry(this.details, event.runId),
@@ -32,6 +37,10 @@ export class HistoryState {
         };
     }
     record(state, runId) {
+        const { commandWaits, ...baseState } = state;
+        Object.assign(this.commandWaits, commandWaits);
+        if (commandWaits !== undefined)
+            this.runWaits.set(runId, commandWaits);
         Object.assign(this.runs, state.runs);
         Object.assign(this.commands, state.commands);
         Object.assign(this.details, state.details);
@@ -45,11 +54,14 @@ export class HistoryState {
         for (const intent of remaining)
             this.pending.add(intent);
         this.intents.set(runId, state.intents);
-        this.state = state;
+        this.state = baseState;
     }
     finish() {
         return {
             ...this.state,
+            ...(Object.keys(this.commandWaits).length === 0
+                ? {}
+                : { commandWaits: this.commandWaits }),
             runs: this.runs,
             commands: this.commands,
             details: this.details,

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

@@ -1,3 +1,4 @@
 export declare function isInstant(value: unknown): value is string;
 export declare function notBefore(value: string, bound: string): boolean;
 export declare function isAfter(value: string, bound: string): boolean;
+export declare function instantMilliseconds(value: string): number;

package/dist/src/authority/instants.js

@@ -36,3 +36,24 @@ export function notBefore(value, bound) {
 export function isAfter(value, bound) {
     return notBefore(value, bound) && !notBefore(bound, value);
 }
+function leapDaysBefore(year) {
+    const previous = year - 1;
+    return (Math.floor(previous / 4) -
+        Math.floor(previous / 100) +
+        Math.floor(previous / 400));
+}
+export function instantMilliseconds(value) {
+    if (!isInstant(value))
+        throw new Error("invalid-instant");
+    const year = Number(value.slice(0, 4));
+    const month = Number(value.slice(5, 7));
+    let days = Number(value.slice(8, 10)) - 1;
+    for (let preceding = 1; preceding < month; preceding += 1)
+        days += daysIn(year, preceding);
+    days += 365 * (year - 1970) + leapDaysBefore(year) - leapDaysBefore(1970);
+    return (days * 86_400_000 +
+        Number(value.slice(11, 13)) * 3_600_000 +
+        Number(value.slice(14, 16)) * 60_000 +
+        Number(value.slice(17, 19)) * 1000 +
+        Number(value.slice(20, 23)));
+}

package/dist/src/authority/operations.js

@@ -24,7 +24,7 @@ const finalStatuses = [
     "stopped",
     "cancelled",
 ];
-export const runOperations = ["start-run", "continue-run"];
+export const runOperations = ["start-run", "continue-run", "resume-hook"];
 export function namesRunIntent(operationId, runId) {
     const scope = operationScope(operationId);
     return scope?.run === runId && runOperations.includes(scope.operation);

package/dist/src/authority/reduction-state.d.ts

@@ -1,3 +1,4 @@
+import { type CommandWaitsState } from "./command-waits.ts";
 import { type RunDetails } from "./details.ts";
 import { type GateState } from "./gates.ts";
 import { type Disposition, type EffectState } from "./operations.ts";
@@ -20,6 +21,7 @@ export interface Recorded {
 }
 export interface Change extends Recorded {
     readonly moved?: RunState;
+    readonly commandWaits?: CommandWaitsState;
     readonly gates?: readonly GateState[];
     readonly added?: readonly EffectIntent[];
     readonly questions?: number;

package/dist/src/authority/reduction-state.js

@@ -1,3 +1,4 @@
+import { closedCommandWaits } from "./command-waits.js";
 import { operationIdentity } from "../operation-identity.js";
 import { continued } from "./details.js";
 import { gateKey } from "./gates.js";
@@ -40,12 +41,16 @@ function nextDetails(change) {
 }
 export function applied(state, change) {
     const { event } = change;
+    const waits = change.commandWaits ?? state.commandWaits;
     return {
         kind: "applied",
         ...(change.disposition === undefined
             ? {}
             : { disposition: change.disposition }),
         state: {
+            ...(waits === undefined
+                ? {}
+                : { commandWaits: closedCommandWaits(waits, event) }),
             sequence: event.sequence,
             runs: change.moved
                 ? { ...state.runs, [event.runId]: change.moved }

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

@@ -1,6 +1,6 @@
 import { type Reduction } from "./reduction-state.ts";
 import { type AuthorityEvent, type AuthorityState } from "./transitions.ts";
-export { gateContinuation } from "./gate-reduction.ts";
+export { gateContinuation, gateDelivery } from "./gate-reduction.ts";
 export type { Reduction } from "./reduction-state.ts";
 export declare function startOperation(runId: string): string;
 export declare function reduce(state: AuthorityState, event: AuthorityEvent): Reduction;

package/dist/src/authority/reduction.js

@@ -1,3 +1,6 @@
+import { checkedCommandWait } from "./command-wait-checks.js";
+import { waitEffectTime, waitEffectChange } from "./command-wait-results.js";
+import { commandWaitKey, commandWaitsAfter, validCommandWaitTime, } from "./command-waits.js";
 import { admittedDetails, observed } from "./details.js";
 import { settled } from "./gates.js";
 import { admittedBudgets } from "./budgets.js";
@@ -7,7 +10,7 @@ import { decided, expired, opened, registered } from "./gate-reduction.js";
 import { expired as leaseExpired, granted } from "./leases.js";
 import { applied, identity, invalid, text, } from "./reduction-state.js";
 import { transition, } from "./transitions.js";
-export { gateContinuation } from "./gate-reduction.js";
+export { gateContinuation, gateDelivery } from "./gate-reduction.js";
 function moved(type) {
     return (state, recorded) => {
         const result = transition(recorded.run, {
@@ -36,6 +39,10 @@ function closed(type) {
     };
 }
 function observation(state, recorded) {
+    const expected = recorded.event.payload["expectedObservation"];
+    if (expected !== undefined &&
+        expected !== String(recorded.details.observation?.sequence ?? 0))
+        return invalid("stale-observation");
     return applied(state, {
         ...recorded,
         observed: observed(recorded.details, recorded.event),
@@ -53,6 +60,8 @@ function dispatched(state, recorded) {
 function effect(rule) {
     return (state, recorded) => {
         const { event, run } = recorded;
+        if (!waitEffectTime(state.commandWaits ?? {}, event))
+            return invalid("invalid-recorded-time");
         const result = rule(state.effects, { event, runStatus: run.status });
         if (result.kind === "invalid")
             return result;
@@ -60,6 +69,7 @@ function effect(rule) {
         return applied(state, {
             ...recorded,
             effects: result.effects,
+            ...waitEffectChange(state, { event, result }),
             ...(result.released === undefined ? {} : { released: result.released }),
             ...(result.disposition === undefined
                 ? {}
@@ -74,7 +84,24 @@ function effect(rule) {
         });
     };
 }
+const changeCommandWait = (state, recorded) => {
+    const { event, run } = recorded;
+    const waits = state.commandWaits ?? {};
+    const key = commandWaitKey(event.runId, event.payload["waitName"] ?? "");
+    if (event.type === "command-wait.opened" &&
+        waits[key] === undefined &&
+        run.status !== "running")
+        return invalid("command-wait-run-not-running");
+    const result = commandWaitsAfter(waits, event);
+    return result.kind === "invalid"
+        ? result
+        : applied(state, { ...recorded, commandWaits: result.waits });
+};
 const handlers = {
+    "schedule.skipped": applied,
+    "command-wait.opened": changeCommandWait,
+    "command-wait.checked": checkedCommandWait,
+    "command-wait.expired": changeCommandWait,
     "effect.requested": effect(requested),
     "lease.granted": effect(granted),
     "lease.expired": effect(leaseExpired),
@@ -141,6 +168,8 @@ function created(state, recorded) {
     };
 }
 export function reduce(state, event) {
+    if (!validCommandWaitTime(state.commandWaits ?? {}, event))
+        return invalid("invalid-command-wait-time");
     if (event.sequence !== state.sequence + 1)
         return invalid("sequence-gap");
     if (state.commands[event.commandId])

package/dist/src/authority/status-input.d.ts

@@ -1,10 +1,11 @@
+import type { CommandWaitView } from "./command-wait-view.ts";
 import type { RunDetails } from "./details.ts";
 import type { GateState } from "./gates.ts";
 import type { RunClosure } from "./stop-sequence.ts";
 import type { RunState } from "./transitions.ts";
 export interface OperationSummary {
     readonly operationId: string;
-    readonly kind: "start-run" | "continue-run" | "protected-effect";
+    readonly kind: "start-run" | "continue-run" | "resume-hook" | "protected-effect";
     readonly releasedSequence: number | null;
     readonly outcomes: readonly (string | null)[];
 }
@@ -21,6 +22,7 @@ export interface BudgetSummary {
     readonly spent: number;
 }
 export interface StatusInput {
+    readonly commandWaits: readonly CommandWaitView[];
     readonly run: RunState;
     readonly details: RunDetails | undefined;
     readonly gates: readonly GateState[];

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

@@ -1,3 +1,4 @@
+import type { CommandWaitView } from "./command-wait-view.ts";
 import { type EffectView, type Recovery } from "./status-effects.ts";
 import { type BudgetSummary, type StatusInput } from "./status-input.ts";
 import type { RunStatus } from "./transitions.ts";
@@ -5,10 +6,12 @@ export { unresolved, unresolvedEffects } from "./status-closure.ts";
 export type { EffectView } from "./status-effects.ts";
 export type { Assessment, BudgetSummary, EffectSummary, OperationSummary, StatusInput, } from "./status-input.ts";
 export interface RunView {
+    readonly commandWaits: readonly CommandWaitView[];
     readonly runId: string;
     readonly workflow: string;
     readonly state: RunStatus;
     readonly condition: string;
+    readonly awaitedRunId: string | null;
     readonly revision: number;
     readonly latestSequence: number;
     readonly pendingDecisions: readonly string[];