Sprint 3: Confirmed Import & Safe Remapping #1

New issue

Closed

opened 2026-05-19 05:04:47 +00:00 by foravo_admin · 0 comments

foravo_admin commented

2026-05-19 05:04:47 +00:00

Owner

Imported from GitHub issue conorgregson/worldbuilding-codex#28.

Source: https://github.com/conorgregson/worldbuilding-codex/issues/28
Original author: @conorgregson
Original state: closed

Goal

Complete the Worldbuilding Codex v1.4 import workflow by allowing users to confirm a validated import, save the imported data as a new world, and safely remap IDs so existing data is not overwritten.

This sprint completes the full world backup-and-restore style workflow for v1.4.

Context

Sprint 1 adds world JSON export.

Sprint 2 adds import validation and preview.

Sprint 3 completes the release by adding confirmed import, safe ID remapping, import success handling, and final release documentation.

The import should create a new world by default. It should not overwrite or merge into an existing world.

Scope

Add a confirmed import endpoint.
Re-run validation before saving imported data.
Save imported data as a new world.
Assign the imported world to the current authenticated user.
Do not overwrite existing worlds.
Do not reuse original exported database IDs.
Remap entity IDs.
Remap relationship IDs.
Remap relationship source and target references.
Remap event IDs.
Remap event participant IDs.
Remap participant event and entity references.
Save imported records in a safe order.
Use transaction-style behavior where available.
Prevent partial saves if import fails.
Add frontend confirm import action.
Add import success state.
Add navigation to the newly imported world.
Add final v1.4 documentation and release notes updates.

Suggested Route Behavior

POST /api/worlds/import

The route should:

Require authentication.
Accept a valid export payload.
Re-run validation before saving.
Create a new world.
Remap source IDs to new IDs.
Save related records safely.
Return the newly imported world ID.

A successful response can return:

{
  "success": true,
  "worldId": "new-world-id",
  "worldTitle": "Imported World Title"
}

Suggested Import Save Order

Confirmed import should save records in a safe order:

1. Create the new world.

2. Create imported entities and store source ID to new ID mappings.

3. Create imported relationships using remapped entity IDs.

4. Create imported timeline events and store source ID to new ID mappings.

5. Create imported event participants using remapped event and entity IDs.

6. Return the newly created world ID.

This order keeps relationship and participant references intact while avoiding reuse of old exported IDs.

Acceptance Criteria

Users can confirm import after a valid preview.
Confirmed import creates a new world.
Imported world belongs to the current authenticated user.
Imported world does not overwrite an existing world.
Imported entities are created under the new world.
Imported relationships are created under the new world.
Imported timeline events are created under the new world.
Imported event participants are created under the new world.
Original exported database IDs are not reused as new database IDs.
Relationship source and target references are remapped correctly.
Event participant event and entity references are remapped correctly.
Failed imports do not leave partial data behind.
Confirmed import re-runs validation before saving.
Import success state is clear.
Users can navigate to the imported world after success.
Import error state is clear and user-friendly.
Confirm import action is keyboard reachable.
Confirm import UI is usable on desktop and narrower screens.
README, ROADMAP, CHANGELOG, sprint docs, PR description, and release notes are updated for v1.4.
No obvious console errors appear during normal import usage.

Verification Checklist

Local Verification

Run frontend build.
Run backend build.
Log in locally.
Export a world with entities, relationships, timeline events, and participants.
Open the import flow.
Upload the exported world JSON file.
Confirm the preview appears correctly.
Click the confirm import action.
Confirm a success state appears.
Click the link to open the imported world.
Confirm the imported world opens successfully.
Confirm the imported world title/details are correct.
Confirm imported entities appear.
Confirm imported relationships appear.
Confirm imported timeline events appear.
Confirm imported event participants appear.
Confirm relationship source/target references point to imported entities.
Confirm event participant references point to imported events and entities.
Confirm the original world still exists.
Confirm the original world is unchanged.
Confirm importing the same file again creates another new world instead of overwriting.
Confirm failed import does not create partial data.
Confirm validation still rejects invalid files before save.
Confirm the confirm import action has a loading or disabled state.
Confirm import success and error states are readable.
Confirm import UI is keyboard reachable.
Confirm import UI is usable on desktop.
Confirm import UI is usable on a narrow viewport.
Confirm no obvious console errors appear.

