From dcd3d329d49bbbe179b55689197ede4ce5eec10f Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 23 Oct 2026 23:24:18 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20land=20S1=E2=80=93S6=20executable-knowl?= =?UTF-8?q?edge=20slices=20(NarrativeRef=20through=20CI)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comment-line NarrativeRef steps, generation CURRENT snapshots, frontmatter sources/applicability, digest-guarded artifact.patch, lock change classes, and an offline CI gate so the documented S0–S6 path has reviewable evidence. Co-authored-by: Cursor --- .github/workflows/executable-knowledge.yml | 22 ++ doc/README.md | 2 +- .../executable-knowledge-gaps-2026-10-23.md | 14 +- examples/executable-knowledge/README.md | 11 +- src/mlsp.rs | 155 ++++++++- src/parse/mod.rs | 5 +- src/parse/prose.rs | 187 ++++++++++- src/sema/ir.rs | 313 +++++++++++++++--- src/sema/lock.rs | 85 ++++- src/sema/mod.rs | 6 +- src/sema/provenance.rs | 251 ++++++++++++++ tests/executable_knowledge.rs | 261 +++++++++++++++ tests/executable_knowledge/README.md | 10 +- .../baseline/11-narrative-ref/main.mq.md | 25 ++ .../baseline/12-tax-source/corpus.md | 3 + .../baseline/12-tax-source/main.mq.md | 20 ++ .../baseline/12b-tax-expired/corpus.md | 3 + .../baseline/12b-tax-expired/main.mq.md | 18 + 18 files changed, 1314 insertions(+), 77 deletions(-) create mode 100644 .github/workflows/executable-knowledge.yml create mode 100644 src/sema/provenance.rs create mode 100644 tests/executable_knowledge/baseline/11-narrative-ref/main.mq.md create mode 100644 tests/executable_knowledge/baseline/12-tax-source/corpus.md create mode 100644 tests/executable_knowledge/baseline/12-tax-source/main.mq.md create mode 100644 tests/executable_knowledge/baseline/12b-tax-expired/corpus.md create mode 100644 tests/executable_knowledge/baseline/12b-tax-expired/main.mq.md diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml new file mode 100644 index 0000000..894ee89 --- /dev/null +++ b/.github/workflows/executable-knowledge.yml @@ -0,0 +1,22 @@ +name: executable-knowledge + +on: + push: + branches: [main] + pull_request: + +jobs: + gate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - name: Offline executable-knowledge gate + run: cargo test --test executable_knowledge --locked + - name: no ignored tests counted as success + run: | + if grep -n '#\[ignore\]' tests/executable_knowledge.rs; then + echo "executable_knowledge must not use #[ignore] as success evidence" >&2 + exit 1 + fi + echo "ok: no #[ignore] in executable_knowledge gate" diff --git a/doc/README.md b/doc/README.md index 65a8258..ae43a3d 100644 --- a/doc/README.md +++ b/doc/README.md @@ -15,7 +15,7 @@ > **可执行知识下一阶段的阅读顺序**:[原始意图 009](next/009.md) → [文档原生开发指导](design/document-native-development-guide.md)(作者体验、语法审查结论、AI 工作协议)→ [详细开发规范](next/Marqdo_Executable_Knowledge_Development.md)(目标语义与工程约束)→ [缺口与交付路线](roadmap/executable-knowledge-gaps-2026-10-23.md)(现状证据、S0–S6)。指导文档修订作者负担、场景政策和交付次序;不得把所有内部治理字段变成作者必填项。与之冲突的早期设计只作历史参考,设计目标不等于已实现能力。 > -> **S0 作者基线(已落地门禁)**:[tests/executable_knowledge/](../tests/executable_knowledge/README.md) — 六类写法 + `cargo test --test executable_knowledge --locked`。`status: design` / 预期失败与已实现分开报告;Bytecode 裸名同名误连记为基线缺陷,待 S2 BoundCall 翻转。 +> **可执行知识门禁**:[tests/executable_knowledge/](../tests/executable_knowledge/README.md) — S0–S2 BoundCall / 效应 / MLSP bind,以及后续 NarrativeRef、来源与整代投影子集;`cargo test --test executable_knowledge --locked`(CI:`.github/workflows/executable-knowledge.yml`)。`status: design` / 预期失败与已实现分开报告。 | 文档 | 摘要 | |------|------| diff --git a/doc/roadmap/executable-knowledge-gaps-2026-10-23.md b/doc/roadmap/executable-knowledge-gaps-2026-10-23.md index 6bae212..1e2aa81 100644 --- a/doc/roadmap/executable-knowledge-gaps-2026-10-23.md +++ b/doc/roadmap/executable-knowledge-gaps-2026-10-23.md @@ -187,13 +187,13 @@ P0/P1/P2 分类改为缺口领域,不再按编号整组串行:G06 的未知 | 切片 | 前置 | 作者 / AI 可见交付及工程关联 | 可复核的完成证据 | |---|---|---|---| -| S0 作者基线与最小语料 | 无 | 六类实际写作/复用任务、当前语法入口、无网络最小门禁(G10/G11) | **已落地**:[tests/executable_knowledge/](../../tests/executable_knowledge/README.md) + `cargo test --test executable_knowledge`;Bytecode 裸名同名误连记为基线缺陷待 S2/G02 | -| S1 可读步骤与唯一目标 | S0 | 一份文档的源码/步骤/view 联动;统一 resolver、图与上下文节点(G01/G03) | **已落地子集**:G01 双图分离;G03 步骤 kind + `steps.json` + view 导航;同名 import resolve;正文 NarrativeRef 仍待 | -| S2 确定执行与早期 AI 复用 | S1 | BoundCall 双后端、最小上下文卡、本地 handle 与现有 Agent 试点(G02/G06/G07/G09 的安全子集) | **已落地**:G02 共享 `resolve_for_exec` + Tree/Bytecode + `bound_calls.json`/`dynamic_calls.json`(`10-boundcall`);G06 效应;G07 MLSP bind/execute;eng_reuse `bind_required`/`bind_targets` | -| S3 局部编辑与库可读性 | S1–S2 | 摘要保护的局部补丁、语义 diff、受限纯表达式提取;lib/ext 示例优化(G03/G09/G10/G11) | 无无关改写;提取等价;声明变更可见;不为旧库增加兼容语法 | -| S4 业务知识与适用性 | S2;与 S3 可交错 | 书店契约、来源/验证事件、传递效应及政策、负知识(G05/G06/G07/G09) | 分清输入不适用、来源过期和测试失败;纯工具免虚构来源 | -| S5 变化传播与严格复用 | S1–S2/S4 | 分类摘要、SCC 闭包、整代快照、impact、严格 handle 复核(G04/G08) | 依赖/证据变化影响正确;文案不混同实现;故障注入无混代 | -| S6 生态验收与发布 | 按发布声明选择 S1–S5 范围 | 全仓兼容矩阵、可运行端到端示例、平台冒烟、作者/AI 指标(G10/G11/G12) | 发布声明逐条有证据;未支持路径明确;无 skipped 核心成功证据 | +| S0 作者基线与最小语料 | 无 | 六类实际写作/复用任务、当前语法入口、无网络最小门禁(G10/G11) | **已落地**:[tests/executable_knowledge/](../../tests/executable_knowledge/README.md) + `cargo test --test executable_knowledge` | +| S1 可读步骤与唯一目标 | S0 | 一份文档的源码/步骤/view 联动;统一 resolver、图与上下文节点(G01/G03) | **已落地**:G01 双图分离;G03 步骤 kind + NarrativeRef(`11-narrative-ref`)+ view 导航;同名 import resolve | +| S2 确定执行与早期 AI 复用 | S1 | BoundCall 双后端、最小上下文卡、本地 handle 与现有 Agent 试点(G02/G06/G07/G09 的安全子集) | **已落地**:G02 BoundCall;G06 效应;G07 MLSP bind/execute;eng_reuse `bind_required` | +| S3 局部编辑与库可读性 | S1–S2 | 摘要保护的局部补丁、语义 diff、受限纯表达式提取;lib/ext 示例优化(G03/G09/G10/G11) | **已落地子集**:MLSP `artifact.patch` + wording 回滚;纯表达式自动提取 / 全库润色仍待 | +| S4 业务知识与适用性 | S2;与 S3 可交错 | 书店契约、来源/验证事件、传递效应及政策、负知识(G05/G06/G07/G09) | **已落地子集**:`sources`/`valid_until` → sourced/expired;business bind;完整书店与负知识仍待 | +| S5 变化传播与严格复用 | S1–S2/S4 | 分类摘要、SCC 闭包、整代快照、impact、严格 handle 复核(G04/G08) | **已落地子集**:`generations/`+`CURRENT`;锁 `classes`;impact 含 narrates;SCC/闭包摘要仍待 | +| S6 生态验收与发布 | 按发布声明选择 S1–S5 范围 | 全仓兼容矩阵、可运行端到端示例、平台冒烟、作者/AI 指标(G10/G11/G12) | **已落地子集**:CI `executable-knowledge.yml`;完整矩阵/冒烟/G12 SLO 仍待 | 每切片完成时同时更新 [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)的实现状态、相关示例及本表;只改文档状态不算完成。S1/S2 先用**无 LLM、无网络、无插件**测试证明确定性协议,随即接现有 Agent 验证实际复用;不等所有治理工程结束。G10/G11 是每片持续门禁,100 单元语料逐片增长;G04 的并发一致性必须在开放并发消费前完成,不能因为列在 S5 就忽略前置风险。 diff --git a/examples/executable-knowledge/README.md b/examples/executable-knowledge/README.md index 5cce801..6595377 100644 --- a/examples/executable-knowledge/README.md +++ b/examples/executable-knowledge/README.md @@ -23,8 +23,15 @@ ``` 它们不是四种语法。`()` 中仍是原有的取元、算术、循环和调用;`[]` 让每一步同时可读、可查、 -可在图中定位。当前实现尚不能完整运行该目标形式(类函数、统一 `Named`、步骤图仍是设计目标), -但它给出了实际项目中应当写成什么样子。 +可在图中定位。 + +**运行状态(勿与设计态混淆)** + +| 子集 | 状态 | 证据 | +|---|---|---| +| 纯计算 / BoundCall / 步骤 kind / NarrativeRef | 门禁已覆盖 | `tests/executable_knowledge/` | +| 本目录完整订单链(类函数、证据闭环、impact→原文) | **设计态** | 仍作目标示例,不计入发布成功 | +| `knowledge/tax-2026.mq.md` 的 `sources:` | 编译可关联 corpus;`business` bind 需 `evidence=sourced` | 见 `baseline/12-tax-source` | ## 预期闭环 diff --git a/src/mlsp.rs b/src/mlsp.rs index bb4fba8..7e46ee1 100644 --- a/src/mlsp.rs +++ b/src/mlsp.rs @@ -64,13 +64,14 @@ fn dispatch(req: &Value) -> Result { Some("artifact.impact") => artifact_impact(¶ms), Some("artifact.bind") => artifact_bind(¶ms), Some("artifact.execute") => artifact_execute(¶ms), + Some("artifact.patch") => artifact_patch(¶ms), // `` M9: occlusion label search (two-tier vocabulary). Some("labels.search") => labels_search(¶ms), // `` M6: one-shot session summary (T1 staleness seen/fixed). Some("session.summary") => session_summary(), other => Err(err( "mlsp.unknown_method", - format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute"), + format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute / artifact.patch"), )), } } @@ -186,6 +187,19 @@ fn artifact_bind(params: &Value) -> Result { "effects": effects, })); } + if policy == "business" + && !matches!( + artifact.verification.evidence.as_str(), + "sourced" | "verified" + ) + { + return Err(json!({ + "code": "artifact.evidence_denied", + "message": "business 策略要求来源已关联;当前证据状态不足", + "policy": policy, + "evidence": artifact.verification.evidence, + })); + } let symbol_id = artifact .symbol_id .as_ref() @@ -198,10 +212,149 @@ fn artifact_bind(params: &Value) -> Result { "project": compilation.semantics.root, "policy": policy, "effects": effects, + "evidence": artifact.verification.evidence, "source": {"file": artifact.source.file, "line": artifact.source.line}, }})) } +/// Digest-guarded local patch (S3/G09). `intent: wording` refuses signature/effect drift. +fn artifact_patch(params: &Value) -> Result { + let compilation = semantic_project(params)?; + let query = params + .get("artifact_id") + .or_else(|| params.get("symbol_id")) + .and_then(Value::as_str) + .ok_or_else(|| err("mlsp.bad_request", "artifact.patch 需要 artifact_id 或 symbol_id"))?; + let candidates = artifact_query(&compilation.semantics, query); + if candidates.len() != 1 { + return Err(err( + if candidates.is_empty() { + "artifact.unresolved" + } else { + "artifact.ambiguous" + }, + format!("无法唯一修补 `{query}`"), + )); + } + let before = candidates[0]; + let expected = params + .get("expected_digest") + .and_then(Value::as_str) + .ok_or_else(|| { + err( + "mlsp.bad_request", + "artifact.patch 需要 expected_digest(hashes.implementation)", + ) + })?; + if expected != before.hashes.implementation.0 { + return Err(json!({ + "code": "artifact.digest_mismatch", + "message": "源码实现摘要已变化,拒绝覆盖", + "expected": expected, + "actual": before.hashes.implementation.0, + })); + } + let path = compilation.semantics.root.join(&before.source.file); + let original = std::fs::read_to_string(&path) + .map_err(|e| err("artifact.load", format!("读源失败: {e}")))?; + let edits_v = params + .get("edits") + .and_then(Value::as_array) + .ok_or_else(|| err("mlsp.bad_request", "artifact.patch 需要 edits"))?; + let mut edits = Vec::new(); + for e in edits_v { + let line = e + .get("line") + .and_then(Value::as_u64) + .ok_or_else(|| err("mlsp.bad_request", "edit.line 必填"))? as u32; + let kind = e.get("op").and_then(Value::as_str).unwrap_or("replace"); + match kind { + "replace" => { + let text = e + .get("text") + .and_then(Value::as_str) + .ok_or_else(|| err("mlsp.bad_request", "replace 需要 text"))? + .to_string(); + edits.push(crate::repair::Edit::Replace { line, text }); + } + "delete" => edits.push(crate::repair::Edit::Delete { line }), + "insert_before" => { + let text = e + .get("text") + .and_then(Value::as_str) + .unwrap_or("") + .to_string(); + edits.push(crate::repair::Edit::InsertBefore { line, text }); + } + other => { + return Err(err( + "mlsp.bad_request", + format!("未知 edit.op `{other}`"), + )) + } + } + } + let start = before.source.line; + let end = before.source.end_line.max(start); + let ranges = [(start, end.max(start + 40))]; + let patched = crate::repair::apply_edits(&original, &ranges, &edits).map_err(|o| { + json!({ + "code": "mlsp.repair_out_of_scope", + "message": "补丁超出制品源码范围", + "lines": o.lines, + "ranges": o.ranges, + }) + })?; + std::fs::write(&path, &patched) + .map_err(|e| err("artifact.write", format!("写源失败: {e}")))?; + let after_comp = semantic_project(params)?; + let after_cands = artifact_query(&after_comp.semantics, query); + if after_cands.len() != 1 { + // roll back + let _ = std::fs::write(&path, &original); + return Err(err( + "artifact.patch_ambiguous", + "补丁后制品无法唯一解析;已回滚", + )); + } + let after = after_cands[0]; + let signature_changed = before.hashes.interface.0 != after.hashes.interface.0; + let effects_changed = before.effects.values() != after.effects.values(); + let implementation_changed = + before.hashes.implementation.0 != after.hashes.implementation.0; + let intent = params.get("intent").and_then(Value::as_str).unwrap_or("edit"); + if intent == "wording" && (signature_changed || effects_changed) { + let _ = std::fs::write(&path, &original); + return Err(json!({ + "code": "artifact.wording_broke_contract", + "message": "intent=wording 但签名或效应已变;已回滚", + "signature_changed": signature_changed, + "effects_changed": effects_changed, + })); + } + Ok(json!({ + "schema_version": 1, + "artifact_id": after.artifact_id.0, + "symbol_id": after.symbol_id.as_ref().map(|id| id.as_str()), + "applied": true, + "diff": { + "signature_changed": signature_changed, + "effects_changed": effects_changed, + "implementation_changed": implementation_changed, + "before": { + "interface": before.hashes.interface.0, + "implementation": before.hashes.implementation.0, + "effects": before.effects.values(), + }, + "after": { + "interface": after.hashes.interface.0, + "implementation": after.hashes.implementation.0, + "effects": after.effects.values(), + }, + }, + })) +} + fn artifact_execute(params: &Value) -> Result { let handle = params.get("handle").ok_or_else(|| err("mlsp.bad_request", "artifact.execute 需要 artifact.bind 返回的 handle"))?; let artifact_id = handle.get("artifact_id").and_then(Value::as_str).ok_or_else(|| err("mlsp.bad_handle", "handle 缺少 artifact_id"))?; diff --git a/src/parse/mod.rs b/src/parse/mod.rs index 6f6ce0d..f304cea 100644 --- a/src/parse/mod.rs +++ b/src/parse/mod.rs @@ -7,7 +7,10 @@ pub use expr::{ parse_call_after_gt, parse_call_arg_value, parse_expr, parse_expr_prefer_var, parse_value_or_interp, }; -pub use prose::{scan_prose_line, ProseBit}; +pub use prose::{ + classify_narrative_target, scan_md_links_in_line, scan_narrative_links, scan_prose_line, + NarrativeLink, NarrativeLinkKind, ProseBit, +}; use anyhow::{bail, Result}; diff --git a/src/parse/prose.rs b/src/parse/prose.rs index 9684fd9..6c4e078 100644 --- a/src/parse/prose.rs +++ b/src/parse/prose.rs @@ -2,8 +2,11 @@ //! //! Soft Markdown emphasis that does not look like code/return is skipped (G2 — //! [code-as-docs-gaps.md](../../../doc/design/code-as-docs-gaps.md)). +//! +//! Comment-line Markdown links `[label](target)` are NarrativeRef / navigation +//! sites (G03); they are never executed. -use crate::lex::{matching_bold_close_inline, matching_italic_close_inline}; +use crate::lex::{matching_bold_close_inline, matching_italic_close_inline, LineKind}; pub use crate::lex::looks_like_bold_code; @@ -22,6 +25,162 @@ pub enum ProseBit { ItalicReturn { inner: String, at: usize }, } +/// Why a comment-line `[]()` is not an executable BoundCall (G03). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum NarrativeLinkKind { + /// In-project symbol / binding / `#anchor` — inert explanation. + Narrate, + /// URL or file path — navigation only; never fetched by compile/run. + Navigation, +} + +impl NarrativeLinkKind { + pub fn as_str(self) -> &'static str { + match self { + Self::Narrate => "narrate", + Self::Navigation => "navigation", + } + } +} + +/// One Markdown link found on a comment (narrative) line. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct NarrativeLink { + pub label: String, + pub target: String, + pub kind: NarrativeLinkKind, + /// 1-based source line. + pub line: u32, + pub at: usize, +} + +/// Classify a link target without parsing it as an expression. +pub fn classify_narrative_target(target: &str) -> NarrativeLinkKind { + let t = target.trim(); + if t.starts_with("http://") + || t.starts_with("https://") + || t.starts_with("mailto:") + || t.starts_with("//") + { + return NarrativeLinkKind::Navigation; + } + if t.contains('/') || t.ends_with(".md") || t.ends_with(".mq.md") || t.ends_with(".html") + { + return NarrativeLinkKind::Navigation; + } + NarrativeLinkKind::Narrate +} + +/// Scan whole-source comment lines for Markdown links; skip fences and code lines. +pub fn scan_narrative_links(source: &str) -> Vec { + let classified = crate::lex::classify_source(source); + let mut out = Vec::new(); + let mut in_fence = false; + for (i, cl) in classified.iter().enumerate() { + let line_no = (i + 1) as u32; + let trimmed = cl.text.trim(); + if trimmed.starts_with("```") { + in_fence = !in_fence; + continue; + } + if in_fence { + continue; + } + if cl.kind != LineKind::Comment { + continue; + } + out.extend(scan_md_links_in_line(&cl.text, line_no)); + } + out +} + +/// Scan one line for `[label](target)`, skipping `` `inline` `` spans. +pub fn scan_md_links_in_line(line: &str, line_no: u32) -> Vec { + let bytes = line.as_bytes(); + let mut i = 0usize; + let mut out = Vec::new(); + while i < bytes.len() { + if bytes[i] == b'`' { + if let Some(rel) = line[i + 1..].find('`') { + i = i + 1 + rel + 1; + continue; + } + i += 1; + continue; + } + if bytes[i] != b'[' { + i += 1; + continue; + } + let Some((label, target, next)) = parse_md_link(line, i) else { + i += 1; + continue; + }; + let kind = classify_narrative_target(&target); + out.push(NarrativeLink { + label, + target, + kind, + line: line_no, + at: i, + }); + i = next; + } + out +} + +fn parse_md_link(line: &str, start: usize) -> Option<(String, String, usize)> { + if !line[start..].starts_with('[') { + return None; + } + let mut depth = 0i32; + let mut label_end = None; + for (rel, ch) in line[start..].char_indices() { + match ch { + '[' => depth += 1, + ']' => { + depth -= 1; + if depth == 0 { + label_end = Some(start + rel); + break; + } + } + _ => {} + } + } + let label_end = label_end?; + let after = line.get(label_end + 1..)?; + if !after.starts_with('(') { + return None; + } + let mut depth = 0i32; + let mut target_end = None; + for (rel, ch) in after.char_indices() { + match ch { + '(' => depth += 1, + ')' => { + depth -= 1; + if depth == 0 { + target_end = Some(rel); + break; + } + } + _ => {} + } + } + let target_end = target_end?; + let label = line[start + 1..label_end].to_string(); + let target = after[1..target_end].trim().to_string(); + if label.is_empty() || target.is_empty() { + return None; + } + // Executable occlusion payloads look like calls (`foo(…)` / `a.b(…)`); those + // live on Code lines already. If a comment link target is expression-shaped + // with `(`, still treat as narrate/navigation by target class — do not eval. + let next = label_end + 1 + target_end + 1; + Some((label, target, next)) +} + /// Scan a narrative (or mixed) line for v0.3 inline bits, left to right. pub fn scan_prose_line(line: &str) -> Vec { let bytes = line.as_bytes(); @@ -255,4 +414,30 @@ mod tests { "glob-like ticks must not yield italic: {bits:?}" ); } + + #[test] + fn narrative_links_skip_fence_and_classify() { + let src = "---\nmarkup: occlusion\n---\n\n# main\n\n见[文档](https://example.com/a)与[总额](总额)。\n\n```\n[ignored](https://x.test)\n```\n\n行内跳过 `[not](x)` 标记。\n"; + let links = scan_narrative_links(src); + assert!( + links.iter().any(|l| { + l.kind == NarrativeLinkKind::Navigation && l.target.contains("example.com") + }), + "{links:?}" + ); + assert!( + links + .iter() + .any(|l| l.kind == NarrativeLinkKind::Narrate && l.target == "总额"), + "{links:?}" + ); + assert!( + !links.iter().any(|l| l.target.contains("x.test")), + "fenced link must not become a step: {links:?}" + ); + assert!( + !links.iter().any(|l| l.target == "x"), + "inline-code link must not become a step: {links:?}" + ); + } } diff --git a/src/sema/ir.rs b/src/sema/ir.rs index 10f4fe1..acdbe05 100644 --- a/src/sema/ir.rs +++ b/src/sema/ir.rs @@ -284,9 +284,21 @@ pub fn compile_project(options: &CompileOptions) -> Result { artifacts.push(module_artifact(&index, module_id, path, text)); let mut by_path = BTreeMap::new(); collect_functions(&module.functions, &mut Vec::new(), &mut by_path); + let narrative_links = crate::parse::scan_narrative_links(text); + let module_prov = super::provenance::parse_module_provenance(text); + let module_symbols: Vec<&SymbolDecl> = index + .symbols() + .iter() + .filter(|s| &s.module == module_id) + .collect(); for symbol in index.symbols().iter().filter(|s| &s.module == module_id) { let function = by_path.get(&symbol.declaration_path).expect("symbol collected from module"); - let (artifact, mut artifact_refs, mut artifact_steps, mut bounds, mut dynamics) = + let owned_links: Vec<_> = narrative_links + .iter() + .filter(|link| enclosing_symbol(&module_symbols, link.line).is_some_and(|s| s.id == symbol.id)) + .cloned() + .collect(); + let (artifact, mut artifact_refs, mut artifact_steps, mut bounds, mut dynamics, prov_diags) = artifact_for_function( &index, module_id, @@ -295,7 +307,16 @@ pub fn compile_project(options: &CompileOptions) -> Result { function, symbol, &local_by_name, + &owned_links, + &module_prov, ); + for diag in prov_diags { + diagnostics.push( + Diagnostic::new(Some(path), Span::new(1, 1), diag.message()) + .with_code(diag.code()) + .with_severity(Severity::Warning), + ); + } refs.append(&mut artifact_refs); steps.append(&mut artifact_steps); bound_calls.append(&mut bounds); @@ -391,6 +412,37 @@ fn attach_project_imports(files: &mut BTreeMap(symbols: &[&'a SymbolDecl], line: u32) -> Option<&'a SymbolDecl> { + symbols + .iter() + .copied() + .filter(|s| s.line <= line) + .max_by_key(|s| s.line) +} + +fn resolve_narrative_target( + index: &ProjectIndex, + module_id: &ModuleId, + local_by_name: &BTreeMap<(ModuleId, String), SymbolId>, + target: &str, +) -> Option { + let t = target.trim().trim_start_matches('#'); + if t.is_empty() { + return None; + } + if let Some(id) = local_by_name.get(&(module_id.clone(), t.to_string())) { + return Some(id.clone()); + } + // Path-like `bind.member` via display name suffix match within project. + index.symbols().iter().find_map(|s| { + if s.declaration_path.join(".") == t || s.name == t { + Some(s.id.clone()) + } else { + None + } + }) +} + fn artifact_for_function( index: &ProjectIndex, module_id: &ModuleId, @@ -399,12 +451,15 @@ fn artifact_for_function( function: &Function, symbol: &SymbolDecl, local_by_name: &BTreeMap<(ModuleId, String), SymbolId>, + narrative_links: &[crate::parse::NarrativeLink], + module_prov: &super::provenance::ModuleProvenance, ) -> ( SemanticArtifact, Vec, Vec, Vec, Vec, + Vec, ) { let calls = collect_call_sites(function); let mut effects = direct_effects(&calls); @@ -436,14 +491,16 @@ fn artifact_for_function( let named = collect_named_steps(function); let mut refs = Vec::new(); let mut steps = Vec::new(); - for (n, named) in named.iter().enumerate() { + let mut step_n = 0u32; + for named in named.iter() { + step_n += 1; let target = named.call.as_ref().and_then(|call| { match classify_call(index, module_id, ast_module, function, call, local_by_name) { CallClass::Bound { target, .. } => Some(target), _ => None, } }); - let ref_id = format!("{}#ref-{}", symbol.id.as_str(), n + 1); + let ref_id = format!("{}#ref-{}", symbol.id.as_str(), step_n); refs.push(KnowledgeRef { id: ref_id.clone(), label: named.label.clone(), @@ -461,7 +518,7 @@ fn artifact_for_function( .map(effects_for_call) .unwrap_or_else(EffectSet::pure); steps.push(KnowledgeStep { - id: ArtifactId(format!("{}#step-{}", symbol.id.as_str(), n + 1)), + id: ArtifactId(format!("{}#step-{}", symbol.id.as_str(), step_n)), reference: ref_id, kind: named.kind.clone(), calls: target.into_iter().collect(), @@ -469,24 +526,57 @@ fn artifact_for_function( source: source_location(index.root().path(), path, named.line, named.line), }); } + // G03 NarrativeRef: comment-line []() — never BoundCall, never effects. + for link in narrative_links { + step_n += 1; + let target = match link.kind { + crate::parse::NarrativeLinkKind::Narrate => { + resolve_narrative_target(index, module_id, local_by_name, &link.target) + } + crate::parse::NarrativeLinkKind::Navigation => None, + }; + let ref_id = format!("{}#ref-{}", symbol.id.as_str(), step_n); + refs.push(KnowledgeRef { + id: ref_id.clone(), + label: link.label.clone(), + context: "narrative".into(), + source: source_location(index.root().path(), path, link.line, link.line), + resolution: match link.kind { + crate::parse::NarrativeLinkKind::Navigation => "navigation".into(), + crate::parse::NarrativeLinkKind::Narrate if target.is_some() => "symbol".into(), + crate::parse::NarrativeLinkKind::Narrate => "unresolved".into(), + }, + target: target.clone(), + }); + steps.push(KnowledgeStep { + id: ArtifactId(format!("{}#step-{}", symbol.id.as_str(), step_n)), + reference: ref_id, + kind: link.kind.as_str().into(), + calls: target.into_iter().collect(), + effects: EffectSet::pure(), + source: source_location(index.root().path(), path, link.line, link.line), + }); + } if effects.0.is_empty() { effects = EffectSet::pure(); } let (signature, contract) = signature(function, symbol.callable, &effects); let interface = digest(signature_json(signature.as_ref())); let implementation = digest(format!("{:?}", function.body)); - let provenance = vec![SourceRef { + let mut provenance = vec![SourceRef { uri: rel_uri(index.root().path(), path), locator: Some(format!("L{}", function.span.line)), content_digest: Some(implementation.clone()), relation: "defines".into(), }]; + let resolved = super::provenance::resolve_provenance(path, module_prov); + provenance.extend(resolved.refs); let evidence = digest(contract_summary(&contract)); let kind = match symbol.kind { SymbolKind::Type => "type", SymbolKind::Function => "function", }.to_string(); - let artifact = semantic_artifact( + let mut artifact = semantic_artifact( ArtifactId(symbol.id.as_str().to_string()), Some(symbol.id.clone()), symbol.declaration_path.join("."), @@ -498,12 +588,20 @@ fn artifact_for_function( effects, dependencies, provenance, - "no explicit applicability constraints".into(), + resolved.applicability, interface, implementation, evidence, ); - (artifact, refs, steps, bound_calls, dynamic_calls) + artifact.verification.evidence = resolved.evidence_status; + ( + artifact, + refs, + steps, + bound_calls, + dynamic_calls, + resolved.diagnostics, + ) } enum CallClass { @@ -1009,57 +1107,166 @@ fn dynamic_call_json(call: &DynamicCall) -> Value { }) } -/// Atomically write the semantic portion of `.marqdo/`. A reader therefore -/// sees either the previous graph or the complete next graph, never a mix. +const SEMANTIC_NAMES: &[&str] = &[ + "project.json", + "symbols.json", + "refs.json", + "steps.json", + "bound_calls.json", + "dynamic_calls.json", + "artifacts", + "graph", + "verification", +]; + +/// Resolve the active semantic generation directory (G04). +/// Prefers `CURRENT` → `generations//`; falls back to `out_dir` itself. +pub fn semantic_generation_dir(out_dir: &Path) -> PathBuf { + let current = out_dir.join("CURRENT"); + if let Ok(id) = fs::read_to_string(¤t) { + let id = id.trim(); + if !id.is_empty() { + let gen = out_dir.join("generations").join(id); + if gen.join("project.json").is_file() { + return gen; + } + } + } + out_dir.to_path_buf() +} + +/// Atomically write the semantic portion of `.marqdo/` as a whole generation +/// (G04). Readers that open via [`semantic_generation_dir`] never see a mix. pub fn write_semantic_projections(out_dir: &Path, compilation: &Compilation) -> Result<()> { - let stage = out_dir.with_extension("tmp-sema"); - if stage.exists() { fs::remove_dir_all(&stage).with_context(|| format!("clear {}", stage.display()))?; } - fs::create_dir_all(stage.join("artifacts"))?; - fs::create_dir_all(stage.join("graph"))?; - fs::create_dir_all(stage.join("verification"))?; + fs::create_dir_all(out_dir).with_context(|| format!("create {}", out_dir.display()))?; + let build_id = { + let mut hasher = Sha256::new(); + hasher.update(compilation.semantics.project_id.as_bytes()); + for a in &compilation.semantics.artifacts { + hasher.update(a.hashes.artifact.0.as_bytes()); + } + hasher.update( + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap_or_default() + .as_nanos() + .to_le_bytes(), + ); + format!("{:x}", hasher.finalize())[..16].to_string() + }; + let gens = out_dir.join("generations"); + fs::create_dir_all(&gens)?; + let gen_dir = gens.join(&build_id); + if gen_dir.exists() { + fs::remove_dir_all(&gen_dir)?; + } + fs::create_dir_all(gen_dir.join("artifacts"))?; + fs::create_dir_all(gen_dir.join("graph"))?; + fs::create_dir_all(gen_dir.join("verification"))?; + write_generation_tree(&gen_dir, compilation)?; + + // Atomic generation pointer: only publish CURRENT after the tree is complete. + let current_tmp = out_dir.join("CURRENT.tmp"); + fs::write(¤t_tmp, format!("{build_id}\n")) + .with_context(|| format!("write {}", current_tmp.display()))?; + fs::rename(¤t_tmp, out_dir.join("CURRENT")) + .with_context(|| format!("publish CURRENT under {}", out_dir.display()))?; + + // Compatibility root: stage a full mirror, then swap names (best-effort for + // legacy readers that do not follow CURRENT). + let stage = out_dir.join(".tmp-sema-publish"); + if stage.exists() { + fs::remove_dir_all(&stage)?; + } + copy_dir_recursive(&gen_dir, &stage)?; + for name in SEMANTIC_NAMES { + let target = out_dir.join(name); + if target.exists() { + if target.is_dir() { + fs::remove_dir_all(&target)?; + } else { + fs::remove_file(&target)?; + } + } + fs::rename(stage.join(name), &target)?; + } + let _ = fs::remove_dir_all(&stage); + Ok(()) +} + +fn write_generation_tree(stage: &Path, compilation: &Compilation) -> Result<()> { let project = compilation.semantics.to_json(); - write_json(&stage.join("project.json"), &json!({"schema_version":SCHEMA_VERSION,"project":project["project"],"artifact_count":compilation.semantics.artifacts.len()}))?; + write_json( + &stage.join("project.json"), + &json!({ + "schema_version": SCHEMA_VERSION, + "project": project["project"], + "artifact_count": compilation.semantics.artifacts.len(), + "generation": stage.file_name().and_then(|s| s.to_str()), + }), + )?; write_json(&stage.join("symbols.json"), &json!({"schema_version":SCHEMA_VERSION,"symbols":compilation.index.symbols().iter().map(|s|json!({"id":s.id.as_str(),"module":s.module.as_str(),"kind":s.kind.as_str(),"callable":s.callable.map(|c|c.as_str()),"name":s.name,"declaration_path":s.declaration_path,"source":{"file":rel_uri(compilation.index.root().path(),&s.source),"line":s.line}})).collect::>() }))?; write_json(&stage.join("refs.json"), &json!({"schema_version":SCHEMA_VERSION,"refs":project["refs"]}))?; write_json(&stage.join("steps.json"), &json!({"schema_version":SCHEMA_VERSION,"steps":project["steps"]}))?; write_json(&stage.join("bound_calls.json"), &json!({"schema_version":SCHEMA_VERSION,"bound_calls":project["bound_calls"]}))?; write_json(&stage.join("dynamic_calls.json"), &json!({"schema_version":SCHEMA_VERSION,"dynamic_calls":project["dynamic_calls"]}))?; write_json(&stage.join("graph/nodes.json"), &json!({"schema_version":SCHEMA_VERSION,"nodes":project["artifacts"]}))?; - write_json(&stage.join("graph/edges.json"), &json!({"schema_version":SCHEMA_VERSION,"authority":"SemanticProject","edges":compilation.semantics.artifacts.iter().flat_map(|a|a.dependencies.iter().map(move |d|json!({"from":a.artifact_id.0,"to":d.0,"kind":"calls"}))).collect::>() }))?; - for artifact in &compilation.semantics.artifacts { - let name = hex_name(&artifact.artifact_id.0); - write_json(&stage.join("artifacts").join(format!("{name}.json")), &artifact_json(artifact))?; - write_json(&stage.join("verification").join(format!("{name}.json")), &artifact_json(artifact)["verification"])?; - } - const SEMANTIC_NAMES: &[&str] = &[ - "project.json", - "symbols.json", - "refs.json", - "steps.json", - "bound_calls.json", - "dynamic_calls.json", - "artifacts", - "graph", - "verification", - ]; - if out_dir.exists() { - for name in SEMANTIC_NAMES { - let target = out_dir.join(name); - if target.exists() { - if target.is_dir() { - fs::remove_dir_all(&target)?; - } else { - fs::remove_file(&target)?; - } + let mut edges: Vec = compilation + .semantics + .artifacts + .iter() + .flat_map(|a| { + a.dependencies.iter().map(move |d| { + json!({"from": a.artifact_id.0, "to": d.0, "kind": "calls"}) + }) + }) + .collect(); + for step in &compilation.semantics.steps { + if step.kind == "narrate" { + for target in &step.calls { + edges.push(json!({ + "from": step.id.0, + "to": target.as_str(), + "kind": "narrates", + })); } } - } else { - fs::create_dir_all(out_dir)?; } - for name in SEMANTIC_NAMES { - fs::rename(stage.join(name), out_dir.join(name))?; + write_json( + &stage.join("graph/edges.json"), + &json!({ + "schema_version": SCHEMA_VERSION, + "authority": "SemanticProject", + "edges": edges, + }), + )?; + for artifact in &compilation.semantics.artifacts { + let name = hex_name(&artifact.artifact_id.0); + write_json( + &stage.join("artifacts").join(format!("{name}.json")), + &artifact_json(artifact), + )?; + write_json( + &stage.join("verification").join(format!("{name}.json")), + &artifact_json(artifact)["verification"], + )?; + } + Ok(()) +} + +fn copy_dir_recursive(src: &Path, dst: &Path) -> Result<()> { + fs::create_dir_all(dst)?; + for ent in fs::read_dir(src).with_context(|| format!("read {}", src.display()))? { + let ent = ent?; + let from = ent.path(); + let to = dst.join(ent.file_name()); + if from.is_dir() { + copy_dir_recursive(&from, &to)?; + } else { + fs::copy(&from, &to) + .with_context(|| format!("copy {} → {}", from.display(), to.display()))?; + } } - fs::remove_dir_all(stage)?; Ok(()) } @@ -1103,25 +1310,29 @@ mod tests { let root = root(); fs::write( root.join("main.mq.md"), - r#"# main + r#"--- +markup: occlusion +--- ## save > fs.write_text path=out.txt text=ok - *1* ## wrap > save - *None* ## mystery > weird_plugin_thing x=1 - *None* + +# main + +> wrap +> print text=ok "#, ) .unwrap(); diff --git a/src/sema/lock.rs b/src/sema/lock.rs index 5d81bf2..53f82e9 100644 --- a/src/sema/lock.rs +++ b/src/sema/lock.rs @@ -15,6 +15,8 @@ pub struct LockReport { pub missing: Vec, pub changed: Vec, pub removed: Vec, + /// Per-artifact which digest class drifted (G08). + pub classes: Vec, } impl LockReport { @@ -29,6 +31,7 @@ impl LockReport { "missing": self.missing, "changed": self.changed, "removed": self.removed, + "classes": self.classes, }) } } @@ -63,21 +66,47 @@ pub fn check_links_lock(out_dir: &Path, project: &SemanticProject) -> Result report.missing.push(id.clone()), - Some(found) if found.get("artifact").and_then(Value::as_str) != Some(digest.as_str()) => report.changed.push(id.clone()), - _ => {} + Some(found) => { + let mut drifted = Vec::new(); + for key in ["interface", "implementation", "evidence", "artifact"] { + let want = entry.get(key).and_then(Value::as_str); + let got = found.get(key).and_then(Value::as_str); + if want != got { + drifted.push(key.to_string()); + } + } + if !drifted.is_empty() { + report.changed.push(id.clone()); + report.classes.push(json!({ + "artifact_id": id, + "changed": drifted, + })); + } + } } } for id in actual.keys() { - if !expected.contains_key(id) { report.removed.push(id.clone()); } + if !expected.contains_key(id) { + report.removed.push(id.clone()); + } } - report.missing.sort(); report.changed.sort(); report.removed.sort(); - report.status = if report.missing.is_empty() && report.changed.is_empty() && report.removed.is_empty() { "clean".into() } else { "outdated".into() }; + report.missing.sort(); + report.changed.sort(); + report.removed.sort(); + report.status = if report.missing.is_empty() + && report.changed.is_empty() + && report.removed.is_empty() + { + "clean".into() + } else { + "outdated".into() + }; Ok(report) } @@ -98,7 +127,29 @@ pub fn impact(project: &SemanticProject, query: &str) -> Value { let mut reverse: BTreeMap> = BTreeMap::new(); for artifact in &project.artifacts { for dependency in &artifact.dependencies { - reverse.entry(dependency.0.clone()).or_default().push(artifact.artifact_id.0.clone()); + reverse + .entry(dependency.0.clone()) + .or_default() + .push(artifact.artifact_id.0.clone()); + } + } + // NarrativeRef edges: step → symbol; impact includes the step's owning artifact. + for step in &project.steps { + if step.kind != "narrate" { + continue; + } + let owner = step + .id + .0 + .split("#step-") + .next() + .unwrap_or(step.id.0.as_str()) + .to_string(); + for target in &step.calls { + reverse + .entry(target.as_str().to_string()) + .or_default() + .push(owner.clone()); } } let mut queue: VecDeque = seeds.iter().cloned().collect(); @@ -119,8 +170,22 @@ pub fn impact(project: &SemanticProject, query: &str) -> Value { json!({"schema_version":SCHEMA_VERSION,"query":query,"resolved":!seeds.is_empty(),"seeds":seeds,"affected":entries}) } -fn artifact_lock_map(project: &SemanticProject) -> BTreeMap { - project.artifacts.iter().map(|artifact| (artifact.artifact_id.0.clone(), artifact.hashes.artifact.0.clone())).collect() +fn artifact_lock_entries(project: &SemanticProject) -> BTreeMap { + project + .artifacts + .iter() + .map(|artifact| { + ( + artifact.artifact_id.0.clone(), + json!({ + "interface": artifact.hashes.interface.0, + "implementation": artifact.hashes.implementation.0, + "evidence": artifact.hashes.evidence.0, + "artifact": artifact.hashes.artifact.0, + }), + ) + }) + .collect() } fn lock_json(project: &SemanticProject) -> Value { diff --git a/src/sema/mod.rs b/src/sema/mod.rs index 876d6c7..6ea1be5 100644 --- a/src/sema/mod.rs +++ b/src/sema/mod.rs @@ -7,14 +7,16 @@ pub mod bind; pub mod ir; pub mod lock; +pub mod provenance; pub mod symbols; pub use bind::{ call_display, is_static_bound, lookup_local, resolve_for_exec, DynamicReason, ExecTarget, }; pub use ir::{ - artifact_json, compile_project, write_semantic_projections, ArtifactId, BoundCall, CompileOptions, - Compilation, Digest, DynamicCall, EffectSet, LockMode, SemanticArtifact, SemanticProject, + artifact_json, compile_project, semantic_generation_dir, write_semantic_projections, ArtifactId, + BoundCall, CompileOptions, Compilation, Digest, DynamicCall, EffectSet, LockMode, + SemanticArtifact, SemanticProject, }; pub use lock::{check_links_lock, impact as semantic_impact, update_links_lock, LockReport}; pub use symbols::{CallableKind, ModuleId, ProjectIndex, SymbolDecl, SymbolId, SymbolKind}; diff --git a/src/sema/provenance.rs b/src/sema/provenance.rs new file mode 100644 index 0000000..e5edd70 --- /dev/null +++ b/src/sema/provenance.rs @@ -0,0 +1,251 @@ +//! Optional source / applicability facts from module frontmatter (G05). +//! +//! Authors declare `sources:` and optional `applicability:` / `valid_until` in +//! frontmatter. Absence means a pure tool may still run but must stay +//! `evidence=unverified` — never invent a business SourceRef. + +use std::fs; +use std::path::{Path, PathBuf}; + +use sha2::{Digest as _, Sha256}; + +use super::ir::{Digest, SourceRef}; + +#[derive(Debug, Clone, Default)] +pub struct ModuleProvenance { + /// Relative corpus paths, optional `#anchor`. + pub sources: Vec, + pub valid_until: Option, + pub region: Option, +} + +/// Scan YAML-ish frontmatter for sources / applicability (no full YAML parser). +pub fn parse_module_provenance(source: &str) -> ModuleProvenance { + let mut lines = source.lines(); + if lines.next().map(|l| l.trim_end()) != Some("---") { + return ModuleProvenance::default(); + } + let mut out = ModuleProvenance::default(); + let mut in_sources = false; + let mut in_applicability = false; + for line in lines { + let t = line.trim_end(); + if t.trim() == "---" { + break; + } + let trimmed = t.trim(); + if trimmed.is_empty() { + continue; + } + if !line.starts_with(' ') && !line.starts_with('\t') { + in_sources = false; + in_applicability = false; + } + if trimmed == "sources:" || trimmed.starts_with("sources:") { + in_sources = true; + in_applicability = false; + if let Some(rest) = trimmed.strip_prefix("sources:") { + let rest = rest.trim(); + if !rest.is_empty() && rest != "|" { + // inline list not used; ignore + } + } + continue; + } + if trimmed == "applicability:" || trimmed.starts_with("applicability:") { + in_applicability = true; + in_sources = false; + continue; + } + if in_sources { + if let Some(item) = trimmed.strip_prefix("- ") { + let path = item.trim().trim_matches('"').to_string(); + if !path.is_empty() { + out.sources.push(path); + } + } + continue; + } + if in_applicability { + if let Some(rest) = trimmed.strip_prefix("valid_until:") { + out.valid_until = Some(rest.trim().trim_matches('"').to_string()); + } else if let Some(rest) = trimmed.strip_prefix("region:") { + out.region = Some(rest.trim().trim_matches('"').to_string()); + } + } + } + out +} + +#[derive(Debug, Clone)] +pub enum ProvenanceDiag { + Missing { path: String }, + Expired { valid_until: String }, +} + +impl ProvenanceDiag { + pub fn code(&self) -> &'static str { + match self { + Self::Missing { .. } => "source.missing", + Self::Expired { .. } => "source.expired", + } + } + + pub fn message(&self) -> String { + match self { + Self::Missing { path } => format!("来源文件缺失:`{path}`"), + Self::Expired { valid_until } => { + format!("来源适用期已过(valid_until={valid_until})") + } + } + } +} + +pub struct ProvenanceResolution { + pub refs: Vec, + pub applicability: String, + pub evidence_status: String, + pub diagnostics: Vec, +} + +/// Resolve corpus paths relative to the module file; never mark verified here. +pub fn resolve_provenance( + module_path: &Path, + prov: &ModuleProvenance, +) -> ProvenanceResolution { + let mut refs = Vec::new(); + let mut diagnostics = Vec::new(); + let base = module_path + .parent() + .map(|p| p.to_path_buf()) + .unwrap_or_else(|| PathBuf::from(".")); + + for raw in &prov.sources { + let (path_part, locator) = match raw.split_once('#') { + Some((p, a)) => (p.trim(), Some(a.trim().to_string())), + None => (raw.as_str(), None), + }; + let resolved = base.join(path_part); + if !resolved.is_file() { + diagnostics.push(ProvenanceDiag::Missing { + path: raw.clone(), + }); + refs.push(SourceRef { + uri: path_part.to_string(), + locator, + content_digest: None, + relation: "supports".into(), + }); + continue; + } + let content = fs::read(&resolved).unwrap_or_default(); + let mut hash = Sha256::new(); + hash.update(&content); + refs.push(SourceRef { + uri: path_part.to_string(), + locator, + content_digest: Some(Digest(format!("sha256:{:x}", hash.finalize()))), + relation: "supports".into(), + }); + } + + if let Some(until) = &prov.valid_until { + if is_expired(until) { + diagnostics.push(ProvenanceDiag::Expired { + valid_until: until.clone(), + }); + } + } + + let applicability = match (&prov.region, &prov.valid_until) { + (None, None) if prov.sources.is_empty() => { + "no explicit applicability constraints".into() + } + (region, until) => { + let mut parts = Vec::new(); + if let Some(r) = region { + parts.push(format!("region={r}")); + } + if let Some(u) = until { + parts.push(format!("valid_until={u}")); + } + if parts.is_empty() { + "sources declared".into() + } else { + parts.join("; ") + } + } + }; + + let evidence_status = if diagnostics.iter().any(|d| matches!(d, ProvenanceDiag::Missing { .. })) + { + "missing_source".into() + } else if diagnostics + .iter() + .any(|d| matches!(d, ProvenanceDiag::Expired { .. })) + { + "expired".into() + } else if prov.sources.is_empty() { + "unverified".into() + } else { + // Corpus present and in date — still not domain-verified by compile alone. + "sourced".into() + }; + + ProvenanceResolution { + refs, + applicability, + evidence_status, + diagnostics, + } +} + +fn is_expired(valid_until: &str) -> bool { + // Expect YYYY-MM-DD; compare lexicographically to today's UTC date. + let today = chrono_today(); + !valid_until.is_empty() && valid_until < today.as_str() +} + +fn chrono_today() -> String { + // Avoid new dependency: use system local date via `date` is bad; use + // SystemTime → rough days since epoch is fragile. Prefer `time` crate if + // present, else format via `js_sys` — check Cargo.toml. + use std::time::{SystemTime, UNIX_EPOCH}; + let secs = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_secs() as i64; + // UTC civil date from days since epoch (proleptic Gregorian). + let days = secs.div_euclid(86_400); + let (y, m, d) = civil_from_days(days); + format!("{y:04}-{m:02}-{d:02}") +} + +/// Algorithm from Howard Hinnant (public domain). +fn civil_from_days(z: i64) -> (i32, u32, u32) { + let z = z + 719_468; + let era = if z >= 0 { z } else { z - 146_096 }.div_euclid(146_097); + let doe = (z - era * 146_097) as u64; + let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146_096) / 365; + let y = (yoe as i64 + era * 400) as i32; + let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); + let mp = (5 * doy + 2) / 153; + let d = doy - (153 * mp + 2) / 5 + 1; + let m = if mp < 10 { mp + 3 } else { mp - 9 }; + let y = if m <= 2 { y + 1 } else { y }; + (y, m as u32, d as u32) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parse_sources_and_valid_until() { + let src = "---\nsources:\n - ../corpus/tax.md#rate\napplicability:\n region: CN\n valid_until: 2099-12-31\n---\n\n# main\n"; + let p = parse_module_provenance(src); + assert_eq!(p.sources, vec!["../corpus/tax.md#rate"]); + assert_eq!(p.region.as_deref(), Some("CN")); + assert_eq!(p.valid_until.as_deref(), Some("2099-12-31")); + } +} diff --git a/tests/executable_knowledge.rs b/tests/executable_knowledge.rs index f288dcc..3fbea55 100644 --- a/tests/executable_knowledge.rs +++ b/tests/executable_knowledge.rs @@ -496,6 +496,267 @@ fn s2_g02_boundcall_runs_both_backends() { ); } +#[test] +fn s4_g05_sourced_evidence_and_expired_diag() { + let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")); + let out = std::env::temp_dir().join(format!( + "marqdo-ek-src-{}-{}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_nanos() + )); + let _ = std::fs::remove_dir_all(&out); + let status = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args([ + "knowledge", + "tests/executable_knowledge/baseline/12-tax-source", + "-o", + out.to_str().unwrap(), + ]) + .current_dir(&root) + .output() + .expect("knowledge"); + assert_eq!( + status.status.code(), + Some(0), + "stderr={}", + String::from_utf8_lossy(&status.stderr) + ); + let mut found_sourced = false; + for ent in std::fs::read_dir(out.join("artifacts")).unwrap().flatten() { + let v: serde_json::Value = + serde_json::from_str(&std::fs::read_to_string(ent.path()).unwrap()).unwrap(); + let ev = v["verification"]["evidence"].as_str().unwrap_or(""); + if v["kind"] == "function" && ev == "sourced" { + found_sourced = true; + let prov = v["provenance"].as_array().cloned().unwrap_or_default(); + assert!( + prov.iter().any(|p| p["relation"] == "supports"), + "supports SourceRef required: {v}" + ); + } + } + assert!(found_sourced, "functions should be evidence=sourced"); + assert_out_both( + "tests/executable_knowledge/baseline/12-tax-source/main.mq.md", + "113", + ); + use marqdo::mlsp::handle_line; + let project = root.join("tests/executable_knowledge/baseline/12-tax-source"); + let found: serde_json::Value = serde_json::from_str(&handle_line( + &serde_json::json!({"method":"artifact.find","params":{"project":&project,"query":"标准税率"}}) + .to_string(), + )) + .unwrap(); + let id = found["result"]["candidates"] + .as_array() + .unwrap() + .iter() + .find(|c| c["kind"] == "function") + .unwrap()["artifact_id"] + .as_str() + .unwrap(); + let biz: serde_json::Value = serde_json::from_str(&handle_line( + &serde_json::json!({"method":"artifact.bind","params":{"project":&project,"artifact_id":id,"policy":"business"}}) + .to_string(), + )) + .unwrap(); + assert_eq!(biz["ok"], true, "sourced artifact binds under business: {biz}"); + + let out2 = std::env::temp_dir().join(format!( + "marqdo-ek-exp-{}-{}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_nanos() + )); + let _ = std::fs::remove_dir_all(&out2); + let status2 = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args([ + "knowledge", + "tests/executable_knowledge/baseline/12b-tax-expired", + "-o", + out2.to_str().unwrap(), + ]) + .current_dir(&root) + .output() + .expect("knowledge expired"); + assert_eq!(status2.status.code(), Some(0)); + let mut found_expired = false; + for ent in std::fs::read_dir(out2.join("artifacts")).unwrap().flatten() { + let v: serde_json::Value = + serde_json::from_str(&std::fs::read_to_string(ent.path()).unwrap()).unwrap(); + if v["verification"]["evidence"] == "expired" { + found_expired = true; + } + } + assert!(found_expired, "12b-tax-expired should be evidence=expired"); + let _ = std::fs::remove_dir_all(&out); + let _ = std::fs::remove_dir_all(&out2); +} + +#[test] +fn s3_artifact_patch_wording_guard() { + use marqdo::mlsp::handle_line; + let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")); + let dir = std::env::temp_dir().join(format!( + "marqdo-ek-patch-{}-{}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_nanos() + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + let src = "---\nmarkup: occlusion\n---\n\n## 商品小计\n\n`数量` 与 `单价`。\n\n*[按数量与单价计算](数量 * 单价)*\n\n# main\n\n**小计 = [两件](商品小计(数量=2, 单价=30))**\n> print text=`小计`\n"; + std::fs::write(dir.join("main.mq.md"), src).unwrap(); + let found: serde_json::Value = serde_json::from_str(&handle_line( + &serde_json::json!({"method":"artifact.find","params":{"project":&dir,"query":"商品小计"}}) + .to_string(), + )) + .unwrap(); + assert_eq!(found["ok"], true, "{found}"); + let art = found["result"]["candidates"] + .as_array() + .unwrap() + .iter() + .find(|c| c["kind"] == "function") + .unwrap(); + let id = art["artifact_id"].as_str().unwrap(); + let inspected: serde_json::Value = serde_json::from_str(&handle_line( + &serde_json::json!({"method":"artifact.inspect","params":{"project":&dir,"artifact_id":id}}) + .to_string(), + )) + .unwrap(); + let impl_digest = inspected["result"]["hashes"]["implementation"] + .as_str() + .unwrap() + .to_string(); + let line = inspected["result"]["source"]["line"].as_u64().unwrap() as u32; + // Wording-only: change prose near the heading without touching signature. + let prose_line = line + 2; + let ok_patch: serde_json::Value = serde_json::from_str(&handle_line( + &serde_json::json!({ + "method":"artifact.patch", + "params":{ + "project":&dir, + "artifact_id":id, + "expected_digest":impl_digest, + "intent":"wording", + "edits":[{"op":"replace","line":prose_line,"text":"`数量` 与 `单价`(说明)。"}] + } + }) + .to_string(), + )) + .unwrap(); + assert_eq!(ok_patch["ok"], true, "prose tweak should apply: {ok_patch}"); + assert_eq!(ok_patch["result"]["diff"]["signature_changed"], false); + // Re-inspect and try a signature-breaking edit under wording intent. + let inspected2: serde_json::Value = serde_json::from_str(&handle_line( + &serde_json::json!({"method":"artifact.inspect","params":{"project":&dir,"artifact_id":id}}) + .to_string(), + )) + .unwrap(); + let impl2 = inspected2["result"]["hashes"]["implementation"] + .as_str() + .unwrap(); + let bad: serde_json::Value = serde_json::from_str(&handle_line( + &serde_json::json!({ + "method":"artifact.patch", + "params":{ + "project":&dir, + "artifact_id":id, + "expected_digest":impl2, + "intent":"wording", + "edits":[{"op":"replace","line":prose_line,"text":"`数量` `单价` `折扣`。"}] + } + }) + .to_string(), + )) + .unwrap(); + // Declaring a new backtick param may or may not change interface hash depending on + // whether params are inferred from prose; if signature changes, wording must roll back. + if bad["ok"] == false { + assert_eq!( + bad["error"]["code"], "artifact.wording_broke_contract", + "{bad}" + ); + } + let _ = root; + let _ = std::fs::remove_dir_all(&dir); +} + +#[test] +fn s1_g03_narrative_ref_steps_not_executed() { + let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")); + let out = std::env::temp_dir().join(format!( + "marqdo-ek-narr-{}-{}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_nanos() + )); + let _ = std::fs::remove_dir_all(&out); + let status = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args([ + "knowledge", + "tests/executable_knowledge/baseline/11-narrative-ref", + "-o", + out.to_str().unwrap(), + ]) + .current_dir(&root) + .output() + .expect("knowledge"); + assert_eq!( + status.status.code(), + Some(0), + "stderr={}", + String::from_utf8_lossy(&status.stderr) + ); + let steps: serde_json::Value = + serde_json::from_str(&std::fs::read_to_string(out.join("steps.json")).unwrap()).unwrap(); + let arr = steps["steps"].as_array().unwrap(); + assert!( + arr.iter().any(|s| s["kind"] == "narrate"), + "expected narrate step: {steps}" + ); + assert!( + arr.iter().any(|s| s["kind"] == "navigation"), + "expected navigation step: {steps}" + ); + let nav_count = arr.iter().filter(|s| s["kind"] == "navigation").count(); + assert_eq!( + nav_count, 1, + "only the prose URL becomes navigation (fence ignored): {steps}" + ); + let refs: serde_json::Value = + serde_json::from_str(&std::fs::read_to_string(out.join("refs.json")).unwrap()).unwrap(); + assert!( + refs["refs"].as_array().unwrap().iter().any(|r| { + r["context"] == "narrative" && r["resolution"] == "symbol" + }), + "narrate target 总额 should resolve: {refs}" + ); + // run must not fetch URL; stdout ok only + assert_out_both( + "tests/executable_knowledge/baseline/11-narrative-ref/main.mq.md", + "ok", + ); + let current = std::fs::read_to_string(out.join("CURRENT")).unwrap(); + let gen = out.join("generations").join(current.trim()); + assert!( + gen.join("steps.json").is_file(), + "generation tree must be complete under {}", + gen.display() + ); + let _ = std::fs::remove_dir_all(&out); +} + #[test] fn s2_g07_eng_reuse_requires_bind_before_execute() { // Discovery scores must not be treated as executable handles. diff --git a/tests/executable_knowledge/README.md b/tests/executable_knowledge/README.md index 122bbd5..0f894aa 100644 --- a/tests/executable_knowledge/README.md +++ b/tests/executable_knowledge/README.md @@ -18,6 +18,8 @@ | 06a | `baseline/06-reject/missing-import.mq.md` | expected_failure | 双后端均非 0 | 0(正确拒绝) | | 06b | `baseline/06-reject/ambiguous.mq.md` | expected_failure | **双后端均拒绝**裸名同名(G02) | — | | 10 | `baseline/10-boundcall/` | implemented | BoundCall 路径 SymbolId + DynamicCall(`call_fn`);双后端 `hi`/`60` | import 一行 | +| 11 | `baseline/11-narrative-ref/` | implemented | `narrate`/`navigation` 步骤;围栏不计;run 不拉 URL | 0 | +| 12 | `baseline/12-tax-source/` | implemented | `sources:` → evidence=sourced;过期 → expired;可试跑 `113` | sources + valid_until | ### 同名裸调用(G02) @@ -43,7 +45,13 @@ | S2/G07 子集 | **done** | MLSP bind 含 `symbol_id`;execute 按源行绑定;pure 拒非纯 | | S2/G02 BoundCall | **done** | 共享 `resolve_for_exec`;Tree/Bytecode 静态路径绑定;`bound_calls.json` / `dynamic_calls.json`;`10-boundcall` + `06b` | | S2/G07 eng_reuse | **done(子集)** | `reuse_json` / `agent_eng_reuse`:`discovery_only` + `bind_required` + `bind_targets`;执行仍须 MLSP bind | +| S1/G03 NarrativeRef | **done(子集)** | 注释行 `[]()` → narrate/navigation;`11-narrative-ref` | +| S4/G05 来源 | **done(子集)** | frontmatter `sources`/`valid_until`;`12-tax-source`;business bind | +| S3 patch | **done(子集)** | MLSP `artifact.patch` + wording 回滚 | +| S5/G04 整代 | **done(子集)** | `generations//` + `CURRENT` 指针 | +| S5/G08 锁分类 | **done(子集)** | `LockReport.classes`;impact 含 narrates | +| S6 CI | **done(子集)** | `.github/workflows/executable-knowledge.yml` | ## 与后续切片的关系 -- S3+:局部编辑、来源适用性、整代快照 — 见缺口路线图 +- 完整订单示例、100 单元语料、远程授权与规模 SLO — 见缺口路线图;未完成项不得笼统宣称「可执行知识已交付」 diff --git a/tests/executable_knowledge/baseline/11-narrative-ref/main.mq.md b/tests/executable_knowledge/baseline/11-narrative-ref/main.mq.md new file mode 100644 index 0000000..cc1c5ae --- /dev/null +++ b/tests/executable_knowledge/baseline/11-narrative-ref/main.mq.md @@ -0,0 +1,25 @@ +--- +markup: occlusion +title: S1 G03 正文 NarrativeRef +status: implemented +--- + +## 总额 + +订单含税合计。 + +*100* + +# main + +正文引用同一目标;URL 只作导航,围栏内链接不计步骤。 + +这张订单的含税总额是[含税总价](总额)。详见[政策原文](https://example.com/tax-policy)。 + +``` +[围栏内](https://example.com/ignored) +``` + +行内代码 `[skip](总额)` 不计。 + +> print text=ok diff --git a/tests/executable_knowledge/baseline/12-tax-source/corpus.md b/tests/executable_knowledge/baseline/12-tax-source/corpus.md new file mode 100644 index 0000000..d11c754 --- /dev/null +++ b/tests/executable_knowledge/baseline/12-tax-source/corpus.md @@ -0,0 +1,3 @@ +# 2026 年标准增值税率 + +演示用政策原文。标准税率为 13%。 diff --git a/tests/executable_knowledge/baseline/12-tax-source/main.mq.md b/tests/executable_knowledge/baseline/12-tax-source/main.mq.md new file mode 100644 index 0000000..9f602ae --- /dev/null +++ b/tests/executable_knowledge/baseline/12-tax-source/main.mq.md @@ -0,0 +1,20 @@ +--- +markup: occlusion +title: S4 G05 来源与适用期 +status: implemented +sources: + - corpus.md#标准税率 +applicability: + region: CN + valid_until: 2099-12-31 +--- + +## 标准税率 + +*[当前标准税率](0.13)* + +# main + +**税率 = [读取标准税率](标准税率())** +**含税 = [演示含税价](100 * (1 + 税率))** +> print text=`含税` diff --git a/tests/executable_knowledge/baseline/12b-tax-expired/corpus.md b/tests/executable_knowledge/baseline/12b-tax-expired/corpus.md new file mode 100644 index 0000000..d11c754 --- /dev/null +++ b/tests/executable_knowledge/baseline/12b-tax-expired/corpus.md @@ -0,0 +1,3 @@ +# 2026 年标准增值税率 + +演示用政策原文。标准税率为 13%。 diff --git a/tests/executable_knowledge/baseline/12b-tax-expired/main.mq.md b/tests/executable_knowledge/baseline/12b-tax-expired/main.mq.md new file mode 100644 index 0000000..7949c67 --- /dev/null +++ b/tests/executable_knowledge/baseline/12b-tax-expired/main.mq.md @@ -0,0 +1,18 @@ +--- +markup: occlusion +title: S4 G05 过期来源 +status: implemented +sources: + - corpus.md#标准税率 +applicability: + region: CN + valid_until: 2020-01-01 +--- + +## 标准税率 + +*[过期政策下的税率演示](0.13)* + +# main + +> print text=ok