Skip to content

Commit dca5b52

Browse files
committed
docs(P-020): React effect-storm profile + competitive positioning
Add the Cloudflare-shaped angle and the hub-level positioning, kept honest. - P-020 (Own.React effect profile under the OwnTS frontend): EFF001-005. Splits honestly — EFF003/004/005 are the existing acquire->release/OWN001 model; EFF001/002 (unstable-dependency effect storm, the actual Cloudflare shape) are a NEW dependency-stability analysis the core does not model yet, named as such rather than smuggled in as a leak. One-rule spike (EFF001), not a TS analyzer. - Cloudflare framing is deliberately non-overclaiming: "not all lifecycle bugs leak memory; some leak requests," never "we'd have saved Cloudflare" (the source is a vendor marketing post, not a neutral postmortem). - ROADMAP framing: "Positioning against the competition (not another SAST)" — the niche is a cross-language resource/lifetime/effect contract checker, a deterministic layer under AI reviewers, not a head-on SAST/AI-review fight. - ROADMAP framing: "From memory leaks to effect storms" — WPF leak / DI captive / ArrayPool view / React effect storm as one lifecycle-contract model. - Cross-link P-017 <-> P-020; EFF003/004 share cleanup semantics with the OwnTS authoring rules, P-020 is the canonical home. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QnGqHwVb2H1jZ71f498MFa
1 parent f5efe0a commit dca5b52

4 files changed

Lines changed: 209 additions & 1 deletion

File tree

‎docs/ROADMAP.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,46 @@ The long-term identity the backlog is aiming at:
3535
> typestate, effects, capabilities, and domain-specific types **without
3636
> rewriting the codebase.**
3737
38+
### Positioning against the competition (not another SAST)
39+
40+
The competition is already standing around this field with shovels and enterprise
41+
sales badges. CodeQL (semantic queries / code scanning), Sonar (quality / bugs /
42+
smells), Semgrep (rule-based AppSec), Snyk Code (SAST), and the AI PR reviewers all
43+
sell the **broad** promise: *"we'll find vulnerabilities / bugs / smells."* Entering
44+
that arena as *"another static analyzer / AI code reviewer / SAST"* is a fight lost
45+
to marketing budget, not to merit.
46+
47+
So Own.NET must **not** be pitched as any of those. The narrower, defensible niche:
48+
49+
> a **cross-language resource / lifetime / effect contract checker** — who holds
50+
> whom, who must release, which resource outlives which, which effect can
51+
> runaway, where a lifecycle contract is broken.
52+
53+
That is a different promise from *"an AI reviewer said this looks suspicious."* And
54+
it is deterministic where the AI reviewers are not — the grown-up framing is *an
55+
LLM may **propose** a suspicious lifecycle contract; Own **verifies** it
56+
deterministically* (reproducible rule, SARIF, suppression/spec, cross-language
57+
model). Not a head-on fight with AI review — a layer underneath it.
58+
59+
### From memory leaks to effect storms (one model, many skins)
60+
61+
The "big idea" that makes the niche coherent: four bugs that look unrelated are the
62+
**same lifecycle/resource-contract failure** in different ecosystems —
63+
64+
| Bug | The contract that broke |
65+
|-----|-------------------------|
66+
| WPF event leak | a long-lived publisher keeps a `ViewModel` alive |
67+
| DI captive dependency | a long-lived service retains a scoped service |
68+
| ArrayPool view-after-return | released backing storage still has a borrowed view |
69+
| **React effect storm** | an unstable dependency repeatedly re-triggers a network effect |
70+
71+
One model (source lifetime / resource / effect / cleanup / stability), one IR
72+
(OwnIR facts), one checker (the `ownlang/` core). The React row is the
73+
Cloudflare-shaped hook — used **honestly**: *"not all lifecycle bugs leak memory;
74+
some leak requests,"* never *"we'd have prevented the Cloudflare outage."* Its
75+
design is [P-020](proposals/P-020-ownts-react-effects.md) (the `Own.React` effect
76+
profile under the OwnTS frontend, [P-017](proposals/P-017-multi-stack-frontends.md)).
77+
3878
## Design philosophy (the load-bearing constraints)
3979

