Platform Audit, Transition, Correlation And Support Evidence — Rebuild Packet¶

Status: DETAILED REBUILD INPUT / DOCUMENTATION ONLY
Source authority: PLATFORM_AUDIT_TRANSITION_CORRELATION_SUPPORT_SOURCE_AUTHORITY.md
Current source baseline: qa/master@a5280b7cdc1c78b809ed6f1996ca31491b522146
Related identity/access packet: PLATFORM_FOUNDATION_RECONSTRUCTION_INDEX.md
Target Runtime: React + Next.js adapters, framework-independent TypeScript applications, MySQL first, optional workers for asynchronous evidence maintenance, PostgreSQL later
Phase implementation: USER HOLD
Current Runtime implementation, DB migration, writer activation, cleanup, Wiki publication and deployment: NOT AUTHORIZED

1. Capability Outcome¶

The platform must let an authorized operator or support user answer the following without guessing from raw source code or replaying an action.

What request was made?
Who physically initiated it and which subject/tenant were effective?
Which business process and transition was intended?
Which state was accepted, rejected, failed, partial or compensation-required?
Which local, external or physical effect boundary was reached?
Which authoritative records and evidence prove that boundary?
What can be safely retried, resumed, corrected or escalated?
Which evidence is unavailable, expired, tombstoned, redacted or conflicting?

The target also preserves enough evidence to rebuild process behavior during React + Next.js migration without treating logs as business truth.

1.1 Non-goals¶

This packet does not authorize:

a universal event-sourcing rewrite;
one generic JSON audit table;
storing raw SQL parameters, request bodies, provider payloads, file contents or secrets in transition audit;
turning notification ACK into approval;
logging every read forever;
broad transition-writer activation;
legal/compliance retention claims;
support users changing business state from the diagnostics view;
replacing domain-specific Scale, Inventory, Staff, File, Mail or Provider evidence;
Runtime, schema, retention-worker or deployment changes while Phase implementation is held.

2. Target Authority Model¶

flowchart LR
    UI[React UI / Current PHP UI]
    WEB[Next.js or PHP Request Adapter]
    APP[Application Command / Query]
    DB[(Business Database)]
    TA[(Transition Audit)]
    OE[(Operation Notification)]
    DE[(Domain Evidence)]
    LOG[(Request Diagnostics)]
    SUP[Support Timeline Projection]

    UI --> WEB
    WEB --> APP
    WEB --> LOG
    APP --> DB
    APP --> TA
    APP --> OE
    APP --> DE
    LOG -. reference .-> SUP
    TA --> SUP
    OE --> SUP
    DE --> SUP
    DB --> SUP

Concern	Target owner	Failure semantics
Business row/state	owning application/repository	command-specific transaction result
Business transition	transition-audit application	same transaction when required by policy; otherwise explicit unavailable evidence
Request diagnostics	request/observability adapter	non-authoritative and normally non-fatal
Notification	operation-notification application	process-specific child effect; never approval
Domain evidence	owning domain	owner-specific transaction/retention/recovery
Support timeline	read-only support query	does not modify source records or infer missing state
Legal hold/retention	approved retention owner	separately authorized, audited and reversible where possible

3. Core TypeScript Contracts¶

The names below are target semantic contracts, not an instruction to create these exact files immediately.

3.1 `RequestTraceContext`¶

type RequestTraceContext = {
  schemaVersion: "request-trace/v1";
  requestId: string;
  pageViewId?: string;
  sessionCorrelationId?: string;
  entrypoint: "WEB" | "API" | "JOB" | "INTEGRATION" | "SYSTEM";
  sourceName: string;
  sourceRevision?: string;
  deploymentId?: string;
  startedAt: string; // UTC
  actorRef?: PrincipalRef;
  subjectRef?: PrincipalRef;
  tenantRef?: TenantRef;
};

Rules:

requestId identifies a transport/request attempt, not a durable business command.
pageViewId groups browser navigation and child API calls.
a retry receives a new request ID unless the transport explicitly reuses it; business idempotency uses a separate command/request token.
logs may retain a redacted safe projection of this context.

3.2 `ProcessExecutionContext`¶

type ProcessExecutionContext = {
  schemaVersion: "process-context/v1";
  tenantContext: TenantExecutionContext;
  processContractId: string;
  processContractVersion: string;
  processInstanceId: string;
  parentProcessInstanceId?: string;
  correlationId: string;
  causationId?: string;
  commandRequestToken?: string;
  sourceType: "WEB" | "API" | "JOB" | "INTEGRATION" | "SYSTEM";
  sourceName: string;
  entityReferences: EntityReference[];
  maximumRecoveryClass: RecoveryClass;
};

Rules:

one process instance represents one durable business execution lineage, not every HTTP request;
child processes preserve correlation, set parent/causation and own their result;
commandRequestToken is capability-specific and must not be replaced by the HTTP request ID;
all consequential writes require strict tenant context.

3.3 `BusinessTransitionAudit`¶

type BusinessTransitionAudit = {
  schemaVersion: "audit-envelope/v1";
  auditId: string;
  processContext: ProcessExecutionContext;
  transitionName: string;
  occurredAt: string;
  recordedAt?: string;
  beforeStateRef?: StateReference;
  afterStateRef?: StateReference;
  reasonRef: ReasonReference;
  approvalRef?: ApprovalReference;
  result: TransitionResult;
  failureRef?: FailureReference;
  recoveryClass: RecoveryClass;
  effectBoundary: EffectBoundary;
  evidenceReferences: EvidenceReference[];
};

The transition row is immutable. A correction is another transition that references the prior audit or process instance; it is not an update to the historical row.

3.4 `EvidenceReference`¶

type EvidenceReference = {
  type:
    | "BUSINESS_RECORD"
    | "KJ_MUTATION"
    | "OPERATION_EVENT"
    | "STAFF_EVENT"
    | "SCALE_EVENT"
    | "INVENTORY_LEDGER"
    | "FILE"
    | "MAIL_ITEM"
    | "EXTERNAL_ATTEMPT"
    | "DEPLOYMENT_RELEASE"
    | "APPROVAL"
    | "INCIDENT";
  reference: string;
  relation: string;
  ownerModule: string;
  tenantRef: TenantRef;
  expectedAvailability?: "DURABLE" | "RETENTION_BOUND" | "EPHEMERAL";
};

Evidence references are stable namespaced identifiers. They never contain a secret, raw payload, signed URL, SQL text or document body.

3.5 `SupportTimelineEntry`¶

type SupportTimelineEntry = {
  entryId: string;
  sourceType:
    | "BUSINESS_STATE"
    | "TRANSITION_AUDIT"
    | "REQUEST_DIAGNOSTIC"
    | "NOTIFICATION"
    | "DOMAIN_EVIDENCE"
    | "DEPLOYMENT";
  occurredAt: string;
  recordedAt?: string;
  tenantRef: TenantRef;
  actorRef?: PrincipalRef;
  subjectRef?: PrincipalRef;
  processRef?: ProcessRef;
  requestId?: string;
  correlationId?: string;
  causationId?: string;
  entityRefs: EntityReference[];
  summaryCode: string;
  summaryText: string;
  result?: TransitionResult;
  effectBoundary?: EffectBoundary;
  evidenceState:
    | "AVAILABLE"
    | "MISSING"
    | "TOMBSTONED"
    | "EXPIRED"
    | "REDACTED"
    | "UNAVAILABLE"
    | "CONFLICT";
  sourceLink?: SafeInternalLink;
  permittedActions: SupportAction[];
};

The summary text is a safe projection from typed codes and current source state. It does not copy arbitrary log messages into a user-facing screen.

4. Transition Results, Effects And Recovery¶

4.1 Result values¶

SUCCEEDED
REJECTED
FAILED
PARTIAL
COMPENSATION_REQUIRED

Definitions:

Result	Meaning
`SUCCEEDED`	the transition reached its declared after-state/effect boundary
`REJECTED`	command was denied before an accepted state change
`FAILED`	transition did not reach the declared target; exact effect boundary determines recovery
`PARTIAL`	one or more child/local/external boundaries succeeded while another did not
`COMPENSATION_REQUIRED`	an irreversible or already committed effect requires a separately approved compensation path

4.2 Effect boundaries¶

Boundary	Meaning	Safe generic retry?
`NONE`	no accepted local/external/physical effect	command-specific, often yes after correction
`DATABASE_COMMITTED`	local business state committed	no blind replay; exact reread first
`EXTERNAL_PENDING`	local request/intent exists; provider result unresolved	no; reconcile attempt first
`EXTERNAL_COMMITTED`	provider accepted/committed effect	never replay without provider reconciliation
`PHYSICAL_COMMITTED`	physical work occurred or was accepted	never repeat from software timeout alone
`COMPENSATION_REQUIRED`	prior committed effect needs explicit compensating action	no ordinary retry

4.3 Recovery classes¶

The current R0–R5 contract remains the baseline. Each process packet must define the maximum class and transition-specific mapping. A shared platform helper must not infer recovery solely from HTTP status.

4.4 Failure stages¶

PRECOMMIT
TRANSACTION
POSTCOMMIT_EXTERNAL
PHYSICAL
COMPENSATION

Support messages must identify the stage without disclosing internal stack traces or credentials.

5. Business Transition Writer Policy¶

5.1 Same-transaction required cases¶

A transition audit should be appended in the same local transaction when all are true:

the transition changes an authoritative business state;
the process contract requires durable lineage for correction/reversal/recovery;
the transition store is installed and selected for that capability;
the audit envelope can be constructed without copying unsafe payloads;
the Process owner accepts audit failure semantics.

For an activated same-transaction cohort:

business mutation fails
-> transition audit is rolled back

audit insert fails before commit
-> business mutation is rolled back

The target must not silently commit the business state and claim the transition is fully evidenced when a required same-transaction audit failed.

