DivineTree.ICP 1.0.2

DivineTree.ICP

Intelligence Carrier Pattern — Sovereign Intelligence Carrier for Agentic Orchestration

The Problem

Agentic systems decompose goals into tasks, route tasks across agents, and make reasoning decisions at every step. At each boundary, the intelligence context — who asked, why, what was decided, and how confident was the model — is lost.

Logs capture what happened. ICPEnvelope carries why it happened.

Traditional approaches:

• Pass raw intent objects between agents — reasoning context stripped at every boundary
• Reconstruct decisions from logs — expensive, lossy, unreliable for audit
• Embed orchestration state in domain payloads — violates separation of concerns

The Intelligence Carrier Pattern solves this by making the envelope — not the intent — the unit of agentic intelligence.

What Is ICP?

The Intelligence Carrier Pattern wraps every agentic intent in an ICPEnvelope<TIntent> that carries three intelligence layers:

The envelope travels with the intent across every orchestration boundary. When the goal completes, the envelope contains a complete, tamper-evident record of every reasoning and routing decision.

Relationship to DivineTree.DCP

ICP and DCP are sovereign peers. They never reference each other at the type level.

DivineTree.DCP          — Data Carrier Pattern
DataEnvelope<T>         — carries domain payloads
IEnvelopeContext        — situational awareness for data
ILineageChain           — transformation history for data

DivineTree.ICP          — Intelligence Carrier Pattern
ICPEnvelope<TIntent>    — carries agentic intelligence
IICPContext             — situational awareness for goals
IICPLineage             — reasoning history for goals

The handoff between ICP and DCP occurs at the service boundary:

ICPEnvelope<GoalRequest> routes the goal
    → CLPlatform receives it
    → Creates DataEnvelope<DomainPayload> for the domain workflow
    → ICP envelope is garbage collected after handoff

ICP extends DCP interfaces — IICPContext extends IEnvelopeContext, IICPStep extends ILineageStep, IICPLineage extends ILineageChain — enabling cross-pattern observability without coupling.

Installation

dotnet add package DivineTree.ICP

This automatically installs DivineTree.DCP as a transitive dependency.

Quick Start

using DivineTree.ICP;

// 1. Create your context — who initiated this goal
var context = new MyICPContext(
    goalId:        Guid.NewGuid().ToString("N"),
    correlationId: traceId,
    userId:        "officer-001",
    channel:       "web");

// 2. Wrap your intent in an envelope
var envelope = new ICPEnvelope<GoalRequest>(goalRequest, context, new MyICPLineage());

// 3. Record reasoning and routing decisions
envelope.AppendStep("goal_received",   "GoalController");
envelope.AppendStep("goal_decomposed", "DecompositionService");
envelope.AppendStep("task_routed",     "GoalRouter");

// 4. Pass the envelope — not the raw intent — across boundaries
await goalRouter.RouteAsync(envelope);

// 5. Persist the audit summary — never persist the full envelope
await auditLogger.WriteAsync(envelope.ToICPAuditSummary());

Envelope Anatomy

ICPEnvelope<TIntent>
├── EnvelopeId       — Unique ID for this envelope instance (from DCP)
├── EnvelopeVersion  — Schema version for forward compatibility (from DCP)
├── Payload          — TIntent — the goal artifact (GoalRequest, TaskGraph, TaskNode)
├── Context          — IICPContext — who, where, when, which goal
├── ICPLineage       — IICPLineage — every reasoning and routing step
└── ToICPAuditSummary() — the only thing persisted

Implementing the Interfaces

DivineTree.ICP ships interfaces and ICPEnvelope<TIntent> only. Your platform provides the implementations.

Minimal IICPContext:

public sealed class MyICPContext : IICPContext
{
    public string GoalId        { get; }
    public string CorrelationId { get; }
    public string UserId        { get; }
    public string Channel       { get; }
    public DateTime CreatedAt   { get; } = DateTime.UtcNow;
    public string WorkflowId    => GoalId;
    public string FacadeId      => Channel;
    public string SchemaVersion => "1.0.0";
    public IReadOnlyDictionary<string, string> Properties { get; }
        = new Dictionary<string, string>();

    public MyICPContext(
        string goalId, string correlationId,
        string userId, string channel)
    {
        GoalId        = goalId;
        CorrelationId = correlationId;
        UserId        = userId;
        Channel       = channel;
    }

    public static MyICPContext New(string userId, string channel) => new(
        goalId:        Guid.NewGuid().ToString("N"),
        correlationId: Guid.NewGuid().ToString("N"),
        userId:        userId,
        channel:       channel);
}

Minimal IICPLineage:

public sealed class MyICPLineage : IICPLineage
{
    private readonly List<ILineageStep> _steps = new();
    public ILineageStep? Origin  => _steps.Count > 0 ? _steps[0]  : null;
    public ILineageStep? Latest  => _steps.Count > 0 ? _steps[^1] : null;
    public IReadOnlyList<ILineageStep> Steps => _steps.AsReadOnly();
    public int StepCount => _steps.Count;

    public void AppendStep(ILineageStep step)
    {
        ArgumentNullException.ThrowIfNull(step);
        _steps.Add(step);
    }

    public void Append(string stepName, string actorId,
        Dictionary<string, string>? metadata = null)
        => _steps.Add(new MyICPStep(stepName, actorId));

    public IReadOnlyList<ILineageStep> GetStepsByActor(string actorId) =>
        _steps.Where(s => s.ActorId.Equals(actorId, StringComparison.OrdinalIgnoreCase))
              .ToList().AsReadOnly();

    public IReadOnlyList<ILineageStep> GetStepsByName(string stepName) =>
        _steps.Where(s => s.StepName.Equals(stepName, StringComparison.OrdinalIgnoreCase))
              .ToList().AsReadOnly();
}

Reasoning Step Naming Convention

Step names must be snake_case and describe the reasoning act, not the actor.

The actor is captured in ActorId. The step name describes what happened to the intelligence.

Creation Responsibility

The orchestration component that receives a goal creates the ICPEnvelope<TIntent>. Infrastructure — message buses, state stores, HTTP middleware — never creates envelopes on behalf of orchestrators.

Audit and Persistence

Only ToICPAuditSummary() should be persisted. The full envelope may contain sensitive goal context.

// Correct — persist the audit summary only
await auditLogger.WriteAsync(envelope.ToICPAuditSummary());

// Wrong — envelope may contain sensitive context
await repository.SaveAsync(envelope);

Standard Reasoning Step Names

Use these standard step names for cross-platform consistency:

Cross-Language Support

The ICP pattern is language-agnostic. DivineTree.ICP is the C# / .NET 9 reference implementation.

Reference Implementation

MajdUAE — Sovereign Agentic Platform for UAE FDI Processing — is the reference implementation of ICP at production scale. AgenticOS.DCP implements DivineTree.ICP across the full goal decomposition and routing pipeline.

Repository: github.com/DivineTreeDesigns/UAEAgentic

Design Principles

1. The envelope travels with the intent. Never strip it at an orchestration boundary.
2. The intent is immutable by convention. Do not mutate TIntent after envelope creation.
3. Only ToICPAuditSummary() is persisted. The full envelope stays in memory.
4. The orchestrator creates the envelope. Infrastructure never creates envelopes.
5. Lineage is append-only. Steps cannot be removed, reordered, or modified.
6. ICP and DCP are sovereign peers. They never reference each other at the type level.

Related Packages

• DivineTree.DCP — Data Carrier Pattern — domain payload intelligence

License

MIT — see LICENSE.

DivineTreeDesigns — Sovereign Confidential