using Aletheia.Sdk.Sample;
using Aletheia.Sdk.Aspects.DependencyInjection;
using Aletheia.Sdk.Capability.Messaging.DependencyInjection;
using Aletheia.Sdk.Web.DependencyInjection;
 
var builder =  WebApplication.CreateBuilder(args);
if (builder.Environment.IsDevelopment())
{
    LocalModelCredential.Apply(builder.Configuration, builder.Environment.ContentRootPath);
}
builder.Services.AddAspects();
 
var app = builder.Build();
 
app.Run();

using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Execution;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Inbound command: ask the library to greet a visitor by name.
/// </summary>
public sealed record GreetCommand(string Name);
 
/// <summary>
/// Our library's greeting — the first capability everyone encounters.
/// </summary>
public sealed record GreetResponse(string Message);
 
[Capability("sample.greet")]
public sealed class GreetHandler : ICapabilityHandler<GreetCommand, GreetResponse>
{
    public ValueTask<ExecutionResult<GreetResponse>> HandleAsync(
        GreetCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
        if (string.IsNullOrWhiteSpace(command.Name))
        {
            // Gracefully handle execution errors
            return ValueTask.FromResult<ExecutionResult<GreetResponse>>(
                new ExecutionResult<GreetResponse>.Fail(
                    new ExecutionError("EMPTY_NAME", "A name is required to enter the Library.")));
        }
 
        // Return successful execution result
        var message = $"Welcome to the Library, {command.Name}. I am the keeper of all manuscripts.";
        return ValueTask.FromResult<ExecutionResult<GreetResponse>>(
            new ExecutionResult<GreetResponse>.Ok(new GreetResponse(message)));
    }
}

using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Execution;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Inbound command: choose an error mode to trigger.
/// </summary>
public sealed record ErrorDemoCommand(string Mode);
 
/// <summary>
/// Response when no error is triggered — the normal path.
/// </summary>
public sealed record ErrorDemoResponse(string Message);
 
/// <summary>
/// Demonstrates that all domain errors return 422 — the code field distinguishes them.
/// Mode "empty-name" → EMPTY_NAME, "missing" → NOT_FOUND, "conflict" → CONFLICT.
/// Mode "success" → 200 (normal response, proving errors are the exception path).
/// </summary>
[Capability("sample.error-demo")]
public sealed class ErrorDemoHandler : ICapabilityHandler<ErrorDemoCommand, ErrorDemoResponse>
{
    public ValueTask<ExecutionResult<ErrorDemoResponse>> HandleAsync(
        ErrorDemoCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
        return command.Mode switch
        {
            "empty-name" => ValueTask.FromResult<ExecutionResult<ErrorDemoResponse>>(
                new ExecutionResult<ErrorDemoResponse>.Fail(
                    new ExecutionError("EMPTY_NAME", "A name is required to enter the Library."))),
 
            "missing" => ValueTask.FromResult<ExecutionResult<ErrorDemoResponse>>(
                new ExecutionResult<ErrorDemoResponse>.Fail(
                    new ExecutionError("NOT_FOUND", "The requested manuscript does not exist in the archives."))),
 
            "conflict" => ValueTask.FromResult<ExecutionResult<ErrorDemoResponse>>(
                new ExecutionResult<ErrorDemoResponse>.Fail(
                    new ExecutionError("CONFLICT", "Another scribe has already modified this manuscript."))),
 
            _ => ValueTask.FromResult<ExecutionResult<ErrorDemoResponse>>(
                new ExecutionResult<ErrorDemoResponse>.Ok(
                    new ErrorDemoResponse("No errors — the capability executed successfully."))),
        };
    }
}

using Aletheia.Sdk.Capability.Messaging.DependencyInjection;
using Aletheia.Sdk.Web.DependencyInjection;
 
using Aletheia.Sdk.Capability.DependencyInjection;
using Aletheia.Sdk.Capability.Http;
using Aletheia.Sdk.Capability.Http.DependencyInjection;
 
var builder =  WebApplication.CreateBuilder(args);
if (builder.Environment.IsDevelopment())
// ...
}
builder.Services.AddAspects();
 
builder.Services.AddCapabilityHandlersFromAssemblyContaining<GreetHandler>();
builder.Services.AddRuntimeInfo(options => options.ApplicationName = "Aletheia Sample");
builder.Services.AddBlobLifecycle();
builder.Services.AddSubscription();
builder.Services.AddCapabilityHttp();
 
var app = builder.Build();
 
app.MapCapabilities();
 
app.Run();

using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Operations;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Sample entity used to demonstrate the full Aletheia platform stack with
/// <strong>every supported scalar CLR type</strong> and its nullable variant:
/// <c>string</c>, <c>bool</c>, <c>int</c>, <c>long</c>, <c>float</c>,
/// <c>double</c>, <c>decimal</c>, <c>DateOnly</c>, <c>DateTimeOffset</c>,
/// <c>Guid</c>, <c>Uri</c> — non-nullable and nullable — plus a
/// <c>List&lt;string&gt;</c> collection to demonstrate list support.
/// <br/>
/// Uses <c>[OperationEndpoints]</c> + <c>MapOperations()</c> to expose five REST
/// endpoints under <c>api/entities/data-records</c> (POST, GET, PUT, DELETE).
/// </summary>
[Entity(Path = "data-records")]
[Identity(IdentityGenerator.Random)]
[OperationEndpoints]
public partial class DataRecord
{
    // ── Non-nullable scalars ─────────────────────────────────────────────────
 
    [Predicate("label")]
    public string Label { get; set; } = string.Empty;
 
    [Predicate("active")]
    public bool Active { get; set; }
 
    [Predicate("count")]
    public int Count { get; set; }
 
    [Predicate("serial")]
    public long Serial { get; set; }
 
    [Predicate("ratio")]
    public float Ratio { get; set; }
 
    [Predicate("score")]
    public double Score { get; set; }
 
    [Predicate("amount")]
    public decimal Amount { get; set; }
 
    [Predicate("effectiveDate")]
    public DateOnly EffectiveDate { get; set; }
 
    [Predicate("timestamp")]
    public DateTimeOffset Timestamp { get; set; }
 
    [Predicate("correlationId")]
    public Guid CorrelationId { get; set; }
 
    [Predicate("reference")]
    public Uri Reference { get; set; } = new Uri("https://aletheia.katharsis.digital/");
 
    // ── Nullable variants ────────────────────────────────────────────────────
 
    [Predicate("notes")]
    public string? Notes { get; set; }
 
    [Predicate("flagged")]
    public bool? Flagged { get; set; }
 
    [Predicate("limit")]
    public int? Limit { get; set; }
 
    [Predicate("sequence")]
    public long? Sequence { get; set; }
 
    [Predicate("factor")]
    public float? Factor { get; set; }
 
    [Predicate("precision")]
    public double? Precision { get; set; }
 
    [Predicate("fee")]
    public decimal? Fee { get; set; }
 
    [Predicate("expiresOn")]
    public DateOnly? ExpiresOn { get; set; }
 
    [Predicate("archivedAt")]
    public DateTimeOffset? ArchivedAt { get; set; }
 
    [Predicate("alternateId")]
    public Guid? AlternateId { get; set; }
 
    [Predicate("canonicalUri")]
    public Uri? CanonicalUri { get; set; }
}

using Aletheia.Sdk.Capability.Http;
using Aletheia.Sdk.Capability.Http.DependencyInjection;
 
using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Operations.Http;
using Aletheia.Sdk.Operations.Http.DependencyInjection;
using Aletheia.Sdk.Repository.DependencyInjection;
using Aletheia.Sdk.Repository.InMemory.DependencyInjection;
using Aletheia.Sdk.Repository.GraphDb.DependencyInjection;
 
var builder =  WebApplication.CreateBuilder(args);
if (builder.Environment.IsDevelopment())
// ...
builder.Services.AddSubscription();
builder.Services.AddCapabilityHttp();
 
if (builder.Configuration["Entity:BaseIri"] is { Length: > 0 } baseIri)
    EntityOptions.BaseIri = baseIri;
var repoBuilder = builder.Services.AddEntityRepository(builder.Configuration);
if (string.Equals(builder.Configuration["EntityRepository:Backend"], "GraphDb", StringComparison.OrdinalIgnoreCase))
    repoBuilder.UseGraphDb();
else
    repoBuilder.UseInMemory();
builder.Services.AddOperationEndpointsHttpFromAssemblyContaining<DataRecord>();
 
var app = builder.Build();
 
app.MapCapabilities();
 
app.MapOperations();
 
app.Run();

using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Entity.Contracts;
using Aletheia.Sdk.Operations;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// A Scribe — a person who writes Manuscripts.
/// Demonstrates EntityRefCollection: one Scribe writes many Manuscripts.
/// </summary>
[Entity(Path = "scribes")]
[Identity(IdentityGenerator.Random)]
[OperationEndpoints]
public partial class Scribe
{
    [Predicate("name")]
    public string Name { get; set; } = string.Empty;
 
    [Predicate("title")]
    public string Title { get; set; } = string.Empty;
 
    // An inverse relationship to the Scribe entity.
    // It automatically is populated with the Manuscripts that reference this Scribe in their Scribes collection.
    [Inverse(nameof(Manuscript.WrittenBy), "writtenBy")]
    public partial EntityRefCollection<Manuscript> Wrote { get; }
}

using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Entity.Contracts;
using Aletheia.Sdk.Operations;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// A Manuscript — the central entity of the Aletheia Study.
/// Represents a scroll entering the Great Library. Every new contributor
/// should start here to understand the Entity slice.
/// </summary>
[Entity(Path = "manuscripts")]
[Identity(IdentityGenerator.Random)]
[OperationEndpoints]
[Label("Manuscript")]
[Label("de", "Handschrift")]
[Description("A scroll entering the Great Library.")]
[Description("de", "Eine Schriftrolle, die in die Große Bibliothek eintritt.")]
public partial class Manuscript
{
    [Required]
    [Predicate("title")]
    [Label("Title")]
    [Label("de", "Titel")]
    [Description("The title of the manuscript.")]
    [Description("de", "Der Titel der Handschrift.")]
    public string Title { get; set; } = string.Empty;
 
    [Predicate("author")]
    [Label("Author")]
    [Label("de", "Autor")]
    [Description("The author of the manuscript.")]
    [Description("de", "Der Autor der Handschrift.")]
    public string Author { get; set; } = string.Empty;
 
    [Owning("genre")]
    public partial EntityRef<Genre>? Genre { get; set; }
 
    [Predicate("shelf")]
    [Label("Shelf")]
    [Label("de", "Regal")]
    [Description("The shelf where the manuscript rests.")]
    [Description("de", "Das Regal, in dem die Handschrift ruht.")]
    public string Shelf { get; set; } = string.Empty;
 
    [Predicate("year")]
    [Label("Year")]
    [Label("de", "Jahr")]
    [Description("The year the manuscript was written.")]
    [Description("de", "Das Jahr, in dem die Handschrift verfasst wurde.")]
    public int Year { get; set; }
 
    [Predicate("isSealed")]
    [Label("Sealed")]
    [Label("de", "Versiegelt")]
    [Description("Whether the manuscript is sealed against further edits.")]
    [Description("de", "Ob die Handschrift gegen weitere Änderungen versiegelt ist.")]
    public bool IsSealed { get; set; }
 
    // A relationship to the Scribe entity.
    // Due to the relation direction, a Manuscript cannot exist without a relationship to Scribes (someone has to write the manuscript).
    // However, a Scribe can exist without a relationship to Manuscripts (maybe they haven't written anything yet).
    [Owning("writtenBy")]
    public partial EntityRefCollection<Scribe> WrittenBy { get; }
}

