sos-sdk-core-ts 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,10 +1,26 @@
 # Changelog
 
-## Unreleased
+## 0.4.0 - 2026-09-29
+
+- Add the shared high-level Communication Bundle editor and reader for SOS,
+  Vet and UHC. Author an outer batch Bundle of Communications, validate each
+  attached inner document/batch/collection Bundle with
+  `fhir-data-utils-ts@0.6.0`, and keep PDF, image, audio and calendar files as
+  inner DocumentReference resources.
+- Pin `sos-data-utils-ts@0.5.1` and extend the existing
+  `gdc-common-utils-ts@2.9.21` Bundle editor, reader and attached-Bundle session
+  rather than introducing a parallel high-level implementation.
+
+- Add runtime-neutral, department-aware equipment calibration and operating-authorization orchestration; blood-bank labeling remains explicitly deferred.
+
+- Link the coordinated SOS/Vet/UHC clinical accessor adoption boundary so
+  shared orchestration is added only with an actual multichannel workflow.
 
 - Require the initial emergency triage Task owner to be a professional Group,
-  while keeping the accepting PractitionerRole as Task owner and actual
-  callback/message sender after acknowledgement.
+  while keeping the accepting PractitionerRole as Task owner and authenticated
+  transport actor after acknowledgement.
+- Define the department Organization as the FHIR Communication sender and keep
+  the professional Group solely as the stable reply queue.
 - Clarify that Group reply routing never replaces the legal Organization
   document author, professional attester or authenticated transport actor.
 

package/README.md

@@ -1,4 +1,6 @@
 # Shared SOS SDK Core
+
+Shared SOS/Vet/UHC orchestration includes [equipment calibration and operating authorization](docs/EQUIPMENT_COMPLIANCE.md) without embedding product roles or persistence plumbing.
 ## Blocking local-first SDK release
 
 The canonical contract is [`SDK_LAYERING.md`](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/SDK_LAYERING.md).
@@ -38,6 +40,24 @@ jobs; those adapters do not belong here.
 Git, workspace, vendored and `file:` dependencies are forbidden in committed
 or deployed dependency state.
 
+The cross-product Bundle/Communication editor and reader are owned here as
+high-level extensions of the existing `gdc-common-utils-ts` `BundleEditor`,
+`BundleReader` and `CommunicationAttachedBundleSession`. They preserve those
+APIs instead of duplicating their attachment or claims-first lifecycle, while
+`fhir-data-utils-ts` supplies neutral import, projection and validation tools.
+Follow the
+[SOS/Vet/UHC clinical accessor adoption matrix](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/CLINICAL_TYPED_ACCESSOR_ADOPTION.md)
+before changing dependencies: unaffected portals and assistants are not forced
+to upgrade merely because a lower package published a newer editor.
+
+All cross-participant exchanges use the established claims-first outer batch
+Bundle containing one or more Communication resources. Each Communication
+contains exactly one inner document, batch or collection Bundle in its
+`application/fhir+json` attachment claims. Binary files such as PDF, image,
+audio or `text/calendar` are DocumentReference entries inside the inner Bundle.
+Native FHIR R4/R5 is materialized only at an explicit adapter boundary. See
+[Communication Bundle editor and reader](docs/COMMUNICATION_BUNDLE_EDITOR_READER.md).
+
 The emergency-group contract stores subject references only on an enumerated
 FHIR Group. A group assistance request references that Group from one standard,
 compact-coded ServiceRequest; it never copies members or persists split coding

package/dist/communication-bundle.d.ts

