@xopcai/xopc 0.0.313 → 0.0.314

package/dist/src/notes/store.js

@@ -1,3 +1,4 @@
+import { init_paths_state, resolveStateDir } from "../config/paths-state.js";
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { requireXopcDatabase } from "../storage/sqlite/connection.js";
@@ -6,53 +7,56 @@ import { buildNoteIndexMeta } from "./note-index-meta.js";
 import { deleteNoteRecord, getNoteRecord, listNoteRecords, upsertNoteRecord } from "../storage/sqlite/notes-repository.js";
 import { deleteNoteAgentContextRecord } from "../storage/sqlite/note-agent-context-repository.js";
 import "../storage/sqlite/index.js";
+import { canRemoveRevokedNoteShareArtifact } from "../share/note-share-revocation.js";
 import { resolveNoteMediaDir } from "./paths.js";
-import { join } from "node:path";
+import { basename, join } from "node:path";
+import { rmSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { copyFile, mkdir, rm, stat, writeFile } from "node:fs/promises";
 //#region src/notes/store.ts
 init_transaction();
 init_logger();
+init_paths_state();
 const log = createLogger("NotesStore");
 var NotesStore = class {
 	initialized = false;
+	failedCleanupPaths = /* @__PURE__ */ new Set();
 	async initialize() {
 		if (this.initialized) return;
 		requireXopcDatabase();
 		this.initialized = true;
 		log.debug("NotesStore initialized");
 	}
-	async addNote(note) {
+	addNote(note) {
 		requireXopcDatabase();
 		upsertNoteRecord(note);
 	}
-	async getNote(id) {
+	getNote(id) {
 		requireXopcDatabase();
 		return getNoteRecord(id);
 	}
-	async updateNote(id, patch) {
-		const existing = await this.getNote(id);
+	updateNote(id, patch) {
+		const existing = this.getNote(id);
 		if (!existing) return null;
 		const updated = {
 			...existing,
 			...patch,
 			id: existing.id,
 			createdAt: existing.createdAt,
-			updatedAt: Date.now()
+			updatedAt: Math.max(Date.now(), existing.updatedAt + 1)
 		};
 		requireXopcDatabase();
 		upsertNoteRecord(updated);
 		return updated;
 	}
-	async deleteNote(id) {
-		requireXopcDatabase();
-		if (!deleteNoteRecord(id)) return false;
-		deleteNoteAgentContextRecord(id);
-		await rm(resolveNoteMediaDir(id), {
-			recursive: true,
-			force: true
-		}).catch(() => void 0);
-		return true;
+	deleteNoteAtomically(id) {
+		return runSqliteWriteTransaction((db) => {
+			if (!deleteNoteRecord(id)) return false;
+			deleteNoteAgentContextRecord(id);
+			db.prepare("DELETE FROM note_snapshots WHERE note_id = ?").run(id);
+			this.queueDeletionCleanup("media", id);
+			return true;
+		});
 	}
 	async listNotes(query = {}) {
 		requireXopcDatabase();
@@ -82,7 +86,7 @@ var NotesStore = class {
 			}, "Failed to remove note attachment file");
 		});
 	}
-	async saveSnapshot(note, trigger) {
+	saveSnapshot(note, trigger) {
 		requireXopcDatabase();
 		runSqliteWriteTransaction((db) => {
 			const row = db.prepare("SELECT MAX(timestamp) AS timestamp FROM note_snapshots WHERE note_id = ?").get(note.id);
@@ -99,7 +103,7 @@ var NotesStore = class {
 			db.prepare("INSERT INTO note_snapshots(note_id, timestamp, payload) VALUES (?, ?, ?)").run(note.id, snapshot.timestamp, JSON.stringify(snapshot));
 		});
 	}
-	async listSnapshots(noteId) {
+	listSnapshots(noteId) {
 		return requireXopcDatabase().db.prepare("SELECT payload FROM note_snapshots WHERE note_id = ? ORDER BY timestamp DESC").all(noteId).map((row) => {
 			const snapshot = JSON.parse(row.payload);
 			return {
@@ -109,18 +113,74 @@ var NotesStore = class {
 			};
 		});
 	}
-	async getSnapshot(noteId, timestamp) {
+	getSnapshot(noteId, timestamp) {
 		const row = requireXopcDatabase().db.prepare("SELECT payload FROM note_snapshots WHERE note_id = ? AND timestamp = ?").get(noteId, timestamp);
 		return row ? JSON.parse(row.payload) : null;
 	}
-	async pruneSnapshots(noteId, maxCount) {
+	pruneSnapshots(noteId, maxCount) {
 		if (!Number.isSafeInteger(maxCount) || maxCount < 0) throw new Error("Invalid snapshot retention count");
 		requireXopcDatabase().db.prepare(`DELETE FROM note_snapshots WHERE note_id = ? AND timestamp NOT IN (
       SELECT timestamp FROM note_snapshots WHERE note_id = ? ORDER BY timestamp DESC LIMIT ?
     )`).run(noteId, noteId, maxCount);
 	}
-	async deleteAllSnapshots(noteId) {
-		requireXopcDatabase().db.prepare("DELETE FROM note_snapshots WHERE note_id = ?").run(noteId);
+	queueAttachmentCleanup(noteId, relativePath) {
+		if (!/^[a-zA-Z0-9_-]+$/.test(noteId) || !relativePath || basename(relativePath) !== relativePath || relativePath === "." || relativePath === "..") throw new Error("Invalid note attachment cleanup path");
+		requireXopcDatabase().db.prepare(`INSERT OR IGNORE INTO note_file_cleanup
+      (note_id, relative_path, created_at) VALUES (?, ?, ?)`).run(noteId, relativePath, Date.now());
+	}
+	queueDeletionCleanup(kind, id) {
+		if (!/^[a-zA-Z0-9_-]+$/.test(id)) throw new Error("Invalid note deletion cleanup identity");
+		requireXopcDatabase().db.prepare("INSERT OR IGNORE INTO note_deletion_cleanup(kind, object_id, created_at) VALUES (?, ?, ?)").run(kind, id, Date.now());
+	}
+	drainDeletionCleanup(limit = 100) {
+		const db = requireXopcDatabase().db;
+		const rows = db.prepare("SELECT kind, object_id, attempts FROM note_deletion_cleanup WHERE next_attempt_at <= ? ORDER BY created_at LIMIT ?").all(Date.now(), limit);
+		for (const row of rows) {
+			const key = `${row.kind}:${row.object_id}`;
+			try {
+				if (!/^[a-zA-Z0-9_-]+$/.test(row.object_id) || !["media", "share"].includes(row.kind)) throw new Error("Invalid note deletion cleanup identity");
+				if (row.kind === "media" ? !this.getNote(row.object_id) : canRemoveRevokedNoteShareArtifact(row.object_id)) rmSync(row.kind === "media" ? resolveNoteMediaDir(row.object_id) : join(resolveStateDir(), "share-artifacts", row.object_id), {
+					recursive: true,
+					force: true
+				});
+				db.prepare("DELETE FROM note_deletion_cleanup WHERE kind = ? AND object_id = ?").run(row.kind, row.object_id);
+				this.failedCleanupPaths.delete(key);
+			} catch (err) {
+				db.prepare("UPDATE note_deletion_cleanup SET attempts = attempts + 1, next_attempt_at = ? WHERE kind = ? AND object_id = ?").run(Date.now() + Math.min(3e5, 1e3 * 2 ** Math.min(row.attempts, 9)), row.kind, row.object_id);
+				if (!this.failedCleanupPaths.has(key)) {
+					this.failedCleanupPaths.add(key);
+					log.warn({
+						err,
+						kind: row.kind,
+						objectId: row.object_id
+					}, "Deferred note deletion cleanup failed; retry scheduled");
+				}
+			}
+		}
+	}
+	/** Called after commit and on startup. A failed deletion remains durable for the next attempt. */
+	drainAttachmentCleanup(limit = 100) {
+		const db = requireXopcDatabase().db;
+		const rows = db.prepare("SELECT note_id, relative_path, attempts FROM note_file_cleanup WHERE next_attempt_at <= ? ORDER BY created_at LIMIT ?").all(Date.now(), limit);
+		for (const row of rows) {
+			const key = `${row.note_id}/${row.relative_path}`;
+			try {
+				if (!/^[a-zA-Z0-9_-]+$/.test(row.note_id) || !row.relative_path || basename(row.relative_path) !== row.relative_path || row.relative_path === "." || row.relative_path === "..") throw new Error("Invalid note attachment cleanup path");
+				if (!this.getNote(row.note_id)?.attachments?.some((item) => item.relativePath === row.relative_path)) rmSync(this.resolveAttachmentPath(row.note_id, row.relative_path), { force: true });
+				db.prepare("DELETE FROM note_file_cleanup WHERE note_id = ? AND relative_path = ?").run(row.note_id, row.relative_path);
+				this.failedCleanupPaths.delete(key);
+			} catch (err) {
+				db.prepare("UPDATE note_file_cleanup SET attempts = attempts + 1, next_attempt_at = ? WHERE note_id = ? AND relative_path = ?").run(Date.now() + Math.min(3e5, 1e3 * 2 ** Math.min(row.attempts, 9)), row.note_id, row.relative_path);
+				if (!this.failedCleanupPaths.has(key)) {
+					this.failedCleanupPaths.add(key);
+					log.warn({
+						err,
+						noteId: row.note_id,
+						relativePath: row.relative_path
+					}, "Deferred note attachment cleanup failed; retry scheduled");
+				}
+			}
+		}
 	}
 };
 //#endregion

package/dist/src/notifications/service.d.ts

@@ -10,6 +10,7 @@ export declare class NotificationService {
         publish: (type: string, payload: unknown) => void;
         fetch?: typeof fetch;
         domainDelivery?: NotificationDomainDelivery;
+        allowsNotification?: (notification: NotificationPlan['notification']) => boolean;
         sendHarmony?: typeof sendHarmonyPush;
     });
     start(): void;

package/dist/src/notifications/service.js

@@ -83,6 +83,7 @@ var NotificationService = class {
 		return this.persistPlan(plan);
 	}
 	persistPlan(plan) {
+		if (this.options.allowsNotification?.(plan.notification) === false) return null;
 		const domain = this.options.domainDelivery?.owns(plan.notification.type) ? this.options.domainDelivery : void 0;
 		if (!domain && !Object.hasOwn(STANDARD_PREFERENCES, plan.notification.type)) throw new Error("Notification domain delivery is not installed");
 		const devices = listDeliverableNotificationDevices().filter((device) => domain ? domain.allowsDevice(device.preferences) : preferenceAllows(plan.notification.type, device.preferences));
@@ -122,6 +123,10 @@ var NotificationService = class {
 		await Promise.all(deliveries.map((delivery) => this.send(delivery)));
 	}
 	async send(delivery) {
+		if (this.options.allowsNotification?.(delivery.event) === false) {
+			markNotificationDeliveryDead(delivery.event.id, delivery.deviceId, "Notification policy changed");
+			return;
+		}
 		const domain = this.options.domainDelivery?.owns(delivery.event.type) ? this.options.domainDelivery : void 0;
 		if (!domain && !Object.hasOwn(STANDARD_PREFERENCES, delivery.event.type)) {
 			markNotificationDeliveryDead(delivery.event.id, delivery.deviceId, "Notification domain delivery is not installed");

package/dist/src/platform/client.d.ts

@@ -66,10 +66,10 @@ export declare const RuntimeCommandSchema: z.ZodObject<{
                     read: "read";
                     write: "write";
                     execute: "execute";
-                    admin: "admin";
                     send: "send";
                     purchase: "purchase";
                     publish: "publish";
+                    admin: "admin";
                 }>>;
             }, z.core.$strict>;
             data: z.ZodObject<{

package/dist/src/platform/contracts.d.ts

@@ -152,10 +152,10 @@ export declare const AgentManifestSchema: z.ZodObject<{
             read: "read";
             write: "write";
             execute: "execute";
-            admin: "admin";
             send: "send";
             purchase: "purchase";
             publish: "publish";
+            admin: "admin";
         }>>;
     }, z.core.$strict>;
     data: z.ZodObject<{

package/dist/src/projects/capabilities/read.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityDispatcher } from '../../capabilities/runtime/dispatcher.js';
+import type { ProjectService } from '../project-service.js';
+export declare function registerProjectReadCapabilities(dispatcher: CapabilityDispatcher, projects: ProjectService): void;

package/dist/src/projects/capabilities/read.js

@@ -0,0 +1,81 @@
+import { ProductReadContracts } from "../../../packages/gateway-contract/src/capabilities.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import { defineReadCapability } from "../../capabilities/runtime/dispatcher.js";
+//#region src/projects/capabilities/read.ts
+init_src();
+function registerProjectReadCapabilities(dispatcher, projects) {
+	const requireProject = (id) => {
+		const project = projects.get(id);
+		if (!project) throw new CapabilityError("NOT_FOUND", "Project not found");
+		return project;
+	};
+	const policy = {
+		majorVersion: 1,
+		effect: "read",
+		surfaces: [
+			"http",
+			"agent",
+			"cli"
+		],
+		scopes: ["workspace.read"]
+	};
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.projects.get",
+		description: "Read a project and its domain details.",
+		...ProductReadContracts["xopc.projects.get"],
+		execute({ id }) {
+			const project = projects.getWithDetails(id);
+			if (!project) throw new CapabilityError("NOT_FOUND", "Project not found");
+			return {
+				ok: true,
+				project: { ...project }
+			};
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.projects.list",
+		description: "List projects with filters and pagination.",
+		...ProductReadContracts["xopc.projects.list"],
+		execute(input) {
+			const result = projects.list(input);
+			return {
+				ok: true,
+				...result,
+				items: result.items.map((project) => ({ ...project }))
+			};
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.projects.list_milestones",
+		description: "List project milestones.",
+		...ProductReadContracts["xopc.projects.list_milestones"],
+		execute({ id }) {
+			requireProject(id);
+			return {
+				ok: true,
+				projectId: id,
+				items: projects.listMilestones(id).map((item) => ({ ...item }))
+			};
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.projects.list_updates",
+		description: "List project progress updates.",
+		...ProductReadContracts["xopc.projects.list_updates"],
+		execute({ id, limit }) {
+			requireProject(id);
+			return {
+				ok: true,
+				projectId: id,
+				items: projects.listUpdates(id, limit).map((item) => ({ ...item }))
+			};
+		}
+	}));
+}
+//#endregion
+export { registerProjectReadCapabilities };

package/dist/src/projects/capabilities/write.d.ts

@@ -0,0 +1,9 @@
+import { type CapabilityDispatcher } from '../../capabilities/runtime/dispatcher.js';
+import { type ProjectService } from '../project-service.js';
+import type { Config } from '../../config/schema.js';
+import type { WorkDiscoveryService } from '../../work-discovery/service.js';
+export interface ProjectWriteCapabilityDeps {
+    getConfig?: () => Config | undefined;
+    getWorkDiscovery?: () => WorkDiscoveryService | undefined;
+}
+export declare function registerProjectWriteCapabilities(dispatcher: CapabilityDispatcher, service: ProjectService, deps?: ProjectWriteCapabilityDeps): void;

package/dist/src/projects/capabilities/write.js

@@ -0,0 +1,260 @@
+import { ProjectCreateInputSchema, ProjectDeleteInputSchema, ProjectDeleteOutputSchema, ProjectEditInputSchema, ProjectMilestoneCreateInputSchema, ProjectMilestoneDeleteInputSchema, ProjectMilestoneDeleteOutputSchema, ProjectMilestoneOutputSchema, ProjectMilestoneUpdateInputSchema, ProjectMutationOutputSchema, ProjectResolveWorkspaceInputSchema, ProjectResolveWorkspaceOutputSchema, ProjectSetPinnedInputSchema, ProjectUpdateCreateInputSchema, ProjectUpdateOutputSchema } from "../../../packages/gateway-contract/src/capabilities.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
+import { ensureSessionRecord } from "../../storage/sqlite/session-repository.js";
+import "../../storage/sqlite/index.js";
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import { defineAtomicCapability } from "../../capabilities/runtime/dispatcher.js";
+import { ProjectWorkspaceConflictError, ProjectWorkspaceMissingError } from "../workspace-project.js";
+import { ProjectDeletionBlockedError, ProjectWorkspaceInUseError, ProjectWorkspaceInvalidError } from "../project-service.js";
+import { isValidProjectAgentId, normalizeProjectAgentId } from "../project-agent.js";
+import { inferSuggestedProjectDefaultAgentId } from "../project-agent-suggestion.js";
+//#region src/projects/capabilities/write.ts
+init_src();
+function projectMutation(execute) {
+	try {
+		return execute();
+	} catch (error) {
+		if (error instanceof ProjectWorkspaceInvalidError) throw new CapabilityError("INVALID_INPUT", error.message);
+		if (error instanceof ProjectWorkspaceConflictError || error instanceof ProjectWorkspaceMissingError || error instanceof ProjectWorkspaceInUseError) {
+			const conflict = new CapabilityError("REVISION_CONFLICT", error.message);
+			conflict.cause = error;
+			throw conflict;
+		}
+		throw error;
+	}
+}
+function registerProjectWriteCapabilities(dispatcher, service, deps = {}) {
+	const policy = {
+		majorVersion: 1,
+		effect: "local-write",
+		surfaces: ["http", "agent"],
+		scopes: ["workspace.write"],
+		afterCommit: () => service.flushCommittedEffects()
+	};
+	const requireProject = (id) => {
+		const project = service.get(id);
+		if (!project) throw new CapabilityError("NOT_FOUND", "Project not found");
+		return project;
+	};
+	const agentId = (raw) => {
+		const normalized = normalizeProjectAgentId(raw);
+		const config = deps.getConfig?.();
+		if (normalized && !config) throw new CapabilityError("UNAVAILABLE", "Agent configuration is unavailable");
+		if (config && !isValidProjectAgentId(config, normalized)) throw new CapabilityError("INVALID_INPUT", "Default agent not found");
+		return normalized;
+	};
+	const flushWorkspace = (projectId) => {
+		try {
+			service.flushCommittedEffects(projectId);
+		} catch (error) {
+			const pending = new CapabilityError("UNAVAILABLE", "Project committed; workspace creation is pending. Retry the same idempotencyKey.");
+			pending.cause = error;
+			throw pending;
+		}
+	};
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		id: "xopc.projects.create",
+		description: "Create a project with a durable receipt and recoverable post-commit workspace creation.",
+		input: ProjectCreateInputSchema,
+		output: ProjectMutationOutputSchema,
+		execute({ autoUnderstand, ...input }) {
+			const understanding = autoUnderstand ? deps.getWorkDiscovery?.() : void 0;
+			if (autoUnderstand && !understanding) throw new CapabilityError("UNAVAILABLE", "Project understanding service is unavailable");
+			const config = deps.getConfig?.();
+			const defaultAgentId = input.defaultAgentId !== void 0 ? agentId(input.defaultAgentId) : config ? inferSuggestedProjectDefaultAgentId({
+				config,
+				...input
+			}) : void 0;
+			const project = projectMutation(() => service.create({
+				...input,
+				defaultAgentId
+			}));
+			understanding?.startProjectUnderstanding(project.id);
+			return {
+				ok: true,
+				project: { ...project }
+			};
+		},
+		afterCommit: (result) => flushWorkspace(result.project.id)
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		id: "xopc.projects.update",
+		description: "Edit a project at its exact version with recoverable workspace creation.",
+		input: ProjectEditInputSchema,
+		output: ProjectMutationOutputSchema,
+		execute({ id, expectedVersion, patch }) {
+			if (requireProject(id).version !== expectedVersion) throw new CapabilityError("REVISION_CONFLICT", "Project changed");
+			const defaultAgentId = patch.defaultAgentId === void 0 ? void 0 : agentId(patch.defaultAgentId) ?? null;
+			return {
+				ok: true,
+				project: { ...projectMutation(() => service.update(id, {
+					...patch,
+					...patch.defaultAgentId === void 0 ? {} : { defaultAgentId }
+				})) }
+			};
+		},
+		afterCommit: (result) => flushWorkspace(result.project.id)
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		id: "xopc.projects.resolve_workspace",
+		description: "Resolve or create a workspace project and optionally bind an unassigned conversation atomically.",
+		input: ProjectResolveWorkspaceInputSchema,
+		output: ProjectResolveWorkspaceOutputSchema,
+		execute(input) {
+			const config = deps.getConfig?.();
+			const existing = input.conversationId ? getSessionMetadata(input.conversationId) : void 0;
+			const requestedAgent = existing ? existing.routing?.agentId || existing.agentId : input.agentId;
+			const resolvedAgent = requestedAgent ? agentId(requestedAgent) ?? void 0 : void 0;
+			const defaultAgentId = input.defaultAgentId !== void 0 ? agentId(input.defaultAgentId) ?? void 0 : config ? inferSuggestedProjectDefaultAgentId({
+				config,
+				workspaceRoot: input.workspacePath,
+				projectKind: input.projectKind
+			}) : resolvedAgent;
+			const match = projectMutation(() => service.resolveOrCreateForWorkspacePath({
+				...input,
+				agentId: resolvedAgent,
+				defaultAgentId
+			}));
+			if (!match) return {
+				ok: true,
+				project: null
+			};
+			const projectAgent = normalizeProjectAgentId(match.project.defaultAgentId);
+			if (input.conversationId && (!projectAgent || projectAgent === resolvedAgent)) {
+				if (existing?.projectId && existing.projectId !== match.project.id) throw new CapabilityError("REVISION_CONFLICT", "Conversation is already bound to another project");
+				if (!existing) ensureSessionRecord(input.conversationId, match.project.workspaceRoot ?? input.workspacePath, {
+					sourceChannel: "tui",
+					sourceChatId: `default:direct:${input.conversationId}`,
+					sessionType: "chat",
+					routing: {
+						agentId: resolvedAgent ?? "main",
+						source: "tui",
+						accountId: "default",
+						peerKind: "direct",
+						peerId: input.conversationId
+					}
+				});
+				if (existing?.projectId !== match.project.id) service.attachSession(input.conversationId, match.project.id);
+			}
+			return {
+				ok: true,
+				...match,
+				project: { ...service.get(match.project.id) }
+			};
+		}
+	}));
+	const requireMilestone = (projectId, id, revision) => {
+		requireProject(projectId);
+		const milestone = service.listMilestones(projectId).find((item) => item.id === id);
+		if (!milestone) throw new CapabilityError("NOT_FOUND", "Milestone not found");
+		if (milestone.updatedAt !== revision) throw new CapabilityError("REVISION_CONFLICT", "Milestone changed");
+	};
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		id: "xopc.projects.delete",
+		description: "Delete a project at its exact version without removing workspace files. External execution stop is not confirmed.",
+		input: ProjectDeleteInputSchema,
+		output: ProjectDeleteOutputSchema,
+		execute({ id, expectedVersion }) {
+			if (requireProject(id).version !== expectedVersion) throw new CapabilityError("REVISION_CONFLICT", "Project changed");
+			try {
+				service.delete(id);
+			} catch (error) {
+				if (error instanceof ProjectDeletionBlockedError) {
+					const conflict = new CapabilityError("REVISION_CONFLICT", error.message);
+					conflict.cause = error;
+					throw conflict;
+				}
+				throw error;
+			}
+			return {
+				ok: true,
+				deleted: true,
+				executionStopConfirmed: false
+			};
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		id: "xopc.projects.set_pinned",
+		description: "Pin or unpin a project at its exact version with a durable receipt.",
+		input: ProjectSetPinnedInputSchema,
+		output: ProjectMutationOutputSchema,
+		execute({ id, expectedVersion, pinned }) {
+			if (requireProject(id).version !== expectedVersion) throw new CapabilityError("REVISION_CONFLICT", "Project changed");
+			return {
+				ok: true,
+				project: { ...pinned ? service.pin(id) : service.unpin(id) }
+			};
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		id: "xopc.projects.create_milestone",
+		description: "Create a project milestone with a durable receipt.",
+		input: ProjectMilestoneCreateInputSchema,
+		output: ProjectMilestoneOutputSchema,
+		execute({ projectId, ...input }) {
+			requireProject(projectId);
+			return {
+				ok: true,
+				milestone: { ...service.createMilestone(projectId, input) },
+				project: { ...requireProject(projectId) }
+			};
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		id: "xopc.projects.update_milestone",
+		description: "Edit a milestone at its exact updatedAt revision.",
+		input: ProjectMilestoneUpdateInputSchema,
+		output: ProjectMilestoneOutputSchema,
+		execute({ projectId, id, expectedRevision, patch }) {
+			requireMilestone(projectId, id, expectedRevision);
+			return {
+				ok: true,
+				milestone: { ...service.updateMilestone(projectId, id, patch) },
+				project: { ...requireProject(projectId) }
+			};
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		id: "xopc.projects.delete_milestone",
+		description: "Delete a milestone at its exact updatedAt revision.",
+		input: ProjectMilestoneDeleteInputSchema,
+		output: ProjectMilestoneDeleteOutputSchema,
+		execute({ projectId, id, expectedRevision }) {
+			requireMilestone(projectId, id, expectedRevision);
+			service.deleteMilestone(projectId, id);
+			return {
+				ok: true,
+				deleted: true
+			};
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		id: "xopc.projects.create_update",
+		description: "Record progress and change project health at an exact project version.",
+		input: ProjectUpdateCreateInputSchema,
+		output: ProjectUpdateOutputSchema,
+		execute({ projectId, expectedVersion, ...input }, context) {
+			if (requireProject(projectId).version !== expectedVersion) throw new CapabilityError("REVISION_CONFLICT", "Project changed");
+			return {
+				ok: true,
+				update: { ...service.createUpdate(projectId, {
+					...input,
+					actor: context.actor ?? { kind: "system" }
+				}) },
+				project: { ...requireProject(projectId) }
+			};
+		}
+	}));
+}
+//#endregion
+export { registerProjectWriteCapabilities };

package/dist/src/projects/index.js

@@ -3,7 +3,7 @@ import { getProjectForSession, getProjectWorkspacePathForSession, resolveProject
 import { ProjectWorkspaceConflictError, ProjectWorkspaceMissingError, canonicalWorkspacePath, ensureWorkspaceDirectory, inferProjectNameFromWorkspaceRoot, isPathSameOrInsideWorkspace, isSafeAutoCreateWorkspaceRoot, resolveWorkspaceProjectRoot, workspaceDirectoryExists } from "./workspace-project.js";
 import { inferProjectExecutionMode, inferProjectKind } from "./project-kind.js";
 import { bindSessionToProject, bindSessionsToProject, listProjectConversationIds, moveSessionToProject, unbindSessionFromProject } from "./session-bind.js";
-import { ProjectService } from "./project-service.js";
+import { ProjectDeletionBlockedError, ProjectService, ProjectWorkspaceInUseError, ProjectWorkspaceInvalidError } from "./project-service.js";
 import { ProjectSkillError, ProjectSkillService } from "./project-skill-service.js";
 import { isValidProjectAgentId, normalizeProjectAgentId, resolveProjectAgentId } from "./project-agent.js";
 import { CODING_PROJECT_AGENT_ID, inferSuggestedProjectDefaultAgentId, suggestProjectDefaultAgentId } from "./project-agent-suggestion.js";
@@ -11,4 +11,4 @@ import { buildProjectLoopOverview } from "./project-loop.js";
 import { bindWorkflowRunToProject } from "./workflow-bind.js";
 import { bindAutomationToProject } from "./automation-bind.js";
 import { bindKnowledgeItemToProject } from "./knowledge-bind.js";
-export { CODING_PROJECT_AGENT_ID, ProjectService, ProjectSkillError, ProjectSkillService, ProjectStore, ProjectWorkspaceConflictError, ProjectWorkspaceMissingError, bindAutomationToProject, bindKnowledgeItemToProject, bindSessionToProject, bindSessionsToProject, bindWorkflowRunToProject, buildProjectLoopOverview, canonicalWorkspacePath, ensureWorkspaceDirectory, getProjectForSession, getProjectWorkspacePathForSession, inferProjectExecutionMode, inferProjectKind, inferProjectNameFromWorkspaceRoot, inferSuggestedProjectDefaultAgentId, isPathSameOrInsideWorkspace, isSafeAutoCreateWorkspaceRoot, isValidProjectAgentId, listProjectConversationIds, moveSessionToProject, normalizeProjectAgentId, resolveProjectAgentId, resolveProjectWorkspacePath, resolveWorkspaceProjectRoot, slugifyProjectName, suggestProjectDefaultAgentId, unbindSessionFromProject, workspaceDirectoryExists };
+export { CODING_PROJECT_AGENT_ID, ProjectDeletionBlockedError, ProjectService, ProjectSkillError, ProjectSkillService, ProjectStore, ProjectWorkspaceConflictError, ProjectWorkspaceInUseError, ProjectWorkspaceInvalidError, ProjectWorkspaceMissingError, bindAutomationToProject, bindKnowledgeItemToProject, bindSessionToProject, bindSessionsToProject, bindWorkflowRunToProject, buildProjectLoopOverview, canonicalWorkspacePath, ensureWorkspaceDirectory, getProjectForSession, getProjectWorkspacePathForSession, inferProjectExecutionMode, inferProjectKind, inferProjectNameFromWorkspaceRoot, inferSuggestedProjectDefaultAgentId, isPathSameOrInsideWorkspace, isSafeAutoCreateWorkspaceRoot, isValidProjectAgentId, listProjectConversationIds, moveSessionToProject, normalizeProjectAgentId, resolveProjectAgentId, resolveProjectWorkspacePath, resolveWorkspaceProjectRoot, slugifyProjectName, suggestProjectDefaultAgentId, unbindSessionFromProject, workspaceDirectoryExists };

package/dist/src/projects/project-change-events.d.ts

@@ -0,0 +1,2 @@
+import type { Project } from './types.js';
+export declare function enqueueProjectChanged(project: Project, changedFields: string[], operation?: 'created' | 'updated' | 'deleted', deletedUnderstandingRunIds?: string[]): void;

package/dist/src/projects/project-change-events.js

@@ -0,0 +1,18 @@
+import { currentOperationId, init_operation_context } from "../infra/operation-context.js";
+import { getSqliteDatabase, init_transaction } from "../storage/sqlite/transaction.js";
+import { randomUUID } from "node:crypto";
+//#region src/projects/project-change-events.ts
+init_operation_context();
+init_transaction();
+function enqueueProjectChanged(project, changedFields, operation = "updated", deletedUnderstandingRunIds = []) {
+	getSqliteDatabase().prepare(`INSERT INTO domain_outbox
+    (event_id, event_type, subject_kind, subject_id, correlation_id, payload_json, created_at, operation_id)
+    VALUES (?, ?, 'project', ?, ?, ?, ?, ?)`).run(randomUUID(), operation === "updated" ? "project.changed" : `project.${operation}`, project.id, project.id, JSON.stringify({
+		projectId: project.id,
+		version: project.version,
+		changedFields,
+		...deletedUnderstandingRunIds.length ? { deletedUnderstandingRunIds } : {}
+	}), project.updatedAt, currentOperationId() ?? null);
+}
+//#endregion
+export { enqueueProjectChanged };

package/dist/src/projects/project-service.d.ts

@@ -7,6 +7,15 @@ export type ProjectSuggestion = {
     score: number;
     reason: string;
 };
+export declare class ProjectDeletionBlockedError extends Error {
+    constructor();
+}
+export declare class ProjectWorkspaceInvalidError extends Error {
+    constructor();
+}
+export declare class ProjectWorkspaceInUseError extends Error {
+    constructor();
+}
 export declare class ProjectService {
     private readonly store;
     constructor(store?: ProjectStore);
@@ -38,6 +47,8 @@ export declare class ProjectService {
     createMilestone(projectId: string, input: Parameters<ProjectStore['createMilestone']>[1]): ProjectMilestone;
     updateMilestone(projectId: string, milestoneId: string, input: Parameters<ProjectStore['updateMilestone']>[2]): ProjectMilestone;
     deleteMilestone(projectId: string, milestoneId: string): boolean;
+    private recordMilestoneChange;
+    flushCommittedEffects(projectId?: string): void;
     listUpdates(projectId: string, limit?: number): ProjectUpdate[];
     createUpdate(projectId: string, input: {
         health: ProjectHealth;