Skip to content

docs(atlas): propose L2 ordered multi-reply via board coordinator - #1601

Merged
jhoffner merged 1 commit into
mainfrom
cursor/atlas-ordered-multireply-04e1
Sep 7, 2026
Merged

jhoffner merged 1 commit into
mainfrom
cursor/atlas-ordered-multireply-04e1

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 6, 2026 •

Copy link
Copy Markdown
Collaborator

The reply-discipline block still said exclusion was a later POC. Lab B already showed a wake is not a turn, and that TaskCollectionRef.claim is 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 current main (after #1598, #1604, #1605). The conflict was only this file.

Keeps Lab B honest: wake ≠ turn; reply-storm exclusion via TaskCollectionRef.claim is 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 with deps, and each task’s work is dispatcher() 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.

1. The pins. Does claim stay exists, and does anything promote who-may-reply or the ordered chain to exists?
2. The coordinator. Is it clearly a roster role composing deps + dispatcher(), not a MessageBoard sequencer, coordinator L1 type, or new lease?
3. Idle and broke. Does “idle before newer posts” stay proposed policy, and does the broke path only name lease / parked / retry?
4. Rebase. Did the rebase keep main’s later memory / tree / intake / same-flow honesty while still teaching the ordered chain?

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
Open in Web Open in Cursor 

@vercel

vercel Bot commented Sep 6, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 7, 2026 12:39am UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 7, 2026 12:39am UTC
flow-state-dev-ui Ignored Ignored Preview Sep 7, 2026 12:39am UTC

Request Review

@jhoffner
jhoffner marked this pull request as ready for review September 6, 2026 16:04
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 6, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-06T16:11:05.257224Z 66ced1c Draft marked ready
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/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.claim to 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[], and isClaimable paths in packages/orchestration match 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 (claim EXISTS, addTasks PROPOSED) 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)

  1. §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.
  2. Drop or shrink the broke-path figure — lease / parked / retry is generic task-machine behavior (framework.html already has a status diagram). One sentence + link is enough unless ordered-reply failure modes differ (they don't in this doc).
  3. 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.
  4. 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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread docs/atlas/workforce.html Outdated
<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&nbsp;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&nbsp;2 policy. Ordered multi-reply is <strong>proposed</strong> Layer&nbsp;2: a board coordinator &#8212; a roster role, not a primitive &#8212; 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>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/atlas/workforce.html
<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&nbsp;2 worker is a <strong>board coordinator</strong> &#8212; a roster role, the same kind of built-in as librarian, not a Layer&nbsp;1 type. It reads one post. It files N reply tasks with <code>deps</code>. Each task&#8217;s work is <code>dispatcher()</code> into that subscriber&#8217;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&nbsp;1 type, or a new lease type to hold this.</p>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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."

Comment thread docs/atlas/workforce.html
<text class="t-lbl f-code" x="34" y="38">LEASE &#183; 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>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/atlas/workforce.html
<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&nbsp;2 convention only. Relay (<strong>FIX-1197</strong>) is today&#8217;s <code>dispatcher()</code> &#8212; 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&nbsp;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&nbsp;1 board-lock.</td></tr>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/atlas/workforce.html Outdated
<div class="note" style="margin-top:26px">
<span class="lbl">The one-sentence version</span>
<p>Workforce is one worker contract on Layer&nbsp;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&nbsp;2 policy (who may speak; one turn; quiet unless addressed), which room as proposed Layer&nbsp;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&#8217;s subscriptions; one manager stack, Conductor&#8217;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&nbsp;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&nbsp;2 (role / <code>@</code> / quiet unless addressed), ordered multi-reply as proposed Layer&nbsp;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&nbsp;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&#8217;s subscriptions; one manager stack, Conductor&#8217;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>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread docs/atlas/workforce.html
<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&nbsp;2 worker is a <strong>board coordinator</strong> &#8212; a roster role, the same kind of built-in as librarian, not a Layer&nbsp;1 type. It reads one post. It files N reply tasks with <code>deps</code>. Each task&#8217;s work is <code>dispatcher()</code> into that subscriber&#8217;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&nbsp;1 type, or a new lease type to hold this.</p>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread docs/atlas/workforce.html
session: { id: (input) => input.dmSessionId },
});

<i>// EXISTS &#8212; reply-storm exclusion. TaskCollectionRef.claim, orchestration.</i>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread docs/atlas/workforce.html
Comment on lines +946 to +948
{ 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>] },

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread docs/atlas/workforce.html
<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>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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>
@cursor
cursor Bot force-pushed the cursor/atlas-ordered-multireply-04e1 branch from 66ced1c to 18c24c1 Compare September 7, 2026 00:39
@jhoffner
jhoffner merged commit dd421b3 into main Sep 7, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants