@crvouga/mockingbird-service-sqlite 1.2.1 → 2.0.0

package/CHANGELOG.md

@@ -1,6 +1,30 @@
 # Changelog — @crvouga/mockingbird-service-sqlite
 
-## 1.2.1 (2026-09-30)
+## 2.0.0 (2026-10-04)
+
+### ⚠️ Breaking changes
+
+- isolate internal routes ([5e19b21](https://github.com/crvouga/mockingbird/commit/5e19b21d403acc74b04778a8b545e80bcbdf8d51))
+
+### Features
+
+- publish agent package indexes ([eca61d3](https://github.com/crvouga/mockingbird/commit/eca61d358b86982cf0b777ae8bd7feaa3663aaa6))
+
+### Fixes and improvements
+
+- honor configured prefixes ([4f569d7](https://github.com/crvouga/mockingbird/commit/4f569d74ca8089f2ed5e33a1abf32b90973f41dd))
+
+## 1.3.0 (2026-09-30)
+
+### Features
+
+- record SQL timelines and serve the admin explorer ([8ced17a](https://github.com/crvouga/mockingbird/commit/8ced17ac398e386ef4e9d7e01fc7744c34b95d07))
+
+### Fixes and improvements
+
+- typecheck SQL admin timelines without a built sqlite port ([072daf4](https://github.com/crvouga/mockingbird/commit/072daf439f3967823149d7b0a8a9ce664d25097c))
+
+## 1.2.1 (2026-09-29)
 
 ### Fixes and improvements
 

package/DISCOVERY.md

@@ -0,0 +1,48 @@
+# @crvouga/mockingbird-service-sqlite discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-sqlite/`; no repository checkout is needed to discover the mock's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`COMPATIBILITY.md`](COMPATIBILITY.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **In-memory SQL engine**.
+- Oracle: **SQLite via bun:sqlite (version pinned in COMPATIBILITY.md)**.
+- Repository command: `bun run --cwd packages/service/sqlite test:sqlite-compat`.
+- Evidence model: Fail-closed differential contracts compare results, errors, counters and logical state.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `README.md public test controls`
+- `COMPATIBILITY.md compatibility and divergence evidence`
+
+For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual mock result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `sqlite`.

package/README.md

@@ -145,16 +145,39 @@ The mocks create their own tables (`mockingbird_records`, `mockingbird_sequences
 resetting one mock leaves the others' data in a shared database intact. Any other client with the same sync surface (better-sqlite3, a
 wrapped `bun:sqlite`) also satisfies the port.
 
+### Socket
+
+SQLite has no client/server protocol, so the stock `sqlite3` CLI cannot attach to this
+engine. `@crvouga/mockingbird-service-sqlite/socket` is a Node entry (it needs `node:net`)
+that listens on `sqlite://host:port/name` and speaks a length-prefixed JSON frame. The
+in-package `connect(uri)` client runs statements against it. Portable queries, including
+from a browser, go through the admin API (`POST /__admin/sql/query`) instead.
+
+```ts
+import { connect, serve } from "@crvouga/mockingbird-service-sqlite/socket"
+
+const server = await serve("sqlite://127.0.0.1:0/app")
+const db = await connect(server.url)
+await db.exec("CREATE TABLE notes (body TEXT)")
+await db.close()
+await server.close()
+```
+
+`mockingbird-sqlite serve` prints that URI. `createAdmin` from
+`@crvouga/mockingbird-service-sqlite/admin` serves the same `/__admin` surface as every
+other mock, including the table explorer.
+
 ### Method semantics
 
 | Method | Behaviour |
 | --- | --- |
 | `exec(sql)` | Runs all semicolon-separated statements; **discards** row results (`void`). Does **not** accept bind parameters. Read `db.changes` / `db.lastInsertRowid` afterwards if needed (counters reflect the **most recent** completed statement, matching SQLite). |
-| `query(sql, params?, { at? }?)` | **Single statement only** (trailing `;` is fine). Returns all rows. `at` queries an immutable checkpoint without changing live state. Multi-statement scripts throw `misuse`. |
+| `query(sql, params?, { at? }?)` | **Single statement only** (trailing `;` is fine). Returns all rows. `at` is a `Snapshot` or a timeline checkpoint id and queries that checkpoint without changing live state. Multi-statement scripts throw `misuse`. |
 | `prepare(sql)` | **Single statement only**. Parses immediately; the AST is reused. Pass binds as rest args to `run` / `all` / `get` / `result` on each call. |
 | `transaction(fn)` | If idle: `BEGIN`, `fn()`, `COMMIT`, or `ROLLBACK` + rethrow. If already in a transaction: nested savepoint. A nested SQL `BEGIN` still errors. `close()` inside `fn` throws `misuse`. |
-| `snapshot()` | Freeze a reusable `Snapshot` template (no encode). Illegal inside a transaction. |
-| `checkpoint()` / `branch(at?)` | Name a COW snapshot as a checkpoint; open an isolated branch from it (or current state). |
+| `snapshot()` | Freeze a reusable `Snapshot` template (no encode) and commit it on the followed timeline branch. Illegal inside a transaction. |
+| `checkpoint()` / `branch(at?)` | `checkpoint` records the same timeline point as `snapshot`. `branch` opens an isolated database from a snapshot (or the current state). |
+| `record(branch?)` / `fork(name, at?)` / `checkout(id, branch?)` / `reset()` | Timeline history on this database. `record` commits the live state. `fork` adds a branch pointer and does not switch live state. `checkout` installs a checkpoint. `reset` returns to the origin checkpoint on `main`. `history` lists heads and checkpoints. |
 | `Snapshot.open()` | Copy-on-write fork from a template. The parent stays open. |
 | `Snapshot.encode()` | Lazy SQLM blob for persistence / worker boot (computed once, cached). |
 | `Snapshot.decode(bytes)` | Decode a blob once per `Uint8Array` (WeakMap); later `open()` calls are copy-on-write. |
@@ -295,24 +318,44 @@ Stable runtime exports of the main entry:
 | `Statement` | Class returned by `db.prepare(sql)` (not constructed directly): `run`, `all`, `get`, `result`. |
 | `SqliteError` | Error class thrown for SQL and API errors: `category` (`ErrorCategory`), `sqliteCode` / `code` (SQLite result-code name, e.g. `"SQLITE_CONSTRAINT_UNIQUE"`; default `"SQLITE_ERROR"`). |
 
-Signatures (types are exported too: `DatabaseOptions`, `RunResult`, `ResultSet`, `ErrorCategory`,
-`BindValue`, `QueryRow`, `QueryValue`):
+Signatures (types are exported too: `DatabaseOptions`, `HistoryCheckpoint`, `DatabaseHistory`,
+`RunResult`, `ResultSet`, `ErrorCategory`, `BindValue`, `QueryRow`, `QueryValue`):
 
 ```ts
 interface DatabaseOptions {
   seed?: number | bigint                 // default 1; ignored when random is "os"
   random?: "deterministic" | "os"        // default "deterministic"; "os" is CSPRNG like SQLite
   now?: Date | (() => Date) | "system"   // default 2000-01-01T00:00:00.000Z; "system" is wall clock
+  maxCheckpoints?: number                // timeline checkpoints to retain; default 1000
+}
+
+interface HistoryCheckpoint {
+  id: string
+  branch: string
+  parent: string | null
+  at: number
+}
+
+interface DatabaseHistory {
+  readonly size: number
+  head(branch?: string): HistoryCheckpoint | undefined
+  branches(): Readonly<Record<string, string>>
+  checkpoints(): readonly HistoryCheckpoint[]
 }
 
 declare class Database {
   constructor(options?: DatabaseOptions)
   exec(sql: string): void
-  query<T = QueryRow>(sql: string, params?: readonly BindValue[], options?: { at?: Snapshot }): T[]
+  query<T = QueryRow>(sql: string, params?: readonly BindValue[], options?: { at?: Snapshot | string }): T[]
   prepare(sql: string): Statement
   transaction<T>(fn: () => T): T
   snapshot(): Snapshot
   checkpoint(): Snapshot
+  record(branch?: string): HistoryCheckpoint
+  fork(name: string, at?: string): HistoryCheckpoint
+  checkout(id: string, branch?: string): HistoryCheckpoint
+  reset(): HistoryCheckpoint
+  readonly history: DatabaseHistory
   branch(at?: Snapshot): Database
   close(): void                             // also [Symbol.dispose] when available
   readonly changes: number

package/dist/admin.d.ts

@@ -0,0 +1,13 @@
+import type { Database, DatabaseOptions } from "./api/database.js";
+
+export interface AdminOptions {
+  database?: Database;
+  adminKey?: string;
+  databaseOptions?: DatabaseOptions;
+}
+
+export interface AdminServer {
+  fetch(request: Request): Promise<Response>;
+}
+
+export declare function createAdmin(options?: AdminOptions): AdminServer;