@tailor-platform/erp-kit 0.3.0 → 0.4.1

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

@@ -0,0 +1,45 @@
+# PolicyFieldRule
+
+## Description
+
+PolicyFieldRule defines how a specific field is handled during audit capture for a parent AuditPolicy. Each rule specifies a fieldName and a sensitivityMode that controls how the field's value is stored in ChangeDetail records. Sensitivity modes include CAPTURE (store raw value, default), MASK (store masked representation), HASH (store one-way hash), and EXCLUDE (record that the field changed but store null for both values). Field names must be a subset of the target entity's registered auditableFields.
+
+Examples: "socialSecurityNumber with EXCLUDE mode", "salary with MASK mode", "amount with CAPTURE mode (default)".
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createAuditPolicy](../commands/CreateAuditPolicy.md) - PolicyFieldRules are created as part of audit policy creation
+- [updateAuditPolicy](../commands/UpdateAuditPolicy.md) - PolicyFieldRules are modified as part of audit policy updates
+
+### Query Definitions
+
+- [getAuditPolicy](../queries/GetAuditPolicy.md) - PolicyFieldRules are returned as part of audit policy retrieval
+- [listAuditPolicies](../queries/ListAuditPolicies.md) - PolicyFieldRules are returned as part of audit policy listing
+
+### Models
+
+- PolicyFieldRule
+
+### Invariants
+
+- Each PolicyFieldRule belongs to exactly one AuditPolicy via auditPolicyId
+- fieldName is required and must be non-empty
+- fieldName must be a member of the target entity's registered auditableFields
+- Duplicate fieldNames within the same AuditPolicy are rejected
+- sensitivityMode must be one of CAPTURE, MASK, HASH, or EXCLUDE; defaults to CAPTURE if not specified
+- When sensitivityMode 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 sensitivityMode is HASH, the stored value is a one-way hash of the original value
+- When sensitivityMode is EXCLUDE, ChangeDetail records store null for both oldValue and newValue
+- 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
+- Binary / BLOB fields are not eligible for policy field rules and cannot be added as a fieldName
+
+### Relationships
+
+- **Belongs To AuditPolicy**: Each PolicyFieldRule is linked to exactly one AuditPolicy via auditPolicyId
+- **Validated Against AuditableEntity**: fieldName must be a member of the target entity's registered auditableFields

package/src/modules/audit/docs/queries/GetAuditEntry.md

