Skip to content

Platform Audit, Transition, Correlation And Support Evidence — Source Authority

1. Authority Decision

CTC currently has several evidence surfaces. They answer different questions and must not be merged into one generic audit log.

Request/Mutation Diagnostic
= what request, statement family, table and transport outcome were observed?

Business Transition Audit
= which accepted/rejected/failed business transition occurred, for which process and state?

Operation Event
= which notification or action-needed message was created and whether a user acknowledged reading it?

Domain Evidence
= which business record, staff event, ledger row, scale event, file, mail item or provider attempt proves one part of the result?

Support Timeline
= a read-only projection that correlates references from the above owners without becoming a new writer or business authority

1.1 Required invariants

KJDatabase mutation metadata
!= business transition

HTTP 200 / request log
!= transaction committed

Operation Event created
!= business work completed

Operation Event ACK
!= business approval
!= transition confirmation

Page viewed
!= command executed

File row exists
!= object readable
!= business link complete

Provider request sent
!= provider accepted
!= local provider reference saved

Audit row exists
!= source evidence remains readable forever

Support timeline entry
!= source authority

1.2 No generic audit Process ID

Audit, telemetry and support are shared platform foundations. They are not one L3 business process. Each business process owns its transition names and business completion semantics; the platform owns safe correlation, persistence, reference resolution, retention controls and support projection.

2. Current Evidence Families

Family Current source Current purpose Not authoritative for
Request/SQL diagnostic app/utils/KJDatabase.php, JsonlLogger.php, API logging request timing, route/type/action, SQL fingerprint, mutation metadata, tables touched, transaction indicator, exception diagnostics business state transition or approval
API/page telemetry app/shared/api/logging.php, page_usage_logger.php, page_report_helper.php request/page correlation, latency, error and usage sampling business completion, authorization or acceptance
Business transition contract TenantExecutionContext, ProcessContext, AuditEnvelope typed tenant/actor/process/state/effect/recovery envelope persistence by itself
Business transition store TransitionAuditStore.php, three transition tables append-only reference-only transition record and typed entity/evidence links raw payload, business-row replacement or notification
Loader transition integration loader_transition_evidence.php, TMS transload callers selected Loader Start/Undo transition evidence all CTC processes or universal coverage
Operation notification T_OPERATION_EVENT, operation_event_helper.php tenant notification, route, display policy, user preference, ACK/unack approval, durable process transition or recovery completion
Staff activity T_STAFF_TIME_EVENT and owners Clock, Break, Job and workforce activity evidence loader/planner/business completion by itself
Scale lineage T_SCALE_TICKET_EVENT and Scale owner reweigh/correction/void/reversal lineage order receipt/shipment completion
Inventory lineage T_INVENTORY_LOT_LEDGER, lot/allocation owners inventory movement, adjustment, void/reversal provenance source order or shipment completion
File evidence T_FILE, storage object and link owners metadata, object/link/readability checkpoints document approval or email/provider completion
Mail evidence T_MAIL_MESSAGE, T_MAIL_REQUEST_ITEM, Gmail owners inbound mail and request work-item lineage; provider IDs where owned local transaction or recipient delivery unless explicitly stored
Provider evidence QBO/Gmail/Telegram/domain-specific state provider request/result/reconciliation local business state unless the owning process says so
Control/deployment metadata Control Tower registry, release SHA/config references deployment/tenant/config identity business transition or operator acceptance

3. Current Business Transition Contract

3.1 Tenant and actor prerequisite

ProcessContext requires a STRICT TenantExecutionContext. A compatibility-only tenant context cannot create an accepted process context.

A safe transition context contains:

local/global tenant identity and provenance
actor and optional subject
request ID and access mode
process contract ID/version
process instance ID
optional parent process instance
correlation ID
optional causation ID
source type/name
1–25 typed entity references
maximum recovery class

A child process preserves tenant and correlation identity, records the parent process instance and requires a causation reference.

3.2 Audit envelope

The current envelope is reference-only and contains:

audit UUID
process context
transition name
occurred timestamp
before/after state references
reason reference
optional approval reference
result
optional failure reference
recovery class
effect boundary
1–50 evidence references

Allowed result states:

SUCCEEDED
REJECTED
FAILED
PARTIAL
COMPENSATION_REQUIRED

Allowed effect boundaries:

NONE
DATABASE_COMMITTED
EXTERNAL_PENDING
EXTERNAL_COMMITTED
PHYSICAL_COMMITTED
COMPENSATION_REQUIRED

