progmune-runtime 2.0.4 → 2.1.1

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "progmune": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "dist/mcp-server.mjs"
+      ]
+    }
+  }
+}

package/.progmune_allowlist

@@ -0,0 +1,50 @@
+# Progmune Allowlist — files exempt from @progmune-generated requirement
+# Add patterns (one per line) for files that don't need the marker.
+# Lines starting with # are comments.
+
+# Configuration files
+\\.json$
+\\.md$
+\\.sh$
+\\.css$
+\\.html$
+
+# Test files
+test-.*
+.*\\.test\\.ts$
+.*\\.spec\\.ts$
+test_.*\\.ts$
+test_.*\\.mjs$
+test_.*\\.js$
+
+# Build artifacts
+dist/
+node_modules/
+
+# Progmune's own infrastructure (core files that predate Phase 4.5)
+src/runtime-types\\.ts$
+src/runtime-invariants\\.ts$
+src/ssg-validator\\.ts$
+src/failure-corpus\\.ts$
+src/memory-layer\\.ts$
+src/planner\\.ts$
+src/emitter\\.ts$
+src/extract-ir.*\\.ts$
+src/validator\\.ts$
+src/semantic-validator\\.ts$
+src/action-runtime\\.ts$
+src/actions\\.ts$
+src/llm\\.ts$
+src/utils\\.ts$
+src/feedback\\.ts$
+src/immune-reporter\\.ts$
+src/report\\.ts$
+src/file-lock\\.ts$
+src/consolidate\\.ts$
+src/mcp-server\\.ts$
+src/check\\.ts$
+src/semantic-trace\\.ts$
+src/semantic-snapshot\\.ts$
+src/obs-web\\.ts$
+src/p0_ssg_demo\\.ts$
+src/main\\.ts$

package/.test_report/test_report.md

