specrails-desktop 2.57.0 → 2.58.0

package/server/dist/modules/loops/runtime/loops-router.js

@@ -4,17 +4,51 @@ exports.registerLoopsRoutes = registerLoopsRoutes;
 const ids_1 = require("../../../ids");
 const feature_flags_1 = require("../../../feature-flags");
 const loops_store_1 = require("./loops-store");
+const loop_graph_1 = require("./loop-graph");
+const loop_definition_1 = require("./loop-definition");
+const loop_compat_1 = require("./loop-compat");
+const loop_migration_1 = require("./loop-migration");
+const agent_runtime_loader_1 = require("../../agent-runtime/runtime/agent-runtime-loader");
 const loop_templates_1 = require("./loop-templates");
 const loop_factory_1 = require("./loop-factory");
+const builtin_loops_1 = require("./builtin-loops");
 const loop_command_catalog_1 = require("./loop-command-catalog");
 const loop_constants_1 = require("./loop-constants");
 const loop_preview_1 = require("./loop-preview");
+const BUILTIN_DELETE_MESSAGE = 'Built-in loops cannot be deleted. Use Restore original to reset it, or Duplicate it to keep a separate copy.';
+async function factoryCapabilities() {
+    try {
+        return (await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).api?.capabilities;
+    }
+    catch {
+        return undefined;
+    }
+}
 function isNonEmptyString(v) {
     return typeof v === 'string' && v.trim().length > 0;
 }
 function registerLoopsRoutes(router, deps) {
     const { db } = deps;
     const isRunning = deps.isLoopRunning ?? (() => false);
+    const isBuiltin = (id) => Boolean((0, loops_store_1.getLoop)(db, id)?.builtinId);
+    // One seeding pass at a time; later calls re-check (Core may have appeared or
+    // changed) and are cheap because the Core API probe is cached by fingerprint.
+    let seeding = null;
+    function seedBuiltins() {
+        if (!deps.builtinLoops)
+            return Promise.resolve();
+        if (!seeding) {
+            seeding = (0, builtin_loops_1.ensureBuiltinLoops)(db, deps.builtinLoops)
+                .catch((error) => { console.warn('[loops] built-in loop seeding failed:', error instanceof Error ? error.message : error); })
+                .finally(() => { seeding = null; });
+        }
+        return seeding;
+    }
+    // Startup: the registry (and its desktop DB) exists when routes are registered.
+    // The Core API probe is synchronous on first use, so defer it past startup
+    // (and the listen call) instead of delaying the server by the probe timeout.
+    if ((0, feature_flags_1.isLoopsEnabled)() && deps.builtinLoops)
+        setImmediate(() => { void seedBuiltins(); }).unref?.();
     // Single gate: every loops route 404s when the feature is disabled.
     function guard(res) {
         if (!(0, feature_flags_1.isLoopsEnabled)()) {
@@ -24,11 +58,11 @@ function registerLoopsRoutes(router, deps) {
         return true;
     }
     // ── Templates ──────────────────────────────────────────────────────────────
-    router.get('/loop-templates', (_req, res) => {
+    router.get('/loop-templates', async (_req, res) => {
         if (!guard(res))
             return;
         res.json({
-            templates: loop_templates_1.LOOP_TEMPLATES.map((t) => ({
+            templates: (0, loop_templates_1.loopTemplatesForCapabilities)(await factoryCapabilities()).map((t) => ({
                 id: t.id,
                 name: t.name,
                 description: t.description,
@@ -41,9 +75,10 @@ function registerLoopsRoutes(router, deps) {
         });
     });
     // ── List / get ───────────────────────────────────────────────────────────────
-    router.get('/loops', (_req, res) => {
+    router.get('/loops', async (_req, res) => {
         if (!guard(res))
             return;
+        await seedBuiltins();
         res.json({ loops: (0, loops_store_1.listLoops)(db) });
     });
     // Magic-command catalog for the builder palette (drives the AI Step chips).
@@ -53,36 +88,65 @@ function registerLoopsRoutes(router, deps) {
             return;
         res.json({ commands: loop_command_catalog_1.LOOP_COMMANDS.map((c) => ({ name: c.name, label: c.label, description: c.description })) });
     });
-    // ── Factory loops (built-in, locked) ─────────────────────────────────────────
-    // Registered BEFORE `/loops/:id` so "factory" is not captured as an id.
-    router.get('/loops/factory', (_req, res) => {
+    // Catalog belongs to the installed runtime; global authoring has no project state.
+    router.get('/loops/catalog', async (_req, res) => {
+        if (!guard(res))
+            return;
+        try {
+            const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
+            if (runtime.api?.capabilities?.engineV2 !== 1 || !runtime.listWorkflows) {
+                res.status(409).json({ error: 'engine_unsupported', message: 'Update Core to author executable workflows.' });
+                return;
+            }
+            res.json(runtime.listWorkflows());
+        }
+        catch (error) {
+            res.status(503).json({ error: 'runtime_catalog_unavailable', message: error instanceof Error ? error.message : 'Core catalog unavailable' });
+        }
+    });
+    // ── Factory loops (built-ins) ────────────────────────────────────────────────
+    // Registered BEFORE `/loops/:id` so "factory" is not captured as an id. Kept
+    // for companion/mobile/MCP back-compat: each entry reflects its editable row
+    // when seeded (name, description and the graph a rail launch would run).
+    router.get('/loops/factory', async (_req, res) => {
         if (!guard(res))
             return;
+        await seedBuiltins();
+        const capabilities = await factoryCapabilities();
         res.json({
-            factoryLoops: loop_factory_1.FACTORY_LOOPS.map((f) => ({
-                id: f.id,
-                name: f.name,
-                description: f.description,
-                mode: f.mode,
-                requiredCapability: f.requiredCapability ?? null,
-                // Absent means launchable (every pre-existing factory loop is).
-                launchable: f.launchable !== false,
-                graph: f.graph,
-            })),
+            factoryLoops: (0, loop_factory_1.factoryLoopsForCapabilities)(capabilities).map((f) => {
+                const resolved = (0, builtin_loops_1.resolveBuiltinLoop)(db, f.id, capabilities);
+                return {
+                    id: f.id,
+                    name: resolved?.name ?? f.name,
+                    description: resolved?.description ?? f.description,
+                    mode: f.mode,
+                    requiredCapability: f.requiredCapability ?? null,
+                    // Absent means launchable (every pre-existing factory loop is).
+                    launchable: f.launchable !== false,
+                    graph: resolved?.graph ?? f.graph,
+                    // Seeded built-ins are ordinary loops: edit them via PUT /loops/:id.
+                    editable: Boolean(resolved?.row),
+                    status: resolved?.row?.status ?? 'published',
+                    modified: resolved?.row?.builtinModified ?? false,
+                };
+            }),
         });
     });
-    // Fork a factory loop into a new editable user Draft (leaves the factory intact).
-    router.post('/loops/factory/:id/fork', (req, res) => {
+    // Back-compat alias of `POST /loops/:id/duplicate` for a built-in: creates a
+    // separate Draft from the built-in's current content (the built-in is unchanged).
+    router.post('/loops/factory/:id/fork', async (req, res) => {
         if (!guard(res))
             return;
-        const f = (0, loop_factory_1.getFactoryLoop)(req.params.id);
-        if (!f) {
+        const resolved = (0, builtin_loops_1.resolveBuiltinLoop)(db, req.params.id, await factoryCapabilities());
+        if (!resolved) {
             res.status(404).json({ error: 'Factory loop not found' });
             return;
         }
         const body = req.body ?? {};
-        const name = isNonEmptyString(body.name) ? body.name.trim() : `${f.name} (fork)`;
-        const loop = (0, loops_store_1.createLoop)(db, { id: (0, ids_1.newId)(), name, description: f.description, graph: f.graph });
+        const name = isNonEmptyString(body.name) ? body.name.trim() : `${resolved.name} (fork)`;
+        const source = resolved.row ?? { description: resolved.description, graph: resolved.graph };
+        const loop = (0, loops_store_1.createLoop)(db, { id: (0, ids_1.newId)(), name, description: source.description, graph: source.graph });
         res.status(201).json({ loop });
     });
     // ── Constants library (global, cross-loop) ─────────────────────────────────
@@ -144,7 +208,12 @@ function registerLoopsRoutes(router, deps) {
             return;
         }
         const provider = typeof body.provider === 'string' ? body.provider : 'claude';
-        res.json((0, loop_preview_1.previewLoop)(body.graph, { provider, constants: (0, loop_constants_1.loadConstantMap)(db) }));
+        try {
+            res.json((0, loop_preview_1.previewLoop)(body.graph, { provider, constants: (0, loop_constants_1.loadConstantMap)(db) }));
+        }
+        catch (error) {
+            res.status(400).json({ errors: [{ code: 'definition_invalid', message: error instanceof Error ? error.message : 'Invalid workflow' }] });
+        }
     });
     // Import loops from an export envelope. Duplicate NAMES are skipped (returned
     // in `skipped`); the rest land as fresh Drafts. Registered BEFORE `/loops/:id`.
@@ -158,6 +227,42 @@ function registerLoopsRoutes(router, deps) {
         }
         res.json((0, loops_store_1.importLoops)(db, body.loops, ids_1.newId));
     });
+    // Read-only migration assessment; registered before `/loops/:id`. It never
+    // converts or (un)publishes: conversion stays an explicit, reviewable step.
+    router.get('/loops/migration', async (_req, res) => {
+        if (!guard(res))
+            return;
+        try {
+            const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
+            const catalog = runtime.listWorkflows?.();
+            if (runtime.api?.capabilities?.engineV2 !== 1 || runtime.api?.capabilities?.workflowDefinitions !== 1 || !catalog || catalog.nodeKindsVersion < 5) {
+                res.status(409).json({ error: 'engine_unsupported', message: 'Migration assessment requires Core catalog version 5 or later.' });
+                return;
+            }
+            const constants = (0, loop_constants_1.loadConstantMap)(db);
+            res.json((0, loop_migration_1.assessLoopMigration)((0, loops_store_1.listLoops)(db), {
+                isRunning,
+                validate: (loop, graph) => {
+                    const definition = (0, loop_definition_1.compileLoopToDefinition)(graph, { id: loop.id, title: loop.name, constants, provider: 'claude', spec: { id: 1, title: 'Sample spec', description: 'Migration assessment' } });
+                    const validation = runtime.validateWorkflowDefinition(definition, { structural: true });
+                    return validation.ok ? { ok: true } : { ok: false, errors: validation.errors.map(error => ({ ...error, nodeId: error.nodeId ?? error.path?.match(/^\/nodes\/([^/]+)/)?.[1] })) };
+                },
+            }));
+        }
+        catch (error) {
+            res.status(503).json({ error: 'runtime_validation_unavailable', message: error instanceof Error ? error.message : 'Core validation unavailable' });
+        }
+    });
+    router.get('/loops/:id/legacy-graph', (req, res) => {
+        if (!guard(res))
+            return;
+        const backup = (0, loops_store_1.readLegacyLoopGraph)(db, req.params.id);
+        if (!backup) {
+            res.status(404).json({ error: 'Original legacy graph not found' });
+            return;
+        }
+        res.json(backup);
+    });
     router.get('/loops/:id', (req, res) => {
         if (!guard(res))
             return;
@@ -186,10 +291,10 @@ function registerLoopsRoutes(router, deps) {
         res.status(201).json({ loop });
     });
     // ── Instantiate from a template ───────────────────────────────────────────────
-    router.post('/loops/from-template/:templateId', (req, res) => {
+    router.post('/loops/from-template/:templateId', async (req, res) => {
         if (!guard(res))
             return;
-        const template = (0, loop_templates_1.getLoopTemplate)(req.params.templateId);
+        const template = (0, loop_templates_1.getLoopTemplate)(req.params.templateId, await factoryCapabilities());
         if (!template) {
             res.status(404).json({ error: 'Template not found' });
             return;
@@ -213,7 +318,10 @@ function registerLoopsRoutes(router, deps) {
             res.status(404).json({ error: 'Loop not found' });
             return;
         }
-        if (isRunning(id)) {
+        // Runs freeze a clone of their graph at launch, and built-in launches use
+        // the last Published snapshot while an edit is Draft, so a running built-in
+        // stays editable. Other loops keep the conservative running guard.
+        if (!isBuiltin(id) && isRunning(id)) {
             res.status(409).json({ error: 'Loop is running; stop the run before editing' });
             return;
         }
@@ -234,7 +342,59 @@ function registerLoopsRoutes(router, deps) {
         res.json({ loop });
     });
     // ── Publish / unpublish ───────────────────────────────────────────────────────
-    router.post('/loops/:id/publish', (req, res) => {
+    router.post('/loops/:id/convert', async (req, res) => {
+        if (!guard(res))
+            return;
+        const id = req.params.id, current = (0, loops_store_1.getLoop)(db, id);
+        if (!current) {
+            res.status(404).json({ error: 'Loop not found' });
+            return;
+        }
+        if (isRunning(id)) {
+            res.status(409).json({ error: 'loop_running' });
+            return;
+        }
+        if ((0, loop_graph_1.isDefinitionGraph)(current.graph) && (0, loops_store_1.readLegacyLoopGraph)(db, id)) {
+            res.json({ loop: current, nodeIds: {}, issues: [], alreadyConverted: true });
+            return;
+        }
+        try {
+            const converted = (0, loop_compat_1.convertLegacyLoop)(current.graph, {
+                ...(typeof req.body?.repositoryId === 'string' && req.body.repositoryId.trim() ? { repositoryId: req.body.repositoryId.trim() } : {}),
+            });
+            if (!converted.ok) {
+                res.status(422).json({ error: 'conversion_invalid', errors: converted.issues });
+                return;
+            }
+            const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
+            const catalog = runtime.listWorkflows?.();
+            if (runtime.api?.capabilities?.engineV2 !== 1 || runtime.api?.capabilities?.workflowDefinitions !== 1 ||
+                !catalog || catalog.nodeKindsVersion < 5) {
+                res.status(409).json({ error: 'engine_unsupported', message: 'Legacy conversion requires Core catalog version 5 or later.' });
+                return;
+            }
+            const definition = (0, loop_definition_1.compileLoopToDefinition)(converted.graph, { id: current.id, title: current.name, constants: (0, loop_constants_1.loadConstantMap)(db), provider: 'claude', spec: { id: 1, title: 'Sample spec', description: 'Conversion preview' } });
+            const validation = runtime.validateWorkflowDefinition(definition, { structural: true });
+            if (!validation.ok) {
+                res.status(422).json({ error: 'conversion_invalid', errors: validation.errors });
+                return;
+            }
+            if (isRunning(id)) {
+                res.status(409).json({ error: 'loop_running' });
+                return;
+            }
+            const loop = (0, loops_store_1.updateLoop)(db, id, { graph: converted.graph }, current);
+            res.json({ loop, nodeIds: converted.nodeIds, issues: converted.issues });
+        }
+        catch (error) {
+            if (error instanceof loops_store_1.LoopPublicationConflict) {
+                res.status(409).json({ error: 'loop_changed' });
+                return;
+            }
+            res.status(400).json({ error: 'conversion_invalid', message: error instanceof Error ? error.message : 'Conversion failed' });
+        }
+    });
+    router.post('/loops/:id/publish', async (req, res) => {
         if (!guard(res))
             return;
         const id = req.params.id;
@@ -243,15 +403,40 @@ function registerLoopsRoutes(router, deps) {
             return;
         }
         try {
-            const loop = (0, loops_store_1.publishLoop)(db, id);
+            const current = (0, loops_store_1.getLoop)(db, id);
+            if ((0, loop_graph_1.isDefinitionGraph)(current.graph)) {
+                const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
+                if (runtime.api?.capabilities?.engineV2 !== 1 || runtime.api?.capabilities?.workflowDefinitions !== 1) {
+                    res.status(409).json({ error: 'engine_unsupported', message: 'Update Core to publish executable workflows.' });
+                    return;
+                }
+                let draft;
+                try {
+                    draft = (0, loop_definition_1.compileLoopToDefinition)(current.graph, { id: current.id, title: current.name, constants: (0, loop_constants_1.loadConstantMap)(db), provider: 'claude', spec: { id: 1, title: 'Sample spec', description: 'Publication preview' } });
+                }
+                catch (error) {
+                    res.status(400).json({ errors: [{ code: 'definition_invalid', message: error instanceof Error ? error.message : 'Invalid workflow' }] });
+                    return;
+                }
+                const validation = runtime.validateWorkflowDefinition(draft, { structural: true });
+                if (!validation.ok) {
+                    res.status(400).json({ errors: validation.errors.map(error => ({ ...error, nodeId: error.nodeId ?? error.path?.match(/^\/nodes\/([^/]+)/)?.[1] })) });
+                    return;
+                }
+            }
+            const loop = (0, loops_store_1.publishLoop)(db, id, current);
             res.json({ loop });
         }
         catch (err) {
+            if (err instanceof loops_store_1.LoopPublicationConflict) {
+                res.status(409).json({ error: err.message, code: 'loop_changed' });
+                return;
+            }
             if (err instanceof loops_store_1.LoopValidationError) {
                 res.status(422).json({ error: 'Loop graph is invalid', errors: err.errors });
                 return;
             }
-            throw err;
+            res.status(503).json({ error: 'runtime_validation_unavailable', message: err instanceof Error ? err.message : 'Core validation unavailable' });
         }
     });
     router.post('/loops/:id/unpublish', (req, res) => {
@@ -262,12 +447,40 @@ function registerLoopsRoutes(router, deps) {
             res.status(404).json({ error: 'Loop not found' });
             return;
         }
+        if (isBuiltin(id)) {
+            res.status(409).json({ error: 'builtin_loop', message: 'Built-in loops stay available on rails. Edit and publish it, or use Restore original.' });
+            return;
+        }
         if (isRunning(id)) {
             res.status(409).json({ error: 'Loop is running; stop the run first' });
             return;
         }
         res.json({ loop: (0, loops_store_1.unpublishLoop)(db, id) });
     });
+    // ── Restore a built-in to its current default ─────────────────────────────────
+    router.post('/loops/:id/restore-builtin', async (req, res) => {
+        if (!guard(res))
+            return;
+        const id = req.params.id;
+        if (!(0, loops_store_1.getLoop)(db, id)) {
+            res.status(404).json({ error: 'Loop not found' });
+            return;
+        }
+        if (!isBuiltin(id)) {
+            res.status(400).json({ error: 'not_builtin', message: 'Only built-in loops can be restored.' });
+            return;
+        }
+        if (isRunning(id)) {
+            res.status(409).json({ error: 'loop_running', message: 'Loop is running; stop the run before restoring it' });
+            return;
+        }
+        const loop = await (0, builtin_loops_1.restoreBuiltin)(db, id, deps.builtinLoops);
+        if (!loop) {
+            res.status(404).json({ error: 'Built-in loop default not found' });
+            return;
+        }
+        res.json({ loop });
+    });
     // ── Duplicate ─────────────────────────────────────────────────────────────────
     router.post('/loops/:id/duplicate', (req, res) => {
         if (!guard(res))
@@ -292,6 +505,10 @@ function registerLoopsRoutes(router, deps) {
             res.status(404).json({ error: 'Loop not found' });
             return;
         }
+        if (isBuiltin(id)) {
+            res.status(409).json({ error: 'builtin_loop', message: BUILTIN_DELETE_MESSAGE });
+            return;
+        }
         if (isRunning(id)) {
             res.status(409).json({ error: 'Loop is running; stop the run before deleting' });
             return;

package/server/dist/modules/loops/runtime/loops-store.js

@@ -1,15 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LoopValidationError = void 0;
+exports.LoopPublicationConflict = exports.LoopValidationError = void 0;
+exports.builtinContentHash = builtinContentHash;
 exports.listLoops = listLoops;
 exports.getLoop = getLoop;
 exports.createLoop = createLoop;
 exports.updateLoop = updateLoop;
+exports.readLegacyLoopGraph = readLegacyLoopGraph;
 exports.publishLoop = publishLoop;
 exports.unpublishLoop = unpublishLoop;
 exports.duplicateLoop = duplicateLoop;
 exports.deleteLoop = deleteLoop;
 exports.importLoops = importLoops;
+exports.seedBuiltinLoops = seedBuiltinLoops;
+exports.restoreBuiltinLoop = restoreBuiltinLoop;
+exports.getBuiltinLoop = getBuiltinLoop;
+exports.readPublishedLoopGraph = readPublishedLoopGraph;
+/**
+ * Loops store — CRUD + Draft/Published lifecycle over the app-level `loops`
+ * table in `desktop.sqlite` (see desktop-db.ts migration 14).
+ *
+ * Definitions are GLOBAL (cross-project): a loop is a reusable recipe consumed
+ * from any project's rail. The third lifecycle state "Running" is NOT stored
+ * here — it is derived from active per-project `loop_runs` and enforced at the
+ * router/service layer (which can see the project registry); this store stays
+ * focused on the persistent definition + the Draft⇄Published transition.
+ */
+const crypto_1 = require("crypto");
 const loop_graph_1 = require("./loop-graph");
 /** Thrown by {@link publishLoop} when the graph fails validation. The router
  *  maps this to a 422 carrying the per-node errors. */
@@ -22,6 +39,11 @@ class LoopValidationError extends Error {
     }
 }
 exports.LoopValidationError = LoopValidationError;
+/** Validation cannot authorize publishing a different edit made while Core loaded. */
+class LoopPublicationConflict extends Error {
+    constructor() { super('Loop changed during validation; reload and publish again'); this.name = 'LoopPublicationConflict'; }
+}
+exports.LoopPublicationConflict = LoopPublicationConflict;
 function mapRow(raw) {
     if (!raw)
         return undefined;
@@ -40,13 +62,25 @@ function mapRow(raw) {
         graph,
         createdAt: raw.created_at,
         updatedAt: raw.updated_at,
+        ...(raw.has_legacy_graph ? { hasLegacyGraph: true } : {}),
+        ...(raw.builtin_id ? {
+            builtinId: raw.builtin_id,
+            builtinModified: builtinContentHash({ name: raw.name, description: raw.description, graph }) !== raw.builtin_default_hash,
+        } : {}),
     };
 }
+/** Content identity of a built-in row (name, description and graph). The
+ *  stored hash is the default last seeded, so equality means "unedited". */
+function builtinContentHash(content) {
+    return (0, crypto_1.createHash)('sha256').update(JSON.stringify([content.name, content.description, content.graph])).digest('hex');
+}
+// Backups can be large; load their contents only for an explicit export.
+const loopColumns = 'id, name, description, status, graph, created_at, updated_at, (graph_legacy IS NOT NULL) AS has_legacy_graph, builtin_id, builtin_default_hash';
 function listLoops(db) {
-    return db.prepare('SELECT * FROM loops ORDER BY updated_at DESC, created_at DESC').all().map((r) => mapRow(r));
+    return db.prepare(`SELECT ${loopColumns} FROM loops ORDER BY updated_at DESC, created_at DESC`).all().map((r) => mapRow(r));
 }
 function getLoop(db, id) {
-    return mapRow(db.prepare('SELECT * FROM loops WHERE id = ?').get(id));
+    return mapRow(db.prepare(`SELECT ${loopColumns} FROM loops WHERE id = ?`).get(id));
 }
 /** Create a new loop. Always starts as a Draft. `graph` defaults to an empty
  *  (structurally-invalid-to-publish) canvas the user fills in the builder. */
@@ -60,30 +94,56 @@ function createLoop(db, input) {
  * Published loop un-publishes it — it must be re-validated and re-published
  * before it is offered in the rail picker again).
  */
-function updateLoop(db, id, patch) {
-    const existing = getLoop(db, id);
-    if (!existing)
+function updateLoop(db, id, patch, expected) {
+    return db.transaction(() => {
+        const existing = getLoop(db, id);
+        if (expected && (!existing || JSON.stringify([existing.name, existing.description, existing.graph, existing.status]) !==
+            JSON.stringify([expected.name, expected.description, expected.graph, expected.status])))
+            throw new LoopPublicationConflict();
+        if (!existing)
+            return undefined;
+        const name = patch.name ?? existing.name;
+        const description = patch.description !== undefined ? patch.description : existing.description;
+        const graph = patch.graph ?? existing.graph;
+        const converting = patch.graph !== undefined && Array.isArray(graph.nodes) && graph.nodes.some(node => node?.type === 'core') &&
+            Array.isArray(existing.graph.nodes) && existing.graph.nodes.some(node => ['ai-step', 'shell', 'decider', 'condition'].includes(node?.type));
+        // Both expressions read the old row. A failed save cannot leave a backup
+        // that claims a conversion happened, and retries cannot replace its bytes.
+        db.prepare(`UPDATE loops SET name = ?, description = ?,
+      graph_legacy = CASE WHEN ? THEN COALESCE(graph_legacy, graph) ELSE graph_legacy END,
+      graph_legacy_saved_at = CASE WHEN ? THEN COALESCE(graph_legacy_saved_at, datetime('now')) ELSE graph_legacy_saved_at END,
+      graph = ?, status = 'draft', updated_at = datetime('now') WHERE id = ?`)
+            .run(name, description, Number(converting), Number(converting), JSON.stringify(graph), id);
+        return getLoop(db, id);
+    }).immediate();
+}
+/** Read-only original export; does not restore, publish or execute a graph. */
+function readLegacyLoopGraph(db, id) {
+    const row = db.prepare('SELECT graph_legacy, graph_legacy_saved_at FROM loops WHERE id = ?').get(id);
+    if (!row?.graph_legacy || !row.graph_legacy_saved_at)
         return undefined;
-    const name = patch.name ?? existing.name;
-    const description = patch.description !== undefined ? patch.description : existing.description;
-    const graph = patch.graph ?? existing.graph;
-    db.prepare(`UPDATE loops SET name = ?, description = ?, graph = ?, status = 'draft', updated_at = datetime('now') WHERE id = ?`).run(name, description, JSON.stringify(graph), id);
-    return getLoop(db, id);
+    return { graph: JSON.parse(row.graph_legacy), savedAt: row.graph_legacy_saved_at };
 }
 /**
  * Validate the graph and, if valid, mark the loop Published (so it becomes
  * selectable in the rail picker). Throws {@link LoopValidationError} otherwise,
  * leaving the loop in Draft.
  */
-function publishLoop(db, id) {
-    const existing = getLoop(db, id);
-    if (!existing)
-        return undefined;
-    const result = (0, loop_graph_1.validateLoopGraph)(existing.graph);
-    if (!result.valid)
-        throw new LoopValidationError(result.errors);
-    db.prepare(`UPDATE loops SET status = 'published', updated_at = datetime('now') WHERE id = ?`).run(id);
-    return getLoop(db, id);
+function publishLoop(db, id, validated) {
+    return db.transaction(() => {
+        const existing = getLoop(db, id);
+        if (validated && (!existing || JSON.stringify([existing.name, existing.description, existing.graph, existing.status]) !==
+            JSON.stringify([validated.name, validated.description, validated.graph, validated.status])))
+            throw new LoopPublicationConflict();
+        if (!existing)
+            return undefined;
+        const result = (0, loop_graph_1.validateLoopGraph)(existing.graph);
+        if (!result.valid)
+            throw new LoopValidationError(result.errors);
+        // The snapshot is what rails launch while a later edit is still Draft.
+        db.prepare(`UPDATE loops SET status = 'published', published_graph = graph, updated_at = datetime('now') WHERE id = ?`).run(id);
+        return getLoop(db, id);
+    }).immediate();
 }
 /** Return a Published loop to Draft without changing its content. */
 function unpublishLoop(db, id) {
@@ -135,3 +195,63 @@ function importLoops(db, items, mintId) {
     }
     return { imported, skipped };
 }
+/**
+ * Ensure one published row per built-in default. Missing rows are inserted
+ * (`INSERT OR IGNORE`, so concurrent seeders converge on one row). With
+ * `refresh`, a row whose content still equals the default it was seeded with
+ * (unedited) is moved to the new default when that default changed — user edits
+ * are never overwritten. Rows for built-ins absent from `defaults` are kept.
+ */
+function seedBuiltinLoops(db, defaults, options) {
+    const result = { inserted: [], refreshed: [] };
+    db.transaction(() => {
+        for (const builtin of defaults) {
+            const hash = builtinContentHash({ name: builtin.name, description: builtin.description, graph: builtin.graph });
+            const graph = JSON.stringify(builtin.graph);
+            const inserted = db.prepare(`INSERT OR IGNORE INTO loops
+        (id, name, description, status, graph, builtin_id, builtin_default_hash, published_graph)
+        VALUES (?, ?, ?, 'published', ?, ?, ?, ?)`)
+                .run(builtin.id, builtin.name, builtin.description, graph, builtin.id, hash, graph);
+            if (inserted.changes > 0) {
+                result.inserted.push(builtin.id);
+                continue;
+            }
+            if (!options.refresh)
+                continue;
+            const row = db.prepare(`SELECT ${loopColumns} FROM loops WHERE builtin_id = ?`).get(builtin.id);
+            const current = mapRow(row);
+            if (!row || !current || current.builtinModified || row.builtin_default_hash === hash)
+                continue;
+            db.prepare(`UPDATE loops SET name = ?, description = ?, graph = ?, status = 'published', published_graph = ?,
+        builtin_default_hash = ?, updated_at = datetime('now') WHERE builtin_id = ?`)
+                .run(builtin.name, builtin.description, graph, graph, hash, builtin.id);
+            result.refreshed.push(builtin.id);
+        }
+    }).immediate();
+    return result;
+}
+/** Reset a built-in row to `builtin` (its current default), Published. */
+function restoreBuiltinLoop(db, builtin) {
+    const hash = builtinContentHash({ name: builtin.name, description: builtin.description, graph: builtin.graph });
+    const graph = JSON.stringify(builtin.graph);
+    const updated = db.prepare(`UPDATE loops SET name = ?, description = ?, graph = ?, status = 'published', published_graph = ?,
+    builtin_default_hash = ?, updated_at = datetime('now') WHERE builtin_id = ?`)
+        .run(builtin.name, builtin.description, graph, graph, hash, builtin.id);
+    return updated.changes > 0 ? getLoop(db, builtin.id) : undefined;
+}
+/** The built-in row for a canonical factory id, when seeded. */
+function getBuiltinLoop(db, builtinId) {
+    return mapRow(db.prepare(`SELECT ${loopColumns} FROM loops WHERE builtin_id = ?`).get(builtinId));
+}
+/** Last published graph snapshot (null when the loop was never published). */
+function readPublishedLoopGraph(db, id) {
+    const row = db.prepare('SELECT published_graph FROM loops WHERE id = ?').get(id);
+    if (!row?.published_graph)
+        return undefined;
+    try {
+        return JSON.parse(row.published_graph);
+    }
+    catch {
+        return undefined;
+    }
+}