| name | swift-protocol-boundaries |
| description | Use when Swift defines or changes XPC, socket, IPC, Codable, serialization, plugin, or other process/module boundaries. Do not invoke for private in-process helper APIs with no compatibility or trust boundary. |
Swift protocol boundaries
Treat the boundary as a hostile, versioned contract. Keep transport mechanics, schema, policy, and domain decisions separate.
Procedure
- Define actors, trust assumptions, direction, framing, maximum sizes, deadlines, cancellation, and compatibility window.
- Model messages as typed enums/structs with explicit success, rejection, and indeterminate outcomes. Reject unknown or malformed data before policy execution.
- Separate wire schema from domain types when evolution, secrecy, or validation differs. Make optionality, defaults, numeric bounds, and canonical encoding explicit.
- Implement bounded framing and one ownership path for buffers/handles. Handle partial reads/writes, EOF, timeout, cancellation, and peer death distinctly.
- Version deliberately: additive fields only when older readers tolerate them; negotiate or reject incompatible versions; never silently reinterpret bytes.
- Test malformed, oversized, truncated, reordered, duplicated, replayed, unknown-version, and unauthorized messages, plus clean shutdown.
Read references/wire-contract-guide.md for the contract checklist.
Guardrails
- Do not use
[String: Any] as a wire schema.
- Do not expose implementation types, file paths, raw errors, or private policy state across the boundary unless they are part of the contract.
- Fail closed for authorization, framing, version, and size failures. Document any deliberate fail-open behavior.
- A successful decode is not authorization and a successful transport write is not successful execution.
Completion contract
Report schema/version, size and timeout bounds, error mapping, trust decisions, compatibility story, and malformed-input proof.
