@futdevpro/nts-dynamo 1.15.151 → 1.15.153

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

@@ -1,10 +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;
-}
+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

@@ -1,7 +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;
-}
+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

@@ -1,21 +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;
-}
+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

@@ -1,8 +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[];
-}
+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

@@ -1,20 +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;
-}
+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

@@ -1,40 +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';
+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

@@ -1,206 +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.');
-}
+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.');
+}