claude-flow 3.49.0 → 3.51.0

package/v3/@claude-flow/cli/dist/src/missions/schemas.js

@@ -0,0 +1,150 @@
+/**
+ * ADR-406 §19.3 — versioned mission schemas.
+ *
+ * `MissionRecord` is the §19.3 logical schema field for field (strict). The
+ * plan body, budget ledger, evidence index and executor observations are kept
+ * in a `MissionView` beside it, so the record itself stays exactly the ADR's.
+ *
+ * Every client input (CLI and MCP alike) is parsed here: strict objects,
+ * bounded strings and arrays, integer monetary units. Principal, tenant and
+ * workspace are never accepted from input; the service derives them.
+ */
+import { z } from 'zod';
+export const MISSION_SCHEMA_VERSION = 1;
+export const MISSION_EVENT_CONTRACT = 'ruflo.mission-event/1';
+export const MISSION_LIMITS = Object.freeze({
+    objective: 2_000,
+    title: 200,
+    text: 500,
+    id: 64,
+    tasks: 100,
+    criteria: 50,
+    deps: 32,
+    capabilities: 32,
+    maxMinor: 1_000_000_000_000, // 10^12 minor units: far above any sane ceiling, below 2^53
+    requestId: 128,
+    eventsPage: 500,
+});
+export const missionStateSchema = z.enum([
+    'draft', 'planned', 'awaitingAuthorization', 'queued',
+    'running', 'pauseRequested', 'paused', 'blocked',
+    'verifying', 'completed', 'failed',
+    'cancelRequested', 'cancelled',
+]);
+export const TERMINAL_STATES = new Set(['completed', 'failed', 'cancelled']);
+export const executionModeSchema = z.enum(['durable-executor', 'session-bound']);
+export const MISSION_ID = /^msn_[a-f0-9]{24}$/;
+const SHORT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const DIGEST = /^(?:sha256:[a-f0-9]{64}|none)$/;
+const text = (max) => z.string().min(1).max(max);
+const shortId = z.string().regex(SHORT_ID);
+const minor = z.number().int().min(0).max(MISSION_LIMITS.maxMinor);
+/** §19.3, exactly. */
+export const missionRecordSchema = z.object({
+    schemaVersion: z.literal(MISSION_SCHEMA_VERSION),
+    missionId: z.string().regex(MISSION_ID),
+    tenantId: text(MISSION_LIMITS.id),
+    workspaceId: text(MISSION_LIMITS.id),
+    ownerPrincipalId: text(MISSION_LIMITS.title),
+    revision: z.number().int().min(1),
+    objective: text(MISSION_LIMITS.objective),
+    plan: z.object({
+        revision: z.number().int().min(0),
+        digest: z.string().regex(DIGEST),
+        taskGraphRef: z.string().max(MISSION_LIMITS.title),
+    }).strict(),
+    policyRef: text(MISSION_LIMITS.title),
+    authorizationRef: text(MISSION_LIMITS.title).optional(),
+    budgetRef: text(MISSION_LIMITS.title),
+    executionMode: executionModeSchema,
+    state: missionStateSchema,
+    evidenceRefs: z.array(text(MISSION_LIMITS.title)),
+    acceptance: z.object({ revision: z.number().int().min(0), criteriaDigest: z.string().regex(DIGEST) }).strict(),
+    lastEventSequence: z.number().int().min(1),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+}).strict();
+// ---------------------------------------------------------------------------
+// Plan input
+// ---------------------------------------------------------------------------
+export const taskSpecSchema = z.object({
+    id: shortId,
+    title: text(MISSION_LIMITS.title),
+    dependsOn: z.array(shortId).max(MISSION_LIMITS.deps).default([]),
+    executor: z.object({
+        mode: executionModeSchema,
+        requirement: text(MISSION_LIMITS.title),
+    }).strict(),
+    capabilityCeiling: z.array(text(MISSION_LIMITS.title)).max(MISSION_LIMITS.capabilities).default([]),
+    estimatedCostMinor: minor.default(0),
+    checkpoint: text(MISSION_LIMITS.title).optional(),
+    acceptanceEvidence: z.array(shortId).max(MISSION_LIMITS.criteria).default([]),
+}).strict();
+export const acceptanceCriterionSchema = z.object({
+    id: shortId,
+    check: text(MISSION_LIMITS.text),
+    inputs: z.array(text(MISSION_LIMITS.title)).max(16).default([]),
+    baseline: text(MISSION_LIMITS.title).optional(),
+    threshold: text(MISSION_LIMITS.title).optional(),
+    producer: text(MISSION_LIMITS.title),
+    independent: z.boolean().default(false),
+    mandatory: z.boolean().default(true),
+}).strict();
+export const budgetSpecSchema = z.object({
+    currency: z.string().regex(/^[A-Z]{3}$/),
+    ceilingMinor: minor.refine((v) => v > 0, 'ceilingMinor must be positive'),
+    tokens: z.number().int().min(0).optional(),
+    wallTimeSeconds: z.number().int().min(0).optional(),
+    concurrency: z.number().int().min(1).max(64).optional(),
+    retries: z.number().int().min(0).max(100).optional(),
+}).strict();
+export const planBodySchema = z.object({
+    tasks: z.array(taskSpecSchema).min(1).max(MISSION_LIMITS.tasks),
+    acceptance: z.array(acceptanceCriterionSchema).min(1).max(MISSION_LIMITS.criteria),
+    budget: budgetSpecSchema,
+    scope: z.object({
+        capabilities: z.array(text(MISSION_LIMITS.title)).max(MISSION_LIMITS.capabilities).default([]),
+    }).strict().default({ capabilities: [] }),
+}).strict();
+// ---------------------------------------------------------------------------
+// Operation inputs (shared by CLI and MCP)
+// ---------------------------------------------------------------------------
+const requestId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/);
+const missionId = z.string().regex(MISSION_ID);
+export const createInputSchema = z.object({
+    requestId,
+    objective: text(MISSION_LIMITS.objective),
+}).strict();
+export const planInputSchema = z.object({
+    requestId,
+    missionId,
+    expectedRevision: z.number().int().min(1),
+    plan: planBodySchema,
+}).strict();
+export const getInputSchema = z.object({ missionId: missionId.optional() }).strict();
+export const eventsInputSchema = z.object({
+    missionId,
+    afterSequence: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(MISSION_LIMITS.eventsPage).default(100),
+}).strict();
+export const requestActionInputSchema = z.object({
+    requestId,
+    missionId,
+    expectedRevision: z.number().int().min(1),
+    action: z.enum(['pause', 'resume', 'cancel', 'requestAuthorization', 'admit']),
+    reason: text(MISSION_LIMITS.text).optional(),
+}).strict();
+// ---------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------
+/** Control events change mission state or authority and bump `revision`. */
+export const CONTROL_EVENTS = [
+    'mission.created', 'plan.validated', 'plan.revised', 'authorization.missing', 'admission.accepted',
+    'executor.acknowledged', 'pause.accepted', 'quiescence.confirmed', 'blocked', 'resume.admitted',
+    'tasks.settled', 'acceptance.passed', 'acceptance.failed', 'cancel.admitted', 'cancel.settled',
+    'failure.verified',
+];
+/** Observations record what was seen; they never change state or revision. */
+export const OBSERVATION_EVENTS = ['executor.observed', 'evidence.recorded', 'task.observed'];
+export const executorConnectionSchema = z.enum(['healthy', 'stale', 'disconnected', 'unknown']);
+//# sourceMappingURL=schemas.js.map

