Universal Audit Log Specification

Document Version: 2.1 Date: 25 March 2026 Status: Proposed for implementation Scope: Constellation platform and all active/future apps

This page is the entry point for the Universal Audit Log spec. The original document was a 957-line single file; it has been split into the deep-linkable pages below. Sections 1 through 5 are reproduced inline because they're short and frame everything else (purpose, decision summary, current state, goals, non-goals).

Spec table of contents

§	Section	Page
1–5	Purpose / Decisions / State / Goals / Non-Goals	(below)
6	Core Architecture	Architecture
7	Canonical Audit Model	Architecture
8	Index Strategy	Architecture
9	GDPR / Privacy — PII in Audit Entries	Privacy & redaction
10	Shared Package API	Shared package API
11	Tamper-Evident Chain Design	Tamper-evident chain
12	Query and UI Model	Query & access control
13	Audit Access Control	Query & access control
14	Operational Monitoring	Operations
15	Export and Reporting	Operations
16	Access Logging Extension	Operations
17	SIEM Integration	Operations
18	Redaction Framework	Privacy & redaction
19–25	Open Mercato Reference / Usage Rules / Rollout / Testing / Cleanup / Spelling / Final	Usage & rollout

---

Revision History

Version	Date	Summary
1.0	25 March 2026	Initial specification. Core architecture, schema, shared API, rollout plan.
2.0	25 March 2026	Multi-agent review incorporation. Adds partitioning, retention, GDPR pseudonymisation, tamper-evident chain design, keyset pagination, granular access control, operational monitoring, export/reporting, SIEM integration, redaction framework, developer ergonomics, index strategy, immutability hardening, IP handling, enforcement mechanisms. Restructured rollout phases.
2.1	25 March 2026	Architecture alignment review. Retention policy aligned with Constellation_Architecture_Spec_v1 (SaaS = indefinite). GDPR pseudonymisation replaced with actor-identity-retained position + future ADR path. Keyset pagination changed to dual-support migration. CI enforcement scoped to mutating tools only with integration tests as merge gate.

---

1. Purpose

This document defines the concrete implementation approach for a universal audit-log mechanism across Constellation applications.

It turns the already-approved architectural direction into an executable design:

• audit is a cross-cutting platform concern
• audit writes are transactional and immutable
• audit capture happens in the tool layer (and other defined capture points)
• every module uses the same storage, query, and UI conventions
• audit data is compliant by design with GDPR, SOC 2, ISO 27001, and ITAR retention requirements

This spec also records which ideas should be adopted from Open Mercato and which should not.

---

2. Decision Summary

2.1 Primary Decision

Constellation SHALL implement universal audit logging as a shared platform capability, not as a separate application.

2.2 Package Boundaries

• @constellation-platform/db
  • owns the canonical audit schema contract
  • owns low-level audit writes and audit queries
  • remains ORM-agnostic and transaction-oriented
• @constellation-platform/audit
  • owns higher-level audit helpers and conventions
  • provides wrappers for critical/security-sensitive audit behaviour
  • provides reusable utilities for diff generation, redaction, and audit metadata normalisation
• apps/*
  • call shared audit APIs from their tool layer
  • do not define their own audit storage models
  • may expose module-local views and adapters over the shared audit APIs

2.3 Why This Is Not Another App

A separate app would be wrong for the primary write path because audit rows must commit in the same transaction as the domain mutation they describe. That requires the audit write to happen inside the same database transaction opened by the module tool.

Separate UI surfaces are acceptable. Separate write ownership is not.

---

3. Current State in Constellation

Constellation already has the correct foundation:

• shared audit schema and helpers in packages/platform/db
• immutable audit table in audit.audit_entries
• auditCritical() in packages/platform/audit
• audit query tool in Directory
• project-tracker audit UI and API stubs awaiting platform integration

Relevant current files:

• packages/platform/db/src/audit.ts
• packages/platform/db/migrations/001_audit_entries.sql
• packages/platform/audit/src/audit-critical.ts
• apps/directory/src/server/tools/audit.tools.ts
• apps/project-tracker/src/app/api/audit/route.ts
• apps/project-tracker/src/lib/entity-audit.ts
• apps/project-tracker/src/components/audit/AuditTrail.tsx

The largest gap is not storage. The gap is consistent capture and usage across apps, retention and compliance, and developer ergonomics.

---

4. Goals

1. Every state-changing business operation produces exactly one canonical audit entry.
2. Audit entries are written atomically with the state mutation they describe.
3. Audit is reusable across all modules without per-app schema duplication.
4. Audit history can be queried by tenant, actor, resource, organisation, and related resource.
5. Security-sensitive actions can trigger guaranteed durable downstream processing.
6. UI consumers can render a per-resource version history from shared APIs.
7. The design supports defence-tier tamper-evident chaining with a concrete implementation path.
8. Audit data minimises PII surface (IP truncation, context_json PII prohibition) while retaining actor identity for investigations per GDPR Article 17(3) exemptions.
9. Failed and denied operations are captured alongside successes.
10. Operational health of the audit subsystem is continuously monitored.

---

5. Non-Goals

1. This spec does not create a standalone audit microservice or app.
2. This spec does not replace domain events with audit events.
3. This spec does not require all read-access events to be logged immediately; access logging is defined as a separate extension path.
4. This spec does not introduce a generic CRUD framework for Constellation.
5. This spec does not require undo/redo support.

Open Mercato's undo/redo-capable action log is informative, but Constellation should not inherit that as a platform requirement.

---