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

package/dist/durable/assess.js

@@ -0,0 +1,239 @@
+/**
+ * Resume assessment — "may I simply carry on?"
+ *
+ * A pure, deterministic function of a task's state and log (no clock except
+ * the `now` the caller passes, no I/O, no LLM). It answers the question every
+ * resumed agentic task has to answer, and classifies the answer into the
+ * three continuation scenarios:
+ *
+ *  - `direct`   : results are in, nothing the plan relied on changed, the next
+ *                 step is known — continue without further reasoning.
+ *  - `adaptive` : results are in, the world moved, but nothing *blocking* was
+ *                 invalidated — continue, taking the listed changes into account.
+ *  - `recovery` : a blocking assumption broke, an effect is in doubt, an awaited
+ *                 result never came, or the next step is unknown — the plan can't
+ *                 be trusted; hand the resume packet to a reasoning component.
+ *
+ * plus `waiting` (nothing runnable yet; more results are expected) and
+ * `closed` (terminal). The classification is conservative: a doubt is never
+ * resolved in favour of `direct`.
+ *
+ * The assessment compares *recorded* assumptions with the *current* values of
+ * the facts they were about. Current values come from `fact.observed` events
+ * (other agents/systems reporting) and from `observations` the caller supplies
+ * live; the live value wins. Durable State does not know how to look at the
+ * world — the application does — but it knows what the plan relied on.
+ */
+import { canonicalize, fingerprintOf, toJson } from './canonical.js';
+const WORLD_TYPES = new Set(['fact.observed', 'plan.declared', 'assumption.recorded', 'assumption.retracted', 'decision.recorded']);
+const PROGRESS_TYPES = new Set(['plan.step_done', 'plan.step_skipped', 'decision.recorded', 'effect.completed']);
+function keyOf(e) {
+    switch (e.type) {
+        case 'fact.observed':
+        case 'assumption.recorded':
+        case 'assumption.retracted':
+            return e.data.key;
+        case 'decision.recorded':
+            return e.data.id;
+        default:
+            return null;
+    }
+}
+export function leaseIsLive(state, now) {
+    const l = state.lease;
+    return l !== null && !l.released && Date.parse(l.leaseUntil) > now.getTime();
+}
+export function assessTask(state, events, opts) {
+    const reasons = [];
+    const base = {
+        taskId: state.taskId,
+        status: state.status,
+        headSeq: state.headSeq,
+    };
+    const live = leaseIsLive(state, opts.now);
+    if (state.status !== 'active') {
+        return {
+            ...base, mode: 'closed', reasons, nextSteps: [], planComplete: state.plan?.every((p) => p.status !== 'pending') ?? false,
+            results: [], pendingAwaits: [], assumptionChanges: [], unresolvedEffects: [], sinceSend: [], claimable: false,
+        };
+    }
+    const awaits = Object.values(state.awaits).sort((a, b) => a.registeredAtSeq - b.registeredAtSeq);
+    const plan = state.plan ?? [];
+    const stepById = new Map(plan.map((p) => [p.id, p]));
+    const closed = (id) => stepById.get(id)?.status !== 'pending';
+    // --- plan readiness -------------------------------------------------------
+    const nextSteps = plan.filter((p) => {
+        if (p.status !== 'pending')
+            return false;
+        if (!p.dependsOn.every(closed))
+            return false;
+        return awaits.filter((a) => a.stepId === p.id).every((a) => a.status === 'resolved');
+    });
+    const pendingSteps = plan.filter((p) => p.status === 'pending');
+    const planComplete = state.plan !== null && pendingSteps.length === 0;
+    const pendingAwaits = awaits
+        .filter((a) => a.status === 'pending')
+        .map((a) => ({ awaitId: a.awaitId, purpose: a.purpose, stepId: a.stepId, deadlineAt: a.deadlineAt, registeredAtSeq: a.registeredAtSeq }));
+    // --- results that arrived but were not acted on ---------------------------
+    const lastProgress = events.reduce((m, e) => (PROGRESS_TYPES.has(e.type) ? Math.max(m, e.seq) : m), 0);
+    const results = awaits
+        .filter((a) => a.status === 'resolved')
+        .filter((a) => (a.stepId !== null && stepById.has(a.stepId) ? stepById.get(a.stepId)?.status === 'pending' : a.resolvedAtSeq > lastProgress))
+        .map((a) => ({
+        awaitId: a.awaitId, stepId: a.stepId, purpose: a.purpose, payload: a.payload, late: a.late, basisSeq: a.basisSeq,
+        resolvedAtSeq: a.resolvedAtSeq,
+    }));
+    // --- assumptions vs. the present -----------------------------------------
+    const liveObs = new Map();
+    const liveVal = new Map();
+    for (const [k, v] of Object.entries(opts.observations ?? {})) {
+        const j = toJson(v, `observation ${k}`);
+        liveObs.set(k, fingerprintOf(j));
+        liveVal.set(k, j);
+    }
+    const assumptionChanges = [];
+    const unverified = opts.unverifiedBlocking ?? 'adaptive';
+    for (const a of Object.values(state.assumptions).filter((x) => x.status === 'active').sort((x, y) => (x.key < y.key ? -1 : x.key > y.key ? 1 : 0))) {
+        const liveFp = liveObs.get(a.key);
+        const rec = state.observations[a.key];
+        const currentFp = liveFp ?? rec?.fingerprint;
+        if (currentFp === undefined) {
+            if (a.criticality === 'blocking' && unverified !== 'ignore') {
+                reasons.push({
+                    code: 'BLOCKING_ASSUMPTION_UNVERIFIED',
+                    severity: unverified === 'recovery' ? 'recovery' : 'adaptive',
+                    detail: `no current value is known for blocking assumption "${a.key}": ${a.statement}`,
+                    refs: [a.key],
+                });
+            }
+            continue;
+        }
+        // A recorded observation older than the assumption says nothing about what changed since.
+        if (liveFp === undefined && rec && rec.seq < a.recordedAtSeq)
+            continue;
+        if (currentFp !== a.fingerprint) {
+            assumptionChanges.push({
+                key: a.key, criticality: a.criticality, statement: a.statement, was: a.value,
+                now: liveFp !== undefined ? liveVal.get(a.key) : (rec?.value ?? null), source: liveFp !== undefined ? 'live' : 'recorded',
+            });
+            reasons.push({
+                code: a.criticality === 'blocking' ? 'BLOCKING_ASSUMPTION_CHANGED' : 'ADVISORY_ASSUMPTION_CHANGED',
+                severity: a.criticality === 'blocking' ? 'recovery' : 'adaptive',
+                detail: `assumption "${a.key}" no longer holds: ${a.statement}`,
+                refs: [a.key],
+            });
+        }
+    }
+    // --- effects whose outcome is unknown --------------------------------------
+    const unresolvedEffects = Object.values(state.effects)
+        .filter((x) => x.status === 'intended' || (x.status === 'failed' && x.uncertain))
+        .sort((a, b) => a.intendedAtSeq - b.intendedAtSeq)
+        .map((x) => ({
+        key: x.key, description: x.description, intendedAtSeq: x.intendedAtSeq,
+        // In flight (not in doubt) only while its own epoch still holds a live lease. A call that already
+        // failed with an unknown outcome is not in flight: nobody is going to record a result for it.
+        inDoubt: x.status === 'failed' || !(live && state.lease !== null && x.intendedEpoch === state.lease.epoch),
+        uncertainFailure: x.status === 'failed',
+    }));
+    for (const x of unresolvedEffects.filter((u) => u.inDoubt)) {
+        reasons.push({
+            code: 'EFFECT_IN_DOUBT', severity: 'recovery',
+            detail: x.uncertainFailure
+                ? `effect "${x.key}" (${x.description}) failed with an unknown outcome: the external operation may have taken effect`
+                : `effect "${x.key}" (${x.description}) was started but its outcome was never recorded`,
+            refs: [x.key],
+        });
+    }
+    // --- awaits that did not deliver -------------------------------------------
+    for (const a of awaits) {
+        if (a.status === 'expired') {
+            reasons.push({ code: 'AWAIT_EXPIRED', severity: 'recovery', detail: `no result for "${a.purpose}" arrived before its deadline`, refs: [a.awaitId] });
+        }
+        else if (a.status === 'resolved' && a.late) {
+            reasons.push({ code: 'LATE_RESULT', severity: 'adaptive', detail: `the result for "${a.purpose}" arrived after it was declared expired`, refs: [a.awaitId] });
+        }
+    }
+    // --- what happened elsewhere while we waited -------------------------------
+    const sinceSend = [];
+    if (results.length > 0) {
+        const oldest = results.reduce((m, r) => Math.min(m, r.basisSeq), Number.MAX_SAFE_INTEGER);
+        const senderOf = (awaitId) => {
+            const reg = events.find((e) => e.type === 'await.registered' && e.data.awaitId === awaitId);
+            return reg ? reg.actor : null;
+        };
+        const ownActors = new Set(results.map((r) => senderOf(r.awaitId)));
+        for (const e of events) {
+            if (e.seq <= oldest || !WORLD_TYPES.has(e.type))
+                continue;
+            if (e.actor !== null && ownActors.has(e.actor))
+                continue;
+            sinceSend.push({ seq: e.seq, type: e.type, at: e.at, actor: e.actor, key: keyOf(e) });
+        }
+        if (sinceSend.some((e) => e.type === 'plan.declared')) {
+            reasons.push({ code: 'REPLANNED_SINCE_SEND', severity: 'adaptive', detail: 'the plan was changed by someone else after the request was sent', refs: [] });
+        }
+        const facts = sinceSend.filter((e) => e.type !== 'plan.declared');
+        if (facts.length > 0) {
+            reasons.push({
+                code: 'WORLD_CHANGED_SINCE_SEND', severity: 'adaptive',
+                detail: `${facts.length} change(s) by other actors were recorded after the request was sent`, refs: facts.map((f) => String(f.seq)),
+            });
+        }
+    }
+    // --- plan shape --------------------------------------------------------------
+    const anyProgress = events.some((e) => PROGRESS_TYPES.has(e.type) || e.type.startsWith('await.') || e.type.startsWith('effect.'));
+    if (state.plan === null) {
+        reasons.push(anyProgress
+            ? { code: 'NO_PLAN_BUT_PROGRESS', severity: 'recovery', detail: 'work was recorded but no plan exists, so the next step is unknown', refs: [] }
+            : { code: 'NO_PLAN_YET', severity: 'info', detail: 'the task has no plan yet', refs: [] });
+    }
+    else if (pendingSteps.length > 0 && nextSteps.length === 0 && pendingAwaits.length === 0 && !reasons.some((r) => r.code === 'AWAIT_EXPIRED')) {
+        reasons.push({ code: 'PLAN_STUCK', severity: 'recovery', detail: 'steps remain but none can run and nothing is awaited', refs: pendingSteps.map((p) => p.id) });
+    }
+    if (live && state.lease) {
+        reasons.push({ code: 'LEASE_HELD', severity: 'info', detail: `held by "${state.lease.owner}" until ${state.lease.leaseUntil}`, refs: [state.lease.owner] });
+    }
+    // --- classification --------------------------------------------------------------
+    const has = (sev) => reasons.some((r) => r.severity === sev);
+    let mode;
+    if (has('recovery'))
+        mode = 'recovery';
+    else if (nextSteps.length === 0 && !planComplete && pendingAwaits.length > 0)
+        mode = 'waiting';
+    else if (has('adaptive'))
+        mode = 'adaptive';
+    else
+        mode = 'direct';
+    return {
+        ...base, mode, reasons, nextSteps, planComplete, results, pendingAwaits, assumptionChanges, unresolvedEffects, sinceSend,
+        claimable: !live,
+    };
+}
+function sameJson(a, b) {
+    return canonicalize(toJson(a)) === canonicalize(toJson(b));
+}
+/** What differs between `before` (e.g. the state when a request was sent) and `after` (now). */
+export function diffStates(before, after) {
+    const out = [];
+    const cmp = (section, a, b) => {
+        for (const k of Object.keys(b).sort()) {
+            if (!Object.hasOwn(a, k))
+                out.push({ section, key: k, change: 'added' });
+            else if (!sameJson(a[k], b[k]))
+                out.push({ section, key: k, change: 'changed' });
+        }
+        for (const k of Object.keys(a).sort())
+            if (!Object.hasOwn(b, k))
+                out.push({ section, key: k, change: 'removed' });
+    };
+    const byId = (xs) => Object.fromEntries((xs ?? []).map((x) => [x.id, x]));
+    cmp('plan', byId(before.plan), byId(after.plan));
+    cmp('assumptions', before.assumptions, after.assumptions);
+    cmp('observations', before.observations, after.observations);
+    cmp('effects', before.effects, after.effects);
+    cmp('awaits', before.awaits, after.awaits);
+    cmp('decisions', byId(before.decisions), byId(after.decisions));
+    if (before.status !== after.status)
+        out.push({ section: 'status', key: 'status', change: 'changed' });
+    return out;
+}

package/dist/durable/canonical.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Canonical JSON and hashing.
+ *
+ * Event hashes must be identical on every machine and every run, so objects
+ * are serialized with sorted keys. Application data is validated to be plain
+ * JSON up front: a value that would not survive a round trip (undefined in an
+ * array, NaN, a Date, a class instance, a cycle) is rejected at the boundary
+ * instead of being silently altered by `JSON.stringify` — a durable record
+ * must read back exactly as it was written.
+ */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * Deep-copies `value` into plain JSON. Properties whose value is `undefined`
+ * are dropped (the usual optional-field idiom); everything that is not
+ * representable is a `ValidationError` naming the path, never the value.
+ */
+export declare function toJson(value: unknown, label?: string): Json;
+/** Deterministic serialization: object keys sorted by UTF-16 code unit order. */
+export declare function canonicalize(v: Json): string;
+export declare function sha256Hex(data: string | Buffer): string;
+/** Fingerprint of an observed value; equal values (any key order) give equal fingerprints. */
+export declare function fingerprintOf(value: unknown): string;
+//# sourceMappingURL=canonical.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/durable/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,MAAM,IAAI,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAIvF;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAU,GAAG,IAAI,CAE5D;AAoCD,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAK5C;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAEvD;AAED,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD"}

package/dist/durable/canonical.js

@@ -0,0 +1,78 @@
+/**
+ * Canonical JSON and hashing.
+ *
+ * Event hashes must be identical on every machine and every run, so objects
+ * are serialized with sorted keys. Application data is validated to be plain
+ * JSON up front: a value that would not survive a round trip (undefined in an
+ * array, NaN, a Date, a class instance, a cycle) is rejected at the boundary
+ * instead of being silently altered by `JSON.stringify` — a durable record
+ * must read back exactly as it was written.
+ */
+import { createHash } from 'crypto';
+import { ValidationError } from './errors.js';
+const MAX_DEPTH = 64;
+/**
+ * Deep-copies `value` into plain JSON. Properties whose value is `undefined`
+ * are dropped (the usual optional-field idiom); everything that is not
+ * representable is a `ValidationError` naming the path, never the value.
+ */
+export function toJson(value, label = 'value') {
+    return walk(value, label, 0);
+}
+function walk(v, path, depth) {
+    if (depth > MAX_DEPTH)
+        throw new ValidationError(`${path}: nesting deeper than ${MAX_DEPTH}.`);
+    if (v === null)
+        return null;
+    switch (typeof v) {
+        case 'boolean':
+        case 'string':
+            return v;
+        case 'number':
+            if (!Number.isFinite(v))
+                throw new ValidationError(`${path}: non-finite number.`);
+            if (Object.is(v, -0))
+                return 0;
+            return v;
+        case 'object':
+            break;
+        default:
+            throw new ValidationError(`${path}: ${typeof v} is not JSON.`);
+    }
+    if (Array.isArray(v)) {
+        return v.map((item, i) => {
+            if (item === undefined)
+                throw new ValidationError(`${path}[${i}]: undefined in an array.`);
+            return walk(item, `${path}[${i}]`, depth + 1);
+        });
+    }
+    const proto = Object.getPrototypeOf(v);
+    if (proto !== Object.prototype && proto !== null)
+        throw new ValidationError(`${path}: only plain objects are allowed.`);
+    const out = {};
+    for (const key of Object.keys(v)) {
+        const item = v[key];
+        if (item === undefined)
+            continue;
+        if (key === '__proto__')
+            throw new ValidationError(`${path}: key "__proto__" is not allowed.`);
+        out[key] = walk(item, `${path}.${key}`, depth + 1);
+    }
+    return out;
+}
+/** Deterministic serialization: object keys sorted by UTF-16 code unit order. */
+export function canonicalize(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(canonicalize).join(',')}]`;
+    const keys = Object.keys(v).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(v[k])}`).join(',')}}`;
+}
+export function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/** Fingerprint of an observed value; equal values (any key order) give equal fingerprints. */
+export function fingerprintOf(value) {
+    return sha256Hex(canonicalize(toJson(value, 'observation')));
+}

package/dist/durable/cli.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `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 { DurableTasks } from './runtime.js';
+export declare const DURABLE_DIR_NAME = "durable";
+export interface CliIo {
+    cwd: string;
+    out: (s: string) => void;
+    err: (s: string) => void;
+}
+/**
+ * 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 declare function openDurable(cwd: string): DurableTasks;
+/**
+ * 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 declare function initializeDurable(cwd: string): 'initialized' | 'already-initialized';
+/** Returns the process exit code: 0 ok, 1 usage/error, 2 verification found a problem. */
+export declare function runDurable(args: string[], io: CliIo): Promise<number>;
+export declare function runDurableCommand(args: string[]): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/durable/cli.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1B;AAiCD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAErD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,qBAAqB,CAEpF;AAED,0FAA0F;AAC1F,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAwD3E;AAOD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrE"}

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);
+}