MoonRestrict

用 MoonBit 实现的离线 DNA 限制性切割坐标、片段重建与证据校验库。

输入 IUPAC DNA、线性/环形拓扑及显式识别/切割模型，输出保留双链坐标和不确定性证据的切割图。 重点不是再做一套通用序列工具：复用 ziju-max/genetic_code@0.1.0 的碱基集合、互补与 FASTA 能力，新增切割几何、环形片段、独立片段校验及比较流程。

仅作抽象序列计算和教学。全部样例为合成字符串；不提供真实酶数据库、实验条件、实验控制、疾病判断或湿实验成功率。包已发布到 MoonCakes；发布成功不代表已经通过赛事验收。

公开源码：CYang-dep/moonrestrict。四目标检查、53 项测试、构建和真实进程验证已通过 CI 基线，包括 Linux native；详细证据与限制见 交付审计。

快速运行

需要 MoonBit、运行 JS 时的 Node.js、运行验收脚本时的 Python 3.8+。native 还需要可用的 C 编译器。 在取得本仓库源代码后，在仓库根目录运行：

moon update
moon check --target wasm-gc --deny-warn
moon test --target wasm-gc
moon run cmd/main --target wasm-gc -- demo
moon run examples/workflow --target wasm-gc
python scripts/cli_smoke.py --target wasm-gc

demo 对环形 GTAC 使用合成模型 ACGT / top=1 / bottom=3：识别起点为 2，顶部切口为 3，底部切口为 1；产生单个线性化片段 CGTA，长度仍为 4。坐标均从 0 开始。

本地验收工具链：moon 0.1.20260713、moonc v0.10.4+2cc641edf。CI 固定安装版本 0.10.4+2cc641edf，不使用浮动 latest。版本兼容性必须通过检查/测试确认，不宣称所有未来工具链均可运行。

三个可复现使用场景

1. 教学开发者检查跨原点切口：运行 demo，读取 sites 的正反链及切口证据，再观察环形分子线性化后的 CGTA，避免把跨原点识别误判成未命中。
2. 离线分析程序校验存档图谱：将 examples/linear.json 交给 digest，再把原请求和报告交给 verify；改动长度或片段序列会被拒绝。验收脚本实际执行成功和篡改失败两条路径。
3. 工具作者比较合成样本：运行 examples/workflow，从三个 FASTA 记录和 TSV 模型开始，生成经校验的图谱、跨原点注释片段、4 个切口子集及精确长度指纹；贪心面板选择第 1 列（从 0 起），区分全部三个样本。这只是字符串指纹区分，不是实验模型推荐。

命令行和文件输入

digest REQUEST_JSON
verify REQUEST_JSON REPORT_JSON
demo
--help

参数是 JSON 文本，不是文件名。PowerShell 示例（适用于小型输入）：

$request = Get-Content -Raw examples/circular.json
moon run cmd/main --target wasm-gc -- digest $request

可移植 Python 示例避免手工 shell 引号，且无需第三方库：

import pathlib, subprocess
request = pathlib.Path("examples/circular.json").read_text(encoding="utf-8")
result = subprocess.run(
    ["moon", "run", "cmd/main", "--target", "wasm-gc", "--", "digest", request],
    capture_output=True, text=True, encoding="utf-8", check=True)
report = result.stdout.strip()
subprocess.run(["moon", "run", "cmd/main", "--target", "wasm-gc", "--",
                "verify", request, report], check=True)

命令行受操作系统参数长度限制（尤其 Windows）；大输入应使用库 API，不应绕过边界扩大 shell 命令。 失败时第一条 stdout 记录为 {"ok":false,"error":"..."}，进程保证非零退出，但具体退出值及 panic 信息依赖运行时。 可嵌入的 command 则稳定返回 exit_code=0/2，不执行 I/O、不 panic。不要把可嵌入返回码等同于所有进程的退出码。

库 API

