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 Integration / Provider — Current Effect Matrix — 2026-08-08¶
- Status:
CURRENT STATIC SOURCE MATRIX / ENVIRONMENT AND PROVIDER EVIDENCE REQUIRED - Current source baseline:
qa@2163051c30380585f07b9541ccd15cbc28d7e7fe - Source refresh:
PLATFORM_INTEGRATION_PROVIDER_CURRENT_SOURCE_REFRESH_2026-08-08.md - Credential authority:
PLATFORM_PROVIDER_CREDENTIAL_CURRENT_SOURCE_AUTHORITY_2026-08-08.md - Previous platform authority:
PLATFORM_INTEGRATION_OUTBOX_WORKER_PROVIDER_SOURCE_AUTHORITY.md - Program state:
PHASE IMPLEMENTATION USER HOLD
1. Purpose¶
This matrix connects each current external effect to the business caller that requests it, the local record that remains authoritative, the provider adapter, the current durable evidence, and the safe recovery boundary.
It prevents the following collapses:
business command success
!= provider accepted
provider accepted
!= provider reference saved locally
provider timeout
!= provider absence
callback acknowledged
!= callback applied
credential saved
!= provider connectivity verified
file metadata saved
!= object readable
notification suppressed
!= notification delivered
worker or cron invocation completed
!= every child item completed
The matrix is a source-reconciled documentation input. It does not authorize a provider call, credential operation, retry, callback replay, file operation, scheduler change or worker deployment.
2. Effect Ownership Matrix¶
| Family | Current business caller / trigger | Local authority | External or file effect | Current durable attempt/result evidence | Callback / receipt | Unknown-result rule | Current disposition |
|---|---|---|---|---|---|---|---|
| QBO Invoice | AR Billing qbo-sync after local AR group validation and claim |
T_TRANSACTION AR rows and QBO state fields |
create one QBO Invoice | QBO fields on T_TRANSACTION; claim token temporarily multiplexed through QBO_ERROR; no immutable attempt ledger |
none identified for invoice create | search/reconcile provider before any recreate when provider acceptance is possible | provider adapter unchanged; environment/provider evidence required |
| QuickBooks Time | committed Staff Time events from Clock, Break and selected Loader job transitions | T_STAFF_TIME_EVENT |
create/update/close provider timesheet; refresh OAuth token when required | provider-specific JSONL and local user/config mapping; no common attempt row | OAuth callback/setup path, not a timesheet-result callback ledger | preserve local staff event; manual review for conflicting/ambiguous provider timesheet | adapter unchanged; Loader caller surface expanded |
| Gmail BOL | Transload BOL email action | T_TRANSLOAD, recipient config and selected attachment source |
send Gmail message with optional Scale PDF and active linked files | synchronous provider response only; no BOL-specific durable attempt row | none | reconcile Sent mail by narrow recipient/subject/reference/time/attachment set before resend | sender and targeted BOL block unchanged |
| Gmail Packing List | Booking Packing List email action by target and generated part | T_BOOKING, packing projection, recipient source and target/part request |
send one or more Gmail messages | response contains per-target/per-part results for the request; no complete durable target/part ledger | none | do not replay all targets/parts; reconcile and resume only missing target/part | sender and targeted block unchanged |
| Gmail Inventory Report | WMS Inventory report email action | Inventory report query, selected tabs/commodities, company recipient configuration | generate temporary XLSX and send Gmail message | synchronous result; temporary file deleted after request; no durable report-send attempt row identified | none | provider evidence before resend after response loss; regenerate attachment only for a proven missing send | current caller added after prior platform baseline |
| Gmail Booking Inquiry | Booking/Empty Plan inquiry action grouped by customer | selected Booking-needed rows and company recipient configuration | send one Gmail message per eligible company group | per-company response rows in current request; no durable batch ledger identified | none | preserve successful groups and retry only proven missing group | current caller added/expanded after prior baseline |
| Gmail Appointment Watch | Gmail Pub/Sub notification and manual replay | T_MAILBOX_WATCH_STATE, T_MAIL_MESSAGE, T_MAIL_REQUEST_ITEM |
Gmail history read and message intake | durable mailbox cursor, message and request-item records | Pub/Sub notification is the receipt input | duplicate/stale notification is no-op; history gap requires replay from durable cursor | provider-specific durable workflow unchanged |
| Gmail Appointment Reply | approved request-item workflow | appointment/request-item state and reply fields | send reply through Gmail | caller stores reply Message/Thread IDs where implemented | none separate from Gmail result | reread request item and Sent mail before repeating approved reply | current domain workflow remains separate from generic outgoing mail |
| Telegram Work Assignment | Office creates Work Assignment; assignment row is inserted before send attempt | T_LOADING_PLANNER Work Assignment row |
Bot API send to assigned Loader | current route returns per-loader Telegram result and may update LAST_SENT_TIME; no common immutable attempt row |
none | assignment exists even when message failed; never recreate assignment to retry notification | current caller added after prior platform baseline |
| Telegram Loader dispatch/completion/next queue | selected Transload planning/completion paths | Planner/Transload/Staff state | Bot API send | caller-specific response and marker fields | none | preserve committed business transition; recover notification on existing record | caller surface expanded |
| Telegram manual dispatch | explicit Loader dispatch action | selected Planner and recipient set | Bot API send | LAST_SENT_TIME after success; provider response in request |
none | reread Planner marker and provider evidence before repeat | current direct caller |
| Telegram suppressed delivery | any Telegram sender while tenant delivery is disabled | caller-owned business row | no provider request | sender result ok=true, suppressed=true |
none | classify SUPPRESSED, never SENT |
unchanged invariant |
| Telegram webhook | Telegram provider webhook | Staff/Loader/domain rows selected by callback/message | callback handling and optional Bot API response/edit | request/log and resulting domain state; no Update-ID receipt ledger identified | webhook request itself | duplicate/replay safety not established by a durable receipt ledger; reread domain state | unchanged provider adapter; current caller mapping required |
| Telegram Break cron | secret-protected HTTP invocation | Break Planner and Staff Time state | close expired break work | request summary and resulting domain rows; no durable run/lease ledger identified | none | rerun only from idempotent owner-state review; report per-item disposition where available | unchanged scheduler style |
| APMT Terminal Appointment | Container Tracking preflight/slots/create | Equipment, Equipment Load, Booking, Delivery and resolved appointment context | provider slot query and appointment create | provider response returned by request; no dedicated local appointment-attempt ledger identified in reviewed route | provider response only | after timeout, reconcile terminal appointment before another create | current caller added after prior platform baseline |
| AI Voice outbound call | AI Voice start action after local call intent commit | T_AI_VOICE_CASE, T_AI_VOICE_CALL |
Twilio call create | durable request key, provider SID/status/error and PROVIDER_UNKNOWN state |
Twilio status/recording callbacks | explicit provider-unknown state; do not start another call until reconciled | provider-specific intent/result model unchanged |
| Twilio status callback | Twilio callback endpoint | T_AI_VOICE_CALL |
apply provider call state | call fields and request diagnostics | callback and application currently occur in endpoint transaction | provider retries failed callback; duplicate/out-of-order behavior remains domain-specific | unchanged |
| Twilio recording callback/cleanup | recording callback and retention cleanup | call recording fields and retry state | record provider recording metadata or delete recording | recording status, retry count and error fields | callback for creation; cleanup request for deletion | retain failed cleanup state and retry through approved retention workflow | unchanged |
| Gemini Live / Voice Gateway | Twilio Media Stream accepted by Node gateway | AI Voice call/session plus gateway memory | long-lived Gemini Live connection and signed CTC tool calls | call/session/transcript state; gateway logs | WebSocket messages, signed tool responses | bounded fallback/transfer; reconcile call and transcript state after disconnect | unchanged |
| Voice transcript filesystem outbox | Voice Gateway transcript segment delivery | transcript segment identity and staged JSON file | HTTP delivery to CTC | host-local atomic JSON files, retry count implicit in drain cycle, deletion after acceptance | CTC response acts as receipt | retain file for later drain; do not generalize to universal queue | unchanged provider-specific outbox |
| File upload/register | current File owner and business upload caller | T_FILE metadata/link plus owning business record |
EFS/S3 object write | object plus DB metadata/link; compensation attempt on DB failure | none | classify object-only, metadata-only, link-only or unreadable; resume missing owner step | storage adapter unchanged |
| File delete/cleanup | File owner, Wiki asset path or archive/retention workflow | soft-deleted T_FILE and cleanup marker |
EFS/S3 object delete | metadata deletion and cleanup marker; log on failure | none | do not repeat business deletion; retry only pending object cleanup | unchanged |
| Provider credential reveal | Admin Console authorized user for one allowlisted tenant credential | encrypted SECRET.<CONFIG_KEY> row plus tenant/provider definition |
no provider call; server-side decrypt and return one value | request diagnostic with body redaction; safe configured/updated metadata; no domain credential-event ledger identified | none | reveal is read of current stored value; never persist/log response | new current source |
| Provider credential replacement | Admin Console authorized user for one allowlisted tenant credential | T_TENANT_CONFIG encrypted secret row |
no provider call; replace encrypted credential | optimistic EXPECTED_UPDATED_AT; update returns timestamp only; legacy plaintext row retired/wiped |
none | on missing response reread safe revision/configured state; do not repeat blindly | new current source |
| Provider credential removal | UI/error text references a separate remove action | no accepted current owner located | intended removal not established | no managed remove route/helper located in reviewed current source | none | treat as NOT IMPLEMENTED / OPEN CONTRACT; do not emulate with empty replacement |
current gap |
| Root CLI jobs | root cron/mail/report jobs | job-specific business markers | Gmail/provider/file effects by job | job-specific JSONL and business marker timestamps; no universal run ledger identified | provider-specific | reread each child owner and provider evidence; do not infer batch success from process exit | unchanged execution style |
| Future provider worker | not currently authoritative | provider-specific intent/attempt records only if separately approved | selected provider effect | lease/attempt/heartbeat contract is target design | provider-specific callback/receipt | reconciliation before retry after lease loss or timeout | target design, not current Runtime |
3. Current Provider Adapter Freshness¶
The following adapters/helpers are byte-identical between the previous platform Integration baseline and the current review ref:
QuickBooksOnlineClient
QuickBooks Time sync helper
GmailSender
TelegramSender
FileStorage
AI Voice voice helper
Gmail Appointment Watch service
Therefore current changes are primarily:
new or expanded business callers
+ tenant credential management
+ current role/config/environment evidence gaps
not a wholesale provider-adapter rewrite.
4. Credential Effect Boundary¶
The current Admin Console credential path has a narrow effect:
Reveal
= decrypt one allowlisted credential for an authorized tenant context
= no provider request
Replace
= encrypt and store one allowlisted credential
= retire/wipe active legacy plaintext companion
= no provider request
Configured
!= provider authenticated
!= provider reachable
!= module enabled
!= action authorized
Current unresolved questions:
- no managed removal command located;
- dedicated deployment UI is read-only, but direct route enforcement requires evidence;
- no separate immutable credential-management event was located;
- long-lived process cache and credential rotation observation require environment evidence;
- reveal/update role acceptance requires controlled-account evidence.
5. Safe Recovery Matrix¶
| Observed condition | Required first step | Prohibited shortcut |
|---|---|---|
| local business committed, provider result failed | reread local owner and provider-specific state | recreate local business record |
| timeout after provider request | provider reconciliation/search or callback/state read | blind replay |
| provider accepted, local reference missing | link/reconcile existing provider object | create another provider object |
| Telegram suppressed | show SUPPRESSED and follow manual notification policy |
call it sent |
| Gmail multi-part partial | identify successful target/part | resend all targets/parts |
| QBT conflict | preserve local Staff Time and classify manual review | close unrelated external timesheet |
| APMT create unknown | search/read terminal appointment evidence | create a second appointment |
| credential update response missing | reread configured/revision metadata | submit replacement repeatedly |
| file metadata/object divergence | classify object, metadata, link and readability separately | delete/reupload all evidence |
| callback duplicate/out of order | reread provider event identity and current domain state | force the requested state |
| worker lease lost after provider request | reconcile provider before re-claim/retry | assume failure from lease expiry |
6. Evidence Required¶
Static source mapping does not establish current operation. Required packages include:
RBR-INTEGRATION-001
RBR-PROVIDER-CREDENTIAL-001
RBR-QBO-001
RBR-QBTIME-001
RBR-GMAIL-001
RBR-TELEGRAM-001
RBR-APMT-001
RBR-AI-VOICE-001
RBR-FILE-001
Each executed package must identify the exact environment, tenant, actor, source/config revision, local record, provider read authority, prohibited effects, result classification and accepting owner.
7. Current Disposition¶
Current provider adapter freshness:
REFRESHED / NO MATERIAL CORE DRIFT LOCATED
Current business caller/effect inventory:
REFRESHED FOR NAMED SURFACES
Current credential-management source:
DOCUMENTED
Current environment/provider state:
NOT READ
Generic outbox:
NOT APPROVED
M3:
NO
M4:
NO
---¶
Source:
docs/processes/PLATFORM_INTEGRATION_PROVIDER_CURRENT_EFFECT_MATRIX_2026-08-08.md— ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.