@pepys/api 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@pepys/api</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <p>
+    <a href="https://www.npmjs.com/package/@pepys/api"><img src="https://img.shields.io/npm/v/@pepys/api" alt="npm version"></a>
+    <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/README.md">Documentation</a>
+  </p>
+</div>
+
+The pepys API, for Bun: typed queries over the store that the host writes.
+
+A deployment serves the core queries and each plug-in's queries over oRPC and as MCP tools.
+
+## Install
+
+```sh
+bun add @pepys/api
+```
+
+## Features
+
+- `serveAPI`, which serves a deployment's queries at `/rpc` and as MCP tools at `/mcp`.
+- `DeploymentClient`, the type of a typed client of a deployment's queries.
+- The store reader over the host's Turso files.
+
+## Documentation
+
+The [pepys docs](../../docs/README.md) hold the design of the API and the store.

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@pepys/api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The pepys API: typed queries over the store",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/pepys.git",
+    "directory": "packages/api"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/test-utils"
+  ],
+  "type": "module",
+  "exports": "./src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.4.0",
+    "@orpc/contract": "2.0.0-beta.50",
+    "@orpc/mcp": "2.0.0-beta.50",
+    "@orpc/openapi": "2.0.0-beta.50",
+    "@orpc/server": "2.0.0-beta.50",
+    "@pepys/contract": "0.1.0",
+    "@pepys/kit": "0.1.0",
+    "@pepys/kysely-turso": "0.1.0",
+    "@pepys/schema": "0.1.0",
+    "@tursodatabase/database": "0.8.3",
+    "elysia": "2.0.0-rc.1",
+    "exact-mirror": "1.2.7",
+    "kysely": "0.29.8",
+    "openapi-types": "12.1.3",
+    "tiny-invariant": "1.3.3",
+    "ts-pattern": "5.9.2",
+    "type-fest": "5.10.0",
+    "typebox": "1.4.4",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@orpc/client": "2.0.0-beta.50",
+    "@pepys/testing": "0.1.0",
+    "@zgeoff/std": "0.4.3"
+  }
+}

package/src/app/create-app.ts

@@ -0,0 +1,37 @@
+import { McpServer, createMcpHandler } from '@modelcontextprotocol/server';
+import { McpRegistrar } from '@orpc/mcp';
+import { COMMON_ERROR_STATUS_MAP } from '@orpc/server';
+import { RPCHandler } from '@orpc/server/fetch';
+import { Elysia } from 'elysia';
+import type { QueryContext } from '../queries/types.ts';
+import { createRouter } from './create-router.ts';
+
+// The router at /rpc, and each of its procedures as an MCP tool at /mcp.
+export function createApp(context: QueryContext) {
+  const router = createRouter(context.deployment.queries);
+
+  // A contract's own status has no effect in oRPC v2: the handler's map gives each code its HTTP
+  // status, and a code the map lacks gets 400. The map sets 503 itself, so it rests on no default.
+  const rpc = new RPCHandler(router, {
+    errorStatusMap: { ...COMMON_ERROR_STATUS_MAP, SERVICE_UNAVAILABLE: 503 },
+  });
+
+  const registrar = new McpRegistrar(router);
+
+  // stateless: one server per request, with the tools of the one router
+  const mcp = createMcpHandler(async () => {
+    const server = new McpServer({ name: `pepys-${context.deployment.name}`, version: '1.0.0' });
+
+    await registrar.register(server, { context });
+
+    return server;
+  });
+
+  return new Elysia()
+    .all('/rpc/*', { parse: 'none' }, async (route) => {
+      const result = await rpc.handle(route.request, { prefix: '/rpc', context });
+
+      return result.matched ? result.response : new Response('not found', { status: 404 });
+    })
+    .all('/mcp', { parse: 'none' }, (route) => mcp.fetch(route.request));
+}

package/src/app/create-router.ts

