PR A: 12-state transaction machine + issueInstrument step + SoD matrix

Architecture note steps 1, 2, 10 (data model).

- types/transactionState.ts: 12 states, allowed-transition table, SoD matrix
- types/plan.ts: add InstrumentTerms + 'issueInstrument' PlanStep type
- services/planValidation.ts: validate SBLC step (BIC, ISO-4217, sha256,
  YYYY-MM-DD expiry, >0 amount)
- services/stateMachine.ts: transition() enforces legality + SoD + appends
  to transaction_state_transitions
- db/migrations/002: plans.transaction_state (CHECK) +
  transaction_state_transitions append-only table
- tests/unit: 13 + 8 unit tests (31 total, all pass)

No behaviour change yet: coordinator still uses legacy status field.
PRs B-G will migrate execution paths onto the new machine.

orchestrator/src/db/migrations/002_transaction_state.ts

@@ -0,0 +1,48 @@
+import { query } from "../postgres";
+import { TRANSACTION_STATES } from "../../types/transactionState";
+
+/**
+ * Migration 002 — workflow-level transaction state.
+ *
+ * Architecture note §8 (12-state machine) + §9 (transition table).
+ *
+ * Adds:
+ *   - plans.transaction_state column (CHECK-constrained)
+ *   - transaction_state_transitions append-only table
+ */
+export async function up() {
+  const states = TRANSACTION_STATES.map((s) => `'${s}'`).join(",");
+
+  await query(
+    `ALTER TABLE plans
+       ADD COLUMN IF NOT EXISTS transaction_state VARCHAR(32) NOT NULL
+         DEFAULT 'DRAFT'
+         CHECK (transaction_state IN (${states}))`,
+  );
+
+  await query(
+    `CREATE TABLE IF NOT EXISTS transaction_state_transitions (
+       id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+       plan_id         UUID NOT NULL REFERENCES plans(plan_id) ON DELETE CASCADE,
+       from_state      VARCHAR(32),
+       to_state        VARCHAR(32) NOT NULL CHECK (to_state IN (${states})),
+       reason          TEXT,
+       source_event_id UUID,
+       actor           VARCHAR(255) NOT NULL,
+       actor_role      VARCHAR(32)  NOT NULL,
+       signature       TEXT,
+       created_at      TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+     )`,
+  );
+
+  await query(
+    `CREATE INDEX IF NOT EXISTS idx_tx_transitions_plan_id
+       ON transaction_state_transitions(plan_id)`,
+  );
+  await query(
+    `CREATE INDEX IF NOT EXISTS idx_tx_transitions_created_at
+       ON transaction_state_transitions(created_at)`,
+  );
+
+  console.log("Migration 002 applied: transaction_state + transitions table");
+}

orchestrator/src/db/migrations/index.ts

@@ -1,4 +1,5 @@
 import { up as up001 } from "./001_initial_schema";
+import { up as up002 } from "./002_transaction_state";
 
 /**
  * Run all migrations
@@ -6,10 +7,10 @@ import { up as up001 } from "./001_initial_schema";
 export async function runMigration() {
   try {
     await up001();
-    console.log("✅ All migrations completed");
+    await up002();
+    console.log("All migrations completed");
   } catch (error) {
-    console.error("❌ Migration failed:", error);
+    console.error("Migration failed:", error);
     throw error;
   }
 }
-