@@ -0,0 +1,91 @@
+import { BundleEditor } from 'gdc-common-utils-ts/utils/bundle-editor';
+import { BundleReader } from 'gdc-common-utils-ts/utils/bundle-reader';
+import { CommunicationAttachedBundleSession } from 'gdc-common-utils-ts/utils/communication-attached-bundle-session';
+import { type FhirResource } from 'fhir-data-utils-ts';
+export type CommunicationInnerBundleType = 'document' | 'batch' | 'collection';
+export type AttachmentDocumentInput = Readonly<{
+    identifier: string;
+    subjectReference: string;
+    contentType: string;
+    dataBase64?: string;
+    url?: string;
+    title?: string;
+    description?: string;
+    date?: string;
+    authorReferences?: readonly string[];
+    eventReferences?: readonly string[];
+}>;
+/**
+ * SOS/Vet/UHC extension of the existing GDC BundleEditor.
+ *
+ * The inherited editor owns the canonical outer claims-first batch. Each
+ * staged message is a CommunicationAttachedBundleSession, so the existing
+ * attachment synchronization and Bundle lifecycle remain the source of truth.
+ * FHIR data utilities are used only at import/materialization boundaries.
+ */
+export declare class CommunicationBundleEditor extends BundleEditor {
+    #private;
+    constructor();
+    newCommunication(): CommunicationMessageEditor;
+    /** Builds the inherited claims-first outer batch after validating every attached Bundle. */
+    build(): ReturnType<BundleEditor['build']>;
+}
+/** High-level message editor extending the established attached-Bundle session. */
+export declare class CommunicationMessageEditor extends CommunicationAttachedBundleSession {
+    #private;
+    constructor(parent: CommunicationBundleEditor);
+    setIdentifier(value: string): this;
+    getIdentifier(): string | undefined;
+    setStatus(value: string): this;
+    getStatus(): string | undefined;
+    setSubject(value: string): this;
+    getSubject(): string | undefined;
+    setSender(value: string): this;
+    getSender(): string | undefined;
+    setRecipients(values: readonly string[]): this;
+    getRecipients(): readonly string[];
+    setSent(value: string): this;
+    getSent(): string | undefined;
+    setAttachmentTitle(value: string): this;
+    getAttachmentTitle(): string | undefined;
+    setInnerBundleType(value: CommunicationInnerBundleType): this;
+    getInnerBundleType(): CommunicationInnerBundleType;
+    /** Adds one canonical claims-first resource to the existing attached-Bundle session. */
+    addResource(resource: FhirResource, request?: Readonly<{
+        method: 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'GET';
+        url: string;
+        ifMatch?: string;
+    }>): this;
+    /** Adds a PDF, image, audio or calendar file as an inner DocumentReference. */
+    addAttachmentDocument(input: AttachmentDocumentInput): this;
+    doneCommunication(): CommunicationBundleEditor;
+    /** @internal */
+    validateForBuild(): void;
+    /** @internal */
+    getCompleteCommunicationClaims(): Record<string, unknown>;
+}
+/** Read-only extension of the established BundleReader for an outer Communication batch. */
+export declare class CommunicationBundleReader extends BundleReader {
+    #private;
+    constructor(outerBatch: Record<string, unknown>);
+    getCommunicationCount(): number;
+    openCommunication(index: number): CommunicationMessageReader;
+}
+/** High-level getters over one claims-first Communication and its attached Bundle. */
+export declare class CommunicationMessageReader extends BundleReader {
+    #private;
+    constructor(entry: Record<string, unknown>);
+    getCommunication(): FhirResource;
+    getInnerBundle(): Record<string, unknown>;
+    getIdentifier(): string;
+    getStatus(): string | undefined;
+    getSubject(): string | undefined;
+    getSender(): string | undefined;
+    getRecipients(): readonly string[];
+    getSent(): string | undefined;
+    getAttachmentTitle(): string | undefined;
+    getInnerBundleType(): string | undefined;
+    getResourcesByType<TResource extends FhirResource = FhirResource>(resourceType: string): readonly TResource[];
+    getAppointments(): readonly FhirResource[];
+    getDocumentReferences(): readonly FhirResource[];
+}

package/dist/communication-bundle.js

