chore: sync GovOPlaN module split state

docs/AUDIT_TRACE_CONTEXT.md

@@ -0,0 +1,82 @@
+# Audit Trace Context
+
+Operational audit entries should let an administrator answer four questions:
+
+- who initiated the operation
+- what object was changed
+- which lifecycle request or run carried the change
+- how the entry connects to surrounding request, installer, or worker logs
+
+The actor, tenant, scope, action, object type, and object ID remain first-class
+`audit_log` columns. Additional operational context belongs in `details`.
+
+## Standard Fields
+
+Use these fields for admin, module lifecycle, installer, and worker operations:
+
+- `module_id`: module affected by the operation, when a single module is the
+  target.
+- `request_id`: queued installer/admin request identifier.
+- `run_id`: installer/worker run identifier.
+- `outcome`: compact state such as `planned`, `queued`, `applied`,
+  `cancelled`, `failed`, or `completed`.
+- `_trace.correlation_id`: request or workflow correlation ID.
+- `_trace.causation_id`: event, run, or operation that caused this audit entry.
+
+Bulk operations may also include concise arrays such as `activated`,
+`deactivated`, `mounted`, `planned_modules`, or sanitized `items`.
+
+## Access Provenance
+
+Access-sensitive events should include a compact provenance array when the
+decision depends on semantic access state. Use `details.access_provenance` with
+items shaped like `AccessDecisionProvenance.to_dict()` from
+`govoplan_core.core.access`.
+
+Expected provenance kinds:
+
+- `identity`
+- `account`
+- `tenant_membership`
+- `organization_unit`
+- `function`
+- `group`
+- `role`
+- `right`
+- `delegation`
+- `policy`
+- `system_actor`
+
+Delegation and acting-in-place events must show both the real actor account and
+the represented/delegated account or function assignment. Feature modules
+should obtain this shape through `access.explanation` instead of inspecting
+access tables directly.
+
+## Redaction
+
+Audit detail payloads must not contain credentials, tokens, raw cookies,
+authorization headers, private keys, message bodies, uploaded file content, or
+other secret material. Use stable IDs, vault references, or package identifiers
+instead.
+
+The compatibility helper in core, `audit_operation_context`, keeps the standard
+fields compact and applies the shared audit redaction pass to additional detail
+values. Feature modules should follow the same shape even when they later write
+through a dedicated audit sink capability.
+
+## Module Lifecycle Events
+
+Module install, uninstall, enable, disable, rollback, and package-catalog
+acceptance events should include:
+
+- `object_type`: `module_install_plan`, `module_install_request`,
+  `module_state`, or another stable lifecycle object type.
+- `object_id`: module ID for single-module actions, otherwise `global` or the
+  request/run ID.
+- `details.module_id`, `details.request_id`, or `details.run_id` when present.
+- `details.outcome` with the lifecycle result.
+- `details._trace` when the operation originated from a request or queued
+  daemon action.
+
+This keeps admin UI timelines, audit exports, and rollback diagnostics aligned
+without coupling modules to the audit table implementation.