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

package/dist/durable/projection.js

@@ -0,0 +1,328 @@
+/**
+ * Projection — the pure fold from events to `TaskState`.
+ *
+ * Deterministic and total over valid logs: the same events always give the
+ * same state, with no clock, randomness or I/O. It is also *strict*: an event
+ * that violates the task's own rules (a second claim with the wrong epoch, a
+ * delivery to an unknown await, an event after a terminal one) is a corrupt
+ * log, not something to be skipped. Writers run every new event through
+ * `applyEvent` before publishing it, so a log that was written by this code
+ * always folds.
+ */
+import { LogCorruptError } from './errors.js';
+import { GENESIS_HASH } from './types.js';
+/** Idempotency keys are scoped to the await they were delivered to ('awaitId' never contains ':'). */
+export function deliveryKey(awaitId, idempotencyKey) {
+    return `${awaitId}:${idempotencyKey}`;
+}
+/**
+ * A string-keyed dictionary that does not inherit from `Object.prototype`.
+ *
+ * Keys of these dictionaries are application data (assumption keys, effect keys, await ids, labels).
+ * On a plain object `d['__proto__'] = x` replaces the prototype instead of storing an entry, and
+ * `d['constructor']` / `d['toString']` read an inherited function for a key that was never written.
+ * A null-prototype object has neither problem; it serializes exactly like a plain one (JSON, canonical
+ * form, `Object.keys/values/entries`), so stored events and the public `Record<string, T>` types are unchanged.
+ */
+export function newDict(from) {
+    const out = Object.create(null);
+    if (from) {
+        // defineProperty, not assignment: an own "__proto__" key of `from` must stay an entry.
+        for (const k of Object.keys(from))
+            Object.defineProperty(out, k, { value: from[k], enumerable: true, writable: true, configurable: true });
+    }
+    return out;
+}
+function corrupt(taskId, seq, reason) {
+    throw new LogCorruptError(taskId, seq, reason);
+}
+/** Validates a plan declaration; returns the first problem or `null`. Shared by the runtime (nice errors) and the fold (strictness). */
+export function planProblem(steps) {
+    const ids = new Set();
+    for (const s of steps) {
+        if (ids.has(s.id))
+            return `duplicate step id "${s.id}"`;
+        ids.add(s.id);
+    }
+    for (const s of steps) {
+        for (const d of s.dependsOn) {
+            if (!ids.has(d))
+                return `step "${s.id}" depends on unknown step "${d}"`;
+            if (d === s.id)
+                return `step "${s.id}" depends on itself`;
+        }
+    }
+    // cycle detection (Kahn)
+    const indeg = new Map(steps.map((s) => [s.id, s.dependsOn.length]));
+    const queue = steps.filter((s) => s.dependsOn.length === 0).map((s) => s.id);
+    let visited = 0;
+    while (queue.length > 0) {
+        const id = queue.pop();
+        visited++;
+        for (const s of steps) {
+            if (s.dependsOn.includes(id)) {
+                const n = indeg.get(s.id) - 1;
+                indeg.set(s.id, n);
+                if (n === 0)
+                    queue.push(s.id);
+            }
+        }
+    }
+    return visited === steps.length ? null : 'the plan has a dependency cycle';
+}
+export function applyEvent(prevState, e) {
+    const t = e.taskId;
+    if (prevState === null) {
+        if (e.seq !== 1 || e.type !== 'task.created')
+            corrupt(t, e.seq, 'a log must start with task.created at seq 1');
+        const d = e.data;
+        return {
+            taskId: t,
+            kind: d.kind,
+            goal: d.goal,
+            input: d.input,
+            parentTaskId: d.parentTaskId,
+            dependsOn: [...d.dependsOn],
+            labels: newDict(d.labels),
+            status: 'active',
+            createdAt: e.at,
+            updatedAt: e.at,
+            closedAt: null,
+            result: null,
+            error: null,
+            headSeq: 1,
+            headHash: e.hash,
+            epoch: 0,
+            lease: null,
+            plan: null,
+            decisions: [],
+            assumptions: newDict(),
+            observations: newDict(),
+            effects: newDict(),
+            awaits: newDict(),
+            deliveryKeys: newDict(),
+            eventCount: 1,
+        };
+    }
+    const s = prevState;
+    if (e.seq !== s.headSeq + 1)
+        corrupt(t, e.seq, `sequence gap (expected ${s.headSeq + 1})`);
+    if (s.status !== 'active')
+        corrupt(t, e.seq, `event after the terminal state (${s.status})`);
+    switch (e.type) {
+        case 'task.created':
+            return corrupt(t, e.seq, 'task.created after seq 1');
+        case 'run.claimed': {
+            const d = e.data;
+            if (d.epoch !== s.epoch + 1)
+                corrupt(t, e.seq, `claim epoch ${d.epoch} is not ${s.epoch + 1}`);
+            s.epoch = d.epoch;
+            s.lease = { owner: d.owner, epoch: d.epoch, leaseUntil: d.leaseUntil, released: false };
+            break;
+        }
+        case 'run.heartbeat': {
+            const d = e.data;
+            if (!s.lease || s.lease.released || s.lease.epoch !== d.epoch || s.lease.owner !== d.owner) {
+                corrupt(t, e.seq, 'heartbeat from a non-current lease holder');
+            }
+            s.lease.leaseUntil = d.leaseUntil;
+            break;
+        }
+        case 'run.released': {
+            const d = e.data;
+            if (!s.lease || s.lease.released || s.lease.epoch !== d.epoch || s.lease.owner !== d.owner) {
+                corrupt(t, e.seq, 'release from a non-current lease holder');
+            }
+            s.lease.released = true;
+            break;
+        }
+        case 'plan.declared': {
+            const problem = planProblem(e.data.steps);
+            if (problem)
+                corrupt(t, e.seq, `invalid plan: ${problem}`);
+            const previous = new Map((s.plan ?? []).map((p) => [p.id, p]));
+            s.plan = e.data.steps.map((decl) => {
+                const old = previous.get(decl.id);
+                // A re-plan never reopens work that is already closed.
+                if (old && old.status !== 'pending')
+                    return { ...old, title: decl.title, dependsOn: [...decl.dependsOn] };
+                return { id: decl.id, title: decl.title, dependsOn: [...decl.dependsOn], status: 'pending', result: null, skipReason: null, closedAtSeq: null };
+            });
+            break;
+        }
+        case 'plan.step_done':
+        case 'plan.step_skipped': {
+            const step = s.plan?.find((p) => p.id === e.data.stepId);
+            if (!step)
+                corrupt(t, e.seq, `unknown plan step "${e.data.stepId}"`);
+            if (step.status !== 'pending')
+                corrupt(t, e.seq, `plan step "${step.id}" is already ${step.status}`);
+            if (e.type === 'plan.step_done') {
+                step.status = 'done';
+                step.result = e.data.result;
+            }
+            else {
+                step.status = 'skipped';
+                step.skipReason = e.data.reason;
+            }
+            step.closedAtSeq = e.seq;
+            break;
+        }
+        case 'decision.recorded': {
+            if (s.decisions.some((x) => x.id === e.data.id))
+                corrupt(t, e.seq, `duplicate decision id "${e.data.id}"`);
+            s.decisions.push({ id: e.data.id, seq: e.seq, at: e.at, summary: e.data.summary, rationale: e.data.rationale, basedOn: [...e.data.basedOn] });
+            break;
+        }
+        case 'assumption.recorded': {
+            const d = e.data;
+            s.assumptions[d.key] = {
+                key: d.key, statement: d.statement, criticality: d.criticality, fingerprint: d.fingerprint, value: d.value,
+                evidence: d.evidence.map((x) => ({ ...x })), status: 'active', recordedAtSeq: e.seq, retractedReason: null,
+            };
+            break;
+        }
+        case 'assumption.retracted': {
+            const a = s.assumptions[e.data.key];
+            if (!a || a.status !== 'active')
+                corrupt(t, e.seq, `no active assumption "${e.data.key}"`);
+            a.status = 'retracted';
+            a.retractedReason = e.data.reason;
+            break;
+        }
+        case 'fact.observed': {
+            const d = e.data;
+            s.observations[d.key] = { key: d.key, fingerprint: d.fingerprint, value: d.value, source: d.source, seq: e.seq, at: e.at };
+            break;
+        }
+        case 'effect.intended': {
+            const d = e.data;
+            const old = s.effects[d.key];
+            if (old && old.status === 'completed')
+                corrupt(t, e.seq, `effect "${d.key}" is already completed`);
+            s.effects[d.key] = {
+                key: d.key, description: d.description, params: d.params, status: 'intended', intendedAtSeq: e.seq,
+                intendedEpoch: d.epoch, result: null, error: null, retryable: true, uncertain: false,
+            };
+            break;
+        }
+        case 'effect.completed': {
+            const x = s.effects[e.data.key];
+            if (!x || x.status === 'completed')
+                corrupt(t, e.seq, `effect "${e.data.key}" cannot be completed from ${x ? x.status : 'nothing'}`);
+            x.status = 'completed';
+            x.result = e.data.result;
+            x.error = null;
+            x.uncertain = false;
+            break;
+        }
+        case 'effect.failed': {
+            const x = s.effects[e.data.key];
+            if (!x || x.status !== 'intended')
+                corrupt(t, e.seq, `effect "${e.data.key}" cannot fail from ${x ? x.status : 'nothing'}`);
+            x.status = 'failed';
+            x.error = e.data.error;
+            x.retryable = e.data.retryable;
+            x.uncertain = e.data.uncertain === true;
+            break;
+        }
+        case 'await.registered': {
+            const d = e.data;
+            if (s.awaits[d.awaitId])
+                corrupt(t, e.seq, `duplicate await id "${d.awaitId}"`);
+            if (Object.values(s.awaits).some((a) => a.token === d.token))
+                corrupt(t, e.seq, 'duplicate await token');
+            s.awaits[d.awaitId] = {
+                awaitId: d.awaitId, token: d.token, purpose: d.purpose, stepId: d.stepId, request: d.request, deadlineAt: d.deadlineAt,
+                basisSeq: d.basisSeq, registeredAtSeq: e.seq, status: 'pending', resolvedAtSeq: null, payload: null, idempotencyKey: null,
+                source: null, late: false, rejectedDeliveries: 0,
+            };
+            break;
+        }
+        case 'await.resolved': {
+            const d = e.data;
+            const a = s.awaits[d.awaitId];
+            if (!a)
+                corrupt(t, e.seq, `delivery to unknown await "${d.awaitId}"`);
+            if (a.status === 'resolved')
+                corrupt(t, e.seq, `await "${a.awaitId}" is already resolved`);
+            if (a.status === 'expired' && !d.late)
+                corrupt(t, e.seq, 'delivery after expiry must be marked late');
+            const dk = deliveryKey(d.awaitId, d.idempotencyKey);
+            if (dk in s.deliveryKeys)
+                corrupt(t, e.seq, 'idempotency key reused');
+            a.status = 'resolved';
+            a.resolvedAtSeq = e.seq;
+            a.payload = d.payload;
+            a.idempotencyKey = d.idempotencyKey;
+            a.source = d.source;
+            a.late = d.late;
+            s.deliveryKeys[dk] = e.seq;
+            break;
+        }
+        case 'await.delivery_rejected': {
+            const d = e.data;
+            const a = s.awaits[d.awaitId];
+            if (!a || a.status !== 'resolved')
+                corrupt(t, e.seq, 'rejected delivery for an await that is not resolved');
+            const dk = deliveryKey(d.awaitId, d.idempotencyKey);
+            if (dk in s.deliveryKeys)
+                corrupt(t, e.seq, 'idempotency key reused');
+            a.rejectedDeliveries++;
+            s.deliveryKeys[dk] = e.seq;
+            break;
+        }
+        case 'await.expired': {
+            const a = s.awaits[e.data.awaitId];
+            if (!a || a.status !== 'pending')
+                corrupt(t, e.seq, `await "${e.data.awaitId}" cannot expire`);
+            a.status = 'expired';
+            break;
+        }
+        case 'task.completed':
+            s.status = 'completed';
+            s.result = e.data.result;
+            s.closedAt = e.at;
+            break;
+        case 'task.failed':
+            s.status = 'failed';
+            s.error = e.data.error;
+            s.closedAt = e.at;
+            break;
+        case 'task.cancelled':
+            s.status = 'cancelled';
+            s.error = e.data.reason;
+            s.closedAt = e.at;
+            break;
+    }
+    s.headSeq = e.seq;
+    s.headHash = e.hash;
+    s.updatedAt = e.at;
+    s.eventCount++;
+    return s;
+}
+/** Folds a verified, contiguous list of events (starting at seq 1, or continuing `from`). */
+export function foldEvents(events, from = null) {
+    let state = from;
+    for (const e of events)
+        state = applyEvent(state, e);
+    if (state === null)
+        throw new LogCorruptError('?', null, 'empty log');
+    return state;
+}
+/** The state as it was when the log had `seq` events — "what did the task look like when this was sent". */
+export function foldUntil(events, seq) {
+    return foldEvents(events.filter((e) => e.seq <= seq));
+}
+/** Deep copy. `structuredClone` alone would turn the null-prototype dictionaries back into plain objects. */
+export function cloneState(s) {
+    const c = structuredClone(s);
+    c.labels = newDict(c.labels);
+    c.assumptions = newDict(c.assumptions);
+    c.observations = newDict(c.observations);
+    c.effects = newDict(c.effects);
+    c.awaits = newDict(c.awaits);
+    c.deliveryKeys = newDict(c.deliveryKeys);
+    return c;
+}
+export { GENESIS_HASH };

