synomem 0.1.1 → 0.3.0

package/dist/client.js

@@ -4,8 +4,8 @@ import { ulid } from 'ulid';
 import { resolveHome } from './config.js';
 import { asSynomemError, SynomemError } from './errors.js';
 import { assertNoSymlinkEscape } from './fs-utils.js';
-import { escapeMarkdown, memoRecordsFromEvents, noteRecordsFromEvents, ProjectionManager, recordsFromEvents, todoRecordsFromEvents, } from './projections.js';
-import { actorSchema, agentIdSchema, createAgentSchema, createNoteSchema, createTodoSchema, changesInputSchema, giveKudosSchema, itemListInputSchema, listInputSchema, reviseNoteSchema, sendMemoSchema, updateTodoSchema, updateAgentSchema, } from './schemas.js';
+import { escapeMarkdown, memoRecordsFromEvents, noteRecordsFromEvents, postRecordsFromEvents, ProjectionManager, recordsFromEvents, taskRecordsFromEvents, todoRecordsFromEvents, } from './projections.js';
+import { actorSchema, agentLookupSchema, bindRuntimeSchema, createAgentSchema, createPostSchema, updatePostSchema, createNoteSchema, createTaskSchema, createTodoSchema, changesInputSchema, giveKudosSchema, itemListInputSchema, listInputSchema, reviseNoteSchema, sendMemoSchema, updateTaskSchema, updateTodoSchema, updateAgentSchema, } from './schemas.js';
 import { SynomemStorage } from './storage.js';
 export class SynomemCore {
     actor;
@@ -21,6 +21,11 @@ export class SynomemCore {
         update: (id, changes) => this.updateAgent(id, changes),
         get: (idOrAlias) => this.getAgent(idOrAlias),
         list: () => this.listAgents(),
+        resolve: (query) => this.resolveAgent(query),
+        directory: () => this.agentDirectory(),
+        bindings: (idOrAlias) => this.listRuntimeBindings(idOrAlias),
+        bindRuntime: (input) => this.bindRuntime(input),
+        unbindRuntime: (bindingId) => this.unbindRuntime(bindingId),
     };
     kudos = {
         give: (input) => this.giveKudos(input),
@@ -37,6 +42,22 @@ export class SynomemCore {
         read: (input) => this.readMemo(input),
         archive: (input) => this.archiveMemo(input),
     };
+    posts = {
+        create: (input) => this.createPost(input),
+        list: (input = {}) => this.listItems({ ...input, kinds: ['post'] }),
+        get: (id) => this.getPost(id),
+        update: (input) => this.updatePost(input),
+        archive: (input) => this.archivePost(input),
+        /*
+         * Acknowledging is an explicit call and always speaks for the caller alone.
+         * There is no bulk form and no acknowledge-on-behalf-of: an acknowledgement
+         * is one actor saying "I have seen this", and reading a post must never
+         * append one, or the roster stops meaning anything.
+         */
+        acknowledge: (input) => this.acknowledgePost(input),
+        withdrawAcknowledgment: (input) => this.withdrawPostAcknowledgment(input),
+        roster: (postId) => this.postRoster(postId),
+    };
     notes = {
         create: (input) => this.createNote(input),
         list: (input = {}) => this.listItems({ ...input, kinds: ['note'] }),
@@ -44,16 +65,59 @@ export class SynomemCore {
         revise: (input) => this.reviseNote(input),
         archive: (input) => this.archiveNote(input),
     };
+    tasks = {
+        create: (input) => this.createTask(input),
+        list: (input = {}) => this.listItems({ ...input, kinds: ['task'] }),
+        get: (id) => this.getTask(id),
+        update: (input) => this.updateTask(input),
+        // A response is optional when accepting and required when rejecting: a
+        // refusal without a reason leaves the assigner unable to act on it.
+        accept: (input) => this.acceptTask(input),
+        reject: (input) => this.rejectTask(input),
+        complete: (input) => this.completeTask(input),
+        reopen: (input) => this.reopenTask(input),
+        cancel: (input) => this.cancelTask(input),
+    };
     todos = {
         create: (input) => this.createTodo(input),
         list: (input = {}) => this.listItems({ ...input, kinds: ['todo'] }),
         get: (id) => this.getTodo(id),
         update: (input) => this.updateTodo(input),
-        accept: (input) => this.acceptTodo(input),
-        reject: (input) => this.rejectTodo(input),
-        complete: (input) => this.completeTodo(input),
-        reopen: (input) => this.reopenTodo(input),
-        cancel: (input) => this.cancelTodo(input),
+        complete: (input) => this.todoTransition(input, 'todo.completed'),
+        reopen: (input) => this.todoTransition(input, 'todo.reopened'),
+        cancel: (input) => this.todoTransition(input, 'todo.canceled'),
+        archive: (input) => this.todoTransition(input, 'todo.archived'),
+    };
+    /**
+     * Unanswered and overdue discovery.
+     *
+     * The plan asks for shared work to be observable without treating runtime
+     * metadata as a delivery guarantee. These are query states derived from
+     * durable events: they say nobody has answered yet, not that the agent was
+     * offline, missed a notification, or lacks a capability it claimed.
+     */
+    discovery = {
+        /**
+         * Tasks awaiting acceptance, unread memos, and unacknowledged kudos —
+         * optionally only those older than a given age or instant.
+         */
+        unanswered: (input = {}) => {
+            const { olderThanHours, awaitingSince, ...rest } = input;
+            const since = awaitingSince ??
+                (olderThanHours !== undefined
+                    ? new Date(Date.now() - olderThanHours * 3_600_000).toISOString()
+                    : undefined);
+            return this.listItems({
+                ...rest,
+                awaitingResponse: true,
+                ...(since ? { awaitingSince: since } : {}),
+            });
+        },
+        /** Open work whose deadline has passed. Defaults to "now". */
+        overdue: (input = {}) => {
+            const { asOf, ...rest } = input;
+            return this.listItems({ ...rest, overdueAsOf: asOf ?? new Date().toISOString() });
+        },
     };
     items = {
         list: (input = {}) => this.listItems(input),
@@ -152,7 +216,7 @@ export class SynomemCore {
     async updateAgent(idOrAlias, changes) {
         this.checkAbort();
         await this.repository.assertEventCompatibility();
-        this.validate(() => agentIdSchema.parse(idOrAlias));
+        this.validate(() => agentLookupSchema.parse(idOrAlias));
         const parsed = this.validate(() => updateAgentSchema.parse(changes));
         const existing = await this.repository.getAgent(idOrAlias);
         if (!existing)
@@ -188,7 +252,7 @@ export class SynomemCore {
     }
     async getAgent(idOrAlias) {
         this.checkAbort();
-        this.validate(() => agentIdSchema.parse(idOrAlias));
+        this.validate(() => agentLookupSchema.parse(idOrAlias));
         const profile = await this.repository.getAgent(idOrAlias);
         if (!profile)
             throw new SynomemError('AGENT_NOT_FOUND', `Unknown agent: ${idOrAlias}`);
@@ -198,6 +262,71 @@ export class SynomemCore {
         this.checkAbort();
         return await this.repository.listAgents();
     }
+    /**
+     * Resolves a name without ever choosing between equally valid answers.
+     *
+     * Callers that want a single agent should treat an empty `match` as a
+     * question for the user, not as "not found": `candidates` distinguishes the
+     * two cases.
+     */
+    async resolveAgent(query) {
+        this.checkAbort();
+        const trimmed = query.trim();
+        if (!trimmed)
+            throw new SynomemError('INVALID_INPUT', 'A lookup name is required.');
+        const resolved = await this.repository.resolveAgent(trimmed);
+        return {
+            query: trimmed,
+            ...(resolved.match ? { match: resolved.match } : {}),
+            candidates: resolved.candidates,
+        };
+    }
+    async agentDirectory() {
+        this.checkAbort();
+        const profiles = await this.repository.listAgents();
+        const entries = [];
+        for (const profile of profiles) {
+            entries.push({
+                profile,
+                runtimeBindings: await this.repository.listRuntimeBindings(profile.id),
+            });
+        }
+        return entries;
+    }
+    async listRuntimeBindings(idOrAlias) {
+        const profile = await this.getAgent(idOrAlias);
+        return await this.repository.listRuntimeBindings(profile.id);
+    }
+    /**
+     * Records where an agent runs. Re-binding the same runtime and profile
+     * updates the claim in place rather than accumulating duplicates, because a
+     * reinstall is the same agent in the same place, not a second one.
+     */
+    async bindRuntime(input) {
+        this.checkAbort();
+        const parsed = this.validate(() => bindRuntimeSchema.parse(input));
+        const profile = await this.getAgent(parsed.agentId);
+        await this.repository.bindRuntime({
+            id: this.idGenerator(),
+            agentId: profile.id,
+            ...(parsed.installationId !== undefined ? { installationId: parsed.installationId } : {}),
+            runtime: parsed.runtime,
+            ...(parsed.profile !== undefined ? { profile: parsed.profile } : {}),
+            ...(parsed.capabilities !== undefined ? { capabilities: parsed.capabilities } : {}),
+            boundAt: this.now(),
+        });
+        const bindings = await this.repository.listRuntimeBindings(profile.id);
+        const binding = bindings.find((candidate) => candidate.runtime === parsed.runtime &&
+            (candidate.profile ?? '') === (parsed.profile ?? '') &&
+            (candidate.installationId ?? '') === (parsed.installationId ?? ''));
+        if (!binding)
+            throw new SynomemError('INTERNAL_ERROR', 'Runtime binding was not persisted.');
+        return binding;
+    }
+    async unbindRuntime(bindingId) {
+        this.checkAbort();
+        return await this.repository.unbindRuntime(bindingId);
+    }
     async giveKudos(input) {
         this.checkAbort();
         await this.repository.assertEventCompatibility();
@@ -351,7 +480,7 @@ export class SynomemCore {
                 ? 'MEMO_NOT_FOUND'
                 : kind === 'note'
                     ? 'NOTE_NOT_FOUND'
-                    : kind === 'todo'
+                    : kind === 'task'
                         ? 'TODO_NOT_FOUND'
                         : 'KUDOS_NOT_FOUND';
             throw new SynomemError(code, `Unknown ${kind}: ${id}`);
@@ -456,6 +585,146 @@ export class SynomemCore {
         await this.projectionWriter.syncAgent(record.event.recipientAgentId);
         return await this.getMemoRecord(input.memoId);
     }
+    async getPostRecord(id) {
+        await this.requireVisibleItem(id, 'post');
+        const record = postRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
+        if (!record)
+            throw new SynomemError('ITEM_NOT_FOUND', `Unknown post: ${id}`);
+        return record;
+    }
+    async getPost(id) {
+        this.checkAbort();
+        return await this.getPostRecord(id);
+    }
+    async createPost(input) {
+        this.checkAbort();
+        await this.repository.assertEventCompatibility();
+        const parsed = this.validate(() => createPostSchema.parse(input));
+        // A reply inherits its parent's workspace by construction, and cannot name
+        // a different target — there is no target to name.
+        if (parsed.replyTo)
+            await this.requireVisibleItem(parsed.replyTo, 'post');
+        const outcome = await this.repository.transaction(async () => {
+            const prior = await this.priorMutation(parsed.idempotencyKey, 'post.created');
+            if (prior?.type === 'post.created')
+                return { id: prior.id, created: false };
+            const id = this.nextId();
+            const event = {
+                ...this.eventBase(id, 1, id),
+                type: 'post.created',
+                title: parsed.title,
+                body: parsed.body,
+                tags: [...new Set(parsed.tags ?? [])].sort(),
+                ...(parsed.replyTo ? { replyTo: parsed.replyTo } : {}),
+                ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
+                ...(parsed.source ? { source: parsed.source } : {}),
+                ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
+            };
+            await this.repository.insertEvent(event);
+            return { id, created: true };
+        });
+        return {
+            record: await this.getPostRecord(outcome.id),
+            created: outcome.created,
+            deduplicated: !outcome.created,
+        };
+    }
+    /** Only the author edits a post. Everyone else responds to it. */
+    assertPostAuthor(record) {
+        if (this.administrative)
+            return;
+        if (record.event.actor.id !== this.actor.id || record.event.actor.kind !== this.actor.kind) {
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the author can change a post.');
+        }
+    }
+    async updatePost(input) {
+        this.checkAbort();
+        const parsed = this.validate(() => updatePostSchema.parse(input));
+        const record = await this.getPostRecord(parsed.postId);
+        this.assertPostAuthor(record);
+        if (record.status === 'archived') {
+            throw new SynomemError('MUTATION_FORBIDDEN', 'An archived post cannot be edited.');
+        }
+        if (record.version !== parsed.expectedVersion) {
+            throw new SynomemError('REVISION_CONFLICT', `Post ${parsed.postId} is at version ${record.version}.`);
+        }
+        await this.repository.transaction(async () => {
+            const event = {
+                ...this.eventBase(parsed.postId, await this.repository.nextAggregateVersion(parsed.postId)),
+                type: 'post.edited',
+                postId: parsed.postId,
+                title: parsed.title ?? record.title,
+                body: parsed.body ?? record.body,
+                tags: [...new Set(parsed.tags ?? record.tags ?? [])].sort(),
+                ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
+            };
+            await this.repository.insertEvent(event);
+        });
+        return await this.getPostRecord(parsed.postId);
+    }
+    async archivePost(input) {
+        this.checkAbort();
+        const record = await this.getPostRecord(input.postId);
+        this.assertPostAuthor(record);
+        if (record.status !== 'archived') {
+            await this.repository.transaction(async () => {
+                const event = {
+                    ...this.eventBase(input.postId, await this.repository.nextAggregateVersion(input.postId)),
+                    type: 'post.archived',
+                    postId: input.postId,
+                    ...(input.reason ? { reason: input.reason } : {}),
+                    ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+                };
+                await this.repository.insertEvent(event);
+            });
+        }
+        return await this.getPostRecord(input.postId);
+    }
+    async acknowledgePost(input) {
+        this.checkAbort();
+        const record = await this.getPostRecord(input.postId);
+        // Acknowledging twice is the same statement, so the second is a no-op
+        // rather than a second row or an error.
+        const already = record.acknowledgments.some((entry) => entry.actor.id === this.actor.id && entry.actor.kind === this.actor.kind);
+        if (!already) {
+            await this.repository.transaction(async () => {
+                const event = {
+                    ...this.eventBase(input.postId, await this.repository.nextAggregateVersion(input.postId)),
+                    type: 'post.acknowledged',
+                    postId: input.postId,
+                    ...(input.note ? { note: input.note } : {}),
+                    ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+                };
+                await this.repository.insertEvent(event);
+            });
+        }
+        return await this.getPostRecord(input.postId);
+    }
+    async withdrawPostAcknowledgment(input) {
+        this.checkAbort();
+        const record = await this.getPostRecord(input.postId);
+        const mine = record.acknowledgments.some((entry) => entry.actor.id === this.actor.id && entry.actor.kind === this.actor.kind);
+        if (mine) {
+            await this.repository.transaction(async () => {
+                const event = {
+                    ...this.eventBase(input.postId, await this.repository.nextAggregateVersion(input.postId)),
+                    type: 'post.acknowledgment.withdrawn',
+                    postId: input.postId,
+                    ...(input.reason ? { reason: input.reason } : {}),
+                };
+                await this.repository.insertEvent(event);
+            });
+        }
+        return await this.getPostRecord(input.postId);
+    }
+    async postRoster(postId) {
+        this.checkAbort();
+        await this.requireVisibleItem(postId, 'post');
+        const roster = await this.repository.postRoster(postId);
+        if (!roster)
+            throw new SynomemError('ITEM_NOT_FOUND', `Unknown post: ${postId}`);
+        return roster;
+    }
     async getNoteRecord(id) {
         await this.requireVisibleItem(id, 'note');
         const record = noteRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
@@ -567,40 +836,40 @@ export class SynomemCore {
         await this.projectionWriter.syncAgent(record.event.ownerAgentId);
         return await this.getNoteRecord(input.noteId);
     }
-    async getTodoRecord(id) {
-        await this.requireVisibleItem(id, 'todo');
-        const record = todoRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
+    async getTaskRecord(id) {
+        await this.requireVisibleItem(id, 'task');
+        const record = taskRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
         if (!record)
-            throw new SynomemError('TODO_NOT_FOUND', `Unknown todo: ${id}`);
+            throw new SynomemError('TODO_NOT_FOUND', `Unknown task: ${id}`);
         return record;
     }
-    async getTodo(id) {
+    async getTask(id) {
         this.checkAbort();
-        return await this.getTodoRecord(id);
+        return await this.getTaskRecord(id);
     }
-    async createTodo(input) {
+    async createTask(input) {
         this.checkAbort();
         await this.repository.assertEventCompatibility();
-        const parsed = this.validate(() => createTodoSchema.parse(input));
+        const parsed = this.validate(() => createTaskSchema.parse(input));
         const assigneeId = parsed.assigneeAgentId ?? (this.actor.kind === 'agent' ? this.actor.id : undefined);
         if (!assigneeId)
             throw new SynomemError('INVALID_INPUT', 'A human or system actor must specify assigneeAgentId.');
         const assignee = await this.repository.getAgent(assigneeId);
         if (!assignee)
-            throw new SynomemError('AGENT_NOT_FOUND', `Unknown todo assignee: ${assigneeId}`);
+            throw new SynomemError('AGENT_NOT_FOUND', `Unknown task assignee: ${assigneeId}`);
         if (this.actor.kind === 'agent' &&
             this.actor.id !== assignee.id &&
-            !this.repository.config.allowCrossAgentTodos)
-            throw new SynomemError('POLICY_FORBIDDEN', 'Cross-agent todo assignment is disabled.');
+            !this.repository.config.allowCrossAgentTasks)
+            throw new SynomemError('POLICY_FORBIDDEN', 'Cross-agent task assignment is disabled.');
         const outcome = await this.repository.transaction(async () => {
-            const prior = await this.priorMutation(parsed.idempotencyKey, 'todo.created');
-            if (prior?.type === 'todo.created')
+            const prior = await this.priorMutation(parsed.idempotencyKey, 'task.created');
+            if (prior?.type === 'task.created')
                 return { id: prior.id, created: false };
             const id = this.nextId();
             const requiresAcceptance = this.actor.kind !== 'agent' || this.actor.id !== assignee.id;
             const event = {
                 ...this.eventBase(id, 1, id),
-                type: 'todo.created',
+                type: 'task.created',
                 assigneeAgentId: assignee.id,
                 assigneeDisplayName: assignee.displayName,
                 title: parsed.title,
@@ -620,43 +889,43 @@ export class SynomemCore {
         if (outcome.created)
             await this.projectionWriter.syncAgent(assignee.id);
         return {
-            record: await this.getTodoRecord(outcome.id),
+            record: await this.getTaskRecord(outcome.id),
             created: outcome.created,
             deduplicated: !outcome.created,
         };
     }
-    assertTodoParticipant(record) {
+    assertTaskParticipant(record) {
         const isCreator = record.event.actor.kind === this.actor.kind && record.event.actor.id === this.actor.id;
         const isAssignee = this.actor.kind === 'agent' && this.actor.id === record.event.assigneeAgentId;
         if (!this.administrative && !isCreator && !isAssignee)
-            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the todo creator, assignee, or a human administrator may change it.');
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the task creator, assignee, or a human administrator may change it.');
     }
-    assertTodoAssignee(record) {
+    assertTaskAssignee(record) {
         if (!this.administrative &&
             !(this.actor.kind === 'agent' && this.actor.id === record.event.assigneeAgentId)) {
-            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the assigned agent or a human administrator may accept or reject this todo.');
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the assigned agent or a human administrator may accept or reject this task.');
         }
     }
-    async updateTodo(input) {
-        const parsed = this.validate(() => updateTodoSchema.parse(input));
-        const record = await this.getTodoRecord(parsed.todoId);
-        this.assertTodoParticipant(record);
+    async updateTask(input) {
+        const parsed = this.validate(() => updateTaskSchema.parse(input));
+        const record = await this.getTaskRecord(parsed.taskId);
+        this.assertTaskParticipant(record);
         if (record.status !== 'open')
-            throw new SynomemError('INVALID_INPUT', 'Only open todos can be updated.');
+            throw new SynomemError('INVALID_INPUT', 'Only open tasks can be updated.');
         if (parsed.expectedVersion !== record.current.version)
-            throw new SynomemError('REVISION_CONFLICT', `Expected todo version ${parsed.expectedVersion}; current version is ${record.current.version}.`);
+            throw new SynomemError('REVISION_CONFLICT', `Expected task version ${parsed.expectedVersion}; current version is ${record.current.version}.`);
         await this.repository.transaction(async () => {
-            const prior = await this.priorMutation(parsed.idempotencyKey, 'todo.updated');
+            const prior = await this.priorMutation(parsed.idempotencyKey, 'task.updated');
             if (prior)
                 return;
             if ((await this.repository.nextAggregateVersion(record.event.id)) !==
                 parsed.expectedVersion + 1)
-                throw new SynomemError('REVISION_CONFLICT', 'The todo changed before this update was stored.');
+                throw new SynomemError('REVISION_CONFLICT', 'The task changed before this update was stored.');
             const due = parsed.due === null ? undefined : (parsed.due ?? record.current.due);
             const event = {
                 ...this.eventBase(record.event.id, parsed.expectedVersion + 1),
-                type: 'todo.updated',
-                todoId: record.event.id,
+                type: 'task.updated',
+                taskId: record.event.id,
                 title: parsed.title ?? record.current.title,
                 ...(parsed.description !== undefined
                     ? { description: parsed.description }
@@ -674,35 +943,40 @@ export class SynomemCore {
             await this.repository.insertEvent(event);
         });
         await this.projectionWriter.syncAgent(record.event.assigneeAgentId);
-        return await this.getTodoRecord(parsed.todoId);
+        return await this.getTaskRecord(parsed.taskId);
     }
-    async todoTransition(input, type) {
-        const record = await this.getTodoRecord(input.todoId);
-        if (type === 'todo.accepted' || type === 'todo.rejected')
-            this.assertTodoAssignee(record);
+    async taskTransition(input, type) {
+        const record = await this.getTaskRecord(input.taskId);
+        // A rejection must say why. Enforced here as well as in the schema so the
+        // failure names the missing thing rather than surfacing as a parse error.
+        if (type === 'task.rejected' && !input.response?.trim()) {
+            throw new SynomemError('INVALID_INPUT', 'Rejecting a task requires a response explaining why, so the assigner knows whether to reassign it, wait, or change the request.');
+        }
+        if (type === 'task.accepted' || type === 'task.rejected')
+            this.assertTaskAssignee(record);
         else
-            this.assertTodoParticipant(record);
-        if ((type === 'todo.accepted' || type === 'todo.rejected') && record.status !== 'assigned') {
-            if (type === 'todo.accepted' && record.status === 'open')
+            this.assertTaskParticipant(record);
+        if ((type === 'task.accepted' || type === 'task.rejected') && record.status !== 'assigned') {
+            if (type === 'task.accepted' && record.status === 'open')
                 return record;
-            if (type === 'todo.rejected' && record.status === 'rejected')
+            if (type === 'task.rejected' && record.status === 'rejected')
                 return record;
-            throw new SynomemError('INVALID_INPUT', 'Only assigned todos may be accepted or rejected.');
+            throw new SynomemError('INVALID_INPUT', 'Only assigned tasks may be accepted or rejected.');
         }
-        if (type === 'todo.completed' && record.status !== 'open') {
+        if (type === 'task.completed' && record.status !== 'open') {
             if (record.status === 'completed')
                 return record;
-            throw new SynomemError('INVALID_INPUT', 'Only accepted or self-created open todos may be completed.');
+            throw new SynomemError('INVALID_INPUT', 'Only accepted or self-created open tasks may be completed.');
         }
-        if (type === 'todo.reopened' && record.status !== 'completed' && record.status !== 'canceled') {
+        if (type === 'task.reopened' && record.status !== 'completed' && record.status !== 'canceled') {
             if (record.status === 'open')
                 return record;
-            throw new SynomemError('INVALID_INPUT', 'Only completed or canceled todos may be reopened.');
+            throw new SynomemError('INVALID_INPUT', 'Only completed or canceled tasks may be reopened.');
         }
-        if (type === 'todo.canceled' && record.status !== 'assigned' && record.status !== 'open') {
+        if (type === 'task.canceled' && record.status !== 'assigned' && record.status !== 'open') {
             if (record.status === 'canceled')
                 return record;
-            throw new SynomemError('INVALID_INPUT', 'Only assigned or open todos may be canceled.');
+            throw new SynomemError('INVALID_INPUT', 'Only assigned or open tasks may be canceled.');
         }
         await this.repository.transaction(async () => {
             const prior = await this.priorMutation(input.idempotencyKey, type);
@@ -710,33 +984,163 @@ export class SynomemCore {
                 return;
             const base = {
                 ...this.eventBase(record.event.id, await this.repository.nextAggregateVersion(record.event.id)),
-                todoId: record.event.id,
+                taskId: record.event.id,
                 ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
             };
-            const event = type === 'todo.completed'
+            const event = type === 'task.completed'
                 ? { ...base, type, ...(input.note ? { note: input.note.trim() } : {}) }
-                : type === 'todo.canceled' || type === 'todo.rejected'
-                    ? { ...base, type, ...(input.reason ? { reason: input.reason.trim() } : {}) }
-                    : { ...base, type };
+                : type === 'task.rejected'
+                    ? { ...base, type, response: input.response.trim() }
+                    : type === 'task.accepted'
+                        ? {
+                            ...base,
+                            type,
+                            ...(input.response ? { response: input.response.trim() } : {}),
+                        }
+                        : type === 'task.canceled'
+                            ? { ...base, type, ...(input.reason ? { reason: input.reason.trim() } : {}) }
+                            : { ...base, type };
             await this.repository.insertEvent(event);
         });
         await this.projectionWriter.syncAgent(record.event.assigneeAgentId);
-        return await this.getTodoRecord(input.todoId);
+        return await this.getTaskRecord(input.taskId);
+    }
+    completeTask(input) {
+        return this.taskTransition(input, 'task.completed');
+    }
+    acceptTask(input) {
+        return this.taskTransition(input, 'task.accepted');
     }
-    completeTodo(input) {
-        return this.todoTransition(input, 'todo.completed');
+    rejectTask(input) {
+        return this.taskTransition(input, 'task.rejected');
     }
-    acceptTodo(input) {
-        return this.todoTransition(input, 'todo.accepted');
+    reopenTask(input) {
+        return this.taskTransition(input, 'task.reopened');
     }
-    rejectTodo(input) {
-        return this.todoTransition(input, 'todo.rejected');
+    cancelTask(input) {
+        return this.taskTransition(input, 'task.canceled');
     }
-    reopenTodo(input) {
-        return this.todoTransition(input, 'todo.reopened');
+    /* ----------------------------------------------------------------- todos *
+     * A Todo is a private reminder an agent creates for itself. There is no
+     * assignee, no acceptance, and no visibility choice: it belongs to its author
+     * and only its author reads it. Every method below asserts that ownership
+     * rather than relying on a visibility filter, so a Todo cannot be reached by
+     * guessing its id.
+     */
+    async createTodo(input) {
+        this.checkAbort();
+        await this.repository.assertEventCompatibility();
+        const parsed = this.validate(() => createTodoSchema.parse(input));
+        const outcome = await this.repository.transaction(async () => {
+            const prior = await this.priorMutation(parsed.idempotencyKey, 'todo.created');
+            if (prior?.type === 'todo.created')
+                return { id: prior.id, created: false };
+            const id = this.nextId();
+            const event = {
+                ...this.eventBase(id, 1, id),
+                type: 'todo.created',
+                title: parsed.title,
+                ...(parsed.details !== undefined ? { details: parsed.details } : {}),
+                priority: parsed.priority ?? 3,
+                ...(parsed.due ? { due: parsed.due } : {}),
+                tags: [...new Set(parsed.tags ?? [])].sort(),
+                ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
+                ...(parsed.source ? { source: parsed.source } : {}),
+                ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
+            };
+            await this.repository.insertEvent(event);
+            return { id, created: true };
+        });
+        return {
+            record: await this.getTodoRecord(outcome.id),
+            created: outcome.created,
+            deduplicated: !outcome.created,
+        };
+    }
+    async getTodoRecord(id) {
+        const record = todoRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
+        if (!record)
+            throw new SynomemError('ITEM_NOT_FOUND', `Unknown todo: ${id}`);
+        this.assertTodoOwner(record);
+        return record;
+    }
+    /**
+     * Todos are owner-only. No role, however broad, reads another actor's
+     * private reminders — that is a named administrative capability this release
+     * does not have, not something a permission check quietly allows.
+     */
+    assertTodoOwner(record) {
+        const owner = record.event.actor;
+        if (owner.kind !== this.actor.kind || owner.id !== this.actor.id) {
+            throw new SynomemError('MUTATION_FORBIDDEN', 'A todo is private to the actor who created it.');
+        }
+    }
+    async getTodo(id) {
+        this.checkAbort();
+        return await this.getTodoRecord(id);
+    }
+    async updateTodo(input) {
+        this.checkAbort();
+        const parsed = this.validate(() => updateTodoSchema.parse(input));
+        const record = await this.getTodoRecord(parsed.todoId);
+        if (record.current.version !== parsed.expectedVersion) {
+            throw new SynomemError('REVISION_CONFLICT', `Todo ${parsed.todoId} is at version ${record.current.version}.`);
+        }
+        const due = parsed.due === null ? undefined : (parsed.due ?? record.current.due);
+        await this.repository.transaction(async () => {
+            const prior = await this.priorMutation(parsed.idempotencyKey, 'todo.updated');
+            if (prior)
+                return;
+            const event = {
+                ...this.eventBase(record.event.id, await this.repository.nextAggregateVersion(record.event.id)),
+                type: 'todo.updated',
+                todoId: record.event.id,
+                title: parsed.title ?? record.current.title,
+                ...((parsed.details ?? record.current.details)
+                    ? { details: parsed.details ?? record.current.details }
+                    : {}),
+                priority: parsed.priority ?? record.current.priority,
+                ...(due ? { due } : {}),
+                tags: [...new Set(parsed.tags ?? record.current.tags)].sort(),
+                ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
+            };
+            await this.repository.insertEvent(event);
+        });
+        return await this.getTodoRecord(parsed.todoId);
     }
-    cancelTodo(input) {
-        return this.todoTransition(input, 'todo.canceled');
+    async todoTransition(input, type) {
+        const record = await this.getTodoRecord(input.todoId);
+        if (type === 'todo.completed' && record.status !== 'open') {
+            if (record.status === 'completed')
+                return record;
+            throw new SynomemError('INVALID_INPUT', 'Only an open todo may be completed.');
+        }
+        if (type === 'todo.reopened' && record.status === 'open')
+            return record;
+        if (type === 'todo.canceled' && record.status !== 'open') {
+            if (record.status === 'canceled')
+                return record;
+            throw new SynomemError('INVALID_INPUT', 'Only an open todo may be canceled.');
+        }
+        if (type === 'todo.archived' && record.status === 'archived')
+            return record;
+        await this.repository.transaction(async () => {
+            const prior = await this.priorMutation(input.idempotencyKey, type);
+            if (prior)
+                return;
+            const base = {
+                ...this.eventBase(record.event.id, await this.repository.nextAggregateVersion(record.event.id)),
+                todoId: record.event.id,
+                ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+            };
+            const event = type === 'todo.completed'
+                ? { ...base, type, ...(input.note ? { note: input.note.trim() } : {}) }
+                : type === 'todo.canceled'
+                    ? { ...base, type, ...(input.reason ? { reason: input.reason.trim() } : {}) }
+                    : { ...base, type };
+            await this.repository.insertEvent(event);
+        });
+        return await this.getTodoRecord(input.todoId);
     }
     async listItems(input) {
         this.checkAbort();
@@ -765,7 +1169,7 @@ export class SynomemCore {
             return this.getMemo(id);
         if (summary.kind === 'note')
             return this.getNote(id);
-        return this.getTodo(id);
+        return this.getTask(id);
     }
     async stats(input = {}) {
         this.checkAbort();
@@ -818,6 +1222,14 @@ export class SynomemCore {
         return stats;
     }
 }
+/**
+ * The schema version this package writes and expects. Named rather than
+ * repeated as a literal because it is asserted in three places, and a doctor
+ * check that silently lags the migration runner reports a healthy database as
+ * broken.
+ */
+const CURRENT_SCHEMA_VERSION = 6;
+const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5, 6];
 export class SynomemClient extends SynomemCore {
     home;
     storage;
@@ -915,8 +1327,9 @@ export class SynomemClient extends SynomemCore {
                 message: `${itemHealth.indexed} of ${itemHealth.created} item aggregates are present in the shared current-state index.`,
             });
             const migrationState = this.storage.migrationState();
-            const migrationsValid = migrationState.schemaVersion === 3 &&
-                JSON.stringify(migrationState.appliedVersions) === JSON.stringify([1, 2, 3]);
+            const migrationsValid = migrationState.schemaVersion === CURRENT_SCHEMA_VERSION &&
+                JSON.stringify(migrationState.appliedVersions) ===
+                    JSON.stringify(EXPECTED_APPLIED_MIGRATIONS);
             diagnostics.push({
                 level: migrationsValid ? 'ok' : 'error',
                 code: migrationsValid ? 'MIGRATIONS_VALID' : 'MIGRATIONS_INCONSISTENT',
@@ -987,7 +1400,7 @@ export class SynomemClient extends SynomemCore {
         const records = recordsFromEvents(events);
         const memos = memoRecordsFromEvents(events);
         const notes = noteRecordsFromEvents(events);
-        const todos = todoRecordsFromEvents(events);
+        const tasks = taskRecordsFromEvents(events);
         const warning = scan.invalid.length
             ? `> Warning: ${scan.invalid.length} unsupported or malformed event(s) omitted from this Markdown view: ${scan.invalid.map((item) => item.id).join(', ')}\n\n`
             : '';
@@ -995,7 +1408,7 @@ export class SynomemClient extends SynomemCore {
             ...records.map((record) => `## Kudos: ${escapeMarkdown(record.event.title)}\n\n${escapeMarkdown(record.event.reason)}\n\nStatus: ${record.revocationStatus === 'revoked' ? 'Revoked' : record.status}\n\nID: \`${record.event.id}\``),
             ...memos.map((record) => `## Memo: ${escapeMarkdown(record.event.subject)}\n\n${escapeMarkdown(record.event.body)}\n\nStatus: ${record.status}\n\nID: \`${record.event.id}\``),
             ...notes.map((record) => `## Note: ${escapeMarkdown(record.current.title)}\n\n${escapeMarkdown(record.current.body)}\n\nStatus: ${record.status}; version ${record.current.version}\n\nID: \`${record.event.id}\``),
-            ...todos.map((record) => `## Todo: ${escapeMarkdown(record.current.title)}\n\n${record.current.description ? `${escapeMarkdown(record.current.description)}\n\n` : ''}Status: ${record.status}; priority ${record.current.priority}\n\nID: \`${record.event.id}\``),
+            ...tasks.map((record) => `## Task: ${escapeMarkdown(record.current.title)}\n\n${record.current.description ? `${escapeMarkdown(record.current.description)}\n\n` : ''}Status: ${record.status}; priority ${record.current.priority}\n\nID: \`${record.event.id}\``),
         ];
         return `${warning}${sections.join('\n\n')}\n`;
     }