docs(confinement): add execution-scope path-set model with order_create example

[omwei-org]

Summary

This change introduces an explicit protected-effect path-set model and makes execution-scope evidence and limitations visible for the confinement documentation.

Key changes

• New section: Execution scope and path sets in docs/confinement.md
• Path classification: distinguishes agent-side paths from deployment-side paths whose coverage requires independent assessment and observation
• Worked example: uses order_create as an illustrative protected effect with four declared path categories (P1–P4); this is not an inventory established for a real order service
• Evidence status: P1–P3 are supported only by specific synthetic confinement probes and generic analogues; they are NOT ESTABLISHED as actual order_create paths
• P4 (external service → orders database) remains DECLARED / NOT ESTABLISHED
• Path-set completeness and the overall complete-mediation claim for order_create remain NOT ESTABLISHED
• Test documentation describes what the fixtures observe without claiming effect-specific coverage

Design rationale

The model distinguishes four different claims:

1. Authorization
2. Correlation
3. Observation
4. Complete mediation: all paths capable of producing the protected effect are within the declared enforcement boundary

Declaring a path set scopes the complete-mediation claim; it does not prove that the set is complete or that every declared path is mediated. The current synthetic fixtures do not invoke an order API or observe an orders database. The EABC NON_BYPASSABILITY(B,E) claim therefore remains unestablished for order_create by these fixtures alone.

Test plan and limitations

• The fixtures exercise synthetic tool delivery and specific canary probes (network, filesystem, child-process, and logging/sink checks); these are not tests of actual order creation or proof of complete path coverage.
• Synchronous tests previously reported as passing: 25/25 in test_adapter.py.
• Async test failures were reported as due to missing pytest-asyncio; this environment limitation should be distinguished from a passing test result.
• Linux Docker tests require CMCP_CONFINEMENT_IMAGE and a suitable Linux/Docker environment.
• No real order service or orders database was tested.

Related issues

• Addresses Define execution scope for protected effects and complete mediation #736 (execution scope for protected effects)
• Builds on Validate that agent egress cannot bypass configured release controls #659 (confinement validation)

[github-actions]

Thanks for this, @omwei-org. Closing it for now, and it is not about the change itself.

This repository asks first-time contributors to be vouched by a maintainer before opening a pull request. That is because agent-written contributions are easy to produce and expensive to review, and we would rather talk to you first than review something neither of us can explain.

To get vouched: open an issue saying what you want to change and why, in your own words. A maintainer will reply, and add you with /vouch. After that, reopen this pull request or open a new one.

See CONTRIBUTING.md for the detail.

[rajnisht7]

The PR direction looks good, but a few places overstate and needs to be tightened:

• “Addressed by declaring” - Declaring a path set only scopes the claim whereas it does not prove complete mediation. it can be stated directly
• order_create vs tests : P1–P3 are marked ENFORCED/TESTED for order_create, but the fixtures only uses synthetic tools and a canary. kindly call this an illustrative example of generic confinement coverage, not proof of order_create
• “All alternate paths” : That test only covers the paths this fixture exercises. it would be good to drop “all” (the limits section already says coverage is partial).
• Network mutation proves the tested escapes (TCP/IPv6/DNS), not every possible route to order_create. kindly narrow the wording.
• File write and subprocess - network are different paths. kindly split them or only claim what was tested
• Listing P1–P4 does not show the list is complete. it will be good to separate “this path was tested” from “the set is complete"
• If P4 is NOT ESTABLISHED, kindly state that overall claim for that effect is also NOT ESTABLISHED
• Logging / sink - Those are confinement checks, not order_create paths. it will be good to keep them out of P1–P3.
• Mutation tests : They show a control was necessary when removed. kindly dont treat them alone as full path coverage
• it would be nice to link or briefly define EABC NON_BYPASSABILITY(B,E)

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[dinakarjs]

Source review at af2a4deccaccbb1769f0c67e0178db9cf481fee9 confirms the scope concerns already raised by rajnisht7. The fixture invokes permitted.tool / public.tool and canary escape probes; it does not execute an order API or observe an orders database. Consequently ENFORCED / TESTED cannot yet be a result for order_create. A declared path list also does not establish completeness; with the external writer path unassessed, the overall effect-boundary claim remains NOT ESTABLISHED.

I prepared a bounded correction for integration: dinakarjs#1 — three files against this exact head. It labels the worked example illustrative, splits file-write from child-network routes, names the actual parent IPv4/IPv6 TCP, UDP/DNS and child IPv4 probes, separates logging/sink tests from order-producing paths, and distinguishes control sensitivity from complete mediation. It also explains the EABC symbol with a link to the existing profile discussion.

Validation: source inspection of examples/confinement/agent.py, tests/confinement/test_linux.py and the documentation; changed test content is docstrings only, with identical executable ASTs before/after; git diff --check passes. I did not rerun native Linux Docker fixtures, execute an order service, or establish deployment coverage. This is a documentation review and proposed patch, not an approval or new runtime-evidence claim.

[imran-siddique]

@omwei-org dinakarjs#1 at 91c8e04 covers all ten of rajnisht7's points, and both test files compare equal to yours once docstrings are set aside, so no executable test changes. It also lands where #736 said this should: each agent-side row names the probe it ran, and the order_create claim reads NOT ESTABLISHED until P4 is observed. Merging it into your branch is the quickest route; can you do that by Oct 16?

[omwei-org]

@omwei-org dinakarjs#1 at 91c8e04 covers all ten of rajnisht7's points, and both test files compare equal to yours once docstrings are set aside, so no executable test changes. It also lands where #736 said this should: each agent-side row names the probe it ran, and the order_create claim reads NOT ESTABLISHED until P4 is observed. Merging it into your branch is the quickest route; can you do that by Oct 16?

Thanks, Imran. I’ll incorporate Dinakar’s changes into my branch and update the PR by October 16.