@xopcai/xopc 0.0.313 → 0.0.315

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

@@ -0,0 +1,96 @@
+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/notes/capabilities/read.ts
+init_src();
+function registerNoteReadCapabilities(dispatcher, getNotes) {
+	const policy = {
+		majorVersion: 1,
+		effect: "read",
+		surfaces: [
+			"http",
+			"agent",
+			"cli"
+		],
+		scopes: ["workspace.read"]
+	};
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.notes.preview_edit",
+		description: "Build a local edit suggestion without modifying the note or calling a model.",
+		...ProductReadContracts["xopc.notes.preview_edit"],
+		async execute({ id, instruction, markdown }) {
+			const result = await getNotes().createAiEditPatch(id, instruction, markdown);
+			if (!result) throw new CapabilityError("NOT_FOUND", "Note not found");
+			return ProductReadContracts["xopc.notes.preview_edit"].output.parse(result);
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.notes.project_summaries",
+		description: "List project note counts without rebuilding understanding.",
+		...ProductReadContracts["xopc.notes.project_summaries"],
+		execute: () => ({ items: getNotes().listProjectSummaries() })
+	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.notes.history",
+		description: "List immutable note history snapshots.",
+		...ProductReadContracts["xopc.notes.history"],
+		execute: async ({ id }) => ({ entries: await getNotes().listNoteHistory(id) })
+	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.notes.snapshot",
+		description: "Read one note snapshot at an exact timestamp.",
+		...ProductReadContracts["xopc.notes.snapshot"],
+		async execute({ id, timestamp }) {
+			const snapshot = await getNotes().getNoteSnapshot(id, timestamp);
+			if (!snapshot) throw new CapabilityError("NOT_FOUND", "Snapshot not found");
+			return { snapshot };
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		id: "xopc.notes.get",
+		majorVersion: 1,
+		description: "Read a note by its stable ID.",
+		effect: "read",
+		surfaces: [
+			"http",
+			"agent",
+			"cli",
+			"extension"
+		],
+		scopes: ["workspace.read"],
+		...ProductReadContracts["xopc.notes.get"],
+		async execute({ id }) {
+			const note = await getNotes().getNote(id);
+			if (!note) throw new CapabilityError("NOT_FOUND", `Note not found: ${id}`);
+			return { note: { ...note } };
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		id: "xopc.notes.list",
+		majorVersion: 1,
+		description: "List notes using explicit filters and pagination.",
+		effect: "read",
+		surfaces: [
+			"http",
+			"agent",
+			"cli",
+			"extension"
+		],
+		scopes: ["workspace.read"],
+		...ProductReadContracts["xopc.notes.list"],
+		async execute(input) {
+			const result = await getNotes().listNotes(input);
+			return {
+				...result,
+				items: result.items.map((item) => ({ ...item }))
+			};
+		}
+	}));
+}
+//#endregion
+export { registerNoteReadCapabilities };

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

@@ -0,0 +1,7 @@
+import { type CapabilityDispatcher } from '../../capabilities/runtime/dispatcher.js';
+import { type NotesService } from '../service.js';
+import type { ProjectService } from '../../projects/index.js';
+export declare function registerNoteWriteCapabilities(dispatcher: CapabilityDispatcher, deps: {
+    getNotes: () => NotesService;
+    getProjects?: () => ProjectService | undefined;
+}): void;

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

