# Self-Healing Architecture & Migration Factory

## Purpose

Webdev Agent OS v17 turns modernization work into a controlled factory. It does not edit protected production source directly. It creates isolated workspaces, stages deterministic transformations, records reviewable patches, proves compatibility, rehearses rollback, and requires independent approval before a modernization wave can begin.

The factory is designed for:

- Framework and runtime upgrades
- Dependency migrations
- API version transitions
- Database schema evolution
- Configuration and policy repair
- Architecture refactors
- Compatibility harness generation
- Drift-triggered repair campaigns
- Incremental modernization waves

## Operating sequence

1. **Register the migration program.** Define objective, risk tolerance, capacity, constraints, and success criteria.
2. **Create an isolated workspace.** Copy source into a separate directory and record a baseline hash plus rollback snapshot.
3. **Stage transformations.** Codemods, framework changes, API versions, database scripts, or configuration updates are described as explicit recipes.
4. **Record patches.** Every changed file receives before/after hashes, a change summary, requirement references, and rollback evidence.
5. **Run verification.** Unit, integration, E2E, security, accessibility, performance, compatibility, migration, and rollback checks require evidence.
6. **Test compatibility.** API consumers and supported runtime environments are tested against both current and target behavior.
7. **Rehearse data changes.** Database migrations run against shadow data with checksums, timing, data-loss checks, and rollback rehearsals.
8. **Compare architecture options.** Competing migration designs are scored for maintainability, migration risk, performance, operability, and reversibility.
9. **Create a modernization wave.** Ready workspaces are grouped into a sequenced release wave with exposure limits and rollback triggers.
10. **Require independent approval.** The author cannot approve the wave.
11. **Start with evidence.** A wave cannot start without approval and deployment or canary evidence.
12. **Observe and learn.** Outcomes become new Digital Twin and Web Intelligence evidence.

## Safety invariants

- Protected source is never the experimentation surface.
- A workspace must have a baseline hash and rollback snapshot.
- Paths cannot escape the isolated workspace.
- Every patch must be reversible and reference rollback evidence.
- Passing verification requires evidence references.
- API suites cannot pass with incompatible or unevidenced cases.
- Database rehearsals cannot pass with data loss or an unverified rollback.
- Wave authors cannot approve their own wave.
- A wave cannot start before independent approval.
- External repositories, CI providers, databases, and production traffic are never implied to be connected when they are not.

## Data model

### Programs

A program defines the modernization objective, owner, budget, strategy, constraints, and success criteria.

### Isolated workspaces

A workspace records:

- Protected source root
- Isolated workspace root
- Branch or migration label
- Baseline and current hashes
- Rollback snapshot
- Linked transformation, patch, and verification records
- Readiness blockers

### Transformations

Supported transformation types:

- `codemod`
- `dependency_upgrade`
- `framework_migration`
- `api_version`
- `database_shadow`
- `config_policy`
- `test_compatibility`
- `architecture_refactor`

### Patches

A patch records:

- Relative file path
- Create, update, delete, or rename operation
- Before and after hashes
- Changed-line count
- Requirement and test links
- Reversibility
- Rollback patch reference

### Verification runs

A verification run records the stage, environment, compatibility target, counts, status, and evidence.

### API compatibility suites

A suite can preserve a current version while validating a target version and documenting a deprecation window.

### Shadow migrations

A shadow migration records:

- Source and target schema
- Row count
- Before and after checksums
- Forward duration
- Rollback duration
- Data-loss detection
- Rollback verification
- Blockers and approval status

### Architecture tournaments

Architecture options are scored using explicit weights. A reviewer selects the option; the highest score is a recommendation, not an automatic decision.

### Repair campaigns

A campaign connects drift, incidents, or contract changes to specific artifacts, workspaces, and transformations.

### Modernization waves

A wave groups ready workspaces into a sequenced release unit. It records exposure, approval, rollback plan, rollback triggers, and runtime evidence.

## Commands

```bash
npm run migration-factory:stats
npm run migration-factory:report
node scripts/migration-factory-cli.js view
```

Create an isolated copy:

```bash
node scripts/migration-factory-cli.js isolate \
  examples/self-healing-migration/source \
  reports/migration-factory/workspaces/demo
```

Apply a deterministic text codemod inside that copy:

```bash
node scripts/migration-factory-cli.js codemod \
  reports/migration-factory/workspaces/demo \
  recipe.json
```

Example recipe:

```json
{
  "filePath": "server.js",
  "search": "const REQUEST_TIMEOUT = 15000;",
  "replacement": "const REQUEST_TIMEOUT = 20000;"
}
```

## API

- `GET /api/migration-factory`
- `GET /api/migration-factory/stats`
- `GET /api/migration-factory/export`
- `POST /api/migration-factory/programs`
- `POST /api/migration-factory/workspaces`
- `POST /api/migration-factory/transforms`
- `POST /api/migration-factory/patches`
- `POST /api/migration-factory/verifications`
- `POST /api/migration-factory/api-suites`
- `POST /api/migration-factory/shadow-migrations`
- `POST /api/migration-factory/architecture-tournaments`
- `POST /api/migration-factory/architecture-tournaments/:id/decision`
- `POST /api/migration-factory/repair-campaigns`
- `POST /api/migration-factory/waves`
- `POST /api/migration-factory/waves/:id/decision`
- `POST /api/migration-factory/waves/:id/start`
- `POST /api/migration-factory/programs/:id/portfolio`
- `POST /api/migration-factory/report`

## Evidence boundary

The bundled records are examples. The local fixture proves source isolation and deterministic codemod behavior. It does not prove that GitHub, a CI service, a live database, a deployment router, or production traffic was connected or modified.