Production Verification

Hosted frontend loads successfully.
Login/authenticated flow works.
Export works in production.
Import validation works in production.
Confirmed import works in production.
Imported world opens in production.
Imported entities appear in production.
Imported relationships appear in production.
Imported timeline events appear in production.
Imported event participants appear in production.
Original world remains unchanged in production.
Re-importing the same file creates a separate new world in production.
Failed import does not create partial data in production.
No obvious production console errors appear.

Release Verification

README updated for v1.4.
ROADMAP updated for v1.4 release status.
CHANGELOG includes v1.4.0 entry.
GitHub release notes prepared.
Sprint blueprints include final verification notes.
Version tagged as v1.4.0.

Out of Scope

Overwriting existing worlds.
Merging imported data into an existing world.
Selective import options.
Duplicate detection beyond safe new-world creation.
Import conflict resolution UI.
Editing imported data during preview.
Import history.
Exporting all worlds at once.
Public sharing work.
Printable world bible export.
Markdown/PDF export.
Collaboration or invite-based imports.

Risks / Notes

Confirmed import should never trust a previously validated frontend state by itself.
Server-side validation should run again immediately before saving.
Import should create a new world by default to avoid destructive behavior.
Original source IDs should only be used to build remapping tables.
Relationship and participant references are the most important integrity risk in this sprint.
Transaction-style behavior is strongly preferred so failed imports do not leave partial worlds behind.
If full database transactions are not practical in the current stack, the import should include defensive cleanup or avoid saving until all required mappings are prepared.
Importing the same file multiple times should create separate worlds unless duplicate detection is intentionally added later.
Sprint 3 should include final documentation and release materials because it completes the v1.4 release.

