synomem 0.2.0 → 0.4.0

package/dist/client.js

@@ -4,10 +4,14 @@ import { ulid } from 'ulid';
 import { resolveHome } from './config.js';
 import { asSynomemError, SynomemError } from './errors.js';
 import { assertNoSymlinkEscape } from './fs-utils.js';
-import { escapeMarkdown, memoRecordsFromEvents, noteRecordsFromEvents, ProjectionManager, recordsFromEvents, taskRecordsFromEvents, todoRecordsFromEvents, } from './projections.js';
-import { actorSchema, agentLookupSchema, bindRuntimeSchema, createAgentSchema, createNoteSchema, createTaskSchema, createTodoSchema, changesInputSchema, giveKudosSchema, itemListInputSchema, listInputSchema, reviseNoteSchema, sendMemoSchema, updateTaskSchema, updateTodoSchema, updateAgentSchema, } from './schemas.js';
+import { escapeMarkdown, memoRecordsFromEvents, noteRecordsFromEvents, postRecordsFromEvents, ProjectionManager, recordsFromEvents, taskRecordsFromEvents, todoRecordsFromEvents, } from './projections.js';
+import { actorSchema, agentLookupSchema, bindRuntimeSchema, createAgentSchema, createPostSchema, updatePostSchema, createNoteSchema, createTaskSchema, createTodoSchema, changesInputSchema, giveKudosSchema, itemListInputSchema, listInputSchema, reviseNoteSchema, sendMemoSchema, updateTaskSchema, updateTodoSchema, updateAgentSchema, } from './schemas.js';
 import { SynomemStorage } from './storage.js';
 export class SynomemCore {
+    /**
+     * Mutable because an agent actor is resolved to its canonical identity on
+     * init: callers name a handle, events record the opaque ID.
+     */
     actor;
     repository;
     projectionWriter;
@@ -22,6 +26,10 @@ export class SynomemCore {
         get: (idOrAlias) => this.getAgent(idOrAlias),
         list: () => this.listAgents(),
         resolve: (query) => this.resolveAgent(query),
+        archive: (idOrAlias) => this.setAgentStatus(idOrAlias, 'archived'),
+        restore: (idOrAlias) => this.setAgentStatus(idOrAlias, 'active'),
+        addAliases: (idOrAlias, aliases) => this.addAgentAliases(idOrAlias, aliases),
+        removeAliases: (idOrAlias, aliases) => this.removeAgentAliases(idOrAlias, aliases),
         directory: () => this.agentDirectory(),
         bindings: (idOrAlias) => this.listRuntimeBindings(idOrAlias),
         bindRuntime: (input) => this.bindRuntime(input),
@@ -42,6 +50,22 @@ export class SynomemCore {
         read: (input) => this.readMemo(input),
         archive: (input) => this.archiveMemo(input),
     };
+    posts = {
+        create: (input) => this.createPost(input),
+        list: (input = {}) => this.listItems({ ...input, kinds: ['post'] }),
+        get: (id) => this.getPost(id),
+        update: (input) => this.updatePost(input),
+        archive: (input) => this.archivePost(input),
+        /*
+         * Acknowledging is an explicit call and always speaks for the caller alone.
+         * There is no bulk form and no acknowledge-on-behalf-of: an acknowledgement
+         * is one actor saying "I have seen this", and reading a post must never
+         * append one, or the roster stops meaning anything.
+         */
+        acknowledge: (input) => this.acknowledgePost(input),
+        withdrawAcknowledgment: (input) => this.withdrawPostAcknowledgment(input),
+        roster: (postId) => this.postRoster(postId),
+    };
     notes = {
         create: (input) => this.createNote(input),
         list: (input = {}) => this.listItems({ ...input, kinds: ['note'] }),
@@ -128,6 +152,29 @@ export class SynomemCore {
             return;
         await this.repository.init();
         this.initialized = true;
+        /*
+         * An agent actor is resolved to its canonical identity here.
+         *
+         * Callers name a handle because that is what people and harnesses know,
+         * but every event must record the opaque ID — otherwise renaming a handle
+         * would orphan the history written under the old one. The display name
+         * comes from the profile for the same reason a harness cannot assert it on
+         * the command line: the stored record is the authority, not the argument.
+         *
+         * An unresolvable name is left as given rather than rejected, so a system
+         * actor can still create the agent that does not exist yet. Writing as an
+         * unknown agent is refused later by the checks that already exist.
+         */
+        if (this.actor.kind === 'agent') {
+            const resolved = await this.repository.resolveAgent(this.actor.id);
+            if (resolved.match) {
+                this.actor = {
+                    kind: 'agent',
+                    id: resolved.match.id,
+                    ...(resolved.match.displayName ? { displayName: resolved.match.displayName } : {}),
+                };
+            }
+        }
     }
     async close() {
         await this.repository.close();
@@ -165,20 +212,29 @@ export class SynomemCore {
         this.checkAbort();
         await this.repository.assertEventCompatibility();
         const parsed = this.validate(() => createAgentSchema.parse(input));
-        if (await this.repository.getAgent(parsed.id)) {
-            throw new SynomemError('AGENT_EXISTS', `Agent or alias already exists: ${parsed.id}`);
+        if (await this.repository.getAgent(parsed.handle)) {
+            throw new SynomemError('AGENT_EXISTS', `Agent or alias already exists: ${parsed.handle}`);
         }
         const aliases = [...new Set(parsed.aliases ?? [])].sort();
-        if (aliases.includes(parsed.id)) {
-            throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own ID as an alias.');
+        if (aliases.includes(parsed.handle)) {
+            throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own handle as an alias.');
         }
         for (const alias of aliases) {
             if (await this.repository.getAgent(alias)) {
                 throw new SynomemError('ALIAS_CONFLICT', `Alias already belongs to an agent: ${alias}`);
             }
         }
+        /*
+         * The canonical ID is generated here and never supplied by the caller.
+         * Every event references it permanently, so it has to be free of meaning:
+         * a caller that could choose it could choose one that collides with an
+         * archived agent's history, and a meaningful ID becomes a handle nobody can
+         * rename.
+         */
         const profile = {
-            id: parsed.id,
+            id: this.nextId(),
+            handle: parsed.handle,
+            status: 'active',
             displayName: parsed.displayName,
             ...(aliases.length ? { aliases } : {}),
             ...(parsed.description !== undefined ? { description: parsed.description } : {}),
@@ -206,8 +262,17 @@ export class SynomemCore {
         if (!existing)
             throw new SynomemError('AGENT_NOT_FOUND', `Unknown agent: ${idOrAlias}`);
         const aliases = parsed.aliases ? [...new Set(parsed.aliases)].sort() : existing.aliases;
-        if (aliases?.includes(existing.id)) {
-            throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own ID as an alias.');
+        const handle = parsed.handle ?? existing.handle;
+        if (aliases?.includes(handle)) {
+            throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own handle as an alias.');
+        }
+        // Renaming the handle is allowed and is why the canonical ID exists, but a
+        // handle another agent already answers to is still refused.
+        if (parsed.handle && parsed.handle !== existing.handle) {
+            const owner = await this.repository.getAgent(parsed.handle);
+            if (owner && owner.id !== existing.id) {
+                throw new SynomemError('ALIAS_CONFLICT', `Handle already belongs to ${owner.id}: ${parsed.handle}`);
+            }
         }
         for (const alias of aliases ?? []) {
             const owner = await this.repository.getAgent(alias);
@@ -234,6 +299,48 @@ export class SynomemCore {
         await this.projectionWriter.syncAgent(updated.id);
         return updated;
     }
+    /**
+     * Archiving stops an agent acting without erasing it.
+     *
+     * Events reference the actor permanently, so deleting an agent would leave
+     * history pointing at nothing. Archived agents keep their records and their
+     * handle, and can be restored.
+     */
+    async setAgentStatus(idOrAlias, status) {
+        this.checkAbort();
+        await this.repository.assertEventCompatibility();
+        this.validate(() => agentLookupSchema.parse(idOrAlias));
+        const existing = await this.repository.getAgent(idOrAlias);
+        if (!existing)
+            throw new SynomemError('AGENT_NOT_FOUND', `Unknown agent: ${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: 'agent.updated',
+                agentId: existing.id,
+                changes: { status },
+            };
+            await this.repository.updateAgent(updated, event.createdAt);
+            await this.repository.insertEvent(event);
+        });
+        await this.projectionWriter.syncAgent(updated.id);
+        return updated;
+    }
+    /** Adds aliases without disturbing the ones already there. */
+    async addAgentAliases(idOrAlias, add) {
+        const existing = await this.getAgent(idOrAlias);
+        const merged = [...new Set([...(existing.aliases ?? []), ...add])].sort();
+        return await this.updateAgent(existing.id, { aliases: merged });
+    }
+    async removeAgentAliases(idOrAlias, remove) {
+        const existing = await this.getAgent(idOrAlias);
+        const drop = new Set(remove.map((alias) => alias.trim().toLowerCase()));
+        const kept = (existing.aliases ?? []).filter((alias) => !drop.has(alias));
+        return await this.updateAgent(existing.id, { aliases: kept });
+    }
     async getAgent(idOrAlias) {
         this.checkAbort();
         this.validate(() => agentLookupSchema.parse(idOrAlias));
@@ -569,6 +676,146 @@ export class SynomemCore {
         await this.projectionWriter.syncAgent(record.event.recipientAgentId);
         return await this.getMemoRecord(input.memoId);
     }
+    async getPostRecord(id) {
+        await this.requireVisibleItem(id, 'post');
+        const record = postRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
+        if (!record)
+            throw new SynomemError('ITEM_NOT_FOUND', `Unknown post: ${id}`);
+        return record;
+    }
+    async getPost(id) {
+        this.checkAbort();
+        return await this.getPostRecord(id);
+    }
+    async createPost(input) {
+        this.checkAbort();
+        await this.repository.assertEventCompatibility();
+        const parsed = this.validate(() => createPostSchema.parse(input));
+        // A reply inherits its parent's workspace by construction, and cannot name
+        // a different target — there is no target to name.
+        if (parsed.replyTo)
+            await this.requireVisibleItem(parsed.replyTo, 'post');
+        const outcome = await this.repository.transaction(async () => {
+            const prior = await this.priorMutation(parsed.idempotencyKey, 'post.created');
+            if (prior?.type === 'post.created')
+                return { id: prior.id, created: false };
+            const id = this.nextId();
+            const event = {
+                ...this.eventBase(id, 1, id),
+                type: 'post.created',
+                title: parsed.title,
+                body: parsed.body,
+                tags: [...new Set(parsed.tags ?? [])].sort(),
+                ...(parsed.replyTo ? { replyTo: parsed.replyTo } : {}),
+                ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
+                ...(parsed.source ? { source: parsed.source } : {}),
+                ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
+            };
+            await this.repository.insertEvent(event);
+            return { id, created: true };
+        });
+        return {
+            record: await this.getPostRecord(outcome.id),
+            created: outcome.created,
+            deduplicated: !outcome.created,
+        };
+    }
+    /** Only the author edits a post. Everyone else responds to it. */
+    assertPostAuthor(record) {
+        if (this.administrative)
+            return;
+        if (record.event.actor.id !== this.actor.id || record.event.actor.kind !== this.actor.kind) {
+            throw new SynomemError('MUTATION_FORBIDDEN', 'Only the author can change a post.');
+        }
+    }
+    async updatePost(input) {
+        this.checkAbort();
+        const parsed = this.validate(() => updatePostSchema.parse(input));
+        const record = await this.getPostRecord(parsed.postId);
+        this.assertPostAuthor(record);
+        if (record.status === 'archived') {
+            throw new SynomemError('MUTATION_FORBIDDEN', 'An archived post cannot be edited.');
+        }
+        if (record.version !== parsed.expectedVersion) {
+            throw new SynomemError('REVISION_CONFLICT', `Post ${parsed.postId} is at version ${record.version}.`);
+        }
+        await this.repository.transaction(async () => {
+            const event = {
+                ...this.eventBase(parsed.postId, await this.repository.nextAggregateVersion(parsed.postId)),
+                type: 'post.edited',
+                postId: parsed.postId,
+                title: parsed.title ?? record.title,
+                body: parsed.body ?? record.body,
+                tags: [...new Set(parsed.tags ?? record.tags ?? [])].sort(),
+                ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
+            };
+            await this.repository.insertEvent(event);
+        });
+        return await this.getPostRecord(parsed.postId);
+    }
+    async archivePost(input) {
+        this.checkAbort();
+        const record = await this.getPostRecord(input.postId);
+        this.assertPostAuthor(record);
+        if (record.status !== 'archived') {
+            await this.repository.transaction(async () => {
+                const event = {
+                    ...this.eventBase(input.postId, await this.repository.nextAggregateVersion(input.postId)),
+                    type: 'post.archived',
+                    postId: input.postId,
+                    ...(input.reason ? { reason: input.reason } : {}),
+                    ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+                };
+                await this.repository.insertEvent(event);
+            });
+        }
+        return await this.getPostRecord(input.postId);
+    }
+    async acknowledgePost(input) {
+        this.checkAbort();
+        const record = await this.getPostRecord(input.postId);
+        // Acknowledging twice is the same statement, so the second is a no-op
+        // rather than a second row or an error.
+        const already = record.acknowledgments.some((entry) => entry.actor.id === this.actor.id && entry.actor.kind === this.actor.kind);
+        if (!already) {
+            await this.repository.transaction(async () => {
+                const event = {
+                    ...this.eventBase(input.postId, await this.repository.nextAggregateVersion(input.postId)),
+                    type: 'post.acknowledged',
+                    postId: input.postId,
+                    ...(input.note ? { note: input.note } : {}),
+                    ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+                };
+                await this.repository.insertEvent(event);
+            });
+        }
+        return await this.getPostRecord(input.postId);
+    }
+    async withdrawPostAcknowledgment(input) {
+        this.checkAbort();
+        const record = await this.getPostRecord(input.postId);
+        const mine = record.acknowledgments.some((entry) => entry.actor.id === this.actor.id && entry.actor.kind === this.actor.kind);
+        if (mine) {
+            await this.repository.transaction(async () => {
+                const event = {
+                    ...this.eventBase(input.postId, await this.repository.nextAggregateVersion(input.postId)),
+                    type: 'post.acknowledgment.withdrawn',
+                    postId: input.postId,
+                    ...(input.reason ? { reason: input.reason } : {}),
+                };
+                await this.repository.insertEvent(event);
+            });
+        }
+        return await this.getPostRecord(input.postId);
+    }
+    async postRoster(postId) {
+        this.checkAbort();
+        await this.requireVisibleItem(postId, 'post');
+        const roster = await this.repository.postRoster(postId);
+        if (!roster)
+            throw new SynomemError('ITEM_NOT_FOUND', `Unknown post: ${postId}`);
+        return roster;
+    }
     async getNoteRecord(id) {
         await this.requireVisibleItem(id, 'note');
         const record = noteRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
@@ -986,10 +1233,34 @@ export class SynomemCore {
         });
         return await this.getTodoRecord(input.todoId);
     }
+    /**
+     * Turns an agent name in a filter into the canonical ID the records hold.
+     *
+     * Callers filter by the name they know — a handle or an alias — while every
+     * record stores the opaque ID. Without this the filter silently matches
+     * nothing, which reads as "there is nothing here" rather than "that name
+     * means something else now".
+     *
+     * An unresolvable name is passed through unchanged so it can match a legacy
+     * name-shaped ID rather than being swallowed.
+     */
+    async canonicalAgentId(name) {
+        if (!name)
+            return name;
+        const resolved = await this.repository.resolveAgent(name);
+        return resolved.match?.id ?? name;
+    }
     async listItems(input) {
         this.checkAbort();
         const parsed = this.validate(() => itemListInputSchema.parse(input));
-        return await this.repository.listItemSummaries(parsed, this.actor);
+        const resolved = {
+            ...parsed,
+            ...(parsed.participantAgentId
+                ? { participantAgentId: await this.canonicalAgentId(parsed.participantAgentId) }
+                : {}),
+            ...(parsed.actorId ? { actorId: await this.canonicalAgentId(parsed.actorId) } : {}),
+        };
+        return await this.repository.listItemSummaries(resolved, this.actor);
     }
     async listItemChanges(input) {
         this.checkAbort();
@@ -1072,8 +1343,8 @@ export class SynomemCore {
  * check that silently lags the migration runner reports a healthy database as
  * broken.
  */
-const CURRENT_SCHEMA_VERSION = 5;
-const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5];
+const CURRENT_SCHEMA_VERSION = 7;
+const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5, 6, 7];
 export class SynomemClient extends SynomemCore {
     home;
     storage;