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): fold review round 1 into FIX-1635
Leg a becomes a standing CI job (FIX-1431 lands it, FIX-1334 extends it,
the closure reuses it) with its control pinned to the 0.1.1 tarball. Each
child lands its HTTP case and proves its control at fix time; the closure
runs the suite on installed tarballs and no longer rebuilds old commits.
ER-3 covers stream attach and resume and asserts owner-scoped reuse; ER-10
matches the shipped create-if-absent contract; the request-as-capability
model gets an evolution row owned by FIX-1018. Rules now each carry an
owner and a check; ER-18 (a restatement of D3) is dropped and the rest
renumbered. DOCS keeps intent and ownership; FIX-1018 owns the draft.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HNTQkGXCUryuVD2TEBLi6G
  • Loading branch information
claude committed Sep 29, 2026
commit 46870d989b594a15583162143cae6725745f4c19
47 changes: 23 additions & 24 deletions specs/epics/FIX-1635/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,39 +9,38 @@ run over real HTTP against installed tarballs.

| # | Rule | Owner | Checked at |
|---|---|---|---|
| ER-1 | Every publishable package, packed and installed into an empty ESM project, imports | FIX-1431 | Closure leg a · CI's extension check |
| ER-2 | DevTool cannot be published without its client assets, and serves them from an installed copy | FIX-1334 | Closure leg a · the release build |
| ER-3 | A request id a caller supplies never reaches another user's request record or its items, on any path that writes one | FIX-1018 | Closure leg b · host and SQLite tests |
| ER-4 | Two users in one tenant with the same request id never share a run-scoped workspace or its resources | FIX-1286 (consumes ER-3) | Closure leg b |
| ER-5 | A session id reaches only its owner's session record; another user's id is not found | FIX-1022 | Closure leg b |
| ER-6 | Only an allow-listed source is re-entered from public HTTP by retry, continue or resume | FIX-1021 | Closure leg b |
| ER-7 | A session's stored flow never authorizes reading another flow's requests or items | FIX-1046 | Closure leg b |
| ER-8 | A cross-flow dispatch admits the target exactly as ingress would, organization included | FIX-1328 | Closure leg b |
| ER-1 | Every publishable package, packed and installed into an empty ESM project, imports | FIX-1431 | Leg a, a standing CI job FIX-1431 lands · the closure reuses it |
| ER-2 | DevTool cannot be published without its client assets, and serves them from an installed copy | FIX-1334 | Leg a, which FIX-1334 extends · the release build |
| ER-3 | A request id a caller supplies never reaches another user's request record or its items, on any path that writes it, attaches to its stream or resumes it. Reusing another user's id gets the caller its own request | FIX-1018 | Its HTTP case · host and SQLite tests · closure leg b |
| ER-4 | Two users in one tenant with the same request id never share a run-scoped workspace or its resources | FIX-1286 (consumes ER-3) | Its HTTP case · closure leg b |
| ER-5 | A session id reaches only its owner's session record; another user's id is not found | FIX-1022 | Its HTTP case · closure leg b |
| ER-6 | Only an allow-listed source is re-entered from public HTTP by retry, continue or resume | FIX-1021 | Its HTTP case · closure leg b |
| ER-7 | A session's stored flow never authorizes reading another flow's requests or items | FIX-1046 | Its HTTP case · closure leg b |
| ER-8 | A cross-flow dispatch admits the target exactly as ingress would, organization included | FIX-1328 | Its HTTP case · closure leg b |
| ER-9 | A schema-invalid resource write throws and leaves state as it was | FIX-1256 (shipped) | Closure re-runs its test |
| ER-10 | `writable: false` on a collection refuses every write-shaped path, `create` with `replace` and `delete` included | FIX-1261 with FIX-1510 (shipped) | Closure re-runs its tests |
| ER-11 | On a queue host, a delivery into an existing session runs the recipient under its concurrency policy and incarnation guard; what still can't be honoured is refused by name | FIX-1634 | Closure leg c |
| ER-12 | A non-streaming multi-step turn returns the text the streamed turn would | FIX-1628 | FIX-1628's test · closure re-run |
| ER-10 | `writable: false` on a collection refuses every write to an existing instance, `create` with `replace` included, and `delete`. Creating a key that does not exist stays open | FIX-1261 with FIX-1510 (shipped) | Closure re-runs its tests |
| ER-11 | On a queue host, a delivery into an existing session runs the recipient under its concurrency policy and incarnation guard; what still can't be honoured is refused by name | FIX-1634 | Its HTTP case, real Redis · closure leg c |
| ER-12 | A non-streaming multi-step turn returns the text the streamed turn would | FIX-1628 | Its HTTP case · closure leg b |

## What no child may do

| # | Rule | Because |
|---|---|---|
| ER-13 | No Workforce (Layer 2) concept in core, engine, client or react. FIX-1634 is generic; its Workforce adopt child is filed after its Layer 1 shape merges | The owner's layer rule |
| ER-14 | No child reopens org-optional, or deletes a named refusal without restating the guarantee it protected | FIX-1442 is settled; a deleted refusal trades a loud failure for a silent one |
| ER-15 | No child widens: Tier B leftovers, first-hour DX and kitchen-sink polish stay out. Something noticed outside the goal is filed normally, not under this epic | The set is locked by the owner |
| ER-16 | No child pins today's defect as a contract in a test, and every fix lands a regression test that fails on the commit before the hole closed | A test that can't fail proves nothing |
| # | Rule | Owner · checked at | Because |
|---|---|---|---|
| ER-13 | No Workforce (Layer 2) concept in core, engine, client or react. FIX-1634 is generic; its Workforce adopt child is filed after its Layer 1 shape merges | FIX-1634, the one child near it · its spec review | The owner's layer rule |
| ER-14 | No child reopens org-optional, or deletes a named refusal without restating the guarantee it protected | Every child · FIX-1634's spec names what FIX-1302's `external-dispatcher` refusal guarantees, since it narrows it; each PR review | FIX-1442 is settled; a deleted refusal trades a loud failure for a silent one |
| ER-15 | No child widens: Tier B leftovers, first-hour DX and kitchen-sink polish stay out. Something noticed outside the goal is filed normally, not under this epic | The epic coordinator · each child's PR review against the set table | The set is locked by the owner |
| ER-16 | Every fix lands a regression test that fails on the commit before the hole closed, and no test pins today's defect as a contract. A child named in ER-3 to ER-8, ER-11 or ER-12 lands it as its case in the shared HTTP suite: over HTTP, as the second user where there is one | Each child · its PR names the commit the case failed on | A test that can't fail proves nothing; a control proved at fix time needs no old commit rebuilt at closure |

## How the set is run

| # | Rule | Because |
|---|---|---|
| ER-17 | A direct-route worker reproduces on current `main` first. No reproduction: it closes with a regression test (ER-16) and the commit that closed the hole, not a rewrite | D2 |
| ER-18 | FIX-1018 merges before FIX-1286 and FIX-1634 implement; their specs may start now | D3 |
| ER-19 | A child's Linear state is mirrored the moment it changes; its route comes from its label | The wake derives blocked-by and route from Linear |
| # | Rule | Owner · checked at | Because |
|---|---|---|---|
| ER-17 | A direct-route worker reproduces on current `main` first, and records the result on its Linear issue: reproduces or not, on which commit. No reproduction: it closes with a regression test (ER-16) and the commit that closed the hole, not a rewrite | Each direct-route child · the Linear comment, before its PR opens | D2. The closure cites the record rather than re-deriving it |
| ER-18 | A child's Linear state is mirrored the moment it changes; its route comes from its label | The epic coordinator · every wake | The wake derives blocked-by and route from Linear |

## The closure

