@inixiative/archive 0.6.0 → 0.8.0

package/src/schemas.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import type { ArchiveSnapshot } from './index';
+import { archiveIntegrationSchema, defaultIntegrations } from './tags';
+
+export const archiveSettingsSchema = z.strictObject({
+  /** Integrations sessions can reference; Kingdom and Foundry display these, Archive owns them. */
+  integrations: z
+    .array(archiveIntegrationSchema)
+    .max(50)
+    .refine(
+      (list) => new Set(list.map((i) => i.key)).size === list.length,
+      'Duplicate integration keys',
+    ),
+  /** Archives whose latest capture is older than this are deleted here. Deletions never sync. */
+  retentionDays: z.number().int().positive().max(36_500).nullable(),
+});
+export type ArchiveSettings = z.infer<typeof archiveSettingsSchema>;
+export const defaultSettings: ArchiveSettings = {
+  integrations: defaultIntegrations,
+  retentionDays: null,
+};
+
+export const tagSchema = z.string().min(1).max(120);
+/** A conceptual tag this archive offers: archive-wide (no actor) or for one actor. */
+export const tagDefinitionSchema = z.strictObject({
+  tag: tagSchema,
+  actorId: z.string().min(1).max(256).optional(),
+  description: z.string().max(500).optional(),
+});
+export type TagDefinition = z.infer<typeof tagDefinitionSchema>;
+
+export interface ArchiveFilter {
+  projectId?: string;
+  source?: ArchiveSnapshot['source'];
+  tag?: string;
+  actorId?: string;
+  reference?: { integration: string; ref: string };
+  model?: string;
+  effort?: string;
+}

package/src/server.ts

@@ -1,13 +1,7 @@
 import { timingSafeEqual } from 'node:crypto';
 import { z } from 'zod';
