From b0be572d34c4def6315a79108de9cba5ec658ce5 Mon Sep 17 00:00:00 2001 From: Reiase Date: Sun, 18 Oct 2026 17:08:04 +0800 Subject: [PATCH 01/14] Rewrite docs navigation and remove retired pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Collapse start/, concepts/, why/, community/, and benchmarks/ sections by merging or deleting thin pages (161→123 pages per locale) - Rewrite governance.md to describe the actual single-maintainer model - Fold methodology.md into benchmarks/index.md, preserving anchors - Move retired Cluster and daemon design detail into surviving pages - Add provenance notes to performance analysis pages for unpublished local `.data/` archives - Fix `pvisor-replay` managed run to pass `--config` instead of rejected `--spec` - Update check-docs.py render assertions for the merged pages --- .workbuddy/memory/2026-10-18.md | 27 ++++ benchmark.new/docs.json | 64 +------- crates/pvisor-cli/src/bin/pvisor-replay.rs | 2 +- docs/README.md | 119 +++++--------- docs/overrides/home.html | 2 +- docs/src/en/benchmarks/agent-tasks.md | 2 +- docs/src/en/benchmarks/cluster-scalability.md | 33 +++- docs/src/en/benchmarks/compare-rl-infra.md | 2 +- docs/src/en/benchmarks/density.md | 2 +- docs/src/en/benchmarks/index.md | 60 ++++++- docs/src/en/benchmarks/isolation-tests.md | 2 +- .../measurement-coverage.render.json | 4 - docs/src/en/benchmarks/methodology.md | 77 --------- docs/src/en/benchmarks/network.md | 2 +- docs/src/en/benchmarks/replay-fidelity.md | 2 +- docs/src/en/benchmarks/startup.md | 2 +- docs/src/en/benchmarks/supervision-cost.md | 2 +- docs/src/en/cases/index.md | 2 +- docs/src/en/community/adopters.md | 28 ---- docs/src/en/community/code-of-conduct.md | 26 --- docs/src/en/community/governance.md | 29 ++-- docs/src/en/community/index.md | 8 + docs/src/en/community/roadmap.md | 6 +- .../en/concepts/capabilities-and-evidence.md | 4 + docs/src/en/concepts/glossary.md | 17 -- docs/src/en/concepts/index.md | 33 ---- docs/src/en/concepts/policy-model.md | 13 -- .../design/agent-task-performance-analysis.md | 14 +- docs/src/en/design/architecture.md | 4 +- .../design/benchmark-methodology-evidence.md | 4 +- docs/src/en/design/cli.md | 2 +- docs/src/en/design/cluster-benchmark-plan.md | 41 ----- .../en/design/cluster-performance-analysis.md | 38 ----- docs/src/en/design/daemon/admission.md | 45 ------ docs/src/en/design/daemon/index.md | 85 ++++++++-- docs/src/en/design/daemon/lifecycle.md | 42 ----- docs/src/en/design/daemon/operations.md | 4 +- .../daemon/responsibility-convergence.md | 63 -------- .../en/design/daemon/shared-working-set.md | 4 +- .../en/design/daemon/state-and-recovery.md | 46 ------ docs/src/en/design/daemon/storage.md | 43 ++++- .../decisions/0001-plan-and-evidence.md | 11 -- .../decisions/0002-capture-and-replay.md | 11 -- .../decisions/0003-explicit-safe-executor.md | 11 -- .../decisions/0004-human-semspec-approval.md | 11 -- .../en/design/decisions/0005-rust-vm-api.md | 11 -- .../design/decisions/0006-stage-snapshot.md | 2 +- .../0007-shared-filesystem-service.md | 23 --- .../0008-host-guest-control-authority.md | 25 --- docs/src/en/design/decisions/index.md | 14 +- docs/src/en/design/environment-snapshot.md | 2 +- .../experimental/guest-stage-cache/index.md | 2 +- .../filesystem-io-performance-analysis.md | 2 + .../design/filesystem-performance-analysis.md | 8 +- docs/src/en/design/index.md | 2 +- .../memory-optimization/compression-local.md | 2 +- .../memory-optimization/compression-pool.md | 2 +- .../design/memory-optimization/compression.md | 49 ------ .../memory-optimization/deduplication.md | 2 +- .../en/design/memory-optimization/index.md | 8 +- .../memory-optimization/offload-format.md | 60 ------- .../en/design/memory-optimization/offload.md | 6 +- .../memory-optimization/proof-of-concept.md | 2 +- docs/src/en/design/records-and-versions.md | 2 +- .../en/design/research/cluster-execution.md | 41 ----- .../en/design/research/design-documents.md | 58 ------- docs/src/en/design/research/index.md | 39 ++++- docs/src/en/design/research/publications.md | 25 --- .../design/research/rl-execution-substrate.md | 31 ---- .../design/vm-memory-performance-analysis.md | 2 + .../design/vm-startup-performance-analysis.md | 8 +- docs/src/en/guides/agents/aider.md | 17 -- docs/src/en/guides/agents/gemini-cli.md | 17 -- docs/src/en/guides/agents/index.md | 21 ++- docs/src/en/guides/agents/opencode.md | 17 -- docs/src/en/guides/daemon/boundaries.md | 51 ------ docs/src/en/guides/daemon/index.md | 148 ++++++++++++------ docs/src/en/guides/daemon/operations.md | 69 -------- docs/src/en/guides/daemon/service.md | 35 ----- docs/src/en/guides/index.md | 2 +- docs/src/en/guides/policies/files.md | 2 +- docs/src/en/reference/cli.md | 26 +-- docs/src/en/reference/config.md | 2 +- docs/src/en/reference/env-vars.md | 2 +- docs/src/en/reference/exit-codes.md | 2 +- docs/src/en/reference/platforms.md | 2 +- docs/src/en/security/executor-boundaries.md | 2 +- docs/src/en/start/first-run.md | 16 ++ docs/src/en/start/index.md | 37 ----- docs/src/en/start/next-steps.md | 27 ---- docs/src/en/start/what-is-pvisor.md | 33 ---- docs/src/en/why/comparisons.md | 36 ++++- docs/src/en/why/faq.md | 22 --- docs/src/en/why/index.md | 19 ++- docs/src/en/why/trust-ladder.md | 41 ----- docs/src/en/why/use-cases.md | 25 --- docs/src/en/why/when-not-to-use.md | 12 -- docs/src/zh/benchmarks/agent-tasks.md | 2 +- docs/src/zh/benchmarks/cluster-scalability.md | 33 +++- docs/src/zh/benchmarks/compare-rl-infra.md | 2 +- docs/src/zh/benchmarks/density.md | 2 +- docs/src/zh/benchmarks/index.md | 60 ++++++- docs/src/zh/benchmarks/isolation-tests.md | 2 +- .../measurement-coverage.render.json | 4 - docs/src/zh/benchmarks/methodology.md | 77 --------- docs/src/zh/benchmarks/network.md | 2 +- docs/src/zh/benchmarks/replay-fidelity.md | 2 +- docs/src/zh/benchmarks/startup.md | 2 +- docs/src/zh/benchmarks/supervision-cost.md | 2 +- docs/src/zh/cases/index.md | 2 +- docs/src/zh/community/adopters.md | 28 ---- docs/src/zh/community/code-of-conduct.md | 26 --- docs/src/zh/community/governance.md | 29 ++-- docs/src/zh/community/index.md | 8 + docs/src/zh/community/roadmap.md | 6 +- .../zh/concepts/capabilities-and-evidence.md | 4 + docs/src/zh/concepts/glossary.md | 17 -- docs/src/zh/concepts/index.md | 33 ---- docs/src/zh/concepts/policy-model.md | 13 -- .../design/agent-task-performance-analysis.md | 14 +- docs/src/zh/design/architecture.md | 4 +- .../design/benchmark-methodology-evidence.md | 4 +- docs/src/zh/design/cli.md | 2 +- docs/src/zh/design/cluster-benchmark-plan.md | 41 ----- .../zh/design/cluster-performance-analysis.md | 38 ----- docs/src/zh/design/daemon/admission.md | 45 ------ docs/src/zh/design/daemon/index.md | 85 ++++++++-- docs/src/zh/design/daemon/lifecycle.md | 42 ----- docs/src/zh/design/daemon/operations.md | 4 +- .../daemon/responsibility-convergence.md | 63 -------- .../zh/design/daemon/shared-working-set.md | 4 +- .../zh/design/daemon/state-and-recovery.md | 46 ------ docs/src/zh/design/daemon/storage.md | 43 ++++- .../decisions/0001-plan-and-evidence.md | 11 -- .../decisions/0002-capture-and-replay.md | 11 -- .../decisions/0003-explicit-safe-executor.md | 11 -- .../decisions/0004-human-semspec-approval.md | 11 -- .../zh/design/decisions/0005-rust-vm-api.md | 11 -- .../design/decisions/0006-stage-snapshot.md | 2 +- .../0007-shared-filesystem-service.md | 23 --- .../0008-host-guest-control-authority.md | 25 --- docs/src/zh/design/decisions/index.md | 14 +- docs/src/zh/design/environment-snapshot.md | 2 +- .../experimental/guest-stage-cache/index.md | 2 +- .../filesystem-io-performance-analysis.md | 2 + .../design/filesystem-performance-analysis.md | 8 +- docs/src/zh/design/index.md | 2 +- .../memory-optimization/compression-local.md | 2 +- .../memory-optimization/compression-pool.md | 2 +- .../design/memory-optimization/compression.md | 42 ----- .../memory-optimization/deduplication.md | 2 +- .../zh/design/memory-optimization/index.md | 8 +- .../memory-optimization/offload-format.md | 60 ------- .../zh/design/memory-optimization/offload.md | 5 +- .../memory-optimization/proof-of-concept.md | 2 +- docs/src/zh/design/records-and-versions.md | 2 +- .../zh/design/research/cluster-execution.md | 41 ----- .../zh/design/research/design-documents.md | 58 ------- docs/src/zh/design/research/index.md | 39 ++++- docs/src/zh/design/research/publications.md | 25 --- .../design/research/rl-execution-substrate.md | 31 ---- .../design/vm-memory-performance-analysis.md | 2 + .../design/vm-startup-performance-analysis.md | 8 +- docs/src/zh/guides/agents/aider.md | 17 -- docs/src/zh/guides/agents/gemini-cli.md | 17 -- docs/src/zh/guides/agents/index.md | 21 ++- docs/src/zh/guides/agents/opencode.md | 17 -- docs/src/zh/guides/daemon/boundaries.md | 51 ------ docs/src/zh/guides/daemon/index.md | 127 ++++++++++----- docs/src/zh/guides/daemon/operations.md | 69 -------- docs/src/zh/guides/daemon/service.md | 35 ----- docs/src/zh/guides/index.md | 2 +- docs/src/zh/guides/policies/files.md | 2 +- docs/src/zh/reference/cli.md | 26 +-- docs/src/zh/reference/config.md | 2 +- docs/src/zh/reference/env-vars.md | 2 +- docs/src/zh/reference/exit-codes.md | 2 +- docs/src/zh/reference/platforms.md | 2 +- docs/src/zh/reference/vocab/vm.sh | 1 - docs/src/zh/security/executor-boundaries.md | 2 +- docs/src/zh/start/first-run.md | 16 ++ docs/src/zh/start/index.md | 37 ----- docs/src/zh/start/next-steps.md | 27 ---- docs/src/zh/start/what-is-pvisor.md | 33 ---- docs/src/zh/why/comparisons.md | 36 ++++- docs/src/zh/why/faq.md | 22 --- docs/src/zh/why/index.md | 19 ++- docs/src/zh/why/trust-ladder.md | 41 ----- docs/src/zh/why/use-cases.md | 25 --- docs/src/zh/why/when-not-to-use.md | 12 -- docs/translations.json | 144 +++++++---------- docs/zensical.en.toml | 35 +---- docs/zensical.zh.toml | 35 +---- scripts/check-docs.py | 9 +- 194 files changed, 1179 insertions(+), 3122 deletions(-) delete mode 100644 docs/src/en/benchmarks/methodology.md delete mode 100644 docs/src/en/community/adopters.md delete mode 100644 docs/src/en/community/code-of-conduct.md delete mode 100644 docs/src/en/concepts/glossary.md delete mode 100644 docs/src/en/concepts/index.md delete mode 100644 docs/src/en/concepts/policy-model.md delete mode 100644 docs/src/en/design/cluster-benchmark-plan.md delete mode 100644 docs/src/en/design/cluster-performance-analysis.md delete mode 100644 docs/src/en/design/daemon/admission.md delete mode 100644 docs/src/en/design/daemon/lifecycle.md delete mode 100644 docs/src/en/design/daemon/responsibility-convergence.md delete mode 100644 docs/src/en/design/daemon/state-and-recovery.md delete mode 100644 docs/src/en/design/decisions/0001-plan-and-evidence.md delete mode 100644 docs/src/en/design/decisions/0002-capture-and-replay.md delete mode 100644 docs/src/en/design/decisions/0003-explicit-safe-executor.md delete mode 100644 docs/src/en/design/decisions/0004-human-semspec-approval.md delete mode 100644 docs/src/en/design/decisions/0005-rust-vm-api.md delete mode 100644 docs/src/en/design/decisions/0007-shared-filesystem-service.md delete mode 100644 docs/src/en/design/decisions/0008-host-guest-control-authority.md delete mode 100644 docs/src/en/design/memory-optimization/compression.md delete mode 100644 docs/src/en/design/memory-optimization/offload-format.md delete mode 100644 docs/src/en/design/research/cluster-execution.md delete mode 100644 docs/src/en/design/research/design-documents.md delete mode 100644 docs/src/en/design/research/publications.md delete mode 100644 docs/src/en/design/research/rl-execution-substrate.md delete mode 100644 docs/src/en/guides/agents/aider.md delete mode 100644 docs/src/en/guides/agents/gemini-cli.md delete mode 100644 docs/src/en/guides/agents/opencode.md delete mode 100644 docs/src/en/guides/daemon/boundaries.md delete mode 100644 docs/src/en/guides/daemon/operations.md delete mode 100644 docs/src/en/guides/daemon/service.md delete mode 100644 docs/src/en/start/index.md delete mode 100644 docs/src/en/start/next-steps.md delete mode 100644 docs/src/en/start/what-is-pvisor.md delete mode 100644 docs/src/en/why/faq.md delete mode 100644 docs/src/en/why/trust-ladder.md delete mode 100644 docs/src/en/why/use-cases.md delete mode 100644 docs/src/en/why/when-not-to-use.md delete mode 100644 docs/src/zh/benchmarks/methodology.md delete mode 100644 docs/src/zh/community/adopters.md delete mode 100644 docs/src/zh/community/code-of-conduct.md delete mode 100644 docs/src/zh/concepts/glossary.md delete mode 100644 docs/src/zh/concepts/index.md delete mode 100644 docs/src/zh/concepts/policy-model.md delete mode 100644 docs/src/zh/design/cluster-benchmark-plan.md delete mode 100644 docs/src/zh/design/cluster-performance-analysis.md delete mode 100644 docs/src/zh/design/daemon/admission.md delete mode 100644 docs/src/zh/design/daemon/lifecycle.md delete mode 100644 docs/src/zh/design/daemon/responsibility-convergence.md delete mode 100644 docs/src/zh/design/daemon/state-and-recovery.md delete mode 100644 docs/src/zh/design/decisions/0001-plan-and-evidence.md delete mode 100644 docs/src/zh/design/decisions/0002-capture-and-replay.md delete mode 100644 docs/src/zh/design/decisions/0003-explicit-safe-executor.md delete mode 100644 docs/src/zh/design/decisions/0004-human-semspec-approval.md delete mode 100644 docs/src/zh/design/decisions/0005-rust-vm-api.md delete mode 100644 docs/src/zh/design/decisions/0007-shared-filesystem-service.md delete mode 100644 docs/src/zh/design/decisions/0008-host-guest-control-authority.md delete mode 100644 docs/src/zh/design/memory-optimization/compression.md delete mode 100644 docs/src/zh/design/memory-optimization/offload-format.md delete mode 100644 docs/src/zh/design/research/cluster-execution.md delete mode 100644 docs/src/zh/design/research/design-documents.md delete mode 100644 docs/src/zh/design/research/publications.md delete mode 100644 docs/src/zh/design/research/rl-execution-substrate.md delete mode 100644 docs/src/zh/guides/agents/aider.md delete mode 100644 docs/src/zh/guides/agents/gemini-cli.md delete mode 100644 docs/src/zh/guides/agents/opencode.md delete mode 100644 docs/src/zh/guides/daemon/boundaries.md delete mode 100644 docs/src/zh/guides/daemon/operations.md delete mode 100644 docs/src/zh/guides/daemon/service.md delete mode 120000 docs/src/zh/reference/vocab/vm.sh delete mode 100644 docs/src/zh/start/index.md delete mode 100644 docs/src/zh/start/next-steps.md delete mode 100644 docs/src/zh/start/what-is-pvisor.md delete mode 100644 docs/src/zh/why/faq.md delete mode 100644 docs/src/zh/why/trust-ladder.md delete mode 100644 docs/src/zh/why/use-cases.md delete mode 100644 docs/src/zh/why/when-not-to-use.md diff --git a/.workbuddy/memory/2026-10-18.md b/.workbuddy/memory/2026-10-18.md index cf0c7213..32b3650a 100644 --- a/.workbuddy/memory/2026-10-18.md +++ b/.workbuddy/memory/2026-10-18.md @@ -33,3 +33,30 @@ - 注意：两版 filesystem.md 的下载链接和图链接在会话期间被外部更新过（PDF→SVG、裸文件名→overrides 完整路径），编辑前需重读文件。 经验：benchmark 用户页规范在 benchmark/README.md#structure 与 #checklist——结论不点名对照项目（名称/版本/数据放数据节）、首句必须直接回答标题、短板上浮、中英同步。 + +## 全站文档 + 设计实现整体 review（产出 review/2026-10-18-docs-review.md） + +用户对文档的两条批评：结论不直接（机器自洽）、结构迂腐（没料撑叙事）。四路并行审读后结论： +- 事实层健康（约 30 项命令/版本对照源码全部通过），债务在叙事层：同一事实被重复包装（三命令闭环 ×10 页、owner.json 段落 ×3、三性框架三套命名）。 +- 重灾区：community/governance.md（单人项目虚构复数治理，P0）、design/decisions 8 篇 ADR 仅 0006 是真的、design/ 下 6 个性能分析页约 4000 行是实验流水账（含 52 处死链 + agent-tasks 两版数字漂移）、experimental/guest-stage-cache 637 行零实现 RFC、guides/daemon 四页 5 处逐字复制、guides/agents 三个 17 行 stub。 +- 标杆页：cases/、security/、reference/ 主体、design 的 overlayfs/journal/records-and-versions、staging.md（可证伪写法）。 +- 设计↔实现漂移仅两处 P1：overlayfs.md:95-101 并发模型描述的是已退役为 test fixture 的旧 pool（生产是 scheduler.rs lane+work stealing）；architecture.md crate 表漏 pvisor-shim。10-17 的三个 P0 已修两个；pvisor-replay TOML/--spec 矛盾仍在（pvisor-replay.rs:361-388 vs run.rs:856,945-949），优先修。 +- 重构计划四阶段：P0 止损（数据矛盾/死链）→ P1 纯减法合并（161→约120页）→ P2 迁移定位（lab-notes、proposal 标注）→ P3 只重写结论层 + 防复发规则。 + +## Phase 0 止损已执行（用户要求逐 Phase 停顿 review） + +- benchmarks/index.md（中英）Startup 行改 2026-10-11 批次数字；reference/cli.md（中英）帮助分组块改 Execution/Changes/Checkpoints/Tools（去掉退役 service）、events.jsonl→events.trace.jsonl；删 zh/reference/vocab/vm.sh 死符号链接。 +- 复核推翻 review 两处误判：methodology.md 锚点实际存在（断锚不成立）；52 处 .data 引用是行内代码段归档路径而非链接。改为在 6 个性能分析页（中英 12 处）页首加统一溯源注记。 +- pvisor-replay.rs:388 `run --spec` → `run --config`（TOML RunConfig 走 --spec 必被拒绝且缺 --result-file）。cargo check 通过，nextest bin 测试 4/4 通过。 +- 教训：Explore agent 的「断锚/死链」结论需人工复核后再动手；锚点要用 `^#`/`{#` 模式核实，行内代码段不等于链接。 + +## Phase 1 后半段（#14-16）执行记录 +- start/ 5→2：删 index/what-is-pvisor/next-steps，next-steps 独占内容（fork 前提、扩大范围提醒、--pass-env 实例）并入 first-run.md 末节；home.html 产品按钮改指 why/。 +- concepts/ 6→3：policy-model 叠加规则并入 capabilities-and-evidence.md#layering；删 glossary/index；files.md 入链改锚点。 +- why/ 7→3：trust-ladder+use-cases 并入 why/index.md（{#trust-ladder} 锚，四级表+摊薄论证）；when-not-to-use+faq 并入 comparisons.md（改题"适用判断、方案对比与常见问题"）；roadmap.md 入链改 why/index.md#trust-ladder。 +- community/：adopters+code-of-conduct 并入 index.md（讨论约定/试用与案例两节）；governance.md 重写为单一维护者实际状态。 +- benchmarks/methodology.md 并入 benchmarks/index.md（保留 #full-ubuntu/#full-ubuntu-qemu/#product-v1/#reference-env/#reference-resources/#json-tables 锚点）；同步删 measurement-coverage.render.json 的 methodology 行，并把 benchmark.new/docs.json 中 coverage rows 14→13、删 methodology 页条目。 +- 收尾修复 zensical --strict 暴露的 7 条残留死链（daemon/boundaries、cluster-execution、ADR 0005/0008、offload-format），中英同步。 +- check-docs.py 的 what-is-pvisor 硬编码渲染检查改为 why/index(admonition)+start/first-run(code block)。 +- 终态：123 页/locale（161→123，-24%），check-docs 全绿（123 pairs / 249 HTML 页），--record-translations 已记录。 +- 教训：本机 sed 是 GNU 语法，-i '' 会把脚本当文件名；用 perl -pi -e 替代。zensical --strict 是删页后死链的最终防线，check-docs 的构建后校验依赖最新 site/。 diff --git a/benchmark.new/docs.json b/benchmark.new/docs.json index 6fd2d419..526631a2 100644 --- a/benchmark.new/docs.json +++ b/benchmark.new/docs.json @@ -70,7 +70,7 @@ { "json": "benchmarks/measurement-coverage.render.json", "kind": "coverage", - "rows": 14, + "rows": 13, "columns": [ "数据状态", "实测范围" @@ -108,16 +108,6 @@ "../../../overrides/assets/benchmarks/data/lazy/lazy-stage-comparisons.csv" ] }, - { - "locale": "zh", - "page": "benchmarks/methodology.md", - "benchmark_ids": [ - "B-METHOD" - ], - "role": "user-facing", - "tables": [], - "source_csv": [] - }, { "locale": "zh", "page": "benchmarks/network.md", @@ -273,26 +263,6 @@ "tables": [], "source_csv": [] }, - { - "locale": "zh", - "page": "design/cluster-performance-analysis.md", - "benchmark_ids": [ - "B-CLUSTER" - ], - "role": "engineering evidence", - "tables": [], - "source_csv": [] - }, - { - "locale": "zh", - "page": "design/cluster-benchmark-plan.md", - "benchmark_ids": [ - "B-CLUSTER" - ], - "role": "engineering evidence", - "tables": [], - "source_csv": [] - }, { "locale": "zh", "page": "design/benchmark-methodology-evidence.md", @@ -370,7 +340,7 @@ { "json": "benchmarks/measurement-coverage.render.json", "kind": "coverage", - "rows": 14, + "rows": 13, "columns": [ "Data status", "Measured scope" @@ -408,16 +378,6 @@ "../../../overrides/assets/benchmarks/data/lazy/lazy-stage-comparisons.csv" ] }, - { - "locale": "en", - "page": "benchmarks/methodology.md", - "benchmark_ids": [ - "B-METHOD" - ], - "role": "user-facing", - "tables": [], - "source_csv": [] - }, { "locale": "en", "page": "benchmarks/network.md", @@ -573,26 +533,6 @@ "tables": [], "source_csv": [] }, - { - "locale": "en", - "page": "design/cluster-performance-analysis.md", - "benchmark_ids": [ - "B-CLUSTER" - ], - "role": "engineering evidence", - "tables": [], - "source_csv": [] - }, - { - "locale": "en", - "page": "design/cluster-benchmark-plan.md", - "benchmark_ids": [ - "B-CLUSTER" - ], - "role": "engineering evidence", - "tables": [], - "source_csv": [] - }, { "locale": "en", "page": "design/benchmark-methodology-evidence.md", diff --git a/crates/pvisor-cli/src/bin/pvisor-replay.rs b/crates/pvisor-cli/src/bin/pvisor-replay.rs index ad0ad3e7..e32d4d4e 100644 --- a/crates/pvisor-cli/src/bin/pvisor-replay.rs +++ b/crates/pvisor-cli/src/bin/pvisor-replay.rs @@ -385,7 +385,7 @@ fn run_managed(config: &ReplayToml) -> Result { ReplayError::configuration(format!("resolve managed replay workspace: {error}")) })?; let mut command = Command::new(&executable); - command.args(["run", "--spec"]).arg(file.path()); + command.args(["run", "--config"]).arg(file.path()); command.current_dir(&working_dir); let status = command.status().map_err(|error| { ReplayError::configuration(format!("start managed pVisor replay: {error}")) diff --git a/docs/README.md b/docs/README.md index 12f8ee9a..334db0c8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -125,9 +125,9 @@ subgroups into their parent group; do not add a third sidebar level. The canonical Chinese documentation uses these sections: - `why/`: the case for pVisor — vision, supervision-bandwidth argument, trust ladder, use cases, comparisons, when not to use. -- `start/`: product scope, installation, the first reproducible Job, and where to go next. +- `start/`: installation and the first reproducible Job, ending with where to go next. - `guides/`: tasks, commands and expected results, grouped by job (`agents/`, `policies/`, `executors/`). -- `concepts/`: the user mental model — jobs, staging, evidence, policy, glossary. +- `concepts/`: the user mental model — jobs, staging, evidence and policy layering. - `benchmarks/`: reproducible measurements and dated comparisons. - `security/`: what is protected, what is not, and how to report issues. - `reference/`: CLI, configuration, schemas and platform support matrices. @@ -247,7 +247,7 @@ it. The models are the uv, Ruff and Ray docs. - Prefer a concrete example over an abstract description; show the command and what it does. - State a guarantee once, on the page that owns it, and link from elsewhere. Never open a page with a disclaimer, and never repeat a caveat in every paragraph. - No meta text: no “本文/本节/本页”, no “继续阅读”, no first line that restates the heading. -- Name the mechanism when it matters; keep terms consistent with the glossary. +- Name the mechanism when it matters; keep terms consistent with the concept page that owns them. - Tables for options, matrices and comparisons; code fences for anything runnable. - Keep article directories in the sidebar. Omit tables that only map topics to documentation links, and do not replace them with equivalent link lists. @@ -261,6 +261,37 @@ it. The models are the uv, Ruff and Ray docs. where its detail becomes relevant instead of duplicating its sections. - A page with no data yet says “建设中” and links to its TODO page instead of making an empty claim. +### Design writing references + +Model the explanation of one mechanism on this sequence: problem and constraints → +minimal system model (who owns state) → the normal path of one real request → +the failure path → tradeoffs → implementation and evidence entry points. The +[design overview](src/zh/design/index.md) follows this order through one +end-to-end task. Each figure answers one reader question: ownership (layered +diagram), one operation (sequence), data placement (layout/map), crash residue +(failure states), or cost (sourced measurement). Figure components must have +corresponding entry points in source or contracts. + +Expression references worth studying, by local topic (accessed 2026-10-07; these +evaluate documentation craft, not project quality): + +| Project and article | What to learn | +| --- | --- | +| [ByteHook · project overview](https://github.com/bytedance/bhook/blob/main/doc/overview.zh-CN.md) | Derive mechanisms from the necessary underlying model; connect objects and calls with figures | +| [TigerBeetle · Architecture](https://github.com/tigerbeetle/tigerbeetle/blob/main/docs/ARCHITECTURE.md) | Start from workload and constraints before persistence and design decisions | +| [Firecracker · Design](https://github.com/firecracker-microvm/firecracker/blob/main/docs/design.md) | Host integration, threads and the device model in one architecture narrative | +| [gVisor · Architecture guide](https://gvisor.dev/docs/architecture_guide/intro/) | Explain the boundary through one syscall example | +| [Tokio · Runtime](https://docs.rs/tokio/latest/tokio/runtime/index.html) | Usage model first, then thread lifetimes and scheduling guarantees | +| [etcd · Client design](https://etcd.io/docs/v3.6/learning/design-client/) | Error and retry semantics for lost ACKs and unknown outcomes | +| [Ray · Architecture whitepapers](https://docs.ray.io/en/latest/ray-contribute/whitepaper.html) | Keep overview and internal topics in separate layers | +| [Rust Compiler Development Guide](https://rustc-dev-guide.rust-lang.org/overview.html) | From pipeline to queries, data structures and source entry points | +| [CockroachDB · Design](https://github.com/cockroachdb/cockroach/blob/master/docs/design.md) | Layered diagrams connecting data abstractions to physical layout | + +Diagrams use the site's dark-blue palette: background `#0d1b30`, cards +`#142840`, accent `#a8cefa`, text `#e9eef8`; teal, amber and dark red mark +sharing, change and conflict states with text labels. Keep SVG text searchable; +split long diagrams into per-topic parts. + The native TOML files own navigation. Maintain paired Chinese and English articles. Keep only current article paths; do not maintain historical redirect maps or compatibility pages. When moving or merging articles, update incoming source @@ -397,51 +428,15 @@ To validate a TOML file without launching an executor: cargo run --locked -p pvisor --example documentation_config -- run.toml ``` -### community/adopters.md - -Measurements, generated references, or formal decisions still need completion. The acceptance criteria below remain required; the page retains its planned status. - -**Acceptance criteria** - -- Publish users and scenarios with consent. -- Distinguish production use from experiments. - -### community/code-of-conduct.md - -**Requirements** - -- Adopt [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) or an equivalent text; -- Specify a reporting channel (dedicated email or maintainers), rather than public issues; -- Describe handling procedures and possible consequences. - -**Acceptance criteria** - -- Add repository-root `CODE_OF_CONDUCT.md` and keep this page consistent; -- Ensure that the reporting channel works and is listed on [Community](index.md). - ### community/governance.md -Measurements, generated references, or formal decisions still need completion. The acceptance criteria below remain required; the page retains its planned status. +The page describes the current single-maintainer process; a formal maintainer list, +charter and conduct reporting channel are not yet established. **Acceptance criteria** -- Define the maintainer list, decision process and advancement path. - Describe the human role in semspec approval. - -### design/decisions/index.md - -**Requirements** - -- Create an ADR template (context, options, decision, consequences, status) and a numbering convention (`NNNN-short-title.md`). -- Backfill the existing key decisions, for example: - - Admission plans stop at `Planned`; enforcement comes only from executor observations. - - Gateway and replay are separated from the core closure as optional features. - - `--safe` does not select an executor and refuses to start rather than degrading when it cannot enforce. - - The human approval process for semantic specifications. - -**Acceptance criteria** - -- At least four numbered ADRs with titles/status. +- Announce the maintainer list, charter and conduct channel on this page once established. ### design/replay.md @@ -456,46 +451,6 @@ Measurements, generated references, or formal decisions still need completion. T - Code/test references per adapter. - Link replay-fidelity results. -### design/research/cluster-execution.md - -**Requirements** - -- Metrics: single-node useful-work density and execution/evidence overhead under fixed resource budgets. -- Controls: native execution and external Kubernetes or Ray orchestration, with pinned versions. -- Workload: independent sandboxes; cross-node placement, retries and workflows remain external. -- Environment: one measured node first; any external multi-node experiment has a separately declared scope. - -**Acceptance criteria** - -- pVisor defines execution semantics without replacing schedulers. -- Distinguish the daemon's implemented VM-only `NativeRuntime` from proposed integrations; require separate prepared-image and end-to-end SDK validation. -- Align claims with measured density; Cluster/controller measurements are not evidence for the node-local daemon. - -### design/research/publications.md - -Measurements, generated references, or formal decisions still need completion. The acceptance criteria below remain required; the page retains its planned status. - -**Acceptance criteria** - -- Link papers/reports/talks. -- State implementation revisions. -- Mark outputs that do not establish product guarantees. - -### design/research/rl-execution-substrate.md - -**Requirements** - -- Metrics: throughput, isolation, reproducibility, fork cost. -- Controls: RL framework sandboxes. -- Workload: fixed rollouts, failure replay, checkpoint forks. -- Environment: pinned model/tools. - -**Acceptance criteria** - -- Integration and scope. -- Tested recording, fork, and prefix replay. -- Separate design from the rollout guide. - ### guides/ci.md **Requirements** diff --git a/docs/overrides/home.html b/docs/overrides/home.html index 5d7a6f83..9a15aa08 100644 --- a/docs/overrides/home.html +++ b/docs/overrides/home.html @@ -15,7 +15,7 @@

