Skip to content

B0: machine/backend contract — isolation, scheduling, capacity and read models (B8/B10) #551

Closed as not planned

Description

@mengmengmengqiang

Parent: #545 (index). This issue owns the B0 machine/backend contract slice and the B8/B10 read-model and doctor surfaces that depend on it. The state machine (Draining / Lost) is the B5 issue; the StoragePlacement guard is its own issue.

Summary

#545 B0 is 1/15 done; B8 is 1/10 done; B10 is 1/9 done. The contract is the blocker: IsolationClass / SchedulingClass do not exist, kind mixes isolation with execution, capabilities are a flat bool set, there is no default isolation or refusal on mismatch, there is no per-Store quota or queue bound, there is no schema_version, and doctor does not check the declared backend capability.

This issue writes the contract and the read models over it. It does not implement providers.

Scope

Baseline

Records and contract

  • Fix the boundaries of MachineRecord, SandboxRecord and Backend. (B0-139)
  • Add the contract test skeleton. (B0-142)
  • Include IsolationClass and SchedulingClass in MachineRecord / BackendRecord. (B0-144)
  • Record backend capability: isolation class, kernel, strength, notes. (B0-145)
  • Keep process as a first-class backend. (B0-146)
  • Default sandbox.create isolation to docker where available; process is opt-in only. (B0-147)
  • Refuse an unavailable isolation class with Unavailable { requested, available }; never downgrade. (B0-148)
  • Record both requested_isolation and effective_isolation in the Sandbox record. (B0-149)
  • One worker serves many Stores: fix the per-Store quota, in-flight limit and queue bound in the contract. (B0-151)
  • Add schema_version to the record and to the capability. (B0-152)

B8 read models

  • machine list/get: kind, state, worker, lease, health. (B8-156)
  • sandbox list/get: state, project, machine, backend, image, capacity. (B8-157)
  • mounted Workspaces (path + branch), running command, recently closed. (B8-158)
  • queries are bounded (2 s / 5 s) and do not hold all 8 control slots. (B8-159)
  • report the per-Store in-flight count and queue bound; a full queue is refused with Capacity. (B8-160)
  • queue time counts against the 2 s / 5 s budget. (B8-161)
  • failures return precise Unavailable / Capacity, never hang. (B8-163)
  • return isolation (class, kernel, strength) from machine get / sandbox get. (B8-164)
  • return scheduling (worker, long-lived Sandbox, lease). (B8-165)

B10 doctor

  • Docker engine / socket reachability. (B10-171)
  • machine kind / VM provider availability. (B10-172)
  • sandbox image existence. (B10-173)
  • mount driver (FUSE / NFS / namespaces). (B10-174)
  • free disk. (B10-175)
  • worker state / lease. (B10-176)
  • check backend isolation capability (the declared capability), not "is Docker". (B10-178)
  • warn when the backend's isolation class is weaker than the requested one. (B10-179)

