Skip to content

CTC Billing, QBO, Files And Email — Current Source Refresh — 2026-08-08

  • Status: CURRENT STATIC SOURCE REFRESH COMPLETE / ENVIRONMENT, ROLE, PROVIDER AND WIKI EVIDENCE REQUIRED
  • Original detailed-packet baseline: qa@8fbe3529792db8b6dcdc18abbea8e52ccebc68a4
  • Current review ref: qa/master@58c24661902c10a30209bab62d43fc5490feaeba
  • Source relation: CURRENT REF IS 67 COMMITS AHEAD OF THE ORIGINAL BASELINE
  • Existing capability packet: CTC_BILLING_QBO_FILES_EMAIL_CAPABILITY_REBUILD_PACKET.md
  • Existing process reconciliation: CTC_BILLING_QBO_FILES_EMAIL_RECONCILIATION.md
  • Current process addendum: CTC_BILLING_QBO_FILES_EMAIL_CURRENT_SOURCE_ADDENDUM_2026-08-08.md
  • Read-only evidence package: RBR-BILL-QBO-FILE-MAIL-READONLY-PREFLIGHT.md
  • Operator addendum: CTC_BILLING_QBO_FILES_EMAIL_CURRENT_SOURCE_ADDENDUM.md
  • Wiki addendum: CTC_BILLING_QBO_FILES_EMAIL_CURRENT_SOURCE_ADDENDUM.md
  • Program state: PHASE IMPLEMENTATION USER HOLD
  • Effects: repository source inspection and documentation only

1. Purpose

The original Billing/QBO/Files/Email packet was written against 8fbe352.... A later cross-family review classified the entire family as direct source drift because several neighboring source files changed afterward.

That classification was intentionally conservative, but it was too broad.

This refresh rechecks the actual owner files and the exact BOL/Packing List effect blocks so the family is not reopened merely because large cross-functional route files gained unrelated Loader, Street Turn, Staff Time or Booking behavior.

The result is:

AR Billing and QBO core owner source
= NO MATERIAL DRIFT LOCATED

Generic transaction route and shared mutation helpers
= NO MATERIAL DRIFT LOCATED

Generic transaction post-helper file
= FILE DRIFT EXISTS
= IDENTIFIED POST-BASELINE CHANGE IS STREET TURN COMPENSATION
= NO BILLING TRANSACTION SEMANTIC CHANGE LOCATED IN THIS REFRESH

File upload/storage/link owner source
= NO MATERIAL DRIFT LOCATED

Gmail sender
= NO MATERIAL DRIFT LOCATED

BOL email function and route
= TARGETED BLOCK COMPARISON FOUND NO MATERIAL DRIFT

Packing List email function
= TARGETED BLOCK COMPARISON FOUND NO MATERIAL DRIFT

QuickBooks Time changes
= PRESENT AFTER BASELINE
= SEPARATE PROVIDER FAMILY FROM QUICKBOOKS ONLINE INVOICE DELIVERY

This refresh therefore supersedes the Billing row in the broad drift review.

Old central classification:
DIRECT SOURCE DRIFT / FULL TARGETED RE-REVIEW REQUIRED

Current classification:
CORE OWNER NO MATERIAL DRIFT LOCATED
+ ADJACENT CROSS-FAMILY FILE DRIFT DOCUMENTED
+ CURRENT ENVIRONMENT/ROLE/PROVIDER/WIKI EVIDENCE REQUIRED

It does not establish Runtime correctness, provider reconciliation, field acceptance, M3 or M4.

2. Authority Separation Retained

Billing close is still a composite reconciliation over independent child authorities.

Local generic AP/AR transaction
!= Local container AR confirmation
!= QBO invoice delivery
!= File object storage
!= T_FILE business link
!= File readability
!= BOL Gmail message
!= Packing List target/part Gmail messages
!= QuickBooks Time synchronization
!= Daily close acceptance

The current source refresh found no basis to collapse those distinctions.

3. Blob Comparison — Core Owners

3.1 AR Billing and QBO

File Original blob Current blob Result
app/systems/BMS/ar-billing/ar_billing_helper.php 29f2ef3d209de94daa2629f3efc3eec9af6e2173 same byte-identical
app/systems/BMS/ar-billing/api_routes.php a4c0d3a21babddd41efd0a8aa175f53e3a039a4b same byte-identical
public/assets/js/modules/bms/ar-billing.js 8930d2dde28277f43073bc513407830e72619874 same byte-identical
app/utils/QuickBooksOnlineClient.php 0bb4d1e13785cef130401c15f3efa5a4389100e5 same byte-identical
app/platform/tenant/config_helper.php 0ee90f8c229804fa19e5c45259b40a3b01704c20 same byte-identical

Conclusion:

Current local AR confirm semantics
Current QBO claim/create/local-save semantics
Current QBO client capability limits
Current QBO tenant-config source
Current AR Billing browser orchestration

remain governed by the original source-reconciled packet until newer evidence disproves them.

3.2 Generic transaction surface

File Original blob Current blob Result
app/systems/BMS/transaction/api_routes.php 517044aad821118fd2a2a6b26aa53266fd98f7a2 same byte-identical
app/shared/api/table_mutation_helper.php 230379966dfeb50db666541bfb5b2e9d88b0cf32 same byte-identical
app/shared/controller/common_post_helper.php dbba9a2196805ce7c9fdeb4f2daa9d69c28ea52a same byte-identical
app/systems/BMS/transaction/post_helper.php 228322c6e6907c3886b53fd44712530b6214be8d d3158f5af503a1d37f3fdde730a9593270b84c52 changed

The changed post_helper.php now contains guarded Street Turn compensation support. The identified post-baseline change:

RevertStreetTurnPairing
-> requires equipment and selected generated export equipment-load identity
-> validates container state
-> blocks progressed Delivery/Transload history
-> soft-deletes generated export load
-> restores the preceding returned import load
-> emits sync tasks for both loads

belongs to the Street Turn/Equipment/Booking/Yard family.

This refresh did not locate a change to the generic AP/AR transaction route, schema-shaped form mutation helper or common mutation helper.

Safe current interpretation:

BMS transaction post-helper file changed
!= Billing transaction semantics changed

The generic transaction packet remains subject to current DB/role/runtime evidence because unchanged source does not prove the deployed environment.

3.3 File object, metadata and storage

File Original blob Current blob Result
app/shared/files/api_routes.php 52bf06646d87dfff15515f51a1dafcb0eb90ef40 same byte-identical
app/shared/files/media_helper.php f8e632a4ff5a530c7b1a741584a4fef08f67c6fb same byte-identical
app/shared/storage/file_storage.php ed6e44f93d53bf82f0174a5a8c3ef1acf37beeee same byte-identical

The original distinctions remain current source input:

object stored
!= metadata saved
!= business link created
!= object readable
!= every intended link complete
!= object safe to delete

3.4 Gmail sender

File Original blob Current blob Result
app/utils/GmailSender.php f2dd8c51fd42eaed848eaad22d198ac52538eda7 same byte-identical

The provider adapter remains synchronous and continues to return provider response data without creating a generic durable business email ledger.

4. Targeted Comparison — BOL Email

The enclosing Transload route file changed substantially after the original baseline because it gained or changed unrelated capabilities, including:

  • Loader work assignment;
  • Staff Time/QuickBooks Time interactions;
  • transition evidence;
  • instruction configuration;
  • Final Loading Review mutation guards;
  • Planning/Yard recovery behavior.

The file-level blob therefore changed.

However, the targeted BOL block was compared at the original and current refs. The following remain materially unchanged:

tmsTransloadApiBolFailure
tmsTransloadApiBolScaleTicketPdf
tmsTransloadApiBolFileAttachments
tmsTransloadApiSendBolEmail
POST /tms/transloads/{id}/bol-email

Current behavior remains:

  1. tenant-scoped active Transload read;
  2. billing-company BOL email lookup;
  3. compatibility recipient override for username admin;
  4. optional Scale Ticket PDF generation;
  5. active Transload file materialization through FileStorage;
  6. synchronous Gmail send;
  7. temporary-file cleanup;
  8. provider response returned to the caller;
  9. no durable BOL send-intent/attempt/result row.

Current completion remains:

intended recipient
+ intended subject/reference
+ intended attachment set
+ Gmail provider evidence
= reconciled BOL send

The following remain unsafe conclusions:

HTTP success alone = durable reconciliation
IS_DOC_SUBMITTED = email sent
file attached = email sent
response missing = email failed

5. Targeted Comparison — Packing List Email

The enclosing Booking route file changed after the original baseline due other Booking/MK/Street Turn and application-surface work.

The targeted tmsBookingApiSendPackingListEmail() block was compared at the original and current refs and no material change was located.

Current behavior remains:

  1. tenant-scoped Booking identity;
  2. CUSTOMER, INSPECTOR or BOTH target selection;
  3. recipient lookup from active PACKING_LIST company-email configuration;
  4. compatibility recipient override for username admin;
  5. rejection of MK report mode on this CTC route;
  6. GP OUT REF prerequisite check;
  7. generated file preparation and Gmail-size batching;
  8. sequential target × part sending;
  9. in-memory successful Results collection;
  10. immediate failure return with prior successful results;
  11. temporary attachment cleanup;
  12. no durable target/part send ledger;
  13. no resume-one-missing-part command.

Current completion remains:

for every intended target
+ for every generated part
+ one reconciled Gmail provider message
= Packing List email complete

A repeated target send can repeat already accepted parts. Unknown-result recovery therefore still requires provider-side reconciliation before resend.

6. QuickBooks Online Versus QuickBooks Time

Post-baseline source added or changed Loader/Staff Time behavior and its QuickBooks Time synchronization.

That source drift is real, but it belongs to a separate provider contract.

QuickBooks Online Invoice
= customer AR invoice provider effect

QuickBooks Time
= staff clock/break/job projection provider effect

The following must not be inferred:

QBT change
-> QBO Invoice delivery changed

QBO Invoice SYNCED
-> Staff Time synchronized

Local Clock Out committed
-> Local AR/QBO state changed

The Billing family may reference QBT only as a cross-process close dependency when staff labor is applicable. Its provider state and recovery remain owned by the Staff Time/Integration family.

7. Current Source Contract Retained

7.1 Local generic transaction

Current source still supports local AP/AR records for source families including Trucking, Transload, Chassis and Scale Ticket.

The current form path remains schema-shaped. The target must still replace arbitrary table mutation with semantic commands.

The local close request still requires exact per-row reread and does not prove payment, QBO, file, email or print completion.

7.2 Local container AR confirm

Current source still uses one local DB transaction for the submitted confirm batch.

Current risks remain:

  • stale preview;
  • no proven unique active booking/container invoice constraint;
  • concurrent confirm duplicate/race;
  • existing local row rewrite;
  • old line soft-delete followed by new line insert;
  • no accepted post-confirm correction process;
  • local confirm and QBO handoff separated by browser orchestration.

7.3 QBO delivery

Current source still follows:

eligible local rows
-> claim token
-> conditional SYNCING
-> createInvoice outside DB transaction
-> local provider reference save
-> SYNCED or ERROR handling

Current unresolved risks remain:

  • no provider idempotency key;
  • no provider invoice search/read/reconcile interface in the current client;
  • stale SYNCING recovery not approved;
  • provider-created/local-save-uncertain duplicate risk;
  • QBO_ERROR used for both claim token and later error text;
  • token refresh and invoice effect share the request path;
  • browser interruption can leave local READY rows with no QBO attempt.

7.4 Files

Current source still separates physical object and DB link in practice but not as fully independent domain records.

Current unresolved risks remain:

  • object success before link failure;
  • duplicate link registration;
  • sequence races;
  • shared path/object deletion ambiguity;
  • orphan cleanup ownership;
  • environment-specific storage/readability;
  • no MySQL/object-store atomic transaction.

7.5 Emails

Current source still has no durable BOL or Packing List business send ledger.

Current unresolved risks remain:

  • response-loss ambiguity;
  • no safe automatic resend;
  • missing attachment silently affecting provider result depending on owner validation;
  • Packing List partial target/part success;
  • no resume-one-part operation;
  • compatibility recipient override is not a target policy.

8. Current Caller And Surface Drift

Even though the core Billing/effect blocks are materially unchanged, their surrounding application surfaces changed.

Relevant current drift includes:

  • Booking gained new operations and relation rules;
  • Transload gained Loader/Staff Time/transition/planning behavior;
  • BMS transaction helper gained Street Turn compensation;
  • Final Loading Review gained outbound correction guards;
  • QuickBooks Time behavior changed for final-break/clock-out workflows.

These changes can affect:

when a source row becomes billable
which source identity is selected
whether a related record can be corrected/deleted
which role can reach an effect
what the daily close must reconcile

