@futdevpro/nts-dynamo 1.15.139 → 1.15.141

package/src/_modules/privacy-lifecycle/_models/privacy-legal-acceptance.interface.ts

@@ -0,0 +1,13 @@
+/** Immutable proof that a subject accepted one exact legal document version. */
+export interface DyNTS_PrivacyLegalAcceptance_Interface {
+  acceptanceId: string;
+  subjectId: string;
+  organizationId: string;
+  documentType: string;
+  documentVersion: string;
+  documentChecksum: string;
+  sourceCode: string;
+  idempotencyHash: string;
+  requestFingerprint: string;
+  acceptedAt: string;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-lifecycle-adapter.interface.ts

@@ -0,0 +1,19 @@
+import { DyNTS_PrivacyContributorOutcome_Interface } from './privacy-contributor-outcome.interface';
+import { DyNTS_PrivacyContributorPlan_Interface } from './privacy-contributor-plan.interface';
+import {
+  DyNTS_PrivacyRequestPersistenceCreateResult_Interface
+} from './privacy-request-persistence-create-result.interface';
+import { DyNTS_PrivacyRequestRecord_Interface } from './privacy-request-record.interface';
+
+/** Atomic persistence contract for the cross-domain privacy lifecycle. */
+export interface DyNTS_PrivacyLifecycleAdapter_Interface {
+  createOrGetRequest(
+    request: DyNTS_PrivacyRequestRecord_Interface
+  ): Promise<DyNTS_PrivacyRequestPersistenceCreateResult_Interface>;
+  findRequestById(requestId: string): Promise<DyNTS_PrivacyRequestRecord_Interface | null>;
+  replaceRequest(request: DyNTS_PrivacyRequestRecord_Interface, expectedRevision: number): Promise<boolean>;
+  saveContributorPlan(requestId: string, plan: DyNTS_PrivacyContributorPlan_Interface): Promise<void>;
+  listContributorPlans(requestId: string): Promise<DyNTS_PrivacyContributorPlan_Interface[]>;
+  saveContributorOutcome(requestId: string, outcome: DyNTS_PrivacyContributorOutcome_Interface): Promise<void>;
+  listContributorOutcomes(requestId: string): Promise<DyNTS_PrivacyContributorOutcome_Interface[]>;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-lifecycle-settings.interface.ts

@@ -0,0 +1,9 @@
+import { DyNTS_PrivacyContributor_Interface } from './privacy-contributor.interface';
+import { DyNTS_PrivacyLifecycleAdapter_Interface } from './privacy-lifecycle-adapter.interface';
+
+/** Dependencies and deterministic time source for the privacy lifecycle orchestrator. */
+export interface DyNTS_PrivacyLifecycleSettings_Interface {
+  adapter: DyNTS_PrivacyLifecycleAdapter_Interface;
+  contributors: DyNTS_PrivacyContributor_Interface[];
+  clock?: () => Date;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-request-create-result.interface.ts

@@ -0,0 +1,7 @@
+import { DyNTS_PrivacyRequestView_Interface } from './privacy-request-view.interface';
+
+/** Atomic create-or-replay result for an idempotent privacy request. */
+export interface DyNTS_PrivacyRequestCreateResult_Interface {
+  request: DyNTS_PrivacyRequestView_Interface;
+  created: boolean;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-request-open.interface.ts

@@ -0,0 +1,10 @@
+import { DyNTS_PrivacyRequest_Type } from '../_enums/privacy-request.type-enum';
+
+/** Subject-scoped input for opening an idempotent privacy request. */
+export interface DyNTS_PrivacyRequestOpen_Interface {
+  subjectId: string;
+  organizationId: string;
+  type: DyNTS_PrivacyRequest_Type;
+  idempotencyKey: string;
+  deadlineAt: string;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-request-persistence-create-result.interface.ts

@@ -0,0 +1,7 @@
+import { DyNTS_PrivacyRequestRecord_Interface } from './privacy-request-record.interface';
+
+/** Adapter-only create-or-replay result retaining server-side persistence metadata. */
+export interface DyNTS_PrivacyRequestPersistenceCreateResult_Interface {
+  request: DyNTS_PrivacyRequestRecord_Interface;
+  created: boolean;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-request-record.interface.ts

@@ -0,0 +1,21 @@
+import { DyNTS_PrivacyRequestState_Type } from '../_enums/privacy-request-state.type-enum';
+import { DyNTS_PrivacyRequest_Type } from '../_enums/privacy-request.type-enum';
+
+/** Central request record. It intentionally carries identifiers and lifecycle metadata only. */
+export interface DyNTS_PrivacyRequestRecord_Interface {
+  requestId: string;
+  subjectId: string;
+  organizationId: string;
+  type: DyNTS_PrivacyRequest_Type;
+  state: DyNTS_PrivacyRequestState_Type;
+  idempotencyHash: string;
+  revision: number;
+  createdAt: string;
+  deadlineAt: string;
+  identityVerifiedAt: string;
+  scopedAt: string;
+  plannedAt: string;
+  executionStartedAt: string;
+  verifyingStartedAt: string;
+  completedAt: string;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-request-result.interface.ts

@@ -0,0 +1,8 @@
+import { DyNTS_PrivacyContributorOutcome_Interface } from './privacy-contributor-outcome.interface';
+import { DyNTS_PrivacyRequestView_Interface } from './privacy-request-view.interface';
+
+/** Safe lifecycle response containing request metadata and content-free contributor outcomes. */
+export interface DyNTS_PrivacyRequestResult_Interface {
+  request: DyNTS_PrivacyRequestView_Interface;
+  outcomes: DyNTS_PrivacyContributorOutcome_Interface[];
+}

package/src/_modules/privacy-lifecycle/_models/privacy-request-view.interface.ts

@@ -0,0 +1,20 @@
+import { DyNTS_PrivacyRequestState_Type } from '../_enums/privacy-request-state.type-enum';
+import { DyNTS_PrivacyRequest_Type } from '../_enums/privacy-request.type-enum';
+
+/** User-safe request projection without persistence idempotency metadata. */
+export interface DyNTS_PrivacyRequestView_Interface {
+  requestId: string;
+  subjectId: string;
+  organizationId: string;
+  type: DyNTS_PrivacyRequest_Type;
+  state: DyNTS_PrivacyRequestState_Type;
+  revision: number;
+  createdAt: string;
+  deadlineAt: string;
+  identityVerifiedAt: string;
+  scopedAt: string;
+  plannedAt: string;
+  executionStartedAt: string;
+  verifyingStartedAt: string;
+  completedAt: string;
+}

package/src/_modules/privacy-lifecycle/index.ts

@@ -0,0 +1,40 @@
+export { DyNTS_PrivacyLifecycle_ControlService } from './privacy-lifecycle.control-service';
+export { DyNTS_PrivacyLedger_ControlService } from './privacy-ledger.control-service';
+export { DyNTS_PrivacyConsentDecision_Type } from './_enums/privacy-consent-decision.type-enum';
+export { DyNTS_PrivacyContributorAction_Type } from './_enums/privacy-contributor-action.type-enum';
+export { DyNTS_PrivacyContributorOutcome_Type } from './_enums/privacy-contributor-outcome.type-enum';
+export { DyNTS_PrivacyRequestState_Type } from './_enums/privacy-request-state.type-enum';
+export { DyNTS_PrivacyRequest_Type } from './_enums/privacy-request.type-enum';
+export { DyNTS_PrivacyContributorContext_Interface } from './_models/privacy-contributor-context.interface';
+export { DyNTS_PrivacyContributorOutcome_Interface } from './_models/privacy-contributor-outcome.interface';
+export { DyNTS_PrivacyContributorPlan_Interface } from './_models/privacy-contributor-plan.interface';
+export { DyNTS_PrivacyContributor_Interface } from './_models/privacy-contributor.interface';
+export { DyNTS_PrivacyLifecycleAdapter_Interface } from './_models/privacy-lifecycle-adapter.interface';
+export { DyNTS_PrivacyLifecycleSettings_Interface } from './_models/privacy-lifecycle-settings.interface';
+export { DyNTS_PrivacyConsentInput_Interface } from './_models/privacy-consent-input.interface';
+export {
+  DyNTS_PrivacyConsentPersistenceResult_Interface
+} from './_models/privacy-consent-persistence-result.interface';
+export { DyNTS_PrivacyConsentRecord_Interface } from './_models/privacy-consent-record.interface';
+export { DyNTS_PrivacyConsentResult_Interface } from './_models/privacy-consent-result.interface';
+export { DyNTS_PrivacyConsentView_Interface } from './_models/privacy-consent-view.interface';
+export { DyNTS_PrivacyLedgerAdapter_Interface } from './_models/privacy-ledger-adapter.interface';
+export { DyNTS_PrivacyLedgerResult_Interface } from './_models/privacy-ledger-result.interface';
+export { DyNTS_PrivacyLedgerSettings_Interface } from './_models/privacy-ledger-settings.interface';
+export { DyNTS_PrivacyLegalAcceptanceInput_Interface } from './_models/privacy-legal-acceptance-input.interface';
+export {
+  DyNTS_PrivacyLegalAcceptancePersistenceResult_Interface
+} from './_models/privacy-legal-acceptance-persistence-result.interface';
+export { DyNTS_PrivacyLegalAcceptanceResult_Interface } from './_models/privacy-legal-acceptance-result.interface';
+export {
+  DyNTS_PrivacyLegalAcceptanceView_Interface
+} from './_models/privacy-legal-acceptance-view.interface';
+export { DyNTS_PrivacyLegalAcceptance_Interface } from './_models/privacy-legal-acceptance.interface';
+export { DyNTS_PrivacyRequestCreateResult_Interface } from './_models/privacy-request-create-result.interface';
+export { DyNTS_PrivacyRequestOpen_Interface } from './_models/privacy-request-open.interface';
+export {
+  DyNTS_PrivacyRequestPersistenceCreateResult_Interface
+} from './_models/privacy-request-persistence-create-result.interface';
+export { DyNTS_PrivacyRequestRecord_Interface } from './_models/privacy-request-record.interface';
+export { DyNTS_PrivacyRequestResult_Interface } from './_models/privacy-request-result.interface';
+export { DyNTS_PrivacyRequestView_Interface } from './_models/privacy-request-view.interface';

package/src/_modules/privacy-lifecycle/privacy-ledger.control-service.spec.ts

@@ -0,0 +1,206 @@
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_PrivacyLedger_ControlService } from './privacy-ledger.control-service';
+import { DyNTS_PrivacyConsentDecision_Type } from './_enums/privacy-consent-decision.type-enum';
+import { DyNTS_PrivacyConsentRecord_Interface } from './_models/privacy-consent-record.interface';
+import {
+  DyNTS_PrivacyConsentPersistenceResult_Interface
+} from './_models/privacy-consent-persistence-result.interface';
+import { DyNTS_PrivacyConsentResult_Interface } from './_models/privacy-consent-result.interface';
+import { DyNTS_PrivacyLedgerAdapter_Interface } from './_models/privacy-ledger-adapter.interface';
+import { DyNTS_PrivacyLedgerResult_Interface } from './_models/privacy-ledger-result.interface';
+import { DyNTS_PrivacyLegalAcceptanceResult_Interface } from './_models/privacy-legal-acceptance-result.interface';
+import { DyNTS_PrivacyLegalAcceptance_Interface } from './_models/privacy-legal-acceptance.interface';
+import {
+  DyNTS_PrivacyLegalAcceptancePersistenceResult_Interface
+} from './_models/privacy-legal-acceptance-persistence-result.interface';
+
+class DyNTS_TestPrivacyLedgerAdapter implements DyNTS_PrivacyLedgerAdapter_Interface {
+  private readonly legal: Map<string, DyNTS_PrivacyLegalAcceptance_Interface> = new Map();
+  private readonly consent: Map<string, DyNTS_PrivacyConsentRecord_Interface> = new Map();
+
+  /** Atomically appends or replays a legal acceptance by idempotency hash. */
+  public async appendLegalAcceptance(
+    acceptance: DyNTS_PrivacyLegalAcceptance_Interface
+  ): Promise<DyNTS_PrivacyLegalAcceptancePersistenceResult_Interface> {
+    const existing: DyNTS_PrivacyLegalAcceptance_Interface | undefined = this.legal.get(acceptance.idempotencyHash);
+
+    if (existing) {
+      return { acceptance: { ...existing }, created: false };
+    }
+
+    this.legal.set(acceptance.idempotencyHash, { ...acceptance });
+
+    return { acceptance: { ...acceptance }, created: true };
+  }
+
+  /** Atomically appends or replays a consent event by idempotency hash. */
+  public async appendConsent(
+    record: DyNTS_PrivacyConsentRecord_Interface
+  ): Promise<DyNTS_PrivacyConsentPersistenceResult_Interface> {
+    const existing: DyNTS_PrivacyConsentRecord_Interface | undefined = this.consent.get(record.idempotencyHash);
+
+    if (existing) {
+      return { consent: { ...existing }, created: false };
+    }
+
+    this.consent.set(record.idempotencyHash, { ...record });
+
+    return { consent: { ...record }, created: true };
+  }
+
+  /** Lists legal acceptances within one exact subject and organization boundary. */
+  public async listLegalAcceptances(
+    subjectId: string,
+    organizationId: string
+  ): Promise<DyNTS_PrivacyLegalAcceptance_Interface[]> {
+    return Array.from(this.legal.values())
+      .filter((item: DyNTS_PrivacyLegalAcceptance_Interface): boolean => (
+        item.subjectId === subjectId && item.organizationId === organizationId
+      ));
+  }
+
+  /** Lists consent history within one exact subject and organization boundary. */
+  public async listConsentHistory(
+    subjectId: string,
+    organizationId: string
+  ): Promise<DyNTS_PrivacyConsentRecord_Interface[]> {
+    return Array.from(this.consent.values())
+      .filter((item: DyNTS_PrivacyConsentRecord_Interface): boolean => (
+        item.subjectId === subjectId && item.organizationId === organizationId
+      ));
+  }
+}
+
+describe('| DyNTS_PrivacyLedger_ControlService', (): void => {
+  let service: DyNTS_PrivacyLedger_ControlService;
+
+  beforeEach((): void => {
+    service = new DyNTS_PrivacyLedger_ControlService({
+      adapter: new DyNTS_TestPrivacyLedgerAdapter(),
+      clock: (): Date => new Date('2026-08-18T10:00:00.000Z'),
+    });
+  });
+
+  it('| appends exact legal-document evidence idempotently without raw keys', async (): Promise<void> => {
+    const first: DyNTS_PrivacyLegalAcceptanceResult_Interface = await acceptTerms(service);
+    const replay: DyNTS_PrivacyLegalAcceptanceResult_Interface = await acceptTerms(service);
+
+    expect(first.created).toBeTrue();
+    expect(replay.created).toBeFalse();
+    expect(replay.acceptance.acceptanceId).toBe(first.acceptance.acceptanceId);
+    expect(JSON.stringify(first.acceptance)).not.toContain('idempotencyHash');
+    expect(JSON.stringify(first.acceptance)).not.toContain('requestFingerprint');
+    expect(first.acceptance.documentChecksum).toBe('a'.repeat(64));
+  });
+
+  it('| keeps consent history and resolves the latest decision per purpose', async (): Promise<void> => {
+    await recordConsent(service, {
+      decision: DyNTS_PrivacyConsentDecision_Type.granted,
+      policyVersion: 'policy-v1',
+      idempotencyKey: 'grant-key',
+    });
+    await recordConsent(service, {
+      decision: DyNTS_PrivacyConsentDecision_Type.withdrawn,
+      policyVersion: 'policy-v1',
+      idempotencyKey: 'withdraw-key',
+    });
+    const ledger: DyNTS_PrivacyLedgerResult_Interface = await service.getLedger('subject-1', 'organization-1');
+
+    expect(ledger.consentHistory.length).toBe(2);
+    expect(ledger.currentConsents.length).toBe(1);
+    expect(ledger.currentConsents[0].decision).toBe(DyNTS_PrivacyConsentDecision_Type.withdrawn);
+  });
+
+  it('| treats a policy-version upgrade as a distinct auditable consent event', async (): Promise<void> => {
+    await recordConsent(service, {
+      decision: DyNTS_PrivacyConsentDecision_Type.granted,
+      policyVersion: 'policy-v1',
+      idempotencyKey: 'v1-key',
+    });
+    await recordConsent(service, {
+      decision: DyNTS_PrivacyConsentDecision_Type.granted,
+      policyVersion: 'policy-v2',
+      idempotencyKey: 'v2-key',
+    });
+    const ledger: DyNTS_PrivacyLedgerResult_Interface = await service.getLedger('subject-1', 'organization-1');
+
+    expect(ledger.consentHistory.map((item: DyNTS_PrivacyConsentRecord_Interface): string => (
+      item.policyVersion
+    ))).toEqual([ 'policy-v1', 'policy-v2' ]);
+    expect(ledger.currentConsents[0].policyVersion).toBe('policy-v2');
+  });
+
+  it('| rejects unverifiable legal document checksums', async (): Promise<void> => {
+    await expectAsync(service.acceptLegalDocument({
+      subjectId: 'subject-1',
+      organizationId: 'organization-1',
+      documentType: 'terms',
+      documentVersion: 'v1',
+      documentChecksum: 'not-a-sha256',
+      sourceCode: 'registration',
+      idempotencyKey: 'legal-key',
+    })).toBeRejectedWithError(DyFM_Error);
+  });
+
+  it('| rejects idempotency-key reuse with different legal content', async (): Promise<void> => {
+    await acceptTerms(service);
+
+    const error: DyFM_Error = await captureError(service.acceptLegalDocument({
+      subjectId: 'subject-1',
+      organizationId: 'organization-1',
+      documentType: 'terms',
+      documentVersion: 'v2',
+      documentChecksum: 'b'.repeat(64),
+      sourceCode: 'registration',
+      idempotencyKey: 'legal-key',
+    }));
+
+    expect(error._errorCode).toContain('IDEMPOTENCY_CONFLICT');
+  });
+});
+
+async function acceptTerms(
+  service: DyNTS_PrivacyLedger_ControlService
+): Promise<DyNTS_PrivacyLegalAcceptanceResult_Interface> {
+  return service.acceptLegalDocument({
+    subjectId: 'subject-1',
+    organizationId: 'organization-1',
+    documentType: 'terms',
+    documentVersion: 'v1',
+    documentChecksum: 'a'.repeat(64),
+    sourceCode: 'registration',
+    idempotencyKey: 'legal-key',
+  });
+}
+
+async function recordConsent(
+  service: DyNTS_PrivacyLedger_ControlService,
+  set: {
+    decision: DyNTS_PrivacyConsentDecision_Type;
+    policyVersion: string;
+    idempotencyKey: string;
+  }
+): Promise<DyNTS_PrivacyConsentResult_Interface> {
+  return service.recordConsent({
+    subjectId: 'subject-1',
+    organizationId: 'organization-1',
+    purposeCode: 'product-improvement',
+    policyVersion: set.policyVersion,
+    decision: set.decision,
+    sourceCode: 'privacy-center',
+    idempotencyKey: set.idempotencyKey,
+  });
+}
+
+async function captureError(promise: Promise<unknown>): Promise<DyFM_Error> {
+  try {
+    await promise;
+  } catch (error: unknown) {
+    if (error instanceof DyFM_Error) {
+      return error;
+    }
+  }
+
+  throw new Error('Expected a DyFM_Error rejection.');
+}

package/src/_modules/privacy-lifecycle/privacy-ledger.control-service.ts

@@ -0,0 +1,253 @@
+import {
+  createHash,
+  randomUUID
+} from 'crypto';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_global_settings } from '../../_collections/global-settings.const';
+import { DyNTS_PrivacyConsentDecision_Type } from './_enums/privacy-consent-decision.type-enum';
+import { DyNTS_PrivacyConsentInput_Interface } from './_models/privacy-consent-input.interface';
+import {
+  DyNTS_PrivacyConsentPersistenceResult_Interface
+} from './_models/privacy-consent-persistence-result.interface';
+import { DyNTS_PrivacyConsentRecord_Interface } from './_models/privacy-consent-record.interface';
+import { DyNTS_PrivacyConsentResult_Interface } from './_models/privacy-consent-result.interface';
+import { DyNTS_PrivacyConsentView_Interface } from './_models/privacy-consent-view.interface';
+import { DyNTS_PrivacyLedgerAdapter_Interface } from './_models/privacy-ledger-adapter.interface';
+import { DyNTS_PrivacyLedgerResult_Interface } from './_models/privacy-ledger-result.interface';
+import { DyNTS_PrivacyLedgerSettings_Interface } from './_models/privacy-ledger-settings.interface';
+import { DyNTS_PrivacyLegalAcceptanceInput_Interface } from './_models/privacy-legal-acceptance-input.interface';
+import {
+  DyNTS_PrivacyLegalAcceptancePersistenceResult_Interface
+} from './_models/privacy-legal-acceptance-persistence-result.interface';
+import { DyNTS_PrivacyLegalAcceptanceResult_Interface } from './_models/privacy-legal-acceptance-result.interface';
+import {
+  DyNTS_PrivacyLegalAcceptanceView_Interface
+} from './_models/privacy-legal-acceptance-view.interface';
+import { DyNTS_PrivacyLegalAcceptance_Interface } from './_models/privacy-legal-acceptance.interface';
+
+/** Maintains immutable legal acceptance and purpose-specific consent evidence. */
+export class DyNTS_PrivacyLedger_ControlService {
+  private readonly adapter: DyNTS_PrivacyLedgerAdapter_Interface;
+  private readonly clock: () => Date;
+
+  /** Creates a privacy ledger over an append-only persistence adapter. */
+  constructor(set: DyNTS_PrivacyLedgerSettings_Interface) {
+    this.adapter = set.adapter;
+    this.clock = set.clock ?? ((): Date => new Date());
+
+    if (!this.adapter) {
+      throw this.buildError(500, 'SETTINGS_INVALID', 'The privacy ledger settings are invalid.');
+    }
+  }
+
+  /** Appends or replays acceptance of one exact checksummed legal document version. */
+  public async acceptLegalDocument(
+    set: DyNTS_PrivacyLegalAcceptanceInput_Interface
+  ): Promise<DyNTS_PrivacyLegalAcceptanceResult_Interface> {
+    this.validateCommon(set);
+
+    if (
+      !this.isSafeCode(set.documentType)
+      || !this.isSafeCode(set.documentVersion)
+      || !/^[a-f0-9]{64}$/u.test(set.documentChecksum)
+    ) {
+      throw this.buildError(400, 'LEGAL_ACCEPTANCE_INVALID', 'The legal acceptance is invalid.');
+    }
+
+    const acceptance: DyNTS_PrivacyLegalAcceptance_Interface = {
+      acceptanceId: randomUUID(),
+      subjectId: set.subjectId,
+      organizationId: set.organizationId,
+      documentType: set.documentType,
+      documentVersion: set.documentVersion,
+      documentChecksum: set.documentChecksum,
+      sourceCode: set.sourceCode,
+      idempotencyHash: this.hashInput('legal', set),
+      requestFingerprint: this.hashContent([
+        set.documentType,
+        set.documentVersion,
+        set.documentChecksum,
+        set.sourceCode,
+      ]),
+      acceptedAt: this.clock().toISOString(),
+    };
+    const result: DyNTS_PrivacyLegalAcceptancePersistenceResult_Interface =
+      await this.adapter.appendLegalAcceptance(acceptance);
+
+    if (
+      result.acceptance.requestFingerprint !== acceptance.requestFingerprint
+      || result.acceptance.idempotencyHash !== acceptance.idempotencyHash
+      || result.acceptance.subjectId !== acceptance.subjectId
+      || result.acceptance.organizationId !== acceptance.organizationId
+    ) {
+      throw this.buildError(409, 'IDEMPOTENCY_CONFLICT', 'The idempotency key belongs to another ledger event.');
+    }
+
+    return { acceptance: this.toLegalView(result.acceptance), created: result.created };
+  }
+
+  /** Appends or replays a purpose-specific consent grant or withdrawal. */
+  public async recordConsent(
+    set: DyNTS_PrivacyConsentInput_Interface
+  ): Promise<DyNTS_PrivacyConsentResult_Interface> {
+    this.validateCommon(set);
+
+    if (
+      !this.isSafeCode(set.purposeCode)
+      || !this.isSafeCode(set.policyVersion)
+      || !Object.values(DyNTS_PrivacyConsentDecision_Type).includes(set.decision)
+    ) {
+      throw this.buildError(400, 'CONSENT_INVALID', 'The consent decision is invalid.');
+    }
+
+    const consent: DyNTS_PrivacyConsentRecord_Interface = {
+      consentId: randomUUID(),
+      subjectId: set.subjectId,
+      organizationId: set.organizationId,
+      purposeCode: set.purposeCode,
+      policyVersion: set.policyVersion,
+      decision: set.decision,
+      sourceCode: set.sourceCode,
+      idempotencyHash: this.hashInput('consent', set),
+      requestFingerprint: this.hashContent([
+        set.purposeCode,
+        set.policyVersion,
+        set.decision,
+        set.sourceCode,
+      ]),
+      occurredAt: this.clock().toISOString(),
+    };
+    const result: DyNTS_PrivacyConsentPersistenceResult_Interface = await this.adapter.appendConsent(consent);
+
+    if (
+      result.consent.requestFingerprint !== consent.requestFingerprint
+      || result.consent.idempotencyHash !== consent.idempotencyHash
+      || result.consent.subjectId !== consent.subjectId
+      || result.consent.organizationId !== consent.organizationId
+    ) {
+      throw this.buildError(409, 'IDEMPOTENCY_CONFLICT', 'The idempotency key belongs to another ledger event.');
+    }
+
+    return { consent: this.toConsentView(result.consent), created: result.created };
+  }
+
+  /** Returns immutable history plus the latest decision for every purpose. */
+  public async getLedger(subjectId: string, organizationId: string): Promise<DyNTS_PrivacyLedgerResult_Interface> {
+    if (!subjectId || !organizationId) {
+      throw this.buildError(400, 'LEDGER_OWNER_INVALID', 'The privacy ledger owner is invalid.');
+    }
+
+    const legalAcceptances: DyNTS_PrivacyLegalAcceptance_Interface[] =
+      await this.adapter.listLegalAcceptances(subjectId, organizationId);
+    const consentHistory: DyNTS_PrivacyConsentRecord_Interface[] =
+      await this.adapter.listConsentHistory(subjectId, organizationId);
+
+    if (
+      legalAcceptances.some((item: DyNTS_PrivacyLegalAcceptance_Interface): boolean => (
+        item.subjectId !== subjectId || item.organizationId !== organizationId
+      ))
+      || consentHistory.some((item: DyNTS_PrivacyConsentRecord_Interface): boolean => (
+        item.subjectId !== subjectId || item.organizationId !== organizationId
+      ))
+    ) {
+      throw this.buildError(500, 'LEDGER_SCOPE_VIOLATION', 'The privacy ledger returned an invalid scope.');
+    }
+    const consentViews: DyNTS_PrivacyConsentView_Interface[] = consentHistory.map((
+      item: DyNTS_PrivacyConsentRecord_Interface
+    ): DyNTS_PrivacyConsentView_Interface => this.toConsentView(item));
+    const currentByPurpose: Map<string, DyNTS_PrivacyConsentView_Interface> = new Map();
+
+    consentViews.forEach((record: DyNTS_PrivacyConsentView_Interface): void => {
+      currentByPurpose.set(record.purposeCode, { ...record });
+    });
+
+    return {
+      legalAcceptances: [ ...legalAcceptances ].map((
+        item: DyNTS_PrivacyLegalAcceptance_Interface
+      ): DyNTS_PrivacyLegalAcceptanceView_Interface => this.toLegalView(item)),
+      consentHistory: consentViews,
+      currentConsents: Array.from(currentByPurpose.values())
+        .sort((
+          first: DyNTS_PrivacyConsentView_Interface,
+          second: DyNTS_PrivacyConsentView_Interface
+        ): number => first.purposeCode.localeCompare(second.purposeCode)),
+    };
+  }
+
+  private validateCommon(set: {
+    subjectId: string;
+    organizationId: string;
+    sourceCode: string;
+    idempotencyKey: string;
+  }): void {
+    if (
+      !this.isBoundedText(set.subjectId, 256)
+      || !this.isBoundedText(set.organizationId, 256)
+      || !this.isSafeCode(set.sourceCode)
+      || !this.isBoundedText(set.idempotencyKey, 256)
+    ) {
+      throw this.buildError(400, 'LEDGER_EVENT_INVALID', 'The privacy ledger event is invalid.');
+    }
+  }
+
+  private hashInput(
+    category: string,
+    set: DyNTS_PrivacyLegalAcceptanceInput_Interface | DyNTS_PrivacyConsentInput_Interface
+  ): string {
+    return createHash('sha256')
+      .update(`${category}\u0000${set.subjectId}\u0000${set.organizationId}\u0000${set.idempotencyKey}`)
+      .digest('hex');
+  }
+
+  private hashContent(parts: string[]): string {
+    return createHash('sha256').update(parts.join('\u0000')).digest('hex');
+  }
+
+  private isSafeCode(value: string): boolean {
+    return typeof value === 'string' && /^[a-zA-Z0-9._:-]{1,128}$/u.test(value);
+  }
+
+  private isBoundedText(value: string, maxLength: number): boolean {
+    return typeof value === 'string' && !!value && value.length <= maxLength && !value.includes('\u0000');
+  }
+
+  private toLegalView(
+    acceptance: DyNTS_PrivacyLegalAcceptance_Interface
+  ): DyNTS_PrivacyLegalAcceptanceView_Interface {
+    return {
+      acceptanceId: acceptance.acceptanceId,
+      subjectId: acceptance.subjectId,
+      organizationId: acceptance.organizationId,
+      documentType: acceptance.documentType,
+      documentVersion: acceptance.documentVersion,
+      documentChecksum: acceptance.documentChecksum,
+      sourceCode: acceptance.sourceCode,
+      acceptedAt: acceptance.acceptedAt,
+    };
+  }
+
+  private toConsentView(record: DyNTS_PrivacyConsentRecord_Interface): DyNTS_PrivacyConsentView_Interface {
+    return {
+      consentId: record.consentId,
+      subjectId: record.subjectId,
+      organizationId: record.organizationId,
+      purposeCode: record.purposeCode,
+      policyVersion: record.policyVersion,
+      decision: record.decision,
+      sourceCode: record.sourceCode,
+      occurredAt: record.occurredAt,
+    };
+  }
+
+  private buildError(status: number, errorCode: string, message: string): DyFM_Error {
+    return new DyFM_Error({
+      status: status,
+      errorCode: `${DyNTS_global_settings.systemShortCodeName}|PRIVACY_LEDGER|${errorCode}`,
+      message: message,
+      userMessage: status < 500 ? message : 'The privacy ledger is unavailable. Please try again later.',
+      issuerService: this.constructor.name,
+    });
+  }
+}