[David Bennett (dkbennett)]

Summary of the Pull Request

This is PR 1 of 5 in the WSLC Compose stack, split from #41526 into individually reviewable and buildable PRs.

Base: feature/compose

This PR establishes consistent project identity, resource naming, and ownership labels as the foundation for request-based Compose operations. It retains the existing synchronous Compose API and CLI command surface.

The review sequence is identity, operation engine, operation client, management, and interactive UX. These PR boundaries are not architectural layers.

PR Checklist

• Closes: None.
• Communication: I've discussed this with core contributors already. If work hasn't been agreed, this work might be rejected
• Tests: Added/updated if needed and all pass
• Localization: All end user facing strings can be localized
• Dev docs: Added/updated if needed
• Documentation updated: If checked, please file a pull request on our docs repo and link it here: No documentation PR is included.

Detailed Description of the Pull Request / Additional comments

• Introduce ComposeNormalizer to normalize project names and validate derived resource names before resource creation.
• Default project identity to the normalized project-directory name. Generate container names as <project>-<service>-1 and the default network name as <project>_default, while honoring explicit container names.
• Add standard com.docker.compose.* identity labels and WSLC managed/metadata-version labels to containers and networks.
• Preserve service-name DNS aliases alongside container-name aliases so service discovery does not depend on generated physical names.
• Separate YAML content parsing from file reading and introduce the internal document/selection model. File loading remains in the existing synchronous entry point.
• Reject unsupported top-level properties and extract shared resource-name validation.

Async service operations, CLI migration, project listing/removal, and terminal progress/Ctrl+C handling are outside this PR and follow in later PRs.

Validation hardening

The following changes are included in published head 134b8809.

• Reject empty or whitespace-only service names before mutation because service names are network aliases, including with an explicit container name.
• Reject decoded NUL characters in service and resolved container names before crossing null-terminated APIs. Regressions cover leading/embedded NUL aliases and distinct container names sharing one C-string prefix. Encoding detection still receives the original document bytes.
• Reject duplicate resolved physical container names before mutation, including generated/explicit and explicit/explicit collisions.
• Pass the original document bytes to yaml-cpp so BOM-marked UTF-16 documents retain encoding detection. Regressions cover both byte orders and a non-ASCII environment value.
• Reject an unsupported cross-file reuse of a cached normalized project with E_NOTIMPL before resource creation or replacement. Regressions verify same-file reuse, same-directory file switching, normalized-name collisions across directories, and preservation of the existing network ID.
• Add localized diagnostics for duplicate names and unsupported file switching.
• Add concise comments explaining YAML encoding detection, Windows drive colons in volume syntax, informational version metadata, service-name aliases, and the cache safety boundary.

Scaffolding limits and architectural ownership

This stack is scaffolding, not a claim of complete Docker Compose compatibility.

The synchronous API caches sessions by canonical source-file path and retains each session's captured definition. Reopening the same file returns that cached session without reinterpreting edits. The safety guard explicitly rejects a different source file resolving to an already cached project before it can replace that project's default network.

That guard is an unsupported-operation limit of this synchronous API, not a single-file-per-project identity rule. The normalized project name remains the project identity within the owning WSLC session; a filename is an input to an invocation, not a separate project namespace.

Parsing and normalization own interpretation. Reconciliation owns desired-versus-observed resource decisions. Desired-definition updates, idempotent resource reuse, and configuration-driven recreation/orphan behavior remain future reconciler work; the later operation-plumbing PRs do not by themselves complete those semantics.

Validation Steps Performed

Validation is local, with broader regression coverage left to CI. The identity build and focused tests are repeated for published head 134b8809, including the decoded-NUL regressions.

Expected red runs against the unchanged production code at 914e02d9:

Command	Result
.\bin\x64\Debug\test.bat '/name:*Compose*'	Failed as expected: 5 passed, 9 failed. Whitespace-only service names removed the preexisting network. A duplicate resolved name triggered a service assertion, invalidating subsequent results.
.\bin\x64\Debug\test.bat -f '/name:*ComposeUtf16*'	Both tests failed with E_INVALIDARG, reproducing rejection of valid UTF-16 documents independently of the assertion.
.\bin\x64\Debug\test.bat -f '/name:*ComposeSession*BeforeMutation*'	Both tests failed because the unsupported second file succeeded, reproducing the missing safety boundary independently of the assertion.