| # | The epic is done when | Proved by |
|---|---|---|
| ER-20 | [The goal](SPEC.md#the-goal-and-how-well-know-its-met) is met: legs a, b and c pass on one `main` commit, each fails under its control, and every finding is fixed and retested | FIX-1636's goal check |
| ER-21 | The authentication guide says a caller-chosen id is an address, not an ownership | FIX-1018's docs change ([DOCS.md](DOCS.md)) |
| ER-19 | [The goal](SPEC.md#the-goal-and-how-well-know-its-met) is met on one `main` commit: leg a passes in its standing job and fails against the 0.1.1 tarball; the HTTP suite (legs b and c) passes against the installed tarballs; every finding is fixed and retested | FIX-1636's goal check |
| ER-20 | The authentication guide says a caller-chosen id is an address, not an ownership, and the architecture's request-id section no longer calls a request id a capability | FIX-1018's docs change ([DOCS.md](DOCS.md)) |
27 changes: 23 additions & 4 deletions specs/epics/FIX-1635/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md)

The calls that sit above any single child. The child set itself is not one of them: the owner
locked it with the FSD Architect on 2026-09-29, including what is out of the epic. Two cards
locked it with the FSD Architect on 2026-09-29, including what is out of the epic. "Twelve"
below is that locked set of child issues; FIX-1510 shipped as FIX-1261's sub-issue. Two cards
are the sign-off; the third is an engineering call recorded so no child reopens it.

## The tree
Expand Down Expand Up @@ -65,10 +66,12 @@ It comes down to a confirmed leak: the design question should not hold the fix f

## Who owns what

![Who owns what: fourteen rules by the open children and the closure issue. Each security, integrity, packaging, queue and generator rule has one child that builds it; FIX-1286 and FIX-1634 consume FIX-1018's binding; the closure issue builds the proof and consumes every other rule.](figures/ownership.svg)
![Who owns what: thirteen rules by the open children and the closure issue. Each security, integrity, packaging, queue and generator rule has one child that builds it; FIX-1286 and FIX-1634 consume FIX-1018's binding, and FIX-1334 builds on FIX-1431's leg a job; the closure issue runs the children's suite on installed tarballs and consumes every other rule.](figures/ownership.svg)

Every rule has one owner. A *consumes* cell is a place a child must not re-decide: FIX-1286
and FIX-1634 build on FIX-1018's binding rather than inventing their own.
Every rule a child builds has one owner. A *consumes* cell is a place a child must not
re-decide: FIX-1286 and FIX-1634 build on FIX-1018's binding rather than inventing their own.
The fence and run rules bind every child, so they are not columns here; each names its owner
and where it's checked in [BUSINESS-RULES.md](BUSINESS-RULES.md#what-no-child-may-do).

## Decided in review, recorded so no child reopens them

Expand All @@ -83,6 +86,18 @@ and FIX-1634 build on FIX-1018's binding rather than inventing their own.
- **FIX-1628 stays scoped** to the non-streaming step loop.
- **The done rows are re-verified, not reopened.** The closure plan re-runs their tests; a
failure is a new bug child.
- **Leg a is a standing CI job, not a closure step** (round 1). FIX-1431 lands the pack,
install and import job and FIX-1334 adds DevTool's assets to it; the closure reuses it. Its
control is the 0.1.1 tarball, pinned, because "the latest release" stops failing once
anything newer is published.
- **Each child owns its HTTP case and its control** (round 1). The children with a hole or a
behaviour to prove over HTTP add a case to one shared suite, and prove it fails on the commit
before the hole closed. The closure runs the suite against installed tarballs and never
rebuilds an old commit.
- **No shared owner-check rule** (round 1). The principal children keep their parallel
bindings and one not-found shape. A shared owner-scoped lookup is FIX-1018's to offer if its
reproduction produces one; the others may use it, and nothing waits for it.
- **FIX-1286's route stays spec** (round 1). D3 already lets it close as proved by FIX-1018.

## What the end-state POC showed

Expand All @@ -93,5 +108,9 @@ is the whole-set proof.

- **Drafted (Sep 29)** from the owner's locked set and the Architect's clusters; the closure
issue FIX-1636 filed; FIX-1018 wired to block FIX-1286 and FIX-1634.
- **Round 1 (Sep 29)** folded a second-look review, the Architect's stamp on it, and the Cursor
and Codex inline comments: leg a moved into standing CI, the children own their HTTP cases,
ER-3 names attach and resume, ER-10 matches the shipped create-if-absent contract, and the
rules were trimmed to ones with an owner.

**Open: none.**
48 changes: 23 additions & 25 deletions specs/epics/FIX-1635/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,36 +6,34 @@ One shared story changes: which ids a caller may choose, and what choosing one g
Most children change behaviour the docs already promise (a package imports, a guard refuses),
so they publish nothing new. The specifics below belong to the child that ships them.

## UPDATE · `apps/docs/docs/server/authentication.md` · new subsection after "Addressed routes, and what they scope by"

> ### Ids you choose are addresses
>
> A client can pick its own ids. An action call may carry a `requestId`, and most routes name
> a session by id. That is useful: a retried call with the same `requestId` is recognised as
> the same request instead of starting a second one.
>
> An id is never proof of ownership. A request or a session belongs to the user and
> organization it was created under, and an id someone else created reaches nothing of yours.
> Send another user's `requestId` and you get your own request, not theirs. Send another
> user's session id and you get a `404`, the same answer as an id that doesn't exist.
>
> ```
> POST /api/flows/chat/actions/send bob's, requestId req_1 (alice's) -> bob's own request
> GET /api/flows/sessions/s_alice bob's, same tenant -> 404
> ```
>
> So you don't need to make ids unguessable to keep users apart. Ids still leak in headers,
> URLs and logs, and nothing here relies on them staying secret.

The example routes are illustrative until FIX-1018's `DOCS.md` fixes the exact paths and
status codes against the shipped behaviour.
## The shared promise · UPDATE `apps/docs/docs/server/authentication.md`

A new subsection after "Addressed routes, and what they scope by", **"Ids you choose are
addresses"**. What it has to tell a reader:

- A client may choose its own ids: a `requestId` on an action call, a session id on most
routes. A retried call with the same `requestId` is the same request, not a second one.
- An id is never proof of ownership. Another user's `requestId` gets the caller its own
request; another user's session id is a `404`, the same as an id that doesn't exist.
- So ids need not be unguessable to keep users apart. They leak in headers, URLs and logs,
and nothing relies on them staying secret.

FIX-1018 writes the prose and its example routes, against the behaviour it ships, in its own
PR. This document holds the intent and who publishes what, not a second copy of the draft.

## UPDATE · `docs/architecture/state-and-scopes.md` · "What `requestId` gates, not tenant"

The section calls a request id an unguessable capability that authorizes stream attach and
resume alone. After FIX-1018 it is an address scoped to its owner, and the section says what
attach and resume check instead ([EVOLUTION.md](EVOLUTION.md)).

## Ownership

| Material | Publisher | Specific draft |
|---|---|---|
| "Ids you choose are addresses", above | FIX-1018, once its behaviour is verified | This document |
| The session-id half of the example, and legacy session keys | FIX-1022 | Its PR; links here |
| "Ids you choose are addresses", above | FIX-1018, once its behaviour is verified | FIX-1018's PR |
| The request-id section of `state-and-scopes.md` | FIX-1018 | FIX-1018's PR |
| The session-id half of the example, and legacy session keys | FIX-1022 | Its PR; links to FIX-1018's subsection |
| A session's flow does not authorize another flow's history | FIX-1046 | Its PR; one sentence in "Addressed routes" |
| The `external-dispatcher` row in `server/background-work.md`'s refusal table, narrowed to what a queue host still can't honour | FIX-1634 | Its `DOCS.md` |
| `writable` on collections | Shipped with FIX-1510 | None |
Expand Down
1 change: 1 addition & 0 deletions specs/epics/FIX-1635/EVOLUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ FIX-1286's own specs.
| FIX-1442: every session and request carries an organization, owned by the verified principal. Source: its Linear spec document and review PR #1899 (no retained repository set) | **Retained** | Shipped (Done, 2026-09). FIX-1328's second option is this rule; the principal cluster builds on it | ER-8, ER-14 | Nothing changes for org identity |
| FIX-682: session keys and re-entry scoped by tenant. Source: `packages/engine/src/stores/scope-keys.ts` → `resolveSessionStorageKey` | **Amended** by FIX-1022 | The tenant wall holds; users inside one tenant were never separated | ER-5 | Existing tenant-only keys are still read by their owner (BP-030) |
| FIX-999: public re-entry admits an allow-list of sources. Source: `packages/engine/src/routes/public-reentry.ts` | **Retained**; FIX-1021 verifies against it | The allow-list landed after FIX-1021 was written | ER-6 | None |
| The request-as-capability model: stream attach and suspension resume are authorized by `requestId` alone, as an unguessable token, with no tenant recheck. Source: `docs/architecture/state-and-scopes.md`, "What `requestId` gates, not tenant" | **Amended** by FIX-1018 | The premise fails: a request id is caller-supplied (`routes/action-routes.ts`), `generateId` is not a CSPRNG, and ids leak in the `x-request-id` header, URLs and logs (FIX-1018's evidence) | ER-3, ER-20; FIX-1018 updates the section | A request created before FIX-1018 still attaches and resumes for its owner (BP-030) |
| FIX-1302: delivery into an existing session is refused `external-dispatcher` on a queue host. Source: `docs/architecture/inbound-transports.md`, the `external-dispatcher` paragraph | **Amended** by FIX-1634 | The refusal protected recipient concurrency and the incarnation guard; FIX-1634 restores both across the queue boundary instead of deleting it | ER-11, ER-14 | Anything still unhonourable keeps a named refusal |

Nothing is wholly superseded. Re-check each cited intent against current code before
Comment thread
jhoffner marked this conversation as resolved.
Resolved
Expand Down
Loading
Loading