toiljs 0.0.85 → 0.0.87

package/docs/database/membership.md

@@ -0,0 +1,246 @@
+# Membership (sets and relationships)
+
+A `Membership` collection stores **sets**: unordered groups of members under a
+key. You add and remove members, ask whether a member is in the set, and list a
+set's members. It is the natural fit for many-to-many relationships like group
+members, followers, and tags.
+
+## What and why
+
+A "set" is a collection with no duplicates and no order: a member is either in it
+or not. `Membership` gives you one set per key. The key names the set; each member
+is one item in it.
+
+This maps directly onto **many-to-many relationships**, where each thing on one
+side can relate to many things on the other:
+
+- **Group members:** the key is a group id, the members are user ids.
+- **Followers:** the key is a user id, the members are the ids of their followers.
+- **Tags:** the key is an article id, the members are tag names.
+- **Access control:** the key is a resource id, the members are the users allowed
+  in.
+
+You could try to store these as an array field inside a [Document](./documents.md)
+(for example `group.memberIds: string[]`). That works for **small, rarely-changed**
+sets, but it has real limits:
+
+| | Array in a Document | `Membership` set |
+| --- | --- | --- |
+| Add/remove one member | Read the whole array, edit it, write it all back | One direct `add`/`remove`, no read-modify-write |
+| Concurrent edits | Two writers can clobber each other's array | Each `add`/`remove` is its own operation |
+| Big sets | The whole array is loaded on every read/write | Members are stored separately; you read a bounded page |
+| "Is X a member?" | Load the array and search it | One direct `contains` check |
+
+Rule of thumb: a **handful** of stable items (a user's two or three roles) is fine
+as an array in a Document. A set that **grows** or is **edited concurrently**
+(followers, group members, tags across many articles) should be a `Membership`.
+
+```mermaid
+flowchart LR
+  K["Group key: 'eng'"] --> S[("Membership set")]
+  S --> M1["ada"]
+  S --> M2["grace"]
+  S --> M3["linus"]
+```
+
+## The type
+
+```ts
+Membership<K, M>
+```
+
+- `K` is the key type: it picks *which* set. For group membership, the key is the
+  group id.
+- `M` is the member type: the shape of one member. For user membership, that is a
+  user id. Both are [`@data`](../concepts/types.md) classes.
+
+Declare it as a `@collection` field on a `@database` class:
+
+```ts
+@data
+class GroupKey {
+  group: string = '';
+  constructor(group: string = '') { this.group = group; }
+}
+
+@data
+class Member {
+  userId: string = '';
+  constructor(userId: string = '') { this.userId = userId; }
+}
+
+@database
+class GroupsDb {
+  @collection static members: Membership<GroupKey, Member>;
+}
+```
+
+## Operations
+
+Four operations, matching the toilscript API exactly. Exact signatures:
+
+| Operation | Signature | What it does |
+| --- | --- | --- |
+| `contains` | `contains(key: K, member: M): bool` | Is `member` in the set? |
+| `add` | `add(key: K, member: M): void` | Put `member` in the set (idempotent). |
+| `remove` | `remove(key: K, member: M): void` | Take `member` out of the set (idempotent). |
+| `list` | `list(key: K, limit: i32): M[]` | Up to `limit` members of the set. |
+
+### `contains`
+
+A direct membership check. It is a keyed read, so it is allowed from any handler,
+including a read-only `@get`.
+
+```ts
+if (GroupsDb.members.contains(new GroupKey('eng'), new Member('ada'))) {
+  // ada is in the 'eng' group
+}
+```
+
+### `add` and `remove`
+
+Both are **writes**, so you call them from an action handler (`@post`, `@put`,
+`@patch`, `@del`), not from a `@get`. Both are **idempotent**: "idempotent"
+means doing it again has no extra effect.
+
+- `add` on a member already in the set: no change, no error.
+- `remove` on a member not in the set: no change, no error.
+
+```ts
+GroupsDb.members.add(new GroupKey('eng'), new Member('ada'));     // ada joins
+GroupsDb.members.add(new GroupKey('eng'), new Member('ada'));     // no-op, still one 'ada'
+GroupsDb.members.remove(new GroupKey('eng'), new Member('linus')); // linus leaves (or no-op)
+```
+
+Because they are idempotent, you do not need to check `contains` before calling
+them. Just `add` to join and `remove` to leave.
+
+### `list`
+
+Returns up to `limit` members of a set.
+
+```ts
+const roster = GroupsDb.members.list(new GroupKey('eng'), 100);
+```
+
+`list` is a **scan** (it can walk many rows), so it is barred on the request
+path: you **cannot** call it from a `@get` or a `@post`. Like reading a whole
+event log, listing a whole set belongs off the request path, in a
+[`@derive`](../background/derive.md) or a `@job`, which publishes a
+[View](./views.md) your routes read. The [worked example](#worked-example-group-membership)
+below shows this.
+
+`list` returns up to `limit` members. A set can be larger than one page, so treat
+the result as "a bounded page of members", not necessarily "every member".
+
+## Worked example: group membership
+
+A user joins or leaves a group from a route; a derive lists the roster into a
+view; a route reads the view. Membership checks happen directly in the route.
+
+```ts
+import { GroupKey } from '../models/GroupKey';
+import { Member } from '../models/Member';
+import { Roster } from '../models/Roster';
+import { JoinRequest } from '../models/JoinRequest';
+
+@database
+class GroupsDb {
+  // The set: who is in each group.
+  @collection static members: Membership<GroupKey, Member>;
+  // A precomputed roster for the GET (listing is a scan, barred on routes).
+  @collection static roster: View<GroupKey, Roster>;
+
+  @derive
+  rebuild(): void {
+    const key = new GroupKey('eng');
+    const r = new Roster();
+    r.users = GroupsDb.members.list(key, 500); // scan, allowed in a derive
+    GroupsDb.roster.publish(key, r);
+  }
+}
+
+@rest('groups')
+class Groups {
+  // GET the roster from the view (a keyed read, not a scan).
+  @get('/eng')
+  public list(): Roster {
+    const r = GroupsDb.roster.get(new GroupKey('eng'));
+    return r == null ? new Roster() : r;
+  }
+
+  // Direct membership check: `contains` is a keyed read, legal in a GET.
+  @get('/eng/is-member')
+  public isMember(userId: string): bool {
+    return GroupsDb.members.contains(new GroupKey('eng'), new Member(userId));
+  }
+
+  // Join: `add` is idempotent, so joining twice is harmless.
+  @post('/eng/join')
+  public join(input: JoinRequest): bool {
+    GroupsDb.members.add(new GroupKey('eng'), new Member(input.userId));
+    return true; // the @derive rebuilds the roster view right after
+  }
+
+  // Leave: `remove` is idempotent, so leaving when not a member is harmless.
+  @post('/eng/leave')
+  public leave(input: JoinRequest): bool {
+    GroupsDb.members.remove(new GroupKey('eng'), new Member(input.userId));
+    return true;
+  }
+}
+```
+
+The models:
+
+```ts
+@data
+export class Member {
+  userId: string = '';
+}
+
+@data
+export class Roster {
+  users: Member[] = [];
+}
+```
+
+The split is the point: `contains`/`add`/`remove` act on a single member and are
+legal on the request path; `list` scans the whole set and lives in a derive that
+feeds a view.
+
+## Consistency
+
+- **Add and remove serialize at the set's home.** Each set key has one home
+  location where its writes are applied in order, so an `add` followed by a
+  `remove` of the same member lands in that order and the set ends up correct.
+- **Reads can lag slightly across regions.** ToilDB is worldwide. A change made
+  at a set's home is copied to other regions in the background (asynchronous
+  replication, giving eventual consistency: every region converges after a short
+  delay). A `contains` or a `list` served from a far region may briefly miss a
+  just-made change.
+- **`add`/`remove` are idempotent**, so retries are safe: re-adding an existing
+  member or re-removing an absent one does nothing.
+- **A set can grow without bound.** Adding never shrinks it. Read it through a
+  bounded `list(key, N)` in a derive, not all at once.
+
+## Gotchas
+
+- **You cannot `list` from a route.** `list` is a scan, legal only in a `@derive`
+  or `@job`. To show a roster on a page, publish it to a [View](./views.md) from a
+  derive and `get` that view in the route.
+- **`list` returns a bounded page.** A large set may have more members than your
+  `limit`. Do not assume the returned array is the entire set.
+- **Sets are unordered.** Do not rely on the order `list` returns members in.
+- **Use `Membership` for growth or concurrency.** A small, stable set is fine as
+  an array in a Document. Reach for `Membership` when the set grows, is edited
+  concurrently, or you frequently ask "is X a member?".
+
+## Related
+
+- [Documents](./documents.md): when a small array field is enough (and when it is
+  not).
+- [Views](./views.md): where a roster/list belongs so routes can read it cheaply.
+- [`@derive`](../background/derive.md): runs `list` off the request path.
+- [Data types (`@data`)](../concepts/types.md): how set keys and members are stored.
+- [Decorators](../concepts/decorators.md): which handler kinds may add/remove vs scan.

package/docs/database/setup.md

@@ -0,0 +1,155 @@
+# Declaring a database
+
+You set up ToilDB by **declaring** it in code: a `@database` class listing your collections, plus the `@data` key and value types those collections use. There is no schema file, no migration command, and no connection string.
+
+## What and why
+
+A **database declaration** tells toiljs three things at compile time: which collections exist, which family each one is, and what key and value types it stores. The compiler bakes that list into your server's WebAssembly, and both the dev server and the production edge read it back to set up your collections automatically. You declare; the platform provisions.
+
+Reach for this on day one: before you can read or write any data, you need a `@database` with at least one `@collection`.
+
+## How: the three pieces
+
+A working database is always these three pieces together.
+
+1. **`@data` key and value types.** Plain classes, tagged `@data`, that describe what you store.
+2. **A `@database` class** whose static fields are `@collection`s, each typed by a family.
+3. **A handler** (a `@rest` route or an RPC method) that reads and writes those collections.
+
+Here is a complete, minimal example: a store of users you look up by id.
+
+```ts
+// A @data key: how you address one user.
+@data
+class UserId {
+  id: string = '';
+  constructor(id: string = '') { this.id = id; }
+}
+
+// A @data value: what you store for each user.
+@data
+class User {
+  id: string = '';
+  name: string = '';
+  score: u64 = 0;
+}
+
+// The database declaration. Each @collection is one collection,
+// typed by its family (here, Documents) with <Key, Value>.
+@database
+class AppDb {
+  @collection static users: Documents<UserId, User>;
+}
+
+// A route that reads and writes the collection.
+@rest('users')
+class Users {
+  @get('/:id')
+  public getUser(ctx: RouteContext): User {
+    const user = AppDb.users.get(new UserId(ctx.param('id')));
+    return user == null ? new User() : user;
+  }
+
+  @post('/')
+  public createUser(input: User): User {
+    AppDb.users.create(new UserId(input.id), input);
+    return input;
+  }
+}
+```
+
+That is the whole setup. Run `toiljs dev` and `AppDb.users` works immediately.
+
+### The `@data` types
+
+Both the key and the value are `@data` classes. `@data` is what makes a class storable: the compiler synthesizes a binary codec (pack to bytes, unpack from bytes) so ToilDB can persist it. The rules that matter here:
+
+- **Give every field a default** (`= ''`, `= 0`, and so on). The decoder builds an empty instance and fills it, so it needs defaults.
+- **A value type must be default-constructible** (creatable with `new User()` and no arguments). Keys often add a convenience constructor, as `UserId` does above, so you can write `new UserId('abc')`.
+- Fields may be numbers (`u8`..`u256`, `i8`..`i256`, `f32`, `f64`), `bool`, `string`, another `@data` class, or an array of any of these.
+
+The full reference, including how the same type becomes a typed client type, is on the [data types page](../backend/data.md).
+
+### The `@database` class and `@collection` fields
+
+```ts
+@database
+class AppDb {
+  @collection static users: Documents<UserId, User>;
+  @collection static likes: Counter<UserId>;
+}
+```
+
+- `@database` marks the class as a database. You can have more than one `@database` class; each is a separate namespace of collections.
+- Each `@collection` is one collection. Declare it as a **`static`** field with **no initializer**: you write the type, and the compiler wires up the actual handle for you.
+- The field's **type is its family**: `Documents<K, V>`, `Counter<K>`, `Events<K, V>`, `Unique<K, V>`, `Membership<K, M>`, `Capacity<K>`, or `View<K, V>`. The compiler reads the family straight from this type, so getting it right here is how you pick a family (see [Choosing a family](./README.md#choosing-a-family-the-decision-guide)).
+
+You reach a collection through the class, statically: `AppDb.users.get(...)`, `AppDb.likes.add(...)`. There is nothing to instantiate.
+
+### Reaching collections from a handler
+
+Any backend function can read and write collections by referencing them on the database class. What that function is allowed to do depends on its **kind**, covered next.
+
+## How access is gated: `@query`, `@action`, and friends
+
+ToilDB will not let every function do everything. Each backend function runs as one **function kind**, and each kind is allowed a different slice of database operations. This is a safety rail: a read-only endpoint physically cannot write, and an expensive scan cannot run on the hot request path.
+
+You rarely write these decorators by hand, because routes get a sensible kind automatically:
+
+- A **`@get`** route (a safe, read-only HTTP method) runs as a **Query**.
+- A **`@post`** route (a mutating method) runs as an **Action**.
+- A plain RPC **`@remote`** method defaults to a **Query** (read-only) because it has no HTTP method to infer from. Tag it `@action` if it writes.
+
+You can override the default with `@query` or `@action` on the method when the automatic choice is wrong (for example, a `@get` that genuinely needs to write, though that is unusual).
+
+What each kind may do:
+
+| Kind | Set by | May do | May **not** do |
+| --- | --- | --- | --- |
+| **Query** | `@get`, plain `@remote`, or `@query` | Point reads: `get`, `getMany`, `exists`, `lookup`, `contains`, counter `get`, view `get`, capacity `available`. | Any write. Any scan. |
+| **Action** | `@post` or `@action` | Everything a Query can, plus bounded writes: `create`, `patch`, `delete`, `getDelete`, `enqueue`, `append`, `appendOnce`, counter `add`, membership `add`/`remove`, unique `claim`/`release`, capacity `reserve`/`confirm`/`cancel`. | Scans. Publishing a View. |
+| **Derive / Job** | `@derive` / `@job` (background work) | Reads including **scans** (`latest`, membership `list`), plus `publish` a View. | (Run off the request path; see below.) |
+
+Two rules trip people up, so they are worth stating plainly:
+
+- **Scans are barred from request handlers.** Reading "the newest N events" (`events.latest`) or "the members of this set" (`membership.list`) can fan out across many rows, so a `@get` or `@post` cannot call them. Do the scan in a `@derive` (a small function that recomputes a snapshot off the request path) and have the request read the snapshot. See [Views](./views.md) and [@derive](../background/derive.md).
+- **Only a `@derive` or `@job` may `publish` a View.** Requests read views; background work writes them.
+
+Both gates are enforced twice: the compiler rejects an illegal call at build time, and the edge rejects it again at runtime, so a hand-edited module cannot sneak past. For the decorator catalog, see [Decorators](../concepts/decorators.md).
+
+## No manual provisioning: how it actually gets set up
+
+You never create a table or run a migration. Here is the machinery, so the "it just works" is not a mystery.
+
+When toilscript compiles your backend, it scans every `@database` class and writes a small catalog into the `.wasm` file: for each collection, its name, its family, its key and value type names, and the value's schema version. This catalog rides *inside* the compiled module.
+
+Then, wherever your backend runs, the host reads that catalog once at startup and builds your collections to match:
+
+- Under **`toiljs dev`**, the host is an in-process, in-memory emulator. It reads the catalog and stands up all seven families in memory. This is a development store: single process, single tenant, and cleared when you restart. It exists so you can build and test against real ToilDB behavior with no services to run.
+- On the **Dacely edge**, the host is the real ToilDB, backed by a globally distributed ScyllaDB cluster. It reads the *same* catalog and serves the *same* operations, now durable and worldwide.
+
+Because both sides read the same catalog, **the same code runs unchanged in dev and in production.** There is no connection string to swap and no provisioning step to run.
+
+```mermaid
+flowchart TD
+    SRC["@database AppDb<br/>@collection static users: Documents...<br/>@data UserId / User"]
+    SRC -->|toilscript compile| WASM["server.wasm<br/>(with an embedded<br/>toildb catalog section)"]
+    WASM -->|toiljs dev reads the catalog| DEV["In-memory dev store<br/>(one process, cleared on restart)"]
+    WASM -->|edge reads the same catalog| EDGE[("ToilDB on the Dacely edge<br/>(ScyllaDB, worldwide, durable)")]
+```
+
+## Gotchas
+
+- **Declare collections as `static` fields with no initializer.** Do not try to `new` a collection or assign a handle yourself; the compiler owns that.
+- **Every `@data` field needs a default, and value types must be default-constructible.** A missing default fails to compile.
+- **Dev data is not durable.** The `toiljs dev` store lives in memory and resets on restart. Do not rely on it to persist across dev runs; that is what the edge is for.
+- **Changing a `@data` type is a format change.** Reordering fields or changing a field's type changes the stored layout. Add new fields at the end, and use a migration when you evolve a stored type. See [data types](../backend/data.md).
+- **Pick the family at the type.** The family is read from the collection's declared type, so `Counter<K>` versus `Documents<K, V>` is a real, load-bearing choice, not a hint. Revisit [Choosing a family](./README.md#choosing-a-family-the-decision-guide) if unsure.
+
+## Related
+
+- [ToilDB overview](./README.md): the seven families and how to choose.
+- [Documents](./documents.md): the general-purpose record family (a good first collection).
+- [Data types (`@data`)](../backend/data.md): keys, values, and the codec.
+- [Decorators](../concepts/decorators.md): `@database`, `@collection`, `@query`, `@action`, `@derive`.
+- [@derive](../background/derive.md): recompute snapshots and run scans off the request path.

package/docs/database/unique.md

@@ -0,0 +1,216 @@
+# Unique
+
+The **Unique** family enforces that a value is claimed by only one owner across the entire world. It is how you make usernames, email addresses, and URL slugs one-of-a-kind, safely, even when two people try to grab the same one at the same instant.
+
+## What and why
+
+A **Unique collection** maps a `@data` **claim key** (the thing that must be unique, like a username) to a `@data` **owner value** (who or what claimed it, like a user id). At any moment a claim key is either **unclaimed** or **owned by exactly one owner**. The family gives you three operations: look up who owns a key, claim a key, and release it.
+
+Reach for Unique whenever a value must be globally singular:
+
+- usernames or handles
+- email addresses
+- URL slugs or workspace names
+- any "reserve this name for me" scenario
+
+Why not just check a Documents record first? Because a check-then-write has a race: two requests can both check "is `alice` free?", both see yes, and both create it. Unique closes that gap. The claim is decided at the key's single **home** (see [consistency](./README.md#eventual-consistency-in-plain-words)), where claims are processed one at a time, so exactly one of the two racers wins.
+
+Declare one by typing a `@collection` as `Unique<ClaimKey, OwnerValue>`:
+
+```ts
+@data
+class Username {
+  name: string = '';
+  constructor(name: string = '') { this.name = name; }
+}
+
+@data
+class OwnerId {
+  userId: string = '';
+  constructor(userId: string = '') { this.userId = userId; }
+}
+
+@database
+class AppDb {
+  @collection static usernames: Unique<Username, OwnerId>;
+}
+```
+
+## The operations
+
+`K` is the claim-key type, `V` the owner value type.
+
+| Operation | Signature | Returns | Use it to |
+| --- | --- | --- | --- |
+| `lookup` | `lookup(key: K): V \| null` | the current owner, or `null` if unclaimed | find out who owns a name |
+| `claim` | `claim(key: K, value: V): ClaimResult<V>` | a `ClaimResult` (see below) | try to take a name for an owner |
+| `release` | `release(key: K, value: V): void` | nothing; **traps** if you are not the owner | give a name back |
+
+`lookup` is a read, so it works in any function. `claim` and `release` are writes, so they need an **Action** (a `@post` route or an `@action`); see [Setup](./setup.md#how-access-is-gated-query-action-and-friends).
+
+### `ClaimResult`
+
+`claim` returns a small object that tells you what happened:
+
+```ts
+class ClaimResult<V> {
+  claimed: bool;      // true if YOU own the key now
+  owner: V | null;    // when claimed is false, who owns it instead
+}
+```
+
+- **`claimed == true`**: you own the key. This covers both a fresh claim and an **idempotent re-claim**: if you claim a key you already own (same owner value), you still get `true`, so retrying a claim is safe. `owner` is `null` in this case.
+- **`claimed == false`**: someone else got there first. `owner` is their value, so you can tell the user "that name is taken."
+
+### `lookup`
+
+`lookup` just reads the current owner without changing anything:
+
+```ts
+const owner = AppDb.usernames.lookup(new Username('alice'));
+if (owner == null) {
+  // 'alice' is free
+} else {
+  // owner.userId currently holds 'alice'
+}
+```
+
+Note that `lookup` is subject to [eventual consistency](./README.md#eventual-consistency-in-plain-words): a claim made moments ago in another region may not show up in a far-away `lookup` yet. Do not use `lookup` as your uniqueness guard. `lookup` is for display ("this name is taken by ..."); the real guarantee comes from `claim`, which is decided at the home and cannot race.
+
+### `claim`
+
+`claim` is the operation that actually enforces uniqueness. You pass the key and the owner value:
+
+```ts
+const result = AppDb.usernames.claim(new Username('alice'), new OwnerId('u_123'));
+if (result.claimed) {
+  // 'alice' is now yours
+} else {
+  // taken; result.owner is the current owner
+}
+```
+
+Because claims are serialized at the key's home, this is race-safe. If two requests anywhere in the world call `claim('alice', ...)` at the same moment, the home applies them in order: the first gets `claimed: true`, the second gets `claimed: false` with the first as `owner`. There is no window where both win.
+
+### `release`
+
+`release` gives a claim back so the key becomes available again. Only the **current owner** may release: you pass both the key and the owner value, and if that value is not the current owner, `release` **traps** (aborts the request). This prevents one user from releasing another user's name.
+
+```ts
+AppDb.usernames.release(new Username('alice'), new OwnerId('u_123'));
+```
+
+Release when a name is being changed or an account is deleted, so the name returns to the pool.
+
+## The claim / release lifecycle
+
+A claim is a small state machine: unclaimed, owned, and back to unclaimed.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Unclaimed
+    Unclaimed --> Owned: claim(key, me) -> claimed: true
+    Owned --> Owned: claim(key, me) again -> claimed: true (idempotent)
+    Owned --> Owned: claim(key, someoneElse) -> claimed: false, owner: me
+    Owned --> Unclaimed: release(key, me)
+```
+
+The key insight: **claiming is the guard, releasing is cleanup.** You claim to reserve, you release to free. A claim that is never released stays owned forever (there is no automatic expiry; if you want time-limited holds, that is what the [Capacity](./capacity.md) family's TTL reservations are for).
+
+## Worked example: reserving a username on signup
+
+The safe signup pattern is: claim the username first, then create the account, and if creating the account fails, release the claim so the name is not stranded.
+
+```ts
+import { Response } from 'toiljs/server/runtime';
+
+@data
+class Username {
+  name: string = '';
+  constructor(name: string = '') { this.name = name; }
+}
+
+@data
+class OwnerId {
+  userId: string = '';
+  constructor(userId: string = '') { this.userId = userId; }
+}
+
+@data
+class UserId {
+  id: string = '';
+  constructor(id: string = '') { this.id = id; }
+}
+
+@data
+class User {
+  id: string = '';
+  username: string = '';
+}
+
+@data
+class SignupInput {
+  username: string = '';
+  userId: string = '';
+}
+
+@database
+class AppDb {
+  @collection static usernames: Unique<Username, OwnerId>;
+  @collection static users: Documents<UserId, User>;
+}
+
+@rest('signup')
+class Signup {
+  // POST /signup  (Action: may claim and write)
+  @post('/')
+  public signup(input: SignupInput): Response {
+    const owner = new OwnerId(input.userId);
+
+    // 1. Claim the username. This is the uniqueness guard.
+    const claim = AppDb.usernames.claim(new Username(input.username), owner);
+    if (!claim.claimed) {
+      return Response.text('username taken', 409);
+    }
+
+    // 2. Create the account. If this fails, undo the claim so the name is free.
+    const user = new User();
+    user.id = input.userId;
+    user.username = input.username;
+    if (!AppDb.users.create(new UserId(input.userId), user)) {
+      AppDb.usernames.release(new Username(input.username), owner);
+      return Response.text('could not create account', 409);
+    }
+
+    return Response.json(user.toJSON().toString());
+  }
+}
+```
+
+Two things make this correct:
+
+- **The claim happens before the account write**, so uniqueness is decided up front.
+- **The claim is released if the follow-up write fails**, so a failed signup does not permanently burn a username.
+
+Because `claim` is idempotent for the same owner, a client that retries the whole request after a network hiccup does not get a false "taken" error: the second `claim('alice', u_123)` returns `claimed: true` again.
+
+## Consistency notes
+
+- **`claim` and `release` are strongly consistent at the key's home.** Two callers can never both own the same key; the home serializes claims. This is the whole point of the family.
+- **`lookup` is eventually consistent.** It reads a possibly-nearby copy, so a very recent claim from elsewhere may not appear yet. Never gate uniqueness on `lookup`; gate it on the result of `claim`.
+- **Claims do not expire.** A claim stays until someone releases it. Use [Capacity](./capacity.md) if you need holds that auto-release after a timeout.
+
+## Gotchas
+
+- **Do not use `lookup` as the uniqueness check.** Its answer can be stale. Call `claim` and trust its `claimed` flag.
+- **Release on failure and on account deletion.** A claim you forget to release stays owned forever, quietly blocking that name.
+- **`release` traps for a non-owner.** Pass the correct owner value, or you abort the request. If you are not sure you own it, `lookup` first (for display) but expect `release` to enforce ownership regardless.
+- **The owner value is data you choose.** Store enough in it (a user id, say) to know who holds the claim, so you can display and release it later.
+
+## Related
+
+- [ToilDB overview](./README.md): the seven families and how to choose.
+- [Setup](./setup.md): declaring the collection and which function kinds may claim.
+- [Documents](./documents.md): the account record you create alongside a claim.
+- [Capacity](./capacity.md): time-limited holds that auto-release (a different kind of "reserve").
+- [Data types (`@data`)](../backend/data.md): the claim key and owner value.