Skip to content

Commit 0406650

Browse files
committed
feat(effects): EFF001 effect-storm — a real core stability analysis (P-020)
Answer P-020's gating question (Open question 1) for real: the unstable- dependency "effect storm" is a genuinely NEW core analysis, not an OWN001 leak and not a frontend heuristic. The honest fact/verdict split holds end to end — the OwnTS frontend emits only facts; the core decides. Core (ownlang/effects.py): a dependency-identity stability lattice (STABLE < UNKNOWN < UNSTABLE) computed to a fixpoint over the render-scope binding references. An object/array literal in render scope is UNSTABLE (fresh identity each render); useMemo/useCallback/useRef/prop/primitive are STABLE; an alias/derivation takes the worst of its refs (instability propagates); an opaque call is UNKNOWN (conservative — no finding). An effect is EFF001 iff it does IO AND a dep is provably UNSTABLE. Its own core code (like DI001), never masquerading as OWN001. Bridge (ownlang/ownir.py): a new optional, additive `effects` block in OwnIR (does not bump the version, mirrors `services`); _effect_findings routes it through effects.py to an EFF001 Finding at the effect call site, with a reachability slice (effect -> the fix site) and a SARIF rule. load() shape-checks the block; malformed input degrades to no findings. Frontend (frontend/ownts/): emits the `effects` facts — per useEffect, the dep list, an IO flag, and the component's render-scope binding table with each binding's syntactic init kind + references. The old stderr-only EFF001 heuristic is removed in favour of the core verdict. - ownlang/effects.py: the analysis (lattice, propagation, cycle-safe) - ownlang/diagnostics.py: register EFF001 title - examples/EffectStorm.tsx: showcase — 2 storms fire (object dep + derived alias), memo/ref/call/primitive/no-IO stay silent (low false positives) - tests/test_effects.py (29 checks) wired into run_tests.py; ownts spike test now pins 3xOWN001+EFF001 / 0 / 2xEFF001 - CI ownts-react-effects job extended; P-020 + README updated mypy --strict clean; ruff clean; full suite green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PVeuchch67CtjSbizYm8gi
1 parent 634594f commit 0406650

11 files changed

