@danypops/papyrus 0.45.3 → 0.46.0

package/README.md

@@ -23,6 +23,10 @@ papyrus tasks pause
 papyrus tasks unpause
 papyrus tasks complete <task-id>
 
+# Resolve a human project name safely before scoped operations
+papyrus tasks projects --query lector --json
+papyrus tasks resolve-project Lector --json
+
 # Deferred human-intent inbox
 papyrus notes capture "Review release provenance later"
 papyrus notes list --json
@@ -38,6 +42,12 @@ It blocks every Papyrus push whose destination is not `DanyPops/papyrus`, includ
 
 The daemon uses WAL, foreign keys, a bounded busy timeout, versioned migrations, periodic passive checkpoints, and periodic `PRAGMA optimize`. Keep the database on a local filesystem; SQLite WAL does not support network filesystems.
 
+Task project names are explicit registrations, never ambient-directory guesses. `tasks.projects` searches bounded registered identities; `tasks.resolve_project` requires one case-insensitive exact id, name, alias, or canonical root and fails on unknown or ambiguous references. Pass its returned `projectRoot` as `project_root` to subsequent task operations. `tasks.register_project` can rename or move an existing identity while preserving its stable id and prior name as an alias.
+
+`tasks.create` accepts an optional `idempotency_key`. Replays with the same caller, canonical project root, key, and payload return the original response without another mutation; conflicting payload reuse is rejected. Keys are retained for seven days, isolated across callers and projects, and then expire. Retry only when reusing the exact key and payload; an unkeyed create remains unsafe to replay after an ambiguous transport failure.
+
+Task lease responses are name-first: `tasks.claim`, `tasks.heartbeat_lease`, and `tasks.lease` return the reusable artifact alias as `taskName` plus `taskTitle`, not the backend UUID. Use `taskName` for later Task operations; retain the lease token for heartbeat or release.
+
 ### Context Mesh persistence model
 
 `artifacts` is the shared graph-identity supertype, not a second copy of every application's database. `edges` references that single identity table at both endpoints, preserving foreign-key integrity for cross-domain links. Domain extension tables exist only where application invariants require indexed relational state: Task chronology/focus/scope and Discourse posts/events/session cursors/projection checkpoints. This is a class-table/table-per-type variant with explicit child-to-parent foreign keys; Papyrus does not use SQLite table inheritance or orphan-prone `(target_type, target_id)` links.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.45.3",
+  "version": "0.46.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/authority-registry.ts

@@ -4,7 +4,8 @@
  *
  * Subtype/relation ownership guards (isDiscourseSubtype, NOTE_SUBTYPE, task-kind checks)
  * were previously re-implemented at every write call site across src/service.ts and
- * src/domain-services.ts. This is the one deep enforcement point: a claim expresses
+ * src/docs/docs-service.ts, src/rules/rules-service.ts, src/playbook/playbook-service.ts
+ * (formerly one combined src/domain-services.ts). This is the one deep enforcement point: a claim expresses
  * which module owns which artifact kind/subtype or relation and what message a
  * non-owner gets for a given action; AuthorizedArtifactWriter enforces claims for the
  * mechanical link/unlink/status paths where the target artifact's persisted kind/subtype

package/src/cli/task-command.ts