@@ -0,0 +1,85 @@
+import { oc } from '@orpc/contract';
+import { openapi } from '@orpc/openapi';
+import { implement } from '@orpc/server';
+import type { Router } from '@orpc/server';
+import { coreContract } from '@pepys/contract';
+import type { AnyQueryDefinition } from '@pepys/kit';
+import { z } from 'zod';
+import { readEntity } from '../queries/get-entity/read-entity.ts';
+import { walkNeighbourhood } from '../queries/neighbourhood/walk-neighbourhood.ts';
+import type { QueryContext } from '../queries/types.ts';
+import { runPluginQuery } from './run-plugin-query.ts';
+
+// One flat router: the two core procedures and each plug-in query, by its snake case name, which
+// is also its MCP tool name. The deployment check refuses a query named as a core procedure.
+export function createRouter(queries: readonly AnyQueryDefinition[]): Router<QueryContext> {
+  const core = implement(coreContract).$context<QueryContext>();
+
+  const router: Record<string, Router<QueryContext>> = {
+    get_entity: core.get_entity.handler(async (options) => {
+      const result = await readEntity(options.context, options.input.id);
+
+      if (!result.ok) {
+        const buildError = options.errors[result.failure.code];
+
+        throw buildError({ message: result.failure.message });
+      }
+
+      return result.value;
+    }),
+    neighbourhood: core.neighbourhood.handler(async (options) => {
+      const result = await walkNeighbourhood(options.context, options.input);
+
+      if (!result.ok) {
+        const buildError = options.errors[result.failure.code];
+
+        throw buildError({ message: result.failure.message });
+      }
+
+      return result.value;
+    }),
+  };
+
+  for (const query of queries) {
+    if (hasTransform(query)) {
+      throw new Error(
+        `the query ${query.name} has a zod transform, which an MCP tool schema cannot carry`,
+      );
+    }
+
+    const contract = oc
+      .errors({ SERVICE_UNAVAILABLE: {} })
+      .meta(openapi({ description: query.description }))
+      .input(query.input)
+      .output(query.output);
+
+    router[query.name] = implement(contract)
+      .$context<QueryContext>()
+      .handler(async (options) => {
+        const result = await runPluginQuery(options.context.store, query, options.input);
+
+        if (!result.ok) {
+          const buildUnavailable = options.errors.SERVICE_UNAVAILABLE;
+          const consumers = result.failure.consumers.join(', ');
+
+          throw buildUnavailable({ message: `the consumers ${consumers} have no current version` });
+        }
+
+        return result.value;
+      });
+  }
+
+  return router;
+}
+
+// zod writes no JSON Schema for the output of a transform, and throws instead.
+function hasTransform(query: AnyQueryDefinition): boolean {
+  try {
+    z.toJSONSchema(query.input, { io: 'output' });
+    z.toJSONSchema(query.output, { io: 'output' });
+
+    return false;
+  } catch {
+    return true;
+  }
+}

package/src/app/run-plugin-query.ts

@@ -0,0 +1,31 @@
+import type {
+  AnyQueryDefinition,
+  QueryDefinition,
+  Result,
+  StoreReader,
+  StoreReaderFailure,
+} from '@pepys/kit';
+
+// Runs one plug-in query's handler on the files of the consumers it reads. The router has parsed
+// `input` with the query's own input schema, and parses the answer with its output schema.
+export async function runPluginQuery(
+  store: StoreReader,
+  query: AnyQueryDefinition,
+  input: unknown,
+): Promise<Result<unknown, StoreReaderFailure>> {
+  const handler: unknown = query.handler;
+
+  if (!isQueryHandler(handler)) {
+    throw new TypeError(`the query ${query.name} has no handler`);
+  }
+
+  const result = await store.withConsumers(query.reads, (db) => handler({ input, db }));
+
+  return result;
+}
+
+// A list of queries types each handler's call as `never`, since no one call type fits every
+// handler. Each handler takes the call that its own input schema parses, which the router gives.
+function isQueryHandler(handler: unknown): handler is QueryDefinition['handler'] {
+  return typeof handler === 'function';
+}

package/src/client/deployment-client.ts

@@ -0,0 +1,9 @@
+import type { ContractRouterClient } from '@orpc/contract';
+import type { CoreContract } from '@pepys/contract';
+import type { Deployment, PluginClient } from '@pepys/kit';
+import type { UnionToIntersection } from 'type-fest';
+
+// The typed client of one deployment: the core procedures, then each plug-in query by its name. A
+// caller that needs one plug-in's queries alone uses the kit's PluginClient.
+export type DeploymentClient<Target extends Deployment> = ContractRouterClient<CoreContract> &
+  UnionToIntersection<PluginClient<Target['plugins'][number]>>;

package/src/config/read-api-config.ts

