harnery 0.13.0 → 0.15.0

package/dist/core/work/index.d.ts

@@ -0,0 +1,3 @@
+export { type RunWorkItemInput, runWorkItem } from "./runner.js";
+export { acceptWorkItem, assertWorkId, type CreateWorkItemInput, cancelWorkItem, createWorkItem, listWorkItems, newWorkId, readWorkItem, reconcileAllWorkItems, reconcileWorkItem, reopenWorkItem, WORK_EVENT_SCHEMA_VERSION, WORK_INTENT_SCHEMA_VERSION, type WorkAttempt, type WorkEvent, type WorkEventType, type WorkIntent, type WorkNextAction, type WorkProjection, type WorkRecord, type WorkState, } from "./state.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/work/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/work/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EACL,cAAc,EACd,YAAY,EACZ,KAAK,mBAAmB,EACxB,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,EACT,YAAY,EACZ,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,yBAAyB,EACzB,0BAA0B,EAC1B,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,SAAS,GACf,MAAM,YAAY,CAAC"}

package/dist/core/work/index.js

@@ -0,0 +1,2 @@
+export { runWorkItem } from "./runner.js";
+export { acceptWorkItem, assertWorkId, cancelWorkItem, createWorkItem, listWorkItems, newWorkId, readWorkItem, reconcileAllWorkItems, reconcileWorkItem, reopenWorkItem, WORK_EVENT_SCHEMA_VERSION, WORK_INTENT_SCHEMA_VERSION, } from "./state.js";

package/dist/core/work/read.d.ts

@@ -0,0 +1,2 @@
+export { assertWorkId, listWorkItems, readWorkItem, WORK_EVENT_SCHEMA_VERSION, WORK_INTENT_SCHEMA_VERSION, type WorkAttempt, type WorkEvent, type WorkEventType, type WorkIntent, type WorkNextAction, type WorkProjection, type WorkRecord, type WorkState, } from "./state.js";
+//# sourceMappingURL=read.d.ts.map

package/dist/core/work/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/core/work/read.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,yBAAyB,EACzB,0BAA0B,EAC1B,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,SAAS,GACf,MAAM,YAAY,CAAC"}

package/dist/core/work/read.js

@@ -0,0 +1 @@
+export { assertWorkId, listWorkItems, readWorkItem, WORK_EVENT_SCHEMA_VERSION, WORK_INTENT_SCHEMA_VERSION, } from "./state.js";

package/dist/core/work/runner.d.ts

@@ -0,0 +1,10 @@
+import type { EngineOpts, RunReport } from "../workflow/types.js";
+export interface RunWorkItemInput {
+    coordRoot: string;
+    workId: string;
+    engine: Omit<EngineOpts, "coordRoot" | "runId" | "resumeRunId" | "workItemId">;
+    retry?: boolean;
+    actor?: string;
+}
+export declare function runWorkItem(input: RunWorkItemInput): Promise<RunReport>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/core/work/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/core/work/runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAWlE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,OAAO,GAAG,aAAa,GAAG,YAAY,CAAC,CAAC;IAC/E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CA2D7E"}

package/dist/core/work/runner.js

@@ -0,0 +1,63 @@
+import { resolve } from "node:path";
+import { runWorkflow } from "../workflow/engine.js";
+import { acquireWorkLease, appendReconcileIfChanged, appendWorkEvent, assertWorkflowUnchanged, boundedActor, newWorkflowRunId, readWorkItemIgnoringLease, } from "./state.js";
+export async function runWorkItem(input) {
+    const coordRoot = resolve(input.coordRoot);
+    const release = acquireWorkLease(coordRoot, input.workId);
+    try {
+        const record = readWorkItemIgnoringLease(coordRoot, input.workId);
+        assertWorkflowUnchanged(record.intent);
+        const latest = record.projection.attempts.at(-1);
+        if (record.projection.state === "awaiting_approval" && latest) {
+            if (record.projection.next_action !== "resume") {
+                throw new Error(`work item ${input.workId} is waiting for approval ${latest.approval_id}`);
+            }
+            appendWorkEvent(coordRoot, input.workId, {
+                event: "attempt.resumed",
+                actor: boundedActor(input.actor),
+                reason: "resuming the parked workflow attempt",
+                run_id: latest.run_id,
+                attempt: latest.number,
+            });
+            return await runWorkflow(record.intent.workflow.path, {
+                ...input.engine,
+                coordRoot,
+                resumeRunId: latest.run_id,
+                workItemId: input.workId,
+            });
+        }
+        if (record.projection.state === "blocked" && !input.retry) {
+            throw new Error(`work item ${input.workId} is blocked; use an explicit retry`);
+        }
+        if (!(record.projection.state === "ready" || record.projection.state === "blocked")) {
+            throw new Error(`work item ${input.workId} cannot run from state ${record.projection.state}`);
+        }
+        if (record.projection.attempts_used >= record.intent.max_attempts) {
+            throw new Error(`work item ${input.workId} exhausted its ${record.intent.max_attempts} attempts`);
+        }
+        const attempt = record.projection.attempts_used + 1;
+        const runId = newWorkflowRunId();
+        appendWorkEvent(coordRoot, input.workId, {
+            event: "attempt.started",
+            actor: boundedActor(input.actor),
+            reason: input.retry ? "explicit retry started" : "workflow attempt started",
+            run_id: runId,
+            attempt,
+        });
+        return await runWorkflow(record.intent.workflow.path, {
+            ...input.engine,
+            coordRoot,
+            runId,
+            workItemId: input.workId,
+        });
+    }
+    finally {
+        try {
+            const current = readWorkItemIgnoringLease(coordRoot, input.workId);
+            appendReconcileIfChanged(coordRoot, current, boundedActor(input.actor, "work-runner"));
+        }
+        finally {
+            release();
+        }
+    }
+}