4080
- **One checker.** The Python core in `ownlang/` is the single source of truth.
@@ -264,3 +304,4 @@ own scan. Label them as estimates wherever they appear.
264304
| [P-015](proposals/P-015-configuration-surface.md) | Configuration surface (check selection & severity) | P2 | draft (stub) |
265305
| [P-016](proposals/P-016-deep-fact-extraction.md) | Deep C# fact extraction (CFG + flow lowering) | P1 | in progress (B0a/B0b/B2/A1 via `--flow-locals`) |
266306
| [P-017](proposals/P-017-multi-stack-frontends.md) | Multi-stack frontends (OwnTS / OwnJVM: OwnJava + OwnKotlin) | horizon | draft |
307+
| [P-020](proposals/P-020-ownts-react-effects.md) | OwnTS React effects profile (`Own.React`) — effect-storm angle | horizon | draft |

‎docs/proposals/P-017-multi-stack-frontends.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,13 @@ surface in this ecosystem (`npm install`, drop into an existing config):
127127
| `OWNTS002` | `setInterval` / `setTimeout` with no `clear*` | `OWN001` |
128128
| `OWNTS003` | `subscribe()` result never `unsubscribe`d | `OWN001` |
129129
| `OWNTS004` | `AbortController` created but never `abort()`ed | `OWN001` |
130-
| `OWNTS005` | unstable dependency re-triggers an external effect | (effect/region) |
130+
| `OWNTS005` | unstable dependency re-triggers an external effect | (effect/region — see P-020) |
131+
132+
The `useEffect`/React rows above are the authoring surface; the deeper **`Own.React`
133+
effect profile** (the `EFF001–005` catalog, the effect-storm analysis, and the
134+
honest Cloudflare framing) is specified in
135+
[P-020](P-020-ownts-react-effects.md). `OWNTS003/004` and `EFF003/004` are the same
136+
cleanup semantics — P-020 is the canonical home; the ESLint rules reference it.
131137

