harnery 0.22.0 → 0.23.0

package/dist/core/workflow/workspaces/leases.js

@@ -0,0 +1,380 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+const MAX_LEASE_BYTES = 8 * 1024;
+const SAFE_COMPONENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+/**
+ * Acquires a crash-safe lease whose active name is always a hard link to one
+ * immutable owner file. Stale takeover is serialized by an atomic recovery
+ * directory; only its claimant may pin and replace the observed `current`.
+ */
+export function acquireNoClobberLease(input) {
+    validateInput(input);
+    const leaseDir = resolve(input.path);
+    ensureLeaseDirectory(leaseDir);
+    const now = input.now ?? Date.now;
+    const created = now();
+    const ownerId = randomUUID();
+    const ownerFile = `owner-${ownerId}.json`;
+    const owner = {
+        schema_version: 1,
+        owner_id: ownerId,
+        owner_file: ownerFile,
+        scope: input.scope,
+        authority_sha256: input.authoritySha256,
+        metadata: input.metadata ? { ...input.metadata } : undefined,
+        pid: input.pid ?? process.pid,
+        host: input.host ?? hostname(),
+        created_at: new Date(created).toISOString(),
+        expires_at: new Date(created + input.staleAfterMs).toISOString(),
+    };
+    const ownerPath = join(leaseDir, ownerFile);
+    const ownerBytes = `${JSON.stringify(owner)}\n`;
+    writeExclusive(ownerPath, ownerBytes);
+    fsyncDirectory(leaseDir);
+    const currentPath = join(leaseDir, "current");
+    const recoveryPath = join(leaseDir, "recovery");
+    let recoveryClaimed = false;
+    try {
+        if (existsSync(recoveryPath)) {
+            reclaimAbandonedRecovery(leaseDir, recoveryPath, input, now());
+        }
+        try {
+            linkSync(ownerPath, currentPath);
+            fsyncDirectory(leaseDir);
+            assertExactOwner(currentPath, ownerPath, ownerBytes, owner);
+            if (existsSync(recoveryPath)) {
+                unlinkExactCurrent(currentPath, ownerPath);
+                throw new Error(`lease ${input.scope} recovery is already in progress`);
+            }
+            return leaseHandle(leaseDir, ownerPath, ownerBytes, owner);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const observed = readOwner(currentPath);
+        if (leaseIsLive(observed.owner, now(), input.staleAfterMs)) {
+            throw new Error(`lease ${input.scope} is held by a live or unexpired owner`);
+        }
+        if (observed.owner.scope !== input.scope ||
+            (input.validateStaleOwner !== undefined && !input.validateStaleOwner(observed.owner))) {
+            throw new Error(`stale lease ${input.scope} has mismatched authority`);
+        }
+        createRecoveryClaim(leaseDir, recoveryPath, owner, observed);
+        recoveryClaimed = true;
+        input.onRecoveryStep?.("claim_created");
+        const pinPath = join(recoveryPath, "stale-pin");
+        linkSync(currentPath, pinPath);
+        assertSameInodeAndBytes(currentPath, pinPath, observed.bytes);
+        fsyncDirectory(recoveryPath);
+        input.onRecoveryStep?.("stale_pinned");
+        assertSameInodeAndBytes(currentPath, pinPath, observed.bytes);
+        unlinkSync(currentPath);
+        fsyncDirectory(leaseDir);
+        input.onRecoveryStep?.("current_removed");
+        linkSync(ownerPath, currentPath);
+        assertExactOwner(currentPath, ownerPath, ownerBytes, owner);
+        fsyncDirectory(leaseDir);
+        input.onRecoveryStep?.("new_current_linked");
+        removePinnedOwner(leaseDir, pinPath, observed.owner);
+        unlinkSync(pinPath);
+        unlinkSync(join(recoveryPath, "claim.json"));
+        rmdirSync(recoveryPath);
+        fsyncDirectory(leaseDir);
+        return {
+            ...leaseHandle(leaseDir, ownerPath, ownerBytes, owner),
+            recovered_owner: observed.owner,
+        };
+    }
+    catch (error) {
+        // Once the recovery directory exists, leave every boundary intact. A
+        // later owner can quarantine that exact abandoned claim and reconcile it.
+        if (!recoveryClaimed)
+            safeUnlink(ownerPath);
+        throw error;
+    }
+}
+function validateInput(input) {
+    if (!SAFE_COMPONENT.test(basename(resolve(input.path))) ||
+        !SAFE_COMPONENT.test(input.scope) ||
+        !/^[a-f0-9]{64}$/.test(input.authoritySha256) ||
+        !Number.isSafeInteger(input.staleAfterMs) ||
+        input.staleAfterMs < 1) {
+        throw new Error("no-clobber lease input is invalid");
+    }
+}
+function ensureLeaseDirectory(leaseDir) {
+    mkdirSync(dirname(leaseDir), { recursive: true, mode: 0o700 });
+    if (existsSync(leaseDir) && !lstatSync(leaseDir).isDirectory()) {
+        throw new Error(`lease path is not a directory: ${leaseDir}`);
+    }
+    if (!existsSync(leaseDir)) {
+        mkdirSync(leaseDir, { mode: 0o700 });
+        fsyncDirectory(dirname(leaseDir));
+    }
+}
+function createRecoveryClaim(leaseDir, recoveryPath, claimant, observed) {
+    const temporary = join(leaseDir, `recovery-claim-${claimant.owner_id}`);
+    mkdirSync(temporary, { mode: 0o700 });
+    const claim = {
+        schema_version: 1,
+        claimant,
+        observed_owner: observed.owner,
+        observed_sha256: digestBytes(observed.bytes),
+        created_at: claimant.created_at,
+    };
+    try {
+        writeExclusive(join(temporary, "claim.json"), `${JSON.stringify(claim)}\n`);
+        fsyncDirectory(temporary);
+        try {
+            renameSync(temporary, recoveryPath);
+            fsyncDirectory(leaseDir);
+        }
+        catch (error) {
+            if (error.code === "EEXIST" ||
+                error.code === "ENOTEMPTY") {
+                unlinkSync(join(temporary, "claim.json"));
+                rmdirSync(temporary);
+                throw new Error(`lease ${claimant.scope} recovery is already in progress`);
+            }
+            throw error;
+        }
+    }
+    catch (error) {
+        if (existsSync(join(temporary, "claim.json")))
+            unlinkSync(join(temporary, "claim.json"));
+        if (existsSync(temporary))
+            rmdirSync(temporary);
+        throw error;
+    }
+}
+function reclaimAbandonedRecovery(leaseDir, recoveryPath, input, now) {
+    const claim = readRecoveryClaim(recoveryPath);
+    if (leaseIsLive(claim.claimant, now, input.staleAfterMs)) {
+        throw new Error(`lease ${input.scope} recovery is already in progress`);
+    }
+    if (claim.claimant.scope !== input.scope ||
+        claim.observed_owner.scope !== input.scope ||
+        (input.validateStaleOwner !== undefined && !input.validateStaleOwner(claim.observed_owner))) {
+        throw new Error(`stale lease ${input.scope} recovery has mismatched authority`);
+    }
+    const recoveryPin = join(recoveryPath, "stale-pin");
+    if (existsSync(recoveryPin)) {
+        const pinned = readOwner(recoveryPin);
+        if (pinned.owner.owner_id !== claim.observed_owner.owner_id ||
+            digestBytes(pinned.bytes) !== claim.observed_sha256) {
+            throw new Error(`stale lease ${input.scope} recovery pin is corrupt`);
+        }
+    }
+    const quarantine = join(leaseDir, `quarantine-${randomUUID()}`);
+    try {
+        renameSync(recoveryPath, quarantine);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`lease ${input.scope} recovery raced with another contender`);
+        }
+        throw error;
+    }
+    fsyncDirectory(leaseDir);
+    const pinPath = join(quarantine, "stale-pin");
+    if (existsSync(pinPath)) {
+        const pinned = readOwner(pinPath);
+        if (pinned.owner.owner_id !== claim.observed_owner.owner_id ||
+            digestBytes(pinned.bytes) !== claim.observed_sha256) {
+            throw new Error(`stale lease ${input.scope} recovery pin is corrupt`);
+        }
+        removePinnedOwner(leaseDir, pinPath, pinned.owner);
+        unlinkSync(pinPath);
+    }
+    const claimantPath = join(leaseDir, claim.claimant.owner_file);
+    const currentPath = join(leaseDir, "current");
+    if (existsSync(claimantPath) &&
+        (!existsSync(currentPath) || !sameInode(claimantPath, currentPath))) {
+        unlinkSync(claimantPath);
+    }
+    unlinkSync(join(quarantine, "claim.json"));
+    rmdirSync(quarantine);
+    fsyncDirectory(leaseDir);
+}
+function readRecoveryClaim(recoveryPath) {
+    const path = join(recoveryPath, "claim.json");
+    const size = lstatSync(path).size;
+    if (size <= 0 || size > MAX_LEASE_BYTES * 2) {
+        throw new Error("lease recovery claim bytes are invalid");
+    }
+    let claim;
+    try {
+        claim = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`lease recovery claim is corrupt: ${error.message}`);
+    }
+    if (claim.schema_version !== 1 ||
+        !validOwner(claim.claimant) ||
+        !validOwner(claim.observed_owner) ||
+        !/^[a-f0-9]{64}$/.test(claim.observed_sha256) ||
+        typeof claim.created_at !== "string" ||
+        claim.created_at !== claim.claimant.created_at) {
+        throw new Error("lease recovery claim has an unsupported schema");
+    }
+    return claim;
+}
+function leaseHandle(leaseDir, ownerPath, ownerBytes, owner) {
+    let released = false;
+    return {
+        owner,
+        release() {
+            if (released)
+                return;
+            const currentPath = join(leaseDir, "current");
+            assertExactOwner(currentPath, ownerPath, ownerBytes, owner);
+            unlinkSync(currentPath);
+            unlinkSync(ownerPath);
+            fsyncDirectory(leaseDir);
+            released = true;
+        },
+    };
+}
+function writeExclusive(path, bytes) {
+    const fd = openSync(path, "wx", 0o600);
+    try {
+        writeFileSync(fd, bytes, "utf8");
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readOwner(path) {
+    let size;
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error("lease owner is not a plain file");
+        size = stat.size;
+    }
+    catch (error) {
+        throw new Error(`lease owner cannot be inspected: ${error.message}`);
+    }
+    if (size <= 0 || size > MAX_LEASE_BYTES)
+        throw new Error("lease owner bytes are invalid");
+    const bytes = readFileSync(path, "utf8");
+    let value;
+    try {
+        value = JSON.parse(bytes);
+    }
+    catch (error) {
+        throw new Error(`lease owner is corrupt: ${error.message}`);
+    }
+    if (!validOwner(value))
+        throw new Error("lease owner has an unsupported schema");
+    return { owner: value, bytes };
+}
+function validOwner(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const owner = value;
+    return (owner.schema_version === 1 &&
+        typeof owner.owner_id === "string" &&
+        typeof owner.owner_file === "string" &&
+        owner.owner_file === `owner-${owner.owner_id}.json` &&
+        SAFE_COMPONENT.test(owner.owner_file) &&
+        typeof owner.scope === "string" &&
+        SAFE_COMPONENT.test(owner.scope) &&
+        typeof owner.authority_sha256 === "string" &&
+        /^[a-f0-9]{64}$/.test(owner.authority_sha256) &&
+        (owner.metadata === undefined ||
+            (isStringRecord(owner.metadata) && Object.keys(owner.metadata).length <= 20)) &&
+        Number.isSafeInteger(owner.pid) &&
+        owner.pid > 0 &&
+        typeof owner.host === "string" &&
+        owner.host.length > 0 &&
+        typeof owner.created_at === "string" &&
+        typeof owner.expires_at === "string" &&
+        Number.isFinite(Date.parse(owner.created_at)) &&
+        Number.isFinite(Date.parse(owner.expires_at)));
+}
+function isStringRecord(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.entries(value).every(([key, item]) => SAFE_COMPONENT.test(key) && typeof item === "string" && item.length <= 1_000));
+}
+function leaseIsLive(owner, now, staleAfterMs) {
+    const created = Date.parse(owner.created_at);
+    const expires = Date.parse(owner.expires_at);
+    if (!Number.isFinite(created) ||
+        !Number.isFinite(expires) ||
+        expires !== created + staleAfterMs ||
+        now < created ||
+        now < expires) {
+        return true;
+    }
+    if (owner.host !== hostname())
+        return false;
+    try {
+        process.kill(owner.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function assertExactOwner(currentPath, ownerPath, expectedBytes, owner) {
+    const current = readOwner(currentPath);
+    if (current.bytes !== expectedBytes ||
+        current.owner.owner_id !== owner.owner_id ||
+        !sameInode(currentPath, ownerPath)) {
+        throw new Error(`lease ${owner.scope} ownership changed`);
+    }
+}
+function unlinkExactCurrent(currentPath, ownerPath) {
+    if (existsSync(currentPath) && sameInode(currentPath, ownerPath))
+        unlinkSync(currentPath);
+}
+function removePinnedOwner(leaseDir, pinPath, owner) {
+    const staleOwnerPath = join(leaseDir, owner.owner_file);
+    if (basename(staleOwnerPath) === owner.owner_file &&
+        existsSync(staleOwnerPath) &&
+        sameInode(staleOwnerPath, pinPath)) {
+        unlinkSync(staleOwnerPath);
+    }
+}
+function assertSameInodeAndBytes(left, right, expectedBytes) {
+    if (!sameInode(left, right))
+        throw new Error("lease recovery owner inode changed");
+    const leftBytes = readFileSync(left, "utf8");
+    const rightBytes = readFileSync(right, "utf8");
+    if (leftBytes !== expectedBytes || rightBytes !== expectedBytes) {
+        throw new Error("lease recovery owner bytes changed");
+    }
+}
+function sameInode(left, right) {
+    const a = statSync(left, { bigint: true });
+    const b = statSync(right, { bigint: true });
+    return a.dev === b.dev && a.ino === b.ino;
+}
+function digestBytes(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function fsyncDirectory(path) {
+    const fd = openSync(path, "r");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function safeUnlink(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}

package/dist/core/workflow/workspaces/lifecycle.d.ts

@@ -0,0 +1,43 @@
+import type { WorkEvent } from "../../work/state.js";
+import type { WorkflowRunManifest } from "../run-state.js";
+import type { WorkflowProof } from "../types.js";
+import type { WorkspaceProviderEvent } from "./state.js";
+import type { IntegrationApplyAttempt, IntegrationApplyReceipt, IntegrationAuthorization, IntegrationPlan, WorkspaceBinding, WorkspaceCancellationReceipt, WorkspaceCancellationResult, WorkspaceCleanupAttempt, WorkspaceCleanupIntent, WorkspaceCleanupReceipt, WorkspaceIntegrationState, WorkspaceLifecycleState, WorkspaceProofOutcome, WorkspaceResourceState } from "./types.js";
+export interface WorkspaceLifecycleProjectionInput {
+    allocation_unsupported?: boolean;
+    binding?: WorkspaceBinding;
+    provider_events?: readonly WorkspaceProviderEvent[];
+    manifest?: WorkflowRunManifest;
+    workflow_journal?: readonly {
+        event: string;
+        ok?: boolean;
+        status?: "blocked" | "lost" | WorkspaceCancellationResult["status"];
+        work_event_seq?: number;
+        work_event_sha256?: string;
+    }[];
+    proof?: WorkflowProof;
+    proof_sha256?: string;
+    integration_plan?: IntegrationPlan;
+    integration_authorization?: IntegrationAuthorization;
+    integration_attempts?: readonly IntegrationApplyAttempt[];
+    integration_receipt?: IntegrationApplyReceipt;
+    cleanup_intent?: WorkspaceCleanupIntent;
+    cleanup_attempts?: readonly WorkspaceCleanupAttempt[];
+    cleanup_receipt?: WorkspaceCleanupReceipt;
+    work_events?: readonly WorkEvent[];
+    cancellation_outcome?: WorkspaceCancellationResult;
+    cancellation_receipt?: WorkspaceCancellationReceipt;
+}
+export interface WorkspaceLifecycleProjection {
+    state: WorkspaceLifecycleState;
+    workflow_outcome: WorkspaceProofOutcome | null;
+    resource_state: WorkspaceResourceState | null;
+    integration_state: WorkspaceIntegrationState;
+    provider_event_chain_sha256: string | null;
+    cancellation: "none" | "host_requested" | "confirmed";
+}
+export declare function isWorkspaceLifecycleState(value: unknown): value is WorkspaceLifecycleState;
+export declare function assertWorkspaceLifecycleTransition(from: WorkspaceLifecycleState, to: WorkspaceLifecycleState): void;
+export declare function deriveWorkspaceLifecycle(input: WorkspaceLifecycleProjectionInput): WorkspaceLifecycleProjection;
+export declare function validateProviderEventChain(events: readonly WorkspaceProviderEvent[], binding?: WorkspaceBinding): void;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/core/workflow/workspaces/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../src/core/workflow/workspaces/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,EACzB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAgHpB,MAAM,WAAW,iCAAiC;IAChD,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,eAAe,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACpD,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,gBAAgB,CAAC,EAAE,SAAS;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,EAAE,CAAC,EAAE,OAAO,CAAC;QACb,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,2BAA2B,CAAC,QAAQ,CAAC,CAAC;QACpE,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,EAAE,CAAC;IACJ,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,eAAe,CAAC;IACnC,yBAAyB,CAAC,EAAE,wBAAwB,CAAC;IACrD,oBAAoB,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC1D,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;IAC9C,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,gBAAgB,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACtD,eAAe,CAAC,EAAE,uBAAuB,CAAC;IAC1C,WAAW,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACnC,oBAAoB,CAAC,EAAE,2BAA2B,CAAC;IACnD,oBAAoB,CAAC,EAAE,4BAA4B,CAAC;CACrD;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,uBAAuB,CAAC;IAC/B,gBAAgB,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC/C,cAAc,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC9C,iBAAiB,EAAE,yBAAyB,CAAC;IAC7C,2BAA2B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,YAAY,EAAE,MAAM,GAAG,gBAAgB,GAAG,WAAW,CAAC;CACvD;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAE1F;AAED,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,uBAAuB,EAC7B,EAAE,EAAE,uBAAuB,GAC1B,IAAI,CAON;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,iCAAiC,GACvC,4BAA4B,CA2G9B;AAicD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,sBAAsB,EAAE,EACzC,OAAO,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAiBN"}