package/v3/@claude-flow/cli/dist/src/missions/service.d.ts

@@ -0,0 +1,88 @@
+/**
+ * ADR-406 §19.7 — the mission semantic operations, shared by every client.
+ *
+ * `mission.create`, `mission.plan`, `mission.get`, `mission.events` and
+ * `mission.requestAction` parse raw input with the same zod schemas whether
+ * the caller is the CLI or an MCP tool. Principal, tenant and workspace are
+ * derived from the trusted local context (the OS user owning this process and
+ * the canonical project path); nothing in the input can name them, and no
+ * input field is treated as proof of permission.
+ *
+ * Every mutation carries a request id and the expected mission revision. A
+ * stale revision is refused with the current one (refreshable conflict). A
+ * repeated request id with the same input returns the original outcome; with
+ * different input it is refused.
+ */
+import { type MissionEvent } from './schemas.js';
+export type Channel = 'cli' | 'mcp';
+export interface MissionContext {
+    readonly projectRoot: string;
+    readonly channel: Channel;
+    readonly now?: () => Date;
+}
+export type MissionResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+    readonly currentRevision?: number;
+};
+export declare class RevisionConflict extends Error {
+    readonly currentRevision: number;
+    constructor(currentRevision: number, expected: number);
+}
+export declare class MissionService {
+    private readonly ctx;
+    private readonly store;
+    private readonly identity;
+    constructor(ctx: MissionContext);
+    private now;
+    private event;
+    /** Same principal + request id earlier in this mission's log: same input replays, other input is refused. */
+    private prior;
+    private publishObservation;
+    create(raw: unknown): Promise<MissionResult<{
+        missionId: string;
+        revision: number;
+        state: string;
+        deduplicated: boolean;
+    }>>;
+    /** Run a control transition with request dedup and an expected-revision check. */
+    private control;
+    plan(raw: unknown): Promise<MissionResult<{
+        missionId: string;
+        revision: number;
+        state: string;
+        deduplicated: boolean;
+        sequence: number;
+        planDigest?: string;
+    }>>;
+    /**
+     * Scoped control requests. Admission and resume need an admitted executor
+     * and a policy-authorized budget reservation (M2); until one exists they are
+     * refused with an explicit reason rather than recorded as if work started.
+     */
+    requestAction(raw: unknown): Promise<MissionResult<{
+        missionId: string;
+        revision: number;
+        state: string;
+        deduplicated: boolean;
+        sequence: number;
+    }>>;
+    get(raw?: unknown): Promise<MissionResult<unknown>>;
+    /**
+     * Events after a cursor. Delivery may repeat; clients deduplicate by
+     * (missionId, seq). `retainedFromSequence` is the oldest event kept; a cursor
+     * older than that gets `gap: true` and must reload a snapshot first.
+     */
+    events(raw: unknown): Promise<MissionResult<{
+        events: MissionEvent[];
+        nextCursor: number;
+        lastEventSequence: number;
+        retainedFromSequence: number;
+        gap: boolean;
+    }>>;
+}
+//# sourceMappingURL=service.d.ts.map

