@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/lib/board/rules.ts

@@ -1,6 +1,6 @@
 /**
  * The card lifecycle: every transition, as a pure function of the card, the
- * operation, who asked, the clock, and the board's other cards.
+ * operation, who asked, the clock, the board's other cards, and the board's limits.
  *
  * One table decides who may do what — the tool, the router, the page, and `team` all
  * route through {@link applyOp} — so a lane change cannot be reachable from one
@@ -8,41 +8,47 @@
  * ownership is advisory (the bus's path claims are the lock), and the store owns the
  * compare-and-set that makes a concurrent writer lose.
  *
+ * Two shapes of failure, and the difference matters. A refusal is `{ ok: false }` with
+ * the reason, and the caller returns the card untouched. A *no-op* is `{ ok: true,
+ * changed: false }`: the operation's preconditions already hold (claiming a card you
+ * already hold), so nothing is written and the revision does not move.
+ *
+ * {@link mayOp} is the same decision without writing it, which is what `team` asks
+ * before it sends a handoff: a dry run is a question — "would this be allowed" — not a
+ * mutation performed as a fake session.
+ *
  * The board index is a parameter rather than a lookup because three operations need a
  * *different* card: a claim or a move is refused while a dependency is unfinished, and
- * a drop is refused while somebody waits on the card. `lib/board/links.ts` answers
- * those questions; this module decides what to do with the answer.
- *
- * Two shapes of failure, and the difference matters. A refusal is `{ ok: false }`
- * with the reason, and the caller returns the card untouched. A *no-op* is
- * `{ ok: true, changed: false }`: the operation's preconditions already hold
- * (claiming a card you already hold), so nothing is written and the revision does
- * not move.
+ * a drop is refused while somebody waits on the card. `lib/board/links.ts` answers those
+ * questions; this module decides what to do with the answer. The board's settings — its WIP
+ * limits and the name its two signatures must carry — are one parameter for the same reason:
+ * the rule decides, the reader of `bytefly.json` supplies them.
  *
  * `add` is {@link createCard} rather than an operation, because it has no card to
- * transition — and because a card is born `todo` with no owner, which is the one
+ * transition — and because a card is born in `backlog` with no owner, which is the one
  * state the other operations never produce.
  */
 
+import type { ArtifactCheck } from "./artifact.ts";
+import { type Card, type CardBlock, CARD_VERSION, DEFAULT_PRIORITY, MAX_LOG, type Priority } from "./card.ts";
+import { type BoardConfig, DEFAULT_BOARD_CONFIG } from "./config.ts";
+import type { Lane } from "./lanes.ts";
+import type { BoardIndex } from "./links.ts";
 import {
-	type Card,
-	type CardOwner,
-	type CardStatus,
-	cardRef,
-	DEFAULT_PRIORITY,
-	dependsOf,
-	MAX_LOG,
-	MAX_NOTES,
-	normalizeBlockedBy,
-	normalizeNote,
-	normalizePathHints,
-	normalizePlanPath,
-	normalizePriority,
-	normalizeTitle,
-	type Priority,
-	priorityOf,
-} from "./card.ts";
-import { type BoardIndex, dependedOn, normalizeDepends, waitingOn } from "./links.ts";
+	approve,
+	archive,
+	assign,
+	claim,
+	contractOp,
+	drop,
+	edit,
+	move,
+	note,
+	offer,
+	reclaim,
+	release,
+	review,
+} from "./steps.ts";
 
 /** Who is attempting an operation: a session when it has one, and the label it is addressed by. */
 export interface Actor {
@@ -52,27 +58,45 @@ export interface Actor {
 
 /** One named mutation of one card. */
 export type CardOp =
+	/** Pull a backlog card into `plan`: the only way a card starts moving. */
 	| { kind: "claim" }
 	/**
-	 * Hand a card to `to`, and — from the page, which cannot message a peer — a note that
-	 * says so. `team assign` sends a handoff instead and passes none.
+	 * Hand a pool card to `to`: the owner is recorded and the card enters `plan`. A held card is
+	 * refused — `reclaim` is how it changes hands — and `team assign` sends the handoff, which
+	 * the state machine knows nothing about.
 	 */
-	| { kind: "assign"; to: Actor; note?: unknown }
+	| { kind: "assign"; to: Actor }
 	| { kind: "release" }
 	/**
-	 * Change lane. `blockedBy` says what a block waits on, and `landed` says which commit
-	 * closed a card: both are read only by the lane they belong to, and both are optional,
-	 * because a card may be blocked with nothing recorded and a `done` card may predate the
-	 * field or live outside a repository.
+	 * Change lane. `blockedBy` and `blocker` are what a block records, `landed` says which
+	 * commit closed a card, and `artifact` is the plan proof a card entering `execute` or
+	 * `done` carries: each is read only by the lanes that ask for it.
 	 */
-	| { kind: "move"; status: Exclude<CardStatus, "todo">; blockedBy?: unknown; landed?: { commit: string } }
-	// `text` and `path` are whatever the model sent: `card.ts` validates them, and the
-	// refusal it produces is the one the caller shows.
+	| {
+			kind: "move";
+			lane: Lane;
+			blockedBy?: unknown;
+			blocker?: unknown;
+			landed?: { commit: string };
+			artifact?: ArtifactCheck;
+	  }
+	// `text` and the contract fields are whatever the model sent: the modules that own
+	// them validate them, and the refusal they produce is the one the caller shows.
 	| { kind: "note"; text: unknown }
-	| { kind: "plan"; path: unknown }
+	/**
+	 * Write the contract and the plan it is executed against. `artifact` is what the caller
+	 * proved: a resolved, existing plan file, or the sentence refusing it. The state machine
+	 * decides — nothing here touches a filesystem — and a contract naming neither is refused,
+	 * so a caller cannot skip the check by omitting it.
+	 */
+	| { kind: "contract"; artifact?: ArtifactCheck; goal?: unknown; acceptance?: unknown; scopeOut?: unknown }
+	/** Read the contract and approve it: the lead, and never the card's holder; `text` is noted with the sign. */
+	| { kind: "approve"; text?: unknown }
+	/** Spot-check the finished work: the lead, in `execute`, and never the card's holder; `text` is noted with the sign. */
+	| { kind: "review"; text?: unknown }
 	// Every field but `kind` is optional, and an absent one is left as it was: the page
 	// sends the three it can show, and omitting a link must not clear it.
-	| { kind: "edit"; title: unknown; paths: unknown; priority: unknown; dependsOn: unknown }
+	| { kind: "edit"; title?: unknown; paths?: unknown; priority?: unknown; dependsOn?: unknown }
 	| { kind: "reclaim" }
 	/**
 	 * Record that the card was offered to the team: `team offer` broadcasts it on the bus
@@ -89,7 +113,10 @@ export type CardOp =
 /** What an operation did: the new card, or the reason it was refused. */
 export type OpResult = { ok: true; card: Card; changed: boolean } | { ok: false; error: string };
 
-/** A card's first state: `todo`, no owner, one note at most. */
+/** What one operation would write, or why it may not. */
+export type Prepared = { error: string } | { fields: Partial<Card> | null; changed: boolean };
+
+/** A card's first state: `backlog`, no owner, one note at most. */
 export function createCard(
 	id: string,
 	input: { title: string; paths: string[]; note?: string; priority?: Priority },
@@ -97,19 +124,19 @@ export function createCard(
 	now: number,
 ): Card {
 	return {
-		v: 1,
+		v: CARD_VERSION,
 		id,
 		title: input.title,
-		status: "todo",
+		lane: "backlog",
 		paths: [...input.paths],
 		// A new card says its priority out loud, even when it is the ordinary one, so a
 		// file on disk tells a reader the whole story without a default to know.
 		priority: input.priority ?? DEFAULT_PRIORITY,
 		notes: input.note === undefined ? [] : [{ by: actor.label, at: now, text: input.note }],
 		notesDropped: 0,
-		// A card is born in `todo`, and that is a transition like any other: a reader asking
-		// "how long has this been waiting" gets an answer rather than an absence.
-		log: [{ status: "todo", at: now, by: actor.label }],
+		// A card is born in `backlog`, and that is a transition like any other: a reader
+		// asking "how long has this been waiting" gets an answer rather than an absence.
+		log: [{ lane: "backlog", at: now, by: actor.label }],
 		logDropped: 0,
 		rev: 1,
 		createdAt: now,
@@ -119,17 +146,21 @@ export function createCard(
 }
 
 /**
- * Whether `actor` is the owner of `card`.
+ * Why `actor` may not apply `op` to `card`, or `undefined` when it may.
  *
- * The id decides when both sides have one — a session that renamed itself is still
- * the same holder — and the label decides otherwise, case-insensitively, the way
- * the bus resolves a target.
+ * The answer a dry run asks for: it computes everything a write would check and nothing
+ * a write would store, so `team` can find out whether a handoff is deliverable before it
+ * sends one.
  */
-export function holds(card: Card, actor: Actor): boolean {
-	const owner = card.owner;
-	if (owner === undefined) return false;
-	if (owner.id !== undefined && actor.id !== undefined) return owner.id === actor.id;
-	return owner.label.toLowerCase() === actor.label.toLowerCase();
+export function mayOp(
+	card: Card,
+	op: CardOp,
+	actor: Actor,
+	board: BoardIndex,
+	config: BoardConfig = DEFAULT_BOARD_CONFIG,
+): string | undefined {
+	const prepared = prepare(card, op, actor, 0, board, config);
+	return "error" in prepared ? prepared.error : undefined;
 }
 
 /**
@@ -138,151 +169,75 @@ export function holds(card: Card, actor: Actor): boolean {
  * A refused operation returns the reason and no card: the caller already holds the
  * card it read, and a "refused" copy of it would be a second version of the truth.
  */
-export function applyOp(card: Card, op: CardOp, actor: Actor, now: number, board: BoardIndex): OpResult {
+export function applyOp(
+	card: Card,
+	op: CardOp,
+	actor: Actor,
+	now: number,
+	board: BoardIndex,
+	config: BoardConfig = DEFAULT_BOARD_CONFIG,
+): OpResult {
+	const prepared = prepare(card, op, actor, now, board, config);
+	if ("error" in prepared) return { ok: false, error: prepared.error };
+	if (!prepared.changed) return { ok: true, card, changed: false };
+	// `archive` changes the pile a card's file lies in and no field at all, which is why
+	// its step has nothing to write and the store's move is the whole of the operation.
+	if (prepared.fields === null) return { ok: true, card, changed: true };
+	return { ok: true, card: write(card, actor, now, prepared.fields), changed: true };
+}
+
+/** The one place an operation becomes a write: each `step*` decides, this applies. */
+function prepare(card: Card, op: CardOp, actor: Actor, now: number, board: BoardIndex, config: BoardConfig): Prepared {
 	switch (op.kind) {
 		case "claim":
-			return claim(card, actor, now, board);
+			return claim(card, actor, board, config.wip);
 		case "assign":
-			return assign(card, op.to, op.note, actor, now, board);
+			return assign(card, op.to, board, config.wip);
 		case "release":
-			return release(card, actor, now);
+			return release(card, actor);
 		case "move":
-			return move(card, op, actor, now, board);
+			return move(card, op, actor, now, board, config);
 		case "note":
 			return note(card, op.text, actor, now);
-		case "plan":
-			return plan(card, op.path, actor, now);
+		case "contract":
+			return contractOp(card, op, actor);
+		case "approve":
+			return approve(card, actor, now, config, op.text);
+		case "review":
+			return review(card, actor, now, config, op.text);
 		case "edit":
-			return edit(card, op, actor, now, board);
+			return edit(card, op, actor, board);
 		case "reclaim":
-			return reclaim(card, actor, now);
+			return reclaim(card);
 		case "offer":
-			return offer(card, actor, now, board);
+			return offer(card, now, board, config.wip);
 		case "archive":
 			return archive(card);
 		case "drop":
 			return drop(card, actor, board);
+		default:
+			// A caller from an older build, or a hand-written fixture, names an operation this
+			// one does not know: that is a refusal, not a crash on `undefined`.
+			return { error: "unknown board operation." };
 	}
 }
 
-function claim(card: Card, actor: Actor, now: number, board: BoardIndex): OpResult {
-	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be claimed.` };
-	if (holds(card, actor)) return { ok: true, card, changed: false };
-	if (card.owner !== undefined) return { ok: false, error: heldBy(card) };
-	const waiting = waitingOn(card, board);
-	if (waiting !== undefined) return { ok: false, error: waiting };
-	return {
-		ok: true,
-		card: write(card, actor, now, { status: "doing", owner: ownerOf(actor), offeredAt: undefined }),
-		changed: true,
-	};
-}
-
-function assign(card: Card, to: Actor, rawNote: unknown, actor: Actor, now: number, board: BoardIndex): OpResult {
-	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be assigned.` };
-	if (card.owner !== undefined && !holds(card, to)) return { ok: false, error: heldBy(card) };
-	if (holds(card, to) && card.status === "doing") return { ok: true, card, changed: false };
-	const waiting = waitingOn(card, board);
-	if (waiting !== undefined) return { ok: false, error: waiting };
-	const fields: Partial<Card> = { status: "doing", owner: ownerOf(to), offeredAt: undefined };
-	if (rawNote !== undefined) {
-		const parsed = normalizeNote(rawNote);
-		if ("error" in parsed) return { ok: false, error: parsed.error };
-		// One revision, not two: the history says who it went to in the same write that
-		// recorded the owner, so a reader never sees the assignment without the sentence.
-		Object.assign(fields, appendNote(card, actor, now, parsed.text));
-	}
-	return { ok: true, card: write(card, actor, now, fields), changed: true };
-}
-
-function release(card: Card, actor: Actor, now: number): OpResult {
-	// Finished work is history: every other transition refuses it, and a release that did
-	// not would be the one way a `done` card could go backwards — reopening the order a
-	// dependency was recorded against.
-	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be released.` };
-	if (card.owner === undefined) return { ok: false, error: `${cardRef(card.id)} is not claimed.` };
-	if (!holds(card, actor)) return { ok: false, error: `${heldBy(card)} Release is the owner's decision.` };
-	return {
-		ok: true,
-		card: write(card, actor, now, { status: "todo", owner: undefined, offeredAt: undefined }),
-		changed: true,
-	};
-}
-
-function move(
-	card: Card,
-	op: Extract<CardOp, { kind: "move" }>,
-	actor: Actor,
-	now: number,
-	board: BoardIndex,
-): OpResult {
-	const status = op.status;
-	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be moved.` };
-	if (card.owner === undefined) {
-		return { ok: false, error: `${cardRef(card.id)} is unclaimed; claim it before moving it to ${status}.` };
-	}
-	if (!holds(card, actor)) return { ok: false, error: `${heldBy(card)} Only its owner can move it.` };
-	// A block's reason is checked before the no-op: a caller that repeats a move with a new
-	// sentence meant to change it, and a refusal is clearer than a silent nothing.
-	let blockedBy: string | undefined;
-	if (status === "blocked" && op.blockedBy !== undefined) {
-		const parsed = normalizeBlockedBy(op.blockedBy);
-		if ("error" in parsed) return { ok: false, error: parsed.error };
-		blockedBy = parsed.blockedBy;
-	}
-	if (card.status === status && blockedBy === undefined) return { ok: true, card, changed: false };
-	// Parking is what a link is for, so only the two lanes that put a card back in flight
-	// are gated: a card that waits may be blocked, it may not be taken or finished.
-	if (status !== "blocked") {
-		const waiting = waitingOn(card, board);
-		if (waiting !== undefined) return { ok: false, error: waiting };
-	}
-	return { ok: true, card: write(card, actor, now, laneFields(status, blockedBy, op, now)), changed: true };
-}
-
 /**
- * The fields one lane change writes.
+ * A card's log after one more transition, with the oldest dropped and counted.
  *
- * `blockedBy` belongs to `blocked` alone: a card that leaves for `doing` or `done` has
- * had its decision or stopped needing one, and a stale sentence would be read as a
- * current one. `landed` belongs to `done` alone, and only when the caller could name a
- * commit — a board outside git still finishes cards, it just cannot say with what.
+ * The block travels with the entry that parked the card, because the card's own `blocked`
+ * is deleted on the way out: without it the answer to "why did this sit for two days" dies
+ * with the resume, and the notes are the only other place it could have been written.
  */
-function laneFields(
-	status: Exclude<CardStatus, "todo">,
-	blockedBy: string | undefined,
-	op: Extract<CardOp, { kind: "move" }>,
+function appendTransition(
+	card: Card,
+	lane: Lane,
+	actor: Actor,
 	now: number,
-): Partial<Card> {
-	const fields: Partial<Card> = { status };
-	if (status === "blocked") {
-		if (blockedBy !== undefined) fields.blockedBy = blockedBy;
-	} else {
-		fields.blockedBy = undefined;
-	}
-	if (status === "done" && op.landed !== undefined) fields.landed = { commit: op.landed.commit, at: now };
-	return fields;
-}
-
-function note(card: Card, raw: unknown, actor: Actor, now: number): OpResult {
-	const parsed = normalizeNote(raw);
-	if ("error" in parsed) return { ok: false, error: parsed.error };
-	return { ok: true, card: write(card, actor, now, appendNote(card, actor, now, parsed.text)), changed: true };
-}
-
-/** A card's notes after one more, with the oldest dropped and counted. */
-function appendNote(card: Card, actor: Actor, now: number, text: string): Pick<Card, "notes" | "notesDropped"> {
-	const notes = [...card.notes, { by: actor.label, at: now, text }];
-	const overflow = Math.max(0, notes.length - MAX_NOTES);
-	return {
-		notes: overflow === 0 ? notes : notes.slice(overflow),
-		notesDropped: card.notesDropped + overflow,
-	};
-}
-
-/** A card's log after one more transition, with the oldest dropped and counted. */
-function appendTransition(card: Card, status: CardStatus, actor: Actor, now: number): Pick<Card, "log" | "logDropped"> {
-	const log = [...(card.log ?? []), { status, at: now, by: actor.label }];
+	block: CardBlock | undefined,
+): Pick<Card, "log" | "logDropped"> {
+	const entry = block === undefined ? { lane, at: now, by: actor.label } : { lane, at: now, by: actor.label, block };
+	const log = [...(card.log ?? []), entry];
 	const overflow = Math.max(0, log.length - MAX_LOG);
 	return {
 		log: overflow === 0 ? log : log.slice(overflow),
@@ -290,148 +245,37 @@ function appendTransition(card: Card, status: CardStatus, actor: Actor, now: num
 	};
 }
 
-function plan(card: Card, raw: unknown, actor: Actor, now: number): OpResult {
-	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; its plan cannot change.` };
-	if (!holds(card, actor)) return { ok: false, error: `${heldBy(card)} Only its owner records a plan.` };
-	const parsed = normalizePlanPath(raw);
-	if ("error" in parsed) return { ok: false, error: parsed.error };
-	if (card.plan === parsed.path) return { ok: true, card, changed: false };
-	return { ok: true, card: write(card, actor, now, { plan: parsed.path }), changed: true };
-}
-
-/**
- * Fix what a card says: its title, its hints, its priority, and what it waits for.
- *
- * The holder decides for a held card and anyone decides for an unclaimed one — and
- * that includes a `done` card, because a title is what a reader reads, not a step of
- * the work: a finished feature whose title says the wrong thing would stay wrong for
- * as long as the board keeps history.
- *
- * Every field is optional and an absent one is left alone; a field that already holds
- * the value asked for is not a write, so re-editing the same card is a no-op.
- */
-function edit(
-	card: Card,
-	op: Extract<CardOp, { kind: "edit" }>,
-	actor: Actor,
-	now: number,
-	board: BoardIndex,
-): OpResult {
-	if (card.owner !== undefined && !holds(card, actor)) {
-		return { ok: false, error: `${heldBy(card)} Only its owner can edit it.` };
-	}
-	const fields: Partial<Card> = {};
-	if (op.title !== undefined) {
-		const parsed = normalizeTitle(op.title);
-		if ("error" in parsed) return { ok: false, error: parsed.error };
-		if (parsed.title !== card.title) fields.title = parsed.title;
-	}
-	if (op.paths !== undefined) {
-		const parsed = normalizePathHints(op.paths);
-		if ("error" in parsed) return { ok: false, error: parsed.error };
-		if (!sameList(parsed.paths, card.paths)) fields.paths = parsed.paths;
-	}
-	if (op.priority !== undefined) {
-		const parsed = normalizePriority(op.priority);
-		if ("error" in parsed) return { ok: false, error: parsed.error };
-		if (parsed.priority !== priorityOf(card)) fields.priority = parsed.priority;
-	}
-	if (op.dependsOn !== undefined) {
-		const parsed = normalizeDepends(op.dependsOn, card.id, board);
-		if ("error" in parsed) return { ok: false, error: parsed.error };
-		if (!sameList(parsed.dependsOn, dependsOf(card))) fields.dependsOn = parsed.dependsOn;
-	}
-	if (Object.keys(fields).length === 0) return { ok: true, card, changed: false };
-	return { ok: true, card: write(card, actor, now, fields), changed: true };
-}
-
-/**
- * Record that the card was offered to the team, and nobody has taken it.
- *
- * The same preconditions a claim would meet, because the offer asks a peer to claim: a
- * held card, a finished one, or one waiting on unfinished work is refused before anything
- * is broadcast. Re-offering refreshes the age rather than refusing as a no-op — a lead
- * who offers again is asking again, and the age is the record of when they last did.
- */
-function offer(card: Card, actor: Actor, now: number, board: BoardIndex): OpResult {
-	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be offered.` };
-	if (card.owner !== undefined) return { ok: false, error: heldBy(card) };
-	const waiting = waitingOn(card, board);
-	if (waiting !== undefined) return { ok: false, error: waiting };
-	return { ok: true, card: write(card, actor, now, { offeredAt: now }), changed: true };
-}
-
-function reclaim(card: Card, actor: Actor, now: number): OpResult {
-	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; there is nothing to reclaim.` };
-	if (card.owner === undefined) return { ok: false, error: `${cardRef(card.id)} has no owner to reclaim.` };
-	return {
-		ok: true,
-		card: write(card, actor, now, { status: "todo", owner: undefined, offeredAt: undefined }),
-		changed: true,
-	};
-}
-
-/**
- * Set a finished card aside, out of the board and into the archive beside it.
- *
- * Only a finished card leaves this way: `done` is terminal, and a card still in flight
- * has an owner, a plan, and a decision in it. No field moves and no transition is
- * appended — the record is unchanged, and what changed is which pile its file lies in,
- * which is the store's write. `changed` is still true, because the board lost a card.
- */
-function archive(card: Card): OpResult {
-	if (card.status !== "done") {
-		return { ok: false, error: `${cardRef(card.id)} is in ${card.status}; only a finished card can be archived.` };
-	}
-	return { ok: true, card, changed: true };
-}
-
-function drop(card: Card, actor: Actor, board: BoardIndex): OpResult {
-	// A drop takes its id with it, so a card another one waits on cannot leave: the
-	// remaining link would name nothing, and nothing on the board would say so.
-	const depended = dependedOn(card.id, board);
-	if (depended !== undefined) return { ok: false, error: depended };
-	if (card.status === "todo" || card.status === "done") return { ok: true, card, changed: true };
-	if (!holds(card, actor)) return { ok: false, error: `${heldBy(card)} It cannot be dropped while someone holds it.` };
-	return { ok: true, card, changed: true };
-}
-
-/** Whether two string lists are the same list, in the same order. */
-function sameList(left: readonly string[], right: readonly string[]): boolean {
-	return left.length === right.length && left.every((entry, index) => entry === right[index]);
-}
-
 /**
  * A card with `fields` applied and its write marks moved.
  *
  * This is the one place a lane change is observed, because it is the one place every
- * transition ends: a note, a plan, or an edit writes fields and leaves the lane alone,
+ * transition ends: a note, a contract, or an edit writes fields and leaves the lane alone,
  * while a claim, an assign, a release, a reclaim, and a move all name the new one. So
  * the log is appended from here rather than from each operation, and an operation added
  * later cannot forget it.
  */
 function write(card: Card, actor: Actor, now: number, fields: Partial<Card>): Card {
-	const status = fields.status;
+	const lane = fields.lane;
 	const transition =
-		status !== undefined && status !== card.status ? appendTransition(card, status, actor, now) : undefined;
+		lane !== undefined && lane !== card.lane
+			? appendTransition(card, lane, actor, now, lane === "blocked" ? fields.blocked : undefined)
+			: undefined;
 	const next: Card = { ...card, ...fields, ...transition, rev: card.rev + 1, updatedAt: now, by: actor.label };
 	// `owner: undefined` must clear the field rather than store a key holding it, so a
 	// released card reads back exactly like one that was never claimed. Only an
 	// explicit `owner` in `fields` may delete it: every other write keeps the holder.
 	if ("owner" in fields && fields.owner === undefined) delete next.owner;
-	// The same for the block: a card that left `blocked` has no reason, and a key holding
-	// undefined would be one more shape for a reader to know about.
-	if ("blockedBy" in fields && fields.blockedBy === undefined) delete next.blockedBy;
-	if ("offeredAt" in fields && fields.offeredAt === undefined) delete next.offeredAt;
+	// The same for a block and a spot-check: a card that left `blocked` has no reason and no
+	// kind, and one that left `execute` is not reviewed, so a key holding undefined would be
+	// one more shape for a reader to know about.
+	for (const field of ["blocked", "offeredAt", "review"] as const) {
+		if (field in fields && fields[field] === undefined) delete next[field];
+	}
+	// `blocked` is a fact about the `blocked` lane and nothing else: a card back in the pool, or
+	// one claimed out of it, is not parked on that decision any more. This is here rather than
+	// in each operation because every lane change ends in this one write — so a release, a
+	// reclaim, and a claim clean it without any of them having to remember, and the transition
+	// log keeps what the park was.
+	if (next.lane !== "blocked") delete next.blocked;
 	return next;
 }
-
-/** The owner recorded for an actor: the id only when this actor has one. */
-function ownerOf(actor: Actor): CardOwner {
-	return actor.id === undefined ? { label: actor.label } : { id: actor.id, label: actor.label };
-}
-
-/** The refusal for an operation on a card someone else holds. */
-function heldBy(card: Card): string {
-	return `${cardRef(card.id)} is held by ${card.owner?.label ?? "another session"}.`;
-}

package/lib/board/seat.ts

@@ -0,0 +1,35 @@
+/**
+ * The seat: the name the page serves as, and the actor it is shown as.
+ *
+ * A page outlives the session that opened it — a `/resume`, a rename, or a fresh session
+ * taking the page over would otherwise change who the page says it is. So the page is a *seat*
+ * rather than a session: one name for its whole life, one id derived from it, and the same
+ * identity however many sessions have served it.
+ *
+ * That name is `board.lead` — the lead's team name, read by `config.ts` — because the two
+ * questions have one answer: the page belongs to the lead, and serving it is how a session
+ * *becomes* the lead (the seat outranks the session's own name while it serves, so the gate
+ * accepts it). There is no built-in seat name here: a name in this module would be a second
+ * answer to a question the config already answers.
+ *
+ * The page writes nothing, so the id decides no ownership: it is what the page's own roster and
+ * the `you` chip are read against, and it keeps a page's reads the same across a handover. The
+ * board's tools write as the session — which is why the label is shared with the session
+ * serving the page and the ids are not.
+ */
+
+import type { Lead } from "./lead.ts";
+import type { Actor } from "./rules.ts";
+
+/** The prefix of a page's actor id, so one is never mistaken for a session id. */
+export const SEAT_ID_PREFIX = "board:";
+
+/**
+ * The actor a page reads as: the lead's name, and an id derived from it.
+ *
+ * The name arrives already normalized: `board.lead` passes `normalizeLabel` on its way out of
+ * `config.ts`, so this only derives the id — one rule for a label, in one place.
+ */
+export function pageActor(lead: Lead): Actor {
+	return { id: `${SEAT_ID_PREFIX}${lead.toLowerCase()}`, label: lead };
+}