@tailor-platform/erp-kit 0.3.0 → 0.4.0

package/src/modules/audit/command/updateAuditPolicy.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../../shared";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./updateAuditPolicy";
+
+export const updateAuditPolicy = defineCommand(permissions.updateAuditPolicy, run);

package/src/modules/audit/command/updateAuditPolicy.test.ts

@@ -0,0 +1,284 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PolicyNotFoundError,
+  InvalidStateError,
+  InvalidOperationTypeError,
+  InvalidFieldNameError,
+  DuplicateFieldNameError,
+  InvalidSensitivityModeError,
+  UnauthorizedError,
+} from "../lib/errors.generated";
+import { InsufficientPermissionError } from "../../../shared";
+import { draftPolicy, activePolicy, inactivePolicy, companyBoundEntity } from "../testing/fixtures";
+import { run } from "./updateAuditPolicy";
+import { updateAuditPolicy } from "./updateAuditPolicy.generated";
+
+const ctx = { actorId: "test-actor", permissions: ["audit:updateAuditPolicy"] };
+
+describe("updateAuditPolicy", () => {
+  it("updates operation type on DRAFT policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.update.mockReturnValueOnce({ ...draftPolicy, operationType: "DELETE" });
+
+    const result = await run(db, { policyId: draftPolicy.id, operationType: "DELETE" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.operationType).toBe("DELETE");
+    }
+  });
+
+  it("updates field-level rules on DRAFT policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+    spies.update.mockReturnValueOnce(draftPolicy);
+    spies.insert.mockReturnValue({
+      id: "rule-new",
+      fieldName: "amount",
+      sensitivityMode: "CAPTURE",
+    });
+
+    const result = await run(
+      db,
+      { policyId: draftPolicy.id, fieldRules: [{ fieldName: "amount" }] },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+  });
+
+  it("updates sensitivity modes on field-level rules", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+    spies.update.mockReturnValueOnce(draftPolicy);
+    spies.insert.mockReturnValue({ id: "rule-new", fieldName: "amount", sensitivityMode: "MASK" });
+
+    const result = await run(
+      db,
+      { policyId: draftPolicy.id, fieldRules: [{ fieldName: "amount", sensitivityMode: "MASK" }] },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+  });
+
+  it("adds new field-level rules to DRAFT policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+    spies.update.mockReturnValueOnce(draftPolicy);
+    spies.insert.mockReturnValue({ id: "rule-new" });
+
+    const result = await run(
+      db,
+      {
+        policyId: draftPolicy.id,
+        fieldRules: [
+          { fieldName: "amount", sensitivityMode: "CAPTURE" },
+          { fieldName: "status", sensitivityMode: "HASH" },
+        ],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+  });
+
+  it("removes field-level rules from DRAFT policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+    spies.update.mockReturnValueOnce(draftPolicy);
+
+    const result = await run(db, { policyId: draftPolicy.id, fieldRules: [] }, ctx);
+
+    expect(result.ok).toBe(true);
+  });
+
+  it("defaults sensitivityMode to CAPTURE when adding a field-level rule without explicit sensitivityMode", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+    spies.update.mockReturnValueOnce(draftPolicy);
+    spies.insert.mockReturnValue({ id: "rule-new" });
+
+    const result = await run(
+      db,
+      { policyId: draftPolicy.id, fieldRules: [{ fieldName: "amount" }] },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    expect(spies.values).toHaveBeenCalledWith(
+      expect.objectContaining({ sensitivityMode: "CAPTURE" }),
+    );
+  });
+
+  it("defaults sensitivityMode to CAPTURE when modifying a field-level rule and sensitivityMode is omitted", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+    spies.update.mockReturnValueOnce(draftPolicy);
+    spies.insert.mockReturnValue({ id: "rule-new" });
+
+    const result = await run(
+      db,
+      { policyId: draftPolicy.id, fieldRules: [{ fieldName: "status" }] },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    expect(spies.values).toHaveBeenCalledWith(
+      expect.objectContaining({ sensitivityMode: "CAPTURE" }),
+    );
+  });
+
+  it("rejects update on ACTIVE policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activePolicy);
+
+    const result = await run(db, { policyId: activePolicy.id, operationType: "DELETE" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateError);
+    }
+  });
+
+  it("rejects update on INACTIVE policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactivePolicy);
+
+    const result = await run(db, { policyId: inactivePolicy.id, operationType: "DELETE" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateError);
+    }
+  });
+
+  it("rejects when policy does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { policyId: "nonexistent" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(PolicyNotFoundError);
+    }
+  });
+
+  it("rejects duplicate field names", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+
+    const result = await run(
+      db,
+      {
+        policyId: draftPolicy.id,
+        fieldRules: [{ fieldName: "amount" }, { fieldName: "amount" }],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateFieldNameError);
+    }
+  });
+
+  it("rejects field names not in entity's auditableFields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+
+    const result = await run(
+      db,
+      { policyId: draftPolicy.id, fieldRules: [{ fieldName: "nonExistentField" }] },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidFieldNameError);
+    }
+  });
+
+  it("rejects invalid operation type", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+
+    const result = await run(db, { policyId: draftPolicy.id, operationType: "INVALID" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidOperationTypeError);
+    }
+  });
+
+  it("rejects invalid sensitivity mode", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+
+    const result = await run(
+      db,
+      {
+        policyId: draftPolicy.id,
+        fieldRules: [{ fieldName: "amount", sensitivityMode: "INVALID" }],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidSensitivityModeError);
+    }
+  });
+
+  it("rejects when caller lacks manageAuditPolicies permission", async () => {
+    const { db } = createMockDb<Transaction>();
+    const denied = { actorId: "test-actor", permissions: [] as string[] };
+    const cmd = updateAuditPolicy();
+
+    const result = await cmd(db, { policyId: draftPolicy.id }, denied);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
+  });
+
+  it("rejects when company-scoped caller updates policy for a different company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy with companyId: "company-1"
+    const scopedCtx = { ...ctx, companyId: "company-2" };
+
+    const result = await run(db, { policyId: draftPolicy.id }, scopedCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+
+  it("rejects when global-scoped caller updates company-scoped policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy with companyId: "company-1"
+    const globalCtx = { ...ctx, companyId: null };
+
+    const result = await run(db, { policyId: draftPolicy.id }, globalCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+});

package/src/modules/audit/command/updateAuditPolicy.ts

@@ -0,0 +1,151 @@
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PolicyNotFoundError,
+  InvalidStateError,
+  InvalidOperationTypeError,
+  InvalidFieldNameError,
+  DuplicateFieldNameError,
+  InvalidSensitivityModeError,
+  UnauthorizedError,
+} from "../lib/errors.generated";
+
+export interface UpdateAuditPolicyInput {
+  policyId: string;
+  operationType?: string;
+  fieldRules?: { fieldName: string; sensitivityMode?: string }[];
+}
+
+const VALID_OPERATION_TYPES = ["CREATE", "UPDATE", "DELETE"] as const;
+const VALID_SENSITIVITY_MODES = ["CAPTURE", "MASK", "HASH", "EXCLUDE"] as const;
+
+/**
+ * Function: updateAuditPolicy
+ *
+ * Updates a DRAFT audit policy's operation type and/or field-level rules.
+ * Only policies in DRAFT status can be updated.
+ */
+export async function run(db: Transaction, input: UpdateAuditPolicyInput, ctx: CommandContext) {
+  const { policyId, operationType, fieldRules } = input;
+
+  // 1. Find policy by ID with forUpdate
+  const existing = await db
+    .selectFrom("AuditPolicy")
+    .selectAll()
+    .where("id", "=", policyId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new PolicyNotFoundError(policyId));
+  }
+
+  // Scope authorization checks
+  if (ctx.companyId !== undefined) {
+    // Company-scoped caller cannot update policy for a different company
+    if (ctx.companyId !== null && existing.companyId !== ctx.companyId) {
+      return err(new UnauthorizedError(ctx.actorId));
+    }
+    // Global-scoped caller (companyId: null) cannot update company-scoped policy
+    if (ctx.companyId === null && existing.companyId !== null) {
+      return err(new UnauthorizedError(ctx.actorId));
+    }
+  }
+
+  // 2. Not DRAFT → InvalidStateError
+  if (existing.status !== "DRAFT") {
+    return err(new InvalidStateError(policyId));
+  }
+
+  // 3. Validate operationType if provided
+  if (
+    operationType !== undefined &&
+    !VALID_OPERATION_TYPES.includes(operationType as (typeof VALID_OPERATION_TYPES)[number])
+  ) {
+    return err(new InvalidOperationTypeError(operationType));
+  }
+
+  // 4. Validate fieldRules if provided
+  if (fieldRules !== undefined) {
+    // Look up entity's auditableFields
+    const entity = await db
+      .selectFrom("AuditableEntity")
+      .selectAll()
+      .where("entityName", "=", existing.entityName)
+      .executeTakeFirst();
+
+    // Parse auditable fields (supports both legacy string[] and new {fieldName, fieldType?}[] formats)
+    const rawFields = entity
+      ? (JSON.parse(entity.auditableFields) as string[] | { fieldName: string }[])
+      : [];
+    const auditableFieldNames = new Set<string>(
+      rawFields.map((f) => (typeof f === "string" ? f : f.fieldName)),
+    );
+
+    // Check for duplicates first
+    const seen = new Set<string>();
+    for (const rule of fieldRules) {
+      if (seen.has(rule.fieldName)) {
+        return err(new DuplicateFieldNameError(rule.fieldName));
+      }
+      seen.add(rule.fieldName);
+    }
+
+    for (const rule of fieldRules) {
+      // Empty fieldName
+      if (!rule.fieldName || rule.fieldName.trim() === "") {
+        return err(new InvalidFieldNameError(rule.fieldName ?? ""));
+      }
+
+      // Field not in auditableFields
+      if (!auditableFieldNames.has(rule.fieldName)) {
+        return err(new InvalidFieldNameError(rule.fieldName));
+      }
+
+      // Invalid sensitivityMode
+      if (
+        rule.sensitivityMode !== undefined &&
+        !VALID_SENSITIVITY_MODES.includes(
+          rule.sensitivityMode as (typeof VALID_SENSITIVITY_MODES)[number],
+        )
+      ) {
+        return err(new InvalidSensitivityModeError(rule.sensitivityMode));
+      }
+    }
+  }
+
+  // 5. Update AuditPolicy
+  const updateValues: Record<string, unknown> = {
+    updatedAt: new Date(),
+  };
+  if (operationType !== undefined) {
+    updateValues.operationType = operationType;
+  }
+
+  const updatedPolicy = await db
+    .updateTable("AuditPolicy")
+    .set(updateValues)
+    .where("id", "=", policyId)
+    .returningAll()
+    .executeTakeFirst();
+
+  // 6. If fieldRules provided: delete existing and insert new
+  if (fieldRules !== undefined) {
+    await db.deleteFrom("PolicyFieldRule").where("auditPolicyId", "=", policyId).execute();
+
+    for (const rule of fieldRules) {
+      await db
+        .insertInto("PolicyFieldRule")
+        .values({
+          auditPolicyId: policyId,
+          fieldName: rule.fieldName,
+          sensitivityMode: rule.sensitivityMode ?? "CAPTURE",
+          updatedAt: null,
+        })
+        .returningAll()
+        .executeTakeFirst();
+    }
+  }
+
+  return ok({ policy: updatedPolicy! });
+}