@@ -0,0 +1,33 @@
+import type { Result } from '@pepys/kit';
+import { parsePort } from '@pepys/schema';
+
+export interface APIConfig {
+  storeDirectory: string;
+
+  // the listen address; 127.0.0.1 unless the deployment sets another
+  host: string;
+  port: number;
+}
+
+export function readAPIConfig(
+  environment: Readonly<Record<string, string | undefined>>,
+): Result<APIConfig, string[]> {
+  const storeDirectory = environment['PEPYS_STORE_DIR'] ?? '';
+  const host = environment['PEPYS_API_HOST'] ?? '';
+  const portText = environment['PEPYS_API_PORT'] ?? '';
+  const port = portText === '' ? ({ ok: true, value: 8081 } as const) : parsePort(portText);
+
+  const problems = [
+    ...(storeDirectory === '' ? ['PEPYS_STORE_DIR is not set'] : []),
+    ...(port.ok ? [] : ['PEPYS_API_PORT is not a port number']),
+  ];
+
+  if (!port.ok || problems.length > 0) {
+    return { ok: false, failure: problems };
+  }
+
+  return {
+    ok: true,
+    value: { storeDirectory, host: host === '' ? '127.0.0.1' : host, port: port.value },
+  };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { createApp } from './app/create-app.ts';
+export { createRouter } from './app/create-router.ts';
+export type { DeploymentClient } from './client/deployment-client.ts';
+export { readAPIConfig } from './config/read-api-config.ts';
+export { buildQueryContext } from './queries/build-query-context.ts';
+export type { QueryContext } from './queries/types.ts';
+export { serveAPI } from './serve/serve-api.ts';
+export { createStoreReader } from './store-reader/create-store-reader.ts';
+export { readChangeOperations } from './store-reader/read-change-operations.ts';
+export { readOffsets } from './store-reader/read-offsets.ts';

package/src/queries/build-query-context.ts

@@ -0,0 +1,13 @@
+import { buildLinkRegistry } from '@pepys/kit';
+import type { CheckedDeployment, StoreReader } from '@pepys/kit';
+import { buildEntityKindIndex } from './entity-kinds/build-entity-kind-index.ts';
+import type { QueryContext } from './types.ts';
+
+export function buildQueryContext(store: StoreReader, deployment: CheckedDeployment): QueryContext {
+  return {
+    store,
+    deployment,
+    entityKinds: buildEntityKindIndex(deployment.consumers),
+    linkRegistry: buildLinkRegistry(deployment.linkTypes),
+  };
+}

package/src/queries/entity-kinds/build-entity-kind-index.ts

@@ -0,0 +1,17 @@
+import type { ConsumerDeclaration, EntityKind, EntityViewDeclaration } from '@pepys/kit';
+
+interface EntityOwner {
+  consumer: ConsumerDeclaration;
+  view: EntityViewDeclaration;
+}
+
+// Which consumer and table hold each kind. The deployment check refuses two views of one kind.
+export type EntityKindIndex = ReadonlyMap<string, EntityOwner>;
+
+export function buildEntityKindIndex(consumers: readonly ConsumerDeclaration[]): EntityKindIndex {
+  return new Map<EntityKind, EntityOwner>(
+    consumers.flatMap((consumer) =>
+      consumer.entityViews.map((view) => [view.kind, { consumer, view }] as const),
+    ),
+  );
+}

package/src/queries/get-entity/build-entity-row.ts

@@ -0,0 +1,23 @@
+import type { ColumnDeclaration, TableDeclaration } from '@pepys/kit';
+import { match } from 'ts-pattern';
+
+export function buildEntityRow(
+  table: TableDeclaration,
+  stored: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(table.columns).map(([name, column]) => [name, toValue(column, stored[name])]),
+  );
+}
+
+function toValue(column: ColumnDeclaration, stored: unknown): unknown {
+  return match(column.kind)
+    .with('boolean', () => (stored === null ? null : stored === 1))
+    .with('json', () => (typeof stored === 'string' ? parseJSON(stored) : stored))
+    .with('text', 'integer', 'real', 'entityID', 'timestamp', () => stored)
+    .exhaustive();
+}
+
+function parseJSON(text: string): unknown {
+  return JSON.parse(text);
+}

package/src/queries/get-entity/read-entity.ts

@@ -0,0 +1,86 @@
+import type { CoreOutputs } from '@pepys/contract';
+import { parseEntityID } from '@pepys/kit';
+import type { Result } from '@pepys/kit';
+import { sql } from 'kysely';
+import invariant from 'tiny-invariant';
+import { z } from 'zod';
+import type { QueryContext, QueryFailure } from '../types.ts';
+import { buildEntityRow } from './build-entity-row.ts';
+
+const storedRowSchema = z.record(z.string(), z.unknown());
+const storedRowsSchema = z.object({ rows: z.array(storedRowSchema) });
+
+type EntityOutput = CoreOutputs['get_entity'];
+
+// The kind in the ID names the owning consumer, so the call attaches that one file.
+export async function readEntity(
+  context: QueryContext,
+  id: string,
+): Promise<Result<EntityOutput, QueryFailure>> {
+  const parsed = parseEntityID(id);
+
+  if (!parsed.ok) {
+    return {
+      ok: false,
+      failure: {
+        code: 'BAD_REQUEST',
+        message: `${id} is not an entity ID: ${parsed.failure.reason}`,
+      },
+    };
+  }
+
+  const notFound = {
+    ok: false,
+    failure: { code: 'NOT_FOUND', message: `no entity ${id}` },
+  } as const;
+
+  const owner = context.entityKinds.get(`${parsed.value.source}:${parsed.value.kind}`);
+
+  if (owner === undefined) {
+    return notFound;
+  }
+
+  const read = await context.store.withConsumers([owner.consumer], async (db) => {
+    const entity = await db
+      .selectFrom('entity')
+      .selectAll()
+      .where('id', '=', id)
+      .executeTakeFirst();
+
+    if (entity === undefined) {
+      return null;
+    }
+
+    // the names come from the declaration, never from the input
+    const table = sql.table(owner.view.table);
+    const idColumn = sql.ref(owner.view.id);
+
+    const result = await sql`select * from ${table} where ${idColumn} = ${id}`.execute(db);
+
+    const [stored] = storedRowsSchema.parse(result).rows;
+    const declaration = owner.consumer.tables[owner.view.table];
+
+    invariant(stored !== undefined && declaration !== undefined, 'an entity row has a table row');
+
+    const value: EntityOutput = {
+      entity,
+      consumer: owner.consumer.name,
+      table: owner.view.table,
+      row: buildEntityRow(declaration, stored),
+    };
+
+    return value;
+  });
+
+  if (!read.ok) {
+    return {
+      ok: false,
+      failure: {
+        code: 'SERVICE_UNAVAILABLE',
+        message: `the consumer ${read.failure.consumers.join(', ')} has no current version`,
+      },
+    };
+  }
+
+  return read.value === null ? notFound : { ok: true, value: read.value };
+}

