Distributed Cognitive Network

Volume VII — Cognitive ABI Specification 0.1

Part 1 — Core Runtime Objects, Invocation Contract, and Interoperability Boundary

1. Scope

The Cognitive ABI defines the stable semantic interface between cognitive components. Its purpose is to ensure that an Agency, expert, K-line, artifact, compiler, evaluator, market adapter, or remote Mind can participate in the same runtime without depending on the implementation details of DCN Runtime, SurrealDB, a particular model vendor, or a particular transport.

The ABI is not a machine-code ABI. It is a semantic cognitive interface.

A conformant implementation MUST preserve the meaning of the canonical objects and transitions defined here even when it maps them to different languages, transports, process boundaries, or storage engines.

2. Design objective

The canonical execution path is:

Observation / Goal
       ↓
CapabilityRequirement
       ↓
Resolution
       ↓
ExpertBinding
       ↓
Execution
       ↓
PatchProposal / Result
       ↓
Evaluation
       ↓
KLineEpisode
       ↓
Learning / Compilation

Every interoperable cognitive component participates at one or more points in this path.

3. ABI principles

The ABI SHALL be capability-oriented, typed, evidence-aware, authority-aware, asynchronous-capable, transport-neutral, failure-explicit, and versioned.

The ABI SHALL NOT assume that a component is an LLM, that cognition is remote, that execution is stateless, or that successful execution is authorized to mutate world state.

4. Canonical object families

Version 0.1 defines these object families:

Observation
Goal
ContextSlice
CapabilityRequirement
CapabilityResolution
ExpertBinding
ExecutionRequest
ExecutionResult
PatchProposal
ValidationResult
EvaluationRequest
EvaluationResult
KLineEpisode
CompilationRequest
ArtifactCandidate
RuntimeEvent
ErrorEnvelope

Protocol-specific objects such as KLineTemplate, KLineArtifact, ExecutionAct, and SettlementAct are referenced by identity and commitment rather than redefined by the ABI.

5. Common envelope

Every ABI message SHALL carry a common envelope:

{
  "abi": "dcn.cognitive-abi.v1",
  "message_id": "msg:...",
  "message_type": "ExecutionRequest",
  "correlation_id": "corr:...",
  "causation_id": "msg:...",
  "sender": "component:...",
  "recipient": "component:...",
  "created_at": "...",
  "deadline": null,
  "context_commitment": "sha256:...",
  "authority_ref": null,
  "trace_ref": null,
  "payload": {}
}

correlation_id groups messages belonging to one cognitive process. causation_id identifies the message or event that directly caused the current message.

6. Component identity

Every ABI participant SHALL expose a stable ComponentDescriptor containing:

component_id
component_type
supported_abi_versions
capabilities
input/output schemas
execution modes
security properties
privacy properties
evidence capabilities
resource profile

Component types MAY include:

agency
expert
artifact
compiler
evaluator
resolver
market_adapter
memory_adapter
authority_adapter
remote_mind

7. Capability declaration

A component SHALL declare what it can do using semantic capabilities rather than tool names alone.

Example:

{
  "capability": "software_engineering.code_review",
  "input_schema": "schema:code-review-input:v1",
  "output_schema": "schema:code-review-result:v1",
  "quality_claims": [],
  "evidence_classes": ["signed_runtime"],
  "execution_modes": ["local"]
}

Tool protocols such as MCP MAY expose the transport-level invocation, but the Cognitive ABI defines the semantic contract consumed by the Cognitive Kernel.

8. Observation

An Observation represents something perceived by the Mind before interpretation has been promoted into world-state belief.

{
  "schema": "dcn.observation.v1",
  "id": "observation:...",
  "source": "component:...",
  "observed_at": "...",
  "content_type": "...",
  "content_ref": "...",
  "content_commitment": "sha256:...",
  "provenance": [],
  "confidence": null
}

Observations are inputs to cognition, not automatic truth claims.

9. Goal

A Goal describes desired future state rather than an imperative tool invocation.

{
  "schema": "dcn.goal.v1",
  "id": "goal:...",
  "desired_state": {},
  "priority": 0.8,
  "deadline": null,
  "constraints": [],
  "dependencies": [],
  "owner": "mind:..."
}

The runtime MAY derive tasks and capability requirements from goals.

10. ContextSlice

A ContextSlice is the minimum semantically relevant subset of Mind state exposed to a cognitive component.

It SHOULD contain references or commitments instead of indiscriminately copying world state.

{
  "schema": "dcn.context-slice.v1",
  "world_snapshot": "sha256:...",
  "goal_refs": [],
  "entity_refs": [],
  "episode_refs": [],
  "kline_refs": [],
  "policy_refs": [],
  "authority_refs": [],
  "private_data_refs": []
}

Context minimization is an ABI requirement because cognition may execute across trust and privacy boundaries.

11. CapabilityRequirement

The ABI reuses the CapabilityRequirement defined by the K-Line Protocol. It is the canonical demand object for cognition.

Components MUST NOT silently relax mandatory fields such as minimum evidence, privacy, jurisdiction, cost ceiling, latency ceiling, or authority conditions.

12. CapabilityResolution

A resolver returns zero or more candidate bindings rather than directly executing cognition.

{
  "schema": "dcn.capability-resolution.v1",
  "requirement_hash": "sha256:...",
  "candidates": [],
  "resolver": "component:...",
  "resolved_at": "..."
}

The Cognitive Kernel applies local admissibility and routing policy to the result.

13. ExpertBinding

ExpertBinding is the late-bound execution selection defined by the K-Line Protocol. ABI messages MUST preserve the exact binding used so an eventual episode can reconstruct what actually happened.

14. ExecutionRequest

