Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm

## [Unreleased]

- Route result put/page/release and batch plan/run/resume through the resident kernel on Windows, preserving the exact public confinement command and scrubbed runner environment. Full-access calls reuse the existing fixed worker on every platform; restricted POSIX calls retain their explicit platform runner until native range ownership is available. Admission failure never falls back or replays (#872).
- Windows 的 result put/page/release 与 batch plan/run/resume 改由常驻内核执行,保留公开 confinement 的原始命令及清理后的 runner 环境。所有平台的完全访问调用复用既有固定 worker;受限 POSIX 调用在原生进程范围所有权可用前保留明确的平台 runner。准入失败不回退、不重放(#872)。

- Connect explicit session Bash results to sealed spill recovery, require `shell-spill-v1` before public activation, and bind retained session callbacks to their exact publishing Agent. Fresh and session projections share the existing root-owned kernel and preserve their separate semantics; accepted runtime distribution remains pending (#872).
- 将显式会话 Bash 结果接入已封存的 spill 恢复,公开启用前要求 `shell-spill-v1`,并把保留的会话回调绑定到发布它的准确 Agent。Fresh 与会话投影共用既有根作用域内核,保留各自语义;合格运行时分发仍待完成(#872)。

Expand Down
52 changes: 52 additions & 0 deletions docs/resident-confined-workers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Resident result and batch execution

[中文](常驻结果与批处理.md)

Native and PTC result put/page/release share the same bridge. PTC batch plan/run/resume
uses that bridge too. On Windows, all of these calls now use the owning resident kernel;
the public subprocess service starts the kernel once, not another OPS worker per call.
The original reference/audit implementations, IDs, result budgets, write-ahead records,
root/session binding and no-follow checks remain unchanged.

The permission boundary is explicit:

| Current policy/platform | Execution path |
| --- | --- |
| Full access, every supported platform | Existing trusted fixed worker leaf inside the resident kernel. |
| Read-only or workspace-write, Windows | Exact public `sandbox.confine()` command, launched inside the existing atomic Windows Job range. |
| Read-only or workspace-write, POSIX | Existing public confined runner. Native arbitrary-runner ownership is not established on this platform; this remaining route is not a kernel-error fallback. |

Batch operations are data, but their existing root-relative path checks are not treated as
proof that OS confinement can be removed. The restricted Windows path preserves the
original argv, working directory, public scrubbed parent environment and Electron Node-runner
adaptation. It reports the actual confinement enforcement and preserves runner-failure and
denial-signature classification. No shell configuration environment is added to a file worker.
Current authority is checked again after asynchronous preparation and before dispatch.

The existing `execute` control frame may carry trusted launch facts for batch/result only.
An older kernel without `confined-worker-v1` refuses the request before dispatch. The envelope
remains limited to 2 MiB, launch metadata to 64 KiB, and the shared request window to 32 calls.
There is no second scheduler. Cancellation and completion retain the same request ID.

The owned range is established before sending request bytes. A started receipt precedes
bounded stdin delivery and EOF; stdin and both output readers join before terminal settlement.
The native envelope deadline covers launch, the physical started acknowledgement, stdin delivery
and a stalled runner before worker decoding. The existing bounded reply queue preserves
started-before-completed ordering when cancelled. A joined input-delivery error does not erase
a known nonzero runner exit or captured stderr; timeout and cancellation remain interrupted.
Cancellation terminates the whole owned range, including the public confinement wrapper.
Unconfirmed cleanup poisons the connection instead of reporting successful cleanup. A lost
receipt never authorizes replay, and interrupted batch effects retain their existing unknown
state and recoverable audit identity when available.

Cache purge continues to use the dedicated resident teardown path. The remaining one-shot
transport is used only by restricted POSIX batch/result calls and the explicit WSL read path.
This slice does not claim POSIX confined-runner migration or completion of issue #872.

Windows verification used worker SHA-256
`024d5e80b9befe77dce3b3ad4bf6c2d4d40e236047054acc79dd9f7196192b2c`.
The eight real routing checks and thirteen Native result checks passed, including actual
public confinement, root-link replacement, cancellation, stalled input, early runner refusal,
and zero public one-shot OPS launches through disposal. The original route failed all three
initial routing checks; the intermediate kernels separately failed the stdin deadline and both
early-refusal checks. These are correctness and ownership observations, not performance results.
9 changes: 5 additions & 4 deletions docs/resident-kernel.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,10 @@ worker. Output drains retain bounded tails with explicit loss information. EOF a
cancel and join admitted executions. No worker is detached or restarted.

This removes repeated **host runner** startup for local file dispatch; it still pays native
child startup per file request. WSL reads and confined PTC batch/result operations
retain their existing runners because their enforced execution contexts cannot be replaced by the
trusted local-file path. The final A/B report must measure all of those costs. This transport is
child startup per file request. Windows batch/result calls now retain exact public confinement
inside an owned native range; full-access calls reuse the fixed leaf. Restricted POSIX batch/result
calls and explicit WSL reads retain their platform runners; see [result and batch routing](resident-confined-workers.md).
The final A/B report must measure all of those costs. This transport is
not evidence that session shells, DSH jobs, complete multi-process cleanup or the performance
targets have been delivered.

Expand Down Expand Up @@ -116,7 +117,7 @@ row remains a delivery requirement even if a smaller slice does not exercise it
| Cancel first interrupts, then may reset only that shell tree | No inner process cancellation boundary exists. | Hard cancellation reports shell-reset/state loss; other sessions continue. |
| Explicit background tasks use DSH job_list/job_output/job_kill | Rust `Job` is a file-batch audit record, not the DSH process-job service. | Immediate jobId, independent output, atomic startup/publication handoff, job-tree kill, session/host cleanup. |
| Ordinary command descendants do not become implicit services | Pending shell/task ownership implementation. | Unregistered descendants cannot silently cross calls; published jobs are not killed merely because their startup request completed. |
| Migration leaves one execution architecture | Local file calls use the shared client with no one-shot fallback. WSL and confined batch/result/cleanup paths remain explicit exceptions. | Complete shell/job ownership and eligible remaining migrations without weakening their execution constraints. |
| Migration leaves one execution architecture | Local files, result cleanup and Windows batch/result calls use the shared client without one-shot fallback. Restricted POSIX batch/result and explicit WSL reads retain their platform runners. | Complete remaining platform migrations without weakening their execution constraints. |
| End-to-end performance and resource evidence | Windows baseline: 824 calls, 0 failures, including 200 hot samples for each of four items. No resident benefit measured. | Resident A/B, Native/PTC, cold/warm, file/command/mixed/concurrent/long workloads; p50/p95/p99, CPU/RSS/handles and failures. |

## Rust reuse boundary
Expand Down
7 changes: 4 additions & 3 deletions docs/常驻内核.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,9 @@ dispatch,并拥有独立终止句柄。Windows 子进程使用嵌套 Job;POS
EOF 与关闭会取消并等待已准入执行结束,不 detach、不重启 worker。

本地文件 dispatch 已消除重复的**宿主 runner** 启动;每次文件请求仍有原生子进程启动成本。
WSL 读取、受约束的 PTC batch/result 操作保留原有 runner,不能用可信本地文件路径
替代它们的强制执行上下文。最终 A/B 报告必须实测这些成本。这条 transport 不代表会话 shell、DSH jobs、完整多进程回收
Windows batch/result 调用在所属原生进程范围内保留原始公开 confinement,完全访问调用复用固定
leaf。受限 POSIX batch/result 与明确启用的 WSL 读取保留平台 runner;参见[结果与批处理路由](常驻结果与批处理.md)。
最终 A/B 报告必须实测这些成本。这条 transport 不代表会话 shell、DSH jobs、完整多进程回收
或性能目标已经交付。

所属结果缓存清理复用同一常驻连接及既有类型化 `result/purge` 操作,不再启动公开的一次性 worker。
Expand Down Expand Up @@ -91,7 +92,7 @@ hook,主入口检查即失败:两个缓存均未完成清理;独立集成
| 先中断,必要时仅重置该 shell 树 | 尚无内部进程取消边界。 | 硬取消明确报告 shell-reset/状态丢失,其他会话继续。 |
| 显式后台任务使用 DSH job_list/job_output/job_kill | Rust `Job` 是文件批处理审计记录,不是 DSH 进程任务服务。 | 立即返回 jobId、独立输出、明确启动/发布交接、任务树 kill、会话/宿主回收。 |
| 普通命令后代不能自动成为服务 | shell/task 所有权待实现。 | 未登记后代不能静默跨调用存活;已发布任务不因启动请求完成而结束。 |
| 迁移后只有一套执行架构 | 本地文件调用使用共享客户端,无一次性 fallback;WSL 与受约束 batch/result/清理路径仍是明确例外。 | 完成 shell/job 所有权与其余适合迁移的路径,不削弱原执行约束。 |
| 迁移后只有一套执行架构 | 本地文件、结果清理及 Windows batch/result 调用使用共享客户端,无一次性 fallback;受限 POSIX batch/result 与明确启用的 WSL 读取保留平台 runner。 | 完成剩余平台迁移,不削弱原执行约束。 |
| 完整调用的性能与资源证据 | Windows 基线共 824 次调用、0 失败,四项各含 200 次热态采样;尚未测得常驻收益。 | 常驻 A/B、Native/PTC、冷/热、文件/命令/混合/并发/长任务;p50/p95/p99、CPU/RSS/句柄与失败样本。 |

## Rust 可复用边界
Expand Down
43 changes: 43 additions & 0 deletions docs/常驻结果与批处理.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# 常驻结果与批处理执行

[English](resident-confined-workers.md)

Native 与 PTC 的 result put/page/release 共用同一桥接层,PTC 的 batch plan/run/resume
也走该桥接层。在 Windows 上,这些调用都使用所属常驻内核;公开 subprocess 服务只启动一次
内核,不再每次调用启动 OPS worker。原有引用与审计实现、ID、结果预算、写前记录、根目录和
会话绑定、no-follow 检查均保持不变。

权限边界明确区分:

| 当前策略与平台 | 执行路径 |
| --- | --- |
| 所有支持平台的完全访问 | 常驻内核内既有的可信固定 worker leaf。 |
| Windows 的只读或工作区写入 | 原始公开 `sandbox.confine()` 命令,在既有原子 Windows Job 范围内启动。 |
| POSIX 的只读或工作区写入 | 既有公开受限 runner;该平台尚未建立任意 runner 的原生所有权。这条剩余路径不是内核错误后的回退。 |

批处理只接受数据,但现有根目录相对路径检查并不被当作可移除 OS confinement 的证明。
受限 Windows 路径保留原始 argv、工作目录、公开清理后的父环境及 Electron Node-runner 适配。
结果报告真实的 confinement enforcement,保留 runner 失败及拒绝签名分类;不会向文件 worker
加入 shell 配置环境。异步准备结束后、派发前再次核对当前权限。

既有 `execute` 控制帧可携带仅供 batch/result 使用的可信启动信息。旧内核若缺少
`confined-worker-v1`,会在派发前拒绝请求。Envelope 仍限 2 MiB,启动信息限 64 KiB,共享
请求窗口仍为 32 个调用;不增加第二个调度器。取消与完成保持同一个 request ID。

请求字节发送前已建立所属进程范围。Started 回执先于有界 stdin 传输及 EOF,stdin 与两个输出
reader 均完成回收后才报告终态。原生 envelope deadline 覆盖启动、物理 started 确认、stdin 传输,
以及 worker 解码前停滞的 runner。既有有界回复队列在取消时仍保持 started 先于 completed。
已回收的输入传输错误不会抹去已知非零 runner 退出码或已捕获 stderr;超时与取消仍报告 interrupted。
取消会终止整个所属范围,包括公开 confinement wrapper。
无法确认回收时将连接置为不可用,而不报告清理成功。回执丢失不授权重放,中断的批处理继续保留
既有 unknown 效果状态,以及可用时的恢复审计标识。

缓存 purge 继续使用独立的常驻销毁路径。剩余一次性 transport 只服务于受限 POSIX batch/result
和明确启用的 WSL 读取。本切片不代表 POSIX 受限 runner 已迁移,也不代表议题 #872 已完成。

Windows 验证使用 worker SHA-256
`024d5e80b9befe77dce3b3ad4bf6c2d4d40e236047054acc79dd9f7196192b2c`。
8 项真实路由检查与 13 项 Native result 检查通过,覆盖公开 confinement、根链接替换、取消、
stdin 停滞、runner 提前拒绝,以及直到销毁结束均无公开一次性 OPS 启动。原有路径在最初 3 项
路由检查中全部失败;中间版本内核分别在 stdin deadline 和两个提前拒绝检查中失败。这些是
正确性与所有权观察,不是性能结果。
5 changes: 3 additions & 2 deletions native/crates/ops-process/src/shell/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
use std::{ffi::OsString, io, path::PathBuf};
mod capture;
pub use capture::{Capture, CaptureRead, CaptureSnapshot, CaptureView, Retention, SpillSnapshot};
pub const MAX_INPUT_BYTES: usize = 2 * 1024 * 1024;

pub struct Launch {
pub argv: Vec<OsString>,
Expand All @@ -26,8 +27,8 @@ pub(crate) fn budget(cap: usize) -> io::Result<()> {
mod windows;
#[cfg(windows)]
pub use windows::{
Baseline, Channel, ChannelSnapshot, ChannelView, MAX_SPILL_BYTES, Range, SpillStore,
signal_console_and_exit,
Baseline, Channel, ChannelSnapshot, ChannelView, MAX_SPILL_BYTES, Range, RangeCancellation,
SpillStore, signal_console_and_exit,
};

/// POSIX group creation would escape the public host's PGID fallback owner.
Expand Down
Loading
Loading