Model Real Upstream Surface
BOUNDARY-MODEL-REAL-UPSTREAM-SURFACE
Summary
Shape local integration APIs around the providers actual records, pages, permissions, rate limits, and consistency behavior. Wrappers may simplify common paths, but they should not promise capabilities the upstream cannot provide.
Rule
Model each integration as the real upstream surface it exposes.
Why
Adapters should not pretend a provider supports a cleaner or broader API than it actually does. If the upstream exposes records, pages, eventual consistency, rate limits, or partial permissions, the local model must either expose or deliberately handle those constraints.
Helps
- Prevents local APIs from promising behavior the upstream cannot provide.
Limits
A wrapper can simplify the common case, but it should still document or return clear errors for unsupported upstream shapes.
Agent Instruction
Model each integration as the real upstream surface it exposes because adapters should not pretend a
provider supports a cleaner or broader API than it actually does.Mechanisms
Supported by adapter docs, capability types, unsupported-shape errors, provider fixtures, and integration tests against real or recorded upstream behavior.