@tailor-platform/erp-kit 0.3.0 → 0.4.1

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

@@ -0,0 +1,79 @@
+# CreateAuditPolicy
+
+## Overview
+
+CreateAuditPolicy creates a new audit policy in DRAFT status. The command accepts a target entity name, optional company scope, a single operation type, and optional field-level rules with sensitivity modes. Policies are created in DRAFT to allow review before activation. The policy's scope must match the target entity's registered scope.
+
+This command requires the `manageAuditPolicies` permission at the appropriate scope.
+
+## Business Rules
+
+- Policy is always created in DRAFT status
+- entityName is required and must reference a registered auditable entity
+- companyId is optional; if provided, the target entity must be COMPANY_BOUND; if null, the target entity must be GLOBAL
+- operationType is required and must be one of CREATE, UPDATE, or DELETE; invalid values are rejected
+- Field names in field-level rules must be non-empty strings
+- Field-level rules are optional; each rule specifies a fieldName and optional sensitivityMode
+- Field names in field-level rules must be a subset of the entity's registered auditableFields
+- Duplicate field names within the same policy are rejected
+- sensitivityMode defaults to CAPTURE if not specified
+- Caller must hold `manageAuditPolicies` permission at the appropriate scope
+- A caller with company-scoped `manageAuditPolicies` can only create policies for their assigned companies
+- A caller with global-scoped `manageAuditPolicies` can only create global policies (companyId null)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Caller has manageAuditPolicies?}
+    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
+    B -->|Yes| B2{Caller scope covers requested policy scope?}
+    B2 -->|No| B3[Return error: UNAUTHORIZED]
+    B2 -->|Yes| D{entityName registered?}
+    D -->|No| E[Return error: ENTITY_TYPE_NOT_REGISTERED]
+    D -->|Yes| F{Policy scope matches entity scope?}
+    F -->|No| G[Return error: SCOPE_MISMATCH]
+    F -->|Yes| G2{operationType valid?}
+    G2 -->|No| G3[Return error: INVALID_OPERATION_TYPE]
+    G2 -->|Yes| H{Validate field rules}
+    H -->|Invalid| I[Return validation error]
+    H -->|Valid| J[Create AuditPolicy in DRAFT]
+    J --> K[Create PolicyFieldRule records]
+    K --> L[Return created 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)
+- **ENTITY_TYPE_NOT_REGISTERED**: entityName does not match any registered auditable entity
+- **SCOPE_MISMATCH**: companyId provided for a global entity, or companyId null for a company-bound entity
+- **INVALID_FIELD_NAME**: A field name in field-level rules is empty or not in the entity's auditableFields
+- **DUPLICATE_FIELD_NAME**: The same field name appears more than once in field-level rules
+- **INVALID_OPERATION_TYPE**: operationType is missing or not one of CREATE, UPDATE, DELETE
+- **INVALID_SENSITIVITY_MODE**: sensitivityMode is not one of CAPTURE, MASK, HASH, EXCLUDE
+
+## Test Cases
+
+- creates policy in DRAFT status
+- creates policy with company scope for company-bound entity
+- creates policy with global scope for global entity
+- creates policy with field-level rules and sensitivity modes
+- creates policy without field-level rules (audits all eligible fields)
+- rejects when entityName is not registered
+- rejects company-scoped policy for global entity
+- rejects global policy for company-bound entity
+- rejects duplicate field names in field-level rules
+- rejects field names not in entity's auditableFields
+- rejects invalid sensitivity mode
+- rejects invalid operation type
+- rejects empty field name in field-level rules
+- defaults sensitivityMode to CAPTURE when not specified
+- rejects when caller lacks manageAuditPolicies permission
+- rejects when company-scoped caller creates policy for a different company
+- creates policy with global scope when companyId is explicitly null
+- rejects when global-scoped caller creates company-scoped policy

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

