Skip to content

Release PII and encrypted values from Chronicle read models

Use IReadModels.Release in the Chronicle .NET client to decrypt personally identifiable information marked [PII] and values marked [Encrypted] in a read model you already hold. You need this when the instance came from raw storage, a cache or message payload, or a Watch<TReadModel>() update that has not been released.

You do not need a separate release after GetInstanceById, GetInstances or GetSnapshotsById on IReadModels. The kernel decrypts projection-backed instances before returning them, and the client releases reducer-backed instances before returning them. Read models and PII explains that automatic path and how to mark personal data; Security covers [Encrypted] values.

Manual release uses the read model’s schema to find both kinds of protected value. Start by declaring the annotations and the identity needed for subject-scoped encryption:

using Cratis.Chronicle;
using Cratis.Chronicle.Compliance.GDPR;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reducers;
[PII]
public record ReleasingPiiRequesterName(string Value) : ConceptAs<string>(Value)
{
public static readonly ReleasingPiiRequesterName NotSet = new(string.Empty);
public static implicit operator string(ReleasingPiiRequesterName name) => name.Value;
public static implicit operator ReleasingPiiRequesterName(string value) => new(value);
}
[EventType]
public record ReleasingPiiSupportTicketOpened(string CustomerId, ReleasingPiiRequesterName RequesterName);
public record ReleasingPiiSupportTicket(string Id, [Subject] string CustomerId, [PII] string RequesterName);
public class ReleasingPiiSupportTicketReducer : IReducerFor<ReleasingPiiSupportTicket>
{
public ReleasingPiiSupportTicket Opened(ReleasingPiiSupportTicketOpened @event, ReleasingPiiSupportTicket? current, EventContext context) =>
new(context.EventSourceId.Value, @event.CustomerId, @event.RequesterName);
}

View C# snippet source on GitHub

The ticket’s Id identifies the ticket, while CustomerId identifies the person whose name is protected. [Subject] tells manual release to use CustomerId to find that person’s key. A property with the Subject type alone does not declare this role.

RequesterName also needs [PII] on the read model. Chronicle uses the read model’s own schema for encryption; mapping a PII-marked event property does not transfer that marker. This applies to both reducers and projections.

Pass the instance to Release and use the returned value. The client resolves its subject, sends the annotated payload to the kernel and deserializes the released result:

using Cratis.Chronicle;
public class ReleasingPiiSupportTicketService(IEventStore eventStore)
{
public Task<ReleasingPiiSupportTicket> Release(ReleasingPiiSupportTicket ticket) =>
eventStore.ReadModels.Release(ticket);
}

View C# snippet source on GitHub

The collection overload resolves a subject for each instance independently. You can pass tickets belonging to different customers in the same collection:

using Cratis.Chronicle;
public class ReleasingPiiSupportTicketBatchService(IEventStore eventStore)
{
public Task<IEnumerable<ReleasingPiiSupportTicket>> ReleaseAll(IEnumerable<ReleasingPiiSupportTicket> tickets) =>
eventStore.ReadModels.Release(tickets);
}

View C# snippet source on GitHub

Watch delivers changes without calling Release. Release each update before using its protected values, and skip removal notifications or changes without an instance:

using Cratis.Chronicle;
public class ReleasingPiiSupportTicketWatcher(IEventStore eventStore)
{
public IDisposable Start() =>
eventStore.ReadModels.Watch<ReleasingPiiSupportTicket>().Subscribe(async changeset =>
{
if (changeset.Removed || changeset.ReadModel is null)
{
return;
}
var ticket = await eventStore.ReadModels.Release(changeset.ReadModel);
Console.WriteLine($"{changeset.ModelKey}: {ticket.RequesterName}");
});
}

View C# snippet source on GitHub

Here, the subscriber uses the returned ticket to print the released requester name. It does not read that name directly from the incoming changeset.

Release looks at the instance you hand it to work out whose encryption key to use, in this order:

Priority Mechanism
1 A property decorated with [Subject]
2 A constructor parameter decorated with [Subject] (record shorthand)
3 A property named Id, case-insensitive

A property attribute takes precedence over a constructor-parameter attribute. If the selected subject property is null, empty or Subject.NotSet, Release tries Id. During a migration to an explicit [Subject] property, that fallback can still release older rows when their Id identifies the correct subject.

[PII] values and [Encrypted] values with the default EncryptionScope.Subject need a subject to identify their key. Namespace- and global-scoped encryption do not; see Scope. When no subject resolves, the annotations determine what happens:

Read model annotations Result without a resolved subject
No [PII] or [Encrypted] metadata Returns the instance unchanged without calling the kernel
Only subject-scoped values Returns the instance unchanged; logs a warning if a subject-scoped value is present
At least one namespace- or global-scoped [Encrypted] value Calls the kernel even without a subject; any subject-scoped values that cannot be released degrade as described below

A model carrying only namespace- or global-scoped secrets therefore needs no Id or [Subject] property for release.

Add [Subject] when the identity that manual Release should use differs from the read model’s own key, exactly as you would on a command or event property to control which identity an append is encrypted under. When the two already match — a person’s own profile, keyed by their own identity — the Id fallback handles it and no attribute is needed.

This attribute affects only subject discovery from the object passed to Release; it does not assign ownership to a managed projection document. Chronicle’s projection pipeline derives ownership from the event that supplied each PII value and persists that information in its reserved __subject and __subjects fields. An explicit subject supplied while appending an event therefore controls the values originating from that event, regardless of whether the read model exposes a Subject property.

A property that can’t be decrypted — its encryption key was deleted, or it was encrypted under a different subject entirely — degrades on its own; the rest of the instance still comes back intact. The property comes back as the empty value of its type: an empty string for a string, 0 or false for a non-nullable number or boolean, null for a nullable one, and an empty collection or object for a collection or value object. Whether an erased value should be distinguishable from a stored 0, false or empty value is an open decision in issue 4620. What a caller sees for each of those cases is covered in Read models and PII.

If the kernel returns a release error, such as a schema mismatch, the client logs it and returns the original instance, still encrypted. This fallback does not catch every failure: transport, serialization and deserialization exceptions can propagate to the caller. If Release returns but a value remains ciphertext, check the application logs before treating the data as unrecoverable.