# silicon_truth_bridge

Silicon Truth Bridge（STB）是一个只读 EDA evidence MCP server。它把设计
数据库、FSDB 波形以及 CDC/Lint saved session 转换为结构化、可分页、可审计的
证据，供 Codex、其他 MCP client 或命令行工作流使用。

STB 不替代 EDA 工具，也不自动修改 RTL、Constraints 或 Waiver。它负责把工具
数据库中的事实安全地交给上层分析流程。

## 主要能力

- Verdi design DB 与 FSDB：对象查询、连通性、Trace、波形、源码上下文、
  Assertion 结构和 design-to-waveform mapping。
- VC Static CDC/Lint saved session：summary、Violation、rule、Waiver、clock、
  reset、Constraints provenance、源码和有界 topology evidence。
- `cdc_evidence_bundle`：面向单条或一组 Violation 聚合规则、clock pair、源码、
  Constraints、Waiver 和 topology，减少交互式 RCA 的往返次数。
- 两阶段 CDC cleanup report：先冻结 evidence 和分析任务，再校验 analyst/reviewer
  结果，最后离线生成中文 HTML 报告。
- 多 context、generation-bound ObjectRef/cursor、资源变更检测、响应大小限制和
  worker hard-timeout 恢复。
- MCP server、CLI、worker 和 supervisor 共享同一个 dispatcher。
- fake backend 提供无 EDA 环境的契约测试与开发能力。

当前公开接口包含 46 个核心工具和 6 个可选诊断工具。

## 安全边界

STB 的默认边界是只读和白名单化：

- 不运行或更新 CDC/Lint 工程。
- 不修改 design DB、FSDB、Constraints 或 Waiver。
- 不接受任意 Tcl、shell、Python 或 NPI method string。
- 不暴露 raw NPI handle。
- 只允许访问 `STB_ALLOWED_ROOTS` 下的文件。
- 原生静态分析报告通过逻辑报告名和严格参数调用。
- source、report、trace 和 response 均有界。
- worker generation 变化后，旧 ObjectRef 和 cursor 立即失效。

VC Static backend 只接受由 `save_session` 生成且包含 `vsi.tar` 或
`vsi.tar.lz4` 的目录。普通工作 RTDB 不作为输入。

## 安装

要求 Python 3.11 或更高版本。

```bash
python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
```

外部 EDA 工具、license、design DB、FSDB 和 saved session 由用户自行准备，不随
本仓库分发。

## 快速开始

### Fake backend

Fake backend 不需要 EDA 环境：

```bash
export STB_BACKEND=fake
export STB_ALLOWED_ROOTS="$PWD"

stb schema object_query
stb --pretty call object_query --request - <<'JSON'
{"context_id":"demo","request":{"scope":"top","limit":20}}
JSON
```

需要先打开 context 的 CLI 工作流可以使用交互模式或 JSONL batch：

```bash
stb --pretty shell
```

```json
{"tool":"context_manage","request":{"action":"open","context_id":"demo","backend":"fake"}}
{"tool":"object_resolve","request":{"context_id":"demo","request":{"name":"top.u_core.req"}}}
```

### Verdi/FSDB backend

```bash
export VERDI_HOME=/path/to/verdi
export STB_BACKEND=verdi
export STB_VERDI_HOME="$VERDI_HOME"
export STB_ALLOWED_ROOTS="/project/design:$VERDI_HOME"
```

打开 design DB 和 FSDB：

```json
{
  "tool": "context_manage",
  "request": {
    "action": "open",
    "context_id": "debug",
    "backend": "verdi",
    "design_spec": {"path": "/project/design/simv.daidir"},
    "wave_specs": [{"wave_id": "run0", "path": "/project/design/run.fsdb"}]
  }
}
```

### CDC/Lint saved session

```bash
export VC_STATIC_HOME=/path/to/vc_static/V-2023.12-SP2
export STB_BACKEND=vc_static
export STB_VC_STATIC_HOME="$VC_STATIC_HOME"
export STB_ALLOWED_ROOTS="/project/design:$VC_STATIC_HOME"
```

先探测 session，再显式打开 context：

