foldkit-remote-server 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -66,6 +66,13 @@ That separation matters. `RemoteServer` can decide that a client may read
66
66
  that field comes from Postgres, another service, an in-memory index, or
67
67
  something else.
68
68
 
69
+ It does **not** own HTTP or WebSocket transport, authentication or session
70
+ storage, a database connection, the client's normalized cache, or Surface
71
+ activation. A durable write is the client's to keep (Remote's outbox) and the
72
+ writer's to recognise when it comes again (a ledger); this package only passes
73
+ its operation id through. Client-authored state that must merge across devices
74
+ is [`foldkit-sync`](../sync)'s.
75
+
69
76
  ## Install
70
77
 
71
78
  ```bash
@@ -297,10 +304,10 @@ const ProjectsByOwner = Query.make('ProjectsByOwner', {
297
304
  Result: Query.connection(Project),
298
305
  })
299
306
 
307
+ // `projectsPage` is your own reader: one page of edges for the window.
300
308
  const ProjectsByOwnerSource = RemoteServer.query(
301
309
  ProjectsByOwner,
302
- ({ input, window, principal, select }) =>
303
- projectsPage({ ownerId: input.ownerId, window, principal }),
310
+ ({ input, window, principal }) => projectsPage({ ownerId: input.ownerId, window, principal }),
304
311
  )
305
312
 
306
313
  const Server = RemoteServer.make({
@@ -311,7 +318,7 @@ const Server = RemoteServer.make({
311
318
 
312
319
  A Query returns:
313
320
 
314
- ```ts
321
+ ```ts sketch
315
322
  {
316
323
  edges,
317
324
  start,
@@ -330,78 +337,13 @@ of guessing from row count.
330
337
 
331
338
  Query input is decoded through the Query's own Schema before your callback runs.
332
339
  The callback receives the decoded input, the requested `QueryWindow`, the
333
- `select` slice when the client sent one, and the principal.
334
-
335
- ### Running a query body over rows you already hold
336
-
337
- A descriptor declared with
338
- [`Query.define`](../remote#queries-and-pagination) carries its meaning as a
339
- value, and `evaluate` runs that value directly:
340
-
341
- ```ts
342
- import { evaluate } from 'foldkit-entity'
343
-
344
- evaluate(PostsBySlug.body!, { slug: 'intro' }, rows)
345
- // the matching rows, in the order the body asks for
346
- ```
347
-
348
- It lives in [`foldkit-entity`](../entity), beside the IR it interprets, because
349
- it is that IR's reference semantics rather than anything this package does —
350
- and because a client judging rows it already holds needs it without depending on
351
- a server package. This package re-exports it, so importing it from either place
352
- means the same thing.
353
-
354
- It is pure — it reads the rows it is given and nothing else — and it is the
355
- reference the compiled interpreters are checked against. `foldkit-remote-drizzle`
356
- turns the same body into SQL; the test suite runs both over the same rows in a
357
- real SQLite and requires the same ids in the same order. That is what makes a
358
- body source-neutral in fact rather than in principle.
359
-
360
- **It follows SQL, not JavaScript.** The case that matters is null: `null = null`
361
- is *unknown* in SQL and matches no row, where JavaScript would call the two
362
- equal. A comparison keeps a row only when it is true, so a null on either side
363
- drops it.
364
-
365
- What it refuses rather than guesses:
366
-
367
- - **Ordering by a column that is null in some row.** SQLite sorts nulls first,
368
- Postgres sorts them last for `asc`: the databases disagree with each other, so
369
- there is no answer to be conformant to and picking one would make this wrong
370
- against the other.
371
- - **Comparing values it has no order for**, such as a number against a string.
372
- - **Searching text that holds a NUL character**, which Postgres text cannot
373
- hold and SQLite's `like` stops at.
374
-
375
- Each throws where the query runs, naming the query. An ordering is checked
376
- before anything is sorted: every term over every matched row, in row order, so
377
- the error names the first row that breaks it (`number and string` when a later
378
- row holds text), the same on every engine, whichever pair a sort would have
379
- compared first. One matched row, or none, has nothing to order and is never
380
- refused.
381
-
382
- ### Checking an interpreter against the semantics
383
-
384
- `evaluate` is the reference, and `cases` is what it is a reference *to*: the
385
- conformance suite, exported so an interpreter written elsewhere can be held to
386
- the same semantics.
387
-
388
- ```ts
389
- import { Subject, cases, rows } from 'foldkit-remote-server'
390
-
391
- for (const { what, body, input, expected } of cases) {
392
- expect(yourInterpreter(body, input, rows).map(row => row.id)).toEqual(expected)
393
- }
394
- ```
340
+ `select` slice when the client sent one, the principal, and the server's
341
+ `viewer` of it.
395
342
 
396
- Every case is chosen to make interpreters **disagree**, which is the only kind
397
- that tests anything: mixed case, nulls on both sides of a comparison, `%` and
398
- `_` as literal text, the empty search, a predicate compared to a boolean either
399
- way round. That is not caution for its own sake — `contains` reached a released
400
- package meaning three different things because every value in the original
401
- fixture happened to be lowercase.
402
-
403
- Both interpreters here run it: this package over rows in memory, and
404
- `foldkit-remote-drizzle` compiled to SQL against a real SQLite.
343
+ A query declared with `Query.define` carries its meaning as a value, so it
344
+ needs no hand-written Source: `RemoteServer.memory` runs its body with
345
+ `evaluate`, and `foldkit-remote-drizzle` compiles it to SQL (see [Reference
346
+ semantics](#reference-semantics-evaluate-and-the-conformance-suite)).
405
347
 
406
348
  ## Mutations
407
349
 
@@ -418,6 +360,7 @@ const RenameProject = Mutation.make('RenameProject', {
418
360
  Output: Schema.Struct({ id: Schema.String }),
419
361
  })
420
362
 
363
+ // `renameProject` is your own write, answering the Output.
421
364
  const RenameProjectSource = RemoteServer.mutation(
422
365
  RenameProject,
423
366
  ({ input, principal }) =>
@@ -443,14 +386,15 @@ A refusal of who is asking, rather than of what they asked, is
443
386
  `Effect.fail(RemoteServer.forbid('Only an admin may archive.'))`: sent as
444
387
  `Forbidden` with the reason (a 403 over JSON), or with none when `forbid()` is
445
388
  given none, so the refusal says nothing of why. It is the same for every
446
- mutation, so it needs no `Refusal` declared. The Source is also given `requestId`, the client's id for the
447
- request, and `operation`, the operation's id across clients, both the same on
448
- every retry of it. Record a write under `operation`, never `requestId`: a
449
- request id is a counter in one client's Model, so two clients' first requests
450
- share it, and a record keyed by it would answer one client with another's write.
451
- `operation` is none from a client that sends none, and bounded on the wire (128
452
- characters of `A-Z a-z 0-9 : . _ -`). A Source
453
- may additionally return connection changes:
389
+ mutation, so it needs no `Refusal` declared. A refusal of a visitor, someone
390
+ not signed in, is `RemoteServer.unauthenticated(reason)` instead (a 401):
391
+ signing in is the remedy, and Remote's outbox keeps a durable write so
392
+ answered waiting for it, where it settles a `Forbidden` one as failed.
393
+ `RemoteServer.write` refuses a visitor a write whose Entity sets a member from
394
+ who asks that way, and `GuardServer` refuses a visitor every write it would
395
+ refuse.
396
+
397
+ A Source may additionally return connection changes:
454
398
 
455
399
  ```ts
456
400
  RemoteServer.prepend(connection, Project.ref(id))
@@ -461,49 +405,124 @@ RemoteServer.remove(connection, Project.ref(id))
461
405
  Those confirmed changes replace the corresponding optimistic connection layers
462
406
  on the client.
463
407
 
408
+ ### A write sent again: `operation`
409
+
410
+ The Source is also given `requestId`, the client's id for the request, and
411
+ `operation`, the operation's id across clients, both the same on every retry of
412
+ it. Record a write under `operation`, never `requestId`: a request id is a
413
+ counter in one client's Model, so two clients' first requests share it, and a
414
+ record keyed by it would answer one client with another's write. `operation`
415
+ is none from a client that sends none, and bounded on the wire (128
416
+ characters of `A-Z a-z 0-9 : . _ -`).
417
+
418
+ Expect the same operation more than once. A write that no answer came back
419
+ for fails on the client with `Unreachable` (`RemoteUnreachable`): the request
420
+ did not go, or what came back was no Remote answer (not JSON, or under a 408,
421
+ 429, 502, 503 or 504, which this package never answers with but a gateway or
422
+ a rate limiter may). The server may have landed it. `Data.retry` sends it
423
+ again under the same operation, and a durable write (`Data.mutate(…, {
424
+ durable: true })`) is stored in the page's outbox and sent again on its own,
425
+ after an `Unreachable` and after a reload, with the same operation id and the
426
+ same `now`. What a retry does depends on the write: setting a value sets it
427
+ again, an `expect`ed revision answers `Conflict`, and only a ledger (below)
428
+ recognises the operation and answers it from its record. A durable Mutation
429
+ therefore needs a writer with a ledger, or a handler that records by
430
+ `operation`.
431
+
432
+ The outbox never sends one principal's waiting writes as another's: it holds
433
+ its queue for one store key and scope, and sends none of it once either
434
+ changes. The server still decides each send as whoever that request
435
+ authenticates as.
436
+
437
+ ### Declared writes: no handler
438
+
464
439
  A mutation declared as a `Write` (`Mutation.write`) needs no handler.
465
440
  `RemoteServer.write(mutation, writer)` binds the input to the write, only the
466
441
  keys the client named when it named some, and hands the row's id and new values
467
442
  to an `EntityWriter`, which writes them and answers the row as written:
468
443
 
469
444
  ```ts
470
- RemoteServer.write(EditProject, writer(Db.Project)) // `writer` from foldkit-remote-drizzle
445
+ // `EditProject` is a Mutation.write; `writer` and the binding `Db` are foldkit-remote-drizzle's.
446
+ RemoteServer.write(EditProject, writer(Db.Project))
471
447
  ```
472
448
 
