Tasks, events, and audit

Tasks, events, and audit answer different management questions. A Task tells the operator whether long-running work completed. An event helps the interface and automation react to a state change. An audit record tells a security reviewer who or what attempted a consequential action. None of them alone proves the customer outcome.

The resource owner decides whether to retry or roll back, the operator reconciles Task state with the owning runtime, and the security owner defines audit retention and export. Keep these records connected with stable resource, request, Task, and operation IDs.

Tasks represent durable long-running work such as builds, deployments, migrations, imports, provisioning, and updates. Follow status, progress, logs, error code, and retry/cancel availability. Do not start duplicates merely because a browser disconnected.

Events update live UI state and trigger supported operational workflows. Consumers must revalidate authorization and tolerate reconnect or replay boundaries.

Audit records attribute security- and configuration-relevant actions to users or system actors. User blocking or deletion does not remove historical attribution. Export to SIEM when independent retention or correlation is required.

Audit details should identify the action and resource without storing secrets, raw credentials, private keys, prompts, or model output.

Task lifecycle

Typical task states distinguish queued, running, waiting, succeeded, failed, cancelled, and interrupted work. The available states and actions depend on the operation. Progress is evidence from the owning worker or daemon, not a browser animation.

Record the Task ID before leaving a long-running operation. Reloading the page must reconnect to durable state rather than creating a second operation. If a command response is lost, inspect both the Task and the owner before retrying.

Retry, cancel, and force cancel

Retry only when the task contract marks the operation retryable or reconciliation proves the previous attempt reached a terminal state. Cancel requests are cooperative when the owner supports cancellation. Force Cancel can stop Opfield from waiting on an abandoned operation, but it does not justify assuming the underlying runtime action never occurred.

After cancellation or interruption, refresh the resource from its owner and resolve any operation marker before starting another mutation.

Events and realtime state

Realtime events reduce UI latency but are not the only source of truth. Clients must tolerate disconnect, replay, duplicate delivery, and an event arriving before a refreshed snapshot. After reconnect, load the authoritative snapshot and merge newer events by stable resource identity.

Events that trigger automation must recheck current authorization, ownership, entitlement, and lifecycle state. Historical permission at event creation does not authorize a later mutation.

Audit interpretation

Audit records identify actor, action, resource, timestamp, outcome, and relevant request context. System and automation actors must remain distinguishable from human sessions and impersonation. Blocking or deleting a user preserves historical attribution.

Audit is not a debug log. Use operational logs and Tasks for implementation detail, and use audit for security and configuration accountability. Export to independently controlled SIEM storage when retention or correlation must survive an Opfield incident.

“Immutable attribution” means account lifecycle changes do not rewrite the historical actor attached to an audit record. It does not mean the local audit database is WORM storage or cryptographically tamper-proof against a person who controls the Opfield host, PostgreSQL, backups, or encryption keys. Those administrators remain inside the trust boundary.

If policy requires evidence that survives control-plane compromise, export audit records continuously to an independently administered SIEM or WORM-capable destination, restrict deletion there, synchronize time, and monitor export gaps. Keep the external retention policy and access review separate from Opfield administration.

Investigation checklist

1. Identify the resource and customer-visible effect.
2. Find the initiating audit record and request ID.
3. Find the durable Task or operation.
4. Compare desired state with current owner state.
5. Review bounded operational logs.
6. Record retry, cancellation, rollback, and final verification.

Success and failure interpretation

A succeeded Task means the owning workflow reached its documented terminal state. It does not necessarily prove DNS propagation, external client access, application-level correctness, delivered email, processed webhook data, or restored business data. Add an independent verification appropriate to the resource.

A failed or interrupted Task does not prove that no side effect occurred. The owner may have created a container, written a file, changed a provider, or completed a runtime action before acknowledgement was lost. Read current owner state and operation history before cleanup or retry.

Waiting states should identify the dependency or required input. If a Task remains waiting without a clear owner, preserve its IDs and escalate rather than using Force Cancel as routine cleanup.

Housekeeping and retention

Housekeeping removes data that Opfield no longer needs, daily at 02:00 by default. Configure it under Settings > Features > Housekeeping: housekeeping:view shows the configuration, statistics, and run history, housekeeping:run starts a run, and housekeeping:configure changes categories and the schedule. Each category can be turned off. The Audit Log category keeps 90 days by default; export audit records to a SIEM when policy requires longer retention.

Two categories added in 2.11 are on by default:

Category	What it removes
Operation History	Finished Docker container Tasks after one day. After the retention period, 90 days by default: finished builds with their logs, empty build batches, finished Compose, Workload Availability, and hosting operations, and Git source webhook deliveries. Each resource keeps its 10 most recent runs, and records that something still uses—a build artifact, an Availability placement, a snapshot, or a hosted Node’s origin—are kept
Expired OAuth Grants	Expired OAuth authorization codes and access and refresh tokens, and OAuth clients that have had no grant for 90 days. A refresh token is kept until it expires, so that its reuse is still detected

Other categories cover nginx logs, dismissed alerts, notification deliveries, structured logs, ClickHouse system tables, orphaned AI artifacts, the internal registry, orphaned volumes, retired system PKI keys, ACME challenge files, and old Opfield images.

Retention and external evidence

Audit rows are not lost when Opfield stops. On shutdown, Opfield writes the rows still in flight before it closes the database connection. When the database has already gone away, as at a host shutdown where every container stops at once, a row that cannot be written is appended to a spool file on the application’s data volume (/var/lib/gateway/audit-spool) and stored at the next start with its original ID, so a replay that stops halfway never adds a row twice; SIEM export picks up the rows it stores. New installations also stop PostgreSQL with a smart shutdown, which waits up to 75 seconds for Opfield to close its connections; existing installations get this when their PostgreSQL container is next recreated.

Keep audit records according to security and compliance policy, and export to independently controlled SIEM storage when the evidence must survive an Opfield outage or administrator compromise. Operational Task logs may have different retention and sensitivity. Do not expand audit payloads with secrets or raw request bodies merely to make debugging easier.

When supplying evidence to support or another team, include timestamps, stable IDs, terminal state, sanitized error details, and the independent verification result. Remove credentials, internal topology, customer data, prompts, model output, and unrestricted logs.