5.2 Optional/non-blocking cases¶

Diagnostic traces, page usage and ordinary notifications normally remain non-blocking. If a process requires a notification to proceed, that requirement must be an explicit child process/effect state, not an implicit dependency on generic logging.

5.3 Rejections¶

Not every invalid field response requires durable transition audit. The policy must define which consequential rejections are retained, such as:

denied compensation or reversal;
foreign-tenant record attempt;
stale/concurrent state conflict;
repeated provider/physical replay attempt;
privileged action denied during impersonation.

High-volume ordinary validation errors can remain request diagnostics unless the Process owner defines otherwise.

5.4 Current Loader cohort¶

The current Loader integration is the first source-level cohort to reconcile. Before expanding it, verify:

exact current table presence and migration state;
current route/write transaction ordering;
Start/Undo transition names and state references;
actor versus subject under impersonation;
audit failure behavior;
duplicate/retry behavior;
DB rows and support queries;
rollback and release identity.

No other process inherits approval merely because Loader uses the framework.

6. Evidence Type Registry¶

6.1 Registry ownership¶

The platform owns the registry syntax and safe-resolution contract. Domain owners own whether a reference is authoritative and how it is read.

Each definition contains:

evidenceType
ownerModule
referenceNamespace
relation allowlist
resolver query
safe fields
record tenant predicate
availability/retention class
redaction classification
source link policy
archive/tombstone behavior
deprecation/replacement

6.2 Proposed definitions¶

Type	Example reference	Owner	Safe support projection
`BUSINESS_RECORD`	`T_TRANSLOAD:123` or future `transload:<uuid>`	process/module repository	ID, safe state, version, timestamps, tenant
`KJ_MUTATION`	`request:SVR_...`	observability	request ID, table/op/fingerprint/result; no parameters
`OPERATION_EVENT`	`operation-event:<uuid>`	notification	type, severity, read state, safe route; ACK warning
`STAFF_EVENT`	`staff-event:<id/uuid>`	workforce	event type/time/source relation
`SCALE_EVENT`	`scale-event:<id/uuid>`	Scale	stage, event type, reason code, safe before/after summary
`INVENTORY_LEDGER`	`inventory-ledger:<id/uuid>`	WMS	movement/reversal type, quantity/weight/UOM, source relation
`FILE`	`file:<uuid>`	file application	metadata/link/readability state; no signed URL by default
`MAIL_ITEM`	`mail-item:<id/uuid>`	mail application	message/request state and safe provider reference
`EXTERNAL_ATTEMPT`	`qbo-attempt:<uuid>`	provider application	attempt/result/reconciliation state; no raw provider payload
`DEPLOYMENT_RELEASE`	`release:<sha-or-release-id>`	deployment/control plane	environment, release ID/SHA, applied state
`APPROVAL`	`approval:<uuid>`	approved decision owner	type, approver reference, occurred time, scope
`INCIDENT`	`incident:<id>`	support/operations	safe incident status and linkage

6.3 Evidence resolution states¶

AVAILABLE
MISSING
TOMBSTONED
EXPIRED
REDACTED
UNAVAILABLE
CONFLICT

A missing source record does not invalidate the historical transition row. The support projection explains that the reference is unresolved and preserves the namespaced ID.

7. Correlation Model¶

7.1 Identifier roles¶

Identifier	Scope	Reuse rule
`requestId`	one transport/server request	new for ordinary retry
`pageViewId`	one browser page view and child API set	stable during one view
`sessionCorrelationId`	one authenticated session diagnostic lineage	never exposed as auth token
`commandRequestToken`	one durable idempotent business command	same token + same payload returns same result
`processInstanceId`	one process execution lineage	stable across transport retries/resume
`parentProcessInstanceId`	composite/child hierarchy	immutable
`correlationId`	cross-command/process business correlation	stable for selected journey/job
`causationId`	immediate cause	points to command/process/event that caused child work
`auditId`	one transition envelope	immutable and tenant-idempotent
`providerAttemptId`	one provider attempt	new for each intentional attempt, linked to same effect intent
`deploymentReleaseId/SHA`	code/config version	immutable reference

7.2 Propagation rules¶

Browser page
-> pageViewId
-> API requestId
-> commandRequestToken
-> processInstanceId/correlationId
-> auditId
-> optional providerAttemptId

A new HTTP request can resume the same command/process. A new provider attempt can belong to the same effect intent. The support timeline must display these distinctions.

7.3 Namespaces¶

References use bounded namespaces, for example:

request:
page-view:
command:
process:
audit:
operation-event:
staff-event:
scale-event:
inventory-ledger:
file:
mail-item:
qbo-attempt:
release:
approval:
incident:

The namespace registry prevents ambiguous plain numeric IDs.

8. Query Contracts¶

8.1 `GetSupportTimeline`¶

Input:

type SupportTimelineQuery = {
  tenant: TenantRef;
  actor: PrincipalRef;
  correlationId?: string;
  processInstanceId?: string;
  requestId?: string;
  entityRef?: EntityReference;
  timeRange?: { from: string; to: string };
  sourceTypes?: string[];
  limit?: number;
  cursor?: string;
};

Rules:

exactly one tenant is mandatory;
at least one strong selector is required: process, correlation, entity or request;
no global text search across raw payloads;
record visibility is resolved before existence details are returned;
entries are ordered by normalized occurred time, then recorded time and stable source sequence;
source-specific errors are returned as child dispositions rather than hiding the entire timeline;
each entry identifies source owner and evidence state.

8.2 `GetTransitionAuditDetail`¶

Returns:

safe transition envelope;
typed entity/evidence references;
resolution status for each reference;
retention/legal-hold metadata permitted to the actor;
immutable hash/duplicate disposition only for diagnostic roles;
no raw payload or secret.

8.3 `GetRequestDiagnosticSummary`¶

Returns a bounded projection:

request ID
source/route/method
status/duration
tables touched
mutation op/table/fingerprint/affected count
transaction indicator
safe exception code/family
source revision/deployment when known

It does not return SQL parameters, raw bodies, session IDs, cookies, credentials or unredacted exception messages.

8.4 `GetOperationNotificationDetail`¶

Returns notification semantics and a fixed warning:

ACK means read/acknowledged notification only.
It is not business approval or completion.

8.5 `ResolveEvidenceReference`¶

Delegates to the owner resolver. It returns safe state and availability, not a generic table row.

8.6 `GetCorrelationDiagnostics`¶

Shows links among request, command, process, audit, provider attempt and deployment references, including gaps/conflicts.

8.7 `GetRetentionDisposition`¶

Returns current engineering retention, archive, purge and hold state. It must identify the source of policy and whether it is approved, default, inferred or unknown.

9. Command Contracts¶

These are target administrative/evidence commands, not current implementation instructions.

9.1 `AppendBusinessTransitionAudit`¶

Normally called by an application command, not directly by UI.

Requirements:

strict tenant/process context;
immutable audit UUID;
exact transition/result/effect/recovery contract;
bounded entity/evidence references;
same caller transaction when policy requires;
duplicate hash conflict detection;
exact append readback.

9.2 `PlaceAuditLegalHold`¶

Requires:

authorized legal/retention role;
explicit reason and approval reference;
tenant and audit-family scope;
immutable hold event;
exact readback;
no deletion or payload export as a side effect.

9.3 `ReleaseAuditLegalHold`¶

Requires separate authorization and records the release as an append-only administrative transition. It does not immediately purge data.

9.4 `ArchiveAuditFamily`¶

Moves one root plus entity/evidence children under an approved archive manifest and unchanged-row check. It preserves UUID, hash, timestamps, purge date and hold state.

9.5 `PurgeExpiredAuditFamily`¶

Destructive command with explicit policy version, hold check, archive disposition and bounded batch. It cannot delete source business/domain evidence.

9.6 `CreateOperationNotification`¶

Creates display/notification state only. The calling Process defines whether failure is blocking, partial or non-blocking.

9.7 `AcknowledgeOperationNotification`¶

Marks read/acknowledged state only. It cannot satisfy an approval reference.

9.8 `ReconcileEvidenceReference`¶

Updates a separate reconciliation/diagnostic disposition or appends a corrective transition; it never mutates historical reference text to hide a tombstone.

9.9 `ExportSupportEvidencePackage`¶

Future optional command requiring:

named incident/case;
tenant and record scope;
actor authorization;
redaction profile;
source/evidence manifest;
expiry and access controls;
no credential, raw token or unrestricted log export.

10. Stable Error Catalog¶

AUDIT_CONTEXT_REQUIRED
AUDIT_CONTEXT_FORBIDDEN
AUDIT_PROCESS_CONTRACT_INVALID
AUDIT_TRANSITION_INVALID
AUDIT_STATE_REFERENCE_INVALID
AUDIT_EVIDENCE_REFERENCE_INVALID
AUDIT_RECOVERY_BOUNDARY_INVALID
AUDIT_APPROVAL_REQUIRED
AUDIT_TRANSACTION_REQUIRED
AUDIT_WRITE_FAILED
AUDIT_DUPLICATE_CONFLICT
AUDIT_STORE_UNAVAILABLE
AUDIT_RESULT_UNKNOWN

CORRELATION_SELECTOR_REQUIRED
CORRELATION_REFERENCE_INVALID
CORRELATION_CONFLICT
CORRELATION_SOURCE_UNAVAILABLE
CORRELATION_TENANT_MISMATCH

EVIDENCE_NOT_FOUND
EVIDENCE_TOMBSTONED
EVIDENCE_EXPIRED
EVIDENCE_REDACTED
EVIDENCE_OWNER_UNAVAILABLE
EVIDENCE_TENANT_MISMATCH
EVIDENCE_CONFLICT

SUPPORT_FORBIDDEN
SUPPORT_SCOPE_TOO_BROAD
SUPPORT_SOURCE_PARTIAL
SUPPORT_EXPORT_FORBIDDEN
SUPPORT_RESULT_UNKNOWN

RETENTION_POLICY_UNAPPROVED
RETENTION_LEGAL_HOLD_REQUIRED
RETENTION_LEGAL_HOLD_CONFLICT
RETENTION_ARCHIVE_INCOMPLETE
RETENTION_PURGE_FORBIDDEN
RETENTION_RESULT_UNKNOWN

User-facing responses expose stable code, safe summary, correlation reference and next action. They do not expose SQL, stack traces, secrets or foreign-record metadata.

11. Access And Redaction¶

11.1 Role separation¶

Target semantic capabilities may include:

platform.support.timeline.view
platform.support.request-diagnostic.view
platform.audit.transition.view
platform.audit.evidence.resolve
platform.audit.retention.view
platform.audit.legal-hold.place
platform.audit.legal-hold.release
platform.audit.archive.execute
platform.audit.purge.execute
platform.operation-event.ack

These are proposed semantic keys, not a current registry.

11.2 Safe disclosure¶

Before resolving an entity/evidence reference:

authenticated actor
+ strict tenant context
+ support/audit capability
+ record tenant/relation predicate
+ record-state disclosure policy
+ redaction class
-> safe projection or safe denial

For sensitive record existence, the owner chooses 403 or 404 behavior. The support timeline does not reveal foreign-tenant IDs through missing-reference messages.

11.3 Redaction classes¶

PUBLIC_OPERATIONAL
INTERNAL_OPERATIONAL
SENSITIVE_BUSINESS
PERSONAL
SECRET
CREDENTIAL
LEGAL_HOLD_RESTRICTED

The transition ledger should contain only safe namespaced references and codes. Resolvers apply the current actor’s redaction rules at read time.

11.4 Prohibited data¶

Do not persist in transition audit or normal support timeline:

passwords;
session IDs/cookies;
access/refresh tokens;
authorization headers;
API keys/secrets;
signed file URLs;
raw document/file contents;
raw email bodies unless the mail owner and access policy explicitly allows a separate view;
raw provider request/response payloads;
unrestricted SQL/parameters;
unnecessary personal data.

12. Support Timeline UX¶

12.1 Primary screen¶

A support user starts from one strong business identity or request correlation, not an unrestricted global log search.

Screen sections:

Context
- tenant, environment, source revision
- actor/subject/impersonation if permitted
- process/record identity

Current authoritative state
- owning record and version
- current process disposition

Timeline
- business transitions
- request diagnostics
- notifications
- domain evidence
- provider/physical boundaries

Recovery
- safe reread
- owner command to resume
- explicit do-not-repeat warning
- escalation owner

Evidence gaps
- missing/tombstoned/expired/redacted/conflicting references

12.2 Required states¶

Loading
No matching evidence
Denied
Partial source availability
Correlation conflict
Evidence tombstoned
Retention/hold restricted
Current state differs from historical transition
Unknown provider/physical result
Complete safe timeline

12.3 No direct repair from generic timeline¶

The support screen links to the owning recovery command/workspace. It does not expose generic table mutation, raw SQL or unrestricted “mark complete” controls.

13. Administrator And Support Procedure¶

flowchart TD
    A[Collect tenant + record/process/request ID] --> B[Confirm environment and source revision]
    B --> C[Read authoritative current business state]
    C --> D[Read transition audit if available]
    D --> E[Resolve domain evidence]
    E --> F[Read request diagnostics]
    F --> G{Effect boundary known?}
    G -- No --> H[Mark UNKNOWN and escalate to owner]
    G -- Yes --> I{Missing action can be safely resumed?}
    I -- Yes --> J[Use owning command only]
    I -- No --> K[Correction/compensation approval]

Never begin with log deletion, notification ACK, direct SQL, blind provider replay or physical-action repetition.

14. React, Next.js, TypeScript And Worker Boundaries¶

14.1 React¶

Owns:

support filter/input UI;
timeline rendering;
evidence-state badges;
safe links to owner workspaces;
partial/unknown/do-not-repeat warnings;
accessibility and mobile layout.

Does not own:

correlation generation;
transition/effect classification;
record authorization;
evidence resolution;
retention/hold decisions.

14.2 Next.js¶

Owns:

Server Components/Route Handlers as adapters;
session/tenant/access bridge;
validated support queries;
safe response/error mapping;
no-store operational reads unless explicitly designed otherwise.

Does not own business transition rules or raw cross-table SQL in route files.

14.3 TypeScript applications¶

Suggested packages:

AuditApplication
CorrelationApplication
SupportTimelineApplication
OperationNotificationApplication
RetentionApplication
EvidenceResolverRegistry

