[WSLC] State-aware lifecycle (PR 3/3): TypeScript SDK per-phase policy configs

[Soham Das (SohamDas2021)]

📖 Description

• I have signed the Contributor License Agreement.
• This pull request is related to an issue.
• If this PR changes build commands, project architecture, or key conventions, I have updated .github/copilot-instructions.md.

---

Summary

Final increment of the WSLc state-aware sandbox lifecycle series: the TypeScript SDK surface. This is a pure SDK-surface addition — no runtime behavior. The daemon, Rust StatefulSandboxBackend, wire model, and generated wire types all landed in the earlier increments; this PR exposes the WSLc backend through the existing generic state-aware functions (provisionSandbox / startSandbox / execInSandbox / execInSandboxAsync / stopSandbox / deprovisionSandbox).

Changes:

• Types (state-aware-types.ts): adds 'wslc' to StateAwareContainmentBackend; five per-phase Wslc*Config interfaces; wslc entries in the closed config + metadata registries (WSLc returns no metadata for any phase). Configs mirror the backend honor matrix — provision takes filesystem / network (cross-cutting) plus backend-specific image / imageTarPath; exec takes process plus a cooperative network.proxy; start/stop/deprovision take version only.
• Routing + versioning (state-aware-helper.ts): adds the wslc: id prefix, SandboxId<'wslc'> branding via PREFIX_TO_BACKEND, and a per-backend default-version map so WSLc envelopes default to 0.8.0-alpha while isolation_session / windows_sandbox stay 0.6.0-alpha (the gate-locked STATE_AWARE_VERSION is untouched).
• Exports (index.ts) + docs (README.md) + unit tests covering version default, experimental.wslc.provision nesting, cross-cutting lifting, prefix routing, metadata-undefined, and brand distinctness.

Consistent with the windows_sandbox precedent: SDK types are permissive where the Rust backend enforces the honor matrix at runtime (e.g. a proxy at provision is expressible but rejected with policy_validation).

Validation: tsc clean · 268/274 SDK unit tests pass · check-schema-versions.js / check-sdk-types-codegen.js / check-version-sync.js green.

Stacked on #801.

📋 Issue Type

• Bug fix
• Feature
• Task

---

GitHub Actions runs the PR validation build automatically. The ADO pipeline
(MXC-PR-Build) is the Azure version of the PR pipeline, kept in parity with the GitHub
Actions build; it runs on merge to main, and Microsoft reviewers with write access can trigger it
on a PR with /azp run. See docs/pull-requests.md.

If the dependency-feed-check check fails on a new dependency, the crate must be added to
the feed before the PR can pass. See docs/pull-requests.md
for the steps.

Microsoft Reviewers: Open in CodeFlow

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Adds WSLc support to the TypeScript SDK’s state-aware lifecycle API.

Changes:

• Adds per-phase WSLc configuration and metadata types.
• Routes wslc: IDs and defaults requests to schema 0.8.0-alpha.
• Updates exports, documentation, and unit coverage.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
sdk/node/src/state-aware-types.ts	Defines WSLc lifecycle types and metadata mapping.
sdk/node/src/state-aware-helper.ts	Adds WSLc versioning and ID-prefix routing.
sdk/node/src/index.ts	Exports the new public types.
sdk/node/README.md	Documents WSLc lifecycle usage.
sdk/node/tests/unit/state-aware.test.ts	Tests envelope construction and lifecycle routing.
sdk/node/tests/unit/state-aware-types.test.ts	Tests type constraints and branding.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Gudge (MGudgin)]

Summary

Requesting changes for two SDK consistency gaps: WSLc's new backend-specific phase fields are not added to the state-aware generated-wire conformance oracle, and prefix routing is the only backend registry in this design that is not compiler-enforced as exhaustive. The remaining two comments are non-blocking documentation cleanup.

Range verified: 9b110a87bf06b1e0239bd13dd24ce4fa6b39c5f6...3b534c67bc11e04bc4191ebf5828bfc7b620994d (6 files, +353/-7). The merge base exactly matches GitHub's PR base. The locally captured git diff and gh pr diff are byte-for-byte identical at 498 lines.

Verified clean, with receipts: the new tests cover WSLc version default/override, filesystem and network lifting, image/imageTarPath nesting, all five lifecycle routes, prefix inference, metadata absence, branded-id separation, and public config/export shapes. Existing generic state-aware tests already verify every wire error code, including policy_validation, maps to MxcError. Runtime Rust policy enforcement is unchanged by this SDK-only PR and fails closed for unsupported WSLc policy fields. No runtime WSL tests were run as part of this filing.

Verified pre-existing - not independently attributed to this PR

• sdk/node/tests/unit/wire-conformance-state-aware.test.ts is byte-identical base vs head. The file itself states that every new backend-specific state-aware phase shape must be represented to prevent generated-wire/public-SDK drift; the finding is framed as a gap in this PR's new WSLc type addition, not as an old defect.
• docs/wsl/wslc-state-aware.md and the Rust WSLc policy implementation are byte-identical base vs head. Their pre-existing content is context only and is not a merge condition in this review.

Requested findings not filed after verification

• The broad NetworkConfig types are intentional: the PR description explicitly follows the Windows Sandbox precedent of permissive SDK shapes with runtime honor-matrix validation. The unchanged Rust backend rejects unsupported fields with policy_validation, so this is not a fail-open or reliability bug.
• Backend-specific policy rejection tests were withdrawn: the SDK cannot prove Rust policy semantics with a fake spawn, while generic state-aware tests already verify typed MxcError propagation and the Rust layer owns the policy tests.
• The honor-matrix omission claim was withdrawn: that pre-existing table is a policy matrix rather than a complete backend-config schema, and the new JSDoc already states that only defaultPolicy is honored at provision.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

src/backends/wslc/common/src/daemon_protocol.rs:40

• The PR description says this is a pure TypeScript SDK-surface addition with “no runtime behavior,” but this protocol bump is part of substantial daemon/runtime changes (live output streaming, base64 frame encoding, and provision-policy gating). Please update the PR scope and validation details, or rebase/split the inherited runtime changes, so the reviewed diff matches the stated purpose.

pub const PROTOCOL_VERSION: u32 = 2;

src/backends/wslc/daemon/src/session_manager.rs:168

• This new rationale is stale within the same change: StreamFrame payloads are now base64 strings, not JSON number arrays. The 64 KiB limit remains frame-safe, but documenting a ~4× expansion misstates the wire format and can lead to incorrect future capacity calculations.

/// allocation and keeps the resulting `Stdout`/`Stderr` frame well under the
/// protocol's `MAX_FRAME_SIZE` (a `Vec<u8>` serializes as a JSON number array,
/// ~4x expansion), so a large callback can never overflow a frame and abort the

[Gudge (MGudgin)]

Verified all four prior review findings at 527a731.

Validation:

• npm run build: passed
• npm test: 268 runnable tests passed, 0 failed, 6 skipped
• GitHub CI: all checks green

The branch is currently behind its declared base (merge-base b9d08f4 vs base 1c11f25), so it should be rebased and revalidated before merge.