@tailor-platform/erp-kit 0.3.0 → 0.4.0

package/src/modules/audit/docs/features/audit-event-logging.md

@@ -0,0 +1,126 @@
+# Audit Event Logging
+
+## Overview
+
+Audit Event Logging captures create, update, and delete operations performed across all ERP modules as immutable audit entries. Each entry records a unique `eventId` for deduplication and idempotency, an optional `correlationId` for grouping related events within a logical operation (e.g., bulk updates, cascading workflows, saga steps), the actor identity (actorType and actorId, with optional metadata such as IP address, user agent, sessionId, requestId, or onBehalfOf reference), the operation type (CREATE, UPDATE, DELETE), the affected entity reference (entityType and entityId), and a precise timestamp. Entries may optionally be scoped by companyId for multi-company data isolation; entries for global entities (e.g., user accounts, currencies) omit companyId and are queryable without company scope.
+
+Audit entries are strictly append-only — once written, they cannot be modified or deleted. This immutability guarantee is fundamental to compliance, forensic investigation, and regulatory reporting. The audit log serves as a universal change history that is queryable by actor, entity type, specific record, operation type, and date range, enabling both real-time monitoring and historical analysis of system activity.
+
+Other modules emit audit events by calling the audit module's ingestion interface. Every audit event submitted must include: `eventId` (UUID, unique, used for idempotency), `actorType` (USER/SYSTEM/SERVICE), `actorId`, `entityType` (must match a registered auditable entity), `entityId`, `operationType` (CREATE/UPDATE/DELETE), and `changes` (array of ChangeDetail). Optional fields include: `correlationId` (UUID, groups related events from a single logical operation), `onBehalfOf` (delegated userId), `actorMetadata` (ipAddress, userAgent, sessionId, requestId), and `companyId` (required for company-bound entities, must be null for global entities). The timestamp is always system-generated at ingestion time and cannot be supplied or overridden by the caller, ensuring a consistent and tamper-resistant time source.
+
+The audit module enforces idempotency on `eventId` — submitting the same eventId more than once silently discards the duplicate (returns success, no new entry). This allows emitting modules to safely retry on transient failures. Ingestion is eventually consistent with the source operation: emitting modules complete their own database transaction first, then submit the audit event. The audit module does not participate in the emitting module's transaction, preventing audit failures from blocking business operations. If the audit write fails permanently after retries, the emitting module logs the failure for operational alerting. Duplicate eventIds are silently accepted; missing required fields, unknown entityTypes, and scope mismatches are rejected with validation errors; events for entity + operation combinations with no active policy are silently discarded.
+
+Modules that want their entities to be auditable register them with the audit module at initialization time, declaring `entityName`, `entityScope` (COMPANY_BOUND or GLOBAL), and `auditableFields` (list of field names eligible for audit capture). The audit module validates that `entityType` in incoming events matches a registered entity.
+
+## Business Purpose
+
+Audit Event Logging provides an append-only record of data mutations captured by the system. Because ingestion is eventually consistent and decoupled from source transactions, coverage is best-effort — not every mutation is guaranteed to be recorded (see ingestion contract above). However, once an entry is written it is immutable and cannot be altered or deleted. This enables:
+
+- Regulatory compliance: immutable, append-only logs support SOX, GDPR, and industry-specific audit trail requirements (applications requiring guaranteed capture should layer an outbox or replay mechanism on top)
+- Forensic investigation: security teams can trace exactly who or what changed data, when, and from where
+- Operational accountability: managers can review change history for any business record to understand how it reached its current state
+- Multi-company isolation: company-scoped audit entries ensure each legal entity's audit trail is independently queryable
+- Global entity auditing: changes to foundational, non-company-scoped entities (users, currencies, UoM) are captured without requiring a company context
+- Change attribution: every mutation is linked to a specific actor identity (human user, system process, or service account), eliminating ambiguity about responsibility
+
+The append-only constraint on stored entries ensures:
+
+- Historical integrity of recorded entries is preserved — no entry can be retroactively altered or removed
+- Stored audit trails remain admissible for external auditors and regulators
+- System administrators cannot suppress evidence of recorded operations
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Actor Performs Operation] --> B[System Identifies Operation Type]
+    B --> C{Operation Type}
+    C -->|CREATE| D[Capture New Entity State]
+    C -->|UPDATE| E[Capture Changed Entity State]
+    C -->|DELETE| F[Capture Deleted Entity Reference]
+    D --> G[Resolve Actor Identity]
+    E --> G
+    F --> G
+    G --> H[Record actorType + actorId + Metadata]
+    H --> I[Determine Scope: company or global]
+    I --> J[Build AuditEntry]
+    J --> K[Write Immutable Entry]
+    K --> L[Entry Available for Query]
+```
+
+Querying the audit log follows this pattern. All query paths enforce authorization — the caller must hold `viewAuditHistory` (for detail queries) or `viewAuditSummary` (for aggregate queries) at the appropriate scope:
+
+```mermaid
+flowchart TD
+    A[Query Request] --> AA{Caller holds required permission?}
+    AA -->|No| AB[Reject: insufficient permissions]
+    AA -->|Yes| B{Filter Criteria}
+    B --> C[By Actor: actorType + actorId]
+    B --> D[By Entity Type + Entity ID]
+    B --> E[By Operation Type]
+    B --> F[By Date Range]
+    C --> G{Scope Filter}
+    D --> G
+    E --> G
+    F --> G
+    G -->|companyId provided| H[Return company-scoped entries\nif caller has company-scoped permission]
+    G -->|no companyId| I[Return global entries only\nif caller has global-scoped permission]
+    G -->|both requested| J[Return combined results\nfor scopes caller is authorized for]
+```
+
+## Scenario Patterns
+
+- **Record Creation Tracking**: A user creates a new sales order. The system writes an AuditEntry with operation CREATE, actorType = USER, the actor's actorId (userId), the entityType (e.g., SalesOrder), the new record's entityId, companyId, and a timestamp — providing a permanent record of who created the order and when
+- **Field Update History**: A user modifies the status of a purchase order. An AuditEntry with operation UPDATE is appended, capturing the actor identity and the affected entity reference, enabling reviewers to see the full change timeline for that record
+- **Deletion Accountability**: An operator deletes a draft invoice. An AuditEntry with operation DELETE is written, ensuring the deletion is permanently recorded even though the original record no longer exists
+- **System-Initiated Change**: A scheduled job recalculates exchange rates. The system writes an AuditEntry with actorType = SYSTEM, actorId referencing the job identifier, and no companyId (global scope), capturing automated changes with the same fidelity as human-initiated ones
+- **Delegated Action**: An administrator performs an action on behalf of another user. The AuditEntry records actorType = USER, actorId = the administrator's userId, and onBehalfOf = the target user's userId, preserving the full delegation chain
+- **Security Investigation**: A security team investigates suspicious activity by querying all audit entries for a specific actorId within a date range, across all operation types, to reconstruct the actor's actions
+- **Compliance Audit**: An external auditor requests the full change history for a specific entity (e.g., all mutations to a particular general ledger account) by querying audit entries filtered by entityType and entityId within a fiscal period
+- **Multi-Company Audit Isolation**: A parent organization runs an audit for one subsidiary. Queries are scoped by companyId, returning only audit entries belonging to that legal entity without leaking data from other companies
+- **Global Entity Audit**: An auditor reviews all changes to user accounts (a non-company-scoped entity). Queries omit companyId to retrieve the full global change history for user-management entities
+
+## Test Cases
+
+- Every accepted audit event for an entity and operation type that has an active policy produces exactly one AuditEntry — except UPDATE events with an empty changes array (zero-delta), which are silently accepted as a no-op without creating an AuditEntry
+- AuditEntry contains required fields: eventId, actorType, actorId, entityType, entityId, operationType, and timestamp
+- companyId is required for company-scoped entities and optional (null) for global entities
+- actorType is required and must be one of USER, SYSTEM, or SERVICE
+- actorId is required and must be non-empty regardless of actorType
+- onBehalfOf is optional and stores the delegated user's identity when an action is performed on behalf of another actor
+- AuditEntries cannot be modified after creation — update attempts are rejected
+- AuditEntries cannot be deleted — delete attempts are rejected
+- Actor metadata (IP address, user agent) is optional and stored when provided
+- Querying by actorId returns only entries for that actor
+- Querying by entityType and entityId returns the full change history for a specific record
+- Querying by operationType filters entries to only the specified operation (CREATE, UPDATE, or DELETE)
+- Querying by date range returns only entries whose timestamp falls within the range
+- Querying with companyId returns only entries scoped to that company
+- Querying without companyId returns only global (company-unscoped) entries
+- An operation performed without a valid actor identity (actorType + actorId) is rejected
+- Timestamp is system-generated and cannot be overridden by the caller
+- Audit entries are returned in chronological order by default
+- Large result sets support pagination for efficient retrieval
+- Every audit event must include a unique eventId (UUID)
+- Submitting an event with a duplicate eventId is silently accepted without creating a new entry
+- correlationId is optional and links related events from a single logical operation
+- Events referencing an unregistered entityType are rejected with a validation error
+- Events with companyId on a global entity are rejected with a validation error
+- Events with null companyId on a company-bound entity are rejected with a validation error
+- Events for an entity + operation with no active policy are silently discarded
+- Entity registration requires entityName, entityScope, and auditableFields
+- actorMetadata (ipAddress, userAgent, sessionId, requestId) is optional and stored when provided
+- Querying audit entries requires the `viewAuditHistory` permission at the appropriate scope
+- A caller with company-scoped `viewAuditHistory` can only retrieve entries for their assigned companies
+- A caller with global-scoped `viewAuditHistory` can retrieve global (company-unscoped) entries
+- A caller without `viewAuditHistory` permission receives an authorization error when querying audit entries
+- Querying audit summaries requires the `viewAuditSummary` permission at the appropriate scope
+
+## Reference Links
+
+- [Odoo Mail Tracking (mail.thread)](https://www.odoo.com/documentation/19.0/developer/reference/backend/orm.html#odoo.models.Model)
+- [Dynamics 365 Database Logging (sysdatabaselog)](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/sysadmin/configure-manage-database-log)
+- [SAP Change Document Header (CDHDR)](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f76052846e404ea8811eb06534b6e099/5e13e82b8ca111d1a6090000e8353423.html)
+- [Oracle Financials Audit Trail](https://docs.oracle.com/en/cloud/saas/financials/24d/faigl/overview-of-financials.html)
+- [AWS CloudTrail Documentation](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html)
+- [AWS CloudTrail userIdentity](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)

package/src/modules/audit/docs/features/audit-policy-configuration.md

@@ -0,0 +1,135 @@
+# Audit Policy Configuration
+
+## Overview
+
+Audit Policy Configuration allows administrators to define precisely which entities, fields, and operation types are tracked by the audit system. Rather than auditing everything indiscriminately — which carries significant performance costs — policies let organizations target the data changes that matter most for compliance, security, and operational oversight. Each policy specifies a target entity, a single operation type (CREATE, UPDATE, or DELETE) to record, the subset of fields to capture, and how sensitive field values should be handled during capture. To audit multiple operation types on the same entity, administrators create separate policies — one per operation type.
+
+Policies follow a lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE) that enables safe rollout and rollback of audit configurations. A policy in DRAFT can be reviewed and refined before it takes effect; activating a policy begins audit capture; deactivating a policy stops capture without losing the policy definition or any previously recorded audit entries. Policies can be scoped globally or to a specific company, supporting multi-company deployments where different legal entities have different compliance requirements.
+
+A uniqueness constraint ensures that at most one ACTIVE policy exists for a given combination of (entityName, companyId, operationType). This eliminates ambiguity about which field set applies and avoids unintended field-set merges. To change the audited fields for an existing active configuration, use the atomic replacement operation (`replaceAuditPolicy`), which deactivates the current ACTIVE policy and activates the replacement DRAFT policy in a single transaction — guaranteeing no gap in audit coverage. Alternatively, an administrator can manually deactivate the current policy and then activate the replacement, but this two-step approach creates a brief window where no policy is active and events for that entity + operation combination will be silently discarded.
+
+Policy scope must match the target entity's scope to eliminate precedence ambiguity. Company-bound entities (entities that always carry a companyId) can only have company-scoped policies — global policies (companyId = null) are rejected at creation time for company-bound entities. Conversely, global entities (entities that never carry a companyId, e.g., user accounts, currencies) can only have global policies — company-scoped policies are rejected at creation time for global entities. This scope-matching rule ensures that for any given operation, exactly zero or one ACTIVE policy can match. Entity scope (company-bound vs global) is declared at entity registration time and is immutable. Because entityName and companyId are immutable after creation, the audit module validates this scope-matching constraint at policy creation time only.
+
+## Business Purpose
+
+- Regulatory compliance demands that certain fields (e.g., financial amounts, approval statuses) are tracked, while auditing every field is unnecessary and expensive
+- Security teams need visibility into sensitive data changes (e.g., user role assignments, payment details) without flooding the audit log with noise
+- Sensitive data protection requires that field values containing personal data, credentials, or payment details are masked, hashed, or excluded from audit logs to prevent the audit trail from becoming a secondary store of sensitive information
+- Performance optimization requires granular control — Dynamics 365, SAP, and other major ERPs explicitly warn that broad audit configurations degrade system throughput
+- Multi-company organizations need different audit policies per legal entity to reflect varying local regulatory requirements
+- Safe rollout of audit changes is critical — a misconfigured policy should be testable in DRAFT before it starts capturing production data
+- Rollback capability allows administrators to deactivate a policy immediately if it causes performance issues or captures unintended data
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createAuditPolicy
+    Draft --> Active: activateAuditPolicy
+    Draft --> Active: replaceAuditPolicy (atomic swap:\ndeactivates current ACTIVE,\nactivates this DRAFT)
+    Active --> Inactive: deactivateAuditPolicy
+    Inactive --> Active: reactivateAuditPolicy
+    Draft --> [*]: deleteAuditPolicy
+```
+
+The policy creation and configuration flow follows this pattern:
+
+```mermaid
+flowchart TD
+    A[Create Audit Policy] --> B[Specify Target Entity]
+    B --> C[Select Operation Type]
+    C --> D[Add Field-Level Rules]
+    D --> D2[Set Sensitivity Mode per Field]
+    D2 --> E{All fields configured?}
+    E -->|No| D
+    E -->|Yes| F{Ready to activate?}
+    F -->|No| G[Continue editing]
+    G --> B
+    F -->|Yes| H{Conflicting ACTIVE policy exists?}
+    H -->|Yes| H2{Use atomic replacement?}
+    H2 -->|Yes| H3[replaceAuditPolicy:\nDeactivate existing + Activate new\nin single transaction]
+    H2 -->|No| H4[Reject: deactivate existing first]
+    H3 --> J[Audit Capture Begins]
+    H -->|No| I[Activate Policy]
+    I --> J
+```
+
+When a data operation occurs, the system evaluates active policies to determine whether to record an audit entry. Because policy scope must match entity scope, the lookup is unambiguous — there is at most one matching ACTIVE policy:
+
+```mermaid
+flowchart TD
+    A[Data Operation Occurs] --> B{Entity is company-bound?}
+    B -->|Yes| C[Look up ACTIVE policy for entity + companyId + operation]
+    B -->|No| D[Look up ACTIVE global policy for entity + operation]
+    C --> E{Policy found?}
+    D --> E
+    E -->|No| F[No audit entry]
+    E -->|Yes| G{Field-level rules defined?}
+    G -->|No| H[Audit all eligible fields on entity]
+    G -->|Yes| I[Audit only specified fields]
+    H --> J[Apply sensitivity modes to values]
+    I --> J
+    J --> K[Record Audit Entry with processed values]
+```
+
+## Scenario Patterns
+
+- **Compliance-Driven Field Tracking**: A financial services company creates two policies — one for UPDATE and one for DELETE — on the Journal Entry entity, each tracking only the amount, account, and approval status fields. This satisfies SOX requirements without capturing every minor metadata change
+- **Security Monitoring**: An administrator creates three policies (one per operation type: CREATE, UPDATE, DELETE) on the User Role Assignment entity, each capturing every field. This provides a complete record of privilege changes for security review
+- **Sensitive Data Protection**: A policy auditing the Employee entity marks the socialSecurityNumber field with sensitivity mode EXCLUDE (omitted from audit logs entirely) and the salary field with MASK (stored as a masked value like "***"). This ensures the audit trail records that these fields changed without exposing the raw values
+- **Gradual Rollout**: A new audit policy for the Sales Order entity is created in DRAFT and reviewed by the compliance team. After validation, it is activated in a single company first, then additional company-scoped policies are created and activated for other subsidiaries
+- **Performance Remediation**: An overly broad policy auditing all fields on a high-volume entity is deactivated immediately when monitoring reveals degraded throughput. A replacement policy targeting only critical fields is created and activated
+- **Multi-Company Differentiation**: A global organization creates separate policies for its EU and US subsidiaries — the EU policy audits personal data fields to comply with GDPR (with appropriate masking), while the US policy focuses on financial fields for SOX compliance
+- **Atomic Policy Replacement**: An administrator needs to add new fields to an active policy. They create a new DRAFT policy with the updated field set and use `replaceAuditPolicy` to atomically deactivate the existing ACTIVE policy and activate the replacement in a single transaction — ensuring no gap in audit coverage
+- **Manual Policy Replacement (with gap)**: An administrator deactivates the existing ACTIVE policy and then activates a replacement DRAFT policy in two separate steps. During the window between deactivation and activation, events for that entity + operation are silently discarded. This approach is acceptable when a brief audit gap is tolerable
+- **Policy Cleanup**: A DRAFT policy that was created for evaluation but never needed is deleted without affecting any audit data
+
+## Test Cases
+
+- Audit policy lifecycle follows DRAFT → ACTIVE ↔ INACTIVE state machine
+- Policies can only be created in DRAFT status
+- Only DRAFT policies can be deleted; ACTIVE and INACTIVE policies cannot
+- Target entity name is required and must be non-empty
+- Exactly one operation type (CREATE, UPDATE, or DELETE) must be specified per policy
+- Operation types are limited to the set CREATE, UPDATE, DELETE — invalid values are rejected
+- A policy without field-level rules audits all eligible fields on the target entity (as defined by the entity's auditableFields registration)
+- A policy with field-level rules audits only the specified fields (which must be a subset of the entity's auditableFields)
+- Field names in field-level rules must be non-empty strings
+- Duplicate field names within the same policy are rejected
+- Activating a policy without a target entity is rejected
+- A policy must have exactly one operation type — policies without an operation type cannot be activated
+- Only ACTIVE policies trigger audit capture; DRAFT and INACTIVE policies do not
+- Deactivating a policy stops new audit capture but does not delete previously recorded audit entries
+- Reactivating an INACTIVE policy resumes audit capture
+- Company-scoped policies apply only to operations within that company
+- A global policy (no company scope) applies to operations on global entities
+- At most one ACTIVE policy can exist for a given (entityName, companyId, operationType) combination — activating a conflicting policy is rejected
+- Activating a policy that would conflict with an existing ACTIVE policy returns an error instructing the administrator to deactivate the existing policy first
+- Creating a global policy (companyId = null) for a company-bound entity is rejected
+- Creating a company-scoped policy for a global entity is rejected
+- Entity scope (company-bound vs global) is validated at policy creation time
+- For any given entity + operation, at most one ACTIVE policy can match because policy scope must align with entity scope
+- Deleting an ACTIVE or INACTIVE policy returns an error
+- Each field-level rule supports a sensitivity mode: CAPTURE (default, store raw value), MASK (store masked representation), HASH (store one-way hash), or EXCLUDE (omit value entirely)
+- When sensitivity mode is MASK, the stored value replaces all but the last 4 characters with asterisks (or stores "***" if the value is 4 characters or fewer)
+- When sensitivity mode is HASH, the stored value is a one-way hash of the original value
+- When sensitivity mode is EXCLUDE, the ChangeDetail records that the field changed but stores null for both oldValue and newValue
+- Fields without an explicit sensitivity mode default to CAPTURE (raw value stored)
+- Sensitivity modes are enforced at write time — once an audit entry is persisted, the original raw value cannot be recovered from MASK, HASH, or EXCLUDE entries
+- `replaceAuditPolicy` atomically deactivates the current ACTIVE policy and activates the replacement DRAFT policy in a single transaction
+- `replaceAuditPolicy` requires the replacement policy to be in DRAFT status — non-DRAFT replacements are rejected
+- `replaceAuditPolicy` requires an existing ACTIVE policy for the same (entityName, companyId, operationType) — if none exists, the operation is rejected (use `activateAuditPolicy` instead)
+- After `replaceAuditPolicy`, the previously active policy is in INACTIVE status and the replacement is in ACTIVE status
+- During manual (non-atomic) replacement, events arriving between deactivation and activation are silently discarded
+- Creating, updating, activating, deactivating, reactivating, replacing, and deleting audit policies requires the `manageAuditPolicies` permission at the appropriate scope
+- A caller with company-scoped `manageAuditPolicies` can only manage policies for their assigned companies
+- A caller with global-scoped `manageAuditPolicies` can only manage global policies
+- A caller without `manageAuditPolicies` permission receives an authorization error when attempting policy operations
+
+## Reference Links
+
+- [Dynamics 365 Configure Entity and Attribute Auditing](https://learn.microsoft.com/en-us/power-platform/admin/manage-dataverse-auditing)
+- [SAP Change Document Objects](https://help.sap.com/docs/ABAP_PLATFORM_NEW/b5670aaaa2364a29935f40b16499972d/4873464e4cf611d3a6510000e835363f.html)
+- [Odoo Tracking Field Changes](https://www.odoo.com/documentation/19.0/developer/reference/backend/orm.html)
+- [AWS CloudTrail Trail Configuration](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html)
+- [Microsoft Dataverse Auditing](https://learn.microsoft.com/en-us/power-platform/admin/manage-dataverse-auditing)

package/src/modules/audit/docs/features/field-level-change-tracking.md

@@ -0,0 +1,95 @@
+# Field-Level Change Tracking
+
+## Overview
+
+Field-Level Change Tracking records the old and new values for each individual field that changes within a business operation, enabling precise before/after comparison at the most granular level. Each change detail is linked to a parent audit entry and captures the field name, previous value, and new value as serialized strings. This approach follows the common ERP pattern of a ChangeDetail entity associated with a parent AuditEntry by auditEntryId.
+
+Not all field types are eligible for audit capture. Scalar fields (string, number, boolean, date, enum) and short text fields (≤ 4,000 characters) are serialized as strings and stored as-is. Long text fields (> 4,000 characters) are truncated to 4,000 characters with a `[truncated]` suffix. Rich text / HTML fields are stripped to plain text, then truncated to 4,000 characters if needed. Binary / BLOB fields are excluded from audit capture entirely and are not eligible for policy field rules. File attachment references capture only the reference metadata (file ID, filename, size), not the file content. Relation fields (foreign keys) capture the foreign key ID as a string. Collection / array fields are serialized as JSON strings and truncated to 4,000 characters if the serialized form exceeds the limit. Computed / derived fields are excluded from audit capture because they are not persisted state. Fields not listed in the entity's `auditableFields` registration are never captured regardless of type. The 4,000-character truncation limit applies after sensitivity mode processing (MASK/HASH/CAPTURE).
+
+By storing values as serialized strings regardless of the original data type, the system maintains a uniform storage model while supporting any eligible field type. For CREATE operations the old value is null and the new value contains the initial value; for DELETE operations the old value contains the last known value and the new value is null; for UPDATE operations both values are populated but only for fields that actually changed. This design keeps the audit trail compact while providing full traceability.
+
+Field values are subject to the sensitivity mode defined in the applicable audit policy. Fields configured as MASK store a masked representation, HASH fields store a one-way hash, and EXCLUDE fields record that a change occurred but store null for both old and new values. This ensures that change tracking does not become a secondary store of sensitive data.
+
+## Business Purpose
+
+- **Regulatory compliance**: Auditors and regulators require evidence of exactly what changed, when, and by whom — field-level tracking satisfies SOX, GDPR, and similar mandates that demand detailed change history
+- **Sensitive data protection**: Field values are processed through sensitivity modes (CAPTURE, MASK, HASH, EXCLUDE) defined in audit policies before storage, preventing the audit trail from containing raw personal data, credentials, or payment information
+- **Dispute resolution**: When discrepancies arise (e.g., pricing, quantities, addresses), field-level history provides an authoritative record of the before and after state for each affected field
+- **Operational debugging**: Support teams can quickly identify which field change caused a downstream issue without reviewing entire record snapshots
+- **Rollback analysis**: Knowing the previous value of each changed field enables informed decisions about whether and how to revert a change
+- **Change auditing across modules**: Every transactional module (accounting, sales, purchasing, inventory) and global modules (user-management, primitives) benefit from a single, consistent mechanism for capturing field-level mutations
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Business Operation Occurs] --> B[Determine Operation Type]
+    B --> C{CREATE / UPDATE / DELETE?}
+    C -->|CREATE| D[Capture all initial field values]
+    C -->|UPDATE| E[Compare old and new record states]
+    C -->|DELETE| F[Capture all last-known field values]
+    D --> G[Generate ChangeDetail entries\noldValue = null, newValue = initial value]
+    E --> H[Generate ChangeDetail entries\nonly for fields that differ]
+    F --> I[Generate ChangeDetail entries\noldValue = last value, newValue = null]
+    G --> J[Apply sensitivity modes from policy]
+    H --> J
+    I --> J
+    J --> K[Link ChangeDetail records to parent AuditEntry]
+    K --> L[Persist AuditEntry + ChangeDetails]
+```
+
+```mermaid
+flowchart TD
+    A[Query Audit History for Record] --> B[Retrieve AuditEntry list]
+    B --> C[Select AuditEntry of interest]
+    C --> D[Retrieve linked ChangeDetail records]
+    D --> E[Display field-by-field before/after comparison]
+```
+
+## Scenario Patterns
+
+- **Price Change Audit**: A sales manager updates the unit price on a quotation line. The system records a ChangeDetail with fieldName = unitPrice, oldValue = "100.00", and newValue = "95.00", providing a clear trail for margin analysis and approval workflows
+- **Address Correction**: A customer service representative corrects a shipping address. Each modified address field (street, city, postalCode) produces its own ChangeDetail entry, allowing reviewers to see exactly which parts of the address were changed
+- **Sensitive Field Masking**: An HR administrator updates an employee's salary. The policy defines salary with sensitivity mode MASK, so the ChangeDetail stores oldValue = "***" and newValue = "***", recording that the field changed without exposing the actual values
+- **Excluded Field**: A system updates a user's password hash. The policy defines passwordHash with sensitivity mode EXCLUDE, so the ChangeDetail stores fieldName = "passwordHash" with both oldValue = null and newValue = null, recording that the field changed without storing any value
+- **Record Creation Baseline**: When a new purchase order is created, ChangeDetail entries are generated for every populated field with oldValue = null, establishing the initial baseline for all future change comparisons
+- **Record Deletion Snapshot**: When a draft invoice is deleted, ChangeDetail entries capture the last known value of every field with newValue = null, preserving a complete snapshot of the record at the time of deletion
+- **Bulk Field Update**: An administrator updates the cost center on 50 inventory items. Each item's audit entry contains a single ChangeDetail for the costCenter field, keeping the audit trail compact by recording only the field that changed rather than full record snapshots
+- **No-Op Detection**: A user saves a record without modifying any fields. No ChangeDetail entries are created because no field values differ, avoiding unnecessary audit noise
+
+## Test Cases
+
+- Each ChangeDetail record is linked to exactly one parent AuditEntry via auditEntryId
+- ChangeDetail captures fieldName, oldValue, and newValue as serialized strings
+- For a CREATE operation, oldValue is null and newValue contains the initial field value
+- For a DELETE operation, oldValue contains the last known value and newValue is null
+- For an UPDATE operation, both oldValue and newValue are populated
+- UPDATE operations generate ChangeDetail entries only for fields whose values actually changed
+- Fields that did not change during an UPDATE are not recorded as ChangeDetail entries
+- A save operation with no field changes produces zero ChangeDetail entries
+- Multiple field changes within a single operation each produce a separate ChangeDetail record under the same AuditEntry
+- fieldName is required and must be non-empty on every ChangeDetail record
+- Values are stored as serialized strings regardless of the original data type (integer, boolean, date, etc.)
+- Querying ChangeDetails by auditEntryId returns all field-level changes for that audit entry
+- ChangeDetail records are immutable once persisted — they cannot be updated or deleted
+- A CREATE operation on a record with N populated fields produces N ChangeDetail entries
+- When the policy sensitivity mode for a field is MASK, oldValue and newValue store masked representations
+- When the policy sensitivity mode for a field is HASH, oldValue and newValue store one-way hashes
+- When the policy sensitivity mode for a field is EXCLUDE, both oldValue and newValue are null, but the ChangeDetail record is still created to indicate the field changed
+- Fields without an explicit sensitivity mode in the policy default to CAPTURE (raw values stored)
+- Binary / BLOB fields are excluded from audit capture and cannot be added to policy field rules
+- Computed / derived fields are excluded from audit capture
+- Long text values exceeding 4,000 characters are truncated with a `[truncated]` suffix
+- Rich text / HTML field values are stripped to plain text before storage
+- Collection / array field values are serialized as JSON strings
+- Serialized values exceeding 4,000 characters are truncated with a `[truncated]` suffix
+- 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
+- Truncation is applied after sensitivity mode processing
+
+## Reference Links
+
+- [SAP Change Documents (CDHDR/CDPOS)](https://help.sap.com/doc/saphelp_nw75/7.5.5/en-US/4d/b2ba6fbb571e57e10000000a42189b/frameset.htm)
+- [Odoo Mail Tracking Values](https://www.odoo.com/documentation/19.0/developer/reference/backend/logging.html)
+- [Dynamics 365 Auditing Overview](https://learn.microsoft.com/en-us/power-platform/admin/manage-dataverse-auditing)
+- [AWS CloudTrail Log Event Reference](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference.html)

package/src/modules/audit/docs/models/AuditEntry.md

@@ -0,0 +1,55 @@
+# AuditEntry
+
+## Description
+
+AuditEntry represents a single immutable record of a data mutation captured by the audit system. Each entry records a unique `eventId` for deduplication and idempotency, the actor identity (actorType and actorId, with optional metadata such as IP address, user agent, sessionId, requestId, or onBehalfOf reference), the operation type (CREATE, UPDATE, DELETE), the affected entity reference (entityType and entityId), and a system-generated timestamp. Entries may be scoped by companyId for multi-company data isolation; entries for global entities omit companyId. An optional correlationId groups related events within a logical operation (e.g., bulk updates, cascading workflows).
+
+Examples: "User jdoe updated SalesOrder SO-1234 at 2025-01-15T10:30:00Z", "System job recalculated exchange rates (global scope, correlationId groups all rate changes)".
+
+## Domain Model Definitions
+
+### Model type
+
+AppendOnly
+
+### Command Definitions
+
+- [logAuditEvent](../commands/LogAuditEvent.md) - Ingest an audit event, creating an AuditEntry with linked ChangeDetail records
+
+### Query Definitions
+
+- [getAuditEntry](../queries/GetAuditEntry.md) - Retrieve a single audit entry by ID
+- [searchAuditEntries](../queries/SearchAuditEntries.md) - Search and filter audit entries by actor, entity, operation type, date range, and company scope
+- [getAuditSummary](../queries/GetAuditSummary.md) - Retrieve aggregated audit entry counts grouped by configurable dimensions
+
+### Models
+
+- AuditEntry
+- ChangeDetail
+
+### Invariants
+
+- eventId is globally unique (UUID) and used for idempotency — duplicate eventId submissions are silently discarded (returns success, no new entry created)
+- Once persisted, an AuditEntry cannot be modified or deleted (append-only, immutable)
+- actorType is required and must be one of USER, SYSTEM, or SERVICE
+- actorId is required and must be non-empty regardless of actorType
+- An operation submitted without a valid actor identity (actorType + actorId) is rejected
+- entityType must reference a registered auditable entity — events referencing an unregistered entityType are rejected with a validation error
+- operationType must be one of CREATE, UPDATE, or DELETE
+- companyId is required for company-bound entities and must be null for global entities — scope mismatches are rejected with a validation error
+- timestamp is system-generated at ingestion time and cannot be supplied or overridden by the caller
+- correlationId is optional (UUID) and groups related events from a single logical operation (e.g., bulk updates, cascading workflows, saga steps)
+- onBehalfOf is optional and stores the delegated user's identity when an action is performed on behalf of another actor
+- actorMetadata (ipAddress, userAgent, sessionId, requestId) is optional and stored when provided
+- An event for an entity + operation combination with no active policy is silently discarded (no entry created)
+- Audit entries are returned in chronological order by default
+- Large result sets support pagination for efficient retrieval
+- Querying audit entries requires the `viewAuditHistory` permission at the appropriate scope
+- Querying audit summaries requires the `viewAuditSummary` permission at the appropriate scope
+
+### Relationships
+
+- **Has Many ChangeDetail**: Each AuditEntry has zero or more ChangeDetail records linked by auditEntryId, capturing field-level changes
+- **References AuditableEntity**: entityType must match a registered AuditableEntity's entityName
+- **References user-management (cross-module)**: actorId references a userId when actorType is USER; onBehalfOf references a delegated userId
+- **References organization (cross-module)**: companyId references a Company from the organization module for company-scoped entries

package/src/modules/audit/docs/models/AuditPolicy.md

@@ -0,0 +1,79 @@
+# AuditPolicy
+
+## Description
+
+AuditPolicy defines which entities, operations, and fields are tracked by the audit system. Each policy targets a specific entity and operation type, with an optional company scope for multi-company deployments. Policies follow a lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE) that enables safe rollout and rollback. Only ACTIVE policies trigger audit capture. A uniqueness constraint ensures at most one ACTIVE policy exists for a given (entityName, companyId, operationType) combination. Policy scope must match the target entity's scope — company-bound entities require company-scoped policies; global entities require global policies.
+
+Examples: "ACTIVE policy auditing UPDATE on SalesOrder for company-123", "DRAFT policy under review for DELETE on JournalEntry".
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createAuditPolicy
+    Draft --> Active: activateAuditPolicy
+    Draft --> Active: replaceAuditPolicy (atomic swap)
+    Active --> Inactive: deactivateAuditPolicy
+    Inactive --> Active: reactivateAuditPolicy
+    Draft --> [*]: deleteAuditPolicy
+    note right of Draft: Only DRAFT policies can be deleted
+    note right of Active: At most one ACTIVE per (entityName, companyId, operationType)
+```
+
+### Command Definitions
+
+- [createAuditPolicy](../commands/CreateAuditPolicy.md) - Create a new audit policy in DRAFT status
+- [updateAuditPolicy](../commands/UpdateAuditPolicy.md) - Modify a DRAFT audit policy's configuration
+- [activateAuditPolicy](../commands/ActivateAuditPolicy.md) - Transition a DRAFT policy to ACTIVE
+- [deactivateAuditPolicy](../commands/DeactivateAuditPolicy.md) - Transition an ACTIVE policy to INACTIVE
+- [reactivateAuditPolicy](../commands/ReactivateAuditPolicy.md) - Transition an INACTIVE policy back to ACTIVE
+- [replaceAuditPolicy](../commands/ReplaceAuditPolicy.md) - Atomically deactivate current ACTIVE and activate a DRAFT replacement
+- [deleteAuditPolicy](../commands/DeleteAuditPolicy.md) - Permanently remove a DRAFT policy
+
+### Query Definitions
+
+- [getAuditPolicy](../queries/GetAuditPolicy.md) - Retrieve a single audit policy by ID
+- [listAuditPolicies](../queries/ListAuditPolicies.md) - List audit policies with optional filters
+
+### Models
+
+- AuditPolicy
+- PolicyFieldRule
+
+### Invariants
+
+- Policies are always created in DRAFT status
+- At most one ACTIVE policy can exist for a given (entityName, companyId, operationType) combination — activating a conflicting policy is rejected with an error instructing the administrator to deactivate the existing policy first
+- Only DRAFT policies can be deleted; ACTIVE and INACTIVE policies cannot — deleting an ACTIVE or INACTIVE policy returns an error
+- Target entity name is required and must be non-empty
+- Target entity name must reference a registered AuditableEntity
+- Exactly one operation type (CREATE, UPDATE, or DELETE) must be specified per policy — policies without an operation type cannot be activated
+- Operation types are limited to the set CREATE, UPDATE, DELETE — invalid values are rejected
+- Activating a policy without a target entity is rejected
+- Policy scope must match the target entity's scope: company-bound entities require company-scoped policies (companyId set); global entities require global policies (companyId null) — mismatches are rejected at creation time
+- entityName and companyId are immutable after creation — scope is validated only at creation time; updates cannot change the policy's scope
+- Only ACTIVE policies trigger audit capture; DRAFT and INACTIVE policies do not
+- Deactivating a policy stops new audit capture but does not delete previously recorded audit entries
+- Reactivating an INACTIVE policy resumes audit capture
+- A policy without field-level rules audits all eligible fields on the target entity (as defined by the entity's auditableFields registration)
+- A policy with field-level rules audits only the specified fields (which must be a subset of the entity's auditableFields)
+- `replaceAuditPolicy` atomically deactivates the current ACTIVE policy and activates the replacement DRAFT policy in a single transaction
+- `replaceAuditPolicy` requires the replacement policy to be in DRAFT status — non-DRAFT replacements are rejected
+- `replaceAuditPolicy` requires an existing ACTIVE policy for the same (entityName, companyId, operationType) — if none exists, the operation is rejected (use `activateAuditPolicy` instead)
+- After `replaceAuditPolicy`, the previously active policy is in INACTIVE status and the replacement is in ACTIVE status
+- During manual (non-atomic) replacement, events arriving between deactivation and activation are silently discarded
+- Creating, updating, activating, deactivating, reactivating, replacing, and deleting audit policies requires the `manageAuditPolicies` permission at the appropriate scope
+- A caller with company-scoped `manageAuditPolicies` can only manage policies for their assigned companies
+- A caller with global-scoped `manageAuditPolicies` can only manage global policies
+
+### Relationships
+
+- **Has Many PolicyFieldRule**: Each AuditPolicy has zero or more PolicyFieldRule records defining field-level audit configuration
+- **References AuditableEntity**: entityName must match a registered AuditableEntity
+- **References organization (cross-module)**: companyId references a Company from the organization module for company-scoped policies

package/src/modules/audit/docs/models/AuditableEntity.md

@@ -0,0 +1,38 @@
+# AuditableEntity
+
+## Description
+
+AuditableEntity represents a registration record for an entity that is eligible for audit tracking. Other modules register their entities at initialization time by declaring the entityName, entityScope (COMPANY_BOUND or GLOBAL), and the list of auditableFields eligible for capture. The audit module validates incoming audit events against registered entities — events referencing an unregistered entityType are rejected. Entity scope is immutable once registered and determines whether policies and audit entries for this entity must be company-scoped or global.
+
+Examples: "SalesOrder registered as COMPANY_BOUND with fields [{fieldName: 'amount', fieldType: 'scalar'}, {fieldName: 'status', fieldType: 'scalar'}, {fieldName: 'customerId', fieldType: 'relation'}]", "User registered as GLOBAL with fields [{fieldName: 'email', fieldType: 'scalar'}, {fieldName: 'role', fieldType: 'scalar'}, {fieldName: 'isActive', fieldType: 'scalar'}]".
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [registerAuditableEntity](../commands/RegisterAuditableEntity.md) - Register a new entity for audit tracking
+
+### Query Definitions
+
+None. AuditableEntity registrations are referenced internally by the audit module during policy creation and event ingestion for validation purposes.
+
+### Models
+
+- AuditableEntity
+
+### Invariants
+
+- entityName is required, must be non-empty, and must be unique across all registrations
+- entityScope must be one of COMPANY_BOUND or GLOBAL and is immutable once registered
+- auditableFields is a JSON-serialized array of field definitions (`{fieldName: string, fieldType?: string}`) eligible for audit capture; must contain at least one entry
+- Only the following fieldType values are eligible for inclusion in auditableFields: `scalar`, `richtext`, `array`, `relation`, `file`. Any other fieldType (e.g. `binary`, `computed`) is rejected
+
+### Relationships
+
+- **Referenced By AuditEntry**: AuditEntry.entityType must match a registered AuditableEntity.entityName
+- **Referenced By AuditPolicy**: AuditPolicy.entityName must match a registered AuditableEntity.entityName
+- **Referenced By emitting modules (reverse dependency)**: Other ERP modules register their auditable entities at initialization time

package/src/modules/audit/docs/models/ChangeDetail.md

@@ -0,0 +1,55 @@
+# ChangeDetail
+
+## Description
+
+ChangeDetail records the old and new values for a single field that changed within a business operation. Each ChangeDetail is linked to a parent AuditEntry via auditEntryId and captures the fieldName, previous value (oldValue), and new value (newValue) as serialized strings. Values are subject to the sensitivity mode defined in the applicable audit policy: CAPTURE stores raw values, MASK stores masked representations, HASH stores one-way hashes, and EXCLUDE stores null for both values while still recording that the field changed. Values exceeding 4,000 characters are truncated with a `[truncated]` suffix after sensitivity mode processing.
+
+Examples: "unitPrice changed from '100.00' to '95.00'", "salary changed (MASK mode: '***' to '***')".
+
+## Domain Model Definitions
+
+### Model type
+
+AppendOnly
+
+### Command Definitions
+
+- [logAuditEvent](../commands/LogAuditEvent.md) - ChangeDetail records are created as part of the logAuditEvent command, linked to the parent AuditEntry
+
+### Query Definitions
+
+- [getChangeDetails](../queries/GetChangeDetails.md) - Retrieve all field-level change details for a given audit entry
+
+### Models
+
+- ChangeDetail
+
+### Invariants
+
+- Each ChangeDetail belongs to exactly one parent AuditEntry via auditEntryId
+- fieldName is required and must be non-empty
+- Values are stored as serialized strings regardless of original data type (integer, boolean, date, etc.)
+- For CREATE operations, oldValue is null and newValue contains the initial value
+- For DELETE operations, oldValue contains the last known value and newValue is null
+- For UPDATE operations, both oldValue and newValue are populated, but only for fields that actually changed
+- A save operation with no field changes produces zero ChangeDetail entries (no-op detection)
+- A CREATE operation on a record with N populated fields produces N ChangeDetail entries
+- Once persisted, ChangeDetail records cannot be modified or deleted (immutable)
+- Binary / BLOB fields are excluded from capture entirely and are not eligible for policy field rules
+- Computed / derived fields are excluded from capture
+- Long text fields (> 4,000 characters) are truncated to 4,000 characters with a `[truncated]` suffix
+- Rich text / HTML field values are stripped to plain text before storage, then truncated if needed
+- Collection / array field values are serialized as JSON strings and truncated to 4,000 characters if the serialized form exceeds the limit
+- Relation field values capture the foreign key ID as a string
+- File attachment fields capture reference metadata (file ID, filename, size), not the file content
+- Truncation is applied after sensitivity mode processing (MASK/HASH/CAPTURE)
+- When sensitivity mode is CAPTURE (default), raw values are stored
+- When sensitivity mode is MASK, oldValue and newValue store masked representations
+- When sensitivity mode is HASH, oldValue and newValue store one-way hashes
+- When sensitivity mode is EXCLUDE, both oldValue and newValue are null, but the ChangeDetail record is still created to indicate the field changed
+- Fields without an explicit sensitivity mode in the policy default to CAPTURE
+
+### Relationships
+
+- **Belongs To AuditEntry**: Each ChangeDetail is linked to exactly one AuditEntry via auditEntryId
+- **Governed By PolicyFieldRule**: Sensitivity mode applied to stored values is determined by the PolicyFieldRule associated with the parent AuditEntry's applicable AuditPolicy