Status
FinKore Core 2.0.4 stable.
Purpose
This document defines attribution of domain events to Actors. An Actor may be a human, service, scheduled process, system, integration, or another identified subject.
Requirements
- AUDIT-ACTOR-001 — An actor reference MUST include a stable identifier.
- AUDIT-ACTOR-007 — An actor reference SHOULD include an actor type.
- AUDIT-ACTOR-008 — Later changes to an Actor profile MUST NOT change the Actor identity recorded by a committed Audit Event.
- AUDIT-ACTOR-002 — Actor identifiers MUST be treated as opaque.
- AUDIT-ACTOR-003 — Display names MAY be captured as historical metadata but MUST NOT replace stable identity.
- AUDIT-ACTOR-004 — If an unknown Actor is represented, that representation MUST distinguish unknown attribution from a known Actor and MUST NOT invent an identity. Audit Events also permits omission when no Actor is known.
- AUDIT-ACTOR-005 — Delegation or acting-on-behalf-of relationships SHOULD preserve both the initiating and represented subjects when domain-relevant.
- AUDIT-ACTOR-006 — Actor data MUST follow applicable redaction rules. In Core 2.0, actor redaction is limited to optional actor context:
actor.displayNameandactor.metadata. A redacted actor representation MUST preserve actoridand any supplied actortype, MUST replace each redacted optional actor member with a redacted representation distinguishable from original absence under AUDIT-REDACTION-002, and MUST leave an omitted actor member omitted. A redaction policy MUST identify these actor targets using exactlyactor.displayNameoractor.metadata. Core 2.0 does not permit redacting actor identity or actor type because those fields carry audit attribution semantics. - AUDIT-ACTOR-009 — When an Audit Event supplies an
actormember, it MUST be a JSON object containingidas a non-empty string. IftypeordisplayNameis supplied, including when it is supplied as explicit null, that member MUST be a non-empty string. A supplied actor that violates this portable shape MUST be rejected withFINKORE_AUDIT_ACTOR_INVALID; omitting the event'sactormember remains the representation for unknown attribution permitted by AUDIT-ACTOR-004. - AUDIT-ACTOR-010 —
actor.metadataMAY be omitted or supplied as any JSON value, including explicit null. An implementation MUST preserve whetheractor.metadatawas supplied, and MUST preserve its JSON value until an applicable redaction rule replaces it. Omitted metadata, supplied null metadata, and redacted metadata MUST remain distinguishable. A supplied non-JSON metadata value MUST be rejected withFINKORE_AUDIT_ACTOR_INVALID.
Invariants
Later changes to an Actor's profile must not change the identity recorded by a committed Audit Event.
Supplying actor.metadata: null records present metadata whose value is null; it does not mean that the member was omitted. A policy targeting actor.metadata redacts either a null or non-null supplied value, while an omitted member remains omitted under AUDIT-ACTOR-006.
Preserving a JSON value under AUDIT-ACTOR-010 includes preserving every supplied object member name and its value recursively. Names such as __proto__ and constructor are ordinary JSON names, not implementation instructions or exceptions to preservation. Their presence alone does not make metadata invalid, and copying or observing metadata cannot remove or reinterpret them. This clarifies the existing JSON boundary without permitting non-JSON runtime values or changing redaction semantics.
Native value boundaries
The non-JSON rejection in AUDIT-ACTOR-010 also applies at native API boundaries. Cyclic maps or arrays cannot denote a JSON value and use FINKORE_AUDIT_ACTOR_INVALID, rather than a runtime recursion failure. Shared acyclic subobjects can denote JSON and are not cycles. An accepted native number must retain an exact, independent value: a mutable numeric reference cannot change committed metadata under AUDIT-APPEND-001. Which native numeric classes are supported belongs to the language API; unsupported values use the same actor error, without coercion to a string or lossy number. When non-actor content is also invalid, AUDIT-ERROR-004 still selects the non-actor error first.
Metadata presence
AUDIT-ACTOR-010 permits explicit null metadata and preserves its presence. This does not relax the nonempty-string rules for supplied id, type, or displayName; explicit null is invalid for those string members.
Example
The following JSON is illustrative and non-normative; it does not prescribe serialized member names.
{
"type": "service",
"id": "settlement-importer"
}
Invalid Examples
- Using a mutable display name as the sole actor identity.
- Attributing an automated event to a human who did not initiate it.
Open Questions
- Which explicit representation should denote an unknown actor?
Non-Goals
This document does not define authentication, authorization, user directories, or role assignment.