package/src/queries/neighbourhood/pick-link-types.ts

@@ -0,0 +1,30 @@
+import type { LinkRegistry, Result } from '@pepys/kit';
+
+interface LinkTypeChoice {
+  linkTypes: readonly string[] | null;
+  includeHubs: boolean;
+}
+
+interface UnknownLinkTypes {
+  unknown: readonly string[];
+  known: readonly string[];
+}
+
+// The link types a walk follows: the named ones, or every one, with a hub type only when the
+// caller includes hubs.
+export function pickLinkTypes(
+  registry: LinkRegistry,
+  choice: LinkTypeChoice,
+): Result<readonly string[], UnknownLinkTypes> {
+  const known = [...registry.keys()].toSorted();
+  const named = choice.linkTypes ?? known;
+  const unknown = [...new Set(named.filter((name) => !registry.has(name)))].toSorted();
+
+  if (unknown.length > 0) {
+    return { ok: false, failure: { unknown, known } };
+  }
+
+  const followed = named.filter((name) => choice.includeHubs || registry.get(name)?.hub === false);
+
+  return { ok: true, value: [...new Set(followed)].toSorted() };
+}

package/src/queries/neighbourhood/take-hop.ts

@@ -0,0 +1,97 @@
+import type { LinkRow } from '@pepys/kit';
+import { compareText } from '../../utils/compare-text.ts';
+
+interface WalkLink {
+  type: string;
+  from: string;
+  to: string;
+  direction: 'outgoing' | 'incoming';
+  origin: string;
+  confidence: number;
+  depth: number;
+}
+
+export interface WalkState {
+  // every ID seen, with the depth it was first seen at; the cycle guard
+  depths: ReadonlyMap<string, number>;
+  links: readonly WalkLink[];
+
+  // the IDs the next hop expands
+  frontier: readonly string[];
+  isTruncated: boolean;
+}
+
+interface Hop {
+  depth: number;
+  entityLimit: number;
+  linkReadLimit: number;
+}
+
+// One hop, from the link rows that touch the frontier in read order. Two origins of one link merge
+// at the highest confidence; new IDs join in ID order while the entity limit has room.
+export function takeHop(state: WalkState, rows: readonly LinkRow[], hop: Hop): WalkState {
+  const frontier = new Set(state.frontier);
+  const followed = new Set(state.links.map((link) => toLinkKey(link.type, link.from, link.to)));
+  const merged = new Map<string, LinkRow>();
+
+  for (const row of rows.slice(0, hop.linkReadLimit)) {
+    const key = toLinkKey(row.type, row.from_id, row.to_id);
+    const held = merged.get(key);
+
+    if (!followed.has(key) && (held === undefined || row.confidence > held.confidence)) {
+      merged.set(key, row);
+    }
+  }
+
+  const candidates = [...merged.values()].map((row) => {
+    const isOutgoing = frontier.has(row.from_id);
+
+    return {
+      link: {
+        type: row.type,
+        from: row.from_id,
+        to: row.to_id,
+        direction: isOutgoing ? 'outgoing' : 'incoming',
+        origin: row.origin,
+        confidence: row.confidence,
+        depth: hop.depth,
+      } satisfies WalkLink,
+      reached: isOutgoing ? row.to_id : row.from_id,
+    };
+  });
+
+  const newIDs = [
+    ...new Set(
+      candidates.map((candidate) => candidate.reached).filter((id) => !state.depths.has(id)),
+    ),
+  ].toSorted();
+
+  const room = Math.max(0, hop.entityLimit - state.depths.size);
+  const admitted = newIDs.slice(0, room);
+
+  const depths = new Map([...state.depths, ...admitted.map((id) => [id, hop.depth] as const)]);
+
+  const links = candidates
+    .filter((candidate) => depths.has(candidate.reached))
+    .map((candidate) => candidate.link)
+    .toSorted(compareLinks);
+
+  return {
+    depths,
+    links: [...state.links, ...links],
+    frontier: admitted,
+    isTruncated: state.isTruncated || rows.length > hop.linkReadLimit || newIDs.length > room,
+  };
+}
+
+function toLinkKey(type: string, from: string, to: string): string {
+  return JSON.stringify([type, from, to]);
+}
+
+function compareLinks(first: WalkLink, second: WalkLink): number {
+  return (
+    compareText(first.type, second.type) ||
+    compareText(first.from, second.from) ||
+    compareText(first.to, second.to)
+  );
+}

package/src/queries/neighbourhood/walk-neighbourhood.ts

