# SQM Ordination Versioning System - Complete Audit Trail

**Version:** 1.0.1-alpha  
**Date Created:** Current Session  
**System:** Production Update Audit & Versioning

---

## Overview

The **Ordination Versioning System** creates an immutable audit trail for every file change across every version. This enables:

- **Complete History**: Every version of every changed file is preserved
- **Timestamp Landmarks**: Each ordinated file carries the exact date/time of deployment
- **Instant Rollback**: Original or any prior version available immediately
- **Compliance**: Full change documentation for audits
- **Dependency Tracking**: Understand which files changed together

---

## How It Works

### Standard Update Flow

**Pre-Production (Dev):**
```
C:\___Work\SqliteMojo\Web\
  ├─ Admin\MigrationExecutor.aspx  [CHANGED]
  ├─ Admin\MigrationAnalyzer.ashx  [CHANGED]
  └─ App_MasterPages\layout.Master [CHANGED]
```

**Production (Live) - Before Update:**
```
C:\___Fire\SqliteMojo\Web\
  ├─ Admin\MigrationExecutor.aspx  [v1.0.0]
  ├─ Admin\MigrationAnalyzer.ashx  [v1.0.0]
  └─ App_MasterPages\layout.Master [v1.0.0]
```

**Production (Live) - After Update 101:**
```
C:\___Fire\SqliteMojo\Web\
  ├─ Admin\MigrationExecutor.aspx  [v1.0.1 UPDATED]
  ├─ Admin\MigrationAnalyzer.ashx  [v1.0.1 UPDATED]
  └─ App_MasterPages\layout.Master [v1.0.1 UPDATED]
```

**Ordination Archive:**
```
C:\___Fire\SqliteMojo\Web\Updates\Ordinations\
  ├─ MigrationExecutor.aspx.101    [timestamp: 2025-01-XX 14:30:45]
  ├─ MigrationAnalyzer.ashx.101    [timestamp: 2025-01-XX 14:30:45]
  ├─ layout.Master.101             [timestamp: 2025-01-XX 14:30:45]
  └─ ... (previous versions: .100, .99, etc.)
```

---

## Ordination File Naming Convention

```
{filename}.{version}
```

**Examples:**
```
MigrationExecutor.aspx.101      ← Update 101 (v1.0.1)
MigrationExecutor.aspx.100      ← Update 100 (v1.0.0) [baseline]
layout.Master.101               ← Update 101 (v1.0.1)
layout.Master.100               ← Update 100 (v1.0.0) [baseline]
BlogCompare.aspx.cs.105         ← Update 105 (v1.0.5) [only if changed in 105]
```

**Rules:**
- Version suffix = 3-digit ordinal from SQM version
- Only files that changed in that update get an ordination entry
- Timestamp embedded in file's `LastWriteTime` metadata
- Original extension preserved before version suffix

---

## Version Mapping

SQM uses semantic versioning mapped to ordinals:

| Semantic Version | Ordinal | Script Name | Description |
|---|---|---|---|
| 1.0.0 | 100 | `SQM_Update_100.ps1` | Baseline (1.0.0-alpha) |
| 1.0.1 | 101 | `SQM_Update_101.ps1` | Feature/Patch |
| 1.0.2 | 102 | `SQM_Update_102.ps1` | Patch |
| 1.1.0 | 110 | `SQM_Update_110.ps1` | Minor Release |
| 2.0.0 | 200 | `SQM_Update_200.ps1` | Major Release |

**Formula:** `(major × 100) + (minor × 10) + patch`

---

## Update 101 Ordinations

**Files changed and ordinated in Update 101:**

### 1. MigrationExecutor.aspx.101
- **Changed in:** Update 101 (1.0.1-alpha)
- **Why:** Complete redesign for multi-app Siphon UI
- **Features Added:**
  - Multi-config auto-discovery
  - Rotator-switch setup controls
  - App selection UI with custom naming
  - Enhanced progress/results reporting

### 2. MigrationAnalyzer.ashx.101
- **Changed in:** Update 101 (1.0.1-alpha)
- **Why:** Enhanced for multi-app analysis & migration
- **Features Added:**
  - JSON payload parsing
  - Multi-app analysis endpoint
  - Multi-app migration coordination
  - Backward compatibility with single-app mode

### 3. layout.Master.101
- **Changed in:** Update 101 (1.0.1-alpha)
- **Why:** Fixed SSI parser error
- **Changes Made:**
  - Removed `<!--#include file="/Content/failsafeskin/includes/favicons.html"-->`
  - Replaced with comment block
  - Eliminated deployment-time parser errors

---

## Audit & Verification

### Checking File History

**List all ordinations for a file:**
```powershell
Get-ChildItem "C:\___Fire\SqliteMojo\Web\Updates\Ordinations\layout.Master.*" | 
    Select-Object Name, LastWriteTime, Length | Sort-Object Name -Descending
```

**Output example:**
```
Name                     LastWriteTime           Length
----                     -------------           ------
layout.Master.101        1/15/2025 2:30:45 PM    45678
layout.Master.100        1/14/2025 4:15:22 PM    45432
```

### Comparing Versions

**See what changed between versions:**
```powershell
$file100 = "C:\___Fire\SqliteMojo\Web\Updates\Ordinations\layout.Master.100"
$file101 = "C:\___Fire\SqliteMojo\Web\Updates\Ordinations\layout.Master.101"

Compare-Object (Get-Content $file100) (Get-Content $file101) | Head -20
```

### Verifying Current Production

**Hash current file against ordination:**
```powershell
$current = "C:\___Fire\SqliteMojo\Web\App_MasterPages\layout.Master"
$ordinated = "C:\___Fire\SqliteMojo\Web\Updates\Ordinations\layout.Master.101"

$h1 = (Get-FileHash $current).Hash
$h2 = (Get-FileHash $ordinated).Hash

if ($h1 -eq $h2) { "✓ Current matches v101" } else { "✗ Mismatch - current differs from v101" }
```

---

## Rollback Scenarios

### Scenario 1: Rollback from 1.0.1 to 1.0.0

**If you need to undo Update 101:**

```powershell
# Method 1: Use automatic backup (if created during update)
Copy-Item -Path "C:\___Fire\SqliteMojo\Backups\SQM_Update_101_*\*" `
          -Destination "C:\___Fire\SqliteMojo\Web" -Recurse -Force

# Method 2: Use ordinated version (restore from prior ordination)
# (assumes you kept v100 ordinations)
Copy-Item -Path "C:\___Fire\SqliteMojo\Web\Updates\Ordinations\*.100" `
          -Destination "C:\___Fire\SqliteMojo\Web" -Recurse -Force
```

### Scenario 2: Selective File Rollback

**If only one file in Update 101 caused a problem:**

```powershell
# Restore just layout.Master from backup
$backupFile = "C:\___Fire\SqliteMojo\Backups\SQM_Update_101_20250115_143045\App_MasterPages\layout.Master"
$targetFile = "C:\___Fire\SqliteMojo\Web\App_MasterPages\layout.Master"

Copy-Item -Path $backupFile -Destination $targetFile -Force
```

---

## Backup Strategy

Each update creates a timestamped backup:

```
C:\___Fire\SqliteMojo\Backups\
  ├─ SQM_Update_101_20250115_143045\  ← Backup before 101
  │  ├─ Admin\MigrationExecutor.aspx
  │  ├─ Admin\MigrationAnalyzer.ashx
  │  └─ App_MasterPages\layout.Master
  │
  ├─ SQM_Update_100_20250114_091230\  ← Backup before 100
  │  └─ ... (initial db files, etc.)
```

**Backup Retention:**
- Keep last 5-10 backups for quick rollback
- Archive older backups separately
- Document restoration process in runbooks

---

## Update Execution

### Test Run (Dry Run)

```powershell
.\SQM_Update_101.ps1 -DryRun
```

Output shows:
- What files WOULD be deployed
- What ordinations WOULD be created
- What verification WOULD run
- **No actual changes**

### Production Deployment

```powershell
.\SQM_Update_101.ps1
```

Process:
1. ✓ Validate prerequisites (files exist, paths valid)
2. ✓ Create timestamped backup
3. ✓ Deploy files to production
4. ✓ Create ordinated versions (`.101` suffix)
5. ✓ Verify file hashes match
6. ✓ Update VERSION.md and VERSION_HISTORY.md
7. ✓ Log all actions to update log

---

## Log Files

### Update Log

**Location:** `C:\___Fire\SqliteMojo\Web\Updates\SQM_Update_101_Log.txt`

**Sample content:**
```
[2025-01-15 14:30:45] [INFO] ✓ Pre-production: C:\___Work\SqliteMojo\Web
[2025-01-15 14:30:45] [SUCCESS] All prerequisites validated successfully
[2025-01-15 14:30:46] [BACKUP] Admin\MigrationExecutor.aspx backed up
[2025-01-15 14:30:46] [UPDATE] Admin\MigrationExecutor.aspx copied to production
[2025-01-15 14:30:46] [ORDINATION] MigrationExecutor.aspx.101 created at 2025-01-15 14:30:46
[2025-01-15 14:30:47] [VERIFY] Admin\MigrationExecutor.aspx verified (hashes match)
[2025-01-15 14:30:48] [UPDATE] VERSION.md updated
[2025-01-15 14:30:48] [SUCCESS] Update SQM_Update_101 completed successfully
```

### Version History

**Location:** `C:\___Fire\SqliteMojo\Web\Updates\VERSION_HISTORY.md`

Documents:
- All update ordinals
- What changed in each
- Deployment timestamps
- File lists per update

---

## Best Practices

### For Operators

1. **Always review changes before deploying**
   ```powershell
   # Review what's in the update
   Get-ChildItem "C:\___Work\SqliteMojo\Web\Admin\MigrationExecutor.aspx"
   Get-Content "C:\___Work\SqliteMojo\Web\Admin\MigrationExecutor.aspx" | Select-Object -First 50
   ```

2. **Run dry-run first**
   ```powershell
   .\SQM_Update_101.ps1 -DryRun
   ```

3. **Schedule during maintenance window**
   - Inform users of brief app restart
   - Have rollback plan ready

4. **Monitor after deployment**
   - Check application health
   - Watch logs for errors
   - Verify functionality

### For Developers

1. **Document changes in VERSION_HISTORY.md**
   - What file changed and why
   - New features or fixes
   - Breaking changes (if any)

2. **Keep pre-production and production in sync**
   - Regular deployments prevent drift
   - Smaller, frequent updates vs. big rare ones

3. **Test in pre-production first**
   - Run update script against dev environment
   - Verify behavior before production

4. **Preserve ordinations long-term**
   - Archive ordination folders after several versions
   - Build complete audit trail

---

## Example Workflow: Update 101 → 102

**Scenario:** You develop fixes in pre-production for version 1.0.2 (ordinal 102)

**Steps:**

1. **Modify files in pre-production:**
   ```
   C:\___Work\SqliteMojo\Web\Admin\MigrationExecutor.aspx [FIXED]
   ```

2. **Create Update 102 script:**
   ```powershell
   # Copy SQM_Update_101.ps1 to SQM_Update_102.ps1
   # Update version numbers from 101 to 102
   # Update description and change notes
   ```

3. **Test dry-run:**
   ```powershell
   .\SQM_Update_102.ps1 -DryRun
   ```

4. **Deploy when ready:**
   ```powershell
   .\SQM_Update_102.ps1
   ```

5. **Audit trail now shows:**
   ```
   MigrationExecutor.aspx.102  [timestamp: when 102 ran]
   MigrationExecutor.aspx.101  [timestamp: when 101 ran]
   MigrationExecutor.aspx.100  [timestamp: when 100 ran]
   ```

---

## Summary

The **SQM Ordination Versioning System** provides:

✅ **Complete audit trail** of every file change  
✅ **Timestamp landmarks** for each version  
✅ **Instant rollback** to any prior version  
✅ **Dependency tracking** (which files changed together)  
✅ **Compliance documentation** (when, what, why changed)  
✅ **Low-overhead operations** (simple PowerShell scripts)  

**The ordination folder becomes your version control for production deployments.**

---

**Tally Ho! Your audit system is production-ready.** 🎯