This is an internal working record, not an everyday instruction. It was written while the system was being rebuilt, for whoever maintains it. If you are here to do today's work, use the everyday documents instead: Procedures · Processes · Runbooks · The working day, step by step

Platform Audit, Transition, Correlation And Support Evidence — Policy, Sequence And Cutover¶

Status: SOURCE-RECONCILED POLICY AND DIAGRAM INPUT / DOCUMENTATION ONLY
Source baseline: qa/master@a5280b7cdc1c78b809ed6f1996ca31491b522146
Source authority: PLATFORM_AUDIT_TRANSITION_CORRELATION_SUPPORT_SOURCE_AUTHORITY.md
Rebuild packet: PLATFORM_AUDIT_TRANSITION_CORRELATION_SUPPORT_REBUILD_PACKET.md
Phase implementation: USER HOLD
Runtime/DB/log/audit/notification/Wiki/deployment effects: NONE

1. Policy Boundary¶

The following are separate and remain separately queryable.

Request diagnostic
Business transition audit
Operation notification
Domain evidence
Support timeline projection

No one surface is allowed to imply the semantics of another.

flowchart TB
    R[Request Diagnostic]
    T[Business Transition Audit]
    N[Operation Notification]
    D[Domain Evidence]
    S[Support Timeline]

    R -. request reference .-> S
    T --> S
    N -. notification reference .-> S
    D --> S

    R -. not authority .-> T
    N -. ACK is not approval .-> T
    S -. read-only projection .-> T

2. Policy Decision Matrix¶

ID	Concern	Current source fact	Recommended target	Status / blocker
`AUDPOL-010`	Evidence authority separation	multiple owners exist	preserve five distinct authorities	`RECOMMENDED`
`AUDPOL-020`	Required audit cohorts	selected Loader integration exists	Process owner chooses same-transaction cohorts	`OPEN — OWNER DECISION`
`AUDPOL-030`	Rejection audit	ordinary errors mainly request logs	retain only consequential rejections by policy	`OPEN`
`AUDPOL-040`	Recovery/effect classification	envelope validates R0–R5	owning process defines mapping	`RECOMMENDED / PER PROCESS`
`AUDPOL-050`	Correlation identity	request/page/process IDs fragmented	stable request/command/process/audit/attempt roles	`RECOMMENDED`
`AUDPOL-060`	Evidence registry	envelope type list exists	versioned registry plus owner resolvers	`OPEN — OWNER`
`AUDPOL-070`	Operation ACK	ACK/unack supported	notification read state only	`ACCEPTED SOURCE SEMANTIC`
`AUDPOL-080`	Notification failure	caller behavior varies	process-specific blocking/partial/non-blocking rule	`OPEN`
`AUDPOL-090`	Support access	current admin/log views are fragmented	strict tenant + semantic support capability + record predicate	`RECOMMENDED`
`AUDPOL-100`	Redaction	key-name mask and truncation exist	typed redaction classes and owner safe projection	`OPEN`
`AUDPOL-110`	Retention precedence	transition purge dates and archive rules differ	archive/hold/purge policy version with clear precedence	`OPEN — LEGAL/BUSINESS OWNER`
`AUDPOL-120`	Legal hold	fields exist; commands not established	separately authorized append-only hold/release	`OPEN`
`AUDPOL-130`	Tombstones	source references may expire	preserve audit reference and expose tombstone state	`RECOMMENDED`
`AUDPOL-140`	Time	UTC/Pacific/LA/domain times coexist	store UTC occurred/recorded plus source timestamp metadata	`RECOMMENDED`
`AUDPOL-150`	Audit correction	immutable store	append corrective/compensating transition	`RECOMMENDED`
`AUDPOL-160`	Loader writer	current source integration exists	verify DB/deployment and reconcile stale docs before expansion	`BLOCKING EVIDENCE`
`AUDPOL-170`	JSONL retention/access	channel-specific/partial cleanup	explicit channel inventory, retention, backup and support access	`OPEN`
`AUDPOL-180`	PHP/Next.js coexistence	no unified support timeline	read shadow then one read/writer authority per cohort	`RECOMMENDED`
`AUDPOL-190`	Raw payload	current transition store reference-only	keep raw payload out of transition/support projection	`RECOMMENDED`
`AUDPOL-200`	Support repair	current tools can lead to direct DB investigation	diagnostics link to owner recovery; no generic repair	`RECOMMENDED`

No RECOMMENDED entry activates Runtime work.

3. Current Request Diagnostic Sequence¶

sequenceDiagram
    actor User
    participant UI as PHP/Browser UI
    participant API as API or Legacy Endpoint
    participant DB as KJDatabase
    participant Biz as Business Tables
    participant Log as JSONL

    User->>UI: Submit action
    UI->>API: Request + optional trace/page headers
    API->>DB: Execute statements
    DB->>Biz: INSERT / UPDATE / DELETE
    Biz-->>DB: affected rows / error
    DB-->>API: result
    API-->>UI: response
    Note over DB,Log: Shutdown logging is diagnostic and non-fatal
    DB-->>Log: request ID, route/type/action, table/op/fingerprint, tx/error metadata

Important:

JSONL written
!= business command succeeded

JSONL missing
!= business command failed

The authoritative business row and transition/effect boundary must be reread.

4. Current Same-Transaction Transition Append¶

Selected Loader source demonstrates the intended local pattern.

sequenceDiagram
    actor Loader
    participant API as TMS API
    participant Tx as Caller DB Transaction
    participant Biz as T_TRANSLOAD / Related Rows
    participant Audit as TransitionAuditStore
    participant AT as Transition Tables

    Loader->>API: Start or Undo command
    API->>Tx: begin
    Tx->>Biz: conditional business mutation
    Biz-->>Tx: exact changed state
    API->>Audit: appendInCallerTransaction(envelope)
    Audit->>AT: audit root + entities + evidence
    alt all writes succeed
        API->>Tx: commit
        API-->>Loader: authoritative result
    else business or audit write fails
        API->>Tx: rollback
        API-->>Loader: failed / conflict
    end

Before treating this as current accepted behavior, verify the deployed source, exact API branch, installed tables and actual rows.

5. Audit Duplicate Sequence¶

sequenceDiagram
    participant App as Application Command
    participant Audit as TransitionAuditStore
    participant DB as Transition Audit DB

    App->>Audit: append audit UUID A + envelope hash H1
    Audit->>DB: INSERT
    alt first append
        DB-->>Audit: ID 100
        Audit-->>App: INSERTED
    else duplicate key
        Audit->>DB: SELECT existing ID/hash
        alt existing hash = H1
            Audit-->>App: IDEMPOTENT ID 100
        else existing hash != H1
            Audit-->>App: DUPLICATE_CONFLICT
        end
    end

The audit UUID must not be reused for a different transition or payload.

6. Operation Notification And ACK¶

sequenceDiagram
    participant Owner as Business/Automation Owner
    participant Event as Operation Event Service
    participant DB as T_OPERATION_EVENT
    actor User

    Owner->>Event: Create display notification
    Event->>DB: Insert event + safe display payload
    DB-->>Event: event UUID
    Event-->>User: bell/toast/history when policy allows
    User->>Event: ACK notification
    Event->>DB: conditional ACKED_AT / ACKED_BY
    Event-->>User: marked read
    Note over User,DB: ACK may later be cleared by Unack
    Note over Owner,DB: ACK is not business approval or transition completion

Prohibited interpretation:

ACKED_AT present
-> Approved / Confirmed / Completed

7. Notification Failure Alternatives¶

The current platform has no universal rule. A selected process must choose one explicit model.

7.1 Non-blocking notification¶

sequenceDiagram
    participant App
    participant DB as Business DB
    participant Event as Notification

    App->>DB: commit business state
    App->>Event: create notification
    alt notification succeeds
        Event-->>App: event ID
    else notification fails
        Event-->>App: non-blocking warning
        Note over App: business state remains committed
    end