@@ -0,0 +1,152 @@
+import { NoteAppendInputSchema, NoteCaptureInputSchema, NoteCreateInputSchema, NoteDeleteInputSchema, NoteDeleteOutputSchema, NoteGetOutputSchema, NoteRestoreInputSchema, NoteUpdateInputSchema } from "../../../packages/gateway-contract/src/capabilities.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { ObjectLinkService } from "../../activity/service.js";
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import { defineAtomicCapability } from "../../capabilities/runtime/dispatcher.js";
+import { NoteRevisionConflictError } from "../service.js";
+//#region src/notes/capabilities/write.ts
+init_src();
+function registerNoteWriteCapabilities(dispatcher, deps) {
+	dispatcher.register(defineAtomicCapability({
+		id: "xopc.notes.delete",
+		majorVersion: 1,
+		description: "Delete a note at an exact revision, revoke shares by default, and durably queue file cleanup after commit.",
+		effect: "local-write",
+		surfaces: ["http", "agent"],
+		scopes: ["workspace.write"],
+		input: NoteDeleteInputSchema,
+		output: NoteDeleteOutputSchema,
+		execute({ id, expectedRevision, revokeShares }) {
+			try {
+				const result = deps.getNotes().deleteNoteAtomically(id, expectedRevision, revokeShares);
+				if (!result.deleted) throw new CapabilityError("NOT_FOUND", "Note not found");
+				return {
+					deleted: true,
+					revokedShares: result.revokedShares
+				};
+			} catch (error) {
+				if (error instanceof NoteRevisionConflictError) throw new CapabilityError("REVISION_CONFLICT", error.message);
+				throw error;
+			}
+		},
+		afterCommit() {
+			deps.getNotes().flushCommittedEffects();
+		}
+	}));
+	const result = (execute) => {
+		try {
+			const note = execute();
+			if (!note) throw new CapabilityError("NOT_FOUND", "Note or snapshot not found");
+			return { note: { ...note } };
+		} catch (error) {
+			if (error instanceof NoteRevisionConflictError) throw new CapabilityError("REVISION_CONFLICT", error.message);
+			throw error;
+		}
+	};
+	dispatcher.register(defineAtomicCapability({
+		id: "xopc.notes.capture",
+		majorVersion: 1,
+		description: "Capture text with a durable receipt.",
+		effect: "local-write",
+		surfaces: ["http"],
+		scopes: ["workspace.write"],
+		input: NoteCaptureInputSchema,
+		output: NoteGetOutputSchema,
+		execute: (input, context) => result(() => deps.getNotes().quickCaptureAtomically(input.text, input.capturedVia, context.idempotencyKey)),
+		afterCommit() {
+			deps.getNotes().flushCommittedEffects();
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		id: "xopc.notes.append",
+		majorVersion: 1,
+		description: "Append text once without replacing concurrent content.",
+		effect: "local-write",
+		surfaces: [
+			"http",
+			"agent",
+			"extension"
+		],
+		scopes: ["workspace.write"],
+		input: NoteAppendInputSchema,
+		output: NoteGetOutputSchema,
+		execute: (input) => result(() => deps.getNotes().appendTextToNoteAtomically(input.id, input.content, input.heading, input.expectedRevision)),
+		afterCommit() {
+			deps.getNotes().flushCommittedEffects();
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		id: "xopc.notes.restore",
+		majorVersion: 1,
+		description: "Restore a snapshot at an exact current note revision.",
+		effect: "local-write",
+		surfaces: ["http"],
+		scopes: ["workspace.write"],
+		input: NoteRestoreInputSchema,
+		output: NoteGetOutputSchema,
+		execute: (input) => result(() => deps.getNotes().restoreNoteSnapshotAtomically(input.id, input.timestamp, input.expectedRevision)),
+		afterCommit() {
+			deps.getNotes().flushCommittedEffects();
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		id: "xopc.notes.create",
+		majorVersion: 1,
+		description: "Create a note with a durable receipt and optional project link.",
+		effect: "local-write",
+		surfaces: [
+			"http",
+			"agent",
+			"extension"
+		],
+		scopes: ["workspace.write"],
+		input: NoteCreateInputSchema,
+		output: NoteGetOutputSchema,
+		execute({ projectId, ...input }, context) {
+			const project = projectId ? deps.getProjects?.()?.get(projectId) : void 0;
+			if (projectId && !project) throw new CapabilityError("NOT_FOUND", "Project not found");
+			const note = deps.getNotes().createNoteAtomically(input, context.idempotencyKey);
+			if (project) new ObjectLinkService().create({
+				id: `note:${note.id}:project:${project.id}`,
+				from: {
+					kind: "note",
+					id: note.id,
+					title: note.title
+				},
+				to: {
+					kind: "project",
+					id: project.id,
+					title: project.name
+				},
+				relation: "belongs_to",
+				source: "user"
+			});
+			return { note: { ...note } };
+		},
+		afterCommit() {
+			deps.getNotes().flushCommittedEffects();
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		id: "xopc.notes.update",
+		majorVersion: 1,
+		description: "Update a note at an exact revision; file cleanup is durable and post-commit.",
+		effect: "local-write",
+		surfaces: [
+			"http",
+			"agent",
+			"extension"
+		],
+		scopes: ["workspace.write"],
+		input: NoteUpdateInputSchema,
+		output: NoteGetOutputSchema,
+		execute(input, context) {
+			return result(() => deps.getNotes().updateNoteAtomically(input.id, input.patch, context.surface === "agent" ? "ai_edit" : input.trigger ?? "edit", input.expectedRevision));
+		},
+		afterCommit() {
+			deps.getNotes().flushCommittedEffects();
+		}
+	}));
+}
+//#endregion
+export { registerNoteWriteCapabilities };

package/dist/src/notes/index.js

@@ -1,5 +1,5 @@
+import { buildNoteAgentContext, buildNoteAgentContextArtifact, getCachedNoteAgentContextArtifact } from "./agent-context.js";
 import { resolveNoteMediaDir, resolveNotesDir } from "./paths.js";
 import { NotesStore } from "./store.js";
-import { buildNoteAgentContext, buildNoteAgentContextArtifact, getCachedNoteAgentContextArtifact } from "./agent-context.js";
 import { NotesService } from "./service.js";
 export { NotesService, NotesStore, buildNoteAgentContext, buildNoteAgentContextArtifact, getCachedNoteAgentContextArtifact, resolveNoteMediaDir, resolveNotesDir };

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

@@ -2,20 +2,22 @@ import type { Config } from '../config/schema.js';
 import { buildNoteAttachmentRef } from './attachment-ref.js';
 import { NotesStore } from './store.js';
 import type { CaptureSource, CreateNoteParams, Note, NoteAiPatch, NoteAttachment, NoteCatalysisReport, NoteIndexEntry, NoteSnapshot, NoteSnapshotEntry, NotesListQuery, SnapshotTrigger } from './types.js';
+export declare class NoteRevisionConflictError extends Error {
+}
 export declare class NotesService {
     private readonly store;
-    private lastSnapshotAt;
-    private quickCapturesInFlight;
-    private noteCapturesInFlight;
     private noteAttachmentsInFlight;
     constructor(store?: NotesStore);
     initialize(): Promise<void>;
+    flushCommittedEffects(): void;
     quickCapture(markdown: string, source: CaptureSource, idempotencyKey?: string): Promise<Note>;
-    private createQuickCapture;
+    quickCaptureAtomically(markdown: string, source: CaptureSource, idempotencyKey?: string): Note;
     createNote(params: CreateNoteParams, idempotencyKey?: string): Promise<Note>;
+    createNoteAtomically(params: CreateNoteParams, idempotencyKey?: string): Note;
     private createNoteWithId;
     getNote(id: string): Promise<Note | null>;
     updateNote(id: string, patch: Partial<Note>, trigger?: SnapshotTrigger): Promise<Note | null>;
+    updateNoteAtomically(id: string, patch: Partial<Note>, trigger?: SnapshotTrigger, expectedRevision?: number): Note | null;
     private reconcileAttachments;
     syncNote(id: string, patch: Partial<Note>, baseRemoteVersion?: number): Promise<{
         note: Note | null;
@@ -38,7 +40,12 @@ export declare class NotesService {
         stale: boolean;
     } | null>;
     appendTextToNote(id: string, content: string, heading?: string): Promise<Note | null>;
+    appendTextToNoteAtomically(id: string, content: string, heading?: string, expectedRevision?: number): Note | null;
     deleteNote(id: string): Promise<boolean>;
+    deleteNoteAtomically(id: string, expectedRevision?: number, revokeShares?: boolean): {
+        deleted: boolean;
+        revokedShares: number;
+    };
     listNotes(query?: NotesListQuery): Promise<{
         items: NoteIndexEntry[];
         total: number;
@@ -66,6 +73,7 @@ export declare class NotesService {
     listNoteHistory(noteId: string): Promise<NoteSnapshotEntry[]>;
     getNoteSnapshot(noteId: string, timestamp: number): Promise<NoteSnapshot | null>;
     restoreNoteSnapshot(noteId: string, timestamp: number): Promise<Note | null>;
+    restoreNoteSnapshotAtomically(noteId: string, timestamp: number, expectedRevision?: number): Note | null;
     moveToGroup(noteId: string, groupId: string | null): Promise<Note | null>;
     createTask(title: string, source: CaptureSource, opts?: {
         dueAt?: number;