Cannery.Core 1.1.280

Cannery.Core

Authoritative, strongly-typed reference types and the Can registry for the Cannery Crucible AI fabric.

What is Cannery.Core?

Cannery.Core is the foundational .NET library for the Cannery Crucible — an AI fabric of tools that enable AI agents and human developers to create agents, apps, and workflows quickly, without the need for infrastructure or foundational software.

It provides three authoritative reference types for addressing any resource across the ecosystem, plus the Can registry that catalogs all available Cans (tools, agents, and capabilities) in the Crucible:

Curi — Cannery URI

Curi is a .NET value object representing a canonical address for any entity or resource in the Cannery/Crucible ecosystem (Curator, Codex, Conductor, Compliance, etc.). It enables stable, typed references with optional versioning and anchors for deterministic narratives and evidence.

• Strongly typed: Prevents stringly-typed errors and enables validation, normalization, and parsing.
• Portable: Designed for use across all domain, application, and infrastructure layers.
• Interoperable: Includes an EF Core value converter (CuriConverter) for string/NVARCHAR persistence.
• Grammar: scheme://type/canonicalKey[?v=][#fragment]

using Cannery.Core.Curi;

// Construct from string (canonicalKey is a system-generated UUIDv7-based key)
var curi = Curi.Parse("curator://catalog/CUR-Catalog-018e8e7e-7b2a-7e6b-bf7e-1a2b3c4d5e6f?v=1");

// Validate
if (!curi.Validate(out var error)) throw new Exception(error);

// Normalize (lowercases scheme and type)
var normalized = curi.Normalize();

// Build — canonical key is generated automatically; callers supply only the CanType
var built = Curi.Build(CanTypes.CuratorResource, version: 1);

// Use as string
string s = curi; // implicit
Console.WriteLine(curi); // ToString()

HttpUri

HttpUri is a strongly-typed value object for HTTP/HTTPS endpoint references. It wraps a validated URI and ensures only well-formed HTTP or HTTPS addresses are used as resource references across agents and workflows.

using Cannery.Core.HttpUri;

var endpoint = HttpUri.Parse("https://api.example.com/v1/agents");
Console.WriteLine(endpoint.Value);

AzureResourceId

AzureResourceId is a strongly-typed value object representing an authoritative reference to an Azure cloud resource (e.g., a storage account, service bus, App Service, or AI service). It parses and validates the standard Azure Resource Manager resource ID format.

using Cannery.Core.AzureResourceId;

var resourceId = AzureResourceId.Parse(
    "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/my-rg/providers/Microsoft.CognitiveServices/accounts/my-ai");

Console.WriteLine(resourceId.SubscriptionId);
Console.WriteLine(resourceId.ResourceGroup);
Console.WriteLine(resourceId.ResourceName);

Can Registry

The Can registry is the catalog of all Cans registered in the Cannery Crucible. A Can is a self-contained unit of capability — an agent, tool, or workflow module — that can be discovered and orchestrated by the Crucible without tight coupling between Cans.

using Cannery.Core.Registry;

// Look up a registered Can by its type
var canType = CanTypes.CuratorResource;
var entry = CanTypeRegistry.Get(canType);

Console.WriteLine(entry.FullId);   // Full identifier
Console.WriteLine(entry.ShortId);  // Short/display identifier

EF Core Persistence

Use the included value converter for Curi properties:

modelBuilder.Entity<MyEntity>()
    .Property(e => e.Curi)
    .HasConversion(new CuriConverter());

API Reference

Curi

• public readonly record struct Curi(string Value)
• bool Validate(out string error)
• Curi Normalize()
• static Curi Build(CanType canType, int? version = null, string? fragment = null)
• Implicit conversion to string, explicit from string

Curi Grammar

scheme://type/canonicalKey[?v=version][#fragment]

• scheme: e.g., curator, codex, conductor, crucible
• type: e.g., catalog, chronicle, playbook, chat-session
• canonicalKey: system-generated, opaque, UUIDv7-based identifier (e.g., CUR-Catalog-018e8e7e-7b2a-7e6b-bf7e-1a2b3c4d5e6f) — never supplied by callers
• version: optional integer via ?v= query parameter
• fragment: optional anchor (e.g., #section=ch1)

See docs/cannery/cannery-uri.md for the full CURI specification.

License

MIT

Contributing

Contributions, issues, and feature requests are welcome! Please see CONTRIBUTING.md.

Acknowledgements

• Cannery/Crucible ecosystem design team
• docs/cannery/cannery-uri.md for canonical CURI specification