#weft

weft：织造时横向穿过的纬线。清单里的 wires 就是纬线——本项目把它们织成一份计划。

#安装与验收入口

git clone https://github.com/soehi/weft.git
cd weft
python scripts/install-toolchain.py --destination _build/toolchains/pinned

export MOON_HOME="$PWD/_build/toolchains/pinned"
export PATH="$MOON_HOME/bin:$PATH"
moon update
moon check src/api src/cli --target js
python3 scripts/check-release-inputs.py

$env:MOON_HOME = Join-Path (Get-Location) '_build/toolchains/pinned'
$env:PATH = (Join-Path $env:MOON_HOME 'bin') + ';' + $env:PATH
moon update
moon check src/api src/cli --target js
python scripts/check-release-inputs.py

moon run src/cli --target js -- plan examples/chain.json --out plan.json
# 类型错误，应失败并指出source.read/sink.in的签名不匹配
moon run src/cli --target js -- plan examples/type-mismatch.json
# 浏览器：打开 http://127.0.0.1:8000，选择成功链或类型错误示例
node scripts/build-demo.mjs
python scripts/serve-demo.py

#为什么有它

#快速开始

# 生成示例组件（从 WAT 汇编成真实组件二进制）
moon run src/tools/make_fixtures --target native -- examples

# 生成计划
moon run src/cli --target native -- plan examples/chain.json

# 同样的命令，换后端，输出逐字节相同
moon run src/cli --target js -- plan examples/chain.json

{
  "version": "0.1.0",
  "components": [
    { "name": "reader", "path": "reader.wasm" },
    { "name": "filter", "path": "filter.wasm" },
    { "name": "sink",   "path": "sink.wasm" }
  ],
  "wires": [
    { "from": "reader.read", "to": "filter.in" },
    { "from": "filter.out", "to": "sink.in" }
  ],
  "resources": { "max_memory_pages": 256, "quota": 1000000 }
}

{"plan_version":"0.2.0",
 "instances":[
   {"name":"reader","path":"reader.wasm","order":0,"incoming":[]},
   {"name":"filter","path":"filter.wasm","order":1,"incoming":[1]},
   {"name":"sink","path":"sink.wasm","order":2,"incoming":[0]}],
 "wires":[
   {"from":"filter.out","to":"sink.in","from_signature":"(i32) -> (i32)","to_signature":"(i32) -> (i32)"},
   {"from":"reader.read","to":"filter.in","from_signature":"(i32) -> (i32)","to_signature":"(i32) -> (i32)"}],
 "resources":{"max_memory_pages":256,"quota":1000000},
 "plan_hash":"1a3640bcc99318d5"}

#子命令

$ weft plan cycle.json
error: plan: dependency cycle: filter -> reader -> filter      # 退出码 1

$ weft plan bad.json
error: plan: `sink` has no port `missing`                      # 退出码 1

$ weft plan missing.wasm.json
error: cannot read component `reader` from /path/to/reader.wasm: No such file or directory

#架构

weft/
├── src/
│   ├── manifest/      声明式清单：解析 + 校验（纯逻辑，三后端）
│   ├── ir/            组件二进制 → 干净的接口/类型表（唯一解码点）
│   ├── plan/          ★ 规划器：图构建、环检测、拓扑排序、canonical 签名检查、JSON + hash
│   ├── wac_adapter/   WAC ↔ 清单 双向转换
│   ├── exec_plan/     计划 → 执行轨迹（纯逻辑，三后端可测）
│   ├── cli/           CLI（三后端可编译）
│   ├── runtime_native/  ★ native-only 实验执行命令（Linux 验证）
│   ├── runtime_probe/   Linux 两组件真实连线执行探针
│   └── tools/         开发者工具（生成示例组件）
├── examples/
├── docs/
└── .github/workflows/ci.yml

• manifest / ir / plan / wac_adapter / exec_plan 不 import wasmoon，只依赖 wasm_component、wac、wit、core。
• src/runtime_native 与独立测试包 src/runtime_probe import wasmoon，均声明 supported_targets = "native"。
• cli 三后端都能 moon build。

#解码路径

#规划器做什么

