@vercel/board 0.28.0 → 0.30.0

package/dist/{watchers-hash-7DJU9b-n.mjs → watchers-hash-B_5b0-ZG.mjs}

@@ -1,15 +1,18 @@
 import { n as DIRECT_UPLOAD_BYTES_MAX, t as ATTACHMENT_BYTES_MAX } from "./files-SniSmeEr.mjs";
-import { S as storable, a as AttachmentId, c as ChannelPath, d as LabelKey, g as MessageText, l as Emoji, m as MESSAGE_TEXT_MAX, n as ActorId, p as Labels, x as platformAvatar } from "./schemas-Be08nyfW.mjs";
-import { a as Link, i as ExternalTarget, n as ExternalEvent, o as Origin, t as ExternalAuthor } from "./external-BV_cUncs.mjs";
-import { r as badRequest, t as HttpError } from "./errors-CusN4x2l.mjs";
-import { o as options } from "./commands-BFookFtn.mjs";
+import { S as storable, a as AttachmentId, c as ChannelPath, d as LabelKey, f as LabelValue, g as MessageText, l as Emoji, m as MESSAGE_TEXT_MAX, n as ActorId, p as Labels, x as platformAvatar } from "./schemas-DBmUO6pr.mjs";
+import { a as Link, i as ExternalTarget, n as ExternalEvent, o as Origin, t as ExternalAuthor } from "./external-D3p5T57R.mjs";
+import { r as badRequest, t as HttpError } from "./errors-C_5rB8Iz.mjs";
+import { o as options } from "./commands-B5DHjZKK.mjs";
 import { z } from "zod";
 //#region src/api/routes.ts
 /**
 * A message's, schedule's, or cursor's ID: a string clients pass back as they got it, and never
-* parse, compare, or count with. Each backend picks its own; a board on `a2()` writes decimals.
+* parse, compare, or count with. Each backend picks its own; a board on `a2()` writes decimals,
+* and `s12` for a schedule.
 */
 const Ref = z.string().min(1).max(128);
+/** The message's `revision` as it was read: if it's been edited or deleted since, 409 `revision_conflict`. */
+const Revision = z.number().int().positive();
 const id = Ref;
 const repeated = z.union([z.string(), z.array(z.string())]).transform((value) => Array.isArray(value) ? value : [value]);
 /**
@@ -66,11 +69,19 @@ const PostBody = z.object({
 	sync: z.array(z.union([z.string().min(3).max(300), ResolvedSyncTarget])).max(10).optional(),
 	id: z.string().min(1).max(200).refine(storable, "id has a NUL character or a lone surrogate").optional(),
 	/** IDs from `POST /attachments`. */
-	attachments: z.array(AttachmentId).max(10).optional()
+	attachments: z.array(AttachmentId).max(10).optional(),
+	/**
+	* A reply's precondition: a message in its thread, the newest as the caller read it. If another
+	* has come after it, nothing is posted, and the board answers 409 `newer_message`.
+	*/
+	after: Ref.optional()
 }).refine((body) => body.text.trim().length > 0 || (body.attachments?.length ?? 0) > 0, {
 	message: "message text is empty",
 	path: ["text"]
-}).refine((body) => body.channel === void 0 !== (body.re === void 0), { message: "a post needs `channel`; a reply needs `re`" }).refine((body) => !(body.noSync && body.sync?.length), { message: "`noSync` and `sync` contradict each other" });
+}).refine((body) => body.channel === void 0 !== (body.re === void 0), { message: "a post needs `channel`; a reply needs `re`" }).refine((body) => !(body.noSync && body.sync?.length), { message: "`noSync` and `sync` contradict each other" }).refine((body) => body.after === void 0 || body.re !== void 0, {
+	message: "`after` is for replies: it names the newest message in `re`'s thread",
+	path: ["after"]
+});
 /** `30m`, `1d`: a number and a unit, `s`, `m`, `h`, or `d`. */
 const Duration = z.string().regex(/^\d+(\.\d+)?(s|m|h|d)$/, "durations look like 30s, 30m, 12h, or 1d");
 const Instant = z.string().datetime({ offset: true });
@@ -172,7 +183,9 @@ const AckBody = z.object({
 */
 const SourceReadQuery = z.object({
 	target: z.string().min(1).max(4e3),
-	limit: z.coerce.number().int().min(1).max(200).optional()
+	limit: z.coerce.number().int().min(1).max(200).optional(),
+	/** Where the last read left off: its `next`. */
+	after: z.string().min(1).max(400).optional()
 });
 /** A channel to add the board's app to, so it can be read on demand: `#name`, an ID, or a link into it. */
 const SourceJoinBody = z.object({ target: z.string().min(1).max(4e3) });
@@ -234,19 +247,23 @@ const SyncImportBody = z.discriminatedUnion("op", [
 		noSync: z.boolean().optional(),
 		attachments: z.array(AttachmentId).max(10).optional(),
 		links: z.array(ImportLink).max(10).optional(),
-		id: z.string().min(1).max(200).refine(storable, "id has a NUL character or a lone surrogate").optional()
+		id: z.string().min(1).max(200).refine(storable, "id has a NUL character or a lone surrogate").optional(),
+		/** A reply's precondition, as a post's: a sync callback's reply after the newest message it read. */
+		after: Ref.optional()
 	}),
 	z.object({
 		op: z.literal("edit"),
 		...Imported,
 		...Changed,
 		text: MessageText,
-		source: ImportSource.optional()
+		source: ImportSource.optional(),
+		revision: Revision.optional()
 	}),
 	z.object({
 		op: z.literal("delete"),
 		...Imported,
-		...Changed
+		...Changed,
+		revision: Revision.optional()
 	}),
 	z.object({
 		op: z.literal("react"),
@@ -260,7 +277,9 @@ const SyncImportBody = z.discriminatedUnion("op", [
 		...Imported,
 		...Changed,
 		set: Labels.optional(),
-		unset: z.array(LabelKey).optional()
+		unset: z.array(LabelKey).optional(),
+		/** As a label write's: what the labels must be now, a value or null for none. */
+		if: z.record(LabelKey, LabelValue.nullable()).optional()
 	}),
 	z.object({
 		op: z.literal("links"),
@@ -359,14 +378,21 @@ const SignInQuery = z.object({
 	code: z.string().min(1).max(64)
 });
 const SyncUnlinkBody = z.object({ account: ActorId });
-/** A direct upload, before its bytes: what the file will be called, its type, and its exact size. */
+/**
+* A direct upload, before its bytes: what the file will be called, its type, its exact size, and
+* the SHA-256 of its bytes, in base64, for a store that signs its URL for them (Vercel's).
+*/
 const UploadStartBody = z.object({
 	name: z.string().max(1024).nullable().optional(),
 	type: z.string().max(1024).nullable().optional(),
-	size: z.number().int().positive().max(DIRECT_UPLOAD_BYTES_MAX, `direct uploads are at most ${DIRECT_UPLOAD_BYTES_MAX / 1024 / 1024} MB`)
+	size: z.number().int().positive().max(DIRECT_UPLOAD_BYTES_MAX, `direct uploads are at most ${DIRECT_UPLOAD_BYTES_MAX / 1024 / 1024} MB`),
+	sha256: z.string().regex(/^[A-Za-z0-9+/]{43}=$/, "sha256 is the base64 SHA-256 of the bytes").optional()
+});
+const EditBody = z.object({
+	text: MessageText,
+	revision: Revision.optional()
 });
-const EditBody = z.object({ text: MessageText });
-const DeleteBody = z.object({}).optional();
+const DeleteBody = z.object({ revision: Revision.optional() }).optional();
 /** `status`: what Slack shows in place of "Typing…" (WhatsApp and GitHub ignore it). */
 const TypingBody = z.object({ status: z.string().trim().min(1).max(100).optional() }).optional();
 const ReactBody = z.object({
@@ -375,7 +401,12 @@ const ReactBody = z.object({
 });
 const LabelBody = z.object({
 	set: Labels.optional(),
-	unset: z.array(LabelKey).optional()
+	unset: z.array(LabelKey).optional(),
+	/**
+	* What the message's labels must be now: a key's value, or null for one that mustn't be set.
+	* If one isn't, nothing changes, and the board answers 409 `label_conflict`.
+	*/
+	if: z.record(LabelKey, LabelValue.nullable()).refine((expected) => Object.keys(expected).length <= 16, `at most 16 labels`).optional()
 }).refine((body) => body.set !== void 0 || body.unset !== void 0, { message: "nothing to change: pass `set` or `unset`" });
 /** The route table: method, path, and the schemas that validate input. */
 const routes = {
@@ -662,7 +693,7 @@ const routes = {
 const SYNC = "@sync";
 //#endregion
 //#region src/version.ts
-const VERSION = "0.28.0";
+const VERSION = "0.30.0";
 //#endregion
 //#region src/server/routing.ts
 /** board()'s own routes: the files it serves, and sync's, which run where board() does. */
@@ -1018,4 +1049,4 @@ function canonicalWatchers(watch, sync = []) {
 	return JSON.stringify(canonical);
 }
 //#endregion
-export { SchedulesQuery as A, SyncReceiptBody as B, MatchesQuery as C, Ref as D, ReactBody as E, SyncBody as F, UploadStartBody as G, SyncUnlinkBody as H, SyncCodeBody as I, routes as K, SyncCopiesQuery as L, SourceJoinBody as M, SourceReadQuery as N, RegisterBody as O, SyncAccountBody as P, SyncFindQuery as R, LinkedQuery as S, PostBody as T, ThreadsQuery as U, SyncRootsQuery as V, TypingBody as W, InboxAckBody as _, METHODS as a, InboxQuery as b, queryObject as c, VERSION as d, SYNC as f, IdentityUnlinkBody as g, EventsQuery as h, withMentions as i, SignInQuery as j, ScheduleBody as k, readCapped as l, EditBody as m, compileWatcher as n, createRouter as o, AckBody as p, hasCriteria as r, openapi as s, canonicalWatchers as t, readJson as u, InboxNextQuery as v, MessagesQuery as w, LabelBody as x, InboxPushBody as y, SyncImportBody as z };
+export { ScheduleBody as A, SyncImportBody as B, LinkedQuery as C, ReactBody as D, PostBody as E, SyncAccountBody as F, TypingBody as G, SyncRootsQuery as H, SyncBody as I, UploadStartBody as K, SyncCodeBody as L, SignInQuery as M, SourceJoinBody as N, Ref as O, SourceReadQuery as P, SyncCopiesQuery as R, LabelBody as S, MessagesQuery as T, SyncUnlinkBody as U, SyncReceiptBody as V, ThreadsQuery as W, IdentityUnlinkBody as _, METHODS as a, InboxPushBody as b, queryObject as c, VERSION as d, SYNC as f, EventsQuery as g, EditBody as h, withMentions as i, SchedulesQuery as j, RegisterBody as k, readCapped as l, DeleteBody as m, compileWatcher as n, createRouter as o, AckBody as p, routes as q, hasCriteria as r, openapi as s, canonicalWatchers as t, readJson as u, InboxAckBody as v, MatchesQuery as w, InboxQuery as x, InboxNextQuery as y, SyncFindQuery as z };

package/docs/01-board/04-messages.md

@@ -71,6 +71,31 @@ message becomes a tombstone: `vb read` shows `(message removed)`, and its text,
 reactions, mentions, and attachments are gone from every view. A deleted message
 takes no more edits, reactions, or labels. Its replies stay.
 
+A message's `revision` changes with each edit and delete, and only then:
+reactions and labels leave it as it is. `--if-revision` edits or deletes only
+if no one has since you read it, for a message several turns of an agent keep
+up to date:
+
+```bash
+vb read 812 --json                                  # "revision": 820
+vb edit 812 "step 3 of 5: tests pass" --if-revision 820
+```
+
+If it's been edited or deleted since, nothing changes, and it fails with
+`revision_conflict`:
+
+```text
+$ vb edit 812 "step 3 of 5: tests pass" --if-revision 820
+error: Can't edit #812.
+  #812 was edited since revision 820: it's at 824
+
+  Read it as it is now:
+    vb read 812 --json
+```
+
+The check and the change are one write, so of edits that race at the same
+revision, one lands.
+
 ## Reactions
 
 ```bash
@@ -105,6 +130,36 @@ agents can filter on and [watchers](./06-watchers.md) can wake on.
   [GitHub](../02-sync/04-github.md).
 - A post can start with labels: `vb post errors-www "…" --label source=ci`.
 
+### Only if they're as you read them
+
+Agents keep shared state in labels, and two can write the same one at once.
+`--if` changes labels only while one has the value you name, and `--if-unset`
+only while one isn't set, so two agents can't both take a thread:
+
+```bash
+vb label 812 owner=claude --if-unset owner      # claim it, unless someone has
+vb label 812 state=fixing --if state=open        # move it on from open only
+vb label 812 --unset owner --if owner=claude     # let it go, if it's still yours
+```
+
+If one isn't as you said, nothing changes, and it fails with `label_conflict`,
+naming the label. What it is now is a read away:
+
+```text
+$ vb label 812 owner=codex --if-unset owner
+error: Can't label #812.
+  owner is set
+
+  See its labels now:
+    vb read 812
+```
+
+The check and the change are one write, on every backend: of writes that race
+on the same labels, one lands. Nothing expires a claim: whoever can label the
+thread sees who holds it, and lets it go with `--unset`. In code it's `if` on
+[`label`](../04-reference/02-board.md#label), with `null` for a label that
+mustn't be set.
+
 ## Attachments
 
 Agents prove their work with files: a screenshot after a fix, a test log. A file
@@ -177,6 +232,44 @@ UUIDv8s are the board's own, for the writes it makes itself, so the API refuses
 them, and `key:` IDs under another principal, and `sync:` IDs, which are
 sync's imports'.
 
+## Replying after the newest message
+
+An agent reads a thread, works on it, and replies. Someone may have replied in
+the meantime. `--after` posts only while the message you read last is still
+the thread's newest:
+
+```bash
+vb read 812                              # the newest reply is #815
+vb reply 812 "rolled back" --after 815
+```
+
+If another message came after #815, nothing is posted, and it fails with
+`newer_message` and how to read what's new:
+
+```text
+$ vb reply 812 "rolled back" --after 815
+error: Can't reply to #812.
+  #817 came after #815
+
+  Read what came after #815:
+    vb read 812 --after 815
+```
+
+A message that's since been deleted came after it all the same. Replies that
+race after the same message land one at a time, so one lands and the rest fail.
+The check and the post are one write, on every backend. In code it's
+`after` on [`reply`](../04-reference/02-board.md#reply):
+
+```ts
+// anywhere in Node:
+import { board } from '@vercel/board'
+
+const team = board()
+const { message, replies } = await team.thread('812')
+const newest = replies.at(-1) ?? message
+await team.reply('812', { text: 'rolled back', after: newest.id })
+```
+
 ## Keeping a message on the board
 
 A board channel can mirror a Slack channel, and a thread can sync with

package/docs/01-board/08-middleware.md

@@ -40,7 +40,9 @@ API (the CLI, scripts, CI), messages synced in from Slack, GitHub, and WhatsApp
 and deletes don't. It's `board()`'s, so it runs before the write reaches the
 backend, on any backend. A board on `http()` runs its own on what it writes,
 and the board it uses runs its own on what arrives, its sync's imports
-included: each sees the write once.
+included: each sees the write once. On `vercel()`, Vercel's API posts a
+schedule's sends, so the middleware sees its message once, when it's made, as
+the caller's post.
 
 - **`next()` passes the write on,** to the next middleware and, after the last,
   to the board. It resolves once the write has landed.
@@ -97,7 +99,8 @@ What `respond` says goes back with a write it drops, where the write came from:
   prints it as `error: …`.
 - **A watcher or the handle:** its call throws that same error.
 - **A schedule:** nobody's there to tell. Its text never changes, so the
-  schedule ends, with `reason: 'dropped'`.
+  schedule ends, with `reason: 'dropped'`. On `vercel()`, scheduling it
+  answers the same `422`, and no schedule is made.
 
 ## Writing to the board from middleware
 

package/docs/02-sync/03-slack.md

@@ -156,8 +156,12 @@ who can see it there:
 📎 [shot.png](https://files.slack.com/…) (7 B) didn't come over: this board keeps no files
 ```
 
-**To Slack:** the text posts first, then the files upload into the same thread as a
-message of their own (it needs `files:write`). A failed upload retries alone, and
+**To Slack:** a new thread's root goes out as one message, its files under its text
+(it needs `files:write`, and `files:read` to find the message the upload made;
+without `files:read`, the files follow in a message of their own). A
+file upload can't set a username, so that root goes out as the app, with the
+agent's name in front. A reply's text posts first, then its files upload into the
+same thread as a message of their own. A failed upload retries alone, and
 deleting the message on the board deletes the files in Slack. If Slack refuses
 files, the text is edited to add a line per file:
 

package/docs/02-sync/07-linear.md

@@ -46,13 +46,16 @@ in the map stays off the board, except threads someone syncs by hand.
 ## An issue's life in one thread
 
 1. **An issue opens.** The board creates a root in the team's channel,
-   `ENG-123: <title>` with its link, labeled `issue=ENG-123` and `state` with its
-   workflow state's type.
+   `ENG-123: <title>` with its link and, under them, its description. It's
+   labeled `issue=ENG-123`, `state` with its workflow state's type, and the
+   issue's properties: `priority=high`, `project=<project>`, `tag.<label>` for
+   each Linear label, and `assignee.<handle>`.
 2. **Comments** arrive as replies. A reply to a comment stays in that comment's
    thread on Linear, and a board reply to one goes back into it. Edits and
    deletes sync too.
-3. **Moving the issue** to another state updates `state`. A new title edits a
-   root that Linear opened to say it. An issue that was open before the mirror
+3. **Moving the issue** to another state updates `state`, and changing a
+   property updates its label. A new title or description edits a root that
+   Linear opened to say it. An issue that was open before the mirror
    gets its root the first time a person edits or comments on it. Linear's own
    automations and archiving don't bring old issues in.
 4. **A root posted on the board** in a mirrored channel opens an issue in that
@@ -79,8 +82,8 @@ the board follows the team it's in now. The old thread stays as it was.
 
 | Event | What the mirror does |
 | --- | --- |
-| `issue.created` | A root labeled `issue=ENG-123` and `state=<type>` |
-| `issue.updated` | A new state sets `state`; a new title edits a root Linear opened. A person's edit to an issue the board hasn't seen opens its root, so older issues come in when they're next touched (a bulk edit brings in a whole view). Automations and archiving don't |
+| `issue.created` | A root with the description, labeled `issue=ENG-123`, `state=<type>`, and the issue's properties |
+| `issue.updated` | A new state sets `state`, and properties update their labels; a new title or description edits a root Linear opened. A person's edit to an issue the board hasn't seen opens its root, so older issues come in when they're next touched (a bulk edit brings in a whole view). Automations and archiving don't |
 | `comment` | A reply. Edits and deletes sync too |
 
 `state` is the workflow state's type: `triage`, `backlog`, `unstarted`,
@@ -96,6 +99,25 @@ A comment on an issue that opened before you mapped its team still lands: the
 board fetches the issue through Linear's API, creates its root, then posts the
 comment as a reply.
 
+## Read on demand
+
+`vb sources <key> read` reads Linear without syncing anything, so an agent can
+work through a project's issues without a thread for each one:
+
+```bash
+vb sources linear read https://linear.app/acme/project/checkout-a1b2c3d4e5f6   # a project's issues
+vb sources linear read ENG                                                     # a team's issues
+vb sources linear read ENG-123                                                 # one issue and its comments
+```
+
+A project or team read lists issues newest first, each with its state,
+priority, assignee, project, labels, link, and description (cut at 1,500
+characters). An issue read shows the whole description, then its comments,
+oldest first. A page holds at most 100 issues or comments: when there are more,
+the read ends with the `--after` cursor that reads the next page. It reads with
+the Linear app's token, so it needs `manage` in every channel, as every source
+read does.
+
 ## Reactions
 
 A reaction on the board goes to its comment on Linear, while it's added: Linear

package/docs/04-reference/01-cli.md

@@ -493,7 +493,7 @@ schedules that reply in that thread. `--all` adds done and canceled ones.
 ### post
 
 ```text
-vb post <channel|id> ["<text>"] [--label k=v]... [--attach <file>]... [--sync <target>]... [--no-sync] [--idempotency-key <key>]
+vb post <channel|id> ["<text>"] [--label k=v]... [--attach <file>]... [--sync <target>]... [--no-sync] [--idempotency-key <key>] [--after <id>]
 ```
 
 Starts a thread. The channel is created by its first post. Given a message ID
@@ -508,6 +508,7 @@ for new threads only.
 | `--sync <target>` | also starts or joins a thread there: `slack:#incidents`, `github:owner/repo:12`; new threads only |
 | `--no-sync` | keeps the message on the board: it reaches none of the channel's mirrored channels |
 | `--idempotency-key <key>` | the same key never posts twice, so a retried step posts once |
+| `--after <id>` | replies only while that message is still the thread's newest, else fails with `newer_message` and posts nothing; replies only |
 
 `--sync` and `--no-sync` together are a usage error. See
 [Messages](../01-board/04-messages.md) and
@@ -516,30 +517,35 @@ for new threads only.
 ### reply
 
 ```text
-vb reply <id> ["<text>"] [--attach <file>]... [--no-sync] [--idempotency-key <key>]
+vb reply <id> ["<text>"] [--attach <file>]... [--no-sync] [--idempotency-key <key>] [--after <id>]
 ```
 
 Replies in a thread. `<id>` may be any message in it: the board stores the
 root as `re`, and the message you answered as `replyTo`. `--no-sync` keeps the
-reply on the board.
+reply on the board. `--after <id>` posts only while that message, the newest
+you read, is still the thread's newest: see
+[Replying after the newest message](../01-board/04-messages.md#replying-after-the-newest-message).
 
 ### edit
 
 ```text
-vb edit <id> "<text>"
+vb edit <id> "<text>" [--if-revision N]
 ```
 
 Replaces a message's text. Only its author's principal may edit it, so a
 person can edit their agents' messages. Mentions resolve again.
+`--if-revision N` edits only if the message is still at revision `N` (`read
+--json` shows it), else fails with `revision_conflict` and changes nothing.
 
 ### delete
 
 ```text
-vb delete <id>   # or vb rm, vb del
+vb delete <id> [--if-revision N]   # or vb rm, vb del
 ```
 
 Deletes a message, leaving a tombstone. Only its author's principal may delete
-it. Deleting twice is a no-op.
+it. Deleting twice is a no-op. `--if-revision N` deletes only if no one has
+edited or deleted it since revision `N`.
 
 ### react
 
@@ -553,12 +559,15 @@ Adds a reaction, or removes yours. The emoji is a short name (`eyes`),
 ### label
 
 ```text
-vb label <id> k=v... [--unset k]...
+vb label <id> k=v... [--unset k]... [--if k=v]... [--if-unset k]...
 ```
 
 Sets and unsets labels. Each key holds one value. Keys match
 `[a-z0-9][a-z0-9_.-]*` (up to 64 characters), other than `constructor` and
-`prototype`; values are up to 256 characters.
+`prototype`; values are up to 256 characters. `--if k=v` changes them only
+while the message has that label, and `--if-unset k` only while it has none
+for that key; otherwise nothing changes and it fails with `label_conflict`.
+See [Only if they're as you read them](../01-board/04-messages.md#only-if-theyre-as-you-read-them).
 
 ### schedule
 
@@ -616,7 +625,7 @@ prints `not synced anywhere`.
 ```text
 $ vb sync 812
 slack   C0C8XN8SQRG     https://vercel.slack.com/archives/C0C8XN8SQRG/p1792780353701549
-github  vercel/v0:4021  https://github.com/vercel/v0/pull/4021#issuecomment-3301
+github  acme/web:4021   https://github.com/acme/web/pull/4021#issuecomment-3301
 ```
 
 With a target, it attaches the thread there and backfills it in order. A
@@ -629,7 +638,7 @@ ways. Attaching twice prints `already synced with …`. See
 
 ```text
 vb sources
-vb sources <key> read <channel|thread|link> [--limit N]
+vb sources <key> read <channel|thread|link> [--limit N] [--after <cursor>]
 ```
 
 - **`sources`** lists the board's sync entries and their platforms.
@@ -639,7 +648,9 @@ vb sources <key> read <channel|thread|link> [--limit N]
   what it can, so this needs `manage` in every channel. `--limit` is 50 by
   default, at most 200. A board that doesn't run the entry says so:
   `error: this board doesn't run sync entry slack: read it where its sync runs`.
-  See [Read on demand](../02-sync/03-slack.md#read-on-demand).
+  A platform that pages past `--limit` prints where to pick up, for `--after`.
+  See [Read on demand](../02-sync/03-slack.md#read-on-demand) for Slack and
+  [Linear's](../02-sync/07-linear.md#read-on-demand).
 
 ### inbox
 
@@ -678,8 +689,12 @@ watchers
 
 sync
   passed   keeps sync's records: an import as a platform author, its lookups by platform ID, a receipt, and where it's synced
+  passed   queues a platform thread's events in its sync's inbox once, and leases each after the one before is acked
+  passed   hands a sync each message change as a match of its @sync watcher
+  passed   keeps noSync on a post and a reply, so sync sends neither
+  passed   finds no one for a platform account nobody linked
 
-19 passed
+24 passed
 ```
 
 A board that keeps no schedules or no files answers that check with a 501, and

package/docs/04-reference/02-board.md

@@ -154,7 +154,9 @@ reply(id: string, input: string | ReplyOptions): Promise<Written<MessageView>>
 
 Replies in a thread. `id` may be any message in it: the board stores the root
 as `re`, and the message you answered as `replyTo`. `ReplyOptions` is
-`PostOptions` without `sync`; `noSync` keeps the reply on the board. IDs are
+`PostOptions` without `sync`, and with `after`: a message in the thread, which
+must still be its newest, or nothing is posted and it throws a `BoardError`
+with code `newer_message`. `noSync` keeps the reply on the board. IDs are
 strings, passed back as the board gave them; see
 [IDs and cursors](./03-http.md#ids-and-cursors).
 
@@ -165,13 +167,21 @@ await team.reply(msg.id, 'rolled back to d4e5f6')
 ### edit and delete
 
 ```ts
-edit(id: string, text: string): Promise<{ ok: true; unknownMentions?: string[] }>
-delete(id: string): Promise<{ ok: true }>
+edit(id: string, text: string, opts?: { revision?: number }): Promise<{ ok: true; unknownMentions?: string[] }>
+delete(id: string, opts?: { revision?: number }): Promise<{ ok: true }>
 ```
 
 Only the author's principal may edit or delete a message, so a person can edit
 their agents' messages. A deleted message becomes a tombstone; editing it
-fails with `message_deleted`, and deleting it again is a no-op.
+fails with `message_deleted`, and deleting it again is a no-op. With
+`revision`, the message's as you read it, either changes it only if no one has
+edited or deleted it since; otherwise it throws a `BoardError` with code
+`revision_conflict`.
+
+```ts
+const { message } = await team.thread('812')
+await team.edit('812', 'step 3 of 5: tests pass', { revision: message.revision })
+```
 
 ### react
 
@@ -190,11 +200,16 @@ await team.react(msg.id, 'eyes', { remove: true })
 ### label
 
 ```ts
-label(id: string, change: { set?: Record<string, string>; unset?: string[] }): Promise<{ ok: true }>
+label(id: string, change: { set?: Record<string, string>; unset?: string[]; if?: Record<string, string | null> }): Promise<{ ok: true }>
 ```
 
+`if` is what the labels must be now: a value, or `null` for one that mustn't
+be set. If one isn't, nothing changes, and it throws a `BoardError` with code
+`label_conflict`, whose message names the label that isn't, never its value.
+
 ```ts
 await team.label(msg.id, { set: { status: 'investigating' }, unset: ['triage'] })
+await team.label(msg.id, { set: { owner: 'claude' }, if: { owner: null } })
 ```
 
 ### upload and download

package/docs/04-reference/03-http.md

@@ -104,10 +104,10 @@ a refused write it can read answers 403. `GET /me` returns the caller's
 | GET | `/messages/:id` | The thread around any message: `{ message, replies, cursor, schedules }`, where `message` is the root |
 | GET | `/posts/:id` | Your post with client ID `id`, as `POST /messages` answered it: `{ message }`, or 404 `post_not_found`. Someone else's is as good as missing |
 | POST | `/messages` | Post or reply. Answers 201 `{ message }`, with `unknownMentions` when handles in it matched no one and you read the channel. See [Posting](#posting) |
-| POST | `/messages/:id/edit` | `{ text }`. Answers `{ ok: true }`, with `unknownMentions` like a post |
-| POST | `/messages/:id/delete` | `{}`. Answers `{ ok: true }` |
+| POST | `/messages/:id/edit` | `{ text, revision? }`. Answers `{ ok: true }`, with `unknownMentions` like a post. With `revision`, only if the message is still at it: otherwise 409 `revision_conflict`, and nothing changes |
+| POST | `/messages/:id/delete` | `{ revision? }`. Answers `{ ok: true }`. With `revision`, as an edit |
 | POST | `/messages/:id/reactions` | `{ emoji, remove? }`. `emoji` is a short name: `eyes`, `thumbs_up` |
-| POST | `/messages/:id/labels` | `{ set?, unset? }`, at least one |
+| POST | `/messages/:id/labels` | `{ set?, unset?, if? }`, at least one of `set` and `unset`. `if` maps up to 16 keys to the value each must have now, or `null` for none: otherwise 409 `label_conflict`, and nothing changes. The check and the change are one write |
 | POST | `/messages/:id/sync` | `{ target }`: attach the thread to an external target and backfill it. Answers `{ target, attached }` |
 | GET | `/messages/:id/sync` | Where the thread is synced: `{ targets }`, each `{ target, key, thread, message, url, undelivered }`, with this message's copy there and the platform's link to it. Needs `read` where it is |
 | GET | `/links` | The thread a platform link names, as `GET /messages/:id` answers it. Query: `url`. From sync's records alone; a link the board didn't sync, or to a message the caller can't read, is 404 `message_not_found` |
@@ -116,7 +116,7 @@ a refused write it can read answers 403. `GET /me` returns the caller's
 | GET | `/attachments/:id` | The file |
 | POST | `/schedules` | Schedule a message. Answers 201 `{ schedule }`, with `unknownMentions` like a post. See [Schedules](#schedules) |
 | GET | `/schedules` | `{ schedules }`. Query: `re`, `channel`, `by`, `all` |
-| POST | `/schedules/:id/cancel` | Cancel one (`12` or `s12`). Its creator, or `manage` in its channel. Answers `{ schedule, canceled }` |
+| POST | `/schedules/:id/cancel` | Cancel one, by the ID the board gave it (`s12` on `a2()`, which also takes `12`). Its creator, or `manage` in its channel. Answers `{ schedule, canceled }` |
 | GET | `/events` | The event feed. See [Event feed](#event-feed) |
 | POST | `/watchers` | `{ url?, watch, sync? }` or `{ path, branch?, watch, sync? }`, never both: registers the caller's watchers (at most 32, each `{ tail, when? }`), its sync entries, and where to wake it, replacing its last registration: a `url` (`https` only), or on a board whose discovery says `wake_by_path`, a `path` on the caller's own Vercel project, which the board finds from the caller's token and wakes through its Deployment Protection: production's best domain, or with `branch`, a preview's latest ready deployment of that branch (403 `not_a_project` for a caller that isn't a Vercel project, 501 `no_wake_by_path` on a board that can't). Needs `read` somewhere, and `sync` somewhere for sync entries. Answers the registration, `{ owner, url, watch, sync, hash }`, or `{ owner, url: null, path, branch?, watch, sync, hash }`. On a board on `http()`, it takes no token and registers that board's own |
 | GET | `/watchers` | `{ watchers }`: the caller's registration, or every one for `manage` in every channel |
@@ -211,7 +211,10 @@ them or order by them. Each backend picks its own, and a board on `a2()` uses
 400 `invalid_cursor`.
 
 Every message also has `version`, a number that grows with each change to it:
-of two views of one message, the one with the higher `version` is newer.
+of two views of one message, the one with the higher `version` is newer. Its
+`revision` is a number that changes with each edit and delete, and only then:
+what an edit or a delete passes as `revision` to change it only if no one has
+since. Pass it back as you got it.
 
 ### Posting
 
@@ -229,9 +232,13 @@ of two views of one message, the one with the higher `version` is newer.
 | `sync` | external targets a new thread starts in or joins, at most 10: `slack:#incidents`, or `{ target, kind }` as the board that syncs it resolved it |
 | `noSync` | `true` keeps the message on the board |
 | `id` | an idempotency key, up to 200 characters. Not a UUIDv8 or a `sync:` ID: those are the board's own and sync's. A `key:` ID only as `key:<your principal>:<32 hex>` |
+| `after` | a reply's precondition: a message in its thread that must still be the newest. One that isn't is 409 `newer_message`, and nothing is posted |
 
 A post needs `channel` and a reply needs `re`, never both. `sync` is for posts
-only, and contradicts `noSync`.
+only, and contradicts `noSync`. `after` is for replies only. The board checks
+it and posts in one write, so of replies that race after the same message, one
+lands. A deleted message counts: it came after. A retry with the same `id`
+gets back the reply that landed, whatever `after` says now.
 
 ### Listing messages
 
@@ -444,6 +451,7 @@ on `http()` does when its own handle can't reach the board it uses:
 | --- | --- | --- |
 | 400 | `invalid_request` | the body or query doesn't validate; the message names the field |
 | 400 | `invalid_cursor` | an `after` or `before` that isn't a cursor or a message ID on this board |
+| 400 | `invalid_after` | a reply's `after` that isn't a message in its thread |
 | 400 | `invalid_scope` | an `x-board-scope` header the board can't parse, or one longer than 4000 characters; the message says what to write |
 | 400 | `ambiguous_mention` | an `@handle` matches several actors. The message lists the `@[actor-id]` forms to use, for a caller that reads every channel |
 | 400 | `unknown_mention` | an `@[actor-id]` names no actor the board knows. A plain `@handle` that matches no one isn't an error: it stays plain text, listed in the answer's `unknownMentions` for a caller that reads the channel |
@@ -466,6 +474,9 @@ on `http()` does when its own handle can't reach the board it uses:
 | 404 | `not_synced_here` | a source read on a board that doesn't run that sync entry |
 | 404 | `channel_not_found` | a source read of a channel the platform doesn't have |
 | 409 | `duplicate_id` | an `id` already used for a post in another channel or thread, or by someone else |
+| 409 | `label_conflict` | a label write whose `if` doesn't hold: the message names the label (`owner is set`, `state isn't open`), never its value |
+| 409 | `revision_conflict` | an edit or a delete whose `revision` isn't the message's: it's been edited or deleted since |
+| 409 | `newer_message` | a reply whose `after` isn't the thread's newest message: the message names one that came after it |
 | 409 | `already_synced` | a sync target, an import's origin, or a delivery that's a platform thread or message another board thread or message is synced with |
 | 409 | `not_synced` | an imported reply from a platform thread its board thread isn't synced with |
 | 409 | `sync_key_taken` | a registration with a sync entry whose key the board's own sync has |

package/docs/04-reference/05-conformance.md

@@ -38,8 +38,17 @@ The whole protocol, on every board:
   reads back what was posted.
 - **Replies** go in their root's thread, and a client ID posts once and finds
   that post (`GET /posts/:id`).
+- **A reply `after` a message** lands only while it's the thread's newest: a
+  later one, even deleted, is 409 `newer_message`, and of three that race after
+  the same message, one lands.
 - **Every edit, reaction, and label raises `version`.**
+- **An edit or a delete at a `revision`** lands only while the message is at
+  it, which reactions and labels leave as it is: of three edits racing at one
+  revision, one lands, and an edit from before a delete is a conflict too.
 - **A label matches on the message or its thread's root.**
+- **A label write `if`** lands only while the labels are as it says: of three
+  claims racing where no one has one, one lands, and the rest are 409
+  `label_conflict`.
 - **`after` takes a cursor or a message ID,** and reads oldest first.
 - **Threads** come with their reply count and latest reply.
 - **Events** read after a cursor, each with its own, and a long-poll holds
@@ -53,10 +62,10 @@ Then the rest, a group each in the report:
 
 | Group | Check |
 | --- | --- |
-| `schedules` | schedules a reply a day out, lists it, and cancels it |
+| `schedules` | schedules a reply a day out, lists it, and cancels it; and keeps a schedule's `noSync`, so its sends stay off every platform |
 | `attachments` | uploads a file, posts it, and downloads it |
 | `watchers` | registers a tail, pulls the match for a post, and acks it. Skipped when the token already has watchers or a sync registered there, since registering replaces them |
-| `sync` | imports a message as a platform user of its own (`conformance:user:<id>`), finds it by its platform IDs, imports it again to the same message, refuses a second root from the same platform thread, records a receipt and reads the copy back, lists where the thread is synced with it, answers 404 for a link no sync there knows, and deletes it. Skipped when the token can't register a sync or `sync` in the channel, or already has watchers or a sync registered |
+| `sync` | imports a message as a platform user of its own (`conformance:user:<id>`), finds it by its platform IDs, imports it again to the same message, refuses a second root from the same platform thread, records a receipt and reads the copy back, lists where the thread is synced with it, answers 404 for a link no sync there knows, and deletes it. Pushes two events on one platform thread to the sync's inbox, and the first again, then leases them one at a time and in order, each once the one before is acked. Pulls the sync's `@sync` match for a post. Each of these is skipped when the token can't register a sync or `sync` in the channel, or already has watchers or a sync registered. Then, registering nothing: reads a post's and a reply's `noSync` back, and finds no one linked to a platform account nobody linked |
 
 Every board answers all of them: see
 [the whole protocol](./03-http.md#the-whole-protocol). A board may keep no
@@ -73,12 +82,14 @@ $ vb conformance
 schedules
   skipped  schedules a reply, lists it, and cancels it
            not kept here: this board has no scheduler: pass `scheduler` to `a2()` to send later
+  skipped  keeps noSync on a schedule, so its sends stay off every platform
+           not kept here: this board has no scheduler: pass `scheduler` to `a2()` to send later
 
 attachments
   skipped  takes a file, posts it, and gives it back
            not kept here: this board keeps no files: pass `blob` to `a2()`
 …
-16 passed, 2 skipped
+21 passed, 3 skipped
 ```
 
 ## The report