PysolateExplained
打开文档导航
本科生解释查看 Markdown 源文件

Artifact、Profile 与 Placement

一句话

Host 根据已验证 artifact/profile 能支持的 imports，再结合 request 的 state、requirements、source 可判定性和 backend availability，生成一份带 identity 的 placement decision；未知信息不会被猜成 WASM 支持。

先看一个例子

考虑三段程序：

import json          # plain shard 已验证
import numpy         # 仓库有 numpy-core build profile
module = __import__(name)  # import root 运行时才知道

看起来第二段“已经有 NumPy artifact”，似乎应该进入 NumPy WASM；当前事实却是默认 router 只消费 plain shard，所以 import numpy 会按 no_qualified_shard 走 native。第三段无法静态确定 import，也保守走 native。

“仓库能构建一个包”与“运行时 router 已接通并能选择它”是两件事。

真实机制

四种基础对象

  • ExecutionArtifact：backend-tagged 执行身份。WASM 分支绑定 distribution artifact/manifest digest；native 分支绑定 OCI image digest 与 rootfs digest。它不把两种 backend 填进同一组 package/import 字段。
  • Distribution manifest：WASM build/verification 产物，可绑定 target、package inventory 与 import closure。Manifest 验证和 ExecutionArtifact.Validate 是相邻但独立的合同。
  • Package profile：封闭的 build-time registry/lock/recipe，例如 base、attrs-770、numpy-core。它描述怎样构建和验证 artifact，不会在运行时下载 package。
  • Execution profile：Host-owned admission policy，把允许的 import roots 与 verified artifact/manifest/qualification identity 绑定。Request 中的 compatibility declaration 只能收窄要求，不能安装包或授权。

Placement 顺序

当前 static-v1 router 大致按以下顺序判断：

  1. 对 raw request 做 strict decode，并计算 request identity。
  2. 非 portable_value state，例如 workspace/process/opaque dependency，选择 native。
  3. Host model-risk signal 或 typed native requirements 存在时，选择 native。
  4. 从 initial top-level import preamble 推断静态 roots。Dynamic、nested、late、relative、compound import 无法确定时，选择 native。
  5. 静态 roots 必须全部在当前 PlainShard.QualifiedImports() 中，而且 request declaration 与 profile 相容，才有 qualified_plain_shard。
  6. Qualified 且 WASM available 时选择 pysolate_wasm；WASM unavailable 而 native available 时选择 native。
  7. 请求需要 native 但 native unavailable，或两边都不可用时，返回 typed unavailable，不偷偷使用较弱 lane。

Decision identity 绑定 request digest、backend、reason、state、analyzer、WASM shard identity 和可选 parent decision。Native decision 不伪造 WASM shard。

Unknown 走 native 是兼容性选择，不是“native 已证明安全或一定能跑”。Native 仍要通过 image/rootfs/RPC/resource/cleanup contract；若 native 不可用，结果就是显式 unavailable。

当前 package 状态也要分层看：base/plain 已被默认 placement 消费；attrs-770 有 build/verification profile，但 generic router 未接通；numpy-core 有 static-native build、manifest 和 research helper，默认 Policy 仍不选择它。

Prepared Family 会在显式 embedding path 中再封存 pysolate.prepared-family-image.v1 identity，把 artifact、manifest、execution profile、qualified imports、deterministic profile、memory/ABI 与 NumPy input identity 绑定。这个 identity 用来拒绝 family/member drift，不会让默认 placement 因看到 numpy import 就自动创建 family。Source-pass transform 同样绑定 exact Guest artifact/profile，但 pass registration 也不是 backend route。

为什么重要

技术上： Placement 在 Guest 启动前发生，并保留可重算 reason/identity。动态 import 或声明漂移不会被错误解释为已验证 WASM artifact 的一部分。

产品和业务上： 平台可以逐个增加经过验证的 shard，而不需要先成为开放世界 package manager。无法证明的请求会进入兼容性 lane 或明确失败，用户不会得到“似乎跑在受支持 WASM 中”的假象。

不能推出什么

  • Package profile 没有 runtime install、wheel resolver 或任意 dependency graph。
  • numpy-core、attrs-770 的 artifact 存在不表示当前 router 会自动选择它们。
  • Qualified import root 只证明固定 qualification surface，不证明任意 API、动态行为或 native extension 都兼容。
  • Placement decision 不是 backend 成功、性能或安全认证。
  • Family image identity 与 pass registration identity 都不是 placement decision，也不会自动安装或选择 shard。

术语卡

  • Artifact：可执行的 WASM distribution 或 native image 及其验证身份。
  • Distribution manifest：WASM 构建产物的 target、package 与 import closure 证明；与 generic execution identity 分开验证。
  • Package profile：封闭的构建、lock、recipe 和 package selection 合同。
  • Execution profile：Host 对 artifact 与 allowed/qualified imports 的运行 admission 绑定。
  • Shard：为特定 import closure 构建和验证的 WASM artifact 单元。
  • Placement decision：Host 为 exact request 选择 backend 的 identity-bound 决定。

继续阅读