synomem 0.1.0

package/src/schemas.ts

@@ -0,0 +1,457 @@
+import { isAbsolute, normalize } from 'node:path';
+import { z } from 'zod';
+import type { JsonValue } from './types.js';
+
+const reservedIds = new Set([
+  '.',
+  '..',
+  'kudos',
+  'synomem',
+  'exports',
+  'inbox',
+  'con',
+  'prn',
+  'aux',
+  'nul',
+  'com1',
+  'lpt1',
+]);
+
+export const agentIdSchema = 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');
+
+export const actorSchema = z.object({
+  kind: z.enum(['human', 'agent', 'system']),
+  id: agentIdSchema,
+  displayName: z.string().trim().min(1).max(200).optional(),
+});
+
+export const jsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema),
+  ]),
+);
+
+export const metadataSchema = z.record(z.string().max(200), jsonValueSchema);
+
+export const sourceSchema = z.object({
+  runtime: z.string().trim().min(1).max(200).optional(),
+  model: z.string().trim().min(1).max(200).optional(),
+  sessionId: z.string().trim().min(1).max(500).optional(),
+  repository: z.string().trim().min(1).max(1000).optional(),
+  commit: z.string().trim().min(1).max(200).optional(),
+  workingDirectory: z.string().trim().min(1).max(2000).optional(),
+});
+
+function isSafeFileEvidence(value: string): boolean {
+  const normalized = normalize(value);
+  return (
+    !isAbsolute(value) &&
+    normalized !== '..' &&
+    !normalized.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)
+  );
+}
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' || url.protocol === 'http:';
+  } catch {
+    return false;
+  }
+}
+
+export const evidenceSchema = z
+  .object({
+    kind: z.enum(['tool-call', 'commit', 'file', 'url', 'task', 'note']),
+    label: z.string().trim().min(1).max(200).optional(),
+    value: z.string().trim().min(1).max(2000),
+  })
+  .superRefine((evidence, context) => {
+    if (evidence.kind === 'url' && !isHttpUrl(evidence.value)) {
+      context.addIssue({ code: 'custom', message: 'URL evidence must use http or https' });
+    }
+    if (evidence.kind === 'file' && !isSafeFileEvidence(evidence.value)) {
+      context.addIssue({ code: 'custom', message: 'File evidence must be a safe relative path' });
+    }
+  });
+
+export const profileSchema = z.object({
+  id: agentIdSchema,
+  displayName: z.string().trim().min(1).max(200),
+  aliases: z.array(agentIdSchema).max(50).optional(),
+  description: z.string().trim().max(2000).optional(),
+  createdAt: z.string().datetime({ offset: true }),
+  metadata: metadataSchema.optional(),
+});
+
+export const createAgentSchema = profileSchema.omit({ createdAt: true });
+export const updateAgentSchema = createAgentSchema.omit({ id: true }).partial();
+
+const baseEventSchema = z.object({
+  schemaVersion: z.literal(1),
+  id: z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$/),
+  workspaceId: z.string().trim().min(1).max(100),
+  aggregateId: z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$|^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+  aggregateVersion: z.number().int().min(1),
+  createdAt: z.string().datetime({ offset: true }),
+  actor: actorSchema,
+  idempotencyKey: z.string().trim().min(1).max(200).optional(),
+  source: sourceSchema.optional(),
+  metadata: metadataSchema.optional(),
+});
+
+export const kudosTitleSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(200)
+  .regex(/^[^\r\n]+$/, 'Kudos titles must be a single line');
+
+export const kudosTagSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(64)
+  .regex(/^[\p{L}\p{N}][\p{L}\p{N}._-]*$/u);
+
+const kudosGivenSchema = baseEventSchema.extend({
+  type: z.literal('kudos.given'),
+  recipientAgentId: agentIdSchema,
+  recipientDisplayName: z.string().trim().min(1).max(200),
+  title: z.string().trim().min(1).max(200),
+  reason: z.string().trim().min(1).max(5000),
+  evidence: z.array(evidenceSchema).max(50).optional(),
+  tags: z.array(kudosTagSchema).max(50).optional(),
+  visibility: z.enum(['private', 'workspace', 'public']),
+});
+
+const acknowledgedSchema = baseEventSchema.extend({
+  type: z.literal('kudos.acknowledged'),
+  kudosId: z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$/),
+  recipientAgentId: agentIdSchema,
+  note: z.string().trim().min(1).max(2000).optional(),
+});
+
+const revokedSchema = baseEventSchema.extend({
+  type: z.literal('kudos.revoked'),
+  kudosId: z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$/),
+  reason: z.string().trim().min(1).max(2000),
+  mode: z.enum(['actor-requested', 'administrative']),
+});
+
+const agentCreatedSchema = baseEventSchema.extend({
+  type: z.literal('agent.created'),
+  agent: profileSchema,
+});
+
+const agentUpdatedSchema = baseEventSchema.extend({
+  type: z.literal('agent.updated'),
+  agentId: agentIdSchema,
+  changes: updateAgentSchema,
+});
+
+const memoSentSchema = baseEventSchema.extend({
+  type: z.literal('memo.sent'),
+  recipientAgentId: agentIdSchema,
+  recipientDisplayName: z.string().trim().min(1).max(200),
+  subject: z
+    .string()
+    .trim()
+    .min(1)
+    .max(200)
+    .regex(/^[^\r\n]+$/),
+  body: z.string().trim().min(1).max(16_000),
+  tags: z.array(kudosTagSchema).max(20).optional(),
+  visibility: z.enum(['private', 'workspace', 'public']),
+});
+
+const memoReadSchema = baseEventSchema.extend({
+  type: z.literal('memo.read'),
+  memoId: z.string().length(26),
+  recipientAgentId: agentIdSchema,
+});
+const memoArchivedSchema = baseEventSchema.extend({
+  type: z.literal('memo.archived'),
+  memoId: z.string().length(26),
+  recipientAgentId: agentIdSchema,
+});
+
+const noteCreatedSchema = baseEventSchema.extend({
+  type: z.literal('note.created'),
+  ownerAgentId: agentIdSchema,
+  ownerDisplayName: z.string().trim().min(1).max(200),
+  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(),
+  visibility: z.literal('private'),
+});
+const noteRevisedSchema = baseEventSchema.extend({
+  type: z.literal('note.revised'),
+  noteId: z.string().length(26),
+  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(),
+  visibility: z.literal('private'),
+});
+const noteArchivedSchema = baseEventSchema.extend({
+  type: z.literal('note.archived'),
+  noteId: z.string().length(26),
+});
+
+const todoDueSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('date'),
+    date: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/)
+      .refine((value) => {
+        const date = new Date(`${value}T00:00:00Z`);
+        return !Number.isNaN(date.valueOf()) && date.toISOString().slice(0, 10) === value;
+      }, 'Use a valid calendar date'),
+  }),
+  z.object({
+    kind: z.literal('datetime'),
+    datetime: z.string().datetime({ offset: true }),
+    timeZone: z
+      .string()
+      .trim()
+      .min(1)
+      .max(100)
+      .refine((value) => {
+        try {
+          new Intl.DateTimeFormat('en-US', { timeZone: value });
+          return true;
+        } catch {
+          return false;
+        }
+      }, 'Use a valid IANA time-zone identifier'),
+  }),
+]);
+const todoFields = {
+  title: z
+    .string()
+    .trim()
+    .min(1)
+    .max(200)
+    .regex(/^[^\r\n]+$/),
+  description: z.string().trim().max(16_000).optional(),
+  priority: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]),
+  due: todoDueSchema.optional(),
+  tags: z.array(kudosTagSchema).max(20).optional(),
+  visibility: z.enum(['private', 'workspace', 'public']),
+};
+const todoCreatedSchema = baseEventSchema.extend({
+  type: z.literal('todo.created'),
+  assigneeAgentId: agentIdSchema,
+  assigneeDisplayName: z.string().trim().min(1).max(200),
+  requiresAcceptance: z.boolean(),
+  ...todoFields,
+});
+const todoUpdatedSchema = baseEventSchema.extend({
+  type: z.literal('todo.updated'),
+  todoId: z.string().length(26),
+  ...todoFields,
+});
+const todoCompletedSchema = baseEventSchema.extend({
+  type: z.literal('todo.completed'),
+  todoId: z.string().length(26),
+  note: z.string().trim().min(1).max(2000).optional(),
+});
+const todoReopenedSchema = baseEventSchema.extend({
+  type: z.literal('todo.reopened'),
+  todoId: z.string().length(26),
+});
+const todoAcceptedSchema = baseEventSchema.extend({
+  type: z.literal('todo.accepted'),
+  todoId: z.string().length(26),
+});
+const todoRejectedSchema = baseEventSchema.extend({
+  type: z.literal('todo.rejected'),
+  todoId: z.string().length(26),
+  reason: z.string().trim().min(1).max(2000).optional(),
+});
+const todoCanceledSchema = baseEventSchema.extend({
+  type: z.literal('todo.canceled'),
+  todoId: z.string().length(26),
+  reason: z.string().trim().min(1).max(2000).optional(),
+});
+
+export const eventSchema = z.discriminatedUnion('type', [
+  kudosGivenSchema,
+  acknowledgedSchema,
+  revokedSchema,
+  agentCreatedSchema,
+  agentUpdatedSchema,
+  memoSentSchema,
+  memoReadSchema,
+  memoArchivedSchema,
+  noteCreatedSchema,
+  noteRevisedSchema,
+  noteArchivedSchema,
+  todoCreatedSchema,
+  todoUpdatedSchema,
+  todoCompletedSchema,
+  todoReopenedSchema,
+  todoAcceptedSchema,
+  todoRejectedSchema,
+  todoCanceledSchema,
+]);
+
+const giveKudosInputSchema = kudosGivenSchema
+  .omit({
+    schemaVersion: true,
+    id: true,
+    type: true,
+    workspaceId: true,
+    aggregateId: true,
+    aggregateVersion: true,
+    createdAt: true,
+    actor: true,
+    recipientDisplayName: true,
+  })
+  .extend({
+    title: kudosTitleSchema,
+    evidence: z.array(evidenceSchema).max(10).optional(),
+    tags: z.array(kudosTagSchema).max(20).optional(),
+  });
+
+function enforceKudosPayloadSize(value: unknown, context: z.RefinementCtx): void {
+  if (Buffer.byteLength(JSON.stringify(value), 'utf8') > 32_768) {
+    context.addIssue({ code: 'custom', message: 'Kudos payload must not exceed 32 KiB' });
+  }
+}
+
+export const giveKudosSchema = giveKudosInputSchema.superRefine(enforceKudosPayloadSize);
+
+export const giveKudosMcpSchema = giveKudosInputSchema
+  .extend({ visibility: z.enum(['private', 'workspace', 'public']).optional() })
+  .superRefine(enforceKudosPayloadSize);
+
+export const listInputSchema = z
+  .object({
+    recipientAgentId: agentIdSchema.optional(),
+    actorId: agentIdSchema.optional(),
+    actorKind: z.enum(['human', 'agent', 'system']).optional(),
+    tag: z.string().trim().min(1).max(64).optional(),
+    status: z.enum(['acknowledged', 'unacknowledged']).optional(),
+    visibility: z.enum(['private', 'workspace', 'public']).optional(),
+    revoked: z.boolean().optional(),
+    from: z.string().datetime({ offset: true }).optional(),
+    to: z.string().datetime({ offset: true }).optional(),
+    cursor: z.string().min(1).max(500).optional(),
+    limit: z.number().int().min(1).max(50).default(10),
+    offset: z.number().int().min(0).default(0),
+  })
+  .superRefine((value, context) => {
+    if (value.cursor && value.offset > 0) {
+      context.addIssue({ code: 'custom', message: 'Use either cursor or offset pagination' });
+    }
+  });
+
+export const changesInputSchema = z.object({
+  after: z.string().min(1).max(500).optional(),
+  limit: z.number().int().min(1).max(100).default(20),
+});
+
+const mutationMetadata = {
+  idempotencyKey: z.string().trim().min(1).max(200).optional(),
+  source: sourceSchema.optional(),
+  metadata: metadataSchema.optional(),
+};
+export const sendMemoSchema = z
+  .object({
+    recipientAgentId: agentIdSchema,
+    subject: memoSentSchema.shape.subject,
+    body: memoSentSchema.shape.body,
+    tags: z.array(kudosTagSchema).max(20).optional(),
+    visibility: z.enum(['private', 'workspace', 'public']).optional(),
+    ...mutationMetadata,
+  })
+  .strict();
+export const createNoteSchema = z
+  .object({
+    ownerAgentId: agentIdSchema.optional(),
+    title: noteCreatedSchema.shape.title,
+    body: noteCreatedSchema.shape.body,
+    tags: z.array(kudosTagSchema).max(20).optional(),
+    ...mutationMetadata,
+  })
+  .strict();
+export const reviseNoteSchema = z
+  .object({
+    noteId: z.string().length(26),
+    expectedVersion: z.number().int().min(1),
+    title: noteCreatedSchema.shape.title.optional(),
+    body: noteCreatedSchema.shape.body.optional(),
+    tags: z.array(kudosTagSchema).max(20).optional(),
+    ...mutationMetadata,
+  })
+  .strict();
+export const createTodoSchema = z
+  .object({
+    assigneeAgentId: agentIdSchema.optional(),
+    title: todoCreatedSchema.shape.title,
+    description: todoCreatedSchema.shape.description,
+    priority: todoCreatedSchema.shape.priority.optional(),
+    due: todoDueSchema.optional(),
+    tags: z.array(kudosTagSchema).max(20).optional(),
+    visibility: z.enum(['private', 'workspace', 'public']).optional(),
+    ...mutationMetadata,
+  })
+  .strict();
+export const updateTodoSchema = z
+  .object({
+    todoId: z.string().length(26),
+    expectedVersion: z.number().int().min(1),
+    title: todoCreatedSchema.shape.title.optional(),
+    description: todoCreatedSchema.shape.description,
+    priority: todoCreatedSchema.shape.priority.optional(),
+    due: todoDueSchema.nullable().optional(),
+    tags: z.array(kudosTagSchema).max(20).optional(),
+    visibility: z.enum(['private', 'workspace', 'public']).optional(),
+    ...mutationMetadata,
+  })
+  .strict();
+export const itemListInputSchema = z
+  .object({
+    kinds: z
+      .array(z.enum(['kudos', 'memo', 'note', 'todo']))
+      .max(4)
+      .optional(),
+    participantAgentId: agentIdSchema.optional(),
+    actorId: agentIdSchema.optional(),
+    actorKind: z.enum(['human', 'agent', 'system']).optional(),
+    tag: kudosTagSchema.optional(),
+    status: z.string().trim().min(1).max(50).optional(),
+    pending: z.boolean().optional(),
+    visibility: z.enum(['private', 'workspace', 'public']).optional(),
+    from: z.string().datetime({ offset: true }).optional(),
+    to: z.string().datetime({ offset: true }).optional(),
+    cursor: z.string().min(1).max(500).optional(),
+    limit: z.number().int().min(1).max(50).default(10),
+    offset: z.number().int().min(0).default(0),
+  })
+  .superRefine((value, context) => {
+    if (value.cursor && value.offset > 0)
+      context.addIssue({ code: 'custom', message: 'Use either cursor or offset pagination' });
+  });