473
- The answer is the mutation's patch, or for a delete its deletion. With
474
- `expect`, the writer is told the revision the row was read at; no row at it is
475
- refused as `Refusal.conflict`. With `when`, the writer is handed the
476
- precondition and the input encoded, checks it in the statement that writes, and
477
- fails a row at the revision that does not hold it with `RemoteUnmet`
478
- (`RemoteServer.unmet()`), which is refused as `Refusal.unmet`: absent first, then
479
- a moved revision, then the precondition. A row the write would leave that
480
- breaks an invariant of its Entity (`Entity.invariant`) is the writer's to
481
- refuse, with `RemoteServer.invalid(message, rule, path)`, which is refused as
482
- `Refusal.invalid`: the invariant's id and path, or none and empty when the
483
- caller may not be told them. A writer says it judges invariants
484
- (`invariants: true`), and a write over an Entity that has some, through a writer
485
- that does not, is refused where it is served. A writer says it checks one
486
- (`preconditions: true` on `EntityWriter`), and a write with a `when` over a
487
- writer that does not is refused where it is served, rather than written whatever
488
- the row holds. A write's increments reach the writer apart from its values
489
- (`increments`, each field's amount, encoded), to be added in the statement that
490
- writes; a writer says it adds them (`increments: true`), and a write with one
491
- over a writer that does not is refused where it is served; so are computed
492
- assignments (`assignments`, each a `Computation`), over a writer that computes
493
- them (`assignments: true`). An increment or a computed assignment that expects
494
- no revision is served only over a writer with a ledger (`ledger: true`), which
495
- records each update under its `operation` and answers a retry from the record
496
- (`recorded`), and only for a request carrying an operation id. Even so, a
497
- concurrent pair must land as one result: an increment only of an integer, and a
498
- computed assignment only where the writer `commutes` it, unless the writer pins
499
- the row it read (`pins: true`, a guard with a revision). A writer
500
- may refuse a write for what only its store knows (`refuses`, asked once where
501
- the write is served): the Drizzle writer refuses an amount that may be a
502
- fraction for a column that holds integers. An update of no row fails; an insert of an id
503
- already holding what it writes answers that row, and a delete of a row already
504
- gone succeeds, so a retry of either is safe. An insert of an id holding
505
- anything else fails: that row is not its answer. The writer must be for the write's own Entity,
506
- which is checked where the mutation is served.
449
+ The answer is the mutation's patch, or for a delete its deletion. The writer
450
+ must be for the write's own Entity, which is checked where the mutation is
451
+ served. The [declared writes guide](../../docs/declared-writes.md) walks
452
+ through the whole path; what this package does with each part of a write:
453
+
454
+ - **What the server chooses.** A write of an Entity with `Entity.sets` is
455
+ handed the members its context sets as well, never from the input (an
456
+ insert all of them, an update those set `on: 'write'`): `Expr.viewer` from
457
+ `RemoteServer.make({ viewer: principal => Option<{ entity, id }> })`, and
458
+ `Expr.now` from the write's time. A value that comes to null where the
459
+ member holds none (a visitor's) is refused as forbidden; a server that
460
+ serves a write setting the viewer with no `viewer` is refused where it is
461
+ made. A path from the viewer is read through the server's own sources, as
462
+ the asker may see each row (the run context's `read`); a server that mounts
463
+ no source for a row the path reaches is refused where it is made, and a
464
+ path reaching no row the asker may see is null.
465
+ - **The write's time** is the client's when it sent one (`Data.mutate`'s
466
+ `now`, the moment the reader acted, which the client showed the row at) and
467
+ it lies within `RemoteServer.make({ clockSkew })` of the server's Effect
468
+ `Clock`: 60 seconds unless given, `0` to never take a client's time.
469
+ Otherwise it is the server's own, and a time past a bound above zero is
470
+ reported as a `ClockSkewed` diagnostic: a durable write sent long after it
471
+ was made takes the server's time. The bound is how far a client can backdate
472
+ or postdate a row; nothing else of a write's context comes from the client.
473
+ A hand-written mutation reads the same time as `now` in its context. A
474
+ retried insert, which only a writer's ledger recognises, keeps its first
475
+ time. A retried update is a new write to a server without a ledger, and
476
+ stores the time of the attempt that ran: the same sent `now` while it lies
477
+ within `clockSkew`, else the server's clock at that attempt (#291). A ledger
478
+ answers the retry from its record, so the first time stays.
479
+ - **`expect`**: the writer is told the revision the row was read at; no row
480
+ at it is refused as `Refusal.conflict`.
481
+ - **`when`**: the writer is handed the precondition and the input encoded,
482
+ checks it in the statement that writes, and fails a row at the revision
483
+ that does not hold it with `RemoteUnmet` (`RemoteServer.unmet()`), refused
484
+ as `Refusal.unmet`: absent first, then a moved revision, then the
485
+ precondition.
486
+ - **Invariants** (`Entity.invariant`) are the writer's to judge over the row
487
+ the write would leave, refusing with `RemoteServer.invalid(message, rule,
488
+ path)`, sent as `Refusal.invalid`: the invariant's id and path, or none and
489
+ empty when the caller may not be told them.
490
+ - **Increments and computed assignments** reach the writer apart from its
491
+ values (`increments`, each field's amount, encoded; `assignments`, each a
492
+ `Computation`), to be applied in the statement that writes. One that
493
+ expects no revision is served only over a writer with a ledger, and only
494
+ for a request carrying an operation id; even so, a concurrent pair must land
495
+ as one result: an increment only of an integer, and a computed assignment
496
+ only where the writer `commutes` it, unless the writer pins the row it read
497
+ (`pins: true`, a guard with a revision).
498
+ - **A rule over another row.** A writer that holds an update's or a delete's
499
+ row to a `requires` (`RowRequirement`: bodies over the row, all or any of
500
+ them) in its own statement refuses a row that fails it with `Forbidden`:
501
+ `foldkit-guard` hands it a rule that reads another row that way.
502
+ - **Creates and deletes.** An update of no row fails, and a delete of a row
503
+ already gone succeeds, so its retry is safe. An insert of an id already
504
+ taken is refused as `Refusal.taken` (the writer fails `insert` with
505
+ `RemoteTaken`, `RemoteServer.taken()`), with one answer whatever the row
506
+ there holds and whether its asker may see it: comparing that row with the
507
+ insert would tell the asker what it holds. Only a writer with a ledger tells a retry from another create
508
+ of the id, by the operation the client sent, and answers it with the row;
509
+ without one, a create whose answer was lost is refused when it is sent
510
+ again. Give a writer a ledger where a client may resend a create, and make
511
+ ids that a guess cannot find where whether a row exists is itself private.
512
+
513
+ A writer says what it can do, and `RemoteServer.write` refuses, where the
514
+ write is served, one that needs what its writer lacks rather than writing it
515
+ wrongly:
516
+
517
+ | `EntityWriter` says | It | Needed by |
518
+ | --- | --- | --- |
519
+ | `preconditions: true` | checks `when` in the statement | a write with a `when` |
520
+ | `invariants: true` | judges the Entity's invariants | a write of an Entity that has any |
521
+ | `increments: true` | adds `increments` in the statement | a write with an increment |
522
+ | `assignments: true` | computes `assignments` in the statement | a write with a computed assignment |
523
+ | `ledger: true` (with `recorded`) | records each update and insert under its `operation`, and answers a retry from the record | an increment or computed assignment with no `expect` |
524
+ | `requires: true` | holds the row to `requires` | `GuardServer.writer` over a rule reading another row, which throws where it is made without it |
525
+ | `refuses(write)` | names what only its store knows it cannot land (the Drizzle writer: a fractional amount for an integer column) | every write, asked once |
507
526
 
508
527
  A writer with a `read` (the row as a principal may see it, under the read
509
528
  rule its Source applies) answers through it: the patch is the written row as
@@ -515,34 +534,147 @@ it where the server would not list it. A writer may refuse with
515
534
  rows they point at, so such a guard can tell a write that unlinks a hidden row
516
535
  from one that changes nothing; `foldkit-remote-drizzle`'s `writer` has both.
517
536
 
518
- Remote mutations are immediate requests against **server-owned** state. They are
519
- not a durable offline intent log; client-authored edits that must survive offline
520
- belong to `foldkit-sync`.
537
+ ### What an answer carries
538
+
539
+ A Source answers the rows it changed; the client says what it shows of them.
540
+ `Data.mutate` sends, with each request, what its active Surfaces read of each
541
+ entity, every field its optimistic layer shows, and the supplied members a
542
+ created or edited row foresees (`may`) (`shown`). After the Source runs, the handler reads, of each row the
543
+ outcome names (a patch, or a list insert), the shown fields the patch left out
544
+ and every shown relation, and answers that read beside the patch (`read`):
545
+
546
+ ```text
547
+ outcome rows × client's shown fields − fields the patch carries -> read -> answer
548
+ ```
549
+
550
+ So a declared write, which answers the columns it stored, also answers the
551
+ derived count, the `may` and the author's name the page reads of the row, and
552
+ the client releases its optimistic layer with nothing left to fetch. The read
553
+ is an ordinary one: the Sources' `read`, `authorize` and `filter` decide it, a
554
+ field the asker may not read comes back settled, and a row they cannot see is
555
+ left out of it, keeping what the patch gave.
556
+
557
+ A Source whose write the server cannot see (a row of a join table, a count it
558
+ keeps itself) names the row with no values, and the read answers all of it:
559
+
560
+ ```ts
561
+ // Sketch, inside a mutation Source over a `Post` Entity: a like in a join table
562
+ // changes its post, so name the post and read nothing yourself.
563
+ return { output: { liked: true }, entities: [Remote.patch(Post, input.postId, {})] }
564
+ ```
565
+
566
+ The read runs after the write commits, outside its transaction. If it fails,
567
+ it is reported as an `AnswerUnread` [diagnostic](#diagnostics) and the
568
+ mutation is answered without it: the write has
569
+ landed, and the client fetches what it lacks as it would have. A deleted row is
570
+ not read.
571
+
572
+ A request also names the lists the client judges the write moves (`lists`):
573
+ each the first page of a query, as the client's read entry would ask for it.
574
+ The handler admits them before the write runs, then reads each after it with
575
+ the query's own handler, so the page is what `FoldkitRemoteQuery` would answer,
576
+ `authorize` and `filter` included, and answers them beside the rows (`lists`):
577
+
578
+ ```text
579
+ request lists -> admitted (before the write) -> read as queries (after it) -> answer.lists
580
+ ```
581
+
582
+ A list is admitted when its query is one the server serves, its window is a
583
+ first page (`first`, no `after`), its `select` names the query's Entity within
584
+ a read's page bound, and the rows of every list admitted so far stay within
585
+ `maxIdsPerEntity` per Entity. One that is not, or whose read fails (reported
586
+ as `AnswerUnread`), is left out; the write runs either way, and the client
587
+ fetches that list as it would have. The wire refuses more than
588
+ `MAX_ANSWER_LISTS` lists in one request.
589
+
590
+ A declared write (`RemoteServer.write`) also reads each row its row points at
591
+ through a `one` relation, before and after the write, through the writer's
592
+ `linked`, where that link can change one of the row's derived members: a
593
+ `Derived.count` or `Derived.exists` over that relation, or any supplied member
594
+ (`Derived.make`), which may read anything. Inserting a `Like` reads what the
595
+ page shows of its post, the new `likeCount` included
596
+ ([#233](https://github.com/doeixd/foldkit-plus/issues/233)), and not its user,
597
+ whose members no like changes. A member declared after `Entity.relate` counts:
598
+ the Entity has one set of members, whichever descriptor declared them
599
+ ([#332](https://github.com/doeixd/foldkit-plus/issues/332)). A row's derived
600
+ members change only with the rows pointing at it, so no app names them. These rows are read, never sent as patches of their own: one the
601
+ asker may not see is not answered at all. Live subscribers hear the outcome's
602
+ own patches, not the read, which is one asker's view.
521
603
 
522
604
  ## Live data
523
605
 
524
- There are two ways to produce live changes.
606
+ A live subscription is one stream per Entity, from that Entity's live Source.
607
+ There are three ways to produce one:
608
+
609
+ - write a live Source directly, below;
610
+ - over Drizzle, `foldkit-remote-drizzle`'s `pollLive`, a live Source that
611
+ re-reads the subscribed rows and lists from inside the subscriber's own
612
+ request, which is what Workers need;
613
+ - in a long-lived process, a `liveHub` that re-reads what each write changed.
525
614
 
526
615
  ### Write a live Source directly
527
616
 
528
617
  ```ts
618
+ // `projectEvents` is your own stream of `LiveChange`s.
529
619
  const ProjectLive = RemoteServer.live(Project, {
530
- subscribe: ({ requirements, after, principal }) =>
620
+ subscribe: ({ requirements, queries, after, principal }) =>
531
621
  projectEvents({
532
622
  requirements,
623
+ queries,
533
624
  after,
534
625
  principal,
535
626
  }),
536
627
  })
537
628
  ```
538
629
 
539
- `after` is the client's resume cursor. Events at or before it are duplicates.
630
+ `after` is the client's resume cursor. Events at or before it are duplicates,
631
+ and the stream's cursors count on from it: its first event is `after + 1`, or
632
+ the client takes the skipped cursors for a gap and restarts the stream.
540
633
  The stream carries Remote `LiveChange`s: entity patches/deletes and connection
541
634
  insert/remove/invalidate events.
542
635
 
636
+ `queries` are the lists of this Entity the subscriber reads live
637
+ (`liveQuery(Data, …)`), each a `LiveQuery` the handler has already
638
+ admitted and resolved: `identity` (the connection as the client keys it, for
639
+ the connection events), `select` (what the read draws of each row), and
640
+ `edges`, the registered query run as the subscriber with the page's window.
641
+ The handler refuses, with `RemoteLiveRefused` and before any live Source is
642
+ asked, a list of a query it does not register, an input that does not
643
+ decode, one with no `select` or no `first`, one whose `select` is of another
644
+ Entity than its query lists (a `QuerySource` names that Entity: `RemoteServer.query`
645
+ reads it from the descriptor's connection), and one whose `first`, added to
646
+ the ids of its Entity the subscription names, passes `maxIdsPerEntity`. A
647
+ subscription watches at most 32 lists (`MAX_LIVE_QUERIES`), refused at decode.
648
+
543
649
  If an Entity has no live Source, it contributes no stream. That is not an error:
544
650
  the client planner can fall back to refetching it.
545
651
 
652
+ A live Source that reads rows to send them must read them as a read would, or
653
+ it sends what the read handlers withhold. `RemoteServer.readAs` is that read:
654
+ only the asked fields the Source declares and its `authorize` allows, each
655
+ record through its `filter`, and no other field.
656
+
657
+ ```ts
658
+ const asReader = RemoteServer.readAs(ProjectSource, {
659
+ ids: ['p1'],
660
+ fields: ['name', 'privateNotes'],
661
+ principal: { isAdmin: false },
662
+ })
663
+ // An Effect that succeeds with Option.some([{ id: 'p1', values: { name: 'Apollo' } }]),
664
+ // or Option.none() when the principal may read none of the fields asked.
665
+ ```
666
+
667
+ `RemoteServer.allowedFields(ProjectSource, principal, fields)` says which of
668
+ `fields` that read would read, without reading: a Source reading several rows
669
+ together, each asked for fields of its own, reads them in one read and still
670
+ tells nothing of a row whose fields the principal may read none of.
671
+
672
+ A live Source that sends only what it reads through one Source names it as
673
+ `reads`, so a startup check can trust it as far as it trusts that Source:
674
+ `GuardServer.validate` accepts a live Source over a guarded Entity only when
675
+ it `reads` the guarded Source it checked. `foldkit-remote-drizzle`'s `pollLive`
676
+ reads through `readAs` and sets `reads`.
677
+
546
678
  ### Let a `liveHub` re-read changed fields
547
679
 
548
680
  A hub fans **what changed** out to live subscribers. Give it to the handlers,
@@ -551,6 +683,7 @@ fields it carries, each deletion as a deletion. A mutation Source names nothing
551
683
  twice.
552
684
 
553
685
  ```ts
686
+ // Inside an Effect.gen: building a hub is an Effect.
554
687
  const entitySources = [ProjectSource]
555
688
  const hub = yield* RemoteServer.liveHub(entitySources)
556
689
 
@@ -559,13 +692,14 @@ const handlers = RemoteServer.handlers(Server, principal, {
559
692
  })
560
693
 
561
694
  // Only for a write that is not a mutation: a database trigger consumer, a job.
562
- yield* hub.changed(Project.ref(projectId), ['status', 'updatedAt'])
563
- yield* hub.deleted(Project.ref(projectId))
695
+ yield* hub.changed(Project.ref('p1'), ['name'])
696
+ yield* hub.deleted(Project.ref('p1'))
564
697
  ```
565
698
 
566
699
  A mutation's publish runs after its Source returned, so after a write that
567
- commits as it goes. A failed publish is logged and the mutation still answers:
568
- its write has happened, and a failed answer would be retried.
700
+ commits as it goes. A failed publish is reported as a `PublishFailed`
701
+ [diagnostic](#diagnostics) and the mutation still answers: its write has
702
+ happened, and a failed answer would be retried.
569
703
 
570
704
  The hub remembers each subscriber's requirements and principal. `changed`:
571
705
 
@@ -586,7 +720,11 @@ Subscribers that selected none of the changed fields do no work, and
586
720
  subscribers with one principal share one re-read. One principal means the same
587
721
  value, unless the hub is given a `key`: then two requests whose principals
588
722
  have one key, each with a principal object of its own, share it, read as the
589
- first of them. A key must therefore name everything the Sources decide by:
723
+ first of them. A key must therefore name everything the Sources decide by,
724
+ the reader itself included when a Source answers a viewer-relative member (a
725
+ `Derived.exists`, whose value is each reader's own; `foldkit-guard`'s
726
+ `Policy.keyOf` names every field of the principal). A key by role, as here,
727
+ fits Sources that answer only by role:
590
728
 
591
729
  ```ts
592
730
  const hub = yield* RemoteServer.liveHub(entitySources, {
@@ -622,14 +760,16 @@ const SharedProjectSource = RemoteServer.entity<Principal>(Project, {
622
760
  re-read.
623
761
  - `foldkit-remote-drizzle`'s `source` and `RemoteServer.memory` take it too,
624
762
  and `foldkit-guard`'s `GuardServer.validate` refuses a shared field a Read
625
- rule could tell readers apart by.
763
+ rule could tell readers apart by. `source` refuses a `Derived.exists` as
764
+ shared: it is each reader's own.
626
765
 
627
766
  A hub is an in-memory fan-out, so whatever calls `changed` must be able to wake
628
767
  the subscriber's fiber. In a worker it cannot: one request cannot wake another's
629
768
  stream, so a hub fed from a second request delivers nothing and tears the first
630
- stream down (see `AGENTS.md`). On Workers, poll the shared store from inside the
631
- subscriber's own request instead — `examples/cloudflare` has the shape. A hub is
632
- right for a long-lived server process that owns both sides.
769
+ stream down: the open response belongs to the request that opened it, and the
770
+ Workers runtime cancels it when another request wakes it. On Workers, poll the
771
+ shared store from inside the subscriber's own request instead, as `pollLive`
772
+ does. A hub is right for a long-lived server process that owns both sides.
633
773
 
634
774
  A hand-written live Source and a hub number their events independently. Use one
635
775
  or the other for a given subscription path rather than mixing cursor domains.
@@ -688,7 +828,7 @@ A complete server definition is just the collection of Sources:
688
828
 
689
829
  ```ts
690
830
  const Server = RemoteServer.make({
691
- entities: [ProjectSource, UserSource],
831
+ entities: [ProjectSource],
692
832
  queries: [ProjectsByOwnerSource],
693
833
  mutations: [RenameProjectSource],
694
834
  live: [ProjectLive],
@@ -700,7 +840,7 @@ Source names at startup:
700
840
 
701
841
  ```ts
702
842
  const Data = Remote.define({
703
- entities: [Project, User],
843
+ entities: [Project],
704
844
  queries: [ProjectsByOwner],
705
845
  mutations: [RenameProject],
706
846
  })
@@ -711,6 +851,30 @@ RemoteServer.validate(Data, Server)
711
851
  That catches an Entity, Query, or Mutation Source whose name is not declared by
712
852
  the shared domain instead of letting it silently answer nothing at runtime.
713
853
 
854
+ `viewer` says who asks, as a row, and is the server's one answer to it:
855
+ `RemoteServer.make({ ..., viewer: principal => Option<{ entity, id }> })`. The
856
+ server hands it to every Source it mounts, with each read, query and live
857
+ subscription (`EntitySourceContext.viewer`), and to every write. A Source
858
+ answering a member per reader declares it (`perViewer`, as a `Derived.exists`
859
+ does), and a server with no `viewer` refuses that Source where it is made,
860
+ naming it. A query body's `Expr.viewer` and `Expr.now` read this viewer and the
861
+ server's Effect `Clock` (`exprContext`).
862
+
863
+ The viewer is also whom every answer says it is for. A read's, a list's and a
864
+ mutation's result carry `principal`: the viewer's key (`'User:ada'`), or
865
+ `null` for a visitor. The client treats it as opaque, stamps each durable
866
+ write it queues with it, and sends it back with every send of that write. The
867
+ handlers compare it with whom they answer as before the mutation's Source
868
+ runs: another person is refused with `RemotePrincipalChanged` (a 409 over
869
+ JSON), a visitor with `Unauthenticated`, and nothing runs, a ledger's replay
870
+ included, so a write resent after the cookie changed hands is never run, or
871
+ answered from its record, as someone else. A write that names `null` (made
872
+ with no one signed in) runs only for a visitor; asked by someone signed in it
873
+ is refused with `RemotePrincipalChanged`, unrun. A write that names no one
874
+ (made before any answer said who) runs as whoever asks.
875
+ A server with no `viewer` keeps no keys: its answers carry no `principal`, and
876
+ it refuses a write that names one, which it cannot check.
877
+
714
878
  Then compile it into handlers, once per principal, or once for every request
715
879
  with a Context key as the principal (see Authentication vs authorization):
716
880
 
@@ -763,18 +927,37 @@ The handler applies bounded, protocol-level safeguards before or around Sources:
763
927
 
764
928
  - a read batch may name at most `maxIdsPerEntity` distinct ids for one Entity
765
929
  (default `1000`); oversized client batches fail rather than loading unbounded
766
- rows;
930
+ rows. Remote's client cuts its batches to the same default, and to the
931
+ number given in `Remote.clientLayer(…, { maxIdsPerEntity })`;
932
+ - a request body may be at most `maxBodyBytes` (default 1 MiB) where bytes are
933
+ read: `serveFetch`'s option, and `bodyLimit` in front of an `RpcServer`
934
+ route. A larger one is a 413, `{ error, tooLarge: { limit } }`, refused by
935
+ its `content-length` before anything else, or cancelled the moment the bytes
936
+ read pass the limit, and never decoded;
767
937
  - nested resolution is bounded by `maxDepth` (default `8`);
768
938
  - the wire decoder also rejects a selection deeper than
769
939
  `MAX_RELATION_DEPTH` (`8`) or more than `MAX_FIELDS_PER_REQUEST` (`256`)
770
940
  fields for one Entity;
941
+ - a collection relation read with no window is the Source's to bound:
942
+ `foldkit-remote-drizzle`'s `source` reads at most `maxCollection` children
943
+ of one row (default 100) and refuses a read that finds more, rather than
944
+ answering a list cut short;
771
945
  - returned field names are copied with `Object.hasOwn` into null-prototype
772
946
  objects, so names such as `__proto__` or `toString` cannot reach prototypes;
773
947
  - Source errors are remapped to protocol error types without echoing application
774
948
  internals.
775
949
 
776
- A `liveHub` applies the same id bound to a subscription. A hand-written live
777
- Source is responsible for any additional bounds appropriate to its backend.
950
+ A live subscription is held to the same bounds, checked once by the handler
951
+ before any live Source or the hub sees it: more than `maxIdsPerEntity` ids of
952
+ one Entity (the `first` of each live list of it counted with them), or more
953
+ pages of one relation than a read may ask, fails the stream with
954
+ `RemoteLiveRefused` and nothing is read; more than `MAX_LIVE_QUERIES` (32) live
955
+ lists fails the wire decoder before that. That matters most for a polling
956
+ Source such as `pollLive`, which re-reads every subscribed row each tick. A
957
+ refusal is not truncation: the client does not reconnect it, and
958
+ `liveStatus(Data, …)` reads `Refused`. A hand-written live Source can rely on what
959
+ it is given having passed, and is responsible for any further bounds its
960
+ backend needs.
778
961
 
779
962
  ## A backend held in memory
780
963
 
@@ -788,10 +971,9 @@ is refused where the server is built.
788
971
 
789
972
  ```ts
790
973
  const backend = RemoteServer.memory({
791
- domain: Data, // or the definition from Remote.define
974
+ domain: Data, // the definition from Remote.define, or a domain from Remote.make
792
975
  rows: {
793
- User: [{ id: 'u1', name: 'Ada' }],
794
- Project: [{ id: 'p1', name: 'Apollo', status: 'active', owner: 'User:u1' }],
976
+ Project: [{ id: 'p1', name: 'Apollo', privateNotes: 'Internal' }],
795
977
  },
796
978
  // Optional: each mutation writes through the store, and the next read sees it.
797
979
  mutations: store => [
@@ -942,16 +1124,57 @@ const route = async (request: Request): Promise<Response> => {
942
1124
  call, of whatever kind, with `_tag: 'Unauthenticated'`.
943
1125
  - **403** with `{ error, forbidden: { reason? } }`: who is asking may not do
944
1126
  this (`RemoteServer.forbid`).
1127
+ - **409** with `{ error, refusal }`: a declared insert's id is already a
1128
+ row's, refused as `Refusal.taken`.
1129
+ - **409** with `{ error, principalChanged: {} }`: the write names someone
1130
+ other than who asks (`RemotePrincipalChanged`). Nothing ran. The client
1131
+ fails it with `_tag: 'PrincipalChanged'`, and the outbox keeps it waiting
1132
+ for them.
945
1133
  - **422** with `{ error, refusal }`: the mutation refused what was asked, in
946
1134
  its own `Refusal`.
947
1135
  - **500** with `{ error }`: the handler failed, and the message is its own;
948
1136
  or something on this side broke, and the message is `Internal error`,
949
- nothing more.
1137
+ nothing more. The cause is reported as a `ServerDefect`
1138
+ [diagnostic](#diagnostics), by default to the log, so a Worker's log
1139
+ (`wrangler tail`) shows what broke.
1140
+
1141
+ It never answers 408, 429, 502, 503 or 504. Remote's client reads a body
1142
+ under one of those, or one that is not JSON, as no answer at all
1143
+ (`Unreachable`): a proxy, gateway or rate limiter in front that answers one
1144
+ leaves the client unsure whether the write ran, and a durable write is sent
1145
+ again (see [A write sent again](#a-write-sent-again-operation)).
950
1146
 
951
1147
  It binds no principal: pass the `handlers` for the request's own,
952
1148
  established by your authentication, as everywhere else. It carries no live
953
1149
  data.
954
1150
 
1151
+ For an endpoint that serves `RemoteRpc` through Effect's own `RpcServer`,
1152
+ `bodyLimit(maxBytes)` is the same limit as HTTP middleware (Effect's
1153
+ `MaxBodySize` fails the RPC body read as a defect, a 500):
1154
+
1155
+ ```ts
1156
+ import { Layer } from 'effect'
1157
+ import { HttpRouter } from 'effect/http'
1158
+ import { RpcSerialization, RpcServer } from 'effect/rpc'
1159
+ import { RemoteRpc } from 'foldkit-remote'
1160
+ import { RemoteServer, bodyLimit } from 'foldkit-remote-server'
1161
+
1162
+ // `server` is your RemoteServer.make; answered as an anonymous principal here.
1163
+ const RpcRoutes = RpcServer.layer(RemoteRpc).pipe(
1164
+ Layer.provide(RemoteRpc.toLayer(RemoteServer.handlers(server, 'anonymous'))),
1165
+ Layer.provide(RpcServer.layerProtocolHttp({ path: '/rpc' })),
1166
+ Layer.provide(RpcSerialization.layerJson),
1167
+ Layer.provide(HttpRouter.middleware(bodyLimit(64 * 1024)).layer),
1168
+ )
1169
+ ```
1170
+
1171
+ The client reads that 413 as the call's own error, and a 401 or 403 from
1172
+ session middleware in front of the route as `Unauthenticated` or `Forbidden`,
1173
+ only over `Remote.rpcProtocolHttp(url)` in place of
1174
+ `RpcClient.layerProtocolHttp({ url })`, which reads the refusal as RPC frames
1175
+ and loses its status: a durable write would then read as unreachable and be
1176
+ sent again for good.
1177
+
955
1178
  ## Over fetch (Workers)
956
1179
 
957
1180
  `serveFetch` from `foldkit-remote-server/fetch` is that route as a value: a
@@ -964,6 +1187,7 @@ what `layer` provides (a session store, an auth service):
964
1187
  ```ts
965
1188
  import { serveFetch } from 'foldkit-remote-server/fetch'
966
1189
 
1190
+ // `server` is your RemoteServer.make; `databaseLayer` and `drizzle` provide what its Sources need.
967
1191
  export default {
968
1192
  fetch: serveFetch({
969
1193
  server,
@@ -974,8 +1198,18 @@ export default {
974
1198
  }
975
1199
  ```
976
1200
 
977
- Only `POST`s to `path` (default `/remote`) are answered; anything else is a 404. A body that is not JSON, or not a request, is a 400 that reaches no
978
- handler; a handler's failure a 500 with its message.
1201
+ Only `POST`s to `path` (default `/remote`) are answered; anything else is a
1202
+ 404. A body larger than `maxBodyBytes` (default 1 MiB) is a 413 with
1203
+ `{ error, tooLarge: { limit } }`: one whose `content-length` says so before
1204
+ the layer is built or the principal resolved, any other once the bytes read
1205
+ pass the limit, its stream cancelled there. Give the client the same number
1206
+ (`Remote.clientLayer(Remote.http('/remote'), { maxBodyBytes })`) and it cuts its
1207
+ reads to fit; `Remote.http` reads a 413 as the call's own error, so a durable
1208
+ write is not resent. A body that is not UTF-8 JSON, or not a request, is a 400
1209
+ that reaches no handler; a handler's failure a 500 with its message. Every response, refusals
1210
+ and errors included, says `cache-control: no-store` unless `headers` gives a
1211
+ `cache-control` of its own: each answer is one principal's rows (and `may`), so
1212
+ no shared cache may keep one.
979
1213
 
980
1214
  A resolver refuses the caller by failing with
981
1215
  `RemoteServer.unauthenticated(reason?)`: a 401 whose body is
@@ -1003,7 +1237,7 @@ A body that opens live (`{ operation: 'live', payload }`) is answered with
1003
1237
  the stream as `text/event-stream`: one `data:` frame per `LiveChange`, then
1004
1238
  a terminal `event: error` frame carrying the failure's message when the
1005
1239
  stream fails rather than ends. A payload no live stream speaks is a 400 that
1006
- subscribes to nothing. `Remote.httpWithLive` is the other end; a client that
1240
+ subscribes to nothing. `httpWithLive` (`foldkit-remote/live`) is the other end; a client that
1007
1241
  disconnects interrupts the subscription, as closing the RPC stream would.
1008
1242
 
1009
1243
  The stream moves on its own even when nothing changes: a `: ping` comment opens
@@ -1015,27 +1249,164 @@ the events it serves, so a stream with nothing to serve still ends.
1015
1249
  calls it must be able to wake the subscriber's fiber: in a worker, one request
1016
1250
  cannot wake another's stream, so a hub fed from a second request delivers
1017
1251
  nothing and ends the first stream. Poll the shared store from inside the
1018
- subscriber's own request instead — `examples/cloudflare`'s `pollLive` is the
1019
- shape. A hub is right for a long-lived process that owns both sides.
1252
+ subscriber's own request instead: `foldkit-remote-drizzle`'s `pollLive` does,
1253
+ with a trigger-kept row log (`rowChangeLog`, `rowLog`) so a quiet tick reads
1254
+ no rows. A hub is right for a long-lived process that owns both sides.
1255
+
1256
+ ### A page's reads, in the same process: `pageReader`
1257
+
1258
+ A Worker that renders pages reads what each page shows before rendering it
1259
+ (`Data.satisfy`), as the reader who asked. `pageReader` is that reader, made
1260
+ from the same config `serveFetch` takes: the request's `RemoteClient` as a
1261
+ Layer, answered by the server's own handlers with no HTTP in between. The
1262
+ server, its `layer` and its limits are the ones `/remote` answers with.
1263
+
1264
+ ```ts
1265
+ import { pageReader, serveFetch } from 'foldkit-remote-server/fetch'
1266
+
1267
+ const remote = { server, resolvePrincipal, layer: (env: Env) => databaseLayer(drizzle(env.DB)) }
1268
+ const served = serveFetch(remote)
1269
+ const reader = pageReader({ ...remote, resolvePrincipal: resolvePage })
1270
+
1271
+ export default {
1272
+ fetch: (request: Request, env: Env) =>
1273
+ new URL(request.url).pathname === '/remote'
1274
+ ? served(request, env)
1275
+ : pages.fetch(PageContext.attach(request, { reader: reader(request, env) })),
1276
+ }
1277
+ ```
1278
+
1279
+ `pages` is the fetch handler Foldkit's build emits, and `PageContext` an
1280
+ `SSR.requestContext` that carries the reader to `renderPage`
1281
+ ([`foldkit-ssr`](../ssr/README.md#what-the-host-hands-the-page-ssrrequestcontext)).
1282
+
1283
+ The resolver is the page's own: a page `GET` is a navigation, which carries
1284
+ no header a script adds, so a resolver that asks for one (Yielded's CSRF
1285
+ header) refuses it. With `foldkit-auth`, give
1286
+ `AuthServer.resolver({ …, requests: 'navigation' })`. When the reader is
1287
+ provided, the principal is resolved and `layer` built, and `layer` closes
1288
+ when that Effect ends, so provide it to the pre-read itself
1289
+ (`Data.satisfy(…).pipe(Effect.provide(reader))`). A refusal fails it with
1290
+ `Unauthenticated`, as a 401 would.
1291
+
1292
+ The reader only reads. A mutation fails with `RemoteMutationError` and a live
1293
+ open with `RemoteLiveError`: another site can start a navigation, so the
1294
+ principal it resolves must never write, and a render keeps no stream.
1295
+
1296
+ ## Diagnostics
1297
+
1298
+ A server answers some failures without telling the caller why. Each is a
1299
+ typed diagnostic, reported through `Diagnostics.Reporter` (`foldkit-surface`'s
1300
+ channel, re-exported by `foldkit-remote`), which by default is Effect's log:
1301
+
1302
+ | `_tag` | `level` | When |
1303
+ | --- | --- | --- |
1304
+ | `ServerDefect` | `error` | Something on this side broke (a layer, a resolver, a handler's defect) and the caller was answered `Internal error`; it carries the `cause`. |
1305
+ | `AnswerUnread` | `warning` | A mutation committed, but reading its answer failed: the client reads those rows again. |
1306
+ | `PublishFailed` | `error` | A mutation committed, but its live publish failed: live subscribers do not hear it. |
1307
+ | `ClockSkewed` | `warning` | A write's time was past `clockSkew` from the server's clock (a client clock that is off, or a durable write that waited), so the server wrote its own; it carries `sent`, `own` and `bound`. |
1308
+
1309
+ Provide another reporter as any service: `Layer.succeed(Diagnostics.Reporter,
1310
+ report)` in the layer the handlers run in. `serveFetch` takes one with the
1311
+ request beside it, used for everything that request runs, a broken layer
1312
+ included:
1313
+
1314
+ ```ts
1315
+ serveFetch({
1316
+ server,
1317
+ resolvePrincipal,
1318
+ layer: (env: Env) => databaseLayer(env),
1319
+ diagnostics: (diagnostic, request) =>
1320
+ Effect.logError(`${request.method} ${request.url}: ${diagnostic.message}`),
1321
+ })
1322
+ ```
1323
+
1324
+ In a test, `Diagnostics.collect()` gives a reporter and the array it fills.
1325
+
1326
+ ## Reference semantics: `evaluate` and the conformance suite
1327
+
1328
+ ### Running a query body over rows you already hold
1329
+
1330
+ A descriptor declared with
1331
+ [`Query.define`](../remote#queries-and-pagination) carries its meaning as a
1332
+ value (`body`), and `evaluate` runs a body directly:
1020
1333
 
1021
- ## What it does not own
1334
+ ```ts
1335
+ import { Entity, Expr, Order, Query, evaluate } from 'foldkit-entity'
1336
+
1337
+ const Post = Entity.define('Post', Schema.Struct({ id: Schema.String, slug: Schema.String }))
1338
+ const intro = Query.from(Post).pipe(
1339
+ Query.where(Expr.eq(Post.fields.slug, 'intro')),
1340
+ Query.orderBy(Order.asc(Post.fields.id)),
1341
+ )
1342
+
1343
+ evaluate(intro, {}, [{ id: 'p1', slug: 'intro' }, { id: 'p2', slug: 'outro' }])
1344
+ // [{ id: 'p1', slug: 'intro' }]: the matching rows, in the order the body asks for
1345
+ ```
1346
+
1347
+ It lives in [`foldkit-entity`](../entity), beside the IR it interprets, because
1348
+ it is that IR's reference semantics rather than anything this package does —
1349
+ and because a client judging rows it already holds needs it without depending on
1350
+ a server package. This package re-exports it, so importing it from either place
1351
+ means the same thing.
1352
+
1353
+ It is pure — it reads the rows it is given and nothing else — and it is the
1354
+ reference the compiled interpreters are checked against. `foldkit-remote-drizzle`
1355
+ turns the same body into SQL; the test suite runs both over the same rows in a
1356
+ real SQLite and Postgres and requires the same ids in the same order. That is
1357
+ what makes a body source-neutral in fact rather than in principle.
1358
+
1359
+ **It follows SQL, not JavaScript.** The case that matters is null: `null = null`
1360
+ is *unknown* in SQL and matches no row, where JavaScript would call the two
1361
+ equal. A comparison keeps a row only when it is true, so a null on either side
1362
+ drops it. Where an ordering puts null is the term's to say
1363
+ (`Order.asc(field, { nulls: 'first' })`); unsaid, it is Postgres's (last
1364
+ ascending, first descending), which the SQL compiler writes out for SQLite too.
1365
+
1366
+ What it refuses rather than guesses, each where the query runs:
1367
+
1368
+ - **Ordering by values it has no order for**, such as a number in one row and
1369
+ text in another, or by a backend's locale collation, which only that backend
1370
+ has. Every term is checked over every matched row before anything is sorted,
1371
+ so the refusal is the same on every engine, whichever pair a sort would have
1372
+ compared first. One matched row, or none, has nothing to order.
1373
+ - **NaN**, which SQLite stores as null and Postgres orders after every number.
1374
+ - **Text holding a NUL character** in a comparison or a search, which Postgres
1375
+ text cannot hold and SQLite's `like` stops at.
1376
+ - **A term with no context.** A body reading `Expr.viewer` or `Expr.now` is
1377
+ refused when run without them (`ContextMissingError`), never read as null.
1022
1378
 
1023
- `foldkit-remote-server` intentionally does **not** own:
1379
+ ### Checking an interpreter against the semantics
1024
1380
 
1025
- - HTTP/WebSocket transport or serialization;
1026
- - authentication protocol or session storage;
1027
- - a database connection;
1028
- - the client's normalized cache;
1029
- - client rendering or Surface activation;
1030
- - durable/offline client-authored state.
1381
+ `evaluate` is the reference, and `cases` (in `foldkit-entity/conformance`) is
1382
+ what it is a reference *to*: the conformance suite, exported so an interpreter
1383
+ written elsewhere can be held to the same semantics. Here `run` is your
1384
+ interpreter:
1385
+
1386
+ ```ts
1387
+ import { cases, rows } from 'foldkit-entity/conformance'
1388
+
1389
+ for (const { what, body, input, expected } of cases) {
1390
+ expect(run(body, input, rows).map(row => row.id), what).toEqual(expected)
1391
+ }
1392
+ ```
1031
1393
 
1032
- Those boundaries keep this package an interpreter of the Remote contract rather
1033
- than another application runtime.
1394
+ Every case is chosen to make interpreters **disagree**, which is the only kind
1395
+ that tests anything: mixed case, nulls on both sides of a comparison, `%` and
1396
+ `_` as literal text, the empty search, a predicate compared to a boolean either
1397
+ way round. That is not caution for its own sake — `contains` reached a released
1398
+ package meaning three different things because every value in the original
1399
+ fixture happened to be lowercase.
1400
+
1401
+ Both interpreters here run it: this package over rows in memory, and
1402
+ `foldkit-remote-drizzle` compiled to SQL against a real SQLite and Postgres.
1034
1403
 
1035
1404
  ## See also
1036
1405
 
1037
1406
  - [Server-derived state](../../docs/remote.md) — the client/server mental model
1038
1407
  and ownership rules.
1408
+ - [Errors and failures](../../docs/errors.md) — what a client is and is not
1409
+ told, beside the failures every other package owns.
1039
1410
  - [`foldkit-remote`](../remote) — requirements, normalized client Model,
1040
1411
  subscriptions, mutations, live reads, and retention.
1041
1412
  - [`foldkit-remote-drizzle`](../remote-drizzle) — compile Entity selections and