{
  "schema": "dcn.execution-request.v1",
  "execution_id": "execution:...",
  "requirement_hash": "sha256:...",
  "binding": {},
  "context": {},
  "input_ref": "...",
  "input_commitment": "sha256:...",
  "budget": {},
  "authority_ref": null,
  "evidence_requirement": {},
  "deadline": null
}

Receipt of an ExecutionRequest does not imply permission to perform undeclared side effects.

15. ExecutionResult

{
  "schema": "dcn.execution-result.v1",
  "execution_id": "execution:...",
  "status": "completed",
  "output_ref": "...",
  "output_commitment": "sha256:...",
  "proposed_patches": [],
  "evidence_refs": [],
  "metrics": {
    "latency_ms": 0,
    "cost": null,
    "energy": null
  },
  "diagnostics": []
}

An execution may successfully return a result even when its proposed side effects are later rejected.

16. PatchProposal

The ABI reuses the DCN Runtime Patch Proposal Protocol. Patch proposals are semantic state-transition requests, not generic database mutations.

Every proposal SHALL reference the base world-state commitment against which it was generated.

17. ValidationResult

Validation is independent from generation.

{
  "schema": "dcn.validation-result.v1",
  "subject": "patch:...",
  "status": "allowed",
  "checks": [],
  "required_authority": [],
  "conflicts": [],
  "evidence_refs": []
}

A validator MUST NOT silently rewrite the subject it validates.

18. EvaluationRequest and EvaluationResult

Evaluation is a first-class ABI operation. Requests SHALL identify the evaluation protocol and exact subject commitment. Results SHALL remain contextual to the declared distribution and environment.

19. KLineEpisode handoff

After execution and validation, the runtime MAY materialize a KLineEpisode. The ABI SHALL preserve sufficient identifiers, commitments, bindings, evidence references, metrics, and causal links to reconstruct the episode without depending on opaque model transcripts.

20. CompilationRequest

A promoted or repeatedly expensive cognitive topology MAY produce a CompilationRequest:

{
  "schema": "dcn.compilation-request.v1",
  "template_ref": "kline:template:...",
  "episode_refs": [],
  "evaluation_refs": [],
  "targets": ["ios-arm64"],
  "objectives": ["cost", "latency", "energy"],
  "constraints": {
    "quality_floor": 0.95,
    "privacy": "local_only"
  }
}

The Compiler Society may respond with multiple ArtifactCandidates.

21. Runtime events

All ABI implementations SHOULD emit causal runtime events for significant state changes. Recommended events include:

ObservationReceived
GoalCreated
CapabilityRequested
CapabilityResolved
ExecutionStarted
ExecutionCompleted
PatchProposed
PatchValidated
PatchCommitted
EvaluationCompleted
EpisodeRecorded
CompilationRequested
ArtifactProduced

Events SHALL carry correlation and causation identifiers.

22. Asynchrony

ABI operations MAY complete synchronously or asynchronously. Long-running execution MUST NOT require a transport connection to remain continuously open.

Asynchronous operations SHALL expose stable operation identity and observable lifecycle state.

23. Cancellation

Cancellable operations SHALL accept a cancellation signal by operation identity. Cancellation MUST NOT fabricate rollback of external side effects that have already occurred; such effects require compensating Acts or patches.

24. Failure model

Failures are explicit data, not exceptions that disappear at process boundaries.

ErrorEnvelope SHALL distinguish at least:

invalid_input
capability_unavailable
authority_denied
policy_denied
budget_exceeded
deadline_exceeded
execution_failed
evidence_failed
validation_failed
conflict
cancelled
transport_failed
internal_error

Retryability SHOULD be declared independently from error class.

25. Version negotiation

Every component SHALL advertise supported ABI versions. Peers MUST negotiate a mutually supported version before exchanging semantic messages whose interpretation differs across versions.

Backward-compatible extension fields SHOULD be ignored when unknown unless marked critical.

26. Transport neutrality

The ABI MAY be carried over:

in-process calls
stdio
MCP
A2A
HTTP
message queues
local IPC
future transports

Transport-specific authentication and framing MUST NOT redefine the semantic object model.

27. Agent Plugins

Agent Plugins MAY package ABI-capable components by providing skills and MCP servers. Installation makes the component discoverable; it does not create authority, spend permission, trust, or capacity publication.

28. Relationship to MCP

MCP answers: How is a tool or resource invoked?

The Cognitive ABI answers: What cognitive contract is being requested, what constraints apply, what evidence is required, and how does the result enter the Mind's learning and state-transition lifecycle?

MCP is therefore a possible transport/interface binding beneath the ABI rather than a replacement for it.

29. Relationship to A2A

A2A may carry negotiation and communication between autonomous agents or Minds. The Cognitive ABI defines the semantic objects exchanged when those interactions request or return cognition.

30. Relationship to Actum Compute

Actum Compute implements network-level resolution and procurement of CapabilityRequirements. Its quote, assignment, execution receipt, and settlement objects bind to the same requirement and execution identities used by the ABI.

31. Relationship to Actum

ABI lifecycle events MAY ultimately produce Actum cognition Acts. ABI messages themselves are not automatically ledger entries. Only transitions requiring durable verifiable history need to be anchored.

32. Conformance

A Cognitive ABI 0.1 implementation MUST:

1. support the common message envelope;
2. support semantic CapabilityRequirement invocation;
3. preserve exact ExpertBindings;
4. separate execution results from state mutation;
5. preserve authority references across boundaries;
6. preserve evidence requirements and evidence references;
7. support explicit failure objects;
8. support version negotiation;
9. preserve correlation and causation identity;
10. avoid assuming any particular model vendor, transport, storage engine, or programming language.

The Cognitive ABI is the interoperability boundary that allows the Distributed Cognitive Network to evolve without binding cognition to today's model APIs or agent frameworks.