feat(catalog-v2): keep license links version-anchored and follow per child sibling

Parent plan_licenses stay on the child version they point at. Child all_versions follow applies each parent's overlay from that sibling's diff, and the dashboard can select those versions (including by slug).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: johnyeocx

server/src/internal/catalogV2/actions/buildPlanChange/buildPlanLicenseChanges/buildPlanLicensePreviousAttributes.ts

@@ -18,5 +18,8 @@ export const buildPlanLicensePreviousAttributes = ({
 	if (from.product.version !== to.product.version) {
 		previous.version = from.product.version;
 	}
+	if (from.product.version_slug !== to.product.version_slug) {
+		previous.version_slug = from.product.version_slug ?? undefined;
+	}
 	return Object.keys(previous).length > 0 ? previous : null;
 };

server/src/internal/catalogV2/actions/updateCatalog/compute/computeMigrationDraftPlans/resolveLicenseMigrationTarget/propagateLicenseDraftUpserts.ts

@@ -9,7 +9,11 @@ import {
 	licenseUpsertFromPlanLicense,
 	sortLicenseDraftUpserts,
 } from "@/internal/catalogV2/actions/updateCatalog/compute/computeMigrationDraftPlans/resolveLicenseMigrationTarget/licenseUpsertFromPlanLicense";
-import { shouldPropagate } from "@/internal/catalogV2/actions/updateCatalog/compute/computeUpsertProductsPlan/computePlanLicensesPlan/licensePlanUtils";
+import {
+	parentLicenseLinkForChild,
+	propagateReachesLink,
+	shouldPropagate,
+} from "@/internal/catalogV2/actions/updateCatalog/compute/computeUpsertProductsPlan/computePlanLicensesPlan/licensePlanUtils";
 import type { ProductStatesContext } from "@/internal/catalogV2/actions/updateCatalog/types/updateCatalogContext";
 import type { UpsertProductPlan } from "@/internal/catalogV2/actions/updateCatalog/types/upsertProductPlan";
 
@@ -45,6 +49,10 @@ export const propagateLicenseDraftUpserts = ({
 			continue;
 		}
 
+		const currentPlanLicense = parentLicenseLinkForChild({ parent, child });
+		if (!currentPlanLicense) continue;
+		if (!propagateReachesLink({ currentPlanLicense, child })) continue;
+
 		const planLicense = parent.planLicenses?.find(
 			(link) => link.licensePlanId === child.row.planId,
 		);

server/src/internal/catalogV2/actions/updateCatalog/compute/computeUpsertProductsPlan/assembleNextFullProduct.ts

@@ -32,5 +32,6 @@ export const assembleNextFullProduct = ({
 		entitlements,
 		free_trial: freeTrial,
 		licenses: currentFullProduct?.licenses,
+		parent_plan_licenses: currentFullProduct?.parent_plan_licenses,
 	} as FullProduct;
 };

server/src/internal/catalogV2/actions/updateCatalog/compute/computeUpsertProductsPlan/computePlanLicensesPlan/declared/resolveDeclaredPlanLicenses.ts

@@ -7,6 +7,8 @@ import type {
 import type { ProductStatesContext } from "@/internal/catalogV2/actions/updateCatalog/types/updateCatalogContext";
 import type { PlanLicensePlan } from "@/internal/catalogV2/actions/updateCatalog/types/upsertProductPlan";
 import { activeFullProductForPlan } from "@/internal/catalogV2/actions/updateCatalog/utils/productStateUtils/activeFullProductForPlan";
+import { findFullProductByInternalId } from "@/internal/catalogV2/actions/updateCatalog/utils/productStateUtils/findFullProductByInternalId";
+import { fullProductForSlug } from "@/internal/catalogV2/actions/updateCatalog/utils/productStateUtils/fullProductForSlug";
 
 const declaredLinkChanged = ({
 	currentPlanLicense,
@@ -38,6 +40,39 @@ const declaredLinkChanged = ({
 	return false;
 };
 
+/** Stated slug = that row. Omitted keeps the existing child id; new links use active. */
+const anchorFullProductForDeclared = ({
+	params,
+	currentPlanLicense,
+	productStatesContext,
+}: {
+	params: PlanLicenseParams;
+	currentPlanLicense: FullPlanLicense | null;
+	productStatesContext: ProductStatesContext;
+}): FullProduct | null => {
+	if (params.version_slug !== undefined) {
+		return fullProductForSlug({
+			planId: params.license_plan_id,
+			versionSlug: params.version_slug,
+			productStatesContext,
+		});
+	}
+
+	if (currentPlanLicense) {
+		return (
+			findFullProductByInternalId({
+				internalId: currentPlanLicense.license_internal_product_id,
+				productStatesContext,
+			}) ?? currentPlanLicense.product
+		);
+	}
+
+	return activeFullProductForPlan({
+		planId: params.license_plan_id,
+		productStatesContext,
+	});
+};
+
 /** Declared licenses[] vs current links → per-link write ops. */
 export const resolveDeclaredPlanLicenses = ({
 	declared,
@@ -58,12 +93,13 @@ export const resolveDeclaredPlanLicenses = ({
 	const declaredIds = new Set(declared.map((entry) => entry.license_plan_id));
 
 	const planned: PlanLicensePlan[] = declared.map((params) => {
-		const licenseProduct = activeFullProductForPlan({
-			planId: params.license_plan_id,
-			productStatesContext,
-		});
 		const currentPlanLicense =
 			currentPlanLicenseByPlanId.get(params.license_plan_id) ?? null;
+		const licenseProduct = anchorFullProductForDeclared({
+			params,
+			currentPlanLicense,
+			productStatesContext,
+		});
 
 		const op = !currentPlanLicense
 			? "create"
@@ -87,6 +123,7 @@ export const resolveDeclaredPlanLicenses = ({
 			prepaidOnly: params.prepaid_only ?? true,
 			metadata: params.metadata,
 			customize: params.customize,
+			declaredVersionSlug: params.version_slug,
 		};
 	});
 

server/src/internal/catalogV2/actions/updateCatalog/compute/computeUpsertProductsPlan/computePlanLicensesPlan/licensePlanUtils.ts

@@ -1,6 +1,7 @@
 import {
 	type CatalogPropagateTargetParams,
 	type FullPlanLicense,
+	type FullProduct,
 	type LicenseCustomize,
 	productKeyToString,
 	productToProductKey,
@@ -9,6 +10,7 @@ import type { ProductStatesContext } from "@/internal/catalogV2/actions/updateCa
 import type { UpsertProductPlan } from "@/internal/catalogV2/actions/updateCatalog/types/upsertProductPlan";
 import { activeVersionForPlan } from "@/internal/catalogV2/actions/updateCatalog/utils/productStateUtils/activeVersionForPlan";
 import { findFullProductByInternalId } from "@/internal/catalogV2/actions/updateCatalog/utils/productStateUtils/findFullProductByInternalId";
+import { versionForSlug } from "@/internal/catalogV2/actions/updateCatalog/utils/productStateUtils/versionForSlug";
 
 /** Current plan_license links on this row. Minted versions fall back to the clone source. */
 export const upsertProductPlanToLicenses = ({
@@ -35,35 +37,81 @@ const childSourceInternalIds = ({
 	),
 ];
 
-/** Incoming links on the upserted child plus the demoted pointer (promote). */
+const uniqueReverseLinks = ({
+	products,
+}: {
+	products: Array<FullProduct | null | undefined>;
+}) => {
+	const seen = new Set<string>();
+	return products.flatMap((product) => {
+		if (!product) return [];
+		return (product.parent_plan_licenses ?? []).filter((link) => {
+			const key = productKeyToString({
+				productKey: productToProductKey({ product: link.product }),
+			});
+			if (seen.has(key)) return false;
+			seen.add(key);
+			return true;
+		});
+	});
+};
+
+/** Incoming links on every live version row of this child plan. */
+export const reverseLinksOnChildPlan = ({
+	planId,
+	productStatesContext,
+}: {
+	planId: string;
+	productStatesContext: ProductStatesContext;
+}) =>
+	uniqueReverseLinks({
+		products: productStatesContext.versionsByPlanId[planId] ?? [],
+	});
+
+/** Incoming links on one child version row. */
+export const reverseLinksOnChildProduct = ({
+	planId,
+	childInternalId,
+	productStatesContext,
+}: {
+	planId: string;
+	childInternalId: string;
+	productStatesContext: ProductStatesContext;
+}) => {
+	const childRow = (productStatesContext.versionsByPlanId[planId] ?? []).find(
+		(row) => row.internal_id === childInternalId,
+	);
+	return uniqueReverseLinks({ products: [childRow] });
+};
+
+/** Incoming links on the planned child row, plus the demoted pointer (promote). */
 export const reverseLinksForChild = ({
 	upsert,
 	productStatesContext,
 }: {
 	upsert: UpsertProductPlan;
 	productStatesContext: ProductStatesContext;
 }) => {
+	const plannedInternalId =
+		upsert.row.currentFullProduct?.internal_id ??
+		upsert.row.baseFullProduct?.internal_id ??
+		upsert.row.nextFullProduct.internal_id;
+	const hydrated = (
+		productStatesContext.versionsByPlanId[upsert.row.planId] ?? []
+	).find((row) => row.internal_id === plannedInternalId);
 	const previousActive = upsert.previousActiveInternalId
 		? findFullProductByInternalId({
 				internalId: upsert.previousActiveInternalId,
 				productStatesContext,
 			})
 		: null;
-	const seen = new Set<string>();
-	return [
-		upsert.row.currentFullProduct,
-		upsert.row.baseFullProduct,
-		previousActive,
-	].flatMap((product) => {
-		if (!product) return [];
-		return (product.parent_plan_licenses ?? []).filter((link) => {
-			const key = productKeyToString({
-				productKey: productToProductKey({ product: link.product }),
-			});
-			if (seen.has(key)) return false;
-			seen.add(key);
-			return true;
-		});
+	return uniqueReverseLinks({
+		products: [
+			hydrated,
+			upsert.row.currentFullProduct,
+			upsert.row.baseFullProduct,
+			previousActive,
+		],
 	});
 };
 
@@ -74,8 +122,14 @@ export const parentLicenseLinkForChild = ({
 	parent: UpsertProductPlan;
 	child: UpsertProductPlan;
 }): FullPlanLicense | undefined => {
+	const licenses = upsertProductPlanToLicenses({ upsert: parent });
+	// Adopt mint clones the old row's link; pair by child plan so follow can
+	// re-anchor onto the child's active row in this batch.
+	if (parent.row.source === "license_adopt") {
+		return licenses.find((link) => link.product.id === child.row.planId);
+	}
 	const sourceInternalIds = childSourceInternalIds({ child });
-	return upsertProductPlanToLicenses({ upsert: parent }).find(
+	return licenses.find(
 		(link) =>
 			link.product.id === child.row.planId &&
 			(sourceInternalIds.length === 0 ||
@@ -110,17 +164,25 @@ const propagateTargetMatchesParent = ({
 	target,
 	parent,
 	activeVersion,
+	productStatesContext,
 }: {
 	target: CatalogPropagateTargetParams;
 	parent: UpsertProductPlan;
 	activeVersion: number | undefined;
+	productStatesContext: ProductStatesContext;
 }): boolean => {
 	if (target.plan_id !== parent.row.planId) return false;
 	if (target.version !== undefined) return target.version === parent.row.version;
+	if (target.version_slug !== undefined) {
+		const version = versionForSlug({
+			planId: target.plan_id,
+			versionSlug: target.version_slug,
+			productStatesContext,
+		});
+		return version !== undefined && version === parent.row.version;
+	}
 	if (target.versioning === "all_versions") return true;
-	return (
-		activeVersion !== undefined && parent.row.version === activeVersion
-	);
+	return activeVersion !== undefined && parent.row.version === activeVersion;
 };
 
 export const childPropagatesToParent = ({
@@ -137,7 +199,12 @@ export const childPropagatesToParent = ({
 		productStatesContext,
 	});
 	return (child.propagate?.license_parents ?? []).some((target) =>
-		propagateTargetMatchesParent({ target, parent, activeVersion }),
+		propagateTargetMatchesParent({
+			target,
+			parent,
+			activeVersion,
+			productStatesContext,
+		}),
 	);
 };
 
@@ -153,18 +220,36 @@ export const movesActivePointer = ({
 	return nextIsActive && (mintedNewRow || promotedExisting);
 };
 
-/** In-place item writes, or the child taking the pointer. Draft-mint clones do not. */
-export const childTriggersLicenseRewrite = ({
+/** Pin-lane trigger: in-place item writes only. Mints/promotes leave anchored links alone. */
+export const childEditsItemsInPlace = ({
 	child,
 }: {
 	child: UpsertProductPlan;
 }): boolean => {
 	const mintedNewRow = child.row.versioning === "new_version";
 	const childHasItemWrites = child.entitlementPricesPlan != null;
-	const inPlaceItemWrites = childHasItemWrites && !mintedNewRow;
-	return inPlaceItemWrites || movesActivePointer({ upsert: child });
+	return childHasItemWrites && !mintedNewRow;
 };
 
+/** Propagate-lane trigger: in-place item writes, or the child taking the pointer. */
+export const childTriggersLicenseRewrite = ({
+	child,
+}: {
+	child: UpsertProductPlan;
+}): boolean =>
+	childEditsItemsInPlace({ child }) || movesActivePointer({ upsert: child });
+
+/** In-place follow only reaches the row this link already points at. Mint/promote still move it. */
+export const propagateReachesLink = ({
+	currentPlanLicense,
+	child,
+}: {
+	currentPlanLicense: FullPlanLicense;
+	child: UpsertProductPlan;
+}): boolean =>
+	movesActivePointer({ upsert: child }) ||
+	!needsRepoint({ currentPlanLicense, child });
+
 export const shouldPropagate = ({
 	parent,
 	child,