instant_record 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e36ca64624187dc76c35e76ec89e98d6bcd58aa154b8cbed2674bfab317196c9
+  data.tar.gz: 1b8abb4f4b2184f500d761572870ff23cec96815d7cc79ec7197058fc97fdbff
+SHA512:
+  metadata.gz: a3909b291e85633d5e5f6f044ab42e33c9570df8ecc7c22aafbb3821dcd10c51be34f4b9cc504f5482d5c10085db7ec737c905c73a9ff70026435af232570bf2
+  data.tar.gz: 337d2df1ce4ca243d71249f0afe607f78d4ec86ced28988577caf1c94108fd3af850e25b07b19b1fb1d7f0d858e7b75d180deb3daa3a0875879f42c9b93d22df

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.1.0
+
+First release. Real Active Record models running in the browser on ruby.wasm
+and PGlite, writing optimistically through a durable outbox that syncs to a
+Rails + Postgres server.
+
+- Browser-runtime migrations: `InstantRecord.prepare_database!` brings a returning visitor's local database up to the app's current schema. `DatabaseTasks.prepare_all` alone cannot — the browser VM's working directory is `/`, so ActiveRecord's relative `db/migrate` resolves to nothing and the migrator silently reports zero pending. `InstantRecord::LocalSchema` reconciles `schema_migrations` by the rule `assume_migrated_upto_version` would have used, then migrates only what is genuinely newer. Ships `instant_record/pglite_compat`, without which no in-browser migration could run at all (Rails' PostgreSQL statement pool asks the PGlite connection for a `status` it does not define, and DDL clears the pool).
+- Microsecond timestamps on every wire path, in both directions, via `InstantRecord.wire_attributes`. The change log and outbox previously serialized through ActiveSupport's JSON encoder (milliseconds) while bootstrap and records kept all six places; the mismatch lost `(created_at, id)` keyset neighbours between history pages and biased last-write-wins against whichever side was rounded.
+- Writes that lose last-write-wins are no longer badged as delivered: the server returns the row that won, the client reconciles to it, and `on_discarded_change` lets a model observe what was thrown away. A client running ahead of the server's schema now gets a rejection rather than jamming the outbox behind a mutation that would retry forever.
+- `InstantRecord.server_url` for app paths that must reach the authoritative server from either runtime.
+- Windowed sync: `sync_window limit:, partition_by:` on Syncable models bounds what syncs — fresh clients hydrate from `GET /bootstrap` (windowed snapshot + cursor) instead of replaying the whole change log, a cold boot evicts windowed models back to their window (pending rows never evicted), and older rows page in through `GET /records` keyset cursors via `InstantRecord.fetch_history` (local-first, idempotent, no outbox noise). The service worker gains an `instant_record.fetch_history` page message sharing the tick's single-flight guard.
+- Swiss Slack demo: thousands of seeded history messages (unlogged `insert_all` backfill, preserved across resets), windowed conversation rendering with scroll-up pagination, and in-place DOM morphing on sync — no more full-page reload on the conversation view.
+- Demo pages that let a visitor check the claims rather than take them on trust: `/console` (a REPL against whichever runtime served the page — the eval action is defined inside `browser_only`, so it does not exist on the server), `/source` (each page's own source, read off disk by the runtime that rendered it), `/receipts` (bundle size and query latency measured on the visitor's device, local and server side by side), and `/migrate` (shipping a v2 migration on demand against a local database that still holds rows and a full outbox).
+- Initial spike: gem skeleton, engine, Syncable concern, sync protocol, demo app.
+- Auto-mount the sync engine; models opt in by including `Syncable` (no registration).
+- `server_only` / `browser_only` blocks for runtime-scoped model rules.
+- `instant_record:install` generator and `instant_record:build` task; opt-in `build_on_precompile`.
+- Ruby-owned sync loop: `InstantRecord.configure` / `start` / `sync_now`; transport moved from service-worker JS into Ruby via JS-fetch interop.
+- SSE endpoint rewritten as a Rack streaming body (no `ActionController::Live`): no thread per stream, no database connection pinned while idle, query cache bypassed in the poll loop. Falcon documented and measured as the recommended server for SSE-heavy deployments (500 concurrent streams, p50 378ms).
+- Browser bundle shrunk 87.2MB -> 61.7MB raw (17.1MB gzipped): `public/` unpacked, mail-family frameworks excluded, wasm-opt strip pass wired into `wasmify:pack`.
+- `InstantRecord::RuntimeScoped`: `server_only`/`browser_only` blocks now work on any class (controllers, jobs) via `extend`; Syncable models get them automatically as before. Demo and README show server-only auth/scoping patterns.
+- Review-driven simplification pass: sync loop consolidated into `InstantRecord::Client` (hash-native, no intra-VM JSON round-trips); fixed tick starvation — change polls now request `window=0` so a tick never holds the server's SSE tail window; cursor persisted once per poll; `MutationApplier` extracted from the mutations controller; `Change.poll` owns the connection-scoped uncached read; shared CORS/mount-path constants; SSE window configurable (`config.instant_record.sse_window_seconds`) with ±10% reconnect jitter; service worker template is single-source (demo copies via `rake pwa:sync`); gem tests run standalone and share helpers.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kieran Klaassen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,378 @@
+# InstantRecord
+
+Rails models that run in the browser, sync to your server, and keep working offline.
+
+## The Problem
+
+Apps like Linear feel instant because they never make you wait on the network: every read and write hits a **local** database, the UI renders from local data, and syncing with the server happens in the background. No spinners, no loading states, and offline works for free.
+
+Building that today means a JavaScript sync engine, a client-side store, an API layer, and client-side state management — a whole second data architecture that leaves Rails behind.
+
+InstantRecord is a bet that Rails developers can have local-first without leaving Ruby:
+
+- **Instant** — `Issue.create!` commits to a Postgres running inside the browser and the UI re-renders immediately. The network is never in the hot path.
+- **Durable** — every write records a mutation in the same local transaction, so nothing is lost to a crash, a reload, or a dead connection.
+- **Convergent** — a background loop drains mutations to your Rails server (the source of truth) and streams everyone else's changes back over SSE.
+- **Still just Rails** — the same `ApplicationRecord` model file runs on both sides. Validations, scopes, callbacks — no API client, no duplicate schema, no JavaScript data layer.
+
+:construction: **This is a proof of concept.** The core loop is built and demonstrated: instant optimistic writes, offline-durable outbox, two clients converging over SSE, and server rejections rolling back cleanly. See [What's proven](#whats-proven).
+
+## The Two Runtimes
+
+The same model file loads into two Ruby runtimes, each backed by its own Postgres:
+
+|  | In the browser | On the server |
+|---|---|---|
+| Ruby | CRuby compiled to WebAssembly, inside a **service worker** | CRuby + Puma |
+| Database | [PGlite](https://pglite.dev) — Postgres-in-wasm, persisted to IndexedDB | PostgreSQL |
+| Writes | **Optimistic** — instant local commit, queued for sync | **Authoritative** — validated, versioned, logged |
+| Your controllers & views | Run here when the page is served by the service worker | Run here at `localhost:3000` |
+
+```mermaid
+flowchart LR
+  subgraph tab [Your browser tab]
+    UI[Your views] --> VM["Your Rails app on ruby.wasm"]
+    VM --> PG[(PGlite)]
+  end
+  VM -->|mutations up| S[Your Rails app on a server]
+  S --> P[(Postgres)]
+  S -->|changes down over SSE| VM
+```
+
+## Usage
+
+### 1. Install
+
+```ruby
+# Gemfile
+gem "instant_record"
+```
+
+[wasmify-rails](https://github.com/palkan/wasmify-rails) comes along as a dependency — it provides the browser build tasks and the PGlite database adapter.
+
+### 2. Make a model syncable
+
+This is the whole opt-in:
+
+```ruby
+class Issue < ApplicationRecord
+  include InstantRecord::Syncable
+
+  validates :title, presence: true
+end
+```
+
+Syncable models need three columns — a string/uuid primary key, `server_version:integer`, and `sync_state:string`. The gem's own tables (outbox, sync metadata, change log, idempotency ledger) install automatically as engine migrations — just run `bin/rails db:migrate`.
+
+Rules that should only run on the server (authorization, quotas, anything the client shouldn't decide) stay in the same file, scoped with a block:
+
+```ruby
+class Issue < ApplicationRecord
+  include InstantRecord::Syncable
+
+  validates :title, presence: true
+
+  server_only do
+    validate :quota_not_exceeded   # server rejects; the client rolls back
+  end
+
+  browser_only do
+    after_commit :flash_confetti   # local-runtime behavior
+  end
+end
+```
+
+There's no server setup: the sync engine auto-mounts at `/instant_record` on the server — `POST /mutations` (batched, idempotent writes) and `GET /events` (SSE change stream) — and every model that includes `Syncable` is syncable. Two optional knobs:
+
+```ruby
+# config/application.rb — move or disable the mount
+config.instant_record.mount_path = "/sync"    # or false to mount manually
+
+# config/initializers/instant_record.rb — restrict syncing to an explicit allowlist
+InstantRecord.sync(Issue, Todo)
+```
+
+### 3. Build the browser bundle
+
+Your app compiles to a wasm module that boots in a service worker. One generator sets everything up — the wasm environment, the PGlite database config, and a PWA shell wired with the sync driver:
+
+```sh
+bin/rails generate instant_record:install
+bin/rails instant_record:build     # compiles the Ruby core (once) + packs app.wasm
+```
+
+**Deploying:** the bundle is a build artifact, like precompiled assets. Either build it in your deploy pipeline with `bin/rails instant_record:build`, or opt in to building during asset precompilation:
+
+```ruby
+# config/application.rb
+config.instant_record.build_on_precompile = true
+```
+
+(Off by default — the build needs the wasm toolchain and network access for ruby.wasm artifacts.)
+
+### 4. Write your app like it's normal Rails
+
+No special APIs in your controllers or views. When the page is served by the service worker, this code executes **in the browser**, reading and writing the local database:
+
+```ruby
+class IssuesController < ApplicationController
+  def index
+    @issues = Issue.order(created_at: :desc)   # instant: local Postgres read
+  end
+
+  def create
+    Issue.create!(issue_params)                # instant: local commit + queued for sync
+    redirect_to root_path
+  end
+end
+```
+
+```erb
+<% @issues.each do |issue| %>
+  <li>
+    <%= issue.title %>
+    <span class="badge"><%= issue.sync_state %></span>  <%# "pending" until the server acks %>
+  </li>
+<% end %>
+```
+
+Useful helpers:
+
+- `issue.sync_state` — `"pending"` (not yet acked) or `"synced"`
+- `InstantRecord.pending_count` — outbox size, for an "unsynced changes" indicator
+- `InstantRecord.sync_now` — force a sync pass (the background loop runs anyway)
+- `server_only { ... }` / `browser_only { ... }` — runtime-scoped model rules
+- `InstantRecord.browser?` — the underlying runtime check, for anywhere else
+- `InstantRecord::Client.applying_remote?` — whether the write running right now arrived from the server, rather than being made here
+- `InstantRecord.server_url(path)` — the URL that reaches the authoritative server from either runtime, honouring a customised `mount_path`
+
+Convergence is last-write-wins on `updated_at`, and the value that loses is gone from the row. A model can watch for that:
+
+```ruby
+class Issue < ApplicationRecord
+  include InstantRecord::Syncable
+
+  # A value from the server that last-write-wins threw away. The block runs with
+  # the losing attribute hash at the only moment it exists here — nothing is
+  # assigned, no callback fires, and the gem keeps no copy.
+  on_discarded_change { |attributes| Rails.logger.info("dropped #{attributes["title"].inspect}") }
+end
+```
+
+#### Server-only controller behavior: auth and scoping
+
+Controllers load in both runtimes too — the browser runs them against local data, the server against Postgres. Anything that depends on sessions, cookies, or secrets exists only on the server, so scope it there:
+
+```ruby
+class IssuesController < ApplicationController
+  extend InstantRecord::RuntimeScoped
+
+  server_only do
+    before_action :authenticate_user!   # sessions and secrets: server only
+  end
+
+  browser_only do
+    skip_forgery_protection             # no CSRF secrets in the local runtime
+  end
+
+  def index
+    @issues = issues_scope.order(created_at: :desc)
+  end
+
+  private
+
+  def issues_scope
+    # Server: enforce per-user scoping. Browser: the local database already
+    # holds only what the server synced to this client, so Issue.all IS the
+    # scoped set.
+    InstantRecord.browser? ? Issue.all : current_user.issues
+  end
+end
+```
+
+**Where authorization actually lives:** browser-side checks are UX, never enforcement — the user owns the client and everything in it. Real enforcement has exactly two places, both on the server:
+
+1. **The mutations endpoint** — server-side validations and `server_only` model rules reject writes the client wasn't allowed to make; the client rolls back.
+2. **What you sync down** — a client can only render what the change stream delivered to it. (Per-user scoping of the stream itself — `syncable_to` — is on the roadmap; today the PoC syncs every registered model to every client.)
+
+A `server_only` controller filter protects the server-rendered surface; it cannot and need not protect the browser's local rendering.
+
+### 5. Sync just happens
+
+The sync loop is Ruby, configured in Ruby:
+
+```ruby
+# config/initializers/instant_record.rb (optional — these are the defaults)
+InstantRecord.configure do |config|
+  config.endpoint = "/instant_record"   # absolute URL for cross-origin setups
+  config.sync_interval = 3              # base backoff for retrying a stuck outbox
+end
+```
+
+The browser shell calls `InstantRecord.start` once at boot; from there Ruby owns the drain, the change stream, reconnects, and reconciliation. (`InstantRecord.sync_now` forces a pass manually.) The only JavaScript left is a timer — wasm Ruby can't sleep without blocking the VM, so the service worker provides the clock and nothing else.
+
+Behind the scenes:
+
+- **First load** — a new client hydrates from a bootstrap snapshot (current state plus the sync cursor, windowed per model — see below) and remembers its position, so later visits paint instantly from IndexedDB and fetch only what's new.
+- **Every write** — committed locally first, then delivered to the server in the background. Offline just means "delivered later"; queued writes survive reloads.
+- **Other clients** — every accepted change streams to all connected clients over SSE, and their pages re-render from local data. Concurrent edits resolve last-write-wins.
+- **Rejections** — if the server refuses a write (failed validation, server-only rule), the client rolls the local record back to server state and stops retrying.
+
+### 6. Window large tables
+
+Tables with unbounded history (chat messages, events, logs) don't have to sync whole. Declare a **sync window** and only the newest rows reach clients:
+
+```ruby
+class Message < ApplicationRecord
+  include InstantRecord::Syncable
+
+  sync_window limit: 50, partition_by: :channel_id   # newest 50 per channel
+end
+```
+
+Windows order by `(created_at, id)`, so a windowed model needs a `created_at` column — and an index on `(partition, created_at, id)` keeps the queries flat at depth.
+
+Declaring a window changes three things:
+
+- **Fresh clients bootstrap.** A client that has never synced hydrates from `GET /instant_record/bootstrap` — current state, windowed per model, plus the change-log cursor — instead of replaying the whole change log. Windowless models still serialize in full.
+- **Boot-time eviction.** On a cold boot the browser trims each windowed model back to its window per partition. Rows with `sync_state: "pending"` are never evicted.
+- **History pages on demand.** Older rows stream in through keyset cursors (never OFFSET), applied idempotently with no outbox noise:
+
+```ruby
+InstantRecord.fetch_history(Message,
+  partition: channel_id,
+  before: { created_at: oldest.created_at.iso8601(6), id: oldest.id },
+  limit: 50)
+# => { ok: true, applied: 50, has_more: true }    — or :busy while a sync pass runs
+```
+
+In the browser this serves repeat scrolls and offline scrollback from the local database and only hits `GET /instant_record/records` for pages it doesn't hold. Page JavaScript reaches it through a service-worker message (never from inside a request — the wasm VM can't re-enter itself):
+
+```js
+const channel = new MessageChannel();
+channel.port1.onmessage = (event) => { /* {ok, has_more, error} */ };
+navigator.serviceWorker.controller.postMessage(
+  { type: "instant_record.fetch_history",
+    request: { type: "Message", partition: channelId,
+               before: { created_at: oldestAt, id: oldestId }, limit: 50 } },
+  [channel.port2],
+);
+```
+
+**Render the top of the scrollback server-side.** A windowed view needs a slot above its oldest row — a scroll-up sentinel, or a "beginning of history" marker once there's nothing left. Render that slot in the initial HTML even when you don't yet know which it is, and let JavaScript fill it in place. Injecting it after a probe shifts every row below it by its height on each load.
+
+The Slack demo's infinite scroll is the reference wiring — IntersectionObserver sentinel, scroll anchoring, in-place DOM updates — in the Stimulus controller `demo/app/javascript/controllers/conversation_controller.js`.
+
+## Running the demo
+
+Requirements: Ruby 3.3.3, Node, PostgreSQL, [wasmtime](https://wasmtime.dev) and [wasi-vfs](https://github.com/kateinoigakukun/wasi-vfs).
+
+```sh
+# Gem tests
+bundle install && bundle exec rake test
+
+# One-time setup
+cd demo
+bundle install
+bin/rails db:prepare
+bin/rails test
+cd pwa && yarn install && cd ..
+
+# One-time browser build (~5 min)
+bin/rails instant_record:build    # writes pwa/public/app.wasm (~62 MB)
+
+# Run it — sync server on :3000, PWA on :5173
+bin/dev
+```
+
+`bin/dev` runs both processes under foreman (see `demo/Procfile.dev`): the Rails sync server, and the Vite server that hosts the service worker, `app.wasm`, and PGlite's wasm.
+
+Open http://localhost:5173/boot.html, wait for **Service Worker Ready**, then open http://localhost:5173/ — that page is rendered by Rails in your browser.
+
+Things to try:
+
+- **Instant writes** — create an issue; it appears immediately with a `pending` badge that flips to `synced`.
+- **Two clients** — open http://127.0.0.1:5173/ too (different origin = separate service worker + separate local database). Changes propagate between windows through the server. A fresh client catches up automatically.
+- **Infinite scroll** — `/slack` seeds thousands of messages in `#general`, but a fresh client only syncs the newest 50 per conversation. Scroll to the top and older pages stream in; messages arriving mid-read update the page without a reload or a scroll jump.
+- **Offline** — stop the Rails server, create issues (they stay `pending`), reload the tab (still there), restart the server and watch them drain.
+- **Rejection** — create an issue titled `reject me`. It appears optimistically, the server refuses it, and it disappears on reconcile.
+
+## Scaling the SSE stream
+
+Every client holds one persistent SSE connection — the service worker keeps it open in JavaScript and hands each event to Ruby, because Ruby awaiting a chunk itself would suspend the sync guard and starve outbox drains for the length of the window. Concurrent streams therefore scale with open tabs; plan your server accordingly. The engine's stream endpoint is a plain Rack streaming body (no `ActionController::Live`, no thread per stream) that releases its database connection between polls, so it runs well on both servers; the ceiling is the server's concurrency model. Measured on the demo (M-series MacBook, dev mode):
+
+| Server | Concurrent SSE clients | Result |
+|---|---|---|
+| Puma (3 threads default) | 2 | Works — p50 delivery 103ms |
+| Puma (3 threads default) | 3 | Streams consumed every thread; the sync write itself starved — 0 delivered |
+| Puma (3 threads default) | 50 | Server unresponsive for minutes (rails/rails#55762's failure mode) |
+| Falcon (fiber per request) | 200 | 200/200 delivered, p50 442ms, 0 errors |
+| Falcon (fiber per request) | 500 | 500/500 delivered, p50 378ms, ~13 MB RSS, 0 errors |
+
+**Recommendation:** Puma is fine for development and a handful of clients. For SSE-heavy deployments, run [Falcon](https://github.com/socketry/falcon) — streams become fibers, `sleep` and `pg` yield to the scheduler, and thousands of idle connections are cheap:
+
+```ruby
+# Gemfile
+gem "falcon", require: false
+```
+
+```ruby
+# config/application.rb — fiber-scoped execution state under Falcon only
+config.active_support.isolation_level = :fiber if defined?(Falcon)
+```
+
+```sh
+bundle exec falcon serve --bind http://localhost:3000
+```
+
+Browser clients receive changes over that held stream — measured at **130ms** from a server-side write to the row appearing, bounded by the server's 0.5s change-log poll rather than by any client interval. Reopening with `?after=<cursor>` replays whatever a dropped connection missed, so nothing polls for changes. The tail window is configurable via `config.instant_record.sse_window_seconds`.
+
+There is no heartbeat in the browser: a sync pass runs on a local write, at boot, and when the network returns, then retries with backoff only while the outbox still has something in it. An idle tab issues no requests at all beyond holding its stream. Reproduce the numbers with `demo/script/sse_load_spike.rb`.
+
+## What's proven
+
+Measured on the demo (Chrome, M-series MacBook):
+
+- Rails 8.1.3 boots under wasm32-wasi with the full gem bundle, including this gem.
+- Warm boot — VM init plus PGlite schema prepare — in **~1.8 seconds**; the `app.wasm` module is **61.9 MB** raw, **17.1 MB** gzipped over the wire.
+- Instant optimistic create with local persistence across reloads.
+- Two independent clients converging through POST + SSE, including fresh-client catch-up.
+- Server rejection reconciled by rolling the local record back.
+- ~5,000 seeded messages in one channel: a fresh client bootstraps only the newest window per conversation, older pages stream in on scroll, and a cold boot evicts the local database back to the window.
+- 226 tests (116 gem + 110 demo) covering the atomic outbox, idempotent apply, last-write-wins both ways, cursor resume, rejection reconcile, bootstrap hydration, keyset history pages, eviction, migration over a populated local store, and schema skew in both directions.
+
+## Roadmap ideas
+
+Sketched but **not built**:
+
+```ruby
+# Model-level conflict resolution beyond last-write-wins
+class Issue < ApplicationRecord
+  include InstantRecord::Syncable
+  resolves_conflict_on :state, prefer: :closed
+end
+```
+
+Also out of scope for the PoC, on purpose: CRDTs, Postgres logical replication, multi-tab leader election, attachments, authentication/authorization on the sync endpoints, and migration generators. An Inertia-compatible layer (server-seeded props hydrating the local database, plus a JS read surface via PGlite live queries) is captured as a follow-up direction in `docs/plans/`.
+
+## History
+
+View the [changelog](CHANGELOG.md).
+
+## Contributing
+
+Everyone is encouraged to help improve this project. Here are a few ways you can help:
+
+- [Report bugs](https://github.com/kieranklaassen/instant_record/issues)
+- Fix bugs and [submit pull requests](https://github.com/kieranklaassen/instant_record/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+To get started with development:
+
+```sh
+git clone https://github.com/kieranklaassen/instant_record.git
+cd instant_record
+bundle install
+bundle exec rake test
+```

data/app/controllers/instant_record/bootstraps_controller.rb

@@ -0,0 +1,34 @@
+module InstantRecord
+  # First-sync hydration: current state (windowed per model when a sync_window
+  # is declared) plus the change-log cursor, so a fresh client never replays
+  # the whole change log. The cursor is read BEFORE the rows, inside one
+  # transaction: events committed between cursor and response re-apply
+  # idempotently client-side, whereas the reverse order would skip them.
+  class BootstrapsController < ActionController::API
+    before_action { headers.merge!(InstantRecord::CORS_HEADERS) }
+
+    def show
+      payload = ActiveRecord::Base.transaction do
+        cursor = Change.maximum(:id) || 0
+        { cursor: cursor, records: bootstrap_models.flat_map { |model| serialize_rows(model) } }
+      end
+      render json: payload
+    end
+
+    private
+
+    # Eager-load first so development doesn't miss lazily-loaded models;
+    # syncable_models then resolves like synced_model (allowlist or all
+    # Syncable includers).
+    def bootstrap_models
+      Rails.application.eager_load! unless Rails.application.config.eager_load
+      InstantRecord.syncable_models
+    end
+
+    def serialize_rows(model)
+      window = model.instant_record_sync_window
+      scope = window ? window.in_window : model.all
+      scope.map { |record| InstantRecord.record_payload(record) }
+    end
+  end
+end

data/app/controllers/instant_record/events_controller.rb

@@ -0,0 +1,59 @@
+module InstantRecord
+  class EventsController < ActionController::Base
+    # SSE change stream as a lazily-enumerated response body — not
+    # ActionController::Live (which burns a thread per stream and bypasses the
+    # fiber scheduler). An #each body is the portable Rack streaming
+    # interface: Puma and Falcon both write each chunk as it is yielded.
+    # Under Falcon each stream is a fiber, so `sleep` and pg queries suspend
+    # the fiber; under Puma the body holds the request thread.
+    #
+    # The change-log row id is the event id, which doubles as the client's
+    # cursor: catch-up from ?after= (or the Last-Event-ID reconnect header),
+    # then tail for a bounded window and close. ?window= lets a client shorten
+    # the tail — the gem's own sync loop polls with window=0 (catch-up only)
+    # so a tick never holds a long stream.
+    EVENT_STREAM_HEADERS = {
+      "content-type" => "text/event-stream",
+      "cache-control" => "no-store",
+      "x-accel-buffering" => "no"
+    }.freeze
+
+    class EventStream
+      def initialize(cursor:, deadline:)
+        @cursor = cursor
+        @deadline = deadline
+      end
+
+      def each
+        loop do
+          Change.poll(@cursor).each do |change|
+            @cursor = change.id
+            yield "id: #{change.id}\nevent: change\ndata: #{change.as_event.to_json}\n\n"
+          end
+
+          break if Time.current >= @deadline
+          sleep 0.5
+        end
+      end
+    end
+
+    def index
+      cursor = (request.headers["Last-Event-ID"] || params[:after] || 0).to_i
+
+      headers.merge!(EVENT_STREAM_HEADERS).merge!(InstantRecord::CORS_HEADERS)
+      self.response_body = EventStream.new(cursor: cursor, deadline: Time.current + window_seconds)
+    end
+
+    private
+
+    def window_seconds
+      configured = Rails.application.config.instant_record.sse_window_seconds.to_f
+      requested = params[:window]&.to_f
+      seconds = requested ? requested.clamp(0.0, configured) : configured
+
+      # +/-10% jitter so a herd of streams opened together doesn't reconnect
+      # in lockstep at every window boundary.
+      seconds.positive? ? seconds * (0.9 + rand * 0.2) : seconds
+    end
+  end
+end

data/app/controllers/instant_record/mutations_controller.rb

@@ -0,0 +1,21 @@
+module InstantRecord
+  class MutationsController < ActionController::API
+    before_action { headers.merge!(InstantRecord::CORS_HEADERS) }
+
+    def preflight
+      head :no_content
+    end
+
+    # Accepts a batch of client mutations; MutationApplier owns the sync
+    # semantics (idempotency, LWW, versioning, change logging).
+    def create
+      results = Array(params.require(:mutations)).map do |raw|
+        MutationApplier.apply(
+          raw.permit(:id, :record_type, :record_id, :operation, :base_version, changes: {})
+        )
+      end
+
+      render json: { results: results }
+    end
+  end
+end

data/app/controllers/instant_record/records_controller.rb

@@ -0,0 +1,46 @@
+module InstantRecord
+  # Keyset-cursor history pages for windowed models: rows strictly below the
+  # (created_at, id) tuple, newest first. Backs InstantRecord.fetch_history;
+  # never uses OFFSET, so page cost stays flat at any depth.
+  class RecordsController < ActionController::API
+    # Independent of any model's window size: the ceiling a client can
+    # request in one page.
+    HARD_LIMIT = 200
+
+    before_action { headers.merge!(InstantRecord::CORS_HEADERS) }
+
+    def index
+      model = InstantRecord.synced_model(params[:type])
+      return head :not_found unless model
+
+      window = model.instant_record_sync_window
+      return head :unprocessable_entity unless window
+      return head :bad_request if window.partition_by && params[:partition].blank?
+
+      before_at = parse_time(params[:before_created_at])
+      return head :bad_request if before_at.nil? || params[:before_id].blank?
+
+      limit = (params[:limit].presence || window.limit).to_i.clamp(1, HARD_LIMIT)
+      rows = window
+        .keyset_below(at: before_at, id: params[:before_id], partition: params[:partition])
+        .limit(limit + 1)
+        .to_a
+
+      render json: {
+        records: rows.first(limit).map { |record| InstantRecord.record_payload(record) },
+        has_more: rows.size > limit
+      }
+    end
+
+    private
+
+    # Time.zone.parse returns nil for unparseable input but raises
+    # ArgumentError for out-of-range components ("25:61"); treat both as a bad
+    # cursor so a crafted param is a 400, not a 500.
+    def parse_time(value)
+      Time.zone.parse(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/app/models/instant_record/applied_mutation.rb

@@ -0,0 +1,9 @@
+module InstantRecord
+  # Idempotency ledger: one row per mutation id ever processed, storing the
+  # result so replays return the original outcome without re-applying.
+  class AppliedMutation < ActiveRecord::Base
+    self.table_name = "instant_record_applied_mutations"
+
+    serialize :result_payload, coder: JSON
+  end
+end

data/app/models/instant_record/change.rb

@@ -0,0 +1,30 @@
+module InstantRecord
+  # Server-side ordered change log. The auto-increment id is the SSE cursor.
+  class Change < ActiveRecord::Base
+    self.table_name = "instant_record_changes"
+
+    serialize :attributes_payload, coder: JSON
+
+    scope :after, ->(cursor) { where("id > ?", cursor.to_i).order(:id) }
+
+    # One poll of the change log for a streaming loop. Block-scoped connection
+    # checkout — an idle stream must not pin a database connection while it
+    # sleeps — and uncached, because the request executor's query cache would
+    # otherwise return the first poll's result forever.
+    def self.poll(cursor)
+      connection_pool.with_connection do
+        uncached { after(cursor).to_a }
+      end
+    end
+
+    def as_event
+      {
+        type: record_type,
+        id: record_id,
+        operation: operation,
+        version: version,
+        attributes: attributes_payload
+      }
+    end
+  end
+end