using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Operations;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// A Genre — a fixed category of manuscripts. Demonstrates the [Enumeration] pattern:
/// sealed entity with public static readonly instances (SKOS-like named individuals).
/// The IRI is deterministic from the Key property via PropertyBasedPlain identity.
/// </summary>
[Entity(Path = "genres", PredicatePath = "genre")]
[Identity(IdentityGenerator.PropertyBasedPlain)]
[Enumeration]
[OperationEndpoints]
[Label("Genre")]
[Label("de", "Gattung")]
[Description("A fixed category of manuscripts.")]
[Description("de", "Eine feste Kategorie von Handschriften.")]
public partial class Genre
{
    [IdentityPart(0)]
    [Predicate("key")]
    [Label("Key")]
    [Label("de", "Schlüssel")]
    [Description("The stable URL-safe key forming the IRI suffix.")]
    [Description("de", "Der stabile, URL-sichere Schlüssel, der den IRI-Suffix bildet.")]
    public partial string Key { get; init; }
 
    [Predicate("displayName")]
    [Label("Display name")]
    [Label("de", "Anzeigename")]
    [Description("The human-readable name of the genre.")]
    [Description("de", "Der lesbare Name der Gattung.")]
    public string DisplayName { get; set; } = string.Empty;
 
    [Label("Philosophy")]
    [Label("de", "Philosophie")]
    [Description("Texts exploring fundamental questions of existence, knowledge, and ethics.")]
    [Description("de", "Texte, die grundlegende Fragen nach Sein, Wissen und Ethik erkunden.")]
    public static readonly Genre Philosophy = new() { Key = "philosophy", DisplayName = "Philosophy" };
 
    [Label("History")]
    [Label("de", "Geschichte")]
    [Description("Chronicles of past events and their interpretation.")]
    [Description("de", "Chroniken vergangener Ereignisse und ihre Deutung.")]
    public static readonly Genre History = new() { Key = "history", DisplayName = "History" };
 
    [Label("Poetry")]
    [Label("de", "Dichtung")]
    [Description("Verse and lyrical composition.")]
    [Description("de", "Verse und lyrische Komposition.")]
    public static readonly Genre Poetry = new() { Key = "poetry", DisplayName = "Poetry" };
 
    [Label("Science")]
    [Label("de", "Wissenschaft")]
    [Description("Systematic study of the natural world.")]
    [Description("de", "Systematische Erforschung der natürlichen Welt.")]
    public static readonly Genre Science = new() { Key = "science", DisplayName = "Science" };
 
    [Label("Magic")]
    [Label("de", "Magie")]
    [Description("Texts of arcane and occult knowledge.")]
    [Description("de", "Texte arkanen und okkulten Wissens.")]
    public static readonly Genre Magic = new() { Key = "magic", DisplayName = "Magic" };
 
    /// <summary>All five named genre individuals in declaration order.</summary>
    public static IReadOnlyList<Genre> All { get; } = [Philosophy, History, Poetry, Science, Magic];
 
}

using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Operations;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// A Catalog Entry — demonstrates PropertyBasedPlain identity: the IRI is built
/// from Author + Title, producing human-readable, collision-safe identifiers
/// like /catalog-entries/plato-the-republic.
/// </summary>
[Entity(Path = "catalog-entries", PredicatePath = "catalogEntry")]
[Identity(IdentityGenerator.PropertyBasedPlain)]
[OperationEndpoints]
public partial class CatalogEntry
{
    [IdentityPart(0)]
    [Predicate("author")]
    public partial string Author { get; init; }
 
    [IdentityPart(1)]
    [Predicate("title")]
    public partial string Title { get; init; }
}

using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Operations;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// A MagicalScribe — a Scribe who wields arcane power.
/// Inherits every property, endpoint, and the identity strategy from <see cref="Scribe"/>.
/// Adds only <c>Mana</c> — their reserve of magical energy.
/// </summary>
/// <remarks>
/// The derived type must not set <c>Path</c> or <c>[Identity]</c> on <c>[Entity]</c> —
/// the base type owns both. <c>[Entity(PredicatePath = "magical-scribe")]</c> scopes
/// the new predicate under the inherited path, and
/// <c>[OperationEndpoints("magical-scribes")]</c> gives it dedicated CRUD routes.
/// <br/>
/// Because a MagicalScribe <em>is</em> a Scribe at the RDF level (multi-type projection),
/// a <c>GET api/entities/scribes</c> list also returns magical-scribe instances.
/// </remarks>
[Entity(PredicatePath = "magical-scribe")]
[OperationEndpoints("magical-scribes")]
public partial class MagicalScribe : Scribe
{
    /// <summary>Reserve of magical energy — the one thing that sets them apart.</summary>
    [Predicate("mana")]
    public int Mana { get; set; }
}

using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Operations;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// A DeterministicRecord — same scalar shape as DataRecord, but uses
/// <see cref="IdentityGenerator.PropertyBasedEncoded"/> for deterministic GUIDv5 IRIs.
/// The IRI is a hash of the <c>Key</c> property under a namespace GUID,
/// so the same key always produces the same IRI — but the IRI reveals nothing
/// about the key value.
/// <br/>
/// Compare with <see cref="DataRecord"/> (Random UUIDv4) and
/// <see cref="Genre"/> (PropertyBasedPlain, human-readable IRI).
/// Together they demonstrate all three identity strategies.
/// </summary>
[Entity(Path = "deterministic-records")]
[Identity(IdentityGenerator.PropertyBasedEncoded)]
[OperationEndpoints]
public partial class DeterministicRecord
{
    /// <summary>
    /// The identity part — hashed into the GUIDv5 IRI.
    /// Same key → same IRI every time. Different key → different IRI.
    /// </summary>
    [IdentityPart(0)]
    [Predicate("key")]
    public partial string Key { get; init; }
 
    [Predicate("label")]
    public string Label { get; set; } = string.Empty;
 
    [Predicate("count")]
    public int Count { get; set; }
 
    [Predicate("active")]
    public bool Active { get; set; }
}

using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Entity.Contracts;
using Aletheia.Sdk.Operations;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// A Wing — a section of the Library, curated by a Scribe.
/// Demonstrates laziness of EntityRef (N:1 relation) — each Wing has one Curator.
/// </summary>
[Entity(Path = "wings")]
[Identity(IdentityGenerator.Random)]
[OperationEndpoints]
public partial class Wing
{
    [Predicate("name")]
    public string Name { get; set; } = string.Empty;
 
    [Predicate("floor")]
    public int Floor { get; set; }
 
    [Owning("curator")]
    public partial EntityRef<Scribe>? Curator { get; set; }
 
    [Owning("manuscripts")]
    public partial EntityRefCollection<Manuscript> Manuscripts { get; }
}

using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Execution;
using Aletheia.Sdk.Repository.Contracts;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Ask Aletheia for the details of a Wing — she walks the relationships.
/// </summary>
public sealed record WingDetailCommand(string WingIri);
 
/// <summary>
/// The Wing's details, including its Curator's name and manuscript count.
/// </summary>
public sealed record WingDetailResponse(string WingName, string? CuratorName, int ManuscriptCount);
 
[Capability("sample.wing-detail")]
public sealed class WingDetailHandler : ICapabilityHandler<WingDetailCommand, WingDetailResponse>
{
    private readonly IEntityStore _store;
 
    public WingDetailHandler(IEntityStore store) => _store = store;
 
    public async ValueTask<ExecutionResult<WingDetailResponse>> HandleAsync(
        WingDetailCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
        var wing = await _store.LoadAsync<Wing>(command.WingIri, cancellationToken);
        if (wing is null)
        {
            return new ExecutionResult<WingDetailResponse>.Fail(
                new ExecutionError("WING_NOT_FOUND", $"No Wing found at '{command.WingIri}'."));
        }
 
        using var session = EntitySession.Begin(_store);
 
        // Lazy-resolve the Curator via EntityRef<T>.GetAwaiter()
        var curator = wing.Curator is not null ? await wing.Curator : null;
 
        return new ExecutionResult<WingDetailResponse>.Ok(new WingDetailResponse(
            wing.Name,
            curator?.Name,
            wing.Manuscripts is not null ? wing.Manuscripts.Iris.Count : 0));
    }
}

using System.Collections.Immutable;
using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Execution;
using Aletheia.Sdk.Operations.Linq;
using Aletheia.Sdk.Repository.Contracts;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Search the Library's manuscripts by keyword.
/// </summary>
public sealed record CatalogCommand(string Keyword);
 
/// <summary>
/// A single manuscript match from the catalog search.
/// </summary>
public sealed record CatalogMatch(string Title, string Author, string Iri);
 
/// <summary>
/// Results of a catalog search.
/// </summary>
public sealed record CatalogResponse(IReadOnlyList<CatalogMatch> Matches);
 
[Capability("sample.catalog")]
public sealed class CatalogHandler : ICapabilityHandler<CatalogCommand, CatalogResponse>
{
    private readonly IEntityStore _store;
 
    public CatalogHandler(IEntityStore store) => _store = store;
 
    public async ValueTask<ExecutionResult<CatalogResponse>> HandleAsync(
        CatalogCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
        // Using Sdk.Operations.Linq to query the entity store for manuscripts that match the keyword in their title.
        var matches = _store
            .Query<Manuscript>()
            .Where(m => m.Title != null && m.Title.Contains(command.Keyword))
            .ToList();
 
        return new ExecutionResult<CatalogResponse>.Ok(new CatalogResponse(
            matches
                .Select(m => new CatalogMatch(m.Title!, m.Author!, m.Iri))
                .ToImmutableList()
        ));
    }
}

using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Entity.Contracts;
using Aletheia.Sdk.Operations;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// A Seal — a frozen record of the Library. Also demonstrates ObjectBearing:
/// each Seal can store a binary object of the sealed scroll.
/// </summary>
[Entity(Path = "seals")]
[Identity(IdentityGenerator.Random)]
[OperationEndpoints]
[ObjectBearing("seal-scrolls")]
public partial class Seal
{
    [Predicate("name")]
    public string Name { get; set; } = string.Empty;
 
    [Predicate("description")]
    public string Description { get; set; } = string.Empty;
 
    [Owning("sealedManuscripts")]
    public partial EntityRefCollection<Manuscript> SealedManuscripts { get; }
}

using Aletheia.Sdk.Repository.InMemory.DependencyInjection;
using Aletheia.Sdk.Repository.GraphDb.DependencyInjection;
 
using Aletheia.Sdk.ObjectStorage.Http;
using Aletheia.Sdk.ObjectStorage.Http.DependencyInjection;
using Aletheia.Sdk.ObjectStorage.InMemory.DependencyInjection;
using Aletheia.Sdk.ObjectStorage.S3.DependencyInjection;
 
var builder =  WebApplication.CreateBuilder(args);
if (builder.Environment.IsDevelopment())
// ...
    repoBuilder.UseInMemory();
builder.Services.AddOperationEndpointsHttpFromAssemblyContaining<DataRecord>();
 
builder.Services.AddObjectBearingEntity();
if (string.Equals(builder.Configuration["ObjectStorage:Backend"], "S3", StringComparison.OrdinalIgnoreCase))
    builder.Services.AddS3ObjectStorage(builder.Configuration);
else
    builder.Services.AddInMemoryObjectStorage();
builder.Services.AddObjectStorageHttpFromAssemblyContaining<Manuscript>();
 
