Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
spec(epic): the gap is selection, not access — match #2037's wording …
…(FIX-1457)

Third pass on the same passage. The previous version still overstated it: "which
org is a question the surface cannot currently be asked" is wrong, because the
surface CAN be asked — it just always answers with the same org. Corrected in
all five places the set repeats it (BUSINESS-RULES.md, SPEC.md, DECISIONS.md D1
addendum and Open 1 plain-terms, PLAN.md, EVOLUTION.md), matching #2037's
re-derivation per the Architect's sibling gate.

The chain that survives, verified end to end on origin/main:

- the three inventory collections are scope:"org";
- an org-scoped read takes its storage key from the execution's orgId
  (createExecutionContext -> resolveOrgStorageKey), which is the org the session
  carries;
- that org is set once at creation from the configured resolver, with
  body.orgId never consulted (FIX-1442);
- the listing has no orgId query fallback by design.

Two corrections to my own previous text:

- The short-circuit is not that anonymousFlowIds is merely unset.
  authorizeManagementRoute returns ALLOWED at its FIRST guard when the host is
  on the default resolver and nothing authenticates, so the anonymous branch is
  never reached; the branch that is reached in a mixed app always returns a Set.
  So `allowed === undefined` means "no flow in this app authenticates".
- The listing clause is dropped rather than repaired. handleListSessions lists
  sessions; the rule is about reading inventory resources. It did no work in the
  argument even when true.

Also removed an unverified premise I had asserted: that nothing under
packages/devtool, packages/fsdev or apps/devtool configures a resolvePrincipal.
No single artifact is confidently "the shell flow", so the text is conditional
now — "where no resolver is configured it is DEFAULT_ORG_ID" — which is true of
the code regardless of which app is meant.

ER-26, the producers, row 5's re-owning and the conclusion are unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
  • Loading branch information
