@cyanheads/mcp-ts-core 0.9.16 → 0.9.18

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.9.16
+**Version:** 0.9.18
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
 **Zod:** ^4.4.3
@@ -56,6 +56,7 @@ Both paths share the same public API. Init copies starter `package.json`, config
 | `/storage` | `StorageService` | Storage abstraction |
 | `/storage/types` | `IStorageProvider` | Provider interface |
 | `/canvas` | `DataCanvas`, `CanvasInstance`, `CanvasRegistry`, `IDataCanvasProvider`, `DuckdbProvider`, `spillover`, `inferSchemaFromRows`, `assertReadOnlyQuery`, `quoteIdentifier`, ... | DataCanvas primitive (Tier 3, optional peer dep `@duckdb/node-api`); SQL/analytical workspace + source-agnostic spillover helper |
+| `/mirror` | `defineMirror`, `sqliteMirrorStore`, `buildSchemaSql`, `openSqliteHandle`, `Mirror`, `MirrorStore`, `MirrorDefinition`, `SyncContext`, `SyncPage`, ... | MirrorService primitive (Tier 3, optional peer dep `better-sqlite3` on Node; `bun:sqlite` built-in on Bun); persistent self-refreshing local mirror of a bulk upstream dataset (embedded SQLite + FTS5). Node/Bun only |
 | `/utils` | formatting, encoding, network, pagination, logging, runtime, telemetry, token counting, parsers†, sanitization†, scheduling† | All utilities (†optional peer deps) |
 | `/services` | `OpenRouterProvider`, `SpeechService`, `createSpeechProvider`, `ElevenLabsProvider`, `WhisperProvider`, `GraphService`, provider interfaces and types | LLM, Speech (TTS/STT), Graph services |
 | `/linter` | `validateDefinitions`, `LintReport`, `LintDiagnostic`, `LintInput`, `LintSeverity` | Definition validation |
@@ -466,7 +467,7 @@ Detailed method signatures, options, and examples live in skill files. Read the
 
 Each `skills/<name>/SKILL.md` carries `metadata.version` in frontmatter. The `maintenance` skill's Phase A uses this to sync consumer copies — replaces the **entire skill directory** as one unit. Without a version bump, Phase A skips the skill (content-hash backstop catches drift, but noisier).
 
-**Policy:** Bump `metadata.version` when changing any file under `skills/<name>/` — SKILL.md is the single version knob for the directory. Typo/whitespace fixes exempt. One bump per release cycle suffices.
+**Policy:** Bump `metadata.version` when changing any file under `skills/<name>/` — SKILL.md is the single version knob for the directory. Typo/whitespace fixes exempt. One bump per release cycle suffices. Enforced by `bun run devcheck` (`scripts/check-skill-versions.ts`): a SKILL.md body change vs `HEAD` without a `metadata.version` bump surfaces as a warning; whitespace-only edits are ignored, and `devcheck.config.json` `skillVersions.ignore` opts out the typo-fix carve-out.
 
 Skills live in `skills/<name>/SKILL.md`. Read the relevant skill before starting a task it covers. The full list is discoverable via the agent's skill registry at session start.
 

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.9.16
+**Version:** 0.9.18
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
 **Zod:** ^4.4.3
@@ -56,6 +56,7 @@ Both paths share the same public API. Init copies starter `package.json`, config
 | `/storage` | `StorageService` | Storage abstraction |
 | `/storage/types` | `IStorageProvider` | Provider interface |
 | `/canvas` | `DataCanvas`, `CanvasInstance`, `CanvasRegistry`, `IDataCanvasProvider`, `DuckdbProvider`, `spillover`, `inferSchemaFromRows`, `assertReadOnlyQuery`, `quoteIdentifier`, ... | DataCanvas primitive (Tier 3, optional peer dep `@duckdb/node-api`); SQL/analytical workspace + source-agnostic spillover helper |
