# Seed Version and Manifest Strategy

Seed manifests make setup repeatable, auditable, and safe to resume.

## Seed Package Model

| Field | Meaning |
| --- | --- |
| `name` | Stable package name, such as `system-core`, `crm-foundation`, `crm-demo-uat`. |
| `version` | Semantic version for the seed package. |
| `type` | `foundation`, `organization`, `business`, `demo_uat`, or `setup_state`. |
| `dependencies` | Package names and compatible versions required before this package. |
| `checksum` | Checksum over manifest content and referenced item checksums. |
| `appliedAt` | Timestamp when applied. |
| `appliedBy` | User id or setup actor id. |
| `targetOrganization` | Organization id/code when organization-scoped. |
| `source` | `script`, `wizard`, `csv`, or `plugin`. |
| `status` | `pending`, `applied`, `skipped`, `warning`, `failed`, `rolled_back`. |
| `report` | Import/seed report with counts, warnings, errors, and storage compensation notes. |

## Manifest Format

```json
{
  "name": "crm-foundation",
  "version": "1.0.0",
  "type": "foundation",
  "dependencies": ["system-core@1.0.0"],
  "targetOrganization": "ALLA",
  "source": "wizard",
  "items": [
    {
      "file": "master-options.csv",
      "checksum": "sha256:...",
      "required": true,
      "importOrder": "06"
    },
    {
      "file": "document-sequences.csv",
      "checksum": "sha256:...",
      "required": true,
      "importOrder": "14"
    }
  ]
}
```

## Package Naming

| Package | Type | Owner |
| --- | --- | --- |
| `system-core` | organization | setup foundation |
| `crm-foundation` | foundation | foundation seed services |
| `crm-organization` | organization | setup wizard/import |
| `crm-business-import` | business | CSV import engine |
| `crm-demo-uat` | demo_uat | UAT seed services |
| `document-template-foundation` | foundation | document-template/PDF foundations |
| `notification-foundation` | foundation | notification foundation |
| `report-foundation` | foundation | CRM report foundation |

## Version Rules

| Existing Manifest | Incoming Manifest | Behavior |
| --- | --- | --- |
| none | any valid version | Apply when dependencies pass. |
| same version + same checksum | same content | Skip and report already applied. |
| same version + changed checksum | changed content | Warn/block unless `force` is true and package allows mutable same-version seed. |
| older version | newer compatible version | Apply upgrade path after compatibility check. |
| newer version | older version | Block unless explicit rollback mode exists. |
| failed | same checksum | Allow retry from failed item when service is idempotent. |
| rolled back | newer version | Apply only after dependency and cleanup verification. |

## Checksum Rules

- Item checksum uses canonical CSV bytes after line-ending normalization.
- Manifest checksum includes sorted item checksums and manifest metadata except `appliedAt`, `appliedBy`, and runtime report.
- Generated wizard inputs should be serialized into canonical JSON and hashed as an item, for example `wizard-organization.json`.
- Storage object checksums should be recorded separately because storage writes cannot be DB-transactional.

## Dependency Rules

- Dependencies use package names and semver ranges, such as `crm-foundation@^1.0.0`.
- A dependency is satisfied when a successful manifest with compatible version/checksum exists for the same target organization or global scope.
- Missing required dependencies block apply.
- Optional dependencies produce warnings.

## Report Contract

Every seed package apply should produce:

```json
{
  "imported": 0,
  "updated": 0,
  "skipped": 0,
  "errors": [],
  "warnings": [],
  "storage": {
    "createdObjects": [],
    "cleanupWarnings": []
  }
}
```

## Persistence Strategy

Use proposed tables:

- `seed_manifests`
- `seed_manifest_items`

D.7.1 does not add migrations. D.7.8 should implement persistence after setup APIs and CSV import behavior are stable.

## Upgrade Behavior

1. Resolve target organization.
2. Load existing manifests for target scope.
3. Validate package dependencies.
4. Compute incoming checksums.
5. Compare version/checksum behavior table.
6. Dry-run item operations.
7. Apply in import order.
8. Store manifest and item reports in the same DB transaction where possible.
9. Store storage compensation report after non-transactional storage operations.

## Rollback Behavior

Rollback is not a default seed feature. It requires:

- previous manifest item reports
- reversible upsert strategy
- explicit reset scope
- storage cleanup strategy
- audit trail

Until implemented, use scoped reset/reseed rather than pretending arbitrary rollback is safe.