stop all work on text regex, ngra text regex is now frozen

2026-09-15 18:06:52 +08:00
parent 57587bec16
commit e04adf594a
33 changed files with 1008 additions and 49 deletions
@@ -0,0 +1,916 @@
+# NGRA 转型计划
+
+> 面向本地 Codex / 项目维护者的快速架构说明  
+> 项目：Nitload General Regular Analyzer（NGRA）
+
+## 1. 转型结论
+
+NGRA 不再以“高性能字符串正则表达式引擎”为主要目标。
+
+原先围绕 `Span<char>`、专用字符串匹配、复杂回溯、Source Generator 等方向继续投入的收益已经明显下降。后续核心工作转向：
+
+1. 以 **ε-NFA / NFA** 为基础执行模型；
+2. 将输入从 `char` 推广为任意可比较、可判定类别的序列元素；
+3. 面向 Token Stream、语法前端、半上下文模式分析等场景；
+4. 支持自动机归并、分层自动机、状态/断言/前序引用；
+5. 在此基础上继续研究 **Weighted Automaton / NGRA-Tensor**。
+
+因此，Text Regex 从“主架构”降级为“兼容前端 / 参考实现 / 测试子系统”。
+
+---
+
+## 2. 当前代码处理原则
+
+### 2.1 保留现有 Text Regex 半成品
+
+当前 Text Regex Source Generator、COUNT/CONCAT/ALT lowering、生成式 matcher 等代码不删除。
+
+原因：
+
+- 五角星 AST 模型仍然是有效成果；
+- AST 搜索、规范化、旋转、合并等代码仍可复用；
+- 当前实现记录了 COUNT continuation、group boundary、rollback 等真实工程问题；
+- 可作为未来自动机 IR 与旧实现行为的对照；
+- 删除会丢失大量探索成果。
+
+建议：
+
+- 将旧生成器移动到 `Legacy` / `Experimental` / `Archive` 目录；
+- 通过 `.csproj` 的 `Compile Remove` 或独立非构建项目，使其暂时不参与主编译；
+- 不再优先修补完整 `.NET Regex` 兼容性。
+
+### 2.2 五角星 AST 继续保留
+
+现有节点关系：
+
+```text
+          Parent
+            ↑
+Previous ← Node → Next
+          ↙    ↘
+       Left    Right
+```
+
+继续作为通用语法树 / 结构树基础设施。
+
+需要坚持：
+
+- AST 用于表达语法和结构；
+- 自动机 / CFG / Relation Graph 用于表达执行与传播；
+- 不再要求 AST 本身承担全部 backtracking / continuation 语义。
+
+---
+
+## 3. 新主线：ε-NFA
+
+第一阶段优先实现一个简单、正确、无性能野心的 ε-NFA 模拟器。
+
+### 3.1 基础状态模型
+
+```text
+Current Active States
+        ↓
+ε-closure
+        ↓
+consume(input)
+        ↓
+Next Active States
+        ↓
+ε-closure
+```
+
+核心状态：
+
+```text
+State
+Transition
+StartState
+AcceptStates
+ActiveStateSet
+```
+
+Transition 分为：
+
+```text
+ε transition
+matched transition
+```
+
+输入类型不能写死为 `char`。
+
+建议：
+
+```csharp
+EpsilonNfa<TInput>
+```
+
+或：
+
+```csharp
+EpsilonNfa<TScalar>
+```
+
+匹配条件可以抽象为：
+
+```csharp
+bool Match(in TInput input)
+```
+
+或者后续升级为更明确的 Predicate / Category Matcher。
+
+### 3.2 第一阶段支持的 Pattern
+
+第一版只要求：
+
+```text
+literal / predicate
+concat
+alternation
+*
+
+?
+{m,n}
+ordinary grouping
+```
+
+暂不追求：
+
+```text
+capture rollback
+复杂 greedy / lazy 行为
+lookaround
+backreference
+完整 .NET Regex compatibility
+```
+
+其中 `{m,n}` 可以优先在构造期展开为 NFA 结构，而不是运行时维护复杂 COUNT 控制流。
+
+---
+
+## 4. 为什么以 NFA 为主，而不是 DFA
+
+DFA 仍然有价值，但不再是必须经过的阶段。
+
+核心路线：
+
+```text
+Pattern
+  ↓
+ε-NFA
+  ↓
+NFA execution
+  ↓
+Weighted NFA
+  ↓
+NGRA-Tensor
+```
+
+DFA 只作为可选 specialization：
+
+```text
+Boolean
+Static
+No dynamic relation
+No weighted state
+```
+
+满足这些条件的局部子图，可以由编译器确定化为 DFA fast path。
+
+总体原则：
+
+> NFA 是主语义模型，DFA 是可选优化后端。
+
+原因：
+
+普通 NFA 的活动状态：
+
+```text
+a_i ∈ {0,1}
+```
+
+加权机可自然推广为：
+
+```text
+a_i ∈ R
+```
+
+Tensor 版本可以继续推广为：
+
+```text
+a_i ∈ R^d
+```
+
+多状态同时活跃不再是需要“消除的非确定性”，而会成为模型本身的状态表示。
+
+---
+
+## 5. NGRA 的目标：广义序列分析
+
+NGRA 不再局限于字符串。
+
+典型输入：
+
+```text
+char
+token
+syntax node
+semantic node
+sensor frame
+event
+instruction-like object
+```
+
+Pattern 的作用也从：
+
+```text
+“这个字符串是不是符合 regex”
+```
+
+扩展为：
+
+```text
+“这个序列在当前状态、历史、类别和上下文条件下，
+是否满足某个结构化模式”
+```
+
+---
+
+## 6. 半上下文 Token Analyzer
+
+NGRA 的近期目标之一，是成为一种介于普通 Regex 与完整 Parser 之间的 Token Stream Analyzer。
+
+可用能力包括：
+
+```text
+Token 类别匹配
+Token 属性匹配
+前序状态引用
+局部断言
+Pattern 状态
+符号绑定
+分层子自动机
+局部上下文
+```
+
+因此它适合作为：
+
+```text
+Lexer 后端
+Token Regex
+语法前端
+编译器预分析器
+DSL Parser Frontend
+结构化流分析器
+```
+
+“半上下文”的含义不是严格的形式语言分类，而是：
+
+> Pattern 不只依赖当前 token，也可以依赖有限的已知状态、绑定、前序结果和结构信息，但不要求一开始就构造完整通用 Parser。
+
+---
+
+## 7. 自动机归并
+
+大量 Pattern 应优先在 NFA 层归并，而不是各自独立执行。
+
+例如：
+
+```text
+             ε → Pattern A
+            /
+GlobalStart ─ε → Pattern B
+            \
+             ε → Pattern C
+```
+
+Accepting State 可以附带：
+
+```text
+PatternId
+MatchKind
+Payload
+```
+
+后续目标：
+
+- 合并公共路径；
+- 消除冗余 ε 边；
+- 状态压缩；
+- bitset active state；
+- pattern priority；
+- 多层自动机组合。
+
+---
+
+## 8. 分层自动机
+
+后续重点不是继续增加字符串 Regex 特性，而是建立分层自动机。
+
+示意：
+
+```text
+Scalar / Token Layer
+        ↓
+Local Pattern Layer
+        ↓
+Phrase / Region Layer
+        ↓
+Sentence / Structure Layer
+        ↓
+Semantic / Relation Layer
+```
+
+低层自动机可以生成高层节点，高层节点继续作为新序列输入。
+
+即：
+
+```text
+Input Stream
+   ↓
+Automaton L0
+   ↓
+Derived Nodes
+   ↓
+Automaton L1
+   ↓
+Higher-level Nodes
+```
+
+这应成为 NGRA 进入编译器前端、自然语言结构分析和复杂流分析的主路径。
+
+---
+
+## 9. Assertion / Context 的重新定义
+
+不再围绕字符串 Regex 的 lookahead / lookbehind 设计核心架构。
+
+通用定义应更接近：
+
+```text
+Assert(Context) -> bool
+```
+
+或者：
+
+```text
+RelationGate(State, Context, History) -> bool
+```
+
+因此：
+
+- 字符串前瞻/后顾只是特殊情况；
+- 前序引用只是状态引用的一种；
+- group/capture 不是核心抽象；
+- Context / Binding / Region / History 才是可推广概念。
+
+---
+
+# NGRA-Tensor 构想
+
+## 10. 基本方向
+
+NGRA-Tensor 不是简单地“给 NFA 边加 float”。
+
+它希望把：
+
+```text
+Boolean multi-state automaton
+```
+
+推广为：
+
+```text
+Weighted / Tensor Relation Network
+```
+
+基础演化：
+
+```text
+NFA
+a_i ∈ {0,1}
+
+↓ weighted
+
+Weighted Automaton
+a_i ∈ R
+
+↓ tensor/state
+
+NGRA-Tensor
+a_i ∈ R^d
+```
+
+---
+
+## 11. Relation 成为一等对象
+
+不再采用固定 `Port4` 作为核心语义。
+
+推荐模型：
+
+```text
+Source Node
+    ↓
+[ Relation ]
+    ↓
+Destination Node
+```
+
+Relation 包含：
+
+```text
+Source
+Destination
+Type
+Parameters
+Weight / Weight Function
+Optional State
+Eligibility / Gate
+```
+
+语义上：
+
+```text
+Relation:
+决定一条联系是否生效，
+以及它如何把 Source 信息贡献给 Destination。
+```
+
+Node 负责保存状态。
+
+Blend 负责汇合多条 Relation 的贡献。
+
+---
+
+## 12. Pull，而不是主动广播
+
+GPU / 执行层优先采用 destination pull：
+
+```text
+Destination Node
+    ↓
+请求自己依赖的 Relations
+    ↓
+读取 Source states
+    ↓
+Relation Eval
+    ↓
+Blend
+```
+
+而不是：
+
+```text
+Source Node
+    ↓
+主动向大量 Destination 广播
+```
+
+优点：
+
+- 减少 scatter；
+- 减少原子写冲突；
+- 减少 readiness 管理；
+- 更适合 GPU destination-centric execution。
+
+---
+
+## 13. Relation 的三段语义
+
+推荐拆成：
+
+```text
+Eligibility
+    ↓
+Compatibility
+    ↓
+Transfer
+```
+
+即：
+
+1. **Eligibility**：这条 Relation 当前能不能参与；
+2. **Compatibility**：参与后有多重要；
+3. **Transfer**：真正传递什么信息。
+
+形式上：
+
+```text
+gate_ij = G(state, context, relation)
+score_ij = F(query, key, relation)
+value_ij = T(source_state, relation)
+```
+
+最终：
+
+```text
+output_i = Blend(gate_ij * weight_ij * value_ij)
+```
+
+---
+
+## 14. 与 Attention / QKV 的关系
+
+QKV 可以作为 Relation 内部算子的第一种 baseline，但不应决定 NGRA-Tensor 的外层拓扑。
+
+标准 Attention：
+
+```text
+Q = “我需要什么”
+K = “我适不适合被引用”
+V = “真正传递的内容”
+```
+
+数学上：
+
+```text
+score_ij = q_i · k_j
+weight_ij = softmax(score_ij)
+output_i = Σ weight_ij * v_j
+```
+
+NGRA-Tensor 的差异：
+
+- Relation 是显式、长期存在、可带类型的；
+- 候选关系通常是稀疏的；
+- 不一定对全部 node 做 dense attention；
+- Relation 可以有自己的参数、状态、类型和 gate；
+- Attention 可以只是某种 Relation Eval backend。
+
+---
+
+## 15. 稀疏关系，而不是全连接爆破
+
+Transformer 的典型关系空间：
+
+```text
+L × L
+```
+
+NGRA-Tensor 的目标：
+
+```text
+E << N²
+```
+
+即只计算显式 Relation。
+
+但必须承认：
+
+- 稀疏图带来 gather；
+- 不规则访问会伤害 GPU；
+- 小算子过多会降低吞吐。
+
+因此不能简单逐 Relation 启动 kernel。
+
+---
+
+## 16. Relation Tile / 脑区式分块
+
+后续 GPU backend 应研究：
+
+```text
+Semantic Relation Graph
+        ↓
+Graph Partition
+        ↓
+Relation Tiles
+        ↓
+Block-sparse / Dense subgraph execution
+```
+
+目标：
+
+> 块内允许不规则访问，块间尽量转成规则张量传输。
+
+示意：
+
+```text
+Dense / semi-dense local region
+        ↓
+少量跨区 Relation
+        ↓
+another dense / semi-dense region
+```
+
+类似“脑区”：
+
+- 区内关系较密；
+- 区间关系较稀；
+- 每个区可以编译成中型 tensor operator；
+- 跨区使用显式 Relation。
+
+这可能成为 NGRA-Tensor 与传统 Transformer 之间的重要折中。
+
+---
+
+## 17. 语义稀疏 vs 物理稠密
+
+前端语义可以是：
+
+```text
+Sparse Relation Graph
+```
+
+GPU backend 可以通过：
+
+```text
+node reorder
+feature reorder
+relation reorder
+graph clustering
+block detection
+tile packing
+kernel fusion
+shared-memory staging
+```
+
+将其转为：
+
+```text
+Dense blocks
+
+Block-sparse blocks
+
+Irregular sparse tails
+```
+
+原则：
+
+> 模型的图结构不等于 GPU 必须逐边解释。
+
+---
+
+## 18. Node State 可以是高维 Tensor
+
+NGRA-Tensor 不等于“每个 Node 只有一个 scalar”。
+
+Node 可以持有：
+
+```text
+x_i = [f0, f1, ..., fN]
+```
+
+但 Relation 不一定读取全部 feature。
+
+因此可能存在两层稀疏：
+
+```text
+Topology sparsity
+Feature sparsity
+```
+
+Relation 可以只对特定 feature/subspace 感兴趣。
+
+例如：
+
+```text
+Relation A:
+Q features = [1, 2, 7]
+K features = [4, 8]
+V features = [16, 17, 18]
+```
+
+语义上只取这些 feature。
+
+物理执行时 GPU compiler 可以为了带宽一次读入更大的连续 block。
+
+---
+
+## 19. Tensor 观念
+
+后续 NGRA-Tensor 设计不要把 Tensor 只理解为“算子”。
+
+Tensor 可以同时是：
+
+```text
+状态
+参数
+关系
+mask
+中间结果
+数据集合
+算子
+```
+
+“算子”只是某个 Tensor 在某次 contraction 中扮演的角色。
+
+建议以“语义轴”理解 Tensor，例如：
+
+```text
+Node × Feature
+Destination × Source
+Relation × Feature
+Time × Node × Feature
+```
+
+优先思考：
+
+- 哪些轴保留；
+- 哪些轴被收缩；
+- 哪些轴表示关系；
+- 哪些轴表示 feature；
+- 哪些轴可以 sparse；
+- 哪些轴可以 dense。
+
+---
+
+## 20. 训练 / 运行时关系发现
+
+NGRA-Tensor 长期设想允许结构学习。
+
+训练阶段：
+
+```text
+短程强关系
+    ↓
+词 / Token 局部关系
+    ↓
+词组 / 短句
+    ↓
+长句 / 语义
+    ↓
+知识网络 / 长程弱关系
+```
+
+运行时：
+
+当现有网络：
+
+```text
+NoActivePath
+LowConfidence
+HighAmbiguity
+Unknown
+```
+
+可进入较慢的 Relation Discovery：
+
+```text
+Stable Graph
+    ↓
+Unknown
+    ↓
+Candidate Relation Search
+    ↓
+Candidate Graph
+    ↓
+验证
+    ↓
+可能固化进入 Stable Graph
+```
+
+不建议运行时每一步都修改主图。
+
+应区分：
+
+```text
+Fast inference time
+Slow structural learning time
+```
+
+---
+
+# 近期开发优先级
+
+## Phase 1 — ε-NFA Reference Runtime
+
+实现：
+
+```text
+EpsilonNfa<TInput>
+StateId
+Transition
+ε-closure
+Consume
+Accept
+```
+
+目标：
+
+- 语义简单；
+- 正确性优先；
+- 不做复杂性能优化；
+- 不绑定 `char`。
+
+## Phase 2 — Pattern → NFA Lowering
+
+从现有 AST / Pattern IR 构造 NFA：
+
+```text
+literal
+predicate
+concat
+alt
+repeat
+```
+
+## Phase 3 — NFA Merge
+
+实现：
+
+```text
+multi-pattern merge
+PatternId
+shared start
+accept payload
+```
+
+然后测试大量 Pattern 同时运行。
+
+## Phase 4 — Token Stream
+
+将输入切换到：
+
+```text
+Token
+```
+
+支持：
+
+```text
+Token kind
+Token value
+Token metadata
+simple binding
+context predicate
+```
+
+目标：作为编译器前端 / Token Regex 原型。
+
+## Phase 5 — Hierarchical Automata
+
+允许低层自动机输出高层节点，并再次进入更高层自动机。
+
+## Phase 6 — Weighted Automaton
+
+将：
+
+```text
+active : bool
+```
+
+推广为：
+
+```text
+activation : float
+```
+
+先不要急于引入复杂 Tensor。
+
+## Phase 7 — NGRA-Tensor Prototype
+
+研究：
+
+```text
+Node state tensor
+Typed Relation
+Eligibility
+Compatibility
+Transfer
+Blend
+Sparse / block-sparse execution
+```
+
+QKV/Attention 可作为 baseline Relation operator。
+
+---
+
+# 非目标
+
+近期不要优先投入：
+
+```text
+完整 .NET Regex 兼容
+极端 Span<char> 优化
+复杂 Source Generator matcher
+完整 capture rollback
+所有 lookaround/backreference
+为了 Regex 完整性设计核心 IR
+```
+
+这些功能如确实需要，可以：
+
+```text
+System.Text.RegularExpressions
+```
+
+作为字符串兼容层。
+
+这不是架构退让，而是目标调整。
+
+---
+
+# 一句话定位
+
+NGRA 的新定位：
+
+> **以 NFA 为基础的广义序列模式与分层自动机框架，并逐步推广到加权 Relation Network 与 NGRA-Tensor。**
+
+Text Regex：
+
+> 一个兼容前端 / 参考实现，不再定义 NGRA 的核心架构。
+
+NGRA-Tensor：
+
+> 把 Boolean NFA 的多状态传播推广为显式、稀疏、可加权、可训练、可分块执行的 Relation Network。