7.2 Required child effect¶

sequenceDiagram
    participant App
    participant DB as Business DB
    participant Intent as Notification Intent
    participant Worker

    App->>DB: commit business state + durable notification intent
    Worker->>Intent: claim intent
    Worker->>Worker: create notification
    alt success
        Worker->>Intent: mark delivered/created
    else failure/unknown
        Worker->>Intent: retry/manual reconciliation state
    end

Do not use generic request logging as the durable notification intent.

8. Domain Evidence Resolution¶

sequenceDiagram
    actor Support
    participant Timeline as Support Timeline
    participant Registry as Evidence Resolver Registry
    participant Owner as Domain Owner
    participant DB as Domain Store

    Support->>Timeline: Open transition evidence
    Timeline->>Registry: Resolve type + namespaced reference
    Registry->>Owner: tenant-scoped safe query
    Owner->>DB: read authoritative record
    alt available and permitted
        DB-->>Owner: safe state
        Owner-->>Timeline: AVAILABLE projection
    else source missing/deleted
        Owner-->>Timeline: TOMBSTONED or MISSING
    else actor not permitted
        Owner-->>Timeline: REDACTED / safe denial
    else source unavailable
        Owner-->>Timeline: UNAVAILABLE
    end
    Timeline-->>Support: typed evidence state, no raw payload

A resolver does not recreate source evidence and does not modify the transition row.

9. Provider Or Physical Unknown Result¶

flowchart TD
    A[Request timed out or response missing] --> B[Read local business state]
    B --> C[Read transition audit/effect boundary]
    C --> D[Read provider attempt or physical evidence]
    D --> E{Boundary}
    E -- No commit/effect --> F[Correct input and retry owner command]
    E -- Local committed only --> G[Resume missing child effect]
    E -- Provider committed --> H[Link/reconcile existing provider result]
    E -- Physical committed --> I[Do not repeat physical action; reconcile system state]
    E -- Unknown --> J[Manual owner review; no blind replay]

This sequence applies to QBO, Gmail, Telegram, Scale, Yard and other external/physical effects through their own domain packets.

10. Current Correlation Chain¶

sequenceDiagram
    actor User
    participant Page as Browser Page
    participant API
    participant Command
    participant Process
    participant Audit
    participant Provider

    User->>Page: Open page
    Note over Page: pageViewId
    Page->>API: requestId + pageViewId
    API->>Command: commandRequestToken
    Command->>Process: processInstanceId + correlationId
    Process->>Audit: auditId + causationId
    Process->>Provider: providerAttemptId when applicable

Current source does not universally propagate every identifier. The diagram is the target correlation model; each migration cohort proves actual propagation.

11. Support Timeline Assembly¶

sequenceDiagram
    actor Support
    participant UI as React/PHP Support UI
    participant API as Support Query Adapter
    participant Biz as Business Owner
    participant Audit as Transition Audit
    participant Log as Request Diagnostics
    participant Event as Operation Event
    participant Evidence as Domain Resolvers

    Support->>UI: Search one tenant + record/process/request
    UI->>API: bounded query
    API->>Biz: read current authoritative state
    API->>Audit: transition timeline
    API->>Log: request diagnostic summaries
    API->>Event: notification summaries
    API->>Evidence: resolve domain evidence
    par source results
        Biz-->>API: current state
        Audit-->>API: transitions/references
        Log-->>API: request summaries or unavailable
        Event-->>API: notifications/ACK warning
        Evidence-->>API: available/tombstoned/redacted/unknown
    end
    API-->>UI: ordered safe timeline + partial-source dispositions

The UI must show source gaps. It must not silently omit a failed evidence source and claim a complete timeline.

12. Support Decision Tree¶