@@ -0,0 +1,121 @@
+import type { CoreOutputs, CoreParsedInputs } from '@pepys/contract';
+import { neighbourhoodCaps } from '@pepys/contract';
+import { parseEntityID } from '@pepys/kit';
+import type { Result } from '@pepys/kit';
+import invariant from 'tiny-invariant';
+import { compareText } from '../../utils/compare-text.ts';
+import type { QueryContext, QueryFailure } from '../types.ts';
+import { pickLinkTypes } from './pick-link-types.ts';
+import { takeHop } from './take-hop.ts';
+import type { WalkState } from './take-hop.ts';
+
+type NeighbourhoodInput = CoreParsedInputs['neighbourhood'];
+
+type NeighbourhoodOutput = CoreOutputs['neighbourhood'];
+
+// A breadth-first walk with one read of the link view per hop. Every consumer with a current
+// version is attached, and none is required, so a consumer with none is skipped and named.
+export async function walkNeighbourhood(
+  context: QueryContext,
+  input: NeighbourhoodInput,
+): Promise<Result<NeighbourhoodOutput, QueryFailure<'NOT_FOUND' | 'BAD_REQUEST'>>> {
+  const parsed = parseEntityID(input.id);
+
+  if (!parsed.ok) {
+    const message = `${input.id} is not an entity ID: ${parsed.failure.reason}`;
+
+    return { ok: false, failure: { code: 'BAD_REQUEST', message } };
+  }
+
+  const kind = `${parsed.value.source}:${parsed.value.kind}`;
+
+  if (!context.deployment.entityKinds.some((known) => known === kind)) {
+    return {
+      ok: false,
+      failure: { code: 'NOT_FOUND', message: `no plug-in brings the kind ${kind}` },
+    };
+  }
+
+  const types = pickLinkTypes(context.linkRegistry, input);
+
+  if (!types.ok) {
+    const message = `unknown link types ${types.failure.unknown.join(', ')}; the known ones are ${types.failure.known.join(', ')}`;
+
+    return { ok: false, failure: { code: 'BAD_REQUEST', message } };
+  }
+
+  const read = await context.store.withConsumers(
+    [],
+    async (db, call) => {
+      let state: WalkState = {
+        depths: new Map([[input.id, 0]]),
+        links: [],
+        frontier: [input.id],
+        isTruncated: false,
+      };
+
+      for (let depth = 1; depth <= input.depthLimit && state.frontier.length > 0; depth += 1) {
+        const frontier = state.frontier;
+
+        const rows =
+          types.value.length === 0
+            ? []
+            : await db
+                .selectFrom('link_effective')
+                .selectAll()
+                .where('type', 'in', types.value)
+                .where('confidence', '>=', input.minimumConfidence)
+                .where((builder) =>
+                  builder.or([
+                    builder('from_id', 'in', frontier),
+                    builder('to_id', 'in', frontier),
+                  ]),
+                )
+                .orderBy('type')
+                .orderBy('from_id')
+                .orderBy('to_id')
+                .orderBy('origin')
+                .limit(neighbourhoodCaps.linkReadLimit + 1)
+                .execute();
+
+        state = takeHop(state, rows, {
+          depth,
+          entityLimit: input.entityLimit,
+          linkReadLimit: neighbourhoodCaps.linkReadLimit,
+        });
+      }
+
+      const entities = await db
+        .selectFrom('entity')
+        .selectAll()
+        .where('id', 'in', [...state.depths.keys()])
+        .execute();
+
+      return { state, entities, skipped: call.skipped };
+    },
+    { whenCurrent: context.deployment.consumers },
+  );
+
+  invariant(read.ok, 'a call with no required consumer always runs');
+
+  const state = read.value.state;
+
+  const found = new Set(read.value.entities.map((entity) => entity.id));
+
+  const entities = read.value.entities.map((entity) =>
+    Object.assign(entity, { depth: state.depths.get(entity.id) ?? 0 }),
+  );
+
+  return {
+    ok: true,
+    value: {
+      entities: entities.toSorted(
+        (first, second) => first.depth - second.depth || compareText(first.id, second.id),
+      ),
+      links: state.links.toSorted((first, second) => first.depth - second.depth),
+      unresolved: [...state.depths.keys()].filter((id) => !found.has(id)).toSorted(),
+      skippedConsumers: [...read.value.skipped],
+      isTruncated: state.isTruncated,
+    },
+  };
+}

package/src/queries/types.ts

@@ -0,0 +1,19 @@
+import type { CheckedDeployment, LinkRegistry, StoreReader } from '@pepys/kit';
+import type { EntityKindIndex } from './entity-kinds/build-entity-kind-index.ts';
+
+export interface QueryContext {
+  store: StoreReader;
+  deployment: CheckedDeployment;
+  entityKinds: EntityKindIndex;
+  linkRegistry: LinkRegistry;
+}
+
+export interface QueryFailure<
+  Code extends 'NOT_FOUND' | 'BAD_REQUEST' | 'SERVICE_UNAVAILABLE' =
+    | 'NOT_FOUND'
+    | 'BAD_REQUEST'
+    | 'SERVICE_UNAVAILABLE',
+> {
+  code: Code;
+  message: string;
+}

package/src/serve/serve-api.ts