Lines changed: 665 additions & 82 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 26 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -999,9 +999,12 @@ jobs:
999999
echo "OK: .csproj input resolves to its source set and feeds the core identically (positional == --project, fact-level parity)"
10001000
10011001
# The OwnTS frontend spike (P-020 Own.React): the SAME OwnIR seam, fed from a
1002-
# React .tsx instead of C#. A useEffect acquire (timer / subscribe / listener)
1003-
# with no cleanup return is the core's OWN001 — proving the leak model is
1004-
# cross-language, not .NET-only. No dotnet needed; pure-Python frontend.
1002+
# React .tsx instead of C#. Two analyses over the one core: (1) a useEffect
1003+
# acquire (timer / subscribe / listener) with no cleanup return is the core's
1004+
# OWN001 — the cross-language leak model; (2) EFF001, a NEW core analysis
1005+
# (ownlang/effects.py) — an IO effect whose dependency identity is unstable
1006+
# (a render-scope object literal) re-fires every render: the effect storm. The
1007+
# frontend emits only facts; the stability verdict is the core's. No dotnet.
10051008
ownts-react-effects:
10061009
name: OwnTS (React useEffect) -> OwnIR -> core
10071010
runs-on: ubuntu-latest
@@ -1010,7 +1013,7 @@ jobs:
10101013
- uses: actions/setup-python@v5
10111014
with:
10121015
python-version: "3.13"
1013-
- name: Pin the spike (leaky=3xOWN001, clean=0, EFF001 heuristic)
1016+
- name: Pin the spike (leaky=3xOWN001+EFF001, clean=0, showcase=2xEFF001)
10141017
run: python frontend/ownts/test_ownts.py
10151018
- name: Extract OwnIR facts from a React .tsx and check through the core
10161019
run: |
@@ -1023,16 +1026,31 @@ jobs:
10231026
|| { echo "FAIL: expected findings located at the .tsx"; exit 1; }
10241027
echo "$out" | grep -q "resource: timer" \
10251028
|| { echo "FAIL: expected the setInterval [resource: timer] leak"; exit 1; }
1026-
echo "$out" | grep -qE "3 finding" \
1027-
|| { echo "FAIL: expected three OWN001 leaks from the leaky effects"; exit 1; }
1028-
- name: The clean fixture (cleanup returns) is silent
1029+
[ "$(echo "$out" | grep -c 'OWN001')" -eq 3 ] \
1030+
|| { echo "FAIL: expected three OWN001 leaks"; exit 1; }
1031+
echo "$out" | grep -q "\[EFF001\].*request storm" \
1032+
|| { echo "FAIL: expected the EFF001 effect-storm verdict"; exit 1; }
1033+
echo "$out" | grep -qE "4 finding" \
1034+
|| { echo "FAIL: expected 3 OWN001 + 1 EFF001 = 4 findings"; exit 1; }
1035+
- name: EFF001 stability showcase — only provable storms fire (low FP)
1036+
run: |
1037+
python frontend/ownts/ownts.py frontend/ownts/examples/EffectStorm.tsx \
1038+
-o "$RUNNER_TEMP/storm.facts.json"
1039+
storm=$(python -m ownlang ownir "$RUNNER_TEMP/storm.facts.json" || true)
1040+
echo "$storm"
1041+
# the direct object dep and its derived alias fire; memo/ref/call/primitive/no-IO stay silent
1042+
echo "$storm" | grep -qE "2 finding" \
1043+
|| { echo "FAIL: expected exactly two EFF001 (object dep + derived alias)"; exit 1; }
1044+
echo "$storm" | grep -q "derives from" \
1045+
|| { echo "FAIL: expected the derivation (propagation) verdict"; exit 1; }
1046+
- name: The clean fixture (cleanups + useMemo'd dep) is silent
10291047
run: |
10301048
python frontend/ownts/ownts.py frontend/ownts/examples/DashboardClean.tsx \
10311049
-o "$RUNNER_TEMP/clean.facts.json"
10321050
clean=$(python -m ownlang ownir "$RUNNER_TEMP/clean.facts.json" || true)
10331051
echo "$clean"
10341052
echo "$clean" | grep -q "0 finding" \
1035-
|| { echo "FAIL: cleaned-up effects must not leak"; exit 1; }
1053+
|| { echo "FAIL: cleaned-up + memoised effects must not fire"; exit 1; }
10361054
10371055
# The distribution surface (Уровень 1): the own-check.sh orchestrator walks a
10381056
# directory of real C# and prints findings in the host-parseable formats the

‎docs/proposals/P-020-ownts-react-effects.md‎

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,15 @@
55
honest before any code.
66
- **Spike landed:** the honest `EFF003`/`EFF004` slice (timer / subscribe /
77
listener acquire with no cleanup `return` → core `OWN001`) is implemented in
8-
`frontend/ownts/` and CI-pinned (the `ownts-react-effects` job). `EFF001/002`
9-
(the effect-storm stability analysis) is **not** built — the spike only emits a
10-
clearly-labelled frontend-only heuristic note for it, never a core finding, per
11-
Open question 1 below.
8+
`frontend/ownts/` and CI-pinned (the `ownts-react-effects` job).
9+
- **`EFF001` is now a real core analysis** (`ownlang/effects.py`), answering Open
10+
question 1 below: a self-contained **dependency-identity stability** lattice with
11+
reference propagation, computed by the **core** over an OwnIR `effects` fact block
12+
the frontend emits — *not* a frontend heuristic, and *not* an `OWN001`. It is its
13+
own core code (`EFF001`), exactly as the DI captive check is `DI001`. The frontend
14+
states only what each render-scope binding syntactically is; the core decides
15+
stability. `EFF002` (network IO with no stable guard) is governed by the same
16+
analysis and left as the next increment.
1217
- **Depends on:** [P-017](P-017-multi-stack-frontends.md) (the OwnTS frontend &
1318
confidence tiers that this profile feeds), `spec/OwnCore.md` (the acquire/release
1419
vocabulary), [P-004](P-004-wpf-lifetime-profile.md) (WPF — the same lifecycle
@@ -151,12 +156,16 @@ has on the .NET side (P-013/P-015); 1/2/6/7 are this proposal's actual work.
151156

152157
## Open questions
153158

154-
1. **The new analysis for `EFF001/002`.** Detecting "dependency identity is unstable
155-
across renders" needs render-scope object-literal/identity reasoning the core
156-
has no model for. Is that a small, self-contained *stability* fact
157-
(`unstable(dep, effect)`) the OwnTS frontend can emit and the core treat like an
158-
acquire-site, or a genuinely new core analysis? This is the gating question — do
159-
not let `EFF001` masquerade as an `OWN001` leak.
159+
1. **The new analysis for `EFF001/002`.** ✅ **Answered (implemented).** It is a
160+
genuinely new core analysis, not an `OWN001` acquire-site — and *not* a frontend
161+
verdict either. The resolution: the frontend emits per-binding **facts** (each
162+
render-scope binding's syntactic `init` kind + the names it references, the dep
163+
list, whether the body does IO) in an OwnIR `effects` block; the **core**
164+
(`ownlang/effects.py`) runs an identity-stability lattice (`STABLE < UNKNOWN <
165+
UNSTABLE`) to a fixpoint over the references and decides `unstable(dep)`. An
166+
effect is `EFF001` iff it does IO **and** a dep is *provably* `UNSTABLE`
167+
(`UNKNOWN`/memoised/primitive clear it — low false positives). The gating
168+
discipline held: `EFF001` is its own core code (like `DI001`), never an `OWN001`.
160169
2. **Confidence tier.** `EFF001` clearly wants TS-mode type info (is the dep an
161170
object literal? does the body do IO?). What, if anything, survives into JS mode
162171
(P-017's heuristic tier) as a warning?

‎frontend/ownts/README.md‎

Lines changed: 34 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@ python frontend/ownts/ownts.py frontend/ownts/examples/Dashboard.tsx
2222
# extract + run straight through the core (the "catch")
2323
python frontend/ownts/ownts.py frontend/ownts/examples/Dashboard.tsx --check
2424

25+
# the EFF001 stability showcase (propagation + the conservative silent cases)
26+
python frontend/ownts/ownts.py frontend/ownts/examples/EffectStorm.tsx --check
27+
2528
# or the real two-step CLI, same as the C# side:
2629
python frontend/ownts/ownts.py frontend/ownts/examples/Dashboard.tsx -o facts.json
2730
python -m ownlang ownir facts.json --format sarif
@@ -30,43 +33,57 @@ python -m ownlang ownir facts.json --format sarif
3033
python frontend/ownts/test_ownts.py
3134
```
3235

33-
`Dashboard.tsx` drops three `OWN001` leaks; `DashboardClean.tsx` (every acquire
34-
has a cleanup `return`) is silent.
36+
`Dashboard.tsx` drops three `OWN001` leaks **and** one `EFF001` effect storm;
37+
`DashboardClean.tsx` (every acquire has a cleanup `return`, and the unstable dep is
38+
`useMemo`'d) is silent.
3539

3640
```
3741
Dashboard.tsx:13: error: [OWN001] timer 'setInterval(() =>' ... never stopped ... (leak) [resource: timer]
3842
Dashboard.tsx:21: error: [OWN001] the result of '.subscribe(...)' is ignored ... (leak) [resource: subscription token]
3943
Dashboard.tsx:27: error: [OWN001] event '.addEventListener(...)' ... never unsubscribed ... (leak) [resource: subscription token]
44+
Dashboard.tsx:34: error: [EFF001] effect re-runs on every render: dependency 'filters' is an object literal ... can become a request storm ... [resource: react effect]
4045
```
4146

4247
## What it catches — the honest `Own.React` slice
4348

44-
| EFF | Pattern | OwnIR `resource` | Core verdict |
45-
|-----|---------|------------------|--------------|
46-
| `EFF004` | `setInterval`/`setTimeout` in an effect, no `clearInterval`/`clearTimeout` cleanup | `timer` | `OWN001` |
47-
| `EFF003` | `X.subscribe(...)` with no `unsubscribe` cleanup | `subscribe` | `OWN001` |
48-
| `EFF003` | `addEventListener` with no `removeEventListener` cleanup | `subscription` | `OWN001` |
49+
| EFF | Pattern | OwnIR fact | Core verdict |
50+
|-----|---------|-----------|--------------|
51+
| `EFF004` | `setInterval`/`setTimeout` in an effect, no `clearInterval`/`clearTimeout` cleanup | `resource: timer` | `OWN001` |
52+
| `EFF003` | `X.subscribe(...)` with no `unsubscribe` cleanup | `resource: subscribe` | `OWN001` |
53+
| `EFF003` | `addEventListener` with no `removeEventListener` cleanup | `resource: subscription` | `OWN001` |
54+
| `EFF001` | IO effect with a render-unstable dependency identity | `effects` block | `EFF001` (new core analysis — see below) |
4955

5056
These three **are** the existing acquire→release model, just emitted by an OwnTS
5157
frontend. The core is untouched.
5258

53-
## What it does NOT do (and why that's honest)
59+
## EFF001 — a real core analysis (not a heuristic, not OWN001)
5460

55-
`EFF001/002` — the unstable-dependency "effect storm" (the Cloudflare 12-Sep-2025
61+
`EFF001` — the unstable-dependency "effect storm" (the Cloudflare 12-Sep-2025
5662
shape: a `useEffect` whose dep object is re-created each render, re-firing the
57-
effect and storming the API) — **is not an acquire/release leak.** It needs a new
58-
core capability (dependency-identity *stability*), which the core does not have.
59-
Per P-020, `EFF001` must **not** masquerade as `OWN001`.
63+
effect and storming the API) — **is not an acquire/release leak.** It is a new core
64+
analysis: **dependency-identity stability** (`ownlang/effects.py`), its own core
65+
code like `DI001`, *never* an `OWN001`.
6066

61-
So the scanner only emits a *frontend-only, clearly-labelled* heuristic note for
62-
`EFF001` candidates on **stderr** — never a core-verified finding:
67+
The honest split is preserved end-to-end. The frontend emits only **facts** — for
68+
each `useEffect`, its dep list, whether the body does IO, and a render-scope
69+
**binding table** (what each binding syntactically is: `object`/`array`/`new`,
70+
`memo`/`callback`/`ref`, `ident` derivation + the names it references, `call`, …).
71+
It does **not** pre-judge stability. The **core** runs an identity-stability lattice
72+
(`STABLE < UNKNOWN < UNSTABLE`) to a fixpoint over the references and decides:
6373

6474
```
65-
Dashboard.tsx:34: EFF001 (frontend heuristic, NOT core-verified): dependency
66-
'filters' is a fresh object/array identity every render; the effect does IO —
67-
possible request storm. Stabilise with useMemo.
75+
EFF001 fires ⟺ the effect does IO ∧ some dep is *provably* UNSTABLE
6876
```
6977

78+
- object/array literal in render scope → UNSTABLE (fresh identity every render)
79+
- `useMemo`/`useCallback`/`useRef`, prop, primitive → STABLE
80+
- an alias/derivation → the worst of what it references (instability *propagates*)
81+
- an opaque `call(...)` → UNKNOWN → **no finding** (conservative; low false positives)
82+
83+
See `examples/EffectStorm.tsx`: two storms fire (a direct object dep and the alias
84+
that derives from it — `derives from 'filters' ... (via alias -> filters)`), while
85+
the memoised, ref, opaque-call, primitive, and no-IO effects all stay silent.
86+
7087
The one-liner the spike pays for: **"Not all lifecycle bugs leak memory. Some
7188
leak requests."** We make **no** "Own would have prevented the Cloudflare outage"
7289
claim — see P-020's Non-goals.
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
// EFF001 showcase — the core's dependency-identity *stability* analysis, not a
2+
// leak. Only the IO effects whose dep is PROVABLY unstable fire; memoised,
3+
// primitive, opaque-call and no-IO cases stay silent (low false positives).
4+
//
5+
// python frontend/ownts/ownts.py frontend/ownts/examples/EffectStorm.tsx --check
6+
//
7+
// Expect exactly two EFF001 findings: the direct object dep, and the alias that
8+
// derives from it.
9+
import { useEffect, useMemo, useRef } from "react";
10+
11+
export function StormBoard({ tenantId }: { tenantId: string }) {
12+
// (1) FIRES — fresh object identity every render + IO.
13+
const filters = { tenantId };
14+
useEffect(() => {
15+
fetch(`/api/tenant/${filters.tenantId}`);
16+
}, [filters]);
17+
18+
// (2) FIRES — `alias` derives from the unstable `filters`; instability propagates.
19+
const alias = filters;
20+
useEffect(() => {
21+
fetch(`/api/alias/${alias.tenantId}`);
22+
}, [alias]);
23+
24+
// (3) SILENT — useMemo gives a stable identity across renders.
25+
const stable = useMemo(() => ({ tenantId }), [tenantId]);
26+
useEffect(() => {
27+
fetch(`/api/stable/${stable.tenantId}`);
28+
}, [stable]);
29+
30+
// (4) SILENT — useRef identity is stable.
31+
const box = useRef({ tenantId });
32+
useEffect(() => {
33+
fetch(`/api/ref/${box.current.tenantId}`);
34+
}, [box]);
35+
36+
// (5) SILENT — opaque call: the core stays conservative (UNKNOWN, no finding).
37+
const computed = makeFilters(tenantId);
38+
useEffect(() => {
39+
fetch(`/api/computed/${computed.tenantId}`);
40+
}, [computed]);
41+
42+
// (6) SILENT — primitive dependency has a stable value identity.
43+
useEffect(() => {
44+
fetch(`/api/primitive/${tenantId}`);
45+
}, [tenantId]);
46+
47+
// (7) SILENT — unstable dep but NO IO: re-running is cheap, not a storm.
48+
const opts = { verbose: true };
49+
useEffect(() => {
50+
console.log(opts.verbose);
51+
}, [opts]);
52+
53+
return <div>storm board</div>;
54+
}

0 commit comments

Comments
 (0)