synomem 0.2.0 → 0.4.0

package/src/types.ts

@@ -3,7 +3,7 @@ export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue
 
 export type ActorKind = 'human' | 'agent' | 'system';
 export type Visibility = 'private' | 'workspace' | 'public';
-export type RecordKind = 'kudos' | 'memo' | 'note' | 'task' | 'todo';
+export type RecordKind = 'kudos' | 'memo' | 'note' | 'post' | 'task' | 'todo';
 
 export interface ActorIdentity {
   kind: ActorKind;
@@ -28,10 +28,22 @@ export interface EvidenceReference {
 }
 
 export interface AgentProfile {
+  /**
+   * Canonical, opaque, immutable. Every event references this, so it can never
+   * change — which is exactly why the handle exists separately.
+   */
   id: string;
+  /** The human-friendly name, unique in the workspace and safe to rename. */
+  handle: string;
   displayName: string;
   aliases?: string[];
   description?: string;
+  /**
+   * Archived agents keep their history and stop being able to act. Events
+   * reference the actor permanently, so deletion would leave history pointing
+   * at nothing.
+   */
+  status: 'active' | 'archived';
   createdAt: string;
   metadata?: Record<string, JsonValue>;
 }
@@ -140,6 +152,54 @@ export interface MemoArchivedEvent extends BaseEvent {
   recipientAgentId: string;
 }
 
+/**
+ * A Post is publication: an author says something to the whole workspace rather
+ * than to a named recipient.
+ *
+ * It has no recipient and no assignee, which is what separates it from a memo
+ * and a task. Everyone who can read the workspace can read it, and each of them
+ * can acknowledge it independently — a memo is read by one person, a post by
+ * many, so "who has responded" is the interesting question rather than "was it
+ * read".
+ */
+export interface PostCreatedEvent extends BaseEvent {
+  type: 'post.created';
+  title: string;
+  body: string;
+  tags?: string[];
+  /** The post this replies to. A reply inherits its parent's workspace. */
+  replyTo?: string;
+}
+export interface PostEditedEvent extends BaseEvent {
+  type: 'post.edited';
+  postId: string;
+  title: string;
+  body: string;
+  tags?: string[];
+}
+export interface PostArchivedEvent extends BaseEvent {
+  type: 'post.archived';
+  postId: string;
+  reason?: string;
+}
+/**
+ * One actor saying "I have seen this", and only ever about themselves.
+ *
+ * Appended by an explicit call. Reading a post never acknowledges it: a roster
+ * built from read receipts would answer "whose client fetched this", which for
+ * an agent means "whose runtime happened to poll".
+ */
+export interface PostAcknowledgedEvent extends BaseEvent {
+  type: 'post.acknowledged';
+  postId: string;
+  note?: string;
+}
+export interface PostAcknowledgmentWithdrawnEvent extends BaseEvent {
+  type: 'post.acknowledgment.withdrawn';
+  postId: string;
+  reason?: string;
+}
+
 export interface NoteCreatedEvent extends BaseEvent {
   type: 'note.created';
   ownerAgentId: string;
@@ -322,6 +382,11 @@ export type SynomemEvent =
   | MemoSentEvent
   | MemoReadEvent
   | MemoArchivedEvent
+  | PostCreatedEvent
+  | PostEditedEvent
+  | PostArchivedEvent
+  | PostAcknowledgedEvent
+  | PostAcknowledgmentWithdrawnEvent
   | NoteCreatedEvent
   | NoteRevisedEvent
   | NoteArchivedEvent
@@ -356,6 +421,40 @@ export interface MemoRecord {
   archived?: MemoArchivedEvent;
   status: 'unread' | 'read' | 'archived';
 }
+export interface PostAcknowledgment {
+  actor: ActorIdentity;
+  acknowledgedAt: string;
+  note?: string;
+}
+export interface PostRecord {
+  event: PostCreatedEvent;
+  edits: PostEditedEvent[];
+  archived?: PostArchivedEvent;
+  /** Everyone who has said they have seen it, in the order they said so. */
+  acknowledgments: PostAcknowledgment[];
+  status: 'active' | 'archived';
+  title: string;
+  body: string;
+  tags?: string[];
+  version: number;
+}
+
+/**
+ * Who has acknowledged a post, and who has not.
+ *
+ * `outstanding` is the honest denominator: actors who can read the post now AND
+ * could have read it when it was posted. Someone who joined afterwards is
+ * neither acknowledged nor outstanding — they were not there — and is reported
+ * as a count instead, so a roster never accuses a newcomer of ignoring
+ * something written before they arrived.
+ */
+export interface PostRoster {
+  postId: string;
+  acknowledged: PostAcknowledgment[];
+  outstanding: Array<{ id: string; displayName: string }>;
+  joinedSince: number;
+}
+
 export interface NoteRecord {
   event: NoteCreatedEvent;
   revision?: NoteRevisedEvent;
@@ -529,6 +628,23 @@ export interface SendMemoInput extends MutationInput {
   tags?: string[];
   visibility?: Visibility;
 }
+export interface CreatePostInput extends MutationInput {
+  title: string;
+  body: string;
+  tags?: string[];
+  /** The post being replied to; a reply inherits its parent's workspace. */
+  replyTo?: string;
+}
+
+export interface UpdatePostInput {
+  postId: string;
+  expectedVersion: number;
+  title?: string;
+  body?: string;
+  tags?: string[];
+  idempotencyKey?: string;
+}
+
 export interface CreateNoteInput extends MutationInput {
   ownerAgentId?: string;
   title: string;
@@ -580,13 +696,15 @@ export interface BindRuntimeInput {
 }
 
 export interface CreateAgentInput {
-  id: string;
+  /** The handle. The canonical ID is generated, never supplied. */
+  handle: string;
   displayName: string;
   aliases?: string[];
   description?: string;
   metadata?: Record<string, JsonValue>;
 }
 export interface UpdateAgentInput {
+  handle?: string;
   displayName?: string;
   aliases?: string[];
   description?: string;
@@ -602,7 +720,15 @@ export interface KudosStats {
   byTag: Record<string, number>;
 }
 export interface Diagnostic {
-  level: 'ok' | 'warning' | 'error';
+  /**
+   * `skipped` is not a failure.
+   *
+   * A check the caller lacks permission to run says so and leaves the overall
+   * result healthy. Failing the whole diagnostic because an ordinary agent
+   * cannot read workspace administration would make `doctor` useless to the
+   * callers who need it most.
+   */
+  level: 'ok' | 'warning' | 'error' | 'skipped';
   code: string;
   message: string;
   path?: string;