@futdevpro/nts-dynamo 1.15.140 → 1.15.142

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

@@ -0,0 +1,353 @@
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_PrivacyLifecycle_ControlService } from './privacy-lifecycle.control-service';
+import { DyNTS_PrivacyContributorAction_Type } from './_enums/privacy-contributor-action.type-enum';
+import { DyNTS_PrivacyContributorOutcome_Type } from './_enums/privacy-contributor-outcome.type-enum';
+import { DyNTS_PrivacyRequestState_Type } from './_enums/privacy-request-state.type-enum';
+import { DyNTS_PrivacyRequest_Type } from './_enums/privacy-request.type-enum';
+import { DyNTS_PrivacyContributorContext_Interface } from './_models/privacy-contributor-context.interface';
+import { DyNTS_PrivacyContributorOutcome_Interface } from './_models/privacy-contributor-outcome.interface';
+import { DyNTS_PrivacyContributorPlan_Interface } from './_models/privacy-contributor-plan.interface';
+import { DyNTS_PrivacyContributor_Interface } from './_models/privacy-contributor.interface';
+import { DyNTS_PrivacyLifecycleAdapter_Interface } from './_models/privacy-lifecycle-adapter.interface';
+import { DyNTS_PrivacyRequestCreateResult_Interface } from './_models/privacy-request-create-result.interface';
+import {
+  DyNTS_PrivacyRequestPersistenceCreateResult_Interface
+} from './_models/privacy-request-persistence-create-result.interface';
+import { DyNTS_PrivacyRequestRecord_Interface } from './_models/privacy-request-record.interface';
+import { DyNTS_PrivacyRequestResult_Interface } from './_models/privacy-request-result.interface';
+
+class DyNTS_TestPrivacyAdapter implements DyNTS_PrivacyLifecycleAdapter_Interface {
+  private readonly requests: Map<string, DyNTS_PrivacyRequestRecord_Interface> = new Map();
+  private readonly idempotencyIndex: Map<string, string> = new Map();
+  private readonly plans: Map<string, Map<string, DyNTS_PrivacyContributorPlan_Interface>> = new Map();
+  private readonly outcomes: Map<string, Map<string, DyNTS_PrivacyContributorOutcome_Interface>> = new Map();
+
+  /** Atomically creates a request or returns its idempotent predecessor. */
+  public async createOrGetRequest(
+    request: DyNTS_PrivacyRequestRecord_Interface
+  ): Promise<DyNTS_PrivacyRequestPersistenceCreateResult_Interface> {
+    const existingId: string | undefined = this.idempotencyIndex.get(request.idempotencyHash);
+
+    if (existingId) {
+      return { request: this.cloneRequest(this.requests.get(existingId)), created: false };
+    }
+
+    this.requests.set(request.requestId, this.cloneRequest(request));
+    this.idempotencyIndex.set(request.idempotencyHash, request.requestId);
+
+    return { request: this.cloneRequest(request), created: true };
+  }
+
+  /** Finds a cloned request by identifier. */
+  public async findRequestById(requestId: string): Promise<DyNTS_PrivacyRequestRecord_Interface | null> {
+    const request: DyNTS_PrivacyRequestRecord_Interface | undefined = this.requests.get(requestId);
+
+    return request ? this.cloneRequest(request) : null;
+  }
+
+  /** Applies a compare-and-set request replacement. */
+  public async replaceRequest(
+    request: DyNTS_PrivacyRequestRecord_Interface,
+    expectedRevision: number
+  ): Promise<boolean> {
+    const existing: DyNTS_PrivacyRequestRecord_Interface | undefined = this.requests.get(request.requestId);
+
+    if (existing?.revision !== expectedRevision) {
+      return false;
+    }
+
+    this.requests.set(request.requestId, this.cloneRequest(request));
+
+    return true;
+  }
+
+  /** Upserts the durable test plan for one contributor. */
+  public async saveContributorPlan(
+    requestId: string,
+    plan: DyNTS_PrivacyContributorPlan_Interface
+  ): Promise<void> {
+    const requestPlans: Map<string, DyNTS_PrivacyContributorPlan_Interface> =
+      this.plans.get(requestId) ?? new Map();
+
+    requestPlans.set(plan.contributorId, { ...plan });
+    this.plans.set(requestId, requestPlans);
+  }
+
+  /** Lists cloned durable contributor plans. */
+  public async listContributorPlans(requestId: string): Promise<DyNTS_PrivacyContributorPlan_Interface[]> {
+    return Array.from(this.plans.get(requestId)?.values() ?? [])
+      .map((plan: DyNTS_PrivacyContributorPlan_Interface): DyNTS_PrivacyContributorPlan_Interface => ({
+        ...plan,
+      }));
+  }
+
+  /** Upserts the latest content-free outcome for one contributor. */
+  public async saveContributorOutcome(
+    requestId: string,
+    outcome: DyNTS_PrivacyContributorOutcome_Interface
+  ): Promise<void> {
+    const requestOutcomes: Map<string, DyNTS_PrivacyContributorOutcome_Interface> =
+      this.outcomes.get(requestId) ?? new Map();
+
+    requestOutcomes.set(outcome.contributorId, { ...outcome });
+    this.outcomes.set(requestId, requestOutcomes);
+  }
+
+  /** Lists cloned contributor outcomes for one request. */
+  public async listContributorOutcomes(requestId: string): Promise<DyNTS_PrivacyContributorOutcome_Interface[]> {
+    return Array.from(this.outcomes.get(requestId)?.values() ?? [])
+      .map((outcome: DyNTS_PrivacyContributorOutcome_Interface): DyNTS_PrivacyContributorOutcome_Interface => ({
+        ...outcome,
+      }));
+  }
+
+  private cloneRequest(
+    request: DyNTS_PrivacyRequestRecord_Interface | undefined
+  ): DyNTS_PrivacyRequestRecord_Interface {
+    if (!request) {
+      throw new Error('The test request does not exist.');
+    }
+
+    return { ...request };
+  }
+}
+
+class DyNTS_TestPrivacyContributor implements DyNTS_PrivacyContributor_Interface {
+  public executionCount: number = 0;
+  public verificationResult: boolean = true;
+  public planFailuresRemaining: number = 0;
+  public failuresRemaining: number = 0;
+
+  /** Creates a configurable deterministic test contributor. */
+  constructor(
+    public readonly contributorId: string,
+    private readonly action: DyNTS_PrivacyContributorAction_Type = DyNTS_PrivacyContributorAction_Type.noData,
+    private readonly retentionBasisCode: string = ''
+  ) {}
+
+  /** Returns the configured non-sensitive test plan. */
+  public async plan(
+    _context: DyNTS_PrivacyContributorContext_Interface
+  ): Promise<DyNTS_PrivacyContributorPlan_Interface> {
+    void _context;
+
+    if (this.planFailuresRemaining) {
+      this.planFailuresRemaining -= 1;
+
+      throw new Error('Synthetic planning failure.');
+    }
+
+    return {
+      contributorId: this.contributorId,
+      action: this.action,
+      retentionBasisCode: this.retentionBasisCode,
+    };
+  }
+
+  /** Returns a deterministic result or simulates a transient domain failure. */
+  public async execute(
+    _context: DyNTS_PrivacyContributorContext_Interface,
+    plan: DyNTS_PrivacyContributorPlan_Interface
+  ): Promise<DyNTS_PrivacyContributorOutcome_Interface> {
+    this.executionCount += 1;
+
+    if (this.failuresRemaining) {
+      this.failuresRemaining -= 1;
+
+      throw new Error('Synthetic contributor failure.');
+    }
+
+    return {
+      contributorId: this.contributorId,
+      action: plan.action,
+      outcome: plan.action === DyNTS_PrivacyContributorAction_Type.retainWithBasis
+        ? DyNTS_PrivacyContributorOutcome_Type.retainedWithBasis
+        : DyNTS_PrivacyContributorOutcome_Type.noData,
+      retentionBasisCode: plan.retentionBasisCode,
+      artifactChecksum: '',
+      processedRecordCount: 0,
+      errorCode: '',
+      completedAt: '2026-08-18T10:00:00.000Z',
+    };
+  }
+
+  /** Returns the configured post-execution verification result. */
+  public async verify(
+    _context: DyNTS_PrivacyContributorContext_Interface,
+    _outcome: DyNTS_PrivacyContributorOutcome_Interface
+  ): Promise<boolean> {
+    void _context;
+    void _outcome;
+
+    return this.verificationResult;
+  }
+}
+
+describe('| DyNTS_PrivacyLifecycle_ControlService', (): void => {
+  let adapter: DyNTS_TestPrivacyAdapter;
+  let contributor: DyNTS_TestPrivacyContributor;
+  let service: DyNTS_PrivacyLifecycle_ControlService;
+
+  beforeEach((): void => {
+    adapter = new DyNTS_TestPrivacyAdapter();
+    contributor = new DyNTS_TestPrivacyContributor('pipeline-data');
+    service = new DyNTS_PrivacyLifecycle_ControlService({
+      adapter: adapter,
+      contributors: [ contributor ],
+      clock: (): Date => new Date('2026-08-18T10:00:00.000Z'),
+    });
+  });
+
+  it('| creates idempotently within the subject and organization boundary', async (): Promise<void> => {
+    const first: DyNTS_PrivacyRequestCreateResult_Interface = await openRequest(service);
+    const replay: DyNTS_PrivacyRequestCreateResult_Interface = await openRequest(service);
+    const otherOrganization: DyNTS_PrivacyRequestCreateResult_Interface = await service.openRequest({
+      subjectId: 'subject-1',
+      organizationId: 'organization-2',
+      type: DyNTS_PrivacyRequest_Type.erasure,
+      idempotencyKey: 'request-key',
+      deadlineAt: '2026-09-18T10:00:00.000Z',
+    });
+
+    expect(first.created).toBeTrue();
+    expect(replay.created).toBeFalse();
+    expect(replay.request.requestId).toBe(first.request.requestId);
+    expect(otherOrganization.request.requestId).not.toBe(first.request.requestId);
+    expect(JSON.stringify(first.request)).not.toContain('idempotencyHash');
+  });
+
+  it('| requires identity verification and hides requests from another subject', async (): Promise<void> => {
+    const opened: DyNTS_PrivacyRequestCreateResult_Interface = await openRequest(service);
+
+    await expectAsync(service.processRequest(opened.request.requestId, 'subject-1')).toBeRejectedWithError(DyFM_Error);
+    const hiddenError: DyFM_Error = await captureError(
+      service.getRequest(opened.request.requestId, 'subject-2')
+    );
+
+    expect(hiddenError._errorCode).toContain('REQUEST_NOT_FOUND');
+  });
+
+  it('| completes only after every contributor result verifies', async (): Promise<void> => {
+    const opened: DyNTS_PrivacyRequestCreateResult_Interface = await openRequest(service);
+
+    await service.verifyIdentity(opened.request.requestId, 'subject-1');
+    const result: DyNTS_PrivacyRequestResult_Interface = await service.processRequest(
+      opened.request.requestId,
+      'subject-1'
+    );
+
+    expect(result.request.state).toBe(DyNTS_PrivacyRequestState_Type.completed);
+    expect(result.request.completedAt).toBe('2026-08-18T10:00:00.000Z');
+    expect(result.request.scopedAt).toBe('2026-08-18T10:00:00.000Z');
+    expect(result.request.plannedAt).toBe('2026-08-18T10:00:00.000Z');
+    expect(result.request.verifyingStartedAt).toBe('2026-08-18T10:00:00.000Z');
+    expect(result.outcomes[0].outcome).toBe(DyNTS_PrivacyContributorOutcome_Type.noData);
+  });
+
+  it('| reports partial completion and resumes only failed contributors', async (): Promise<void> => {
+    const stable: DyNTS_TestPrivacyContributor = new DyNTS_TestPrivacyContributor('account-data');
+
+    contributor.failuresRemaining = 1;
+    service = new DyNTS_PrivacyLifecycle_ControlService({
+      adapter: adapter,
+      contributors: [ contributor, stable ],
+    });
+    const opened: DyNTS_PrivacyRequestCreateResult_Interface = await openRequest(service);
+
+    await service.verifyIdentity(opened.request.requestId, 'subject-1');
+    const partial: DyNTS_PrivacyRequestResult_Interface = await service.processRequest(
+      opened.request.requestId,
+      'subject-1'
+    );
+    const resumed: DyNTS_PrivacyRequestResult_Interface = await service.processRequest(
+      opened.request.requestId,
+      'subject-1'
+    );
+
+    expect(partial.request.state).toBe(DyNTS_PrivacyRequestState_Type.partiallyCompleted);
+    expect(resumed.request.state).toBe(DyNTS_PrivacyRequestState_Type.completed);
+    expect(contributor.executionCount).toBe(2);
+    expect(stable.executionCount).toBe(1);
+  });
+
+  it('| accepts explicit retention only with a matching legal-basis code', async (): Promise<void> => {
+    contributor = new DyNTS_TestPrivacyContributor(
+      'billing-data',
+      DyNTS_PrivacyContributorAction_Type.retainWithBasis,
+      'statutory-accounting-retention'
+    );
+    service = new DyNTS_PrivacyLifecycle_ControlService({ adapter: adapter, contributors: [ contributor ] });
+    const opened: DyNTS_PrivacyRequestCreateResult_Interface = await openRequest(service);
+
+    await service.verifyIdentity(opened.request.requestId, 'subject-1');
+    const result: DyNTS_PrivacyRequestResult_Interface = await service.processRequest(
+      opened.request.requestId,
+      'subject-1'
+    );
+
+    expect(result.request.state).toBe(DyNTS_PrivacyRequestState_Type.completed);
+    expect(result.outcomes[0].retentionBasisCode).toBe('statutory-accounting-retention');
+  });
+
+  it('| persists partial planning and resumes before any execution', async (): Promise<void> => {
+    contributor.planFailuresRemaining = 1;
+    const opened: DyNTS_PrivacyRequestCreateResult_Interface = await openRequest(service);
+
+    await service.verifyIdentity(opened.request.requestId, 'subject-1');
+    const partial: DyNTS_PrivacyRequestResult_Interface = await service.processRequest(
+      opened.request.requestId,
+      'subject-1'
+    );
+
+    expect(partial.request.state).toBe(DyNTS_PrivacyRequestState_Type.partiallyCompleted);
+    expect(contributor.executionCount).toBe(0);
+
+    const resumed: DyNTS_PrivacyRequestResult_Interface = await service.processRequest(
+      opened.request.requestId,
+      'subject-1'
+    );
+
+    expect(resumed.request.state).toBe(DyNTS_PrivacyRequestState_Type.completed);
+    expect(contributor.executionCount).toBe(1);
+  });
+
+  it('| converts a verification failure into a content-free partial result', async (): Promise<void> => {
+    contributor.verificationResult = false;
+    const opened: DyNTS_PrivacyRequestCreateResult_Interface = await openRequest(service);
+
+    await service.verifyIdentity(opened.request.requestId, 'subject-1');
+    const result: DyNTS_PrivacyRequestResult_Interface = await service.processRequest(
+      opened.request.requestId,
+      'subject-1'
+    );
+
+    expect(result.request.state).toBe(DyNTS_PrivacyRequestState_Type.partiallyCompleted);
+    expect(result.outcomes[0].errorCode).toBe('CONTRIBUTOR_VERIFY_FAILED');
+    expect(JSON.stringify(result.outcomes)).not.toContain('Synthetic contributor failure');
+  });
+});
+
+async function openRequest(
+  service: DyNTS_PrivacyLifecycle_ControlService
+): Promise<DyNTS_PrivacyRequestCreateResult_Interface> {
+  return service.openRequest({
+    subjectId: 'subject-1',
+    organizationId: 'organization-1',
+    type: DyNTS_PrivacyRequest_Type.erasure,
+    idempotencyKey: 'request-key',
+    deadlineAt: '2026-09-18T10:00:00.000Z',
+  });
+}
+
+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.');
+}