@@ -0,0 +1,55 @@
+# DeactivateAuditPolicy
+
+## Overview
+
+DeactivateAuditPolicy transitions an audit policy from ACTIVE to INACTIVE status, stopping new audit capture for the specified entity, operation type, and scope. Previously recorded audit entries are not affected. Events arriving for this entity + operation combination while no active policy exists will be silently discarded.
+
+This command requires the `manageAuditPolicies` permission at the appropriate scope.
+
+## Business Rules
+
+- Only policies in ACTIVE status can be deactivated
+- Deactivation stops new audit capture but does not delete previously recorded audit entries
+- Events for the entity + operation + scope combination will be silently discarded while no ACTIVE policy exists
+- Caller must hold `manageAuditPolicies` permission at the appropriate scope
+- A caller with company-scoped `manageAuditPolicies` can only deactivate policies for their assigned companies
+- A caller with global-scoped `manageAuditPolicies` can only deactivate global policies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate 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 ACTIVE status?}
+    F -->|No| G[Return error: INVALID_STATE]
+    F -->|Yes| H[Set status to INACTIVE]
+    H --> I[Return deactivated 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 ACTIVE status
+
+## Test Cases
+
+- deactivates ACTIVE policy to INACTIVE
+- stops new audit capture after deactivation
+- does not delete previously recorded audit entries
+- rejects deactivation of DRAFT policy
+- rejects deactivation of INACTIVE policy
+- rejects when policy does not exist
+- rejects when caller lacks manageAuditPolicies permission
+- rejects when company-scoped caller deactivates policy for a different company
+- rejects when global-scoped caller deactivates company-scoped policy

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

@@ -0,0 +1,55 @@
+# DeleteAuditPolicy
+
+## Overview
+
+DeleteAuditPolicy permanently removes an audit policy that is in DRAFT status. Only DRAFT policies can be deleted — ACTIVE and INACTIVE policies must be preserved for audit integrity. Deleting a policy does not affect any previously recorded audit entries.
+
+This command requires the `manageAuditPolicies` permission at the appropriate scope.
+
+## Business Rules
+
+- Only policies in DRAFT status can be deleted
+- ACTIVE and INACTIVE policies cannot be deleted
+- Deleting a policy does not affect previously recorded audit entries
+- Caller must hold `manageAuditPolicies` permission at the appropriate scope
+- A caller with company-scoped `manageAuditPolicies` can only delete policies for their assigned companies
+- A caller with global-scoped `manageAuditPolicies` can only delete global policies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete 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[Delete AuditPolicy and associated PolicyFieldRules]
+    H --> I[Return success]
+```
+
+## 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 (ACTIVE or INACTIVE policies cannot be deleted)
+
+## Test Cases
+
+- deletes DRAFT policy
+- deletes associated PolicyFieldRules when deleting policy
+- does not affect previously recorded audit entries
+- rejects deletion of ACTIVE policy
+- rejects deletion of INACTIVE policy
+- rejects when policy does not exist
+- rejects when caller lacks manageAuditPolicies permission
+- rejects when company-scoped caller deletes policy for a different company
+- rejects when global-scoped caller deletes company-scoped policy

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

@@ -0,0 +1,137 @@
+# LogAuditEvent
+
+## Overview
+
+LogAuditEvent ingests a structured audit event from an emitting module, creating an immutable AuditEntry with linked ChangeDetail records. The command enforces idempotency on eventId — duplicate submissions are silently discarded. Events are validated against registered auditable entities and active audit policies. The timestamp is system-generated and cannot be supplied by the caller.
+
+This command is the primary ingestion interface for the audit module and is called by other modules after they commit their own transactions.
+
+## Business Rules
+
+- eventId must be a UUID and globally unique; duplicate eventId submissions are silently accepted (no new entry created)
+- actorType is required and must be one of USER, SYSTEM, or SERVICE
+- actorId is required and must be non-empty
+- entityType must reference a registered auditable entity
+- entityId is required and must be non-empty
+- operationType must be one of CREATE, UPDATE, or DELETE
+- companyId is required for company-bound entities and must be null for global entities
+- timestamp is system-generated at ingestion time; caller-supplied timestamps are ignored
+- An active audit policy must exist for the entity + operation + scope combination; events with no matching active policy are silently discarded
+- changes array must contain at least one ChangeDetail for CREATE and DELETE operations
+- For UPDATE operations, only fields that actually changed should be included in changes
+- For UPDATE operations, if the changes array is empty (no fields actually changed), the event is a no-op: no AuditEntry or ChangeDetail records are created, and the command returns success silently — this prevents audit noise from saves that do not modify any field values
+- After policy field-rule filtering and auditable-field filtering, if no processable changes remain:
+  - UPDATE: treated as a no-op (same as empty changes array above)
+  - CREATE / DELETE: rejected with VALIDATION_ERROR because these operations require at least one auditable change to produce a meaningful entry
+- Field values are normalized by type before sensitivity processing:
+  - Scalar fields (string, number, boolean, date, enum) are serialized as strings and stored as-is
+  - Rich text / HTML field values are stripped to plain text before storage
+  - Collection / array field values are serialized as JSON strings
+  - Relation field values capture the foreign key ID as a string
+  - File attachment fields capture the reference metadata (file ID, filename, size), not the file content
+  - Binary / BLOB fields are excluded from audit capture entirely and are not eligible for policy field rules
+  - Computed / derived fields are excluded from audit capture
+- Fields in the changes array that are not listed in the entity's registered auditableFields are silently dropped — no ChangeDetail is created for them and no error is raised
+- Fields in the changes array that are listed in auditableFields but not included in the active policy's field rules (when the policy has explicit field rules) are also silently dropped
+- Field values are processed through the applicable policy's sensitivity modes after normalization
+- Values exceeding 4,000 characters are truncated with a `[truncated]` suffix after sensitivity processing
+- correlationId is optional and groups related events from a single logical operation; if provided, it must be a valid UUID — invalid values are rejected with VALIDATION_ERROR
+- actorMetadata (ipAddress, userAgent, sessionId, requestId) is optional
+- onBehalfOf is optional and records the delegated user's identity
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive audit event] --> A2{Caller has logAuditEvent permission?}
+    A2 -->|No| A3[Return error: INSUFFICIENT_PERMISSION]
+    A2 -->|Yes| B{Duplicate eventId?}
+    B -->|Yes| C[Return success, no new entry]
+    B -->|No| D{entityType registered?}
+    D -->|No| E[Return error: ENTITY_TYPE_NOT_REGISTERED]
+    D -->|Yes| F{Validate required fields}
+    F -->|Invalid| G[Return validation error]
+    F -->|Valid| H{Company scope matches entity scope?}
+    H -->|No| I[Return error: SCOPE_MISMATCH]
+    H -->|Yes| H2{correlationId provided and not valid UUID?}
+    H2 -->|Yes| H3[Return error: VALIDATION_ERROR]
+    H2 -->|No| J{Active policy exists for entity + operation + scope?}
+    J -->|No| K[Silently discard, return success]
+    J -->|Yes| J2{UPDATE with empty changes array?}
+    J2 -->|Yes| J3[No-op: return success, no entry created]
+    J2 -->|No| J4{CREATE or DELETE with empty changes?}
+    J4 -->|Yes| J5[Return error: VALIDATION_ERROR]
+    J4 -->|No| L[Apply policy field rules and sensitivity modes]
+    L --> L2{Any processable changes remain after filtering?}
+    L2 -->|No, UPDATE| L3[No-op: return success, no entry created]
+    L2 -->|No, CREATE/DELETE| L4[Return error: VALIDATION_ERROR]
+    L2 -->|Yes| M[Generate system timestamp]
+    M --> N[Create AuditEntry]
+    N --> O[Create ChangeDetail records]
+    O --> P[Return success]
+```
+
+## External Dependencies
+
+- None (internal module command; emitting modules call this interface)
+
+## Error Scenarios
+
+- **INSUFFICIENT_PERMISSION**: Caller lacks the required command permission (shared error from defineCommand)
+- **ENTITY_TYPE_NOT_REGISTERED**: entityType does not match any registered auditable entity
+- **INVALID_ACTOR**: actorType is missing or not one of USER, SYSTEM, SERVICE; or actorId is empty
+- **INVALID_OPERATION_TYPE**: operationType is missing or not one of CREATE, UPDATE, DELETE
+- **SCOPE_MISMATCH**: companyId provided for a global entity, or companyId missing for a company-bound entity
+- **MISSING_ENTITY_ID**: entityId is empty or not provided
+- **MISSING_EVENT_ID**: eventId is empty or not a valid UUID
+- **VALIDATION_ERROR**: CREATE or DELETE operation submitted with an empty changes array; CREATE or DELETE operation where all changes are filtered out by policy field rules or auditable-field filtering (no auditable changes remain); or correlationId provided but not a valid UUID
+
+## Test Cases
+
+- creates AuditEntry with all required fields for a CREATE operation
+- creates AuditEntry with all required fields for an UPDATE operation
+- creates AuditEntry with all required fields for a DELETE operation
+- silently skips AuditEntry creation for UPDATE with empty changes array (zero-delta no-op)
+- rejects CREATE with empty changes array
+- rejects DELETE with empty changes array
+- silently discards duplicate eventId without creating a new entry
+- rejects event with unregistered entityType
+- rejects event with missing actorType
+- rejects event with invalid actorType
+- rejects event with empty actorId
+- rejects event with invalid operationType
+- rejects event with companyId on a global entity
+- rejects event with null companyId on a company-bound entity
+- silently discards event when no active policy matches entity + operation + scope
+- generates system timestamp and ignores caller-supplied timestamp
+- creates ChangeDetail records linked to the parent AuditEntry
+- applies MASK sensitivity mode to field values
+- applies HASH sensitivity mode to field values
+- applies EXCLUDE sensitivity mode storing null for both oldValue and newValue
+- serializes scalar field values as strings
+- strips rich text / HTML values to plain text before storage
+- serializes collection / array field values as JSON strings
+- captures relation field values as foreign key ID strings
+- captures file attachment fields as reference metadata only (file ID, filename, size)
+- excludes binary / BLOB fields from audit capture
+- excludes computed / derived fields from audit capture
+- silently drops fields from changes array that are not in entity's registered auditableFields
+- silently drops fields from changes array that are not in the active policy's field rules when policy has explicit rules
+- truncates values exceeding 4,000 characters with [truncated] suffix
+- stores correlationId when provided
+- stores actorMetadata (ipAddress, userAgent, sessionId, requestId) when provided
+- stores onBehalfOf when provided
+- creates ChangeDetail with null oldValue for CREATE operations
+- creates ChangeDetail with null newValue for DELETE operations
+- filters out unchanged fields for UPDATE operations
+- returns no-op when all UPDATE changes are unchanged after normalization
+- enforces oldValue=null for CREATE even if caller provides oldValue
+- enforces newValue=null for DELETE even if caller provides newValue
+- rejects event with empty entityId
+- rejects event with empty eventId
+- rejects event with non-UUID eventId
+- rejects event with non-UUID correlationId
+- rejects CREATE when all changes are filtered out by policy rules
+- rejects DELETE when all changes are filtered out by policy rules
+- returns no-op for UPDATE when all changes are filtered out by policy rules
+- rejects caller without logAuditEvent permission

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

@@ -0,0 +1,58 @@
+# ReactivateAuditPolicy
+
+## Overview
+
+ReactivateAuditPolicy transitions an audit policy from INACTIVE back to ACTIVE status, resuming audit capture. Reactivation is rejected if a conflicting ACTIVE policy already exists for the same (entityName, companyId, operationType) combination.
+
+This command requires the `manageAuditPolicies` permission at the appropriate scope.
+
+## Business Rules
+
+- Only policies in INACTIVE status can be reactivated
+- At most one ACTIVE policy can exist for a given (entityName, companyId, operationType) combination
+- If a conflicting ACTIVE policy exists, reactivation is rejected
+- Caller must hold `manageAuditPolicies` permission at the appropriate scope
+- A caller with company-scoped `manageAuditPolicies` can only reactivate policies for their assigned companies
+- A caller with global-scoped `manageAuditPolicies` can only reactivate global policies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate 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 INACTIVE status?}
+    F -->|No| G[Return error: INVALID_STATE]
+    F -->|Yes| H{Conflicting ACTIVE policy exists?}
+    H -->|Yes| I[Return error: CONFLICTING_ACTIVE_POLICY]
+    H -->|No| J[Set status to ACTIVE]
+    J --> K[Return reactivated 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 INACTIVE status
+- **CONFLICTING_ACTIVE_POLICY**: An ACTIVE policy already exists for the same (entityName, companyId, operationType)
+
+## Test Cases
+
+- reactivates INACTIVE policy to ACTIVE
+- resumes audit capture after reactivation
+- rejects reactivation of DRAFT policy
+- rejects reactivation of ACTIVE policy
+- rejects reactivation when conflicting ACTIVE policy exists
+- rejects when policy does not exist
+- rejects when caller lacks manageAuditPolicies permission
+- rejects when company-scoped caller reactivates policy for a different company
+- rejects when global-scoped caller reactivates company-scoped policy

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

@@ -0,0 +1,62 @@
+# RegisterAuditableEntity
+
+## Overview
+
+RegisterAuditableEntity registers an entity for audit tracking within the audit module. Other modules call this command at initialization time to declare which of their entities are eligible for auditing, specifying the entity name, scope (COMPANY_BOUND or GLOBAL), and the list of auditable fields. Each field can be specified as a plain string (field name only) or as an object `{ fieldName, fieldType? }` where fieldType must be one of the eligible types: scalar, richtext, array, relation, or file. Any other fieldType is rejected as ineligible. Once registered, entity scope is immutable.
+
+## Business Rules
+
+- entityName is required, must be non-empty, and must be unique across all registrations
+- entityScope is required and must be one of COMPANY_BOUND or GLOBAL
+- auditableFields is required and must contain at least one entry
+- Each entry in auditableFields is either a non-empty string or an object with a non-empty `fieldName` and an optional `fieldType`
+- Only the following fieldType values are eligible: `scalar`, `richtext`, `array`, `relation`, `file`. Any other fieldType (e.g. `binary`, `computed`) is rejected with INVALID_AUDITABLE_FIELDS
+- If an entity with the same name is already registered, the command is rejected
+- Entity scope is immutable once registered — it cannot be changed after initial registration
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive registration request] --> A2{Caller has registerAuditableEntity permission?}
+    A2 -->|No| A3[Return error: INSUFFICIENT_PERMISSION]
+    A2 -->|Yes| B{entityName non-empty?}
+    B -->|No| C[Return error: INVALID_ENTITY_NAME]
+    B -->|Yes| D{entityScope valid?}
+    D -->|No| G[Return error: INVALID_ENTITY_SCOPE]
+    D -->|Yes| E{auditableFields non-empty?}
+    E -->|No| I[Return error: INVALID_AUDITABLE_FIELDS]
+    E -->|Yes| F{All field names non-empty and fieldTypes eligible?}
+    F -->|No| I2[Return error: INVALID_AUDITABLE_FIELDS]
+    F -->|Yes| H{entityName already registered?}
+    H -->|Yes| J[Return error: DUPLICATE_ENTITY_NAME]
+    H -->|No| K[Create AuditableEntity record]
+    K --> L[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INSUFFICIENT_PERMISSION**: Caller lacks the required command permission (shared error from defineCommand)
+- **INVALID_ENTITY_NAME**: entityName is empty or not provided
+- **DUPLICATE_ENTITY_NAME**: An entity with the same name is already registered
+- **INVALID_ENTITY_SCOPE**: entityScope is missing or not one of COMPANY_BOUND, GLOBAL
+- **INVALID_AUDITABLE_FIELDS**: auditableFields is empty, contains an empty field name, or contains a field with an ineligible fieldType (any type outside scalar, richtext, array, relation, file)
+
+## Test Cases
+
+- registers entity with COMPANY_BOUND scope
+- registers entity with GLOBAL scope
+- accepts mixed string and object field definitions in auditableFields
+- rejects registration with empty entityName
+- rejects registration with duplicate entityName
+- rejects registration with invalid entityScope
+- rejects registration with empty auditableFields
+- rejects registration with empty field name in auditableFields
+- rejects registration with binary field type in auditableFields
+- rejects registration with computed field type in auditableFields
+- rejects registration with unknown field type in auditableFields
+- rejects caller without registerAuditableEntity permission

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

@@ -0,0 +1,72 @@
+# ReplaceAuditPolicy
+
+## Overview
+
+ReplaceAuditPolicy atomically deactivates the current ACTIVE policy and activates a replacement DRAFT policy for the same (entityName, companyId, operationType) combination in a single transaction. This ensures no gap in audit coverage during policy updates. The replacement policy must be in DRAFT status and target the same entity, operation, and scope as the existing ACTIVE policy.
+
+This command requires the `manageAuditPolicies` permission at the appropriate scope.
+
+## Business Rules
+
+- The replacement policy must be in DRAFT status
+- An existing ACTIVE policy must exist for the same entityName; if none exists, the operation is rejected (use activateAuditPolicy instead)
+- The existing ACTIVE policy must match the replacement policy's companyId and operationType; a mismatch is rejected as TARGET_MISMATCH
+- The operation is atomic — either both the deactivation and activation succeed, or neither takes effect
+- After completion, the previously ACTIVE policy is INACTIVE and the replacement is ACTIVE
+- Caller must hold `manageAuditPolicies` permission at the appropriate scope
+- A caller with company-scoped `manageAuditPolicies` can only replace policies for their assigned companies
+- A caller with global-scoped `manageAuditPolicies` can only replace global policies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive replace request] --> B{Caller has manageAuditPolicies?}
+    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
+    B -->|Yes| D{Replacement 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{Replacement in DRAFT status?}
+    F -->|No| G[Return error: INVALID_STATE]
+    F -->|Yes| H{Any ACTIVE policy exists for this entity?}
+    H -->|No| I[Return error: NO_ACTIVE_POLICY_TO_REPLACE]
+    H -->|Yes| H2{ACTIVE policy matches replacement's operation + scope?}
+    H2 -->|No| H3[Return error: TARGET_MISMATCH]
+    H2 -->|Yes| J[Begin transaction]
+    J --> K[Set existing ACTIVE policy to INACTIVE]
+    K --> L[Set replacement DRAFT policy to ACTIVE]
+    L --> M[Commit transaction]
+    M --> N[Return both updated policies]
+```
+
+## 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 replacement policy ID does not exist
+- **INVALID_STATE**: Replacement policy is not in DRAFT status
+- **NO_ACTIVE_POLICY_TO_REPLACE**: No ACTIVE policy exists for the same entityName; use activateAuditPolicy instead
+- **TARGET_MISMATCH**: The existing ACTIVE policy does not match the replacement's companyId or operationType
+
+## Test Cases
+
+- atomically deactivates existing ACTIVE policy and activates DRAFT replacement
+- existing policy is INACTIVE after replacement
+- replacement policy is ACTIVE after replacement
+- no gap in audit coverage during replacement
+- rejects when replacement policy is not in DRAFT status
+- rejects when replacement policy is ACTIVE
+- rejects when replacement policy is INACTIVE
+- rejects when no existing ACTIVE policy for the same entity
+- rejects when replacement targets different operationType than existing ACTIVE policy
+- rejects when replacement targets different companyId than existing ACTIVE policy
+- selects correct ACTIVE policy when multiple ACTIVE policies exist for the same entity
+- rejects when replacement policy does not exist
+- rejects when caller lacks manageAuditPolicies permission
+- rejects when company-scoped caller replaces policy for a different company
+- rejects when global-scoped caller replaces company-scoped policy

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

@@ -0,0 +1,77 @@
+# UpdateAuditPolicy
+
+## Overview
+
+UpdateAuditPolicy modifies the configuration of an existing audit policy that is in DRAFT status. The command allows updating the operation type, field-level rules, and sensitivity modes. Only DRAFT policies can be updated — ACTIVE and INACTIVE policies are immutable.
+
+This command requires the `manageAuditPolicies` permission at the appropriate scope.
+
+## Business Rules
+
+- Only policies in DRAFT status can be updated
+- entityName and companyId cannot be changed after creation
+- Operation type can be updated; must be one of CREATE, UPDATE, or DELETE
+- Field names in field-level rules must be non-empty strings
+- Field-level rules can be added, modified, or removed
+- When adding or modifying field-level rules, sensitivityMode defaults to CAPTURE if not specified
+- Field names in field-level rules must be a subset of the entity's registered auditableFields
+- Duplicate field names within the same policy are rejected
+- Caller must hold `manageAuditPolicies` permission at the appropriate scope
+- A caller with company-scoped `manageAuditPolicies` can only update policies for their assigned companies
+- A caller with global-scoped `manageAuditPolicies` can only update global policies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update 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| G2{operationType valid?}
+    G2 -->|No| G3[Return error: INVALID_OPERATION_TYPE]
+    G2 -->|Yes| H{Validate field rules}
+    H -->|Invalid| I[Return validation error]
+    H -->|Valid| J[Update AuditPolicy fields]
+    J --> K[Update PolicyFieldRule records]
+    K --> L[Return updated 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
+- **INVALID_OPERATION_TYPE**: operationType is not one of CREATE, UPDATE, DELETE
+- **INVALID_FIELD_NAME**: A field name in field-level rules is empty or not in the entity's auditableFields
+- **DUPLICATE_FIELD_NAME**: The same field name appears more than once in field-level rules
+- **INVALID_SENSITIVITY_MODE**: sensitivityMode is not one of CAPTURE, MASK, HASH, EXCLUDE
+
+## Test Cases
+
+- updates operation type on DRAFT policy
+- updates field-level rules on DRAFT policy
+- updates sensitivity modes on field-level rules
+- adds new field-level rules to DRAFT policy
+- removes field-level rules from DRAFT policy
+- defaults sensitivityMode to CAPTURE when adding a field-level rule without explicit sensitivityMode
+- defaults sensitivityMode to CAPTURE when modifying a field-level rule and sensitivityMode is omitted
+- rejects update on ACTIVE policy
+- rejects update on INACTIVE policy
+- rejects when policy does not exist
+- rejects duplicate field names
+- rejects field names not in entity's auditableFields
+- rejects invalid operation type
+- rejects invalid sensitivity mode
+- rejects when caller lacks manageAuditPolicies permission
+- rejects when company-scoped caller updates policy for a different company
+- rejects when global-scoped caller updates company-scoped policy