@openfairygui/backend 0.2.0-alpha.0

package/src/services/authoring-service.ts

@@ -0,0 +1,186 @@
+import { materializeUamProject, ProjectWriter } from '@openfairygui/core';
+import { applyUamTransactionApp, type ApplyUamTransactionAppError } from '@openfairygui/functions';
+import type { CacheService } from './cache-service.js';
+import { failure, success, type BackendContext } from './context.js';
+import type { EventService } from './event-service.js';
+import type {
+	ApplySessionTransactionInput,
+	BackendFileSystem,
+	BackendResult,
+	BackendSessionSnapshot,
+	SavePartialFailureError,
+	SessionNotFoundError,
+	SessionStaleWriteError,
+} from '../runtime.js';
+import { validateSaveTarget, type PathPolicyViolationError } from '../path-policy.js';
+import { createSessionNotFoundError, createStaleWriteError, toSessionSnapshot } from './session-utils.js';
+
+function createWriterFileSystem(
+	fileSystem: BackendFileSystem,
+	committedPaths: string[],
+	failedPaths: string[],
+): import('@openfairygui/core').FileSystem {
+	async function trackWrite<T>(targetPath: string, fn: () => Promise<T>): Promise<T> {
+		try {
+			const result = await fn();
+			committedPaths.push(targetPath);
+			return result;
+		} catch (error) {
+			failedPaths.push(targetPath);
+			throw error;
+		}
+	}
+
+	return {
+		async readFile(filePath: string): Promise<string> {
+			return fileSystem.readFile(filePath);
+		},
+		async readFileRaw(filePath: string): Promise<Uint8Array> {
+			return fileSystem.readFileRaw(filePath);
+		},
+		async writeFile(filePath: string, content: string): Promise<void> {
+			await trackWrite(filePath, async () => {
+				await fileSystem.mkdir(fileSystem.dirname(filePath), { recursive: true });
+				await fileSystem.writeFile(filePath, content);
+			});
+		},
+		async writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
+			await trackWrite(filePath, async () => {
+				await fileSystem.mkdir(fileSystem.dirname(filePath), { recursive: true });
+				await fileSystem.writeFileRaw(filePath, data);
+			});
+		},
+		async mkdir(dirPath: string): Promise<void> {
+			await fileSystem.mkdir(dirPath, { recursive: true });
+		},
+		async readdir(dirPath: string): Promise<string[]> {
+			return fileSystem.readdir(dirPath);
+		},
+		async exists(filePath: string): Promise<boolean> {
+			try {
+				await fileSystem.stat(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		join(...paths: string[]): string {
+			return fileSystem.join(...paths);
+		},
+		dirname(filePath: string): string {
+			return fileSystem.dirname(filePath);
+		},
+	};
+}
+
+export class AuthoringService {
+	public constructor(
+		private readonly context: BackendContext,
+		private readonly cacheService: CacheService,
+		private readonly eventService: EventService,
+	) {}
+
+	public async applyTransaction(
+		input: ApplySessionTransactionInput,
+	): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>> {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) {
+			return failure('authoring', startedAt, createSessionNotFoundError(input.sessionId));
+		}
+		if (input.expectedRevision !== session.revision) {
+			this.eventService.emit({ kind: 'transaction.rejected', sessionId: session.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision });
+			return failure('authoring', startedAt, createStaleWriteError(session, input.expectedRevision), toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+			});
+		}
+
+		const result = applyUamTransactionApp({
+			project: session.project,
+			operations: input.operations,
+		});
+		if (result.ok === false) {
+			this.eventService.emit({ kind: 'transaction.rejected', sessionId: session.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, diagnostics: result.error.issues?.map((issue) => ({ code: result.error.code, message: issue.message, severity: 'error' as const })) ?? [] });
+			return failure('authoring', startedAt, result.error, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+			});
+		}
+
+		session.project = result.project;
+		session.revision += 1;
+		session.dirty = true;
+		const cacheEntry = this.cacheService.invalidateSession(session);
+		this.eventService.emit({ kind: 'transaction.applied', sessionId: session.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision });
+		this.eventService.emit({ kind: 'cache.invalidated', sessionId: session.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, cacheRevision: cacheEntry.revision });
+
+		return success('authoring', startedAt, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision,
+		});
+	}
+
+	public async saveSession(
+		input: { sessionId: string; expectedRevision?: number; targetPath?: string },
+	): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError>> {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) {
+			return failure('authoring', startedAt, createSessionNotFoundError(input.sessionId));
+		}
+		if (input.expectedRevision !== undefined && input.expectedRevision !== session.revision) {
+			return failure('authoring', startedAt, createStaleWriteError(session, input.expectedRevision), toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+			});
+		}
+		const targetViolation = await validateSaveTarget(this.context.fileSystem, session.fairyPath, input.targetPath);
+		if (targetViolation) {
+			return failure('authoring', startedAt, targetViolation, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+			});
+		}
+		if (!session.dirty) {
+			return success('authoring', startedAt, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+			});
+		}
+
+		const committedPaths: string[] = [];
+		const failedPaths: string[] = [];
+		this.eventService.emit({ kind: 'save.started', sessionId: session.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision });
+		try {
+			const writer = new ProjectWriter(createWriterFileSystem(this.context.fileSystem, committedPaths, failedPaths));
+			await writer.write(materializeUamProject(session.project), session.fairyPath);
+			session.lastSavedRevision = session.revision;
+			session.dirty = false;
+			const cacheEntry = this.cacheService.refreshSession(session);
+			this.eventService.emit({ kind: 'save.completed', sessionId: session.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision });
+			this.eventService.emit({ kind: 'cache.updated', sessionId: session.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, cacheRevision: cacheEntry.revision });
+			return success('authoring', startedAt, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+			});
+		} catch (error) {
+			this.cacheService.invalidateSession(session);
+			this.eventService.emit({ kind: 'save.failed', sessionId: session.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision });
+			return failure('authoring', startedAt, {
+				code: 'save_partial_failure',
+				message: error instanceof Error ? error.message : String(error),
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				attemptedRevision: session.revision,
+				lastSavedRevision: session.lastSavedRevision,
+				committedPaths,
+				failedPaths,
+				diskMayBePartiallyUpdated: true,
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+			});
+		}
+	}
+}

