alla-allaos-fullstack/docs/setup/seed-version-manifest.md

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

{
  "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:

{
  "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.