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
Cross-Process Handoff And Identity Matrix¶
- Status:
CURRENT P6-007 SOURCE-RECONCILIATION INPUT - Owns: cross-process handoff identity, completion evidence, next owner, partial-result and migration coupling view
- Does not own: atomic process semantics, role approval, Runtime implementation, Task status or migration authorization
- Context:
Context Appendix M - Portfolio:
OPERATING_MODEL_PROCESS_PORTFOLIO_AND_MIGRATION_MAP.md - Migration standard:
PROCESS_MIGRATION_READINESS_EXTENSION.md - Initial source baseline:
4fc2f5a893765fbb95e0a2bdcb971322b0ec9fc0
1. Purpose¶
Most migration failures occur at process boundaries rather than inside one page. This matrix makes the handoff contract explicit.
For every handoff it answers:
what completed
-> which stable identity is carried
-> which process becomes responsible
-> what the next owner must reread
-> what completion is not implied
-> how partial/unknown results are recovered
A visible row, toast, navigation link or copied reference number is not sufficient handoff evidence unless the owning process contract says so.
2. Identity Rules¶
- Carry stable same-tenant IDs/UUIDs, not display labels alone.
- Keep source and target process identities distinct.
- A composite correlation ID may group work but does not transfer mutation authority.
- A provider ID, file ID, print result or message ID is a separate effect identity.
- A derived report row is not a write identity.
- Unknown/partial completion requires rereading the source owner before retry.
- React route parameters and browser state are transport identities, not business authority.
- During migration, PHP and TypeScript use the same authoritative business identity and exactly one writer.
Common identity classes¶
| Identity class | Examples | Use |
|---|---|---|
| Business work | Commercial Order, Load, Transload, Booking, Delivery | stable process subject |
| Execution child | Loading Planner, Yard Queue, Driver Log, Scale Ticket | child process execution identity |
| Inventory | Inventory Lot, Allocation, Ledger event | quantity/weight/provenance authority |
| Finance | Transaction, Transaction List, Invoice group | local accounting authority |
| Document/file | File UUID, stored object, generated snapshot | separate output/evidence identity |
| Provider | Gmail message, QBO invoice, Telegram result | external effect/reconciliation identity |
| Process correlation | Process instance/correlation/causation ID where available | observability only unless contract says otherwise |
3. CTC Request, Planning And Execution Handoffs¶
| From process / event | Completion evidence before handoff | Stable carried identity | To process / owner | Required target reread | Not implied | Partial/unknown recovery |
|---|---|---|---|---|---|---|
| Appointment email review | accepted request branch and scheduled transload/appointment exists | mailbox/message/request-item ID + T_TRANSLOAD ID/UUID |
PROC-TMS-INBOUND-PLANNING |
planning-board row for exact transload/date | customer reply sent; check-in, planner or assignment exists | reread request item and transload before retry; provider reply remains separate |
| Manual appointment | saved same-tenant appointment/transload | T_TRANSLOAD ID/UUID + business reference |
PROC-TMS-INBOUND-PLANNING |
exact planning-board/detail row | email review or provider evidence exists | search by stable ID/reference and inspect duplicate risk before create |
| Inbound check-in/plan | plan/assignment records reread | T_TRANSLOAD ID/UUID + T_LOADING_PLANNER ID |
Loader execution within PROC-TMS-INBOUND-PLANNING |
loader-assignment/current-job row | physical work started | refresh assignment and staff context; do not create duplicate planner |
| Loader Start | authoritative planner/transload state and staff event reread | transload + planner + assigned user | Loader Complete | current job and start time | job completed, inventory exists or Yard work exists | reread current job; reconcile duplicate/unknown Start before retry |
| Loader Complete: Reload/Transload | operational TRANSLOADED/SPARE, out time, final metrics and finished planner |
transload ID/UUID + planner ID + final quantity/weight | PROC-WMS-FINAL-LOADING-REVIEW-CTC |
Pending review row and derived readiness | review confirmed; Source/Leftover reconciled; billing complete | review exact transload/planner/ledger; correct source owner only |
| Loader Complete: Unload | operational completion and inventory/yard effects reread | transload + created/updated lot + location/yard identity | Inventory/Yard owners | exact lot, placement and queue/location rows | Final Loading Review applies; downstream process complete | reread child owners independently; no composite rollback |
| Loader completion with Telegram failure | business completion committed | transload/planner/staff identity + missing message effect | notification recovery/manual fallback | completion row first, then notification state if available | business work failed | retry only notification when safe; do not rerun completion |
| Inbound terminal Yard requirement | active Yard queue/location work exists | transload/equipment/load + Yard queue ID | PROC-YMS-YARD-DISPATCH |
queue and actual Yard location | Yard move or Driver delivery completed | resume Yard child only; do not reopen inbound completion |
Migration note¶
The Planning-to-Loader-to-Review chain should not be migrated as one giant transaction. Each atomic transition must retain separate owner, readback and recovery.
4. CTC Final Loading Review And Inventory Handoffs¶
| From process / event | Completion evidence | Stable carried identity | To process / owner | Required reread | Not implied | Recovery |
|---|---|---|---|---|---|---|
| Completed Reload/Transload | finished planner + operational completion + final metrics | transload ID/UUID + planner ID | PROC-WMS-FINAL-LOADING-REVIEW-CTC |
review queue/detail and active ledger summary | ready/confirmed review | fix owning data/source; do not force status |
Review SOURCE_REQUIRED |
positive difference and missing/mismatched source ledger | transload + required qty/weight + customer/commodity | PROC-WMS-BALE-INVENTORY-ADJUSTMENT-CTC |
eligible source lot, balance, planned/actual context | source selected or consumed | reread source availability and ledger before apply/retry |
| Extra Source applied | lot balance and active EXTRA_APPLIED ledger event reread |
source lot UUID + ledger UUID + transload ID | Final Loading Review | derived review readiness | review confirmed | if uncertain, reread lot/ledger; void only through adjustment owner |
Review LEFTOVER_REQUIRED |
negative difference and missing/mismatched leftover evidence | transload + required qty/weight + actual location | Bale Inventory Adjustment | created leftover lot + ledger/source relation | review confirmed or warehouse placement accepted beyond owner | reread lot/ledger/location; preserve correction provenance |
| Leftover created | leftover lot/ledger and location reread | lot UUID + transload ID + location ID | Final Loading Review / Warehouse visibility | review readiness and current location | later shipment/billing complete | correct through lot/ledger/location owner, then reread review |
| Weight Review | equal quantity, differing weights, no accepted reason | transload + current inbound/final weight | Final Loading Review weight command or owning metric source | exact current values after action | Confirmed | stale expected value -> full reread; no blind retry |
| Final Confirm | conditional Pending-to-Confirmed update and exact review reread | transload ID/UUID + confirmation actor/time | Daily/Inventory reconciliation | confirmed review + active evidence | inventory movement, billing, document or provider complete | response loss -> reread review; do not repeat source/physical work |
| Reopen | persisted state rereads Pending | transload ID/UUID + retained metadata | metric/source/leftover correction owner | current metrics, ledger, review state | prior effects were reversed | perform only required owner correction, then reconfirm |
| Source/Leftover Void | reversal/readback excludes prior active evidence | lot/ledger/transload identity | Final Loading Review | derived state becomes blocked/ready as appropriate | review automatically reopened | if confirmed, Reopen first; preserve reversal provenance |
5. CTC Yard And Driver Handoffs¶
| From process / event | Completion evidence | Carried identity | To | Required reread | Not implied | Recovery |
|---|---|---|---|---|---|---|
| Office Yard request | queue row saved and schedule/target context visible | Yard queue ID + equipment/load/delivery IDs | Yard Driver claim | queue and assignable current state | physical move occurred | search exact queue/entity; avoid duplicate active queue |
| Yard claim | queue owner/claimed state reread | queue ID + claiming user | Yard movement/closing | queue, source/target location and actual physical context | move completed | unclaim/cancel only through owned path; inspect concurrency |
| Non-pull Yard complete | queue completion + actual location reread | queue/equipment/location | daily reconciliation or conditional Driver | queue absence/completion and Yard Map | Driver delivery complete | queue-after-clear/location mismatch handled by Yard owner |
| Pull Out closing | scale/closing and queue completion checkpoints reconciled | queue + scale ticket + equipment/location | conditional Driver or external release | each child record independently | one atomic all-or-nothing commit | partial closing -> reread scale, queue, location before retry |
| Yard-to-Driver eligibility | applicable active Yard blocker removed and delivery is still assigned/eligible | equipment/load/delivery + former queue context | PROC-TMS-DRIVER-DELIVERY |
driver list/current log/delivery row | Driver Start accepted | if delivery missing or queue remains, keep partial handoff |
| Driver Start | driver-owned status/log reread | delivery ID + driver log + assigned user | delivery execution | current delivery and evidence state | pickup/drop-off/yard complete | reread before retry; do not infer from button state |
| Driver Finish | delivery status/times and required evidence reread | delivery + file/photo + equipment/yard context | daily close / Yard follow-up / billing | delivery, Yard queue/location and files separately | Yard queue-after-clear or provider effect complete | resume first missing child only; Undo is not full rollback |
| Driver Trouble/Undo | current child states inspected | delivery/equipment/Yard/file IDs | Office exception owner | every affected owner | exact prior state restored | manual reconciliation; preserve partial effects |
6. CTC Billing, File And Provider Handoffs¶
| From process / event | Completion evidence | Carried identity | To | Target reread | Not implied | Recovery |
|---|---|---|---|---|---|---|
| Source AP/AR transaction save | exact transaction/header/lines reread | transaction ID/UUID + source relation | local close/billing review | current transaction and lines | invoice confirmed or provider sent | reread after ambiguous response; avoid duplicate source transaction |
| AR preview | reviewed candidate/group/source totals | candidate/source IDs + proposed invoice group | AR Confirm | preview and current source rows | local mutation occurred | stale source -> rebuild preview; do not confirm old totals |
| Local AR Confirm | all local rows/transaction state reread | local transaction/invoice/group IDs | QBO delivery and document/file processes | local source before provider action | QBO invoice exists, email sent or file readable | provider/file failures do not recreate local transaction |
| QBO send | provider ID plus local provider-link/status reread | QBO invoice ID + local transaction/group IDs | billing reconciliation | provider and local sides | customer receipt or document email | unknown provider result -> search provider first; no blind resend |
| File upload | object exists and T_FILE relation reread |
file UUID/object path + business relation | document consumer | readable object and intended link | email/provider delivery | partial object/link -> reconcile storage and DB separately |
| BOL email | accepted provider response and, when available, sent-message identity | transload/file/recipient/message IDs | billing/document close | provider evidence and source files | local billing complete | unknown send -> provider search/receipt before resend |
| Packing-list email | target/part-level provider outcomes | booking/file/target/part identities | billing/document close | every selected target/part result | all parts sent because one succeeded | reconcile partial targets; no full replay without evidence |
| Composite billing close | every applicable local/provider/file/email child reconciled | child identities and manual disposition | daily/period close | child owners | one stored composite status exists | carry first unresolved child and owner |
7. MK Commercial, Purchase And Inventory Handoffs¶
| From process / event | Completion evidence | Carried identity | To | Target reread | Not implied | Recovery |
|---|---|---|---|---|---|---|
| Commercial Purchase save | same-tenant header/lines exact reread | commercial order/item IDs + number | Inbound Purchase | exact commercial reference and item context | inbound receipt or lot exists | search by ID/number before retry; do not infer execution status |
| Commercial Sales save | same-tenant header/lines exact reread | commercial order/item IDs + relation | Outbound Sales | exact sales relation | Booking/allocation/shipment exists | reread relation; do not force status |
| Inbound Purchase save | header/items exact reread | load/order/item IDs + commercial pointer | receipt execution / optional Scale | current order/items and branch requirements | physical receipt or inventory lot exists | ambiguous save -> full child reread before retry |
| No-scale receipt completion | eligible order completion + created transload/lot readback | order/item/transload/lot IDs | Inventory / optional Allocation | exact lot quantity/weight/source/location | Scale occurred or allocation exists | reconcile partial materialization by child owner |
| Physical Scale checkout | ticket stages reread | scale ticket + order/item/link identity | Inbound finalize or Sales sync | ticket and owner process finalization separately | owner finalization succeeded | keep physical ticket evidence; resume missing owner only |
| Inbound materialization | current lot and source relation reread | lot UUID + source order/item/transload | Inventory/Allocation | lot remaining quantity/weight and placement | outbound demand fulfilled | fix lot/source owner; no inferred allocation |
| Doortrade assistance | reviewed extracted proposal only | document/input context | human Inbound command | actual saved order/result | AI output is approved or persisted | human review; provider failure cannot fabricate order |
8. MK Sales, Booking, Allocation And Fulfillment Handoffs¶
| From process / event | Completion evidence | Carried identity | To | Target reread | Not implied | Recovery |
|---|---|---|---|---|---|---|
| Outbound Sales save | header/items exact reread | outbound load/item IDs + commercial relation | Booking/Allocation/Schedule | exact outbound demand and references | inventory reserved or container assigned | search current demand; avoid duplicate line/create |
| Booking save/link | booking and outbound pointer exact reread | booking ID/UUID + outbound order + equipment/container | Allocation / Packing / Documents | each child source | shipment, packing or document complete | ambiguous save/clone -> reread booking and linked children |
| Schedule view | derived inbound/outbound projection | owning order/item IDs | owning Inbound/Outbound or Allocation command | source owner detail | Schedule is an independent state owner | correct source owner, not projection |
| Allocation apply | lot balance, allocation row and outbound demand reread | lot UUID + allocation ID + outbound item | outbound fulfillment / Trade | lot, allocation, demand and bridge | shipment complete or reversal supported | unknown result -> reread all three; no invented unallocate |
| Allocation failure | no complete basket result or ambiguous partial | basket identities | Allocation recovery owner | every lot/allocation/demand row | safe retry | stop on overdraw/unknown; manual recovery if reversal absent |
| Outbound cost save | selected AP transaction and lines reread | outbound order + transaction ID | Trade Summary / accounting | cost transaction and derived result | billing closed or file preserved | replace/delete through owner; reconcile sibling/file collision |
| Packing rate save | exact outbound item rate reread | booking + outbound item ID | Packing output / Trade | source rate and rendered output | autosave display proves persistence | failed/pending blur state -> reread before print/retry |
| Trade Summary read | source-class detail reconciled | equipment/order/transaction identities | human review/management | source owners, not report row | settlement or close write occurred | trace discrepancy to source class; report remains read-only |
9. MK Conditional Documents And Outputs¶
| From | Completion evidence | Carried identity | To | Required reread | Not implied | Recovery |
|---|---|---|---|---|---|---|
| Booking/Outbound current source | current source rows reconcile | booking/order/equipment IDs | Packing Document | rendered values against source | durable document exists | source changed -> regenerate; print is nondurable |
| Purchase order source | current purchase/item/company values | order/item IDs | Local Invoice output | calculated/rendered values | invoice persisted/sent | re-open source and regenerate |
| Booking source | current booking/sales reference | booking ID | Booking Confirmation | rendered source precedence | submission or receipt | regenerate after source correction |
| Sales order source | current sales/equipment/weight values | order/equipment IDs | Sales Weight Ticket output | source and physical-scale distinction | physical Scale ticket exists | correct source; do not infer physical event |
| Export Brokerage request | generated child inventory reread | logical job/source doc + generated child IDs | child reconciliation/cancel | every generated child and balance | all-or-nothing provenance exists automatically | use owned compensating cancel; do not create duplicate job |
Document render/print is not durable completion unless a later approved process creates a stored snapshot, acknowledgement or provider effect.
10. Migration Coupling Classification¶
| Coupling | Meaning | Example | Migration rule |
|---|---|---|---|
| Strong identity handoff | target cannot operate without source stable ID | transload -> Final Loading Review | migrate/query shared contract first |
| Independent checkpoint | later effect may fail without reversing source | AR Confirm -> QBO | use outbox/worker or explicit reconciliation |
| Derived projection | target reads multiple owners but does not mutate them | Trade Summary | read-only reference candidate |
| Conditional child | child runs only when physical/business condition applies | Scale, documents | do not make universally mandatory |
| Compatibility mirror | duplicated field supports legacy read | transload warehouse location | identify final owner and caller-zero |
| Cross-module guard | one owner protects another owner's mutation | Final Review mutable guard in TMS/BMS | replace with public policy/application contract |
| Manual reconciliation | no stored composite status | CTC daily, MK order-to-packing | preserve user disposition without inventing transaction |
11. Handoff Acceptance Checklist¶
Before a process reaches M3/M4, every material handoff must answer:
- [ ] source process ID and version;
- [ ] target process ID and version;
- [ ] trigger and source completion evidence;
- [ ] stable carried identity;
- [ ] tenant/profile and role boundary;
- [ ] target authoritative reread;
- [ ] what is not implied;
- [ ] duplicate/stale/concurrent behavior;
- [ ] timeout/unknown-result recovery;
- [ ] correction/reopen/void/reversal relationship;
- [ ] provider/physical/file checkpoint where applicable;
- [ ] current PHP callers and target TypeScript contract;
- [ ] one-writer cutover and rollback;
- [ ] Wiki/manual wording and next owner.
12. Priority Gaps For P6-007¶
- Confirm Final Loading Review as a registered process and update CTC daily composition.
- Reconcile exact role/menu/API ownership for CTC Planning, Review, Yard, Driver and Billing.
- Define stable correlation between loading completion, inventory lot/ledger and Final Review.
- Resolve Yard Closing partial-scale/queue duplication semantics.
- Resolve QBO/email/file provider identity, unknown-result and retry owners.
- Define MK Commercial-to-Inbound/Outbound relation and status policy.
- Define allocation reversal/concurrency policy before migration.
- Separate physical Scale completion from owner-process finalization in every packet.
- Classify output/print processes as nondurable until Product defines durable completion.
- Add target-role Wiki procedure and recovery coverage after process-owner acceptance.
---¶
Source:
docs/processes/CROSS_PROCESS_HANDOFF_AND_IDENTITY_MATRIX.md— ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.