Imported from GitHub issue `conorgregson/worldbuilding-codex#28`. Source: https://github.com/conorgregson/worldbuilding-codex/issues/28 Original author: @conorgregson Original state: closed  --- ## Goal Complete the Worldbuilding Codex v1.4 import workflow by allowing users to confirm a validated import, save the imported data as a new world, and safely remap IDs so existing data is not overwritten. This sprint completes the full world backup-and-restore style workflow for v1.4. --- ## Context Sprint 1 adds world JSON export. Sprint 2 adds import validation and preview. Sprint 3 completes the release by adding confirmed import, safe ID remapping, import success handling, and final release documentation. The import should create a new world by default. It should not overwrite or merge into an existing world. --- ## Scope - Add a confirmed import endpoint. - Re-run validation before saving imported data. - Save imported data as a new world. - Assign the imported world to the current authenticated user. - Do not overwrite existing worlds. - Do not reuse original exported database IDs. - Remap entity IDs. - Remap relationship IDs. - Remap relationship source and target references. - Remap event IDs. - Remap event participant IDs. - Remap participant event and entity references. - Save imported records in a safe order. - Use transaction-style behavior where available. - Prevent partial saves if import fails. - Add frontend confirm import action. - Add import success state. - Add navigation to the newly imported world. - Add final v1.4 documentation and release notes updates. --- ## Suggested Route Behavior ```txt POST /api/worlds/import ``` The route should: - Require authentication. - Accept a valid export payload. - Re-run validation before saving. - Create a new world. - Remap source IDs to new IDs. - Save related records safely. - Return the newly imported world ID. A successful response can return: ```json { "success": true, "worldId": "new-world-id", "worldTitle": "Imported World Title" } ``` --- ## Suggested Import Save Order Confirmed import should save records in a safe order: **1.** Create the new world. **2.** Create imported entities and store source ID to new ID mappings. **3.** Create imported relationships using remapped entity IDs. **4.** Create imported timeline events and store source ID to new ID mappings. **5.** Create imported event participants using remapped event and entity IDs. **6.** Return the newly created world ID. This order keeps relationship and participant references intact while avoiding reuse of old exported IDs. --- ## Acceptance Criteria - [x] Users can confirm import after a valid preview. - [x] Confirmed import creates a new world. - [x] Imported world belongs to the current authenticated user. - [x] Imported world does not overwrite an existing world. - [x] Imported entities are created under the new world. - [x] Imported relationships are created under the new world. - [x] Imported timeline events are created under the new world. - [x] Imported event participants are created under the new world. - [x] Original exported database IDs are not reused as new database IDs. - [x] Relationship source and target references are remapped correctly. - [x] Event participant event and entity references are remapped correctly. - [x] Failed imports do not leave partial data behind. - [x] Confirmed import re-runs validation before saving. - [x] Import success state is clear. - [x] Users can navigate to the imported world after success. - [x] Import error state is clear and user-friendly. - [x] Confirm import action is keyboard reachable. - [x] Confirm import UI is usable on desktop and narrower screens. - [x] README, ROADMAP, CHANGELOG, sprint docs, PR description, and release notes are updated for v1.4. - [x] No obvious console errors appear during normal import usage. --- ## Verification Checklist ### Local Verification - [x] Run frontend build. - [x] Run backend build. - [x] Log in locally. - [x] Export a world with entities, relationships, timeline events, and participants. - [x] Open the import flow. - [x] Upload the exported world JSON file. - [x] Confirm the preview appears correctly. - [x] Click the confirm import action. - [x] Confirm a success state appears. - [x] Click the link to open the imported world. - [x] Confirm the imported world opens successfully. - [x] Confirm the imported world title/details are correct. - [x] Confirm imported entities appear. - [x] Confirm imported relationships appear. - [x] Confirm imported timeline events appear. - [x] Confirm imported event participants appear. - [x] Confirm relationship source/target references point to imported entities. - [x] Confirm event participant references point to imported events and entities. - [x] Confirm the original world still exists. - [x] Confirm the original world is unchanged. - [x] Confirm importing the same file again creates another new world instead of overwriting. - [x] Confirm failed import does not create partial data. - [x] Confirm validation still rejects invalid files before save. - [x] Confirm the confirm import action has a loading or disabled state. - [x] Confirm import success and error states are readable. - [x] Confirm import UI is keyboard reachable. - [x] Confirm import UI is usable on desktop. - [x] Confirm import UI is usable on a narrow viewport. - [x] Confirm no obvious console errors appear. ### Production Verification - [x] Hosted frontend loads successfully. - [x] Login/authenticated flow works. - [x] Export works in production. - [x] Import validation works in production. - [x] Confirmed import works in production. - [x] Imported world opens in production. - [x] Imported entities appear in production. - [x] Imported relationships appear in production. - [x] Imported timeline events appear in production. - [x] Imported event participants appear in production. - [x] Original world remains unchanged in production. - [x] Re-importing the same file creates a separate new world in production. - [x] Failed import does not create partial data in production. - [x] No obvious production console errors appear. ### Release Verification - [ ] README updated for v1.4. - [ ] ROADMAP updated for v1.4 release status. - [ ] CHANGELOG includes v1.4.0 entry. - [ ] GitHub release notes prepared. - [ ] Sprint blueprints include final verification notes. - [ ] Version tagged as v1.4.0. --- ## Out of Scope - Overwriting existing worlds. - Merging imported data into an existing world. - Selective import options. - Duplicate detection beyond safe new-world creation. - Import conflict resolution UI. - Editing imported data during preview. - Import history. - Exporting all worlds at once. - Public sharing work. - Printable world bible export. - Markdown/PDF export. - Collaboration or invite-based imports. --- ## Risks / Notes - Confirmed import should never trust a previously validated frontend state by itself. - Server-side validation should run again immediately before saving. - Import should create a new world by default to avoid destructive behavior. - Original source IDs should only be used to build remapping tables. - Relationship and participant references are the most important integrity risk in this sprint. - Transaction-style behavior is strongly preferred so failed imports do not leave partial worlds behind. - If full database transactions are not practical in the current stack, the import should include defensive cleanup or avoid saving until all required mappings are prepared. - Importing the same file multiple times should create separate worlds unless duplicate detection is intentionally added later. - Sprint 3 should include final documentation and release materials because it completes the v1.4 release.

foravo_admin

2026-05-19 05:04:47 +00:00