What changes for the reader
patterns.md has no worked example showing how to model outbound calls to an
external API or service from a spec's own perspective. The closest existing
patterns point the reader the wrong way for this case:
- Pattern 6 (
APIAccess) models exposing a consumer-facing, rate-limited API
using exposes / provides. The API is the surface owner; the consumer is
the facing party.
- Pattern 9 (Framework Integration Contract) models a framework-to-plugin
boundary with contracts: demands / fulfils.
Neither shows the very common case: "my spec is a client that calls an external
typed API" (a third-party REST service, an SDK, an MCP server). A reader looking
for "how do I model calling out to service X" finds the word "API" only in
Pattern 6 and reasonably, but wrongly, reaches for provides:.
Why it matters
Calling an external service is one of the most common integration shapes. The
intended construct is a module-level contract referenced via
contracts: demands ExternalApi from the caller's side, but without a worked
example this is hard to discover. We hit exactly this while modelling an MCP
server boundary: lacking a "calling an external API" pattern, the model was
first written with provides: (user-facing semantics) before being corrected to
contract + contracts:. A named example would have prevented the detour, for
humans and for AI assistants reading the patterns as guidance.
Desired
Add an example (its own pattern, or a sub-example under Pattern 9) that shows:
- a module-level
contract for an external API with typed signatures
- a surface that references it from the caller's perspective via
contracts: demands ExternalApiName
- a short note contrasting the directions:
demands (I call out to / require
the counterpart to implement) versus fulfils (I supply this API) versus
provides (a user triggers an action that fires a domain rule)
Out of scope
- Any change to the language or grammar itself
- Documentation of zero-argument contract signatures (separate concern)
Related
- Pattern 6
APIAccess and Pattern 9 Framework Integration Contract: skills/allium/references/patterns.md
- Contracts section:
skills/allium/references/language-reference.md
What changes for the reader
patterns.md has no worked example showing how to model outbound calls to an
external API or service from a spec's own perspective. The closest existing
patterns point the reader the wrong way for this case:
APIAccess) models exposing a consumer-facing, rate-limited APIusing
exposes/provides. The API is the surface owner; the consumer isthe
facingparty.boundary with
contracts: demands / fulfils.Neither shows the very common case: "my spec is a client that calls an external
typed API" (a third-party REST service, an SDK, an MCP server). A reader looking
for "how do I model calling out to service X" finds the word "API" only in
Pattern 6 and reasonably, but wrongly, reaches for
provides:.Why it matters
Calling an external service is one of the most common integration shapes. The
intended construct is a module-level
contractreferenced viacontracts: demands ExternalApifrom the caller's side, but without a workedexample this is hard to discover. We hit exactly this while modelling an MCP
server boundary: lacking a "calling an external API" pattern, the model was
first written with
provides:(user-facing semantics) before being corrected tocontract+contracts:. A named example would have prevented the detour, forhumans and for AI assistants reading the patterns as guidance.
Desired
Add an example (its own pattern, or a sub-example under Pattern 9) that shows:
contractfor an external API with typed signaturescontracts: demands ExternalApiNamedemands(I call out to / requirethe counterpart to implement) versus
fulfils(I supply this API) versusprovides(a user triggers an action that fires a domain rule)Out of scope
Related
APIAccessand Pattern 9 Framework Integration Contract:skills/allium/references/patterns.mdskills/allium/references/language-reference.md