```json
{
  "tool": "static_db_probe",
  "request": {
    "path": "/project/design/cdc/saved_session",
    "domains": ["cdc"]
  }
}
```

```json
{
  "tool": "static_context_manage",
  "request": {
    "action": "open",
    "context_id": "cdc",
    "session_spec": {
      "path": "/project/design/cdc/saved_session",
      "domains": ["cdc"]
    }
  }
}
```

查询 summary 和单条 Violation：

```json
{"tool":"cdc_summary","request":{"context_id":"cdc","request":{}}}
```

```json
{
  "tool": "cdc_violation_resolve",
  "request": {
    "context_id": "cdc",
    "request": {
      "violation_ids": ["CDC:1001"],
      "disposition": "unwaived"
    }
  }
}
```

完整 backend 能力、边界和 cleanup report 流程见
[docs/vc-static.md](docs/vc-static.md)。

## CDC cleanup report

HTML 报告采用 fail-closed 的两阶段流程。Evidence collector 只读 saved session；
最终 Root cause 和 Decision 必须来自 cluster RCA analyst，并按任务要求经过独立
reviewer。模板 fallback 只允许用于调试。

### 1. 准备 evidence 与任务

```bash
.venv/bin/python scripts/generate_cdc_cleanup_report.py \
  --session /project/design/cdc/saved_session \
  --output /project/reports/cdc_cleanup_report.html \
  --vc-static-home "$VC_STATIC_HOME" \
  --allowed-roots "/project/design:$VC_STATIC_HOME" \
  --prepare-analysis
```

生成：

```text
cdc_cleanup_report.evidence.json
cdc_cleanup_report.analysis-tasks.json
```

### 2. 汇总 analyst 与 reviewer 输出

```bash
.venv/bin/python scripts/assemble_cdc_analysis.py \
  --tasks /project/reports/cdc_cleanup_report.analysis-tasks.json \
  --fragment /project/reports/analyst-a.json \
  --fragment /project/reports/analyst-b.json \
  --reviews /project/reports/reviewer-a.json \
  --output /project/reports/cdc_cleanup_report.reviewed-analysis.json
```

Assembler 会检查 cluster/member 覆盖、packet hash、analyst receipt、reviewer
覆盖和 Decision 一致性。缺失、重复或存在未裁决分歧时拒绝输出可渲染结果。

### 3. 离线生成 HTML

```bash
.venv/bin/python scripts/generate_cdc_cleanup_report.py \
  --session /project/design/cdc/saved_session \
  --output /project/reports/cdc_cleanup_report.html \
  --evidence-input /project/reports/cdc_cleanup_report.evidence.json \
  --analysis-input /project/reports/cdc_cleanup_report.reviewed-analysis.json
```

渲染阶段不会重新打开 saved session。只有 evidence fingerprint、完整覆盖、
family hard gate、reviewer 和 cleanup work package 全部通过后，才生成 HTML。

报告重点是工程决策而不是复刻 EDA GUI：

- 每条 Violation 的规则含义、source/destination clock domain 和 Root cause。
- crossing、convergence、glitch、reset 与 quasi-static evidence boundary。
- `Fix RTL`、`Fix Constraints`、`Investigate`、`Conditional waive` 或 `Waive`
  建议及其成立条件。
- Root cause cluster、cleanup work package、Owner、依赖、退出条件和审计链。
- 按 Decision、Tag、Root cause、Confidence 和 clock pair 分组/过滤。
- 支持 `tag:`、`rule:`、`object:`、`clock:`、`cause:`、`source:`、
  `quasi:` 和 `convergence:` 等字段检索。

## MCP server

启动 stdio MCP server：

```bash
stb-mcp
```

通用 MCP 配置示例：

```json
{
  "mcpServers": {
    "stb": {
      "command": "/path/to/silicon_truth_bridge/.venv/bin/stb-mcp",
      "env": {
        "STB_BACKEND": "fake",
        "STB_ALLOWED_ROOTS": "/project/design"
      }
    }
  }
}
```

真实 backend 还需在 `env` 中配置对应的 tool home。不要把 license、token、项目
路径或私有 session 写入公开配置。