{% if zh %}让自主 Agent 的执行可以规模化{% else %}Scaling autonom

{% if zh %}今天：在本机放手运行 Claude Code、Codex 或任意命令，结束后审查改动和证据，只合入你要的部分。{% else %}Today: run Claude Code, Codex, or any command unattended on your machine, then review the changes and evidence and keep only what you want.{% endif %}

{% if zh %}开始第一次运行{% else %}Start your first Run{% endif %} - {% if zh %}理解 PolicyVisor{% else %}Explore the model{% endif %} + {% if zh %}为什么是 pVisor{% else %}Why pVisor{% endif %}
diff --git a/docs/src/en/benchmarks/agent-tasks.md b/docs/src/en/benchmarks/agent-tasks.md index 3ae31ab3..baa00a01 100644 --- a/docs/src/en/benchmarks/agent-tasks.md +++ b/docs/src/en/benchmarks/agent-tasks.md @@ -104,4 +104,4 @@ Claude uses `--bare` with only Bash allowed; Codex uses `--ephemeral` and `dange Complete CSV/JSON and raw records remain in their local cohorts or the documentation data archive. -[Method](methodology.md) · [Reproduction manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) +[Comparison method](index.md#interpretation) · [Reproduction manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) diff --git a/docs/src/en/benchmarks/cluster-scalability.md b/docs/src/en/benchmarks/cluster-scalability.md index 85765c62..5d8e07bd 100644 --- a/docs/src/en/benchmarks/cluster-scalability.md +++ b/docs/src/en/benchmarks/cluster-scalability.md @@ -64,6 +64,35 @@ N=3 independent processes per size; table values are P50, with observed minimum The retired Controller's million-record cohort observed about 8 GiB lifecycle peak and about 14.62 s warm-log replay; neither is a current sizing recommendation. Recovery excludes Worker reconciliation and cold-disk reads. The medians across processes for typed in-memory count calls are about 107–110 ns, describing synthetic state-count calls rather than HTTP/CLI latency; details remain in the complete local statistics. +### Archived readiness probes and Controller index costs {#archive-probes} + +The 2026-10-05 shell/sleep probe grew Worker count and CPU budget together, observing parallel readiness of one to four guests. It answers whether readiness keeps up with added budget, not useful-task throughput under a fixed budget. + +| Live VMs | Total memory P50, MiB | Ready P50, s | Batch readiness rate, VMs/s | +|---:|---:|---:|---:| +| 1 | 92.93 | 3.807 | 0.261 | +| 2 | 178.00 | 3.789 | 0.525 | +| 4 | 342.96 | 4.383 | 0.901 | + +Each level ran one warmup and five measured batches; guests had 128 MiB / one vCPU. Readiness includes CLI/HTTP submission, persistence, scheduling and VM startup; memory is the sum of non-overlapping service cgroups once all guests are ready, not a startup peak. + +The retired Controller's synthetic history queries and retained-record replay (one release process, one CPU, NVMe per level; counts use twenty query samples of one hundred index calls each; RSS and replay have a single observation per level): + +| Retained records | Index count P50, ns | Full-scan reference P50, ms | Process + ID fixture RSS, MiB | Log, MiB | Warm replay, s | +|---:|---:|---:|---:|---:|---:| +| 1,000 | 202.83 | 0.068 | 12.13 | 1.93 | 0.079 | +| 10,000 | 286.78 | 5.254 | 70.59 | 19.33 | 0.388 | +| 100,000 | 129.40 | 20.789 | 658.82 | 193.25 | 1.744 | +| 1,000,000 | 169.47 | 134.204 | 6,540.58 | 1,932.55 | 16.090 | + +RSS includes the ID fixture and allocator retention; warm replay excludes Worker reconciliation and cold-disk recovery; the full scan is an algorithmic reference, not throughput of another Controller build. These figures must not be merged with other cohorts on this page. + +### Retired proposals and the bar for replacements {#retired-proposals} + +These old proposals retired with Controller/Worker, and the archived measurements do not validate them: startup attribution (direct VM versus old dispatch), marginal memory (distinguishing shared base, private working set and offload), useful work under a fixed budget (idle-CPU-release A/B), history scaling (HTTP scheduling throughput), recovery (end-to-end reconciliation) and sustained operation (long-term resource bounds). The memory and density questions remain with the independent B-DENSITY and B-VM-MEMORY probes under their own registries. + +Any replacement experiment needs an independently registered subject and user question, frozen source/binary/input identities, verified whole-process-tree CPU/memory/zero-swap controls, identical workloads, predeclared sample counts and stopping rules, and complete correctness, conflict and recovery checks; failures, unknowns and OOMs are retained; A/B conclusions report paired uncertainty. The protocol is frozen before formal sampling; hypotheses are not approved from exploratory data after the fact. + ### Comparison with existing schedulers {#limits} Matched workloads and common budgets for Kubernetes, Ray and cloud sandboxes are unmeasured, so no numeric ranking is provided. The archived measurements do not size the current daemon or justify replacing a general scheduler. Single-task Docker, Firecracker and QEMU measurements are in the [end-to-end tasks](agent-tasks.md). @@ -72,6 +101,6 @@ Matched workloads and common budgets for Kubernetes, Ray and cloud sandboxes are The five CSVs remain unchanged in the local documentation data archive as historical evidence for retired Controller/Worker artifacts. There is no active Cluster measurement or publishing entry; the [runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) records retirement, not a new reproduction command. -[Comparison method](methodology.md) · [Runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) +[Comparison method](index.md#interpretation) · [Runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) -Derived tables link one raw report to the per-task evidence audit digest. Complete CSV/JSON, raw reports, completion records, service logs, controls, source and binaries stay in local `.data/` or the documentation data archive. Implementation analysis is in the [Cluster technical analysis](../design/cluster-performance-analysis.md). +Derived tables link one raw report to the per-task evidence audit digest. Complete CSV/JSON, raw reports, completion records, service logs, controls, source and binaries stay in local `.data/` or the documentation data archive. Historical figure inputs (`vm.tsv`, `vm-summary.csv`, `controller-summary.csv`, `controller-provenance.tsv`, `manifest.tsv`, `setup-failure.tsv`) are likewise kept in the local archive and are not site downloads. diff --git a/docs/src/en/benchmarks/compare-rl-infra.md b/docs/src/en/benchmarks/compare-rl-infra.md index f2aca2bb..8ec402ac 100644 --- a/docs/src/en/benchmarks/compare-rl-infra.md +++ b/docs/src/en/benchmarks/compare-rl-infra.md @@ -66,4 +66,4 @@ Training throughput, useful-sample success, reward, retries and end-to-end resou Complete CSV/JSON, artifact digests, controls and raw records for each topic remain in their local cohorts or the documentation data archive, retaining provenance and statistical scope. -[Comparison method](methodology.md) · [Reproduction manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) +[Comparison method](index.md#interpretation) · [Reproduction manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) diff --git a/docs/src/en/benchmarks/density.md b/docs/src/en/benchmarks/density.md index 0d5e46e8..ef27d68c 100644 --- a/docs/src/en/benchmarks/density.md +++ b/docs/src/en/benchmarks/density.md @@ -78,6 +78,6 @@ Compressed parked snapshots versus container pause have not completed validation ### Sources and reproduction {#run} -[Comparison method](methodology.md) · [Runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) +[Comparison method](index.md#interpretation) · [Runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) Complete CSV/JSON retains attempts, complete batches, failure reasons, unknowns, OOM, observed ranges and source digests for every condition. It remains with raw records in local cohorts or the documentation data archive; failed batches remain in capacity denominators. diff --git a/docs/src/en/benchmarks/index.md b/docs/src/en/benchmarks/index.md index d41e95c3..d76d2742 100644 --- a/docs/src/en/benchmarks/index.md +++ b/docs/src/en/benchmarks/index.md @@ -10,6 +10,14 @@ | Small workspace or tool execution alone | Compare native workflows and container costs | | VM or concurrent capacity | Require complete tool and resource measurements | +When choosing across configurations, choose execution modes using measured workloads with matching budgets and timing boundaries; use different configurations to understand their individual performance levels. Startup, tool execution, application and resource occupancy answer different questions and cannot substitute for one another. + +| Decision | Required evidence | +|---|---| +| Choose local tool execution | Native, Docker and pVisor host/staged/VM task comparisons | +| Choose an independent guest kernel | Firecracker, QEMU and pVisor startup plus tool data | +| Set capacity or timeouts | Success rates, complete-task waiting and matching resource accounting | + Filesystem measurements cover nine configurations and 19 layered workloads, with three independent environments per cell and three resident rounds, without an interference gate. Of 505 executed environments, 501 pass and 4 resource cells time out; 8 subsequent observations are explicitly skipped. Historical N5/N30 and single-pass tasks remain separate; other topics retain their own cohorts. @@ -18,7 +26,7 @@ Filesystem measurements cover nine configurations and 19 layered workloads, with ## Motivation {#motivation} -Selection requires the total cost of producing the same result, beyond startup or a single command. Review/application, execution boundaries and resource use determine which Agent workflows suit pVisor. +Selection requires the total cost of producing the same result, beyond startup or a single command. Faster startup does not guarantee faster compilation, and writable mounts and staged review provide different workflows; review/application, execution boundaries and resource use determine which Agent workflows suit pVisor. ## Experiment design {#interpretation} @@ -28,15 +36,37 @@ This reuses separately registered [startup](startup.md), [filesystem](filesystem [Lazy images](lazy-image-startup.md) covers file loading through the same host staged executor and separate Docker/lazy VM shell and NumPy startup cohorts. For the matched four-file stage probe, pVisor has shorter cold- and warm-client median waits than OverlayBD; the historical VM comparisons favor lazy for cold clients and Docker for warm clients. Both studies use prepared local services and separate content, metadata and total-response accounting. Their cache states, execution boundaries and budgets remain distinct rather than forming a single ranking. +### Same-host controls and timing + +B-STARTUP, B-FS-TOOLS and B-AGENT-TASK use one offline tool environment and fixed inputs across native, pVisor host/staged/VM, private rootless Docker, Firecracker PCI and QEMU q35/microvm. Images, tools and daemon are prepared beforehand. Every execution uses the same two-core affinity; tool VMs have matching configured memory. Each job gets a fresh workspace, with seeded randomized runtime order. Complete Ubuntu, macOS and distinct binaries remain separate cohorts. + +Downloads, benchmark compilation, image import and input copying are excluded. Timing separates first valid output, internal tools plus validation, returned results and launch-to-process-exit. Successful samples require validated outputs, observed executor and complete staging. Staged modes also verify that original host files remain unchanged. + +### JSON tables and hyperfine {#json-tables} + +Tables load resolved named-row JSON before Markdown rendering. Rendering reads data and executes no benchmark. Direct-command startup and replay cohorts use hyperfine statistics; their input preparation and Python hooks are outside timing. Conditions run independently, without the randomized paired-order claim used by historical campaigns. Historical distributions, correctness counts, capacity and physical-memory readings keep their original measurement scope. Reproduction and remaining workload prerequisites are listed in the [JSON benchmark manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark.new/README.md). + +### Distributions and failures + +Cohorts are not pooled, and slow samples are not removed after measurement. Failures and invalid outputs are counted separately and never treated as zero latency. Capacity guards are not completed jobs. P95 is descriptive: it is omitted below 30 samples. Public P99 is omitted; small cohorts do not support stable tail-latency claims. + +Separated clusters are reported with counts and individual medians. The descriptive split rule is in the [runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md); it establishes no cause. Engineering A/B percentage claims need a 95% bootstrap interval for the median difference; user pages do not narrate optimization work. + +### Isolation and resources {#reference-resources} + +Docker writable bind mounts write directly to the host; pVisor staging retains changes until apply. Firecracker/QEMU use private ext4, while pVisor VM uses virtio-fs with different kernels and devices. This is not a pure VMM or production-security ranking. Standalone staging boundaries follow actual records and [isolation checks](isolation-tests.md). + +RSS sums sampled process scopes and may double-count shared pages or miss short peaks. Docker must include actual container processes and identify its dedicated daemon. Whole-group memory must include all descendants, backing and charged cache, without double-counting overlapping cgroups. Configured RAM, RSS, macOS RAM proxies and net physical memory are distinct metrics. + ## Data and analysis {#results} -The 2026-10-06 startup/filesystem/repair cohorts have 1,440 valid samples and review has 360; the separate 2026-10-07 stock-kernel startup cohort has 240 valid samples. All have zero measured failures. The selected-source filesystem comparison on 2026-10-12 adds 240 valid samples and zero failures, with task-local caches and a common parent resource budget. Cohorts are not pooled; topic pages provide median differences and paired-bootstrap 95% intervals. +The 2026-10-06 startup/filesystem/repair cohorts have 1,440 valid samples and review has 360; the separate 2026-10-07 stock-kernel startup cohort has 240 valid samples. All have zero measured failures. The full startup retest after the reboot on 2026-10-11 is the current cohort (numbers in [Startup](startup.md)); historical randomized-pair cohorts do not carry over. The selected-source filesystem comparison on 2026-10-12 adds 240 valid samples and zero failures, with task-local caches and a common parent resource budget. Cohorts are not pooled; topic pages provide median differences and paired-bootstrap 95% intervals. The separate layered filesystem cohort executes 505 environments: 501 pass, 4 resource cells time out, and 8 subsequent observations are explicitly skipped. Complete tasks and resource boundaries are reported separately. | Question | Measured level (timing is P50) | |---|---| -| [Startup](startup.md) | Stock controls: VM 100.91 ms; Firecracker 285.04 ms; QEMU microvm 321.56 ms; q35 702.98 ms | +| [Startup](startup.md) | 2026-10-11 retest: VM 130.71 ms; Firecracker MMIO 287.13 ms; QEMU microvm 260.10 ms; QEMU 663.25 ms | | [Repair completion](agent-tasks.md) | staged 0.64 s; Docker 0.81 s; VM 3.25 s; QEMU microvm 1.40 s | | [Layered filesystem tasks](filesystem.md#complete-task) | N=3, three publication rounds: VM 11.271 s; VM + writeback 5.928 s; Docker 2.053 s; Firecracker 4.305 s; QEMU q35/microvm 4.065/3.851 s | | [Review workflow](supervision-cost.md) | 10,000 files: stage 141 ms; Git 248 ms; reflink 343 ms | @@ -52,6 +82,28 @@ Net physical-memory savings and useful-task density from compression, trimmed-ke [End-to-end tasks](agent-tasks.md) combines tool waiting, workspace lifecycle and CLI compatibility to analyze Agent sandbox, container, VM and cloud tradeoffs. [Reinforcement learning](compare-rl-infra.md) maps tool costs, active capacity and historical-prefix preparation to rollouts; full training throughput and reward are unmeasured. +### Prepared environments {#reference-env} + +[Startup](startup.md) · [Files and tools](filesystem.md) · [Repair tasks and CLIs](agent-tasks.md). Tables retain cohort identities and counts, with pinned artifacts rather than claims about current third-party releases. + +### Complete distributions {#full-ubuntu} + +Ubuntu uses its distribution kernel, initrd, systemd and private disks; pVisor reuses prepared tool directories. The comparison answers deployment waiting, rather than isolating VMM cost. + +### QEMU complete distributions {#full-ubuntu-qemu} + +q35 and microvm use one Ubuntu template. Their samples and percentiles remain separate from other cohorts. + +### Tasks and resources {#product-v1} + +[Application](supervision-cost.md#apply-cost) · [Network](network.md) · [Concurrency](density.md) · [Isolation](isolation-tests.md) · [Replay](replay-fidelity.md) · [Review](supervision-cost.md). Unmeasured industry alternatives are marked explicitly, without marketing numbers filling gaps. + +### Engineering experiments and data retention {#evidence-format} + +Engineering A/B, instrumented profiles and diagnostic probes remain in [technical analysis](../design/filesystem-performance-analysis.md), outside cross-product main tables. + +Markdown retains user-facing tables, with shared CSV downloads only for necessary user statistics. Static tables already in articles, per-round/per-environment records, historical tables and engineering intermediate tables do not receive additional exports by default. Complete CSV/JSON, raw reports, individual samples, logs, artifact manifests and frozen harnesses remain in their local cohorts or the `benchmark.new/.data/docs-assets-prune-20261018/` documentation data archive, outside the published site. Dynamic JSON is limited to display tables needed by the build; public engineering figures use SVG. See the [runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) for reproduction and retention rules. + ### Measurement coverage of the new framework {#measurement-coverage} This table separates new measurements from historical evidence. Data is updated only when metrics, inputs, configurations and correctness gates match. Ready, normal exit, internal tool timings, memory and correctness do not substitute for one another. Unprepared experiments produce no new numbers; historical conclusions apply to their original cohorts. @@ -66,4 +118,4 @@ Filesystem coverage refers to the nine-mode, 19-workload N3 protocol, with four Complete CSV/JSON and raw records for other topics remain in their local cohorts or the documentation data archive. -[Method](methodology.md) · [Reproduction manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) +[Reproduction manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) diff --git a/docs/src/en/benchmarks/isolation-tests.md b/docs/src/en/benchmarks/isolation-tests.md index 31c2c84c..f68aac4d 100644 --- a/docs/src/en/benchmarks/isolation-tests.md +++ b/docs/src/en/benchmarks/isolation-tests.md @@ -54,4 +54,4 @@ Mount grants, rootfs and configuration determine the boundary; other configurati Complete CSV/JSON and raw records remain in their local cohorts or the documentation data archive. -[Comparison method](methodology.md) · [Runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) +[Comparison method](index.md#interpretation) · [Runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) diff --git a/docs/src/en/benchmarks/measurement-coverage.render.json b/docs/src/en/benchmarks/measurement-coverage.render.json index 8a58b9ce..d3772b2a 100644 --- a/docs/src/en/benchmarks/measurement-coverage.render.json +++ b/docs/src/en/benchmarks/measurement-coverage.render.json @@ -31,10 +31,6 @@ "Data status": "Partially rerun", "Measured scope": "Same host staged executor, four-file lazy loading; N30 cold/warm including fetch and mount; VM application startup retains separate historical data" }, - "[methodology](methodology.md)": { - "Data status": "Historical data", - "Measured scope": "Original metrics and sources retained; no matching new measurements" - }, "[network](network.md)": { "Data status": "Historical data", "Measured scope": "Original metrics and sources retained; no matching new measurements" diff --git a/docs/src/en/benchmarks/methodology.md b/docs/src/en/benchmarks/methodology.md deleted file mode 100644 index fcc712aa..00000000 --- a/docs/src/en/benchmarks/methodology.md +++ /dev/null @@ -1,77 +0,0 @@ -# Which benchmark results support an adoption decision? - -## Main conclusions {#conclusions} - -**Choose execution modes using measured workloads with matching budgets and timing boundaries; use different configurations to understand their individual performance levels.** Startup, tool execution, application and resource occupancy answer different questions. - -| Decision | Required evidence | -|---|---| -| Choose local tool execution | Native, Docker and pVisor host/staged/VM task comparisons | -| Choose an independent guest kernel | Firecracker, QEMU and pVisor startup plus tool data | -| Set capacity or timeouts | Success rates, complete-task waiting and matching resource accounting | - - - -The numbers and conclusions on this page still belong to the original historical cohorts. The new framework has no matching rerun yet; see [measurement coverage](index.md#measurement-coverage). - - - -## Motivation {#motivation} - -Faster startup does not guarantee faster compilation. Writable mounts and staged review also provide different workflows. Adoption decisions require speed, execution boundaries and how changes reach the original directory. - -## Experiment design {#interpretation} - -### Same-host controls - -B-STARTUP, B-FS-TOOLS and B-AGENT-TASK use one offline tool environment and fixed inputs across native, pVisor host/staged/VM, private rootless Docker, Firecracker PCI and QEMU q35/microvm. Images, tools and daemon are prepared beforehand. Every execution uses the same two-core affinity; tool VMs have matching configured memory. Each job gets a fresh workspace, with seeded randomized runtime order. Complete Ubuntu, macOS and distinct binaries remain separate cohorts. - -Downloads, benchmark compilation, image import and input copying are excluded. Timing separates first valid output, internal tools plus validation, returned results and launch-to-process-exit. Successful samples require validated outputs, observed executor and complete staging. Staged modes also verify that original host files remain unchanged. - -### JSON tables and hyperfine {#json-tables} - -Tables load resolved named-row JSON before Markdown rendering. Rendering reads data and executes no benchmark. Direct-command startup and replay cohorts use hyperfine statistics; their input preparation and Python hooks are outside timing. Conditions run independently, without the randomized paired-order claim used by historical campaigns. Historical distributions, correctness counts, capacity and physical-memory readings keep their original measurement scope. Reproduction and remaining workload prerequisites are listed in the [JSON benchmark manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark.new/README.md). - -### Distributions and failures - -Cohorts are not pooled, and slow samples are not removed after measurement. Failures and invalid outputs are counted separately and never treated as zero latency. Capacity guards are not completed jobs. P95 is descriptive: it is omitted below 30 samples. Public P99 is omitted; small cohorts do not support stable tail-latency claims. - -Separated clusters are reported with counts and individual medians. The descriptive split rule is in the [runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md); it establishes no cause. Engineering A/B percentage claims need a 95% bootstrap interval for the median difference; user pages do not narrate optimization work. - -### Isolation and resources {#reference-resources} - -Docker writable bind mounts write directly to the host; pVisor staging retains changes until apply. Firecracker/QEMU use private ext4, while pVisor VM uses virtio-fs with different kernels and devices. This is not a pure VMM or production-security ranking. Standalone staging boundaries follow actual records and [isolation checks](isolation-tests.md). - -RSS sums sampled process scopes and may double-count shared pages or miss short peaks. Docker must include actual container processes and identify its dedicated daemon. Whole-group memory must include all descendants, backing and charged cache, without double-counting overlapping cgroups. Configured RAM, RSS, macOS RAM proxies and net physical memory are distinct metrics. - -## Data and analysis {#results} - -### Prepared environments {#reference-env} - -[Startup](startup.md) · [Files and tools](filesystem.md) · [Repair tasks and CLIs](agent-tasks.md). Tables retain cohort identities and counts, with pinned artifacts rather than claims about current third-party releases. - -### Complete distributions {#full-ubuntu} - -Ubuntu uses its distribution kernel, initrd, systemd and private disks; pVisor reuses prepared tool directories. The comparison answers deployment waiting, rather than isolating VMM cost. - -### QEMU complete distributions {#full-ubuntu-qemu} - -q35 and microvm use one Ubuntu template. Their samples and percentiles remain separate from other cohorts. - -### Tasks and resources {#product-v1} - -[Application](supervision-cost.md#apply-cost) · [Network](network.md) · [Concurrency](density.md) · [Isolation](isolation-tests.md) · [Replay](replay-fidelity.md) · [Review](supervision-cost.md). Unmeasured industry alternatives are marked explicitly, without marketing numbers filling gaps. - -### Filesystem engineering experiments {#filesystem-service} - -Engineering A/B, instrumented profiles and diagnostic probes remain in [technical analysis](../design/filesystem-performance-analysis.md), outside cross-product main tables. - -### Data location and retention {#evidence-format} - -Markdown retains user-facing tables, with shared CSV downloads only for necessary user statistics. Static tables already in articles, per-round/per-environment records, historical tables and engineering intermediate tables do not receive additional exports by default. Complete CSV/JSON, raw reports, individual samples, logs, artifact manifests and frozen harnesses remain in their local cohorts or the `benchmark.new/.data/docs-assets-prune-20261018/` documentation data archive, outside the published site. Dynamic JSON is limited to display tables needed by the build; public engineering figures use SVG. - -See the [runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) for reproduction and retention rules. - -### Sources and reproduction {#run} - -[Comparison method](methodology.md) · [Runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) diff --git a/docs/src/en/benchmarks/network.md b/docs/src/en/benchmarks/network.md index 886c836a..9bc49203 100644 --- a/docs/src/en/benchmarks/network.md +++ b/docs/src/en/benchmarks/network.md @@ -66,6 +66,6 @@ Podman host network supplies an ordinary OCI control. pVisor OCI additionally us ### Sources and reproduction {#run} -[Comparison method](methodology.md) · [Runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) +[Comparison method](index.md#interpretation) · [Runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) Complete CSV/JSON, raw reports, response timings, command logs, input/build receipts and per-invocation output audits remain in their local cohorts or the documentation data archive. diff --git a/docs/src/en/benchmarks/replay-fidelity.md b/docs/src/en/benchmarks/replay-fidelity.md index 52fd76ee..fadfd0bd 100644 --- a/docs/src/en/benchmarks/replay-fidelity.md +++ b/docs/src/en/benchmarks/replay-fidelity.md @@ -62,4 +62,4 @@ These results support structure, argument and observation fidelity for pinned sh Complete CSV/JSON and raw records remain in their local cohorts or the documentation data archive. -[Comparison method](methodology.md) · [Runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) +[Comparison method](index.md#interpretation) · [Runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) diff --git a/docs/src/en/benchmarks/startup.md b/docs/src/en/benchmarks/startup.md index c1dfb006..695c9797 100644 --- a/docs/src/en/benchmarks/startup.md +++ b/docs/src/en/benchmarks/startup.md @@ -168,4 +168,4 @@ The local historical CSV includes an outer shell, taskset and timeout. Its origi Complete CSV/JSON for startup statistics, VM differences and 95% intervals, source and artifact provenance, and raw records remain in their local cohorts or the documentation data archive. See the [startup manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark.new/startup/README.md) to reproduce the current Ready / Exit experiment. -[Method](methodology.md) · [Historical reproduction manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md#explicit-firecracker-kernel-controls) +[Comparison method](index.md#interpretation) · [Historical reproduction manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md#explicit-firecracker-kernel-controls) diff --git a/docs/src/en/benchmarks/supervision-cost.md b/docs/src/en/benchmarks/supervision-cost.md index c0edb1f4..e608f5d9 100644 --- a/docs/src/en/benchmarks/supervision-cost.md +++ b/docs/src/en/benchmarks/supervision-cost.md @@ -165,4 +165,4 @@ Local provenance records binary, source, harness and raw-report digests. Timing ### Sources and reproduction {#run} -[Comparison method](methodology.md) · [Reproduction manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) +[Comparison method](index.md#interpretation) · [Reproduction manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) diff --git a/docs/src/en/cases/index.md b/docs/src/en/cases/index.md index 73704d9c..f414e5d9 100644 --- a/docs/src/en/cases/index.md +++ b/docs/src/en/cases/index.md @@ -60,7 +60,7 @@ just cases --suite use --output target/pvisor-learning-report.json Specifications and the complete Markdown documents containing preparation participate in semspec digests. New cases remain UNREVIEWED: execution success and human semantic approval are separate. After human review of the engine, vocabulary, and cases, add --require-reviewed. Test execution does not approve cases or update the review ledger. -[DOC cases](../reference/cases.md), [VM control cases](../reference/cases-vm.md), STAGE and USE scenarios run through `just cases`, selected with `--suite doc/stage/use/vm`; `just examples` runs examples/pvisor. CI runs existing isolation regressions and network/Gateway mock scenarios alongside this learning path. Retired standalone snapshot hardware records remain historical evidence. Legacy Controller/Worker acceptance records are not validation of the new daemon. Validate native execution restoration separately against the [execution-checkpoint contract](../reference/cli.md#full-vm-execution-checkpoints); the daemon's [runtime boundaries](../guides/daemon/boundaries.md) do not include VM restore. This learning path does not count unexecuted VM/Gateway capabilities as success. +[DOC cases](../reference/cases.md), [VM control cases](../reference/cases-vm.md), STAGE and USE scenarios run through `just cases`, selected with `--suite doc/stage/use/vm`; `just examples` runs examples/pvisor. CI runs existing isolation regressions and network/Gateway mock scenarios alongside this learning path. Retired standalone snapshot hardware records remain historical evidence. Legacy Controller/Worker acceptance records are not validation of the new daemon. Validate native execution restoration separately against the [execution-checkpoint contract](../reference/cli.md#full-vm-execution-checkpoints); the daemon's [runtime boundaries](../guides/daemon/index.md) do not include VM restore. This learning path does not count unexecuted VM/Gateway capabilities as success. The full execution gate currently targets Linux. On macOS, select applicable cases individually; loopback policy differs from Linux namespaces, so the host-loopback refusal checked by S-USE-014 is not a macOS guarantee. diff --git a/docs/src/en/community/adopters.md b/docs/src/en/community/adopters.md deleted file mode 100644 index 33b2240f..00000000 --- a/docs/src/en/community/adopters.md +++ /dev/null @@ -1,28 +0,0 @@ -# Adopters and case studies - -If you are considering pVisor, start with your task type: let a coding agent modify a project, collect candidate changes in CI, or generate scored rollouts in a batch. One small task can establish whether execution, review, and change acceptance fit your workflow. - -No organization case with public authorization is currently registered here. The following are reproducible trial paths; organization names, logos, and production scale require confirmation before publication. - -## Start from your workflow {#start} - -| Scenario | First trial | Results to inspect | -| --- | --- | --- | -| Local coding agent | One small staged change | File diff, tests, and apply selection | -| CI repair | An offline script, then an agent | Failure records, Stage artifacts, and review handoff | -| Parallel agents | Two independent worktrees | Separately traceable results and clear integration | -| RL rollout | One candidate collected and scored | Input version, trajectory, reward, and failure category | - -Follow [CI](../guides/ci.md), [Parallel agents](../guides/parallel-agents.md), or [Rollouts](../guides/rl-rollouts.md). Validate your task before measuring speed and capacity with your actual workload. - -## Share a useful case study {#case} - -Describe the original workflow, problem, pVisor version, platform and executor, agent and model versions, key commands or configuration, and review process. Include a public task input and result, explaining what adoption changed in practice. - -Attach task counts, hardware, and methodology to performance figures. Connect experience claims to concrete actions such as approval counts, consolidated diff review, or conflict handling. Failure cases and subsequent configuration changes are useful too. - -Confirm permission to publish organization names, logos, quotations, and data. Replace private code and credentials with a public reproduction; full logs containing secrets are unnecessary. - -## Case record fields {#fields} - -Record organization or individual attribution, publication permission scope, date, versions, task type, integration, scale, metric definitions, and links to original material. Keep unauthorized cases unnamed and distinguish experimental trials from production use. diff --git a/docs/src/en/community/code-of-conduct.md b/docs/src/en/community/code-of-conduct.md deleted file mode 100644 index 64c65fb3..00000000 --- a/docs/src/en/community/code-of-conduct.md +++ /dev/null @@ -1,26 +0,0 @@ -# Code of conduct - -When discussing implementation, reporting problems, or reviewing contributions, focus on observable behavior and evidence so people with different experience, backgrounds, and communication styles can keep collaborating. - -Formal adoption of the Contributor Covenant and a private conduct-reporting contact have not yet been published. The following provides practical discussion expectations; the formal policy needs maintainer confirmation. - -## Make discussions easier to resolve {#participation} - -- Include versions, platforms, reproductions, or specific passages so others can act on a report. -- Explain the impact and acceptable changes in code review without judging a contributor's ability or identity. -- When views differ, restate the problem both sides need to solve, then compare options and acceptance results. -- Give newcomers necessary context and allow questions, corrections, and uncertainty. - -Insults, harassment, discrimination, threats, disclosure of private information, and persistent personal attacks undermine collaboration. Keep technical disagreement focused on proposals. - -## Responding to inappropriate interactions {#response} - -You can pause a conversation and retain relevant links, timestamps, and records without escalating the conflict. If you already have a private maintainer contact, ask about the appropriate reporting route. Public issues can discuss process improvements, but should not disclose affected people's identities, private messages, or sensitive incident details. - -The project still needs to publish an available private conduct-reporting channel, responsible people, recusal process, and response times. The vulnerability channel is for security vulnerabilities; follow [Disclosure policy](../security/disclosure.md) for those reports. - -## Scope {#adoption} - -These discussion expectations apply to issues, PRs, reviews, and community exchanges. Technical discussions can retain differing views while allowing participants to contribute and receive responses. - -Formal conduct incident handling requires a private channel and responsible people. No dedicated contact is currently published; the repository's vulnerability channel continues to follow the security disclosure policy. diff --git a/docs/src/en/community/governance.md b/docs/src/en/community/governance.md index ca936338..bb868646 100644 --- a/docs/src/en/community/governance.md +++ b/docs/src/en/community/governance.md @@ -1,28 +1,19 @@ # Governance and maintainers -Choose an entry by change size: submit a PR for wording fixes and small issues, and discuss larger interface or behavior changes in an issue with clear acceptance criteria. Report security-boundary vulnerabilities through [private disclosure](../security/disclosure.md). +pVisor is currently decided by a single maintainer: code merges, releases, semspec approvals, and the authoritative documentation all go through the same entry point. There is no formal committee or multi-maintainer voting mechanism. This page describes current practice, not a charter that has yet to be established. -## Current contribution and decision workflow {#workflow} +## How contributions land {#workflow} -1. Describe the user problem, expected behavior, and reproduction. -2. For design changes, explain options, costs, and compatibility effects, with clear acceptance requirements. -3. Submit implementation, matching documentation, and validation, following [Contributing](contributing.md). -4. Reviewers check behavior, evidence, and tests; maintainers with the relevant repository permissions merge and release changes. +1. Describe the user problem, expected behavior, and how to reproduce it; align on the problem and acceptance criteria in an issue first for substantial interface or behavior changes. +2. Submit the implementation, corresponding documentation, and verification results; run the relevant checks per [Contributing](contributing.md). +3. The maintainer reviews behavior, evidence, and tests before merging. Vulnerabilities touching security boundaries use the [private disclosure process](../security/disclosure.md). -Code review, merge permission, and semantic approval are separate responsibilities. Passing PR tests does not automatically approve a product commitment; new public boundaries need matching specifications and human review. +Code review, merging, and semantic-spec approval are handled separately: a passing PR does not automatically approve a product commitment; new user-visible boundaries need corresponding specs and human review. -## Human responsibility for semspec approval {#semspec} +## semspec approval {#semspec} -Contributors can draft cases, fix implementations, and maintain runner tests. Maintainers assess claim accuracy and coverage before approve/revoke actions and approval-record updates. AI does not approve cases, edit real `REVIEWED.toml` or `.approved/` snapshots, or weaken existing checks to obtain PASS. +Contributors may draft cases, fix implementations, and maintain runner tests. semspec approve/revoke and the real `REVIEWED.toml` and `.approved/` snapshots are executed only by the maintainer; AI does not perform approvals and does not weaken existing checks to obtain PASS. See [Testing and semspec](testing.md) for the commands and rules. -Provide source version, environment, results, and limitations with the review. See [Testing and semspec](testing.md) for commands and rules. +## Not yet established {#records} -## Becoming a sustained contributor {#contributors} - -Start with a reproducible problem and maintain a module's implementation, documentation, and regression cases over time. Propose broader responsibilities in a public issue, describing the intended scope and work already completed. - -Repository permissions determine who can merge and release; expanded responsibilities need confirmation from maintainers with that authority. When views differ, collect the disputed points, alternatives, and validation in one issue and request a maintainer decision linked to the resulting change. - -## What governance records should publish {#records} - -Maintainer entries should include accounts, responsibilities, and effective dates. Design decisions should link to issues, PRs, or ADRs; permission and release-responsibility changes should remain recorded. Sensitive security reports follow disclosure procedures, with public records referencing only publishable conclusions. +A formal maintainer list, governance charter, and private conduct-reporting channel have not been established; they will be announced on this page once they are. Until then, design decisions are anchored by issue, PR, or ADR links, and discussion norms are in [Community](index.md). diff --git a/docs/src/en/community/index.md b/docs/src/en/community/index.md index 2f9bdcfb..429d673d 100644 --- a/docs/src/en/community/index.md +++ b/docs/src/en/community/index.md @@ -21,3 +21,11 @@ Keep a PR focused on one change: repair the implementation, add relevant regress Unit and integration tests check implementation. Semspec expresses product commitments as claims, violation examples, and executable checks. You may draft new cases, fix implementations, and maintain runner tests, but must not weaken existing claims, checks, or `xfail` annotations to obtain PASS. Human semantic review is separate from tests and PR merging. AI must not run `semspec approve` / `revoke` or edit real `REVIEWED.toml` or `.approved/` snapshots. See [Testing and semspec](testing.md) for the rules. Contributions are licensed under Apache-2.0. + +## Discussion norms + +Keep discussions about implementation, issue reports, and contribution reviews focused on observable behavior and evidence: include version, platform, and reproduction when reporting a problem; explain impact and acceptable changes when reviewing, without judging a contributor's ability or identity; when disagreeing, first restate the problem each side needs solved, then compare options and verification results. Insults, harassment, discrimination, publishing others' private information, and sustained personal attacks are not acceptable. The project has not yet formally adopted a Contributor Covenant or a private conduct-reporting channel; both will be announced here once established. Report security vulnerabilities through the [disclosure policy](../security/disclosure.md). + +## Trying it out and sharing a case + +No organization case is currently registered here with public authorization; organization names, logos, and production scale are published only after the user's confirmation. If you have tried pVisor, a useful case record includes the original workflow and the problem, the pVisor version, platform and executor, agent and model versions, key commands or configuration, how results were reviewed, and what actually changed after adoption. Attach task counts, machine specs, and measurement methods to performance numbers; failed attempts and the configurations adjusted afterward are equally valuable. Confirm public authorization for names, quotes, and data before submitting, and replace private code and credentials with publicly reproducible material. diff --git a/docs/src/en/community/roadmap.md b/docs/src/en/community/roadmap.md index 525044df..f4ac7815 100644 --- a/docs/src/en/community/roadmap.md +++ b/docs/src/en/community/roadmap.md @@ -1,6 +1,6 @@ # Roadmap -See [Trust ladder](../why/trust-ladder.md) for the levels and scale axes. The table below lists ongoing L1 work (individual local Jobs) and its acceptance criteria. +See [Why pVisor](../why/index.md#trust-ladder) for the levels and scale axes. The table below lists ongoing L1 work (individual local Jobs) and its acceptance criteria. | Work | Acceptance criteria | | --- | --- | @@ -36,7 +36,7 @@ The [daemon](../guides/daemon/index.md) has VM-only `NativeRuntime` embedding pV ## L2 and L3 milestones !!! note "Under construction" - The entry criteria and gap list for L2/L3 are not final, and no schedule is set. The requirements and acceptance criteria below describe the current work. For the level definitions see the [trust ladder](../why/trust-ladder.md); for the capacity rationale see [concurrency density](../benchmarks/density.md). + The entry criteria and gap list for L2/L3 are not final, and no schedule is set. The requirements and acceptance criteria below describe the current work. For the level definitions see the [trust ladder](../why/index.md#trust-ladder); for the capacity rationale see [concurrency density](../benchmarks/density.md). ### L2: multiple local Jobs / one pipeline @@ -49,7 +49,7 @@ Acceptance criteria: ### L3: clustered execution, centralized evidence -Entry criteria (TBD): the boundary with schedulers is defined—pVisor provides execution semantics and evidence, while cross-node orchestration goes to Kubernetes and Ray; see [cluster execution](../design/research/cluster-execution.md). +Entry criteria (TBD): the boundary with schedulers is defined—pVisor provides execution semantics and evidence, while cross-node orchestration goes to Kubernetes and Ray; see [cluster execution](../design/research/index.md). Acceptance criteria: diff --git a/docs/src/en/concepts/capabilities-and-evidence.md b/docs/src/en/concepts/capabilities-and-evidence.md index f94bf20d..04134fc8 100644 --- a/docs/src/en/concepts/capabilities-and-evidence.md +++ b/docs/src/en/concepts/capabilities-and-evidence.md @@ -2,6 +2,10 @@ To judge what a Job actually guarantees, check the requested permissions, admission plans, installed controls and observed outcomes separately. `--safe`, a stage directory, or an executor name alone does not prove that every capability is enforced. +## Policy layering rules {#layering} + +Policies narrow layer by layer: a later `allow` cannot override an earlier explicit `deny`. A layer that declares rules but omits `default_action` denies by default; with no policy configured at all, the network runs public and reads are unrestricted—to restrict them you must declare it. `--safe` requires isolation to be installed and rejects sensitive paths; `--strict` validates every requested dimension and refuses to run without evidence. For fields and presets see the [policy fields reference](../reference/policy.md) (in progress). + ## Check each dimension | Dimension | Check | diff --git a/docs/src/en/concepts/glossary.md b/docs/src/en/concepts/glossary.md deleted file mode 100644 index 42a22767..00000000 --- a/docs/src/en/concepts/glossary.md +++ /dev/null @@ -1,17 +0,0 @@ -# Glossary - -| Term | Meaning | -| --- | --- | -| [Job](jobs.md) | A persistent unit of work in pVisor: command, evidence, and staged changes | -| [Stage](staging.md) | A copy-on-write staging workspace | -| [apply / drop](staging.md) | Selectively merge staged changes into the target / discard them | -| [Run Bundle](../reference/run-bundle.md) | The result, control observations, artifacts, and summary of one run | -| [Capability](capabilities-and-evidence.md) | The request and actual control of one capability dimension (files, network, subprocess, …) | -| [Evidence](capabilities-and-evidence.md) | The controls an executor actually installed and the results observed, not the declaration | -| [Placement](../design/operations-events.md) | The chosen execution location (host / container / VM, and Overlay combinations) | -| Plan level | What the executor plans to install at admission: `Unsupported`, `Cooperative`, `Planned`—not proof it is installed | -| Observed level | What the executor observes at teardown: `Unenforced`, `Cooperative`, `Enforced` | -| [Interception](../guides/policies/network.md) | Network-layer interception of egress traffic (explicit proxy or VM data plane) | -| [L0–L3](../why/trust-ladder.md) | Trust ladder levels | - -For mechanisms and fields, see [design](../design/index.md) and [reference](../reference/index.md). diff --git a/docs/src/en/concepts/index.md b/docs/src/en/concepts/index.md deleted file mode 100644 index fb1ad64e..00000000 --- a/docs/src/en/concepts/index.md +++ /dev/null @@ -1,33 +0,0 @@ -# Concepts and boundaries - -Judge three results separately for each task: whether the command completed, which net file changes it produced, and whether requested restrictions actually took effect. Exit codes, stages, and executor names describe different things and cannot substitute for each other. - -## The Job is the review unit - -A Job associates a managed command with its execution evidence and staged changes. After the command stops, you can still locate it and review the result; a failed command can leave useful candidate files. - -In default storage, `last` searches by current workspace. An explicit `--stage PATH` stores the Job in that directory; use its path or the printed Job ID to avoid selecting the wrong result with custom storage or parallel projects. See [Jobs and storage](jobs.md) for identity and cleanup rules. - -## The file view and publication are separate stages - -With staging enabled, the Job reads workspace lower files combined with its own upper changes. Writes, deletions, and renames change that view first. Review shows the net effect; operation counts are not the final diff. - -Apply compares selected changes against the baseline recorded at first modification before publishing to the original workspace. It refuses to overwrite targets changed by another writer. Stop other writers during publication: multi-file updates are not atomic against external editors. Drop only discards staged changes that have not been applied. See [staging and apply](staging.md) for the full contract and semantic cases. - -Drop cannot undo explicitly shared direct-write host paths, applied batches, or remote API effects. Logical checkpoints save the upper and conflict preimages; they freeze neither every host lower file nor process memory or external service state. - -## Check policy intent separately from installed controls - -```text -Requested permissions → Policy narrowing and admission plan → Installed controls → Observed execution and outcome -``` - -User, workspace, session, and executor base policies narrow permissions layer by layer. An allow in one layer cannot override a deny in another. `Planned` in an admission plan means a mechanism is intended for installation, not that it has been enforced; executor observations at teardown report actual controls. See [policy model](policy-model.md) for policy composition. - -Check file reads, file writes, network, subprocesses, credentials, and resources separately in the Run Bundle. Staging does not prove network isolation, and captured requests do not prove the absence of uncaptured connections. Observations cover only operations reaching their control points; `null` means unobserved, while zero means observed with no hits. See [capabilities and evidence](capabilities-and-evidence.md) for levels and guarantee scope. - -## Records have distinct responsibilities - -`run.json` stores Job identity, state, and local resources; the Run Bundle stores outcomes, control observations, and artifact summaries; an optional Event Journal links published facts and causal references. The Journal replaces neither the Bundle nor a global ordering of external side effects across Jobs. - -These records support local review and diagnosis, not cryptographic remote attestation or hostile multi-tenancy guarantees. See the [execution model](../design/execution-model.md) for ownership of Operation, Attempt, and Session implementations. diff --git a/docs/src/en/concepts/policy-model.md b/docs/src/en/concepts/policy-model.md deleted file mode 100644 index 28d424f2..00000000 --- a/docs/src/en/concepts/policy-model.md +++ /dev/null @@ -1,13 +0,0 @@ -# Policy model - -An execution passes through five steps, each recording something different; they cannot substitute for one another: - -- **Request**: the permissions you declare (`--safe`, `--access`, `--overlaynet-*`, and so on). -- **Admission**: what the selected executor can provide, at most `Planned`. -- **Effective constraints**: the result of intersecting the user, workspace, session, and executor base policies. -- **Installed controls**: which enforcement mechanisms the executor actually installed. -- **Observed results**: the observations the executor reports at teardown—this is the evidence of what actually took effect. - -Policy **narrows layer by layer**: a later `allow` cannot override an earlier explicit `deny`. A layer that declares rules but omits `default_action` denies by default; with no policy configured at all, the network runs public and reads are unrestricted—to restrict them you must declare it. `--safe` requires isolation to be installed and rejects sensitive paths; `--strict` validates every requested dimension and refuses to run without evidence. - -For fields and presets see the [policy fields reference](../reference/policy.md) (in progress); for the evidence definitions see [capabilities and evidence](capabilities-and-evidence.md). diff --git a/docs/src/en/design/agent-task-performance-analysis.md b/docs/src/en/design/agent-task-performance-analysis.md index b6110cb3..d5fd0f32 100644 --- a/docs/src/en/design/agent-task-performance-analysis.md +++ b/docs/src/en/design/agent-task-performance-analysis.md @@ -1,5 +1,7 @@ # Agent tool tasks: technical evidence +> Note: "local original records" and paths such as `docs/src/assets/benchmarks/.data/` refer to local measurement archives that are not published with the repository or the site; they are kept for batch provenance only. + Complete repair/testing takes about **4.61 s** in image-free pVisor VM and **8.51 s** on Firecracker / complete Ubuntu; staging takes **0.72 s**. Ubuntu boot affects short jobs, while pVisor retains substantial tool-execution costs: fast startup does not establish leading tools. Claude/VM: initialization timeout / N=0; real Codex tool-loop results follow below. ## Motivation @@ -18,7 +20,7 @@ These workloads were measured on Linux; macFUSE/FSKit overhead and capacity rema ### Image-free pVisor and complete Ubuntu: full Agent Env {#full-ubuntu} -pVisor reuses installed host Python/Node/Rust/Git/rg/Claude/Codex without making an OS image. Firecracker/QEMU install distribution tools and the same Rust/Agent CLIs in complete official Ubuntu 26.04.1 LTS. Each trial creates a new environment, then runs the same repair plan and tests. VMs use 2 vCPU / 16 GiB; all groups share the two-core budget and warm host caches, with 10 planned samples, 3 warmups and randomized order; cells state effective N when below 10. Ubuntu Python/Node/Git versions differ from the host; full versions and kernel differences are in the [method](../benchmarks/methodology.md#full-ubuntu). +pVisor reuses installed host Python/Node/Rust/Git/rg/Claude/Codex without making an OS image. Firecracker/QEMU install distribution tools and the same Rust/Agent CLIs in complete official Ubuntu 26.04.1 LTS. Each trial creates a new environment, then runs the same repair plan and tests. VMs use 2 vCPU / 16 GiB; all groups share the two-core budget and warm host caches, with 10 planned samples, 3 warmups and randomized order; cells state effective N when below 10. Ubuntu Python/Node/Git versions differ from the host; full versions and kernel differences are in the [method](../benchmarks/index.md#full-ubuntu). ![Complete Ubuntu and image-free pVisor tool loops](../assets/benchmarks/full-ubuntu-qemu-20261004/ubuntu-workflows.svg) @@ -62,17 +64,17 @@ Claude/VM preflight still exceeds 90 seconds during initialization, with formal Codex uses uniform inner `danger-full-access`, with the outer runtime supplying its stated boundary; default nested sandbox compatibility is unmeasured. N=10 gives first-version budgets and repeatability, not long-term tail or real-model success guarantees. RSS sums the launcher tree every 20 ms, including separate Firecracker DNS/NAT support; QEMU uses built-in user networking. Shared pages may be counted twice and short peaks missed. Configured 16 GiB is not 16 GiB resident, and short-task RSS does not establish concurrency capacity. -Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/summary.tsv` · [Method and reproduction](../benchmarks/methodology.md#full-ubuntu) · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/ubuntu-workflows-private-tmp-20261004/evidence.tar.gz` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/ubuntu-clients-console-v2-20261004/evidence.tar.gz` +Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/summary.tsv` · [Method and reproduction](../benchmarks/index.md#full-ubuntu) · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/ubuntu-workflows-private-tmp-20261004/evidence.tar.gz` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/ubuntu-clients-console-v2-20261004/evidence.tar.gz` Complete-Ubuntu repair/testing takes **8.12 s** on q35 and **10.33 s** on microvm, with internal tools taking **2.75 / 2.81 s**. Image-free pVisor reduces waiting for fresh jobs, while its 4.02 s worker time remains above these complete-Ubuntu paths, a priority when environments are reused. Selecting microvm does not automatically improve complete tasks in this configuration. Networking, devices and exposed CPU features differ; the entire difference cannot be assigned to block devices or FUSE. -Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-qemu-20261004/manifest.tsv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-qemu-20261004/summary.tsv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-qemu-20261004/ubuntu-qemu-complete-20261004/evidence.tar.gz` · [QEMU method](../benchmarks/methodology.md#full-ubuntu-qemu) +Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-qemu-20261004/manifest.tsv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-qemu-20261004/summary.tsv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-qemu-20261004/ubuntu-qemu-complete-20261004/evidence.tar.gz` · [QEMU method](../benchmarks/index.md#full-ubuntu-qemu) ### Historical controlled environment: shared tools and trimmed reference VMs {#reference-env} This batch shares tool artifacts to control some version differences. Firecracker/QEMU use trimmed Linux 6.12.109 and static init, without a complete distribution boot. pVisor shares a tool directory through virtio-fs without an image. These results retain Docker and minimal-VM context; see the [complete Ubuntu and image-free hostroot deployment](#full-ubuntu) above. -The deployed environment contains Python 3.14.7, Node 24.18.0/npm, Rust/Cargo 1.98.1, Git, rg, Claude Code 2.1.128, and Codex 0.160.0: about 3.58 GiB and 76,000 files. Native, Docker and VMs use the same tool artifacts, projects and checks. Each case has 30 samples and 3 warmups, a two-core budget, and 2 vCPU / 16 GiB for complete VMs. Full [parameters and boundaries](../benchmarks/methodology.md#reference-env) are stated separately. +The deployed environment contains Python 3.14.7, Node 24.18.0/npm, Rust/Cargo 1.98.1, Git, rg, Claude Code 2.1.128, and Codex 0.160.0: about 3.58 GiB and 76,000 files. Native, Docker and VMs use the same tool artifacts, projects and checks. Each case has 30 samples and 3 warmups, a two-core budget, and 2 vCPU / 16 GiB for complete VMs. Full [parameters and boundaries](../benchmarks/index.md#reference-env) are stated separately. The workflow inspects a project, searches for the bug, repairs Python, runs Python/Rust/Node tests, installs 32 local dependencies, and generates a diff. Fixed model responses request that plan. Real CLIs must return actual passing tool results and exit normally. This covers environment deployment and tool execution, not large repositories, real model success rates or Internet dependency installation. @@ -111,7 +113,7 @@ VM npm installation takes about 1.74 s, its largest phase here; Rust compilation Do not rank Claude against Codex by absolute time. Codex also has seconds of client waiting in this path: roughly 6.26 s in Docker and 10.93 s in pVisor VM. These numbers describe the complete client experience more closely than bare startup, for these versions and controlled tasks, not model speed. -**Deployment is separate.** Offline tool copying, image import and ext4 creation take about 109 s; adding the CPU affinity helper takes another 5.3 s. Downloads and kernel compilation are excluded. Per-run workspace/private-disk preparation is recorded as `prepare_ms`, outside the task table. These are prepared-environment task budgets, not first-install-to-completion costs. See the [memory audit](../benchmarks/methodology.md#reference-resources); 16 GiB configured RAM does not mean each Agent consumes 16 GiB resident memory. +**Deployment is separate.** Offline tool copying, image import and ext4 creation take about 109 s; adding the CPU affinity helper takes another 5.3 s. Downloads and kernel compilation are excluded. Per-run workspace/private-disk preparation is recorded as `prepare_ms`, outside the task table. These are prepared-environment task budgets, not first-install-to-completion costs. See the [memory audit](../benchmarks/index.md#reference-resources); 16 GiB configured RAM does not mean each Agent consumes 16 GiB resident memory. Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/summary.tsv` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/evidence.tar.gz` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/compatibility.tsv` @@ -150,4 +152,4 @@ python3 benchmark/pvisor/product_v1.py \ Start with `--samples 1 --warmups 0` to check prerequisites. Workloads and correctness assertions live in `benchmark/pvisor/v1/`. Reports pin binaries, firmware and harness source with hashes. Failed operations never enter performance distributions. Effective sample counts are stated per page; P95/P99 from small samples describe this batch rather than production tail probabilities. -[Environment, artifacts and method](../benchmarks/methodology.md#product-v1) · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/manifest.tsv` · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/evidence.tar.gz`. Reports retain dirty source status; executable SHA256 identifies the measured artifact. The archive excludes large rootfs/binaries and reproducible workspace payloads, while retaining input hashes and each batch's harness. +[Environment, artifacts and method](../benchmarks/index.md#product-v1) · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/manifest.tsv` · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/evidence.tar.gz`. Reports retain dirty source status; executable SHA256 identifies the measured artifact. The archive excludes large rootfs/binaries and reproducible workspace payloads, while retaining input hashes and each batch's harness. diff --git a/docs/src/en/design/architecture.md b/docs/src/en/design/architecture.md index 57681ab7..19055877 100644 --- a/docs/src/en/design/architecture.md +++ b/docs/src/en/design/architecture.md @@ -23,7 +23,7 @@ There are two responsibilities: **core provides definitions; pvisor provides imp | `pvisor-vm` | VMs, devices, freezing, snapshots and RAM mappings; uniform api and private platform implementations | | `pvisor-replay` | Agent trajectory replay mechanisms; consumes Core/Journal contracts, with frontends in CLI | -The [daemon](daemon/index.md) uses VM-only NativeRuntime: detached supervisors embed `PVisor::run` and retain RunHandles across daemon restart. The executable constructs NativeRuntime with native CLI settings; stage/apply, checkpoint/fork and Gateway APIs are absent, and node sharing is not automatically acquired. See [responsibility convergence](daemon/responsibility-convergence.md). External orchestration owns host choice and workflows. +The [daemon](daemon/index.md) uses VM-only NativeRuntime: detached supervisors embed `PVisor::run` and retain RunHandles across daemon restart. The executable constructs NativeRuntime with native CLI settings; stage/apply, checkpoint/fork and Gateway APIs are absent, and node sharing is not automatically acquired. External orchestration owns host choice and workflows. Core neither owns the execution loop nor starts processes or opens control sockets. pvisor implements AgentCtl clients/servers and approval sockets. Drivers implement file, network and isolation boundaries. The default core does not depend on Gateway, TUI or replay; the `gateway` feature enables capture. @@ -44,7 +44,7 @@ Migrated `api` modules declare public data, fields and trait methods. Opaque own Migration proceeds one crate at a time, updating its consumers, README, public documentation and boundary checks together while preserving external contract coverage. Unmigrated crates should not gain blanket re-export layers or duplicate DTOs merely to appear uniform, nor expose internals to bypass compilation boundaries. Hardware/private-state checks remain inside the crate; callers rely on ownership, lifecycle, post-failure state and synchronization contracts. -This Rust boundary does not automatically establish stable wire protocols or old-record compatibility. CLI `JobCommand`/tickets still require exact build matching, and stored formats have independent readers. See [Records and version matrix](records-and-versions.md) and the VM rationale in [ADR 0005](decisions/0005-rust-vm-api.md). Status follows static inspection of `lib.rs`, VM `runtime_modules.rs`, `api.rs` and directory READMEs; it does not claim fresh contract-test or platform validation. +This Rust boundary does not automatically establish stable wire protocols or old-record compatibility. CLI `JobCommand`/tickets still require exact build matching, and stored formats have independent readers. See [Records and version matrix](records-and-versions.md). Status follows static inspection of `lib.rs`, VM `runtime_modules.rs`, `api.rs` and directory READMEs; it does not claim fresh contract-test or platform validation. ## Host and Guest AgentCtl {#host-agentctl} diff --git a/docs/src/en/design/benchmark-methodology-evidence.md b/docs/src/en/design/benchmark-methodology-evidence.md index b0ded415..c676bdf5 100644 --- a/docs/src/en/design/benchmark-methodology-evidence.md +++ b/docs/src/en/design/benchmark-methodology-evidence.md @@ -1,5 +1,7 @@ # Benchmark measurement protocols and evidence +> Note: "local original records" and paths such as `docs/src/assets/benchmarks/.data/` refer to local measurement archives that are not published with the repository or the site; they are kept for batch provenance only. + All benchmarks follow the same protocol: - State the hardware, operating system, kernel or macOS version, FUSE implementation, pVisor version, and commit. @@ -154,7 +156,7 @@ uv run --no-project --with matplotlib python benchmark/pvisor/render_ubuntu_base --assets target/ubuntu-reference-new --output /tmp/full-ubuntu-report-new ``` -Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/summary.tsv` · [Method and reproduction](../benchmarks/methodology.md#full-ubuntu) +Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/summary.tsv` · [Method and reproduction](../benchmarks/index.md#full-ubuntu) See the Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/ubuntu-packages.txt`. Formal tasks uniformly place compiler/client temporary files in private workspace `_tmp` to accommodate hostroot read-only `/tmp`. Failed diagnostics are retained outside the new formal distributions. diff --git a/docs/src/en/design/cli.md b/docs/src/en/design/cli.md index 664ecd30..a6e058d4 100644 --- a/docs/src/en/design/cli.md +++ b/docs/src/en/design/cli.md @@ -87,7 +87,7 @@ pvisor-daemon memory-pool --help Use `pvisor-daemon` directly for sandbox lifecycle and optional pool ownership. The cache, replay and TUI remain separate from Job commands; replay/TUI companion lookup reports missing tools explicitly. The daemon CLI constructs the native VM runtime and dispatches supervisors, with synchronous internal VM dispatch before Tokio. Node resource protocols belong to the runtime and have no daemon acquire/release adapter. Packaging does not expose staging/checkpoint APIs or automatically acquire node resources. -Tools come from a static table and only a trusted installation directory; discovery neither searches PATH nor executes companions. The directory/executables belong to the current user or root, must not be group/world writable, and reject symlinks. Unix `exec` preserves argv, stdio, signals and exit codes. Tool `--help`/`--version` arguments pass through unchanged, and tools cannot shadow Job commands. See [daemon operations](daemon/operations.md) for sandbox deployment and [responsibility convergence](daemon/responsibility-convergence.md) for separate native resource budgets. +Tools come from a static table and only a trusted installation directory; discovery neither searches PATH nor executes companions. The directory/executables belong to the current user or root, must not be group/world writable, and reject symlinks. Unix `exec` preserves argv, stdio, signals and exit codes. Tool `--help`/`--version` arguments pass through unchanged, and tools cannot shadow Job commands. See the [daemon architecture](daemon/index.md) and [operations](daemon/operations.md) for sandbox deployment and native resource budgets. The default core build excludes Gateway. Use `--features gateway` for capture; wheel builds enable it. Without capture, OverlayNet still authorizes and forwards ordinary explicit proxy traffic. Requesting uncompiled capture or Gateway debug capabilities returns an error. diff --git a/docs/src/en/design/cluster-benchmark-plan.md b/docs/src/en/design/cluster-benchmark-plan.md deleted file mode 100644 index cd09ce94..00000000 --- a/docs/src/en/design/cluster-benchmark-plan.md +++ /dev/null @@ -1,41 +0,0 @@ -# Retired Cluster benchmark plan - -**The Controller/Worker experiment plan is retired, not transferred to the daemon.** B-CLUSTER has no active runner or acceptance protocol. The [historical measurements](../benchmarks/cluster-scalability.md) answer questions only about their frozen artifacts; they do not validate the proposals below or current daemon density. - -## Existing evidence {#existing} - -The [technical archive](cluster-performance-analysis.md) distinguishes growing-budget readiness probes, synthetic history queries and the independent completed-task cohort. Readiness is not completion throughput; fixture RSS is not net control-plane memory; warm replay is not full recovery. Historical tables, CSVs and raw `.data/` remain in their original cohorts, without relabeling or new measurements. - -## Startup attribution proposal {#q1} - -Comparing direct VM execution with old Cluster dispatch was an unfulfilled attribution proposal, not a current Controller/Worker experiment. Old debug, release and quota configurations cannot be subtracted to infer scheduling cost. - -## Marginal-memory proposal {#q2} - -Separating shared bases, private working sets and offload recovery remains a measurement question, not a proven Cluster density benefit. Independent B-DENSITY and B-VM-MEMORY probes continue under their own registry entries and receipts. Single-VM reclaimed memory cannot be converted into daemon capacity. - -## Fixed-budget useful-work proposal {#q3} - -The proposed model-wait/CPU-release A/B was not validated by shell readiness or by the separate Python/Git completion cohort. The retired `release_cpu_on_idle` path is not an active measurement target. No current effective-Agent-throughput or unit-cost claim follows. - -## History-scaling proposal {#q4} - -Archived count calls and retained-record replay do not establish HTTP scheduling throughput, large active-set behavior or current daemon history costs. No old scheduler example is an active measurement entry. - -## Recovery proposal {#q5} - -The old Controller/Worker reconciliation experiment is retired. Local warm-log replay cannot establish end-to-end recovery, convergence under partition or exactly-once execution. No safety claim or receipt is weakened by retiring the experiment. - -## Sustained-operation proposal {#q6} - -Short probes cannot establish bounded long-term resource use. The former persistent-Worker plan is not a current daemon reliability or retention test. - -## Requirements for any replacement experiment {#protocol} - -A replacement needs its own registered subject and user question, frozen source/binary/input identities, verified whole-tree CPU/memory/zero-swap controls, identical workloads, declared sample counts and stopping rules, and complete correctness, conflict and recovery checks. Retain failures, unknown outcomes and OOMs. Keep independent batches and correlated in-batch observations distinct; use paired uncertainty for A/B claims. Freeze the protocol before formal sampling, and never retrospectively approve a hypothesis from exploratory data. - -These requirements do not authorize a new measurement or semantic approval. Human-reviewed claims, receipts, semspec checks and approval records remain unchanged. - -## Current scope {#priority} - -There is no executable Cluster priority list or reproduction command. Use [local capacity](../benchmarks/density.md) and [VM memory](../benchmarks/vm-memory/index.md) only within their documented native-probe scope. Daemon density, multi-host scalability and matched scheduler comparisons remain unmeasured. The [runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) lists the retired entries and independent active probes. diff --git a/docs/src/en/design/cluster-performance-analysis.md b/docs/src/en/design/cluster-performance-analysis.md deleted file mode 100644 index ccd42e1b..00000000 --- a/docs/src/en/design/cluster-performance-analysis.md +++ /dev/null @@ -1,38 +0,0 @@ -# Retired Cluster performance evidence - -**Controller/Worker measurements describe retired artifacts, not the current daemon.** B-CLUSTER has no active measurement, plotting or publication entry. The [historical benchmark](../benchmarks/cluster-scalability.md) preserves completed-task and history tables with their original CSV provenance. No new measurements or daemon-density conclusions are added. - -## Historical VM readiness probes {#execution} - -The 2026-10-05 shell/sleep experiment increased both Worker count and CPU budget, using one independent Worker per VM. It observed parallel readiness for one to four guests, not fixed-budget useful-task throughput or single-Worker density. - -![Historical retired-Worker readiness probe](../assets/benchmarks/cluster-scalability-20261005/execution.svg) - -| Live VMs | Total memory P50, MiB | Readiness P50, s | Burst readiness rate, guests/s | -|---:|---:|---:|---:| -| 1 | 92.93 | 3.807 | 0.261 | -| 2 | 178.00 | 3.789 | 0.525 | -| 4 | 342.96 | 4.383 | 0.901 | - -Five measured batches per size followed one warmup. Guests used 128 MiB/one vCPU; each Worker and descendants had 512 MiB/0.5-core caps, and Controller 256 MiB/0.25 core, with zero swap. The shared Linux/KVM host used prepared minimal inputs and debug artifacts; other host workloads continued. Readiness includes submit CLI/HTTP, persistence, scheduling and VM startup. Memory is the sum of non-overlapping service cgroups while all guests are ready, not startup peak. Charts show observed ranges, not confidence intervals. These observations do not establish production capacity, tail latency, shared-working-set benefits or current daemon performance. - -## Historical Controller costs {#controller} - -| Retained records | Indexed counts P50, ns | Full-scan reference P50, ms | Process + ID fixture RSS, MiB | Journal, MiB | Warm replay, s | -|---:|---:|---:|---:|---:|---:| -| 1,000 | 202.83 | 0.068 | 12.13 | 1.93 | 0.079 | -| 10,000 | 286.78 | 5.254 | 70.59 | 19.33 | 0.388 | -| 100,000 | 129.40 | 20.789 | 658.82 | 193.25 | 1.744 | -| 1,000,000 | 169.47 | 134.204 | 6,540.58 | 1,932.55 | 16.090 | - -The archived `controller-indexes-20261005-v3-history-*` results used one release process per size, one CPU, NVMe and warm replay. There was one ready record and otherwise cancelled history, without guest execution or HTTP load. Counts used twenty query samples, with one hundred indexed calls per sample; RSS and replay had one observation per size. RSS includes the ID fixture and allocator retention. Warm replay excludes Worker reconciliation and cold-disk recovery. The scan is an algorithm reference, not another Controller binary's throughput. Do not merge this cohort with the independent later history cohort in the historical benchmark. - -## Evidence boundaries {#limits} - -The readiness and query observations remain historical descriptions of their frozen implementations. They provide no current optimization priority, daemon sizing recommendation or scheduler/runtime ranking. Local [capacity](../benchmarks/density.md) and [VM memory](../benchmarks/vm-memory/index.md) have independent subjects and retained evidence; single-VM memory reclamation does not establish concurrent density. The [retired plan](cluster-benchmark-plan.md) records the boundary between old proposals and measured claims. - -## Retention, not active reproduction {#reproduce} - -`cluster_scalability.py`, `cluster_worker.py`, `controller_history.py`, their dedicated tests, `plot_cluster_scalability.py` and `publish_controller_history.py` are removed. There is no current build/run/publish command for the retired scheduler example. Original logs, samples, manifests and frozen harnesses remain local under `.data/`; retained copies are archives, not active entry points. Removal of old crate measurements does not authorize rewriting receipts or assigning those measurements to daemon source. - -Historical chart inputs are recorded under `docs/src/assets/benchmarks/.data/cluster-scalability-20261005/`: `vm.tsv`, `vm-summary.csv`, `controller-summary.csv`, `controller-provenance.tsv`, `manifest.tsv` and `setup-failure.tsv`. These are local provenance locations, not public download links. The [runner manual](https://github.com/DeepLink-org/pvisor/blob/main/benchmark/pvisor/README.md) documents retirement and the independent active native probes. diff --git a/docs/src/en/design/daemon/admission.md b/docs/src/en/design/daemon/admission.md deleted file mode 100644 index dea9ef21..00000000 --- a/docs/src/en/design/daemon/admission.md +++ /dev/null @@ -1,45 +0,0 @@ -# Local sandbox admission - -Bound accepted sandbox resources on one machine before native VM creation. The daemon admits hard-limit sums; it does not queue work, choose hosts or infer spare capacity from a low RSS sample. - -## Request validation {#model} - -Creation requires a local prepared-image key in `image.uri`, nonempty argv and `resourceLimits` containing exactly `cpu` and `memory`. CPU accepts whole/fractional cores or millicores; memory accepts bytes and supported decimal/binary suffixes. Quantities must be positive, exactly representable and checked for overflow. - -```json -{ - "image": {"uri": "prepared-agent-1.1.0"}, - "entrypoint": ["sleep", "600"], - "resourceLimits": {"cpu": "500m", "memory": "256Mi"}, - "timeout": 600, - "metadata": {"purpose": "local-example"} -} -``` - -This is a request-shape example, not a validated image recipe. The manifest `entrypoint` bootstrap must supervise these arguments and the required services; [operations](operations.md#image-contract) defines that contract. No image is pulled during creation. - -Optional platform selection must match the native Linux architecture. Unsupported snapshots/templates, resource requests, network policy, credential proxy, secure access, volumes, image authentication, lifecycle hooks and nonempty extensions fail before native creation. Environment and metadata maps are bounded and validated. - -## Capacity accounting {#admission} - -| Bound | Admission rule | -| --- | --- | -| Sandbox count | Registry record count must remain within `max_sandboxes` | -| CPU | Sum of all records' `cpu_millis` plus the request must fit configured capacity | -| Memory | Sum of all records' `memory_bytes` plus the request must fit configured capacity | - -The serialized durable insertion is the reservation barrier. Concurrent creations cannot both spend the same capacity. Refusal returns `429 CAPACITY_EXCEEDED`, not an assignment for later execution. There are no tenant quotas or authenticated per-tenant resource accounts. - -Paused, terminated, failed and uncertain records retain their full CPU/memory/count charge until explicitly deleted or failed creation has verified cleanup. Pause does **not** release logical CPU. Native deletion and absence confirmation precede durable record removal; unknown cleanup cannot create reusable capacity. - -## Installed controls and physical memory {#reservations} - -Requires Linux x86_64, usable `/dev/kvm`, trusted absolute paths and a writable delegated cgroup v2 hierarchy with enabled CPU/memory/PID controllers and `cgroup.kill`. Preflight checks real controller writes and the KVM API; there is no host, OCI command or registry-pull fallback. - -The native supervisor embeds `pvisor::PVisor` with only `VmExecutor` and holds its RunHandle in a detached subprocess. The sandbox cgroup caps the entire supervisor/VMM/helper tree: aggregate CPU rate **10–8000 millicores**, hard memory, zero swap, `pids.max=512` and group OOM. vCPU count rounds quota up to whole CPUs (at most 8); guest RAM rounds down to MiB, while the hard memory cap also includes host overhead. Full limit/readiness checks remain at create, Inspect and resume; endpoint lookup authenticates live Running state and deletion fences without repeating full health/cgroup checks per data request. See [service access](lifecycle.md#endpoints). Paused, failed and uncertain records retain conservative admission charges. - -The launch callback joins the identity-bound cgroup **before exec**, using a pre-opened `cgroup.procs` FD under the owner lock and checking started/deletion/tombstone markers. Supervisor startup verifies membership instead of moving an already-running Tokio process; supervisor/Tokio allocations and subsequent VM/helper children are charged inside the sandbox budget. Direct hidden-command invocation outside that cgroup fails closed. - -Logical admitted sums, installed supervisor/VM-tree limits and whole-node physical occupancy are different quantities. Daemon, helpers, caches and the host need headroom outside sandbox limits. There is no implicit CPU/RAM overcommit, pressure-based admission or measured node-wide physical budget. Native [shared working sets](shared-working-set.md) do not authorize lower daemon reservations. - -Validation and arithmetic live in `daemon/models.rs`; serialized reservation insertion lives in `daemon/mod.rs`; native KVM/cgroup preflight and controls live in `runtime.rs`. diff --git a/docs/src/en/design/daemon/index.md b/docs/src/en/design/daemon/index.md index 0d841519..f4a6c626 100644 --- a/docs/src/en/design/daemon/index.md +++ b/docs/src/en/design/daemon/index.md @@ -19,23 +19,88 @@ Manage local sandboxes through `pvisor-daemon`: one process accepts resource-bou The Runtime trait has one implementation: VM-only NativeRuntime. Detached supervisors embed `pvisor::PVisor` with only VmExecutor and retain RunHandles across daemon restart. No host/OCI/pull fallback exists. The executable's `serve` command constructs NativeRuntime using required `--images-dir`/`--cgroup-root`; synchronous internal VM dispatch runs before Tokio, and the hidden supervisor command is dispatched. See [operations](operations.md#deployment). -## Create and access {#task-flow} +Responsibility convergence means assigning every node-local resource a clear owner, not merging every service into the daemon process: sandbox lifecycle, native immutable backing and unlosable live RAM have different authorities and failure boundaries. Shipping in one package, a unified entry point or fewer ports cannot substitute for the missing runtime adapters, and establishes neither faster startup, lower memory nor higher density. Define acquisition, cancellation, termination and pin-release contracts before wiring a new path, and evaluate through fixed-budget measurement; convergence does not establish live-VM takeover, shared cold-pool arbitration, automatic node acquisition or density advantages. -1. Validate the image, argv, environment, metadata, hard CPU/memory limits and optional TTL. Reject unsupported controls before admission. -2. Under registry serialization, check local capacity and durably insert a random `sb-*` identity, reservation and `Pending` record. -3. Persist native preparation/identity, install identity-bound cgroup limits, place the child in that cgroup before exec, launch the detached supervisor and verify acknowledged live VM controls plus real service readiness. -4. Persist `Running` only after native creation succeeds. Verified failed-create cleanup releases the record; uncertain cleanup retains its identity and reservation. -5. Resolve supported service endpoints through the daemon. Inspect reconciles native state; deletion persists intent and confirms native absence before releasing capacity. +## Admission and capacity accounting {#admission} -This is sandbox management, not a task/result protocol. Private runtime records bind generation to native Run/Attempt IDs, but `sb-*` is not a public Job ID and the API does not expose Job review, checkpoints or Run Bundle export. +Before creating native VMs, bound the total resources of accepted sandboxes on the node. The daemon admits by the sum of hard limits; it does not queue, choose hosts, or infer available capacity from low RSS samples. + +Creation must provide a local prepared-image key in `image.uri`, a non-empty argv, and a `resourceLimits` containing only `cpu` and `memory`. CPU accepts integer/decimal cores or millicores; memory accepts bytes and supported decimal/binary suffixes. Amounts must be positive, exactly representable and overflow-checked. An optional platform must match the local Linux architecture. Unsupported snapshot/template, resource requests, network policy, credential proxy, secure access, volumes, image auth, lifecycle hooks and non-empty extensions fail before native creation. Environment and metadata maps are bounded and validated. + +```json +{ + "image": {"uri": "prepared-agent-1.1.0"}, + "entrypoint": ["sleep", "600"], + "resourceLimits": {"cpu": "500m", "memory": "256Mi"}, + "timeout": 600, + "metadata": {"purpose": "local-example"} +} +``` + +This is a request-shape example, not a validated image recipe; no image is pulled during creation. + +| Boundary | Admission rule | +| --- | --- | +| Sandbox count | Registry records must not exceed `max_sandboxes` | +| CPU | The sum of `cpu_millis` over all records plus the new request must fit the configured capacity | +| Memory | The sum of `memory_bytes` over all records plus the new request must fit the configured capacity | + +Serialized durable insertion is the reservation barrier: concurrent creations cannot double-spend capacity. Rejection returns `429 CAPACITY_EXCEEDED`; no pending allocation is produced. There are no tenant quotas or authenticated per-tenant resource accounts. Paused, Terminated, Failed and uncertain records keep their full CPU/memory/count charges until explicit deletion or verified failed-create cleanup. Pause does **not** release logical CPU. + +Logical admission totals, installed limits on each supervisor/VM tree and node-wide physical occupancy are different quantities. The daemon, helpers, caches and host need headroom beyond sandbox limits. There is no implicit CPU/RAM oversubscription, pressure-based admission or measured node-wide physical budget. Native [shared working sets](shared-working-set.md) do not authorize lowering daemon reservations. + +## Actual controls and physical memory {#reservations} + +You need Linux x86_64, a usable `/dev/kvm`, trusted absolute paths, and a writable, delegated cgroup v2 hierarchy with the CPU/memory/PID controllers and `cgroup.kill` enabled. Preflight checks verify real controller writes and the KVM API; there is no host, OCI-command or registry-pull fallback. + +The native supervisor embeds `pvisor::PVisor` in a separate child process outside the daemon's lifecycle, configures only `VmExecutor`, and holds the RunHandle. The sandbox cgroup limits the whole supervisor/VMM/helper tree: total CPU rate **10–8000 millicores**, hard memory, zero swap, `pids.max=512` and group OOM. vCPU count rounds the quota up (at most 8); guest RAM rounds down to MiB; the hard memory limit also covers host-side overhead. Full limit/readiness checks remain at create, Inspect and resume; endpoint resolution authenticates the live Running state and checks deletion fences, without repeating full health/cgroup checks per data request. + +The startup callback checks started/delete/tombstone markers under the owner lock and joins the identity-bound cgroup **before exec** through a pre-opened `cgroup.procs` FD. The supervisor verifies membership at startup and does not migrate already-running Tokio processes; supervisor/Tokio allocations and later VM/helper children all count toward the sandbox budget. Invoking the hidden command outside that cgroup fails closed. + +## Lifecycle controls {#control} + +Confirm node-local native state before reporting control completion or releasing resources. The daemon serializes operations per sandbox; operations on different sandboxes proceed independently. + +| Operation | Durable/native order | Response | +| --- | --- | --- | +| Create | Persist `Pending` and reservation → create/start → verify configuration and service readiness → persist `Running` | 202 JSON | +| Pause | Query → persist `Pausing` → acknowledged vCPU pause → confirm Paused → persist `Paused` | 202 empty body | +| Resume | Query → persist `Resuming` → acknowledged vCPU resume and readiness → confirm Running → persist `Running` | 202 empty body | +| Delete | Persist `Stopping` → confirm native absence and hold the owner lock exclusively → publish tombstone → reclaim cgroup/private run storage → confirm Missing → durably remove the registry record | 204 | + +Pause/resume return the live state in an authenticated native acknowledgement; the daemon consumes it without a second post-control Inspect. When the target state is already observed, success may be returned without repeating native control; a native error is never a control success. Accepted lifecycle operations run in self-owned async tasks; HTTP disconnects do not cancel them. Losing a create response is not an idempotent-retry contract; blind resubmission may create another sandbox. + +Private IPC verifies same-UID peer, owner, sandbox ID, generation and a secret token; persistent identity binds the boot ID and cgroup device/inode. IDs are never reused or restarted. IPC loss means unknown, not Missing or cleanup evidence. Persistent delete intent and the supervisor's exclusive lock block late starts; cleanup uses identity-bound `cgroup.kill`, never stores PIDs or kills by PID, and releases capacity only after the cgroup is empty and the owner lock is released. A replaced or lost cgroup without persistent tombstone evidence under the same boot does not prove the object is absent. + +Cleanup uses ownership binding and does not depend on image/startup validation; a removed rootfs/firmware does not block it. The persistent tombstone supports retrying interrupted reclamation and ends with a minimal ID barrier. Cleanup errors retain the reservation. See [storage](storage.md#gc). + +## Expiration {#expiration} + +An omitted/null timeout means manual cleanup. A TTL is at least 60 seconds and bounded by the configured maximum (default one day, maximum one year). Renewal supplies a future RFC3339 time within the cap; an existing deadline must be extended, and expired or non-renewable states are rejected. + +Maintenance scans once per second with at most eight concurrent cleanup tasks. Cleanup rechecks expiration under the same lock as renewal, so a stale scan cannot delete a renewed sandbox. Pending delete intent is retained and retried after cleanup failures. + +TTL is best-effort cleanup, not a hard execution deadline. Slow native commands, upload/header waits and same-sandbox controls delay deletion. New proxy requests are rejected after expiration; established response streams have no total timeout. Maintenance stops while the daemon is down; stronger deadlines need independent host supervision. + +## Service access and concurrency {#endpoints} + +Only execd 44772 and egress 18080 are published. Endpoint discovery and every data request's endpoint resolution authenticate the live supervisor, require the current RunHandle to be Running, check deletion fences and resolve the current publication, without trusting persisted observation caches. Discovery returns a daemon-routed authority and does not expose supervisor loopback addresses. Resolution does not repeat service health probes or full cgroup reconciliation per data request. Create, Inspect and resume retain full configuration/readiness checks; upstream connection failures are handled by the API adapter and are not readiness evidence. Proxy connection establishment shares the lifecycle lock with control/deletion, so daemon-managed deletion or port reuse cannot race a connection. + +The proxy streams real upstream command/file/health/metrics traffic, including multipart and SSE. Upload plus response-header wait is capped at 120 seconds; established responses have no total timeout. WebSocket, CONNECT and arbitrary application ports are unsupported. Traffic/output quotas belong to the upstream services. ## Concurrency and failure boundaries {#documents} The [registry commit lock](storage.md#commit) serializes capacity checks and durable mutations. A per-sandbox lifecycle lock orders controls and proxy connection establishment; slow VM operations do not hold a global runtime mutex. This keeps unrelated sandboxes moving while preventing two creations from spending the same reservation or a connection from racing daemon-managed deletion. -Durable intentions and live observations have different authority. Persist `Stopping` before native deletion, and release capacity only after absence is confirmed. Lost IPC or an acknowledgement leaves work to reconcile; it cannot authorize a replacement VM or reusable capacity. A [daemon-only restart](state-and-recovery.md#reconcile) reconnects surviving supervisors using the same ownership state. Host reboot loses live VMs. +Durable intentions and live observations have different authority. Persist `Stopping` before native deletion, and release capacity only after absence is confirmed. Lost IPC or an acknowledgement leaves work to reconcile; it cannot authorize a replacement VM or reusable capacity. A [daemon-only restart](storage.md#reconcile) reconnects surviving supervisors using the same ownership state. Host reboot loses live VMs. + +Conservative reservations trade utilization for explicit cleanup accounting: paused, failed and uncertain records remain charged until verified removal. Low RSS and native cache sharing do not reduce those reservations; admission and physical working-set accounting remain separate. + +## Independent execution semantics {#integration} + +Native pause/resume controls the same Attempt's live vCPUs through the RunHandle; it is not cgroup freeze, memory offload, checkpoint/restore or VM reconstruction. Admission accounting is retained. Execd forwarding is not Gateway routing, capture or inference-idle CPU release. -Conservative reservations trade utilization for explicit cleanup accounting: paused, failed and uncertain records remain charged until verified removal. Low RSS and native cache sharing do not reduce those reservations; [admission](admission.md#reservations) and physical working-set accounting remain separate. +Ordinary Jobs keep their independent [checkpoint/fork semantics](../execution-model.md). The daemon cannot stage/apply files, restore native VM state, acquire node backing or coordinate model responses. Wiring those paths requires explicit adapters with lifecycle/evidence contracts, not renaming the retired distributed control. ## Compatibility and evidence {#invariants} @@ -43,4 +108,4 @@ The partial API profile is pinned to **OpenSandbox 1.1.0**, `release-1.1.0`, com Native VM execution is wired in the runtime. Stage/apply, checkpoint/fork and offload APIs, Gateway inference-wait coordination and automatic node-resource acquisition are not implemented. Historical Cluster results do not validate daemon SDK conformance, performance or density; no node-wide physical-memory gain is established. -Implementation ownership: `crates/pvisor-daemon/src/daemon/{models,store,mod,api}.rs`, `runtime.rs` and `main.rs`. The retired Cluster implementation is not this architecture. +Implementation ownership: `crates/pvisor-daemon/src/daemon/{models,store,mod,api}.rs`, `crates/pvisor-daemon/src/runtime.rs` and `crates/pvisor-daemon/src/main.rs`. Validation and resource arithmetic live in `daemon/models.rs`; serialized reservation insertion and lifecycle orchestration in `daemon/mod.rs`; native KVM/cgroup preflight and controls in `runtime.rs`; streaming forwarding in `daemon/api.rs`. The retired Cluster implementation is not this architecture. diff --git a/docs/src/en/design/daemon/lifecycle.md b/docs/src/en/design/daemon/lifecycle.md deleted file mode 100644 index 5576de5f..00000000 --- a/docs/src/en/design/daemon/lifecycle.md +++ /dev/null @@ -1,42 +0,0 @@ -# Sandbox lifecycle - -Confirm local native state before reporting a completed control or releasing resources. The daemon serializes operations per sandbox, while unrelated sandbox operations can progress independently. - -## Creation and controls {#control} - -| Operation | Durable/native sequence | Response | -| --- | --- | --- | -| Create | Persist `Pending` and reservation → create/start → verify configuration and service readiness → persist `Running` | 202 JSON | -| Pause | Inspect → persist `Pausing` → acknowledged vCPU pause → confirm Paused → persist `Paused` | 202 empty | -| Resume | Inspect → persist `Resuming` → acknowledged vCPU resume and readiness → confirm Running → persist `Running` | 202 empty | -| Delete | Persist `Stopping` → confirm native absence and exclusive owner lock → publish tombstone → reclaim cgroup/private run storage → confirm Missing → durably remove registry record | 204 | - -Pause/resume return the confirmed live state in the authenticated native acknowledgement; the daemon consumes it without issuing a second post-control Inspect. Resume confirmation includes readiness and enforcement checks. Lost acknowledgements or unexpected states retain the durable transition intention for reconciliation and do not prove that the control was unapplied. - -An already observed desired pause/resume state can return success without another native control. Native errors cannot be treated as successful controls. Accepted lifecycle operations run in owned asynchronous tasks: an HTTP disconnect does not cancel them. A lost create response is not an idempotent retry contract; blindly resubmitting can create another sandbox. - -Private IPC authenticates same-UID peers plus owner, sandbox ID, generation and secret token; durable identity binds boot ID and cgroup device/inode. IDs are never reused or relaunched. Lost IPC is uncertainty, not Missing or cleanup proof. Durable deletion intent and the supervisor exclusive lock fence late launch; cleanup uses identity-bound `cgroup.kill`, never a persisted PID or PID-based kill, and confirms an empty cgroup plus released lock before capacity release. Replaced or missing same-boot cgroups without durable tombstone proof do not prove absence. - -Cleanup uses ownership bindings rather than image/launch validation; removed rootfs/firmware do not prevent it. A durable tombstone makes interrupted cgroup/private-storage reclamation retryable; only a minimal ID fence remains. Cleanup errors retain reservations. See [storage](storage.md#gc). - -## Expiration {#expiration} - -Omitted/null timeout means manual cleanup. A TTL is at least 60 seconds and within the configured maximum (one day by default, configuration ceiling one year). Renewal supplies a future RFC3339 deadline within the maximum; an existing deadline must extend, and expired or nonrenewable states are rejected. - -Maintenance scans once per second and runs at most eight cleanup tasks concurrently. Cleanup rechecks expiration under the same lock as renewal, so a stale scan cannot delete a renewed sandbox. Pending deletion retries remain pending on failure. - -TTL is best-effort cleanup, not a hard execution deadline. Slow native commands, upload/header waits and same-sandbox controls can delay deletion. New proxy requests are refused after expiration; established streams have no total response timeout. Daemon downtime suspends maintenance, so independent host supervision is needed for a stronger deadline. - -## Service access and concurrency {#endpoints} - -Only execd port 44772 and egress port 18080 are published. Endpoint discovery and each data-request endpoint lookup authenticate the live supervisor, require current RunHandle Running state, check deletion fences and resolve a current publication; they do not trust a durable observation cache. Discovery returns a daemon-routed authority, not the supervisor's loopback address. Lookup does not repeat service health probes or full cgroup-limit reconciliation for every data request. Create, Inspect and resume retain full configuration/readiness checks; upstream connection failures are handled by the API adapter rather than treated as readiness proof. Proxy establishment shares the lifecycle lock with control/deletion, preventing daemon-managed deletion/port reuse while connecting. External runtime manipulation is outside that coordination. - -The proxy streams real upstream command/file/health/metrics traffic, including multipart and SSE. Upload plus response-header wait is capped at 120 seconds; established responses stream without a total timeout. WebSocket, CONNECT and arbitrary application ports are unsupported. Stream/output quotas belong to the upstream service. - -## Separate execution semantics {#integration} - -Native pause/resume controls live vCPUs through RunHandle on the same Attempt, not cgroup freeze, memory offload, checkpoint/restore or VM reconstruction. Admission charges remain. Execd forwarding is not Gateway routing, capture or inference-idle CPU release. - -Ordinary Jobs retain their own [checkpoint/fork semantics](../execution-model.md). The daemon cannot stage/apply changes, restore native VM state, acquire node backing or coordinate model replies. Adding those paths would require an explicit adapter and lifecycle/evidence contract, not renaming retired distributed controls. - -Lifecycle orchestration resides in `daemon/mod.rs`; native controls/readiness are in `runtime.rs`; streaming is in `daemon/api.rs`. diff --git a/docs/src/en/design/daemon/operations.md b/docs/src/en/design/daemon/operations.md index bf21a696..9ce5679c 100644 --- a/docs/src/en/design/daemon/operations.md +++ b/docs/src/en/design/daemon/operations.md @@ -26,9 +26,7 @@ Keep state and runtime configuration compatible across restarts. Use TLS termina Keep runtime paths absolute and unchanged across daemon restarts. Use short state paths such as `/run/user/1000/pvd`: per-sandbox `control.sock` must be shorter than 104 bytes, and vsock Unix sockets also have path limits. Retain state; this `/run` example does not promise persistence across logout/reboot, and VMs cannot survive host reboot. `/sys/fs/cgroup/pvd` must be a real delegated hierarchy, not an ordinary directory. -An occupied version-1 `sandboxes.json` without the native `owner.json` marker is rejected under the existing exclusive store lock: it may still own live Podman containers. Use fresh native state while preserving and cleaning up the old deployment, or delete every sandbox through the old Podman daemon and confirm cleanup before switching backends with the emptied registry. Never erase registry entries, reservations or ownership state, or fabricate a native marker to bypass this guard. The native daemon neither adopts those containers as Missing nor silently releases their reservations. - -A v2 header is also rejected without `owner.json`, even with its intentionally empty `sandboxes` map. Preserve the native marker, header and private `records/` tree together; see [storage migration and activation](storage.md#migration). +An occupied v1 registry or a v2 header without the native `owner.json` marker is rejected, even with an intentionally empty map: it may still own live Podman containers. Preserve the original ownership state; use fresh native state or clean up through the old Podman daemon before switching, and never erase records/reservations or fabricate markers. Rejection and migration rules live in [storage](storage.md#migration). ## Prepared image contract {#image-contract} diff --git a/docs/src/en/design/daemon/responsibility-convergence.md b/docs/src/en/design/daemon/responsibility-convergence.md deleted file mode 100644 index 43e63d37..00000000 --- a/docs/src/en/design/daemon/responsibility-convergence.md +++ /dev/null @@ -1,63 +0,0 @@ -# Service responsibility convergence - -Reduce duplicated management by giving each local resource a clear owner, not by combining every service into the daemon process. Sandbox lifecycle, native immutable backing and indispensable live RAM have different authority and failure boundaries. - -## Current responsibilities {#roles} - -| Responsibility | Owner | Relationship to daemon | -| --- | --- | --- | -| Sandbox admission, intentions, expiration, endpoints | `pvisor-daemon` | Implemented by VM-only NativeRuntime with integrated executable/CLI | -| Job/Attempt lifecycle, staging, Gateway and native VM checkpoints | `pvisor` Session/executors | VM execution embedded in supervisors; staging/Gateway/checkpoint APIs not exposed | -| Immutable environment mounts and shared read-only RAM backing | Native node resource service (`pvisor/src/node.rs`) | Runtime protocols for native callers; no daemon acquire/release adapter | -| Image preparation, publication, serving and reads | Independent `pvisor-cache` and runtime cache modules | Separate executable, data path and budgets; not absorbed by daemon | -| Optional shared pages and session references | `pvisor-daemon/src/memory_pool.rs` | `serve --memory-pool` starts/reuses a detached `memory-pool --directory DIR` component; off by default | -| Host selection, workflows and retry policy | External orchestration | Outside the product control plane | - -Node runtime protocols are available to embedded native callers. Its identity is an image handle/digest or sealed RAM identity/compatibility, not a sandbox ID. A connection pins one owner. Same-identity preparation is single-flight; active owner/session/preparation counts and warming are bounded. A process-local registry remains available where native callers do not configure a node socket. - -```mermaid -flowchart TB - Caller[Caller or external orchestration] --> Daemon[Sandbox daemon] - Daemon --> Supervisor[Native pVisor VM supervisor] - Supervisor --> Image[Prepared execd and egress image] - Native[Native pVisor execution] --> Node[Native node resource service] - Node --> Cache[Immutable cache and lazy reads] - Node --> RAM[Shared read-only RAM backing] - Daemon --> Pool[Optional detached shared-page pool] - Supervisor --> Pool -``` - -There is deliberately no daemon-to-node arrow. Shared packaging, a common launch entry or fewer ports does not supply a missing runtime adapter or establish faster startup, lower memory or improved useful-work density. - -## Data authority and restart boundaries {#authority} - -| Object | What may be reclaimed? | Failure boundary | -| --- | --- | --- | -| Refetchable image/decoded blocks | Unpinned hot contents with a valid durable source | Hits do not replace publication authorization | -| Active read-only RAM/FUSE owner | Idle warmth after active pins end, not active mounts | Durable source does not automatically recover a live VM after owner failure | -| Private cold RAM transferred to pool | Not its only remaining copy | Lost sessions/pool contents may fail-stop dependent VMs | -| Published checkpoints/evidence | Only through their own retention and GC roots | Native registry warmth cannot authorize deletion | -| Daemon sandbox record | After confirmed native deletion | Normal daemon shutdown preserves supervisors/VMs and registry | - -A daemon-only restart preserves detached native supervisors/VMs and the configuration-bound pool component. It does not recover a failed pool or recreate its live pages. Restarting a backing owner or cold pool is a different operation and cannot promise transparent session reconnect. Keep pins until native runners are reaped; without lossless draining, wait for dependent VMs before upgrades. Do not infer live RAM reconstruction from a restored metadata file. - -## Budgets and concurrency {#budget} - -Native node configuration bounds owners, warm owners, sessions, preparations and retained cache payload. That payload counter aggregates content blocks, paged metadata and Linux decoded RAM; it excludes complete metadata, scratch, external references and kernel residency. The daemon pool has separate bounded page/object/connection/reference budgets, outside individual sandbox cgroups. They are not dynamically arbitrated against node caches or equal to a whole-process cap; see [pool budgets](../../guides/daemon/index.md#memory-pool). - -Reserve headroom for active objects and restoration before optional caches/prefetch. Under pressure, drop expendable warmth/refetchable contents or refuse new preparations, never the only live bytes. Slow teardown and I/O stay outside management map locks; same-identity serialization must retain authorization and compatibility checks. - -Daemon CPU/memory admission remains a separate conservative sum of supervisor/VM-tree hard limits. It has no combined physical-memory accounting with native node/pool resources. Host cgroup supervision and observations must include services and transient work, not only workloads. - -## Integration direction {#migration} - -1. Retain separate owners and failure scopes while obsolete distributed roles are retired. -2. Before connecting the existing native runtime to node resources, define acquisition, private writable state, cancellation, native termination and pin release before sharing resources. -3. Unify observations and controllable budgets only after distinguishing reservations, shared physical pages, evictable payload and indispensable RAM. -4. Consider process merging only after explicit restart/drain and data-preservation contracts, followed by fixed-budget measurements. - -No live-VM takeover, shared cold-pool arbitration, automatic node acquisition or density advantage is established by consolidation. Native resource correctness evidence and legacy service experiments keep their original scope; they are not daemon acceptance results. - -The independent cache provides `prepare`, `publish`, `serve`, `list`, `stat` and `read`. Cache and node protocols have separate ownership from daemon sandbox lifecycle. - -Related contracts: [shared working sets](shared-working-set.md), [state and recovery](state-and-recovery.md), [native shared image storage](../shared-image-cache-storage.md) and [experimental pool](../memory-optimization/proof-of-concept.md). diff --git a/docs/src/en/design/daemon/shared-working-set.md b/docs/src/en/design/daemon/shared-working-set.md index f453d2e0..2c7e7b30 100644 --- a/docs/src/en/design/daemon/shared-working-set.md +++ b/docs/src/en/design/daemon/shared-working-set.md @@ -41,7 +41,7 @@ node memory = service overhead Count physically shared pages once. Shared costs vary with revisions and access patterns; private costs grow with executions and write ratios. Disjoint accesses and many writes can eliminate gains. File copy-up, transfer blocks, read-ahead and COW may amplify requested bytes. -Keep logical reservations, physical occupancy and reclaimable cache separate. Native node retained-payload accounting covers content blocks, paged metadata and decoded RAM, not complete metadata, scratch, external references or kernel pages. Kernel caps and whole-group observation remain necessary. None of this relaxes daemon [hard-limit admission](admission.md). +Keep logical reservations, physical occupancy and reclaimable cache separate. Native node retained-payload accounting covers content blocks, paged metadata and decoded RAM, not complete metadata, scratch, external references or kernel pages. Kernel caps and whole-group observation remain necessary. None of this relaxes daemon [hard-limit admission](index.md#admission). ## Ownership and future connections {#integration} @@ -67,4 +67,4 @@ Use at most four simultaneous real native guests, counting live source VMs; cap The daemon pool is separate from node-backed restoration. Physical-pool loss fails dependent VMs; sealed-compressed clients retain delivered handles for local recovery and stop new publication; API restart retains the detached component but cannot recover failed pool contents. See [activation, ownership and limits](../../guides/daemon/index.md#memory-pool). -Related designs: [responsibility convergence](responsibility-convergence.md), [shared image storage](../shared-image-cache-storage.md), [memory optimization](../memory-optimization/index.md) and [experimental cold RAM pool](../memory-optimization/proof-of-concept.md). +Related designs: [daemon architecture](index.md), [shared image storage](../shared-image-cache-storage.md), [memory optimization](../memory-optimization/index.md) and [experimental cold RAM pool](../memory-optimization/proof-of-concept.md). diff --git a/docs/src/en/design/daemon/state-and-recovery.md b/docs/src/en/design/daemon/state-and-recovery.md deleted file mode 100644 index b69b32aa..00000000 --- a/docs/src/en/design/daemon/state-and-recovery.md +++ /dev/null @@ -1,46 +0,0 @@ -# Local state and restart recovery - -Restart with the same private state directory and compatible runtime configuration to retain native ownership and unresolved reservations. A stored state is the last durable observation, not proof that a VM survived. - -## Authority and identity {#authority} - -| State | Authority | Restart behavior | -| --- | --- | --- | -| Registry version and owner UUID | Durable daemon registry | Validate and retain the same owner | -| Sandbox identity, image/argv/env/metadata, resources, TTL and endpoint token | Durable record | Preserve intentions, access identity and conservative capacity | -| Running/Paused/Terminated | Native runtime observation | Inspect registered objects and update changed observations | -| `Stopping` | Durable deletion intent | Retry delete; inspection cannot overwrite it | -| Actual VM and service readiness | Native supervisor, VM controls, kernel cgroup and real services | Registry cannot recreate them | - -One daemon exclusively locks `daemon.lock`. Private IPC authenticates same-UID peers plus owner, sandbox ID, generation and secret token; durable identity binds boot ID and cgroup device/inode. IDs are never reused or relaunched. Lost IPC is uncertainty, not Missing or cleanup proof. Durable deletion intent and the supervisor exclusive lock fence late launch; cleanup uses identity-bound `cgroup.kill`, never a persisted PID or PID-based kill, and confirms an empty cgroup plus released lock before capacity release. Replaced or missing same-boot cgroups without durable tombstone proof do not prove absence. - -An occupied version-1 `sandboxes.json` without the native `owner.json` marker is rejected under the existing exclusive store lock: it may still own live Podman containers. Use fresh native state while preserving and cleaning up the old deployment, or delete every sandbox through the old Podman daemon and confirm cleanup before switching backends with the emptied registry. Never erase registry entries, reservations or ownership state, or fabricate a native marker to bypass this guard. The native daemon neither adopts those containers as Missing nor silently releases their reservations. - -A version-2 header without `owner.json` is rejected even though its `sandboxes` map is empty: that header activates private per-sandbox records, not an empty inventory. Restore original ownership state, never manufacture a marker. See [storage activation and migration](storage.md#migration). - -## Startup reconciliation {#reconcile} - -1. Open and validate the private registry, rejecting corrupt, oversized or incompatible contents rather than forgetting native ownership. -2. Construct the runtime with the persisted owner. Only after its factory accepts that owner, initialize/migrate storage: commit owner-wrapped records and metadata, then atomically activate the v2 header. Until activation the v1 full snapshot remains authoritative. Complete native preflight after storage initialization and before API binding. -3. Retry records with `Stopping`; inspect other registered sandboxes under their lifecycle lock. -4. Map native Running/Paused/Stopped/Missing to `Running`/`Paused`/`Terminated`/`Failed`. A missing sandbox remains visible and reserved until explicit deletion. -5. Report deferred reconciliation errors without inventing successful cleanup. Start maintenance to retry expired/pending deletion. - -Normal daemon shutdown leaves detached supervisors/VMs and records. Restart reconnects private IPC, not a recreated VM or new Attempt; loss of IPC preserves uncertainty. GET reconciles while list returns durable observations. Startup does not adopt unknown VMs or relaunch missing/crashed workloads; host reboot cannot retain a live VM. - -Cleanup validates durable owner/ID/generation and boot/cgroup bindings independently of launch resources: it does not require the original rootfs or firmware directory to remain present or guest argv/env/resource settings to pass launch validation. After proving native absence and acquiring the owner lock, it durably publishes `tombstone.json`, removes the empty owned cgroup and reclaims private run storage, live RAM backing, temporary overlays/specs, sockets and secret-bearing identity records and any legacy observation caches. A minimal directory retains the tombstone, owner lock and lifecycle markers to fence ID reuse. Interrupted reclamation resumes from the tombstone, including after cgroup removal; errors retain the reservation. Missing/replaced same-boot cgroups without this durable proof still do not authorize absence. See [storage](storage.md#gc). - -## Uncertainty and recovery {#failures} - -| Failure | Preserved boundary | Action | -| --- | --- | --- | -| Create fails, cleanup confirmed | Record/reservation removed | Diagnose image/runtime before another request | -| Create cleanup uncertain | Failed record, ID in error, full reservation | Query/delete that ID; do not blindly resubmit | -| Native inspect unavailable | No fabricated native state | Repair runtime access and query again | -| Delete fails or absence unknown | `Stopping`, token/record and reservation retained | Restore runtime access and retry | -| Registry commit uncertain | Storage-failed latch refuses subsequent registry access | Preserve state, repair storage, restart and reconcile | -| Daemon down past TTL | No maintenance while down | Use host supervision if execution must end independently | - -The registry is an incrementally committed local inventory, not a complete execution history or business-effect ledger. Version 2 reconstructs it from the owner/header and validated per-sandbox records; it does not fall back to v1 when an activated records tree is corrupt or incomplete. Restart does not roll back external calls, restore lost RAM or provide cross-host failover. Consistent automated backup/native-state restore is not implemented; copying a live directory or deleting state is not a recovery procedure. - -The recovery path is implemented in `daemon/mod.rs`; registry validation and durability are in `daemon/store.rs`. See [storage](storage.md) and [operations](operations.md#runbook). diff --git a/docs/src/en/design/daemon/storage.md b/docs/src/en/design/daemon/storage.md index 0a285abc..9674ab53 100644 --- a/docs/src/en/design/daemon/storage.md +++ b/docs/src/en/design/daemon/storage.md @@ -1,7 +1,29 @@ -# Daemon storage and reclamation +# Daemon storage, recovery and reclamation Keep durable sandbox intentions in a bounded local registry. The native runtime owns private per-sandbox run state; prepared services own workload files and streamed outputs. These stores are not a centralized pVisor evidence repository. +Restart with the same private state directory and a compatible runtime configuration, preserving native ownership and unresolved reservations. Persisted state is the most recent durable observation; it does not prove a VM is still alive. + +## Authority and identity {#authority} + +| State | Authority | Restart behavior | +| --- | --- | --- | +| Registry version and owner UUID | Daemon's durable registry | Validate and retain the same owner | +| Sandbox identity, image/argv/env/metadata, resources, TTL and endpoint tokens | Durable records | Retain intentions, access identity and conservative capacity | +| Running/Paused/Terminated | Native runtime observation | Query registered objects and update changed observations | +| `Stopping` | Durable delete intent | Retry deletion; queries cannot override it | +| Actual VM and service readiness | Native supervisor, VM control, kernel cgroups and real services | The registry cannot rebuild them | + +## Startup reconciliation {#reconcile} + +1. Open and validate the private registry; reject corrupt, over-limit or incompatible content instead of continuing startup by forgetting native ownership. +2. Construct the runtime with the persisted owner. Storage initializes/migrates only after the factory accepts that owner: commit records and metadata with the owner envelope, then activate the v2 header atomically. Before activation the complete v1 snapshot remains authoritative. Native preflight checks run after storage initialization and before binding the API. +3. Retry `Stopping` records; query other registered sandboxes under their lifecycle locks. +4. Map native Running/Paused/Stopped/Missing to `Running`/`Paused`/`Terminated`/`Failed`. Missing sandboxes stay visible and reserved until explicitly deleted. +5. Report deferred reconciliation errors without fabricating cleanup success. Startup maintenance retries expired/delete-pending objects. + +A normal daemon shutdown preserves detached supervisors/VMs and records. Restart reconnects over private IPC without rebuilding VMs or minting new Attempts; IPC loss preserves an uncertain state. GET reconciles; list returns persisted observations. Startup neither adopts unknown VMs nor restarts missing/crashed workloads; a host reboot does not preserve live VMs. + ## Private registry {#metadata} ```text @@ -24,7 +46,7 @@ Records retain image/argv, environment, metadata, CPU/memory reservation, creati Runtime state additionally retains private `owner.json`, per-sandbox `preparing.json`/`identity.json`, `run.json` (generation/Run/Attempt IDs), lifecycle markers, owner lock, `control.sock`, `ports/` bridges and `run/` native storage, including `live-ram` backing and `tmp/` scratch (set as supervisor `TMPDIR`). A completed cleanup retains only its minimal tombstone/lock/marker fence. These support reconciliation/cleanup, not a public stage/checkpoint/artifact API. -Native runtime does not write `observation.json` caches or use them as liveness proof. Endpoint lookup authenticates the live supervisor and checks current Running state and deletion fences; full readiness checks remain at create, Inspect and resume. See [service access](lifecycle.md#endpoints). +Native runtime does not write `observation.json` caches or use them as liveness proof. Endpoint lookup authenticates the live supervisor and checks current Running state and deletion fences; full readiness checks remain at create, Inspect and resume. See [service access](index.md#endpoints). ## Commit barrier {#commit} @@ -50,6 +72,19 @@ Cleanup validates durable owner/ID/generation and boot/cgroup bindings independe Deleting a sandbox does not undo remote effects or provide a retained evidence bundle. Externally provisioned image manifests/rootfs/firmware are not deleted by sandbox cleanup. The daemon API has no stage review/apply, artifact retention/download or external object-GC protocol. Do not remove native resources or registry state independently as recovery. -Native immutable cache/snapshot stores retain separate publication, integrity, pin and GC contracts; see [shared image storage](../shared-image-cache-storage.md) and [responsibility convergence](responsibility-convergence.md#authority). No daemon-to-node storage bridge is implemented. +## Uncertainty and recovery {#failures} + +| Failure | Retained boundary | Action | +| --- | --- | --- | +| Creation failed, cleanup confirmed | Record/reservation removed | Investigate the image/runtime before requesting again | +| Create cleanup uncertain | Failed record, ID from the error, full reservation | Query/delete that ID; do not blindly resubmit | +| Native query unavailable | No fabricated native state | Restore runtime access and query again | +| Delete failed or absence unknown | `Stopping`, tokens/records and reservation retained | Restore runtime access and retry | +| Registry commit uncertain | Storage-failed marker rejects further registry access | Retain state, repair storage, restart to reconcile | +| Daemon down beyond TTL | No maintenance while down | Independent termination requirements belong to host supervision | + +The registry is an incrementally committed local inventory, not a complete execution history or business side-effect ledger. Version 2 rebuilds the inventory from the owner/header and validated per-sandbox records; a corrupt or incomplete activated record tree does not fall back to v1. Restart does not roll back external calls, restore lost RAM or provide cross-host failover. Automatic consistent backup/native-state restoration is unimplemented; copying a live directory or deleting state is not a recovery procedure. + +Native immutable cache/snapshot stores retain separate publication, integrity, pin and GC contracts; see [shared image storage](../shared-image-cache-storage.md). No daemon-to-node storage bridge is implemented. -Implementation: `daemon/store.rs` owns per-record publication, budget accounting and v1 activation; `daemon/mod.rs` owns reservation and deletion ordering. +Implementation: `daemon/store.rs` owns per-record publication, budget accounting and v1 activation; `daemon/mod.rs` owns reservation, deletion ordering and the recovery path. diff --git a/docs/src/en/design/decisions/0001-plan-and-evidence.md b/docs/src/en/design/decisions/0001-plan-and-evidence.md deleted file mode 100644 index 6eb3d66f..00000000 --- a/docs/src/en/design/decisions/0001-plan-and-evidence.md +++ /dev/null @@ -1,11 +0,0 @@ -# 0001: A plan cannot prove that controls were installed {#adr-0001} - -**Status: implementation backfill.** This records the existing contract without inferring independent maintainer approval. - -**Context.** Before launch, pVisor can plan how a requested policy should be implemented. Permissions, platforms, and startup failures can prevent installation. - -**Options.** Let plans assert enforcement, or wait for executor observations. - -**Current choice.** Admission plans reach at most `Planned`; executor observations supply actual enforcement evidence. The Run Bundle retains requests, plans, and observations. See [Evidence design](../../concepts/capabilities-and-evidence.md). - -**Consequences.** Automation must inspect actual observations, and platform adapters must report installation outcomes. Task completion or a configuration field does not replace that evidence. diff --git a/docs/src/en/design/decisions/0002-capture-and-replay.md b/docs/src/en/design/decisions/0002-capture-and-replay.md deleted file mode 100644 index a0e2a64b..00000000 --- a/docs/src/en/design/decisions/0002-capture-and-replay.md +++ /dev/null @@ -1,11 +0,0 @@ -# 0002: Capture and replay have separate data responsibilities {#adr-0002} - -**Status: implementation backfill.** This records the existing contract without inferring independent maintainer approval. - -**Context.** Running tasks, recording model traffic, and restoring native agent context require different protocols and dependencies. - -**Options.** Put every protocol in the execution core, or exchange explicit records across independent components. - -**Current choice.** Gateway owns model traffic capture and routing; Replay consumes native agent trajectories and re-executes tools; the execution core maintains Run lifecycle and shared records. Gateway is an optional feature, and Replay has a separate crate and command. See [Replay design](../replay.md). - -**Consequences.** Users can use execution and staging alone. Capture journals and native trajectories must be collected separately; new agent integrations primarily belong in the Replay adapter boundary. diff --git a/docs/src/en/design/decisions/0003-explicit-safe-executor.md b/docs/src/en/design/decisions/0003-explicit-safe-executor.md deleted file mode 100644 index f14f7f6e..00000000 --- a/docs/src/en/design/decisions/0003-explicit-safe-executor.md +++ /dev/null @@ -1,11 +0,0 @@ -# 0003: Safe expresses requirements while executor selection stays explicit {#adr-0003} - -**Status: implementation backfill.** This records the existing contract without inferring independent maintainer approval. - -**Context.** Users choose executors for speed, Linux userspace, or kernel isolation while expecting their file and network policies to take effect. - -**Options.** Safe could silently select an executor, or impose requirements on the chosen executor. - -**Current choice.** `--safe` configures staging, file access, environment, and related settings without selecting an executor. Missing required controls cause startup rejection. See [Network policies](../../guides/policies/network.md) for network paths. - -**Consequences.** Identical arguments can encounter capability errors on different machines. Install the prerequisites or explicitly select an executor that meets the requirements; reviewers inspect the Bundle for the outcome. diff --git a/docs/src/en/design/decisions/0004-human-semspec-approval.md b/docs/src/en/design/decisions/0004-human-semspec-approval.md deleted file mode 100644 index f27bd9a8..00000000 --- a/docs/src/en/design/decisions/0004-human-semspec-approval.md +++ /dev/null @@ -1,11 +0,0 @@ -# 0004: Passing a test and approving a commitment are separate actions {#adr-0004} - -**Status: existing contribution rule backfill.** This records the existing contract without inferring independent maintainer approval. - -**Context.** A passing test establishes one successful verification. A public commitment also needs human judgment about scope and conditions. - -**Options.** Automatically approve passing cases, or retain a separate human review step. - -**Current choice.** AI and contributors can draft cases, fix implementations, and maintain runner tests. Humans maintain `semspec approve`, `revoke`, real `REVIEWED.toml` ledgers, and `.approved/` snapshots. Existing checks and xfail annotations must not be weakened to obtain PASS. See [Testing and semspec](../../community/testing.md). - -**Consequences.** Reviews consider claims, execution results, and human approval records together. Green tests do not automatically expand support. diff --git a/docs/src/en/design/decisions/0005-rust-vm-api.md b/docs/src/en/design/decisions/0005-rust-vm-api.md deleted file mode 100644 index b4bf5c24..00000000 --- a/docs/src/en/design/decisions/0005-rust-vm-api.md +++ /dev/null @@ -1,11 +0,0 @@ -# 0005: Keep VM backend differences inside one Rust runtime {#adr-0005} - -**Status.** Implementation backfill; this records the implemented boundary, not independent maintainer approval. - -**Context.** VM configuration, device customizations and snapshots were split between pVisor and multiple libkrun crates. C contexts, borrowed raw pointers and public backend structs made ownership and platform differences leak into consumers. - -**Options.** Retain an external C context ABI and vendored component crates, or consolidate private runtime modules behind one Rust contract. - -**Current choice.** `pvisor-vm` compiles the core modules together. Only `api` is public; portable structs and traits define every public method signature without conditional compilation or default implementations. Private adapters implement those traits. Architecture layout and hypervisor behavior have separate internal traits; callers receive explicit unsupported errors and inspect capabilities. Firmware data ABI and OS FFI remain private. - -**Migration and consequences.** Executor, shim, snapshot/checkpoint/pager, examples and the init benchmark use the new API. Hardware/device tests move inside the crate. Static kernel packing belongs to the runtime. Old core crate dependencies and VM control C functions are removed; existing evidence identifiers and serialized snapshot fields remain compatible. Uniform API shape does not promise cross-architecture restore. `api_contract` and `repository_boundary` guard the boundary; native tests and target compile checks supply distinct evidence. See [development](../../community/development.md) and the [runtime contract](https://github.com/deeplink-org/pvisor/blob/main/crates/pvisor-vm/README.md). diff --git a/docs/src/en/design/decisions/0006-stage-snapshot.md b/docs/src/en/design/decisions/0006-stage-snapshot.md index cb427c90..3ece0e90 100644 --- a/docs/src/en/design/decisions/0006-stage-snapshot.md +++ b/docs/src/en/design/decisions/0006-stage-snapshot.md @@ -25,4 +25,4 @@ Keep existing full-environment formats readable. New manifests/profiles distingu Hold stage/RAM fixed while increasing the base: warm save/fork must not traverse or copy an unchanged base. Then vary stage bytes, entry count, large-file copy-up, and 1/8/64 branches. Preserve branch isolation, deletion/metadata/hardlinks, open handles, dependency GC, corruption rejection, and failed-publication contracts. Budgets such as 100 ms must state size, preparation, durability, and first-useful-work boundaries; this record makes no latency commitment. -The runtime retains one public `api`, uniform cross-platform traits/structs, and private backend implementations. Image resolution, base pins, and store publication stay outside the VMM. See the [current full-environment implementation](../environment-snapshot.md), [OverlayCore](../overlayfs.md), and [ADR 0005](0005-rust-vm-api.md#adr-0005). +The runtime retains one public `api`, uniform cross-platform traits/structs, and private backend implementations. Image resolution, base pins, and store publication stay outside the VMM. See the [current full-environment implementation](../environment-snapshot.md) and [OverlayCore](../overlayfs.md). diff --git a/docs/src/en/design/decisions/0007-shared-filesystem-service.md b/docs/src/en/design/decisions/0007-shared-filesystem-service.md deleted file mode 100644 index 47392b1c..00000000 --- a/docs/src/en/design/decisions/0007-shared-filesystem-service.md +++ /dev/null @@ -1,23 +0,0 @@ -# 0007: Share file services between host FUSE and virtio-fs {#adr-0007} - -**Status: implementation backfill.** Records current source responsibilities without new formal approval or performance claims. - -## Context {#context} - -Host staging serves files through host FUSE; VMs request files through guest virtio-fs. Layer lookup, policy, copy-up, preimages and lazy-lower reads need identical semantics. Inodes, handles, credentials and queue completion depend on each protocol entry. - -## Alternatives and choice {#decision} - -Options include duplicating file semantics in both adapters, routing VM requests through host FUSE, or calling a shared service directly. The implementation chooses the third: `pvisor-overlay-core::service::FilesystemService` owns OverlayCore and is called directly by host FUSE and VM virtio-fs. It unifies local-file and immutable-image backend reads. - -The service accepts file operations, paths and backing identities rather than `fuser::Reply*`, virtqueue descriptors or guest RAM pointers. Adapters retain protocol inodes/handles, permission translation, operation guards and completion publication. VMs require no intermediate `/dev/fuse` mount. - -## Consequences {#consequences} - -File semantics have one implementation, while the two entries retain platform and concurrency differences. virtio-fs workers hold RAM leases until used-ring publication, and freezing drains in-flight I/O. Shared-service content reads should not hold whole protocol handle-table locks. Lazy-lower copy-up or full export can still materialize unread content; interface reuse does not establish end-to-end speedups. - -## Implementation and scope {#implementation} - -Source entries are `crates/pvisor-overlay-core/src/service.rs`, `crates/pvisor-overlayfs/src/fs.rs`, `crates/pvisor-vm/src/devices/virtio/fs/`, and `crates/pvisor/src/image/cache/backend.rs`, `direct.rs`, `lazy.rs`. `pvisor-overlay-core` has not yet migrated to a sole `api` entry. Shared file services and API-visibility migration remain separate concerns. - -[Filesystem subsystem](../overlayfs.md#filesystem-service) owns request paths, layouts and existing measurement scope; [VM subsystem](../vm-runtime.md#virtio) owns mapping lifetimes. diff --git a/docs/src/en/design/decisions/0008-host-guest-control-authority.md b/docs/src/en/design/decisions/0008-host-guest-control-authority.md deleted file mode 100644 index ccd2d1b4..00000000 --- a/docs/src/en/design/decisions/0008-host-guest-control-authority.md +++ /dev/null @@ -1,25 +0,0 @@ -# 0008: Separate Host and Guest control authority {#adr-0008} - -**Status: implementation backfill.** Records current protocol and ownership boundaries without expanding platform-validation scope. - -## Context {#context} - -Guests report state, receive directives and participate in checkpoint quiescence. Host callers manage Jobs, VMs, stages and supervisors. Their trust scopes differ, so guest cooperation credentials cannot grant host lifecycle authority. - -## Alternatives and choice {#decision} - -Host operations could be added to Guest `Hello`/`Sync`, or use separate endpoints, schemas and credentials. The implementation chooses separation: Guest AgentCtl retains workload cooperation, while Host envelopes carry typed host requests whose endpoint owners validate Job/Attempt/generation and authority. - -The CLI Job listener accepts requests under a private same-UID authority root, handing off through separate tickets and worker channels. Native daemon supervisors use Host envelopes with owner/token credentials, not Guest tokens or CLI worker tickets. Shared Core defines envelopes and validation; implementations retain CLI DTOs and transport. - -## Consequences {#consequences} - -Bundle `agentctl` state still describes Guest cooperation, not Host authorization receipts. Both protocols currently use version 1, but are not interchangeable. CLI worker schema, package version and executable digest jointly determine internal compatibility; old listeners/supervisors follow their drain-and-upgrade contract. - -Host `request_id` provides correlation rather than durable deduplication for every command. Timeout or cancellation requires reconciling Job state and effects. Private directories and same-UID peer checks define host trust scope rather than isolating all other same-UID processes. macOS identity/descendant cleanup and real VM TUI paths retain the documented validation gaps. - -## Implementation and scope {#implementation} - -Source entries: `crates/pvisor-core/src/host_protocol.rs`, `protocol.rs`; `crates/pvisor-cli/src/cli/host_service.rs`, `host_fds.rs`; `crates/pvisor/src/runtime/host_transport.rs`, `supervisor.rs`, `instance_control.rs`. - -[Host/Guest AgentCtl](../architecture.md#host-agentctl) owns detailed authority and upgrades, the [Protocol matrix](../records-and-versions.md#control-protocols) lists versions, and [Failure semantics](../failure-semantics.md#idempotency) explains disconnects and retries. diff --git a/docs/src/en/design/decisions/index.md b/docs/src/en/design/decisions/index.md index 639a7e2f..681fbbc9 100644 --- a/docs/src/en/design/decisions/index.md +++ b/docs/src/en/design/decisions/index.md @@ -4,14 +4,14 @@ ADRs retain context, alternatives and consequences. Subsystem articles own curre | Number | Decision | Boundary or cost retained | Record status | | --- | --- | --- | --- | -| 0001 | [Separate plans from installed-control evidence](0001-plan-and-evidence.md) | Plans reach Planned; consumers still inspect observations | Implementation backfill | -| 0002 | [Separate capture and replay](0002-capture-and-replay.md) | Execution works independently; model capture and native trajectories are collected separately | Implementation backfill | -| 0003 | [Keep executor selection explicit under safe](0003-explicit-safe-executor.md) | Reject missing controls; platform prerequisites remain | Implementation backfill | -| 0004 | [Human approval of semantic commitments](0004-human-semspec-approval.md) | Test results and product commitments receive separate review | Existing contribution rule backfill | -| 0005 | [One Rust VM crate and trait API](0005-rust-vm-api.md) | Private backends; uniform declarations do not promise cross-architecture restore | Implementation backfill | +| 0001 | Separate plans from installed-control evidence | Plans reach Planned; consumers still inspect observations | Implementation backfill | +| 0002 | Separate capture and replay | Execution works independently; model capture and native trajectories are collected separately | Implementation backfill | +| 0003 | Keep executor selection explicit under safe | Reject missing controls; platform prerequisites remain | Implementation backfill | +| 0004 | Human approval of semantic commitments | Test results and product commitments receive separate review | Existing contribution rule backfill | +| 0005 | One Rust VM crate and trait API | Private backends; uniform declarations do not promise cross-architecture restore | Implementation backfill | | 0006 | [Snapshot stages and reuse immutable bases](0006-stage-snapshot.md) | Bases require validation and pins; historical standalone CLI profiles differ from current Job interfaces | accepted; retains the original 2026-10-04 status | -| 0007 | [Share file services between host FUSE and virtio-fs](0007-shared-filesystem-service.md) | Shared semantics; adapters retain protocol state and concurrency | Implementation backfill | -| 0008 | [Separate Host and Guest control authority](0008-host-guest-control-authority.md) | Separate credentials/endpoints; internal Host protocols require exact compatibility | Implementation backfill | +| 0007 | Share file services between host FUSE and virtio-fs | Shared semantics; adapters retain protocol state and concurrency | Implementation backfill | +| 0008 | Separate Host and Guest control authority | Separate credentials/endpoints; internal Host protocols require exact compatibility | Implementation backfill | Implementation backfill means the choice can be checked against source or existing contribution rules, without new maintainer approval. ADR 0006 retains its independent record's accepted status; its old CLI and measurements remain historical artifacts. [Environment snapshots](../environment-snapshot.md) and [Job checkpoints](../job-checkpoint-cli.md#10-当前实现与验收边界) define current behavior. diff --git a/docs/src/en/design/environment-snapshot.md b/docs/src/en/design/environment-snapshot.md index e83a0b95..62824cd4 100644 --- a/docs/src/en/design/environment-snapshot.md +++ b/docs/src/en/design/environment-snapshot.md @@ -51,7 +51,7 @@ The former save maps to suspend; resume continues the current head, while fork - The [single-node daemon](daemon/index.md) uses native VM execution, but does not implement capture/restore APIs. Its pause/resume is acknowledged live vCPU control on the same Attempt, not cgroup freeze or a snapshot. Snapshot, checkpoint/fork, stage/apply and offload APIs remain absent. Do not use retired Cluster controls as snapshot entries. -Native node backing ownership remains separate from daemon lifecycle; see [responsibility convergence](daemon/responsibility-convergence.md). +Native node backing ownership remains separate from daemon lifecycle; see the [daemon architecture](daemon/index.md). ## Historical evidence {#historical-evidence} diff --git a/docs/src/en/design/experimental/guest-stage-cache/index.md b/docs/src/en/design/experimental/guest-stage-cache/index.md index 9c0f2992..12cbfa36 100644 --- a/docs/src/en/design/experimental/guest-stage-cache/index.md +++ b/docs/src/en/design/experimental/guest-stage-cache/index.md @@ -291,7 +291,7 @@ Existing control owners continue to schedule quiescence, seal and snapshot. Thes The host trims invisible paths, protected aliases and object grants before metadata delivery. Mode/owner/ACL/xattr inputs must be complete. Preserve raw path bytes; symlinks cannot request arbitrary host paths. Content digests do not grant cross-tenant access. -Guest Linux checks permissions locally; VMM still validates host-recognized authorization for data/mutations. Session tokens, guest uid and mutation lists cannot replace Host-control credentials or alter host permission ledgers. See [Host/Guest authority](../../decisions/0008-host-guest-control-authority.md). +Guest Linux checks permissions locally; VMM still validates host-recognized authorization for data/mutations. Session tokens, guest uid and mutation lists cannot replace Host-control credentials or alter host permission ledgers (Host/Guest authority separation). Profiles requiring per-operation host policy/audit callbacks exclude local open. Policy changes revoke new cache admission and coordinate references; resume only after rebuilding permission/retention contracts. diff --git a/docs/src/en/design/filesystem-io-performance-analysis.md b/docs/src/en/design/filesystem-io-performance-analysis.md index dec09136..8c042a28 100644 --- a/docs/src/en/design/filesystem-io-performance-analysis.md +++ b/docs/src/en/design/filesystem-io-performance-analysis.md @@ -1,5 +1,7 @@ # Filesystem I/O: caching, asynchronous batching and completed throughput +> Note: "local original records" and `.data/` paths refer to local measurement archives that are not published with the repository or the site; they are kept for batch provenance only. + ## Conclusions {#conclusions} ### 1. Overall verdict: two write-intensive tasks improve, with complete-task evidence diff --git a/docs/src/en/design/filesystem-performance-analysis.md b/docs/src/en/design/filesystem-performance-analysis.md index 9012ad55..ae449c8d 100644 --- a/docs/src/en/design/filesystem-performance-analysis.md +++ b/docs/src/en/design/filesystem-performance-analysis.md @@ -1,5 +1,7 @@ # Filesystem performance: technical analysis and experiment records +> Note: "local original records" and paths such as `docs/src/assets/benchmarks/.data/` and `benchmark/.data/` refer to local measurement archives that are not published with the repository or the site; they are kept for batch provenance only. + ## Current conclusions and measurement coverage {#filesystem-status} The [filesystem I/O curves](filesystem-io-performance-analysis.md) compare request size, concurrency, synchronization, capacity and reuse working sets. Independent N30 and ordinary-CLI comparisons do not support enabling host-owned asynchronous batching by default; request counts distinguish backing coalescing from FUSE WRITE reduction. @@ -2270,7 +2272,7 @@ The table excludes environment boot, measuring operations and grading. This new These values locate waiting in traversal, search, compilation and installation. A single read does not establish that block devices always outperform FUSE: kernels, tool versions, storage and staging semantics differ together. For longer tasks, combine worker time with the [complete loop](../benchmarks/agent-tasks.md#full-ubuntu) rather than startup alone. -Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/summary.tsv` · [Method and reproduction](../benchmarks/methodology.md#full-ubuntu) +Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/summary.tsv` · [Method and reproduction](../benchmarks/index.md#full-ubuntu) ### Docker baseline in the complete tool environment {#reference-fs} @@ -2291,7 +2293,7 @@ This establishes a concrete position: Docker metadata/read/write stay close to n Tasks verify file counts/sizes, SHA256, clean Git state, search matches, compiled output, and installed package counts. Docker uses a writable bind mount, pVisor a staged view, and Firecracker/QEMU private ext4. Different file paths are part of actual deployment cost; this is not a causal experiment changing only the VMM over an identical filesystem. The summary also contains each operation's distribution for other runtimes. -[Configuration and reproduction](../benchmarks/methodology.md#reference-env) · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/summary.tsv` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/evidence.tar.gz` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/compatibility.tsv` +[Configuration and reproduction](../benchmarks/index.md#reference-env) · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/summary.tsv` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/evidence.tar.gz` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/compatibility.tsv` ### First-edition Linux matrix: separate batch @@ -2398,4 +2400,4 @@ python3 benchmark/pvisor/product_v1.py \ Start with `--samples 1 --warmups 0` to check prerequisites. Workloads and correctness assertions live in `benchmark/pvisor/v1/`. Reports pin binaries, firmware and harness source with hashes. Failed operations never enter performance distributions. Effective sample counts are stated per page; P95/P99 from small samples describe this batch rather than production tail probabilities. -[Environment, artifacts and method](../benchmarks/methodology.md#product-v1) · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/manifest.tsv` · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/evidence.tar.gz`. Reports retain dirty source status; executable SHA256 identifies the measured artifact. The archive excludes large rootfs/binaries and reproducible workspace payloads, while retaining input hashes and each batch's harness. +[Environment, artifacts and method](../benchmarks/index.md#product-v1) · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/manifest.tsv` · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/product-v1-20261004/evidence.tar.gz`. Reports retain dirty source status; executable SHA256 identifies the measured artifact. The archive excludes large rootfs/binaries and reproducible workspace payloads, while retaining input hashes and each batch's harness. diff --git a/docs/src/en/design/index.md b/docs/src/en/design/index.md index 26ca2e43..383b5e7b 100644 --- a/docs/src/en/design/index.md +++ b/docs/src/en/design/index.md @@ -228,4 +228,4 @@ Execution isolation constrains access, staging constrains file publication, snap Implementation scope remains explicit: the daemon has a VM-only NativeRuntime and an opt-in Linux physical pool, while its API does not expose native Job stage/apply or execution checkpoints. External orchestration and RL integration still need a separate handoff and end-to-end validation. Implemented mechanisms alone do not establish production density or long-term recovery conclusions. -The organization follows [ByteHook's project introduction and principles](https://github.com/bytedance/bhook/blob/main/doc/overview.zh-CN.md): explain prerequisite mechanisms, request paths and engineering constraints continuously. See [Open-source design references](research/design-documents.md) for further writing references and their application. +The organization follows [ByteHook's project introduction and principles](https://github.com/bytedance/bhook/blob/main/doc/overview.zh-CN.md): explain prerequisite mechanisms, request paths and engineering constraints continuously. See the design-writing references section of the repository's [docs/README.md](https://github.com/DeepLink-org/pvisor/blob/main/docs/README.md) for further writing references. diff --git a/docs/src/en/design/memory-optimization/compression-local.md b/docs/src/en/design/memory-optimization/compression-local.md index 0c21c222..a85b8336 100644 --- a/docs/src/en/design/memory-optimization/compression-local.md +++ b/docs/src/en/design/memory-optimization/compression-local.md @@ -112,5 +112,5 @@ physical-sharing path. [Memory evidence](proof-of-concept.md#memory-evidence) does not establish known production net gains. Compare total host occupancy, temporary peaks, CPU cost, -and application tails, not encoded size alone. See the [overview](compression.md) +and application tails, not encoded size alone. See the [architecture index](index.md) and [pooled alternative](compression-pool.md) for the ownership choice. diff --git a/docs/src/en/design/memory-optimization/compression-pool.md b/docs/src/en/design/memory-optimization/compression-pool.md index 57b2e737..c22ca36c 100644 --- a/docs/src/en/design/memory-optimization/compression-pool.md +++ b/docs/src/en/design/memory-optimization/compression-pool.md @@ -116,5 +116,5 @@ configuration; drain old instances and use fresh state to change it. [Memory evidence](proof-of-concept.md#memory-evidence) establishes no known production net gains or verified net physical-memory savings. Historical pool measurements do not validate sealed backing. The [architecture index](index.md) -and [compression overview](compression.md) distinguish implementation, component +distinguishes implementation, component correctness, the scoped real-guest probe and remaining workload acceptance gates. diff --git a/docs/src/en/design/memory-optimization/compression.md b/docs/src/en/design/memory-optimization/compression.md deleted file mode 100644 index e604766a..00000000 --- a/docs/src/en/design/memory-optimization/compression.md +++ /dev/null @@ -1,49 +0,0 @@ -# Memory compression - -Compression can reduce the cost of retaining cold RAM when encoding savings outweigh -storage, CPU, and recovery costs. Choose local ownership first; add a pool only -when sharing across instances justifies coordination. - -## Target and current status {#status} - -[Per-instance compression](compression-local.md) is delivered experimentally on -Linux x86_64 through the default-off `vm.cold_ram_compression` / -`--vm-cold-ram-compression`: a runtime-owned userfaultfd pager with bounded local -storage, no FUSE and no external pool. It is distinct from `vm.ram_compression` -(FUSE file backing), and is eviction/refault probing rather than a read-access -heat detector. Neither it nor [pooled-server compression](compression-pool.md) -is a production-benefit claim. The macOS/HVF heap pool remains experimental and -can fail dependent VMs when its service is lost. Linux sealed compressed backing -is implemented experimentally, with process-level handoff/recovery tests and a -passing two-VM guest discard/refault and file-I/O probe after service termination. - -## Ownership and data flow {#architecture} - -Each instance owns checkpoint save, compression, and restore independently of -runtime optimization. A [complete environment snapshot](../environment-snapshot.md) -includes machine state and durability; runtime cold objects retain only current -RAM fragments. A compressed checkpoint does not automatically reclaim live RAM. - -The VM runtime owns cold-page selection and mapping changes; the codec transforms -bytes, and backing carries them. `memfd` does not compress automatically. The -target restores writable pages into instance-private RAM, even with shared objects. - -## Choices and tradeoffs {#tradeoffs} - -Local compression avoids service coordination but cannot share payloads across -instances. A pool adds optional [deduplication](deduplication.md), shared storage, -and host-wide budgets, at the cost of IPC, contention, and broader failure risks. -Both need temporary-memory and recovery headroom, CPU budgets, and acceptable tails. - -## Direction and evidence {#direction} - -The Linux local pager publishes and validates objects before reclaiming RAM, -then validates restoration through `UFFD_COPY`. Kernel-fault userfaultfd authority -is required; compiled support does not grant permission and missing authority -fails startup. It rejects dedup, file/FUSE backing, snapshot capture/restore, -whole-VM [offload](offload.md), and external memory pools; see the -[local contract](compression-local.md#direction). Linux sealed `memfd` pool -delivery has process-level tests and a passing scoped real-guest UFFD probe; -a macOS sealed equivalent is not delivered. Start from the -[optimization architecture](index.md); [memory evidence](proof-of-concept.md#memory-evidence) -establishes no known production net gains or verified net physical-memory savings. diff --git a/docs/src/en/design/memory-optimization/deduplication.md b/docs/src/en/design/memory-optimization/deduplication.md index 2465bc88..cc9b5009 100644 --- a/docs/src/en/design/memory-optimization/deduplication.md +++ b/docs/src/en/design/memory-optimization/deduplication.md @@ -102,7 +102,7 @@ correctness probe are separate from physical-page-sharing evidence; see - **Sharing versus isolation:** Restrict trust domains and assess content-presence side channels. KSM advice has no pVisor-defined domain parameter, so product labels alone cannot establish isolation. - **Simplicity versus coverage:** The current physical pool uses bounded resident scanning. Arbitrary instant hot-page merging and P2P remain outside its scope; active shared slots and durable machine recovery are designed separately. -The first version does not combine KSM and userspace cold reclamation on the same region, avoiding redundant merging followed by copying and compression. See [Memory compression](compression.md) for unique but compressible cold content. +The first version does not combine KSM and userspace cold reclamation on the same region, avoiding redundant merging followed by copying and compression. See [Per-instance compression](compression-local.md) for unique but compressible cold content. ## Current integration and evidence {#direction} diff --git a/docs/src/en/design/memory-optimization/index.md b/docs/src/en/design/memory-optimization/index.md index b402ca00..10060990 100644 --- a/docs/src/en/design/memory-optimization/index.md +++ b/docs/src/en/design/memory-optimization/index.md @@ -38,7 +38,9 @@ Pin a reliable backing or recovery source before unmapping or reclaiming origina | Local live compression | Unique compressible cold content within an instance | userfaultfd permissions, encoding CPU and refault costs | | Whole-VM offload | Idle state with a retained recovery source | Write/restore costs, storage and peak headroom | -See [Memory deduplication](deduplication.md), [Memory compression](compression.md), [Per-instance compression](compression-local.md) and [Offload format](offload-format.md). [Pooled-server compression](compression-pool.md) shares sealed encoded objects in an explicit Linux mode; the default daemon physical pool shares raw pages. They remain separate mechanisms. +See [Memory deduplication](deduplication.md), [Per-instance compression](compression-local.md), [RAM offload](offload.md) and the [byte-layout appendix](../offload/disk-layout-and-schema.md). [Pooled-server compression](compression-pool.md) shares sealed encoded objects in an explicit Linux mode; the default daemon physical pool shares raw pages. They remain separate mechanisms. + +The default route is instance-local ownership: local compression avoids service coordination but cannot share encoded results across instances. Pooling adds optional deduplication, shared storage and host-level budgets at the cost of IPC, contention and a wider failure radius; introduce it only when cross-instance sharing of encoded objects is needed. Both need scratch memory, restoration headroom, a CPU budget and acceptable tail latency. ## Ownership and publication order {#ownership} @@ -71,12 +73,12 @@ Losing the physical/legacy pool fails dependent VMs. Linux sealed-compressed cli ## Implementation and combinations {#direction} -The Linux daemon enables raw-page sharing explicitly with `serve --memory-pool`; it does not require userfaultfd. Per-instance live compression and `--memory-pool-mode compressed` use userfaultfd. The sealed pool has component-level service-loss tests and a passing two-VM probe covering eviction/refault and file I/O after service termination; production-density and latency acceptance remain open. Snapshot capture/restore, file backing, whole-VM offload, KSM advice and cold-page paths have explicit incompatibility checks. Callers select supported profiles; combinations do not switch automatically at runtime. +The Linux daemon enables raw-page sharing explicitly with `serve --memory-pool`; it does not require userfaultfd. Per-instance live compression and `--memory-pool-mode compressed` use userfaultfd. The sealed pool has component-level service-loss tests and a passing two-VM probe covering eviction/refault and file I/O after service termination; the equivalent sealed pooling is not delivered on macOS, and production-density and latency acceptance remain open. Snapshot capture/restore, file backing, whole-VM offload, KSM advice and cold-page paths have explicit incompatibility checks. Callers select supported profiles; combinations do not switch automatically at runtime. [VM memory benchmarks](../../benchmarks/vm-memory/index.md) retain sharing and offload evidence by configuration, samples and accounting scope. Ready-stage savings do not guarantee lower lifecycle peaks, and writes reduce sharing. [Proofs of concept](proof-of-concept.md) retain historical mechanisms and failures; [Environment snapshots](../environment-snapshot.md) define complete-state contracts. ## System connections and source map {#integration} -Mappings and block state stay inside the VM; pools and stores supply referenced content. Virtual devices join the same quiescence boundary through RAM leases. [Complete snapshots](../environment-snapshot.md#consistent-cut) additionally combine CPU, RAM, devices and files. [Daemon admission](../daemon/admission.md) must budget private pages, shared services and restore peaks across the node, rather than converting a local compression ratio directly into concurrency. +Mappings and block state stay inside the VM; pools and stores supply referenced content. Virtual devices join the same quiescence boundary through RAM leases. [Complete snapshots](../environment-snapshot.md#consistent-cut) additionally combine CPU, RAM, devices and files. [Daemon admission](../daemon/index.md#admission) must budget private pages, shared services and restore peaks across the node, rather than converting a local compression ratio directly into concurrency. Source entries: `crates/pvisor-vm/src/memory.rs`, `handle.rs`, `cold_ram_linux.rs`, `ram_dedup.rs` and `devices/virtio/memory_gate.rs`. `api.rs` defines interfaces and lifecycles; [Shared working sets](../daemon/shared-working-set.md) covers daemon object budgets and process ownership. diff --git a/docs/src/en/design/memory-optimization/offload-format.md b/docs/src/en/design/memory-optimization/offload-format.md deleted file mode 100644 index 680ae9c6..00000000 --- a/docs/src/en/design/memory-optimization/offload-format.md +++ /dev/null @@ -1,60 +0,0 @@ -# Offload file format - -The storage layout determines what can be read back, published and safely deleted. -A raw file favors simplicity; a compressed base/delta bundle trades that simplicity for reuse. - -## Two storage models {#storage-models} - -Raw backing stores RAM bytes at the VMM's compact file offsets, without a pVisor format header. -It is directly mappable, but logical length is not allocated disk space: the file can be sparse. -Neither a raw RAM file nor a compressed bundle includes the complete state of a recoverable VM. - -In compressed mode the manifest identifies the sidecar directory and committed head. -Immutable generations hold a full base followed by deltas that inherit unchanged blocks. -Writable staging holds new raw pages; FUSE combines those pages with committed content -into the logical RAM file used by the live instance. Staging is not a historical snapshot. - -## Random reads and integrity {#reads-and-integrity} - -A block index resolves the latest source in the chain; a seek table locates its compressed frame. -Uniform blocks use fill entries. Reads validate metadata, ancestry, decoded length and block -checksums instead of decoding the entire RAM image. Integrity detects corruption, not a complete -VM checkpoint or an atomic capture of CPU, devices and external effects. - -Current staging uses 4 KiB pages and compression uses 64 KiB blocks; host pages are separate. -Small units reduce partial-write and cold-read amplification but increase indexes and bookkeeping. -Large units can improve compression and reduce metadata, but a small access may decode a whole -block. [Local compression](compression-local.md) discusses the related memory/CPU tradeoff. - -## Publication and retention {#publication-and-retention} - -The writer flushes logical-file writes into staging, builds and synchronizes a new generation, -then publishes it without replacing an existing generation before appending a manifest head. -FUSE writeback or fsync alone does not publish a committed epoch; offload coordinates that boundary. -Immutability keeps published bytes stable, but it does not by itself keep their files alive. - -GC currently retains the current head and ancestors plus explicitly pinned historical roots. -Old manifest head records are not retention roots, and standard offload does not automatically pin. -Reader leases are a lifecycle requirement for future concurrent inspection or portable bundles, -not a new lease facility promised by this format. Current inspection requires a stopped writer. -The separate [full environment snapshot](../environment-snapshot.md) store has its own restore leases. - -## Compaction and capacity {#compaction} - -Deltas reduce repeated storage, but deepen dependencies. Current depth-triggered compaction builds -a new full base while the VM is paused, decoding old blocks and encoding the entire logical RAM. -Budget for the old chain, new base under construction, staging and pinned history simultaneously. -Do not count the temporary file and its published name as two copies of the same new generation. -Small deltas do not predict compaction latency, peak space or cold-read decode amplification. - -## Current limits and design direction {#status} - -The manifest currently stores an absolute sidecar path; copying or aliasing it does not relocate -its dependencies. Open rejects a torn head-log tail rather than automatically falling back. -Staging validity masks live only in memory, and dirty kernel pages may not yet be staged; -normal exit does not commit post-resume writes. These files are not a crash-atomic full-VM archive. - -Portable references, recovery-safe publication and coordinated reader/GC leases are future goals, -not capabilities established by these pages. See the [architecture](index.md) and -[RAM offload](offload.md) for scope; the existing [byte layout and schema appendix](../offload/disk-layout-and-schema.md) -owns binary fields, size formulas and parser limits rather than duplicating them here. diff --git a/docs/src/en/design/memory-optimization/offload.md b/docs/src/en/design/memory-optimization/offload.md index f802f064..d442ec46 100644 --- a/docs/src/en/design/memory-optimization/offload.md +++ b/docs/src/en/design/memory-optimization/offload.md @@ -45,7 +45,11 @@ This offload path must not be applied indiscriminately to snapshot-restored priv Raw backing lets the kernel write RAM bytes directly to the file and satisfy later page faults. The compressed path exposes a logical RAM file through FUSE: writeback stages raw pages, then offload commits changed blocks into a base/delta bundle; reads decode committed blocks. -[Offload file format](offload-format.md) explains the storage and publication model. +Staging currently uses 4 KiB pages while compression uses 64 KiB blocks: a small granularity +reduces partial-write and cold-read amplification; a large one improves compression and cuts +metadata, but a small access may decode a whole block. +[Offload file format](../offload/disk-layout-and-schema.md) defines the storage format, +publication model and parsing limits. Compression can reduce stored bytes, but adds encoding, checksums, staging I/O and FUSE work. Resuming adds block decoding to cold reads. Incompressible data, frequent rewrites and compaction diff --git a/docs/src/en/design/memory-optimization/proof-of-concept.md b/docs/src/en/design/memory-optimization/proof-of-concept.md index b6a758f1..5c3b741d 100644 --- a/docs/src/en/design/memory-optimization/proof-of-concept.md +++ b/docs/src/en/design/memory-optimization/proof-of-concept.md @@ -1,6 +1,6 @@ # Experimental proof of concept -Shared-baseline, COW, and cold-pool experiments provide foundations for memory optimization while exposing service availability, restoration contention, and physical-accounting limitations. [Memory optimization](index.md), [Memory deduplication](deduplication.md), and [Memory compression](compression.md) define the target architecture. The implementation, experiments, and failures below retain their version scope rather than establishing production guarantees for future approaches. +Shared-baseline, COW, and cold-pool experiments provide foundations for memory optimization while exposing service availability, restoration contention, and physical-accounting limitations. [Memory optimization](index.md), [Memory deduplication](deduplication.md), and [Per-instance compression](compression-local.md) define the target architecture. The implementation, experiments, and failures below retain their version scope rather than establishing production guarantees for future approaches. The current Linux daemon pool uses physical shared pages with COW; reads do not restore private copies. See the [daemon guide](../../guides/daemon/index.md#memory-pool) for activation and budgets. This page retains the macOS cold-compression and historical Linux mechanism records. diff --git a/docs/src/en/design/records-and-versions.md b/docs/src/en/design/records-and-versions.md index 474225de..7c0e850e 100644 --- a/docs/src/en/design/records-and-versions.md +++ b/docs/src/en/design/records-and-versions.md @@ -47,7 +47,7 @@ Public persisted fields are in [Run Bundle](../reference/run-bundle.md); event b Environment manifest versions describe different RAM/filesystem combinations. A maximum version of 5 does not mean every new snapshot writes 5. Stage profiles use v4 for raw RAM and v5 for compressed RAM; other profiles follow their field combinations. SDK readability of a storage format does not mean the current Job CLI can adopt arbitrary historical standalone snapshot stores. -[Job checkpoint design](job-checkpoint-cli.md#10-当前实现与验收边界) owns entries and compatible profiles. [Environment snapshots](environment-snapshot.md#storage-contract) owns machine and file references, [Offload format](memory-optimization/offload-format.md) owns RAM subformats, and [Shared image cache](shared-image-cache-storage.md) owns image metadata/content versions. +[Job checkpoint design](job-checkpoint-cli.md#10-当前实现与验收边界) owns entries and compatible profiles. [Environment snapshots](environment-snapshot.md#storage-contract) owns machine and file references, [Offload format](offload/disk-layout-and-schema.md) owns RAM subformats, and [Shared image cache](shared-image-cache-storage.md) owns image metadata/content versions. ## Control protocols and build identity {#control-protocols} diff --git a/docs/src/en/design/research/cluster-execution.md b/docs/src/en/design/research/cluster-execution.md deleted file mode 100644 index 863aae31..00000000 --- a/docs/src/en/design/research/cluster-execution.md +++ /dev/null @@ -1,41 +0,0 @@ -# Cluster-scale execution and centralized evidence - -Scale execution across hosts through **external orchestration**, while keeping each execution's boundary and evidence explicit. Kubernetes, Ray or a training framework may own host selection and business workflows; pVisor does not replace them with a distributed product control plane. - -## Local execution building blocks {#execution-flow} - -Ordinary `pvisor run` owns a Job/Run/Attempt through native executors, optional staging and Gateway, and produces execution records. The [single-node daemon](../daemon/index.md) instead owns local native VM sandbox admission, lifecycle, TTL and service endpoints. Its partial OpenSandbox profile does not automatically supply native Job semantics, VM restore, stage/apply, offload or centralized Run Bundles. - -Native node resources can retain immutable environment/backing ownership on one host, independently of the daemon. They do not share physical RAM across machines and are not integrated with the daemon backend. See [shared working sets](../daemon/shared-working-set.md). - -The earlier Controller/Worker implementation explored distributed execution and evidence delivery. Its archived measurements retain that historical scope; they do not describe the new daemon or validate a current distributed product. - -## Product and external integration boundaries {#boundary} - -| Layer | Current responsibility | Integration/validation remaining | -| --- | --- | --- | -| Native pVisor execution | Job lifecycle, executor controls, staging, optional Gateway and records | Orchestrator adapters and representative workload acceptance | -| Sandbox daemon | NativeRuntime VM admission, durable supervisor ownership, lifecycle and real-service proxy | Supplied/validated bootstrap and SDK profile; no stage/checkpoint API or density evidence | -| Native node resources | Same-host immutable ownership, pins and bounded warmth | Daemon wiring, full transient accounting and workload measurements | -| External orchestration | Host choice, queues, dependencies, retries and tenancy | Explicit execution/evidence handoff and business-effect reconciliation | -| Evidence/checkpoint repositories | Native integrity, publication and retention contracts | Central collection, authorization, replication and cross-host compatibility | -| Review/release services | Consume explicitly retained outputs | Baseline checks, selective acceptance, business reconciliation and publication | - -A local record path or uploaded JSON is not a complete transfer of files. A downloadable checkpoint does not prove arbitrary-host restore compatibility. Define pinned inputs, runtime profiles, model versions and storage authorization before interpreting recovery as equivalent execution. - -## Experiments to design {#validation} - -Compare external orchestration using pVisor execution boundaries against pinned Kubernetes/Ray or training-framework baselines. Fix workloads, resources, models and output checks; measure useful completion throughput, first-result/restore tails, whole-group memory and centralized-review cost. Extend [concurrent-density methodology](../../benchmarks/density.md), without extrapolating daemon gains from historical empty tasks or native sharing mechanisms. - -Inject host loss, daemon/orchestrator downtime, partitions, full disks, interrupted collection and credential revocation. Track orchestrator work identity, local sandbox or Job/Run/Attempt identity, native observations and artifacts separately. A timeout or control identity does not prove external effects stopped; retry policy must reconcile unknown effects. - -No cross-host recovery, exactly-once external effects or daemon density advantage is established by this research direction. Current daemon [operations](../daemon/operations.md) define only local behavior. - -## Research questions {#research} - -- What minimal handoff preserves requested policy, installed controls, observed outcomes and complete evidence between execution and orchestration? -- Which retained inputs and runtime compatibility checks make a restore portable, and which effects require business reconciliation rather than replay? -- How much supervision does batch review save at fixed correctness and audit coverage, including collection and storage costs? -- Does immutable sharing or bounded laziness improve first useful result and full completion under equal total resources? - -See [parallel agents](../../guides/parallel-agents.md) for local workflows and [RL execution substrate](rl-execution-substrate.md) for training integration. Research plans do not create a product scheduler or substitute for production acceptance. diff --git a/docs/src/en/design/research/design-documents.md b/docs/src/en/design/research/design-documents.md deleted file mode 100644 index c0873883..00000000 --- a/docs/src/en/design/research/design-documents.md +++ /dev/null @@ -1,58 +0,0 @@ -# Open-source design references - -[ByteHook’s project introduction and principles](https://github.com/bytedance/bhook/blob/main/doc/overview.zh-CN.md) is the main writing reference for pVisor’s design chapter. It establishes prerequisite low-level models, diagrams objects and calls, then explains engineering choices and constraints. Readers reach implementation through causal reasoning. - -For pVisor, the sequence is execution problems and ownership → VMs, vCPUs and virtio → memory mappings, sharing and faults → filesystems, images and network requests → snapshot consistency and journal commits → costs and experiments. Figures should show actual buffers, files, queues, references and state changes; prose follows each figure to explain why its steps are necessary. - -[Design and underlying mechanisms](../index.md) connects these layers through a task that reads a file, accesses HTTPS and writes configuration. The projects below supply narrower references that complement this continuous explanation. - -## Projects and specific articles {#projects} - -These are recommendations about writing and organization, rather than project-quality or performance rankings. Sources were visited on 2026-10-07; implementation details retain each project's stated revision scope. - -| Project and article | Useful writing practice | Application to pVisor | -| --- | --- | --- | -| [ByteHook · Introduction and principles](https://github.com/bytedance/bhook/blob/main/doc/overview.zh-CN.md) | Derives mechanisms from prerequisite models, diagrams objects and calls, and explains constraints | Connect syscalls, virtqueues, backing, preimages and commit points to the complete execution path | -| [TigerBeetle · Architecture](https://github.com/tigerbeetle/tigerbeetle/blob/main/docs/ARCHITECTURE.md) | Starts with workloads and constraints, then explains persistence and decisions through an overall model | Describe reuse, writes, failure and budgets before slots/references, Journal and snapshots | -| [Firecracker · Design](https://github.com/firecracker-microvm/firecracker/blob/main/docs/design.md) | Connects host integration, processes/threads and devices, showing fast paths and host responsibilities | Show API, supervisors, VMs, devices and pools; explain control and data paths separately | -| [gVisor · Architecture guide](https://gvisor.dev/docs/architecture_guide/intro/) | Uses syscall examples to explain Sentry/host relationships, mechanisms and compatibility | Trace one file/network request through actual interception and Host/OCI/VM coverage | -| [Tokio · Runtime](https://docs.rs/tokio/latest/tokio/runtime/index.html) | Moves from usage to thread lifetimes, fairness assumptions and scheduler behavior, separating guarantees from implementation | Explain waiter cancellation, accepted operations, completion tasks and runtime shutdown | -| [etcd · Client design](https://etcd.io/docs/v3.6/learning/design-client/) | Explains connections and requests through client responsibilities, errors and retries | Describe lost ACKs, Unknown, request IDs, retries and reconciliation; locate ambiguity in sequences | -| [Ray · Architecture whitepapers](https://docs.ray.io/en/latest/ray-contribute/whitepaper.html) | Separates overall architecture from internal topics and retains whitepaper versions | Separate orchestration, node ownership, execution paths and research; retain proposal status | -| [Rust Compiler Development Guide · Overview](https://rustc-dev-guide.rust-lang.org/overview.html) | Moves from processing flow to queries, data structures and source entry points, identifying simplifications | Trace Job/Attempt calls into core data, lifecycle and implementation files | -| [CockroachDB · Design](https://github.com/cockroachdb/cockroach/blob/master/docs/design.md) | Layer diagrams connect data abstractions, components and physical layout, with historical limits | Explain logical Jobs, persistent records and backing objects; identify historical designs | - -Choose narrower references by the question: Firecracker for host integration, Tokio for concurrency guarantees, etcd for failed requests and retries. Keep pVisor’s own data and execution paths as the narrative, so readers can understand behavior without first memorizing a component catalog. - -## Explaining one mechanism completely {#structure} - -![From problems and hypotheses to mechanisms, experiments and scoped conclusions](../assets/research-cycle.svg) - -1. **Problem and constraints.** Who encounters which cost? Which resources and trust assumptions are fixed? -2. **Minimal system model.** Who owns state, may mutate it and must release it? -3. **Normal flow.** Trace one real request through calls, data, commit points and results. -4. **Failure flow.** Explain retained state and reconciliation after cancellation, disconnects, write failure and process exit. -5. **Tradeoffs.** Describe costs removed and introduced, plus where alternatives fit. -6. **Implementation and evidence.** Provide source entry points and materials; distinguish behavior, workload results and proposals. - -For Journal, explain event identities and idempotent retries before diagramming append, write, sync and receipts. Write failure retains Unknown; retrying the same event does not create a second record. Readers can understand failure semantics without interpreting LocalSync as remote replication. [Journal design](../journal.md) owns the detailed contract. - -## Choosing figures and their detail {#figures} - -| Reader's question | Suitable figure | Essential information | -| --- | --- | --- | -| Who owns each responsibility? | Layer or ownership diagram | Owners, boundaries, call direction and external dependencies | -| How does an operation complete? | Sequence or lifecycle diagram | Acceptance, commit, confirmation, cancellation and return | -| Where is data stored? | Physical layout or mapping diagram | Objects, references, offsets, private/shared state and reclaim conditions | -| What survives a crash? | Failure-state diagram | Durable intent, live observations, Unknown and reconciliation | -| Why is it cheaper or slower? | Sourced experiment figure | Budget, baseline, samples, failures, peaks and applicable workload | - -Each figure answers one main question. Arrows identify calls, data, references or state changes; each figure explicitly defines its solid and dashed lines. SVG retains searchable text and scalable geometry; prose supplies an example and the main tradeoff. Component relationships should map to code or contracts. - -The overall architecture matches the documentation with a navy background, blue-gray layers, light-blue headings and nested rounded shapes. Execution mechanisms remain the visual focus, with distinct outlines expressing nesting. Within `pvisor-vm`, vCPUs, RAM and virtual devices appear side by side, above their coordinated freeze and platform adaptation. Shared contracts and optional extensions remain supporting annotations. VM, memory, filesystem and network block diagrams reuse this visual language to expand their respective boundaries. Each topic explains the diagram and ownership, one access path, core data and mechanisms, failure and cleanup, then system connections and source entry points. Detailed mechanism figures use a textbook layered style: blue bands of different brightness separate execution layers, address spaces or phases; dark cards represent concrete objects; corresponding objects stay aligned across layers or before/after states. Numbers connect to the prose, and labels also express color meanings. Sequence diagrams retain their time axis, byte layouts retain offsets and proportions, and long figures split into independently readable details. - -Figures use `#0d1b30` for the canvas, `#142840` for cards, `#a8cefa` for accents and `#e9eef8` for text, matching the site theme. Teal, amber and muted red retain each figure's distinctions between states such as sharing, changes and conflicts, alongside text labels. SVGs contain their complete palette so standalone viewing and PNG exports retain the same appearance. - -## Separate designs, decisions and research {#status} - -Implementation designs describe current ownership and behavior; [ADRs](../decisions/index.md) retain context, options and consequences; research retains hypotheses, experiments and counterexamples. External articles guide expression. pVisor's implementation status and performance claims remain constrained by its own revisions and evidence. diff --git a/docs/src/en/design/research/index.md b/docs/src/en/design/research/index.md index ba7a6334..cddfbf2b 100644 --- a/docs/src/en/design/research/index.md +++ b/docs/src/en/design/research/index.md @@ -10,9 +10,19 @@ A useful hypothesis specifies workloads and counterexamples. VMs with equal base ## Execution and orchestration ownership {#ownership} -pVisor owns individual execution boundaries and observations; the node-local daemon owns sandbox identity and lifecycle. External orchestration owns host selection, queues, dependencies and application retries; trainers own models, sampling, reward and evaluator versions. The [daemon API](../daemon/index.md) does not expose native Job staging, execution checkpoints or Run Bundle export, so research integration needs an explicit execution/evidence handoff. +pVisor owns individual execution boundaries and observations; the node-local daemon owns sandbox identity and lifecycle. External orchestration (Kubernetes, Ray or training frameworks) owns host selection, queues, dependencies and application retries; trainers own models, sampling, reward and evaluator versions. pVisor does not replace them with a distributed product control plane. -A proposed adapter binds external work identities to local Jobs/Attempts or sandboxes, pins inputs and runtime revisions, and collects results with artifacts. Timeouts and disconnects preserve unknown outcomes for reconciliation before retry. [External orchestration research](cluster-execution.md) examines this handoff; placement remains external. +The [daemon API](../daemon/index.md) does not expose native Job staging, execution checkpoints or Run Bundle export, so research integration needs an explicit execution/evidence handoff. Current responsibilities and open items per layer: + +| Layer | Current responsibility | To integrate / validate | +| --- | --- | --- | +| Native pVisor execution | Job lifecycle, executor control, staging, optional Gateway and recording | Orchestration adapters and representative workload acceptance | +| Sandbox daemon | NativeRuntime VM admission, persistent supervisor identity, lifecycle and real service proxy | Bootstrap provisioning/validation and SDK profiles; no stage/checkpoint API or density evidence | +| Native node resources | Node-local immutable ownership, pins and bounded warming | Daemon integration, complete transient accounting and workload measurement | +| External orchestration | Host selection, queues, dependencies, retries and tenants | Explicit execution/evidence handoff and business side-effect reconciliation | +| Evidence/checkpoint stores | Native integrity, publication and retention contracts | Centralized collection, authorization, replication and cross-host compatibility | + +A local record path or an uploaded JSON does not represent complete file transfer; a downloadable checkpoint does not prove compatible restoration on an arbitrary host. Archived measurements from the retired Controller/Worker implementation keep their historical scope and do not describe the current daemon. ## Three kinds of state and evaluation {#state} @@ -22,7 +32,15 @@ A proposed adapter binds external work identities to local Jobs/Attempts or sand | Agent trajectory | Model context and tool history | Prefix preparation, re-execution differences and model continuation | | VM execution checkpoint | CPU/RAM/device/file state of supported profiles | Consistency, compatibility, restoration and fork costs | -Tool re-execution produces fresh observations; remote service state and training metadata are retained separately. Execution success, task reward and file acceptance are evaluated independently; see the [RL substrate](rl-execution-substrate.md) for the proposed integration. +Tool re-execution produces fresh observations; remote service state and training metadata are retained separately. Execution success, task reward and file acceptance are evaluated independently: reward is computed by the evaluator, and a pVisor success is only an execution result. + +## The execution contract of one rollout {#rollout-contract} + +Inputs include the task ID, attempt ID, repository commit or image digest, workspace, agent command, policy, resource budget and random seed. Outputs include the end state, exit code, file candidates, the Run Bundle, the native trajectory, and the Gateway Journal when capture is enabled. The trainer associates these artifacts with model versions, sampling parameters, reward and evaluator versions. Environment-preparation failures, permission denials and upstream request failures have their own categories; infrastructure failures are handled by predetermined rules when evaluating model problem-solving. + +The minimal integration order: first follow the [rollout guide](../../guides/rl-rollouts.md) to collect and score candidates for one offline task; then increase concurrency with separate workspaces so each attempt's files and records stay independent; finally attach native Agent trajectories and validate prefix preparation, tool re-execution and model continuation separately. Replay tools produce fresh observations, so a replayed run's new observations and the old session text are not simply the same experimental input. + +What still needs experimental evidence: completed rollouts per second, tail latency, disk and resident memory per candidate, fork/checkpoint cost, tool re-execution cost and reward delta. Pin model-serving capacity and separate substrate bottlenecks from model-serving bottlenecks. Async queues, cross-node fault tolerance, reward deduplication, shared-prefix benefits and large-scale sampling still require integration and measurement. ## Levels of benefit evidence {#evidence} @@ -33,8 +51,17 @@ Tool re-execution produces fresh observations; remote service state and training - **Product evidence:** include preparation, SDKs, guest services, reclamation, sustained concurrency and failure scope. - **Supervision evidence:** measure actual review effort, rejection and rework; machine CPU cost does not measure human attention. -Native pool or offload probes alone do not establish complete daemon density. Controller/Worker data retains its historical identity. Orchestration and RL adapters remain research/planning work, with benefits requiring their own workload validation. +Native pool or offload probes alone do not establish complete daemon density. Orchestration and RL adapters remain research/planning work, with benefits requiring their own workload validation; when injecting host loss, daemon/orchestrator downtime, partitions or full disks, a timeout or control identity does not prove that external side effects stopped, and retry policies must reconcile unknown side effects. This direction establishes neither cross-host restoration, exactly-once external side effects, nor daemon density advantages. + +## Research questions {#questions} + +- What minimal handoff between execution and orchestration preserves requested policy, installed controls, observed results and complete evidence? +- Which retained inputs and runtime compatibility checks make restoration portable, and which side effects need business reconciliation instead of replay? +- Under fixed correctness and audit coverage, how much supervision cost does batch review save, including collection and storage costs? +- Under the same total resources, can immutable sharing or bounded on-demand loading improve first useful results and complete completions? + +Research plans do not create a product scheduler and do not replace production acceptance. -## Using designs and papers {#references} +## Public materials and writing references {#references} -[Public research outputs](publications.md) retain materials, revisions and experiment scope; no formal papers, external reports or talks are registered yet. [Open-source design references](design-documents.md) explain problem statements, layer diagrams, sequences, failure semantics and tradeoffs without turning writing practices into product guarantees. +No formal papers, external reports or talks are currently registered; the public technical material is the design documentation and benchmark evidence in this repository (for example [replay fidelity](../../benchmarks/replay-fidelity.md)). Cite conclusions with the report date, machine, executor, workload and statistical scope. Design-writing practice and open-source expression references are maintained in the repository's [docs/README.md](https://github.com/DeepLink-org/pvisor/blob/main/docs/README.md) and are not repeated here. diff --git a/docs/src/en/design/research/publications.md b/docs/src/en/design/research/publications.md deleted file mode 100644 index 00300024..00000000 --- a/docs/src/en/design/research/publications.md +++ /dev/null @@ -1,25 +0,0 @@ -# Papers, reports, and talks - -pVisor's public technical material currently consists of repository designs and engineering experiments. Use these records to understand execution mechanisms, select experiment subjects, and trace results to their source revisions and environments. - -## Existing engineering material {#materials} - -The [Replay fidelity report](../../benchmarks/replay-fidelity.md) measures short-prefix preparation for pinned trajectory formats: it checks historical boundaries, command arguments and tool observations, and records elapsed time from CLI launch through preparation exit. `prepare-only` executes no tools, starts no Agent and leaves the workspace unchanged. Use these results to select historical context inputs; the [Replay design](../replay.md) explains the responsibilities of prefix preparation, tool re-execution and live continuation. - -The [RAM offload appendix](../offload/index.md#experiments) retains the 2026-10-03 storage/control checks and a compressed backing sample. Use it to study publication order, base/delta inheritance and storage-size accounting. The record separately lists passing mechanism checks, tests blocked before guest execution, and the sample files' logical sizes and allocated space. - -Retired [Controller/Worker evidence](../cluster-performance-analysis.md) provides historical measurements of frozen artifacts. Readiness probes describe VM readiness time; history-query measurements describe query and warm-replay costs for retained records. Completed-task cohorts retain their own provenance and statistical definitions. Cite data separately by experiment subject and cohort. - -Specific measurement gaps: the replay report has not measured fidelity of continuation with a real model; the offload sample has not measured net physical-memory savings or multi-VM density; current daemon performance and density await independent experiments. - -## Record a new public output {#record} - -Each entry needs title, authors or speaker, publication date, public link, material type, source commit, agent/model versions, data and reproduction entry, and conclusion scope. Papers should include venue and DOI; identify preprints, engineering reports, and talks by type. - -If research uses an unreleased branch, record its commit and differences from the release. Preserve the original record when implementation changes, adding new validation or a superseding explanation. - -## How to cite {#citation} - -Cite performance conclusions with report date, hardware, executor, task, and statistical definitions. Cite designs with a source commit or release version. Retain the environment conditions for effects observed in a specific environment. - -No formal paper, external report, or talk is currently registered here. Contributions should provide accessible links and reproduction details using the fields above. Distinguish a design proposal, a passing mechanism test and a measured workload result when citing them; implementation guarantees belong to the matching version's documentation and tests. diff --git a/docs/src/en/design/research/rl-execution-substrate.md b/docs/src/en/design/research/rl-execution-substrate.md deleted file mode 100644 index eb6062b1..00000000 --- a/docs/src/en/design/research/rl-execution-substrate.md +++ /dev/null @@ -1,31 +0,0 @@ -# An execution substrate for reinforcement learning - -Agent training needs traceable attempts: their starting inputs, tool calls, results, and reasons for stopping. pVisor can provide individual execution and evidence collection while the trainer retains reward, sampling, and scheduling in its control layer. - -## The execution contract for a rollout {#contract} - -Inputs include task ID, attempt ID, repository commit or image digest, workspace, agent command, policy, resource budget, and seed. Outputs include terminal status, exit code, candidate files, Run Bundle, native trajectory, and a Gateway Journal when capture is enabled. - -The trainer associates these artifacts with model version, sampling parameters, reward, and evaluator version. Setup failures, permission rejection, and upstream failures have distinct categories; evaluate model task-solving ability using predetermined handling for these infrastructure failures. - -## Three kinds of reusable state {#state} - -| State | What it reuses | What must be saved separately | -| --- | --- | --- | -| File checkpoint | Candidate files and staged layers over a fixed baseline | Model context and external service state | -| Native agent trajectory | Session lineage, tool calls, and observations | Resettable workspace, agent and model versions | -| VM snapshot | VM runtime state supported by the specific implementation | Scheduler metadata, model service, and remote side effects | - -Re-executing tools produces fresh observations. Reproducibility experiments should fix inputs and versions while recording those differences; fresh replay observations and old session text cannot simply be treated as identical experimental inputs. - -## A minimal integration sequence {#integration} - -Start with the [rollout guide](../../guides/rl-rollouts.md) to collect and score one offline candidate. Increase concurrency with independent workspaces and verify that every attempt has separate files and records. Then add native agent trajectories and validate prefix preparation, tool re-execution, and model continuation separately. - -The evaluator calculates reward. Successful pVisor completion is an execution outcome; task scores require task-specific tests, and file changes must be judged against the task requirements. - -## What experiments must establish {#experiments} - -Measure completed rollouts per second, tail latency, candidate storage and resident memory, fork/checkpoint cost, tool replay cost, and reward delta. Fix model-service capacity and distinguish substrate bottlenecks from model-service bottlenecks. - -Asynchronous queues, cross-node recovery, reward deduplication, shared-prefix benefits, and large-scale sampling need integration and measurement. See [Replay fidelity](../../benchmarks/replay-fidelity.md), [Concurrent density](../../benchmarks/density.md), and [Cluster execution](cluster-execution.md) for methods. diff --git a/docs/src/en/design/vm-memory-performance-analysis.md b/docs/src/en/design/vm-memory-performance-analysis.md index fc18f391..41af6c40 100644 --- a/docs/src/en/design/vm-memory-performance-analysis.md +++ b/docs/src/en/design/vm-memory-performance-analysis.md @@ -1,5 +1,7 @@ # Memory deduplication curves: Firecracker, Docker and pVisor +> Note: local `.data/` paths refer to local measurement archives that are not published with the repository or the site; they are kept for batch provenance only. + ## Linux: preflight of deduplication speed, compression and shared libraries {#linux-pool-curves} ### Observed benefits and costs {#pool-findings} diff --git a/docs/src/en/design/vm-startup-performance-analysis.md b/docs/src/en/design/vm-startup-performance-analysis.md index b188860f..ff181024 100644 --- a/docs/src/en/design/vm-startup-performance-analysis.md +++ b/docs/src/en/design/vm-startup-performance-analysis.md @@ -1,5 +1,7 @@ # VM startup: technical analysis and experiment records +> Note: "local original records" and paths such as `docs/src/assets/benchmarks/.data/` refer to local measurement archives that are not published with the repository or the site; they are kept for batch provenance only. + ## Linux: startup and exit fixes retest, 2026-10-11 {#concurrency-retest} **Exit cleanup has a measured benefit, but startup regressions are not fully resolved.** Against the `cf8bfa5` GNU artifact, host Ready improves by about 9.11 ms and Exit by 75.00 ms. VM Exit improves by about 48.26 ms, with no detected Ready improvement. New staged Ready has two separated clusters and cannot be declared restored. @@ -339,13 +341,13 @@ Linux / KVM, 2 vCPU / 2 GiB, the same two-core host budget, 30 samples for each **QEMU boots the same complete Ubuntu, rather than the historical trimmed kernel.** q35 and microvm share Firecracker's stock kernel, initrd, tools and initialized disk template. A minimal device model does not remove seconds of distribution boot in this configuration. These are independent same-host cohorts; QEMU has N=10, background host load remains, and outliers are retained. Similar medians do not support a precise VMM ranking. QEMU first cloud-init boot is unmeasured. -Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-qemu-20261004/samples.csv` · [QEMU protocol](../benchmarks/methodology.md#full-ubuntu-qemu) +Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-qemu-20261004/samples.csv` · [QEMU protocol](../benchmarks/index.md#full-ubuntu-qemu) **Selection meaning:** Creating environments for one or two commands benefits from avoiding seconds of OS boot. Complete Ubuntu provides distribution services and an independent Ubuntu environment at that startup cost. These are deployment paths with different kernels, initialization and storage; the table does not establish a roughly 50-times VMM advantage for libkrun. For longer jobs, compare [task and internal tool time](../benchmarks/agent-tasks.md#full-ubuntu), where boot cost is amortized. Exit includes normal shutdown: pVisor P50 is 174 ms, Firecracker/Ubuntu about 9.23 / 12.86 seconds. Firecracker/Ubuntu uses default MMIO devices and the stock initrd, with zero VMM exit after guest reboot. Every trial retains full OS proof with no failed units. Workspace copying or private disk cloning is recorded as `prepare_ms`, with medians around 37 / 29 ms outside Ready. The chart uses a logarithmic axis, bars P50 and ticks P95. With N=30, P99 is near the maximum and describes this batch only. -Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/summary.tsv` · [Method and reproduction](../benchmarks/methodology.md#full-ubuntu) · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/ubuntu-ready-mmio-20261004/evidence.tar.gz` +Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/summary.tsv` · [Method and reproduction](../benchmarks/index.md#full-ubuntu) · Local raw record `docs/src/assets/benchmarks/.data/full-ubuntu-20261004/ubuntu-ready-mmio-20261004/evidence.tar.gz` #### New VM startup results {#linux-results} @@ -389,7 +391,7 @@ QEMU q35's 218 ms does not establish QEMU's minimum startup cost: microvm with o **First output does not establish that an Agent can complete a task.** Seven-tool version checking takes 1.40 seconds in pVisor VM. See the [complete tool environment](../benchmarks/agent-tasks.md#reference-env) for repair/test timing and CLI compatibility. The preceding 172.69 ms GNU/libkrunfw 5.5.0 batch remains historical evidence. This batch uses a new pinned static artifact; it is not a controlled single-configuration optimization experiment. -[Configuration and reproduction](../benchmarks/methodology.md#reference-env) · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/summary.tsv` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/evidence.tar.gz` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/compatibility.tsv` +[Configuration and reproduction](../benchmarks/index.md#reference-env) · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/samples.csv` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/summary.tsv` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/evidence.tar.gz` · Local raw record `docs/src/assets/benchmarks/.data/reference-env-20261004/compatibility.tsv` #### Full-exit follow-up: cleanup is separate from Ready {#reference-exit} diff --git a/docs/src/en/guides/agents/aider.md b/docs/src/en/guides/agents/aider.md deleted file mode 100644 index 4f7f159c..00000000 --- a/docs/src/en/guides/agents/aider.md +++ /dev/null @@ -1,17 +0,0 @@ -# aider - -!!! note "Experimental" - The commands below use only existing pVisor options, but no pinned Agent-version end-to-end regression has been run yet. - -## Integration starting point using the existing CLI - -Install aider inside the selected executor and verify it runs in an independent test project. The target below is api.openai.com:443; the example assumes you already selected the matching OpenAI service in the agent's own configuration — pVisor does not configure providers for you. - -```bash -pvisor run --safe --overlaynet-allow api.openai.com:443 \ - --pass-env OPENAI_API_KEY -- aider -pvisor status --review last -pvisor apply last --path src -``` - -Explicit allow replaces safe preset lists. Add authentication/provider/dependency destinations individually. Only the direct executable name selects adaptation; shell wrappers change matching. Safe HOME writes are discarded, so do not depend on persistent login state from this run. diff --git a/docs/src/en/guides/agents/gemini-cli.md b/docs/src/en/guides/agents/gemini-cli.md deleted file mode 100644 index 70eec9eb..00000000 --- a/docs/src/en/guides/agents/gemini-cli.md +++ /dev/null @@ -1,17 +0,0 @@ -# Gemini CLI - -!!! note "Experimental" - The commands below use only existing pVisor options, but no pinned Agent-version end-to-end regression has been run yet. - -## Integration starting point using the existing CLI - -Install Gemini CLI inside the selected executor and verify it runs in an independent test project. The target below is generativelanguage.googleapis.com:443; configure the model provider in the agent itself — pVisor does not do that for you. - -```bash -pvisor run --safe --overlaynet-allow generativelanguage.googleapis.com:443 \ - --pass-env GEMINI_API_KEY -- gemini -pvisor status --review last -pvisor apply last --path src -``` - -Explicit allow replaces safe preset lists. Add authentication/provider/dependency destinations individually. Only the direct executable name selects adaptation; shell wrappers change matching. Safe HOME writes are discarded, so do not depend on persistent login state from this run. diff --git a/docs/src/en/guides/agents/index.md b/docs/src/en/guides/agents/index.md index 5f183e46..59d6089e 100644 --- a/docs/src/en/guides/agents/index.md +++ b/docs/src/en/guides/agents/index.md @@ -14,15 +14,28 @@ pvisor apply last --path src | --- | --- | --- | --- | | Claude Code | `claude` | `api.anthropic.com` | [Claude Code](claude-code.md) | | Codex CLI | `codex` | `api.openai.com`, `chatgpt.com`, `ab.chatgpt.com` | [Codex CLI](codex.md) | -| Gemini CLI | `gemini` | `generativelanguage.googleapis.com` | [Gemini CLI](gemini-cli.md) | +| Gemini CLI | `gemini` | `generativelanguage.googleapis.com` | See [`--safe` presets](../../reference/cli.md#safe-参数预设) | | ZCode | `zcode` | `api.z.ai`, `open.bigmodel.cn` | See [`--safe` presets](../../reference/cli.md#safe-参数预设) | -| aider | — | No preset; needs `--overlaynet-allow` | [aider](aider.md) | -| OpenCode | — | No preset; needs `--overlaynet-allow` | [OpenCode](opencode.md) | +| aider | `aider` | No preset; needs `--overlaynet-allow` | See "Agents without presets" below | +| OpenCode | `opencode` | No preset; needs `--overlaynet-allow` | See "Agents without presets" below | | Any script | Any | None; `bash`, `sh`, `zsh`, `fish` reuse the Codex destinations | [Any script](custom-scripts.md) | Unknown commands deny outbound access. `--overlaynet-allow HOST:PORT` grants it explicitly and replaces preset lists. Matching uses the **direct executable filename**; shell wrappers do not trigger agent-specific adaptation. +## Agents without presets {#custom-agent} + +Take aider as the example: install it in the selected executor, pick the provider in the agent's own configuration, then explicitly allow its API destination and pass the credential variable (variable names come from the agent's own documentation, such as `OPENAI_API_KEY` or `GEMINI_API_KEY`): + +```bash +pvisor run --safe --overlaynet-allow api.openai.com:443 \ + --pass-env OPENAI_API_KEY -- aider +pvisor status --review last +pvisor apply last --path src +``` + +Logins, other providers and dependency downloads each need their own allowed destination. + After a run, check the installed controls and observations in the Run Bundle. Supported agent version ranges are not systematically tested; see [end-to-end tasks](../../benchmarks/agent-tasks.md). !!! note "Experimental integrations" - The aider, Gemini CLI, and OpenCode guides use only existing pVisor options and stay experimental until a pinned-version regression exists. The Linux host selective proxy is cooperative; use a prepared VM when you need enforcement. + The aider, Gemini CLI, and OpenCode integrations use only existing pVisor options and stay experimental until a pinned-version regression exists. The Linux host selective proxy is cooperative; use a prepared VM when you need enforcement. diff --git a/docs/src/en/guides/agents/opencode.md b/docs/src/en/guides/agents/opencode.md deleted file mode 100644 index 17f5b253..00000000 --- a/docs/src/en/guides/agents/opencode.md +++ /dev/null @@ -1,17 +0,0 @@ -# OpenCode - -!!! note "Experimental" - The commands below use only existing pVisor options, but no pinned Agent-version end-to-end regression has been run yet. - -## Integration starting point using the existing CLI - -Install OpenCode inside the selected executor and verify it runs in an independent test project. The target below is api.openai.com:443; the example assumes you already selected the matching OpenAI service in the agent's own configuration — pVisor does not configure providers for you. - -```bash -pvisor run --safe --overlaynet-allow api.openai.com:443 \ - --pass-env OPENAI_API_KEY -- opencode -pvisor status --review last -pvisor apply last --path src -``` - -Explicit allow replaces safe preset lists. Add authentication/provider/dependency destinations individually. Only the direct executable name selects adaptation; shell wrappers change matching. Safe HOME writes are discarded, so do not depend on persistent login state from this run. diff --git a/docs/src/en/guides/daemon/boundaries.md b/docs/src/en/guides/daemon/boundaries.md deleted file mode 100644 index 6fb939ff..00000000 --- a/docs/src/en/guides/daemon/boundaries.md +++ /dev/null @@ -1,51 +0,0 @@ -# Daemon runtime and integration boundaries - -Choose `pvisor-daemon` for node-local native VM sandbox lifecycle, or `pvisor run` for the public Job/file-review workflow. The daemon embeds native execution but keeps separate API identities, state and capabilities. - -## Prepared-image contract {#images} - -Images are trusted local `images_dir/.json` manifests, not registry references. Fields are absolute independent Linux `rootfs` (never host `/` or overlapping daemon state), absolute guest bootstrap `entrypoint` argv, optional `cmd`, optional `env` and optional absolute firmware `library_dir`. Requested workload argv (or `cmd` if empty) is appended to `entrypoint`; request env overrides manifest env, without host environment inheritance or shell interpolation. - -The long-lived guest bootstrap must supervise workload, real OpenSandbox 1.1.0 execd and egress, initialize/authenticate services, forward signals and reap children. It must expose byte-transparent AF_VSOCK listeners on guest **CID 3**, ports **44772/18080**, bridging to real services. Supervisor loopback TCP publications connect through private Unix sockets and native vsock forwarding. A stock rootfs or sleeping process is insufficient. - -Create, Inspect of a Running VM and resume readiness checks require genuine HTTP 200 execd `/ping`, `/ready` with JSON `initialized: true`, and egress `/healthz` through the bridges, with bounded bodies. The daemon does not inject/initialize execd or synthesize command/SSE/file responses. Python SDK initialization resolves both endpoints even without network policy. - -Prepare the bootstrap and vsock bridges described above; an upstream image name alone cannot meet these requirements. The project **has not supplied a bootstrap or image recipe or performed end-to-end validation**; SDK-conformance validation and density measurements are also unavailable. This native VM backend does not use the old container `cap-drop=ALL` restriction. - -## Isolation and resource limits {#isolation} - -Requires Linux x86_64, usable `/dev/kvm`, trusted absolute paths and a writable delegated cgroup v2 hierarchy with enabled CPU/memory/PID controllers and `cgroup.kill`. Preflight checks real controller writes and the KVM API; there is no host, OCI command or registry-pull fallback. - -The native supervisor embeds `pvisor::PVisor` with only `VmExecutor` and holds its RunHandle in a detached subprocess. The sandbox cgroup caps the entire supervisor/VMM/helper tree: aggregate CPU rate **10–8000 millicores**, hard memory, zero swap, `pids.max=512` and group OOM. vCPU count rounds quota up to whole CPUs (at most 8); guest RAM rounds down to MiB, while the hard memory cap also includes host overhead. Full limit/readiness checks remain at create, Inspect and resume; endpoint lookup authenticates live Running state and deletion fences without repeating full health/cgroup checks per data request. See [service access](../../design/daemon/lifecycle.md#endpoints). Paused, failed and uncertain records retain conservative admission charges. - -The launch callback joins the identity-bound cgroup **before exec**, using a pre-opened `cgroup.procs` FD under the owner lock and checking started/deletion/tombstone markers. Supervisor startup verifies membership instead of moving an already-running Tokio process; supervisor/Tokio allocations and subsequent VM/helper children are charged inside the sandbox budget. Direct hidden-command invocation outside that cgroup fails closed. - -Native OverlayNet supplies VM outbound networking. OpenSandbox network-policy requests are unsupported and rejected; rejecting a request does not change egress to deny-all. - -The host account, daemon/firmware and prepared image must be trusted. Private state and same-UID IPC cannot block hostile same-UID or root code. Other local users may reach loopback publications, so configure service authentication and host access controls. Secrets stay out of supervisor argv and host environment but persist in private records. No security audit results are available; hostile multi-user isolation is outside the protection scope. - -Private IPC authenticates same-UID peers plus owner, sandbox ID, generation and secret token; durable identity binds boot ID and cgroup device/inode. IDs are never reused or relaunched. Lost IPC is uncertainty, not Missing or cleanup proof. Durable deletion intent and the supervisor exclusive lock fence late launch; cleanup uses identity-bound `cgroup.kill`, never a persisted PID or PID-based kill, and confirms an empty cgroup plus released lock before capacity release. Replaced or missing same-boot cgroups without durable tombstone proof do not prove absence. - -## OpenSandbox profile {#profile} - -Compatibility is pinned to OpenSandbox **1.1.0**, tag `release-1.1.0`, commit `b1a29cf93a823a95913f7943010febb3f29de05c`. Support is limited to the partial API profile below; full OpenSandbox and unmodified SDK end-to-end conformance have not been validated. - -| Capability | Current behavior | -| --- | --- | -| Image creation, list, inspect, delete | Local sandbox lifecycle; create accepts argv/env/metadata, CPU/memory limits and optional TTL | -| Pause / resume | Acknowledged live vCPU pause/resume on the same Attempt, not a checkpoint | -| Expiration renewal | Future RFC3339 deadline extending an existing TTL | -| Endpoints | Daemon-routed execd 44772 and egress 18080 only | -| Commands, files, health, metrics | Streamed to real upstream services in the prepared image | -| Snapshots, templates/pools, metadata mutation, hooks | Unsupported | -| Network policy, credential proxy, secure access, volumes, image auth | Unsupported creation options are rejected | -| Arbitrary application ports, signed endpoints, WebSocket, CONNECT | Unsupported | -| Stage/apply, checkpoint/fork, offload | Not integrated with this daemon backend | - -## Native VM, checkpoints and Gateway {#native} - -Native `pvisor run --executor vm` retains its KVM/HVF and rootfs requirements. The daemon uses the native VM executor, but does not expose these Job APIs. The [VM guide](../executors/vm.md) explains execution; [checkpoint and fork](../fork-checkpoint.md) covers local Job file checkpoints. Compatible owned-rootfs, no-network VM Jobs can use execution checkpoints; inspect `pvisor status --json` for capability and blockers, and follow the [CLI execution-checkpoint contract](../../reference/cli.md#full-vm-execution-checkpoints). - -A daemon pause is acknowledged vCPU pause on the same live Attempt, not a sealed RAM/CPU/device/filesystem snapshot. Daemon sandbox IDs are not Job IDs: do not pass them to `pvisor checkpoint`, `fork`, `apply` or `drop`. Native snapshot storage, node owners, shared image cache and the experimental macOS cold-page pool remain native facilities, not daemon templates or pools. - -For model request routing and capture in native Jobs, use the [Gateway guide](../capture.md) and [Agent integration](../agents/index.md). The daemon has no old Worker `gateway.routes` profile or integrated pVisor credential proxy/capture contract. Prepared services and applications own any model access; external API effects cannot be undone by file review. diff --git a/docs/src/en/guides/daemon/index.md b/docs/src/en/guides/daemon/index.md index ce70966a..21e240a5 100644 --- a/docs/src/en/guides/daemon/index.md +++ b/docs/src/en/guides/daemon/index.md @@ -1,20 +1,21 @@ # Run the single-node daemon -Install `pvisor-daemon` to manage image-based sandboxes on one Linux host through a partial OpenSandbox 1.1.0 API. It owns local admission, lifecycle, durable state and expiration. Use Kubernetes, Ray or your application for cross-node task scheduling, global DAGs and distributed leases; the daemon includes no Controller or Workers. +Install `pvisor-daemon` to manage image sandboxes on one Linux host through an API partially compatible with OpenSandbox 1.1.0. The daemon owns node-local admission, lifecycle, persistent state and expiration cleanup. Cross-node scheduling, global DAGs and distributed leases belong to Kubernetes, Ray or your application; the daemon contains no Controller or Worker. Choose `pvisor-daemon` for node-local native VM sandbox lifecycles; use `pvisor run` for the public Job/file-review workflow. +!!! warning + The project **has not supplied a guest bootstrap or image recipe and has not performed end-to-end validation**; SDK-conformance validation and density measurements are also unavailable. Every step below requires you to prepare images and vsock bridging yourself. ## Prerequisites {#prerequisites} -Requires Linux x86_64, usable `/dev/kvm`, trusted absolute paths and a writable delegated cgroup v2 hierarchy with enabled CPU/memory/PID controllers and `cgroup.kill`. Preflight checks real controller writes and the KVM API; there is no host, OCI command or registry-pull fallback. +You need Linux x86_64, a usable `/dev/kvm`, trusted absolute paths, and a writable, delegated cgroup v2 hierarchy with the CPU/memory/PID controllers and `cgroup.kill` enabled. Preflight checks verify real controller writes and the KVM API; there is no host, OCI-command or registry-pull fallback. -Images are trusted local `images_dir/.json` manifests, not registry references. Fields are absolute independent Linux `rootfs` (never host `/` or overlapping daemon state), absolute guest bootstrap `entrypoint` argv, optional `cmd`, optional `env` and optional absolute firmware `library_dir`. Requested workload argv (or `cmd` if empty) is appended to `entrypoint`; request env overrides manifest env, without host environment inheritance or shell interpolation. +An image is a trusted local `images_dir/.json` manifest, not a registry reference. Fields include an absolute-path standalone Linux `rootfs` (neither the host `/` nor overlapping daemon state), an absolute-path guest bootstrap `entrypoint` argv, optional `cmd`, optional `env`, and an optional absolute-path firmware `library_dir`. The requested workload argv (or `cmd` when empty) is appended to `entrypoint`; request env overrides manifest env, does not inherit the host environment, and receives no shell interpolation. -!!! warning - Prepare your own guest bootstrap and vsock service bridges following the [image contract](boundaries.md#images). The project **has not supplied a bootstrap or image recipe or performed end-to-end validation**; SDK-conformance validation and density measurements are also unavailable. +The long-running guest bootstrap must supervise the workload, a real OpenSandbox 1.1.0 execd and egress; initialize/authenticate the services itself; forward signals and reap children. It must provide byte-transparent AF_VSOCK listeners on ports **44772/18080** of guest **CID 3**, bridging the real services. The supervisor's loopback TCP publications reach the guest over a private Unix socket and native vsock forwarding. A plain rootfs or a sleep-only process is not enough. Create, Inspect on a Running VM and resume readiness checks require, through the bridge, a real HTTP 200 from execd `/ping`, JSON `initialized: true` from `/ready`, and egress `/healthz`, with bounded response bodies. The daemon neither injects/initializes execd nor synthesizes command/SSE/file responses. -## Install the executable {#install} +## Install and start {#install} -On Linux x86_64, install the `pvisor` wheel to get the standalone `pvisor-daemon` executable in your Python environment's bin directory. macOS wheels do not include the daemon: +Install the `pvisor` wheel on Linux x86_64 to get the standalone `pvisor-daemon` executable in the Python environment's bin directory. macOS wheels do not include the daemon: ```bash pip install pvisor @@ -22,19 +23,9 @@ pvisor-daemon --help pvisor-daemon protocol ``` -For the latest `main` build, use the [nightly wheel installer](../../start/installation.md). Alternatively, prepare the [native build prerequisites](../../community/development.md) and run these local source-installation commands at your selected revision. This source-installation path has not yet been validated: - -```bash -cargo install --locked --path crates/pvisor-daemon --bin pvisor-daemon -pvisor-daemon --help -pvisor-daemon protocol -``` - -`protocol` prints the pinned OpenSandbox version and commit. Local source installation is separate from installing the Python `pvisor` package. Both installation paths require you to prepare images separately. Pin the source revision, SDK 1.1.0 and image contents together; SDK conformance still needs end-to-end validation. +For the latest `main` build, use the [nightly wheel installer](../../start/installation.md). `protocol` prints the pinned OpenSandbox version and commit. Pin the source revision, SDK 1.1.0 and image contents together. The local source-install path (`cargo install --locked --path crates/pvisor-daemon`) is not verified. -## Start the API {#start} - -`serve` constructs `NativeRuntime` using the implemented, required `--images-dir` and `--cgroup-root` flags. Cargo links `pvisor` and `pvisor-core`; synchronous `main` calls `pvisor::run_krun_internal_if_requested()` before argument parsing or Tokio, then dispatches the hidden `native-supervisor --sandbox-dir ABSOLUTE_PATH` command. Once the images and cgroup hierarchy are ready, start the API with the following CLI configuration. +`serve` constructs the `NativeRuntime` from the implemented and required `--images-dir` and `--cgroup-root`: ```bash export OPEN_SANDBOX_API_KEY="$(openssl rand -hex 32)" @@ -49,11 +40,11 @@ pvisor-daemon serve \ --max-timeout-seconds 86400 ``` -Keep runtime paths absolute and unchanged across daemon restarts. Use short state paths such as `/run/user/1000/pvd`: per-sandbox `control.sock` must be shorter than 104 bytes, and vsock Unix sockets also have path limits. Retain state; this `/run` example does not promise persistence across logout/reboot, and VMs cannot survive host reboot. `/sys/fs/cgroup/pvd` must be a real delegated hierarchy, not an ordinary directory. +Runtime paths are absolute and must stay unchanged across daemon restarts. Keep the state path short, for example `/run/user/1000/pvd`: each sandbox's `control.sock` must be shorter than 104 bytes, and vsock Unix sockets also have path-length limits. Retain the state; this `/run` example does not guarantee persistence across logout/reboot, and VMs do not survive a host reboot. `/sys/fs/cgroup/pvd` must be a real delegated hierarchy, not a plain directory. -Choose a private state directory outside the checkout. Generate the API key once and keep the same value in protected service secret storage on restart. The example sets an admission budget of 32 records, four CPU units and 8 GiB of summed hard memory limits. Whole-node physical usage has not been measured; leave daemon/cache/host headroom and configure host supervision separately. +Choose a private state directory outside the checkout. Generate the API key once, keep it in protected service secret storage, and reuse the same value across restarts. The example admission budget is 32 records, four CPU units and an 8 GiB total hard memory limit. Whole-node physical occupancy is unmeasured; leave headroom for daemon/cache/host and configure host supervision separately. -In a second shell with the same protected API key, query the lifecycle API: +Query the lifecycle API from a second shell with the same protected API key: ```bash curl --fail-with-body --config - <

-

Scaling autonomous

agent execution.
让自主 Agent 的执行可以规模化。

+
+

PolicyVisor

+

Scaling autonomous agent execution.
让自主 Agent 的执行可以规模化。