flowchart TD
    A[Identify tenant + environment + source revision] --> B[Identify strong record/process/request reference]
    B --> C[Read current authoritative business state]
    C --> D[Read transition audit if available]
    D --> E[Resolve domain evidence]
    E --> F[Read request diagnostic summary]
    F --> G{Do sources agree?}
    G -- Yes --> H[Classify effect boundary and next owner action]
    G -- No --> I[Mark CONFLICT; do not repair generically]
    H --> J{Safe to resume?}
    J -- Yes --> K[Use owning command only]
    J -- No --> L[Correction/compensation/manual review]

13. Time Ordering¶

flowchart LR
    O[occurredAt] --> N[Normalize to UTC]
    R[recordedAt] --> N
    P[provider/device capturedAt] --> N
    L[legacy local timestamp] --> C{timezone known?}
    C -- yes --> N
    C -- no --> U[Mark ordering uncertainty]
    N --> T[Timeline sort: occurred, recorded, stable source order]

Support UI must display the source timezone/normalization warning where ordering is uncertain.

14. Retention, Archive And Purge¶

stateDiagram-v2
    [*] --> Active
    Active --> LegalHold: approved hold
    Active --> ArchiveEligible: archive criteria met
    LegalHold --> Active: separately approved hold release
    LegalHold --> LegalHold: purge/archive blocked
    ArchiveEligible --> Archived: atomic root/entity/evidence move + readback
    Archived --> PurgeEligible: purgeAfter reached + no hold + policy allows
    PurgeEligible --> Purged: destructive approved batch
    Archived --> Restored: approved restore
    Restored --> Active

Required precedence:

Legal Hold
> Archive eligibility
> Purge eligibility

The exact relationship between current PURGE_AFTER, two-year archive eligibility and ten-year archive policy remains open.

15. Audit Correction And Compensation¶

sequenceDiagram
    participant Original as Original Transition
    actor Reviewer
    participant Owner as Process Owner
    participant Correct as Corrective Transition

    Reviewer->>Owner: Identify incorrect/partial historical result
    Owner->>Original: read immutable transition and evidence
    Owner->>Owner: apply accepted correction/compensation command
    Owner->>Correct: append new transition with causation/prior reference
    Correct-->>Reviewer: new state/effect/evidence
    Note over Original: Original transition remains unchanged

Do not update the original audit row to make history appear clean.

16. Current-To-Target Migration¶

sequenceDiagram
    participant Current as Current PHP/Logs
    participant Shadow as TypeScript Read Shadow
    participant Support as React/Next Support UI
    participant Writer as Selected Audit Writer
    participant DB as MySQL

    Current->>DB: current business/diagnostic writes
    Shadow->>DB: read-only correlation
    Shadow-->>Current: parity report
    Support->>Shadow: read-only support timeline
    Note over Writer: no writer activation until policy and DB evidence
    Writer->>DB: selected same-transaction audit cohort
    alt cohort accepted
        Current->>Writer: one authoritative transition path
    else rollback
        Writer-->>Current: disable cohort; retain audit history
    end

No PHP/TypeScript dual transition writer is allowed for the same command/cohort.

17. Parity Matrix¶

Concern	Current baseline	Target parity requirement	Required improvement	Evidence
Request ID	multiple similar generators	every selected adapter provides safe request ID	distinguish request from command/process IDs	request/route scenarios
Actor/subject	scalar helpers plus typed context	physical actor and effective subject preserved	support/audit access and redaction	impersonation scenarios
Mutation diagnostic	table/op/fingerprint/tx metadata	safe summary retained	no false before/after claim	JSONL fixtures/runtime
Transition schema	source/migration and selected writer	exact typed transition/entity/evidence	current environment verification	DB schema/readback
Transition idempotency	tenant+UUID+hash	same	stable command/audit ID contract	duplicate scenarios
Notification	tenant event + display/ACK	same notification semantics	stable transition/effect linkage where approved	event role/ACK scenarios
Domain evidence	separate owner tables	typed resolvers	tombstone/redaction states	owner fixtures
Support timeline	manual cross-source lookup	safe bounded projection	source-partial/conflict UI	support scenarios
Retention	mixed channel/audit/archive rules	approved precedence and hold	versioned policy/manifest	dry-run/restore
PHP/Next.js	PHP current tools	one read/writer authority per cohort	React support UX and TS contracts	cutover/rollback