@@ -0,0 +1,249 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _CommunicationBundleEditor_instances, _CommunicationBundleEditor_messages, _CommunicationBundleEditor_committed, _CommunicationBundleEditor_commitCommunication, _CommunicationMessageEditor_parent, _CommunicationMessageEditor_status, _CommunicationMessageEditor_sender, _CommunicationMessageEditor_recipients, _CommunicationMessageEditor_sent, _CommunicationMessageEditor_attachmentTitle, _CommunicationBundleReader_communicationEntries, _CommunicationMessageReader_resource, _CommunicationMessageReader_claims;
+import { BundleEditor, BundleOperations, BundleTypes } from 'gdc-common-utils-ts/utils/bundle-editor';
+import { BundleReader } from 'gdc-common-utils-ts/utils/bundle-reader';
+import { CommunicationAttachedBundleSession, CommunicationClaimsContext, } from 'gdc-common-utils-ts/utils/communication-attached-bundle-session';
+import { decodeAttachedBundleFromCommunicationClaims } from 'gdc-common-utils-ts/utils/communication-didcomm-payload';
+import { CommunicationClaim } from 'gdc-common-utils-ts/models/interoperable-claims/communication-claims';
+import { DocumentReferenceClaim } from 'fhir-data-utils-ts';
+/**
+ * SOS/Vet/UHC extension of the existing GDC BundleEditor.
+ *
+ * The inherited editor owns the canonical outer claims-first batch. Each
+ * staged message is a CommunicationAttachedBundleSession, so the existing
+ * attachment synchronization and Bundle lifecycle remain the source of truth.
+ * FHIR data utilities are used only at import/materialization boundaries.
+ */
+export class CommunicationBundleEditor extends BundleEditor {
+    constructor() {
+        super();
+        _CommunicationBundleEditor_instances.add(this);
+        _CommunicationBundleEditor_messages.set(this, []);
+        _CommunicationBundleEditor_committed.set(this, false);
+        this.setBundleOperation(BundleOperations.create)
+            .setBundleType(BundleTypes.batch)
+            .setAllowedResourceType('Communication');
+    }
+    newCommunication() {
+        if (__classPrivateFieldGet(this, _CommunicationBundleEditor_committed, "f"))
+            throw new TypeError('communication_bundle_already_built');
+        const message = new CommunicationMessageEditor(this);
+        __classPrivateFieldGet(this, _CommunicationBundleEditor_messages, "f").push(message);
+        return message;
+    }
+    /** Builds the inherited claims-first outer batch after validating every attached Bundle. */
+    build() {
+        if (!__classPrivateFieldGet(this, _CommunicationBundleEditor_messages, "f").length)
+            throw new TypeError('communication_required');
+        if (!__classPrivateFieldGet(this, _CommunicationBundleEditor_committed, "f")) {
+            for (const message of __classPrivateFieldGet(this, _CommunicationBundleEditor_messages, "f"))
+                __classPrivateFieldGet(this, _CommunicationBundleEditor_instances, "m", _CommunicationBundleEditor_commitCommunication).call(this, message);
+            __classPrivateFieldSet(this, _CommunicationBundleEditor_committed, true, "f");
+        }
+        return super.build();
+    }
+}
+_CommunicationBundleEditor_messages = new WeakMap(), _CommunicationBundleEditor_committed = new WeakMap(), _CommunicationBundleEditor_instances = new WeakSet(), _CommunicationBundleEditor_commitCommunication = function _CommunicationBundleEditor_commitCommunication(message) {
+    message.validateForBuild();
+    const claims = message.getCompleteCommunicationClaims();
+    const identifier = requireText(claims[CommunicationClaim.Identifier], 'communication_identifier_required');
+    const entry = this.newEntry(identifier);
+    for (const [claim, value] of Object.entries(claims))
+        entry.setClaim(claim, value);
+    entry.create();
+};
+/** High-level message editor extending the established attached-Bundle session. */
+export class CommunicationMessageEditor extends CommunicationAttachedBundleSession {
+    constructor(parent) {
+        super({
+            communicationClaims: { '@context': CommunicationClaimsContext },
+            initialBundle: { resourceType: 'Bundle', type: 'batch', data: [] },
+        });
+        _CommunicationMessageEditor_parent.set(this, void 0);
+        _CommunicationMessageEditor_status.set(this, void 0);
+        _CommunicationMessageEditor_sender.set(this, void 0);
+        _CommunicationMessageEditor_recipients.set(this, []);
+        _CommunicationMessageEditor_sent.set(this, void 0);
+        _CommunicationMessageEditor_attachmentTitle.set(this, void 0);
+        __classPrivateFieldSet(this, _CommunicationMessageEditor_parent, parent, "f");
+    }
+    setIdentifier(value) { this.setCommunicationIdentifier(value); return this; }
+    getIdentifier() { return optionalText(this.getCommunicationIdentifier()); }
+    setStatus(value) { __classPrivateFieldSet(this, _CommunicationMessageEditor_status, requireText(value, 'communication_status_required'), "f"); return this; }
+    getStatus() { return __classPrivateFieldGet(this, _CommunicationMessageEditor_status, "f"); }
+    setSubject(value) { this.setCommunicationSubject(value); return this; }
+    getSubject() { return optionalText(this.getCommunicationSubject()); }
+    setSender(value) { __classPrivateFieldSet(this, _CommunicationMessageEditor_sender, requireText(value, 'communication_sender_required'), "f"); return this; }
+    getSender() { return __classPrivateFieldGet(this, _CommunicationMessageEditor_sender, "f"); }
+    setRecipients(values) { __classPrivateFieldSet(this, _CommunicationMessageEditor_recipients, uniqueReferences(values, 'communication_recipient_required'), "f"); return this; }
+    getRecipients() { return Object.freeze([...__classPrivateFieldGet(this, _CommunicationMessageEditor_recipients, "f")]); }
+    setSent(value) { __classPrivateFieldSet(this, _CommunicationMessageEditor_sent, requireText(value, 'communication_sent_required'), "f"); return this; }
+    getSent() { return __classPrivateFieldGet(this, _CommunicationMessageEditor_sent, "f"); }
+    setAttachmentTitle(value) { __classPrivateFieldSet(this, _CommunicationMessageEditor_attachmentTitle, requireText(value, 'communication_attachment_title_required'), "f"); return this; }
+    getAttachmentTitle() { return __classPrivateFieldGet(this, _CommunicationMessageEditor_attachmentTitle, "f"); }
+    setInnerBundleType(value) {
+        if (!['document', 'batch', 'collection'].includes(value))
+            throw new TypeError('fhir_inner_bundle_type_invalid');
+        this.setAttachedBundle({ ...this.getAttachedBundle(), type: value });
+        return this;
+    }
+    getInnerBundleType() { return this.getAttachedBundle().type; }
+    /** Adds one canonical claims-first resource to the existing attached-Bundle session. */
+    addResource(resource, request) {
+        const claims = claimsFromResource(resource);
+        const identifier = resourceIdentifier(resource, claims);
+        this.upsertActiveEntry({
+            resourceType: resource.resourceType,
+            claims,
+            fullUrl: `urn:uuid:${identifier}`,
+            ...(request ? { request } : {}),
+        }).saveAndReleaseActiveEntry();
+        return this;
+    }
+    /** Adds a PDF, image, audio or calendar file as an inner DocumentReference. */
+    addAttachmentDocument(input) {
+        const identifier = requireText(input.identifier, 'document_reference_identifier_required');
+        const subjectReference = requireText(input.subjectReference, 'document_reference_subject_required');
+        const contentType = requireText(input.contentType, 'document_reference_content_type_required');
+        if (!input.dataBase64 && !input.url)
+            throw new TypeError('document_reference_content_required');
+        const claims = compactClaims({
+            '@context': CommunicationClaimsContext,
+            [DocumentReferenceClaim.Identifier]: identifier,
+            [DocumentReferenceClaim.Subject]: subjectReference,
+            [DocumentReferenceClaim.ContentType]: contentType,
+            [DocumentReferenceClaim.ContentData]: input.dataBase64,
+            [DocumentReferenceClaim.Location]: input.url,
+            [DocumentReferenceClaim.Description]: input.description || input.title,
+            [DocumentReferenceClaim.Date]: input.date,
+            [DocumentReferenceClaim.Author]: input.authorReferences?.join(','),
+            [DocumentReferenceClaim.EventReference]: input.eventReferences?.join(','),
+        });
+        this.upsertActiveDocumentReferenceEntry({ claims, fullUrl: `urn:uuid:${identifier}` }).saveAndReleaseActiveEntry();
+        return this;
+    }
+    doneCommunication() { return __classPrivateFieldGet(this, _CommunicationMessageEditor_parent, "f"); }
+    /** @internal */
+    validateForBuild() {
+        requireText(this.getCommunicationIdentifier(), 'communication_identifier_required');
+        requireText(__classPrivateFieldGet(this, _CommunicationMessageEditor_status, "f"), 'communication_status_required');
+        requireText(this.getCommunicationSubject(), 'communication_subject_required');
+        validateAttachedBundle(this.getAttachedBundle());
+    }
+    /** @internal */
+    getCompleteCommunicationClaims() {
+        return compactClaims({
+            ...this.getCommunicationClaims(),
+            [CommunicationClaim.Status]: __classPrivateFieldGet(this, _CommunicationMessageEditor_status, "f"),
+            [CommunicationClaim.Sender]: __classPrivateFieldGet(this, _CommunicationMessageEditor_sender, "f"),
+            [CommunicationClaim.Recipient]: __classPrivateFieldGet(this, _CommunicationMessageEditor_recipients, "f").length ? __classPrivateFieldGet(this, _CommunicationMessageEditor_recipients, "f").join(',') : undefined,
+            [CommunicationClaim.Sent]: __classPrivateFieldGet(this, _CommunicationMessageEditor_sent, "f"),
+            [CommunicationClaim.ContentAttachmentTitle]: __classPrivateFieldGet(this, _CommunicationMessageEditor_attachmentTitle, "f"),
+        });
+    }
+}
+_CommunicationMessageEditor_parent = new WeakMap(), _CommunicationMessageEditor_status = new WeakMap(), _CommunicationMessageEditor_sender = new WeakMap(), _CommunicationMessageEditor_recipients = new WeakMap(), _CommunicationMessageEditor_sent = new WeakMap(), _CommunicationMessageEditor_attachmentTitle = new WeakMap();
+/** Read-only extension of the established BundleReader for an outer Communication batch. */
+export class CommunicationBundleReader extends BundleReader {
+    constructor(outerBatch) {
+        super(outerBatch);
+        _CommunicationBundleReader_communicationEntries.set(this, void 0);
+        if (this.getBundleType() !== 'batch')
+            throw new TypeError('fhir_batch_bundle_required');
+        __classPrivateFieldSet(this, _CommunicationBundleReader_communicationEntries, Object.freeze(this.getEntries().filter(entry => entry.resource?.resourceType === 'Communication')), "f");
+        if (!__classPrivateFieldGet(this, _CommunicationBundleReader_communicationEntries, "f").length)
+            throw new TypeError('fhir_communication_required');
+    }
+    getCommunicationCount() { return __classPrivateFieldGet(this, _CommunicationBundleReader_communicationEntries, "f").length; }
+    openCommunication(index) {
+        if (!Number.isInteger(index) || index < 0 || index >= __classPrivateFieldGet(this, _CommunicationBundleReader_communicationEntries, "f").length)
+            throw new RangeError('communication_index_invalid');
+        return new CommunicationMessageReader(__classPrivateFieldGet(this, _CommunicationBundleReader_communicationEntries, "f")[index]);
+    }
+}
+_CommunicationBundleReader_communicationEntries = new WeakMap();
+/** High-level getters over one claims-first Communication and its attached Bundle. */
+export class CommunicationMessageReader extends BundleReader {
+    constructor(entry) {
+        const resource = entry.resource;
+        if (resource?.resourceType !== 'Communication')
+            throw new TypeError('fhir_communication_required');
+        const claims = claimsFromResource(resource);
+        const attachedBundle = decodeAttachedBundleFromCommunicationClaims(claims);
+        super(attachedBundle);
+        _CommunicationMessageReader_resource.set(this, void 0);
+        _CommunicationMessageReader_claims.set(this, void 0);
+        validateAttachedBundle(attachedBundle);
+        __classPrivateFieldSet(this, _CommunicationMessageReader_resource, clone(resource), "f");
+        __classPrivateFieldSet(this, _CommunicationMessageReader_claims, clone(claims), "f");
+    }
+    getCommunication() { return clone(__classPrivateFieldGet(this, _CommunicationMessageReader_resource, "f")); }
+    getInnerBundle() { return clone(decodeAttachedBundleFromCommunicationClaims(__classPrivateFieldGet(this, _CommunicationMessageReader_claims, "f"))); }
+    getIdentifier() { return requireText(__classPrivateFieldGet(this, _CommunicationMessageReader_claims, "f")[CommunicationClaim.Identifier], 'communication_identifier_required'); }
+    getStatus() { return optionalText(__classPrivateFieldGet(this, _CommunicationMessageReader_claims, "f")[CommunicationClaim.Status]); }
+    getSubject() { return optionalText(__classPrivateFieldGet(this, _CommunicationMessageReader_claims, "f")[CommunicationClaim.Subject]); }
+    getSender() { return optionalText(__classPrivateFieldGet(this, _CommunicationMessageReader_claims, "f")[CommunicationClaim.Sender]); }
+    getRecipients() { return csv(__classPrivateFieldGet(this, _CommunicationMessageReader_claims, "f")[CommunicationClaim.Recipient]); }
+    getSent() { return optionalText(__classPrivateFieldGet(this, _CommunicationMessageReader_claims, "f")[CommunicationClaim.Sent]); }
+    getAttachmentTitle() { return optionalText(__classPrivateFieldGet(this, _CommunicationMessageReader_claims, "f")[CommunicationClaim.ContentAttachmentTitle]); }
+    getInnerBundleType() { return this.getBundleType(); }
+    getResourcesByType(resourceType) {
+        return Object.freeze(this.getEntries().flatMap(entry => {
+            const resource = entry.resource;
+            return resource?.resourceType === resourceType ? [clone(resource)] : [];
+        }));
+    }
+    getAppointments() { return this.getResourcesByType('Appointment'); }
+    getDocumentReferences() { return this.getResourcesByType('DocumentReference'); }
+}
+_CommunicationMessageReader_resource = new WeakMap(), _CommunicationMessageReader_claims = new WeakMap();
+function claimsFromResource(resource) {
+    const meta = resource.meta;
+    const claims = meta && typeof meta === 'object' && !Array.isArray(meta) ? meta.claims : undefined;
+    if (!claims || typeof claims !== 'object' || Array.isArray(claims))
+        throw new TypeError('claims_first_resource_required');
+    return clone(claims);
+}
+function resourceIdentifier(resource, claims) {
+    return requireText(resource.id || claims[`${resource.resourceType}.identifier`], 'resource_identifier_required');
+}
+function validateAttachedBundle(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('fhir_bundle_required');
+    const bundle = value;
+    if (bundle.resourceType !== 'Bundle')
+        throw new TypeError('fhir_bundle_required');
+    const type = optionalText(bundle.type);
+    if (!type || !['document', 'batch', 'collection'].includes(type))
+        throw new TypeError('fhir_inner_bundle_type_invalid');
+    const entries = Array.isArray(bundle.data) ? bundle.data : [];
+    if (type === 'document' && entries[0]?.resource?.resourceType !== 'Composition')
+        throw new TypeError('fhir_document_composition_first_required');
+    if (type === 'batch' && entries.some(entry => {
+        const request = entry.request;
+        return !optionalText(request?.method) || !optionalText(request?.url);
+    }))
+        throw new TypeError('fhir_batch_request_required');
+}
+function csv(value) {
+    if (Array.isArray(value))
+        return Object.freeze(value.map(String).map(item => item.trim()).filter(Boolean));
+    const normalized = optionalText(value);
+    return Object.freeze(normalized ? normalized.split(',').map(item => item.trim()).filter(Boolean) : []);
+}
+function uniqueReferences(values, error) { return [...new Set(values.map(value => requireText(value, error)))]; }
+function compactClaims(input) { return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined && value !== null && value !== '')); }
+function optionalText(value) { return typeof value === 'string' && value.trim() ? value.trim() : undefined; }
+function requireText(value, error) { const normalized = optionalText(value); if (!normalized)
+    throw new TypeError(error); return normalized; }
+function clone(value) { return JSON.parse(JSON.stringify(value)); }