package/src/services/cache-service.ts

@@ -0,0 +1,60 @@
+import { failure, success, type BackendContext, type BackendSessionState } from './context.js';
+import { createSessionNotFoundError } from './session-utils.js';
+import type {
+	BackendCacheEntry,
+	BackendCacheSnapshot,
+	BackendResult,
+	GetCacheSnapshotInput,
+	SessionNotFoundError,
+} from '../runtime.js';
+import { cloneCacheEntrySnapshot } from './snapshot-utils.js';
+
+function createCacheEntry(session: BackendSessionState, valid: boolean): BackendCacheEntry {
+	return {
+		canonicalPathKey: session.canonicalPathKey,
+		sessionId: session.sessionId,
+		revision: session.revision,
+		lastSavedRevision: session.lastSavedRevision,
+		dirty: session.dirty,
+		valid,
+		indexedAt: new Date().toISOString(),
+		summary: {
+			packageCount: session.project.packages.length,
+			resourceCount: session.project.packages.reduce((total, pkg) => total + pkg.resources.length, 0),
+			diagnostics: [],
+		},
+	};
+}
+
+export class CacheService {
+	public constructor(private readonly context: BackendContext) {}
+
+	public getCacheSnapshot(input: GetCacheSnapshotInput): BackendResult<BackendCacheSnapshot, SessionNotFoundError> {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) {
+			return failure('read', startedAt, createSessionNotFoundError(input.sessionId));
+		}
+		const entry = this.context.cacheBySession.get(input.sessionId);
+		return success('read', startedAt, {
+			cacheRevision: entry?.revision ?? session.revision,
+			entries: entry ? [cloneCacheEntrySnapshot(entry)] : [],
+		}, { sessionId: session.sessionId, revision: session.revision });
+	}
+
+	public refreshSession(session: BackendSessionState): BackendCacheEntry {
+		const entry = createCacheEntry(session, true);
+		this.context.cacheBySession.set(session.sessionId, entry);
+		return entry;
+	}
+
+	public invalidateSession(session: BackendSessionState): BackendCacheEntry {
+		const entry = createCacheEntry(session, false);
+		this.context.cacheBySession.set(session.sessionId, entry);
+		return entry;
+	}
+
+	public removeSession(sessionId: string): void {
+		this.context.cacheBySession.delete(sessionId);
+	}
+}

