wlbs-scan 0.6.0

WLBS Behavior Graph Scanner - static + dynamic curvature analysis for Python/JS codebases

wlbs-scan v0.6

English | 中文

---

English

Static + dynamic behavior graph scanner based on the World-Line Behavior Space (WLBS) framework.

Learns from your failures. Gets smarter over time. Zero dependencies beyond Python 3.8+.

---

Install

Option 1 — PyPI (recommended):

pip install wlbs-scan
wlbs-scan --help

Option 2 — from GitHub:

pip install git+https://github.com/val1813/wlbs-cli.git

Option 3 — clone and install locally:

git clone https://github.com/val1813/wlbs-cli.git
cd wlbs-cli
pip install -e .

Option 4 — run directly without installing:

python wlbs_scan.py <path>

Option 5 — self-validate after install:

python -m wlbs_scan.validate

python -m wlbs_scan.validate supports two modes:

• In the repository checkout, it runs the full validation suite from validation/run_validation.py.
• In an installed wheel outside the repo, it falls back to an embedded self-check harness with the same JSON schema (validation_mode indicates which path ran).

---

Commands

Command	What it does
wlbs-scan .	Scan + show risk map
wlbs-scan . --record-failure rbac	Record a test failure (teaches the system)
wlbs-scan . --record-fix roles	Record a fix (updates curvature down)
wlbs-scan . --pytest tests/	Auto-run pytest + record all results into world-lines
wlbs-scan . --history	View what the system has learned
wlbs-scan . --diff	Curvature delta since last scan
wlbs-scan . --suggest	Actionable fix recommendations for high-risk nodes
wlbs-scan . --suggest --suggest-node rbac	Reasoning-chain repair route for one symptom node
wlbs-scan . --advise rbac --json	Agent-friendly advisory JSON with confidence and open questions
wlbs-scan . --context rbac	Resolution-decay context assembly around one node
wlbs-scan . --record-outcome --symptom rbac --final-target roles --result pass	Persist task-level outcome and routing stats
wlbs-scan . --status	Show current risk status and optional account info
wlbs-scan . --dashboard	Open interactive local risk dashboard
wlbs-scan . --moe	MoE expert routing map (WLBS-guided activation weights)
wlbs-scan . --blame	Git blame on high-curvature nodes (line-range attribution)
wlbs-scan . --export-html report.html	Full HTML visualization report
wlbs-scan . --badges	README shield badge markdown
wlbs-scan . --ci --fail-above 0.85	CI mode — exit 1 if threshold exceeded
wlbs-scan . --init-hook	Install as git pre-commit hook
wlbs-scan . --watch --pytest tests/	Watch files + auto-rerun tests on change
wlbs-scan src/ --lang js	Scan JavaScript / TypeScript projects
wlbs-scan . --json	JSON output for CI/CD pipelines
wlbs-scan . --dist roles rbac	Behavioral distance between two nodes
wlbs-scan . --reset	Clear all learned history

---

How curvature κ is computed

Curvature κ(n) ∈ [0, 1] for each node (function / class / module):

If world-line history exists (failure_count > 0):
    bonus = 0.40 × history_signal + 0.15 × git_signal
    κ(n)  = static_curvature + bonus          # additive — failures only raise κ
Else if git history exists:
    κ(n)  = 0.45 × static + 0.55 × git
Else:
    κ(n)  = static_curvature

static_curvature = 0.35×(complexity/max_c) + 0.25×(import_count/max_i)
                 + 0.10×(line_count/max_l) + 0.15×(no_exception_handling)

history_signal   = recent_failure_rate × 0.8 + (failure_count/20) × 0.2
                   × discount (0.7 if last event was a fix, else 1.0)

Aporia / Backpropagation — when a node with failure_count > 0 reaches κ ≥ 0.5, its failure signal propagates upstream along dependency edges with exponential decay:

Δκ(dep) = κ(seed) × 0.5^depth        (paper §3.2: Δκ = α·λ^d)

This allows the system to identify root-cause modules that have no direct failures but are depended upon by failing nodes.

---

Singularity detection

A singularity is a high-curvature node (κ ≥ 0.55) that:

• Has no direct failure record of its own
• Has at least two downstream failure events in dependent nodes
• Has at least one caller (called_by > 0) or is imported by other modules
• Has structural complexity ≥ 2

Singularities are upstream root-cause candidates — the place to look when a failure manifests downstream.

---

Validated claims (paper § cross-reference)

All claims below are reproduced by running python validation/run_validation.py. See validation/VALIDATION_RESULTS.md for the full run log.