@@ -0,0 +1,49 @@
+# GetAuditEntry
+
+## Overview
+
+GetAuditEntry retrieves a single audit entry by its unique identifier. Returns the full AuditEntry record including eventId, actor identity, entity reference, operation type, timestamp, and scope, or null if no matching entry exists.
+
+This query requires the `viewAuditHistory` permission at the appropriate scope.
+
+## Business Rules
+
+- Lookup by `id` performs an exact UUID match
+- Returns the full AuditEntry record including all fields
+- Returns null when no matching entry is found
+- Caller must hold `viewAuditHistory` permission at the appropriate scope
+- A caller with company-scoped permission can only retrieve entries for their assigned companies
+- A caller with global-scoped permission can retrieve global (company-unscoped) entries
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup request] --> B{Caller has viewAuditHistory?}
+    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
+    B -->|Yes| D[Query AuditEntry by id]
+    D --> E{Found?}
+    E -->|Yes| F{Caller authorized for entry's scope?}
+    F -->|No| G[Return error: UNAUTHORIZED]
+    F -->|Yes| H[Return audit entry]
+    E -->|No| I[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INSUFFICIENT_PERMISSION**: Caller lacks `viewAuditHistory` permission
+- **UNAUTHORIZED**: Caller's permission scope does not cover the requested entry's scope
+
+## Test Cases
+
+- returns audit entry when found by id
+- returns null when audit entry not found
+- returns entry with all fields populated
+- returns company-scoped entry when caller has matching company permission
+- returns global entry when caller has global-scoped permission
+- rejects when caller lacks viewAuditHistory permission
+- rejects when caller lacks permission for entry's company scope

package/src/modules/audit/docs/queries/GetAuditPolicy.md

@@ -0,0 +1,54 @@
+# GetAuditPolicy
+
+## Overview
+
+GetAuditPolicy retrieves a single audit policy by its unique identifier. Returns the full AuditPolicy record including status, entity name, operation type, company scope, and associated PolicyFieldRule records, or null if no matching policy exists.
+
+This query requires the `manageAuditPolicies` permission at the appropriate scope.
+
+## Business Rules
+
+- Lookup by `id` performs an exact UUID match
+- Returns the full AuditPolicy record including associated PolicyFieldRules
+- Does not filter by status — returns DRAFT, ACTIVE, and INACTIVE policies
+- Returns null when no matching policy is found
+- Caller must hold `manageAuditPolicies` permission at the appropriate scope
+- A caller with company-scoped `manageAuditPolicies` can only retrieve policies for their assigned companies
+- A caller with global-scoped `manageAuditPolicies` can only retrieve global policies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup request] --> B{Caller has manageAuditPolicies?}
+    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
+    B -->|Yes| D[Query AuditPolicy by id]
+    D --> E{Found?}
+    E -->|Yes| F{Caller authorized for policy's scope?}
+    F -->|No| G[Return error: UNAUTHORIZED]
+    F -->|Yes| H[Load associated PolicyFieldRules]
+    H --> I[Return policy with field rules]
+    E -->|No| J[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INSUFFICIENT_PERMISSION**: Caller lacks `manageAuditPolicies` permission
+- **UNAUTHORIZED**: Caller's permission scope does not cover the policy's scope
+
+## Test Cases
+
+- returns audit policy when found by id
+- returns null when audit policy not found
+- returns DRAFT policy
+- returns ACTIVE policy
+- returns INACTIVE policy
+- includes associated PolicyFieldRules in response
+- rejects when caller lacks manageAuditPolicies permission
+- rejects when caller lacks permission for policy's company scope
+- returns global policy when caller has global-scoped permission
+- rejects when global-scoped caller retrieves company-scoped policy

package/src/modules/audit/docs/queries/GetAuditSummary.md

@@ -0,0 +1,84 @@
+# GetAuditSummary
+
+## Overview
+
+GetAuditSummary returns aggregated audit statistics without exposing field-level change details. It provides counts of audit entries grouped by configurable dimensions such as entityType, operationType, actorType, and time period. This query is designed for compliance dashboards and operational oversight where administrators need a high-level view of audit activity without access to sensitive before/after field values.
+
+This query requires the `viewAuditSummary` permission at the appropriate scope — a lower-privilege alternative to `viewAuditHistory` which grants access to full audit entry details.
+
+## Business Rules
+
+- Caller must hold `viewAuditSummary` permission at the appropriate scope
+- A caller with company-scoped `viewAuditSummary` can only retrieve summaries for their assigned companies
+- A caller with global-scoped `viewAuditSummary` can retrieve summaries for global (company-unscoped) entries
+- At least one grouping dimension must be specified (entityType, operationType, actorType, or timePeriod)
+- Optional filters: entityType, operationType, actorType, companyId, date range
+- An optional `scope` parameter accepts COMPANY, GLOBAL, or ALL to control which entries are summarized
+- When `scope` is COMPANY (or companyId is provided without explicit scope), returns summary counts scoped to that company only; companyId is required in this case
+- When `scope` is GLOBAL (or companyId is omitted without explicit scope), returns summary counts for global entries only
+- When `scope` is ALL, returns combined summary counts for all scopes the caller is authorized for; if companyId is also provided, it acts as an additional filter within the combined results
+- When both company and global scope are requested via `scope=ALL`, the caller must hold `viewAuditSummary` at each scope they wish to see — unauthorized scopes are silently excluded from the result
+- Response contains only aggregate counts — no eventId, entityId, actorId, change details, or other entry-level data is returned
+- Time period grouping supports DAY, WEEK, and MONTH granularities
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive summary request] --> B{Caller has viewAuditSummary?}
+    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
+    B -->|Yes| D{At least one grouping dimension?}
+    D -->|No| E[Return error: VALIDATION_ERROR]
+    D -->|Yes| F[Apply scope and filter criteria]
+    F --> G{Determine scope}
+    G -->|scope=COMPANY or companyId provided| H[Scope to company entries]
+    G -->|scope=GLOBAL or no companyId| I[Scope to global entries]
+    G -->|scope=ALL| I2[Combine company + global entries\nfor scopes caller is authorized for]
+    H --> J[Aggregate counts by grouping dimensions]
+    I --> J
+    I2 --> J
+    J --> K[Return summary results]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INSUFFICIENT_PERMISSION**: Caller lacks `viewAuditSummary` permission
+- **UNAUTHORIZED**: Caller's permission scope does not cover the requested company scope
+- **VALIDATION_ERROR**: No grouping dimension specified (at least one of entityType, operationType, actorType, or timePeriod is required)
+- **VALIDATION_ERROR**: `scope` is COMPANY but no companyId is provided
+- **INVALID_SCOPE**: `scope` is not one of COMPANY, GLOBAL, or ALL
+
+## Test Cases
+
+- returns entry counts grouped by entityType
+- returns entry counts grouped by operationType
+- returns entry counts grouped by actorType
+- returns entry counts grouped by time period (DAY)
+- returns entry counts grouped by time period (WEEK)
+- returns entry counts grouped by time period (MONTH)
+- combines multiple grouping dimensions
+- filters by entityType before aggregation
+- filters by operationType before aggregation
+- filters by date range before aggregation
+- filters by companyId returning only company-scoped counts
+- returns global entry counts when companyId is omitted
+- returns combined company and global counts when scope is ALL
+- restricts combined results to scopes the caller is authorized for
+- returns only company counts in combined scope when caller lacks global permission
+- returns only global counts in combined scope when caller lacks company permission
+- filters combined scope results by companyId when both scope=ALL and companyId are provided
+- rejects scope=COMPANY when companyId is not provided
+- rejects invalid scope value
+- returns zero counts when no entries match filters
+- rejects when no grouping dimension is specified
+- rejects when caller lacks viewAuditSummary permission
+- rejects when caller lacks permission for requested company scope
+- restricts company-scoped caller to their company even when scope=GLOBAL
+- restricts company-scoped caller to their company even when scope=ALL
+- restricts global-scoped caller to global entries even when scope=COMPANY
+- restricts global-scoped caller to global entries even when scope=ALL
+- does not expose field-level change details in response

package/src/modules/audit/docs/queries/GetChangeDetails.md

@@ -0,0 +1,56 @@
+# GetChangeDetails
+
+## Overview
+
+GetChangeDetails retrieves all field-level change detail records linked to a specific audit entry. Returns a list of ChangeDetail records containing the fieldName, oldValue, and newValue for each field that changed, enabling precise before/after comparison at the field level.
+
+This query requires the `viewAuditHistory` permission at the appropriate scope.
+
+## Business Rules
+
+- Lookup by `auditEntryId` returns all ChangeDetail records for that audit entry
+- Returns an empty list if the audit entry has no change details
+- Returns an error if the referenced audit entry does not exist
+- Authorization is checked against the parent AuditEntry's scope: if the entry is company-scoped, the caller must hold `viewAuditHistory` for that company; if the entry is global, the caller must hold global-scoped `viewAuditHistory`
+- A caller with company-scoped permission can only retrieve change details for entries belonging to their assigned companies
+- A caller with global-scoped permission can retrieve change details for global (company-unscoped) entries
+- ChangeDetail records reflect sensitivity mode processing applied at write time (values may be masked, hashed, or excluded)
+- Caller must hold `viewAuditHistory` permission at the appropriate scope
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive query request] --> B{Caller has viewAuditHistory?}
+    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
+    B -->|Yes| D{AuditEntry exists?}
+    D -->|No| E[Return error: AUDIT_ENTRY_NOT_FOUND]
+    D -->|Yes| F{Caller authorized for entry's scope?}
+    F -->|No| F2[Return error: UNAUTHORIZED]
+    F -->|Yes| G[Query ChangeDetails by auditEntryId]
+    G --> H[Return list of change details]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INSUFFICIENT_PERMISSION**: Caller lacks `viewAuditHistory` permission
+- **UNAUTHORIZED**: Caller's permission scope does not cover the entry's scope
+- **AUDIT_ENTRY_NOT_FOUND**: Referenced audit entry does not exist
+
+## Test Cases
+
+- returns all change details for an audit entry
+- returns empty list when audit entry has no change details
+- returns change details with masked values for MASK sensitivity mode
+- returns change details with hashed values for HASH sensitivity mode
+- returns change details with null values for EXCLUDE sensitivity mode
+- returns change details with raw values for CAPTURE sensitivity mode
+- returns change details for company-scoped entry when caller has matching company permission
+- returns change details for global entry when caller has global-scoped permission
+- rejects when caller lacks permission for entry's company scope
+- returns error when audit entry does not exist
+- rejects when caller lacks viewAuditHistory permission

package/src/modules/audit/docs/queries/ListAuditPolicies.md

@@ -0,0 +1,58 @@
+# ListAuditPolicies
+
+## Overview
+
+ListAuditPolicies retrieves a list of audit policies with optional filters by entity name, status, company scope, and operation type. Returns policies with their associated PolicyFieldRule records. This query supports administrative views for managing audit configurations across entities and companies.
+
+This query requires the `manageAuditPolicies` permission at the appropriate scope.
+
+## Business Rules
+
+- All filter parameters are optional
+- Filtering by entityName returns only policies targeting that entity
+- Filtering by status returns only policies in the specified status (DRAFT, ACTIVE, INACTIVE)
+- Filtering by companyId returns only policies scoped to that company
+- Filtering by companyId explicitly set to null returns only global policies (companyId = null)
+- Omitting the companyId filter entirely returns policies of all scopes (global and company-scoped), subject to the caller's permission scope
+- Filtering by operationType returns only policies for that operation
+- Caller must hold `manageAuditPolicies` permission at the appropriate scope
+- A caller with company-scoped `manageAuditPolicies` can only retrieve policies for their assigned companies
+- A caller with global-scoped `manageAuditPolicies` can only retrieve global policies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive list request] --> B{Caller has manageAuditPolicies?}
+    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
+    B -->|Yes| D[Build query from filter criteria]
+    D --> E[Apply scope restrictions based on caller's permissions]
+    E --> F[Load matching policies with PolicyFieldRules]
+    F --> G[Return list of policies]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INSUFFICIENT_PERMISSION**: Caller lacks `manageAuditPolicies` permission
+- **UNAUTHORIZED**: Caller's permission scope does not cover the requested scope
+
+## Test Cases
+
+- returns all policies when no filters applied
+- returns policies filtered by entityName
+- returns policies filtered by status
+- returns policies filtered by companyId
+- returns only global policies when companyId filter is explicitly null
+- returns policies filtered by operationType
+- combines multiple filter criteria
+- returns policy objects with expected fields
+- returns empty list when no policies match
+- paginates results correctly
+- rejects when caller lacks manageAuditPolicies permission
+- rejects when caller with company-scoped permission requests policies for a different company
+- returns only global policies when caller has global-scoped permission
+- rejects when global-scoped caller requests company-scoped policies

package/src/modules/audit/docs/queries/SearchAuditEntries.md

@@ -0,0 +1,91 @@
+# SearchAuditEntries
+
+## Overview
+
+SearchAuditEntries searches and filters audit entries using multiple criteria: actor identity (actorType, actorId), entity reference (entityType, entityId), operation type, date range, company scope, and correlationId. Results are returned in chronological order by default and support pagination for efficient retrieval of large result sets.
+
+This query requires the `viewAuditHistory` permission at the appropriate scope.
+
+## Business Rules
+
+- All filter parameters are optional; at least one must be 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
+- Querying by date range returns only entries whose timestamp falls within the range
+- An optional `scope` parameter accepts COMPANY, GLOBAL, or ALL to control which entries are returned
+- When `scope` is COMPANY (or companyId is provided without explicit scope), returns only entries scoped to that company; companyId is required in this case
+- When `scope` is GLOBAL (or companyId is omitted without explicit scope), returns only global (company-unscoped) entries
+- When `scope` is ALL, returns combined results for all scopes the caller is authorized for; if companyId is also provided, it acts as an additional filter within the combined results
+- When `scope` is ALL, the caller must hold `viewAuditHistory` at each scope they wish to see — unauthorized scopes are silently excluded from the result
+- An invalid `scope` value is rejected with INVALID_SCOPE
+- `scope` is COMPANY but no companyId is provided is rejected with VALIDATION_ERROR
+- Results are returned in chronological order by default
+- Large result sets support pagination
+- Caller must hold `viewAuditHistory` permission at the appropriate scope
+- A caller with company-scoped permission can only retrieve entries for their assigned companies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive search request] --> B{Caller has viewAuditHistory?}
+    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
+    B -->|Yes| D[Build query from filter criteria]
+    D --> D2{At least one filter provided?}
+    D2 -->|No| D3[Return error: VALIDATION_ERROR]
+    D2 -->|Yes| E{Determine scope}
+    E -->|scope=COMPANY or companyId provided| F[Scope to company entries]
+    E -->|scope=GLOBAL or no companyId| G[Scope to global entries]
+    E -->|scope=ALL| G2[Combine company + global entries\nfor scopes caller is authorized for]
+    F --> H[Apply remaining filters]
+    G --> H
+    G2 --> H
+    H --> I[Order by timestamp ascending]
+    I --> J[Apply pagination]
+    J --> K[Return paginated results]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INSUFFICIENT_PERMISSION**: Caller lacks `viewAuditHistory` permission
+- **UNAUTHORIZED**: Caller's permission scope does not cover the requested company scope
+- **VALIDATION_ERROR**: No filter parameters provided (at least one is required)
+- **VALIDATION_ERROR**: `scope` is COMPANY but no companyId is provided
+- **INVALID_SCOPE**: `scope` is not one of COMPANY, GLOBAL, or ALL
+
+## Test Cases
+
+- returns entries filtered by actorId
+- returns entries filtered by actorType and actorId
+- returns entries filtered by entityType
+- returns entries filtered by entityType and entityId
+- returns entries filtered by operationType
+- returns entries filtered by date range
+- returns entries filtered by companyId
+- returns global entries when companyId is omitted
+- returns only company entries when scope is COMPANY
+- returns only global entries when scope is GLOBAL
+- returns combined company and global entries when scope is ALL
+- restricts combined results to scopes the caller is authorized for when scope is ALL
+- returns only company entries in combined scope when caller lacks global permission
+- returns only global entries in combined scope when caller lacks company permission
+- filters combined scope results by companyId when both scope=ALL and companyId are provided
+- rejects scope=COMPANY when companyId is not provided
+- rejects invalid scope value
+- returns entries filtered by correlationId
+- combines multiple filter criteria
+- returns results in chronological order
+- paginates large result sets
+- returns empty list when no entries match
+- rejects when no filter parameters are provided
+- rejects when caller lacks viewAuditHistory permission
+- rejects when caller lacks permission for requested company scope
+- restricts company-scoped caller to their company even when scope=GLOBAL
+- restricts company-scoped caller to their company even when scope=ALL
+- restricts global-scoped caller to global entries even when scope=COMPANY
+- restricts global-scoped caller to global entries even when scope=ALL

package/src/modules/audit/generated/kysely-tailordb.ts

@@ -0,0 +1,92 @@
+import {
+  createGetDB,
+  type Generated,
+  type Timestamp,
+  type NamespaceDB,
+  type NamespaceInsertable,
+  type NamespaceSelectable,
+  type NamespaceTable,
+  type NamespaceTableName,
+  type NamespaceTransaction,
+  type NamespaceUpdateable,
+} from "@tailor-platform/sdk/kysely";
+
+export interface Namespace {
+  "main-db": {
+    AuditEntry: {
+      id: Generated<string>;
+      eventId: string;
+      actorType: string;
+      actorId: string;
+      entityType: string;
+      entityId: string;
+      operationType: string;
+      companyId: string | null;
+      correlationId: string | null;
+      ipAddress: string | null;
+      userAgent: string | null;
+      sessionId: string | null;
+      requestId: string | null;
+      onBehalfOf: string | null;
+      timestamp: Timestamp;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    AuditPolicy: {
+      id: Generated<string>;
+      entityName: string;
+      companyId: string | null;
+      operationType: string;
+      status: string;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    AuditableEntity: {
+      id: Generated<string>;
+      entityName: string;
+      entityScope: string;
+      auditableFields: string;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    ChangeDetail: {
+      id: Generated<string>;
+      auditEntryId: string;
+      fieldName: string;
+      oldValue: string | null;
+      newValue: string | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    PolicyFieldRule: {
+      id: Generated<string>;
+      auditPolicyId: string;
+      fieldName: string;
+      sensitivityMode: string;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    Company: {
+      id: Generated<string>;
+    }
+  }
+}
+
+export const getDB = createGetDB<Namespace>();
+
+export type DB<N extends keyof Namespace = keyof Namespace> = NamespaceDB<Namespace, N>;
+
+export type Transaction<K extends keyof Namespace | DB = keyof Namespace> =
+  NamespaceTransaction<Namespace, K>;
+
+type TableName = NamespaceTableName<Namespace>;
+export type Table<T extends TableName> = NamespaceTable<Namespace, T>;
+
+export type Insertable<T extends TableName> = NamespaceInsertable<Namespace, T>;
+export type Selectable<T extends TableName> = NamespaceSelectable<Namespace, T>;
+export type Updateable<T extends TableName> = NamespaceUpdateable<Namespace, T>;

package/src/modules/audit/index.ts

@@ -0,0 +1,2 @@
+export { defineModule, type DefineModuleParams } from "./module";
+export { permissions, own, all, aliases } from "./permissions";

package/src/modules/audit/lib/_db_deps.ts

@@ -0,0 +1,13 @@
+// Stub types for cross-module dependencies — used only for codegen.
+// At runtime, actual types are injected via defineModule() params.
+// TODO: Replace with SDK-level externalTypes support when available.
+import {
+  db,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export const company = db
+  .type("Company", {})
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);

package/src/modules/audit/lib/errors.generated.ts

@@ -0,0 +1,120 @@
+// @generated — do not edit
+import { createDomainError } from "@tailor-platform/erp-kit/module";
+
+// Note: Permission checks use the shared InsufficientPermissionError from defineCommand,
+// not a module-specific variant. See shared/errors.ts and shared/defineCommand.ts.
+
+export const UnauthorizedError = createDomainError(
+  "UnauthorizedError", "AUDIT_UNAUTHORIZED",
+  (identifier: string) => `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): ${identifier}`,
+);
+
+export const PolicyNotFoundError = createDomainError(
+  "PolicyNotFoundError", "AUDIT_POLICY_NOT_FOUND",
+  (identifier: string) => `Specified policy ID does not exist: ${identifier}`,
+);
+
+export const InvalidStateError = createDomainError(
+  "InvalidStateError", "AUDIT_INVALID_STATE",
+  (identifier: string) => `Policy is not in the required status for this operation: ${identifier}`,
+);
+
+export const IncompletePolicyError = createDomainError(
+  "IncompletePolicyError", "AUDIT_INCOMPLETE_POLICY",
+  (identifier: string) => `Policy is missing entity name or operation type: ${identifier}`,
+);
+
+export const EntityTypeNotRegisteredError = createDomainError(
+  "EntityTypeNotRegisteredError", "AUDIT_ENTITY_TYPE_NOT_REGISTERED",
+  (identifier: string) => `The target entity name does not reference a currently registered auditable entity: ${identifier}`,
+);
+
+export const ConflictingActivePolicyError = createDomainError(
+  "ConflictingActivePolicyError", "AUDIT_CONFLICTING_ACTIVE_POLICY",
+  (identifier: string) => `An ACTIVE policy already exists for the same (entityName, companyId, operationType); deactivate it first or use replaceAuditPolicy: ${identifier}`,
+);
+
+export const ScopeMismatchError = createDomainError(
+  "ScopeMismatchError", "AUDIT_SCOPE_MISMATCH",
+  (identifier: string) => `companyId provided for a global entity, or companyId null for a company-bound entity: ${identifier}`,
+);
+
+export const InvalidFieldNameError = createDomainError(
+  "InvalidFieldNameError", "AUDIT_INVALID_FIELD_NAME",
+  (identifier: string) => `A field name in field-level rules is empty or not in the entity's auditableFields: ${identifier}`,
+);
+
+export const DuplicateFieldNameError = createDomainError(
+  "DuplicateFieldNameError", "AUDIT_DUPLICATE_FIELD_NAME",
+  (identifier: string) => `The same field name appears more than once in field-level rules: ${identifier}`,
+);
+
+export const InvalidOperationTypeError = createDomainError(
+  "InvalidOperationTypeError", "AUDIT_INVALID_OPERATION_TYPE",
+  (identifier: string) => `operationType is missing or not one of CREATE, UPDATE, DELETE: ${identifier}`,
+);
+
+export const InvalidSensitivityModeError = createDomainError(
+  "InvalidSensitivityModeError", "AUDIT_INVALID_SENSITIVITY_MODE",
+  (identifier: string) => `sensitivityMode is not one of CAPTURE, MASK, HASH, EXCLUDE: ${identifier}`,
+);
+
+export const InvalidActorError = createDomainError(
+  "InvalidActorError", "AUDIT_INVALID_ACTOR",
+  (identifier: string) => `actorType is missing or not one of USER, SYSTEM, SERVICE; or actorId is empty: ${identifier}`,
+);
+
+export const MissingEntityIdError = createDomainError(
+  "MissingEntityIdError", "AUDIT_MISSING_ENTITY_ID",
+  (identifier: string) => `entityId is empty or not provided: ${identifier}`,
+);
+
+export const MissingEventIdError = createDomainError(
+  "MissingEventIdError", "AUDIT_MISSING_EVENT_ID",
+  (identifier: string) => `eventId is empty or not a valid UUID: ${identifier}`,
+);
+
+export const ValidationErrorError = createDomainError(
+  "ValidationErrorError", "AUDIT_VALIDATION_ERROR",
+  (identifier: string) => `CREATE or DELETE operation submitted with an empty changes array or with no auditable changes remaining after policy filtering; or correlationId provided but not a valid UUID: ${identifier}`,
+);
+
+export const InvalidEntityNameError = createDomainError(
+  "InvalidEntityNameError", "AUDIT_INVALID_ENTITY_NAME",
+  (identifier: string) => `entityName is empty or not provided: ${identifier}`,
+);
+
+export const DuplicateEntityNameError = createDomainError(
+  "DuplicateEntityNameError", "AUDIT_DUPLICATE_ENTITY_NAME",
+  (identifier: string) => `An entity with the same name is already registered: ${identifier}`,
+);
+
+export const InvalidEntityScopeError = createDomainError(
+  "InvalidEntityScopeError", "AUDIT_INVALID_ENTITY_SCOPE",
+  (identifier: string) => `entityScope is missing or not one of COMPANY_BOUND, GLOBAL: ${identifier}`,
+);
+
+export const InvalidAuditableFieldsError = createDomainError(
+  "InvalidAuditableFieldsError", "AUDIT_INVALID_AUDITABLE_FIELDS",
+  (identifier: string) => `auditableFields is empty, contains an empty field name, or contains a field with an ineligible fieldType (any type outside scalar, richtext, array, relation, file): ${identifier}`,
+);
+
+export const NoActivePolicyToReplaceError = createDomainError(
+  "NoActivePolicyToReplaceError", "AUDIT_NO_ACTIVE_POLICY_TO_REPLACE",
+  (identifier: string) => `No ACTIVE policy exists for the same entityName; use activateAuditPolicy instead: ${identifier}`,
+);
+
+export const TargetMismatchError = createDomainError(
+  "TargetMismatchError", "AUDIT_TARGET_MISMATCH",
+  (identifier: string) => `The existing ACTIVE policy does not match the replacement's companyId or operationType: ${identifier}`,
+);
+
+export const InvalidScopeError = createDomainError(
+  "InvalidScopeError", "AUDIT_INVALID_SCOPE",
+  (identifier: string) => `scope is not one of COMPANY, GLOBAL, or ALL: ${identifier}`,
+);
+
+export const AuditEntryNotFoundError = createDomainError(
+  "AuditEntryNotFoundError", "AUDIT_AUDIT_ENTRY_NOT_FOUND",
+  (identifier: string) => `Referenced audit entry does not exist: ${identifier}`,
+);