package/dist/equipment-compliance-orchestration.d.ts

@@ -0,0 +1,39 @@
+import { buildDeviceCalibrationFlatGraph, buildDeviceOperatingAuthorizationFlatResource } from 'fhir-data-utils-ts';
+export type EquipmentComplianceAction = 'record-calibration' | 'publish-operating-authorization';
+export type EquipmentComplianceActorContext = Readonly<{
+    actorReference: string;
+    departmentReference: string;
+}>;
+export type EquipmentComplianceDecision = EquipmentComplianceActorContext & Readonly<{
+    action: EquipmentComplianceAction;
+}>;
+/**
+ * Runtime-neutral authorization boundary for equipment compliance records.
+ * Products decide whether the authenticated assignment in its department may perform the action;
+ * the shared SDK never infers authority from a job-title string.
+ */
+export interface EquipmentComplianceAuthorizer {
+    authorize(decision: EquipmentComplianceDecision): boolean;
+}
+type CalibrationInput = Parameters<typeof buildDeviceCalibrationFlatGraph>[0];
+type OperatingAuthorizationInput = Parameters<typeof buildDeviceOperatingAuthorizationFlatResource>[0];
+/** Prepares standard claims-first records after an explicit product authorization decision. */
+export declare class EquipmentComplianceManager {
+    private readonly authorizer;
+    constructor(authorizer: EquipmentComplianceAuthorizer);
+    prepareCalibration(input: CalibrationInput, actorContext: EquipmentComplianceActorContext): readonly Readonly<{
+        resourceType: "DocumentReference" | "Procedure" | "DeviceMetric" | "RegulatedAuthorization";
+        id: string;
+        meta: Readonly<{
+            claims: Readonly<Record<string, string>>;
+        }>;
+    }>[];
+    prepareOperatingAuthorization(input: OperatingAuthorizationInput, actorContext: EquipmentComplianceActorContext): Readonly<{
+        resourceType: "DocumentReference" | "Procedure" | "DeviceMetric" | "RegulatedAuthorization";
+        id: string;
+        meta: Readonly<{
+            claims: Readonly<Record<string, string>>;
+        }>;
+    }>;
+}
+export {};

