DivineTree.ICPVault.Storage 1.0.0

DivineTree.ICPVault.Storage

Connection Framework for ICPVault Storage Implementations

What Is This?

DivineTree.ICPVault.Storage is the connection framework for DivineTree.ICPVault storage implementations. It provides connection lifecycle, retry with exponential backoff, exception translation, and disposal so your implementation focuses on pure storage queries only.

Zero storage SDK. No Neo4j, Cosmos, or any other storage dependency ships in this NuGet.

Installation

dotnet add package DivineTree.ICPVault.Storage

Requires:

dotnet add package DivineTree.ICPVault

What Ships in This Package

Quick Start

Extend BaseVaultStorageAdapter<TAgenticContext> and implement three methods:

public sealed class Neo4jAIEnvelopeVault<TAgenticContext>
    : BaseVaultStorageAdapter<TAgenticContext>
    where TAgenticContext : class
{
    protected override async Task ExecutePersistAsync(
        AIVaultRecord<TAgenticContext> record, CancellationToken ct)
    {
        // Pure storage query only
        // Framework owns: guard clauses · connection · retry · exception translation
    }

    protected override async Task<IReadOnlyList<AIVaultRecord<TAgenticContext>>> ExecuteQueryAsync(
        AIVaultQuery query, CancellationToken ct) { ... }

    protected override async Task<int> ExecuteCountAsync(CancellationToken ct) { ... }
}

What the Framework Owns

Caller
  |
Guard clauses          — null record · empty lineage chain → ArgumentException
  |
EnsureConnectionAsync  — opens if closed · health check before every operation
  |
Retry                  — 3 attempts · exponential backoff · transient only
  |
ExecutePersistAsync    — YOUR CODE — pure storage query
  |
Exception translation  — raw exceptions → VaultStorageException
  |
Dispose                — connection manager lifecycle

Implementing a Connection Manager

Extend DefaultVaultConnectionManager and implement three methods:

public sealed class Neo4jConnectionManager : DefaultVaultConnectionManager
{
    public IDriver? Driver { get; private set; }

    protected override Task OpenConnectionAsync(CancellationToken ct)
    {
        Driver = GraphDatabase.Driver(_uri, AuthTokens.Basic(_username, _password));
        return Task.CompletedTask;
    }

    protected override async Task CloseConnectionAsync(CancellationToken ct)
    {
        if (Driver is not null) { await Driver.DisposeAsync(); Driver = null; }
    }

    protected override async Task<bool> CheckHealthAsync(CancellationToken ct)
    {
        if (Driver is null) return false;
        try { await Driver.VerifyConnectivityAsync(); return true; }
        catch { return false; }
    }
}

AuraDB URI Scheme Note

When using neo4j+s:// URI — do not call WithEncryptionLevel. The +s scheme implies TLS.

Design Principles

1. The framework owns plumbing. Your implementation owns queries.
2. Connection is opened lazily — on first operation, not on construction.
3. Health is checked before every operation.
4. Only transient failures are retried.
5. All exceptions are translated to VaultStorageException.
6. Disposal is deterministic — always await using.

License

MIT — see LICENSE.

DivineTreeDesigns — Sovereign Confidential