synomem 0.2.0 → 0.3.0

package/src/client.ts

@@ -8,6 +8,7 @@ import {
   escapeMarkdown,
   memoRecordsFromEvents,
   noteRecordsFromEvents,
+  postRecordsFromEvents,
   ProjectionManager,
   recordsFromEvents,
   taskRecordsFromEvents,
@@ -18,6 +19,8 @@ import {
   agentLookupSchema,
   bindRuntimeSchema,
   createAgentSchema,
+  createPostSchema,
+  updatePostSchema,
   createNoteSchema,
   createTaskSchema,
   createTodoSchema,
@@ -49,6 +52,10 @@ import type {
   AgentRuntimeBinding,
   BindRuntimeInput,
   CreateAgentInput,
+  CreatePostInput,
+  PostRecord,
+  PostRoster,
+  UpdatePostInput,
   Diagnostic,
   DoctorResult,
   GiveKudosInput,
@@ -139,6 +146,27 @@ export class SynomemCore implements SynomemDomainService {
     archive: (input: { memoId: string; idempotencyKey?: string }) => this.archiveMemo(input),
   };
 
+  readonly posts = {
+    create: (input: CreatePostInput) => this.createPost(input),
+    list: (input: Omit<ItemListInput, 'kinds'> = {}) =>
+      this.listItems({ ...input, kinds: ['post'] }),
+    get: (id: string) => this.getPost(id),
+    update: (input: UpdatePostInput) => this.updatePost(input),
+    archive: (input: { postId: string; reason?: string; idempotencyKey?: string }) =>
+      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: { postId: string; note?: string; idempotencyKey?: string }) =>
+      this.acknowledgePost(input),
+    withdrawAcknowledgment: (input: { postId: string; reason?: string }) =>
+      this.withdrawPostAcknowledgment(input),
+    roster: (postId: string) => this.postRoster(postId),
+  };
+
   readonly notes = {
     create: (input: CreateNoteInput) => this.createNote(input),
     list: (input: Omit<ItemListInput, 'kinds'> = {}) =>
@@ -757,6 +785,174 @@ export class SynomemCore implements SynomemDomainService {
     return await this.getMemoRecord(input.memoId);
   }
 
+  private async getPostRecord(id: string): Promise<PostRecord> {
+    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;
+  }
+
+  private async getPost(id: string): Promise<PostRecord> {
+    this.checkAbort();
+    return await this.getPostRecord(id);
+  }
+
+  private async createPost(input: CreatePostInput): Promise<{
+    record: PostRecord;
+    created: boolean;
+    deduplicated: boolean;
+  }> {
+    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: SynomemEvent = {
+        ...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. */
+  private assertPostAuthor(record: PostRecord): void {
+    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.');
+    }
+  }
+
+  private async updatePost(input: UpdatePostInput): Promise<PostRecord> {
+    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: SynomemEvent = {
+        ...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);
+  }
+
+  private async archivePost(input: {
+    postId: string;
+    reason?: string;
+    idempotencyKey?: string;
+  }): Promise<PostRecord> {
+    this.checkAbort();
+    const record = await this.getPostRecord(input.postId);
+    this.assertPostAuthor(record);
+    if (record.status !== 'archived') {
+      await this.repository.transaction(async () => {
+        const event: SynomemEvent = {
+          ...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);
+  }
+
+  private async acknowledgePost(input: {
+    postId: string;
+    note?: string;
+    idempotencyKey?: string;
+  }): Promise<PostRecord> {
+    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: SynomemEvent = {
+          ...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);
+  }
+
+  private async withdrawPostAcknowledgment(input: {
+    postId: string;
+    reason?: string;
+  }): Promise<PostRecord> {
+    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: SynomemEvent = {
+          ...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);
+  }
+
+  private async postRoster(postId: string): Promise<PostRoster> {
+    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;
+  }
+
   private async getNoteRecord(id: string): Promise<NoteRecord> {
     await this.requireVisibleItem(id, 'note');
     const record = noteRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
@@ -1343,8 +1539,8 @@ export class SynomemCore implements SynomemDomainService {
  * 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 = 6;
+const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5, 6];
 
 export class SynomemClient extends SynomemCore implements SynomemService {
   readonly home: string;

package/src/mcp/index.ts

@@ -326,6 +326,82 @@ export async function createSynomemMcpServer(
     },
   );
 
+  server.registerTool(
+    'synomem_post_create',
+    {
+      title: 'Publish a post',
+      description:
+        'Publish something the whole workspace can read. Use for an announcement, a decision, or context several agents need. A post has no recipient — if one named actor must act, send a memo or assign a task instead.',
+      inputSchema: z.object({
+        title: z.string().trim().min(1).max(200),
+        body: z.string().trim().min(1).max(32_000),
+        tags: z.array(z.string()).max(20).optional(),
+        replyTo: z.string().length(26).optional(),
+        idempotencyKey: z.string().max(200).optional(),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async (input) => {
+      try {
+        const result = await client.posts.create(input);
+        return success(actor, `Published post ${result.record.event.id}.`, {
+          post: result.record,
+        });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_post_acknowledge',
+    {
+      title: 'Acknowledge a post',
+      description:
+        'Record that YOU have seen a post. This speaks only for the configured actor and is never implied by reading one: acknowledge when you have actually taken it in, not to clear a list. An optional note tells the author something useful, such as work already done.',
+      inputSchema: z.object({
+        postId: z.string().length(26),
+        note: z.string().trim().min(1).max(2000).optional(),
+        idempotencyKey: z.string().max(200).optional(),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    },
+    async (input) => {
+      try {
+        const record = await client.posts.acknowledge(input);
+        return success(actor, `Acknowledged post ${input.postId}.`, { post: record });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_post_roster',
+    {
+      title: 'See who has acknowledged a post',
+      description:
+        'Who has acknowledged a post and who has not. An outstanding entry means no acknowledgement was recorded — never that somebody has not read it. Agents created after the post are counted separately, because they were not there when it was written. This is read-only and does not acknowledge anything.',
+      inputSchema: z.object({ postId: z.string().length(26) }),
+      outputSchema,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    },
+    async ({ postId }) => {
+      try {
+        const roster = await client.posts.roster(postId);
+        return success(
+          actor,
+          `${roster.acknowledged.length} acknowledged, ${roster.outstanding.length} with no acknowledgement recorded.`,
+          roster,
+        );
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
   server.registerTool(
     'synomem_agent_resolve',
     {

package/src/ports/repository.ts

@@ -5,6 +5,8 @@ import type {
   ChangePage,
   ItemListInput,
   JsonValue,
+  PostAcknowledgment,
+  PostRoster,
   ItemSummary,
   KudosListInput,
   KudosSummary,
@@ -45,6 +47,9 @@ export interface SynomemRepository {
   listAgents(): Awaitable<AgentProfile[]>;
   /** Resolves a name case-insensitively, reporting ambiguity instead of guessing. */
   resolveAgent(query: string): Awaitable<{ match?: AgentProfile; candidates: AgentProfile[] }>;
+  listPostAcknowledgments(postId: string): Awaitable<PostAcknowledgment[]>;
+  /** Who has acknowledged a post and who has not; see PostRoster. */
+  postRoster(postId: string): Awaitable<PostRoster | undefined>;
   listRuntimeBindings(agentId: string): Awaitable<AgentRuntimeBinding[]>;
   bindRuntime(binding: {
     id: string;

package/src/projections.ts

@@ -16,6 +16,7 @@ import type {
   KudosRecord,
   MemoRecord,
   NoteRecord,
+  PostRecord,
   TaskDue,
   TaskRecord,
   TodoRecord,
@@ -254,6 +255,75 @@ export function memoRecordsFromEvents(events: SynomemEvent[]): MemoRecord[] {
   return [...records.values()].sort((a, b) => b.event.createdAt.localeCompare(a.event.createdAt));
 }
 
+/**
+ * Rebuilds posts from their events, acknowledgements included.
+ *
+ * Edits are kept as a list rather than collapsed into the current text. A reader
+ * has to be able to see that a post changed after somebody acknowledged it —
+ * silently rewriting what was acknowledged is how a record becomes a lie.
+ */
+export function postRecordsFromEvents(events: SynomemEvent[]): PostRecord[] {
+  const records = new Map<string, PostRecord>();
+  for (const event of events) {
+    if (event.type === 'post.created') {
+      records.set(event.id, {
+        event,
+        edits: [],
+        acknowledgments: [],
+        status: 'active',
+        title: event.title,
+        body: event.body,
+        ...(event.tags ? { tags: event.tags } : {}),
+        // The text version, counting only changes to the text.
+        //
+        // Deliberately not the aggregate version, which also counts every
+        // acknowledgement. If they were the same number, somebody
+        // acknowledging a post would invalidate an edit the author was in the
+        // middle of making — a conflict with nothing to reconcile.
+        version: 1,
+      });
+    } else if (event.type === 'post.edited') {
+      const record = records.get(event.postId);
+      if (record) {
+        record.edits.push(event);
+        record.title = event.title;
+        record.body = event.body;
+        if (event.tags) record.tags = event.tags;
+        record.version += 1;
+      }
+    } else if (event.type === 'post.archived') {
+      const record = records.get(event.postId);
+      if (record) {
+        record.archived = event;
+        record.status = 'archived';
+      }
+    } else if (event.type === 'post.acknowledged') {
+      const record = records.get(event.postId);
+      if (record) {
+        // One statement per actor: a repeat replaces rather than accumulates.
+        const existing = record.acknowledgments.findIndex(
+          (entry) => entry.actor.id === event.actor.id && entry.actor.kind === event.actor.kind,
+        );
+        const entry = {
+          actor: event.actor,
+          acknowledgedAt: event.createdAt,
+          ...(event.note ? { note: event.note } : {}),
+        };
+        if (existing >= 0) record.acknowledgments[existing] = entry;
+        else record.acknowledgments.push(entry);
+      }
+    } else if (event.type === 'post.acknowledgment.withdrawn') {
+      const record = records.get(event.postId);
+      if (record) {
+        record.acknowledgments = record.acknowledgments.filter(
+          (entry) => !(entry.actor.id === event.actor.id && entry.actor.kind === event.actor.kind),
+        );
+      }
+    }
+  }
+  return [...records.values()];
+}
+
 export function noteRecordsFromEvents(events: SynomemEvent[]): NoteRecord[] {
   const records = new Map<string, NoteRecord>();
   for (const event of events) {

package/src/remote.ts

@@ -6,6 +6,8 @@ import type {
   ChangesInput,
   BindRuntimeInput,
   CreateAgentInput,
+  CreatePostInput,
+  UpdatePostInput,
   CreateNoteInput,
   CreateTaskInput,
   GiveKudosInput,
@@ -200,6 +202,52 @@ export class RemoteSynomemService implements SynomemService {
       ),
   };
 
+  readonly posts = {
+    create: (input: CreatePostInput) =>
+      this.mutation<Awaited<ReturnType<SynomemService['posts']['create']>>>('POST', 'posts', input),
+    list: (input: Omit<ItemListInput, 'kinds'> = {}) =>
+      this.request<Awaited<ReturnType<SynomemService['posts']['list']>>>(
+        'GET',
+        `posts${queryString(input)}`,
+      ),
+    get: (id: string) =>
+      this.request<Awaited<ReturnType<SynomemService['posts']['get']>>>(
+        'GET',
+        `posts/${encodeURIComponent(id)}`,
+      ),
+    update: (input: UpdatePostInput) =>
+      this.mutation<Awaited<ReturnType<SynomemService['posts']['update']>>>(
+        'POST',
+        `posts/${encodeURIComponent(input.postId)}/revisions`,
+        input,
+        ['postId'],
+      ),
+    archive: (input: { postId: string; reason?: string; idempotencyKey?: string }) =>
+      this.mutation<Awaited<ReturnType<SynomemService['posts']['archive']>>>(
+        'POST',
+        `posts/${encodeURIComponent(input.postId)}/archive`,
+        input,
+        ['postId'],
+      ),
+    acknowledge: (input: { postId: string; note?: string; idempotencyKey?: string }) =>
+      this.mutation<Awaited<ReturnType<SynomemService['posts']['acknowledge']>>>(
+        'POST',
+        `posts/${encodeURIComponent(input.postId)}/acknowledgment`,
+        input,
+        ['postId'],
+      ),
+    withdrawAcknowledgment: (input: { postId: string; reason?: string }) =>
+      this.request<Awaited<ReturnType<SynomemService['posts']['withdrawAcknowledgment']>>>(
+        'DELETE',
+        `posts/${encodeURIComponent(input.postId)}/acknowledgment`,
+      ),
+    roster: (postId: string) =>
+      this.request<Awaited<ReturnType<SynomemService['posts']['roster']>>>(
+        'GET',
+        `posts/${encodeURIComponent(postId)}/roster`,
+      ),
+  };
+
   readonly kudos = {
     give: (input: GiveKudosInput) =>
       this.mutation<Awaited<ReturnType<SynomemService['kudos']['give']>>>('POST', 'kudos', input),

package/src/schemas.ts

@@ -257,6 +257,47 @@ const noteArchivedSchema = baseEventSchema.extend({
   noteId: z.string().length(26),
 });
 
+/**
+ * Post events. A post carries no recipient, assignee or visibility: it is
+ * addressed to the workspace, and workspace membership is the audience. Adding
+ * a visibility field would create a second, weaker way to hide a record.
+ */
+const postFields = {
+  title: z
+    .string()
+    .trim()
+    .min(1)
+    .max(200)
+    .regex(/^[^\r\n]+$/),
+  body: z.string().trim().min(1).max(32_000),
+  tags: z.array(kudosTagSchema).max(20).optional(),
+};
+const postCreatedSchema = baseEventSchema.extend({
+  type: z.literal('post.created'),
+  ...postFields,
+  replyTo: z.string().length(26).optional(),
+});
+const postEditedSchema = baseEventSchema.extend({
+  type: z.literal('post.edited'),
+  postId: z.string().length(26),
+  ...postFields,
+});
+const postArchivedSchema = baseEventSchema.extend({
+  type: z.literal('post.archived'),
+  postId: z.string().length(26),
+  reason: z.string().trim().min(1).max(2000).optional(),
+});
+const postAcknowledgedSchema = baseEventSchema.extend({
+  type: z.literal('post.acknowledged'),
+  postId: z.string().length(26),
+  note: z.string().trim().min(1).max(2000).optional(),
+});
+const postAcknowledgmentWithdrawnSchema = baseEventSchema.extend({
+  type: z.literal('post.acknowledgment.withdrawn'),
+  postId: z.string().length(26),
+  reason: z.string().trim().min(1).max(2000).optional(),
+});
+
 const taskDueSchema = z.discriminatedUnion('kind', [
   z.object({
     kind: z.literal('date'),
@@ -380,6 +421,11 @@ const todoArchivedSchema = baseEventSchema.extend({
 });
 
 export const eventSchema = z.discriminatedUnion('type', [
+  postCreatedSchema,
+  postEditedSchema,
+  postArchivedSchema,
+  postAcknowledgedSchema,
+  postAcknowledgmentWithdrawnSchema,
   kudosGivenSchema,
   acknowledgedSchema,
   revokedSchema,
@@ -477,6 +523,24 @@ export const sendMemoSchema = z
     ...mutationMetadata,
   })
   .strict();
+export const createPostSchema = z
+  .object({
+    ...postFields,
+    replyTo: z.string().length(26).optional(),
+    ...mutationMetadata,
+  })
+  .strict();
+export const updatePostSchema = z
+  .object({
+    postId: z.string().length(26),
+    expectedVersion: z.number().int().min(1),
+    title: postFields.title.optional(),
+    body: postFields.body.optional(),
+    tags: postFields.tags,
+    idempotencyKey: z.string().trim().min(1).max(200).optional(),
+  })
+  .strict();
+
 export const createNoteSchema = z
   .object({
     ownerAgentId: agentIdSchema.optional(),
@@ -553,7 +617,7 @@ export const updateTodoSchema = z
 export const itemListInputSchema = z
   .object({
     kinds: z
-      .array(z.enum(['kudos', 'memo', 'note', 'task', 'todo']))
+      .array(z.enum(['kudos', 'memo', 'note', 'post', 'task', 'todo']))
       .max(5)
       .optional(),
     participantAgentId: agentIdSchema.optional(),

package/src/service.ts

@@ -2,6 +2,10 @@ import type {
   ActorIdentity,
   AgentDirectoryEntry,
   AgentProfile,
+  CreatePostInput,
+  PostRecord,
+  PostRoster,
+  UpdatePostInput,
   AgentResolution,
   AgentRuntimeBinding,
   BindRuntimeInput,
@@ -80,6 +84,28 @@ export interface SynomemDomainService {
     bindRuntime(input: BindRuntimeInput): Promise<AgentRuntimeBinding>;
     unbindRuntime(bindingId: string): Promise<boolean>;
   };
+  readonly posts: {
+    create(input: CreatePostInput): Promise<{
+      record: PostRecord;
+      created: boolean;
+      deduplicated: boolean;
+    }>;
+    list(input?: Omit<ItemListInput, 'kinds'>): Promise<Page<ItemSummary>>;
+    get(id: string): Promise<PostRecord>;
+    update(input: UpdatePostInput): Promise<PostRecord>;
+    archive(input: {
+      postId: string;
+      reason?: string;
+      idempotencyKey?: string;
+    }): Promise<PostRecord>;
+    acknowledge(input: {
+      postId: string;
+      note?: string;
+      idempotencyKey?: string;
+    }): Promise<PostRecord>;
+    withdrawAcknowledgment(input: { postId: string; reason?: string }): Promise<PostRecord>;
+    roster(postId: string): Promise<PostRoster>;
+  };
   readonly kudos: {
     give(input: GiveKudosInput): Promise<GiveKudosResult>;
     list(input?: KudosListInput): Promise<Page<KudosSummary>>;