@@ -0,0 +1,53 @@
+import { checkDeployment } from '@pepys/kit';
+import type { Deployment } from '@pepys/kit';
+import { makeShutdownHandler } from '@pepys/schema';
+import { createApp } from '../app/create-app.ts';
+import { readAPIConfig } from '../config/read-api-config.ts';
+import { buildQueryContext } from '../queries/build-query-context.ts';
+import { createStoreReader } from '../store-reader/create-store-reader.ts';
+
+interface ServeAPIOptions {
+  deployment: Deployment;
+  environment: Readonly<Record<string, string | undefined>>;
+}
+
+// The API process of a deployment: oRPC at /rpc and MCP at /mcp, on the listen address from the
+// environment. It exits 1 at start on a failed deployment check or a bad variable.
+export function serveAPI(options: ServeAPIOptions): void {
+  const checked = checkDeployment(options.deployment);
+
+  if (!checked.ok) {
+    console.error('the deployment fails its check', JSON.stringify(checked.failure));
+    process.exit(1);
+  }
+
+  const config = readAPIConfig(options.environment);
+
+  if (!config.ok) {
+    console.error(config.failure.join('\n'));
+    process.exit(1);
+  }
+
+  const store = createStoreReader({ storeDirectory: config.value.storeDirectory });
+  const app = createApp(buildQueryContext(store, checked.value));
+
+  app.listen({ hostname: config.value.host, port: config.value.port });
+  console.log(`api listening on ${config.value.host}:${app.server?.port}`);
+
+  const shutdown = makeShutdownHandler({
+    stop: async () => {
+      await app.stop();
+      await store.close();
+    },
+    logError: (message, error) => {
+      console.error(message, error);
+    },
+    exit: (code) => process.exit(code),
+  });
+
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+    process.on(signal, () => {
+      void shutdown();
+    });
+  }
+}

package/src/store-reader/build-shared-views-plugin.ts

@@ -0,0 +1,86 @@
+import type { ConsumerDeclaration } from '@pepys/kit';
+import {
+  DummyDriver,
+  Kysely,
+  SelectQueryNode,
+  SqliteAdapter,
+  SqliteIntrospector,
+  SqliteQueryCompiler,
+  sql,
+} from 'kysely';
+import type { KyselyPlugin, WithNode } from 'kysely';
+import invariant from 'tiny-invariant';
+
+// Turso refuses a TEMP view over an attached file, so the shared views are common table expressions
+// in front of every query. Each file holds its own `entity` view, and a bare name reads the first
+// attached file's alone; a common table expression of the same name wins over it.
+export function buildSharedViewsPlugin(attached: readonly ConsumerDeclaration[]): KyselyPlugin {
+  const views = collectSharedViews(attached);
+
+  return {
+    transformQuery: (args) => {
+      if (!SelectQueryNode.is(args.node)) {
+        return args.node;
+      }
+
+      return {
+        ...args.node,
+        with: {
+          ...views,
+          expressions: [...views.expressions, ...(args.node.with?.expressions ?? [])],
+        },
+      };
+    },
+    transformResult: (args) => Promise.resolve(args.result),
+  };
+}
+
+// A builder that compiles and never connects: it only makes the operation nodes. Its tables are
+// the attached files' own, named `<consumer>.entity` and `<consumer>.link`.
+const builder = new Kysely<Record<string, Record<string, unknown>>>({
+  dialect: {
+    createAdapter: () => new SqliteAdapter(),
+    createDriver: () => new DummyDriver(),
+    createIntrospector: (db) => new SqliteIntrospector(db),
+    createQueryCompiler: () => new SqliteQueryCompiler(),
+  },
+});
+
+const entityColumns = ['id', 'kind', 'title', 'url', 'actor', 'updated_at'];
+const linkColumns = ['type', 'from_id', 'to_id', 'scope', 'origin', 'confidence', 'evidence'];
+
+function collectSharedViews(attached: readonly ConsumerDeclaration[]): WithNode {
+  const entityFiles = attached.filter((consumer) => consumer.entityViews.length > 0);
+  const linkFiles = attached.filter((consumer) => consumer.links.length > 0);
+
+  const withNode = builder
+    .with('entity', (creator) => {
+      const [first, ...rest] = entityFiles.map((consumer) =>
+        creator.selectFrom(`${consumer.name}.entity`).select(entityColumns),
+      );
+
+      // no attached file has an entity view: the same columns, and no rows
+      if (first === undefined) {
+        return creator.selectNoFrom(entityColumns.map((column) => sql`null`.as(column))).limit(0);
+      }
+
+      return rest.reduce((union, next) => union.unionAll(next), first);
+    })
+    .with('link_effective', (creator) => {
+      const [first, ...rest] = linkFiles.map((consumer) =>
+        creator.selectFrom(`${consumer.name}.link`).select(linkColumns),
+      );
+
+      if (first === undefined) {
+        return creator.selectNoFrom(linkColumns.map((column) => sql`null`.as(column))).limit(0);
+      }
+
+      return rest.reduce((union, next) => union.unionAll(next), first);
+    })
+    .selectNoFrom(sql`1`.as('one'))
+    .toOperationNode().with;
+
+  invariant(withNode !== undefined, 'a query with two common table expressions has a with node');
+
+  return withNode;
+}

package/src/store-reader/create-store-reader.ts

@@ -0,0 +1,187 @@
+import { realpath } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import type { ConsumerDeclaration, ConsumersDB, StoreReader } from '@pepys/kit';
+import { createTursoDialect } from '@pepys/kysely-turso';
+import { connect } from '@tursodatabase/database';
+import type { Database } from '@tursodatabase/database';
+import { Kysely } from 'kysely';
+import { buildSharedViewsPlugin } from './build-shared-views-plugin.ts';
+import { pickAttachedFiles } from './pick-attached-files.ts';
+import type { AttachedFile, CurrentFile } from './pick-attached-files.ts';
+
+interface StoreReaderOptions {
+  storeDirectory: string;
+}
+
+// One open read-only handle on a consumer file. Turso 0.8.3 refuses to attach a file that the
+// host holds open with its multi-process WAL, unless this process holds a handle of its own.
+interface FileKeeper {
+  path: string;
+  database: Promise<Database>;
+  readers: number;
+  isRetired: boolean;
+}
+
+// The Turso adapter of the store reader port. Each call opens one connection on an empty
+// in-memory database, attaches the current file of each consumer read-only under the consumer's
+// name, and runs the work in one transaction, which holds one snapshot of each file.
+export function createStoreReader(options: StoreReaderOptions): StoreReader {
+  const keepers = new Map<string, FileKeeper>();
+  const retired = new Set<FileKeeper>();
+
+  const holdKeeper = (file: AttachedFile): FileKeeper => {
+    const held = keepers.get(file.consumer.name);
+
+    if (held?.path === file.path) {
+      held.readers += 1;
+
+      return held;
+    }
+
+    const keeper: FileKeeper = {
+      path: file.path,
+      database: connect(file.path, { readonly: true, experimental: ['multiprocess_wal'] }),
+      readers: 1,
+      isRetired: false,
+    };
+
+    keepers.set(file.consumer.name, keeper);
+
+    // the host swapped the version: the old file closes once its last call ends
+    if (held !== undefined) {
+      held.isRetired = true;
+
+      retired.add(held);
+    }
+
+    return keeper;
+  };
+
+  const releaseKeeper = async (keeper: FileKeeper): Promise<void> => {
+    keeper.readers -= 1;
+
+    if (keeper.isRetired && keeper.readers === 0 && retired.delete(keeper)) {
+      const database = await keeper.database;
+
+      await database.close();
+    }
+  };
+
+  return {
+    withConsumers: async (consumers, work, callOptions) => {
+      // every file resolves before anything opens, so a swap during the call changes nothing
+      const [required, optional] = await Promise.all([
+        readCurrentFiles(options.storeDirectory, consumers),
+        readCurrentFiles(options.storeDirectory, callOptions?.whenCurrent ?? []),
+      ]);
+
+      const plan = pickAttachedFiles(required, optional);
+
+      if (plan.kind === 'missing') {
+        return { ok: false, failure: { reason: 'no-current-version', consumers: plan.consumers } };
+      }
+
+      const held = plan.files.map((file) => holdKeeper(file));
+
+      try {
+        await Promise.all(held.map((keeper) => keeper.database));
+
+        const connection = await connect(':memory:', { experimental: ['attach'] });
+
+        const db = new Kysely<ConsumersDB<typeof consumers>>({
+          dialect: createTursoDialect({ database: () => Promise.resolve(connection) }),
+        });
+
+        try {
+          for (const file of plan.files) {
+            await connection.exec(formatAttachStatement(file));
+          }
+
+          const call = {
+            attached: Object.fromEntries(
+              plan.files.map((file): [string, { version: string }] => [
+                file.consumer.name,
+                { version: basename(dirname(file.path)) },
+              ]),
+            ),
+            skipped: plan.skipped,
+          };
+
+          const views = buildSharedViewsPlugin(plan.files.map((file) => file.consumer));
+
+          // A failed write ends Turso's transaction itself, and Kysely's own rollback would then
+          // fail and hide the first error, so the call opens and ends the transaction by hand.
+          await connection.exec('begin');
+
+          try {
+            const value = await work(db.withPlugin(views), call);
+
+            return { ok: true, value };
+          } finally {
+            if (connection.inTransaction) {
+              await connection.exec('rollback');
+            }
+          }
+        } finally {
+          await db.destroy();
+        }
+      } finally {
+        await Promise.all(held.map((keeper) => releaseKeeper(keeper)));
+      }
+    },
+    close: async () => {
+      const open = [...keepers.values(), ...retired];
+
+      keepers.clear();
+      retired.clear();
+
+      await Promise.all(
+        open.map(async (keeper) => {
+          const database = await keeper.database;
+
+          await database.close();
+        }),
+      );
+    },
+  };
+}
+
+function readCurrentFiles(
+  storeDirectory: string,
+  consumers: readonly ConsumerDeclaration[],
+): Promise<CurrentFile[]> {
+  return Promise.all(
+    consumers.map(async (consumer) => {
+      const path = await readRealPath(
+        join(storeDirectory, consumer.name, 'current', 'consumer.db'),
+      );
+
+      return { consumer, path };
+    }),
+  );
+}
+
+async function readRealPath(path: string): Promise<string | null> {
+  try {
+    const resolved = await realpath(path);
+
+    return resolved;
+  } catch (error: unknown) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+// A URI opens the file read-only. The path is percent-encoded, so a `?`, `#`, `%` or quote in a
+// folder name stays part of the path.
+function formatAttachStatement(file: AttachedFile): string {
+  const encoded = encodeURI(file.path)
+    .replaceAll('?', '%3F')
+    .replaceAll('#', '%23')
+    .replaceAll("'", '%27');
+
+  return `ATTACH 'file:${encoded}?mode=ro' AS "${file.consumer.name.replaceAll('"', '""')}"`;
+}

package/src/store-reader/pick-attached-files.ts

@@ -0,0 +1,45 @@
+import type { ConsumerDeclaration } from '@pepys/kit';
+
+export interface CurrentFile {
+  consumer: ConsumerDeclaration;
+
+  // the consumer file of the current version, every link resolved; null with no current version
+  path: string | null;
+}
+
+export interface AttachedFile {
+  consumer: ConsumerDeclaration;
+  path: string;
+}
+
+export type AttachPlan =
+  | { kind: 'missing'; consumers: readonly string[] }
+  | { kind: 'attach'; files: readonly AttachedFile[]; skipped: readonly string[] };
+
+// Which files one call attaches: every required consumer's, else the call fails naming each one
+// with no current version; then each optional consumer's that has one. A name attaches once.
+export function pickAttachedFiles(
+  required: readonly CurrentFile[],
+  optional: readonly CurrentFile[],
+): AttachPlan {
+  const missing = required.filter((file) => file.path === null).map((file) => file.consumer.name);
+
+  if (missing.length > 0) {
+    return { kind: 'missing', consumers: missing };
+  }
+
+  const files = new Map<string, AttachedFile>();
+  const skipped = new Set<string>();
+
+  for (const file of [...required, ...optional]) {
+    const name = file.consumer.name;
+
+    if (file.path === null) {
+      skipped.add(name);
+    } else if (!files.has(name)) {
+      files.set(name, { consumer: file.consumer, path: file.path });
+    }
+  }
+
+  return { kind: 'attach', files: [...files.values()], skipped: [...skipped] };
+}

package/src/store-reader/read-change-operations.ts

@@ -0,0 +1,44 @@
+import type { ConsumerDeclaration, Result, StoreReader, StoreReaderFailure } from '@pepys/kit';
+import { sql } from 'kysely';
+import { z } from 'zod';
+
+interface ChangeOperation {
+  key: string;
+  operation: string;
+}
+
+const changeLogRowSchema = z.object({ changes: z.string() });
+const changeLogRowsSchema = z.object({ rows: z.array(changeLogRowSchema) });
+
+const changeSchema = z.object({
+  key: z.string(),
+  headers: z.object({ operation: z.string() }),
+});
+
+// each change log row holds one batch as a JSON list of State Protocol messages
+const changesSchema = z.array(changeSchema);
+
+export async function readChangeOperations(
+  store: StoreReader,
+  consumer: ConsumerDeclaration,
+): Promise<Result<ChangeOperation[], StoreReaderFailure>> {
+  const table = sql.table(`${consumer.name}.change_log`);
+
+  const result = await store.withConsumers([consumer], (db) =>
+    sql`select changes from ${table} order by batch`.execute(db),
+  );
+
+  if (!result.ok) {
+    return result;
+  }
+
+  const operations = changeLogRowsSchema.parse(result.value).rows.flatMap((row) => {
+    const changes: unknown = JSON.parse(row.changes);
+
+    return changesSchema
+      .parse(changes)
+      .map((change) => ({ key: change.key, operation: change.headers.operation }));
+  });
+
+  return { ok: true, value: operations };
+}

package/src/store-reader/read-offsets.ts

@@ -0,0 +1,33 @@
+import type { ConsumerDeclaration, Result, StoreReader, StoreReaderFailure } from '@pepys/kit';
+import { sql } from 'kysely';
+import { z } from 'zod';
+
+interface Offset {
+  stream: string;
+  lastSeqNum: number;
+}
+
+const offsetRowSchema = z.object({ stream: z.string(), last_seq_num: z.number() });
+const offsetRowsSchema = z.object({ rows: z.array(offsetRowSchema) });
+
+// The last sequence number the host applied from each stream the consumer reads.
+export async function readOffsets(
+  store: StoreReader,
+  consumer: ConsumerDeclaration,
+): Promise<Result<Offset[], StoreReaderFailure>> {
+  const table = sql.table(`${consumer.name}.offsets`);
+
+  const result = await store.withConsumers([consumer], (db) =>
+    sql`select stream, last_seq_num from ${table} order by stream`.execute(db),
+  );
+
+  if (!result.ok) {
+    return result;
+  }
+
+  const offsets = offsetRowsSchema
+    .parse(result.value)
+    .rows.map((row) => ({ stream: row.stream, lastSeqNum: row.last_seq_num }));
+
+  return { ok: true, value: offsets };
+}

package/src/utils/compare-text.ts

@@ -0,0 +1,8 @@
+// Code unit order, as the default sort and SQLite's binary collation give, not the locale's.
+export function compareText(first: string, second: string): number {
+  if (first === second) {
+    return 0;
+  }
+
+  return first < second ? -1 : 1;
+}