Recovery classes are R0 through R5. The envelope validates result, failure stage, effect boundary, process maximum recovery, approval and evidence consistency.

3.3 Evidence-reference types

Current envelope mapping:

Evidence type Required relation Meaning
KJ_MUTATION MUTATION request-level mutation diagnostic reference
OPERATION_EVENT NOTIFICATION_ONLY notification reference only
STAFF_EVENT STAFF_ACTIVITY workforce activity evidence
FILE FILE_EVIDENCE file/object/link evidence reference
MAIL_ITEM MAIL_WORK_ITEM mail/request-work reference
EXTERNAL_ATTEMPT EXTERNAL_ATTEMPT provider attempt/result owner reference
BUSINESS_RECORD BUSINESS_STATE authoritative business-row reference

R4 and R5 require explicit approval and at least one non-notification evidence reference. An Operation Event alone cannot satisfy high-impact transition evidence.

4. Current Transition Audit Persistence

4.1 Table family

T_PROCESS_TRANSITION_AUDIT
T_PROCESS_TRANSITION_ENTITY
T_PROCESS_TRANSITION_EVIDENCE

The main table stores bounded scalar values. Child tables store typed references. There is no generic JSON/text/blob payload column.

Important main fields include:

  • tenant and optional global tenant UUID;
  • schema/context versions;
  • process contract and instance/parent IDs;
  • correlation and causation IDs;
  • source, entrypoint and request ID;
  • actor and optional subject;
  • transition, before/after state, reason and approval;
  • result/failure/recovery/effect boundary;
  • retention class, purge date and legal-hold reference.

4.2 Append semantics

TransitionAuditStore supports two transaction modes.

append()
= audit store owns its transaction

appendInCallerTransaction()
= business caller already owns a transaction
= audit append neither commits nor rolls back it

Same-transaction append is the only current way to guarantee:

business state write
+ transition audit write
= one local commit boundary

Duplicate behavior:

same tenant + audit UUID + same canonical safe-envelope hash
-> IDEMPOTENT existing result

same tenant + audit UUID + different hash
-> TRANSITION_AUDIT_DUPLICATE_CONFLICT

4.3 Retention fields

Current code derives:

STANDARD
-> occurredAt + 400 days

EXTENDED
-> occurredAt + 2,555 days

R4, R5, external-committed, physical-committed and compensation transitions use EXTENDED.

These are engineering defaults. They are not a legal, statutory or customer-specific retention guarantee.

4.4 Current activation discrepancy

Several older documents and migration comments state that the transition store has no active business caller. Current source contains a concrete Loader transition integration:

CtcLoaderTransitionEvidence
-> strict tenant context
-> PROC-TMS-INBOUND-PLANNING / 0.5.0
-> START_TRANSLOADING or Undo transition
-> BUSINESS_RECORD + KJ_MUTATION evidence
-> appendInCallerTransaction()

The integration is referenced by current TMS transload source. Therefore the accurate source-level statement is:

Transition-audit framework: present
Selected Loader transition writer: present in source
Universal process adoption: absent
Current DB table presence/row volume: not verified in this session
Production writer activation: not verified in this session
Cleanup worker: not established

Do not use the older no active caller statement as current Runtime truth without reconciling the exact deployed source and DB.

5. KJDatabase Request And Mutation Diagnostics

5.1 Current captured mutation shape

Current KJDatabase detects simple SQL mutation families and records:

operation: INSERT / REPLACE / UPDATE / DELETE
table
statement fingerprint
insert ID when available
affected row count
before policy
tables touched
transaction used / committed / rolled back
request ID
transport and exception metadata

5.2 Important correction

Current source does not capture a general before/after business-row snapshot.

captureBeforeSnapshot()
-> { policy: NOT_CAPTURED }

Therefore documentation or support UI must not claim that KJDatabase provides complete before/after DML evidence. It provides bounded request and mutation metadata.

5.3 Scope limits

  • Mutation detection is SQL-shape based and may not represent every stored procedure, multi-statement, driver-specific or indirect write.
  • The log can identify a table and statement fingerprint, not the business meaning of the change.
  • A transaction indicator does not identify which business state transition was accepted.
  • Logging is limited to selected request paths such as controller/login/API surfaces.
  • Logging failure is intentionally non-fatal and cannot prove that a business write did or did not commit.
  • Redaction is primarily key-name based and truncated; unexpected sensitive fields can still require separate review.
  • JSONL is file-based, rotated by channel/date conventions, and not an append-only relational business ledger.

