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

deploy/deploy.sh

@@ -67,12 +67,20 @@ printf '%s' "$DB_ROOT_PASSWORD_VALUE" > "$SECRETS_DIR/db_root_password"
 # exact bug ENVIRONMENT-unset guards elsewhere in this file exist to prevent).
 HARDCOVER_API_TOKEN_VALUE="$(env_get "$ENV_FILE" HARDCOVER_API_TOKEN)"
 printf '%s' "$HARDCOVER_API_TOKEN_VALUE" > "$SECRETS_DIR/hardcover_api_token"
+# Same reasoning/pattern as Hardcover above — optional, written unconditionally.
+# Payments\HelcimConfig::is_configured() is false (and the gateway stays
+# unconfigured) until a real sandbox token lands in HELCIM_API_TOKEN.
+HELCIM_API_TOKEN_VALUE="$(env_get "$ENV_FILE" HELCIM_API_TOKEN)"
+printf '%s' "$HELCIM_API_TOKEN_VALUE" > "$SECRETS_DIR/helcim_api_token"
+if [[ -z "$HELCIM_API_TOKEN_VALUE" ]]; then
+  echo "    (HELCIM_API_TOKEN not set in ${ENV_FILE} — Helcim gateway will install but stay unconfigured)"
+fi
 # 644, not 600: the db/wordpress/cron containers read this as their own
 # (non-host-matching) container UID, e.g. www-data — chmod 600 made it
 # unreadable to them. The containing directory (700, above) is what
 # actually keeps other host users out; these just need to be world-readable
 # within that already-restricted directory.
-chmod 644 "$SECRETS_DIR/db_password" "$SECRETS_DIR/db_root_password" "$SECRETS_DIR/hardcover_api_token"
+chmod 644 "$SECRETS_DIR/db_password" "$SECRETS_DIR/db_root_password" "$SECRETS_DIR/hardcover_api_token" "$SECRETS_DIR/helcim_api_token"
 
 echo "==> building and starting ${ENVIRONMENT}"
 $COMPOSE up -d --build
@@ -104,7 +112,7 @@ echo "==> installing/activating theme (Blocksy — free; Book Store starter site
 $WP theme install blocksy --activate
 
 echo "==> installing/activating required plugins"
-$WP plugin install woocommerce redis-cache blocksy-companion --activate
+$WP plugin install woocommerce redis-cache blocksy-companion helcim-commerce-for-woocommerce --activate
 $WP plugin activate bookstore-core
 $WP redis enable || true