byterover-cli 3.5.0 → 3.6.0

package/dist/server/infra/dream/dream-log-schema.js

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+// ── Operation schemas (discriminated on type) ────────────────────────────────
+const ConsolidateOperationSchema = z.object({
+    action: z.enum(['MERGE', 'TEMPORAL_UPDATE', 'CROSS_REFERENCE']),
+    inputFiles: z.array(z.string()),
+    needsReview: z.boolean(),
+    outputFile: z.string().optional(),
+    previousTexts: z.record(z.string(), z.string()).optional(),
+    reason: z.string(),
+    type: z.literal('CONSOLIDATE'),
+});
+const SynthesizeOperationSchema = z.object({
+    action: z.enum(['CREATE', 'UPDATE']),
+    confidence: z.number().min(0).max(1),
+    needsReview: z.boolean(),
+    outputFile: z.string(),
+    sources: z.array(z.string()),
+    type: z.literal('SYNTHESIZE'),
+});
+const PruneOperationSchema = z.object({
+    action: z.enum(['ARCHIVE', 'KEEP', 'SUGGEST_MERGE']),
+    file: z.string(),
+    mergeTarget: z.string().optional(),
+    needsReview: z.boolean(),
+    reason: z.string(),
+    stubPath: z.string().optional(),
+    type: z.literal('PRUNE'),
+});
+export const DreamOperationSchema = z.discriminatedUnion('type', [
+    ConsolidateOperationSchema,
+    SynthesizeOperationSchema,
+    PruneOperationSchema,
+]);
+// ── Summary schema ───────────────────────────────────────────────────────────
+export const DreamLogSummarySchema = z.object({
+    consolidated: z.number().int().min(0),
+    errors: z.number().int().min(0),
+    flaggedForReview: z.number().int().min(0),
+    pruned: z.number().int().min(0),
+    synthesized: z.number().int().min(0),
+});
+// ── Entry schema (discriminated on status) ───────────────────────────────────
+const DreamLogEntryBaseSchema = z.object({
+    id: z.string().regex(/^drm-\d+$/),
+    operations: z.array(DreamOperationSchema),
+    startedAt: z.number(),
+    summary: DreamLogSummarySchema,
+    taskId: z.string().optional(),
+    trigger: z.enum(['agent-idle', 'manual', 'cli']),
+});
+export const DreamLogEntrySchema = z.discriminatedUnion('status', [
+    DreamLogEntryBaseSchema.extend({ completedAt: z.number(), status: z.literal('completed') }),
+    DreamLogEntryBaseSchema.extend({ abortReason: z.string(), completedAt: z.number(), status: z.literal('partial') }),
+    DreamLogEntryBaseSchema.extend({ completedAt: z.number(), error: z.string(), status: z.literal('error') }),
+    DreamLogEntryBaseSchema.extend({ status: z.literal('processing') }),
+    DreamLogEntryBaseSchema.extend({ completedAt: z.number(), status: z.literal('undone'), undoneAt: z.number() }),
+]);

package/dist/server/infra/dream/dream-log-store.d.ts

@@ -0,0 +1,55 @@
+import { type DreamLogEntry, type DreamLogStatus } from './dream-log-schema.js';
+type DreamLogStoreOptions = {
+    baseDir: string;
+    maxEntries?: number;
+};
+/**
+ * File-based store for dream log entries.
+ *
+ * Each entry is stored as a JSON file:
+ *   {baseDir}/dream-log/drm-{timestamp_ms}.json
+ *
+ * Writes are atomic (tmp → rename). Reads validate with Zod and return null
+ * for corrupt/missing files. Prunes oldest entries when maxEntries is exceeded.
+ */
+export declare class DreamLogStore {
+    private lastTimestamp;
+    private readonly logDir;
+    private readonly maxEntries;
+    constructor(opts: DreamLogStoreOptions);
+    /**
+     * Retrieve an entry by ID. Returns null if:
+     * - ID format is invalid (security: prevents path traversal)
+     * - File does not exist
+     * - File content fails Zod validation (corrupted)
+     */
+    getById(id: string): Promise<DreamLogEntry | null>;
+    /**
+     * Generate the next monotonic log entry ID in the format `drm-{timestamp_ms}`.
+     * Guaranteed to increase even if called multiple times in the same millisecond.
+     */
+    getNextId(): Promise<string>;
+    /**
+     * List entries sorted newest-first (by timestamp embedded in filename).
+     * Filters (status, after, before) are applied before limit. Skips corrupt entries silently.
+     */
+    list({ after, before, limit, status, }?: {
+        after?: number;
+        before?: number;
+        limit?: number;
+        status?: DreamLogStatus[];
+    }): Promise<DreamLogEntry[]>;
+    /**
+     * Persist a log entry atomically (write to tmp, then rename).
+     * After saving, prunes oldest entries if count exceeds maxEntries (best-effort).
+     */
+    save(entry: DreamLogEntry): Promise<void>;
+    private entryPath;
+    private pruneOldest;
+    /**
+     * If a "processing" entry is older than STALE_PROCESSING_THRESHOLD_MS, the daemon
+     * was killed before it could finalize it. Rewrite as "error" on disk (best-effort).
+     */
+    private resolveStale;
+}
+export {};

package/dist/server/infra/dream/dream-log-store.js