5.4 Table checksum tokens

Dirty-table handling writes a changing token under temp/<TABLE> after a successful commit or non-transaction write. The token is used for frontend synchronization; it is not a content checksum, audit record or proof of a specific row mutation.

6. Request, Page And API Correlation

6.1 Current request identifiers

Several current request families create or accept request IDs:

API v2 apiRequestId()
legacy endpoint endpointRequestId()
legacy controller controllerRequestId()
KJDatabase request ID
browser _trace.reqId
X-Request-Id

They use similar safe-character and length rules but are not yet one universal request-context owner.

6.2 Page and API correlation

Browser page telemetry can supply:

X-CTC-Page
X-CTC-Page-View

API logging can then record:

  • page key;
  • page-view ID;
  • request ID;
  • actor label;
  • bounded input summary;
  • API method/route/module;
  • duration and HTTP status.

This supports operational troubleshooting but does not prove a business result.

6.3 Session correlation

Current logs may include a truncated hash of the PHP session ID. It is a diagnostic correlation value, not a public session identifier or authentication token.

6.4 Process correlation

ProcessContext adds a separate hierarchy:

processInstanceId
parentProcessInstanceId
correlationId
causationId
requestId through tenant context

The target must define how one request, command, process instance, child process and provider attempt relate. Reusing one arbitrary request ID for every concept is not sufficient.

7. API And Page Telemetry

7.1 API request logging

The API logger records non-GET requests, errors and selected GET diagnostics. Successful GET retention can be sampled; errors and slow requests can be retained.

Current redaction:

  • removes _trace;
  • masks keys containing password/token/authorization/API-key/code/state patterns;
  • limits field/value count and length for page/API input summaries;
  • truncates serialized query/body snapshots.

This is operational hygiene, not a proof that every payload is safe for broad support access.

7.2 Page usage

Page usage records page/client/day counts and duration summaries. It may store a maximum-duration sample with timestamp and session hash.

Page usage
= navigation/performance evidence

Page usage
!= authorization evidence
!= command evidence
!= business-state evidence

The current page-log cleanup removes one page-log family after 30 days. This does not define retention for all JSONL channels.

8. Operation Events

8.1 Current purpose

T_OPERATION_EVENT owns display-oriented operational notifications.

Current attributes include:

  • tenant-scoped UUID;
  • event type and severity;
  • source type and numeric source ID;
  • display payload JSON;
  • ACK timestamp and user;
  • lifecycle timestamps.

Role/config policy controls visibility, toast, bell, history, ACK, sound, browser behavior and creation.

8.2 ACK semantics

Current ACK is conditional and role-aware. Unack is also supported.

ACKED_AT / ACKED_BY
= this notification was marked read/acknowledged in the notification UI

It is not:

business approval
supervisor approval
process completion
provider reconciliation
physical work verification

Because unack clears ACK fields, it cannot be used as immutable approval evidence.

8.3 Current correlation limit

The table has source type/ID and payload links but no universal process-instance, correlation, causation or request-ID columns. A transition audit may reference an Operation Event as NOTIFICATION_ONLY; the notification does not become the transition owner.

8.4 Notification failure policy

Current callers create Operation Events from several modules and transaction positions. The source family does not establish one universal policy for:

  • whether business work fails when notification creation fails;
  • whether notification creation is inside or after the business transaction;
  • how duplicate notification requests are identified;
  • how missed notifications are reconciled.

Each process must document its own current boundary until a shared effect contract is approved.

9. Domain Evidence Catalog

9.1 Business record

Use the exact tenant-scoped record and authoritative state/version. A request or audit reference never replaces exact business-row readback.

9.2 Staff event

Staff events prove workforce activity such as Clock, Break, Job Start/End. They do not automatically prove the related Planner, Loader, Delivery or Billing workflow completed.

9.3 Scale event

T_SCALE_TICKET_EVENT is immutable correction/void/reversal lineage for Scale. It does not prove Purchase receipt, Outbound close or Billing completion.

9.4 Inventory ledger

T_INVENTORY_LOT_LEDGER proves inventory movement or reversal according to its owner. It does not prove the source order, review or shipment is complete.

9.5 File evidence

A complete file checkpoint can require:

object created
+ metadata row
+ business relation
+ object readable
+ intended links complete

An audit stores references, not file bytes or signed URLs.

9.6 Mail evidence

Mail evidence can include message/thread/request-item identity. A queued or locally recorded item does not prove recipient delivery unless the mail owner stores and reconciles that result.

