@hearthlog/ledger 0.0.0-stage → 0.1.0

package/src/rpc.ts

@@ -0,0 +1,42 @@
+import {
+    LedgerError,
+    normalizeError,
+    type ErrorBody,
+} from "./errors";
+
+export interface RpcSuccess<T> {
+    ok: true;
+    status: number;
+    body: T;
+}
+
+export interface RpcFailure {
+    ok: false;
+    status: number;
+    body: ErrorBody;
+}
+
+export type RpcResult<T> = RpcSuccess<T> | RpcFailure;
+
+export function rpcSuccess<T>(body: T, status = 200): RpcSuccess<T> {
+    return { ok: true, status, body };
+}
+
+export async function rpcCall<T>(
+    operation: () => RpcSuccess<T> | Promise<RpcSuccess<T>>,
+): Promise<RpcResult<T>> {
+    try {
+        return await operation();
+    } catch (cause) {
+        if (cause instanceof LedgerError) {
+            return {
+                ok: false,
+                status: cause.status,
+                body: cause.body,
+            };
+        }
+        // Anything else is a server fault. Reporting it as invalid input would
+        // make clients permanently reject changes that a retry could accept.
+        throw normalizeError(cause);
+    }
+}

package/src/schema.ts

@@ -0,0 +1,236 @@
+const MIGRATIONS_TABLE = `
+CREATE TABLE IF NOT EXISTS _sql_schema_migrations (
+    id INTEGER PRIMARY KEY,
+    applied_at TEXT NOT NULL
+);
+`;
+
+const LEDGER_APP_SCHEMA = `
+CREATE TABLE IF NOT EXISTS app_metadata (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    app_id TEXT NOT NULL,
+    name TEXT NOT NULL,
+    principal_id TEXT NOT NULL,
+    principal_generation INTEGER NOT NULL,
+    created_at TEXT NOT NULL,
+    token_created_at TEXT NOT NULL,
+    revoked_at TEXT
+);
+CREATE TABLE IF NOT EXISTS logs (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    version INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL,
+    last_updated_at TEXT
+);
+CREATE TABLE IF NOT EXISTS log_events (
+    log_id TEXT NOT NULL,
+    version INTEGER NOT NULL,
+    event_id TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    entity_version INTEGER NOT NULL,
+    event_timestamp TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    PRIMARY KEY (log_id, version),
+    UNIQUE (log_id, event_id)
+);
+CREATE INDEX IF NOT EXISTS log_events_entity_idx
+    ON log_events(log_id, entity_id, entity_version);
+CREATE TABLE IF NOT EXISTS entity_claims (
+    log_id TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    current_version INTEGER NOT NULL,
+    version_created INTEGER NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (log_id, entity_id)
+);
+CREATE TABLE IF NOT EXISTS append_requests (
+    request_id TEXT NOT NULL,
+    log_id TEXT NOT NULL,
+    request_hash TEXT NOT NULL,
+    result TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    PRIMARY KEY (request_id, log_id)
+);
+CREATE TABLE IF NOT EXISTS socket_tickets (
+    nonce TEXT PRIMARY KEY,
+    log_id TEXT NOT NULL,
+    principal_id TEXT NOT NULL,
+    principal_generation INTEGER NOT NULL,
+    after_version INTEGER NOT NULL,
+    origin TEXT,
+    expires_at INTEGER NOT NULL,
+    consumed_at INTEGER
+);
+`;
+
+const DROP_SOCKET_TICKETS = `
+DROP TABLE IF EXISTS socket_tickets;
+DROP INDEX IF EXISTS log_events_entity_idx;
+`;
+
+const APP_REGISTRY_SCHEMA = `
+CREATE TABLE IF NOT EXISTS applications (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    created_at TEXT NOT NULL,
+    revoked_at TEXT,
+    active_principal_id TEXT NOT NULL,
+    principal_generation INTEGER NOT NULL,
+    active_token_created_at TEXT,
+    provisioning_state TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS applications_created_idx ON applications(created_at);
+`;
+
+interface Migration {
+    id: number;
+    sql: string;
+}
+
+const LEDGER_APP_MIGRATIONS: readonly Migration[] = [
+    { id: 1, sql: LEDGER_APP_SCHEMA },
+    { id: 2, sql: DROP_SOCKET_TICKETS },
+    { id: 3, sql: `
+        ALTER TABLE log_events ADD COLUMN action_id TEXT;
+        ALTER TABLE log_events ADD COLUMN action_index INTEGER;
+        ALTER TABLE log_events ADD COLUMN action_size INTEGER;
+        CREATE UNIQUE INDEX log_events_action_position
+            ON log_events(log_id, action_id, action_index) WHERE action_id IS NOT NULL;
+    ` },
+    { id: 4, sql: `
+        ALTER TABLE logs ADD COLUMN source_log_id TEXT;
+        ALTER TABLE logs ADD COLUMN source_version INTEGER;
+        ALTER TABLE logs ADD COLUMN status TEXT NOT NULL DEFAULT 'ready';
+        CREATE TABLE log_fork_requests (
+            request_id TEXT PRIMARY KEY,
+            source_log_id TEXT NOT NULL,
+            target_version INTEGER NOT NULL,
+            expected_source_head_version INTEGER NOT NULL,
+            name TEXT NOT NULL,
+            fork_log_id TEXT NOT NULL UNIQUE
+        );
+        CREATE INDEX logs_source_idx ON logs(source_log_id);
+    ` },
+    // Replay compatibility checks run on every read, append and socket
+    // delivery. This partial index holds only restore and removal markers.
+    { id: 5, sql: `
+        CREATE INDEX log_events_replay_markers
+            ON log_events(log_id, event_type)
+            WHERE event_type IN ('WORKSPACE_RESTORED', 'EVENTS_EXCISED');
+    ` },
+    { id: 6, sql: `
+        CREATE TABLE gallery_photo_references (
+            log_id TEXT NOT NULL,
+            photo_id TEXT NOT NULL,
+            file_version_id TEXT NOT NULL,
+            source_version INTEGER NOT NULL,
+            PRIMARY KEY (log_id, photo_id, file_version_id)
+        );
+        CREATE INDEX gallery_photo_references_file_idx
+            ON gallery_photo_references(photo_id, file_version_id);
+    ` },
+    // Clients close their stream while hidden, so live sockets alone rarely
+    // show who uses an application. The administrator console lists the most
+    // recent sessions; LedgerApp keeps this table bounded.
+    { id: 7, sql: `
+        CREATE TABLE socket_sessions (
+            connection_id TEXT PRIMARY KEY,
+            log_id TEXT NOT NULL,
+            principal_id TEXT NOT NULL,
+            principal_generation INTEGER NOT NULL,
+            connected_at TEXT NOT NULL,
+            disconnected_at TEXT,
+            close_code INTEGER,
+            cursor INTEGER NOT NULL,
+            last_sent_at TEXT,
+            user_agent TEXT,
+            ip TEXT,
+            country TEXT,
+            colo TEXT
+        );
+        CREATE INDEX socket_sessions_connected_idx
+            ON socket_sessions(connected_at);
+    ` },
+    // Hiding is a presentation choice for the log tree. A null value keeps
+    // older Workers and restored backups showing every log.
+    { id: 8, sql: `
+        ALTER TABLE logs ADD COLUMN hidden_at TEXT;
+    ` },
+    // An accepted append's events already live in log_events; its replay
+    // needs only their version range. Older rows keep the full response.
+    { id: 9, sql: `
+        ALTER TABLE append_requests ADD COLUMN first_version INTEGER;
+        ALTER TABLE append_requests ADD COLUMN last_version INTEGER;
+    ` },
+    // Who wrote an event: the identity the frontend Worker verified. Null for
+    // events accepted before this column existed or without a stamped identity;
+    // earlier code ignores the column during a rollback.
+    { id: 10, sql: `
+        ALTER TABLE log_events ADD COLUMN actor TEXT;
+    ` },
+    // What the application may append (see event-validation.ts). Null keeps
+    // the behavior applications had before policies, and earlier code ignores the column.
+    { id: 11, sql: `
+        ALTER TABLE app_metadata ADD COLUMN event_policy TEXT;
+    ` },
+    // 'importing' while an identity-preserving import fills the application;
+    // null otherwise, so earlier code never sees a value it does not know.
+    { id: 12, sql: `
+        ALTER TABLE app_metadata ADD COLUMN import_state TEXT;
+    ` },
+    // The write fence of a tenant move (see fence.ts). Null means writable, and
+    // earlier code ignores the columns.
+    { id: 13, sql: `
+        ALTER TABLE app_metadata ADD COLUMN fence_mode TEXT;
+        ALTER TABLE app_metadata ADD COLUMN fence_destination TEXT;
+    ` },
+];
+
+const APP_REGISTRY_MIGRATIONS: readonly Migration[] = [
+    { id: 1, sql: APP_REGISTRY_SCHEMA },
+];
+
+export function migrateLedgerApp(storage: DurableObjectStorage): void {
+    migrate(storage, LEDGER_APP_MIGRATIONS);
+}
+
+export function migrateAppRegistry(storage: DurableObjectStorage): void {
+    migrate(storage, APP_REGISTRY_MIGRATIONS);
+}
+
+function migrate(
+    storage: DurableObjectStorage,
+    migrations: readonly Migration[],
+): void {
+    storage.transactionSync(() => {
+        storage.sql.exec(MIGRATIONS_TABLE);
+        const applied = new Set(
+            storage.sql
+                .exec<{ id: number }>(
+                    "SELECT id FROM _sql_schema_migrations ORDER BY id",
+                )
+                .toArray()
+                .map(({ id }) => id),
+        );
+
+        let previousId = 0;
+        for (const migration of migrations) {
+            if (migration.id <= previousId) {
+                throw new Error("schema migrations must be strictly ordered");
+            }
+            previousId = migration.id;
+            if (applied.has(migration.id)) continue;
+
+            storage.sql.exec(migration.sql);
+            storage.sql.exec(
+                `INSERT INTO _sql_schema_migrations (id, applied_at)
+                 VALUES (?, ?)`,
+                migration.id,
+                new Date().toISOString(),
+            );
+        }
+    });
+}

