synomem 0.2.0 → 0.4.0

package/src/remote.ts

@@ -6,6 +6,8 @@ import type {
   ChangesInput,
   BindRuntimeInput,
   CreateAgentInput,
+  CreatePostInput,
+  UpdatePostInput,
   CreateNoteInput,
   CreateTaskInput,
   GiveKudosInput,
@@ -177,6 +179,30 @@ export class RemoteSynomemService implements SynomemService {
         'GET',
         `agents/resolve?query=${encodeURIComponent(query)}`,
       ),
+    archive: (idOrAlias: string) =>
+      this.mutation<Awaited<ReturnType<SynomemService['agents']['archive']>>>(
+        'POST',
+        `agents/${encodeURIComponent(idOrAlias)}/archive`,
+        {},
+      ),
+    restore: (idOrAlias: string) =>
+      this.mutation<Awaited<ReturnType<SynomemService['agents']['restore']>>>(
+        'POST',
+        `agents/${encodeURIComponent(idOrAlias)}/restore`,
+        {},
+      ),
+    addAliases: (idOrAlias: string, aliases: string[]) =>
+      this.mutation<Awaited<ReturnType<SynomemService['agents']['addAliases']>>>(
+        'POST',
+        `agents/${encodeURIComponent(idOrAlias)}/aliases`,
+        { aliases },
+      ),
+    removeAliases: (idOrAlias: string, aliases: string[]) =>
+      this.mutation<Awaited<ReturnType<SynomemService['agents']['removeAliases']>>>(
+        'POST',
+        `agents/${encodeURIComponent(idOrAlias)}/aliases/remove`,
+        { aliases },
+      ),
     directory: () =>
       this.request<Awaited<ReturnType<SynomemService['agents']['directory']>>>(
         'GET',
@@ -200,6 +226,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

@@ -17,12 +17,34 @@ const reservedIds = new Set([
   'lpt1',
 ]);
 
-export const agentIdSchema = z
+/**
+ * A handle: the human-friendly name for an agent, unique within its workspace.
+ *
+ * Mutable, unlike the canonical ID. People and agents type this, so it stays
+ * lowercase kebab and refuses the reserved words that would collide with
+ * filesystem or route segments.
+ */
+export const agentHandleSchema = z
   .string()
   .min(1)
   .max(63)
   .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'Use lowercase ASCII letters, digits, and hyphens')
-  .refine((id) => !reservedIds.has(id), 'Reserved agent ID');
+  .refine((handle) => !reservedIds.has(handle), 'Reserved agent handle');
+
+/** A canonical opaque agent ID: a ULID, uppercase Crockford base32. */
+export const agentUlidSchema = z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$/);
+
+/**
+ * An actor ID as it appears in an event.
+ *
+ * Accepts a ULID or a handle-shaped name. New agents are created with an opaque
+ * ULID so a handle can be renamed without orphaning the events that reference
+ * the actor; agents that predate that, and human and system actors, carry a
+ * name-shaped ID. Widening rather than replacing keeps append-only history
+ * readable — rewriting the actor ID inside stored events to tidy the format
+ * would be exactly the rewrite the event log exists to prevent.
+ */
+export const agentIdSchema = z.union([agentUlidSchema, agentHandleSchema]);
 
 /**
  * An alias as written, folded to the canonical lowercase form.
@@ -110,16 +132,42 @@ export const evidenceSchema = z
   });
 
 export const profileSchema = z.object({
+  /** Canonical, opaque and immutable. Events reference this, never the handle. */
   id: agentIdSchema,
+  handle: agentHandleSchema,
   displayName: z.string().trim().min(1).max(200),
   aliases: z.array(agentAliasSchema).max(50).optional(),
   description: z.string().trim().max(2000).optional(),
+  /** Archived agents keep their history and stop being able to act. */
+  status: z.enum(['active', 'archived']).default('active'),
   createdAt: z.string().datetime({ offset: true }),
   metadata: metadataSchema.optional(),
 });
 