package/src/services/context.ts

@@ -0,0 +1,112 @@
+import type {
+	BackendCacheEntry,
+	BackendCapabilities,
+	BackendError,
+	BackendEvent,
+	BackendFailure,
+	BackendFileSystem,
+	BackendJobSnapshot,
+	BackendSessionSnapshot,
+	BackendSuccess,
+} from '../runtime.js';
+import {
+	BACKEND_CAPABILITY_SCHEMA_VERSION,
+	BACKEND_CONTRACT_VERSION,
+	type BackendDiagnostic,
+	type BackendMessage,
+	type BackendResponseMeta,
+	type BackendStage,
+} from '../contracts.js';
+
+export interface BackendSessionState {
+	sessionId: string;
+	fairyPath: string;
+	canonicalProjectPath: string;
+	canonicalPathKey: string;
+	lockFilePath: string;
+	project: import('@openfairygui/core').UamProject;
+	revision: number;
+	lastSavedRevision: number;
+	dirty: boolean;
+	lockHeld: boolean;
+	closed: boolean;
+}
+
+export interface BackendContext {
+	fileSystem: BackendFileSystem;
+	capabilities: BackendCapabilities;
+	sessions: Map<string, BackendSessionState>;
+	sessionsByPath: Map<string, string>;
+	eventsBySession: Map<string, BackendEvent[]>;
+	jobsBySession: Map<string, BackendJobSnapshot[]>;
+	cacheBySession: Map<string, BackendCacheEntry>;
+	nextEventSequence: () => number;
+}
+
+function randomId(): string {
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function createMeta(
+	stage: BackendStage,
+	startedAt: number,
+	options?: {
+		requestId?: string;
+		sessionId?: string;
+		revision?: number;
+		warnings?: BackendMessage[];
+		diagnostics?: BackendDiagnostic[];
+	},
+): BackendResponseMeta {
+	return {
+		requestId: options?.requestId ?? randomId(),
+		sessionId: options?.sessionId,
+		revision: options?.revision,
+		durationMs: Math.max(0, Date.now() - startedAt),
+		warnings: options?.warnings ?? [],
+		diagnostics: options?.diagnostics ?? [],
+		stage,
+		contractVersion: BACKEND_CONTRACT_VERSION,
+		capabilitySchemaVersion: BACKEND_CAPABILITY_SCHEMA_VERSION,
+	};
+}
+
+export function success<T>(
+	stage: BackendStage,
+	startedAt: number,
+	data: T,
+	options?: {
+		requestId?: string;
+		sessionId?: string;
+		revision?: number;
+		warnings?: BackendMessage[];
+		diagnostics?: BackendDiagnostic[];
+	},
+): BackendSuccess<T> {
+	return {
+		ok: true,
+		meta: createMeta(stage, startedAt, options),
+		data,
+	};
+}
+
+export function failure<E extends BackendError>(
+	stage: BackendStage,
+	startedAt: number,
+	error: E,
+	session?: BackendSessionSnapshot,
+	options?: {
+		requestId?: string;
+		sessionId?: string;
+		revision?: number;
+		warnings?: BackendMessage[];
+		diagnostics?: BackendDiagnostic[];
+	},
+): BackendFailure<E> {
+	return {
+		ok: false,
+		meta: createMeta(stage, startedAt, options),
+		error,
+		session,
+	};
+}

package/src/services/event-service.ts

@@ -0,0 +1,84 @@
+import { failure, success, type BackendContext } from './context.js';
+import { createSessionNotFoundError } from './session-utils.js';
+import type {
+	BackendEvent,
+	BackendResult,
+	EventCursorInvalidError,
+	GetEventsInput,
+	GetEventsSnapshot,
+	SessionNotFoundError,
+} from '../runtime.js';
+import { cloneEventSnapshot } from './snapshot-utils.js';
+
+const DEFAULT_EVENT_RETENTION_LIMIT = 1000;
+
+export class EventService {
+	public constructor(private readonly context: BackendContext) {}
+
+	public emit(event: Omit<BackendEvent, 'sequence' | 'timestamp' | 'diagnostics'> & {
+		diagnostics?: BackendEvent['diagnostics'];
+	}): BackendEvent {
+		const emitted: BackendEvent = {
+			...event,
+			sequence: this.context.nextEventSequence(),
+			timestamp: new Date().toISOString(),
+			diagnostics: event.diagnostics ?? [],
+		};
+		const sessionId = event.sessionId;
+		if (!sessionId) return emitted;
+		const events = this.context.eventsBySession.get(sessionId) ?? [];
+		events.push(emitted);
+		while (events.length > DEFAULT_EVENT_RETENTION_LIMIT) events.shift();
+		this.context.eventsBySession.set(sessionId, events);
+		return emitted;
+	}
+
+	public getEvents(input: GetEventsInput): BackendResult<GetEventsSnapshot, SessionNotFoundError | EventCursorInvalidError> {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) {
+			return failure('runtime', startedAt, createSessionNotFoundError(input.sessionId));
+		}
+		const events = this.context.eventsBySession.get(input.sessionId) ?? [];
+		const oldestSequence = events[0]?.sequence ?? (events.length === 0 ? 1 : 0);
+		const currentSequence = events.at(-1)?.sequence ?? 0;
+		const after = input.after === undefined ? 0 : Number(input.after);
+		if (!Number.isInteger(after) || after < 0) {
+			return failure('runtime', startedAt, {
+				code: 'event_cursor_invalid',
+				message: `Invalid event cursor: ${input.after}`,
+				sessionId: input.sessionId,
+				after: String(input.after),
+			});
+		}
+		if (events.length > 0 && after < oldestSequence - 1) {
+			return failure('runtime', startedAt, {
+				code: 'event_cursor_invalid',
+				message: `Event cursor has expired: ${after}`,
+				sessionId: input.sessionId,
+				after: String(input.after),
+			});
+		}
+		if (after > currentSequence) {
+			return failure('runtime', startedAt, {
+				code: 'event_cursor_invalid',
+				message: `Unknown event cursor: ${after}`,
+				sessionId: input.sessionId,
+				after: String(input.after),
+			});
+		}
+
+		const filtered = events.filter((event) => event.sequence > after);
+		const limit = input.limit === undefined ? filtered.length : Math.max(0, input.limit);
+		return success('runtime', startedAt, {
+			events: filtered.slice(0, limit).map(cloneEventSnapshot),
+			oldestSequence,
+			currentSequence,
+			cursorExpired: false,
+		}, { sessionId: session.sessionId, revision: session.revision });
+	}
+
+	public removeSession(sessionId: string): void {
+		this.context.eventsBySession.delete(sessionId);
+	}
+}

