Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

Migrates PublishSocket.containerPath and PublishSocket.hostPath from Foundation.URL to SystemPackage.FilePath, consistent with the project-wide effort to replace URL/String paths with strongly-typed FilePath / SystemPath at API boundaries (#1480, #1493, #1518, #1522, #1523, #1570, #1574, #1580). PublishSocket was the last URL-typed path in ContainerResource.

URL is the wrong type for filesystem paths: it implies a navigable resource, permits non-file schemes, and forces consumers through percent-encoding when interoperating with POSIX APIs. FilePath is purpose-built, Sendable, and already used by both callers of this struct after the recent runtime reorg (#1577).

Tracking issue: #1593

Wire-format compatibility

PublishSocket is serialized to disk as part of container bundles and over XPC. To keep this migration non-breaking on the wire:

• The encoder emits each path as URL(filePath: path.string).absoluteString — byte-identical to the prior URL-typed JSONEncoder output (e.g. "file:///var/run/docker.sock"). Existing bundles and any reader still decoding these fields as URL continue to work.
• The decoder accepts the legacy file:// form, plain absolute paths (forward-compat), and resolves percent-encoding. Empty, relative, malformed, or non-localhost-host inputs throw DecodingError.dataCorrupted so corrupt state fails loudly rather than silently producing an invalid socket path.

Source compatibility

Source-breaking for any external consumer constructing PublishSocket directly with URL. Acceptable given the pre-1.0 project status and the consistent direction of prior migrations.

Testing

• Tested locally (swift test --filter ContainerResourceTests — 50/50 passing)
• Added/updated tests — Tests/ContainerResourceTests/PublishSocketTests.swift, 14 cases covering:
  • Encoder produces byte-identical output to the prior URL encoding (pinned via a sibling LegacyPublishSocket mirror)
  • Encoder percent-encodes spaces and special characters
  • Decoder accepts legacy file:// form, percent-encoded paths, and file://localhost/...
  • Decoder accepts plain absolute paths (forward-compat)
  • Encode → decode round-trip preserves all fields including permissions
  • Decoder rejects empty strings, "file:", "file://", relative paths, and non-local-host file URLs
• Added/updated docs — public API change only; no doc surface impacted

Build verified clean: swift build --target ContainerRuntimeLinuxServer.