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

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

Status: CURRENT SOURCE ADDENDUM / ORIGINAL PROCESS PACKET RETAINED
Current review ref: qa/master@58c24661902c10a30209bab62d43fc5490feaeba
Original source baseline: qa@8fbe3529792db8b6dcdc18abbea8e52ccebc68a4
Current source refresh: CTC_BILLING_QBO_FILES_EMAIL_CURRENT_SOURCE_REFRESH_2026-08-08.md
Original reconciliation: CTC_BILLING_QBO_FILES_EMAIL_RECONCILIATION.md
Original process owners:
PROC-BMS-BILLING-CLOSE-CTC
PROC-BMS-TRANSACTION-LIFECYCLE-CTC
PROC-BMS-AR-BILLING-CONFIRM-CTC
PROC-BMS-AR-QBO-DELIVERY-CTC
PROC-BMS-TRANSACTION-DOCUMENT-CTC
PROC-TMS-BOL-EMAIL-CTC
PROC-TMS-PACKING-LIST-EMAIL-CTC
Program state: PHASE IMPLEMENTATION USER HOLD
Effects: documentation only

1. Addendum Decision¶

The original process reconciliation remains the detailed semantic owner.

This addendum corrects only the source-freshness interpretation.

Original process semantics:
RETAIN

Core Billing/QBO/File/Gmail owner source:
NO MATERIAL DRIFT LOCATED

BOL and Packing List send blocks:
NO MATERIAL DRIFT LOCATED

Surrounding Transload/Booking/BMS helper files:
CHANGED FOR ADJACENT PROCESSES

Current environment/role/provider/Wiki evidence:
REQUIRED

Do not rewrite the entire process family based on unrelated file-level drift.

2. Current Composite Boundary¶

The current daily Billing close is still a human/composite reconciliation.

Source work eligible for Billing
-> Local generic AP/AR transaction when applicable
-> Local container AR confirmation when applicable
-> QBO Invoice delivery when applicable
-> File object/link/readability when applicable
-> BOL email when applicable
-> Packing List target/part email when applicable
-> Carry unresolved child with exact evidence and owner

There is no accepted universal persisted BILLING_COMPLETE state.

Each child remains independently authoritative.

3. Current Source Checkpoints¶

3.1 Local generic AP/AR¶

The current route and shared mutation helpers remain the original source contract.

Current checkpoint:

intended source relation
+ intended transaction header
+ intended active lines
+ reviewed close fields
+ exact row reread
= local transaction checkpoint

Non-implications:

local transaction exists
!= reviewed/closed
!= paid
!= QBO delivered
!= file complete
!= email sent

3.2 Local container AR¶

Current confirm remains a local transaction over the submitted item batch.

Current checkpoint:

one intended active local container AR
+ reviewed active lines
+ current local QBO state
+ exact header/line reread
= local container AR checkpoint

READY means local readiness for QBO, not provider delivery.

3.3 QBO Invoice¶

Current checkpoint:

provider invoice identity and intended values
+ local QBO invoice ID/doc/sync token
+ every local group row SYNCED
= reconciled QBO checkpoint

The following remain uncertain and require reconciliation:

SYNCING
ERROR
response timeout
provider accepted / local reference missing
multiple possible provider matches

3.4 File¶

Current checkpoint:

object exists
+ every intended T_FILE business link exists
+ object is readable through each intended link
= file checkpoint

Metadata-only success is not sufficient.

3.5 BOL email¶

Current checkpoint:

intended Transload/reference
+ intended recipient
+ intended subject
+ intended attachments
+ Gmail provider evidence
= BOL email checkpoint

3.6 Packing List email¶

Current checkpoint:

for every intended target
+ for every generated part
+ one provider-accepted message
= Packing List email checkpoint

The current API response is evidence for that request only and is not a durable send ledger.

4. Current Partial-Result Matrix¶

Situation	Current safe interpretation	Required next step
Local transaction response missing	commit unknown	reread exact transaction/header/lines before retry
Local AR confirmed, QBO not called	local checkpoint succeeded	start only QBO step after reread
QBO `SYNCING` stale	provider state unknown	search/reconcile provider before any create retry
QBO `ERROR`	provider absence not proven	inspect claim/error/provider evidence
Provider invoice exists, local ID missing	provider committed/local pending	link/reconcile existing provider invoice; do not recreate
File object exists, no link	object-only partial	register/reconcile intended link or controlled cleanup
Link exists, object unreadable	metadata/object conflict	file-owner recovery; do not create unrelated duplicate links
BOL response missing	Gmail result unknown	search Sent/provider evidence by recipient/subject/time
Packing customer sent, inspector failed	partial target result	reconcile sent target; retry only missing approved target/part
Packing part N failed	earlier parts may be accepted	provider-side part inventory before retry
QuickBooks Time failed after local staff event	separate provider partial	Staff Time/Integration owner recovery; do not alter QBO Invoice state

