Repository navigation
docs(atlas): propose L2 ordered multi-reply via board coordinator - #1601
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
/simplify review — direction sound, presentation over-built
Verdict: The design lock is right; the page diff repeats it more than it needs to. Not blocking — I'd merge after a hub-and-spoke trim (or accept as-is if you're optimizing for "one scrollable SSOT" and will reconcile with #1598 on merge).
What landed well
- Promoting
TaskCollectionRef.claimto exists is the substantive win. The old "later POC may reuse claim/lease" hedge was hiding a pin that's already on main. Verified:claim,ClaimOptions.eligibility,deps[], andisClaimablepaths inpackages/orchestrationmatch the citations. - Splitting reply discipline into exclusion / who / order is a real boundary: substrate vs policy vs optional composition. Conflating them was the old smell.
- Ordered multi-reply via roster-role +
deps+dispatcher()reuses substrate correctly. The CUT list (no MessageBoard sequencer, no coordinator L1 type, no new lease) is appropriate guard-railing. - Annotated code samples (
claimEXISTS,addTasksPROPOSED) are the strongest reuse pattern in the diff — prefer these over more SVG text.
Where the approach went too far (documentation, not design)
The PR encodes the same four-label taxonomy (claim exists · who-may-reply proposed · ordered chain proposed · cross-flow proposed) plus the CUT refrain in ~12–15 surfaces: §05 lede, cards, disposition table, three figures + figcaptions, routing-matrix box, Talk table, note, §06 lede, §08 table, §12 inventory, §13 cuts, §14 one-liner.
conductor.html does the opposite: one disposition table + one deep subsection, then pointers. This PR follows workforce's Piece-table habit but not conductor's hub-and-spoke discipline — it reads like copy-paste per section, similar to the feedback on #1598.
Rough cost: ~40% of added prose/SVG could be pointers without losing meaning.
Simpler shape I'd recommend (optional, pre- or post-merge with #1598)
- §05 = sole hub — disposition table + one composite figure (wake → claim → optional deps chain as dashed overlay) + the two code blocks + one prose block for ordered multi-reply.
- Drop or shrink the broke-path figure — lease /
parked/ retry is generic task-machine behavior (framework.htmlalready has a status diagram). One sentence + link is enough unless ordered-reply failure modes differ (they don't in this doc). - Downstream = pointers only — §06, routing matrix, §08: "Group replies → §05" without re-listing deps/coordinator/broke. Keep the full anti-substrate paragraph once in §13.
- Restore the one-sentence version — it grew into an inventory string; either shorten or relabel it.
Coordination with #1598
Both PRs promote claim-exists with near-identical wording. #1598 also promotes same-flow group fan-out to exists; this branch leaves it proposed. That's a real disposition conflict if both land unmerged — worth reconciling on rebase (merge #1598 first, then add only this PR's unique ordered-chain content).
Minor clarity (not blocking)
- "Coordinator" overload — used for who-may-reply actor, board coordinator filing deps, and routing parent-star. Consider renaming the ordered-reply role (e.g. reply scheduler) in doc only.
- Claim scope — "one holder per post" is L2 composition (one row per post + eligibility). Worth one explicit sentence; deps enforce order among rows, claim enforces one worker per row — complementary, easy to misread in the Alice/Bob/Cara diagram.
Performance
Not a concern — static HTML, simple SVG primitives, +13KB. The maintenance surface area is the real cost.
Bottom line: Keep the lock; trim the scatter. If you want a single actionable follow-up: collapse §05 to hub-and-spoke and make §08/§12/routing-matrix one-line pointers — that alone addresses most of the /simplify findings.
Sent by Cursor Automation: Review For Best Approach
| <section id="channels"> | ||
| <div class="sec-head"><span class="sec-num">05</span><h2>Channels</h2></div> | ||
| <p class="lede">Two channel kinds. A <strong>DM</strong> is one static session with that one worker, opened at bootstrap. A <strong>group</strong> is a message board plus one subscription session per subscribed member. A group post wakes those sessions. <strong>Who answers is proposed Layer 2 policy</strong>, not a new primitive and not a shared room.</p> | ||
| <p class="lede">Two channel kinds. A <strong>DM</strong> is one static session with that one worker, opened at bootstrap. A <strong>group</strong> is a message board plus one subscription session per subscribed member. A group post wakes those sessions. <strong>A wake is not a turn.</strong> Reply-storm exclusion <strong>exists</strong> via <code>TaskCollectionRef.claim</code>. Who may reply is <strong>proposed</strong> Layer 2 policy. Ordered multi-reply is <strong>proposed</strong> Layer 2: a board coordinator — a roster role, not a primitive — files N reply tasks with <code>deps</code>; settle unlocks the next; only an idle chain looks at newer posts. Cross-flow stays proposed. Not a new primitive and not a shared room.</p> |
There was a problem hiding this comment.
Lede became a second disposition table. This paragraph now repeats what the three cards, Piece table, and figures say sentence-for-sentence. Consider: channel kinds + "a wake is not a turn" only here; move the claim/who/order taxonomy into the cards or table beneath.
| <text class="t-xs" x="342" y="158">NOT A NEW PRIMITIVE</text> | ||
| <text class="t-xs" x="342" y="176">NOT A MULTIPARTY SESSION</text> | ||
| <h3>Ordered multi-reply</h3> | ||
| <p>Who may speak is policy. <em>In what order</em> they speak is a chain of tasks. The proposed Layer 2 worker is a <strong>board coordinator</strong> — a roster role, the same kind of built-in as librarian, not a Layer 1 type. It reads one post. It files N reply tasks with <code>deps</code>. Each task’s work is <code>dispatcher()</code> into that subscriber’s session. Settle marks the row <code>completed</code>; <code>isClaimable</code> already waits on <code>deps[]</code>, so the next reply unlocks. Only when that chain is idle does the coordinator look at newer posts. The broke path is the existing machine: a lapsed lease is reclaimed, <code>parked</code> waits on a person, <code>fail()</code> retries when budget remains. Do not invent a MessageBoard sequencer, a coordinator Layer 1 type, or a new lease type to hold this.</p> |
There was a problem hiding this comment.
Same paragraph appears three times (this h3, the "Ordered multi-reply" disposition row, and the ordered-chain figcaption). Pick one owner — I'd keep this prose block + the addTasks sample and shorten the table row to one line + "see below."
| <text class="t-lbl f-code" x="34" y="38">LEASE · EXISTS</text> | ||
| <text class="t-b" x="34" y="64">claim times out</text> | ||
| <text class="t-s" x="34" y="92">leaseUntil lapses</text> | ||
| <text class="t-xs" x="34" y="114">isClaimable ADMITS THE ROW</text> |
There was a problem hiding this comment.
Candidate to drop or replace with a link. Lease / parked / retry is the generic task machine, not specific to ordered replies. framework.html already documents status transitions. One sentence here ("broke = existing lease / parked / retry — see framework orchestration") would save ~2KB SVG and a maintenance surface.
| <tr><td>Cross-flow fire-and-forget</td><td><span class="tag t-prop">this cycle</span></td><td><code>packages/engine/src/context/create-request-host.ts</code> refuses with <code>session-not-addressable</code>: <em>cross-flow delivery is not supported</em>. Convention uses it when the refuse goes away.</td></tr> | ||
| <tr><td>A second send door</td><td><span class="tag t-gone">cut</span></td><td>No <code>packages/relay</code>. No message-board package. Message board is Layer 2 convention only. Relay (<strong>FIX-1197</strong>) is today’s <code>dispatcher()</code> — not a second bus.</td></tr> | ||
| <tr><td>Group reply discipline</td><td><span class="tag t-prop">proposed</span></td><td>Same spine. Policy says who may reply (role / <code>@</code> / coordinator), one claim or turn per post, default quiet unless addressed. Not a second bus. Not a Layer 1 board-lock.</td></tr> | ||
| <tr><td>Reply-storm exclusion via existing claim</td><td><span class="tag t-real">exists</span></td><td><code>TaskCollectionRef.claim</code>. One holder per post across N subscriber sessions. Same spine. Not a second bus. Not a Layer 1 board-lock.</td></tr> |
There was a problem hiding this comment.
Near-duplicate of §05 disposition rows (lines 665–667). Conductor pattern: inventory table points to the hub section; Talk table could say "Group replies → §05" without three full rows. Drift risk if wording changes in one place only.
| <div class="note" style="margin-top:26px"> | ||
| <span class="lbl">The one-sentence version</span> | ||
| <p>Workforce is one worker contract on Layer 1: a flow per worker, files for tools, skills, personality, and role, memory via isolation, DMs as static sessions, groups as a board plus one session per subscriber, group replies as proposed Layer 2 policy (who may speak; one turn; quiet unless addressed), which room as proposed Layer 2 (roster + context; prefer the project room; no peer-edge graph), projects as dynamic ones, teams as roster plus shared boards (a seat may name a harness and inherit that harness’s subscriptions; one manager stack, Conductor’s), plans as board plus resource text, talk as dispatch. Today it is a thin registry. This cycle writes the convention. Conductor does not wait.</p> | ||
| <p>Workforce is one worker contract on Layer 1: a flow per worker, files for tools, skills, personality, and role, memory via isolation, DMs as static sessions, groups as a board plus one session per subscriber, reply-storm exclusion via existing <code>claim</code> (exists), who may reply as proposed Layer 2 (role / <code>@</code> / quiet unless addressed), ordered multi-reply as proposed Layer 2 (a board coordinator files N reply tasks with <code>deps</code>; settle unlocks the next; idle before newer posts; no MessageBoard sequencer), which room as proposed Layer 2 (roster + context; prefer the project room; no peer-edge graph), projects as dynamic ones, teams as roster plus shared boards (a seat may name a harness and inherit that harness’s subscriptions; one manager stack, Conductor’s), plans as board plus resource text, talk as dispatch. Today it is a thin registry. This cycle writes the convention. Conductor does not wait.</p> |
There was a problem hiding this comment.
No longer one sentence — and it re-lists every pin from this PR. Either restore a short summary (pre-PR length + link to §05 for reply trilogy) or relabel the block "Full inventory" so readers know it's exhaustive, not grok-first.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 66ced1c074
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| <text class="t-xs" x="342" y="158">NOT A NEW PRIMITIVE</text> | ||
| <text class="t-xs" x="342" y="176">NOT A MULTIPARTY SESSION</text> | ||
| <h3>Ordered multi-reply</h3> | ||
| <p>Who may speak is policy. <em>In what order</em> they speak is a chain of tasks. The proposed Layer 2 worker is a <strong>board coordinator</strong> — a roster role, the same kind of built-in as librarian, not a Layer 1 type. It reads one post. It files N reply tasks with <code>deps</code>. Each task’s work is <code>dispatcher()</code> into that subscriber’s session. Settle marks the row <code>completed</code>; <code>isClaimable</code> already waits on <code>deps[]</code>, so the next reply unlocks. Only when that chain is idle does the coordinator look at newer posts. The broke path is the existing machine: a lapsed lease is reclaimed, <code>parked</code> waits on a person, <code>fail()</code> retries when budget remains. Do not invent a MessageBoard sequencer, a coordinator Layer 1 type, or a new lease type to hold this.</p> |
There was a problem hiding this comment.
Wait for recipient completion before settling the reply task
When the task worker is the illustrated internal dispatcher({ session: { id } }), the dispatcher returns as soon as the host accepts the fire-and-forget request, after which the task board records success and completes the row. If Alice's subscriber action is still generating its reply, Bob therefore becomes claimable and may reply first, so this chain orders dispatch acceptance rather than replies. Keep the row open until the recipient acknowledges completion or explicitly await the dispatched request.
AGENTS.md reference: AGENTS.md:L197-L199
Useful? React with 👍 / 👎.
| session: { id: (input) => input.dmSessionId }, | ||
| }); | ||
|
|
||
| <i>// EXISTS — reply-storm exclusion. TaskCollectionRef.claim, orchestration.</i> |
There was a problem hiding this comment.
Renew and fence the claim before calling it exclusion
For a reply that runs longer than the default two-minute lease, this bare manual claim() receives no automatic renewal; another subscriber can reclaim the post while the original execution continues and may still emit its reply. The resulting duplicate replies are exactly what this example says the existing claim excludes. Route the work through lease renewal and lease-loss cancellation/fencing, or qualify the guarantee as only one current lease holder rather than reply-storm exclusion.
AGENTS.md reference: AGENTS.md:L197-L199
Useful? React with 👍 / 👎.
| { id: <em>"reply-alice"</em>, goal: <em>"reply as alice"</em>, assignee: <em>"alice"</em> }, | ||
| { id: <em>"reply-bob"</em>, goal: <em>"reply as bob"</em>, assignee: <em>"bob"</em>, deps: [<em>"reply-alice"</em>] }, | ||
| { id: <em>"reply-cara"</em>, goal: <em>"reply as cara"</em>, assignee: <em>"cara"</em>, deps: [<em>"reply-bob"</em>] }, |
There was a problem hiding this comment.
Namespace reply-task IDs by post
When this standing board processes a second post for the same subscribers, the terminal tasks from the first post still occupy reply-alice, reply-bob, and reply-cara, and addTasks() rejects those duplicate IDs instead of creating the next chain. Include postId in each task ID and dependency reference, or generate unique IDs and thread them through deps.
AGENTS.md reference: AGENTS.md:L197-L199
Useful? React with 👍 / 👎.
| <text class="t-b" x="34" y="64">claim times out</text> | ||
| <text class="t-s" x="34" y="92">leaseUntil lapses</text> | ||
| <text class="t-xs" x="34" y="114">isClaimable ADMITS THE ROW</text> | ||
| <text class="t-xs" x="34" y="132">reclaim() TAKES IT BACK</text> |
There was a problem hiding this comment.
Replace reclaim() with claim() in the recovery diagram
Automatic lease-lapse recovery occurs atomically inside the next claim(), leaving the row in_progress while advancing its attempt and abandonment counters. reclaim() is a separate manual, unbounded override that resets the row to pending without advancing those counters, so following this diagram can bypass the abandonment bound; the caption on line 821 already describes the correct next-claim behavior.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
Room lock 2026-09-06: keep Lab B pins honest (wake ≠ turn; claim exclusion exists; who-may-reply proposed) and record the proposed ordered chain — a roster-role coordinator files N reply tasks with deps, dispatcher() into each subscriber session, settle unlocks the next, idle before newer posts. Broke path is the existing lease / parked / retry. No MessageBoard sequencer, coordinator L1 type, or new lease. Cross-flow stays proposed. Independent of #1598 so that PR can merge on its own. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
66ced1c to
18c24c1
Compare


The reply-discipline block still said exclusion was a later POC. Lab B already showed a wake is not a turn, and that
TaskCollectionRef.claimis the exclusion. The 2026-09-06 room lock adds a second half: when several people may speak, a board coordinator files that as an ordered task chain. Leaving both halves as one “proposed policy” blob hid the pin that exists and the composition that does not.What this does
Atlas-only on
docs/atlas/workforce.html. Rebased onto currentmain(after #1598, #1604, #1605). The conflict was only this file.Keeps Lab B honest: wake ≠ turn; reply-storm exclusion via
TaskCollectionRef.claimis exists; who-may-reply stays proposed. Records the new lock as proposed Layer 2: a board coordinator (roster role, L2 worker — not a type) reads one post, files N reply tasks withdeps, and each task’s work isdispatcher()into that subscriber’s session. Settle unlocks the next. Only an idle chain looks at newer posts. Broke path is the existing lease /parked/ retry. Cross-flow stays proposed. Two diagrams: the ordered chain, and the broke path as the task machine you already have.Later atlas honesty on main is kept, not overwritten: reverse
{ from: true }exists; same-flow group N sessions exists; claim exists; memory scopes and declare-at-level stay; section numbers stay §07 / §08.What's asked of you
Nothing here is yours to decide. This is the lock on a page Jake can merge without the lab.
Parts worth reviewing closely
The rest of this is for whoever reviews the page.
Linear: none — room lock 2026-09-06 · Atlas-only · no changeset
How to review this — altitude, what's in scope, what's deliberately unsettled
How to review this. The contract for this change is a one-screen agent brief, not a spec — Cycle PM honesty on the atlas page. So no approach was signed off upstream, and this PR is the only gate.
Most valuable here: whether anything changed meaning rather than presentation — a caveat dropped, a lock quietly rewritten, a sample that invents an API. Then whether Lab B is over-claimed or the ordered chain is under-fenced.
In scope to challenge: the approach, the scope, and whether this earned its place at all.
One request, if you are an automated reviewer: this is living design HTML, not runtime code. Do not propose packages, types, or a route-resolver. Do not invent a Channel / Team / MessageBoard Layer 1, a MessageBoard sequencer, a coordinator L1 type, or a new lease. Do not claim the ordered chain or cross-flow exists.
Engineering calls — decided along the way, no product sign-off needed
mainatd19c855e1(after docs(atlas): same-flow group fan-out exists; cross-kind stays proposed #1598 / docs(atlas): RC vision with teams (plural) #1604 / docs(atlas): memory / knowledge scopes #1605). Onlydocs/atlas/workforce.htmlconflicted.addTaskssample, cuts).c2a743a25(do not regress to the older2a44dbb14).