package/v3/@claude-flow/cli/dist/src/missions/service.js

@@ -0,0 +1,278 @@
+/**
+ * ADR-406 §19.7 — the mission semantic operations, shared by every client.
+ *
+ * `mission.create`, `mission.plan`, `mission.get`, `mission.events` and
+ * `mission.requestAction` parse raw input with the same zod schemas whether
+ * the caller is the CLI or an MCP tool. Principal, tenant and workspace are
+ * derived from the trusted local context (the OS user owning this process and
+ * the canonical project path); nothing in the input can name them, and no
+ * input field is treated as proof of permission.
+ *
+ * Every mutation carries a request id and the expected mission revision. A
+ * stale revision is refused with the current one (refreshable conflict). A
+ * repeated request id with the same input returns the original outcome; with
+ * different input it is refused.
+ */
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { resolve } from 'node:path';
+import { MISSION_EVENT_CONTRACT, createInputSchema, eventsInputSchema, getInputSchema, planInputSchema, requestActionInputSchema, } from './schemas.js';
+import { TransitionError, checkTransition, digestOf, validatePlan } from './transitions.js';
+import { eventHash, foldEvent, GENESIS_HASH } from './fold.js';
+import { MissionStore, MissionStoreError } from './store.js';
+import { OBSERVATION_FILE, buildObservation, observeMission } from './observation.js';
+export class RevisionConflict extends Error {
+    currentRevision;
+    constructor(currentRevision, expected) {
+        super(`revision-conflict: expected ${expected}, current ${currentRevision}; refresh and retry`);
+        this.currentRevision = currentRevision;
+    }
+}
+class RequestReuse extends Error {
+    constructor(requestId) { super(`request-id-reuse: ${requestId} was already used with different input`); }
+}
+function identityOf(ctx) {
+    let root;
+    try {
+        root = realpathSync(resolve(ctx.projectRoot));
+    }
+    catch {
+        root = resolve(ctx.projectRoot);
+    }
+    return {
+        principalId: `local:${userInfo().username}`,
+        tenantId: 'local',
+        workspaceId: `ws_${createHash('sha256').update(root).digest('hex').slice(0, 16)}`,
+    };
+}
+function parse(schema, raw) {
+    const r = schema.safeParse(raw);
+    if (!r.success)
+        throw new TransitionError('invalid-input', r.error.issues.map((i) => `${i.path.join('.') || 'input'}: ${i.message}`).join('; '));
+    return r.data;
+}
+function fail(error) {
+    if (error instanceof RevisionConflict)
+        return { ok: false, code: 'revision-conflict', message: error.message, currentRevision: error.currentRevision };
+    if (error instanceof TransitionError || error instanceof MissionStoreError)
+        return { ok: false, code: error.code, message: error.message };
+    if (error instanceof RequestReuse)
+        return { ok: false, code: 'request-id-reuse', message: error.message };
+    return { ok: false, code: 'internal', message: error instanceof Error ? error.message : String(error) };
+}
+export class MissionService {
+    ctx;
+    store;
+    identity;
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.store = new MissionStore(ctx.projectRoot);
+        this.identity = identityOf(ctx);
+    }
+    now() { return (this.ctx.now ?? (() => new Date()))().toISOString(); }
+    event(view, missionId, type, payload, request, control) {
+        const draft = {
+            contract: MISSION_EVENT_CONTRACT,
+            seq: view ? view.record.lastEventSequence + 1 : 1,
+            missionId,
+            type,
+            expectedRevision: request?.expectedRevision ?? null,
+            revision: view ? view.record.revision + (control ? 1 : 0) : 1,
+            principalId: this.identity.principalId,
+            channel: this.ctx.channel,
+            requestId: request?.requestId ?? null,
+            requestDigest: request?.digest ?? null,
+            policyDecisionRef: null,
+            at: this.now(),
+            payload,
+            prevHash: view ? view.lastHash : GENESIS_HASH,
+        };
+        return { ...draft, hash: eventHash(draft) };
+    }
+    /** Same principal + request id earlier in this mission's log: same input replays, other input is refused. */
+    prior(events, requestId, digest) {
+        const hit = events.find((e) => e.requestId === requestId && e.principalId === this.identity.principalId);
+        if (!hit)
+            return null;
+        if (hit.requestDigest !== digest)
+            throw new RequestReuse(requestId);
+        return hit;
+    }
+    async publishObservation() {
+        await this.store.withWorkspaceLock(() => {
+            const views = this.store.listMissionIds().map((id) => this.store.loadView(id)).filter((v) => v !== null);
+            this.store.writeWorkspaceFile(OBSERVATION_FILE, `${JSON.stringify(buildObservation(this.identity.workspaceId, views), null, 2)}\n`);
+        });
+    }
+    async create(raw) {
+        try {
+            const input = parse(createInputSchema, raw);
+            const digest = digestOf({ op: 'mission.create', input });
+            const scope = [this.identity.tenantId, this.identity.principalId, this.identity.workspaceId, 'mission.create', input.requestId].join('\u0000');
+            const missionId = `msn_${createHash('sha256').update(scope).digest('hex').slice(0, 24)}`;
+            this.store.claim(missionId); // atomic; a concurrent duplicate falls through to the dedup check below
+            const result = await this.store.withMission(missionId, (view, log) => {
+                if (view) {
+                    this.prior(log.events, input.requestId, digest);
+                    return { events: [], view, result: { missionId, revision: view.record.revision, state: view.record.state, deduplicated: true } };
+                }
+                const event = this.event(null, missionId, 'mission.created', {
+                    objective: input.objective,
+                    tenantId: this.identity.tenantId,
+                    workspaceId: this.identity.workspaceId,
+                    ownerPrincipalId: this.identity.principalId,
+                    policyRef: 'policy:.claude-flow/policy/state.json',
+                    budgetRef: `budget:${missionId}`,
+                }, { requestId: input.requestId, digest, expectedRevision: null }, true);
+                const next = foldEvent(null, event);
+                return { events: [event], view: next, result: { missionId, revision: next.record.revision, state: next.record.state, deduplicated: false } };
+            });
+            if (!result.deduplicated)
+                await this.publishObservation();
+            return { ok: true, data: result };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+    /** Run a control transition with request dedup and an expected-revision check. */
+    async control(missionId, requestId, expectedRevision, digest, decide) {
+        try {
+            if (!this.store.exists(missionId))
+                throw new MissionStoreError('not-found', missionId);
+            const result = await this.store.withMission(missionId, (view, log) => {
+                if (!view)
+                    throw new MissionStoreError('not-found', missionId);
+                const prior = this.prior(log.events, requestId, digest);
+                if (prior) {
+                    return { events: [], view, result: { missionId, revision: prior.revision, state: view.record.state, deduplicated: true, sequence: prior.seq } };
+                }
+                if (expectedRevision !== view.record.revision)
+                    throw new RevisionConflict(view.record.revision, expectedRevision);
+                const { type, payload, then } = decide(view);
+                checkTransition(view, type, payload);
+                const event = this.event(view, missionId, type, payload, { requestId, digest, expectedRevision }, true);
+                let next = foldEvent(view, event);
+                const events = [event];
+                const follow = then?.(next);
+                if (follow) {
+                    // A consequence decided by the runtime in the same transaction, not a client request.
+                    const second = this.event(next, missionId, follow.type, follow.payload, { requestId: `${requestId}#settle`, digest, expectedRevision: next.record.revision }, true);
+                    next = foldEvent(next, second);
+                    events.push(second);
+                }
+                const lastSeq = events[events.length - 1].seq;
+                return { events, view: next, result: { missionId, revision: next.record.revision, state: next.record.state, deduplicated: false, sequence: lastSeq } };
+            });
+            if (!result.deduplicated)
+                await this.publishObservation();
+            return { ok: true, data: result };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+    async plan(raw) {
+        let input;
+        try {
+            input = parse(planInputSchema, raw);
+        }
+        catch (error) {
+            return fail(error);
+        }
+        const checked = validatePlan(input.plan);
+        if (checked.error !== null)
+            return { ok: false, code: 'invalid-plan', message: checked.error };
+        const planDigest = digestOf(checked.plan);
+        const result = await this.control(input.missionId, input.requestId, input.expectedRevision, digestOf({ op: 'mission.plan', missionId: input.missionId, plan: checked.plan }), (view) => ({ type: view.record.state === 'draft' ? 'plan.validated' : 'plan.revised', payload: { plan: checked.plan, digest: planDigest } }));
+        return result.ok ? { ok: true, data: { ...result.data, planDigest } } : result;
+    }
+    /**
+     * Scoped control requests. Admission and resume need an admitted executor
+     * and a policy-authorized budget reservation (M2); until one exists they are
+     * refused with an explicit reason rather than recorded as if work started.
+     */
+    async requestAction(raw) {
+        let input;
+        try {
+            input = parse(requestActionInputSchema, raw);
+        }
+        catch (error) {
+            return fail(error);
+        }
+        if (input.action === 'admit' || input.action === 'resume') {
+            return {
+                ok: false,
+                code: 'executor-unavailable',
+                message: 'no durable executor independent of the Claude process is admitted yet; admission and resume are not available (ADR-406 M2)',
+            };
+        }
+        const digest = digestOf({ op: 'mission.requestAction', input });
+        return this.control(input.missionId, input.requestId, input.expectedRevision, digest, (view) => {
+            if (input.action === 'requestAuthorization')
+                return { type: 'authorization.missing', payload: { reason: input.reason ?? 'authorization requested for review' } };
+            if (input.action === 'pause')
+                return { type: 'pause.accepted', payload: { reason: input.reason ?? null } };
+            // Nothing was ever admitted to an executor, so no executor holds work to
+            // acknowledge: settlement is immediate. Otherwise the mission stays
+            // cancelRequested until the executor confirms (§9, §19.4).
+            const neverAdmitted = view.lease.epoch === 0 && view.lease.executorId === null;
+            return {
+                type: 'cancel.admitted',
+                payload: { reason: input.reason ?? null },
+                then: neverAdmitted ? () => ({ type: 'cancel.settled', payload: { acknowledgedExecutors: [], settledBy: 'no-executor-admitted' } }) : undefined,
+            };
+        });
+    }
+    async get(raw = {}) {
+        try {
+            const input = parse(getInputSchema, raw ?? {});
+            if (input.missionId) {
+                const view = this.store.exists(input.missionId) ? this.store.loadView(input.missionId) : null;
+                if (!view)
+                    throw new MissionStoreError('not-found', input.missionId);
+                return { ok: true, data: { record: view.record, plan: view.planBody, budget: view.budget, tasks: view.tasks, evidence: view.evidence, executor: view.executor, unresolvedOperations: view.unresolvedOperations, blockedReason: view.blockedReason } };
+            }
+            const missions = this.store.listMissionIds().map((id) => this.store.loadView(id)).filter((v) => v !== null).map(observeMission);
+            return { ok: true, data: { workspaceId: this.identity.workspaceId, missions } };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+    /**
+     * Events after a cursor. Delivery may repeat; clients deduplicate by
+     * (missionId, seq). `retainedFromSequence` is the oldest event kept; a cursor
+     * older than that gets `gap: true` and must reload a snapshot first.
+     */
+    async events(raw) {
+        try {
+            const input = parse(eventsInputSchema, raw);
+            if (!this.store.exists(input.missionId))
+                throw new MissionStoreError('not-found', input.missionId);
+            const log = this.store.readLog(input.missionId);
+            // Validate the whole chain before serving any of it.
+            let view = null;
+            for (const e of log.events)
+                view = foldEvent(view, e);
+            const retainedFromSequence = 1;
+            const page = log.events.filter((e) => e.seq > input.afterSequence).slice(0, input.limit);
+            const last = log.events.length ? log.events[log.events.length - 1].seq : 0;
+            return {
+                ok: true,
+                data: {
+                    events: page,
+                    nextCursor: page.length ? page[page.length - 1].seq : Math.min(input.afterSequence, last),
+                    lastEventSequence: last,
+                    retainedFromSequence,
+                    gap: input.afterSequence + 1 < retainedFromSequence,
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+}
+//# sourceMappingURL=service.js.map

package/v3/@claude-flow/cli/dist/src/missions/store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * ADR-406 M0 — durable mission storage.
+ *
+ * Store decision (audit in the PR): ruflo's authoritative state already lives
+ * in project files guarded by a lock and replaced atomically (the policy
+ * ledger in `.claude-flow/policy/`, claims, workspace leases). `better-sqlite3`
+ * is an optional dependency the CLI must run without, and `sql.js` keeps the
+ * database in memory and persists by whole-file export, which is neither
+ * append-durable nor safe across processes. So a mission is:
+ *
+ *   .claude-flow/missions/<missionId>/events.jsonl   append-only, hash-chained
+ *   .claude-flow/missions/<missionId>/snapshot.json  materialized cache (rebuildable)
+ *   .claude-flow/missions/<missionId>/lock           per-mission writer lock
+ *
+ * The log is the truth; the snapshot is only a cache that must agree with it.
+ * Each event is one write of one line followed by fsync. A crash can leave at
+ * most an unterminated last line, which readers ignore and the next locked
+ * writer truncates. Writers take the policy runtime's lock (`acquireLock`),
+ * which recognises a dead owner by pid, pid namespace and boot id.
+ */
+import { type MissionEvent } from './schemas.js';
+import type { MissionView } from './transitions.js';
+export declare const MISSIONS_DIR: string;
+export interface LogRead {
+    readonly events: MissionEvent[];
+    /** Bytes covered by complete lines; anything after is a torn tail. */
+    readonly validBytes: number;
+    readonly tornTail: boolean;
+}
+export declare class MissionStoreError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** tmp + fsync + rename + directory fsync. */
+export declare function writeFileAtomic(path: string, text: string, mode?: number): void;
+export declare function parseLog(buffer: Buffer): LogRead;
+export declare class MissionStore {
+    readonly root: string;
+    constructor(projectRoot: string);
+    missionDir(missionId: string): string;
+    private logPath;
+    private snapshotPath;
+    exists(missionId: string): boolean;
+    listMissionIds(): string[];
+    /** Atomic claim of a new mission id: `mkdir` fails if another request won. */
+    claim(missionId: string): boolean;
+    readLog(missionId: string): LogRead;
+    /** Snapshot when it agrees with the log, then fold the tail; otherwise full replay. */
+    loadView(missionId: string, log?: LogRead): MissionView | null;
+    /**
+     * Run `fn` under the mission's writer lock with a freshly replayed view.
+     * Events `fn` returns are appended (each fsynced) only after `fn` validated
+     * them, then the snapshot is refreshed.
+     */
+    withMission<T>(missionId: string, fn: (view: MissionView | null, log: LogRead) => {
+        events: MissionEvent[];
+        result: T;
+        view: MissionView | null;
+    }): Promise<T>;
+    private append;
+    writeSnapshot(missionId: string, view: MissionView): void;
+    /** For diagnostics and tests: the log file's size in bytes. */
+    logSize(missionId: string): number;
+    /** Workspace-level lock for the observation file. */
+    withWorkspaceLock<T>(fn: () => T): Promise<T>;
+    writeWorkspaceFile(name: string, text: string): void;
+}
+//# sourceMappingURL=store.d.ts.map