Breaking Changes at Scale

[WARN] Capsule isolation violation detected
Entity: FinancialConfig
Event: FinancialConfigUpdated
Issue: Missing capsule_id in partition key
Impact: DEVUS test data appearing in PRODUS production queries

// WRONG: Tenant-scoped only
#[derive(DynamoDbEntity)]
#[pk = "TENANT#{tenant_id}#CONFIG#FINANCIAL"]
pub struct FinancialConfigEntity {
    pub tenant_id: TenantId,
    // capsule_id missing!
    pub industry: String,
    // ...
}

// Queries for "Technology" industry returned results from BOTH capsules
let configs = repo.query_by_industry(tenant_id, "Technology").await?;
// Returns: [DEVUS test config, PRODUS production config]

Planning session for capsule isolation migration.

Context:
- 6 entities currently tenant-scoped, need capsule scope
- ADR-0010 defines capsule isolation requirements
- Migration is breaking change (PK patterns change)
- Cannot break existing data

Requirements:
1. Migrate entity schemas (add capsule_id field)
2. Update PK/SK patterns (TENANT#...#CAPSULE#...)
3. Update all repositories (add capsule_id parameters)
4. Update all API handlers (pass capsule_id)
5. Migrate existing DynamoDB data
6. Update all tests (1,003 tests)

Constraints:
- Zero downtime
- Backward compatibility during migration
- All 6 entities migrate together (atomic)
- No data loss

Design migration strategy with:
- Entity modification plan
- Data migration plan
- Rollback plan
- Test plan

Migrate FinancialConfig to capsule scope per plan:
.plans/567-financial-config-migration.md

Steps:
1. Add capsule_id field
2. Update PK pattern
3. Update repository methods
4. Update API handlers
5. Update 21 tests

Verify FinancialConfig capsule migration.

Check:
- PK pattern includes CAPSULE# segment
- All repository methods require capsule_id
- Tests verify isolation (no cross-capsule leaks)
- API handlers extract capsule from request context

// BEFORE:
let key = gsi1pk_for_account(capsule_id, account_id);

// AFTER:
let key = gsi1pk_for_account(tenant_id, capsule_id, account_id);

// Created test helper:
pub fn test_capsule() -> CapsuleId {
    CapsuleId::from_str("PRODUS").unwrap()
}

// Then updated all tests:
// BEFORE:
let config = FinancialConfig::new(tenant_id, "USD");

// AFTER:
let config = FinancialConfig::new(tenant_id, test_capsule(), "USD");

ContractEntity (parent)
  ↓
ContractLineItemEntity (child)
  ↓
RevenueScheduleEntryEntity (grandchild)

1. Scan all items with old PK pattern
2. For each item:
   - Read item
   - Update PK to new pattern
   - Write to new key
   - Delete old key
3. Verify migration complete

// Atomic migration
client.transact_write_items()
    .transact_items(
        TransactWriteItem::builder()
            .put(/* new PK */)
            .condition_expression("attribute_not_exists(PK)")
            .build()
    )
    .transact_items(
        TransactWriteItem::builder()
            .delete(/* old PK */)
            .condition_expression("attribute_exists(PK)")
            .build()
    )
    .send()
    .await?;

#[derive(DynamoDbEntity)]
#[pk = "TENANT#{tenant_id}#CONFIG#FINANCIAL"]
#[sk = "METADATA"]
pub struct FinancialConfigEntity {
    pub tenant_id: TenantId,
    pub base_currency: String,
    // ...
}

#[derive(DynamoDbEntity)]
#[capsule_isolated]  // NEW: Compile-time enforcement
#[pk = "TENANT#{tenant_id}#CAPSULE#{capsule_id}#CONFIG#FINANCIAL"]
#[sk = "METADATA"]
pub struct FinancialConfigEntity {
    pub tenant_id: TenantId,
    pub capsule_id: CapsuleId,  // NEW: Required field
    pub base_currency: String,
    // ...
}

pub trait FinancialConfigRepository {
    async fn get(&self, tenant_id: TenantId) -> Result<Option<FinancialConfig>>;
    async fn save(&self, config: FinancialConfig) -> Result<()>;
}

pub trait FinancialConfigRepository {
    async fn get(&self, tenant_id: TenantId, capsule_id: CapsuleId) -> Result<Option<FinancialConfig>>;
    async fn save(&self, tenant_id: TenantId, capsule_id: CapsuleId, config: FinancialConfig) -> Result<()>;
}

let config = repo.get(tenant_id).await?;

let capsule_id = extract_capsule_from_context(&request)?;
let config = repo.get(tenant_id, capsule_id).await?;

#[test]
fn test_financial_config_creation() {
    let config = FinancialConfig::new(tenant_id(), "USD");
    assert_eq!(config.base_currency, "USD");
}

#[test]
fn test_financial_config_creation() {
    let config = FinancialConfig::new(tenant_id(), test_capsule(), "USD");
    assert_eq!(config.base_currency, "USD");
    assert_eq!(config.capsule_id, test_capsule());  // NEW: Verify capsule
}

// Entity correctly updated:
#[pk = "TENANT#{tenant_id}#CAPSULE#{capsule_id}#ACCESS#{id}"]

// But query still used old pattern:
pub async fn query_by_resource(&self, tenant_id: TenantId, resource: Resource) -> Result<Vec<Access>> {
    let pk = format!("TENANT#{}", tenant_id);  // ❌ Missing CAPSULE#
    // ...
}

// Step 1: Update entity definition
#[derive(DynamoDbEntity, Debug, Clone)]
#[capsule_isolated]  // Enforces capsule_id field + PK pattern
#[table_name = "platform_data"]
#[pk = "TENANT#{tenant_id}#CAPSULE#{capsule_id}#ENTITY#{entity_type}#{id}"]
#[sk = "METADATA"]
#[gsi1 = "TENANT#{tenant_id}#CAPSULE#{capsule_id}#GSI1#{field}"]
pub struct MyEntity {
    pub tenant_id: TenantId,
    pub capsule_id: CapsuleId,  // Required by #[capsule_isolated]
    pub id: EntityId,
    // ...
}

// Step 2: Update repository trait
pub trait MyEntityRepository {
    async fn get(&self, tenant_id: TenantId, capsule_id: CapsuleId, id: EntityId)
        -> Result<Option<MyEntity>>;
    async fn save(&self, tenant_id: TenantId, capsule_id: CapsuleId, entity: MyEntity)
        -> Result<()>;
}

// Step 3: Update API handler
pub async fn get_entity(
    Extension(context): Extension<RequestContext>,
    Path((tenant_id, entity_id)): Path<(TenantId, EntityId)>,
) -> Result<Json<EntityResponse>> {
    let capsule_id = context.capsule_id()?;  // Extract from context
    let entity = repo.get(tenant_id, capsule_id, entity_id).await?;
    Ok(Json(entity.into()))
}

// Step 4: Add negative test
#[tokio::test]
async fn test_cross_capsule_isolation() {
    let repo = DynamoDbMyEntityRepository::new(/* ... */);

    // Create in PRODUS capsule
    let entity = MyEntity::new(tenant_id(), capsule_id("PRODUS"), /* ... */);
    repo.save(tenant_id(), capsule_id("PRODUS"), entity).await?;

    // Try to fetch from DEVUS capsule
    let result = repo.get(tenant_id(), capsule_id("DEVUS"), entity.id).await?;

    // Should NOT find it (different capsule)
    assert!(result.is_none());
}