Platform Integration / Provider — Current Source Refresh — 2026-08-08¶

Status: CURRENT STATIC SOURCE REFRESH COMPLETE / ENVIRONMENT, PROVIDER, CREDENTIAL, CALLBACK AND SERVICE EVIDENCE REQUIRED
Previous source-authority baseline: qa/master@a5280b7cdc1c78b809ed6f1996ca31491b522146
Current review ref: qa@2163051c30380585f07b9541ccd15cbc28d7e7fe
Previous authority: PLATFORM_INTEGRATION_OUTBOX_WORKER_PROVIDER_SOURCE_AUTHORITY.md
Current effect matrix: PLATFORM_INTEGRATION_PROVIDER_CURRENT_EFFECT_MATRIX_2026-08-08.md
Current read-only preflight: RBR-INTEGRATION-001-READONLY-CURRENT-SURFACE-PREFLIGHT.md
Credential boundary: PLATFORM_PROVIDER_CREDENTIAL_MANAGEMENT_CURRENT_SOURCE_2026-08-08.md
Credential preflight: RBR-CREDENTIAL-001-READONLY-CURRENT-STATE-PREFLIGHT.md
Support addendum: PLATFORM_INTEGRATION_PROVIDER_CURRENT_SURFACE_ADDENDUM.md
Wiki addendum: PLATFORM_INTEGRATION_PROVIDER_CURRENT_SURFACE_WIKI_ADDENDUM.md
Program state: PHASE IMPLEMENTATION USER HOLD
Effects: repository source inspection and documentation only

1. Purpose¶

The earlier Integration source authority correctly separated business state, provider attempt, callback receipt, local reconciliation, scheduler execution, file-object lifecycle and worker behavior. Its declared source baseline predates later operational caller additions and the current Admin Console credential-management path.

This refresh answers:

Which provider executors changed?
Which business callers were added or expanded?
Which provider/config credentials are now directly manageable?
Which result checkpoints are durable local state versus transient response/log state?
Which callbacks or cron endpoints have durable receipts or run ledgers?
Which unknown-result paths still require provider-specific reconciliation?
Which statements remain target design rather than current Runtime?

It does not authorize:

a provider call or search;
credential reveal or update;
webhook replay;
cron execution;
file-object read or cleanup;
generic outbox, queue or worker creation;
a Runtime or configuration change;
Phase implementation.

2. Refresh Result¶

2.1 Core provider executors remain stable¶

The current source comparison found the primary provider adapters below unchanged from the previous Integration baseline.

Provider/effect owner	Blob at previous baseline	Blob at current review	Result
`app/utils/QuickBooksOnlineClient.php`	`0bb4d1e13785cef130401c15f3efa5a4389100e5`	same	byte-identical
`app/systems/TMS/staff-time/quickbooks_time_sync_helper.php`	`8c0a63cc7d038ce8a62ca0c5297101e8c0610aa1`	same	byte-identical
`app/utils/GmailSender.php`	`f2dd8c51fd42eaed848eaad22d198ac52538eda7`	same	byte-identical
`app/utils/TelegramSender.php`	`f450b9bade24bc492da9608c9958eeecedd23f47`	same	byte-identical
`app/shared/storage/file_storage.php`	`ed6e44f93d53bf82f0174a5a8c3ef1acf37beeee`	same	byte-identical
`app/systems/TMS/ai-voice/voice_helper.php`	`3aab6b3368ee702c9bb326b3188bb76a384004fb`	same	byte-identical
`app/utils/GmailAppointmentWatchService.php`	`e36a82ef99ebd2e59a21d4c3157ba4d3d390e809`	same	byte-identical

The baseline-to-current repository comparison also did not identify changes in the inspected Voice Gateway, Gmail appointment intake/store, Telegram webhook/cron, root cron, Twilio callback or shared File API owner families.

Therefore:

QBO provider adapter semantics
QuickBooks Time provider adapter semantics
Gmail MIME/send adapter semantics
Telegram sender/suppression semantics
FileStorage EFS/S3 semantics
AI Voice local/provider state semantics
Gmail watch/history-sync semantics

remain governed by the previous source-authority packet unless environment evidence disproves them.

2.2 Caller and credential surfaces changed¶

The following current source additions materially affect Integration ownership even though the provider executors remain stable:

Tenant Provider Settings credential reveal/update
Loader Work Assignment Telegram notification
Loader Work Assignment / Clock / Break QuickBooks Time sync callers
Inventory Report Gmail delivery
Booking Inquiry Gmail delivery
APMT appointment provider caller/config family
Street Turn and Final Review handoffs that affect later provider/file work
Expanded request-body redaction for credential routes

The correct current classification is:

CORE PROVIDER EXECUTORS:
NO MATERIAL DRIFT LOCATED

CURRENT BUSINESS CALLERS:
EXPANDED / SOURCE-RECONCILED ADDENDUM REQUIRED

PROVIDER CREDENTIAL MANAGEMENT:
DIRECT CURRENT SOURCE CHANGE

CURRENT PROVIDER, CALLBACK, FILE, SCHEDULER AND CREDENTIAL STATE:
ENVIRONMENT EVIDENCE REQUIRED

3. Authority Separation Retained¶

No current source supports collapsing the following checkpoints:

Business Command committed
!= Effect requested

Effect requested
!= Provider invocation started

Provider invocation started
!= Provider accepted

Provider accepted
!= Local provider reference saved

Callback HTTP response
!= Callback business state applied

Local notification marker
!= Message delivered

Message delivered
!= Every intended target/part/attachment delivered

Credential configured
!= Module enabled
!= User authorized
!= Provider reachable
!= Provider call permitted

File object stored
!= T_FILE metadata committed
!= Business link complete
!= Object readable
!= Object cleanup complete

Cron endpoint returned success
!= Every eligible item processed

Worker/process alive
!= Backlog drained
!= Business complete

The current accepted decision also remains:

Generic DB outbox/retry/replay for all providers
= CANCELED

Provider-specific durable intent or receipt
= requires a separate owner and explicit approval

Shared Node.js process hosting
!= shared business/effect authority

4. Current Provider Credential Management¶

Current qa adds a first-class Admin Console path for allowlisted provider secrets.

4.1 Allowlist¶

Only entries from tenant_provider_config_definitions() whose declared valueType is secret are accepted by the managed credential helper.

Current provider-definition families include:

Gemini / legacy OpenAI image credential
Telegram
Gmail
QuickBooks Time
QuickBooks Online
APMT
Twilio / AI Voice

Arbitrary environment variables, non-secret provider settings, login credentials and unregistered keys are not accepted by this path.

4.2 Storage¶

Managed credentials are stored under:

SECRET.<CONFIG_KEY>

with the existing AES-256-GCM envelope:

enc:v1:<base64 envelope>

When a legacy plaintext row exists under the original key, a managed update:

writes/updates encrypted SECRET.<CONFIG_KEY>
-> wipes and soft-deletes the active legacy plaintext row
-> rereads stored metadata

Schema variants with or without VALUE_TYPE, UPDATED_AT and MODULE_ID remain supported.

4.3 Reveal¶

Current endpoint:

POST /platform/admin/tenants/{clientId}/credentials/{credentialKey}/reveal

Current server checks:

Admin Console access;
tenant administrator is limited to the effective tenant;
super-admin may target an explicitly selected tenant;
credential key is an allowlisted secret.

Current response behavior:

returns one decrypted credential value;
includes configured and updatedAt;
sets Cache-Control: no-store, private;
sets Pragma: no-cache;
route request body is excluded from API log context.

This is an explicit current credential exposure to an authorized administrator. It is not ordinary support diagnosis and must not be confused with safe availability metadata.

4.4 Update¶

Current endpoint:

POST /platform/admin/tenants/{clientId}/credentials/{credentialKey}

Current behavior:

rejects an empty replacement value;
accepts optional EXPECTED_UPDATED_AT;
returns a conflict when the stored revision changed;
encrypts the replacement;
retires a legacy plaintext row;
returns updated metadata, not the submitted plaintext.

The current helper error text refers to a separate removal action, but no current managed-credential removal endpoint or helper was located in the inspected source. Removal therefore remains NOT ESTABLISHED and must not be documented as a current operation.

4.5 UI and logging¶

The current Admin Console:

shows Configured · masked or Not configured;
shows last-updated metadata when available;
reveals one saved value on explicit Show;
clears another revealed value when switching;
clears credential fields on page exit;
uses replacement input plus Save and Cancel;
treats dedicated-deployment tenant management as read-only in the UI.

The inspected API route does not itself show a dedicated-deployment check. Current server-side enforcement for direct credential requests in a dedicated deployment therefore remains an evidence question.

Current generic API logging:

removes the body entirely for routes marked redactRequestBody;
masks config/credential/token/secret-style fields in ordinary log paths;
records request metadata rather than response body.

No provider-credential-specific immutable reveal/update audit ledger was located. Request logs are not a substitute for an accepted credential-access audit contract.

5. QBO Invoice¶

5.1 Provider adapter¶

QuickBooksOnlineClient is unchanged. The current source-confirmed operation remains Invoice creation; no source-confirmed provider search/reconciliation API was located in that client.

5.2 Local caller¶

Current AR Billing continues to use:

local conditional claim
-> QBO_SYNC_STATUS = SYNCING
-> provider createInvoice
-> local QBO ID / Doc Number / Sync Token save
-> SYNCED or ERROR result

The local claim token remains multiplexed through QBO_ERROR; it is not an immutable provider-attempt identity.

5.3 Current unknown-result boundary¶

provider accepted
+ response lost or local result save failed
-> local row may lack provider reference
-> blind replay can duplicate the invoice

The new credential path can replace QBO secrets but does not add provider reconciliation, duplicate detection, attempt history or stale-SYNCING policy.

QBO current-state evidence remains owned by:

RBR-QBO-001

and the Billing read-only preflight.

6. QuickBooks Time¶

6.1 Provider adapter¶

The QuickBooks Time sync helper is unchanged from the previous Integration baseline.

6.2 Expanded caller surface¶

Current Loader Work Assignment and Staff Time flows add or retain post-commit calls after local events such as:

JOB_START
JOB_END
CLOCK_IN
CLOCK_OUT
BREAK_IN
BREAK_OUT

The current pattern remains:

commit local T_STAFF_TIME_EVENT
-> invoke QuickBooks Time synchronously after commit
-> return/log provider-specific result

Therefore:

local Work Assignment transition succeeded
!= QuickBooks Time synchronized

and provider failure must not replay the local Loader transition.

6.3 Credential/config effect¶

QuickBooks Time can refresh OAuth tokens and write updated token configuration. That is a separate provider/config effect from the timesheet create/update/close operation.

The current managed credential UI can replace allowlisted QuickBooks Time secrets, but it does not reconcile active provider timesheets, token refresh outcomes or local staff-event mappings.

7. Gmail Outgoing¶

7.1 Sender¶

GmailSender is unchanged. It still performs synchronous Gmail send and can return provider Message/Thread identifiers.

An absent local attachment path can be skipped by the sender. Therefore caller validation remains required:

Gmail send success
!= every intended attachment included

7.2 Existing high-risk callers¶

The Billing refresh already source-reconciled:

BOL email
Packing List target/part email

Both remain synchronous and lack one universal durable outgoing-mail attempt ledger.

7.3 Expanded current callers¶

Current source also includes:

Inventory Report email¶

select report tabs/date/company
-> build temporary XLSX
-> require finalized Physical Inventory for physical tab
-> Gmail send to configured INVENTORY recipients
-> delete temporary attachment

A successful provider result does not by itself prove every requested report tab/row was correct or that a durable mail-result ledger exists.

Booking Inquiry email¶

group booking-needed rows by customer
-> resolve BOOKING_INQUIRY recipients
-> send one message per eligible customer
-> return per-customer SUCCESS / FAILED / SKIPPED_NO_RECIPIENT

This is a per-customer partial-result flow. Retrying the entire request after an unknown response can duplicate messages already accepted by Gmail.

7.4 Credential management¶

The current Provider Settings path can reveal/update allowlisted Gmail secrets and credential paths. It does not validate OAuth usability, mailbox ownership, send scope, watch status, provider connectivity or current message state.

8. Gmail Appointment Watch And Intake¶

The provider-specific durable workflow remains unchanged:

T_MAILBOX_WATCH_STATE
T_MAIL_MESSAGE
T_MAIL_REQUEST_ITEM

Current separation remains:

Pub/Sub notification accepted
!= history synchronized

history synchronized
!= message ingested

message ingested
!= request item approved

request item approved
!= appointment mutation completed
!= reply message completed

No source change in this refresh converts appointment mail state into a universal outgoing-mail or provider-attempt authority.

The new credential path can alter Gmail watch/send credentials. A successful credential update does not prove watch renewal, history-cursor continuity or callback delivery.

9. Telegram¶

9.1 Provider adapter¶

TelegramSender is unchanged. Delivery disabled remains a distinct result:

ok=true
suppressed=true

which means:

SUPPRESSED
!= SENT

9.2 Expanded Work Assignment caller¶

Current Work Assignment creation:

insert local planner assignment
-> attempt Telegram notification
-> preserve assignment when notification fails
-> return per-loader assignment and Telegram disposition

This is a correct separation of local assignment from notification, but the active Route representation does not persist the same typed notification-attempt metadata as the historical typed helper.

Current local evidence can include planner timestamps and returned notification result, but no common immutable Telegram attempt row was identified.

9.3 Other current callers¶

Current transload operations also include completion, next-queue and explicit Loader Telegram sends. Each owning business action must preserve its own local result before notification recovery.

9.4 Webhook and cron¶

Current Telegram webhook and secret-protected cron remain direct endpoint executions. No durable Telegram Update receipt/deduplication ledger or generic cron run/lease ledger was identified.

The managed credential UI can update Telegram token/webhook/cron secrets, but it does not establish webhook registration, update deduplication, cron scheduler state or provider reachability.

10. APMT Appointment Provider¶

Current provider definitions include:

APMT_TERMINAL_API_BASE_URL
APMT_TERMINAL_CONSUMER_KEY
APMT_TERMINAL_AUTHORIZATION_KEY
APMT_TERMINAL_TIMEOUT_SECONDS

Current YMS container routes include:

POST /yms/apmt-appointments/preflight
POST /yms/apmt-appointments/slots
POST /yms/apmt-appointments/create

The local preflight resolves current container/equipment-load/booking/delivery state before provider slot or create work.

Current boundary:

local eligibility preflight passed
!= provider slot available

provider appointment created
!= all local operational state advanced

The current provider credential UI can replace the APMT keys, but it does not prove the selected environment URL, terminal identity, slot semantics, callback behavior or duplicate-create reconciliation.

No provider-specific durable APMT attempt/receipt ledger was identified in the reviewed source.

11. AI Voice / Twilio / Gemini¶

11.1 Core source¶

The core AI Voice helper remains byte-identical to the previous Integration baseline.

Current local records remain:

T_AI_VOICE_CASE
T_AI_VOICE_CALL
T_AI_VOICE_TRANSCRIPT_SEGMENT

Current call flow remains local-intent first with explicit PROVIDER_UNKNOWN handling.

11.2 Callbacks¶

Twilio status/recording callbacks remain provider-specific handlers that validate and apply provider state. A separate durable callback-receipt ledger was not identified.

11.3 Voice Gateway¶

The Node Voice Gateway remains the owner of:

Twilio Media Stream;
Gemini Live session;
signed CTC tool calls;
transcript sequencing;
transcript filesystem outbox and bounded drain.

The transcript outbox remains provider/domain specific and host-local. It is not evidence that a generic worker queue exists or should be introduced.

11.4 Current compatibility and credentials¶

The current AI Voice helper still contains numeric Client 1 compatibility. Provider Settings now expose allowlisted Gemini/Twilio secrets to authorized administrators and can replace them.

Credential replacement does not prove:

Voice Gateway environment parity;
Twilio callback URL registration;
Gemini model/session compatibility;
HMAC secret parity;
transcript outbox readability/drain;
current call recovery.

12. File Object / Metadata / Link / Cleanup¶

The shared FileStorage owner is unchanged.

Current independent checkpoints remain:

FILE_OBJECT
FILE_METADATA
FILE_LINK
FILE_READABILITY
OBJECT_CLEANUP

Current operational callers can create temporary Gmail attachments, business-linked files and provider evidence. None of those outcomes collapse file state.

T_FILE row exists
!= object exists
!= object is readable
!= attachment was sent
!= object cleanup completed

No generic provider-worker change was located in this family.

13. Current Credential Resolution Versus Provider Execution¶

Runtime provider helpers commonly resolve:

tenant encrypted credential/config
-> environment fallback
-> provider default/non-secret config

The managed Admin Console path changes only the tenant-config source.

It does not change these non-implications:

credential configured
!= effective runtime source known

credential updated
!= current process cache refreshed

credential decrypted
!= provider authenticated

provider authenticated
!= effect authorized

module enabled
!= provider call permitted

Current environment evidence must distinguish:

encrypted tenant row;
legacy plaintext compatibility row;
deployment environment fallback;
default non-secret value;
missing/invalid source;
process/cache observation;
provider acceptance.

14. Current Effect Matrix Summary¶