They depend on typed repositories/resolvers, not React or next/*.

14.4 Repositories¶

TransitionAuditRepository
BusinessRecordResolver
RequestDiagnosticRepository
OperationNotificationRepository
DomainEvidenceResolver
RetentionManifestRepository

14.5 Worker¶

A worker is appropriate for:

asynchronous provider/evidence reconciliation;
bounded archive/purge batches;
evidence-link health checks;
support package generation;
retention policy observation.

A worker is not required for the same-transaction business audit append.

15. Migration And Coexistence¶

AUD-W0 — Current environment characterization¶

verify transition tables/schema in each target environment;
verify active Loader caller and rows;
inventory request-log channels, retention and access;
inventory Operation Event callers and transaction position;
inventory evidence-owner references;
pin source/deployment revisions.

AUD-W1 — Read-only support correlation¶

TypeScript read models over current business state, transition tables and safe logs;
no new writer;
compare with existing manual support workflow.

AUD-W2 — React + Next.js read-only support timeline¶

selected tenant/record/process cohort;
current access/redaction parity;
partial-source and tombstone handling;
no repair controls.

AUD-W3 — Current Loader transition writer reconciliation¶

verify exact source and DB behavior;
correct stale documentation;
define writer failure/rollback policy;
retain one authoritative writer.

AUD-W4 — One additional low-risk transition cohort¶

choose an accepted process with local DB-only R1 boundary;
same-transaction audit append;
duplicate/rollback/readback scenarios;
no provider/physical cohort first.

AUD-W5 — Operation notification linkage¶

preserve separate notification owner;
add stable references where approved;
keep ACK semantics unchanged.

AUD-W6 — Domain evidence resolvers¶

staff, scale, inventory, file, mail and provider families in bounded waves;
tenant/record/redaction tests.

AUD-W7 — Retention/hold/archive design activation¶

approved policy and owner;
dry-run/readback/restore;
no purge activation in the first wave.

AUD-W8 — PHP/Next.js support cutover¶

one read authority per cohort;
rollback to current support queries;
no dual transition writer.

AUD-W9 — Caller-zero and PostgreSQL later¶

retire superseded read adapters after usage evidence;
preserve transition IDs/hashes/relationships;
design PostgreSQL retention/partition strategy separately.

16. Rollback¶

16.1 Read-only support UI¶

Rollback removes the new adapter/UI and returns to current diagnostic tools. It does not delete evidence or change business state.

16.2 Transition writer¶

For an activated cohort:

disable new writer route/cohort
-> retain all audit rows
-> preserve business rows
-> reconcile in-flight/unknown requests
-> return to prior business command

Rollback does not delete transition history.

16.3 Retention/archive¶

Stop new archive/purge claims first. Preserve manifests and rows. A destructive rollback requires separate DB/retention approval.

17. PostgreSQL Preservation¶

Later PostgreSQL design must preserve:

tenant-first uniqueness for audit UUID;
immutable envelope hash;
process/correlation/entity/evidence lookup indexes;
actor/subject nullable-pair constraints;
before/after state triple constraints;
approval and legal-hold pair constraints;
UTC microsecond timestamps;
archive/purge/hold semantics;
deterministic canonical envelope hashing;
ordered child references;
same-transaction append with business command where required.

Potential partitioning is a later design decision. Do not partition by assumptions that break tenant/legal-hold lookup or cross-partition uniqueness.

18. Stable Policy IDs¶

AUDPOL-010 evidence-authority separation
AUDPOL-020 required same-transaction audit cohorts
AUDPOL-030 rejection-audit policy
AUDPOL-040 recovery/effect classification owner
AUDPOL-050 request/process/correlation ID contract
AUDPOL-060 evidence registry and safe resolver
AUDPOL-070 operation-event ACK semantics
AUDPOL-080 notification failure policy
AUDPOL-090 support access and safe denial
AUDPOL-100 redaction classes
AUDPOL-110 retention/archive/purge precedence
AUDPOL-120 legal hold authority
AUDPOL-130 source tombstone behavior
AUDPOL-140 timestamp/timezone normalization
AUDPOL-150 audit correction/compensation lineage
AUDPOL-160 loader writer current-state disposition
AUDPOL-170 JSONL retention/access
AUDPOL-180 PHP/Next.js one-writer/read authority

19. Stable Exception IDs¶

AUD-EXC-010 request response lost after local commit
AUD-EXC-020 business commit succeeded / required audit failed
AUD-EXC-030 audit UUID duplicate same envelope
AUD-EXC-040 audit UUID duplicate conflicting envelope
AUD-EXC-050 operation notification missing
AUD-EXC-060 operation event ACK mistaken for approval
AUD-EXC-070 evidence source tombstoned
AUD-EXC-080 evidence source foreign tenant
AUD-EXC-090 provider committed / local reference missing
AUD-EXC-100 physical work occurred / system result unknown
AUD-EXC-110 request IDs disagree across adapters
AUD-EXC-120 process correlation missing
AUD-EXC-130 actor/subject missing or collapsed
AUD-EXC-140 timezone ordering conflict
AUD-EXC-150 redaction classification unknown
AUD-EXC-160 retention policy conflict
AUD-EXC-170 legal hold blocks archive/purge
AUD-EXC-180 JSONL unavailable
AUD-EXC-190 transition table unavailable
AUD-EXC-200 support source partial

20. Verification Scenarios¶

Request diagnostics¶

AUD-SCN-010 API write request with one DB transaction
AUD-SCN-020 legacy endpoint write
AUD-SCN-030 multiple KJDatabase connections in one API request
AUD-SCN-040 failed transaction
AUD-SCN-050 logging write failure remains non-fatal
AUD-SCN-060 redaction of known sensitive keys
AUD-SCN-070 unexpected sensitive-key review
AUD-SCN-080 pageViewId to child API correlation

Transition audit¶

AUD-SCN-110 same-transaction successful append
AUD-SCN-120 business rollback removes audit append
AUD-SCN-130 audit failure rolls back required business change
AUD-SCN-140 duplicate same UUID/same envelope returns idempotent
AUD-SCN-150 duplicate same UUID/different envelope conflicts
AUD-SCN-160 child process parent/correlation/causation
AUD-SCN-170 R4/R5 approval and non-notification evidence
AUD-SCN-180 result/effect/recovery invalid combinations rejected
AUD-SCN-190 actor/subject impersonation preserved
AUD-SCN-200 evidence cardinality/order constraints

Operation notification¶

AUD-SCN-210 create and tenant-scoped read
AUD-SCN-220 role visibility denied
AUD-SCN-230 ACK sets read state
AUD-SCN-240 unack clears read state
AUD-SCN-250 ACK does not create approval/transition
AUD-SCN-260 notification failure boundary by selected process

Evidence and support¶

AUD-SCN-310 business record available
AUD-SCN-320 source tombstoned
AUD-SCN-330 source expired
AUD-SCN-340 source redacted
AUD-SCN-350 source foreign tenant
AUD-SCN-360 provider result unknown
AUD-SCN-370 physical result unknown
AUD-SCN-380 timezone normalization
AUD-SCN-390 partial timeline source unavailable
AUD-SCN-400 safe support export

Retention and migration¶

AUD-MIG-SCN-010 current transition schema characterization
AUD-MIG-SCN-020 Loader writer parity
AUD-MIG-SCN-030 read-only timeline parity
AUD-MIG-SCN-040 one-writer transition cohort
AUD-MIG-SCN-050 rollback preserves audit rows
AUD-MIG-SCN-060 archive root/children atomically
AUD-MIG-SCN-070 legal hold blocks archive/purge
AUD-MIG-SCN-080 restore preserves identity/hash/timestamps
AUD-MIG-SCN-090 PHP reader caller-zero
AUD-MIG-SCN-100 PostgreSQL parity

Every scenario records environment, source SHA, tenant, actor/subject, request/process/audit IDs, before/after state, exact readback, residue and cleanup.

21. Open Policy Decisions¶

The following must not be invented by an implementation writer:

Which business transitions require same-transaction audit.
Whether audit-store unavailability blocks each selected command.
Which consequential rejections are retained.
Recovery-class and effect-boundary owners per process.
Correlation ID and command-token generation/propagation.
Evidence registry owner and versioning.
Support/audit role model and safe-denial policy.
Redaction classification and sensitive-data review.
Operation Event create failure policy per process.
Current Loader writer activation and stale-document correction.
JSONL channel retention, access, backup and purge.
Transition archive versus PURGE_AFTER precedence.
Legal-hold placement/release authority.
Evidence tombstone and source-retention behavior.
Timezone normalization and event-order policy.
Provider/physical evidence attempt identity.
Support evidence export policy.
PHP/Next.js read and transition-writer cutover owner.
PostgreSQL partition/index/retention design.
Legal/customer retention requirements.

22. Definition Of Ready For Any Implementation Cohort¶

[ ] exact current source and deployed revision pinned;
[ ] exact DB schema/table presence verified;
[ ] tenant/actor/subject/access contract accepted;
[ ] process contract/version and transition names accepted;
[ ] state/effect/recovery mapping accepted;
[ ] evidence references and owner resolvers defined;
[ ] audit failure semantics defined;
[ ] request/command/process correlation defined;
[ ] duplicate/timeout/partial/unknown recovery defined;
[ ] safe support/redaction contract defined;
[ ] retention/hold impact classified;
[ ] one writer and rollback defined;
[ ] target-role and negative scenarios prepared;
[ ] Client 1 non-regression where shared code is involved.

23. Definition Of Complete For One Migrated Cohort¶

[ ] business and transition write commit/rollback behavior verified;
[ ] exact transition/entity/evidence rows read back;
[ ] duplicate/conflicting UUID behavior verified;
[ ] actor/subject/tenant/correlation preserved;
[ ] support timeline matches authoritative business state;
[ ] notification ACK remains non-approval;
[ ] evidence resolvers enforce tenant/redaction;
[ ] unknown-result recovery does not replay committed work;
[ ] rollback preserves audit and business history;
[ ] current operator/support Runbook and Wiki updated and accepted;
[ ] observation period completed;
[ ] superseded caller/read adapter reaches caller-zero;
[ ] no raw secret or unrestricted payload introduced.

24. Current Disposition¶

Source authority:
DETAILED INPUT

Target data/interface/evidence contract:
DETAILED INPUT

Loader transition current activation:
SOURCE PRESENT / DB AND DEPLOYMENT EVIDENCE REQUIRED

Support timeline:
TARGET DESIGN / NOT CURRENT UNIVERSAL RUNTIME

Policy acceptance:
OPEN / PARTIAL

Phase implementation:
USER HOLD

Migration readiness:
NOT M4

---¶

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

Platform Audit, Transition, Correlation And Support Evidence — Rebuild Packet¶

1. Capability Outcome¶

1.1 Non-goals¶

2. Target Authority Model¶

3. Core TypeScript Contracts¶

3.1 RequestTraceContext¶

3.2 ProcessExecutionContext¶

3.3 BusinessTransitionAudit¶

3.4 EvidenceReference¶

3.5 SupportTimelineEntry¶

4. Transition Results, Effects And Recovery¶

4.1 Result values¶

4.2 Effect boundaries¶

4.3 Recovery classes¶

4.4 Failure stages¶

5. Business Transition Writer Policy¶

5.1 Same-transaction required cases¶

5.2 Optional/non-blocking cases¶

5.3 Rejections¶

5.4 Current Loader cohort¶

6. Evidence Type Registry¶

6.1 Registry ownership¶

6.2 Proposed definitions¶

6.3 Evidence resolution states¶

7. Correlation Model¶

7.1 Identifier roles¶

7.2 Propagation rules¶

7.3 Namespaces¶

8. Query Contracts¶

8.1 GetSupportTimeline¶

8.2 GetTransitionAuditDetail¶

8.3 GetRequestDiagnosticSummary¶

8.4 GetOperationNotificationDetail¶

8.5 ResolveEvidenceReference¶

8.6 GetCorrelationDiagnostics¶

8.7 GetRetentionDisposition¶

9. Command Contracts¶

9.1 AppendBusinessTransitionAudit¶

9.2 PlaceAuditLegalHold¶

9.3 ReleaseAuditLegalHold¶

9.4 ArchiveAuditFamily¶

9.5 PurgeExpiredAuditFamily¶

9.6 CreateOperationNotification¶

9.7 AcknowledgeOperationNotification¶

9.8 ReconcileEvidenceReference¶

9.9 ExportSupportEvidencePackage¶

10. Stable Error Catalog¶

11. Access And Redaction¶

11.1 Role separation¶

11.2 Safe disclosure¶

11.3 Redaction classes¶

11.4 Prohibited data¶

12. Support Timeline UX¶

12.1 Primary screen¶

12.2 Required states¶

12.3 No direct repair from generic timeline¶

13. Administrator And Support Procedure¶

14. React, Next.js, TypeScript And Worker Boundaries¶

14.1 React¶

14.2 Next.js¶

14.3 TypeScript applications¶

14.4 Repositories¶

14.5 Worker¶

15. Migration And Coexistence¶

AUD-W0 — Current environment characterization¶

AUD-W1 — Read-only support correlation¶

AUD-W2 — React + Next.js read-only support timeline¶

AUD-W3 — Current Loader transition writer reconciliation¶

AUD-W4 — One additional low-risk transition cohort¶

AUD-W5 — Operation notification linkage¶

AUD-W6 — Domain evidence resolvers¶

AUD-W7 — Retention/hold/archive design activation¶

AUD-W8 — PHP/Next.js support cutover¶

AUD-W9 — Caller-zero and PostgreSQL later¶

16. Rollback¶

16.1 Read-only support UI¶

16.2 Transition writer¶

16.3 Retention/archive¶

17. PostgreSQL Preservation¶

18. Stable Policy IDs¶

3.1 `RequestTraceContext`¶

3.2 `ProcessExecutionContext`¶

3.3 `BusinessTransitionAudit`¶

3.4 `EvidenceReference`¶

3.5 `SupportTimelineEntry`¶

8.1 `GetSupportTimeline`¶

8.2 `GetTransitionAuditDetail`¶

8.3 `GetRequestDiagnosticSummary`¶

8.4 `GetOperationNotificationDetail`¶

8.5 `ResolveEvidenceReference`¶

8.6 `GetCorrelationDiagnostics`¶

8.7 `GetRetentionDisposition`¶

9.1 `AppendBusinessTransitionAudit`¶

9.2 `PlaceAuditLegalHold`¶

9.3 `ReleaseAuditLegalHold`¶

9.4 `ArchiveAuditFamily`¶

9.5 `PurgeExpiredAuditFamily`¶

9.6 `CreateOperationNotification`¶

9.7 `AcknowledgeOperationNotification`¶

9.8 `ReconcileEvidenceReference`¶

9.9 `ExportSupportEvidencePackage`¶