Therefore this refresh does not declare the entire operational close accepted merely because the core helper blobs are stable.

Required current evidence still includes:

  • Client 1 role/page/API/action/record matrix;
  • exact active schema and constraints;
  • current transaction/AR/QBO row distributions;
  • current QBO credential availability and provider reconciliation procedure;
  • current file object/link/readability state;
  • current Gmail recipient and provider evidence;
  • current Wiki rows and rendered role behavior;
  • target-role normal, denied, duplicate, timeout and recovery scenarios.

9. Corrected Drift Classification

Previous broad classification

DIRECT SOURCE DRIFT
FULL TARGETED RE-REVIEW REQUIRED

Corrected current classification

CORE BILLING/QBO/FILE/GMAIL OWNER SOURCE:
NO MATERIAL DRIFT LOCATED

BOL/PACKING EMAIL TARGETED BLOCKS:
NO MATERIAL DRIFT LOCATED

GENERIC TRANSACTION HELPER FILE:
ADJACENT STREET TURN DRIFT
NO BILLING SEMANTIC CHANGE LOCATED

CURRENT OPERATIONAL SURFACE:
CROSS-FAMILY CALLER/STATE DRIFT PRESENT

CURRENT ENVIRONMENT EVIDENCE:
REQUIRED

Current use:

Existing detailed packet
+ this current-source refresh
+ current read-only evidence package
= current documentation input

Do not use only the old baseline header, and do not discard the existing packet as obsolete.

10. Required Evidence Packages

This refresh assembles four previously named evidence families into one read-only preflight:

RBR-BILL-001
Local Billing / AR current state

RBR-QBO-001
QBO state and unknown-result inventory

RBR-FILE-001
Object / metadata / link / readability inventory

RBR-MAIL-001
BOL / Packing List local/provider evidence inventory

Execution is not authorized by this document.

Required result classes:

SOURCE_STABLE_ENVIRONMENT_UNKNOWN
CURRENT_LOCAL_STATE_CONSISTENT
CURRENT_LOCAL_STATE_CONFLICT
PROVIDER_RECONCILIATION_REQUIRED
FILE_RECONCILIATION_REQUIRED
MAIL_RECONCILIATION_REQUIRED
ROLE_OR_WIKI_MISMATCH
BLOCKED

11. Current Policy Decisions Still Open

Local transaction and AR

  • active invoice uniqueness;
  • correction/void/reversal after confirm;
  • close-state transition and allowed actors;
  • mixed selected-row close behavior;
  • source-specific create idempotency;
  • invoice version/line identity.

QBO

  • provider search/reconciliation operation;
  • durable provider effect identity;
  • stale SYNCING threshold and owner;
  • duplicate-match handling;
  • existing provider invoice link procedure;
  • token refresh ownership;
  • manual-review and compensation policy.

File

  • object identity versus link identity;
  • link uniqueness;
  • shared-object reference count;
  • unlink versus delete;
  • orphan retention/cleanup;
  • object-read evidence;
  • environment storage recovery.

Mail

  • durable email intent/attempt/result;
  • required attachment policy;
  • response-loss search contract;
  • safe resend authorization;
  • target/part resume;
  • compatibility recipient override retirement;
  • retention and support evidence.

12. Current Readiness

Static source refresh:
COMPLETE

Core owner blob comparison:
COMPLETE

BOL targeted block comparison:
COMPLETE

Packing List targeted block comparison:
COMPLETE

Current process addendum:
PRESENT

Read-only evidence package:
DEFINED / NOT RUN

Current DB/schema/rows:
NOT READ

Current QBO provider state:
NOT READ

Current Gmail provider state:
NOT READ

Current File object readability:
NOT READ

Current role/API/Wiki evidence:
NOT RUN

M3:
NO

M4:
NO

Phase progress:
NONE

13. Maintenance

Reopen the static source refresh when a later commit changes any of:

BMS transaction create/close/form paths
AR Billing candidate/preview/confirm
QBO claim/create/local-save/reconcile
QuickBooksOnlineClient
Tenant QBO config/credential resolution
File upload/link/download/delete/storage
GmailSender
BOL email block/route
Packing List email block/route
Billing/AR/QBO role or menu contract

Adjacent Loader, Street Turn, Scale, Booking or WMS changes should be classified first. Do not automatically reopen the entire Billing family unless they change a Billing/effect owner or an applicable source-state handoff.

---

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