Skip to content

Canonical Audit And Transition Contract Correction — 2026-08-08

1. Correction Summary

The following older shorthand is not an accurate current contract:

KJDatabase records before/after business-row snapshots.
Transition Audit has no writer.

Use the following current interpretation instead:

KJDatabase
= request and mutation diagnostic metadata
= statement/table/affected-row/transaction/error correlation
!= general immutable before/after business-row snapshot authority

Transition Audit
= append-only reference-only business-transition evidence family
= selected Loader transition writer exists in source
!= universal process coverage
!= verified current-environment activation without DB/runtime evidence

This correction controls interpretation until the large canonical owner files are updated through a consumer-safe bounded edit.

2. Current KJDatabase Diagnostic Contract

2.1 What it records

Current KJDatabase and request logging can record bounded diagnostic facts such as:

  • request ID and route/type/action context;
  • SQL statement fingerprint or statement family;
  • affected table names;
  • insert ID where available;
  • affected row count;
  • transaction used/committed/rolled back indicators;
  • elapsed time;
  • exception or statement error metadata;
  • tables touched during a request.

2.2 What it does not establish

It is not the general authority for:

  • exact business before state;
  • exact business after state;
  • Process transition name;
  • approval;
  • compensation;
  • physical completion;
  • provider acceptance;
  • user-facing recovery state.

A diagnostic log can help correlate a request. The owning business row, transition evidence, ledger, file, provider, or physical record remains authoritative for the business result.

2.3 Support rule

KJ diagnostic found
-> identify request/table/transaction context
-> reread authoritative business records
-> reread transition/domain/provider evidence
-> classify committed / missing / partial / unknown

Do not use a statement fingerprint or affected-row count as a substitute for business-state readback.

3. Business Transition Audit Contract

3.1 Table family

T_PROCESS_TRANSITION_AUDIT
T_PROCESS_TRANSITION_ENTITY
T_PROCESS_TRANSITION_EVIDENCE

The main row stores a bounded transition envelope. Child rows store typed references. The contract intentionally avoids copying unrestricted business payloads, document contents, credentials, or provider bodies.

3.2 Main semantics

A transition envelope can identify:

  • tenant and optional portable tenant identity;
  • actor and effective subject;
  • request, process instance, correlation, and causation IDs;
  • Process contract and transition name;
  • before/after state references;
  • result and failure reference;
  • recovery class;
  • effect boundary;
  • reason/approval references;
  • retention and legal-hold metadata;
  • typed entity/evidence references.

Allowed result classes include:

SUCCEEDED
REJECTED
FAILED
PARTIAL
COMPENSATION_REQUIRED

Allowed effect-boundary classes include:

NONE
DATABASE_COMMITTED
EXTERNAL_PENDING
EXTERNAL_COMMITTED
PHYSICAL_COMMITTED
COMPENSATION_REQUIRED

3.3 Append semantics

append()
= audit store owns its transaction

appendInCallerTransaction()
= business caller owns the transaction
= business mutation and transition evidence may share one commit boundary

Idempotency is by tenant plus audit UUID and canonical safe-envelope hash.

same UUID + same hash
-> existing idempotent result

same UUID + different hash
-> duplicate conflict

4. Current Writer Status

Current source contains a selected Loader transition integration that writes evidence for bounded Loader transitions such as Start and Undo under the Inbound Planning process family.

Therefore:

Transition framework source: PRESENT
Selected Loader writer source: PRESENT
Universal Process coverage: NO

The following remain unverified in this documentation-only work:

  • whether the three tables exist in each current environment;
  • current table version and indexes;
  • whether the selected writer is exercised in the current deployed Runtime;
  • current row count and retention state;
  • whether every selected transition commits its audit row in the same transaction;
  • cleanup/archive worker state.

Use:

SOURCE PRESENT / ENVIRONMENT EVIDENCE REQUIRED

Do not use either extreme:

no writer exists

or:

all business transitions are audited

5. Operation Event Boundary

T_OPERATION_EVENT is a notification ledger.

Event created
= notification/action-needed record exists

ACKED_AT / ACKED_BY
= a user marked the notification read

ACK does not mean:

  • approved;
  • confirmed;
  • completed;
  • reversed;
  • compensated;
  • provider-delivered;
  • physically performed.

Business completion must be read from the owning Process state and evidence.

6. Domain Evidence Boundary

Evidence owner Proves Does not prove alone
T_STAFF_TIME_EVENT Clock, Break, Job activity Planner/Load/Clock-Out workflow completion
T_SCALE_TICKET_EVENT Scale correction/void/reversal lineage Purchase/Outbound completion
T_INVENTORY_LOT_LEDGER Inventory balance movement/reversal Source Order or shipment completion
T_FILE + object/link checks metadata/object/link/readability checkpoints approval or mail delivery
Mail/provider state provider-specific send/receive result local business completion
Deployment metadata release/config identity user acceptance or Process completion

A Support Timeline may correlate these references but must remain read-only and must not become a second business authority.

7. Canonical Wording To Use

Architecture summary

KJDatabase provides tenant-scoped database access and bounded request/mutation diagnostic metadata. It is not the general before/after business-state audit authority.

Schema summary

The transition-audit table family is a reference-only append model. Selected source writers exist, but environment installation, current activation, rows, retention, and universal Process coverage require separate evidence.

Support summary

Request diagnostics identify the request and mutation context. Business rows and typed transition/domain/provider evidence establish the business result.

8. Evidence Package

Use evidence ID:

RBR-AUDIT-002 — Current Audit And Transition Environment Inventory

Read-only scope:

  • exact environment and DB identity;
  • table existence, columns, indexes, and constraints;
  • selected writer caller inventory;
  • current transition rows by Process/transition/effect boundary;
  • duplicate/hash-conflict behavior from existing evidence or a separately authorized fixture;
  • retention/legal-hold fields;
  • notification ACK distinction;
  • KJ diagnostic shape and redaction;
  • correlation from request ID to business row and transition evidence.

This document does not authorize that package to run.

9. Target Reconstruction Rule

The target system keeps separate contracts:

RequestDiagnostic
BusinessTransitionAudit
DomainEvidenceReference
ProviderAttemptReference
OperationNotification
SupportTimelineProjection

React/Next.js support views may display these together, but no UI or adapter may collapse them into one mutable audit record.

10. Maintenance

Update this correction when:

  • KJDatabase capture behavior changes;
  • transition tables or writer set changes;
  • current environment evidence is accepted;
  • retention/legal-hold policy is approved;
  • canonical Architecture/Schema summaries are corrected;
  • a successor document is accepted and all consumers migrate.

---

Source: docs/reconstruction/CANONICAL_AUDIT_AND_TRANSITION_CONTRACT_CORRECTION_2026-08-08.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.