132138
```
133139
eslint-plugin-own ← authoring rules for JS/TS (the user-facing surface)
Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# P-020 — OwnTS React effects profile (`Own.React`) — the effect-storm angle
2+
3+
- **Status:** draft — **experiment / proposal, explicitly not mainline.** A
4+
marketing-shaped spike under the OwnTS frontend, on the record so the framing is
5+
honest before any code.
6+
- **Depends on:** [P-017](P-017-multi-stack-frontends.md) (the OwnTS frontend &
7+
confidence tiers that this profile feeds), `spec/OwnCore.md` (the acquire/release
8+
vocabulary), [P-004](P-004-wpf-lifetime-profile.md) (WPF — the same lifecycle
9+
model in a different skin).
10+
11+
## The seam this fits
12+
13+
[P-017](P-017-multi-stack-frontends.md) splits two axes: the **OwnTS frontend**
14+
(what parses JS/TS and emits OwnIR) vs a **platform profile** (the lifetime/effect
15+
facts a domain needs). This proposal is the second kind: **`Own.React`**, the
16+
effect/cleanup profile the OwnTS frontend feeds the core — exactly as WPF is a
17+
profile for the .NET side. P-017 owns the frontend mechanics and the
18+
`OWNTS001–005` authoring rules; P-020 specifies the `Own.React` **EFF** catalog and
19+
the effect-storm analysis behind it.
20+
21+
## Motivation — not all lifecycle bugs leak memory; some leak requests
22+
23+
The originating hook is the Cloudflare dashboard/API outage of **12 Sep 2025**,
24+
described (in a Panto AI DEV post, 16 Sep 2025) as a "self-DDoS": a React dashboard
25+
update created a runaway loop of redundant API requests, traced to a `useEffect`
26+
whose dependency object was re-created on every render, re-running the effect each
27+
time.
28+
29+
**Read the source honestly.** That post is a *vendor/marketing* text, not a neutral
30+
postmortem — it closes by suggesting an AI reviewer like Panto would have flagged
31+
it. So the case is a great *PR angle* and a poor *proof*. We do **not** claim
32+
"Own.NET would have prevented the Cloudflare outage" — that is the startup classic
33+
("we can't catch this bug class yet, but we'd already have saved the internet").
34+
The honest, and stronger, framing:
35+
36+
> Cloudflare-style outages show that lifecycle bugs are not just memory bugs.
37+
> A single unstable UI effect can become a control-plane incident. Own models
38+
> subscriptions, timers, resources, and effects as explicit contracts, so teams can
39+
> catch lifecycle mistakes before they become production loops.
40+
41+
The one-liner: **"Not all lifecycle bugs leak memory. Some leak requests."**
42+
43+
This matters to the project because React `useEffect` is the *same animal* the core
44+
already models for .NET — `event += / -=`, `Subscribe()/Dispose`, timers,
45+
lifetimes — wearing JSX:
46+
47+
```tsx
48+
useEffect(() => { subscribe(); return () => unsubscribe(); }, [deps]); // cleanup contract
49+
useEffect(() => { fetchTenantData(filters); }, [filters]); // effect-storm if `filters` is unstable
50+
```
51+
52+
## The `Own.React` EFF catalog
53+
54+
Profile catalog IDs (like `WPFxxx` — they live in the catalog and map to **core**
55+
verdicts/labels; the emitter stays core `OWN` codes + a `[profile: react]` /
56+
`[resource: …]` tag, per the consolidation discipline):
57+
58+
| EFF | Pattern | Maps to | Tier |
59+
|-----|---------|---------|------|
60+
| `EFF001` | unstable dependency object re-runs the effect, **and** the effect does external IO (request storm) | **new** stability analysis (see below) | effect-storm |
61+
| `EFF002` | effect performs a network request with no stable guard | **new** stability analysis | effect-storm |
62+
| `EFF003` | effect subscribes without a cleanup `return` | `OWN001` (acquire w/o release) | leak |
63+
| `EFF004` | `setInterval`/`setTimeout` in an effect without cleanup | `OWN001` | leak |
64+
| `EFF005` | `AbortController` created but never `abort()`ed | `OWN001` | leak |
65+
66+
**Honest split.** `EFF003/004/005` *are* the existing acquire→release/`OWN001`
67+
model — the same fact shape P-001 already proved, just emitted by the OwnTS
68+
frontend. `EFF001/002` (the actual Cloudflare shape) are **not** an acquire/release
69+
leak; they are a *new* analysis dimension — **dependency-identity stability** →
70+
effect re-trigger → IO storm. The core does not model that today. This proposal
71+
names it as the new capability it would require, rather than pretending the leak
72+
checker already covers it (see Open questions).
73+
74+
## The spike (one rule, end-to-end, not a TypeScript analyzer)
75+
76+
Build **`EFF001` only**, in TS mode, as a small experiment — *not* a general
77+
TypeScript effect analyzer.
78+
79+
Bad (flagged):
80+
81+
```tsx
82+
function Dashboard({ tenantId }: Props) {
83+
const filters = { tenantId }; // new object identity every render
84+
useEffect(() => {
85+
fetch(`/api/tenant/${filters.tenantId}`);
86+
}, [filters]); // → effect re-runs every render
87+
}
88+
```
89+
90+
```text
91+
EFF001: unstable object dependency 'filters' causes the effect to re-run on every
92+
render. The effect performs network IO; this can create a request storm.
93+
```
94+
95+
OK (silent):
96+
97+
```tsx
98+
function Dashboard({ tenantId }: Props) {
99+
useEffect(() => { fetch(`/api/tenant/${tenantId}`); }, [tenantId]); // stable primitive dep
100+
}
101+
// — or — const filters = useMemo(() => ({ tenantId }), [tenantId]); ... }, [filters]);
102+
```
103+
104+
The article line that pays for the spike: *"The same OwnIR idea behind WPF
105+
subscription leaks can model React effect storms."*
106+
107+
## Positioning — deterministic contract checker, not another AI reviewer
108+
109+
The competitive note that frames this whole direction lives at the hub
110+
([ROADMAP — Positioning against the competition](../ROADMAP.md#positioning-against-the-competition-not-another-sast)).
111+
The React-specific edge over a Panto-style AI reviewer:
112+
113+
| AI reviewer | Own / OwnTS |
114+
|-------------|-------------|
115+
| *maybe* flags a suspicious pattern | explicit resource/effect/lifetime **facts** |
116+
| natural-language, nondeterministic | deterministic rule, reproducible **SARIF** |
117+
| no suppression/spec contract | suppression + spec mechanism, cross-language model |
118+
119+
We do **not** fight AI reviewers head-on. The grown-up line is: *an LLM may
120+
**propose** a suspicious lifecycle contract; Own **verifies** it deterministically.*
121+
122+
## Non-goals
123+
124+
- **Not a TypeScript effect/dataflow analyzer.** One rule (`EFF001`), TS mode,
125+
spike only. General closure/render-dataflow stays out (same narrow-frontend
126+
discipline as the C# side).
127+
- **No "we'd have saved Cloudflare" claim**, in README, talk, or PR. The hook is
128+
"lifecycle bugs aren't only memory bugs," never a counterfactual rescue.
129+
- **Not mainline.** This rides as an experiment/proposal until the .NET surface is
130+
a tasty alpha and the spike demonstrably finds real effect storms in real OSS
131+
dashboards with low false positives.
132+
- **No second checker.** `Own.React` emits OwnIR facts (`EFF003/004/005`) or routes
133+
through the new stability analysis (`EFF001/002`); the Python core stays the one
134+
checker.
135+
136+
## What a Cloudflare-type buyer actually needs (so we don't ship "buy our idea")
137+
138+
A real org evaluates the *demo that catches the bug class*, not the DSL. The bar:
139+
140+
1. a reproducible minimal example of the class; 2. the rule catches it with low
141+
false positives; 3. SARIF / GitHub annotation; 4. CI integration; 5. a suppression
142+
mechanism; 6. a plain "why this becomes a request storm" explanation; 7. a
143+
benchmark — *finds N real issues in OSS dashboards*. Items 3–5 the project already
144+
has on the .NET side (P-013/P-015); 1/2/6/7 are this proposal's actual work.
145+
146+
## Open questions
147+
148+
1. **The new analysis for `EFF001/002`.** Detecting "dependency identity is unstable
149+
across renders" needs render-scope object-literal/identity reasoning the core
150+
has no model for. Is that a small, self-contained *stability* fact
151+
(`unstable(dep, effect)`) the OwnTS frontend can emit and the core treat like an
152+
acquire-site, or a genuinely new core analysis? This is the gating question — do
153+
not let `EFF001` masquerade as an `OWN001` leak.
154+
2. **Confidence tier.** `EFF001` clearly wants TS-mode type info (is the dep an
155+
object literal? does the body do IO?). What, if anything, survives into JS mode
156+
(P-017's heuristic tier) as a warning?
157+
3. **Overlap with P-017's `OWNTS003/004`.** `EFF003/004` restate the cleanup rules
158+
from the OwnTS authoring surface — keep one canonical home (the `Own.React`
159+
profile here) and have P-017's ESLint rules reference it, not duplicate the
160+
semantics.

‎docs/proposals/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ proposal is marked `done` with a pointer.
3939
| [P-015](P-015-configuration-surface.md) | Configuration surface (check selection & per-category severity) | draft (stub) |
4040
| [P-016](P-016-deep-fact-extraction.md) | Deep C# fact extraction (CFG + flow lowering; loops) | in progress (B0a/B0b/B2/A1 via `--flow-locals`) |
4141
| [P-017](P-017-multi-stack-frontends.md) | Multi-stack frontends (OwnTS / OwnJVM: OwnJava + OwnKotlin) | draft |
42+
| [P-020](P-020-ownts-react-effects.md) | OwnTS React effects profile (`Own.React`) — the effect-storm angle | draft |
4243

4344
> For priorities, milestones, the framing, and the design philosophy across all
4445
> of these, see the strategy hub: [`docs/ROADMAP.md`](../ROADMAP.md). P-004 … P-016

0 commit comments

Comments
 (0)