Turboship v1.2.0 Release Notes

This release represents a significant milestone in the development of Turboship, compiling 194 commits since version v1.1.482 (released April 15, 2026). The scope of this release spans major architectural refactoring, physical sandbox isolation, robust address validation workflows, a custom fraud rules engine, and transition to a strictly-typed codebase utilizing Effect schema and static build-time pipeline linters.

Release Metadata

1. Executive Summary

Over the last 7 weeks, the Turboship engineering team has focused on three core objectives:

1. Security & Sandbox Isolation: Eliminating sandbox/production environment bleed by provisioning physically separate AWS accounts and hardening identity, secrets management, and custom domain CORS boundaries.
2. Operational Resilience & Automation: Automating order address correction, validating customer addresses before shipping costs are incurred, and implementing a highly-configurable custom fraud evaluation engine.
3. Build-Time Quality Controls: Completely excising Zod in favor of Effect Schema, implementing a static linter to catch JSONPath mapping errors in Step Functions before deployment, and introducing a deterministic code thumbprinting system.

2. Core Epics & New Features

2.1 Custom Fraud Detection Rules Engine

A fully configurable custom fraud rules engine has been designed to supplement Shopify's native fraud warnings. The rules engine evaluates incoming orders and flags them based on risk factors, pausing workflow orchestration for manual review or secondary verification.

• Risk Factors Analyzed:
  1. Billing ≠ Shipping Mismatch: Flags if the billing address/email differs from the shipping address/email.
  2. Drop Ship Detection: Detects if the order is drop-shipped by comparing the shipping destination against the customer’s default default address.
  3. Unestablished Customer: Flags if the customer account is less than 6 months old or has completed $\le 1$ order.
  4. High Order Total: Flags order totals exceeding a configurable dollar threshold (default $500).
  5. High Spending Velocity: Compares customer order totals in the last 180 days against a configurable velocity threshold (default $1000).
• Workflow Integration: The engine pauses the state machine on high-risk combinations (e.g., drop-shipped order from an unestablished customer) and prompts for a human override before allowing label creation.
• Web Portal UI Display:
  • Collapsed view: Displays a summary indicator (e.g., 🔴 Fraud Flags: 3 - Drop Ship, Unestablished Customer, High Total).
  • Expanded view: Provides detailed factor analysis including customer age, default address contrast, and velocity logs.
• Settings Panel Configuration: Added controls to the frontend settings page to toggle rules and modify thresholds dynamically (stored in SSM Parameter Store).

2.2 Geocoding & Address Validation Workflow

To prevent shipping label failures, a new verification chain has been integrated prior to printing.

• Multi-Tier Validation: Address checks run against the Starshipit API, with automatic duplication of suggestions.
• Google Maps Fallback: If Starshipit/UPS checks fail due to network or formatting limits, the system triggers a geocoding fallback using Google Maps API to normalize spelling and country/province codes.
• Automated Address Correction Feedback Loop:
  1. If an address is invalid, the Step Function halts and calls SendInvalidAddressEmail to send a secure form link to the customer.
  2. The email templates are dynamically retrieved from S3 with stage-aware headers and verified sender identity protection.
  3. CORS & Redirects: CORS origins are parameterized globally to support Shopify pixel origins and subdomain routing, eliminating old browser redirect loops.
  4. Resuming Execution: A customer updates their address via the web status page. This triggers an EventBridge extraction lambda which overwrites database properties and restarts the validation loop.

2.3 Physical UAT Sandbox Isolation

To eliminate cross-environment database and queue pollution, the UAT environment was physically migrated to a separate, isolated AWS account.

