---
summary: "MirrorService — persistent, self-refreshing local mirror of a bulk upstream dataset (embedded SQLite + FTS5) via new @cyanheads/mcp-ts-core/mirror subpath"
breaking: false
security: false
agent-notes: |
  New subpath `/mirror` exports `defineMirror`, `sqliteMirrorStore`, `buildSchemaSql`, `openSqliteHandle`, `Mirror`, `MirrorStore`, `MirrorDefinition`, `SyncContext`, `SyncPage`, and related types. Node/Bun only — unavailable on Workers. Optional peer dep `better-sqlite3` is required on Node; Bun uses the built-in `bun:sqlite`. New skill `api-mirror` covers the full API surface.
---

# 0.9.17 — 2026-05-30

## Added

- **`defineMirror()`** — assembles a `MirrorStore` + a server `sync` generator into an owned `Mirror` instance with `runSync({ mode: 'init' | 'refresh' })`, `query()`, `status()`, `ready()`, `getByIds()`, and a raw-handle escape hatch (`handle()`). ([#164](https://github.com/cyanheads/mcp-ts-core/issues/164))
- **`sqliteMirrorStore()`** — embedded-SQLite backend with cross-runtime support (`bun:sqlite` built-in on Bun; `better-sqlite3` optional peer on Node); declarative schema (columns + opt-in FTS5 external-content index with sync triggers + configurable tokenizer + secondary indexes); generic flat `query()` (FTS `MATCH` + equality/range filters + column-or-bm25 sort + pagination); `schema_version` migration runner.
- **Sync state machine** — volatile `cursor` (intra-run resume token, cleared on completion) kept distinct from the durable `checkpoint` (incremental high-water mark, advances monotonically on success); per-page persistence gives resume-on-interrupt; readiness keys off the durable completion marker so the mirror stays queryable during a refresh.
- **`MirrorStore` interface** — pluggable backend contract, leaving a clean path to non-SQLite backends without re-architecting.
- **`@cyanheads/mcp-ts-core/mirror` subpath** — all mirror exports live here; Tier 3 (optional peer dep), Node/Bun only.
- **`better-sqlite3` optional peer dependency** — required on Node; gated like the existing Supabase/DuckDB providers. Bun uses the built-in `bun:sqlite`.
- **`api-mirror` skill** — documents the full `/mirror` API surface for downstream agent consumption.

## Changed

- **`@cloudflare/workers-types`** `4.20260530.1 → 4.20260531.1` (dev) — trivial patch refresh.
