toiljs 0.0.115 → 0.0.117

package/docs/database/documents.md

@@ -1,277 +0,0 @@
-# Documents
-
-The **Documents** family is ToilDB's general-purpose record store: you keep a value under a key and look it up, update it, or delete it by that key. It is the family you will use most, and the one to reach for whenever the other six do not obviously fit.
-
-## What and why
-
-A **Documents collection** maps a `@data` key to a `@data` value: one value per key, which you can read, replace, and remove. Think users by user id, posts by post id, orders by order number. If you are storing "a thing with fields that I look up and update by its id," this is the family.
-
-Declare one by typing a `@collection` as `Documents<Key, Value>`:
-
-```ts
-@data
-class UserId {
-  id: string = '';
-  constructor(id: string = '') { this.id = id; }
-}
-
-@data
-class User {
-  id: string = '';
-  name: string = '';
-  email: string = '';
-  score: u64 = 0;
-}
-
-@database
-class AppDb {
-  @collection static users: Documents<UserId, User>;
-}
-```
-
-## The operations
-
-Here is every operation, its shape, and what it gives back. `K` is your key type, `V` your value type.
-
-| Operation | Signature | Returns | Use it to |
-| --- | --- | --- | --- |
-| `get` | `get(key: K): V \| null` | the value, or `null` if absent | read one record |
-| `require` | `require(key: K): V` | the value; **traps** if absent | read a record you are sure exists |
-| `getMany` | `getMany(keys: K[]): Array<V \| null>` | one entry per key, in order, each value or `null` | read several records in one call |
-| `exists` | `exists(key: K): bool` | `true` if the record is present | check presence without reading the value |
-| `create` | `create(key: K, value: V): bool` | `true` if inserted, `false` if the key was already taken | add a **new** record without overwriting |
-| `patch` | `patch(key: K, value: V): V` | the newly stored value; **traps** if the record is absent | replace an **existing** record's value |
-| `upsert` | `upsert(key: K, value: V): UpsertResult` | `UpsertResult.Created` or `.Updated`; `.Conflict` on a `@unique` collision (nothing written) | create **or** overwrite in one op (last-writer-wins) |
-| `enqueue` | `enqueue(key: K, value: V): bool` | `true` if applied, `false` if a concurrent write won first or the record is absent | a version-checked (compare-and-swap) overwrite of an existing record |
-| `delete` | `delete(key: K): void` | nothing (idempotent) | remove a record |
-| `getDelete` | `getDelete(key: K): V \| null` | the value that was there, or `null`; removes it atomically | consume a record exactly once |
-
-Which kind of function may call which operation is covered in [Setup](./setup.md#how-access-is-gated-query-action-and-friends). In short: reads (`get`, `getMany`, `exists`) work anywhere; writes (`create`, `patch`, `upsert`, `enqueue`, `delete`, `getDelete`) need an **Action** (a `@post` route or an `@action`).
-
-### Reading: `get`, `require`, `exists`, `getMany`
-
-`get` is the everyday read. It returns the value or `null`, so you handle "not found" explicitly:
-
-```ts
-const user = AppDb.users.get(new UserId('u_123'));
-if (user == null) {
-  return Response.notFound();
-}
-// user is a fully typed User here
-```
-
-`require` is `get` for the case where absence is a bug, not a normal outcome: it returns the value directly and traps (aborts the request) if the record is missing. Use it only when you have already guaranteed the record exists.
-
-`exists` answers "is there a record here?" without paying to decode the value. It is handy as a cheap precondition:
-
-```ts
-if (AppDb.users.exists(new UserId(name))) {
-  // username already registered, do not overwrite
-}
-```
-
-`getMany` reads several keys in a single operation. You hand it an array of keys; you get back an array the same length and in the same order, each entry either the value or `null` for a key that was absent. Reach for it instead of a loop of `get` calls when you already know the handful of keys you need.
-
-```ts
-const ids = [new UserId('a'), new UserId('b'), new UserId('c')];
-const found: Array<User | null> = AppDb.users.getMany(ids);
-// found[0] lines up with ids[0], and so on; each is a User or null
-```
-
-`getMany` is a **bounded batch of point reads**, not a scan: the number of keys you may pass is capped by the request budget, and it never walks the whole collection. There is no "get all records" operation on a request path, by design (an unbounded scan could fan out across a huge collection). If you need "the latest N of something," model it as [Events](./events.md) or precompute a [View](./views.md).
-
-### Writing: `create` vs `upsert` vs `patch` vs `enqueue`
-
-These four all put a value under a key, but they differ in one important way each. Choosing correctly is the heart of using this family.
-
-```mermaid
-flowchart TD
-    START["I want to write a record"] --> Q1{"Must this write fail if another<br/>request changed the record<br/>since I read it?"}
-    Q1 -->|"Yes, guard against a lost update"| ENQUEUE["enqueue<br/>(version-checked CAS;<br/>false = retry)"]
-    Q1 -->|"No, last write wins"| Q2{"Does the record<br/>already exist?"}
-    Q2 -->|"Must be new (never clobber)"| CREATE["create<br/>(false if the key is taken)"]
-    Q2 -->|"May or may not exist"| UPSERT["upsert<br/>(create-or-overwrite in one op)"]
-    Q2 -->|"Definitely exists"| PATCH["patch<br/>(overwrite; returns the value;<br/>traps if absent)"]
-```
-
-**`create` inserts a new record.** It only writes if the key is free. If the key already has a record, `create` does nothing and returns `false`. This is your tool for "sign up a new user" or "claim this order id," where accidentally overwriting an existing record would be a bug. Because every key is serialized at its home (see [eventual consistency](./README.md#eventual-consistency-in-plain-words)), `create` is race-safe: if two requests create the same key at the same instant, exactly one gets `true` and the other gets `false`.
-
-```ts
-const ok = AppDb.users.create(new UserId(input.id), input);
-if (!ok) {
-  return Response.text('that id is taken', 409);
-}
-```
-
-**`patch` overwrites an existing record** and returns the value now stored. The record **must already exist**: `patch` on a missing key traps (aborts the request), so create it first. Despite the name, `patch` replaces the whole value; there is no field-level partial update, so read the current value, change the fields you want, and patch the whole thing back:
-
-```ts
-const current = AppDb.users.get(new UserId('u_123'));
-if (current == null) return Response.notFound();
-current.score = current.score + 10;
-const saved: User = AppDb.users.patch(new UserId('u_123'), current);
-// saved is what is now stored
-```
-
-**`enqueue` is a version-checked overwrite (a compare-and-swap).** Like `patch`, it replaces the whole value of an **existing** record, but it does so *only if the record has not changed since you read it*. A **compare-and-swap** (CAS) is exactly that: "write my new value, but only if the current value is still the one I saw." It returns a `bool`: `true` means your write was applied; `false` means either a concurrent write changed the record first (someone else beat you to it) or the record is absent. A `false` is **not an error**; it is the signal to **re-read and try again**. This approach is called **optimistic concurrency**: rather than locking the record, you assume nobody else will touch it, and you simply re-run the update on the rare occasion someone did.
-
-Reach for `enqueue` when several requests may update the *same* record at once and you must not silently lose any of their changes. A plain `patch` cannot promise that: two overlapping patches clobber each other (the last writer wins and the earlier update just vanishes). The intended pattern for `enqueue` is always a read-modify-CAS **retry loop**:
-
-```ts
-const key = new UserId('u_123');
-for (let attempt = 0; attempt < 5; attempt++) {
-  const current = AppDb.users.get(key);      // 1. read the current value
-  if (current == null) return Response.notFound();
-  current.score = current.score + 10;        // 2. modify your copy
-  if (AppDb.users.enqueue(key, current)) {   // 3. try to commit it
-    return Response.text('ok');              //    true: applied, we are done
-  }
-  // false: someone wrote between our get and our enqueue.
-  // Loop: re-read the now-newer value and reapply the change on top of it.
-}
-return Response.text('too much contention, try again later', 409);
-```
-
-Because every retry re-reads the latest value, the two updates **compose** (both `+10`s land) instead of one silently overwriting the other. If you do not need this guard (only one writer touches the key, or last-write-wins is genuinely fine), a plain `patch` is simpler and also hands you the stored value back directly.
-
-**`upsert` creates the record or overwrites it, in one operation.** It is the "just store this value, I do not care whether a row was already there" call, and it is the right tool for a save that runs repeatedly (a profile edit, a settings blob) where the first save inserts and every later save replaces. It returns an `UpsertResult` telling you which happened:
-
-```ts
-const key = new UserId('u_123');
-const result = AppDb.users.upsert(key, user);
-// result is UpsertResult.Created (row was absent) or UpsertResult.Updated (overwrote)
-```
-
-Before `upsert`, that meant two operations, `create` then `patch`:
-
-```ts
-// the old two-op idiom - upsert replaces it
-if (!AppDb.users.create(key, user)) {
-  AppDb.users.patch(key, user);
-}
-```
-
-`upsert` collapses both into a single write, so the common "already exists" path costs one round trip instead of two.
-
-Like `patch`, it is a **last-writer-wins** overwrite, not a compare-and-swap: concurrent upserts never fail or retry, the later one simply wins. That makes it correct for writing a **whole value**, and wrong for a read-modify-write of accumulating state (a running total, a like count) where a concurrent write would be silently lost, use `enqueue`'s retry loop or a [Counter](./counters.md) there. On a collection with a `@unique` field, `upsert` returns `UpsertResult.Conflict` (and writes nothing) when the value's unique field is already held by a **different** record, the one case it cannot resolve by overwriting:
-
-```ts
-const outcome = AppDb.handles.upsert(key, profile);
-if (outcome == UpsertResult.Conflict) {
-  return Response.text('that handle is taken', 409);
-}
-```
-
-### Removing: `delete` and `getDelete`
-
-`delete` removes a record. It is **idempotent**: deleting a key that is already gone is not an error, it just does nothing. So you can call it without first checking that the record exists.
-
-```ts
-AppDb.users.delete(new UserId('u_123'));
-```
-
-`getDelete` is the atomic **fetch-and-remove**: in one indivisible step it reads the current value and deletes it, returning what it removed (or `null` if there was nothing). "Atomic" here means no other request can slip in between the read and the delete, so exactly one caller can ever receive a given value. That makes it the right tool for **consume-once** data: one-time login challenges, single-use invite codes, password-reset tokens. The PQ-auth demo uses it to consume a login challenge exactly once, so a challenge cannot be replayed:
-
-```ts
-const challenge = AppDb.challenges.getDelete(new ChallengeId(cid));
-if (challenge == null) return fail(); // unknown, already used, or expired
-// ...verify against challenge...
-```
-
-If two requests race to `getDelete` the same key, only one gets the value; the other gets `null`. That is the guarantee a plain `get` then `delete` cannot give you, because two racers could both `get` the value before either `delete`s it.
-
-## A full worked example: a small CRUD entity
-
-Putting it together, here is a complete `notes` resource: create, read, update, and delete, backed by a Documents collection.
-
-```ts
-import { Response, RouteContext } from 'toiljs/server/runtime';
-
-// ---- key + value ----
-@data
-class NoteId {
-  id: string = '';
-  constructor(id: string = '') { this.id = id; }
-}
-
-@data
-class Note {
-  id: string = '';
-  title: string = '';
-  body: string = '';
-  updatedAt: u64 = 0;
-}
-
-// ---- database ----
-@database
-class NotesDb {
-  @collection static notes: Documents<NoteId, Note>;
-}
-
-// ---- routes ----
-@rest('notes')
-class Notes {
-  // GET /notes/:id  -> read one (Query: read-only)
-  @get('/:id')
-  public read(ctx: RouteContext): Response {
-    const note = NotesDb.notes.get(new NoteId(ctx.param('id')));
-    if (note == null) return Response.notFound();
-    return Response.json(note.toJSON().toString());
-  }
-
-  // POST /notes  -> create a new one, refusing a duplicate id (Action: may write)
-  @post('/')
-  public create(input: Note): Response {
-    input.updatedAt = <u64>(Date.now() / 1000);
-    if (!NotesDb.notes.create(new NoteId(input.id), input)) {
-      return Response.text('id already exists', 409);
-    }
-    return Response.json(input.toJSON().toString());
-  }
-
-  // POST /notes/:id  -> overwrite an existing note (Action)
-  @post('/:id')
-  public update(input: Note, ctx: RouteContext): Response {
-    const key = new NoteId(ctx.param('id'));
-    if (!NotesDb.notes.exists(key)) return Response.notFound();
-    input.id = ctx.param('id');
-    input.updatedAt = <u64>(Date.now() / 1000);
-    const saved = NotesDb.notes.patch(key, input);
-    return Response.json(saved.toJSON().toString());
-  }
-
-  // POST /notes/:id/delete  -> remove one (Action)
-  @post('/:id/delete')
-  public remove(ctx: RouteContext): Response {
-    NotesDb.notes.delete(new NoteId(ctx.param('id')));
-    return Response.text('deleted');
-  }
-}
-```
-
-That is a complete persistent CRUD entity. Run it under `toiljs dev` and the notes survive across requests; deploy it and the same code stores them worldwide on the edge.
-
-## Consistency notes
-
-Documents follows ToilDB's general model (see [the overview](./README.md#eventual-consistency-in-plain-words)):
-
-- **Writes to one key are serialized at that key's home**, so `create` is race-safe and `patch`/`upsert`/`enqueue`/`getDelete` never corrupt a record under concurrency. `upsert` is last-writer-wins like `patch`: serialization means the writes do not tear, but the later one still overwrites the earlier, so it does not by itself prevent a lost update (use `enqueue` for that).
-- **Reads are eventually consistent across regions.** Right after a write, a read from a far-away region may briefly still see the old value (or, for a just-created record, not see it yet). The copies converge within moments.
-- Because `patch` replaces the whole value, two updates to *different* fields of the same record can clobber each other if they overlap (read-modify-write races). `enqueue`'s version check is exactly the guard against that: use the read-modify-CAS retry loop shown above so a lost update turns into a retry instead of silent data loss. If you find yourself contending on one hot record a lot, a counter or a set is often a better fit than a Documents value. See [Counters](./counters.md) and [Membership](./membership.md).
-
-## Gotchas
-
-- **`patch` requires an existing record.** Calling it on a missing key traps the request. Use `create` for new records, or `upsert` when the record may or may not exist yet.
-- **`patch` replaces the whole value.** There is no field-level merge; read, modify, and write back the full value.
-- **`enqueue` returning `false` is not a failure.** It means a concurrent write beat you to the record (or the record is absent), so re-read and retry in a loop; never ignore the return value or treat `false` as a hard error. `enqueue` also does not hand back the stored value; use `patch` when you want the value returned and last-write-wins is acceptable.
-- **`upsert` is last-writer-wins, not a merge.** It writes the whole value you pass, so it is for storing a complete value, not a read-modify-write of one field of a shared record. Two overlapping upserts do not error, but the earlier one is overwritten (lost). When several writers contend on one record and must not lose each other's changes, use `enqueue`'s retry loop or a [Counter](./counters.md).
-- **No "get all."** There is no scan on the request path. Use `getMany` for known keys, and [Events](./events.md) or a [View](./views.md) for "the latest N."
-- **`getDelete`, not `get` + `delete`, for consume-once.** Only `getDelete` guarantees exactly one caller receives the value.
-
-## Related
-
-- [ToilDB overview](./README.md): the seven families and how to choose.
-- [Setup](./setup.md): declaring the collection and which function kinds may write.
-- [Data types (`@data`)](../backend/data.md): keys and values.
-- [Counters](./counters.md): when you are really just counting.
-- [Events](./events.md) and [Views](./views.md): for "the latest N" and precomputed reads.

package/docs/database/events.md

@@ -1,307 +0,0 @@
-# Events (append-only logs)
-
-An `Events` collection is an **append-only log**: a growing list of immutable
-facts under a key. You add events to the end and read the newest ones back. You
-never edit or delete an event once it is written.
-
-## What and why
-
-An "append-only log" means exactly two things happen to it:
-
-1. You **append** a new event (it goes on the end).
-2. You **read** events back (newest first).
-
-That is it. There is no "update event 5" and no "delete event 3". Each event is a
-permanent record of something that happened: "Ada signed the guestbook", "order
-1234 was refunded", "user logged in from a new device".
-
-Use an `Events` log when you care about the **history**, not just the latest
-state:
-
-- **Activity feeds:** "what happened in this room, newest first".
-- **Audit trails:** a tamper-resistant record of every important action.
-- **Event sourcing:** treat the log as the source of truth and compute other
-  values (totals, summaries, leaderboards) from it.
-
-If you only ever need the *current* value of something (a user's profile, a
-shopping cart), use [Documents](./documents.md) instead. If you only need a
-running total (likes, page views), use a [Counter](./counters.md). Events are
-for keeping the full list of what happened.
-
-```mermaid
-flowchart LR
-  A["append(user, event)"] --> L[("Event log for user<br/>(oldest ... newest)")]
-  B["append(user, event)"] --> L
-  L --> R["latest(user, 20)<br/>returns newest 20"]
-```
-
-## The type
-
-An `Events` collection has two type parameters: the **key** (which log) and the
-**event** (what each entry stores).
-
-```ts
-Events<K, V>
-```
-
-- `K` is the key type: it picks *which* log you are appending to. One key, one
-  log. For a per-user activity feed, the key is the user id.
-- `V` is the event type: the shape of a single entry. Both `K` and `V` are
-  [`@data`](../concepts/types.md) classes so they can be stored as bytes.
-
-You declare it as a `@collection` field inside a `@database` class:
-
-```ts
-@data
-class UserKey {
-  id: string = '';
-  constructor(id: string = '') { this.id = id; }
-}
-
-@data
-class Activity {
-  action: string = '';   // 'login', 'post.create', 'comment', ...
-  detail: string = '';
-  at: u64 = 0;           // unix seconds
-}
-
-@database
-class FeedDb {
-  @collection static activity: Events<UserKey, Activity>;
-}
-```
-
-The field name (`activity`) names the collection; the class name (`FeedDb`) names
-the database. You reach the log through `FeedDb.activity`.
-
-## Operations
-
-There are three operations, exactly matching the [toilscript](../concepts/decorators.md)
-API. Their exact signatures:
-
-| Operation | Signature | What it does |
-| --- | --- | --- |
-| `append` | `append(key: K, event: V): void` | Add one event to the end of the log. |
-| `appendOnce` | `appendOnce(key: K, eventId: string, event: V): bool` | Add one event, but only if that `eventId` was never seen before. |
-| `latest` | `latest(key: K, limit: i32): V[]` | Read up to `limit` events, newest first. |
-| `since` | `since(key: K, limit: i32): V[]` | Read the NEXT batch of events past a `@derive`'s checkpoint, oldest first. For folding a growing log incrementally. |
-
-### `append`
-
-The everyday operation. It adds one event and returns nothing.
-
-```ts
-FeedDb.activity.append(
-  new UserKey('ada'),
-  new Activity('login', 'from Paris', now),
-);
-```
-
-`append` is a **write**, so you may call it from an action handler (`@post`,
-`@put`, `@patch`, `@del`) but not from a read-only `@get`. See
-[decorators](../concepts/decorators.md) for what each handler kind may do.
-
-### `appendOnce` (idempotent append)
-
-`appendOnce` adds an event **at most once** for a given id. "Idempotent" means
-running it more than once has the same effect as running it once: the extra calls
-change nothing.
-
-Why you want this: networks retry. A client (or another service) may send the
-same request twice because the first reply got lost. With plain `append`, that
-double-delivery writes the event twice. With `appendOnce`, you pass a stable
-`eventId` (a string you choose that is unique for that logical event), and the
-log records it only once.
-
-```ts
-// `orderId` uniquely identifies this order event. If the request is retried,
-// the second call is a no-op and the log still has exactly one entry.
-const first = FeedDb.activity.appendOnce(
-  new UserKey('ada'),
-  `order-refunded:${orderId}`,   // the idempotency id
-  new Activity('order.refund', orderId, now),
-);
-// first === true  -> this call appended the event
-// first === false -> a previous call already appended it; nothing happened now
-```
-
-The return value tells you which happened:
-
-- `true`: this call appended the event (it was the first with that id).
-- `false`: a call with the same id already appended it, so this was a no-op.
-
-Pick an `eventId` that is truly unique per event: an order id, a payment id, a
-message uuid. Do not reuse one id for two different events, or the second will be
-silently dropped as a "duplicate".
-
-### `latest`
-
-Reads the newest events back, up to a limit, newest first.
-
-```ts
-const recent = FeedDb.activity.latest(new UserKey('ada'), 20);
-// recent[0] is the most recent event, recent[1] the next, ...
-```
-
-`latest` is a **scan**: it can walk many rows. Scans are barred on the request
-path, so you **cannot** call `latest` from a `@get` or a `@post`. This is a
-deliberate guardrail: a log can grow without bound, and a per-request scan would
-get slower and more expensive as the log grows.
-
-Instead you scan the log **off** the request path, in a
-[`@derive`](../background/derive.md), and publish a small precomputed
-[View](./views.md) that your routes read cheaply. The next section shows the full
-pattern.
-
-### `since` (incremental read for a `@derive`)
-
-`latest` rescans the tail every time. For a log that grows without bound, that gets slower and slower. `since`
-reads only the events you have **not folded yet**: the next batch past a saved cursor, oldest first, up to a
-limit. It is how a [`@derive`](../background/derive.md) folds a huge log incrementally instead of rescanning
-it from the start on every change.
-
-You do not pass or manage the cursor. The host owns it: it seeds `since` from a durable checkpoint, advances
-it as it hands you events, and saves it after your fold's view publish lands. So you just loop until the
-batch is empty:
-
-```ts
-@derive
-rollup(): void {
-    const key = new StatsKey('global');
-    const view = StatsDb.summary.get(key) ?? new Summary();   // the running view
-    let batch = StatsDb.events.since(key, 500);
-    while (batch.length > 0) {                                 // drain in bounded batches
-        for (let i = 0; i < batch.length; i++) view.apply(batch[i]);
-        batch = StatsDb.events.since(key, 500);
-    }
-    StatsDb.summary.publish(key, view);
-}
-```
-
-Two rules:
-
-- **`@derive` or `@job` only.** Like `latest`, `since` is a scan, so it is barred on the request path (`@get`
-  / `@post`). Calling it there is rejected.
-- **Your fold must be idempotent per event.** A rare crash-recovery case (a "healed" event that arrives at an
-  older position) makes the host re-read the log from the start that one run, so applying an event twice must
-  not change the result. Use set-style updates (`view.byId[e.id] = e.value`), not blind accumulation
-  (`view.count += 1`). If your fold cannot be idempotent, use `latest` and recompute instead.
-
-`since` is the efficient path; `latest` (recompute) is the simple path. See [`@derive`](../background/derive.md)
-for the full picture.
-
-## Worked example: an activity feed
-
-Here is the whole loop: an action appends an event, a `@derive` folds the log
-into a view, and a `@get` serves the view.
-
-```ts
-import { Activity } from '../models/Activity';
-import { UserKey } from '../models/UserKey';
-import { FeedView } from '../models/FeedView';
-import { NewActivity } from '../models/NewActivity';
-
-@database
-class FeedDb {
-  // The source of truth: every activity, appended forever.
-  @collection static activity: Events<UserKey, Activity>;
-  // The precomputed snapshot the GET serves: the newest 20 activities.
-  @collection static feed: View<UserKey, FeedView>;
-
-  // A @derive runs OFF the request path, so it is allowed to scan the log
-  // (`latest`) and publish the view. The runtime runs it right after an append,
-  // so the view reflects the new event on the next read.
-  @derive
-  rebuild(): void {
-    const key = new UserKey('ada');           // (real code would loop per active user)
-    const view = new FeedView();
-    view.items = FeedDb.activity.latest(key, 20);
-    FeedDb.feed.publish(key, view);
-  }
-}
-
-@rest('feed')
-class Feed {
-  // GET reads the precomputed view: a single keyed read, NOT a scan.
-  @get('/')
-  public list(): FeedView {
-    const view = FeedDb.feed.get(new UserKey('ada'));
-    return view == null ? new FeedView() : view;
-  }
-
-  // POST appends one activity. The @derive republishes `feed` right after.
-  @post('/')
-  public record(input: NewActivity): FeedView {
-    const at = <u64>(Date.now() / 1000);
-    FeedDb.activity.append(new UserKey('ada'), new Activity(input.action, input.detail, at));
-    // We do NOT scan here (that would be barred). We just acknowledge; the GET
-    // serves the updated list from the view the derive rebuilds.
-    return new FeedView();
-  }
-}
-```
-
-The two `@data` models:
-
-```ts
-@data
-export class Activity {
-  action: string = '';
-  detail: string = '';
-  at: u64 = 0;
-}
-
-@data
-export class FeedView {
-  items: Activity[] = [];
-}
-```
-
-The key idea: the **log** is the durable history, and the **view** is a small,
-read-cheap snapshot derived from it. Reads hit the view; the log grows quietly in
-the background.
-
-## Ordering and consistency
-
-ToilDB is a **worldwide** database: your data lives in many regions at once. A
-few honest details about what that means for events:
-
-- **Ordering within a log is stable.** Each key (each log) has one "home" location
-  where appends are serialized and stamped with an increasing sequence number. So
-  `latest` always returns a consistent newest-first order for that key.
-- **`latest` is newest first.** Index `0` is the most recent event.
-- **Reads can lag slightly across regions.** An append is applied at the log's
-  home first, then copied out to other regions in the background (this is called
-  *asynchronous replication*, and the result is *eventual consistency*: given a
-  little time, every region converges to the same log). A read served from a far
-  region may briefly miss the very newest event. A `@derive` runs right after the
-  append that triggered it, so the view it publishes reflects that write.
-- **`appendOnce` dedups by your id.** The at-most-once guarantee is anchored to
-  the `eventId` you pass, so retries are safe even across a flaky network.
-- **A log grows without bound.** Appending never shrinks it. Keep events small,
-  and read them through a bounded `latest(key, N)` in a derive rather than trying
-  to hold the whole log in memory.
-
-## Gotchas
-
-- **You cannot read the log from a route.** `latest` is a scan and is only legal
-  in a `@derive` or a `@job`. If you try to call it from a `@get`/`@post`, the
-  compiler rejects it. Read a [View](./views.md) from your route instead.
-- **Events are immutable.** There is no "edit" or "delete an event". If a fact
-  changes, append a new event that records the change (for example, an
-  `order.refund` event, not an edit to the original `order.create`).
-- **Choose `eventId` carefully for `appendOnce`.** It must be unique per logical
-  event. Reusing an id drops the new event as a duplicate.
-- **Do not treat a counter as a log.** A [Counter](./counters.md) gives you a
-  running total but forgets the individual events. If you need the list, use
-  `Events`.
-
-## Related
-
-- [Documents](./documents.md): mutable, one value per key (edit in place).
-- [Counters](./counters.md): a single running total per key.
-- [Views](./views.md): the precomputed snapshot your routes read.
-- [`@derive`](../background/derive.md): folds an event log into a View, off the
-  request path.
-- [Data types (`@data`)](../concepts/types.md): how keys and events are stored.
-- [Decorators](../concepts/decorators.md): which handler kinds may append vs scan.