9.7 External attempt

Provider evidence remains domain-owned. The reference should identify a durable attempt/result record, not copy raw provider payload or credential-bearing headers into the transition store.

10. Time Semantics

Current evidence surfaces use mixed time policies:

Surface Current time tendency
Transition audit UTC DATETIME(6) for occurred/recorded/purge
JSONL default US/Pacific timestamp unless caller supplies a timezone
Page usage America/Los_Angeles
Business records mixed DB/server/business timezone conventions
Provider/device events owner-specific timestamps

The target support timeline must retain:

occurredAt
recordedAt
source timezone or UTC normalization status
provider/device capturedAt when available

Sorting only by local display time can misorder cross-system evidence.

11. Retention, Archive, Purge And Legal Hold

11.1 Current transition fields

Transition rows include retention class, purge date and legal-hold fields. Current code derives engineering purge dates but does not establish an enabled cleanup worker in this source review.

11.2 Archive-runbook interaction

The current archive Runbook classifies the transition family as future archive scope and proposes moving the root plus entity/evidence children after two years when no legal hold exists.

This creates a policy question:

Archive eligibility date
!= purge-after date

The accepted future policy must specify:

  • whether archive preserves the original purge date;
  • which store is checked for legal hold;
  • whether purge can run only after both current and archive stores are reconciled;
  • how evidence tombstones are displayed;
  • how restored audit rows preserve IDs, UUIDs and hashes;
  • who authorizes legal hold, release and destructive purge.

Current 400-day, 2,555-day, two-year and ten-year values are engineering/archive inputs. Do not present them as legal or contractual policy without owner approval.

12. Support Timeline Current-State Gap

Current support work must manually correlate:

business row
request ID / JSONL
page and API telemetry
operation event
staff/scale/inventory/file/mail/provider evidence
transition audit when present
source SHA / environment

There is no current universal support timeline read model that safely resolves all of these with one authorization/redaction contract.

A support operator can otherwise make unsafe assumptions such as:

  • treating a mutation fingerprint as proof of committed business state;
  • treating ACK as approval;
  • retrying a provider action because only the local row was visible;
  • exposing foreign-tenant record existence;
  • copying raw payloads or secrets into an incident note;
  • ordering events incorrectly across timezones.

13. Current Factual Discrepancies To Reconcile

Document/source statement Current source observation Required disposition
KJDatabase records before/after DML snapshots current captureBeforeSnapshot() returns NOT_CAPTURED; mutation metadata is retained correct canonical schema wording after source/DB owner review
Transition store has no active writer caller Loader transition evidence is integrated in current source verify current DB/deployment activation and update canonical current-state docs
Transition migration comment says inactive writer current source includes selected caller retain migration history, add current activation note rather than silently rewriting history
ADR states cleanup initially disabled no universal cleanup worker was found in this review keep disabled/unknown until exact Runtime evidence
Archive Runbook says process audit future scope transition tables may exist locally; current archive script scope remains separate verify each environment before archive/purge planning

Do not resolve these by changing Runtime or DB in a documentation-only wave.

14. Current Source Gaps

The inspected source does not establish complete answers for:

  • transition table presence and row volume in every environment;
  • exact deployed Loader transition writer behavior;
  • which business transitions must fail if audit append fails;
  • comprehensive process adoption;
  • universal request/correlation propagation;
  • operation-event create transaction policy across all callers;
  • durable external-attempt registry;
  • support role and redaction policy;
  • legal/contractual retention;
  • legal-hold command and approval process;
  • all JSONL channel retention/rotation/backup;
  • evidence resolution after source archival/deletion;
  • current Production support-query performance;
  • PostgreSQL partition/retention implementation.

These remain OPEN POLICY or RUNTIME EVIDENCE REQUIRED.

15. Reconstruction Boundary

The target platform must preserve separate authorities:

RequestTrace
BusinessTransitionAudit
OperationNotification
DomainEvidence
SupportTimelineProjection

It must not:

  • copy raw request/provider/file payloads into the transition ledger;
  • make audit persistence the business-state owner;
  • make Operation Event ACK an approval;
  • make React/Next.js route logs the source of truth;
  • require support staff to query raw cross-tenant tables;
  • convert all current logs into one unbounded JSON event store;
  • activate broad audit writers while phase work is held.

The detailed target contract is in PLATFORM_AUDIT_TRANSITION_CORRELATION_SUPPORT_REBUILD_PACKET.md.

---

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