@@ -0,0 +1,141 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DREAM_LOG_DIR, DREAM_LOG_ID_PREFIX } from '../../constants.js';
+import { DreamLogEntrySchema } from './dream-log-schema.js';
+const ID_PATTERN = new RegExp(`^${DREAM_LOG_ID_PREFIX}-\\d+$`);
+const DEFAULT_MAX_ENTRIES = 50;
+/** Entries stuck in "processing" longer than this are considered interrupted. */
+const STALE_PROCESSING_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
+/**
+ * File-based store for dream log entries.
+ *
+ * Each entry is stored as a JSON file:
+ *   {baseDir}/dream-log/drm-{timestamp_ms}.json
+ *
+ * Writes are atomic (tmp → rename). Reads validate with Zod and return null
+ * for corrupt/missing files. Prunes oldest entries when maxEntries is exceeded.
+ */
+export class DreamLogStore {
+    lastTimestamp = 0;
+    logDir;
+    maxEntries;
+    constructor(opts) {
+        this.logDir = join(opts.baseDir, DREAM_LOG_DIR);
+        this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    }
+    /**
+     * Retrieve an entry by ID. Returns null if:
+     * - ID format is invalid (security: prevents path traversal)
+     * - File does not exist
+     * - File content fails Zod validation (corrupted)
+     */
+    async getById(id) {
+        if (!ID_PATTERN.test(id))
+            return null;
+        try {
+            const raw = await readFile(this.entryPath(id), 'utf8');
+            const parsed = DreamLogEntrySchema.safeParse(JSON.parse(raw));
+            if (!parsed.success)
+                return null;
+            return await this.resolveStale(parsed.data);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Generate the next monotonic log entry ID in the format `drm-{timestamp_ms}`.
+     * Guaranteed to increase even if called multiple times in the same millisecond.
+     */
+    async getNextId() {
+        const now = Date.now();
+        this.lastTimestamp = now <= this.lastTimestamp ? this.lastTimestamp + 1 : now;
+        return `${DREAM_LOG_ID_PREFIX}-${this.lastTimestamp}`;
+    }
+    /**
+     * List entries sorted newest-first (by timestamp embedded in filename).
+     * Filters (status, after, before) are applied before limit. Skips corrupt entries silently.
+     */
+    async list({ after, before, limit, status, } = {}) {
+        let files;
+        try {
+            const entries = await readdir(this.logDir, { withFileTypes: true });
+            files = entries
+                .filter((e) => e.isFile() && e.name.endsWith('.json') && ID_PATTERN.test(e.name.slice(0, -5)))
+                .map((e) => e.name)
+                .sort()
+                .reverse();
+        }
+        catch {
+            return [];
+        }
+        const hasFilters = Boolean(status?.length || after !== undefined || before !== undefined);
+        const filesToRead = hasFilters ? files : files.slice(0, limit ?? files.length);
+        const allEntries = [];
+        await Promise.all(filesToRead.map(async (filename) => {
+            const id = filename.slice(0, -5);
+            const entry = await this.getById(id);
+            if (entry)
+                allEntries.push(entry);
+        }));
+        allEntries.sort((a, b) => b.startedAt - a.startedAt);
+        let results = allEntries;
+        if (status?.length) {
+            results = results.filter((e) => status.includes(e.status));
+        }
+        if (after !== undefined) {
+            results = results.filter((e) => e.startedAt >= after);
+        }
+        if (before !== undefined) {
+            results = results.filter((e) => e.startedAt <= before);
+        }
+        return limit === undefined ? results : results.slice(0, limit);
+    }
+    /**
+     * Persist a log entry atomically (write to tmp, then rename).
+     * After saving, prunes oldest entries if count exceeds maxEntries (best-effort).
+     */
+    async save(entry) {
+        DreamLogEntrySchema.parse(entry);
+        await mkdir(this.logDir, { recursive: true });
+        const filePath = this.entryPath(entry.id);
+        const tmpPath = `${filePath}.${randomUUID()}.tmp`;
+        await writeFile(tmpPath, JSON.stringify(entry, null, 2), 'utf8');
+        await rename(tmpPath, filePath);
+        this.pruneOldest().catch(() => { });
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────────
+    entryPath(id) {
+        return join(this.logDir, `${id}.json`);
+    }
+    async pruneOldest() {
+        const entries = await readdir(this.logDir, { withFileTypes: true });
+        const files = entries
+            .filter((e) => e.isFile() && e.name.endsWith('.json') && ID_PATTERN.test(e.name.slice(0, -5)))
+            .map((e) => e.name)
+            .sort();
+        if (files.length <= this.maxEntries)
+            return;
+        const toDelete = files.slice(0, files.length - this.maxEntries);
+        await Promise.all(toDelete.map((f) => rm(join(this.logDir, f), { force: true }).catch(() => { })));
+    }
+    /**
+     * If a "processing" entry is older than STALE_PROCESSING_THRESHOLD_MS, the daemon
+     * was killed before it could finalize it. Rewrite as "error" on disk (best-effort).
+     */
+    async resolveStale(entry) {
+        if (entry.status !== 'processing')
+            return entry;
+        if (Date.now() - entry.startedAt <= STALE_PROCESSING_THRESHOLD_MS)
+            return entry;
+        const recovered = {
+            ...entry,
+            completedAt: Date.now(),
+            error: 'Interrupted (daemon terminated)',
+            status: 'error',
+        };
+        this.save(recovered).catch(() => { });
+        return recovered;
+    }
+}

package/dist/server/infra/dream/dream-response-schemas.d.ts

@@ -0,0 +1,219 @@
+import { z } from 'zod';
+export declare const ConsolidationActionSchema: z.ZodObject<{
+    confidence: z.ZodOptional<z.ZodNumber>;
+    files: z.ZodArray<z.ZodString, "many">;
+    mergedContent: z.ZodOptional<z.ZodString>;
+    outputFile: z.ZodOptional<z.ZodString>;
+    reason: z.ZodString;
+    type: z.ZodEnum<["MERGE", "TEMPORAL_UPDATE", "CROSS_REFERENCE", "SKIP"]>;
+    updatedContent: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "MERGE" | "SKIP" | "TEMPORAL_UPDATE" | "CROSS_REFERENCE";
+    reason: string;
+    files: string[];
+    confidence?: number | undefined;
+    mergedContent?: string | undefined;
+    outputFile?: string | undefined;
+    updatedContent?: string | undefined;
+}, {
+    type: "MERGE" | "SKIP" | "TEMPORAL_UPDATE" | "CROSS_REFERENCE";
+    reason: string;
+    files: string[];
+    confidence?: number | undefined;
+    mergedContent?: string | undefined;
+    outputFile?: string | undefined;
+    updatedContent?: string | undefined;
+}>;
+export declare const ConsolidateResponseSchema: z.ZodObject<{
+    actions: z.ZodArray<z.ZodObject<{
+        confidence: z.ZodOptional<z.ZodNumber>;
+        files: z.ZodArray<z.ZodString, "many">;
+        mergedContent: z.ZodOptional<z.ZodString>;
+        outputFile: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+        type: z.ZodEnum<["MERGE", "TEMPORAL_UPDATE", "CROSS_REFERENCE", "SKIP"]>;
+        updatedContent: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "MERGE" | "SKIP" | "TEMPORAL_UPDATE" | "CROSS_REFERENCE";
+        reason: string;
+        files: string[];
+        confidence?: number | undefined;
+        mergedContent?: string | undefined;
+        outputFile?: string | undefined;
+        updatedContent?: string | undefined;
+    }, {
+        type: "MERGE" | "SKIP" | "TEMPORAL_UPDATE" | "CROSS_REFERENCE";
+        reason: string;
+        files: string[];
+        confidence?: number | undefined;
+        mergedContent?: string | undefined;
+        outputFile?: string | undefined;
+        updatedContent?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    actions: {
+        type: "MERGE" | "SKIP" | "TEMPORAL_UPDATE" | "CROSS_REFERENCE";
+        reason: string;
+        files: string[];
+        confidence?: number | undefined;
+        mergedContent?: string | undefined;
+        outputFile?: string | undefined;
+        updatedContent?: string | undefined;
+    }[];
+}, {
+    actions: {
+        type: "MERGE" | "SKIP" | "TEMPORAL_UPDATE" | "CROSS_REFERENCE";
+        reason: string;
+        files: string[];
+        confidence?: number | undefined;
+        mergedContent?: string | undefined;
+        outputFile?: string | undefined;
+        updatedContent?: string | undefined;
+    }[];
+}>;
+export type ConsolidationAction = z.infer<typeof ConsolidationActionSchema>;
+export type ConsolidateResponse = z.infer<typeof ConsolidateResponseSchema>;
+export declare const SynthesisCandidateSchema: z.ZodObject<{
+    claim: z.ZodString;
+    confidence: z.ZodNumber;
+    evidence: z.ZodArray<z.ZodObject<{
+        domain: z.ZodString;
+        fact: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        domain: string;
+        fact: string;
+    }, {
+        domain: string;
+        fact: string;
+    }>, "many">;
+    placement: z.ZodString;
+    title: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    confidence: number;
+    claim: string;
+    evidence: {
+        domain: string;
+        fact: string;
+    }[];
+    placement: string;
+}, {
+    title: string;
+    confidence: number;
+    claim: string;
+    evidence: {
+        domain: string;
+        fact: string;
+    }[];
+    placement: string;
+}>;
+export declare const SynthesizeResponseSchema: z.ZodObject<{
+    syntheses: z.ZodArray<z.ZodObject<{
+        claim: z.ZodString;
+        confidence: z.ZodNumber;
+        evidence: z.ZodArray<z.ZodObject<{
+            domain: z.ZodString;
+            fact: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            domain: string;
+            fact: string;
+        }, {
+            domain: string;
+            fact: string;
+        }>, "many">;
+        placement: z.ZodString;
+        title: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        confidence: number;
+        claim: string;
+        evidence: {
+            domain: string;
+            fact: string;
+        }[];
+        placement: string;
+    }, {
+        title: string;
+        confidence: number;
+        claim: string;
+        evidence: {
+            domain: string;
+            fact: string;
+        }[];
+        placement: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    syntheses: {
+        title: string;
+        confidence: number;
+        claim: string;
+        evidence: {
+            domain: string;
+            fact: string;
+        }[];
+        placement: string;
+    }[];
+}, {
+    syntheses: {
+        title: string;
+        confidence: number;
+        claim: string;
+        evidence: {
+            domain: string;
+            fact: string;
+        }[];
+        placement: string;
+    }[];
+}>;
+export type SynthesisCandidate = z.infer<typeof SynthesisCandidateSchema>;
+export type SynthesizeResponse = z.infer<typeof SynthesizeResponseSchema>;
+export declare const PruneDecisionSchema: z.ZodObject<{
+    decision: z.ZodEnum<["ARCHIVE", "KEEP", "MERGE_INTO"]>;
+    file: z.ZodString;
+    mergeTarget: z.ZodOptional<z.ZodString>;
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reason: string;
+    file: string;
+    decision: "ARCHIVE" | "KEEP" | "MERGE_INTO";
+    mergeTarget?: string | undefined;
+}, {
+    reason: string;
+    file: string;
+    decision: "ARCHIVE" | "KEEP" | "MERGE_INTO";
+    mergeTarget?: string | undefined;
+}>;
+export declare const PruneResponseSchema: z.ZodObject<{
+    decisions: z.ZodArray<z.ZodObject<{
+        decision: z.ZodEnum<["ARCHIVE", "KEEP", "MERGE_INTO"]>;
+        file: z.ZodString;
+        mergeTarget: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        reason: string;
+        file: string;
+        decision: "ARCHIVE" | "KEEP" | "MERGE_INTO";
+        mergeTarget?: string | undefined;
+    }, {
+        reason: string;
+        file: string;
+        decision: "ARCHIVE" | "KEEP" | "MERGE_INTO";
+        mergeTarget?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    decisions: {
+        reason: string;
+        file: string;
+        decision: "ARCHIVE" | "KEEP" | "MERGE_INTO";
+        mergeTarget?: string | undefined;
+    }[];
+}, {
+    decisions: {
+        reason: string;
+        file: string;
+        decision: "ARCHIVE" | "KEEP" | "MERGE_INTO";
+        mergeTarget?: string | undefined;
+    }[];
+}>;
+export type PruneDecision = z.infer<typeof PruneDecisionSchema>;
+export type PruneResponse = z.infer<typeof PruneResponseSchema>;

package/dist/server/infra/dream/dream-response-schemas.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+// ── Consolidate ──────────────────────────────────────────────────────────────
+export const ConsolidationActionSchema = z.object({
+    confidence: z.number().min(0).max(1).optional(),
+    files: z.array(z.string()).min(1),
+    mergedContent: z.string().optional(),
+    outputFile: z.string().optional(),
+    reason: z.string(),
+    type: z.enum(['MERGE', 'TEMPORAL_UPDATE', 'CROSS_REFERENCE', 'SKIP']),
+    updatedContent: z.string().optional(),
+});
+export const ConsolidateResponseSchema = z.object({
+    actions: z.array(ConsolidationActionSchema),
+});
+// ── Synthesize ───────────────────────────────────────────────────────────────
+export const SynthesisCandidateSchema = z.object({
+    claim: z.string(),
+    confidence: z.number().min(0).max(1),
+    evidence: z.array(z.object({
+        domain: z.string(),
+        fact: z.string(),
+    })),
+    placement: z.string(),
+    title: z.string(),
+});
+export const SynthesizeResponseSchema = z.object({
+    syntheses: z.array(SynthesisCandidateSchema),
+});
+// ── Prune ────────────────────────────────────────────────────────────────────
+export const PruneDecisionSchema = z.object({
+    decision: z.enum(['ARCHIVE', 'KEEP', 'MERGE_INTO']),
+    file: z.string(),
+    mergeTarget: z.string().optional(),
+    reason: z.string(),
+});
+export const PruneResponseSchema = z.object({
+    decisions: z.array(PruneDecisionSchema),
+});

package/dist/server/infra/dream/dream-state-schema.d.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+export declare const PendingMergeSchema: z.ZodObject<{
+    mergeTarget: z.ZodString;
+    reason: z.ZodString;
+    sourceFile: z.ZodString;
+    suggestedByDreamId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reason: string;
+    mergeTarget: string;
+    sourceFile: string;
+    suggestedByDreamId: string;
+}, {
+    reason: string;
+    mergeTarget: string;
+    sourceFile: string;
+    suggestedByDreamId: string;
+}>;
+export declare const DreamStateSchema: z.ZodObject<{
+    curationsSinceDream: z.ZodNumber;
+    lastDreamAt: z.ZodNullable<z.ZodString>;
+    lastDreamLogId: z.ZodNullable<z.ZodString>;
+    pendingMerges: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        mergeTarget: z.ZodString;
+        reason: z.ZodString;
+        sourceFile: z.ZodString;
+        suggestedByDreamId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        reason: string;
+        mergeTarget: string;
+        sourceFile: string;
+        suggestedByDreamId: string;
+    }, {
+        reason: string;
+        mergeTarget: string;
+        sourceFile: string;
+        suggestedByDreamId: string;
+    }>, "many">>>;
+    totalDreams: z.ZodNumber;
+    version: z.ZodLiteral<1>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    curationsSinceDream: number;
+    lastDreamAt: string | null;
+    lastDreamLogId: string | null;
+    pendingMerges: {
+        reason: string;
+        mergeTarget: string;
+        sourceFile: string;
+        suggestedByDreamId: string;
+    }[];
+    totalDreams: number;
+}, {
+    version: 1;
+    curationsSinceDream: number;
+    lastDreamAt: string | null;
+    lastDreamLogId: string | null;
+    totalDreams: number;
+    pendingMerges?: {
+        reason: string;
+        mergeTarget: string;
+        sourceFile: string;
+        suggestedByDreamId: string;
+    }[] | undefined;
+}>;
+export type DreamState = z.infer<typeof DreamStateSchema>;
+export type PendingMerge = z.infer<typeof PendingMergeSchema>;
+export declare const EMPTY_DREAM_STATE: DreamState;

package/dist/server/infra/dream/dream-state-schema.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export const PendingMergeSchema = z.object({
+    mergeTarget: z.string(),
+    reason: z.string(),
+    sourceFile: z.string(),
+    suggestedByDreamId: z.string(),
+});
+export const DreamStateSchema = z.object({
+    curationsSinceDream: z.number().int().min(0),
+    lastDreamAt: z.string().datetime().nullable(),
+    lastDreamLogId: z.string().nullable(),
+    pendingMerges: z.array(PendingMergeSchema).optional().default([]),
+    totalDreams: z.number().int().min(0),
+    version: z.literal(1),
+});
+export const EMPTY_DREAM_STATE = {
+    curationsSinceDream: 0,
+    lastDreamAt: null,
+    lastDreamLogId: null,
+    pendingMerges: [],
+    totalDreams: 0,
+    version: 1,
+};

package/dist/server/infra/dream/dream-state-service.d.ts

@@ -0,0 +1,38 @@
+import { type DreamState } from './dream-state-schema.js';
+type DreamStateServiceOptions = {
+    baseDir: string;
+};
+/**
+ * File-based persistence for dream state.
+ *
+ * Reads return EMPTY_DREAM_STATE on missing/corrupt files (fail-open).
+ * Writes are atomic (tmp → rename) and validate with Zod before persisting.
+ */
+export declare class DreamStateService {
+    private readonly stateFilePath;
+    constructor(opts: DreamStateServiceOptions);
+    /**
+     * Read-modify-write under a per-file mutex. Serializes concurrent increments
+     * from parallel curate tasks within the same agent process so no updates are lost.
+     */
+    incrementCurationCount(): Promise<void>;
+    read(): Promise<DreamState>;
+    /**
+     * Generic read-modify-write under the same per-file mutex used by
+     * incrementCurationCount. All writers that mutate dream-state.json based on
+     * its current contents (e.g. dream-executor step 7's reset, consolidate's
+     * pendingMerges clear) MUST go through this method, otherwise concurrent
+     * increments can be silently overwritten.
+     */
+    update(updater: (state: DreamState) => DreamState): Promise<DreamState>;
+    /**
+     * Atomic write (tmp file → rename). Does NOT acquire the per-file mutex.
+     *
+     * Direct callers that perform a logical read-modify-write by pairing
+     * {@link read} + write bypass serialization and may lose updates from
+     * concurrent writers. Use {@link update} for any RMW that depends on the
+     * current state.
+     */
+    write(state: DreamState): Promise<void>;
+}
+export {};