package/src/service.ts

@@ -0,0 +1,140 @@
+import type {
+  ActorIdentity,
+  AgentProfile,
+  ChangePage,
+  ChangesInput,
+  CreateAgentInput,
+  CreateNoteInput,
+  CreateNoteResult,
+  CreateTodoInput,
+  CreateTodoResult,
+  DoctorResult,
+  GiveKudosInput,
+  GiveKudosResult,
+  ItemListInput,
+  ItemRecord,
+  ItemSummary,
+  KudosChangesInput,
+  KudosListInput,
+  KudosRecord,
+  KudosStats,
+  KudosSummary,
+  MemoRecord,
+  SynomemClientOptions,
+  SynomemEvent,
+  NoteRecord,
+  Page,
+  ReviseNoteInput,
+  SendMemoInput,
+  SendMemoResult,
+  TodoRecord,
+  UpdateAgentInput,
+  UpdateTodoInput,
+} from './types.js';
+
+export interface SynomemServiceCapabilities {
+  backend: 'local' | 'remote';
+  binding: {
+    workspaceId: string;
+    actor: ActorIdentity;
+  };
+  administration: {
+    agentCreationViaMcp: boolean;
+    rebuildViaMcp: boolean;
+  };
+  projections: {
+    writeWinsMarkdown: boolean;
+    writeMemoryMarkdown: boolean;
+    writeTodosMarkdown: boolean;
+    writeInboxEntries: boolean;
+  };
+}
+
+export type SynomemServiceInfo =
+  | { backend: 'local'; home: string; databasePath: string }
+  | { backend: 'remote'; baseUrl: string; workspaceId: string };
+
+export interface ProjectionRebuildResult {
+  generated: string[];
+  removed: string[];
+}
+
+export interface SynomemDomainService {
+  readonly actor: ActorIdentity;
+  readonly agents: {
+    create(input: CreateAgentInput): Promise<AgentProfile>;
+    update(id: string, changes: UpdateAgentInput): Promise<AgentProfile>;
+    get(idOrAlias: string): Promise<AgentProfile>;
+    list(): Promise<AgentProfile[]>;
+  };
+  readonly kudos: {
+    give(input: GiveKudosInput): Promise<GiveKudosResult>;
+    list(input?: KudosListInput): Promise<Page<KudosSummary>>;
+    changes(input?: KudosChangesInput): Promise<ChangePage>;
+    get(id: string): Promise<KudosRecord>;
+    acknowledge(input: { kudosId: string; note?: string }): Promise<KudosRecord>;
+    revoke(input: {
+      kudosId: string;
+      reason: string;
+      administrative?: boolean;
+    }): Promise<KudosRecord>;
+  };
+  readonly memos: {
+    send(input: SendMemoInput): Promise<SendMemoResult>;
+    list(input?: Omit<ItemListInput, 'kinds'>): Promise<Page<ItemSummary>>;
+    get(id: string): Promise<MemoRecord>;
+    read(input: { memoId: string; idempotencyKey?: string }): Promise<MemoRecord>;
+    archive(input: { memoId: string; idempotencyKey?: string }): Promise<MemoRecord>;
+  };
+  readonly notes: {
+    create(input: CreateNoteInput): Promise<CreateNoteResult>;
+    list(input?: Omit<ItemListInput, 'kinds'>): Promise<Page<ItemSummary>>;
+    get(id: string): Promise<NoteRecord>;
+    revise(input: ReviseNoteInput): Promise<NoteRecord>;
+    archive(input: { noteId: string; idempotencyKey?: string }): Promise<NoteRecord>;
+  };
+  readonly todos: {
+    create(input: CreateTodoInput): Promise<CreateTodoResult>;
+    list(input?: Omit<ItemListInput, 'kinds'>): Promise<Page<ItemSummary>>;
+    get(id: string): Promise<TodoRecord>;
+    update(input: UpdateTodoInput): Promise<TodoRecord>;
+    accept(input: { todoId: string; idempotencyKey?: string }): Promise<TodoRecord>;
+    reject(input: {
+      todoId: string;
+      reason?: string;
+      idempotencyKey?: string;
+    }): Promise<TodoRecord>;
+    complete(input: {
+      todoId: string;
+      note?: string;
+      idempotencyKey?: string;
+    }): Promise<TodoRecord>;
+    reopen(input: { todoId: string; idempotencyKey?: string }): Promise<TodoRecord>;
+    cancel(input: {
+      todoId: string;
+      reason?: string;
+      idempotencyKey?: string;
+    }): Promise<TodoRecord>;
+  };
+  readonly items: {
+    list(input?: ItemListInput): Promise<Page<ItemSummary>>;
+    get(id: string): Promise<ItemRecord>;
+    changes(input?: ChangesInput): Promise<ChangePage>;
+  };
+
+  init(): Promise<void>;
+  close(): Promise<void>;
+  stats(input?: KudosListInput): Promise<KudosStats>;
+}
+
+export interface SynomemService extends SynomemDomainService {
+  doctor(): Promise<DoctorResult>;
+  export(format: 'json' | 'jsonl' | 'markdown'): Promise<string>;
+  backup?(destination: string): Promise<string>;
+  rebuild(): Promise<ProjectionRebuildResult>;
+  capabilities(): Promise<SynomemServiceCapabilities>;
+  info(): Promise<SynomemServiceInfo>;
+  getCanonicalEvent(id: string): Promise<SynomemEvent | undefined>;
+}
+
+export type SynomemServiceFactory = (options: SynomemClientOptions) => SynomemService;