# Generation Run Persistence Implementation Plan

**Goal:** Persist every successful ProjectSpec generation manifest with its Spec and environment fingerprints, then compare any two historical runs by target and file path.

**Architecture:** Keep `ProjectSpecGenerationService` responsible for deterministic source generation. After all targets are generated and inspected successfully, it computes an environment fingerprint and delegates one transactional write to `ProjectSpecGenerationRunService`. Runs, target summaries, and file manifests use normalized tables. Query and Diff APIs read only persisted manifests; generated ZIP bytes remain transient.

**Tech Stack:** Java 8, Spring, MyBatis, MySQL, JUnit 4, Mockito, Vue 3, Element Plus, Node test runner, Vite.

## Task 1: Schema And Persistence Contract

- [x] Add `factory_generation_run`, `factory_generation_target`, and `factory_generation_file` to the upgrade and base SQL scripts.
- [x] Store Spec, Adapter, Plugin, Template, environment, target, and aggregate content fingerprints.
- [x] Add immutable insert/read-only MyBatis contracts and schema tests.

## Task 2: Environment Fingerprints And Run Store

- [x] Compute deterministic Adapter, Plugin, Template, and aggregate environment fingerprints from ProjectSpec and selected targets.
- [x] Persist one successful run, all target summaries, and file manifests in one transaction.
- [x] List and load runs with project ownership checks.
- [x] Diff files by `templateType + path`, with added, removed, changed, and unchanged counts.

## Task 3: Generation And HTTP Integration

- [x] Persist a run only after deterministic generation completes successfully.
- [x] Return `generationRunId`, creation time, status, and environment fingerprints from the existing generate endpoint.
- [x] Add list, detail, and run Diff endpoints to the Factory controller and frontend API.

## Task 4: Factory Workspace

- [x] Replace the in-memory-only manifest view with persisted generation history.
- [x] Show run/Spec identity and Adapter, Plugin, Template, and environment fingerprints.
- [x] Add run selectors and a file-level artifact Diff table.
- [x] Keep generation ZIP download and certified artifact actions out of this phase.

## Task 5: Verification And Roadmap

- [x] Run Factory backend tests, all frontend source-contract tests, and the Vite production build.
- [x] Run `git diff --check` and update the AI Software Factory roadmap with P1-G boundaries.

## Explicit Boundaries

- Only successful synchronous generations are persisted in P1-G.
- ZIP bytes and generated source files are not stored; manifests and hashes are stored.
- Adapter and Template fingerprints identify the current legacy contracts. P2 will replace these provisional contracts with first-class versioned Adapter and Template Pack descriptors.
- A persisted run is traceable output evidence, not a certified artifact or deployment.