{
  "feature": "fund-creation-lifecycle",
  "version": "1.0.0",
  "description": "CFA-driven fund setup from mandate through IPS, benchmark, Reg 28 flag, custodian registration, seed capital, and go-live",
  "category": "workflow",
  "tags": [
    "fund-setup",
    "mandate",
    "ips",
    "benchmark",
    "custodian",
    "lifecycle",
    "cfa"
  ],
  "aliases": [
    "fund-setup",
    "new-fund-onboarding",
    "fund-launch",
    "fund-registration",
    "fund-onboarding",
    "fund-lifecycle",
    "fund-go-live"
  ],
  "fields": [
    {
      "name": "fund_id",
      "type": "text",
      "required": true,
      "label": "Fund Identifier"
    },
    {
      "name": "fund_name",
      "type": "text",
      "required": true,
      "label": "Fund Name"
    },
    {
      "name": "mandate",
      "type": "rich_text",
      "required": true,
      "label": "Investment Mandate"
    },
    {
      "name": "ips_document",
      "type": "file",
      "required": false,
      "label": "IPS Document"
    },
    {
      "name": "benchmark",
      "type": "text",
      "required": true,
      "label": "Benchmark Index"
    },
    {
      "name": "reg28_flag",
      "type": "boolean",
      "required": true,
      "label": "Regulation 28 Fund",
      "default": false
    },
    {
      "name": "custodian_id",
      "type": "text",
      "required": false,
      "label": "Custodian Identifier"
    },
    {
      "name": "seed_capital",
      "type": "number",
      "required": false,
      "label": "Seed Capital (ZAR)"
    },
    {
      "name": "status",
      "type": "select",
      "required": true,
      "label": "Fund Status",
      "options": [
        {
          "value": "draft",
          "label": "Draft"
        },
        {
          "value": "mandate_defined",
          "label": "Mandate Defined"
        },
        {
          "value": "ips_approved",
          "label": "IPS Approved"
        },
        {
          "value": "custodian_registered",
          "label": "Custodian Registered"
        },
        {
          "value": "seeded",
          "label": "Seeded"
        },
        {
          "value": "live",
          "label": "Live"
        },
        {
          "value": "closed",
          "label": "Closed"
        }
      ]
    }
  ],
  "rules": {
    "mandate_definition": {
      "description": "MUST: Mandate captures investment universe, benchmark, return target, risk limits, liquidity, and exclusions",
      "required_sections": [
        "universe",
        "benchmark",
        "return_target",
        "risk_limits",
        "liquidity",
        "exclusions"
      ]
    },
    "ips_content": {
      "description": "MUST: IPS documents goals, constraints, time horizon, rebalancing policy, reporting cadence. Approved by compliance before next stage.",
      "approver": "compliance_officer"
    },
    "reg28": {
      "description": "MUST: If reg28_flag is true, apply Regulation 28 limits from day one; verify at each lifecycle step"
    },
    "custodian": {
      "description": "MUST: Custodian registration requires signed agreement, account numbers, SWIFT details, and reconciliation contact"
    },
    "seed_capital": {
      "description": "MUST: Fund cannot go live without verified seed capital in the custodian account",
      "minimum_zar": 1000000
    },
    "separation_of_duties": {
      "description": "MUST: CFA defines mandate; compliance approves IPS; fund admin handles custodian; no single actor covers all stages"
    }
  },
  "actors": [
    {
      "id": "cfa",
      "name": "Chartered Financial Analyst",
      "type": "human",
      "role": "investment_management",
      "description": "Defines mandate, selects benchmark, authors IPS"
    },
    {
      "id": "compliance_officer",
      "name": "Compliance Officer",
      "type": "human",
      "role": "compliance",
      "description": "Approves IPS and ensures Reg 28 applicability"
    },
    {
      "id": "custodian",
      "name": "Custodian Bank",
      "type": "external",
      "description": "Holds fund assets and provides statements"
    },
    {
      "id": "fund_admin",
      "name": "Fund Administrator",
      "type": "human",
      "role": "operations",
      "description": "Handles custodian registration and seed capital"
    }
  ],
  "states": {
    "field": "status",
    "values": [
      {
        "value": "draft",
        "initial": true
      },
      {
        "value": "mandate_defined"
      },
      {
        "value": "ips_approved"
      },
      {
        "value": "custodian_registered"
      },
      {
        "value": "seeded"
      },
      {
        "value": "live",
        "terminal": true
      },
      {
        "value": "closed",
        "terminal": true
      }
    ],
    "transitions": [
      {
        "from": "draft",
        "to": "mandate_defined",
        "actor": "cfa",
        "description": "CFA finalizes mandate"
      },
      {
        "from": "mandate_defined",
        "to": "ips_approved",
        "actor": "compliance_officer",
        "description": "Compliance approves IPS"
      },
      {
        "from": "ips_approved",
        "to": "custodian_registered",
        "actor": "fund_admin",
        "description": "Fund admin registers with custodian"
      },
      {
        "from": "custodian_registered",
        "to": "seeded",
        "actor": "fund_admin",
        "description": "Seed capital verified"
      },
      {
        "from": "seeded",
        "to": "live",
        "actor": "compliance_officer",
        "description": "Go-live approval"
      },
      {
        "from": "live",
        "to": "closed",
        "actor": "compliance_officer",
        "description": "Fund closure"
      }
    ]
  },
  "flows": {
    "happy_path": [
      {
        "actor": "cfa",
        "step": "Draft mandate with universe, benchmark, return target, risk limits"
      },
      {
        "actor": "cfa",
        "step": "Author IPS aligned to mandate"
      },
      {
        "actor": "compliance_officer",
        "step": "Review and approve IPS; confirm Reg 28 applicability"
      },
      {
        "actor": "fund_admin",
        "step": "Register fund with custodian; capture account details"
      },
      {
        "actor": "fund_admin",
        "step": "Transfer and verify seed capital"
      },
      {
        "actor": "compliance_officer",
        "step": "Sign off go-live; fund is live"
      }
    ]
  },
  "outcomes": {
    "fund_created_successfully": {
      "priority": 10,
      "description": "A new fund was initialized in draft state with a defined mandate",
      "given": [
        {
          "field": "fund_name",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "mandate",
          "source": "input",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "create_record",
          "type": "fund",
          "target": "funds"
        },
        {
          "action": "emit_event",
          "event": "fund.created",
          "payload": [
            "fund_id",
            "fund_name"
          ]
        }
      ],
      "result": "Fund record created in draft state",
      "transaction": true
    },
    "mandate_approved": {
      "priority": 10,
      "description": "Mandate meets required sections and is approved",
      "given": [
        "mandate contains universe, benchmark, return target, risk limits"
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "draft",
          "to": "mandate_defined"
        },
        {
          "action": "emit_event",
          "event": "fund.mandate_approved",
          "payload": [
            "fund_id"
          ]
        }
      ],
      "result": "Mandate finalized"
    },
    "ips_approved": {
      "priority": 10,
      "description": "IPS reviewed and approved by compliance",
      "given": [
        "compliance_officer has signed off IPS"
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "mandate_defined",
          "to": "ips_approved"
        },
        {
          "action": "emit_event",
          "event": "fund.ips_approved",
          "payload": [
            "fund_id"
          ]
        }
      ],
      "result": "IPS accepted"
    },
    "fund_launched": {
      "priority": 10,
      "description": "Fund is live and accepting allocations",
      "given": [
        "seed capital has been verified in the custodian account",
        "compliance sign-off recorded"
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "seeded",
          "to": "live"
        },
        {
          "action": "emit_event",
          "event": "fund.launched",
          "payload": [
            "fund_id",
            "seed_capital"
          ]
        }
      ],
      "result": "Fund is live",
      "transaction": true
    },
    "mandate_rejected": {
      "priority": 2,
      "error": "FUND_MANDATE_REJECTED",
      "description": "Mandate missing required sections or violates internal policy",
      "given": [
        "any required mandate section is missing"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "fund.mandate_rejected",
          "payload": [
            "fund_id",
            "missing_sections"
          ]
        }
      ],
      "result": "Mandate returned to CFA for revision"
    },
    "custodian_rejection": {
      "priority": 2,
      "error": "FUND_CUSTODIAN_REJECTED",
      "description": "Custodian declined to register the fund",
      "given": [
        "custodian returned a registration rejection"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "fund.custodian_rejected",
          "payload": [
            "fund_id",
            "custodian_id",
            "reason_code"
          ]
        }
      ],
      "result": "Registration blocked pending remediation"
    }
  },
  "errors": [
    {
      "code": "FUND_MANDATE_REJECTED",
      "status": 422,
      "message": "Fund mandate is incomplete or violates policy.",
      "retry": false
    },
    {
      "code": "FUND_CUSTODIAN_REJECTED",
      "status": 409,
      "message": "Custodian registration was rejected.",
      "retry": true
    },
    {
      "code": "FUND_NOT_FOUND",
      "status": 404,
      "message": "Fund not found.",
      "retry": false
    }
  ],
  "events": [
    {
      "name": "fund.created",
      "description": "Fund initialized in draft",
      "payload": [
        "fund_id",
        "fund_name"
      ]
    },
    {
      "name": "fund.mandate_approved",
      "description": "Mandate finalized",
      "payload": [
        "fund_id"
      ]
    },
    {
      "name": "fund.ips_approved",
      "description": "IPS approved by compliance",
      "payload": [
        "fund_id"
      ]
    },
    {
      "name": "fund.launched",
      "description": "Fund live",
      "payload": [
        "fund_id",
        "seed_capital"
      ]
    },
    {
      "name": "fund.mandate_rejected",
      "description": "Mandate missing required sections",
      "payload": [
        "fund_id",
        "missing_sections"
      ]
    },
    {
      "name": "fund.custodian_rejected",
      "description": "Custodian registration rejected",
      "payload": [
        "fund_id",
        "custodian_id",
        "reason_code"
      ]
    }
  ],
  "api": {
    "http": {
      "method": "POST",
      "path": "/api/funds"
    },
    "request": {
      "content_type": "application/json",
      "schema": {
        "fund_name": "string",
        "mandate": "string",
        "benchmark": "string",
        "reg28_flag": "boolean"
      }
    },
    "response": {
      "success": {
        "status": 201,
        "schema": {
          "fund_id": "string",
          "status": "string"
        }
      },
      "errors": [
        {
          "status": 422,
          "error_code": "FUND_MANDATE_REJECTED"
        },
        {
          "status": 409,
          "error_code": "FUND_CUSTODIAN_REJECTED"
        },
        {
          "status": 404,
          "error_code": "FUND_NOT_FOUND"
        }
      ]
    }
  },
  "anti_patterns": [
    {
      "rule": "Do not allow a single actor to drive the fund from draft to live",
      "why": "Separation of duties is a regulatory expectation and prevents rogue launches"
    },
    {
      "rule": "Do not mark a fund live before verifying seed capital in the custodian",
      "why": "Launching without money leads to trade failures and reputation damage"
    },
    {
      "rule": "Do not forget the Reg 28 flag on retirement fund mandates",
      "why": "Downstream compliance gates rely on it; a missing flag lets non-compliant trades through"
    },
    {
      "rule": "Do not store IPS only as PDF without structured fields",
      "why": "Automation needs parseable benchmark, limits, cadence"
    },
    {
      "rule": "Do not skip the compliance sign-off gate",
      "why": "That gate catches prohibited strategies before go-live"
    },
    {
      "rule": "Do not reuse a closed fund_id for a new fund",
      "why": "Historical attribution becomes unverifiable"
    }
  ],
  "related": [
    {
      "feature": "regulation-28-compliance",
      "type": "required",
      "reason": "Reg 28 funds must satisfy prudential limits from day one"
    },
    {
      "feature": "client-risk-profiling-ips",
      "type": "recommended",
      "reason": "Client IPS informs fund mandate"
    },
    {
      "feature": "fund-custodian-reconciliation",
      "type": "required",
      "reason": "Custodian recon starts once the fund is registered"
    },
    {
      "feature": "immutable-audit-log",
      "type": "required",
      "reason": "All lifecycle transitions must be audited"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "compliant_fund_launch",
        "description": "Launch new funds with documented mandate, approved IPS, registered custodian, and verified seed capital",
        "success_metrics": [
          {
            "metric": "time_to_live_days",
            "target": "< 30 days",
            "measurement": "Median days from draft to live"
          },
          {
            "metric": "rework_rate",
            "target": "< 20%",
            "measurement": "Percentage of funds that return to prior state"
          }
        ],
        "constraints": [
          {
            "type": "regulatory",
            "description": "Compliance approval is mandatory; cannot be automated away",
            "negotiable": false
          },
          {
            "type": "security",
            "description": "Separation of duties across CFA, compliance, and fund admin",
            "negotiable": false
          }
        ]
      }
    ],
    "autonomy": {
      "level": "human_in_loop",
      "human_checkpoints": [
        "mandate approval",
        "ips approval",
        "go-live"
      ],
      "escalation_triggers": [
        "custodian_rejection",
        "mandate_rejected"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "fund_created_successfully",
          "permission": "autonomous"
        },
        {
          "action": "mandate_approved",
          "permission": "human_required"
        },
        {
          "action": "ips_approved",
          "permission": "human_required"
        },
        {
          "action": "fund_launched",
          "permission": "human_required"
        }
      ]
    },
    "verification": {
      "invariants": [
        "fund cannot be live without verified seed capital",
        "IPS approval precedes custodian registration",
        "Reg 28 funds have reg28_flag = true from creation"
      ]
    },
    "coordination": {
      "protocol": "orchestrated"
    }
  }
}