[
  {
    "type": "alter_table",
    "description": "Add signSemantics column to qb_account_mapping — Spec 048 Phase 2. Replaces the implicit sign-flip convention in JournalEntryService::buildJournalLines with explicit per-field semantics. 'directional' = sign of source value flips entryType (used for cashOverShort and similar fields where sign carries meaning). 'absolute' = always use entryType as-is, ignore sign of source value (used for fields like newReturns/usedReturns where negative is just a labeling convention).",
    "database": "{{store}}",
    "check_query": "SHOW COLUMNS FROM qb_account_mapping LIKE 'signSemantics'",
    "sql": "ALTER TABLE `qb_account_mapping` ADD COLUMN `signSemantics` ENUM('directional','absolute') NOT NULL DEFAULT 'directional' COMMENT 'directional = sign of value flips entryType; absolute = always use entryType, ignore sign' AFTER `entryType`"
  },
  {
    "type": "update",
    "description": "Backfill signSemantics='absolute' and flip entryType='credit'->'debit' for newReturns/usedReturns fields — Spec 048 Phase 2 migration 048_006 self-documenting fix. Mathematically equivalent (these fields have always posted as DEBITs to contra-revenue via the implicit sign-flip on negative source values), but the mapping now reads as 'this is a DEBIT to Returns' instead of 'this is a CREDIT but actually flips to DEBIT because of negative input'. Idempotent: only updates rows still in the legacy state.",
    "database": "{{store}}",
    "sql": "UPDATE qb_account_mapping SET signSemantics = 'absolute', entryType = 'debit', updatedAt = NOW() WHERE fieldName IN ('newReturns', 'usedReturns') AND signSemantics = 'directional' AND entryType = 'credit'"
  }
]