twinclaw 1.0.0

package/dist/services/orchestration-service.js

@@ -0,0 +1,422 @@
+import { randomUUID } from 'node:crypto';
+import { cancelOrchestrationJob, completeOrchestrationJob, createOrchestrationJob, failOrchestrationJob, markOrchestrationJobRunning, queueOrchestrationRetry, saveOrchestrationEvent, } from './db.js';
+import { logThought } from '../utils/logger.js';
+const DEFAULT_MAX_CONCURRENT_JOBS = 2;
+const DEFAULT_JOB_TIMEOUT_MS = 20_000;
+const DEFAULT_MAX_RETRY_ATTEMPTS = 1;
+const DEFAULT_FAILURE_CIRCUIT_BREAKER_THRESHOLD = 3;
+const DEFAULT_MAX_GRAPH_NODES = 8;
+const DEFAULT_MAX_GRAPH_DEPTH = 4;
+const ALLOWED_TRANSITIONS = {
+    queued: ['running', 'cancelled'],
+    running: ['queued', 'completed', 'failed', 'cancelled'],
+    completed: [],
+    failed: [],
+    cancelled: [],
+};
+export class OrchestrationService {
+    #maxConcurrentJobs;
+    #jobTimeoutMs;
+    #maxRetryAttempts;
+    #failureCircuitBreakerThreshold;
+    #maxGraphNodes;
+    #maxGraphDepth;
+    #jobs = new Map();
+    #consecutiveFailures = 0;
+    constructor(options = {}) {
+        this.#maxConcurrentJobs = Math.max(1, Number(options.maxConcurrentJobs ?? DEFAULT_MAX_CONCURRENT_JOBS));
+        this.#jobTimeoutMs = Math.max(1_000, Number(options.jobTimeoutMs ?? DEFAULT_JOB_TIMEOUT_MS));
+        this.#maxRetryAttempts = Math.max(0, Number(options.maxRetryAttempts ?? DEFAULT_MAX_RETRY_ATTEMPTS));
+        this.#failureCircuitBreakerThreshold = Math.max(1, Number(options.failureCircuitBreakerThreshold ?? DEFAULT_FAILURE_CIRCUIT_BREAKER_THRESHOLD));
+        this.#maxGraphNodes = Math.max(1, Number(options.maxGraphNodes ?? DEFAULT_MAX_GRAPH_NODES));
+        this.#maxGraphDepth = Math.max(1, Number(options.maxGraphDepth ?? DEFAULT_MAX_GRAPH_DEPTH));
+    }
+    observe(jobId) {
+        const job = this.#jobs.get(jobId);
+        return job ? this.#snapshot(job) : undefined;
+    }
+    cancel(jobId, reason = 'Cancelled by runtime operator.') {
+        const job = this.#jobs.get(jobId);
+        if (!job || this.#isTerminal(job.state)) {
+            return false;
+        }
+        job.abortController.abort();
+        this.#transition(job, 'cancelled', reason);
+        return true;
+    }
+    async runDelegation(request, executor) {
+        if (request.briefs.length === 0) {
+            return {
+                jobs: [],
+                summary: 'Delegation skipped: no briefs were provided.',
+                hasFailures: false,
+            };
+        }
+        if (this.#consecutiveFailures >= this.#failureCircuitBreakerThreshold) {
+            const summary = 'Delegation circuit-breaker is open after repeated failures; execution was blocked.';
+            await logThought(`[Orchestration] ${summary}`);
+            return {
+                jobs: [],
+                summary,
+                hasFailures: true,
+            };
+        }
+        const graph = this.#buildGraph(request);
+        await this.#runGraph(graph, request, executor);
+        const snapshots = graph.topologicalOrder
+            .map((nodeId) => graph.jobsByNodeId.get(nodeId))
+            .filter((job) => !!job)
+            .map((job) => this.#snapshot(job));
+        const hasFailures = snapshots.some((job) => job.state === 'failed' || job.state === 'cancelled');
+        const summary = this.#buildSummary(snapshots);
+        await logThought(`[Orchestration] Delegation finished for session '${request.sessionId}' with ${snapshots.length} job(s).`);
+        return {
+            jobs: snapshots,
+            summary,
+            hasFailures,
+        };
+    }
+    #createJob(request, brief) {
+        const timestamp = new Date().toISOString();
+        const job = {
+            id: randomUUID(),
+            nodeId: brief.id,
+            sessionId: request.sessionId,
+            parentMessage: request.parentMessage,
+            brief,
+            state: 'queued',
+            attempt: 1,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            abortController: new AbortController(),
+        };
+        this.#jobs.set(job.id, job);
+        createOrchestrationJob(job.id, job.sessionId, job.parentMessage, JSON.stringify(job.brief));
+        this.#recordEvent(job, 'queued', `Queued delegation job '${brief.title}'.`);
+        return job;
+    }
+    #buildGraph(request) {
+        if (request.briefs.length > this.#maxGraphNodes) {
+            throw new Error(`[Orchestration] Delegation graph has ${request.briefs.length} nodes, exceeding maxGraphNodes=${this.#maxGraphNodes}.`);
+        }
+        const briefsById = new Map();
+        const dependentsByNodeId = new Map();
+        const unmetDependencies = new Map();
+        for (const brief of request.briefs) {
+            const nodeId = brief.id.trim();
+            if (!nodeId) {
+                throw new Error('[Orchestration] Delegation brief id must be a non-empty string.');
+            }
+            if (briefsById.has(nodeId)) {
+                throw new Error(`[Orchestration] Duplicate delegation node id '${nodeId}'.`);
+            }
+            briefsById.set(nodeId, { ...brief, id: nodeId });
+            dependentsByNodeId.set(nodeId, []);
+        }
+        for (const brief of briefsById.values()) {
+            const deps = brief.dependsOn ?? [];
+            const normalizedDeps = deps.map((dep) => dep.trim()).filter(Boolean);
+            if (normalizedDeps.some((dep) => dep === brief.id)) {
+                throw new Error(`[Orchestration] Node '${brief.id}' cannot depend on itself.`);
+            }
+            for (const dep of normalizedDeps) {
+                if (!briefsById.has(dep)) {
+                    throw new Error(`[Orchestration] Node '${brief.id}' depends on missing node '${dep}'.`);
+                }
+                dependentsByNodeId.get(dep)?.push(brief.id);
+            }
+            unmetDependencies.set(brief.id, new Set(normalizedDeps));
+        }
+        const topologicalOrder = this.#topologicalSort(briefsById, dependentsByNodeId, unmetDependencies);
+        if (topologicalOrder.length !== briefsById.size) {
+            throw new Error('[Orchestration] Delegation graph contains one or more dependency cycles.');
+        }
+        const depth = this.#computeGraphDepth(topologicalOrder, briefsById);
+        if (depth > this.#maxGraphDepth) {
+            throw new Error(`[Orchestration] Delegation graph depth ${depth} exceeds maxGraphDepth=${this.#maxGraphDepth}.`);
+        }
+        const jobsByNodeId = new Map();
+        for (const brief of briefsById.values()) {
+            const job = this.#createJob(request, brief);
+            jobsByNodeId.set(brief.id, job);
+        }
+        return {
+            jobsByNodeId,
+            dependentsByNodeId,
+            unmetDependencies,
+            pendingNodes: new Set(briefsById.keys()),
+            topologicalOrder,
+        };
+    }
+    #topologicalSort(briefsById, dependentsByNodeId, unmetDependencies) {
+        const inDegree = new Map();
+        for (const [nodeId, deps] of unmetDependencies) {
+            inDegree.set(nodeId, deps.size);
+        }
+        const queue = [...briefsById.keys()].filter((nodeId) => (inDegree.get(nodeId) ?? 0) === 0);
+        const ordered = [];
+        while (queue.length > 0) {
+            const nodeId = queue.shift();
+            if (!nodeId) {
+                continue;
+            }
+            ordered.push(nodeId);
+            const children = dependentsByNodeId.get(nodeId) ?? [];
+            for (const child of children) {
+                const next = (inDegree.get(child) ?? 0) - 1;
+                inDegree.set(child, next);
+                if (next === 0) {
+                    queue.push(child);
+                }
+            }
+        }
+        return ordered;
+    }
+    #computeGraphDepth(order, briefsById) {
+        const depths = new Map();
+        let maxDepth = 0;
+        for (const nodeId of order) {
+            const deps = briefsById.get(nodeId)?.dependsOn ?? [];
+            const depth = deps.length === 0
+                ? 1
+                : Math.max(...deps.map((dep) => depths.get(dep) ?? 1)) + 1;
+            depths.set(nodeId, depth);
+            maxDepth = Math.max(maxDepth, depth);
+        }
+        return maxDepth;
+    }
+    async #runGraph(graph, request, executor) {
+        while (graph.pendingNodes.size > 0) {
+            if (this.#consecutiveFailures >= this.#failureCircuitBreakerThreshold) {
+                this.#cancelPendingGraphNodes(graph, 'Cancelled because orchestration circuit-breaker opened.');
+                return;
+            }
+            const readyJobs = this.#selectReadyJobs(graph);
+            if (readyJobs.length === 0) {
+                this.#cancelPendingGraphNodes(graph, 'Cancelled due to unresolved dependencies after upstream failures.');
+                return;
+            }
+            for (const batch of this.#chunkJobs(readyJobs, this.#maxConcurrentJobs)) {
+                const outcomes = await Promise.all(batch.map((job) => this.#executeGraphJob(job, request, executor)));
+                for (const outcome of outcomes) {
+                    if (outcome.retryRequested) {
+                        continue;
+                    }
+                    graph.pendingNodes.delete(outcome.job.nodeId);
+                    if (outcome.job.state === 'completed') {
+                        this.#releaseDependents(outcome.job.nodeId, graph);
+                        continue;
+                    }
+                    if (outcome.job.state === 'failed' || outcome.job.state === 'cancelled') {
+                        this.#cancelDependents(outcome.job.nodeId, graph, outcome.job.error ?? 'Upstream dependency failed.');
+                    }
+                }
+            }
+        }
+    }
+    #selectReadyJobs(graph) {
+        const ready = [];
+        for (const nodeId of graph.pendingNodes) {
+            const job = graph.jobsByNodeId.get(nodeId);
+            if (!job || job.state !== 'queued') {
+                continue;
+            }
+            const unmet = graph.unmetDependencies.get(nodeId);
+            if (!unmet || unmet.size === 0) {
+                ready.push(job);
+            }
+        }
+        ready.sort((a, b) => a.brief.id.localeCompare(b.brief.id));
+        return ready;
+    }
+    async #executeGraphJob(job, request, executor) {
+        if (this.#consecutiveFailures >= this.#failureCircuitBreakerThreshold) {
+            this.#transition(job, 'cancelled', 'Cancelled because orchestration circuit-breaker opened.');
+            return { job, retryRequested: false };
+        }
+        const retryRequested = await this.#executeJob(job, request, executor);
+        return { job, retryRequested };
+    }
+    #releaseDependents(completedNodeId, graph) {
+        const dependents = graph.dependentsByNodeId.get(completedNodeId) ?? [];
+        for (const childNodeId of dependents) {
+            if (!graph.pendingNodes.has(childNodeId)) {
+                continue;
+            }
+            const unmet = graph.unmetDependencies.get(childNodeId);
+            if (!unmet || !unmet.has(completedNodeId)) {
+                continue;
+            }
+            unmet.delete(completedNodeId);
+            const childJob = graph.jobsByNodeId.get(childNodeId);
+            if (!childJob) {
+                continue;
+            }
+            if (unmet.size === 0) {
+                this.#recordEvent(childJob, 'queued', `All dependencies resolved for node '${childNodeId}'.`);
+            }
+            else {
+                this.#recordEvent(childJob, 'queued', `Dependency '${completedNodeId}' resolved for node '${childNodeId}'. Remaining: ${[...unmet].join(', ')}`);
+            }
+        }
+    }
+    #cancelDependents(failedNodeId, graph, reason) {
+        const queue = [...(graph.dependentsByNodeId.get(failedNodeId) ?? [])];
+        while (queue.length > 0) {
+            const nodeId = queue.shift();
+            if (!nodeId || !graph.pendingNodes.has(nodeId)) {
+                continue;
+            }
+            const job = graph.jobsByNodeId.get(nodeId);
+            if (!job || this.#isTerminal(job.state)) {
+                graph.pendingNodes.delete(nodeId);
+                continue;
+            }
+            this.#transition(job, 'cancelled', `Cancelled because dependency '${failedNodeId}' did not complete successfully. ${reason}`);
+            graph.pendingNodes.delete(nodeId);
+            const descendants = graph.dependentsByNodeId.get(nodeId) ?? [];
+            queue.push(...descendants);
+        }
+    }
+    #cancelPendingGraphNodes(graph, reason) {
+        for (const nodeId of [...graph.pendingNodes]) {
+            const job = graph.jobsByNodeId.get(nodeId);
+            if (!job || this.#isTerminal(job.state)) {
+                graph.pendingNodes.delete(nodeId);
+                continue;
+            }
+            this.#transition(job, 'cancelled', reason);
+            graph.pendingNodes.delete(nodeId);
+        }
+    }
+    #chunkJobs(jobs, size) {
+        const chunks = [];
+        for (let index = 0; index < jobs.length; index += size) {
+            chunks.push(jobs.slice(index, index + size));
+        }
+        return chunks;
+    }
+    async #executeJob(job, request, executor) {
+        this.#transition(job, 'running', `Starting attempt ${job.attempt}.`);
+        try {
+            const output = await this.#executeWithTimeout(job, request, executor);
+            this.#transition(job, 'completed', `Attempt ${job.attempt} completed.`, output);
+            this.#consecutiveFailures = 0;
+            return false;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const canRetry = job.attempt <= this.#maxRetryAttempts;
+            if (canRetry) {
+                job.attempt += 1;
+                this.#transition(job, 'queued', `Attempt failed; retrying. Reason: ${message}`);
+                return true;
+            }
+            this.#transition(job, 'failed', `Attempt ${job.attempt} failed: ${message}`);
+            this.#consecutiveFailures += 1;
+            return false;
+        }
+    }
+    async #executeWithTimeout(job, request, executor) {
+        const timeoutMs = job.brief.constraints.timeoutMs > 0
+            ? job.brief.constraints.timeoutMs
+            : this.#jobTimeoutMs;
+        let timeoutHandle = null;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutHandle = setTimeout(() => {
+                job.abortController.abort();
+                reject(new Error(`Delegated job timed out after ${timeoutMs}ms.`));
+            }, timeoutMs);
+        });
+        try {
+            const result = await Promise.race([
+                executor({
+                    request,
+                    job: this.#snapshot(job),
+                    signal: job.abortController.signal,
+                }),
+                timeoutPromise,
+            ]);
+            return result;
+        }
+        finally {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+        }
+    }
+    #transition(job, nextState, detail, output) {
+        const allowed = ALLOWED_TRANSITIONS[job.state];
+        if (!allowed.includes(nextState)) {
+            throw new Error(`[Orchestration] Illegal transition ${job.state} -> ${nextState} for job ${job.id}.`);
+        }
+        job.state = nextState;
+        job.updatedAt = new Date().toISOString();
+        if (nextState === 'running') {
+            job.startedAt = job.startedAt ?? job.updatedAt;
+            markOrchestrationJobRunning(job.id, job.attempt);
+        }
+        else if (nextState === 'completed') {
+            job.completedAt = job.updatedAt;
+            job.output = output ?? '';
+            completeOrchestrationJob(job.id, job.output);
+        }
+        else if (nextState === 'failed') {
+            job.completedAt = job.updatedAt;
+            job.error = detail;
+            failOrchestrationJob(job.id, detail);
+        }
+        else if (nextState === 'cancelled') {
+            job.completedAt = job.updatedAt;
+            job.error = detail;
+            cancelOrchestrationJob(job.id, detail);
+        }
+        else {
+            queueOrchestrationRetry(job.id, job.attempt, detail);
+        }
+        this.#recordEvent(job, nextState, detail);
+    }
+    #recordEvent(job, state, detail) {
+        saveOrchestrationEvent({
+            id: randomUUID(),
+            jobId: job.id,
+            sessionId: job.sessionId,
+            state,
+            detail,
+        });
+    }
+    #snapshot(job) {
+        return {
+            id: job.id,
+            sessionId: job.sessionId,
+            parentMessage: job.parentMessage,
+            brief: job.brief,
+            state: job.state,
+            attempt: job.attempt,
+            createdAt: job.createdAt,
+            updatedAt: job.updatedAt,
+            startedAt: job.startedAt,
+            completedAt: job.completedAt,
+            output: job.output,
+            error: job.error,
+        };
+    }
+    #buildSummary(jobs) {
+        const completed = jobs.filter((job) => job.state === 'completed').length;
+        const failed = jobs.filter((job) => job.state === 'failed').length;
+        const cancelled = jobs.filter((job) => job.state === 'cancelled').length;
+        const lines = jobs.map((job) => {
+            const suffix = job.state === 'completed'
+                ? (job.output ?? '').slice(0, 280)
+                : (job.error ?? 'No error detail captured.');
+            return `- ${job.brief.title} [${job.state}] ${suffix}`;
+        });
+        return [
+            `Delegation summary: ${completed} completed, ${failed} failed, ${cancelled} cancelled.`,
+            ...lines,
+        ].join('\n');
+    }
+    #isTerminal(state) {
+        return state === 'completed' || state === 'failed' || state === 'cancelled';
+    }
+}

