synomem 0.6.11 → 0.7.0

package/src/client.ts

@@ -33,6 +33,10 @@ import {
   updateTaskSchema,
   updateTodoSchema,
   updateAgentSchema,
+  createTopicSchema,
+  updateTopicSchema,
+  topicListInputSchema,
+  topicLookupSchema,
 } from './schemas.js';
 import { SynomemStorage } from './storage.js';
 import type {
@@ -78,6 +82,11 @@ import type {
   TodoRecord,
   ItemListInput,
   ItemRecord,
+  Topic,
+  CreateTopicInput,
+  UpdateTopicInput,
+  TopicListInput,
+  TopicResolution,
   ItemSummary,
   ChangesInput,
   KudosChangesInput,
@@ -137,6 +146,17 @@ export class SynomemCore implements SynomemDomainService {
     unbindRuntime: (bindingId: string) => this.unbindRuntime(bindingId),
   };
 
+  readonly topics = {
+    create: (input: CreateTopicInput) => this.createTopic(input),
+    update: (idOrAlias: string, changes: UpdateTopicInput) =>
+      this.updateTopicRecord(idOrAlias, changes),
+    get: (idOrAlias: string) => this.getTopicRecord(idOrAlias),
+    list: (input: TopicListInput = {}) => this.listTopicsRecord(input),
+    resolve: (query: string) => this.resolveTopicRecord(query),
+    archive: (idOrAlias: string) => this.setTopicStatus(idOrAlias, 'archived'),
+    restore: (idOrAlias: string) => this.setTopicStatus(idOrAlias, 'active'),
+  };
+
   readonly kudos = {
     give: (input: GiveKudosInput) => this.giveKudos(input),
     list: (input: KudosListInput = {}) => this.listKudos(input),
@@ -578,6 +598,148 @@ export class SynomemCore implements SynomemDomainService {
     return await this.repository.unbindRuntime(bindingId);
   }
 
+  /* ---------------------------------------------------------------- topics *
+   * A topic is a controlled, reusable subject a record can be filed under —
+   * one canonical display name and a set of aliases, so a stable "Synomem"
+   * page survives a rename without retagging every record that carries it.
+   * Any actor may create one freely, the same as a tag; only the creator or
+   * an administrator renames or archives it, matching how an agent's own
+   * identity is managed.
+   */
+
+  private async createTopic(input: CreateTopicInput): Promise<Topic> {
+    this.checkAbort();
+    await this.repository.assertEventCompatibility();
+    const parsed = this.validate(() => createTopicSchema.parse(input));
+    if (await this.repository.getTopic(parsed.displayName)) {
+      throw new SynomemError(
+        'TOPIC_EXISTS',
+        `Topic or alias already exists: ${parsed.displayName}`,
+      );
+    }
+    const aliases = [...new Set(parsed.aliases ?? [])].sort();
+    for (const alias of aliases) {
+      if (await this.repository.getTopic(alias)) {
+        throw new SynomemError('ALIAS_CONFLICT', `Alias already belongs to a topic: ${alias}`);
+      }
+    }
+    const topic: Topic = {
+      id: this.nextId(),
+      displayName: parsed.displayName,
+      ...(aliases.length ? { aliases } : {}),
+      status: 'active',
+      createdAt: this.now(),
+    };
+    const event: SynomemEvent = {
+      ...this.eventBase(topic.id, 1),
+      type: 'topic.created',
+      topic,
+    };
+    await this.repository.transaction(async () => {
+      await this.repository.insertTopic(topic);
+      await this.repository.insertEvent(event);
+    });
+    return topic;
+  }
+
+  private async updateTopicRecord(idOrAlias: string, changes: UpdateTopicInput): Promise<Topic> {
+    this.checkAbort();
+    await this.repository.assertEventCompatibility();
+    this.validate(() => topicLookupSchema.parse(idOrAlias));
+    const parsed = this.validate(() => updateTopicSchema.parse(changes));
+    const existing = await this.repository.getTopic(idOrAlias);
+    if (!existing) throw new SynomemError('TOPIC_NOT_FOUND', `Unknown topic: ${idOrAlias}`);
+    if (parsed.displayName && parsed.displayName !== existing.displayName) {
+      const owner = await this.repository.getTopic(parsed.displayName);
+      if (owner && owner.id !== existing.id) {
+        throw new SynomemError(
+          'ALIAS_CONFLICT',
+          `Display name already belongs to ${owner.id}: ${parsed.displayName}`,
+        );
+      }
+    }
+    const aliases = parsed.aliases ? [...new Set(parsed.aliases)].sort() : existing.aliases;
+    for (const alias of aliases ?? []) {
+      const owner = await this.repository.getTopic(alias);
+      if (owner && owner.id !== existing.id) {
+        throw new SynomemError('ALIAS_CONFLICT', `Alias already belongs to ${owner.id}: ${alias}`);
+      }
+    }
+    const updated: Topic = {
+      ...existing,
+      ...parsed,
+      ...(aliases?.length ? { aliases } : { aliases: undefined }),
+    };
+    const changesForEvent = { ...parsed, ...(parsed.aliases ? { aliases } : {}) };
+    await this.repository.transaction(async () => {
+      const event: SynomemEvent = {
+        ...this.eventBase(existing.id, await this.repository.nextAggregateVersion(existing.id)),
+        type: 'topic.updated',
+        topicId: existing.id,
+        changes: changesForEvent,
+      };
+      await this.repository.updateTopic(updated, event.createdAt);
+      await this.repository.insertEvent(event);
+    });
+    return updated;
+  }
+
+  private async setTopicStatus(idOrAlias: string, status: 'active' | 'archived'): Promise<Topic> {
+    this.checkAbort();
+    await this.repository.assertEventCompatibility();
+    this.validate(() => topicLookupSchema.parse(idOrAlias));
+    const existing = await this.repository.getTopic(idOrAlias);
+    if (!existing) throw new SynomemError('TOPIC_NOT_FOUND', `Unknown topic: ${idOrAlias}`);
+    if (existing.status === status) return existing;
+    const updated: Topic = { ...existing, status };
+    await this.repository.transaction(async () => {
+      const event: SynomemEvent = {
+        ...this.eventBase(existing.id, await this.repository.nextAggregateVersion(existing.id)),
+        type: 'topic.updated',
+        topicId: existing.id,
+        changes: { status },
+      };
+      await this.repository.updateTopic(updated, event.createdAt);
+      await this.repository.insertEvent(event);
+    });
+    return updated;
+  }
+
+  private async getTopicRecord(idOrAlias: string): Promise<Topic> {
+    this.checkAbort();
+    this.validate(() => topicLookupSchema.parse(idOrAlias));
+    const topic = await this.repository.getTopic(idOrAlias);
+    if (!topic) throw new SynomemError('TOPIC_NOT_FOUND', `Unknown topic: ${idOrAlias}`);
+    return topic;
+  }
+
+  private async listTopicsRecord(input: TopicListInput): Promise<Topic[]> {
+    this.checkAbort();
+    const parsed = this.validate(() => topicListInputSchema.parse(input));
+    return await this.repository.listTopics(parsed.status);
+  }
+
+  private async resolveTopicRecord(query: string): Promise<TopicResolution> {
+    this.checkAbort();
+    const trimmed = this.validate(() => topicLookupSchema.parse(query));
+    const resolved = await this.repository.resolveTopic(trimmed);
+    return { query: trimmed, ...resolved };
+  }
+
+  /**
+   * Every topic in `topicIds` must already exist and be active — a record
+   * cannot be filed under a subject that does not exist, or one somebody
+   * archived precisely to stop new records collecting under it.
+   */
+  private async assertTopicsExist(topicIds: string[] | undefined): Promise<void> {
+    for (const topicId of topicIds ?? []) {
+      const topic = await this.repository.getTopic(topicId);
+      if (!topic || topic.status !== 'active') {
+        throw new SynomemError('TOPIC_NOT_FOUND', `Unknown or archived topic: ${topicId}`);
+      }
+    }
+  }
+
   private async giveKudos(input: GiveKudosInput): Promise<GiveKudosResult> {
     this.checkAbort();
     await this.repository.assertEventCompatibility();
@@ -587,6 +749,7 @@ export class SynomemCore implements SynomemDomainService {
         visibility: input.visibility ?? this.repository.config.defaultVisibility,
       }),
     );
+    await this.assertTopicsExist(parsed.topicIds);
     const recipient = await this.repository.getAgent(parsed.recipientAgentId);
     if (!recipient) {
       throw new SynomemError('AGENT_NOT_FOUND', `Unknown recipient: ${parsed.recipientAgentId}`);
@@ -616,6 +779,7 @@ export class SynomemCore implements SynomemDomainService {
         visibility: parsed.visibility,
         ...(parsed.evidence ? { evidence: parsed.evidence } : {}),
         ...(parsed.tags ? { tags: [...new Set(parsed.tags)].sort() } : {}),
+        ...(parsed.topicIds ? { topicIds: [...new Set(parsed.topicIds)].sort() } : {}),
         ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
         ...(parsed.source ? { source: parsed.source } : {}),
         ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
@@ -803,6 +967,7 @@ export class SynomemCore implements SynomemDomainService {
     this.checkAbort();
     await this.repository.assertEventCompatibility();
     const parsed = this.validate(() => sendMemoSchema.parse(input));
+    await this.assertTopicsExist(parsed.topicIds);
     const recipient = await this.repository.getAgent(parsed.recipientAgentId);
     if (!recipient)
       throw new SynomemError('AGENT_NOT_FOUND', `Unknown recipient: ${parsed.recipientAgentId}`);
@@ -818,6 +983,7 @@ export class SynomemCore implements SynomemDomainService {
         subject: parsed.subject,
         body: parsed.body,
         tags: [...new Set(parsed.tags ?? [])].sort(),
+        topicIds: [...new Set(parsed.topicIds ?? [])].sort(),
         visibility: parsed.visibility ?? this.repository.config.defaultVisibility,
         ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
         ...(parsed.source ? { source: parsed.source } : {}),
@@ -915,6 +1081,7 @@ export class SynomemCore implements SynomemDomainService {
     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.
@@ -930,6 +1097,7 @@ export class SynomemCore implements SynomemDomainService {
         title: parsed.title,
         body: parsed.body,
         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 } : {}),
@@ -956,6 +1124,7 @@ export class SynomemCore implements SynomemDomainService {
   private async updatePost(input: UpdatePostInput): Promise<PostRecord> {
     this.checkAbort();
     const parsed = this.validate(() => updatePostSchema.parse(input));
+    await this.assertTopicsExist(parsed.topicIds);
     const record = await this.getPostRecord(parsed.postId);
     this.assertPostAuthor(record);
     if (record.status === 'archived') {
@@ -975,6 +1144,7 @@ export class SynomemCore implements SynomemDomainService {
         title: parsed.title ?? record.title,
         body: parsed.body ?? record.body,
         tags: [...new Set(parsed.tags ?? record.tags ?? [])].sort(),
+        topicIds: [...new Set(parsed.topicIds ?? record.topicIds ?? [])].sort(),
         ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
       };
       await this.repository.insertEvent(event);
@@ -1078,6 +1248,7 @@ export class SynomemCore implements SynomemDomainService {
     this.checkAbort();
     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)
@@ -1099,6 +1270,7 @@ export class SynomemCore implements SynomemDomainService {
         title: parsed.title,
         body: parsed.body,
         tags: [...new Set(parsed.tags ?? [])].sort(),
+        topicIds: [...new Set(parsed.topicIds ?? [])].sort(),
         visibility: 'private',
         ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
         ...(parsed.source ? { source: parsed.source } : {}),
@@ -1129,6 +1301,7 @@ export class SynomemCore implements SynomemDomainService {
 
   private async reviseNote(input: ReviseNoteInput): Promise<NoteRecord> {
     const parsed = this.validate(() => reviseNoteSchema.parse(input));
+    await this.assertTopicsExist(parsed.topicIds);
     const record = await this.getNoteRecord(parsed.noteId);
     this.assertNoteOwner(record);
     if (record.status === 'archived')
@@ -1156,6 +1329,7 @@ export class SynomemCore implements SynomemDomainService {
         title: parsed.title ?? record.current.title,
         body: parsed.body ?? record.current.body,
         tags: parsed.tags ?? record.current.tags,
+        topicIds: parsed.topicIds ?? record.current.topicIds,
         visibility: 'private',
         ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
         ...(parsed.source ? { source: parsed.source } : {}),
@@ -1207,6 +1381,7 @@ export class SynomemCore implements SynomemDomainService {
     this.checkAbort();
     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)
@@ -1238,6 +1413,7 @@ export class SynomemCore implements SynomemDomainService {
         priority: parsed.priority ?? 3,
         ...(parsed.due ? { due: parsed.due } : {}),
         tags: [...new Set(parsed.tags ?? [])].sort(),
+        topicIds: [...new Set(parsed.topicIds ?? [])].sort(),
         visibility: parsed.visibility ?? this.repository.config.defaultVisibility,
         requiresAcceptance,
         ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
@@ -1281,6 +1457,7 @@ export class SynomemCore implements SynomemDomainService {
 
   private async updateTask(input: UpdateTaskInput): Promise<TaskRecord> {
     const parsed = this.validate(() => updateTaskSchema.parse(input));
+    await this.assertTopicsExist(parsed.topicIds);
     const record = await this.getTaskRecord(parsed.taskId);
     this.assertTaskParticipant(record);
     if (record.status !== 'open')
@@ -1315,6 +1492,7 @@ export class SynomemCore implements SynomemDomainService {
         priority: parsed.priority ?? record.current.priority,
         ...(due ? { due } : {}),
         tags: parsed.tags ?? record.current.tags,
+        topicIds: parsed.topicIds ?? record.current.topicIds,
         visibility: parsed.visibility ?? record.current.visibility,
         ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
         ...(parsed.source ? { source: parsed.source } : {}),
@@ -1425,6 +1603,7 @@ export class SynomemCore implements SynomemDomainService {
     this.checkAbort();
     await this.repository.assertEventCompatibility();
     const parsed = this.validate(() => createTodoSchema.parse(input));
+    await this.assertTopicsExist(parsed.topicIds);
     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 };
@@ -1437,6 +1616,7 @@ export class SynomemCore implements SynomemDomainService {
         priority: parsed.priority ?? 3,
         ...(parsed.due ? { due: parsed.due } : {}),
         tags: [...new Set(parsed.tags ?? [])].sort(),
+        topicIds: [...new Set(parsed.topicIds ?? [])].sort(),
         ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
         ...(parsed.source ? { source: parsed.source } : {}),
         ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
@@ -1487,6 +1667,7 @@ export class SynomemCore implements SynomemDomainService {
   private async updateTodo(input: UpdateTodoInput): Promise<TodoRecord> {
     this.checkAbort();
     const parsed = this.validate(() => updateTodoSchema.parse(input));
+    await this.assertTopicsExist(parsed.topicIds);
     const record = await this.getTodoRecord(parsed.todoId);
     if (record.current.version !== parsed.expectedVersion) {
       throw new SynomemError(
@@ -1512,6 +1693,7 @@ export class SynomemCore implements SynomemDomainService {
         priority: parsed.priority ?? record.current.priority,
         ...(due ? { due } : {}),
         tags: [...new Set<string>(parsed.tags ?? record.current.tags)].sort(),
+        topicIds: [...new Set<string>(parsed.topicIds ?? record.current.topicIds)].sort(),
         ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
       };
       await this.repository.insertEvent(event);
@@ -1681,8 +1863,8 @@ export class SynomemCore implements SynomemDomainService {
  * check that silently lags the migration runner reports a healthy database as
  * broken.
  */
-const CURRENT_SCHEMA_VERSION = 7;
-const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5, 6, 7];
+const CURRENT_SCHEMA_VERSION = 8;
+const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5, 6, 7, 8];
 
 export class SynomemClient extends SynomemCore implements SynomemService {
   readonly home: string;

package/src/errors.ts

@@ -8,6 +8,8 @@ export const errorCodes = [
   'AGENT_NOT_FOUND',
   'AGENT_EXISTS',
   'ALIAS_CONFLICT',
+  'TOPIC_NOT_FOUND',
+  'TOPIC_EXISTS',
   'KUDOS_NOT_FOUND',
   'ITEM_NOT_FOUND',
   'MEMO_NOT_FOUND',

package/src/mcp/index.ts

@@ -19,6 +19,8 @@ import {
   sendMemoSchema,
   updateTaskSchema,
   updateTodoSchema,
+  topicNameSchema,
+  topicAliasSchema,
 } from '../schemas.js';
 import { packageVersion } from '../version.js';
 import type { SynomemService, SynomemServiceFactory } from '../service.js';
@@ -132,7 +134,7 @@ export async function createSynomemMcpServer(
     { name: 'synomem', version: packageVersion() },
     {
       instructions:
-        'Use Synomem for durable kudos, memos, notes, posts, tasks, and todos. Pick by who the record is for: a task is work assigned to another agent, which they must accept; a todo is your own private reminder that no other agent can see or assign (the human administrator can still see it in the Synomem dashboard); a post tells everyone in the workspace something and records who acknowledged it. Store only necessary, factual content; never secrets or raw sensitive tool output. The server binds every write to its configured actor.',
+        'Use Synomem for durable kudos, memos, notes, posts, tasks, and todos. Pick by who the record is for: a task is work assigned to another agent, which they must accept; a todo is your own private reminder that no other agent can see or assign (the human administrator can still see it in the Synomem dashboard); a post tells everyone in the workspace something and records who acknowledged it. Any record may also carry topicIds — synomem_topic_resolve or synomem_topic_list first, synomem_topic_create only if none already fits — for a stable cross-kind subject (like "Synomem" itself) that tags cannot give, since a tag is a loose free-text label with no identity of its own. Store only necessary, factual content; never secrets or raw sensitive tool output. The server binds every write to its configured actor.',
     },
   );
 
@@ -552,6 +554,143 @@ export async function createSynomemMcpServer(
     },
   );
 
+  server.registerTool(
+    'synomem_topic_create',
+    {
+      title: 'Create a topic',
+      description:
+        'Create a controlled, reusable subject records can be filed under — a stable ID, one canonical display name, and optional aliases, distinct from a free-text tag. Any actor may create one. Use synomem_topic_resolve first to check whether the topic you mean already exists, so "Synomem" is not created twice under two different IDs.',
+      inputSchema: z.object({
+        displayName: topicNameSchema,
+        aliases: z.array(topicAliasSchema).max(20).optional(),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async (input) => {
+      try {
+        const topic = await client.topics.create(input);
+        return success(actor, `Created topic "${topic.displayName}" (ID ${topic.id}).`, { topic });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_topic_update',
+    {
+      title: 'Rename a topic or change its aliases',
+      description:
+        "Rename a topic or replace its aliases without changing its ID — every record already filed under it stays filed under it. Only the topic's creator or an administrator may do this.",
+      inputSchema: z.object({
+        idOrAlias: z.string().min(1).describe('A topic ID or alias, in any casing.'),
+        displayName: topicNameSchema.optional(),
+        aliases: z.array(topicAliasSchema).max(20).optional(),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async ({ idOrAlias, ...changes }) => {
+      try {
+        const topic = await client.topics.update(idOrAlias, changes);
+        return success(actor, `Updated topic "${topic.displayName}" (ID ${topic.id}).`, { topic });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_topic_list',
+    {
+      title: 'List topics',
+      description: 'List known topics. This is read-only.',
+      inputSchema: z.object({ status: z.enum(['active', 'archived']).optional() }),
+      outputSchema,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    },
+    async (input) => {
+      try {
+        const topics = await client.topics.list(input);
+        return success(actor, `Found ${topics.length} topic(s).`, { topics });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_topic_resolve',
+    {
+      title: 'Resolve a topic name',
+      description:
+        'Resolve a name or alias to exactly one topic. Matching ignores case. When several topics answer to the name, no match is returned and the candidates are listed instead — ask which one is meant, or use synomem_topic_create only once neither the name nor an alias already exists.',
+      inputSchema: z.object({
+        query: z.string().min(1).describe('A topic ID or alias, in any casing.'),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    },
+    async ({ query }) => {
+      try {
+        const resolution = await client.topics.resolve(query);
+        const message = resolution.match
+          ? `"${resolution.query}" resolves to ${resolution.match.id}.`
+          : resolution.candidates.length
+            ? `"${resolution.query}" is ambiguous across ${resolution.candidates.length} topics. Ask which one is meant.`
+            : `No topic answers to "${resolution.query}".`;
+        return success(actor, message, resolution);
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_topic_archive',
+    {
+      title: 'Archive a topic',
+      description:
+        "Archive a topic so it can no longer be attached to new records; records already carrying it keep it. Only the topic's creator or an administrator may do this.",
+      inputSchema: z.object({
+        idOrAlias: z.string().min(1).describe('A topic ID or alias, in any casing.'),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    },
+    async ({ idOrAlias }) => {
+      try {
+        const topic = await client.topics.archive(idOrAlias);
+        return success(actor, `Archived topic "${topic.displayName}" (${topic.id}).`, { topic });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_topic_restore',
+    {
+      title: 'Restore an archived topic',
+      description:
+        'Let an archived topic be attached to new records again, using the same ID it always had.',
+      inputSchema: z.object({
+        idOrAlias: z.string().min(1).describe('A topic ID or alias, in any casing.'),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    },
+    async ({ idOrAlias }) => {
+      try {
+        const topic = await client.topics.restore(idOrAlias);
+        return success(actor, `Restored topic "${topic.displayName}" (${topic.id}).`, { topic });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
   server.registerTool(
     'synomem_rebuild',
     {

package/src/ports/repository.ts

@@ -14,6 +14,7 @@ import type {
   SynomemEvent,
   Page,
   RecordKind,
+  Topic,
 } from '../types.js';
 
 /**
@@ -63,6 +64,13 @@ export interface SynomemRepository {
   unbindRuntime(bindingId: string): Awaitable<boolean>;
   touchRuntimeBinding(agentId: string, runtime: string, at: string): Awaitable<void>;
 
+  insertTopic(topic: Topic): Awaitable<void>;
+  updateTopic(topic: Topic, updatedAt: string): Awaitable<void>;
+  getTopic(idOrAlias: string): Awaitable<Topic | undefined>;
+  listTopics(status?: 'active' | 'archived'): Awaitable<Topic[]>;
+  /** Resolves a name case-insensitively, reporting ambiguity instead of guessing. */
+  resolveTopic(query: string): Awaitable<{ match?: Topic; candidates: Topic[] }>;
+
   listKudosSummaries(
     input: Required<Pick<KudosListInput, 'limit' | 'offset'>> & KudosListInput,
     viewer: ActorIdentity,

package/src/projections.ts

@@ -334,6 +334,7 @@ export function noteRecordsFromEvents(events: SynomemEvent[]): NoteRecord[] {
           title: event.title,
           body: event.body,
           tags: event.tags ?? [],
+          topicIds: event.topicIds ?? [],
           visibility: event.visibility,
           version: event.aggregateVersion,
         },
@@ -347,6 +348,7 @@ export function noteRecordsFromEvents(events: SynomemEvent[]): NoteRecord[] {
           title: event.title,
           body: event.body,
           tags: event.tags ?? [],
+          topicIds: event.topicIds ?? [],
           visibility: event.visibility,
           version: event.aggregateVersion,
         };
@@ -382,6 +384,7 @@ export function todoRecordsFromEvents(events: SynomemEvent[]): TodoRecord[] {
           priority: event.priority,
           ...(event.due ? { due: event.due } : {}),
           tags: event.tags ?? [],
+          topicIds: event.topicIds ?? [],
           version: event.aggregateVersion,
         },
         status: 'open',
@@ -396,6 +399,7 @@ export function todoRecordsFromEvents(events: SynomemEvent[]): TodoRecord[] {
           priority: event.priority,
           ...(event.due ? { due: event.due } : {}),
           tags: event.tags ?? [],
+          topicIds: event.topicIds ?? [],
           version: event.aggregateVersion,
         };
       }
@@ -440,6 +444,7 @@ export function taskRecordsFromEvents(events: SynomemEvent[]): TaskRecord[] {
           priority: event.priority,
           ...(event.due ? { due: event.due } : {}),
           tags: event.tags ?? [],
+          topicIds: event.topicIds ?? [],
           visibility: event.visibility,
           version: event.aggregateVersion,
         },
@@ -456,6 +461,7 @@ export function taskRecordsFromEvents(events: SynomemEvent[]): TaskRecord[] {
           priority: event.priority,
           ...(event.due ? { due: event.due } : {}),
           tags: event.tags ?? [],
+          topicIds: event.topicIds ?? [],
           visibility: event.visibility,
           version: event.aggregateVersion,
         };

package/src/remote.ts

@@ -19,6 +19,9 @@ import type {
   UpdateTaskInput,
   UpdateTodoInput,
   CreateTodoInput,
+  CreateTopicInput,
+  UpdateTopicInput,
+  TopicListInput,
 } from './types.js';
 
 const defaultMaximumResponseBytes = 1024 * 1024;
@@ -240,6 +243,48 @@ export class RemoteSynomemService implements SynomemService {
       ),
   };
 
+  readonly topics = {
+    create: (input: CreateTopicInput) =>
+      this.mutation<Awaited<ReturnType<SynomemService['topics']['create']>>>(
+        'POST',
+        'topics',
+        input,
+      ),
+    update: (idOrAlias: string, changes: UpdateTopicInput) =>
+      this.mutation<Awaited<ReturnType<SynomemService['topics']['update']>>>(
+        'PATCH',
+        `topics/${encodeURIComponent(idOrAlias)}`,
+        changes,
+      ),
+    get: (idOrAlias: string) =>
+      this.request<Awaited<ReturnType<SynomemService['topics']['get']>>>(
+        'GET',
+        `topics/${encodeURIComponent(idOrAlias)}`,
+      ),
+    list: (input: TopicListInput = {}) =>
+      this.request<Awaited<ReturnType<SynomemService['topics']['list']>>>(
+        'GET',
+        `topics${queryString(input)}`,
+      ),
+    resolve: (query: string) =>
+      this.request<Awaited<ReturnType<SynomemService['topics']['resolve']>>>(
+        'GET',
+        `topics/resolve?query=${encodeURIComponent(query)}`,
+      ),
+    archive: (idOrAlias: string) =>
+      this.mutation<Awaited<ReturnType<SynomemService['topics']['archive']>>>(
+        'POST',
+        `topics/${encodeURIComponent(idOrAlias)}/archive`,
+        {},
+      ),
+    restore: (idOrAlias: string) =>
+      this.mutation<Awaited<ReturnType<SynomemService['topics']['restore']>>>(
+        'POST',
+        `topics/${encodeURIComponent(idOrAlias)}/restore`,
+        {},
+      ),
+  };
+
   readonly posts = {
     create: (input: CreatePostInput) =>
       this.mutation<Awaited<ReturnType<SynomemService['posts']['create']>>>('POST', 'posts', input),