(B8-162 and B10-177 are already satisfied by #535/#536; they are not re-opened here. B0-140 is the B5 state enum; B0-150 is the StoragePlacement issue.)

Contract shape

MachineRecord:
  isolation_class: process | container | vm | remote
  exec_mode: worker | remote-exec
  kernel: shared | separate | separate-host
  provider: native | docker | fly | e2b | cloudflare | modal | daytona | k8s | fargate | ssh
  capabilities: Capability (typed, #[non_exhaustive], schema_version)
  • kind is the isolation class only. remote-exec is an exec_mode; gvisor is a runtime detail behind a provider.
  • Strength is a total order: process < container < microvm <= vm; a mismatch is refused, never downgraded.
  • Capability is a typed struct with schema_version, not a HashMap<String, bool>: idle_stop: IdleStop { Ours, Provider, None }, snapshot: Option<SnapshotCapability>.
  • sandbox.create defaults to docker; process is opt-in; the record keeps requested_isolation and effective_isolation.
  • One naming convention for every field; provider names never branch in core (no if provider == ...).
  • Per-Store quota, in-flight limit and queue bound are part of the contract; overflow is Capacity, and queue time counts against the read budget.
  • All read models are bounded (2 s / 5 s), warning-only where diagnostic, and never start a machine or Sandbox or write the home.

Non-goals

  • Provider adapters: the B7 issue.
  • StoragePlacement refusal: its own issue.
  • Draining / Lost / generation CAS: the B5 issue.
  • Scratch cleanup: the B6 issue.
  • Choosing D2 defaults: the fields can land first; defaults wait for D2.

Acceptance

  • Contract tests: vm requested, only process available → Unavailable { requested, available }, never a downgraded Sandbox.
  • requested_isolation and effective_isolation are recorded and returned by sandbox get.
  • machine get / sandbox get return isolation and scheduling; doctor checks the declared capability and warns only.
  • A full per-Store queue is refused with Capacity; queue time is inside the 2 s / 5 s budget.
  • schema_version is present on the record and the capability; an old record is read with an explicit migration path.
  • No if provider == ... in core; one naming convention across the capability struct.
  • doctor never starts a machine/Sandbox and never writes the home.

Dependencies

Related

Activity

  1. mengmengmengqiang commented on Nov 4, 2026

    @mengmengmengqiang
    ContributorAuthor

    Maintainer: this sub-issue was created without labels because the available token has no triage permission. Requested labels: v2.0.0, enhancement. Please add them (and adjust if the repo's triage rules disagree).

  2. mengmengmengqiang commented on Nov 4, 2026

    @mengmengmengqiang
    ContributorAuthor

    All #551 checkboxes are now covered by agent-b0iso + agent-b0ext2.

    Evidence: contract 4/4, api contract 8/8, typed_records 8/8, doctor 8/8 default/10/10 machine, isolation 4/4, sandbox_machines 4/4, layerfs-sandbox runtime_enum+conformance 11/11.

    Evidence-tier caveats (not unchecked boxes):

    • B8-159/161/163 are proven at the contract/refusal layer plus code; no live saturated daemon.
    • B10-172 is host-conditional (skipped when no Sandbox uses a VM).
    • B10-175 is code-only (disk healthy in tests).
    • scheduling.long_lived is currently a contract value, RemoteExec is not returned by a platform, machine.create/connect take no isolation option, and docs/versioned/2.0.0/ does not yet document isolation.
  3. mengmengmengqiang commented on Nov 5, 2026

    @mengmengmengqiang
    ContributorAuthor

    All checkboxes are covered by the verified branches/PRs; evidence is recorded in the issue evidence comments and the subagent reports.

  4. mengmengmengqiang commented on Nov 5, 2026

    @mengmengmengqiang
    ContributorAuthor

    Reopened: the delivery gate is code on the target branch + PR merged + CI green + traceable evidence. This issue was closed on branch/test evidence only; its PR/branch is not merged to layerfs_v2_0_0 yet.

  5. added this to the LayerFS v2.0.0 milestone on Nov 6, 2026
  6. added theissue type on Nov 6, 2026
  7. yifanxuaaa commented on Nov 6, 2026

    @yifanxuaaa
    Contributor

    Owner decision: drop SnapshotCapability from the B0 capability contract (PR #567). Details: #545 (comment)

  8. added a commit that references this issue on Nov 7, 2026
  9. yifanxuaaa commented on Nov 7, 2026

    @yifanxuaaa
    Contributor

    Closed by the owner (2026-11-07). PR #567 is shown as merged into layerfs_v2_0_0, but it was recorded as history only (a git merge -s ours in #601): mengmengmengqiang's commits and credit are kept, but none of its code is on the branch. The control layer split (layerfs-project#101) replaced this area, and the port was cancelled, so this is not delivered.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

new featureA new user-facing capability

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions