Fund Migration Coordinator

The Fund Migration Coordinator orchestrates the controlled transition of an existing fund to the latest schema and platform conventions without disrupting day-to-day operations. It acts as the bridge between the original fund state (bank accounts, investors, ledger balances) and the post-migration target, ensuring that every downstream service receives data in the canonical formats introduced after the fundId string migration.

Prerequisites

Before initiating a migration, confirm the following checklist:

1. Readiness window – Daily EOD processing is paused and the fund has a maintenance window approved by operations.
2. Stable identifiers – All dependent services already accept string-based fundId values and expose lookups for legacy numeric references when required.
3. Bank account parity – Each active bank account is mapped to a destination ledger account and reconciled up to the last closed business date.
4. Investor snapshots – Investor holdings and pending transactions are exported so the wizard can verify balances post-migration.
5. Change ticket – A change-management ticket ID is recorded for audit (required input field).
6. Backups – A preflight export of fund configuration, investor registry, and cash balances is archived in secure storage.

Payload Structure

The coordinator accepts the following payload via domain service or TRPC mutation:

export interface FundMigrationCommand {
  fundId: string;
  targetSchemaVersion: string;
  changeTicket: string;
  migrateBankAccounts?: boolean;
  migrateInvestors?: boolean;
  reconcileNav?: boolean;
  dryRun?: boolean;
  requestedBy: {
    userId: string;
    role: "system" | "tenant" | "support";
  };
  schedule?: {
    earliestStart: string; // ISO-8601 timestamp
    latestCompletion?: string; // Optional ISO-8601 timestamp
  };
}

• targetSchemaVersion references the semantic version recorded in the migration ledger. It defaults to the coordinator's built-in CURRENT_SCHEMA_VERSION if omitted.
• dryRun instructs the coordinator to execute validation and diff reporting without persisting any changes. All downstream services must respect this flag.
• reconcileNav triggers a NAV recomputation once balances and investor units are migrated.
• schedule allows deferred execution by the operations team while preserving the original audit context.

The coordinator responds with a status envelope:

export interface FundMigrationResult {
  fundId: string;
  targetSchemaVersion: string;
  startedAt: string;
  completedAt?: string;
  status: "queued" | "running" | "succeeded" | "failed";
  dryRun: boolean;
  safeguards: Array<
    | "bank-account-lock"
    | "investor-hold-lock"
    | "nav-immutable"
    | "transaction-freeze"
  >;
  validationFindings: Array<{
    code: string;
    severity: "info" | "warning" | "error";
    message: string;
  }>;
}

Operational Safeguards

The migration path enforces several safeguards to keep production data safe:

1. Coordinated Locks

The coordinator acquires idempotent locks across the fund, linked bank accounts, and investor holdings. Locks are stored in the operations service so that concurrent tenant workflows are automatically blocked with a user-facing "Fund migration in progress" message.

2. Bank Account Integrity Checks

For each bank account, the coordinator:

• Verifies balances as of the freeze date and prevents ledger postings after the freeze timestamp.
• Ensures routing numbers and account numbers meet the normalized format introduced with the latest schema.
• Confirms that closing and opening balances net to zero when journal entries are replayed in the new schema.

3. Investor Portfolio Validation

Investor holdings are re-valued against the migration NAV snapshot. Any discrepancy greater than ±1 minor unit is flagged as a blocking error unless dryRun is set. The coordinator also confirms that pending purchase/redemption requests are re-applied with the new fund identifiers.

4. Audit Trail & Notifications

Every migration emits structured logs tagged with the change ticket, user ID, and resulting schema version. On completion, the coordinator notifies:

• Operations (for unlocking fund activity).
• Finance (for NAV attestation).
• Engineering (with a diff of schema changes applied).

5. Rollback Strategy

If validation fails, the coordinator leaves the fund in the pre-migration state, unlocks all resources, and returns a status: "failed" result containing remediation guidance. The preflight backups provide the source of truth for manual restoration when necessary.

Related Resources

• Fund Setup Coordinator – Baseline workflow used for greenfield funds.
• Bank Account Service API – Account-level safeguards referenced during migration.
• Investor Service API – Investor normalization and holding reconciliation.
• Fund Migration Wizard – Frontend workflow that surfaces these safeguards to operators.

TRPC Access Point

System users trigger migrations via trpc.system.funds.runMigration.mutate(options), which forwards a FundMigrationCommand payload to the coordinator. The mutation enforces the capability flag CAPABILITIES.MANAGE_OPERATIONS and requires system-level authentication.

Tenant operators consume a read-only status stream using trpc.shared.funds.getMigrationStatus.query({ fundId }) to monitor progress without the ability to start or cancel migrations.

Note: All TRPC procedures expect string-based fund identifiers that match the post-migration schema. Legacy numeric identifiers must be translated before invocation.