@x12i/memorix-service 3.2.1 → 3.4.0

package/dist/routes/metadata.js

@@ -1,9 +1,14 @@
 import { METADATA_KIND_IDS, METADATA_KIND_REGISTRY, validateMetadataPack, } from "@x12i/memorix-metadata";
 import { resolveScope } from "../request-scope.js";
+import { resolveEffectiveForListing } from "../effective-listing.js";
 import { ServiceError } from "../errors.js";
 import { listKnownPackIds, loadKnownMetadataPack } from "../known-packs.js";
 import { stripOrgRuntimeSourcesFromPack } from "../org-sources.js";
-import { PACKAGE_CATALOG_ORG, associationsFromPack, buildPackagePayload, catalogAgentId, discoverPackageCatalog, packageVersionMessage, parsePackageMessage, releaseAssociations, resolveOwnerAgent, } from "../magit/package-catalog-bridge.js";
+import { associationsFromPack, buildPackagePayload, catalogAgentId, discoverPackageCatalog, releaseAssociations, resolveOwnerAgent, } from "../magit/package-catalog-bridge.js";
+import { packagePayloadToPack } from "../magit/pack-to-patchset.js";
+import { createCatalogService } from "../catalog/catalog-service.js";
+import { collapseCatalogVersions, parsePackagesSource, selectPackagesBySource, } from "../catalog/package-list-source.js";
+import { isMagitCatalogKind } from "../catalog/types.js";
 function requireMagit(platform) {
     if (!platform.magit) {
         throw new ServiceError("MAGIT_UNAVAILABLE", "metadata versioning requires a durable Mongo connection (set METADATA_MAGIT=0 to disable)", 503);
@@ -144,7 +149,7 @@ export async function registerMetadataRoutes(app, platform) {
     });
     app.get("/api/metadata/effective", async (req) => {
         const scope = resolveScope(req);
-        const resolved = platform.metadata.resolveEffective(scope.agentIds);
+        const resolved = resolveEffectiveForListing((ids) => platform.metadata.resolveEffective(ids), scope.agentIds);
         return {
             scope,
             ok: resolved.ok,
@@ -156,12 +161,12 @@ export async function registerMetadataRoutes(app, platform) {
                 issues: resolved.issues ?? [],
                 referenceIssues: resolved.referenceIssues ?? [],
             },
-            note: "agentIds select effective metadata only; effective is the resolved definition array",
+            note: "agentIds select effective metadata only; Any/* fans out and unions when multi-agent joint resolve conflicts",
         };
     });
     app.get("/api/metadata/kinds", async (req) => {
         const scope = resolveScope(req);
-        const effective = platform.metadata.resolveEffective(scope.agentIds);
+        const effective = resolveEffectiveForListing((ids) => platform.metadata.resolveEffective(ids), scope.agentIds);
         const customDeclarations = (effective.effective ?? []).filter((e) => e.kind === "kind-declarations");
         return {
             scope,
@@ -184,7 +189,7 @@ export async function registerMetadataRoutes(app, platform) {
     app.get("/api/metadata/kinds/:kind", async (req) => {
         const scope = resolveScope(req);
         const { kind } = req.params;
-        const effective = platform.metadata.resolveEffective(scope.agentIds);
+        const effective = resolveEffectiveForListing((ids) => platform.metadata.resolveEffective(ids), scope.agentIds);
         const items = (effective.effective ?? []).filter((e) => e.kind === kind);
         return { scope, kind, items };
     });
@@ -596,8 +601,8 @@ export async function registerMetadataRoutes(app, platform) {
         return { scope, definition: def };
     });
     // ---------------------------------------------------------------------------
-    // Package catalog (Magit 2.9+ packages/ — Pack / list / fetch; Restore → install)
-    // Spec: .operational/magit-central-package-storage-FR.md
+    // Central package catalog (org-free Pack/List/Fetch; org required
+    // only on Restore as the install target)
     // ---------------------------------------------------------------------------
     function installedPacks() {
         return platform.metadata.exportMetadata().packs;
@@ -608,95 +613,52 @@ export async function registerMetadataRoutes(app, platform) {
             return k;
         throw new ServiceError("VALIDATION", "kind must be agent | connector | service", 400);
     }
-    /** Optional Magit actor from request headers (audit; not ownership ACL until Magit G1). */
-    function actorFromRequest(req) {
-        const h = req.headers;
-        const pick = (name) => {
-            const v = h[name] ?? h[name.toLowerCase()];
-            if (Array.isArray(v))
-                return v[0]?.trim() || undefined;
-            return typeof v === "string" && v.trim() ? v.trim() : undefined;
-        };
-        const subject = pick("x-memorix-actor") ??
-            pick("x-actor-id") ??
-            pick("x-authix-subject");
-        return subject ? { subject } : undefined;
-    }
-    /**
-     * Magit published catalog and/or packable live installs.
-     * Query: source=catalog|packable|all (default all); optional kind filter.
-     * packages = Magit published (distinct kind+id, latest version row as summary).
-     * packable = installed live (for Publish-from-this-env).
-     * No publisher "ours only" filter until Magit G1–G3 ship.
-     */
+    // Local packable by default. source=catalog proxies Magit inventory collapse;
+    // source=all returns both planes. Global product inventory is GET /api/catalog.
     app.get("/api/metadata/packages", async (req) => {
         const magit = requireMagit(platform);
         const q = req.query;
         const kindFilter = q.kind?.trim() && q.kind.trim() !== "all"
             ? parseKind(q.kind)
             : undefined;
-        const sourceRaw = (q.source?.trim() || "all").toLowerCase();
-        const source = sourceRaw === "catalog" || sourceRaw === "packable" || sourceRaw === "all"
-            ? sourceRaw
-            : (() => {
-                throw new ServiceError("VALIDATION", "source must be catalog | packable | all", 400);
-            })();
-        const wantCatalog = source === "catalog" || source === "all";
-        const wantPackable = source === "packable" || source === "all";
-        let packages = [];
-        let remote = magit.hasRemoteCatalog();
-        if (wantCatalog) {
-            const listed = await magit.listCatalogPackages({
+        const source = parsePackagesSource(q.source);
+        const packable = discoverPackageCatalog(installedPacks()).filter((e) => kindFilter ? e.kind === kindFilter : true);
+        let catalogRows = [];
+        if (source === "catalog" || source === "all") {
+            const catalog = createCatalogService({
+                magit,
+                metadata: platform.metadata,
+                connectorRegistry: platform.connectorRegistry,
+                genericConnectors: platform.genericConnectors,
+            });
+            const versions = await catalog.listMagitVersionRows({
                 kind: kindFilter,
-                maxCount: 500,
             });
-            remote = listed.remote || remote;
-            // Collapse versions → one catalog entry per kind+id (latest createdAt wins).
-            const byKey = new Map();
-            for (const v of listed.items) {
-                if (kindFilter && v.kind !== kindFilter)
-                    continue;
-                const key = `${v.kind}::${v.id}`;
-                const prev = byKey.get(key);
-                if (prev?.createdAt && prev.createdAt >= v.createdAt)
-                    continue;
-                byKey.set(key, {
-                    kind: v.kind,
-                    id: v.id,
-                    // Owner agent is live concern; catalog packages are org-free.
-                    agentId: v.kind === "agent" ? v.id : "",
-                    label: v.kind === "agent"
-                        ? v.id
-                        : `${v.kind}:${v.id}${v.version ? ` @ ${v.version.slice(0, 12)}` : ""}`,
-                    version: v.version,
-                    checksum: v.checksum,
-                    createdAt: v.createdAt,
-                    mode: v.mode,
-                    associations: v.associations,
-                });
-            }
-            packages = [...byKey.values()].sort((a, b) => a.kind.localeCompare(b.kind) || a.id.localeCompare(b.id));
-        }
-        const packable = wantPackable
-            ? discoverPackageCatalog(installedPacks()).filter((e) => kindFilter ? e.kind === kindFilter : true)
-            : [];
-        // Backward-compat: when clients only read `packages`, prefer catalog when requested.
-        // For source=packable only, packages[] mirrors packable so older clients still work.
-        if (source === "packable") {
-            packages = packable.map((e) => ({
-                kind: e.kind,
-                id: e.id,
-                agentId: e.agentId,
-                label: e.label,
+            catalogRows = versions
+                .filter((v) => isMagitCatalogKind(v.kind))
+                .map((v) => ({
+                kind: v.kind,
+                id: v.id,
+                version: v.version,
+                createdAt: v.createdAt,
+                checksum: v.checksum,
             }));
         }
-        return {
-            packages,
+        const selected = selectPackagesBySource({
+            source,
+            packages: collapseCatalogVersions(catalogRows),
             packable,
+        });
+        const note = source === "packable"
+            ? "Package identities discoverable from packs installed in this environment."
+            : source === "catalog"
+                ? "Collapsed Magit catalog identities (latest version per kind+id). Prefer GET /api/catalog for product inventory."
+                : "packages=Magit catalog (collapsed); packable=installed pack identities.";
+        return {
+            packages: selected.packages,
+            ...(source === "all" ? { packable: selected.packable } : {}),
             source,
-            remote,
-            catalogOrg: PACKAGE_CATALOG_ORG,
-            note: "packages = Magit published catalog; packable = live installs for Publish. Publisher-scoped catalog awaits Magit G1–G3 (.operational/magit-package-ownership-catalog-FR.md).",
+            note,
         };
     });
     app.get("/api/metadata/packages/:kind/:id/associations", async (req) => {
@@ -719,6 +681,8 @@ export async function registerMetadataRoutes(app, platform) {
             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);
@@ -726,44 +690,42 @@ export async function registerMetadataRoutes(app, platform) {
         if (!id)
             throw new ServiceError("VALIDATION", "id required", 400);
         const q = req.query;
-        const packs = installedPacks();
-        let ownerAgentId;
-        try {
-            ownerAgentId = resolveOwnerAgent(packs, kind, id, q.agentId);
-        }
-        catch {
-            ownerAgentId = kind === "agent" ? id : q.agentId?.trim() || "";
-        }
         const maxCount = q.maxCount ? Number(q.maxCount) : 50;
-        const listed = await magit.listCatalogPackages({
+        const versions = await magit.listPackages({
             kind,
             id,
             maxCount: Number.isFinite(maxCount) ? maxCount : 50,
         });
-        const versions = listed.items.map((v) => {
-            const parsed = parsePackageMessage(v.message);
-            return {
-                commit: v.version,
-                agentId: ownerAgentId || id,
-                checksum: v.checksum,
-                message: v.message,
-                createdAt: v.createdAt,
-                source: "save-version",
-                packageKind: (parsed.kind ?? v.kind),
-                packageId: parsed.id ?? v.id,
-                mode: parsed.mode ?? v.mode,
-                displayMessage: parsed.message || v.message,
-                associations: v.associations,
-            };
-        });
         return {
             kind,
             id,
-            agentId: ownerAgentId || id,
-            versions,
-            remote: listed.remote || magit.hasRemoteCatalog(),
-            catalogOrg: PACKAGE_CATALOG_ORG,
-            note: "Versions from Magit package catalog (packages/). Org is not package identity.",
+            // `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) => {
@@ -788,11 +750,7 @@ export async function registerMetadataRoutes(app, platform) {
         if (!live) {
             throw new ServiceError("NOT_FOUND", `No installed pack for agent ${agentId}`, 404);
         }
-        const mode = kind === "agent"
-            ? body.mode === "narrow"
-                ? "narrow"
-                : "full"
-            : "narrow";
+        const mode = kind === "agent" ? (body.mode === "narrow" ? "narrow" : "full") : undefined;
         const payload = buildPackagePayload(live, {
             kind,
             id,
@@ -807,74 +765,51 @@ export async function registerMetadataRoutes(app, platform) {
         const associations = kind === "agent" && mode
             ? releaseAssociations(live, mode, body.includeConnectorIds, body.includeServiceIds)
             : undefined;
-        // Full agent pack: publish pin packages first, then agent with Magit pins.
-        const actor = actorFromRequest(req);
-        const pins = [];
+        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 slice = buildPackagePayload(live, { kind: "connector", id: connectorId });
                 const ok = validateMetadataPack(slice);
                 if (!ok.ok)
                     continue;
-                const b = await magit.packCatalogPackage({
+                const b = await magit.packPackage({
                     kind: "connector",
                     id: connectorId,
-                    message: packageVersionMessage("connector", connectorId, `bundled with agent ${id}: ${message}`),
+                    message: `bundled with agent ${id}: ${message}`,
                     pack: slice,
-                    mode: "narrow",
-                    actor,
-                });
-                pins.push({
-                    kind: "connector",
-                    id: connectorId,
-                    version: b.version,
-                });
-                bundled.push({
-                    kind: "connector",
-                    id: connectorId,
-                    commit: b.version,
-                    version: b.version,
                 });
+                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 slice = buildPackagePayload(live, { kind: "service", id: serviceId });
                 const ok = validateMetadataPack(slice);
                 if (!ok.ok)
                     continue;
-                const b = await magit.packCatalogPackage({
+                const b = await magit.packPackage({
                     kind: "service",
                     id: serviceId,
-                    message: packageVersionMessage("service", serviceId, `bundled with agent ${id}: ${message}`),
+                    message: `bundled with agent ${id}: ${message}`,
                     pack: slice,
-                    mode: "narrow",
-                    actor,
-                });
-                pins.push({ kind: "service", id: serviceId, version: b.version });
-                bundled.push({
-                    kind: "service",
-                    id: serviceId,
-                    commit: b.version,
-                    version: b.version,
                 });
+                bundled.push({ kind: "service", id: serviceId, version: b.version, commit: b.version });
             }
         }
-        const saved = await magit.packCatalogPackage({
-            kind,
-            id,
-            message: packageVersionMessage(kind, id, message, mode),
-            pack: payload,
-            mode: kind === "agent" ? mode : "narrow",
-            associations,
-            pins: pins.length ? pins : undefined,
-            actor,
-        });
+        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,
@@ -883,13 +818,13 @@ export async function registerMetadataRoutes(app, platform) {
             mode: mode ?? null,
             associations,
             bundled,
-            commit: saved.version,
             version: saved.version,
             checksum: saved.checksum,
             reused: saved.reused,
-            remote: saved.remote || magit.hasRemoteCatalog(),
-            catalogOrg: PACKAGE_CATALOG_ORG,
-            note: "Packed into Magit package catalog (not live).",
+            ...(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) => {
@@ -921,13 +856,14 @@ export async function registerMetadataRoutes(app, platform) {
             throw new ServiceError("VALIDATION", "agentId required to restore connector/service into an agent pack", 400);
         }
         const sliceAgentId = catalogAgentId(kind, id, agentId);
-        const loaded = await magit.fetchCatalogPackage({ kind, id, version }, sliceAgentId);
-        let installPack = loaded.pack;
+        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((loaded.pack.sources ?? [])
+                const keepRefs = new Set((loadedPack.sources ?? [])
                     .map((s) => s && typeof s === "object" && "connectorRef" in s
                     ? String(s.connectorRef ?? "")
                     : "")
@@ -941,19 +877,16 @@ export async function registerMetadataRoutes(app, platform) {
                 installPack = {
                     ...live,
                     agentId,
-                    sources: [...otherSources, ...(loaded.pack.sources ?? [])],
+                    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));
+                const otherServices = (live.services ?? []).filter((s) => !(s && typeof s === "object" && "id" in s && String(s.id) === svcId));
                 installPack = {
                     ...live,
                     agentId,
-                    services: [...otherServices, ...(loaded.pack.services ?? [])],
+                    services: [...otherServices, ...(loadedPack.services ?? [])],
                 };
             }
         }
@@ -981,12 +914,10 @@ export async function registerMetadataRoutes(app, platform) {
             id,
             agentId,
             version,
+            checksum: fetched.checksum,
             targetOrgId: scope.orgId,
-            checksum: loaded.checksum,
             result,
-            remote: loaded.remote || magit.hasRemoteCatalog(),
-            catalogOrg: PACKAGE_CATALOG_ORG,
-            note: "Restored from Magit package catalog into this environment. Org is restore target only.",
+            note: "Installed from the shared package catalog into this organization. Organization is the install target only.",
         };
     });
     app.post("/api/metadata/packages/diff", async (req) => {
@@ -1010,12 +941,31 @@ export async function registerMetadataRoutes(app, platform) {
             agentId = kind === "agent" ? id : body.agentId?.trim() || id;
         }
         const sliceAgentId = catalogAgentId(kind, id, agentId);
-        // version↔version: Magit catalog commits; installed vs version uses catalog org Mongo lens.
+        // "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 diff = await magit.diff(PACKAGE_CATALOG_ORG, sliceAgentId, {
+        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,
@@ -1023,10 +973,333 @@ export async function registerMetadataRoutes(app, platform) {
             id,
             agentId,
             catalogAgentId: sliceAgentId,
-            remote: magit.hasRemoteCatalog(),
             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 result = await magit.setReleaseChannel({
+            channel,
+            releaseId,
+            message: body.message?.trim() || undefined,
+            expectedReleaseId: body.expectedReleaseId,
+        });
+        return {
+            ...result,
+            note: "Release channel updated in one write (atomic set promote). Does not install into organizations.",
+        };
+    });
+    app.get("/api/metadata/packages/releases/channels", async () => {
+        const magit = requireMagit(platform);
+        const channels = await magit.listReleaseChannels();
+        return {
+            channels,
+            note: "Release channel heads with member sets.",
+        };
+    });
+    app.get("/api/metadata/packages/releases/channels/:channel", async (req) => {
+        const magit = requireMagit(platform);
+        const channel = String(req.params.channel ?? "").trim();
+        if (!channel)
+            throw new ServiceError("VALIDATION", "channel required", 400);
+        const result = await magit.resolveReleaseChannel({ channel });
+        return {
+            ...result,
+            note: "Resolved release channel with full member set (Magit syncs first).",
+        };
+    });
+    app.get("/api/metadata/packages/releases/channels/:channel/history", async (req) => {
+        const magit = requireMagit(platform);
+        const channel = String(req.params.channel ?? "").trim();
+        if (!channel)
+            throw new ServiceError("VALIDATION", "channel required", 400);
+        const history = await magit.releaseChannelHistory({ channel });
+        return {
+            channel,
+            history,
+            note: "Rollback list: promote a previous releaseId to move the channel back.",
+        };
+    });
+    /**
+     * Atomic install of a release set into the target org.
+     * Body: { confirm:true, channel? | releaseId?, message? }
+     * Installs members with agent-first ordering; rolls back prior installs on failure.
+     */
+    app.post("/api/metadata/packages/releases/install", 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 release install", 400);
+        }
+        if (!scope.orgId?.trim()) {
+            throw new ServiceError("VALIDATION", "x-memorix-org-id required — organization is the install target", 400);
+        }
+        let members;
+        let releaseId;
+        let channel = null;
+        if (body.channel?.trim()) {
+            channel = body.channel.trim();
+            const live = await magit.resolveReleaseChannel({ channel });
+            releaseId = live.releaseId;
+            members = live.release.members;
+        }
+        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);
+            }
+        }
+        else {
+            throw new ServiceError("VALIDATION", "channel or releaseId required", 400);
+        }
+        if (members.length === 0) {
+            throw new ServiceError("VALIDATION", "release has no members", 400);
+        }
+        // Install agent members first so connector/service merges have a host pack.
+        const ordered = [...members].sort((a, b) => {
+            const rank = (k) => k === "agent" ? 0 : k === "connector" ? 1 : 2;
+            return rank(a.kind) - rank(b.kind);
+        });
+        const priors = [];
+        const installed = [];
+        const packs = installedPacks();
+        try {
+            for (const m of ordered) {
+                const kind = parseKind(m.kind);
+                const key = `${kind}:${m.id}`;
+                let agentId = body.agentIdByMember?.[key]?.trim() ||
+                    (kind === "agent" ? m.id : "");
+                if (!agentId) {
+                    try {
+                        agentId = resolveOwnerAgent(packs, kind, m.id, undefined);
+                    }
+                    catch {
+                        agentId = kind === "agent" ? m.id : "";
+                    }
+                }
+                if (!agentId) {
+                    throw new ServiceError("VALIDATION", `agentId required to install ${kind}/${m.id}`, 400);
+                }
+                const priorPack = packs[agentId]
+                    ? structuredClone(packs[agentId])
+                    : null;
+                priors.push({ agentId, pack: priorPack });
+                const sliceAgentId = catalogAgentId(kind, m.id, agentId);
+                const fetched = await magit.fetchPackage({
+                    kind,
+                    id: m.id,
+                    version: m.version,
+                });
+                let installPack = packagePayloadToPack(sliceAgentId, fetched.payload);
+                if (kind === "connector" || kind === "service") {
+                    const live = packs[agentId] ?? emptyPackForRestore(agentId);
+                    if (kind === "connector") {
+                        const keepRefs = new Set((installPack.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, ...(installPack.sources ?? [])],
+                        };
+                    }
+                    else {
+                        const svcId = m.id;
+                        const otherServices = (live.services ?? []).filter((s) => !(s &&
+                            typeof s === "object" &&
+                            "id" in s &&
+                            String(s.id) === svcId));
+                        installPack = {
+                            ...live,
+                            agentId,
+                            services: [...otherServices, ...(installPack.services ?? [])],
+                        };
+                    }
+                }
+                installPack = stripOrgRuntimeSourcesFromPack(installPack);
+                const validation = validateMetadataPack(installPack);
+                if (!validation.ok) {
+                    throw new ServiceError("VALIDATION", `release member ${kind}/${m.id} failed validation`, 400, { issues: validation.issues });
+                }
+                const message = body.message?.trim() ||
+                    `Install release ${releaseId.slice(0, 12)} member ${kind}/${m.id}`;
+                const result = platform.metadata.install(installPack, {
+                    reinstall: true,
+                    magitCommit: m.version,
+                    magitRelease: releaseId,
+                    source: "rollback",
+                    message,
+                    environment: "live",
+                });
+                if (!result.ok) {
+                    throw new ServiceError("VALIDATION", result.issues.map((i) => i.message).join("; ") ||
+                        `install failed for ${kind}/${m.id}`, 400);
+                }
+                installed.push({ kind, id: m.id, version: m.version, agentId });
+            }
+        }
+        catch (err) {
+            // Best-effort rollback to prior packs for successfully installed members.
+            for (let i = priors.length - 1; i >= 0; i--) {
+                const prior = priors[i];
+                if (prior.pack) {
+                    try {
+                        platform.metadata.install(prior.pack, {
+                            reinstall: true,
+                            source: "rollback",
+                            message: `Rollback after failed release install ${releaseId.slice(0, 12)}`,
+                            environment: "live",
+                        });
+                    }
+                    catch {
+                        // keep original error
+                    }
+                }
+            }
+            throw err;
+        }
+        return {
+            installed: true,
+            releaseId,
+            channel,
+            targetOrgId: scope.orgId,
+            members: installed,
+            note: "Atomic release install into the target organization. On failure, prior packs are restored.",
+        };
+    });
 }
 function emptyPackForRestore(agentId) {
     return {