## 配置

| 环境变量 | 默认值 | 说明 |
|---|---|---|
| `STB_BACKEND` | `fake` | `fake`、`verdi` 或 `vc_static` |
| `STB_ALLOWED_ROOTS` | 当前目录 | 冒号分隔的允许访问根目录 |
| `STB_ARTIFACT_ROOT` | `.stb/artifacts` | 大结果 artifact 目录 |
| `STB_VERDI_HOME` | `$VERDI_HOME` | Verdi 安装路径 |
| `STB_VERDI_RELEASE` | 自动识别 | 显式 release override |
| `STB_VC_STATIC_HOME` | `$VC_STATIC_HOME` | VC Static 安装路径 |
| `STB_VC_STATIC_RELEASE` | 自动识别 | 显式 release override |
| `STB_ALLOW_UNVERIFIED_VERDI` | `false` | 允许未验证 release 试运行 |
| `STB_ALLOW_UNVERIFIED_VC_STATIC` | `false` | 允许未验证 release 试运行 |
| `STB_MAX_ACTIVE_CONTEXTS` | `4` | 最大 active context 数 |
| `STB_DEFAULT_TIMEOUT_SEC` | `120` | 请求 soft timeout |
| `STB_HARD_TIMEOUT_SEC` | `300` | worker hard timeout |
| `STB_NORMAL_RESPONSE_BYTES` | `4194304` | 普通响应上限 |
| `STB_HARD_RESPONSE_BYTES` | `16777216` | 硬响应上限 |
| `STB_DEV_TOOLS` | `false` | 注册 admin 诊断工具 |

## 工具分组

设计与波形：

```text
context_manage wave_manage catalog
object_resolve object_get object_query object_traverse
connectivity_direct trace trace_active_driver trace_value_origin
wave_value wave_changes wave_compute
source_context assertion_structure mapping artifact
```

CDC/Lint：

```text
static_db_probe static_context_manage static_catalog static_report_catalog
cdc_summary cdc_violation_query cdc_violation_resolve cdc_violation_get
cdc_explain_violation cdc_evidence_bundle cdc_rule_get cdc_waiver_audit
lint_summary lint_violation_query lint_violation_get lint_explain_violation
lint_rule_get lint_waiver_audit
static_object_resolve static_object_get static_object_query
static_connectivity_direct static_trace static_case_trace
static_source_context static_clock_relationship
static_constraint_provenance static_report_run
```

诊断工具仅在 `STB_DEV_TOOLS=true` 时注册：

```text
admin_doctor admin_metrics admin_trace
admin_logs admin_benchmark admin_selftest
```

使用 `stb schema <tool>` 查看准确请求 schema。

## 测试

```bash
.venv/bin/pytest -q
```

运行公开 fake benchmark：

```bash
PYTHONPATH=src .venv/bin/python scripts/run_benchmarks.py \
  --iterations 20 \
  --output benchmarks/fake-baseline.json
```

真实 EDA 环境测试默认跳过，需要由使用者在具备工具、license 和测试数据的环境中
显式启用。私有 session、golden、RCA benchmark 和生成的 evidence/analysis 文件
不属于公开仓库。

## 目录

```text
src/stb/                         server、dispatcher、supervisor 与 backend
src/stb/backends/verdi.py        design DB / FSDB backend
src/stb/backends/vc_static.py    CDC/Lint saved-session backend
src/stb/cdc_analysis.py          RCA task、validation 与 cleanup model
scripts/                         benchmark 与 cleanup report 工具
tests/                           fake、contract 与 backend 单元测试
docs/                            架构、CLI、API 和 backend 文档
```

## 文档

- [Static CDC/Lint backend](docs/vc-static.md)
- [V1 architecture](docs/stb-v1-architecture.md)
- [V1 API contract](docs/stb-v1-api-contract.md)
- [CLI](docs/stb-v1-cli.md)
- [Verification plan](docs/stb-v1-verification-plan.md)

## 许可证

本项目采用仓库内 [LICENSE](LICENSE) 定义的个人研究许可证。外部 EDA 软件、
数据库、规则文档和用户设计不包含在本许可证或本仓库中。