rcdebug 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
rcdebug/learner.py ADDED
@@ -0,0 +1,745 @@
1
+ """
2
+ Adaptive Place & Flaw Learning Engine for rcdebug.
3
+
4
+ Automatically learns game-specific naming conventions, remote patterns,
5
+ state exposure surfaces, and flaw frequencies from every audited place
6
+ or live playtest session, persisting knowledge to ~/.rcdebug/learned_flaws.json
7
+ and ~/.rcdebug/learned_patterns.txt so rcdebug becomes smarter across all games.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import json
13
+ import math
14
+ import random
15
+ import re
16
+ from datetime import datetime, timedelta
17
+ from pathlib import Path
18
+ from typing import TYPE_CHECKING, Any
19
+
20
+ from .models import AuditSession, Finding, normalize_severity
21
+
22
+ if TYPE_CHECKING:
23
+ from .flaw_catalog import FlawCatalog
24
+
25
+ LEARNED_DIR = Path.home() / ".rcdebug"
26
+ LEARNED_FILE = LEARNED_DIR / "learned_flaws.json"
27
+ LEARNED_TXT_FILE = LEARNED_DIR / "learned_patterns.txt"
28
+ HISTORY_FILE = LEARNED_DIR / "command_history.json"
29
+ SYNC_STATE_FILE = LEARNED_DIR / "brain_sync_state.json"
30
+ FLAW_BRAIN_FILE = LEARNED_DIR / "flaw_brain.json"
31
+
32
+ _CAMEL_SPLIT_RE = re.compile(r"[A-Z]?[a-z]+|[A-Z]+(?=[A-Z][a-z]|\b)|\d+")
33
+ _STOP_TOKENS = frozenset({
34
+ "workspace", "replicatedstorage", "replicatedfirst", "serverscriptservice",
35
+ "serverstorage", "startergui", "starterpack", "starterplayer", "players",
36
+ "localplayer", "character", "backpack", "playergui", "remotes", "remote",
37
+ "events", "event", "functions", "function", "folder", "model", "part",
38
+ "meshpart", "main", "menu", "script", "localscript", "modulescript",
39
+ "value", "intvalue", "numbervalue", "boolvalue", "stringvalue", "attribute",
40
+ "client", "server", "exposed", "endpoint", "visible", "accessible",
41
+ "readable", "high", "risk", "unanchored", "network", "ownership", "game",
42
+ "ui", "gui", "fx", "vfx", "sfx", "handler", "manager", "controller",
43
+ "system", "service", "core", "shared", "common", "default", "object",
44
+ "data", "info", "warn", "critical", "rcd", "matched", "state", "player",
45
+ "replicated", "local", "right", "left", "body", "storage", "top", "bottom",
46
+ })
47
+
48
+
49
+ def extract_game_tokens(text: str) -> list[str]:
50
+ """Extracts meaningful lowercase tokens from camelCase/PascalCase/snake_case paths."""
51
+ tokens: list[str] = []
52
+ seen: set[str] = set()
53
+ for part in re.split(r"[^A-Za-z0-9]+", text):
54
+ if not part:
55
+ continue
56
+ # Whole identifier token if >= 4 chars
57
+ whole = part.lower()
58
+ if len(whole) >= 4 and not whole.isdigit() and whole not in _STOP_TOKENS and whole not in seen:
59
+ seen.add(whole)
60
+ tokens.append(whole)
61
+ # Split camelCase sub-tokens
62
+ for sub in _CAMEL_SPLIT_RE.findall(part):
63
+ low = sub.lower()
64
+ if len(low) >= 4 and not low.isdigit() and low not in _STOP_TOKENS and low not in seen:
65
+ seen.add(low)
66
+ tokens.append(low)
67
+ return tokens
68
+
69
+
70
+ class AdaptiveLearner:
71
+ """
72
+ Persistent learning store that records newly discovered game tokens,
73
+ flaw frequencies, and place signatures across audits.
74
+ """
75
+
76
+ def __init__(self, store_path: Path = LEARNED_FILE, txt_path: Path = LEARNED_TXT_FILE) -> None:
77
+ self.store_path = store_path
78
+ self.txt_path = txt_path
79
+ self.learned_tokens: dict[str, dict[str, Any]] = {}
80
+ self.catalog_hits: dict[str, int] = {}
81
+ self.places_audited: list[str] = []
82
+ self.load()
83
+
84
+ def load(self) -> None:
85
+ if not self.store_path.exists():
86
+ return
87
+ try:
88
+ raw = json.loads(self.store_path.read_text(encoding="utf-8"))
89
+ if isinstance(raw, dict):
90
+ tokens = raw.get("learned_tokens", {})
91
+ if isinstance(tokens, dict):
92
+ self.learned_tokens = tokens
93
+ hits = raw.get("catalog_hits", {})
94
+ if isinstance(hits, dict):
95
+ self.catalog_hits = {str(k): int(v) for k, v in hits.items()}
96
+ places = raw.get("places_audited", [])
97
+ if isinstance(places, list):
98
+ self.places_audited = [str(p) for p in places]
99
+ except Exception:
100
+ pass
101
+
102
+ def save(self) -> None:
103
+ self.store_path.parent.mkdir(parents=True, exist_ok=True)
104
+ payload = {
105
+ "updated_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
106
+ "total_learned_tokens": len(self.learned_tokens),
107
+ "places_audited": self.places_audited[-50:],
108
+ "catalog_hits": self.catalog_hits,
109
+ "learned_tokens": self.learned_tokens,
110
+ }
111
+ self.store_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
112
+
113
+ # Also export human-readable pipe-delimited learned patterns file
114
+ lines: list[str] = []
115
+ for tok, info in sorted(self.learned_tokens.items()):
116
+ lines.append(
117
+ "|".join([
118
+ tok,
119
+ str(info.get("severity", "WARN")),
120
+ str(info.get("category", "RuntimeAudit")),
121
+ str(info.get("domain", "Learned")),
122
+ f"seen={info.get('seen_count', 1)}",
123
+ str(info.get("flaw", "")).replace("|", "/"),
124
+ str(info.get("fix", "")).replace("|", "/"),
125
+ ])
126
+ )
127
+ self.txt_path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
128
+
129
+ def learn_from_finding(
130
+ self,
131
+ finding: Finding,
132
+ catalog: FlawCatalog,
133
+ place_name: str = "Unknown",
134
+ ) -> int:
135
+ """
136
+ Learns from a single Finding. Returns the number of newly discovered tokens.
137
+ """
138
+ new_count = 0
139
+ cat_code = finding.metadata.get("catalog_code")
140
+ if cat_code:
141
+ self.catalog_hits[str(cat_code)] = self.catalog_hits.get(str(cat_code), 0) + 1
142
+
143
+ tokens = extract_game_tokens(f"{finding.path} {finding.title}")
144
+ domain = str(finding.metadata.get("domain") or finding.category or "Universal")
145
+
146
+ for tok in tokens:
147
+ # Skip tokens already natively indexed as primary keywords in flaws_18000.txt
148
+ if catalog.has_primary_keyword(tok):
149
+ continue
150
+
151
+ existing = self.learned_tokens.get(tok)
152
+ if existing is None:
153
+ self.learned_tokens[tok] = {
154
+ "severity": normalize_severity(finding.severity),
155
+ "category": finding.category,
156
+ "domain": domain,
157
+ "seen_count": 1,
158
+ "first_seen": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
159
+ "places": [place_name],
160
+ "flaw": finding.flaw or f"Learned pattern '{tok}' observed in {finding.category}.",
161
+ "abuse": finding.abuse or f"Custom endpoint/state '{tok}' may allow client tampering if unvalidated.",
162
+ "fix": finding.fix or f"Enforce server-side validation, typeof() checks, and cooldowns for '{tok}'.",
163
+ }
164
+ new_count += 1
165
+ else:
166
+ existing["seen_count"] = int(existing.get("seen_count", 1)) + 1
167
+ # Escalate learned severity if observed at higher severity
168
+ sev_rank = {"INFO": 1, "WARN": 2, "CRITICAL": 3}
169
+ old_sev = normalize_severity(str(existing.get("severity", "INFO")))
170
+ new_sev = normalize_severity(finding.severity)
171
+ if sev_rank.get(new_sev, 1) > sev_rank.get(old_sev, 1):
172
+ existing["severity"] = new_sev
173
+ places = existing.setdefault("places", [])
174
+ if place_name not in places and len(places) < 20:
175
+ places.append(place_name)
176
+
177
+ return new_count
178
+
179
+ def learn_from_session(self, session: AuditSession, catalog: FlawCatalog) -> int:
180
+ """
181
+ Automatically learns from all findings in an AuditSession and persists updates.
182
+ Returns the count of newly discovered tokens.
183
+ """
184
+ if session.target_name and session.target_name not in self.places_audited:
185
+ self.places_audited.append(session.target_name)
186
+
187
+ total_new = 0
188
+ for finding in session.findings:
189
+ total_new += self.learn_from_finding(finding, catalog, place_name=session.target_name)
190
+
191
+ if session.findings:
192
+ self.save()
193
+ if getattr(catalog, "brain", None) is not None:
194
+ for finding in session.findings:
195
+ catalog.brain.ingest_flaw_record(
196
+ domain=str(finding.metadata.get("domain", finding.category)),
197
+ severity=finding.severity,
198
+ text=f"{finding.title} {finding.path} {finding.flaw}",
199
+ fix=finding.fix,
200
+ )
201
+ catalog.brain.save()
202
+ return total_new
203
+
204
+
205
+ class CommandHistory:
206
+ """
207
+ Persistent JSON log of every rcdebug terminal command execution (~/.rcdebug/command_history.json).
208
+ Tracks command invocations, severities, learned tokens, and domain weights
209
+ so rcdebug gets smarter and faster across sessions.
210
+ """
211
+
212
+ def __init__(self, history_path: Path = HISTORY_FILE) -> None:
213
+ self.history_path = history_path
214
+ self.entries: list[dict[str, Any]] = []
215
+ self.domain_weights: dict[str, int] = {}
216
+ self.load()
217
+
218
+ def load(self) -> None:
219
+ if not self.history_path.exists():
220
+ return
221
+ try:
222
+ raw = json.loads(self.history_path.read_text(encoding="utf-8"))
223
+ if isinstance(raw, dict):
224
+ entries = raw.get("history", [])
225
+ if isinstance(entries, list):
226
+ self.entries = entries
227
+ weights = raw.get("domain_weights", {})
228
+ if isinstance(weights, dict):
229
+ self.domain_weights = {str(k): int(v) for k, v in weights.items()}
230
+ except Exception:
231
+ pass
232
+
233
+ def save(self) -> None:
234
+ self.history_path.parent.mkdir(parents=True, exist_ok=True)
235
+ payload = {
236
+ "updated_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
237
+ "total_commands": len(self.entries),
238
+ "domain_weights": self.domain_weights,
239
+ "history": self.entries[-500:],
240
+ }
241
+ self.history_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
242
+
243
+ def record_run(
244
+ self,
245
+ argv: list[str],
246
+ mode: str,
247
+ target: str = "",
248
+ filters: list[str] | None = None,
249
+ findings_count: int = 0,
250
+ severity_counts: dict[str, int] | None = None,
251
+ domains_seen: list[str] | None = None,
252
+ learned_added: int = 0,
253
+ duration_ms: float = 0.0,
254
+ synthetic: bool = False,
255
+ timestamp_override: str | None = None,
256
+ ) -> dict[str, Any]:
257
+ for dom in domains_seen or []:
258
+ if dom:
259
+ self.domain_weights[dom] = self.domain_weights.get(dom, 0) + 1
260
+
261
+ entry = {
262
+ "timestamp": timestamp_override or datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
263
+ "command": f"rcdebug {' '.join(argv)}".strip(),
264
+ "argv": argv,
265
+ "mode": mode,
266
+ "target": target,
267
+ "filters": filters or [],
268
+ "findings_count": findings_count,
269
+ "severity_counts": severity_counts or {"CRITICAL": 0, "WARN": 0, "INFO": 0},
270
+ "domains_seen": sorted(set(domains_seen or [])),
271
+ "learned_tokens_added": learned_added,
272
+ "duration_ms": round(duration_ms, 2),
273
+ "synthetic": synthetic,
274
+ }
275
+ self.entries.append(entry)
276
+ self.save()
277
+ return entry
278
+
279
+
280
+ _TRAINING_SCENARIOS: tuple[tuple[str, str, list[str], list[tuple[str, str, str, str]]], ...] = (
281
+ (
282
+ "SimulatorPlace",
283
+ "--client --critical --warning",
284
+ ["Economy", "Inventory", "Progression"],
285
+ [
286
+ ("CRITICAL", "EconomySecurity", "GiveRebirthCoins", "ReplicatedStorage.Remotes.GiveRebirthCoins"),
287
+ ("WARN", "InventorySecurity", "HatchMythicEgg", "ReplicatedStorage.Remotes.HatchMythicEgg"),
288
+ ("CRITICAL", "StateReplication", "PetMultiplier", "Players.LocalPlayer.PetMultiplier"),
289
+ ],
290
+ ),
291
+ (
292
+ "HorrorCoopPlace",
293
+ "--client --replay-log",
294
+ ["Vitals", "NetworkOwnership", "Session"],
295
+ [
296
+ ("WARN", "NetworkOwnership", "WraithPatrolRig", "Workspace.Monsters.WraithPatrolRig"),
297
+ ("CRITICAL", "StateReplication", "FlashlightBattery", "Workspace.Player1.FlashlightBattery"),
298
+ ("INFO", "StateReplication", "SanityMeter", "Players.LocalPlayer [Attribute:SanityMeter]"),
299
+ ],
300
+ ),
301
+ (
302
+ "FPSArenaPlace",
303
+ "--server --critical",
304
+ ["Combat", "Movement", "Admin"],
305
+ [
306
+ ("CRITICAL", "CombatSecurity", "FireBulletDamage", "ReplicatedStorage.Weapons.FireBulletDamage"),
307
+ ("CRITICAL", "PrivilegeEscalation", "ModKickRemote", "ReplicatedStorage.Admin.ModKickRemote"),
308
+ ("WARN", "PhysicsSecurity", "DashImpulse", "ReplicatedStorage.Movement.DashImpulse"),
309
+ ],
310
+ ),
311
+ (
312
+ "TycoonEmpirePlace",
313
+ "--server --place ./TycoonSrc --critical --warning",
314
+ ["Building", "Economy", "Shop"],
315
+ [
316
+ ("CRITICAL", "MarketplaceSecurity", "ClaimVipDropper", "ReplicatedStorage.Tycoon.ClaimVipDropper"),
317
+ ("WARN", "WorldSecurity", "PlotCollector", "Workspace.Tycoons.PlotCollector"),
318
+ ("CRITICAL", "EconomySecurity", "CollectBankPayout", "ReplicatedStorage.Remotes.CollectBankPayout"),
319
+ ],
320
+ ),
321
+ (
322
+ "RPGLobbyPlace",
323
+ "--client --warning",
324
+ ["Trading", "Session", "Vitals"],
325
+ [
326
+ ("CRITICAL", "EconomySecurity", "ConfirmPlayerTrade", "ReplicatedStorage.Trading.ConfirmPlayerTrade"),
327
+ ("WARN", "SessionSecurity", "DungeonTeleport", "ReplicatedStorage.Matchmaking.DungeonTeleport"),
328
+ ("CRITICAL", "StateReplication", "ManaPool", "Workspace.Player1.ManaPool"),
329
+ ],
330
+ ),
331
+ (
332
+ "VehicleDerbyPlace",
333
+ "--client --critical --warning",
334
+ ["Vehicle", "PhysicsSecurity", "Performance"],
335
+ [
336
+ ("WARN", "PhysicsSecurity", "NitroBoostSeat", "Workspace.Vehicles.NitroBoostSeat"),
337
+ ("CRITICAL", "RemoteTraffic", "ChassisSyncRemote", "ReplicatedStorage.Vehicles.ChassisSyncRemote"),
338
+ ("WARN", "Performance", "SkidmarkDebris", "Workspace.VFX.SkidmarkDebris"),
339
+ ],
340
+ ),
341
+ )
342
+
343
+
344
+ def seed_training_history(
345
+ catalog: FlawCatalog,
346
+ history: CommandHistory | None = None,
347
+ count: int = 24,
348
+ force: bool = False,
349
+ ) -> int:
350
+ """
351
+ Seeds randomized multi-genre terminal command history & learned flaw patterns
352
+ so rcdebug's brain (command_history.json + learned_flaws.json) starts warm and smart.
353
+ Returns number of seeded entries added.
354
+ """
355
+ hist = history or CommandHistory()
356
+ if hist.entries and not force:
357
+ return 0
358
+
359
+ rng = random.Random(20261117)
360
+ base_time = datetime.now() - timedelta(hours=count)
361
+ added = 0
362
+
363
+ for i in range(count):
364
+ place_name, cmd_str, domains, items = rng.choice(_TRAINING_SCENARIOS)
365
+ argv = cmd_str.split()
366
+ mode = "server" if "--server" in argv else "client"
367
+ filters = [f.lstrip("-").upper() for f in argv if f in ("--critical", "--warning", "--info")]
368
+ if "WARNING" in filters:
369
+ filters = ["WARN" if x == "WARNING" else x for x in filters]
370
+
371
+ sev_counts = {"CRITICAL": 0, "WARN": 0, "INFO": 0}
372
+ learned_added = 0
373
+ for sev, cat, title_tok, path in items:
374
+ sev_counts[sev] = sev_counts.get(sev, 0) + 1
375
+ f = Finding(
376
+ severity=sev,
377
+ category=cat,
378
+ title=f"Discovered {title_tok}",
379
+ path=path,
380
+ flaw=f"Pattern '{title_tok}' observed during {place_name} audit.",
381
+ abuse=f"Unvalidated '{title_tok}' endpoint or state can be spoofed by clients.",
382
+ fix=f"Enforce server-side typeof(), range, and cooldown validation for '{title_tok}'.",
383
+ )
384
+ catalog.enrich_finding(f)
385
+ learned_added += catalog.learner.learn_from_finding(f, catalog, place_name=place_name)
386
+
387
+ ts = (base_time + timedelta(minutes=i * rng.randint(12, 45))).strftime("%Y-%m-%d %H:%M:%S")
388
+ hist.record_run(
389
+ argv=argv,
390
+ mode=mode,
391
+ target=place_name,
392
+ filters=filters,
393
+ findings_count=len(items),
394
+ severity_counts=sev_counts,
395
+ domains_seen=domains,
396
+ learned_added=learned_added,
397
+ duration_ms=rng.uniform(42.0, 185.0),
398
+ synthetic=True,
399
+ timestamp_override=ts,
400
+ )
401
+ added += 1
402
+
403
+ catalog.learner.save()
404
+ return added
405
+
406
+
407
+ _LOG_WIRE_RE = re.compile(r"\[rcdebug-wire:report\]\s+(\{.*\})\s*$")
408
+ _LOG_CONSOLE_RE = re.compile(
409
+ r"\[rcdebug-console\]\s+\[(CRITICAL|WARN|INFO)\]\s+\[([^\]]+)\]\s+(.+?)\s+\|\s+(.+?)\s*$"
410
+ )
411
+ _ROBLOX_ERR_RE = re.compile(r"\[FLog::(?:Output|CreatorOutput|Error)\]\s+(.+)$")
412
+
413
+
414
+ class AutonomousBrainSync:
415
+ """
416
+ Continuously reads command_history.json and ~/Library/Logs/Roblox/*_last.log
417
+ so rcdebug learns automatically even outside explicit --learn runs.
418
+ """
419
+
420
+ def __init__(
421
+ self,
422
+ state_path: Path = SYNC_STATE_FILE,
423
+ log_dir: Path | None = None,
424
+ ) -> None:
425
+ self.state_path = state_path
426
+ self.log_dir = log_dir if log_dir is not None else (Path.home() / "Library" / "Logs" / "Roblox")
427
+ self.synced_history_count = 0
428
+ self.log_offsets: dict[str, int] = {}
429
+ self._load_state()
430
+
431
+ def _load_state(self) -> None:
432
+ if not self.state_path.exists():
433
+ return
434
+ try:
435
+ data = json.loads(self.state_path.read_text(encoding="utf-8"))
436
+ if isinstance(data, dict):
437
+ self.synced_history_count = int(data.get("synced_history_count", 0))
438
+ offsets = data.get("log_offsets", {})
439
+ if isinstance(offsets, dict):
440
+ self.log_offsets = {str(k): int(v) for k, v in offsets.items()}
441
+ except Exception:
442
+ pass
443
+
444
+ def _save_state(self) -> None:
445
+ self.state_path.parent.mkdir(parents=True, exist_ok=True)
446
+ self.state_path.write_text(
447
+ json.dumps(
448
+ {
449
+ "updated_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
450
+ "synced_history_count": self.synced_history_count,
451
+ "log_offsets": self.log_offsets,
452
+ },
453
+ indent=2,
454
+ ),
455
+ encoding="utf-8",
456
+ )
457
+
458
+ def sync_once(self, catalog: FlawCatalog, history: CommandHistory) -> int:
459
+ """
460
+ Ingests any unprocessed command_history.json entries and new Roblox log lines.
461
+ Returns total newly learned tokens.
462
+ """
463
+ new_tokens = 0
464
+ dirty = False
465
+
466
+ # 1. Always read & learn from command_history.json
467
+ history.load()
468
+ if len(history.entries) > self.synced_history_count:
469
+ for entry in history.entries[self.synced_history_count :]:
470
+ target = str(entry.get("target", ""))
471
+ cmd = str(entry.get("command", ""))
472
+ domains = entry.get("domains_seen", [])
473
+ dom = domains[0] if domains else "History"
474
+ if target or cmd:
475
+ f = Finding(
476
+ severity="INFO",
477
+ category="CommandHistory",
478
+ title=f"History Pattern: {target or cmd}",
479
+ path=target or cmd,
480
+ flaw=f"Observed in command history ({cmd}).",
481
+ abuse="Recurring targets/domains indicate high-value audit surfaces.",
482
+ fix=f"Prioritize {dom} server-side validation checks.",
483
+ metadata={"domain": dom},
484
+ )
485
+ new_tokens += catalog.learner.learn_from_finding(f, catalog, place_name=target or "CLI")
486
+ self.synced_history_count = len(history.entries)
487
+ dirty = True
488
+
489
+ # 2. Always scan new bytes in Roblox Player/Studio logs
490
+ if self.log_dir.exists():
491
+ candidates = sorted(
492
+ [
493
+ p
494
+ for p in self.log_dir.iterdir()
495
+ if p.is_file()
496
+ and p.name.endswith("_last.log")
497
+ and "CrashHandler" not in p.name
498
+ and ("_Player_" in p.name or "_Studio_" in p.name)
499
+ ],
500
+ key=lambda p: p.stat().st_mtime,
501
+ reverse=True,
502
+ )[:3]
503
+
504
+ for log_path in candidates:
505
+ key = str(log_path)
506
+ try:
507
+ size = log_path.stat().st_size
508
+ except OSError:
509
+ continue
510
+ offset = self.log_offsets.get(key, 0)
511
+ if size < offset:
512
+ offset = 0
513
+ if size <= offset:
514
+ continue
515
+
516
+ try:
517
+ with log_path.open("r", encoding="utf-8", errors="replace") as fh:
518
+ fh.seek(offset)
519
+ chunk = fh.read()
520
+ self.log_offsets[key] = fh.tell()
521
+ dirty = True
522
+ except OSError:
523
+ continue
524
+
525
+ for line in chunk.splitlines():
526
+ m_wire = _LOG_WIRE_RE.search(line)
527
+ if m_wire:
528
+ try:
529
+ data = json.loads(m_wire.group(1))
530
+ f = Finding(
531
+ severity=str(data.get("severity", "INFO")),
532
+ category=str(data.get("category", "RuntimeAudit")),
533
+ title=str(data.get("title", "Finding")),
534
+ path=str(data.get("path", "Roblox")),
535
+ flaw=str(data.get("flaw", "")),
536
+ abuse=str(data.get("abuse", "")),
537
+ fix=str(data.get("fix", "")),
538
+ )
539
+ catalog.enrich_finding(f)
540
+ new_tokens += catalog.learner.learn_from_finding(f, catalog, place_name=log_path.name)
541
+ except Exception:
542
+ pass
543
+ continue
544
+
545
+ m_con = _LOG_CONSOLE_RE.search(line)
546
+ if m_con:
547
+ sev, cat, title, path = m_con.groups()
548
+ f = Finding(
549
+ severity=sev,
550
+ category=cat,
551
+ title=title,
552
+ path=path,
553
+ flaw="",
554
+ abuse="",
555
+ fix="",
556
+ )
557
+ catalog.enrich_finding(f)
558
+ new_tokens += catalog.learner.learn_from_finding(f, catalog, place_name=log_path.name)
559
+ continue
560
+
561
+ if "ScriptContext" in line or "Infinite yield possible on" in line:
562
+ m_err = _ROBLOX_ERR_RE.search(line)
563
+ if m_err:
564
+ f = Finding(
565
+ severity="WARN",
566
+ category="RobloxRuntimeError",
567
+ title="Runtime Error / Infinite Yield",
568
+ path=m_err.group(1)[:140],
569
+ flaw="Detected runtime error or infinite WaitForChild yield in Roblox log.",
570
+ abuse="Unhandled script errors or missing timeout on WaitForChild break gameplay loops.",
571
+ fix="Add WaitForChild(name, 5) timeouts and nil guards.",
572
+ )
573
+ new_tokens += catalog.learner.learn_from_finding(f, catalog, place_name=log_path.name)
574
+
575
+ if dirty:
576
+ if new_tokens > 0:
577
+ catalog.learner.save()
578
+ self._save_state()
579
+
580
+ return new_tokens
581
+
582
+
583
+ _BRAIN_STOPWORDS = frozenset({
584
+ "the", "and", "for", "with", "from", "that", "this", "into", "when", "without",
585
+ "context", "handler", "endpoint", "client", "server", "clients", "players",
586
+ "player", "roblox", "system", "logic", "state", "values", "value", "before",
587
+ "instead", "directly", "over", "across", "during", "every", "all", "any",
588
+ "can", "may", "are", "is", "not", "or", "on", "in", "to", "of", "by", "as",
589
+ })
590
+
591
+
592
+ class FlawBrain:
593
+ """
594
+ Flaw-level statistical learner trained directly on the 18,000-flaw database,
595
+ the 120-probe Luau debugger pack, and every live finding observed at runtime.
596
+ Infers domain, severity, and remediation for previously unseen flaw patterns.
597
+ """
598
+
599
+ def __init__(self, brain_path: Path = FLAW_BRAIN_FILE) -> None:
600
+ self.brain_path = brain_path
601
+ self.total_flaws_learned: int = 0
602
+ self.token_domain_weights: dict[str, dict[str, int]] = {}
603
+ self.token_severity_counts: dict[str, dict[str, int]] = {}
604
+ self.domain_fixes: dict[str, str] = {}
605
+ self.load()
606
+
607
+ def load(self) -> None:
608
+ if not self.brain_path.exists():
609
+ return
610
+ try:
611
+ raw = json.loads(self.brain_path.read_text(encoding="utf-8"))
612
+ if isinstance(raw, dict):
613
+ self.total_flaws_learned = int(raw.get("total_flaws_learned", 0))
614
+ self.token_domain_weights = raw.get("token_domain_weights", {})
615
+ self.token_severity_counts = raw.get("token_severity_counts", {})
616
+ self.domain_fixes = raw.get("domain_fixes", {})
617
+ except Exception:
618
+ pass
619
+
620
+ def save(self) -> None:
621
+ self.brain_path.parent.mkdir(parents=True, exist_ok=True)
622
+ # Keep top 25,000 most informative flaw concepts
623
+ ranked_tokens = sorted(
624
+ self.token_domain_weights.items(),
625
+ key=lambda kv: (-sum(kv[1].values()), kv[0]),
626
+ )[:25000]
627
+ trimmed_domains = dict(ranked_tokens)
628
+ trimmed_sevs = {
629
+ tok: self.token_severity_counts[tok]
630
+ for tok in trimmed_domains
631
+ if tok in self.token_severity_counts
632
+ }
633
+ payload = {
634
+ "updated_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
635
+ "total_flaws_learned": self.total_flaws_learned,
636
+ "indexed_flaw_concepts": len(trimmed_domains),
637
+ "domain_fixes": self.domain_fixes,
638
+ "token_domain_weights": trimmed_domains,
639
+ "token_severity_counts": trimmed_sevs,
640
+ }
641
+ self.brain_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
642
+
643
+ def _extract_flaw_concepts(self, text: str) -> list[str]:
644
+ concepts: list[str] = []
645
+ seen: set[str] = set()
646
+ for tok in extract_game_tokens(text):
647
+ if tok not in _BRAIN_STOPWORDS and tok not in seen:
648
+ seen.add(tok)
649
+ concepts.append(tok)
650
+ return concepts
651
+
652
+ def ingest_flaw_record(
653
+ self,
654
+ domain: str,
655
+ severity: str,
656
+ text: str,
657
+ fix: str = "",
658
+ ) -> None:
659
+ sev = normalize_severity(severity)
660
+ concepts = self._extract_flaw_concepts(text)
661
+ for tok in concepts:
662
+ dom_map = self.token_domain_weights.setdefault(tok, {})
663
+ dom_map[domain] = dom_map.get(domain, 0) + 1
664
+ sev_map = self.token_severity_counts.setdefault(tok, {})
665
+ sev_map[sev] = sev_map.get(sev, 0) + 1
666
+ if fix and domain not in self.domain_fixes:
667
+ self.domain_fixes[domain] = fix
668
+ self.total_flaws_learned += 1
669
+
670
+ def train_from_corpus(self, catalog: FlawCatalog, pack: Any | None = None, force: bool = False) -> int:
671
+ """
672
+ Trains directly on all 18,000 flaws in flaws_18000.txt and all 120 probes
673
+ in luau_debugger_pack_120.json.
674
+ """
675
+ target_min = catalog.count() + (pack.count() if pack is not None else 0)
676
+ if not force and self.total_flaws_learned >= target_min and self.token_domain_weights:
677
+ return 0
678
+
679
+ self.total_flaws_learned = 0
680
+ self.token_domain_weights.clear()
681
+ self.token_severity_counts.clear()
682
+ self.domain_fixes.clear()
683
+
684
+ for sig in catalog.iter_signatures():
685
+ self.ingest_flaw_record(
686
+ domain=sig.domain,
687
+ severity=sig.severity,
688
+ text=f"{sig.title} {sig.flaw} {sig.abuse} {' '.join(sig.keywords)}",
689
+ fix=sig.fix,
690
+ )
691
+
692
+ if pack is not None:
693
+ for probe in pack.probes:
694
+ self.ingest_flaw_record(
695
+ domain=probe.category,
696
+ severity=probe.severity,
697
+ text=f"{probe.name} {probe.root_cause} {probe.source}",
698
+ fix=probe.fix,
699
+ )
700
+
701
+ self.save()
702
+ return self.total_flaws_learned
703
+
704
+ def predict(self, text: str) -> tuple[str, str, str] | None:
705
+ """
706
+ Infers (domain, severity, fix) for any unseen flaw or endpoint using
707
+ learned co-occurrence weights from the 18,000+ flaw brain.
708
+ """
709
+ concepts = self._extract_flaw_concepts(text)
710
+ if not concepts or not self.token_domain_weights:
711
+ return None
712
+
713
+ domain_scores: dict[str, float] = {}
714
+ sev_scores: dict[str, float] = {"CRITICAL": 0.0, "WARN": 0.0, "INFO": 0.0}
715
+ matched_any = False
716
+ total_docs = max(1, self.total_flaws_learned)
717
+
718
+ for tok in concepts:
719
+ dom_map = self.token_domain_weights.get(tok)
720
+ if dom_map:
721
+ matched_any = True
722
+ doc_freq = sum(dom_map.values())
723
+ idf = math.log((1.0 + total_docs) / (1.0 + doc_freq))
724
+ for dom, w in dom_map.items():
725
+ domain_scores[dom] = domain_scores.get(dom, 0.0) + (w * idf)
726
+ sev_map = self.token_severity_counts.get(tok)
727
+ if sev_map:
728
+ doc_freq = sum(sev_map.values())
729
+ idf = math.log((1.0 + total_docs) / (1.0 + doc_freq))
730
+ for sev, w in sev_map.items():
731
+ sev_scores[sev] = sev_scores.get(sev, 0.0) + (w * idf)
732
+
733
+ if not matched_any or not domain_scores:
734
+ return None
735
+
736
+ best_domain = max(domain_scores.items(), key=lambda kv: kv[1])[0]
737
+ best_sev = max(sev_scores.items(), key=lambda kv: kv[1])[0]
738
+ best_fix = self.domain_fixes.get(
739
+ best_domain,
740
+ f"Enforce server-authoritative validation and rate limiting for {best_domain} endpoints.",
741
+ )
742
+ return best_domain, best_sev, best_fix
743
+
744
+
745
+