. A numeric-keyed * document would duplicate the uuid-keyed row client-side. */ final class Order_Document { /** * Read the order's stable uuid from a payload's meta, failing closed. * The IDENTITY payload must be the full serialized payload (the serializer * stamped it via the woocommerce_pos_sync_serialized_order filter). * * @param array $identity_payload The FULL serialized payload (uuid source of truth). * @param int $order_id The numeric Woo order id (for the error message). * * @throws Order_Uuid_Exception when the payload carries no valid uuid. */ public static function require_uuid( array $identity_payload, int $order_id ): string { $uuid = Pos_Uuid::read_valid_uuid_from_meta( $identity_payload['meta_data'] ?? array() ); if ( '' === $uuid ) { throw Order_Uuid_Exception::for_order( $order_id ); } return $uuid; } /** * Build the complete order document envelope. * * @param array $identity_payload The FULL serialized payload (uuid source of truth). * @param array $client_payload The payload actually shipped. * @param int $order_id The numeric Woo order id (for the uuid guard's error message). * @param string $revision The document revision (index row's, or the canonical fallback). * @param array $checkpoint The per-document checkpoint (updatedAtGmt/orderId/revision/sequence). * @param bool $partial Whether $client_payload is a partial fieldset. * @param string $source 'custom-pull' | 'skeleton' | 'snapshot'. * * @throws Order_Uuid_Exception when the identity payload carries no valid uuid. */ public static function build( array $identity_payload, array $client_payload, int $order_id, string $revision, array $checkpoint, bool $partial, string $source ): array { return array( // ADR 0029 decision 6: no per-document wooOrderId key — the client derives // remote identity from payload.id at its ingest edge. The deletes channel // (a SEPARATE response key) still speaks numeric order ids. 'id' => self::require_uuid( $identity_payload, $order_id ), 'payload' => $client_payload, 'sync' => array( 'revision' => $revision, 'checkpoint' => $checkpoint, 'partial' => $partial, 'source' => $source, ), 'local' => array( 'dirty' => false, 'pendingMutationIds' => array(), ), ); } }