package/dist/equipment-compliance-orchestration.js

@@ -0,0 +1,18 @@
+import { buildDeviceCalibrationFlatGraph, buildDeviceOperatingAuthorizationFlatResource, } from 'fhir-data-utils-ts';
+/** Prepares standard claims-first records after an explicit product authorization decision. */
+export class EquipmentComplianceManager {
+    constructor(authorizer) {
+        this.authorizer = authorizer;
+    }
+    prepareCalibration(input, actorContext) {
+        if (!this.authorizer.authorize({ action: 'record-calibration', ...actorContext }))
+            throw new Error('equipment_calibration_forbidden');
+        return buildDeviceCalibrationFlatGraph(input);
+    }
+    prepareOperatingAuthorization(input, actorContext) {
+        if (!this.authorizer.authorize({ action: 'publish-operating-authorization', ...actorContext })) {
+            throw new Error('equipment_operating_authorization_forbidden');
+        }
+        return buildDeviceOperatingAuthorizationFlatResource(input);
+    }
+}

package/dist/index.d.ts

@@ -6,3 +6,5 @@ export * from './emergency-authorization.js';
 export * from './care-emergency-alert-orchestration.js';
 export * from './place-card-association.js';
 export * from './secure-message-crypto.js';
+export * from './equipment-compliance-orchestration.js';
+export * from './communication-bundle.js';

package/dist/index.js

@@ -5,3 +5,5 @@ export * from './emergency-authorization.js';
 export * from './care-emergency-alert-orchestration.js';
 export * from './place-card-association.js';
 export * from './secure-message-crypto.js';
+export * from './equipment-compliance-orchestration.js';
+export * from './communication-bundle.js';

package/docs/CARE_EMERGENCY_AND_ALERT_ORCHESTRATION.md

@@ -71,12 +71,13 @@ owner and returns only stable references plus the protected thread
 correlation. The product server must still resolve the current encrypted
 recipient endpoints and signaling transport.
 
-The initial Group is the service queue, not a document author or a human
-sender. Once accepted, `Task.owner` is the acting `PractitionerRole`; that role
-is also the Communication/call sender. Controller/member replies are addressed
-to the stable department Group route retained by the protected thread. The
-legal Organization remains the author of any later clinical document, and its
-professional attester and authenticated transport actor remain separate.
+The department Organization is the FHIR `Communication.sender`. Once accepted,
+`Task.owner` is the acting `PractitionerRole`. The PractitionerRole is the authenticated transport actor
+and call initiator, not the FHIR sender. The
+Group remains the reply queue retained by the protected thread, never the
+sender. The legal parent Organization remains the author of any later clinical
+document, and its professional attester remains separate from every transport
+coordinate.
 
 ## 3. Governed alerts
 

package/docs/COMMUNICATION_BUNDLE_EDITOR_READER.md

@@ -0,0 +1,84 @@
+# Communication Bundle editor and reader
+
+`sos-sdk-core-ts` owns the high-level extension shared unchanged by SOS, Vet
+and UHC. It extends the existing `gdc-common-utils-ts` `BundleEditor`,
+`BundleReader` and `CommunicationAttachedBundleSession`; it does not create a
+parallel editor lifecycle. `fhir-data-utils-ts` owns neutral FHIR types,
+import/materialization, validation and flat-claim projections.
+
+The invariant is always:
+
+```text
+outer Bundle[type=batch, entry[]]
+└── Communication resource.meta.claims
+    └── Communication.content-attachment-data[application/fhir+json]
+        └── inner Bundle[type=document|batch|collection, data[]]
+            ├── Appointment / Observation / ... flat claims
+            └── DocumentReference[PDF | image | audio | text/calendar] flat claims
+```
+
+Use `document` only when the first resource is Composition. Use `batch` only
+when every inner entry carries its executable request. Use `collection` for an
+unordered group such as an Appointment and its calendar attachment.
+
+## Author
+
+```ts
+import { CommunicationBundleEditor } from 'sos-sdk-core-ts'
+
+const outerBatch = new CommunicationBundleEditor()
+  .newCommunication()
+  .setIdentifier(communicationIdentifier)
+  .setStatus('completed')
+  .setSubject(subjectReference)
+  .setSender(departmentOrganizationReference)
+  .setRecipients(recipientReferences)
+  .setInnerBundleType('collection')
+  .addResource(appointment)
+  .addAttachmentDocument({
+    identifier: calendarDocumentIdentifier,
+    subjectReference,
+    contentType: 'text/calendar',
+    dataBase64: calendarDataBase64,
+    title: 'appointment.ics',
+    eventReferences: [appointmentReference],
+  })
+  .doneCommunication()
+  .build()
+```
+
+`addAttachmentDocument(...)` deliberately has no direct-Communication mode.
+The only Communication attachment is the serialized inner Bundle. At an
+explicit FHIR R4/R5 wire boundary, `fhir-data-utils-ts` materializes these
+canonical claims as native `Communication.payload.contentAttachment` and native
+inner resources; the editor itself remains release-neutral and claims-first.
+
+## Read
+
+```ts
+import { CommunicationBundleReader } from 'sos-sdk-core-ts'
+
+const message = new CommunicationBundleReader(receivedOuterBatch)
+  .openCommunication(0)
+
+const appointment = message.getAppointments()[0]
+const calendarDocument = message.getDocumentReferences()[0]
+const sender = message.getSender()
+const recipients = message.getRecipients()
+```
+
+The reader fails closed for a bare Appointment, a direct PDF/calendar/audio
+payload, an invalid document order, a batch entry without a request, or an
+outer resource that is not a batch Bundle.
+
+## Boundaries
+
+- The department Organization may be the FHIR Communication sender; the
+  authenticated professional/device remains separate transport evidence.
+- DIDComm, ML-KEM recipient encryption, WebRTC signaling, endpoint resolution,
+  retry and persistence stay in runtime packages.
+- GW persistence receives independently projected flat-claim resources. Direct
+  claims CRUD is an internal storage boundary, not the participant wire format.
+- The SOS editor subclasses the established GDC Bundle editor/reader and the
+  attached-Bundle session. A future antifraud-common implementation can replace
+  that base behind this shared SOS API without migrating Vet and UHC separately.

package/docs/EQUIPMENT_COMPLIANCE.md

@@ -0,0 +1,43 @@
+# Equipment compliance orchestration
+
+`EquipmentComplianceManager` is the shared SOS/Vet/UHC application boundary for equipment records.
+
+- `prepareCalibration(...)` creates a claims-first FHIR R5 graph: a completed `Procedure`, the resulting `DeviceMetric` calibration state, and an optional hashed `DocumentReference`.
+- `prepareOperatingAuthorization(...)` creates a separate claims-first `RegulatedAuthorization` issued by the competent authority.
+- The caller supplies an authorization adapter. The SDK does not infer permission from occupation labels; products evaluate the authenticated organization, assignment, group and jurisdictional policy.
+- These methods prepare records only. A BFF sends them through the high-level SDK to the GW; native FHIR is materialized only at an explicit export boundary.
+
+```ts
+const equipmentCompliance = new EquipmentComplianceManager({
+  authorize: action => authorizationPolicy.allows(authenticatedAssignment, action),
+})
+
+const calibrationRecords = equipmentCompliance.prepareCalibration(calibrationInput, {
+  actorReference: authenticatedAssignment.practitionerRoleReference,
+  departmentReference: authenticatedAssignment.departmentReference,
+})
+```
+
+A `Device` is an optional `Schedule.actor` only when the service capacity really
+depends on that specific machine, such as an apheresis station. Most schedules
+need only the `HealthcareService` and independently reservable `Location` or
+professional capacity. Device failure is an equipment event/state change; the
+booking workflow separately marks only the affected future slots unavailable
+and reconciles their appointments. It must not cancel unrelated schedules.
+
+## Deferred blood-bank product work
+
+The following is backlog for Vet, UHC and SOS products when an organization has
+a blood-bank or blood-donation department. It is not part of this SDK release:
+
+- product policy for trained nurses and Canadian `Donor Care Associate`
+  assignments to record governed calibration checks;
+- department panels for calibrating apheresis machines and donation scales;
+- collection-sample labels and blood/plasma product labels using the applicable
+  ISBT 128 data structures and official ICCBBA tables;
+- separate `Specimen` and `BiologicallyDerivedProduct` projections, scanning,
+  printing, chain-of-identity and audit tests.
+
+`Donor Care Associate` is retained as the employer/assignment role and is not
+silently mapped to nurse or nursing assistant. Authorization depends on the
+verified assignment, training and department policy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-core-ts",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Runtime-neutral shared orchestration for SOS, Vet and UHC products",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -35,6 +35,14 @@
     "./secure-message-crypto": {
       "types": "./dist/secure-message-crypto.d.ts",
       "default": "./dist/secure-message-crypto.js"
+    },
+    "./equipment-compliance-orchestration": {
+      "types": "./dist/equipment-compliance-orchestration.d.ts",
+      "default": "./dist/equipment-compliance-orchestration.js"
+    },
+    "./communication-bundle": {
+      "types": "./dist/communication-bundle.d.ts",
+      "default": "./dist/communication-bundle.js"
     }
   },
   "files": [
@@ -55,8 +63,9 @@
     "@noble/ciphers": "2.4.0",
     "@noble/hashes": "2.4.0",
     "@noble/post-quantum": "0.7.1",
-    "fhir-data-utils-ts": "0.3.7",
-    "sos-data-utils-ts": "0.4.2"
+    "fhir-data-utils-ts": "0.6.0",
+    "gdc-common-utils-ts": "2.9.21",
+    "sos-data-utils-ts": "0.5.1"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",