Local configuration, build, and checks:

Command	Result
cmake .	Passed; configured the identity branch before the baseline run.
.\FormatSource.ps1	Passed; formatted the stabilization and decoded-NUL changes.
cmake --build . -- -m	Passed at 134b8809.
.\bin\x64\Debug\test.bat '/name:*Compose*'	Passed at 134b8809; 17/17, no skipped or blocked tests. Setup enabled, no -f.
.\FormatSource.ps1 -Branch -BaseBranch feature/compose -Verify $true	Passed; all nine identity C++ files checked.
python tools\devops\validate-localization.py	Passed with expected missing-translation warnings; only the en-US source was changed.
python tools\devops\validate-copyright-headers.py src\windows\wslcsession	Passed; 57 source files checked.
python tools\devops\validate-copyright-headers.py test\windows\wslc	Passed; 76 test source files checked.
git diff --check	Passed.

[Copilot]

🟡 Changes recommended

Empty service keys can pass normalization and trigger network mutation before endpoint validation rejects them.

1 open issue

• Reject empty service keys before mutating resources · New

What changed in this PR

This first Compose layer establishes project and resource identity for WSLC while retaining the synchronous API and existing CLI commands.

Changes:

• Normalize project names and validate generated resource names before creation.
• Add ownership labels, project-based resource names, and service-name DNS aliases.
• Separate YAML parsing from file loading and expand identity and connectivity tests.

File	Description
test/​windows/​wslc/​WSLCComposeTests.cpp	Tests labels, generated names, validation, and DNS connectivity.
src/​windows/​wslcsession/​WSLCSession.cpp	Integrates normalization, labels, and service aliases.
src/​windows/​wslcsession/​ResourceName.h	Extracts shared resource-name validation.
src/​windows/​wslcsession/​ComposeSpec.h	Adds service identity and content-based parsing.
src/​windows/​wslcsession/​ComposeSpec.cpp	Parses supplied YAML and rejects unsupported top-level properties.
src/​windows/​wslcsession/​ComposeNormalizer.h	Defines document, selection, and normalization interfaces.
src/​windows/​wslcsession/​ComposeNormalizer.cpp	Normalizes project identity and validates derived names.
src/​windows/​wslcsession/​CMakeLists.txt	Registers normalization and validation files.
src/​windows/​service/​inc/​wslc.idl	Defines project-name limits and schema version.
src/​windows/​inc/​ComposeLabels.h	Defines Compose identity and WSLC ownership labels.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Critical validation and session-identity gaps can delete or replace existing networks before conflicts are detected, while the new NUL-byte check also rejects valid UTF-16 Compose files.

3 open issues

• Reject whitespace-only service names before resource mutation · New
• Reject duplicate resolved container names before mutation · New
• Reuse or reject sessions by normalized project identity · New

1 previously missed issue

In code that hasn't changed since last review

Allow BOM-marked UTF-16 Compose files

src/​windows/​wslcsession/​ComposeNormalizer.cpp:42

This rejects valid UTF-16 Compose files: their encoded bytes contain NULs even though the decoded YAML does not. The previous YAML::LoadFile path supported BOM-marked UTF-16, so files written by Windows PowerShell's default Out-File now fail with E_INVALIDARG before parsing. Let the YAML parser perform encoding validation rather than rejecting zero bytes in the encoded document.

1 resolved since last review

• Reject empty service keys before mutating resources

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Embedded NULs in service and container names bypass preflight validation, allowing name collisions or empty aliases to cause failures after the existing default network has already been replaced.

1 open issue

• Reject embedded NULs before replacing the default network · New

3 resolved since last review

• Reuse or reject sessions by normalized project identity
• Reject duplicate resolved container names before mutation
• Reject whitespace-only service names before resource mutation

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Human assessment is needed to weigh the user-facing impact of untranslated validation details and directory-derived project-name failures that lack an explanatory diagnostic.

No open issues 🎉

1 resolved since last review

• Reject embedded NULs before replacing the default network

_{Review effort: Balanced}