# configuration/strings/coordination.fragment.strings.ts > 302 lines of code and 17 definitions. Tree: Site tree Language: typescript Layer: product Canonical: https://banes-lab.com/anatomy/tree#file-configuration-strings-coordination-fragment-strings-ts Source text: https://banes-lab.com/assets/sources/source.e6d293ec95981ca04e268e18efe3ccba53746a192255ab0b65a4588520185bf1.generated.txt ## Definitions - `RECORD_SHAPE` (lexical_declaration, line 16) - `SCHEDULE_SHAPE` (lexical_declaration, line 19) - `MODEL_DIAGRAM` (lexical_declaration, line 22) - `READER_DIAGRAM` (lexical_declaration, line 25) - `SEAT_DIAGRAM` (lexical_declaration, line 28) - `SURFACE_DIAGRAM` (lexical_declaration, line 31) - `ITEM_DIAGRAM` (lexical_declaration, line 34) - `CONVERGENCE_DIAGRAM` (lexical_declaration, line 37) - `WAIT_DIAGRAM` (lexical_declaration, line 40) - `CAP_DIAGRAM` (lexical_declaration, line 43) - `RUN_DIAGRAM` (lexical_declaration, line 46) - `TURN_DIAGRAM` (lexical_declaration, line 49) - `COORDINATION_SECTION` (lexical_declaration, line 52) - `SURFACE_SECTION` (lexical_declaration, line 118) - `WAIT_SECTION` (lexical_declaration, line 198) - `TURN_SECTION` (lexical_declaration, line 278) - `SURFACE_SECTIONS` (lexical_declaration, line 319, exported) ## Source ```typescript import { COORDINATION_SECTION_ICON, SURFACE_SECTION_ICON, TURN_SECTION_ICON, WAIT_SECTION_ICON, } from "#configuration/icons/coordination.icons"; import { COORDINATION_SECTION_ID, SURFACE_SECTION_ID, TURN_SECTION_ID, WAIT_SECTION_ID, } from "#core/ids/coordination.ids"; import { TEXT_LANGUAGE, TYPESCRIPT_LANGUAGE } from "#configuration/constants/code.constants"; import type { Section } from "#types/document.types"; const RECORD_SHAPE = "┌─── ─── one writer: · others cite, never edit · a span edit only, never a whole-file write\n — \n : \n : \n :\n ┌─── - ─── kind: at: to:\n To — the argument, across as many lines as it needs.\n └─── END -\n : \n└─── END "; const SCHEDULE_SHAPE = 'export const SCHEDULE_STATES = ["planned", "created", "open", "archived"] as const;\nexport type ScheduleState = (typeof SCHEDULE_STATES)[number];\n\nexport interface ScheduleRow {\n readonly ordinal: string;\n readonly invariant: string;\n readonly establishes: string;\n readonly merged?: string;\n readonly declaredState?: ScheduleState;\n readonly declaredBecause?: string;\n}\n\nexport const schedule: readonly ScheduleRow[] = [\n { ordinal: "1", invariant: "", establishes: "" },\n { ordinal: "2", invariant: "", establishes: "" },\n { ordinal: "2a", invariant: "", establishes: "", declaredState: "planned", declaredBecause: "" },\n];'; const MODEL_DIAGRAM = 'flowchart TB\n subgraph surface["A surface · a file the parties read and write"]\n r1["Record · one writer, declared on the record"]\n r2["Record · one writer"]\n r3["Record · one writer"]\n end\n artifact["An artifact in the tree"]\n other["A record on another surface"]\n r1 -- satisfied-by · closes when the artifact exists --> artifact\n r2 -- blocks · the target cannot close first --> r3\n r3 -- answers · refutes · supersedes --> other\n state["Every state is a query over these edges · no party writes one"]\n surface -.-> state'; const READER_DIAGRAM = 'flowchart TB\n participant["A participant · holds a seat"]\n owns["Receives the surfaces it owns and its inbox"]\n waits["Ends never · it waits, and waiting has a command"]\n bounded["A bounded reader · a spawned run"]\n injected["Receives a task and whatever the host injects · never a coordination surface"]\n projection["One derived line is its whole view of the graph"]\n returns["Ends by returning · which is its contract"]\n participant --> owns --> waits\n bounded --> injected --> projection --> returns'; const SEAT_DIAGRAM = 'flowchart TB\n claim["A letter is claimed by adding a row to the index, before the first write"]\n allocated["The identity is allocated · the shortest free one, never reused"]\n role["A role document at the concern, the letter in a field"]\n record["A fenced record on the board, raised from the template"]\n state["One mutable column · active, inactive, invoked · a seat moves only its own row"]\n claim --> allocated --> role --> record\n claim -.-> state'; const SURFACE_DIAGRAM = 'flowchart TB\n subgraph board["The board · current truth only"]\n b1["Who owns what · what is directed at whom"]\n b2["Swept · a resolved item is deleted, never marked"]\n b3["Read whole, every round"]\n end\n subgraph venue["The venue · an argument"]\n v1["Where each seat stands · what it still needs"]\n v2["Accumulates until it converges · dissent survives"]\n v3["Holds the build while open · that red is intended"]\n end\n transport["One transport · fenced records, tool-allocated ids, compare-and-swap"]\n board -.-> transport\n venue -.-> transport\n venue -- converged, absorbed, then archived whole --> archive["The archive · the reasoning survives"]\n board -- absorbed items extract first --> history["The history accumulator · the only home history has"]'; const ITEM_DIAGRAM = 'flowchart TB\n posted["An item is posted · a fenced span, an allocated id, a kind, a stamp, its addressees"]\n kind{"Which kind?"}\n artifact["Artifact · asks for something that can exist"]\n judgement["Judgement · asks for a reading"]\n ref["Closes with a typed reference that must resolve"]\n ack["Closes by its acknowledger, with no reference"]\n handler["Closed by a seat in its reader set · never its author"]\n ledger["Held while a named recipient has not marked it read"]\n extract["Its durable half extracted to the accumulator first"]\n dropped["The span is dropped, never a matched line"]\n posted --> kind\n kind -- artifact --> artifact --> ref --> handler\n kind -- judgement --> judgement --> ack --> handler\n handler --> ledger --> extract --> dropped'; const CONVERGENCE_DIAGRAM = 'flowchart TB\n open["Open · the venue declares its own exit condition and holds the build"]\n needs["Every convened seat states its needs"]\n signed["Every convened seat has signed · a signature with an open need is refused"]\n durable["Every seat\'s durable half resolves in the accumulator"]\n deferred["Every deferred question has a destination that resolves"]\n directives["Every directive is discharged"]\n absorbed["The outcome is absorbed · the distribution checklist carries no open item"]\n inherited["Every clause the successor inherits was deferred here"]\n archive["Moved whole into the archive · never deleted"]\n open --> needs --> signed --> durable --> deferred --> directives --> absorbed --> inherited --> archive'; const WAIT_DIAGRAM = 'flowchart TB\n invoke["One invocation · the seat declared, the surface named"]\n check["Every operand of every requested operation is checked before any lands"]\n witness["A witness read immediately before the write"]\n moved{"Did the surface move since the read?"}\n span{"Does the change overlap this seat\'s own span?"}\n replay["Replay · the writes commute"]\n refuse["Refuse · carrying the diff of that span"]\n land["Land inside the seat\'s own fence"]\n sweep["Sweep · items every addressee has written past and been handed, extracted whole"]\n echo["Echo the seat\'s own claim, the items it can close, the open discussions"]\n snapshot["Re-snapshot for this seat · the next call reports only what changed"]\n invoke --> check --> witness --> moved\n moved -- no --> land\n moved -- yes --> span\n span -- no --> replay --> land\n span -- yes --> refuse\n land --> sweep --> echo --> snapshot'; const CAP_DIAGRAM = 'flowchart TB\n able["Seats able to write · parked, running a live claim, or active inside the liveness window"]\n waiting["Seats already parked"]\n cap{"Would this wait leave no seat able to write?"}\n blocked["Blocked · write first, the board owes a response"]\n watch["Watch the surface · changed with the diff, quiet after the window, removed if deleted"]\n able --> cap\n waiting --> cap\n cap -- yes --> blocked\n cap -- no --> watch'; const RUN_DIAGRAM = 'flowchart TB\n start["A run declares its write scope and claims standing"]\n live{"Does a live run\'s write set overlap?"}\n held["Healing held · report only, until the other run publishes"]\n later{"Did this run start later than that one?"}\n join["Join · read out what the live run publishes, write nothing"]\n run["Run · stamp every surface read, re-stamp at the end, name the surfaces it healed apart"]\n quotable["The aggregate is overwritten · the verdict carries its standing"]\n start --> live\n live -- no --> run\n live -- yes --> later\n later -- yes --> join\n later -- no --> held --> run\n run --> quotable'; const TURN_DIAGRAM = 'flowchart TB\n item{"Is there an open item?"}\n work["Work it · a tool call advances it"]\n blocked{"Blocked on a peer?"}\n next["Route to the next unblocked item"]\n wait["Wait through the tool · the turn stays open"]\n changed{"What did the wait return?"}\n read["Read the surface whole, then act on every item addressed to me"]\n own["Pick up my own work and wait again"]\n report["A report to the developer"]\n item -- yes --> blocked\n blocked -- no --> work --> item\n blocked -- yes, others open --> next --> work\n blocked -- yes, all --> wait --> changed\n changed -- changed --> read --> item\n changed -- quiet --> own --> wait\n item -. never, while work remains .-> report'; const COORDINATION_SECTION: Section = { icon: COORDINATION_SECTION_ICON, id: COORDINATION_SECTION_ID, intro: "When several reasoning agents write to one tree at the same time, this method treats their coordination as software. Its parts are shown in the model. A seat is created in the order shown in a seat's making, and its readers fall into the two classes shown in reader classes. A lost update, a stale item, a missed message or a surface that has grown past reading is a defect report against the protocol, never a call for more care, and friction points to a missing concurrency control. The grammar page states the same premise under orchestration as declared structure, and the schema derived here is the one described in shared surfaces there.", subsections: [ { blocks: [ { application: "In practice, the coordination is modelled as a graph. A surface is a file the parties read and write, a record is one addressable claim inside it with exactly one writer declared on the record itself, and an edge is an id in a field. Every state is derived by traversing the edges, and no party writes one. Each party has a permanent identity bound in an index before its first write, and who may read an item is derived from presence on the surface and state in the index, never from anything a party declares about itself.", boundary: "One writer per record is the invariant everything else rests on, and it does not apply to an outcome surface that is written jointly, such as a contract or a measured baseline. There the invariant is declared inapplicable, with its reason, and a clash in meaning is caught by an announcement plus each author removing its own duplicate, which is a different instrument from a fence.", cause: "Every coordination failure is produced by good behaviour composing badly: each append is a real finding honestly reported, and the defect lies entirely in the composition, which no rule about care can see.", decision: "Every coordination failure is treated as a missing mechanism and answered with a surface, a schema or a validator, rather than with a request for more care.", failureMode: "A board grows past what any reader can consume, carrying hundreds of directed items, with every drain rule in force and agreed by every party.", kind: "lesson", principle: "For this reason I treat coordination as software, with state, invariants and a schema, which decays without a validator.", problem: "More than one agent on one tree loses writes, accumulates stale items and misses messages, and each incident has a plausible local cause that hides the gap in the mechanism.", validation: "To check this, take the last coordination failure and name the mechanism that would have made it impossible or loud. If the answer is that you or the model should have been more careful, the mechanism is still missing.", }, { caption: "the model", kind: "mermaid", text: MODEL_DIAGRAM }, ], title: "Surfaces, records, edges, states", }, { blocks: [ { kind: "text", text: "One writer per record refuses shared mutable state at the level of a single claim. With one writer per record, ordinals are allocated without coordination, last-writer-wins cannot happen, and protecting another party's scope becomes checkable record by record. The scope of the rule is the whole point: stated per surface, it is false wherever a surface is shared, which is the normal case, and because the two versions look identical on a surface with one writer, the mistake survives. A record's identity is allocated once and never recomputed, while its subject is declared and derived again on every run, because an id derived from location breaks on a move and one derived from the subject breaks on a rename. Two records sharing a subject key is the finding that catches a re-derivation.", }, { kind: "text", text: "No agent writes a state, which is derived state applied here as everywhere else. A written state is a marker, a marker goes stale, and a stale marker creates a false belief, while an absent one simply reads as absence. Open, blocked and absorbed are queries over the edges, which is event sourcing over a graph of claims: a record is open while a citation is unresolved, blocked while an inbound edge comes from an open record, and absorbed once the citation resolves. Absorbed is a transition, never a resting state. The record's durable half is extracted to the one home history has, an append-only log, and the record is deleted in the same change, because a record resting in absorbed is a status marker spelled differently.", }, ], title: "One writer, no written state", }, { blocks: [ { kind: "text", text: "A seat is a letter bound to a role in an index that only grows, and what the role document holds is described in a seat is a contract. The index is an accumulator rather than a section of the board, because the board deletes what is resolved, while a letter that is no longer active still has to resolve: every item, row and citation that ever named it points there. A letter is claimed by adding its row before the first write, never simply by using it. The identity is allocated rather than chosen. The tool issues the shortest free identity from a scheme that never runs out and never reuses one, and the letter a party asks for is only its declaration for that call, not the allocation. The index has one mutable column, the seat's state, drawn from a closed set, because the reader set, the wait cap, the resolution of addressees and the convergence check all derive from it. A seat moves its own row, and a party that moves another party's state writes its reason beneath the row.", }, { caption: "a seat's making", kind: "mermaid", text: SEAT_DIAGRAM }, ], title: "A seat is allocated, never chosen", }, { blocks: [ { kind: "text", text: "A reader's class is derived from what it received, never from what it decides it is. A participant receives the surfaces it owns and its inbox, and its turn never ends: it waits, and waiting has a command. A bounded reader receives a task and whatever the host injects, never a coordination surface. One derived line is all it knows about every surface, so a fact missing from that line does not exist for anything spawned, and the line is refreshed in the same change as the fact it carries, because a stale projection is a false statement delivered as the only statement. The rules divide by class, and the rules about owning a turn are inverted for a bounded reader: obeying the rule that a turn never ends would forbid it from returning, and returning is its contract. Which class a reader belongs to comes from the binding rather than from the reader. A deployment whose board slot resolves as absent is single-worker by declaration, and a reader classifying its own turn would be an escape hatch keyed on self-classification.", }, { caption: "reader classes", kind: "mermaid", text: READER_DIAGRAM }, ], title: "Two reader classes", }, ], title: "Coordination is software", }; const SURFACE_SECTION: Section = { icon: SURFACE_SECTION_ICON, id: SURFACE_SECTION_ID, intro: "Two surfaces with opposite lifetimes share one transport, as shown in two surfaces. The board carries coordination state, meaning who owns what and what is directed at whom, and it is swept, because it holds current truth only and an item that no seat drains is a cost every seat pays every round. One seat's part of it is shown in a seat's record, and an item's closure shows how an item leaves it. The venue carries an argument and accumulates until the argument converges, because a position stands until it is read and dissent survives to the end, through the orderings shown in convergence and the schedule typed in a venue schedule. The coordination templates on the grammar page carry both shapes, and the seats that write them are partitioned as described in composing a collaboration.", subsections: [ { blocks: [ { application: "In practice, the board holds current truth only: it is overwritten in place, a resolved item is deleted outright, and every append is paired with a drain of whatever is already absorbed. Each seat's record is enclosed in a delimiter naming its writer, and each addressed item in a fence keyed to an id the tool allocates, with its kind on the marker. An edit then has a span to anchor to, a removal takes the span rather than a matched line, and the closure is chosen by the kind rather than judged. The seat that handled an item removes it, never the seat that wrote it, and extracts its durable half first. Positions are written to an open venue, the build is held while the venue stands, and the venue is archived whole once its outcome is built.", boundary: "A venue can be written by the tool but never drained by it, and once archived it takes on immutability as an append-only log of the argument. Nothing in an open venue is closed or compressed, since draining a discussion would delete the argument it exists to hold. Leaving the active tree and leaving the repository are different operations, and a word like deleted blurs the two.", cause: "Only the handler knows an item is handled, and only the writer was permitted to remove it, so the knowledge and the permission sat in different seats and the item stayed.", decision: "The surfaces are split by lifetime rather than by topic, so a swept surface and an accumulating one never share a record.", failureMode: "A converged venue is removed from disk as soon as it is signed, which satisfies every ordering the closure checks, and every position id the accumulator cites then points at nothing.", kind: "lesson", principle: "For this reason the board is swept and the venue accumulates, and the two share only their transport.", problem: "One surface asked to hold both coordination state and an argument reports one state and hides the other.", validation: "To check this, read the board for an item that argues rather than states, and read the archive for a venue whose reasoning is missing. Either one is a lifetime applied to the wrong surface.", }, { caption: "two surfaces", kind: "mermaid", text: SURFACE_DIAGRAM }, ], title: "Swept and accumulated", }, { blocks: [ { kind: "text", text: "The delimiter is not decoration. A seat revising its own record needs a span it can match exactly, one that no other seat's content occupies. Without it, the only thing left to match is the whole file, so the seat reaches for a whole-file write, which succeeds, reports success to the party that overwrote, and says nothing to the party that was overwritten. A template that has to contain a record shape in order to describe one fences the specimen, because a fenced specimen is a record mentioned, while an unfenced one is a record claimed; this is the confusion between use and mention, appearing on the write side.", }, { kind: "text", text: "An item's kind sits on its marker and selects its closure, which the grammar page describes as handoff signals: typed items with closures that can be checked. An artifact item asks for something that can exist, so it closes with a typed reference that has to resolve. A reference whose kind names no corpus would resolve vacuously and read exactly like one that passed, which is why the set of kinds is closed. A judgement item asks for a reading, so it closes when its declared acknowledger signs it off, with no reference, because there is nothing for a reference to point at; the acknowledger is required or forbidden by kind rather than optional. An artifact item that carries nothing durable closes with a reference declared empty, and the tool then publishes the classes already filed, so declaring nothing durable becomes a lookup a peer can contest rather than an oversight that stays invisible.", }, { kind: "text", text: "The sweep is the mechanical drain, and it is gated on delivery: an item is a message on a message queue whose consumers are named, and it leaves the queue once every consumer has taken delivery. On every write, the tool sweeps the items that every addressee has both written after and been handed in a delivered read, extracting each one whole into the accumulator before removing it. It holds any item an addressee has not received, because having written after an item says something about that party's writing and nothing about its reading. Durability and delivery are independent, and archiving an item that no addressee received preserves the first while destroying the second. An argument is refused on the swept surface by its shape: a body carrying the declared fields of a position, derived from the venue template rather than listed, is turned back with the instruction to name the venue.", }, { caption: "an item's closure", kind: "mermaid", text: ITEM_DIAGRAM }, { code: RECORD_SHAPE, kind: "code", language: TEXT_LANGUAGE, title: "a seat's record" }, ], title: "Fences, kinds and the sweep", }, { blocks: [ { kind: "text", text: "A venue declares its own exit condition, or it becomes an indefinite halt. While it stands, its presence fails the pipeline, and that red result is intended, because building around an open question produces work that gets rewritten. Its fields are its own: where each seat stands and what it still needs before it can sign. An empty list of needs across every convened seat is what convergence looks like, rather than something a seat judges. A position is posted through the tool into the seat's own fenced record, so the fence, the id, the addressing and the compare-and-swap apply on a venue just as on the board. A position ends with a signed line as its one structural end mark, because a body cut short at a blank line reaches the argument already short, and the signature detects what the boundary would hide. A signature is refused while the same seat states an open need, since an unmet need and a signature are contradictory claims by one party.", }, { kind: "text", text: "Convergence is a walk over event ordering, with each ordering encoded as a refusal rather than a note, because an ordering recorded in prose is rediscovered by collision, while one encoded in the operation cannot be broken. The general form is stated under orchestration invariants on the grammar page, and how a seat writes one is described in stating an invariant. The convened set is the intersection of the board's active seats and the venue's participants, and a venue that no seat is party to is reported as failing rather than passing vacuously, because a filter over an empty set holds over nothing. Convergence certifies agreement and says nothing about the tree, so the outcome is distributed as a checklist with an owner for each item, and it lands before the venue moves. The move creates the archived name, failing if that name already exists, before it removes the source, so a failure leaves the venue where it was.", }, { caption: "convergence", kind: "mermaid", text: CONVERGENCE_DIAGRAM }, ], title: "A venue converges or holds the build", }, { blocks: [ { kind: "text", text: "A successor is declared by name against a schedule rather than derived from an ordinal, because an ordinal is a position in a total order, while the real edges are partial and include forward dependencies: a directed acyclic graph rather than a list. The declaration is checked at the moment it is written. A deferral names its receiver on the same line and is refused unless the receiver is an active seat, a venue on disk or a planned row, and a venue that defers nothing records that as a third state, distinct from unfilled. The schedule has one author, resolved by concern and handed on rather than shared, because a schedule with several authors stops being derivable from any single reading.", }, { kind: "text", text: "The record and the schedule are the two shapes worth holding in mind, because every check on the surface derives from one of them. The state column is computed on every run unless a row declares a state with a reason, so the set of rows is the plan, and nothing in it records what happened. Both shapes ship as templates, and the checks read their contracts from those templates, as described in the drop-in.", }, { code: SCHEDULE_SHAPE, kind: "code", language: TYPESCRIPT_LANGUAGE, title: "a venue schedule" }, ], title: "The schedule is a graph", }, ], title: "The board and the venue", }; const WAIT_SECTION: Section = { icon: WAIT_SECTION_ICON, id: WAIT_SECTION_ID, intro: "The seats speak to each other through one tool, which makes the protocol structural rather than something each seat has to remember; it is the rule described in tools live in the tree, applied to the collaboration itself. Posting and waiting are one operation, shown end to end in one invocation. Every invocation declares its seat and writes only inside that seat's own fence, under optimistic locking. It delivers the diff of what the seat's peers wrote since it last looked, sweeps what every addressee has received, and takes a new snapshot. How long an invocation waits is derived as shown in the wait cap, and a second run joins a live one, as shown in joining a run.", subsections: [ { blocks: [ { application: "In practice, the collaboration has one tool with one shape. Every invocation is keyed to a declared seat, because the snapshot, the fence, the reader set and the closure check all derive from it. Every operand of every requested operation is checked before any of them lands, so an invocation is one unit. A witness read is taken immediately before every write; a write that commutes with what moved is replayed, and only a genuine overlap with the diff of the writer's own span is refused. The diff is delivered whole, never as a status line with content attached.", boundary: "The tool covers the surfaces that are shared and still writable. A surface with one writer by construction needs no fence, no allocated id, no compare-and-swap and no reader set, because all four defend against a party that cannot exist there, and a closed record or an archived discussion needs no write path at all.", cause: "A protocol that mandates a surface its tool cannot write to is obeyed by hand, and a hand write has no fence, no allocated id, no compare-and-swap, no reader set and no gate.", decision: "Every coordination write is a tool write, and the tool refuses what the protocol forbids, rather than the protocol relying on each seat to remember it.", failureMode: "Three seats filter the tool's output for the line confirming that their own write landed, discard every peer position delivered in the same stream, and the tool reports success each time.", kind: "lesson", principle: "For this reason posting and waiting are one operation keyed to a declared seat, and what it delivers is the diff since that seat last looked, read whole.", problem: "A coordination surface written by hand carries every guarantee as a hope, and a hope decays at the rate of the party who holds it.", validation: "To check this, invoke the tool with nothing after it and read the whole of what it returns. Then try to break each guarantee by hand: a body passed as an argument, a closure by the author, a mark by a stranger, a second record for one seat. Each attempt should be refused, with the reason the refusal exists.", }, { caption: "one invocation", kind: "mermaid", text: WAIT_DIAGRAM }, ], title: "One tool, one shape", }, { blocks: [ { kind: "text", text: "The snapshot is kept per seat and per surface. The tool reads the seat's last snapshot of the target, writes the current content as the new snapshot, records which addressed items it delivered, and returns a line-level diff. A first read answers with a snapshot and nothing else, an unchanged surface answers that nothing moved, and a changed one answers with the added and removed lines. The diff is the delivery: every peer position written since the seat last looked arrives in that stream and nowhere else, so the output has to be read whole. Past the read budget, the delivery degrades rather than truncates, which is backpressure applied to a read: it names every changed item by its fence and leaves the bodies on the surface, because a silent truncation hands over a partial read that looks complete. Every write also echoes back what nothing else would prompt the seat to read again.", }, ], title: "The delivery is the diff", }, { blocks: [ { kind: "text", text: "The allocated id is a correlation id: every closure, citation and read mark resolves through it. A body that contains a boundary marker line is refused, because the boundaries are what make a span removable.", }, ], title: "The item and its id", }, { blocks: [ { kind: "text", text: "A read ledger for each item lives on the item's own marker and disappears with it, which lets a swept surface carry delivery state per party without becoming a surface that tracks. The ledger is what makes each seat an idempotent consumer of the items addressed to it. Each party moves its own letter and no other, a mark by a party the item never addressed is refused, and a closure is held while a named recipient that is still active has not marked the item, so a change that every seat must hold drains on its last reader rather than its first. A rehearsal that writes is the worst form a preview can take, because the invocation a party chooses for safety becomes the one that acts without warning, which is why, as described in tools live in the tree, a tool that rewrites values previews its changes by default.", }, ], title: "Delivery per party", }, { blocks: [ { kind: "text", text: "The wait blocks on the surface's modification state, which is the publish/subscribe pattern over a file, with a timeout pattern for the window. It reports the diff when the surface moves, quiet when the window closes untouched, and removed if the surface is deleted while it watches, and every exit is typed so that a caller reads the code rather than the prose. The number of waiters is capped at the number of seats able to write, minus one, and what counts is liveness rather than membership. A seat counts if it is parked, holds a live run, or touched a surface inside the declared window; otherwise a seat that stops without updating its row would raise the threshold by one, until every remaining party could park with no seat left to write. The last seat is told that the board owes a response, and the case of a single seat is stated separately, because no write clears it.", }, { caption: "the wait cap", kind: "mermaid", text: CAP_DIAGRAM }, ], title: "The wait and its cap", }, { blocks: [ { kind: "text", text: "A long-running run scales by joining rather than duplicating, which is the idempotency of a measurement. A run declares its write scope and claims standing before it runs. Healing is held while another live run's write set overlaps, because healing changes the tree, and healing while another run is mid-write takes an exclusive resource without declaring it. A run that starts later than an overlapping live one joins it and reads what it publishes instead of measuring the same tree twice, and a run whose question a live run already covers reads the covering result. Every surface a run reads is stamped and stamped again, and what a moved read set does to the verdict is described in verify the verifier. The surfaces the run healed itself are named separately, because counting a run's own repairs as contention would make every healing run impossible to quote. A run's declaration is a claim and its writes are a fact, so a write outside the declared scope and a claimed repair whose surface never moved are both reported; that is the one comparison between a claim and an observation the run performs.", }, { caption: "joining a run", kind: "mermaid", text: RUN_DIAGRAM }, ], title: "A run joins, never duplicates", }, ], title: "Posting and waiting are one operation", }; const TURN_SECTION: Section = { icon: TURN_SECTION_ICON, id: TURN_SECTION_ID, intro: "A turn never ends because work is blocked on a peer, which is the one edge a turn never takes: ending the turn would be the wait, and that wait is a halt. Waiting costs a tool call rather than a turn. A seat reports to its peers on the surface, never to the developer, because a report addressed to the developer reads as an ending and stops the collaboration for as long as the developer takes to reply. The tool this section relies on is described in posting and waiting are one operation, and phase binding on the grammar page explains why a bounded run returns instead.", subsections: [ { blocks: [ { application: "In practice, the model is asked to work the next open item and, where one blocks, to move to the next unblocked one. Where every item depends on a peer, it waits through the tool, naming the surface the argument is on, and keeps the turn open across the wait. When the wait returns a change, it reads the surface whole and acts on every live item addressed to it, without waiting again straight away and without narrating what the read found. When the wait returns quiet, it picks up its own work and waits again. Findings, status and conclusions are written as directed items to the seats that need them.", boundary: "Where the work is clear and nothing blocks it, the work is simply done. Every coordination mechanism is a way of moving work, and moving work feels like doing it, so the blocker is named before anything is routed; where naming it produces nothing, the item is clear and routing it would be a substitute for the work.", cause: "A well-organised summary delivered at a moment that felt conclusive is the most common disguise a halt wears, and the quality of the summary is not a defence.", decision: "A blocked item is routed to the next open one, and the wait goes through the tool only when every item is blocked, rather than the turn ending on a report.", failureMode: "A seat's own queue empties, it reports a milestone, the turn ends, and the peers whose writes would have created its next work never receive what it found.", kind: "lesson", principle: "For this reason a turn ends on a tool call, a wait is a call rather than a halt, and findings go to the seats that need them.", problem: "Every coordination failure that outlives its mechanisms takes the shape of a turn that ended on prose.", validation: "To check this, read the last action of every response in a session. A response whose last action is prose while work remained stopped the collaboration, however much work came before it.", }, { kind: "text", text: "A second wait straight after the first throws away the signal just delivered while looking like diligence, because a tool call is present and the turn stays open. Reading produces a coherent picture of what just moved, and a coherent picture is the strongest invitation to describe it; the description is the halt. Quiet is a fact about the peers, never about the queue, and the queue is not empty while a surface is unaudited, a pattern is ungated or a claim is unverified.", }, { kind: "text", text: "A decision that no seat is making is a routing signal rather than a stall, and it travels as one of the handoff signals the grammar page types. Two independent refusals are the trigger. A question that every existing seat has declined is an input that exists in no file, which is exactly what makes the work suited to an agent, and it is assigned to a seat without waiting to be asked: either an existing seat whose concern covers it, or a new one created for it. A question a seat correctly judges to be above its own authority goes to the seat whose surface the decision binds, named in the same position that declines it, because saying a decision is not yours is a routing statement, not an end point. A contradiction that is fully diagnosed, with a named repair and no seat to take it, reads as handled while nothing lands. The developer is out of the loop for venues and signs off on every venue automatically, so no venue waits on the developer's signature and no decision inside one is the developer's to take. What the work is for remains the developer's to answer whenever they choose, at the cost of a message rather than a held venue. A question to the developer binds a seat only; a bounded invocation returns its uncertainty instead, as described in ask where it appears.", }, { caption: "a turn", kind: "mermaid", text: TURN_DIAGRAM }, ], title: "Waiting has a command", }, ], title: "A turn never ends to wait", }; export const SURFACE_SECTIONS: readonly Section[] = [COORDINATION_SECTION, SURFACE_SECTION, WAIT_SECTION, TURN_SECTION]; ```