var app = builder.Build();
 
// ...
 
app.MapOperations();
 
app.MapObjectOperations();
 
app.Run();

using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Execution;
using Aletheia.Sdk.Operations;
using Aletheia.Sdk.Repository.Transaction;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Register a Manuscript together with its Scribe in one atomic transaction.
/// If the transaction fails — or if errorScenario is "rollback" — neither enters the Library.
/// </summary>
public sealed record RegisterManuscriptCommand(string Title, string Author, string ScribeName, string? ErrorScenario = null);
 
/// <summary>
/// The result of registering a Manuscript — both the scroll and its creator.
/// </summary>
public sealed record RegisterManuscriptResponse(string ManuscriptIri, string ScribeIri, string ScribeName, bool Committed);
 
[Capability("sample.register-manuscript")]
public sealed class RegisterManuscriptHandler : ICapabilityHandler<RegisterManuscriptCommand, RegisterManuscriptResponse>
{
    private readonly ITransactionalEntityStore _store;
 
    public RegisterManuscriptHandler(ITransactionalEntityStore store) => _store = store;
 
    public async ValueTask<ExecutionResult<RegisterManuscriptResponse>> HandleAsync(
        RegisterManuscriptCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
        if (string.IsNullOrWhiteSpace(command.Title))
            return new ExecutionResult<RegisterManuscriptResponse>.Fail(
                new ExecutionError("EMPTY_TITLE", "A scroll must have a title."));
 
        if (string.IsNullOrWhiteSpace(command.ScribeName))
            return new ExecutionResult<RegisterManuscriptResponse>.Fail(
                new ExecutionError("EMPTY_SCRIBE", "A Scribe must have a name."));
 
        using var _ = EntityOperations.Use(_store);
 
        var scribe = new Scribe { Name = command.ScribeName, Title = "Registered Scribe" };
        var manuscript = new Manuscript { Title = command.Title, Author = command.Author };
 
        await using var tx = EntityOperations.BeginTransaction();
        tx.Create(scribe);
        tx.Create(manuscript);
        // Force IRI generation before linking (access triggers MaterializeIdentity)
        var manuscriptIri = manuscript.Iri;
        await scribe.Wrote.AddAsync(manuscript, cancellationToken);
        tx.Update(scribe);
 
        if (string.Equals(command.ErrorScenario, "rollback", StringComparison.OrdinalIgnoreCase))
        {
            // Deliberately abandon the transaction — no CommitAsync called.
            // The await using disposes without committing; both entities are lost.
            return new ExecutionResult<RegisterManuscriptResponse>.Fail(
                new ExecutionError("TX_ROLLBACK",
                    "Transaction rolled back deliberately. Neither scroll nor Scribe entered the Library."));
        }
 
        await tx.CommitAsync(cancellationToken);
 
        return new ExecutionResult<RegisterManuscriptResponse>.Ok(
            new RegisterManuscriptResponse(manuscript.Iri, scribe.Iri, scribe.Name, true));
    }
}

using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Execution;
using Aletheia.Sdk.Operations;
using Aletheia.Sdk.Repository.Transaction;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Register the same catalog entry twice to make a deliberate fail of the transaction.
/// </summary>
public sealed record DuplicateCatalogEntryCommand();
 
/// <summary>
/// The result of creating duplicate catalog entries. Should never be returned.
/// </summary>
public sealed record DuplicateCatalogEntryResponse();
 
[Capability("sample.duplicate-catalog-entry")]
public sealed class DuplicateCatalogEntryHandler : ICapabilityHandler<DuplicateCatalogEntryCommand, DuplicateCatalogEntryResponse>
{
    private readonly ITransactionalEntityStore _store;
 
    public DuplicateCatalogEntryHandler(ITransactionalEntityStore store) => _store = store;
 
    public async ValueTask<ExecutionResult<DuplicateCatalogEntryResponse>> HandleAsync(
        DuplicateCatalogEntryCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
 
        using var _ = EntityOperations.Use(_store);
 
        var catalogEntry1 = new CatalogEntry { Author = "Plato", Title = "The Republic" };
        var catalogEntry2 = new CatalogEntry { Author = "Plato", Title = "The Republic" };
 
        await using var tx = EntityOperations.BeginTransaction();
        tx.Create(catalogEntry1);
        tx.Create(catalogEntry2); // This will cause a duplicate identity error when committing the transaction.
        await tx.CommitAsync(cancellationToken);
 
        return new ExecutionResult<DuplicateCatalogEntryResponse>.Ok(
            new DuplicateCatalogEntryResponse()
        );
    }
}

using Aletheia.Sdk.Aspects;
using Aletheia.Sdk.Aspects.Abstractions;
using Aletheia.Sdk.Aspects.Abstractions.Contracts;
using Aletheia.Sdk.Aspects.Message;
 
public static class CapabilityAspects
{
    // A message aspect that validates catalog search keywords.
    // The aspect uses SHACL (Shapes Constraint Language) to define the validation rules.
    // The aspect is identified by the IRI "urn:aletheia:aspects:catalog-keyword-v1" and is associated with the CatalogCommand entity type.
    // The validation rules specify that a catalog search keyword must be at least 3 characters long.
    // The message-property IRI has no entity vocabulary constant — kept as a full IRI literal.
    [AspectDefinition("urn:aletheia:aspects:catalog-keyword-v1", AspectDefinitionFamily.Message)]
    public static readonly IMessageAspect CatalogKeywordV1 = new InlineTtlMessageAspect("urn:aletheia:aspects:catalog-keyword-v1", Ttl.WithPrefixes($$"""
        <urn:aletheia:aspects:catalog-keyword-shape>
            a sh:NodeShape ;
            sh:targetClass <urn:Aletheia.Sdk.Sample.CatalogCommand> ;
            sh:property [
                sh:path <https://aletheia.katharsis.digital/Keyword> ;
                sh:name "Keyword"@en ;
                sh:minLength 3 ;
                sh:message "A catalog search keyword must be at least 3 characters." ;
            ] .
        """));
 
    [AspectDefinition("urn:aletheia:aspects:capability:catalog-v1", AspectDefinitionFamily.Capability)]
    public static readonly CapabilityAspect CatalogV1 = new()
    {
        Iri = "urn:aletheia:aspects:capability:catalog-v1",
        CommandAspectIri = "urn:aletheia:aspects:catalog-keyword-v1"
    };
 
    [AspectDefinition("urn:aletheia:aspects:catalog-keyword-v2", AspectDefinitionFamily.Message)]
    public static readonly IMessageAspect CatalogKeywordV2 = new InlineTtlMessageAspect("urn:aletheia:aspects:catalog-keyword-v2", Ttl.WithPrefixes($$"""
        <urn:aletheia:aspects:catalog-keyword-shape>
            a sh:NodeShape ;
            sh:targetClass <urn:Aletheia.Sdk.Sample.CatalogCommand> ;
            sh:property [
                sh:path <https://aletheia.katharsis.digital/Keyword> ;
                sh:name "Keyword"@en ;
                sh:minLength 3 ;
                sh:message "A catalog search keyword must be at least 3 characters." ;
            ] .
        """));
 
    [AspectDefinition("urn:aletheia:aspects:capability:catalog-v2", AspectDefinitionFamily.Capability)]
    public static readonly CapabilityAspect CatalogV2 = new()
    {
        Iri = "urn:aletheia:aspects:capability:catalog-v2",
        CommandAspectIri = "urn:aletheia:aspects:catalog-keyword-v2"
    };
}

using Aletheia.Sdk.Aspects;
using Aletheia.Sdk.Aspects.Abstractions;
using Aletheia.Sdk.Aspects.Abstractions.Contracts;
using Aletheia.Sdk.Aspects.Operation;
using Aletheia.Sdk.Entity;
 
public static class OperationAspects
{
    // An operation aspect that validates manuscripts before they are written to the repository.
    // The aspect uses SHACL (Shapes Constraint Language) to define the validation rules.
    // The aspect is identified by the IRI "urn:aletheia:aspects:manuscript-write-v1" and is associated with the Manuscript entity type.
    // The shape mentions exactly the properties the operation governs: the title carries the
    // non-empty constraint, and every other path listed is the set the write saves — properties
    // NOT mentioned are neither saved nor edited. Operation aspects propose no sh:name at all:
    // the fields they constrain speak the entity's own vocabulary.
    [AspectDefinition("urn:aletheia:aspects:manuscript-write-v1", AspectDefinitionFamily.Operation)]
    public static readonly IOperationAspect ManuscriptWriteV1 = new InlineTtlOperationAspect("urn:aletheia:aspects:manuscript-write-v1", Ttl.WithPrefixes($$"""
        <urn:aletheia:aspects:manuscript-shape>
            a sh:NodeShape ;
            sh:targetClass <{{Vocabulary.Manuscript.Type}}> ;
            sh:property [
                sh:path <{{Vocabulary.Manuscript.Title}}> ;
                sh:minCount 1 ; sh:minLength 1 ;
                sh:message "A manuscript must have a non-empty title." ;
            ] ;
            sh:property [ sh:path <{{Vocabulary.Manuscript.Author}}> ] ;
            sh:property [ sh:path <{{Vocabulary.Manuscript.Genre}}> ] ;
            sh:property [ sh:path <{{Vocabulary.Manuscript.Shelf}}> ] ;
            sh:property [ sh:path <{{Vocabulary.Manuscript.Year}}> ] ;
            sh:property [ sh:path <{{Vocabulary.Manuscript.IsSealed}}> ] .
        """), null);
}

using Aletheia.Sdk.Aspects;
using Aletheia.Sdk.Aspects.Abstractions;
using Aletheia.Sdk.Aspects.Abstractions.Contracts;
using Aletheia.Sdk.Aspects.Query;
using Aletheia.Sdk.Entity;
 
public static class QueryAspects
{
    // Query aspect 1 — enrichment: derive a reasoned access status from the stored
    // seal flag and merge it into reads as an ordinary JSON field (`accessStatus`).
    // The result shape declares exactly the properties the aspect returns: the reasoned
    // `accessStatus` and the stored `isSealed` flag the reader needs alongside it. Properties
    // the shape does not mention are not returned. The CONSTRUCT is the "construction set" — a
    // SPARQL query that computes the implicit-knowledge fact. On GraphDB the same construct runs
    // with ?infer=true, so an OWL ruleset can contribute further inferred triples; the InMemory
    // backend evaluates it structurally.
    // `accessStatus` is a derived predicate with no entity property — kept as a full predicate IRI.
    // Its reasoned values are declared vocabulary, not magic strings: the shape lists them via
    // sh:in and names each (sh:name/sh:description), so the localization dictionary publishes
    // `aspects.manuscript-access-v1.values.accessStatus.restricted|public` and a reader resolves
    // the IRI a read returns through the same chain as every other label.
    [AspectDefinition("urn:aletheia:aspects:manuscript-access-v1", AspectDefinitionFamily.Query)]
    public static readonly IQueryAspect ManuscriptAccessV1 = new InlineTtlQueryAspect(
        "urn:aletheia:aspects:manuscript-access-v1",
        filterWhere: null,
        resultShapeTtl: Ttl.WithPrefixes($$"""
            <urn:aletheia:aspects:manuscript-access-shape>
                a sh:NodeShape ;
                sh:targetClass <{{Vocabulary.Manuscript.Type}}> ;
                sh:property [
                    sh:path <https://aletheia.katharsis.digital/predicates/manuscripts/accessStatus> ;
                    sh:name "Access status"@en ;
                    sh:in ( <urn:aletheia:aspects:manuscript-access:restricted> <urn:aletheia:aspects:manuscript-access:public> ) ;
                ] ;
                sh:property [ sh:path <{{Vocabulary.Manuscript.IsSealed}}> ] .
 
            <urn:aletheia:aspects:manuscript-access:restricted> sh:name "Restricted"@en, "Eingeschränkt"@de .
            <urn:aletheia:aspects:manuscript-access:public> sh:name "Public"@en, "Öffentlich"@de .
            """),
        enrichmentConstruct: $$"""
            CONSTRUCT { ?entityIri <https://aletheia.katharsis.digital/predicates/manuscripts/accessStatus> ?status }
            WHERE {
              ?entityIri <{{Vocabulary.Manuscript.IsSealed}}> ?sealed .
              BIND(IF(?sealed, <urn:aletheia:aspects:manuscript-access:restricted>, <urn:aletheia:aspects:manuscript-access:public>) AS ?status)
            }
            """);
 
    // Query aspect 2 — request-parameterized filter + access gate in one aspect
    // (Aspects ADR-0010): list the manuscripts of one genre and hide sealed ones in
    // the same pass. The client sends `?genre=<genre-iri>` alongside the
    // `X-Aletheia-Query-AspectIri` header; the engine resolves the
    // `##aspect:param:genre##` placeholder (percent-encoding the value before
    // interpolation) and applies the WHOLE filter to the LIST type-scan — so a
    // crafted value can neither inject SPARQL nor break out of the IRI literal, and
    // the sealed gate is enforced for free on the same filter.
    // The subject variable MUST be ?entityIri — the engine binds it to each read
    // subject (mapped to ?s on the collection type-scan), so a filter using any other
    // variable would silently match nothing.
    [AspectDefinition("urn:aletheia:aspects:manuscript-by-genre-v1", AspectDefinitionFamily.Query)]
    public static readonly IQueryAspect ManuscriptByGenreV1 = new InlineTtlQueryAspect(
        "urn:aletheia:aspects:manuscript-by-genre-v1",
        $$"""
            ?entityIri <{{Vocabulary.Manuscript.Genre}}> <##aspect:param:genre##> .
            ?entityIri <{{Vocabulary.Manuscript.IsSealed}}> ?sealed .
            FILTER(?sealed = false)
        """,
        // The result shape declares the properties the aspect returns: title and the seal
        // flag the filter reasons about. Structural properties carry no sh:name — only the
        // reasoned properties of a query aspect are named.
        resultShapeTtl: Ttl.WithPrefixes($$"""
            <urn:aletheia:aspects:manuscript-by-genre-shape>
                a sh:NodeShape ;
                sh:targetClass <{{Vocabulary.Manuscript.Type}}> ;
                sh:property [ sh:path <{{Vocabulary.Manuscript.Title}}> ] ;
                sh:property [ sh:path <{{Vocabulary.Manuscript.IsSealed}}> ] .
            """));
 
    // Query aspect 3 — the platform's SECOND infused variable: `?agentIri`.
    // A read that only a VERIFIED AGENT may make. The engine binds `?agentIri` to the acting
    // agent — the `Agent` record behind the caller's token — wherever an aspect's SPARQL names
    // it, exactly as it binds `?entityIri` to the entity being read. The BOUND guard is what
    // refuses everyone else, and it is load-bearing rather than decoration: this SPARQL engine
    // compares SOFTLY against an unbound variable (`?agentIri = <…>` would PASS), so an
    // anonymous caller slips through a bare comparison. Naming ONE agent is the same gate with
    // the comparison added beside the guard:
    //   FILTER(BOUND(?agentIri) && ?agentIri = <https://…/authorization-agents/<uuid>>)
    // An Agent's IRI is a v5 UUID of its token (see Aletheia.Sdk.Authorization.Entity), which
    // is why the sample names the guard rather than one agent: a lesson should be readable.
    // The gate opens with a triple pattern whose subject is `?entityIri` because the platform's
    // analyzer requires that convention (ALETHEIA_1005) — the pattern is also the projection the
    // result shape returns.
    [AspectDefinition("urn:aletheia:aspects:manuscripts-for-agents-v1", AspectDefinitionFamily.Query)]
    public static readonly IQueryAspect ManuscriptsForAgentsV1 = new InlineTtlQueryAspect(
        "urn:aletheia:aspects:manuscripts-for-agents-v1",
        $$"""
            ?entityIri <{{Vocabulary.Manuscript.Title}}> ?title .
            FILTER(BOUND(?agentIri))
        """,
        resultShapeTtl: Ttl.WithPrefixes($$"""
            <urn:aletheia:aspects:manuscripts-for-agents-shape>
                a sh:NodeShape ;
                sh:targetClass <{{Vocabulary.Manuscript.Type}}> ;
                sh:property [ sh:path <{{Vocabulary.Manuscript.Title}}> ] .
            """));
}

using Aletheia.Sdk.Aspects;
using Aletheia.Sdk.Aspects.Abstractions;
using Aletheia.Sdk.Aspects.Abstractions.Contracts;
using Aletheia.Sdk.Aspects.Operation;
using Aletheia.Sdk.Entity;
 
/// <summary>
/// Object-level aspects — guards for [ObjectBearing] upload routes.
/// These apply to the object storage pipeline, not entity properties.
/// </summary>
public static class ObjectAspects
{
    // An object-lock aspect that prevents re-uploading a Seal's scroll.
    // Once the Seal entity has an objectKey (a blob has been uploaded), the aspect
    // blocks further uploads. Delete the blob first to unlock.
    // The SHACL Local shape binds the aspect to the Seal entity type via
    // sh:targetClass and declares WHICH members it governs — Name and Description,
    // the two the reader sees. It constrains neither of them, so it never rejects:
    // a shape names what an aspect is about, and constrains only what it enforces.
    // The lock itself is the SPARQL context gate below: a graph pattern check on the
    // upload route, keyed on the objectKey the shape deliberately does NOT name.
    [AspectDefinition("urn:aletheia:aspects:operation:seal-lock-v1", AspectDefinitionFamily.Operation)]
    public static readonly IOperationAspect SealLockV1 = new InlineTtlOperationAspect("urn:aletheia:aspects:operation:seal-lock-v1", Ttl.WithPrefixes($$"""
        <urn:aletheia:aspects:seal-lock-shape>
            a sh:NodeShape ;
            sh:targetClass <{{Vocabulary.Seal.Type}}> ;
            sh:property [ sh:path <{{Vocabulary.Seal.Name}}> ] ;
            sh:property [ sh:path <{{Vocabulary.Seal.Description}}> ] .
        """), $$"""
        ?entityIri <{{Vocabulary.Seal.ObjectKey}}> ?existingKey .
        BIND(?entityIri AS ?focusNode)
        BIND("This seal already bears a scroll. Delete the object before re-uploading." AS ?message)
        """);
}

using Aletheia.Sdk.Aspects;
using Aletheia.Sdk.Aspects.Abstractions;
using Aletheia.Sdk.Aspects.Abstractions.Contracts;
using Aletheia.Sdk.Aspects.View;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// The frontend-purpose view aspects of the tutorial — the Manuscript
/// form shape the browser validates against before submitting.
/// <br/><br/>
/// Views are feedback, never enforcement: the capability pipeline never checks
/// them. The exploration endpoints serve their Turtle source, and the view
/// aspect engine validates JSON form values on demand
/// (<c>POST api/entities/aletheia/aspects/{iri}/validate</c>), reporting
/// findings of every severity mapped to JSON paths.
/// <br/><br/>
/// Every <c>sh:path</c> is a predicate in the canonical JSON namespace
/// (<see cref="Aletheia.Sdk.Aspects.Abstractions.Aspect.JsonNamespace"/>) — its
/// local name is the JSON key.
/// <br/><br/>
/// The shape declares no <c>sh:targetClass</c>. A view is about a FORM: its
/// subject is the form itself, not an instance of an entity, so no class of the
/// domain is a meaningful context. The view engine types the validated JSON root
/// node with the shape's own IRI in that case — the constraints fire against the
/// payload's root either way. A view MAY name a target class; it is never required.
/// <br/><br/>
/// The form also says what it may be USED WITH. A view names the aspects it is
/// valid with — <see cref="Aletheia.Sdk.Aspects.Abstractions.Aspect.OperationAspectPredicate"/>
/// for the writes it feeds, <see cref="Aletheia.Sdk.Aspects.Abstractions.Aspect.QueryAspectPredicate"/>
/// for the reads that serve it. Each is a LIST and an allowed set, never the
/// choice itself: a request still names exactly one aspect in its header
/// (<c>X-Aletheia-Operation-AspectIri</c> / <c>X-Aletheia-Query-AspectIri</c>), and
/// the frontend reads the declaration to check that a screen which binds this
/// form uses an aspect the form actually declares. A form that outgrows one
/// aspect names another rather than losing the link; a view that names nothing
/// is simply unbound — declaring is opt-in, never an obligation.
/// </summary>
public static class ViewAspects
{
    // The Manuscript form shape — the three members a catalogue record of a manuscript really needs:
    // a TITLE (a string), a GENRE (a reference to a published enumeration) and a YEAR (an integer).
    // The three JSON shapes a form value can have are all here, and the genre is a closed list: a
    // model that fills this form must look the list up, with the names the platform publishes for
    // it, rather than invent a value. A genre outside the published list is a WARNING — worth
    // saying, not worth refusing.
    //
    // The bindings are read as: this form is WRITTEN through the manuscript operation aspect (whose
    // shape names exactly the fields the write saves, this form's title and genre among them), and
    // it is READ through two queries — the list filtered by the very genre this form captures, and
    // the agent-gated read that returns this form's title. A binding is a claim about reuse, and the
    // frontend's conformance test is what keeps a screen honest about it.
    [AspectDefinition("urn:aletheia:views:manuscript-form", AspectDefinitionFamily.View)]
    public static readonly IViewAspect ManuscriptForm = new InlineTtlViewAspect("urn:aletheia:views:manuscript-form", Ttl.WithPrefixes($$"""
        <urn:aletheia:views:manuscript-form>
            a sh:NodeShape ;
            <{{Aspect.OperationAspectPredicate}}> <urn:aletheia:aspects:manuscript-write-v1> ;
            <{{Aspect.QueryAspectPredicate}}> <urn:aletheia:aspects:manuscript-by-genre-v1> ;
            <{{Aspect.QueryAspectPredicate}}> <urn:aletheia:aspects:manuscripts-for-agents-v1> ;
            sh:property [
                sh:path <{{Aspect.JsonNamespace}}title> ; sh:name "Title"@en, "Titel"@de ;
                sh:minCount 1 ; sh:minLength 5 ;
                sh:datatype xsd:string ;
                sh:message "view.manuscript.title" ;
            ] ;
            sh:property [
                sh:path <{{Aspect.JsonNamespace}}genre> ; sh:name "Genre"@en, "Gattung"@de ;
                sh:minCount 1 ; sh:nodeKind sh:IRI ;
                sh:message "view.manuscript.genre" ;
            ] ;
            sh:property [
                sh:path <{{Aspect.JsonNamespace}}genre> ; sh:name "Genre"@en, "Gattung"@de ;
                sh:in ( {{PublishedGenres()}} ) ;
                sh:severity sh:Warning ;
                sh:message "view.manuscript.genre.unpublished" ;
            ] ;
            sh:property [
                sh:path <{{Aspect.JsonNamespace}}year> ; sh:name "Year"@en, "Jahr"@de ;
                sh:minCount 1 ; sh:datatype xsd:integer ; sh:minInclusive 1000 ;
                sh:message "view.manuscript.year" ;
            ] .
        """));
 
    /// <summary>
    /// The published genres, as IRIs for the shape's <c>sh:in</c> list.
    /// <br/><br/>
    /// The list is read from the enumeration ITSELF — the instances' own IRIs — so adding a genre to
    /// <see cref="Genre"/> cannot leave the shape warning about a value the platform publishes. Each
    /// instance materializes its identity in Genre's static constructor, which reading a static field
    /// triggers.
    /// </summary>
    private static string PublishedGenres() => string.Join(
        " ",
        typeof(Genre)
            .GetFields(System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Static)
            .Where(field => field.FieldType == typeof(Genre))
            .Select(field => field.GetValue(null) as Genre)
            .Where(genre => genre is not null)
            .Select(genre => $"<{genre!.Iri}>")
            .OrderBy(iri => iri, StringComparer.Ordinal));
}

using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Execution;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Returns all evnets for a given entity IRI, or all events if no IRI is provided.
/// </summary>
/// <param name="Iri">Iri of the entity to retrieve events for. If null, all events are returned.</param>
public sealed record EntityEventLogCommand(string? Iri);
 
/// <summary>
/// Response carries the events
/// </summary>
public sealed record EntityEventLogResponse(IReadOnlyList<EntityEventLogEntry> Events);
 
[Capability("sample.entity-event-log")]
public sealed class EntityEventLogHandler : ICapabilityHandler<EntityEventLogCommand, EntityEventLogResponse>
{
    private readonly EntityEventLog _log;
 
    public EntityEventLogHandler(EntityEventLog log)
    {
        _log = log;
    }
 
    public async ValueTask<ExecutionResult<EntityEventLogResponse>> HandleAsync(
        EntityEventLogCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
        if (command.Iri is null)
            return new ExecutionResult<EntityEventLogResponse>.Ok(
                new EntityEventLogResponse(_log.GetAll()));
 
        return new ExecutionResult<EntityEventLogResponse>.Ok(
            new EntityEventLogResponse(_log.GetByIri(command.Iri)));
    }
}

namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Entry in the in-process entity event log used by the event demo.
/// </summary>
public sealed record EntityEventLogEntry(
    string EntityIri,
    string TypeName,
    string Operation,
    string BranchIri,
    string Topic,
    DateTimeOffset TimestampUtc);
 
/// <summary>
/// Thread-safe in-process log of entity change events.
/// Exposed via GET /api/diagnostics/entity-events.
/// </summary>
public sealed class EntityEventLog
{
    private readonly List<EntityEventLogEntry> _entries = [];
    private readonly object _lock = new();
 
    public void Add(EntityEventLogEntry entry)
    {
        lock (_lock) _entries.Add(entry);
    }
 
    public IReadOnlyList<EntityEventLogEntry> GetAll()
    {
        lock (_lock) return [.. _entries];
    }
 
    public IReadOnlyList<EntityEventLogEntry> GetByIri(string iri)
    {
        lock (_lock) return [.. _entries.Where(e => e.EntityIri == iri)];
    }
}

using Aletheia.Sdk.Entity.Messaging;
using Aletheia.Sdk.Messaging;
using Microsoft.Extensions.Hosting;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Background service that listens for Manuscript changes and logs them.
/// Part of Chapter 09: Events — every new Manuscript rings through the Library.
/// </summary>
internal sealed class ManuscriptSubscription (
    IMessageConsumer<string, EntityChangedEnvelope<Manuscript>> consumer,
    EntityEventLog log) : BackgroundService
{
    internal const string Topic = "aletheia.entities.manuscript.history";
 
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var envelope in consumer.ConsumeAsync(Topic, stoppingToken).ConfigureAwait(false))
        {
            log.Add(new EntityEventLogEntry(
                EntityIri: envelope.Payload.Iri.ToString(),
                TypeName: envelope.Payload.TypeName,
                Operation: envelope.Payload.Operation.ToString(),
                BranchIri: envelope.Payload.BranchIri,
                Topic: Topic,
                TimestampUtc: envelope.TimestampUtc));
        }
    }
}

using Aletheia.Sdk.ObjectStorage.InMemory.DependencyInjection;
using Aletheia.Sdk.ObjectStorage.S3.DependencyInjection;
 
using Aletheia.Sdk.Entity.Messaging.DependencyInjection;
using Aletheia.Sdk.Messaging.InMemory.DependencyInjection;
using Aletheia.Sdk.Branch.Http;
 
var builder =  WebApplication.CreateBuilder(args);
if (builder.Environment.IsDevelopment())
// ...
}
builder.Services.AddAspects();
 
builder.Services.AddMessagingInMemory();
builder.Services.AddEntityEvents();
builder.Services.AddEntityMessaging<Manuscript>(opts =>
    opts.TypeIri = "https://aletheia.katharsis.digital/entities/Manuscript");
builder.Services.AddMessagingTopicEntity();
builder.Services.AddSingleton<EntityEventLog>();
builder.Services.AddHostedService<ManuscriptSubscription>();
 
builder.Services.AddCapabilityHandlersFromAssemblyContaining<GreetHandler>();
builder.Services.AddRuntimeInfo(options => options.ApplicationName = "Aletheia Sample");
// ...

using System.Text.Json.Serialization;
using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Execution;
using Microsoft.Extensions.Logging;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Inbound command for the index capability. With an <see cref="Iri"/> it records one indexed
/// record; without one it reads the ledger back, so the same endpoint both appends and lists.
/// </summary>
/// <remarks>
/// The three properties pin <see cref="JsonPropertyNameAttribute"/> because the two entry points
/// name them differently by default: the subscription's command template produces camelCase JSON,
/// which <c>ICapabilityCatalog.DispatchAsync</c> deserializes with <c>System.Text.Json</c> defaults
/// (case-sensitive, PascalCase), while a manual POST body arrives through ASP.NET Core's camelCase
/// serializer. Pinning <c>iri</c>, <c>operation</c> and <c>label</c> makes one payload shape valid
/// on both paths.
/// </remarks>
/// <param name="Iri">The entity IRI to index, or <c>null</c> to read the ledger.</param>
/// <param name="Operation">The mutation that triggered the dispatch.</param>
/// <param name="Label">The record's label, carried by the template's <c>${event.dto.label}</c> token.</param>
public sealed record IndexCommand(
    [property: JsonPropertyName("iri")] string? Iri = null,
    [property: JsonPropertyName("operation")] string? Operation = null,
    [property: JsonPropertyName("label")] string? Label = null);
 
/// <summary>The ledger the capability holds, together with its size.</summary>
/// <param name="TotalCount">The number of records indexed so far.</param>
/// <param name="Entries">Every indexed record, in arrival order.</param>
public sealed record IndexResponse(int TotalCount, IReadOnlyList<IndexEntry> Entries);
 
/// <summary>
/// The capability the <c>data-record-indexed</c> subscription targets — the Library indexes a record
/// as it arrives. It is not a data operation: it writes no entity and holds no state beyond the
/// ledger, so the same endpoint answers both the subscription and a manual POST.
/// </summary>
[Capability("sample.index")]
public sealed class IndexHandler : ICapabilityHandler<IndexCommand, IndexResponse>
{
    private readonly IndexLedger _ledger;
    private readonly TimeProvider _timeProvider;
    private readonly ILogger<IndexHandler> _logger;
 
    /// <summary>Creates the index handler.</summary>
    /// <param name="ledger">The ledger the indexed records are written to.</param>
    /// <param name="timeProvider">The clock the indexed instant is taken from.</param>
    /// <param name="logger">The log every dispatch is recorded in.</param>
    public IndexHandler(IndexLedger ledger, TimeProvider timeProvider, ILogger<IndexHandler> logger)
    {
        _ledger = ledger;
        _timeProvider = timeProvider;
        _logger = logger;
    }
 
    /// <inheritdoc/>
    public ValueTask<ExecutionResult<IndexResponse>> HandleAsync(
        IndexCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
        // No IRI means "read the ledger"; an IRI means "index this record". One capability, two
        // entry points, so the subscription and a manual probe cannot disagree about the shape.
        if (command.Iri is { Length: > 0 })
        {
            _ledger.Add(new IndexEntry(
                command.Iri,
                command.Operation ?? "Unknown",
                command.Label ?? string.Empty,
                _timeProvider.GetUtcNow()));
 
            _logger.LogInformation(
                "Indexed {Operation} of '{Iri}' (label: {Label}).",
                command.Operation ?? "Unknown",
                command.Iri,
                command.Label ?? "none");
        }
 
        var entries = _ledger.GetAll();
        return ValueTask.FromResult<ExecutionResult<IndexResponse>>(
            new ExecutionResult<IndexResponse>.Ok(new IndexResponse(entries.Count, entries)));
    }
}

namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// One record the <c>sample.index</c> capability has indexed: the IRI the change reported, the
/// operation that caused it, the record's label, and the instant the capability ran.
/// </summary>
/// <param name="Iri">The IRI of the entity that changed.</param>
/// <param name="Operation">The mutation that triggered the dispatch, e.g. <c>Created</c>.</param>
/// <param name="Label">The label carried by the command template's <c>${event.dto.label}</c> token.</param>
/// <param name="AtUtc">The instant the capability ran.</param>
public sealed record IndexEntry(string Iri, string Operation, string Label, DateTimeOffset AtUtc);
 
/// <summary>
/// Thread-safe in-process ledger of the records the subscription has caused to be indexed.
/// Read through <c>POST /api/capabilities/sample/index</c> with no <c>iri</c>.
/// </summary>
public sealed class IndexLedger
{
    private readonly List<IndexEntry> _entries = [];
    private readonly object _lock = new();
 
    /// <summary>Appends one indexed record.</summary>
    /// <param name="entry">The entry to append.</param>
    public void Add(IndexEntry entry)
    {
        lock (_lock)
            _entries.Add(entry);
    }
 
    /// <summary>Every indexed record, in arrival order.</summary>
    /// <returns>A snapshot of the ledger.</returns>
    public IReadOnlyList<IndexEntry> GetAll()
    {
        lock (_lock)
            return [.. _entries];
    }
}

using Aletheia.Sdk.Messaging.InMemory.DependencyInjection;
using Aletheia.Sdk.Branch.Http;
 
using Aletheia.Sdk.Subscription.DependencyInjection;
 
var builder =  WebApplication.CreateBuilder(args);
if (builder.Environment.IsDevelopment())
// ...
    builder.Services.AddInMemoryObjectStorage();
builder.Services.AddObjectStorageHttpFromAssemblyContaining<Manuscript>();
 
builder.Services.AddEntityMessaging<DataRecord>(opts =>
    opts.TypeIri = "https://aletheia.katharsis.digital/entities/DataRecord");
builder.Services.AddSingleton<IndexLedger>();
builder.Services.AddSubscription<DataRecord>("data-record-indexed", subscription =>
{
    subscription.Operations = "created";
    subscription.CapabilityIdentity = "sample.index";
    subscription.CommandTemplateJson = "{\"iri\": ${event.iri}, \"operation\": ${event.operation}, \"label\": ${event.dto.label}}";
});
 
var app = builder.Build();
 
// ...

