synomem 0.6.11 → 0.7.0

package/dist/client.js

@@ -5,7 +5,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, } from './schemas.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 { SynomemStorage } from './storage.js';
 export class SynomemCore {
     /**
@@ -35,6 +35,15 @@ export class SynomemCore {
         bindRuntime: (input) => this.bindRuntime(input),
         unbindRuntime: (bindingId) => this.unbindRuntime(bindingId),
     };
+    topics = {
+        create: (input) => this.createTopic(input),
+        update: (idOrAlias, changes) => this.updateTopicRecord(idOrAlias, changes),
+        get: (idOrAlias) => this.getTopicRecord(idOrAlias),
+        list: (input = {}) => this.listTopicsRecord(input),
+        resolve: (query) => this.resolveTopicRecord(query),
+        archive: (idOrAlias) => this.setTopicStatus(idOrAlias, 'archived'),
+        restore: (idOrAlias) => this.setTopicStatus(idOrAlias, 'active'),
+    };
     kudos = {
         give: (input) => this.giveKudos(input),
         list: (input = {}) => this.listKudos(input),
@@ -427,6 +436,138 @@ export class SynomemCore {
         this.checkAbort();
         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.
+     */
+    async createTopic(input) {
+        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 = {
+            id: this.nextId(),
+            displayName: parsed.displayName,
+            ...(aliases.length ? { aliases } : {}),
+            status: 'active',
+            createdAt: this.now(),
+        };
+        const event = {
+            ...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;
+    }
+    async updateTopicRecord(idOrAlias, changes) {
+        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 = {
+            ...existing,
+            ...parsed,
+            ...(aliases?.length ? { aliases } : { aliases: undefined }),
+        };
+        const changesForEvent = { ...parsed, ...(parsed.aliases ? { aliases } : {}) };
+        await this.repository.transaction(async () => {
+            const event = {
+                ...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;
+    }
+    async setTopicStatus(idOrAlias, status) {
+        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 = { ...existing, status };
+        await this.repository.transaction(async () => {
+            const event = {
+                ...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;
+    }
+    async getTopicRecord(idOrAlias) {
+        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;
+    }
+    async listTopicsRecord(input) {
+        this.checkAbort();
+        const parsed = this.validate(() => topicListInputSchema.parse(input));
+        return await this.repository.listTopics(parsed.status);
+    }
+    async resolveTopicRecord(query) {
+        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.
+     */
+    async assertTopicsExist(topicIds) {
+        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}`);
+            }
+        }
+    }
     async giveKudos(input) {
         this.checkAbort();
         await this.repository.assertEventCompatibility();
@@ -434,6 +575,7 @@ export class SynomemCore {
             ...input,
             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}`);
@@ -458,6 +600,7 @@ export class SynomemCore {
                 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 } : {}),
@@ -605,6 +748,7 @@ export class SynomemCore {
         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}`);
@@ -621,6 +765,7 @@ export class SynomemCore {
                 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 } : {}),
@@ -700,6 +845,7 @@ export class SynomemCore {
         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)
@@ -715,6 +861,7 @@ export class SynomemCore {
                 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 } : {}),
@@ -740,6 +887,7 @@ export class SynomemCore {
     async updatePost(input) {
         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') {
@@ -756,6 +904,7 @@ export class SynomemCore {
                 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);
@@ -840,6 +989,7 @@ export class SynomemCore {
         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)
             throw new SynomemError('INVALID_INPUT', 'A human or system actor must specify ownerAgentId.');
@@ -862,6 +1012,7 @@ export class SynomemCore {
                 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 } : {}),
@@ -886,6 +1037,7 @@ export class SynomemCore {
     }
     async reviseNote(input) {
         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')
@@ -906,6 +1058,7 @@ export class SynomemCore {
                 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 } : {}),
@@ -951,6 +1104,7 @@ export class SynomemCore {
         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)
             throw new SynomemError('INVALID_INPUT', 'A human or system actor must specify assigneeAgentId.');
@@ -977,6 +1131,7 @@ export class SynomemCore {
                 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 } : {}),
@@ -1008,6 +1163,7 @@ export class SynomemCore {
     }
     async updateTask(input) {
         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')
@@ -1035,6 +1191,7 @@ export class SynomemCore {
                 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 } : {}),
@@ -1131,6 +1288,7 @@ export class SynomemCore {
         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')
@@ -1144,6 +1302,7 @@ export class SynomemCore {
                 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 } : {}),
@@ -1188,6 +1347,7 @@ export class SynomemCore {
     async updateTodo(input) {
         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('REVISION_CONFLICT', `Todo ${parsed.todoId} is at version ${record.current.version}.`);
@@ -1208,6 +1368,7 @@ export class SynomemCore {
                 priority: parsed.priority ?? record.current.priority,
                 ...(due ? { due } : {}),
                 tags: [...new Set(parsed.tags ?? record.current.tags)].sort(),
+                topicIds: [...new Set(parsed.topicIds ?? record.current.topicIds)].sort(),
                 ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
             };
             await this.repository.insertEvent(event);
@@ -1362,8 +1523,8 @@ export class SynomemCore {
  * 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 {
     home;
     storage;