claude committed Sep 22, 2026
commit c789af5cc737d66fd181f52bc32f7ceaf77304bb
79 changes: 38 additions & 41 deletions specs/epics/FIX-1457/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,34 +117,28 @@ no reader in any plan. FIX-1502 was filed to own it; 1481 keeps verifying the ro
flow declaring the three collections is the workforce **channel** flow
(`packages/workforce/src/channel/channel-flow.ts`), so today they are reachable solely through a
channel's own session.
4. **And an org-scoped read cannot be told *which* org.** Its storage identity **is** an org id,
and the engine only ever has one to hand it: the session's, which flows through
`createExecutionContext` → `resolveOrgStorageKey`. **No request can supply another.** A session's
org is set once at creation from the configured resolver — `body.orgId` is **not consulted at
all** ([FIX-1442](https://linear.app/fixpoint-labs/issue/FIX-1442)) — and **there is no `orgId`
query parameter on any engine route**, because an organization is never a caller's to name.
Those two facts are the whole of it, and they hold whichever internal function derives the scope
id. (`packages/engine/src/resources/internal.ts` states the same invariant in so many words —
*"never from caller input (BP-031)"* — though it states it for the *external*-collection path,
which these three are not.)

**So the axis is missing because nothing can *name* an org — not because no org is reachable.**
Declaring a `client` config on the inventory collections would not open an org picker; it would
open the read onto whichever org the session already holds. On a host that configures **no
`resolvePrincipal`** — which nothing under `packages/devtool`, `packages/fsdev` or `apps/devtool`
does — that is always the default org
([`projects-on-org-scope.md`](../../../apps/docs/guides/projects-on-org-scope.md): *"Configure no
`resolvePrincipal` and everything runs under `DEFAULT_ORG_ID`"*); a host that *does* configure one
binds each session to that principal's org instead, so the default is a property of the
unauthenticated shell, not of the framework. **No surface anywhere accepts *show me organization
X*, and supplying that is exactly
[FIX-1486](https://linear.app/fixpoint-labs/issue/FIX-1486)'s subject.** **Building it inside W5 is
the [ER-25](#what-no-child-may-do) substrate growth the owner fenced**, arriving under a polish
label; raised up per [ER-17](#er-17) rather than answered locally.

**Plan the successor against the naming gap, not against reachability.** The two read differently:
a reachability story invites a child to widen a read, and the naming story says the work is an
address the request can carry, which is the shape FIX-1486 actually has.
4. **And an org-scoped read cannot be told *which* org to read.** Its storage key comes from the
execution's `orgId` (`createExecutionContext` → `resolveOrgStorageKey`), which is the org the
**session** carries. That org is set once at creation from the configured resolver:
`body.orgId` is **never consulted**
([FIX-1442](https://linear.app/fixpoint-labs/issue/FIX-1442)), and the listing has **no `orgId`
query fallback** by design. Where no resolver is configured, it is `DEFAULT_ORG_ID`
([`projects-on-org-scope.md`](../../../apps/docs/guides/projects-on-org-scope.md): *"Configure
no `resolvePrincipal` and everything runs under `DEFAULT_ORG_ID`"*); where one is, it is that
principal's org.

**So the gap is that you cannot *choose* the org — not that no org is reachable.** State it that
way round, because the sloppy version is wrong in a way that matters: **the surface can be asked,
it just always answers with the same org.** Declaring a `client` config on these collections would
not add an org picker; it would open the read onto whichever org the session already holds.
**Supplying the ability to select one is exactly
[FIX-1486](https://linear.app/fixpoint-labs/issue/FIX-1486)'s subject**, and building it inside W5
is the [ER-25](#what-no-child-may-do) substrate growth the owner fenced — raised up per
[ER-17](#er-17) rather than answered locally.

**Plan the successor against selection, not against access.** An access story invites a child to
widen a read; a selection story says the work is an address the request can carry, which is the
shape FIX-1486 actually has.

> **Two corrections inside the correction, because this mechanism has now been got wrong twice.**

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 / altitude: The blockquote about this amendment’s wrong drafts (handleListSessions, #2037) is valuable forensic history but heavy inside BUSINESS-RULES (children inherit this file as rules, not changelog).

Recommend moving to EVOLUTION.md (you already have a 2026-09-22 row there) and leaving one invariant here: “gap is org selection, not access; do not cite closed BP-031 hole.”

>
Expand All @@ -158,17 +152,20 @@ address the request can carry, which is the shape FIX-1486 actually has.
> **Two.** The first draft of *this* amendment replaced it with a second false claim: that the
> session listing *"withholds every row that is not on that org."* It does not. `handleListSessions`
> filters on `isOrgAttributed(s) && (allowed === undefined || s.orgId === DEFAULT_ORG_ID)`, and
> `allowed` is `ctx.anonymousFlowIds` — which is never set on this path at all, because
> `authorizeManagementRoute` returns `ALLOWED` at its first guard when the host is on the default
> resolver and no flow authenticates (`packages/engine/src/routes/route-auth.ts`). The second
> conjunct is therefore vacuously true and **only unattributed legacy rows are withheld**; the
> `DEFAULT_ORG_ID` narrowing reaches that filter solely in the *mixed-app anonymous* case.
> **And it was irrelevant as well as wrong**: that route lists **sessions, not inventory
> resources**, so it was never evidence about an inventory read. Caught on sibling PR
> [#2037](https://github.com/fixpoint-labs/flow-state-dev/pull/2037), whose re-derivation this
> wording now matches, and corrected here before merge. The conclusion never depended on it.
> `allowed === undefined` means *no flow in this app authenticates*: `authorizeManagementRoute`
> returns `ALLOWED` at its **first** guard when the host is on the default resolver and nothing
> authenticates, so the anonymous branch is never reached at all, and the branch that *is* reached
> in a mixed app always returns a `Set` (`packages/engine/src/routes/route-auth.ts`). The second
> conjunct is therefore vacuously true on that path and **only unattributed legacy rows are
> withheld**; the `DEFAULT_ORG_ID` narrowing reaches that filter solely in the *mixed-app
> anonymous* case.
>
> **What both errors had in common** is that they reasoned about handlers instead of reading them,
> and both landed on *reachability* — which org can be got at — when the real constraint is
> **naming**. A child that inherits the reachability framing will try to widen a read; the naming
> framing points it at the address instead.
> **The clause is dropped rather than repaired, because it was doing no work even when true**:
> that route lists **sessions**, and this rule is about reading **inventory resources**. It was
> never evidence for the claim it was attached to. Caught on sibling PR
> [#2037](https://github.com/fixpoint-labs/flow-state-dev/pull/2037), whose re-derivation the
> wording above now matches, and corrected here before merge. The conclusion never depended on it.
>
> **What all three wrong versions had in common** is that they reasoned about handlers instead of
> reading them, and each landed on *access* — which org can be got at — when the real constraint
> is **selection**. A child that inherits the access framing will try to widen a read.
9 changes: 4 additions & 5 deletions specs/epics/FIX-1457/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,9 +113,8 @@ cannot be rendered without a new L1 type. Two of its six rows fail today and
is live, not theoretical — and [ER-8](BUSINESS-RULES.md) says a failing row is never passed with a status value.

**And on 2026-09-22 it half-fired, on a third row.** Checklist row 5 turned out to need not a new L1
type but **an org-identity axis the surface can be addressed by, which does not exist** — an
org-scoped read's identity is the session's own org, and **nothing can *name* a different one**, so
no surface accepts *show me organization X*
type but **a way to *select* an org, which does not exist** — an org-scoped read always answers
with the org its session already carries, and **nothing can choose another**
([FIX-1486](https://linear.app/fixpoint-labs/issue/FIX-1486) supplies the axis; the mechanism is
worked through in [BUSINESS-RULES.md](BUSINESS-RULES.md#devtool-checklist)). That is the same shape as the
condition above — a QA row that cannot be rendered on today's substrate — and the card holds:
Expand Down Expand Up @@ -313,8 +312,8 @@ replaced it is narrower and sharper.
everything in this organization — every seat, every channel, who is in which."* Building it needs
something W5 does not have and is not allowed to build: **the DevTool has no way to say *which*
organization it is asking about.** An organization is deliberately never something a caller names
on a request — the gap is naming one, not reaching one — so an unauthenticated shell like the
DevTool only ever sees the one default organization it runs as. Giving it a way to ask is
on a request — the gap is *choosing* one, not reaching one — so where no resolver is configured
the DevTool only ever sees the one default organization it runs as. Giving it a way to choose is
[FIX-1486](https://linear.app/fixpoint-labs/issue/FIX-1486), which belongs to the substrate, not
to a QA epic. [FIX-1502](https://linear.app/fixpoint-labs/issue/FIX-1502) holds the row and waits
on it. The other five rows are unaffected. So: **call the Devtool proof passed at five of six and
Expand Down
Loading
Loading