package/src/schemas.ts

@@ -0,0 +1,429 @@
+import { t } from "elysia";
+import type {
+    AdminConnection as AdminConnectionContract,
+    AdminConnectionsResponse as AdminConnectionsResponseContract,
+    AdminRecentConnection as AdminRecentConnectionContract,
+} from "@hearthlog/contracts/ledger/admin";
+
+type JsonPrimitive = null | boolean | number | string;
+// A bounded depth keeps Cloudflare's RPC serializability inference finite.
+type JsonValue0 = JsonPrimitive;
+type JsonValue1 = JsonPrimitive | JsonValue0[] | Record<string, JsonValue0>;
+type JsonValue2 = JsonPrimitive | JsonValue1[] | Record<string, JsonValue1>;
+type JsonValue3 = JsonPrimitive | JsonValue2[] | Record<string, JsonValue2>;
+type JsonValue4 = JsonPrimitive | JsonValue3[] | Record<string, JsonValue3>;
+type JsonValue5 = JsonPrimitive | JsonValue4[] | Record<string, JsonValue4>;
+type JsonValue6 = JsonPrimitive | JsonValue5[] | Record<string, JsonValue5>;
+
+export type JsonValue = JsonValue6;
+export type JsonObject = Record<string, JsonValue>;
+
+const uuid = (label: string) =>
+    t.String({
+        format: "uuid",
+        error: `${label} must be a UUID`,
+    });
+
+const jsonObject = t.Unsafe<JsonObject>(t.Record(t.String(), t.Unknown()));
+
+const strictObject = { additionalProperties: false } as const;
+const queryInteger = {
+    minimum: 0,
+    maximum: Number.MAX_SAFE_INTEGER,
+    multipleOf: 1,
+} as const;
+const queryLimit = {
+    ...queryInteger,
+    minimum: 1,
+} as const;
+
+/** What an application may append; see `EventPolicy` in event-validation.ts. */
+export const eventPolicyBody = t.Object(
+    {
+        contracts: t.Union([t.Array(t.String({ pattern: "^(core|[a-z0-9]+(\\.[a-z0-9-]+)+)$" }), { maxItems: 64 }), t.Null()]),
+        dynamicEvents: t.Boolean(),
+        validation: t.Union([t.Literal("report"), t.Literal("enforce"), t.Null()]),
+    },
+    strictObject,
+);
+
+export const importBeginBody = t.Object(
+    {
+        id: uuid("application id"),
+        name: t.String(),
+        createdAt: t.String(),
+        policy: t.Optional(t.Union([eventPolicyBody, t.Null()])),
+    },
+    strictObject,
+);
+
+/** Records are validated strictly by `parseTransferRecords`, not by the route. */
+export const importRecordsBody = t.Object({ records: t.Array(t.Any(), { minItems: 1, maxItems: 2000 }) }, strictObject);
+
+export const importFinishBody = t.Object(
+    { logs: t.Array(t.Object({ id: uuid("log id"), headVersion: t.Integer({ minimum: 0 }) }, strictObject), { maxItems: 10000 }) },
+    strictObject,
+);
+
+export const fenceBody = t.Object(
+    {
+        mode: t.Union([t.Literal("off"), t.Literal("tenant_migrating"), t.Literal("moved")]),
+        destination: t.Optional(t.Nullable(t.String())),
+    },
+    strictObject,
+);
+
+export const createApplicationBody = t.Object(
+    {
+        name: t.String(),
+        /** Omitted: the application starts with the policy new applications get. */
+        policy: t.Optional(eventPolicyBody),
+    },
+    strictObject,
+);
+
+export const applicationParams = t.Object(
+    {
+        appId: uuid("application id"),
+    },
+    strictObject,
+);
+
+export const createLogBody = t.Object(
+    {
+        name: t.Optional(t.Nullable(t.String())),
+    },
+    strictObject,
+);
+
+export const logVisibilityBody = t.Object(
+    {
+        hidden: t.Boolean(),
+    },
+    strictObject,
+);
+
+export const forkLogBody = t.Object(
+    {
+        name: t.String({ minLength: 1 }),
+        targetVersion: t.Integer(queryInteger),
+        expectedSourceHeadVersion: t.Integer(queryInteger),
+        requestId: uuid('fork request id'),
+    },
+    strictObject,
+);
+
+export const logLineageBody = t.Object(
+    {
+        sourceLogId: uuid('source log id'),
+        sourceVersion: t.Integer(queryInteger),
+    },
+    strictObject,
+);
+
+export const logParams = t.Object(
+    {
+        logId: uuid("logId"),
+    },
+    strictObject,
+);
+
+export const galleryPhotoReferenceParams = t.Object(
+    {
+        logId: uuid('log id'),
+        photoId: uuid('gallery photo id'),
+        fileVersionId: uuid('gallery file version id'),
+    },
+    strictObject,
+);
+
+export const eventsQuery = t.Object(
+    {
+        afterVersion: t.Optional(t.Numeric(queryInteger)),
+        limit: t.Optional(t.Numeric(queryLimit)),
+    },
+    strictObject,
+);
+
+export const socketQuery = t.Object(
+    {
+        replayVersion: t.Optional(t.Numeric(queryInteger)),
+        afterVersion: t.Optional(t.Numeric(queryInteger)),
+    },
+    strictObject,
+);
+
+export const adminEventParams = t.Object(
+    {
+        appId: uuid("application id"),
+        logId: uuid("log id"),
+    },
+    strictObject,
+);
+
+export const adminEventsQuery = t.Object(
+    {
+        beforeVersion: t.Optional(t.Numeric({ ...queryInteger, minimum: 1 })),
+        limit: t.Optional(t.Numeric({ ...queryLimit, maximum: 100 })),
+        search: t.Optional(t.String({ maxLength: 200 })),
+    },
+    strictObject,
+);
+
+export const adminMetrics = t.Object(
+    {
+        sampledAt: t.String(),
+        logCount: t.Integer({ minimum: 0 }),
+        eventCount: t.Integer({ minimum: 0 }),
+        entityCount: t.Integer({ minimum: 0 }),
+        databaseBytes: t.Integer({ minimum: 0 }),
+        connectedClients: t.Integer({ minimum: 0 }),
+        lastUpdatedAt: t.Nullable(t.String()),
+    },
+    strictObject,
+);
+
+export const adminConnectionsQuery = t.Object(
+    { afterId: t.Optional(uuid("connection id")) },
+    strictObject,
+);
+const adminConnectionClient = t.Object(
+    {
+        userAgent: t.Nullable(t.String()),
+        ip: t.Nullable(t.String()),
+        country: t.Nullable(t.String()),
+        colo: t.Nullable(t.String()),
+    },
+    strictObject,
+);
+export const adminConnection = t.Object(
+    {
+        id: uuid("connection id"),
+        logId: uuid("log id"),
+        logName: t.Nullable(t.String()),
+        principalId: uuid("principal id"),
+        generation: t.Integer({ minimum: 1 }),
+        state: t.Union([
+            t.Literal("connecting"),
+            t.Literal("open"),
+            t.Literal("closing"),
+            t.Literal("closed"),
+        ]),
+        cursor: t.Integer({ minimum: 0 }),
+        headVersion: t.Nullable(t.Integer({ minimum: 0 })),
+        connectedAt: t.Nullable(t.String()),
+        lastSentAt: t.Nullable(t.String()),
+        client: adminConnectionClient,
+    },
+    strictObject,
+);
+export const adminRecentConnection = t.Object(
+    {
+        id: uuid("connection id"),
+        logId: uuid("log id"),
+        logName: t.Nullable(t.String()),
+        principalId: uuid("principal id"),
+        generation: t.Integer({ minimum: 1 }),
+        cursor: t.Integer({ minimum: 0 }),
+        connectedAt: t.String(),
+        disconnectedAt: t.Nullable(t.String()),
+        closeCode: t.Nullable(t.Integer({ minimum: 0 })),
+        lastSentAt: t.Nullable(t.String()),
+        client: adminConnectionClient,
+    },
+    strictObject,
+);
+export const adminConnectionsResponse = t.Object(
+    {
+        sampledAt: t.String(),
+        total: t.Integer({ minimum: 0 }),
+        unavailable: t.Integer({ minimum: 0 }),
+        connections: t.Array(adminConnection),
+        nextAfterId: t.Nullable(uuid("connection id")),
+        recent: t.Array(adminRecentConnection),
+    },
+    strictObject,
+);
+
+export const incomingEvent = t.Object(
+    {
+        id: t.Optional(t.Nullable(uuid("event id"))),
+        type: t.String(),
+        timestamp: t.Optional(t.Nullable(t.Integer({ minimum: 0 }))),
+        entityId: t.String(),
+        baseEntityVersion: t.Optional(t.Nullable(t.Integer({ minimum: 0 }))),
+        payload: jsonObject,
+    },
+    strictObject,
+);
+
+export const appendEventsBody = t.Object(
+    {
+        requestId: uuid("requestId"),
+        actionId: t.Optional(uuid("actionId")),
+        expectedLogVersion: t.Optional(t.Integer({ minimum: 0 })),
+        events: t.Array(incomingEvent, { maxItems: 512 }),
+    },
+    strictObject,
+);
+
+export const storedEvent = t.Object(
+    {
+        action: t.Optional(t.Object({
+            id: uuid("action id"),
+            index: t.Integer({ minimum: 0 }),
+            size: t.Integer({ minimum: 1 }),
+        }, strictObject)),
+        version: t.Integer({ minimum: 1 }),
+        id: uuid("stored event id"),
+        type: t.String(),
+        entityId: t.String(),
+        entityVersion: t.Integer({ minimum: 1 }),
+        timestamp: t.Integer({ minimum: 0 }),
+        payload: jsonObject,
+        /** Identity the gateway verified for the request that wrote the event. */
+        actor: t.Optional(t.String({ minLength: 1, maxLength: 320 })),
+    },
+    strictObject,
+);
+
+export const logSummary = t.Object(
+    {
+        id: uuid("stored log id"),
+        name: t.String(),
+        headVersion: t.Integer({ minimum: 0 }),
+        createdAt: t.String(),
+        lastUpdatedAt: t.Nullable(t.String()),
+        sourceLogId: t.Nullable(uuid('source log id')),
+        sourceLogName: t.Nullable(t.String()),
+        sourceVersion: t.Nullable(t.Integer({ minimum: 0 })),
+        sourceTimestamp: t.Nullable(t.String()),
+        status: t.Union([t.Literal('ready'), t.Literal('preparing')]),
+        hiddenAt: t.Nullable(t.String()),
+    },
+    strictObject,
+);
+
+export const applicationSummary = t.Object(
+    {
+        id: uuid("stored application id"),
+        name: t.String(),
+        createdAt: t.String(),
+        revokedAt: t.Nullable(t.String()),
+        activeTokenCreatedAt: t.Nullable(t.String()),
+    },
+    strictObject,
+);
+
+export const apiModels = {
+    AdminConnectionsResponse: adminConnectionsResponse,
+    AdminMetricsResponse: adminMetrics,
+    AdminEventsResponse: t.Object(
+        {
+            events: t.Array(storedEvent),
+            headVersion: t.Integer({ minimum: 0 }),
+            nextBeforeVersion: t.Nullable(t.Integer({ minimum: 1 })),
+        },
+        strictObject,
+    ),
+    ApplicationResponse: applicationSummary,
+    ApplicationListResponse: t.Object(
+        {
+            apps: t.Array(applicationSummary),
+        },
+        strictObject,
+    ),
+    ApplicationTokenResponse: t.Object(
+        {
+            app: applicationSummary,
+            token: t.String(),
+        },
+        strictObject,
+    ),
+    AppendEventsResponse: t.Object(
+        {
+            newVersion: t.Integer({ minimum: 0 }),
+            events: t.Array(storedEvent),
+        },
+        strictObject,
+    ),
+    CreateLogResponse: t.Object(
+        {
+            id: uuid("stored log id"),
+            name: t.String(),
+            headVersion: t.Literal(0),
+            createdAt: t.String(),
+        },
+        strictObject,
+    ),
+    EmptyResponse: t.Null(),
+    EventBatchResponse: t.Object(
+        {
+            events: t.Array(storedEvent),
+        },
+        strictObject,
+    ),
+    HealthResponse: t.Null(),
+    LogListResponse: t.Object(
+        {
+            logs: t.Array(logSummary),
+            lineage: t.Object({
+                rootIds: t.Array(uuid('root log id')),
+                childIdsByLogId: t.Record(t.String(), t.Array(uuid('child log id'))),
+            }, strictObject),
+        },
+        strictObject,
+    ),
+    LogResponse: logSummary,
+    ForkLogResponse: logSummary,
+    GalleryPhotoReferenceResponse: t.Object({ present: t.Boolean() }, strictObject),
+    SessionResponse: t.Object(
+        {
+            appId: uuid("appId"),
+            principalId: uuid("principalId"),
+            capabilities: t.Optional(t.Array(t.String())),
+            fence: t.Optional(t.Object({
+                mode: t.Union([t.Literal("tenant_migrating"), t.Literal("moved")]),
+                destination: t.Nullable(t.String()),
+            }, strictObject)),
+        },
+        strictObject,
+    ),
+};
+
+export type CreateApplicationRequest = typeof createApplicationBody.static;
+export type EventPolicyRequest = typeof eventPolicyBody.static;
+export type CreateLogRequest = typeof createLogBody.static;
+export type ForkLogRequest = typeof forkLogBody.static;
+export type LogVisibilityRequest = typeof logVisibilityBody.static;
+export type EventsQuery = typeof eventsQuery.static;
+export type IncomingEvent = typeof incomingEvent.static;
+export type AppendEventsRequest = typeof appendEventsBody.static;
+export type StoredEvent = typeof storedEvent.static;
+export type ApplicationSummary = typeof applicationSummary.static;
+export type ApplicationListResponse =
+    typeof apiModels.ApplicationListResponse.static;
+export type ApplicationTokenResponse =
+    typeof apiModels.ApplicationTokenResponse.static;
+export type AppendEventsResponse = typeof apiModels.AppendEventsResponse.static;
+export type CreateLogResponse = typeof apiModels.CreateLogResponse.static;
+export type EventBatchResponse = typeof apiModels.EventBatchResponse.static;
+export type LogSummary = typeof logSummary.static;
+export type LogListResponse = typeof apiModels.LogListResponse.static;
+export type SessionResponse = typeof apiModels.SessionResponse.static;
+export type AdminMetrics = typeof adminMetrics.static;
+export type AdminEventsQuery = typeof adminEventsQuery.static;
+export type AdminEventsResponse = typeof apiModels.AdminEventsResponse.static;
+export type AdminConnection = typeof adminConnection.static;
+export type AdminRecentConnection = typeof adminRecentConnection.static;
+export type AdminConnectionsQuery = typeof adminConnectionsQuery.static;
+export type AdminConnectionsResponse = typeof adminConnectionsResponse.static;
+
+// The browser's view of these responses is `@hearthlog/contracts/ledger/admin`; this fails to
+// compile when the schemas and those types stop describing the same shape.
+type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : never) : never;
+export const adminContractsMatch: [
+    Same<AdminConnection, AdminConnectionContract>,
+    Same<AdminRecentConnection, AdminRecentConnectionContract>,
+    Same<AdminConnectionsResponse, AdminConnectionsResponseContract>,
+] = [true, true, true];