synomem 0.9.6 → 0.10.0

package/dist/client.js

@@ -1,3 +1,9 @@
+import { actorDirectoryInput } from './actor-directory.js';
+import { z } from 'zod';
+import { threadInputSchema, threadSubscriptionSchema, replyCreateSchema, replyDeleteSchema, reactionSetSchema, } from './schemas.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { cursorFilter } from './cursors.js';
+import { isRecordAdministrator, localOwnerAuthority, overseesAgent, resolveAuthority, sameActor, } from './policy.js';
 import { accessSync, constants as fsConstants, existsSync, lstatSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { ulid } from 'ulid';
@@ -5,7 +11,7 @@ import { resolveHome } from './config.js';
 import { asSynomemError, SynomemError } from './errors.js';
 import { assertNoSymlinkEscape } from './fs-utils.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, createTopicSchema, updateTopicSchema, topicListInputSchema, topicLookupSchema, } from './schemas.js';
+import { actorSchema, eventSchema, overrideTaskDecisionSchema, agentLookupSchema, bindRuntimeSchema, createAgentSchema, createPostSchema, updatePostSchema, createNoteSchema, createTaskSchema, createTodoSchema, changesInputSchema, giveKudosSchema, itemListInputSchema, listInputSchema, reviseNoteSchema, sendMemoSchema, updateTaskSchema, updateTodoSchema, updateAgentSchema, createTopicSchema, updateTopicSchema, topicListInputSchema, topicLookupSchema, } from './schemas.js';
 import { SynomemStorage } from './storage.js';
 export class SynomemCore {
     /**
@@ -19,7 +25,280 @@ export class SynomemCore {
     idGenerator;
     signal;
     administrative;
+    writeAllowed;
+    mutationContext = new AsyncLocalStorage();
+    authority;
     initialized = false;
+    bookmarks = {
+        list: (input = {}) => {
+            const parsed = this.validate(() => z
+                .object({
+                after: z.string().max(4096).optional(),
+                limit: z.number().int().min(1).max(100).optional(),
+            })
+                .strict()
+                .parse(input));
+            return this.repository.bookmarks.list(parsed, this.actor);
+        },
+        has: async (rootId) => {
+            await this.getItem(rootId);
+            return { saved: await this.repository.bookmarks.has(rootId, this.boundRef()) };
+        },
+        set: async (input) => {
+            const parsed = this.validate(() => z
+                .object({ rootId: z.string().length(26), present: z.boolean() })
+                .strict()
+                .parse(input));
+            if (!this.writeAllowed)
+                throw new SynomemError('READ_ONLY', 'This binding cannot change saved records.');
+            await this.repository.transaction(async () => {
+                await this.resolveActor(this.boundRef(), true);
+                await this.getItem(parsed.rootId);
+                await this.repository.bookmarks.set(parsed.rootId, this.boundRef(), parsed.present);
+            });
+            return { saved: parsed.present };
+        },
+    };
+    notifications = {
+        list: async (input = {}) => {
+            const parsed = this.validate(() => z
+                .object({
+                after: z.string().max(4096).optional(),
+                limit: z.number().int().min(1).max(100).optional(),
+                view: z.enum(['all', 'unread', 'action_required', 'default']).optional(),
+            })
+                .strict()
+                .parse(input));
+            if (this.writeAllowed)
+                await this.repository.transaction(() => this.repository.notifications.drain());
+            const page = await this.repository.notifications.list(parsed, this.actor);
+            return page;
+        },
+        read: (id) => this.personalWrite(() => this.repository.notifications.read(id, this.boundRef())),
+        dismiss: (id) => this.personalWrite(() => this.repository.notifications.dismiss(id, this.boundRef())),
+        readThrough: (through) => this.personalWrite(() => this.repository.notifications.readThrough(through, this.boundRef())),
+    };
+    replies = {
+        changes: async (input) => {
+            const parsed = this.validate(() => threadInputSchema.parse(input));
+            await this.getItem(parsed.rootId);
+            return this.repository.participation.changes(parsed, this.actor);
+        },
+        create: (input) => this.mutate('replies.create', input, () => this.createReply(input)),
+        get: (id) => this.getReply(id),
+        delete: (input) => this.mutate('replies.delete', input, () => this.deleteReply(input)),
+    };
+    threads = {
+        read: async (input) => {
+            const parsed = this.validate(() => z
+                .object({ rootId: z.string().length(26), through: z.string().max(4096) })
+                .strict()
+                .parse(input));
+            await this.personalWrite(async () => {
+                await this.getItem(parsed.rootId);
+                await this.repository.participation.read(parsed.rootId, parsed.through, this.boundRef());
+            });
+        },
+        get: async (input) => {
+            const parsed = this.validate(() => threadInputSchema.parse(input));
+            await this.getItem(parsed.rootId);
+            return this.repository.participation.thread(parsed, this.actor);
+        },
+        subscription: async (input) => {
+            const parsed = this.validate(() => threadSubscriptionSchema.parse(input));
+            await this.personalWrite(async () => {
+                await this.getItem(parsed.rootId);
+                await this.repository.participation.subscription(parsed.rootId, this.boundRef(), parsed.following, parsed.muted);
+            });
+        },
+    };
+    reactions = {
+        set: (input) => this.mutate('reactions.set', input, () => this.setReaction(input)),
+        get: async (targetId) => {
+            await this.reactionRoot(targetId);
+            return this.repository.participation.reactions(targetId, this.boundRef());
+        },
+    };
+    allowedActions(record) {
+        const event = record.event;
+        const active = record.status !== 'archived' &&
+            (!('revocationStatus' in record) || record.revocationStatus !== 'revoked');
+        const owner = 'owner' in event ? event.owner : event.actor;
+        const participant = 'assignee' in event &&
+            (this.canManage(event.assignee) || this.canManage(event.actor));
+        const managed = event.type === 'memo.sent'
+            ? this.canManage(event.recipient)
+            : event.type === 'task.created'
+                ? participant
+                : this.canManage(owner);
+        const flags = {
+            reply: active,
+            edit: active &&
+                managed &&
+                ['post.created', 'note.created', 'task.created', 'todo.created'].includes(event.type),
+            archive: active && managed && !['task.created', 'kudos.given'].includes(event.type),
+            moderateReplies: this.canModerateRoot(record),
+            acknowledge: event.type === 'kudos.given'
+                ? active && sameActor(this.actor, event.recipient) && record.status === 'unacknowledged'
+                : event.type === 'post.created'
+                    ? active &&
+                        'acknowledgments' in record &&
+                        !record.acknowledgments.some((entry) => sameActor(this.actor, entry.actor))
+                    : false,
+            withdrawAcknowledgment: event.type === 'post.created' &&
+                active &&
+                'acknowledgments' in record &&
+                record.acknowledgments.some((entry) => sameActor(this.actor, entry.actor)),
+            readMemo: event.type === 'memo.sent' &&
+                active &&
+                sameActor(this.actor, event.recipient) &&
+                record.status === 'unread',
+            revoke: event.type === 'kudos.given' && active && this.canManage(event.actor),
+        };
+        if (event.type === 'task.created')
+            Object.assign(flags, {
+                accept: record.status === 'assigned' && this.canManage(event.assignee),
+                reject: record.status === 'assigned' && this.canManage(event.assignee),
+                complete: record.status === 'open' && participant,
+                reopen: ['completed', 'canceled'].includes(record.status) && participant,
+                cancel: ['assigned', 'open'].includes(record.status) && participant,
+                overrideDecision: ['open', 'rejected'].includes(record.status) &&
+                    this.actor.kind === 'human' &&
+                    (this.administrative ||
+                        (event.assignee.kind === 'agent' &&
+                            overseesAgent(this.actor, this.authority, event.assignee.id)) ||
+                        (event.actor.kind === 'agent' &&
+                            overseesAgent(this.actor, this.authority, event.actor.id))),
+            });
+        if (event.type === 'todo.created')
+            Object.assign(flags, {
+                complete: record.status === 'open' && managed,
+                reopen: ['completed', 'canceled'].includes(record.status) && managed,
+                cancel: record.status === 'open' && managed,
+            });
+        return Object.fromEntries(Object.entries(flags).map(([name, allowed]) => [name, this.writeAllowed && allowed]));
+    }
+    async decorateRecord(record) {
+        return {
+            ...record,
+            lifecycleVersion: (await this.repository.nextAggregateVersion(record.event.id)) - 1,
+            allowedActions: this.allowedActions(record),
+        };
+    }
+    async getReply(id) {
+        const reply = await this.repository.participation.getReply(id);
+        if (!reply)
+            throw new SynomemError('ITEM_NOT_FOUND', 'Unknown reply.');
+        await this.getItem(reply.rootId);
+        return reply;
+    }
+    async createReply(input) {
+        await this.repository.assertEventCompatibility();
+        const parsed = this.validate(() => replyCreateSchema.parse(input));
+        const root = await this.getItem(parsed.rootId);
+        if (root.status === 'archived' ||
+            ('revocationStatus' in root && root.revocationStatus === 'revoked'))
+            throw new SynomemError('MUTATION_FORBIDDEN', 'This root no longer accepts replies.');
+        if (parsed.parentId) {
+            const parent = await this.getReply(parsed.parentId);
+            if (parent.rootId !== parsed.rootId)
+                throw new SynomemError('INVALID_INPUT', 'The parent must belong to this thread.');
+        }
+        const mentions = [];
+        for (const supplied of parsed.mentions ?? []) {
+            const target = await this.resolveActor(supplied, true);
+            const ref = { kind: target.kind, id: target.id };
+            if (!(await this.repository.canActorReadItem(parsed.rootId, ref)))
+                throw new SynomemError('INVALID_INPUT', 'Mention targets must already have access.');
+            if (!mentions.some((actor) => sameActor(actor, ref)))
+                mentions.push(ref);
+        }
+        await this.repository.participation.reserveBudget('reply', this.boundRef(), this.now());
+        const id = this.nextId();
+        await this.repository.insertEvent({
+            ...this.eventBase(id, 1, id),
+            type: 'reply.created',
+            rootId: parsed.rootId,
+            parentId: parsed.parentId ?? null,
+            body: parsed.body,
+            mentions,
+        });
+        return this.getReply(id);
+    }
+    canModerateRoot(root) {
+        if (this.actor.kind !== 'human')
+            return false;
+        const event = root.event;
+        if (this.administrative || sameActor(event.actor, this.actor))
+            return true;
+        const targets = [
+            event.actor,
+            ...('recipient' in event ? [event.recipient] : []),
+            ...('owner' in event ? [event.owner] : []),
+            ...('assignee' in event ? [event.assignee] : []),
+        ];
+        return targets.some((ref) => ref.kind === 'agent' && overseesAgent(this.actor, this.authority, ref.id));
+    }
+    async deleteReply(input) {
+        await this.repository.assertEventCompatibility();
+        const parsed = this.validate(() => replyDeleteSchema.parse(input));
+        const reply = await this.getReply(parsed.replyId);
+        const root = await this.getItem(reply.rootId);
+        const own = sameActor(reply.author, this.actor);
+        if (!own && !this.canModerateRoot(root))
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the reply author or an authorized human moderator may delete it.');
+        if (!own && !parsed.reason)
+            throw new SynomemError('INVALID_INPUT', 'Moderation requires a reason.');
+        if (reply.version !== parsed.expectedVersion)
+            throw new SynomemError('REVISION_CONFLICT', 'The reply changed. Refresh before deleting.');
+        if (reply.deleted)
+            return reply;
+        await this.repository.insertEvent({
+            ...this.eventBase(reply.id, reply.version + 1),
+            ...(!own ? this.intervention(reply.author, parsed.reason) : {}),
+            type: 'reply.deleted',
+            replyId: reply.id,
+            rootId: reply.rootId,
+            ...(parsed.reason ? { reason: parsed.reason } : {}),
+        });
+        return this.getReply(reply.id);
+    }
+    async reactionRoot(targetId) {
+        const reply = await this.repository.participation.getReply(targetId);
+        if (reply) {
+            await this.getItem(reply.rootId);
+            if (reply.deleted)
+                throw new SynomemError('MUTATION_FORBIDDEN', 'Deleted replies cannot receive reactions.');
+            return reply.rootId;
+        }
+        await this.getItem(targetId);
+        return targetId;
+    }
+    async setReaction(input) {
+        await this.repository.assertEventCompatibility();
+        const parsed = this.validate(() => reactionSetSchema.parse(input));
+        const rootId = await this.reactionRoot(parsed.targetId);
+        const actor = this.boundRef();
+        const present = await this.repository.participation.hasReaction(parsed.targetId, actor, parsed.code);
+        if (present !== parsed.present) {
+            await this.repository.participation.reserveBudget('reaction', actor, this.now());
+            const id = this.nextId();
+            await this.repository.insertEvent({
+                ...this.eventBase(id, 1, id),
+                type: parsed.present ? 'reaction.added' : 'reaction.removed',
+                rootId,
+                targetId: parsed.targetId,
+                code: parsed.code,
+            });
+        }
+        return this.repository.participation.reactions(parsed.targetId, actor);
+    }
+    async search(input) {
+        this.checkAbort();
+        if (!this.repository.search)
+            throw new SynomemError('UNSUPPORTED_BACKEND', 'Search is available on hosted workspaces.');
+        return this.repository.search(input, this.actor);
+    }
     agents = {
         create: (input) => this.createAgent(input),
         update: (id, changes) => this.updateAgent(id, changes),
@@ -45,65 +324,66 @@ export class SynomemCore {
         restore: (idOrAlias) => this.setTopicStatus(idOrAlias, 'active'),
     };
     kudos = {
-        give: (input) => this.giveKudos(input),
+        give: (input) => this.mutate('kudos.give', input, () => this.giveKudos(input)),
         list: (input = {}) => this.listKudos(input),
         changes: (input = {}) => this.listKudosChanges(input),
         get: (id) => this.getKudos(id),
-        acknowledge: (input) => this.acknowledgeKudos(input),
-        revoke: (input) => this.revokeKudos(input),
+        acknowledge: (input) => this.mutate('kudos.acknowledge', input, () => this.acknowledgeKudos(input)),
+        revoke: (input) => this.mutate('kudos.revoke', input, () => this.revokeKudos(input)),
     };
     memos = {
-        send: (input) => this.sendMemo(input),
+        send: (input) => this.mutate('memos.send', input, () => this.sendMemo(input)),
         list: (input = {}) => this.listItems({ ...input, kinds: ['memo'] }),
         get: (id) => this.getMemo(id),
-        read: (input) => this.readMemo(input),
-        archive: (input) => this.archiveMemo(input),
+        read: (input) => this.mutate('memos.read', input, () => this.readMemo(input)),
+        archive: (input) => this.mutate('memos.archive', input, () => this.archiveMemo(input)),
     };
     posts = {
-        create: (input) => this.createPost(input),
+        create: (input) => this.mutate('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),
+        update: (input) => this.mutate('posts.update', input, () => this.updatePost(input)),
+        archive: (input) => this.mutate('posts.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),
+        acknowledge: (input) => this.mutate('posts.acknowledge', input, () => this.acknowledgePost(input)),
+        withdrawAcknowledgment: (input) => this.mutate('posts.withdrawAcknowledgment', input, () => this.withdrawPostAcknowledgment(input)),
         roster: (postId) => this.postRoster(postId),
     };
     notes = {
-        create: (input) => this.createNote(input),
+        create: (input) => this.mutate('notes.create', input, () => this.createNote(input)),
         list: (input = {}) => this.listItems({ ...input, kinds: ['note'] }),
         get: (id) => this.getNote(id),
-        revise: (input) => this.reviseNote(input),
-        archive: (input) => this.archiveNote(input),
+        revise: (input) => this.mutate('notes.revise', input, () => this.reviseNote(input)),
+        archive: (input) => this.mutate('notes.archive', input, () => this.archiveNote(input)),
     };
     tasks = {
-        create: (input) => this.createTask(input),
+        overrideDecision: (input) => this.mutate('tasks.overrideDecision', input, () => this.overrideTaskDecision(input)),
+        create: (input) => this.mutate('tasks.create', input, () => this.createTask(input)),
         list: (input = {}) => this.listItems({ ...input, kinds: ['task'] }),
         get: (id) => this.getTask(id),
-        update: (input) => this.updateTask(input),
+        update: (input) => this.mutate('tasks.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),
+        accept: (input) => this.mutate('tasks.accept', input, () => this.acceptTask(input)),
+        reject: (input) => this.mutate('tasks.reject', input, () => this.rejectTask(input)),
+        complete: (input) => this.mutate('tasks.complete', input, () => this.completeTask(input)),
+        reopen: (input) => this.mutate('tasks.reopen', input, () => this.reopenTask(input)),
+        cancel: (input) => this.mutate('tasks.cancel', input, () => this.cancelTask(input)),
     };
     todos = {
-        create: (input) => this.createTodo(input),
+        create: (input) => this.mutate('todos.create', input, () => this.createTodo(input)),
         list: (input = {}) => this.listItems({ ...input, kinds: ['todo'] }),
         get: (id) => this.getTodo(id),
-        update: (input) => this.updateTodo(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'),
+        update: (input) => this.mutate('todos.update', input, () => this.updateTodo(input)),
+        complete: (input) => this.mutate('todos.complete', input, () => this.todoTransition(input, 'todo.completed')),
+        reopen: (input) => this.mutate('todos.reopen', input, () => this.todoTransition(input, 'todo.reopened')),
+        cancel: (input) => this.mutate('todos.cancel', input, () => this.todoTransition(input, 'todo.canceled')),
+        archive: (input) => this.mutate('todos.archive', input, () => this.todoTransition(input, 'todo.archived')),
     };
     /**
      * Unanswered and overdue discovery.
@@ -122,7 +402,7 @@ export class SynomemCore {
             const { olderThanHours, awaitingSince, ...rest } = input;
             const since = awaitingSince ??
                 (olderThanHours !== undefined
-                    ? new Date(Date.now() - olderThanHours * 3_600_000).toISOString()
+                    ? new Date(Date.now() - olderThanHours * 3600000).toISOString()
                     : undefined);
             return this.listItems({
                 ...rest,
@@ -151,16 +431,36 @@ export class SynomemCore {
         this.clock = options.clock ?? (() => new Date());
         this.idGenerator = options.idGenerator ?? (() => ulid(this.clock().getTime()));
         this.signal = options.signal;
-        this.administrative = options.administrative ?? this.actor.kind === 'human';
+        this.authority = resolveAuthority(options.authority);
+        this.writeAllowed = options.canWrite ?? true;
+        this.administrative = isRecordAdministrator(this.actor, this.authority);
         this.repository = options.repository;
         this.projectionWriter = options.projectionWriter;
     }
+    /** Trusted adapters refresh live authority after acquiring the workspace write boundary. Never exposed as a tool/input. */
+    setAuthority(authority, canWrite = this.writeAllowed) {
+        this.writeAllowed = canWrite;
+        this.authority = resolveAuthority(authority);
+        this.administrative = isRecordAdministrator(this.actor, this.authority);
+        this.repository.setAuthority(this.authority);
+    }
     async init() {
         this.checkAbort();
         if (this.initialized)
             return;
         await this.repository.init();
         this.initialized = true;
+        if (this.actor.kind === 'human' &&
+            this.authority.mode === 'local-owner' &&
+            !(await this.repository.getActor({ kind: 'human', id: this.actor.id }))) {
+            await this.repository.transaction(() => this.repository.registerHuman({
+                kind: 'human',
+                id: this.actor.id,
+                handle: this.actor.id,
+                displayName: this.actor.displayName ?? this.actor.id,
+                status: 'active',
+            }));
+        }
         /*
          * An agent actor is resolved to its canonical identity here.
          *
@@ -189,6 +489,321 @@ export class SynomemCore {
         await this.repository.close();
         this.initialized = false;
     }
+    actors = {
+        profile: async (input) => {
+            const actor = await this.resolveActor(input.target);
+            return {
+                actor,
+                counts: await this.repository.actorCounts(actor, this.actor),
+                authored: await this.listItems({
+                    actorKind: actor.kind,
+                    actorId: actor.id,
+                    cursor: input.after,
+                    limit: input.limit,
+                }),
+            };
+        },
+        list: async (input = {}) => {
+            this.checkAbort();
+            return await this.repository.listActors(actorDirectoryInput(input), this.actor);
+        },
+        get: (ref) => this.resolveActor(ref),
+        registerHuman: async (input) => {
+            if (this.actor.kind !== 'human' || this.authority.mode !== 'local-owner')
+                throw new SynomemError('MUTATION_FORBIDDEN', 'Only the local owner may register a human.');
+            const ref = actorSchema.parse({
+                kind: 'human',
+                id: input.id,
+                displayName: input.displayName,
+            });
+            const handle = agentLookupSchema.parse(input.handle);
+            await this.repository.registerHuman({
+                kind: 'human',
+                id: ref.id,
+                handle,
+                displayName: input.displayName,
+                status: 'active',
+            });
+            return this.resolveActor({ kind: 'human', id: ref.id });
+        },
+    };
+    async resolveActor(ref, requireActive = false) {
+        if (!ref || (ref.kind !== 'human' && ref.kind !== 'agent'))
+            throw new SynomemError('INVALID_INPUT', 'An actor reference is required.');
+        const actor = await this.repository.getActor(ref);
+        if (!actor)
+            throw new SynomemError('AGENT_NOT_FOUND', `Unknown ${ref.kind}: ${ref.id}`);
+        if (requireActive && actor.status !== 'active')
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Inactive actors cannot receive new work.');
+        return actor;
+    }
+    boundRef() {
+        if (this.actor.kind === 'system')
+            throw new SynomemError('MUTATION_FORBIDDEN', 'A human or agent identity is required.');
+        return { kind: this.actor.kind, id: this.actor.id };
+    }
+    canManage(ref) {
+        return (sameActor(ref, this.actor) ||
+            this.administrative ||
+            (ref.kind === 'agent' && overseesAgent(this.actor, this.authority, ref.id)));
+    }
+    intervention(ref, reason) {
+        if (this.actor.kind !== 'human' || sameActor(this.actor, ref) || !this.canManage(ref))
+            return {};
+        const basis = this.authority.mode === 'local-owner'
+            ? 'local_owner'
+            : this.authority.organizationAdministrator
+                ? 'organization_admin'
+                : this.authority.workspaceAdministrator
+                    ? 'workspace_admin'
+                    : 'operator';
+        return { intervention: { basis, ...(reason ? { reason } : {}) } };
+    }
+    async syncActor(ref) {
+        if (ref.kind === 'agent') {
+            const context = this.mutationContext.getStore();
+            if (context)
+                context.projections.add(ref.id);
+            else
+                await this.projectionWriter.syncAgent(ref.id);
+        }
+    }
+    async normalizeMutation(operation, input) {
+        const schemas = {
+            'kudos.give': giveKudosSchema,
+            'replies.create': replyCreateSchema,
+            'replies.delete': replyDeleteSchema,
+            'reactions.set': reactionSetSchema,
+            'memos.send': sendMemoSchema,
+            'notes.create': createNoteSchema,
+            'notes.revise': reviseNoteSchema,
+            'posts.create': createPostSchema,
+            'posts.update': updatePostSchema,
+            'tasks.create': createTaskSchema,
+            'tasks.update': updateTaskSchema,
+            'tasks.overrideDecision': overrideTaskDecisionSchema,
+            'todos.create': createTodoSchema,
+            'todos.update': updateTodoSchema,
+        };
+        const value = this.validate(() => schemas[operation]?.parse(operation === 'kudos.give'
+            ? {
+                ...input,
+                visibility: input.visibility ?? this.repository.config.defaultVisibility,
+            }
+            : input) ?? input);
+        const normalized = { ...value };
+        delete normalized.idempotencyKey;
+        for (const field of ['recipient', 'owner', 'assignee']) {
+            const supplied = normalized[field];
+            if (supplied) {
+                const actor = await this.resolveActor(supplied);
+                normalized[field] = { kind: actor.kind, id: actor.id };
+            }
+        }
+        for (const field of [
+            'title',
+            'body',
+            'subject',
+            'reason',
+            'response',
+            'note',
+            'details',
+            'description',
+        ])
+            if (typeof normalized[field] === 'string')
+                normalized[field] = normalized[field].trim();
+        for (const field of ['tags', 'topicIds'])
+            if (field in normalized ||
+                operation.endsWith('.create') ||
+                ['kudos.give', 'memos.send'].includes(operation))
+                normalized[field] = [...new Set((normalized[field] ?? []))].sort();
+        if (['kudos.give', 'memos.send', 'tasks.create'].includes(operation))
+            normalized.visibility ??= this.repository.config.defaultVisibility;
+        if (['notes.create', 'todos.create'].includes(operation))
+            normalized.owner ??= this.boundRef();
+        if (operation === 'tasks.create')
+            normalized.assignee ??= this.boundRef();
+        if (['tasks.create', 'todos.create'].includes(operation))
+            normalized.priority ??= 3;
+        if (['replies.create', 'posts.create', 'posts.update'].includes(operation)) {
+            if (operation === 'replies.create')
+                normalized.parentId ??= null;
+            if (operation === 'posts.update' && normalized.mentions === undefined)
+                return normalized;
+            const mentions = [];
+            for (const supplied of (normalized.mentions ?? [])) {
+                let actor;
+                try {
+                    actor = await this.resolveActor(supplied, true);
+                }
+                catch (error) {
+                    if (error instanceof SynomemError &&
+                        ['AGENT_NOT_FOUND', 'INVALID_INPUT'].includes(error.code))
+                        throw new SynomemError('INVALID_INPUT', 'Mention targets must be active and accessible.');
+                    throw error;
+                }
+                if (!mentions.some((ref) => sameActor(ref, actor)))
+                    mentions.push({ kind: actor.kind, id: actor.id });
+            }
+            normalized.mentions = mentions.sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`));
+        }
+        return normalized;
+    }
+    async authorizeReceipt(operation, result) {
+        if (operation.startsWith('replies.')) {
+            const reply = await this.getReply(result.id);
+            if (operation === 'replies.delete' &&
+                !sameActor(reply.author, this.actor) &&
+                !this.canModerateRoot(await this.getItem(reply.rootId)))
+                throw new SynomemError('MUTATION_FORBIDDEN', 'Moderation authority was removed.');
+            return;
+        }
+        if (operation === 'reactions.set') {
+            await this.reactionRoot(result.targetId);
+            return;
+        }
+        const candidate = result;
+        const id = candidate.record?.event?.id ?? candidate.event?.id;
+        if (!id)
+            throw new SynomemError('IDEMPOTENCY_EXPIRED', 'The cached mutation result cannot be reconstructed.');
+        const record = await this.getItem(id);
+        const event = record.event;
+        if (operation.startsWith('notes.'))
+            this.assertNoteOwner(record);
+        else if (operation.startsWith('todos.'))
+            this.assertTodoOwner(record);
+        else if (operation.startsWith('tasks.') && operation !== 'tasks.create') {
+            if (['tasks.accept', 'tasks.reject'].includes(operation))
+                this.assertTaskAssignee(record);
+            else
+                this.assertTaskParticipant(record);
+            if (operation === 'tasks.overrideDecision' &&
+                (this.actor.kind !== 'human' ||
+                    !(this.administrative ||
+                        (record.event.assignee.kind === 'agent' &&
+                            overseesAgent(this.actor, this.authority, record.event.assignee.id)) ||
+                        (event.actor.kind === 'agent' &&
+                            overseesAgent(this.actor, this.authority, event.actor.id)))))
+                throw new SynomemError('MUTATION_FORBIDDEN', 'Only a human overseer may override a task.');
+        }
+        else if (operation.startsWith('posts.') &&
+            ['posts.update', 'posts.archive'].includes(operation))
+            this.assertPostAuthor(record);
+        else if (operation === 'memos.read')
+            this.assertRecipient(record.event.recipient, 'mark this memo read');
+        else if (operation === 'memos.archive')
+            this.assertRecipient(record.event.recipient, 'archive this memo', true);
+        else if (operation === 'kudos.acknowledge' &&
+            !sameActor(this.actor, record.event.recipient))
+            throw new SynomemError('ACKNOWLEDGMENT_FORBIDDEN', 'Only the recipient may acknowledge kudos.');
+        else if (operation === 'kudos.revoke' && !this.canManage(event.actor))
+            throw new SynomemError('REVOCATION_FORBIDDEN', 'Only the author or an authorized overseer may revoke kudos.');
+        for (const field of ['recipient', 'owner', 'assignee'])
+            if (field in event) {
+                const ref = event[field];
+                await this.syncActor(ref);
+            }
+    }
+    personalWrite(operation) {
+        this.checkAbort();
+        if (!this.writeAllowed)
+            throw new SynomemError('READ_ONLY', 'This binding cannot change personal state.');
+        return this.repository.transaction(async () => {
+            await this.resolveActor(this.boundRef(), true);
+            return operation();
+        });
+    }
+    async mutate(operation, input, action) {
+        this.checkAbort();
+        if (!this.writeAllowed)
+            throw new SynomemError('READ_ONLY', 'This binding cannot write records.');
+        const rawKey = input.idempotencyKey;
+        if (rawKey !== undefined &&
+            (typeof rawKey !== 'string' || !rawKey.trim() || rawKey.trim().length > 200))
+            throw new SynomemError('INVALID_INPUT', 'Idempotency keys must contain 1–200 characters.');
+        const key = typeof rawKey === 'string' ? rawKey.trim() : undefined;
+        const state = { ...(key ? { key } : {}), projections: new Set() };
+        const result = await this.mutationContext.run(state, () => this.repository.transaction(async () => {
+            if (this.actor.kind !== 'system')
+                await this.resolveActor(this.boundRef(), true);
+            const normalized = await this.normalizeMutation(operation, input);
+            const requestHash = cursorFilter({ operation, request: normalized });
+            const keyHash = key ? cursorFilter(key) : undefined;
+            const prior = keyHash
+                ? await this.repository.getMutationReceipt(this.actor.kind, this.actor.id, keyHash)
+                : undefined;
+            if (prior) {
+                if (prior.operation !== operation || prior.requestHash !== requestHash)
+                    throw new SynomemError('IDEMPOTENCY_CONFLICT', 'This key was already used for a different request.');
+                if (!prior.resultJson)
+                    throw new SynomemError('IDEMPOTENCY_EXPIRED', 'The original response expired. This request will not execute again.');
+                const response = JSON.parse(prior.resultJson);
+                await this.authorizeReceipt(operation, response);
+                if (operation === 'replies.create' || operation === 'replies.delete') {
+                    const current = await this.getReply(response.id);
+                    if (current.deleted)
+                        return { ...response, body: undefined, mentions: undefined, deleted: true };
+                }
+                if (response && typeof response === 'object' && 'created' in response)
+                    return { ...response, created: false, deduplicated: true };
+                return response;
+            }
+            if (key &&
+                (await this.repository.getEventByIdempotency(this.actor.kind, this.actor.id, key)))
+                throw new SynomemError('IDEMPOTENCY_EXPIRED', 'The original request receipt is unavailable. This key will not execute again.');
+            const lifecycleOperations = new Set([
+                'kudos.acknowledge',
+                'kudos.revoke',
+                'memos.read',
+                'memos.archive',
+                'posts.archive',
+                'posts.acknowledge',
+                'posts.withdrawAcknowledgment',
+                'notes.archive',
+                'tasks.accept',
+                'tasks.reject',
+                'tasks.complete',
+                'tasks.reopen',
+                'tasks.cancel',
+                'todos.complete',
+                'todos.reopen',
+                'todos.cancel',
+                'todos.archive',
+            ]);
+            if (lifecycleOperations.has(operation)) {
+                const supplied = input.expectedVersion;
+                if (!Number.isSafeInteger(supplied) || supplied < 1)
+                    throw new SynomemError('INVALID_INPUT', 'expectedVersion must be the current positive lifecycleVersion.');
+                const rootId = normalized[(operation.startsWith('kudos.')
+                    ? 'kudos'
+                    : operation.split('.')[0].replace(/s$/, '')) + 'Id'];
+                const current = await this.getItem(rootId);
+                await this.authorizeReceipt(operation, current);
+                if (current.lifecycleVersion !== supplied)
+                    throw new SynomemError('REVISION_CONFLICT', 'The record changed. Refresh before applying this action.');
+            }
+            const response = await action();
+            if (keyHash) {
+                const resultJson = JSON.stringify(response);
+                if (Buffer.byteLength(resultJson) > 262144)
+                    throw new SynomemError('INVALID_INPUT', 'The mutation response exceeds the receipt budget.');
+                const eventId = (key
+                    ? await this.repository.getEventByIdempotency(this.actor.kind, this.actor.id, key)
+                    : undefined)?.id;
+                await this.repository.insertMutationReceipt(this.actor.kind, this.actor.id, keyHash, {
+                    operation,
+                    requestHash,
+                    resultJson,
+                    ...(eventId ? { eventId } : {}),
+                    createdAt: this.now(),
+                });
+            }
+            return response;
+        }));
+        for (const id of state.projections)
+            await this.projectionWriter.syncAgent(id);
+        return result;
+    }
     now() {
         return this.clock().toISOString();
     }
@@ -197,7 +812,10 @@ export class SynomemCore {
     }
     eventBase(aggregateId, aggregateVersion, id = this.nextId()) {
         return {
-            schemaVersion: 1,
+            schemaVersion: 2,
+            ...(this.mutationContext.getStore()?.key
+                ? { idempotencyKey: this.mutationContext.getStore().key }
+                : {}),
             id,
             workspaceId: this.repository.config.workspaceId,
             aggregateId,
@@ -576,13 +1194,13 @@ export class SynomemCore {
             visibility: input.visibility ?? this.repository.config.defaultVisibility,
         }));
         await this.assertTopicsExist(parsed.topicIds);
-        const recipient = await this.repository.getAgent(parsed.recipientAgentId);
+        const recipient = await this.resolveActor(parsed.recipient, true);
         if (!recipient) {
-            throw new SynomemError('AGENT_NOT_FOUND', `Unknown recipient: ${parsed.recipientAgentId}`);
+            throw new SynomemError('AGENT_NOT_FOUND', `Unknown recipient: ${parsed.recipient?.id}`);
         }
         if (!this.repository.config.allowSelfAwards &&
             this.actor.kind !== 'human' &&
-            this.actor.id === recipient.id) {
+            sameActor(this.actor, recipient)) {
             throw new SynomemError('SELF_AWARD_FORBIDDEN', 'Non-human actors cannot award kudos to a matching agent identity.');
         }
         const outcome = await this.repository.transaction(async () => {
@@ -593,7 +1211,7 @@ export class SynomemCore {
             const event = {
                 ...this.eventBase(id, 1, id),
                 type: 'kudos.given',
-                recipientAgentId: recipient.id,
+                recipient: { kind: recipient.kind, id: recipient.id },
                 recipientDisplayName: recipient.displayName,
                 title: parsed.title,
                 reason: parsed.reason,
@@ -609,7 +1227,7 @@ export class SynomemCore {
             return { event, created: true };
         });
         if (outcome.created)
-            await this.projectionWriter.syncAgent(recipient.id);
+            await this.syncActor(recipient);
         const record = await this.getKudosRecord(outcome.event.id);
         return { record, created: outcome.created, deduplicated: !outcome.created };
     }
@@ -618,7 +1236,7 @@ export class SynomemCore {
         const record = recordsFromEvents(await this.repository.getReadableSynomemEvents(id))[0];
         if (!record)
             throw new SynomemError('KUDOS_NOT_FOUND', `Unknown kudos: ${id}`);
-        return record;
+        return this.decorateRecord(record);
     }
     async getKudos(id) {
         this.checkAbort();
@@ -627,15 +1245,15 @@ export class SynomemCore {
     async listKudos(input) {
         this.checkAbort();
         const filters = this.validate(() => listInputSchema.parse(input));
-        const recipient = filters.recipientAgentId
-            ? await this.repository.getAgent(filters.recipientAgentId)
+        const recipient = filters.recipient?.id
+            ? await this.resolveActor(filters.recipient)
             : undefined;
-        if (filters.recipientAgentId && !recipient) {
-            throw new SynomemError('AGENT_NOT_FOUND', `Unknown agent: ${filters.recipientAgentId}`);
+        if (filters.recipient?.id && !recipient) {
+            throw new SynomemError('AGENT_NOT_FOUND', `Unknown agent: ${filters.recipient?.id}`);
         }
         return await this.repository.listKudosSummaries({
             ...filters,
-            ...(recipient ? { recipientAgentId: recipient.id } : {}),
+            ...(recipient ? { recipient: { kind: recipient.kind, id: recipient.id } } : {}),
         }, this.actor);
     }
     async listKudosChanges(input) {
@@ -654,19 +1272,19 @@ export class SynomemCore {
             return record;
         if (record.revocation)
             throw new SynomemError('INVALID_INPUT', 'Revoked kudos cannot be acknowledged.');
-        const isRecipient = this.actor.kind === 'agent' && this.actor.id === record.event.recipientAgentId;
-        if (!this.administrative && !isRecipient) {
-            throw new SynomemError('ACKNOWLEDGMENT_FORBIDDEN', 'Only the recipient agent or a human administrator may acknowledge kudos.');
+        const isRecipient = sameActor(this.actor, record.event.recipient);
+        if (!isRecipient) {
+            throw new SynomemError('ACKNOWLEDGMENT_FORBIDDEN', 'Only the recipient may acknowledge kudos.');
         }
         const event = {
             ...this.eventBase(record.event.id, 2),
             type: 'kudos.acknowledged',
             kudosId: record.event.id,
-            recipientAgentId: record.event.recipientAgentId,
+            recipient: record.event.recipient,
             ...(input.note ? { note: input.note.trim() } : {}),
         };
         await this.repository.transaction(() => this.repository.insertEvent(event));
-        await this.projectionWriter.syncAgent(record.event.recipientAgentId);
+        await this.syncActor(record.event.recipient);
         return await this.getKudosRecord(input.kudosId);
     }
     async revokeKudos(input) {
@@ -684,18 +1302,19 @@ export class SynomemCore {
             throw new SynomemError('REVOCATION_FORBIDDEN', 'Only an administrator may request an administrative revocation.');
         }
         const administrative = this.administrative && !isOriginalActor;
-        if (!isOriginalActor && !this.administrative) {
-            throw new SynomemError('REVOCATION_FORBIDDEN', 'Only the original actor or an administrator may revoke kudos.');
+        if (!this.canManage(record.event.actor)) {
+            throw new SynomemError('REVOCATION_FORBIDDEN', 'Only the author or an authorized overseer may revoke kudos.');
         }
         const event = {
             ...this.eventBase(record.event.id, record.acknowledgment ? 3 : 2),
+            ...this.intervention(record.event.actor, reason),
             type: 'kudos.revoked',
             kudosId: record.event.id,
             reason,
             mode: administrative && !isOriginalActor ? 'administrative' : 'actor-requested',
         };
         await this.repository.transaction(() => this.repository.insertEvent(event));
-        await this.projectionWriter.syncAgent(record.event.recipientAgentId);
+        await this.syncActor(record.event.recipient);
         return await this.getKudosRecord(input.kudosId);
     }
     async priorMutation(idempotencyKey, expectedType) {
@@ -708,13 +1327,13 @@ export class SynomemCore {
         return prior;
     }
     canViewItem(summary) {
+        if (summary.kind === 'note' || summary.kind === 'todo')
+            return !!summary.owner && this.canManage(summary.owner);
         return (this.administrative ||
             summary.visibility !== 'private' ||
-            (summary.actor.kind === this.actor.kind && summary.actor.id === this.actor.id) ||
-            (this.actor.kind === 'agent' &&
-                (summary.recipientAgentId === this.actor.id ||
-                    summary.ownerAgentId === this.actor.id ||
-                    summary.assigneeAgentId === this.actor.id)));
+            [summary.actor, summary.recipient, summary.assignee].some((ref) => !!ref &&
+                (sameActor(ref, this.actor) ||
+                    (ref.kind === 'agent' && overseesAgent(this.actor, this.authority, ref.id)))));
     }
     async requireVisibleItem(id, kind) {
         const summary = await this.repository.getItemSummary(id);
@@ -738,7 +1357,7 @@ export class SynomemCore {
         const record = memoRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
         if (!record)
             throw new SynomemError('MEMO_NOT_FOUND', `Unknown memo: ${id}`);
-        return record;
+        return this.decorateRecord(record);
     }
     async getMemo(id) {
         this.checkAbort();
@@ -749,9 +1368,9 @@ export class SynomemCore {
         await this.repository.assertEventCompatibility();
         const parsed = this.validate(() => sendMemoSchema.parse(input));
         await this.assertTopicsExist(parsed.topicIds);
-        const recipient = await this.repository.getAgent(parsed.recipientAgentId);
+        const recipient = await this.resolveActor(parsed.recipient, true);
         if (!recipient)
-            throw new SynomemError('AGENT_NOT_FOUND', `Unknown recipient: ${parsed.recipientAgentId}`);
+            throw new SynomemError('AGENT_NOT_FOUND', `Unknown recipient: ${parsed.recipient?.id}`);
         const outcome = await this.repository.transaction(async () => {
             const prior = await this.priorMutation(parsed.idempotencyKey, 'memo.sent');
             if (prior?.type === 'memo.sent')
@@ -760,7 +1379,7 @@ export class SynomemCore {
             const event = {
                 ...this.eventBase(id, 1, id),
                 type: 'memo.sent',
-                recipientAgentId: recipient.id,
+                recipient: { kind: recipient.kind, id: recipient.id },
                 recipientDisplayName: recipient.displayName,
                 subject: parsed.subject,
                 body: parsed.body,
@@ -775,22 +1394,20 @@ export class SynomemCore {
             return { id, created: true };
         });
         if (outcome.created)
-            await this.projectionWriter.syncAgent(recipient.id);
+            await this.syncActor(recipient);
         return {
             record: await this.getMemoRecord(outcome.id),
             created: outcome.created,
             deduplicated: !outcome.created,
         };
     }
-    assertRecipient(recipientAgentId, operation) {
-        if (!this.administrative &&
-            !(this.actor.kind === 'agent' && this.actor.id === recipientAgentId)) {
-            throw new SynomemError('MUTATION_FORBIDDEN', `Only the recipient agent or a human administrator may ${operation}.`);
-        }
+    assertRecipient(recipient, operation, oversight = false) {
+        if (!(oversight ? this.canManage(recipient) : sameActor(this.actor, recipient)))
+            throw new SynomemError('MUTATION_FORBIDDEN', `Only the recipient may ${operation}.`);
     }
     async readMemo(input) {
         const record = await this.getMemoRecord(input.memoId);
-        this.assertRecipient(record.event.recipientAgentId, 'mark this memo read');
+        this.assertRecipient(record.event.recipient, 'mark this memo read');
         if (record.read)
             return record;
         await this.repository.transaction(async () => {
@@ -801,17 +1418,17 @@ export class SynomemCore {
                 ...this.eventBase(record.event.id, await this.repository.nextAggregateVersion(record.event.id)),
                 type: 'memo.read',
                 memoId: record.event.id,
-                recipientAgentId: record.event.recipientAgentId,
+                recipient: record.event.recipient,
                 ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
             };
             await this.repository.insertEvent(event);
         });
-        await this.projectionWriter.syncAgent(record.event.recipientAgentId);
+        await this.syncActor(record.event.recipient);
         return await this.getMemoRecord(input.memoId);
     }
     async archiveMemo(input) {
         const record = await this.getMemoRecord(input.memoId);
-        this.assertRecipient(record.event.recipientAgentId, 'archive this memo');
+        this.assertRecipient(record.event.recipient, 'archive this memo', true);
         if (record.archived)
             return record;
         await this.repository.transaction(async () => {
@@ -819,15 +1436,16 @@ export class SynomemCore {
             if (prior)
                 return;
             const event = {
+                ...this.intervention(record.event.recipient),
                 ...this.eventBase(record.event.id, await this.repository.nextAggregateVersion(record.event.id)),
                 type: 'memo.archived',
                 memoId: record.event.id,
-                recipientAgentId: record.event.recipientAgentId,
+                recipient: record.event.recipient,
                 ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
             };
             await this.repository.insertEvent(event);
         });
-        await this.projectionWriter.syncAgent(record.event.recipientAgentId);
+        await this.syncActor(record.event.recipient);
         return await this.getMemoRecord(input.memoId);
     }
     async getPostRecord(id) {
@@ -835,21 +1453,30 @@ export class SynomemCore {
         const record = postRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
         if (!record)
             throw new SynomemError('ITEM_NOT_FOUND', `Unknown post: ${id}`);
-        return record;
+        return this.decorateRecord(record);
     }
     async getPost(id) {
         this.checkAbort();
         return await this.getPostRecord(id);
     }
+    async canonicalPostMentions(input) {
+        const mentions = [];
+        for (const reference of input) {
+            const actor = await this.resolveActor(reference, true);
+            const ref = { kind: actor.kind, id: actor.id };
+            if (!mentions.some((mention) => sameActor(mention, ref)))
+                mentions.push(ref);
+        }
+        return mentions.sort((left, right) => `${left.kind}:${left.id}`.localeCompare(`${right.kind}:${right.id}`));
+    }
     async createPost(input) {
         this.checkAbort();
         await this.repository.assertEventCompatibility();
         const parsed = this.validate(() => createPostSchema.parse(input));
         await this.assertTopicsExist(parsed.topicIds);
-        // 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 mentions = parsed.mentions
+            ? await this.canonicalPostMentions(parsed.mentions)
+            : undefined;
         const outcome = await this.repository.transaction(async () => {
             const prior = await this.priorMutation(parsed.idempotencyKey, 'post.created');
             if (prior?.type === 'post.created')
@@ -860,9 +1487,9 @@ export class SynomemCore {
                 type: 'post.created',
                 title: parsed.title,
                 body: parsed.body,
+                mentions: mentions ?? [],
                 tags: [...new Set(parsed.tags ?? [])].sort(),
                 topicIds: [...new Set(parsed.topicIds ?? [])].sort(),
-                ...(parsed.replyTo ? { replyTo: parsed.replyTo } : {}),
                 ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
                 ...(parsed.source ? { source: parsed.source } : {}),
                 ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
@@ -878,7 +1505,9 @@ export class SynomemCore {
     }
     /** Only the author edits a post. Everyone else responds to it. */
     assertPostAuthor(record) {
-        if (this.administrative)
+        if (this.administrative ||
+            (record.event.actor.kind === 'agent' &&
+                overseesAgent(this.actor, this.authority, record.event.actor.id)))
             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.');
@@ -888,6 +1517,9 @@ export class SynomemCore {
         this.checkAbort();
         const parsed = this.validate(() => updatePostSchema.parse(input));
         await this.assertTopicsExist(parsed.topicIds);
+        const mentions = parsed.mentions
+            ? await this.canonicalPostMentions(parsed.mentions)
+            : undefined;
         const record = await this.getPostRecord(parsed.postId);
         this.assertPostAuthor(record);
         if (record.status === 'archived') {
@@ -898,11 +1530,13 @@ export class SynomemCore {
         }
         await this.repository.transaction(async () => {
             const event = {
+                ...this.intervention(record.event.actor),
                 ...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,
+                mentions: mentions ?? record.mentions ?? [],
                 tags: [...new Set(parsed.tags ?? record.tags ?? [])].sort(),
                 topicIds: [...new Set(parsed.topicIds ?? record.topicIds ?? [])].sort(),
                 ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
@@ -918,6 +1552,7 @@ export class SynomemCore {
         if (record.status !== 'archived') {
             await this.repository.transaction(async () => {
                 const event = {
+                    ...this.intervention(record.event.actor),
                     ...this.eventBase(input.postId, await this.repository.nextAggregateVersion(input.postId)),
                     type: 'post.archived',
                     postId: input.postId,
@@ -979,7 +1614,7 @@ export class SynomemCore {
         const record = noteRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
         if (!record)
             throw new SynomemError('NOTE_NOT_FOUND', `Unknown note: ${id}`);
-        return record;
+        return this.decorateRecord(record);
     }
     async getNote(id) {
         this.checkAbort();
@@ -990,15 +1625,9 @@ export class SynomemCore {
         await this.repository.assertEventCompatibility();
         const parsed = this.validate(() => createNoteSchema.parse(input));
         await this.assertTopicsExist(parsed.topicIds);
-        const ownerId = parsed.ownerAgentId ?? (this.actor.kind === 'agent' ? this.actor.id : undefined);
-        if (!ownerId)
-            throw new SynomemError('INVALID_INPUT', 'A human or system actor must specify ownerAgentId.');
-        const owner = await this.repository.getAgent(ownerId);
-        if (!owner)
-            throw new SynomemError('AGENT_NOT_FOUND', `Unknown note owner: ${ownerId}`);
-        if (!this.administrative && (this.actor.kind !== 'agent' || this.actor.id !== owner.id)) {
-            throw new SynomemError('MUTATION_FORBIDDEN', 'Agents may create notes only for themselves.');
-        }
+        const owner = await this.resolveActor(parsed.owner ?? this.boundRef(), true);
+        if (!this.canManage(owner))
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the owner or an authorized overseer may create private memory.');
         const outcome = await this.repository.transaction(async () => {
             const prior = await this.priorMutation(parsed.idempotencyKey, 'note.created');
             if (prior?.type === 'note.created')
@@ -1006,8 +1635,9 @@ export class SynomemCore {
             const id = this.nextId();
             const event = {
                 ...this.eventBase(id, 1, id),
+                ...this.intervention({ kind: owner.kind, id: owner.id }),
                 type: 'note.created',
-                ownerAgentId: owner.id,
+                owner: { kind: owner.kind, id: owner.id },
                 ownerDisplayName: owner.displayName,
                 title: parsed.title,
                 body: parsed.body,
@@ -1022,7 +1652,7 @@ export class SynomemCore {
             return { id, created: true };
         });
         if (outcome.created)
-            await this.projectionWriter.syncAgent(owner.id);
+            await this.syncActor(owner);
         return {
             record: await this.getNoteRecord(outcome.id),
             created: outcome.created,
@@ -1030,10 +1660,8 @@ export class SynomemCore {
         };
     }
     assertNoteOwner(record) {
-        if (!this.administrative &&
-            !(this.actor.kind === 'agent' && this.actor.id === record.event.ownerAgentId)) {
-            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the note owner or a human administrator may change it.');
-        }
+        if (!this.canManage(record.event.owner))
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the owner or an authorized overseer may change private memory.');
     }
     async reviseNote(input) {
         const parsed = this.validate(() => reviseNoteSchema.parse(input));
@@ -1052,6 +1680,7 @@ export class SynomemCore {
                 parsed.expectedVersion + 1)
                 throw new SynomemError('REVISION_CONFLICT', 'The note changed before this revision was stored.');
             const event = {
+                ...this.intervention(record.event.owner),
                 ...this.eventBase(record.event.id, parsed.expectedVersion + 1),
                 type: 'note.revised',
                 noteId: record.event.id,
@@ -1066,7 +1695,7 @@ export class SynomemCore {
             };
             await this.repository.insertEvent(event);
         });
-        await this.projectionWriter.syncAgent(record.event.ownerAgentId);
+        await this.syncActor(record.event.owner);
         return await this.getNoteRecord(parsed.noteId);
     }
     async archiveNote(input) {
@@ -1079,6 +1708,7 @@ export class SynomemCore {
             if (prior)
                 return;
             const event = {
+                ...this.intervention(record.event.owner),
                 ...this.eventBase(record.event.id, await this.repository.nextAggregateVersion(record.event.id)),
                 type: 'note.archived',
                 noteId: record.event.id,
@@ -1086,7 +1716,7 @@ export class SynomemCore {
             };
             await this.repository.insertEvent(event);
         });
-        await this.projectionWriter.syncAgent(record.event.ownerAgentId);
+        await this.syncActor(record.event.owner);
         return await this.getNoteRecord(input.noteId);
     }
     async getTaskRecord(id) {
@@ -1094,7 +1724,7 @@ export class SynomemCore {
         const record = taskRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
         if (!record)
             throw new SynomemError('TODO_NOT_FOUND', `Unknown task: ${id}`);
-        return record;
+        return this.decorateRecord(record);
     }
     async getTask(id) {
         this.checkAbort();
@@ -1105,26 +1735,21 @@ export class SynomemCore {
         await this.repository.assertEventCompatibility();
         const parsed = this.validate(() => createTaskSchema.parse(input));
         await this.assertTopicsExist(parsed.topicIds);
-        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 task assignee: ${assigneeId}`);
+        const assignee = await this.resolveActor(parsed.assignee ?? this.boundRef(), true);
         if (this.actor.kind === 'agent' &&
-            this.actor.id !== assignee.id &&
+            !sameActor(this.actor, assignee) &&
             !this.repository.config.allowCrossAgentTasks)
-            throw new SynomemError('POLICY_FORBIDDEN', 'Cross-agent task assignment is disabled.');
+            throw new SynomemError('POLICY_FORBIDDEN', 'Cross-actor task assignment is disabled.');
         const outcome = await this.repository.transaction(async () => {
             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 requiresAcceptance = !sameActor(this.actor, assignee);
             const event = {
                 ...this.eventBase(id, 1, id),
                 type: 'task.created',
-                assigneeAgentId: assignee.id,
+                assignee: { kind: assignee.kind, id: assignee.id },
                 assigneeDisplayName: assignee.displayName,
                 title: parsed.title,
                 ...(parsed.description !== undefined ? { description: parsed.description } : {}),
@@ -1142,7 +1767,7 @@ export class SynomemCore {
             return { id, created: true };
         });
         if (outcome.created)
-            await this.projectionWriter.syncAgent(assignee.id);
+            await this.syncActor(assignee);
         return {
             record: await this.getTaskRecord(outcome.id),
             created: outcome.created,
@@ -1150,16 +1775,12 @@ export class SynomemCore {
         };
     }
     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 task creator, assignee, or a human administrator may change it.');
+        if (!this.canManage(record.event.assignee) && !this.canManage(record.event.actor))
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Only task participants or authorized overseers may change it.');
     }
     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 task.');
-        }
+        if (!this.canManage(record.event.assignee))
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the assignee or an authorized overseer may decide this task.');
     }
     async updateTask(input) {
         const parsed = this.validate(() => updateTaskSchema.parse(input));
@@ -1179,6 +1800,7 @@ export class SynomemCore {
                 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.intervention(record.event.assignee),
                 ...this.eventBase(record.event.id, parsed.expectedVersion + 1),
                 type: 'task.updated',
                 taskId: record.event.id,
@@ -1199,9 +1821,41 @@ export class SynomemCore {
             };
             await this.repository.insertEvent(event);
         });
-        await this.projectionWriter.syncAgent(record.event.assigneeAgentId);
+        await this.syncActor(record.event.assignee);
         return await this.getTaskRecord(parsed.taskId);
     }
+    async overrideTaskDecision(input) {
+        this.checkAbort();
+        const parsed = this.validate(() => overrideTaskDecisionSchema.parse(input));
+        await this.repository.transaction(async () => {
+            const record = await this.getTaskRecord(parsed.taskId);
+            if (this.actor.kind !== 'human' ||
+                !(this.administrative ||
+                    (record.event.assignee.kind === 'agent' &&
+                        overseesAgent(this.actor, this.authority, record.event.assignee.id)) ||
+                    (record.event.actor.kind === 'agent' &&
+                        overseesAgent(this.actor, this.authority, record.event.actor.id))))
+                throw new SynomemError('MUTATION_FORBIDDEN', 'Only an authorized human overseer may override a decision.');
+            if (record.current.version !== parsed.expectedVersion)
+                throw new SynomemError('REVISION_CONFLICT', 'The task changed. Reload it before overriding.');
+            if (record.status !== 'open' && record.status !== 'rejected')
+                throw new SynomemError('INVALID_INPUT', 'Only accepted/open or rejected decisions can be overridden.');
+            if (record.status === parsed.nextStatus)
+                throw new SynomemError('INVALID_INPUT', 'The requested decision is already in effect.');
+            const event = {
+                ...this.eventBase(parsed.taskId, parsed.expectedVersion + 1),
+                ...this.intervention(record.event.assignee, parsed.reason),
+                type: 'task.decision_overridden',
+                taskId: parsed.taskId,
+                previousStatus: record.status,
+                nextStatus: parsed.nextStatus,
+                reason: parsed.reason,
+                ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
+            };
+            await this.repository.insertEvent(event);
+        });
+        return this.getTaskRecord(parsed.taskId);
+    }
     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
@@ -1240,6 +1894,7 @@ export class SynomemCore {
             if (prior)
                 return;
             const base = {
+                ...this.intervention(record.event.assignee),
                 ...this.eventBase(record.event.id, await this.repository.nextAggregateVersion(record.event.id)),
                 taskId: record.event.id,
                 ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
@@ -1259,7 +1914,7 @@ export class SynomemCore {
                             : { ...base, type };
             await this.repository.insertEvent(event);
         });
-        await this.projectionWriter.syncAgent(record.event.assigneeAgentId);
+        await this.syncActor(record.event.assignee);
         return await this.getTaskRecord(input.taskId);
     }
     completeTask(input) {
@@ -1289,6 +1944,9 @@ export class SynomemCore {
         await this.repository.assertEventCompatibility();
         const parsed = this.validate(() => createTodoSchema.parse(input));
         await this.assertTopicsExist(parsed.topicIds);
+        const owner = await this.resolveActor(parsed.owner ?? this.boundRef(), true);
+        if (!this.canManage(owner))
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the owner or an authorized overseer may create private memory.');
         const outcome = await this.repository.transaction(async () => {
             const prior = await this.priorMutation(parsed.idempotencyKey, 'todo.created');
             if (prior?.type === 'todo.created')
@@ -1296,7 +1954,9 @@ export class SynomemCore {
             const id = this.nextId();
             const event = {
                 ...this.eventBase(id, 1, id),
+                ...this.intervention({ kind: owner.kind, id: owner.id }),
                 type: 'todo.created',
+                owner: { kind: owner.kind, id: owner.id },
                 title: parsed.title,
                 ...(parsed.details !== undefined ? { details: parsed.details } : {}),
                 priority: parsed.priority ?? 3,
@@ -1321,7 +1981,7 @@ export class SynomemCore {
         if (!record)
             throw new SynomemError('ITEM_NOT_FOUND', `Unknown todo: ${id}`);
         this.assertTodoOwner(record);
-        return record;
+        return this.decorateRecord(record);
     }
     /**
      * Todos are owner-only for every ordinary actor — the same rule notes
@@ -1335,10 +1995,8 @@ export class SynomemCore {
      * on top of a permission that had already been granted.
      */
     assertTodoOwner(record) {
-        const owner = record.event.actor;
-        if (!this.administrative && (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.');
-        }
+        if (!this.canManage(record.event.owner))
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the owner or an authorized overseer may change private memory.');
     }
     async getTodo(id) {
         this.checkAbort();
@@ -1358,6 +2016,7 @@ export class SynomemCore {
             if (prior)
                 return;
             const event = {
+                ...this.intervention(record.event.owner),
                 ...this.eventBase(record.event.id, await this.repository.nextAggregateVersion(record.event.id)),
                 type: 'todo.updated',
                 todoId: record.event.id,
@@ -1377,6 +2036,7 @@ export class SynomemCore {
     }
     async todoTransition(input, type) {
         const record = await this.getTodoRecord(input.todoId);
+        this.assertTodoOwner(record);
         if (type === 'todo.completed' && record.status !== 'open') {
             if (record.status === 'completed')
                 return record;
@@ -1431,10 +2091,10 @@ export class SynomemCore {
         const parsed = this.validate(() => itemListInputSchema.parse(input));
         const resolved = {
             ...parsed,
-            ...(parsed.participantAgentId
-                ? { participantAgentId: await this.canonicalAgentId(parsed.participantAgentId) }
+            ...(parsed.participant ? { participant: await this.resolveActor(parsed.participant) } : {}),
+            ...(parsed.actorId && parsed.actorKind === 'agent'
+                ? { actorId: await this.canonicalAgentId(parsed.actorId) }
                 : {}),
-            ...(parsed.actorId ? { actorId: await this.canonicalAgentId(parsed.actorId) } : {}),
         };
         return await this.repository.listItemSummaries(resolved, this.actor);
     }
@@ -1473,11 +2133,11 @@ export class SynomemCore {
         void _cursor;
         void _limit;
         void _offset;
-        const recipient = filters.recipientAgentId
-            ? await this.repository.getAgent(filters.recipientAgentId)
+        const recipient = filters.recipient?.id
+            ? await this.resolveActor(filters.recipient)
             : undefined;
-        if (filters.recipientAgentId && !recipient) {
-            throw new SynomemError('AGENT_NOT_FOUND', `Unknown agent: ${filters.recipientAgentId}`);
+        if (filters.recipient?.id && !recipient) {
+            throw new SynomemError('AGENT_NOT_FOUND', `Unknown agent: ${filters.recipient?.id}`);
         }
         const records = [];
         let cursor;
@@ -1486,7 +2146,7 @@ export class SynomemCore {
         while (hasMore) {
             const page = await this.repository.listKudosSummaries({
                 ...filters,
-                ...(recipient ? { recipientAgentId: recipient.id } : {}),
+                ...(recipient ? { recipient: { kind: recipient.kind, id: recipient.id } } : {}),
                 limit: 50,
                 offset: 0,
                 ...(cursor ? { cursor } : {}),
@@ -1508,7 +2168,7 @@ export class SynomemCore {
             byTag: {},
         };
         for (const record of includedRecords) {
-            stats.byAgent[record.recipientAgentId] = (stats.byAgent[record.recipientAgentId] ?? 0) + 1;
+            stats.byAgent[record.recipient?.id] = (stats.byAgent[record.recipient?.id] ?? 0) + 1;
             const actor = `${record.actor.kind}:${record.actor.id}`;
             stats.byActor[actor] = (stats.byActor[actor] ?? 0) + 1;
             for (const tag of record.tags)
@@ -1523,8 +2183,8 @@ export class SynomemCore {
  * check that silently lags the migration runner reports a healthy database as
  * broken.
  */
-const CURRENT_SCHEMA_VERSION = 8;
-const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5, 6, 7, 8];
+const CURRENT_SCHEMA_VERSION = 9;
+const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5, 6, 7, 8, 9];
 export class SynomemClient extends SynomemCore {
     home;
     storage;
@@ -1533,7 +2193,9 @@ export class SynomemClient extends SynomemCore {
         const home = resolveHome(options.home);
         const storage = new SynomemStorage({
             home,
+            ...(options.actor ? { actor: options.actor } : {}),
             readOnly: options.readOnly ?? false,
+            ...(options.authority ? { authority: options.authority } : {}),
             ...(options.config ? { config: options.config } : {}),
         });
         const projections = new ProjectionManager(storage);
@@ -1541,10 +2203,11 @@ export class SynomemClient extends SynomemCore {
             repository: storage,
             projectionWriter: projections,
             ...(options.actor ? { actor: options.actor } : {}),
-            ...(options.administrative !== undefined ? { administrative: options.administrative } : {}),
+            ...(options.authority ? { authority: options.authority } : {}),
             ...(options.clock ? { clock: options.clock } : {}),
             ...(options.idGenerator ? { idGenerator: options.idGenerator } : {}),
             ...(options.signal ? { signal: options.signal } : {}),
+            canWrite: !options.readOnly,
         });
         this.home = home;
         this.storage = storage;
@@ -1714,7 +2377,33 @@ export class SynomemClient extends SynomemCore {
     }
     async export(format) {
         this.checkAbort();
-        const rows = this.storage.rawEventRows();
+        const rows = [];
+        const access = new Map();
+        for (const row of this.storage.rawEventRows()) {
+            let event;
+            try {
+                event = eventSchema.parse(JSON.parse(row.payload));
+            }
+            catch {
+                if (this.administrative)
+                    rows.push(row);
+                continue;
+            }
+            const rootId = 'rootId' in event ? event.rootId : event.aggregateId;
+            if (event.type.startsWith('agent.')) {
+                if (this.administrative)
+                    rows.push(row);
+                continue;
+            }
+            if (!access.has(rootId))
+                access.set(rootId, this.storage.canActorReadItem(rootId, this.actor));
+            if (!access.get(rootId))
+                continue;
+            if (event.type === 'reply.created' &&
+                (await this.storage.participation.getReply(event.id))?.deleted)
+                continue;
+            rows.push(row);
+        }
         if (format === 'jsonl')
             return `${rows.map((row) => row.payload).join('\n')}\n`;
         const exported = rows.map((row) => {
@@ -1728,7 +2417,8 @@ export class SynomemClient extends SynomemCore {
         if (format === 'json')
             return `${JSON.stringify(exported, null, 2)}\n`;
         const scan = this.storage.scanEvents();
-        const events = scan.events;
+        const allowedIds = new Set(rows.map((row) => row.id));
+        const events = scan.events.filter((event) => allowedIds.has(event.id));
         const records = recordsFromEvents(events);
         const memos = memoRecordsFromEvents(events);
         const notes = noteRecordsFromEvents(events);
@@ -1756,6 +2446,16 @@ export class SynomemClient extends SynomemCore {
         this.checkAbort();
         return {
             backend: 'local',
+            participation: {
+                version: 2,
+                replies: true,
+                reactions: true,
+                personalInbox: true,
+                search: false,
+                canWrite: !this.storage.readOnly,
+                administrator: this.administrative,
+                managedAgentIds: [...this.authority.operatedAgentIds],
+            },
             binding: { workspaceId: this.storage.config.workspaceId, actor: this.actor },
             administration: {
                 agentCreationViaMcp: this.storage.config.allowAgentCreationViaMcp,
@@ -1771,7 +2471,23 @@ export class SynomemClient extends SynomemCore {
     }
     async getCanonicalEvent(id) {
         this.checkAbort();
-        return this.storage.getEvent(id);
+        const event = this.storage.getEvent(id);
+        if (!event)
+            return undefined;
+        if (event.type.startsWith('agent.'))
+            return this.administrative ? event : undefined;
+        const rootId = 'rootId' in event ? event.rootId : event.aggregateId;
+        if (!this.storage.canActorReadItem(rootId, this.actor))
+            throw new SynomemError('POLICY_FORBIDDEN', 'This event is not visible.');
+        if (event.type === 'reply.created' &&
+            (await this.storage.participation.getReply(event.id))?.deleted)
+            return undefined;
+        return event;
     }
 }
+export function createLocalOwnerClient(options = {}) {
+    if (options.actor?.kind !== 'human')
+        throw new SynomemError('POLICY_FORBIDDEN', 'Local owner administration requires an explicit human actor.');
+    return new SynomemClient({ ...options, authority: localOwnerAuthority() });
+}
 //# sourceMappingURL=client.js.map