@@ -18,7 +18,8 @@ interface TaskContext extends CommandContext {
 }
 
 type CliTaskLease = {
-	taskId: string;
+	taskName: string;
+	taskTitle: string;
 	owner: string;
 	token: string;
 	claimedAt: string;
@@ -195,7 +196,11 @@ const claimCommand = buildCommand({
 			ttl_ms: flags.ttlMs,
 			note: flags.note,
 		});
-		render.call(this, lease, `Claimed by "${lease.owner}" until ${lease.leaseExpiresAt} (token ${lease.token}).`);
+		render.call(
+			this,
+			lease,
+			`Claimed ${lease.taskName} (${lease.taskTitle}) by "${lease.owner}" until ${lease.leaseExpiresAt} (token ${lease.token}).`,
+		);
 	},
 	parameters: {
 		flags: {
@@ -216,7 +221,7 @@ const heartbeatLeaseCommand = buildCommand({
 			token: flags.token,
 			ttl_ms: flags.ttlMs,
 		});
-		render.call(this, lease, `Renewed until ${lease.leaseExpiresAt}.`);
+		render.call(this, lease, `Renewed ${lease.taskName} (${lease.taskTitle}) until ${lease.leaseExpiresAt}.`);
 	},
 	parameters: {
 		flags: {
@@ -251,7 +256,11 @@ const releaseLeaseCommand = buildCommand({
 const leaseCommand = buildCommand({
 	func: async function (this: TaskContext, _flags: Record<string, never>, id: string) {
 		const lease = await this.client.call<Record<string, unknown>, CliTaskLease | null>("tasks.lease", { id });
-		render.call(this, lease, lease ? `Leased by "${lease.owner}" until ${lease.leaseExpiresAt}.` : "No live lease.");
+		render.call(
+			this,
+			lease,
+			lease ? `${lease.taskName} (${lease.taskTitle}) is leased by "${lease.owner}" until ${lease.leaseExpiresAt}.` : "No live lease.",
+		);
 	},
 	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Task id", parse: String, placeholder: "id" }] } },
 	docs: { brief: "Show this Task's current lease" },
@@ -314,6 +323,7 @@ const createCommand = buildCommand({
 			templateId?: string;
 			parentId?: string;
 			dependsOnJson?: string[];
+			idempotencyKey?: string;
 			sessionId?: string;
 		},
 	) {
@@ -329,6 +339,7 @@ const createCommand = buildCommand({
 			parent_id: flags.parentId,
 			depends_on: flags.dependsOnJson,
 			project_root: this.projectRoot,
+			idempotency_key: flags.idempotencyKey,
 			actor: "user",
 			source: "cli",
 			session_id: flags.sessionId,
@@ -353,6 +364,13 @@ const createCommand = buildCommand({
 				placeholder: "json",
 				optional: true,
 			},
+			idempotencyKey: {
+				brief: "Retry key for an exact create payload",
+				kind: "parsed",
+				parse: String,
+				placeholder: "key",
+				optional: true,
+			},
 			sessionId: {
 				brief: "Attribute this creation to one agent session",
 				kind: "parsed",
@@ -595,6 +613,70 @@ const historyCommand = buildCommand({
 	docs: { brief: "Task's append-only lifecycle event history" },
 });
 
+const projectsCommand = buildCommand({
+	func: async function (this: TaskContext, flags: { query?: string; limit?: number }) {
+		const projects = await this.client.call<Record<string, unknown>, Array<{ name: string; projectRoot: string }>>("tasks.projects", {
+			query: flags.query,
+			limit: flags.limit,
+		});
+		render.call(
+			this,
+			projects,
+			projects.length === 0
+				? "No registered task projects."
+				: projects.map((project) => `${project.name} — ${project.projectRoot}`).join("\n"),
+		);
+	},
+	parameters: {
+		flags: {
+			query: { brief: "Filter by project name, alias, or root", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			limit: { brief: "Maximum results", kind: "parsed", parse: numberParser, placeholder: "n", optional: true },
+		},
+	},
+	docs: { brief: "List registered Task project scopes" },
+});
+
+const resolveProjectCommand = buildCommand({
+	func: async function (this: TaskContext, _flags: Record<string, never>, name: string) {
+		const project = await this.client.call<Record<string, unknown>, { name: string; projectRoot: string }>("tasks.resolve_project", {
+			name,
+		});
+		render.call(this, project, `${project.name} — ${project.projectRoot}`);
+	},
+	parameters: {
+		flags: {},
+		positional: { kind: "tuple", parameters: [{ brief: "Project name, alias, id, or root", parse: String, placeholder: "name" }] },
+	},
+	docs: { brief: "Resolve a project reference to its canonical root" },
+});
+
+const registerProjectCommand = buildCommand({
+	func: async function (this: TaskContext, flags: { name?: string; aliasesJson?: string[]; project?: string }, projectRoot: string) {
+		const registered = await this.client.call<Record<string, unknown>, { name: string; projectRoot: string }>("tasks.register_project", {
+			project_root: projectRoot,
+			name: flags.name,
+			aliases: flags.aliasesJson,
+			project: flags.project,
+		});
+		render.call(this, registered, `${registered.name} — ${registered.projectRoot}`);
+	},
+	parameters: {
+		flags: {
+			name: { brief: "Stable project display name", kind: "parsed", parse: String, placeholder: "name", optional: true },
+			aliasesJson: { brief: "JSON string array of aliases", kind: "parsed", parse: parseStringArray, placeholder: "json", optional: true },
+			project: {
+				brief: "Existing project reference when renaming or moving",
+				kind: "parsed",
+				parse: String,
+				placeholder: "reference",
+				optional: true,
+			},
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Canonical absolute project root", parse: String, placeholder: "project-root" }] },
+	},
+	docs: { brief: "Register, rename, or move a Task project" },
+});
+
 const scopeCommand = buildCommand({
 	func: async function (this: TaskContext, _flags: Record<string, never>, mode?: string, rootTaskId?: string) {
 		if (mode === undefined) {
@@ -857,6 +939,9 @@ const app = buildApplication(
 			),
 			update: updateCommand,
 			history: historyCommand,
+			projects: projectsCommand,
+			"resolve-project": resolveProjectCommand,
+			"register-project": registerProjectCommand,
 			scope: scopeCommand,
 			"assign-project": assignProjectCommand,
 			focus: focusCommand,

package/src/constants.ts

@@ -9,7 +9,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 24;
+export const SQLITE_SCHEMA_VERSION = 26;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -262,6 +262,11 @@ export const TASK_SCOPE_MAX_TASKS = 1_000;
 /** Docs/Rules/Skills project scope listing bound, mirroring TASK_SCOPE_MAX_TASKS. */
 export const ARTIFACT_SCOPE_MAX_ARTIFACTS = 1_000;
 export const TASK_PROJECT_ROOT_MAX_LENGTH = 4_096;
+export const TASK_PROJECT_NAME_MAX_LENGTH = 200;
+export const TASK_PROJECT_ALIAS_MAX_COUNT = 20;
+export const TASK_PROJECT_LIST_MAX_RESULTS = 100;
+export const TASK_CREATE_IDEMPOTENCY_KEY_MAX_LENGTH = 200;
+export const TASK_CREATE_IDEMPOTENCY_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 export const GRAPH_RENDER_PADDING_X = 2;
 export const GRAPH_RENDER_PADDING_Y = 1;
 export const GRAPH_RENDER_BOX_PADDING = 0;

package/src/db.ts

@@ -1,6 +1,7 @@
+import { randomUUID } from "node:crypto";
 import { mkdirSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname } from "node:path";
+import { basename, dirname } from "node:path";
 import { runMigrations, type SqliteMigrationRunner } from "@danypops/vehicle-server/storage";
 import { generateUniqueAlias, slugify } from "./artifact/artifact-alias.ts";
 import { SQLITE_BUSY_TIMEOUT_MS, SQLITE_SCHEMA_VERSION } from "./constants.ts";
@@ -156,6 +157,25 @@ CREATE TABLE IF NOT EXISTS task_views (
 	updated_at    TEXT NOT NULL,
 	CHECK ((mode = 'graph' AND root_task_id IS NOT NULL) OR (mode != 'graph' AND root_task_id IS NULL))
 );
+CREATE TABLE IF NOT EXISTS task_projects (
+	id            TEXT PRIMARY KEY,
+	name          TEXT NOT NULL,
+	aliases_json  TEXT NOT NULL DEFAULT '[]',
+	project_root  TEXT NOT NULL UNIQUE,
+	created_at    TEXT NOT NULL,
+	updated_at    TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS task_projects_name_idx ON task_projects(name);
+CREATE TABLE IF NOT EXISTS task_create_requests (
+	request_scope   TEXT NOT NULL,
+	idempotency_key TEXT NOT NULL,
+	request_hash    TEXT NOT NULL,
+	response_json   TEXT NOT NULL,
+	created_at      TEXT NOT NULL,
+	expires_at      TEXT NOT NULL,
+	PRIMARY KEY (request_scope, idempotency_key)
+);
+CREATE INDEX IF NOT EXISTS task_create_requests_expiry_idx ON task_create_requests(expires_at);
 CREATE TABLE IF NOT EXISTS artifact_events (
 	id                   INTEGER PRIMARY KEY AUTOINCREMENT,
 	artifact_id          TEXT NOT NULL REFERENCES artifacts(id),
@@ -298,6 +318,7 @@ INSERT OR IGNORE INTO statuses VALUES ('review','task');
 INSERT OR IGNORE INTO statuses VALUES ('rejected','task');
 INSERT OR IGNORE INTO statuses VALUES ('done','task');
 INSERT OR IGNORE INTO statuses VALUES ('canceled','task');
+INSERT OR IGNORE INTO statuses VALUES ('draft','rule');
 INSERT OR IGNORE INTO statuses VALUES ('active','rule');
 INSERT OR IGNORE INTO statuses VALUES ('deprecated','rule');
 INSERT OR IGNORE INTO statuses VALUES ('active','playbook');
@@ -732,6 +753,52 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			db.exec("CREATE UNIQUE INDEX IF NOT EXISTS artifacts_alias_idx ON artifacts(alias)");
 		},
 	},
+	{
+		version: 25,
+		name: "rule-draft-status",
+		up: (db) => {
+			db.exec("INSERT OR IGNORE INTO statuses SELECT 'draft','rule' WHERE EXISTS (SELECT 1 FROM kinds WHERE name = 'rule')");
+		},
+	},
+	{
+		version: 26,
+		name: "task-projects-and-create-idempotency",
+		up: (db) => {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS task_projects (
+					id            TEXT PRIMARY KEY,
+					name          TEXT NOT NULL,
+					aliases_json  TEXT NOT NULL DEFAULT '[]',
+					project_root  TEXT NOT NULL UNIQUE,
+					created_at    TEXT NOT NULL,
+					updated_at    TEXT NOT NULL
+				);
+				CREATE INDEX IF NOT EXISTS task_projects_name_idx ON task_projects(name);
+				CREATE TABLE IF NOT EXISTS task_create_requests (
+					request_scope   TEXT NOT NULL,
+					idempotency_key TEXT NOT NULL,
+					request_hash    TEXT NOT NULL,
+					response_json   TEXT NOT NULL,
+					created_at      TEXT NOT NULL,
+					expires_at      TEXT NOT NULL,
+					PRIMARY KEY (request_scope, idempotency_key)
+				);
+				CREATE INDEX IF NOT EXISTS task_create_requests_expiry_idx ON task_create_requests(expires_at);
+			`);
+			const roots = db
+				.prepare("SELECT DISTINCT project_root FROM task_scopes WHERE project_root IS NOT NULL ORDER BY project_root")
+				.all() as Array<{
+				project_root: string;
+			}>;
+			const insert = db.prepare(
+				"INSERT OR IGNORE INTO task_projects (id, name, aliases_json, project_root, created_at, updated_at) VALUES (?, ?, '[]', ?, ?, ?)",
+			);
+			for (const row of roots) {
+				const now = new Date().toISOString();
+				insert.run(randomUUID(), basename(row.project_root) || row.project_root, row.project_root, now, now);
+			}
+		},
+	},
 ];
 
 /**

package/src/docs/docs-service.ts

@@ -0,0 +1,192 @@
+/**
+ * Doc domain composition logic (create/list/show/transition/update/link), split out of the
+ * former domain-services.ts into its own per-domain file alongside rules/rules-service.ts and
+ * playbook/playbook-service.ts. Shared, kind-agnostic helpers live in ../domain-service-shared.ts.
+ */
+
+import { type Artifact, requireLocallyOwnedContent } from "../artifact/artifact.ts";
+import type { ArtifactEventContext } from "../artifact/artifact-event.ts";
+import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import type { ArtifactAction, AuthorityRegistry } from "../authority-registry.ts";
+import { normalizeProjectRoot } from "../domain/task-scope.ts";
+import {
+	assertBodyBounds,
+	assertLabelsBounds,
+	assertTitleBounds,
+	type ListFilter,
+	listScoped,
+	requireContentUpdateFields,
+	requireKind,
+	runTransition,
+	type TransitionTable,
+	type UpdateContentInput,
+} from "../domain-service-shared.ts";
+import { NOTE_SUBTYPE } from "../note/note-service.ts";
+
+function rejectsNoteTemplate(artifacts: ArtifactStore, templateId: string | undefined, subtype: string | undefined): boolean {
+	if (subtype === NOTE_SUBTYPE) return true;
+	if (!templateId) return false;
+	const template = artifacts.get(templateId);
+	const defaults = template?.extra.defaults;
+	return (
+		typeof defaults === "object" &&
+		defaults !== null &&
+		!Array.isArray(defaults) &&
+		(defaults as Record<string, unknown>).subtype === NOTE_SUBTYPE
+	);
+}
+
+/** caller never owns NOTE_SUBTYPE, so requireArtifactAllowed always throws — the trailing throw only satisfies TypeScript's control-flow analysis for a `never`-returning function. */
+function requireNotesFacade(authority: AuthorityRegistry, caller: string): never {
+	authority.requireArtifactAllowed("doc", NOTE_SUBTYPE, "create", caller);
+	throw new Error("note creation requires notes.capture");
+}
+
+function templateSubtype(artifacts: ArtifactStore, templateId: string | undefined): string | undefined {
+	if (!templateId) return undefined;
+	const defaults = artifacts.get(templateId)?.extra.defaults;
+	if (typeof defaults !== "object" || defaults === null || Array.isArray(defaults)) return undefined;
+	const subtype = (defaults as Record<string, unknown>).subtype;
+	return typeof subtype === "string" ? subtype : undefined;
+}
+
+// No default action: linkDocument's own bug (both target and source checks silently defaulting to
+// "status" here) was exactly what let a plain reference edge to a Task trip the tasks.* lifecycle
+// guard, which is scoped to actual status changes only. Every call site now names its real action.
+function requireMutableDocument(document: Artifact, authority: AuthorityRegistry, action: ArtifactAction): Artifact {
+	authority.requireArtifactAllowed(document.kind, document.subtype, action, "docs");
+	return document;
+}
+
+export interface CreateDocumentInput {
+	title: string;
+	body?: string;
+	subtype?: string;
+	labels?: string[];
+	extra?: Record<string, unknown>;
+	templateId?: string;
+	/** Optional at creation, unlike Tasks -- omitting it leaves the Doc in the unscoped bucket, matching today's default behavior for every existing caller. */
+	projectRoot?: string;
+}
+
+export type UpdateDocumentInput = UpdateContentInput;
+
+export type DocumentTransition = "activate" | "archive" | "reopen";
+export type DocumentRelation = "references" | "documents" | "supersedes" | "relates_to" | "contains" | "part_of";
+
+const DOCUMENT_TRANSITIONS: TransitionTable<DocumentTransition, string> = {
+	activate: { from: ["draft"], to: "active" },
+	archive: { from: ["draft", "active"], to: "archived" },
+	reopen: { from: ["archived"], to: "draft" },
+};
+
+export function createDocument(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	input: CreateDocumentInput,
+	authority: AuthorityRegistry,
+	context?: ArtifactEventContext,
+): Artifact {
+	if (rejectsNoteTemplate(artifacts, input.templateId, input.subtype)) requireNotesFacade(authority, "docs");
+	authority.requireArtifactAllowed("doc", input.subtype ?? templateSubtype(artifacts, input.templateId), "create", "docs");
+	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const document = artifacts.create(
+		{
+			kind: "doc",
+			// Explicit, not defaultStatusFor's "first status row by rowid" fallback -- the same
+			// heuristic that made Task creation non-deterministic on a migrated database. Every
+			// creation path that has no caller-supplied initial status must set one explicitly.
+			status: "draft",
+			title: input.title,
+			body: input.body,
+			subtype: input.subtype,
+			labels: input.labels,
+			extra: input.extra,
+			templateId: input.templateId,
+		},
+		context,
+	);
+	scopes.assign(document.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	return document;
+}
+
+export function listDocuments(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
+	return listScoped(artifacts, scopes, "doc", filter, NOTE_SUBTYPE);
+}
+
+export function assignDocumentProject(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	id: string,
+	projectRoot: string | undefined,
+): Artifact {
+	requireDocument(artifacts, id); // rejects Notes -- project reassignment for notes goes through notes.* like everything else about them
+	scopes.assign(
+		id,
+		projectRoot === undefined ? undefined : normalizeProjectRoot(projectRoot),
+		projectRoot === undefined ? "unscoped" : "explicit",
+	);
+	return artifacts.get(id)!;
+}
+
+function requireDocument(artifacts: ArtifactStore, id: string): Artifact {
+	const document = requireKind(artifacts, id, "doc");
+	if (document.subtype === NOTE_SUBTYPE) throw new Error("note access requires a notes.* operation");
+	return document;
+}
+
+export function showDocument(artifacts: ArtifactStore, id: string): Artifact {
+	requireDocument(artifacts, id);
+	return artifacts.get(id, { tree: true })!;
+}
+
+export function transitionDocument(
+	artifacts: ArtifactStore,
+	id: string,
+	action: DocumentTransition,
+	authority: AuthorityRegistry,
+	context?: ArtifactEventContext,
+): Artifact {
+	const document = requireLocallyOwnedContent(requireMutableDocument(requireDocument(artifacts, id), authority, "status"));
+	return runTransition(artifacts, document, "doc", action, DOCUMENT_TRANSITIONS, context);
+}
+
+/**
+ * Docs are immutable-by-convention only in the sense that no path existed to change them --
+ * this is that path. A read-only external projection (see requireLocallyOwnedContent) still
+ * refuses, on purpose: rewriting it here would silently fork from whatever system actually
+ * owns it (e.g. web-spider's ingested pages), with nothing to ever reconcile the two again.
+ */
+export function updateDocument(
+	artifacts: ArtifactStore,
+	id: string,
+	input: UpdateDocumentInput,
+	authority: AuthorityRegistry,
+	context?: ArtifactEventContext,
+): Artifact {
+	requireContentUpdateFields(input);
+	assertTitleBounds(input.title);
+	assertBodyBounds(input.body);
+	assertLabelsBounds(input.labels);
+	const _document = requireLocallyOwnedContent(requireMutableDocument(requireDocument(artifacts, id), authority, "update"));
+	const updated = artifacts.updateContent(id, input, context);
+	if (!updated) throw new Error(`document "${id}" not found`);
+	return updated;
+}
+
+export function linkDocument(
+	artifacts: ArtifactStore,
+	id: string,
+	relation: DocumentRelation,
+	targetId: string,
+	authority: AuthorityRegistry,
+	context?: ArtifactEventContext,
+): Artifact {
+	requireLocallyOwnedContent(requireMutableDocument(requireDocument(artifacts, id), authority, "link"));
+	const target = artifacts.get(targetId);
+	if (!target) throw new Error(`target artifact "${targetId}" not found`);
+	requireLocallyOwnedContent(requireMutableDocument(target, authority, "link"));
+	artifacts.link({ from: id, relation, to: targetId }, context);
+	return showDocument(artifacts, id);
+}

package/src/domain/task-lease.ts

@@ -16,6 +16,12 @@ export interface TaskLease {
 	note?: string;
 }
 
+/** Name-first operation response. The UUID remains an internal lease-store key. */
+export interface TaskLeaseView extends Omit<TaskLease, "taskId"> {
+	taskName: string;
+	taskTitle: string;
+}
+
 export function validateLeaseOwner(owner: string): string {
 	if (owner.length === 0 || owner.length > TASK_LEASE_OWNER_MAX_LENGTH) {
 		throw new Error(`lease owner must be between 1 and ${TASK_LEASE_OWNER_MAX_LENGTH} characters`);

package/src/domain/task-scope.ts

@@ -10,6 +10,22 @@ export interface TaskProjectScope {
 	source: TaskScopeSource;
 }
 
+export interface TaskProject {
+	id: string;
+	name: string;
+	aliases: string[];
+	projectRoot: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface RegisterTaskProjectInput {
+	projectRoot: string;
+	name?: string;
+	aliases?: string[];
+	existingId?: string;
+}
+
 export interface TaskViewPreference {
 	projectRoot: string;
 	mode: TaskViewMode;