package/dist/durable/prune-check.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Preconditions of an irreversible prune, checked against the task's own log. A pure function over verified events: the
+ * stores call it AFTER the prune attempt is visible in the register, so that any append that lands later closes the
+ * attempt through G2 (ADR-019) instead of being missed by a check-then-act gap.
+ */
+import { type TaskEvent, type TaskState, type Tombstone } from './types.js';
+/** sha256 of the canonical final result/error: what the tombstone keeps instead of the data. */
+export declare function outcomeDigestOf(state: TaskState): string;
+/** The tombstone of a finished task: what remains of it once its data is removed. */
+export declare function tombstoneFor(state: TaskState, prunedAt: string): Tombstone;
+/**
+ * Why `tombstone` may not be used to remove the task whose log is `events`, or `null` when it may. Throws
+ * `LogCorruptError` when the log itself does not verify (a corrupt task is never pruned). `prunedAt` is the pruner's own
+ * clock and is not compared.
+ */
+export declare function tombstoneProblem(taskId: string, events: readonly TaskEvent[], t: Tombstone): string | null;
+/**
+ * Why a COMMITTED prune must not be rolled forward over the data that is still on disk, or `null` when it may.
+ * `events` are the surviving events with `seq <= t.headSeq`, each verified on its own (`parseEvent`), at most one per seq.
+ * Events beyond the committed head are stragglers of appends that lost against the commit (G2 reports them as pruned but
+ * leaves the file): they are deleted with the rest and are not evidence either way.
+ *
+ * What the data can prove depends on whether the roll-forward has begun. It publishes `tombstone.json` BEFORE its first
+ * unlink, so a log with a part missing and no `tombstone.json` was not removed by a roll-forward:
+ *  - `deletionStarted` is false: nothing may be missing. The whole prefix `1..headSeq` must be there and is judged exactly
+ *    like a prepare (`tombstoneProblem`: a finished task with the tombstone's head). A register forged for an active task,
+ *    or one that names a head the log does not have, is caught here, before the first unlink;
+ *  - `deletionStarted` is true: a roll-forward deletes in directory order, so any part of the log may be gone and no check
+ *    may demand the whole of it. The head slot, if it survives, must be the head the commit names; a complete prefix is
+ *    judged as above; a partial one has nothing that contradicts the commit, and a part cannot prove the rest.
+ * Throws `LogCorruptError` when a complete prefix does not verify.
+ */
+export declare function committedProblem(taskId: string, events: readonly TaskEvent[], t: Tombstone, deletionStarted: boolean): string | null;
+//# sourceMappingURL=prune-check.d.ts.map

