Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
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
24 changes: 24 additions & 0 deletions .claude/settings.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,29 @@
"commit": "",
"pr": "",
"sessionUrl": false
},
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [
{
"type": "command",
"command": "cd \"$CLAUDE_PROJECT_DIR\" && node --import tsx scripts/hooks/server-fact-write-guard.ts",
"timeout": 20
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "cd \"$CLAUDE_PROJECT_DIR\" && node --import tsx scripts/hooks/server-fact-approve-guard.ts",
"timeout": 120
}
]
}
]
}
}
20 changes: 19 additions & 1 deletion .github/workflows/ci-lint-format-queue.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,24 @@ jobs:
cache-key: ${{ steps.lint-cache.outputs.cache-key }}
path: ${{ env.LINT_CACHE_PATHS }}

server-facts:
runs-on: ubuntu-latest
steps:
- name: Checkout ref
uses: actions/checkout@v7
with:
fetch-depth: 0

- name: Setup frontend
uses: ./.github/actions/setup-frontend

# Push runs gate the pushed range; a branch-creation push has no base.
- name: Check server facts on changed lines
if: ${{ (github.event.merge_group.base_sha || github.event.before) != '0000000000000000000000000000000000000000' }}
env:
BASE_SHA: ${{ github.event.merge_group.base_sha || github.event.before }}
run: pnpm lint:server-facts --base "$BASE_SHA"

typecheck:
runs-on: ubuntu-latest
steps:
Expand Down Expand Up @@ -132,7 +150,7 @@ jobs:

# Single stable branch-protection context over the parallel jobs above.
lint-and-format:
needs: [lint, typecheck, typecheck-aux, repo-checks]
needs: [lint, server-facts, typecheck, typecheck-aux, repo-checks]
if: ${{ always() && github.event_name == 'push' }}
runs-on: ubuntu-latest
steps:
Expand Down
18 changes: 18 additions & 0 deletions .github/workflows/ci-lint-format.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,24 @@ jobs:
cache-key: ${{ steps.lint-cache.outputs.cache-key }}
path: ${{ env.LINT_CACHE_PATHS }}

server-facts:
runs-on: ubuntu-latest
steps:
- name: Checkout PR
uses: actions/checkout@v7
with:
ref: ${{ !github.event.pull_request.head.repo.fork && github.head_ref || github.ref }}
token: ${{ !github.event.pull_request.head.repo.fork && secrets.PR_GH_TOKEN || github.token }}
fetch-depth: 0

- name: Setup frontend
uses: ./.github/actions/setup-frontend

- name: Check server facts on changed lines
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
run: pnpm lint:server-facts --base "$BASE_SHA"

typecheck:
runs-on: ubuntu-latest
steps:
Expand Down
6 changes: 6 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,12 @@ When working from a TDD or design doc, record its tradeoffs, alternatives consid

## Common Pitfalls

- NEVER derive a server fact on the client: a gate renders one fact from the
API as received, without combining it with role, tier, plan state, seats or
`isCloud`. Local UI state (loading, in-flight, form validity) may only
disable the control, never grant it. A missing fact is a backend ticket plus
`pendingServerFact('BE-xxxx', expr)`, never another field. See
`docs/adr/API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md`
- NEVER use `any` type - use proper TypeScript types
- NEVER use `as any` type assertions - fix the underlying type issue
- NEVER add `@ts-ignore` or `@ts-nocheck`. Use `@ts-expect-error` only in a test
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
# ADR-API-SERVER-FACTS-0042: Server Facts Are Rendered, Not Derived

Date: 2026-10-09

## Status

Proposed

## Context

The frontend keeps recombining facts the backend owns into decisions of its
own. The latest case shipped two billing P0s (BE-19903 Invite member,
BE-19904 Manage seats) through three PRs that agents wrote and agents
approved:

- #15675 gated member management on `isCloud ? can_change_seats : role`.
`can_change_seats` answers "may this workspace change its seat quantity",
so Enterprise owners lost member management.
- #18662 OR'd `isPlanEnded && canManageSubscription` onto `can_invite_members`.
- #19455 added tier and plan-status checks so that gate survived the backend
collapsing `max_seats` to 1.

This is not specific to billing. Since April, about 20 fixes moved a
decision back to the server after the client had derived it, including:

- workspace creation (`can_create_workspace`)
- agent gating (server `/features`)
- the free-run offer (`free_tier_offer`)
- asset counts
- release notes keyed by the wrong version
- queue caps

Each derivation is a second copy of backend policy. It drifts silently,
because a wrongly hidden or disabled control emits nothing.

A rule written as prose did not stop it. A reviewer-side "never approve a
frontend-derived server fact" rule was in place before #18662 and #19455,
and both were approved. This guidance also pointed the other way:
`docs/guidance/state-and-effects.md` said "derive everything derivable", and
its first example was a `can*` flag.

## Decision

A **server fact** is anything the backend knows about an account, workspace,
subscription or resource that would stay true with no UI:

- permissions and capabilities
- role, tier, plan status and seats
- readiness and versions
- server timestamps and error codes

1. **The server fact alone decides entitlement.** A gate renders one server
fact as received. It does not combine that fact with another server fact
or a value derived from one (role, tier, plan state, seats, `isCloud`)
through `&&`, `||`, `??`, a ternary, arithmetic, a comparison or a helper.
It also does not choose which fact answers the question. Local, transient
UI state (loading, an in-flight request, form validity) may delay or
disable the control, as in `canTopUp && !isLoading`. It never grants
entitlement or stands in for a server field.
2. **`isCloud` decides which build ships, not what a user may do.** Off
Cloud, a local provider answers the same fact.
3. **A failed read uses the default its contract names.** Never fall back to
a role or a tier.
4. **A fact the API does not emit yet is a backend ticket.** Until the ticket
lands, wrap the interim expression in `pendingServerFact('<ticket>', expr)`.
Never substitute another field. `can_change_seats` is not member
management.
5. **Choosing which server field answers a UI question needs review from
the backend team that owns the field.**

Presentation stays on the client: formatting, translation, sorting, layout,
and local UI state such as loading, open panels and form validation.

The rule is to be enforced by checks that fail, not by prose. None of
them ships with this ADR; each lands in its own change, tracked under
FE-3349 (TDD "Server-fact guardrails"):

- oxlint rules gated on changed lines in the required lint check: the
authoritative block (FE-3351)
- a checked-in agent write hook and an approve hook: an advisory first line
that fails open (FE-3352, FE-3353)
- the `pendingServerFact` bridge and its expiry check (FE-3354)
- orthogonality tests on every gate a PR touches (FE-3355)

Until those land, this ADR and the `AGENTS.md` line are the only guidance.

### Alternatives considered

- **More Markdown in reviewer skills.** Rejected: it was already in place
and failed twice.
- **An LLM reviewer prompt for this rule.** Rejected as a gate: that is what
approved the three PRs. It is not calibrated, and it shares the author's
framing.
- **Opaque `ServerFact<T>` types now.** Deferred: it is the strongest
guarantee, but about 15 billing surfaces and other domains have to migrate
first. The planned lint gate (FE-3351) is meant to hold the line in the
meantime.
- **Server-driven UI.** Rejected for now: out of scope for the capabilities
API.

## Consequences

### Positive

- One copy of each policy, in the backend, shared by every client (app,
billing-web, website, platform).
- A missing fact becomes a visible backend ticket instead of a silent client
proxy.
- Reviewers and agents get a mechanical test: is this gate one server fact,
as received?

### Negative

- Some UI waits on backend fields that the client could approximate today.
`pendingServerFact` is the escape hatch, and it expires with its ticket.
- Existing derivations need burning down domain by domain. Until then, new
code is held to the rule on changed lines only.

## Notes

- Capabilities TDD: "an API should emit facts about its own domain, and
clients should render those facts rather than recombine them into a
decision."
- Related: ADR-AUTH-SESSION-0037 (the server owns the AND for one flag).
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ An Architecture Decision Record captures an important architectural decision mad
| [AGENT-OBSERVABILITY-0034](AGENT-OBSERVABILITY-0034-frontend-journey-effect-contract.md) | Frontend Journey Effect Contract | Proposed | 2026-09-17 |
| [AGENT-SESSION-0028](AGENT-SESSION-0028-compose-turn-origin-and-account-generation.md) | Compose Turn Origin and Account Generation | Proposed | 2026-09-05 |
| [AGENT-TARGET-0037](AGENT-TARGET-0037-commit-workflow-target-on-send-or-node-reference.md) | Commit Workflow Target on Explicit User Intent | Proposed | 2026-09-24 |
| [API-SERVER-FACTS-0042](API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md) | Server Facts Are Rendered, Not Derived | Proposed | 2026-10-09 |
| [ASSETS-DRAG-DROP-0035](ASSETS-DRAG-DROP-0035-asset-card-drag-uses-file-url.md) | Asset Card Drag-and-Drop Uses the File URL, Never the Preview URL | Proposed | 2026-09-19 |
| [ASSETS-LIFECYCLE-0030](ASSETS-LIFECYCLE-0030-asset-record-and-content-lifecycles.md) | Asset Record and Content Lifecycles | Accepted | 2026-08-27 |
| [AUTH-BILLING-0014](AUTH-BILLING-0014-billing-attempt-context-and-workspace-scope.md) | Billing Attempt Context and Workspace Scope | Proposed | 2026-07-28 |
Expand Down
12 changes: 9 additions & 3 deletions docs/guidance/state-and-effects.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,9 +85,15 @@ async function startFlow(id: string) {

## 4. Derive everything derivable

Do not store `isOpening`, `canTransition`, `isLast`, or a second copy of data
that already exists. If a `computed` can name it, do not put it in a `ref` and
keep it in sync by hand — the sync is where the bugs live.
Do not store `isOpening`, `isLast`, or a second copy of data that already
exists. If a `computed` can name it, do not put it in a `ref` and keep it in
sync by hand — the sync is where the bugs live.

This covers state the feature owns. A server fact (a permission, role, tier,
plan status, seat count, readiness or server timestamp) is not derivable here.
Render the field the API returns. If the API does not return it, ask the
backend for it. See
[ADR-API-SERVER-FACTS-0042](../adr/API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md).

## 5. Reserve effects for synchronising with the outside

Expand Down
3 changes: 3 additions & 0 deletions lint-staged.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,9 @@ export default function lintStaged(stagedFiles: string[]) {
'pnpm exec oxfmt --write --no-error-on-unmatched-pattern'
),
...lintCommands(codeFiles, styleFiles, astroFiles),
...(codeFiles.length > 0
? repoWide('pnpm lint:server-facts --staged')
: []),
...commandsWithFiles(
astroFiles.map((fileName) => fileName.slice('apps/website/'.length)),
'pnpm --dir apps/website exec prettier --write'
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@
"lint:fix:ci": "pnpm lint:fix --cache-strategy content",
"lint:fix": "pnpm oxlint --fix && eslint --cache --concurrency auto --fix",
"lint:no-cache": "pnpm exec stylelint '{apps,packages,src}/**/*.{css,vue}' && pnpm oxlint && eslint --concurrency auto",
"lint:server-facts": "tsx scripts/server-fact-gate.ts",
"lint:unstaged:fix": "tsx scripts/lint-unstaged.ts --fix",
"lint:unstaged": "tsx scripts/lint-unstaged.ts",
"lint:ci": "pnpm lint --cache-strategy content",
Expand Down
Loading
Loading