• Domain & Custom API Gateways: Switched API custom domains from EDGE to REGIONAL to resolve implicit browser caching of wildcard CORS headers (Access-Control-Allow-Origin: * vs specific credentials-allowed subdomains like https://status-uat.turboheat.net).
• Dynamic CORS Utility: Created a CORS evaluator to check request origin headers against verified Shopify and local domain registers, preventing browser blockages while maintaining credentials security.
• 1Password / IAM Federation: Frictionless credential handoff utilizing 1Password CLI integrations, AWS session token caching, and automated SAML identity setups for sandbox access.

2.4 Stateful Storage Stack Decoupling & Continuous Backups

To protect persistent client order data during iterative infrastructure deployments, all storage resources were separated from ephemeral compute resources.

• Dedicated Storage Stack: Separated DynamoDB PrintStatusTable and S3 RAW payload archiving buckets into a dedicated storage stack.
• Point-in-Time Recovery (PITR): Enabled DynamoDB Point-in-Time Recovery in UAT and PROD accounts, ensuring continuous, automatic database backups. This provides the capability to restore the order registry to any single second in the past 35 days.
• Automated Offsite Backups: Integrated a new Makefile target make backup-all-prod that triggers manual DynamoDB backups and replicates S3 storage bucket files to isolated offsite secure storage.
• Export-Driven Cross-References: Stacks reference storage buckets and tables using cdk.Fn.importValue rather than hardcoded environment properties, preventing accidental resource re-creations or collision overrides.
• Log Consolidation: Standardized log group nomenclature to ship/{stage}/{service} and established a mandatory 14-day retention rule.

3. Engineering Quality & Schema Safety (The Type-Safety Epic)

This release represents the culmination of a major type-safety initiative originally started 8 months ago. Over the last month, we resolved the remaining hurdles to enforce 100% strict data modeling, which has permanently eradicated the category of runtime data-mapping and serialization errors that historically occurred during every workflow modification.

3.1 Strict Model-to-Model Transformations & Effect Schema

All validation has been refactored around Effect Schema (@effect/schema), replacing legacy Zod validation.

• Model-to-Model Contracts: The workflow is governed by strict, well-defined model structures. A robust model-to-model transformation strategy ensures that data passing between AWS API Gateway, Lambda functions, and Step Functions is explicitly mapped and structurally aligned at design-time.
• JSON Schema Compilation: For serialized boundaries (such as Step Function input/output configurations), the pipeline compiles the Effect schemas directly into standard JSON Schema documents.
• Coercion & Parsing: Created a utility parser to enforce string-to-number coercion at API-Gateway endpoints before payloads enter the type-safe boundary.

3.2 Build-Time ASL and JSONPath Dataflow Linter

Step Function CDK task constructs historically utilized manual, string-based JSONPath parameters, which was a frequent source of runtime crashes. We replaced this with build-time contract alignment:

• Mapping Contracts: We established explicit contract mapping files (e.g., PrintStatusUpdateInputPass.mapping.json) defining the JSONPath maps for every state.
• Design-Time Validation (CDK Aspects): Registered compile-time aspects that simulate context transformations and verify that every step's input schema matches the accumulated state machine context. Mismatched properties or incorrect paths crash the build immediately.
• Result: Manual JSONPaths inside construct files have been reduced from 72 to 0, guaranteeing correct data-model alignment at all workflow entry and exit points before deployment.

3.3 Deterministic Code Thumbprint System

To solve the "Is my local code actually running in UAT/PROD?" problem, a deterministic build thumbprint system was implemented.

• Content Hashing: During synthesis, all generated templates, Lambda code bundles, schemas, and configurations are hashed. Self-referential build files are excluded to avoid hashing loops.
• Traceability: The resulting hash is injected as the CODE_THUMBPRINT environment variable in Lambdas and tagged as build-version on the Step Function state machines. Every log output includes the version, git commit hash, and thumbprint.

4. Developer Experience & Tooling Updates

This release introduces an array of utility tools to streamline daily developer tasks:

• Asset Pipelines: Custom Sharp scripts to recolor logos and automate transparency extraction for status and homepage applications.
• Worktree Testing: Added automation to spin up git worktrees for bisection testing, copying gitignored files, and running local builds on historical branches.
• Automated Frontend Bundling: Integrated an esbuild bundler directly into the Makefile build targets to output minimized JS assets with browser cache busting query variables.
• New Makefile Targets:
  • make version-all: Prints version logs from Local, UAT, and PROD configurations.
  • make deploy-homepage-uat / deploy-homepage-prod: Rapidly deploys frontend static pages.
  • make deploy-all-uat / deploy-all-prod: Chains storage, API, lambdas, and frontend deployment in a single CLI target.
  • make typecheck & make lint: Quick validation steps before pushing code.