TrueGrowth/openspec/changes/unify-local-data-persistence/specs/desktop-local-persistence/spec.md

ADDED Requirements

Requirement: Canonical Desktop Data Root

TrueGrowth SHALL use a single writable per-user desktop data root as the canonical location for business persistence.

Scenario: Local API starts outside Electron

• WHEN the Local API starts without explicit runtime path environment variables
• THEN it resolves the same platform user data root that Electron uses
• AND it stores canonical data under a data directory and runtime outputs under a runtime directory.

Scenario: Electron starts the Local API

• WHEN Electron launches or imports the Local API
• THEN it provides the canonical TRUEGROWTH_ELECTRON_USER_DATA and TRUEGROWTH_RUNTIME_STATE_DIR
• AND repeated desktop launches use the same persisted data root.

Requirement: SQLite Business Ledger

TrueGrowth SHALL store desktop business records in a canonical SQLite ledger.

Scenario: Runtime task is created

• WHEN a local runtime task is queued, updated, completed, failed, or cleared
• THEN the task and clear marker are written to the ledger
• AND restarting the Local API restores the latest task state from the ledger.

Scenario: Runtime asset is imported or generated

• WHEN a media asset is imported or generated
• THEN its metadata is written to the ledger with local file path and URL identity
• AND the media file remains in the managed runtime output directory or its indexed legacy path.

Scenario: Workflow or publishing state changes

• WHEN workflows, schedules, runs, events, accounts, campaigns, or jobs change
• THEN the aggregate state is saved to the ledger
• AND JSON shadow files remain compatible during migration.

Requirement: Storage Diagnostics And Migration

TrueGrowth SHALL expose local storage diagnostics and safe migration controls.

Scenario: User checks storage health

• WHEN a client requests storage diagnostics
• THEN the response includes canonical paths, active runtime path, SQLite availability, ledger path, legacy source status, and warnings for split roots.

Scenario: Legacy project runtime exists

• WHEN migration runs and .truegrowth-runtime contains previous records or outputs
• THEN TrueGrowth imports metadata and indexes file paths without deleting or copying large files by default
• AND records the migration result in the ledger.

Scenario: User exports or imports local data

• WHEN export or import is requested
• THEN TrueGrowth serializes or restores ledger-managed business data through the Local API
• AND invalid import payloads are rejected without clearing existing data.