package/dist/durable/prune-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune-check.d.ts","sourceRoot":"","sources":["../../src/durable/prune-check.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAc,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAExF,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAGxD;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CAK1E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAW1G;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,CAAC,EAAE,SAAS,EAAE,eAAe,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOpI"}

package/dist/durable/prune-check.js

@@ -0,0 +1,72 @@
+/**
+ * Preconditions of an irreversible prune, checked against the task's own log. A pure function over verified events: the
+ * stores call it AFTER the prune attempt is visible in the register, so that any append that lands later closes the
+ * attempt through G2 (ADR-019) instead of being missed by a check-then-act gap.
+ */
+import { canonicalize, sha256Hex } from './canonical.js';
+import { GENESIS_HASH, verifyChain } from './log.js';
+import { foldEvents } from './projection.js';
+import { isTerminal } from './types.js';
+/** sha256 of the canonical final result/error: what the tombstone keeps instead of the data. */
+export function outcomeDigestOf(state) {
+    const outcome = state.status === 'completed' ? state.result : { error: state.error };
+    return sha256Hex(canonicalize((outcome ?? null)));
+}
+/** The tombstone of a finished task: what remains of it once its data is removed. */
+export function tombstoneFor(state, prunedAt) {
+    return {
+        v: 1, taskId: state.taskId, kind: state.kind, finalStatus: state.status, createdAt: state.createdAt, closedAt: state.closedAt,
+        prunedAt, headSeq: state.headSeq, headHash: state.headHash, outcomeDigest: outcomeDigestOf(state),
+    };
+}
+/**
+ * Why `tombstone` may not be used to remove the task whose log is `events`, or `null` when it may. Throws
+ * `LogCorruptError` when the log itself does not verify (a corrupt task is never pruned). `prunedAt` is the pruner's own
+ * clock and is not compared.
+ */
+export function tombstoneProblem(taskId, events, t) {
+    if (events.length === 0)
+        return 'its log has no readable events';
+    verifyChain(taskId, events, 0, GENESIS_HASH);
+    const s = foldEvents(events);
+    if (!isTerminal(s.status))
+        return `the task is ${s.status}, not finished`;
+    if (t.headSeq !== s.headSeq)
+        return `the tombstone names head ${t.headSeq}, the log ends at ${s.headSeq}`;
+    if (t.headHash !== s.headHash)
+        return 'the tombstone head hash is not the hash of the last event of the log';
+    if (t.finalStatus !== s.status)
+        return `the tombstone says "${t.finalStatus}", the task ended "${s.status}"`;
+    if (t.kind !== s.kind || t.createdAt !== s.createdAt || t.closedAt !== s.closedAt)
+        return 'the tombstone does not describe this task';
+    if (t.outcomeDigest !== outcomeDigestOf(s))
+        return 'the tombstone outcome digest is not the digest of the final outcome';
+    return null;
+}
+/**
+ * Why a COMMITTED prune must not be rolled forward over the data that is still on disk, or `null` when it may.
+ * `events` are the surviving events with `seq <= t.headSeq`, each verified on its own (`parseEvent`), at most one per seq.
+ * Events beyond the committed head are stragglers of appends that lost against the commit (G2 reports them as pruned but
+ * leaves the file): they are deleted with the rest and are not evidence either way.
+ *
+ * What the data can prove depends on whether the roll-forward has begun. It publishes `tombstone.json` BEFORE its first
+ * unlink, so a log with a part missing and no `tombstone.json` was not removed by a roll-forward:
+ *  - `deletionStarted` is false: nothing may be missing. The whole prefix `1..headSeq` must be there and is judged exactly
+ *    like a prepare (`tombstoneProblem`: a finished task with the tombstone's head). A register forged for an active task,
+ *    or one that names a head the log does not have, is caught here, before the first unlink;
+ *  - `deletionStarted` is true: a roll-forward deletes in directory order, so any part of the log may be gone and no check
+ *    may demand the whole of it. The head slot, if it survives, must be the head the commit names; a complete prefix is
+ *    judged as above; a partial one has nothing that contradicts the commit, and a part cannot prove the rest.
+ * Throws `LogCorruptError` when a complete prefix does not verify.
+ */
+export function committedProblem(taskId, events, t, deletionStarted) {
+    if (events.length === 0)
+        return deletionStarted ? null : 'the log has no readable events, yet no removal was started';
+    const head = events.find((e) => e.seq === t.headSeq);
+    if (head && head.hash !== t.headHash)
+        return `the surviving event ${t.headSeq} is not the head hash the commit names`;
+    const whole = events.length === t.headSeq && events.every((e, i) => e.seq === i + 1);
+    if (!whole)
+        return deletionStarted ? null : `events of the log are missing (${events.length} of ${t.headSeq} found), yet no removal was started`;
+    return tombstoneProblem(taskId, events, t);
+}