package/src/services/job-service.ts

@@ -0,0 +1,239 @@
+import { failure, success, type BackendContext } from './context.js';
+import type { CacheService } from './cache-service.js';
+import type { EventService } from './event-service.js';
+import { createSessionNotFoundError } from './session-utils.js';
+import { cloneJobSnapshot } from './snapshot-utils.js';
+import type {
+	BackendJobListSnapshot,
+	BackendJobNotCancellableError,
+	BackendJobNotFoundError,
+	BackendJobSnapshot,
+	BackendJobStatus,
+	BackendResult,
+	CancelJobInput,
+	GetJobInput,
+	ListJobsInput,
+	RefreshCacheInput,
+	SessionNotFoundError,
+} from '../runtime.js';
+
+const COMPLETED_JOB_RETENTION_LIMIT = 100;
+const REFRESH_START_DELAY_MS = 0;
+const REFRESH_COMPLETE_DELAY_MS = 50;
+
+function isTerminal(status: BackendJobStatus): boolean {
+	return status === 'completed' || status === 'failed' || status === 'cancelled';
+}
+
+export class JobService {
+	public constructor(
+		private readonly context: BackendContext,
+		private readonly cacheService: CacheService,
+		private readonly eventService: EventService,
+	) {}
+	private readonly cancellationRequests = new Set<string>();
+
+	private getJobs(sessionId: string): BackendJobSnapshot[] {
+		return this.context.jobsBySession.get(sessionId) ?? [];
+	}
+
+	private setJobs(sessionId: string, jobs: BackendJobSnapshot[]): void {
+		const retained: BackendJobSnapshot[] = [];
+		let terminalCount = 0;
+		for (let index = jobs.length - 1; index >= 0; index -= 1) {
+			const job = jobs[index];
+			if (isTerminal(job.status)) {
+				if (terminalCount >= COMPLETED_JOB_RETENTION_LIMIT) continue;
+				terminalCount += 1;
+			}
+			retained.push(job);
+		}
+		this.context.jobsBySession.set(sessionId, retained.reverse());
+	}
+
+	public refreshCache(input: RefreshCacheInput): BackendResult<BackendJobSnapshot, SessionNotFoundError> {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) {
+			return failure('runtime', startedAt, createSessionNotFoundError(input.sessionId));
+		}
+		const jobId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+		const createdAt = new Date().toISOString();
+		const job: BackendJobSnapshot = {
+			jobId,
+			kind: 'cache.refresh',
+			status: 'queued',
+			createdAt,
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision,
+			diagnostics: [],
+			progress: { completed: 0, total: 1, message: input.reason ?? 'manual' },
+		};
+		const jobs = this.getJobs(session.sessionId);
+		jobs.push(job);
+		this.setJobs(session.sessionId, jobs);
+		this.eventService.emit({ kind: 'job.created', sessionId: session.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, jobId });
+		this.scheduleRefreshJob(session.sessionId, jobId);
+
+		return success('runtime', startedAt, cloneJobSnapshot(job), { sessionId: session.sessionId, revision: session.revision });
+	}
+
+	public getJob(input: GetJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError> {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure('runtime', startedAt, createSessionNotFoundError(input.sessionId));
+		const job = this.getJobs(input.sessionId).find((item) => item.jobId === input.jobId);
+		if (!job) {
+			return failure('runtime', startedAt, {
+				code: 'job_not_found',
+				message: `Job was not found: ${input.jobId}`,
+				sessionId: input.sessionId,
+				jobId: input.jobId,
+			}, undefined, { sessionId: session.sessionId, revision: session.revision });
+		}
+		return success('runtime', startedAt, cloneJobSnapshot(job), { sessionId: session.sessionId, revision: session.revision });
+	}
+
+	public listJobs(input: ListJobsInput): BackendResult<BackendJobListSnapshot, SessionNotFoundError> {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure('runtime', startedAt, createSessionNotFoundError(input.sessionId));
+		let jobs = [...this.getJobs(input.sessionId)];
+		if (input.kind) jobs = jobs.filter((job) => job.kind === input.kind);
+		if (input.status) {
+			if (input.status === 'active') jobs = jobs.filter((job) => !isTerminal(job.status));
+			else if (input.status === 'terminal') jobs = jobs.filter((job) => isTerminal(job.status));
+			else jobs = jobs.filter((job) => job.status === input.status);
+		}
+		if (input.limit !== undefined) jobs = jobs.slice(0, Math.max(0, input.limit));
+		return success('runtime', startedAt, { jobs: jobs.map(cloneJobSnapshot) }, { sessionId: session.sessionId, revision: session.revision });
+	}
+
+	public cancelJob(input: CancelJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError | BackendJobNotCancellableError> {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure('runtime', startedAt, createSessionNotFoundError(input.sessionId));
+		const job = this.getJobs(input.sessionId).find((item) => item.jobId === input.jobId);
+		if (!job) {
+			return failure('runtime', startedAt, {
+				code: 'job_not_found',
+				message: `Job was not found: ${input.jobId}`,
+				sessionId: input.sessionId,
+				jobId: input.jobId,
+			}, undefined, { sessionId: session.sessionId, revision: session.revision });
+		}
+		if (isTerminal(job.status)) {
+			return failure('runtime', startedAt, {
+				code: 'job_not_cancellable',
+				message: `Job is already terminal: ${input.jobId}`,
+				sessionId: input.sessionId,
+				jobId: input.jobId,
+				status: job.status as 'completed' | 'failed' | 'cancelled',
+			}, undefined, { sessionId: session.sessionId, revision: session.revision });
+		}
+		this.cancellationRequests.add(job.jobId);
+		this.eventService.emit({ kind: 'job.cancelRequested', sessionId: input.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, jobId: job.jobId });
+		const cancelled = this.cancelRefreshJob(session.sessionId, job);
+		return success('runtime', startedAt, cloneJobSnapshot(cancelled), { sessionId: session.sessionId, revision: session.revision });
+	}
+
+	public removeSession(sessionId: string): void {
+		for (const job of this.getJobs(sessionId)) this.cancellationRequests.delete(job.jobId);
+		this.context.jobsBySession.delete(sessionId);
+	}
+
+	private replaceJob(sessionId: string, nextJob: BackendJobSnapshot): void {
+		const jobs = this.getJobs(sessionId).map((job) => job.jobId === nextJob.jobId ? nextJob : job);
+		this.setJobs(sessionId, jobs);
+	}
+
+	private scheduleRefreshJob(sessionId: string, jobId: string): void {
+		setTimeout(() => this.startRefreshJob(sessionId, jobId), REFRESH_START_DELAY_MS);
+	}
+
+	private startRefreshJob(sessionId: string, jobId: string): void {
+		const session = this.context.sessions.get(sessionId);
+		if (!session || session.closed) return;
+		const job = this.getJobs(sessionId).find((item) => item.jobId === jobId);
+		if (!job || isTerminal(job.status)) return;
+		if (this.cancellationRequests.has(jobId)) {
+			this.cancelRefreshJob(sessionId, job);
+			return;
+		}
+		const running: BackendJobSnapshot = {
+			...job,
+			status: 'running',
+			startedAt: new Date().toISOString(),
+			progress: { completed: 0, total: 1, message: 'refreshing cache' },
+		};
+		this.replaceJob(sessionId, running);
+		this.eventService.emit({ kind: 'job.started', sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, jobId });
+		this.eventService.emit({ kind: 'job.progress', sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, jobId, payload: running.progress });
+		setTimeout(() => this.completeRefreshJob(sessionId, jobId), REFRESH_COMPLETE_DELAY_MS);
+	}
+
+	private completeRefreshJob(sessionId: string, jobId: string): void {
+		const session = this.context.sessions.get(sessionId);
+		if (!session || session.closed) return;
+		const job = this.getJobs(sessionId).find((item) => item.jobId === jobId);
+		if (!job || isTerminal(job.status)) return;
+		if (this.cancellationRequests.has(jobId)) {
+			this.cancelRefreshJob(sessionId, job);
+			return;
+		}
+		try {
+			const entry = this.cacheService.refreshSession(session);
+			const completed: BackendJobSnapshot = {
+				...job,
+				status: 'completed',
+				finishedAt: new Date().toISOString(),
+				cacheRevision: entry.revision,
+				progress: { completed: 1, total: 1, message: 'cache refreshed' },
+				result: { cacheRevision: entry.revision },
+			};
+			this.replaceJob(sessionId, completed);
+			this.eventService.emit({ kind: 'job.completed', sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, cacheRevision: entry.revision, jobId });
+			this.eventService.emit({ kind: 'cache.updated', sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, cacheRevision: entry.revision });
+		} catch (error) {
+			const failed: BackendJobSnapshot = {
+				...job,
+				status: 'failed',
+				finishedAt: new Date().toISOString(),
+				error: {
+					code: 'cache_refresh_failed',
+					message: error instanceof Error ? error.message : 'Cache refresh failed',
+					sessionId,
+					jobId,
+				},
+			};
+			this.replaceJob(sessionId, failed);
+			this.eventService.emit({ kind: 'job.failed', sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, jobId, diagnostics: failed.diagnostics });
+		}
+	}
+
+	private cancelRefreshJob(sessionId: string, job: BackendJobSnapshot): BackendJobSnapshot {
+		const session = this.context.sessions.get(sessionId);
+		const cancelled: BackendJobSnapshot = {
+			...job,
+			status: 'cancelled',
+			finishedAt: new Date().toISOString(),
+			error: {
+				code: 'job_cancelled',
+				message: `Job was cancelled: ${job.jobId}`,
+				sessionId,
+				jobId: job.jobId,
+			},
+		};
+		this.replaceJob(sessionId, cancelled);
+		this.cancellationRequests.delete(job.jobId);
+		this.eventService.emit({
+			kind: 'job.cancelled',
+			sessionId,
+			canonicalPathKey: session?.canonicalPathKey ?? job.canonicalPathKey,
+			revision: session?.revision ?? job.revision,
+			jobId: job.jobId,
+		});
+		return cancelled;
+	}
+}