DivineTree.DCP 1.0.0

DivineTree.DCP

DataMolecule Carrier Pattern — Sovereign Intelligence Carrier for Agentic Systems

The Problem

In agentic systems, data moves across service boundaries — from intake to parsing, from validation to decision, from decision to audit. At each boundary, context is lost.

RAG reconstructs context. DataEnvelope carries it permanently.

Traditional approaches:

• Pass raw data between services — context stripped at every boundary
• Reconstruct context from logs — expensive, lossy, unreliable
• Embed context in payload — couples business data to infrastructure concerns

The DataMolecule Carrier Pattern solves this by making the envelope — not the payload — the unit of intelligence.

What Is DCP?

The DataMolecule Carrier Pattern wraps every domain payload in a DataEnvelope<T> that carries four intelligence layers:

The envelope travels with the payload across every service boundary. When the workflow completes, the envelope contains a complete, tamper-evident record of everything that happened to the data.

Installation

dotnet add package DivineTree.DCP

Quick Start

using DivineTree.DCP;

// 1. Create your context
var context = new MyEnvelopeContext(
    correlationId: traceId,
    workflowId:    applicationId,
    facadeId:      "AF-LoanAgent");

// 2. Wrap your payload in an envelope
var envelope = new DataEnvelope<LoanApplication>(loanApplication, context)
{
    Lineage = new MyLineageChain(),
    Intent  = new MyIntentHints("verify_income_for_underwriting")
};

// 3. Record transformations as the payload moves through the system
envelope.AppendLineageStep(new MyLineageStep(
    stepName:      "document_ingested",
    actorId:       "AF-LoanAgent",
    outputVersion: "1.0.0"));

// 4. Pass the envelope — not the raw payload — across boundaries
await documentParser.ParseAsync(envelope);

// 5. Audit summary for persistence — never persist the full envelope
var auditRecord = envelope.ToAuditSummary();

Envelope Anatomy

DataEnvelope<T>
├── EnvelopeId       — Unique ID for this envelope instance
├── EnvelopeVersion  — Schema version for forward compatibility
├── Payload          — Your domain data (T) — immutable by convention
├── Context          — IEnvelopeContext — situational awareness
├── Lineage          — ILineageChain — transformation history
├── Intent           — IIntentHints — advisory business purpose
└── Observability    — IObservabilityHooks — resource and trace metrics

Implementing the Interfaces

DivineTree.DCP ships interfaces and DataEnvelope<T> only. Your platform provides the implementations. This is intentional — the pattern is technology-agnostic.

Minimal IEnvelopeContext:

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

    public MyContext(string correlationId, string workflowId, string facadeId)
    {
        CorrelationId = correlationId;
        WorkflowId    = workflowId;
        FacadeId      = facadeId;
    }
}

Minimal ILineageStep:

public sealed record MyLineageStep(
    string StepName,
    string ActorId,
    string OutputVersion,
    string? InputVersion = null) : ILineageStep
{
    public DateTime OccurredAt { get; } = DateTime.UtcNow;
    public IReadOnlyDictionary<string, string> Metadata { get; }
        = new Dictionary<string, string>();
}

Minimal ILineageChain:

public sealed class MyLineageChain : ILineageChain
{
    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 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();
}

Lineage Step Naming Convention

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

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

Intent Is Always Advisory

IIntentHints.IsAdvisoryOnly must always return true. Intent hints describe business purpose — they never drive routing, conditional logic, or control flow.

// Correct — code makes decisions, intent describes purpose
if (riskScore > threshold)
    await hitlService.EscalateAsync(envelope);

// Wrong — intent driving control flow — never do this
if (envelope.Intent.PrimaryGoal == "high_risk_review")
    await hitlService.EscalateAsync(envelope);

Creation Responsibility

The domain component that originates a workflow creates the DataEnvelope<T>. Platform infrastructure — message buses, orchestrators, state stores — never creates envelopes on behalf of domain components.

Audit and Persistence

Only ToAuditSummary() should be persisted. The full envelope may contain PII in the payload.

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

// Wrong — payload may contain PII
await repository.SaveAsync(envelope);

NullLineageChain

NullLineageChain.Instance is the default Lineage value — a no-op singleton. All operations are no-ops. StepCount always returns 0. Use it when lineage tracking is not required.

Standard Observability Metric Keys

Cross-Language Support

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

Reference Implementation

MajdUAE — Sovereign Agentic Platform for UAE FDI Processing — is the reference implementation of DCP at production scale: 8 actor-agents, 9 entity-agents, 21 lineage steps, 3-tier HITL model.

Repository: github.com/DivineTreeDesigns/UAEAgentic

Design Principles

1. The envelope travels with the payload. Never strip it at a service boundary.
2. The payload is immutable by convention. Do not mutate T after envelope creation.
3. Intent is always advisory. IsAdvisoryOnly is always true. No exceptions.
4. Only ToAuditSummary() is persisted. The full envelope stays in memory.
5. The domain creates the envelope. Infrastructure never creates envelopes.
6. Lineage is append-only. Steps cannot be removed, reordered, or modified.

License

MIT — see LICENSE.

DivineTreeDesigns — Sovereign Confidential