@cratis/chronicle 6.32.1 → 6.33.0

package/readModels/ReadModels.ts

@@ -19,7 +19,7 @@ import { hasFromEventMetadata } from '../projections/modelBound/fromEvent.js';
 import { hasModelBoundProperties } from '../types/TypeDiscoverer.js';
 import { isPassive } from '../projections/modelBound/passive.js';
 import { getReducerMetadata } from '../reducers/reducer.js';
-import { JsonSchemaGenerator } from '../schemas/index.js';
+import { JsonSchemaGenerator, type JsonSchema } from '../schemas/index.js';
 import { WellKnownSinks } from '../sinks/index.js';
 import { getReadModelMetadata, getReadModelId } from './readModel.js';
 import { buildReadModelDefinition } from './buildReadModelDefinition.js';
@@ -238,6 +238,123 @@ export class ReadModels implements IReadModels {
         return Promise.all(releasePromises);
     }
 
+    /** @inheritdoc */
+    async releaseDocument<TReadModel>(readModelType: Constructor<TReadModel>, document: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>> {
+        const readModel = this.resolveReadModel(readModelType);
+        const schema = JSON.parse(this.getReadModelSchema(readModelType, readModel.identifier)) as JsonSchema;
+        const properties = schema.properties ?? {};
+        const stored = this.copyStoredDocument(document);
+        const storedDefaultSubject = stored.__subject;
+        const defaultSubject = this.isDocumentSubject(storedDefaultSubject) ? storedDefaultSubject : undefined;
+        const storedSubjects = this.isDocumentObject(stored.__subjects) ? stored.__subjects : {};
+        const subjects = new Map<string, string>();
+
+        if (storedDefaultSubject !== undefined && storedDefaultSubject !== null && typeof storedDefaultSubject !== 'string') {
+            throw new Error('Stored read model document has an invalid default subject.');
+        }
+        for (const [property, subject] of Object.entries(storedSubjects)) {
+            if (property === '__subject' || property === '__subjects') {
+                throw new Error('Stored read model document has an unknown subject property.');
+            }
+            // The kernel's JSON subject map ignores null/empty strings, but rejects non-string values.
+            if (subject !== null && typeof subject !== 'string') {
+                throw new Error('Stored read model document has an invalid property subject.');
+            }
+            // Cleared or removed properties can leave stale mappings in stored documents.
+            if (!Object.hasOwn(stored, property)) {
+                continue;
+            }
+            if (!Object.hasOwn(properties, property)) {
+                throw new Error('Stored read model document has an unknown subject property.');
+            }
+            if (this.isDocumentSubject(subject)) {
+                subjects.set(property, subject);
+            }
+        }
+
+        const groups = new Map<string, string[]>();
+        const releasedEntries: [string, unknown][] = [];
+        for (const [property, value] of Object.entries(stored)) {
+            // Only schema-declared data is returned, never storage bookkeeping.
+            if (property === '__subject' || property === '__subjects' || !Object.hasOwn(properties, property)) {
+                continue;
+            }
+            const subject = subjects.get(property) ?? defaultSubject;
+            if (subject === undefined) {
+                releasedEntries.push([property, value]);
+                continue;
+            }
+            const group = groups.get(subject) ?? [];
+            group.push(property);
+            groups.set(subject, group);
+        }
+
+        for (const [subject, propertyNames] of groups) {
+            const payload = Object.fromEntries(propertyNames.map(property => [property, stored[property]]));
+            const groupSchema: JsonSchema = {
+                ...schema,
+                properties: Object.fromEntries(propertyNames.map(property => [property, properties[property]])),
+                required: schema.required?.filter(property => propertyNames.includes(property))
+            };
+            const released = await this.releaseDocumentProperties(subject, groupSchema, payload);
+            const releasedProperties = Object.keys(released);
+            if (releasedProperties.length !== propertyNames.length ||
+                releasedProperties.some(property => !Object.hasOwn(payload, property))) {
+                throw new Error('Failed to release stored read model document: missing or conflicting properties.');
+            }
+            releasedEntries.push(...Object.entries(released));
+        }
+
+        // Publish only after every subject succeeded. Entire top-level subtrees belong to one group.
+        return Object.fromEntries(releasedEntries);
+    }
+
+    private async releaseDocumentProperties(subject: string, schema: JsonSchema, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+        try {
+            const response = await this._connection.compliance.release({
+                EventStore: this._eventStore,
+                Namespace: this._namespace,
+                Subject: subject,
+                Schema: JSON.stringify(schema),
+                Payload: JSON.stringify(payload)
+            });
+            if (response.HasError !== false || typeof response.Payload !== 'string') {
+                throw new Error();
+            }
+            const released: unknown = JSON.parse(response.Payload);
+            if (!this.isDocumentObject(released)) {
+                throw new Error();
+            }
+            return released;
+        } catch {
+            // Kernel, transport and JSON parser errors can contain PII; do not expose them as causes.
+            throw new Error('Failed to release PII in stored read model document.');
+        }
+    }
+
+    private copyStoredDocument(document: Readonly<Record<string, unknown>>): Record<string, unknown> {
+        try {
+            if (!this.isDocumentObject(document)) {
+                throw new Error();
+            }
+            const copy: unknown = JSON.parse(JSON.stringify(document));
+            if (!this.isDocumentObject(copy)) {
+                throw new Error();
+            }
+            return copy;
+        } catch {
+            throw new Error('Stored read model document must be a JSON object.');
+        }
+    }
+
+    private isDocumentObject(value: unknown): value is Record<string, unknown> {
+        return value !== null && typeof value === 'object' && !Array.isArray(value);
+    }
+
+    private isDocumentSubject(value: unknown): value is string {
+        return typeof value === 'string' && value.length > 0;
+    }
+
     private async releaseSnapshotInstances<TReadModel>(readModelType: Constructor<TReadModel>, snapshots: ReadModelSnapshot<TReadModel>[]): Promise<ReadModelSnapshot<TReadModel>[]> {
         return Promise.all(
             snapshots.map(async snapshot => ({

package/readModels/for_ReadModels/given/a_stored_read_model.ts

@@ -0,0 +1,62 @@
+// 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 { field } from '@cratis/fundamentals';
+import type { ReleaseRequest, ReleaseResponse } from '@cratis/chronicle.contracts';
+import { vi } from 'vitest';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
+import { pii } from '../../../compliance/pii.js';
+import { subject } from '../../../compliance/subject.js';
+import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
+import type { IReadModels } from '../../IReadModels.js';
+import { ReadModels } from '../../ReadModels.js';
+
+class AccountOpened {}
+
+export class ContactDetails {
+    @field(String)
+    @pii()
+    phone!: string;
+}
+
+@fromEvent(AccountOpened)
+export class AccountDocument {
+    @field(String)
+    @subject()
+    id!: string;
+
+    @field(String)
+    @pii()
+    name!: string;
+
+    @field(String)
+    @pii()
+    email!: string;
+
+    @field(ContactDetails)
+    contact!: ContactDetails;
+
+    @field(Array, { genericArguments: [ContactDetails] })
+    contacts!: ContactDetails[];
+}
+
+export class a_stored_read_model {
+    readonly release = vi.fn<(request: ReleaseRequest) => Promise<ReleaseResponse>>()
+        .mockImplementation(async request => ({ HasError: false, Error: '', Payload: request.Payload }));
+    readonly readModels: IReadModels;
+
+    constructor() {
+        const connection = { compliance: { release: this.release } } as unknown as ChronicleConnection;
+        const artifacts: IClientArtifactsProvider = {
+            eventTypes: [], readModels: [AccountDocument], projections: [], reducers: [], reactors: [],
+            seeders: [], constraints: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+        };
+        this.readModels = new ReadModels('store', 'tenant', connection, artifacts, 'sink');
+    }
+
+    requestFor(subject: string): ReleaseRequest {
+        return this.release.mock.calls.map(([request]) => request).find(request => request.Subject === subject)!;
+    }
+}

package/readModels/for_ReadModels/when_releasing_a_document/with_a_default_subject.spec.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { JsonSchemaGenerator } from '../../../schemas/index.js';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+chai.should();
+
+describe('when releasing a document with a default subject', () => {
+    let context: a_stored_read_model;
+    let result: Record<string, unknown>;
+
+    beforeEach(async () => {
+        context = new a_stored_read_model();
+        context.release.mockResolvedValue({ HasError: false, Error: '', Payload: '{"id":"account","name":"released name"}' });
+        result = await context.readModels.releaseDocument(AccountDocument, {
+            id: 'account', name: 'encrypted name', __subject: 'owner'
+        });
+    });
+
+    it('should release all present properties together', () => context.release.mock.calls.should.have.lengthOf(1));
+    it('should use the stored subject rather than the id', () => context.requestFor('owner').Subject.should.equal('owner'));
+    it('should use the current event store and namespace', () => {
+        const { EventStore, Namespace } = context.requestFor('owner');
+        ({ EventStore, Namespace }).should.deep.equal({ EventStore: 'store', Namespace: 'tenant' });
+    });
+    it('should send only data properties', () => JSON.parse(context.requestFor('owner').Payload).should.deep.equal({ id: 'account', name: 'encrypted name' }));
+    it('should preserve compliance metadata in the relevant schema', () => {
+        const schema = JsonSchemaGenerator.generate(AccountDocument);
+        JSON.parse(context.requestFor('owner').Schema).should.deep.equal({
+            ...schema,
+            properties: { id: schema.properties!.id, name: schema.properties!.name },
+            required: ['id', 'name']
+        });
+    });
+    it('should return the released values', () => result.should.deep.equal({ id: 'account', name: 'released name' }));
+    it('should return a plain document rather than a model instance', () => Object.getPrototypeOf(result).should.equal(Object.prototype));
+});

package/readModels/for_ReadModels/when_releasing_a_document/with_a_frozen_document.spec.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+chai.should();
+
+describe('when releasing a frozen document', () => {
+    let document: Readonly<Record<string, unknown>>;
+    let result: Record<string, unknown>;
+    let original: string;
+
+    beforeEach(async () => {
+        const context = new a_stored_read_model();
+        document = Object.freeze({
+            name: 'encrypted name', contact: Object.freeze({ phone: 'unchanged phone' }),
+            __subjects: Object.freeze({ name: 'owner' })
+        });
+        original = JSON.stringify(document);
+        context.release.mockResolvedValue({ HasError: false, Error: '', Payload: '{"name":"released name"}' });
+        result = await context.readModels.releaseDocument(AccountDocument, document);
+    });
+
+    it('should not mutate the document or its metadata', () => JSON.stringify(document).should.equal(original));
+    it('should release into a separate document', () => result.should.deep.equal({ name: 'released name', contact: { phone: 'unchanged phone' } }));
+    it('should copy even the subtrees that are not released', () => result.contact!.should.not.equal(document.contact));
+});

package/readModels/for_ReadModels/when_releasing_a_document/with_a_malformed_response.spec.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+const should = chai.should();
+
+describe.each(['private@example.test', '', 'null', '[]', '"private@example.test"', '42'])('when releasing a document with malformed response %s', payload => {
+    let result: Record<string, unknown> | undefined;
+    let error: Error;
+
+    beforeEach(async () => {
+        const context = new a_stored_read_model();
+        result = undefined;
+        context.release.mockResolvedValue({ HasError: false, Error: '', Payload: payload });
+        await context.readModels.releaseDocument(AccountDocument, { name: 'encrypted name', __subject: 'owner' }).then(
+            released => { result = released; }, caught => { error = caught as Error; }
+        );
+    });
+
+    it('should reject without returning data', () => should.not.exist(result));
+    it('should sanitize parsing failures', () => error.message.should.equal('Failed to release PII in stored read model document.'));
+});

package/readModels/for_ReadModels/when_releasing_a_document/with_a_reported_failure.spec.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+const should = chai.should();
+
+describe.each(['kernel', 'transport'])('when releasing a document and a later subject reports a %s failure', failure => {
+    let context: a_stored_read_model;
+    let result: Record<string, unknown> | undefined;
+    let error: Error;
+    let document: Record<string, unknown>;
+    let original: string;
+
+    beforeEach(async () => {
+        context = new a_stored_read_model();
+        result = undefined;
+        document = { name: 'encrypted name', email: 'encrypted email', __subjects: { name: 'owner', email: 'other-owner' } };
+        original = JSON.stringify(document);
+        context.release.mockResolvedValueOnce({ HasError: false, Error: '', Payload: '{"name":"released name"}' });
+        if (failure === 'kernel') {
+            context.release.mockResolvedValueOnce({ HasError: true, Error: 'PII private@example.test', Payload: '{"email":"private@example.test"}' });
+        } else {
+            context.release.mockRejectedValueOnce(new Error('Transport details: private@example.test'));
+        }
+        await context.readModels.releaseDocument(AccountDocument, document).then(
+            released => { result = released; }, caught => { error = caught as Error; }
+        );
+    });
+
+    it('should have attempted both subjects', () => context.release.mock.calls.should.have.lengthOf(2));
+    it('should reject the whole operation', () => error.should.be.instanceOf(Error));
+    it('should never expose the earlier released group', () => should.not.exist(result));
+    it('should leave the input unchanged even after a partial release', () => JSON.stringify(document).should.equal(original));
+    it('should not expose PII from errors or payloads', () => error.message.should.equal('Failed to release PII in stored read model document.'));
+    it('should not attach an unsafe cause', () => should.not.exist(error.cause));
+});

package/readModels/for_ReadModels/when_releasing_a_document/with_an_empty_released_value.spec.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+chai.should();
+
+describe('when releasing a document and the kernel reports success with an empty value', () => {
+    let result: Record<string, unknown>;
+
+    beforeEach(async () => {
+        const context = new a_stored_read_model();
+        context.release.mockResolvedValue({ HasError: false, Error: '', Payload: '{"name":""}' });
+        result = await context.readModels.releaseDocument(AccountDocument, { name: 'encrypted name', __subject: 'owner' });
+    });
+
+    it('should accept the reported success without guessing whether decryption failed', () => result.should.deep.equal({ name: '' }));
+});

package/readModels/for_ReadModels/when_releasing_a_document/with_an_unknown_subject_property.spec.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+chai.should();
+
+describe.each(['unknown', 'contact.phone', '__subject', '__subjects', 'toString'])('when releasing a document with unknown subject property %s', property => {
+    let context: a_stored_read_model;
+    let error: Error;
+
+    beforeEach(async () => {
+        context = new a_stored_read_model();
+        await context.readModels.releaseDocument(AccountDocument, {
+            name: 'encrypted name', contact: { phone: 'encrypted phone' }, unknown: 'not declared',
+            'contact.phone': 'not declared', toString: 'not declared',
+            __subject: 'owner', __subjects: { [property]: 'other-owner' }
+        }).catch(caught => { error = caught as Error; });
+    });
+
+    it('should reject undeclared, nested, reserved and inherited property names', () => error.message.should.equal('Stored read model document has an unknown subject property.'));
+    it('should validate the entire subject map before attempting any releases', () => context.release.mock.calls.should.have.lengthOf(0));
+});
+
+describe.each(['email', 'removedProperty', 'contact.phone', 'toString'])('when releasing a document with a stale subject property %s', property => {
+    let context: a_stored_read_model;
+    let result: Record<string, unknown>;
+
+    beforeEach(async () => {
+        context = new a_stored_read_model();
+        result = await context.readModels.releaseDocument(AccountDocument, {
+            name: 'encrypted name', __subject: 'owner', __subjects: { [property]: 'other-owner' }
+        });
+    });
+
+    it('should ignore mappings without a corresponding document property', () => result.should.deep.equal({ name: 'encrypted name' }));
+    it('should release only the existing properties under their subject', () => {
+        context.release.mock.calls.should.have.lengthOf(1);
+        JSON.parse(context.requestFor('owner').Payload).should.deep.equal({ name: 'encrypted name' });
+    });
+});

package/readModels/for_ReadModels/when_releasing_a_document/with_bookkeeping_fields.spec.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+chai.should();
+
+describe.each([undefined, 'owner'])('when releasing a document with bookkeeping and default subject %s', defaultSubject => {
+    let context: a_stored_read_model;
+    let result: Record<string, unknown>;
+
+    beforeEach(async () => {
+        context = new a_stored_read_model();
+        result = await context.readModels.releaseDocument(AccountDocument, {
+            id: 'account', name: 'stored name', _id: 'storage-id', __generation: 1,
+            __subject: defaultSubject, __subjects: {}
+        });
+    });
+
+    it('should strip storage-only and subject metadata', () => result.should.deep.equal({ id: 'account', name: 'stored name' }));
+    it('should never send bookkeeping for release', () => {
+        context.release.mock.calls.forEach(([request]) => {
+            JSON.parse(request.Payload).should.deep.equal({ id: 'account', name: 'stored name' });
+        });
+    });
+});

package/readModels/for_ReadModels/when_releasing_a_document/with_conflicting_or_missing_properties.spec.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+const should = chai.should();
+
+describe.each([
+    '{}',
+    '{"name":"wrong group"}',
+    '{"email":"released email","name":"overwrite released group"}',
+    '{"email":"released email","id":"overwrite unreleased property"}',
+    '{"email":"released email","__proto__":{"polluted":true}}'
+])('when releasing a document with missing or conflicting response properties %s', payload => {
+    let result: Record<string, unknown> | undefined;
+    let error: Error;
+
+    beforeEach(async () => {
+        const context = new a_stored_read_model();
+        result = undefined;
+        context.release.mockResolvedValueOnce({ HasError: false, Error: '', Payload: '{"name":"released name"}' });
+        context.release.mockResolvedValueOnce({ HasError: false, Error: '', Payload: payload });
+        await context.readModels.releaseDocument(AccountDocument, {
+            id: 'account', name: 'encrypted name', email: 'encrypted email',
+            __subjects: { name: 'owner', email: 'other-owner' }
+        }).then(released => { result = released; }, caught => { error = caught as Error; });
+    });
+
+    it('should reject the whole operation', () => error.message.should.equal('Failed to release stored read model document: missing or conflicting properties.'));
+    it('should not expose a partial result', () => should.not.exist(result));
+});

package/readModels/for_ReadModels/when_releasing_a_document/with_empty_subject_metadata.spec.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+chai.should();
+
+describe.each([
+    { __subject: null }, { __subject: '' },
+    { __subjects: { name: null } }, { __subjects: { name: '' } },
+    { __subjects: null }, { __subjects: [] }, { __subjects: 'owner' }, { __subjects: 42 }
+])('when releasing a document without usable subject metadata %j', metadata => {
+    let context: a_stored_read_model;
+    let result: Record<string, unknown>;
+
+    beforeEach(async () => {
+        context = new a_stored_read_model();
+        result = await context.readModels.releaseDocument(AccountDocument, { name: 'stored name', ...metadata });
+    });
+
+    it('should copy properties without a subject unchanged', () => result.should.deep.equal({ name: 'stored name' }));
+    it('should not attempt release', () => context.release.mock.calls.should.have.lengthOf(0));
+});
+
+describe.each([null, ''])('when releasing a document with an empty property subject %j and a default subject', subject => {
+    let context: a_stored_read_model;
+    let result: Record<string, unknown>;
+
+    beforeEach(async () => {
+        context = new a_stored_read_model();
+        context.release.mockResolvedValue({ HasError: false, Error: '', Payload: JSON.stringify({ name: 'released name' }) });
+        result = await context.readModels.releaseDocument(AccountDocument, {
+            name: 'encrypted name', __subject: 'owner', __subjects: { name: subject }
+        });
+    });
+
+    it('should fall back to the default subject', () => context.requestFor('owner').Subject.should.equal('owner'));
+    it('should release the property', () => result.should.deep.equal({ name: 'released name' }));
+});
+
+describe.each([null, ''])('when releasing a document with an empty default subject %j and a property subject', subject => {
+    let context: a_stored_read_model;
+    let result: Record<string, unknown>;
+
+    beforeEach(async () => {
+        context = new a_stored_read_model();
+        context.release.mockResolvedValue({ HasError: false, Error: '', Payload: JSON.stringify({ name: 'released name' }) });
+        result = await context.readModels.releaseDocument(AccountDocument, {
+            id: 'account', name: 'encrypted name', __subject: subject, __subjects: { name: 'owner' }
+        });
+    });
+
+    it('should release only the property with a subject', () => JSON.parse(context.requestFor('owner').Payload).should.deep.equal({ name: 'encrypted name' }));
+    it('should retain properties without a subject', () => result.should.deep.equal({ id: 'account', name: 'released name' }));
+});

package/readModels/for_ReadModels/when_releasing_a_document/with_invalid_subject_metadata.spec.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+chai.should();
+
+describe.each([
+    { __subject: 42 }, { __subject: false }, { __subject: [] }, { __subject: {} },
+    { __subjects: { name: 42 } }, { __subjects: { name: false } },
+    { __subjects: { name: [] } }, { __subjects: { name: { subject: 'private@example.test' } } },
+    { __subjects: { email: 42 } }, { __subjects: { removedProperty: 42 } }
+])('when releasing a document with invalid subject metadata %j', metadata => {
+    let context: a_stored_read_model;
+    let error: Error;
+
+    beforeEach(async () => {
+        context = new a_stored_read_model();
+        await context.readModels.releaseDocument(AccountDocument, { name: 'encrypted name', ...metadata })
+            .catch(caught => { error = caught as Error; });
+    });
+
+    it('should reject the document', () => error.should.be.instanceOf(Error));
+    it('should not expose metadata values in the error', () => error.message.should.not.contain('private@example.test'));
+    it('should not attempt release with invalid metadata', () => context.release.mock.calls.should.have.lengthOf(0));
+});

package/readModels/for_ReadModels/when_releasing_a_document/with_mixed_subjects.spec.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+chai.should();
+
+describe('when releasing a document with mixed default and property subjects', () => {
+    let context: a_stored_read_model;
+    let result: Record<string, unknown>;
+
+    beforeEach(async () => {
+        context = new a_stored_read_model();
+        context.release.mockImplementation(async request => ({
+            HasError: false, Error: '', Payload: JSON.stringify(request.Subject === 'owner'
+                ? { id: 'account', name: 'released name' } : { email: 'released email' })
+        }));
+        result = await context.readModels.releaseDocument(AccountDocument, {
+            id: 'account', name: 'encrypted name', email: 'encrypted email',
+            __subject: 'owner', __subjects: { name: 'owner', email: 'joined-owner' }
+        });
+    });
+
+    it('should reuse the default subject group for matching property subjects', () => context.release.mock.calls.should.have.lengthOf(2));
+    it('should apply the default to unmapped properties', () => {
+        JSON.parse(context.requestFor('owner').Payload).should.deep.equal({ id: 'account', name: 'encrypted name' });
+    });
+    it('should override the default for mapped properties', () => {
+        JSON.parse(context.requestFor('joined-owner').Payload).should.deep.equal({ email: 'encrypted email' });
+    });
+    it('should send a schema limited to the overridden property', () => {
+        Object.keys(JSON.parse(context.requestFor('joined-owner').Schema).properties).should.deep.equal(['email']);
+    });
+    it('should merge the released properties without bookkeeping', () => result.should.deep.equal({
+        id: 'account', name: 'released name', email: 'released email'
+    }));
+});

package/readModels/for_ReadModels/when_releasing_a_document/with_property_subjects.spec.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { JsonSchemaGenerator } from '../../../schemas/index.js';
+import { AccountDocument, a_stored_read_model } from '../given/a_stored_read_model.js';
+
+chai.should();
+
+describe('when releasing a document with property subjects', () => {
+    let context: a_stored_read_model;
+    let result: Record<string, unknown>;
+
+    beforeEach(async () => {
+        context = new a_stored_read_model();
+        context.release.mockImplementation(async request => ({
+            HasError: false, Error: '', Payload: JSON.stringify(request.Subject === 'owner'
+                ? { name: 'released name', email: 'released email' }
+                : { contact: { phone: 'released phone' }, contacts: [{ phone: 'released list phone' }] })
+        }));
+        result = await context.readModels.releaseDocument(AccountDocument, {
+            id: 'account', name: 'encrypted name', email: 'encrypted email',
+            contact: { phone: 'encrypted phone' }, contacts: [{ phone: 'encrypted list phone' }],
+            __subjects: { name: 'owner', email: 'owner', contact: 'contact-owner', contacts: 'contact-owner' }
+        });
+    });
+
+    it('should batch properties by distinct subject', () => context.release.mock.calls.should.have.lengthOf(2));
+    it('should send only the owner properties to that subject', () => {
+        JSON.parse(context.requestFor('owner').Payload).should.deep.equal({ name: 'encrypted name', email: 'encrypted email' });
+    });
+    it('should release each nested subtree and array under its top-level subject', () => {
+        JSON.parse(context.requestFor('contact-owner').Payload).should.deep.equal({
+            contact: { phone: 'encrypted phone' }, contacts: [{ phone: 'encrypted list phone' }]
+        });
+    });
+    it('should retain nested compliance schemas', () => {
+        const properties = JsonSchemaGenerator.generate(AccountDocument).properties!;
+        JSON.parse(context.requestFor('contact-owner').Schema).properties.should.deep.equal({
+            contact: properties.contact, contacts: properties.contacts
+        });
+    });
+    it('should include the array item phone PII metadata in the subject-specific schema', () => {
+        JSON.parse(context.requestFor('contact-owner').Schema).properties.contacts.items.properties.phone.should.deep.equal({
+            type: 'string', compliance: [{ metadataType: 'PII', details: '' }]
+        });
+    });
+    it('should combine the released groups and retain properties without a subject', () => result.should.deep.equal({
+        id: 'account', name: 'released name', email: 'released email',
+        contact: { phone: 'released phone' }, contacts: [{ phone: 'released list phone' }]
+    }));
+});