# Scope: Automated Field Management Tool (MCP)

**Task ID:** 153357623
**Type:** MCP Tool / Dev Utility
**Target System:** Aether API V3 (FastAPI + MariaDB)

## 1. Objective
To create a safe, automated "Vertical Slice" tool that handles the repetitive and error-prone process of adding or modifying fields in the Aether backend.

**Current Manual Process (Pain Points):**
1.  `ALTER TABLE` in MariaDB (risk of locking or syntax errors).
2.  Update/Recreate `v_[object]` SQL View (easy to forget, breaks Triple ID).
3.  Update Pydantic Models in `app/models/` (tedious, risk of schema drift).
4.  Update `searchable_fields` in `app/object_definitions/` (often forgotten).

## 2. Proposed Solution: `ae_field_manage`

A Python script in the MCP toolset (`agents_sync/scripts/ae_field_manage.py`) that orchestrates these steps atomically.

### Usage Example
```bash
# CLI Usage
python3 ae_field_manage.py add person nickname --type string --length 50 --nullable

# MCP Tool Usage
{
  "tool": "ae_field_manage",
  "action": "add",
  "object": "person",
  "field": "nickname",
  "params": { "type": "string", "length": 50 }
}
```

## 3. Implementation Steps

### Phase 1: Analysis & Safety (Dry Run)
*   [ ] **Input Validation:** Ensure field name is snake_case and valid.
*   [ ] **Schema Check:** Check if field already exists in DB or Pydantic.
*   [ ] **Impact Analysis:** Identify which files will be modified (e.g., `app/models/person_models.py`).

### Phase 2: Database Operations
*   [ ] **Backup:** (Optional) Trigger a quick table dump?
*   [ ] **DDL Execution:** Run `ALTER TABLE {table} ADD COLUMN {field} {type} ...`.
*   [ ] **View Recreation:**
    *   Fetch current view definition OR construct standard V3 view.
    *   Ensure Triple ID pattern is preserved (`id`, `{type}_id`, `{type}_id_random`).
    *   Execute `CREATE OR REPLACE VIEW`.

### Phase 3: Codebase Modification (AST/Regex)
*   [ ] **Pydantic Model Update:**
    *   Locate `class {Object}_Base(BaseModel):`.
    *   Inject field definition: `nickname: Optional[str] = Field(None, max_length=50)`.
    *   Use AST (Abstract Syntax Tree) parsing for safety, or careful Regex if AST is too complex for simple insertions.
*   [ ] **Search Registry Update:**
    *   If flag `--searchable` is set, add to `searchable_fields` list in `app/object_definitions/core.py`.

### Phase 4: Verification
*   [ ] **Integrity Check:** Run `ae_check_integrity` to verify View health.
*   [ ] **Schema Sync:** Trigger `ae_schema_sync` to update Frontend TS interfaces (if applicable).

## 4. Technical Constraints
*   **Database:** MariaDB 10.11.
*   **Language:** Python 3.10+.
*   **ORM:** SQLAlchemy (for type mapping), but raw SQL for DDL.
*   **File Paths:** Must respect `~/OSIT_dev/` structure.

## 5. Risks & Mitigation
*   **Risk:** Corrupting `person_models.py`.
    *   *Mitigation:* Create a `.bak` copy before writing.
*   **Risk:** Locking the DB table.
    *   *Mitigation:* Verify no active heavy transactions (low priority for dev env).
*   **Risk:** View definition divergence.
    *   *Mitigation:* The tool should ideally *read* the existing view logic or use a standard template.

## 6. Definition of Done
*   Can add a string/int/bool field to `person` via one command.
*   Database column exists.
*   View `v_person` includes the column.
*   `Person_Base` model includes the field.
*   `ae_obj_info person` reflects the change.