源代码使用示例见 examples/workflow/main.mbt，完整签名见 pkg.generated.mbti。 本模块已于 2026-09-11 发布到 MoonCakes，版本为 0.1.0，许可证为 MIT。已在独立消费项目中从公共源下载，并通过严格检查与多记录工作流运行验证。

在你的 MoonBit 项目根目录安装：

moon add CYang-dep/moonrestrict@0.1.0

这里的安装命令用于将库加入现有项目；上面的 cmd/main 和 examples/workflow 命令则应在本仓库源码目录运行。

此 README 已按实际发布状态更新。已发布的 0.1.0 包和 GitHub v0.1.0 标签保留发布时快照，其中的旧 README 仍可能显示“未发布”；不覆盖已发布版本。该版本 MoonCakes 元数据的 repository 字段为空，源码仓库以本文顶部的 GitHub 链接为准。 在可解析本模块的 MoonBit 工作区中，包声明导入：

import { "CYang-dep/moonrestrict" @restrict }

在允许抛出 RestrictError 的函数或测试中：

let dna = @restrict.Dna::new("GTAC", topology=Circular)
let enzyme = @restrict.Enzyme::new("synthetic", "ACGT", 1, 3)
let report = @restrict.digest(dna, enzyme)
@restrict.verify_digest(dna, [enzyme], report)
let (before, after) = @restrict.cut_ends(dna, report.cuts[0])
let compatibility = @restrict.compatible_ends(before, after)

能力	API
校验/转换 DNA 与模型	Dna::new, Enzyme::new, reverse_complement
双向识别与确定性	scan
完整单/多模型切割	digest, digest_many
证据、片段坐标及原文校验	verify_digest, Request::verify
平末端、5′/3′突出末端和互补性	cut_ends, compatible_ends
FASTA 与模型 TSV	read_fasta, write_fasta, read_enzymes, write_enzymes
部分切割的数学子集	partial_digests
区间投影	annotate_fragments
精确长度指纹与比较	size_bands, band_signature, compare_maps, select_panel
版本化 JSON 与可移植命令分发	read_request, read_report, run_json, command

关键语义与边界

• 半开区间、参考顶部链方向、0 起点边界坐标；片段长度是顶部链长度，不是双链物理轮廓长度或质量。
• 反向识别变换：top = start + motif_length - bottom_offset；bottom = start + motif_length - top_offset。
• 环形坐标取模但保留有符号 stagger；未切割环保持 circular=true，有切口则输出线性片段。识别模式不允许比整条环更长。
• 输入碱基集合全部满足模式才是 Certain；仅部分交集为 Possible。默认只切确定命中，显式 possible 才纳入可能命中，reject 遇到可能命中即失败。这些不是概率。
• 同一顶部切口且相同几何合并，但原始识别证据全部保留；同顶不同底、底链交叉/共用切口及不支持的环形几何失败，不伪造物理片段。
• verify_digest 重新运行识别/选切，并独立检查片段边界、逐碱基内容和长度守恒；它不是第二套独立识别算法，也不是密码学签名或数据来源认证。
• 精确条带保留重复次数，不做电泳误差、强度、分辨率或质量推断。面板采用确定性贪心，不保证最小列数。

详见 协议与限制、架构、来源、安全边界 和 查重范围。

开发与验收

moon fmt --check
moon check --target wasm-gc --deny-warn
moon check --target wasm --deny-warn
moon check --target js --deny-warn
moon check --target native --deny-warn
python scripts/verify.py --skip-native-runtime
# 有 C 编译器时，运行完整四目标验收：
python scripts/verify.py

verify.py 执行检查、测试、构建、真实命令行与多记录工作流。跳过 native 运行时会明确记录 SKIP，不算 PASS。 测试含 1,364 个长度 1–5 的具体 DNA 字符串、256 个四碱基环的各次旋转、225 组 IUPAC 集合匹配及恶意输入回归；数量是域覆盖，不宣称穷尽所有 DNA。

MIT 开源；AI 参与范围见 AI_USAGE.md，贡献流程见 CONTRIBUTING.md。