@x12i/memorix-service 3.6.0 → 3.6.2

package/dist/routes/metadata.js

@@ -661,437 +661,123 @@ export async function registerMetadataRoutes(app, platform) {
             note,
         };
     });
-    app.get("/api/metadata/packages/:kind/:id/associations", async (req) => {
-        requireMagit(platform);
-        const kind = parseKind(req.params.kind);
-        const id = String(req.params.id ?? "").trim();
+    // Magit 2.14 — package channels & release sets (Mode A only; fail closed if unset)
+    // Static paths registered before /:kind/:id/* so Fastify never treats them as params.
+    app.get("/api/metadata/packages/capabilities", async () => {
+        const magit = requireMagit(platform);
+        const caps = magit.packageCatalogCapabilities();
+        return {
+            ...caps,
+            note: "Safe capability flags for Packages UI. Never includes tokens or store selector.",
+        };
+    });
+    app.post("/api/metadata/packages/channels/promote", async (req) => {
+        const magit = requireMagit(platform);
+        const body = req.body;
+        const kind = parseKind(body.kind);
+        const id = body.id?.trim();
+        const channel = body.channel?.trim();
+        const version = body.version?.trim();
         if (!id)
             throw new ServiceError("VALIDATION", "id required", 400);
-        const packs = installedPacks();
-        const q = req.query;
-        const agentId = resolveOwnerAgent(packs, kind, id, q.agentId);
-        const pack = packs[agentId];
-        if (!pack) {
-            throw new ServiceError("NOT_FOUND", `No installed pack for agent ${agentId}`, 404);
-        }
-        return {
+        if (!channel)
+            throw new ServiceError("VALIDATION", "channel required", 400);
+        if (!version)
+            throw new ServiceError("VALIDATION", "version required", 400);
+        const result = await magit.setPackageChannel({
             kind,
             id,
-            agentId,
-            associations: associationsFromPack(pack),
+            channel,
+            version,
+            message: body.message?.trim() || undefined,
+            expectedVersion: body.expectedVersion,
+        });
+        return {
+            ...result,
+            note: "Channel pointer updated. Packages do not move; promote does not install into organizations.",
         };
     });
-    // FR-CPS-3/5 — flat catalog listing. Org-free: kind + id only, no agentId
-    // resolution needed (a catalog package isn't owned by any installed pack).
-    app.get("/api/metadata/packages/:kind/:id/versions", async (req) => {
+    app.get("/api/metadata/packages/:kind/:id/channels", async (req) => {
         const magit = requireMagit(platform);
         const kind = parseKind(req.params.kind);
         const id = String(req.params.id ?? "").trim();
         if (!id)
             throw new ServiceError("VALIDATION", "id required", 400);
-        const q = req.query;
-        const maxCount = q.maxCount ? Number(q.maxCount) : 50;
-        const versions = await magit.listPackages({
-            kind,
-            id,
-            maxCount: Number.isFinite(maxCount) ? maxCount : 50,
-        });
+        const channels = await magit.listPackageChannels({ kind, id });
         return {
             kind,
             id,
-            // `commit` aliases `version` for existing HTTP callers written against
-            // the pre-cutover org-scoped history shape (e.g. Studio's
-            // PackVersionsPage.tsx keys/renders list rows by `.commit`). `version`
-            // is the FR-CPS-4/5 field name and the one new callers should use.
-            versions: versions.map((v) => ({ ...v, commit: v.version })),
-            note: "Versions from the central Magit package catalog.",
+            channels,
+            note: "Known channel heads for this package (shared catalog).",
         };
     });
-    // FR-CPS-5 — fetch a package version's payload directly (§7 of the FR).
-    // Org header is ignored: catalog reads are org-free.
-    app.get("/api/metadata/packages/:kind/:id/versions/:version", async (req) => {
+    app.get("/api/metadata/packages/:kind/:id/channels/:channel", async (req) => {
         const magit = requireMagit(platform);
         const kind = parseKind(req.params.kind);
         const id = String(req.params.id ?? "").trim();
+        const channel = String(req.params.channel ?? "").trim();
         if (!id)
             throw new ServiceError("VALIDATION", "id required", 400);
-        const version = String(req.params.version ?? "").trim();
-        if (!version)
-            throw new ServiceError("VALIDATION", "version required", 400);
-        const fetched = await magit.fetchPackage({ kind, id, version });
+        if (!channel)
+            throw new ServiceError("VALIDATION", "channel required", 400);
+        const result = await magit.resolvePackageChannel({ kind, id, channel });
         return {
-            kind,
-            id,
-            version,
-            checksum: fetched.checksum,
-            payload: fetched.payload,
-            associations: fetched.associations,
+            ...result,
+            note: "Resolved after Magit sync (fresh channel head).",
         };
     });
-    app.post("/api/metadata/packages/pack", async (req) => {
+    app.get("/api/metadata/packages/:kind/:id/channels/:channel/history", async (req) => {
         const magit = requireMagit(platform);
-        const body = req.body;
-        const kind = parseKind(body.kind);
-        const id = body.id?.trim();
+        const kind = parseKind(req.params.kind);
+        const id = String(req.params.id ?? "").trim();
+        const channel = String(req.params.channel ?? "").trim();
         if (!id)
             throw new ServiceError("VALIDATION", "id required", 400);
-        const message = body.message?.trim();
-        if (!message)
-            throw new ServiceError("VALIDATION", "message required", 400);
-        const packs = installedPacks();
-        let agentId;
-        try {
-            agentId = resolveOwnerAgent(packs, kind, id, body.agentId);
-        }
-        catch (e) {
-            throw new ServiceError("NOT_FOUND", e instanceof Error ? e.message : String(e), 404);
-        }
-        const live = packs[agentId];
-        if (!live) {
-            throw new ServiceError("NOT_FOUND", `No installed pack for agent ${agentId}`, 404);
-        }
-        const mode = kind === "agent" ? (body.mode === "narrow" ? "narrow" : "full") : undefined;
-        const payload = buildPackagePayload(live, {
+        if (!channel)
+            throw new ServiceError("VALIDATION", "channel required", 400);
+        const history = await magit.packageChannelHistory({ kind, id, channel });
+        return {
             kind,
             id,
-            mode,
-            includeConnectorIds: body.includeConnectorIds,
-            includeServiceIds: body.includeServiceIds,
-        });
-        const validation = validateMetadataPack(payload);
-        if (!validation.ok) {
-            return { packed: false, result: validation };
+            channel,
+            history,
+            note: "Package channel history — promote a previous version to roll back the pointer.",
+        };
+    });
+    app.post("/api/metadata/packages/releases/pack", async (req) => {
+        const magit = requireMagit(platform);
+        const body = req.body;
+        const members = (body.members ?? []).map((m) => ({
+            kind: parseKind(m.kind),
+            id: String(m.id ?? "").trim(),
+            version: String(m.version ?? "").trim(),
+        }));
+        if (members.length === 0) {
+            throw new ServiceError("VALIDATION", "members must list at least one { kind, id, version }", 400);
         }
-        const associations = kind === "agent" && mode
-            ? releaseAssociations(live, mode, body.includeConnectorIds, body.includeServiceIds)
-            : undefined;
-        const saved = await magit.packPackage({
-            kind,
-            id,
-            message,
-            pack: payload,
-            mode,
-            associations,
-        });
-        // Full agent pack also snapshots selected connector/service packages.
-        // `commit` aliases `version` for the same backward-compat reason as the
-        // versions-list route above.
-        const bundled = [];
-        if (kind === "agent" && mode === "full" && associations) {
-            for (const connectorId of associations.connectorIds) {
-                const slice = buildPackagePayload(live, { kind: "connector", id: connectorId });
-                const ok = validateMetadataPack(slice);
-                if (!ok.ok)
-                    continue;
-                const b = await magit.packPackage({
-                    kind: "connector",
-                    id: connectorId,
-                    message: `bundled with agent ${id}: ${message}`,
-                    pack: slice,
-                });
-                bundled.push({ kind: "connector", id: connectorId, version: b.version, commit: b.version });
-            }
-            for (const serviceId of associations.serviceIds) {
-                const slice = buildPackagePayload(live, { kind: "service", id: serviceId });
-                const ok = validateMetadataPack(slice);
-                if (!ok.ok)
-                    continue;
-                const b = await magit.packPackage({
-                    kind: "service",
-                    id: serviceId,
-                    message: `bundled with agent ${id}: ${message}`,
-                    pack: slice,
-                });
-                bundled.push({ kind: "service", id: serviceId, version: b.version, commit: b.version });
+        for (const m of members) {
+            if (!m.id || !m.version) {
+                throw new ServiceError("VALIDATION", "each member needs kind, id, and version", 400);
             }
         }
-        const note = saved.published === false
-            ? "Published locally but not to the shared catalog (published=false)."
-            : saved.published === true
-                ? "Published to the shared package catalog."
-                : "Published to the package catalog.";
+        const result = await magit.packRelease({
+            members,
+            message: body.message?.trim() || undefined,
+        });
         return {
-            packed: true,
-            kind,
-            id,
-            agentId,
-            mode: mode ?? null,
-            associations,
-            bundled,
-            version: saved.version,
-            checksum: saved.checksum,
-            reused: saved.reused,
-            ...(saved.published !== undefined ? { published: saved.published } : {}),
-            ...(saved.storeId ? { storeId: saved.storeId } : {}),
-            ...(saved.packageTypeId ? { packageTypeId: saved.packageTypeId } : {}),
-            note,
+            ...result,
+            note: "Immutable release set (content-addressed). Promote via release channel. Install separately into a target organization.",
         };
     });
-    app.post("/api/metadata/packages/restore", async (req) => {
-        const scope = resolveScope(req);
+    app.post("/api/metadata/packages/releases/channels/promote", async (req) => {
         const magit = requireMagit(platform);
         const body = req.body;
-        if (!body?.confirm) {
-            throw new ServiceError("CONFIRMATION_REQUIRED", "explicit confirm:true required for package restore", 400);
-        }
-        if (!scope.orgId?.trim()) {
-            throw new ServiceError("VALIDATION", "x-memorix-org-id required — org is the restore target, not package identity", 400);
-        }
-        const kind = parseKind(body.kind);
-        const id = body.id?.trim();
-        if (!id)
-            throw new ServiceError("VALIDATION", "id required", 400);
-        const version = (body.version ?? body.commit)?.trim();
-        if (!version)
-            throw new ServiceError("VALIDATION", "version required", 400);
-        const packs = installedPacks();
-        let agentId;
-        try {
-            agentId = resolveOwnerAgent(packs, kind, id, body.agentId);
-        }
-        catch {
-            agentId = kind === "agent" ? id : body.agentId?.trim() || "";
-        }
-        if (!agentId) {
-            throw new ServiceError("VALIDATION", "agentId required to restore connector/service into an agent pack", 400);
-        }
-        const sliceAgentId = catalogAgentId(kind, id, agentId);
-        const fetched = await magit.fetchPackage({ kind, id, version });
-        const loadedPack = packagePayloadToPack(sliceAgentId, fetched.payload);
-        let installPack = loadedPack;
-        // Connector/service restore merges slice into current live agent pack.
-        if (kind === "connector" || kind === "service") {
-            const live = packs[agentId] ?? emptyPackForRestore(agentId);
-            if (kind === "connector") {
-                const keepRefs = new Set((loadedPack.sources ?? [])
-                    .map((s) => s && typeof s === "object" && "connectorRef" in s
-                    ? String(s.connectorRef ?? "")
-                    : "")
-                    .filter(Boolean));
-                const otherSources = (live.sources ?? []).filter((s) => {
-                    const ref = s && typeof s === "object" && "connectorRef" in s
-                        ? String(s.connectorRef ?? "")
-                        : "";
-                    return !keepRefs.has(ref);
-                });
-                installPack = {
-                    ...live,
-                    agentId,
-                    sources: [...otherSources, ...(loadedPack.sources ?? [])],
-                };
-            }
-            else {
-                const svcId = id;
-                const otherServices = (live.services ?? []).filter((s) => !(s && typeof s === "object" && "id" in s && String(s.id) === svcId));
-                installPack = {
-                    ...live,
-                    agentId,
-                    services: [...otherServices, ...(loadedPack.services ?? [])],
-                };
-            }
-        }
-        installPack = stripOrgRuntimeSourcesFromPack(installPack);
-        const validation = validateMetadataPack(installPack);
-        if (!validation.ok) {
-            throw new ServiceError("VALIDATION", "pack at version failed validation", 400, { issues: validation.issues });
-        }
-        const message = body.message?.trim() ||
-            `Restore ${kind}:${id} @ ${version.slice(0, 12)} into org ${scope.orgId}`;
-        const result = platform.metadata.install(installPack, {
-            reinstall: true,
-            magitCommit: version,
-            magitRelease: undefined,
-            source: "rollback",
-            message,
-            environment: "live",
-        });
-        if (!result.ok) {
-            throw new ServiceError("VALIDATION", result.issues.map((i) => i.message).join("; ") || "restore install failed", 400);
-        }
-        return {
-            restored: true,
-            kind,
-            id,
-            agentId,
-            version,
-            checksum: fetched.checksum,
-            targetOrgId: scope.orgId,
-            result,
-            note: "Installed from the shared package catalog into this organization. Organization is the install target only.",
-        };
-    });
-    app.post("/api/metadata/packages/diff", async (req) => {
-        const magit = requireMagit(platform);
-        const body = req.body;
-        const kind = parseKind(body.kind);
-        const id = body.id?.trim();
-        if (!id)
-            throw new ServiceError("VALIDATION", "id required", 400);
-        const from = body.from?.trim();
-        const to = body.to?.trim();
-        if (!from || !to) {
-            throw new ServiceError("VALIDATION", "from and to required", 400);
-        }
-        const packs = installedPacks();
-        let agentId;
-        try {
-            agentId = resolveOwnerAgent(packs, kind, id, body.agentId);
-        }
-        catch {
-            agentId = kind === "agent" ? id : body.agentId?.trim() || id;
-        }
-        const sliceAgentId = catalogAgentId(kind, id, agentId);
-        // "installed" sentinel → live / installed pack slice for typed-store compare.
-        // Flat Mode B still maps installed → "live" commit/mongo side via MagitPackService.
-        const fromRef = from === "installed" ? "live" : from;
-        const toRef = to === "installed" ? "live" : to;
-        const needsInstalled = fromRef === "live" ||
-            toRef === "live" ||
-            from === "installed" ||
-            to === "installed";
-        let installedPack = null;
-        if (needsInstalled) {
-            const live = packs[agentId];
-            if (live) {
-                installedPack = buildPackagePayload(live, {
-                    kind,
-                    id,
-                    mode: kind === "agent" ? "narrow" : undefined,
-                });
-            }
-        }
-        const diff = await magit.diffPackages(sliceAgentId, {
-            from: fromRef,
-            to: toRef,
-            kind,
-            id,
-            installedPack,
-        });
-        return {
-            ...diff,
-            kind,
-            id,
-            agentId,
-            catalogAgentId: sliceAgentId,
-            note: "Compare package versions or version vs installed. Not env→env copy.",
-        };
-    });
-    // Magit 2.14 — package channels & release sets (Mode A only; fail closed if unset)
-    app.get("/api/metadata/packages/capabilities", async () => {
-        const magit = requireMagit(platform);
-        const caps = magit.packageCatalogCapabilities();
-        return {
-            ...caps,
-            note: "Safe capability flags for Packages UI. Never includes tokens or store selector.",
-        };
-    });
-    app.post("/api/metadata/packages/channels/promote", async (req) => {
-        const magit = requireMagit(platform);
-        const body = req.body;
-        const kind = parseKind(body.kind);
-        const id = body.id?.trim();
-        const channel = body.channel?.trim();
-        const version = body.version?.trim();
-        if (!id)
-            throw new ServiceError("VALIDATION", "id required", 400);
-        if (!channel)
-            throw new ServiceError("VALIDATION", "channel required", 400);
-        if (!version)
-            throw new ServiceError("VALIDATION", "version required", 400);
-        const result = await magit.setPackageChannel({
-            kind,
-            id,
-            channel,
-            version,
-            message: body.message?.trim() || undefined,
-            expectedVersion: body.expectedVersion,
-        });
-        return {
-            ...result,
-            note: "Channel pointer updated. Packages do not move; promote does not install into organizations.",
-        };
-    });
-    app.get("/api/metadata/packages/:kind/:id/channels", async (req) => {
-        const magit = requireMagit(platform);
-        const kind = parseKind(req.params.kind);
-        const id = String(req.params.id ?? "").trim();
-        if (!id)
-            throw new ServiceError("VALIDATION", "id required", 400);
-        const channels = await magit.listPackageChannels({ kind, id });
-        return {
-            kind,
-            id,
-            channels,
-            note: "Known channel heads for this package (shared catalog).",
-        };
-    });
-    app.get("/api/metadata/packages/:kind/:id/channels/:channel", async (req) => {
-        const magit = requireMagit(platform);
-        const kind = parseKind(req.params.kind);
-        const id = String(req.params.id ?? "").trim();
-        const channel = String(req.params.channel ?? "").trim();
-        if (!id)
-            throw new ServiceError("VALIDATION", "id required", 400);
-        if (!channel)
-            throw new ServiceError("VALIDATION", "channel required", 400);
-        const result = await magit.resolvePackageChannel({ kind, id, channel });
-        return {
-            ...result,
-            note: "Resolved after Magit sync (fresh channel head).",
-        };
-    });
-    app.get("/api/metadata/packages/:kind/:id/channels/:channel/history", async (req) => {
-        const magit = requireMagit(platform);
-        const kind = parseKind(req.params.kind);
-        const id = String(req.params.id ?? "").trim();
-        const channel = String(req.params.channel ?? "").trim();
-        if (!id)
-            throw new ServiceError("VALIDATION", "id required", 400);
-        if (!channel)
-            throw new ServiceError("VALIDATION", "channel required", 400);
-        const history = await magit.packageChannelHistory({ kind, id, channel });
-        return {
-            kind,
-            id,
-            channel,
-            history,
-            note: "Package channel history — promote a previous version to roll back the pointer.",
-        };
-    });
-    app.post("/api/metadata/packages/releases/pack", async (req) => {
-        const magit = requireMagit(platform);
-        const body = req.body;
-        const members = (body.members ?? []).map((m) => ({
-            kind: parseKind(m.kind),
-            id: String(m.id ?? "").trim(),
-            version: String(m.version ?? "").trim(),
-        }));
-        if (members.length === 0) {
-            throw new ServiceError("VALIDATION", "members must list at least one { kind, id, version }", 400);
-        }
-        for (const m of members) {
-            if (!m.id || !m.version) {
-                throw new ServiceError("VALIDATION", "each member needs kind, id, and version", 400);
-            }
-        }
-        const result = await magit.packRelease({
-            members,
-            message: body.message?.trim() || undefined,
-        });
-        return {
-            ...result,
-            note: "Immutable release set (content-addressed). Promote via release channel. Install separately into a target organization.",
-        };
-    });
-    app.post("/api/metadata/packages/releases/channels/promote", async (req) => {
-        const magit = requireMagit(platform);
-        const body = req.body;
-        const channel = body.channel?.trim();
-        const releaseId = body.releaseId?.trim();
-        if (!channel)
-            throw new ServiceError("VALIDATION", "channel required", 400);
-        if (!releaseId) {
-            throw new ServiceError("VALIDATION", "releaseId required", 400);
+        const channel = body.channel?.trim();
+        const releaseId = body.releaseId?.trim();
+        if (!channel)
+            throw new ServiceError("VALIDATION", "channel required", 400);
+        if (!releaseId) {
+            throw new ServiceError("VALIDATION", "releaseId required", 400);
         }
         const result = await magit.setReleaseChannel({
             channel,
@@ -1135,6 +821,18 @@ export async function registerMetadataRoutes(app, platform) {
             note: "Rollback list: promote a previous releaseId to move the channel back.",
         };
     });
+    app.get("/api/metadata/packages/releases/by-id/:releaseId", async (req) => {
+        const magit = requireMagit(platform);
+        const releaseId = String(req.params.releaseId ?? "").trim();
+        if (!releaseId) {
+            throw new ServiceError("VALIDATION", "releaseId required", 400);
+        }
+        const release = await magit.getRelease({ releaseId });
+        return {
+            ...release,
+            note: "Immutable release set from Magit readRelease (after store sync).",
+        };
+    });
     /**
      * Atomic install of a release set into the target org.
      * Body: { confirm:true, channel? | releaseId?, message? }
@@ -1161,18 +859,8 @@ export async function registerMetadataRoutes(app, platform) {
         }
         else if (body.releaseId?.trim()) {
             releaseId = body.releaseId.trim();
-            // Resolve via channel history is not available for bare releaseId —
-            // pack response members must be re-fetched through channel or re-cut.
-            // Prefer channel path; for releaseId-only, resolve from listReleaseChannels.
-            const listed = await magit.listReleaseChannels();
-            const match = listed.find((c) => c.releaseId === releaseId);
-            if (match) {
-                members = match.release.members;
-                channel = match.channel;
-            }
-            else {
-                throw new ServiceError("VALIDATION", "releaseId not found on any release channel; pass channel to install from a channel head", 400);
-            }
+            const release = await magit.getRelease({ releaseId });
+            members = release.members;
         }
         else {
             throw new ServiceError("VALIDATION", "channel or releaseId required", 400);
@@ -1300,6 +988,321 @@ export async function registerMetadataRoutes(app, platform) {
             note: "Atomic release install into the target organization. On failure, prior packs are restored.",
         };
     });
+    app.get("/api/metadata/packages/:kind/:id/associations", async (req) => {
+        requireMagit(platform);
+        const kind = parseKind(req.params.kind);
+        const id = String(req.params.id ?? "").trim();
+        if (!id)
+            throw new ServiceError("VALIDATION", "id required", 400);
+        const packs = installedPacks();
+        const q = req.query;
+        const agentId = resolveOwnerAgent(packs, kind, id, q.agentId);
+        const pack = packs[agentId];
+        if (!pack) {
+            throw new ServiceError("NOT_FOUND", `No installed pack for agent ${agentId}`, 404);
+        }
+        return {
+            kind,
+            id,
+            agentId,
+            associations: associationsFromPack(pack),
+        };
+    });
+    // FR-CPS-3/5 — flat catalog listing. Org-free: kind + id only, no agentId
+    // resolution needed (a catalog package isn't owned by any installed pack).
+    app.get("/api/metadata/packages/:kind/:id/versions", async (req) => {
+        const magit = requireMagit(platform);
+        const kind = parseKind(req.params.kind);
+        const id = String(req.params.id ?? "").trim();
+        if (!id)
+            throw new ServiceError("VALIDATION", "id required", 400);
+        const q = req.query;
+        const maxCount = q.maxCount ? Number(q.maxCount) : 50;
+        const versions = await magit.listPackages({
+            kind,
+            id,
+            maxCount: Number.isFinite(maxCount) ? maxCount : 50,
+        });
+        return {
+            kind,
+            id,
+            // `commit` aliases `version` for existing HTTP callers written against
+            // the pre-cutover org-scoped history shape (e.g. Studio's
+            // PackVersionsPage.tsx keys/renders list rows by `.commit`). `version`
+            // is the FR-CPS-4/5 field name and the one new callers should use.
+            versions: versions.map((v) => ({ ...v, commit: v.version })),
+            note: "Versions from the central Magit package catalog.",
+        };
+    });
+    // FR-CPS-5 — fetch a package version's payload directly (§7 of the FR).
+    // Org header is ignored: catalog reads are org-free.
+    app.get("/api/metadata/packages/:kind/:id/versions/:version", async (req) => {
+        const magit = requireMagit(platform);
+        const kind = parseKind(req.params.kind);
+        const id = String(req.params.id ?? "").trim();
+        if (!id)
+            throw new ServiceError("VALIDATION", "id required", 400);
+        const version = String(req.params.version ?? "").trim();
+        if (!version)
+            throw new ServiceError("VALIDATION", "version required", 400);
+        const fetched = await magit.fetchPackage({ kind, id, version });
+        return {
+            kind,
+            id,
+            version,
+            checksum: fetched.checksum,
+            payload: fetched.payload,
+            associations: fetched.associations,
+        };
+    });
+    app.post("/api/metadata/packages/pack", async (req) => {
+        const magit = requireMagit(platform);
+        const body = req.body;
+        const kind = parseKind(body.kind);
+        const id = body.id?.trim();
+        if (!id)
+            throw new ServiceError("VALIDATION", "id required", 400);
+        const message = body.message?.trim();
+        if (!message)
+            throw new ServiceError("VALIDATION", "message required", 400);
+        const packs = installedPacks();
+        let agentId;
+        try {
+            agentId = resolveOwnerAgent(packs, kind, id, body.agentId);
+        }
+        catch (e) {
+            throw new ServiceError("NOT_FOUND", e instanceof Error ? e.message : String(e), 404);
+        }
+        const live = packs[agentId];
+        if (!live) {
+            throw new ServiceError("NOT_FOUND", `No installed pack for agent ${agentId}`, 404);
+        }
+        const mode = kind === "agent" ? (body.mode === "narrow" ? "narrow" : "full") : undefined;
+        const payload = buildPackagePayload(live, {
+            kind,
+            id,
+            mode,
+            includeConnectorIds: body.includeConnectorIds,
+            includeServiceIds: body.includeServiceIds,
+        });
+        const validation = validateMetadataPack(payload);
+        if (!validation.ok) {
+            return { packed: false, result: validation };
+        }
+        const associations = kind === "agent" && mode
+            ? releaseAssociations(live, mode, body.includeConnectorIds, body.includeServiceIds)
+            : undefined;
+        const saved = await magit.packPackage({
+            kind,
+            id,
+            message,
+            pack: payload,
+            mode,
+            associations,
+        });
+        // Full agent pack also snapshots selected connector/service packages.
+        // `commit` aliases `version` for the same backward-compat reason as the
+        // versions-list route above.
+        const bundled = [];
+        if (kind === "agent" && mode === "full" && associations) {
+            for (const connectorId of associations.connectorIds) {
+                const slice = buildPackagePayload(live, { kind: "connector", id: connectorId });
+                const ok = validateMetadataPack(slice);
+                if (!ok.ok)
+                    continue;
+                const b = await magit.packPackage({
+                    kind: "connector",
+                    id: connectorId,
+                    message: `bundled with agent ${id}: ${message}`,
+                    pack: slice,
+                });
+                bundled.push({ kind: "connector", id: connectorId, version: b.version, commit: b.version });
+            }
+            for (const serviceId of associations.serviceIds) {
+                const slice = buildPackagePayload(live, { kind: "service", id: serviceId });
+                const ok = validateMetadataPack(slice);
+                if (!ok.ok)
+                    continue;
+                const b = await magit.packPackage({
+                    kind: "service",
+                    id: serviceId,
+                    message: `bundled with agent ${id}: ${message}`,
+                    pack: slice,
+                });
+                bundled.push({ kind: "service", id: serviceId, version: b.version, commit: b.version });
+            }
+        }
+        const note = saved.published === false
+            ? "Published locally but not to the shared catalog (published=false)."
+            : saved.published === true
+                ? "Published to the shared package catalog."
+                : "Published to the package catalog.";
+        return {
+            packed: true,
+            kind,
+            id,
+            agentId,
+            mode: mode ?? null,
+            associations,
+            bundled,
+            version: saved.version,
+            checksum: saved.checksum,
+            reused: saved.reused,
+            ...(saved.published !== undefined ? { published: saved.published } : {}),
+            ...(saved.storeId ? { storeId: saved.storeId } : {}),
+            ...(saved.packageTypeId ? { packageTypeId: saved.packageTypeId } : {}),
+            note,
+        };
+    });
+    app.post("/api/metadata/packages/restore", async (req) => {
+        const scope = resolveScope(req);
+        const magit = requireMagit(platform);
+        const body = req.body;
+        if (!body?.confirm) {
+            throw new ServiceError("CONFIRMATION_REQUIRED", "explicit confirm:true required for package restore", 400);
+        }
+        if (!scope.orgId?.trim()) {
+            throw new ServiceError("VALIDATION", "x-memorix-org-id required — org is the restore target, not package identity", 400);
+        }
+        const kind = parseKind(body.kind);
+        const id = body.id?.trim();
+        if (!id)
+            throw new ServiceError("VALIDATION", "id required", 400);
+        const version = (body.version ?? body.commit)?.trim();
+        if (!version)
+            throw new ServiceError("VALIDATION", "version required", 400);
+        const packs = installedPacks();
+        let agentId;
+        try {
+            agentId = resolveOwnerAgent(packs, kind, id, body.agentId);
+        }
+        catch {
+            agentId = kind === "agent" ? id : body.agentId?.trim() || "";
+        }
+        if (!agentId) {
+            throw new ServiceError("VALIDATION", "agentId required to restore connector/service into an agent pack", 400);
+        }
+        const sliceAgentId = catalogAgentId(kind, id, agentId);
+        const fetched = await magit.fetchPackage({ kind, id, version });
+        const loadedPack = packagePayloadToPack(sliceAgentId, fetched.payload);
+        let installPack = loadedPack;
+        // Connector/service restore merges slice into current live agent pack.
+        if (kind === "connector" || kind === "service") {
+            const live = packs[agentId] ?? emptyPackForRestore(agentId);
+            if (kind === "connector") {
+                const keepRefs = new Set((loadedPack.sources ?? [])
+                    .map((s) => s && typeof s === "object" && "connectorRef" in s
+                    ? String(s.connectorRef ?? "")
+                    : "")
+                    .filter(Boolean));
+                const otherSources = (live.sources ?? []).filter((s) => {
+                    const ref = s && typeof s === "object" && "connectorRef" in s
+                        ? String(s.connectorRef ?? "")
+                        : "";
+                    return !keepRefs.has(ref);
+                });
+                installPack = {
+                    ...live,
+                    agentId,
+                    sources: [...otherSources, ...(loadedPack.sources ?? [])],
+                };
+            }
+            else {
+                const svcId = id;
+                const otherServices = (live.services ?? []).filter((s) => !(s && typeof s === "object" && "id" in s && String(s.id) === svcId));
+                installPack = {
+                    ...live,
+                    agentId,
+                    services: [...otherServices, ...(loadedPack.services ?? [])],
+                };
+            }
+        }
+        installPack = stripOrgRuntimeSourcesFromPack(installPack);
+        const validation = validateMetadataPack(installPack);
+        if (!validation.ok) {
+            throw new ServiceError("VALIDATION", "pack at version failed validation", 400, { issues: validation.issues });
+        }
+        const message = body.message?.trim() ||
+            `Restore ${kind}:${id} @ ${version.slice(0, 12)} into org ${scope.orgId}`;
+        const result = platform.metadata.install(installPack, {
+            reinstall: true,
+            magitCommit: version,
+            magitRelease: undefined,
+            source: "rollback",
+            message,
+            environment: "live",
+        });
+        if (!result.ok) {
+            throw new ServiceError("VALIDATION", result.issues.map((i) => i.message).join("; ") || "restore install failed", 400);
+        }
+        return {
+            restored: true,
+            kind,
+            id,
+            agentId,
+            version,
+            checksum: fetched.checksum,
+            targetOrgId: scope.orgId,
+            result,
+            note: "Installed from the shared package catalog into this organization. Organization is the install target only.",
+        };
+    });
+    app.post("/api/metadata/packages/diff", async (req) => {
+        const magit = requireMagit(platform);
+        const body = req.body;
+        const kind = parseKind(body.kind);
+        const id = body.id?.trim();
+        if (!id)
+            throw new ServiceError("VALIDATION", "id required", 400);
+        const from = body.from?.trim();
+        const to = body.to?.trim();
+        if (!from || !to) {
+            throw new ServiceError("VALIDATION", "from and to required", 400);
+        }
+        const packs = installedPacks();
+        let agentId;
+        try {
+            agentId = resolveOwnerAgent(packs, kind, id, body.agentId);
+        }
+        catch {
+            agentId = kind === "agent" ? id : body.agentId?.trim() || id;
+        }
+        const sliceAgentId = catalogAgentId(kind, id, agentId);
+        // "installed" sentinel → live / installed pack slice for typed-store compare.
+        // Flat Mode B still maps installed → "live" commit/mongo side via MagitPackService.
+        const fromRef = from === "installed" ? "live" : from;
+        const toRef = to === "installed" ? "live" : to;
+        const needsInstalled = fromRef === "live" ||
+            toRef === "live" ||
+            from === "installed" ||
+            to === "installed";
+        let installedPack = null;
+        if (needsInstalled) {
+            const live = packs[agentId];
+            if (live) {
+                installedPack = buildPackagePayload(live, {
+                    kind,
+                    id,
+                    mode: kind === "agent" ? "narrow" : undefined,
+                });
+            }
+        }
+        const diff = await magit.diffPackages(sliceAgentId, {
+            from: fromRef,
+            to: toRef,
+            kind,
+            id,
+            installedPack,
+        });
+        return {
+            ...diff,
+            kind,
+            id,
+            agentId,
+            catalogAgentId: sliceAgentId,
+            note: "Compare package versions or version vs installed. Not env→env copy.",
+        };
+    });
 }
 function emptyPackForRestore(agentId) {
     return {