-export const createAgentSchema = profileSchema.omit({ createdAt: true });
-export const updateAgentSchema = createAgentSchema.omit({ id: true }).partial();
+/**
+ * Creating an agent names a handle; the canonical ID is generated, never
+ * supplied. A caller that could choose the ID could choose one that collides
+ * with an archived agent's history.
+ */
+export const createAgentSchema = z
+  .object({
+    handle: agentHandleSchema,
+    displayName: z.string().trim().min(1).max(200),
+    aliases: z.array(agentAliasSchema).max(50).optional(),
+    description: z.string().trim().max(2000).optional(),
+    metadata: metadataSchema.optional(),
+  })
+  .strict();
+
+export const updateAgentSchema = z
+  .object({
+    handle: agentHandleSchema.optional(),
+    displayName: z.string().trim().min(1).max(200).optional(),
+    aliases: z.array(agentAliasSchema).max(50).optional(),
+    description: z.string().trim().max(2000).optional(),
+    metadata: metadataSchema.optional(),
+  })
+  .strict();
 
 /**
  * A runtime binding is a claim about where an agent runs, so the fields stay
@@ -196,7 +244,14 @@ const agentCreatedSchema = baseEventSchema.extend({
 const agentUpdatedSchema = baseEventSchema.extend({
   type: z.literal('agent.updated'),
   agentId: agentIdSchema,
-  changes: updateAgentSchema,
+  /*
+   * Archiving is recorded as an update, so `status` belongs in the event even
+   * though callers cannot set it through `agents.update` — it moves through
+   * `archive` and `restore`, which keep the transition explicit.
+   */
+  changes: updateAgentSchema.extend({
+    status: z.enum(['active', 'archived']).optional(),
+  }),
 });
 
 const memoSentSchema = baseEventSchema.extend({
@@ -257,6 +312,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 +476,11 @@ const todoArchivedSchema = baseEventSchema.extend({
 });
 
 export const eventSchema = z.discriminatedUnion('type', [
+  postCreatedSchema,
+  postEditedSchema,
+  postArchivedSchema,
+  postAcknowledgedSchema,
+  postAcknowledgmentWithdrawnSchema,
   kudosGivenSchema,
   acknowledgedSchema,
   revokedSchema,
@@ -477,6 +578,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 +672,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,
@@ -75,11 +79,37 @@ export interface SynomemDomainService {
     get(idOrAlias: string): Promise<AgentProfile>;
     list(): Promise<AgentProfile[]>;
     resolve(query: string): Promise<AgentResolution>;
+    archive(idOrAlias: string): Promise<AgentProfile>;
+    restore(idOrAlias: string): Promise<AgentProfile>;
+    addAliases(idOrAlias: string, aliases: string[]): Promise<AgentProfile>;
+    removeAliases(idOrAlias: string, aliases: string[]): Promise<AgentProfile>;
     directory(): Promise<AgentDirectoryEntry[]>;
     bindings(idOrAlias: string): Promise<AgentRuntimeBinding[]>;
     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>>;

package/src/storage.ts

@@ -31,6 +31,8 @@ import type {
   AgentProfile,
   AgentRuntimeBinding,
   ChangePage,
+  PostAcknowledgment,
+  PostRoster,
   JsonValue,
   KudosChange,
   SynomemEvent,
@@ -237,6 +239,37 @@ CREATE UNIQUE INDEX agent_runtime_bindings_unique
 CREATE INDEX agent_runtime_bindings_agent ON agent_runtime_bindings(agent_id);
 `;
 
+const migrationV6 = `
+-- Acknowledgements are their own rows rather than a column on the post: many
+-- actors acknowledge one post independently, and the interesting question is
+-- who, not how many.
+CREATE TABLE post_acknowledgments (
+  post_id TEXT NOT NULL,
+  actor_kind TEXT NOT NULL,
+  actor_id TEXT NOT NULL,
+  actor_display_name TEXT,
+  note TEXT,
+  acknowledged_at TEXT NOT NULL,
+  PRIMARY KEY (post_id, actor_kind, actor_id)
+) STRICT;
+CREATE INDEX post_acknowledgments_post ON post_acknowledgments(post_id);
+`;
+
+const migrationV7 = `
+-- Opaque canonical IDs, with the handle as a separate mutable name.
+--
+-- Existing agents keep their name-shaped ID and take it as their handle too.
+-- Rewriting the actor ID inside stored events to tidy the format would be
+-- exactly the rewrite an append-only log exists to prevent, so history stays
+-- as written and only NEW agents get a generated opaque ID.
+ALTER TABLE agents ADD COLUMN handle TEXT;
+UPDATE agents SET handle = id WHERE handle IS NULL;
+CREATE UNIQUE INDEX agents_handle ON agents(handle);
+
+-- Archived agents keep their records and stop being able to act.
+ALTER TABLE agents ADD COLUMN status TEXT NOT NULL DEFAULT 'active';
+`;
+
 const migrationV3 = `
 DROP TRIGGER IF EXISTS events_append_only_update;
 DROP TRIGGER IF EXISTS events_append_only_delete;
@@ -365,6 +398,7 @@ function eventKind(event: SynomemEvent): RecordKind | undefined {
   if (event.type.startsWith('kudos.')) return 'kudos';
   if (event.type.startsWith('memo.')) return 'memo';
   if (event.type.startsWith('note.')) return 'note';
+  if (event.type.startsWith('post.')) return 'post';
   if (event.type.startsWith('task.')) return 'task';
   if (event.type.startsWith('todo.')) return 'todo';
   return undefined;
@@ -411,7 +445,8 @@ export class SynomemStorage implements SynomemRepository {
 
   constructor(options: StorageOptions) {
     this.home = resolve(options.home);
-    this.storageDirectory = join(this.home, 'synomem');
+    // The home is the storage directory; see configLocation in backend.ts.
+    this.storageDirectory = this.home;
     this.databasePath = join(this.storageDirectory, 'synomem.sqlite3');
     this.configPath = join(this.storageDirectory, 'config.json');
     this.readOnly = options.readOnly;
@@ -499,7 +534,7 @@ export class SynomemStorage implements SynomemRepository {
     const version = Number(
       (db.prepare('PRAGMA user_version').get() as { user_version: number }).user_version,
     );
-    if (version > 5) {
+    if (version > 7) {
       throw new SynomemError(
         'UNSUPPORTED_SCHEMA',
         `Database schema version ${version} is newer than this package supports.`,
@@ -567,14 +602,38 @@ export class SynomemStorage implements SynomemRepository {
         db.exec('PRAGMA user_version = 5');
       });
     }
+    const afterV5 = Number(
+      (db.prepare('PRAGMA user_version').get() as { user_version: number }).user_version,
+    );
+    if (afterV5 === 5) {
+      this.transactionSync(() => {
+        db.exec(migrationV6);
+        db.prepare(
+          'INSERT OR IGNORE INTO schema_migrations(version, applied_at) VALUES (?, ?)',
+        ).run(6, new Date().toISOString());
+        db.exec('PRAGMA user_version = 6');
+      });
+    }
+    const afterV6 = Number(
+      (db.prepare('PRAGMA user_version').get() as { user_version: number }).user_version,
+    );
+    if (afterV6 === 6) {
+      this.transactionSync(() => {
+        db.exec(migrationV7);
+        db.prepare(
+          'INSERT OR IGNORE INTO schema_migrations(version, applied_at) VALUES (?, ?)',
+        ).run(7, new Date().toISOString());
+        db.exec('PRAGMA user_version = 7');
+      });
+    }
   }
 
   private assertSchemaSupported(): void {
     const version = Number(
       (this.db().prepare('PRAGMA user_version').get() as { user_version: number }).user_version,
     );
-    if (version !== 5) {
-      if (version >= 1 && version <= 4) {
+    if (version !== 7) {
+      if (version >= 1 && version <= 6) {
         throw new SynomemError(
           'UNSUPPORTED_SCHEMA',
           `Database schema version ${version} requires migration. Open this home once with readOnly: false, then retry the read-only client.`,
@@ -835,6 +894,61 @@ export class SynomemStorage implements SynomemRepository {
         ownerAgentId: event.ownerAgentId,
         ownerDisplayName: event.ownerDisplayName,
       });
+    } else if (event.type === 'post.created') {
+      /*
+       * A post is addressed to the workspace, so it is recorded as `workspace`
+       * visibility rather than carrying a visibility of its own. There is no
+       * owner-scoped or recipient-scoped read filter to apply: everyone who can
+       * read the workspace can read it, which is the whole point of the domain.
+       */
+      insert({
+        kind: 'post',
+        title: event.title,
+        tags: event.tags,
+        visibility: 'workspace',
+        status: 'active',
+      });
+    } else if (event.type === 'post.edited') {
+      this.db()
+        .prepare(
+          `UPDATE items_current SET title = ?, tags_json = ?,
+         updated_sequence = ?, updated_at = ? WHERE item_id = ?`,
+        )
+        .run(
+          event.title,
+          JSON.stringify(event.tags ?? []),
+          sequence,
+          event.createdAt,
+          event.postId,
+        );
+    } else if (event.type === 'post.archived') {
+      updateStatus('archived');
+    } else if (event.type === 'post.acknowledged') {
+      // One row per actor per post: acknowledging twice is the same statement,
+      // not a second one.
+      this.db()
+        .prepare(
+          `INSERT INTO post_acknowledgments
+             (post_id, actor_kind, actor_id, actor_display_name, note, acknowledged_at)
+           VALUES (?, ?, ?, ?, ?, ?)
+           ON CONFLICT(post_id, actor_kind, actor_id) DO UPDATE SET
+             note = excluded.note,
+             acknowledged_at = excluded.acknowledged_at`,
+        )
+        .run(
+          event.postId,
+          event.actor.kind,
+          event.actor.id,
+          event.actor.displayName ?? null,
+          event.note ?? null,
+          event.createdAt,
+        );
+    } else if (event.type === 'post.acknowledgment.withdrawn') {
+      this.db()
+        .prepare(
+          'DELETE FROM post_acknowledgments WHERE post_id = ? AND actor_kind = ? AND actor_id = ?',
+        )
+        .run(event.postId, event.actor.kind, event.actor.id);
     } else if (event.type === 'note.revised') {
       this.db()
         .prepare(
@@ -1418,7 +1532,7 @@ export class SynomemStorage implements SynomemRepository {
         this.db()
           .prepare(
             `SELECT COUNT(*) AS count FROM events WHERE type IN
-       ('kudos.given', 'memo.sent', 'note.created', 'task.created')`,
+       ('kudos.given', 'memo.sent', 'note.created', 'post.created', 'task.created')`,
           )
           .get() as { count: number }
       ).count,
@@ -1444,12 +1558,23 @@ export class SynomemStorage implements SynomemRepository {
     return { schemaVersion, appliedVersions };
   }
 
+  /**
+   * Aliases that also name an agent directly.
+   *
+   * Matches against the HANDLE as well as the canonical ID. With opaque IDs an
+   * alias can no longer accidentally equal one, but it can easily equal another
+   * agent's handle — which is the collision that actually makes a lookup
+   * ambiguous now.
+   */
   aliasIdentityConflicts(): Array<{ alias: string; agentId: string }> {
     return this.db()
       .prepare(
         `SELECT x.alias, x.agent_id AS agentId
-         FROM aliases x JOIN agents a ON a.id = x.alias
-         ORDER BY x.alias`,
+         FROM aliases x
+         JOIN agents a ON lower(a.id) = x.normalized_alias
+                       OR lower(a.handle) = x.normalized_alias
+        WHERE a.id != x.agent_id
+        ORDER BY x.alias`,
       )
       .all() as unknown as Array<{ alias: string; agentId: string }>;
   }
@@ -1571,6 +1696,11 @@ export class SynomemStorage implements SynomemRepository {
           'note.created',
           'note.revised',
           'note.archived',
+          'post.created',
+          'post.edited',
+          'post.archived',
+          'post.acknowledged',
+          'post.acknowledgment.withdrawn',
           'task.created',
           'task.updated',
           'task.completed',
@@ -1636,10 +1766,13 @@ export class SynomemStorage implements SynomemRepository {
     const parsed = profileSchema.parse(profile);
     this.db()
       .prepare(
-        'INSERT INTO agents(id, display_name, profile_json, created_at, updated_at) VALUES (?, ?, ?, ?, ?)',
+        `INSERT INTO agents(id, handle, status, display_name, profile_json, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
       )
       .run(
         parsed.id,
+        parsed.handle,
+        parsed.status,
         parsed.displayName,
         JSON.stringify(parsed),
         parsed.createdAt,
@@ -1651,8 +1784,18 @@ export class SynomemStorage implements SynomemRepository {
   updateAgent(profile: AgentProfile, updatedAt: string): void {
     const parsed = profileSchema.parse(profile);
     this.db()
-      .prepare('UPDATE agents SET display_name = ?, profile_json = ?, updated_at = ? WHERE id = ?')
-      .run(parsed.displayName, JSON.stringify(parsed), updatedAt, parsed.id);
+      .prepare(
+        `UPDATE agents SET handle = ?, status = ?, display_name = ?, profile_json = ?,
+           updated_at = ? WHERE id = ?`,
+      )
+      .run(
+        parsed.handle,
+        parsed.status,
+        parsed.displayName,
+        JSON.stringify(parsed),
+        updatedAt,
+        parsed.id,
+      );
     this.db().prepare('DELETE FROM aliases WHERE agent_id = ?').run(parsed.id);
     this.insertAliases(parsed.id, parsed.aliases ?? []);
   }
@@ -1679,14 +1822,69 @@ export class SynomemStorage implements SynomemRepository {
         `SELECT DISTINCT a.profile_json
            FROM agents a
            LEFT JOIN aliases x ON x.agent_id = a.id
-          WHERE lower(a.id) = ? OR x.normalized_alias = ?
+          WHERE lower(a.id) = ? OR lower(a.handle) = ? OR x.normalized_alias = ?
           ORDER BY a.id ASC`,
       )
-      .all(normalized, normalized) as unknown as ProfileRow[];
+      .all(normalized, normalized, normalized) as unknown as ProfileRow[];
     const candidates = rows.map((row) => profileSchema.parse(JSON.parse(row.profile_json)));
     return candidates.length === 1 ? { match: candidates[0]!, candidates } : { candidates };
   }
 
+  /* -------------------------------------------------------- post acknowledgment */
+
+  listPostAcknowledgments(postId: string): PostAcknowledgment[] {
+    const rows = this.db()
+      .prepare(
+        `SELECT actor_kind, actor_id, actor_display_name, note, acknowledged_at
+           FROM post_acknowledgments WHERE post_id = ? ORDER BY acknowledged_at ASC`,
+      )
+      .all(postId) as unknown as Array<{
+      actor_kind: string;
+      actor_id: string;
+      actor_display_name: string | null;
+      note: string | null;
+      acknowledged_at: string;
+    }>;
+    return rows.map((row) => ({
+      actor: {
+        kind: row.actor_kind as ActorIdentity['kind'],
+        id: row.actor_id,
+        ...(row.actor_display_name ? { displayName: row.actor_display_name } : {}),
+      },
+      acknowledgedAt: row.acknowledged_at,
+      ...(row.note ? { note: row.note } : {}),
+    }));
+  }
+
+  /**
+   * Who has acknowledged a post and who has not.
+   *
+   * The denominator is agents that existed when the post was written. An agent
+   * created afterwards is counted separately rather than listed as
+   * outstanding — it was not there, and a roster that says otherwise accuses a
+   * newcomer of ignoring something written before it arrived.
+   */
+  postRoster(postId: string): PostRoster | undefined {
+    const post = this.db()
+      .prepare("SELECT created_at FROM items_current WHERE item_id = ? AND kind = 'post'")
+      .get(postId) as { created_at: string } | undefined;
+    if (!post) return undefined;
+
+    const acknowledged = this.listPostAcknowledgments(postId);
+    const acknowledgedIds = new Set(acknowledged.map((entry) => entry.actor.id));
+
+    const eligible = this.db()
+      .prepare('SELECT id, display_name, created_at FROM agents ORDER BY id ASC')
+      .all() as unknown as Array<{ id: string; display_name: string; created_at: string }>;
+
+    const outstanding = eligible
+      .filter((agent) => agent.created_at <= post.created_at && !acknowledgedIds.has(agent.id))
+      .map((agent) => ({ id: agent.id, displayName: agent.display_name }));
+    const joinedSince = eligible.filter((agent) => agent.created_at > post.created_at).length;
+
+    return { postId, acknowledged, outstanding, joinedSince };
+  }
+
   /* ------------------------------------------------------- runtime bindings */
 
   listRuntimeBindings(agentId: string): AgentRuntimeBinding[] {
@@ -1818,11 +2016,16 @@ export class SynomemStorage implements SynomemRepository {
     });
   }
 
-  replaceAgentProjectionManifest(agentId: string, paths: string[], generatedAt: string): void {
+  /**
+   * @param directory the agent's projection directory name, which is its
+   * handle rather than its canonical ID: these rows are keyed by the path on
+   * disk, and projections are named for people to read.
+   */
+  replaceAgentProjectionManifest(directory: string, paths: string[], generatedAt: string): void {
     this.transactionSync(() => {
       this.db()
         .prepare('DELETE FROM projection_manifest WHERE path LIKE ? OR path LIKE ?')
-        .run(`${agentId}/%`, `${agentId}\\%`);
+        .run(`${directory}/%`, `${directory}\\%`);
       const insert = this.db().prepare(
         'INSERT INTO projection_manifest(path, generated_at) VALUES (?, ?)',
       );