1. 解析组件：sniff_binary_kind → 语义解码 → 校验。失败时报哪个组件、什么错误。
2. 提取接口：world 的 imports/exports，含接口内函数与完整类型表。
3. 连线类型检查：先拒绝未支持的函数和值类型语义，再按双方各自的类型表检查严格结构相等，最后用上游 canonical ABI 展开作补充检查。bool 和 u32 即使同为 i32 也不兼容；规则见 支持矩阵。
4. 绑定覆盖：拒绝重复 wire、未绑定 import 和当前无法表达的实例/非函数 import。允许同一 export 连接不同函数 import。
5. 依赖图 + 环检测：DFS，报出环上的组件序列。
6. 拓扑排序：Kahn，同层按组件名字典序 tie-break（自有 cmp_str，不依赖库的 compare）。
7. 输出计划：JSON，含实例化顺序、连线绑定、资源策略元数据、plan_hash（对规范化后的计划体做 FNV-1a 64）。

#确定性从哪来

• 组件按名字排序后建图；邻接表排序去重。
• 拓扑排序的 ready 集合始终按名字取最小。
• wire 按 (from_component, from_port, to_component, to_port) 排序后才输出。
• 所有字符串比较用 src/ir/order.mbt 的逐码点字典序——不用 String::compare，因为本工具链的实现是"先比长度再比内容"，不是字典序。
• JSON 手写拼装，键顺序、数字格式全部显式。

#测试

moon test src/manifest src/ir src/plan src/wac_adapter src/exec_plan src/cli --target native
moon test src/manifest src/ir src/plan src/wac_adapter src/exec_plan src/cli --target wasm-gc
moon test src/manifest src/ir src/plan src/wac_adapter src/exec_plan src/cli --target js

1. src/plan/golden_wbtest.mbt 把示例计划的完整字节写死在测试里；它在三个后端都跑，任何一个后端的排序/格式/hash 有偏差都会在该后端失败。
2. CI 的 identical job 与本地入口使用同一 Node 检查程序，直接比较三个后端 --out 文件的完整字节，不过滤换行或错误日志。

bash scripts/check-backends.sh
# Windows PowerShell（需要 moon、node）：
pwsh -NoProfile -File scripts/check-backends.ps1
# 故意失败的隔离夹具：验证两个入口均失败并保留原始诊断（另需 Bash、pwsh）
node scripts/test-gate.mjs

#范围与限制（诚实边界）

• 规划器对函数级 wire 执行严格语义结构匹配与 ABI 检查；async、resource、own/borrow、future/stream、error-context、fixed-list/map 明确报 Unsupported。不做 subtyping 或接口实例整体兼容性证明，完整计划要求每个函数 import 恰有一条提供方 wire；导入接口实例与非函数 import 暂时拒绝，详见 绑定规则。详见 支持矩阵及迁移说明。
• 不宣称安全隔离 / 沙箱保证。隔离语义来自 wasmoon，而 wasmoon 上游自述：

  "This project is primarily developed with AI assistance and has not been thoroughly audited. Do not use in production or security-sensitive environments."

  本项目只能宣称"编排策略"，不能宣称"隔离保证"。
• 实验执行器已通过清单规划到真实跨实例连线的 Linux 集成测试；独立原生命令已验证30项CLI检查。
• Linux 独立探针已验证真实连线、断线和改接；实验执行器及独立原生命令已接入。Windows/MSVC 的 C11 原子链接阻塞仍存在，macOS 未验证。见 docs/S3-EXECUTION.md。
• 不做分布式、不做集群、不做网络传输——那是 wasmCloud 的领域。
• 不做静态合成产物——那是 wasm-compose 的领域。
• 不重写 WAC 语言——解析与验证全部走 moonrockz/wac。本适配器只把已通过验证的语义模型映射成清单，遇到 spread、嵌套 new、rename 等超出清单模型的结构会明确报 Unsupported，不静默近似。
• 生态里已有 moonrockz/wac、wasm-devkit、mizchi/wit、pei0331/moon-wit 等工具。本文档不使用"首个""唯一"这类无法证伪的表述。

#执行层现状

moon run src/runtime_native --target native -- run examples/execution/chain.json --component consumer --export run --arg u32:41

#依赖

#许可证