devchain-cli 0.22.0 → 0.23.0

package/dist/server/modules/storage/local/delegates/epic.delegate.js

@@ -36,12 +36,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EpicStorageDelegate = void 0;
 const drizzle_orm_1 = require("drizzle-orm");
 const node_crypto_1 = require("node:crypto");
+const domain_models_1 = require("../../models/domain.models");
 const error_types_1 = require("../../../../common/errors/error-types");
 const logger_1 = require("../../../../common/logging/logger");
 const schema_1 = require("../../db/schema");
 const storage_helpers_1 = require("../helpers/storage-helpers");
 const base_storage_delegate_1 = require("./base-storage.delegate");
 const logger = (0, logger_1.createLogger)('EpicStorageDelegate');
+const MAX_RELATION_BATCH_SIZE = 1000;
+const MAX_RELATION_LIST_LIMIT = 100;
+const MAX_RELATION_PREFIX_RESULTS = 100;
 class EpicStorageDelegate extends base_storage_delegate_1.BaseStorageDelegate {
     dependencies;
     constructor(context, dependencies) {
@@ -51,11 +55,14 @@ class EpicStorageDelegate extends base_storage_delegate_1.BaseStorageDelegate {
     async createEpic(data, eventFactory) {
         return this.txRunner.runImmediateQueued(() => this.insertEpic(data, eventFactory));
     }
-    async createEpicInCurrentTransaction(data, eventFactory) {
+    async createEpicInCurrentTransaction(data, eventFactory, beforeEventAppend) {
         if (!this.rawClient.inTransaction) {
             throw new error_types_1.StorageError('Epic transaction insert requires an active storage transaction.');
         }
-        return this.insertEpic(data, eventFactory);
+        const epic = this.insertEpic(data);
+        await beforeEventAppend?.(epic);
+        this.appendEpicEvent(epic, eventFactory);
+        return epic;
     }
     insertEpic(data, eventFactory) {
         const now = new Date().toISOString();
@@ -121,11 +128,14 @@ class EpicStorageDelegate extends base_storage_delegate_1.BaseStorageDelegate {
                     .run();
             }
         }
+        this.appendEpicEvent(epic, eventFactory);
+        return epic;
+    }
+    appendEpicEvent(epic, eventFactory) {
         const event = eventFactory?.(epic);
         if (event) {
             this.dependencies.appendEvent(event);
         }
-        return epic;
     }
     async getEpic(id) {
         return this.getEpicSync(id);
@@ -201,8 +211,9 @@ class EpicStorageDelegate extends base_storage_delegate_1.BaseStorageDelegate {
         };
     }
     async listProjectEpics(projectId, options = {}) {
-        const { epics, statuses } = await Promise.resolve().then(() => __importStar(require('../../db/schema')));
+        const { epics, statuses, externalTaskLinks } = await Promise.resolve().then(() => __importStar(require('../../db/schema')));
         const { eq, and, sql, desc } = await Promise.resolve().then(() => __importStar(require('drizzle-orm')));
+        const { safeJsonText } = await Promise.resolve().then(() => __importStar(require('../../db/sqlite-json')));
         const limit = options.limit ?? 100;
         const offset = options.offset ?? 0;
         const conditions = [eq(epics.projectId, projectId)];
@@ -210,13 +221,19 @@ class EpicStorageDelegate extends base_storage_delegate_1.BaseStorageDelegate {
             const search = options.q.trim().toLowerCase();
             if (search.length) {
                 const pattern = `%${search}%`;
+                const externalIdentifierMatch = sql `EXISTS (
+          SELECT 1 FROM ${externalTaskLinks}
+          WHERE ${externalTaskLinks.epicId} = ${epics.id}
+            AND (lower(${externalTaskLinks.remoteTaskId}) LIKE ${pattern}
+              OR lower(${safeJsonText(externalTaskLinks.sourceSnapshot, '$.remoteKey')}) LIKE ${pattern})
+        )`;
                 const isUuidPrefix = search.length >= 8 && /^[a-f0-9-]+$/.test(search);
                 if (isUuidPrefix) {
                     const idPrefixPattern = `${search}%`;
-                    conditions.push(sql `(lower(${epics.title}) LIKE ${pattern} OR lower(ifnull(${epics.description}, '')) LIKE ${pattern} OR ${epics.id} LIKE ${idPrefixPattern})`);
+                    conditions.push(sql `(lower(${epics.title}) LIKE ${pattern} OR lower(ifnull(${epics.description}, '')) LIKE ${pattern} OR ${epics.id} LIKE ${idPrefixPattern} OR ${externalIdentifierMatch})`);
                 }
                 else {
-                    conditions.push(sql `(lower(${epics.title}) LIKE ${pattern} OR lower(ifnull(${epics.description}, '')) LIKE ${pattern})`);
+                    conditions.push(sql `(lower(${epics.title}) LIKE ${pattern} OR lower(ifnull(${epics.description}, '')) LIKE ${pattern} OR ${externalIdentifierMatch})`);
                 }
             }
         }
@@ -372,6 +389,12 @@ class EpicStorageDelegate extends base_storage_delegate_1.BaseStorageDelegate {
             versionOf: (current) => current.version,
             prepare: ({ current }) => {
                 if (data.parentId !== undefined) {
+                    if (data.parentId !== current.parentId) {
+                        this.ensureEpicIsNotRouteEndpointSync(id);
+                    }
+                    if (data.parentId === null && current.parentId !== null) {
+                        this.assertPromotionKeepsEligibleRoutesSync(id, current.projectId);
+                    }
                     this.ensureValidEpicParentSync(current.projectId, data.parentId ?? null, id);
                 }
                 if (data.agentId !== undefined) {
@@ -436,8 +459,14 @@ class EpicStorageDelegate extends base_storage_delegate_1.BaseStorageDelegate {
             if (rows.length === 0) {
                 throw new error_types_1.NotFoundError('Epic', id);
             }
+            const { workspace_id: workspaceId } = this.rawClient
+                .prepare(`SELECT project.workspace_id
+           FROM epics epic
+           INNER JOIN projects project ON project.id = epic.project_id
+           WHERE epic.id = ?`)
+                .get(id);
             for (const row of rows) {
-                const event = eventFactory?.(this.getEpicSync(row.id));
+                const event = eventFactory?.(this.getEpicSync(row.id), workspaceId);
                 if (event) {
                     this.dependencies.appendEvent(event);
                 }
@@ -651,27 +680,35 @@ class EpicStorageDelegate extends base_storage_delegate_1.BaseStorageDelegate {
             offset,
         };
     }
-    async createEpicComment(data) {
-        await this.getEpic(data.epicId);
-        const { randomUUID } = await Promise.resolve().then(() => __importStar(require('crypto')));
-        const { epicComments } = await Promise.resolve().then(() => __importStar(require('../../db/schema')));
+    async createEpicComment(data, eventFactory) {
+        return this.txRunner.runImmediateQueued(() => this.insertEpicComment(data, eventFactory));
+    }
+    insertEpicComment(data, eventFactory) {
+        const epic = this.getEpicSync(data.epicId);
         const now = new Date().toISOString();
         const comment = {
-            id: randomUUID(),
+            id: (0, node_crypto_1.randomUUID)(),
             epicId: data.epicId,
             authorName: data.authorName,
             content: data.content,
             createdAt: now,
             updatedAt: now,
         };
-        await this.db.insert(epicComments).values({
+        this.db
+            .insert(schema_1.epicComments)
+            .values({
             id: comment.id,
             epicId: comment.epicId,
             authorName: comment.authorName,
             content: comment.content,
             createdAt: comment.createdAt,
             updatedAt: comment.updatedAt,
-        });
+        })
+            .run();
+        const event = eventFactory?.(comment, epic);
+        if (event) {
+            this.dependencies.appendEvent(event);
+        }
         return comment;
     }
     async deleteEpicComment(id) {
@@ -695,6 +732,661 @@ class EpicStorageDelegate extends base_storage_delegate_1.BaseStorageDelegate {
             .from(epics)
             .where(and(eq(epics.projectId, projectId), sql `substr(${epics.id}, 1, ${prefix.length}) = ${prefix}`));
     }
+    async setEpicRelation(data, context) {
+        return this.txRunner.runImmediateQueuedOrJoin(() => {
+            const [focal, related] = this.validateRelationPairSync(data.epicId, data.relatedEpicId);
+            this.authorizeRelationWriteSync(focal, related, context);
+            const { leftEpicId, rightEpicId } = this.canonicalRelationPair(focal.id, related.id);
+            const { type, direction } = this.toStoredRelation(focal.id, leftEpicId, data.type);
+            const createdBy = data.createdBy ?? null;
+            const createdByAgentId = data.createdByAgentId ?? null;
+            if (createdBy !== null && createdBy !== 'user' && createdBy !== 'agent') {
+                throw new error_types_1.ValidationError('Relation creator type must be user or agent.');
+            }
+            if (createdByAgentId !== null) {
+                if (createdBy !== 'agent') {
+                    throw new error_types_1.ValidationError('An agent relation creator requires createdBy="agent".');
+                }
+                const creator = this.dependencies.getAgent(createdByAgentId);
+                if (creator.projectId !== focal.project_id) {
+                    throw new error_types_1.ValidationError('Relation creator must belong to the focal Epic project.', {
+                        createdByAgentId,
+                        projectId: focal.project_id,
+                    });
+                }
+            }
+            const existing = this.rawClient
+                .prepare(`SELECT id, left_epic_id, right_epic_id, type, direction,
+                  created_by, created_by_agent_id, created_at, updated_at
+           FROM epic_relations
+           WHERE left_epic_id = ? AND right_epic_id = ?`)
+                .get(leftEpicId, rightEpicId);
+            if (existing?.type === type && existing.direction === direction) {
+                return {
+                    ...this.mapEpicRelation(existing),
+                    changed: false,
+                    workspaceId: focal.workspace_id,
+                };
+            }
+            const pairEligible = focal.parent_id === null &&
+                related.parent_id === null &&
+                focal.project_id === related.project_id;
+            const directedEffect = type === 'related' ? (0, domain_models_1.resolveRelationEndpoints)(leftEpicId, rightEpicId, direction) : null;
+            const newEligibleRoute = pairEligible ? directedEffect : null;
+            const oldEffect = existing && existing.type === 'related' && existing.direction !== 'none' && pairEligible
+                ? (0, domain_models_1.resolveRelationEndpoints)(existing.left_epic_id, existing.right_epic_id, existing.direction)
+                : null;
+            const effectUnchanged = newEligibleRoute !== null &&
+                oldEffect !== null &&
+                newEligibleRoute.sourceEpicId === oldEffect.sourceEpicId &&
+                newEligibleRoute.targetEpicId === oldEffect.targetEpicId;
+            const displacedEffects = [];
+            if (oldEffect !== null && !effectUnchanged) {
+                displacedEffects.push(oldEffect);
+            }
+            if (newEligibleRoute) {
+                const otherRoute = this.findOutgoingEligibleRouteSync(newEligibleRoute.sourceEpicId, existing?.id);
+                if (otherRoute) {
+                    displacedEffects.push(otherRoute);
+                }
+            }
+            if (displacedEffects.length > 1) {
+                throw new error_types_1.ValidationError('This change would displace two active time routes. Delete one Related pair explicitly first, then retry the change.', { displacedEffects });
+            }
+            const displacedEffect = displacedEffects[0] ?? null;
+            if (displacedEffect) {
+                const accepted = data.acceptedRouteEffect;
+                if (context.trustedLocalHuman !== true ||
+                    !accepted ||
+                    accepted.sourceEpicId !== displacedEffect.sourceEpicId ||
+                    accepted.targetEpicId !== displacedEffect.targetEpicId) {
+                    throw new error_types_1.RelationConfirmationRequiredError(displacedEffect);
+                }
+            }
+            if (newEligibleRoute) {
+                this.assertNoEligibleRouteCycleSync(newEligibleRoute, existing?.id);
+            }
+            const id = (0, node_crypto_1.randomUUID)();
+            const now = new Date().toISOString();
+            this.rawClient
+                .prepare(`INSERT INTO epic_relations (
+             id, left_epic_id, right_epic_id, type, direction,
+             created_by, created_by_agent_id, created_at, updated_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(left_epic_id, right_epic_id) DO UPDATE SET
+             type = excluded.type,
+             direction = excluded.direction,
+             updated_at = excluded.updated_at`)
+                .run(id, leftEpicId, rightEpicId, type, direction, createdBy, createdByAgentId, now, now);
+            if (newEligibleRoute) {
+                this.deleteOutgoingEligibleRouteSync(newEligibleRoute.sourceEpicId, leftEpicId, rightEpicId);
+            }
+            const row = this.rawClient
+                .prepare(`SELECT id, left_epic_id, right_epic_id, type, direction,
+                  created_by, created_by_agent_id, created_at, updated_at
+           FROM epic_relations
+           WHERE left_epic_id = ? AND right_epic_id = ?`)
+                .get(leftEpicId, rightEpicId);
+            return {
+                ...this.mapEpicRelation(row),
+                changed: true,
+                workspaceId: focal.workspace_id,
+            };
+        });
+    }
+    async deleteEpicRelation(epicId, relatedEpicId, context) {
+        return this.txRunner.runImmediateQueuedOrJoin(() => {
+            const [focal, related] = this.validateRelationPairSync(epicId, relatedEpicId);
+            this.authorizeRelationWriteSync(focal, related, context);
+            const pair = this.canonicalRelationPair(focal.id, related.id);
+            const deleted = this.rawClient
+                .prepare('DELETE FROM epic_relations WHERE left_epic_id = ? AND right_epic_id = ?')
+                .run(pair.leftEpicId, pair.rightEpicId).changes > 0;
+            return { deleted, workspaceId: focal.workspace_id };
+        });
+    }
+    async listEpicRelations(epicId, options = {}) {
+        const focal = this.getRelationContextSync(epicId);
+        this.assertRelationReadWorkspace(focal, options);
+        const limit = this.normalizeRelationListLimit(options.limit, 'Relation');
+        const offset = this.normalizeRelationListOffset(options.offset, 'Relation');
+        const relatedEpicId = options.relatedEpicId ?? null;
+        const queryArgs = [
+            epicId,
+            epicId,
+            epicId,
+            options.excludeMcpHidden ? 1 : 0,
+            relatedEpicId,
+            relatedEpicId,
+        ];
+        const count = this.rawClient
+            .prepare(`SELECT COUNT(*) AS total
+         FROM epic_relations relation
+         INNER JOIN epics target
+           ON target.id = CASE
+             WHEN relation.left_epic_id = ? THEN relation.right_epic_id
+             ELSE relation.left_epic_id
+           END
+         INNER JOIN statuses status ON status.id = target.status_id
+         WHERE (relation.left_epic_id = ? OR relation.right_epic_id = ?)
+           AND (? = 0 OR status.mcp_hidden = 0)
+           AND (? IS NULL OR target.id = ?)`)
+            .get(...queryArgs);
+        const rows = this.rawClient
+            .prepare(`SELECT
+           relation.id AS relation_id,
+           relation.left_epic_id,
+           relation.right_epic_id,
+           relation.type,
+           relation.direction,
+           relation.created_at,
+           relation.updated_at,
+           target.id AS epic_id,
+           target.project_id,
+           project.name AS project_name,
+           target.title,
+           target.status_id,
+           status.label AS status_label,
+           status.color AS status_color,
+           status.mcp_hidden AS status_mcp_hidden
+         FROM epic_relations relation
+         INNER JOIN epics target
+           ON target.id = CASE
+             WHEN relation.left_epic_id = ? THEN relation.right_epic_id
+             ELSE relation.left_epic_id
+           END
+         INNER JOIN projects project ON project.id = target.project_id
+         INNER JOIN statuses status ON status.id = target.status_id
+         WHERE (relation.left_epic_id = ? OR relation.right_epic_id = ?)
+           AND (? = 0 OR status.mcp_hidden = 0)
+           AND (? IS NULL OR target.id = ?)
+         ORDER BY lower(project.name), lower(target.title), target.id
+         LIMIT ? OFFSET ?`)
+            .all(...queryArgs, limit, offset);
+        return {
+            items: rows.map((row) => {
+                const endpoints = (0, domain_models_1.resolveRelationEndpoints)(row.left_epic_id, row.right_epic_id, row.direction);
+                return {
+                    relationId: row.relation_id,
+                    epicId: row.epic_id,
+                    projectId: row.project_id,
+                    projectName: row.project_name,
+                    title: row.title,
+                    statusId: row.status_id,
+                    statusLabel: row.status_label,
+                    statusColor: row.status_color,
+                    statusMcpHidden: Boolean(row.status_mcp_hidden),
+                    type: this.toFocalRelationType(epicId, row),
+                    sourceEpicId: endpoints?.sourceEpicId ?? null,
+                    targetEpicId: endpoints?.targetEpicId ?? null,
+                    createdAt: row.created_at,
+                    updatedAt: row.updated_at,
+                };
+            }),
+            total: count.total,
+            limit,
+            offset,
+        };
+    }
+    async summarizeEpicRelationsBatch(epicIds, options = {}) {
+        if (!Array.isArray(epicIds)) {
+            throw new error_types_1.ValidationError('epicIds must be an array.');
+        }
+        const uniqueIds = Array.from(new Set(epicIds.map((id) => (typeof id === 'string' ? id.trim() : ''))));
+        if (uniqueIds.some((id) => id.length === 0)) {
+            throw new error_types_1.ValidationError('epicIds must contain non-empty strings.');
+        }
+        if (uniqueIds.length > MAX_RELATION_BATCH_SIZE) {
+            throw new error_types_1.ValidationError(`epicIds cannot contain more than ${MAX_RELATION_BATCH_SIZE} IDs.`);
+        }
+        if (uniqueIds.length === 0)
+            return new Map();
+        const rows = this.rawClient
+            .prepare(`WITH requested(epic_id) AS (
+           SELECT value FROM json_each(?)
+         ), focal_relations AS (
+           SELECT relation.left_epic_id AS epic_id,
+                  relation.right_epic_id AS target_epic_id,
+                  relation.type, relation.direction, 1 AS focal_is_left
+           FROM epic_relations relation
+           UNION ALL
+           SELECT relation.right_epic_id AS epic_id,
+                  relation.left_epic_id AS target_epic_id,
+                  relation.type, relation.direction, 0 AS focal_is_left
+           FROM epic_relations relation
+         )
+         SELECT
+           focal.epic_id,
+           SUM(CASE WHEN focal.type = 'related' THEN 1 ELSE 0 END) AS related,
+           SUM(CASE WHEN focal.type = 'related' AND (
+             (focal.focal_is_left = 1 AND focal.direction = 'left_to_right') OR
+             (focal.focal_is_left = 0 AND focal.direction = 'right_to_left')
+           ) THEN 1 ELSE 0 END) AS related_targets,
+           SUM(CASE WHEN focal.type = 'related' AND (
+             (focal.focal_is_left = 1 AND focal.direction = 'right_to_left') OR
+             (focal.focal_is_left = 0 AND focal.direction = 'left_to_right')
+           ) THEN 1 ELSE 0 END) AS related_sources,
+           SUM(CASE WHEN focal.type = 'related' AND focal.direction = 'none' THEN 1 ELSE 0 END) AS related_neutral,
+           SUM(CASE WHEN focal.type = 'blocks' AND (
+             (focal.focal_is_left = 1 AND focal.direction = 'left_to_right') OR
+             (focal.focal_is_left = 0 AND focal.direction = 'right_to_left')
+           ) THEN 1 ELSE 0 END) AS blocks,
+           SUM(CASE WHEN focal.type = 'blocks' AND (
+             (focal.focal_is_left = 1 AND focal.direction = 'right_to_left') OR
+             (focal.focal_is_left = 0 AND focal.direction = 'left_to_right')
+           ) THEN 1 ELSE 0 END) AS blocked_by,
+           COUNT(*) AS total
+         FROM requested
+         INNER JOIN focal_relations focal ON focal.epic_id = requested.epic_id
+         INNER JOIN epics target ON target.id = focal.target_epic_id
+         INNER JOIN statuses target_status ON target_status.id = target.status_id
+         INNER JOIN epics focal_epic ON focal_epic.id = focal.epic_id
+         INNER JOIN projects focal_project ON focal_project.id = focal_epic.project_id
+         WHERE (? = 0 OR target_status.mcp_hidden = 0)
+           AND (? IS NULL OR focal_project.workspace_id = ?)
+         GROUP BY focal.epic_id`)
+            .all(JSON.stringify(uniqueIds), options.excludeMcpHidden ? 1 : 0, options.workspaceId ?? null, options.workspaceId ?? null);
+        return new Map(rows.map((row) => [
+            row.epic_id,
+            {
+                epicId: row.epic_id,
+                related: Number(row.related),
+                relatedTargets: Number(row.related_targets),
+                relatedSources: Number(row.related_sources),
+                relatedNeutral: Number(row.related_neutral),
+                blocks: Number(row.blocks),
+                blockedBy: Number(row.blocked_by),
+                total: Number(row.total),
+            },
+        ]));
+    }
+    async listEpicRelationCandidates(epicId, options = {}) {
+        const focal = this.getRelationContextSync(epicId);
+        this.assertRelationReadWorkspace(focal, options);
+        const limit = this.normalizeRelationListLimit(options.limit, 'Relation candidate');
+        const offset = this.normalizeRelationListOffset(options.offset, 'Relation candidate');
+        const search = typeof options.q === 'string' ? options.q.trim().toLowerCase() : '';
+        if (search.length > 200) {
+            throw new error_types_1.ValidationError('Relation candidate search cannot exceed 200 characters.');
+        }
+        const conditions = [
+            'project.workspace_id = ?',
+            'project.is_template = 0',
+            '(? = 0 OR status.mcp_hidden = 0)',
+            'candidate.id <> ?',
+            '(candidate.parent_id IS NULL OR candidate.parent_id <> ?)',
+            '(? IS NULL OR candidate.id <> ?)',
+            `NOT EXISTS (
+         SELECT 1 FROM epic_relations existing
+         WHERE (existing.left_epic_id = ? AND existing.right_epic_id = candidate.id)
+            OR (existing.right_epic_id = ? AND existing.left_epic_id = candidate.id)
+       )`,
+        ];
+        const parameters = [
+            focal.workspace_id,
+            options.excludeMcpHidden ? 1 : 0,
+            focal.id,
+            focal.id,
+            focal.parent_id,
+            focal.parent_id,
+            focal.id,
+            focal.id,
+        ];
+        if (search) {
+            const escapedSearch = search.replace(/[\\%_]/g, '\\$&');
+            conditions.push(`(lower(candidate.title) LIKE ? ESCAPE '\\'
+          OR lower(substr(candidate.id, 1, ?)) = ?)`);
+            parameters.push(`%${escapedSearch}%`, search.length, search);
+        }
+        const where = conditions.join('\n AND ');
+        const totalRow = this.rawClient
+            .prepare(`SELECT COUNT(*) AS count
+         FROM epics candidate
+         INNER JOIN projects project ON project.id = candidate.project_id
+         INNER JOIN statuses status ON status.id = candidate.status_id
+         WHERE ${where}`)
+            .get(...parameters);
+        const rows = this.rawClient
+            .prepare(`SELECT candidate.id, candidate.project_id, project.name AS project_name,
+                candidate.title, candidate.status_id, status.label AS status_label,
+                status.color AS status_color, status.mcp_hidden AS status_mcp_hidden,
+                candidate.parent_id
+         FROM epics candidate
+         INNER JOIN projects project ON project.id = candidate.project_id
+         INNER JOIN statuses status ON status.id = candidate.status_id
+         WHERE ${where}
+         ORDER BY lower(project.name), lower(candidate.title), candidate.id
+         LIMIT ? OFFSET ?`)
+            .all(...parameters, limit, offset);
+        return {
+            items: rows.map((row) => this.mapRelationCandidate(row)),
+            total: Number(totalRow.count),
+            limit,
+            offset,
+        };
+    }
+    async getWorkspaceEpicsByIdPrefix(epicId, prefix, options = {}) {
+        const focal = this.getRelationContextSync(epicId);
+        this.assertRelationReadWorkspace(focal, options);
+        const normalizedPrefix = typeof prefix === 'string' ? prefix.trim().toLowerCase() : '';
+        if (!/^[a-f0-9-]{8,36}$/.test(normalizedPrefix)) {
+            return [];
+        }
+        const rows = this.rawClient
+            .prepare(`SELECT candidate.id, candidate.project_id, project.name AS project_name,
+                candidate.title, candidate.status_id, status.label AS status_label,
+                status.color AS status_color, status.mcp_hidden AS status_mcp_hidden,
+                candidate.parent_id
+         FROM epics candidate
+         INNER JOIN projects project ON project.id = candidate.project_id
+         INNER JOIN statuses status ON status.id = candidate.status_id
+         WHERE project.workspace_id = ?
+           AND project.is_template = 0
+           AND (? = 0 OR status.mcp_hidden = 0)
+           AND candidate.id <> ?
+           AND lower(substr(candidate.id, 1, ?)) = ?
+         ORDER BY candidate.id
+         LIMIT ?`)
+            .all(focal.workspace_id, options.excludeMcpHidden ? 1 : 0, focal.id, normalizedPrefix.length, normalizedPrefix, MAX_RELATION_PREFIX_RESULTS);
+        return rows.map((row) => this.mapRelationCandidate(row));
+    }
+    validateRelationPairSync(epicId, relatedEpicId) {
+        if (typeof epicId !== 'string' || typeof relatedEpicId !== 'string') {
+            throw new error_types_1.ValidationError('Relation Epic IDs must be strings.');
+        }
+        if (epicId === relatedEpicId) {
+            throw new error_types_1.ValidationError('An Epic cannot have a relation to itself.', { epicId });
+        }
+        const focal = this.getRelationContextSync(epicId);
+        let related;
+        try {
+            related = this.getRelationContextSync(relatedEpicId);
+        }
+        catch (error) {
+            if (error instanceof error_types_1.NotFoundError) {
+                throw new error_types_1.NotFoundError('Related Epic');
+            }
+            throw error;
+        }
+        if (focal.workspace_id !== related.workspace_id) {
+            throw new error_types_1.NotFoundError('Related Epic');
+        }
+        if (focal.parent_id === related.id || related.parent_id === focal.id) {
+            throw new error_types_1.ValidationError('A parent and direct sub-Epic cannot have a relation.', {
+                epicId,
+                relatedEpicId,
+            });
+        }
+        return [focal, related];
+    }
+    authorizeRelationWriteSync(focal, related, context) {
+        if (context?.actor?.type === 'guest') {
+            throw new error_types_1.ForbiddenError('Guests cannot write Epic relations.');
+        }
+        if (context?.trustedLocalHuman === true && !context.actor) {
+            return;
+        }
+        if (context?.actor?.type !== 'agent') {
+            throw new error_types_1.ForbiddenError('An authorized relation writer is required.');
+        }
+        const currentAgent = this.rawClient
+            .prepare('SELECT project_id, is_project_owner FROM agents WHERE id = ?')
+            .get(context.actor.id);
+        if (!currentAgent || currentAgent.project_id !== focal.project_id) {
+            throw new error_types_1.ForbiddenError('The caller must currently belong to the focal Epic project.');
+        }
+        if (related.project_id !== focal.project_id && !Boolean(currentAgent.is_project_owner)) {
+            throw new error_types_1.ForbiddenError('Cross-project Epic relations require the focal project current Project Owner.');
+        }
+    }
+    assertRelationReadWorkspace(focal, options) {
+        if (options.workspaceId && focal.workspace_id !== options.workspaceId) {
+            throw new error_types_1.NotFoundError('Epic');
+        }
+    }
+    getRelationContextSync(epicId) {
+        const row = this.rawClient
+            .prepare(`SELECT epic.id, epic.project_id, project.workspace_id, epic.parent_id
+         FROM epics epic
+         INNER JOIN projects project ON project.id = epic.project_id
+         WHERE epic.id = ?`)
+            .get(epicId);
+        if (!row) {
+            throw new error_types_1.NotFoundError('Epic', epicId);
+        }
+        return row;
+    }
+    canonicalRelationPair(epicId, relatedEpicId) {
+        return epicId < relatedEpicId
+            ? { leftEpicId: epicId, rightEpicId: relatedEpicId }
+            : { leftEpicId: relatedEpicId, rightEpicId: epicId };
+    }
+    toStoredRelation(focalEpicId, leftEpicId, focalType) {
+        const focalIsLeft = focalEpicId === leftEpicId;
+        if (focalType === 'related') {
+            return { type: 'related', direction: focalIsLeft ? 'left_to_right' : 'right_to_left' };
+        }
+        if (focalType !== 'blocks' && focalType !== 'blocked_by') {
+            throw new error_types_1.ValidationError('Relation type must be related, blocks, or blocked_by.');
+        }
+        const leftBlocksRight = focalType === 'blocks' ? focalIsLeft : !focalIsLeft;
+        return {
+            type: 'blocks',
+            direction: leftBlocksRight ? 'left_to_right' : 'right_to_left',
+        };
+    }
+    static ELIGIBLE_ROUTE_SOURCE_PREDICATE = `
+      relation.type = 'related'
+      AND relation.direction != 'none'
+      AND left_epic.parent_id IS NULL
+      AND right_epic.parent_id IS NULL
+      AND left_epic.project_id = right_epic.project_id
+      AND (
+        (relation.left_epic_id = ? AND relation.direction = 'left_to_right')
+        OR (relation.right_epic_id = ? AND relation.direction = 'right_to_left')
+      )`;
+    assertNoEligibleRouteCycleSync(newEffect, replacedRowId) {
+        const outgoing = this.rawClient.prepare(`SELECT relation.id, relation.left_epic_id, relation.right_epic_id, relation.direction
+       FROM epic_relations relation
+       INNER JOIN epics left_epic ON left_epic.id = relation.left_epic_id
+       INNER JOIN epics right_epic ON right_epic.id = relation.right_epic_id
+       WHERE${EpicStorageDelegate.ELIGIBLE_ROUTE_SOURCE_PREDICATE}`);
+        const visited = new Set([newEffect.targetEpicId]);
+        let current = newEffect.targetEpicId;
+        for (let step = 0; step <= MAX_RELATION_BATCH_SIZE; step++) {
+            if (current === newEffect.sourceEpicId) {
+                throw new error_types_1.ValidationError('A time route cannot form a cycle.', {
+                    sourceEpicId: newEffect.sourceEpicId,
+                    targetEpicId: newEffect.targetEpicId,
+                });
+            }
+            const edge = outgoing.get(current, current);
+            if (!edge || edge.id === replacedRowId) {
+                return;
+            }
+            const effect = (0, domain_models_1.resolveRelationEndpoints)(edge.left_epic_id, edge.right_epic_id, edge.direction);
+            if (!effect || visited.has(effect.targetEpicId)) {
+                return;
+            }
+            visited.add(effect.targetEpicId);
+            current = effect.targetEpicId;
+        }
+    }
+    findOutgoingEligibleRouteSync(sourceEpicId, excludedRowId) {
+        const row = this.rawClient
+            .prepare(`SELECT relation.id, relation.left_epic_id, relation.right_epic_id, relation.direction
+         FROM epic_relations relation
+         INNER JOIN epics left_epic ON left_epic.id = relation.left_epic_id
+         INNER JOIN epics right_epic ON right_epic.id = relation.right_epic_id
+         WHERE${EpicStorageDelegate.ELIGIBLE_ROUTE_SOURCE_PREDICATE}
+         LIMIT 1`)
+            .get(sourceEpicId, sourceEpicId);
+        if (!row || row.id === excludedRowId) {
+            return null;
+        }
+        return (0, domain_models_1.resolveRelationEndpoints)(row.left_epic_id, row.right_epic_id, row.direction);
+    }
+    deleteOutgoingEligibleRouteSync(sourceEpicId, keepLeftEpicId, keepRightEpicId) {
+        this.rawClient
+            .prepare(`DELETE FROM epic_relations
+         WHERE id IN (
+           SELECT relation.id
+           FROM epic_relations relation
+           INNER JOIN epics left_epic ON left_epic.id = relation.left_epic_id
+           INNER JOIN epics right_epic ON right_epic.id = relation.right_epic_id
+           WHERE${EpicStorageDelegate.ELIGIBLE_ROUTE_SOURCE_PREDICATE}
+         )
+         AND NOT (left_epic_id = ? AND right_epic_id = ?)`)
+            .run(sourceEpicId, sourceEpicId, keepLeftEpicId, keepRightEpicId);
+    }
+    ensureEpicIsNotRouteEndpointSync(epicId) {
+        const routed = this.rawClient
+            .prepare(`SELECT relation.left_epic_id, relation.right_epic_id
+         FROM epic_relations relation
+         INNER JOIN epics left_epic ON left_epic.id = relation.left_epic_id
+         INNER JOIN epics right_epic ON right_epic.id = relation.right_epic_id
+         WHERE relation.type = 'related'
+           AND relation.direction != 'none'
+           AND left_epic.parent_id IS NULL
+           AND right_epic.parent_id IS NULL
+           AND left_epic.project_id = right_epic.project_id
+           AND (relation.left_epic_id = ? OR relation.right_epic_id = ?)
+         LIMIT 1`)
+            .get(epicId, epicId);
+        if (routed) {
+            throw new error_types_1.ValidationError('Delete the eligible Related pair explicitly before reparenting one of its endpoints.', { epicId, leftEpicId: routed.left_epic_id, rightEpicId: routed.right_epic_id });
+        }
+    }
+    assertPromotionKeepsEligibleRoutesSync(epicId, projectId) {
+        const newlyEligible = this.rawClient
+            .prepare(`SELECT CASE WHEN relation.direction = 'left_to_right'
+                  THEN relation.left_epic_id ELSE relation.right_epic_id END AS source_id,
+                CASE WHEN relation.direction = 'left_to_right'
+                  THEN relation.right_epic_id ELSE relation.left_epic_id END AS target_id
+         FROM epic_relations relation
+         INNER JOIN epics other
+           ON other.id = CASE
+             WHEN relation.left_epic_id = ? THEN relation.right_epic_id
+             ELSE relation.left_epic_id END
+         WHERE relation.type = 'related'
+           AND relation.direction != 'none'
+           AND (relation.left_epic_id = ? OR relation.right_epic_id = ?)
+           AND other.parent_id IS NULL
+           AND other.project_id = ?`)
+            .all(epicId, epicId, epicId, projectId);
+        if (newlyEligible.length === 0) {
+            return;
+        }
+        const duplicateSource = this.rawClient
+            .prepare(`SELECT CASE WHEN relation.direction = 'left_to_right'
+                  THEN relation.left_epic_id ELSE relation.right_epic_id END AS source_id,
+                COUNT(*) AS route_count
+         FROM epic_relations relation
+         INNER JOIN epics left_epic ON left_epic.id = relation.left_epic_id
+         INNER JOIN epics right_epic ON right_epic.id = relation.right_epic_id
+         WHERE relation.type = 'related'
+           AND relation.direction != 'none'
+           AND (left_epic.parent_id IS NULL OR left_epic.id = ?)
+           AND (right_epic.parent_id IS NULL OR right_epic.id = ?)
+           AND left_epic.project_id = right_epic.project_id
+         GROUP BY source_id
+         HAVING COUNT(*) > 1
+         LIMIT 1`)
+            .get(epicId, epicId);
+        if (duplicateSource) {
+            throw new error_types_1.ValidationError('Promoting this Epic would activate more than one eligible time route from one source. Delete the extra Related pair explicitly first.', {
+                epicId,
+                sourceEpicId: duplicateSource.source_id,
+                routeCount: duplicateSource.route_count,
+            });
+        }
+        const outgoing = this.rawClient.prepare(`SELECT relation.left_epic_id, relation.right_epic_id, relation.direction
+       FROM epic_relations relation
+       INNER JOIN epics left_epic ON left_epic.id = relation.left_epic_id
+       INNER JOIN epics right_epic ON right_epic.id = relation.right_epic_id
+       WHERE relation.type = 'related'
+         AND relation.direction != 'none'
+         AND (left_epic.parent_id IS NULL OR left_epic.id = ?)
+         AND (right_epic.parent_id IS NULL OR right_epic.id = ?)
+         AND left_epic.project_id = right_epic.project_id
+         AND (
+           (relation.left_epic_id = ? AND relation.direction = 'left_to_right')
+           OR (relation.right_epic_id = ? AND relation.direction = 'right_to_left')
+         )`);
+        for (const edge of newlyEligible) {
+            const visited = new Set([edge.target_id]);
+            let current = edge.target_id;
+            for (let step = 0; step <= MAX_RELATION_BATCH_SIZE; step++) {
+                if (current === edge.source_id) {
+                    throw new error_types_1.ValidationError('Promoting this Epic would complete a time-route cycle. Delete one Related pair explicitly first.', { epicId, sourceEpicId: edge.source_id, targetEpicId: edge.target_id });
+                }
+                const next = outgoing.get(epicId, epicId, current, current);
+                if (!next) {
+                    break;
+                }
+                const effect = (0, domain_models_1.resolveRelationEndpoints)(next.left_epic_id, next.right_epic_id, next.direction);
+                if (!effect || visited.has(effect.targetEpicId)) {
+                    break;
+                }
+                visited.add(effect.targetEpicId);
+                current = effect.targetEpicId;
+            }
+        }
+    }
+    toFocalRelationType(focalEpicId, relation) {
+        if (relation.type === 'related') {
+            return 'related';
+        }
+        const focalIsLeft = focalEpicId === relation.left_epic_id;
+        const focalBlocks = (focalIsLeft && relation.direction === 'left_to_right') ||
+            (!focalIsLeft && relation.direction === 'right_to_left');
+        return focalBlocks ? 'blocks' : 'blocked_by';
+    }
+    mapEpicRelation(row) {
+        const endpoints = (0, domain_models_1.resolveRelationEndpoints)(row.left_epic_id, row.right_epic_id, row.direction);
+        return {
+            id: row.id,
+            leftEpicId: row.left_epic_id,
+            rightEpicId: row.right_epic_id,
+            type: row.type,
+            direction: row.direction,
+            sourceEpicId: endpoints?.sourceEpicId ?? null,
+            targetEpicId: endpoints?.targetEpicId ?? null,
+            createdBy: row.created_by,
+            createdByAgentId: row.created_by_agent_id,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        };
+    }
+    mapRelationCandidate(row) {
+        return {
+            id: row.id,
+            projectId: row.project_id,
+            projectName: row.project_name,
+            title: row.title,
+            statusId: row.status_id,
+            statusLabel: row.status_label,
+            statusColor: row.status_color,
+            statusMcpHidden: Boolean(row.status_mcp_hidden),
+            parentId: row.parent_id,
+        };
+    }
+    normalizeRelationListLimit(limit, label) {
+        if (limit === undefined)
+            return 50;
+        if (!Number.isInteger(limit) || limit < 1 || limit > MAX_RELATION_LIST_LIMIT) {
+            throw new error_types_1.ValidationError(`${label} limit must be between 1 and ${MAX_RELATION_LIST_LIMIT}.`);
+        }
+        return limit;
+    }
+    normalizeRelationListOffset(offset, label) {
+        if (offset === undefined)
+            return 0;
+        if (!Number.isInteger(offset) || offset < 0) {
+            throw new error_types_1.ValidationError(`${label} offset must be a non-negative integer.`);
+        }
+        return offset;
+    }
     ensureValidEpicParentSync(projectId, parentId, childId) {
         if (!parentId) {
             return;
@@ -719,6 +1411,18 @@ class EpicStorageDelegate extends base_storage_delegate_1.BaseStorageDelegate {
             });
         }
         if (childId) {
+            const existingRelation = this.rawClient
+                .prepare(`SELECT 1 FROM epic_relations
+           WHERE (left_epic_id = ? AND right_epic_id = ?)
+              OR (left_epic_id = ? AND right_epic_id = ?)
+           LIMIT 1`)
+                .get(childId, parentId, parentId, childId);
+            if (existingRelation) {
+                throw new error_types_1.ValidationError('A parent and direct sub-Epic cannot have a relation.', {
+                    epicId: childId,
+                    parentId,
+                });
+            }
             const descendants = this.db
                 .select({ id: schema_1.epics.id })
                 .from(schema_1.epics)