User-text candidate scheduling and Facts-driven refresh
用户文本候选调度与 Facts 驱动刷新
User text contains references owned by independent businesses. Recognition must follow original-text positions, resolve collisions deterministically, and reuse unaffected matching work when Facts change. The evaluator must expose its scheduling behavior to pure logic tests without depending on React, browser timing, or elapsed-time benchmarks.
English
Problem
User text contains references owned by independent businesses. Recognition must follow original-text positions, resolve collisions deterministically, and reuse unaffected matching work when Facts change. The evaluator must expose its scheduling behavior to pure logic tests without depending on React, browser timing, or elapsed-time benchmarks.
Decision
The composition is business registration, lazy candidate matching, a single reconciliation loop, readonly JSON nodes, and business-owned keyed renderers. Initialization and Facts refresh use the same algorithm; they differ only in which query caches remain valid.
Rule roles and original coordinates
Every rule provides an ID, finite order, and synchronous match(text, from, context). Each call returns its nearest eligible node with start >= from, or no candidate anywhere in the remaining original text. It returns one node, not all matches or a replacement document. The original string and UTF-16 offsets remain intact: a search cursor does not create a new word, line, or quoted-token boundary. Matching depends only on original text and Facts, not previously selected node payloads.
Each matcher resolves its own alternative spellings by earliest start and then its documented same-start choice; Session labels choose the longer match. A matcher cannot replace a consumed prefix with the remainder of an overlapping candidate. Each business owns its grammar, payload, and renderer; the generic evaluator has no Session, file, skill, or command branches.
There is one rule type and one candidate protocol. A candidate contains either a business node using the rule ID or a Text node preserving the original substring with an optional data.display. Text-producing rules compete by the same start, order, and stable ID as business rules. Order only breaks same-start ties; no rule gets precedence over an earlier position.
One reconciliation loop
The evaluator keeps original text, the previous successful segmentation, registered definitions, per-rule Facts reads, and query results. Nonempty text initially has one Text covering [0, text.length); empty text has no nodes. Initialization makes every rule invalid, including rules that read no Facts.
Each reconciliation starts its result cursor at zero. Every matcher obtains one candidate through the same cache-aware query operation. The evaluator selects the smallest candidate start, breaks same-start ties by ascending rule order and stable ID, emits the preceding raw Text gap, emits the winner, and advances the cursor to the winner's end. No candidate means the remaining raw text is emitted and recognition ends.
Only a consumed candidate or a candidate whose start is before the new cursor needs another query. A cached candidate beginning at or after the cursor remains eligible. A no-candidate result remains eligible as the cursor advances. All ranges are nonempty half-open original-text ranges; candidates cannot move the cursor backward or exceed the original string.
Previously accepted nodes are reusable output, not a complete list of possible matches: a losing candidate can become visible when an earlier winner disappears. The evaluator retains queries for this purpose instead of treating an old Text node or the absence of a business node as unconditional evidence of no match.
Query cache and traversal
A query record contains its original from offset and either the next candidate, no candidate, or a failure. If a query from q returned a candidate starting at s, its result is valid for any requested cursor c with q <= c <= s. A no-candidate result is valid for every c >= q. Neither result proves anything before q. A failed query is reusable only at the same requested offset while its dependencies remain valid.
During a reconciliation, each matcher has one active candidate. The evaluator also retains the sorted query records already produced for that matcher across reconciliations; it does not enumerate all possible matches eagerly. Forward cursors walk these records monotonically. Queries generated in newly exposed gaps are merged with retained records in source order, with one record per query offset. Unsearched intervals require matching rather than an invented negative result.
The result cursor and matcher search cursors are distinct. Starting result reconciliation at zero does not require unchanged matchers to scan from zero again: their recorded queries answer valid requests. Each matcher must implement a forward search rather than repeatedly materializing every match in the remaining text. Internal scans, candidate selection, and result comparison still have costs; the scheduling guarantees concern actual matcher calls, not a claim that arbitrary regular expressions are linear.
Actual Facts dependencies
context.read(key) returns the borrowed readonly value from the current Facts snapshot and records the read, including undefined. The reader is valid only during its owning synchronous call and cannot be retained. Businesses receive neither a whole Facts object, a manual dependsOn list, nor previous-output/cache objects.
A matcher's dependency set is the union of reads for the queries retained in its current cache generation, including losing candidates, no-match queries, and failed calls. Changed fields are detected with Object.is at field granularity. A new outer Facts object alone does not invalidate matching. When a rule is invalidated, its old queries and read set are discarded; subsequent calls establish the replacement read set, so obsolete conditional dependencies do not remain permanently attached.
Text-producing rules use the same query cache and dependency generation as every other rule. Updating a whitespace switch invalidates only its readers; it does not trigger an unconditional pass over the completed nodes.
Facts, text, and registration refresh
A Facts update invalidates only rules that read changed fields. Their first query starts at original offset zero; all other rules retain their query records. The same reconciliation loop then compares fresh candidates with reusable ones. Refreshing a rule does not give it priority, and a new first candidate does not hide the removal of an earlier old winner.
A fresh candidate confined to previously plain text can split that Text without invoking unrelated matchers whose cached queries still cover the new cursors. A fresh candidate that loses to an earlier unchanged winner is discarded without invalidating that winner. When a fresh winner covers another candidate, only expired heads advance. When a winner disappears or shrinks, cached losing candidates can compete again; any previously unsearched interval causes a query at the newly exposed cursor. All changes use the same cursor loop and query-coverage rules.
Several changed Facts fields form one snapshot and one invalidation set. All affected matchers participate in the same reconciliation; one update is not committed before processing the next. Equivalent refreshed results reuse previous nodes and, when all elements remain identical, the entire result array. Reconciliation settles the complete document before publishing its result.
Original-text changes discard all query caches and supply one full-range Text as the previous segmentation. New or replaced rule definitions start with empty caches; unchanged definitions retain their independent queries. Removed rules lose their dependencies and candidates. Reconciliation after additions, removals, or order changes uses the same selection logic and can expose formerly blocked candidates.
Output, ownership, and publication
Nodes retain { id, start, end, data }. Business nodes use their matcher's ID; Text retains the exact source substring in data.text and optional display text in data.display. Output is ordered, nonoverlapping, and completely covers the original text. JSON compatibility and readonly ownership are TypeScript obligations: the evaluator neither freezes borrowed objects nor deep-copies Facts or payloads for isolation.
The document evaluator owns all caches; the registry retains neither evaluators nor document subscriptions. Separate text instances do not share state through a global cache. Only fully successful evaluation publishes a new result. A matcher failure carries the rule ID and cause and publishes no partial segmentation; its actual reads remain available for dependency-driven retry. Reentrant evaluation and escaped synchronous read contexts are rejected.
conversation.user.text remains a session-scoped Factory owning conversation.user.text.node, a keyed inline Slot. React consumes final nodes and forwards raw and interactive to the business renderer. Session, skill, file/folder, and command matching remain owned by their respective plugins, and actions remain in each renderer's Injection. No matching work or cache subscription moves into React.
collapseWhitespace and trimWhitespace each control one ordinary matcher and default to off. Collapse offers whitespace runs as Text candidates with display " "; trim offers original leading/trailing whitespace runs with display "". Trim has lower order than collapse, so it wins their same-start edge collisions. An earlier reference candidate consumes its whole range and naturally excludes internal whitespace candidates. Every Text candidate retains its exact raw substring; emoji and spaces between references remain intact. interactive and CSS ellipsis remain React Props, not matching Facts. Queue uses full original text with CSS ellipsis; native attachments remain in their existing cards and image Slots, outside text recognition.
Verification requirements
Pure logic tests assert both the final nodes and each matcher's ordered calls with their from offsets. They use deterministic input and spies rather than clocks or performance thresholds.
- Initialization calls every matcher, including Facts-free and no-match rules; empty input has explicit terminal-query behavior.
- Earlier starts beat stronger order values; same-start ties use order and stable ID, and each matcher preserves its own longest-match choice.
- A future candidate and a no-match answer are not requested again during forward traversal; only the winner and overlapping heads advance.
- Unread Facts changes and new outer Facts objects with unchanged field values cause no matcher calls.
- One or several changed fields rerun exactly their readers; missing fields, losing candidates, no-match results, failures, and conditional read-set replacement remain covered.
- Equivalent refreshes preserve node/array identity and do not invoke unrelated matchers; payload-only changes preserve unaffected nodes.
- Insertions in plain text, losing new candidates, same-start winner changes, extending/shrinking matches, and removal of an early winner assert the exact affected query offsets and counts.
- Removing or shrinking a winner exposes cached losers and unsearched gaps; an old tail no-match result cannot answer a query before its recorded origin.
- Batched Facts updates equal a fresh evaluation under the same snapshot and do not give the first refreshed matcher precedence.
- Text and rule-definition changes, registration/disposal, range validation, synchronous failure containment, Context lifetime, and independent evaluator state have deterministic tests.
- Real Session/file/skill/command combinations preserve full quoted references, original word boundaries, and same-start precedence; whitespace candidates use exactly the same scheduling and cache rules.
Alternatives considered
Ordered whole-document business transforms. A business can consume later text before an earlier reference from another business is considered, so fixed type order does not express leftmost recognition.
Consequences
Field-level invalidation can require a matcher to traverse the document again; it does not promise per-element Facts invalidation. Query history consumes memory proportional to the distinct recorded search positions for the current text and definitions. Reconciliation and JSON identity alignment can still traverse output without invoking matchers. The performance evidence is the exact scheduling count and query offsets, while semantic evidence compares refreshed output with a fresh evaluator. This mechanism requires no browser end-to-end or elapsed-time benchmark tests.
中文
问题
用户文本包含独立业务拥有的引用。识别必须按原文位置推进，确定性地处理冲突，并在 Facts 变化时复用无关匹配工作。计算器必须能通过纯逻辑测试展示调度行为，不依赖 React、浏览器时序或耗时基准。
决策
采用业务注册、按需候选匹配、单一协调循环、只读 JSON 节点和业务拥有的 keyed renderer。初始化与 Facts 刷新使用同一个算法，只在查询缓存的有效性上存在差别。
规则职责与原始坐标
所有规则都提供 ID、有限的 order 和同步 match(text, from, context)。每次调用返回 start >= from 的最近有效节点，或确认剩余原文中没有候选。它返回一个节点，不返回全部匹配或整份替换文档。原始字符串及 UTF-16 坐标保持不变：搜索游标不创造新的词首、行首或带引号词元边界。匹配只依赖原文和 Facts，不依赖先前选中节点的 payload。
每个匹配器先按最早起点处理自身不同写法，再按该语法规定处理同起点选择；Session 标签选择较长匹配。匹配器不能把被消费前缀之后的半截重叠候选变成新匹配。语法、payload 和 renderer 均归对应业务所有，通用计算器不包含 Session、文件、skill 或命令分支。
只有一种规则类型和一个候选协议。候选既可以包含使用规则 ID 的业务节点，也可以包含保留原文子串、携带可选 data.display 的 Text 节点。产生 Text 的规则与业务规则按相同的起点、order 和稳定 ID 竞争。Order 仅裁定同起点冲突，任何规则都不优先于更早的位置。
单一协调循环
计算器保留原文、上一次成功分段、注册定义、逐规则 Facts 读取记录和查询结果。非空原文最初对应一个覆盖 [0, text.length) 的 Text，空原文没有节点。初始化使所有规则失效，包括不读取 Facts 的规则。
每次协调都从结果游标零开始，各匹配器通过同一个带缓存的查询操作获取一个候选。计算器选择起点最小的候选，同起点按规则 order 升序和稳定 ID 裁定，输出前面的原文 Text 空隙，输出赢家，再将游标推进到赢家末尾。全部没有候选时，输出剩余原文并结束识别。
只有被消费的候选或起点早于新游标的候选需要再次查询。缓存候选从新游标或其后开始时仍然有效；无候选结论在游标前进时保持有效。所有范围均是原文中的非空半开区间；候选不能使游标倒退或超出原文。
先前采纳的节点是可复用输出，不是所有可能匹配的完整清单；更早的赢家消失后，落败候选可能重新可见。计算器为此保留查询，而不能将旧 Text 节点或缺少某类业务节点无条件解释为没有匹配。
查询缓存与遍历
查询记录包含原始 from 偏移，以及下一个候选、无候选或失败。若从 q 查询得到起点为 s 的候选，则在请求游标 c 满足 q <= c <= s 时可以复用；无候选结论可用于所有 c >= q。两者都不能证明 q 之前的情况。失败查询只在请求偏移相同且依赖仍有效时复用。
一次协调过程中，每个匹配器只有一个活动候选。计算器同时保留该匹配器跨次协调已经产生的有序查询记录，不预先枚举所有可能匹配。前进游标单调遍历这些记录；新暴露空隙中的查询按原文顺序与旧记录合并，每个查询偏移只保留一条记录。未搜索区间必须执行匹配，不能虚构无匹配结论。
结果游标与匹配器搜索游标不同。结果协调从零开始，不代表无变化的匹配器需要从零重新扫描，它们的查询记录可以回答有效请求。各匹配器必须实现向前搜索，不能每次调用都重新收集剩余文本中的全部匹配。内部扫描、候选选择及结果比较仍有成本；调度保证针对实际匹配器调用，不宣称任意正则表达式都是线性的。
实际 Facts 依赖
context.read(key) 返回本次 Facts 快照中借用的只读值，并记录读取，包括 undefined。读取器仅在所属同步调用期间有效，不得保留。业务既不获得完整 Facts 对象，也不维护手工 dependsOn 列表或接收上一轮输出／缓存对象。
匹配器依赖集合是当前缓存代次所保留查询读取字段的并集，包括落败候选、无匹配查询和失败调用。字段变化按 Object.is 比较，外层 Facts 对象换引用不单独使匹配失效。规则失效时丢弃旧查询及读取集合，后续调用建立新的集合，因此已经不再读取的条件依赖不会永久残留。
产生 Text 的规则与其他规则共用查询缓存和依赖代次。空白开关更新只使它的读取者失效，不触发对已完成节点的无条件遍历。
Facts、原文与注册刷新
Facts 更新只使实际读取变化字段的规则失效。它们的首次查询从原文零开始，其他规则保留查询记录；随后由同一个协调循环比较新候选和可复用候选。规则刷新不赋予额外优先权，新首个候选也不能掩盖更早旧赢家的消失。
新候选完全位于原有普通文字内时，可以拆分该 Text；无关匹配器的缓存仍覆盖新游标时，不调用它们。新候选输给更早的有效旧赢家时，丢弃新候选，不使旧赢家失效。新赢家覆盖其他候选时，只推进过期的候选头。赢家消失或缩短时，缓存的落败候选可以重新竞争；此前未搜索的区间在新暴露游标处触发查询。所有变化都使用同一个游标循环和查询覆盖规则。
多个 Facts 字段变化形成同一份快照和一个失效集合，所有受影响匹配器共同参与一次协调，不先提交某个更新再处理另一个。刷新结果等价时复用旧节点，所有元素相同则复用整个结果数组。协调在整份文档确定后发布结果。
原文变化会丢弃全部查询缓存，并以覆盖全文的 Text 作为上一版分段。新增或替换的规则定义从空缓存开始，无变化定义保留各自独立查询。规则移除时删除其依赖和候选。新增、移除或顺序变化后的协调仍使用相同选择逻辑，并可暴露此前被遮挡的候选。
输出、所有权与发布
节点保留 { id, start, end, data }。业务节点使用所属匹配器 ID；Text 的 data.text 保留准确原文子串，data.display 可保存显示文字。输出有序、非重叠并完整覆盖原文。JSON 兼容性与只读所有权由 TypeScript 协议约束；计算器既不冻结借用对象，也不为隔离而深拷贝 Facts 或 payload。
文档计算器拥有全部缓存；注册表不持有计算器或文档订阅，不同文本实例不通过全局缓存共享状态。只有完整成功的求值才能发布新结果。匹配器失败时保留规则 ID 与 cause，不发布部分分段；实际读取仍参与依赖驱动的重试。禁止重入求值以及逃逸的同步读取 Context。
conversation.user.text 保持 session 作用域 Factory，拥有 keyed inline Slot conversation.user.text.node。React 消费最终节点，将 raw 和 interactive 交给业务 renderer。Session、skill、文件／目录和命令匹配仍归各插件所有，动作仍由各 renderer 的 Injection 提供，匹配与缓存订阅不进入 React。
collapseWhitespace 与 trimWhitespace 分别控制一个普通匹配器，缺省均关闭。Collapse 将空白串作为显示值为 " " 的 Text 候选；trim 将原文开头／末尾的空白串作为显示值为 "" 的候选。Trim 的 order 小于 collapse，因此在同起点的边缘空白冲突中胜出。更早的引用候选消费自身完整范围，自然排除内部空白候选。每个 Text 候选保留准确的原文子串，emoji 及引用之间的空格保持不变。interactive 和 CSS ellipsis 仍为 React Props，不是匹配 Facts。Queue 使用完整原文和 CSS 省略，原生附件保留既有卡片及图片 Slot，不进入文本识别。
验证要求
纯逻辑测试同时断言最终节点，以及每个匹配器有序的调用和 from 偏移。使用确定性输入与 spy，不依赖时钟或性能阈值。
- 初始化调用所有匹配器，包括不读 Facts 和始终无匹配的规则；空输入具有明确的终止查询行为。
- 较早起点胜过更强 order；同起点按 order 和稳定 ID 裁定，各匹配器保留自身最长匹配选择。
- 向前遍历不重复查询未来候选及无匹配结论，只推进赢家和重叠候选头。
- 未读取 Facts 字段变化，或字段值不变而外层 Facts 对象换引用，不调用匹配器。
- 一个或多个字段变化只重跑实际读取者；覆盖缺失字段、落败候选、无匹配结果、失败和条件依赖集合替换。
- 等价刷新保留节点／数组引用且不调用无关匹配器；仅 payload 变化保留无关节点。
- 普通文字中插入、落败的新候选、同起点换赢家、匹配扩张／缩短、较早赢家移除，均断言准确的受影响查询偏移与次数。
- 赢家移除或缩短后暴露缓存落败者及未搜索空隙；旧尾部的无匹配结论不能回答其查询起点之前的问题。
- 批量 Facts 更新等于相同快照下的新建计算器结果，不赋予先刷新匹配器额外优先权。
- 原文及规则定义变化、注册／注销、范围校验、同步失败隔离、Context 生命周期和计算器状态独立均有确定性测试。
- 真实 Session／文件／skill／命令组合保留完整带引号引用、原始词边界和同起点优先关系；空白候选使用完全相同的调度和缓存规则。
备选方案
按顺序处理整篇文档的业务变换。 某业务可能在另一业务更早的引用获得考虑前消费后面的文本，因此固定类型顺序不能表达最左优先识别。
影响
字段级失效仍可能要求某个匹配器重新遍历文档，不承诺 Facts 字段内部逐元素失效。查询历史的内存量与当前原文、定义下记录的不同搜索位置成正比。协调及 JSON 引用对齐可能遍历输出而不调用匹配器。性能证据是准确的调度次数和查询偏移，语义证据是刷新结果与全新计算器的等价性。本机制不需要浏览器端到端测试或耗时基准测试。