using System.Text.Json.Serialization;
using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Execution;
using Microsoft.Extensions.Logging;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Inbound command: the note that travels with a heartbeat. The schedule seeds it from
/// <c>CommandJson</c>; a manual POST supplies its own.
/// </summary>
/// <remarks>
/// <see cref="Note"/> carries <see cref="JsonPropertyNameAttribute"/> because the two entry points
/// name it differently by default: the HTTP body arrives through ASP.NET Core's camelCase
/// serializer, while <c>ScheduleTargetExecutor</c> deserializes <c>CommandJson</c> with
/// <c>System.Text.Json</c> defaults. Pinning the wire name to <c>note</c> makes one payload shape
/// valid on both paths.
/// </remarks>
public sealed record ScheduleHeartbeatCommand([property: JsonPropertyName("note")] string? Note = null);
 
/// <summary>
/// The heartbeat's report: the instant it fired and its beat number within the UTC day.
/// </summary>
public sealed record ScheduleHeartbeatResponse(DateTimeOffset FiredAtUtc, int FireCount);
 
/// <summary>
/// The capability the <c>library-heartbeat</c> schedule targets — a scheduled job, not a data
/// operation: it writes nothing and answers with what the clock says.
/// </summary>
[Capability("scheduling.heartbeat")]
public sealed class ScheduleHeartbeatHandler : ICapabilityHandler<ScheduleHeartbeatCommand, ScheduleHeartbeatResponse>
{
    private readonly TimeProvider _timeProvider;
    private readonly ILogger<ScheduleHeartbeatHandler> _logger;
 
    /// <summary>Creates the heartbeat handler.</summary>
    /// <param name="timeProvider">The clock the schedule and the ticker also run on.</param>
    /// <param name="logger">The log the Library's heartbeat is recorded in.</param>
    public ScheduleHeartbeatHandler(TimeProvider timeProvider, ILogger<ScheduleHeartbeatHandler> logger)
    {
        _timeProvider = timeProvider;
        _logger = logger;
    }
 
    /// <inheritdoc/>
    public ValueTask<ExecutionResult<ScheduleHeartbeatResponse>> HandleAsync(
        ScheduleHeartbeatCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
        var firedAtUtc = _timeProvider.GetUtcNow();
 
        // The handler keeps no counter: the beat number is derived from the clock, so the handler stays
        // stateless — overlapping fires of the same schedule each report their own instant, and a
        // restart cannot leave the heartbeat counting from a stale value. For a per-minute schedule the
        // minute within the UTC day *is* the ordinal of the beat.
        var fireCount = (int)(firedAtUtc - firedAtUtc.Date).TotalMinutes;
 
        _logger.LogInformation(
            "Library heartbeat #{FireCount} at {FiredAtUtc} (note: {Note}).",
            fireCount,
            firedAtUtc.ToString("O"),
            command.Note ?? "none");
 
        return ValueTask.FromResult<ExecutionResult<ScheduleHeartbeatResponse>>(
            new ExecutionResult<ScheduleHeartbeatResponse>.Ok(
                new ScheduleHeartbeatResponse(firedAtUtc, fireCount)));
    }
}

using Aletheia.Sdk.Messaging.InMemory.DependencyInjection;
using Aletheia.Sdk.Branch.Http;
 
using Aletheia.Sdk.Scheduling;
using Aletheia.Sdk.Scheduling.DependencyInjection;
 
using Aletheia.Sdk.Subscription.DependencyInjection;
 
// ...
    builder.Services.AddInMemoryObjectStorage();
builder.Services.AddObjectStorageHttpFromAssemblyContaining<Manuscript>();
 
builder.Services.AddScheduling(configure: store => store.Register(new ScheduleDefinition
{
    Name = "library-heartbeat",
    CronExpression = "* * * * *",
    TimeZone = "UTC",
    CapabilityIdentity = "scheduling.heartbeat",
    CommandJson = """{"note":"scheduled-heartbeat"}""",
}));
builder.Services.AddScheduleEntity();
 
builder.Services.AddEntityMessaging<DataRecord>(opts =>
    opts.TypeIri = "https://aletheia.katharsis.digital/entities/DataRecord");
// ...

using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Execution;
using Aletheia.Sdk.Messaging;
using Aletheia.Sdk.Operations;
using Aletheia.Sdk.Repository;
using Aletheia.Sdk.Repository.Contracts;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Fire-and-forget: accept the request, store a pending result, return immediately.
/// </summary>
public sealed record EchoCommand(string Message);
 
/// <summary>
/// Response carries the result IRI — the caller polls this to check completion.
/// </summary>
public sealed record EchoResponse(string ResultIri, bool Accepted);
 
[Capability("sample.echo")]
public sealed class EchoHandler : ICapabilityHandler<EchoCommand, EchoResponse>
{
    private readonly IEntityStore _store;
    private readonly IMessageProducer<string, EchoResult> _producer;
 
    public EchoHandler(IEntityStore store, IMessageProducer<string, EchoResult> producer)
    {
        _store = store;
        _producer = producer;
    }
 
    public async ValueTask<ExecutionResult<EchoResponse>> HandleAsync(
        EchoCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
        using var _ = EntityOperations.Use(_store);
 
        // Create the pending result entity
        var result = new EchoResult { OriginalMessage = command.Message, IsReady = false };
        await EntityOperations.CreateAsync(result, cancellationToken);
 
        // Publish to the echo topic for background processing
        await _producer.ProduceAsync(new MessageEnvelope<EchoResult>(
            "aletheia.echo.requests",
            result.Iri,
            result,
            ExecutionScope.Current ?? new ExecutionCorrelation(),
            DateTimeOffset.UtcNow), cancellationToken);
 
        return new ExecutionResult<EchoResponse>.Ok(
            new EchoResponse(result.Iri, true));
    }
}

using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Capability.Messaging;
using Aletheia.Sdk.Execution;
using Aletheia.Sdk.Operations;
using Aletheia.Sdk.Repository.Contracts;
 
namespace Aletheia.Sdk.Sample;
 
// ── AsyncEcho (user-facing entry point) ──────────────────────────────────────
 
/// <summary>
/// Fire-and-forget via the async capability dispatcher.
/// The caller sends a message, gets back a result IRI immediately, and polls.
/// </summary>
public sealed record AsyncEchoCommand(string Message);
 
/// <summary>
/// Response carries the result IRI — the caller polls this to check completion.
/// </summary>
public sealed record AsyncEchoResponse(string ResultIri, bool Accepted);
 
[Capability("sample.async-echo")]
public sealed class AsyncEchoHandler : ICapabilityHandler<AsyncEchoCommand, AsyncEchoResponse>
{
    private readonly IEntityStore _store;
    private readonly IAsyncCapabilityDispatcher<ProcessEchoCommand, ProcessEchoResponse> _dispatcher;
 
    public AsyncEchoHandler(
        IEntityStore store,
        IAsyncCapabilityDispatcher<ProcessEchoCommand, ProcessEchoResponse> dispatcher)
    {
        _store = store;
        _dispatcher = dispatcher;
    }
 
    public async ValueTask<ExecutionResult<AsyncEchoResponse>> HandleAsync(
        AsyncEchoCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
        using var _ = EntityOperations.Use(_store);
 
        // Create the pending result entity
        var result = new EchoResult { OriginalMessage = command.Message, IsReady = false };
        await EntityOperations.CreateAsync(result, cancellationToken);
 
        // Dispatch to the message bus — fire and forget
        await _dispatcher.PublishAsync(
            new ProcessEchoCommand(result.Iri, command.Message),
            cancellationToken: cancellationToken);
 
        return new ExecutionResult<AsyncEchoResponse>.Ok(
            new AsyncEchoResponse(result.Iri, true));
    }
}

using Aletheia.Sdk.Capability;
using Aletheia.Sdk.Execution;
using Aletheia.Sdk.Operations;
using Aletheia.Sdk.Repository.Contracts;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Command dispatched via the message bus by <see cref="AsyncEchoHandler"/>.
/// Carries the result IRI so the background handler knows which EchoResult to update.
/// </summary>
public sealed record ProcessEchoCommand(string ResultIri, string Message);
 
/// <summary>
/// Response from the background processor — not surfaced to the original caller.
/// </summary>
public sealed record ProcessEchoResponse(string EchoMessage);
 
/// <summary>
/// Runs on a background thread via the CapabilityCommandPumpService.
/// Loads the pending EchoResult, marks it ready, and saves.
/// </summary>
/// <remarks>
/// This handler exists separately from <see cref="EchoHandler"/> because async
/// dispatch has different semantics: the caller owns the pending entity,
/// the handler only updates it. <see cref="EchoHandler"/> owns its entity —
/// it creates it. Different responsibilities, different capabilities.
/// </remarks>
[Capability("sample.process-echo")]
public sealed class ProcessEchoHandler : ICapabilityHandler<ProcessEchoCommand, ProcessEchoResponse>
{
    private readonly IEntityStore _store;
 
    public ProcessEchoHandler(IEntityStore store) => _store = store;
 
    public async ValueTask<ExecutionResult<ProcessEchoResponse>> HandleAsync(
        ProcessEchoCommand command,
        CapabilityContext context,
        CancellationToken cancellationToken = default)
    {
        var result = await _store.LoadAsync<EchoResult>(command.ResultIri, cancellationToken);
        if (result is null)
        {
            return new ExecutionResult<ProcessEchoResponse>.Fail(
                new ExecutionError("NOT_FOUND", $"EchoResult '{command.ResultIri}' not found."));
        }
 
        using var _ = EntityOperations.Use(_store);
 
        result.EchoMessage = $"processed: {command.Message}";
        result.IsReady = true;
        await EntityOperations.UpdateAsync(result, cancellationToken);
 
        return new ExecutionResult<ProcessEchoResponse>.Ok(
            new ProcessEchoResponse(result.EchoMessage));
    }
}

using Aletheia.Sdk.Entity;
using Aletheia.Sdk.Operations;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// An Echo Result — stores the outcome of an async echo request.
/// Created immediately with isReady=false, then updated by the background processor.
/// </summary>
[Entity(Path = "echo-results")]
[Identity(IdentityGenerator.Random)]
[OperationEndpoints]
public partial class EchoResult
{
    [Predicate("originalMessage")]
    public string OriginalMessage { get; set; } = string.Empty;
 
    [Predicate("echoMessage")]
    public string EchoMessage { get; set; } = string.Empty;
 
    [Predicate("isReady")]
    public bool IsReady { get; set; }
}

using Aletheia.Sdk.Messaging;
using Aletheia.Sdk.Operations;
using Aletheia.Sdk.Repository.Contracts;
using Microsoft.Extensions.Logging;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Background subscription that processes Echo requests asynchronously.
/// Listens on the echo topic, processes the message, and marks the result as ready.
/// </summary>
internal sealed class EchoSubscription(
    IMessageConsumer<string, EchoResult> consumer,
    IEntityStore store,
    ILogger<EchoSubscription> logger) : BackgroundService
{
    internal const string Topic = "aletheia.echo.requests";
 
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var envelope in consumer.ConsumeAsync(Topic, stoppingToken).ConfigureAwait(false))
        {
            try
            {
                await ProcessAsync(envelope.Payload, stoppingToken);
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                return;
            }
            catch (Exception exception)
            {
                // A background subscriber must never take the host down with it — HostOptions stops the
                // whole process when a BackgroundService faults. In Enforced mode this delivery has no
                // service identity of its own (see 12-Async-Execution/Learning.md), so the read is
                // REFUSED: the echo stays pending, the refusal is logged, and the next message is read.
                logger.LogWarning(
                    exception,
                    "Echo delivery for {Iri} was refused; the echo stays pending. See 12-Async-Execution/Learning.md.",
                    envelope.Payload.Iri);
            }
        }
    }
 
    private async Task ProcessAsync(EchoResult echo, CancellationToken cancellationToken)
    {
        using var _ = EntityOperations.Use(store);
 
        // Simulate async work — the Echo takes a moment to respond
        await Task.Delay(200, cancellationToken);
 
        var loaded = await store.LoadAsync<EchoResult>(echo.Iri, cancellationToken);
        if (loaded is not null)
        {
            loaded.EchoMessage = $"Echo: {loaded.OriginalMessage}";
            loaded.IsReady = true;
            await EntityOperations.UpdateAsync(loaded, cancellationToken);
        }
    }
}

    builder.Services.AddInMemoryObjectStorage();
