@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.0

package/dist/durable/cli.js

@@ -0,0 +1,141 @@
+/* eslint-disable no-console */
+/**
+ * `monolith durable ...` — read-mostly operator commands over the durable store
+ * of the current MONOLITH instance (`<monolithRoot>/durable`).
+ *
+ *   monolith durable list [--status active|completed|failed|cancelled]
+ *   monolith durable show <taskId> [--reveal-tokens]
+ *   monolith durable assess <taskId>
+ *   monolith durable packet <taskId> [--reveal-tokens]
+ *   monolith durable verify [taskId]
+ *   monolith durable retention --retain-days N [--compact-after N] [--apply]
+ *
+ * Output is JSON so it can be piped. Nothing here creates, claims or edits a
+ * task: tasks are driven by application code through `DurableTasks`. The only
+ * mutating command is `retention --apply`; without `--apply` it only reports.
+ */
+import { join } from 'path';
+import { assertContainedFile, resolveMonolithRoot, reportWriteWarning } from '../root/index.js';
+import { DurableError } from './errors.js';
+import { FsEventStore } from './fs-store.js';
+import { DurableTasks } from './runtime.js';
+export const DURABLE_DIR_NAME = 'durable';
+const STATUSES = ['active', 'completed', 'failed', 'cancelled'];
+/**
+ * Await tokens are capabilities: whoever holds one can deliver a result to the task. The CLI output ends up in
+ * terminals, logs and tickets, so the secret part (the nonce) is replaced there; `--reveal-tokens` prints it.
+ * The programmatic API (`getState`, `resumePacket`) is unchanged: a worker needs the real token to send it out.
+ */
+function redactTokens(v) {
+    if (Array.isArray(v))
+        return v.map(redactTokens);
+    if (v !== null && typeof v === 'object') {
+        const out = {};
+        for (const [k, x] of Object.entries(v)) {
+            out[k] = k === 'token' && typeof x === 'string' ? x.replace(/\.[0-9a-f]{32}$/, '.<redacted>') : redactTokens(x);
+        }
+        return out;
+    }
+    return v;
+}
+function flag(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+function openStore(cwd) {
+    const root = resolveMonolithRoot(cwd);
+    assertContainedFile(root, `${DURABLE_DIR_NAME}/x`);
+    const dir = join(root.rootAbs, DURABLE_DIR_NAME);
+    return new FsEventStore({ target: { scope: 'project', projectRoot: root.projectRoot, dir }, onWarning: (w) => reportWriteWarning(w) });
+}
+/**
+ * Opens the durable store of the instance. A store without `durable-protocol.json` is open for diagnostics only: reads
+ * work, every write is refused (`STORE_PROTOCOL`). Opening never creates the marker.
+ */
+export function openDurable(cwd) {
+    return new DurableTasks({ store: openStore(cwd) });
+}
+/**
+ * The explicit operator action that makes an EMPTY store writable (Design A section 46.5, ADR-018 D3). Not reachable from
+ * `runDurable` on purpose: it must be called by a person or script that knows no runtime of an older version is running.
+ * Refuses a store that already holds tasks.
+ */
+export function initializeDurable(cwd) {
+    return openStore(cwd).initializeProtocolSync();
+}
+/** Returns the process exit code: 0 ok, 1 usage/error, 2 verification found a problem. */
+export async function runDurable(args, io) {
+    const [sub, ...rest] = args;
+    const reveal = rest.includes('--reveal-tokens');
+    const json = (v) => io.out(JSON.stringify(reveal ? v : redactTokens(v), null, 2));
+    try {
+        const rt = openDurable(io.cwd);
+        switch (sub) {
+            case 'list': {
+                const status = flag(rest, '--status');
+                if (status !== undefined && !STATUSES.includes(status)) {
+                    io.err(`--status must be one of ${STATUSES.join(', ')}.`);
+                    return 1;
+                }
+                json(await rt.listTasks(status ? { status: status } : {}));
+                return 0;
+            }
+            case 'show': {
+                if (!rest[0])
+                    return usage(io, 'show <taskId>');
+                json(await rt.getState(rest[0]));
+                return 0;
+            }
+            case 'assess': {
+                if (!rest[0])
+                    return usage(io, 'assess <taskId>');
+                json(await rt.assess(rest[0]));
+                return 0;
+            }
+            case 'packet': {
+                if (!rest[0])
+                    return usage(io, 'packet <taskId>');
+                json(await rt.resumePacket(rest[0]));
+                return 0;
+            }
+            case 'verify': {
+                const reports = await rt.verify(rest[0]);
+                json(reports);
+                return reports.every((r) => r.ok) ? 0 : 2;
+            }
+            case 'retention': {
+                const days = Number(flag(rest, '--retain-days'));
+                if (!Number.isFinite(days) || days < 0)
+                    return usage(io, 'retention --retain-days N [--compact-after N] [--apply]');
+                const compact = flag(rest, '--compact-after');
+                const policy = {
+                    terminalRetentionMs: days * 86_400_000,
+                    ...(compact !== undefined ? { compactAfterEvents: Number(compact) } : {}),
+                };
+                if (rest.includes('--apply'))
+                    json(await rt.applyRetention(policy));
+                else
+                    json({ dryRun: true, decisions: await rt.planRetention(policy) });
+                return 0;
+            }
+            default:
+                return usage(io, 'list | show <id> | assess <id> | packet <id> | verify [id] | retention --retain-days N [--apply]');
+        }
+    }
+    catch (err) {
+        if (err instanceof DurableError)
+            io.err(`${err.code}: ${err.message}`);
+        else
+            io.err(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}
+function usage(io, text) {
+    io.err(`Usage: monolith durable ${text}`);
+    return 1;
+}
+export async function runDurableCommand(args) {
+    const code = await runDurable(args, { cwd: process.cwd(), out: (s) => console.log(s), err: (s) => console.error(s) });
+    if (code !== 0)
+        process.exit(code);
+}

package/dist/durable/errors.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Durable State — typed error taxonomy.
+ *
+ * Every error carries a stable `code`. Callers branch on `code`, never on
+ * message text. No error message embeds event payloads or file contents
+ * (payloads are application data and may be sensitive).
+ */
+export type DurableErrorCode = 'VALIDATION' | 'TASK_NOT_FOUND' | 'TASK_PRUNED' | 'TASK_EXISTS' | 'TASK_CLOSED' | 'TASK_ORPHANED' | 'REQUIRED_TASK_PENDING' | 'LEASE_HELD' | 'STALE_FENCE' | 'CONTENTION' | 'LOG_CORRUPT' | 'LOG_UNSUPPORTED' | 'LOG_TOO_LARGE' | 'STORE_SECURITY' | 'STORE_IO' | 'EFFECT_IN_DOUBT' | 'EFFECT_FAILED' | 'EFFECT_CONFLICT' | 'EFFECT_NOT_EXECUTED' | 'RETENTION_REFUSED' | 'PRUNE_DECISION_CORRUPT' | 'PRUNE_ATTEMPT_LIMIT' | 'STORE_PROTOCOL';
+export declare class DurableError extends Error {
+    readonly code: DurableErrorCode;
+    constructor(code: DurableErrorCode, message: string);
+}
+export declare class ValidationError extends DurableError {
+    constructor(message: string);
+}
+export declare class TaskNotFoundError extends DurableError {
+    readonly taskId: string;
+    constructor(taskId: string);
+}
+/** The task existed and was pruned by retention; only its tombstone remains. */
+export declare class TaskPrunedError extends DurableError {
+    readonly taskId: string;
+    constructor(taskId: string);
+}
+export declare class TaskExistsError extends DurableError {
+    readonly taskId: string;
+    constructor(taskId: string);
+}
+/** The task reached a terminal state; its log is sealed. */
+export declare class TaskClosedError extends DurableError {
+    readonly taskId: string;
+    readonly status: string;
+    constructor(taskId: string, status: string);
+}
+export declare class LeaseHeldError extends DurableError {
+    readonly taskId: string;
+    readonly owner: string;
+    readonly leaseUntil: string;
+    constructor(taskId: string, owner: string, leaseUntil: string);
+}
+/**
+ * A worker acted with an epoch/owner that is no longer current: someone else
+ * claimed the task (fencing). The worker must stop; nothing was written.
+ */
+export declare class StaleFenceError extends DurableError {
+    readonly taskId: string;
+    readonly owner: string;
+    readonly epoch: number;
+    readonly currentEpoch: number;
+    constructor(taskId: string, owner: string, epoch: number, currentEpoch: number);
+}
+export declare class ContentionError extends DurableError {
+    readonly taskId: string;
+    readonly attempts: number;
+    constructor(taskId: string, attempts: number);
+}
+/** The log failed an integrity check (hash chain, sequence gap, schema). Fail closed; never auto-repaired. */
+export declare class LogCorruptError extends DurableError {
+    readonly taskId: string;
+    readonly seq: number | null;
+    readonly reason: string;
+    constructor(taskId: string, seq: number | null, reason: string);
+}
+/**
+ * `withdrawTombstone` found the pruned task's data no longer complete: removal has started, so the prune is committed
+ * and cannot be rolled back. (It is a `LogCorruptError` for callers that only know the old contract.)
+ */
+export declare class TombstoneCommittedError extends LogCorruptError {
+    constructor(taskId: string, reason: string);
+}
+/** The log contains an event format/type this version does not know. Never skipped silently. */
+export declare class LogUnsupportedError extends DurableError {
+    readonly taskId: string;
+    readonly seq: number;
+    readonly what: string;
+    constructor(taskId: string, seq: number, what: string);
+}
+export declare class LogTooLargeError extends DurableError {
+    readonly taskId: string;
+    readonly limit: number;
+    constructor(taskId: string, limit: number);
+}
+/** The filesystem layout is not what a managed store must look like (symlink, foreign hard link, special file). */
+export declare class StoreSecurityError extends DurableError {
+    readonly detailCode: string;
+    constructor(message: string, detailCode: string);
+}
+/**
+ * The storage layer failed (disk full, I/O error, permission). Nothing was published by the failed call.
+ * This is a PHYSICAL failure and is never confused with `LogTooLargeError`, which is the logical event budget.
+ * `errnoCode` is the operating-system code found in the cause chain (`ENOSPC`, `EDQUOT`, `EIO`, ...), if any.
+ */
+export declare class StoreIoError extends DurableError {
+    readonly cause?: unknown | undefined;
+    readonly errnoCode: string | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** An effect was announced but its outcome was never recorded (crash between intent and result). */
+export declare class EffectInDoubtError extends DurableError {
+    readonly taskId: string;
+    readonly effectKey: string;
+    constructor(taskId: string, effectKey: string);
+}
+export declare class EffectFailedError extends DurableError {
+    readonly taskId: string;
+    readonly effectKey: string;
+    readonly detail: string;
+    constructor(taskId: string, effectKey: string, detail: string);
+}
+/**
+ * Thrown by the function given to `runEffect` to assert that the external operation did NOT take effect
+ * (for example a connection refused before any request was sent). It is the only kind of error that leaves
+ * an effect safely retryable by default: any other exception, a timeout above all, proves nothing about
+ * what the remote side did, and the effect is then recorded as having an unknown outcome.
+ */
+export declare class EffectNotExecutedError extends DurableError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Another caller announced, finished or re-announced the same effect between this caller's decision and its
+ * announcement (compare-and-set on the effect's identity in the log lost). The function was NOT run by this call.
+ * Re-read the task and decide again; the other caller's attempt is the one that counts.
+ */
+export declare class EffectConflictError extends DurableError {
+    readonly taskId: string;
+    readonly effectKey: string;
+    constructor(taskId: string, effectKey: string);
+}
+/**
+ * The task is active in the log, but a task it requires (`parentTaskId` / `dependsOn`) was pruned or does not exist,
+ * so it must not run. Raised by `claim`; the log is NOT what decides this, the required task's state right now is.
+ */
+export declare class TaskOrphanedError extends DurableError {
+    readonly taskId: string;
+    readonly requiredTaskId: string;
+    constructor(taskId: string, requiredTaskId: string);
+}
+/**
+ * A task this one requires is in an unfinished prune (tombstone published, removal not finished or not provably
+ * rolled back), or could not be examined right now. Nothing is run and NOTHING IS CANCELLED: the state is transient,
+ * and the call can simply be repeated. Contrast `TaskOrphanedError`, which is final.
+ */
+export declare class RequiredTaskPendingError extends DurableError {
+    readonly taskId: string;
+    readonly requiredTaskId: string;
+    readonly retryable = true;
+    constructor(taskId: string, requiredTaskId: string);
+}
+export declare class RetentionRefusedError extends DurableError {
+    readonly taskId: string;
+    readonly why: string;
+    constructor(taskId: string, why: string);
+}
+/** Why the prune decision register of a task cannot be trusted (Design A, section 20.4). */
+export type PruneCorruptReason = 'register' | 'gap' | 'unknown-artifact' | 'commit-audit' | 'multiple-commit' | 'history' | 'task-dir-missing' | 'tombstone-without-commit' | 'legacy-tombstone-unmigrated';
+/**
+ * The persisted prune decision register of a task is corrupt, or the task directory is missing, or it is an
+ * unmigrated legacy tombstone. Fail closed: nothing is deleted and nobody is cancelled; an operator decides.
+ * Never mapped to `TaskOrphanedError`, `RetentionRefusedError` or a quarantine, and never retryable.
+ * `published` is true when a write the caller made is already visible (the outcome of that write is unknown).
+ */
+export declare class PruneDecisionCorruptError extends DurableError {
+    readonly taskId: string;
+    readonly reason: PruneCorruptReason;
+    readonly file: string | null;
+    readonly attempt: number | null;
+    readonly published: boolean;
+    readonly retryable = false;
+    constructor(taskId: string, reason: PruneCorruptReason, file?: string | null, attempt?: number | null, published?: boolean);
+}
+/** The attempt number would exceed `MAX_PRUNE_ATTEMPTS`. A liveness limit: numbers are never reused or reset. */
+export declare class PruneAttemptLimitError extends DurableError {
+    readonly taskId: string;
+    readonly attempts: number;
+    constructor(taskId: string, attempts: number);
+}
+export type StoreProtocolCode = 'PROTOCOL_NOT_INITIALIZED' | 'PROTOCOL_UNSUPPORTED' | 'PROTOCOL_STORE_NOT_EMPTY';
+/**
+ * The store does not carry a usable `durable-protocol.json`: it is uninitialized (read-only diagnostics only), has a
+ * version this build does not understand, or cannot be initialized because it already holds tasks. The marker is
+ * created only by an explicit operator action, never by opening the store.
+ */
+export declare class StoreProtocolError extends DurableError {
+    readonly detailCode: StoreProtocolCode;
+    constructor(message: string, detailCode: StoreProtocolCode);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/durable/errors.d.ts.map

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

package/dist/durable/errors.js

@@ -0,0 +1,317 @@
+/**
+ * Durable State — typed error taxonomy.
+ *
+ * Every error carries a stable `code`. Callers branch on `code`, never on
+ * message text. No error message embeds event payloads or file contents
+ * (payloads are application data and may be sensitive).
+ */
+export class DurableError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'DurableError';
+        this.code = code;
+    }
+}
+export class ValidationError extends DurableError {
+    constructor(message) {
+        super('VALIDATION', message);
+        this.name = 'DurableValidationError';
+    }
+}
+export class TaskNotFoundError extends DurableError {
+    taskId;
+    constructor(taskId) {
+        super('TASK_NOT_FOUND', `task "${taskId}" does not exist.`);
+        this.taskId = taskId;
+        this.name = 'TaskNotFoundError';
+    }
+}
+/** The task existed and was pruned by retention; only its tombstone remains. */
+export class TaskPrunedError extends DurableError {
+    taskId;
+    constructor(taskId) {
+        super('TASK_PRUNED', `task "${taskId}" was pruned by retention; only its tombstone remains.`);
+        this.taskId = taskId;
+        this.name = 'TaskPrunedError';
+    }
+}
+export class TaskExistsError extends DurableError {
+    taskId;
+    constructor(taskId) {
+        super('TASK_EXISTS', `task "${taskId}" already exists with different content.`);
+        this.taskId = taskId;
+        this.name = 'TaskExistsError';
+    }
+}
+/** The task reached a terminal state; its log is sealed. */
+export class TaskClosedError extends DurableError {
+    taskId;
+    status;
+    constructor(taskId, status) {
+        super('TASK_CLOSED', `task "${taskId}" is ${status}; its log is sealed.`);
+        this.taskId = taskId;
+        this.status = status;
+        this.name = 'TaskClosedError';
+    }
+}
+export class LeaseHeldError extends DurableError {
+    taskId;
+    owner;
+    leaseUntil;
+    constructor(taskId, owner, leaseUntil) {
+        super('LEASE_HELD', `task "${taskId}" is leased by "${owner}" until ${leaseUntil}.`);
+        this.taskId = taskId;
+        this.owner = owner;
+        this.leaseUntil = leaseUntil;
+        this.name = 'LeaseHeldError';
+    }
+}
+/**
+ * A worker acted with an epoch/owner that is no longer current: someone else
+ * claimed the task (fencing). The worker must stop; nothing was written.
+ */
+export class StaleFenceError extends DurableError {
+    taskId;
+    owner;
+    epoch;
+    currentEpoch;
+    constructor(taskId, owner, epoch, currentEpoch) {
+        super('STALE_FENCE', `"${owner}" (epoch ${epoch}) no longer holds task "${taskId}" (current epoch ${currentEpoch}).`);
+        this.taskId = taskId;
+        this.owner = owner;
+        this.epoch = epoch;
+        this.currentEpoch = currentEpoch;
+        this.name = 'StaleFenceError';
+    }
+}
+export class ContentionError extends DurableError {
+    taskId;
+    attempts;
+    constructor(taskId, attempts) {
+        super('CONTENTION', `gave up appending to task "${taskId}" after ${attempts} lost races.`);
+        this.taskId = taskId;
+        this.attempts = attempts;
+        this.name = 'ContentionError';
+    }
+}
+/** The log failed an integrity check (hash chain, sequence gap, schema). Fail closed; never auto-repaired. */
+export class LogCorruptError extends DurableError {
+    taskId;
+    seq;
+    reason;
+    constructor(taskId, seq, reason) {
+        super('LOG_CORRUPT', `log of task "${taskId}" is corrupt${seq === null ? '' : ` at seq ${seq}`}: ${reason}`);
+        this.taskId = taskId;
+        this.seq = seq;
+        this.reason = reason;
+        this.name = 'LogCorruptError';
+    }
+}
+/**
+ * `withdrawTombstone` found the pruned task's data no longer complete: removal has started, so the prune is committed
+ * and cannot be rolled back. (It is a `LogCorruptError` for callers that only know the old contract.)
+ */
+export class TombstoneCommittedError extends LogCorruptError {
+    constructor(taskId, reason) {
+        super(taskId, null, reason);
+        this.name = 'TombstoneCommittedError';
+    }
+}
+/** The log contains an event format/type this version does not know. Never skipped silently. */
+export class LogUnsupportedError extends DurableError {
+    taskId;
+    seq;
+    what;
+    constructor(taskId, seq, what) {
+        super('LOG_UNSUPPORTED', `log of task "${taskId}" has an unsupported ${what} at seq ${seq}; refusing to interpret it.`);
+        this.taskId = taskId;
+        this.seq = seq;
+        this.what = what;
+        this.name = 'LogUnsupportedError';
+    }
+}
+export class LogTooLargeError extends DurableError {
+    taskId;
+    limit;
+    constructor(taskId, limit) {
+        super('LOG_TOO_LARGE', `task "${taskId}" reached the event limit (${limit}); continue the work in a new task (parentTaskId). ` +
+            'Completing, failing or cancelling the task is still possible.');
+        this.taskId = taskId;
+        this.limit = limit;
+        this.name = 'LogTooLargeError';
+    }
+}
+/** The filesystem layout is not what a managed store must look like (symlink, foreign hard link, special file). */
+export class StoreSecurityError extends DurableError {
+    detailCode;
+    constructor(message, detailCode) {
+        super('STORE_SECURITY', message);
+        this.detailCode = detailCode;
+        this.name = 'StoreSecurityError';
+    }
+}
+/**
+ * The storage layer failed (disk full, I/O error, permission). Nothing was published by the failed call.
+ * This is a PHYSICAL failure and is never confused with `LogTooLargeError`, which is the logical event budget.
+ * `errnoCode` is the operating-system code found in the cause chain (`ENOSPC`, `EDQUOT`, `EIO`, ...), if any.
+ */
+export class StoreIoError extends DurableError {
+    cause;
+    errnoCode;
+    constructor(message, cause) {
+        super('STORE_IO', message);
+        this.cause = cause;
+        this.name = 'StoreIoError';
+        this.errnoCode = errnoOf(cause);
+    }
+}
+function errnoOf(cause) {
+    let c = cause;
+    for (let i = 0; i < 4 && c !== null && typeof c === 'object'; i++) {
+        const code = c.code;
+        if (typeof code === 'string' && /^E[A-Z0-9]{2,}$/.test(code))
+            return code;
+        c = c.cause;
+    }
+    return undefined;
+}
+/** An effect was announced but its outcome was never recorded (crash between intent and result). */
+export class EffectInDoubtError extends DurableError {
+    taskId;
+    effectKey;
+    constructor(taskId, effectKey) {
+        super('EFFECT_IN_DOUBT', `effect "${effectKey}" of task "${taskId}" has an unrecorded outcome; reconcile it against the external system.`);
+        this.taskId = taskId;
+        this.effectKey = effectKey;
+        this.name = 'EffectInDoubtError';
+    }
+}
+export class EffectFailedError extends DurableError {
+    taskId;
+    effectKey;
+    detail;
+    constructor(taskId, effectKey, detail) {
+        super('EFFECT_FAILED', `effect "${effectKey}" of task "${taskId}" failed permanently: ${detail}`);
+        this.taskId = taskId;
+        this.effectKey = effectKey;
+        this.detail = detail;
+        this.name = 'EffectFailedError';
+    }
+}
+/**
+ * Thrown by the function given to `runEffect` to assert that the external operation did NOT take effect
+ * (for example a connection refused before any request was sent). It is the only kind of error that leaves
+ * an effect safely retryable by default: any other exception, a timeout above all, proves nothing about
+ * what the remote side did, and the effect is then recorded as having an unknown outcome.
+ */
+export class EffectNotExecutedError extends DurableError {
+    cause;
+    constructor(message, cause) {
+        super('EFFECT_NOT_EXECUTED', message);
+        this.cause = cause;
+        this.name = 'EffectNotExecutedError';
+    }
+}
+/**
+ * Another caller announced, finished or re-announced the same effect between this caller's decision and its
+ * announcement (compare-and-set on the effect's identity in the log lost). The function was NOT run by this call.
+ * Re-read the task and decide again; the other caller's attempt is the one that counts.
+ */
+export class EffectConflictError extends DurableError {
+    taskId;
+    effectKey;
+    constructor(taskId, effectKey) {
+        super('EFFECT_CONFLICT', `effect "${effectKey}" of task "${taskId}" was changed by another caller while this call was deciding; it was not run by this call.`);
+        this.taskId = taskId;
+        this.effectKey = effectKey;
+        this.name = 'EffectConflictError';
+    }
+}
+/**
+ * The task is active in the log, but a task it requires (`parentTaskId` / `dependsOn`) was pruned or does not exist,
+ * so it must not run. Raised by `claim`; the log is NOT what decides this, the required task's state right now is.
+ */
+export class TaskOrphanedError extends DurableError {
+    taskId;
+    requiredTaskId;
+    constructor(taskId, requiredTaskId) {
+        super('TASK_ORPHANED', `task "${taskId}" requires task "${requiredTaskId}", which was pruned or does not exist; it will not be run.`);
+        this.taskId = taskId;
+        this.requiredTaskId = requiredTaskId;
+        this.name = 'TaskOrphanedError';
+    }
+}
+/**
+ * A task this one requires is in an unfinished prune (tombstone published, removal not finished or not provably
+ * rolled back), or could not be examined right now. Nothing is run and NOTHING IS CANCELLED: the state is transient,
+ * and the call can simply be repeated. Contrast `TaskOrphanedError`, which is final.
+ */
+export class RequiredTaskPendingError extends DurableError {
+    taskId;
+    requiredTaskId;
+    retryable = true;
+    constructor(taskId, requiredTaskId) {
+        super('REQUIRED_TASK_PENDING', `task "${taskId}" requires task "${requiredTaskId}", whose prune is not settled; it is not run now, and not cancelled. Retry.`);
+        this.taskId = taskId;
+        this.requiredTaskId = requiredTaskId;
+        this.name = 'RequiredTaskPendingError';
+    }
+}
+export class RetentionRefusedError extends DurableError {
+    taskId;
+    why;
+    constructor(taskId, why) {
+        super('RETENTION_REFUSED', `refusing to prune task "${taskId}": ${why}`);
+        this.taskId = taskId;
+        this.why = why;
+        this.name = 'RetentionRefusedError';
+    }
+}
+/**
+ * The persisted prune decision register of a task is corrupt, or the task directory is missing, or it is an
+ * unmigrated legacy tombstone. Fail closed: nothing is deleted and nobody is cancelled; an operator decides.
+ * Never mapped to `TaskOrphanedError`, `RetentionRefusedError` or a quarantine, and never retryable.
+ * `published` is true when a write the caller made is already visible (the outcome of that write is unknown).
+ */
+export class PruneDecisionCorruptError extends DurableError {
+    taskId;
+    reason;
+    file;
+    attempt;
+    published;
+    retryable = false;
+    constructor(taskId, reason, file = null, attempt = null, published = false) {
+        super('PRUNE_DECISION_CORRUPT', `the prune decision register of task "${taskId}" cannot be trusted (${reason}${file ? `: ${file}` : ''}); nothing was deleted or cancelled.`);
+        this.taskId = taskId;
+        this.reason = reason;
+        this.file = file;
+        this.attempt = attempt;
+        this.published = published;
+        this.name = 'PruneDecisionCorruptError';
+    }
+}
+/** The attempt number would exceed `MAX_PRUNE_ATTEMPTS`. A liveness limit: numbers are never reused or reset. */
+export class PruneAttemptLimitError extends DurableError {
+    taskId;
+    attempts;
+    constructor(taskId, attempts) {
+        super('PRUNE_ATTEMPT_LIMIT', `task "${taskId}" has used all ${attempts} prune attempts; raise the limit or find out why they keep being aborted.`);
+        this.taskId = taskId;
+        this.attempts = attempts;
+        this.name = 'PruneAttemptLimitError';
+    }
+}
+/**
+ * The store does not carry a usable `durable-protocol.json`: it is uninitialized (read-only diagnostics only), has a
+ * version this build does not understand, or cannot be initialized because it already holds tasks. The marker is
+ * created only by an explicit operator action, never by opening the store.
+ */
+export class StoreProtocolError extends DurableError {
+    detailCode;
+    constructor(message, detailCode) {
+        super('STORE_PROTOCOL', message);
+        this.detailCode = detailCode;
+        this.name = 'StoreProtocolError';
+    }
+}