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);}import io.cratis.chronicle.compliance.Piiimport io.cratis.chronicle.events.EventTypeimport io.cratis.chronicle.readModels.ReadModel
@EventTypedata class SupportTicketOpened(val customerId: String = "", val requesterName: String = "")
/** * [Release][io.cratis.chronicle.readModels.IReadModelsService.release] resolves whose encryption * key to use by looking for a property named `id`, case-insensitive - here that is the ticket's * own key, which is also the customer it belongs to. */@ReadModeldata class ReleasingReadModelSupportTicket( val id: String = "", @Pii val requesterName: String = "")import io.cratis.chronicle.compliance.Pii;import io.cratis.chronicle.events.EventType;import io.cratis.chronicle.readModels.ReadModel;
@EventTyperecord SupportTicketOpened(String customerId, String requesterName) {}
// Release resolves whose encryption key to use by looking for a property named "id",// case-insensitive - here that is the ticket's own key, which is also the customer it belongs to.@ReadModelclass ReleasingReadModelSupportTicket { private String id = ""; @Pii private String requesterName = "";
public String getId() { return id; } public void setId(String id) { this.id = id; }
public String getRequesterName() { return requesterName; } public void setRequesterName(String requesterName) { this.requesterName = requesterName; }}defmodule MyApp.Events.ReleasingPiiSupportTicketOpened do use Chronicle.Events.EventType, id: "releasing-pii-support-ticket-opened"
defstruct [:customer_id, :requester_name]end
defmodule MyApp.ReadModels.ReleasingPiiSupportTicket do use Chronicle.ReadModels.ReadModel
defstruct [:id, :customer_id, :requester_name]
subject :customer_id pii :requester_nameend
defmodule MyApp.Reducers.ReleasingPiiSupportTicketReducer do use Chronicle.Reducers.Reducer, model: MyApp.ReadModels.ReleasingPiiSupportTicket
alias MyApp.Events.ReleasingPiiSupportTicketOpened
@handles ReleasingPiiSupportTicketOpened
@impl true def reduce(%ReleasingPiiSupportTicketOpened{} = event, _model, context) do %MyApp.ReadModels.ReleasingPiiSupportTicket{ id: context.event_source_id, customer_id: event.customer_id, requester_name: event.requester_name } endendimport { EventContext, eventType, pii, reducer, subject } from '@cratis/chronicle';import { field } from '@cratis/fundamentals';
@eventType()class ReleasingPiiSupportTicketOpened { @field(String) readonly customerId: string; @field(String) readonly requesterName: string;
constructor(customerId: string, requesterName: string) { this.customerId = customerId; this.requesterName = requesterName; }}
class ReleasingPiiSupportTicket { // The ticket's own id identifies the ticket, not the person the PII belongs to - @subject() // tells release() to use customerId as the encryption key's owner instead. Without it, // release() would fall back to id. id = '';
@subject() customerId = '';
@pii('The name of the person who opened the ticket') requesterName = '';}
@reducer('', undefined, ReleasingPiiSupportTicket)class ReleasingPiiSupportTicketReducer { releasingPiiSupportTicketOpened( event: ReleasingPiiSupportTicketOpened, current: ReleasingPiiSupportTicket | undefined, context: EventContext ): ReleasingPiiSupportTicket { return { id: context.eventSourceId, customerId: event.customerId, requesterName: event.requesterName }; }}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.
Release a single instance
Section titled “Release a single instance”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);}import io.cratis.chronicle.IEventStoreimport io.cratis.chronicle.readModels.ReadModel
@ReadModeldata class ReleasingSingleInstanceSupportTicket(val id: String = "", val requesterName: String = "")
suspend fun release(store: IEventStore, ticket: ReleasingSingleInstanceSupportTicket): ReleasingSingleInstanceSupportTicket = store.readModels.release(ticket)import io.cratis.chronicle.EventStore;import io.cratis.chronicle.readModels.ReadModel;
import io.cratis.chronicle.java.ReadModelsJavaBridge;
@ReadModelclass ReleasingSingleInstanceSupportTicket { private String id = ""; private String requesterName = "";
public String getId() { return id; } public void setId(String id) { this.id = id; }
public String getRequesterName() { return requesterName; } public void setRequesterName(String requesterName) { this.requesterName = requesterName; }}
class ReadModelsReleasingPiiSingleInstance { ReleasingSingleInstanceSupportTicket release(EventStore store, ReleasingSingleInstanceSupportTicket ticket) { return ReadModelsJavaBridge.release(store.getReadModels(), ticket); }}Elixir does not support this workflow yet.import { IEventStore } from '@cratis/chronicle';
class ReleasingPiiSupportTicketService { constructor(private readonly store: IEventStore) {}
release(ticket: ReleasingPiiSupportTicket): Promise<ReleasingPiiSupportTicket> { return this.store.readModels.release(ReleasingPiiSupportTicket, ticket); }}Release a collection
Section titled “Release a collection”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);}import io.cratis.chronicle.IEventStoreimport io.cratis.chronicle.readModels.ReadModel
@ReadModeldata class ReleasingCollectionSupportTicket(val id: String = "", val requesterName: String = "")
/** * Releases more than one instance at once - the subject for each is resolved independently, so * a single batch can freely mix data belonging to different people. */suspend fun releaseAll(store: IEventStore, tickets: List<ReleasingCollectionSupportTicket>): List<ReleasingCollectionSupportTicket> = store.readModels.releaseMany(tickets)import io.cratis.chronicle.EventStore;import io.cratis.chronicle.readModels.ReadModel;
import java.util.List;
import io.cratis.chronicle.java.ReadModelsJavaBridge;
@ReadModelclass ReleasingCollectionSupportTicket { private String id = ""; private String requesterName = "";
public String getId() { return id; } public void setId(String id) { this.id = id; }
public String getRequesterName() { return requesterName; } public void setRequesterName(String requesterName) { this.requesterName = requesterName; }}
class ReadModelsReleasingPiiCollection { // Releases more than one instance at once - the subject for each is resolved independently. List<ReleasingCollectionSupportTicket> releaseAll(EventStore store, List<ReleasingCollectionSupportTicket> tickets) { return ReadModelsJavaBridge.releaseMany(store.getReadModels(), tickets); }}Elixir does not support this workflow yet.import { IEventStore } from '@cratis/chronicle';
class ReleasingPiiSupportTicketBatchService { constructor(private readonly store: IEventStore) {}
releaseAll(tickets: ReleasingPiiSupportTicket[]): Promise<ReleasingPiiSupportTicket[]> { return this.store.readModels.releaseMany(ReleasingPiiSupportTicket, tickets); }}Release while watching for changes
Section titled “Release while watching for changes”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}"); });}import io.cratis.chronicle.IEventStoreimport io.cratis.chronicle.readModels.ReadModelimport kotlinx.coroutines.flow.collect
@ReadModeldata class ReleasingWatchSupportTicket(val id: String = "", val requesterName: String = "")
/** * [io.cratis.chronicle.readModels.IReadModelsService.watch] is the one built-in read that does * not release PII automatically - release each change yourself as it arrives. */suspend fun watchTickets(store: IEventStore) { store.readModels.watch(ReleasingWatchSupportTicket::class).collect { changeset -> if (changeset.removed || changeset.readModel == null) return@collect
val ticket = store.readModels.release(changeset.readModel!!) println("${changeset.modelKey}: ${ticket.requesterName}") }}import io.cratis.chronicle.EventStore;import io.cratis.chronicle.readModels.ReadModel;
import io.cratis.chronicle.java.ReadModelsJavaBridge;import kotlinx.coroutines.Job;
@ReadModelclass ReleasingWatchSupportTicket { private String id = ""; private String requesterName = "";
public String getId() { return id; } public void setId(String id) { this.id = id; }
public String getRequesterName() { return requesterName; } public void setRequesterName(String requesterName) { this.requesterName = requesterName; }}
class ReadModelsReleasingPiiWatch { // watch() is the one built-in read that does not release PII automatically - release each // change yourself as it arrives. Job watchTickets(EventStore store) { return ReadModelsJavaBridge.watch(store.getReadModels(), ReleasingWatchSupportTicket.class, changeset -> { if (changeset.getRemoved() || changeset.getReadModel() == null) { return; }
ReleasingWatchSupportTicket ticket = ReadModelsJavaBridge.release(store.getReadModels(), changeset.getReadModel()); System.out.println(changeset.getModelKey() + ": " + ticket.getRequesterName()); }); }}Elixir does not support this workflow yet.import { IEventStore } from '@cratis/chronicle';
class ReleasingPiiSupportTicketWatcher { constructor(private readonly store: IEventStore) {}
async start(): Promise<void> { for await (const changeset of this.store.readModels.watch(ReleasingPiiSupportTicket)) { if (changeset.removed) { continue; }
const ticket = await this.store.readModels.release(ReleasingPiiSupportTicket, changeset.readModel); console.log(`${changeset.key}: ${ticket.requesterName}`); } }}Here, the subscriber uses the returned ticket to print the released requester name. It does not read that name directly from the incoming changeset.
How the subject is resolved
Section titled “How the subject is resolved”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.
When release can’t recover a value
Section titled “When release can’t recover a value”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.
Related topics
Section titled “Related topics”- Read models and PII - How Chronicle encrypts and decrypts PII automatically, and GDPR erasure
- The PII attribute - Marking event and read model properties as PII
- Encrypting operational secrets - Marking a value
[Encrypted]instead of[PII] - Watching Read Models - Subscribing to read model changes
- Getting a Single Instance - The read path that releases for you