@@ -0,0 +1,87 @@
+# Progmune Runtime 综合测试报告
+
+**测试时间**: 2026-05-23 14:15:09
+**运行时长**: 3171ms
+**测试版本**: 2.0.5
+**LLM 后端**: DeepSeek Chat (deepseek-chat)
+**Node 版本**: v20.11.1
+
+---
+
+## 测试结果摘要
+
+| 指标 | 数值 |
+|------|------|
+| 总用例 | 29 |
+| 通过 | 29 |
+| 失败 | 0 |
+| 通过率 | 100.0% |
+
+## 逐项测试详情
+
+| # | 测试项 | 状态 | 说明 |
+|---|--------|------|------|
+| 1 | MCP tools/list 返回工具列表 | ✅ PASS | 返回 2 个工具 |
+| 2 | MCP 暴露 progmune_generate 工具 | ✅ PASS | 工具名: progmune_generate |
+| 3 | 工具包含 intent 参数 | ✅ PASS |  |
+| 4 | 工具包含 projectPath 参数 | ✅ PASS |  |
+| 5 | SVL-1: 调用存在的函数通过 | ✅ PASS |  |
+| 6 | SVL-1: 拦截不存在的函数 | ✅ PASS | 错误: 函数 'nonexistent_func' 不存在 |
+| 7 | SVL-1: 错误消息包含"不存在" | ✅ PASS | 函数 'nonexistent_func' 不存在 |
+| 8 | SVL-2: 参数数量匹配通过 | ✅ PASS |  |
+| 9 | SVL-2: 拦截参数数量不匹配 | ✅ PASS | 错误: 参数数量不匹配: 期望 2, 实际 1 |
+| 10 | SVL-2: 错误消息包含"参数数量" | ✅ PASS | 参数数量不匹配: 期望 2, 实际 1 |
+| 11 | SVL-3: 变量先声明后使用通过 | ✅ PASS |  |
+| 12 | SVL-3: 拦截未声明变量 | ✅ PASS | 错误: 变量 'undeclaredVar' 在赋值前未声明 |
+| 13 | SVL-3: 拦截条件中未声明变量 | ✅ PASS | 错误: 条件中引用了未声明的变量 'undefinedVar' |
+| 14 | SVL-3: 复杂嵌套变量流通过 | ✅ PASS |  |
+| 15 | SVL-4: 认证动作合法 | ✅ PASS | 状态: UNAUTHENTICATED -> AUTHENTICATED |
+| 16 | SVL-4: 认证后签发令牌合法 | ✅ PASS | 状态: AUTHENTICATED -> TOKEN_ISSUED |
+| 17 | SVL-4: 拦截未认证直接签发令牌 | ✅ PASS | 错误: [PROGMUNE] L4 协议违规：issue_token
+  当前状态：UNAUTHENTICATED
+  期望前置状态：AUTHENTICATED
+  缺失步骤：authenticate → AUTHENTICATED |
+| 18 | Failure Corpus: 记录失败案例 | ✅ PASS | 共 17 条 |
+| 19 | Failure Corpus: 按 SVL-1 过滤 | ✅ PASS | 找到 2 条 |
+| 20 | Failure Corpus: 生成失败模式统计 | ✅ PASS | [{"pattern":"SVL-4:protocol","count":11},{"pattern":"SVL-1:symbol_existence","count":2},{"pattern":"SVL-2:type_mismatch","count":2}] |
+| 21 | 记忆系统: 记录情景记忆 | ✅ PASS | 共 5 条 |
+| 22 | 记忆系统: 过滤成功情景 | ✅ PASS | 共 5 条 |
+| 23 | 记忆系统: 语义模板巩固与匹配 | ✅ PASS | 模板: tmpl_1779545707638, 成功率: 1 |
+| 24 | 边界: 空动作序列通过 | ✅ PASS |  |
+| 25 | 边界: 拦截未知动作类型 | ✅ PASS | 无效动作类型: 'invalid_kind' |
+| 26 | 边界: 多层嵌套通过 | ✅ PASS |  |
+| 27 | 白名单: 内置函数通过校验 | ✅ PASS | console.log, JSON.stringify |
+| 28 | 端到端: 生成动作序列 | ✅ PASS | 共 2 个动作 |
+| 29 | 端到端: 生成 Python 代码 | ✅ PASS | 代码长度: 144 字符 |
+
+---
+
+## SVL 层级覆盖矩阵
+
+| SVL 级别 | 名称 | 测试覆盖 | 状态 |
+|:---------:|:----|:---------|:----:|
+| SVL-1 | 符号存在性 | 调用存在/不存在函数校验 | ✅ |
+| SVL-2 | 类型有效性 | 参数数量匹配校验 | ✅ |
+| SVL-3 | 数据流正确性 | 变量声明/使用、嵌套作用域 | ✅ |
+| SVL-4 | 协议合法性 | SSG 状态机、非法跃迁拦截 | ✅ |
+
+## 系统组件覆盖
+
+| 组件 | 测试覆盖 | 状态 |
+|:-----|:---------|:----:|
+| MCP 协议层 | tools/list、tools/call | ✅ |
+| 校验引擎 (Validator) | SVL-1~3 校验 | ✅ |
+| SSG 状态机 | 协议跃迁校验 | ✅ |
+| Failure Corpus | 记录/查询/模式统计 | ✅ |
+| 三层记忆系统 | 情景记忆/语义模板 | ✅ |
+| 代码生成器 | 动作序列 → Python | ✅ |
+| 内置白名单 | console.log / fetch 等 | ✅ |
+| 边界情况 | 空序列/嵌套/非法类型 | ✅ |
+
+## 结论
+
+**全部测试通过。** Progmune Runtime 各核心组件运行正常，约束引擎、SSG 协议校验、记忆系统和 Failure Corpus 均按预期工作。
+
+---
+
+*报告由 Progmune Runtime 综合测试套件自动生成*

package/Dockerfile

@@ -1,17 +1,9 @@
 FROM node:18-alpine
-
 WORKDIR /app
-
-# 只复制运行时需要的文件
 COPY server/ ./server/
 COPY dist/ ./dist/
+COPY public/ ./public/
 COPY package.json package-lock.json* ./
-
-# 安装生产依赖
 RUN npm install --production
-
-# 暴露端口
-EXPOSE 3000
-
-# 启动中央免疫服务器
+EXPOSE 8080
 CMD ["node", "server/hub.js"]

package/FAQ.md

