chore: highlight deterministic foundation for AI governance in SDI

src/main/resources/wiki/Spec‐Driven-Integration.md

@@ -38,10 +38,16 @@ A single specification can give rise to multiple integration variants, each opti
 
 SDI as a methodology is tool-agnostic, but it requires concrete artifacts to be effective: a specification format expressive enough to capture integration intent, and a runtime capable of executing that specification without translation.
 
-**The Capability Specification**  
-The natural SDI artifact is a *capability specification* — a declarative document that defines a bounded integration unit: what upstream APIs it consumes, how data is shaped and composed, what contract it exposes to downstream consumers, and under what conditions. A well-formed capability spec is self-contained and human-readable, without requiring knowledge of the underlying implementation.
+**The Capability as a Container for Business Value**  
+In SDI, a *capability* is more than an integration artifact — it is a container for business value. Each capability encapsulates three dimensions that together define a complete, self-contained unit of organizational worth:
 
-In practice, this means a structured YAML document that describes inputs, outputs, transformation logic, authentication, and protocol mappings in a single place. The spec *is* the integration — not a description of it.
+- **Business context** — the domain knowledge that gives the capability meaning: what upstream systems it connects to, what authentication and compliance boundaries apply, and what organizational constraints shape its behavior. Context answers *why this integration exists* and *under what conditions it operates*.
+- **Business function** — the concrete operations the capability performs: consuming upstream APIs, transforming and composing data, and exposing well-shaped contracts to downstream consumers. Function answers *what the integration does* — the inputs it accepts, the outputs it produces, and the logic that connects them.
+- **Business events** — the signals that trigger, inform, or result from the capability's execution: webhooks, state changes, notifications, and feedback loops that tie the capability into the broader operational landscape. Events answer *when the integration acts* and *what happens as a consequence*.
+
+A capability specification is the declarative document that captures all three dimensions in a single place. It is self-contained and human-readable, without requiring knowledge of the underlying implementation. In practice, this means a structured YAML document that describes domain context, operational functions, transformation logic, authentication, protocol mappings, and event flows. The spec *is* the integration — not a description of it.
+
+This framing matters because it aligns integration boundaries with business boundaries. When a capability maps to a recognizable unit of business value — not just an API endpoint or a data pipeline — it becomes something the organization can reason about, prioritize, and govern at the right level of abstraction.
 
 **The Capability Engine**  
 For specifications to be executable, a runtime must interpret them directly. Rather than generating code from a spec (which reintroduces drift), the engine reads the specification at runtime and handles all integration concerns: HTTP consumption, data transformation, format conversion, and exposure via REST or MCP interfaces.
@@ -62,4 +68,16 @@ This cycle keeps the specification as the primary artifact throughout — ensuri
 
 SDI is particularly well-suited to the demands of AI-driven architectures. Context engineering — shaping, filtering, and composing data for AI model consumption — is fundamentally an integration problem. Agent orchestration surfaces, such as MCP servers and tool-based APIs, require exactly the kind of right-sized, semantically coherent integration boundaries that SDI is designed to produce.
 
-When specifications are the primary artifact, AI agents can reason about integrations, propose refinements, and validate consistency — treating the specification as a structured, inspectable contract rather than opaque runtime behavior.
+When specifications are the primary artifact, AI agents can reason about integrations, propose refinements, and validate consistency — treating the specification as a structured, inspectable contract rather than opaque runtime behavior.
+
+**A Deterministic Foundation for Agents**  
+AI agents are powerful reasoning engines, but they are non-deterministic by nature — their outputs vary across invocations, they can hallucinate plausible-but-wrong API contracts, and they have no built-in mechanism to guarantee that a tool call today behaves the same as it did yesterday. This is acceptable for generation tasks; it is unacceptable for integration, where correctness, repeatability, and auditability are non-negotiable.
+
+SDI addresses this by placing a deterministic layer beneath the agent. The capability specification defines — precisely and immutably for a given version — what data is consumed, how it is shaped, and what contract is exposed. The engine executes that specification without interpretation. There is no room for the runtime to invent a field, guess a mapping, or silently change a response shape. What the spec declares is what the agent receives.
+
+This deterministic foundation reduces two categories of risk that compound in agent-driven architectures:
+
+- **Drift risk**: When integration logic lives in code maintained by multiple teams — or worse, in prompts and agent memory — behavior drifts invisibly over time. SDI anchors integration behavior to a versioned, diffable artifact. If the spec has not changed, the integration has not changed. Drift becomes visible as a spec delta, not as a mysterious production incident.
+- **Hallucination risk**: Agents tasked with calling APIs or composing tool outputs can fabricate parameter names, assume response structures, or invent error-handling paths that do not exist. When integrations are mediated by a spec-driven engine, the agent operates against a declared contract — not against its own inference of what the API might return. The specification constrains the agent to reality.
+
+Together, these properties enable **operational governance of AI**: organizations can audit what an agent can access, review what transformations are applied, version-control every change, and enforce approval workflows — all through the specification. Governance shifts from monitoring opaque agent behavior after the fact to controlling the integration contracts agents depend on before deployment. The specification becomes the governance surface.