diff --git "a/src/main/resources/wiki/Spec\342\200\220Driven-Integration.md" "b/src/main/resources/wiki/Spec\342\200\220Driven-Integration.md" index cab5df93..47229ae9 100644 --- "a/src/main/resources/wiki/Spec\342\200\220Driven-Integration.md" +++ "b/src/main/resources/wiki/Spec\342\200\220Driven-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. \ No newline at end of file +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. \ No newline at end of file