@@ -0,0 +1,167 @@
+# Progmune Runtime 常见问题 (FAQ)
+
+## 安装与配置
+
+### 如何获取 LLM API 密钥？
+
+Progmune 需要 LLM API 密钥来生成代码。目前支持 DeepSeek 和 OpenAI 兼容接口。
+
+**DeepSeek:**
+1. 访问 https://platform.deepseek.com/api_keys
+2. 注册账号并创建 API 密钥
+3. 密钥格式：`sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+**OpenAI:**
+1. 访问 https://platform.openai.com/api-keys
+2. 创建 API 密钥
+3. 设置环境变量 `LLM_BASE_URL=https://api.openai.com/v1` 和 `LLM_MODEL=gpt-4`
+
+### 如何配置 API 密钥？
+
+**方式一：MCP 客户端配置（推荐）**
+在 `~/.claude/settings.json` 中：
+```json
+{
+  "mcpServers": {
+    "progmune": {
+      "command": "npx",
+      "args": ["progmune-runtime"],
+      "env": {
+        "LLM_API_KEY": "你的密钥",
+        "LLM_BASE_URL": "https://api.deepseek.com/v1"
+      }
+    }
+  }
+}
+```
+
+**方式二：环境变量**
+```bash
+export LLM_API_KEY="你的密钥"
+npx progmune-runtime
+```
+
+**方式三：快速配置命令**
+```bash
+npx progmune-runtime setup 你的密钥
+```
+
+### 如何验证安装是否成功？
+
+```bash
+# 检查版本
+npx progmune-runtime --version
+
+# 检查 MCP 工具列表（需在 MCP 客户端中）
+# 应看到 progmune_generate 和 progmune_status 两个工具
+
+# 运行内置测试
+npx progmune-runtime test
+```
+
+### 为什么浏览器打不开仪表板？
+
+如果运行 `open http://localhost:8080/` 无效：
+
+1. **确认 Hub 服务器正在运行：**
+   ```bash
+   curl http://localhost:8080/api/dashboard
+   ```
+   如果返回 JSON 数据，说明服务器运行正常。
+
+2. **手动在浏览器打开：**
+   - 在地址栏输入 `http://localhost:8080/`
+   - 注意使用 `http://` 而非 `https://`（本地服务器不支持 HTTPS）
+
+3. **端口冲突：**
+   - 默认端口 8080，可通过 `PORT` 环境变量修改
+   - 检查是否有其他程序占用：`lsof -i :8080`
+
+## 使用问题
+
+### MCP 配置失败怎么办？
+
+**症状：** Claude Code 提示 "MCP server progmune not found"
+
+**排查步骤：**
+1. 确认 `~/.claude/settings.json` 中配置格式正确
+2. 确认 Node.js >= 18 已安装：`node --version`
+3. 尝试手动启动验证：`npx progmune-runtime`
+4. 检查 Claude Code 日志中是否有错误信息
+
+**症状：** 调用 `progmune_generate` 返回 "未设置 LLM_API_KEY"
+
+即使已在终端 `export` 了密钥，MCP 子进程也可能无法继承。必须在 `settings.json` 的 `env` 字段中显式配置。
+
+### 如何开启免疫网络上报？
+
+```bash
+# 开启（推荐）
+npx progmune-runtime opt-in enable
+
+# 关闭
+npx progmune-runtime opt-in disable
+
+# 查看状态
+npx progmune-runtime opt-in status
+```
+
+开启后，每次代码生成的脱敏错误指纹会自动上报到中央免疫服务器。
+
+### 如何部署中央免疫服务器？
+
+```bash
+# 启动本地 Hub
+cd progmune-runtime
+node server/hub.js
+
+# 设置环境变量让 MCP 服务器自动上报
+export PROGMUNE_HUB=http://localhost:8080/report
+```
+
+仪表板访问：`http://localhost:8080/`
+
+## 错误与调试
+
+### "无法生成满足约束的代码"
+
+这意味着 LLM 生成的代码未能通过 Progmune 的约束校验（SVL-1~4）。常见原因：
+
+1. **IR 为空：** 项目目录中没有提取到函数定义。确认 `projectPath` 指向包含 `.py` 文件的目录。
+2. **LLM 输出不符合格式：** DeepSeek/OpenAI 返回了非预期的格式。重试通常可以解决。
+3. **SSG 协议违规：** 生成的代码跳过了必要的业务步骤。错误信息会提示缺失的步骤。
+
+### "函数 'xxx' 不存在"
+
+这是 SVL-1 符号存在性校验的拦截。说明 LLM 幻觉调用了一个项目中不存在的函数。这是 Progmune 的正常保护行为。
+
+### 如何查看运行状态？
+
+通过 MCP 调用 `progmune_status` 工具，返回 JSON 格式的运行状态，包括：
+- LLM 模型和调用次数
+- 免疫网络状态
+- Failure Corpus 统计
+- 记忆系统状态
+
+## 技术细节
+
+### Progmune 支持哪些语言？
+
+目前代码生成支持 **Python**。IR 提取支持 Python 项目（通过 `extract-ir-python.ts`）。
+
+### 数据隐私如何保障？
+
+上报到中央免疫服务器的数据**只包含**：
+- 函数名序列（如 `verify_password → generate_jwt`）
+- SVL 违规级别
+- 约束类型
+
+**绝不包含**：
+- 代码片段
+- 变量值
+- 文件内容
+- 用户数据
+
+### 如何贡献？
+
+欢迎通过 GitHub Issues 提交"看似合法但实际危险"的生成案例，帮助我们完善语义状态图（SSG）协议。