Family	Local authority	Provider/effect call	Durable provider result	Unknown-result recovery
QBO Invoice	`T_TRANSACTION` QBO fields	synchronous create	final provider IDs stored on success; no immutable attempt history	provider search/manual finance reconciliation required before replay
QuickBooks Time	`T_STAFF_TIME_EVENT`	post-commit synchronous sync	provider-specific log/result; no common attempt ledger	reconcile external timesheet; never replay local event
Gmail BOL/Packing	business row + response	synchronous send	generally no universal durable send ledger	search Sent mail by bounded identity before resend
Gmail Inventory/Inquiry	report/input rows + per-result response	synchronous send	no common durable attempt ledger	target/customer-specific reconciliation
Gmail Appointment	watch/message/request-item tables	callback/history sync/reply	durable provider/domain workflow rows	history replay and request-item owner recovery
Telegram	planner/business row	synchronous send	caller-specific marker/result only	reread local business row; notify existing work only
APMT	equipment/load/booking state	synchronous preflight/slots/create	no provider attempt ledger identified	provider/local appointment reconciliation required
AI Voice	case/call/transcript tables	Twilio/Gemini/callbacks	provider SID/status and callback state	explicit provider-unknown and callback/recording recovery
Voice transcript	outbox JSON file	CTC transcript delivery	file remains until accepted	bounded drain
File object	object + `T_FILE` + link	EFS/S3 I/O	metadata and cleanup fields	object/link/readability reconciliation
Credential management	encrypted tenant-config row	no provider call	updatedAt/configured metadata	exact row reread; provider readiness separately verified

15. Current High-Risk Gaps¶

15.1 Credential reveal/update¶

no credential-specific immutable audit ledger located;
response contains plaintext by design for an authorized reveal;
no current managed removal route located;
dedicated UI read-only intent lacks source-confirmed route-level enforcement in the inspected handler;
optimistic concurrency depends on UPDATED_AT availability;
same-process/long-lived consumer cache behavior requires environment evidence;
current actor/tenant/role usage has not been observed.

15.2 Provider unknown results¶

QBO create accepted/local save missing;
Gmail accepted/local marker/result missing;
Telegram response ambiguous or notification suppressed;
QuickBooks Time external conflict/unknown;
APMT appointment create response lost;
Twilio call start/provider unknown;
callback accepted but local application uncertain;
file object stored but metadata/link failed.

15.3 Scheduler and callback operations¶

installed scheduler/timer definitions not read;
current last-run/last-success/backlog not read;
callback endpoint/provider registration not verified;
webhook duplicate/out-of-order populations not read;
Voice Gateway host/outbox state not read;
provider credentials/connectivity not tested.

16. Current Evidence Packages¶

Cross-provider¶

RBR-INTEGRATION-001
Current integration/provider/callback/scheduler surface

Credential¶

RBR-CREDENTIAL-001
Current allowlisted provider credential storage/access metadata

Existing provider/domain packages¶

RBR-QBO-001
RBR-FILE-001
RBR-MAIL-001
RBR-AUDIT-002
RBR-DEPLOY-001

All remain:

DEFINED OR UPDATED
NOT AUTHORIZED TO RUN BY THIS DOCUMENT
NOT RUN

17. Target Migration Implications¶

The current refresh reinforces the existing target design:

React support/operator UI
-> Next.js authenticated adapter
-> framework-independent TypeScript application owner
-> provider-specific adapter or approved worker
-> provider-specific attempt/receipt/reconciliation state

Do not migrate by:

moving every direct provider call into one generic queue;
treating credential rows as effect authorization;
replaying every UNKNOWN result;
copying raw secret values into a new database/service;
creating PHP and TypeScript dual provider writers;
allowing a worker to decide business completion;
treating callback HTTP success as business completion.

For each selected provider cohort, migration requires:

one business/effect owner
+ exact request identity
+ provider idempotency/reconciliation strategy
+ credential owner/reference
+ callback receipt/application policy
+ rollback that does not replay committed effects
+ old caller-zero

18. Current Disposition¶

Previous Integration semantic packet:
REMAINS VALID INPUT

Core provider executor freshness:
CONFIRMED FOR REVIEWED OWNERS

Current caller/effect inventory:
REFRESHED FOR NAMED FAMILIES

Managed provider credential source:
CURRENT SOURCE-RECONCILED

Generic outbox/replay policy:
REMAINS CANCELED

Current DB/config rows:
NOT READ

Credential values:
NOT READ

Provider state/connectivity:
NOT READ

Callbacks/schedulers/services:
NOT VERIFIED

File/object state:
NOT READ

Authenticated role behavior:
NOT RUN

M3:
NO

M4:
NO

Phase progress:
NONE

---¶

Source: docs/reconstruction/PLATFORM_INTEGRATION_PROVIDER_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.