docs(seatbelt): correct rule-precedence and listen() rationale

[Carlos Alexandro Becker (caarlos0)]

• 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

Follow-up to #749, which a post-merge Copilot review correctly flagged for describing Seatbelt's precedence rules inaccurately. Comments and docs only — no behavior change, and the generated profile is byte-for-byte identical.

Three claims were wrong. All three are corrected against measurements, not reasoning.

1. "An allow can never take authority back from an earlier rule"

False, and it contradicts this backend's own design: the shallow-to-deep emission depends on a later filtered allow overriding an earlier filtered deny.

profile	result
allow then deny, same path	EPERM
deny then allow, same path	CONNECT_OK
shallow deny, deeper allow	CONNECT_OK

The real reason a read-only path still needs an explicit (deny file-write* network-bind network-outbound …) is narrower: the read-only allow names only file-read*, so it says nothing about write or socket operations and cannot displace a broader grant on its own.

2. "deniedPaths is emitted after the network rules so it also overrides the unfiltered (allow network-outbound)"

The override is real, but it does not depend on that ordering — an unfiltered rule never overrides a path-filtered one, in either direction:

profile	result
fs deny, then unfiltered net allow	EPERM
unfiltered net allow, then fs deny	EPERM
unfiltered net allow, no fs deny	CONNECT_OK (control)

The control confirms (allow network-outbound) genuinely does grant AF_UNIX connect(), so the first two rows are the deny winning, not a missing capability.

This one matters beyond accuracy: documenting an ordering constraint that does not exist invites a future change to "fix" the emission order on a false premise.

3. "network-inbound is required in addition to network-bind before the kernel will accept listen()"

Backwards.

profile	result
(allow network-inbound (local ip)) alone	LISTEN_OK
(allow network-bind (local ip)) alone	bind() OK, listen() denied (EPERM)
neither	bind() denied (EPERM)

network-inbound is what governs listen(), and it covers the bind() too. It is network-bind that is insufficient on its own. This also explains why allowLocalNetwork works under defaultPolicy: "block", where write_local_network_rules emits network-inbound and nothing else.

Follow-ups in this PR

Two things surfaced after the initial push, both extending claim 2 rather than adding new scope:

The strip site itself (0d5248b). Both review passes on #749 — Copilot and a human — landed on the same line, the read-only network-outbound strip, and asked whether the later unfiltered allow defeats it. Nothing at that site said otherwise; the comment there only claimed "an allow never denies", which is the phrasing that produced the wrong model. It now states the rule where the question actually gets asked, and names the test that pins it.

Re-verified end-to-end with the real mxc-exec-mac against a listener created outside the sandbox, one field of config apart:

readonlyPaths:  ["/private/tmp/sbt7/ro"]  ->  CONNECT_DENIED [Errno 1] Operation not permitted
readwritePaths: ["/private/tmp/sbt7/ro"]  ->  CONNECT_OK

Two tests still enforced the false constraint (f6fd568, from review feedback). Asserting the deny is emitted after the unfiltered (allow network-outbound) encodes exactly the ordering this PR documents as nonexistent.

• denied_paths_deny_outbound_after_unfiltered_allow → denied_paths_deny_outbound_under_default_allow; keeps the real guarantee, drops the order assert.
• readonly_socket_strip_survives_a_default_allow_outbound had the same guard, added in fix(seatbelt): allow AF_UNIX sockets and resolve symlinked root paths #749 for the same wrong reason. Dropped.

The order assertions that remain are all against filtered allows, where last-match-wins genuinely applies and the deny must come second — denied_paths_appear_after_allows_to_override and denied_paths_deny_unix_socket_ops_after_allows. Those stay; that constraint is real.

Validation

• cargo test -p seatbelt_common → 63 passed, 0 failed
• cargo clippy -p seatbelt_common --all-targets -- -D warnings → clean
• cargo fmt --all -- --check → clean

Every table above was produced with sandbox-exec against a live listener on this host (macOS 26.5.2, arm64).

Microsoft Reviewers: Open in CodeFlow

[Copilot]

Pull request overview

Corrects Seatbelt documentation and code comments without changing generated profiles.

Changes:

• Clarifies filtered-rule precedence and deniedPaths ordering.
• Corrects the rationale for read-only deny rules.
• Documents that network-inbound governs listen().

Show a summary per file

File	Description
src/backends/seatbelt/common/src/profile_builder.rs	Updates precedence and socket-operation comments.
docs/macos-support/seatbelt-backend.md	Corrects filesystem and network policy explanations.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Balanced