@cratis/chronicle 3.1.0 → 4.0.0

package/schemas/JsonSchema.ts

@@ -1,6 +1,21 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+/**
+ * Represents a single compliance classification recorded on a schema node.
+ */
+export interface ComplianceSchemaMetadata {
+    /**
+     * The type of compliance metadata (e.g. 'PII').
+     */
+    metadataType: string;
+
+    /**
+     * Any additional details - can be empty.
+     */
+    details: string;
+}
+
 /**
  * Represents a JSON Schema object.
  */
@@ -15,4 +30,5 @@ export type JsonSchema = {
     items?: JsonSchema;
     additionalProperties?: boolean | JsonSchema;
     enum?: Array<string | number | boolean | null>;
+    compliance?: ComplianceSchemaMetadata[];
 };

package/schemas/JsonSchemaGenerator.spec.ts

@@ -0,0 +1,195 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { ConceptAs, field } from '@cratis/fundamentals';
+import { describe, expect, it } from 'vitest';
+import { pii } from '../compliance/pii';
+import { eventType, getEventTypeJsonSchemaFor } from '../events/eventTypeDecorator';
+import { getReadModelMetadata, readModel } from '../readModels/readModel';
+import { JsonSchema } from './JsonSchema';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support - they exercise exactly
+// the same decorator functions and metadata storage that `@decorator` syntax would invoke.
+//
+// Order matters here in a way it would not for a real `@decorator` stack: class decorators
+// apply bottom-to-top, so `pii()` must run - and therefore be called - before `readModel()`/
+// `eventType()` so the compliance metadata already exists when the schema is generated.
+
+function schemaFor(target: Function): JsonSchema {
+    return getReadModelMetadata(target)!.schema;
+}
+
+describe('JsonSchemaGenerator', () => {
+    describe('when a class is marked @pii() at the class level', () => {
+        class PersonProfile {
+            name = '';
+            email = '';
+        }
+        pii()(PersonProfile);
+        readModel()(PersonProfile);
+
+        const schema = schemaFor(PersonProfile);
+
+        it('should mark every one of its own properties as PII', () => {
+            expect(schema.properties!.name.compliance).toEqual([{ metadataType: 'PII', details: '' }]);
+            expect(schema.properties!.email.compliance).toEqual([{ metadataType: 'PII', details: '' }]);
+        });
+    });
+
+    describe('when only a single property is marked @pii()', () => {
+        class Contact {
+            name = '';
+            ssn = '';
+        }
+        pii('Social security number')(Contact.prototype, 'ssn');
+        readModel()(Contact);
+
+        const schema = schemaFor(Contact);
+
+        it('should mark the decorated property as PII', () => {
+            expect(schema.properties!.ssn.compliance).toEqual([{ metadataType: 'PII', details: 'Social security number' }]);
+        });
+
+        it('should leave the other property without compliance metadata', () => {
+            expect(schema.properties!.name.compliance).toBeUndefined();
+        });
+    });
+
+    describe('when a property is typed as a ConceptAs<T> marked @pii()', () => {
+        class EmailAddress extends ConceptAs<string> {
+            constructor(value: string) {
+                super(value);
+            }
+        }
+        pii('Email address')(EmailAddress);
+
+        describe('on a read model', () => {
+            class Customer {
+                email: EmailAddress = new EmailAddress('');
+            }
+            readModel()(Customer);
+
+            const schema = schemaFor(Customer);
+
+            it('should mark the concept-typed property as PII', () => {
+                expect(schema.properties!.email.compliance).toEqual([{ metadataType: 'PII', details: 'Email address' }]);
+            });
+
+            it('should describe the concept as its underlying primitive type', () => {
+                expect(schema.properties!.email.type).toBe('string');
+            });
+        });
+
+        describe('on an event', () => {
+            class CustomerRegistered {
+                email: EmailAddress = new EmailAddress('');
+            }
+            eventType()(CustomerRegistered);
+
+            const schema = getEventTypeJsonSchemaFor(CustomerRegistered);
+
+            it('should mark the concept-typed property as PII', () => {
+                expect(schema.properties!.email.compliance).toEqual([{ metadataType: 'PII', details: 'Email address' }]);
+            });
+        });
+    });
+
+    describe('when a property-level @pii() combines with a class-level @pii()', () => {
+        class Employee {
+            name = '';
+            email = '';
+        }
+        pii()(Employee.prototype, 'name');
+        pii('Every field on this record is personal')(Employee);
+        readModel()(Employee);
+
+        const schema = schemaFor(Employee);
+
+        it('should not duplicate the compliance entry on the property carrying both markers', () => {
+            expect(schema.properties!.name.compliance).toHaveLength(1);
+        });
+
+        it('should keep the property-level details when both sources apply', () => {
+            expect(schema.properties!.name.compliance).toEqual([{ metadataType: 'PII', details: '' }]);
+        });
+
+        it('should still mark the property that only carries the class-level marker', () => {
+            expect(schema.properties!.email.compliance).toEqual([{ metadataType: 'PII', details: 'Every field on this record is personal' }]);
+        });
+    });
+
+    describe('when a property typed as a nested composite value object is marked @pii()', () => {
+        class ContactDetails {
+            phone = '';
+            fax = '';
+        }
+        class Vendor {
+            contact: ContactDetails = new ContactDetails();
+        }
+        pii('Vendor contact information')(Vendor.prototype, 'contact');
+        readModel()(Vendor);
+
+        const schema = schemaFor(Vendor);
+
+        it('should push the compliance metadata down onto every leaf property', () => {
+            expect(schema.properties!.contact.properties!.phone.compliance).toEqual([{ metadataType: 'PII', details: 'Vendor contact information' }]);
+            expect(schema.properties!.contact.properties!.fax.compliance).toEqual([{ metadataType: 'PII', details: 'Vendor contact information' }]);
+        });
+
+        it('should not leave compliance metadata on the container node itself', () => {
+            expect(schema.properties!.contact.compliance).toBeUndefined();
+        });
+    });
+
+    describe('when an array element is a ConceptAs<T> marked @pii()', () => {
+        class RequirementCode extends ConceptAs<string> {
+            constructor(value: string) {
+                super(value);
+            }
+        }
+        pii('Sensitive requirement code')(RequirementCode);
+
+        class Contract {
+            codes: RequirementCode[] = [];
+        }
+        field(Array, { enumerable: true, genericArguments: [RequirementCode] })(Contract.prototype, 'codes');
+        readModel()(Contract);
+
+        const schema = schemaFor(Contract);
+
+        it('should describe the property as an array', () => {
+            expect(schema.properties!.codes.type).toBe('array');
+        });
+
+        it('should carry the element concept compliance metadata onto the item schema', () => {
+            expect(schema.properties!.codes.items!.compliance).toEqual([{ metadataType: 'PII', details: 'Sensitive requirement code' }]);
+        });
+
+        it('should describe the item as the concept underlying primitive type', () => {
+            expect(schema.properties!.codes.items!.type).toBe('string');
+        });
+
+        it('should not leave coarse compliance metadata on the array container itself', () => {
+            expect(schema.properties!.codes.compliance).toBeUndefined();
+        });
+    });
+
+    describe('when an array element is not a ConceptAs<T>', () => {
+        class PlainItem {
+            value = '';
+        }
+        class Basket {
+            items: PlainItem[] = [];
+        }
+        field(Array, { enumerable: true, genericArguments: [PlainItem] })(Basket.prototype, 'items');
+        readModel()(Basket);
+
+        const schema = schemaFor(Basket);
+
+        it('should fall back to an opaque object item schema', () => {
+            expect(schema.properties!.items.items).toEqual({ type: 'object' });
+        });
+    });
+});

