Week 3: checkout + order engine (Helcim gateway, pre-charge recheck, order state machine)

Wires up Helcim's free WooCommerce plugin (installed inert until a sandbox
token exists) alongside a synchronous pre-charge supplier/margin recheck
and a fraud-check hook, both firing immediately before payment per the
Appendix B immediate-charge decision. Adds a custom order-status sequence
(bsc-ordered/bsc-shipped/bsc-exception) as the state machine and review
queue, an Action Scheduler-backed supplier-submission job with idempotency
guards, a bsc_order_audit ledger, and two new transactional emails.

Hooks both the classic WooCommerce checkout actions and the real
woocommerce_checkout_validate_order_before_payment hook, since this site's
storefront runs WooCommerce Blocks/Store API rather than the classic
shortcode checkout (confirmed by reading WooCommerce's own source after
the classic hooks turned out not to fire in live testing).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D2gmgaDVXcRGCwLfdXQajD

docker-compose.yml

@@ -22,11 +22,11 @@
 # bind mount never touches the file's content, only its path, so it's
 # immune to this entirely.
 #
-# The remaining supplier/payment keys below are still passed the old ${VAR}
-# way and remain exposed to the same class of bug — nothing consumes them
-# yet (bookstore-core is still a stub for those), so when that code is
-# written it should read `_FILE` variants the same way HARDCOVER_API_TOKEN
-# now does below.
+# The remaining supplier keys below are still passed the old ${VAR} way and
+# remain exposed to the same class of bug — nothing consumes them yet
+# (bookstore-core is still a stub for those), so when that code is written
+# it should read `_FILE` variants the same way HARDCOVER_API_TOKEN and (as
+# of Week 3) HELCIM_API_TOKEN now do below.
 x-bookstore-env: &bookstore-env
   WORDPRESS_DB_HOST: db
   WORDPRESS_DB_NAME: ${DB_NAME}
@@ -45,10 +45,10 @@ x-bookstore-env: &bookstore-env
   BOOKSRUN_API_KEY: ${BOOKSRUN_API_KEY:-}
   INGRAM_API_KEY: ${INGRAM_API_KEY:-}
   INGRAM_ACCOUNT_ID: ${INGRAM_ACCOUNT_ID:-}
-  HELCIM_API_TOKEN: ${HELCIM_API_TOKEN:-}
   HELCIM_ACCOUNT_ID: ${HELCIM_ACCOUNT_ID:-}
   MAILERLITE_API_KEY: ${MAILERLITE_API_KEY:-}
   HARDCOVER_API_TOKEN_FILE: /run/secrets/hardcover_api_token
+  HELCIM_API_TOKEN_FILE: /run/secrets/helcim_api_token
 
 services:
   db:
@@ -98,6 +98,7 @@ services:
       - ./wp-content/mu-plugins:/var/www/html/wp-content/mu-plugins
       - ./secrets/${ENVIRONMENT:?ENVIRONMENT must be set}/db_password:/run/secrets/db_password:ro
       - ./secrets/${ENVIRONMENT:?ENVIRONMENT must be set}/hardcover_api_token:/run/secrets/hardcover_api_token:ro
+      - ./secrets/${ENVIRONMENT:?ENVIRONMENT must be set}/helcim_api_token:/run/secrets/helcim_api_token:ro
     healthcheck:
       # No HTTP endpoint to hit directly — php-fpm speaks FastCGI on 9000,
       # not HTTP, and this image has no `nc`. bash's /dev/tcp redirection
@@ -152,6 +153,7 @@ services:
       - ./docker/cron/entrypoint.sh:/usr/local/bin/cron-entrypoint.sh:ro
       - ./secrets/${ENVIRONMENT:?ENVIRONMENT must be set}/db_password:/run/secrets/db_password:ro
       - ./secrets/${ENVIRONMENT:?ENVIRONMENT must be set}/hardcover_api_token:/run/secrets/hardcover_api_token:ro
+      - ./secrets/${ENVIRONMENT:?ENVIRONMENT must be set}/helcim_api_token:/run/secrets/helcim_api_token:ro
 
 volumes:
   db_data: