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 Source Addendum¶

Status: CURRENT SOURCE-RECONCILED ADMIN/SUPPORT DRAFT / NOT FIELD-ACCEPTED
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
Effect matrix: PLATFORM_INTEGRATION_PROVIDER_CURRENT_EFFECT_MATRIX_2026-08-08.md
Read-only preflight: RBR-INTEGRATION-001-READONLY-CURRENT-SURFACE-PREFLIGHT.md
Phase implementation: USER HOLD

1. Purpose¶

Use this addendum when a local business action and an external Provider/File effect do not show one clearly completed result.

Primary rule:

Stop replay
-> identify exact tenant/business source
-> reread local authority
-> classify provider/file/callback state
-> resume only the missing owner step

Do not repair an Integration problem by recreating the business record that requested the effect.

2. Operator Roles¶

Role	Responsibility
Business operator	report exact action, source record and visible result; stop repeat actions
Module owner	reread business state and decide whether an effect is still required
Provider owner	perform separately authorized provider search/read or credential lifecycle action
Support operator	correlate request/local/provider/file evidence without exposing secrets
Credential owner	replace approved credential and verify metadata/revision; never disclose in ticket or Wiki
Deployment/service owner	verify process, scheduler, callback or host-local outbox state
Finance owner	accept QBO reconciliation, duplicate risk and link-existing disposition

A support operator does not become the business or provider owner merely because the operator can see diagnostics.

3. Universal Investigation Sequence¶

Stop the repeated action.
Record environment, source SHA, tenant, actor/subject, page/API, record ID and time window.
Reread the authoritative local business row.
Reread caller-owned local effect markers and current provider status fields.
Decide whether the provider request definitely did not start, definitely failed, may have been accepted, or is unknown.
Use separately authorized provider/file/service read evidence when needed.
Classify:

NOT_REQUIRED
SUPPRESSED
LOCAL_PENDING
PROVIDER_ABSENT_RETRY_ALLOWED
PROVIDER_ACCEPTED_LOCAL_PENDING
SUCCEEDED
FAILED_DEFINITE
PARTIAL
UNKNOWN
MANUAL_REVIEW
COMPENSATION_REQUIRED

Resume only the missing owner step.
Reread local and provider/file evidence after recovery.
Record the result without copying sensitive payloads.

4. Provider Credential Management¶

4.1 Safe current behavior¶

Current Admin Console supports one allowlisted provider secret at a time.

Show
= authorized server-side decrypt and one-value response

Save
= encrypted replacement of SECRET.<KEY>
+ optimistic revision check
+ retirement/wipe of active legacy direct-key row

Show or Save
!= provider connectivity test

4.2 Before revealing¶

Confirm:

exact effective tenant;
intended physical actor and subject;
provider/key is in the managed definition registry;
the task genuinely requires the plaintext value rather than configured/not-configured metadata;
no screen share, recording, log export or unrestricted ticket capture is active.

Do not reveal merely to check whether the credential exists. Use masked configured/revision metadata.

4.3 During reveal¶

expose one credential only;
do not paste it into chat, ticket, Wiki, email, log or command history;
do not inspect browser storage or network response outside the authorized session;
hide it immediately after the required use;
leave or reload the page to clear the current display.

4.4 Replacement¶

Before Save:

verify exact key and tenant;
record current safe updatedAt revision;
validate that the new value came from the approved credential owner;
understand which services/processes consume it;
define rollback/previous-credential recovery outside Repository content.

After Save:

reread configured/revision metadata;
do not infer provider success;
perform any provider connectivity check only as a separately approved action;
observe long-lived services/processes for stale cached credentials when relevant.

4.5 Missing response¶

Save response missing
-> reread safe revision/configured metadata
-> compare expected/current updatedAt
-> do not submit repeatedly

4.6 Removal gap¶

A managed remove route/helper was not located in the reviewed current source.

Do not:

save an empty string;
directly clear the DB row;
soft-delete the row manually;
misuse a general tenant-config editor.

Escalate as an open credential-lifecycle contract.

5. QBO Invoice Recovery¶

Local states¶

READY
SYNCING
SYNCED
ERROR
VOIDED

Missing response or stale `SYNCING`¶

Reread the exact AR transaction and provider-reference fields.
If an Invoice ID exists, perform a separately authorized provider lookup by that ID.
If the local reference is absent but provider acceptance is possible, search using the approved narrow identity and time window.
Classify provider found, absent, rejected, multiple or unknown.
If found, link/reconcile the existing Invoice; do not create another.
Finance owner accepts duplicate-risk and manual-review outcomes.

Never use local ERROR alone as proof that QBO has no Invoice.

6. QuickBooks Time Recovery¶

Local Staff Time remains authoritative.

local CLOCK/BREAK/JOB event
!= external timesheet state

When sync fails or returns manual review:

Reread the local event sequence and effective Staff user.
Verify provider-user mapping metadata.
Read the exact provider timesheet under separate authorization.
If the provider has an unrelated active timesheet, do not close it automatically.
Preserve the local event; classify provider projection separately.
Resume only the required provider operation after conflict resolution.

Do not repeat Loader Start/Complete or local Clock Out to fix external time.

7. Gmail Recovery¶

BOL¶

Use exact:

Transload/reference;
intended recipient;
subject;
narrow send window;
expected Scale PDF and linked-file names.

If the response is missing, search Sent mail before resend.

Packing List¶

Classify each target and part independently.

Customer part 1 = sent
Customer part 2 = unknown
Inspector = not attempted

Do not repeat BOTH or all parts. Resume only a proven missing target/part.

Inventory Report¶

verify selected tabs and date range;
verify physical tab was finalized when included;
identify the generated attachment name;
provider-read before regenerating/resending after response loss.

Booking Inquiry¶

Each company group is an independent child. Preserve successful groups and retry only a proven missing group.

Gmail Watch / Intake¶

Pub/Sub notification
!= message ingested
!= request approved
!= appointment changed
!= reply sent

Use durable history cursor/message/request-item state. A history gap requires controlled replay from the cursor, not broad message reprocessing.

8. Telegram Recovery¶

Work Assignment¶

Assignment committed + Telegram failed
-> Assignment remains valid
-> do not create another Assignment

Use the existing row and approved manual or notification recovery.

Suppressed delivery¶

suppressed = intentional no-send
suppressed != sent

Show the state honestly and apply the tenant's manual-notification procedure.

Manual dispatch / completion / next queue¶

Reread the exact Planner/Transload/Staff state and local marker before another send.

Webhook¶

Because a universal durable Telegram Update receipt ledger was not established, inspect current domain state and duplicate identity before replay or manual correction.

Break cron¶

A successful endpoint/process response does not prove every eligible Break was processed. Record child dispositions and current Break/Staff state.

9. APMT Appointment Recovery¶

Before provider call:

exact Equipment Load and Container;
Pickup/Return Booking context;
Delivery status/type;
newer-load conflicts;
appointment source/type/date/slot;
tenant credential/config metadata.

After timeout or missing response:

provider appointment search/read
-> found: link/reconcile existing appointment
-> absent: retry allowed only after owner acceptance
-> multiple: manual review
-> unknown: no repeat create

Do not create a second terminal appointment solely because the browser did not receive a response.

10. AI Voice / Twilio / Gemini Recovery¶

Start call¶

Local call intent/request key is created before provider start. PROVIDER_UNKNOWN is an explicit state.

Do not create a second call while the first result is unknown.

Callback¶

Verify provider signature, exact Call identity, current status and callback order. Provider retry should handle endpoint failure; manual replay requires separate authorization.

Recording cleanup¶

Recording delete failure is a cleanup problem, not a reason to delete the local call or transcript. Retain retry/error state.

Transcript outbox¶

The Voice Gateway filesystem outbox is host-local and provider-specific.

Investigate:

directory ownership/permissions;
count, oldest age and total size;
gateway/drain release identity;
CTC endpoint acceptance logs.

Do not read transcript bodies during broad support inventory.

11. File/Object Recovery¶

Classify independently:

object
metadata
business link
readability
cleanup

Examples:

object stored, DB transaction failed;
metadata/link exists, object unreadable;
business row deleted, object cleanup pending;
two active metadata rows reference the same locator;
object readable but linked to the wrong business record.

Do not solve every case by delete and reupload. Resume the missing owner step or perform approved cleanup/compensation.

12. Scheduler, Callback And Service State¶

For any cron, service, gateway or callback:

process active
!= ready

endpoint 200
!= every item processed

callback accepted
!= domain state applied

host-local backlog empty
!= all provider effects reconciled

Record source/config identity, run user, schedule/timezone, last result, overlap control, log ownership and alert owner.

Do not restart or edit a service during a read-only investigation.

13. Escalation Packet¶

Environment/host/source SHA:
Tenant/profile:
Actor/subject/role:
Business source and exact ID:
Provider/file family:
Local state and revision:
Provider reference presence:
Callback/watch/run state:
Observed result:
Unknown/partial boundary:
Repeated actions already attempted:
Sensitive-data handling confirmation:
Provider/file/service read required:
Recommended next owner step:
Prohibited replay:

14. Current State¶

Current source and effect mapping:
COMPLETE

Current credential authority:
DOCUMENTED

Read-only package:
DEFINED

Current environment/provider/service/file evidence:
NOT RUN

Field/support acceptance:
INCOMPLETE

M3:
NO

M4:
NO

---¶

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