subscribe() cannot resume: `since` reaches the adapter, but nothing can set it

[cuibonobo]

An app that subscribes, stops, and starts again has no way to say where it left off. It gets every change from the present onward, and nothing about the gap.

The plumbing for the other half already exists:

• SubscribeChangesOptions.since is on the adapter hook, and APIAdapter.subscribeChanges() honors it — it becomes Last-Event-ID on the connection.
• RecordChange.seq reaches subscribers on relayed frames, so a consumer can retain the last cursor it saw.
• Stack.openRelay() passes filter, includeRecords, onError and onReset through, and nothing else. SubscribeOptions has no since, so there is nothing to pass.

So a consumer can hold a cursor and an adapter can consume one, and the two cannot be introduced. Change events § Known limitations states the consequence — "a restart with no feed is a full resync" — as though it followed from having no feed. For a remote stack it doesn't: the feed resumes, the app just can't ask it to.

Why this matters more than a missing convenience

D4's rejection of blocking hooks rests on this. The argument for handlers never blocking a write is that an indexer which must not miss a write gets that from a resumable cursor and idempotent application, not from making every subscriber a latency and failure dependency of every write. That argument is right, and it names something an app cannot currently reach. Indexing is the first of #3's four use cases, and it is the one that needs this.

Delivery is already at-least-once and deduped on (recordId, version, kind), so the consumer side of resumption is a solved problem — persist the cursor after applying, and let dedupe absorb whatever the overlap replays.

Questions to settle

Does a refused cursor fire onReset? Today onReset is documented as never firing on first connect, which was true when the first connect had nothing to resume from. A caller-supplied since the server will not honor is exactly a gap on first connect, and it is the case an app most needs to hear about — it is the difference between "you are current" and "you are missing an unknown amount". The rule needs revisiting alongside the option.

What does since mean on a local stack? Local events carry no seq, so there is no cursor a local stack could ever have minted. Silently ignoring one lets an app believe it resumed when it did not; refusing loudly costs an app portability between a local and a hosted stack, which the same document sells as the point of designing the event model once. Neither is obviously right.

What does a resume: false server do with it? It answers every connection with a reset already, so presumably nothing new — but that is the path where an app's carefully persisted cursor is worth nothing, and it should be stated rather than inferred.

Not in scope

Minting seq locally. Ordering and durability are storage concerns, and core runs no storage it shares with anyone. A local stack has one writing process and therefore no gap to resume across; this issue is about a cursor a server minted reaching the adapter that can present it.

[cuibonobo]

A second use case: a static-site generator reading a stack

Recording this alongside indexing, since it's the same shape as the case the issue already makes.

An Eleventy stack integration is planned for the cuibonobo.com migration, and watch/serve mode is exactly the consumer described here: apply the changes since last time, persist the cursor after applying, resume from it on restart. --serve restarts constantly during a session — a config edit, a crash, a template error — so "a restart means a full resync" is the normal case for that consumer, not the exceptional one.

The dedupe property the issue mentions holds here too: rebuilding a page that didn't need rebuilding is harmless, so a resumption that replays some overlap costs nothing. Which is what makes the cursor sufficient and a stronger delivery guarantee unnecessary.

Not a blocker for a first version — full rebuilds work, and at personal-site scale they're fast enough that incremental builds are an optimization rather than a requirement. Marking priority: low for that reason. It's what separates a correct incremental build from one that silently misses changes across a restart, so it matters whenever incremental mode gets built, not before.

On the open question about local stacks

From a consumer's side, the portability argument in the issue is the one that bites. A generator ought to be able to build against a local SQLite file and a remote stack with the same code — that's the pitch for designing the event model once — and since throwing on one but not the other breaks that at exactly the point where the two are supposed to be interchangeable.

But silently accepting a cursor that can't mean anything is worse: the app believes it resumed. If those are the only two options, refusing loudly is the safer failure, and the portability cost is bounded — a consumer can check stack.features (or whatever surfaces resumability) once at startup and pick its strategy, rather than discovering the difference by having a cursor rejected mid-run. That does mean the capability wants to be discoverable, which is arguably the more useful half of the answer.

---

Generated by Claude Code