-import {
-  archiveKey,
-  archiveReferenceSchema,
-  archiveSnapshotSchema,
-  selectChunks,
-  snapshotDigest,
-} from './index';
-import { archiveSettingsSchema, LocalArchiveStore, tagDefinitionSchema } from './local';
+import { archiveReferenceSchema, archiveSnapshotSchema, selectChunks } from './index';
+import { ArchiveConflict, ArchiveStore, archiveSettingsSchema, tagDefinitionSchema } from './store';
 
 const ingestSchema = z.strictObject({
   snapshot: archiveSnapshotSchema,
@@ -43,19 +37,8 @@ const tagSchema = z.strictObject({
 const tagListSchema = z.strictObject({ actorId: z.string().min(1).max(256).optional() });
 const tagRemoveSchema = tagDefinitionSchema.pick({ tag: true, actorId: true });
 
-/** Cursor paging over newest-first archives. */
-function page<T extends { id: string }>(items: T[], limit: number, beforeId?: string) {
-  const cursor = beforeId ? items.findIndex((item) => item.id === beforeId) : -1;
-  if (beforeId && cursor < 0) return undefined;
-  const slice = items.slice(cursor + 1, cursor + 1 + limit);
-  return {
-    items: slice,
-    nextCursor: items.length > cursor + 1 + slice.length ? (slice.at(-1)?.id ?? null) : null,
-  };
-}
-
 /** One deployment, one ownership boundary. No shared cross-tenant database or admin API. */
-export function createArchiveHandler(store: LocalArchiveStore, token: string) {
+export function createArchiveHandler(store: ArchiveStore, token: string) {
   if (token.length < 32)
     throw new Error('ARCHIVE_SERVER_TOKEN must contain at least 32 characters');
   const expected = Buffer.from(`Bearer ${token}`);
@@ -86,48 +69,53 @@ export function createArchiveHandler(store: LocalArchiveStore, token: string) {
         chunks.push(item.value);
       }
       const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      if (path === '/api/v1/archive/info') {
+        z.strictObject({}).parse(body);
+        return json({ data: { sourceId: await store.sourceId(), protocol: 2 } });
+      }
       if (path === '/api/v1/archive/ingest') {
         const { snapshot, previousDigest } = ingestSchema.parse(body);
-        const id = archiveKey(snapshot),
-          old = store.read(id),
-          next = snapshotDigest(snapshot);
-        if (old?.digest !== next && (old?.digest ?? null) !== previousDigest)
-          return json({ error: 'Revision conflict' }, 409);
-        if (old && old.digest !== next && old.snapshot.capturedAt > snapshot.capturedAt)
-          return json({ error: 'Stale capture' }, 409);
-        return json({ data: store.capture(snapshot) });
+        return json({ data: await store.capture(snapshot, { previousDigest }) });
+      }
+      if (path === '/api/v1/archive/head') {
+        const head = await store.head(readSchema.pick({ archiveId: true }).parse(body).archiveId);
+        return head ? json({ data: head }) : json({ error: 'Archive unavailable' }, 404);
       }
       if (path === '/api/v1/archive/read') {
         const input = readSchema.parse(body),
-          archive = store.read(input.archiveId, input.revision);
+          archive = await store.read(input.archiveId, input.revision);
         return archive ? json({ data: archive }) : json({ error: 'Archive unavailable' }, 404);
       }
       if (path === '/api/v1/archive/list') {
         const { limit, beforeId, ...filter } = listSchema.parse(body);
-        const result = page(store.list(filter), limit, beforeId);
+        const result = await store.page(filter, limit, beforeId);
         if (!result) return json({ error: 'Invalid cursor' }, 400);
         return json({ data: { archives: result.items, nextCursor: result.nextCursor } });
       }
       if (path === '/api/v1/archive/search') {
         const { query, budget, limit, beforeId, ...filter } = searchSchema.parse(body);
-        let remaining = budget;
-        const matching = store
-          .list(filter)
-          .filter(
-            (a) =>
-              !query ||
-              selectChunks(store.read(a.id)!.chunks, query, budget).matchingChunks > 0 ||
-              [a.title, ...a.tags].some((text) => text.toLowerCase().includes(query.toLowerCase())),
+        const lower = query.toLowerCase();
+        const result = await store.page(filter, limit, beforeId, async (listings) => {
+          if (!query) return new Set(listings.map((a) => a.id));
+          const hits = await store.matching(
+            listings.map((a) => a.id),
+            query,
           );
-        const result = page(matching, limit, beforeId);
+          for (const a of listings)
+            if ([a.title, ...a.tags].some((text) => text.toLowerCase().includes(lower)))
+              hits.add(a.id);
+          return hits;
+        });
         if (!result) return json({ error: 'Invalid cursor' }, 400);
-        const archives = result.items.map((a) => {
+        let remaining = budget;
+        const archives = [];
+        for (const a of result.items) {
           const selected =
             remaining >= 16
-              ? selectChunks(store.read(a.id)!.chunks, query, remaining)
+              ? selectChunks((await store.read(a.id))!.chunks, query, remaining)
               : { chunks: [], tokenCount: 0 };
           remaining -= selected.tokenCount;
-          return {
+          archives.push({
             archiveId: a.id,
             revision: a.revision,
             digest: a.digest,
@@ -140,37 +128,43 @@ export function createArchiveHandler(store: LocalArchiveStore, token: string) {
             references: a.references,
             coverage: a.coverage,
             ...selected,
-          };
-        });
+          });
+        }
         return json({
           data: { archives, tokenCount: budget - remaining, nextCursor: result.nextCursor },
         });
       }
       if (path === '/api/v1/archive/tag') {
         const input = tagSchema.parse(body);
-        if (!store.read(input.archiveId)) return json({ error: 'Archive unavailable' }, 404);
-        return json({ data: store.tag(input.archiveId, input) });
+        if (!(await store.read(input.archiveId)))
+          return json({ error: 'Archive unavailable' }, 404);
+        return json({ data: await store.tag(input.archiveId, input) });
       }
       if (path === '/api/v1/archive/delete') {
         const input = readSchema.pick({ archiveId: true }).parse(body);
-        return store.delete(input.archiveId)
+        return (await store.delete(input.archiveId))
           ? json({ data: { archiveId: input.archiveId, deleted: true } })
           : json({ error: 'Archive unavailable' }, 404);
       }
       if (path === '/api/v1/archive/settings/read') {
         z.strictObject({}).parse(body);
-        return json({ data: store.settings() });
+        return json({ data: await store.settings() });
       }
       if (path === '/api/v1/archive/settings/update')
-        return json({ data: store.updateSettings(archiveSettingsSchema.partial().parse(body)) });
+        return json({
+          data: await store.updateSettings(archiveSettingsSchema.partial().parse(body)),
+        });
       if (path === '/api/v1/archive/tags/list')
-        return json({ data: { tags: store.tagDefinitions(tagListSchema.parse(body).actorId) } });
+        return json({
+          data: { tags: await store.tagDefinitions(tagListSchema.parse(body).actorId) },
+        });
       if (path === '/api/v1/archive/tags/define')
-        return json({ data: store.defineTag(tagDefinitionSchema.parse(body)) });
+        return json({ data: await store.defineTag(tagDefinitionSchema.parse(body)) });
       if (path === '/api/v1/archive/tags/remove')
-        return json({ data: { removed: store.undefineTag(tagRemoveSchema.parse(body)) } });
+        return json({ data: { removed: await store.undefineTag(tagRemoveSchema.parse(body)) } });
       return json({ error: 'Not found' }, 404);
     } catch (error) {
+      if (error instanceof ArchiveConflict) return json({ error: error.message }, 409);
       if (error instanceof z.ZodError || error instanceof SyntaxError)
         return json({ error: 'Invalid archive request' }, 400);
       return json({ error: 'Archive operation failed' }, 500);
@@ -178,20 +172,20 @@ export function createArchiveHandler(store: LocalArchiveStore, token: string) {
   };
 }
 
-export function startArchiveServer(options: {
-  store: string;
+export async function startArchiveServer(options: {
+  databaseUrl: string;
   token: string;
   port?: number;
   hostname?: string;
 }) {
-  const store = new LocalArchiveStore(options.store);
-  // Retention runs at start and hourly; it only ever deletes from this archive.
-  store.prune();
-  const retention = setInterval(() => store.prune(), 3_600_000);
-  retention.unref();
+  const store = new ArchiveStore(options.databaseUrl);
   try {
+    // Retention runs at start and hourly; it only ever deletes from this archive.
+    await store.prune();
+    const retention = setInterval(() => void store.prune().catch(() => {}), 3_600_000);
+    retention.unref();
     const server = Bun.serve({
-      port: options.port ?? 4411,
+      port: options.port ?? 4700,
       hostname: options.hostname ?? '127.0.0.1',
       maxRequestBodySize: 65_000_000,
       fetch: createArchiveHandler(store, options.token),
@@ -202,12 +196,11 @@ export function startArchiveServer(options: {
       async close() {
         clearInterval(retention);
         await server.stop(true);
-        store.close();
+        await store.close();
       },
     };
   } catch (error) {
-    clearInterval(retention);
-    store.close();
+    await store.close();
     throw error;
   }
 }

package/src/store.ts

@@ -0,0 +1,438 @@
+import { randomUUID } from 'node:crypto';
+import { type Prisma, PrismaClient } from '@prisma/client';
+import { z } from 'zod';
+import {
+  type ArchiveChunk,
+  type ArchiveSnapshot,
+  archiveKey,
+  archiveSnapshotSchema,
+  chunkArchive,
+  selectChunks,
+  snapshotDigest,
+} from './index';
+import {
+  type ArchiveFilter,
+  type ArchiveSettings,
+  archiveSettingsSchema,
+  defaultSettings,
+  type TagDefinition,
+  tagDefinitionSchema,
+  tagSchema,
+} from './schemas';
+import { archiveReferences, suggestTags } from './tags';
+
+export {
+  type ArchiveFilter,
+  type ArchiveSettings,
+  archiveSettingsSchema,
+  type TagDefinition,
+  tagDefinitionSchema,
+} from './schemas';
+
+const summarize = (snapshot: ArchiveSnapshot, settings: ArchiveSettings) => {
+  const { entries, tags, ...metadata } = snapshot;
+  const models = new Map<string, { model: string; effort?: string; entries: number }>();
+  for (const entry of entries) {
+    if (!entry.model) continue;
+    const key = JSON.stringify([entry.model, entry.effort]);
+    const current = models.get(key) ?? {
+      model: entry.model,
+      ...(entry.effort ? { effort: entry.effort } : {}),
+      entries: 0,
+    };
+    current.entries++;
+    models.set(key, current);
+  }
+  return {
+    ...metadata,
+    capturedTags: tags,
+    entries: entries.length,
+    models: [...models.values()],
+    suggestedTags: suggestTags(snapshot),
+    references: archiveReferences(snapshot, settings.integrations),
+  };
+};
+type Summary = ReturnType<typeof summarize>;
+
+const toChunk = (row: {
+  id: string;
+  entryId: string;
+  sourceRef: string;
+  kind: string;
+  start: number;
+  end: number;
+  text: string;
+  tokenCount: number;
+}): ArchiveChunk => ({
+  id: row.id,
+  entryId: row.entryId,
+  sourceRef: row.sourceRef,
+  kind: row.kind as ArchiveChunk['kind'],
+  start: row.start,
+  end: row.end,
+  text: row.text,
+  tokenCount: row.tokenCount,
+  encoding: 'cl100k_base',
+});
+
+const BATCH = 500;
+
+type ArchiveRow = {
+  id: string;
+  revision: number;
+  digest: string;
+  summary: Prisma.JsonValue;
+  tagEdits: { tag: string; added: boolean }[];
+};
+const listing = (row: ArchiveRow, filter: ArchiveFilter) => {
+  const { capturedTags, ...summary } = row.summary as Summary;
+  const removed = new Set(row.tagEdits.filter((e) => !e.added).map((e) => e.tag));
+  const tags = [
+    ...new Set([...capturedTags, ...row.tagEdits.filter((e) => e.added).map((e) => e.tag)]),
+  ].filter((tag) => !removed.has(tag));
+  const { reference, model, effort } = filter;
+  if (
+    (filter.tag && !tags.includes(filter.tag)) ||
+    (model && !summary.models.some((m) => m.model === model)) ||
+    (effort && !summary.models.some((m) => m.effort === effort && (!model || m.model === model))) ||
+    (reference &&
+      !summary.references.some(
+        (r) => r.integration === reference.integration && r.ref === reference.ref,
+      ))
+  )
+    return [];
+  return [{ id: row.id, revision: row.revision, digest: row.digest, ...summary, tags }];
+};
+export type ArchiveListing = ReturnType<typeof listing>[number];
+
+/** One archive on Postgres. One deployment is one ownership boundary. */
+export class ArchiveStore {
+  readonly db: PrismaClient;
+  private cachedSourceId?: string;
+  constructor(databaseUrl: string) {
+    this.db = new PrismaClient({ datasourceUrl: databaseUrl });
+  }
+  /** This archive's identity, stamped into the snapshots its collectors capture. */
+  async sourceId() {
+    if (this.cachedSourceId) return this.cachedSourceId;
+    const row = await this.db.setting.upsert({
+      where: { key: 'sourceId' },
+      create: { key: 'sourceId', value: randomUUID() },
+      update: {},
+    });
+    this.cachedSourceId = z.uuid().parse(row.value);
+    return this.cachedSourceId;
+  }
+  async capture(input: unknown, expected?: { previousDigest: string | null }) {
+    const snapshot = archiveSnapshotSchema.parse(input);
+    const id = archiveKey(snapshot);
+    const digest = snapshotDigest(snapshot);
+    const settings = await this.settings();
+    return this.db.$transaction(
+      async (tx) => {
+        // Serializes concurrent captures of one session.
+        await tx.$executeRaw`SELECT 1 FROM pg_advisory_xact_lock(hashtext(${id}))`;
+        const old = await tx.archive.findUnique({ where: { id } });
+        if (old?.digest === digest) return { id, digest, revision: old.revision, changed: false };
+        if (expected && (old?.digest ?? null) !== expected.previousDigest)
+          throw new ArchiveConflict('Revision conflict');
+        if (old && old.capturedAt > snapshot.capturedAt) throw new ArchiveConflict('Stale capture');
+        const revision = (old?.revision ?? 0) + 1;
+        const fields = {
+          digest,
+          revision,
+          source: snapshot.source,
+          projectId: snapshot.projectId ?? null,
+          actorId: snapshot.actor?.id ?? null,
+          capturedAt: snapshot.capturedAt,
+          summary: summarize(snapshot, settings) as Prisma.InputJsonValue,
+        };
+        await tx.archive.upsert({ where: { id }, create: { id, ...fields }, update: fields });
+        await tx.revision.create({
+          data: { archiveId: id, revision, digest, snapshot: snapshot as Prisma.InputJsonValue },
+        });
+        const chunks = chunkArchive(snapshot);
+        for (let offset = 0; offset < chunks.length; offset += 1000)
+          await tx.chunk.createMany({
+            data: chunks.slice(offset, offset + 1000).map(({ encoding: _, ...chunk }, i) => ({
+              archiveId: id,
+              revision,
+              position: offset + i,
+              ...chunk,
+            })),
+          });
+        return { id, digest, revision, changed: true };
+        // A 64 MB session writes tens of thousands of chunks.
+      },
+      { timeout: 120_000, maxWait: 30_000 },
+    );
+  }
+  /** Current digest and revision without the content. */
+  async head(id: string) {
+    const row = await this.db.archive.findUnique({
+      where: { id },
+      select: { id: true, digest: true, revision: true, projectId: true },
+    });
+    return row ?? undefined;
+  }
+  async read(id: string, revision?: number) {
+    const archive = await this.db.archive.findUnique({ where: { id } });
+    if (!archive) return undefined;
+    const row = await this.db.revision.findUnique({
+      where: { archiveId_revision: { archiveId: id, revision: revision ?? archive.revision } },
+      include: { chunks: { orderBy: { position: 'asc' } } },
+    });
+    if (!row) return undefined;
+    return {
+      id,
+      revision: row.revision,
+      digest: row.digest,
+      snapshot: archiveSnapshotSchema.parse(row.snapshot),
+      chunks: row.chunks.map(toChunk),
+    };
+  }
+  /**
+   * One page of archive metadata, newest first, read from the database in batches. Tags are the
+   * captured tags with this archive's edits applied. `keep` narrows each batch further (search).
+   */
+  async page(
+    filter: ArchiveFilter,
+    limit: number,
+    beforeId?: string,
+    keep?: (listings: ArchiveListing[]) => Promise<Set<string>>,
+  ) {
+    let cursor: bigint | undefined;
+    if (beforeId) {
+      const before = await this.db.archive.findUnique({
+        where: { id: beforeId },
+        select: { seq: true },
+      });
+      if (!before) return undefined;
+      cursor = before.seq;
+    }
+    const items: ArchiveListing[] = [];
+    while (items.length <= limit) {
+      const rows = await this.db.archive.findMany({
+        where: {
+          ...(filter.projectId ? { projectId: filter.projectId } : {}),
+          ...(filter.source ? { source: filter.source } : {}),
+          ...(filter.actorId ? { actorId: filter.actorId } : {}),
+          ...(cursor === undefined ? {} : { seq: { lt: cursor } }),
+        },
+        include: { tagEdits: true },
+        orderBy: { seq: 'desc' },
+        take: BATCH,
+      });
+      if (!rows.length) break;
+      cursor = rows.at(-1)!.seq;
+      let listings = rows.flatMap((row) => listing(row, filter));
+      if (keep && listings.length) {
+        const kept = await keep(listings);
+        listings = listings.filter((item) => kept.has(item.id));
+      }
+      items.push(...listings);
+      if (rows.length < BATCH) break;
+    }
+    const slice = items.slice(0, limit);
+    return { items: slice, nextCursor: items.length > limit ? slice.at(-1)!.id : null };
+  }
+  /** Every archive matching the filter, newest first. */
+  async list(filter: ArchiveFilter = {}) {
+    const all: ArchiveListing[] = [];
+    let beforeId: string | undefined;
+    do {
+      const result = (await this.page(filter, BATCH, beforeId))!;
+      all.push(...result.items);
+      beforeId = result.nextCursor ?? undefined;
+    } while (beforeId);
+    return all;
+  }
+  /** Ids among `ids` whose current revision has a chunk containing any term. */
+  async matching(ids: string[], query: string) {
+    const terms = [...new Set(query.toLowerCase().match(/[\p{L}\p{N}_-]+/gu) ?? [])].slice(0, 64);
+    if (!terms.length || !ids.length) return new Set(ids);
+    const current = await this.db.archive.findMany({
+      where: { id: { in: ids } },
+      select: { id: true, revision: true },
+    });
+    const rows = await this.db.chunk.findMany({
+      where: {
+        OR: current.map((a) => ({ archiveId: a.id, revision: a.revision })),
+        AND: {
+          OR: terms.map((term) => ({ text: { contains: term, mode: 'insensitive' as const } })),
+        },
+      },
+      distinct: ['archiveId'],
+      select: { archiveId: true },
+    });
+    return new Set(rows.map((row) => row.archiveId));
+  }
+  async search(ids: string[], query: string, budget = 2048) {
+    return Promise.all(
+      ids.map(async (id) => {
+        const archive = await this.read(id);
+        if (!archive) throw new Error('Archive unavailable');
+        return {
+          id,
+          revision: archive.revision,
+          digest: archive.digest,
+          ...selectChunks(archive.chunks, query, budget),
+        };
+      }),
+    );
+  }
+  /** Tag or untag without a new revision. Edits belong to this archive and do not sync. */
+  async tag(id: string, change: { add?: string[]; remove?: string[] }) {
+    const add = z
+      .array(tagSchema)
+      .max(100)
+      .parse(change.add ?? []);
+    const remove = z
+      .array(tagSchema)
+      .max(100)
+      .parse(change.remove ?? []);
+    return this.db.$transaction(async (tx) => {
+      const archive = await tx.archive.findUnique({ where: { id } });
+      if (!archive) throw new Error('Archive unavailable');
+      const captured = new Set((archive.summary as Summary).capturedTags);
+      const set = (tag: string, added: boolean) =>
+        tx.tagEdit.upsert({
+          where: { archiveId_tag: { archiveId: id, tag } },
+          create: { archiveId: id, tag, added },
+          update: { added },
+        });
+      const clear = (tag: string) => tx.tagEdit.deleteMany({ where: { archiveId: id, tag } });
+      for (const tag of add) await (captured.has(tag) ? clear(tag) : set(tag, true));
+      for (const tag of remove) await (captured.has(tag) ? set(tag, false) : clear(tag));
+      const edits = await tx.tagEdit.findMany({ where: { archiveId: id } });
+      const removed = new Set(edits.filter((e) => !e.added).map((e) => e.tag));
+      const tags = [
+        ...new Set([...captured, ...edits.filter((e) => e.added).map((e) => e.tag)]),
+      ].filter((tag) => !removed.has(tag));
+      z.array(tagSchema).max(100, 'An archive holds at most 100 tags').parse(tags);
+      return { id, tags };
+    });
+  }
+  async delete(id: string) {
+    return (await this.db.archive.deleteMany({ where: { id } })).count > 0;
+  }
+  /** Applies the retention setting; returns the deleted archive ids. */
+  async prune(now = Date.now()) {
+    const { retentionDays } = await this.settings();
+    if (retentionDays === null) return [];
+    const expired = await this.db.archive.findMany({
+      where: { capturedAt: { lt: now - retentionDays * 86_400_000 } },
+      select: { id: true },
+    });
+    await this.db.archive.deleteMany({ where: { id: { in: expired.map((a) => a.id) } } });
+    return expired.map((a) => a.id);
+  }
+  async settings(): Promise<ArchiveSettings> {
+    const row = await this.db.setting.findUnique({ where: { key: 'archive' } });
+    return row ? archiveSettingsSchema.parse(row.value) : defaultSettings;
+  }
+  /** Saves settings and recomputes listings together, since references follow the integrations. */
+  async updateSettings(change: Partial<ArchiveSettings>) {
+    const next = archiveSettingsSchema.parse({ ...(await this.settings()), ...change });
+    await this.db.$transaction(
+      async (tx) => {
+        await tx.setting.upsert({
+          where: { key: 'archive' },
+          create: { key: 'archive', value: next },
+          update: { value: next },
+        });
+        const archives = await tx.archive.findMany({ select: { id: true, revision: true } });
+        for (const archive of archives) {
+          const row = await tx.revision.findUnique({
+            where: { archiveId_revision: { archiveId: archive.id, revision: archive.revision } },
+            select: { snapshot: true },
+          });
+          if (!row) continue;
+          await tx.archive.update({
+            where: { id: archive.id },
+            data: {
+              summary: summarize(
+                archiveSnapshotSchema.parse(row.snapshot),
+                next,
+              ) as Prisma.InputJsonValue,
+            },
+          });
+        }
+      },
+      { timeout: 600_000, maxWait: 30_000 },
+    );
+    return next;
+  }
+  /** Offered tags with how many archives carry each; an actor sees archive-wide and their own. */
+  async tagDefinitions(actorId?: string) {
+    const rows = await this.db.tagDefinition.findMany({
+      where: { actorId: { in: ['', actorId ?? ''] } },
+      orderBy: { tag: 'asc' },
+    });
+    const archives = await this.list(actorId ? { actorId } : {});
+    return rows.map((row) => ({
+      tag: row.tag,
+      ...(row.actorId ? { actorId: row.actorId } : {}),
+      ...(row.description ? { description: row.description } : {}),
+      archives: archives.filter((archive) => archive.tags.includes(row.tag)).length,
+    }));
+  }
+  async defineTag(input: TagDefinition) {
+    const definition = tagDefinitionSchema.parse(input);
+    const actorId = definition.actorId ?? '';
+    const description = definition.description ?? null;
+    await this.db.tagDefinition.upsert({
+      where: { actorId_tag: { actorId, tag: definition.tag } },
+      create: { actorId, tag: definition.tag, description },
+      update: { description },
+    });
+    return definition;
+  }
+  async undefineTag(input: { tag: string; actorId?: string }) {
+    return (
+      (
+        await this.db.tagDefinition.deleteMany({
+          where: { actorId: input.actorId ?? '', tag: input.tag },
+        })
+      ).count > 0
+    );
+  }
+  async receipt(id: string, destination: string) {
+    return (
+      (
+        await this.db.receipt.findUnique({
+          where: { archiveId_destination: { archiveId: id, destination } },
+        })
+      )?.digest ?? null
+    );
+  }
+  async pending(id: string, destination: string) {
+    const row = await this.db.outbox.findUnique({
+      where: { archiveId_destination: { archiveId: id, destination } },
+    });
+    return row ? { revision: row.revision } : null;
+  }
+  async enqueue(id: string, destination: string, pending: { revision: number }) {
+    await this.db.outbox.upsert({
+      where: { archiveId_destination: { archiveId: id, destination } },
+      create: { archiveId: id, destination, revision: pending.revision },
+      update: {},
+    });
+  }
+  async delivered(id: string, destination: string, digest: string) {
+    await this.db.$transaction([
+      this.db.receipt.upsert({
+        where: { archiveId_destination: { archiveId: id, destination } },
+        create: { archiveId: id, destination, digest },
+        update: { digest },
+      }),
+      this.db.outbox.deleteMany({ where: { archiveId: id, destination } }),
+    ]);
+  }
+  async close() {
+    await this.db.$disconnect();
+  }
+}
+
+/** A capture that lost a race or arrived out of order; the server answers 409. */
+export class ArchiveConflict extends Error {}