Paper Section	Claim	Result	Measured
§4 Impl	Demo scan latency	✅	avg 28.00 ms, max 39.94 ms (in-process)
§4 Impl	Scaling to larger Python projects	✅	60 files avg 47.10 ms
§3.1 Def 2	Behavioral distance d(roles, rbac) = 1 hop	✅	d = 1
§3.2	Upstream localization after downstream failures	✅	roles κ=1.000, downstream_failures=3
§3.1 Def 4	Singularity matches paper definition	✅	roles singularity, rbac not singularity
§3 General	World-line accumulation: κ strictly increases on low-static node	✅	0.087 → 0.411 → 0.415 → 0.419 → 0.423
§4 Impl	--pytest auto-records pass/fail into world-lines	✅	4 passed, 2 failed, 2 events persisted
§4 Impl	JS/TS support	✅	d(core, api)=1 on deterministic JS fixture
§4 Impl	HTML report export	✅	10,621-byte report artifact generated
§3.3	Resolution-decay context assembly	✅	near tier contains rbac and roles
§3.4	Reasoning-chain repair routing	✅	rbac routed to upstream target roles
Harness Phase 1	Advisory CLI output	✅	schema=wlbs-advisory-v1, tone=suggestion
Harness Phase 2	Task-level memory recording	✅	task_memory persisted with routing stats
Harness Phase 3	EMA policy learning	✅	pass-followed 0.825, fail-followed 0.277
Harness Phase 3	Similar-task transfer	✅	similar_past_tasks populated in advisory JSON
Harness Phase 4	Self-validation entrypoint	✅	python -m wlbs_scan.validate --json works

Reproduce: python validation/run_validation.py — rewrites VALIDATION_RESULTS.md with live data.

---

Demo project (roles.py → rbac.py)

The demo/ directory mirrors the paper's Figure 1 concrete failure scenario:

demo/
  roles.py          # root-cause module — 'admin' key missing in PERMISSIONS
  rbac.py           # downstream — imports roles.get_permissions(), crashes on 'admin'
  tests/
    test_rbac.py    # 4 pass / 2 intentional fail (test_admin_access, test_grant_permissions)

Run the demo:

cd demo
python ../wlbs_scan.py . --pytest tests/
python ../wlbs_scan.py . --history
python ../wlbs_scan.py . --dist roles rbac
python ../wlbs_scan.py . --context rbac
python ../wlbs_scan.py . --advise rbac --json
python ../wlbs_scan.py . --suggest --suggest-node rbac
python ../wlbs_scan.py . --record-outcome --symptom rbac --final-target roles --result pass --tests-before 4/6 --tests-after 6/6
python -m wlbs_scan.validate --json

---

MoE integration

--moe shows how a Mixture-of-Experts system routes gate decisions using curvature as activation weight:

p(expert_n) = κ(n) / Σκ

High-curvature nodes activate specialized experts (LoRA adapters in a full system). Singularities are targeted first when failure signals propagate upstream.

See: World-Line Behavior Space (Huang, 2026) · CN 2026103746505 · CN 2026103756225

---

Memory

All history is stored in .wlbs/world_lines.json in your project root. The file accumulates across sessions — the longer you use wlbs-scan, the more accurate its curvature estimates become.

wlbs-scan . --history    # see everything it has learned
wlbs-scan . --reset      # start over

Harness Loop

wlbs-scan can now work as a lightweight CLI harness in front of coding agents:

# 1. Ask for advisory output before editing
wlbs-scan . --advise rbac --json > wlbs_advice.json

# 2. Let your agent inspect files and make changes

# 3. Record the task outcome after tests
wlbs-scan . --record-outcome \
  --symptom rbac \
  --final-target roles \
  --result pass \
  --tests-before 4/6 \
  --tests-after 6/6

The advisory output is intentionally phrased as a suggestion rather than a directive. This lets a stronger agent disagree when it has better context, while still feeding the final outcome back into task memory for later policy learning.

Product Loop (V3)

For a Pro-style flow, the product loop now looks like this:

# local analysis
wlbs-scan . --status

# machine-readable routing
wlbs-scan . --advise rbac --json

# local dashboard
wlbs-scan . --dashboard

# task outcome persistence
wlbs-scan . --record-outcome --symptom rbac --final-target roles --result pass --tests-before 4/6 --tests-after 6/6

With --api-key, the CLI can also query account status and attempt best-effort trace upload to the hub server.

IDE Support

This repository now includes first-party IDE configuration for VS Code / Cursor style workflows:

• .vscode/extensions.json
• .vscode/settings.json
• .vscode/launch.json
• .vscode/tasks.json
• pyrightconfig.json
• .editorconfig

With these files in place you can:

# VS Code / Cursor integrated tasks
python -m pytest tests -q
python -m wlbs_scan.validate
python -m wlbs_scan . --advise rbac --json

Server

The standalone hub server lives in wlbs_server.py. Deployment material is included under deploy/DEPLOY_V3.md.

---

Roadmap

Feature	Status
Python AST graph + curvature	✅ v0.5
World-line persistence	✅ v0.5
Aporia backpropagation (Δκ = α·λ^d)	✅ v0.5
Singularity detection	✅ v0.5
--pytest auto-record	✅ v0.5
--blame line-range git attribution	✅ v0.5
--export-html visualization	✅ v0.5
--watch file change detection	✅ v0.5
JS/TS support (--lang js)	✅ v0.5
CI mode + pre-commit hook	✅ v0.5
Resolution-decay context assembly (--context)	✅ v0.6
LLM-guided repair suggestions (--suggest reasoning chain)	✅ v0.6
Advisory CLI harness (--advise)	✅ v0.6
Task memory + routing stats (--record-outcome)	✅ v0.6
EMA policy learning + similar task transfer	✅ v0.6
Self-validation entrypoint (python -m wlbs_scan.validate)	✅ v0.6
IDE workspace configs (.vscode / pyright / editorconfig)	✅ v0.6
Cross-repo world-line sharing	🔲 v0.6
Java / Go / Rust AST parsers	🔲 v0.6
VS Code extension	🔲 v0.7
GitHub Actions official action	🔲 v0.7
Online dashboard (world-line cloud sync)	🔲 v0.8

---

Figures

Figure 1 — System Architecture

Figure 2 — World-Line Data Structure

Figure 3 — Curvature Backpropagation (Aporia)

Figure 4 — Resolution-Decay Context Assembly

---

Theory

World-Line Behavior Space: A Unified Framework for Continual Learning and Spatial Root-Cause Attribution in AI-Driven Autonomous Systems Zhongchang Huang (黄中常), 2026 CN Patent Applications 2026103746505 · 2026103756225

Full paper: PAPER.md

---

License

Business Source License 1.1 (BSL 1.1)

• Free for non-commercial use, research, and internal evaluation
• Commercial use in third-party products/services requires a separate license
• Automatically converts to Apache 2.0 on 2029-01-01

See LICENSE for full terms. Patent protection: CN 2026103746505 · CN 2026103756225

---

Contact / 联系作者

Zhongchang Huang (黄中常) Email: [e-mail] WeChat: val001813

---

---

中文

基于世界线行为空间（WLBS）框架的静态+动态行为图扫描工具。

从你的失败中学习，越用越准。除 Python 3.8+ 外零依赖。

---

安装

方式一 — PyPI 直装（推荐）：

pip install wlbs-scan
wlbs-scan --help

方式二 — 从 GitHub 安装：

pip install git+https://github.com/val1813/wlbs-cli.git

方式三 — clone 后本地安装：

git clone https://github.com/val1813/wlbs-cli.git
cd wlbs-cli
pip install -e .

方式四 — 无需安装，直接运行：

python wlbs_scan.py <路径>

---

命令一览

命令	功能
wlbs-scan .	扫描并显示风险图谱
wlbs-scan . --record-failure rbac	记录测试失败（训练系统）
wlbs-scan . --record-fix roles	记录修复成功（曲率下调）
wlbs-scan . --pytest tests/	自动运行 pytest 并将结果写入世界线
wlbs-scan . --history	查看系统已学习的内容
wlbs-scan . --diff	与上次扫描对比曲率变化
wlbs-scan . --suggest	高风险节点的修复建议
wlbs-scan . --moe	MoE 专家路由权重图（WLBS 引导）
wlbs-scan . --blame	高曲率节点的 git blame（行级归因）
wlbs-scan . --export-html report.html	导出 HTML 可视化报告
wlbs-scan . --badges	生成 README 徽章 markdown
wlbs-scan . --ci --fail-above 0.85	CI 模式，超阈值退出码非零
wlbs-scan . --init-hook	安装为 git pre-commit hook
wlbs-scan . --watch --pytest tests/	监听文件变化并自动重跑测试
wlbs-scan src/ --lang js	扫描 JavaScript / TypeScript 项目
wlbs-scan . --json	JSON 输出，接入 CI/CD 流水线
wlbs-scan . --dist roles rbac	计算两个节点间的行为距离
wlbs-scan . --reset	清空所有学习历史

