@danypops/papyrus 0.60.1 → 0.60.3

package/src/handlers/binders.ts

@@ -0,0 +1,231 @@
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import type { ArtifactTrashStore } from "../artifact/artifact-trash-store.ts";
+import { binderTree } from "../binder/binder-service.ts";
+import { bindersOperations } from "../modules/binders.ts";
+import type { ProjectRegistryStore } from "../project-registry/project-registry-store.ts";
+import { normalizeProjectRoot } from "../project-registry/scope-source.ts";
+import type { ScopeGroupStore } from "../scope-group/scope-group-store.ts";
+import { booleanProp, createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
+
+const OWNER = "binders";
+
+function resolveBinderId(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	projectRoot: string | undefined,
+	id: unknown,
+	name: unknown,
+): string {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.trim().length === 0) throw validationError("id or name is required");
+	const alias = artifacts.getByAlias(name.trim());
+	if (alias?.kind === "binder" && (projectRoot === undefined || scopes.appliesToProjectRoot(alias.id, normalizeProjectRoot(projectRoot)))) {
+		return alias.id;
+	}
+	const tree = binderTree(artifacts, scopes, { projectRoot });
+	const pathNeedle = name.trim().startsWith("/") ? name.trim() : `/${name.trim()}`;
+	const pathMatches = tree.nodes.filter((node) => node.path.toLowerCase() === pathNeedle.toLowerCase());
+	if (pathMatches.length === 1) return pathMatches[0]!.binder.id;
+	const titleMatches = tree.nodes.filter((node) => node.binder.title.trim().toLowerCase() === name.trim().toLowerCase());
+	if (titleMatches.length === 1) return titleMatches[0]!.binder.id;
+	if (titleMatches.length > 1 || pathMatches.length > 1) {
+		const matches = pathMatches.length > 0 ? pathMatches : titleMatches;
+		throw validationError(`binder name "${name}" is ambiguous: ${matches.map((node) => node.path).join(", ")} -- use a path or id`);
+	}
+	throw validationError(`no binder named "${name}" found in this project context`);
+}
+
+function resolveAnyArtifactId(artifacts: ArtifactStore, id: unknown, name: unknown): string {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.trim().length === 0) throw validationError("artifact_id or artifact_name is required");
+	return resolveArtifactIdWidened(artifacts, name, () => artifacts.query({ text: name }));
+}
+
+export function registerBindersVehicleOperations(
+	registry: VehicleRegistry,
+	artifacts: ArtifactStore & ArtifactTrashStore,
+	scopes: ArtifactScopeStore,
+	projectRegistry: ProjectRegistryStore,
+	scopeGroups: ScopeGroupStore,
+): void {
+	const operations = new Map(
+		bindersOperations(artifacts, scopes, projectRegistry, scopeGroups).map((operation) => [operation.name, operation]),
+	);
+	const call = (name: string, input: Record<string, unknown>): unknown => operations.get(name)!.execute(input);
+	const define = createOperationDefiner(registry, OWNER, "binders", ["binders:read", "binders:write"], call);
+	const arrayProp = { type: "array" } as unknown as { type: string };
+	const withBinderId = (input: Record<string, unknown>, idKey = "id", nameKey = "name") => ({
+		...input,
+		[idKey]: resolveBinderId(artifacts, scopes, input.project_root as string | undefined, input[idKey], input[nameKey]),
+	});
+
+	define(
+		"create",
+		"Creates a filesystem-style Binder. Binders organize artifacts without changing Task containment or Playbook execution. Direct labels on a Binder are inherited additively by descendants at read time. Prefer parent_name (a title, alias, or /path) over parent_id.",
+		"local-write",
+		{ title: stringProp, labels: arrayProp, parent_id: stringProp, parent_name: stringProp, project_root: stringProp, projects: arrayProp },
+		["title"],
+		(input) => ({
+			...input,
+			...(input.parent_id || input.parent_name
+				? { parent_id: resolveBinderId(artifacts, scopes, input.project_root as string | undefined, input.parent_id, input.parent_name) }
+				: {}),
+		}),
+	);
+	define(
+		"list",
+		"Lists Binders. project_root alone is exact-membership audit scope; project_root plus applicable:true includes global Binders and Binders applicable to the project. Returns lean summaries unless full:true.",
+		"read",
+		{ text: stringProp, limit: numberProp, project_root: stringProp, applicable: booleanProp, full: booleanProp },
+		[],
+		(input) => input,
+	);
+	define(
+		"tree",
+		"Returns the project-context Binder tree plus placements and direct/inherited/effective labels for the bounded artifact_ids supplied. Label inheritance is computed, not copied into artifact labels.",
+		"read",
+		{ project_root: stringProp, artifact_ids: arrayProp },
+		[],
+		(input) => input,
+	);
+	define(
+		"show",
+		"Shows one Binder node by id, alias, title, or /path, including its path and inherited/effective labels.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => withBinderId(input),
+	);
+	define(
+		"update",
+		"Renames a Binder and/or replaces its direct labels. Inherited labels on descendants update immediately because they are computed dynamically.",
+		"local-write",
+		{ id: stringProp, name: stringProp, title: stringProp, labels: arrayProp, project_root: stringProp },
+		[],
+		(input) => withBinderId(input),
+	);
+	define(
+		"move",
+		"Moves a Binder under parent_id/parent_name, or to the project-context root when neither is supplied. Rejects cycles and duplicate sibling names.",
+		"local-write",
+		{ id: stringProp, name: stringProp, parent_id: stringProp, parent_name: stringProp, project_root: stringProp },
+		[],
+		(input) => {
+			const resolved = withBinderId(input);
+			return {
+				...resolved,
+				...(input.parent_id || input.parent_name
+					? { parent_id: resolveBinderId(artifacts, scopes, input.project_root as string | undefined, input.parent_id, input.parent_name) }
+					: {}),
+			};
+		},
+	);
+	define(
+		"file",
+		"Files one non-Binder artifact in a Binder for this project context, replacing its previous visible placement. Prefer binder_name/artifact_name over ids when unambiguous.",
+		"local-write",
+		{
+			binder_id: stringProp,
+			binder_name: stringProp,
+			artifact_id: stringProp,
+			artifact_name: stringProp,
+			project_root: stringProp,
+		},
+		[],
+		(input) => ({
+			...input,
+			binder_id: resolveBinderId(artifacts, scopes, input.project_root as string | undefined, input.binder_id, input.binder_name),
+			artifact_id: resolveAnyArtifactId(artifacts, input.artifact_id, input.artifact_name),
+		}),
+	);
+	define(
+		"unfile",
+		"Moves one artifact to this project context's Binder root. This changes organization only, never Task containment or dependencies.",
+		"local-write",
+		{ artifact_id: stringProp, artifact_name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, artifact_id: resolveAnyArtifactId(artifacts, input.artifact_id, input.artifact_name) }),
+	);
+	define(
+		"remove",
+		"Trashes an empty Binder. A non-empty Binder is rejected until its contents are moved or unfiled.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp, reason: stringProp },
+		[],
+		(input) => withBinderId(input),
+	);
+	define(
+		"scope",
+		"Shows a Binder's project/scope-group scope.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => withBinderId(input),
+	);
+	define(
+		"set_global",
+		"Makes a Binder apply in every project.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => withBinderId(input),
+	);
+	define(
+		"set_none",
+		"Hides a Binder from every project context.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => withBinderId(input),
+	);
+	define(
+		"add_project",
+		"Adds one registered project to a Binder's explicit scope.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project: stringProp, project_root: stringProp },
+		["project"],
+		(input) => withBinderId(input),
+	);
+	define(
+		"remove_project",
+		"Removes one project from a Binder's explicit scope; removing the final member is rejected.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project: stringProp, project_root: stringProp },
+		["project"],
+		(input) => withBinderId(input),
+	);
+	define(
+		"replace_projects",
+		"Replaces a Binder's project membership with a bounded non-empty list.",
+		"local-write",
+		{ id: stringProp, name: stringProp, projects: arrayProp, project_root: stringProp },
+		["projects"],
+		(input) => withBinderId(input),
+	);
+	define(
+		"add_group",
+		"Adds one nested scope group to a Binder's explicit scope.",
+		"local-write",
+		{ id: stringProp, name: stringProp, group: stringProp, project_root: stringProp },
+		["group"],
+		(input) => withBinderId(input),
+	);
+	define(
+		"remove_group",
+		"Removes one scope group from a Binder's explicit scope; removing the final member is rejected.",
+		"local-write",
+		{ id: stringProp, name: stringProp, group: stringProp, project_root: stringProp },
+		["group"],
+		(input) => withBinderId(input),
+	);
+	define(
+		"replace_groups",
+		"Replaces a Binder's scope-group membership with a bounded non-empty list.",
+		"local-write",
+		{ id: stringProp, name: stringProp, groups: arrayProp, project_root: stringProp },
+		["groups"],
+		(input) => withBinderId(input),
+	);
+}

