{
    "openapi": "3.1.0",
    "info": {
        "title": "InvestMoz Tax Rule Governance API",
        "version": "0.1.0",
        "description": "Management-only rule version workflow. Records are not read by the simulation engine; no fiscal parameters are activated by this API."
    },
    "servers": [{ "url": "/api/v2/investment/admin" }],
    "security": [{ "webSession": [] }],
    "paths": {
        "/tax-rules": {
            "get": {
                "summary": "List rule versions for designated governance users",
                "parameters": [
                    {
                        "name": "rule_code",
                        "in": "query",
                        "schema": { "type": "string", "maxLength": 64 }
                    },
                    {
                        "name": "component",
                        "in": "query",
                        "schema": { "$ref": "#/components/schemas/Component" }
                    },
                    {
                        "name": "scope_key",
                        "in": "query",
                        "schema": { "type": "string", "maxLength": 160 }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": { "$ref": "#/components/schemas/Status" }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        }
                    }
                ],
                "responses": {
                    "200": { "description": "Paginated rule versions" },
                    "403": { "description": "Role or MFA required" }
                }
            },
            "post": {
                "summary": "Create a draft version (editor role)",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/RuleVersionInput"
                            }
                        }
                    }
                },
                "responses": {
                    "201": { "description": "Draft saved with version_no 1" },
                    "403": { "description": "Editor role and MFA required" },
                    "422": { "description": "Invalid source, fields, or scope" }
                }
            }
        },
        "/tax-rules/{id}": {
            "get": {
                "summary": "Read a rule version and its governance state",
                "parameters": [{ "$ref": "#/components/parameters/Id" }],
                "responses": {
                    "200": { "description": "Private governance record" },
                    "404": { "description": "Not found" }
                }
            },
            "put": {
                "summary": "Edit the author's draft with optimistic locking",
                "parameters": [{ "$ref": "#/components/parameters/Id" }],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/RuleVersionInput"
                                    },
                                    {
                                        "type": "object",
                                        "required": ["version_no"],
                                        "properties": {
                                            "version_no": {
                                                "type": "integer",
                                                "minimum": 1
                                            }
                                        }
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": { "description": "Updated draft" },
                    "403": {
                        "description": "Only author/editor may change own draft"
                    },
                    "409": { "description": "Stale version" }
                }
            }
        },
        "/tax-rules/{id}/{action}": {
            "post": {
                "summary": "Advance a rule through submit, review, reject, approve, publish, suspend, or archive",
                "parameters": [
                    { "$ref": "#/components/parameters/Id" },
                    {
                        "name": "action",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "submit",
                                "review",
                                "reject",
                                "approve",
                                "publish",
                                "suspend",
                                "archive"
                            ]
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/Transition"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Transition recorded with append-only snapshot"
                    },
                    "403": {
                        "description": "Role segregation denied transition"
                    },
                    "409": {
                        "description": "Stale version or published period overlap"
                    },
                    "422": {
                        "description": "Invalid state or unavailable legal source"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "webSession": {
                "type": "apiKey",
                "in": "cookie",
                "name": "investmoz_session",
                "description": "Verified portal manager, confirmed MFA, and explicit role allowlist are all required."
            }
        },
        "parameters": {
            "Id": {
                "name": "id",
                "in": "path",
                "required": true,
                "schema": { "type": "string", "format": "uuid" }
            }
        },
        "schemas": {
            "Component": {
                "type": "string",
                "enum": [
                    "IRPC",
                    "IVA",
                    "ISPC",
                    "IRPS",
                    "INSS",
                    "RETENCOES",
                    "DIREITOS_ADUANEIROS",
                    "ICE"
                ]
            },
            "Status": {
                "type": "string",
                "enum": [
                    "draft",
                    "submitted",
                    "reviewed",
                    "rejected",
                    "approved",
                    "published",
                    "suspended",
                    "archived"
                ]
            },
            "RuleVersionInput": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "rule_code",
                    "rule_version",
                    "component",
                    "scope_key",
                    "valid_from",
                    "legal_source_id",
                    "source_sha256",
                    "rule_definition",
                    "parameters",
                    "rounding_policy"
                ],
                "properties": {
                    "rule_code": {
                        "type": "string",
                        "pattern": "^[A-Z0-9][A-Z0-9._-]{2,63}$"
                    },
                    "rule_version": { "type": "integer", "minimum": 1 },
                    "component": { "$ref": "#/components/schemas/Component" },
                    "scope_key": {
                        "type": "string",
                        "minLength": 2,
                        "maxLength": 160
                    },
                    "valid_from": { "type": "string", "format": "date" },
                    "valid_until": {
                        "type": ["string", "null"],
                        "format": "date"
                    },
                    "legal_source_id": { "type": "string", "format": "uuid" },
                    "source_sha256": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{64}$",
                        "description": "Hash declared by the editor; official exemplar verification remains an approval task."
                    },
                    "rule_definition": {
                        "type": "object",
                        "description": "Versioned declarative AST; a parameter update may preserve the same AST."
                    },
                    "parameters": {
                        "type": "object",
                        "description": "Versioned values approved with the rule version; each DSL parameter has value, unit and conditions. No values are seeded.",
                        "additionalProperties": {
                            "type": "object",
                            "required": ["value", "unit", "conditions"],
                            "properties": {
                                "value": {
                                    "oneOf": [
                                        { "type": "string" },
                                        { "type": "integer" }
                                    ]
                                },
                                "unit": { "type": "string" },
                                "conditions": { "type": "object" }
                            }
                        }
                    },
                    "rounding_policy": {
                        "type": "object",
                        "description": "Versioned with the rule and must be approved."
                    }
                }
            },
            "Transition": {
                "type": "object",
                "additionalProperties": false,
                "required": ["version_no", "evidence"],
                "properties": {
                    "version_no": { "type": "integer", "minimum": 1 },
                    "evidence": {
                        "type": "string",
                        "minLength": 20,
                        "maxLength": 2000
                    }
                }
            }
        }
    }
}