feat(logs): add tail and until retrieval filters

[stephenlclarke]

Type of Change

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

Motivation and Context

This is a draft stacked follow-up to #1592. Chris's #1592 introduces the initial ContainerLogOptions API shape for since and timestamps; this draft extends that direction with the remaining line-retrieval filters needed by container logs and external API clients: tail and until.

The motivation is to keep Docker-style log retrieval semantics close to the service that owns the log files, rather than requiring every caller to replay and filter the complete stream locally. This is useful for the container logs CLI and for external orchestrators, while keeping Compose-specific formatting and policy out of apple/container.

Draft/stacking note: this branch is based on full-chaos/container:feat/chaos-1322-log-options from #1592. Because GitHub PRs to apple/container target main, this diff includes #1592 plus the follow-up commits below. The intended review delta for this draft is:

• ece5d5d feat(logs): add tail and until retrieval filters
• bd178e8 fix(logs): harden tail replay filters
• acab75a test(logs): cover byte-preserving log replay
• 881f9e9 fix(logs): fail closed when filtering logs
• b8d7675 test(logs): close filtered log handles
• f4e2723 test(logs): close command log handles
• 03c2594 docs(logs): clarify followed time filter limitation
• 4884d25 fix(logs): create filtered logs with private permissions
• 897665a fix(logs): require unlinking filtered log files

What Changed

• Extends ContainerLogOptions with tail and until while preserving the existing zero-option behavior.
• Plumbs tail, since, and until through ContainerClient, XPC, the harness, and ContainersService.
• Applies tail after service-side line filtering, with Docker-compatible negative-tail behavior treated as "all".
• Adds a bounded service-side tail scan for static tail-only requests instead of reading the whole log into memory.
• Adds byte-preserving local output for followed raw logs so negative tail and non-UTF-8 log bytes do not crash or decode incorrectly.
• Adds container logs --tail long-form support and --since / --until CLI arguments.
• Preserves unparseable and non-UTF-8 raw log bytes while filtering what can be safely filtered.
• Fails closed when filtered log replay cannot create the temporary filtered handle, so callers do not silently receive unfiltered logs.
• Creates filtered replay files with exclusive owner-only permissions and requires successful unlink before returning the replay handle.
• Closes filtered and command log handles explicitly in focused tests.
• Clarifies that followed time filters are not supported for this static-replay draft.
• Updates the command reference for the new CLI options and the current followed time-filter limitation.

Relationship to Existing Work

• Builds on Add container log retrieval options #1592 rather than replacing it.
• Related to [Request]: Add container log retrieval options #1591 and Support Docker Compose-compatible container log semantics #1752.
• If maintainers prefer, the retrieval-only shape from this draft can be folded into Add container log retrieval options #1592 before that PR lands.

Non-Goals

• This does not add structured log records.
• This does not add timestamp rendering for raw logs.
• This does not add Compose-specific behavior.
• This does not support followed --since / --until yet; those filters are static replay only in this draft.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Local verification:

swift format lint --strict --configuration .swift-format-nolint Sources/ContainerCommands/LogFileOutput.swift Sources/ContainerCommands/Container/ContainerLogs.swift Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift Tests/ContainerCommandsTests/ContainerLogsCommandTests.swift Tests/ContainerAPIServiceTests/ContainerLogsTests.swift Tests/ContainerResourceTests/ContainerLogOptionsTests.swift
git diff --check
swift build
swift test --filter ContainerLogsCommandTests
swift test --filter ContainerLogsTests
swift test --filter ContainerLogOptionsTests

Result: focused validation passed locally. The focused tests ran 25 tests across ContainerLogsCommandTests, ContainerLogsTests, and ContainerLogOptionsTests.

[stephenlclarke]

@chrisgeo, I tried to add you as a reviewer but GitHub would not let me request review from this fork. These draft follow-ups are stacked on your log retrieval options work in #1592. No pressure for a full review yet; early guidance on API shape and whether this fits your intended direction would be really useful before I polish them for maintainer review.