package/src/modules/audit/db/auditEntry.ts

@@ -0,0 +1,47 @@
+import {
+  db,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { company as companyStub } from "../lib/_db_deps";
+
+export interface CreateAuditEntryTypeParams {
+  companyType?: TailorAnyDBType;
+}
+
+export function createAuditEntryType(params: CreateAuditEntryTypeParams) {
+  return db
+    .type("AuditEntry", {
+      eventId: db.uuid().unique().description("Globally unique event ID for idempotency"),
+      actorType: db.string().description("Actor type: USER, SYSTEM, or SERVICE"),
+      actorId: db.string().description("Actor identifier"),
+      entityType: db.string().description("Type name of the audited entity"),
+      entityId: db.string().description("ID of the audited entity"),
+      operationType: db.string().description("Operation type: CREATE, UPDATE, or DELETE"),
+      companyId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "keyOnly",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "auditEntries",
+        })
+        .description("Foreign key to Company; null for global entities"),
+      correlationId: db
+        .uuid({ optional: true })
+        .description("Optional correlation ID grouping related events"),
+      ipAddress: db.string({ optional: true }).description("Actor IP address metadata"),
+      userAgent: db.string({ optional: true }).description("Actor user agent metadata"),
+      sessionId: db.string({ optional: true }).description("Actor session ID metadata"),
+      requestId: db.string({ optional: true }).description("Request ID metadata"),
+      onBehalfOf: db
+        .string({ optional: true })
+        .description("Delegated user identity when acting on behalf of another"),
+      timestamp: db.date().description("System-generated timestamp at ingestion time"),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const auditEntry = createAuditEntryType({});

package/src/modules/audit/db/auditPolicy.ts

@@ -0,0 +1,33 @@
+import {
+  db,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { company as companyStub } from "../lib/_db_deps";
+
+export interface CreateAuditPolicyTypeParams {
+  companyType?: TailorAnyDBType;
+}
+
+export function createAuditPolicyType(params: CreateAuditPolicyTypeParams) {
+  return db
+    .type("AuditPolicy", {
+      entityName: db.string().description("Target entity name for audit tracking"),
+      companyId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "keyOnly",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "auditPolicies",
+        })
+        .description("Foreign key to Company; null for global entities"),
+      operationType: db.string().description("Operation type: CREATE, UPDATE, or DELETE"),
+      status: db.string().description("Policy lifecycle status: DRAFT, ACTIVE, INACTIVE"),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const auditPolicy = createAuditPolicyType({});

package/src/modules/audit/db/auditableEntity.ts

@@ -0,0 +1,22 @@
+import {
+  db,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export const auditableEntity = db
+  .type("AuditableEntity", {
+    entityName: db
+      .string()
+      .unique()
+      .description("Unique entity name registered for audit tracking"),
+    entityScope: db.string().description("Entity scope: COMPANY_BOUND or GLOBAL"),
+    auditableFields: db
+      .string()
+      .description(
+        "JSON-serialized array of field definitions ({fieldName, fieldType?}) eligible for audit capture",
+      ),
+    ...db.fields.timestamps(),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);

package/src/modules/audit/db/changeDetail.ts

@@ -0,0 +1,28 @@
+import {
+  db,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { auditEntry } from "./auditEntry";
+
+export const changeDetail = db
+  .type("ChangeDetail", {
+    auditEntryId: db
+      .uuid()
+      .relation({
+        type: "n-1",
+        toward: { type: auditEntry },
+        backward: "changeDetails",
+      })
+      .description("Foreign key to parent AuditEntry"),
+    fieldName: db.string().description("Name of the field that changed"),
+    oldValue: db
+      .string({ optional: true })
+      .description("Previous value (serialized string); null for CREATE operations"),
+    newValue: db
+      .string({ optional: true })
+      .description("New value (serialized string); null for DELETE operations"),
+    ...db.fields.timestamps(),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);

package/src/modules/audit/db/policyFieldRule.ts

@@ -0,0 +1,23 @@
+import {
+  db,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { auditPolicy } from "./auditPolicy";
+
+export const policyFieldRule = db
+  .type("PolicyFieldRule", {
+    auditPolicyId: db
+      .uuid()
+      .relation({
+        type: "n-1",
+        toward: { type: auditPolicy },
+        backward: "policyFieldRules",
+      })
+      .description("Foreign key to parent AuditPolicy"),
+    fieldName: db.string().description("Field name to audit"),
+    sensitivityMode: db.string().description("Sensitivity mode: CAPTURE, MASK, HASH, or EXCLUDE"),
+    ...db.fields.timestamps(),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);

package/src/modules/audit/docs/commands/ActivateAuditPolicy.md

@@ -0,0 +1,69 @@
+# ActivateAuditPolicy
+
+## Overview
+
+ActivateAuditPolicy transitions an audit policy from DRAFT to ACTIVE status, enabling audit capture for the specified entity, operation type, and scope. Activation is rejected if a conflicting ACTIVE policy already exists for the same (entityName, companyId, operationType) combination. The policy must have a valid entity name and an operation type before activation.
+
+This command requires the `manageAuditPolicies` permission at the appropriate scope.
+
+## Business Rules
+
+- Only policies in DRAFT status can be activated
+- At most one ACTIVE policy can exist for a given (entityName, companyId, operationType) combination
+- If a conflicting ACTIVE policy exists, activation is rejected with guidance to deactivate the existing policy first or use replaceAuditPolicy
+- Target entity name must be non-empty and reference a registered entity
+- Exactly one operation type must be specified
+- Caller must hold `manageAuditPolicies` permission at the appropriate scope
+- A caller with company-scoped `manageAuditPolicies` can only activate policies for their assigned companies
+- A caller with global-scoped `manageAuditPolicies` can only activate global policies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Caller has manageAuditPolicies?}
+    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
+    B -->|Yes| D{Policy exists?}
+    D -->|No| E[Return error: POLICY_NOT_FOUND]
+    D -->|Yes| D2{Caller scope covers this policy?}
+    D2 -->|No| D3[Return error: UNAUTHORIZED]
+    D2 -->|Yes| F{Policy in DRAFT status?}
+    F -->|No| G[Return error: INVALID_STATE]
+    F -->|Yes| H{Entity name and operation type valid?}
+    H -->|No| I[Return error: INCOMPLETE_POLICY]
+    H -->|Yes| I2{Entity still registered?}
+    I2 -->|No| I3[Return error: ENTITY_TYPE_NOT_REGISTERED]
+    I2 -->|Yes| J{Conflicting ACTIVE policy exists?}
+    J -->|Yes| K[Return error: CONFLICTING_ACTIVE_POLICY]
+    J -->|No| L[Set status to ACTIVE]
+    L --> M[Return activated policy]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INSUFFICIENT_PERMISSION**: Caller lacks the required command permission (shared error from defineCommand)
+- **UNAUTHORIZED**: Caller's permission scope does not cover this policy (e.g., company-scoped caller managing a different company's policy, or global-scoped caller managing a company-scoped policy)
+- **POLICY_NOT_FOUND**: Specified policy ID does not exist
+- **INVALID_STATE**: Policy is not in DRAFT status
+- **INCOMPLETE_POLICY**: Policy is missing entity name or operation type
+- **ENTITY_TYPE_NOT_REGISTERED**: The target entity name does not reference a currently registered auditable entity
+- **CONFLICTING_ACTIVE_POLICY**: An ACTIVE policy already exists for the same (entityName, companyId, operationType); deactivate it first or use replaceAuditPolicy
+
+## Test Cases
+
+- activates DRAFT policy to ACTIVE
+- begins audit capture after activation
+- rejects activation of ACTIVE policy
+- rejects activation of INACTIVE policy
+- rejects activation when conflicting ACTIVE policy exists
+- rejects activation when entity name is missing
+- rejects activation when operation type is missing
+- rejects when policy does not exist
+- rejects when caller lacks manageAuditPolicies permission
+- rejects when company-scoped caller activates policy for a different company
+- rejects when global-scoped caller activates company-scoped policy
+- rejects when target entity is no longer registered