package/src/handlers/notes.ts

@@ -60,6 +60,21 @@ export function registerNotesVehicleOperations(registry: VehicleRegistry, notes:
 		(input) => input,
 	);
 
+	define(
+		"list_page",
+		"Cursor-paginates a stable Note inventory. Omit project_root only for an intentional cross-project audit; use nextCursor until absent.",
+		"read",
+		{
+			project_root: stringProp,
+			status: { type: "string", enum: ["draft", "active", "archived"] },
+			text: stringProp,
+			limit: numberProp,
+			cursor: stringProp,
+		},
+		[],
+		(input) => input,
+	);
+
 	define(
 		"show",
 		"Shows one note by id or title.",

package/src/handlers/registry.ts

@@ -21,6 +21,7 @@ import type { TaskScopeStore } from "../task/scope/task-scope-store.ts";
 import type { Tasks } from "../task/task-service.ts";
 import { registerArtifactTrashOperations } from "./artifact-trash.ts";
 import { registerBatchVehicleOperation } from "./batch.ts";
+import { registerBindersVehicleOperations } from "./binders.ts";
 import { registerDiscussVehicleOperations } from "./discuss.ts";
 import { registerDocsVehicleOperations } from "./docs.ts";
 import { registerNotesVehicleOperations } from "./notes.ts";
@@ -56,6 +57,7 @@ export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleR
 	// session_id, a correlation id, not a secret -- see session-identity-service.ts).
 	registry.setExposeHandlerFailureDetails(true);
 	registerNotesVehicleOperations(registry, deps.notes, deps.artifacts);
+	registerBindersVehicleOperations(registry, deps.artifacts, deps.scopes, deps.projectRegistry, deps.scopeGroups);
 	registerRulesVehicleOperations(registry, deps.artifacts, deps.scopes, deps.projectRegistry, deps.scopeGroups);
 	registerDocsVehicleOperations(registry, deps.artifacts, deps.scopes, deps.authority, deps.projectRegistry, deps.scopeGroups);
 	registerPlaybooksVehicleOperations(registry, {

package/src/handlers/tasks.ts

@@ -246,6 +246,7 @@ const readSchemaProps = {
 
 /** list-only: opts into full Artifact bodies instead of the lean summarizeArtifact() default (modules/tasks.ts). */
 const listSchemaProps = { ...readSchemaProps, full: booleanProp };
+const listPageSchemaProps = { ...listSchemaProps, cursor: stringProp };
 
 /** Same gate/checklist narrative lines the removed tool built client-side. */
 function completionContentText(labels: Map<string, string>, result: TaskCompletion): string {
@@ -447,6 +448,18 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		},
 	);
 
+	define(
+		"list_page",
+		"Cursor-paginates a stable creation-ordered Task inventory. Use nextCursor until it is absent. Existing tasks.list remains the lean array convenience API.",
+		"read",
+		listPageSchemaProps,
+		["project_root"],
+		(input) => {
+			const rootTaskId = resolveRootTaskId(artifacts, tasks, input.project_root as string, input.root_task_id, input.root_task_name);
+			return { ...input, ...(rootTaskId ? { root_task_id: rootTaskId } : {}) };
+		},
+	);
+
 	define(
 		"graph",
 		"Returns the full task graph (nodes with parent/child/dependency ids) for the requested scope. project_root is required.",

package/src/index.ts

@@ -8,6 +8,14 @@
 export type { Artifact, ArtifactEdge } from "./artifact/artifact.ts";
 export { projectArtifactRelationships } from "./artifact/artifact-relationship-view.ts";
 export type { ArtifactStore } from "./artifact/artifact-store.ts";
+export {
+	BINDER_FILED_IN_RELATION,
+	BINDER_KIND,
+	BINDER_ORGANIZES_RELATION,
+	type BinderArtifactPlacement,
+	type BinderNode,
+	type BinderTree,
+} from "./binder/binder.ts";
 export {
 	connectPapyrusClient,
 	type PapyrusClient,

package/src/modules/binders.ts

@@ -0,0 +1,171 @@
+import { summarizeArtifact } from "../artifact/artifact.ts";
+import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import type { ArtifactTrashStore } from "../artifact/artifact-trash-store.ts";
+import {
+	addBinderGroup,
+	addBinderProject,
+	binderScope,
+	binderTree,
+	createBinder,
+	fileArtifact,
+	listBinders,
+	moveBinder,
+	removeBinder,
+	removeBinderGroup,
+	removeBinderProject,
+	replaceBinderGroups,
+	replaceBinderProjects,
+	setBinderGlobal,
+	setBinderNone,
+	unfileArtifact,
+	updateBinder,
+} from "../binder/binder-service.ts";
+import type { OperationDefinition } from "../module-registry.ts";
+import type { ProjectRegistryStore } from "../project-registry/project-registry-store.ts";
+import type { ScopeGroupStore } from "../scope-group/scope-group-store.ts";
+import { type OperationInput, optionalBoolean, optionalNumber, optionalString, string } from "./operation-input.ts";
+
+const MODULE_ID = "binders";
+
+const eventContext = (input: OperationInput) => ({
+	actor: optionalString(input, "actor"),
+	source: optionalString(input, "source"),
+	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
+});
+
+const listFilter = (input: OperationInput) => {
+	const projectRoot = optionalString(input, "project_root");
+	const applicable = optionalBoolean(input, "applicable") === true;
+	if (applicable && projectRoot === undefined) throw new Error("applicable requires project_root");
+	return {
+		text: optionalString(input, "text"),
+		limit: optionalNumber(input, "limit"),
+		...(applicable ? { applicableToProjectRoot: projectRoot } : { projectRoot }),
+	};
+};
+
+export const BINDERS_OPERATION_NAMES = [
+	"binders.create",
+	"binders.list",
+	"binders.tree",
+	"binders.show",
+	"binders.update",
+	"binders.move",
+	"binders.file",
+	"binders.unfile",
+	"binders.remove",
+	"binders.scope",
+	"binders.set_global",
+	"binders.set_none",
+	"binders.add_project",
+	"binders.remove_project",
+	"binders.replace_projects",
+	"binders.add_group",
+	"binders.remove_group",
+	"binders.replace_groups",
+] as const;
+
+export function bindersOperations(
+	artifacts: ArtifactStore & ArtifactTrashStore,
+	scopes: ArtifactScopeStore,
+	registry: ProjectRegistryStore,
+	scopeGroups: ScopeGroupStore,
+): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name,
+		moduleId: MODULE_ID,
+		execute,
+	});
+	return [
+		define("binders.create", (input: OperationInput) =>
+			createBinder(
+				artifacts,
+				scopes,
+				{
+					title: string(input, "title"),
+					labels: input.labels as string[] | undefined,
+					parentId: optionalString(input, "parent_id"),
+					projectRoot: optionalString(input, "project_root"),
+					projectReferences: input.projects as string[] | undefined,
+				},
+				eventContext(input),
+				registry,
+			),
+		),
+		define("binders.list", (input: OperationInput) => {
+			const binders = listBinders(artifacts, scopes, listFilter(input));
+			return optionalBoolean(input, "full") === true ? binders : binders.map(summarizeArtifact);
+		}),
+		define("binders.tree", (input: OperationInput) =>
+			binderTree(artifacts, scopes, {
+				projectRoot: optionalString(input, "project_root"),
+				artifactIds: input.artifact_ids as string[] | undefined,
+			}),
+		),
+		define("binders.show", (input: OperationInput) => {
+			const id = string(input, "id");
+			const tree = binderTree(artifacts, scopes, { projectRoot: optionalString(input, "project_root") });
+			const node = tree.nodes.find((candidate) => candidate.binder.id === id);
+			if (!node) throw new Error(`binder artifact "${id}" not found in this project context`);
+			return node;
+		}),
+		define("binders.update", (input: OperationInput) =>
+			updateBinder(
+				artifacts,
+				scopes,
+				string(input, "id"),
+				{ title: optionalString(input, "title"), labels: input.labels as string[] | undefined },
+				optionalString(input, "project_root"),
+				eventContext(input),
+			),
+		),
+		define("binders.move", (input: OperationInput) =>
+			moveBinder(
+				artifacts,
+				scopes,
+				string(input, "id"),
+				optionalString(input, "parent_id"),
+				optionalString(input, "project_root"),
+				eventContext(input),
+			),
+		),
+		define("binders.file", (input: OperationInput) =>
+			fileArtifact(
+				artifacts,
+				scopes,
+				string(input, "artifact_id"),
+				string(input, "binder_id"),
+				optionalString(input, "project_root"),
+				eventContext(input),
+			),
+		),
+		define("binders.unfile", (input: OperationInput) =>
+			unfileArtifact(artifacts, scopes, string(input, "artifact_id"), optionalString(input, "project_root"), eventContext(input)),
+		),
+		define("binders.remove", (input: OperationInput) =>
+			removeBinder(artifacts, string(input, "id"), eventContext(input), optionalString(input, "reason")),
+		),
+		define("binders.scope", (input: OperationInput) => binderScope(artifacts, scopes, string(input, "id"))),
+		define("binders.set_global", (input: OperationInput) => setBinderGlobal(artifacts, scopes, string(input, "id"))),
+		define("binders.set_none", (input: OperationInput) => setBinderNone(artifacts, scopes, string(input, "id"))),
+		define("binders.add_project", (input: OperationInput) =>
+			addBinderProject(artifacts, scopes, registry, string(input, "id"), string(input, "project")),
+		),
+		define("binders.remove_project", (input: OperationInput) =>
+			removeBinderProject(artifacts, scopes, registry, string(input, "id"), string(input, "project")),
+		),
+		define("binders.replace_projects", (input: OperationInput) =>
+			replaceBinderProjects(artifacts, scopes, registry, string(input, "id"), (input.projects as string[] | undefined) ?? []),
+		),
+		define("binders.add_group", (input: OperationInput) =>
+			addBinderGroup(artifacts, scopes, scopeGroups, string(input, "id"), string(input, "group")),
+		),
+		define("binders.remove_group", (input: OperationInput) =>
+			removeBinderGroup(artifacts, scopes, scopeGroups, string(input, "id"), string(input, "group")),
+		),
+		define("binders.replace_groups", (input: OperationInput) =>
+			replaceBinderGroups(artifacts, scopes, scopeGroups, string(input, "id"), (input.groups as string[] | undefined) ?? []),
+		),
+	];
+}

package/src/modules/notes.ts

@@ -24,6 +24,7 @@ const MODULE_ID = "notes";
 export const NOTES_OPERATION_NAMES = [
 	"notes.capture",
 	"notes.list",
+	"notes.list_page",
 	"notes.show",
 	"notes.history",
 	"notes.consume",
@@ -57,6 +58,15 @@ export function notesOperations(notes: Notes): OperationDefinition[] {
 				limit: optionalNumber(input, "limit"),
 			}),
 		),
+		define("notes.list_page", (input: OperationInput) =>
+			notes.listPage({
+				projectRoot: optionalString(input, "project_root"),
+				status: optionalString(input, "status") as "draft" | "active" | "archived" | undefined,
+				text: optionalString(input, "text"),
+				limit: optionalNumber(input, "limit"),
+				cursor: optionalString(input, "cursor"),
+			}),
+		),
 		define("notes.show", (input: OperationInput) => notes.show(string(input, "id"), string(input, "project_root"))),
 		define("notes.history", (input: OperationInput) =>
 			notes.history(string(input, "id"), string(input, "project_root"), {

package/src/modules/tasks.ts

@@ -54,6 +54,7 @@ const taskFilter = (input: OperationInput) => ({
 	rootTaskId: optionalString(input, "root_task_id"),
 	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
 	labels: optionalStringArray(input, "labels"),
+	cursor: optionalString(input, "cursor"),
 });
 
 /**
@@ -69,6 +70,7 @@ export const TASKS_OPERATION_NAMES = [
 	"tasks.create",
 	"tasks.update",
 	"tasks.list",
+	"tasks.list_page",
 	"tasks.graph",
 	"tasks.plan",
 	"tasks.show",
@@ -164,6 +166,13 @@ export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionI
 			const rows = tasks.list(taskFilter(input));
 			return optionalBoolean(input, "full") === true ? rows : rows.map(summarizeArtifact);
 		}),
+		define("tasks.list_page", (input: OperationInput) => {
+			const page = tasks.listPage(taskFilter(input));
+			return {
+				...page,
+				items: optionalBoolean(input, "full") === true ? page.items : page.items.map(summarizeArtifact),
+			};
+		}),
 		define("tasks.graph", (input: OperationInput) => tasks.graph(taskFilter(input))),
 		define("tasks.plan", (input: OperationInput) => projectTaskExecution(tasks.graph(taskFilter(input)))),
 		define("tasks.show", (input: OperationInput) => tasks.show(string(input, "id"))),

package/src/note/note-service.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import type { Artifact } from "../artifact/artifact.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import { requireAtomicArtifactStore } from "../artifact/atomic-artifact-store.ts";
@@ -37,6 +38,27 @@ export interface ListNotesInput {
 	limit?: number;
 }
 
+export interface ListNotesPageInput {
+	/** Omit only for an explicit cross-project inventory. */
+	projectRoot?: string;
+	status?: "draft" | "active" | "archived";
+	text?: string;
+	limit?: number;
+	cursor?: string;
+}
+
+export interface NotesPage {
+	items: Artifact[];
+	nextCursor?: string;
+}
+
+interface NotesPageCursor {
+	v: 1;
+	createdAt: string;
+	id: string;
+	filterHash: string;
+}
+
 export interface ArchiveNoteInput extends NoteProvenance {
 	projectRoot: string;
 	disposition: NoteDisposition;
@@ -54,6 +76,29 @@ function optionalBounded(value: string | undefined, field: string, maximum: numb
 	return requiredBounded(value, field, maximum);
 }
 
+function notesPageFilterHash(input: ListNotesPageInput, projectRoot: string | undefined): string {
+	return createHash("sha256")
+		.update(JSON.stringify({ projectRoot, status: input.status, text: input.text }))
+		.digest("base64url");
+}
+
+function decodeNotesPageCursor(cursor: string | undefined, filterHash: string): NotesPageCursor | undefined {
+	if (cursor === undefined) return undefined;
+	try {
+		const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as Partial<NotesPageCursor>;
+		if (parsed.v !== 1 || !parsed.createdAt || !parsed.id || parsed.filterHash !== filterHash) throw new Error("invalid cursor");
+		return parsed as NotesPageCursor;
+	} catch {
+		throw new Error("notes page cursor is invalid or does not match the requested filters");
+	}
+}
+
+function encodeNotesPageCursor(note: Artifact, filterHash: string): string {
+	return Buffer.from(JSON.stringify({ v: 1, createdAt: note.created_at, id: note.id, filterHash } satisfies NotesPageCursor)).toString(
+		"base64url",
+	);
+}
+
 function noteTitle(body: string, requested?: string): string {
 	if (requested !== undefined) return requiredBounded(requested, "note title", NOTE_TITLE_MAX_CHARACTERS);
 	const firstLine = body.split(/\r?\n/, 1)[0]!.replace(/\s+/g, " ").trim();
@@ -110,6 +155,33 @@ export class Notes {
 		});
 	}
 
+	/** Cursor-paged inventory; omitting projectRoot intentionally enumerates notes across projects. */
+	listPage(input: ListNotesPageInput): NotesPage {
+		const projectRoot =
+			input.projectRoot === undefined ? undefined : requiredBounded(input.projectRoot, "project_root", TASK_PROJECT_ROOT_MAX_LENGTH);
+		const limit = input.limit ?? NOTE_LIST_DEFAULT_LIMIT;
+		if (!Number.isInteger(limit) || limit < 1 || limit > NOTE_LIST_MAX_LIMIT) {
+			throw new Error(`note limit must be an integer from 1 to ${NOTE_LIST_MAX_LIMIT}`);
+		}
+		const filterHash = notesPageFilterHash(input, projectRoot);
+		const cursor = decodeNotesPageCursor(input.cursor, filterHash);
+		const candidates = this.artifacts.query({
+			kind: "doc",
+			subtype: NOTE_SUBTYPE,
+			...(input.status ? { status: input.status } : { statuses: ["draft", "active"] }),
+			...(input.text ? { text: input.text } : {}),
+			...(projectRoot ? { extraEquals: { projectRoot } } : {}),
+			order: "created_desc",
+			...(cursor ? { after: { createdAt: cursor.createdAt, id: cursor.id } } : {}),
+			limit: limit + 1,
+		});
+		const items = candidates.slice(0, limit);
+		return {
+			items,
+			...(candidates.length > limit && items.length > 0 ? { nextCursor: encodeNotesPageCursor(items.at(-1)!, filterHash) } : {}),
+		};
+	}
+
 	show(id: string, projectRoot: string): Artifact {
 		const note = this.requireNote(id);
 		this.requireProject(note, projectRoot);

package/src/ops.ts

@@ -367,8 +367,14 @@ export function queryArtifacts(db: Db, filter: ArtifactQuery): Artifact[] {
 		conditions.push("json_extract(extra, ?) = ?");
 		params.push(`$.${key}`, value);
 	}
+	if (filter.after) {
+		if (filter.order !== "created_desc") throw new Error("artifact query cursor requires created_desc ordering");
+		if (!filter.after.createdAt || !filter.after.id) throw new Error("artifact query cursor is invalid");
+		conditions.push("(created_at < ? OR (created_at = ? AND id > ?))");
+		params.push(filter.after.createdAt, filter.after.createdAt, filter.after.id);
+	}
 	if (conditions.length) sql += ` WHERE ${conditions.join(" AND ")}`;
-	sql += " ORDER BY updated_at DESC";
+	sql += filter.order === "created_desc" ? " ORDER BY created_at DESC, id ASC" : " ORDER BY updated_at DESC, id ASC";
 	if (filter.limit !== undefined) {
 		if (!Number.isInteger(filter.limit) || filter.limit < 1) throw new Error("artifact query limit must be a positive integer");
 		sql += " LIMIT ?";