---

曲率 κ 计算方式

每个节点（函数/类/模块）的曲率 κ(n) ∈ [0, 1]：

若有世界线历史（failure_count > 0）：
    bonus = 0.40 × history_signal + 0.15 × git_signal
    κ(n)  = static_curvature + bonus     # 加法型：失败只会提升 κ
若仅有 git 历史：
    κ(n)  = 0.45 × static + 0.55 × git
否则：
    κ(n)  = static_curvature

static_curvature = 0.35×(复杂度/最大) + 0.25×(被引入数/最大)
                 + 0.10×(行数/最大) + 0.15×(无异常处理)

Aporia / 曲率反向传播 — 当 failure_count > 0 且 κ ≥ 0.5 的节点存在时， 失败信号沿依赖边向上游传播，按指数衰减：

Δκ(dep) = κ(seed) × 0.5^depth        （论文 §3.2: Δκ = α·λ^d）

这让系统能识别没有直接失败记录、但被失败节点依赖的根因模块。

---

验证数据（论文声明对照）

所有数据均通过 python validation/run_validation.py 真实测量， 完整记录见 validation/VALIDATION_RESULTS.md。

论文章节	声明	结果	实测数据
§4 实现	行为图构建速度	✅	avg 95–100 ms（3 文件 demo 项目）
§3.1 定义 2	行为距离 d(roles, rbac) = 1 跳	✅	d = 1
§3.2	rbac κ 在记录失败后上升	✅	0.820 → 1.000（+0.180）
§3.2	Aporia：roles κ 经反向传播上升（无直接失败）	✅	0.405 → 0.905（+0.500）
§3.1 定义 4	跨文件失败后检测到奇点	✅	singularities=[rbac]
§3.1 定义 4	roles 被反向传播识别（κ > static）	✅	κ=0.905, static=0.405
§3 总体	世界线累积：κ 单调不递减	✅	单调序列已验证
§4 实现	--pytest 自动记录通过/失败到世界线	✅	2 个事件已写入

复现方法： python validation/run_validation.py

---

Demo 项目（roles.py → rbac.py）

demo/ 目录复现了论文图 1 的具体失败场景：

demo/
  roles.py          # 根因模块 — PERMISSIONS 中缺少 'admin' 键
  rbac.py           # 下游模块 — 导入 roles.get_permissions()，访问 'admin' 时崩溃
  tests/
    test_rbac.py    # 4 通过 / 2 故意失败

cd demo
python ../wlbs_scan.py . --pytest tests/
python ../wlbs_scan.py . --history
python ../wlbs_scan.py . --dist roles rbac

---

路线图

功能	状态
Python AST 图 + 曲率计算	✅ v0.5
世界线持久化	✅ v0.5
Aporia 反向传播（Δκ = α·λ^d）	✅ v0.5
奇点（Singularity）检测	✅ v0.5
--pytest 自动记录	✅ v0.5
--blame 行级 git 归因	✅ v0.5
--export-html 可视化报告	✅ v0.5
--watch 文件变化监听	✅ v0.5
JS/TS 支持（--lang js）	✅ v0.5
CI 模式 + pre-commit hook	✅ v0.5
分辨率衰减上下文装配（--context）	✅ v0.6
LLM 引导的修复建议（推理链）	✅ v0.6
跨仓库世界线共享	🔲 v0.6
Java / Go / Rust AST 解析器	🔲 v0.6
VS Code 扩展	🔲 v0.7
GitHub Actions 官方 Action	🔲 v0.7
在线 Dashboard（世界线云同步）	🔲 v0.8

---

论文附图

附图 1 — 系统架构

附图 2 — 世界线数据结构

附图 3 — 曲率反向传播（Aporia）

附图 4 — 分辨率衰减上下文组装

---

理论基础

世界线行为空间：AI 驱动自主系统中持续学习与空间根因归因的统一框架 黄中常，2026 中国专利申请 2026103746505 · 2026103756225

完整论文：PAPER.md

---

许可证

Business Source License 1.1 (BSL 1.1)

• 非商业用途、科研、内部评估免费使用
• 面向第三方的商业产品/服务需向作者申请商业授权
• 2029-01-01 自动转为 Apache 2.0

完整条款见 LICENSE。 WLBS 方法论受专利保护：CN 2026103746505 · CN 2026103756225

---

联系作者

黄中常 (Zhongchang Huang) 邮箱：[e-mail] 微信：val001813