18. Cutover Waves¶

Wave	Scope	Entry condition	Exit evidence	Rollback
`AUD-W0`	source/DB/log/caller inventory	documentation accepted	environment matrix	none, read-only
`AUD-W1`	TypeScript read shadow	access/redaction defined	parity report	disable shadow
`AUD-W2`	React/Next read-only support UI	selected support role/cohort	role/tenant/partial-source acceptance	return to current tools
`AUD-W3`	Loader writer reconciliation	current table/deployment verified	exact Start/Undo audit readback	disable writer path, retain rows
`AUD-W4`	one new local DB-only transition	Process owner accepts failure semantics	commit/rollback/idempotency tests	route/cohort revert
`AUD-W5`	notification linkage	ACK semantics protected	event/audit reference parity	remove linkage, keep events
`AUD-W6`	evidence resolvers	owner safe projections accepted	tenant/redaction/tombstone tests	disable resolver
`AUD-W7`	retention/hold/archive	legal/business policy approved	dry-run/restore/hold evidence	stop claims, preserve rows
`AUD-W8`	support reader cutover	stabilization	target-role observation	current reader restore
`AUD-W9`	caller-zero/PostgreSQL later	accepted parity	static/runtime caller-zero	failback plan

19. Rollback Rules¶

Never delete transition rows to roll back an application change.
Never unack a notification to simulate business rollback.
Never edit JSONL to hide a failed request.
Never overwrite source evidence references after deletion; expose tombstone state.
Stop new writer/read cohorts first and preserve in-flight identifiers.
Reconcile provider/physical unknown results before retry.
A support UI rollback removes the projection only; it does not modify source data.
Retention/purge rollback is a separate destructive-data procedure and cannot be inferred from code rollback.

20. Acceptance Scenarios¶

ID	Scenario	Expected result
`AUD-SCN-010`	committed local command + request JSONL	business row and transition/effect prove state; JSONL is diagnostic only
`AUD-SCN-020`	JSONL write fails	command result follows owner transaction; diagnostic gap shown
`AUD-SCN-030`	audit required and append fails	selected business transaction rolls back
`AUD-SCN-040`	audit optional/unavailable	process-specific partial/unavailable result, no false audit claim
`AUD-SCN-050`	duplicate audit same hash	idempotent existing ID
`AUD-SCN-060`	duplicate audit different hash	conflict
`AUD-SCN-070`	Operation Event ACK/unack	read state changes; approval does not
`AUD-SCN-080`	evidence source deleted	audit remains; source shown tombstoned
`AUD-SCN-090`	foreign-tenant evidence reference	safe denial/no existence disclosure
`AUD-SCN-100`	provider committed/local unknown	reconcile provider result; no replay
`AUD-SCN-110`	physical work/system timeout	physical evidence first; no repeated action
`AUD-SCN-120`	mixed timezone evidence	normalized ordering or uncertainty warning
`AUD-SCN-130`	one timeline source unavailable	partial result with source disposition
`AUD-SCN-140`	legal hold	archive/purge blocked
`AUD-SCN-150`	correction	new transition appended; original unchanged
`AUD-SCN-160`	PHP/Next read shadow	same safe entries/dispositions for selected cohort
`AUD-SCN-170`	writer rollback	business/audit rows remain consistent; no dual writer

21. Current Documentation Disposition¶

Source reconciliation:
DETAILED INPUT

Policy:
RECOMMENDATIONS + OPEN OWNER DECISIONS

Sequence/state/cutover diagrams:
DOCUMENTED

Runtime or DB activation:
NONE

Current Wiki publication:
NONE

Phase status:
USER HOLD

M4:
NOT ESTABLISHED

---¶

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