package/dist/services/persona-state.js

@@ -0,0 +1,256 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { access, copyFile, mkdir, readFile, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+import { logThought } from '../utils/logger.js';
+import { PERSONA_DOCUMENT_KEYS, PersonaConflictError, PersonaValidationError, } from '../types/persona-state.js';
+const MAX_PERSONA_FIELD_LENGTH = 120_000;
+const DEFAULT_FS_ADAPTER = {
+    access,
+    copyFile,
+    mkdir: async (targetPath, options) => {
+        await mkdir(targetPath, options);
+    },
+    readFile,
+    rename,
+    rm: async (targetPath, options) => {
+        await rm(targetPath, { force: options?.force ?? false });
+    },
+    stat,
+    writeFile,
+};
+export class PersonaStateService {
+    #identityDir;
+    #now;
+    #fs;
+    #auditLogger;
+    constructor(options = {}) {
+        this.#identityDir = options.identityDir ?? path.resolve('identity');
+        this.#now = options.now ?? (() => new Date());
+        this.#fs = options.fsAdapter ?? DEFAULT_FS_ADAPTER;
+        this.#auditLogger = options.auditLogger ?? logThought;
+    }
+    async getState() {
+        await this.#fs.mkdir(this.#identityDir, { recursive: true });
+        const soul = await this.#readDocument('soul');
+        const identity = await this.#readDocument('identity');
+        const user = await this.#readDocument('user');
+        const revision = this.#computeRevision({
+            soul: soul.content,
+            identity: identity.content,
+            user: user.content,
+        });
+        const latestUpdatedAtMs = Math.max(soul.updatedAtMs, identity.updatedAtMs, user.updatedAtMs);
+        return {
+            revision,
+            updatedAt: latestUpdatedAtMs > 0
+                ? new Date(latestUpdatedAtMs).toISOString()
+                : this.#now().toISOString(),
+            soul: soul.content,
+            identity: identity.content,
+            user: user.content,
+        };
+    }
+    async updateState(input) {
+        const normalizedInput = this.#validateUpdateInput(input);
+        const currentState = await this.getState();
+        if (normalizedInput.expectedRevision !== currentState.revision) {
+            throw new PersonaConflictError(currentState.revision);
+        }
+        const nextState = {
+            soul: normalizedInput.soul,
+            identity: normalizedInput.identity,
+            user: normalizedInput.user,
+        };
+        const changedDocuments = PERSONA_DOCUMENT_KEYS.filter((key) => {
+            return currentState[key] !== nextState[key];
+        });
+        if (changedDocuments.length === 0) {
+            return {
+                state: currentState,
+                diagnostics: {
+                    outcome: 'noop',
+                    changedDocuments: [],
+                    warnings: [],
+                },
+            };
+        }
+        const plans = [];
+        const warnings = [];
+        for (const key of changedDocuments) {
+            const targetPath = this.#documentPath(key);
+            const tempPath = `${targetPath}.tmp-${randomUUID()}`;
+            const backupPath = `${targetPath}.bak-${randomUUID()}`;
+            await this.#fs.writeFile(tempPath, nextState[key], 'utf8');
+            const hadOriginal = await this.#fileExists(targetPath);
+            if (hadOriginal) {
+                await this.#fs.copyFile(targetPath, backupPath);
+            }
+            plans.push({
+                key,
+                targetPath,
+                tempPath,
+                backupPath,
+                hadOriginal,
+                applied: false,
+                originalRemoved: false,
+            });
+        }
+        try {
+            for (const plan of plans) {
+                await this.#removePathIfExists(plan.targetPath);
+                plan.originalRemoved = true;
+                await this.#fs.rename(plan.tempPath, plan.targetPath);
+                plan.applied = true;
+            }
+            for (const plan of plans) {
+                warnings.push(...(await this.#cleanupPath(plan.backupPath)));
+            }
+            const updatedState = await this.getState();
+            await this.#auditLogger(`[PersonaState] Updated documents: ${changedDocuments.join(', ')} | revision=${updatedState.revision}`);
+            return {
+                state: updatedState,
+                diagnostics: {
+                    outcome: 'updated',
+                    changedDocuments,
+                    warnings,
+                },
+            };
+        }
+        catch (error) {
+            const rollbackWarnings = await this.#rollbackPlans(plans);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const warningSuffix = rollbackWarnings.length > 0 ? ` | Rollback warnings: ${rollbackWarnings.join(' | ')}` : '';
+            await this.#auditLogger(`[PersonaState] Update failed; rollback applied. ${errorMessage}${warningSuffix}`);
+            throw new Error(`Persona state update failed; rollback applied. ${errorMessage}${warningSuffix}`);
+        }
+        finally {
+            for (const plan of plans) {
+                warnings.push(...(await this.#cleanupPath(plan.tempPath)));
+                warnings.push(...(await this.#cleanupPath(plan.backupPath)));
+            }
+        }
+    }
+    #validateUpdateInput(input) {
+        const hints = [];
+        const isValidRevision = typeof input.expectedRevision === 'string' && input.expectedRevision.trim().length > 0;
+        if (!isValidRevision) {
+            hints.push("'expectedRevision' must be a non-empty string.");
+        }
+        const soul = this.#validateField('soul', input.soul, hints);
+        const identity = this.#validateField('identity', input.identity, hints);
+        const user = this.#validateField('user', input.user, hints);
+        if (hints.length > 0) {
+            throw new PersonaValidationError(hints);
+        }
+        // isValidRevision is true here (would have thrown otherwise)
+        return {
+            expectedRevision: input.expectedRevision,
+            soul,
+            identity,
+            user,
+        };
+    }
+    #validateField(name, value, hints) {
+        if (typeof value !== 'string') {
+            hints.push(`'${name}' must be a string.`);
+            return '';
+        }
+        if (value.length > MAX_PERSONA_FIELD_LENGTH) {
+            hints.push(`'${name}' exceeds ${MAX_PERSONA_FIELD_LENGTH} characters.`);
+        }
+        return value;
+    }
+    async #rollbackPlans(plans) {
+        const warnings = [];
+        const reversePlans = [...plans].reverse();
+        for (const plan of reversePlans) {
+            if (plan.applied || plan.originalRemoved) {
+                if (plan.hadOriginal) {
+                    warnings.push(...(await this.#removePathIfExists(plan.targetPath)));
+                    try {
+                        await this.#fs.rename(plan.backupPath, plan.targetPath);
+                    }
+                    catch (error) {
+                        warnings.push(`Failed to restore backup for '${plan.key}': ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+                else {
+                    warnings.push(...(await this.#removePathIfExists(plan.targetPath)));
+                }
+            }
+            warnings.push(...(await this.#cleanupPath(plan.tempPath)));
+            warnings.push(...(await this.#cleanupPath(plan.backupPath)));
+        }
+        return warnings;
+    }
+    async #readDocument(key) {
+        const filePath = this.#documentPath(key);
+        try {
+            const [content, metadata] = await Promise.all([
+                this.#fs.readFile(filePath, 'utf8'),
+                this.#fs.stat(filePath),
+            ]);
+            return {
+                content,
+                updatedAtMs: Number.isFinite(metadata.mtimeMs) ? metadata.mtimeMs : 0,
+            };
+        }
+        catch (error) {
+            if (this.#isNotFound(error)) {
+                return { content: '', updatedAtMs: 0 };
+            }
+            throw error;
+        }
+    }
+    #computeRevision(value) {
+        return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+    }
+    #documentPath(key) {
+        return path.join(this.#identityDir, `${key}.md`);
+    }
+    async #fileExists(targetPath) {
+        try {
+            await this.#fs.access(targetPath);
+            return true;
+        }
+        catch (error) {
+            if (this.#isNotFound(error)) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async #removePathIfExists(targetPath) {
+        try {
+            await this.#fs.rm(targetPath, { force: true });
+            return [];
+        }
+        catch (error) {
+            if (this.#isNotFound(error)) {
+                return [];
+            }
+            return [
+                `Failed to remove '${targetPath}': ${error instanceof Error ? error.message : String(error)}`,
+            ];
+        }
+    }
+    async #cleanupPath(targetPath) {
+        return this.#removePathIfExists(targetPath);
+    }
+    #isNotFound(error) {
+        return (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT');
+    }
+}
+let defaultPersonaStateService = null;
+export function getPersonaStateService() {
+    if (!defaultPersonaStateService) {
+        defaultPersonaStateService = new PersonaStateService();
+    }
+    return defaultPersonaStateService;
+}
+export function resetPersonaStateServiceForTests() {
+    defaultPersonaStateService = null;
+}