package/dist/durable/register.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The persisted prune decision register: record formats and the pure derivation of the prune state.
+ *
+ * Design A (docs/architecture/DURABLE-PRUNE-PROTOCOL-DESIGN-004.md, sections 5, 19, 20, 32, 37, 41; ADR-019).
+ * This module does no I/O of its own. `derivePruneState` is a function of the names in the task directory and of what
+ * `RegisterIO` returns for them, so its decisions can be tested with injected partial listings and I/O errors
+ * without a filesystem. It never writes, never deletes and never repairs.
+ *
+ * Every verdict is fail-closed: `corrupt`, `unreadable`, `missing` and `legacy` never grant an irreversible action,
+ * and a missing name is never read as permission to delete anything (section 37, "absence of information is not
+ * permission").
+ */
+import { MAX_PRUNE_ATTEMPTS, type DecisionBy, type PruneOutcome, type PruneState, type Tombstone } from './types.js';
+export { MAX_PRUNE_ATTEMPTS };
+/** Re-checks of the register by a writer that has published a file (Design A, section 24.2). */
+export declare const MAX_WRITE_RESOLVE = 3;
+/** A register record is tiny; anything larger is refused before it is read. */
+export declare const MAX_REGISTER_BYTES: number;
+export declare const REGISTER_FORMAT_VERSION = 2;
+/**
+ * Staging files of the write primitive: `<name>.tmp.<pid>.<hex16>`. The ONE definition: the filesystem store uses it
+ * for its own temp names too (Design A, section 20.2, N1), so the register can never mistake a staging file for a record.
+ */
+export declare const STAGING_RE: RegExp;
+export declare const TOMBSTONE_FILE = "tombstone.json";
+export declare const PROTOCOL_MARKER_FILE = "durable-protocol.json";
+export declare const prepareFile: (n: number) => string;
+export declare const decisionFile: (n: number) => string;
+export interface PrepareRecord {
+    v: 2;
+    attempt: number;
+    tombstone: Tombstone;
+    check: string;
+}
+export type DecisionRecord = {
+    v: 2;
+    attempt: number;
+    outcome: 'abort';
+    by?: DecisionBy;
+    check: string;
+} | {
+    v: 2;
+    attempt: number;
+    outcome: 'commit';
+    tombstone: Tombstone;
+    migrated?: true;
+    legacySha256?: string;
+    check: string;
+};
+/** SHA-256 of the canonical serialization of every other field: a guard against accidental damage, not against an adversary. */
+export declare function checkOf(record: object): string;
+export declare function encodePrepare(attempt: number, tombstone: Tombstone): string;
+export declare function encodeDecision(attempt: number, outcome: PruneOutcome, tombstone: Tombstone | undefined, by: DecisionBy | undefined): string;
+/** The `tombstone.json` file published from a commit. Same content, any reader of the v1 format understands it. */
+export declare function encodeTombstone(tombstone: Tombstone): string;
+/** Closed schema of a v1 tombstone. `null` when it is anything else. */
+export declare function asTombstone(v: unknown, taskId: string): Tombstone | null;
+/** Same tombstone, whatever the key order. */
+export declare const sameTombstone: (a: Tombstone, b: Tombstone) => boolean;
+/**
+ * What reading one file gave. `bad` is a PRESENT file that is not a valid record (damage, an unknown schema, a symlink,
+ * a special file) — evidence. `ioerr` is "the value is unknown" (EIO, EACCES, EMFILE): never evidence of anything.
+ */
+export type Obs<T> = {
+    k: 'ok';
+    v: T;
+} | {
+    k: 'absent';
+} | {
+    k: 'bad';
+    reason: string;
+} | {
+    k: 'ioerr';
+    reason: string;
+};
+export declare function parsePrepare(text: string, n: number, taskId: string): Obs<PrepareRecord>;
+export declare function parseDecision(text: string, n: number, taskId: string): Obs<DecisionRecord>;
+/** `tombstone.json` is the v1 format and is written by older code with its own key order: parse leniently, validate strictly. */
+export declare function parseTombstoneFile(text: string, taskId: string): Obs<Tombstone>;
+/**
+ * Reads for `derivePruneState`. Each returns an observation of ONE name in the task directory; a name that is not there
+ * is `absent`. The caller maps its filesystem errors to `ioerr` (never to `absent`) and a refused file (symlink, special
+ * file, wrong size) to `bad`.
+ */
+export interface RegisterIO {
+    prepare(n: number): Obs<PrepareRecord>;
+    decision(n: number): Obs<DecisionRecord>;
+    tombstone(): Obs<Tombstone>;
+}
+/**
+ * The state of a task's register.
+ *
+ * `names` is ONE directory listing of `tasks/<id>/` (not an atomic snapshot: a name created during the listing may be
+ * missing from it). `io` reads individual files. A verdict that rests only on names that were NOT in the listing is
+ * not given without looking those names up (section 32.3); if the lookup finds the names the verdict is recomputed, if
+ * every one is confirmed absent it stands with `basis: 'lookup'`, and if anything cannot be confirmed the answer is
+ * `unreadable` — never a guess.
+ */
+export declare function derivePruneState(names: readonly string[], io: RegisterIO, maxAttempts?: number): PruneState;
+//# sourceMappingURL=register.d.ts.map

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

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