Audit logs

Status: partially implemented. Operational logs exist via actorLog. A formal audit-event schema, queryable audit store, retention policy, and admin UI are target state.

Today's reality

Logs from actors flow through actorLog (projects/matrix-3/packages/system-platform/src/actorLog.ts). These are operational logs — debug, info, error — not formally-shaped audit events.

actorLog writes to the bus as event topics that anyone subscribed can read. The Host Service supervisor records logs to <host-home>/logs/runtimes/<runtime-id>.log. There is one log file per runtime.

For ops:

# Read recent log lines from the gateway runtime on the platform Host
tail -f /var/lib/hivecast/host-home/logs/runtimes/system-gateway-http.log

This works but it is not "an audit log." It mixes information levels, has no query, no retention policy, no integrity protection, no export.

What an audit log needs

A real audit log needs:

• Structured events. Each event has an event type, actor, principal, target, outcome, timestamp.
• Tamper-resistance. Append-only, hash-chained, optionally signed.
• Queryable store. "Show me all auth.hostLink.revoke events for principal X in the last 30 days."
• Retention policy. Configurable per-event-type retention.
• Export. Operators ship audit logs to SIEM tools.
• Admin UI. A reviewable view in the platform-admin dashboard.

None of these exist as first-class platform features today. Operators pursuing compliance must layer their own.

Events that should be audit-logged

Today these go through actorLog (mixed with operational logs):

Event	Source actor / op
auth.session.create (login)	system.auth
auth.session.revoke (logout)	system.auth
auth.principal.ensure (first login of new principal)	system.auth
auth.namespace.claim	system.auth
auth.hostLink.create (Device pair)	system.auth
auth.hostLink.revoke (Device disconnect)	system.auth
auth.hostLink.credentials.refresh	system.auth
runtimes.start / stop / reload	system.runtimes, host.control
system.devices register/heartbeat	system.devices

A target audit-event schema would standardize all of these as { type, ts, actor, principalId, target, outcome, metadata }.

What actorLog does today

actorLog is a thin wrapper that emits log lines on the bus and to local files. It is the standard way for actors to log per Rule 9 (no console.log).

A subscriber to log topics can read live; the local file is the durable record. The format is human-readable JSON, not a strict schema.

Loose ends

• No WORKSTREAMS/audit/ directory yet.
• The system-observability package has scaffolding for tracing but nothing audit-specific.
• The ARCHITECTURE-OBSERVABILITY-PIPELINE-V2.md document discusses the broader observability story but does not dive into audit specifically.

Retention today

Per-runtime log files rotate based on the supervisor's settings (default: size-based rotation, no time bound). Operators wanting long retention export to external systems.

There is no GDPR/CCPA "delete principal X's audit trail" path. Target state.

What an operator can do today

• Tail the relevant runtime log.
• Grep for principal id, host link id, etc.
• Capture and archive log files manually.
• For the auth flows specifically, inspect <host-home>/state/auth-state.json for current state of principals, Spaces, Host Links, sessions revoked. The state file is not an audit log — it is current state — but it answers most "is this account in the expected state" questions.

Compliance posture

The platform is not currently fit for SOC 2 / HIPAA / PCI compliance audit, primarily because of the audit-log gap. Compliance-track work is a target state requirement; not on the launch path.

See also

• Authentication — events that should be audit-logged.
• Authorization — events that should be audit-logged.
• Reference: Operational runbooks — log inspection procedures.
• ARCHITECTURE/ARCHITECTURE-OBSERVABILITY-PIPELINE-V2.md — broader observability design.

Source: projects/matrix-3/packages/system-platform/src/actorLog.ts. No audit-specific implementation exists.