package/schemas/JsonSchemaGenerator.ts

@@ -2,9 +2,10 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import 'reflect-metadata';
-import { ConceptAs, Guid } from '@cratis/fundamentals';
-import { JsonSchema } from './JsonSchema';
+import { ConceptAs, Constructor, Fields, Guid } from '@cratis/fundamentals';
+import { ComplianceSchemaMetadata, JsonSchema } from './JsonSchema';
 import { TypeIntrospector } from '../types';
+import { ComplianceMetadata } from '../compliance/ComplianceMetadata';
 import { ComplianceMetadataResolver } from '../compliance/ComplianceMetadataResolver';
 
 /**
@@ -48,12 +49,17 @@ export class JsonSchemaGenerator {
         const prototype = target.prototype;
 
         for (const [memberName, memberType] of membersToUse.entries()) {
-            const propertySchema = this.mapRuntimeTypeToSchema(memberType);
+            const propertySchema = this.mapRuntimeTypeToSchema(memberType, target, memberName);
             // Only include properties whose type was resolved. An empty schema ({}) means
             // the runtime type was unavailable (e.g. esbuild/tsx omits design:paramtypes).
             if (Object.keys(propertySchema).length > 0) {
-                // Add compliance metadata to property schema if present (both property and type-level)
-                this.addComplianceMetadata(propertySchema, prototype, memberName, memberType);
+                // An array of concept elements resolves and applies its own item-level compliance
+                // inside mapRuntimeTypeToSchema - the general property/type/declaring-class walk
+                // below is skipped for it, mirroring the C# generator's enumerable-of-concept branch.
+                if (!this.isConceptArrayMember(target, memberName, memberType)) {
+                    const metadata = this.collectComplianceMetadata(prototype, memberName, memberType);
+                    this.addComplianceMetadataToSchema(propertySchema, metadata);
+                }
                 schemaProperties[memberName] = propertySchema;
             }
         }
@@ -72,7 +78,7 @@ export class JsonSchemaGenerator {
         };
     }
 
-    private static mapRuntimeTypeToSchema(runtimeType: Function | undefined): JsonSchema {
+    private static mapRuntimeTypeToSchema(runtimeType: Function | undefined, declaringType?: Function, propertyName?: string): JsonSchema {
         const knownTypeFormat = this.getKnownTypeFormat(runtimeType);
         if (knownTypeFormat) {
             return knownTypeFormat;
@@ -91,7 +97,7 @@ export class JsonSchemaGenerator {
         }
 
         if (runtimeType === Array) {
-            return { type: 'array', items: { type: 'object' } };
+            return this.mapArrayTypeToSchema(declaringType, propertyName);
         }
 
         if (!runtimeType) {
@@ -115,6 +121,63 @@ export class JsonSchemaGenerator {
         return { type: 'object' };
     }
 
+    /**
+     * Maps an array-typed member to a schema, resolving the element type from a
+     * `@field(Array, { genericArguments: [ItemType] })` declaration when present.
+     * @param declaringType - The class constructor that declares the array property.
+     * @param propertyName - The array property name.
+     * @returns The array schema, with the element's own compliance metadata carried onto `items` when the element is a PII concept.
+     */
+    private static mapArrayTypeToSchema(declaringType: Function | undefined, propertyName: string | undefined): JsonSchema {
+        const elementType = this.getArrayElementType(declaringType, propertyName);
+
+        // An array whose element is a ConceptAs<T> loses its classification the moment it is put in
+        // a list unless the element concept's own compliance metadata is carried onto the item schema -
+        // a value that would be encrypted as a scalar would otherwise be persisted in the clear as a
+        // list element. Mirrors the C# generator's explicit enumerable-of-concept branch.
+        if (elementType && this.isConceptAs(elementType)) {
+            const itemSchema = this.mapRuntimeTypeToSchema(elementType);
+            const metadata = ComplianceMetadataResolver.getMetadataForType(elementType);
+            this.addComplianceMetadataToSchema(itemSchema, metadata);
+            return { type: 'array', items: itemSchema };
+        }
+
+        return { type: 'array', items: { type: 'object' } };
+    }
+
+    /**
+     * Resolves the element type of an array property from its `@field(Array, { genericArguments: [...] })`
+     * declaration. TypeScript erases generic type arguments at runtime, so without an explicit
+     * `@field` declaration the element type cannot be recovered.
+     * @param declaringType - The class constructor that declares the array property.
+     * @param propertyName - The array property name.
+     * @returns The element type constructor, or undefined when it cannot be resolved.
+     */
+    private static getArrayElementType(declaringType: Function | undefined, propertyName: string | undefined): Function | undefined {
+        if (!declaringType || !propertyName) {
+            return undefined;
+        }
+
+        const field = Fields.getFieldsForType(declaringType as Constructor).find(candidate => candidate.name === propertyName);
+        return field?.genericArguments?.[0];
+    }
+
+    /**
+     * Checks whether a member is an array whose element type is a ConceptAs<T>.
+     * @param declaringType - The class constructor that declares the property.
+     * @param propertyName - The property name.
+     * @param runtimeType - The member's reflected runtime type.
+     * @returns True when the member is an array of concept elements; false otherwise.
+     */
+    private static isConceptArrayMember(declaringType: Function, propertyName: string, runtimeType: Function | undefined): boolean {
+        if (runtimeType !== Array) {
+            return false;
+        }
+
+        const elementType = this.getArrayElementType(declaringType, propertyName);
+        return elementType !== undefined && this.isConceptAs(elementType);
+    }
+
     private static isConceptAs(runtimeType: Function): boolean {
         let current: Function | null = runtimeType;
         while (current && current !== Function.prototype) {
@@ -150,35 +213,90 @@ export class JsonSchemaGenerator {
     }
 
     /**
-     * Adds compliance metadata to a property schema if the property has compliance decorators.
-     * Also checks if the property's type itself is marked as PII (e.g., ConceptAs types).
-     * @param schema - The property schema to add compliance metadata to.
-     * @param target - The class prototype.
+     * Collects compliance metadata for a property from every source C# resolves PII from: the
+     * property itself, its declaring class, and its own type (the concept case).
+     * @param target - The class prototype the property is declared on.
      * @param propertyKey - The property name.
+     * @param propertyType - The property's runtime type, when resolved.
+     * @returns The collected compliance metadata, in property → declaring-class → type order.
      */
-    private static addComplianceMetadata(schema: JsonSchema, target: object, propertyKey: string, propertyType?: Function): void {
-        const complianceArray: Array<{ metadataType: string; details: string }> = [];
+    private static collectComplianceMetadata(target: object, propertyKey: string, propertyType?: Function): ComplianceMetadata[] {
+        const metadata: ComplianceMetadata[] = [];
 
-        // Check for property-level compliance decorators
+        // Property-level compliance decorator.
         if (ComplianceMetadataResolver.hasMetadataFor(target, propertyKey)) {
-            const propertyMetadata = ComplianceMetadataResolver.getMetadataFor(target, propertyKey);
-            complianceArray.push(...propertyMetadata.map(metadata => ({
-                metadataType: metadata.metadataType.value.toString(),
-                details: metadata.details
-            })));
+            metadata.push(...ComplianceMetadataResolver.getMetadataFor(target, propertyKey));
+        }
+
+        // Declaring class-level compliance decorator - a class-level @pii() marks every one of
+        // its own properties, the same way C#'s PIIMetadataProvider checks property.DeclaringType.
+        const declaringClass = (target as { constructor?: Function }).constructor;
+        if (declaringClass) {
+            metadata.push(...ComplianceMetadataResolver.getMetadataForType(declaringClass));
         }
 
-        // Check for type-level compliance decorators (e.g., @pii on ConceptAs)
+        // Type-level compliance decorator on the property's own type (e.g., @pii on a ConceptAs).
         if (propertyType) {
-            const typeMetadata = ComplianceMetadataResolver.getMetadataForType(propertyType);
-            complianceArray.push(...typeMetadata.map(metadata => ({
-                metadataType: metadata.metadataType.value.toString(),
-                details: metadata.details
-            })));
+            metadata.push(...ComplianceMetadataResolver.getMetadataForType(propertyType));
+        }
+
+        return metadata;
+    }
+
+    /**
+     * Adds compliance metadata to a schema node, descending into an object's properties so that
+     * the metadata always lands on the leaves that actually hold a value.
+     * @param schema - The schema node to add to.
+     * @param metadata - The compliance metadata to add.
+     * @remarks
+     * A compliance marker can be declared on something that is not a single value: a `@pii()` on a
+     * composite value-object type, or on a property whose type is such an object. Compliance is
+     * applied per value, so leaving the marker on the container would make Chronicle hand the whole
+     * JSON object to the value handler and store one opaque ciphertext string where the schema still
+     * says "object". Releasing that gives back a string, not an object, and the read model then
+     * fails to materialize. Pushing the metadata down to every leaf keeps encryption symmetric with
+     * the release walk, keeps each value independently encrypted, and preserves the document shape.
+     *
+     * An array-typed node is deliberately left as a container: coarse compliance on a whole
+     * collection is an established, separately handled behavior (the collection is blob-encrypted
+     * and its shape restored on release).
+     */
+    private static addComplianceMetadataToSchema(schema: JsonSchema, metadata: ComplianceMetadata[]): void {
+        if (metadata.length === 0) {
+            return;
         }
 
-        if (complianceArray.length > 0) {
-            (schema as Record<string, unknown>).compliance = complianceArray;
+        if (schema.properties && Object.keys(schema.properties).length > 0) {
+            for (const propertySchema of Object.values(schema.properties)) {
+                this.addComplianceMetadataToSchema(propertySchema, metadata);
+            }
+            return;
         }
+
+        const compliance = schema.compliance ?? [];
+        for (const item of metadata) {
+            const metadataType = item.metadataType.value.toString();
+            if (!this.hasComplianceMetadataOfType(compliance, metadataType)) {
+                compliance.push({ metadataType, details: item.details });
+            }
+        }
+
+        if (compliance.length > 0) {
+            schema.compliance = compliance;
+        }
+    }
+
+    /**
+     * Checks whether a compliance array already carries metadata of a given type.
+     * @param compliance - The compliance array to check.
+     * @param metadataType - The metadata type to look for.
+     * @returns True when the metadata type is already present, false if not.
+     * @remarks
+     * A leaf can be reached by more than one marker — for example a `@pii()` concept inside a value
+     * object whose type is itself marked `@pii()`. Recording the same metadata type twice adds
+     * nothing and makes the generated schema noisier to read and to diff.
+     */
+    private static hasComplianceMetadataOfType(compliance: ComplianceSchemaMetadata[], metadataType: string): boolean {
+        return compliance.some(item => item.metadataType === metadataType);
     }
 }

package/schemas/index.ts

@@ -3,4 +3,4 @@
 
 export { JsonSchemaGenerator } from './JsonSchemaGenerator';
 export { jsonSchemaProperty, getTrackedJsonSchemaProperties } from './jsonSchemaProperty';
-export type { JsonSchema } from './JsonSchema';
+export type { ComplianceSchemaMetadata, JsonSchema } from './JsonSchema';

package/seeding/EventSeeding.ts

@@ -6,6 +6,7 @@ import { IClientArtifactsProvider } from '../artifacts';
 import { ChronicleConnection } from '../connection';
 import { EventStoreNamespaceName } from '../EventStoreNamespaceName';
 import { getEventTypeFor } from '../events/eventTypeDecorator';
+import { getTagsFor } from '../events/tagDecorator';
 import { ICanSeedEvents } from './ICanSeedEvents';
 import { IEventSeeding } from './IEventSeeding';
 import { IEventSeedingBuilder } from './IEventSeedingBuilder';
@@ -104,11 +105,12 @@ export class EventSeeding implements IEventSeeding {
     private addEntries<TEvent extends object>(eventSourceId: string, events: Iterable<TEvent>, isGlobal: boolean, targetNamespace: string): void {
         for (const event of events) {
             const eventType = getEventTypeFor(event.constructor as Function);
+            const tags = getTagsFor(event.constructor as Function).map(t => t.value);
             this._entries.push({
                 eventSourceId,
                 eventTypeId: eventType.id.value,
                 content: JSON.stringify(event),
-                tags: [],
+                tags,
                 isGlobal,
                 targetNamespace
             });