package/README.md

@@ -1,12 +1,27 @@
 # Progmune Runtime（免序）
 
-**程序免疫学：为生成式程序建立免疫系统**
+**程序免疫学：约束引导的程序合成运行时**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
 [![Stage: Technical Preview](https://img.shields.io/badge/Stage-Technical_Preview-orange)]()
 
-**Progmune（免序）不是一个 AI 编程助手，而是一个面向生成式程序的免疫系统。** 它将大语言模型（LLM）从开放世界的代码生成器，降级为在程序真相层（IR）严格约束下的启发式搜索器，确保生成的代码不仅在符号和类型上正确，更在行为协议上合法。
+Progmune（免序）不是一个 AI 编程助手，而是一个面向生成式程序的免疫系统。它将大语言模型（LLM）从开放世界的代码生成器，降级为在程序真相层（IR）严格约束下的启发式搜索器，确保生成的代码不仅在符号和类型上正确，更在行为协议上合法。
+
+---
+
+## 目录
+
+- [核心命题](#核心命题ai-生成的程序必须具备免疫系统)
+- [架构概览](#架构概览一个会学习会记忆会防御的运行时)
+- [语义有效性级别 (SVL)](#语义有效性级别-svl)
+- [v2.1.0 新特性：抗体与快照](#v210-新特性抗体与快照)
+- [Semantic Observatory](#semantic-observatory语义观测台)
+- [快速开始](#快速开始)
+- [CLI 命令](#cli-命令)
+- [MCP 工具](#mcp-工具)
+- [全球免疫网络](#全球免疫网络-global-immune-network)
+- [许可证](#许可证)
 
 ---
 
@@ -14,7 +29,7 @@
 
 LLM 在生成代码时会产生“幻觉”——调用不存在的函数、违反类型约束、跳过关键的业务步骤。传统的提示工程和事后校验无法根除这些问题，因为它们将 LLM 置于系统的中心，缺乏第一性原理的约束。
 
-Progmune 提出**程序免疫学（Program Immunology）**范式，为生成式程序建立一套可识别、可记忆、可进化的防御体系。我们证明了，通过将程序的真实结构（IR）确立为唯一真相源，可以使 AI 生成的代码具备：
+Progmune 提出**程序免疫学（Program Immunology）**范式，为生成式程序建立一套可识别、可记忆、可进化的防御体系：
 
 1.  **天然免疫**：快速识别并拒绝违反符号存在性、类型兼容性和数据流规则的代码。
 2.  **获得性免疫**：从过去的失败案例中学习，生成特异性的防御规则，主动预防未来同类错误。
@@ -26,22 +41,47 @@ Progmune 提出**程序免疫学（Program Immunology）**范式，为生成式
 
 ## 架构概览：一个会学习、会记忆、会防御的运行时
 
-Progmune 的架构受生物免疫系统启发，分为六个核心层：
+Progmune 的架构受生物免疫系统启发，分为核心防御层：
 
 | 生物免疫系统 | 程序免疫 (Progmune) | 核心职责 |
-|-------------|---------------------|----------|
+|:-------------|:--------------------|:---------|
 | **天然免疫** | **约束引擎** (IR + SVL-1~SVL-3) | 快速、自动地拒绝调用不存在的函数、类型错误和数据流问题。 |
 | **获得性免疫** | **语义状态图 (SSG)** | 通过可编程的状态机，精确拦截非法业务逻辑跃迁（如“未认证即签发令牌”）。 |
-| **免疫记忆** | **三层记忆架构** | 工作记忆、情景记忆和语义记忆协同，让系统越用越聪明，相似意图可跳过LLM直接复用验证过的路径。 |
-| **抗原呈递** | **Failure Corpus** | 结构化的失败案例库，每一次拦截都转化为可分析的“错误指纹”，为系统进化提供数据基础。 |
+| **免疫记忆** | **三层记忆 + Failure Corpus** | 工作记忆、情景记忆和语义记忆协同；失败基因组记录每次语义异常、修复路径和适应轨迹。 |
+| **抗体生成** | **Antibody Registry** | **v2.1.0 新增**：从失败中自动挖掘修复模式，生成 ACL-1~4 置信度分级的免疫规则。 |
+| **免疫观测** | **Semantic Observatory** | 终端原生语义观测工具——时间线、认知回放、状态机追踪、基因组热力图。 |
+
+---
+
+## v2.1.0 新特性：抗体与快照
+
+在 v2.1.0 版本中，Progmune 实现了从“被动拦截”到“主动防御”的跨越：
+
+*   **抗体注册表 (Antibody Registry)**：系统自动从 `Failure Corpus` 中提取修复模式。高置信度（ACL-4）的抗体可触发“免疫快跑”，绕过 LLM 直接应用验证过的修复路径。
+*   **语义快照引擎 (Snapshot Engine)**：在规划时自动捕获 IR 状态。支持通过 `diff` 命令对比不同时间点的 IR 差异，解决因环境漂移导致的生成失败。
+*   **BFS 协议修复**：SSG 验证器现在使用广度优先搜索寻找多步修复路径，能够自动补全复杂的协议缺失（如 `INIT` -> `EMAIL_OK` -> `PWD_HASHED`）。
+
+---
+
+## 语义有效性级别 (SVL)
+
+Progmune 定义了 AI 生成代码正确性的分层标准：
+
+| 级别 | 名称 | 保证 |
+|:-----|:-----|:-----|
+| SVL-1 | 符号存在性 | 绝不调用项目中不存在的函数 |
+| SVL-2 | 类型有效性 | 参数数量和类型严格匹配 |
+| SVL-3 | 数据流正确性 | 变量先声明后使用，无循环引用 |
+| SVL-4 | 协议合法性 | 业务步骤顺序必须遵守状态迁移规则 |
 
 ---
 
 ## 快速开始
 
 ### 前置条件
-- [Node.js](https://nodejs.org/) >= 18
-- 一个有效的 LLM API 密钥（DeepSeek 或 OpenAI 兼容接口）
+
+*   [Node.js](https://nodejs.org/) >= 18
+*   一个有效的 LLM API 密钥（DeepSeek 或 OpenAI 兼容接口）
 
 ### 1. 安装
 
@@ -49,70 +89,84 @@ Progmune 的架构受生物免疫系统启发，分为六个核心层：
 npm install -g progmune-runtime
 ```
 
-### 2. 配置 LLM API 密钥
+### 2. 配置
+
 ```bash
-export LLM_API_KEY="你的DeepSeek或OpenAI密钥"
+npx progmune-runtime setup "你的API密钥"
 ```
 
-### 3. 在 MCP 客户端中配置
-**Claude Code**: 编辑 `~/.claude/settings.json` 并添加：
-
-```json
-{
-  "mcpServers": {
-    "progmune": {
-      "command": "npx",
-      "args": ["progmune-runtime"]
-    }
-  }
-}
+### 3. 验证
+
+```bash
+npx progmune-runtime test
 ```
 
-**Manus / 其他客户端**: Command: `npx`, Args: `progmune-runtime`。
+---
+
+## 许可证
+
+MIT License。
 
-配置完成后，在对话中直接描述编程需求，AI 代理会自动调用 Progmune 生成安全代码。
+Progmune 正在重新定义 AI 辅助编程——不是“让模型更聪明”，而是“让程序真相主导生成”。
 
 ---
 
-## 全球免疫网络 (Global Immune Network)
-Progmune 支持将本地脱敏后的错误指纹安全上报至中央免疫服务器，实现“群体免疫”。
+# Progmune Runtime
 
-**设置中央服务器地址**:
-```bash
-export PROGMUNE_HUB="https://progmune-runtime.fly.dev/report"
-```
+**Program Immunology: Constraint-Guided Program Synthesis Runtime**
 
-**预览待上报的脱敏数据**:
-```bash
-npx ts-node src/report.ts preview
-```
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
+[![Stage: Technical Preview](https://img.shields.io/badge/Stage-Technical_Preview-orange)]()
 
-**执行安全上报**:
-```bash
-npx ts-node src/report.ts report
-```
+Progmune is not an AI programming assistant, but an immune system for generative programs. It demotes LLMs from open-world code generators to heuristic searchers strictly constrained by the Program Truth Layer (IR).
+
+---
+
+## v2.1.0 New Features: Antibodies & Snapshots
 
-**隐私保护**: 只上传函数名序列、SVL级别、状态迁移，绝不包含任何代码片段、变量值或用户数据。
+v2.1.0 marks a major leap from "passive interception" to "active defense":
+
+*   **Antibody Registry**: Automatically extracts repair patterns from the `Failure Corpus`. High-confidence (ACL-4) antibodies trigger "Immune Fast-Path," bypassing the LLM to apply validated fixes directly.
+*   **Semantic Snapshot Engine**: Captures the exact IR state during planning. Supports `diff` commands to track IR evolution and debug environment drift.
+*   **BFS Protocol Repair**: The SSG validator now uses Breadth-First Search to find multi-hop repair paths, automatically filling complex protocol gaps.
 
 ---
 
-## 语义有效性级别 (SVL)
-Progmune 定义了 AI 生成代码正确性的分层标准：
+## Architecture Overview
 
-| 级别 | 名称 | 保证 |
-|---|---|---|
-| SVL-1 | 符号存在性 | 绝不调用项目中不存在的函数 |
-| SVL-2 | 类型有效性 | 参数数量和类型严格匹配 |
-| SVL-3 | 数据流正确性 | 变量先声明后使用，无循环引用 |
-| SVL-4 | 协议合法性 | 业务步骤顺序必须遵守状态迁移规则 |
+| Biological Immune System | Program Immunology (Progmune) | Core Responsibility |
+|:-------------------------|:------------------------------|:--------------------|
+| **Innate Immunity**      | **Constraint Engine** (IR + SVL-1~3) | Rejects non-existent functions, type errors, and dataflow issues. |
+| **Adaptive Immunity**    | **Semantic State Graph (SSG)** | Intercepts illegal business logic transitions (e.g., "issue token before auth"). |
+| **Immune Memory**        | **Three-Layer Memory**        | Working, episodic, and semantic memory collaborate to make the system smarter with use. |
+| **Antibody Generation**  | **Antibody Registry**         | **New in v2.1.0**: Mines repair patterns and generates ACL-1~4 graded immune rules. |
 
 ---
 
-## 如何贡献
-Progmune 的核心护城河在于不断积累的语义失败语料库。欢迎通过 GitHub Issues 提交您在使用过程中遇到的“看似合法但实际危险”的生成案例（请务必脱敏），帮助我们完善语义状态图（SSG）协议。
+## Semantic Validity Levels (SVL)
 
-## 许可证
-MIT License。
+| Level | Name                 | Guarantee                                      |
+|:------|:---------------------|:-----------------------------------------------|
+| SVL-1 | Symbolic Existence   | Never calls functions that do not exist in the project |
+| SVL-2 | Type Validity        | Parameter count and types strictly match       |
+| SVL-3 | Dataflow Correctness | Variables are declared before use, no circular references |
+| SVL-4 | Protocol Legality    | Business step order must adhere to state transition rules |
 
-Progmune 正在重新定义 AI 辅助编程——不是“让模型更聪明”，而是“让程序真相主导生成”。
-加入我们的技术预览，一起构建可验证的 AI 编码未来。
+---
+
+## Quick Start
+
+```bash
+npm install -g progmune-runtime
+npx progmune-runtime setup "YOUR_API_KEY"
+npx progmune-runtime test
+```
+
+---
+
+## License
+
+MIT License.
+
+Progmune is redefining AI-assisted programming—not by "making models smarter," but by "letting program truth govern generation."

package/demo-project/auth.ts

@@ -0,0 +1,55 @@
+/**
+ * Demo 项目: 用户认证系统
+ * 用于展示 SSG (Semantic State Graph) 协议验证
+ *
+ * 每个函数通过 JSDoc @protocol 注解声明其状态转换规则。
+ * 这些注解在 IR 提取时被解析，驱动 SSG 状态机。
+ */
+
+/**
+ * 验证用户密码
+ * @protocol pre_states=["UNAUTHENTICATED"] post_states=["PASSWORD_VERIFIED"]
+ */
+export function verify_password(username: string, password: string): boolean {
+  return password === "correct";
+}
+
+/**
+ * 签发 JWT 令牌
+ * @protocol pre_states=["PASSWORD_VERIFIED"] post_states=["TOKEN_ISSUED"] invalidate=["PASSWORD_VERIFIED"]
+ */
+export function generate_jwt(userId: string, expiresIn: number): string {
+  return "eyJhbGciOi...";
+}
+
+/**
+ * 创建用户会话
+ * @protocol pre_states=["TOKEN_ISSUED"] post_states=["SESSION_ACTIVE"] invalidate=["TOKEN_ISSUED"]
+ */
+export function create_session(token: string): { sessionId: string } {
+  return { sessionId: "sess_abc123" };
+}
+
+/**
+ * 撤销令牌
+ * @protocol pre_states=["TOKEN_ISSUED"] post_states=["UNAUTHENTICATED"] invalidate=["TOKEN_ISSUED"]
+ */
+export function revoke_token(token: string): void {
+  // 将 token 加入黑名单
+}
+
+/**
+ * 登出
+ * @protocol pre_states=["SESSION_ACTIVE"] post_states=["UNAUTHENTICATED"] invalidate=["SESSION_ACTIVE"]
+ */
+export function logout(sessionId: string): void {
+  // 销毁会话
+}
+
+/**
+ * 获取用户资料（无协议约束）
+ * @protocol pre_states=[] post_states=[]
+ */
+export function get_user_profile(userId: string): { name: string; email: string } {
+  return { name: "Alice", email: "alice@example.com" };
+}

package/demo-project/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "strict": true
+  },
+  "include": ["*.ts"]
+}

package/dist/ab-stats.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+// @progmune-generated session=sess_1780345600422_aexmh timestamp=2026-06-01T20:26:42.334Z ruleHash=9dec68bc2995e92a
+// Generated with IR constraint: 384 functions, 17 protocol rules
+const failure_corpus_1 = require("./failure-corpus");
+function main() {
+    const stats = (0, failure_corpus_1.getAntibodyStats)();
+    return stats;
+}
+main();

package/dist/acl-breakdown.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+// @progmune-generated session=sess_1780343994721_xgc40 timestamp=2026-06-01T19:59:59.184Z ruleHash=9dec68bc2995e92a
+// Generated with IR constraint: 400 functions, 17 protocol rules
+const failure_corpus_1 = require("./failure-corpus");
+const semantic_trace_1 = require("./semantic-trace");
+function main() {
+    const stats = (0, failure_corpus_1.getAntibodyStats)();
+    const formatted = (0, semantic_trace_1.formatAntibodyStats)();
+    return formatted;
+}
+main();

package/dist/action-runtime.js

@@ -51,6 +51,7 @@ class ActionBuilder {
     }
 }
 let currentVars = {};
+/** @requires ACTION_CODE @produces ACTION_RESULT */
 function executeActionCode(code) {
     const root = new ActionBuilder();
     currentVars = {};

package/dist/all-sessions.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+// @progmune-generated session=sess_1780343397192_jd8hw timestamp=2026-06-01T19:49:58.982Z ruleHash=9dec68bc2995e92a
+// Generated with IR constraint: 383 functions, 17 protocol rules
+const failure_corpus_1 = require("./failure-corpus");
+function main() {
+    const sessions = (0, failure_corpus_1.getAllSessions)();
+    return sessions;
+}
+main();