Skip to content

Phase 3c: formalize the three version axes and the negotiation flow#582

Open
MGudgin wants to merge 1 commit into
user/gudge/versioning_phase3b_schema_floorfrom
user/gudge/versioning_phase3c_three_axis_docs
Open

Phase 3c: formalize the three version axes and the negotiation flow#582
MGudgin wants to merge 1 commit into
user/gudge/versioning_phase3b_schema_floorfrom
user/gudge/versioning_phase3c_three_axis_docs

Conversation

@MGudgin

@MGudgin MGudgin commented Jun 26, 2026

Copy link
Copy Markdown
Member

Stacked PR. Base is user/gudge/versioning_phase3b_schema_floor (Phase 3b), not main. Review/merge the stack in order (2.5 -> 3a -> 3b -> 3c); this branch will be retargeted to main as its base lands.

Summary

Phase 3c of the versioning remediation — the documentation half. It rewrites the conceptual sections of docs/versioning.md to match the post-3a/3b reality: it formalizes the three independent, never-conflated version axes and replaces the old version-centric "Version Negotiation" steps with the three-stage, capability-driven runtime flow. Docs-only; no code change.

Details

  • Add a "Three version axes" section: schema/config version (the version field; semver; 0.6.x floor through 0.8.x dev ceiling; major.minor compared), product version (Rust workspace + npm; independent; check-version-sync.js), and host capability (negotiated at runtime, never a string in the config). States the Phase 3a invariant: schema version no longer selects the Windows backend.
  • Rewrite "Version Negotiation" as three ordered stages: (1) schema-range check at the trust boundary; (2) containment resolve (abstract process/vm intent → concrete backend per host, independent of version); (3) host-capability negotiate (BaseContainer when is_base_container_usable(), else AppContainer BFS/DACL, logged; the only fallback). Updates the Data Flow diagram to match.
  • Correct the BaseContainer OS handshake: today MXC uses a fixed SANDBOX_SPEC_VERSION ("0.1.0") and calls Experimental_CreateProcessInSandbox directly; the EnumerateSandboxSpecVersionInfo spec-version handshake is now marked forward-looking / not yet implemented (it had been written as current behavior).
  • Tighten the Error Contract: schema-range, capability (BackendUnavailable on the ScriptResponse / SDK spawn paths), and policy-unsupported (e.g. deniedPaths) failures are typed and actionable; security policy never fuzzy-falls-back.
  • Fixups surfaced while editing: bump a stale 0.4.0 example to 0.6.0-alpha; note retired 0.4/0.5 stable schemas are kept as artifacts; correct a promotion-step reference to a non-existent parser symbol.

Tests

  • Docs-only change; no code or CI gates affected. The draft was fact-checked (rubber-duck pass) against config_parser.rs, models.rs, fallback_detector.rs, dispatcher.rs, and base_container_runner.rs.
Microsoft Reviewers: Open in CodeFlow

This PR rewrites the conceptual sections of docs/versioning.md to match the
post-3a/3b reality. It formalizes the three independent, never-conflated version
axes and replaces the old version-centric "Version Negotiation" steps with the
three-stage, capability-driven runtime flow.

Details:
- Add a "Three version axes" section: schema/config version (the version field;
  semver; 0.6.x floor through 0.8.x dev ceiling; major.minor compared), product
  version (Rust workspace + npm; independent; check-version-sync.js), and host
  capability (negotiated at runtime, never a string in the config). States the
  Phase 3a invariant: schema version no longer selects the Windows backend.
- Rewrite "Version Negotiation" as three ordered stages: (1) schema-range check
  at the trust boundary; (2) containment resolve (abstract process/vm intent ->
  concrete backend per host, independent of version); (3) host-capability
  negotiate (BaseContainer when is_base_container_usable(), else AppContainer
  BFS/DACL, logged; the only fallback). Updates the Data Flow diagram to match.
- Correct the BaseContainer OS handshake: today MXC uses a fixed
  SANDBOX_SPEC_VERSION and calls Experimental_CreateProcessInSandbox directly;
  the EnumerateSandboxSpecVersionInfo spec-version handshake is marked
  forward-looking / not yet implemented (it had been written as current behavior).
- Tighten the Error Contract: schema-range, capability (BackendUnavailable on the
  ScriptResponse / SDK spawn paths), and policy-unsupported (e.g. deniedPaths)
  failures are typed and actionable; security policy never fuzzy-falls-back.
- Fixups surfaced while editing: bump a stale 0.4.0 example to 0.6.0-alpha; note
  retired 0.4/0.5 stable schemas are kept as artifacts; correct a promotion-step
  reference to a non-existent parser symbol.

Tests:
- Docs-only change; no code or CI gates affected. Draft fact-checked against
  config_parser.rs, models.rs, fallback_detector.rs, dispatcher.rs, and
  base_container_runner.rs (SANDBOX_SPEC_VERSION = "0.1.0",
  Experimental_CreateProcessInSandbox).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Generated-with: claude-opus-4.8
@MGudgin MGudgin requested a review from a team as a code owner June 26, 2026 20:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant