The Data Operations framework is a unified, safety-first system for moving and transforming data across SveltyCMS environments. It consolidates six operation domains under a shared lifecycle with consistent audit logging, background job support, and identity matching.

📁 Six-Domain Separation

Data Operations span six distinct domains, each with its own namespace, handler, and permission model:

🔄 Shared Operation Lifecycle

All six domains follow a common validate → plan → apply → verify lifecycle. Each phase gates the next, ensuring no destructive operation proceeds without explicit confirmation:

Phase Details

🛡️ Safety Modes

All mutation-capable domains support four safety modes that control merge behavior:

Mode Selection by Domain

🔑 Identity Matching Priority

When moving resources between environments, the framework must match source entities to target entities. Identity resolution follows this priority chain:

When no match is found, the entity is treated as new. When multiple candidates match, the operation is flagged for manual resolution and included in the plan’s warnings.

📋 Background Job Integration

Large operations (1,000+ entities) are dispatched as background jobs via the Adaptive Job Scheduler:

Job thresholds:

📊 Audit & Observability

Every data operation writes structured audit log entries with crypto-chained integrity (SHA-256 hash chain).

Audit Entry Schema

interface DataOperationAuditEntry {
  timestamp: ISODateString;
  domain: "config" | "content-package" | "migration" | "importer" | "backup" | "content-sync";
  operation: "export" | "import" | "plan" | "apply" | "restore";
  planId: string;
  mode: "add" | "merge" | "mirror" | "replace";
  actor: { userId: string; tenantId: string };
  outcome: "success" | "partial" | "failure" | "rollback";
  summary: {
    created: number;
    updated: number;
    deleted: number;
    skipped: number;
    failed: number;
  };
  durationMs: number;
  previousHash: string; // SHA-256 chain link
  currentHash: string; // SHA-256 of this entry
}

Observability Requirements

🔗 Service / Handler Patterns (Content Lists)

Data operations that mutate entries (content packages, importers, content sync, migrations) must stay consistent with how the CMS reads list data:

Related: Collection Filtering Platform · Content query params · entry-list

🗺️ Route Architecture

The Data Operations framework is dispatched through the Unified Gatekeeper (src/routes/api/[...path]/+server.ts):

api/
├── config/
│   ├── resources          GET  — List syncable resource types
│   ├── status             GET  — Drift summary
│   ├── export             POST — DB → Filesystem
│   ├── plan               POST — Dry-run operation list
│   ├── apply              POST — Execute confirmed plan
│   └── history            GET  — Past operations
├── config_sync            GET  — Deprecated alias → /api/config/status
├── config-sync            GET  — Deprecated alias → /api/config/status
├── content-export/
│   ├── validate           POST — Validate export selection
│   ├── plan               POST — Preview export contents
│   ├── run                POST — Execute export
│   ├── download           GET  — Download exported package
│   └── jobs               GET  — Export job status
├── content-import/
│   ├── validate           POST — Validate import package
│   ├── plan               POST — Preview import changes
│   ├── apply              POST — Execute import
│   └── jobs               GET  — Import job status
├── migrations/
│   ├── status             GET  — Pending migration list
│   ├── history            GET  — Past migration runs
│   ├── plan               POST — Dry-run migration
│   ├── apply              POST — Execute migration
│   └── verify             POST — Post-migration checks
├── importers/
│   ├── sources            GET  — Available import sources
│   ├── validate           POST — Validate import file
│   ├── preview            POST — Preview field mapping
│   ├── run                POST — Execute import
│   └── jobs               GET  — Import job status
├── backups/
│   ├── (list)             GET  — List backups
│   ├── create             POST — Create backup
│   ├── validate           POST — Validate backup integrity
│   ├── restore-plan       POST — Preview restore
│   ├── restore            POST — Execute restore
│   └── jobs               GET  — Backup job status
└── content-sync/
    ├── channels           GET  — List configured sync channels
    ├── plan               POST — Preview sync operations
    ├── push               POST — Push to target environment
    ├── pull               POST — Pull from source environment
    └── jobs               GET  — Sync job status

Permission Model

All unmapped namespaces fail-closed with 403 Forbidden. Admin users bypass RBAC via the dispatcher fast-path.

📦 File Format Plans

Configuration Sync Manifest

Deterministic JSON files for version-controlled site structure in /config/sync/:

/config/sync/
├── config.manifest.json
├── collections/
│   └── blog-posts.f47ac10b.json
├── system/
│   ├── widget.state.json
│   ├── theme.state.json
│   ├── webhooks.state.json
│   └── automations.state.json
└── roles/
    └── editor.a1b2c3d4.json

Each file includes a deterministic checksum and UUID for cross-environment identity matching.

Content Package (.svelty-content-package)

Portable content bundles using NDJSON streaming:

package.svelty-content-package
├── manifest.json         ← Metadata, source info, creation timestamp
├── schema/               ← Collection schemas referenced by content
│   └── {collection-name}.json
├── data/
│   ├── entries-0001.ndjson
│   ├── entries-0002.ndjson
│   └── ...
└── media/
    ├── media-manifest.json
    └── files/             ← Optional, for small transfers

Backup Archive (.svelty-backup)

Disaster-recovery archives with encryption and integrity verification:

backup-2026-07-10.svelty-backup
├── backup.manifest.json   ← Timestamp, checksums, adapter type, version
├── content/
│   └── {collection}/
│       └── entries.ndjson
├── config/
│   └── snapshot.json
├── media/
│   └── media.manifest.json
└── signatures/
    └── sha256.checksums

🏗️ Current Implementation Status

Legend: 🟢 Complete · 🟡 In progress / Partial · 🔴 Planned

Related Documentation

• Configuration Promotion API
• Configuration Management Architecture
• Server Hooks (Middleware Pipeline)
• State Management & Readiness
• Cache System
• System & Infrastructure API
• Utilities API