builder.Services.AddObjectStorageHttpFromAssemblyContaining<Manuscript>();
 
builder.Services.AddHostedService<EchoSubscription>();
builder.Services.AddCapabilityMessaging();
 
builder.Services.AddScheduling(configure: store => store.Register(new ScheduleDefinition
{
// ...

using Aletheia.Sdk.Messaging.InMemory.DependencyInjection;
using Aletheia.Sdk.Branch.Http;
 
using Aletheia.Sdk.Branch.Http.DependencyInjection;
 
using Aletheia.Sdk.Scheduling;
using Aletheia.Sdk.Scheduling.DependencyInjection;
// ...
builder.Services.AddSingleton<EntityEventLog>();
builder.Services.AddHostedService<ManuscriptSubscription>();
 
builder.Services.AddBranchHttp(builder.Configuration);
 
builder.Services.AddCapabilityHandlersFromAssemblyContaining<GreetHandler>();
builder.Services.AddRuntimeInfo(options => options.ApplicationName = "Aletheia Sample");
// ...
 
app.MapObjectOperations();
 
app.UseBranchScope();
app.MapBranches();
 
app.Run();

app.UseBranchScope();
app.MapBranches();
 
app.MapSnapshots();
 
app.Run();

 
using Aletheia.Sdk.Branch.Http.DependencyInjection;
 
using Aletheia.Sdk.Structure;
using Aletheia.Sdk.Structure.DependencyInjection;
 
using Aletheia.Sdk.Scheduling;
using Aletheia.Sdk.Scheduling.DependencyInjection;
// ...
 
builder.Services.AddBranchHttp(builder.Configuration);
 
builder.Services.AddStructure();
builder.Services.AddOperationEndpointsHttp(typeof(Node).Assembly);
builder.Services.AddCapabilityHandlersFromAssemblyContaining<GetConfiguredTreeHandler>();
 
builder.Services.AddCapabilityHandlersFromAssemblyContaining<GreetHandler>();
builder.Services.AddRuntimeInfo(options => options.ApplicationName = "Aletheia Sample");
// ...

using System.Text.Json;
using Aletheia.Sdk.AI.Scenarios;
using Aletheia.Sdk.Aspects.Abstractions;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// Registers the tutorial's AI scenarios — the note-to-form use-case, TWICE: once
/// as a form value the view accepts, and once all the way into the store, where
/// the write is judged by the operation aspect (chapter 08) before the record
/// exists — and once more for READING the library: a flow that answers questions
/// about the manuscripts that already exist.
/// <br/><br/>
/// Every step runs on a role named through <c>AIOptions.ModelRoles</c>: the two
/// note-to-form flows build and write on <c>builder</c>, and the questions flow
/// reads on <c>reader</c>. All of them are plain TEXT steps: no flow carries an
/// image, so no vision model is needed. The role that writes is the role that
/// reads, because the second step needs the same tool-calling ability as the first.
/// <br/><br/>
/// A note may be typed or DICTATED: an audio part is transcribed before the first
/// step runs and arrives as text, because speech-to-text is intake rather than a
/// step. Each flow NAMES the role that hears it — <see cref="IntakeRole"/> — so the
/// ear a flow uses is part of its declaration instead of a host detail nobody can
/// see. And the two note-to-form scenarios share the FIRST step — the same
/// instruction, the same schema, the same view — so a reader can see that writing a
/// record is one additional step, not a different flow.
/// </summary>
public static class AiScenarios
{
    /// <summary>The Manuscript form shape from chapter 08 — the flows validate against it.</summary>
    public const string ManuscriptFormViewIri = "urn:aletheia:views:manuscript-form";
 
    /// <summary>The operation aspect that judges a manuscript write (chapter 08).</summary>
    public const string ManuscriptWriteAspectIri = "urn:aletheia:aspects:manuscript-write-v1";
 
    /// <summary>
    /// The role that HEARS a dictated note, from <c>AIOptions.ModelRoles</c>. Every flow here names
    /// it as its intake, so the engine behind the transcript is declared rather than guessed: a
    /// reader of a flow's definition can see which model listens to it.
    /// </summary>
    public const string IntakeRole = "transcriber";
 
    /// <summary>
    /// The key of the flow that ANSWERS QUESTIONS about what the library already holds. Declared
    /// here because the tests and the chapter both name it.
    /// </summary>
    public const string QuestionsScenarioKey = "manuscript-questions";
 
    public static void RegisterAiScenarios(this ScenarioRegistry registry)
    {
        // ONE STEP: the note becomes a VALIDATED form value, and nothing is written.
        registry.Register(new ScenarioDefinition(
            Key: "manuscript-form-from-note",
            Description: "Read a note about a manuscript cover — typed, or dictated and transcribed — " +
                "and build a Manuscript form value the view accepts.",
            Steps:
            [
                new ScenarioStep(
                    Name: "builder",
                    ModelRole: "builder",
                    Instruction: FormInstruction(),
                    OutputSchema: ManuscriptSchema(),
                    MaxRetries: 3,
                    ViewIri: ManuscriptFormViewIri),
            ],
            IntakeRole: IntakeRole));
 
        // TWO STEPS: the same form, and then the RECORD — written through the operation aspect by the
        // platform's own write tool. The second step is what makes the flow a transaction rather than
        // a draft: the aspect's shape judges the record before it exists in the store.
        registry.Register(new ScenarioDefinition(
            Key: "manuscript-record-from-note",
            Description: "Read a note, build the Manuscript form value the view accepts, and write the " +
                "record through the manuscript-write operation aspect.",
            Steps:
            [
                new ScenarioStep(
                    Name: "builder",
                    ModelRole: "builder",
                    Instruction: FormInstruction(),
                    OutputSchema: ManuscriptSchema(),
                    MaxRetries: 3,
                    ViewIri: ManuscriptFormViewIri),
                new ScenarioStep(
                    Name: "writer",
                    ModelRole: "builder",
                    Instruction: WriterInstruction(),
                    OutputSchema: IriSchema(),
                    MaxRetries: 2),
            ],
            IntakeRole: IntakeRole));
 
        // ONE STEP, and it WRITES NOTHING: it answers. The step is given no output schema — the
        // answer is prose — and it runs on the reading role, whose job is to navigate the platform
        // and say what it found. Everything the earlier flows learned to BUILD, this one READS:
        // the entities, the aspects that frame them, the records already in the store.
        registry.Register(new ScenarioDefinition(
            Key: QuestionsScenarioKey,
            Description: "Answer questions about the manuscripts the library already holds — each " +
                "step explores the platform's own definitions and records through its tools, then " +
                "answers from what it read.",
            Steps:
            [
                new ScenarioStep(
                    Name: "reader",
                    ModelRole: "reader",
                    Instruction: QuestionsInstruction(),
                    // No schema: this step produces an ANSWER, not a value. `TextOutput` is exactly
                    // that contract — raw text in, raw text out, no JSON and no shape to validate.
                    OutputSchema: default,
                    MaxRetries: 2,
                    TextOutput: true),
            ],
            IntakeRole: IntakeRole));
    }
 
    /// <summary>
    /// The first step's instruction: it states the platform objects the form belongs to — the entity,
    /// the view that judges it, the operation aspect a write must also satisfy, and the query aspects a
    /// read MAY go through (with the no-operation aspect named for the case where none is picked) — and
    /// it says which member is an ENUMERATION, so the model looks the list up instead of inventing one.
    /// <br/><br/>
    /// The IRIs come from the aspect constants themselves, not from strings pasted here, so a renamed or
    /// moved aspect cannot leave the prompt describing something that no longer exists.
    /// </summary>
    private static string FormInstruction() =>
        string.Join(
            Environment.NewLine,
            [
                "You turn the user's note about a manuscript — typed, or dictated and transcribed into " +
                    "user voice instructions — into the Manuscript form value of the Aletheia Study.",
                "",
                "The platform objects this form belongs to:",
                "- Entity: Manuscript, entity path `manuscripts`.",
                $"- View aspect `{ViewAspects.ManuscriptForm.Iri}`: the shape that judges THIS step's " +
                    "output — the form itself. Three members, three JSON shapes:",
                "  - `title`, a string of at least five characters. Take it from the note and quote it " +
                    "as the note gives it.",
                "  - `genre`, the IRI of a PUBLISHED genre: a genre is an enumeration, so call " +
                    "`aletheia_ai` with operation `list` and target `genres`, and use a value it " +
                    "publishes, with the name it publishes for it in the reader's language. Never " +
                    "invent a genre IRI, and never translate a genre name yourself — the platform " +
                    "publishes the wording.",
                "  - `year`, an integer of at least 1000. Take it from the note; if the note names no " +
                    "year, OMIT the key rather than guessing one.",
                $"- Operation aspect `{OperationAspects.ManuscriptWriteV1.Iri}`: the ONE aspect that " +
                    "must be satisfied when a Manuscript is written. It matters to the step AFTER this " +
                    "one; here it only tells you what a record has to be.",
                $"- Query aspects `{QueryAspects.ManuscriptAccessV1.Iri}` and " +
                    $"`{QueryAspects.ManuscriptByGenreV1.Iri}`: what a READ may go through. Neither is " +
                    $"required — with no query aspect picked the platform's no-operation aspect " +
                    $"`{Aspect.NoOpIri}` applies and the read is simply unconstrained.",
                "",
                "Filling it:",
                "- The note is the only source of the title and the year: if it does not give one, leave " +
                    "that key out.",
                "- Ask the tools what the platform publishes before you answer, and judge the form " +
                    "against the view with the `validate` operation of `aletheia_ai`. Fix only what " +
                    "the note supports.",
            ]);
 
    /// <summary>
    /// The second step's instruction: it writes the RECORD, and it says which aspect the write must be
    /// judged by — the tool takes the aspect IRI, so the aspect's shape runs before the store sees the
    /// record. A write that named no aspect would be ungoverned, which is the one thing this step must
    /// never do.
    /// </summary>
    private static string WriterInstruction() =>
        string.Join(
            Environment.NewLine,
            [
                "You write the manuscript record from the form value above, using the platform's tools.",
                "",
                "- Call `aletheia_ai` with operation `create` and target `manuscripts`, putting EVERY " +
                    "member of the form value above in the payload under the entity's own keys " +
                    "(`Title`, `Genre`, `Year`). A record that lost one of them would not be the " +
                    "record the view validated, so `Genre` — the IRI — is passed too.",
                $"- Pass `aspectIri` = `{ManuscriptWriteAspectIri}` so the operation aspect judges the " +
                    "write BEFORE the record is stored. Never write without it: a write that names no " +
                    "aspect is ungoverned, and this flow exists to be governed.",
                "- The tool answers with the record it created. If it refuses, the refusal is the " +
                    "aspect's own finding: correct what the form value supports and never invent a value " +
                    "to satisfy it.",
                $"- End by answering with a single JSON object: `{{\"iri\": \"<the created record's IRI>\"}}`.",
            ]);
 
    /// <summary>The form the view judges: title and genre and year are all required by its shape.</summary>
    private static JsonElement ManuscriptSchema() => JsonSchema(
        ("title", "string", Required: true),
        ("genre", "string", Required: true),
        ("year", "integer", Required: true));
 
    /// <summary>
    /// The questions flow's instruction: EXPLORE, then answer.
    /// <br/><br/>
    /// The point of this flow is that nothing has to be enumerated for it. Every definition the
    /// platform publishes is served the same way, and every entity type's records are served by the
    /// same two tools, so the instruction can tell the model to LOOK — with the ontology it
    /// was given as the map, and the operations as the only vocabulary it needs to know. A prompt
    /// that listed the manuscripts, the genres and the authors would be a prompt that goes stale the
    /// moment a record is added; this one stays true because it describes how to ask, not what the
    /// answer is.
    /// </summary>
    private static string QuestionsInstruction() =>
        string.Join(
            Environment.NewLine,
            [
                "You answer questions about what the Aletheia Study already holds, using the " +
                    "platform's own tools. You never answer from memory: everything you say about a " +
                    "manuscript, a genre, an author or a link between them must come from something " +
                    "you READ in this run.",
                "",
                "The ontology in your system prompt is your map — the entity types, the aspects that " +
                    "frame them and the shapes that judge them. Use it to decide WHAT to ask for, " +
                    "then ask:",
                "- `aletheia_ai` is the one instrument: pass `operation` (`list`, `read`, `create`, " +
                    "`update`, `delete`, `execute`, `validate`, `plan`) and `target` (an entity path " +
                    "like `manuscripts`, a capability identity, or a view aspect IRI). `list` lists " +
                    "the records of one entity type; `read` reads one record by the IRI a list gave " +
                    "you. Every entity type is served the same way — there is nothing else to learn " +
                    "per type.",
                "- The same instrument runs the platform's own actions (`execute`) and checks a draft " +
                    "against the shape that would judge it (`validate`). `describe` returns one full " +
                    "definition — properties, labels, the shape — when you need the wording exactly.",
                "- The VIEW aspects tell you how a value is shaped and what the shape requires, the " +
                    "OPERATION aspects tell you what a write must satisfy, and the QUERY aspects tell " +
                    "you what a read may go through. All of them are published the same way the " +
                    "entities are, and all of them are worth reading before you claim how something " +
                    "is framed.",
                "",
                "How to answer:",
                "- Explore FIRST, then answer. Name the IRIs you actually read — a manuscript, a " +
                    "genre, an author, an aspect, the branch it lives on — instead of paraphrasing " +
                    "them, so the reader can follow the same link you followed.",
                "- Follow the LINKS: a manuscript's genre and author are references, so read the " +
                    "record they point at before you describe them.",
                "- Say what you did not find. An IRI you never read, a type with no records, an " +
                    "aspect this deployment does not publish — state it as the absence it is rather " +
                    "than filling the gap with something plausible.",
                "- Answer in prose in the reader's language. No JSON object, no schema: this flow " +
                    "produces an ANSWER, not a form value.",
            ]);
 
    /// <summary>What the writing step reports: the IRI of the record it created.</summary>
    private static JsonElement IriSchema() => JsonSchema(("iri", "string", Required: true));
 
    private static JsonElement JsonSchema(params (string Name, string Type, bool Required)[] properties)
    {
        var props = new Dictionary<string, object>();
        var required = new List<string>();
        foreach (var (name, type, isRequired) in properties)
        {
            props[name] = new { type };
            if (isRequired) required.Add(name);
        }
 
        return JsonSerializer.SerializeToElement(new
        {
            type = "object",
            properties = props,
            required,
        });
    }
}

using Microsoft.Extensions.Configuration;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// The one model credential this machine holds, handed to the model roles the AI chapter binds.
/// <br/><br/>
/// A model connection — endpoint, model, limits — is configuration and belongs in
/// <c>appsettings*.json</c>. A credential is not: it is a fact about the machine, never about the
/// repository. So the host reads it from <c>.env.local</c> (gitignored; the tracked
/// <c>.env.local.example</c> shows the shape) or from the ambient <c>DEEPSEEK_API_KEY</c>, and
/// gives it to every role whose own <c>ApiKey</c> is still empty — which is what makes a plain
/// <c>dotnet run</c> work without a key in any tracked file, and what lets an explicitly
/// configured key (appsettings, user-secrets, environment) keep its say.
/// </summary>
internal static class LocalModelCredential
{
    /// <summary>The variable a reader is told to set — one value, every role that needs it.</summary>
    internal const string VariableName = "DEEPSEEK_API_KEY";
 
    /// <summary>The file a reader may keep instead, beside the project and gitignored.</summary>
    internal const string FileName = ".env.local";
 
    /// <summary>
    /// Give <see cref="VariableName"/> to every model role whose key is empty. Nothing happens
    /// when the machine provides no key: the roles stay keyless, the host still starts, and the
    /// AI endpoints answer 401 with the provider's own words.
    /// </summary>
    internal static void Apply(ConfigurationManager configuration, string contentRootPath)
    {
        var key = Read(contentRootPath);
        if (string.IsNullOrWhiteSpace(key))
        {
            return;
        }
 
        foreach (var role in configuration.GetSection("AI:ModelRoles").GetChildren())
        {
            var roleKey = $"AI:ModelRoles:{role.Key}:ApiKey";
            if (string.IsNullOrWhiteSpace(configuration[roleKey]))
            {
                configuration[roleKey] = key;
            }
        }
    }
 
    /// <summary>
    /// The key as the machine holds it: the ambient variable first (a shell that exports it means
    /// it), then the file. Quoted values are unquoted, comments and blank lines ignored — a
    /// reader who pastes the key with quotes around it still gets a usable value.
    /// </summary>
    internal static string? Read(string contentRootPath)
    {
        var ambient = Environment.GetEnvironmentVariable(VariableName);
        if (!string.IsNullOrWhiteSpace(ambient))
        {
            return Unquote(ambient);
        }
 
        var file = Path.Combine(contentRootPath, FileName);
        if (!File.Exists(file))
        {
            return null;
        }
 
        foreach (var line in File.ReadAllLines(file))
        {
            var trimmed = line.Trim();
            if (trimmed.Length == 0 || trimmed[0] is '#')
            {
                continue;
            }
 
            var separator = trimmed.IndexOf('=');
            if (separator <= 0)
            {
                continue;
            }
 
            if (!trimmed[..separator].Trim().Equals(VariableName, StringComparison.Ordinal))
            {
                continue;
            }
 
            var value = Unquote(trimmed[(separator + 1)..]);
            return value.Length == 0 ? null : value;
        }
 
        return null;
    }
 
    /// <summary>Trim whitespace and one layer of matching quotes — a shape a reader may type.</summary>
    private static string Unquote(string value)
    {
        var trimmed = value.Trim();
        if (trimmed.Length >= 2 &&
            (trimmed[0] is '"' or '\'') &&
            trimmed[^1] == trimmed[0])
        {
            return trimmed[1..^1].Trim();
        }
 
        return trimmed;
    }
}

using Microsoft.Extensions.Configuration;
 
namespace Aletheia.Sdk.Sample;
 
/// <summary>
/// The local model credential: where the host finds it, and what it does with it. These tests
/// write their own file into a temporary directory — never the developer's <c>.env.local</c> —
/// and restore the ambient variable afterwards.
/// </summary>
public sealed class LocalModelCredentialTests : IDisposable
{
    private const string Sample = "sk-not-a-real-key";
 
    private readonly string _root = Path.Combine(Path.GetTempPath(), "aletheia-cred-" + Guid.NewGuid().ToString("N"));
    private readonly string? _ambient = Environment.GetEnvironmentVariable(LocalModelCredential.VariableName);
 
    public LocalModelCredentialTests()
    {
        Directory.CreateDirectory(_root);
        Environment.SetEnvironmentVariable(LocalModelCredential.VariableName, null);
    }
 
    public void Dispose()
    {
        Environment.SetEnvironmentVariable(LocalModelCredential.VariableName, _ambient);
        Directory.Delete(_root, recursive: true);
    }
 
    private void WriteEnv(string contents) =>
        File.WriteAllText(Path.Combine(_root, LocalModelCredential.FileName), contents);
 
    private static ConfigurationManager Configuration(params (string Key, string Value)[] values)
    {
        var configuration = new ConfigurationManager();
        configuration.AddInMemoryCollection(new Dictionary<string, string?>
        {
            ["AI:ModelRoles:reader:ApiKey"] = string.Empty,
            ["AI:ModelRoles:builder:ApiKey"] = string.Empty,
        });
        foreach (var (key, value) in values)
        {
            configuration[key] = value;
        }
 
        return configuration;
    }
 
    [Fact]
    public void Reads_the_key_from_the_env_file()
    {
        WriteEnv($"# a comment\n\n{LocalModelCredential.VariableName}={Sample}\n");
 
        Assert.Equal(Sample, LocalModelCredential.Read(_root));
    }
 
    [Fact]
    public void Ignores_another_variable_and_blank_values()
    {
        WriteEnv($"OTHER_KEY={Sample}\n{LocalModelCredential.VariableName}=\n");
 
        Assert.Null(LocalModelCredential.Read(_root));
    }
 
    [Fact]
    public void Unquotes_a_value_a_reader_typed_with_quotes()
    {
        WriteEnv($"{LocalModelCredential.VariableName}=\"{Sample}\"\n");
 
        Assert.Equal(Sample, LocalModelCredential.Read(_root));
    }
 
    [Fact]
    public void Prefers_the_ambient_variable_over_the_file()
    {
        WriteEnv($"{LocalModelCredential.VariableName}=from-file\n");
        Environment.SetEnvironmentVariable(LocalModelCredential.VariableName, "from-environment");
 
        Assert.Equal("from-environment", LocalModelCredential.Read(_root));
    }
 
    [Fact]
    public void Yields_nothing_when_the_machine_has_no_key()
    {
        Assert.Null(LocalModelCredential.Read(_root));
    }
 
    [Fact]
    public void Gives_the_key_to_every_role_that_has_none()
    {
        WriteEnv($"{LocalModelCredential.VariableName}={Sample}\n");
        var configuration = Configuration();
 
        LocalModelCredential.Apply(configuration, _root);
 
        Assert.Equal(Sample, configuration["AI:ModelRoles:reader:ApiKey"]);
        Assert.Equal(Sample, configuration["AI:ModelRoles:builder:ApiKey"]);
    }
 
    [Fact]
    public void Never_overwrites_a_role_that_already_has_a_key()
    {
        WriteEnv($"{LocalModelCredential.VariableName}={Sample}\n");
        var configuration = Configuration(("AI:ModelRoles:reader:ApiKey", "configured-elsewhere"));
 
        LocalModelCredential.Apply(configuration, _root);
 
        Assert.Equal("configured-elsewhere", configuration["AI:ModelRoles:reader:ApiKey"]);
        Assert.Equal(Sample, configuration["AI:ModelRoles:builder:ApiKey"]);
    }
 
    [Fact]
    public void Leaves_the_roles_alone_when_the_machine_has_no_key()
    {
        var configuration = Configuration();
 
        LocalModelCredential.Apply(configuration, _root);
 
        Assert.Equal(string.Empty, configuration["AI:ModelRoles:reader:ApiKey"]);
        Assert.Equal(string.Empty, configuration["AI:ModelRoles:builder:ApiKey"]);
    }
}