+| `/mirror` | `defineMirror`, `sqliteMirrorStore`, `buildSchemaSql`, `openSqliteHandle`, `Mirror`, `MirrorStore`, `MirrorDefinition`, `SyncContext`, `SyncPage`, ... | MirrorService primitive (Tier 3, optional peer dep `better-sqlite3` on Node; `bun:sqlite` built-in on Bun); persistent self-refreshing local mirror of a bulk upstream dataset (embedded SQLite + FTS5). Node/Bun only |
 | `/utils` | formatting, encoding, network, pagination, logging, runtime, telemetry, token counting, parsers†, sanitization†, scheduling† | All utilities (†optional peer deps) |
 | `/services` | `OpenRouterProvider`, `SpeechService`, `createSpeechProvider`, `ElevenLabsProvider`, `WhisperProvider`, `GraphService`, provider interfaces and types | LLM, Speech (TTS/STT), Graph services |
 | `/linter` | `validateDefinitions`, `LintReport`, `LintDiagnostic`, `LintInput`, `LintSeverity` | Definition validation |
@@ -466,7 +467,7 @@ Detailed method signatures, options, and examples live in skill files. Read the
 
 Each `skills/<name>/SKILL.md` carries `metadata.version` in frontmatter. The `maintenance` skill's Phase A uses this to sync consumer copies — replaces the **entire skill directory** as one unit. Without a version bump, Phase A skips the skill (content-hash backstop catches drift, but noisier).
 
