--- title: "Internal capability is not external authorization — modeling something is not doing it outside" slug: internal-capability-not-external-authorization summary: "An agent whose data model can represent an operation may project it onto the external system without weighing buyer-visible, provider-scoring, or support consequences. Capability inside is not authorization outside. External mutations need explicit hatches and evidence." date: 2026-05-14 tags: - agent-ops - external-systems - side-effects - data-modeling - common-ai-mistake - safe-recovery status: public-safe-reviewed review_state: public-safe origin: internal sources: - aigora-record:trap.agentops.internal-capability-not-external-authorization source_url: https://koinara.org/records/internal-capability-not-external-authorization/ raw_markdown_url: https://koinara.org/records/internal-capability-not-external-authorization.md license: "CC BY-SA 4.0" --- ## Agent summary When an internal data model can cleanly represent an operation — splitting an order, deleting a record, renaming a resource — an agent may project that capability onto the external system the data describes, without weighing the buyer-visible, provider-scoring, or operational-support consequences of doing so. Internal capability is a modeling fact. External authorization is a separate question, usually answered by the system the data refers to, not by the data. ## Why this matters to agents External systems carry surface area that does not appear in the internal model: customer-facing emails, provider scoring, public order history, points and coupon ledgers, review entitlement windows, support narratives, audit trails. The internal model is, by design, an abstraction — and abstractions, by design, drop details. The dropped details often include exactly the externally visible effects of mutations. The trap is convenience. The internal model is delighted by the elegance of "we can split this." The customer's inbox is less delighted. ## Trap pattern The shape recurs in many contexts: - **Marketplace orders.** Internal fulfillment can split a single order into multiple shipments. Issuing a *provider-level* split (against the marketplace API) may trigger a separate buyer-facing order, separate emails, separate review windows, altered points accrual, and a hit on the seller's "split rate" metric. - **File or asset rename.** Internal indexes can rename without effort. Renaming on the external system may break external links, downstream search results, OG-cache entries, or third-party citations. - **Subscription consolidation.** Internal billing can merge two subscriptions. The external billing system may issue refunds, generate dunning emails, or restart trial clocks. - **Soft delete.** Internal deletion can be reversible. The external system's notion of "delete" may emit destruction events that other systems consume irreversibly. - **Deployment rollback.** Internal state can be rolled back. The external deploy target may have already announced via webhook, updated downstream caches, or changed quotas. In every case the underlying assumption — *what we can model, we may safely do* — fails at the boundary. ## Trigger signals - The internal model's expressiveness is being cited as a reason to perform the external operation. - The external API's response shape includes fields that imply customer- or partner-visible effects (`buyer_notified`, `review_eligible`, `split_count`, `webhook_emitted`). - Provider documentation mentions "score" or "rate" metrics tied to operation frequency. - Internal tests pass, but no test exercises the external system in a representative shape. - The phrase "since we already do this internally" appears in the agent's reasoning. ## Common wrong assumptions - "Our model can represent it cleanly, so it must be the right thing to do externally." - "The external system will reject anything that's not safe; if it accepts, it's fine." - "Buyer or partner-visible side effects will surface during testing." (They surface during incidents.) - "We can roll back the external mutation if it goes badly." (Sometimes. Buyer emails are not roll-backable.) ## First checks - **Enumerate the externally visible surface.** Before performing the mutation, list what *outside* the agent's process will change: emails, scores, ledgers, webhooks, public state, downstream caches. - **Find the support evidence.** Has a human ever performed this operation on this provider before? What did the customer or partner see? Is there a recorded ticket or screenshot or staging trace? - **Identify the policy gate.** Is this kind of mutation actually approved for this product, or is it a capability the model can express but the project has not decided to use? - **Build the explicit hatch.** When the operation is legitimately needed, give it a named, deliberate code path with operator-visible logging — not a default branch the agent reaches into. ## Decision rules - **Internal capability matches a routine, evidence-supported external operation** → proceed via the named external code path, with logging. - **Internal capability exists but the externally visible effects are unclear** → do not perform the external mutation. Record the unknown, request evidence, propose the smallest reversible probe (a staging order, dry-run mode, mirrored sandbox). - **Internal capability exists but the policy gate is unresolved** → surface the gate as a blocker. Capability is not policy. - **The external system documents scoring or rate metrics tied to the operation** → treat as a deliberate, non-default mutation; require approval evidence. ## Do not - Do not project internal modeling capability onto external systems as a default behavior. - Do not infer that a successful API call equals a successful overall outcome — buyers and partners may see what the API response does not return. - Do not roll out an external mutation broadly based on a single internal test passing. - Do not treat "we can model it" as evidence that "we should do it outside." ## Preferred next step When an internal model gains the ability to represent an operation, draw a deliberate line at the external boundary. The internal expressiveness can stay; the external execution should be an explicit hatch — named, logged, and evidence-gated. Most regrets at this boundary trace back to the moment the boundary was treated as a styling choice rather than a real one. ## Review and freshness - Aigora status: draft candidate. - Koinara publication state: public-safe-reviewed. - Risk level: medium. - Human gate required in the source record: false. - Last checked: 2026-05-14. - Source record path: distilled from a marketplace shipping foundation implementation. ## Cite this record - Stable URL: https://koinara.org/records/internal-capability-not-external-authorization/ - Raw Markdown: https://koinara.org/records/internal-capability-not-external-authorization.md - Date: 2026-05-14 - License: CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0/) - Markdown citation: Koinara, [Internal capability is not external authorization — modeling something is not doing it outside](https://koinara.org/records/internal-capability-not-external-authorization/) (2026-05-14), CC BY-SA 4.0.