5. Current Adjacent-Process Drift¶

5.1 Street Turn in BMS transaction helper¶

The BMS helper now supports guarded Street Turn compensation.

This is a source-ownership warning:

one helper file
!= one Process authority

Street Turn compensation must remain under its own Process/recovery contract and must not be documented as generic Billing transaction behavior.

5.2 Loader and Staff Time in Transload routes¶

The Transload route file now contains Loader, Staff Time, notification and transition-evidence behavior.

The BOL email block itself remains unchanged, but source eligibility and operational close timing may depend on the current Transload state.

5.3 Booking and MK/Street Turn surface¶

The Booking route file now has additional Booking/MK/Street Turn behavior. The CTC Packing List email block remains unchanged.

Do not infer that every Booking change alters Packing List delivery. Reopen the email contract only when the target/recipient/attachment/send/result block changes.

5.4 QuickBooks Time¶

QuickBooks Time is a separate external effect from QBO Invoice.

Current close documentation must not combine their state fields, retry procedures or completion claims.

6. Current State Machines Retained¶

Local container AR¶

NOT_PRESENT
-> READY
-> SYNCING
-> SYNCED

READY / SYNCING
-> ERROR

ERROR
-> manual/provider reconciliation
-> READY only after absence/retry eligibility is established
-> SYNCED when existing provider result is linked

These labels describe current local projection, not a complete provider attempt history.

File¶

NO_OBJECT
OBJECT_ONLY
OBJECT_AND_LINK
READABLE
PARTIAL_LINK
UNREADABLE
ORPHAN_CANDIDATE
DELETE_PENDING

These are semantic classifications for evidence/recovery. They are not claimed current schema enums.

Mail target/part¶

NOT_ATTEMPTED
SENT
FAILED_DEFINITE
UNKNOWN
PARTIAL

Current source persists no full target/part state machine. The classification is reconstructed from response and provider evidence.

7. Stable Identity Retained¶

Boundary	Current identity	Required evidence
source work → generic transaction	tenant + related table/id + transaction ID/UUID	source and transaction reread
booking/container → local AR	tenant + booking/container + transaction UUID	active header/lines
local AR → QBO group	sorted transaction UUIDs + grouping mode + customer/doc values	local claim and provider invoice
provider QBO → local	provider invoice ID/doc/sync token + local transaction set	both sides reconciled
object → transaction	storage/path or object UUID + `T_FILE` relation	object and link/readability
Transload → BOL	tenant + Transload/reference + recipient + attachment set	Gmail provider evidence
Booking → Packing mail	tenant + Booking + target + part/total + attachment content	per-target/part provider evidence

Subject text alone is not a sufficient durable identity.

8. Current Access And Role Evidence Required¶

Static source stability does not prove authorization correctness.

The current evidence package must cover:

Office/Billing intended role
Denied field roles
Direct page access
Initial data APIs
Confirm/close/QBO/file/email action APIs
Tenant and record predicates
Current state predicates
Visible button versus backend denial
Super Admin/compatibility behavior

A Super Admin result cannot substitute for the intended Office/Billing role.

9. Current Wiki Requirements¶

Current Wiki topics:

billing
ar-billing-qbo
ctc-daily
errors-recovery

Required current wording:

Local complete != QBO complete
QBO accepted != local reference saved
File metadata != readable object
BOL/Packing response missing != safe resend
Packing target/part partial != complete
QuickBooks Time != QBO Invoice

Actual T_WIKI_PAGE content and rendered role behavior remain unread.

10. Evidence Before Any Source Correction¶

Run only after separate authorization:

Required evidence order:

source/deployment/DB identity
-> schema/index inventory
-> local transaction/AR/QBO row inventory
-> file object/link metadata inventory
-> mail local-evidence inventory
-> named-role GET/action visibility evidence
-> provider reconciliation where separately authorized
-> current Wiki inventory

Do not modify source merely because an old packet header is stale.

11. Addendum Conclusion¶

Original detailed process packet:
RETAIN

Static current source refresh:
COMPLETE

Core owner material drift:
NOT LOCATED

Adjacent source/caller drift:
DOCUMENTED

Current environment evidence:
NOT RUN

Provider evidence:
NOT RUN

Current Wiki evidence:
NOT RUN

M3:
NO

M4:
NO

---¶

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