@penpair/core 0.1.3 → 0.2.0

package/dist/client.d.ts

@@ -1,12 +1,21 @@
 import { type Endpoint } from "./endpoint.js";
-import { type PenpairErrorCode } from "./errors.js";
+import { PenpairError, type PenpairErrorCode } from "./errors.js";
+export interface ExecutionMetrics {
+    requestSnippetBytes: number;
+    responsePayloadBytes: number;
+}
 export interface ToolOutcome {
+    metrics?: ExecutionMetrics;
     text: string;
+    structuredContent?: unknown;
     isError: boolean;
 }
 /** The only Penpot surface penpair needs: one tool call at a time on an already connected editor. */
+export interface ToolCallOptions {
+    timeoutMs?: number;
+}
 export interface PenpotToolClient {
-    callTool(name: string, args: Record<string, unknown>): Promise<ToolOutcome>;
+    callTool(name: string, args: Record<string, unknown>, options?: ToolCallOptions): Promise<ToolOutcome>;
     /** The names of the tools the server offers. A hosted Penpot may offer fewer than a local one. */
     listTools?(): Promise<string[]>;
     close(): Promise<void>;
@@ -17,6 +26,10 @@ export declare function connect(endpoint: Endpoint): Promise<PenpotToolClient>;
 /** Maps Penpot MCP failure text to a distinct code so each failure gets its own remedy. */
 export declare function classifyFailure(text: string): PenpairErrorCode;
 export interface ExecuteOptions {
+    /** Per-request budget; adapters/guards must forward it. */
+    timeoutMs?: number;
+    /** Only known read-only executions may be retried. Unclassified source is treated as a possible write. */
+    effect?: "read" | "write" | "unknown";
     /** How many times to wait and retry a suspended tab. */
     retries?: number;
     sleep?: (milliseconds: number) => Promise<void>;
@@ -25,13 +38,21 @@ export interface ExecuteOptions {
     redact?: (text: string) => string;
 }
 export interface ExecuteResult {
+    metrics?: ExecutionMetrics;
+    runId: string;
+    outcome: "ran";
     /** What the snippet returned, parsed when it was JSON. */
     result: unknown;
     /** What the snippet printed. */
     log: string;
 }
+export declare function executionEnvelope(outcome: ToolOutcome): Pick<ExecuteResult, "result" | "log"> | undefined;
 /**
- * Runs a snippet inside the connected Penpot editor. A suspended tab is waited out and retried, because the snippet may
- * already have run; the caller reads the page before repeating a write.
+ * Retries only declared reads. A lost response to any possible write leaves an uncertain outcome requiring independent inspection.
  */
-export declare function executeCode(client: PenpotToolClient, code: string, { retries, sleep, onWait, redact }?: ExecuteOptions): Promise<ExecuteResult>;
+export declare function executeCode(client: PenpotToolClient, code: string, { timeoutMs, effect, retries: requestedRetries, sleep, onWait, redact }?: ExecuteOptions): Promise<ExecuteResult>;
+export declare class UncertainExecutionError extends PenpairError {
+    readonly runId: string;
+    readonly outcome = "uncertain";
+    constructor(runId: string, message: string);
+}

package/dist/client.js

@@ -1,29 +1,32 @@
+import { commandSignal, commandSleep } from "./command-result.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { randomUUID } from "node:crypto";
 import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { redactEndpoint } from "./endpoint.js";
 import { PenpairError } from "./errors.js";
 /** Penpot's proxy refuses request bodies of about 110 KB; snippets stay under this. */
 export const maxSnippetBytes = 90 * 1024;
 export async function connect(endpoint) {
+    commandSignal()?.throwIfAborted();
     const client = new Client({ name: "penpair", version: "0" });
     const transport = new StreamableHTTPClientTransport(new URL(endpoint.url));
     try {
-        await client.connect(transport);
+        await client.connect(transport, { signal: commandSignal(), timeout: 120_000 });
     }
     catch (error) {
         throw transportFailure(error, endpoint);
     }
     return {
-        async callTool(name, args) {
+        async callTool(name, args, options) {
             try {
-                const result = await client.callTool({ name, arguments: args }, undefined, { timeout: 120_000 });
+                const result = await client.callTool({ name, arguments: args }, undefined, { timeout: options?.timeoutMs ?? 120_000, signal: commandSignal() });
                 const content = Array.isArray(result.content) ? result.content : [];
                 const text = content
                     .flatMap((item) => typeof item === "object" && item !== null && "type" in item && item.type === "text" && "text" in item
                     ? [String(item.text)]
                     : [])
                     .join("\n");
-                return { text, isError: result.isError === true };
+                return { text, metrics: { requestSnippetBytes: typeof args.code === "string" ? Buffer.byteLength(args.code, "utf8") : 0, responsePayloadBytes: Buffer.byteLength(text, "utf8") + (result.structuredContent === undefined ? 0 : Buffer.byteLength(JSON.stringify(result.structuredContent), "utf8")) }, ...(result.structuredContent !== undefined ? { structuredContent: result.structuredContent } : {}), isError: result.isError === true };
             }
             catch (error) {
                 throw transportFailure(error, endpoint);
@@ -31,7 +34,7 @@ export async function connect(endpoint) {
         },
         async listTools() {
             try {
-                return (await client.listTools()).tools.map((tool) => tool.name);
+                return (await client.listTools(undefined, { signal: commandSignal(), timeout: 120_000 })).tools.map((tool) => tool.name);
             }
             catch (error) {
                 throw transportFailure(error, endpoint);
@@ -43,6 +46,8 @@ export async function connect(endpoint) {
     };
 }
 function transportFailure(error, endpoint) {
+    if (commandSignal()?.aborted)
+        return commandSignal().reason;
     const raw = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
     const message = redactEndpoint(raw, endpoint);
     if (error instanceof StreamableHTTPError && (error.code === 401 || error.code === 403))
@@ -62,16 +67,18 @@ export function classifyFailure(text) {
         return "mcp-unavailable";
     return "tool-failed";
 }
-const defaultSleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
-function unpack(text) {
-    let envelope;
-    try {
-        envelope = JSON.parse(text);
-    }
-    catch {
-        return undefined;
+const defaultSleep = commandSleep;
+export function executionEnvelope(outcome) {
+    let envelope = outcome.structuredContent;
+    if (envelope === undefined) {
+        try {
+            envelope = JSON.parse(outcome.text);
+        }
+        catch {
+            return undefined;
+        }
     }
-    if (typeof envelope !== "object" || envelope === null || !("result" in envelope))
+    if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope) || !("result" in envelope) || "log" in envelope && typeof envelope.log !== "string")
         return undefined;
     const log = "log" in envelope && typeof envelope.log === "string" ? envelope.log : "";
     const raw = envelope.result;
@@ -85,16 +92,23 @@ function unpack(text) {
     }
 }
 /**
- * Runs a snippet inside the connected Penpot editor. A suspended tab is waited out and retried, because the snippet may
- * already have run; the caller reads the page before repeating a write.
+ * Retries only declared reads. A lost response to any possible write leaves an uncertain outcome requiring independent inspection.
  */
-export async function executeCode(client, code, { retries = 6, sleep = defaultSleep, onWait, redact = (text) => text } = {}) {
+export async function executeCode(client, code, { timeoutMs = 120_000, effect = "unknown", retries: requestedRetries = 6, sleep = defaultSleep, onWait, redact = (text) => text } = {}) {
+    commandSignal()?.throwIfAborted();
     if (Buffer.byteLength(code, "utf8") > maxSnippetBytes)
         throw new PenpairError("snippet-too-large", `The snippet is ${Buffer.byteLength(code, "utf8")} bytes`);
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000)
+        throw new Error("Execution timeout must be from 1 to 120000 ms");
+    const retries = effect === "read" ? requestedRetries : 0;
+    const runId = randomUUID();
+    const uncertain = (message) => new UncertainExecutionError(runId, redact(message));
     for (let attempt = 0;; attempt++) {
         let outcome;
         try {
-            outcome = await client.callTool("execute_code", { code });
+            commandSignal()?.throwIfAborted();
+            outcome = await client.callTool("execute_code", { code }, { timeoutMs });
+            commandSignal()?.throwIfAborted();
         }
         catch (error) {
             if (error instanceof PenpairError && error.code === "plugin-suspended" && attempt < retries) {
@@ -102,18 +116,30 @@ export async function executeCode(client, code, { retries = 6, sleep = defaultSl
                 await sleep(5_000 * (attempt + 1));
                 continue;
             }
+            if (effect !== "read" && (!(error instanceof PenpairError) || !["file-mismatch", "snippet-too-large", "auth-rejected"].includes(error.code)))
+                throw uncertain(error instanceof Error ? error.message : String(error));
             throw error;
         }
-        const unpacked = unpack(outcome.text);
+        const unpacked = executionEnvelope(outcome);
         const failed = outcome.isError || (!unpacked && /^Tool execution failed:/i.test(outcome.text.trim()));
         if (!failed && unpacked)
-            return unpacked;
+            return { ...unpacked, runId, outcome: "ran", metrics: outcome.metrics ?? { requestSnippetBytes: Buffer.byteLength(code, "utf8"), responsePayloadBytes: Buffer.byteLength(outcome.text, "utf8") + (outcome.structuredContent === undefined ? 0 : Buffer.byteLength(JSON.stringify(outcome.structuredContent), "utf8")) } };
         const code_ = classifyFailure(outcome.text);
         if (code_ === "plugin-suspended" && attempt < retries) {
             onWait?.(`Penpot tab is suspended; bring it to the foreground (retry ${attempt + 1}/${retries})`);
             await sleep(5_000 * (attempt + 1));
             continue;
         }
+        if (effect !== "read" && code_ !== "auth-rejected")
+            throw uncertain(outcome.text.slice(0, 500));
         throw new PenpairError(code_, redact(outcome.text).slice(0, 500));
     }
 }
+export class UncertainExecutionError extends PenpairError {
+    runId;
+    outcome = "uncertain";
+    constructor(runId, message) {
+        super("write-uncertain", `Run ${runId} has an uncertain outcome: ${message}`);
+        this.runId = runId;
+    }
+}

package/dist/command-result.d.ts

@@ -0,0 +1,159 @@
+export interface CommandFailure {
+    code: string;
+    message: string;
+    remedy: string;
+    runId?: string;
+}
+export interface CommandResult {
+    schemaVersion: 1;
+    redacted?: boolean;
+    command: string;
+    outcome: "success" | "drift" | "failed" | "incomplete" | "uncertain" | "cancelled" | "deadline";
+    phase: string;
+    exitCode: number;
+    target: {
+        fileId?: string;
+        pageId?: string;
+    } | null;
+    runId: string | null;
+    data: unknown;
+    messages: string[];
+    warnings: string[];
+    errors: CommandFailure[];
+    completeness: {
+        complete: boolean;
+        reason?: string;
+    };
+    timings: {
+        startedAt: string;
+        durationMs: number;
+    };
+}
+export interface CommandOutput {
+    log(...values: unknown[]): void;
+    error(...values: unknown[]): void;
+    result(value: unknown): void;
+}
+export declare const commandOutput: CommandOutput;
+export declare function commandRedactor(redact: (value: string) => string): void;
+export declare function commandFailure(error: unknown): void;
+export declare function withCommandSignal<T>(signal: AbortSignal, work: () => Promise<T>): Promise<T>;
+/** Bounded explicit restoration work may finish after the main command is cancelled. */
+export declare function withCleanupDeadline<T>(work: () => Promise<T>, milliseconds?: number): Promise<T>;
+export declare function commandSignal(): AbortSignal | undefined;
+export declare function commandSleep(milliseconds: number): Promise<void>;
+export declare class CommandInterruptedError extends Error {
+    readonly code: "cancelled" | "deadline";
+    constructor(code: "cancelled" | "deadline");
+}
+/** Shared service boundary for CLI and future tool surfaces; no stdout or global console interception. */
+export declare function collectCommand(command: string, work: () => Promise<number>, options?: {
+    signal?: AbortSignal;
+}): Promise<CommandResult>;
+/** Outer transport contract. Command-specific data remains owned by the command service. */
+export declare const commandResultSchema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schemaVersion", "command", "outcome", "phase", "exitCode", "target", "runId", "data", "messages", "warnings", "errors", "completeness", "timings"];
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly const: 1;
+        };
+        readonly redacted: {
+            readonly type: "boolean";
+        };
+        readonly command: {
+            readonly type: "string";
+        };
+        readonly outcome: {
+            readonly enum: readonly ["success", "drift", "failed", "incomplete", "uncertain", "cancelled", "deadline"];
+        };
+        readonly phase: {
+            readonly type: "string";
+        };
+        readonly exitCode: {
+            readonly enum: readonly [0, 1, 2, 3, 4, 124, 130];
+        };
+        readonly target: {
+            readonly anyOf: readonly [{
+                readonly type: "null";
+            }, {
+                readonly type: "object";
+                readonly properties: {
+                    readonly fileId: {
+                        readonly type: "string";
+                    };
+                    readonly pageId: {
+                        readonly type: "string";
+                    };
+                };
+                readonly additionalProperties: false;
+            }];
+        };
+        readonly runId: {
+            readonly type: readonly ["string", "null"];
+        };
+        readonly data: {};
+        readonly messages: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly warnings: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly errors: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["code", "message", "remedy"];
+                readonly properties: {
+                    readonly code: {
+                        readonly type: "string";
+                    };
+                    readonly message: {
+                        readonly type: "string";
+                    };
+                    readonly remedy: {
+                        readonly type: "string";
+                    };
+                    readonly runId: {
+                        readonly type: "string";
+                    };
+                };
+                readonly additionalProperties: false;
+            };
+        };
+        readonly completeness: {
+            readonly type: "object";
+            readonly required: readonly ["complete"];
+            readonly properties: {
+                readonly complete: {
+                    readonly type: "boolean";
+                };
+                readonly reason: {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly timings: {
+            readonly type: "object";
+            readonly required: readonly ["startedAt", "durationMs"];
+            readonly properties: {
+                readonly startedAt: {
+                    readonly type: "string";
+                };
+                readonly durationMs: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+            };
+            readonly additionalProperties: false;
+        };
+    };
+};

package/dist/command-result.js

@@ -0,0 +1,179 @@
+import { setTimeout as wait } from "node:timers/promises";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { redactEndpoint } from "./endpoint.js";
+const scope = new AsyncLocalStorage();
+const line = (values) => values.map((value) => typeof value === "string" ? value : JSON.stringify(value)).join(" ");
+export const commandOutput = {
+    log(...values) {
+        const current = scope.getStore();
+        if (!current) {
+            console.log(...values.map(value => renderHuman(value)));
+            return;
+        }
+        const message = line(values);
+        try {
+            current.data.push(JSON.parse(message));
+        }
+        catch {
+            current.messages.push(message);
+        }
+    },
+    error(...values) {
+        const current = scope.getStore();
+        if (current) {
+            const message = current.redactors.reduce((text, redact) => redact(text), redactEndpoint(line(values)));
+            if (message !== line(values))
+                current.redacted = true;
+            current.warnings.push(message);
+            console.error(message);
+        }
+        else
+            console.error(...values.map(value => renderHuman(value)));
+    },
+    result(value) { const current = scope.getStore(); if (current)
+        current.authoritative = value; },
+};
+export function commandRedactor(redact) { (scope.getStore()?.redactors ?? signals.getStore()?.redactors)?.push(redact); }
+export function commandFailure(error) {
+    const current = scope.getStore();
+    if (!current)
+        return;
+    const value = error;
+    if (current.signal?.aborted && value?.code !== "write-uncertain" && value?.outcome !== "uncertain") {
+        const reason = current.signal.reason;
+        current.errors.push({ code: reason?.code === "deadline" ? "deadline" : "cancelled", message: reason?.code === "deadline" ? "Command deadline exceeded" : "Command cancelled", remedy: "Inspect any recorded run and current state before starting again." });
+        return;
+    }
+    current.errors.push({ code: typeof value?.code === "string" ? value.code : typeof value?.outcome === "string" ? value.outcome : "command-failed",
+        message: error instanceof Error ? error.message : String(error), remedy: typeof value?.remedy === "string" ? value.remedy : "Inspect the command result and current project state before trying again.",
+        ...(typeof value?.runId === "string" ? { runId: value.runId } : {}) });
+}
+const signals = new AsyncLocalStorage();
+function redactHuman(text) { return (signals.getStore()?.redactors ?? []).reduce((value, redact) => redact(value), redactEndpoint(text)); }
+function renderHuman(value) {
+    const clean = (entry) => typeof entry === "string" ? redactHuman(entry) : Array.isArray(entry) ? entry.map(clean) : entry && typeof entry === "object" ? Object.fromEntries(Object.entries(entry).map(([key, child]) => [redactHuman(key), clean(child)])) : entry;
+    if (typeof value !== "string")
+        return clean(value);
+    try {
+        return JSON.stringify(clean(JSON.parse(value)), null, 2);
+    }
+    catch {
+        return redactHuman(value);
+    }
+}
+export function withCommandSignal(signal, work) { return signals.run({ signal, redactors: [] }, work); }
+const cleanupSignals = new AsyncLocalStorage();
+/** Bounded explicit restoration work may finish after the main command is cancelled. */
+export async function withCleanupDeadline(work, milliseconds = 10000) {
+    if (!Number.isInteger(milliseconds) || milliseconds < 1 || milliseconds > 30000)
+        throw new Error("Cleanup deadline must be from 1 to 30000 ms");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("Restoration deadline exceeded")), milliseconds);
+    try {
+        return await cleanupSignals.run(controller.signal, work);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function commandSignal() { return cleanupSignals.getStore() ?? scope.getStore()?.signal ?? signals.getStore()?.signal; }
+export async function commandSleep(milliseconds) {
+    const signal = commandSignal();
+    try {
+        await wait(milliseconds, undefined, { signal });
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw signal.reason;
+        throw error;
+    }
+}
+export class CommandInterruptedError extends Error {
+    code;
+    constructor(code) {
+        super(code === "deadline" ? "Command deadline exceeded" : "Command cancelled");
+        this.code = code;
+    }
+}
+/** Shared service boundary for CLI and future tool surfaces; no stdout or global console interception. */
+export async function collectCommand(command, work, options = {}) {
+    const started = Date.now();
+    const capture = { data: [], messages: [], warnings: [], errors: [], redactors: [], signal: options.signal };
+    let exitCode;
+    try {
+        exitCode = await scope.run(capture, async () => { options.signal?.throwIfAborted(); const code = await work(); options.signal?.throwIfAborted(); return code; });
+    }
+    catch (error) {
+        await scope.run(capture, async () => commandFailure(error));
+        exitCode = 1;
+    }
+    if (![0, 1, 2, 3, 4, 124, 130].includes(exitCode)) {
+        capture.warnings.push("Unsupported extension exit code was normalized to failure");
+        exitCode = 1;
+    }
+    const data = capture.authoritative !== undefined ? capture.authoritative : capture.data.length === 1 ? capture.data[0] : capture.data.length ? capture.data : null;
+    const record = data && typeof data === "object" && !Array.isArray(data) ? data : {};
+    const errorCode = capture.errors[0]?.code;
+    const incomplete = record.complete === false || record.truncated === true || errorCode === "incomplete-output";
+    let outcome = exitCode === 0 ? "success" : exitCode === 2 ? "drift" : exitCode === 3 ? "incomplete" : exitCode === 4 ? "uncertain" : exitCode === 130 ? "cancelled" : exitCode === 124 ? "deadline" : "failed";
+    if (errorCode === "write-uncertain" || errorCode === "uncertain") {
+        outcome = "uncertain";
+        exitCode = 4;
+    }
+    else if (errorCode === "cancelled" || errorCode === "deadline") {
+        outcome = errorCode;
+        exitCode = errorCode === "cancelled" ? 130 : 124;
+    }
+    else if (incomplete) {
+        outcome = "incomplete";
+        exitCode = 3;
+    }
+    if (exitCode !== 0 && !capture.errors.length && !["drift", "incomplete"].includes(outcome))
+        capture.errors.push({ code: "command-failed", message: "Command checks failed; inspect data and diagnostics.", remedy: "Resolve the reported checks before proceeding." });
+    const identity = (record.capture ?? record.target ?? record);
+    const target = typeof identity.fileId === "string" ? { fileId: identity.fileId, ...(typeof identity.pageId === "string" ? { pageId: identity.pageId } : {}) } : null;
+    const journal = record.journal;
+    const sanitize = (value) => {
+        if (value === undefined || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint" || typeof value === "number" && !Number.isFinite(value))
+            return null;
+        if (typeof value === "string")
+            return capture.redactors.reduce((text, redact) => redact(text), redactEndpoint(value));
+        if (Array.isArray(value))
+            return value.map(sanitize);
+        if (value && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [String(sanitize(key)), sanitize(entry)]));
+        return value;
+    };
+    const raw = { schemaVersion: 1, command, outcome, phase: typeof record.phase === "string" ? record.phase : outcome === "uncertain" || outcome === "cancelled" || outcome === "deadline" ? "interrupted" : "finished", exitCode, target,
+        runId: capture.errors.find((error) => error.runId)?.runId ?? (typeof journal?.runId === "string" ? journal.runId : null), data, messages: capture.messages, warnings: capture.warnings, errors: capture.errors,
+        completeness: { complete: outcome === "success" || outcome === "drift", ...(incomplete ? { reason: "Output is truncated or required observations are missing" } : {}) }, timings: { startedAt: new Date(started).toISOString(), durationMs: Math.max(0, Date.now() - started) } };
+    const result = sanitize(raw);
+    if (record.redacted === true || capture.redacted || JSON.stringify(result) !== JSON.stringify(raw)) {
+        result.redacted = true;
+        result.warnings.push("Sensitive or non-JSON output was redacted; hashes describe original evidence.");
+        if (JSON.stringify(result.data) !== JSON.stringify(data)) {
+            result.completeness = { complete: false, reason: "Displayed data required redaction and is not lossless source evidence" };
+            if (result.outcome === "success" || result.outcome === "drift") {
+                result.outcome = "incomplete";
+                result.exitCode = 3;
+            }
+        }
+    }
+    return result;
+}
+/** Outer transport contract. Command-specific data remains owned by the command service. */
+export const commandResultSchema = {
+    type: "object", additionalProperties: false,
+    required: ["schemaVersion", "command", "outcome", "phase", "exitCode", "target", "runId", "data", "messages", "warnings", "errors", "completeness", "timings"],
+    properties: {
+        schemaVersion: { const: 1 }, redacted: { type: "boolean" }, command: { type: "string" },
+        outcome: { enum: ["success", "drift", "failed", "incomplete", "uncertain", "cancelled", "deadline"] },
+        phase: { type: "string" }, exitCode: { enum: [0, 1, 2, 3, 4, 124, 130] },
+        target: { anyOf: [{ type: "null" }, { type: "object", properties: { fileId: { type: "string" }, pageId: { type: "string" } }, additionalProperties: false }] },
+        runId: { type: ["string", "null"] }, data: {},
+        messages: { type: "array", items: { type: "string" } }, warnings: { type: "array", items: { type: "string" } },
+        errors: { type: "array", items: { type: "object", required: ["code", "message", "remedy"], properties: { code: { type: "string" }, message: { type: "string" }, remedy: { type: "string" }, runId: { type: "string" } }, additionalProperties: false } },
+        completeness: { type: "object", required: ["complete"], properties: { complete: { type: "boolean" }, reason: { type: "string" } }, additionalProperties: false },
+        timings: { type: "object", required: ["startedAt", "durationMs"], properties: { startedAt: { type: "string" }, durationMs: { type: "number", minimum: 0 } }, additionalProperties: false },
+    },
+};

package/dist/coordination.d.ts

@@ -0,0 +1,15 @@
+import type { PenpotToolClient } from "./client.js";
+import type { JournalTarget } from "./journal.js";
+export interface WriteLease {
+    check(): Promise<void>;
+    release(): Promise<void>;
+}
+export interface CoordinationOptions {
+    root: string;
+    operation: string;
+    forceLock?: boolean;
+    warn?(message: string): void;
+}
+export declare function writeCoordinator(client: PenpotToolClient, options: CoordinationOptions): (runId: string, target: JournalTarget) => Promise<WriteLease>;
+/** Revision precondition is checked inside the delivered mutation, after all guard calls. It is not a server CAS. */
+export declare function guardRevision(client: PenpotToolClient, target: JournalTarget): PenpotToolClient;