-**Policy:** Bump `metadata.version` when changing any file under `skills/<name>/` — SKILL.md is the single version knob for the directory. Typo/whitespace fixes exempt. One bump per release cycle suffices.
+**Policy:** Bump `metadata.version` when changing any file under `skills/<name>/` — SKILL.md is the single version knob for the directory. Typo/whitespace fixes exempt. One bump per release cycle suffices. Enforced by `bun run devcheck` (`scripts/check-skill-versions.ts`): a SKILL.md body change vs `HEAD` without a `metadata.version` bump surfaces as a warning; whitespace-only edits are ignored, and `devcheck.config.json` `skillVersions.ignore` opts out the typo-fix carve-out.
 
 Skills live in `skills/<name>/SKILL.md`. Read the relevant skill before starting a task it covers. The full list is discoverable via the agent's skill registry at session start.
 

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.9.16-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx)
+[![Version](https://img.shields.io/badge/Version-0.9.18-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx)
 
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)
 

package/changelog/0.9.x/0.9.17.md

@@ -0,0 +1,23 @@
+---
+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.

package/changelog/0.9.x/0.9.18.md

@@ -0,0 +1,12 @@
+---
+summary: "Two devcheck enforcement gates: a metadata.version bump check for SKILL.md body changes (#99), and an AST check for open-indexed-named interfaces (#123)."
+breaking: false
+security: false
+---
+
+# 0.9.18 — 2026-05-31
+
+## Added
+
+- **Skill-version enforcement gate** in devcheck — a `skills/<name>/SKILL.md` body change without a `metadata.version` bump surfaces as a warning; whitespace-only edits are ignored; `devcheck.config.json` `skillVersions.ignore` opts out the typo carve-out. ([#99](https://github.com/cyanheads/mcp-ts-core/issues/99))
+- **Open-indexed-named interface gate** in devcheck — an AST check fails on interfaces mixing named members with an open `[key: string]: unknown|any` index signature unless annotated `// allow open-indexed-named: <rationale>`; six framework extensibility bags annotated as the baseline. ([#123](https://github.com/cyanheads/mcp-ts-core/issues/123))

package/dist/mcp-server/tools/utils/toolDefinition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/utils/toolDefinition.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAyB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA+NzE,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,UAAU,IAAI,CAMlB,IAAY,EACZ,OAAwE;IAExE,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAyB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAgOzE,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,UAAU,IAAI,CAMlB,IAAY,EACZ,OAAwE;IAExE,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/services/mirror/core/defineMirror.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview `defineMirror` — assembles a {@link MirrorStore}, a server's
+ * `sync` generator, and the runner into a single owned mirror instance. The
+ * returned object is what a server holds (one per mirror) and exposes to its
+ * tools: `runSync`, `query`, `status`/`ready`, `getByIds`, and the raw handle.
+ * @module services/mirror/core/defineMirror
+ */
+import type { MirrorDefinition, MirrorRow, MirrorStatus, MirrorStore, QueryOptions, QueryResult, RunSyncOptions, SqliteHandle, SyncResult } from '../types.js';
+/** Options for a single {@link Mirror.runSync} call. */
+export type MirrorRunOptions = RunSyncOptions & {
+    /** Cancels the run; the runner persists state before stopping. Defaults to a never-aborting signal. */
+    signal?: AbortSignal;
+};
+/** An owned mirror instance — the return value of {@link defineMirror}. */
+export interface Mirror {
+    /** Close the underlying store. */
+    close(): Promise<void>;
+    /** Fetch records by primary-key list, preserving input order. */
+    getByIds(ids: string[]): Promise<MirrorRow[]>;
+    /** Stable name from the definition. */
+    readonly name: string;
+    /** Generic flat query over the mirror. */
+    query(options: QueryOptions): Promise<QueryResult>;
+    /** The opened runtime-agnostic handle for server-specific access paths. */
+    raw(): Promise<SqliteHandle>;
+    /** `true` once a full sync has ever completed (queryable even mid-refresh). */
+    ready(): Promise<boolean>;
+    /** Run a full (`init`) or incremental (`refresh`) sync. */
+    runSync(options: MirrorRunOptions): Promise<SyncResult>;
+    /** Current sync status, including the durable `ready` marker. */
+    status(): Promise<MirrorStatus>;
+    /** The backing store (escape hatch for advanced use). */
+    readonly store: MirrorStore;
+}
+/**
+ * Assemble a mirror from a store, a `sync` generator, and a name. Nothing opens
+ * until the first call; construction is cheap and side-effect-free.
+ *
+ * @example
+ * ```ts
+ * const papers = defineMirror({
+ *   name: 'arxiv-papers',
+ *   store: sqliteMirrorStore({
+ *     path: config.mirrorPath,
+ *     primaryKey: 'id',
+ *     columns: { id: 'TEXT', title: 'TEXT', abstract: 'TEXT', updated: 'TEXT' },
+ *     fts: ['title', 'abstract'],
+ *     indexes: [{ columns: ['updated'] }],
+ *   }),
+ *   async *sync({ mode, cursor, checkpoint, signal }) {
+ *     for await (const page of harvest({ cursor, since: checkpoint, signal })) {
+ *       yield { records: page.rows, cursor: page.token, checkpoint: page.maxStamp };
+ *     }
+ *   },
+ * });
+ *
+ * await papers.runSync({ mode: 'init', signal: AbortSignal.timeout(3_600_000) });
+ * const { rows, total } = await papers.query({ match: 'transformers', limit: 10, offset: 0 });
+ * ```
+ */
+export declare function defineMirror(definition: MirrorDefinition): Mirror;
+//# sourceMappingURL=defineMirror.d.ts.map

package/dist/services/mirror/core/defineMirror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineMirror.d.ts","sourceRoot":"","sources":["../../../../src/services/mirror/core/defineMirror.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,gBAAgB,EAEhB,SAAS,EACT,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACX,cAAc,EACd,YAAY,EACZ,UAAU,EACX,MAAM,aAAa,CAAC;AAGrB,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG;IAC9C,uGAAuG;IACvG,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,2EAA2E;AAC3E,MAAM,WAAW,MAAM;IACrB,kCAAkC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC9C,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACnD,2EAA2E;IAC3E,GAAG,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7B,+EAA+E;IAC/E,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1B,2DAA2D;IAC3D,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACxD,iEAAiE;IACjE,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAChC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,CAkDjE"}

package/dist/services/mirror/core/defineMirror.js

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview `defineMirror` — assembles a {@link MirrorStore}, a server's
+ * `sync` generator, and the runner into a single owned mirror instance. The
+ * returned object is what a server holds (one per mirror) and exposes to its
+ * tools: `runSync`, `query`, `status`/`ready`, `getByIds`, and the raw handle.
+ * @module services/mirror/core/defineMirror
+ */
+import { logger } from '../../../utils/internal/logger.js';
+import { requestContextService } from '../../../utils/internal/requestContext.js';
+import { runSync as runSyncCore } from './runner.js';
+/**
+ * Forwards sync logs to the framework logger when the definition supplies none.
+ * Sync runs outside the request pipeline, so each call wraps `meta` in a fresh
+ * `RequestContext` (the shape the framework logger expects); `error` takes a
+ * `RequestContext` in the no-Error overload.
+ */
+const defaultLogger = {
+    debug: (message, meta) => logger.debug(message, ctxFrom(meta)),
+    info: (message, meta) => logger.info(message, ctxFrom(meta)),
+    notice: (message, meta) => logger.notice(message, ctxFrom(meta)),
+    warning: (message, meta) => logger.warning(message, ctxFrom(meta)),
+    error: (message, meta) => logger.error(message, ctxFrom(meta)),
+};
+function ctxFrom(meta) {
+    return requestContextService.createRequestContext({
+        operation: 'mirror.sync',
+        ...(meta ?? {}),
+    });
+}
+/**
+ * Assemble a mirror from a store, a `sync` generator, and a name. Nothing opens
+ * until the first call; construction is cheap and side-effect-free.
+ *
+ * @example
+ * ```ts
+ * const papers = defineMirror({
+ *   name: 'arxiv-papers',
+ *   store: sqliteMirrorStore({
+ *     path: config.mirrorPath,
+ *     primaryKey: 'id',
+ *     columns: { id: 'TEXT', title: 'TEXT', abstract: 'TEXT', updated: 'TEXT' },
+ *     fts: ['title', 'abstract'],
+ *     indexes: [{ columns: ['updated'] }],
+ *   }),
+ *   async *sync({ mode, cursor, checkpoint, signal }) {
+ *     for await (const page of harvest({ cursor, since: checkpoint, signal })) {
+ *       yield { records: page.rows, cursor: page.token, checkpoint: page.maxStamp };
+ *     }
+ *   },
+ * });
+ *
+ * await papers.runSync({ mode: 'init', signal: AbortSignal.timeout(3_600_000) });
+ * const { rows, total } = await papers.query({ match: 'transformers', limit: 10, offset: 0 });
+ * ```
+ */
+export function defineMirror(definition) {
+    const { name, store, sync } = definition;
+    const log = definition.logger ?? defaultLogger;
+    return {
+        name,
+        store,
+        runSync(options) {
+            const signal = options.signal ?? new AbortController().signal;
+            const runOptions = {
+                mode: options.mode,
+                ...(options.onProgress && { onProgress: options.onProgress }),
+            };
+            return runSyncCore(store, sync, { log, signal }, runOptions);
+        },
+        query(options) {
+            return store.query(options);
+        },
+        getByIds(ids) {
+            return store.getByIds(ids);
+        },
+        async status() {
+            const state = await store.readState();
+            return {
+                status: state.status,
+                ready: state.completedAt != null,
+                ...(state.checkpoint !== undefined && { checkpoint: state.checkpoint }),
+                ...(state.total !== undefined && { total: state.total }),
+                ...(state.startedAt !== undefined && { startedAt: state.startedAt }),
+                ...(state.completedAt !== undefined && { completedAt: state.completedAt }),
+                ...(state.error !== undefined && { error: state.error }),
+            };
+        },
+        async ready() {
+            return (await store.readState()).completedAt != null;
+        },
+        raw() {
+            return store.raw();
+        },
+        close() {
+            return store.close();
+        },
+    };
+}
+//# sourceMappingURL=defineMirror.js.map

package/dist/services/mirror/core/defineMirror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineMirror.js","sourceRoot":"","sources":["../../../../src/services/mirror/core/defineMirror.ts"],"names":[],"mappings":"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"}

package/dist/services/mirror/core/runner.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Sync runner — drives a server's `sync` generator against a
+ * {@link MirrorStore} for full init and incremental refresh. Owns the
+ * cursor/checkpoint state machine, per-page persistence, resume-on-interrupt,
+ * and terminal status transitions.
+ * @module services/mirror/core/runner
+ */
+import type { MirrorLogger, MirrorStore, RunSyncOptions, SyncGenerator, SyncResult } from '../types.js';
+/** Minimal context the runner consumes — a duck-typed logger plus cancellation. */
+export interface RunnerContext {
+    log: MirrorLogger;
+    signal: AbortSignal;
+}
+/**
+ * Run one sync cycle.
+ *
+ * - `init` performs a full harvest. With no prior state it starts from scratch;
+ *   if a previous init left an incomplete dataset (status `in_progress` from a
+ *   crash, or `error` from a caught failure) and a `cursor` was persisted, it
+ *   resumes from that cursor, with `checkpoint` available for recovery.
+ * - `refresh` performs an incremental harvest from the durable `checkpoint`.
+ *
+ * State is persisted after every page, so an interrupt at any point resumes from
+ * the last yielded page. On success the volatile `cursor` is cleared and
+ * `completedAt`/`total` advance; on failure they are preserved (a failed
+ * refresh on top of a complete mirror stays "ready").
+ */
+export declare function runSync(store: MirrorStore, sync: SyncGenerator, ctx: RunnerContext, options: RunSyncOptions): Promise<SyncResult>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/services/mirror/core/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../../src/services/mirror/core/runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,cAAc,EACd,aAAa,EACb,UAAU,EAEX,MAAM,aAAa,CAAC;AAErB,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,YAAY,CAAC;IAClB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,OAAO,CAC3B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,aAAa,EACnB,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,UAAU,CAAC,CAiFrB"}

package/dist/services/mirror/core/runner.js

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview Sync runner — drives a server's `sync` generator against a
+ * {@link MirrorStore} for full init and incremental refresh. Owns the
+ * cursor/checkpoint state machine, per-page persistence, resume-on-interrupt,
+ * and terminal status transitions.
+ * @module services/mirror/core/runner
+ */
+/**
+ * Run one sync cycle.
+ *
+ * - `init` performs a full harvest. With no prior state it starts from scratch;
+ *   if a previous init left an incomplete dataset (status `in_progress` from a
+ *   crash, or `error` from a caught failure) and a `cursor` was persisted, it
+ *   resumes from that cursor, with `checkpoint` available for recovery.
+ * - `refresh` performs an incremental harvest from the durable `checkpoint`.
+ *
+ * State is persisted after every page, so an interrupt at any point resumes from
+ * the last yielded page. On success the volatile `cursor` is cleared and
+ * `completedAt`/`total` advance; on failure they are preserved (a failed
+ * refresh on top of a complete mirror stays "ready").
+ */
+export async function runSync(store, sync, ctx, options) {
+    const existing = await store.readState();
+    // An init re-runs from scratch only when the prior run completed; otherwise it
+    // resumes from a persisted cursor (crash mid-write, or caught error mid-init).
+    const incompleteInit = options.mode === 'init' && existing.status !== 'complete';
+    const resuming = incompleteInit && existing.cursor !== undefined;
+    const startCursor = resuming ? existing.cursor : undefined;
+    const startCheckpoint = options.mode === 'refresh' || incompleteInit ? existing.checkpoint : undefined;
+    const startedAt = (resuming && existing.startedAt) || new Date().toISOString();
+    let cursor = startCursor;
+    let checkpoint = startCheckpoint;
+    await store.writeState({ status: 'in_progress', startedAt, cursor, checkpoint });
+    let pagesFetched = 0;
+    let recordsApplied = 0;
+    let tombstonesApplied = 0;
+    try {
+        for await (const page of sync({
+            mode: options.mode,
+            cursor: startCursor,
+            checkpoint: startCheckpoint,
+            signal: ctx.signal,
+        })) {
+            const tombstones = page.tombstones ?? [];
+            await store.applyBatch(page.records, tombstones);
+            pagesFetched += 1;
+            recordsApplied += page.records.length;
+            tombstonesApplied += tombstones.length;
+            cursor = page.cursor;
+            // Durable high-water mark advances monotonically (lexicographic compare).
+            if (page.checkpoint && (!checkpoint || page.checkpoint > checkpoint)) {
+                checkpoint = page.checkpoint;
+            }
+            await store.writeState({ status: 'in_progress', startedAt, cursor, checkpoint });
+            options.onProgress?.({
+                pages: pagesFetched,
+                records: recordsApplied,
+                tombstones: tombstonesApplied,
+                cursor,
+                checkpoint,
+            });
+        }
+        const total = await store.count();
+        await store.writeState({
+            status: 'complete',
+            startedAt,
+            checkpoint,
+            cursor: undefined, // volatile cursor is meaningless once complete
+            completedAt: new Date().toISOString(),
+            total,
+        });
+        ctx.log.info?.('Mirror sync complete', {
+            mode: options.mode,
+            pagesFetched,
+            recordsApplied,
+            tombstonesApplied,
+            total,
+        });
+        return { pagesFetched, recordsApplied, tombstonesApplied, total };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const errorState = {
+            status: 'error',
+            startedAt,
+            cursor,
+            checkpoint,
+            error: message,
+        };
+        await store.writeState(errorState);
+        ctx.log.error?.('Mirror sync failed', { mode: options.mode, error: message });
+        throw err;
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/services/mirror/core/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../../../src/services/mirror/core/runner.ts"],"names":[],"mappings":"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"}

package/dist/services/mirror/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Public barrel for the MirrorService primitive. Servers import
+ * from `@cyanheads/mcp-ts-core/mirror` to stand up a persistent, self-refreshing
+ * local mirror of a bulk upstream dataset: declare a store + a `sync` generator
+ * via {@link defineMirror}, then `runSync` / `query` / `status`.
+ *
+ * The SQLite driver is loaded lazily on first use, so importing this barrel does
+ * not pull in `bun:sqlite` / `better-sqlite3` until a mirror is actually opened.
+ *
+ * @module services/mirror
+ */
+export { defineMirror, type Mirror, type MirrorRunOptions } from './core/defineMirror.js';
+export { type RunnerContext, runSync } from './core/runner.js';
+export { type OpenHandleOptions, openSqliteHandle, type SqliteHandle, type SqliteStatement, type SqlValue, } from './sqlite/handle.js';
+export { buildSchemaSql, DEFAULT_FTS_TOKENIZER, type SchemaSpec, validateSchemaSpec, } from './sqlite/schema.js';
+export { type SqliteMirrorStoreSpec, sqliteMirrorStore, } from './sqlite/sqliteMirrorStore.js';
+export type { FilterOp, Migration, MirrorDefinition, MirrorLogger, MirrorRow, MirrorStatus, MirrorStore, QueryFilter, QueryOptions, QueryResult, QuerySort, RunSyncOptions, SyncContext, SyncGenerator, SyncMode, SyncPage, SyncProgress, SyncResult, SyncState, SyncStatus, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/mirror/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/mirror/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,MAAM,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EAAE,KAAK,aAAa,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EACL,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,QAAQ,GACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,KAAK,UAAU,EACf,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,qBAAqB,EAC1B,iBAAiB,GAClB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EACV,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,WAAW,EACX,SAAS,EACT,cAAc,EACd,WAAW,EACX,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,SAAS,EACT,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/services/mirror/index.js

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Public barrel for the MirrorService primitive. Servers import
+ * from `@cyanheads/mcp-ts-core/mirror` to stand up a persistent, self-refreshing
+ * local mirror of a bulk upstream dataset: declare a store + a `sync` generator
+ * via {@link defineMirror}, then `runSync` / `query` / `status`.
+ *
+ * The SQLite driver is loaded lazily on first use, so importing this barrel does
+ * not pull in `bun:sqlite` / `better-sqlite3` until a mirror is actually opened.
+ *
+ * @module services/mirror
+ */
+export { defineMirror } from './core/defineMirror.js';
+export { runSync } from './core/runner.js';
+export { openSqliteHandle, } from './sqlite/handle.js';
+export { buildSchemaSql, DEFAULT_FTS_TOKENIZER, validateSchemaSpec, } from './sqlite/schema.js';
+export { sqliteMirrorStore, } from './sqlite/sqliteMirrorStore.js';
+//# sourceMappingURL=index.js.map

package/dist/services/mirror/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/mirror/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAsC,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EAAsB,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAEL,gBAAgB,GAIjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,cAAc,EACd,qBAAqB,EAErB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,iBAAiB,GAClB,MAAM,+BAA+B,CAAC"}

package/dist/services/mirror/sqlite/handle.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Runtime-agnostic SQLite handle for the mirror store. Uses the
+ * built-in `bun:sqlite` driver under Bun and the `better-sqlite3` optional peer
+ * dependency on Node — both exposed through one synchronous handle interface
+ * (the intersection of the two driver APIs).
+ *
+ * The drivers are loaded via variable-specifier dynamic imports so the
+ * framework typechecks and builds without `bun-types` in scope or
+ * `better-sqlite3` installed; both resolve at runtime on the matching runtime.
+ * @module services/mirror/sqlite/handle
+ */
+/** Primitive value storable in a mirror column. Buffers/bigints are out of scope for v1. */
+export type SqlValue = string | number | null;
+/**
+ * Runtime-agnostic prepared statement — the intersection of the `bun:sqlite`
+ * and `better-sqlite3` statement APIs. Bound parameters are passed positionally.
+ */
+export interface SqliteStatement<TRow = unknown> {
+    all(...params: SqlValue[]): TRow[];
+    get(...params: SqlValue[]): TRow | undefined;
+    run(...params: SqlValue[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+}
+/** Runtime-agnostic database handle. Synchronous — both drivers are synchronous. */
+export interface SqliteHandle {
+    close(): void;
+    exec(sql: string): void;
+    prepare<TRow = unknown>(sql: string): SqliteStatement<TRow>;
+    transaction<T>(fn: () => T): T;
+}
+/** Options for {@link openSqliteHandle}. */
+export interface OpenHandleOptions {
+    /** `PRAGMA busy_timeout` in ms — how long a writer waits on a locked DB. Default 5000. */
+    busyTimeoutMs?: number;
+}
+/**
+ * Open (or create) a SQLite database at `path`, picking the driver for the
+ * current runtime. Creates the parent directory, enables WAL, and sets
+ * `busy_timeout` so a refresh writer and reader processes coexist without
+ * spurious `database is locked` errors.
+ *
+ * Throws `ConfigurationError` on Node when `better-sqlite3` is not installed,
+ * and `DatabaseError` for any other open failure.
+ */
+export declare function openSqliteHandle(path: string, options?: OpenHandleOptions): Promise<SqliteHandle>;
+//# sourceMappingURL=handle.d.ts.map

package/dist/services/mirror/sqlite/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../../../../src/services/mirror/sqlite/handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,4FAA4F;AAC5F,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,IAAI,GAAG,OAAO;IAC7C,GAAG,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,CAAC;IACnC,GAAG,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC;IAC7C,GAAG,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACnF;AAED,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5D,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CAChC;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA0CD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,YAAY,CAAC,CAuBvB"}