chore: highlight deterministic foundation for AI governance in SDI by jlouvel · Pull Request #322 · naftiko/framework

jlouvel · 2026-04-14T13:58:35Z

What does this PR do?

Revises the Spec-Driven Integration wiki page with two additions:

Capability as a container for business value — Reframes "The Capability Specification" subsection to define a capability as a self-contained unit encapsulating three business dimensions: context (why it exists), function (what it does), and events (when it acts). Aligns integration boundaries with business boundaries rather than technical ones.
A deterministic foundation for agents — New subsection under "SDI and AI Integration" articulating how SDI provides a deterministic layer beneath non-deterministic AI agents. Identifies drift risk and hallucination risk as two compounding categories SDI mitigates, and connects them to operational governance of AI — the specification as the auditable, version-controlled governance surface.

Tests

No tests — documentation-only change (wiki content).

Checklist

CI is green (build, tests, schema validation, security scans)
Rebased on latest main
Small and focused — one concern per PR
Commit messages follow Conventional Commits

Agent Context (optional)

agent_name: GitHub Copilot
llm: Claude Opus 4.6
tool: VS Code Chat
confidence: high
source_event: user request to revise SDI wiki page
discovery_method: user_report
review_focus: src/main/resources/wiki/Spec‐Driven-Integration.md

eskenazit

LGTM

kinlane

This is a great start in capturing why SDI matters. Agree with it all, added a few thoughts that could help shape evolution, but nothing in new direction.

Using this vision to guid governance via policies, ensuring that policies capture and express clearly when, where, and why deterministic or non-determinism matters for different domains via a sort of coverage on the spec-driven core of Naftiko will help the fleet move in the right fdirection..

kinlane · 2026-04-14T16:49:45Z

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

-**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:


I like. A lot. The question is, how do you address at scale in aggregation, and align with the ship or vessel metaphor that could have my containers collectively bringing business value.

Good point, let me iterate on this

kinlane · 2026-04-14T16:53:52Z

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

+- **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.


I'd like to see example capabilities that are parsed with this in mind -- what percentage of the spec (properties) are context, functions, and events -- what is the governance, validation, and coverage of this concept over an real world capability.

Some of this is a vision statement. Naftiko Framework doesn't yet support events or semantics formally. We do have Aggregates now including domain Functions though and Skills via the Agent Skills adapter.

kinlane · 2026-04-14T16:54:59Z

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

+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.


"Rather than generating code from a spec (which reintroduces drift)" -- these are fight'n words in some corners. What is impact on SDK debate?

Agreed, adding a paragraph embracing some select derived artifacts like SDKs

kinlane · 2026-04-14T16:56:26Z

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

@@ -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.


How much of the current security concerns around AI integration aren't really technical, but a lack of "right-sized, semantically coherent integration boundaries"

It is helping with security for sure, adding a mention

jlouvel · 2026-04-14T22:26:21Z

@kinlane Thanks for the positive and constructive feedback. I have prepared a new PR to address them. Could you review again and let's move the conversation there: #324

jlouvel added 2 commits April 14, 2026 09:21

chore: highlight deterministic foundation for AI governance in SDI

ef8a0a1

chore: frame capability as container for business value in SDI

0d86c37

jlouvel requested review from eskenazit and kinlane April 14, 2026 13:58

jlouvel self-assigned this Apr 14, 2026

eskenazit approved these changes Apr 14, 2026

View reviewed changes

eskenazit merged commit f4ad291 into main Apr 14, 2026
2 checks passed

eskenazit deleted the chore/sdi-revision branch April 14, 2026 14:11

kinlane reviewed Apr 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: highlight deterministic foundation for AI governance in SDI#322

chore: highlight deterministic foundation for AI governance in SDI#322
eskenazit merged 2 commits intomainfrom
chore/sdi-revision

jlouvel commented Apr 14, 2026

Uh oh!

eskenazit left a comment

Uh oh!

Uh oh!

kinlane left a comment

Uh oh!

kinlane Apr 14, 2026

Uh oh!

jlouvel Apr 14, 2026

Uh oh!

kinlane Apr 14, 2026

Uh oh!

jlouvel Apr 14, 2026

Uh oh!

kinlane Apr 14, 2026

Uh oh!

jlouvel Apr 14, 2026

Uh oh!

kinlane Apr 14, 2026

Uh oh!

jlouvel Apr 14, 2026

Uh oh!

jlouvel commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -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.

Conversation

jlouvel commented Apr 14, 2026

What does this PR do?

Tests

Checklist

Agent Context (optional)

Uh oh!

eskenazit left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kinlane left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jlouvel commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants