@cratis/pi 0.0.1

package/skills/cratis-chronicle-client-typescript/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: cratis-chronicle-client-typescript
+description: Talk to a Chronicle server from a Node.js or TypeScript application with @cratis/chronicle - reflect-metadata and decorator compiler settings, ChronicleClient and connection strings, @eventType classes, eventLog.append, reactors and reducers dispatched by camelCase method name, model-bound and declarative projections, glob-based artifact discovery, and the lazy connect and keepalive lifecycle. Use when a Node application appends to or observes a Chronicle event store. Do not use for the .NET, Kotlin, or Elixir clients, and do not use for Arc React frontends or generated Arc proxies.
+license: MIT
+---
+
+# The Chronicle client for TypeScript
+
+`@cratis/chronicle` is a **standalone Node.js client SDK** that speaks gRPC to a
+Chronicle server. It is not a browser library and it is not the Arc TypeScript
+proxy layer — an Arc frontend calls generated command and query proxies over
+HTTP and never sees this package.
+
+## Verified product sources
+
+This skill is verified against `Cratis/Chronicle.TypeScript` at tag `v4.0.0`
+(commit `bed0b86`), which is the version published on npm.
+
+| Package | Version | Where |
+| --- | --- | --- |
+| `@cratis/chronicle` | `4.0.0` | `Source/package.json:2` |
+| `@cratis/chronicle.contracts` | `17.0.0` | `Source/package.json` dependency |
+| `@cratis/fundamentals` | `^7.14.0` | **peer dependency** — you install it |
+
+> **Do not read the version out of the repository.** `Source/package.json` says
+> `1.0.0`; `publish-version.js` overwrites it at publish time. Take the version
+> from npm.
+
+**`v4.0.0` is a major bump and it changed real API.** Guidance written against
+`3.x` is wrong in at least three places — event tags did not exist, reducers took
+two arguments, and two event-store RPCs were renamed. Do not carry `3.x` examples
+forward.
+
+## Project setup
+
+```shell
+yarn add @cratis/chronicle @cratis/fundamentals reflect-metadata
+```
+
+`@cratis/fundamentals` is a peer dependency, so it does not arrive on its own.
+`reflect-metadata` must be imported **once, at the entry point**, before any
+decorated class is loaded (`Documentation/getting-started.md:16-27`):
+
+```typescript
+import 'reflect-metadata';
+```
+
+The package is **ESM-only** (`"type": "module"`, `Source/package.json:34`) and
+requires decorator support:
+
+```jsonc
+// tsconfig.json
+{
+    "compilerOptions": {
+        "experimentalDecorators": true,
+        "emitDecoratorMetadata": true
+    }
+}
+```
+
+Both are set in the shipped sample (`Samples/Console/tsconfig.json:12-13`).
+
+## Connecting
+
+```typescript
+import 'reflect-metadata';
+import { ChronicleClient, ChronicleOptions } from '@cratis/chronicle';
+
+const client = new ChronicleClient(ChronicleOptions.development());
+try {
+    const store = await client.getEventStore('<EventStoreName>');
+    // ... use store ...
+} finally {
+    client.dispose();
+}
+```
+
+`IChronicleClient` is three members — `Source/IChronicleClient.ts:16-39`:
+
+| Member | Line |
+| --- | --- |
+| `readonly options: ChronicleOptions` | `:18` |
+| `getEventStore(name, namespace?): Promise<IEventStore>` | `:27` |
+| `getEventStores(): Promise<EventStoreName[]>` | `:33` |
+| `dispose(): void` | `:38` |
+
+`ChronicleClient`'s constructor takes exactly one argument —
+`constructor(readonly options: ChronicleOptions)`, `Source/ChronicleClient.ts:58`.
+
+**Connecting is implicit and lazy.** There is no `connect()`. The constructor
+starts a health-check watchdog and kicks off artifact discovery; the actual
+connect happens on the first `getEventStore`/`getEventStores` through an internal
+`ensureConnected()`. `getEventStore` also *creates* the store if it does not
+exist — it calls `ensureEventStore` (`Source/ChronicleClient.ts:135`).
+
+`dispose()` is **synchronous** (`Source/ChronicleClient.ts:193`), not
+`Symbol.dispose` or `Symbol.asyncDispose`. After disposal every call throws.
+
+### Options
+
+`ChronicleOptions` has a **private constructor**
+(`Source/ChronicleOptions.ts:67`); use a static factory:
+
+- `ChronicleOptions.fromConnectionString(connectionString, options?)` — `:92`
+- `ChronicleOptions.development(options?)` — `:116`
+
+The optional bag accepts `clientArtifactsProvider`, `discoveryPatterns`, and
+`defaultSinkTypeId`. `defaultSinkTypeId` defaults to `WellKnownSinks.MongoDB`
+(`:84`).
+
+> `programIdentifier`, `softwareVersion`, and `softwareCommit` exist on the type
+> (`:69-71`) but **neither public factory forwards them**, so they cannot be set.
+> Do not write guidance that configures them.
+
+### The connection string
+
+Schemes `chronicle://` and `chronicle+srv://`, default port `35000`
+(`Source/connection/ChronicleConnectionString.ts`). Query parameters: `apiKey`,
+`disableTls`, `skipTlsValidation`, `certificatePath`, `certificatePassword`,
+`loadBalancer`, `srvNameServer`.
+
+Two facts to carry into production guidance:
+
+- **`skipTlsValidation` defaults to `true`.** TLS is on but the certificate chain
+  is not validated, because a development kernel serves a self-signed
+  certificate. Set `?skipTlsValidation=false` against a real server.
+- **A connection string with no credentials silently falls back to the
+  development client credentials** (`Source/connection/ChronicleConnection.ts`).
+  An anonymous-looking connection string is not anonymous; it is
+  `chronicle-dev-client`.
+
+> **There is no `./connection` subpath export.** `ChronicleConnectionString`,
+> `ChronicleConnectionStringBuilder`, `AuthenticationMode`, and `LoadBalancerMode`
+> are unreachable from the public entry points — `Source/index.ts` never
+> re-exports them and `Source/package.json`'s `exports` map has no
+> `"./connection"` key. **Application code passes a connection *string*.** Do not
+> write an example that imports a connection-string type.
+
+The subpath exports that do exist: `.`, `./events`, `./eventSequences`,
+`./eventStoreSubscriptions`, `./compliance`, `./reactors`, `./reducers`,
+`./seeding`, `./readModels`, `./projections`, `./jobs`, `./webhooks`,
+`./externalServices`, `./identities`, `./observation`, `./sinks`, `./schemas`,
+`./types`, `./artifacts`, `./identity`, `./auditing`, `./correlation`,
+`./transactions`.
+
+## Event types
+
+```typescript
+import { eventType } from '@cratis/chronicle';
+
+@eventType()
+export class <EventName> {
+    constructor(readonly <property>: <Type> = <default>) {}
+}
+```
+
+Seven overloads — `Source/events/eventTypeDecorator.ts:54-60`:
+
+```typescript
+export function eventType(): ClassDecorator;
+export function eventType(id: string): ClassDecorator;
+export function eventType(id: string, generation: number): ClassDecorator;
+export function eventType(id: string, generation: number, tombstone: boolean): ClassDecorator;
+export function eventType(generation: number): ClassDecorator;
+export function eventType(generation: number, tombstone: boolean): ClassDecorator;
+export function eventType(tombstone: boolean): ClassDecorator;
+```
+
+**The event type id defaults to the class name** — `new EventTypeId(id || constructor.name)`
+at `:91`. Two classes with the same name in different modules collide on the wire.
+
+**Give constructor parameters default values.** Member discovery walks explicit
+`@field` declarations from `@cratis/fundamentals` first, then tracked properties,
+then the properties present on a *default-constructed* instance, then
+`design:paramtypes` — `Source/types/TypeIntrospector.ts:52-60`, with the reason
+spelled out at `:40-48`: **esbuild and tsx do not emit `design:type` or
+`design:paramtypes`**. Under `tsx`, a class whose constructor parameters have no
+defaults and no `@field` decorators produces no members and an empty schema. Every
+sample event carries defaults for exactly this reason.
+
+Tag an event type at declaration with `@tag(...)` / `@tags(...)` —
+`Source/events/tagDecorator.ts:30`, `:42`.
+
+## Appending
+
+`IEventLog` is an empty extension of `IEventSequence`
+(`Source/eventSequences/IEventLog.ts:10`); the surface is on `IEventSequence`:
+
+```typescript
+append(eventSourceId: string, event: object, options?: AppendOptions): Promise<AppendResult>;               // :44
+appendMany(eventSourceId: string, events: object[], options?: AppendOptions): Promise<AppendResult[]>;       // :53
+appendMany(events: EventForEventSourceId[], options?: AppendOptions): Promise<AppendResult[]>;               // :61
+```
+
+```typescript
+const result = await store.eventLog.append('<event-source-id>', new <EventName>('<value>'));
+if (!result.isSuccess) {
+    // result.constraintViolations, result.concurrencyViolation, result.errors
+}
+```
+
+- **The event source id is a plain `string`.** There is no `EventSourceId` value
+  type at this boundary.
+- `AppendResult` — `Source/eventSequences/AppendResult.ts:15-38`: `sequenceNumber`,
+  `constraintViolations`, `concurrencyViolation?`, `errors`, `isSuccess`, and
+  `waitForCompletion(timeoutMs?)` which defaults to 5000 ms.
+- **`sequenceNumber` wraps a `bigint`.** Read it as `result.sequenceNumber.value`.
+  `EventContext.sequenceNumber` is a `bigint` too.
+- `AppendOptions` — `Source/eventSequences/AppendOptions.ts`: `correlationId?`,
+  `eventSourceId?`, `concurrencyScope?`, `concurrencyScopes?`, and **`tags?`**
+  (`:22-29`, new in `4.0.0`).
+
+> **Single `append()` cannot target a stream or a subject.** It hardcodes
+> `EventSourceType: 'Default'`, `EventStreamType: 'Default'`,
+> `EventStreamId: eventSourceId`, and `Subject: eventSourceId`
+> (`Source/eventSequences/EventSequence.ts:100-119`). Only `tags` became a real
+> option in `4.0.0` (`:117`). To target a different stream or subject, use the
+> `EventForEventSourceId[]` overload, whose entries carry `eventStreamType`,
+> `eventStreamId`, `eventSourceType`, `subject`, and `tags`.
+
+Correlation id, identity, and the causation chain are picked up from the ambient
+module-level managers (`identityProvider`, `causationManager`,
+`correlationIdManager`) — you do not pass them.
+
+Several appends as one unit:
+
+```typescript
+const unitOfWork = store.unitOfWorkManager.begin();
+await store.eventLog.transactional.append('<id>', new <EventName>('<value>'));
+await unitOfWork.commit();
+```
+
+`ITransactionalEventSequence` returns `Promise<void>`, not an `AppendResult`;
+results are on the unit of work.
+
+## Observing
+
+### Handlers are found by camelCase method name
+
+This is the defining convention of this client, and it is **not** the parameter
+type. `Source/reactors/Reactors.ts:378-381` computes the method name from the
+event class name and looks it up on the prototype:
+
+```typescript
+const className = (eventTypeClass as Function).name;
+const methodName = className.charAt(0).toLowerCase() + className.slice(1);
+
+if (typeof proto[methodName] === 'function') { /* it is a handler */ }
+```
+
+Reducers do the same (`Source/reducers/Reducers.ts:454-460`). A handler whose
+method name does not match is simply never called — **there is no error**.
+
+> The docstring at `Source/reactors/reactor.ts:28-29` claims dispatch is by the
+> first parameter's type. **It is wrong**, and it is still wrong at `4.0.0`. The
+> code is the authority; so are the client snippets under `Documentation/`, which
+> state the name rule explicitly.
+
+```typescript
+import { reactor } from '@cratis/chronicle/reactors';
+import { EventContext, EventForEventSourceId } from '@cratis/chronicle';
+
+@reactor()
+export class <ReactorName> {
+    async <eventName>(event: <EventName>, context: EventContext): Promise<EventForEventSourceId> {
+        return {
+            eventSourceId: '<other-event-source-id>',
+            event: new <SideEffectEvent>(context.eventSourceId)
+        };
+    }
+}
+```
+
+A returned event, array, or `EventForEventSourceId` is appended as a side effect;
+a failed side-effect append fails the partition.
+
+> **The handler receives `JSON.parse(event.Content)` — a plain object, not an
+> instance of your event class** (`Source/reactors/Reactors.ts:297`, `:320`;
+> `Source/reducers/Reducers.ts:377`). `instanceof` checks and methods on the event
+> class do not work. Read properties only.
+
+`@reducer(id?, eventSequenceId?, readModel?, isActive?)` —
+`Source/reducers/reducer.ts:58`. Passing `readModel` also registers that type as a
+read model. **The reducer handler takes three arguments at `4.0.0`** —
+`reducerInstance[methodName](content, currentState, context)`
+(`Source/reducers/Reducers.ts:400`). The third is optional by arity, and a handler
+may be sync or async.
+
+Restrict an observer to tagged events with `@filterEventsByTag(value)` —
+`Source/events/filterEventsByTagDecorator.ts:36`.
+
+### Read models and projections
+
+`store.readModels` — `Source/readModels/IReadModels.ts`: `getInstanceById(type, key, sessionId?)`
+(`:38`), `getInstances(type, eventCount?)` (`:46`), `getSnapshotsById` (`:54`),
+`watch(type): AsyncIterable<ReadModelChangeset<T>>` (`:61`), plus `materialized`
+for paged access.
+
+Two projection styles:
+
+- **Model-bound** — decorators on the read model, from
+  `@cratis/chronicle/projections`: `fromEvent`, `fromEvery`, `fromAll`, `setFrom`,
+  `setFromContext`, `setValue`, `join`, `addFrom`, `subtractFrom`, `increment`,
+  `decrement`, `count`, `childrenFrom`, `nested`, `clearWith`, `removedWith`,
+  `removedWithJoin`, `noAutoMap`, `notRewindable`, `passive`.
+- **Declarative** — `@projection(id?, readModelType?, eventSequenceId?)` on a class
+  implementing `IProjectionFor<TReadModel>` with
+  `define(builder: IProjectionBuilderFor<TReadModel>): void`.
+
+Constraints are `@constraint()` on a class implementing `IConstraint` with a
+`define(builder)`; the builder gives `unique(...)`, `uniqueFor(...)`,
+`perEventSourceType`, `perEventStreamType`, `perEventStreamId`. **There are no
+model-bound constraint decorators in this client** — the class-plus-builder form
+is the only one.
+
+## Discovery is a runtime file glob — this is the biggest difference
+
+`ChronicleOptions.discoveryPatterns` defaults to
+`['**/*.ts', '!**/*.d.ts', '!**/node_modules', '!**/dist', '!**/build', '!**/.git', '!**/.vscode', '!**/*.spec.ts', '!**/*.test.ts']`
+(`Source/ChronicleOptions.ts:73-83`), and the client `import()`s every matching
+file at construction time so that the decorators run. Registration is into a
+process-wide static map.
+
+Two consequences that decide whether an application works at all:
+
+1. **The default pattern matches `.ts`, not `.js`.** It works under a
+   TypeScript-capable runtime — the sample runs `tsx index.ts` — and a compiled
+   `dist/*.js` deployment discovers **nothing** unless `discoveryPatterns` is
+   overridden.
+2. **Decorators only register when their module is imported.** Side-effect imports
+   of event, reactor, reducer, and projection modules are load-bearing; the sample
+   does exactly this with a comment saying why.
+
+`EventStore.registerArtifacts()` registers event types first, then everything else
+in parallel, and re-runs for every cached event store on reconnect.
+
+## Lifecycle
+
+- A health-check watchdog runs `getVersionInfo` every 5 seconds and reconnects on
+  failure; the interval handle is `unref()`'d so it does not hold the process open.
+- Reconnect uses exponential backoff with jitter, capped at 30 seconds, rebuilding
+  the gRPC channel on every attempt.
+- **Keepalive registration is what keeps observers alive.** Losing it triggers a
+  full reconnect, because the kernel tears down the client's observers otherwise.
+- Failed operations are retried once after reconnecting, keyed on gRPC status
+  codes 4/13/14 plus a substring match over the error text.
+
+> **The client version reported to the kernel is a hardcoded `'1.0.0'`** with a
+> TODO — `Source/ChronicleClient.ts:429`, alongside `ClientType: 'TypeScript'`
+> (`:434`). The Chronicle 17 server-side compatibility check therefore sees a
+> placeholder from this client, and grepping `Source/` for `CheckCompatibility`,
+> `ProtocolVersion`, or descriptor-set handling finds nothing. **Do not tell
+> developers this client negotiates protocol compatibility** — it does not.
+
+## No dependency injection
+
+There is none, and none is planned in the source: no container integration, no
+`addChronicle`-style registration. Reactors, reducers, projections, constraints,
+and seeders are instantiated by the client itself, so **constructor injection does
+not work**. Use module-scope collaborators, as the shipped sample does.
+
+## Common pitfalls
+
+| Pitfall | Why it bites |
+| --- | --- |
+| Naming a reactor method after the handler's purpose | Dispatch is by the camelCase event class name; a mismatch is silently never called |
+| `instanceof` on the event inside a handler | It is a `JSON.parse`d plain object, not your class |
+| Event class with no default constructor values under `tsx` | No decorator metadata is emitted, so the schema comes out empty |
+| Two `@eventType()` classes sharing a class name | The id defaults to the class name and they collide |
+| Deploying compiled `dist/*.js` with default discovery | The default glob matches `**/*.ts`; nothing is discovered |
+| Omitting a side-effect import of an artifact module | Its decorator never runs, so it is never registered |
+| Forgetting `import 'reflect-metadata'` at the entry point | Decorators do not work at runtime |
+| Forgetting to install `@cratis/fundamentals` | It is a peer dependency and is not installed for you |
+| Importing `ChronicleConnectionString` | There is no `./connection` export; pass a string |
+| Expecting single `append()` to set a stream or subject | Those fields are hardcoded; use the `EventForEventSourceId[]` overload |
+| A connection string with no credentials | Silently falls back to the development client credentials |
+| Shipping the default TLS behavior | `skipTlsValidation` defaults to `true` |
+| Constructor-injecting a dependency into a reactor | There is no DI; the client constructs it |
+| Carrying a `3.x` example forward | Tags, the reducer context parameter, and two RPC names changed in `4.0.0` |
+| Reading `result.sequenceNumber` as a number | It is a `bigint` behind `.value` |
+
+## Verify
+
+- The installed version is the one you intended, taken from npm, and
+  `@cratis/fundamentals` is installed alongside it.
+- `reflect-metadata` is imported exactly once, at the entry point.
+- `experimentalDecorators` and `emitDecoratorMetadata` are both on.
+- Every event class either has `@field` declarations or default constructor
+  values, and its schema is non-empty at runtime.
+- `discoveryPatterns` matches the files that actually ship in the deployed
+  artifact.
+- Every reactor and reducer handler is named as the exact camelCase of its event
+  class, and an appended event demonstrably reaches it.
+- A production connection string carries credentials and `skipTlsValidation=false`.
+- `client.dispose()` runs on shutdown.
+- Lint, `tsc`, and the test suite are clean against the verified package version.

package/skills/cratis-chronicle-compliance/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-chronicle-compliance/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: cratis-chronicle-compliance
+description: Model personal data in Chronicle with [PII] and [Subject], and erase it through crypto-shredding with IPIIManager. Use when an event or read model carries data about a natural person, when a subject must be identified for erasure, when a right-to-erasure request must be executed, or when redacting a stored event. Do not use for authorization, authentication, secret handling, or generic data-protection policy.
+license: MIT
+---
+
+# Chronicle compliance and personal data
+
+Chronicle keeps events forever, so personal data cannot be deleted from the log.
+Chronicle protects it by encrypting each marked value under a key owned by the
+subject, and erases it by destroying that key. Decide the subject before you
+decide the event shape — the subject is what erasure operates on.
+
+## Verified product sources
+
+This skill is verified against this exact public release:
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Chronicle` | `16.45.3` | `Cratis.Chronicle.Compliance.GDPR`, `Cratis.Chronicle.SubjectAttribute`, `IEventSequence.Redact`, `IReadModels.Release` |
+| `Cratis.Chronicle.CodeAnalysis` | `16.45.3` | `CHR0026`, `CHR0034`, `CHR0035`, `CHR0043`, `CHR0046` |
+
+Reverify product sources before claiming support for another version.
+
+## Mark personal data with `[PII]`
+
+`Cratis.Chronicle.Compliance.GDPR.PIIAttribute` marks a value as personal data.
+It targets a class, a property, or a constructor parameter, and it is not
+repeatable.
+
+```csharp
+using Cratis.Chronicle.Compliance;
+using Cratis.Chronicle.Compliance.GDPR;
+
+[EventType]
+public record <PersonEventName>(
+    [property: PII] string <PersonalPropertyName>,
+    <NonPersonalType> <BusinessPropertyName>);
+```
+
+On a positional record the attribute must be written as `[property: PII]` or
+placed on the constructor parameter; Chronicle looks for it on the property, the
+property's declaring type, the property's own type, and the matching primary
+constructor parameter.
+
+Marking the concept type itself makes the value personal everywhere it appears,
+which is usually what you want for an email, a phone number, or a personal name:
+
+```csharp
+[PII]
+[ComplianceDetails("<why this value is collected and under what basis>")]
+public record <ConceptName>(string Value) : ConceptAs<string>(Value);
+```
+
+`PIIAttribute` accepts an optional `details` string, **but Chronicle never reads
+it.** The rationale that actually reaches the event schema comes from
+`Cratis.Chronicle.Compliance.ComplianceDetailsAttribute`. Write `[PII]` for the
+marker and `[ComplianceDetails("...")]` for the reason; do not write
+`[PII("reason")]` and expect the reason to be recorded.
+
+`PII` is the only compliance category Chronicle defines — there is exactly one
+well-known `ComplianceMetadataType`. Chronicle has no `[Redact]`, `[Erase]`,
+`[Anonymize]`, `[Encrypt]`, or `[NotAudited]` attribute; do not write one into
+an example. Redaction is an API call, not an annotation.
+
+Mark only genuinely personal values. Business metadata, identifiers of
+non-persons, and amounts stay unmarked — every marked value costs an encryption
+round trip and becomes unreadable the moment the subject is erased.
+
+## Decide the subject
+
+The subject is the natural person a value belongs to, and it is the unit of
+erasure. `Cratis.Chronicle.SubjectAttribute` marks the value that supplies it.
+The attribute is a pure marker with no arguments and targets a property or a
+constructor parameter.
+
+For an appended event, Chronicle uses the explicit subject when one is supplied
+and otherwise falls back to the event source id. That default is the shape you
+want: a person-per-stream model needs no `[Subject]` at all.
+
+```csharp
+[EventType]
+public record <PersonEventName>(
+    [property: Subject] <SubjectValueType> <SubjectPropertyName>,
+    [property: PII] string <PersonalPropertyName>);
+```
+
+Add `[Subject]` only when the person is **not** the event source — for example
+an event on an order stream that carries the customer's personal data. A
+reactor can supply the subject for its side-effect events by implementing
+`Cratis.Chronicle.Events.ICanProvideSubject`, whose single member is
+`Subject GetSubject()`.
+
+`Cratis.Chronicle.Subject` is `record Subject(string Value) : ConceptAs<string>`
+with a `NotSet` value, an `IsSet` test, and implicit conversion from `string`,
+`Guid`, and `EventSourceId`.
+
+For a read model instance, Chronicle resolves the subject from the `[Subject]`
+property that has a value, then the `[Subject]` constructor parameter, then a
+property named `Id`. A stored document carries one default subject; keep one
+person's personal data in one document rather than mixing several people into
+one row.
+
+### Do not put `[Subject]` or `[PII]` on the stream identity
+
+An `EventSourceId<T>`-derived value already is both the key and the compliance
+subject.
+
+- `[Key]` or `[Subject]` on it is redundant — analyzer **CHR0026** (warning).
+- `[PII]` on it is rejected — analyzer **CHR0034** (error), and at runtime
+  `Cratis.Chronicle.Compliance.GDPR.PIINotSupportedOnEventSourceId`.
+
+Chronicle cannot encrypt an event source id. When the natural identifier is
+itself sensitive, use a random surrogate stream id and carry the sensitive value
+as a `[PII]` property.
+
+### Reserved read-model property names
+
+Chronicle stamps `__subject` and `__subjects` onto stored read-model documents.
+Analyzer **CHR0035** (error) rejects a `[ReadModel]` that declares `_subject`,
+`__subject`, or `__subjects`. Rename the property.
+
+## Erase a subject
+
+`IEventStore.PII` exposes `Cratis.Chronicle.Compliance.GDPR.IPIIManager`:
+
+```csharp
+Task DeleteEncryptionKeyFor(EncryptionKeyIdentifier identifier);
+Task AllowNewEncryptionKeyFor(EncryptionKeyIdentifier identifier);
+```
+
+`EncryptionKeyIdentifier` is a `ConceptAs<string>` with implicit conversion from
+`string`, so the subject value can be passed directly:
+
+```csharp
+var eventStore = await chronicleClient.GetEventStore("<EventStoreName>");
+await eventStore.PII.DeleteEncryptionKeyFor("<subject-value>");
+```
+
+What this does and does not do:
+
+- It destroys the subject's key and records an **erasure fence** so a later
+  write cannot resurrect a key for that subject. The fence is monotonic and is
+  recorded before any key is deleted.
+- The events stay in the log. Their `[PII]` values remain as unreadable
+  ciphertext — this is crypto-shredding, not deletion.
+- Reading an erased value yields an **empty string** rather than an exception,
+  so queries and read models over an erased subject keep working. An erased
+  container value comes back as an empty object or array.
+- Appending a new `[PII]` value for an erased subject **fails** with
+  `EncryptionKeyErased`. It does not quietly mint a new key. Call
+  `AllowNewEncryptionKeyFor` deliberately if the subject must be re-enrolled.
+- A partially completed erasure throws `EncryptionKeyErasureIncomplete`, which
+  carries the individual failures. Treat it as unfinished and retry — the fence
+  is already in place, so retrying is safe.
+
+**Erasure is scoped to one namespace.** There is no cross-namespace erasure. In
+a multi-tenant deployment, an erasure request that spans tenants is one call per
+tenant namespace, and completing only some of them is an incomplete erasure.
+
+## Redact a stored event
+
+Erasure removes a subject's readability. Redaction removes a specific event's
+content. `Cratis.Chronicle.EventSequences.IEventSequence` exposes both forms:
+
+```csharp
+Task Redact(EventSequenceNumber sequenceNumber, RedactionReason reason);
+Task Redact(EventSourceId eventSourceId, RedactionReason reason, params Type[] clrEventTypes);
+```
+
+`RedactionReason` is a `ConceptAs<string>` with an `Unknown` value and implicit
+conversion from `string`. Chronicle records the redaction itself as an
+`EventRedacted` event, so the fact that a redaction happened stays auditable.
+
+Use redaction for content that should never have been appended. Use key erasure
+for a subject exercising a right to erasure. They are different mechanisms and
+one does not imply the other.
+
+## Read personal data back
+
+The kernel decrypts on the paths it owns, so projections and observers see plain
+values. When a read-model instance is fetched outside those paths, decrypt it
+explicitly through `Cratis.Chronicle.ReadModels.IReadModels`:
+
+```csharp
+Task<TReadModel> Release<TReadModel>(TReadModel instance);
+Task<IEnumerable<TReadModel>> Release<TReadModel>(IEnumerable<TReadModel> instances);
+```
+
+`Release` degrades quietly by design: it returns the instance unchanged when no
+subject can be derived, when the type carries no compliance metadata, or when
+decryption fails. It logs, it does not throw. Do not treat a value that came
+back looking encrypted as proof the data is intact — check the subject
+resolution first.
+
+The asymmetry is deliberate and worth knowing: **applying** compliance on append
+fails loudly, **releasing** it on read fails quietly.
+
+## Setup
+
+An ASP.NET Core host that calls `builder.AddCratisChronicle()` needs no
+compliance setup — `AddCompliance()` is already called for you, and the raw
+client path discovers the metadata providers by convention. The developer-facing
+requirement is only to annotate the types.
+
+Key storage is a hosting decision, not an application one. Chronicle ships
+MongoDB (the default), SQL, in-memory, HashiCorp Vault, and Azure Key Vault key
+storage, configured under `Cratis:Chronicle:Compliance:Encryption`.
+
+> **Operational trap.** Switching to a dedicated compliance key store without
+> setting `MigrateFromDefaultStorage` leaves every existing key unreachable.
+> Every `[PII]` value then reads back as an empty string, with no exception and
+> no log — byte-for-byte indistinguishable from a completed erasure. Verify the
+> migration flag before switching stores, and confirm a known subject still
+> reads after the switch.
+
+## Modeling rules that follow from erasure
+
+- Prefer **one subject per event stream** for person-level personal data. The
+  default subject is then correct everywhere and erasure is one call.
+- A key redirected away from the event's own stream can carry a `[PII]` value
+  across a compliance subject boundary — analyzers **CHR0043** and **CHR0046**
+  (warnings) flag that shape. Treat the warning as a modeling question, not
+  noise: which person owns the resulting document?
+- Bearer tokens, magic links, and signed URLs are secrets, not durable facts.
+  Store a keyed hash or an opaque reference. Chronicle has no attribute that
+  withholds a secret from the log.
+- If a subject boundary cannot be made person-level without changing product
+  behavior, stop and surface the trade-off before implementing.
+
+## Verify
+
+- Every value that identifies or describes a natural person carries `[PII]`;
+  business metadata does not.
+- Rationale is written with `[ComplianceDetails]`, not with a `[PII]` argument.
+- The subject is explicit wherever the person is not the event source, and
+  absent where the event source already is the person.
+- No `[Key]`, `[Subject]`, or `[PII]` sits on an `EventSourceId<T>` value.
+- No read model declares `_subject`, `__subject`, or `__subjects`.
+- One stored read-model document holds one person's personal data.
+- Erasure is executed per namespace, and an incomplete erasure is retried rather
+  than reported as done.
+- Reads that must show personal data outside the kernel's own paths call
+  `Release`, and an unchanged instance is investigated rather than assumed.
+- The build is clean with zero `CHR00xx` diagnostics outstanding, and the
+  relevant specifications pass against the verified package version.

package/skills/cratis-chronicle-event-constraints/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.