Status
FinKore Core 2.0.4 stable.
Purpose
This document defines how an audit event may describe domain-relevant field changes.
Requirements
- AUDIT-CHANGE-001 — A Change MUST identify the changed field or domain path.
- AUDIT-CHANGE-002 — A Change SHOULD record prior and resulting values when both may be safely retained.
- AUDIT-CHANGE-003 — A Change MUST distinguish an absent value from an explicit null value when the underlying domain distinguishes them.
- AUDIT-CHANGE-004 — Values MUST use stable domain representations, not localized display strings. Changes to Money values MUST preserve the semantics defined by Money.
- AUDIT-CHANGE-005 — A Change set MUST NOT claim a field changed when its domain value remained equal.
- AUDIT-CHANGE-006 — Sensitive values MUST follow Redaction.
- AUDIT-CHANGE-007 — An event MAY omit field changes when its event type fully expresses the occurrence or disclosure is prohibited.
- AUDIT-CHANGE-008 — Unless a Change explicitly declares a supported domain value type, its prior and resulting values MUST be compared as ordinary JSON values. Equality is recursive and type-sensitive: null equals only null; a Boolean MUST NOT equal a number; strings compare by their exact value; numbers compare by their JSON numeric value; arrays compare in declared order; and objects compare the same member names and recursively equal member values without assigning meaning to object member order. Absence remains distinct from every supplied JSON value, including null. A value outside the JSON data model is not a supported portable Audit Change value and MUST be rejected with
FINKORE_AUDIT_INVALID_EVENT. - AUDIT-CHANGE-009 — A portable Audit Change whose values carry Money semantics MUST explicitly declare
valueTypeasMONEY; Money semantics MUST NOT be inferred from an ordinary JSON object merely because it hasamountandcurrencymembers. Each supplied non-null, non-absent value of aMONEYChange MUST be a valid normative Money serialization. Two supplied Money values are equal only when their currencies are the same and their exact decimal amounts are numerically equal under MONEY-REPRESENTATION-005 and MONEY-COMPARISON-002; differing valid currencies or amounts are different domain values. Null and absence retain the distinctions required by AUDIT-CHANGE-003. An unknownvalueTypeor malformed declared Money value MUST make the Audit Event invalid withFINKORE_AUDIT_INVALID_EVENT.
Invariants
Recorded Changes must be consistent with the Audit Event's declared domain meaning.
Audit owns validation of its Change representation and the decision whether a Change falsely claims equality. Money owns Money parsing and numeric semantics; Audit invokes those semantics only after the Change explicitly declares Money. The Audit equality check is not the finkore.money.compare operation: two valid Money values with different currencies are different Change values, so their difference is recordable without reporting a currency-mismatch error.
The complete member-set comparison in AUDIT-CHANGE-008 includes names such as __proto__ and constructor, at every nesting level. They are ordinary JSON members. Copying, retaining, or observing a Change must not drop those members or reinterpret them as runtime instructions. Objects differing only in one such member can be different values; equal objects remain subject to unchanged-value rejection under AUDIT-CHANGE-005. This clarifies existing preservation and equality obligations rather than adding a reserved-name policy.
Example
At native boundaries, AUDIT-CHANGE-008 rejects cyclic containers and unsupported native numeric values with FINKORE_AUDIT_INVALID_EVENT. Shared acyclic references are not cycles. Every accepted numeric value must remain exact and independent of later caller mutation under AUDIT-APPEND-001. These checks apply to history import and candidate validation, with the existing priority in AUDIT-ERROR-004. Rejection cannot partially commit history or escape as a host recursion/stack failure.
The following JSON is illustrative and non-normative; it does not prescribe serialized member names or a domain-path syntax.
{
"field": "state",
"before": "DRAFT",
"after": "SUBMITTED"
}
Invalid Examples
- Recording a secret in clear text when policy requires redaction.
- Using translated labels as canonical before and after values.
Open Questions
- Should domain paths use a standardized portable syntax?
- How should large or structured values be summarized without losing evidentiary meaning?
Comparison declaration
AUDIT-CHANGE-008 defines ordinary JSON comparison for AUDIT-CHANGE-005. AUDIT-CHANGE-009 provides an opt-in Money declaration; omitting valueType preserves ordinary JSON semantics under SPEC-COMPATIBILITY-010. A Money-shaped object alone does not declare Money.