package/dist/core/work/state.d.ts

@@ -0,0 +1,109 @@
+export declare const WORK_INTENT_SCHEMA_VERSION: 1;
+export declare const WORK_EVENT_SCHEMA_VERSION: 1;
+export type WorkState = "waiting" | "ready" | "running" | "awaiting_approval" | "in_review" | "blocked" | "succeeded" | "cancelled";
+export type WorkNextAction = "wait_for_dependencies" | "run" | "wait_for_run" | "resolve_approval" | "resume" | "retry" | "review" | "none";
+export interface WorkIntent {
+    schema_version: typeof WORK_INTENT_SCHEMA_VERSION;
+    id: string;
+    title: string;
+    objective: string;
+    acceptance: string[];
+    dependencies: string[];
+    workflow: {
+        path: string;
+        sha256: string;
+    };
+    max_attempts: number;
+    source?: {
+        kind: "human" | "workflow" | "external";
+        ref?: string;
+    };
+    created_at: string;
+}
+export type WorkEventType = "work.created" | "work.reconciled" | "attempt.started" | "attempt.resumed" | "work.accepted" | "work.cancelled" | "work.reopened";
+export interface WorkEvent {
+    schema_version: typeof WORK_EVENT_SCHEMA_VERSION;
+    work_id: string;
+    seq: number;
+    ts: string;
+    event: WorkEventType;
+    actor: string;
+    reason?: string;
+    run_id?: string;
+    attempt?: number;
+    state?: WorkState;
+    next_action?: WorkNextAction;
+}
+export interface WorkAttempt {
+    number: number;
+    run_id: string;
+    started_at: string;
+    status: "running" | "parked" | "succeeded" | "failed" | "lost";
+    approval_id?: string;
+    proof_path?: string;
+}
+export interface WorkProjection {
+    id: string;
+    title: string;
+    state: WorkState;
+    reason: string;
+    next_action: WorkNextAction;
+    unresolved_dependencies: string[];
+    attempts: WorkAttempt[];
+    attempts_used: number;
+    attempts_remaining: number;
+    latest_run_id?: string;
+    approval_id?: string;
+    proof_path?: string;
+    updated_at: string;
+}
+export interface WorkRecord {
+    intent: WorkIntent;
+    events: WorkEvent[];
+    projection: WorkProjection;
+}
+export interface CreateWorkItemInput {
+    coordRoot: string;
+    title: string;
+    objective: string;
+    workflowPath: string;
+    acceptance?: string[];
+    dependencies?: string[];
+    maxAttempts?: number;
+    source?: WorkIntent["source"];
+    id?: string;
+    actor?: string;
+}
+export declare function createWorkItem(input: CreateWorkItemInput): WorkRecord;
+export declare function readWorkItem(coordRoot: string, workId: string): WorkRecord;
+export declare function listWorkItems(coordRoot: string): WorkRecord[];
+export declare function reconcileWorkItem(coordRoot: string, workId: string, actor?: string): WorkRecord;
+export declare function reconcileAllWorkItems(coordRoot: string, actor?: string): WorkRecord[];
+export declare function acceptWorkItem(coordRoot: string, workId: string, input?: {
+    actor?: string;
+    reason?: string;
+}): WorkRecord;
+export declare function cancelWorkItem(coordRoot: string, workId: string, input?: {
+    actor?: string;
+    reason?: string;
+}): WorkRecord;
+export declare function reopenWorkItem(coordRoot: string, workId: string, input?: {
+    actor?: string;
+    reason?: string;
+}): WorkRecord;
+export declare function assertWorkId(workId: string): void;
+export declare function newWorkId(): string;
+export declare function newWorkflowRunId(): string;
+/** @internal Runner seam; not a separate persistence contract. */
+export declare function appendReconcileIfChanged(coordRoot: string, record: WorkRecord, actor: string): void;
+/** @internal Runner seam; not a separate persistence contract. */
+export declare function appendWorkEvent(coordRoot: string, workId: string, input: Omit<WorkEvent, "schema_version" | "work_id" | "seq" | "ts">): WorkEvent;
+/** @internal Runner seam; not a separate persistence contract. */
+export declare function readWorkItemIgnoringLease(coordRoot: string, workId: string): WorkRecord;
+/** @internal Runner seam; not a separate persistence contract. */
+export declare function assertWorkflowUnchanged(intent: WorkIntent): void;
+/** @internal Runner seam; not a separate persistence contract. */
+export declare function acquireWorkLease(coordRoot: string, workId: string): () => void;
+/** @internal Runner seam; not a separate persistence contract. */
+export declare function boundedActor(value?: string, fallback?: string): string;
+//# sourceMappingURL=state.d.ts.map

package/dist/core/work/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/core/work/state.ts"],"names":[],"mappings":"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"}